XSLT and XPath

for Visual Studio Code

143K Installs:

Print Debugging

To set breakpoints and step through a stylesheet, see the Debugger.

While debugging, a logpoint can do much of what an xsl:message with xdm:debug-color() does, without changing the stylesheet or including the xdm-view library. Its message can include XPath values, formatted and colored in the same way, and {$*} writes all the local variables, with a banner. A logpoint has less flexibility, though:

  • Messages are only written while debugging, with SaxonJ - not when the stylesheet runs as a task or with Quick Run, or with SaxonJS or SaxonC.
  • There's less control over formatting: the banner always names the template, function or instruction, there's no $level indentation, and {$*} writes every local variable, not a chosen set.
  • An expression in the message can't contain braces, as in a map constructor.
  • Logpoints aren't saved with the code. VS Code keeps them for the workspace, so they can't be committed or shared with the stylesheet.

Adding xsl:message instructions is another way to debug XSLT - one that works with any Saxon processor, including SaxonJS and SaxonC, and shows how values change over a whole run. The output is written to the terminal when the stylesheet runs as a task or with Quick Run, and to the Debug Console when it's debugged, with ANSI colors kept in both. Diagnostics are added using the xdm:debug() function, from the xdm-viewer XSLT library, which renders one or more named in-scope variables to a formatted string for use in an xsl:message.

Diagnosing state of in-scope XSLT variables

There is special provision for conveniently reviewing the state of in-scope XSLT variables. This approach is outlined here.

1. Use Auto-complete for xsl:message

To assist with debugging, the XSLT editor has special auto-completion for the xsl:message instruction. Four completion items are offered when in-scope variables are found - otherwise, only xsl:message (blank):

  • xsl:message (blank) - inserts a simple placeholder, for entering your own xsl:message content
  • xsl:message - adaptive serialization - serializes the last declared variable using serialize() with the adaptive method
  • xsl:message - xdm:debug variables - lists all in-scope variables in a single xdm:debug() call
  • xsl:message - xdm:debug-color variables - as above, with ANSI-colored output
The auto-complete list for xsl:message when variables or parameters are in context.

2. Review Inserted xsl:message

When xsl:message - xdm:debug variables (or xsl:message - xdm:debug-color variables) is selected from the auto-complete list, an xsl:message snippet is inserted at the cursor with all in-scope variables collected into a single XPath map, passed as the second argument to xdm:debug(). A title is inserted as the first argument: Watch: followed by the name of the element that the xsl:message is in - e.g. an xsl:function or named template - or the mode of an xsl:template. If that element has neither, the title is Watch Variables.

<xsl:message select="xdm:debug('Watch: my-function', map { 'items': $items, 'total': $total })"/>

The generated xsl:message inserted with unresolved call to xdm:debug-color()

3. Quick Fix: Include the xdm-view Library

As can be seen above, the xdm:debug() function is not initially resolvable - it will be marked as a 'problem' until its defining library is included. Put the cursor on the problem function and open Quick Fix with Cmd/Ctrl+. - or choose Quick Fix... when hovering over it.

Two Quick Fix options are offered:

  • include XSLT module for xdm:debug and xdm:trace (the preferred option) - inserts the xdm namespace declaration (http://deltaxignia.com/ns/xdm-persistence) and an xsl:include instruction referencing a workspace-local copy of xdm-view.xsl if one is found, otherwise the copy of the xdm-viewer library bundled with this extension.
  • copy xdm-view library into workspace - copies the bundled xdm-viewer library (and its xdm-persistence dependency) into an xslt-resources/xdm-view folder in your workspace, then applies the same include as above. Use this if you want the library files available locally, for example to inspect or version them alongside your own stylesheets.
Quick Fix menu to resolve the call to xdm:debug-color()

4. Run XSLT and Review State in Terminal

You can now run the XSLT as normal, but you will now see the xsl:message output in the terminal window, with each in-scope variable shown under a title banner. Node values are shown with their location path and a pruned, truncated rendering, keeping the output readable for large trees.

xsl:message output xdm:debug-color().

5. Benefits of xdm:debug() over fn:serialize()

We recommend the xdm:debug-color() function as it supplements the built-in serialize function with features that are especially important when you're interested in several variable values or the values have complex types.

The auto-complete fills in the arguments, so you rarely need to change them. The function signatures are:

xdm:debug($title as xs:string, $labels as map(xs:string, item()*)) as xs:string xdm:debug($title as xs:string, $labels as map(xs:string, item()*), $level as xs:integer) as xs:string xdm:debug-color($title as xs:string, $labels as map(xs:string, item()*)) as xs:string xdm:debug-color($title as xs:string, $labels as map(xs:string, item()*), $level as xs:integer) as xs:string
  • The output begins with a title to help locate the xsl:message in the code
  • The remaining content is structured in two columns: variable names in the first, values in the second
  • Nested maps, arrays and sequences are formatted for readability
  • Bracket-pair coloring helps identify the start/end of maps, sequences or arrays
  • A set of named variables or parameters can be serialized with a single function
  • Lexical XPath locations are shown above each node, and above each XPath 4.0 JNode, e.g. /lines/*[2]/sku - see JSON and JNodes
  • Node content is truncated when required to keep message output concise
  • Syntax highlighting helps identify types and map keys etc.
  • Values are annotated with their type where this is non-obvious
  • The optional $level argument adds indentation proportional to this value - helpful for recursive calls

Tracing a value within an expression: xdm:trace()

To see a value part-way through an XPath expression, without taking the expression apart, wrap it in xdm:trace(). Like XPath's built-in trace(), it returns the value unchanged, so the expression gives the same result, and writes it with xsl:message, after a label. Where trace()'s output is up to the processor - Saxon writes one line per item, with a map on one line - xdm:trace() writes the value as xdm:debug() does: formatted over several lines where it has structure, and in color.

<xsl:variable name="total" select="sum(xdm:trace($order/line ! (@qty * @price), 'line totals'))"/> <xsl:variable name="customer" select="xdm:trace($customers?($id), 'customer')"/> line totals: (7.5, 12, 17.5) customer: { 'name': 'Ada', 'langs': ['xslt', 'xpath'] }

To trace an existing expression, select it and choose Wrap with xdm:trace() (or Wrap with trace()) from the refactoring code actions, e.g. with ⌘.. The call's label is the expression itself, selected so you can type another. When you've finished debugging, put the cursor on a call's name - xdm:trace, trace or fn:trace - and choose Remove xdm:trace() - keep the expression to leave just the expression traced. It's kept in brackets only where it needs them to keep its meaning, e.g. (1 + 2) * 2 from xdm:trace(1 + 2, 'x') * 2.

At the start of an XPath expression, auto-completion offers xdm:trace(…, label). It's from the same xdm-viewer library as xdm:debug(), so it's marked as a problem until the library is included, with the same Quick Fix. The function signatures are:

xdm:trace($value as item()*) as item()* xdm:trace($value as item()*, $label as xs:string?) as item()* xdm:trace($value as item()*, $label as xs:string?, $useColor as xs:boolean) as item()*
  • Color is on by default. To turn it off for every call - e.g. when messages are written to a log file - set the NO_COLOR environment variable, to any value. To turn it off for one call, pass false() as the third argument.
  • Node values are shown with their location path and a pruned rendering, as with xdm:debug().
  • xdm:trace() reads the whole value before returning it, to format it. trace() may instead report the items of a lazily evaluated value one at a time as they're used - so, for example, head(xdm:trace($items)) reads all of $items.
  • In the debugger, the output is written to the Debug Console, in color.

On this page