XSL Transformations (XSLT) Version 4.0

2.14 Error Handling

[Definition: An error that can be detected by examining a stylesheet before execution starts (that is, before the source document and values of stylesheet parameters are available) is referred to as a static error.]

Generally, errors in the structure of the stylesheet, or in the syntax of XPath expressions contained in the stylesheet, are classified as static errors. Where this specification states that an element in the stylesheet must or must not appear in a certain position, or that it must or must not have a particular attribute, or that an attribute must or must not have a value satisfying specified conditions, then any contravention of this rule is a static error unless otherwise specified.

A processor must provide a mode of operation that takes a (possibly erroneous) stylesheet package as input and enables the user to determine whether or not that package contains any static errors.

A processor may also provide a mode of operation in which static errors in parts of the stylesheet that are not evaluated can go unreported.

[Definition: An error that is not capable of detection until a source document is being transformed is referred to as a dynamic error.]

When a dynamic error occurs, and is not caught using xsl:catch, the processormust raise the error, and the transformation fails.

Because different implementations may optimize execution of the stylesheet in different ways, the detection of dynamic errors is to some degree implementation-dependent. In cases where an implementation is able to produce a principal result or secondary result without evaluating a particular construct, the implementation is never required to evaluate that construct solely in order to determine whether doing so causes a dynamic error. For example, if a variable is declared but never referenced, an implementation may choose whether or not to evaluate the variable declaration, which means that if evaluating the variable declaration causes a dynamic error, some implementations will raise this error and others will not.

There are some cases where this specification requires that a construct must not be evaluated: for example, the content of an xsl:if instruction must not be evaluated if the test condition is false. This means that an implementation must not raise any dynamic errors that would arise if the construct were evaluated.

An implementation may raise a dynamic error before any source document is available, but only if it can determine that the error would be raised for every possible source document and every possible set of parameter values. For example, some circularity errors fall into this category: see 9.11 Circular Definitions.

There are also some dynamic errors where the specification gives a processor license to raise the error during the analysis phase even if the construct might never be executed; an example is the use of an invalid QName as a literal argument to a function such as key, or the use of an invalid regular expression in the regex attribute of the xsl:analyze-string instruction.

A dynamic error is also raised during the static analysis phase if the error occurs during evaluation of a static expression.

The XPath specification states (see [XPath 4.0] section 2.4.1 Kinds of Errors) that if any expression (at any level) can be evaluated during the analysis phase (because all its explicit operands are known and it has no dependencies on the dynamic context), then any error in performing this evaluation may be raised as a static error. For XPath expressions used in an XSLT stylesheet, however, any such errors must not be raised as static errors in the stylesheet unless they would occur in every possible evaluation of that stylesheet; instead, they must be raised as dynamic errors, and raised only if the XPath expression is actually evaluated.

<xsl:choose>
  <xsl:when test="system-property('xsl:version') = '1.0'">
    <xsl:value-of select="1 div 0"/>
  </xsl:when>
  <xsl:otherwise>
    <xsl:value-of select="xs:double('INF')"/>
  </xsl:otherwise>
</xsl:choose>

[Definition: Certain errors are classified as type errors. A type error occurs when the value supplied as input to an operation is of the wrong type for that operation, for example when an integer is supplied to an operation that expects a node.] If a type error occurs in an instruction that is actually evaluated, then it must be raised in the same way as a dynamic error. Alternatively, an implementation may raise a type error during the analysis phase in the same way as a static error, even if it occurs in part of the stylesheet that is never evaluated, provided it can establish that execution of a particular construct would never succeed.

It is implementation-defined whether type errors are raised statically.

<xsl:if test="false()">
  <xsl:number select="42"/>
</xsl:if>

<xsl:template match="para">
  <xsl:param name="p" as="item()"/>
  <xsl:number select="$p"/>
</xsl:template>

If more than one error arises, an implementation is not required to raise any errors other than the first one that it detects. It is implementation-dependent which of the several errors is raised. This applies both to static errors and to dynamic errors. An implementation is allowed to raise more than one error, but if any errors have been raised, it must not finish as if the transformation were successful.

When a transformation raises one or more dynamic errors, the final state of any persistent resources updated by the transformation is implementation-dependent. Implementations are not required to restore such resources to their initial state. In particular, where a transformation produces multiple result documents, it is possible that one or more serialized result documents may be written successfully before the transformation terminates, but the application cannot rely on this behavior.

Everything said above about error handling applies equally to errors in evaluating XSLT instructions, and errors in evaluating XPath expressions. Static errors and dynamic errors may occur in both cases.

[Definition: If a transformation has successfully produced a principal result or secondary result, it is still possible that errors may occur in serializing that result . For example, it may be impossible to serialize the result using the encoding selected by the user. Such an error is referred to as a serialization error.] If the processor performs serialization, then it must do so as specified in 26 Serialization, and in particular it must raise any serialization errors that occur.

Errors are identified by a QName. For errors defined in this specification, the namespace of the QName is always http://www.w3.org/2005/xqt-errors (and is therefore not given explicitly), while the local part is an 8-character code in the form PPSSNNNN. Here PP is always XT (meaning XSLT), and SS is one of SE (static error), DE (dynamic error), or TE (type error). Note that the allocation of an error to one of these categories is purely for convenience and carries no normative implications about the way the error is handled. Many errors, for example, can be raised either dynamically or statically. These error codes are used to label error conditions in this specification, and are summarized in D Summary of Error Conditions.

