XSL Transformations (XSLT) Version 4.0

5.5 Named Types

XSLT 4.0 introduces two new and closely-related constructs allowing item types to be given names, and to be referred to by name anywhere that item types are used, for example in function declarations and variable declarations.

The xsl:item-type declaration allows any item type to be given a name. It is particularly useful to avoid repetitive use of the same choice types, enumeration types, or function types, and means that if the definition changes, the change only needs to be made in one place.

The xsl:record-type declaration takes this a step further. Like xsl:item-type, it allows a name to be given to any record type. In addition, though, it offers two further capabilities:

• Named record types can be recursive, allowing definitions of recursive data structures such as lists and trees.

• Declaring a named record type automatically establishes a constructor function for records of that type; the constructor function has the same name as the record type itself.

<xsl:record-type name="cx:complex">
    <xsl:field name="r" as="xs:double"/>
    <xsl:field name="i" as="xs:double"/>
</xsl:record-type>
   
<xsl:variable name="i" as="cx:complex" select="cx:complex(0, 1)"/>
   
<xsl:function name="cx:add" as="cx:complex">
  <xsl:param name="x" as="cx:complex"/>
  <xsl:param name="y" as="cx:complex"/>
  <xsl:sequence select="cx:complex($x?r + $y?r, $x?i + $y?i)"/>
</xsl:function>

<xsl:template match="xsl:record-type" expand-text="yes">
   <t:item-type name="{@name}"
                visibility="{@visibility otherwise 'private'}">
     <xsl:attribute name="as">
        <xsl:text>record(</xsl:text>
        <xsl:for-each select="xsl:field" separator=", ">
           <xsl:variable name="optional"
                         as="xs:boolean"
                         select="normalize-space(@required) = ('no','false','0')"/>
           {@name}{'?'[$optional]} as {@as otherwise 'item()*'}
        </xsl:for-each>
        <xsl:if test="normalize-space(@extensible) = ('yes','true','1')">
           <xsl:text>, *</xsl:text>
        </xsl:if>
        <xsl:text>)</xsl:text>
      </xsl:attribute>  
   </t:item-type>
</xsl:template>

<xsl:record-type name="cx:complex" extensible="yes">
    <xsl:field name="r" as="xs:double"/>
    <xsl:field name="i" as="xs:double" required="no" default="0"/>
</xsl:record-type>

<xsl:item-type name="cx:complex"
       as="record(r as xs:double, i? as xs:double, *)"/>

<xsl:template match="xsl:record-type">
    <t:function name="{@name}"
                as="{@name}"
                visibility="{(@visibility otherwise 'private')}">
                
      <!-- if the record type is extensible, choose a name for the options parameter -->
      <xsl:variable name="options-param" as="xs:string?">
         <xsl:if test="normalize-space(@extensible) = ('yes', 'true', 'a')"
                 then="('options', (1 to count(xsl:field)) ! `options{.}`)
                         [not(. = current()/xsl:field/@name)][1]"/>
      </xsl:variable>                   
      
      <!-- declare the parameters -->
      <xsl:for-each select="xsl:field">
         <t:param name="{@name}"
                  required="{@required otherwise 'yes'}">
            <xsl:attribute name="as">
               <xsl:variable name="as" 
                             select="normalize-space(@as otherwise 'item()*')"/>
               <xsl:variable name="optional" 
                             select="normalize-space(@required) = ('no', 'false', '0')"/>
               <xsl:choose>
                  <xsl:when test="not($optional)" select="$as"/>
                  <!-- for optional fields, amend the required type to allow () -->
                  <xsl:when test="matches($as, '[?*]$')" select="$as"/>
                  <xsl:when test="matches($as, '\+$')" select="replace($as, '\+$', '*')"/>
                  <xsl:otherwise select="$as || '?'"/>
               </xsl:choose>
            </xsl:attribute>
            <xsl:if test="@default">
               <xsl:attribute name="select" select="@default"/>
            </xsl:if>   
         </t:param>
      </xsl:for-each>
      
      <!-- for an extensible record type, declare the options parameter -->
      <xsl:if test="exists($options-param)">
         <t:param name="{$options-param}" as="map(*)" required="no" select="{}"/>
      </xsl:if>           
      
      <!-- function body: construct a map -->
      <t:map duplicates="fn($first, $second){{$first}}">
         <xsl:for-each select="xsl:field">
            <xsl:variable name="optional" 
                          select="normalize-space(@required) = ('no', 'false', '0')"/>
            <xsl:choose>
              <xsl:when test="$optional and not(@default)">
                 <!-- omit map entries for optional fields if no value is supplied -->
                 <t:if test="exists(${@name})">
                    <t:map-entry key="'{@name}'" select="${@name}"/>
                 </t:if>
              </xsl:when>
              <xsl:otherwise>
                <t:map-entry key="'{@name}'" select="${@name}"/>
              </xsl:otherwise>  
            </xsl:choose>  
         </xsl:for-each>
        
         <!-- if the record type is extensible, 
              add entries from the options parameter -->
              
         <xsl:if test="exists($options-param)">
            <t:sequence select="${$options-param}"/>
         </xsl:if>   

      </t:map>
    </t:function>          
