XSLT and XPath

for Visual Studio Code

143K Installs:

Records and Enums

XPath 4.0 adds record types, for maps with a known set of fields, and enumeration types, for strings with a known set of values. XSLT 4.0 adds the xsl:item-type declaration to give these types names.

When a variable, parameter or function result is declared with one of these types, the XSLT/XPath extension uses the declared type for auto-completion, linting, hover help and navigation - for example, to list the fields when building a map, or the values of an enumeration inside a string literal.

These features are enabled when the stylesheet has version="4.0". See the XSLT 4.0 page for the XSLT 4.0 features supported.

For Saxon PE or EE 12.8 or later, run with syntax extensions, they can also be enabled for XSLT 3.0 stylesheets, with the setting XSLT.validation.xslt30ItemTypesAndNotes - see XSLT 4.0 Item Types and Notes in XSLT 3.0. That page also describes converting Saxon's earlier saxon:type-alias and tuple(...) syntax.

Declaring types

A record type lists its fields, each with an optional type. A field name followed by ? is optional. An enumeration type lists its values as string literals:

<xsl:item-type name="address" as="record(city as xs:string, postcode? as xs:string)"/> <xsl:item-type name="person" as="record(name as xs:string, age as xs:integer, address as address)"/> <xsl:item-type name="colour" as="enum('red', 'green', 'blue')"/>

A type can also be written inline in an as attribute, for example as="record(x as xs:double, y as xs:double)".

In an attribute value, quotes within a type can be written as references, as Saxon allows - for example as="enum(&quot;it's&quot;, 'is')" or a field name quoted with &#39; - and the extension reads them as the quotes they stand for.

Auto-completion for types

  • Within an as attribute, and after instance of, castable as and the other type operators, the names of declared item types are offered with the built-in types.
  • The record(...) and enum(...) suggestions insert a snippet with placeholders for the fields or values.

Checks on declarations

  • An item type name that isn't declared is reported, as are duplicate declarations and a type that refers to itself (directly or through other named types).
  • A duplicate field name in a record type is an error, as in Saxon. A duplicate value in an enumeration type is a warning, with a Remove duplicate enum value quick fix.
  • Extensible record types, such as record(a, *), have been dropped from XPath 4.0 and are reported as an error.

Go to Definition (F12) and Find All References (⌥⇧F12) work for item type names.

Building records

A record is built with a map constructor, or with the xsl:map or xsl:record instruction. Wherever the record type is known, the extension helps you complete the map and checks it against the type.

Map constructors