Errors defined in related specifications ([XPath 4.0], [Functions and Operators 4.0][Serialization 4.0]) use QNames with a similar structure, in the same namespace. When errors occur in processing XPath expressions, an XSLT processor should use the original error code reported by the XPath processor, unless a more specific XSLT error code is available.

Implementations must use the codes defined in these specifications when raising dynamic errors, to ensure that xsl:catch behaves in an interoperable way across implementations. Stylesheet authors should note, however, that there are many examples of errors where more than one rule in this specification is violated, and where the processor therefore has discretion in deciding which error code to associate with the condition: there is therefore no guarantee that different processors will always use the same error code for the same erroneous input.

Additional errors defined by an implementation (or by an application) may use QNames in an implementation-defined (or user-defined) namespace without risk of collision.

5.6 Value Templates

The string value of an attribute or text node in the stylesheet may in particular circumstances contain embedded expressions enclosed between curly brackets. Attributes and text nodes that use (or are permitted to use) this mechanism are referred to respectively as attribute value templates and text value templates.

[Definition: Collectively, attribute value templates and text value templates are referred to as value templates.]

A value template is a string consisting of an alternating sequence of fixed parts and variable parts:

• A variable part consists of an optional XPath expression enclosed in curly brackets ({}): more specifically, a string conforming to the XPath production Expr?.

  Note:

  An expression within a variable part may contain an unescaped curly bracket within a StringLiteral^XP or within a comment.

  Currently no XPath expression starts with an opening curly bracket, so the use of {{ creates no ambiguity. If an enclosed expression ends with a closing curly bracket, no whitespace is required between this and the closing delimiter.

  The fact that the expression is optional means that the string contained between the curly brackets may be zero-length, may comprise whitespace only, or may contain XPath comments. The effective value in this case is a zero-length string, which is equivalent to omitting the variable part entirely, together with its curly-bracket delimiters.

• A fixed part may contain any characters, except that a left curly bracket must be written as {{ and a right curly bracket must be written as }}.

[ERR XTSE0350] It is a static error if an unescaped left curly bracket appears in a fixed part of a value template without a matching right curly bracket.

It is a static error if the string contained between matching curly brackets in a value template does not match the XPath production Expr?^XP, or if it contains other XPath static errors. The error is raised using the appropriate XPath error code.

[ERR XTSE0370] It is a static error if an unescaped right curly bracket occurs in a fixed part of a value template.

The result of evaluating a value template is referred to as its effective value. The effective value is the string obtained by concatenating the expansions of the fixed and variable parts:

• The expansion of a fixed part is obtained by replacing any double curly brackets ({{ or }}) by the corresponding single curly bracket.

• The expansion of a variable part is as follows:

  • If an expression is present, the result of evaluating the enclosed XPath expression and converting the resulting value to a string. This conversion is done using the rules given in 5.7.2 Constructing Simple Content.

  • If the expression is omitted, a zero-length string.

In the case of an attribute value template, the effective value becomes the string value of the new attribute node. In the case of a text value template, the effective value becomes the string value of the new text node.

<xsl:variable name="id" select="'A123'"/>
<xsl:variable name="step" select="5"/>
<xsl:message expand-text="yes">Processing id={ $id }, step={ $step }</xsl:message>

<xsl:function name="f:sum" expand-text="yes" as="xs:integer">
<xsl:param name="x" as="xs:integer"/>
<xsl:param name="y" as="xs:integer"/>
  { $x + $y }
</xsl:function>

5.7 Sequence Constructors

[Definition: A sequence constructor is a sequence of zero or more sibling nodes in the stylesheet that can be evaluated to return a sequence of nodes, atomic items, and function items. The way that the resulting sequence is used depends on the containing instruction.]

Many XSLT elements, and also literal result elements, are defined to take a sequence constructor as their content.

Four kinds of nodes may be encountered in a sequence constructor:

1. A Text node appearing in the stylesheet (if it has not been removed in the process of whitespace stripping: see 3.13.1 Stripping Whitespace and Commentary from the Stylesheet) is processed as follows:

   1. if the effective value of the standard attribute [xsl:]expand-text is no, or in the absence of this attribute, the text node in the stylesheet is copied to create a new parentless text node in the result of the sequence constructor.

   2. Otherwise (the effective value of [xsl:]expand-text is yes), the text node in the stylesheet is processed as described in 5.6.2 Text Value Templates.

2. A literal result element is evaluated to create a new parentless element node, having the same expanded QName as the literal result element: see 11.1 Literal Result Elements.

3. An XSLT instruction produces a sequence of zero, one, or more items as its result. For most XSLT instructions, these items are nodes, but some instructions (such as xsl:sequence, xsl:select, xsl:map, xsl:array, and xsl:copy-of) can also produce atomic items or function items.

   Several instructions, such as xsl:element, return a newly constructed parentless node (which may have its own attributes, namespaces, children, and other descendants). Other instructions, such as xsl:if, pass on the items produced by their own nested sequence constructors.

   Three instructions serve primarily to evaluate XPath expressions:

   • The xsl:sequence instruction evaluates an XPath expression written statically in its select attribute.

   • The xsl:select instruction evaluates an XPath expression written statically in its contained text node.

   • The xsl:evaluate instruction compiles and evaluates an XPath expression that is constructed dynamically as a character string.

   These three instructions may return atomic items, function items, or nodes.

4. An extension instruction (see 24.2 Extension Instructions) also produces a sequence of items as its result.

[Definition: The result of evaluating a sequence constructor is the sequence of items formed by concatenating the results of evaluating each of the nodes in the sequence constructor, retaining order. This is referred to as the immediate result of the sequence constructor.]

However:

• For the effect of the xsl:fallback instruction, see 24.2.3 Fallback.

• For the effect of the xsl:on-empty and xsl:on-non-empty instructions, see 8.5 Conditional Content Construction.

The way that immediate result of a sequence constructor is used depends on the containing element in the stylesheet, and is specified in the rules for that element. It is typically one of the following:

• The immediate result may be bound to a variable or delivered as the result of a stylesheet function. In this case the as attribute of the containing xsl:variable or xsl:function element may be used to declare its required type, and the immediate result is then converted to the required type by applying the coercion rules.

  Note:

  • In the absence of an as attribute, the result of a function is the immediate result of the sequence constructor; but the value of a variable (for backwards compatibility reasons) is a document node whose content is formed by applying the rules in 5.7.1 Constructing Complex Content to the immediate result.

  • The coercion rules do not merge adjacent text nodes or insert separators between adjacent items. This means it is often inappropriate to use xsl:value-of in the body of xsl:variable or xsl:function, especially when the intent is to return an atomic result. The xsl:sequence instruction is designed for this purpose, and is usually a better choice.

  • The result of a function, or the value of a variable, may contain nodes (such as elements, attributes, and text nodes) that are not attached to any parent node in a result tree. The semantics of XPath expressions when applied to parentless nodes are well-defined; however, such expressions should be used with care. For example, the expression / causes a type error if the root of the tree containing the context node is not a document node.

  • Parentless attribute nodes require particular care because they have no namespace nodes associated with them. A parentless attribute node is not permitted to contain namespace-sensitive content (for example, a QName or an XPath expression) because there is no information enabling the prefix to be resolved to a namespace URI. Parentless attributes can be useful in an application (for example, they provide an alternative to the use of attribute sets: see 10.2 Named Attribute Sets) but they need to be handled with care.

• The sequence may be returned as the result of the containing element. This happens, for example, when the element containing the sequence constructor is xsl:break, xsl:catch, xsl:fallback, xsl:for-each, xsl:for-each-group, xsl:fork, xsl:if, xsl:iterate, xsl:matching-substring, xsl:non-matching-substring, xsl:on-completion, xsl:otherwise, xsl:perform-sort, xsl:sequence, xsl:try, or xsl:when.

• The sequence may be used to construct the content of a new element or document node. This happens when the sequence constructor appears as the content of a literal result element, or of one of the instructions xsl:copy, xsl:element, xsl:document, xsl:result-document, xsl:assert, or xsl:message. It also happens when the sequence constructor is contained in one of the elements xsl:variable, xsl:param, or xsl:with-param, when this instruction has no as attribute. For details, see 5.7.1 Constructing Complex Content.

• The sequence may be used to construct the string value of an attribute node, text node, namespace node, comment node, or processing instruction node. This happens when the sequence constructor is contained in one of the elements xsl:attribute, xsl:text, xsl:value-of, xsl:namespace, xsl:comment, or xsl:processing-instruction. For details, see 5.7.2 Constructing Simple Content.

<doc>
  <xsl:attribute name="e" select="1 to 5"/>
  <xsl:attribute name="f">
    <xsl:for-each select="1 to 5">
      <xsl:value-of select="."/>
    </xsl:for-each>
  </xsl:attribute>
  <xsl:attribute name="g" expand-text="yes">{1 to 5}</xsl:attribute>
</doc>

<doc e="1 2 3 4 5" f="12345" g="1 2 3 4 5"/>

8.5 Conditional Content Construction

The facilities described in this section are designed to make it easier to generate result trees conditionally depending on what is found in the input, without violating the rules for streamability. These facilities are available whether or not streaming is in use, but they are introduced to the language specifically to make streaming easier.

The facilities are introduced first by example:

<xsl:if test="exists(event)">
  <events>
    <xsl:copy-of select="event"/>
  </events>
</xsl:if>

<xsl:where-populated>
  <events>
    <xsl:copy-of select="event"/>
  </events>
</xsl:where-populated>

<xsl:if test="exists(item-for-sale)">
  <h1>Items for Sale</h1>
</xsl:if>  
<xsl:apply-templates select="item-for-sale"/>
<xsl:if test="exists(item-for-sale)">
  <p>Total value: {accumulator-before('total-value')}</p>
</xsl:if>

<xsl:sequence>
  <xsl:on-non-empty>
    <h1>Items for Sale</h1>
  </xsl:on-non-empty>  
  <xsl:apply-templates select="item-for-sale"/>
  <xsl:on-non-empty>
    <p>Total value: {accumulator-before('total-value')}</p>
  </xsl:on-non-empty>  
</xsl:sequence>

<xsl:apply-templates select="item-for-sale"/>
<xsl:if test="empty(item-for-sale)">
  <p>There are no items for sale.</p>
</xsl:if>

<xsl:sequence>
  <xsl:apply-templates select="item-for-sale"/>
  <xsl:on-empty>
    <p>There are no items for sale.</p>
  </xsl:on-empty>
</xsl:sequence>

<xsl:where-populated>
  <ul class="my-list">
    <xsl:for-each select="source-item">
       <li><xsl:value-of select="."/></li>
    </xsl:for-each>
  </ul>
</xsl:where-populated><xsl:where-populated expand-text="yes">
  <ul class="my-list">
    <xsl:for-each select="source-item">
       <li>{.}</li>
    </xsl:for-each>
  </ul>
</xsl:where-populated><xsl:where-populated expand-text="yes">
  <ul class="my-list">
    <xsl:for-each select="source-item">
       <li>{<xsl:value-of select="."}/></li>
    </xsl:for-each>
  </ul>
</xsl:where-populated>

<div id="students">
<xsl:where-populated>
   <table>
      <xsl:on-non-empty>
         <thead>
            <tr><th>Name</th><th>Age</th></tr>
         </thead>
      </xsl:on-non-empty>
      <xsl:where-populated>
         <tbody>
            <xsl:for-each select="student/copy-of()">
               <tr>
                  <td><xsl:value-of select="name"/></td>
                  <td><xsl:value-of select="age"/></td>
               </tr>
            </xsl:for-each>
         </tbody>
      </xsl:where-populated>
   </table>
</xsl:where-populated>
<xsl:on-empty>
   <p>There are no students</p>
</xsl:on-empty>
</div><div id="students" xsl:expand-text="yes">
<xsl:where-populated>
   <table>
      <xsl:on-non-empty>
         <thead>
            <tr><th>Name</th><th>Age</th></tr>
         </thead>
      </xsl:on-non-empty>
      <xsl:where-populated>
         <tbody>
            <xsl:for-each select="student/copy-of()">
               <tr>
                  <td>{name}</td>
                  <td>{age}</td>
               </tr>
            </xsl:for-each>
         </tbody>
      </xsl:where-populated>
   </table>
</xsl:where-populated>
<xsl:on-empty>
   <p>There are no students</p>
</xsl:on-empty>
</div><div id="students" xsl:expand-text="yes">
<xsl:where-populated>
   <table>
      <xsl:on-non-empty>
         <thead>
            <tr><th>Name</th><th>Age</th></tr>
         </thead>
      </xsl:on-non-empty>
      <xsl:where-populated>
         <tbody>
            <xsl:for-each select="student/copy-of()">
               <tr>
                  <td>{<xsl:value-of select="name"}/></td>
                  <td>{<xsl:value-of select="age"}/></td>
               </tr>
            </xsl:for-each>
         </tbody>
      </xsl:where-populated>
   </table>
</xsl:where-populated>
<xsl:on-empty>
   <p>There are no students</p>
</xsl:on-empty>
</div>

10.3 Stylesheet Functions

[Definition: An xsl:function declaration declares the name, parameters, and implementation of a family of stylesheet functions that can be called from any XPath expression within the stylesheet (subject to visibility rules).]

<!-- Category: declaration -->
<xsl:function
  name = eqname
  as? = sequence-type〔'item()*'〕
  visibility? = "public" | "private" | "final" | "abstract"〔'private'〕
  streamability? = "unclassified" | "absorbing" | "inspection" | "filter" | "shallow-descent" | "deep-descent" | "ascent" | eqname〔'unclassified'〕
  override-extension-function? = boolean〔'yes'〕
  [override]? = boolean〔'yes'〕
  new-each-time? = "yes" | "true" | "1" | "no" | "false" | "0" | "maybe"
  cache? = boolean〔'no'〕 >
  <!-- Content: (xsl:param*, sequence-constructor) -->
</xsl:function>

The effect of an xsl:function declaration is to add a function definition to the static context for all XPath expressions used in the stylesheet (including an XPath expression used within a predicate in a pattern).

The content of the xsl:function element consists of zero or more xsl:param elements that specify the formal parameters of the function, followed by a sequence constructor that defines the value to be returned by the function.

The children and attributes of the xsl:function declaration translate directly into properties of the function definition:

• The xsl:function/@name attribute defines the function’s name.

• The xsl:param children define the function’s parameters:

  • The xsl:param/@name attribute defines the name of the parameter.

  • The xsl:param/@required attribute determines whether the parameter is mandatory or optional.

  • The xsl:param/@as attribute determines the required type of the parameter.

  • The xsl:param/@select attribute determines a default value for an optional parameter.

• The xsl:function/@as attribute defines the return type of the function.

• The implementation of the function is defined by the sequence constructor content of the xsl:function element.

An xsl:function declaration can only appear as a top-level element in a stylesheet module.

<xsl:transform 
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:str="http://example.com/namespace"
  version="3.0"
  exclude-result-prefixes="str"> 

<xsl:function name="str:reverse" as="string">
  <xsl:param name="sentence" as="string"/>
  <xsl:sequence  
     select="if (contains($sentence, ' '))
             then concat(str:reverse(substring-after($sentence, ' ')),
                         ' ',
                         substring-before($sentence, ' '))
             else $sentence"/>
</xsl:function>

<xsl:template match="/">
  <output>
    <xsl:value-of select="str:reverse('DOG BITES MAN')"/>
  </output>
</xsl:template>

</xsl:transform><xsl:transform 
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:str="http://example.com/namespace"
  version="3.0"
  expand-text="yes"
  exclude-result-prefixes="str"> 

<xsl:function name="str:reverse" as="string">
  <xsl:param name="sentence" as="string"/>
  <xsl:if test="contains($sentence, ' ')"
             then="str:reverse(substring-after($sentence, ' ')) ||
                         ' ' || substring-before($sentence, ' ')"
             else="$sentence"/>
</xsl:function>

<xsl:template match="/">
  <output>{str:reverse('DOG BITES MAN')}</output>
</xsl:template>

</xsl:transform><xsl:transform 
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:str="http://example.com/namespace"
  version="3.0"
  expand-text="yes"
  exclude-result-prefixes="str"> 

<xsl:function name="str:reverse" as="string">
  <xsl:param name="sentence" as="string"/>
  <xsl:sequencexsl:if  
      selecttest="if (contains($sentence, ' '))"
             then =concat"(str:reverse(substring-after($sentence, ' ')) ||
                         ' ' || substring-before($sentence, ' ')str:reverse"(substring-after($sentence, ' ')),
                         ' ',
                         substring-before($sentence, ' '))
             else ="$sentence"/>
</xsl:function>

<xsl:template match="/">
  <output>
    {<xsl:value-of select="str:reverse('DOG BITES MAN')"}/>
  </output>
</xsl:template>

</xsl:transform>

<xsl:function name="str:reverse" as="xs:string">
  <xsl:param name="sentence" as="string"/>
  <xsl:if test="contains($sentence, ' ')" 
             then="concat(str:reverse(substring-after($sentence, ' ')),
                                ' ',
                                substring-before($sentence, ' '))" 
             else="$sentence"/>
