| ${this.escape(key)} | `)); 32 | tags.push('||
|---|---|---|
| ${this.escape(innerItem)} | `); 39 | }) 40 | } else if (typeof item === 'object') { 41 | // array of objects 42 | Object.values(item).forEach(value => tags.push(`${this.escape(value)} | `)); 43 | } else { 44 | tags.push(`${this.escape(item)} | `); 45 | } 46 | tags.push('
| ${this.escape(key)} | `); 60 | if (Array.isArray(value)) { 61 | value.forEach((innerItem) => { 62 | tags.push(`${this.escape(innerItem)} | `); 63 | }) 64 | } else { 65 | tags.push(`${this.escape(value)} | `); 66 | } 67 | tags.push('
|---|
2 |
3 | # XPath Notebook for Visual Studio Code
4 |
5 | **XPath Notebook** adds XPath 3.1's extensive JSON and XML analysis features to [Visual Studio Code's Notebooks](https://code.visualstudio.com/blogs/2021/11/08/custom-notebooks).
6 |
7 | Notebooks can be used for data-analysis, code experimentation, tutorials or learning.
8 |
9 |
10 | 
11 | # DeltaXignia's XPath Notebook Features
12 |
13 | | Feature | Details |
14 | | ------- | ------- |
15 | | **XPath 3.1 Compatible** | See W3C specifications for [XPath 3.1](https://www.w3.org/TR/xpath-31/#id-introduction)
16 | | **XPath Processing** | Requires [Node.js](https://nodejs.org/en/) to be installed. Uses Saxonica's [Saxon-JS Processor](https://www.saxonica.com/saxon-js/index.xml)
17 | | **JSON or XML sources** | The context for XPath evaluation can be JSON or XML files
18 | | **Syntax Highlighting** | Fast and precise - using [Semantic Highlighting](https://code.visualstudio.com/api/language-extensions/semantic-highlight-guide) exclusively
19 | | **Code Formatting** | For multi-line XPath expressions, 'as-you-type' or 'on-save'
20 | | **Code Diagnostics** | For XPath Syntax, variable/param references, functions, namespace-prefixes etc.
21 | | **Auto-Completion** | For XPath node-names, functions, variables, function-parameters etc.
22 | | **Color Theme Support** | Tested with most popular color themes ([Semantic Highlighting]() must be enabled in settings)
23 | | **Evaluation Context** | Sets context item, namespace context, context variables, last result variable
24 | | **Code Folding** | The indentation of XPath expressions is used to determine fold regions
25 | | **Notebook Context Variables** | An **XPath Prologue** (e.g. ` variable = countries %` ) assigns the cell result to a notebook variable
26 | | **Last Result Variable** | Use `$_` to reference the last evaluated notebook cell result
27 | | **Bracket Matching** | For `()`, `{}`, and `[]`
28 | | **Hover assistance** | Shows tooltips. Providing signatures and descriptions for all built-in XSLT and XPath
29 | | **JSON output** | View Cell output with the JSON syntax (suitable for 3rd-party renderers) - mime-type: `text/x-json`
30 | | **Table output** | View Cell output as a simple table - mime-type: `text/html`
31 | | **XML Node navigation** | Navigates to and highlights XML result nodes in the source document
32 | |||
33 |
34 |
35 | # Introduction
36 |
37 | DeltaXignia'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](https://jupyterlab.readthedocs.io/en/latest/user/notebook.html#notebook).
38 |
39 | 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.
40 |
41 | 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.
42 |
43 | # Getting Started
44 |
45 | ## STEP 1: Setup the XPath Processor
46 |
47 | To evaluate XPath expressions, the XPath Notebook requires **Node.js** to be installed. The Node.js installer is available for download from:
48 |
49 | https://nodejs.org/en/.
50 |
51 | ## STEP 2: Create and save a new XPath Notebook
52 |
53 | 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.
54 |
55 | 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.*
56 |
57 | 
58 |
59 |
60 | ## STEP 3: Setup the XPath Source
61 |
62 | To set the evaluation context file for a notebook just open an XML or JSON file in Visual Studio Code.
63 |
64 | The context-item is the result of evaluating either [`doc($uri)`](https://www.w3.org/TR/xpath-functions-31/#func-doc) or
65 | [`json-doc($uri)`](https://www.w3.org/TR/xpath-functions-31/#func-json-doc) respectively on the last opened file (excluding notebook files). Here is a summary of the evaluation context:
66 |
67 | | Definition | Details |
68 | | ------- | ------- |
69 | | **Context Item** | [`doc($uri)`](https://www.w3.org/TR/xpath-functions-31/#func-doc) or [`json-doc($uri)`](https://www.w3.org/TR/xpath-functions-31/#func-json-doc) evaluated with last editor URI arg
70 | | **Statically known namespaces** | for prefixes: `array`, `map`, `math`, `xs`, `xsl`|
71 | | **Dynamically known namespaces** | from root element of last opened file - if it was XML |
72 | | **Default element namespace** | any default namespace on root element of last opened XML file |
73 | | **In-scope variables** | `$_` for last cell output variables declared in prolog of executed cells 74 | | **Static Base URI** | the URI of the current XPath Notebook file 75 | | **Base URI** | the URI of the last opened file - if it was XML 76 | 77 | --- 78 | ## STEP 4: Add and execute Notebook cells 79 | 80 | 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. 81 | 82 | 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. 83 | 84 | ## Step 5: Save the XPath Notebook when done 85 | 86 | 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. 87 | 88 | # General Usage 89 | 90 | ## Result node navigation 91 | 92 | 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. 93 | 94 | > To view the string values of XML nodes in the output cell 95 | > you should convert them to a string, for example, using the `string()` function, for example: `/books/book/@author! string()` 96 | 97 |  98 | 99 | *Sample JSON output cell showing special syntax highlighting for XML nodes* 100 | 101 | ## Add NoteBook Context Variables 102 | 103 | 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. 104 | 105 | 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: 106 | ```xml 107 | variable =