XSLT/XPath for Visual Studio Code

The XSLT/XPath extension for VSCode provides comprehensive language support for XSLT 3.0 and XPath 3.1, and for the XSLT 4.0 and XPath 4.0 features implemented in Saxon 13. This ReadMe is merely a 'quick start' guide, see the XSLT/XPath User Guide for more comprehensive help.

XSLT 4.0 with a documentation note, its hover help where the function is called, and the XSLT Imports view:

Features

This release adds full support for XSLT 4.0 in Saxon 13 - see Release 2.0 Highlights.

* Problem-reporting currently depends on the VSCode symbol-provider. To ensure problems are always reported in VSCode, use the following VSCode setting: "breadcrumbs.enabled": true

XML Commands

The XML selection commands are also in the XML Selection submenu of the editor's context menu (right-click), and in the XML: Select Element... quick pick (⇧⌘2 / Ctrl+Shift+2) - both show their key-bindings.

Introduction

For lexical analysis, this extension processes code character-by-character. This analysis is exploited for all features including all syntax highlighting. Avoiding the much more common use of regular expressions on a line-by-line basis brings significant benefits. These benefits include improved responsiveness, lower CPU load, improved code maintainability and greater integrity for syntax highlighting.

Auto-completion is provided for XSLT and XPath. This includes context-aware completion items for all code symbol names. XSLT and XPATH function signatures and descriptions are shown in the description alongside function completion items. The last active non-XSLT file is used as the source to compute available node names for XPath location steps.

This extension's linter performs a comprehensive set of checks on the code. The linter ensures that any code symbols within XSLT or XPath with problems are accurately identified at the symbol-level. Asynchronous processing for xsl:include/xsl:import dependencies allows checking of references to symbol definitions regardless of the location of the definition.

Running XSLT

(1) XSLT in active editor, (2) the Saxon processor, (3) the XML context file - click the play button to run

The quickest way to run the stylesheet in the active editor is Quick Run (⌘⌥R / Ctrl+Alt+R): the first run creates a task for you, which later runs reuse.

XSLT transforms for SaxonJava, SaxonJS and SaxonC are configured and run as special VSCode Tasks.

XSLT task JSON properties can reference special commands. The special commands allow file-selection via a File Explorer or 'Recent Files' list, an example using: "xsltFile": "${command:xslt-xpath:pickXsltFile}". A sample screenshot is shown below:

For more a full description on using VSCode tasks to run XSLT, see Running XSLT.

Release Notes

The project changelog is maintained on the project wiki. See Release Notes.

Extension Settings

To benefit from this extension, it's essential to make a few updates to VS Code's User or Workspace settings to your specific needs and environment. This section outlines the main settings associated with XSLT features.

For more details on how these settings are managed within VS Code see: VSCode Settings

XSLT Tasks

To use the task-provider for the Java Saxon XSLT Processor, the following setting is required (alter path to suit actual jar location):

  "XSLT.tasks.saxonJar": "/path/to/folder/SaxonHE12-9J/saxon-he-12.9.jar"

To use the task-provider for SaxonC, set the path of the folder containing the SaxonC command-line Transform executable:

  "XSLT.tasks.saxonCPath": "/path/to/folder/containing/Transform"

XSLT 4.0 Tasks

XSLT 4.0 requires Saxon-PE or Saxon-EE (or the equivalent SaxonC edition). The task property allowSyntaxExtensions40 defaults to "auto", which enables XPath 4.0 syntax unless the processor is Saxon-HE.

When the parse-html() function is used, the following setting is also needed, e.g.:

  "XSLT.tasks.htmlParserJar": "/path/to/folder/htmlparser-1.4.jar" // or: nu.validator.jar

XSLT Packages

If your XSLT contains xsl:use-package instructions, XSLT package names are resolved to lookup symbols to support the following features:

• Goto Definition
• Symbol Diagnostics
• Symbol Auto-Completion

To allow XSLT package names to be resolved to file paths, package details should be added to the setting:

XSLT.resources.xsltPackages

An example of XSLT package name settings:

"XSLT.resources.xsltPackages": [
       { "name": "example.com.package1", "version": "2.0", "path": "included1.xsl"},
       { "name": "example.com.package2", "version": "2.0", "path": "features/included2.xsl"},
       { "name": "example.com.package3", "version": "2.0", "path": "features/not-exists.xsl"}
]