</xsl:function>

<xsl:function name="num:roman" as="xs:string">
  <xsl:param name="value" as="xs:integer"/>
  <xsl:number value="$value" format="i"/>
</xsl:function>

<xsl:function name="f:is-subordinate" as="xs:boolean">
    <xsl:param name="superior" 
               as="node()"/>
    <xsl:param name="subordinate" 
               as="node()"/>
    <xsl:param name="get-direct-children" 
               as="fn(node()) as node()*"/>
    <xsl:select>
               some $sub in $get-direct-children($superior) satisfies
                 ($sub is $subordinate or
                  f:is-subordinate($sub, $subordinate, 
                                      $get-direct-children))
    </xsl:select>                                   
</xsl:function>

<employee id="P57832" manager="P68951"/>

<xsl:function name="f:direct-reports" 
               as="element(employee)*">
    <xsl:param name="manager" as="element(employee)"/>
    <xsl:sequence select="$manager/../employee
                               [@manager = $manager/@id]"/>
</xsl:function>

f:is-subordinate($M, $E, f:direct-reports#1)

10.4 Static XPath Evaluation

The two instructions described in this section, xsl:sequence and xsl:select, can be used to evaluate XPath expressions that are statically known: that is, the XPath expressions are statically processed during the static processing of the stylesheet, and are dynamically evaluated during the dynamic evaluation of the stylesheet. The xsl:sequence instruction can also be used to evaluate a sequence constructor.

<xsl:select as="map(*)">
   {  "title"  : $title,
      "author" : $author
   }
</xsl:select>

<xsl:function name="f:book-to-json" as="map(*)">
   <xsl:param name="book" as="element(book)">            
   <xsl:select>
      {  "title"  : string($book/title),
         "isbn"   : string($book/isbn),
         "price"  : number($book/@price),
         "author" : array { $book/author ! string() },
         "date"   : current-date()"
      }
   </xsl:select>
</xsl:function>

14.4 Examples of Grouping

<cities>
  <city name="Milano"  country="Italia"      pop="5"/>
  <city name="Paris"   country="France"      pop="7"/>
  <city name="München" country="Deutschland" pop="4"/>
  <city name="Lyon"    country="France"      pop="2"/>
  <city name="Venezia" country="Italia"      pop="1"/>
</cities>

<table>
  <tr>
    <th>Position</th>
    <th>Country</th>
    <th>List of Cities</th>
    <th>Population</th>
  </tr>
  <tr>
    <td>1</td>
    <td>Italia</td>
    <td>Milano, Venezia</td>
    <td>6</td>
  </tr>
  <tr>
    <td>2</td>
    <td>France</td>
    <td>Lyon, Paris</td>
    <td>9</td>
  </tr>  
  <tr>
    <td>3</td>
    <td>Deutschland</td>
    <td>München</td>
    <td>4</td>
  </tr>  
</table>

<table xsl:version="3.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <tr>
    <th>Position</th>
    <th>Country</th>
    <th>City List</th>
    <th>Population</th>
  </tr>
  <xsl:for-each-group select="cities/city" group-by="@country">
    <tr>
      <td><xsl:value-of select="position()"/></td>
      <td><xsl:value-of select="current-grouping-key()"/></td>
      <td>
        <xsl:for-each select="current-group()/@name">
          <xsl:sort select="."/>
          <xsl:if test="position() ne 1">, </xsl:if>
          <xsl:value-of select="."/>
        </xsl:for-each>  
      </td>
      <td><xsl:value-of select="sum(current-group()/@pop)"/></td>
    </tr>
  </xsl:for-each-group>
</table><table xsl:version="3.0" xsl:expand-text="yes"
        xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <tr>
    <th>Position</th>
    <th>Country</th>
    <th>City List</th>
    <th>Population</th>
  </tr>
  <xsl:for-each-group select="cities/city" group-by="@country">
    <tr>
      <td>{position()}</td>
      <td>{current-grouping-key()}</td>
      <td>
        <xsl:for-each select="current-group()/@name">
          <xsl:sort select="."/>
          <xsl:if test="position() ne 1">, </xsl:if>
          {.}
        </xsl:for-each>  
      </td>
      <td>{sum(current-group()/@pop)}</td>
    </tr>
  </xsl:for-each-group>
</table><table xsl:version="3.0" xsl:expand-text="yes"
        xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <tr>
    <th>Position</th>
    <th>Country</th>
    <th>City List</th>
    <th>Population</th>
  </tr>
  <xsl:for-each-group select="cities/city" group-by="@country">
    <tr>
      <td>{<xsl:value-of select="position()"}/></td>
      <td>{<xsl:value-of select="current-grouping-key()"}/></td>
      <td>
        <xsl:for-each select="current-group()/@name">
          <xsl:sort select="."/>
          <xsl:if test="position() ne 1">, </xsl:if>
          <{xsl:value-of select="."}/>
        </xsl:for-each>  
      </td>
      <td>{<xsl:value-of select="sum(current-group()/@pop)"}/></td>
    </tr>
  </xsl:for-each-group>
</table>

<cities>
  <city name="Milano"  country="Italia"  year="1950"   pop="5.23"/>
  <city name="Milano"  country="Italia"  year="1960"   pop="5.29"/>  
  <city name="Padova"  country="Italia"  year="1950"   pop="0.69"/>
  <city name="Padova"  country="Italia"  year="1960"   pop="0.93"/>    
  <city name="Paris"   country="France"  year="1951"   pop="7.2"/>
  <city name="Paris"   country="France"  year="1961"   pop="7.6"/>
</cities>

<xsl:for-each-group select="cities/city" 
                    group-by="@name, @country" 
                    composite="yes">
  <p>
    <xsl:value-of select="current-grouping-key()[1] || ', ' ||
                          current-grouping-key()[2] || ': ' || 
                          avg(current-group()/@pop)"/>
  </p>
</xsl:for-each-group><xsl:for-each-group select="cities/city" 
                    group -by="@name, @country" 
                    composite="yes"
                    expand-text="yes">
  <p>{current-grouping-key()[1]}, {current-grouping-key()[2]}: {avg(current-group()/@pop)""<t>{current-grouping-key()[1]}, {current-grouping-key()[2]}: {avg(current-group()/@pop)"/>
  </p>
</xsl:for-each-group><xsl:for-each-group select="cities/city" 
                    group-bygroup -by="@@name, @countryname", 
                     composite@=country"yes" 
                    
                    compositeexpand-text="yes">
  <p>
    {<xsl:value-of select="current-grouping-key()[1] }||, '{, ' ||
                          current-grouping-key()[2] }||: '{avg(current-group()/@pop)": '" <t>||{ 
                          current-grouping-key()[1]}, {current-grouping-key()[2]}: {avg(current-group()/@pop)"/>/>
  </p>
</xsl:for-each-group>

<body>
  <h2>Introduction</h2>
  <p>XSLT is used to write stylesheets.</p>
  <p>XQuery is used to query XML databases.</p>
  <h2>What is a stylesheet?</h2>
  <p>A stylesheet is an XML document used to define a transformation.</p>
  <p>Stylesheets may be written in XSLT.</p>
  <p>XSLT 2.0 introduces new grouping constructs.</p>
</body>

<chapter>
  <section title="Introduction">
    <para>XSLT is used to write stylesheets.</para>
    <para>XQuery is used to query XML databases.</para>
  </section> 
  <section title="What is a stylesheet?">
    <para>A stylesheet is used to define a transformation.</para>
    <para>Stylesheets may be written in XSLT.</para>
    <para>XSLT 2.0 introduces new grouping constructs.</para>
  </section>
</chapter>

<xsl:template match="body">
  <chapter>
    <xsl:for-each-group select="*" group-starting-with="h2">
      <section title="{self::h2}">
        <xsl:for-each select="current-group()[self::p]">
          <para><xsl:value-of select="."/></para>
        </xsl:for-each> 
      </section>
    </xsl:for-each-group>
  </chapter>
</xsl:template>

<doc>
  <page continued="yes">Some text</page>
  <page continued="yes">More text</page>    
  <page>Yet more text</page>
  <page continued="yes">Some words</page>
  <page continued="yes">More words</page>    
  <page>Yet more words</page>        
</doc>

<doc>
  <pageset>
    <page>Some text</page>
    <page>More text</page>    
    <page>Yet more text</page>
  </pageset>
  <pageset>
    <page>Some words</page>
    <page>More words</page>    
    <page>Yet more words</page>
  </pageset>
</doc>

<xsl:template match="doc">
<doc>
  <xsl:for-each-group select="*" 
                      group-ending-with="page[not(@continued='yes')]">
    <pageset>
      <xsl:for-each select="current-group()">
        <page><xsl:value-of select="."/></page>
      </xsl:for-each> 
    </pageset>
  </xsl:for-each-group>
</doc>
</xsl:template>

<titles>
    <title>A Beginner's Guide to <ix>Java</ix></title>
    <title>Learning <ix>XML</ix></title>
    <title>Using <ix>XML</ix> with <ix>Java</ix></title>
</titles>

<h2>Java</h2>
    <p>A Beginner's Guide to Java</p>
    <p>Using XML with Java</p>
<h2>XML</h2>
    <p>Learning XML</p>
    <p>Using XML with Java</p>

<xsl:template match="titles">
    <xsl:for-each-group select="title" group-by="ix">
      <h2><xsl:value-of select="current-grouping-key()"/></h2>
      <xsl:for-each select="current-group()">
        <p><xsl:value-of select="."/></p>
      </xsl:for-each>
    </xsl:for-each-group>
</xsl:template>

<p>Do <em>not</em>:
    <ul>
    <li>talk,</li>
    <li>eat, or</li>
    <li>use your mobile telephone</li>
    </ul>
    while you are in the cinema.</p>

<p>Do <em>not</em>:</p>
    <ul>
    <li>talk,</li>
    <li>eat, or</li>
    <li>use your mobile telephone</li>
    </ul>
    <p>while you are in the cinema.</p>

<xsl:template match="p">
    <xsl:for-each-group select="node()" 
            group-adjacent="self::ul or self::ol">
        <xsl:choose>
            <xsl:when test="current-grouping-key()">
                <xsl:copy-of select="current-group()"/>  
            </xsl:when>
            <xsl:otherwise>
                <p>
                    <xsl:copy-of select="current-group()"/>
                </p>
            </xsl:otherwise>  
        </xsl:choose>
    </xsl:for-each-group>
</xsl:template>

{
   "Africa/Abidjan": { "offset": "+00:00", "DST-offset": "+00:00" },
   "Africa/Algiers": { "offset": "+01:00", "DST-offset": "+01:00" },
   "Africa/Nairobi": { "offset": "+03:00", "DST-offset": "+03:00" },
   "America/Anchorage": { "offset": "-09:00", "DST-offset": "-08:00" },
   "America/Los_Angeles": { "offset": "-08:00", "DST-offset": "-07:00" },
   "Asia/Dubai": { "offset": "+04:00", "DST-offset": "+04:00" },
   "Asia/Kolkata": { "offset": "+05:30", "DST-offset": "+05:30" }                 
}

{
  "Africa": {
    "Abidjan": { "offset": "+00:00", "DST-offset": "+00:00" },
    "Algiers": { "offset": "+01:00", "DST-offset": "+01:00" },
    "Nairobi": { "offset": "+03:00", "DST-offset": "+03:00" }
  },
  "America": {
    "Anchorage": { "offset": "-09:00", "DST-offset": "-08:00" },
    "Los_Angeles": { "offset": "-08:00", "DST-offset": "-07:00" }
  },
  "Asia": {
    "Dubai": { "offset": "+04:00", "DST-offset": "+04:00" },
    "Kolkata": { "offset": "+05:30", "DST-offset": "+05:30" }
  }
}

<xsl:map>
   <xsl:for-each-group select="json-doc('tz.json') => map:pairs()" 
                       group-by="substring-before(?key, '/')">
     <xsl:map-entry key="current-grouping-key()">
       <xsl:map>
         <xsl:for-each select="current-group()">
           <xsl:map-entry key="substring-after(?key, '/')" select="?value"/>
         </xsl:for-each>
       </xsl:map>
     </xsl:map-entry>
   </xsl:for-each-group>
</xsl:map>

<xsl:variable name="ages" as="xs:integer*" select="5, 24, 9, 5, 6, 8, 36, 38, 28">

map { 1 : (5, 9, 5, 6, 8), 2 : (24), 3 : (36, 38), 4 : (28)}

<xsl:map>
  <xsl:for-each-group select="$ages" merge-when="function($a, $b){abs($a - $b) le 2}">
    <xsl:map-entry key="position()" select="current-group()"/>
  </xsl:for-each-group>
</xsl:map>

<body type="source">
  <div ref="7a1">[text]</div>
  <div ref="7a2">[text]</div>
  <div ref="7a3">[text]</div>
  <div ref="7a4">[text]</div>
  <!-- . . . -->
</body>

<body type="commentary">
  <div ref="7a1 7a2">[commentary A]</div>
  <!-- . . . -->
</body>

<body type="commentary">
  <div ref="7a2 7a3">[commentary B]</div>
  <!-- . . . -->
</body>

<body type="gloss">
  <div ref="7a1">[gloss A]</div>
  <!-- . . . -->
</body>

<body type="gloss">
  <div ref="7a4">[gloss B]</div>
  <!-- . . . -->
</body>

<div class="edition">
  <div class="text-cluster">
    <div class="ref">7a1</div>
    <div class="ref">7a2</div>
    <div class="ref">7a3</div>
    <div class="source">[text]</div>
    <div class="commentary">[commentary A]</div>
    <div class="commentary">[commentary B]</div>
    <div class="gloss">[gloss A]</div>
  </div>
  <div class="text-cluster">
    <div class="ref">7a4</div>
    <div class="source">[text]</div>
    <div class="gloss">[gloss B]</div>
  </div>
</div>

<xsl:template match="html:div[@class eq 'edition']" mode="collate-versions">
  <xsl:copy>
    <xsl:copy-of select="@*"/>
    <xsl:for-each-group select="$versions//body/div" merge-when="function($a, $b){tokenize($a/@ref) = tokenize($b/@ref)}">
      <div class="text-cluster">
        <xsl:for-each select="distinct-values(current-group() ! tokenize(@ref))">
          <div class="ref">
            <xsl:value-of select="."/>
          </div>
        </xsl:for-each>
        <xsl:for-each-group select="current-group()" group-by="../@type">
          <div>
            <xsl:attribute name="class" select="current-grouping-key()"/>
            <xsl:apply-templates mode="#current"/>
          </div>
        </xsl:for-each-group> 
      </div>
    </xsl:for-each-group>
  </xsl:copy>
</xsl:template>

18.2 Accumulators

Accumulators are introduced in XSLT 3.0 to enable data that is read during streamed processing of a document to be accumulated, processed or retained for later use. However, they may equally be used with non-streamed processing.

[Definition: An accumulator defines a series of values associated with the nodes of the tree. If an accumulator is applicable to a particular tree, then for each node in the tree, other than attribute and namespace nodes, there will be two values available, called the pre-descent and post-descent values. These two values are available via a pair of functions, accumulator-before and accumulator-after.]

There are two ways the values of an accumulator can be established for a given tree: they can be computed by evaluating the rules appearing in the xsl:accumulator declaration, or they can be copied from the corresponding nodes in a different tree. The second approach (copying the values) is available via the snapshot and copy-of functions, or by use of the xsl:copy-of instruction specifying copy-accumulators="yes". Accumulator values are also copied during the implicit invocation of the snapshot function performed by the xsl:merge instruction.

The following sections give first, the syntax rules for defining an accumulator; then an informal description of the semantics; then a more formal definition; and finally, examples. But to illustrate the concept intuitively, the following simple example shows how an accumulator can be used for numbering of nodes:

<xsl:accumulator name="figNr" as="xs:integer" 
                    initial-value="0" streamable="yes">
     <xsl:accumulator-rule match="chapter" select="0"/>
     <xsl:accumulator-rule match="figure" select="$value + 1"/>
   </xsl:accumulator>
   
   <xsl:mode streamable="yes"/>
   <xsl:template match="figure">
     <xsl:apply-templates/>
     <p>Figure <xsl:value-of select="accumulator-before('figNr')"/></p>
   </xsl:template><xsl:accumulator name="figNr" as="xs:integer" 
                    initial-value="0" streamable="yes">
     <xsl:accumulator-rule match="chapter" select="0"/>
     <xsl:accumulator-rule match="figure" select="$value + 1"/>
</xsl:accumulator>
   
<xsl:mode streamable="yes"/>
<xsl:template match="figure" expand-text="yes">
     <xsl:apply-templates/>
     <p>Figure {accumulator-before('figNr')}</p>
</xsl:template><xsl:accumulator name="figNr" as="xs:integer" 
                    initial-value="0" streamable="yes">
     <xsl:accumulator-rule match="chapter" select="0"/>
     <xsl:accumulator-rule match="figure" select="$value + 1"/>
   
</xsl:accumulator>
   
   
   
<xsl:mode streamable="yes"/>
   
<xsl:template match="figure" expand-text="yes">
     <xsl:apply-templates/>
     <p>Figure <{xsl:value-of select="accumulator-before('figNr')"}/></p>
   
</xsl:template>

<xsl:accumulator name="firstTitle" as="xs:string?" initial-value="()" 
                                                     streamable="yes">
    <xsl:accumulator-rule match="/html/head/title/text()" select="string(.)"/>
  </xsl:accumulator>

<xsl:template match="h1">
    <xsl:variable name="firstTitle" select="accumulator-before('firstTitle')"/>
    <xsl:variable name="thisTitle" select="string(.)"/>
    <xsl:if test="$thisTitle ne $firstTitle">
      <div class="heading-1"><xsl:value-of select="$thisTitle"/></div>
    </xsl:if>
    </xsl:template>

<xsl:accumulator name="word-count" 
                   as="xs:integer" 
                   initial-value="0">
    <xsl:accumulator-rule match="text()" 
         select="$value + count(tokenize(.))"/>
  </xsl:accumulator>

<xsl:template match="/">
     <xsl:apply-templates/>
     <p>Word count: <xsl:value-of select="accumulator-after('word-count')"/></p>
   </xsl:template>

<xsl:accumulator name="section-nr" as="xs:integer*" 
                 initial-value="0">
  <xsl:accumulator-rule match="section" phase="start" 
                 select="0, head($value)+1, tail($value)"/>
  <xsl:accumulator-rule match="section" phase="end" 
                 select="tail($value) (:pop:)"/>
</xsl:accumulator>