XSL Transformations (XSLT) Version 2.0

1.1 What is XSLT?

This specification defines the syntax and semantics of the XSLT 2.0 language. A transformation in the XSLT language is expressed in the form of a stylesheet, whose syntax is well-formed XML [XML 1.0] conforming to the Namespaces in XML Recommendation [XML Namespaces 1.0]. A stylesheet generally includes elements that are defined by XSLT as well as elements that are not defined by XSLT. XSLT-defined elements are distinguished by use of the namespace http://www.w3.org/1999/XSL/Transform (see 3.1 XSLT Namespace), which is referred to in this specification as the XSLT namespace. Thus this specification is a definition of the syntax and semantics of the XSLT namespace.

The term stylesheet reflects the fact that one of the important roles of XSLT is to add styling information to an XML source document, by transforming it into a document consisting of XSL formatting objects (see [XSL Formatting Objects]), or into another presentation-oriented format such as HTML, XHTML, or SVG. However, XSLT is used for a wide range of XML-to-XML transformation tasks, not exclusively for formatting and presentation applications.

A transformation expressed in XSLT describes rules for transforming one or more source trees into one or more result trees. The transformation is achieved by a set of template rules. A template rule associates a pattern, which matches nodes in the source document, with a sequence constructor, which can be evaluated to produce part of a result tree. The structure of the result trees can be completely different from the structure of the source trees. In constructing a result tree, nodes from the source trees can be filtered and reordered, and arbitrary structure can be added. This mechanism allows a stylesheet to be applicable to a wide class of documents that have similar source tree structures.

A stylesheet may consist of several stylesheet modules, contained in different XML documents. For a given transformation, one of these functions as the principal stylesheet module. The complete stylesheet is assembled by finding the stylesheet modules referenced directly or indirectly from the principal stylesheet module using xsl:include and xsl:import elements: see 3.8.1 Stylesheet Inclusion and 3.8.2 Stylesheet Import .

1.2 What's new in XSLT 2.0?

XSLT 1.0 was published in November 1999, and version 2.0 represents a significant increase in the capability of the language. A detailed list of changes is included in K Changes from XSLT 1.0. XSLT 2.0 has been developed in parallel with XPath 2.0 (see [XPath 2.0]), so the changes to XPath must be considered alongside the changes to XSLT.

2.1 Terminology

For a full glossary of terms, see B Glossary.

The software responsible for transforming source trees into a result trees is referred to as the processor. This is sometimes expanded to XSLT processor to avoid any confusion with other processors, for example an XML processor. A specific product that performs the functions of an XSLT processor is referred to as an implementation .

Note:

The precise meanings of the terms source tree and result tree, as used in this specification, depend on the context. In the context of the stylesheet as a whole, the source trees are the trees provided as the initial input to the transformation, together with any trees supplied as stylesheet parameters and any trees accessed using the document, doc or collection functions; while the result trees are the trees created by an explicit xsl:result-document instruction as well as the implicit result tree created in the absence of an xsl:result-document instruction. In the context of an individual instruction in the stylesheet, the term source tree also includes any temporary tree that the instruction is using for input, and the term result tree includes any temporary tree that the instruction is using for output.

In this specification the words must, must not, should, should not, may, required, and recommended are to be interpreted as described in [RFC2119]. Where the word must relates to the behavior of the XSLT processor, then an implementation is not conformant unless it behaves as specified, subject to the more detailed rules in 21 Conformance. Where the word must relates to a stylesheet, then the processor must enforce this constraint on stylesheets.

In this specification, the term implementation-defined refers to a feature where the implementation is allowed some flexibility, and where the choices made by the implementation should be described in the vendor's documentation.

The term implementation-dependent refers to a feature where the behavior may vary from one implementation to another, and where the vendor is not expected to provide a full specification of the behavior. (This might apply, for example, to limits on the size of source documents that can be transformed.)

In all cases where this specification leaves the behavior implementation-defined or implementation-dependent, the implementation has the option of providing mechanisms that allow the user to influence the behavior.

Paragraphs labeled as Notes or described as examples are non-normative.

Many terms used in this document are defined in the XPath specification [XPath 2.0] or the Data Model specification [Data Model]. Particular attention is drawn to the following:

• The term atomization is defined in [XPath 2.0]. It is a process that takes as input a sequence of nodes and atomic values, and returns a sequence of atomic values, in which the nodes are replaced by their typed values as defined in [Data Model]. For some nodes (for example, elements with element content), atomization generates a dynamic error.

• The term string value is defined in [Data Model]. Every node has a string value. For example, the string value of an element is the concatenation of the string values of all its descendant text nodes.

2.2 Notation

In this document the specification of each XSLT-defined element type is preceded by a summary of its syntax in the form of a model for elements of that element type. A full list of all these specifications can be found in C Element Syntax Summary. The meaning of syntax summary notation is as follows:

• An attribute is required if and only if its name is in bold.

• The string that occurs in the place of an attribute value specifies the allowed values of the attribute. If this is surrounded by curly braces, then the attribute value is treated as an attribute value template, and the string occurring within curly braces specifies the allowed values of the result of evaluating the attribute value template. Alternative allowed values are separated by |. A quoted string indicates a value equal to that specific string. An unquoted, italicized name specifies a particular type of value.

  In all cases where this specification limits the set of values that an attribute may take, leading and trailing whitespace in the attribute value is ignored. In the case of an attribute value template, this applies to the effective value obtained when the attribute value template is expanded.

• Unless the element is required to be empty, the model element contains a comment specifying the allowed content. The allowed content is specified in a similar way to an element type declaration in XML; sequence constructor means that any mixture of text nodes, literal result elements, extension instructions, and XSLT elements from the instruction category is allowed; other-declarations means that any mixture of XSLT elements from the declaration category, other than xsl:import, is allowed, together with user-defined data elements.

• The element is prefaced by comments indicating if it belongs to the instruction category or declaration category or both. The category of an element only affects whether it is allowed in the content of elements that allow a sequence constructor or other-declarations.

[ERR001] A static error is signaled if an XSLT-defined element is used in a context where it is not permitted, if a required attribute is omitted, or if the content of the element does not correspond to the content that is allowed for the element.

Attributes are validated as follows. These rules apply to the value of the attribute after removing leading and trailing whitespace.

• [ERR002] It is a static error if an attribute (other than an attribute written using curly braces in a position where an attribute value template is permitted) contains a value that is not one of the permitted values for that attribute.

• [ERR003] It is a dynamic error if the effective value of an attribute written using curly braces, in a position where an attribute value template is permitted, is a value that is not one of the permitted values for that attribute.

Special rules apply if the construct appears in part of the stylesheet that is processed with forwards-compatible behavior: see 3.7 Forwards-Compatible Processing.

Note:

This working draft includes a non-normative XML Schema for XSLT stylesheet modules: see F Schema for XSLT Stylesheets. However, it has been decided to retain the syntax summaries in their present form as these are thought to be easier to read.

XSLT defines a set of standard functions which are additional to those defined in [Functions and Operators]. The signatures of these functions are described using the same notation as used in [Functions and Operators].

2.3 Initiating a Transformation

This document does not specify any application programming interfaces or other interfaces for initiating a transformation. This section, however, describes the information that must be supplied when a transformation is initiated.

Implementations may allow a transformation to run as two or more phases, for example parsing, compilation and execution. Such a distinction is outside the scope of this specification, which treats transformation as a single process controlled using a set of stylesheet modules, supplied in the form of XML documents.

The following information is supplied to execute a transformation:

• An identification of the stylesheet module that is to act as the principal stylesheet module for the transformation. The complete stylesheet is assembled by expanding the xsl:import and xsl:include declarations in the principal stylesheet module, as described in 3.8.1 Stylesheet Inclusion and 3.8.2 Stylesheet Import

• A set (possibly empty) of values for stylesheet parameters (see 9.5 Global Variables and Parameters). These values are available for use within expressions in the stylesheet.

• A set of nodes (possibly empty) that forms the initial input sequence. These nodes (which will often be document nodes, but may in principle be any kind of node, from the same or different documents) are available at any time during the transformation as the result of the input function described in [Functions and Operators].

• A node that acts as the initial context node for the transformation. This node is accessible within the stylesheet as the initial value of the XPath expressions . and self::node(), as described in 2.5 Maintaining Position: the Focus . If no initial context node is supplied, then the context item, context position, and context size will initially be unset, and the evaluation of any expression that references these values will result in a dynamic error.

  Note:

  It is not necessary for the initial context node to be a member of the initial input sequence, but in a simple transformation of a single document, it is convenient to set both the initial input sequence and the initial context node to the document node of the source document to be transformed.

• Optionally, the name of a named template which is to be executed as the entry point to the transformation. This template must exist within the stylesheet. If no named template is supplied, then the transformation starts with the template rule that best matches the initial context node, according to the rules defined in 6.4 Conflict Resolution for Template Rules. Either a named template, or an initial context node, or both, must be supplied.

• Optionally, an initial mode. If an initial mode is supplied, then in searching for the template rule that best matches the initial context node, the processor considers only those rules that apply to the initial mode. If no initial mode is supplied, the default mode is used.

• A base output URI, that is, a URI to be used as the base URI when resolving a relative URI allocated to a result tree. If the transformation generates multiple result trees, then typically each one will be allocated a URI relative to this base URI.

[ERR004] It is a dynamic error if the invocation of the stylesheet specifies a template name that does not match the expanded-QName of a named template defined in the stylesheet.

The transformation is performed by evaluating an initial template; if a named template is supplied when the transformation is initiated, then this is the initial template; otherwise, the initial template is the template rule selected for processing the initial context node in the initial mode, selected according to the rules used by the xsl:apply-templates instruction. If the result of evaluating the initial template is a non-empty sequence, then this sequence is used to construct an implicit result tree, following the rules described in 5.6.1 Constructing Complex Content: the effect is as if the sequence constructor contained in the initial template were contained in an xsl:result-document element with no attributes.

Parameters passed to the transformation by the client application are matched against stylesheet parameters (see 9.5 Global Variables and Parameters), not against the template parameters declared within the initial template. All template parameters within the initial template to be executed will take their default values. [ERR005] It is a dynamic error if the initial template defines a template parameter that specifies required="yes". The processor must signal the error.