If file paths are relative they are resolved from the first Visual Studio Code Workspace folder

Note: Currently, XSLT Package versions are not used in package-name lookup

Formatting

This extension supports special XSLT code formatting. This can be invoked with a VS Code command and/or as you type, depending on your settings.

VSCode Formatting Command Keyboard Shortcuts

1. On Windows - Shift + Alt + F.
2. On Mac - Shift + Option + F.
3. On Ubuntu - Ctrl + Shift + I.

Recommended Editor Settings For Formatting etc.

You should start with something like the following in the settings.json file:

{
  ...
  "[xslt]": {
        "editor.formatOnPaste": true,
        "editor.formatOnSave": false,
        "editor.formatOnSaveMode": "modifications",
        "editor.formatOnType": true,
        "editor.defaultFormatter": "deltaxml.xslt-xpath",
        "editor.detectIndentation": true,
        "editor.tabSize": 2,
        "editor.wordSeparators": "`~!@#$%^&*()=+[{]}\\|;:'\",.<>/?",
        "outline.showArrays": true,
        "breadcrumbs.showArrays": true,
        "editor.semanticHighlighting.enabled": true
  }
  ...
}

Refactoring

A range of code refactoring features are supported, including Rename Symbol, Extract Function and, for XSLT 4.0, Extract record type.

When XSLT code is refactored, instructions and expressions are revised when necessary to ensure the code behaviour remains unchanged. For example, the Extract Function refactor revises all expressions requiring the context-item so the code compiles and runs as before.

Editor Settings for Highlighting in Color Theme Extensions

Syntax highlighting is currently only enabled by default in VSCode's built-in themes. This is because some extension themes may not yet have specific language support for VSCode's 'Semantic Highlighting' as used by this extension.

To enable syntax highighting for a custom theme you need to change User Settings. A set of dark color themes, specially enhanced for XSLT, are provided by the XSLT Dark Themes extension.

You can also customize XSLT token colors. For example, to enable syntax highlighting for XSLT and add some customizations in the Gruvbox Material Dark theme you could use:

  "editor.semanticTokenColorCustomizations": {
    "[Gruvbox Material Dark]": {
      "enabled": true,
      "rules": {
        "xmlPunctuation": "#b75a1e",
        "anonymousFunction": "#d3869b",
        "xmlText": "#928374",
        "attributeNameTest": "#89b482",
        "elementName": "#d3869b"
      },
    }
  },

Or, to enable syntax highlighting for all themes:

  "editor.semanticHighlighting.enabled": true,

Editor Settings For Word Selection/Navigation

For word selection/navigation, by default, names like $two-parts are treated as two words for selection purposes and $ is also excluded from the name. This behaviour can be altered using the VSCode setting:

editor.wordSeparators

See: VSCode Documentation on Settings

Code Folding

Code-folding currently works by indentation indicating the nesting level. So, if code-folding does not work as expected, try reformatting using (for MacOS) - Shift-⌥-F.

Region code-folding is also supported. This can be useful, for example, for blocks of templates for a specific mode. To set a region code-folding block, surround it with <?region?> and <?endregion?> processing instructions. You may optionally include a label for the processing instructions, for example:

  <?region reconstruct?>
    ...
  <?endregion reconstruct?>

XSLT/XPath User Guide

The XSLT/XPath User Guide provides an introduction to features supported by this extension for XSLT and XPath developers.

The main documentation pages are linked below:

• Overview
• Release 2.0 Highlights
• Editing XML
• Editing XSLT/XPath
• Code Navigation
• Quick Run
• Running XSLT
• Debugging
• Settings
• XSLT 4.0
• Records and Enums
• Code Documentation
• XML Catalogs

Support for other languages with embedded XPath

In addition to XSLT, other XML-based languages/vocabularies with embedded XPath will be supported in future in this extension. Currently, DeltaXignia's Document Comparison Pipeline (DCP) format is supported, acting as a pilot for other languages.

Project Sponsor Message:

DeltaXignia specialise in management of change in structured content with solutions including XML and JSON compare and merge. Whether you are working with documents, data or code, DeltaXignia’s solutions provide the most reliable, efficient and accurate comparison and merge functions for managing structured content.

Comprehensive API’s, configurable output formats and full audit trail capabilities make DeltaXignia’s products perfect for integration with your current content management workflows or for embedding within existing editing and publishing products.