XSL Transformations (XSLT) Version 4.0

6.6 Default Priority for Template Rules

[Definition: If no priority attribute is specified on an xsl:template element, a default priority is computed, based on the syntax of the pattern supplied in the match attribute.] The rules are as follows.

1. If the top-level pattern is a ParenthesizedExprP then the outer parentheses are effectively stripped; these rules are applied recursively to the UnionExprP contained in the ParenthesizedExprP.

2. If the top-level pattern is a UnionExprP consisting of multiple alternatives separated by | or union, then the template rule is treated equivalently to a set of template rules, one for each alternative. For example, a rule with match="a|b" is treated as if there were one rule with match="a" and another with match="b". These template rules are adjacent to each other in declaration order, and the declaration order within this set of template rules (which affects the result of xsl:next-match if the alternatives have the same default priority) is the order of alternatives in the UnionExprP.

   Similarly:

   • If the top-level pattern takes the form of a UnionNodeTest^XP preceded by an axis name or abbreviation, it is treated equivalently to a set of template rules, one for each alternative. For example, a rule with match="@(a|b)" is treated as if there were one rule with match="@a" and another with match="@b".

   • If the top-level pattern takes the form of an ElementTest^XP or AttributeTest^XP containing a NameTestUnion^XP with multiple alternatives, optionally preceded by a ForwardAxisP, it is treated equivalently to a set of template rules, one for each alternative. For example, a rule with match="element(a|b)" is treated as if there were one rule with match="element(a)" and another with match="element(b)", while a rule with match="attribute(a|b, xs:integer)" is treated as a pair of rules specifying match="attribute(a, xs:integer)" and match="attribute(b, xs:integer)" respectively

   If the top-level pattern is a UnionExprP consisting of multiple alternatives separated by | or union, then the default priority is the maximum of the default priorities of the alternatives.

   Note:

   The splitting of a template rule into multiple rules occurs only if there is no explicit priority attribute.

   Splitting the template rule has two effects: firstly, the two match patterns may have different default priority. Secondly, an xsl:next-match instruction within the template body may result in the other template rule being invoked.

   In practice, this means that the splitting has no effect if (a) the alternatives have the same default priority, and (b) the alternatives are disjoint — which is the case for some of the examples given above.

   This is a backwards incompatible change from XSLT 3.0 and earlier versions, which treated the template rule as equivalent to multiple template rules with different priorities.

   The change is made because of the increasing complexity of extending the rule to patterns like @(a|b), or attribute(a|b, xs:integer) which are defined to be semantically identical to equivalent union patterns; and to prevent confusion with type patterns such as type(element(a)|element(b)), where different rules apply.

   The change affects any template rule with a union pattern that (a) has no explicit priority attribute, and (b) has multiple branches with different default priority. It is recommended that processors should output a compatibility warning when such template rules are encountered.

   The change has two effects. Firstly, if two alternatives in a union pattern have different priority (for example in a pattern such as a | b/c, the priority of one of the branches will be raised to that of the other branch. Secondly, in cases where the same item matches both branches, a call on xsl:next-match will never cause the same template rule to be evaluated repeatedly.

3. If the top-level pattern is an IntersectExceptExprP containing two or more PathExprP operands separated by intersect or except operators, then the priority of the pattern is that of the first PathExprP.

4. If the pattern is a PredicatePattern then its priority is 1 (one), unless there are no predicates, in which case the priority is −1 (minus one).

5. If the pattern is a PathExprP taking the form /, then the priority is −0.5 (minus 0.5).

6. If the pattern is a PathExprP taking the form of an EQName optionally preceded by a ForwardAxisP or has the form processing-instruction(StringLiteral^XP) or processing-instruction(NCName^Names) optionally preceded by a ForwardAxisP, then the priority is 0 (zero).

7. If the pattern is a PathExprP taking the form of an ElementTest^XP or AttributeTest^XP, optionally preceded by a ForwardAxisP, then the priority is as shown in the table below. In this table:

   • The symbols E, A, and T represent an arbitrary element name, attribute name, and type name respectively;

   • The symbol W represents a Wildcard^XP other than * (for example prefix:* or *:local);

   • The symbol * represents itself.

   The presence or absence of the symbol ? following a type name does not affect the priority.

   Default Priority of Patterns

   Format	Priority	Notes
   element()	−0.5	(equivalent to *)
   element(*)	−0.5	(equivalent to *)
   attribute()	−0.5	(equivalent to @*)
   attribute(*)	−0.5	(equivalent to @*)
   element(W)	−0.25
   attribute(W)	−0.25
   element(E)	0	(equivalent to E)
   element(*,T)	0	(matches by type only)
   attribute(A)	0	(equivalent to @A)
   attribute(*,T)	0	(matches by type only)
   element(W,T)	0.125
   element(E,T)	0.25	(matches by name and type)
   schema-element(E)	0.25	(matches by substitution group and type)
   attribute(W,T)	0.125
   attribute(A,T)	0.25	(matches by name and type)
   schema-attribute(A)	0.25	(matches by name and type)

8. If the pattern is a PathExprP taking the form of a DocumentTest^XP, then if it includes no ElementTest^XP or SchemaElementTest^XP the priority is −0.5. If it does include an ElementTest^XP or SchemaElementTest^XP, then the priority is the same as the priority of that ElementTest^XP or SchemaElementTest^XP, computed according to the table above.

9. If the pattern is a PathExprP taking the form of an NCName^Names:*, BracedURILiteral^XP*, or *:NCName^Names, optionally preceded by a ForwardAxisP, then the priority is −0.25. [XSLT 3.0 Erratum E37, bug 30375].

10. If the pattern is a PathExprP taking the form of any other NodeTest^XP, optionally preceded by a ForwardAxisP, then the priority is −0.5.

11. If the pattern is a TypePattern, then the priority is 0 (zero).

12. In all other cases, the priority is +0.5.

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:

  As explained in 6.5 Conflict Resolution for Template Rules, a template rule with no priority attribute, whose match pattern contains multiple alternatives separated by |, is treated equivalently to a set of template rules, one for each alternative. This means that where the same item matches more than one alternative, it is possible for an xsl:next-match instruction to cause the current template rule to be invoked recursively. This situation does not occur when the template rule has an explicit priority.

  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, with the values of parameters being set using the child xsl:with-param elements as described in 9.10 Setting Parameter Values. 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).

An xsl:apply-imports or xsl:next-match instruction may use xsl:with-param child elements to pass parameters to the chosen template rule (see 9.10 Setting Parameter Values). It also passes on any tunnel parameters as described in 10.1.6 Tunnel Parameters.

[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 processor, but can be used to define fallback behavior when the stylesheet is processed by an XSLT 1.0 processor with forwards compatible behavior.