There is no step-through debugger in the XSLT/XPath extension. When debugging XSLT, the xsl:message instruction can be used to send output to the terminal window. 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:

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

2. Review Inserted xsl:message

When xdm:debug variables (or 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, defaulting to the name of the enclosing xsl:function or the mode of an enclosing xsl:template, is inserted as the first argument.

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

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. Hover over the problem function and accept the 'QuickFix' by pressing Enter.

Two Quick Fix options are offered:

• Include XSLT module for xdm:debug (the default, 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.

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.

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

• 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
• 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