In the select attribute of a declaration with a record type, type { (or map {) and accept the suggestion to insert a complete map constructor, with an entry for each required field - when the record has optional fields, a second suggestion includes them too:

<xsl:variable name="p" as="person" select="{ 'name': __TODO.name, 'age': __TODO.age, 'address': { 'city': __TODO.city } }"/>

Each __TODO.field placeholder is reported as a warning until it's replaced with a value. A double-click selects the whole placeholder, ready to type over.

After typing , at the end of an entry, the suggestions list the fields that aren't in the map yet, including optional fields.

The xsl:map instruction

Where a record is built with xsl:map, for example in the content of an xsl:variable with a record type, typing < offers an xsl:map suggestion with an xsl:map-entry for each required field (or, as a second suggestion, for all fields). Inside an existing xsl:map, the xsl:map-entry suggestions are named after the fields not yet added, for example xsl:map-entry 'age', and the key attribute offers the field names.

The xsl:record instruction

The XSLT 4.0 xsl:record instruction builds a record from its attributes: each attribute in no namespace is a field, with an XPath expression as its value. Its record type is the type in its own xsl:as attribute, or else the declared type of its value, as for xsl:map:

<xsl:variable name="p" as="person"> <xsl:record name="'Ann'" age="42" address="{ 'city': 'Oxford' }"/> </xsl:variable>
  • Auto-completion - typing < offers an xsl:record suggestion with an attribute for each required field, e.g. xsl:record person: required fields, and a second suggestion with all fields. Within the start tag, the fields not yet added are offered as attributes, required fields first, and within the content, typing < offers an xsl:map-entry for each field not yet added. A field whose name isn't an NCName, e.g. 'first name', is added as an xsl:map-entry child.
  • Checks - as for a map: an attribute that isn't a field is a warning, a literal value of the wrong type is an error, and a missing required field is an error, with the Add missing record fields quick fix. A field can also be added by an xsl:map-entry child - and when other content may add fields, missing fields aren't reported.
  • Renaming - renaming a field renames its xsl:record attributes, and Find All References lists them.

Checks on records

  • Missing fields - a required field that's missing is an error, with an Add missing record fields quick fix that adds an entry, with a placeholder, for each one.
  • Unknown fields - an entry for a field that isn't in the record type is a warning. For a map constructor key, or an xsl:record attribute, there's a Change to 'name' quick fix for each field not yet in the map, closest name first - e.g. Change to 'name' for 'nam'.
  • Field values - a literal value of the wrong type, such as a string for an xs:integer field, is an error.
  • Duplicate keys - two entries with the same literal key are an error, in any map constructor or xsl:map, whether or not it has a record type - except in an xsl:map with a duplicates attribute, which handles them, where they're a warning.

Where the record type comes from

Maps are checked, and completed, where their type is declared:

  • the select or content of an xsl:variable, xsl:param or xsl:with-param with an as attribute - for an xsl:with-param without one, the type of the called template's parameter is used
  • the result of an xsl:function with an as attribute - its last xsl:sequence
  • xsl:sequence and xsl:select with an as attribute
  • the arguments of calls to user-defined functions, including keyword arguments such as ex:move(point := { ... }) and the left-hand operand of the arrow operators
  • a typed let binding, such as let $p as person := { ... }

Using records

Lookups

After the ? lookup operator on a value with a record type, the suggestions list the record's fields. This works for variables, calls to functions with a declared record result, and chains of lookups such as $p?address?city. A lookup of a field that isn't in the record type is a warning.

Hover and navigation

Hovering over a field name - in a lookup, a map constructor key or the key of an xsl:map-entry - shows the field's declaration. Go to Definition on a field name goes to the field in the record type.

Hovering over the name of a named item type - where it's used, or on its declaration - shows its declaration, with its values for an enumeration type. When the xsl:item-type has a documentation note, the note is shown too, and a field's @field text is shown when hovering over the field, and with the field in the auto-completion suggestions.

Hover over a record field in a lookup, e.g. $shape?colour, showing the field's declaration and its @field text from the xsl:item-type's documentation note.

Renaming a field

Rename Symbol (F2) on a field name - in the record type, a lookup, a map constructor key, the key of an xsl:map-entry, an xsl:record attribute, or an @field tag of a documentation note - renames the field, and all its references. Find All References (⌥⇧F12) lists them.

  • Only the field of that record type is renamed - not a field with the same name in another record type.
  • The references are found in the stylesheet, the modules it includes or imports, and - from the workspace's modules - each stylesheet that imports or includes it, with the modules they use. So a rename in a module of types reaches the stylesheets that use them.
  • A quoted field name keeps its quotes, e.g. 'unit name'. A new name must be an NCName, unless the field's name isn't one.

Path steps on records (JNodes)

XPath 4.0 path expressions can navigate maps and arrays as trees of JNodes, e.g. jtree($p)/address/city. Field names are suggested, and checked, for steps after jtree($p)/, and after a variable declared as a JNode for a record type, such as jnode(*, person). See JSON and JNodes.

Refactoring: Extract record type

The Extract record type refactoring creates a record type from an existing map - for example, when updating code written for XSLT 3.0. It's offered when the stylesheet has version="4.0", or with the XSLT.validation.xslt30ItemTypesAndNotes setting:

  1. Select a map constructor or xsl:map whose keys are string literals - or simply place the cursor on the start tag of the xsl:variable, xsl:param, xsl:with-param, xsl:function, xsl:sequence or xsl:select that it's the value of.
  2. Open the refactorings with the 💡 light-bulb, or ⌘., and choose Extract record type.
  3. An xsl:item-type declaration is added for the record type, and the declaration's as attribute is set to it - replacing a generic type such as map(*). Field types are taken from literal values, and a nested map becomes a nested record type.
  4. The new type is named record-type, and Rename Symbol is started so you can give it a meaningful name.

If an existing xsl:item-type already has the same field names, a Use record type 'name' refactoring is also offered, in the Rewrite section of the list. It sets the as attribute to the existing type without adding a declaration.

Extract record type is also offered for a record(...) type written inline in an as attribute - with the cursor on it, or a selection within it - except the whole type of an xsl:item-type. The innermost record type is replaced by the name of a new xsl:item-type, named after the field whose type it is, if any, and Rename Symbol is started:

<xsl:item-type name="person" as="record(name as xs:string, address as record(city as xs:string))"/>

becomes:

<xsl:item-type name="address" as="record(city as xs:string)"/> <xsl:item-type name="person" as="record(name as xs:string, address as address)"/>
Before refactor: The two 💡 refactorings for a candidate record-type variable.
After refactor: a prompt to rename the record-type now it's declared and set on the variable.

Enumeration types

Auto-completion for values

Where an enumeration type is expected, typing a quote character offers the enumeration's values. This applies to:

  • the select of an xsl:variable, xsl:param or xsl:with-param declared with the type (or xs:boolean, for true() and false())
  • arguments of calls to user-defined functions whose parameter has the type, and typed let bindings
  • record fields with the type, in map constructors
  • the test of an xsl:when in an xsl:switch - see below

A string literal that isn't one of the values is reported as an error.

Hovering over the name of an enumeration type - or a global variable or parameter, a parameter of a function or template, or a record field, with the type - lists its values - on one line for a few values, otherwise as a list. For a type declared as another, or as a choice of enumeration types, the values are those it resolves to.

Hover over the name of an enumeration type, showing its values

Renaming a value

Rename Symbol (F2) on an enumeration value - in its enum(...) declaration, or a string literal for it - renames the value and the string literals that refer to it: variable values, function arguments (including keyword arguments), record field values in map constructors, typed let bindings and xsl:switch cases. Find All References (⌥⇧F12) lists them.

  • Only the values of that type are renamed - not the same value in another enumeration type. An inline enum(...) type is identified by its values.
  • The value is renamed in imported modules too.
  • A new name that's already a value of the type is rejected. A quote in the new value must be doubled, e.g. don''t.

xsl:switch on an enumeration

The XSLT 4.0 xsl:switch instruction selects an xsl:when by comparing a value with each test. When the select has an enumeration type - a variable, function call or record field lookup with a declared type - the extension works with its values.

Quick Fix options shown for xsl:switch on an enum type.

  • Missing values - when an enumeration value has no xsl:when, and there's no xsl:otherwise, the xsl:switch is marked with the information message xsl:switch has no xsl:when or xsl:otherwise for the enumeration values: .... Its two quick fixes add an xsl:when for each missing value:
    • Add missing xsl:when cases with select - e.g. <xsl:when test="'green'" select=""/>
    • Add missing xsl:when cases with content - e.g. <xsl:when test="'green'">...</xsl:when>
  • Values that never match - a test value that isn't one of the enumeration's values, or that an earlier xsl:when already tests, is a warning, as the xsl:when never matches it.
  • Auto-completion - inside an xsl:switch, the completion list offers an xsl:when for each value not yet tested.

On this page