</xsl:template>

<xsl:record-type name="cx:complex">
    <xsl:field name="r" as="xs:double"/>
    <xsl:field name="i" as="xs:double" required="no" default="0"/>
</xsl:record-type>

<xsl:function name="cx:complex" as="cx:complex" visibility="private">
    <xsl:param name="r" as="xs:double"/>
    <xsl:param name="i" as="xs:double" required="no" select="0"/>
    <xsl:map>
       <xsl:map-entry key="'r'" select="$r"/>
       <xsl:map-entry key="'i'" select="$i"/>
    </xsl:map>
</xsl:function>

<xsl:record-type name="cx:complex" visibility="public">
    <xsl:field name="r" as="xs:double"/>
    <xsl:field name="i" as="xs:double" required="no"/>
</xsl:record-type>

<xsl:function name="cx:complex" as="cx:complex" visibility="public">
    <xsl:param name="r" as="xs:double"/>
    <xsl:param name="i" as="xs:double?" required="no"/>
    <xsl:map>
       <xsl:map-entry key="'r'" select="$r"/>
       <xsl:if test="exists($i)">
          <xsl:map-entry key="'i'" select="$i"/>
       </xsl:if>   
    </xsl:map>
</xsl:function>

<xsl:record-type name="cx:complex" extensible="yes">
    <xsl:field name="r" as="xs:double"/>
    <xsl:field name="i" as="xs:double"/>
</xsl:record-type>

<xsl:function name="cx:complex" as="cx:complex" visibility="private">
    <xsl:param name="r" as="xs:double"/>
    <xsl:param name="i" as="xs:double"/>
    <xsl:param name="options" as="map(*)" required="no" default="{}"/>
    <xsl:map duplicates="fn($first, $second){$first}">
       <xsl:map-entry key="'r'" select="$r"/>
       <xsl:map-entry key="'i'" select="$i"/>
       <xsl:sequence select="$options"/>   
    </xsl:map>
</xsl:function>

<xsl:record-type name="my:binary-tree">
   <xsl:field name="left" as="my:binary-tree?"/>
   <xsl:field name="payload" as="item()*"/>
   <xsl:field name="right" as="my:binary-tree?"/>
   <xsl:field name="depth" as="fn(my:binary-tree) as xs:integer"
      default="fn() {1 + max((?left?depth(), ?right?depth())) otherwise 0)}"/>
</xsl:record-type><xsl:record-type name="my:binary-tree">
   <xsl:field name="left" as="my:binary-tree?"/>
   <xsl:field name="payload" as="item()*"/>
   <xsl:field name="right" as="my:binary-tree?"/>
   <xsl:field name="depth" as="fn(my:binary-tree) as xs:integer"
      default="fn() {1 + max((?left =?> depth(), ?right =?> depth())) otherwise 0)}"/>
