This document is also available in these non-normative formats: HTML without revision markings and HTML with revision markings.
Copyright © 2003 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark, document use and software licensing rules apply.
This specification defines the syntax and semantics of XSLT 2.0, which is a language for transforming XML documents into other XML documents.
XSLT 2.0 is designed to be used in conjunction with XPath 2.0, which is defined in [XPath 2.0]. XSLT shares the same data model as XPath 2.0, which is defined in [Data Model], and it uses the library of functions and operators defined in [Functions and Operators].
XSLT 2.0 also includes optional facilities to serialize the results of a transformation, by means of an interface to the serialization component described in [XSLT and XQuery Serialization].
This document contains hyperlinks to specific sections or definitions within other documents in this family of specifications. These links are indicated visually by a superscript identifying the target specification: for example XP for XPath, DM for the Data Model, FO for Functions and Operators.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
This specification is a Last Call Working Draft of XSLT 2.0. This is a signal that:
the XSL Working Group believes that it has satisfied its relevant technical requirements;
the Working Group believes that it has satisfied significant dependencies with other groups;
other groups are invited to review the document to confirm that these dependencies have been satisfied;
the Working Group is planning to advance the specification to become a Candidate Recommendation.
The final date for comments on this draft is 15 February 2004.
Comments should be sent to public-qt-comments@w3.org. Because
the same mailing list is also used for comments on XPath 2.0 and XQuery
1.0, it is helpful to include the string [XSLT2.0]
in the
subject line, together with an originator's reference number that can be
used to track progress in dealing with the comment. If possible, please
send each comment as a separate email. Archives of
the comments and responses are available.
The document is published in two versions: one that highlights changes since the previous published Working Draft, and one without change highlighting.
As predicted in the previous (May 2003) draft, there are relatively
few technical innovations in this draft, but a substantial amount of
editorial revision and clarification. The technical changes of note are
the ability of many XSLT instructions (for example, xsl:attribute
and xsl:value-of
) to use a
select
attribute or a contained sequence
constructor interchangeably, and the introduction of tunnel parameters
which allow parameter values to be passed from a high-level template rule
to a low-level rule without being declared in all the intermediate
templates. Named sort keys and the sort
function have been
replaced with a new xsl:perform-sort
instruction.
There have been revisions to the date formatting functions, aligning them
with the xsl:number
instruction and transferring some of the functionality into xsl:number
to make it more widely
applicable.
A detailed summary of the changes is included at K.2.4 Changes since the May 2003 draft
The Working Group has commenced, but has not yet completed, a review of the classification of all error conditions described in this draft. It is likely that this review will cause the classification of some errors to change, for example some errors currently classified as recoverable may change to being non-recoverable, or vice versa. Comments on the classification, or on the general approach to handling of dynamic errors, are welcomed.
The statements in this draft concerning dependencies on other specifications that are not yet Recommendations (notably XML 1.1 and XML Namespaces 1.1) must be regarded as provisional, pending final acceptance of those specifications.
Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
XSLT 2.0 is a revised version of the XSLT 1.0 Recommendation [XSLT 1.0] published on 16 November 1999. The changes made in this document are intended to meet the requirements for XSLT 2.0 described in [XSLT 2.0 Requirements] and to incorporate fixes for errors that have been detected in XSLT 1.0. A summary of the changes since XSLT 1.0 is included in K Changes from XSLT 1.0.
XSLT 2.0 is designed to be used together with XPath 2.0, which has been developed by the W3C XSL Working Group in collaboration with the XML Query Working Group. The current specification of XPath 2.0 can be found in [XPath 2.0].
Public discussion of XSL, including XSL Transformations, takes place on the XSL-List mailing list.
The English version of this specification is the only normative version. However, for translations of this document, see http://www.w3.org/Style/XSL/translations.html.
The development of XSLT is undertaken by the XSL Working Group which is now part of the W3C XML Activity.
Patent disclosures relevant to this specification may be found on the XSL Working Group's patent disclosure page at http://www.w3.org/Style/XSL/Disclosures.html.
1 Introduction
1.1 What is
XSLT?
1.2 What's new in
XSLT 2.0?
2 Concepts
2.1 Terminology
2.2 Notation
2.3 Initiating a
Transformation
2.4 Executing a Transformation
2.5 The Stylesheet Evaluation
Context
2.5.1 Maintaining Position: the Focus
2.5.2 Additional Context Variables
2.6 Parsing
and Serialization
2.7 Extensibility
2.8 Stylesheets and Schemas
2.9 Error Handling
3 Stylesheet Structure
3.1 XSLT
Namespace
3.2 Reserved
Namespaces
3.3 Extension
Attributes
3.4 XSLT Media
Type
3.5 Standard
Attributes
3.6 Stylesheet
Element
3.6.1 User-defined Data Elements
3.7 Simplified
Stylesheet Modules
3.8 Backwards-Compatible
Processing
3.9 Forwards-Compatible
Processing
3.10 Combining
Stylesheet Modules
3.10.1 Locating Stylesheet Modules
3.10.2 Stylesheet Inclusion
3.10.3 Stylesheet Import
3.11 Embedded Stylesheet
Modules
3.12 Built-in
Types
3.13 Importing Schema
Components
4 Data Model
4.1 XML
Versions
4.2 Stripping
Whitespace from the Stylesheet
4.3 Stripping Whitespace from a
Source Tree
4.4 Attributes Types
and DTD Validation
4.5 Disable Output
Escaping
5 Syntactic Constructs
5.1 Qualified Names
5.2 Unprefixed
QNames in Expressions and Patterns
5.3 Expressions
5.3.1 Initializing the Static Context
5.3.2 Initializing the Dynamic Context
5.4 Patterns
5.5 Attribute Value Templates
5.6 Sequence
Constructors
5.6.1 Constructing Complex Content
5.6.2 Constructing Simple Content
5.6.3 Namespace Fixup
6 Template Rules
6.1 Defining
Templates
6.2 Defining
Template Rules
6.3 Applying
Template Rules
6.4 Conflict Resolution for
Template Rules
6.5 Modes
6.6 Built-in Template
Rules
6.7 Overriding Template
Rules
7 Repetition
8 Conditional Processing
8.1 Conditional Processing with
xsl:if
8.2 Conditional Processing
with xsl:choose
9 Variables and Parameters
9.1 Variables
9.2 Parameters
9.3 Values of
Variables and Parameters
9.4 Temporary
Trees
9.5 Global Variables
and Parameters
9.6 Local Variables
and Parameters
9.7 Scope of
Variables
9.8 Circular
Definitions
10 Callable Components
10.1 Named
Templates
10.1.1 Passing Parameters to Templates
10.1.2 Tunnel Parameters
10.2 Named Attribute
Sets
10.3 Stylesheet
Functions
11 Creating Nodes and Sequences
11.1 Literal
Result Elements
11.1.1 Setting the Type Annotation for Literal
Result Elements
11.1.2 Attribute Nodes for Literal Result
Elements
11.1.3 Namespace Nodes for Literal Result Elements
11.1.4 Namespace Aliasing
11.2 Creating Element
Nodes using xsl:element
11.2.1 Setting the Type Annotation for a
Constructed Element Node
11.3 Creating
Attribute Nodes using xsl:attribute
11.3.1 Setting the Type Annotation for a
Constructed Attribute Node
11.4 Creating Text
Nodes
11.4.1 Literal Text Nodes
11.4.2 Creating Text Nodes using xsl:text
11.4.3 Generating Text with xsl:value-of
11.5 Creating Processing
Instructions
11.6 Creating
Namespace Nodes
11.7 Creating
Comments
11.8 Copying Nodes from a
Source Tree to a Result Tree
11.8.1 Shallow Copy
11.8.2 Deep Copy
11.9 Constructing Sequences
12 Numbering
12.1 Formatting a Supplied Number
12.2 Numbering based on Position in a
Document
12.3 Number to String
Conversion Attributes
13 Sorting
13.1 The xsl:sort
Element
13.1.1 The Sorting Process
13.1.2 Comparing Sort Key Values
13.1.3 Sorting using Collations
13.2 Creating
a Sorted Sequence
13.3 Processing a
Sequence in Sorted Order
14 Grouping
14.1 The Current
Group
14.2 The Current
Grouping Key
14.3 The
xsl:for-each-group Element
14.4 Examples of
Grouping
15 Regular Expressions
15.1 The
xsl:analyze-string instruction
15.2 Captured
Substrings
15.3 Examples of
Regular Expression Matching
16 Additional Functions
16.1 Multiple Source
Documents
16.2 Reading Text
Files
16.3 Keys
16.3.1 The xsl:key Declaration
16.3.2 The key Function
16.4 Number
Formatting
16.4.1 Defining a Decimal Format
16.4.2 Processing the Picture String
16.4.3 Analysing the Picture String
16.4.4 Formatting the Number
16.5 Formatting Dates and
Times
16.5.1 The Picture String
16.5.2 The language, calendar, and country
arguments
16.5.3 Examples of date and time formatting
16.6 Miscellaneous
Additional Functions
16.6.1 current
16.6.2 unparsed-entity-uri
16.6.3 unparsed-entity-public-id
16.6.4 generate-id
16.6.5 system-property
17 Messages
18 Extensibility and Fallback
18.1 Extension
Functions
18.1.1 Testing Availability of
Functions
18.1.2 Calling Extension Functions
18.1.3 External Objects
18.2 Extension
Instructions
18.2.1 Designating an Extension
Namespace
18.2.2 Testing Availability of
Instructions
18.2.3 Fallback
19 Result Trees
19.1 Creating
Result Trees
19.2 Validation
19.2.1 Validating Constructed Elements and
Attributes
19.2.2 Validating Document Nodes
20 Serialization
20.1 Character
Maps
20.2 Disabling
Output Escaping
21 Conformance
21.1 Basic XSLT
Processor
21.2 Schema-Aware XSLT Processor
21.3 Serialization Feature
21.4 Backwards Compatibility
Feature
A References
A.1 Normative
References
A.2 Other
References
B The XSLT Media Type
B.1 Registration of MIME media type
application/xslt+xml
B.2 Fragment
Identifiers
C Glossary (Non-Normative)
D Element Syntax Summary
(Non-Normative)
E Summary of Error Conditions
(Non-Normative)
F Checklist of
Implementation-Defined Features (Non-Normative)
G Schema for XSLT Stylesheets
(Non-Normative)
H Acknowledgements (Non-Normative)
I Checklist of Requirements (Non-Normative)
J Summary of Issues (Non-Normative)
J.1 Open Issues
J.2 Decided
Issues
J.3 Closed
Issues
K Changes from XSLT 1.0 (Non-Normative)
K.1 Incompatible
Changes
K.1.1 Backwards Compatibility
Behavior
K.1.2 Incompatibility in the Absence of a
Schema
K.1.3 Compatibility in the Presence of a
Schema
K.1.4 XPath 2.0 Backwards Compatibility
K.2 New
Functionality
K.2.1 Pervasive changes
K.2.2 Major Features
K.2.3 Minor Changes
K.2.4 Changes since the May 2003 draft
This specification defines the syntax and semantics of the XSLT 2.0 language.
[Definition: 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]), 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 structure of these trees is described in [Data Model]. 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.
[Definition: 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.10.2 Stylesheet Inclusion and 3.10.3 Stylesheet Import.]
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.
For a full glossary of terms, see C Glossary.
[Definition: The software responsible for transforming source trees into 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.]
[Definition: 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
FO or collection
FO 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.
[Definition: 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.]
[Definition: 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.
A paragraph labeled as a Note or described as an example is 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:
[Definition: The term atomization is defined in Section 2.3.2 AtomizationXP. 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-only content), atomization generates a dynamic error.
[Definition: The
term typed value is defined in Section
5.6 typed-value AccessorDM. Every
node except an element defined in the schema with element-only
content has a typed value. For example, the typed value of an
attribute of type xs:IDREFS
is a sequence of zero or
more xs:IDREF
values.]
[Definition: The term string value is defined in Section 5.5 string-value AccessorDM. 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.]
[Definition: The term XPath 1.0
compatibility mode is defined in Section 2.1.1
Static ContextXP. This is a setting
in the static context of an XPath expression; it has two values,
true
and false
. When the value is set
to true, the semantics of function calls and certain other
operations are adjusted to give a greater degree of backwards
compatibility between XPath 2.0 and XPath 1.0.]
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 D Element Syntax Summary. The meaning of syntax summary notation is as follows:
An attribute that is required is shown with its name in bold. An attribute that may be omitted is shown with a question mark following its name.
The string that occurs in the place of an attribute value
specifies the allowed values of the attribute. If this is
surrounded by curly brackets ({...}
), then the
attribute value is treated as an attribute value template, and
the string occurring within curly brackets 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 states that the value of an attribute must be one of a limited set of values, 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.
This example illustrates the notation used to describe XSLT elements.
<!-- Category: instruction
-->
<xsl:example-element
select = expression
debug? = { "yes" | "no" }>
<!-- Content: ((xsl:variable | xsl:param)*, xsl:sequence) -->
</xsl:example-element>
This example defines a (non-existent) element
xsl:example-element
. The element is classified as an
instruction. It takes a mandatory select
attribute,
whose value is an XPath expression, and an optional debug
attribute, whose value must be either
yes
or no
; the curly brackets indicate
that the value can be defined as an attribute value template,
allowing a value such as debug="{$debug}"
, where the
variable
debug
is evaluated to yield "yes"
or
"no"
at run-time.
The content of an xsl:example-element
instruction
is defined to be a sequence of zero or more xsl:variable
and xsl:param
elements, followed by
an xsl:sequence
element.
[ERR XT0010] 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.
[ERR XT0020] It is a static error if an attribute (other than an attribute written using curly brackets in a position where an attribute value template is permitted) contains a value that is not one of the permitted values for that attribute.
[ERR XT0030] It is a non-recoverable dynamic error if the effective value of an attribute written using curly brackets, 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.9 Forwards-Compatible Processing.
Note:
This working draft includes a non-normative XML Schema for XSLT stylesheet modules (see G Schema for XSLT Stylesheets). The syntax summaries described in this section are normative.
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]. The names of these functions are all in the standard function namespace.
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:
The stylesheet module that is to act as
the principal stylesheet module
for the transformation. The complete stylesheet is assembled by
recursively expanding the xsl:import
and xsl:include
declarations in
the principal stylesheet module, as described in 3.10.2 Stylesheet Inclusion and 3.10.3 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.
[Definition: 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
.
(dot) and self::node()
, as described
in 2.5.1 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 that the initial context size and context position will always be 1 (one) when an initial context node is supplied, and will be undefined if no initial context node is supplied).
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.
[Definition: 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.]
[ERR XT0040] It is a non-recoverable 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.
[ERR
XT0050] It is a non-recoverable dynamic error if
the stylesheet that is invoked declares a visible stylesheet
parameter with required="yes"
and no value for this
parameter is supplied during the invocation of the stylesheet. A
stylesheet parameter is visible if it is not masked by another global
variable or parameter with the same name and higher import
precedence.
[Definition: 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 according to the
rules of the xsl:apply-templates
instruction for processing the initial context node in the initial
mode.]
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.
[ERR
XT0060] It is a non-recoverable dynamic error if
the initial
template defines a template parameter that specifies
required="yes"
.
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
(see 16.1 Multiple Source Documents) or doc
FO or collection
FO (see [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).
[Definition: A stylesheet contains a set of template rules (see 6 Template Rules). A template rule has two parts: a pattern that is matched against nodes, and a sequence constructor that is evaluated to produce a sequence of items. In most cases these items are nodes, which are then written to a result tree.]
A transformation as a whole is executed by evaluating the
sequence constructor of the initial template
as described in 5.6 Sequence
Constructors. If the result 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.
[Definition: The elements appearing within a sequence constructor are referred to as instructions.]
The main categories of instruction elements are as follows:
instructions that create new nodes: xsl:element
, xsl:attribute
, xsl:processing-instruction
,
xsl:comment
, xsl:value-of
, xsl:text
, xsl:namespace
;
an instruction that creates an arbitrary sequence: xsl:sequence
;
instructions that cause conditional or repeated evaluation of
nested instructions: xsl:if
, xsl:choose
, xsl:for-each
, xsl:for-each-group
;
instructions that invoke templates: xsl:apply-templates
,
xsl:apply-imports
,
xsl:call-template
,
xsl:next-match
;
an instruction that declares variables: xsl:variable
;
other specialized instructions: xsl:number
, xsl:analyze-string
,
xsl:message
, xsl:result-document
.
Often, a sequence constructor will include an
xsl:apply-templates
instruction, which selects a sequence of nodes to be processed. Each
of the selected nodes is processed by searching the stylesheet for a
matching template
rule and evaluating the sequence constructor of that template
rule. The resulting sequences of items are concatenated, in order, to
give the result of the xsl:apply-templates
instruction, as described in 6.3
Applying Template Rules; this sequence is often added to a
result tree. Since the sequence constructors of the selected
template rules
may themselves contain xsl:apply-templates
instructions, this results in a cycle of selecting nodes, identifying
template rules,
constructing sequences, and constructing result trees, that recurses
through the source tree.
During the evaluation of a stylesheet, certain information is maintained about the current state of processing. This information is referred to collectively as the evaluation context. The variables that make up the evaluation context are described in this section.
The evaluation context is structured as a stack. When an instruction is evaluated, it inherits the state of the evaluation context from its calling instruction. An instruction may make modifications to the state of the evaluation context, but on return to its caller, the evaluation context is always in the same state as it was on entry to the instruction. The scope of variables in the evaluation context is dynamic; they are passed implicitly from a calling template to a called template, except where otherwise specified.
The variables making up the evaluation context are not available when a stylesheet function is called from an XPath expression. On entry to a stylesheet function, a new empty evaluation context is established. Some variables in an empty evaluation context are said to be undefined, in which case any reference to this variable causes a dynamic error. Other variables are initialized to a defined value, such as an empty sequence.
For convenience, the evaluation context is described in two parts: the focus, which represents the place in the source document that is currently being processed, and a collection of additional context variables.
[Definition: 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:
[Definition: 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).
[Definition: 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()
.
[Definition: 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()
.
[Definition: 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 .
(dot) 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 that 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.
[ERR XT0070] When the focus is undefined, evaluation of any expression that references the context item, context position, or context size results in a non-recoverable dynamic 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.
[Definition: 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 captured
substrings: this is a sequence of strings, 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.2 Captured
Substrings.
The output
state: this is a flag whose two possible values are
final output state and temporary output state. This
flag indicates whether instructions are currently writing to a
final result tree or to an internal data structure. The initial
setting is final output state, and it is
switched to temporary output state by
instructions such as xsl:variable
. For more
details, see 19.1 Creating
Result Trees.
The following non-normative table summarizes the initial state of each of the variables in the evaluation context, and the instructions which cause the state of the variable to change.
Variable | Initial Setting | Set by | Cleared by |
---|---|---|---|
focus | singleton focus based on the initial context node if supplied | xsl:apply-templates ,
xsl:for-each ,
xsl:for-each-group ,
xsl:analyze-string |
calls on stylesheet functions |
current template | the initial template | xsl:apply-templates ,
xsl:apply-imports ,
xsl:next-match |
xsl:for-each , xsl:for-each-group ,
calls on stylesheet functions |
current mode | the initial mode | xsl:apply-templates |
calls on stylesheet functions |
current group | empty sequence | xsl:for-each-group |
calls on stylesheet functions |
current grouping key | empty sequence | xsl:for-each-group |
calls on stylesheet functions |
current captured substrings | empty sequence | xsl:matching-substring |
xsl:non-matching-substring ;
calls on stylesheet functions |
output state | final output state | Set to temporary output state by
instructions such as xsl:variable , xsl:attribute , etc.,
and by calls on stylesheet functions |
None |
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.
[Definition: 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 declarations (the xsl:output
element and the
xsl:character-map
declarations, see 20
Serialization) which allow a stylesheet to specify the desired
properties of a serialized output file. When serialization is
not being performed, either because the implementation does not
support the serialization option, or because the user is executing
the transformation in a way that does not invoke serialization, then
the content of the xsl:output
and xsl:character-map
declarations has no effect. Under these circumstances the processor
may report any errors in an xsl:output
or xsl:character-map
declaration, but is not required to do
so.
XSLT defines a number of features that allow the language to be extended by implementers, or, if implementers choose to provide the capability, by users. These features have been designed, so far as possible, so that they can be used without sacrificing interoperability. Extensions other than those explicitly defined in this specification are not permitted.
These features are all based on XML namespaces; namespaces are used to ensure that the extensions provided by one implementer do not clash with those of a different implementer.
The most common way of extending the language is by providing additional functions, which can be invoked from XPath expressions. These are known as extension functions, and are described in 18.1 Extension Functions.
It is also permissible to extend the language by providing new
XSLT instructions. These are referred to as extension
instructions, and are described in 18.2 Extension Instructions. A
stylesheet that uses extension instructions must declare that it is
doing so by using the [xsl:]extension-element-prefixes
attribute.
Extension instructions and extension functions defined according to these rules may be provided by the implementer of the XSLT processor, and the implementer 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. For further details, see 18 Extensibility and Fallback.
The XSLT language can also be extended by the use of extension attributes (see 3.3 Extension Attributes), and by means of user-defined data elements (see 3.6.1 User-defined Data Elements).
An XSLT stylesheet can make use of information from a 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 untyped 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).
There are places within a stylesheet, and within XPath expressions and patterns in a stylesheet, where it is possible to refer to named type definitions in a schema, or to element and attribute declarations. For example, it is possible to declare the types expected for the parameters of a function. This is done using the SequenceType XP syntax defined in [XPath 2.0].
[Definition: Type definitions and element and attribute declarations are referred to collectively as schema components.]
[Definition: The schema components that may be referenced by name in a stylesheet are referred to as the in-scope schema components. This set is the same throughout a stylesheet.]
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 work unchanged with a schema-aware XSLT
processor, unless the type information created as a result of schema
processing introduces type errors (for example, an attribute of type
xs:integer
cannot be used as an argument of the concat
FO function), or unless the type information
changes the outcome of operations such as comparison and
sorting.
There is a standard set of type definitions that are always available as in-scope schema components in every stylesheet. These are defined in 3.12 Built-in Types. The set of built-in types varies between a basic XSLT processor and a schema-aware XSLT processor.
The remainder of this section describes facilities that are available only with a schema-aware XSLT processor.
Additional schema components (type definitions,
element declarations, and attribute declarations) may be added to the
in-scope schema components by
means of the xsl:import-schema
declaration in a stylesheet.
It is only necessary to import a schema explicitly if one or more of its schema components are referenced explicitly by name 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 type of an 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>
This example will cause the transformation to fail with an error
message unless the document element of the source document is valid
against the top-level element declaration my:invoice
,
and has been annotated as such.
It is possible that a source document may contain nodes whose type
annotation is not one of the types imported by the stylesheet. This
creates a potential problem because in the case of an expression such
as data(.) instance of xs:integer
the system needs to
know whether the type named in the type annotation of the context
node is derived by restriction from the type xs:integer
.
This information is not explicitly available in the data model, as
defined in [Data Model]. The implementation
may choose one of several strategies for dealing with this
situation:
The processor may signal a non-recoverable dynamic error if a source document is found to contain a type annotation that is not known to the processor.
The processor may maintain additional metadata, beyond that
described in [Data Model], that allows
the source document to be processed as if all the necessary
schema information had been imported using xsl:import-schema
. Such
metadata might be held in the data model itself, or it might be
held in a system catalog or repository.
The processor may be configured to use a fixed set of schemas, which are automatically used to validate all source documents before they can be supplied as input to a transformation. In this case it is impossible for a source document to have a type annotation that the processor is not aware of.
The processor may be configured to treat the input data model
as if no schema processing had been performed, that is,
effectively to strip all type annotations from elements and
attributes on input, marking them instead as having type
xdt:untypedAny
and xdt:untypedAtomic
respectively.
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. Under some circumstances (see 2.9 Error Handling) type errors that are detected early may be reported as static errors. In addition an implementation may report any condition found during static analysis as a warning, provided that this does not prevent the stylesheet being evaluated as described by this specification.
A stylesheet can also control the type annotations of nodes that it constructs in a final result tree, or in temporary trees. This can be done in a number of ways.
It is possible to request explicit validation of a complete
result tree. Validation is either strict or lax, as described 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 in all other cases, the element and
attribute nodes of the tree will be annotated with the names of
the 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, attributes, or document nodes are
copied, either explicitly using the xsl:copy
or xsl:copy-of
instructions, 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.
When nodes in a temporary tree are validated, type information is available for use by operations carried out on the temporary tree, in the same way as for a source document that has undergone schema assessment.
For details of how validation of element and attribute nodes works, see 19.2 Validation.
[Definition: 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.9 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.
[Definition: An error that is not detected until a source document is being transformed is referred to as a dynamic error.]
[Definition: 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.
[Definition: If an implementation chooses to recover from a recoverable dynamic error, it must take the optional recovery action defined for that error condition 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 may also take other action, such as logging a warning message.
[Definition: A dynamic error that is not recoverable is referred to as a non-recoverable dynamic error. When a non-recoverable dynamic error occurs, the processor must signal the error, and the transformation fails.]
Because different implementations may optimize execution of the stylesheet in different ways, the detection of dynamic errors is to some degree implementation-dependent. In cases where an implementation is able to produce 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 may choose whether or not to evaluate the variable declaration, which means that if evaluating the variable declaration causes a dynamic error, some implementations will 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.
The XPath specification states, in effect, that an XPath processor may evaluate a constant subexpression during the analysis phase, and if any error occurs during that evaluation, it may report this as a static error. For XPath expressions used in an XSLT stylesheet, however, any such errors must not be reported as static errors in the stylesheet; instead, they must be held back until the evaluation phase, and signaled only if the XPath expression is actually evaluated.
An XPath processor may report statically that the expression
1 div 0
fails with a "divide by zero" error. But
suppose this XPath expression occurs in an XSLT construct such
as:
<xsl:choose> <xsl:when test="system-property('xsl:version') = '1.0'"> <xsl:value-of select="1 div 0"/> </xsl:when> <xsl:otherwise> <xsl:value-of select="xs:double('+INF')"/> </xsl:otherwise> </xsl:choose>
Then the XSLT processor must not report an error, because the relevant XPath construct appears in a context where it will never be executed by an XSLT 2.0 processor. (An XSLT 1.0 processor will execute this code successfully, returning positive infinity, because it uses double arithmetic rather than decimal arithmetic.)
[Definition: Certain errors are classified as type errors. A type error occurs when the value supplied as input to an operation is of the wrong type for that operation, for example when an integer is supplied to an operation that expects a node.] If a type error occurs in an instruction that is actually evaluated, then it must be signaled in the same way as a non-recoverable dynamic error. Alternatively, an implementation may signal a type error during the analysis phase in the same way as a static error, even if it occurs in part of the stylesheet that is never evaluated, provided it can establish that execution of a particular construct would never succeed.
It is implementation-defined whether type errors are signaled statically.
For example, the following construct contains a type error,
because 42
is not allowed as an operand of the
xsl:apply-templates
instruction. An implementation may
optionally signal this as a static error, even though the offending
instruction will never be evaluated, and the type error would
therefore never be signaled as a dynamic error.
<xsl:if test="false()"> <xsl:apply-templates select="42"/> </xsl:if>
On the other hand, in the following example it is not possible
to determine statically whether the operand of xsl:apply-templates
will have a suitable dynamic type. An implementation may produce a warning in such cases, but it
must not treat it as an error.
<xsl:template match="para"> <xsl:param name="p" as="item()"/> <xsl:apply-templates select="$p"/> </xsl:template>
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.
[Definition: 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.
The error codes used to label error conditions in this specification (and summarized in E Summary of Error Conditions) are provided for ease of reference. Implementations may use these codes when signaling errors, but they are not required to do so. An implementation that uses these codes within an API should treat the codes as unprefixed QNames; additional codes defined by an implementation (or by an application) can then use QNames in an implementation-defined namespace without risk of collision.
[Definition: A stylesheet consists of one or more stylesheet modules, each one forming all or part of a well-formed XML document.]
Note:
A stylesheet module, as defined here, contains XML in its raw textual form. In discussing the semantics of a stylesheet module, this specification frequently makes reference to nodes in the data model (see [Data Model]) that is generated when the XML document containing the stylesheet module is parsed. These references should not be taken as implying that an implementation must always start with stylesheet modules as textual XML documents, nor that it must represent the stylesheet internally as an instance of the data model.
A stylesheet module is either a standard stylesheet module or a simplified stylesheet module:
[Definition: A standard stylesheet
module is an XML document, or part of an XML document, having
an xsl:stylesheet
or
xsl:transform
element
as its outermost element (see 3.6
Stylesheet Element).]
[Definition: A simplified stylesheet
module is an XML document, or part of an XML document, whose
outermost element is a literal result element to be
copied to the result tree. This element is not itself in the XSLT
namespace, but it must have an
xsl:version
attribute, which implies that the XSLT
namespace must be declared. For further
details see 3.7 Simplified
Stylesheet Modules. ]
Both forms of stylesheet module (standard and simplified) can exist either as an entire XML document, or embedded as part of another XML document, typically a source document that is to be processed using the stylesheet.
[Definition: A standalone stylesheet module is a stylesheet module that comprises the whole of an XML document.]
[Definition: An embedded stylesheet module is a stylesheet module that is embedded within another XML document, typically the source document that is being transformed.] (see 3.11 Embedded Stylesheet Modules).
There are thus four kinds of stylesheet module:
standalone standard stylesheet modules
standalone simplified stylesheet modules
embedded standard stylesheet modules
embedded simplified stylesheet modules
[Definition: 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.6 Stylesheet Element and
3.7 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 D 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.
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.
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
FO.
[Definition: 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 3.1 XSLT Namespace, is reserved.
[Definition: The standard function
namespace
http://www.w3.org/2003/11/xpath-functions
is used
for functions in the core function library, defined in [Functions and Operators]. ]
[Definition: 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
].
[Definition: 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.
[Definition: 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.
[Definition: The XPath datatypes
namespace
http://www.w3.org/2003/11/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.
[Definition: 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.
[ERR XT0080] 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 decimal-format, a variable or parameter, a stylesheet function, a named output definition, or a character map.
[Definition: 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. These attributes are referred to as extension attributes.] The presence of an extension attribute must not cause the result trees produced by the transformation to be different from the result trees that a conformant XSLT 2.0 processor might produce. They must not cause the processor to fail to signal an error that a conformant processor is required to signal. This means that an extension attribute must not change the effect of any instruction except to the extent that the effect is implementation-defined or implementation-dependent.
Note:
Extension attributes may be used to modify the behavior of extension functions and extension instructions. They may be used to select processing options in cases where the specification leaves the behavior implementation-defined or implementation-dependent. They may also be used for optimization hints, for diagnostics, or for documentation.
Extension attributes may also be used to control what happens to a result tree once the transformation is complete. They may thus be used to provide additional parameters to the serializer, or to override the serialization behavior specified in 20 Serialization.
An implementation that does not recognize the name of an extension attribute, or that does not recognize its value, must perform the transformation as if the extension attribute were not present. As always, it is permissible to produce warning messages.
xsl:message
For example, the following code might be used to indicate to a
particular implementation that the xsl:message
instruction is to
ask the user for confirmation before continuing with the
transformation:
<xsl:message abc:pause="yes" xmlns:abc="http://vendor.example.com/xslt/extensions">Phase 1 complete</xsl:message>
Implementations that do not recognize the namespace
http://vendor.example.com/xslt/extensions
will simply
ignore the extra attribute, and evaluate the xsl:message
instruction in the
normal way.
[ERR XT0090] It is a static error for an element from the XSLT namespace to have an attribute whose namespace is either null (that is, an attribute with an unprefixed name) or the XSLT namespace, other than attributes defined for the element in this document.
The media type application/xslt+xml
will be
registered for XSLT stylesheet modules.
The proposed definition of the media type is at B The XSLT Media Type
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.
[Definition: 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 implementer 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.
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.8 Backwards-Compatible Processing and 3.9 Forwards-Compatible Processing
[xsl:]xpath-default-namespace
[xsl:]exclude-result-prefixes
[xsl:]extension-element-prefixes
<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
.
[ERR
XT0100] An xsl:stylesheet
element
must have a version
attribute,
indicating the version of XSLT that the stylesheet
module requires.
[ERR
XT0110] The value of the version
attribute
must be a number (specifically, it
must be a DecimalLiteral
XP 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 module was written
with the intention that it should be
processed using an XSLT 1.0 processor.
If a stylesheet
that specifies [xsl:]version="1.0"
in the outermost
element of the principal stylesheet module
(that is, version="1.0"
in the case of a standard stylesheet module, or
xsl:version="1.0"
in the case of a simplified stylesheet module)
is submitted to an XSLT 2.0 processor, the processor should output a warning advising the user of possible
incompatibilities, unless the user has requested otherwise. The
processor must then process the stylesheet
using the rules for backwards-compatible
behavior. These rules require that if the processor does not
support backwards-compatible
behavior, it must signal an error and
must not execute the transformation.
When the value of the version
attribute is greater
than 2.0, forwards-compatible behavior
is enabled (see 3.9 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 module 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 will
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.
[ERR
XT0120] An xsl:stylesheet
element
must not have any text node children.
(This rule applies after stripping of whitespace
text nodes as described in 4.2
Stripping Whitespace from the Stylesheet)
[Definition: An element
occurring as a child of an xsl:stylesheet
element is
called a top-level element.]
[Definition: 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.6.1 User-defined Data Elements)]
The declaration
elements permitted in the xsl:stylesheet
element
are:
xsl:import
xsl:include
xsl:attribute-set
xsl:character-map
xsl:decimal-format
xsl:function
xsl:import-schema
xsl:key
xsl:namespace-alias
xsl:output
xsl:param
xsl:preserve-space
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.
[Definition: In addition to declarations, the xsl:stylesheet
element may
contain any element not from the XSLT namespace, provided that the
expanded-QName of the element has a
non-null namespace URI. Such elements are referred to as
user-defined data elements.]
[ERR
XT0130] It is a static error if the xsl:stylesheet
element has a
child element whose name has a null namespace URI.
An implementation may attach an
implementation-defined
meaning to user-defined data elements that appear in
particular namespaces. The set of namespaces that are
recognized for such data elements is implementation-defined. The
presence of a user-defined data element must
not change the behavior of XSLT elements and functions
defined in this document; for example, it is not permitted for a
user-defined data element to specify that xsl:apply-templates
should use different rules to resolve conflicts. The
constraints on what user-defined data elements can and cannot do
are exactly the same as the constraints on extension
attributes, described in 3.3
Extension Attributes. Thus, an implementation is
always free to ignore user-defined data elements, and must ignore such data elements without giving an
error if it does not recognize the namespace URI.
User-defined data elements can provide, for example,
information used by extension instructions or extension functions (see 18 Extensibility and Fallback),
information about what to do with the result tree,
information about how to obtain the source tree,
optimization hints for the processor,
metadata about the stylesheet,
structured documentation for the stylesheet.
[ERR
XT0140] A user-defined data element must not precede an xsl:import
element within a
stylesheet module.
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. The literal result element must
have an xsl:version
attribute (and it must therefore
also declare the XSLT namespace). Such a stylesheet
module is equivalent to a standard stylesheet module
whose xsl:stylesheet
element contains a template rule containing the literal result
element, minus its xsl:version
attribute;
the template rule has a match pattern of /
.
For example:
<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>
has the same meaning as
<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>
Note that it is not possible, using a simplified stylesheet, to
request that the serialized output contains a DOCTYPE
declaration. This can only be done by using a standard stylesheet
module, and using the xsl:output
element.
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>
[ERR
XT0150] 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 will normally be
2.0
; the value must be a
DecimalLiteral
XP 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.8 Backwards-Compatible
Processing). When the xsl:version
attribute is
numerically greater than 2.0
, forwards-compatible behavior
is enabled (see 3.9 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.
[Definition: An element enables
backwards-compatible behavior for itself, its attributes, its
descendants and their attributes if it has an
[xsl:]version
attribute (see 3.5 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.
If an attribute containing an XPath expression is processed with
backwards-compatible behavior, then the expression is evaluated with
XPath 1.0 compatibility mode set to
true
. For details of this mode, see Section
XP.
Certain XSLT constructs also produce different results when backwards-compatible behavior is enabled. This is described separately for each such construct.
These rules do not apply to the xsl:output
element, whose
version
attribute has an entirely different purpose: it
is used to define the version of the output method to be used for
serialization.
Note:
By making use of backwards-compatible behavior, it is possible to write the stylesheet in a way that ensures that its results when processed with an XSLT 2.0 processor are identical 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 a 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.
[ERR XT0160] If an implementation does not support backwards-compatible behavior, then it is a non-recoverable dynamic error if any element is evaluated that enables backwards-compatible behavior.
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:import-schema
.
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.
[Definition: An element enables
forwards-compatible behavior for itself, its attributes, its
descendants and their attributes if it has an
[xsl:]version
attribute (see 3.5 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: it is used to define the
version of the output method to be used for serialization.
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 includes, but is not limited to, the following situations:
if an element in the XSLT namespace appears as a child
of the xsl:stylesheet
element, and XSLT 2.0 does not allow such elements as
declarations, then the element must be
ignored along with its content;
if an element in the XSLT namespace appears in a sequence constructor and XSLT 2.0 does not allow such elements to occur in sequence constructors, then the processor must not signal an error, and if the element is evaluated, the processor must perform fallback for the element as specified in 18.2.3 Fallback;
if an element has an attribute that XSLT 2.0 does not allow the element to have, then the attribute must be ignored.
if an 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 instruction element has a mandatory attribute with a value that XSLT 2.0 does not allow the attribute to have, then the error must not be signaled unless the instruction is actually evaluated.
if an attribute contains an XPath expression that does not match the allowed syntax of an XPath 2.0 expression, the error must not be signaled unless the expression is actually evaluated.
if an attribute contains an XPath expression that calls a function that cannot be identified by its name and arity, the error must not be signaled unless the function call is actually evaluated.
For example, an XSLT 2.0 processor will process the following stylesheet without error, although the stylesheet includes elements from the XSLT namespace that are not defined in this specification:
<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.
For example,
<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="number(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>
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.
The include and import mechanisms use two declarations, xsl:include
and xsl:import
, which are defined in
the sections that follow.
These declarations use an href
attribute, whose
value is a URI reference, to identify the stylesheet
module to be included or imported. If the value of this
attribute is a relative URI, it is resolved using the algorithm
defined in [RFC2396], relative to the base
URI of the xsl:include
or xsl:import
element as
defined in [Data Model].
After resolving against the base URI, the way in which the URI reference is used to locate a stylesheet module is implementation-defined. In particular, it is implementation-defined which URI schemes are supported, whether fragment identifiers are supported, and what media types are supported. Conventionally, the URI is a reference to a resource containing the stylesheet module as a source XML document, or it may include a fragment identifier that selects an embedded stylesheet module within a source XML document; but the implementation is free to use other mechanisms to locate the stylesheet module identified by the URI reference.
The referenced stylesheet module may be any of the four kinds of stylesheet module: that is, it may be standalone or embedded, and it may be standard or simplified. If it is a simplified stylesheet module then it is transformed into the equivalent standard stylesheet module by applying the transformation described in 3.7 Simplified Stylesheet Modules.
Implementations may choose to accept URI references containg a fragment identifier defined by reference to the XPointer specification (see [XPointer]). Note that if the implementation does not support the use of fragment identifiers in the URI reference, then it will not be possible to include an embedded stylesheet module.
[ERR XT0165] It is a static error if the processor is not able to retrieve the resource identified by the URI reference, or if the resource that is retrieved does not contain a stylesheet module conforming to this specification.
<!-- Category: declaration
-->
<xsl:include
href =
uri-reference />
A stylesheet module may include another stylesheet module using
an xsl:include
declaration.
The xsl:include
declaration has a required
href
attribute whose value is a URI reference
identifying the stylesheet module to be included. This attribute is
used as described in 3.10.1 Locating
Stylesheet Modules.
[ERR
XT0170] An xsl:include
element
must be a top-level element.
[Definition: A stylesheet level is a collection of
stylesheet modules connected using
xsl:include
declarations: specifically, two stylesheet modules A and
B are part of the same stylesheet level if one of them
includes the other by means of an xsl:include
declaration, or if
there is a third stylesheet module C that is in the same
stylesheet level as both A and B.]
[Definition: The declarations within a stylesheet level
have a total ordering known as declaration order. The order
of declarations within a stylesheet level is the same as the
document order that would result if each stylesheet module were
inserted textually in place of the xsl:include
element that
references it.] In other respects,
however, the effect of xsl:include
is not equivalent
to the effect that would be obtained by textual inclusion.
[ERR XT0180] It is a static error if a stylesheet module directly or indirectly includes itself.
Note:
It is not intrinsically an error for a stylesheet to include the same module more than once. However, doing so can cause errors because of duplicate definitions. Such multiple inclusions are less obvious when they are indirect. For example, if stylesheet B includes stylesheet A, stylesheet C includes stylesheet A, and stylesheet D includes both stylesheet B and stylesheet C, then A will be included indirectly by D twice. If all of B, C and D are used as independent stylesheets, then the error can be avoided by separating everything in B other than the inclusion of A into a separate stylesheet B' and changing B to contain just inclusions of B' and A, similarly for C, and then changing D to include A, B', C'.
<!-- Category: declaration
-->
<xsl:import
href =
uri-reference />
A stylesheet module may import another stylesheet
module using an xsl:import
declaration. Importing a
stylesheet module is the same as including it (see
3.10.2 Stylesheet Inclusion) except
that template
rules and other declarations in the importing
module take precedence over template rules and
declarations in the imported module; this is described
in more detail below.
The xsl:import
declaration has a required
href
attribute whose value is a URI reference
identifying the stylesheet module to be included. This attribute is
used as described in 3.10.1 Locating
Stylesheet Modules.
[ERR
XT0190] An xsl:import
element must be a top-level element.
[ERR
XT0200] The xsl:import
element children
must precede all other element children
of an xsl:stylesheet
element, including any xsl:include
element children
and any user-defined data elements.
xsl:import
For example,
<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>
[Definition: The
stylesheet
levels making up a stylesheet are treated as forming an import
tree. In the import tree, each stylesheet level has one child
for each xsl:import
declaration that it contains.] The
ordering of the children is the declaration order of the xsl:import
declarations within
their stylesheet level.
[Definition: A declaration D in the stylesheet is defined to have lower import precedence than another declaration E if the stylesheet level containing D would be visited before the stylesheet level containing E in a post-order traversal of the import tree (that is, a traversal of the import tree in which a stylesheet level is visited after its children). Two declarations within the same stylesheet level have the same import precedence.]
For example, suppose
stylesheet module A imports stylesheet modules B and C in that order;
stylesheet module B imports stylesheet module D;
stylesheet module C imports stylesheet module E.
Then the import tree has the following structure:
A | +---+---+ | | B C | | D E
The order of import precedence (lowest first) is D, B, E, C, A.
In general, a declaration with higher import precedence takes precedence over a declaration with lower import precedence. This is defined in detail for each kind of declaration.
[ERR XT0210] It is a static error if a stylesheet module directly or indirectly imports itself.
Note:
The case where a stylesheet module with a particular URI is imported several times is not treated specially. The effect is exactly the same as if several stylesheet modules with different URIs but identical content were imported. This might or might not cause an error, depending on the content of the stylesheet module.
A standalone 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 may
have an ID attribute that specifies a unique identifier.
Note:
In order for such an attribute to be used with the XPath
id
FO 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
Processing Instruction
The following example shows how the xml-stylesheet
processing instruction (see [XML
Stylesheet]) can be used to allow a source document to contain
its own stylesheet. The URI reference uses a relative URI with a
fragment identifier to locate the xsl:stylesheet
element:
<?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
confirmation: see 3.4
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 required for
conformance with this Recommendation.
Every XSLT 2.0 processor includes the following named type definitions in the in-scope schema components:
xs:string
xs:boolean
xs:integer
xs:decimal
xs:double
xs:date
xs:time
xs:dateTime
xs:QName
xs:anyURI
xdt:yearMonthDuration
xdt:dayTimeDuration
xdt:anyAtomicType
xdt:untypedAtomic
These types are defined in [XML Schema]
(Part 2) in the case of the names prefixed xs:
, and in
[XPath 2.0] in the case of those prefixed
xdt:
.
A schema-aware XSLT processor additionally supports:
All other built-in types defined in [XML Schema] (Part 2)
User-defined types, and element and attribute declarations,
that are imported using an xsl:import-schema
declaration as described in 3.13
Importing Schema Components. These may include both
simple and complex types.
Note:
The names that are imported from the XML Schema namespace do not
include all the names of top-level types defined in either the
Schema for Schemas or the Schema for Datatypes. The Schema for
Datatypes, as well as defining built-in types such as
xs:integer
and xs:double
, also defines
types that are intended for use only within the Schema for
DataTypes, such as xs:derivationControl
. A stylesheet that is designed
to process XML Schema documents as its input or output may import
the Schema for Schemas.
An implementation may define mechanisms that allow additional schema components to be added to the in-scope schema components for the stylesheet. 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.
These schema components are the only ones that
may be referenced in XPath expressions within the stylesheet, or in
the [xsl:]type
and as
attributes of those
elements that permit these attributes.
Note:
The facilities described in this section are not available with a basic XSLT processor. They require a schema-aware XSLT processor, as described in 21 Conformance.
<!-- 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, top-level type
definitions and top-level element and attribute declarations) that
need to be available statically, that is, before any source document
is available. Names of such components used statically within
the stylesheet must
refer to an in-scope schema component, which
means they must either be built-in types as defined in 3.12 Built-in Types, or they must be
imported using an xsl:import-schema
declaration.
The xsl:import-schema
declaration identifies a namespace containing the names of the
components to be imported (or indicates that components whose names
are in no namespace are to be imported). The effect is that the names
of top-level element and attribute declarations and type definitions
from this namespace (or non-namespace) become available for use
within XPath expressions in the stylesheet, and within other stylesheet
constructs such as the type
and as
attributes of various XSLT elements.
The same schema components are available in all stylesheet modules; importing components 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. If this leaves more than one, then all the
declarations at the highest import precedence are used (which may
cause conflicts, as described below).
After discarding any xsl:import-schema
declarations under the above rule, the effect of the remaining
xsl:import-schema
declarations is defined in terms of a
hypothetical document called the synthetic schema document, which is
constructed as follows. The synthetic schema document defines an
arbitrary target namespace that is different from any namespace
actually used by the application, and it contains
xs:import
elements corresponding one-for-one with the
xsl:import-schema
declarations in the stylesheet, with the following
correspondence:
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.
The schema components included in the in-scope schema components (that is, the components whose names are available for use within the stylesheet) are the top-level element and attribute declarations and type definitions that are available for reference within the synthetic schema document. See [XML Schema] (Part 1, section 4.2.3, References to schema components across namespaces).
[ERR XT0220] It is a static error if the synthetic schema document does not satisfy the constraints described in [XML Schema] (Part 1, section 5.1, Errors in Schema Construction and Structure). This includes, without loss of generality, conflicts such as multiple definitions of the same name..
Note:
The synthetic schema document does not need to be constructed by
a real implementation. It is purely a mechanism for defining the
semantics of xsl:import-schema
in
terms of rules that already exist within the XML Schema
specification. In particular, it implicitly defines the rules that
determine whether the set of xsl:import-schema
declarations are mutually consistent.
These rules do not cause names to be imported transitively. The fact that a name is available for reference within a schema document A does not of itself make the name available for reference in a stylesheet that imports the target namespace of schema document A. (See [XML Schema] Part 1, section 3.15.3, Constraints on XML Representations of Schemas.) The stylesheet must import all the namespaces containing names that it actually references.
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.
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 a hint
indicating where a schema document or other resource containing the
required definitions may be found. It is likely that a schema-aware XSLT processor
will be able to process a schema document found at this
location.
The XML Schema specification gives implementations flexibility in how to handle multiple imports for the same namespace. Multiple imports do not cause errors if the definitions do not conflict.
A consequence of these rules is that it is not intrinsically an
error if no schema document can be located for a namespace
identified in an xsl:import-schema
declaration. This will cause an error only if it results in the
stylesheet containing references to names that have not been
imported.
The use of a namespace in an xsl:import-schema
declaration does not by itself associate any namespace prefix with
the namespace. If names from the namespace are used within the
stylesheet module then a namespace declaration must be included in
the stylesheet module, in the usual way.
The data model used by XSLT is the XPath 2.0 and XQuery 1.0 data model, as defined in [Data Model]. XSLT operates on source, result and stylesheet documents using the same data model.
This section elaborates on some particular features of the data model as it is used by XSLT:
The rules in 4.2 Stripping Whitespace from the Stylesheet and 4.3 Stripping Whitespace from a Source Tree make use of the concept of a whitespace text node.
[Definition: A whitespace text node is a text node whose content consists entirely of whitespace characters (that is, #x09, #x0A, #x0D, or #x20).]
Note:
Features of a source XML document that are not represented in the tree defined by the data model will have no effect on the operation of an XSLT stylesheet. Examples of such features are entity references, CDATA sections, character references, whitespace within element tags, and the choice of single or double quotes around attribute values.
The data model defined in [Data Model] is capable of representing either an XML 1.0 document (conforming to [XML 1.0] and [XML Namespaces 1.0]) or an XML 1.1 document (conforming to [XML 1.1] and [XML Namespaces 1.1]), and it makes no distinction between the two. In principle, therefore, XSLT 2.0 can be used with either of these XML versions; the only differences arise outside the boundary of the transformation proper, either while creating the data model from textual XML (parsing), or while producing textual XML from the data model (serialization).
Construction of the data model is outside the scope of this specification, so XSLT 2.0 places no formal requirements on an XSLT processor to accept input from either XML 1.0 documents or XML 1.1 documents or both. This specification does define a serialization capability (see 20 Serialization), though from a conformance point of view it is an optional feature. Although facilities are described for serializing the data model as either XML 1.0 or XML 1.1 (and controlling the choice), there is again no formal requirement on an XSLT processor to support either or both of these XML versions as serialization targets.
Because the data model is the same whether the original document was XML 1.0 or XML 1.1, the semantics of XSLT processing do not depend on the version of XML used by the original document. There is no reason in principle why all the input and output documents used in a single transformation must conform to the same version of XML.
Some of the syntactic constructs in XSLT 2.0 and XPath 2.0, for example the productions Char XML and NCName Names, are defined by reference to the XML and XML Namespaces specifications. There are slight variations between the XML 1.0 and XML 1.1 versions of these productions. It is recommended that an XSLT 2.0 processor should implement the 1.1 versions.
At the time of writing there is no published version of [XML Schema] that references the XML 1.1
specifications. This means that data types such as
xs:NCName
and xs:ID
are constrained by the
XML 1.0 rules. It is recommended that an
XSLT 2.0 processor should implement the rules in later versions of
[XML Schema] as they become available.
The tree representing the stylesheet is preprocessed as follows:
All comments and processing instructions are removed.
Any text nodes that are now adjacent to each other are merged.
Any whitespace text node that satisfies both the following conditions is removed from the tree:
The parent of the text node is not an xsl:text
element
The text node does not have an ancestor element that has
an xml:space
attribute with a value of
preserve
, unless there is a closer ancestor
element having an xml:space
attribute with a
value of default
.
Any whitespace text node whose parent
is one of the following elements is removed from the tree,
regardless of any xml:space
attributes:
xsl:analyze-string
xsl:apply-imports
xsl:apply-templates
xsl:attribute-set
xsl:call-template
xsl:character-map
xsl:choose
xsl:next-match
xsl:stylesheet
xsl:transform
Any whitespace text node whose
following-sibling node is an xsl:param
or xsl:sort
element is removed from
the tree, regardless of any xml:space
attributes.
[ERR
XT0260] Within an XSLT element that is required to be empty, any content other than comments
or processing instructions, including any whitespace
text node preserved using the xml:space="preserve"
attribute, is a static error.
A source document supplied as input to the transformation process may contain whitespace text nodes that are of no interest, and that do not need to be retained by the transformation. Conceptually, an XSLT processor makes a copy of the source tree from which unwanted whitespace text nodes have been removed. This process is referred to as whitespace stripping.
The stripping process takes as input a set of element names whose child whitespace text nodes are to be preserved.
A whitespace text node is preserved if either of the following apply:
The element name of the parent of the text node is in the set of whitespace-preserving element names.
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 whitespace 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.
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.
<!-- Category: declaration
-->
<xsl:strip-space
elements = tokens />
<!-- Category: declaration
-->
<xsl:preserve-space
elements = tokens />
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 among all
the 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
XP; an element name matches an xsl:strip-space
or xsl:preserve-space
element
if it matches one of the NameTests
XP. An element matches a NameTest
XP if and only if the NameTest
XP 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
XP. 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.
[ERR XT0270] It is a recoverable dynamic error if this leaves more than one match. The optional recovery action is to select, from 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 conforming to the data model described in [Data Model]. 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.
The data model allows attribute nodes to have type annotations derived from schema processing. It is also possible for a limited set of type annotations (on attributes only) to be derived from DTD-based validation of a source document. Because the construction of the data model is outside the scope of XSLT processing, this specification (in common with [Data Model]) neither requires nor prevents this. This section merely points out some of the consequences of the decision.
In general, creating type annotations based on DTD attribute types
is likely to create some backwards compatibility problems. For
example, an attribute annotated with type xs:NMTOKENS
will have a different typed value than if it were annotated as
xdt:untypedAtomic
. If the value of the
colors
attribute is red green blue
, then
the expression @colors = "red"
will return
true
if the type annotation is xs:NMTOKENS
,
but false
if the type annotation is
xdt:untypedAtomic
.
Special considerations apply to ID
attributes,
because in XSLT 1.0, attributes defined in a DTD as having type
ID
were explicitly recognized by the XPath id
FO function. An XSLT 2.0 processor wishing to
offer the best possible backwards compatibility should therefore recognize ID
attributes
during DTD processing, and annotate the resulting nodes accordingly,
even though it does not recognize other DTD-based types such as
NMTOKENS
.
The conformance rules for a basic XSLT processor do not allow
attribute nodes to be annotated with type xs:ID
. For
backwards compatibility reasons, however, a processor may implement the id
FO function so that it recognizes attributes
defined in a DTD as being ID attributes, even though they are not
annotated as being of type xs:ID
in the data model.
A basic XSLT processor does not allow
nodes to be annotated as being of type xs:IDREF
or
xs:IDREFS
, which means that with such a processor, the
idref
FO function will always return an empty
sequence.
For backwards compatibility reasons, XSLT 2.0 continues to support
the disable-output-escaping
feature introduced in XSLT
1.0. This is an optional feature and implementations are not
required to support it. A new facility,
that of named character maps (see 20.1 Character Maps) is introduced in
XSLT 2.0. It provides similar capabilities to
disable-output-escaping
, but without distorting the data
model.
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 has a boolean property indicating whether the serializer
is to 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
can be
viewed not so much a property stored with nodes in the tree, but
rather as additional information passed across the interface
between the XSLT processor and the serializer.
The name of a stylesheet-defined object, specifically a named template, a mode, an attribute set, a key, a decimal-format, a variable or parameter, a stylesheet function, a named output definition, or a character map is specified as a QName using the syntax for QNameNames as defined in [XML Namespaces 1.0].
[Definition: 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, as described
below.]
Because an atomic value of type xs:QName
is sometimes
referred to loosely as a QName, this specification also uses the term
lexical QName
to emphasize that it is referring to a QNameNames
in its lexical form rather than its expanded form. This term is used
especially when strings containing lexical QNames are manipulated as
run-time values.
[Definition: A
lexical QName is a string representing a QName in the form (NCName ":")?
NCName
, that is, a local name optionally preceded by a
namespace prefix.]
[Definition: QNames may occur 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.]
[Definition: An expanded-QName is a pair of values containing a local name and an optional namespace URI. Two expanded-QNames are equal if the namespace URIs are the same (or both absent) and the local names are the same.]
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.
There are two cases where the default namespace from the static context is used when expanding an unprefixed QName:
Where a QName is used to define the name of an element being
constructed in the result tree. This applies both to cases where
the name is known statically (that is, the name of a literal
result element) and to cases where it is computed dynamically
(the value of the name
attribute of the xsl:element
instruction).
The default namespace is used when expanding the first
argument of the function element-available
.
In the case of an unprefixed QName used as a NameTest
within an XPath expression (see 5.3
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.2 Unprefixed QNames in
Expressions and Patterns.
[ERR XT0280] In the case of a prefixed QName used as the value of an attribute in the stylesheet, or appearing within an XPath expression in the stylesheet, it is a static error if the defining element has no namespace node whose name matches the prefix of the QName.
[ERR XT0290] Where the result of evaluating an XPath expression (or an attribute value template) is required to be a lexical QName, then unless otherwise specified it is a non-recoverable dynamic error if the defining element has no namespace node whose name matches the prefix of the lexical QName. This error may be signaled as a static error if the value of the expression can be determined statically.
Note:
In some cases this is defined as a recoverable dynamic error, for
example when evaluating the name
attribute of xsl:element
and xsl:attribute
The attribute [xsl:]xpath-default-namespace
(see
3.5 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.
The value of the attribute is the namespace URI to be used.
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.
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 of the following constructs appearing within its scope:
any unprefixed element name or type name used in a pattern
any unprefixed element name used in the elements
attribute of the xsl:strip-space
or
xsl:preserve-space
instructions
any unprefixed element name or type name used in the
as
attribute of an XSLT instructions
any unprefixed type name used in the type
attribute of an XSLT instruction.
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.
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.
[Definition: Within this specification, the term XPath expression, or simply expression, means a string that matches the production ExprXP defined in [XPath 2.0].]
An XPath expression may occur as the value of certain attributes on XSLT-defined elements, and also within curly brackets in attribute value templates.
[ERR XT0300] Except where forwards-compatible behavior is enabled (see 3.9 Forwards-Compatible Processing), it is a static error if the value of such an attribute, or the text between curly brackets in an attribute value template, does not match the XPath production ExprXP, 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.
[ERR XT0310] The transformation fails with a non-recoverable dynamic error if any XPath expression is evaluated and raises a dynamic error.
[ERR XT0320] The transformation fails with a type error if an XPath expression raises a type error, or if the result of evaluating the XPath expression is evaluated and raises a type error, or if the XPath processor signals a type error during static analysis of an expression.
[Definition: 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()*
.
[Definition: Except where otherwise
indicated, the actual value of an expression is converted to the required type using the
function 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 XPath 1.0 compatibility mode is set to
false
.]
This specification also invokes the XPath 2.0 function conversion rules to
convert the result of evaluating an XSLT sequence
constructor to a required type (for example, the sequence
constructor enclosed in an xsl:variable
, xsl:template
, or xsl:function
element).
Any dynamic error or type error that occurs when applying the function conversion rules to convert a value to a required type results in the transformation failing, in the same way as if the error had occurred while evaluating an expression.
Note:
Note the distinction between the two kinds of error that may
occur. Attempting to convert an integer to a date is a type error,
because such a conversion is never possible. Type errors can be
reported statically if they can be detected statically, whether or
not the construct in question is ever evaluated. Attempting to
convert the string 2003-02-29
to a date is a dynamic
error rather than a type error, because the problem is with this
particular value, not with its type. Dynamic errors are reported
only if the instructions or expressions that cause them are
actually evaluated.
XPath defines the concept of an expression contextXP which contains all the information that can affect the result of evaluating an expression. The evaluation context has two parts, the static contextXP, and the dynamic contextXP. The components that make up the expression context are defined in the XPath specification (see Section 2.1 Expression ContextXP). The following paragraphs describe the way in which these components are initialized when an XPath expression is contained within an XSLT stylesheet.
The static contextXP of an XPath expression appearing in an XSLT stylesheet is initialized as follows. In these rules, the term containing element means the element within the stylesheet that is the parent of the attribute whose value contains the XPath expression in question.
XPath 1.0 compatibility mode is set to true if and only if the containing element occurs in part of the stylesheet where backwards compatible behavior is enabled (see 3.8 Backwards-Compatible Processing).
The in-scope namespacesXP are the namespace declarations that are in scope for the containing element.
The default
namespace for element names and type
namesXP is the namespace defined
by the [xsl:]xpath-default-namespace
attribute on
the innermost containing element that has such an
attribute, as described in 5.2 Unprefixed QNames in Expressions
and Patterns. The value of this attribute is a
namespace URI. If there is no
[xsl:]xpath-default-namespace
attribute on a
containing element, the default namespace for element names and
type names is the null namespace.
The default namespace
for function namesXP 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 is it necessary to use the
prefix fn
(or any other prefix) in calls to the
core functions.
The in-scope schema definitionsXP for the XPath expression are the same as the in-scope schema components for the stylesheet, and are as specified in 3.12 Built-in Types.
The in-scope variablesXP are defined by the variable binding elements that are in scope for the containing element (see 9 Variables and Parameters).
The in-scope functionsXP are the core functions defined in [Functions and Operators], 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).
[ERR XT0330] It is a non-recoverable dynamic error for an expression to call any function that is not included in the in-scope functions. This error occurs only if the function call is actually evaluated.
The in-scope collationsXP are implementation-defined. However, the set of in-scope collations must always include the Unicode codepoint collation, defined in Section 7.3 Equality and Comparison of StringsFO.
The default collationXP is implementation-defined.
[Definition: In this specification the term
default collation means the collation that is used by
XPath operators such as eq
and lt
appearing in XPath expressions within the
stylesheet.]
This collation is also used by default when comparing
strings in the evaluation of the xsl:key
and xsl:for-each-group
elements. This may also (but need not
necessarily) be the same as the default collation used for
xsl:sort
elements
within the stylesheet. Collations used by xsl:sort
are described in
13.1.3 Sorting using
Collations.
Implementations should provide a mechanism allowing the user to select the default collation to be used by XPath expressions within a stylesheet.
The base URIXP is the base URI of the containing element. The concept of the base URI of a node is defined in Section 5.1 base-uri AccessorDM
The dynamic contextXP of an XPath expression appearing in an XSLT stylesheet is initialized as follows.
Where the containing element is an instruction or a literal result 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.
In other cases, the rules are given in the specification of the containing element.
The dynamic variablesXP are the current values of the in-scope variable binding elements.
The current date and time represents an implementation-dependent point in time during processing of the transformation; it does not change during the course of the transformation.
The implicit timezoneXP is implementation-defined.
The available documentsXP, and the available collectionsXP are implementation-dependent.
The available
documentsXP are defined as part
of the XPath 2.0 dynamic context to support the doc
FO function, but this variable is also
referenced by the similar XSLT document
function: see
16.1 Multiple Source Documents.
This variable defines a mapping between URIs passed to the
doc
FO or document
function and the
document nodes that are returned.
Note:
Defining this as part of the evaluation context is a formal way of specifying that the way in which URIs get turned into document nodes is outside the control of the language specification, and depends entirely on the run-time environment in which the transformation takes place.
Unlike the doc
FO function, the XSLT-defined document
function allows
the use of URI references containing fragment identifiers. The
interpretation of a fragment identifier depends on the media
type of the resource. Therefore, the information supplied in
available
documentsXP for XSLT processing
must provide not only a mapping from URIs to document nodes as
required by XPath, but also a mapping from URIs to media
types.
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).
[Definition: 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.
Here are some examples of patterns:
para
matches any para
element.
*
matches any element.
chapter|appendix
matches any
chapter
element and any appendix
element.
olist/entry
matches any entry
element with an olist
parent.
appendix//para
matches any para
element with an appendix
ancestor element.
element(us:address)
matches any element that is
annotated as an instance of the type defined by the schema
element declaration us:address
, and whose name is
either us:address
or the name of another element
in its substitution group.
attribute(*, xs:date)
matches any attribute
annotated as being of type xs:date
.
/
matches a document node.
document-node()
matches a document node.
document-node(element(my:invoice))
matches the
document node of a document whose document element
matches the element declaration
my:invoice
.
text()
matches any text node.
node()
matches any node other than an attribute
node, namespace node, or document node.
id("W33")
matches the element with unique
ID.
para[1]
matches any para
element
that is the first para
child element of its
parent. It also matches a parentless para
element.
//para
matches any para
element
that has a parent node.
bullet[position() mod 2 = 0]
matches any
bullet
element that is an even-numbered
bullet
child of its parent.
div[@class="appendix"]//p
matches any
p
element with a div
ancestor element
that has a class
attribute with value
appendix
.
@class
matches any class
attribute
(not any element that has a class
attribute).
@*
matches any attribute node.
[ERR
XT0340] 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 |
or
union
, where each step in the path expression is
constrained to be an AxisStep
XP that uses only the child
or
attribute
axes. Patterns may also use the
//
operator. Predicates
XP in a pattern can contain arbitrary XPath
expressions (enclosed between square brackets) in the same way as
predicates in a path expression.
Patterns may start with an id
FO 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.8 Backwards-Compatible Processing), then the semantics of the pattern are defined on the basis that the equivalent XPath expression is evaluated with XPath 1.0 compatibility mode set to true.
[1] | Pattern |
::= | PathPattern |
| Pattern ('|' | 'union')
PathPattern |
|||
[2] | PathPattern |
::= | RelativePathPattern |
| '/' RelativePathPattern? |
|||
| '//' RelativePathPattern |
|||
| IdKeyPattern (('/' |
'//') RelativePathPattern)? |
|||
[3] | RelativePathPattern |
::= | PatternStep (('/' |
'//') RelativePathPattern)? |
[4] | PatternStep |
::= | PatternAxis? NodeTest
XP Predicates
XP |
[5] | PatternAxis |
::= | ('child' '::' | 'attribute' '::' | '@') |
[6] | IdKeyPattern |
::= | 'id' '(' IdValue
')' |
| 'key' '(' StringLiteral
XP ',' KeyValue
')' |
|||
[7] | IdValue |
::= | StringLiteral
XP | VarRef
XP |
[8] | KeyValue |
::= | Literal
XP | VarRef
XP |
The constructs NodeTest XP, Predicates XP, VarRef XP, Literal XP, and StringLiteral XP 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
PS of this
RelativePathPattern
is adjusted to allow it to match a
parentless element or attribute node, as follows:
If the NodeTest
in PS is
document-node()
(optionally with arguments), and if
no explicit axis is specified, then the axis in step
PS is taken as self
rather than
child
.
If PS uses the child axis (explicitly or
implicitly), and if the NodeTest
in PS is
not document-node()
(optionally with arguments),
then the axis in step PS is replaced by
child-or-top
, which is defined as follows. If the
context node is a parentless element, comment,
processing-instruction, or text 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 PS uses the attribute axis, then the axis in
step PS is replaced by attribute-or-top
,
which is defined as follows. If the context node is an attribute
node with no parent, 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.
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.
Note:
The purpose of these adjustments 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. The
pattern node()
will match any element, text node,
comment, or processing instruction, whether or not it has a parent.
For backwards compatibility reasons, the pattern
node()
, when used without an explicit axis, does not
match document nodes, attribute nodes, or namespace nodes. The
rules are also phrased to ensure that positional patterns of the
form para[1]
continue to count nodes relative to their
parent, if they have one.
Let the equivalent expression, calculated according to these rules, be EE.
To determine whether a node N matches the pattern,
evaluate the expression root(.)//(EE)
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.
For example, p
matches any p
element,
because a p
element will always be present in the
result of evaluating the expression
root(.)//(child-or-top::p)
. Similarly, /
matches a document node, and only a document node,
because the result of the expression root(.)//(/)
returns
the root node of the tree containing the context node if and
only if it is a document node.
The pattern node()
matches all nodes selected by
the expression root(.)//(child-or-top::node())
, that
is, all element, text, comment, and processing instruction nodes,
whether or not they have a parent. 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 because for backwards compatibility reasons the
child-or-top
axis does not match a document
node.
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
root(.)//(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 way in which the processor evaluates a pattern may affect the
detection of dynamic errors. For example, given the
pattern chapter[P]/section[Q]
, where P
and
Q
are arbitrary expressions, an error in evaluating
Q
might or might not be signaled while matching a
section
element that has no chapter parent, and an error
in evaluating P
might or might not be signaled while
matching an element that is not a section
. In general,
it is well defined whether a node matches a pattern, but it is not
well defined whether or not dynamic errors will be signaled when
evaluating a pattern against a node that does not match the
pattern.
One particular optimization is required
by this specification: for a PathPattern that starts with /
or
//
or with an IdKeyPattern, the result of testing this
pattern against a node in a tree whose root is not a document node
must be a non-match, rather than a dynamic error. This rule applies
to each to each PathPattern within a
Pattern.
Note:
Without the above rule, any attempt to apply templates to a
parentless element node would create the risk of a dynamic error if
the stylesheet has a template rule specifying
match="/"
.
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 definition by evaluating the equivalent expression and then testing the membership of a specific node in the result would probably be very inefficient.
[Definition: 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 brackets
({}
)].
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 brackets ({}
). A fixed part may contain any
characters, except that a left curly bracket must be written as {{
and a right curly
bracket must be written as
}}
.
Note:
An expression within a variable part may contain an unescaped curly bracket within a StringLiteral XP or within a comment.
[ERR XT0350] It is a static error if an unescaped left curly bracket appears in a fixed part of an attribute value template without a matching right curly bracket.
[ERR XT0360] It is a static error if the string contained between matching curly brackets in an attribute value template does not match the XPath production ExprXP.
[ERR XT0370] It is a static error if an unescaped right curly bracket occurs in a fixed part of an attribute value template.
[Definition: 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 brackets ({{
or
}}
) by the corresponding single curly bracket. 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.
Note:
This process can generate dynamic errors, for example if the
sequence contains an xs:QName
(which cannot be cast to
a string), or an element with a complex content type (which cannot
be atomized).
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 brackets 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 brackets.
Note:
Not all attributes are designated 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 designated as attribute value templates. Namespace declarations are not attribute nodes in the data model and are therefore never treated as attribute value templates.
The following example creates an img
result element
from a photograph
element in the source; the value of
the src
and width
attributes are computed
using XPath expressions enclosed in attribute value templates:
<xsl:variable name="image-dir" select="'/images'"/> <xsl:template match="photograph"> <img src="{$image-dir}/{href}" width="{size/@width}"/> </xsl:template>
With this source
<photograph> <href>headquarters.jpg</href> <size width="300"/> </photograph>
the result would be
<img src="/images/headquarters.jpg" width="300"/>
The following example shows how the values in a sequence are output as a space-separated list. The following literal result element:
<temperature readings="{10.32, 5.50, 8.31}"/>
produces the output node:
<temperature readings="10.32 5.5 8.31"/>
Curly brackets are not recognized recursively inside expressions.
For example:
<a href="#{id({@ref})/title}">
is not allowed. Instead, use simply:
<a href="#{id(@ref)/title}">
[Definition: A sequence constructor is a sequence of zero or more sibling nodes in the stylesheet that can be evaluated to return a sequence of nodes and atomic values. The way that the resulting sequence is used depends on the containing instruction.]
Many XSLT elements (including literal result elements) are defined to take a sequence constructor as their content.
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.2 Stripping Whitespace from the Stylesheet) 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 expanded-QName 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.
Extension instructions (see 18.2 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. 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
FO 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. This happens when the instruction containing the
sequence constructor is xsl:analyze-string
,
xsl:apply-imports
,
xsl:apply-templates
,
xsl:call-template
,
xsl:choose
, xsl:fallback
, xsl:for-each
, xsl:for-each-group
,
xsl:if
, xsl:matching-substring
,
xsl:next-match
,
xsl:non-matching-substring
,
xsl:otherwise
,
xsl:perform-sort
,
xsl:sequence
, or
xsl:when
The sequence may be used to construct the content of a new
element or document node. This happens when the sequence
constructor appears as the content of a literal result element,
or of one of the instructions xsl:copy
, xsl:element
, 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, text node, namespace node, comment
node, or processing instruction node. This happens when the
sequence constructor is contained in one of the elements xsl:attribute
,
xsl:value-of
,
xsl:namespace
,
xsl:comment
, or
xsl:processing-instruction
.
For details, see 5.6.2
Constructing Simple Content.
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.
This section describes how the sequence obtained by evaluating a
sequence constructor may be used to
construct the children of a newly constructed document node, or the
children, attributes and namespaces of a newly constructed element
node. The sequence of items may be obtained by evaluating the
sequence constructor contained in an
instruction such as xsl:copy
, xsl:element
, xsl:result-document
, or
a literal result element.
The sequence is processed as follows:
The containing instruction may generate attribute nodes
and/or namespace nodes, as specified in the rules for the
individual instruction. For example, these nodes may be
produced by expanding an [xsl:]use-attribute-sets
attribute, or by expanding the attributes of a literal result element. Any
such nodes are prepended to the sequence produced by evaluating
the sequence constructor.
Any atomic value in the sequence is cast to a string.
Special considerations apply to two atomic types for which
casting to xs:string
is not possible:
[ERR XT0380] A recoverable dynamic error
occurs if the sequence contains an atomic value of type
xs:QName
, because such values
cannot be cast to a string. The optional recovery action
is to ignore the offending
xs:QName
value.
Any consecutive sequence of strings within the result sequence is converted to a single text node, whose string value contains the content of each of the strings in turn, with a with a single space (#x20) used as a separator between successive strings. If this process would create a text node whose string value is zero-length, no text node is created and the content is discarded.
Any document node within the result sequence is replaced by a sequence containing each of its children, in document order.
Adjacent text nodes within the result sequence are merged into a single text node.
Invalid namespace and attribute nodes are detected as follows.
[ERR XT0410] It is a recoverable dynamic error if the result sequence used to construct the content of an element node contains a namespace node or attribute node that is preceded in the sequence by a node that is neither a namespace node nor an attribute node. The optional recovery action is to ignore the offending namespace or attribute node.
[ERR XT0420] It is a recoverable dynamic error if the result sequence used to construct the content of a document node contains a namespace node or attribute node. The optional recovery action is to ignore the offending namespace or attribute node.
[ERR XT0430] It is a recoverable dynamic error if the result sequence contains two or more namespace nodes having the same name but different string values (that is, namespace nodes that map the same prefix to different namespace URIs). The optional recovery action is to discard all conflicting namespace nodes other than the one that appears last in the result sequence.
[ERR XT0440] It is a recoverable dynamic error if the result sequence contains a namespace node with no name and the element node being constructed has a null namespace URI (that is, it is an error to define a default namespace when the element is in no namespace). The optional recovery action is to ignore the offending namespace node.
If the result sequence contains two or more namespace nodes with the same name (or no name) and the same string value (that is, two namespace nodes mapping the same prefix to the same namespace URI), then all but one of the duplicate nodes are discarded.
Note:
Since the order of namespace nodes is undefined, it is not significant which of the duplicates is retained.
If an attribute A in the result sequence has the same name as another attribute B that appears later in the result sequence, then attribute A is discarded from the result sequence.
Each node in the resulting sequence is attached as a
namespace, attribute, or child of the newly constructed element
or document node. Conceptually this involves making a deep copy
of the node; in practice, however, copying the node will only
be necessary if the existing node can be referenced
independently of the parent to which it is being attached. When
copying an element node, its base URI property is changed to be
the same as that of its new parent, unless it has an
xml:base
attribute (see [XMLBASE]) that overrides this.
If the newly constructed node is an element node, then namespace fixup is applied to this node, as described in 5.6.3 Namespace Fixup
For example, consider the following stylesheet fragment:
<td> <xsl:attribute name="valign">top</xsl:attribute> <xsl:value-of select="@description"/> </td>
This fragment consists of a literal result element
td
, containing a sequence constructor that consists
of two instructions: xsl:attribute
and xsl:value-of
. The sequence
constructor is evaluated to produce a sequence of two nodes: a
parentless attribute node, and a parentless text node. The
td
instruction causes a td
element to
be created; the new attribute therefore becomes an attribute of
the new td
element, while the text node created by
the xsl:value-of
instruction becomes a child of the td
element.
The xsl:attribute
,
xsl:comment
, xsl:processing-instruction
,
xsl:namespace
,
and xsl:value-of
elements
create nodes that cannot have children. Specifically, the
xsl:attribute
instruction creates an attribute node, xsl:comment
creates a comment
node, xsl:processing-instruction
creates a processing instruction node, xsl:namespace
creates a
namespace node, and xsl:value-of
creates a text
node. The string value of the new node is constructed using either
the select
attribute of the instruction, or the
sequence constructor that forms the
content of the instruction. The select
attribute
allows the content to be specified by means of an XPath expression,
while the sequence constructor allows it to be specified by means
of a sequence of XSLT instructions. The select
attribute or sequence constructor is evaluated to produce a result
sequence, and the string value of the new node is derived from
this result sequence in the following way:
The sequence is atomized.
Every value in the atomized sequence is cast to
a string. Special considerations apply to atomic values of type
xs:QName
:
[ERR XT0450] A recoverable dynamic error
occurs if the sequence contains a value of type
xs:QName
, because such values
cannot be cast to a string. The optional recovery action
is to ignore the
xs:QName
value.
Note:
An example showing how to construct QName-valued
attributes (specifically, an xsi:type
attribute) is given in 11.6 Creating Namespace
Nodes. Essentially, the application is
responsible for choosing a namespace prefix, and this can
then be used firstly to create a namespace node by using
the xsl:namespace
instruction, and secondly to construct the lexical
QName, which is then written directly as the
attribute value.
The strings within the resulting sequence are concatenated,
with a (possibly zero-length) separator inserted between
successive strings. When the select
attribute is
used the default separator is a single space character (#x20).
When the value is constructed using a sequence
constructor, the default separator is a zero-length string.
In the case of xsl:attribute
and
xsl:value-of
, a different separator can be
specified using the separator
attribute of the
instruction; it is permissible for this to be a zero-length
string, in which case the strings are concatenated with no
separator. In the case of xsl:comment
, xsl:processing-instruction
,
and xsl:namespace
the default separator cannot be changed.
The string that results from this concatenation forms the string value of the new attribute, namespace, comment, processing-instruction, or text node.
In a tree supplied to or constructed by an XSLT processor, the following constraints relating to namespace nodes must be satisfied in addition to those specified in [Data Model]:
If an element node has an expanded-QName with a non-null namespace URI, then that element node must have at least one namespace node whose string value is the same as that namespace URI.
If an element node has an attribute node whose expanded-QName has a non-null namespace URI, then the element must have at least one namespace node whose string value is the same as that namespace URI and whose name is non-empty.
Every element must
have a namespace node whose expanded-QName has local-part
xml
and whose string value is
http://www.w3.org/XML/1998/namespace
. The
namespace prefix xml
must not be associated with
any other namespace URI, and the namespace URI
http://www.w3.org/XML/1998/namespace
must not be
associated with any other prefix.
A namespace node must not have the
name xmlns
.
If an element is annotated with the type
xs:QName
, or a type derived from
xs:QName
, or if it has an attribute with such a
type annotation, then that element must have a namespace node whose string value is the
same as the namespace URI of that QName value, and whose name
is the same as the prefix used in the lexical representation of
the QName (if the lexical representation is unprefixed, the
namespace node must be unnamed).
[Definition: The rules for the individual XSLT instructions that construct a result tree (see 11 Creating Nodes and Sequences) prescribe some of the situations in which namespace nodes are written to the tree. These rules, however, are not sufficient to ensure that the above constraints are always satisfied. The XSLT processor must therefore add additional namespace nodes to satisfy these constraints. This process is referred to as namespace fixup.]
The actual namespace nodes that are added to the tree by the namespace fixup process are implementation-defined, provided firstly, that at the end of the process the above constraints must all be satisfied, and secondly, that a namespace node must not be added to the tree unless the namespace node is necessary either to satisfy these constraints, or to enable the tree to be serialized using the original namespace prefixes from the source document or stylesheet.
Namespace fixup must not result in an element having multiple namespace nodes with the same name.
Namespace fixup is applied to every element that is constructed
using a literal result element, or one of
the instructions xsl:element
, xsl:copy
, or xsl:copy-of
. An implementation
is not required to perform namespace
fixup for elements in any source document, that is,
documents loaded using the document
, doc
FO or collection
FO function, documents supplied as the value
of a stylesheet parameter, or documents
returned by an extension function or extension
instruction.
[ERR XT0490] It is a recoverable dynamic error if such a source document does not already satisfy the constraints listed above . This is a recoverable error. The optional recovery action is either to perform namespace fixup, or to produce implementation-dependent results.
In an InfoSet (see [XML Information Set]) created from a document conforming to [XML Namespaces 1.0], it will always be true that if a parent element has an in-scope namespace with a non-empty namespace prefix, then its child elements will also have an in-scope namespace with the same namespace prefix, though possibly with a different namespace URI. This constraint is removed in [XML Namespaces 1.1]. XSLT 2.0 supports the creation of result trees that do not satisfy this constraint: the namespace fixup process does not add a namespace node to an element merely because its parent node in the result tree has such a namespace node.
Note:
This has implications on serialization, defined in [XSLT and XQuery Serialization]. It
means that it is possible to create result trees that cannot be
faithfully serialized as XML 1.0 documents. When such a result
tree is serialized as XML 1.0, namespace declarations written for
the parent element will be inherited by its child elements as if
the corresponding namespace nodes were present on the child
element, except in the case of the default namespace, which
can be undeclared using the construct
xmlns=""
. When the same result tree is
serialized as XML 1.1, however, it is possible to undeclare any
namespace on the child element (for example,
xmlms:foo=""
) to prevent this inheritance
taking place.
Template rules define the processing that can be applied to nodes that match a particular pattern.
<!-- Category: declaration
-->
<xsl:template
match? = pattern
name? = qname
priority? = number
mode? = tokens
as? = sequence-type>
<!-- Content: (xsl:param*, sequence-constructor)
-->
</xsl:template>
[Definition: An xsl:template
declaration defines
a template, which contains a sequence
constructor 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
(see 5.6 Sequence
Constructors). If an as
attribute is present,
the as
attribute defines the required type of the
result.
The result of evaluating the sequence constructor is converted to the required type using the function conversion rules.
If no as
attribute is specified, the default value is
item()*
, which permits any value. No conversion then
takes place.
This section describes template rules. Named templates are 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
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.
For example, an XML document might contain:
This is an <emph>important</emph> point.
The following template rule matches emph
elements and produces a fo:wrapper
element with a
font-weight
property of bold
.
<xsl:template match="emph"> <fo:wrapper font-weight="bold" xmlns:fo="http://www.w3.org/1999/XSL/Format"> <xsl:apply-templates/> </fo:wrapper> </xsl:template>
A template
rule is evaluated when an xsl:apply-templates
instruction selects a node that matches the pattern specified in the
match
attribute. The xsl:apply-templates
instruction is described in the next section. If several template
rules match a selected node, only one of them is evaluated, as
described in 6.4 Conflict Resolution for
Template Rules.
<!-- Category: instruction
-->
<xsl:apply-templates
select? = 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 the input
sequence is sorted as described in 13
Sorting. The result of this sort is referred to below
as the sorted sequence; if there are no xsl:sort
elements, then the sorted
sequence is the same as the input sequence.
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 in 6.4 Conflict Resolution for
Template Rules. If there is no template rule whose pattern
matches the node, a built-in template rule is used (see 6.6 Built-in Template Rules). The chosen
template rule is evaluated. The rule that matches the Nth
node in the sorted sequence is evaluated with that node as the
context item,
with N as the context position, and with the length of
the sorted 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 sorted sequence) are then
concatenated, to form a single sequence. They are concatenated
retaining the order of the nodes in the sorted sequence. The final
concatenated sequence forms the result of the xsl:apply-templates
instruction.
Suppose the source document is as follows:
<message>Proceed <emph>at once</emph> to the exit!</message>
This can be processed using the two template rules shown below.
<xsl:template match="message"> <p> <xsl:apply-templates select="child::node()"/> </p> </xsl:template> <xsl:template match="emph"> <b> <xsl:apply-templates select="child::node()"/> </b> </xsl:template>
There is no template rule for the document node; the built-in
template rule for this node will cause the message
element to be processed. The template rule for the
message
element causes a p
element to be
written to the result tree; the contents of this p
element are constructed as the result of the xsl:apply-templates
instruction. This instruction selects the three child nodes of the
message
element (a text node containing the value
"Proceed
", an emph
element node, and a
text node containing the value " to the exit!
"). The
two text nodes are processed using the built-in template rule for
text nodes, which returns a copy of the text node. The
emph
element is processed using the explicit template
rule that specifies match="emph"
.
When the emph
element is processed, this template
rule constructs a b
element. The contents of the
b
element are constructed by means of another xsl:apply-templates
instruction, which in this case selects a single node (the text
node containing the value "at once
"). This is again
processed using the built-in template rule for text nodes, which
returns a copy of the text node.
The final result of the match="message"
template
rule thus consists of a p
element node with three
children: a text node containing the value "Proceed
",
a b
element that is the parent of a text node
containing the value "at once
", and a text node
containing the value " to the exit!
". This result tree
might be serialized as:
<p>Proceed <b>at once</b> to the exit!</p>
The default value of the select
attribute is
child::node()
, which causes all the children of context
node to be processed.
Note:
This includes child element nodes, text nodes, comments, and processing instructions. It does not, however, include attributes.
[ERR
XT0510] It is a recoverable dynamic error if an xsl:apply-templates
instruction with no select
attribute is evaluated when
the context item
is not a node. The optional recovery action is to
return the empty sequence.
Note:
If stripping of whitespace text 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
FO function. This typically means that the
child elements will be numbered 2, 4, 6... This effect can be
prevented by stripping whitespace text nodes as specified in
4.3 Stripping Whitespace from a Source
Tree, or by writing <xsl:apply-templates
select="*"/>
to avoid processing the child text
nodes.
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).
[ERR
XT0520] It is a type error if the sequence returned by the
select
expression contains an item that is not a
node.
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.
The following example processes all of the
given-name
children of the author
elements that are children of author-group
:
<xsl:template match="author-group"> <fo:wrapper> <xsl:apply-templates select="author/given-name"/> </fo:wrapper> </xsl:template>
It is also possible to process elements that are not descendants
of the context node. This example assumes that a
department
element has group
children and
employee
descendants. It finds an employee's
department and then processes the group
children of
the department
.
<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>
It is possible to write template rules that are matched according to the schema-defined type of an element or attribute. The following example applies different formatting to the children of an element depending on their type:
<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>
The xsl:next-match
instruction
is described in 6.7 Overriding Template
Rules.
Multiple xsl:apply-templates
elements can be used within a single template to do simple
reordering. The following example creates two HTML tables. The
first table is filled with domestic sales while the second table is
filled with foreign sales.
<xsl:template match="product"> <table> <xsl:apply-templates select="sales/domestic"/> </table> <table> <xsl:apply-templates select="sales/foreign"/> </table> </xsl:template>
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.
This means that if the template rule for the div
element processes its own children, then these grandchildren will
be processed more than once, which is probably not what is
required. The solution is to process one level at a time in a
recursive descent, by using select="div"
in place of
select=".//div"
Note:
The xsl:apply-templates
instruction is most commonly used to process 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.
It is possible for a node in a source document to match more than one template rule. When this happens, only one template rule is evaluated for the node. The template rule to be used is determined as follows:
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.
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.
[ERR
XT0530] The value of this must be a decimal number (positive or
negative), matching the production IntegerLiteral
XP or DecimalLiteral
XP with an optional leading minus
sign (-
).
[Definition: If no priority
attribute is
specified on the xsl:template
element, a
default priority is computed, based on the syntax of the
pattern supplied in the match
attribute.] The rules are as follows:
If the pattern contains multiple alternatives separated by
|
or union
, 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
XP)
or
processing-instruction(
NCName
Names)
optionally
preceded by a PatternAxis, then
the priority is 0.
If the pattern has the form of an ElementTest
XP or AttributeTest
XP, 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 symbol *
represents itself. A SchemaContextPath
XP may be specified in addition to the
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 XP, then if it includes no ElementTest XP the priority is −0.5. If if does include an ElementTest XP, then the priority is the same as the priority of that ElementTest XP, computed according to the table above.
If the pattern has the form NCName
Names:*
or
*:
NCName
Names, optionally preceded by a PatternAxis, then the priority is
−0.25.
If the pattern is any other NodeTest XP, 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.
[ERR XT0540] It is a recoverable dynamic error if the conflict resolution algorithm for template rules leaves more than one matching template rule. The optional recovery action is to select, from the matching template rules that are left, the one that occurs last in declaration order.
[Definition: 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 be one of the
following:
a QName, which is expanded as described in 5.1 Qualified Names to define the name of the mode
the token #default
, to indicate that the template
rule is applicable to the default mode
the token #all
, to indicate that the template
rule is applicable to all modes.
[ERR
XT0550] 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.
[Definition: 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).
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 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 always used when xsl:apply-templates
selects a namespace node.
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.
<!-- 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 import
precedence and/or priority. Both instructions will invoke
the built-in template rule for the node (see 6.6 Built-in Template Rules) if no other
template rule is found.
[Definition: At any point in the processing of a
stylesheet, there may
be a current template rule. Whenever a template rule is chosen
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
instruction may use xsl:with-param
child elements
to pass parameters to the chosen template rule (see 10.1.1 Passing Parameters to Templates).
It also passes on any tunnel parameters as described in 10.1.2 Tunnel Parameters.
[ERR
XT0560] It is a non-recoverable dynamic error if
xsl:apply-imports
or xsl:next-match
is
evaluated when the current template rule is null.
xsl:apply-imports
For example, suppose the stylesheet doc.xsl
contains a template rule for example
elements:
<xsl:template match="example"> <pre><xsl:apply-templates/></pre> </xsl:template>
Another stylesheet could import doc.xsl
and modify
the treatment of example
elements as follows:
<xsl:import href="doc.xsl"/> <xsl:template match="example"> <div style="border: solid red"> <xsl:apply-imports/> </div> </xsl:template>
The combined effect would be to transform an
example
into an element of the form:
<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.
<!-- Category: instruction -->
<xsl:for-each
select = sequence-expression>
<!-- Content: (xsl:sort*,
sequence-constructor) -->
</xsl:for-each>
The xsl:for-each
instruction processes each item in a sequence of items, evaluating the
sequence constructor within the xsl:for-each
instruction once for
each item in that sequence.
The select
attribute is required, and the expression must evaluate
to a sequence, called the input sequence. If there is an xsl:sort
element present (see 13 Sorting) the input sequence is sorted to
produce a sorted sequence. Otherwise, the sorted sequence is the same
as the input sequence.
The xsl:for-each
instruction contains a sequence constructor, which is evaluated
once for each item in the sorted sequence. The sequence
constructor is evaluated with the focus set as follows:
The context
item is the item being processed. If this is a node, it will
also be the context
node. If it is not a node, there will be no context node: that
is, the value of self::node()
will be an empty
sequence.
The context position is the position of this item in the sorted sequence.
The context size is the size of the sorted sequence (which is the same as the size of the input sequence).
For each item in the input sequence, evaluating the sequence
constructor produces a sequence of items (see 5.6 Sequence Constructors). These
output sequences are concatenated; if item Q follows
item P in the sorted sequence, then the result of evaluating
the sequence constructor with Q as the context item is
concatenated after the result of evaluating the sequence constructor
with P as the context item. The result of the
xsl:for-each
instruction
is the concatenated sequence of items.
Note:
With XSLT 1.0, the selected nodes were processed in document order. With XSLT 2.0, XPath expressions that would have been valid under XPath 1.0 (such as path expressions and union expressions) will return a sequence of nodes that is already in document order, so backwards compatibility is maintained.
xsl:for-each
For example, given an XML document with this structure
<customers> <customer> <name>...</name> <order>...</order> <order>...</order> </customer> <customer> <name>...</name> <order>...</order> <order>...</order> </customer> </customers>
the following would create an HTML document containing a table
with a row for each customer
element
<xsl:template match="/"> <html> <head> <title>Customers</title> </head> <body> <table> <tbody> <xsl:for-each select="customers/customer"> <tr> <th> <xsl:apply-templates select="name"/> </th> <xsl:for-each select="order"> <td> <xsl:apply-templates/> </td> </xsl:for-each> </tr> </xsl:for-each> </tbody> </table> </body> </html> </xsl:template>
There are two instructions in XSLT that support conditional
processing in a template: xsl:if
and xsl:choose
. The xsl:if
instruction provides simple
if-then conditionality; the xsl:choose
instruction supports
selection of one choice when there are several possibilities.
xsl:if
<!-- Category: instruction -->
<xsl:if
test = expression>
<!-- Content: sequence-constructor
-->
</xsl:if>
The xsl:if
element has a
mandatory test
attribute, which specifies an expression. The content is a
sequence constructor.
The result of the xsl:if
instruction depends on the effective boolean
valueXP 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 (see 5.6 Sequence Constructors), and
the resulting node sequence is returned as the result of the xsl:if
instruction; otherwise,
the sequence constructor is not evaluated, and the empty
sequence is returned.
xsl:if
In the following example, the names in a group of names are formatted as a comma separated list:
<xsl:template match="namelist/name"> <xsl:apply-templates/> <xsl:if test="not(position()=last())">, </xsl:if> </xsl:template>
The following colors every other table row yellow:
<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>
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 the order that the elements appear in the
stylesheet), until one of the xsl:when
elements is satisfied.
If none of the xsl:when
elements is satisfied, then
the xsl:otherwise
element is considered, as described below.
An xsl:when
element is
satisfied if the effective boolean
valueXP 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:choose
The following example enumerates items in an ordered list using arabic numerals, letters, or roman numerals depending on the depth to which the ordered lists are nested.
<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>
[Definition: The two elements xsl:variable
and xsl:param
are referred to as
variable-binding elements ].
[Definition: The xsl:variable
element declares a
variable, which may be a global variable or a local
variable.]
[Definition: The xsl:param
element declares a
parameter, which may be a stylesheet parameter, a template
parameter, or a function parameter. A parameter is a
variable with the
additional property that its value can be set by the caller when the
stylesheet, the template, or the function is invoked.]
[Definition: A variable is a binding between a name and a value. The value of a variable is any sequence (of nodes and/or atomic values), as defined in [Data Model].]
<!-- 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
XP, as defined in [XPath
2.0].
[Definition: The value of the variable is computed using the
expression given in
the select
attribute 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.] If the xsl:variable
element has a
select
attribute, then the sequence constructor
must be empty.
If the as
attribute is specified, then the supplied value of the
variable is converted to the required type, using the function conversion rules.
[ERR XT0570] It is a type error if the supplied value of a variable cannot be converted to the required type.
If the as
attribute is omitted, the supplied value of the
variable is used directly, and no conversion takes place.
<!-- Category: declaration -->
<xsl:param
name = qname
select? = expression
as? = sequence-type
required? = "yes" | "no"
tunnel? = "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.
[ERR XT0580] It is a static error if two parameters of a template or of a stylesheet function have the same name.
Note:
For rules concerning stylesheet parameters, see 9.5 Global Variables and Parameters. Local variables may shadow template parameters and function parameters: see 9.7 Scope of Variables.
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 or the contained sequence
constructor, as described in 9.3
Values of Variables and Parameters. If the xsl:param
element has a
select
attribute, then the sequence constructor
must be empty.
Note:
This specification does not dictate whether and when the default
value of a parameter is evaluated. For example, if the default is
specified as <xsl:param
name="p"><foo/></xsl:param>
, then it is not
specified whether a distinct foo
element node will be
created on each invocation of the template or function, or whether
the same foo
element node will be used for each
invocation. However, it is permissible for the default value to be
depend on the values of other parameters, or on the evaluation
context, in which case the default must effectively be evaluated on
each invocation.
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
XP, as defined in [XPath
2.0].
If the as
attribute is specified, then the supplied value of the
parameter is converted to the required type, using the function conversion rules.
[ERR XT0590] It is a type error if the conversion of the supplied value of a parameter to its required type fails.
If the as
attribute is omitted, the supplied value of the
parameter is used directly, and no conversion takes place.
The optional 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. A parameter is mandatory if it is a function
parameter or if the required
attribute is present
and has the value yes
. Otherwise, the parameter is
optional. If the parameter is mandatory, then the xsl:param
element must be empty and must not
have a select
attribute.
[ERR
XT0600] If a default value is given explicitly, that is,
if there is either a select
attribute or a non-empty
sequence constructor, then it is a
type error if the
default value cannot be converted to the required type, using the
function conversion rules.
If an optional parameter has no select
attribute and
has an empty sequence constructor, and if there is
no as
attribute, then the default value of the parameter
is a zero length string.
[ERR
XT0610] If an optional parameter has no
select
attribute and has an empty sequence
constructor, and if there is an as
attribute, then
the default value of the parameter is an empty sequence. If the empty
sequence is not a valid instance of the required type defined in the
as
attribute, then the parameter is treated as a
required parameter, which means that it is a non-recoverable dynamic error if the
caller supplies no value for the parameter.
Note:
The effect of these rules is that specifying <xsl:param
name="p" as="xs:date" select="2"/>
is an error, but if
the default value of the parameter is never used, then the
processor has discretion whether or not to report the error. By
contrast, <xsl:param name="p" as="xs:date"/>
is
treated as if required="yes"
had been specified: the
empty sequence is not a valid instance of xs:date
, so
in effect there is no default value and the parameter is therefore
treated as being mandatory.
The optional tunnel
attribute may be used to indicate
that a parameter is a tunnel parameter. The default is
no
; the value yes
may be specified only for
template
parameters. Tunnel parameters are described in 10.1.2 Tunnel 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="''"/>
[Definition: If a variable-binding element
has no select
attribute and has non-empty content
(that is, 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
(see 5.6 Sequence
Constructors).
These combinations are summarized in the table below.
select attribute | as attribute | content | Effect |
---|---|---|---|
present | absent | empty | Value is obtained by
evaluating the select attribute |
present | present | empty | Value is obtained by
evaluating the select attribute, adjusted to the
type required by the as attribute |
present | absent | present | Static error |
present | present | present | Static error |
absent | absent | empty | Value is a zero-length string |
absent | present | empty | Value is an empty
sequence, provided the as attribute permits an
empty sequence |
absent | absent | present | Value is a temporary tree |
absent | present | present | Value is obtained by
evaluating the sequence constructor, adjusted to the type
required by the as attribute |
[ERR
XT0620] It is a static error if a variable-binding element has a
select
attribute and has non-empty content.
The value of the following variable is the sequence of integers (1, 2, 3):
<xsl:variable name="i" as="xs:integer*" select="1 to 3"/>
The value of the following variable is an integer, assuming that
the attribute @size
exists, and is annotated either as
an integer, or as xdt:untypedAtomic
:
<xsl:variable name="i" as="xs:integer" select="@size"/>
The value of the following variable is a zero-length string:
<xsl:variable name="z"/>
The value of the following variable is document node containing an empty element as a child (that is, a temporary tree):
<xsl:variable name="doc"><c/></xsl:variable>
The value of the following variable is sequence of integers (2, 4, 6):
<xsl:variable name="seq" as="xs:integer*"> <xsl:for-each select="1 to 3"> <xsl:sequence select=".*2"/> </xsl:for-each> </xsl:variable>
The value of the following variable is sequence of parentless attribute nodes:
<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>
The value of the following variable is an empty sequence:
<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.
When a variable is used to select nodes by position, be careful not to do:
<xsl:variable name="n">2</xsl:variable> ... <xsl:value-of select="td[$n]"/>
This will output the value of the first td
element,
because the variable n
will be bound to a node, not a
number. Instead, do one of the following:
<xsl:variable name="n" select="2"/> ... <xsl:value-of select="td[$n]"/>
or
<xsl:variable name="n">2</xsl:variable> ... <xsl:value-of select="td[position()=$n]"/>
or
<xsl:variable name="n" as="xs:integer">2</xsl:variable> ... <xsl:value-of select="td[$n]"/>
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
FO 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.
For example, the following stylesheet uses a temporary tree as the intermediate result of a two-phase transformation, using different modes for the two phases (see 6.5 Modes):
<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 a good idea to use modes to ensure that each tree is processed using the appropriate set of template rules.
Both xsl:variable
and
xsl:param
are allowed as
declaration
elements: that is, they may appear as children of the xsl:stylesheet
element.
[Definition: A top-level variable-binding element declares a global variable that is visible everywhere (except where it is shadowed by another binding).]
[Definition: 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.] As described in 9.2 Parameters, a stylesheet parameter may
be declared as being mandatory, or may have a default value specified
for use when no value is supplied by the caller. The
mechanism by which the caller supplies a value for a stylesheet
parameter is implementation-defined. An
XSLT processor
must provide such a mechanism.
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.
[ERR XT0630] 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, unless it also contains another binding with the same name and higher 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. An XPath error will be reported if the evaluation of a global variable or parameter references the context item, context position, or context size when no initial context node is supplied.
The following example declares a global parameter
para-font-size
, which it references in an attribute value template.
<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>
The implementation must provide a mechanism
allowing the user to supply a value for the parameter
para-font-size
when invoking the stylesheet; the value
12pt
acts as a default.
[Definition: 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.]
[Definition: 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
.
]
[Definition: 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.
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.
[Definition: 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.
The following is allowed:
<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.
The following is not an error, but is discouraged, because the
effect is probably not what was intended. The template outputs
<x value="1"/>
, because the declaration of the
inner variable named $x
has no effect on the value of
the outer variable named $x
.
<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.
[Definition: 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.]
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"/>
[ERR XT0640] In general, a circularity in a stylesheet is a non-recoverable dynamic 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.
This section describes three constructs that can be used to provide subroutine-like functionality that can be invoked from anywhere in the stylesheet: named templates (see 10.1 Named Templates), named attribute sets (see 10.2 Named Attribute Sets) and stylesheet functions (see 10.3 Stylesheet Functions).
<!-- Category: instruction
-->
<xsl:call-template
name = qname>
<!-- Content: xsl:with-param* -->
</xsl:call-template>
[Definition: 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
instruction 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 have
no effect when the template is invoked by an xsl:call-template
instruction. Similarly, the name
attribute on an
xsl:template
element
has no effect when the template is invoked by an
xsl:apply-templates
instruction.
[ERR
XT0650] 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.
[ERR XT0660] It is a static error if a stylesheet contains more than one template with the same name and the same import precedence, unless it also contains a template with the same name and higher import precedence.
The target template
for an xsl:call-template
instruction is the template 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. The result of evaluating an xsl:call-template
instruction is the sequence produced by evaluating the sequence
constructor contained in its target template (see 5.6 Sequence Constructors).
<xsl:with-param
name = qname
select? = expression
as? = sequence-type
tunnel? = "yes" | "no">
<!-- Content: sequence-constructor
-->
</xsl:with-param>
Parameters are passed to templates using the xsl:with-param
element. The
required name
attribute
specifies the name of the template parameter (the variable the
value of whose binding is to be replaced). The value of the
name
attribute is a QName, which is expanded as described in 5.1 Qualified Names.
xsl:with-param
is
allowed within xsl:call-template
,
xsl:apply-templates
,
xsl:apply-imports
,
and xsl:next-match
.
[ERR
XT0670] It is a static error if a single xsl:call-template
,
xsl:apply-templates
,
xsl:apply-imports
,
or xsl:next-match
element contains two or more xsl:with-param
elements with
matching name
attributes.
The value of the parameter is specified in the same way as for
xsl:variable
and
xsl:param
(see 9.3 Values of Variables and
Parameters), taking account of the values of the
select
and as
attributes and the content
of the xsl:with-param
element, if
any.
Note:
It is possible to have an as
attribute on the
xsl:with-param
element that differs from the as
attribute on the
corresponding xsl:param
element describing the formal parameters of the called template.
In this situation, the computed value of the parameter will be
validated and/or converted twice, first according to the rules of
the as
attribute on the xsl:with-param
element,
and then according to the rules of the as
attribute
on the xsl:param
element.
The focus used for
computing the value specified by xsl:with-param
element is
the same as that used for the xsl:apply-templates
,
xsl:apply-imports
,
xsl:next-match
, or
xsl:call-template
element within which it occurs.
[ERR
XT0680] In the case of xsl:call-template
, it is
a static error
to pass a parameter named x to a template that does not
have a template parameter named x.
This is not an error in the case of xsl:apply-templates
,
xsl:apply-imports
,
and xsl:next-match
; in
these cases the parameter is simply ignored.
The optional tunnel
attribute may be used to
indicate that a parameter is a tunnel parameter. The default is
no
. Tunnel parameters are described in 10.1.2 Tunnel Parameters
[ERR
XT0690] It is a static error if a template that is invoked
using xsl:call-template
declares a template parameter specifying
required="yes"
and not specifying
tunnel="yes"
, if no value for this parameter is
supplied by the calling instruction.
[ERR
XT0700] In other cases, it is a non-recoverable dynamic error if the
template that is invoked declares a template parameter with
required="yes"
and no value for this parameter is
supplied by the calling instruction.
This example defines a named template for a
numbered-block
with an argument to control the
format of the number.
<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>
Note:
Arguments to stylesheet functions are supplied as part of an XPath function call: see 10.3 Stylesheet Functions
[Definition: A parameter passed to a template may be defined as a tunnel parameter. Tunnel parameters have the property that they are automatically passed on by the called template to any further templates that it calls, and so on recursively.] Tunnel parameters thus allow values to be set that are accessible during an entire phase of stylesheet processing, without the need for each template that is used during that phase to be aware of the parameter.
Note:
Tunnel parameters are conceptually similar to dynamically-scoped variables in some functional programming languages.
A tunnel
parameter is created by using an xsl:with-param
element that
specifies tunnel="yes"
. A template that requires
access to the value of a tunnel parameter must declare it using an
xsl:param
element that
also specifies tunnel="yes"
.
On any template call using an xsl:apply-templates
,
xsl:call-template
,
xsl:apply-imports
or xsl:next-match
instruction, a set of tunnel parameters is passed from the
calling template to the called template. This set consists of any
parameters explicitly created using <xsl:with-param
tunnel="yes">
, overlaid on a base set of tunnel
parameters. If the xsl:apply-templates
,
xsl:call-template
,
xsl:apply-imports
or xsl:next-match
instruction has an xsl:template
declaration as an
ancestor element in the stylesheet, then the base set consists of
the tunnel parameters that were passed to that template; otherwise
(for example, if the instruction is within a global variable
declaration, an attribute set declaration, or stylesheet
function), the base set is empty. If a parameter created using
<xsl:with-param tunnel="yes">
has the same
expanded-QName as a parameter in the base
set, then the parameter created using xsl:with-param
overrides the
parameter in the base set; otherwise, the parameter created using
xsl:with-param
is
added to the base set.
When a template accesses the value of a tunnel parameter
by declaring it with xsl:param tunnel="yes"
, this does
not remove the parameter from the base set of tunnel parameters
that is passed on to any templates called by this template.
Two sibling xsl:with-param
elements must
have distinct parameter names, even if one is a tunnel parameter
and the other is not. Equally, two sibling xsl:param
elements representing
template parameters must have distinct
parameter names, even if one is a tunnel parameter and the other is not.
However, the tunnel parameters that are implicitly passed in a
template call may have names that duplicate the names of non-tunnel
parameters that are explicitly passed on the same call.
Tunnel parameters are not passed in calls to stylesheet functions.
All other options of xsl:with-param
and xsl:param
are available with
tunnel
parameters just as with non-tunnel parameters. For example,
parameters may be declared as mandatory or optional, a default
value may be specified, and a required type may be specified. If
any conversion is required from the supplied value of a tunnel
parameter to the required type specified in xsl:param
, then the converted
value is used within the receiving template, but the value that is
passed on in any further template calls is the original supplied
value before conversion. Equally, any default value is local to the
template: specifying a default value for a tunnel parameter does
not change the set of tunnel parameters that is passed on in
further template calls.
The set of tunnel parameters that is passed to the initial template is empty.
Tunnel parameters are passed unchanged through a built-in template rule (see 6.6 Built-in Template Rules).
Suppose that the equations in a scientific paper are to be sequentially numbered, but that the format of the number depends on the context in which the equations appear. It is possible to reflect this using a rule of the form:
<xsl:template match="equation"> <xsl:param name="equation-format" select="'(1)'" tunnel="yes"/> <xsl:number level="any" format="{$format}"/> </xsl:template>
At any level of processing above this level, it is possible to determine how the equations will be numbered, for example:
<xsl:template match="appendix"> ... <xsl:apply-templates> <xsl:with-param name="equation-format" select="'[i]'" tunnel="yes"/> </xsl:apply-templates> ... </xsl:template>
The parameter value is passed transparently through all the
intermediate layers of template rules until it reaches the rule
with match="equation"
. The effect is similar to
using a global variable, except that the parameter can take
different values during different phases of the
transformation.
<!-- Category: declaration
-->
<xsl:attribute-set
name = qname
use-attribute-sets? = qnames>
<!-- Content: xsl:attribute* -->
</xsl:attribute-set>
[Definition: The xsl:attribute-set
element
defines a named attribute set: that is, a collection of
attribute definitions that can be used repeatedly on
different elements in the result tree.]
The required 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
instructions that
are evaluated to produce the attributes in the set.
The result of evaluating an attribute set is a sequence of attribute nodes. Evaluating the same attribute set more than once can produce different results, because although an attribute set does not have parameters, it may contain expressions or instructions whose value depends on the evaluation context.
Attribute
sets are used by specifying a use-attribute-sets
attribute on the xsl:element
or, xsl:copy
instruction, or by
specifying an xsl:use-attribute-sets
attribute on a
literal result element. An attribute set may be defined in terms of
other attribute sets by using the use-attribute-sets
attribute on the xsl:attribute-set
element
itself. The value of the [xsl:]use-attribute-sets
attribute is in each case 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 broadly
equivalent to adding xsl:attribute
instructions for
each of the attributes in each of the named attribute sets to the
beginning of the content of the instruction with the
[xsl:]use-attribute-sets
attribute, in the same order in
which the names of the attribute sets are specified in the
use-attribute-sets
attribute.
More formally, an xsl:use-attribute-sets
attribute is
expanded using the following recursive algorithm, or any algorithm
that produces the same results:
The value of the attribute is a tokenized as a list of QNames.
Each QName in the list is processed, in order, as follows:
The QName must match the name
attribute of
one or more xsl:attribute-set
declarations in the stylesheet.
Each xsl:attribute-set
declaration whose name matches is processed as follows. Where
two such declarations have different import
precedence, the one with lower import precedence is
processed first. Where two declarations have the same import
precedence, they are processed in declaration
order.
If the xsl:attribute-set
declaration has a use-attribute-sets
attribute, the attribute is expanded by applying this
algorithm recursively.
If the xsl:attribute-set
declaration contains one or more xsl:attribute
instructions, these instructions are evaluated (following
the rules for evaluating a sequence constructor: see
5.6 Sequence
Constructors) to produce a sequence of attribute
nodes. These attribute nodes are appended to the result
sequence.
The xsl:attribute
instructions are evaluated using the same focus as is used for evaluating the element that is
the parent of the [xsl:]use-attribute-sets
attribute
forming the initial input to the algorithm. However, the static
context for the evaluation depends on the position of the xsl:attribute
instruction in
the stylesheet: thus, only local variables declared within an
xsl:attribute
instruction, and global variables, are visible.
The set of attribute nodes produced by expanding an
xsl:use-attribute-sets
may include several attributes
with the same name. When the attributes are added to an element node,
only the last of the duplicates will take effect.
The way in which each instruction uses the results of expanding
the [xsl:]use-attribute-sets
attribute is described in
the specification for the relevant instruction: see 11.1 Literal Result Elements,
11.2 Creating Element Nodes using
xsl:element , and 11.8 Copying Nodes
from a Source Tree to a Result Tree.
[ERR
XT0710] It is a static error if the value of the
use-attribute-sets
attribute of an xsl:copy
, xsl:element
, or xsl:attribute-set
element,
or the xsl:use-attribute-sets
attribute of a literal
result element, is not a space-separated sequence of QNames, or if it contains a QName that
does not match the name
attribute of any xsl:attribute-set
declaration in the stylesheet.
[ERR
XT0720] It is a static error if an xsl:attribute-set
element
directly or indirectly references itself via the names contained in
the use-attribute-sets
attribute.
[ERR
XT0730] It is a recoverable dynamic error if the
expansion of two or more different xsl:attribute-set
declarations with the same name and the same import
precedence produce attribute nodes having the same name. The
optional recovery action is to
include both attribute nodes in the result. When the resulting set of
attribute nodes is added to an element node, only the last of the
duplicates will take effect.
Each attribute node produced by expanding an attribute set has a
type annotation determined by the rules for the xsl:attribute
instruction that
created the attribute node: see 11.3.1 Setting the Type
Annotation for a Constructed Attribute Node. These type
annotations may be preserved, stripped, or replaced as determined by
the rules for the instruction that creates the element in which the
attributes are used.
Attribute sets are used as follows:
The xsl:copy
and
xsl:element
instructions have an use-attribute-sets
attribute.
The sequence of attribute nodes produced by evaluating this
attribute is prepended to the sequence produced by evaluating the
sequence constructor contained
within the instruction.
Literal result elements allow an
xsl:use-attribute-sets
attribute, which is evaluated
in the same way as the use-attribute-sets
attribute
of xsl:element
and
xsl:copy
. The sequence
of attribute nodes produced by evaluating this attribute is
prepended to the sequence of attribute nodes produced by
evaluating the attributes of the literal result element, which in
turn is prepended to the sequence produced by evaluating the
sequence constructor contained
with the literal result element.
The following example creates a named attribute set title-style
and uses it in a template rule.
<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>
The following example creates a named attribute set
base-style
and uses it in a template rule with
multiple specifications of the attributes:
is specified only in the attribute set
is specified in the attribute set, is specified on the
literal result element, and in an xsl:attribute
instruction
is specified in the attribute set, and on the literal result element
is specified in the attribute set, and in an xsl:attribute
instruction
Stylesheet fragment:
<xsl:attribute-set name="base-style"> <xsl:attribute name="font-family">Univers</xsl:attribute> <xsl:attribute name="font-size">10pt</xsl:attribute> <xsl:attribute name="font-style">normal</xsl:attribute> <xsl:attribute name="font-weight">normal</xsl:attribute> </xsl:attribute-set> <xsl:template match="o"> <fo:block xsl:use-attribute-sets="base-style" font-size="12pt" font-style="italic"> <xsl:attribute name="font-size">14pt</xsl:attribute> <xsl:attribute name="font-weight">bold</xsl:attribute> <xsl:apply-templates/> </fo:block> </xsl:template>
Result:
<fo:block font-family="Univers" font-size="14pt" font-style="italic" font-weight="bold"> ... </fo:block>
[Definition: 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.]
<!-- Category: declaration
-->
<xsl:function
name = qname
as? = sequence-type
override? = "yes" | "no">
<!-- Content: (xsl:param*, sequence-constructor)
-->
</xsl:function>
The xsl:function
declaration defines a stylesheet function that can be called
from any XPath expression used in the stylesheet (including an XPath expression
used within a predicate in a pattern). The name
attribute specifies
the name of the function. The value of the name
attribute is a QName, which is
expanded as described in 5.1 Qualified
Names.
An xsl:function
declaration can only appear as a top-level element in a
stylesheet module.
[ERR XT0740] A stylesheet function must have a prefixed name, to remove any risk of a clash with a function in the default function namespace. It is a static error if the name has no prefix. The prefix must not refer to a reserved namespace.
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.
The content of the xsl:function
element consists of
zero or more xsl:param
elements that specify the formal arguments of the function, followed
by a sequence constructor that defines the
value to be returned by the function.
[Definition: The arity of a
stylesheet function is the number of xsl:param
elements in the function
definition.] Optional arguments are
not allowed.
[ERR
XT0760] Because arguments to a stylesheet function call
must all be specified, the xsl:param
elements within an
xsl:function
element
must not specify a default value: this
means they must be empty, and must not have a select
attribute.
A stylesheet function is included in the in-scope functions of the static context for all XPath expressions used in the stylesheet, unless
there is another stylesheet function with the same name and arity, and higher import precedence, or
the override
attribute has the value
no
and there is already a function with the same
name and arity in the
in-scope functions.
The optional override
attribute defines what happens
if this function has the same name and arity as a function provided by the
implementer or made available in the static context using an
implementation-defined mechanism. If the override
attribute has the value yes
, then this function is used
in preference; if it has the value no
, then the other
function is used in preference. The default value is
yes
.
Note:
Specifying override="yes"
ensures interoperable
behavior: the same code will execute with all processors.
Specifying override="no"
is useful when writing a
fallback implementation of a function that is available with some
processors but not others: it allows the vendor's implementation of
the function to be used in preference to the stylesheet
implementation, which is useful when the vendor's implementation is
more efficient.
[ERR XT0770] It is a static error for a stylesheet to contain two or more functions with the same expanded-QName, the same arity, and the same import precedence, unless there is another function with the same expanded-QName and arity, and a higher import precedence.
As defined in XPath, the function that is executed as the result
of a function call is identified by looking in the in-scope functions
of the static context for a function whose name and arity matches the name and number of arguments
in the function call. In an XSLT context, the error that occurs when
there is no matching function is a dynamic error: this is to allow the
stylesheet to execute conditional logic depending on whether or not a
function is available, which can be tested using the function-available
function.
Note:
Functions are not polymorphic. Although the XPath function call mechanism allows two functions to have the same name and different arity, it does not allow them to be distinguished by the types of their arguments.
The optional as
attribute indicates the required type of the
result of the function. The value of the as
attribute is
a SequenceType
XP, as defined in [XPath
2.0].
[ERR
XT0780] If the as
attribute is specified,
then the result evaluated by the sequence
constructor (see 5.6
Sequence Constructors) is converted to the required type,
using the function conversion rules. It is
a type error if this
conversion fails. If the as
attribute is omitted, the
calculated result is used as supplied, and no conversion takes
place.
If a stylesheet function has been defined
with a particular expanded-QName, then a call on function-available
will return true when called with an argument that is a QName that expands to this same
expanded-QName.
The xsl:param
elements
define the formal arguments to the function. These are interpreted
positionally. When the function is called using a function-call in an
XPath expression, the
first argument supplied is assigned to the first xsl:param
element, the second
argument supplied is assigned to the second xsl:param
element, and so on.
The as
attribute of the xsl:param
element defines the
required type of the parameter. The rules for converting the values
of the actual arguments supplied in the function call to the types
required by each xsl:param
element are defined in [XPath 2.0]. The
rules that apply are those for the case where XPath
1.0 compatibility mode is set to false
. If
the value cannot be converted to the required type, a type exception
is signaled. If the as
attribute is omitted, no
conversion takes place and any value is accepted.
[ERR XT0800] Within the body of a stylesheet function, the focus is initially undefined; this means that any attempt to reference the context item, context position, or context size is a non-recoverable dynamic error.
It is not possible within the body of the stylesheet function to access the values of local variables that were in scope in the place where the function call was written. Global variables, however, remain available.
The following example creates a stylesheet function named
str:reverse
that reverses the words in a supplied
sentence, and then invokes this function from within a template rule.
<xsl:transform xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:xs="http://www.w3.org/2001/XMLSchema" 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>
An alternative way of writing the same function is to implement the conditional logic at the XSLT level, thus:
<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>
The following example illustrates the use of the as
attribute in a function definition. It returns a string containing
the representation of its integer argument, expressed as a roman
numeral. For example, the function call num:roman(7)
will return the string "vii"
. This example uses the
xsl:number
instruction,
described in 12 Numbering. The
xsl:number
instruction
returns a text node, and the function conversion rules
are invoked to convert this text node to the type declared in the
xsl:function
element,
namely xs:string
. So the text node is atomized to a string.
<xsl:function name="num:roman" as="xs:string"> <xsl:param name="value" as="xs:integer"/> <xsl:number value="$value" format="i"/> </xsl:function>
This section describes instructions that directly create new nodes, or sequences of nodes and atomic values.
[Definition: 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 (see 5.6 Sequence Constructors). The sequence obtained by evaluating this sequence constructor, after prepending any attribute nodes produced as described in 11.1.2 Attribute Nodes for Literal Result Elements and namespace nodes produced as described in 11.1.3 Namespace Nodes for Literal Result Elements, is used to construct the content of the element, following the rules in 5.6.1 Constructing Complex Content
The attributes xsl:type
and
xsl:validation
may be used on a literal result element
to invoke validation of the contents of the element
against a type definition or element declaration in a
schema, and to determine the type annotation that the new
element node will carry. These attributes also affect the type
annotation carried by any elements and attributes that have the new
element node as an ancestor. These two attributes are both
optional, and if one is specified then the other must be omitted. The permitted values of these
attributes and their semantics are described in 19.2 Validation.
Attribute nodes for a literal result element may be created by
including xsl:attribute
instructions
within the sequence constructor. Additionally,
attribute nodes are created corresponding to the attributes of the
literal result element in the stylesheet, and as a result of
expanding the xsl:use-attribute-sets
attribute of the
literal result element, if present.
The sequence that is used to construct the content of the literal result element (as described in 5.6.1 Constructing Complex Content is the concatenation of the following four sequences, in order:
The sequence of namespace nodes produced as described in 11.1.3 Namespace Nodes for Literal Result Elements.
The sequence of attribute nodes produced by expanding the
xsl:use-attribute-sets
attribute (if present)
following the rules given in 10.2
Named Attribute Sets
The attributes produced by processing the attributes of the literal result element itself, other than attributes in the XSLT namespace. The way these are processed is described below.
The sequence produced by evaluating the contained sequence constructor, if the element is not empty.
Note:
The significance of this order is that an attribute produced
by an xsl:attribute
instruction in the content of
the literal result element takes precedence over an attribute
produced by expanding an attribute of the literal result element
itself, which in turn takes precedence over an attribute produced
by expanding the xsl:use-attribute-sets
attribute.
This is because of the rules in 5.6.1 Constructing Complex
Content, which specify that when two or more attributes
in the sequence have the same name, all but the last of the
duplicates are discarded.
In practice, it makes no difference whether the namespace nodes come before or after the attributes.
Each attribute of the literal result element, other than an attribute in the XSLT namespace, is processed to produce an attribute for the element in the result tree.
The value of such an attribute is interpreted as an attribute value template: it can
therefore contain expressions contained in curly brackets
({}
). The new attribute node will have the same name
as the attribute in the stylesheet tree, and its string value will be the
same as the effective value of the attribute in the
stylesheet tree. The type annotation on the attribute will
initially be xdt:untypedAtomic
, and the typed value of the
attribute node will be the same as its string value.
Note:
The eventual type annotation of the attribute in the result
tree depends on the xsl:validation
and
xsl:type
attributes of the parent literal result
element, and on the instructions used to create its ancestor
elements. If the xsl:validation
attribute is set to
preserve
or strip
, the type annotation
will be xdt:untypedAtomic
, and the typed value of the
attribute node will be the same as its string value. If the
xsl:validation
attribute is set to
strict
or lax
, or if the
xsl:type
attribute is used, the type annotation on
the attribute will be set as a result of the schema validation
process applied to the parent element. If neither attribute is
present, the type annotation on the attribute will be
xdt:untypedAtomic
.
Note:
The xml:base
, xml:lang
and
xml:space
attributes have two effects in XSLT. They
behave as standard XSLT attributes, which means for example that
if they appear on a literal result element, they will be copied
to the result tree in the same way as any other attribute. In
addition, they have their standard meaning as defined in the core
XML specifications. Thus, an xml:base
attribute in
the stylesheet affects the base URI of the element on which it
appears, and an xml:space
attribute affects the
interpretation of whitespace text nodes within that
element. One consequence of this is that these attributes
should not be written as attribute
value templates: although an XSLT processor will understand this
notation, the XML parser will not.
The same is true of the schema-defined attributes
xsi:type
, xsi:nil
, and
xsi:schemaLocation
. If the stylesheet is processed
by a schema processor, these attributes will be recognized and
interpreted by the schema processor, but they have no special
meaning to the XSLT processor. The attributes are copied to the
result tree in the same way as any other attribute. If the result
tree is validated, the copied attributes will again be recognized
and interpreted by the schema processor.
None of these attributes will be generated in the result tree unless the stylesheet writes them to the result tree explicitly, in the same way as any other attribute.
[ERR XT0805] It is a static error if an attribute on a literal result element is in the XSLT namespace, unless it is one of the attributes explicitly defined in this specification.
The created element node will also have a copy of the namespace nodes that were present on the element node in the stylesheet tree with the exception of any namespace node whose string value is designated as an excluded namespace. Special considerations apply to aliased namespaces: see 11.1.4 Namespace Aliasing
The following namespaces are designated as excluded namespaces:
The XSLT
namespace URI
(http://www.w3.org/1999/XSL/Transform
)
A namespace URI declared as an extension namespace (see 18.2 Extension Instructions)
A namespace URI designated by using an
[xsl:]exclude-result-prefixes
attribute either on
the literal result element itself or on an ancestor element.
The attribute must be in the XSLT
namespace only if its parent element is not in the
XSLT namespace.
The value of the attribute is either
#all
, or a whitespace-separated list of tokens,
each of which is either a namespace prefix or
#default
. The namespace bound to each of
the prefixes is designated as an excluded namespace. It is a
static
error if there is no namespace bound to the prefix on the
element bearing the [xsl:]exclude-result-prefixes
attribute.
The default namespace (as declared by xmlns
)
may be designated as an excluded namespace by including
#default
in the list of namespace prefixes.
The value #all
indicates that all namespaces
that are in scope for the stylesheet element that is the
parent of the [xsl:]exclude-result-prefixes
attribute are designated as excluded namespaces.
The designation of a namespace as an excluded namespace is
effective within the subtree of the stylesheet
module rooted at the element bearing the
[xsl:]exclude-result-prefixes
attribute; a subtree
rooted at an xsl:stylesheet
element
does not include any stylesheet modules imported or included by
children of that xsl:stylesheet
element.
The excluded namespaces, as described above, only
affect namespace nodes copied from the stylesheet when processing a
literal result element. There is no guarantee that an excluded
namespace will not appear on the result tree for some other reason.
Namespace nodes are also written to the result tree as part of the
process of namespace fixup (see 5.6.3
Namespace Fixup), or as the result of instructions such as
xsl:copy
and xsl:element
.
Note:
When a stylesheet uses a namespace declaration only for the
purposes of addressing the source tree, specifying the prefix in
the [xsl:]exclude-result-prefixes
attribute will
avoid superfluous namespace declarations in the result tree. The
attribute is also useful to prevent namespaces used solely for
the naming of stylesheet functions or extension functions from
appearing in the result tree.
For example, consider the following stylesheet:
<xsl:stylesheet xsl:version=1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:a="a.uri" xmlns:b="b.uri"> exclude-result-prefixes="#all"> <xsl:template match="/"> <foo xmlns:c="c.uri" xmlns:d="d.uri" xmlns:a2="a.uri" xsl:exclude-result-prefixes="c"/> </xsl:template> </xsl:stylesheet>
The result of this stylesheet will be:
<foo xmlns:d="d.uri"/>
The namespaces a.uri
and b.uri
are
excluded by virtue of the exclude-result-prefixes
attribute on the xsl:stylesheet
element,
and the namespace c.uri
is excluded by virtue of the
xsl:exclude-result-prefixes
attribute on the
foo
element. The setting #all
does not
affect the namespace d.uri
because
d.uri
is not an in-scope namespace for the xsl:stylesheet
element.
The element in the result tree does not have a namespace node
corresponding to xmlns:a2="a.uri"
because the effect
of exclude-result-prefixes
is to designate the
namespace URI a.uri
as an excluded namespace,
irrespective of how many prefixes are bound to this namespace
URI.
If the stylesheet is changed so that the literal result
element has an attribute b:bar="3"
, then the element
in the result tree will typically have a namespace declaration
xmlns:b="b.uri"
, although the processor is free to
choose a different namespace prefix if it wishes. The
exclude-result-prefixes
attribute makes
b.uri
an excluded namespace, so the namespace node
is not automatically copied from the stylesheet, but the presence
of an attribute whose name is in the namespace b.uri
forces the namespace fixup process (see 5.6.3 Namespace Fixup) to introduce
a namespace node for this namespace.
When a stylesheet is used to define a transformation whose output is itself a stylesheet module, or in certain other cases where the result document uses namespaces that it would be inconvenient to use in the stylesheet, namespace aliasing can be used to declare a mapping between a namespace URI used in the stylesheet and the corresponding namespace URI to be used in the result document.
[Definition: A namespace URI in the stylesheet tree that is being used to specify a namespace URI in the result tree is called a literal namespace URI.]
[Definition: The namespace URI that is to be used in the result tree as a substitute for a literal namespace URI is called the target namespace URI.]
<!-- Category: declaration
-->
<xsl:namespace-alias
stylesheet-prefix = prefix |
"#default"
result-prefix = prefix |
"#default" />
[Definition: A stylesheet can use the
xsl:namespace-alias
element to declare that a literal namespace URI is being used
as an alias for a target namespace URI.]
The effect is that when names in the namespace identified by the literal namespace URI are copied to the result tree, the namespace URI in the result tree will be the target namespace URI, instead of the literal namespace URI. This applies to:
the namespace URI in the expanded-QName of a literal result element in the stylesheet
the namespace URI in the expanded-QName of an attribute specified on a literal result element in the stylesheet
The xsl:namespace-alias
element declares that the namespace URI bound to the prefix
specified by the stylesheet-prefix
is the literal
namespace URI, and the namespace URI bound to the prefix
specified by the result-prefix
attribute is the
target namespace URI. Thus, the
stylesheet-prefix
attribute specifies the namespace
URI that will appear in the stylesheet, and the
result-prefix
attribute specifies the corresponding
namespace URI that will appear in the result tree.
The default namespace (as declared by xmlns
) may be
specified by using #default
instead of a prefix.
If a namespace URI is declared to be an alias for multiple different namespace URIs, then the declaration with the highest import precedence is used.
[ERR
XT0810] It is a static error if there is more than
one such declaration with the same literal namespace URI and the
same import precedence and different values
for the target namespace URI, unless
there is also an xsl:namespace-alias
declaration with the same literal namespace URI and a higher
import precedence.
[ERR
XT0815] It is a static error if the value
#default
is specified for either the
stylesheet-prefix
or the result-prefix
attributes of the xsl:namespace-alias
element when there is no default namespace.
Note:
See resolution of issue 187. This situation was left unclear in XSLT 1.0.
When a literal result element is processed, its namespace nodes are handled as follows:
A namespace node whose string value is a literal namespace URI is not copied to the result tree.
A namespace node whose string value is a target namespace URI is copied to the result tree, whether or not the URI identifies an excluded namespace.
In the event that the same URI is used as a literal namespace URI and a target namespace URI, the second of these rules takes precedence.
Note:
These rules achieve the effect that the element generated from
the literal result element will have an in-scope namespace node
that binds the result-prefix
to the target
namespace URI, provided that the namespace declaration
associating this prefix with this URI is in scope for both the
xsl:namespace-alias
instruction and for the literal result element. Conversely, the
stylesheet-prefix
and the literal
namespace URI will not normally appear in the result tree.
The processor still has a free choice of prefixes when generating
element and attribute names in the result tree, but it will
normally use the result-prefix
since that prefix
will already be declared in the result tree.
xsl:namespace-alias
to Generate a
Stylesheet
When literal result elements are being used to create element, attribute, or namespace nodes that use the XSLT namespace URI, the stylesheet may use an alias.
For example, the stylesheet
<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="2.0"> <xsl:apply-templates/> </axsl:stylesheet> </xsl:template> <xsl:template match="elements"> <axsl:template match="/"> <axsl:comment select="system-property('xsl:version')"/> <axsl:apply-templates/> </axsl:template> </xsl:template> <xsl:template match="block"> <axsl:template match="{.}"> <fo:block><axsl:apply-templates/></fo:block> </axsl:template> </xsl:template> </xsl:stylesheet>
will generate an XSLT stylesheet from a document of the form:
<elements> <block>p</block> <block>h1</block> <block>h2</block> <block>h3</block> <block>h4</block> </elements>
The output of the transformation will be a stylesheet such as
the following. Whitespace has been added for clarity. Note that
an implementation may output different namespace prefixes from
those appearing in this example; however, the rules
guarantee that there will be a namespace node that binds the
prefix xsl
to the URI
http://www.w3.org/1999/XSL/Transform
, which makes it
safe to use the QName xsl:version
in the content of
the generated stylesheet.
<xsl:stylesheet version="2.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:fo="http://www.w3.org/1999/XSL/Format"> <xsl:template match="/"> <xsl:comment select="system-property('xsl:version')"/> <xsl:apply-templates/> </xsl:template> <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>
Note:
It may be necessary also to use aliases for namespaces other
than the XSLT namespace URI. For example, it can be useful
to define an alias for the namespace
http://www.w3.org/2001/XMLSchema-instance
, so that
the stylesheet can use the attributes xsi:type
,
xsi:nil
, and xsi:schemaLocation
on a
literal result element, without running the risk that a schema
processor will interpret these as applying to the stylesheet
itself. Equally, literal result elements belonging to a
namespace dealing with digital signatures might cause XSLT
stylesheets to be mishandled by general-purpose security
software; using an alias for the namespace would avoid the
possibility of such mishandling.
It is not possible to define an alias for the XML namespace
http://www.w3.org/XML/1998/namespace
because there
is a specific provision in [XML Namespaces
1.0] (see erratum NE05) that disallows the use of this
namespace URI with any prefix other than xml
.
xsl:element
<!-- Category: instruction
-->
<xsl:element
name = { qname }
namespace? = { uri-reference }
use-attribute-sets? = qnames
type? = qname
validation? = "strict" | "lax" | "preserve" |
"strip">
<!-- 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 (see 5.6 Sequence Constructors) is
used to construct the content of the element, as described in
5.6.1 Constructing Complex
Content.
The xsl:element
element may have a use-attribute-sets
attribute, whose
value is a space-separated list of QNames that identify xsl:attribute-set
declarations. If this attribute is present, it is expanded as
described in 10.2 Named Attribute
Sets to produce a sequence of attribute nodes. This sequence
is prepended to the sequence produced as a result of evaluating the
sequence constructor, 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,
whose effective
value must be a lexical
QName.
[ERR
XT0820] It is a recoverable dynamic error if the
effective
value of the name
attribute is not a lexical QName. The
optional recovery action is to
return the sequence of nodes created by evaluating the
sequence constructor, excluding any
initial attribute and namespace nodes.
[ERR
XT0830] In the case of an xsl:element
instruction with no
namespace
attribute, it is a recoverable 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.
The optional recovery action is to
ignore the prefix part of the lexical QName, with the effect
that the new element will be in the default namespace.
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 lexical 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 lexical QName specified in the
name
attribute when selecting a prefix during the
namespace fixup process (see 5.6.3
Namespace Fixup); however, they are not required to do so.
The optional attributes type
and
validation
may be used on the xsl:element
instruction to
invoke validation of the contents of the element
against a type definition or element declaration in a
schema, and to determine the type annotation that the new
element node will carry. These attributes also affect the type
annotation carried by any elements and attributes that have the new
element node as an ancestor. These two attributes are both
optional, and if one is specified then the other must be omitted. The permitted values of these
attributes and their semantics are described in
19.2 Validation.
Note:
The final type annotation of the element in the result tree
also depends on the type
and validation
attributes of the instructions used to create the ancestors of
the element.
xsl:attribute
<!-- Category: instruction
-->
<xsl:attribute
name = { qname }
namespace? = { uri-reference }
select? = expression
separator? = { string }
type? = qname
validation? = "strict" | "lax" | "preserve" |
"strip">
<!-- 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. Except in error cases,
the result of evaluating an xsl:attribute
instruction is
the newly constructed attribute node.
The string value of the new attribute node may be defined either
by using the select
attribute, or by the sequence
constructor that forms the content of the xsl:attribute
element. These
are mutually exclusive. If neither is present, the value of the new
attribute node will be a zero-length string. The way in which the
value is constructed is specified in 5.6.2 Constructing Simple
Content.
[ERR
XT0840] It is a static error if the select
attribute of the xsl:attribute
element is
present unless the element has empty content.
If the separator
attribute is present, then the
effective
value of this attribute is used to separate adjacent items in the
result sequence, as described in 5.6.2 Constructing Simple
Content. In the absence of this attribute, the default
separator is a single space (#x20) when the content is specified
using the select
attribute, or a zero-length string when
the content is specified using a sequence constructor.
The name
attribute is interpreted as an attribute value template,
whose effective
value must be a lexical
QName.
[ERR
XT0850] It is a recoverable dynamic error if the
effective
value of the name
attribute is not a lexical QName or is the
string xmlns
. The optional recovery action is to
return the empty sequence.
[ERR
XT0860] In the case of an xsl:attribute
instruction with
no namespace
attribute, it is a recoverable dynamic
error if the effective value of the name
attribute is a lexical QName whose prefix is not declared in
an in-scope namespace declaration for the xsl:attribute
instruction. The
optional recovery action is to
ignore the prefix part of the QName.
If the namespace
attribute is not present, then the
lexical 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 lexical QName specified by the
name
attribute is used as the local part of the
expanded-QName of the attribute to be
created.
The following instruction creates the attribute
colors="red green blue"
:
<xsl:attribute name="colors" select="'red', 'green', 'blue'"/>
Implementations may make use of the
prefix of the lexical QName specified in the
name
attribute when selecting a prefix during the
namespace fixup process (see 5.6.3
Namespace Fixup).
It is not an error to write:
<xsl:attribute name="xmlns:xsl" namespace="file://some.namespace">http://www.w3.org/1999/XSL/Transform</xsl:attribute>
However, this will not result in the namespace declaration
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
being
output. Instead, it will produce an attribute node with local name
xsl
, and with a system-allocated namespace prefix
mapped to the namespace URI file://some.namespace
.
This is because the namespace fixup process is not allowed to use
xmlns
as the name of a namespace node.
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.
Note:
If a collection of attributes is generated repeatedly, this can be done conveniently by using named attribute sets: see 10.2 Named Attribute Sets
The optional attributes type
and
validation
may be used on the xsl:attribute
instruction to
invoke validation of the contents of the attribute
against a type definition or attribute declaration in a
schema, and to determine the type annotation that the new
attribute node will carry. These two attributes are both optional,
and if one is specified then the other must be omitted. The permitted values of these
attributes and their semantics are described in
19.2 Validation.
Note:
The final type annotation of the attribute in the result tree
also depends on the type
and validation
attributes of the instructions used to create the ancestors of
the attribute.
A sequence constructor can contain text nodes. Each text node in a sequence constructor remaining after whitespace text nodes have been stripped as specified in 4.3 Stripping Whitespace from a Source Tree will construct a new text node with the same string value. The resulting text node is added to the result of the containing sequence constructor. When the resulting content is added to a result tree, adjacent text nodes in the result tree are merged.
Text is processed at the tree level. Thus, markup of
<
in a template will be represented in the
stylesheet tree by a text node that includes the character
<
. This will create a text node in the result tree
that contains a <
character, which will be
represented by the markup <
(or an equivalent
character reference) when the result tree is serialized as an XML
document, unless otherwise specified using character maps (see
20.1 Character Maps) or
disable-output-escaping
(see 20.2 Disabling Output
Escaping).
xsl:text
<!-- Category: instruction -->
<xsl:text
disable-output-escaping? = "yes" | "no">
<!-- Content: #PCDATA -->
</xsl:text>
The xsl:text
element is
evaluated to contruct a new text node. The content of the xsl:text
element is a single text
node whose value forms the string value of the new text
node. An xsl:text
element
may also be empty, in which case the result of evaluating the
instruction is an empty sequence.
The result of evaluating an xsl:text
instruction is either a
single node, the newly constructed text node, or an empty
sequence.
A text node that is an immediate child of an xsl:text
instruction will not be
stripped from the stylesheet tree, even if it consists entirely of
whitespace (see 4.3 Stripping Whitespace from a
Source Tree).
For the effect of the deprecated
disable-output-escaping
attribute, see 20.2 Disabling Output
Escaping
Note:
It is not always necessary to use the xsl:text
instruction to write
text nodes to the result tree. Literal text can be written to the
result tree by including it anywhere in a sequence
constructor, while computed text can be output using the
xsl:value-of
instruction. The principal reason for using xsl:text
is that it offers
improved control over whitespace handling.
xsl:value-of
Within a sequence constructor, the xsl:value-of
instruction can
be used to compute generated text, for example by extracting text
from the source tree or by inserting the value of a variable. The
xsl:value-of
instruction computes this text using an expression that is specified as the value of
the select
attribute.
<!-- Category: instruction
-->
<xsl:value-of
select? = expression
separator? = { string }
disable-output-escaping? = "yes" | "no">
<!-- Content: sequence-constructor
-->
</xsl:value-of>
The xsl:value-of
instruction is evaluated to construct a new text node; the result
of the instruction is the newly constructed text node. But if the
rules below produce a text node whose string value is the
zero-length string, the result of the instruction is an empty
sequence.
The string value of the new text node may be defined either by
using the select
attribute, or by the sequence
constructor (see 5.6
Sequence Constructors) that forms the content of the
xsl:value-of
element.
These are mutually exclusive, and one of them must be present. The
way in which the value is constructed is specified in 5.6.2 Constructing Simple
Content.
[ERR
XT0870] It is a static error if the select
attribute of the xsl:value-of
element is
present when the content of the element is non-empty, or if the
select
attribute is absent when the content is
empty.
If the separator
attribute is present, then the
effective
value of this attribute is used to separate adjacent items in
the result sequence, as described in 5.6.2 Constructing Simple
Content. In the absence of this attribute, the default
separator is a single space (#x20) when the content is specified
using the select
attribute, or a zero-length string
when the content is specified using a sequence
constructor.
Special rules apply when backwards compatible
behavior is enabled for the instruction. If no
separator
attribute is present, and if the
select
attribute is present, then all items in the
atomized result
sequence other than the first are ignored.
For example, the instruction:
<x><xsl:value-of select="1 to 4" separator="|"/></x>
produces the output:
<x>1|2|3|4</x>
Note:
The xsl:copy-of
element can be used to copy a sequence of nodes to the result
tree without atomization. See 11.8.2 Deep Copy.
For the effect of the deprecated
disable-output-escaping
attribute, see 20.2 Disabling Output
Escaping
<!-- Category:
instruction -->
<xsl:processing-instruction
name = { ncname }
select? = expression>
<!-- Content: sequence-constructor
-->
</xsl:processing-instruction>
The xsl:processing-instruction
element is evaluated to create a processing instruction node.
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.
The string value of the new processing-instruction node may be
defined either by using the select
attribute, or by the
sequence constructor that forms the
content of the xsl:processing-instruction
element. These are mutually exclusive. If neither is present, the
string value of the new processing-instruction node will be a
zero-length string. The way in which the value is constructed is
specified in 5.6.2
Constructing Simple Content.
[ERR
XT0880] It is a static error if the select
attribute of the xsl:processing-instruction
element is present unless the element has empty content.
Except in error situations, the result of evaluating the xsl:processing-instruction
instruction is a single node, the newly constructed processing
instruction node.
This instruction:
<xsl:processing-instruction name="xml-stylesheet"> select="('href="book.css"', 'type="text/css")"/>
creates the processing instruction
<?xml-stylesheet href="book.css" type="text/css"?>
Note that the xml-stylesheet
processing instruction
contains pseudo-attributes in the form
name="value"
. Although these have the same textual
form as attributes in an element start tag, they are not
represented as attribute nodes in the data model, and cannot
therefore be constructed using xsl:attribute
instructions.
[ERR
XT0890] It is a recoverable dynamic error if the
effective
value of the name
attribute is not both an NCName
Names and a PITarget
XML. The optional recovery action is
to return the 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).
[ERR
XT0900] It is a recoverable dynamic error if the result
of evaluating the content of the xsl:processing-instruction
contains the string ?>
. The optional recovery action is to
insert a space after any occurrence of ?
that is
followed by a >
<!-- Category: instruction
-->
<xsl:namespace
name = { ncname }
select? = expression>
<!-- Content: sequence-constructor
-->
</xsl:namespace>
The xsl:namespace
element is evaluated to create a namespace node. Except in error
situations, the result of evaluating the xsl:namespace
instruction is a
single node, the newly constructed namespace node.
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
effective
value of the name
attribute is a zero-length
string, a namespace node is added for the default namespace.
The string value of the new namespace node (that is, the namespace
URI) may be defined either by using the select
attribute, or by the sequence constructor that forms the
content of the xsl:namespace
element. These
are mutually exclusive. Since the string value of a namespace node
cannot be a zero-length string, one of them must be present. The way
in which the value is constructed is specified in 5.6.2 Constructing Simple
Content.
[ERR
XT0910] It is a static error if the select
attribute of the xsl:namespace
element is
present when the element has content other than one or more
xsl:fallback
instructions, or if the select
attribute is
absent when the element has empty content.
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.
This literal result element:
<data xsi:type="xs:integer" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <xsl:namespace name="xs" select="http://www.w3.org/2001/XMLSchema"/> <xsl:text>42</xsl:text> </data>
would typically cause the output document to contain the element:
<data xsi:type="xs:integer" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">42</data>
In this case, the element is constructed using a literal result
element, and the namespace
xmlns:xs="http://www.w3.org/2001/XMLSchema"
could
therefore have been added to the result tree simply by declaring it
as one of the in-scope namespaces in the stylesheet. In practice,
the xsl:namespace
instruction is more likely to be useful in situations where the
element is constructed using an xsl:element
instruction, which
does not copy all the in-scope namespaces from the stylesheet.
[ERR
XT0920] It is a recoverable dynamic error if the
effective
value of the name
attribute is neither a zero-length
string nor an NCName
Names, or if it is xml
or
xmlns
. The optional recovery action is
to return the empty sequence.
[ERR
XT0930] It is a recoverable dynamic error if evaluating
the select
attribute or the contained sequence
constructor of an xsl:namespace
instruction results in a zero-length string. The optional recovery action is to
return the 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 does, 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.
Given the instruction:
<p:item xmlns:p="p.uri"><xsl:namespace name="p">q.uri</xsl:namespace></p:item>
a possible serialization of the result tree is:
<ns0:item xmlns:ns0="p.uri" xmlns:p="q.uri"/>
The processor must invent a namespace prefix for the URI
p.uri
; it cannot use the prefix p
because
that prefix has been explicitly associated with a different
URI.
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 in [XML Namespaces 1.1]). Namespace undeclarations
are generated automatically by the serializer if
undeclare-namespaces="yes"
is specified on xsl:output
, whenever a
parent element has a namespace node for the default namespace
prefix, and a child element has no namespace node for that
prefix.
<!-- Category: instruction
-->
<xsl:comment
select? = expression>
<!-- Content: sequence-constructor
-->
</xsl:comment>
The xsl:comment
element is evaluated to contruct a new comment node. Except in error
cases, the result of evaluating the xsl:comment
instruction is a
single node, the newly constructed comment node.
The string value of the new comment node may be defined either by
using the select
attribute, or by the sequence
constructor that forms the content of the xsl:comment
element. These are
mutually exclusive. If neither is present, the value of the new
comment node will be a zero-length string. The way in which the value
is constructed is specified in 5.6.2 Constructing Simple
Content.
[ERR
XT0940] It is a static error if the select
attribute of the xsl:comment
element is present
unless the element has empty content.
For example, this
<xsl:comment>This file is automatically generated. Do not edit!</xsl:comment>
would create the comment
<!--This file is automatically generated. Do not edit!-->
[ERR
XT0950] It is a recoverable dynamic error if the result
of evaluating the content of the xsl:comment
contains the string
--
or ends with -
. The optional recovery action is to
insert a space after any occurrence of -
that is
followed by another -
or that ends the comment.
<!-- Category: instruction -->
<xsl:copy
copy-namespaces? = "yes" | "no"
use-attribute-sets? = qnames
type? = qname
validation? = "strict" | "lax" | "preserve" |
"strip">
<!-- Content: sequence-constructor
-->
</xsl:copy>
The xsl:copy
instruction provides a way of copying the context item. If the
context item is
a node, evaluating the xsl:copy
instruction constructs a
copy of the context node, and the result of the xsl:copy
instruction is this newly
constructed node. By default, the namespace nodes of
the context node are automatically copied as well, but the
attributes and children of the node are not automatically
copied.
When the context
item is an atomic value, the xsl:copy
instruction returns this
value. The sequence constructor, if present, is
not evaluated.
When the context
item is an attribute node, text node, comment node, processing
instruction node, or namespace node, the xsl:copy
instruction returns a new
node that is a copy of the context node. The new node will have the
same node kind, name, and string value as the context node. The
sequence constructor, if present, is
not evaluated.
When the context item is a document node or element node,
the xsl:copy
instruction
returns a new node that has the same node kind and name as the
context node. The content of the new node is formed by evaluating
the sequence constructor contained in
the xsl:copy
instruction. The sequence obtained by evaluating this
sequence constructor is used (after prepending any attribute nodes
or namespace nodes as described in the following paragraphs) to
construct the content of the document or element node, as described
in 5.6.1 Constructing
Complex Content.
The identity transformation can be written using xsl:copy
as follows:
<xsl:template match="@*|node()"> <xsl:copy> <xsl:apply-templates select="@*|node()"/> </xsl:copy> </xsl:template>
This template rule can be used to copy any node in a tree by
applying template rules to its attributes and children. It can be
combined with additional template rules that modify selected
nodes, for example if all nodes are to be copied except
note
elements and their contents, this can be
achieved by using the identity template rule together with the
template rule:
<xsl:template match="note"/>
Note:
The xsl:copy
instruction is most useful when copying element nodes. In other
cases, the xsl:copy-of
instruction is
more flexible, because it has a select
attribute
allowing selection of the nodes or values to be copied.
The xsl:copy
instruction has an optional use-attribute-sets
attribute, whose value is a space-separated list of QNames that
identify xsl:attribute-set
declarations. This attribute is used only when copying element
nodes. This list is expanded as described in 10.2 Named Attribute Sets to produce a
sequence of attribute nodes. This sequence is prepended to the
sequence produced as a result of evaluating the sequence
constructor.
The xsl:copy
instruction has an optional copy-namespaces
attribute,
with the value yes
or no
. The default
value is yes
. The attribute is used only when copying
element nodes. If the value is set to yes
, or is
omitted, then all the namespace nodes of the source element are
copied as namespace nodes for the result element. These
copied namespace nodes are prepended to the sequence produced as a
result of evaluating the sequence constructor (it is
immaterial whether they come before or after any attribute nodes
produced by expanding the use-attribute-sets
attribute). If the value is set to no
, then the
namespace nodes are not copied. However, namespace nodes will still
be added to the result element as required by the namespace fixup process: see 5.6.3 Namespace Fixup.
Note:
Note that when attribute nodes are copied, whether with
xsl:copy
or with
xsl:copy-of
, the
processor does not automatically copy any associated namespace
information. The namespace used in the attribute name itself will
be declared by virtue of the namespace fixup process (see
5.6.3 Namespace Fixup) when
the attribute is added to an element in the result tree, but if
namespaces are used in the content of the attribute (for example,
if the value of the attribute is an XPath expression) then it is
the responsibility of the stylesheet author to ensure that
suitable namespace declarations are added to the result tree.
This can be achieved by copying the namespace nodes using
xsl:copy
, or by
generating them using xsl:namespace
.
The optional attributes type
and
validation
may be used on the xsl:copy
instruction to
validate the contents of an element, attribute or
document node against a type definition, element declaration, or
attribute declaration in a schema, and thus to determine the type
annotation that the new copy of an element or attribute node will
carry. These attributes are ignored when copying an item that is
not an element, attribute or document node. When
the node being copied is an element or document node, these
attributes also affect the type annotation carried by any elements
and attributes that have the copied element or document node as an
ancestor. These two attributes are both optional, and if one
is specified then the other must be
omitted. The permitted values of these attributes and their
semantics are described in 19.2 Validation.
Note:
The final type annotation of the node in the result tree also
depends on the type
and validation
attributes of the instructions used to create the ancestors of
the node.
The base URI of a node is copied. However, if the copied node is
subsequently attached as a child to a new element, the final copy
of the node inherits its base URI from its parent node, unless this
is overridden using an xml:base
attribute.
<!-- Category: instruction
-->
<xsl:copy-of
select = expression
copy-namespaces? = "yes" | "no"
type? = qname
validation? = "strict" | "lax" | "preserve" |
"strip" />
The xsl:copy-of
instruction can be used to construct a copy of a sequence of nodes
and/or atomic values, with each new node containing
copies of all the children, attributes, and (by default) namespaces
of the original node, recursively. The result of evaluating the
instruction is a sequence of items corresponding
one-to-one with the supplied sequence, and retaining its order.
The required select
attribute contains an expression, whose value may be any
sequence of nodes and atomic values. The items in this
sequence are processed as follows:
If the item is an element node, a new element is constructed and appended to the result sequence. The new element will have the same expanded-QName as the original, and it will have deep copies of the attribute nodes and children of the element node.
The new element will also have namespace nodes copied from
the original element node, unless they are excluded by
specifying copy-namespaces="no"
. If this
attribute is omitted, or takes the value yes
, then
all the namespace nodes of the original element are copied to
the new element. If it takes the value no
, then
none of the namespace nodes are copied: however, namespace
nodes will still be created in the result tree as required by the namespace fixup process: see
5.6.3 Namespace Fixup.
This attribute affects all elements copied by this instruction:
both elements selected directly by the select
expression, and
elements that are descendants of nodes selected by the
select
expression.
If the item is a document node, the instruction adds a new document node to the result sequence; the children of this document node will be one-to-one copies of the children of the original document node (each copied according to the rules for its own node kind).
If the item is an attribute or namespace node, or a text
node, a comment, or a processing instruction, the same rules
apply as with xsl:copy
(see 11.8.1 Shallow
Copy).
If the item is an atomic value, the value is appended to the
result sequence, as with xsl:sequence
.
The optional attributes type
and
validation
may be used on the xsl:copy-of
instruction to
validate the contents of an element, attribute or document
node against a type definition, element declaration, or attribute
declaration in a schema and thus to determine the type
annotation that the new copy of an element or attribute node will
carry. These attributes are applied individually to each element,
attribute, and document node that is selected by the
expression in the select
attribute. These
attributes are ignored when copying an item that is not an element,
attribute or document node.
The specified type
and
validation
apply directly only to elements,
attributes and document nodes created as copies of nodes actually
selected by the select
expression, they do not apply
to nodes that are implicitly copied because they have selected
nodes as an ancestor. However, these attributes do indirectly
affect the type annotation carried by such implicitly copied nodes,
as a consequence of the validation process.
These two attributes are both optional, and if one is specified then the other must be omitted. The permitted values of these attributes and their semantics are described in 19.2 Validation.
[ERR
XT0955] It is a static error to specify
copy-namespaces="no"
in conjunction with the explicit
or implicit value validation="preserve"
.
Note:
This is because failing to copy the namespace nodes may cause QName values in the content of an element to become invalid.
The base URI of a node is copied. However, if the copied node is
subsequently attached as a child to a new element, the final copy
of the node inherits its base URI from its parent node, unless this
is overridden using an xml:base
attribute.
<!-- 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. Unlike most other
instructions, xsl:sequence
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 (but not
both).
[ERR
XT0960] It is a static error if an xsl:sequence
instruction with a
select
attribute has any content other than xsl:fallback
instructions.
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 function conversion rules.
[ERR XT0970] If the computed value cannot be converted to the required type, a type error occurs.
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.
For example, the following code:
<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)"/>
produces the output: 37
xsl:for-each
to Construct a Sequence
The following code constructs a sequence containing the value of
the @price
attribute for selected elements (which we
assume to be typed as xs:decimal
), or a computed price
for those elements that have no @price
attribute. It
then returns the average price:
<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)"/>
Note that the existing @price
attributes could
equally have been added to the $prices
sequence using
xsl:copy-of
or xsl:value-of
. However,
xsl:copy-of
would
create a copy of the attribute node, which is not needed in this
situation, while xsl:value-of
would create a
new text node, which then has to be converted to an
xs:decimal
. Using xsl:sequence
, which in this
case atomizes the existing attribute node and adds an
xs:decimal
atomic value to the result sequence, is a
more direct way of achieving the same result.
This example could alternatively be solved at the XPath level:
<xsl:value-of select="avg(for $p in //product return if ($p/@price) then $p/@price else ($p/@cost * 1.5))"/>
<!-- Category: instruction -->
<xsl:number
value? = expression
select? = expression
level? = "single" | "multiple" | "any"
count? = pattern
from? = pattern
format? = { string }
lang? = { nmtoken }
letter-value? = { "alphabetic" | "traditional" }
ordinal? = { string }
grouping-separator? = { char }
grouping-size? = { number
} />
The xsl:number
instruction is used to create a formatted number. The result of the
instruction is a newly constructed text node containing the formatted
number as its string
value. But if the formatted number is a zero-length string,
the result of the instruction is an empty sequence.
[Definition: The
xsl:number
instruction
performs two tasks: firstly, determining a place marker (this is
a sequence of integers, to allow for hierarchic numbering schemes such
as 1.12.2
or 3(c)ii
), and secondly,
formatting the place marker for output as a text node in the result
sequence.] The place marker to be
formatted can either be supplied directly, in the value
attribute, or it can be computed based on the position of a
selected node within the tree that contains it.
[ERR
XT0975] It is a static error if the value
attribute
of xsl:number
is present
unless the select
, level
, count
,
and from
attributes are all absent.
Note:
The facilities described in this section are specifically designed
to enable the calculation and formatting of section numbers,
paragraph numbers, and the like. For formatting of other numeric
quantities, the format-number
function may
be more suitable: see 16.4 Number
Formatting.
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 $V in the atomized sequence is then converted
to the integer value returned by the XPath expression
xs:integer(round(number($V)))
. 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.
[ERR
XT0980] It is a recoverable dynamic error if any
undiscarded item in the atomized sequence cannot be
converted to an integer, or if the resulting integer is less than 1
(one). The optional recovery action is to
convert that item (after atomization, but before conversion to
a number) to a string as if by a call to the string
FO function and then to insert the resulting
string into the formatted result string in its proper position.
If the value cannot be converted to a string, the error is
treated as an unrecoverable error.
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.
The following example numbers a sorted list:
<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>
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
a selected node within its containing document. If the
select
attribute is present, then the expression
contained in the select
attribute is evaluated to
determine the selected node. If the select
attribute is
omitted, then the selected node is the context node.
[ERR
XT0990] It is a recoverable dynamic error if the xsl:number
instruction is
evaluated, with no value
or
select
attribute, when the context item is not a
node. The optional recovery action is to
return the empty sequence.
[ERR
XT1000] It is a type error if the result of evaluating the
select
attribute of the xsl:number
instruction is anything
other than a single node.
The following attributes control how the selected 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 selected
node and, if the selected node has an expanded-QName,
with the same expanded-QName as the
selected 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 and only 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 and only 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.
Let $S
be the selected node.
When level="single"
:
Let $A
be the node sequence selected by the
following expression:
$S/ancestor-or-self::node()[matches-count(.)][1]
(this selects the innermost ancestor-or-self node that matches
the count
pattern)
Let $F
be the node sequence selected by the
expression
$S/ancestor-or-self::node()[matches-from(.)][1]
(this selects the innermost ancestor-or-self node that matches
the from
pattern):
Let $AF
be the value of:
$A intersect
($F/descendant-or-self::node())
(this selects $A if it is a descendant-or-self of $F, or the empty sequence otherwise)
If $AF
is empty, return the empty sequence,
()
Otherwise return the value of:
1 +
count($AF/preceding-sibling::node()[matches-count(.)])
(the number of preceding siblings of the counted node that
match the count
pattern, plus one).
When level="multiple"
:
Let $A
be the node sequence selected by the
expression
$S/ancestor-or-self::node()[matches-count(.)]
(the set of ancestor-or-self nodes that match the
count
pattern)
Let $F
be the node sequence selected by the
expression
$S/ancestor-or-self::node()[matches-from(.)][1]
(the innermost ancestor-or-self node that matches the
from
pattern)
Let $AF
be the value of
$A intersect
($F/descendant-or-self::node())
(the nodes selected in the first step that are descendant-or-self nodes of the node selected in the second step)
Return the result of the expression
for $af in $AF return
1+count($af/preceding-sibling::node()[matches-count(.)])
(a sequence of integers containing, for each of these nodes,
one plus the number of preceding siblings that match the
count
pattern)
When level="any"
:
Let $A
be the node sequence selected by the
expression
$S/(preceding::node()|ancestor-or-self::node())[matches-count(.)]
(the set of nodes that match the count
pattern
and that precede the selected node in document order, but
excluding attribute and namespace nodes)
Let $F
be the node sequence selected by the
expression
$S/(preceding::node()|ancestor-or-self::node())[matches-from(.)][last()]
(the last node in document order that matches the
from
pattern and that precedes the selected node,
using the same definition)
Let $AF
be the node sequence $A[. is $F or
. >> $F]
.
(the nodes selected in the first step, excluding those that precede the node selected in the second step)
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.
The following will number the items in an ordered list:
<xsl:template match="ol/item"> <fo:block> <xsl:number/> <xsl:text>. </xsl:text> <xsl:apply-templates/> </fo:block> <xsl:template>
The following two rules will number title
elements.
This is intended for a document that contains a sequence of
chapters followed by a sequence of appendices, where both chapters
and appendices contain sections, which in turn contain subsections.
Chapters are numbered 1, 2, 3; appendices are numbered A, B, C;
sections in chapters are numbered 1.1, 1.2, 1.3; sections in
appendices are numbered A.1, A.2, A.3. Subsections within a
chapter are numbered 1.1.1, 1.1.2, 1.1.3; subsections within an
appendix are numbered A.1.1, A.1.2, A.1.3.
<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>
This example numbers notes sequentially within a chapter:
<xsl:template match="note"> <fo:block> <xsl:number level="any" from="chapter" format="(1) "/> <xsl:apply-templates/> </fo:block> </xsl:template>
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) indicate the format to be used for each number
in the sequence; in most cases the format token is the same as
the required representation of the number 1 (one). 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. 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 .
(dot).
Given the sequence of numbers 5, 13, 7
and the
format token A-001(i)
, the output will be the string
E-013(vii)
Format tokens 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. The digits used in the decimal
representation are the set of digits containing the digit
character used in 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 of ١
(Arabic-Indic
digit one) generates the sequence ١
then
٢
then ٣
...
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 ...
.
A format token w
generates numbers written as
lower-case words, for example in English, one two three
four ...
A format token W
generates numbers written as
upper-case words, for example in English, ONE TWO THREE
FOUR ...
A format token Ww
generates numbers written as
title-case words, for example in English, One Two Three
Four ...
Any other format token indicates a numbering sequence that
starts with that token (but see the note below). It is implementation-defined which
numbering sequences, additional to those listed above, are
supported. If an implementation does not support a numbering
sequence represented by the given token, it must use a format token of 1
.
Note:
In some traditional numbering sequences additional signs are added to denote that the letters should be interpreted as numbers; these are not included in the format token. An example, see also the example below, is classical Greek where a dexia keraia and sometimes an aristeri keraia is added.
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
.
The above expansions of numbering sequences for format tokens such
as a
and i
are indicative but not
prescriptive. There are various conventions in use for how alphabetic
sequences continue when the alphabet is exhausted, and differing
conventions for how roman numerals are written (for example,
IV
versus IIII
as the representation of the
number 4). Sometimes alphabetic sequences are used that omit letters
such as i
and o
. This specification does
not prescribe the detail of any sequence other than those sequences
consisting entirely of decimal digits.
Many numbering sequences are language-sensitive. This
applies especially to the sequence selected by the tokens
w
, W
and Ww
. It also applies
to other sequences, for example different languages using the
Cyrillic alphabet use different sequences of characters, each
starting with the letter #x410 (Cyrillic capital letter A). In such
cases, the lang
attribute specifies which
language's conventions are to be used; it has the same
range of values as xml:lang
(see [XML
1.0]). If no lang
value is specified, the language
that is used is implementation-defined. The
set of languages for which numbering is supported is implementation-defined. If a
language is requested that is not supported, the processor uses the
language that it would use if the lang
attribute were
omitted.
If the optional ordinal
attribute is present, and if
its value is not a zero-length string, this indicates a request to
output ordinal numbers rather than cardinal numbers. For example, in
English, the value ordinal="yes"
when used with the
format token 1
outputs the sequence 1st 2nd 3rd
4th ...
, and when used with the format token w
outputs the sequence first second third fourth ...
. In
some languages, ordinal numbers vary depending on the grammatical
context, for example they may have different genders and may decline
with the noun that they qualify. In such cases the value of the
ordinal
attribute may be used to indicate the variation
of the ordinal number required. The way in which the variation is
indicated will depend on the conventions of the language. For
inflected languages that vary the ending of the word, the preferred
approach is to indicate the required ending, preceded by a hyphen:
for example in German, appropriate values are -e, -er, -es,
-en
. If ordinal numbering is not supported for the combination
of the format token, the language, and the actual value of the
ordinal
attribute, the request is ignored and cardinal
numbers are generated instead.
The specification format="1" ordinal="-º"
language="it"
, if supported, should produce the
sequence:
1º 2º 3º 4º ...
The specification format="Ww" ordinal="-o"
language="it"
, if supported, should produce the
sequence:
Primo Secondo Terzo Quarto Quinto ...
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:
Implementations may use
extension attributes on
xsl:number
to provide
additional control over the way in which numbers are formatted.
The grouping-separator
attribute gives the separator
used as a grouping (for example, 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
while
grouping-separator="."
and
grouping-size="2"
would produce numbers of the form
1.00.00.00
. If only one of the
grouping-separator
and grouping-size
attributes is specified, then it is ignored.
These examples use non-Latin characters which might not display correctly in all browsers, depending on the system configuration.
Description | Format Token | Sequence |
---|---|---|
French cardinal words | format="Ww"
language="fr" |
Un, Deux, Trois, Quatre |
German ordinal words | format="w" ordinal="-e"
language="de" |
erste, zweite, dritte, vierte |
Katakana numbering |
format="ア" |
ア, イ, ウ, エ, オ, カ, キ, ク, ケ, コ, サ, シ, ス, セ, ソ, タ, チ, ツ, テ, ト, ナ, ニ, ヌ, ネ, ノ, ハ, ヒ, フ, ヘ, ホ, マ, ミ, ム, メ, モ, ヤ, ユ, ヨ, ラ, リ, ル, レ, ロ, ワ, ヰ, ヱ, ヲ, ン |
Katakana numbering in iroha order |
format="イ" |
イ, ロ, ハ, ニ, ホ, ヘ, ト, チ, リ, ヌ, ル, ヲ, ワ, カ, ヨ, タ, レ, ソ, ツ, ネ, ナ, ラ, ム, ウ, ヰ, ノ, オ, ク, ヤ, マ, ケ, フ, コ, エ, テ, ア, サ, キ, ユ, メ, ミ, シ, ヱ, ヒ, モ, セ, ス |
Thai numbering |
format="๑" |
๑, ๒, ๓, ๔, ๕, ๖, ๗, ๘, ๙, ๑๐, ๑๑, ๑๒, ๑๓, ๑๔, ๑๕, ๑๖, ๑๗, ๑๘, ๑๙, ๒๐ |
Traditional Hebrew numbering | format="א"
letter-value="traditional" |
א, ב, ג, ד, ה, ו, ז, ח, ט, י, יא, יב, יג, יד, טו, טז, יז, יח, יט, כ |
Traditional Georgian numbering | format="ა"
letter-value="traditional" |
ა, ბ, გ, დ, ე, ვ, ზ, ჱ, თ, ი, ია, იბ, იგ, იდ, იე, ივ, იზ, იჱ, ით, კ |
Classical Greek numbering (see note) | format="α"
letter-value="traditional" |
αʹ, βʹ, γʹ, δʹ, εʹ, ϛʹ, ζʹ, ηʹ, θʹ, ιʹ, ιαʹ, ιβʹ, ιγʹ, ιδʹ, ιεʹ, ιϛʹ, ιζʹ, ιηʹ, ιθʹ, κʹ |
Old Slavic numbering | format="а"
letter-value="traditional" |
А, В, Г, Д, Е, Ѕ, З, И, Ѳ, Ӏ, АӀ, ВӀ, ГӀ, ДӀ, ЕӀ, ЅӀ, ЗӀ, ИӀ, ѲӀ, К |
Note that Glassical Greek is an example where the format token is not the same as the representation of the number 1.
[Definition: A sort key specification is a
sequence of one or more adjacent xsl:sort
elements which together
define rules for sorting the items in an input sequence to form a
sorted sequence.]
[Definition: Within a sort key specification, each
xsl:sort
element defines one
sort key component.] The first
xsl:sort
element specifies the
primary component of the sort key specification, the second xsl:sort
element specifies the
secondary component of the sort key specification and so on.
A sort key specification may occur only immediately within an
xsl:apply-templates
,
xsl:for-each
,
xsl:perform-sort
, or
xsl:for-each-group
element.
Note:
When used within xsl:for-each
, xsl:for-each-group
,
xsl:perform-sort
, or
xsl:sort
elements
must occur before any other children.
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 }>
<!-- Content: sequence-constructor
-->
</xsl:sort>
The xsl:sort
element
defines a sort key component. A sort key component
specifies how a sort key value is to be computed for each
item in the sequence being sorted, and also how two sort key values
are to be compared.
The value of a sort key component is determined either
by its select
attribute, or by the contained sequence
constructor. If neither is present, the default is
select="."
, which has the effect of sorting on the
actual value of the item if it is an atomic value, or on the
typed-value of the item if it is a node. If a select
attribute is present, its value must be an
XPath expression.
[ERR
XT1015] It is a static error if an xsl:sort
element with a
select
attribute has non-empty content.
Those attributes of the xsl:sort
elements whose values are
attribute value templates are
evaluated using the same focus as is used to evaluate the select
attribute of the containing instruction (specifically, xsl:apply-templates
,
xsl:for-each
, xsl:for-each-group
, or
xsl:perform-sort
).
[Definition: The sequence to be sorted is referred to as the initial sequence.]
[Definition: The sequence after sorting as defined by the
xsl:sort
elements is
referred to as the sorted sequence.]
[Definition: For each item in the initial sequence, a value is computed for each sort key component within the sort key specification. The value computed for an item by using the Nth sort key component is referred to as the Nth sort key value of that item.]
The items in the initial sequence are ordered into a
sorted
sequence by comparing their sort key values. The relative position of
two items A and B in the sorted sequence is
determined as follows. The first sort key value of A is
compared with the first sort key value of B, according
to the rules of the first sort key component. 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 component specifies
descending
, in which case B will precede
A in the sorted sequence. If, however, the relevant sort
key values compare equal, then the second sort key value of
A is compared with the second sort key value of
B, according to the rules of the second sort key
component. This continues until two sort key values are found
that compare unequal. If all the sort key values compare equal,
then A will precede B in the sorted sequence if
and only if A preceded B in the initial
sequence.
Note:
If two items have equal sort key values, then their order in the
sorted
sequence will be the same as their order in the initial
sequence, regardless of whether
order="descending"
was specified on any or all of
the sort key components.
The Nth sort key value is computed by evaluating
either the select
attribute or the contained sequence
constructor of the Nth xsl:sort
element, or the
expression .
(dot) if neither is present. This
evaluation is done with the focus set as follows:
The context item is the item in the initial sequence whose sort key value 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.
Note:
As in any other XPath expression, the current
function may be used
within the select
expression of xsl:sort
to refer to the item
that is the context item for the expression as a whole; that is,
the item whose sort key value is being computed.
The sort key values are atomized, and are then compared. The way they are compared depends on their data type, as described in the next section.
It is possible to force the system to compare sort key values
using the rules for a particular data type by including a cast as
part of the sort key component. 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 key values are compared using the rules appropriate
to their data type. Any values of type
xdt:untypedAtomic
are cast to
xs:string
.
For backwards compatibility with XSLT 1.0, the
data-type
attribute remains available. If this
has the effective value text
,
the atomized sort key values are converted to strings
before being compared. If it has the effective value
number
, the atomized sort key values are
converted to doubles before being compared. The conversion is done
by using the string
FO or number
FO function as appropriate. If the
data-type
attribute has any other effective value,
then the value must be a lexical QName with a
non-empty prefix, and the effect of the attribute is
implementation-defined.
[ERR
XT1020] If any sort key value, 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
sort key value is the first item in the sequence. In other cases,
this is a type
error.
The set of sort key values (after any conversion) are first divided into two categories: empty values, and ordinary values. The empty sort key values represent those items where the sort key value is an empty sequence. These values are considered for sorting purposes to be equal to each other, but less than any other value. The remaining values are classified as ordinary values.
[ERR
XT1030] It is a recoverable dynamic error if, for any
sort
key component, the set of sort key values 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. The
optional recovery action is to
assign an arbitrary but consistent implementation-dependent
ordering to any such pair of values.
Note:
The above error condition may occur if the values to be sorted
are of a type that does not support ordering (for example,
xs:QName
) or if the sequence is heterogeneous (for
example, if it contains both strings and numbers). The error can
generally be prevented by invoking a cast or constructor function
within the sort key component
In general, comparison of two ordinary values is performed
according to the rules of the XPath lt
operator.
However, NaN values, for sorting purposes, are considered to
be equal to each other, and less than any other numeric
value. Special rules also apply to the
xs:string
type and types derived by restriction
from xs:string
, as described in the next
section.
The rules given in this section apply when comparing
values whose type is xs:string
, or a type
derived by restriction from xs:string
.
[Definition: 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.
The one collation URI that must be recognized by every
implementation is
http://www.w3.org/2003/11/xpath-functions/collation/codepoint
,
which provides the ability to compare strings based on the Unicode
codepoint values of the characters in the string.
For more information about collations, see Section 7.3 Equality and Comparison of StringsFO in [Functions and Operators].
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.
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)
.
[ERR
XT1035] It is a recoverable dynamic error if the
collation URI specified to xsl:sort
is a collation that is
not recognized by the implementation. The optional recovery action is to
sort using the collation that would be chosen if the
collation
attribute were omitted.
Note:
It is entirely for the implementation to determine whether it recognizes a particular collation URI. For example, if the implementation allows collation URIs to contain parameters in the query part of the URI, it is the implementation that determines whether a URI containing an unknown or invalid parameter is or is not a recognized collation URI.
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 should be used. 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).
If none of the collation
, lang
or
case-order
attributes is present, the collation is
chosen in an implementation-defined way. It is
not required that the default collation
for sorting should be the same as the default collation used when
evaluating XPath expressions, as described in 5.3.1 Initializing the Static
Context.
Note:
It is usually appropriate, when sorting, to use a strong collation, that is, one that takes account of secondary differences (accents) and tertiary differences (case) between strings that are otherwise equal.
Useful background information on international sorting is
provided in [UNICODE TR10]. The
case-order
attribute may be interpreted as described
in section 6.6 of [UNICODE
TR10].
<!-- Category: instruction
-->
<xsl:perform-sort
select? = expression>
<!-- Content: (xsl:sort+,
sequence-constructor) -->
</xsl:perform-sort>
The xsl:perform-sort
instruction
is used to return a sorted sequence.
The initial sequence is obtained either by
evaluating the select
attribute or by evaluating the
contained sequence constructor (but not both). If there is no
select
attribute and no sequence constructor then the
initial
sequence (and therefore, the sorted sequence) is an empty sequence.
[ERR
XT1040] It is a static error if an xsl:perform-sort
instruction
with a select
attribute has any content other than
xsl:sort
and xsl:fallback
instructions.
The result of the xsl:perform-sort
instruction
is the result of sorting its initial sequence using its contained
sort key specification.
The following stylesheet function sorts a sequence of atomic values using the value itself as the sort key.
<xsl:function name="local:sort" as="xdt:anyAtomicType*"> <xsl:param name="in" as="xdt:anyAtomicType*"/> <xsl:perform-sort select="$in"> <xsl:sort select="."/> </xsl:perform-sort> </xsl:function>
The following example defines a function that sorts books by price, and uses this function to output the five books that have the lowest prices:
<xsl:function name="bib:books-by-price" as="element(bib:book)*> <xsl:param name="in" as="element(bib:book)*"/> <xsl:perform-sort select="$in"> <xsl:sort select="xs:decimal(bib:price)"/> </xsl:perform-sort> </xsl:function> ... <xsl:copy-of select="bib:books-by-price(//bib:book)[position() = 1 to 5]"/>
When used within xsl:for-each
or xsl:apply-templates
, a
sort key 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.
For example, suppose an employee database has the form
<employees> <employee> <name> <given>James</given> <family>Clark</family> </name> ... </employee> </employees>
Then a list of employees sorted by name could be generated using:
<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 key specification indicates the
order in which the groups are to be processed. For the effect of
xsl:for-each-group
, see
14 Grouping
The facilities described in this section are designed to allow items in a sequence to be grouped based on common values; for example it allows grouping of elements having the same value for a particular attribute, or elements with the same name, or elements with common values for any other expression. Since grouping identifies items with duplicate values, the same facilities also allow selection of the distinct values in a sequence of items, that is, the elimination of duplicates.
Note:
Simple elimination of duplicates can also be achieved using the
function distinct-values
FO in the core function library: see [Functions and Operators].
In addition these facilities allow grouping based on sequential
position, for example selecting groups of adjacent para
elements. The facilities also provide an easy way to do fixed-size
grouping, for example identifying groups of three adjacent nodes, which
is useful when arranging data in multiple columns.
For each group of items identified, it is possible to evaluate a sequence constructor for the group. Grouping is nestable to multiple levels so that groups of distinct items can be identified, then from among the distinct groups selected, further sub-grouping of distinct items in the current group can be done.
It is also possible for one item to participate in more than one group.
current-group
() as
item()*
[Definition: 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.
[ERR
XT1060] It is a static error if the current-group
function is
used within a pattern.
current-grouping-key
() as
xdt:anyAtomicType?
[Definition: 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 a
single atomic value. At other times, it will be the empty
sequence.
The function current-grouping-key
returns the current grouping key.
The function takes no arguments.
[ERR
XT1070] It is a static error if the current-grouping-key
function is used within a pattern.
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.
[Definition: 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
or final 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.
[Definition: 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.]
[Definition: 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.
[ERR XT1080] 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.
[ERR
XT1090] It is an error to specify the
collation
attribute if neither the group-by
attribute nor group-adjacent
attribute is specified.
[Definition: 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.
[ERR
XT1100] It is a type error if the result of
evaluating the group-adjacent
attribute is
an empty sequence, or a sequence containing more than one item.
Grouping keys
are compared using the rules for the eq
operator
appropriate to their dynamic type. Values of type
xdt:untypedAtomic
are cast to xs:string
before the comparison. Two items that are not comparable using the
eq
operator are considered to be not equal, that is,
they are allocated to different groups. 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.
[ERR
XT1120] When the group-starting-with
or
group-ending-with
attribute is used, it is a type error if the result of
evaluating the select
expression contains an item that
is not a node.
If the group-by
attribute is present, the items
in the population
are examined, in population order. For each item J,
the expression in the group-by
attribute is
evaluated to produce a sequence of zero or more grouping key values.
For each one of these grouping keys, if there is already a group
created to hold items having that grouping key value,
J is added to that group; otherwise a new group is
created for items with that grouping key value, and J
becomes its first member.
An item in the population may thus be assigned to zero, one, or many groups. An item will never be 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. An item here means the item at a particular position within the population—if the population contains the same node at several different positions in the sequence then a group may indeed contain duplicate nodes.
The number of groups will be the same as the number of distinct grouping key values present in the population.
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.
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.
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.
[Definition: For each group, the item within the group that is first in population order is known as the initial item of the group.]
[Definition: 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.]
[Definition: 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 key components are allowed, and are
evaluated in major-to-minor order. If two groups have the same values
for all their sort key components, 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 value 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.
For example, this means that if the grouping key is @category
,
you can sort the groups in order of their grouping key by writing
<xsl:sort select="current-grouping-key()"/>
; or
you can sort the groups in order of size by writing
<xsl:sort select="count(current-group())"/>
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 sequence 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
sequence constructor, a call on
position()
takes successive values 1, 2, ...
last()
.
On completion of the evaluation of the xsl:for-each-group
, the
current group
and current grouping key revert to
their previous value.
The following example groups a list of nodes based on common values. The resulting groups are numbered but unsorted, and a total is calculated for each group.
Source XML document:
<cities> <city name="Milano" country="Italia" pop="5"/> <city name="Paris" country="France" pop="7"/> <city name="München" country="Deutschland" pop="4"/> <city name="Lyon" country="France" pop="2"/> <city name="Venezia" country="Italia" pop="1"/> </cities>
More specifically, the aim is to produce a four-column table,
containing one row for each distinct country. The four columns are
to contain first, a sequence number giving the number of the row;
second, the name of the country, third, a comma-separated
alphabetical list of the city names within that country, and
fourth, the sum of the pop
attribute for the cities in
that country.
Desired output:
<table> <tr> <th>Position</th> <th>Country</th> <th>List of Cities</th> <th>Population</th> </tr> <tr> <td>1</td> <td>Italia</td> <td>Milano, Venezia</td> <td>6</td> </tr> <tr> <td>2</td> <td>France</td> <td>Lyon, Paris</td> <td>9</td> </tr> <tr> <td>3</td> <td>Deutschland</td> <td>München</td> <td>4</td> </tr> </table>
Solution:
<table xsl:version="2.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> <tr> <th>Position</th> <th>Country</th> <th>City List</th> <th>Population</th> </tr> <xsl:for-each-group select="cities/city" group-by="@country"> <tr> <td><xsl:value-of select="position()"/></td> <td><xsl:value-of select="@country"/></td> <td> <xsl:value-of select="current-group()/@name" separator=", "/> </td> <td><xsl:value-of select="sum(current-group()/@pop)"/></td> </tr> </xsl:for-each-group> </table>
Sometimes it is necessary to use a composite grouping key: for example, suppose the source document is similar to the one used in the previous examples, but allows multiple entries for the same country and city, such as:
<cities> <city name="Milano" country="Italia" year="1950" pop="5.23"/> <city name="Milano" country="Italia" year="1960" pop="5.29"/> <city name="Padova" country="Italia" year="1950" pop="0.69"/> <city name="Padova" country="Italia" year="1960" pop="0.93"/> <city name="Paris" country="France" year="1951" pop="7.2"/> <city name="Paris" country="France" year="1961" pop="7.6"/> </cities>
Now suppose we want to list the average value of
@pop
for each (country, name) combination. One way to
handle this is to concatenate the parts of the key, for example
<xsl:for-each-group select="concat(@country, '/',
@name)">
. A more flexible solution is to nest one
xsl:for-each-group
element directly inside another:
<xsl:for-each-group select="cities/city" group-by="@country"> <xsl:for-each-group select="current-group()" group-by="@name"> <p><xsl:value-of select="@name"/>, <xsl:value-of select="@country"/>: <xsl:value-of select="avg(current-group()/@pop)"/></p> </xsl:for-each-group> </xsl:for-each-group>
The two approaches are not precisely equivalent. If the code
were changed to output the value of position()
alongside @name
then the first approach (a single
xsl:for-each-group
element with a compound key) would number the groups (1, 2, 3),
while the second approach (two nested xsl:for-each-group
elements) would number them (1, 2, 1).
The next example identifies a group not by the presence of a
common value, but rather by adjacency in document order. A group
consists of an h2
element, followed by all the
p
elements up to the next h2
element.
Source XML document:
<body> <h2>Introduction</h2> <p>XSLT is used to write stylesheets.</p> <p>XQuery is used to query XML databases.</p> <h2>What is a stylesheet?</h2> <p>A stylesheet is an XML document used to define a transformation.</p> <p>Stylesheets may be written in XSLT.</p> <p>XSLT 2.0 introduces new grouping constructs.</p> </body>
Desired output:
<chapter> <section title="Introduction"> <para>XSLT is used to write stylesheets.</para> <para>XQuery is used to query XML databases.</para> </section> <section title="What is a stylesheet?"> <para>A stylesheet is an XML document used to define a transformation.</para> <para>Stylesheets may be written in XSLT.</para> <para>XSLT 2.0 introduces new grouping constructs.</para> </section> </chapter>
Solution:
<xsl:template match="body"> <chapter> <xsl:for-each-group select="*" group-starting-with="h2" > <section title="{self::h2}"> <xsl:for-each select="current-group()[self::p]"> <para><xsl:value-of select="."/></para> </xsl:for-each> </section> </xsl:for-each-group> </chapter> </xsl:template>
The use of title="{self::h2}"
rather than
title="{.}"
is to handle the case where the first
element is not an h2
element.
The next example illustrates how a group of related elements can
be identified by the last element in the group, rather than the
first. Here the absence of the attribute
continued="yes"
indicates the end of the group.
Source XML document:
<doc> <page continued="yes">Some text</page> <page continued="yes">More text</page> <page>Yet more text</page> <page continued="yes">Some words</page> <page continued="yes">More words</page> <page>Yet more words</page> </doc>
Desired output:
<doc> <pageset> <page>Some text</page> <page>More text</page> <page>Yet more text</page> </pageset> <pageset> <page>Some words</page> <page>More words</page> <page>Yet more words</page> </pageset> </doc>
Solution:
<xsl:template match="doc"> <doc> <xsl:for-each-group select="*" group-ending-with="page[not(@continued='yes')]"> <pageset> <xsl:for-each select="current-group()"> <page><xsl:value-of select="."/></page> </xsl:for-each> </pageset> </xsl:for-each-group> </doc> </xsl:template>
The next example shows how an item can be added to multiple groups. Book titles will be added to one group for each indexing term marked up within the title.
Source XML document:
<titles> <title>A Beginner's Guide to <ix>Java</ix></title> <title>Learning <ix>XML</ix></title> <title>Using <ix>XML</ix> with <ix>Java</ix></title> </titles>
Desired output:
<h2>Java</h2> <p>A Beginner's Guide to Java</p> <p>Using XML with Java</p> <h2>XML</h2> <p>Learning XML</p> <p>Using XML with Java</p>
Solution:
<xsl:template match="titles"> <xsl:for-each-group select="title" group-by="ix"> <h2><xsl:value-of select="current-grouping-key()"/></h2> <xsl:for-each select="current-group()"> <xsl:value-of select="."/> </xsl:for-each> </xsl:for-each-group> </xsl:template>
In the final example, the membership of a node within a group is based both on adjacency of the nodes in document order, and on common values. In this case, the grouping key is a boolean condition, true or false, so the effect is that a grouping establishes a maximal sequence of nodes for which the condition is true, followed by a maximal sequence for which it is false, and so on.
Source XML document:
<p>Do <em>not</em>: <ul> <li>talk,</li> <li>eat, or</li> <li>use your mobile telephone</li> </ul> while you are in the cinema.</p>
Desired output:
<p>Do <em>not</em>:</p> <ul> <li>talk,</li> <li>eat, or</li> <li>use your mobile telephone</li> </ul> <p>while you are in the cinema.</p>
Solution:
This requires creating a p
element around the
maximal sequence of sibling nodes that does not include a
ul
or ol
element.
This can be done by using group-adjacent
, with a
grouping key that is true if the element is a ul
or
ol
element, and false otherwise:
<xsl:template match="p"> <xsl:for-each-group select="node()" group-adjacent="self::ul or self::ol"> <xsl:choose> <xsl:when test="current-grouping-key()"> <xsl:copy-of select="current-group()"/> </xsl:when> <xsl:otherwise> <p> <xsl:copy-of select="current-group()"/> </p> </xsl:otherwise> </xsl:choose> </xsl:for-each-group> </xsl:template>
The core function library for XPath 2.0 defines three functions that make use of regular expressions:
matches
FO returns a boolean result that indicates
whether or not a string matches a given regular expression.
replace
FO takes a string as input and returns a
string obtained by replacing all substrings that match a given
regular expression with a replacement string.
tokenize
FO returns a sequence of strings formed by
breaking a supplied input string at any separator that matches a
given regular expression.
These functions are described in [Functions and Operators].
For more complex string processing than is possible using these
functions, XSLT provides an instruction xsl:analyze-string
, which is
defined in this section.
The regular expressions used by this instruction, and the flags that control the interpretation of these regular expressions, must conform to the syntax defined in [Functions and Operators] (see Section 7.6.1 Regular Expression SyntaxFO), which is itself based on the syntax defined in [XML Schema].
xsl:analyze-string
instruction<!-- Category: instruction
-->
<xsl:analyze-string
select = expression
regex = { string }
flags? = { string }>
<!-- Content: (xsl:matching-substring?, xsl:non-matching-substring?,
xsl:fallback*) -->
</xsl:analyze-string>
<xsl:matching-substring>
<!-- Content: sequence-constructor
-->
</xsl:matching-substring>
<xsl:non-matching-substring>
<!-- Content: sequence-constructor
-->
</xsl:non-matching-substring>
The xsl:analyze-string
instruction takes as input a string (the result of evaluating the
expression in the select
attribute) and a regular
expression (the effective value of the regex
attribute).
The flags
attribute may be used to control the
interpretation of the regular expression. If the attribute is
omitted, the effect is the same as supplying a zero-length string.
This is interpreted in the same way as the $flags
attribute of the functions matches
FO, replace
FO, and tokenize
FO. Specifically, if it contains the
letter m
, the match operates in multiline mode. If it
contains the letter s
, it operates in dot-all mode. If
it contains the letter i
, it operates in
case-insensitive mode. If it contains the letter x
, then
whitespace within the regular expression is ignored. For more
detailed specifications of these modes, see [Functions and Operators] (Section 7.6.1.1
FlagsFO).
Note:
Because the regex
attribute is an attribute value
template, curly brackets within the regular expression must be
doubled. For example, to match a sequence of one to five
characters, write regex=".{{1,5}}"
.
The xsl:analyze-string
instruction may have two child elements: xsl:matching-substring
and xsl:non-matching-substring
.
Both elements are optional, and neither may appear more than once.
At least one of them must be present.
[ERR
XT1130] It is a static error if the xsl:analyze-string
instruction contains neither an xsl:matching-substring
nor an xsl:non-matching-substring
element.
The xsl:analyze-string
instruction may also have zero or more xsl:fallback
child elements.
These are ignored by an XSLT 2.0 processor, but allow fallback
behavior to be defined when the stylesheet is used with an XSLT 1.0
processor operating in forwards-compatible mode.
This instruction is designed to process all the non-overlapping substrings of the input string that match the regular expression supplied.
[ERR
XT1140] It is a non-recoverable dynamic error if
the effective
value of the regex
attribute does not conform to the
required syntax for regular expressions, as
specified in [Functions and Operators]. The
processor must signal the error. If the
regular expression is known statically (for example, if the attribute
does not contain any expressions enclosed in curly brackets) then the
processor may signal the error as a
static error.
[ERR
XT1145] It is a non-recoverable dynamic error if
the effective
value of the flags
attribute has a value other than
the values defined in [Functions and Operators].
The processor must signal the error. If the
value of the attribute is known statically (for example, if the
attribute does not contain any expressions enclosed in curly brackets) then the
processor may signal the error as a
static error.
[ERR
XT1150] It is a non-recoverable dynamic error if
the effective
value of the regex
attribute is a regular expression
that matches a zero-length string: or more specifically, if the
regular expression $r
and flags $f
are such
that matches("", $r, $f)
returns true. The
processor must signal the error. If the
regular expression is known statically (for example, if the attribute
does not contain any expressions enclosed in curly brackets) then the
processor may signal the error as a
static error.
The xsl:analyze-string
instruction starts at the beginning of the input string and attempts
to find the first substring that matches the regular expression. If
there are several matches, the first match is defined to be the one
whose starting position comes first in the string. If several
alternatives within the regular expression both match at the same
position in the input string, then the match that is chosen is the
first alternative that matches. For example, if the input string is
The quick brown fox jumps
and the regular expression is
jump|jumps
, then the match that is chosen is
jump
.
Having found the first match, the instruction proceeds to find the second and subsequent matches by repeating the search, starting at the first character that was not included in the previous match.
The input string is thus partitioned into a sequence of
substrings, some of which match the regular expression, others which
do not match it. Each substring will contain at least one
character. This sequence of substrings is processed using the
xsl:matching-substring
and xsl:non-matching-substring
child instructions. A matching substring is processed using the
xsl:matching-substring
element, a non-matching substring using the xsl:non-matching-substring
element. Each of these elements takes a sequence
constructor as its content. If the element is absent, the effect is
the same as if it were present with empty content. In processing each
substring, the contents of the substring will be the context item (as a value
of type xs:string
); the position of the substring within
the sequence of matching and non-matching substrings will be the
context
position; and the number of matching and non-matching substrings
will be the context
size.
If the input is a zero-length string, the number of substrings
will be zero, so neither the xsl:matching-substring
nor xsl:non-matching-substring
elements will be evaluated.
regex-group
($group-number
as
xs:integer
) as
xs:string
[Definition: While the xsl:matching-substring
instruction is active, a set of current captured substrings is
available, corresponding to the parenthized sub-expressions of the
regular expression.] These captured
substrings are accessible using the function regex-group
. This function
takes an integer argument to identify the group, and returns a string
representing the captured substring.
If the value of the argument is zero, the entire matched string is
returned. This means that the value of regex-group(0)
is
initially the same as the value of .
(dot).
The function returns the zero-length string if there is no captured substring with the relevant number. This can occur for a number of reasons:
The regular expression does not contain a parenthesized sub-expression with the given number.
The parenthesized sub-expression exists, and did not match any part of the input string.
The parenthesized sub-expression exists, and matched a zero-length substring of the input string.
The set of captured substrings is a context variable with dynamic
scope. It is initially an empty sequence. During the evaluation of an
xsl:matching-substring
instruction it is set to the sequence of matched substrings for that
regex match. During the evaluation of an xsl:non-matching-substring
instruction or a pattern or
a stylesheet function it is set to an
empty sequence. On completion of an instruction that changes the
value, the variable reverts to its previous value.
The value of the current captured substrings is
unaffected through calls of xsl:apply-templates
,
xsl:call-template
,
xsl:apply-imports
or xsl:next-match
, or
by expansion of named attribute sets.
Problem: replace all newline characters in the
abstract
element by empty br
elements:
Solution:
<xsl:analyze-string select="abstract" regex="\n"> <xsl:non-matching-substring> <xsl:value-of select="."/> </xsl:non-matching-substring> <xsl:matching-substring> <br/> </xsl:matching-substring> </xsl:analyze-string>
Problem: replace all occurrences of [...]
in the
body
by cite
elements, retaining the
content between the square brackets as the content of the new
element.
Solution:
<xsl:analyze-string select="body" regex="\[(.*?)\]"> <xsl:matching-substring> <cite><xsl:value-of select="regex-group(1)"/></cite> </xsl:matching-substring> <xsl:non-matching-substring> <xsl:value-of select="."/> </xsl:non-matching-substring> </xsl:analyze-string>
Note that this simple approach fails if the body
element contains markup that needs to be retained. In this case it
is necessary to apply the regular expression processing to each
text node individually. If the [...]
constructs span
multiple text nodes (for example, because there are elements within
the square brackets) then it probably becomes necessary to make two
or more passes over the data.
Problem: the input string contains a date such as 23 March
2002
. Convert it to the form 2002-03-23
.
Solution (with no error handling if the input format is incorrect):
<xsl:variable name="months" select="'January', 'February', 'March', ..."/> <xsl:analyze-string select="normalize-space($input)" regex="([0-9]{{1,2}})\s([A-Z][a-z]+)\s([0-9]{{4}})"> <xsl:matching-substring> <xsl:number value="regex-group(3)" format="0001"/> <xsl:text>-</xsl:text> <xsl:number value="index-of($months, regex-group(2))" format="01"/> <xsl:text>-</xsl:text> <xsl:number value="regex-group(1)" format="01"/> </xsl:matching-substring> </xsl:analyze-string>
Note the use of normalize-space
to simplify the
work done by the regular expression, and the use of doubled curly
brackets because the regex
attribute is an attribute
value template.
This section describes XSLT-specific additions to the core XPath function library. Some of these additional functions also make use of information specified by declarations in the stylesheet; this section also describes these declarations.
document
($uri-sequence
as
item()*
) as
node()*
document
($uri-sequence
as
item()*
,
$base-node
as
node()
) as
node()*
The document
function allows access to XML documents identified by a URI.
The first argument contains a sequence of URI references. The second argument, if present, is a node whose base URI is used to resolve any relative URI references contained in the first argument.
A sequence of absolute URI references is obtained as follows.
For an item in $uri-sequence
that is an instance
of xs:string
, xs:anyURI
, or
xdt:untypedAtomic
, the value is cast to
xs:anyURI
. If the resulting URI reference is an
absolute URI reference then it is used as is. If it is a
relative URI reference, then it is resolved against the base URI
of $base-node
if supplied, or against the base URI
from the static context otherwise (this will usually be the base
URI of the stylesheet module). A relative URI is resolved
against a base URI using the rules defined in [RFC2396]
For an item in $uri-sequence
that is a node, the
node is atomized.
The result must be a sequence whose
items are all instances of xs:string
,
xs:anyURI
, or xdt:untypedAtomic
. Each
of these values is cast to xs:anyURI
, and if the
resulting URI reference is an absolute URI reference then it is
used as is. If it is a relative URI reference, then it
is resolved against the base URI of $base-node
if
supplied, or against the base URI of the node that contained it
otherwise.
Note:
The XPath rules for function calling ensure that it is a type error if the supplied value of the second argument is anything other than a single node. If XPath 1.0 compatibility mode is enabled, then a sequence of nodes may be supplied, and the first node in the sequence will be used.
Each of these absolute URI references is then processed as
follows. Any fragment identifier that is present in the URI reference
is removed, and the resulting absolute URI is cast to a string
and then passed to the doc
FO function defined in [Functions and Operators]. This returns a document node.
If an error occurs during evaluation of the doc
FO function, the processor may either signal this error in the normal way, or
may recover by ignoring the failure, in
which case the failing URI will not contribute any nodes to the
result of the document
function.
If the URI reference contained no fragment identifier, then this
document node is included in the sequence of nodes returned by the
document
function.
If the URI reference contained a fragment identifier, then the fragment identifier is interpreted according to the rules for the media type of the resource identified by the URI, and is used to select zero or more nodes that are descendant-or-self nodes of the returned document node. As described in 2.3 Initiating a Transformation, the media type is available as part of the evaluation context for a transformation.
[ERR XT1160] When a URI reference contains a fragment identifier, it is a recoverable dynamic error if the media type is not one that is recognized by the processor, or if the fragment identifier does not conform to the rules for fragment identifiers for that media type, or if the fragment identifier selects something other than a sequence of nodes (for example, if it selects a range of characters within a text node). The optional recovery action is to ignore the fragment identifier and return the document node. The set of media types recognized by a processor is implementation-defined.
Note:
The recovery action here is different from XSLT 1.0
The sequence of nodes returned by the function is in document
order, with no duplicates. This order has no necessary relationship
to the order in which URIs were supplied in the
$uri-sequence
argument.
Note:
The effect of these rules is that unless XML entities or
xml:base
are used, document("")
refers to
the document node of the containing stylesheet module (the
definitive rules are in [RFC2396]).
The XML resource containing the stylesheet module is processed
exactly as if it were any other XML document, for example there is
no special recognition of xsl:text
elements, and no special
treatment of comments and processing instructions.
unparsed-text
($href
as
xs:string?
)
as
xs:string
unparsed-text
($href
as
xs:string?
,
$encoding
as
xs:string
) as
xs:string
The unparsed-text
function
reads an external resource (for example, a file) and returns its
contents as a string.
The $href
argument must be
a string in the form of a URI. The URI must contain no fragment identifier, and must identify a resource that can be read as text. If
the URI is a relative URI, then it is resolved relative to the base
URI from the static context.
Note:
If a different base URI is appropriate (for example, when
resolving a relative URI read from a source document) then the
relative URI should be resolved using the resolve-uri
FO function before passing it to the unparsed-text
function.
The $encoding
argument, if present, is the name of an
encoding. This encoding is used to translate the contents of the file
into a string. The values for this attribute follow the same rules as
for the encoding attribute in an XML declaration. The only values
which every implementation is obliged to recognize are
utf-8
and utf-16
.
The encoding of the external resource is determined as follows:
external encoding information is used if available, otherwise
if the media type of the resource is text/xml
or
application/xml
(see [RFC2376]), or if it matches the conventions
text/*+xml
or application/*+xml
(see
[RFC3023]), then the encoding is
recognized as specified in [XML 1.0],
otherwise
the value of the $encoding
argument is used if
present, otherwise
UTF-8 is assumed.
Note:
The above rules are chosen for consistency with [XInclude]. Files with an XML media type are treated specially because there are use cases for this function where the retrieved text is to be included as unparsed XML within a CDATA section of a containing document, and because processors are likely to be able to reuse the code that performs encoding detection for XML external entities.
[ERR XT1170] It is a recoverable dynamic error if a URI cannot be used to retrieve a resource containing text. The optional recovery action is to treat the URI as if it referenced a resource containing a zero-length string.
[ERR XT1180] It is a recoverable dynamic error if a resource contains characters that are not permitted XML characters. The optional recovery action is to replace each invalid character with the character #xFFFD (Unicode Replacement Character).
Note:
A different character can be substituted in the serialized output by specifying a character map: see 20.1 Character Maps
[ERR XT1190] It is a non-recoverable dynamic error if a resource contains octets that cannot be decoded into permitted XML characters using the specified encoding. This includes the case where the processor does not support the requested encoding.
[ERR
XT1200] It is a non-recoverable dynamic error if
the second argument of the unparsed-text
function is
omitted and the processor cannot infer the encoding using
external information and the encoding is not UTF-8.
The result is a string containing the text of the resource retrieved using the URI.
Note:
If the text file contains characters such as <
and &
, these will typically be output as
<
and &
when the string is
written to the result tree and serialized as XML or HTML. If these
characters actually represent markup (for example, if the text file
contains HTML), then the stylesheet can attempt to write them as
markup to the output file using the
disable-output-escaping
attribute of the xsl:value-of
instruction (see
20.2 Disabling Output
Escaping. Note, however, that implementations are not
required to support this feature.
This example attempts to read an HTML file and copy it, as HTML, to the serialized output file:
<xsl:output method="html"/> <xsl:template match="/"> <xsl:value-of select="unparsed-text('header.html', 'iso-8859-1')" disable-output-escaping="yes"/> <xsl:apply-templates/> <xsl:value-of select="unparsed-text('footer.html', 'iso-8859-1')" disable-output-escaping="yes"/> </xsl:template>
Keys provide a way to work with documents that contain an implicit cross-reference structure. They make it easier to locate the nodes within a document that have a given value for a given attribute or child element, and they provide a hint to the implementation that certain access paths in the document need to be efficient.
xsl:key
Declaration<!-- Category: declaration -->
<xsl:key
name = qname
match = pattern
use? = expression
collation? = uri>
<!-- Content: sequence-constructor
-->
</xsl:key>
The xsl:key
declaration is used to
declare keys. The name
attribute specifies the name of the key. The value of the
name
attribute is a QName, which is expanded as described in 5.1 Qualified Names. The match
attribute is a Pattern; an xsl:key
element applies to all
nodes that match the pattern specified in the match
attribute.
The value of the key may be specified either using the
use
attribute or by means of the contained sequence
constructor.
[ERR
XT1205] It is a static error if an xsl:key
declaration has a
use
attribute and has non-empty content, or if it has
empty content and no use
attribute.
If the use
attribute is present, its value is an
expression
specifying the values of the key. The expression will be evaluated
with the node that matches the pattern as the context node.
Similarly, if a sequence constructor is present, it is used to determine the values of the key. The sequence constructor will be evaluated with the node that matches the pattern as the context node.
[Definition: The expression in the use
attribute and the sequence constructor within an
xsl:key
declaration are
referred to collectively as the key specifier. The key
specifier determines the values that may be used to find a node
using this key.]
Note:
There is no requirement that all the values of a key should have the same type.
The presence of an xsl:key
declaration makes it easy
to find a node that matches the match
pattern if any
of the values of the key specifier (when applied to that
node) are known. It also provides a hint to the implementation that
access to the nodes by means of these values needs to be efficient
(many implementations are likely to construct an index or hash
table to achieve this). Note that the key specifier
in general returns a sequence of values, and any one of these may
be used to locate the node.
The optional collation
attribute is
used only when deciding whether two strings are equal for the
purposes of key matching. Specifically, two values $a
and $b
are considered equal if the result of the
function call compare($a, $b, $collation)
is zero.
If an xsl:key
declaration specifies a collation
attribute, then
every other xsl:key
declaration with the same value for its name
attribute
must either specify the same collation,
or specify no collation; this collation is used for all xsl:key
declarations with the given
name. In the absence of a collation
attribute, the default collation is used.
It is possible to have:
multiple xsl:key
declarations with the same name;
a node that matches the match
patterns of
several different xsl:key
declarations,
whether these have the same key name or different key
names;
a node that returns more than one value from its key specifier;
a key value that identifies more than one node (the key values for different nodes do not need to be unique).
[Definition: A key is defined as a
set of xsl:key
declarations
in the stylesheet
that share the same name.]
An xsl:key
declaration
with higher import precedence does not override
another of lower import precedence; all the xsl:key
declarations in the
stylesheet are effective regardless of their import precedence.
[ERR
XT1220] It is a static error if there are several
xsl:key
declarations in the
stylesheet with the
same key name and different non-defaulted
collation
attributes. The collation attributes
are the same if the URIs consist of the same sequence of Unicode
code-points.
key
Functionkey
($key-name
as
xs:string
,
$key-value
as
xdt:anyAtomicType*
) as
node*
The key
function does
for keys what the id
FO function does for IDs.
The $key-name
argument specifies the name of the
key. The value of the argument
must be a lexical QName, which is expanded as
described in 5.1 Qualified Names.
[ERR
XT1260] It is a non-recoverable dynamic error
if the value is not a valid QName, or if there is no namespace
declaration in scope for the prefix of the QName, or if the name
obtained by expanding the QName is not the same as the expanded
name of any xsl:key
declaration in the stylesheet. The processor must signal
these errors. If the processor is able to detect the error
statically (for example, when the argument is supplied as a string
literal), then the processor may
optionally signal this as a static error.
The $key-value
argument to the key
function is considered as a
sequence. The set of requested key values is formed by
atomizing the supplied value of the argument,
using the standard function calling rules. Each of the
resulting atomic values is considered as a requested key value. The
result of the function is a sequence of nodes, in document order
and with duplicates removed, comprising those nodes in the same
document as the context node that are matched by an xsl:key
declaration whose name is
the same as the supplied key name, where the result of
evaluating the key specifier contains a value that
is equal to one of these requested key values, under the rules
appropriate to the XPath eq
operator for the two
values in question, using the collation
attributes of
the key declaration when comparing strings. No error is reported if
two values are encountered that are not comparable; they are
regarded for this purposes of this function as being not
equal.
If the second argument is an empty sequence, the result of the function will be an empty sequence.
More specifically, the result of the key
function is a sequence
containing every node N that satisfies the following
conditions:
N is in the same document as the context node.
N matches the pattern specified in the
match
attribute of an xsl:key
declaration whose
name
attribute matches the name specified
in the $key-name
argument.
When the key specifier of that xsl:key
declaration is
evaluated with a singleton focus based on
N, the atomized value of the resulting sequence
includes a value that compares equal to at least one item in
the atomized value of the sequence supplied as
$key-value
, under the rules of the
eq
operator with the collation selected as
described above.
If the current
function is used in either the match
pattern or the
use
expression of the xsl:key
declaration, its value is
the node N that is being considered for inclusion in the
result.
The sequence returned by the key function will be in document order, with duplicates removed.
For example, given a declaration
<xsl:key name="idkey" match="div" use="@id"/>
an expression key("idkey",@ref)
will return the
same nodes as id(@ref)
, assuming that the only ID
attribute declared in the XML source document is:
<!ATTLIST div id ID #IMPLIED>
and that the ref
attribute of the context node
contains no whitespace.
Suppose a document describing a function library uses a
prototype
element to define functions
<prototype name="sqrt" return-type="xs:double"> <arg type="xs:double"/> </prototype>
and a function
element to refer to function
names
<function>sqrt</function>
Then the stylesheet could generate hyperlinks between the references and definitions as follows:
<xsl:key name="func" match="prototype" use="@name"/> <xsl:template match="function"> <b> <a href="#{generate-id(key('func',.))}"> <xsl:apply-templates/> </a> </b> </xsl:template> <xsl:template match="prototype"> <p><a name="{generate-id()}"> <b>Function: </b> ... </a></p> </xsl:template>
The key
function always
returns nodes that are in the same document as the context node. To
retrieve a node from any other document, it is
necessary first to change the context node.
For example, suppose a document contains bibliographic
references in the form
<bibref>XSLT</bibref>
, and there is a
separate XML document bib.xml
containing a
bibliographic database with entries in the form:
<entry name="XSLT">...</entry>
Then the stylesheet could use the following to transform the
bibref
elements:
<xsl:key name="bib" match="entry" use="@name"/> <xsl:template match="bibref"> <xsl:variable name="name" select="."/> <xsl:apply-templates select="document('bib.xml')/key('bib',$name)"/> </xsl:template>
Note:
This relies on the ability in XPath 2.0 to have a function
call on the right-hand side of the /
operator in a
path expression.
[ERR
XT1270] It is a non-recoverable dynamic error
to call the key
function
if there is no context node, or if the root of the
tree containing the context node is not a document node.
format-number
($value
as
xs:double
,
$picture
as
xs:string
) as
xs:string
format-number ( |
$value |
as xs:double , |
$picture |
as xs:string , |
|
$decimal-format-name |
as xs:string ) as xs:string |
The format-number
function
formats $value
as a string using the picture string
specified by the $picture
argument and the
decimal-format named by the $decimal-format-name
argument, or the default decimal-format, if there is no
$decimal-format-name
argument. The value of
$decimal-format-name
must be a
lexical QName,
which is expanded as described in 5.1 Qualified
Names. The result of the function is the formatted string
representation of the supplied number.
[ERR
XT1280] It is a recoverable dynamic error if the name
specified as the $decimal-format-name
argument is
not a valid QName, or if its
prefix has not been declared in an in-scope namespace
declaration, or if the stylesheet does not contain a declaration of a
decimal-format with a matching expanded-QName . The optional recovery action is to
ignore the $decimal-format-name
argument. If the
processor is able to detect the error statically (for example, when
the argument is supplied as a string literal), then the processor
may optionally signal this as a static error.
<!-- Category: declaration
-->
<xsl:decimal-format
name? = qname
decimal-separator? = char
grouping-separator? = char
infinity? = string
minus-sign? = char
NaN? = string
percent? = char
per-mille? = char
zero-digit? = char
digit? = char
pattern-separator? =
char />
[Definition: The xsl:decimal-format
element declares a decimal-format, which controls the
interpretation of a picture string used by the format-number
function.] If there is a
name
attribute, then the element declares a named
decimal-format; otherwise, it declares the default decimal-format.
The value of the name
attribute is a QName, which is expanded as described in
5.1 Qualified Names.
[ERR
XT1290] It is a static error to declare either the default
decimal-format or a decimal-format with a given name more than once
(even with different import precedence), unless it is
declared every time with the same value for all attributes (taking
into account any default values). If a stylesheet does not contain a declaration of
the default decimal format, a declaration equivalent to an xsl:decimal-format
element with no attributes is implied.
The attributes of the xsl:decimal-format
declaration establish values for a number of variables used as
input to the algorithm followed by the format-number
function.
An outline of the purpose of each attribute is given below;
however, the definitive explanations are given later, as part of
the description of this algorithm.
The following attributes control the interpretation of
characters in the picture string supplied to the format-number
function,
and also specify characters that may appear in the result of
formatting the number. In each case the value must be a single character.
decimal-separator
specifies the character used
for the decimal-separator-sign; the default value is
the period character (.
)
grouping-separator
specifies the character used
for the grouping-sign, which is typically used as a
thousands separator; the default value is the comma character
(,
)
percent
specifies the character used for the
percent-sign; the default value is the percent
character (%
)
per-mille
specifies the character used for the
per-mille-sign; the default value is the Unicode
per-mille character (#x2030)
zero-digit
specifies the character used for the
digit-zero-sign; the default value is the digit zero
(0
). This character must
be a digit (category Nd in the Unicode property database), and
it must have the numeric value zero.
This attribute implicitly defines the Unicode character
that is used to represent each of the values 0 to 9 in the
final result string: Unicode is organized so that each set of
decimal digits forms a contiguous block of characters in
numerical sequence.
The following attributes control the interpretation of
characters in the picture string supplied to the format-number
function.
In each case the value must be a single
character.
digit
specifies the character used for the
digit-sign in the picture string; the default value is
the number sign character (#
)
pattern-separator
specifies the character used
for the pattern-separator-sign, which separates
positive and negative sub-pictures in a picture string;
the default value is the semi-colon character
(;
)
The following attributes specify characters or strings that may appear in the result of formatting the number:
infinity
specifies the string used for the
infinity-symbol; the default value is the string
Infinity
NaN
specifies the string used for the
NaN-symbol, which is used to represent the value NaN
(not-a-number); the default value is the string
NaN
minus-sign
specifies the character used for the
minus-symbol; the default value is the hyphen-minus
character (-
, #x2D). The value must be a single character.
[ERR XT1300] It is a static error if, for any named or unnamed decimal format, the variables representing characters used in a picture string do not each have distinct values. These variables are decimal-separator-sign, grouping-sign, percent-sign, per-mille-sign, digit-zero-sign, digit-sign, and pattern-separator-sign.
[Definition: The formatting of a number is controlled by a picture string. The picture string is a sequence of characters, in which the characters assigned to the variables decimal-separator-sign, grouping-sign, zero-digit-sign, digit-sign and pattern-separator-sign are classified as active characters, and all other characters (including the percent-sign and per-mille-sign) are classified as passive characters.]
The integer part of the sub-picture is defined as the part that appears to the left of the decimal-separator-sign if there is one, or the entire sub-picture otherwise. The fractional part of the sub-picture is defined as the part that appears to the right of the decimal-separator-sign if there is one; it is a zero-length string otherwise.
[ERR
XT1310] The picture string must conform to the following rules. It is a
recoverable dynamic error if the
picture string does not satisfy these rules. The optional recovery action is to
ignore those characters in the supplied picture string that make
the picture string invalid. If a valid picture string cannot be
constructed in this way, the processor may recover
by returning the string obtained by applying the string
FO function to the supplied number.
Note that in these rules the words "preceded" and "followed" refer to characters anywhere in the string, they are not to be read as "immediately preceded" and "immediately followed".
A picture-string consists either of a sub-picture, or of two sub-pictures separated by a pattern-separator-sign. A picture-string must not contain more than one pattern-separator-sign. If the picture-string contains two sub-pictures, the first is used for positive values and the second for negative values.
A sub-picture must not contain more than one decimal-separator-sign.
A sub-picture must not contain more than one percent-sign or per-mille-sign, and it must not contain one of each.
A sub-picture must contain at least one digit-sign or zero-digit-sign.
A sub-picture must not contain a passive character that is preceded by an active character and that is followed by another active character.
A sub-picture must not contain a grouping-separator-sign adjacent to a decimal-separator-sign.
The integer part of a sub-picture must not contain a zero-digit-sign that is followed by a digit-sign. The fractional part of a sub-picture must not contain a digit-sign that is followed by a zero-digit-sign.
The evaluation of the format-number
function
is described below in two phases, an analysis phase and a
formatting phase. The analysis phase takes as its inputs the
picture
string and the variables derived from the relevant xsl:decimal-format
declaration, and produces as its output a number of variables with
defined values. The formatting phase takes as its inputs the number
to be formatted and the variables produced by the analysis phase,
and produces as its output a string containing a formatted
representation of the number.
Note:
Numbers will always be formatted with the most significant digit on the left.
This phase of the algorithm analyses the picture string and
the attribute settings of the xsl:decimal-format
declaration, and has the effect of setting the values of various
variables, which are used in the subsequent formatting phase. These
variables are listed below. Each is shown with its initial setting
and its data type.
Several variables are associated with each sub-picture. If there are two sub-pictures, then these rules are applied to one sub-picture to obtain the values that apply to positive numbers, and to the other to obtain the values that apply to negative numbers. If there is only one sub-picture, then the values for both cases are derived from this sub-picture.
The variables are as follows:
The whole-part-grouping-positions is a sequence of integers representing the positions of grouping separators within the integer part of the sub-picture. For each grouping-separator-sign that appears within the integer part of the sub-picture, this sequence contains an integer that is equal to the total number of digit-sign and zero-digit-sign characters that appear within the integer part of the sub-picture and to the right of the grouping-separator-sign. In addition, if these whole-part-grouping-positions are at regular intervals (that is, if they are all consecutive integer multiples of some value N, including the case where there is only one number in the list), then the sequence contains all integer multiples of N as far as necessary to accommodate the largest possible number.
The minimum-whole-part-size is an integer indicating the minimum number of digits that will appear to the left of the decimal-separator-sign. It is normally set to the number of zero-digit-sign characters found in the integer part of the sub-picture. But if the sub-picture contains no zero-digit-sign and no decimal-separator-sign, it is set to one.
The overflow-threshold indicates the smallest number that is too large to fit in the space available. If any digit-sign is found in the integer part of the sub-picture, the overflow-threshold is set to infinity. Otherwise, it is set to ten raised to the power of the number of zero-digit-sign characters found in the integer part of the sub-picture.
The prefix is set to contain all passive characters in the sub-picture to the left of the leftmost active character. If the picture string contains only one sub-picture, the prefix for the negative sub-picture is set by concatenating the minus-sign character and the prefix for the positive sub-picture (if any), in that order.
The fractional-part-grouping-positions is a sequence of integers representing the positions of grouping separators within the fractional part of the sub-picture. For each grouping-separator-sign that appears within the fractional part of the sub-picture, this sequence contains an integer that is equal to the total number of digit-sign and zero-digit-sign characters that appear within the fractional part of the sub-picture and to the left of the grouping-separator-sign.
The minimum-fractional-part-size is set to the number of zero-digit-sign characters found in the fractional part of the sub-picture.
The maximum-fractional-part-size is set to the total number of digit-sign and zero-digit-sign characters found in the fractional part of the sub-picture.
The suffix is set to contain all passive characters to the right of the rightmost active character in the fractional part of the sub-picture.
Note:
If there is only one sub-picture, then all variables for positive numbers and negative numbers will be the same, except for prefix: the prefix for negative numbers will be preceded by the minus-sign character.
This section describes the second phase of processing of the
format-number
function. This phase takes as input a number to be formatted
(referred to as the input number), and the variables set
up by analysing the xsl:decimal-format
declaration and the picture string, as described above. The
result of this phase is a string, which forms the return value of
the format-number
function.
The algorithm for this second stage of processing is as follows:
If the input number is NaN (not a number), the result is the concatenation of the prefix, the specified NaN-symbol, and the suffix, where the prefix and suffix are taken from the sub-picture that applies to positive numbers.
In the rules below, the positive sub-picture and its associated variables are used if the input number is positive, and the negative sub-picture and its associated variables are used otherwise. Negative zero is taken as negative, positive zero as positive.
If the input number is positive or negative infinity, the result is the concatenation of the appropriate prefix, the infinity-symbol, and the appropriate suffix.
If the sub-picture contains a percent-sign, the number is multiplied by 100. If the sub-picture contains a per-mille-sign, the number is multiplied by 1000. The resulting number is referred to below as the adjusted number.
[ERR XT1320] It is a recoverable dynamic error if the absolute value of the adjusted number is numerically greater than or equal to the overflow-threshold. The optional recovery action is to format the number as if each zero-digit-sign character in the integer part of the sub-picture were a digit-sign.
The adjusted number is rounded so that it uses no
more than maximum-fractional-part-size digits in its
fractional part. The rounded number is defined as
the result of calling the function round-half-to-even
FO
with the adjusted number as the first argument, and
the maximum-fractional-part-size as the second
argument.
The absolute value of the rounded number is converted to a string in decimal notation, with no insignificant leading or trailing zeroes, using the characters implied by the choice of zero-digit-sign to represent the ten decimal digits, and the decimal-separator-sign to separate the integer part and the fractional part. (The value zero will at this stage be represented by a decimal-separator-sign on its own.)
If the number of digits to the left of the decimal-separator-sign is less than minimum-whole-part-size, leading zero-digit-sign characters are added to pad out to that size.
If the number of digits to the right of the decimal-separator-sign is less than minimum-fractional-part-size, trailing zero-digit-sign characters are added to pad out to that size.
For each integer N in the whole-part-grouping-positions list, a grouping-separator-sign character is inserted into the string immediately after that digit that appears in the integer part of the number and has N digits between it and the decimal-separator-sign, if there is such a digit.
For each integer N in the fractional-part-grouping-positions list, a grouping-separator-sign character is inserted into the string immediately before that digit that appears in the fractional part of the number and has N digits between it and the decimal-separator-sign, if there is such a digit.
If there is no decimal-separator-sign in the sub-picture, the decimal-separator-sign character is removed from the string (it will be the rightmost character in the string).
The result of the function is the concatenation of the appropriate prefix, the string conversion of the number as obtained above, and the appropriate suffix.
Three functions are provided to represent dates and times as a string, using the conventions of a selected calendar, language, and country. Each has two variants.
format-dateTime ( |
$value |
as xs:dateTime? , |
$picture |
as xs:string , |
|
$language |
as xs:string? , |
|
$calendar |
as xs:string? , |
|
$country |
as xs:string? ) as xs:string? |
format-dateTime
($value
as
xs:dateTime?
,
$picture
as
xs:string
) as
xs:string?
format-date ( |
$value |
as xs:date? , |
$picture |
as xs:string , |
|
$language |
as xs:string? , |
|
$calendar |
as xs:string? , |
|
$country |
as xs:string? ) as xs:string? |
format-date
($value
as
xs:date?
,
$picture
as
xs:string
) as
xs:string?
format-time ( |
$value |
as xs:time? , |
$picture |
as xs:string , |
|
$language |
as xs:string? , |
|
$calendar |
as xs:string? , |
|
$country |
as xs:string? ) as xs:string? |
format-time
($value
as
xs:time?
,
$picture
as
xs:string
) as
xs:string?
The format-dateTime
,
format-date
, and
format-time
functions format $value
as a string using the picture
string specified by the $picture
argument, the
calendar specified by the $calendar
argument, the
language specified by the $language
argument, and the
country specified by the $country
argument. The
result of the function is the formatted string representation of the
supplied dateTime
, date
, or
time
value.
[Definition: The three functions format-date
, format-time
, and format-dateTime
are
referred to collectively as the date formatting
functions.]
If $value
is the empty sequence, the empty sequence
is returned.
Calling the two-argument form of each of the three functions is equivalent to calling the five-argument form with each of the last three arguments set to an empty sequence.
For details of the language
, calendar
,
and country
arguments, see 16.5.2 The language, calendar, and country
arguments.
In general, the use of an invalid picture
,
language
, calendar
, or country
argument is classified as a recoverable dynamic error, with the
optional recovery action being to output
the value of the date
, time
, or
dateTime
in a fallback representation. Use of an option
in any of these arguments that is valid but not supported by the
implementation is not an error, and in these cases the implementation
is required to output the value in a fallback representation.
The picture consists of a sequence of variable markers and literal substrings. A substring enclosed in square brackets is interpreted as a variable marker; substrings not enclosed in square brackets are taken as literal substrings. The literal substrings are optional and if present are rendered unchanged, including any whitespace. If an opening or closing square bracket is required within a literal sub-string, it must be doubled. The variable markers are replaced in the result by strings representing aspects of the date and/or time to be formatted. These are described in detail below.
A variable marker consists of a component specifier followed optionally by one or two presentation modifiers and/or optionally by a width modifier. Whitespace within a variable marker is ignored.
The component specifier indicates the component of the date or time that is required, and takes the following values:
Specifier | Meaning | Default Presentation Modifier |
---|---|---|
Y | year | 1 |
M | month in year | 1 |
D | day in month | 1 |
d | day in year | 1 |
F | day of week | n |
W | week in year | 1 |
w | week in month | 1 |
H | hour in day (24 hours) | 1 |
h | hour in half-day (12 hours) | 1 |
P | am/pm marker | n |
m | minute in hour | 1 |
s | second in minute | 1 |
f | fractional seconds | 1 |
Z | timezone as a time offset from UTC, or if an alphabetic modifier is present the conventional name of a timezone (such as PST) | 1 |
z | timezone as a time offset using GMT, for example GMT+1 | 1 |
C | calendar: the name or abbreviation of a calendar name | n |
E | era: the name of a baseline for the numbering of years, for example the reign of a monarch | n |
[ERR
XT1350] It is a recoverable dynamic error if a
component specifier within the picture refers to components that
are not available in the given $value
. The optional recovery action is to
ignore the offending component specifiers.
The first presentation modifier indicates the style in which the value of a component is to be represented. Its value may be either:
any format token permitted in the format
string
of the xsl:number
instruction (see 12 Numbering),
indicating that the value of the component is to be output
numerically using the specified number format (for example,
1
, 01
, i
,
I
, w
, W
, or
Ww
) or
the format token n
, N
, or
Nn
, indicating that the value of the component is
to be output by name, in lower-case, upper-case, or title-case
respectively. Components that can be output by name include
(but are not limited to) months, days of the week, timezones,
and eras.
If the implementation does not support the use of the requested format token, it must use the default presentation modifier for that component.
If the first presentation modifier is present, then it may optionally be followed by a second presentation modifier as follows:
Modifier | Meaning |
---|---|
t | traditional
numbering. This has the same meaning as
letter-value="traditional" in xsl:number . |
o | ordinal form of a
number, for example 8th or 8º .
The actual representation of the ordinal form of a
number may depend not only on the language, but also on the
grammatical context (for example, in some languages it must
agree in gender). |
Note:
Although the formatting rules are expressed in terms of the
rules for format tokens in xsl:number
, the formats
actually used may be specialized to the numbering of date
components where appropriate. For example, in Italian, it is
conventional to use an ordinal number (primo
) for
the first day of the month, and cardinal numbers (due, tre,
quattro ...
) for the remaining days. A processor may
therefore use this convention to number days of the month,
ignoring the presence or absence of the ordinal presentation
modifier.
Whether or not a presentation modifier is included, a width modifier may be supplied. This indicates the number of characters or digits to be included in the representation of the value.
The width modifier, if present, is introduced by a comma. It takes the form:
, min-width ("-"
max-width)?
where min-width
is either an unsigned integer
indicating the minimum number of characters to be output, or
*
indicating that there is no explicit minimum, and
max-width
is either an unsigned integer indicating the
maximum number of characters to be output, or *
indicating that there is no explicit maximum; if
max-width
is omitted then *
is assumed.
Both integers, if present, must be
greater than zero.
A format token containing leading zeroes, such as
001
, sets the minimum and maximum width to the number
of digits appearing in the format token; if a width modifier is
also present, then the width modifier takes precedence.
If the minumum and maximum width are unspecified, then the output uses as many characters as are required to represent the value of the component without truncation and without padding: this is referred to below as the full representation of the value.
If the full representation of the value exceeds the specified
maximum width, then the processor should
attempt to use an alternative shorter representation that fits
within the maximum width. Where the presentation modifier is
N
, n
, or Nn
, this is done by
abbreviating the name, using either conventional abbreviations if
available, or crude right-truncation if not. For example, setting
max-width
to 4
indicates that four-letter
abbreviations should be used, though it
would be acceptable to use a three-letter abbreviation if this is
in conventional use. (For example, "Tuesday" might be abbreviated
to "Tues", and "Friday" to "Fri".) In the case of the year
component, setting max-width
requests omission of
high-order digits from the year, for example, if
max-width
is set to 2
then the year 2003
will be output as 03
. If no mechanism is available for
fitting the value within the specified maximum width (for example,
when roman numerals are used), then the value should be output in its full representation.
If the full representation of the value is shorter than the specified minimum width, then the processor should pad the value to the specified width. For decimal representations of numbers, this should be done by prepending zero digits from the appropriate set of digit characters, or appending zero digits in the case of the fractional seconds component. In other cases, it should be done by appending spaces.
The set of languages, calendars, and countries that are supported in the date formatting functions is implementation-defined. When any of these arguments is omitted or is an empty sequence, an implementation-defined default value is used.
If the fallback representation uses a different calendar from
that requested, the output string must be
prefixed with [Calendar: X]
where X
identifies the calendar actually used. The string
Calendar
should be localized
using the requested language if available. If the fallback
representation uses a different language from that requested, the
output string should be prefixed with [Language: Y]
where Y
identifies the language actually used. The
string Language
may be
localized in an implementation-dependent way. If
a particular component of the value cannot be output in the
requested format, it should be output in
the default format for that component.
The language
argument specifies the language to be
used for the result string of the function. The value of the
argument must be either the empty
sequence or a value that would be valid for the
xml:lang
attribute (see [XML]). Note that this permits
the identification of sublanguages based on country codes (from
[ISO 3166-1]) as well as identification of
dialects and of regions within a country.
If the language
argument is omitted or is set to an
empty sequence, or if it is set to an invalid value or a value that
the implementation does not recognize, then the processor uses
implementation-defined language.
If an explicit language was requested and the request is not
honored,
The language is used to select the appropriate language-dependent forms of:
names (for example, of months)
numbers expressed as words or as ordinals (twenty, 20th, twentieth
)
hour convention (0-23 vs 1-24, 0-11 vs 1-12)
first day of week, first week of year
Where appropriate this choice may also take into account the
value of the country
argument, though this
should not be used to override the
language or any sublanguage that is specified as part of the
language
argument.
The choice of the names and abbreviations used in any given
language is implementation-defined. For
example, one implementation might abbreviate July as
Jul
while another uses Jly
. In German,
one implementation might represent Saturday as Samstag
while another uses Sonnabend
. Implementations
may provide mechanisms allowing users to
control such choices.
Where ordinal numbers are used, the selection of the correct representation of the ordinal (for example, the linguistic gender) may depend on the component being formatted and on its textual context in the picture string.
The calendar
attribute specifies that the
dateTime
, date
, or time
supplied in the $value
argument must be converted to a value in the specified
calendar and then converted to a string using the conventions of
that calendar.
A calendar value must be a valid QName. If the QName does not have a prefix, then it identifies a calendar with the designator specified below. If the QName has a prefix, then the QName is expanded into an expanded-QName as described in 5.1 Qualified Names; the expanded-QName identifies the calendar; the behavior in this case is implementation-defined.
If the calendar attribute is omitted an implementation-defined value is used.
Note:
The calendars listed below were known to be in use during the last hundred years. Many other calendars have been used in the past.
This specification does not define any of these calendars, nor
the way that they map to the value space of the
xs:date
data type in [XML
Schema]. There may be ambiguities when dates are recorded
using different calendars. For example, the start of a new day is
not simultaneous in different calendars, and may also vary
geographically (for example, based on the time of sunrise or
sunset). Translation of dates is therefore more reliable when the
time of day is also known, and when the geographic location is
known. When translating dates between one calendar and another,
the processor may take account of the
values of the country
and/or language
arguments, with the country
argument taking
precedence.
Information about some of these calendars, and algorithms for converting between them, may be found in [Calendrical Calculations].
Designator | Calendar |
---|---|
AD | Anno Domini (Christian Era) |
AH | Anno Hegirae (Muhammedan Era) |
AME | Mauludi Era (solar years since Mohammed's birth) |
AM | Anno Mundi (Jewish Calendar) |
AP | Anno Persici |
AS | Aji Saka Era (Java) |
BE | Buddhist Era |
CB | Cooch Behar Era |
CE | Common Era |
CL | Chinese Lunar Era |
CS | Chula Sakarat Era |
EE | Ethiopian Era |
FE | Fasli Era |
ISO | ISO 8601 calendar |
JE | Japanese Calendar |
KE | Khalsa Era (Sikh calendar) |
KY | Kali Yuga |
ME | Malabar Era |
MS | Monarchic Solar Era |
NS | Nepal Samwat Era |
OS | Old Style (Julian Calendar) |
RS | Rattanakosin (Bangkok) Era |
SE | Saka Era |
SH | Mohammedan Solar Era (Iran) |
SS | Saka Samvat |
TE | Tripurabda Era |
VE | Vikrama Era |
VS | Vikrama Samvat Era |
At least one of the above calendars must be supported. It is implementation-defined which calendars are supported.
The ISO 8601 calendar ([ISO 8601]), which
is included in the above list and designated ISO
, is
essentially the same as the Gregorian calendar designated
AD
, but it prescribes the use of particular numbering
conventions as defined in ISO 8601, rather than allowing these to
be localized on a per-language basis. Specifically, in the ISO
calendar the days of the week are numbered from 1 (Monday) to 7
(Sunday), and week 1 in any calendar year is the week (from Monday
to Sunday) that includes the first Thursday of that year. The
numeric values of the components year, month, day, hour, minute,
and second are the same in this calendar as the values used in the
lexical representation of the date and time as defined in [XML Schema]. The ISO calendar is intended
primarily for applications that need to produce dates and times in
formats to be read by other software, rather than by human
users.
Note:
The value space of the date and time data types, as defined in
XML Schema, is based on absolute points in time. The lexical
space of these data types defines a representation of these
absolute points in time using the proleptic Gregorian calendar,
that is, the modern Western calendar extrapolated into the past
and the future; but the value space is calendar-neutral. The
date formatting functions
produce a representation of this absolute point in time, but
denoted in a possibly different calendar. So, for example, the
date whose lexical representation in XML Schema is
1502-01-11
(the day on which Pope Gregory XIII was
born) might be formatted using the Old Style (Julian) calendar as
1 January 1502
. This reflects the fact that there
was at that time a ten-day difference between the two calendars.
It would be incorrect, and would produce incorrect results, to
represent this date in an element or attribute of type
xs:date
as 1502-01-01
, even though this
might reflect the way the date was recorded in contemporary
documents.
The intended use of the country
argument is to
identify the place where an event represented by the
dateTime
, date
, or time
supplied in the $value
argument took place or will
take place. If the value is supplied, and is not the empty
sequence, then it should be a country
code defined in [ISO 3166-1].
Implementations may also allow the use of
codes representing subdivisions of a country from ISO 3166-2, or
codes representing formerly used names of countries from ISO
3166-3. This argument is not intended to identify the location of
the user for whom the date or time is being formatted; that should
be done by means of the language
attribute. This
information may be used to provide
additional information when converting dates between calendars or
when deciding how individual components of the date and time are to
be formatted. For example, different countries using the Old Style
(Julian) calendar started the new year on different days, and some
countries used variants of the calendar that were out of
sychronization as a result of differences in calculating leap
years. The geographical area identified by an ISO 3166-1 country
code is defined by the present-day boundaries of that country, not
by the boundaries as they existed historically.
The following examples show a selection of dates and times and the way they might be formatted. These examples assume the use of the Gregorian calendar as the default calendar.
Required Output | Expression |
---|---|
2002-12-31 |
format-date($d,
"[Y0001]-[M01]-[D01]") |
12-31-2002 |
format-date($d,
"[M]-[D]-[Y]") |
31-12-2002 |
format-date($d,
"[D]-[M]-[Y]") |
31 XII 2002 |
format-date($d, "[D1]
[MI] [Y]") |
31st December,
2002 |
format-date($d, "[D1o]
[MNn], [Y]", "en", (), ()) |
31 DEC 2002 |
format-date($d, "[D01]
[MN,*-3] [Y0001]", "en", (), ()) |
December 31,
2002 |
format-date($d, "[MNn]
[D], [Y]", "en", (), ()) |
31 Dezember,
2002 |
format-date($d, "[D]
[MNn], [Y]", "de", (), ()) |
Tisdag 31 December
2002 |
format-date($d, "[FNn]
[D] [MNn] [Y]", "sv", (), ()) |
[2002-12-31] |
format-date($d,
"[[[Y0001]-[M01]-[D01]]]") |
Two Thousand and
Three |
format-date($d, "[YWw]",
"en", (), ()) |
einunddreißigste
Dezember |
format-date($d, "[Dwo]
[MNn]", "de", (), ()) |
3:58 PM |
format-time($t,
"[h]:[m01] [PN]", "en", (), ()) |
3:58:45 pm |
format-time($t,
"[h]:[m01]:[s01] [Pn]", "en", (), ()) |
3:58:45 PM
PDT |
format-time($t,
"[h]:[m01]:[s01] [PN] [ZN,*-3]", "en", (), ()) |
3:58:45 o'clock PM
PDT |
format-time($t,
"[h]:[m01]:[s01] o'clock [PN] [ZN,*-3]", "en") |
15:58 |
format-time($t,"[H01]:[m01]") |
15:58:45.762 |
format-time($t,"[H01]:[m01]:[s01].[f001]") |
15:58:45
GMT+02:00 |
format-time($t,"[H01]:[m01]:[s01] [z]", "en", (),
()) |
15.58 Uhr
GMT+02:00 |
format-time($t,"[H01]:[m01] Uhr [z]", "de", (),
()) |
The following examples use calendars other than the Gregorian calendar.
These examples use non-Latin characters which might not display correctly in all browsers, depending on the system configuration.
Description | Request | Result |
---|---|---|
Islamic |
format-date($d, "[D١] [Mn]
[Y١]", "Islamic", "ar", "AH", ()) |
٢٦ ﺸﻭّﺍﻝ ١٤٢٣ |
Jewish (with Western numbering) |
format-date($d, "[D] [Mn] [Y]", "he", "AM",
()) |
26 טבת 5763 |
Jewish (with traditional numbering) |
format-date($d, "[Dאt] [Mn]
[Yאt]", "he", "AM", ()) |
כ״ו טבת תשס״ג |
Julian (Old Style) |
format-date($d, "[D] [MNn] [Y]", "en", "OS",
()) |
18 December 2002 |
Thai |
format-date($d, "[D๑] [Mn]
[Y๑]", "th", "BE", ()) |
๓๑ ธันวาคม ๒๕๔๕ |
current
() as
item()
The current
function, used within an XPath expression, returns the item that was the
context item at
the point where the expression was invoked from the XSLT stylesheet. This is referred
to as the current item. For an outermost expression (an expression
not occurring within another expression), the current item is
always the same as the context item. Thus,
<xsl:value-of select="current()"/>
means the same as
<xsl:value-of select="."/>
However, within square brackets, or on the right-hand side of
the /
operator, the current item is generally
different from the context item.
current
Function
For example,
<xsl:apply-templates select="//glossary/entry[@name=current()/@ref]"/>
will process all entry
elements that have a
glossary
parent element and that have a
name
attribute with value equal to the value of the
current item's ref
attribute. This is different
from
<xsl:apply-templates select="//glossary/entry[@name=./@ref]"/>
which means the same as
<xsl:apply-templates select="//glossary/entry[@name=@ref]"/>
and so would process all entry
elements that have
a glossary
parent element and that have a
name
attribute and a ref
attribute with
the same value.
If the current
function is used within a pattern, its value is the node that is being
matched against the pattern.
[ERR
XT1360] If the current
function is evaluated
within an expression that is evaluated when the context item is
undefined, a non-recoverable dynamic error
occurs.
unparsed-entity-uri
($entity-name
as
xs:string
) as
xs:string
The unparsed-entity-uri
function returns the URI of the unparsed entity whose name is given
by the value of the $entity-name
argument, in the
document containing the context node. It returns the zero-length
string if there is no such entity. This function maps to the
dm:unparsed-entity-system-id
accessor defined in
[Data Model].
[ERR
XT1370] It is a non-recoverable dynamic error
if the unparsed-entity-uri
is called when there is no context node, or when the root of the tree
containing the context node is not a document node.
unparsed-entity-public-id
($entity-name
as
xs:string
) as
xs:string
The unparsed-entity-public-id
function returns the public identifier of the unparsed entity whose
name is given by the value of the $entity-name
argument, in the document containing the context node. It returns the
zero-length string if there is no such entity, or if the
entity has no public identifier. This function maps to
the dm:unparsed-entity-public-id
accessor defined in
[Data Model].
[ERR
XT1380] It is a non-recoverable dynamic error
if the unparsed-entity-public-id
is called when there is no context node, or when the root of the tree
containing the context node is not a document node.
generate-id
() as
xs:string
generate-id
($node
as
node()?
) as
xs:string
The generate-id
function returns a string that uniquely identifies a given node.
The unique identifier must consist of
ASCII alphanumeric characters and must
start with an alphabetic character. Thus, the string is
syntactically an XML name. An implementation is free to generate an
identifier in any convenient way provided that it always generates
the same identifier for the same node and that different
identifiers are always generated from different nodes. An
implementation is under no obligation to generate the same
identifiers each time a document is transformed. There is no
guarantee that a generated unique identifier will be distinct from
any unique IDs specified in the source document. If the argument is
the empty sequence, the result is the zero-length
string. If the argument is omitted, it defaults to the
context
node.
system-property
($property-name
as
xs:string
) as
xs:string
The $property-name
argument must evaluate to a lexical QName. The lexical QName is expanded as described
in 5.1 Qualified Names.
[ERR XT1390] It is a non-recoverable dynamic error if the value is not a valid QName, or if there is no namespace declaration in scope for the prefix of the QName. The processor must signal these errors. If the processor is able to detect the error statically (for example, when the argument is supplied as a string literal), then the processor may optionally signal this as a static error.
The system-property
function returns a string representing the value of the system
property identified by the name. If there is no such system
property, the zero-length string is returned.
Implementations must provide the following system properties, which are all in the XSLT namespace:
xsl:version
, a number giving the version of
XSLT implemented by the processor; for implementations conforming
to the version of XSLT specified by this document, this is the
string "2.0"
. The value will always be a string in
the lexical space of the decimal data type defined in XML
Schema (see [XML Schema]) This allows
the value to be converted to a number for the purpose of
magnitude comparisons.
xsl:vendor
, a string identifying the
implementer of the processor
xsl:vendor-url
, a string containing a URL
identifying the implementer of the processor; typically this is the host page
(home page) of the implementer's Web site.
xsl:product-name
, a string containing the name
of the implementation, as defined by the implementer. This
should normally remain constant from
one release of the product to the next. It should also be constant across platforms in cases
where the same source code is used to produce compatible
products for multiple execution platforms.
xsl:product-version
, a string identifying the
version of the implementation, as defined by the implementer.
This should normally vary from one
release of the product to the next, and at the discretion of
the implementer it may also vary
across different execution platforms.
xsl:is-schema-aware
, returns the string
"yes"
in the case of a processor that claims
conformance as a schema-aware XSLT
processor, or "no"
in the case of a basic
XSLT processor.
xsl:supports-serialization
, returns the string
"yes"
in the case of a processor that offers the
serialization feature, or
"no"
otherwise.
xsl:supports-backwards-compatibility
, returns
the string "yes"
in the case of a processor that
offers the backwards compatibility
feature, or "no"
otherwise.
Some of these properties relate to the conformance levels and features offered by the processor: these options are described in 21 Conformance.
The actual values returned for the above properties are implementation-defined.
The set of system properties that are supported, in addition to those listed above, is also implementation-defined.
Note:
An implementation must not return
the value 2.0
as the value of the
xsl:version
system property unless it is conformant
to XSLT 2.0.
It is recognized that vendors who are enhancing XSLT 1.0
processors may wish to release interim implementations before all
the mandatory features of this specification are implemented.
Since such products are not conformant to XSLT 2.0, this
specification cannot define their behavior. However, implementers
of such products are encouraged to return a value for the
xsl:version
system property that is intermediate
between 1.0 and 2.0, and to provide the element-available
and function-available
functions to allow users to test which features have been fully
implemented.
Implementations must not define additional system properties in the XSLT namespace.
<!-- Category: instruction -->
<xsl:message
select? = expression
terminate? = { "yes" | "no" }>
<!-- Content: sequence-constructor
-->
</xsl:message>
The xsl:message
instruction sends a message in an implementation-defined way. The
xsl:message
instruction
causes the creation of a new document, which is typically serialized
and output to an implementation-defined destination.
The result of the xsl:message
instruction is an empty
sequence.
The content of the message may be specified by using either or both
of the optional select
attribute and the sequence
constructor that forms the content of the xsl:message
instruction.
If the xsl:message
instruction contains a sequence constructor, then the sequence
obtained by evaluating this sequence constructor is used to construct
the content of the new document node, as described in 5.6.1 Constructing Complex
Content.
If the xsl:message
instruction has a select
attribute, then the value of the
attribute must be an XPath expression. The
effect of the xsl:message
instruction is then the same as if a single xsl:copy-of
instruction with this
select
attribute were added to the start of the sequence
constructor.
If the xsl:message
instruction has no content and no select
attribute, then
an empty message is produced.
The tree produced by the xsl:message
instruction is not
technically a result tree. The tree has no URI and processors are not
required to make the tree accessible to
applications.
Note:
In many cases, the XML document produced using xsl:message
will consist of a
document node owning a single text node. However, it may contain a
more complex structure.
Note:
An implementation might implement xsl:message
by popping up an
alert box or by writing to a log file. Because the order of
execution of instructions is implementation-defined, the order in
which such messages appear is not predictable.
The terminate
attribute is interpreted as an attribute value template.
If the effective value of the terminate
attribute is yes
, then the processor must terminate
processing after sending the message. The default value is
no
. Note that because the order of evaluation of
instructions is implementation-dependent, this gives no guarantee that
any particular instruction will or will not be evaluated before
processing terminates.
One convenient way to do localization is to put the localized
information (message text, etc.) in an XML document, which becomes an
additional input file to the stylesheet. For example, suppose messages for a
language L
are stored in an XML file
resources/L.xml
in the form:
<messages> <message name="problem">A problem was detected.</message> <message name="error">An error was detected.</message> </messages>
Then a stylesheet could use the following approach to localize messages:
<xsl:param name="lang" select="'en'"/> <xsl:variable name="messages" select="document(concat('resources/', $lang, '.xml'))/messages"/> <xsl:template name="localized-message"> <xsl:param name="name"/> <xsl:message select="string($messages/message[@name=$name])"/> </xsl:template> <xsl:template name="problem"> <xsl:call-template name="localized-message"> <xsl:with-param name="name">problem</xsl:with-param> </xsl:call-template> </xsl:template>
XSLT allows two kinds of extension, extension instructions and extension functions.
[Definition: An extension instruction is an element within a sequence constructor that is in a namespace (not the XSLT namespace) designated as an extension namespace.]
[Definition: An extension function is a function
that is available for use within an XPath expression, other than a core function defined in
the XPath specification, an additional function defined in this XSLT
specification, or a stylesheet function defined using an
xsl:function
declaration.].
This specification does not define any mechanism for creating or binding implementations of extension instructions or extension functions, and it is not required that implementations support any such mechanism. Such mechanisms, if they exist, are implementation-defined. Therefore, an XSLT stylesheet that must be portable between XSLT implementations cannot rely on particular extensions being available. XSLT provides mechanisms that allow an XSLT stylesheet to determine whether the implementation makes particular extensions available, and to specify what happens if those extensions are not available. If an XSLT stylesheet is careful to make use of these mechanisms, it is possible for it to take advantage of extensions and still retain portability.
If the function name used in a FunctionCall XP within an XPath expression is not an NCName Names (that is, if it contains a colon), and if the stylesheet contains no stylesheet function with a matching expanded-QName, then it is treated as a call to an extension function. The QName used as the function name is expanded using the namespace declarations in scope at the point in the stylesheet where the expression appears.
The function-available
function can be used with the xsl:choose
and xsl:if
instructions to explicitly
control how a stylesheet behaves if a particular extension function
is not available.
function-available
($function-name
as
xs:string
) as
xs:boolean
A function name is said to be available if it matches the name of a core function defined in XPath, or the name of an additional function defined in this XSLT specification, or the name of a stylesheet function, or if the processor is able to locate an implementation of an extension function with a matching name.
The function-available
function returns true if the function name supplied as its
$function-name
argument is available; otherwise it
returns false.
The value of the $function-name
argument
must be a string containing a lexical QName. The
lexical QName is expanded into an expanded-QName using the namespace
declarations in scope for the expression. If the lexical QName is
unprefixed, then the standard function namespace
is used in the expanded QName. The function-available
function returns true if and only if the expanded-QName is the name of a
function in the function library. If the expanded-QName has a non-null
namespace URI, then it refers to a stylesheet function or extension
function; otherwise, it refers to a function defined by XPath
or XSLT.
[ERR XT1400] It is a recoverable dynamic error if the argument does not evaluate to a string that is a valid QName, or if there is no namespace declaration in scope for the prefix of the QName. The optional recovery action is to return the value false. If the processor is able to detect the error statically (for example, when the argument is supplied as a string literal), then the processor may optionally signal this as a static error.
Note:
The fact that a function with a given name is available gives no guarantee that any particular call on the function will be successful. For example, it is not possible to determine the number of arguments expected, nor their types.
[ERR XT1410] It is a non-recoverable dynamic error if a FunctionCall XP within an XPath expression is evaluated, when the function in question is not available. An implementation must not signal a static error merely because an expression contains a call to an extension function for which no implementation is available.
If the function name used in a FunctionCall XP within an XPath expression identifies an extension function, then to evaluate the FunctionCall XP, the processor will first evaluate each of the arguments in the FunctionCall XP. If the processor has information about the data types expected by the extension function, then it may perform any necessary type conversions between the XPath data types and those defined by the implementation language. If multiple extension functions are available with the same name, the processor may decide which one to invoke based on the number of arguments, the types of the arguments, or any other criteria. The result returned by the implementation is returned as the result of the function call, again after any necessary conversions between the data types of the implementation language and those of XPath. The details of such type conversions are outside the scope of this specification.
[ERR XT1420] It is a non-recoverable dynamic error if the arguments supplied to a call on an extension function do not satisfy the rules defined for that particular extension function, or if the extension function reports an error, or if the result of the extension function cannot be converted to an XPath value.
Note:
There is no prohibition on calling extension functions that have side-effects (for example, an extension function that writes data to a file). However, the order of execution of XSLT instructions is not defined in this specification, so the effects of such functions are unpredictable.
Implementations are not required to perform full validation of values returned by extension functions. It is an error for an extension function to return a string containing characters that are not permitted in XML, but the consequences of this error are implementation-defined. The implementation may raise an error, may convert the string to a string containing valid characters only, or may treat the invalid characters as if they were permitted characters.
Note:
The ability to execute extension functions represents a potential security weakness, since untrusted stylesheets may invoke code that has privileged access to resources on the machine where the processor executes. Implementations may therefore provide mechanisms that restrict the use of extension functions by untrusted stylesheets.
An implementation may allow an
extension function to return an object that does not have any
natural representation in the XPath data model, either as an atomic
value or as a node. For example, an extension function
sql:connect
might return an object that represents a
connection to a relational database; the resulting connection
object might be passed as an argument to calls on other extension
functions such as sql:insert
and
sql:select
.
The way in which such objects are represented in the type system
is implementation-defined. They might
be represented by a completely new data type, or they might be
mapped to existing data types such as integer
,
string
, or anyURI
.
[Definition: The extension instruction mechanism allows namespaces to be designated as extension namespaces. When a namespace is designated as an extension namespace and an element with a name from that namespace occurs in a sequence constructor, then the element is treated as an instruction rather than as a literal result element.] The namespace determines the semantics of the instruction.
Note:
Since an element that is a child of an xsl:stylesheet
element is
not occurring in a sequence constructor, user-defined
data elements (see 3.6.1
User-defined Data Elements) are not extension elements as
defined here, and nothing in this section applies to them.
A namespace is designated as an extension namespace by using an
[xsl:]extension-element-prefixes
attribute on an
element in the stylesheet (see 3.5 Standard Attributes). The
attribute must be in the XSLT namespace
only if its parent element is not in the XSLT namespace.
The value of the attributes is a whitespace-separated list of
namespace prefixes. The namespace bound to each of the prefixes is
designated as an extension namespace.
[ERR
XT1430] It is a static error if there is no namespace bound
to the prefix on the element bearing the
[xsl:]extension-element-prefixes
attribute. The
default namespace (as declared by xmlns
) may be
designated as an extension namespace by including
#default
in the list of namespace prefixes. The
designation of a namespace as an extension namespace is effective
for the element bearing the
[xsl:]extension-element-prefixes
attribute and for all
descendants of that element within the same stylesheet module.
The element-available
function can be used with the xsl:choose
and xsl:if
instructions to explicitly
control how a stylesheet behaves if a particular extension
instruction is not available.
element-available
($element-name
as
xs:string
) as
xs:boolean
The value of the $element-name
argument
must be a string containing a QName. The QName is expanded into an expanded-QName using the namespace
declarations in scope for the expression. If there is a default namespace in
scope, then it is used to expand an unprefixed QName. The element-available
function returns true if and only if the expanded-QName is the name of an
instruction. If
the expanded-QName has a namespace URI equal
to the XSLT
namespace URI, then it refers to an element defined by XSLT.
Otherwise, it refers to an extension instruction. If the
expanded-QName has a null namespace URI,
the element-available
function will return false.
[ERR XT1440] It is a recoverable dynamic error if the argument does not evaluate to a string that is a valid QName, or if there is no namespace declaration in scope for the prefix of the QName. The optional recovery action is to return the value false. If the processor is able to detect the error statically (for example, when the argument is supplied as a string literal), then the processor may optionally signal this as a static error.
If the processor
does not have an implementation of a particular extension
instruction available, then the element-available
function must return false for the name
of the element. When such an extension instruction is evaluated,
then the processor
must perform fallback for the element as
specified in 18.2.3 Fallback. An
implementation must not signal an error
merely because the stylesheet contains an extension instruction for
which no implementation is available.
If the processor
has an implementation of a particular extension
instruction available, then the element-available
function must return true for the name of
the element.
<!-- Category: instruction
-->
<xsl:fallback>
<!-- Content: sequence-constructor
-->
</xsl:fallback>
[ERR
XT1450] When a processor performs fallback for an instruction element, if
the instruction element has one or more xsl:fallback
children, then
the content of each of the xsl:fallback
children
must be evaluated; it is a non-recoverable dynamic error if it
has no xsl:fallback
children.
The content of an xsl:fallback
element is a
sequence constructor, and when
performing fallback, the value returned by the xsl:fallback
element is the
result of evaluating this sequence constructor.
When not performing fallback, evaluating an xsl:fallback
element returns
an empty sequence: the content of the xsl:fallback
element is
ignored.
There are two situations where a processor performs fallback: when an extension instruction that is not available is evaluated, and when an instruction in the XSLT namespace, that is not defined in XSLT 2.0, is evaluated within a region of the stylesheet for which forwards compatible behavior is enabled.
Note:
Fallback processing is not invoked in other situations, for
example it is not invoked when an XPath expression uses
unrecognized syntax or contains a call to an unknown function. To
handle such situations dynamically, the stylesheet should call functions such as system-property
and
function-available
to decide what capabilities are available.
The output of a transformation is a set of zero or more result trees.
A result tree may be created explicitly, by evaluating an xsl:result-document
instruction. A result tree is also created implicitly if the result of
evaluating the initial template is a non-empty sequence.
This implicit result tree is created as if the sequence
constructor contained in the initial template were contained in an
xsl:result-document
instruction with no attributes.
The way in which a result tree is delivered to an application is implementation-defined.
A result tree has a URI. If the implementation provides an API to access result trees, then it must allow a final result tree to be identified by means of this URI.
Note:
The URI of the result tree is not the same thing as the URI of its serialized representation on disk, if any. For example, a server (or browser client) might store the result trees only in memory, or in an internal disk cache. As long as it satisfies requests for those URIs, it is irrelevant where they are actually written on disk, if at all.
Note:
It will often be the case that one result tree contains links to another result tree produced during the same transformation, in the form of a relative URI. The mechanism of associating a URI with a final result tree has been chosen to allow the integrity of such links to be preserved when the trees are serialized.
Note:
The URI of a result tree is unrelated to the base URI of its document node.
Serialization of final result trees is described further in 20 Serialization
<!-- Category: instruction
-->
<xsl:result-document
format? = qname
href? = { uri-reference }
validation? = "strict" | "lax" | "preserve" |
"strip"
type? = qname>
<!-- Content: sequence-constructor
-->
</xsl:result-document>
The xsl:result-document
instruction is used to create a result tree. The content of the
xsl:result-document
element is a sequence constructor for the
children of the document node of the tree. A document node is
created, and the sequence obtained by evaluating the sequence
constructor is used to construct the content of the document, as
described in 5.6.1
Constructing Complex Content. The tree rooted at this
document node forms the result tree.
The xsl:result-document
instruction defines the URI of the result tree, and may optionally
specify the output format to be used for serializing this tree.
The value of the format
attribute, if specified,
must be a QName. The QName is expanded using the namespace declarations in
scope for the xsl:result-document
element. The expanded-QName must match the expanded QName of a named output
definition in the stylesheet. This identifies the xsl:output
declaration that will
control the serialization of the result tree (see 20 Serialization), if the result tree is
serialized. If the format
attribute is omitted, the
unnamed output definition is used to control
serialization of the result tree.
[ERR
XT1460] It is a static error if the value of the
format
attribute is not a valid QName, or if it does not
match the expanded-QName of an output
definition in the stylesheet.
The href
attribute is optional. The default value is
the zero-length string. The effective value of the attribute
must be a URI, which may be absolute or
relative. There may be implementation-defined restrictions
on the form of absolute URI that may be used, but the implementation
is not required to enforce any
restrictions. Any legal relative URI must
be accepted. Note that the zero-length string is a legal relative
URI.
If the effective value is a relative URI, then it is resolved relative to the base output URI.
The optional attributes type
and
validation
may be used on the xsl:result-document
instruction to validate the contents of the new document, and to
determine the type annotation that elements and attributes within the
result tree will carry. The permitted values and their semantics are
described in 19.2.2
Validating Document Nodes.
A processor
may allow a result tree to be serialized.
Serialization is described in 20
Serialization. However, an implementation (for example, a
processor running in an
environment with no access to writable filestore) is not required to support the serialization of result trees.
An implementation that does not support the serialization of result
trees may ignore the format
attribute. Such an implementation must
provide the application with some means of access to the
(un-serialized) result tree, optionally using its URI to identify
it.
Implementations may provide additional mechanisms, outside the
scope of this specification, for defining the way in which result
trees are processed. Such mechanisms may
make use of the XSLT-defined attributes on the xsl:result-document
and/or xsl:output
elements, or they may use additional
elements or attributes in an implementation-defined
namespace.
The following example takes an XHTML document as input, and
breaks it up so that the text following each <h1> element is
included in a separate document. A new document
toc.html
is constructed to act as an index:
<xsl:stylesheet version="2.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:xhtml="http://www.w3.org/1999/xhtml"> <xsl:output name="toc-format" method="xhtml" indent="yes" doctype-system="http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd" doctype-public="-//W3C//DTD XHTML 1.0 Strict//EN"/> <xsl:output name="section-format" method="xhtml" indent="no" doctype-system="http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" doctype-public="-//W3C//DTD XHTML 1.0 Transitional//EN"/> <xsl:template match="/"> <xsl:result-document href="toc.html" format="toc-format" validation="strict"> <html xmlns="http://www.w3.org/1999/xhtml"> <head><title>Table of Contents</title></head> <body> <h1>Table of Contents</h1> <xsl:for-each select="/*/xhtml:body/(*[1] | xhtml:h1)"> <p><a href="section{position()}.html"><xsl:value-of select="."/></a></p> </xsl:for-each> </body> </html> </xsl:result-document> <xsl:for-each-group select="/*/xhtml:body/*" group-starting-with="xhtml:h1"> <xsl:result-document href="section{position()}.html" format="section-format" validation="strip"> <html xmlns="http://www.w3.org/1999/xhtml"> <head><title><xsl:value-of select="."/></title></head> <body> <xsl:copy-of select="current-group()"/> </body> </html> </xsl:result-document> </xsl:for-each-group> </xsl:template> </xsl:stylesheet>
There are restrictions on the use of the xsl:result-document
instruction, designed to ensure that the results are fully
interoperable even when processors optimize the sequence in which
instructions are evaluated. Informally, the restriction is that the
xsl:result-document
instruction can only be used while writing a final result tree, not
while writing to a temporary tree or a sequence. This restriction is
defined formally as follows.
[Definition: Each instruction in the stylesheet is evaluated in one of two possible output states].
[Definition: The first of the two output states is called final output state. This state applies when instructions are writing to a final result tree.]
[Definition: The second of the two output states is called temporary output state. This state applies when instructions are writing to a temporary tree or any other non-final destination.]
The instructions in the initial template are evaluated in
final
output state . An instruction is evaluated in the same output state as its
calling instruction, except that xsl:variable
, xsl:param
, xsl:with-param
, xsl:attribute
, xsl:comment
, xsl:processing-instruction
,
xsl:namespace
,
xsl:value-of
,
xsl:function
, xsl:key
, xsl:sort
, and xsl:message
always evaluate the
instructions in their contained sequence constructor in temporary
output state.
[ERR
XT1480] It is a non-recoverable dynamic error to
evaluate the xsl:result-document
instruction in temporary output state.
[ERR XT1490] It is a non-recoverable dynamic error for a transformation to generate two or more result trees with the same URI.
Note:
Note, this means that it is an error to evaluate more than one
xsl:result-document
instruction that omits the href
attribute, or to
evaluate any xsl:result-document
instruction that omits the href
attribute if the
initial result tree is created implicitly.
Technically, the result of evaluating the xsl:result-document
instruction is an empty sequence. This means it does not contribute
any nodes to the result of the sequence constructor it
is part of.
[ERR XT1500] It is a recoverable dynamic error for a stylesheet to write to an external resource and read from the same resource during a single transformation, whether or not the same URI is used to access the resource in both cases. The optional recovery action is implementation-dependent: implementations are not obliged to detect the error condition.
It is possible to control the type annotation applied to
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
, xsl:copy-of
, and xsl:result-document
instructions, or the xsl:type
and
xsl:validation
attributes of a literal
result element.
The [xsl:]type
and [xsl:]validation
attributes are mutually exclusive. Both are optional, but if one is
present then the other must be omitted. If
both attributes are omitted, the effect is the same as specifying the
validation
attribute with the value specified in the
default-validation
attribute of the containing xsl:stylesheet
element; if
this is not specified, the effect is the same as specifying
validation="strip"
.
[ERR
XT1505] It is a static error if both the
[xsl:]type
and [xsl:]validation
attributes
are present on the xsl:element
, xsl:attribute
, xsl:copy
, xsl:copy-of
, or xsl:result-document
instructions, or on a literal result element.
The detailed rules for validation vary depending on the kind of node being validated. The rules for element and attribute nodes are given in 19.2.1 Validating Constructed Elements and Attributes, while those for document nodes are given in 19.2.2 Validating Document Nodes.
The [xsl:]validation
attribute defines the action
to be taken. It determines the type annotation not only of the node
that is constructed by the relevant instruction itself, but also
the type annotations of all element and attribute nodes that have
the constructed node as an ancestor. Conceptually, the validation
requested for a child element or attribute node is applied before
the validation requested for its parent element. For example, if
the instruction that constructs a child element specifies
validation="strict"
, this will cause the child element
to be checked against an element declaration, but if the
instruction that constructs its parent element specifies
validation="strip"
, then the final effect will be that
the child node is annotated as
xdt:untypedAny
.
In the paragraphs below, the term contained nodes means the elements and attributes that have the newly constructed node as an ancestor.
The value strip
indicates that the new node and
each of the contained nodes will have the type annotation
xdt:untypedAny
if it is an element,
or xdt:untypedAtomic
if it is an attribute. Any
previous type annotation present on a contained element or
attribute node (for example, a type annotation that is present
on an element copied from a source document) is discarded.
Schema validation is not invoked.
The value preserve
indicates that nodes that
are copied will retain their type annotations, but nodes whose
content is newly constructed will be annotated as
xdt:untypedAny
in the case of
elements, or xdt:untypedAtomic
in the case of
attributes. Schema validation is not invoked. The detailed
effect depends on the instruction:
In the case of xsl:element
and literal
result elements, the new element has a type annotation of
xdt:untypedAny
, and the type
annotations of contained nodes are retained unchanged.
In the case of xsl:attribute
, the
effect is exactly the same as specifying
validation="strip"
: that is, the new attribute
will have the type annotation
xdt:untypedAtomic
.
In the case of xsl:copy-of
, all the
nodes that are copied will retain their type annotations
unchanged. This option is permitted only if all
namespace nodes are retained.
In the case of xsl:copy
, the effect
depends on the kind of node being copied.
Where the node being copied is an attribute, the copied attribute will retain its type annotation.
Where the node being copied is an element, the
copied element will have a type annotation of
xdt:untypedAny
(because this
instruction does not copy the content of the element,
it would be wrong to assume that the type is
unchanged); but any contained nodes will have their
type annotations retained in the same way as with
xsl:element
.
The value strict
indicates that type
annotations are established by performing strict schema
validity assessment on the element or attribute node created by
this instruction as follows:
In the case of an element, an element declaration is
identified whose local name and namespace (if any) match
the name of the element, and schema-validity assessment is
carried out according to the rules defined in [XML Schema] (Part 1, section 3.3.4
"Element Declaration Validation Rules", validation rule
"Schema-Validity Assessment (Element)", clauses 1.1 and 2).
The element is considered valid if the result of the schema
validity assessment is a PSVI in which the relevant element
node has a validity
property whose value is
valid
. If the element is not considered valid,
the transformation fails. In effect this means that the
element being validated must be
declared using a top-level declaration in the schema, and
must conform to its declaration.
The process of validation applies recursively to contained
elements and attributes to the extent required by the
schema definition.
In the case of an attribute, an attribute declaration is
identified whose local name and namespace (if any) match
the name of the attribute, and schema-validity assessment
is carried out according to the rules defined in [XML Schema] (Part 1, section 3.2.4
"Attribute Declaration Validation Rules", validation rule
"Schema-Validity Assessment (Attribute)"). The attribute is
considered valid if the result of the schema validity
assessment is a PSVI in which the relevant attribute node
has a validity
property whose value is
valid
. If the attribute is not considered
valid, the transformation fails. In effect this means that
the attribute being validated must be declared using a top-level
declaration in the schema, and must conform to its declaration.
The schema components used to validate an element or
attribute may be located in any way permitted by [XML Schema] (see Part 1, section 4.3.2,
How schema documents are located on the Web). The
components in the schema constructed from the synthetic
schema document (see 3.13
Importing Schema Components) will always be
available for validating constructed nodes; if additional
schema components are needed, they may for example be located implicitly from
knowledge of the namespace in which the elements and
attributes appear, or they may be
located using the xsi:schemaLocation
attribute
of elements within the tree being validated.
If no validation is performed for a node, which can
happen when the schema specifies lax
or
skip
validation for that node or for a
subtree, then the node is annotated as
xdt:untypedAny
in the case of an
element, and xdt:untypedAtomic
in the case of
an attribute.
The value lax
has the same effect as the value
strict
, except that whereas strict
validation fails if the outcome of validity assessment is a
validity
property of invalid
or
notKnown
, lax
validation fails only
if the outcome of validity assessment is a
validity
property of invalid
. That
is, lax
validation does not cause a type error
when the outcome is notKnown
.
In practice this means that the element or attribute being
validated must conform to its
declaration if a top-level declaration is available. If no such
declaration is available, then the element or attribute is not
validated, but its attributes and children are validated, again
with lax validation. Any nodes whose validation outcome is a
validity
property of notKnown
are
annotated as xdt:untypedAny
in the
case of an element, and xdt:untypedAtomic
in the
case of an attribute.
[ERR
XT1510] If the validation
attribute of an
xsl:element
, xsl:attribute
, xsl:copy
, xsl:copy-of
, or xsl:result-document
instruction, or the xsl:validation
attribute of a
literal result element, has the effective value
strict
, and schema validity assessment concludes that
the validity of the element or attribute is invalid or unknown, 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.
[ERR
XT1515] If the validation
attribute of an
xsl:element
, xsl:attribute
, xsl:copy
, xsl:copy-of
, or xsl:result-document
instruction, or the xsl:validation
attribute of a
literal result element, has the effective value lax
,
and schema validity assessment concludes that the element or
attribute is invalid, 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:
No mechanism is provided to validate an element or attribute against a local declaration in a schema. Such validation can usually be achieved by applying validation to a containing element for which a top-level element declaration exists.
The [xsl:]type
attribute takes as its value a
QName
. This must be
the name of a type definition included in the in-scope schema components for
the stylesheet. If the QName has no prefix, it is expanded
using the default namespace established using the effective
[xsl:]xpath-default-namespace
attribute if there is
one; otherwise, it is taken as being a name in no namespace.
If the [xsl:]type
attribute is present, then the
newly constructed element or attribute is validated against the
type definition identified by this attribute.
In the case of an element, schema-validity assessment is
carried out according to the rules defined in [XML Schema] (Part 1, section 3.3.4 "Element
Declaration Validation Rules", validation rule "Schema-Validity
Assessment (Element)", clauses 1.2 and 2), using this type
definition as the "processor-stipulated type definition". The
element is considered valid if the result of the schema
validity assessment is a PSVI in which the relevant element
node has a validity
property whose value is
valid
.
In the case of an attribute, the attribute is considered
valid if (in the terminology of XML Schema) the attribute's
normalized value is locally valid with respect to that type
definition according to the rules for "String Valid" ([XML Schema], Part 1, section 3.14.4).
(Normalization here refers to the process of normalizing
whitespace according to the rules of the
whiteSpace
facet for the data type).
If the element or attribute is not considered valid, the transformation fails.
[ERR
XT1520] It is a static error if the value of the
type
attribute of an xsl:element
, xsl:attribute
, xsl:copy
, xsl:copy-of
, or xsl:result-document
instruction, or the xsl:type
attribute of a literal
result element, is not a valid QName
, or if it uses a
prefix that is not defined in an in-scope namespace declaration, or
if the QName is not the name of a type definition included in the
in-scope schema components for
the stylesheet.
[ERR
XT1530] It is a static error if the value of the
type
attribute of an xsl:attribute
instruction
refers to a complex type definition.
[ERR
XT1540] It is a type error if an [xsl:]type
attribute is defined for a constructed element or attribute, and
the outcome of schema validity assessment against that type is that
the validity
property of that element or attribute
information item is other than valid
.
Note:
Like other type errors, this error may be signaled statically if it can be detected
statically. For example, the instruction <xsl:attribute
name="dob"
type="xs:date">1999-02-29</xsl:attribute>
may result in a static error being
signaled. If the error is not signaled statically, it will be
signaled when the instruction is evaluated.
As well as checking for validity against the schema, the validity assessment process causes type annotations to be associated with element and attribute nodes. If default values for elements or attributes are defined in the schema, the validation process will where necessary create new nodes containing these default values.
Validation of an element or attribute node only takes into account constraints on the content of the element or attribute. Validation rules affecting the document as a whole are not applied. Specifically, this means:
The validation rule "Validation Root Valid (ID/IDREF)" is not applied. This means that validation will not fail if there are non-unique ID values or dangling IDREF values in the subtree being validated.
The validation rule "Validation Rule: Identity-constraint Satisfied" is not applied.
There is no check that the document contains unparsed
entities whose names match the values of nodes of type
xs:ENTITY
or xs:ENTITIES
. (XSLT 2.0
provides no facility to construct unparsed entities within a
tree.)
There is no check that the document contains notations whose
names match the values of nodes of type
xs:NOTATION
. (The XPath 2.0 data model makes no
provision for notations to be represented in the tree.)
With these caveats, validating a newly constructed element, using strict or lax validation, is equivalent to the following steps:
The element is serialized to textual XML form, according to the rules defined in [XSLT and XQuery Serialization] using the XML output method, with all parameters defaulted. Note that this process discards any existing type annotations.
The resulting XML document is parsed to create an XML Information Set (see [XML Information Set].)
The Information Set produced in the previous step is validated according to the rules in [XML Schema]. The result of this step is a Post-Schema Validation Infoset (PSVI). If the validation process is not successful (as defined above), a type error is raised.
The PSVI produced in the previous step is converted back into the XPath data model by the mapping described in [Data Model] (Section 3.3.1 Mapping PSVI Additions to TypesDM). This process creates nodes with simple or complex type annotations based on the types established during schema validation.
It is possible to apply validation to a document node. The circumstances under which this happens are as follows:
A result tree is constructed implicitly in the absence of
the xsl:result-document
instruction, and the default-validation
attribute
of the xsl:stylesheet
element
in the principal stylesheet
module requests validation.
A result tree is constructed using an xsl:result-document
instruction, and the validation
or
type
attribute is specified explicitly or
implicitly.
The xsl:copy
instruction is used when the context item is a document node,
and the validation
or type
attribute
is specified explicitly or implicitly.
One or more of the items selected by the xsl:copy-of
instruction is
a document node, and the validation
or
type
attribute is specified explicitly or
implicitly.
Validation is never applied to temporary trees, nor to document nodes
created using xsl:message
, even if the
default-validation
attribute of the containing
xsl:stylesheet
element requests validation. (This is equivalent to using
validation="preserve"
: nodes within temporary trees
retain their type annotation.)
The values validation="preserve"
and
validation="strip"
do not request validation. In the
first case, all element and attribute nodes within the tree rooted
at the new document node retain their type annotations. In the
second case, elements within the tree have their type annotation
set to xdt:untypedAny
, while attributes have their
type annotation set to xdt:untypedAtomic
.
When validation is requested for a document node (that is, when
validation
is set to strict
or
lax
, or when a type
attribute is
present), the following processing takes place:
[ERR XT1550] A type error occurs unless the children of the document node comprise exactly one element node, no text nodes, and zero or more comment and processing instruction nodes, in any order.
The single element node child is validated, using the
supplied values of the validation
and
type
attributes, as described in 19.2.1 Validating
Constructed Elements and Attributes.
Note:
The type
attribute on xsl:result-document
,
and on xsl:copy
and
xsl:copy-of
when
copying a document node, thus refers to the required type of
the element node that is the only element child of the
document node. It does not refer to the type of the document
node itself.
The validation rule "Validation Root Valid (ID/IDREF)" is applied to the single element node child of the document node. This means that validation will fail if there are non-unique ID values or dangling IDREF values in the document tree.
Identity constraints, as defined in section 3.11 of [XML Schema] Part 1, are checked. (This refers
to constraints defined using xs:unique
,
xs:key
, and xs:keyref
.)
There is no check that the tree contains unparsed entities
whose names match the values of nodes of type
xs:ENTITY
or xs:ENTITIES
. This is
because there is no facility in XSLT 2.0 to create unparsed
entities in a result tree. It is possible to add unparsed
entity declarations to the result document by referencing a
suitable DOCTYPE during serialization.
There is no check that the document contains notations whose
names match the values of nodes of type
xs:NOTATION
. This is because notations are not
part of the XPath 2.0 data model. It is possible to add
notations to the result document by referencing a suitable
DOCTYPE during serialization.
All other children of the document node (comments and processing instructions) are copied unchanged.
[ERR
XT1555] It is a type error if, when validating a document
node, document-level constraints are not satisfied. These
constraints include identity constraints (xs:unique
,
xs:key
, and xs:keyref
) and ID/IDREF
constraints.
A processor
may output a result tree as a sequence of
octets, although it is not required to be able to do so (see 21 Conformance). Stylesheet authors can use
the xsl:output
declaration
to specify how they wish result trees to be serialized. If a processor
serializes the result tree, it should do so
as specified by these elements; however, it is not required to do so.
The rules governing the output of the serializer are defined in
[XSLT and XQuery Serialization]. The
serialization is controlled using a number of serialization parameters.
The values of these serialization parameters may be set within the
stylesheet, using the
xsl:output
and xsl:character-map
declarations.
<!-- Category: declaration -->
<xsl:output
name? = qname
method? = "xml" | "html" | "xhtml" | "text" |
qname-but-not-ncname
cdata-section-elements? = qnames
doctype-public? = string
doctype-system? = string
encoding? = string
escape-uri-attributes? = "yes" | "no"
include-content-type? = "yes" | "no"
indent? = "yes" | "no"
media-type? = string
normalize-unicode? = "yes" | "no"
omit-xml-declaration? = "yes" | "no"
standalone? = "yes" | "no"
undeclare-namespaces? = "yes" | "no"
use-character-maps? = qnames
version? = nmtoken />
The xsl:output
declaration is optional; if used, it must
always appear as a top-level element within a stylesheet
module.
A stylesheet may
contain multiple xsl:output
declarations and may include or import stylesheet modules that also
contain xsl:output
declarations. The name of an xsl:output
declaration is the value
of its name
attribute, if any.
[Definition: All the xsl:output
declarations in a
stylesheet that share the same name are grouped into a named output
definition; those that have no name are grouped into a single
unnamed output definition.]
A named output definition is used when its name matches the
format
attribute used in an xsl:result-document
element. The unnamed output definition is used when an xsl:result-document
element
omits the format
attribute. It is also used when
serializing the result tree that is created implicitly in the absence
of an xsl:result-document
element.
All the xsl:output
elements making up an output definition are effectively merged. For the
cdata-section-elements
attribute, the output definition
uses the union of the values from all the constituent xsl:output
declarations. For
the use-character-maps
attribute, the output definition
uses the concatenation (space separated) of the values from all the
constituent xsl:output
declarations, taking them in order of increasing import precedence,
or where several have the same import precedence, in declaration
order. For other attributes, the output definition uses the
value of that attribute from the xsl:output
declaration with the
highest import precedence.
[ERR
XT1560] It is a static error if two xsl:output
declarations within an
output
definition specify explicit values for the same attribute (other
than cdata-section-elements
and
use-character-maps
), with the values of the attributes
being not equal, unless there is another xsl:output
declaration within the
same output
definition that has higher import precedence and that specifies an
explicit value for the same attribute.
The values of attributes are defaulted after the xsl:output
elements have been
merged; different output methods may have different default values for
an attribute.
An implementation may allow the attributes
of the xsl:output
declaration to be overridden, or the default values to be changed,
using the API that controls the transformation.
The location to which result trees are serialized (whether in
filestore or elsewhere) is implementation-defined (which in
practice may mean that it is controlled using
an implementation-defined API). However, these locations must satisfy the constraint that when two result trees
are both created (implicitly or explicitly) using relative URIs in the
href
attribute of the xsl:result-document
instruction, then these relative URIs may be used to construct
references from one tree to the other, and such references must remain valid when both result trees are
serialized.
The method
attribute on the xsl:output
element identifies the
overall method that is to be used for outputting the result tree.
[ERR
XT1570] The value must be a valid
QName. If the QName does not have a prefix, then it identifies a
method specified in [XSLT and XQuery
Serialization] and must be one of
xml
, html
, xhtml
, or
text
. If the QName
has a prefix, then the QName is
expanded into an expanded-QName as described in 5.1 Qualified Names; the expanded-QName identifies the output
method; the behavior in this case is not specified by this
document.
The default for the method
attribute is chosen as
follows. If the document node of the result tree has an element child,
and any text nodes preceding the first element child of the document
node of the result tree contain only whitespace characters, then:
If the expanded-QName of this first element child
has local part html
(in lower case), and namespace URI
http://www.w3.org/1999/xhtml
, then the default output
method is xhtml
.
If the expanded-QName of this first element child
has local part html
(in any combination of upper and
lower case) and a null namespace URI, then the default output
method is html
.
In all other cases, the default output method is
xml
.
The default output method is used if there are no xsl:output
elements or if none of
the xsl:output
elements
specifies a value for the method
attribute.
The other attributes on xsl:output
provide parameters for
the output method. The following attributes are allowed:
The value of the encoding
attribute provides the
value of the encoding
parameter to the serialization
method. The default value is implementation-defined, but
in the case of the xml
and xhtml
methods
it must be either UTF-8
or
UTF-16
.
The cdata-section-elements
attribute is a
space-separated list of QNames. After expansion of these names
using the in-scope namespace declarations for the xsl:output
declaration in which
they appear, this list of names provides the value of the
cdata-section-elements
parameter to the serialization
method. The default value is an empty list.
The value of the doctype-system
attribute provides
the value of the doctype-system
parameter to the
serialization method. By default, the parameter is not
supplied.
The value of the doctype-public
attribute provides
the value of the doctype-public
parameter to the
serialization method. By default, the parameter is not
supplied.
The value of the escape-uri-attributes
attribute
provides the value of the escape-uri-attributes
parameter to the serialization method. The default value is
yes
.
The value of the include-content-type
attribute
provides the value of the include-content-type
parameter to the serialization method. The default value is
yes
.
The value of the indent
attribute provides the
value of the indent
parameter to the serialization
method. The default value is yes
in the case of the
html
and xhtml
output methods,
no
in the case of the xml
output
method.
The value of the media-type
attribute provides the
value of the media-type
parameter to the serialization
method. The default value is text/xml
in the case of
the xml
output method, text/html
in the
case of the html
and xhtml
output
methods, and text/plain
in the case of the
text
output method.
The value of the normalize-unicode
attribute
provides the value of the normalize-unicode
parameter
to the serialization method. The default value is
no
.
The value of the omit-xml-declaration
attribute
provides the value of the omit-xml-declaration
parameter to the serialization method. The default value is
no
.
The value of the standalone
attribute provides the
value of the standalone
parameter to the serialization
method. By default, the parameter is not supplied; this means that
no standalone
attribute is included in the XML
declaration.
The undeclare-namespaces
attribute is relevant only
when producing output with method="xml"
and
version="1.1"
. It defines whether namespace
undeclarations (of the form xmlns:foo=""
) should be output when a child element has no
namespace node with the same name (that is, namespace prefix) as a
namespace node of its parent element. The default value is
no
: this means that namespace undeclarations are not
output, which has the effect that when the resulting XML is
reparsed, the new tree will contain namespace nodes on the child
element that were not there in the original tree before
serialization.
The use-character-maps
attribute provides a list of
named character maps that are used in conjunction with this output
definition. The way this attribute is used is described in 20.1 Character Maps.
The value of the version
attribute provides the
value of the version
parameter to the serialization
method. The default value depends on the output method: it is
1.0
for xml
, 4.01
for
html
, and 1.0
for xhtml
. The
parameter is not used by the text output method.
[Definition: A character map allows a specific character appearing in a text or attribute node in the result tree to be substituted by a specified string of characters during serialization.] The effect of character maps is defined in [XSLT and XQuery Serialization].
The character map that is supplied as a parameter to the
serializer is determined from the xsl:character-map
elements
referenced from the xsl:output
declaration for the
selected output definition.
The xsl:character-map
element
is a declaration that may appear as a child of the xsl:stylesheet
element.
<!-- Category: declaration
-->
<xsl:character-map
name = qname
use-character-maps? = qnames>
<!-- Content: (xsl:output-character*) -->
</xsl:character-map>
The xsl:character-map
declaration declares a character map with a name and a set of
character mappings. The character mappings are specified by means of
xsl:output-character
elements contained either directly within the xsl:character-map
element,
or in further character maps referenced in the
use-character-maps
attribute.
The required name
attribute
provides a name for the character map. When a character map is used
by an output definition or another character map, the character map
with the highest import precedence is used.
[ERR XT1580] It is a static error if the stylesheet contains two or more character maps with the same name and the same import precedence, unless it also contains another character map with the same name and higher import precedence.
The optional use-character-maps
attribute lists the
names of further character maps that are included into this character
map.
[ERR
XT1590] It is a static error if a name in the
use-character-maps
attribute does not match the
name
attribute of any xsl:character-map
in the
stylesheet.
[ERR
XT1600] It is a static error if a character map references
itself, directly or indirectly, via a name in the
use-character-maps
attribute.
It is not an error if the same character map is referenced more than once, directly or indirectly.
An output definition, after recursive expansion of character maps
referenced via its use-character-maps
attribute, may
contain several mappings for the same character. In this situation,
the last character mapping takes precedence. To establish the
ordering, the following rules are used:
Within a single xsl:character-map
element, the characters defined in character maps referenced in
the use-character-maps
attribute are considered
before the characters defined in the child xsl:output-character
elements.
The character maps referenced in a single
use-character-maps
attribute are considered in the
order in which they are listed in that attribute. The expansion
is depth-first: each referenced character map is fully expanded
before the next one is considered.
Two xsl:output-character
elements appearing as children of the same xsl:character-map
element are considered in document order.
The xsl:output-character
element is defined as follows:
<xsl:output-character
character = char
string = string />
The character map that is passed as a parameter to the serializer
contains a mapping for the character specified in the
character
attribute to the string specified in the
string
attribute.
Character mapping is not applied to characters for which output escaping has been disabled as described in 20.2 Disabling Output Escaping.
If a character is mapped, then it is not subjected to XML or HTML escaping.
Character maps can be useful when producing serialized output in a format that resembles, but is not strictly conformant to, HTML or XML. For example, when the output is a JSP page, there might be a need to generate the output:
<jsp:setProperty name="user" property="id" value='<%= "id" + idValue %>'/>
Although this output is not well-formed XML or HTML, it is valid
in Java Server Pages. This can be achieved by allocating three
Unicode characters (which are not needed for any other purpose) to
represent the strings <%
, %>
, and
"
, for example:
<xsl:character-map name="jsp"> <xsl:output-character char="«" string="<%"/> <xsl:output-character char="»" string="%>"/> <xsl:output-character char="§" string='"'/> </xsl:character-map>
When this character map is referenced in the xsl:output
declaration, the
required output can be produced by writing the following in the
stylesheet:
<jsp:setProperty name="user" property="id" value='«= §id§ + idValue »'/>
This works because the serialization specification requires that when an apostrophe or quotation mark is generated as part of an attribute value by the use of character maps, the serializer will (where possible) use the other choice of delimiter around the attribute value.
The following example illustrates a composite character map constructed in a modular fashion:
<xsl:output name="htmlDoc" use-character-maps="htmlDoc" /> <xsl:character-map name="htmlDoc" use-character-maps="html-chars doc-entities windows-format" /> <xsl:character-map name="html-chars" use-character-maps="latin1 ..." /> <xsl:character-map name="latin1"> <xsl:output-character character=" " string="&nbsp;" /> <xsl:output-character character="¡" string="&iexcl;" /> ... </xsl:character-map> <xsl:character-map name="doc-entities"> <xsl:output-character character="" string="&t-and-c;" /> <xsl:output-character character="" string="&chap1;" /> <xsl:output-character character="" string="&chap2;" /> ... </xsl:character-map> <xsl:character-map name="windows-format"> <!-- newlines as CRLF --> <xsl:output-character character="
" string="
" /> <!-- tabs as three spaces --> <xsl:output-character character="	" string=" " /> <!-- images for special characters --> <xsl:output-character character="" string="<img src='special1.gif' />" /> <xsl:output-character character="" string="<img src='special2.gif' />" /> ... </xsl:character-map>
Normally, when using the XML, HTML, or XHTML output method, the
serializer will escape special characters such as &
and <
when outputting text nodes. This ensures that
the output is well-formed. However, it is sometimes convenient to be
able to produce output that is almost, but not quite well-formed XML;
for example, the output may include ill-formed sections which are
intended to be transformed into well-formed XML by a subsequent
non-XML-aware process. For this reason, XSLT defines a mechanism for
disabling output escaping.
This is an optional feature: it is not required that a XSLT processor that implements the serialization option should offer the ability to disable output escaping, and there is no conformance level that requires this feature.
This feature requires an extension to the serializer described in
[XSLT and XQuery Serialization].
Conceptually, the result tree provides an additional boolean property
disable-escaping
associated with every character in a
text node. When this property is set, the normal action of the
serializer to escape special characters such as &
and <
is suppressed.
An xsl:value-of
or
xsl:text
element may have a
disable-output-escaping
attribute; the allowed values
are yes
or no
. The default is
no
; if the value is yes
, then every
character in the text node generated by evaluating the xsl:value-of
or xsl:text
element should have the disable-output
property
set.
For example,
<xsl:text disable-output-escaping="yes"><</xsl:text>
should generate the single character <
.
[ERR
XT1610] It is a recoverable dynamic error for output
escaping to be disabled for an xsl:value-of
or xsl:text
instruction that is used to
generate something other than a text node in the result tree. Thus,
it is an error to disable output escaping for an xsl:value-of
or xsl:text
element that is used to
generate the string
value of a comment, processing instruction or attribute node. The
optional recovery action is to
ignore disable-output-escaping
attribute.
If output escaping is disabled for text within an element that
would normally be output using a CDATA section, because the element
is listed in the cdata-section-elements
, then the
relevant text will not be included in a CDATA section. In effect,
CDATA is treated as an alternative escaping mechanism, which is
disabled by the disable-output-escaping
option.
For example, if <xsl:output
cdata-section-elements="title"/>
is specified, then the
following instructions:
<title> <xsl:text disable-output-escaping="yes">This is not <hr/> good coding practice</xsl:text> </title>
should generate the output:
<title><![CDATA[This is not ]]><hr/><![CDATA[ good coding practice]]></title>
The disable-output-escaping
attribute may be used
with the html
output method as well as with the
xml
output method. The text
output method
ignores the disable-output-escaping
attribute, since it
does not perform any output escaping.
A processor will only be able to disable output escaping if it controls how the result tree is output. This might not always be the case. For example, the result tree might be used as the source tree for another XSLT transformation instead of being output. It is implementation-defined whether (and under what circumstances) disabling output escaping is supported.
[ERR
XT1620] It is a recoverable dynamic error if an xsl:value-of
or xsl:text
instruction specifies that
output escaping is to be disabled and the implementation does not
support this. The optional recovery action is to
ignore the disable-output-escaping
attribute.
[ERR
XT1630] It is a recoverable dynamic error if an xsl:value-of
or xsl:text
instruction specifies that
output escaping is to be disabled when when writing to a result tree
that is not being serialized. The optional recovery action is
to ignore the disable-output-escaping
attribute.
In particular, it is implementation-defined what happens when output escaping is disabled for a text node that is written to a temporary tree rather than a final result tree. The implementation may retain the information that output escaping was disabled, and use it when the relevant node is subsequently copied to a final result tree, but it is not required to do so. The fact that output escaping was disabled is not represented explicitly in the data model, and must not affect the result of any expressions that access the temporary tree.
[ERR
XT1640] It is a recoverable dynamic error if output
escaping is disabled for a character that is not representable in the
encoding that the processor is using for output. The optional recovery action is to
ignore the disable-output-escaping
attribute.
Since disabling output escaping might not work with all implementations and can result in XML that is not well-formed, it should be used only when there is no alternative.
Note:
The facility to define character maps for use during serialization, as described in 20.1 Character Maps, has been produced as an alternative mechanism that can be used in many situations where disabling of output escaping was previously necessary, without the same difficulties.
A processor that claims conformance with this specification must claim conformance either as a basic XSLT processor or as a schema-aware XSLT processor. The rules for these two conformance levels are defined in the following sections.
A processor that claims conformance at either of these two levels may additionally claim conformance with either or both of the following optional features: the serialization feature, defined in 21.3 Serialization Feature, and the backwards compatibility feature, defined in 21.4 Backwards Compatibility Feature.
Note:
There is no conformance level or feature defined in this specification that requires implementation of the static typing features described in [XPath 2.0]. An XSLT processor may provide a user option to invoke static typing, but to be conformant with this specification it must allow a stylesheet to be processed with static typing disabled. The interaction of XSLT stylesheets with the static typing feature of XPath 2.0 has not been specified, so the results of using static typing, if available, are implementation-defined.
An XSLT processor takes as its inputs a stylesheet and one or more trees supplied as instances of the data model defined in [Data Model]. It is not required that the processor supports any particular method of constructing input data models, but conformance can only be tested if it provides a mechanism that enables data model instances representing the stylesheet and primary source document data model to be constructed and supplied as input to the processor.
The output of the XSLT processor consists of one or more trees. It is not required that the processor supports any particular method of accessing a result tree, but if it does not support the serialization module, conformance can only be tested if it provides some alternative mechanism that enables access to the results of the transformation.
Certain facilities in this specification are described as producing implementation-defined results. A claim that asserts conformance with this specification must be accompanied by documentation stating the effect of each implementation-defined feature. For convenience, a non-normative checklist of implementation-defined features is provided at F Checklist of Implementation-Defined Features.
A conforming processor must signal any static error occurring in the stylesheet, or in any XPath expression, except where specified otherwise either for individual error conditions or under the general provisions for forwards compatible behavior (see 3.9 Forwards-Compatible Processing). After signaling such an error, the processor may continue for the purpose of signaling additional errors, but must terminate abnormally without performing any transformation.
When a dynamic error occurs during the course of a transformation, the action depends on whether the error is classified as a recoverable error. If a non-recoverable error occurs, the processor must signal it and must eventually terminate abnormally. If a recoverable error occurs, the processor must either signal it and terminate abnormally, or it must take the defined recovery action and continue processing.
Some errors, notably type errors, may be treated as static errors or dynamic errors at the discretion of the processor.
A conforming processor may impose limits on the processing resources consumed by the processing of a stylesheet.
[Definition: A basic XSLT processor is an XSLT processor that implements all the mandatory requirements of this specification with the exception of certain explicitly-identified constructs related to schema processing.] These constructs are listed below.
The mandatory requirements of this specification are taken to include the mandatory requirements of XPath 2.0, as described in [XPath 2.0]. A requirement is mandatory unless the specification includes wording (such as the use of the words should or may) that clearly indicates that it is optional.
A basic XSLT processor must enforce the following restrictions. It must signal a static or dynamic error when the restriction is violated, as described below.
[ERR
XT1650] A basic XSLT processor must signal a static error if the stylesheet includes an xsl:import-schema
declaration.
Note:
Note that a processor that rejects an xsl:import-schema
declaration will also reject any reference to a user-defined type
defined in a schema, or to a user-defined element or attribute
declaration; it will not, however, reject references to the
built-in types listed in 3.12 Built-in
Types.
[ERR
XT1660] A basic XSLT processor must signal a static error if the stylesheet includes an
[xsl:]type
attribute, or an
[xsl:]validation
or default-validation
attribute with a value other than strip
.
A basic XSLT processor constrains the data model as follows:
Atomic values must belong to one of the following atomic types:
xs:string
xs:boolean
xs:decimal
xs:integer
xs:double
xs:date
xs:time
xs:dateTime
xs:QName
xs:anyURI
xdt:untypedAtomic
xdt:dayTimeDuration
xdt:yearMonthDuration
An atomic value may also belong to an implementation-defined type that has been added to the context for use with extension functions or extension instructions.
The static context, which defines the full set of type names
recognized by an XSLT processor and also by the XPath processor,
includes the types listed, plus xs:anyType
,
xs:anySimpleType
,
xdt:untypedAny
, and
xdt:anyAtomicType
.
The set of constructor functions available are limited to those that construct values of the above types.
Element nodes must be annotated with
the type annotation xdt:untypedAny
, and
attribute nodes with the type annotation
xdt:untypedAtomic
.
Note:
See however 4.4 Attributes Types and DTD Validation, which makes special provision for attributes defined in a DTD as being ID attributes.
[ERR
XT1665] A basic XSLT processor must raise a non-recoverable dynamic error if
the input to the processor includes a node with a type annotation
other than xdt:untypedAny
or
xdt:untypedAtomic
, or an atomic value of a type other
than those which a basic XSLT processor supports.
Note:
Although this is expressed in terms of a requirement to detect invalid input, an alternative approach is for a basic XSLT processor to prevent this error condition occurring, by not providing any interfaces that would allow the situation to arise. A processor might, for example, implement a mapping from the PSVI to the data model that loses all non-trivial type annotations; or it might not accept input from a PSVI at all.
The phrase input to the processor is deliberately wide:
it includes the tree containing the initial context node, trees
passed as stylesheet parameters, trees
accessed using the document
, doc
FO, and collection
FO functions, and trees returned by extension
functions and extension instructions.
[Definition: A schema-aware XSLT processor is an XSLT processor that implements all the mandatory requirements of this specification, including those features that a basic XSLT processor signals as an error. The mandatory requirements of this specification are taken to include the mandatory requirements of XPath 2.0, as described in [XPath 2.0]. A requirement is mandatory unless the specification includes wording (such as the use of the words should or may) that clearly indicates that it is optional.]
[Definition: A processor that claims conformance with
the serialization feature must
support the conversion of a result tree to a sequence of
octets following the rules defined in 20 Serialization.] It must respect all
the attributes of the xsl:output
and xsl:character-map
declarations, and must provide all four
output methods, xml
, xhtml
,
html
, and text
. Where the specification
uses words such as must and required, then it must
serialize the result tree in precisely the way described; in other
cases it may use an alternative, equivalent
representation.
A processor may claim conformance with the serialization feature
whether or not it supports the setting
disable-output-escaping="yes"
on xsl:text
, xsl:value-of
, or xsl:attribute
.
A processor that does not claim conformance with the serialization
feature must not signal an error merely
because the stylesheet contains xsl:output
or xsl:character-map
declarations; these declarations should be
ignored.
[Definition: A processor that claims conformance with the backwards compatibility feature must support the processing of stylesheet instructions and XPath expressions with backwards compatible behavior, as defined in 3.8 Backwards-Compatible Processing.]
[ERR
XT1670] A processor that does not claim conformance with
the backwards compatibility feature must
raise a non-recoverable dynamic error if an
instruction is evaluated containing an [xsl:]version
attribute that invokes backwards compatible behavior.
Note:
The reason this is a dynamic error rather than a static error is
to allow stylesheets to contain conditional logic, following
different paths depending on whether the XSLT processor implements
XSLT 1.0 or XSLT 2.0. The selection of which path to use can be
controlled by using the system-property
function to test the xsl:version
system property.
A processor that claims conformance with the backwards compatibility feature must permit the use of the namespace axis in XPath expressions when backwards compatible behavior is enabled. In all other circumstances, support for the namespace axis is optional.
This appendix registers a new MIME media type,
"application/xslt+xml
".
application
xslt+xml
None.
charset
This parameter has identical semantics to the
charset
parameter of the
application/xml
media type as specified in
[RFC3023].
By virtue of XSLT content being XML, it has the same
considerations when sent as "application/xslt+xml
"
as does XML. See RFC 3023, section 3.2.
Several XSLT instructions may cause arbitrary URIs to be dereferenced. In this case, the security issues of RFC1738, section 6, should be considered.
In addition, because of the extensibility features for XSLT,
it is possible that "application/xslt+xml
" may
describe content that has security implications beyond those
described here. However, if the processor follows only the
normative semantics of this specification, this content will be
ignored. Only in the case where the processor recognizes and
processes the additional content, or where further processing of
that content is dispatched to other processors, would security
issues potentially arise. And in that case, they would fall
outside the domain of this registration document.
This specification describes processing semantics that dictate behavior that must be followed when dealing with, among other things, unrecognized elements.
Because XSLT is extensible, conformant
"application/xslt+xml
" processors can expect that
content received is well-formed XML, but it cannot be guaranteed
that the content is valid XSLT or that the processor will
recognize all of the elements and attributes in the document.
This media type registration is for XSLT stylesheet modules as described by this specification.
Some authors have already started to write XSLT 2.0 documents.
However that content is currently most often described using the
unregistered media type "text/xslt
".
There is no experimental, vendor specific, or personal tree
predecessor to "application/xslt+xml
", reflecting
the fact that no applications currently recognize it. This new
type is being registered in order to allow for the expected
deployment of XSLT 2.0 on the World Wide Web, as a first class
XML application.
There is no single initial octet sequence that is always present in XSLT documents.
XSLT documents are most often identified with the
extensions ".xsl
" or ".xslt
".
TEXT
Norman Walsh, <Norman.Walsh@Sun.COM>
.
COMMON
The XSLT specification is a work product of the World Wide Web Consortium's XSL Working Group. The W3C has change control over these specifications.
A stylesheet can use the xsl:namespace-alias
element to declare that a literal namespace URI is being used
as an alias for a target namespace URI.
The arity of a stylesheet function is the number of
xsl:param
elements in the
function definition.
The term atomization is defined in Section 2.3.2 AtomizationXP. 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].
The xsl:attribute-set
element
defines a named attribute set: that is, a collection of
attribute definitions that can be used repeatedly on
different elements in the result tree.
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 brackets ({}
)
A processor that claims conformance with the backwards compatibility feature must support the processing of stylesheet instructions and XPath expressions with backwards compatible behavior, as defined in 3.8 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.5 Standard Attributes) whose
value is less than 2.0
.
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.
A basic XSLT processor is an XSLT processor that implements all the mandatory requirements of this specification with the exception of certain explicitly-identified constructs related to schema processing.
A character map allows