XPath Notebook for Visual Studio Code

XPath Notebook adds XPath 3.1's extensive JSON and XML analysis features to Visual Studio Code's Notebooks.

Notebooks can be used for data-analysis, code experimentation, tutorials or learning.

DeltaXML's XPath Notebook Features

Introduction

DeltaXML's XPath Notebook extension adds comprehensive XPath 3.1 support to Visual Studio Code's built-in notebooks. Visual Studio Code notebooks provide similar features to other popular notebook interfaces like the Juypter Notebook.

A notebook comprises a set of notebooks cells. These cells can either be Markdown cells for narrative content or Code cells for a specific programming language.

When a Code cell is executed, the result is rendered in an Output cell immediately below the current Code cell. The currently active NotebookController (also known as a Kernel) determines the output types that can be shown in the Output cell. Each output type will have a corresponding NotebookRenderer that is responsible for formatting the output type. For example, the result may be shown as JSON text, as an interactive table or an interactive graphical plot.

Getting Started

STEP 1: Setup the XPath Processor

To evaluate XPath expressions, the XPath Notebook requires Node.js to be installed. The Node.js installer is available for download from:

https://nodejs.org/en/.

STEP 2: Create and save a new XPath Notebook

Open the Visual Studio Code command palette (⇧⌘P), and run the New XPath Notebook command. An untitled notebook with a markdown cell and a code cell will be shown, initially the file is untitled with a .xbook file extension.

Save the Notebook file in the usual way (⌘S), keeping the .xbook extension. Note that XPath Notebook output cell values are not saved when the file is saved.

STEP 3: Setup the XPath Source

To set the evaluation context file for a notebook just open an XML or JSON file in Visual Studio Code.

The context-item is the result of evaluating either doc($uri) or json-doc($uri) respectively on the last opened file (excluding notebook files). Here is a summary of the evaluation context:

STEP 4: Add and execute Notebook cells

Press the '+ Code' or '+ Markdown' buttons to add Code or Markdown cells. To execute a cell, press Ctrl-ENTER on the keyboard or click on the 'execute' button alongside the cell. When a Code cell is executed the result is shown in the Output cell immediately below the current cell.

For XPath Notebooks the default Output Cell type is JSON text. This allows XPath maps, arrays and sequences to be represented in an intuitive way.

Step 5: Save the XPath Notebook when done

Use the CMD-S keyboard shortcut to save an XPath Notebook so it can be used again. Currently, the Output cell details are not saved.

General Usage

Result node navigation

If a result item is an XML node the XPath for the node is shown with special syntax highlighting. Result nodes can be navigated easily: first press and hold the CMD button and then click on the XPath in the output cell. The corresponding source XML document will be shown alongside the XPath Notebook, with the corresponding node highlighted.

To view the string values of XML nodes in the output cell you should convert them to a string, for example, using the string() function, for example: /books/book/@author! string()

Sample JSON output cell showing special syntax highlighting for XML nodes

Add NoteBook Context Variables

XPath expressions in code cells can reference the results of other code cells. The $_ variable is always set to the result of the previously executed cell. If you want to assign the result of a cell to a specific XPath variable, use a special XPath Prolog* as the first line.

An XPath Prolog is separated from the XPath expression with the % character as this is not a valid XPath operator. The syntax for the prolog is:

variable = <name> %

In the above, <name> is the name of the variable to which we assign the evaluation result of the following XPath expression.

Note: The intension is to use the XPath Prolog for other features later.

In the example below, the result of the $cities variable declared in cell [4] is used when cell [5] is executed:

Problem Reporting

XPath expressions in Code cells are checked against basic syntax rules. Also, variable names and namespace prefixes are checked using the evaluation context (described above). References to Notebook context variables are marked as invalid until the Code cell with the corresponding variable assignment is executed.

Auto-completion

Auto-completion is available when editing inside Code cells. Auto-completion is triggered for XPath functions and variable names. The variable names list will include Notebook context variables only once the corresponding cells have been evaluated.

Choosing Cell Output Type

Currently XPath Notebooks supports two output types:

Note: RandomFractals Data Table renderer supports large data sets and provides column sort and data-type formatting.

To select an alternative output type, press the (consolidated) output button or the (normal) output button shown to the left of the output cell. Then select the text/html mime-type. (See the note below to see how to control what button is shown).

Note: A Notebook Layout setting (@tag:notebookLayout consolidated output button) control whether you see a 'consolidated' or 'normal' button alongside the Notbook output cell. For this extension, it's more convenient to disable the 'consolidated' button.

Implementation Detail

Evaluation

The XPath Notebook uses the Node.js REPL to execute XPath cells. The Saxon-JS NPM module from Saxonica is pre-installed with the extension.

To evaluate an XPath expression the SaxonJS.transform function invoked via the Node.js REPL. The XSLT used in the transorm is a compiled SEF file, the XPath expression and evaluation context are passed as XSLT parameters.

Additional namespace bindings are added by the XSLT to the context node for 'array', 'map'... prefixes. The XSLT converts the result of an xsl:evaluate intruction to the XML representation for JSON by applying templates to the result. The JSON XML is then converted to JSON using the xml-to-json XPath function.

Prior to evaluation, the XSLT separates any XPath Prolog from the expression. If a variable assignment is found in the prolog, the ixsl:call extension function is used to invoke a setVariable function on a JavaScript object passed as an XSLT parameter via the API.

ixsl:get and ixsl:call extension functions are used on the JavaScript object passed as an XSLT parameter to fetch the set of variables added to the Notexbook context by evaluation of previous Code cells.

XPath Code Editing Features

All XPath code editing features are provided by DeltaXML's companion XSLT/XPath for Visual Studio Code extension - installed automatically with the XPath Notebook extension.

For documentation on XPath editing features, see the extensions documentation at: Editing XSLT/XPath

Commands

XPath Notebook Samples

An Introduction Notebook sample in the code repository at: notebooks/introduction/xpath-notebook.xbook