</xsl:record-type><xsl:record-type name="my:binary-tree">
   <xsl:field name="left" as="my:binary-tree?"/>
   <xsl:field name="payload" as="item()*"/>
   <xsl:field name="right" as="my:binary-tree?"/>
   <xsl:field name="depth" as="fn(my:binary-tree) as xs:integer"
      default="fn() {1 + max((?left =?> depth(), ?right =?> depth())) otherwise 0)}"/>
</xsl:record-type>

let $tree := my:binary-tree(
               my:binary-tree((), 17, ()),
               18,
               my:binary-tree((), 19, 
                 my:binary-tree((), 20, ())))
return $tree?depth()

let $tree := my:binary-tree(
               my:binary-tree((), 17, ()),
               18,
               my:binary-tree((), 19, 
                 my:binary-tree((), 20, ())))
return $tree =?> depth()

6.9 Overriding Template Rules

<!-- Category: instruction -->
<xsl:apply-imports>
  <!-- Content: xsl:with-param* -->
</xsl:apply-imports>

<!-- Category: instruction -->
<xsl:next-match>
  <!-- Content: (xsl:with-param | xsl:fallback)* -->
</xsl:next-match>

A template rule that is being used to override another template rule (see 6.5 Conflict Resolution for Template Rules) can use the xsl:apply-imports or xsl:next-match instruction to invoke the overridden template rule. The xsl:apply-imports instruction only considers template rules in imported stylesheet modules; the xsl:next-match instruction considers all template rules that have not already been used. Both instructions will invoke the built-in template rule for the context item (see 6.8 Built-in Template Rules) if no other template rule is found.

[Definition: At any point in the processing of a stylesheet, there may be a current template rule. Whenever a template rule is chosen as a result of evaluating xsl:apply-templates, xsl:apply-imports, or xsl:next-match, the template rule becomes the current template rule for the evaluation of the rule’s sequence constructor.]

The current template rule is cleared (becomes absent) by any instruction that evaluates an operand with changed focus. It is therefore cleared when evaluating instructions contained within:

• xsl:for-each

• xsl:for-each-group

• xsl:analyze-string

• xsl:iterate

• xsl:source-document

• xsl:merge

• xsl:sort

• xsl:key

• xsl:copy if and only if there is a select attribute

• A global xsl:variable or xsl:param

• xsl:function

• xsl:template if and only if the called template specifies <xsl:context-item use="absent"/>

These rules ensure that when xsl:apply-imports or xsl:next-match is called, the context item is the same as when the current template rule was invoked.

Both xsl:apply-imports and xsl:next-match search for a template rule that matches the context item, and that is applicable to the current mode (see 6.7 Modes). In choosing a template rule, they use the usual criteria such as the priority and import precedence of the template rules, but they consider as candidates only a subset of the template rules in the stylesheet. This subset differs between the two instructions:

• The xsl:apply-imports instruction considers as candidates only those template rules contained in stylesheet levels that are descendants in the import tree of the stylesheet level that contains the current template rule.

  Note:

  This is not the same as saying that the search considers all template rules whose import precedence is lower than that of the current template rule.

  [ERR XTSE3460] It is a static error if an xsl:apply-imports element appears in a template rule declared within an xsl:override element. (To invoke the template rule that is being overridden, xsl:next-match should therefore be used.)