A stylesheet can process further source documents in addition to those supplied when the transformation is invoked. These additional documents can be loaded using the functions document, doc or collection described in [Functions and Operators], or they can be supplied as stylesheet parameters (see 9.5 Global Variables and Parameters), or as the result of an extension function (see 18.1 Extension Functions

2.4 Executing a Transformation

The XSLT instructions used to control a transformation can be divided into two groups: push processing instructions, which use template rules to define the processing associated with different nodes in a source tree, and pull processing instructions, which allow the selection and processing of source tree nodes to be described together. These two groups of instructions are described in the following sections.

<doc>
  <val>1</val>
  <val>2</val>
  <val>3</val>
</doc>

<xsl:template match="val">
<li><xsl:value-of select="."/></li>
</xsl:template>

  <li>1</li>
  <li>2</li>
  <li>3</li>

<xsl:template match="doc">
<ol><xsl:apply-templates select="*"/></ol>
</xsl:template>

<ol>
  <li>1</li>
  <li>2</li>
  <li>3</li>
</ol>

2.5 Maintaining Position: the Focus

When a sequence constructor is evaluated, the processor keeps track of which nodes are being processed by means of a set of implicit variables referred to collectively as the focus. More specifically, the focus consists of the following three values:

• The context item is the item currently being processed. An item (see [Data Model]) is either an atomic value (such as an integer, date, or string), or a node. The context item is initially set to the initial context node supplied when the transformation is invoked (see 2.3 Initiating a Transformation). It changes whenever instructions such as xsl:apply-templates and xsl:for-each are used to process a sequence of items; each item in such a sequence becomes the context item while that item is being processed. The context item is returned by the XPath expression . (dot).

• The context position is the position of the context item within the sequence of items currently being processed. It changes whenever the context item changes. When an instruction such as xsl:apply-templates or xsl:for-each is used to process a sequence of items, the first item in the sequence is processed with a context position of 1, the second item with a context position of 2, and so on. The context position is returned by the XPath expression position().

• The context size is the number of items in the sequence of items currently being processed. It changes whenever instructions such as xsl:apply-templates and xsl:for-each are used to process a sequence of items; during the processing of each one of those items, the context size is set to the count of the number of items in the sequence (or equivalently, the position of the last item in the sequence). The context size is returned by the XPath expression last().

If the context item is a node (as distinct from an atomic value such as an integer), then it is also referred to as the context node. The context node is not an independent variable, it changes whenever the context item changes. When the context item is an atomic value, there is no context node. The context node is returned by the XPath expression self::node(), and it is used as the starting node for all relative path expressions.

The current function can be used within any XPath expression to select the item that was supplied as the context item to the XPath expression by the XSLT processor; unlike . this is unaffected by changes to the context item that occur within the XPath expression. The current function is described in 16.6.1 current.

On completion of an instruction which changes the focus (such as xsl:apply-templates or xsl:for-each), the focus reverts to its previous value.

When a stylesheet function is called, the focus within the body of the function is initially undefined. The focus is also undefined on initial entry to the stylesheet if no initial context node supplied. [ERR006] When the focus is undefined, evaluation of any expression that references the context item, context position, or context size results in a dynamic error. The processor must signal the error.

The description above gives an outline of the way the focus works. Detailed rules for the effect of each instruction are given separately with the description of that instruction. In the absence of specific rules, an instruction uses the same focus as its parent instruction.

Sometimes the focus is based on a single node. A singleton focus based on a node N has the context item (and therefore the context node) set to N, and the context position and context size both set to 1 (one).

In addition to the values that make up the focus, an XSLT processor maintains a number of other internal variables that reflect aspects of the evaluation context. These variables are fully described in the sections of the specification that maintain and use these variables. They are:

• The current template, which is the template rule most recently invoked by an xsl:apply-templates, xsl:apply-imports, or xsl:next-match instruction: see 6.7 Overriding Template Rules

• The current mode, which is the mode in which the current template rule was invoked: see 6.5 Modes

• The current group and current grouping key, which provide information about the collection of items currently being processed by an xsl:for-each-group instruction: see 14.1 The Current Group and 14.2 The Current Grouping Key.

• The current set of captured substrings, which is maintained when a string is matched against a regular expression using the xsl:analyze-string instruction, and which is accessible using the regex-group function: see 15 Regular Expressions

As with the focus, these variables are not accessible within a stylesheet function unless they have been initialized within that function.

2.6 Parsing and Serialization

An XSLT stylesheet describes a process that constructs a set of result trees from a set of source trees.

The stylesheet does not describe how a source tree is constructed. Frequently an implementation will operate in conjunction with an XML parser (or more strictly, in the terminology of [XML 1.0], an XML processor), to build the source tree from an input XML document. An implementation may also provide an application programming interface allowing the tree to be constructed directly, or allowing it to be supplied in the form of a DOM Document object (see [DOM2]). This is outside the scope of this specification. Users should be aware, however, that since the input to the transformation is a tree conforming to the XPath data model as described in [Data Model], constructs that might exist in the original XML document, or in the DOM, but which are not within the scope of the data model, cannot be processed by the stylesheet and cannot be guaranteed to remain unchanged in the transformation output. Such constructs include CDATA section boundaries, the use of entity references, and the DOCTYPE declaration and internal DTD subset.

A frequent requirement is to output a result tree as an XML document (or in other formats such as HTML). This process is referred to as serialization. Like parsing, serialization is not part of the transformation process, and it is not required that an XSLT processor must be able to perform serialization. However, for pragmatic reasons, this specification describes a declaration (the xsl:output element, see 20 Serialization) which allows a stylesheet to specify the desired properties of a serialized output file. Implementations that do not serialize result trees are allowed to ignore this declaration.

2.7 Extensibility

XSLT provides two hooks for extending the language, one hook for extending the set of instruction elements used in sequence constructors and one hook for extending the set of functions used in XPath expressions. These hooks are both based on XML namespaces: see 18 Extensibility and Fallback for further details. Extension instructions and extension functions defined according to these rules may be provided by the implementor of the XSLT processor, and the implementor may also provide facilities to allow users to create further extension instructions and extension functions. This specification defines how extension instructions and extension functions are invoked, but the facilities for creating new extension instructions and extension functions are implementation-defined.

2.8 Stylesheets and Schemas

An XSLT stylesheet can make use of information from XML Schemas, as defined in [XML Schema]. An XSLT transformation can take place in the absence of a schema (and, indeed, in the absence of a DTD), but where the source document has undergone schema validity assessment, the XSLT processor has access to the type information associated with individual nodes, not merely to the raw text.

Information from a schema can be used both statically (when the stylesheet is compiled), and dynamically (during evaluation of the stylesheet to transform a source document).

The conformance rules for XSLT 2.0, defined in 21 Conformance, distinguish between a basic XSLT processor and a schema-aware XSLT processor. As the names suggest, a basic XSLT processor does not support the features of XSLT that require access to schema information, either statically or dynamically. A stylesheet that works with a basic XSLT processor will usually work unchanged with a schema-aware XSLT processor; however, the fact that a source document has been processed using a schema processor and has been annotated with type information affects the outcome of certain operations such as sorting.

The remainder of this section describes facilities that are available only with a schema-aware XSLT processor.

There are places within a stylesheet, and within XPath expressions and patterns in a stylesheet, where the names of schema-defined elements, attributes, and named types appear. For example, it is possible to declare the types expected for the parameters of a function. The element, attribute, and type names that appear in such contexts must either be built-in schema types (for example xs:string or xs:integer), or they must be user-defined types that are made accessible to the XSLT processor by means of an xsl:import-schema declaration: see 3.10 Importing Schema Components.

It is only necessary to import a schema explicitly if its type definitions are mentioned statically in the stylesheet; it is not necessary to import a schema merely because the stylesheet is used to process a source document that has been assessed against that schema. It is possible to make use of the information resulting from schema assessment (for example, the fact that a particular attribute holds a date) even if no schema has been imported by the stylesheet.

Further, importing a schema does not of itself say anything about the type of the source document that the stylesheet is expected to process. The imported type definitions can be used for temporary nodes or for nodes on the result tree just as much as for nodes in source documents. It is possible to make assertions about the types of input document by means of tests within the stylesheet. For example:

<xsl:template match="document-node(element(my:invoice))" priority="2">
. . .
</xsl:template>

<xsl:template match="document-node()" priority="1">
  <xsl:message terminate="yes">Source document is not an invoice</xsl:message>
</xsl:template>

A stylesheet can also control the types of nodes that it constructs in a final result tree, or in temporary trees. In the case of temporary trees, this enables the tree to be processed in the same way as a source document that has undergone schema assessment. In the case of a final result tree, it enables the result tree to be passed to further processes (including further XSLT transformations) with its type information intact.

Where a stylesheet author chooses to make assertions about the types of nodes or of variables and parameters, it is possible for an XSLT processor to perform static analysis of the stylesheet (that is, analysis in the absence of any source document). Such analysis may reveal errors that would otherwise not be discovered until the transformation is actually executed. An XSLT processor is not required to perform such static type-checking, and if it does perform such checking, any errors signaled are advisory only: the user must be given the option to use the stylesheet even if static analysis has revealed type errors.

Type annotations can be created in nodes of a result tree, or of a temporary tree, in a number of ways.

• It is possible to request explicit validation of a complete result tree. Validation is either strict or lax, and is performed according to the rules defined in [XML Schema]. If validation of a result tree fails (strictly speaking, if the outcome of the validity assessment is invalid), then the transformation fails, but if it succeeds, the element and attribute nodes of the tree will be annotated with the names of the schema-defined types to which these nodes conform. These annotations will be discarded if the result tree is serialized as an XML document, but they remain available when the result tree is passed to an application (perhaps another stylesheet) for further processing.

• It is also possible to validate individual element and attribute nodes as they are constructed. This is done using the type and validation attributes of the xsl:element, xsl:attribute, xsl:copy, and xsl:copy-of instructions, or the xsl:type and xsl:validation attributes of a literal result element.

• When elements or attributes are copied, either explicitly using the xsl:copy or xsl:copy-of, or implicitly when nodes in a sequence are attached to a new parent node, the options validation="strip" and validation="preserve" are available, to control whether existing type annotations are to be retained or not.

For details of how validation of element and attribute nodes works, see 19.2 Validation.

2.9 Error Handling

An error that is 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. Errors classified in this specification as static errors must be signaled by all implementations: that is, the processor must indicate that the error is present. A static error must be signaled even if it occurs in a part of the stylesheet that is never evaluated. Static errors are never recoverable. After signaling a static error, a processor may continue for the purpose of signaling additional errors, but it must eventually terminate abnormally without producing any result tree.

There is an exception to this rule when the stylesheet specifies forwards-compatible behavior (see 3.7 Forwards-Compatible Processing).

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.

An error that is not detected until a source document is being transformed is referred to as a dynamic error. Some dynamic errors are classed as recoverable errors. When a recoverable error occurs, this specification allows the processor either to signal the error (by reporting the error condition and terminating execution) or to take a defined recovery action and continue processing. It is implementation-defined whether the error is signaled or the recovery action is taken. If the implementation does choose to take recovery action, it must take the recovery action defined in this specification.

When the implementation makes the choice between signaling a dynamic error or recovering, it is not restricted in how it makes the choice; for example, it may provide options that can be set by the user. When an implementation chooses to recover from a dynamic error, it is also allowed to take other action, such as logging a warning message.

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 the result tree 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 can choose whether or not to evaluate the variable declaration, which means that if evaluating the variable declaration causes a dynamic error, some implementations will signal 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 signal any dynamic errors that would arise if the construct were evaluated.

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

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 signaled as a dynamic error. An implementation may also, optionally, signal a type error 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 signaled statically.

<xsl:if test="false()">
  <xsl:apply-templates select="42"/>
</xsl:if>

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

When a transformation signals 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 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.

If a transformation has successfully produced a result tree, it is still possible that errors may occur in serializing the result tree. For example, it may be impossible to serialize the result tree using the encoding selected by the user. Such an error is referred to as a serialization error. As with other aspects of serialization, the handling of serialization errors is implementation-defined: see 20 Serialization.

3.1 XSLT Namespace

The XSLT namespace has the URI http://www.w3.org/1999/XSL/Transform. It is used to identify elements, attributes, and other names that have a special meaning defined in this specification.

Note:

The 1999 in the URI indicates the year in which the URI was allocated by the W3C. It does not indicate the version of XSLT being used, which is specified by attributes (see 3.4 Stylesheet Element and 3.5 Simplified Stylesheet Modules).

XSLT processors must use the XML namespaces mechanism [XML Namespaces 1.0] to recognize elements and attributes from this namespace. Elements from the XSLT namespace are recognized only in the stylesheet and not in the source document. The complete list of XSLT-defined elements is specified in C Element Syntax Summary. Implementations must not extend the XSLT namespace with additional elements or attributes. Instead, any extension must be in a separate namespace. Any namespace that is used for additional instruction elements must be identified by means of the extension instruction mechanism specified in 18.2 Extension Instructions.

This specification uses a prefix of xsl: for referring to elements in the XSLT namespace. However, XSLT stylesheets are free to use any prefix, provided that there is a namespace declaration that binds the prefix to the URI of the XSLT namespace.

An element from the XSLT namespace may have any attribute not from the XSLT namespace, provided that the expanded-QName (see [XPath 2.0]) of the attribute has a non-null namespace URI. The presence of such attributes must not change the behavior of XSLT elements and functions defined in this document or in the XPath specification, though they may be used to modify the behavior of extension functions and extension instructions. Thus, an implementation is always free to ignore such attributes, and must ignore such attributes without giving an error if it does not recognize the namespace URI. Such attributes can provide, for example, unique identifiers, optimization hints, or documentation. The set of namespaces that are recognized for such attributes is implementation-defined.

Note:

Throughout this specification, an element or attribute that is in no namespace, or an expanded-QName whose namespace part is an empty sequence, is referred to as having a null namespace URI.

<xsl:message
    abc:pause="yes"
    xmlns:abc="http://vendor.example.com/xslt/extensions">Phase 1 complete</xsl:message>

[ERR007] It is a static error for an element from the XSLT namespace to have an attribute whose namespace is either null (i.e. an attribute with an unprefixed name) or the XSLT namespace, other than attributes defined for the element in this document.

Note:

The conventions used for the names of XSLT elements, attributes and functions are that names are all lower-case, use hyphens to separate words, and use abbreviations only if they already appear in the syntax of a related language such as XML or HTML. Names of types defined in XML Schema however, are regarded as single words and are capitalized exactly as in XML Schema. This sometimes leads to composite function names such as current-dateTime.

The XSLT namespace, together with certain other namespaces recognized by an XSLT processor, are classified as reserved namespaces and must be used only as specified in this and related specifications. The reserved namespaces are those listed below.

• The XSLT namespace, described in this section, is reserved.

• The standard function namespace http://www.w3.org/2003/05/xpath-functions is used for functions in the core function library, defined in [Functions and Operators].

• The XML namespace, defined in [XML Namespaces 1.0] as http://www.w3.org/XML/1998/namespace, is used for attributes such as xml:lang and xml:space.

• The schema namespace http://www.w3.org/2001/XMLSchema is used as defined in [XML Schema] . In a stylesheet this namespace may be used to refer to built-in schema datatypes and to the constructor functions associated with those datatypes.

• The schema datatypes namespace http://www.w3.org/2001/XMLSchema-datatypes is used as defined in [XML Schema] . In a stylesheet this namespace may be used to refer to built-in schema datatypes and to the constructor functions associated with those datatypes: in these respects it is equivalent to the schema namespace.

• The XPath datatypes namespace http://www.w3.org/2003/05/xpath-datatypes is used as defined in [Functions and Operators] . In a stylesheet this namespace may be used to refer to the types xdt:untypedAtomic, xdt:yearMonthDuration, xdt:dayTimeDuration, xdt:anyAtomicType, and to the constructor functions associated with the first three of these types.

• The schema instance namespace http://www.w3.org/2001/XMLSchema-instance is used as defined in [XML Schema] . Attributes in this namespace, if they appear in a stylesheet, are treated by the XSLT processor in the same way as any other attributes.

Reserved namespaces may be used without restriction to refer to the names of elements and attributes in source documents and result documents. As far as the XSLT processor is concerned, reserved namespaces other than the XSLT namespace may be used without restriction in the names of literal result elements and user-defined data elements, and in the names of attributes of literal result elements or of XSLT instructions: but other processors may impose restrictions or attach special meaning to them. Reserved namespaces must not be used, however, in the names of stylesheet-defined objects such as variables and stylesheet functions.

Note:

With the exception of the XML namespace, any of the above namespaces that are used in a stylesheet must be explicitly declared with a namespace declaration. Although conventional prefixes are used for these namespaces in this specification, any prefix may be used in a user stylesheet.

[ERR008] It is a static error to use a reserved namespace in the name of a named template, a mode, an attribute set, a key, a named sort specification, a decimal-format, a date-format, a variable or parameter, a stylesheet function, a named output definition, or a character map.

Implementations may reserve additional namespaces for use by the implementation, provided they follow accepted practice to avoid naming collisions. The set of such namespaces is implementation-defined.

Future versions of this specification may reserve additional namespaces starting with http://www.w3.org/.

3.2 XSLT Media Type

A media type will be registered for XSLT stylesheet modules.

Note:

It is expected that this media type will be application/xslt+xml as forecast in section 8.17 of [RFC3023].

This media type should be used for an XML document containing a standard stylesheet module at its top level, and it may also be used for a simplified stylesheet module. It should not be used for an XML document containing an embedded stylesheet module.

3.3 Standard Attributes

There are a number of standard attributes that may appear on any XSLT element: specifically version, exclude-result-prefixes, extension-element-prefixes, and xpath-default-namespace.

These attributes may also appear on a literal result element, but in this case, to distinguish them from user-defined attributes, the names of the attributes are in the XSLT namespace. They are thus typically written as xsl:version, xsl:exclude-result-prefixes, xsl:extension-element-prefixes, or xsl:xpath-default-namespace.

It is recommended that these attributes should also be permitted on extension instructions, but this is at the discretion of the implementor of each extension instruction. They may also be permitted on user-defined data elements, though they will only have any useful effect in the case of data elements that are designed to behave like XSLT declarations or instructions.

In the following descriptions, these attributes are referred to generically as [xsl:]version, and so on.

These attributes all affect the element they appear on, and any descendant elements of the element they appear on, together with attributes of those descendant elements. The two forms with and without the XSLT namespace have the same effect; the XSLT namespace is used for the attribute if and only if its parent element is not in the XSLT namespace.

In the case of [xsl:]version and [xsl:]xpath-default-namespace the value can be overridden by a different value for the same attribute appearing on a descendant element. The effective value of the attribute for a particular stylesheet element is determined by the innermost containing element on which the attribute appears. Note however that the version attribute on the xsl:output element serves an entirely different purpose.

In the case of [xsl:]exclude-result-prefixes and [xsl:]extension-element-prefixes the values are cumulative. For these attributes, the value is given as a whitespace-separated list of namespace prefixes, and the effective value for an element is the combined set of namespace URIs designated by the prefixes that appear in this attribute for that element and any of its ancestor elements. Again, the two forms with and without the XSLT namespace are equivalent.

Because these attributes may appear on any XSLT element, they are not listed in the syntax summary of each individual element. Instead they are listed and described in the description of the xsl:stylesheet and xsl:transform elements only. This reflects the fact that these attributes are often used on the xsl:stylesheet element, in which case they apply to the entire stylesheet module.

Note that the effect of these attributes does not extend to stylesheet modules referenced by xsl:include or xsl:import declarations.

For the detailed effect of each attribute, see the following sections:

• [xsl:]version: see 3.6 Backwards-Compatible Processing and 3.7 Forwards-Compatible Processing

• [xsl:]xpath-default-namespace: see 5.4 Unprefixed Names in Expressions and Patterns.

• [xsl:]exclude-result-prefixes: see 11.1.3 Namespace Nodes for Literal Result Elements.

• [xsl:]extension-element-prefixes: see 18.2 Extension Instructions.

3.4 Stylesheet Element

<xsl:stylesheet
  id = id
  extension-element-prefixes = tokens
  exclude-result-prefixes = tokens
  version = number
  xpath-default-namespace = uri
  default-validation = "strict" | "lax" | "preserve" | "strip">
  <!-- Content: (xsl:import*, other-declarations) -->
</xsl:stylesheet>

<xsl:transform
  id = id
  extension-element-prefixes = tokens
  exclude-result-prefixes = tokens
  version = number
  xpath-default-namespace = uri
  default-validation = "strict" | "lax" | "preserve" | "strip">
  <!-- Content: (xsl:import*, other-declarations) -->
</xsl:transform>

A stylesheet module is represented by an xsl:stylesheet element in an XML document. xsl:transform is allowed as a synonym for xsl:stylesheet; everything this specification says about the xsl:stylesheet element applies equally to xsl:transform.

[ERR009] An xsl:stylesheet element must have a version attribute, indicating the version of XSLT that the stylesheet requires. [ERR010] The value of the version attribute must be a number (specifically, it must be a DecimalLiteral as defined in [XPath 2.0].) For this version of XSLT, the value should normally be 2.0. A value of 1.0 indicates that the stylesheet was written with the intention that it should be processed using an XSLT 1.0 processor. [ERR011] It is a static error to submit to an XSLT 2.0 processor a stylesheet that specifies version="1.0" in the xsl:stylesheet element of the principal stylesheet module, or in the xsl:version attribute of the outermost element in the case of a simplified stylesheet module. This is a recoverable error. The processor may signal the error, or may recover by processing the stylesheet with backwards-compatible processing behavior enabled (see 3.6 Backwards-Compatible Processing).

When the value of the version attribute is greater than 2.0, forwards-compatible behavior is enabled (see 3.7 Forwards-Compatible Processing).

Note:

XSLT 1.0 allowed the [xsl:]version attribute to take any numeric value, and specified that if the value was not equal to 1.0, the stylesheet would be executed in forwards compatible mode. XSLT 2.0 continues to allow the attribute to take any unsigned decimal value. A software product that includes both an XSLT 1.0 processor and an XSLT 2.0 processor (or that can execute as either) may use the [xsl:]version attribute to decide which processor to invoke; such behavior is outside the scope of this specification. When the stylesheet is executed with an XSLT 2.0 processor, the value 1.0 is taken to indicate that the stylesheet was written with XSLT 1.0 in mind: if this value appears on the outermost element of the principal stylesheet module then an XSLT 2.0 processor must either reject the stylesheet or execute it in backwards compatible mode, as described above. Setting version="2.0" indicates that the stylesheet is to be executed with neither backwards nor forwards compatible behavior enabled. Any other value less than 2.0 enables backwards compatible behavior, while any value greater than 2.0 enables forwards compatible behavior. When developing a stylesheet that is designed to execute under either XSLT 1.0 or XSLT 2.0, the recommended practice is to create two separate entry modules, one specifying version="1.0", and the other specifying version="2.0"; these entry modules can use xsl:include or xsl:import to incorporate the common code. Subsidiary stylesheet modules should specify version="2.0" if they make use of XSLT 2.0 facilities, and version="1.0" otherwise.

The default-validation attribute defines the default value of the validation attribute of all xsl:element, xsl:attribute, xsl:copy, xsl:copy-of, and xsl:result-document instructions, and of the xsl:validation attribute of all literal result elements. It also determines the validation applied to the implicit result tree created in the absence of an xsl:result-document instruction. This default applies within the stylesheet module: it does not extend to included or imported stylesheet modules. If the attribute is omitted, the default is strip. For details of the effect of this attribute, see 19.2 Validation.

[ERR012] An xsl:stylesheet element must have no text node children, other than text nodes consisting entirely of whitespace.

An element occurring as a child of an xsl:stylesheet element is called a top-level element.

Top-level elements fall into two categories: declarations, and user-defined data elements. Top-level elements whose names are in the XSLT namespace are declarations. Top-level elements in any other namespace are user-defined data elements (see 3.4.1 User-defined Data Elements)

The xsl:stylesheet element may contain the following types of declaration:

• xsl:import

• xsl:include

• xsl:attribute-set

• xsl:character-map

• xsl:date-format

• xsl:decimal-format

• xsl:function

• xsl:import-schema

• xsl:key

• xsl:namespace-alias

• xsl:output

• xsl:param

• xsl:preserve-space

• xsl:sort-key

• xsl:strip-space

• xsl:template

• xsl:variable

If there are xsl:import elements, these must come before any other elements. Apart from this, the child elements of the xsl:stylesheet element may appear in any order. The ordering of these elements does not affect the results of the transformation unless there are conflicting declarations (for example, two template rules with the same priority that match the same node). In general, it is an error for a stylesheet to contain such conflicting declarations, but in some cases the processor is allowed to recover from the error by choosing the declaration that appears last in the stylesheet.

3.5 Simplified Stylesheet Modules

A simplified syntax is allowed for a stylesheet module that defines only a single template rule for the document node. The stylesheet module may consist of just a literal result element (see 11.1 Literal Result Elements) together with its contents. Such a stylesheet is equivalent to a standard stylesheet module whose xsl:stylesheet element contains a template rule containing the literal result element; the template rule has a match pattern of /.

<html xsl:version="2.0"
      xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
      xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <title>Expense Report Summary</title>
  </head>
  <body>
    <p>Total Amount: <xsl:value-of select="expense-report/total"/></p>
  </body>
</html>

<xsl:stylesheet version="2.0"
                xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns="http://www.w3.org/1999/xhtml">
<xsl:template match="/">
<html>
  <head>
    <title>Expense Report Summary</title>
  </head>
  <body>
    <p>Total Amount: <xsl:value-of select="expense-report/total"/></p>
  </body>
</html>
</xsl:template>
</xsl:stylesheet>

More formally, a simplified stylesheet module is equivalent to the standard stylesheet module that would be generated by applying the following transformation to the simplified stylesheet module, invoking the transformation by calling the named template expand, with the containing literal result element as the context node:

<xsl:stylesheet version="2.0"
                xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

<xsl:template name="expand">
  <xsl:element name="xsl:stylesheet">
    <xsl:attribute name="version">
      <xsl:value-of select="@xsl:version"/>
    </xsl:attribute>
    <xsl:element name="xsl:template">
      <xsl:attribute name="match">/</xsl:attribute>
      <xsl:copy-of select="."/>
    </xsl:element>
  </xsl:element>
</xsl:template>  

</xsl:stylesheet>

[ERR015] A literal result element that is used as the outermost element of a simplified stylesheet module must have an xsl:version attribute. This indicates the version of XSLT that the stylesheet requires. For this version of XSLT, the value should normally be 2.0; the value must be a DecimalLiteral as defined in [XPath 2.0].

Other literal result elements may also have an xsl:version attribute. When the xsl:version attribute is numerically less than 2.0, backwards-compatible processing behavior is enabled (see 3.6 Backwards-Compatible Processing). When the xsl:version attribute is numerically greater than 2.0, forwards-compatible behavior is enabled (see 3.7 Forwards-Compatible Processing).

The allowed content of a literal result element when used as a simplified stylesheet is the same as when it occurs within a sequence constructor. Thus, a literal result element used as the document element of a simplified stylesheet cannot contain declarations.

3.6 Backwards-Compatible Processing

An element enables backwards-compatible behavior for itself, its attributes, its descendants and their attributes if it has an [xsl:]version attribute (see 3.3 Standard Attributes) whose value is less than 2.0. An element that has an [xsl:]version attribute whose value is greater than or equal to 2.0 disables backwards-compatible behavior for itself, its attributes, its descendants and their attributes. The compatibility behavior established by an element overrides any compatibility behavior established by an ancestor element.

These rules do not apply to the version attribute of the xsl:output element, which has an entirely different purpose.

If an attribute containing an XPath expression is processed with backwards-compatible behavior, then the expression is evaluated with the XPath 1.0 backwards compatibility flag set to true.

Certain XSLT constructs also produce different results when backwards-compatible behavior is enabled. This is described separately for each such construct.

Note:

The result of processing a stylesheet using backwards compatible behavior is likely in most cases to be identical or very similar to the effects of processing the same stylesheet using an XSLT 1.0 processor. The differences are described (non-normatively) in K.1 Incompatible Changes. To assist with transition, some parts of an stylesheet may be processed with backwards compatible behavior enabled, and other parts with this behavior disabled. All data values manipulated by an XSLT 2.0 processor are defined by the XPath 2.0 data model, whether or not the relevant expressions use backwards compatible behavior. Because the same data model is used in both cases, expressions are fully composable. The result of evaluating instructions or expressions with backwards compatible behavior is fully defined in the XSLT 2.0 and XPath 2.0 specifications, it is not defined by reference to the XSLT 1.0 and XPath 1.0 specifications.

It is implementation-defined whether a particular XSLT 2.0 implementation supports backwards-compatible behavior. [ERR017] If an implementation does not support backwards-compatible behavior, then it is a dynamic error if any element is evaluated that enables backwards-compatible behavior. The processor must signal the error.

Note:

To write a stylesheet that works with both XSLT 1.0 and 2.0 processors, while making selective use of XSLT 2.0 facilities, it is necessary to understand both the rules for backwards-compatible behavior in XSLT 2.0, and the rules for forwards-compatible behavior in XSLT 1.0. If the xsl:stylesheet element specifies version="2.0", then an XSLT 1.0 processor will ignore XSLT 2.0 declarations that were not defined in XSLT 1.0, for example xsl:function and xsl:sort-key. If any new XSLT 2.0 instructions are used (for example xsl:analyze-string or xsl:namespace), or if new XPath 2.0 features are used (for example, new functions, or syntax such as conditional expressions, or calls to a function defined using xsl:function), then the stylesheet must provide fallback behavior that relies on XSLT 1.0 and XPath 1.0 facilities only. The fallback behavior can be invoked by using the xsl:fallback instruction, or by testing the results of the function-available or element-available functions, or by testing the value of the xsl:version property returned by the system-property function.

3.7 Forwards-Compatible Processing

An element enables forwards-compatible behavior for itself, its attributes, its descendants and their attributes if it has an [xsl:]version attribute (see 3.3 Standard Attributes) whose value is greater than 2.0. An element that has an [xsl:]version attribute whose value is less than or equal to 2.0 disables forwards-compatible behavior for itself, its attributes, its descendants and their attributes. The compatibility behavior established by an element overrides any compatibility behavior established by an ancestor element.

These rules do not apply to the version attribute of the xsl:output element, which has an entirely different purpose.

Within a section of a stylesheet where forwards-compatible behavior is enabled, errors that would normally be static errors are treated instead as dynamic errors. This means that no error is signaled unless the construct containing the error is actually evaluated.

This means, for example, that when an element is processed with forwards-compatible behavior:

• if it is a declaration element and XSLT 2.0 does not allow such elements as declarations, then the element must be ignored along with its content;

• if it is an element in a sequence constructor and XSLT 2.0 does not allow such elements to occur in sequence constructors, then if the element is not evaluated, no error must be signaled, and if the element is evaluated, the processor must perform fallback for the element as specified in 18.2.3 Fallback;

• if the element has an attribute that XSLT 2.0 does not allow the element to have or if the element has an optional attribute with a value that XSLT 2.0 does not allow the attribute to have, then the attribute must be ignored.

• if an attribute of the element contains an XPath expression that does not match the allowed syntax of an XPath 2.0 expression, or one that calls a function whose name is in the standard function namespace (see [Functions and Operators]) but that is not defined in XPath 2.0 or XSLT 2.0, or that calls such a function with the wrong number or type of arguments, the error must not be signaled unless the expression is actually evaluated.

<xsl:stylesheet version="17.0"
                xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <xsl:template match="/">
    <xsl:choose>
      <xsl:when test="system-property('xsl:version') >= 17.0">
        <xsl:exciting-new-17.0-feature/>
      </xsl:when>
      <xsl:otherwise>
        <html>
        <head>
          <title>XSLT 17.0 required</title>
        </head>
        <body>
          <p>Sorry, this stylesheet requires XSLT 17.0.</p>
        </body>
        </html>
      </xsl:otherwise>
    </xsl:choose>
  </xsl:template>
</xsl:stylesheet>

Note:

If a stylesheet depends crucially on a declaration introduced by a version of XSLT after 2.0, then the stylesheet can use an xsl:message element with terminate="yes" (see 17 Messages) to ensure that implementations that conform to an earlier version of XSLT will not silently ignore the declaration.

<xsl:stylesheet version="18.0"
                xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

  <xsl:important-new-17.0-declaration/>

  <xsl:template match="/">
    <xsl:choose>
      <xsl:when test="system-property('xsl:version') < 17.0">
        <xsl:message terminate="yes">
          <xsl:text>Sorry, this stylesheet requires XSLT 17.0.</xsl:text>
        </xsl:message>
      </xsl:when>
      <xsl:otherwise>
        ...
      </xsl:otherwise>
    </xsl:choose>
  </xsl:template>
  ...
</xsl:stylesheet>

3.8 Combining Stylesheet Modules

XSLT provides two mechanisms to construct a stylesheet from multiple stylesheet modules:

• an inclusion mechanism that allows stylesheet modules to be combined without changing the semantics of the modules being combined, and

• an import mechanism that allows stylesheet modules to override each other.

<xsl:stylesheet version="2.0"
                xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <xsl:import href="article.xsl"/>
  <xsl:import href="bigfont.xsl"/>
  <xsl:attribute-set name="note-style">
    <xsl:attribute name="font-style">italic</xsl:attribute>
  </xsl:attribute-set>
</xsl:stylesheet>

         A
         |
     +---+---+
     |       |
     B       C
     |       |
     D       E

3.9 Embedded Stylesheet Modules

A standard stylesheet module is a complete XML document with the xsl:stylesheet element as its document element. However, a stylesheet module may also be embedded in another resource. Two forms of embedding are possible:

• the XSLT stylesheet may be textually embedded in a non-XML resource, or

• the xsl:stylesheet element may occur in an XML document other than as the document element.

To facilitate the second form of embedding, the xsl:stylesheet element is allowed to have an ID attribute that specifies a unique identifier.

Note:

In order for such an attribute to be used with the XPath id function, it must actually be declared in the DTD or schema as being of type ID. The same requirement typically applies if the identifier is to be used as a fragment identifier in a URI reference.

<?xml-stylesheet type="application/xslt+xml" href="#style1"?>
<!DOCTYPE doc SYSTEM "doc.dtd">
<doc>
<head>
<xsl:stylesheet id="style1"
                version="2.0"
                xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns:fo="http://www.w3.org/1999/XSL/Format">
<xsl:import href="doc.xsl"/>
<xsl:template match="id('foo')">
  <fo:block font-weight="bold"><xsl:apply-templates/></fo:block>
</xsl:template>
<xsl:template match="xsl:stylesheet">
  <!-- ignore -->
</xsl:template>
</xsl:stylesheet>
</head>
<body>
<para id="foo">
...
</para>
</body>
</doc>

Note:

A stylesheet module that is embedded in the document to which it is to be applied typically needs to contain a template rule that specifies that xsl:stylesheet elements are to be ignored.

Note:

The above example uses the pseudo-attribute type="application/xslt+xml" in the xml-stylesheet processing instruction to denote an XSLT stylesheet. This usage is subject to change: see 3.2 XSLT Media Type. In the absence of a registered media type for XSLT stylesheets, some vendors' products have adopted different conventions, notably type="text/xsl".

Note:

Support for the xml-stylesheet processing instruction is not a requirement for conformance with this Recommendation.

3.10 Importing Schema Components

<!-- Category: declaration -->
<xsl:import-schema
  namespace = uri-reference
  schema-location = uri-reference />

The xsl:import-schema declaration is used to identify schema components (that is, the names of type definitions and element and attribute declarations) which need to be available statically, that is, before any source document is available. Every such name used statically within the stylesheet other than the built-in type names defined in XML Schema and the four built-in types defined in XPath 2.0 (xdt:dayTimeDuration, xdt:yearMonthDuration, xdt:anyAtomicType, xdt:untypedAtomic) must be defined in an imported schema.

The xsl:import-schema declaration imports the top-level element and attribute declarations and type definitions from the schema, and makes them available for use within XPath expressions in the stylesheet, and within other stylesheet contexts such as the type and as attributes of various XSLT elements.

The same schema definitions are available in all stylesheet modules; importing the definitions in one stylesheet module makes them available throughout the stylesheet.

The namespace and schema-location attributes are both optional.

If two xsl:import-schema declarations specify the same namespace, or if both specify no namespace, then only the one with highest import precedence is used. [ERR023] It is a static error if two xsl:import-schema declarations for the same namespace have the same import precedence, unless there is another xsl:import-schema declaration for this namespace that has higher import precedence.

After discarding any xsl:import-schema declarations under the above rule, the effect of the remaining xsl:import-schema declarations is the same as the effect of importing a single hypothetical schema that consists entirely of xs:import elements corresponding one-for-one with the xsl:import-schema declarations in the stylesheet, with the following correspondence:

• The order of xs:import elements is in increasing order of the import precedence of the corresponding xsl:import-schema declarations, and in declaration order where two declarations have the same import precedence.

• The namespace attribute of the xs:import element is copied from the namespace attribute of the xsl:import-schema declaration if present, and is absent if it is absent.

• The schemaLocation attribute of the xs:import element is copied from the schema-location attribute of the xsl:import-schema declaration if present, and is absent if it is absent.

• The base URI of the xs:import element is the same as the base URI of the xsl:import-schema declaration.

Conflicts (multiple definitions of the same name) are handled as defined in [XML Schema], assuming that all the imported definitions are assembled into one schema using the process described above.

Note:

The namespace attribute indicates that a schema for the given namespace is required by the stylesheet. This information may be enough on its own to enable an implementation to locate the required schema components. The namespace attribute may be omitted to indicate that a schema for names in no namespace is being imported. Note that the zero-length string is not a valid namespace URI, and is therefore not a valid value for the namespace attribute. The schema-location attribute gives the URI of a location where a schema document or other resource containing the required definitions may be found. A schema-aware XSLT processor must have the capability to process an XML Schema that exists at this location in the form of a source XML document; implementations may also be able to access equivalent information held in other forms, for example a compiled XML Schema, or type information expressed using some other schema language. Any xs:import (or xs:include and xs:redefine elements in an imported schema are processed recursively.

[ERR024] It is a static error if the processor is not able to locate a schema using the namespace and/or schema-location attributes , or if the document that it locates is neither a valid XML Schema nor any other resource that the implementation can process.

[ERR025] It is a static error if both the namespace and the schema-location attributes are specified, and the schema that is located is not a schema for the specified namespace.

[ERR026] It is a static error if the schema-location attribute is omitted, and the namespace attribute identifies a namespace whose schema is not known to the XSLT processor.

The use of a namespace in an xsl:import-schema declaration does not by itself make the namespace available for use in the stylesheet. If names from the namespace are used within the stylesheet module, a prefix must be associated with the namespace by means of a namespace declaration, in the normal way.

The precise way in which an implementation uses the namespace and/or schema-location attributes to locate schema definitions is implementation-defined.

Additional types may be imported into a stylesheet using implementation-defined mechanisms. For example, the mechanisms used to define extension functions (see 18.1 Extension Functions) may also be used to import the types used in the interface to such functions.

4.1 Whitespace Stripping

The source document supplied as input to the transformation process may contain whitespace nodes (that is, text nodes consisting solely of whitespace characters) that are of no interest, and that do not need to be retained by the transformation. Conceptually, such whitespace nodes may be removed from the tree before the transformation commences. This process is referred to as whitespace stripping. The source tree itself must not be modified: the processor may implement whitespace stripping either by creating a copy of the tree from which the whitespace nodes have been removed, or by working on a virtual tree in which the whitespace nodes are treated as if they were absent.

The stripping process takes as input a set of element names whose child whitespace nodes must be preserved. The stripping process is applied to both stylesheets and source documents, but the set of whitespace-preserving element names is determined differently for stylesheets and for source documents.

Note:

Where multiple transformations are to be applied to the same source document, a useful optimization is to do the whitespace stripping only once. Implementations may therefore allow whitespace stripping to be controlled as a separate operation from the rest of the transformation process.

A text node is preserved if any of the following apply:

• The element name of the parent of the text node is in the set of whitespace-preserving element names.

• The text node contains at least one non-whitespace character. As in XML, a whitespace character is #x20, #x9, #xD or #xA.

• An ancestor element of the text node has an xml:space attribute with a value of preserve, and no closer ancestor element has xml:space with a value of default.

Otherwise, the text node is stripped.

The xml:space attributes are not removed from the tree.

Note:

This implies that if an xml:space attribute is specified on a literal result element, it will be included in the result.

For stylesheets, the set of whitespace-preserving element names consists of just xsl:text.

Processing instructions and comments in a stylesheet module are ignored: the stylesheet module is treated as if the processing instructions and comments were not there. This also means that sibling text nodes that are separated by a processing instruction or comment in a stylesheet module are concatenated into a single text node; and a text node is classified as a whitespace text node for the purpose of whitespace stripping only after this concatenation has taken place.

The content model for some XSLT elements (for example xsl:stylesheet and xsl:choose) does not permit text nodes as children of these elements. If the xml:space="preserve" attribute is used to suppress the stripping of whitespace text nodes within such elements, then any whitespace used for the layout of such elements will be retained in the stylesheet tree in the form of whitespace text nodes. Such text nodes must not be signaled as an error. [ERR027] Within an XSLT element that is required to be empty, any content other than comments or processing instructions, including any whitespace-only text node preserved using the xml:space="preserve" attribute, is a static error.

<!-- Category: declaration -->
<xsl:strip-space
  elements = tokens />

<!-- Category: declaration -->
<xsl:preserve-space
  elements = tokens />

For source documents, the set of whitespace-preserving element names is specified by xsl:strip-space and xsl:preserve-space declarations. Whether an element name is included in the set of whitespace-preserving names is determined by the best match amongst xsl:strip-space or xsl:preserve-space declarations: it is included if and only if there is no match or the best match is an xsl:preserve-space element. The xsl:strip-space and xsl:preserve-space elements each have an elements attribute whose value is a whitespace-separated list of NameTests; an element name matches an xsl:strip-space or xsl:preserve-space element if it matches one of the NameTests. An element matches a NameTest if and only if the NameTest would be true for the element as an XPath node test. When more than one xsl:strip-space and xsl:preserve-space element matches, the best matching element is determined by the best matching NameTest. This is determined in the same way as with template rules:

• First, any match with lower import precedence than another match is ignored.

• Next, any match that has a lower default priority than the default priority of another match is ignored.

[ERR028] It is a dynamic error if this leaves more than one match. This is a recoverable error. The processor must either signal the error, of must recover by choosing, from amongst the matches that are left, the one that occurs last in declaration order.

Note:

A source document is supplied as input to the XSLT processor in the form of a tree. Nothing in this specification states that this tree must be built by parsing an XML document; nor does it state that the application that constructs the tree is required to treat whitespace in any particular way. The provisions in this section relate only to whitespace text nodes that are present in the tree supplied as input to the processor. In particular, the processor cannot preserve whitespace text nodes unless they were actually present in the supplied tree.

4.2 Disable Output Escaping

If an implementation supports the disable-output-escaping attribute of xsl:text, xsl:value-of, and xsl:attribute (see 20.2 Disabling Output Escaping), then the data model for trees constructed by the processor is augmented with a boolean value representing the value of this property. This boolean value, however, can be set only within a final result tree that is being passed to the serializer.

Conceptually, each character in a text node on such a result tree, and each attribute node, has a boolean property indicating whether the serializer should disable the normal rules for escaping of special characters (for example, outputting of & as &) in respect of this character or attribute node.

Note:

In practice, the nodes in a final result tree will often be streamed directly from the XSLT processor to the serializer. In such an implementation, disable-output-escaping is not so much a property stored with nodes in the tree, but an out-of-band signal passed across the interface between the XSLT processor and the serializer.

5.1 Qualified Names

The name of a stylesheet-defined object, specifically a named template, a mode, an attribute set, a key, a named sort specification, a decimal-format, a date-format, a variable or parameter, a stylesheet function, a named output definition, or a character map is specified as a QName.

A QName is always written in the form (NCName ":")? NCName, that is, a local name optionally preceded by a namespace prefix. When two QNames are compared, however, they are considered equal if the corresponding expanded-QNames are the same.

An expanded-QName is a pair of values containing a local name and an optional namespace URI. A QName is expanded by replacing the namespace prefix with the corresponding namespace URI, from the namespace declarations that are in scope at the point where the QName is written. Two expanded-QNames are equal if the namespace URIs are the same (or both absent) and the local names are the same.

QNames may occur either as the value of an attribute node in a stylesheet module, or within an XPath expression contained in such an attribute node, or as the result of evaluating an XPath expression contained in such an attribute node. The element containing this attribute node is referred to as the defining element of the QName.

If the QName has a prefix, then the prefix is expanded into a URI reference using the namespace declarations in effect on its defining element. The expanded-QName consisting of the local part of the name and the possibly null URI reference is used as the name of the object. The default namespace (as defined by a namespace declaration of the form xmlns="some.uri") is not used for unprefixed names.

In the case of an unprefixed QName used as a NameTest within an XPath expression (see 5.2 Expressions) , and in certain other contexts, the namespace to be used in expanding the QName may be specified by means of the [xsl:]xpath-default-namespace attribute, as specified in 5.4 Unprefixed Names in Expressions and Patterns.

[ERR029] In the case of a QName used as the value of an attribute in the stylesheet, or appearing within the text of an XPath expression in the the stylesheet, it is a static error if the defining element has no namespace node whose name matches the prefix of the QName.

[ERR030] In the case of a QName produced by evaluating an XPath expression, it is a dynamic error if the defining element has no namespace node whose name matches the prefix of the QName. The error is a dynamic error even if the value of the expression is known statically, for example if the QName is written as a string literal. The required action depends on the defining element.

5.2 Expressions

XSLT uses the expression language defined by XPath 2.0 [XPath 2.0]. Expressions are used in XSLT for a variety of purposes including:

• selecting nodes for processing;

• specifying conditions for different ways of processing a node;

• generating text to be inserted in the result tree.

Within this specification, the term XPath expression, or simply expression, means a string that matches the production Expr defined in [XPath 2.0].

An XPath expression may occur as the value of certain attributes on XSLT-defined elements, and also within curly braces in attribute value templates.

[ERR031] Except where otherwise stated, it is a static error if the value of such an attribute , or the text between curly braces in an attribute value template, does not match the XPath production Expr, or if it fails to satisfy other static constraints defined in the XPath specification, for example that all variable references must refer to variables that are in scope.

[ERR032] The transformation fails with a dynamic error if any XPath expression is evaluated and raises a dynamic error. The processor must signal the error.

The context within a stylesheet where an XPath expression appears may specify the required type of the expression. The required type indicates the data type of value that the expression is expected to return. If no required type is specified, the expression may return any value: in effect, the required type is then item()*.

Except where otherwise indicated, the actual value of an expression is converted to the required type using the argument conversion rules. These are the rules defined in [XPath 2.0] for converting the supplied argument of a function call to the required type of that argument, as defined in the function signature. The relevant rules are those that apply when the "XPath 1.0 backwards compatibility flag" is not set.

[ERR033] It is a type error if an XPath expression raises a type error, or if the type of the XPath expression is incompatible with the required type. The processor must signal the error.

The context for evaluation of an XPath expression is determined according to the following rules. The context has two parts: the static context, and the dynamic expression evaluation context.

The static context depends on the element in the stylesheet that contains the attribute holding the XPath expression ("the containing element") as follows:

• The in-scope namespaces are the namespace declarations that are in scope for the containing element.

• The default namespace for element names and type names is the namespace defined by the innermost [xsl:]xpath-default-namespace attribute, as described in 5.4 Unprefixed Names in Expressions and Patterns. The value of this attribute is a namespace URI.

• The default namespace for function names is the standard function namespace , defined in [Functions and Operators]. This means that it is not necessary to declare this namespace in the stylesheet, nor to use the prefix xf used in the specification of the core functions.

• The in-scope schema definitions includes the built-in types of XML Schema (see [XML Schema]), the built-in XPath types, any type definitions and element and attribute declarations imported using the xsl:import-schema declaration (see 3.10 Importing Schema Components), and any additional definitions imported using implementation-defined mechanisms.

• The in-scope variables are the variable binding elements that are in scope for the containing element (see 9 Variables and Parameters).

• The in-scope functions are the core functions defined by XPath, the additional functions defined in this specification, the stylesheet functions defined in the stylesheet, plus any extension functions bound using implementation-defined mechanisms (see 18 Extensibility and Fallback). [ERR034] It is a dynamic error for an expression to call any function that is not included in the in-scope functions. The processor must signal the error, but only if the function call is actually evaluated.

• The in-scope collations are implementation-defined.

• The default collation is implementation-defined.

  Note:

  Implementations should provide a mechanism allowing the user to select the default collation for a transformation.

• The base URI is the base URI of the containing element.

• The XPath 1.0 backwards compatibility flag is set to true if and only if the XSLT instruction containing the XPath expression occurs in part of the stylesheet where backwards compatible behavior is enabled (see 3.6 Backwards-Compatible Processing).

The evaluation context, which includes the focus, is determined as follows:

• The variable values are the current values of the in-scope variable binding elements.

Where the containing element is an instruction or a literal result element, the focus is established as follows. In other cases, the rules are given for the specific containing element.

• The initial context item, context position, and context size for the XPath expression are the same as the context item, context position, and context size for the evaluation of the containing instruction or literal result element. (Note that these values may change for evaluation of sub-expressions within the XPath expression, according to the XPath rules.)

5.3 Patterns

A template rule identifies the nodes to which it applies by means of a pattern. As well as being used in template rules, patterns are used for numbering (see 12 Numbering), for grouping (see 14 Grouping), and for declaring keys (see 16.3 Keys).

A pattern specifies a set of conditions on a node. A node that satisfies the conditions matches the pattern; a node that does not satisfy the conditions does not match the pattern. The syntax for patterns is a subset of the syntax for expressions. As explained in detail below, a node matches a pattern if the node can be selected by deriving an equivalent expression, and evaluating this expression with respect to some possible context.

[ERR035] Where an attribute is defined to contain a pattern, it is a static error if the pattern does not match the production Pattern. Every pattern is a legal XPath expression, but the converse is not true: 2+2 is an example of a legal XPath expression that is not a pattern. The XPath expressions that can be used as patterns are those that match the grammar for Pattern, given below.

Informally, a Pattern is a set of path expressions separated by |, where each step in the path expression is constrained to be an AxisStep that uses only the child or attribute axes. Patterns may also use the // operator. Predicates in a pattern (the construct enclosed between square brackets) can contain arbitrary XPath expressions in the same way as predicates in a path expression.

Patterns may start with an id or key function call, provided that the value to be matched is supplied as either a literal or a reference to a variable or parameter, and the key name (in the case of the key function) is supplied as a string literal. These patterns will never match a node in a tree whose root is not a document node.

If a pattern occurs in part of the stylesheet where backwards compatible behavior is enabled (see 3.6 Backwards-Compatible Processing), then the semantics of the pattern are defined on the basis that the equivalent XPath expression is evaluated with the XPath 1.0 backwards compatibility flag set to true.

Patterns

The constructs NodeTest, Literal, StringLiteral, and Expr are part of the XPath expression language, and are defined in [XPath 2.0].

The meaning of a pattern is defined formally as follows.

First we define the concept of an equivalent expression. In general, the equivalent expression is the XPath expression that takes the same lexical form as the pattern as written. However, if the pattern contains a PathPattern that is a RelativePathPattern, then the first PatternStep of this RelativePathPattern is adjusted to allow it to match a parentless element or attribute node. If this first PatternStep uses the child axis (explicitly or implicitly), and if the NodeTest in this PatternStep is not node(), then the axis in this step is replaced by child-or-top::. If this PatternStep uses the attribute axis, then the axis is replaced by attribute-or-top::.

The axes child-or-top and attribute-or-top are introduced only for definitional purposes, they cannot be used explicitly in a user-written pattern or expression. They are defined as follows:

• If the context node is a parentless element, comment, processing-instruction, text, or document node then the child-or-top axis selects the context node; otherwise it selects the children of the context node. It is a forwards axis whose principal node kind is element.

• If the context node is a parentless attribute node then the attribute-or-top axis selects the context node; otherwise it selects the attributes of the context node. It is a forwards axis whose principal node kind is attribute.

Note:

The purpose of this adjustment is to ensure that a pattern such as person matches any element named person, even if it has no parent; and similarly, that the pattern @width matches any attribute named width, even a parentless attribute. The rule also ensures that a pattern using a NodeTest of the form document-node(...) matches a document node, though for backwards compatibility reasons, it remains true that the pattern node() will not match a document node (or any other parentless node).

To determine whether a node N matches a pattern PAT, evaluate the expression //(PAT) with a singleton focus based on N. If the result is a sequence of nodes that includes N, then node N matches the pattern; otherwise node N does not match the pattern. In this expression, PAT is the equivalent expression as defined above.

Note:

Although the semantics of patterns are specified formally in terms of expression evaluation, it is possible to understand pattern matching using a different model. In a pattern, | indicates alternatives; a pattern with one or more | separated alternatives matches if any one of the alternatives matches. A pattern such as book/chapter/section can be examined from right to left. A node will only match this pattern if it is a section element; and then, only if its parent is a chapter; and then, only if the parent of that chapter is a book. When the pattern uses the // operator, one can still read it from right to left, but this time testing the ancestors of a node rather than its parent. For example appendix//section matches every section element that has an ancestor appendix element. The formal definition, however, is useful for understanding the meaning of a pattern such as para[1]. This matches any node selected by the expression //(child-or-top::para[1]): that is, any para element that is the first para child of its parent , or a para element that has no parent.

The pattern node() matches all nodes selected by the expression //(node()), that is, all element, text, comment, and processing instruction nodes. It does not match attribute or namespace nodes because the expression does not select nodes using the attribute or namespace axes. It does not match document nodes, or other parentless nodes, because for backwards compatibility reasons the child axis is not replaced by child-or-top in this case.

Note:

An implementation, of course, may use any algorithm it wishes for evaluating patterns, so long as the result corresponds with the formal definition above. An implementation that followed the formal semantics by evaluating the equivalent expression and then testing the membership of a specific node in the result would probably be very inefficient.

5.4 Unprefixed Names in Expressions and Patterns

The attribute [xsl:]xpath-default-namespace (see 3.3 Standard Attributes) may be used on an element in the stylesheet to define the namespace that will be used for an unprefixed element name or type name within an XPath expression, and in certain other contexts listed below.

For any element in the stylesheet, this attribute has an effective value, which is the value of the [xsl:]xpath-default-namespace on that element or on the innermost containing element that specifies such an attribute, or the zero-length string if no containing element specifies such an attribute.

The value of the attribute is the namespace URI to be used.

For any element in the stylesheet, the effective value of this attribute determines the value of the default namespace for element and type names in the static context of any XPath expression contained in an attribute of that element. The effect of this is specified in [XPath 2.0]; in summary, it determines the namespace used for any unprefixed type name in the SequenceType production, and for any element name appearing in a path expression or in the SequenceType production.

The effective value of this attribute similarly applies to:

• any unprefixed element name or type name used in a pattern within its scope

• any unprefixed element name used in the elements attribute of the xsl:strip-space or xsl:preserve-space instructions within its scope

• any unprefixed element name or type name used in the as attribute of any XSLT instructions within its scope.

• any unprefixed type name used in the type attribute of any XSLT instructions within its scope.

The [xsl:]xpath-default-namespace attribute must be in the XSLT namespace if and only if its parent element is not in the XSLT namespace.

If the effective value of the attribute is a zero-length string, which will be the case if it is explicitly set to a zero-length string or if it is not specified at all, then an unprefixed element name or type name refers to a name that is in no namespace. The default namespace (as defined by an xmlns="some-uri" declaration) is not used.

The attribute does not affect other names, for example function names, variable names, or names used as arguments to the key or system-property functions.

5.5 Attribute Value Templates

In an attribute that is designated as an attribute value template, such as an attribute of a literal result element, an expression can be used by surrounding the expression with curly braces ({}).

An attribute value template consists of an alternating sequence of fixed parts and variable parts. A variable part consists of an XPath expression enclosed in curly braces ({}). A fixed part may contain any characters, except that a left curly brace must be written as {{ and a right curly brace must be written as }}.

Note:

An expression within a variable part may contain an unescaped curly brace within a StringLiteral. It may also contain a construct, such as a comment, that is delimited by paired opening and closing braces.

[ERR036] It is a static error if a left curly brace appears in an attribute value template without a matching right curly brace.

[ERR037] It is a static error if the string contained between matching curly braces in an attribute value template does not match the XPath production Expr.

[ERR038] It is a static error if a right curly brace occurs in an attribute value template outside an expression without being followed by a second right curly brace. A right curly brace inside a StringLiteral in an expression is not recognized as terminating the expression.

The result of evaluating an attribute value template is referred to as the effective value of the attribute. 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 braces ({{ or }}) by the corresponding single curly brace. The expansion of a variable part is obtained by evaluating the enclosed XPath expression and converting the resulting value to a string. This conversion is done by atomizing the result of the expression using the procedure defined in [XPath 2.0], and then converting each of the atomic values in the atomized sequence to a string, adding a single space after each value other than the last. If the atomized sequence is empty, the result is a zero-length string.

If backwards compatible behavior is enabled for the attribute, the rules for converting the value of the expression to a string are modified as follows. After atomizing the result of the expression, all items other than the first item in the resulting sequence are discarded, and the effective value is obtained by converting the first item in the sequence to a string. If the atomized sequence is empty, the result is a zero-length string.

Curly braces are not treated specially in an attribute value in an XSLT stylesheet unless the attribute is specifically designated as one that permits an attribute value template; in an element syntax summary, the value of such attributes is surrounded by curly braces.

Note:

Not all attributes are interpreted as attribute value templates. Attributes whose value is an expression or pattern, attributes of declaration elements and attributes that refer to named XSLT objects are not interpreted as attribute value templates. In addition, xmlns attributes are not interpreted as attribute value templates: this is because they must be interpreted in the same way by the XML parser and the XSLT processor.

<xsl:variable name="image-dir">/images</xsl:variable>

<xsl:template match="photograph">
<img src="{$image-dir}/{href}" width="{size/@width}"/>
</xsl:template>

<photograph>
  <href>headquarters.jpg</href>
  <size width="300"/>
</photograph>

<img src="/images/headquarters.jpg" width="300"/>

<temperature readings="{10.32, 5.50, 8.31}"/>

<temperature readings="10.32 5.5 8.31"/>

Curly braces are not recognized recursively inside expressions.

<a href="#{id({@ref})/title}">

<a href="#{id(@ref)/title}">

5.6 Sequence Constructors

Note:

The term sequence constructor replaces template as used in XSLT 1.0. The change is made partly for clarity (to avoid confusion with template rules and named templates), but also to reflect a more formal definition of the semantics. Whereas XSLT 1.0 described a template as a sequence of instructions that write to the result tree, XSLT 2.0 describes a sequence constructor as something that can be evaluated to return a sequence of items; what happens to these items depends on the containing instruction.

Many XSLT elements (including literal result elements) are defined to take as their content a sequence constructor.

A sequence constructor is a sequence of sibling nodes in the stylesheet that can be evaluated to return a sequence of nodes and atomic values. The way that the resulting sequence is used depends on the containing instruction.

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

• Text nodes appearing in the stylesheet (if they have not been removed in the process of whitespace stripping: see 4.1 Whitespace Stripping) are copied to create a new parentless text node in the result sequence.

• Literal result elements are evaluated to create a new parentless element node, having the same name as the literal result element, which is added to the result sequence: see 11.1 Literal Result Elements

• XSLT instructions produce a sequence of zero, one, or more items as their result. These items are added to the result sequence. For most XSLT instructions, these items are nodes, but some instructions (xsl:sequence and xsl:copy-of) can also produce atomic values. 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. The xsl:sequence instruction may return atomic values, or existing nodes from a source document.

• Extension instructions also produce a sequence of items as their result. The items in this sequence are added to the result sequence.

There are several ways the result of a sequence constructor may be used.

• The sequence may be bound to a variable or returned from a stylesheet function, in which case it becomes available as a value to be manipulated in arbitrary ways by XPath expressions. The sequence is bound to a variable when the sequence constructor appears within one of the elements xsl:variable, xsl:param, or xsl:with-param, when this instruction has an as attribute that indicates that the constructed sequence is required as the value. For details, see 9.3 Values of Variables and Parameters. The sequence is returned from a stylesheet function when the sequence constructor appears within the xsl:function element.

  Note:

  This will typically expose to the stylesheet elements, attributes, and other nodes that have not yet been attached to a 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 / selects the root node of the tree containing the context node, which will not necessarily be a document node. The expression /E selects an E element child of the root node of the tree: if the root node is itself an E element, this expression will not select it. Parentless attribute nodes require particular care because they have no namespace nodes associated with them. This means, for example, that the name function will not be able to determine a prefix to use when reporting the name of the attribute. When a parentless attribute node has content containing namespace prefixes (for example, a QName or an XPath expression) then there is no information allowing 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. It will then typically be concatenated with other sequences before eventually being returned to an instruction that processes it. This happens when the instruction containing the sequence constructor is xsl:if, xsl:choose, xsl:when, xsl:otherwise, xsl:sequence, xsl:call-template, xsl:apply-templates, xsl:apply-imports, xsl:next-match, xsl:for-each, xsl:for-each-group, xsl:analyze-string, xsl:matching-substring, xsl:non-matching-substring, or xsl:fallback.

• 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:element, xsl:copy, 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.6.1 Constructing Complex Content.

• The sequence may be used to construct the string value of an attribute 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:namespace, xsl:comment, or xsl:processing-instruction. For details, see 5.6.2 Constructing Simple Content.

<td>
<xsl:attribute name="valign">top</xsl:attribute>
<xsl:value-of select="@description"/>
</td>

6.1 Defining Templates

<!-- Category: declaration -->
<xsl:template
  match = pattern
  name = qname
  priority = number
  mode = tokens
  as = sequence-type>
  <!-- Content: (xsl:param*, sequence-constructor) -->
</xsl:template>

An xsl:template declaration defines a template, which contains a sequence of instructions for creating nodes and/or atomic values. A template can serve either as a template rule, invoked by matching nodes against a pattern, or as a named template, invoked explicitly by name. It is also possible for the same template to serve in both capacities.

An xsl:template element must have either a match attribute or a name attribute, or both. If it has a match attribute, then it is a template rule. If it has a name attribute, then it is a named template. An xsl:template element that has no match attribute must have no mode attribute and no priority attribute.

A template may be invoked in a number of ways, depending on whether it is a template rule, a named template, or both. The result of invoking the template is the result of evaluating the sequence constructor contained in the xsl:template element. If an as attribute is present, the as attribute defines the required type of the result. [ERR051] The result of evaluating the sequence constructor is converted to the required type using the argument conversion rules. A type error occurs if this conversion is unsuccessful. Like other type errors, this error may be signaled statically if it can be detected statically.

If no as attribute is specified, the default value is item()*, which permits any value. No conversion then takes place.

6.2 Defining Template Rules

This section describes template rules. The use of named templates is described in 10.1 Named Templates.

A template rule is specified using the xsl:template element with a match attribute. The match attribute is a Pattern that identifies the source node or nodes to which the rule applies. The result of applying the template rule is the result of evaluating the sequence constructor contained in the xsl:template element, with the matching node used as the context node.

This is an <emph>important</emph> point.

<xsl:template match="emph">
  <fo:wrapper font-weight="bold">
    <xsl:apply-templates/>
  </fo:wrapper>
</xsl:template>

As described in the next section, the xsl:apply-templates element can be used to process the children of a source element, and their children, recursively.

6.3 Applying Template Rules

<!-- Category: instruction -->
<xsl:apply-templates
  select = node-sequence-expression
  mode = token>
  <!-- Content: (xsl:sort | xsl:with-param)* -->
</xsl:apply-templates>

The xsl:apply-templates instruction takes as input a sequence of nodes in the source tree, and produces as output a sequence of items; these will often be nodes to be added to the result tree.

If the instruction has one or more xsl:sort children, then then input sequence is sorted as described in 13 Sorting.

Each node in the input sequence is processed by finding a template rule whose pattern matches that node. If there is more than one, the best among them is chosen, using rules described below; if there is none, a built-in template rule is used. The chosen template rule is evaluated. The rule that matches the Nth node in the sequence (after sorting) is evaluated with that node as the context item, with N as the context position, and with the length of the sequence as the context size. Each template rule that is evaluated produces a sequence of items as its result. The resulting sequences (one for each node in the input sequence) are then concatenated, to form a single sequence. They are concatenated retaining the order of the nodes in the input sequence after sorting. The final concatenated sequence forms the result of the xsl:apply-templates instruction, and is passed to its parent instruction .

<xsl:template match="chapter">
  <fo:block>
    <xsl:apply-templates/>
  </fo:block>
</xsl:template>

In the absence of a select attribute, the xsl:apply-templates instruction processes all of the children of the context node, including text nodes. [ERR052] It is a dynamic error if the context item is not a node. This is a recoverable error. The processor must either signal the error, or must recover by returning an empty sequence.

Note:

If stripping of whitespace nodes has not been enabled for an element, then all whitespace in the content of the element will be processed as text, and thus whitespace between child elements will count in determining the position of a child element as returned by the position function. This effect can be prevented by stripping whitespace text nodes as specified in 4.1 Whitespace Stripping.

A select attribute can be used to process nodes selected by an expression instead of processing all children. The value of the select attribute is an expression. The expression must evaluate to a sequence of nodes (it can contain zero, one, or more nodes). The order of the result sequence will be the same as the order of this sequence, unless a sorting specification is present (see 13 Sorting).

[ERR053] It is a type error if the sequence returned by the select expression contains an item that is not a node. This is a recoverable error. The processor must either signal the error, or must recover by ignoring the items that are not nodes. As with other type errors, the error may be signaled statically if it can be detected statically.

Note:

In XSLT 1.0, the select attribute selected a set of nodes, which by default were processed in document order. In XSLT 2.0, it selects a sequence of nodes. In cases that would have been valid in XSLT 1.0, the expression will return a sequence of nodes in document order, so the effect is the same.

<xsl:template match="author-group">
  <fo:wrapper>
    <xsl:apply-templates select="author"/>
  </fo:wrapper>
</xsl:template>

<xsl:template match="author-group">
  <fo:wrapper>
    <xsl:apply-templates select="author/given-name"/>
  </fo:wrapper>
</xsl:template>

<xsl:template match="book">
  <fo:block>
    <xsl:apply-templates select=".//heading"/>
  </fo:block>
</xsl:template>

<xsl:template match="employee">
  <fo:block>
    Employee <xsl:apply-templates select="name"/> belongs to group
    <xsl:apply-templates select="ancestor::department/group"/>
  </fo:block>
</xsl:template>

<xsl:template match="product">
  <table>
    <xsl:apply-templates select="*"/>
  </table>
</xsl:template>

<xsl:template match="product/*" priority="3">
  <tr>
    <td><xsl:value-of select="name()"/></td>
    <td><xsl:next-match/></td>
  </tr>
</xsl:template>

<xsl:template match="product/element(*, xs:decimal) | 
                     product/element(*, xs:double)" priority="2">  
  <xsl:value-of select="format-number(xs:double(.), '#,###0.00')"/>
</xsl:template>

<xsl:template match="product/element(*, xs:date)" priority="2">
  <xsl:value-of select="format-date(., '[Mn] [D], [Y]')"/>
</xsl:template>

<xsl:template match="product/* priority="1.5">
  <xsl:value-of select="."/>
</xsl:template>

<xsl:template match="product">
  <table>
    <xsl:apply-templates select="sales/domestic"/>
  </table>
  <table>
    <xsl:apply-templates select="sales/foreign"/>
  </table>
</xsl:template>

Note:

It is possible for there to be two matching descendants where one is a descendant of the other. This case is not treated specially: both descendants will be processed as usual. For example, given a source document <doc><div><div></div></div></doc> the rule <xsl:template match="doc"> <xsl:apply-templates select=".//div"/> </xsl:template> will process both the outer div and inner div elements.

Note:

Typically, xsl:apply-templates is used to process only nodes that are descendants of the context node. Such use of xsl:apply-templates cannot result in non-terminating processing loops. However, when xsl:apply-templates is used to process elements that are not descendants of the context node, the possibility arises of non-terminating loops. For example, <xsl:template match="foo"> <xsl:apply-templates select="."/> </xsl:template> Implementations may be able to detect such loops in some cases, but the possibility exists that a stylesheet may enter a non-terminating loop that an implementation is unable to detect. This may present a denial of service security risk.

6.4 Conflict Resolution for Template Rules

It is possible for a node in a source document to match more than one template rule. The template rule to be used is determined as follows:

1. First, all matching template rules that have lower import precedence than the matching template rule or rules with the highest import precedence are eliminated from consideration.

2. Next, all matching template rules that have lower priority than the matching template rule or rules with the highest priority are eliminated from consideration. The priority of a template rule is specified by the priority attribute on the template rule. [ERR054] The value of this must be a decimal number (positive or negative), matching the production NumericLiteral with an optional leading minus sign (-).

   If no priority attribute is specified on the xsl:template element, the default priority is computed as follows:

   • If the pattern contains multiple alternatives separated by |, then the template rule is treated equivalently to a set of template rules, one for each alternative. However, it is not an error if a node matches more than one of the alternatives.

   • If the pattern has the form /, then the priority is -0.5.

   • If the pattern has the form of a QName optionally preceded by a PatternAxis or has the form processing-instruction(StringLiteral) optionally preceded by a PatternAxis, then the priority is 0.

   • If the pattern has the form of an ElementTest or AttributeTest, optionally preceded by a PatternAxis, 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, while the symbols * and @* represent themselves. A SchemaContextPath and LocalName may be specified instead of an element or attribute name; this does not affect the priority. The presence or absence of the keyword nillable does not affect the priority.

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

   • If the pattern has the form of a DocumentTest, then if it includes no ElementTest the priority is -0.5. If if does include an ElementTest, then the priority is the same as the priority of that ElementTest, computed according to the table above.

   • If the pattern has the form NCName:* or *:NCName, optionally preceded by a PatternAxis, then the priority is -0.25.

   • If the pattern is any other NodeTest, optionally preceded by a PatternAxis, then the priority is -0.5.

   • Otherwise, the priority is 0.5.

   Note:

   In many cases this means that highly selective patterns have higher priority than less selective patterns. The most common kind of pattern (a pattern that tests for a node of a particular kind, with a particular expanded-QName or a particular type) has priority 0. The next less specific kind of pattern (a pattern that tests for a node of a particular kind and an expanded-QName with a particular namespace URI) has priority -0.25. Patterns less specific than this (patterns that just test for nodes of a given kind) have priority -0.5. Patterns that specify both the name and the required type have a priority of +0.25, putting them above patterns that only specify the name or the type. Patterns more specific than this, for example patterns that include predicates or that specify the ancestry of the required node, have priority 0.5. However, it is not invariably true that a more selective pattern has higher priority than a less selective pattern. For example, the priority of the pattern node()[self::*] is higher than that of the pattern salary. Similarly, the patterns attribute(*, xs:decimal) and attribute(*, xs:short) have the same priority, despite the fact that the latter pattern matches a subset of the nodes matched by the former. Therefore, to achieve clarity in a stylesheet it is good practice to allocate explicit priorities.

[ERR055] It is a dynamic error if this leaves more than one matching template rule. This is a recoverable error. The processor must either signal the error, or must recover by choosing, from amongst the matching template rules that are left, the one that occurs last in declaration order.

6.5 Modes

Modes allow a node in the source tree to be processed multiple times, each time producing a different result. They also allow different sets of template rules to be active when processing different trees, for example when processing documents loaded using the document function (see 16.1 Multiple Source Documents) or when processing temporary trees (see 9.4 Temporary Trees)

Modes are identified by a QName, except for the default mode, which is unnamed.

A template rule is applicable to one or more modes. The modes to which it is applicable are defined by the mode attribute of the xsl:template element. If the attribute is omitted, then the template rule is applicable to the default mode. If the attribute is present, then its value must be a space-separated list of tokens, each of which defines a mode to which the template rule is applicable. Each token must either be a QName, which is expanded as described in 5.1 Qualified Names to define the name of the mode, or it must be the token #default, to indicate that the template rule is applicable to the default mode, or it must be the token #all, to indicate that the template rule is applicable to all modes.

[ERR056] It is a static error if the same token is included more than once in the list or if the token #all appears together with any other value.

The xsl:apply-templates element also has an optional mode attribute. The value of this attribute must either be a QName, which is expanded as described in 5.1 Qualified Names to define the name of a mode, or the token #default, to indicate that the default mode is to be used, or the token #current, to indicate that the current mode is to be used. If the attribute is omitted, the default mode is used.

When searching for a template rule to process each node selected by the xsl:apply-templates instruction, only those template rules that are applicable to the selected mode are considered.

At any point in the processing of a stylesheet, there is a current mode. When the transformation is initiated, the current mode is the default mode, unless a different initial mode has been supplied, as described in 2.3 Initiating a Transformation. Whenever an xsl:apply-templates instruction is evaluated, the current mode becomes the mode selected by this instruction. When a stylesheet function is called, the current mode becomes the default mode. No other instruction changes the current mode. On completion of the xsl:apply-templates instruction, or on return from a stylesheet function call, the current mode reverts to its previous value. The current mode is used when an xsl:apply-templates instruction uses the syntax mode="#current"; it is also used by the xsl:apply-imports and xsl:next-match instructions (see 6.7 Overriding Template Rules).

6.6 Built-in Template Rules

When a node is selected by xsl:apply-templates and there is no template rule in the stylesheet that can be used to process that node, a built-in template rule is evaluated instead. The built-in template rule for document nodes and elements nodes causes the children of the node to be processed; the built in rule for text nodes and attribute nodes causes the text to be copied to the result tree.

The built-in template rules apply to all modes.

The built-in rule for document nodes and element nodes is equivalent to calling xsl:apply-templates with no select attribute, and with the mode attribute set to #current. If the built-in rule was invoked with parameters, those parameters are passed on in the implicit xsl:apply-templates instruction.

For example, suppose the stylesheet contains the following instruction:

<xsl:apply-templates select="title" mode="mm">
  <xsl:with-param name="init" select="10"/>
</xsl:apply-template>

If there is no explicit template rule that matches the title element, then the following implicit rule is used:

<xsl:template match="title" mode="#all">
  <xsl:with-param name="init"/>
  <xsl:apply-templates mode="#current">
    <xsl:with-param name="init" select="$init"/>
  </xsl:apply-templates>
</xsl:template>

The built-in template rule for text and attribute nodes returns a text node containing the string value of the context node, unless the string value is zero-length, in which case it returns an empty sequence. It is effectively:

<xsl:template match="text()|@*" mode="#all">
  <xsl:value-of select="."/>
</xsl:template>

The built-in template rule for processing instructions and comments does nothing (it returns the empty sequence).

<xsl:template match="processing-instruction()|comment()" mode="#all"/>

The built-in template rule for namespace nodes is also to do nothing. There is no pattern that can match a namespace node; so, the built-in template rule is the only template rule that is applied for namespace nodes.

The built-in template rules have lower import precedence than all other template rules. Thus, the stylesheet author can override a built-in template rule by including an explicit template rule.

6.7 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.4 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 other template rules of lower precedence and/or priority.

At any point in the processing of a stylesheet, there may be a current template rule. Whenever a template rule is chosen by matching a pattern, the template rule becomes the current template rule for the evaluation of the rule's sequence constructor. When an xsl:for-each or xsl:for-each-group instruction is evaluated, or when a stylesheet function is called (see 10.3 Stylesheet Functions), the current template rule becomes null for the evaluation of that instruction or function.

The current template rule is not affected by invoking named templates (see 10.1 Named Templates) or named attribute sets (see 10.2 Named Attribute Sets). While evaluating a global variable or the default value of a stylesheet parameter (see 9.5 Global Variables and Parameters) the current template rule is null.

Note:

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, and is always a node.

Both xsl:apply-imports and xsl:next-match search for a template rule that matches the context node, and that is applicable to the current mode (see 6.5 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.

• 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.4 Conflict Resolution for Template Rules. That is, it considers all template rules with lower import precedence than the current template rule, plus the template rules that are at the same import precedence that have lower priority than the current template rule. If the processor has recovered from the error that occurs when two matching template rules have the same import precedence and priority, then it also considers all matching template rules with the same import precedence and priority that occur before the current template rule in declaration order.

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

An xsl:apply-imports or xsl:next-match element may use xsl:with-param child elements to pass parameters to the chosen template rule (see 10.1.1 Passing Parameters to Templates).

[ERR058] It is a dynamic error if xsl:apply-imports or xsl:next-match is evaluated when the current template rule is null. The processor must signal the error.

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

8.1 Conditional Processing with xsl:if

<!-- Category: instruction -->
<xsl:if
  test = expression>
  <!-- Content: sequence-constructor -->
</xsl:if>

The xsl:if element has a test attribute, which specifies an expression. The content is a sequence constructor.

The result of the xsl:if instruction depends on the effective boolean value of the expression in the test attribute. The rules for determining the effective boolean value of an expression are given in [XPath 2.0]: they are the same as the rules used for XPath conditional expressions.

If the effective boolean value of the expression is true, then the sequence constructor is evaluated, and the resulting node sequence is returned as the result of the xsl:if instruction; otherwise, an empty sequence is returned.

<xsl:template match="namelist/name">
  <xsl:apply-templates/>
  <xsl:if test="not(position()=last())">, </xsl:if>
</xsl:template>

<xsl:template match="item">
  <tr>
    <xsl:if test="position() mod 2 = 0">
       <xsl:attribute name="bgcolor">yellow</xsl:attribute>
    </xsl:if>
    <xsl:apply-templates/>
  </tr>
</xsl:template>

8.2 Conditional Processing with xsl:choose

<!-- Category: instruction -->
<xsl:choose>
  <!-- Content: (xsl:when+, xsl:otherwise?) -->
</xsl:choose>

<xsl:when
  test = expression>
  <!-- Content: sequence-constructor -->
</xsl:when>

<xsl:otherwise>
  <!-- Content: sequence-constructor -->
</xsl:otherwise>

The xsl:choose element selects one among a number of possible alternatives. It consists of a sequence of xsl:when elements followed by an optional xsl:otherwise element. Each xsl:when element has a single attribute, test, which specifies an expression. The content of the xsl:when and xsl:otherwise elements is a sequence constructor.

When an xsl:choose element is processed, each of the xsl:when elements is tested in turn (that is, in document order as the elements appear in the stylesheet), until one of the xsl:when elements is satisfied. An xsl:when element is satisfied if the effective boolean value of the expression in its test attribute is true. The rules for determining the effective boolean value of an expression are given in [XPath 2.0]: they are the same as the rules used for XPath conditional expressions.

The content of the first, and only the first, xsl:when element that is satisfied is evaluated, and the resulting sequence is returned as the result of the xsl:choose instruction. If no xsl:when element is satisfied, the content of the xsl:otherwise element is evaluated, and the resulting sequence is returned as the result of the xsl:choose instruction. If no xsl:when element is satisfied, and no xsl:otherwise element is present, the result of the xsl:choose instruction is an empty sequence.

Only the sequence constructor of the selected xsl:when or xsl:otherwise instruction is evaluated. The test expressions for xsl:when instructions after the selected one are not evaluated.

<xsl:template match="orderedlist/listitem">
  <fo:list-item indent-start='2pi'>
    <fo:list-item-label>
      <xsl:variable name="level"
                    select="count(ancestor::orderedlist) mod 3"/>
      <xsl:choose>
        <xsl:when test='$level=1'>
          <xsl:number format="i"/>
        </xsl:when>
        <xsl:when test='$level=2'>
          <xsl:number format="a"/>
        </xsl:when>
        <xsl:otherwise>
          <xsl:number format="1"/>
        </xsl:otherwise>
      </xsl:choose>
      <xsl:text>. </xsl:text>
    </fo:list-item-label>
    <fo:list-item-body>
      <xsl:apply-templates/>
    </fo:list-item-body>
  </fo:list-item>
</xsl:template>

9.1 Variables

<!-- Category: declaration -->
<!-- Category: instruction -->
<xsl:variable
  name = qname
  select = expression
  as = sequence-type>
  <!-- Content: sequence-constructor -->
</xsl:variable>

The xsl:variable element has a required name attribute, which specifies the name of the variable. The value of the name attribute is a QName, which is expanded as described in 5.1 Qualified Names.

The xsl:variable element has an optional as attribute, which specifies the required type of the variable. The value of the as attribute is a SequenceType, as defined in [XPath 2.0].

The value of the variable is computed using the expression given in the select attribute and/or the contained sequence constructor, as described in 9.3 Values of Variables and Parameters. This value is referred to as the supplied value of the variable.

[ERR059] If the as attribute is specified, then the supplied value of the variable is converted to the required type, using the argument conversion rules. It is a type error if this conversion fails. The processor must signal the error. As with other type errors, the error may be signaled statically if it can be detected statically.

If the as attribute is omitted, the supplied value of the variable is used directly, and no conversion takes place. The effect is the same as if the type were specified as item()*.

9.2 Parameters

<!-- Category: declaration -->
<xsl:param
  name = qname
  select = expression
  as = sequence-type
  required = "yes" | "no">
  <!-- Content: sequence-constructor -->
</xsl:param>

The xsl:param element may be used as a child of xsl:stylesheet, to define a parameter to the transformation; or as a child of xsl:template to define a parameter to a template, which may be supplied when the template is invoked using xsl:call-template, xsl:apply-templates, xsl:apply-imports or xsl:next-match; or as a child of xsl:function to define a parameter to a stylesheet function, which may be supplied when the function is called from an XPath expression.

The xsl:param element has a required name attribute, which specifies the name of the parameter. The value of the name attribute is a QName, which is expanded as described in 5.1 Qualified Names.

The supplied value of the parameter is the value supplied by the caller. If no value was supplied by the caller, and if the parameter is not mandatory, then the supplied value is computed using the expression given in the select attribute and/or the contained sequence constructor, as described in 9.3 Values of Variables and Parameters.

The xsl:param element has an optional as attribute, which specifies the required type of the parameter. The value of the as attribute is a SequenceType, as defined in [XPath 2.0]. [ERR061] If the as attribute is specified, then the supplied value of the parameter is converted to the required type, using argument conversion rules. It is a type error if this conversion fails.

If the as attribute is omitted, the supplied value of the parameter is used directly, and no conversion takes place. The effect is the same as if the type were specified as item()*.

The required attribute may be used to indicate that a parameter is mandatory. This attribute may be specified for stylesheet parameters and for template parameters; it must not be specified for function parameters, which are always mandatory. The default value is no, indicating that the parameter is optional. If the value of the required attribute is yes, the xsl:param element must be empty, and must have no select attribute.

[ERR063] If the value of the required attribute is no, and the caller supplies no value for the parameter, then it is a type error if the default value of the parameter cannot be converted to the required type, using the argument conversion rules. If the default value is supplied implicitly, that is, if the xsl:param element has no select attribute and has empty content, then the default value is a zero-length string; if the zero-length string cannot be converted to the required type, then an error must be signaled only as a dynamic error, if the caller supplies no value for the parameter. In all other cases the type error may be signaled either as a static error or as a dynamic error.

9.3 Values of Variables and Parameters

A variable-binding element may specify the supplied value of the variable or parameter in four different ways.

• If the variable-binding element has a select attribute, then the value of the attribute must be an expression and the supplied value of the variable is the value that results from evaluating the expression. In this case, the content of the variable-binding element must be empty.

• If the variable-binding element has empty content and has neither a select attribute nor an as attribute, then the supplied value of the variable is a zero-length string. Thus

  <xsl:variable name="x"/>

  is equivalent to

  <xsl:variable name="x" select="''"/>

• If a variable-binding element has no select attribute and has non-empty content (i.e. the variable-binding element has one or more child nodes), and has no as attribute, then the content of the variable-binding element specifies the supplied value. The content of the variable-binding element is a sequence constructor; a new document (referred to as a temporary tree) is constructed with a document node having as its children the sequence of nodes that results from evaluating the sequence constructor. Temporary trees are described in more detail in 9.4 Temporary Trees.

• If a variable-binding element has an as attribute but no select attribute, then the supplied value is the sequence that results from evaluating the (possibly empty) sequence constructor contained within the variable-binding element.

These combinations are summarized in the table below.

[ERR064] It is a static error if a variable-binding element has a select attribute and has non-empty content.

<xsl:variable name="i" as="xs:integer*" select="1 to 3"/>

<xsl:variable name="i" as="xs:integer" select="@size"/>

<xsl:variable name="z"/>

<xsl:variable name="doc"><c/></xsl:variable>

<xsl:variable name="seq" as="xs:integer*">
  <xsl:for-each select="1 to 3">
    <xsl:sequence select=".*2"/>
  </xsl:for-each>
</xsl:variable>

<xsl:variable name="attset" as="attribute()+">
  <xsl:attribute name="x">2</xsl:attribute>
  <xsl:attribute name="y">3</xsl:attribute>
  <xsl:attribute name="z">4</xsl:attribute>    
</xsl:variable>

<xsl:variable name="empty" as="empty()"/>

The actual value of the variable depends on the supplied value, as described above, and the required type, which is determined by the value of the as attribute.

9.4 Temporary Trees

A temporary tree is constructed by evaluating an xsl:variable, xsl:param, or xsl:with-param element that has non-empty content and that has no as attribute. This element is referred to as the variable-binding element. The value of the variable is a single node, the document node of the temporary tree. This document node is created implicitly, and its content is formed from the result of evaluating the sequence constructor owned by the variable-binding element, as described in 5.6.1 Constructing Complex Content.

The base URI of a node in the temporary tree is determined as if all the nodes in the temporary tree came from a single entity whose URI was the base URI of the variable-binding element (see [Data Model]). Thus, the base URI of the document node will be equal to the base URI of the variable-binding element; an xml:base attribute within the temporary tree will change the base URI for its parent element and that element's descendants, just as it would within a document constructed by parsing.

A temporary tree is available for processing in exactly the same way as any source document. For example, its nodes are accessible using path expressions, and they can be processed using instructions such as xsl:apply-templates and xsl:for-each. Also, the key and id functions can be used to find nodes within a temporary tree, provided that at the time the function is called, the context item is a node within the temporary tree.

<xsl:stylesheet
  version="2.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

<xsl:import href="phase1.xsl"/>
<xsl:import href="phase2.xsl"/>

<xsl:variable name="intermediate">
  <xsl:apply-templates select="/" mode="phase1"/>
</xsl:variable>

<xsl:template match="/">
  <xsl:apply-templates select="$intermediate" mode="phase2"/>
</xsl:template>

</xsl:stylesheet>

Note:

The algorithm for matching nodes against template rules is exactly the same regardless which tree the nodes come from; if nodes from different trees cannot be distinguished by means of patterns, it is therefore a good idea to use modes to ensure that each tree is processed using the appropriate set of template rules.

9.5 Global Variables and Parameters

Both xsl:variable and xsl:param are allowed as declaration elements: that is, they may appear as children of the xsl:stylesheet element. A top-level variable-binding element declares a global variable that is visible everywhere (except where it is shadowed by another binding). A top-level xsl:param element declares a stylesheet parameter. A stylesheet parameter is a global variable with the additional property that its value can be supplied by the caller when a transformation is initiated. XSLT does not define the mechanism by which parameter values are passed to the stylesheet.

If a stylesheet contains more than one binding for a global variable of a particular name, then the binding with the highest import precedence is used. [ERR065] It is a static error if a stylesheet contains more than one binding of a global variable with the same name and same import precedence.

For a global variable or the default value of a stylesheet parameter, the expression or sequence constructor specifying the variable value is evaluated with a singleton focus based on the document node of the document containing the initial context node. It is therefore an error for the evaluation of a global variable or parameter to reference the context item, context position, or context size when no initial context node is supplied.

<xsl:param name="para-font-size" as="xs:string">12pt</xsl:param>

<xsl:template match="para">
 <fo:block font-size="{$para-font-size}">
   <xsl:apply-templates/>
 </fo:block>
</xsl:template>

9.6 Local Variables and Parameters

As well as being allowed as declaration elements, the xsl:variable element is also allowed in sequence constructors. Such a variable is known as a local variable.

An xsl:param element may appear as a child of an xsl:template element, before any non-xsl:param children of that element. Such a parameter is known as a template parameter. A template parameter is a local variable with the additional property that its value can be set when the template is called, using any of the instructions xsl:call-template, xsl:apply-templates, xsl:apply-imports, or xsl:next-match.

An xsl:param element may appear as a child of an xsl:function element, before any non-xsl:param children of that element. Such a parameter is known as a function parameter. A function parameter is a local variable with the additional property that its value can be set when the function is called, using a function call in an XPath expression.

The result of evaluating a local xsl:variable or xsl:param element (that is, the contribution it makes to the result of the sequence constructor it is part of) is an empty sequence.

9.7 Scope of Variables

For any variable-binding element, there is a region of the stylesheet within which the binding is visible. The set of variable bindings in scope for an XPath expression consists of those bindings that are visible at the point in the stylesheet where the expression occurs.

A global variable binding element is visible everywhere in the stylesheet (including other stylesheet modules) except within the xsl:variable or xsl:param element itself and any region where it is shadowed by another variable binding.

A local variable binding element is visible for all following siblings and their descendants. The binding is not visible for the xsl:variable or xsl:param element itself.

A binding shadows another binding if the binding occurs at a point where the other binding is visible, and the bindings have the same name. It is not an error if a binding established by a local xsl:variable or xsl:param shadows a global binding. In this case, the global binding will not be visible in the region of the stylesheet where it is shadowed by the other binding.

<xsl:param name="x" select="1"/>
<xsl:template name="foo">
  <xsl:variable name="x" select="2"/>
</xsl:template>

It is also not an error if a binding established by a local xsl:variable or xsl:param element shadows another binding established by another local xsl:variable or xsl:param. However, such shadowing is discouraged and implementations may output a warning when it occurs.

<xsl:template name="foo">
  <xsl:variable name="x" select="1"/>
  <xsl:for-each select="1 to 5">
    <xsl:variable name="x" select="$x+1"/>
  <xsl:for-each>
  <x value="{$x}"/>
</xsl:template>

Note:

Once a variable has been given a value, the value cannot subsequently be changed. XSLT does not provide an equivalent to the assignment operator available in many procedural programming languages. This is because an assignment operator would make it harder to create an implementation that processes a document other than in a batch-like way, starting at the beginning and continuing through to the end.

As well as global variables and local variables, an XPath expression may also declare range variables for use locally within an expression. For details, see [XPath 2.0].

Where a reference to a variable occurs in an XPath expression, it is resolved first by reference to range variables that are in scope, then by reference to local variables and parameters, and finally by reference to global variables and parameters. A range variable may shadow a local variable or a global variable. XPath also allows a range variable to shadow another range variable.

9.8 Circular Definitions

If the expression or sequence constructor specifying the value of a global variable X references a global variable Y, then the value for Y must be computed before the value of X. If it is impossible to do this for all global variable definitions, then a circularity is said to exist.

For example the following two declarations create a circularity:

<xsl:variable name="x" select="$y+1"/>

<xsl:variable name="y" select="$x+1"/>

The definition of a global variable can be circular even if no other variable is involved. For example the following two declarations (see 10.3 Stylesheet Functions for an explanation of the xsl:function element) also create a circularity:

<xsl:variable name="x" select="my:f()"/>

<xsl:function name="my:f">
  <xsl:sequence select="$x"/>
</xsl:function>

The definition of a variable is also circular if the evaluation of the variable invokes an xsl:apply-templates instruction and the variable is referenced in the pattern used in the match attribute of any template rule in the stylesheet. For example the following definition is circular:

<xsl:variable name="x">
  <xsl:apply-templates select="//param[1]"/>
</xsl:variable>

<xsl:template match="param[$x]">1</xsl:template>

Similarly, a variable definition is circular if it causes a call on the key function, and the definition of that key refers to that variable in its match or use attributes. So the following definition is circular:

<xsl:variable name="x" select="my:f(10)"/>

<xsl:function name="my:f">
  <xsl:param name="arg1"/>
  <xsl:sequence select="key('k', $arg1)"/>
</xsl:function>

<xsl:key name="k" match="item[@code=$x]" use="@desc"/>

[ERR066] In general, a circularity in a stylesheet is a dynamic error. The processor must signal the error. However, as with all other dynamic errors, an implementation will signal the error only if it actually executes the instructions and expressions that participate in the circularity. Because different implementations may optimize the execution of a stylesheet in different ways, it is implementation-dependent whether a particular circularity will actually be signaled.

For example, in the following declarations, the function declares a local variable $b, but it returns a result that does not require the variable to be evaluated. It is implementation-dependent whether the value is actually evaluated, and it is therefore implementation-dependent whether the circularity is signaled as an error:

<xsl:variable name="x" select="my:f(1)/>

<xsl:function name="my:f">
  <xsl:param name="a"/>
  <xsl:variable name="b" select="$x"/>  
  <xsl:sequence select="$a + 2"/>
</xsl:function>

Circularities usually involve global variables or parameters, but they can also exist between key definitions (see 16.3 Keys), between named attribute sets (see 10.2 Named Attribute Sets), or between any combination of these constructs. For example, a circularity exists if a key definition invokes a function that references an attribute set that calls the key function, supplying the name of the original key definition as an argument.

Circularity is not the same as recursion. Stylesheet functions (see 10.3 Stylesheet Functions) and named templates (see 10.1 Named Templates) may call other functions and named templates without restriction. With careless coding, recursion may be non-terminating. Implementations are required to signal circularity as a dynamic error, but they are not required to detect non-terminating recursion.

10.1 Named Templates

<!-- Category: instruction -->
<xsl:call-template
  name = qname>
  <!-- Content: xsl:with-param* -->
</xsl:call-template>

Templates can be invoked by name. An xsl:template element with a name attribute defines a named template. The value of the name attribute is a QName, which is expanded as described in 5.1 Qualified Names. If an xsl:template element has a name attribute, it may, but need not, also have a match attribute. An xsl:call-template element invokes a template by name; it has a required name attribute that identifies the template to be invoked. Unlike xsl:apply-templates, the xsl:call-template instruction does not change the focus.

The match, mode and priority attributes on an xsl:template element do not affect whether the template is invoked by an xsl:call-template instruction. Similarly, the name attribute on an xsl:template element does not affect whether the template is invoked by an xsl:apply-templates instruction.

[ERR067] It is a static error if a stylesheet contains more than one template with the same name and the same import precedence.

The result of evaluating an xsl:call-template instruction is the sequence produced by evaluating the sequence constructor contained in the associated xsl:template element. The associated xsl:template element is the one whose name attribute matches the name attribute of the xsl:call-template instruction and that has higher import precedence than any other template with this name.

[ERR068] It is a static error if a stylesheet contains an xsl:call-template instruction whose name attribute does not match the name attribute of any xsl:template in the stylesheet.

<xsl:template name="numbered-block">
  <xsl:param name="format">1. </xsl:param>
  <fo:block>
    <xsl:number format="{$format}"/>
    <xsl:apply-templates/>
  </fo:block>
</xsl:template>

<xsl:template match="ol//ol/li">
  <xsl:call-template name="numbered-block">
    <xsl:with-param name="format">a. </xsl:with-param>
  </xsl:call-template>
</xsl:template>

10.2 Named Attribute Sets

<!-- Category: declaration -->
<xsl:attribute-set
  name = qname
  use-attribute-sets = qnames>
  <!-- Content: xsl:attribute* -->
</xsl:attribute-set>

The xsl:attribute-set element defines a named attribute set: that is, a collection of attribute values that can be used repeatedly on different elements in the result tree. The name attribute specifies the name of the attribute set. The value of the name attribute is a QName, which is expanded as described in 5.1 Qualified Names. The content of the xsl:attribute-set element consists of zero or more xsl:attribute elements that specify the attributes in the set.

Attribute sets are used by specifying a use-attribute-sets attribute on the xsl:element, xsl:copy (see 11.8 Copying Nodes from a Source Tree to a Result Tree) or xsl:attribute-set elements. The value of the use-attribute-sets attribute is a whitespace-separated list of names of attribute sets. Each name is specified as a QName, which is expanded as described in 5.1 Qualified Names. Specifying a use-attribute-sets attribute is equivalent to adding xsl:attribute elements for each of the attributes in each of the named attribute sets to the beginning of the content of the element with the use-attribute-sets attribute, in the same order in which the names of the attribute sets are specified in the use-attribute-sets attribute. [ERR073] It is a dynamic error if use of use-attribute-sets attributes on xsl:attribute-set elements causes an attribute set to use itself, directly or indirectly. The processor must signal the error

Attribute sets can also be used by specifying an xsl:use-attribute-sets attribute on a literal result element. The value of the xsl:use-attribute-sets attribute is a whitespace-separated list of names of attribute sets. The xsl:use-attribute-sets attribute has the same effect as the use-attribute-sets attribute on xsl:element with the additional rule that attributes specified on the literal result element itself are treated as if they were specified by xsl:attribute elements before any actual xsl:attribute elements but after any xsl:attribute elements implied by the xsl:use-attribute-sets attribute. Thus, in the node sequence produced by evaluating the sequence constructor for a literal result element, attributes from attribute sets named in an xsl:use-attribute-sets attribute will appear first, in the order listed in the attribute; these will be followed by attributes specified on the literal result element will be added; finally, any attributes specified by xsl:attribute elements will appear. Since in a sequence of attribute nodes produced by a sequence constructor, only the last attribute with a given expanded-QName has any effect (see 5.6 Sequence Constructors), this means that attributes specified in attribute sets can be overridden by attributes specified on the literal result element itself.

The sequence constructor within each xsl:attribute element in an xsl:attribute-set element is evaluated each time the attribute set is used; it is evaluated using the same focus as is used for evaluating the element bearing the use-attribute-sets or xsl:use-attribute-sets attribute. However, it is the position in the stylesheet of the xsl:attribute element rather than of the element bearing the use-attribute-sets or xsl:use-attribute-sets attribute that determines which variable bindings are visible (see 9 Variables and Parameters); thus, only global variables and parameters and local variables declared within an xsl:attribute instruction are visible.

<xsl:template match="chapter/heading">
  <fo:block font-stretch="condensed" xsl:use-attribute-sets="title-style">
    <xsl:apply-templates/>
  </fo:block>
</xsl:template>

<xsl:attribute-set name="title-style">
  <xsl:attribute name="font-size">12pt</xsl:attribute>
  <xsl:attribute name="font-weight">bold</xsl:attribute>
</xsl:attribute-set>

Multiple definitions of an attribute set with the same expanded-QName are merged. An attribute from a definition that has higher import precedence takes precedence over an attribute from a definition that has lower import precedence. [ERR074] It is a dynamic error if there are two attribute sets that have the same expanded-QName and equal import precedence and that both contain the same attribute, unless there is a definition of the attribute set with higher import precedence that also contains the attribute. This is a recoverable error. The processor must either signal the error, or must recover by choosing from amongst the definitions that specify the attribute that have the highest import precedence the one that was specified last in declaration order.

Where the attributes in an attribute set were specified is relevant only in merging the attributes into the attribute set; it makes no difference when the attribute set is used. For each attribute set name occurring in a use-attribute-sets attribute on an xsl:attribute-set element, all definitions of an attribute set with that name must be merged before the use-attribute-sets attribute is replaced by the equivalent sequence of xsl:attribute child elements. Any use-attribute-sets attribute on an xsl:attribute-set element must be replaced by the equivalent sequence of xsl:attribute child elements before that xsl:attribute-set element is merged with other xsl:attribute-set elements with the same expanded-QName. When xsl:attribute-set elements with the same expanded-QName are merged, any xsl:attribute child elements added to replace a use-attribute-sets attribute are treated exactly as if they had originally been specified in the stylesheet as child elements.

10.3 Stylesheet Functions

An xsl:function declaration declares the name, parameters, and implementation of a stylesheet function that can be called from any XPath expression within the stylesheet. [ERR075] A stylesheet function must have a prefixed name, to remove any risk of a clash with a system-defined function. It is a static error if the name has no prefix.

Note:

To prevent the namespace declaration used for the function name appearing in the result document, use the exclude-result-prefixes attribute on the xsl:stylesheet element: see 11.1.3 Namespace Nodes for Literal Result Elements.

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

<xsl:function name="str:reverse" as="xs:string">
  <xsl:param name="sentence" as="xs: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:function name="str:reverse" as="xs:string">
  <xsl:param name="sentence" as="xs:string"/>
  <xsl:choose>
    <xsl:when test="contains($sentence, ' ')">  
      <xsl:sequence select="concat(str:reverse(substring-after($sentence, ' ')),
                                ' ',
                                substring-before($sentence, ' '))"/>
    </xsl:when>
    <xsl:otherwise>
      <xsl:sequence select="$sentence"/>
    </xsl:otherwise>
  </xsl:choose>
</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>

11.1 Literal Result Elements

In a sequence constructor, an element in the stylesheet that does not belong to the XSLT namespace and that is not an extension instruction (see 18.2 Extension Instructions) is classified as a literal result element. A literal result element is evaluated to construct a new element node with the same expanded-QName. The result of evaluating a literal result element is a node sequence containing one element, the newly constructed element node.

The content of the element is a sequence constructor. The sequence obtained by evaluating this sequence constructor is used to construct the content of the element, as described in 5.6.1 Constructing Complex Content

<xsl:stylesheet
  version="2.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:fo="http://www.w3.org/1999/XSL/Format"
  xmlns:axsl="file://namespace.alias">

<xsl:namespace-alias stylesheet-prefix="axsl" result-prefix="xsl"/>

<xsl:template match="/">
  <axsl:stylesheet version="1.0">
    <xsl:apply-templates/>
  </axsl:stylesheet>
</xsl:template>

<xsl:template match="block">
  <axsl:template match="{.}">
     <fo:block><axsl:apply-templates/></fo:block>
  </axsl:template>
</xsl:template>

</xsl:stylesheet>

<elements>
<block>p</block>
<block>h1</block>
<block>h2</block>
<block>h3</block>
<block>h4</block>
</elements>

<xsl:stylesheet
  version="1.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform" 
  xmlns:fo="http://www.w3.org/1999/XSL/Format">
  
<xsl:template match="p">
  <fo:block><xsl:apply-templates/></fo:block>
</xsl:template>

<xsl:template match="h1">
  <fo:block><xsl:apply-templates/></fo:block>
</xsl:template>

<xsl:template match="h2">
  <fo:block><xsl:apply-templates/></fo:block>
</xsl:template>

<xsl:template match="h3">
  <fo:block><xsl:apply-templates/></fo:block>
</xsl:template>

<xsl:template match="h4">
  <fo:block><xsl:apply-templates/></fo:block>
</xsl:template>

</xsl:stylesheet>

11.2 Creating Element Nodes using xsl:element

<!-- Category: instruction -->
<xsl:element
  name = { qname }
  namespace = { uri-reference }
  use-attribute-sets = qnames
  validation = "strict" | "lax" | "preserve" | "strip"
  type = qname>
  <!-- Content: sequence-constructor -->
</xsl:element>

The xsl:element instruction allows an element to be created with a computed name. The expanded-QName of the element to be created is specified by a required name attribute and an optional namespace attribute.

The content of the xsl:element instruction is a sequence constructor for the children, attributes, and namespaces of the created element. The sequence obtained by evaluating this sequence constructor is used to construct the content of the element, as described in 5.6.1 Constructing Complex Content

The result of evaluating the xsl:element instruction, except in error cases, is the newly constructed element node.

The name attribute is interpreted as an attribute value template.

[ERR084] It is a dynamic error if the effective value is not a QName. This is a recoverable error. The processor must either signal the error, or must recover by making the result of evaluating the xsl:element element be the sequence of nodes created by evaluating the content of the xsl:element element, excluding any initial attribute and namespace nodes.

[ERR085] In the case of an xsl:element instruction with no namespace attribute, it is a dynamic error if the effective value of the name attribute is a QName whose prefix is not declared in an in-scope namespace declaration for the xsl:element instruction. This is a recoverable error. The processor must either signal the error, or must recover by ignoring the prefix part of the QName.

If the namespace attribute is not present then the QName is expanded into an expanded-QName using the namespace declarations in effect for the xsl:element element, including any default namespace declaration.

If the namespace attribute is present, then it too is interpreted as an attribute value template. The effective value should be a URI reference. It is not an error if the string is not a syntactically legal URI reference. If the string is zero-length, then the expanded-QName of the element has a null namespace URI. Otherwise, the string is used as the namespace URI of the expanded-QName of the element to be created. The local part of the QName specified by the name attribute is used as the local part of the expanded-QName of the element to be created.

Implementations may make use of the prefix of the QName specified in the name attribute when selecting the prefix used for outputting the created element as XML; however, they are not required to do so.

For the effect of the use-attribute-sets attribute, see 10.2 Named Attribute Sets

11.3 Creating Attribute Nodes using xsl:attribute

<!-- Category: instruction -->
<xsl:attribute
  name = { qname }
  namespace = { uri-reference }
  validation = "strict" | "lax" | "preserve" | "strip"
  type = qname
  disable-output-escaping = "yes" | "no">
  <!-- Content: sequence-constructor -->
</xsl:attribute>

The xsl:attribute element can be used to add attributes to result elements whether created by literal result elements in the stylesheet or by instructions such as xsl:element or xsl:copy. The expanded-QName of the attribute to be created is specified by a required name attribute and an optional namespace attribute. The result of evaluating an xsl:attribute instruction is the newly constructed attribute node.

The content of the xsl:attribute element is a sequence constructor. The sequence obtained by evaluating this sequence constructor is used to construct the content of the attribute, as described in 5.6.2 Constructing Simple Content.

The name attribute is interpreted as an attribute value template.

[ERR086] It is a dynamic error if the effective value is not a QName or is the string xmlns. This is a recoverable error. The processor must either signal the error, or must recover by not adding the attribute to the result tree.

[ERR087] In the case of an xsl:attribute instruction with no namespace attribute, it is a dynamic error if the effective value of the name attribute is a QName whose prefix is not declared in an in-scope namespace declaration for the xsl:attribute instruction. This is a recoverable error. The processor must either signal the error, or must recover by ignoring the prefix part of the QName.

If the namespace attribute is not present, then the QName is expanded into an expanded-QName using the namespace declarations in effect for the xsl:attribute element, not including any default namespace declaration.

If the namespace attribute is present, then it too is interpreted as an attribute value template. The effective value should be a URI reference. It is not an error if the string is not a syntactically legal URI reference. If the string is zero-length, then the expanded-QName of the attribute has a null namespace URI. Otherwise, the string is used as the namespace URI of the expanded-QName of the attribute to be created. The local part of the QName specified by the name attribute is used as the local part of the expanded-QName of the attribute to be created.

Implementations may make use of the prefix of the QName specified in the name attribute when selecting the prefix used for outputting the created attribute as XML; however, they are not required to do so and, if the prefix is xmlns, they must not do so.

<xsl:attribute name="xmlns:xsl" 
   namespace="file://some.namespace">http://www.w3.org/1999/XSL/Transform</xsl:attribute>

As described in 5.6.1 Constructing Complex Content, in a sequence that is used to construct the content of an element, any attribute nodes must appear in the sequence before any element, text, comment, or processing instruction nodes. Where the sequence contains two or more attribute nodes with the same expanded-QName, the one that comes last is the only one that takes effect.

For the effect of the disable-output-escaping attribute, see 20.2 Disabling Output Escaping

11.4 Creating Text Nodes

<x><xsl:value-of select="(1,2,3,4)" separator="|"/></x>

<x>1|2|3|4</x>

<xsl:template match="person">
  <p>
   <xsl:value-of select="@given-name"/>
   <xsl:text> </xsl:text>
   <xsl:value-of select="@family-name"/>
  </p>
</xsl:template>

<xsl:template match="person">
  <p>
   <xsl:value-of select="given-name"/>
   <xsl:text> </xsl:text>
   <xsl:value-of select="family-name"/>
  </p>
</xsl:template>

<xsl:template match="procedure">
  <fo:block>
    <xsl:value-of select="ancestor-or-self::*[@security][1]/@security"/>
  </fo:block>
  <xsl:apply-templates/>
</xsl:template>

11.5 Creating Processing Instructions

<!-- Category: instruction -->
<xsl:processing-instruction
  name = { ncname }>
  <!-- Content: sequence-constructor -->
</xsl:processing-instruction>

The xsl:processing-instruction element is evaluated to create a processing instruction node. The content of the xsl:processing-instruction element is a sequence constructor. The sequence obtained by evaluating this sequence constructor is used to construct the content of the processing instruction, as described in 5.6.2 Constructing Simple Content.

The xsl:processing-instruction element has a required name attribute that specifies the name of the processing instruction node. The value of the name attribute is interpreted as an attribute value template.

Except in error situations, the result of evaluating the xsl:processing-instruction instruction is a single node, the newly constructed processing instruction.

<xsl:processing-instruction name="xml-stylesheet">
  <xsl:text>href="book.css" type="text/css"</xsl:text>
</xsl:processing-instruction>

<?xml-stylesheet href="book.css" type="text/css"?>

[ERR089] It is a dynamic error if the effective value of the name attribute is not both an NCName and a PITarget. This is a recoverable error. The processor must either signal the error, or must recover by returning an empty sequence.

Note:

This means that xsl:processing-instruction cannot be used to output an XML declaration. The xsl:output declaration should be used to control this instead (see 20 Serialization).

[ERR090] It is a dynamic error if the result of evaluating the content of the xsl:processing-instruction contains the string ?>. This is a recoverable error. The processor must either signal the error, or must recover by inserting a space after any occurrence of ? that is followed by a >

11.6 Creating Namespace Nodes

<!-- Category: instruction -->
<xsl:namespace
  name = { ncname }>
  <!-- Content: sequence-constructor -->
</xsl:namespace>

The xsl:namespace element is evaluated to create a namespace node. The content of the xsl:namespace element is a sequence constructor. The sequence obtained by evaluating this sequence constructor is used to construct the string value of the namespace node (that is, the namespace URI), as described in 5.6.2 Constructing Simple Content.

The xsl:namespace element has a required name attribute that specifies the name of the namespace node (that is, the namespace prefix). The value of the name attribute is interpreted as an attribute value template. If the value of the name attribute is a zero-length string, a namespace node is added for the default namespace.

Except in error situations, the result of evaluating the xsl:namespace instruction is a single node, the newly constructed namespace node. Note the restrictions described in 5.6.1 Constructing Complex Content for the position of a namespace node relative to other nodes in the node sequence returned by a sequence constructor.

<xsl:namespace name="xs">http://www.w3.org/2001/XMLSchema</xsl:namespace>

xmlns:xs="http://www.w3.org/2001/XMLSchema"

[ERR091] It is a dynamic error if the effective value of the name attribute is neither a zero-length string nor an NCName. This is a recoverable error. The processor must either signal the error, or must recover by returning an empty sequence.

[ERR092] It is a dynamic error if evaluating the content of xsl:namespace results in a zero-length string. This is a recoverable error. The processor must either signal the error, or must recover by returning an empty sequence.

For details of other error conditions that may arise, see 5.6 Sequence Constructors.

Note:

It is rarely necessary to use xsl:namespace to create a namespace node in the result tree; in most circumstances, the required namespace nodes will be created automatically, as a side-effect of writing elements or attributes that use the namespace. An example where xsl:namespace is needed is a situation where the required namespace is used only within attribute values in the result document, not in element or attribute names; especially where the required namespace prefix or namespace URI is computed at run-time and is not present in either the source document or the stylesheet. Adding a namespace node to the result tree will never change the expanded-QName of any element or attribute node in the result tree: that is, it will never change the namespace URI of an element or attribute. It may, however, constrain the choice of prefixes when namespace fixup is performed. Namespace prefixes for element and attribute names are effectively established by the namespace fixup process described in 5.6.3 Namespace Fixup. The fixup process ensures that an element has in-scope namespace nodes for the namespace URIs used in the element name and in its attribute names, and the serializer will typically use these namespace nodes to determine the prefix to use in the serialized output. The fixup process cannot generate namespace nodes that are inconsistent with those already present in the tree. This means that it is not possible for the processor to decide the prefix to use for an element or for any of its attributes until all the namespace nodes for the element have been added. If a namespace prefix is mapped to a particular namespace URI using the xsl:namespace instruction, or by using xsl:copy or xsl:copy-of to copy a namespace node, this prevents the namespace fixup process (and hence the serializer) from using the same prefix for a different namespace URI on the same element.

Note:

The xsl:namespace instruction cannot be used to generate a namespace undeclaration of the form xmlns="" (nor the new forms of namespace undeclaration permitted by XML Namespaces 1.1: see [XML Namespaces 1.1]). Namespace undeclarations are generated automatically by the serializer when a parent element has a namespace node for the default namespace prefix, and a child element has no namespace node for that prefix.

<xsl:namespace name="xs">http://www.w3.org/2001/XMLSchema</xsl:namespace>
<xsl:attribute name="xsi:type" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">  
  <xsl:text>xs:decimal</xsl:text>
</xsl:attribute>

11.7 Creating Comments

<!-- Category: instruction -->
<xsl:comment>
  <!-- Content: sequence-constructor -->
</xsl:comment>

The xsl:comment element is evaluated to contruct a new comment node. The content of the xsl:comment element is a sequence constructor. The sequence obtained by evaluating this sequence constructor is used to construct the content of the comment, as described in 5.6.2 Constructing Simple Content.

The result of evaluating the xsl:comment instruction is a single node, the newly constructed comment node.

<xsl:comment>This file is automatically generated. Do not edit!</xsl:comment>

<!--This file is automatically generated. Do not edit!-->

[ERR093] It is a dynamic error if the result of evaluating the content of the xsl:comment contains the string -- or ends with -. This is a recoverable error. The processor must either signal the error, or must recover by inserting a space after any occurrence of - that is followed by another - or that ends the comment.

11.8 Copying Nodes from a Source Tree to a Result Tree

<xsl:template match="@*|node()">
  <xsl:copy>
    <xsl:apply-templates select="@*|node()"/>
  </xsl:copy>
</xsl:template>

11.9 Constructing Sequences

<!-- Category: instruction -->
<xsl:sequence
  select = expression
  as = sequence-type>
  <!-- Content: sequence-constructor -->
</xsl:sequence>

The xsl:sequence instruction may be used within a sequence constructor to construct a sequence of nodes and/or atomic values. This sequence is returned as the result of the instruction. This is the only instruction that can add existing nodes to a sequence, rather than constructing new nodes. When xsl:sequence is used to add atomic values to a sequence, the effect is very similar to the xsl:copy-of instruction.

The items comprising the result sequence may be selected using the select attribute, or constructed using the contained sequence constructor. Any items selected by the select attribute are added to the result sequence before any items constructed using the sequence constructor. If the select attribute is omitted and the sequence constructor is empty, the instruction returns an empty sequence.

The as attribute, if present, defines the required type of the result sequence. The computed value of the result sequence will be converted to this type using the argument conversion rules. [ERR095] If the computed value cannot be converted to the required type, a type error occurs. The processor must signal the error. As with other type errors, the error may be signaled statically if it can be detected statically.

Note:

The as attribute may be used to restrict the sequence to contain only atomic values, or only nodes, or it may allow a sequence containing both atomic values and nodes.

If no as attribute is specified, the default value is item()*, which permits any value. No conversion then takes place.

<xsl:variable name="values" as="xs:integer*">
    <xsl:sequence select="(1,2,3,4)"/>
    <xsl:sequence select="(8,9,10)"/>
</xsl:variable>
<xsl:value-of select="sum($values)"/>

<xsl:variable name="prices" as="xs:decimal*">
  <xsl:for-each select="//product">
    <xsl:choose>
      <xsl:when test="@price">
        <xsl:sequence select="@price"/>
      </xsl:when>
      <xsl:otherwise>
        <xsl:sequence select="@cost * 1.5"/>
      </xsl:otherwise>
    </xsl:choose>
  </xsl:for-each>
</xsl:variable>
<xsl:value-of select="avg($prices)"/>

<xsl:value-of select="avg(for $p in //product return
             if ($p/@price) then $p/@price else ($p/@cost * 1.5))"/>

12.1 Formatting a Supplied Number

The place marker to be formatted may be specified by an expression. The value attribute contains the expression. The value of this expression is atomized using the procedure defined in [XPath 2.0], and each value in the atomized sequence is then converted to an integer by first applying the XPath number and round functions, and then casting the result to an integer. The resulting sequence of integers is used as the place marker to be formatted.

If backwards compatible behavior is enabled for the instruction, then all items in the atomized sequence after the first are discarded.

[ERR096] It is a dynamic error if any undiscarded item in the sequence cannot be converted to an integer, or if the resulting integer is less than 1 (one). This is a recoverable error. The processor must either signal the error, or must recover by converting that item to a string as if by a call to the string function and inserting the resulting string into the formatted result string in its proper position.

The resulting sequence is formatted as a string using the effective values of the attributes specified in 12.3 Number to String Conversion Attributes; each of these attributes is interpreted as an attribute value template. After conversion, the xsl:number element constructs a new text node containing the resulting string, and returns this node.

<xsl:template match="items">
  <xsl:for-each select="item">
    <xsl:sort select="."/>
    <p>
      <xsl:number value="position()" format="1. "/>
      <xsl:value-of select="."/>
    </p>
  </xsl:for-each>
</xsl:template>

12.2 Numbering based on Position in a Document

If no value attribute is specified, then the xsl:number instruction returns a new text node containing a formatted place marker that is based on the position of the context node within its containing document.

[ERR097] It is a dynamic error if the xsl:number instruction is evaluated, with no value attribute, when the context item is not a node. This is a recoverable error. The processor must either signal the error, or must recover by returning an empty sequence.

The following attributes control how the context node is to be numbered:

• The level attribute specifies rules for selecting the nodes that are taken into account in allocating a number; it has the values single, multiple or any. The default is single.

• The count attribute is a pattern that specifies which nodes are to be counted at those levels. If count attribute is not specified, then it defaults to the pattern that matches any node with the same node kind as the context node and, if the context node has an expanded-QName, with the same expanded-QName as the context node.

• The from attribute is a pattern that specifies where counting starts.

In addition, the attributes specified in 12.3 Number to String Conversion Attributes are used for number to string conversion, as in the case when the value attribute is specified.

The xsl:number element first constructs a sequence of positive integers using the level, count and from attributes. Where level is single or any, this sequence will either be empty or contain a single number; where level is multiple, the sequence may be of any length. The sequence is constructed as follows:

Let matches-count($node) be a function that returns true if the given node $node matches the pattern given in the count attribute, or the implied pattern (according to the rules given above) if the count attribute is omitted.

Let matches-from($node) be a function that returns true if the given node $node matches the pattern given in the from attribute, or if $node is the root node of a tree. If the from attribute is omitted, then the function returns true if and only if $node is the root node of a tree.

When level="single":

• Let $A be the node sequence selected by the following expression (this selects the innermost ancestor-or-self node that matches the count pattern):

     ancestor-or-self::node()[matches-count(.)][1]

• Let $F be the node sequence selected by the expression

     ancestor-or-self::node()[matches-from(.)][1]

• Let $AF be the value of

     $A intersect ($F/descendant-or-self::node())

• If $AF is empty, return the empty sequence, ()

• Otherwise return the value of

     1 + count($AF/preceding-sibling::node()[matches-count(.)])

When level="multiple":

• Let $A be the node sequence selected by the expression

     ancestor-or-self::node()[matches-count(.)]

• Let $F be the node sequence selected by the expression

     ancestor-or-self::node()[matches-from(.)][1]

• Let $AF be the value of

     $A intersect ($F/descendant-or-self::node())

• Return the result of the expression

     for $af in $AF return 1+count($af/preceding-sibling::node()[matches-count(.)])

When level="any":

• If the context node is a document node, return the empty sequence, ()

• Let $A be the node sequence selected by the expression

     (preceding::node()|ancestor-or-self::node())[matches-count(.)]

• Let $F be the node sequence selected by the expression

     (preceding::node()|ancestor-or-self::node())[matches-from(.)][last()]

• Let $AF be the node sequence $A[. is $F or . >> $F].

• If $AF is empty, return the empty sequence, ()

• Otherwise return the value of the expression count($AF)

The sequence of numbers (the place marker) is then converted into a string using the effective values of the attributes specified in 12.3 Number to String Conversion Attributes; each of these attributes is interpreted as an attribute value template. After conversion, the resulting string is inserted in the result tree.

<xsl:template match="ol/item">
  <fo:block>
    <xsl:number/><xsl:text>. </xsl:text><xsl:apply-templates/>
  </fo:block>
<xsl:template>

<xsl:template match="title">
  <fo:block>
     <xsl:number level="multiple"
                 count="chapter|section|subsection"
                 format="1.1 "/>
     <xsl:apply-templates/>
  </fo:block>
</xsl:template>

<xsl:template match="appendix//title" priority="1">
  <fo:block>
     <xsl:number level="multiple"
                 count="appendix|section|subsection"
                 format="A.1 "/>
     <xsl:apply-templates/>
  </fo:block>
</xsl:template>

<xsl:template match="note">
  <fo:block>
     <xsl:number level="any" from="chapter" format="(1) "/>
     <xsl:apply-templates/>
  </fo:block>
</xsl:template>

<xsl:template match="H4">
 <fo:block>
   <xsl:number level="any" from="H1" count="H2"/>
   <xsl:text>.</xsl:text>
   <xsl:number level="any" from="H2" count="H3"/>
   <xsl:text>.</xsl:text>
   <xsl:number level="any" from="H3" count="H4"/>
   <xsl:text> </xsl:text>
   <xsl:apply-templates/>
 </fo:block>
</xsl:template>

12.3 Number to String Conversion Attributes

The following attributes are used to control conversion of a sequence of numbers into a string. The numbers are integers greater than 0. The attributes are all optional.

The main attribute is format. The default value for the format attribute is 1. The format attribute is split into a sequence of tokens where each token is a maximal sequence of alphanumeric characters or a maximal sequence of non-alphanumeric characters. Alphanumeric means any character that has a Unicode category of Nd, Nl, No, Lu, Ll, Lt, Lm or Lo. The alphanumeric tokens (format tokens) specify the format to be used for each number in the sequence. If the first token is a non-alphanumeric token, then the constructed string will start with that token; if the last token is non-alphanumeric token, then the constructed string will end with that token. Non-alphanumeric tokens that occur between two format tokens are separator tokens that are used to join numbers in the sequence. The nth format token will be used to format the nth number in the sequence. If there are more numbers than format tokens, then the last format token will be used to format remaining numbers. If there are no format tokens, then a format token of 1 is used to format all numbers. The format token specifies the string to be used to represent the number 1. Each number after the first will be separated from the preceding number by the separator token preceding the format token used to format that number, or, if there are no separator tokens, then by . (a period character).

Format tokens are a superset of the allowed values for the type attribute for the OL element in HTML 4.0 and are interpreted as follows:

• Any token where the last character has a decimal digit value of 1 (as specified in the Unicode character property database), and the Unicode value of preceding characters is one less than the Unicode value of the last character generates a decimal representation of the number where each number is at least as long as the format token. Thus, a format token 1 generates the sequence 1 2 ... 10 11 12 ..., and a format token 01 generates the sequence 01 02 ... 09 10 11 12 ... 99 100 101.

• A format token A generates the sequence A B C ... Z AA AB AC....

• A format token a generates the sequence a b c ... z aa ab ac....

• A format token i generates the sequence i ii iii iv v vi vii viii ix x ....

• A format token I generates the sequence I II III IV V VI VII VIII IX X ....

• Any other format token indicates a numbering sequence that starts with that token. It is implementation-defined which numbering sequences, additional to those listed above, are supported. If an implementation does not support a numbering sequence that starts with the given token, it must use a format token of 1.

For all format tokens other than the first kind above (one that consists of decimal digits), there may be an implementation-defined upper bound on the range of numbers that can be formatted using this format token; indeed, for some numbering sequences there may be an intrinsic limit. For the numbering sequences described above, the upper bound must not be less than 1000 (one thousand). Numbers that exceed the upper bound must be formatted using the format token 1.

When numbering with an alphabetic sequence, the lang attribute specifies which language's alphabet is to be used; it has the same range of values as xml:lang [XML 1.0]; if no lang value is specified, the language should be determined from the system environment. The set of languages for which numbering is supported is implementation-defined.

The letter-value attribute disambiguates between numbering sequences that use letters. In many languages there are two commonly used numbering sequences that use letters. One numbering sequence assigns numeric values to letters in alphabetic sequence, and the other assigns numeric values to each letter in some other manner traditional in that language. In English, these would correspond to the numbering sequences specified by the format tokens a and i. In some languages, the first member of each sequence is the same, and so the format token alone would be ambiguous. A value of alphabetic specifies the alphabetic sequence; a value of traditional specifies the other sequence. If the letter-value attribute is not specified, then it is implementation-dependent how any ambiguity is resolved.

Note:

It is possible for two conforming implementations not to convert a number to exactly the same string. Some implementations might not support some languages. Furthermore, variations are possible in the way conversions are performed for any particular language. Implementations may use implementation-defined namespaced attributes on xsl:number to provide additional control.

The grouping-separator attribute gives the separator used as a grouping (e.g. thousands) separator in decimal numbering sequences, and the optional grouping-size specifies the size (normally 3) of the grouping. For example, grouping-separator="," and grouping-size="3" would produce numbers of the form 1,000,000. If only one of the grouping-separator and grouping-size attributes is specified, then it is ignored.

Here are some examples of conversion specifications:

• format="ア" specifies Katakana numbering

• format="イ" specifies Katakana numbering in the "iroha" order

• format="๑" specifies numbering with Thai digits

• format="א" letter-value="traditional" specifies "traditional" Hebrew numbering

• format="ა" letter-value="traditional" specifies Georgian numbering

• format="α" letter-value="traditional" specifies "classical" Greek numbering

• format="а" letter-value="traditional" specifies Old Slavic numbering

The following examples show some non-Western numbering sequences.

13.1 Collating Sequences

Facilities in XSLT 2.0 and XPath 2.0 that require strings to be ordered rely on the concept of a named collation. A collation is a set of rules that determine whether two strings are equal, and if not, which of them is to be sorted before the other. A collation is identified by a URI, but the manner in which this URI is associated with an actual rule or algorithm is implementation-defined.

Note:

The reason XSLT does not provide detailed mechanisms for defining collating sequences is that many implementations will re-use collating mechanisms available from the underlying implementation platform (for example, from the operating system or from the run-time library of a chosen programming language). These will inevitably differ from one XSLT implementation to another.

Note:

Useful background information on international sorting is provided in [UNICODE TR10].

13.2 The xsl:sort Element

<xsl:sort
  select = expression
  lang = { nmtoken }
  order = { "ascending" | "descending" }
  collation = { uri }
  case-order = { "upper-first" | "lower-first" }
  data-type = { "text" | "number" | qname-but-not-ncname } />

Those attributes of the xsl:sort elements whose values are attribute value templates are evaluated using the outer focus, which is defined as follows:

• If the element that contains the xsl:sort elements is an xsl:sort-key declaration, then the outer focus is a singleton focus based on the document node of the document containing the initial context node; a dynamic error occurs if an expression if such an attribute value template references the context node, context position, or context size when no initial context node is supplied.

• Otherwise, the outer focus is the focus used to evaluate the select attribute of the containing instruction (for example, xsl:for-each or xsl:apply-templates).

The sequence to be sorted is referred to as the initial sequence. The sequence after sorting as defined by the xsl:sort elements is referred to as the sorted sequence.

For each item in the initial sequence, a value is computed for each sort key definition within the sort specification. The value computed for an item by using the Nth sort key definition is referred to as the Nth sort key of that item. Specifically, the Nth sort key is computed by evaluating the expression contained in the select attribute of the Nth xsl:sort element, if there is such an attribute. If there is no select attribute, the sort key is computed by taking the actual item in the initial sequence if it is an atomic value, or the typed-value of this item if it is a node.

The expression in the select attribute of the xsl:sort element is evaluated with the focus set as follows:

• The context item is the item in the initial sequence whose sort key is being computed.

• The context position is the position of that item in the initial sequence.

• The context size is the size of the initial sequence.

The values of the sort keys are atomized, and are then compared. The way they are compared depends on their data type.

It is possible to force the system to compare sort keys using the rules for a particular data type by including a cast as part of the sort key. For example, <xsl:sort select="xs:date(@dob)"/> will force the attributes to be compared as dates. In the absence of such a cast, the sort keys are compared using the rules appropriate to their data type. For this purpose the empty sequence is considered to be comparable to all other values: it is considered equal to itself, and less than any other value.

For backwards compatibility with XSLT 1.0, the data-type attribute remains available. If this has the effective value text, the sort keys are converted to strings before being compared. If it has the effective value number, the sort keys are converted to doubles before being compared. The conversion is done by using the string or number function as appropriate. If the data-type attribute has any other effective value, then the value must be a prefixed QName, and the effect of the attribute is implementation-defined.

[ERR100] If the value of any sort key, after atomization and any type conversion required by the data-type attribute, is a sequence containing more than one item, then the effect depends on whether the xsl:sort element is evaluated with backwards compatible behavior. With backwards compatible behavior, the effective value of the sort key is the first item in the sequence. In other cases, this is a type error. The processor must signal the error.

The values of the sort keys (after any conversion) are first divided into three categories: empty values, NaN values, and ordinary values. The empty values represent those items where the sort key evaluates to an empty sequence. These values are considered for sorting purposes to be equal to each other, but less than any other value. NaN values are considered for sorting purposes to be equal to each other, greater than any empty value, but less than any ordinary value. The remaining values are classified as ordinary values.

In general, comparison of two ordinary values is performed according to the rules of the XPath lt operator. However, special rules apply to the xs:string type and types derived by restriction from xs:string, as described below.

[ERR102] It is a dynamic error if, for any sort key definition, the set of sort keys evaluated for all the items in the initial sequence, after any type conversion requested, contains a pair of ordinary values for which the result of the XPath lt operator is an error. This is a recoverable error. The processor must either signal the error, or must recover by assigning an arbitrary ordering to any such pair of values.

The items in the initial sequence are ordered into a sorted sequence by comparing their sort keys. The relative position of two items A and B in the sorted sequence is determined as follows. The first sort key of A is compared with the first sort key of B, according to the rules of the first sort key definition. If, under these rules, A is less than B, then A will precede B in the sorted sequence, unless the order attribute of this sort key definition specifies descending, in which case B will precede A in the sorted sequence. If, however, the relevant sort keys compare equal, then the second sort key of A is compared with the second sort key of B, according to the rules of the second sort key definition. This continues until two sort keys are found that compare unequal. If all the sort keys compare equal, then A will precede B in the sorted sequence if A preceded B in the initial sequence, and vice versa.

For comparison of string values, special rules apply. If the xsl:sort element has a collation attribute, then the strings are compared according to the rules for the named collation: that is, they are compared using the XPath function call compare($a, $b, $collation).

Note:

XSLT provides no facilities to declare or define collations: such mechanisms are expected to be provided by implementors. Equally, this specification does not define what happens if the collation name is not recognized: the implementation may signal an error, or it may use the default collation.

The lang and case-order attributes are ignored if a collation attribute is present. But in the absence of a collation attribute, these attributes provide input to an implementation-defined algorithm to identify a suitable collation:

• The lang attribute indicates that a collation suitable for a particular natural language is required. The effective value of the attribute must be a value that would be valid for the xml:lang attribute (see [XML 1.0]).

• The case-order attribute indicates whether the desired collation should sort upper-case letters before lower-case or vice versa. The effective value of the attribute must be either lower-first (indicating that lower-case letters precede upper-case letters in the collating sequence) or upper-first (indicating that upper-case letters precede lower-case).

In the absence of any of these attributes, the default collation is used.

13.3 Using Unnamed Sort Specifications

When used within xsl:for-each or xsl:apply-templates, a sort specification indicates that the sequence of items selected by that instruction is to be processed in sorted order, not in the order of the supplied sequence.

<employees>
  <employee>
    <name>
      <given>James</given>
      <family>Clark</family>
    </name>
    ...
  </employee>
</employees>

<xsl:template match="employees">
  <ul>
    <xsl:apply-templates select="employee">
      <xsl:sort select="name/family"/>
      <xsl:sort select="name/given"/>
    </xsl:apply-templates>
  </ul>
</xsl:template>

<xsl:template match="employee">
  <li>
    <xsl:value-of select="name/given"/>
    <xsl:text> </xsl:text>
    <xsl:value-of select="name/family"/>
  </li>
</xsl:template>

When used within xsl:for-each-group, a sort specification indicates the order in which the groups are to be processed. For the effect of xsl:for-each-group, see 14 Grouping

13.4 Using Named Sort Specifications

<xsl:sort-key name="book-price">
   <xsl:sort select="xs:decimal(price)"/>
</xsl:sort-key>
   ...
   <xsl:copy-of select="sort(//book, 'book-price')[1]"/>

 

14.1 The Current Group

The evaluation context for XPath expressions includes an additional value called the current group, which is a sequence. The current group is the collection of related items that are processed collectively in one iteration of the xsl:for-each-group element.

While an xsl:for-each-group instruction is being evaluated, the current group will be non-empty. At other times, it will be an empty sequence.

The function current-group returns the current group.

The function takes no arguments.

[ERR106] It is a static error if the current-group function is used within a pattern.

14.2 The Current Grouping Key

The evaluation context for XPath expressions includes an additional value called the current grouping key, which is an atomic value. The current grouping key is a value shared in common by all the items within the current group.

While an xsl:for-each-group instruction with a group-by or group-adjacent attribute is being evaluated, the current grouping key will be non-empty. At other times, it will be an empty sequence.

The function current-grouping-key returns the current grouping key.

The function takes no arguments.

[ERR107] It is a static error if the current-grouping-key function is used within a pattern.

14.3 The xsl:for-each-group Element

<!-- Category: instruction -->
<xsl:for-each-group
  select = expression
  group-by = expression
  group-adjacent = expression
  group-starting-with = pattern
  group-ending-with = pattern
  collation = { uri }>
  <!-- Content: (xsl:sort*, sequence-constructor) -->
</xsl:for-each-group>

This element is an instruction that may be used anywhere within a sequence constructor.

The xsl:for-each-group instruction allocates the items in an input sequence into groups of items (that is, it establishes a collection of sequences) based either on common values of a grouping key, or on a pattern that the initial node in a group must match. The sequence constructor that forms the content of the xsl:for-each-group instruction is evaluated once for each of these groups. A group is never empty.

The sequence of items to be grouped, which is referred to as the population, is determined by evaluating the XPath expression contained in the select attribute. The population is treated as a sequence; the order of items in this sequence is referred to as population order. If the population is empty, the number of groups will be zero. The assignment of items to groups depends on the group-by, group-adjacent, group-starting-with, and group-ending-with attributes. [ERR108] These four attributes are mutually exclusive: it is a static error if none of these four attributes is present, or if more than one of them is present.

[ERR110] It is an error to specify the collation attribute if neither the group-by attribute nor group-adjacent attribute is specified.

If either of the group-by attribute or group-adjacent attributes is present, then grouping keys are calculated for each item in the population. The expression contained in the group-by or group-adjacent attribute is evaluated with that item as the context item, with its position in population order as the context position, and with the size of the population as the context size. The resulting sequence is atomized, and each atomic value in the atomized sequence acts as a grouping key for that item in the population.

If the group-by attribute is present, then an item in the population may have multiple grouping keys: that is, the group-by expression evaluates to a sequence. The item is included in as many groups as there are distinct grouping keys (which may be zero). If the group-adjacent attribute is used, then each item in the population must have exactly one grouping key value.

[ERR111] It is a type error if the result of the group-adjacent attribute is an empty sequence, or a sequence containing more than one item. The processor must signal the error.

[ERR112] It is a type error if the set of grouping keys obtained by evaluating the group-by or group-adjacent attributes for all items in the population contains two items that are not comparable using the eq operator. The processor must signal the error.

Grouping keys are compared using the rules for the eq operator appropriate to their dynamic type. If the values are strings, or untyped atomic values, they are compared using the collation specified in the collation attribute if present, or the default collation otherwise. For the purposes of grouping, the value NaN is considered equal to itself.

• If the group-by attribute is present, then all items that have the same grouping key are assigned to the same group, and the number of groups is the same as the number of distinct grouping key values present in the population. An item in the population may thus be assigned to zero, one, or many groups. An item will never by assigned more than once to the same group; if two or more grouping keys for the same item are equal, then the duplicates are ignored.

• If the group-adjacent attribute is present, the items in the population are examined, in population order. If an item has the same value for the grouping key as its preceding item within the population (in population order), then it is assigned to the same group as its preceding item; otherwise a new group is created and the item becomes its first member.

• If the group-starting-with attribute is present, then its value must be a pattern. In this case, the items in the population must all be nodes. [ERR114] It is a dynamic error if the result of evaluating the select expression contains an item that is not a node. The processor must signal the error.

  The nodes in the population are examined in population order. If a node matches the pattern, or is the first node in the population, then a new group is created and the node becomes its first member. Otherwise, the node is assigned to the same group as its preceding node within the population.

• If the group-ending-with attribute is present, then its value must be a pattern. In this case, the items in the population must all be nodes. [ERR115] It is a dynamic error if the result of evaluating the select expression contains an item that is not a node. The processor must signal the error.

  The nodes in the population are examined in population order. If a node is the first node in the population, or if the previous node in the population matches the pattern, then a new group is created and the node becomes its first member. Otherwise, the node is assigned to the same group as its preceding node within the population.

For each group, the item within the group that is first in population order is known as the initial item of the group.

There is an ordering among groups referred to as the order of first appearance. A group G is defined to precede a group H in order of first appearance if the initial item of G precedes the initial item of H in population order. If two groups G and H have the same initial item (because the item is in both groups) then G precedes H if the grouping key of G precedes the grouping key of H in the sequence that results from evaluating the group-by expression of this initial item.

There is another ordering among groups referred to as processing order.

If there are no xsl:sort elements immediately within the xsl:for-each-group element, the processing order of the groups is the order of first appearance.

Otherwise, the xsl:sort elements immediately within the xsl:for-each-group element define the processing order of the groups (see 13 Sorting). They do not affect the order of items within each group. Multiple sort keys are allowed, and are evaluated in major-to-minor order. If two groups have the same values for all their sort keys, they are processed in order of first appearance.

The select expression of an xsl:sort element is evaluated once for each group. During this evaluation, the context item is the initial item of the group, the context position is the position of this item within the set of initial items (that is, one item for each group in the population) in population order, the context size is the number of groups, the current group is the group whose sort key is being determined, and the current grouping key is the grouping key for that group. If the xsl:for-each-group instruction uses the group-starting-with or group-ending-with attributes, then the current grouping key is the empty sequence.

If there are attribute value templates present in the xsl:sort element, the focus for evaluation of the contained expressions is the same as the focus for evaluation of the select attribute of the containing xsl:for-each-group instruction.

The sequence constructor contained in the xsl:for-each-group element is evaluated once for each of the groups, in processing order. The sequences that result are concatenated, in processing order, to form the result of the xsl:for-each-group element. Within the sequence constructor, the context item is the initial item of the relevant group, the context position is the position of this item among the set of initial items (one item for each group) arranged in processing order of the groups, the context size is the number of groups, the current group is the group being processed, and the current grouping key is the grouping key for that group. If the xsl:for-each-group instruction uses the group-starting-with or group-ending-with attributes, then the current grouping key is the empty sequence. This has the effect that within the the sequence constructor, a call on position() takes successive values 1, 2, ... last().