xpath-notebook.xbook

[{"kind":1,"language":"markdown","value":"# XPath Notebook Introduction\n\nThis XPath Notebook describes [DeltaXML's XPath Notebook extension](https://marketplace.visualstudio.com/items?itemName=deltaxml.xpath-notebook) for Visual Studio Code. \n\nHere we cover the fundamentals of using XPath 3.1 in a [Visual Studio Code Notebook](https://code.visualstudio.com/blogs/2021/11/08/custom-notebooks). \n\n## What can XPath Notebooks be used for? \n\nAn XPath Notebook may be used for a range of purposes, including:\n\n- Data Analysis (of JSON or XML)\n- Experimentation with XPath\n- Tutorials on specific XML/JSON formats or XPath itself\n- Learning XPath\n\n## Evaluation Context\n\nEach XPath code cell executed in a notebook has an **Evaluation Context**:\n\n1. Any XPath expression in a Notebook can reference a *context item*. \n    - The *context item* is the parsed form of the last (valid) XML or JSON file opened in Visual Studio Code \n2. The `$_` variable in the evaluation context holds the result of the last executed cell\n3. XPath Notebook variables like `$myvar` are used to reference results from previously executed cells\n    - An 'XPath Prolog' like `variable=myvar%` for a Code cell stores the XPath result in the variable `myvar`\n6. The **Static Base URI** is set to the Notebook file URI\n7. The dynamic **Base URI** is set to the context file URI - if this is an XML file\n8. XML namespaces from the root element of an XML context file are added to the evaluation context\n9. Common prefix/namespace-uri bindings like `array`, `map` and `xs` are always added to the XPath evaluation context\n"},{"kind":1,"language":"markdown","value":"## Notebook Cells\nEach XPath Notebook comprises a set of **Cells**:"},{"kind":1,"language":"markdown","value":"### Markdown Cell ###\n1. The text rendered here is in a **Markdown cell**\n2. To edit the styled output here as Markdown, double-click on this cell\n3. To exit editing mode, press *⌃Enter*\n4. Headings in Markdown cells affect the **Outline view** tree shown in the **Explorer** Side Bar"},{"kind":1,"language":"markdown","value":"### Code Cell ###\n1. The first **Code cell** in this Notebook contains the XPath expression `'Hello '` || `'World'`\n2. A **Status Bar** is shown at the bottom of each Code cell\n3. The Status Bar item *XPath* identifies the cell's programming language\n4. Clicking on the **XPath** Status Bar item would allow you to switch other language options for the cell\n5. The `[]` label left of the Status Bar shows the execution order of the cell\n6. Select the first Code cell by clicking on it\n7. Press *⌃Enter* to execute the selected Code cell\n8. The 'Execution Order' label now shows: `[1]`\n\n#### Code Cell Status Bar\n1. On success, the Status Bar should show something like: `✔︎ 0.2s`\n2. The name of the *context item* file is shown in the Status Bar\n3. The Status bar shows the number of array or sequence items in a result"},{"kind":1,"language":"markdown","value":"### Output Cell\n1. A new **Output cell**, below the Code cell, now shows the result: `\"Hello World\"`\n2. The default Output cell mimetype is `text/x-json`\n2. Use the `</>` button left of the cell to change the mimetype to `text/html`\n3. The Output cell now shows a 'table' with a single row and column"},{"kind":2,"language":"xpath","value":"'Hello ' || 'World'"},{"kind":1,"language":"markdown","value":"## Cell Output Types\nNotebook cells can support a number of output types, these are identified by a *mimetype*. The XPath Notebook currently supports `text/x-json` and `text/html` output types.\n\nYou can switch the mimetype of an Output cell by clicking on the `</>` button immediately to the left of the cell"},{"kind":1,"language":"markdown","value":"### JSON Output\n1. The default Cell output type is JSON - using the mimetype `text/x-json`\n2. XPath sequences and arrays are represented as JSON arrays\n3. XPath maps are represented as JSON objects with properties corresponding to map keys\n4. XPath nodes are represented as XPath strings with special highlighting\n5. Support for XPath types like `QName` that don't have a JSON equivalent is a **Work in Progress**"},{"kind":1,"language":"markdown","value":"#### Representing XPath Sequences and Arrays\n1. XPath sequences and arrays are both represented as JSON arrays\n2. When executed, the Code cell below results in an XPath sequence. Each sequence item is itself an array\n3. With the result output as JSON, the result is seen as an array of arrays"},{"kind":2,"language":"xpath","value":"['London', 25], \n['New York', 32]"},{"kind":1,"language":"markdown","value":"#### Representing XPath Maps\n1. XPath Maps are represented as JSON objects\n2. Map keys correspond to JSON object property names\n3. When JSON is parsed by XPath, JSON objects are processed as XPath maps\n3. If the Code cell below is executed, the result is a sequence of maps\n4. (In the JSON representation this is shown as an array of objects)"},{"kind":2,"language":"xpath","value":"map { 'City': 'London', 'Temperature': 22 },\nmap { 'City': 'New York', 'Temperature': 32 }"},{"kind":1,"language":"markdown","value":"#### Representing XML Nodes\n1. When XPath is executed the result may be an XML Node such as an Element or Arribute\n2. The result is represented in JSON as a string holding the XPath location of the node. \n3. Each XPath location string is prefixed with the Unicode Character 'OGHAM SPACE MARK' `U+1680`\n4. XPath location strings are identifiable by special syntax highlighting\n5. `CMD + click` on an XPath location to highlight the node in the XML source (currently the source file URI is assumed to be that of the context item)\n6. Executing the two XPath cells below (repeat ⇧Enter to execute and move to next cell) results in a sequence of XML Attribute nodes"},{"kind":2,"language":"xpath","value":"variable = data-uri % resolve-uri('../gdpbycountry/gdpByCountry.xml', static-base-uri())"},{"kind":1,"language":"markdown","value":"*Note: XPath below uses the `$data-uri` context variable declared in the XPath Prolog above*"},{"kind":2,"language":"xpath","value":"doc($data-uri)/countries/country[@region eq 'Europe']/@name"},{"kind":1,"language":"markdown","value":"#### Representing Primitive Types\n\n1. The most basic XPath types are supported with their JSON equivalent\n2. The string equivalent of XPath types such as `QName` are used\n3. An XPath empty-sequence is currently represented as`[]`"},{"kind":1,"language":"markdown","value":"### HTML Data Table\n1. This output type uses the mimetype `text/html`\n2. The Output cell is rendered as an HTML table\n3. Each table row corresponds to a JSON array item that may be an object or another nested array\n4. Each table corresponds to either a property of an object or a nested-array item\n5. Change the Output cells in this notebook by clicking on the `</>` button to the `text/html` mimetype to see the table representation\n\n*Note: This output type is light-weight and quite primitve in implementation. For large data-sets or rich table rendering it is recommended you install and use third-party Notebook renderer extensions (like [RandomFractals Data Table](https://marketplace.visualstudio.com/items?itemName=RandomFractalsInc.vscode-data-table)) for the `text/x-json` output type.*"}]