• The xsl:next-match instruction considers as candidates all those template rules that come after the current template rule in the ordering of template rules implied by the conflict resolution rules given in 6.5 Conflict Resolution for Template Rules.

  This process could be implemented by the following algorithm:

  1. Set a flag active to false.

  2. Follow the rules in 6.5 Conflict Resolution for Template Rules to find the best matching rule, without raising any errors or warnings if there are multiple matches.

  3. If the template rule identified is the current template rule, discard this rule, and repeat the process from step 2 with the flag active set to true.

  4. Otherwise, if active is set to false, discard this rule, and repeat the process from step 2, with the flag active still set to false

  5. Otherwise (if active is set to true) use the selected rule.

  Note:

  An alternative implementation would be to maintain, not just the current template rule, but a list of rules that have been used to process the context item. The implementation of xsl:next-match can then eliminate these rules from the search.

  In the absence of type patterns, it is possible to define a total ordering of template rules for each mode, and to exclude those rules that appear before the current template rule in this ordering. The introduction of type patterns makes this approach more challenging, since types are partially ordered.

  Note:

  Because a template rule declared as a child of xsl:override has higher precedence than any template rule declared in the used package (see 3.5.4 Overriding Template Rules from a Used Package), the effect of xsl:next-match within such a template rule is to consider as candidates first any other template rules for the same mode within the same xsl:use-package element (taking into account explicit and implicit priority, and document order, in the usual way), and then all template rules in the used package.

If no matching template rule is found, both xsl:apply-imports and xsl:next-match cause the built-in template rule for the mode to be invoked.

If multiple matching template rules with the same explicit or implicit priority are found, both xsl:apply-imports and xsl:next-match respect the on-multiple-match and warning-on-multiple-match attributes of the mode declaration.

If a matching template rule R is found, then the result of the xsl:next-match or xsl:apply-imports instruction is the result of invoking R. The parameters that are passed to R are as follows:

• All parameters explicitly set using xsl:with-param child elements (see 9.10 Setting Parameter Values).

• If the effective version of the xsl:next-match or xsl:apply-imports instruction is 4.0 or greater, then all non-tunnel parameters that were supplied in the invocation of the current template rule, excluding any whose names match the names of parameters appearing in child xsl:with-param elements.

• All tunnel parameters as described in 10.1.6 Tunnel Parameters.

The template rule R is evaluated with the same focus as the xsl:next-match or xsl:apply-imports instruction. The current template rule changes to be R. The current mode does not change.

If no matching template rule is found that satisfies these criteria, the built-in template rule for the context item is used (see 6.8 Built-in Template Rules).

[ERR XTDE0560] It is a dynamic error if xsl:apply-imports or xsl:next-match is evaluated when the current template rule is absent.

<xsl:template match="example">
  <pre><xsl:apply-templates/></pre>
</xsl:template>

<xsl:import href="doc.xsl"/>

<xsl:template match="example">
  <div style="border: solid red">
     <xsl:apply-imports/>
  </div>
</xsl:template>

<div style="border: solid red"><pre>...</pre></div>

An xsl:fallback instruction appearing as a child of an xsl:next-match instruction is ignored by an XSLT 2.0 or 3.0, 3.0, or 4.0 processor, but can be used to define fallback behavior when the stylesheet is processed by an XSLT 1.0 processor with forwards compatible behavior.

<phrase upper-case="true" italic="true" bold="false" underscore="true">Hannover</phrase>

<italic><underscore>HANNOVER</underscore></italic>

<xsl:template match="phrase" priority="10">
  <xsl:next-match>
     <xsl:with-param name="upper-case" select="xs:boolean(@upper-case)"/>
  </xsl:next-match>
</xsl:template>  

<xsl:template match="phrase[xs:boolean(@italic)]" priority="8">
  <italic>
    <xsl:next-match/>
  </italic>
</xsl:template>

<xsl:template match="phrase[xs:boolean(@bold)]" priority="6">
  <bold>
    <xsl:next-match/>
  </bold>
</xsl:template>

<xsl:template match="phrase[xs:boolean(@underscore)]" priority="4">
  <underscore>
    <xsl:next-match/>
  </underscore>
</xsl:template>

<xsl:template match="phrase" priority="2">
  <xsl:param name="upper-case" as="xs:boolean?"/>
  <xsl:if test="$upper-case" then="upper-case(.)" else="string(.)"/>
</xsl:template>