See also translations.
The following associated resources are available:
Copyright © 2013 W3C® (MIT, ERCIM, Keio, Beihang), All Rights Reserved. W3C liability, trademark and document use rules apply.
This specification defines the syntax and semantics of XSLT 3.0, a language for transforming XML documents into other XML documents.
XSLT 3.0 is a revised version of the XSLT 2.0 Recommendation [XSLT 2.0] published on 23 January 2007.
The primary purpose of the changes in this version of the language is to enable transformations to be performed in streaming mode, where neither the source document nor the result document is ever held in memory in its entirety. Another important aim is to improve the modularity of large stylesheets, allowing stylesheets to be developed from independently-developed components with a high level of software engineering robustness.
XSLT 3.0 is designed to be used in conjunction with XPath 3.0,
which is defined in [XPath 3.0]. XSLT
shares the same data model as XPath 3.0, which is defined in
[Data Model], and it uses the
library of functions and operators defined in [Functions and Operators]. XPath 3.0 and
the underlying function library introduce a number of enhancements,
for example the availability of higher-order functions. Some of the
functions that were previously defined in the XSLT 2.0
specification, such as the format-date
FO30
and
format-number
FO30 functions,
are now defined in the standard function library to make them
available to other host languages.
XSLT 3.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 XP30 for XPath 3.0, DM30 for the XDM data model version 3.0, FO30 for Functions and Operators version 3.0.
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 is a Last Call Working Draft as described in the W3C process document. It has been developed by the W3C XSLT Working Group, which is part of the XML Activity. Comments on this document will be formally accepted until 10 February 2014. The Working Group expects to advance this specification to Recommendation Status.
This specification has been developed in conjunction with [XPath 3.0] and other documents that underpin both XSLT and XQuery. XSLT 3.0 is dependent on XPath 3.0, which at the time of publication is a Proposed Recommendation.
In addition, this document specifies extensions to the XDM
data model and to XPath language syntax to underpin the
introduction of maps, which have been found necessary to support
some XSLT streaming use cases and make many other processing tasks
easier. This has involved extensive consultation with the XQuery
Working Group (which has joint responsibility for XDM and XPath),
and plans for incorporation of these extensions in a future version
of those specifications are well advanced. This has resulted in
some changes since the previous draft of July 2012: most notably,
the :=
separator in map expressions has changed to
:
, and collations as a property of a map have been
replaced by an alternative design using explicit collation
keys.
Changes since previous versions are listed in J Changes since XSLT 2.0 and K Changes since the Working Draft of 10 July 2012. The only incompatibilities with XSLT 2.0 relate to the way in which certain error conditions are handled: the details are given in L Incompatibilities with XSLT 2.0. The most significant changes since the previous working draft are the introduction of text value templates and static variables; the introduction of a family of URIs for collations conforming to the Unicode Collation Algorithm; extensive reworking of the syntax for patterns; changes to the way in which accumulator functions are invoked; and a substantial rewrite of the rules for assessing the streamability of stylesheet constructs such as template rules.
Please report errors in this document using W3C's public Bugzilla system (instructions can be found at http://www.w3.org/XML/2005/04/qt-bugzilla). If access to that system is not feasible, you may send your comments to the W3C XSLT/XPath/XQuery public comments mailing list, public-qt-comments@w3.org. It will be very helpful if you include the string "[XSLT30]" in the subject line of your report, whether made in Bugzilla or in email. Please use multiple Bugzilla entries (or, if necessary, multiple email messages) if you have more than one comment to make. Archives of the comments and responses are available at http://lists.w3.org/Archives/Public/public-qt-comments/.
A public test suite for XSLT 3.0 is under development. Implementors and others are encouraged to run these tests, to submit comments and contributions, and to report their results. The test suite is available at https://dvcs.w3.org/hg/xslt30-test/.
Publication as a Last Call 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.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
1 Introduction
1.1 What is
XSLT?
1.2 What's
New in XSLT 3.0?
2 Concepts
2.1 Terminology
2.2 Notation
2.3 Initiating a
Transformation
2.3.1 Information needed for Static
Analysis
2.3.2 Priming a Stylesheet
2.3.3 Invoking an Initial Mode
2.3.4 Invoking an Initial Template
2.3.5 Invoking an Initial Function
2.3.6 Post-processing the Raw Result
2.4 Executing a Transformation
2.5 The Evaluation
Context
2.6 Parsing and Serialization
2.7 Packages and Modules
2.8 Extensibility
2.9 Stylesheets and XML Schemas
2.10 Streaming
2.11 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 Packages
3.6.1 Dependencies between Packages
3.6.2 Named Components in Packages
3.6.2.1
Visibility of Components
3.6.2.2
Visibility of Declarations
3.6.2.3
Exposing Components
3.6.2.4
Accepting Components
3.6.2.5
Overriding Named
Components from a Used Package
3.6.2.6
Binding References to
Components
3.6.3 Overriding Template Rules from a Used
Package
3.6.4 Declarations Local to a
Package
3.6.5 Using an XQuery Library Package
3.7 Stylesheet Modules
3.8 Stylesheet Element
3.8.1 The default-collation
Attribute
3.8.2 The [xsl:]default-mode Attribute
3.8.3 User-defined Data Elements
3.9 Simplified Stylesheet Modules
3.10 Backwards
Compatible Processing
3.10.1 XSLT 1.0 Compatibility Mode
3.10.2 XSLT 2.0 Compatibility Mode
3.11 Forwards
Compatible Processing
3.12 Combining
Stylesheet Modules
3.12.1 Locating Stylesheet Modules
3.12.2 Stylesheet Inclusion
3.12.3 Stylesheet Import
3.13 Embedded
Stylesheet Modules
3.14 Conditional Element Inclusion
3.15 Built-in
Types
3.16 Importing
Schema Components
4 Data Model
4.1 XML
Versions
4.2 Stripping Whitespace from the
Stylesheet
4.3 Stripping Type Annotations from a Source
Tree
4.4 Stripping Whitespace
from a Source Tree
4.5 Attribute
Types and DTD Validation
4.6 Data
Model for Streaming
4.7 Limits
4.8 Disable
Output Escaping
5 Features of the XSLT Language
5.1 Qualified
Names
5.2 Unprefixed
Lexical QNames in Expressions and Patterns
5.3 Expressions
5.4 The Static and Dynamic
Context
5.4.1 Initializing the Static Context
5.4.2 Additional Static Context Components
used by XSLT
5.4.3 Initializing the Dynamic Context
5.4.3.1
Maintaining Position: the Focus
5.4.3.2
Other Components of the XPath Dynamic
Context
5.4.4 Additional Dynamic Context Components
used by XSLT
5.5 Defining a Decimal Format
5.6 Patterns
5.6.1 Examples of Patterns
5.6.2 Syntax of Patterns
5.6.3 The Meaning of a Pattern
5.6.4 Errors in Patterns
5.7 Value
Templates
5.7.1 Attribute Value Templates
5.7.2 Text Value Templates
5.8 Sequence Constructors
5.8.1 Constructing Complex
Content
5.8.2 Constructing Simple
Content
5.8.3 Namespace Fixup
5.9 URI
References
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 Default
Priority for Template Rules
6.6 Modes
6.6.1 Declaring Modes
6.6.2 Using Modes
6.6.3 Streamable Templates
6.7 Declaring the Context Item
6.7.1 Declaring the Initial Context Item for
a Mode
6.7.2 Declaring the context item for a
template
6.8 Built-in
Template Rules
6.8.1 Built-in Templates: Text-only
Copy
6.8.2 Built-in Templates: Deep
Copy
6.8.3 Built-in Templates: Shallow
Copy
6.8.4 Built-in Templates: Deep
Skip
6.8.5 Built-in Templates: Shallow
Skip
6.8.6 Built-in Templates: Fail
6.9 Overriding
Template Rules
6.10 Passing Parameters to Template
Rules
7 Repetition
7.1 The xsl:for-each
instruction
7.2 The xsl:iterate
Instruction
8 Conditional Processing
8.1 Conditional
Processing with xsl:if
8.2 Conditional
Processing with xsl:choose
8.3 Try/Catch
8.3.1 Try/Catch Examples
9 Variables and
Parameters
9.1 Variables
9.2 Parameters
9.3 Values of
Variables and Parameters
9.4 Creating
Implicit Document Nodes
9.5 Global
Variables and Parameters
9.6 Static
Variables and Parameters
9.7 Static
Expressions
9.8 Local
Variables and Parameters
9.9 Scope of
Variables
9.10 Setting
Parameter Values
9.11 Circular
Definitions
10 Callable Components
10.1 Named
Templates
10.1.1 Passing Parameters to Named
Templates
10.1.2 Tunnel Parameters
10.2 Named
Attribute Sets
10.2.1 Using Attribute Sets
10.2.2 Visibility of Attribute
Sets
10.2.3 Streamability of Attribute
Sets
10.2.4 Evaluating Attribute Sets
10.2.5 Attribute Sets: Examples
10.3 Stylesheet Functions
10.3.1 Function Name and Arity
10.3.2 Arguments
10.3.3 Function Result
10.3.4 Visibility and Overriding of
Functions
10.3.5 Dynamic Access to Functions
10.3.6 Determinism of Functions
10.3.7 Memoization
10.3.8 Examples of Stylesheet Functions
10.4 Dynamic XPath
Evaluation
10.4.1 Static context for the target
expression
10.4.2 Dynamic context for the target
expression
10.4.3 The effect of the xsl:evaluate
instruction
10.4.4 xsl:evaluate as an optional
feature
10.4.5 Examples of xsl:evaluate
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 Conditional Creation of
Literal Result Elements
11.1.5 Namespace Aliasing
11.2 Creating
Element Nodes Using xsl:element
11.2.1 The Content of the Constructed Element
Node
11.2.2 The Name of the Constructed Element
Node
11.2.3 Other Properties of the Constructed
Element Node
11.2.4 The Type Annotation of the
Constructed Element Node
11.2.5 Conditional Construction of Element
Nodes
11.3 Creating Attribute Nodes Using
xsl:attribute
11.3.1 Setting the Type Annotation
for a Constructed Attribute Node
11.3.2 Conditional Creation of Attribute
Nodes
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 Document Nodes
11.6 Creating Processing
Instructions
11.7 Creating Namespace Nodes
11.8 Creating
Comments
11.9 Copying
Nodes
11.9.1 Shallow Copy
11.9.1.1
Conditional Copying of Nodes
11.9.2 Deep Copy
11.10 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
13.4 The Unicode
Collation Algorithm
14 Grouping
14.1 The
xsl:for-each-group Element
14.2 Accessing Information about the Current
Group Value
14.2.1 fn:current-group
14.2.2 fn:current-grouping-key
14.3 Ordering
among Groups
14.4 Examples
of Grouping
14.5 Non-Transitivity
15 Merging
15.1 Terminology for Merging
15.2 The
xsl:merge Instruction
15.3 Selecting the Sequences to be
Merged
15.4 Streamable Merging
15.5 Defining the
Merge Keys
15.6 The
xsl:merge-action Element
15.7 Examples of
xsl:merge
16 Splitting
16.1 The
xsl:fork Instruction
16.2 Examples
of Splitting with Streamed Data
17 Regular Expressions
17.1 The
xsl:analyze-string Instruction
17.2 fn:regex-group
17.3 Examples of
Regular Expression Matching
18 Streaming
18.1 The
xsl:stream Instruction
18.1.1 Validation of Streamed Documents
18.1.2 Examples of xsl:stream
18.2 Accumulators
18.2.1 Declaring an Accumulator
18.2.2 Informal Model for
Accumulators
18.2.3 Formal Model for Accumulators
18.2.4 fn:accumulator-before
18.2.5 fn:accumulator-after
18.2.6 Visibility and Overriding
of Accumulators
18.2.7 Streamability of
Accumulators
18.2.8 Examples of Accumulators
18.3 fn:copy-of
18.4 fn:snapshot
19 Streamability
19.1 An
Optimization: Pattern-Based Scanning
19.2 Determining the Static Type of a
Construct
19.3 Determining the Context Item
Type
19.4 Operand
Roles
19.4.1 Examples showing the Effect of Operand
Usage
19.5 Determining the
Posture of a Construct
19.6 Determining the Context
Posture
19.7 The Sweep of a
Construct
19.8 Classifying Constructs
19.8.1 General Rules for
Streamability
19.8.2 Examples of the General
Streamability Rules
19.8.3 Classifying Sequence
Constructors
19.8.4 Classifying Instructions
19.8.4.1
Streamability of
Literal Result Elements
19.8.4.2
Streamability of
extension instructions
19.8.4.3
Streamability of
xsl:analyze-string
19.8.4.4
Streamability of
xsl:apply-imports
19.8.4.5
Streamability of
xsl:apply-templates
19.8.4.6
Streamability of
xsl:assert
19.8.4.7
Streamability of
xsl:attribute
19.8.4.8
Streamability of
xsl:break
19.8.4.9
Streamability of
xsl:call-template
19.8.4.10
Streamability of
xsl:choose
19.8.4.11
Streamability of
xsl:comment
19.8.4.12
Streamability of
xsl:copy
19.8.4.13
Streamability of
xsl:copy-of
19.8.4.14
Streamability of
xsl:document
19.8.4.15
Streamability of
xsl:element
19.8.4.16
Streamability of
xsl:evaluate
19.8.4.17
Streamability of
xsl:for-each
19.8.4.18
Streamability of
xsl:for-each-group
19.8.4.19
Streamability of
xsl:fork
19.8.4.20
Streamability of xsl:if
19.8.4.21
Streamability of
xsl:iterate
19.8.4.22
Streamability of xsl:map
19.8.4.23
Streamability of
xsl:map-entry
19.8.4.24
Streamability of
xsl:merge
19.8.4.25
Streamability of
xsl:message
19.8.4.26
Streamability of
xsl:namespace
19.8.4.27
Streamability of
xsl:next-iteration
19.8.4.28
Streamability of
xsl:next-match
19.8.4.29
Streamability of
xsl:number
19.8.4.30
Streamability of
xsl:perform-sort
19.8.4.31
Streamability
of xsl:processing-instruction
19.8.4.32
Streamability of
xsl:result-document
19.8.4.33
Streamability of
xsl:sequence
19.8.4.34
Streamability of
xsl:stream
19.8.4.35
Streamability of
xsl:text
19.8.4.36
Streamability of xsl:try
19.8.4.37
Streamability of
xsl:value-of
19.8.4.38
Streamability of
xsl:variable
19.8.5 Classifying Attribute Sets
19.8.6 Classifying Value Templates
19.8.7 Classifying Expressions
19.8.7.1
Streamability of for
expressions
19.8.7.2
Streamability of
Quantified Expressions
19.8.7.3
Streamability of if
expressions
19.8.7.4
Streamability of
union, intersect, and except expressions
19.8.7.5
Streamability of
Simple Mapping Expressions
19.8.7.6
Streamability of Path
Expressions
19.8.7.7
Streamability of Axis
Steps
19.8.7.8
Streamability of
Filter Expressions
19.8.7.9
Streamability of
Dynamic Function Calls
19.8.7.10
Streamability of
Variable References
19.8.7.11
Streamability
of the Context Item Expression
19.8.7.12
Streamability of
Function Calls
19.8.7.13
Streamability of
Named Function References
19.8.7.14
Streamability of
Inline Function Declarations
19.8.7.15
Streamability of map
expressions
19.8.8 Classifying Calls to Built-In
Functions
19.8.8.1
Streamability of the
accumulator-after function
19.8.8.2
Streamability of the
accumulator-before function
19.8.8.3
Streamability of the current
function
19.8.8.4
Streamability of the
current-group function
19.8.8.5
Streamability of
the current-grouping-key function
19.8.8.6
Streamability of the
function-lookup function
19.8.8.7
Streamability of the last
function
19.8.8.8
Streamability of the
outermost function
19.8.8.9
Streamability of the position
function
19.8.8.10
Streamability of the root
function
19.8.8.11
Streamability
of the unparsed-entity-public-id function
19.8.8.12
Streamability of
the unparsed-entity-uri function
19.8.9 Classifying Patterns
19.9 Examples of Streamability
Analysis
19.10 Streamability Guarantees
20 Additional Functions
20.1 fn:document
20.2 Keys
20.2.1 The xsl:key Declaration
20.2.2 fn:key
20.3 Miscellaneous
Additional Functions
20.3.1 fn:current
20.3.2 fn:unparsed-entity-uri
20.3.3 fn:unparsed-entity-public-id
20.3.4 fn:system-property
21 XPath Extensions
21.1 Maps
21.1.1 The Type of a Map
21.1.2 Functions that Operate on Maps
21.1.2.1
map:new
21.1.2.2
map:keys
21.1.2.3
map:contains
21.1.2.4
map:get
21.1.2.5
map:entry
21.1.2.6
map:remove
21.1.2.7
map:for-each-entry
21.1.2.8
fn:collation-key
21.1.2.10
fn:deep-equal
21.1.3 Map Instructions
21.1.4 Map Expressions
21.1.5 Maps and Streaming
21.1.6 Examples using Maps
21.2 Processing JSON
Data
21.2.1 XML Representation of JSON
21.2.2 fn:json-to-xml
21.2.3 Converting XML to JSON
22 Diagnostics
22.1 Messages
22.2 Assertions
23 Extensibility and Fallback
23.1 Extension Functions
23.1.1 fn:function-available
23.1.2 Calling Extension
Functions
23.1.3 External Objects
23.1.4 fn:type-available
23.2 Extension Instructions
23.2.1 Designating an Extension
Namespace
23.2.2 fn:element-available
23.2.3 Fallback
24 Final Result Trees
24.1 Creating Final Result Trees
24.2 Validation
24.2.1 Validating Constructed Elements and
Attributes
24.2.1.1
Validation using
the [xsl:]validation Attribute
24.2.1.2
Validation using the [xsl:]type
Attribute
24.2.1.3
The Validation Process
24.2.2 Validating Document Nodes
25 Serialization
25.1 Character
Maps
25.2 Disabling Output Escaping
26 Conformance
26.1 Basic
XSLT Processor
26.2 Schema-Awareness Conformance
Feature
26.3 Serialization Feature
26.4 Compatibility Features
26.5 Streaming
Feature
26.6 Dynamic Evaluation Feature
26.7 XQuery Invocation
Feature
A References
A.1 Normative References
A.2 Other
References
B XML Representation of JSON
B.1 Schema for
the XML Representation of JSON
B.2 Stylesheet for converting XML to JSON
(without indentation)
B.3 Stylesheet for converting XML to
JSON (with indentation)
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 List of XSLT-defined
functions (Non-Normative)
H Schema for XSLT Stylesheets
(Non-Normative)
I Acknowledgements
(Non-Normative)
J Changes since XSLT 2.0
(Non-Normative)
J.1 Changes in this Specification
J.2 Changes in Other Related
Specifications
K Changes since the Working
Draft of 10 July 2012 (Non-Normative)
L Incompatibilities with XSLT 2.0
(Non-Normative)
This specification defines the syntax and semantics of the XSLT 3.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 [Namespaces in XML].]
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-FO]), or into another presentation-oriented format such as HTML, XHTML, or SVG. However, XSLT is used for a wide range of transformation tasks, not exclusively for formatting and presentation applications.
A transformation expressed in XSLT describes rules for transforming zero 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. In many cases, evaluating the sequence constructor will cause new nodes to be constructed, which can be used 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.
Note:
The use of the term tree in this document does not imply the use of a data structure in memory that holds the entire contents of the document at one time. It implies rather a logical view of the XML input and output in which elements have a hierarchic relationship to each other. When a source document is being processed in a streaming manner, access to the nodes in this tree is constrained, but it is still viewed and described as a tree.
A stylesheet has a modular structure. It may consist of one or more packages developed independently of each other; each package defines the services (functions, templates, etc) that it exposes to its clients. Internally, a package may consist of a number of stylesheet modules.
[Definition: For a given transformation, one
stylesheet module 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.12.2 Stylesheet Inclusion and
3.12.3 Stylesheet Import.]
A major focus for enhancements in XSLT 3.0 is the requirement to enable streaming of source documents. This is needed when source documents become too large to hold in main memory, and also for applications where it is important to start delivering results before the entire source document is available.
While implementations of XSLT that use streaming have always been theoretically possible, the nature of the language has made it very difficult to achieve this in practice. The approach adopted in this specification is twofold: it identifies a set of restrictions which, if followed by stylesheet authors, will enable implementations to adopt a streaming mode of operation without placing excessive demands on the optimization capabilities of the processor; and it provides new constructs to indicate that streaming is required, or to express transformations in a way that makes it easier for the processor to adopt a streaming execution plan.
Capabilities provided in this category include:
A new xsl:stream
instruction, which reads and processes a source document in
streaming mode;
The ability to declare that a mode is a streaming mode, in which case all the template rules using that mode must be streamable;
A new xsl:iterate
instruction, which iterates over the items in a sequence, allowing
parameters for the processing of one item to be set during the
processing of the previous item;
A new xsl:merge
instruction, allowing multiple input streams to be merged into a
single output stream;
A new xsl:fork
instruction, allowing multiple computations to be performed in
parallel during a single pass through an input document.
Accumulators, which allow a value to be computed progressively during streamed processing of a document, and accessed as a function of a node in the document, without compromise to the functional nature of the XSLT language.
A second focus for enhancements in XSLT 3.0 is the introduction of a new mechanism for stylesheet modularity, called the package. Unlike the stylesheet modules of XSLT 1.0 and 2.0 (which remain available), a package defines an interface that regulates which functions, variables, templates and other components are visible outside the package, and which can be overridden. There are two main goals for this facility: it is designed to deliver software engineering benefits by improving the reusability and maintainability of code, and it is intended to streamline stylesheet deployment by allowing packages to be compiled independently of each other, and compiled instances of packages to be shared between multiple applications.
Other significant features in XSLT 3.0 include:
An xsl:evaluate
instruction allowing evaluation of XPath expressions that are
dynamically constructed as strings, or that are read from a source
document;
Enhancements to the syntax of patterns, in particular enabling the matching of atomic values as well as nodes;
An xsl:try
instruction
to allow recovery from dynamic errors;
The element xsl:context-item
, used to
declare the stylesheet's expectations of the initial context item
(notably, its type), given the initial mode.
A new instruction xsl:assert
to assist developers
in producing correct and robust code.
XSLT 3.0 also delivers enhancements made to the XPath language and to the standard function library, including the following:
Variables can now be bound in XPath using the let
expression.
Functions are now first class values, and can be passed as arguments to other (higher-order) functions, making XSLT a fully-fledged functional programming language.
A number of new functions are available, for example
trigonometric functions, and the functions parse-xml
FO30
and serialize
FO30
to convert between lexical and tree representations of XML.
This Working Draft includes support for maps (a data structure consisting of key/value pairs, sometimes referred to in other programming languages as dictionaries, hashes, or associative arrays). This feature extends the data model, provides new syntax in XPath, and adds a number of new functions and operators. The XSL Working Group intends that these changes should eventually become part of XPath: however, this has not yet been agreed with all interested parties.
A full list of changes is at J Changes since XSLT 2.0.
For a full glossary of terms, see C Glossary.
[Definition: The software responsible for transforming source trees into result trees using an XSLT stylesheet 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. ]
[Definition: The term result tree is used to refer to any tree constructed by instructions in the stylesheet. A result tree is either a final result tree or a temporary tree.]
[Definition: A final result tree is a result
tree that forms part of the final output of a transformation.
Once created, the contents of a final result tree are not
accessible within the stylesheet itself.] The xsl:result-document
instruction always creates a final result tree, and a final result
tree may also be created implicitly by the initial template. The conditions under
which this happens are described in 2.4 Executing a
Transformation. A final result tree may be serialized as described in 25 Serialization.
[Definition: The
term source tree means any tree provided as input to the
transformation. This includes the document containing the
initial context item if any,
documents containing nodes supplied as the values of stylesheet parameters, documents
obtained from the results of functions such as document
, doc
FO30,
and collection
FO30,
documents read using the xsl:stream
instruction,
and documents returned by extension functions or extension
instructions. In the context of a particular XSLT instruction, the
term source tree means any tree provided as input to that
instruction; this may be a source tree of the transformation as a
whole, or it may be a temporary tree produced during the
course of the transformation.]
[Definition: The term temporary tree means any tree that is neither a source tree nor a final result tree.] Temporary trees are used to hold intermediate results during the execution of the transformation.
The use of the term "tree" in phrases such as source tree, result tree, and temporary tree is not confined to documents that the processor materializes in memory in their entirety. The processor may, and in some cases must, use streaming techniques to limit the amount of memory used to hold source and result documents. When streaming is used, the nodes of the tree may never all be in memory at the same time, but at an abstract level the information is still modeled as a tree of nodes, and the document is therefore still described as a tree.
In this specification the phrases must, must not, should, should not, may, required, and recommended, when used in normative text and rendered in capitals, are to be interpreted as described in [rfc2119].
Where the phrase must, must not, or required 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 26 Conformance.
Where the phrase must, must not, or required relates to a stylesheet then the processor must enforce this constraint on stylesheets by reporting an error if the constraint is not satisfied.
Where the phrase should, should not, or recommended relates to a stylesheet then a processor may produce warning messages if the constraint is not satisfied, but must not treat this as an error.
[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 must be described in documentation that accompanies any conformance claim.]
[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 3.0] or the XDM specification [Data Model]. Particular attention is drawn to the following:
[Definition: The term atomization is defined in Section 2.4.2 Atomization XP30. It is a process that takes as input a sequence of items, and returns a sequence of atomic values, in which the nodes are replaced by their typed values as defined in [Data Model].] For some items (for example, elements with element-only content, and function items), atomization generates a dynamic error.
[Definition: The
term typed value is defined in Section
5.15 typed-value Accessor DM30. Every
node, other than an element whose type annotation identifies
it as having 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.13 string-value Accessor DM30. 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 Context XP30. 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 3.0 and XPath
1.0.]
[Definition: The term core function means a function that is specified in [Functions and Operators] and that is in the standard function namespace.]
[Definition: An XSLT element is an element in the XSLT namespace whose syntax and semantics are defined in this specification.] For a non-normative list of XSLT elements, see D Element Syntax Summary.
In this document the specification of each XSLT element 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.
An attribute that is deprecated is shown in a grayed font within square brackets.
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.
The types used are as follows:
Type name | Meaning |
---|---|
string | Any string |
expression | An XPath expression |
pattern | A pattern as described in 5.6 Patterns. |
sequence-type | A SequenceTypeXP30 as defined in the XPath specification |
uri; uris | A URI, for example a namespace URI or a collation URI; a whitespace-separated list of URIs |
qname | A lexical QName as defined in 5.1 Qualified Names |
eqname; eqnames | An EQName as defined in 5.1 Qualified Names; a whitespace-separated list of EQNames |
token; tokens | A string containing no significant whitespace; a whitespace-separated list of such strings |
nmtoken; nmtokens | A string conforming to the XML schema
rules for the type xs:NMTOKEN ; a whitespace-separated
list of such strings. |
char | A string comprising a single Unicode character |
integer | An integer, that is a string in the
lexical space of the schema type xs:integer |
decimal | A decimal value, that is a string in
the lexical space of the schema type xs:decimal |
ncname | An unprefixed name: a string in the
value space of the schema type xs:NCName |
prefix | An xs:NCName
representing a namespace prefix, which must be in scope for the
element on which it appears |
id | An xs:NCName used as a
unique identifier for an element in the containing XML
document |
Except where the set of allowed values of an attribute is specified using the italicized name string or char, 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 XTSE0010] It is a static error 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 XTSE0020] 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 XTDE0030] It is a 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. If the processor is able to detect the error statically (for example, when any XPath expressions within the curly brackets can be evaluated statically), then the processor may optionally signal this as a static error.
Special rules apply if the construct appears in part of the stylesheet that is processed with forwards compatible behavior: see 3.11 Forwards Compatible Processing.
[Definition: Some constructs defined in this specification are described as being deprecated. The use of this term implies that stylesheet authors should not use the construct, and that the construct may be removed in a later version of this specification.]
Note:
This working draft includes a non-normative XML Schema for XSLT stylesheet modules (see H 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]. A list of these functions appears in G List of XSLT-defined functions. The signatures of these functions are described using the same notation as used in [Functions and Operators]. The names of many of these functions are 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 is supplied when a transformation is initiated. Except where otherwise indicated, the information is required.
The execution of a stylesheet necessarily involves two
activities: static analysis and dynamic evaluation. Static analysis
consists of those tasks that can be performed by inspection of the
stylesheet alone, including the binding of static
variables, the evaluation of [xsl:]use-when
expressions (see 3.14
Conditional Element Inclusion), and detection of static
errors. Dynamic evaluation consists of tasks which in general
cannot be carried out until a source document is available.
Dynamic evaluation is further divided into two activities: priming the stylesheet, and invoking a selected component.
Priming the stylesheet provides the dynamic context for evaluation, and supplies all the information needed to establish the values of global variables.
Invoking a component (such as a template or function) causes evaluation of that template or function to produce a result, which is an arbitrary XDM value.
[Definition: The result of invoking the selected component, after any required conversion to the declared result type of the component, is referred to as the raw result.]
This raw result may optionally be post-processed to construct a result tree, to serialize the result, or both, as described in 2.3.6 Post-processing the Raw Result.
Implementations may allow static analysis and dynamic evaluation to be initiated independently, so that the cost of static analysis can be amortized over multiple transformations using the same stylesheet. Implementations may also allow priming of a stylesheet and invocation of components to be initiated independently, in which case a single act of priming the stylesheet may be followed by a series of independent component invocations. Although this specification does not require such a separation, this section distinguishes information that is needed before static analysis can proceed, information that is needed to prime the stylesheet, and information that is needed when invoking components.
The language is designed to allow the static analysis of each package to be performed independently of other packages, with only basic knowledge of the properties of components made available by used packages. Beyond this, the specification leaves it to implementations to decide how to organize this process. When packages are not used explicitly, the entire stylesheet is treated as a single package.
The following information is needed prior to static analysis of a package:
The location of the package manifest, or in the absence
of a package manifest, the stylesheet module that
is to act as the principal
stylesheet module for the transformation. The complete
package
is assembled by recursively expanding the xsl:import
and xsl:include
declarations in the
principal stylesheet module, as described in 3.12.2 Stylesheet Inclusion and 3.12.3 Stylesheet Import.
Information about the packages referenced from this package
using xsl:use-package
declarations. The information needed will include the names and
signatures of public components exported by the referenced
package.
A set (possibly empty) of values for static parameters
(see 9.5 Global Variables and
Parameters). These values are available for use within
static expressions (notably
[xsl:]use-when
expressions) as well as non-static
expressions in the stylesheet. As a minimum, values must be supplied for any static parameters declared
with the attribute required="yes"
.
Conceptually, the output of the static analysis of a package is an object which might be referred to (without constraining the implementation) as a compiled package. Prior to dynamic evaluation, all the compiled packages needed for execution must be checked for consistency, and component references must be resolved. This process may be referred to, again without constraining the implementation, as linking.
The information needed when priming a stylesheet is as follows:
A set (possibly empty) of values for non-static
stylesheet parameters (see 9.5 Global Variables and
Parameters). These values are available for use within
expressions in the stylesheet. As a minimum,
values must be supplied for any
parameters declared with the attribute
required="yes"
.
A supplied value is converted if necessary to the declared type of the stylesheet parameter using the function conversion rules.
Note:
It is possible for static stylesheet parameters to be declared in any package, and stylesheet parameters in different packages might have the same name.
[Definition: An item that acts as the initial
context item for the transformation. This item is accessible
within the stylesheet as the initial value of the XPath
expressions .
(dot) and
self::node()
, as described in 5.4.3.1 Maintaining Position: the Focus
].
The initial context item is potentially
used when initializing global variables and parameters. If the
initialization of any global variables or parameter depends on the context
item, a dynamic error can occur if the context item is absent. It
is implementation-defined whether
this error occurs during priming of the stylesheet or subsequently
when the variable is referenced; and it is implementation-defined whether the
error occurs at all if the variable or parameter is never
referenced. The error can be suppressed by use of xsl:try
and xsl:catch
within the
initialization of the variable or parameter.
If no initial context item is supplied, then the context item, context position, and context size will initially be absent, 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 item is supplied, and will be absent if no initial context item is supplied).
A base output URI. [Definition: The base output URI is a URI to be used as the base URI when resolving a relative URI reference allocated to a final result tree. If the transformation generates more than one final result tree, then typically each one will be allocated a URI relative to this base URI. ] The way in which a base output URI is established is implementation-defined.
A mechanism for obtaining a document node and a media type,
given an absolute URI. The total set of available documents
(modeled as a mapping from URIs to document nodes) forms part of
the context for evaluating XPath expressions, specifically the
doc
FO30
function. The XSLT document
function additionally
requires the media type of the resource representation, for use in
interpreting any fragment identifier present within a URI
Reference.
Note:
The set of documents that are available to the stylesheet is implementation-dependent, as is the processing that is carried out to construct a tree representing the resource retrieved using a given URI. Some possible ways of constructing a document (specifically, rules for constructing a document from an Infoset or from a PSVI) are described in [Data Model].
Once a stylesheet is primed, the values of global variables
remain stable through all component invocations. In addition,
priming a stylesheet creates an execution
scopeFO30 during which the dynamic
context and all function calls remain stable; for example two calls
on the
current-dateTime
FO30 function
within an execution scope are defined to return the same
result.
Parameters passed to the transformation by the client application when a stylesheet is primed are matched against stylesheet parameters (see 9.5 Global Variables and Parameters), not against the template parameters declared within the initial template.
[ERR XTDE0050] It is a dynamic error if a
stylesheet declares a visible stylesheet
parameter with required="yes"
and no value for
this parameter is supplied when the stylesheet is primed. A
stylesheet parameter is visible if it is not masked by another
global variable or parameter with the same name and higher
import precedence. If the
parameter is a static parameter then the value
must be supplied prior to the static
analysis phase.
When the stylesheet is evaluated by invoking a mode, processing proceeds by finding the template rules that match the items in a supplied input sequence, and evaluating these template rules with a focus based on this input sequence.
The following information is needed when dynamic evaluation is to start with a template rule:
Optionally, a sequence of items to be processed. If no input sequence is supplied explicitly, this defaults to a singleton sequence containing the initial context item.
Note:
In earlier versions of this specification, the initial input sequence (to which templates are applied) was always the same as the initial context item (used for computing the values of global variables), and since this is the most common scenario, it is likely to affect the design of APIs.
Optionally, an initial mode.
[Definition: The
initial mode, if specified, must either
be the default mode, or a mode that is explicitly named
either in an xsl:mode
declaration, or in
the mode
attribute of an xsl:template
declaration
within the stylesheet. If an initial mode is supplied, then in
searching for the template rule that best matches the
initial context item, the
processor considers only those rules that apply to the initial
mode. If no initial mode is supplied, then the mode used is that
named in the default-mode
attribute of the
xsl:stylesheet
element of the principal
stylesheet module; or failing that, the mode named in the
default-mode
attribute of its containing xsl:package
element; or
in the absence of such an attribute, the unnamed
mode.]
Parameters, which will be passed to the template rules used to
process items in the input sequence. The parameters consist of two
sets of (QName, value) pairs, one set for tunnel parameters and one for non-tunnel
parameters, in which the QName identifies the name of a parameter
and the value provides the value of the parameter. Either or both
sets of parameters may be empty. The effect is the same as when a
template is invoked using xsl:apply-templates
with an xsl:with-param
child
specifying tunnel="yes"
or tunnel="no"
as
appropriate. If a parameter is supplied that is not declared or
used, the value is simply ignored. These parameters are
not used to set stylesheet
parameters.
A supplied value is converted if necessary to the declared type of the template parameter using the function conversion rules.
The raw result of the invocation is the result of
processing the supplied input sequence as if by a call on xsl:apply-templates
in
the specified mode: specifically, each item in the input sequence
is processed by selecting and evaluating the best matching template
rule, and converting the result (if necessary) to the type declared
in the as
attribute of that template using the
function conversion rules; and
the results of processing each item are then concatenated into a
single sequence, respecting the order of items in the input
sequence.
Note:
If the initial mode is a streamable mode, then streaming will only be possible if nodes in the input sequence are supplied in a form that allows such processing: for example, as a reference to a stream of parsing events.
Note:
The design of the API for invoking a transformation should provide some means for users to designate the unnamed mode as the initial mode in cases where it is not the default mode.
[ERR XTDE0044] It is a dynamic error if the invocation of the stylesheet specifies an initial mode and if no input sequence is supplied (either explicitly, or defaulted to the initial context item).
[ERR XTDE0045] It is a dynamic error if the
invocation of the stylesheet specifies an initial mode (other than the
unnamed mode) that does not match either the expanded
QName in the name
attribute of an xsl:mode
declaration, or
the expanded QName in the mode
attribute of any template defined in the stylesheet.
Note:
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
20.1 fn:document) or doc
FO30
or collection
FO30
(see [Functions and Operators]),
or using the xsl:stream
instruction;
alternatively, they can be supplied as stylesheet parameters (see 9.5 Global Variables and
Parameters), or returned as the result of an extension function (see 23.1 Extension Functions).
The following additional information is needed when dynamic evaluation is to start with a named template:
Optionally, the name of a named template which is to
be executed as the entry point to the transformation. If no
template name is supplied, the default template name is
xsl:initial-template
. The selected template
must exist within the stylesheet.
Optionally, a context item for evaluation of this named template, defaulting to the initial context item if it exists.
Parameters, which will be passed to the selected template rule.
The parameters consist of two sets of (QName, value) pairs, one set
for tunnel parameters and one for non-tunnel
parameters, in which the QName identifies the name of a parameter
and the value provides the value of the parameter. Either or both
sets of parameters may be empty. The effect is the same as when a
template is invoked using xsl:call-template
with an
xsl:with-param
child
specifying tunnel="yes"
or tunnel="no"
as
appropriate. If a parameter is supplied that is not declared or
used, the value is simply ignored. These parameters are
not used to set stylesheet
parameters.
A supplied value is converted if necessary to the declared type of the template parameter using the function conversion rules.
The raw result of the invocation is the result of
evaluating the initial template, after conversion of the result to
the type declared in the as
attribute of that template
using the function conversion rules,
if such conversion is necessary.
[ERR XTDE0040] It is a dynamic error if the
invocation of the stylesheet specifies a template name that does
not match the expanded QName of a named template defined
in the stylesheet, whose visibility is
public
or final
.
[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 item in the
initial mode.]
It is a dynamic error [see
ERR XTDE0060] if the initial template defines a template parameter that specifies
required="yes"
and no value is supplied for that
parameter.
The following additional information is needed when dynamic evaluation is to start with a stylesheet function
The name and arity of a stylesheet function which is to be executed as the entry point to the transformation.
Note:
In the design of a concrete API, the arity may be inferred from the length of the parameter list.
A list of values to act as parameters to the initial function. The number of values in the list must be the same as the arity of the function.
A supplied value is converted if necessary to the declared type of the stylesheet parameter using the function conversion rules.
The raw result of the invocation is the result of
evaluating the initial function, after conversion of the result to
the type declared in the as
attribute of that function
using the function conversion rules,
if such conversion is necessary.
[ERR XTDE0041] It is a dynamic error if the
invocation of the stylesheet specifies a function name and arity
that does not match the expanded QName and arity of a named
stylesheet function defined in the
stylesheet, whose visibility is
public
or final
.
[Definition: The transformation is performed by evaluating an initial function. ]
[ERR XTDE0060] It is a dynamic error if the
initial template defines a template parameter that specifies
required="yes"
.
At user option, the raw result of a component invocation may either be returned to the calling application unchanged, or it may be post-processed. Two stages of post-processing are defined, both of which are optional:
Result tree construction
If the raw result is non-empty, then it is used to construct an implicit final result tree, following the rules described in 5.8.1 Constructing Complex Content: the effect is as if the raw result R were processed by the following function:
<xsl:function name="construct-result-tree" as="document-node()"> <xsl:param name="R" as="item()*"> <xsl:document validation="preserve"> <xsl:sequence select="$R"/> </xsl:document> </xsl:function>
An implicit result tree is also created when the raw result is
empty, provided that no xsl:result-document
instruction has been evaluated during the course of the
transformation. In this situation the implicit result tree will
consist of a document node with no children.
Note:
This means that there is always at least one result tree. It
also means that if the content of the initial template is a single
xsl:result-document
instruction, as in the example above, then only one result tree is
produced, not two. It is useful to make the result document
explicit as this is a convenient way of invoking document-level
validation. (Validation of the implicit result document can also be
achieved by adding an xsl:document
instruction to
the initial template.)
If the result of the initial template is non-empty, and an
explicit xsl:result-document
instruction has been evaluated with the empty attribute
href=""
, then an error will occur [see ERR XTDE1490],
since it is not possible to create two final result trees with the
same URI.
Serialization
See 2.6 Parsing and Serialization.
Either the raw result, or a result tree produced as described above, may optionally be serialized as decribed in [serialization].
Note:
The first phase of serialization, called sequence
normalization, has no effect if the supplied value is a single
document node, which will be the case if serialization is preceded
by result tree construction. In the case of any other supplied
value, the effect of sequence normalization is very similar to the
effect of result tree construction, except where an
item-separator
serialization parameter is present. Use
of item-separator
allows, for example, a sequence of
strings returned by invoking a stylesheet function to be output
with newline separators.
Note:
This specification does not constrain the design of application programming interfaces or the choice of defaults. In previous versions of this specification, result tree construction was a mandatory process, while serialization was optional. When invoking stylesheet functions directly, however, result tree construction and serialization may be inappropriate as defaults. These considerations may affect the design of APIs.
The classic method of executing an XSLT transformation is to apply template rules to an input document, delivering the result as a result tree which is then optionally serialized. This processing model is described in this section. Other ways of invoking a transformation or processing the result are outlined in the previous section.
[Definition: A stylesheet contains a set of template rules (see 6 Template Rules). A template rule has three parts: a pattern that is matched against nodes, a (possibly empty) set of template parameters, and a sequence constructor that is evaluated to produce a sequence of items.] In many cases these items are newly constructed 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.8 Sequence Constructors.
The result sequence produced by evaluating the initial template is handled as follows:
If the initial template has an as
attribute, then
the result sequence of the initial template is checked against the
required type in the same way as for any other template.
If the result sequence is non-empty, then it is typically used to construct an implicit final result tree, following the rules described in 5.8.1 Constructing Complex Content: the effect is as if the initial template T were called by an implicit template of the form:
<xsl:template name="IMPLICIT"> <xsl:result-document href=""> <xsl:call-template name="T"/> </xsl:result-document> </xsl:template>
The process of generating a result tree from the raw result of
the initial template may be replaced with
the very similar sequence normalization process described in
25 Serialization. In the latter
case the serialization parameter item-separator
may be
used to separate items in the raw result with a string other than
space (for example, newlines).
An implicit result tree is also created when the result sequence
is empty, provided that no xsl:result-document
instruction has been evaluated during the course of the
transformation. In this situation the implicit result tree will
consist of a document node with no children.
Note:
This means that there is always at least one result tree. It
also means that if the content of the initial template is a single
xsl:result-document
instruction, as in the example above, then only one result tree is
produced, not two. It is useful to make the result document
explicit as this is the only way of invoking document-level
validation.
If the result of the initial template is non-empty, and an
explicit xsl:result-document
instruction has been evaluated with the empty attribute
href=""
, then an error will occur [see ERR XTDE1490],
since it is not possible to create two final result trees with the
same URI.
A sequence constructor is a sequence of sibling nodes in the stylesheet, each of which is either an XSLT instruction, a literal result element, a text node, or an extension instruction.
[Definition: An instruction is either an XSLT instruction or an extension instruction.]
[Definition: An XSLT instruction is an XSLT
element whose syntax summary in this specification contains the
annotation <!-- category: instruction
-->
.]
Extension instructions are described in 23.2 Extension Instructions.
The main categories of XSLT instruction are as follows:
instructions that create new nodes: xsl:document
, xsl:element
, xsl:attribute
, xsl:processing-instruction
,
xsl:comment
, xsl:value-of
, xsl:text
, xsl:namespace
;
an instruction that returns an arbitrary sequence by evaluating
an XPath expression: xsl:sequence
;
instructions that cause conditional or repeated evaluation of
nested instructions: xsl:if
,
xsl:choose
,
xsl:try
,
xsl:for-each
, xsl:for-each-group
,
xsl:fork
, xsl:iterate
and its subordinate
instructions xsl:next-iteration
and
xsl:break
;
instructions that invoke templates: xsl:apply-templates
,
xsl:apply-imports
,
xsl:call-template
,
xsl:next-match
;
Instructions that declare variables: xsl:variable
, xsl:param
;
other specialized instructions: xsl:number
, xsl:analyze-string
,
xsl:assert
,
xsl:message
, xsl:result-document
,
xsl:stream
,
xsl:perform-sort
,
xsl:merge
.
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 a
source tree.
The results of some expressions and instructions in a stylesheet may depend on information provided contextually. This context information is divided into two categories: the static context, which is known during static analysis of the stylesheet, and the dynamic context, which is not known until the stylesheet is evaluated. Although information in the static context is known at analysis time, it is sometimes used during stylesheet evaluation.
Some context information can be set by means of declarations within the stylesheet itself. For example, the namespace bindings used for any XPath expression are determined by the namespace declarations present in containing elements in the stylesheet. Other information may be supplied externally or implicitly: an example is the current date and time.
The context information used in processing an XSLT stylesheet
includes as a subset all the context information required when
evaluating XPath expressions. The XPath 3.0
specification defines a static and dynamic context that the host
language (in this case, XSLT) may initialize, which affects the
results of XPath expressions used in that context. XSLT augments
the context with additional information: this additional
information is used firstly by XSLT constructs outside the scope of
XPath (for example, the xsl:sort
element), and secondly,
by functions that are defined in the XSLT specification (such as
key
and current-group
) that are
available for use in XPath expressions appearing within a
stylesheet.
The static context for an expression or other construct in a stylesheet is determined by the place in which it appears lexically. The details vary for different components of the static context, but in general, elements within a stylesheet module affect the static context for their descendant elements within the same stylesheet module.
The dynamic context is maintained as a stack. When an instruction or expression is evaluated, it may add dynamic context information to the stack; when evaluation is complete, the dynamic context reverts to its previous state. An expression that accesses information from the dynamic context always uses the value at the top of the stack.
The most commonly used component of the dynamic context is the
context item. This is an implicit variable
whose value is the item currently being processed (it may be a
node, an atomic value, or a function item). The value
of the context item can be referenced within an XPath expression
using the expression .
(dot).
Full details of the static and dynamic context are provided in 5.4 The Static and Dynamic Context.
An XSLT stylesheet describes a process that constructs a set of final result trees from a set of source trees.
The stylesheet does not describe how a source tree is constructed. Some possible ways of constructing source trees are described in [Data Model]. 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 a 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 [DOM Level 2]). 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 XDM 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 final 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 25
Serialization), and attributes on the xsl:result-document
instruction, that 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, or in the serialization attributes of xsl:result-document
,
but is not required to do so.
In previous versions of the XSLT language, it has been possible
to structure a stylesheet as a collection of modules, using the
xsl:include
and
xsl:import
declarations
to express the dependency of on module on others.
In XSLT 3.0 an additional layer of modularization of stylesheet code is enabled through the introduction of packages. A package is a collection of stylesheet modules with a controlled interface to the packages that use it: for example, it defines which functions and templates defined in the package are visible to callers, which are purely internal, and which are not only public but capable of being overridden by other functions and templates supplied by the using package.
Packages are introduced with several motivations, which broadly divide into two categories:
Software engineering benefits: greater re-use of code, greater robustness through ease of testing, controlled evolution of code in response to new requirements, ability to deliver code that users cannot see or modify.
Efficiency benefits: the ability to avoid compiling libraries repeatedly when they are used in multiple stylesheets, and to avoid holding multiple copies of the same library in memory simultaneously.
Packages are designed to allow separate compilation: that is, a package can be compiled independently of the packages that use it. This specification does not define a process model for compilation, or expand on what it means to compile different packages independently. Nor does it mandate that implementations offer any feature along these lines. It merely defines language features that are designed to make separate compilation of packages possible.
To achieve this, packages (unlike modules):
Must not contain unresolved references to functions, templates, or variables declared in other packages;
Have strict rules governing the ability to override declarations in a library package with declarations in a package that uses the library;
Constrain the visibility of component names and of context declarations such as the declarations of keys and decimal formats;
Can declare a mode (a collection of template rules) as final, which disallows the addition of new overriding template rules in a using package;
Require explicit disambiguation where naming conflicts arise, for example when a package uses two other packages that both export like-named components;
Allow multiple specializations of library components to coexist in the same application.
A package is defined by means of an XML document whose outermost
element is an xsl:package
element. This is
referred to as the package manifest. The xsl:package
element has child
elements describing properties of the package, as well as an
xsl:stylesheet
or
xsl:transform
child
element that defines the content of the package, either directly or
by reference through one or more xsl:import
or xsl:include
declarations.
When no packages are explicitly defined, the entire stylesheet
is treated as a single package; the effect is as if the principal stylesheet module
were wrapped in an xsl:package
element with no
other information in the package manifest.
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 23.1 Extension Functions.
It is also permissible to extend the language by providing new
instructions. These are referred to as
extension instructions, and are
described in 23.2 Extension
Instructions. A stylesheet that uses extension instructions
in a particular namespace 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 23 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.8.3 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 SequenceTypeXP30 syntax defined in [XPath 3.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 all the modules of a stylesheet.]
The conformance rules for XSLT 3.0, defined in
26 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 produce the same results with a schema-aware XSLT
processor provided that the source documents are untyped (that is,
they are not validated against a schema). However, if source
documents are validated against a schema then the results may be
different from the case where they are not validated. Some
constructs that work on untyped data may fail with typed data (for
example, an attribute of type xs:date
cannot be used
as an argument of the substring
FO30
function) and other constructs may produce different results
depending on the datatype (for example, given the element
<product price="10.00" discount="2.00"/>
, the
expression @price gt @discount
will return true if the
attributes have type xs:decimal
, but will return false
if they are untyped).
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.15 Built-in Types.
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.
The xsl:import-schema
declaration may reference an external schema document by means of a
URI, or it may contain an inline xs:schema
element.
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.
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 a 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:mode initial="yes" typed="lax"> <xsl:context-item use="required" as="document-node(schema-element(my:invoice))"/> </xsl:mode>
This example will cause the transformation to fail with an error
message when the initial mode is the unnamed mode, unless the
document element of the source document is valid against the
top-level element declaration my:invoice
, and has been
annotated as such.
The setting typed="lax"
further ensures that in any
match pattern for a template rule in this mode, an element name
that corresponds to the name of an element declaration in the
schema is taken as referring to elements validated against that
declaration: for example, match="employee"
will only
match a validated employee
element. Selecting this
option enables the XSLT processor to do more compile-time
type-checking against the schema, for example it allows the
processor to produce warning or error messages when path
expressions contain misspelt element names, or confuse an element
with an attribute.
It is also true that importing a schema does not of itself say
anything about the structure of the result tree. It is possible to
request validation of a result tree against the schema by using the
xsl:result-document
instruction, for example:
<xsl:template match="/"> <xsl:result-document validation="strict"> <xhtml:html> <xsl:apply-templates/> </xhtml:html> </xsl:result-document> </xsl:template>
This example will cause the transformation to fail with an error
message unless the document element of the result document is valid
against the top-level element declaration
xhtml:html
.
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 an XDM tree, as defined in [Data Model]. The implementation may
choose one of several strategies for dealing with this
situation:
The processor may signal a 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 structure representing the
source document 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 source document 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 xs:untyped
and
xs: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.11 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
document, that is, a tree rooted at a document node. This applies
both to temporary trees constructed using the xsl:document
(or xsl:copy
) instruction and also to
final result trees constructed using
xsl:result-document
.
Validation is either strict or lax, as described in [XML Schema Part 1]. 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 type
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 24.2 Validation.
[Definition: The term streaming refers to a manner of processing in which documents (such as source and result documents) are not represented by a complete tree of nodes occupying memory proportional to document size, but instead are processed "on the fly" as a sequence of events, similar in concept to the stream of events notified by an XML parser to represent markup in lexical XML.]
[Definition: A streamed document is a source tree that is processed using streaming, that is, without constructing a complete tree of nodes in memory.]
[Definition: A streamed node is a node in a streamed document.]
Many processors implementing earlier versions of this specification have adopted an architecture that allows streaming of the result tree directly to a serializer, without first materializing the complete result tree in memory. Streaming of the source tree, however, has proved to be more difficult without subsetting the language. This has created a situation where documents exceeding the capacity of virtual memory could not be transformed. XSLT 3.0 therefore introduces facilities allowing stylesheets to be written in a way that makes streaming of source documents possible, without excessive reliance on processor-specific optimization techniques.
Streaming achieves two important objectives: it allows large documents to be transformed without requiring correspondingly large amounts of memory; and it allows the processor to start producing output before it has finished receiving its input, thus reducing latency.
This specification does not attempt to legislate precisely which implementation techniques fall under the definition of streaming, and which do not. A number of techniques are available that reduce memory requirements, while still requiring a degree of buffering, or allocation of memory to partial results. A stylesheet that requests streaming of a source document is indicating that the processor should avoid assuming that the entire source document will fit in memory; in return, the stylesheet must be written in a way that makes streaming possible. This specification does not attempt to describe the algorithms that the processor should actually use, or to impose quantitative constraints on the resources that these algorithms should consume.
Nothing in this specification, nor in its predecessors [XSLT 1.0] and [XSLT 2.0], prevents a processor using streaming whenever it sees an opportunity to do so. However, experience has shown that in order to achieve streaming, it is often necessary to write stylesheet code in such a way as to make this possible. Therefore, XSLT 3.0 provides explicit constructs allowing the stylesheet author to request streaming, and defines explicit static constraints on the structure of the code which are designed to make streaming possible.
A processor that claims conformance with the streaming option offers a guarantee that when streaming is requested for a source document, and when the stylesheet conforms to the rules that make the processing guaranteed-streamable, then an algorithm will be adopted in which memory consumption is either completely independent of document size, or increases only very slowly as document size increases, allowing documents to be processed that are orders-of-magnitude larger than the physical memory available. A processor that does not claim conformance with the streaming option must still process a stylesheet and deliver the correct results, but is not required to use streaming algorithms, and may therefore fail with out-of-memory errors when presented with large source documents.
Apart from the fact that there are constructs to request streaming, and rules that must be followed to guarantee that streaming is possible, the language has been designed so there are as few differences as possible between streaming and non-streaming evaluation. The semantics of the language continue to be expressed in terms of the XDM data model, which is substantively unchanged; but readers must take care to observe that when terms like "node" and "axis" are used, the concepts are completely abstract and may have no direct representation in the run-time execution environment.
Streamed processing of a document can be initiated in one of two ways:
The initial mode can be declared as a streamable mode. In this case the
initial context item will
generally be a document node, and it will be supplied by the
calling application in a form that allows streaming (that is, in
some form other than a tree in memory; for example, as a reference
to a push or pull XML parser primed to deliver a stream of events).
The type of the initial context item
can be constrained using the xsl:context-item
element.
Streamed processing of any document can be initiated using the
xsl:stream
instruction.
This has an attribute href
whose value is the URI of a
document to be processed using streaming, and the actual processing
to be applied is defined by the instructions written as children of
the xsl:stream
instruction.
The rules for streamability, which are defined in detail in 19 Streamability, impose two main constraints:
The only nodes reachable from the node that is currently being
processed are its attributes and namespaces, its ancestors and
their attributes and namespaces, and its descendants and their
attributes and namespaces. The siblings of the node, and the
siblings of its ancestors, are not reachable in the tree, and any
attempt to use their values is a static error. However,
constructs (for example, simple forms of xsl:number
, and simple
positional patterns) that require knowledge of the number of
preceding elements by name are permitted.
When processing a given node in the tree, each descendant node can only be visited once. Essentially this allows two styles of processing: either visit each of the children once, and then process that child with the same restrictions applied; or process all the descendants in a single pass, in which case it is not possible while processing a descendant to make any further downward selection.
The second restriction, that only one visit to the children is
allowed, means that XSLT code that was not designed with streaming
in mind will often need to be rewritten to make it streamable. In
many cases it is possible to do this using a technique sometimes
called windowing or burst-mode streaming (note
this is not quite the same meaning as windowing in XQuery
3.0). Many XML documents consist of a large number of elements,
each of manageable size, representing transactions or business
objects where each such element can be processed independently: in
such cases, an effective design pattern is to write a streaming
transformation that takes a snapshot of each element in turn,
processing the snapshot using the full power of the XSLT language.
Each snapshot is a tree built in memory and is therefore fully
navigable. For details see the snapshot
and copy-of
functions.
The new facility of accumulators allows applications complete control over how much information is retained (and by implication, how much memory is required) in the course of a pass over a streamed document. An accumulator computes a value for every node in a streamed document: or more accurately, two values, one for the first visit to a node (before visiting its descendants), and a second value for the second visit to the node (after visiting the descendants). The computation is structured in such a way that the value for a given node can depend only on the value for the previous node in document order together with the data available when positioned at the current node (for example, the attribute values). Based on the well-established fold operation of functional programming languages, accumulators provide the convenience and economy of mutable variables while remaining within the constraints of a purely declarative processing model.
Streaming applications often fall into one of the following categories:
Aggregation applications, where a single aggregation operation
(perhaps count
FO30,
sum
FO30,
exists
FO30,
or
distinct-values
FO30) is
applied to a set of elements selected from the streamed source
document by means of a path expression.
Record-at-a-time applications, where the source document
consists of a long sequence of elements with similar structure
("records"), and each "record" is processed using the same logic,
independently of any other "records". This kind of processing is
facilitated using the snapshot
and copy-of
function mentioned
earlier.
Grouping applications, where the output follows the structure of the input, except that an extra layer of hierarchy is added. For example, the input might be a flat series of banking transactions in date/time order, and the output might contain the same transactions grouped by date.
Accumulator applications, which are the same as record-at-a-time
applications, except that the processing of one "record" might
depend on data encountered earlier in the document. A classical
example is processing a sequence of banking transactions in which
the input transaction contains a debit or credit amount, and the
output adds a running total (the account balance). The xsl:iterate
instruction has
been introduced to facilitate this style of processing.
Isomorphic transformations, in which there is an ordered (often
largely one-to-one) relationship between the nodes of the source
tree and the nodes of the result tree: for example, transformations
that involve only the renaming or selective deletion of nodes, or
scalar manipulations of the values held in the leaf nodes. Such
transformations are most conveniently expressed using recursive
application of template rules. This is possible with a streamed
input document only if all the template rules adhere to the
constraints required for streamability. To enforce these rules,
while still allowing unrestricted processing of other documents
within the same transformation, all streaming evaluation must be
carried out using a specific mode, which is declared to be a streaming mode by
means of an xsl:mode
declaration in the stylesheet.
There are important classes of application in which streaming is possible only if multiple streams can be processed in parallel. This specification therefore provides facilities:
allowing multiple sorted input sequences to be merged into one
sorted output sequence (the xsl:merge
instruction)
allowing multiple output sequences to be generated during a
single pass of an input sequence (the xsl:fork
instruction).
These facilities have been designed in such a way that they can readily be implemented using streaming, that is, without materializing the input or output sequences in memory.
[Definition: An error that can be detected by examining a stylesheet before execution starts (that is, before the source document and values of stylesheet parameters are available) is referred to as a static error.]
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 final result tree.
There is an exception to this rule when the stylesheet specifies forwards compatible behavior (see 3.11 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.]
When a dynamic error occurs, and is not caught
using xsl:catch
, 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 final result trees 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.11 Circular Definitions.
There are also some dynamic errors where the specification
gives a processor license to signal the error during the analysis
phase even if the construct might never be executed; an example is
the use of an invalid QName as a literal argument to a function
such as key
, or the use of an
invalid regular expression in the regex
attribute of
the xsl:analyze-string
instruction.
A dynamic error may also be signaled during the static analysis phase if the error occurs during evaluation of a static expression.
The XPath specification states (see Section 2.3.1 Kinds of Errors XP30) that if any expression (at any level) can be evaluated during the analysis phase (because all its explicit operands are known and it has no dependencies on the dynamic context), then any error in performing this evaluation may be reported 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 unless they would occur in every possible evaluation of that stylesheet; instead, they must be signaled as dynamic errors, 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 or 3.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 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.
The following construct contains a type error, because
42
is not allowed as the value of the
select
expression of the xsl:number
instruction (it must
be a node). 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:number select="42"/> </xsl:if>
On the other hand, in the following example it is not possible
to determine statically whether the operand of xsl:number
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:number 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 serialized result documents may be written successfully before the transformation terminates, but the application cannot rely on this behavior.
Everything said above about error handling applies equally to errors in evaluating XSLT instructions, and errors in evaluating XPath expressions. Static errors and dynamic errors may occur in both cases.
[Definition: If a transformation has successfully produced a final 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.] If the processor performs serialization, then it must do so as specified in 25 Serialization, and in particular it must signal any serialization errors that occur.
Errors are identified by a QName. For errors defined in this
specification, the namespace of the QName is always
http://www.w3.org/2005/xqt-errors
(and is therefore
not given explicitly), while the local part is an 8-character code
in the form PPSSNNNN. Here PP is always
XT
(meaning XSLT), and SS is one of
SE
(static error), DE
(dynamic error),
RE
(recoverable dynamic error), or TE
(type error). Note that the allocation of an error to one of these
categories is purely for convenience and carries no normative
implications about the way the error is handled. Many errors, for
example, can be reported either dynamically or statically. These
error codes are used to label error conditions in this
specification, and are summarized in E
Summary of Error Conditions.
Errors defined in related specifications ([XPath 3.0], [Functions and Operators] [XSLT and XQuery Serialization]) use QNames with a similar structure, in the same namespace. When errors occur in processing XPath expressions, an XSLT processor should use the original error code reported by the XPath processor, unless a more specific XSLT error code is available.
Implementations must use the
codes defined in these specifications when signaling errors, to
ensure that xsl:catch
behaves in an interoperable way across implementations. Stylesheet
authors should note, however, that there are many examples of
errors where more than one rule in this specification is violated,
and where the processor therefore has discretion in deciding which
error code to associate with the condition: there is therefore no
guarantee that different processors will always use the same error
code for the same erroneous input.
Additional errors defined by an implementation (or by an application) may use QNames in an implementation-defined (or user-defined) namespace without risk of collision.
This section describes the overall structure of a stylesheet as a collection of XML documents.
[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.8 Stylesheet Element and
3.9 Simplified Stylesheet
Modules).
XSLT processors must use the XML namespaces mechanism [Namespaces in XML] 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 23.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 are regarded as single
words and are capitalized exactly as in XML Schema. This sometimes
leads to composite function names such as
current-dateTime
FO30.
[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/2005/xpath-functions
is used for functions in the function library defined in [Functions and Operators] and for
standard functions defined in this specification.]
The namespace
http://www.w3.org/2005/xpath-functions/math
is used
for mathematical functions in the function library defined in
[Functions and Operators].
The namespace
http://www.w3.org/2005/xpath-functions/map
is used for
functions defined in this specification relating to the
manipulation of maps.
[Definition: The
XML namespace, defined in [Namespaces
in XML] as http://www.w3.org/XML/1998/namespace
,
is used for attributes such as xml:lang
,
xml:space
, and xml:id
.]
[Definition: The schema namespace
http://www.w3.org/2001/XMLSchema
is used as defined in
[XML Schema Part 1]]. 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 instance
namespace
http://www.w3.org/2001/XMLSchema-instance
is used as
defined in [XML Schema Part
1]]. Attributes in this
namespace, if they appear in a stylesheet, are treated by the
XSLT processor in the same way as any other attributes.
[Definition: The standard error
namespace http://www.w3.org/2005/xqt-errors
is
used for error codes defined in this specification and related
specifications. It is also used for the names of certain predefined
variables accessible within the scope of an xsl:catch
element.]
The namespace http://www.w3.org/2000/xmlns/
is
reserved for use as described in [Namespaces
in XML]. No element or attribute node can have a name in this
namespace, and although the prefix xmlns
is implicitly
bound to this namespace, no namespace node will ever define this
binding.
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 elements: 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 XTSE0080] 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 3.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 final result trees produced by the transformation to be different from the result trees that a conformant XSLT 3.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.
Furthermore, if serialization is performed using one of the
serialization methods xml
, xhtml
,
html
, or text
described in [XSLT and XQuery
Serialization], the presence of an extension attribute must not
cause the serializer to behave in a way that is inconsistent with
the mandatory provisions of that specification.
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 influence the behavior of the serialization methods
xml
, xhtml
, html
, or
text
, to the extent that the behavior of the
serialization method is implementation-defined or
implementation-dependent. For
example, an extension attribute might be used to define the amount
of indentation to be used when indent="yes"
is
specified. If a serialization method other than one of these four
is requested (using a prefixed QName in the method parameter) then
extension attributes may influence its behavior in arbitrary ways.
Extension attributes must not be used to cause the four standard
serialization methods to behave in a non-conformant way, for
example by failing to report serialization errors that a serializer
is required to report. An implementation that wishes to provide
such options must create a new serialization method for the
purpose.
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.
The namespace used for an extension attribute will be copied to
the result tree in the normal way if it is in
scope for a literal result element. This can
be prevented using the [xsl:]exclude-result-prefixes
attribute.
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 XTSE0090] 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
has
been registered for XSLT stylesheet modules.
The definition of the media type is at [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 default-collation
,
default-mode
, default-validation
,
exclude-result-prefixes
,
expand-text
,
extension-element-prefixes
, use-when
,
version
, 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:default-collation
,
xsl:default-mode
, xsl:default-validation
,
xsl:exclude-result-prefixes
,
xsl:expand-text
,
xsl:extension-element-prefixes
,
xsl:use-when
, xsl:version
, or
xsl:xpath-default-namespace
.
It is recommended that all 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, together with any elements and attributes that have that element as an ancestor. 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:]default-collation
,
[xsl:]expand-text
,
[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
ancestor-or-self element on which the attribute appears.
In an embedded stylesheet module, standard attributes appearing on ancestors of the outermost element of the stylesheet module have no effect.
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.
The effect of the [xsl:]use-when
attribute is
described in 3.14 Conditional
Element Inclusion.
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
entry for the xsl:stylesheet
, xsl:transform
, and
xsl:package
elements only. This reflects the fact that these attributes are
often used on the outermost element of the stylesheet,
in which case they apply to the entire stylesheet module
or package manifest.
Note that the effect of these attributes does not
extend to stylesheet modules referenced by
xsl:include
or xsl:import
declarations,
nor to packages referenced using xsl:use-package
.
For the detailed effect of each attribute, see the following sections:
[xsl:]default-collation
[xsl:]default-mode
[xsl:]default-validaion
see 24.2 Validation
[xsl:]exclude-result-prefixes
[xsl:]expand-text
[xsl:]extension-element-prefixes
[xsl:]use-when
[xsl:]version
see 3.10 Backwards Compatible Processing and 3.11 Forwards Compatible Processing
[xsl:]xpath-default-namespace
see 5.2 Unprefixed Lexical QNames in Expressions and Patterns
[Definition: A package
is represented by an xsl:package
element, which will
generally be the outermost element of an XML document.] (This specification does not preclude the
xsl:package
being
embedded in another XML document, but it will never have any other
XSLT element as an ancestor).
<xsl:package
name? = uri
package-version? = string
version = decimal
input-type-annotations? = "preserve" | "strip" |
"unspecified"
default-mode? = eqname | "#unnamed"
default-validation? = "preserve" | "strip"
default-collation? = uris
extension-element-prefixes? = prefixes
exclude-result-prefixes? = prefixes
expand-text? = "yes" | "no"
use-when? = expression
xpath-default-namespace? =
uri >
<!-- Content: (xsl:use-package*, (xsl:stylesheet | xsl:transform), xsl:expose*) -->
</xsl:package>
[Definition: The content of the xsl:package
element is referred
to as the package manifest].
The version
attribute indicates the
version of the XSLT language specification to which the package
manifest conforms. The value should be
3.0
.
A package typically has a name, given in its name
attribute, which must be an absolute URI.
Unnamed packages are allowed, but they can only be used as the "top
level" of an application; they cannot be the target of a xsl:use-package
declaration
in another package.
A package may have a version identifier, given in
its package-version
attribute. This is used to
distinguish different packages that have the same package name,
perhaps successive versions of a package, or perhaps variants of a
package for use in different environments. The version identifier
can be any string.
The attributes default-collation
,
default-mode
, default-validation
,
exclude-result-prefixes
, expand-text
,
extension-element-prefixes
, use-when
,
version
, and xpath-default-namespace
are
standard attributes that can appear on any XSLT element, and
potentially affect all descendant elements. Their meaning is
described in 3.5 Standard
Attributes.
The package manifest is in three parts:
It starts with zero-or-more xsl:use-package
elements
which identify the packages used by this package, including
subsidiary elements that constrain the way in which the components
contained in those packages are used.
This is followed by an xsl:stylesheet
or xsl:transform
element (the
two names are synonyms) which is an embedded standard stylesheet module.
This can contain references to other stylesheet modules using
xsl:include
and/or
xsl:import
declarations, and it can contain other
declarations such as xsl:function
and xsl:template
.
The modules making up a package are this module, plus all
modules that are transitively reachable from it using xsl:import
and xsl:include
declarations. It is
permissible for the same module to appear in more than one package,
or indeed more than once in the same package; this situation is no
different from having two modules with identical content but
different URIs.
Finally, the manifest contains zero or more xsl:expose
declarations that
define the interface offered by this package to the outside
world.
A package that does not itself expose any components (in effect,
a stylesheet that makes use of library packages but is not itself
intended to act as a library package) may be written using a
simplified syntax: the xsl:package
element is omitted,
and the xsl:use-package
children
are moved to the xsl:stylesheet
or xsl:transform
element, which
is now the outermost element of the stylesheet module. More
formally, an xsl:stylesheet
or xsl:transform
element having
one or more xsl:use-package
children is
equivalent to the package represented by the output of the
following transformation, preserving the base URI of the
source:
<xsl:transform version="3.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:t="http://www.w3.org/1999/XSL/TransformAlias"> <xsl:namespace-alias stylesheet-prefix="t" result-prefix="xsl"/> <xsl:mode on-no-match="shallow-copy"/> <xsl:template match="(xsl:stylesheet|xsl:transform)[xsl:use-package]"> <t:package version="{@version}"> <xsl:copy-of select="xsl:use-package"/> <xsl:copy> <xsl:copy-of select="@*"/> <xsl:copy-of select="* except xsl:use-package"/> </xsl:copy> </t:package> </xsl:template> </xsl:transform>
The effect of the input-type-annotations
attribute
is defined in 4.3 Stripping
Type Annotations from a Source Tree.
When components in one package reference components in another,
the dependency of the first package on the second must be
represented by an xsl:use-package
element in
the package manifest of the first
package.
[Definition: If a package Q
contains an xsl:use-package
element
that references package P, then package Q is
said to use package P. In this relationship
package Q is referred to as the using package,
package P as the used package.]
The phrase directly uses is synonymous with uses as defined above, while directly or indirectly uses refers to the transitive closure of this relationship.
<xsl:use-package
name = uri
package-version? = token >
<!-- Content: (xsl:accept | xsl:override)* -->
</xsl:use-package>
A package may be used by more than one other package, but the relationship must not be cyclic. It is possible, but by no means inevitable, that using the same package in more than one place within a stylesheet will cause static errors due to the presence of conflicting components according to the above rules. Where a package is successfully used by more than one other package, its components may be overridden in different ways by different using packages.
The name
and package-version
attributes together identify the used package. The used package
must have a name that is an exact match for the name in the
name
attribute (using codepoint comparison), and it
may have a package-version that matches the pattern given in the
package-version
attribute, according to the rules
below. Omitting this attribute is equivalent to specifying the
value as package-version="#"
, which matches any
version.
The value of the package-version
attribute consists
of a prefix and a suffix separated by a hash sign (#); if there is
no hash sign, the entire string is used as the prefix, and the
suffix is empty; if there is more than one hash sign, the first one
is taken as the separator and others as part of the suffix; if the
hash sign is the last character in the string then a suffix of ".*"
is assumed. The pattern matches a package version if the package
version can be divided into two substrings such that the first
substring matches the prefix literally (using codepoint
comparison), and the second substring matches the suffix considered
as a regular expression (matched according to the rules of the
matches
FO30
function with the $flags
argument set to a zero length
string). Thus the version pattern 3.1
matches version
3.1
only; the pattern 3.1#
matches
3.1
, 3.1.2
, and 3.17
; the
pattern 3.1#(\.\d+)?
matches 3.1
and
3.1.5
; and the pattern 3.1#(\.\d+)*
matches 3.1
, 3.1.5
, and
3.1.5.2
.
This specification does not define how the implementation locates a package given its name and version. Nor does it define whether this process locates source code or some other representation of the package contents. Such mechanisms are implementation-defined. Use of the package name as a dereferencable URI is not recommended, because the intent of the packaging feature is to allow a package to be distributed as reusable code and therefore to exist in many different locations.
The xsl:accept
and
xsl:override
elements
are used to modify the visibility or behavior of components
acquired from the used package; they are described in 3.6.2.4 Accepting Components
below.
An xsl:use-package
element
whose parent element is xsl:stylesheet
or xsl:transform
is allowed only
if the xsl:stylesheet
or xsl:transform
does not form
part of an explicit package.
This section discusses the use of named components in packages: specifically functions, named templates, attribute sets, modes, accumulators, keys, modes, and global variables and parameters. Some of the provisions in this section also apply to named modes, but there are differences noted in 3.6.3 Overriding Template Rules from a Used Package. The section is largely concerned with details of the rules that affect references from one component to another by name, whether the components are in the same package or in different packages. The rules are designed to meet a number of requirements:
A component defined in one package can be overridden by a component in another package, provided the signatures are type-compatible.
The author of a package can declare whether the components in the package are public or private (that is, whether or not they can be used from outside the package) and whether they are final, overridable, or abstract (that is whether they can or must be overridden by the using package).
Within an application, two packages can make use of a common library and override its components in different ways.
Visibility of components can be defined either as part of the declaration of the component, or in the package manifest.
An application that wishes to make use of a library package can be selective about which components from the library it acquires, perhaps to avoid name clashes between components acquired from different libraries.
[Definition: The term component is used to refer to any of the following: a stylesheet function, a named template, a mode, an accumulator an attribute set, a key, global variable, or a mode.]
[Definition: The symbolic identifier of a component is a composite name used to identify the component uniquely within a package. The symbolic identifier comprises the kind of component (stylesheet function, named template, accumulator, attribute set, global variable, or mode), the expanded QName of the component (namespace URI plus local name), and in the case of stylesheet functions, the arity.]
[Definition: Two components are said to be homonymous if they have the same symbolic identifier.]
Every component has a declaration in some stylesheet module and therefore within some package. In the case of attribute sets, there may be several declarations. The declaration is an element in an XDM tree representing the stylesheet module. Declarations therefore have identity, based on XDM node identity.
Not all declarations result in components:
Some declarations, such as xsl:decimal-format
and
xsl:strip-space
,
declare aspects of the processing context which are not considered
to be components as defined here.
Template rules (xsl:template
with a
match
attribute) are also not considered to be
components for the purposes of this section, which is concerned
only with components that are bound by name. However, when an
xsl:template
has both
a match
attribute and a name
attribute,
then it establishes both a template rule and a named
template, and in its role as a named template it comes within
the scope of this discussion.
A named declaration, for example a named template, a function, an accumulator, or a global variable, may be overridden within the same package by another like-named declaration having higher import precedence. When a declaration is overridden in this way it can never be referenced or invoked either from within its containing package or from outside that package; it is effectively dead code, and it therefore does not result in the creation of any component, which means that it plays no part in the component binding process.
In the case of xsl:attribute-set
and
xsl:key
declarations,
several declarations combine to form a single component.
[Definition: The declaring package of a component is
the package that contains the declaration (or, in the case of
xsl:attribute-set
and xsl:key
, multiple
declarations) of the component.]
When a component declared in one package is made available in another, the using package will contain a separate component that can be regarded as a modified copy of the original. The new component shares the same symbolic identifier as the original, and it has the same declaration, but it has other properties such as its visibility that may differ from the original.
[Definition: A component declaration results in
multiple components, one in the package in which the declaration
appears, and potentially one in each package that uses the
declaring package, directly or indirectly, subject to the
visibility of the component. Each of these multiple compenents has
the same declaring package, but each has a
different containing package. For the original component,
the declaring package and the containing package are the same; for
a copy of a component made as a result of a xsl:use-package
declaration, the declaring package will be the original package,
and the containing package will be the package in which the
xsl:use-package
declaration appears.]
The properties of a component are as follows:
The original declaration of the component.
The package to which the component belongs (called its containing package, not to be confused with the declaring package).
The symbolic identifier of the component.
The visibility of the component, which determines
the way in which the component is seen by other components within
the same package and within using packages. This is one of
public
, private
, abstract
,
final
, or hidden
. The visibility of
components is discussed further in 3.6.2.1
Visibility of Components.
A set of bindings for the symbolic references in the component. The way in which these bindings are established is discussed further in 3.6.2.6 Binding References to Components.
Note:
When a function F defined in a package P is acquired by two using packages Q and R, we may think of P, Q, and R as all providing access to the "same" function. The detailed semantics, however, demand an understanding that there is one function declaration, but three components. The three components representing the function F within packages P, Q, and R have some properties in common (the same symbolic identifier, the same declaration), but other properties (the visibility and the bindings of symbolic references) that may vary from one of these components to another.
[Definition: The declaration of a component includes
constructs that can be interpreted as references to other components by
means of their symbolic identifiers. These
constructs are generically referred to as symbolic
references. Examples of constructs that give rise to symbolic
references are the name
attribute of xsl:call-template
; the
[xsl:]use-attribute-sets
attribute of xsl:copy
, xsl:element
, and literal result elements; the
mode
attribute of xsl:template
and xsl:apply-templates
;
XPath variable references referring to global variables; and XPath
function calls referring to stylesheet functions
or accumulator
functions.]
Symbolic references exist as properties of the declaration of a component. The symbolic identifier being referred to
can be determined straightforwardly from the syntactic form and
context of the reference: for example, the instruction
<xsl:value-of select="f:price($o)"
xmlns:f="http://f.com/"/>
contains a symbolic reference
to a function with expanded name {http://f.com/}price
and with arity=1. However, because there may be several
(homonymous) function components with this symbolic identifier,
translating this symbolic reference into a reference to a specific
component (a process called "binding") is less straightforward, and
is described in the text that follows.
The process of assembling a stylesheet from its constituent packages is primarily a process of binding these symbolic references to actual components. Within any component whose declaration is D, there is a set of bindings; each binding is an association between an symbolic reference in D and a component whose symbolic identifier matches the outward reference. Outward references for which a component C contains a binding are said to be bound in C; those for which C contains no binding are said to be unbound.
For example, suppose that in some package P, function
A calls B, which in turn calls C,
and that B is private
. Now suppose that in
some package Q which uses P, C is
overridden. The effect of the binding process is that Q
will contain three components corresponding to A,
B, and C, which we might call
A(Q), B(Q), and C(Q). The
declarations of A(Q) and
B(Q) are in package P, but the declaration of
C(Q) is in Q. The internal visibility of
B(Q) will be hidden
(meaning that it cannot
be referenced from within Q), and B(Q) will
contain a binding for the component C(Q) that
corresponds to the outward reference from B to
C. The effect is that when A calls
B and B calls C, it is the
overriding version of C that is executed. In another
package R that uses P without overriding
C, there will be three different components
A(R), B(R), and C(R). This time
the declaration of all three components is in the original package
P. Component B(R) will contain a binding to
C(R), so in this package, the original version of
C is executed. The fact that one package Q
overrides C thus has no effect on R, which
does not override it.
Template rules are not components in their own right; unlike named templates, they are never referenced by name. Component references within a template rule (for example, references to functions, global variables, or named templates) are treated as occurring within the component that represents the containing mode. If a template rule lists several modes, it is treated as if there were multiple template rules one in each mode.
Keys behave
rather differently from other components. Their visibility is
always private, which means they can only be used within their
declaring package. In addition, the component binding (the
reference to a key definition from a call on the key
function) is in the general case
made dynamically rather than statically. However, outward
references from key definitions to other components (such as global
variables and functions) behave in the same way as component
references contained in any other private component, in that they
may be rebound to an overriding declaration of the target
component.
[Definition: The
visibility of a component is one of: private
,
public
, abstract
, final
, or
hidden
.]
The meanings of these visibility values is as follows:
Visibility | Meaning |
---|---|
public | The component can be referenced from other components in this package or in any using package; it can be overridden by a different component in any using package. |
private | The component can be referenced from other components in this package; it cannot be referenced or overridden within a using package. |
abstract | The component can be referenced from other components in this package or in any using package; in a using package it can either remain abstract or be overridden by a different component. |
final | The component can be referenced from other components in this package or in any using package; it cannot be overridden by a different component in any using package. |
hidden | The component cannot be referenced from other components in this package; it cannot be referenced or overridden within a using package. |
The visibility (sometimes called the actual visibility) of a component depends on two factors: its potential visibility and its exposed visibility.
[Definition: The potential visibility of a component is established when the component is declared or accepted into a package.]
[Definition: The exposed visibility of a
component is established by an xsl:expose
element in the
package manifest.]
For a component within its declaring package the
potential visibility is the value of
the visibility
attribute on the component's declaration, or private
if the
attribute is absent.
For a component accepted from another package, the potential visibility depends on the
visibility declared in the relevant xsl:accept
or xsl:override
element that
makes the component available within the using package; this in
turn has a default that depends on the (actual) visibility of the
corresponding component in the used package.
These rules are described more fully in the sections that follow.
The xsl:function
,
xsl:template
, xsl:attribute-set
,
xsl:variable
, xsl:param
, and xsl:mode
declarations each have
an optional visibility
attribute that determines the
potential visibility of the
component corresponding to this declaration in its declaring package. The value is one of
private
, public
, abstract
,
final
(never hidden
), with the default
being private
. In the case of xsl:attribute-set
, all
the declarations for an attribute set must have the same value for
the visibility
attribute. In the case of xsl:key
, the visibility cannot be
explicitly specified: it is always private
.
Whatever the value of this attribute, and whatever the exposed visiblity of the component,
other declarations within the same package may contain symbolic references to this
declaration: informally, the name of the component is always "in
scope" within the package containing its declaration. The way in
which these symbolic references are bound to an actual component,
however, depends on the component's visibility, as defined in
3.6.2.6 Binding References to
Components. For example, a symbolic reference will never be
bound to a component whose visibility is abstract
.
The visibility of a component within a package may
be modified by means of an xsl:expose
element in the
package manifest.
<xsl:expose
component = "template" | "function" |
"accumulator" | "attribute-set" | "variable" | "mode"
names = tokens
visibility = "public" | "private" | "final" |
"abstract" />
The xsl:expose
element allows selected components within a package to have an
exposed visibility different from
their potential visibility .
The components in question are identified using their symbolic identifiers. The
component
attribute defines the kind of component that
is selected (variable
embraces xsl:variable
and xsl:param
). The
names
attribute selects a subset of those components
by name (and in the case of functions, arity); its value is a
whitespace-separated sequence of tokens each of which is either a
NameTestXP30
or a NamedFunctionRefXP30.
(Examples are *
, p:*
,
*:local
, p:local
, and
p:local#2
.)
The value may be a NamedFunctionRef
only in the
case of stylesheet functions, and distinguishes functions with the
same name and different arity.
The visibility
attribute defines the exposed
visibility of the selected components.
If a component is matched by more than one xsl:expose
element in the
package manifest, then its exposed visibility is determined by the
best matching NameTestXP30
or LiteralFunctionItem
. The rules are similar to those
for template rules:
A token in the form of a LiteralFunctionItem (for example,
f:price#1
) has higher priority than any NameTest.
Next, any match that has a lower default priority than the default priority of another match is ignored.
If several matches have the same default priority
(which can happen if the same value is repeated, or if one of the
NameTests takes the form *:local
and the other takes
the form prefix:*
), then the xsl:expose
element that appears
last in document order within the package manifest is used.
If no xsl:expose
element matches a component, then the visibility of the component is
its potential visibility.
Otherwise, the visibility of the component depends on its potential visibility and its exposed visibility as defined by the following table. In this table, the value N/P means "not permitted".
Exposed visibility | Potential visibility | |||
---|---|---|---|---|
public | private | final | abstract | |
public | public | N/P | N/P | N/P |
private | private | private | private | N/P |
final | final | N/P | final | N/P |
abstract | N/P | N/P | N/P | abstract |
[ERR XTSE3010] It is a static error if the exposed visibility of a component is inconsistent with its potential visibility, as defined in the above table, unless the token that matches the component is a wildcard, in which case it is treated as not matching that component.
[ERR XTSE3020] It is a static error if an
xsl:expose
element
matches no components in the containing package, unless the tokens
in the names
attribute are all wildcards.
When a package Q uses a package P, by
virtue of an xsl:use-package
element in
the package manifest of Q, then
Q will contain a component corresponding to every component
in P. The potential visibility
of the component within Q depends on the visibility
of the component in P, optionally modified by two
elements that may appear as children of the xsl:use-package
element,
namely xsl:accept
and
xsl:override
.
For every component C(P) in package P that
is not matched by any xsl:override
or xsl:accept
element in the
package manifest of Q, there will be a corresponding
component C(Q) in package Q that has the same
symbolic identifier and declaration as C(P). The potential visibility of
C(Q) will be the same as the (actual) visibility
of C(P), except that where the visibility of
C(P) is private
, the potential visibility of
C(Q) will be hidden
. The (actual)
visibility of C(Q) depends both on its potential visibility and its
exposed visibility, as described in
3.6.2.3 Exposing
Components.
A component C(P) in package P whose
visibility is hidden
will never
be matched by an xsl:override
or xsl:accept
element in the
package manifest of Q, and therefore Q will
contain a hidden
component C(Q)
corresponding to C(P).
<xsl:accept
component = "template" | "function" |
"accumulator" | "attribute-set" | "variable" | "mode"
names = tokens
visibility = "public" | "private" | "final" |
"abstract" | "hidden" | "absent" />
The xsl:accept
element has the same syntax as xsl:expose
, and very similar
semantics. Whereas xsl:expose
allows a package to
restrict the visibility of its own components to other (using)
packages, xsl:accept
allows a package to restrict the visibility of components exposed
by a package that it uses. This may be necessary if, for example,
it uses two different packages whose component names conflict. It
may also simply be good practice if the package author knows that
only a small subset of the functionality of a used package is
required.
The rules for determining whether an xsl:accept
element matches a
particular component, and for which element to use if there are
several matches, are the same as the rules for the xsl:expose
element.
[ERR XTSE3030] It is a static error if an
xsl:accept
element
matches no components in the used package, unless the tokens in its
names
attribute are all wildcards.
In the absence of a matching xsl:override
element (see
3.6.2.5 Overriding
Named Components from a Used Package), the potential visibility of a component
that matches an xsl:accept
element depends both
on the visibility
attribute of the best-matching
xsl:accept
element and
on the (actual) visibility of the corresponding component in
the used package, according to the following table. In this table
the entry "N/P" means "not permitted".
Visibility in
xsl:accept element |
Visibility in used package | |||
---|---|---|---|---|
public | private | final | abstract | |
public | public | N/P | N/P | N/P |
private | private | N/P | private | N/P |
final | final | N/P | final | N/P |
abstract | N/P | N/P | N/P | abstract |
hidden | hidden | N/P | hidden | N/P |
absent | N/P | N/P | N/P | absent |
[ERR XTSE3040] It is a static error if the
visibility assigned to a component by an xsl:accept
element is
incompatible with the visibility of the corresponding component in
the used package, as defined by the above table, unless the token
that matches the component name is a wildcard, in which case the
xsl:accept
element is
treated as not matching that component.
[ERR XTSE3050] It is a static error if the
xsl:use-package
elements in a package manifest cause two or more
homonymous components to be accepted with a
visibility other than hidden
.
Conflicts between the components accepted from used packages and those declared within the package itself are handled as follows:
If the conflict is between two components both declared within the package itself, then it is resolved by the rules relating to import precedence defined for each kind of component.
If the conflict is between two components both accepted from used packages, or between a component declared within the package and an accepted component, then a static error occurs.
The value visibility="absent"
may be used only in
the case of a component that is present in the used package with
exposed visibility abstract
. It is used to indicate
that the using package does not intend to provide an implementation
of the abstract component, and that any invocation of the abstract
component is therefore to result in an error. Specifically:
Any component reference to the component within the using package is a static error, as if the component were hidden: in effect, the name of the component is not in scope in the using package.
Any invocation of the absent component (typically from within its declaring package) causes a dynamic error, as if the component were overridden by a component that unconditionally raises a dynamic error.
[ERR XTDE3052] It is a dynamic error if an
invocation of an absent component (that is, an abstract component
accepted into a using package with
visibility="absent"
) is evaluated.
Note:
To override a component accepted from a used package, the
overriding declaration must appear as a child of the xsl:override
element.
Note:
There is no rule that prevents a function (say) being declared
in the using package with the same name as a private
function in the used package. This does not create a conflict,
since all references in the used package are bound to one function
and all those in the using package are bound to another.
[Definition: A component in
a using package may override a component in a used package,
provided that the visibility of the component in the used
package is either abstract
or public
. The
overriding declaration is written as a child of the xsl:override
element, which in
turn appears as a child of xsl:use-package
.]
<xsl:override>
<!-- Content: (xsl:template | xsl:function | xsl:accumulator | xsl:variable | xsl:param | xsl:attribute-set)* -->
</xsl:override>
Note:
This mechanism is distinct from the mechanism for overriding declarations within the same package by relying on import precedence. It imposes stricter rules: the overriding component is required to be type-compatible with the component that it overrides.
If the used package P contains a component C(P)
and the xsl:use-package
element
contains an xsl:override
element which
contains a declaration D whose symbolic identifier matches the
symbolic identifier of C(P), then the using package
Q will contain a component whose declaration is D, whose
symbolic identifier is that of D, and whose potential visibility is equal to the
value of the visibility
attribute of D, or
private
if this is absent.
If the overridden component C(P) has visibility
public
then the using package Q will also
contain a component C′(Q) whose declaration is the same
as the declaration of C(P) and whose visibility
is hidden
. This component is used as the target of a
binding for the symbolic reference xsl:original
described below.
Other than its appearance as a child of xsl:override
, the overriding
declaration is a normal xsl:function
, xsl:template
, xsl:accumulator
,
xsl:variable
, xsl:param
, xsl:attribute-set
, or
xsl:mode
element. In the
case of xsl:variable
and xsl:param
, the
variable that is declared is a global variable.
The potential visibility of the
overriding component in the using package is defined by the
visibility
attribute appearing on the overriding
declaration.
[ERR XTSE3055] It is a static error if a
component declaration appearing as a child of xsl:override
is homonymous
with any other declaration in the using package, regardless of
import precedence, including any other
overriding declaration in the package manifest of the using
package.
Note:
When an attribute set is overridden, the overriding attribute
set must be defined using a single xsl:attribute-set
element. Attribute sets defined in different packages are never
merged by virtue of having the same name, though they may be merged
explicitly by using the use-attribute-sets
attribute.
[ERR XTSE3058] It is a static error if a
component declaration appearing as a child of xsl:override
does not match
(is not homonymous with) some component in the used
package.
[ERR XTSE3060] It is a static error if the
component referenced by an xsl:override
declaration has
visibility other than public
or
abstract
A package is executable if and only if it contains no component
whose visibility is abstract
. A package
that is not executable is not a stylesheet, and therefore
cannot be nominated as the stylesheet to be used when initiating a
transformation.
Note:
In other words, if a component is declared as abstract, then some package that uses the declaring package of that component directly or indirectly must override that component with one that is not abstract. It is not necessary for the override to happen in the immediately using package.
[ERR XTSE3070] It is a static error if the signature of an overriding component is not compatible with the signature of the component that it is overriding.
[Definition: The signatures of two components are compatible if they present the same interface to the user of the component. The additional rules depend on the kind of component.]
Compatibility is only relevant when comparing two components that have the same symbolic identifier. The compatibility rules for each kind of component are as follows:
Two attribute sets with the same name are compatible if and only if they satisfy the following rule:
If the overridden attribute set specifies
streamable="yes"
then the overriding attribute set
also specifies streamable="yes"
.
Two functions with the same name and arity are compatible if and only if they satisfy all the following rules:
The types of the arguments are pairwise identical.
The return types are identical.
If the overridden function specifies
identity-sensitive="no"
then the overriding function
also specifies identity-sensitive="no"
.
If the overridden function specifies
override-extension-functions="no"
(or the equivalent
using the deprecated override
attribute) then the
overriding function also specifies
override-extension-functions="no"
(or the
equivalent).
Two accumulators with the same name are compatible if and only if they satisfy all the following rules:
The types (defined in the as
attribute) are
identical.
If the overridden accumulator specifies
streamable="yes"
then the overriding accumulator also
specifies streamable="yes"
.
Two named templates with the same name are compatible if and only if they satisfy all the following rules:
Their return types are identical.
For every parameter on the overridden template, there is a
parameter on the overriding template that has the same name, an
identical required type, and the same
effective values for the tunnel
and
required
attributes.
Any parameter on the overriding template for which there is no
corresponding parameter on the overridden template specifies
required="no"
.
The two templates have equivalent xsl:context-item
children,
where equivalence means that the use
attributes are
the same and the required types are identical; an absent
xsl:context-item
is equivalent to one that specifies use="optional"
and
as="item()"
.
Two variables (including parameters) with the same name are compatible if and only if they satisfy all the following rules:
Their declared types are identical.
If the overridden variable is a parameter that specifies
required="yes"
then the overriding variable is either
a non-parameter variable, or a parameter that specifies
required="yes"
Note:
A variable may override a parameter or vice-versa, and the initial value may differ.
Because static variables and parameters are constrained to have
visibility private
or final
, they cannot
be overridden in another package. The compatibility rules therefore
do not arise. The reason that such variables cannot be overridden
is that they are typically used during stylesheet compilation (for
example, in [xsl:]use-when
expressions) and it is a
design goal that packages should be capable of independent
compilation.
[Definition: Types S and T are considered
identical for the purpose of these rules if and only if
subtype(S, T)
and subtype(T, S)
both
hold, where the subtype relation is defined in Section 2.5.6.1
The judgement subtype(A, B)
XP30.]
Note:
One consequence of this rule is that two plain union types are considered identical if they have the same set of member types, even if the union types have different names or the ordering of the member types is different.
While this rule may appear formal, it is not as straightforward as might be supposed, because the subtype relation in XPath has a dependency on the "Type derivation OK (Simple)" relation in XML Schema, which itself appeals to a judgement as to whether the two type definitions being compared "are the same type definition". Both XSD 1.0 and XSD 1.1 add the note "The wording of [this rule] appeals to a notion of component identity which is only incompletely defined by this version of this specification." However, they go on to say that component identity is well defined if the components are named simple type definitions, which will always apply in this case. For named atomic types, the final result of these rules is that two atomic types are identical if and only if they have the same name.
Modes are not overridable, so the xsl:mode
declaration cannot appear
as a child of xsl:override
.
Within the declaration of an overriding component (that is, a
component whose declaration is a child of xsl:override
), where the
overridden component has public
visibility, it is
possible to use the name xsl:original
as a symbolic reference to the overridden
component:
Within an overriding named template, <xsl:call-template
name="xsl:original"/>
may be used to call the overridden
named template.
Within an overriding stylesheet function,
xsl:original()
may be used to call the overridden
stylesheet function.
Within an overriding global variable or parameter,
$xsl:original
may be used to reference the overridden
global variable or parameter.
Within an overriding attribute set,
[xsl:]use-attribute-set="xsl:original"
may be used to
reference the overridden attribute set.
Within an overriding accumulator, however, it is not possible to refer to the overridden accumulator.
Within the overriding component C(Q), this symbolic
reference is bound to the hidden component C′(Q)
described earlier, whose declaration is that of the component
C(P) in the used package. The static context for the
overriding declaration is augmented to include a component of the
relevant kind (function, named template, attribute set, or
variable) with the name xsl:original
.
[Definition: The process of identifying the component to which a symbolic reference applies (possibly chosen from several homonymous alternatives) is called reference binding.] A reference is called bound if the component to which it applies has been identified and fixed, and is unbound otherwise (that is, if it exists only in the form of a symbolic identifier).
Reference resolution for the components in a package occurs conceptually after a package has been fully defined and before the processing of any other package that uses it.
Note:
If packages are separately compiled, then reference resolution is likely to form part of the compilation process.
When reference resolution is performed for a component C, each symbolic reference R that is present in the declaration of C is processed as follows:
If C already contains a binding for R then this binding is retained.
If C contains no binding for R then the
processor attempts to locate a component in the containing package
of C whose visibility is not hidden
and
whose symbolic name matches R. If there is no such
component, then a static error is reported as described elsewhere
in this specification. There can never be more than one. Call the
located component D. If D has visibility
private
or final
, then C
acquires a binding that associates the symbolic reference
R with the component D. Otherwise, the
reference remains unbound.
When a package P is used by another package Q, then Q will accept components corresponding to the components in P, as described in previous sections. Until reference resolution is performed for Q, these components will have the same bindings as their corresponding components from P: a symbolic reference that was bound for a component in P will retain the same binding, and a symbolic reference that was unbound in P will remain unbound in the corresponding component in Q. Subsequently, when reference resolution is performed for package Q, these symbolic references may become bound, perhaps to components whose declaration is in Q or in some other package.
When reference resolution is performed on a package that is
intended to be used as a stylesheet (that is, for the top-level
package), symbolic references to components whose visibility is
public
are bound in the same way as references to
components whose visibility is private
or
final
. At this stage there must be no symbolic
references referring to components whose visibility is
abstract
(that is, an implementation must be provided
for every abstract component).
[ERR XTSE3080] It is a static error if a
top-level package intended for execution (as distinct from a
library package) contains symbolic references referring to
components whose visibility is abstract
.
Note:
Unresolved references are allowed at the module level but not at the package level. A stylesheet module can contain references to components that are satisfied only when the module is imported into another module that declares the missing component.
Note:
The process of resolving references (or linking) is critical to an implementation that uses separate compilation. One of the aims of these rules is to ensure that when compiling a package, it is always possible to determine the signature of called functions, templates, and other components. A further aim is to establish unambiguously in what circumstances components can be overridden, so that compilers know when it is possible to perform optimizations such as inlining of function and variable references.
Suppose a public template T calls a private function F. When the package containing these two components is referenced by a using package, the template remains public, while the function becomes hidden. Because the function becomes hidden, it can no longer conflict with any other function of the same name, or be overridden by any other function; at this stage the compiler knows exactly which function T will be calling, and can perform optimizations based on this knowledge.
The mechanism for resolving component references described in this section is consistent with the mechanism used for binding function and variable references described in the XPath specification. XPath requires these variable and function names to be present in the static context for an XPath expression. XSLT ensures that all the non-hidden functions, global variables, and global parameters in a package are present in the static context for every XPath expression that appears in that package, along with required information such as the type of a variable and the signature of a function.
The rules in the previous section apply to named components including functions, named templates, global variables, and named attribute sets. The rules for modes, and the template rules appearing within a mode, are slightly different.
The unnamed mode is local to a package: in effect, each package has its own private unnamed mode, and the unnamed mode of one package does not interact with the unnamed mode of any other package.
A named mode may be declared in an xsl:mode
declaration as being
either public
, private
, or
final
. The values of the visibility
attribute are interpreted as follows:
Value | Meaning |
---|---|
public | A using package may use
xsl:apply-templates to
invoke templates in this mode; it may also declare additional
template rules in this mode, which are selected in preference to
template rules in the used package. These may appear only as
children of the xsl:override element within
the xsl:use-package
element. |
private | A using package may neither reference the mode nor provide additional templates in this mode; the name of the mode is not even visible in the using package, so no such attempt is possible. The using package can use the same name for its own modes without risk of conflict. |
final | A using package may use
xsl:apply-templates to
invoke templates in this mode, but it must not provide additional
template rules in this mode. |
As with other named components, an xsl:use-package
declaration
may contain an xsl:expose
element to control
the visibility of a mode acquired from the used package. The
allowed values of its visibility
attribute are
public
, private
, final
, and
hidden
.
The xsl:mode
declaration itself must not be overridden. A using package must not
contain an xsl:mode
declaration whose name matches that of a public
or
final
xsl:mode
component accepted from a
used package.
The xsl:expose
and
xsl:accept
elements may
be used to reduce the visibility of a mode in a using package; the
same rules apply in general, though some of the rules are not
applicable because, for example, modes cannot be
abstract
.
It is not possible for a package to combine the template rules
from two other packages into a single mode. When xsl:apply-templates
is
used without specifying a mode, the chosen template rules will
always come from the same package; when it is used with a named
mode, then they will come from the package where the mode is
defined, or any package that uses that package and adds template
rules to the mode. If two template rules defined in different
packages match the same node, then the rule in the using package
wins over any rule in the used package; this decision is made
before taking other factors such as import precedence and priority
into account.
A static error occurs if two modes with the same name are visible within a package, either because they are both declared within the package, or because one is declared within the package and the other is acquired from a used package, or because both are accepted from different used packages.
The rules for matching template rules by precedence and priority
operate as normal, with the addition that template rules declared
within an xsl:use-package
element
have higher precedence than any template rule declared in the used
package.
When a template rule specifies mode="#all"
this is
interpreted as meaning all modes declared implicitly or explicitly
within the declaring package of the xsl:template
element.
Note:
If existing XSLT code has been written to use template rules in
the unnamed mode, a convenient way to incorporate this code into a
library package is to add a stub module that defines a new named
public
or final
mode, in which there is a
single template rule whose content is the single instruction
<xsl:apply-templates/>
. This in effect redirects
xsl:apply-templates
instructions using the named mode to the rules defined in the
unnamed mode.
Declarations of keys, decimal formats, namespace aliases (see
11.1.5 Namespace
Aliasing), output definitions, and character
maps within a package have local scope within that package —
they are all effectively private. The elements that declare these
constructs do not have a visibility
attribute. The
unnamed decimal format and the unnamed output format are also local
to a package.
If xsl:strip-space
or xsl:preserve-space
declarations appear within a library package, they only affect
calls to the doc
FO30
or document
functions
appearing within that package. Such a declaration within the main
package additionally affects stripping of whitespace in the
principal source document.
An xsl:decimal-format
declaration within a package applies only to calls on
format-number
FO30 appearing
within that package.
An xsl:namespace-alias
declarations within a package applies only to literal result
elements within the same package.
An xsl:import-schema
declaration within a package adds the names of the imported schema
components to the static context for that package only; these names
are effectively private, in the sense that they do not become
available for use in any other packages. However, the names of
schema components must be consistent across the stylesheet as a
whole: it is not possible for two different packages within a
stylesheet to use a type-name such as "part-number" to refer to
different schema-defined simple or complex types.
Type names used in the interface of public components in a package (for example, in the arguments of a function) must be respected by callers of those components, in the sense that the caller must supply values of the correct type. Often this will mean that the using component, if it contains calls on such interfaces, must itself import the necessary schema components. However, the requirement for an explicit schema import applies only where the package contains explicit use of the names of schema components required to call such interfaces.
Note:
For example, suppose a library package contains a function which
requires an argument of type mfg:part-number
. The
caller of this function must supply an argument of the correct
type, but does not need to import the schema unless it explicitly
uses the schema type name mfg:part-number
. If it
obtains an instance of this type from outside the package, for
example as the result of another function call, then it can supply
this instance to the acquired function even though it has not
imported a schema that defines this type.
At execution time, the schema available for validating instance documents contains (at least) the union of the schema components imported into all constituent packages of the stylesheet.
The capability described in this section is an optional feature that processors are not required to provide.
A processor may recognize the URI
supplied in the name
attribute of an xsl:use-package
element as
the module URI of an XQuery library module.
In this case all public functions and global variables declared in the XQuery library module become available for use in the using package as if they were declared as public functions or global variables in an XSLT 3.0 package. XQuery external variables are treated as if they were XSLT stylesheet parameters.
There are some minor differences in semantics between XSLT and XQuery, for example XSLT uses the function conversion rules when initializing a global variable (in XSLT, a node will be atomized if the required type is atomic) whereas XQuery requires the computed value to match the declared type precisely. The way in which such differences are handled is implementation-defined; a conformant implementation may use either the XQuery semantics or the XSLT semantics.
It is implementation-defined whether an
XQuery expression that is evaluated in the course of a
transformation is evaluated within the same execution
scopeFO30 as the calling XSLT code.
(It if is, then, for example, calls to
current-dateTime
will deliver the same result whether
called from the XSLT code or the XQuery code.)
It is implementation-defined whether node identity is preserved when calling XQuery code from XSLT code.
Note:
Where the XSLT implementation invokes an XQuery processor developed by a third party, it may be necessary to convert nodes to a different internal representation as part of the calling mechanism, and it may be difficult to do this conversion in a way that retains node identity. It is required, however, that nodes passed to the XQuery processor, or returned in the result, retain all their relationships to other nodes in the same tree. Furthermore, this specification provides no license to drop type annotations.
As when using multiple XSLT packages, it is required that any schema imported by the XQuery library module must be consistent with the schema imported by the using package, and that any type annotation on a node passed from one package to another must refer unambiguously to the same type.
The effect of using an XQuery library module in which there are functions that are updating or nondeterministic is implementation-defined.
Processors may impose additional
restrictions on the use of XQuery library modules; for example they
may treat variables and functions declared in the library module as
final
, or they may require that the module uses a
particular version of XQuery.
[Definition: A package consists of one or more stylesheet modules, each one forming all or part of an XML document.]
Note:
A stylesheet module is represented by an XDM element node (see
[Data Model]). In the case of a
standard stylesheet module, this will be an xsl:stylesheet
or xsl:transform
element. In the
case of a simplified stylesheet module, it can be any element (not
in the XSLT namespace) that has an
xsl:version
attribute.
Although stylesheet modules will commonly be maintained in the form of documents conforming to XML 1.0 or XML 1.1, this specification does not mandate such a representation. As with source trees, the way in which stylesheet modules are constructed, from textual XML or otherwise, is outside the scope of this specification.
A stylesheet module is either a standard stylesheet module or a simplified stylesheet module:
[Definition: A standard stylesheet
module is a tree, or part of a tree, consisting of an xsl:stylesheet
or xsl:transform
element (see
3.8 Stylesheet Element)
together with its descendant nodes and associated attributes and
namespaces.]
[Definition: A simplified stylesheet
module is a tree, or part of a tree, consisting of a literal result element together
with its descendant nodes and associated attributes and namespaces.
This element is not itself in the XSLT namespace, but it
must have an xsl:version
attribute, which implies that it must
have a namespace node that declares a binding for the XSLT
namespace. For further details see 3.9 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 but not necessarily 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.13 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
<xsl:stylesheet
id? = id
version? = decimal
default-mode? = eqname | "#unnamed"
default-validation? = "preserve" | "strip"
input-type-annotations? = "preserve" | "strip" |
"unspecified"
default-collation? = uris
extension-element-prefixes? = prefixes
exclude-result-prefixes? = prefixes
expand-text? = "yes" | "no"
use-when? = expression
xpath-default-namespace? =
uri >
<!-- Content: (xsl:use-package*,
other-declarations) -->
</xsl:stylesheet>
<xsl:transform
id? = id
version? = decimal
default-mode? = eqname | "#unnamed"
default-validation? = "preserve" | "strip"
input-type-annotations? = "preserve" | "strip" |
"unspecified"
default-collation? = uris
extension-element-prefixes? = prefixes
exclude-result-prefixes? = prefixes
expand-text? = "yes" | "no"
use-when? = expression
xpath-default-namespace? =
uri >
<!-- Content: (xsl:use-package*,
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
.
The version
attribute indicates the version of XSLT
that the stylesheet module requires. The attribute is required, unless the xsl:stylesheet
element is a
child of an xsl:package
element, in which case it is optional: the default is then taken
from the parent xsl:package
element.
[ERR XTSE0110] The value of the
version
attribute if present must be a number: specifically, it must be a valid instance of the type
xs:decimal
as defined in [XML
Schema Part 2].
The version
attribute is intended to indicate the
version of the XSLT specification against which the stylesheet is
written. In a stylesheet written to use XSLT 3.0, the value
should normally be set to
3.0
. If the value is numerically less than
3.0
, the stylesheet is processed using the rules for
backwards compatible
behavior (see 3.10 Backwards Compatible
Processing). If the value is numerically greater than
3.0
, the stylesheet is processed using the rules for
forwards compatible behavior
(see 3.11 Forwards Compatible
Processing).
The effect of the input-type-annotations
attribute
is described in 4.3 Stripping
Type Annotations from a Source Tree.
The [xsl:]default-validation
attribute defines the
default value of the validation
attribute of all
relevant instructions appearing within its scope. For details of
the effect of this attribute, see 24.2
Validation.
[ERR XTSE0120] 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
,
xsl:transform
, or
xsl:override
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.8.3 User-defined Data Elements)].
The declaration elements permitted in the
xsl:stylesheet
element are:
xsl:use-package
xsl:import
xsl:include
xsl:accumulator
xsl:attribute-set
xsl:character-map
xsl:decimal-format
xsl:function
xsl:import-schema
xsl:key
xsl:mode
xsl:namespace-alias
xsl:output
xsl:param
xsl:preserve-space
xsl:strip-space
xsl:template
xsl:variable
Note that the xsl:variable
and xsl:param
elements can act either
as declarations or as instructions. A global
variable or parameter is defined using a declaration; a local
variable or parameter using an instruction.
If there are xsl:use-package
elements,
these must come before any other
elements. If there are xsl:import
elements, these
must come after any xsl:use-package
elements
but before any other elements. Apart from this, the child
elements of the xsl:stylesheet
element may
appear in any order. In most cases, the ordering of these
elements does not affect the results of the transformation;
however, as described in 6.4 Conflict
Resolution for Template Rules, when two template rules with
the same priority match the same nodes, there are
situations where the order of the template rules will affect which
is chosen.
For the meaning of the xsl:use-package
element,
see 3.6 Packages.
default-collation
AttributeThe default-collation
attribute is a standard attribute that may appear on
any element in the XSLT namespace, or (as
xsl:default-collation
) on a literal result element.
The attribute, when it appears on an element E,
is used to specify the default collation used by all XPath
expressions appearing in attributes or text value templates that have
E as an ancestor, unless overridden by another
default-collation
attribute on an inner element. It
also determines the collation used by certain XSLT constructs (such
as xsl:key
and xsl:for-each-group
)
within its scope.
The value of the attribute is a whitespace-separated list of collation URIs. If any of these URIs is a relative URI reference, then it is resolved relative to the base URI of the attribute's parent element. If the implementation recognizes one or more of the resulting absolute collation URIs, then it uses the first one that it recognizes as the default collation.
[ERR XTSE0125] It is a static error if the
value of an [xsl:]default-collation
attribute, after
resolving against the base URI, contains no URI that the
implementation recognizes as a collation URI.
Note:
The reason the attribute allows a list of collation URIs is that
collation URIs will often be meaningful only to one particular XSLT
implementation. Stylesheets designed to run with several different
implementations can therefore specify several different collation
URIs, one for use with each. To avoid the above error condition, it
is possible to include as the last collation URI in the list either
the Unicode Codepoint Collation or a collation in the UCA
family (see 13.4 The Unicode Collation
Algorithm) with the parameter
fallback=yes
.
The [xsl:]default-collation
attribute does not
affect the collation used by xsl:sort
.
In the absence of an [xsl:]default-collation
attribute, the default collation may be
set by the calling application in an implementation-defined way. The
recommended default, unless the user chooses otherwise, is to use
the Unicode codepoint collation.
[xsl:]default-mode
AttributeThe default-mode
attribute defines the default
value for the mode attribute of all xsl:template
and xsl:apply-templates
elements within its scope. When the
mode
attribute of these elements is omitted, or when
it contains the value #default
, then the mode is taken
from the [xsl:]default-mode
attribute of the innermost
ancestor element that has such an attribute. If there is no such
element, then the default is the unnamed mode. This is
equivalent to specifying #unnamed
.
The value must either be an
EQName, or the token #unnamed
which refers to the unnamed mode. It is not necessary for the
referenced mode to be explicitly declared in an xsl:mode
declaration.
Note:
This attribute is provided to support an approach to stylesheet modularity in which all the template rules for one mode are collected together into a single stylesheet module. Using this attribute reduces the risk of forgetting to specify the mode in one or more places where it is needed, and it also makes it easier to reuse an existing stylesheet module that does not use modes in an application where modes are needed to avoid conflicts with existing template rules.
[Definition: In addition to declarations, the xsl:stylesheet
element may
contain among its children 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 XTSE0130] 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 23 Extensibility and Fallback),
information about what to do with any final result tree,
information about how to construct source trees,
optimization hints for the processor,
metadata about the stylesheet,
structured documentation for the stylesheet.
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="3.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="3.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="3.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> <xsl:template name="expand"> <xsl:element name="xsl:stylesheet"> <xsl:attribute name="version" select="@xsl:version"/> <xsl:element name="xsl:template"> <xsl:attribute name="match" select="'/'"/> <xsl:copy-of select="."/> </xsl:element> </xsl:element> </xsl:template> </xsl:stylesheet>
[ERR XTSE0150] 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
3.0
; the value must be a valid instance of the type
xs:decimal
as defined in [XML
Schema Part 2].
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. Simplified stylesheets
therefore cannot use template rules, global variables,
stylesheet parameters, stylesheet functions, keys, attribute-sets, or
output definitions. In turn this means
that the only useful way to initiate the transformation is to
supply a document node as the initial context
item, to be matched by the implicit
match="/"
template rule using the unnamed
mode.
[Definition: The effective version of an element
in a stylesheet module or package manifest is the decimal
value of the [xsl:]version
attribute (see 3.5 Standard Attributes) on that
element or on the innermost ancestor element that has such an
attribute, excluding the version
attribute on an
xsl:output
element.]
[Definition: An element is processed with
backwards compatible behavior if its effective version is less than
3.0
.]
Specifically:
If the effective version is equal to 1.0, then the element is processed with XSLT 1.0 behavior as described in 3.10.1 XSLT 1.0 Compatibility Mode.
If the effective version is equal to 2.0, then the element is processed with XSLT 2.0 behavior as described in 3.10.2 XSLT 2.0 Compatibility Mode.
If the effective version is any other value less than 3.0, the recommended action is to report a static error; however, processors may recognize such values and process the element in an implementation-defined way.
Note:
XSLT 1.0 allowed the version
attribute to take any
decimal value, and invoked forwards compatible processing for any
value other than 1.0. XSLT 2.0 allowed the attribute to take any
decimal value, and invoked backwards compatible (i.e.
1.0-compatible) processing for any value less than 2.0. Some
stylesheets may therefore be encountered that use values other than
1.0 or 2.0. In particular, the value 1.1 is sometimes encountered,
as it was used at one stage in a draft language proposal.
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.
It is implementation-defined whether a particular XSLT 3.0 implementation supports backwards compatible behavior for any XSLT version earlier than XSLT 3.0.
[ERR XTDE0160] It is a dynamic error if an element has an effective version of V (with V < 3.0) when the implementation does not support backwards compatible behavior for XSLT version V.
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 3.0 processor are identical to the effects of processing the same stylesheet using a processor for an earlier version of XSLT. 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 3.0 processor are defined by the XDM 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 3.0 and XPath 3.0 specifications, it is not defined by reference to earlier versions of the XSLT and XPath specifications.
To write a stylesheet that makes use of features that are
new in version N, while also working with a processor
that only supports XSLT version M (M <
N), it is necessary to understand both the rules
for backwards compatible behavior in XSLT version
N, and the rules for forwards compatible behavior
in XSLT version M. If the xsl:stylesheet
element
specifies version="2.0"
or
version="3.0"
, then an XSLT 1.0 processor will
ignore XSLT 2.0 and XSLT 3.0 declarations that were
not defined in XSLT 1.0, for example xsl:function
and xsl:import-schema
. If any
new XSLT 3.0 instructions are used (for example
xsl:evaluate
or
xsl:stream
), or if new
XPath 3.0 features are used (for example, new
functions, or let expressions), then the stylesheet
must provide fallback behavior that relies only on facilities
available in the earliest XSLT version supported. 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 in the stylesheet is processed with XSLT 1.0 behavior if its effective version is equal to 1.0.]
In this mode, if any attribute contains an XPath expression,
then the expression is evaluated with XPath 1.0 compatibility mode set to
true
. For details of this mode, see Section 2.1.1
Static Context XP30.
Expressions contained in text value
templates are always evaluated with XPath 1.0 compatibility mode set to
false
, since this construct was not available in XSLT
1.0.
Furthermore, in such an expression any function call for which no implementation is available (unless it uses the standard function namespace) is bound to a fallback error function whose effect when evaluated is to raise a dynamic error [see ERR XTDE1425] . The effect is that with backwards compatible behavior enabled, calls on extension functions that are not available in a particular implementation do not cause an error unless the function call is actually evaluated. For further details, see 23.1 Extension Functions.
Note:
This might appear to contradict the specification of XPath 3.0, which states that a static error [XPST0017] is raised when an expression contains a call to a function that is not present (with matching name and arity) in the static context. This apparent contradiction is resolved by specifying that the XSLT processor constructs a static context for the expression in which every possible function name and arity (other than names in the standard function namespace) is present; when no other implementation of the function is available, the function call is bound to a fallback error function whose run-time effect is to raise a dynamic error.
Certain XSLT constructs also produce different results when XSLT 1.0 compatibility mode is enabled. This is described separately for each such construct.
[Definition: An element is processed with XSLT 2.0 behavior if its effective version is equal to 2.0.]
In this specification, no differences are defined for XSLT 2.0 behavior. An XSLT 3.0 processor will therefore produce the same results whether the effective version of an element is set to 2.0 or 3.0.
Note:
An XSLT 2.0 processor, by contrast, will in some cases produce
different results in the two cases. For example, if the stylesheet
contains an xsl:iterate
instruction with an xsl:fallback
child, an XSLT
3.0 processor will process the xsl:iterate
instruction
regardless whether the effective version is 2.0 or 3.0, while an
XSLT 2.0 processor will report a static error if the effective
version is 2.0, and will take the fallback action if the effective
version is 3.0.
The intent of forwards compatible behavior is to make it possible to write a stylesheet that takes advantage of features introduced in some version of XSLT subsequent to XSLT 3.0, while retaining the ability to execute the stylesheet with an XSLT 3.0 processor using appropriate fallback behavior.
It is always possible to write conditional code to run under
different XSLT versions by using the use-when
feature
described in 3.14 Conditional
Element Inclusion. The rules for forwards compatible
behavior supplement this mechanism in two ways:
certain constructs in the stylesheet that mean nothing to an XSLT 3.0 processor are ignored, rather than being treated as errors.
explicit fallback behavior can be defined for instructions
defined in a future XSLT release, using the xsl:fallback
instruction.
The detailed rules follow.
[Definition: An element is processed with
forwards compatible behavior if its effective version is greater than
3.0
.]
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.
When an element is processed with forwards compatible behavior:
if the element is in the XSLT namespace and appears as a child
of the xsl:stylesheet
element, and
XSLT 3.0 does not allow the element to appear as a
child of the xsl:stylesheet
element, then
the element and its content must be
ignored.
if the element has an attribute that XSLT 3.0 does not allow the element to have, then the attribute must be ignored.
if the element is in the XSLT namespace and appears as part of a sequence constructor, and XSLT 3.0 does not allow such elements to appear as part of a sequence constructor, then:
If the element has one or more xsl:fallback
children, then no
error is reported either statically or dynamically, and the result
of evaluating the instruction is the concatenation of the sequences
formed by evaluating the sequence constructors within its xsl:fallback
children, in
document order. Siblings of the xsl:fallback
elements are
ignored, even if they are valid XSLT 3.0
instructions.
If the element has no xsl:fallback
children, then a
static error is reported in the same way as if forwards compatible
behavior were not enabled.
For example, an XSLT 3.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:exciting-new-17.0-feature> <xsl:fly-to-the-moon/> <xsl:fallback> <html> <head> <title>XSLT 17.0 required</title> </head> <body> <p>Sorry, this stylesheet requires XSLT 17.0.</p> </body> </html> </xsl:fallback> </xsl:exciting-new-17.0-feature> </xsl:template> </xsl:stylesheet>
Note:
If a stylesheet depends crucially on a declaration introduced
by a version of XSLT after 3.0, then the stylesheet
can use an xsl:message
element with terminate="yes"
(see 22.1 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')) lt 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>
Note:
The XSLT 1.0 and XSLT 2.0 specifications did not anticipate the
introduction of the xsl:package
element. An XSLT
1.0 or 2.0 processor encountering this element will report a static
error, regardless of the version
setting.
This problem can be circumvented by using the simplified package
syntax (whereby xsl:use-package
appears as
a child of xsl:stylesheet
, or by
writing the stylesheet code in a separate module from the package
manifest, and using the separate module as the version of the
stylesheet that is presented to a 2.0 processor.
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
reference, it is resolved as described in 5.9 URI References.
After resolving against the base URI, the way in which the URI reference is used to locate a representation of a stylesheet module, and the way in which the stylesheet module is constructed from that representation, are 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.9 Simplified Stylesheet Modules.
Implementations may choose to accept URI references containing a fragment identifier defined by reference to the XPointer specification (see [XPointer Framework]). 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 XTSE0165] 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.
Note:
It is appropriate to use this error code when the resource cannot be retrieved, or when the retrieved resource is not well formed XML. If the resource contains XML than can be parsed but that violates the rules for stylesheet modules, then a more specific error code may be more appropriate.
<!-- Category: declaration
-->
<xsl:include
href = uri />
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.12.1 Locating
Stylesheet Modules.
[ERR XTSE0170] 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 XTSE0180] 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 />
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.12.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.12.1 Locating
Stylesheet Modules.
[ERR XTSE0190] An xsl:import
element must be a top-level element.
xsl:import
For example,
<xsl:stylesheet version="3.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:
Here you should see a diagram. If it does not appear correctly in your browser, you need to install an SVG Plugin.
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 XTSE0210] 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.
An embedded stylesheet module is a stylesheet module whose containing element is not the outermost element of the containing XML document. Both standard stylesheet modules and simplified stylesheet modules may be embedded in this way.
Two situations where embedded stylesheets may be useful are:
The stylesheet may be embedded in the source document to be transformed.
The stylesheet may be embedded in an XML document that describes a sequence of processing of which the XSLT transformation forms just one part.
The xsl:stylesheet
element
may have an id
attribute to
facilitate reference to the stylesheet module within the containing
document.
Note:
In order for such an attribute value to be used as a fragment
identifier in a URI, the XDM attribute node must generally have the
is-id
property: see Section 5.5
is-id Accessor DM30. This property
will typically be set if the attribute is defined in a DTD as being
of type ID
, or if is defined in a schema as being of
type xs:ID
. It is also necessary that the media type
of the containing document should support the use of ID values as
fragment identifiers. Such support is widespread in existing
products, and is endorsed in respect of the media type
application/xml
by [XPointer
Framework].
An alternative, if the implementation supports it, is to use an
xml:id
attribute. XSLT allows this attribute (like
other namespaced attributes) to appear on any XSLT
element.
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 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="3.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 is the officially registered media type for
XSLT: see 3.4 XSLT Media
Type. However, browsers developed before this media type
was registered are more likely to accept the unofficial designation
type="text/xsl"
.
Note:
Support for the xml-stylesheet
processing
instruction is not required for conformance with this
Recommendation. Implementations are not constrained in the
mechanisms they use to identify a stylesheet when a transformation
is initiated: see 2.3 Initiating a
Transformation.
Any element in the XSLT namespace may have a
use-when
attribute whose value is an XPath expression
that can be evaluated statically. If the attribute is present and
the effective
boolean valueXP30 of the expression
is false, then the element, together with all the nodes having that
element as an ancestor, is effectively excluded from the stylesheet module. When a node is
effectively excluded from a stylesheet module the stylesheet module
has the same effect as if the node were not there. Among other
things this means that no static or dynamic errors will be reported
in respect of the element and its contents, other than errors in
the use-when
attribute itself.
Note:
This does not apply to XML parsing or validation errors, which
will be reported in the usual way. It also does not apply to
attributes that are necessarily processed before
[xsl:]use-when
, examples being xml:space
and [xsl:]xpath-default-namespace
.
A literal result element, or any
other element within a stylesheet module that is not in
the XSLT namespace, may similarly carry an
xsl:use-when
attribute.
If the xsl:stylesheet
or xsl:transform
element itself
is effectively excluded, the effect is to exclude all the children
of the xsl:stylesheet
or xsl:transform
element, but
not the xsl:stylesheet
or xsl:transform
element or its
attributes.
Note:
This allows all the declarations that depend on the same
condition to be included in one stylesheet module, and for their
inclusion or exclusion to be controlled by a single
use-when
attribute at the level of the module.
Conditional element exclusion happens after stripping of whitespace text nodes from the stylesheet, as described in 4.2 Stripping Whitespace from the Stylesheet.
The XPath expression used as the value of the
xsl:use-when
attribute follows the rules for static expressions.
The use of [xsl:]use-when
is illustrated in the
following examples.
This example demonstrates the use of the use-when
attribute to achieve portability of a stylesheet across
schema-aware and non-schema-aware processors.
<xsl:import-schema schema-location="http://example.com/schema" use-when="system-property('xsl:is-schema-aware')='yes'"/> <xsl:template match="/" use-when="system-property('xsl:is-schema-aware')='yes'" priority="2"> <xsl:result-document validation="strict"> <xsl:apply-templates/> </xsl:result-document> </xsl:template> <xsl:template match="/"> <xsl:apply-templates/> </xsl:template>
The effect of these declarations is that a non-schema-aware
processor ignores the xsl:import-schema
declaration and the first template rule, and therefore generates no
errors in respect of the schema-related constructs in these
declarations.
This example includes different stylesheet modules depending on which XSLT processor is in use.
<xsl:include href="module-A.xsl" use-when="system-property('xsl:vendor')='vendor-A'"/> <xsl:include href="module-B.xsl" use-when="system-property('xsl:vendor')='vendor-B'"/>
Every XSLT 3.0 processor includes the following named type definitions in the in-scope schema components:
All built-in types defined in [XML
Schema Part 2], including xs:anyType
and
xs:anySimpleType
.
The following types defined in [XPath
3.0]: xs:yearMonthDuration
,
xs:dayTimeDuration
, xs:anyAtomicType
,
xs:untyped
, and xs:untypedAtomic
.
XSLT 3.0 processors may optionally
include types defined in XSD 1.1 (see [XML
Schema]). XSD 1.1 adopts the types
xs:yearMonthDuration
, xs:dayTimeDuration
,
and xs:anyAtomicType
previously defined in XPath 2.0,
and adds one new type: xs:dateTimeStamp
. XSD 1.1 also
allows implementors to define additional primitive types, and XSLT
3.0 permits such types to be supported by an XSLT processor.
A schema-aware XSLT processor additionally supports:
User-defined types, and element and attribute declarations, that
are imported using an xsl:import-schema
declaration as described in 3.16
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 Schema Documents or the Schema for Schema Documents
(Datatypes). The Schema for Schema Documents, as well as defining
built-in types such as xs:integer
and
xs:double
, also defines types that are intended for
use only within that schema, such as
xs:derivationControl
. A stylesheet that is designed to
process XML Schema documents as its input or output may import the
Schema for Schema Documents.
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 23.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 26 Conformance.
<!-- Category: declaration
-->
<xsl:import-schema
namespace? = uri
schema-location? = uri >
<!-- Content: xs:schema? -->
</xsl:import-schema>
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.15 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 package, 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 within the declaring package; importing components in one stylesheet module makes them available throughout the package.
The schema components imported into different packages within a stylesheet must be consistent. Specifically, it is not permitted to use the same name in the same XSD symbol space to refer to different schema components within different packages; and the union of the schema components imported into the packages of a stylesheet must constitute a valid schema (as well as the set of schema components imported into each package forming a valid schema in its own right).
The namespace
and schema-location
attributes are both optional.
If the xsl:import-schema
element
contains an xs:schema
element, then the
schema-location
attribute must be absent, and one of the following must be true:
the namespace
attribute of the xsl:import-schema
element
and the targetNamespace
attribute of the
xs:schema
element are both absent (indicating a
no-namespace schema), or
the namespace
attribute of the xsl:import-schema
element
and the targetNamespace
attribute of the
xs:schema
element are both present and both have the
same value, or
the namespace
attribute of the xsl:import-schema
element
is absent and the targetNamespace
attribute of the
xs:schema
element is present, in which case the target
namespace is as given on the xs:schema
element.
[ERR XTSE0215] It is a static error if an
xsl:import-schema
element that contains an xs:schema
element has a
schema-location
attribute, or if it has a
namespace
attribute that conflicts with the target
namespace of the contained schema.
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 it is explicitly present, or is implied by the
targetNamespace
attribute of a contained
xs:schema
element, 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. If there is
a contained xs:schema
element, the effective value of
the schemaLocation
attribute is a URI referencing a
document containing a copy of the xs:schema
element.
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 XTSE0220] 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 is a URI
Reference that 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.
An inline schema document (using an xs:schema
element as a child of the xsl:import-schema
element)
has the same status as an external schema document, in the sense
that it acts as a hint for a source of schema components in the
relevant namespace. To ensure that the inline schema document is
always used, it is advisable to use a target namespace that is
unique to this schema document.
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 following example shows an inline schema document. This
declares a simple type local:yes-no
, which the
stylesheet then uses in the declaration of a variable.
The example assumes the namespace declaration
xmlns:local="http://example.com/ns/yes-no"
<xsl:import-schema> <xs:schema targetNamespace="http://example.com/ns/yes-no" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:local="http://example.com/ns/yes-no"> <xs:simpleType name="yes-no"> <xs:restriction base="xs:string"> <xs:enumeration value="yes"/> <xs:enumeration value="no"/> </xs:restriction> </xs:simpleType> </xs:schema> </xsl:import-schema> <xsl:variable name="condition" select="local:yes-no('yes')" as="local:yes-no"/>
The data model used by XSLT is the XPath 3.0 and XQuery 3.0 data model (XDM), 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 XDM as it is used by XSLT:
The rules in 4.2 Stripping Whitespace from the Stylesheet and 4.4 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 XDM tree 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 XDM data model defined in [Data Model] is capable of representing either an XML 1.0 document (conforming to [XML 1.0] and [Namespaces in XML]) or an XML 1.1 document (conforming to [XML 1.1] and [Namespaces in XML 1.1]), and it makes no distinction between the two. In principle, therefore, XSLT 3.0 can be used with either of these XML versions.
Construction of the XDM tree is outside the scope of this specification, so XSLT 3.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 25 Serialization), though from a conformance point of view it is an optional feature. Although facilities are described for serializing the XDM tree 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 XDM tree 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 3.0 and XPath 3.0, for example the productions CharXML and NCNameNames, 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 (and, indeed, between different editions of XML 1.0). Implementations may support any version; it is recommended that an XSLT 3.0 processor that implements the 1.1 versions should also provide a mode that supports the 1.0 versions. It is thus implementation-defined whether the XSLT processor supports XML 1.0 with XML Namespaces 1.0, or XML 1.1 with XML Namespaces 1.1, or supports both versions at user option.
Note:
The specification referenced as [Namespaces in XML] was actually published without a version number.
The current version of [XML Schema
Part 2] (that is, XSD 1.0) does not reference the XML 1.1
specifications. This means that datatypes such as
xs:NCName
and xs:ID
are constrained by
the XML 1.0 rules, and do not allow the full range of values
permitted by XML 1.1. This situation will not be resolved until a
new version of [XML Schema Part 2]
becomes available; in the meantime, it is recommended that implementers wishing to support XML
1.1 should consult [XML Schema 1.0
and XML 1.1] for guidance. An XSLT 3.0 processor
that supports XML 1.1 should implement
the rules in later versions of [XML Schema
Part 2] 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:accumulator
xsl:analyze-string
xsl:apply-imports
xsl:apply-templates
xsl:attribute-set
xsl:call-template
xsl:character-map
xsl:choose
xsl:evaluate
xsl:fork
xsl:merge
xsl:merge-source
xsl:mode
xsl:next-iteration
xsl:next-match
xsl:override
xsl:package
xsl:stylesheet
xsl:transform
xsl:use-package
Any whitespace text node whose immediate
following-sibling node is an xsl:param
or xsl:sort
element is removed from
the tree, regardless of any xml:space
attributes.
Any whitespace text node whose immediate
preceding-sibling node is an xsl:catch
or xsl:on-completion
element
is removed from the tree, regardless of any xml:space
attributes.
[ERR XTSE0260] 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.
Note:
Using xml:space="preserve"
in parts of the
stylesheet that contain sequence constructors
will cause whitespace text nodes in that part of the
stylesheet to be copied to the result of the sequence
constructor. When the result of the sequence constructor is
used to form the content of an element, this can cause errors if
such text nodes are followed by attribute nodes generated using
xsl:attribute
.
Note:
If an xml:space
attribute is specified on a
literal result element, it will be
copied to the result tree in the same way as any other
attribute.
[Definition: The
term type annotation is used in this specification to refer
to the value returned by the dm:type-name
accessor of
a node: see Section
5.14 type-name Accessor
DM30.]
There is sometimes a requirement to write stylesheets that
produce the same results whether or not the source documents have
been validated against a schema. To achieve this, an option is
provided to remove any type annotations on element and attribute
nodes in a source tree, replacing them with an
annotation of xs:untyped
in the case of element nodes,
and xs:untypedAtomic
in the case of attribute
nodes.
Such stripping of type annotations can be requested by
specifying input-type-annotations="strip"
on the
xsl:package
element.
This attribute has three permitted values: strip
,
preserve
, and unspecified
. The default
value is unspecified
.
The input-type-annotations
attribute may also be
specified on the xsl:stylesheet
element; if
it is specified at this level then it must be consistent for all
stylesheet modules within the same package.
[ERR XTSE0265] It is a static error if there
is a stylesheet module in a package that
specifies input-type-annotations="strip"
and another
stylesheet module that specifies
input-type-annotations="preserve"
, or if a
stylesheet module specifies the value strip
or
preserve
and the same value is not specified on the
xsl:package
element of
the containing package.
The source trees to which this applies are the
same as those affected by xsl:strip-space
and
xsl:preserve-space
:
see 4.4 Stripping Whitespace from a Source
Tree. As with whitespace stripping, the rules for
stripping of type annotations may vary from one package to another,
and have the effect of modifying the mapping from URIs to document
nodes defined in the XPath dynamic context; this means that two
calls to the doc
FO30
function (for example) supplying the same URI may produce different
document nodes if the calls appear in different
packages.
When type annotations are stripped, the following changes are made to the source tree:
The type annotation of every element node is changed to
xs:untyped
The type annotation of every attribute node is changed to
xs:untypedAtomic
The typed value of every element and attribute node is set to be
the same as its string value, as an instance of
xs:untypedAtomic
.
The is-nilled
property of every element node is set
to false
.
The values of the is-id
and is-idrefs
properties are not changed.
Note:
Stripping type annotations does not necessarily return the
document to the state it would be in had validation not taken
place. In particular, any defaulted elements and attributes that
were added to the tree by the validation process will still be
present , and elements and attributes validated as IDs will still
be accessible using the id
FO30
function.
A source tree 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.
For the purposes of this section, the term source tree
means the document containing the initial context
item if it is a node, any document returned by the
functions document
,
doc
FO30,
or collection
FO30,
and any document read using xsl:stream
. It does not
include documents passed as the values of stylesheet parameters or
parameters of the initial template or function, nor values
returned from extension functions.
Each source tree is associated with a package: the relevant
package for the initial context item is the top-level package; the
relevant package for a call on document
, doc
FO30,
or collection
FO30;
is the package in which that call appears; and the relevant package
for evaluation of xsl:stream
is the package in
which that instruction appears.
The stripping process takes as input a set of element names
whose child whitespace text nodes are to be
preserved. The way in which this set of element names is
established using the xsl:strip-space
and
xsl:preserve-space
declarations is described later in this section.
Formally, the stripping process modifies the mapping from URIs
to document nodes defined in the XPath dynamic context. This
mapping can therefore vary from one package to another. The mapping
that applies to a particular call on document
, doc
FO30,
or collection
FO30,
or a particular evaluation of xsl:stream
, is affected by the
xsl:strip-space
and
xsl:preserve-space
declarations within the package in which that construct appears.
This means that two calls on the doc
FO30
function (for example) may return different nodes if the calls
appear in different packages.
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.
<!-- 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 NameTestsXP30;
an element name matches an xsl:strip-space
or xsl:preserve-space
element if it matches one of the NameTestsXP30.
An element matches a NameTestXP30
if and only if the NameTestXP30
would be true for the element as an XPath node test.
The effect of xsl:strip-space
and
xsl:preserve-space
is local to the package in which they appear. Declarations within
a library package only affect the handling of documents loaded
using a call on the document
, doc
FO30,
or collection
FO30
functions or an evaluation of an xsl:stream
instruction
appearing lexically within the same package. Declarations within
the top-level package also affect the processing of the main input
document.
[ERR XTSE0270] It is a static error if
within any package the same NameTestXP30
appears in both an xsl:strip-space
and an
xsl:preserve-space
declaration if both have the same import precedence.
Two NameTests are considered the same if they match the same set of
names (which can be determined by comparing them after expanding
namespace prefixes to URIs).
Otherwise, when more than one xsl:strip-space
and
xsl:preserve-space
element within the relevant package matches, the best
matching element is determined by the best matching NameTestXP30.
The rules are similar to those for 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.
If several matches have the same default priority
(which can only happen if one of the NameTests takes the form
*:local
and the other takes the form
prefix:*
), then the declaration that appears last in
declaration order is used.
If an element in a source document has a type
annotation that is a simple type or a complex type with simple
content, then any whitespace text nodes among its children are
preserved, regardless of any xsl:strip-space
declarations. The reason for this is that stripping a whitespace
text node from an element with simple content could make the
element invalid: for example, it could cause the
minLength
facet to be violated.
Stripping of type annotations happens before stripping of
whitespace text nodes, so this situation will not occur if
input-type-annotations="strip"
is specified.
Note:
In [Data Model], processes are
described for constructing an XDM tree from an Infoset or from a
PSVI. Those processes deal with whitespace according to their own
rules, and the provisions in this section apply to the resulting
tree. In practice this means that elements that are defined in a
DTD or a Schema to contain element-only content will have whitespace text nodes stripped,
regardless of the xsl:strip-space
and
xsl:preserve-space
declarations in the stylesheet.
However, source trees are not necessarily constructed using those processes; indeed, they are not necessarily constructed by parsing XML documents. Nothing in the XSLT specification constrains how the source tree is constructed, or what happens to whitespace text nodes during its construction. The provisions in this section relate only to whitespace text nodes that are present in the tree supplied as input to the XSLT processor. The XSLT processor cannot preserve whitespace text nodes unless they were actually present in the supplied tree.
The mapping from the Infoset to the XDM data model, described in
[Data Model], does not retain
attribute types. This means, for example, that an attribute
described in the DTD as having attribute type NMTOKENS
will be annotated in the XDM tree as xs:untypedAtomic
rather than xs:NMTOKENS
, and its typed value will
consist of a single xs:untypedAtomic
value rather than
a sequence of xs:NMTOKEN
values.
Attributes with a DTD-derived type of ID, IDREF, or IDREFS will
be marked in the XDM tree as having the is-id
or
is-idrefs
properties. It is these properties, rather
than any type annotation, that are examined by the
functions id
FO30
and idref
FO30
described in [Functions and
Operators].
The data model for nodes in a document that is being streamed is no different from the standard XDM data model, in that it contains the same objects (nodes) with the same properties and relationships. The facilities for streaming do not change the data model; instead they impose rules that limit the ability of stylesheets to navigate the data model.
A useful way to visualize streaming is to suppose that at any point in time, there is a current position in the streamed input document which may be the start or end of the document, the start or end tag of an element, or a text, comment, or processing instruction node. From this position, the stylesheet has access to the following information:
Properties intrinsic to the node, such as its name, its base
URI, its type annotation, and its is-id
and
is-idref
properties.
The ancestors of the node (but navigation downwards from the ancestors is not permitted).
The attributes of the node, and the attributes of its ancestors. For each such attribute, all the properties of the node including its string value and typed value are available, but there are limitations that restrict navigation from the attribute node to other nodes in the document.
The in-scope namespace bindings of the node.
In the case of attributes, text nodes, comments, and processing instructions, the string value and typed value of the node.
Summary data about the preceding siblings of the node, and of
each of its ancestor nodes: specifically, for each distinct
combination of node kind, node name, and type annotation, a count
of the number of preceding siblings that have that combination of
properties. This information allows patterns such as
match="para[1]"
to be used, and it permits some
limited use of the xsl:number
instruction.
The children and other descendants of a node are not accessible except as a by-product of changing the current position in the document. The same applies to properties of an element or document node that require examination of the node's descendants, that is, the string value and typed value. This is enforced by means of a rule that only one expression requiring downward navigation from a node is permitted.
There is an assumption that information about unparsed entities is available at all times during the processing of a document. This has two implications: firstly, the processor may need to read ahead at the start of the document to determine this information so that it is available while processing the document root node; and secondly, the information then needs to be retained for the duration of the processing.
Expressions such as (/) instance of
document-node(element(invoice))
also require look-ahead as
far as the start-tag of the first element.
A streaming processor is required to read only as much of the source document as is needed to generate correct stylesheet output. It is not required to read the full source document merely in order to satisfy the requirement imposed by the XML Recommendation that an XML Processor must report violations of well-formedness in the input.
More detailed rules are defined in 19 Streamability.
The XDM data model (see [Data Model]) leaves it to the host language to define limits. This section describes the limits that apply to XSLT.
Limits on some primitive datatypes are defined in [XML Schema Part 2]. Other limits, listed below, are implementation-defined. Note that this does not necessarily mean that each limit must be a simple constant: it may vary depending on environmental factors such as available resources.
The following limits are implementation-defined:
For the xs:decimal
type, the maximum number of
decimal digits (the totalDigits
facet). This must be
at least 18 digits. (Note, however, that support for the full value
range of xs:unsignedLong
requires 20 digits.)
For the types xs:date
, xs:time
,
xs:dateTime
, xs:gYear
, and
xs:gYearMonth
: the range of values of the year
component, which must be at least +0001 to +9999; and the maximum
number of fractional second digits, which must be at least 3.
For the xs:duration
type: the maximum absolute
values of the years, months, days, hours, minutes, and seconds
components.
For the xs:yearMonthDuration
type: the maximum
absolute value, expressed as an integer number of months.
For the xs:dayTimeDuration
type: the maximum
absolute value, expressed as a decimal number of seconds.
For the types xs:string
, xs:hexBinary
,
xs:base64Binary
, xs:QName
,
xs:anyURI
, xs:NOTATION
, and types derived
from them: the maximum length of the value.
For sequences, the maximum number of items in a sequence.
For backwards compatibility reasons, XSLT 3.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
25.1 Character Maps)
was 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
and xsl:value-of
, (see 25.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.
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 a qualified name: that is, it consists of a local name and an optional namespace URI.
In most cases where such names are written in a stylesheet, the syntax for expressing the name is given by the production EQNameXP30 in the XPath specification. In practice, this means that three forms are permitted:
A simple NCName
appearing on its own (without any
prefix). This represents the local name of the object. The
interpretation of unprefixed names is described below.
A lexical QName written in the form
NCName ":" NCName
where the first part is a namespace
prefix and the second part is the local name. The namespace part of
the object's name is then derived from the prefix by examining the
in-scope namespace bindings of the element node in the stylesheet
where the name appears.
A URIQualifiedNameXP30
in the form "Q{" URI? "}" NCName
where the two parts
of the name, that is the namespace part and the local part, both
appear explicitly. If the URI part is omitted (for example
Q{}local
), the resulting expanded QName is a QName
whose namespace part is absent.
Note:
There are a few places where the third form, a URIQualifiedName,
is not permitted. These include the name
attribute of
xsl:element
and
xsl:attribute
(which
have a separate namespace
attribute for the purpose),
and constructs defined by other specifications. For example, names
appearing within an embedded xs:schema
element must
follow the XSD rules.
[Definition: An expanded QName is a value in the
value space of the xs:QName
datatype as defined in the
XDM data model (see [Data
Model]): that is, a triple containing namespace prefix
(optional), namespace URI (optional), and local name. Two expanded
QNames are equal if the namespace URIs are the same (or both
absent) and the local names are the same. The prefix plays no part
in the comparison, but is used only if the expanded QName needs to
be converted back to a string.]
[Definition: An EQName is a string representing a expanded QName where the string, after removing leading and trailing whitespace, is in the form defined by the EQNameXP30 production in the XPath specification.]
[Definition: A lexical QName is a string representing
a expanded QName where the string, after
removing leading and trailing whitespace, is within the lexical
space of the xs:QName
datatype as defined in XML
Schema (see [XML Schema Part 2]): that
is, a local name optionally preceded by a namespace prefix and a
colon.]
Note that every lexical QName is an EQName, but the converse is not true.
The following rules are used when interpreting a lexical QName:
[Definition: A string in the form of a lexical QName may occur as the value of an attribute node in a stylesheet module, or within an XPath expression contained in an attribute or text node within a stylesheet module, or as the result of evaluating an XPath expression contained in such a node. The element containing this attribute or text node is referred to as the defining element of the lexical QName.]
If the lexical 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 of the defining element (see Section 6.2 Element Nodes DM30) is not used for unprefixed names.
[ERR XTSE0280] In the case of a prefixed lexical QName used as the value (or as part of 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 lexical QName.
[ERR XTDE0290] Where the result of evaluating an XPath expression (or an attribute value template) is required to be a lexical QName, or if it is permitted to be a lexical QName and the actual value takes the form of a lexical QName, then unless otherwise specified it is a dynamic error if the value has a prefix and the defining element has no namespace node whose name matches that prefix. This error may be signaled as a static error if the value of the expression can be determined statically.
If the lexical QName has no prefix, then:
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 Lexical QNames in
Expressions and Patterns.
If the name is in one of the following categories, then the default namespace of the defining element is used:
Where a QName is used to define the name of an element being
constructed. 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
.
The default namespace applies to any unqualified element names
appearing in the cdata-section-elements
attribute of
xsl:output
or xsl:result-document
In all other cases, a lexical QName with no prefix
represents an expanded QName in no namespace (that is,
an xs:QName
value in which both the prefix and the
namespace URI are absent).
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 or text node of
that element (including XPath expressions in attribute value templates
and text value templates). The
effect of this is specified in [XPath 3.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 element
any unprefixed type name used in the type
attribute
of an XSLT element
any unprefixed type name used in the xsl:type
attribute of a literal result element.
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 of the parent element (see Section 6.2 Element Nodes DM30) is not used.
The attribute does not affect other names, for example function
names, variable names, or template names, or strings that are
interpreted as lexical QNames during stylesheet
evaluation, such as the effective value of the
name
attribute of xsl:element
or the string
supplied as the first argument to the key
function.
XSLT uses the expression language defined by XPath 3.0 [XPath 3.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 a result tree.
[Definition: Within this specification, the term XPath expression, or simply expression, means a string that matches the production ExprXP30 defined in [XPath 3.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 and text value templates.
Except where forwards compatible behavior is enabled (see 3.11 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 or text value template, does not match the XPath production ExprXP30, 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. Error codes are defined in [XPath 3.0].
The transformation fails with a dynamic error if any XPath expression is evaluated and raises a dynamic error. Error codes are defined in [XPath 3.0].
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. Error codes are defined in [XPath 3.0].
[Definition: The context within a stylesheet where an XPath
expression appears may specify the required
type of the expression. The required type indicates the type of
the 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 3.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 3.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 contextXP30 which contains all the information that can affect the result of evaluating an expression. The expression context has two parts, the static contextXP30, and the dynamic contextXP30. The components that make up the expression context are defined in the XPath specification (see Section 2.1 Expression Context XP30). This section describes the way in which these components are initialized when an XPath expression is contained within an XSLT stylesheet.
As well as providing values for the static and dynamic context
components defined in the XPath specification, XSLT defines
additional context components of its own. These context components
are used by XSLT instructions (for example, xsl:next-match
and xsl:apply-imports
), and
also by the functions in the extended function library described in
this specification.
The following four sections describe:
5.4.1 Initializing the Static Context
5.4.2 Additional Static Context Components used by XSLT
5.4.3 Initializing the Dynamic Context
5.4.4 Additional Dynamic Context Components used by XSLT
The static contextXP30 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 or text node whose value contains the XPath expression in question, and the term enclosing element means the containing element or any of its ancestors.
XPath 1.0 compatibility mode is set to true if and only if the containing element is processed with XSLT 1.0 behavior (see 3.10 Backwards Compatible Processing).
The statically known namespacesXP30 are the namespace declarations that are in scope for the containing element.
The default
element/type namespaceXP30 is the
namespace defined by the [xsl:]xpath-default-namespace
attribute on the innermost enclosing element that has such an
attribute, as described in 5.2
Unprefixed Lexical QNames in Expressions and Patterns. The
value of this attribute is a namespace URI. If there is no
[xsl:]xpath-default-namespace
attribute on an
enclosing element, the default namespace for element names and type
names is the null namespace.
The default function
namespaceXP30 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 definitionsXP30 for the XPath expression are the same as the in-scope schema components for the stylesheet, and are as specified in 3.15 Built-in Types.
The in-scope variablesXP30 are defined by the variable binding elements that are in scope for the containing element (see 9 Variables and Parameters).
The context
item static typeXP30 may be
determined by an XSLT processor that performs static type
inferencing, using rules that are outside the scope of this
specification; if no static type inferencing is done, then the
context item static type for every XPath expression is
item()
. Note that some limited static type
inferencing is required in the case of a processor that performs
streamability analysis: see 19.2 Determining the Static Type of a
Construct.
The Statically known function signaturesXP30 are the core functions defined in [Functions and Operators], the constructor functions for all the simple types in the in-scope schema definitionsXP30, the additional functions defined in this specification, the stylesheet functions defined in the stylesheet, plus any extension functions bound using implementation-defined mechanisms (see 23 Extensibility and Fallback).
Note:
It follows from the above that a conformant XSLT processor must implement the entire library of core functions defined in [Functions and Operators].
The statically known collationsXP30 are implementation-defined. However, the set of in-scope collations must always include the Unicode codepoint collation, defined in Section 5.3 Comparison of strings FO30.
The default
collationXP30 is defined by the value
of the [xsl:]default-collation
attribute on the
innermost enclosing element that has such an attribute. For
details, see 3.8.1 The
default-collation Attribute.
[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.
The base URI is the base URI of the containing element in the stylesheet. The concept of the base URI of a node is defined in Section 5.2 base-uri Accessor DM30
The set of statically known documentsXP30 is implementation-defined.
The set of statically known collectionsXP30 is implementation-defined.
The statically known default collection typeXP30 is implementation-defined.
The set of statically
known decimal formatsXP30 is the set
of decimal formats defined by xsl:decimal-format
declarations in the stylesheet.
Some of the components of the XPath static context are used also
by XSLT elements. For example, the xsl:sort
element makes use of the
collations defined in the static context, and attributes such as
type
and as
may reference types defined
in the in-scope schema components.
Many top-level declarations in a stylesheet, and attributes on
the xsl:stylesheet
element, affect the behavior of instructions within the stylesheet.
Each of these constructs is described in its appropriate place in
this specification.
A number of these constructs are of particular significance because they are used by functions defined in XSLT, which are added to the library of functions available for use in XPath expressions within the stylesheet. These are:
The set of named keys, used by the key
function
The values of system properties, used by the system-property
function
The set of available instructions, used by the element-available
function
A dynamic function call clears the first of these components:
this means that a dynamic call to the key
function will always raise a
dynamic error (the key name is unknown). The values of system
properties and the set of available instructions, by contrast,
reflect the capabilities and configuration of the processor rather
than values specific to the stylesheet code itself; the result of a
dynamic call to system-property
or
element-available
will reflect the information available to the processor at
evaluation time.
Note:
If these functions are called within a static expression, the results will reflect the capabilities and configuration of the processor used to perform static analysis, while if they are called elsewhere, the results should reflect the capabilities and configuration of the processor used to perform dynamic evaluation, which might give a different result. These calls should not be pre-evaluated at compile time unless it is known that this will give the same result.
For convenience, the dynamic 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.
A number of functions specified in [Functions and Operators] are defined to
be deterministicFO30,
meaning that if they are called twice during the same execution
scopeFO30, with the same arguments,
then they return the same results (see Section 1.6
Terminology FO30). In XSLT, the
execution of a stylesheet defines the execution scope. This means,
for example, that if the function
current-dateTime
FO30 is called
repeatedly during a transformation, it produces the same result
each time. By implication, the components of the dynamic context on
which these functions depend are also stable for the duration of
the transformation. Specifically, the following components defined
in Section
2.1.2 Dynamic Context XP30 must be
stable: function implementations, current
dateTime, implicit timezone, available
documents, available collections, and default
collection. The values of global variables and stylesheet
parameters are also stable for the duration of a transformation.
The focus is not stable; the additional dynamic context
components defined in 5.4.4 Additional Dynamic Context
Components used by XSLT are also not stable.
As specified in [Functions and
Operators], implementations may provide user options that relax
the requirement for the doc
FO30
and collection
FO30
functions (and therefore, by implication, the document
function) to return
stable results. By default, however, the functions must be stable.
The manner in which such user options are provided, if at all, is
implementation-defined.
XPath expressions contained in [xsl:]use-when
attributes are not considered to be evaluated "during the
transformation" as defined above. For details see 3.14 Conditional Element
Inclusion.
[Definition: A component of the context that has no value is said to be absent.] This is a distinguishable state, and is not the same as having the empty sequence as its value.
[Definition: When a sequence constructor is evaluated, the processor keeps track of which items 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), a node,
or a function item. The context item is initially set
to the initial context item 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 or a function item,
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.
Where the containing element of an XPath expression 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.
For an XPath expression contained in a value template, 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 sequence constructor.
In other cases (for example, where the containing element is
xsl:sort
, xsl:with-param
, or xsl:key
), the rules are given in
the specification of the containing element.
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 20.3.1
fn: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 absent. The focus is also absent on initial entry to the stylesheet if no initial context item is supplied.
When the focus is absent, evaluation of any expression that references the context item, context position, or context size results in a dynamic error [ERR XPDY0002] XP30
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.
[Definition: A singleton focus based on an item J has the context item (and therefore the context node, if J is a node) set to J, and the context position and context size both set to 1 (one).]
The previous section explained how the focus for an XPath expression appearing in an XSLT stylesheet is initialized. This section explains how the other components of the dynamic contextXP30 of an XPath expression are initialized.
The dynamic variablesXP30 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 timezoneXP30 is implementation-defined.
The available documentsXP30, and the available collectionsXP30 are determined as part of the process for initiating a transformation (see 2.3 Initiating a Transformation).
The available
documentsXP30 are defined as part of
the XPath 3.0 dynamic context to support the doc
FO30
function, but this component is also referenced by the similar XSLT
document
function: see
20.1 fn:document. This variable
defines a mapping between URIs passed to the doc
FO30
or document
function and
the document nodes that are returned.
The mapping from URIs to document nodes is affected by xsl:strip-space
declarations and by the input-type-annotations
attribute, and may therefore vary from one package to another.
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.
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 representation. Therefore, the information supplied
in available
documentsXP30 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.
The default collectionXP30 is implementation-defined. This allows options such as setting the default collection to be an empty sequence, or to be absent.
In addition to the values that make up the focus, an XSLT processor maintains a number of other dynamic context components that reflect aspects of the evaluation context. These components are fully described in the sections of the specification that maintain and use them. They are:
The current template rule, which is the
template rule most recently invoked by an
xsl:apply-templates
,
xsl:apply-imports
, or
xsl:next-match
instruction: see 6.9 Overriding
Template Rules;
The current mode, which is the mode set by the most recent
call of xsl:apply-templates
(for a full definition see 6.6
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
or xsl:merge
instruction: see 14.2.1
fn:current-group, 14.2.2
fn:current-grouping-key, and 15
Merging;
Note:
In XSLT 3.0 the initial value of these two properties is
"absent", which means that any reference to their values causes a
dynamic error. Previously, the initial value was an empty sequence.
The value is also set to "absent" by an xsl:for-each-group
instruction that binds variables to the current group value and/or current grouping key value
using the bind-group
or bind-grouping-key
attributes.
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
17.2 fn:regex-group.
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 24.1 Creating
Final Result Trees.
The following non-normative table summarizes the initial state of each of the components in the evaluation context, and the instructions which cause the state of the component to change.
Component | Initial Setting | Set by | Cleared by |
---|---|---|---|
focus | singleton focus based on the initial context item if supplied | xsl:apply-templates ,
xsl:for-each , xsl:for-each-group ,
xsl:analyze-string ,
evaluation of patterns |
Calls to stylesheet functions |
current template rule | If a named template is supplied as the entry point to the transformation, then absent; otherwise the initial template | xsl:apply-templates ,
xsl:apply-imports ,
xsl:next-match |
xsl:for-each , xsl:for-each-group ,
xsl:analyze-string ,
xsl:iterate ,
xsl:stream , xsl:merge , xsl:evaluate , and
calls to stylesheet functions, and dynamic
function calls. Also cleared while evaluating global
variables or default values of stylesheet parameters,
patterns, and the sequence constructors
contained in xsl:key and
xsl:sort . |
current mode | the initial mode | xsl:apply-templates |
Calls to stylesheet functions. Also
cleared while evaluating global variables and stylesheet
parameters, patterns, and the sequence constructor
contained in xsl:key or
xsl:sort . Clearing the
current mode causes the current mode to be set to the default
(unnamed) mode. |
current group | absent | xsl:for-each-group ,
xsl:merge |
Calls to stylesheet functions, dynamic
function calls, evaluation of global variables,
stylesheet parameters, and patterns, calls on xsl:for-each-group with
a bind-group attribute. |
current grouping key | absent | xsl:for-each-group ,
xsl:merge |
Calls to stylesheet functions, dynamic
function calls, evaluation of global variables,
stylesheet parameters, and patterns, calls on xsl:for-each-group with
a bind-grouping-key attribute or with a
group-starting-with or group-ending-with
attribute. |
current captured substrings | empty sequence | xsl:matching-substring |
xsl:non-matching-substring ;
Calls to stylesheet functions, dynamic
function calls, evaluation of global variables,
stylesheet parameters, and patterns |
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 |
[Definition: The term non-contextual
function call is used to refer to function calls that do not
pass the dynamic context to the called function. This includes all
calls on stylesheet functions and all dynamic
function invocationsXP30, (that is
calls to function items as permitted by XPath 3.0). It does not
include calls to all core functions in particular those that
explicitly depend on the context, such as the current-group
and regex-group
functions. It is
implementation-defined whether,
and under what circumstances, calls to extension functions are
non-contextual.]
Named function references (such as position#0
) and
calls on
function-lookup
FO30 (for
example, function-lookup("position", 0)
) are defined
to retain the XPath static and dynamic context at the point of
invocation as part of the closure of the resulting function item,
and to use this preserved context when a dynamic function call is
subsequently made using the function item. This rule does not
extend to the XSLT extensions to the dynamic context defined in
this section. If a dynamic function call is made that depends on
the XSLT part of the dynamic context (for example,
regex-group#1(2)
), then the relevant components of the
context are cleared as described in the table above.
The definition of the
format-number
FO30 function is
now in [Functions and Operators].
What remains here is the definition of the xsl:decimal-format
declaration, which provides the context for this function when used
in an XSLT stylesheet.
<!-- Category: declaration
-->
<xsl:decimal-format
name? = eqname
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 />
The xsl:decimal-format
element sets the statically known decimal formats
component of the static context for XPath expressions, which
controls the interpretation of a picture string used by the
format-number
FO30
function.
[Definition: The picture string is the string
supplied as the second argument of the
format-number
FO30
function.]
Note:
The
format-number
FO30 function,
previously defined in this specification, is now a core function
defined in [Functions and
Operators].
A package may contain multiple xsl:decimal-format
declarations and may include or import stylesheet modules
that also contain xsl:decimal-format
declarations. The name of an xsl:decimal-format
declaration is the value of its name
attribute, if
any.
[Definition: All the xsl:decimal-format
declarations in a package that share the same name are
grouped into a named decimal format; those that have no name
are grouped into a single unnamed decimal format.]
The attributes of the xsl:decimal-format
declaration define the value of the corresponding attribute in the
relevant decimal format in the Statically
known decimal formatsXP30 component
of the static context for all XPath expressions in the package. The
attribute names used in the XSLT 3.0 syntax are the same as the
attribute names used in the definition of the static context,
except that the digit
attribute of xsl:decimal-format
corresponds to the digit-sign
attribute in the static
context.
The scope of an xsl:decimal-format
name
is the package in which it is declared; the name is available for
use only in calls to
format-number
FO30 that appear
within the same package.
If a package does not contain a declaration of the
unnamed 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
FO30 function. An
outline of the purpose of each attribute is given below; however,
the definitive explanations are given as part of the
specification of
format-number
FO30.
For any named decimal format, the effective value of
each attribute is taken from an xsl:decimal-format
declaration that has that name, and that specifies an explicit
value for the required attribute. If there is no such declaration,
the default value of the attribute is used. If there is more than
one such declaration, the one with highest import precedence is used.
For any unnamed decimal format, the effective value of
each attribute is taken from an xsl:decimal-format
declaration that is unnamed, and that specifies an explicit value
for the required attribute. If there is no such declaration, the
default value of the attribute is used. If there is more than one
such declaration, the one with highest import precedence
is used.
[ERR XTSE1290] It is a static error if a named
or unnamed decimal format contains two conflicting
values for the same attribute in different xsl:decimal-format
declarations having the same import precedence,
unless there is another definition of the same attribute with
higher import precedence.
The following attributes control the interpretation of
characters in the picture string supplied to the
format-number
FO30 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 [see
ERR XTSE0020].
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.
[ERR XTSE1295] It is a static error if the
character specified in the zero-digit
attribute is not
a digit or is a digit that does not have the numeric value
zero.
The following attributes control the interpretation of
characters in the picture string supplied to the
format-number
FO30 function. In
each case the value must be a single
character [see ERR
XTSE0020].
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 XTSE1300] 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.
Every (named or unnamed) decimal format defined in a package is
added to the statically
known decimal formatsXP30 in the
static
contextXP30 of every expression in
the package, excluding expressions appearing in
[xsl:]use-when
attributes.
In XSLT 3.0, patterns can match any kind of item: atomic values and function items as well as nodes.
A template rule identifies the items 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 20.2 Keys).
[Definition: A pattern specifies a set of conditions on an item. An item that satisfies the conditions matches the pattern; an item that does not satisfy the conditions does not match the pattern.]
There are two basic kinds of pattern: predicate patterns, and path patterns. Patterns may also be formed by combining other patterns using union, intersection, and difference operators.
A predicate pattern uses the syntax .[ Expr ]
written with zero or or more predicates in square brackets; it
matches an item if each of the predicates matches the context item.
The detailed semantics are given in 5.6.3 The Meaning of a Pattern.
This construct can be used to match items of any kind (nodes,
atomic values, and function items). For example, the pattern
.[starts-with(., '$')]
matches any string that starts
with the character "$", or a node whose atomized value starts with
"$". This example shows a predicate pattern with a single
predicate, but the grammar allows any number of predicates (zero or
more).
The syntax for path patterns is a subset of the syntax for expressions. Path patterns are used only for matching nodes; an item other than a node will never match a path pattern. As explained in detail below, a node matches a path pattern if the node can be selected by deriving an equivalent expression, and evaluating this expression with respect to some possible context.
Note:
The specification uses the phrases an item matches a pattern and a pattern matches an item interchangeably. They are equivalent: an item matches a pattern if and only if the pattern matches the item.
Here are some examples of patterns:
.
matches any item.
*
matches any element.
para
matches any para
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.
schema-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(schema-element(my:invoice))
matches
the document node of a document whose document element is named
my:invoice
and matches the type defined by the global
element declaration my:invoice
.
text()
matches any text node.
namespace-node()
matches any namespace node.
node()
matches any node other than an attribute
node, namespace node, or document node.
id("W33")
matches the element with unique ID
W33
.
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.
$xyz
matches any node that is present in the value
of the variable $xyz
.
$xyz//*
matches any element that is a descendant of
a node that is present in the value of the variable
$xyz
.
doc('product.xml')//*
matches any element within
the document whose document URI is 'product.xml'.
.[. instance of node()]
matches any node. (Note the
distinction from the pattern node()
.)
.[. instance of xs:date]
matches any atomic value
of type xs:date
(or a type derived by restriction from
xs:date
).
.[. gt current-date()]
matches any date in the
future. It can match an atomic value of type xs:date
or xs:untypedAtomic
, or a node whose atomized value is
an xs:date
or xs:untypedAtomic
value.
.[starts-with(., 'e')]
matches any node or atomic
value that after conversion to a string using the function
conversion rules starts with the letter 'e'.
.[. instance of function(*)]
matches any function
item.
.[$f(.)]
matches any item provided that the call on
the function bound to the variable $f
returns a result
whose effective boolean value is true.
[ERR XTSE0340] Where an attribute is defined to contain a pattern, it is a static error if the pattern does not match the production Pattern30.
The grammar for patterns uses the notation defined in Section A.1.1 Notation XP30.
The lexical rules for patterns are the same as the lexical rules
for XPath expressions, as defined in Section A.2
Lexical structure XP30. Comments are
permitted between tokens, using the syntax (: ... :)
.
All other provisions of the XPath grammar apply where relevant, for
example the rules for whitespace handling and extra-grammatical
constraints.
[1] | Pattern30 |
::= | PredicatePattern |
UnionExprP |
[2] | PredicatePattern |
::= | "." PredicateListXP30 |
[3] | UnionExprP |
::= | IntersectExceptExprP
(("union" | "|") IntersectExceptExprP)* |
[4] | IntersectExceptExprP |
::= | PathExprP
(("intersect" | "except") PathExprP)* |
[5] | PathExprP |
::= | RootedPath |
[6] | RootedPath |
::= | (VarRefXP30
| FunctionCallP)
PredicateListXP30
(("/" | "//") RelativePathExprP)? |
[7] | FunctionCallP |
::= | OuterFunctionName
ArgumentListP |
[8] | OuterFunctionName |
::= | "doc" | "id" | "element-with-id" | "key" | PrefixedQName | URIQualifiedNameXP30 |
[10] | ArgumentListP |
::= | "(" (ArgumentP ("," ArgumentP)*)? ")" |
[11] | ArgumentP |
::= | VarRefXP30
| LiteralXP30 |
[12] | RelativePathExprP |
::= | StepExprP
(("/" | "//") StepExprP)* |
[13] | StepExprP |
::= | PostfixExprP | AxisStepP |
[14] | PostfixExprP |
::= | ParenthesizedExprP
PredicateListXP30 |
[15] | ParenthesizedExprP |
::= | "(" UnionExprP ")" |
[16] | AxisStepP |
::= | ForwardStepP PredicateListXP30 |
[17] | ForwardStepP |
::= | (ForwardAxisP NodeTestXP30)
| AbbrevForwardStepXP30 |
[18] | ForwardAxisP |
::= | ("child" "::") |
[122] | PrefixedQName |
::= | NCNameXP30
":" NCNameXP30 |
The names of these constructs are chosen to align with the XPath
3.0 grammar. Constructs whose names are suffixed with
P
are restricted forms of the corresponding XPath 3.0
construct without the suffix. Constructs labelled with the suffix
"XP30" are defined in [XPath 3.0].
In a FunctionCallP, the
EQName
used for the function name must have local part
doc
, id
, element-with-id
, or
key
, and must use the standard function namespace
either explicitly or implicitly.
Note:
As with XPath expressions, the pattern / union /*
can be parsed in two different ways, and the chosen interpretation
is to treat union
as an element name rather than as an
operator. The other interpretation can be achieved by writing
(/) union (/*)
The meaning of a pattern is defined formally as follows, where "if" is to be read as "if and only if".
If the pattern is a PredicatePattern PP, then it matches an item J if the XPath expression taking the same form as PP returns a non-empty sequence when evaluated with a singleton focus based on J.
Note:
The pattern .
, which is a
PredicatePattern
with an empty
PredicateList
, matches every item.
A predicate with the numeric value 1 (one) always matches, and a
predicate with any other numeric value never matches. Numeric
predicates in a PredicatePattern
are therefore not
useful, but are defined this way in the interests of consistency
with XPath.
Otherwise (the pattern is a PathPattern
), the
pattern is converted to an expression, called the equivalent
expression. The equivalent expression to a Pattern is the XPath
expression that takes the same lexical form as the
Pattern
as written, with the following adjustment:
If any PathExprP
in the Pattern
is a RelativePathExprP
, then the first
StepExprP
PS of this
RelativePathExprP
is adjusted to allow it to
match a parentless element, attribute, or namespace node. The
adjustment depends on the axis used in this step, whether it
appears explicitly or implicitly (according to the rules of
Section 3.3.5
Abbreviated Syntax XP30), and is made
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 (explicitly or
implicitly), 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.
If PS uses the namespace axis (explicitly or
implicitly), then the axis in step PS is replaced
by namespace-or-top
, which is defined as follows. If
the context node is a namespace node with no parent, then the
namespace-or-top
axis selects the context node;
otherwise it selects the namespace nodes of the context node. It is
a forwards axis whose principal node kind is namespace.
The axes child-or-top
,
attribute-or-top
, and namespace-or-top
are introduced only for definitional purposes. They cannot be used
explicitly in a user-written pattern or expression.
Note:
The purpose of this adjustment is to ensure that a pattern such
as person
matches any element named
person
, even if it has no parent; and similarly, that
the pattern @width
matches any attribute named
width
, even a parentless attribute. The rule also
ensures that a pattern using a NodeTest
of the form
document-node(...)
matches a document node. 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. To match any node at all, XSLT 3.0
allows the pattern .[. instance of node()]
to be
used.
The meaning of the pattern is then defined in terms of the
semantics of the equivalent expression, denoted below as
EE
.
Specifically, an item N matches a pattern
P if the following applies, where EE
is the
equivalent expression to P:
N is a node, and the result of evaluating the
expression root(.)//(EE)
with a singleton focus based on N is
a sequence that includes the node N
If a pattern appears in an attribute of an element that is processed with XSLT 1.0 behavior (see 3.10 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.
The path pattern 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 path 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.
The path pattern $V
matches all nodes selected by
the expression root(.)//($V)
, that is, all nodes in
the value of $V (which will typically be a global variable, though
when the pattern is used in contexts such as the xsl:number
or xsl:for-each-group
instructions, it can also be a local variable).
The path pattern doc('product.xml')//product
matches all nodes selected by the expression
root(.)//(doc('product.xml')//product)
, that is, all
product
elements in the document whose URI is
product.xml
.
Although the semantics of path patterns are specified formally
in terms of expression evaluation, it is possible to understand
pattern matching using a different model. A path 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.
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.
A dynamic error or type error that occurs during the evaluation of a pattern against a particular item has the effect that the item being tested is treated as not matching the pattern. The error does not cause the transformation to fail, and cannot be caught by a try/catch expression surrounding the instruction that causes the pattern to be evaluated.
Note:
The reason for this provision is that it is difficult for the stylesheet author to predict which predicates in a pattern will actually be evaluated. In the case of match patterns in template rules, it is not even possible to predict which patterns will be evaluated against a particular node.
There is a risk that ignoring errors in this way may make programming mistakes harder to debug. Implementations may mitigate this by providing warnings or other diagnostics when evaluation of a pattern triggers an error condition.
Static errors in patterns, including dynamic and type errors that are signaled statically as permitted by the specification, are reported in the normal way and cause the transformation to fail.
The string value of an attribute or text node in the stylesheet may in particular circumstances contain embedded expressions enclosed between curly brackets. Attributes and text nodes that use (or are permitted to use) this mechanism are referred to respectively as attribute value templates and text value templates..
[Definition: Collectively, attribute value templates and text value templates are referred to as value templates.]
A value template is a string consisting of an alternating
sequence of fixed parts and variable parts. A variable part
consists of an 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 StringLiteralXP30 or within a comment.
Currently no XPath expression starts with an opening curly
bracket, so the use of {{
creates no ambiguity. If an
enclosed expression ends with a closing curly bracket, no
whitespace is required between this and the closing delimiter.
[ERR XTSE0350] It is a static error if an unescaped left curly bracket appears in a fixed part of a value template without a matching right curly bracket.
It is a static error if the string contained between matching curly brackets in a value template does not match the XPath production ExprXP30, or if it contains other XPath static errors. The error is signaled using the appropriate XPath error code.
[ERR XTSE0370] It is a static error if an unescaped right curly bracket occurs in a fixed part of a value template.
[Definition: The result of evaluating a value template is referred to as its effective value.] The effective value is the string obtained by concatenating the expansions of the fixed and variable parts:
The expansion of a fixed part is obtained by replacing any
double curly brackets ({{
or }}
) by the
corresponding single curly bracket.
The expansion of a variable part is obtained by evaluating the enclosed XPath expression and converting the resulting value to a string. This conversion is done using the rules given in 5.8.2 Constructing Simple Content.
Note:
This process can generate dynamic errors, for example if the sequence contains an element with a complex content type (which cannot be atomized).
In the case of an attribute value template, the effective value becomes the string value of the new attribute node. In the case of a text value template, the effective value becomes the string value of the new text node.
[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 ({}
), following the
general rules for value templates].
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 generally not designated as
attribute value templates (an exception is the format
attribute of xsl:result-document
).
Namespace declarations are not XDM attribute nodes and are
therefore never treated as attribute value templates.
If the element containing the attribute is processed with XSLT 1.0 behavior, then the rules for converting the value of the expression to a string (given in 5.7 Value Templates) 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.
Note:
The above rule applies to attribute value templates but not to text value templates, since the latter were not available in XSLT 1.0.
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.
The standard attribute
[xsl:]expand-text
may appear on any element in the
stylesheet, and determines whether descendant text nodes of that
element are treated as text value templates. A text node in the
stylesheet is treated as a text value template if (a) it is part of
a sequence constructor, (b) there is
an ancestor element with an [xsl:]expand-text
attribute, and (c) on the innermost ancestor element that has such
an attribute, the value of the attribute is yes
. The
value of the attribute must be
yes
or no
.
This section describes how text nodes appearing in sequence
constructors are processed when the effective value is
yes
. Such text nodes are referred to as text value
templates.
[Definition: In a text node that is designated as a
text value template, expressions can be used by surrounding
each expression with curly brackets ({}
).]
The rules for text value templates are given in 5.7 Value Templates. A text node in a sequence constructor whose value is a text value template results in the construction of a text node in the result of the sequence constructor. The string value of that text node is obtained by computing the effective value of the value template.
Note:
The content of an xsl:text
element is not a sequence
constructor, and therefore cannot contain a text value
template.
The result of evaluating a text value template is a (possibly zero-length) text node. This text node becomes part of the result of the containing sequence constructor, and is thereafter handled exactly as if the value had appeared explicitly as a text node in the stylesheet.
The way in which the effective value is computed does not depend
on any separator
attribute on a containing xsl:value-of
or xsl:attribute
instruction.
The separator
attribute only affects how the text node
is combined with adjacent items in the result of the containing
sequence constructor.
Fixed parts consisting entirely of whitespace are significant and are handled in the same way as any other fixed part. This is different from the default treatment of "boundary space" in XQuery.
<xsl:variable name="id" select="'A123'"/> <xsl:variable name="step" select="5"/> <xsl:message expand-text="yes" >Processing id={$id}, step={$step}</xsl:message>
This will typically output the message text Processing
id=A123, step=5
.
<xsl:function name="f:sum" expand-text="yes" as="xs:integer"> <xsl:param name="x" as="xs:integer"/> <xsl:param name="y" as="xs:integer"/> {$x + $y} </xsl:function>
Note that although this is a very readable way of expressing the
computation performed by the function, the semantics are somewhat
complex, and this could mean that execution is inefficient. The
function computes the value of $x + $y
as an integer,
and then constructs a text node containing the string
representation of this integer (preceded and followed by
whitespace). Because the declared result type of the function is
xs:integer
, this text node is then atomized, giving an
xs:untypedAtomic
value, and the
xs:untypedAtomic
value is then cast to an
xs:integer
.
Note:
The main motivations for adding text value templates to the XSLT
language are firstly, to make it easier to construct parameterized
text in contexts such as xsl:value-of
and xsl:message
, and secondly, to
allow use of complex multi-line XPath expressions where maintaining
correct indentation is important for readability. The fact that XML
processors are required to normalize whitespace in attribute values
means that writing such expressions within a select
attribute is not ideal.
The facility is only present if enabled using the
[xsl:]expand-text
attribute. This is partly for
backwards compatibility, and partly to avoid creating difficulties
when constructing content that is rich in curly brackets, for
example Javascript code or CSS style sheets.
[Definition: A sequence constructor is a sequence of zero or more sibling nodes in the stylesheet that can be evaluated to return a sequence of nodes, atomic values, and function items. The way that the resulting sequence is used depends on the containing instruction.]
Many XSLT elements, and also literal result elements, are defined to take a sequence constructor as their content.
Four kinds of nodes may be encountered in a sequence constructor:
A Text node appearing in the stylesheet (if it has not been removed in the process of whitespace stripping: see 4.2 Stripping Whitespace from the Stylesheet) is processed as follows:
if the effective value of the standard attribute
[xsl:]expand-text
is no
, or in the
absence of this attribute, the text node in the stylesheet is
copied to create a new parentless text node in the result of the
sequence constructor.
Note:
For an xsl:text
element, the effective value of [xsl:]expand-text
is
always "no".
Otherwise (the effective value of [xsl:]expand-text
is yes
), the text node in the stylesheet is processed
as described in 5.7.2 Text Value
Templates.
A literal result element is evaluated to create a new parentless element node, having the same expanded QName as the literal result element: see 11.1 Literal Result Elements.
An XSLT instruction produces a sequence of zero, one,
or more items as its result. For most XSLT instructions, these
items are nodes, but some instructions (such as
xsl:sequence
and
xsl:copy-of
) can also
produce atomic values or function items. Several
instructions, such as xsl:element
, return a newly
constructed parentless node (which may have its own attributes,
namespaces, children, and other descendants). Other instructions,
such as xsl:if
, pass on the
items produced by their own nested sequence constructors. The
xsl:sequence
instruction may return atomic values, function items,
or existing nodes.
An extension instruction (see 23.2 Extension Instructions) also produces a sequence of items as its result.
The result of evaluating a sequence constructor is the sequence of items formed by concatenating the results of evaluating each of the nodes in the sequence constructor, retaining order.
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 /
causes a type error if the root of
the tree containing the context node is not a document node.
Parentless attribute nodes require particular care because they have no namespace nodes associated with them. A parentless attribute node is not permitted to contain namespace-sensitive content (for example, a QName or an XPath expression) because there is no information enabling the prefix to be resolved to a namespace URI. Parentless attributes can be useful in an application (for example, they provide an alternative to the use of attribute sets: see 10.2 Named Attribute Sets) but they need to be handled with care.
The sequence may be returned as the result of the containing
element. This happens when the element containing the
sequence constructor is xsl:analyze-string
,
xsl:apply-imports
,
xsl:apply-templates
,
xsl:break
,
xsl:call-template
,
xsl:catch
,
xsl:choose
, xsl:fallback
, xsl:for-each
, xsl:for-each-group
,
xsl:fork
,
xsl:if
, xsl:iterate
, xsl:matching-substring
,
xsl:next-match
,
xsl:non-matching-substring
,
xsl:on-completion
,
xsl:otherwise
,
xsl:perform-sort
,
xsl:sequence
,
xsl:try
, or
xsl:when
.
The sequence may be used to construct the content of a new
element or document node. This happens when the sequence
constructor appears as the content of a literal result element, or of one
of the instructions xsl:copy
, xsl:element
, xsl:document
, xsl:result-document
,
xsl:assert
,
or xsl:message
. It also
happens when the sequence constructor is contained in one of the
elements xsl:variable
,
xsl:param
, or xsl:with-param
, when this
instruction has no as
attribute. For details, see
5.8.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.8.2
Constructing Simple Content.
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:document
, xsl:result-document
, or
a literal result element.
When constructing the content of an element, the
inherit-namespaces
attribute of the xsl:element
or xsl:copy
instruction, or the
xsl:inherit-namespaces
property of the literal result
element, determines whether namespace nodes are to be inherited.
The effect of this attribute is described in the rules that
follow.
The sequence is processed as follows (applying the rules in the order they are listed):
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.
Note:
Casting from xs:QName
or xs:NOTATION
to xs:string
always succeeds, because these values
retain a prefix for this purpose. However, there is no guarantee
that the prefix used will always be meaningful in the context where
the resulting string is used.
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 single space (#x20) used as a separator between successive strings.
Any document node within the result sequence is replaced by a sequence containing each of its children, in document order.
Zero-length text nodes within the result sequence are removed.
Adjacent text nodes within the result sequence are merged into a single text node.
Invalid items in the result sequence are detected as follows.
[ERR XTDE0410] It is a 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.
[ERR XTDE0420] It is a dynamic error if the result sequence used to construct the content of a document node contains a namespace node or attribute node.
[ERR XTDE0430] It is a 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).
[ERR XTDE0440] It is a 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).
[ERR XTDE0450] It is a dynamic error if the result sequence contains a function item.
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 implementation-dependent, 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. Before discarding attribute A, the processor may signal any type errors that would be signaled if attribute B were not present.
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 or processing
instruction 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 [XML Base]) that overrides
this. If the copied element has an xml:base
attribute,
its base URI is the value of that attribute, resolved (if it is
relative) against the base URI of the new parent node.
If the newly constructed node is an element node, then namespace fixup is applied to this node, as described in 5.8.3 Namespace Fixup.
If the newly constructed node is an element node, and if namespaces are inherited, then each namespace node of the newly constructed element (including any produced as a result of the namespace fixup process) is copied to each descendant element of the newly constructed element, unless that element or an intermediate element already has a namespace node with the same name (or absence of a name) or that descendant element or an intermediate element is in no namespace and the namespace node has no name.
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 (unless
it is zero-length, in which case it is discarded).
Consider the following stylesheet fragment:
<doc> <e><xsl:sequence select="1 to 5"/></e> <f> <xsl:for-each select="1 to 5"> <xsl:value-of select="."/> </xsl:for-each> </f> </doc>
This produces the output (when indented):
<doc> <e>1 2 3 4 5</e> <f>12345</f> </doc>
The difference between the two cases is that for the
e
element, the sequence constructor generates a
sequence of five atomic values, which are therefore separated by
spaces. For the f
element, the content is a sequence
of five text nodes, which are concatenated without space
separation.
It is important to be aware of the distinction between xsl:sequence
, which returns
the value of its select
expression unchanged, and
xsl:value-of
, which
constructs a text node.
The instructions xsl:attribute
, xsl:comment
, xsl:processing-instruction
,
xsl:namespace
, and
xsl:value-of
all
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 according to the rules below.
These rules are also used to compute the effective value of an value template. In this case the sequence being processed is the result of evaluating an XPath expression enclosed between curly brackets, and the separator is a single space character.
Zero-length text nodes in the sequence are discarded.
Adjacent text nodes in the sequence are merged into a single text node.
The sequence is atomized (which may cause a dynamic error).
Every value in the atomized sequence is cast to a string.
The strings within the resulting sequence are concatenated, with
a (possibly zero-length) separator inserted between successive
strings. The default separator is a single space. 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
,
and when expanding a value template, the
default separator cannot be changed.
In the case of xsl:processing-instruction
,
any leading spaces in the resulting string are removed.
The resulting string forms the string value of the new attribute, namespace, comment, processing-instruction, or text node.
Consider the following stylesheet fragment:
<doc> <xsl:attribute name="e" select="1 to 5"/> <xsl:attribute name="f"> <xsl:for-each select="1 to 5"> <xsl:value-of select="."/> </xsl:for-each> </xsl:attribute> <xsl:attribute name="g" expand-text="yes">{1 to 5}</xsl:attribute> </doc>
This produces the output:
<doc e="1 2 3 4 5" f="12345" g="1 2 3 4 5"/>
The difference between the three cases is as follows. For the
e
attribute, the sequence constructor generates a
sequence of five atomic values, which are therefore separated by
spaces. For the f
attribute, the content is supplied
as a sequence of five text nodes, which are concatenated without
space separation. For the g
attribute, the text value template constructs a text
node using the rules for constructing simple content, which insert
space separators between atomic values; the text node is then
atomized to form the value of the attribute.
Specifying separator=""
on the first xsl:attribute
instruction
would cause the attribute value to be e="12345"
. A
separator
attribute on the second xsl:attribute
instruction
would have no effect, since the separator only affects the way
adjacent atomic values are handled: separators are never inserted
between adjacent text nodes. A separator
on the
third xsl:attribute
instruction would also have no effect, because text value templates
are evaluated without regard to the containing
instruction.
Note:
If an attribute value template contains a sequence of fixed and
variable parts, no additional whitespace is inserted between the
expansions of the fixed and variable parts. For example, the
effective value of the attribute
a="chapters{4 to 6}"
is a="chapters4 5
6"
.
In a tree supplied to or constructed by an XSLT processor, the constraints relating to namespace nodes that are specified in [Data Model] must be satisfied. For example
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
or the string value
http://www.w3.org/2000/xmlns/
.
[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 prescribed 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-dependent, 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 may, if necessary to
resolve conflicts, change the namespace prefix contained in the
QName value that holds the name of an element or attribute node.
This includes the option to add or remove a prefix. However,
namespace fixup must not change the
prefix component contained in a value of type xs:QName
or xs:NOTATION
that forms the typed value of an
element or attribute node.
Note:
Namespace fixup is not used to create namespace declarations for
xs:QName
or xs:NOTATION
values appearing
in the content of an element or attribute.
Where values acquire such types as the result of validation, namespace fixup does not come into play, because namespace fixup happens before validation: in this situation, it is the user's responsibility to ensure that the element being validated has the required namespace nodes to enable validation to succeed.
Where existing elements are copied along with their existing
type annotations (validation="preserve"
) the rules
require that existing namespace nodes are also copied, so that any
namespace-sensitive values remain valid.
Where existing attributes are copied along with their existing
type annotations, the rules of the XDM data model require that a
parentless attribute node cannot contain a namespace-sensitive
typed value; this means that it is an error to copy an attribute
using validation="preserve"
if it contains
namespace-sensitive content.
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, for a document
in the initial input sequence, documents loaded using the document
, doc
FO30
or collection
FO30
function, documents supplied as the value of a stylesheet parameter, or documents
returned by an extension function or extension instruction.
Note:
A source document (an input document, a document returned by the
document
, doc
FO30
or collection
FO30
functions, a document returned by an extension function or
extension instruction, or a document supplied as a stylesheet
parameter) is required to satisfy the constraints described in
[Data Model], including the
constraints imposed by the namespace fixup process. The effect of
supplying a pseudo-document that does not meet these constraints is
implementation-dependent.
In an Infoset (see [XML Information
Set]) created from a document conforming to [Namespaces in XML], 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
[Namespaces in XML 1.1]. XSLT
3.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.
However, the process of constructing the children of a new element,
which is described in 5.8.1 Constructing Complex
Content, does cause the namespaces of a parent element to
be inherited by its children unless this is prevented using
[xsl:]inherit-namespaces="no"
on the instruction that
creates the parent element.
Note:
This has implications on serialization, defined in [XSLT and XQuery
Serialization]. It means that it is possible to create
final 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,
xmlns:foo=""
) to prevent this inheritance taking
place.
[Definition: Within this specification, the term URI
Reference, unless otherwise stated, refers to a string in the
lexical space of the xs:anyURI
datatype as defined in
[XML Schema Part 2].] Note that this is a wider definition than
that in [RFC3986]: in particular, it is
designed to accommodate Internationalized Resource Identifiers
(IRIs) as described in [RFC3987], and thus
allows the use of non-ASCII characters without escaping.
URI References are used in XSLT with three main roles:
As namespace URIs
As collation URIs
As identifiers for resources such as stylesheet modules; these
resources are typically accessible using a protocol such as HTTP.
Examples of such identifiers are the URIs used in the
href
attributes of xsl:import
, xsl:include
, and xsl:result-document
.
The rules for namespace URIs are given in [Namespaces in XML] and [Namespaces in XML 1.1]. Those specifications deprecate the use of relative URI references as namespace URIs.
The rules for collation URIs are given in [Functions and Operators].
URI references used to identify external resources must conform
to the same rules as the locator attribute (href
)
defined in section 5.4 of [XLink]. If the URI
reference is relative, then it is resolved (unless otherwise
specified) against the base URI of the containing element node,
according to the rules of [RFC3986], after
first escaping all characters that need to be escaped to make it a
valid RFC3986 URI reference. (But a relative URI
reference in the href
attribute of
xsl:result-document
is
resolved against the Base Output URI.)
Other URI references appearing in an XSLT stylesheet document,
for example the system identifiers of external entities or the
value of the xml:base
attribute, must follow the rules
in their respective specifications.
The base URI of an element node in the stylesheet is determined
as defined in Section 5.2
base-uri Accessor DM30. Some
implementations may allow the output of the static analysis phase
of stylesheet processing (a "compiled stylesheet") to be evaluated
in a different location from that where static analysis took place.
Furthermore, stylesheet authors may in such cases which to avoid
exposing the location of resources that are private to the
development environment. If the base URI of an element in the
stylesheet is defined by an absolute URI appearing in an
xml:base
attribute within the stylesheet, this value
must be used as the static base URI. In
other cases where processing depends on the static base URI of a
stylesheet module, implementations may
use different values for the static base URI during static analysis
and during dynamic evaluation (for example, an implementation
may use different base URIs for resolving
xsl:import
module
references and for resolving a relative reference used as an
argument to the doc
FO30
function). In such cases an implementation must document how the static base URI is computed for
each situation in which it is required.
Template rules define the processing that can be applied to items that match a particular pattern.
<!-- Category: declaration
-->
<xsl:template
match? = pattern
name? = eqname
priority? = decimal
mode? = tokens
as? = sequence-type
visibility? = "public" | "private" | "final" |
"abstract" >
<!-- Content: (xsl:context-item?, xsl:param*, sequence-constructor)
-->
</xsl:template>
[Definition: An xsl:template
declaration
defines a template, which contains a sequence constructor ; this
sequence constructor is evaluated to determine the result of the
template. A template can serve either as a template
rule, invoked by matching items 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.]
[ERR XTSE0500] An xsl:template
element
must have either a match
attribute or a name
attribute, or both. An xsl:template
element that has
no match
attribute must have
no mode
attribute and no priority
attribute. An xsl:template
element that has
no name
attribute must have
no visibility
attribute.
If an xsl:template
element has a match
attribute, then it is a template
rule. If it has a name
attribute, then it is a
named template.
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.8 Sequence
Constructors).
For details of the optional xsl:context-item
child
element, see 6.7.2
Declaring the context item for a template.
If an as
attribute of the xsl:template
element is
present, the as
attribute defines the required type of
the result. The result of evaluating the sequence constructor is then
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.
[ERR XTTE0505] It is a type error if the result of evaluating the sequence constructor cannot be converted to the required type.
If the visibility
attribute is present with the
value abstract
then (a) the sequence constructor defining the
template body must be empty: that is, the
only permitted children are xsl:context-item
and
xsl:param
, and (b) there
must be no match
attribute.
If the parent of the xsl:template
element is an
xsl:override
element,
then there must be a name
attribute and no
match
attribute, and the package that is the target of the
containing xsl:use-package
element
must contain among its components a named template whose
symbolic identifier is the same as
this named template, and which has a compatible signature.
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 items 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 item used as the context
item.
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 an item 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 item, 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 items
(typically nodes in a source tree), and produces as output a
sequence of items; these will often be nodes to be added to a
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 item in the input sequence is processed by
finding a template rule whose pattern matches that
item. If there is more than one such template rule,
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
item, a built-in template rule is used (see 6.8 Built-in Template Rules). The
chosen template rule is evaluated. The rule that matches the
Nth item in the sorted sequence is
evaluated with that item 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
item in the sorted sequence) are then concatenated, to
form a single sequence. They are concatenated retaining the order
of the items 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 the
context node to be processed.
[ERR XTTE0510] It is a type error if an xsl:apply-templates
instruction with no select
attribute is evaluated when
the context item is not a node.
A select
attribute can be used to process
items selected by an expression instead of processing
all children. The value of the select
attribute is an
expression.
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.9 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"
This example reads a non-XML text file and processes it line-by-line, applying different template rules based on the content of each line:
<xsl:template name="main"> <xsl:apply-templates select="unparsed-text-lines('input.txt')"/> </xsl:template> <xsl:template match=".[starts-with(., '==')]"> <h2><xsl:value-of select="replace(., '==', '')"/></h2> </xsl:template> <xsl:template match=".[starts-with(., '::')]"> <p class="indent"><xsl:value-of select="replace(., '::', '')"/></p> </xsl:template> <xsl:template match="."> <p class="body"><xsl:value-of select="."/></p> </xsl:template>
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 selected item to match more than one template rule with a given mode M. When this happens, only one template rule is evaluated for the item. The template rule to be used is determined as follows:
First, only the matching template rule or rules with the highest import precedence are considered. Other matching template rules with lower precedence are eliminated from consideration.
Next, of the remaining matching rules, only those with the highest priority are considered. Other matching template rules with lower priority are eliminated from consideration.
[Definition: The
priority of a template rule is specified by the
priority
attribute on the xsl:template
declaration. If
no priority is specified explicitly for a template rule, its
default priority is used, as defined in
6.5 Default Priority for Template
Rules.]
[ERR XTSE0530] The value of the
priority
attribute must
conform to the rules for the xs:decimal
type defined
in [XML Schema Part 2]. Negative values
are permitted.
If this leaves more than one matching template rule, then:
If the mode
M has an xsl:mode
declaration, and the
attribute value on-multiple-match="fail"
is specified
in the mode declaration, a dynamic error is signaled. The error is
treated as occurring in the xsl:apply-templates
instruction, and can be recovered by wrapping that instruction in
an xsl:try
instruction.
[ERR XTDE0540] It is a dynamic error if the
conflict resolution algorithm for template rules leaves more than
one matching template rule when the declaration of the
relevant mode
has an on-multiple-match
attribute with the value
fail
.
Otherwise, of the matching template rules that remain, the one that occurs last in declaration order is used.
Note:
This was a recoverable error in XSLT 2.0, meaning that it was
implementation-defined whether the error was signaled, or whether
the ambiguity was resolved by taking the last matching rule in
declaration order. In XSLT 3.0 this situation is not an error
unless the attribute value on-multiple-match="fail"
is
specified in the mode declaration. It is also possible to request
warnings when this condition arises, by means of the attribute
warning-on-multiple-match="yes"
.
[Definition: If no priority
attribute is
specified on an xsl:template
element, a
default priority is computed, based on the syntax of the
pattern
supplied in the match
attribute.] The rules are as follows.
If the top-level pattern is a ParenthesizedExprP then the outer parentheses are effectively stripped; these rules are applied recursively to the UnionExprP contained in the ParenthesizedExprP.
If the top-level pattern is a UnionExprP consisting of
multiple alternatives separated by |
or
union
, then the template rule is treated equivalently
to a set of template rules, one for each alternative. These
template rules are adjacent to each other in declaration order, and
the declaration order within this set of template rules (which
affects the result of xsl:next-match
if the
alternatives have the same default priority) is the order of
alternatives in the UnionExprP.
Note:
The splitting of a template rule into multiple rules occurs only
if there is no explicit priority
attribute.
If the top-level pattern is a IntersectExceptExprP
containing two or more PathExprP operands separated
by intersect
or except
operators, then
the priority of the pattern is that of the first PathExprP.
If the pattern is a PredicatePattern then
its priority is 1 (one), unless the PredicateList
is
empty, in which case the priority is −1 (minus one).
If the pattern is a PathExprP taking the form
/
, then the priority is −0.5 (minus 0.5).
If the pattern is a PathExprP taking the form of
an EQName
optionally preceded by a ForwardAxisP or has the
form processing-instruction(
StringLiteralXP30
)
or processing-instruction(
NCNameNames
)
optionally preceded by a ForwardAxisP, then the
priority is 0 (zero).
If the pattern is a PathExprP taking the form of
an ElementTestXP30
or AttributeTestXP30,
optionally preceded by a ForwardAxisP, then the
priority is as shown in the table below. In this table, the symbols
E, A, and T represent an arbitrary
element name, attribute name, and type name respectively, while the
symbol *
represents itself. The presence or absence of
the symbol ?
following a type name 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 | (equivalent to E) |
element(*,T) |
0 | (matches by type only) |
attribute(A) |
0 | (equivalent to @A ) |
attribute(*,T) |
0 | (matches by type only) |
element(E,T) |
0.25 | (matches by name and type) |
schema-element(E) |
0.25 | (matches by substitution group and type) |
attribute(A,T) |
0.25 | (matches by name and type) |
schema-attribute(A) |
0.25 | (matches by name and type) |
If the pattern is a PathExprP taking the form of a DocumentTestXP30, then if it includes no ElementTestXP30 or SchemaElementTestXP30 the priority is −0.5. If it does include an ElementTestXP30 or SchemaElementTestXP30, then the priority is the same as the priority of that ElementTestXP30 or SchemaElementTestXP30, computed according to the table above.
If the pattern is a PathExprP taking the form of
an NCNameNames:*
or *:
NCNameNames,
optionally preceded by a ForwardAxisP, then the
priority is −0.25.
If the pattern is a PathExprP taking the form of any other NodeTestXP30, optionally preceded by a ForwardAxisP, then the priority is −0.5.
In all other cases, 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.
[Definition: Modes allow a node
in a 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 20.1 fn:document) or when
processing temporary trees.]
Modes are identified by an expanded QName; in addition
to any named modes, there is always one unnamed mode available.
Whether a mode is named or unnamed, its properties may be defined in an xsl:mode
declaration. If a mode
name is used (for example in an xsl:template
declaration or an
xsl:apply-templates
instruction) and no declaration of that mode appears in the
stylesheet, the mode is implicitly declared with default
properties.
<!-- Category: declaration -->
<xsl:mode
name? = eqname
streamable? = "yes" | "no"
on-no-match? = "deep-copy" | "shallow-copy" |
"deep-skip" | "shallow-skip" | "text-only-copy" | "fail"
on-multiple-match? = "use-last" | "fail"
warning-on-no-match? = "yes" | "no"
warning-on-multiple-match? = "yes" | "no"
typed? = "yes" | "no" | "strict" | "lax" |
"unspecified"
visibility? = "public" | "private" |
"final" >
<!-- Content: (xsl:context-item?) -->
</xsl:mode>
[Definition: There is always an unnamed mode
available. The unnamed mode is the default mode used when no
mode
attribute is specified on an xsl:apply-templates
instruction or xsl:template
declaration,
unless a different default mode has been specified using the
[xsl:]default-mode
attribute of a containing
element.]
Every mode other than the unnamed mode is identified by an expanded QName.
A stylesheet may contain multiple xsl:mode
declarations and may
include or import stylesheet modules that also
contain xsl:mode
declarations. The name of an xsl:mode
declaration is the value
of its name
attribute, if any.
[Definition: All the xsl:mode
declarations in a
stylesheet that share the same name are grouped into a named
mode definition; those that have no name are grouped into a
single unnamed mode definition.]
If a stylesheet does not contain a declaration of
the unnamed mode, a declaration is implied equivalent to an
xsl:mode
element with the
single attribute initial="yes"
. Similarly, if there is
a mode that is named in an xsl:template
or xsl:apply-templates
element, or in the [xsl:]default-mode
attribute
of a containing element, and the stylesheet does not
contain a declaration of that mode, then a declaration is implied
comprising an xsl:mode
element with a name
attribute plus the attribute
initial="yes"
.
The contained xsl:context-item
element,
if present, is used to declare requirements for the initial context item when this mode
is used as the initial mode. Therefore, there must be no
xsl:context-item
child if initial="no"
is specified.
[ERR XTSE0542] It is a static error if an
xsl:mode
declaration
specifying initial="no"
contains an xsl:context-item
element.
The attributes of the xsl:mode
declaration establish
values for a number of properties of a mode. The allowed values and
meanings of the attributes are given in the following table.
Attribute | Values | Meaning |
---|---|---|
name | A EQName | Specifies the name of the mode. If
omitted, this xsl:mode
declaration provides properties of the unnamed mode |
streamable | yes or no
(default no ) |
Determines whether template rules in
this mode are to be capable of being processed using streaming. If
the value yes is specified, then the body of any
template rule that uses this mode
must conform to the rules for streamable
templates given in 6.6.3
Streamable Templates. |
on-no-match | One of deep-copy ,
shallow-copy , deep-skip ,
shallow-skip , text-only-copy or
fail (default text-only-copy ) |
Determines selection of the built-in
template rules that are used to process a
node when an xsl:apply-templates
instruction selects a node that does not match any user-written
template rule in the stylesheet. For details,
see 6.8 Built-in Template
Rules. |
on-multiple-match | One of fail or
use-last (default use-last ) |
Defines the action to be taken when
xsl:apply-templates is
used in this mode and more than one user-written template
rule is available to process the node, having the same
import precedence and priority. The
value fail indicates that it is a dynamic
error if more than one template rule matches the node. The
value use-last indicates that the situation is not to
be treated as an error (the last template in declaration order is the one that is
used). |
warning-on-no-match | One of yes or
no . The default is implementation-defined |
Requests the processor to output (or
not to output) a warning message in the case where an xsl:apply-templates
instruction selects a node that matches no template rule. The form
and destination of such warnings is implementation-defined. The
processor may ignore this attribute, for
example if the environment provides no suitable means of
communicating with the user. |
warning-on-multiple-match | One of yes or
no . The default is implementation-defined |
Requests the processor to output a
warning message in the case where an xsl:apply-templates
instruction selects a node that matches multiple template rules
having the same import precedence and priority. The
form and destination of such warnings is implementation-defined. The
processor may ignore this attribute, for
example if the environment provides no suitable means of
communicating with the user. |
typed | One of yes ,
no , strict , lax , or
unspecified . The default is
unspecified . |
Informs the processor
whether the nodes to be processed by template rules in this mode
are to be typed or untyped. If the value yes is
specified, then all nodes processed in this mode must be typed (a dynamic error occurs if xsl:apply-templates in
this mode selects an element or attribute whose type annotation is
xs:untyped or xs:untypedAtomic ). If the
value no is specified, then all nodes processed in
this mode must be untyped (a dynamic
error occurs if xsl:apply-templates in
this mode selects an element or attribute whose type annotation is
anything other than xs:untyped or
xs:untypedAtomic ). The value strict
is equivalent to yes , with the additional provision
that within the match pattern of every template rule in this mode,
any NameTest used as an AbbrevForwardStep
(with no preceding "@") in the ForwardStepP of the
first StepExprP of a RelativePathExprP is
interpreted as match="schema-element(product)" , while
match="product/code" is interpreted as
match="schema-element(product)/code" . The value
lax is equivalent to strict , except that
the interpretation of a NameTest as a
SchemaElementTest occurs only if it matches the name
of a global element declaration in the in-scope schema
declarations. The value unspecified is equivalent to
omitting the attribute, and places no constraints on whether the
nodes to be processed in this mode are typed or
untyped. |
visibility | One of public ,
private , or final . The default is
private . |
See 3.6.2.2 Visibility of
Declarations. A mode is not eligible to be used as
the initial mode if its visibility is
private . |
[ERR XTTE3100] It is a type error if an xsl:apply-templates
instruction in a particular mode
selects an element or
attribute whose type is xs:untyped
or
xs:untypedAtomic
when the typed
attribute
of that mode specifies the value yes
,
strict
, or lax
.
[ERR XTTE3110] It is a type error if an xsl:apply-templates
instruction in a particular mode
selects an element or
attribute whose type is anything other than xs:untyped
or xs:untypedAtomic
when the typed
attribute of that mode specifies the value no
.
[Definition: A streamable mode is a mode that is declared in an
xsl:mode
declaration with
the attribute streamable="yes"
.]
For any named mode, the effective value of each attribute is taken
from an xsl:mode
declaration that has a matching name in its name
attribute, and that specifies an explicit value for the required
attribute. If there is more than one such declaration, the one with
highest import precedence is used.
For the unnamed mode, the effective value of each
attribute is taken from an xsl:mode
declaration that has no
name
attribute, and that specifies an explicit value
for the required attribute. If there is no such declaration, the
default value of the attribute is used. If there is more than one
such declaration, the one with highest import precedence
is used.
The above rules apply both to the attributes (other than
name
) of the xsl:mode
element itself, and to
the attributes of the contained xsl:context-item
element
if present.
[ERR XTSE0545] It is a static error if a named
or unnamed mode
contains two conflicting values for the same attribute in different
xsl:mode
declarations
having the same import precedence, unless there is
another definition of the same attribute with higher import
precedence. The attributes in question are the attributes other
than name
on the xsl:mode
element, and the
as
attribute on the contained xsl:context-item
element
if present.
If the initial context item supplied to a stylesheet is a streamed document node, then it is not permitted for the values of global variables to be dependent on the context item in a way that requires reading of the input stream. This constraint is enforced by the following static rule:
[ERR XTSE0548] It is a static error if there
is both (a) a mode definition in the stylesheet
that has the effective attribute values
streamable="yes"
and initial="yes"
, and
(b) a global variable in the stylesheet
whose initializing expression is not motionless with respect to its
context item, as defined in 19
Streamability.
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 specified in the
[xsl:]default-mode
attribute of the innermost
containing element that has such an attribute, which in turn
defaults to the unnamed mode. If the
mode
attribute is present, then its value must be a non-empty whitespace-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:
an EQName, 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 that would apply if
the mode
attribute were absent
the token #unnamed
, to indicate that the template
rule is applicable to the unnamed mode
the token #all
, to indicate that the template rule
is applicable to all modes (specifically, to the
unnamed mode and to every mode that is named
explicitly or implicitly in an xsl:apply-templates
instruction anywhere in the stylesheet).
[ERR XTSE0550] It is a static error if the
list of modes is empty, if the same token is included more than
once in the list, if the list contains an invalid token, 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 be one of the
following:
an EQName, which is expanded as described in 5.1 Qualified Names to define the name of a mode
the token #default
, to indicate that the default
mode for the stylesheet module is to be
used
the token #unnamed
, to indicate that the unnamed
mode is to be used
the token #current
, to indicate that the current
mode is to be used
If the attribute is omitted, the default mode for the stylesheet module is used.
When searching for a template rule to process each
item 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 initial mode, 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 non-contextual function
call is made, the current mode is set to the unnamed
mode. While evaluating global variables and parameters, and the
sequence constructor contained in xsl:key
or xsl:sort
, the current mode is set
to the unnamed mode. No other instruction changes the current mode.
The current mode while evaluating an attribute set is the
same as the current mode of the caller. 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.9 Overriding
Template Rules).
A template is guaranteed-streamable if and only if all the following conditions are satisfied:
The pattern defined in the match
attribute of the xsl:template
element
is a motionless pattern as defined in 19.8.9 Classifying Patterns.
The sequence constructor contained in
the body of the xsl:template
element is
grounded, as defined in 19 Streamability.
Every expression and contained sequence constructor in a contained
xsl:param
element (the
construct that provides the default value of the parameter)
is motionless.
Specifying streamable="yes"
on an xsl:mode
declaration declares an
intent that every template rule that includes that mode (explicitly
or implicitly, including by specifying #all
), should
be guaranteed streamable according to these criteria. The
consequences of declaring the mode to be streamable when there is
such a template rule that is not guaranteed streamable depend on
the conformance level of the processor, and are explained in
19.10 Streamability
Guarantees.
Processing of a document using streamable templates may be
initiated using code such as the following, where S
is
a mode declared with streamable="yes"
:
<xsl:stream href="bigdoc.xml"> <xsl:apply-templates mode="S"/> </xsl:stream>
Alternatively, streamed processing may be initiated by invoking the transformation with an initial mode declared as streamable, while supplying the initial context item (in an implementation-defined way) as a streamed document.
Note:
Invoking a streamable template using the construct
<xsl:apply-templates
select="doc('bigdoc.xml')"/>
does not ensure streamed
processing. As always, processors may use streamed processing if
they are able to do so, but when the doc
FO30
or document
functions are
used, processors are obliged to ensure that the results are
deterministic, which may be difficult to reconcile with streaming
(if the same document is read twice, the results must be
identical). The use of xsl:stream
does not offer the
same guarantees of determinism.
For an example of processing a collection of documents by use of
the function
uri-collection
FO30 in
conjunction with xsl:stream
, see 18.1.2 Examples of xsl:stream .
The xsl:context-item
element
is used for two purposes:
As a child of xsl:mode
,
it declares the required type of the initial context item that is
supplied by the calling application when this mode is used as the
initial mode.
As a child of xsl:template
, it declares the
required type of the context item when the containing template is
called using an xsl:call-template
instruction.
<xsl:context-item
as? = sequence-type
use? = "required" | "optional" |
"prohibited" />
If the as
attribute is present then its value must
be an ItemTypeXP30.
If the attribute is omitted this is equivalent to specifying
as="item()"
.
A type error is signaled if the supplied context
item does not match its required type. The error code is the same
as for xsl:param
:
[see ERR
XTTE0590].
This section applies when xsl:context-item
is used
to declare the initial context item for a mode.
When the xsl:context-item
element
appears as a child of xsl:mode
, the only permitted value
for the use
attribute is required
,
indicating that an initial context item must be supplied by the calling application when this
mode is selected as the initial mode. The context item that is
supplied will be converted to the declared type using the function conversion rules. This
may result in a type error if the conversion is not
possible.
Note:
If the ItemType
is one that can only be satisfied
by a schema-validated input document, for example
as="schema-element(invoice)"
, the processor may interpret
this as a request to apply schema validation to the input.
Similarly, if the KindTest
indicates that an element
node is required, the processor may interpret this as a request to
supply the document element rather than the document node of a
supplied input document.
If there is no xsl:context-item
element
for an xsl:mode
that
specifies initial="yes"
, this is equivalent to
specifying <xsl:context-item as="item()"/>
The following example declares two modes, both of which have
initial="yes"
meaning that they can be used as entry
points to the stylesheet. In the first mode, named
invoice
, the required context item is a
schema-validated invoice
element. In the second mode,
named po
, the required context item is a
schema-validated purchase-order
element. A third mode,
format-address
is declared with
initial="no"
so it cannot be used as an initial entry
point; this mode might be used when processing content that is
common to invoices and purchase orders.
<xsl:mode name="invoice" initial="yes" on-no-match="deep-copy"> <xsl:context-item as="schema-element(invoice)"/> </xsl:mode> <xsl:mode name="po" initial="yes" on-no-match="deep-copy"> <xsl:context-item as="schema-element(purchase-order)"/> </xsl:mode> <xsl:mode name="format-address" initial="no"/>
The xsl:context-item
element
can appear as a child of xsl:template
to define the
type of the context item passed to a named template. If the named
template is also the initial template, then this
constrains the initial context item for the
transformation as a whole.
If an xsl:context-item
element
is present as the first child element of xsl:template
, it defines
whether the template requires a context item to be supplied, and if
so, what the type of the context item must be. If this template is
the initial template, then this has the
effect of placing constraints on the initial context item for the
transformation as a whole.
The use
attribute of xsl:context-item
takes the
value required
, optional
, or
prohibited
. If the value required
is
specified, then there must be a context item. (This will
automatically be the case if the template is invoked using xsl:apply-templates
,
xsl:apply-imports
, or
xsl:next-match
, but
not if it is invoked using xsl:call-template
). If
the value optional
is specified, or if the attribute
is omitted, or if the xsl:context-item
element
is omitted, then there may or may not be a context item when the
template is invoked. If the containing xsl:template
element has no
name
attribute then the only permitted value is
required
. If the value prohibited
is
specified, then there will be no context item available to the body
template (if the calling template has a context item, it will not
be made available to the called template).
The as
attribute of the xsl:context-item
defines
the required type of the context item supplied to the template if
one is supplied. The default value is as="item()"
. If
a context item is supplied (which will automatically be the case if
the template is invoked using xsl:apply-templates
,
xsl:apply-imports
, or
xsl:next-match
) then
if will be converted to the required type by applying the function conversion rules; a
type
error [see ERR
XTTE0590] occurs if conversion to the required type is
not possible. The processor may signal a
type
error statically if the required context item type is
incompatible with the match
pattern, that is, if no
item that satisfies the match pattern can also satisfy the required
context item type.
The xsl:context-item
element
plays no part in deciding whether and when the template rule is
invoked in response to an xsl:apply-templates
instruction.
[ERR XTTE3090] It is a type error if the
xsl:context-item
child of xsl:template
specifies that a context item is required and none is supplied by
the caller, that is, if the context item is absent at the point
where xsl:call-template
is
evaluated.
When an item is selected by xsl:apply-templates
and
there is no user-specified template rule in the stylesheet
that can be used to process that item, then a built-in
template rule is evaluated instead.
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.
There are six sets of built-in template rules available. The set
that is chosen is a property of the mode selected by the xsl:apply-templates
instruction. This property is set using the
on-no-match
attribute of the xsl:mode
declaration, which takes
one of the six values deep-copy
,
shallow-copy
, deep-skip
,
shallow-skip
, text-only-copy
, or
fail
, the default being text-only-copy
.
The effect of these six sets of built-in template rules is
explained in the following subsections.
The effect of processing a tree using a mode that specifies
on-no-match="text-only-copy"
is that the
textual content of the source document is retained while losing the
markup, except where explicit template rules dictate otherwise.
When an element is encountered for which there is no explicit
template rule, the processing continues
with the children of that element. Text nodes are copied to the
output.
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.
The built-in template rule for text and attribute nodes and atomic values returns a text node containing the string value of the context node. It is effectively:
<xsl:template match="text()|@*|xs:anyAtomicType" mode="M"> <xsl:value-of select="string(.)"/> </xsl:template>
Note:
This text node may have a string value that is zero-length.
The built-in template rule for processing instructions, comments, namespace nodes, and function items does nothing (it returns the empty sequence).
<xsl:template match="processing-instruction()|comment()|namespace-node()|function(*)" mode="M"/>
Suppose the stylesheet contains the following instruction:
<xsl:apply-templates select="title" mode="M"> <xsl:with-param name="init" select="10"/> </xsl:apply-templates>
If there is no explicit template rule that matches the
title
element, then the following implicit rule is
used:
<xsl:template match="title" mode="M"> <xsl:param name="init"/> <xsl:apply-templates mode="#current"> <xsl:with-param name="init" select="$init"/> </xsl:apply-templates> </xsl:template>
The effect of processing a tree using a mode that specifies
on-no-match="deep-copy"
is that an unmatched
element in the source tree is copied unchanged to the output,
together with its entire subtree. Other unmatched items are also
copied unchanged. The subtree is copied unconditionally, without
attempting to match nodes in the subtree against template
rules.
When this default action is selected for a mode M, all items (nodes, atomic values, and functions) are processed using a template rule that is equivalent to the following:
<xsl:template match="." mode="M"> <xsl:copy-of select="." validation="preserve"/> </xsl:template>
The effect of processing a tree using a mode that specifies
on-no-match="shallow-copy"
is that the source
tree is copied unchanged to the output, except for nodes where
different processing is specified using an explicit template
rule.
When this default action is selected for a mode M,
all items (nodes, atomic values, and functions) are
processed using a template rule that is equivalent to the
following, except that all parameters supplied in xsl:with-param
elements are
passed on implicitly to the called templates:
<xsl:template match="." mode="M"> <xsl:copy validation="preserve"> <xsl:apply-templates select="@*" mode="M"/> <xsl:apply-templates select="node()" mode="M"/> </xsl:copy> </xsl:template>
This rule is often referred to as the identity template, though it should be noted that it does not preserve node identity.
Note:
This rule differs from the traditional identity template rule by
using two xsl:apply-templates
instructions, one to process the attributes and one to process the
children. The only observable difference from the traditional
select="node() | @*
is that with two separate
instructions, the value of position()
in the called
templates forms one sequence starting at 1 for the attributes, and
a new sequence starting at 1 for the children.
A further reason for choosing this form is for streamability:
this formulation is guaranteed-streamable, whereas the
traditional form using select="node() | @*"
is not
(see 19.8.4.5
Streamability of xsl:apply-templates).
The following stylesheet transforms an input document by
deleting all elements named note
, together with their
attributes and descendants:
<xsl:stylesheet version="3.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> <xsl:mode on-no-match="shallow-copy" streamable="yes"/> <xsl:template match="note"> <!-- no action --> </xsl:template> </xsl:stylesheet>
The effect of processing a tree using a mode that specifies
on-no-match="deep-skip"
is that where no explicit
template rule is specified for an element, that element and all its
descendants are ignored, and are not copied to the result tree.
The effect of choosing on-no-match="deep-skip"
is
as follows:
The built-in rule for document 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.
The built-in rule for all items other than document nodes (that is, for all other kinds of node, as well as atomic values and functions) is to do nothing, that is, to return an empty sequence (without applying templates to any children or ancestors).
The effect of processing a tree using a mode that specifies
on-no-match="shallow-skip"
is to drop both the
textual content and the markup from the result document, except
where there is an explicit user-written template rule that
dictates otherwise.
The built-in rule for document nodes and element nodes is the
same as for on-no-match="text-only-copy"
: that is, it
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.
The built-in template rule for all other kinds of node, and for atomic values and functions, is empty: that is, when the item is matched, the built-in template rule returns an empty sequence.
The effect of choosing on-no-match="fail"
for a
mode is that
every item selected in an xsl:apply-templates
instruction must be matched by an explicit user-written template
rule.
The built-in template rule is effectively:
<xsl:template match="." mode="M"> <xsl:message terminate="yes" error-code="err:XTDE0555"/> </xsl:template>
with an implementation-dependent message body.
[ERR XTDE0555] It is a dynamic error if
xsl:apply-templates
,
xsl:apply-imports
or xsl:next-match
is
used to process a node using a mode whose declaration specifies
on-no-match="fail"
when there is no template
rule in the stylesheet whose match pattern matches that
node.
<!-- 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,
and also declarations of the same precedence and priority
that appear earlier in declaration order. Both
instructions will invoke the built-in template rule for the
context item (see 6.8
Built-in Template Rules) if no other template rule is
found.
[Definition: At any point in the processing of a
stylesheet, there may be a current template
rule. Whenever a template rule is chosen as a result of
evaluating xsl:apply-templates
,
xsl:apply-imports
, or
xsl:next-match
, the
template rule becomes the current template rule for the evaluation
of the rule's sequence constructor. When an xsl:for-each
, xsl:for-each-group
,
xsl:analyze-string
,
xsl:iterate
,
xsl:stream
, xsl:merge
, or xsl:evaluate
instruction is evaluated, or when evaluating a sequence constructor
contained in an xsl:sort
or xsl:key
element, or when
a non-contextual function
call is made, the current template rule becomes
absent 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 absent.
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.
Both xsl:apply-imports
and
xsl:next-match
search for a template rule that matches the
context item, and that is applicable
to the current mode (see 6.6
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, plus
the template rules with the same import precedence and
priority that occur before the current template rule in declaration order.
Note:
As explained in 6.4 Conflict Resolution
for Template Rules, a template rule with no
priority
attribute, whose match pattern
contains multiple alternatives separated by |
, is
treated equivalently to a set of template rules, one for each
alternative. This means that where the same item
matches more than one alternative, it is possible for an xsl:next-match
instruction
to cause the current template rule to be invoked recursively. This
situation does not occur when the template rule has an
explicit priority.
If no matching template rule is found that satisfies these criteria, the built-in template rule for the context item is used (see 6.8 Built-in Template Rules).
An xsl:apply-imports
or
xsl:next-match
instruction may use xsl:with-param
child
elements to pass parameters to the chosen template rule (see
9.10 Setting Parameter Values). It
also passes on any tunnel parameters as described in
10.1.2 Tunnel Parameters.
[ERR XTDE0560] It is a dynamic error if
xsl:apply-imports
or xsl:next-match
is
evaluated when the current template rule is
absent.
xsl: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 or 3.0 processor, but can be
used to define fallback behavior when the stylesheet is processed
by an XSLT 1.0 processor with forwards compatible behavior.
A template rule may have parameters. The parameters are declared
in the body of the template using xsl:param
elements, as described
in 9.2 Parameters.
Values for these parameters may be supplied in the calling
xsl:apply-templates
,
xsl:apply-imports
, or
xsl:next-match
instruction by means of xsl:with-param
elements
appearing as children of the calling instruction. The expanded
QName represented by the name
attribute of the
xsl:with-param
element must match the expanded QName represented by the
name
attribute of the corresponding xsl:param
element.
[ERR XTDE0700] It is a dynamic error if a
template that is invoked using xsl:apply-templates
,
xsl:apply-imports
, or
xsl:next-match
declares a template parameter with
required="yes"
and no value for this parameter is
supplied by the calling instruction. The same error is reported in
the case of a tunnel parameter whether invoked using
one of these three instructions or by xsl:call-template
, as
explained in 10.1.2 Tunnel
Parameters.
It is not an error for these instructions to supply a parameter that does not match any parameter declared in the template rule that is invoked; unneeded parameter values are simply ignored.
A parameter may be declared as a tunnel parameter by
specifying tunnel="yes"
in the xsl:param
declaration; in this
case the caller must supply the value as a tunnel parameter by
specifying tunnel="yes"
in the corresponding xsl:with-param
element.
Tunnel parameters differ from ordinary template parameters in that
they are passed transparently through multiple template
invocations. They are fully described in 10.1.2 Tunnel Parameters.
XSLT offers two constructs for processing each item of a
sequence: xsl:for-each
and xsl:iterate
.
The main difference between the two constructs is that with
xsl:for-each
, the
processing applied to each item in the sequence is independent of
the processing applied to any other item; this means that the items
may be processed in any order or in parallel, though the order of
the output sequence is well defined and corresponds to the order of
the input (sorted if so requested). By contrast, with xsl:iterate
, the processing is
explicitly sequential: while one item is being processed, values
may be computed which are then available for use while the next
item is being processed. This makes xsl:iterate
suitable for tasks
such as creating a running total over a sequence of financial
transactions.
A further difference is that xsl:for-each
permits sorting
of the input sequence, while xsl:iterate
does not.
xsl:for-each
instruction<!-- Category: instruction
-->
<xsl:for-each
select = 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; it contains an expression which is evaluated
to produce 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.
The sequence constructor is evaluated
once for each item in the sorted sequence, with the focus set as
follows:
The context item is the item being processed.
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.8
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.
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>
xsl:iterate
Instruction<!-- Category: instruction
-->
<xsl:iterate
select = expression >
<!-- Content: (xsl:param*, sequence-constructor,
xsl:on-completion?)
-->
</xsl:iterate>
<!-- Category: instruction
-->
<xsl:next-iteration>
<!-- Content: (xsl:with-param*) -->
</xsl:next-iteration>
<!-- Category: instruction
-->
<xsl:break
select? = expression >
<!-- Content: (sequence-constructor)
-->
</xsl:break>
<xsl:on-completion
select? = expression >
<!-- Content: (sequence-constructor)
-->
</xsl:on-completion>
The select
attribute is required; it contains an expression which is evaluated
to produce a sequence, called the input sequence.
The sequence constructor contained in
the xsl:iterate
instruction is evaluated once for each item in the input sequence,
in order, or until the loop exits by evaluating an xsl:break
instruction, whichever
is earlier. Within the sequence constructor
that forms the body of the xsl:iterate
instruction, the
context item is set to each item from the
value of the select
expression in turn; the context position reflects the position
of this item in the input sequence, and the context size is the
number of items in the input sequence (which may be greater than
the number of iterations, if the loop exits prematurely using
xsl:break
).
Note:
If xsl:iterate
is
used in conjunction with xsl:stream
to achieve streaming,
calls on the function last
FO30
will be disallowed.
The xsl:break
and
xsl:on-completion
elements may have either a select
attribute or a
non-empty contained sequence constructor but not
both. The effect of the element in both cases is obtained by
evaluating the select
expression if present or the
contained sequence constructor otherwise; if neither is present,
the value is an empty sequence.
The effect of xsl:next-iteration
is to
cause the iteration to continue by processing the next item in the
input sequence, potentially with different values for the iteration
parameters. The effect of xsl:break
is to cause the
iteration to finish, whether or not all the items in the input
sequence have been processed. In both cases the affected iteration
is the one controlled by the innermost ancestor xsl:iterate
element.
The instructions xsl:next-iteration
and
xsl:break
are allowed
only as descendants of an xsl:iterate
instruction, and
only in a tail position within the sequence constructor forming the
body of the xsl:iterate
instruction.
[Definition: An instruction J is in a tail position within a sequence constructor SC if it satisfies one of the following conditions:]
J is the last instruction in SC, ignoring
any xsl:fallback
instructions.
J is in a tail position within the sequence
constructor that forms the body of an xsl:if
instruction that is itself in
a tail position within SC.
J is in a tail position within the sequence
constructor that forms the body of an xsl:when
or xsl:otherwise
branch of an
xsl:choose
instruction
that is itself in a tail position within SC.
J is in a tail position within the sequence
constructor that forms the body of an xsl:try
instruction that is itself
in a tail position within SC (that
is, it is immediately followed by an xsl:catch
element, ignoring any
xsl:fallback
elements).
J is in a tail position within the sequence
constructor that forms the body of an xsl:catch
element within an
xsl:try
instruction that is
itself in a tail position within SC.
[ERR XTSE3120] It is a static error if an
xsl:break
or xsl:next-iteration
element appears other than in a tail position within the
sequence constructor forming the
body of an xsl:iterate
instruction.
[ERR XTSE3125] It is a static error if the
select
attribute of xsl:break
or xsl:on-completion
is
present and the instruction has children.
[ERR XTSE3130] It is a static error if the
name
attribute of an xsl:with-param
child of an
xsl:next-iteration
element does not match the name
attribute of an
xsl:param
child of the
innermost containing xsl:iterate
instruction.
Parameter names in xsl:with-param
must be
unique: [see ERR
XTSE0670].
The result of the xsl:iterate
instruction is the
concatenation of the sequences that result from the repeated
evaluation of the contained sequence constructor,
followed by the sequence that results from evaluating the xsl:break
or xsl:on-completion
element
if any.
Any xsl:param
element
that appears as a child of xsl:iterate
declares a
parameter whose value may vary from one iteration to the next. The
initial value of the parameter is the value obtained according to
the rules given in 9.3 Values of
Variables and Parameters. The dynamic context for
evaluating the initial value of an xsl:param
element is the same as
the dynamic context for evaluating the select
expression of the xsl:iterate
instruction (the
context item is thus not the first item in the input
sequence).
On the first iteration a parameter always takes its initial value (which may depend on variables or other aspects of the dynamic context). Subsequently:
If an xsl:next-iteration
instruction is evaluated, then parameter values for processing the
next item in the input sequence can be set in the xsl:with-param
children of
that instruction; in the absence of an xsl:with-param
element that
names a particular parameter, that parameter will retain its value
from the previous iteration.
If an xsl:break
instruction is evaluated, no further items in the input sequence
are processed.
If neither an xsl:next-iteration
nor
an xsl:break
instruction
is evaluated, then the next item in the input sequence is processed
using parameter values that are unchanged from the previous
iteration.
The xsl:next-iteration
instruction contributes nothing to the result sequence
(technically, it returns an empty sequence). The instruction
supplies parameter values for the next iteration, which are
evaluated according to the rules given in 9.10 Setting Parameter Values; if there
are no further items in the input sequence then it supplies
parameter values for use while evaluating the body of the xsl:on-completion
element
if any.
The xsl:break
instruction indicates that the iteration should terminate without
processing any remaining items from the input sequence. The
select
expression or contained sequence
constructor is evaluated using the same context item, position, and
size as the xsl:break
instruction itself, and the result is appended to the result of the
xsl:iterate
instruction
as a whole.
If neither an xsl:next-iteration
nor
an xsl:break
instruction
is evaluated, the next item in the input sequence is processed with
parameter values unchanged from the previous iteration; if there
are no further items in the input sequence, the iteration
terminates.
The optional xsl:on-completion
element
(which is not technically an instruction and is not technically part
of the sequence constructor) is evaluated
when the input sequence is exhausted. It is not evaluated if the
evaluation is terminated using xsl:break
. During evaluation of
this sequence constructor the context item, position, and size are
absent
(that is, any reference to these values is an error). However, the
values of the parameters to xsl:iterate
are available, and
take the values supplied by the xsl:next-iteration
instruction evaluated while processing the last item in the
sequence.
If the input sequence is empty, then the result of the xsl:iterate
instruction is the
result of evaluating the sequence constructor
forming the body of the xsl:on-completion
element, using the initial values of the xsl:param
elements. If there is
no xsl:on-completion
element, the result is an empty sequence.
Note:
Conceptually, xsl:iterate
behaves like a
tail-recursive function. The xsl:next-iteration
instruction then represents the recursive call, supplying the tail
of the input sequence as an implicit parameter. There are two main
reasons for providing the xsl:iterate
instruction. One is
that many XSLT users find writing recursive functions to be a
difficult skill, and this construct promises to be easier to learn.
The other is that recursive function calls are difficult for an
optimizer to analyze. Because xsl:iterate
is more constrained
than a general-purpose head-tail recursive function, it should be
more amenable to optimization. In particular, when the instruction
is used in conjunction with xsl:stream
, it is designed to
make it easy for the implementation to use streaming techniques,
processing the nodes in an input document sequentially as they are
read, without building the entire document tree in memory.
The examples below use xsl:iterate
in conjunction with
the xsl:stream
instruction. This is not the only way of using xsl:iterate
, but it illustrates
the way in which the two features can be combined to achieve
streaming of a large input document.
xsl:iterate
to Compute
Cumulative TotalsSuppose that the input XML document has this structure
<transactions> <transaction date="2008-09-01" value="12.00"/> <transaction date="2008-09-01" value="8.00"/> <transaction date="2008-09-02" value="-2.00"/> <transaction date="2008-09-02" value="5.00"/> </transactions>
and that the requirement is to transform this to:
<account> <balance date="2008-09-01" value="12.00"/> <balance date="2008-09-01" value="20.00"/> <balance date="2008-09-02" value="18.00"/> <balance date="2008-09-02" value="23.00"/> </account>
This can be achieved using the following code, which is designed to process the transaction file using streaming:
<account> <xsl:stream href="transactions.xml"> <xsl:iterate select="transactions/transaction"> <xsl:param name="balance" select="0.00" as="xs:decimal"/> <xsl:variable name="newBalance" select="$balance + xs:decimal(@value)"/> <balance date="{@date}" value="{$newBalance}"/> <xsl:next-iteration> <xsl:with-param name="balance" select="$newBalance"/> </xsl:next-iteration> </xsl:iterate> </xsl:stream> </account>
The following example modifies this by only outputting the information for the first day's transactions:
<account> <xsl:stream href="'transactions.xml"> <xsl:iterate select="transactions/transaction"> <xsl:param name="balance" select="0.00" as="xs:decimal"/> <xsl:param name="prevDate" select="()" as="xs:date?"/> <xsl:variable name="newBalance" select="$balance + xs:decimal(@value)"/> <xsl:variable name="thisDate" select="xs:date(@date)"/> <xsl:choose> <xsl:when test="empty($prevDate) or $thisDate eq $prevDate"> <balance date="{$thisDate}" value="{format-number($newBalance, '0.00')}"/> <xsl:next-iteration> <xsl:with-param name="balance" select="$newBalance"/> <xsl:with-param name="prevDate" select="$thisDate"/> </xsl:next-iteration> </xsl:when> <xsl:otherwise> <xsl:break/> </xsl:otherwise> </xsl:choose> </xsl:iterate> </xsl:stream> </account>
The following code outputs the balance only at the end of each day, together with the final balance:
<account> <xsl:stream href="transactions.xml"> <xsl:iterate select="transactions/transaction"> <xsl:param name="balance" select="0.00" as="xs:decimal"/> <xsl:param name="prevDate" select="()" as="xs:date?"/> <xsl:variable name="newBalance" select="$balance + xs:decimal(@value)"/> <xsl:variable name="thisDate" select="xs:date(@date)"/> <xsl:if test="exists($prevDate) and $thisDate ne $prevDate"> <balance date="{$prevDate}" value="{format-number($balance, '0.00')}"/> </xsl:if> <xsl:next-iteration> <xsl:with-param name="balance" select="$newBalance"/> <xsl:with-param name="prevDate" select="$thisDate"/> </xsl:next-iteration> <xsl:on-completion> <balance date="{$prevDate}" value="{format-number($balance, '0.00')}"/> </xsl:on-completion> </xsl:iterate> </xsl:stream> </account>
If the sequence of transactions is empty, this code outputs a
single element: <balance date=""
value="0.00"/>
.
Problem: Given a sequence of employee
elements,
find the employees having the highest and lowest salary, while
processing each employee only once.
Solution:
<xsl:stream href="employees.xml"> <xsl:iterate select="employees/employee"> <xsl:param name="highest" as="element(employee)*"/> <xsl:param name="lowest" as="element(employee)*"/> <xsl:variable name="is-new-highest" as="xs:boolean" select="empty($highest[@salary ge current()/@salary])"/> <xsl:variable name="is-equal-highest" as="xs:boolean" select="exists($highest[@salary eq current()/@salary])"/> <xsl:variable name="is-new-lowest" as="xs:boolean" select="empty($lowest[@salary le current()/@salary])"/> <xsl:variable name="is-equal-lowest" as="xs:boolean" select="exists($lowest[@salary eq current()/@salary])"/> <xsl:variable name="new-highest-set" as="element(employee)*" select="if ($is-new-highest) then . else if ($is-equal-highest) then ($highest, .) else $highest"/> <xsl:variable name="new-lowest-set" as="element(employee)*" select="if ($is-new-lowest) then . else if ($is-equal-lowest) then ($lowest, .) else $lowest"/> <xsl:next-iteration> <xsl:with-param name="highest" select="$new-highest-set"/> <xsl:with-param name="lowest" select="$new-lowest-set"/> </xsl:next-iteration> <xsl:on-completion> <highest-paid-employees> <xsl:value-of select="$highest/name"/> </highest-paid-employees> <lowest-paid-employees> <xsl:value-of select="$lowest/name"/> </lowest-paid-employees> </xsl:on-completion> </xsl:iterate> </xsl:stream>
If the input sequence is empty, this code outputs an empty
highest-paid-employees
element and an empty
lowest-paid-employees
element.
When streaming, some limited look-ahead is needed to determine
whether the item being processed is the last in a sequence. The
last
FO30
function cannot be used in guaranteed-streamable code. The
xsl:iterate
instruction
provides a solution to this problem.
Problem: render the last paragraph in a section in some special
way, for example by using bold face. (The actual rendition is
achieved by processing the paragraph with mode
last-para
.)
The solution uses xsl:iterate
together with
the copy-of
function to maintain a one-element lookahead by explicit
coding:
<xsl:template match="section" mode="streaming"> <xsl:iterate select="para"> <xsl:param name="prev" select="()" as="element(para)?"/> <xsl:if test="$prev"> <xsl:apply-templates select="$prev"/> </xsl:if> <xsl:next-iteration> <xsl:with-param name="prev" select="copy-of(.)"/> </xsl:next-iteration> <xsl:on-completion> <xsl:apply-templates select="$prev" mode="last-para"/> </xsl:on-completion> </xsl:iterate> </xsl:template>
There are two instructions in XSLT that support conditional
processing: 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.
XSLT 3.0 also supports xsl:try
and xsl:catch
which define
conditional processing to handle dynamic errors.
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
valueXP30 of the expression in the
test
attribute. The rules for determining the
effective boolean value of an expression are given in [XPath 3.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.8 Sequence
Constructors), and the resulting 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 one or more 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
valueXP30 of the expression
in its test
attribute is true
. The rules
for determining the effective boolean value of an expression are
given in [XPath 3.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>
The xsl:try
instruction
can be used to trap dynamic errors occurring within the expression
it wraps; the recovery action if such errors occur is defined using
a child xsl:catch
element.
<!-- Category: instruction -->
<xsl:try
select? = expression >
<!-- Content: (sequence-constructor,
xsl:catch, (xsl:catch | xsl:fallback)*) -->
</xsl:try>
Note:
Because a sequence constructor may contain an xsl:fallback
element, the
effect of this content model is that an xsl:fallback
instruction may
appear as a child of xsl:try
in any position.
<xsl:catch
errors? = tokens
select? = expression >
<!-- Content: sequence-constructor
-->
</xsl:catch>
An xsl:try
instruction
evaluates either the expression contained in its
select
attribute, or its contained sequence constructor, and returns
the result of that evaluation if it succeeds without error. If a
dynamic error occurs during the evaluation,
the processor evaluates the first xsl:catch
child element
applicable to the error, and returns that result instead.
If the xsl:try
element
has a select
attribute, then it must have no children other than xsl:catch
and xsl:fallback
. That is, the
select
attribute and the contained sequence
constructor are mutually exclusive. If neither is present, the
result of the xsl:try
is an
empty sequence (no dynamic error can occur in this case).
[ERR XTSE3140] It is a static error if the
select
attribute of the xsl:try
element is present and the
element has children other than xsl:catch
and xsl:fallback
elements.
Any xsl:fallback
children of the xsl:try
element are ignored by an XSLT 3.0 processor, but can be used to
define the recovery action taken by an XSLT 1.0 or XSLT 2.0
processor operating with forwards
compatible behavior.
The xsl:catch
element
has an optional errors
attribute, which lists the
error conditions that the xsl:catch
element is designed to
intercept. The default value is errors="*"
, which
catches all errors. The value is a whitespace-separated list of
NameTestsXP30;
an xsl:catch
element
catches an error condition if this list includes a
NameTest
that matches the error code associated with
that error condition.
Note:
Error codes are QNames. Those defined in this specification and
in related specifications are all in the standard error namespace, and
may therefore be caught using an xsl:catch
element such as
<xsl:catch errors="err:FODC0001 err:FODC0005">
where the namespace prefix err
is bound to this
namespace. Errors defined by implementors, and errors raised by an
explicit call of the error
FO30
function or by use of the xsl:message
or xsl:assert
instruction,
may use error codes in other namespaces.
If more than one xsl:catch
element matches an
error, the error is processed using the first one that matches, in
document order. If no xsl:catch
matches the error, then
the error is not caught (that is, evaluation of the xsl:try
element fails with the
dynamic error).
An xsl:catch
element
may have either a select
attribute, or a contained
sequence constructor.
[ERR XTSE3150] It is a static error if the
select
attribute of the xsl:catch
element is present
unless the element has empty content.
The result of evaluating the xsl:catch
element is the result
of evaluating the XPath expression in its select
attribute or the result of evaluating the contained sequence
constructor; if neither is present, the result is an empty
sequence. This result is delivered as the result of the
xsl:try
instruction.
If a dynamic error occurs during the evaluation of xsl:catch
, it causes the
containing xsl:try
to fail
with this error. The error is not caught by other sibling xsl:catch
elements within the
same xsl:try
instruction,
but it may be caught by an xsl:try
instruction at an outer
level, or by an xsl:try
instruction nested within the xsl:catch
.
Within the select
expression, or within the
sequence constructor contained by the xsl:catch
element, a number of
variables are implicitly declared, giving information about the
error that occurred. These are lexically scoped to the
xsl:catch
element. These variables are all in the
standard error namespace, and
they are initialized as described in the following table:
Variable | Type | Value |
---|---|---|
err:code | xs:QName | The error code |
err:description | xs:string? | A description of the error condition;
an empty sequence if no description is available (for
example, if the error FO30
function was called with one argument). |
err:value | item()* | Value associated with the error. For
an error raised by calling the error FO30
function, this is the value of the third argument (if supplied).
For an error raised by evaluating xsl:message with
terminate="yes" , or a failing xsl:assert , this is the
document node at the root of the tree containing the XML message
body. |
err:module | xs:string? | The URI (or system ID) of the stylesheet module containing the instruction where the error occurred; an empty sequence if the information is not available. |
err:line-number | xs:integer? | The line number within the stylesheet module of the instruction where the error occurred; an empty sequence if the information is not available. The value may be approximate. |
err:column-number | xs:integer? | The column number within the stylesheet module of the instruction where the error occurred; an empty sequence if the information is not available. The value may be approximate. |
Variables declared within the sequence constructor of the
xsl:try
element (and not
within an xsl:catch
) are
not visible within the xsl:catch
element.
Note:
Within an xsl:catch
it
is possible to re-throw the error using the function call
error($err:code, $err:description, $err:value)
.
The following additional rules apply to the catching of errors:
All dynamic errors occurring during the evaluation of the
xsl:try
sequence
constructor or select
expression are caught (provided
they match one of the xsl:catch
elements).
This includes errors occurring in functions or templates invoked
in the course of this evaluation, unless already caught by a nested
xsl:try
.
It also includes errors caused by calling the error
FO30
function, or the xsl:message
instruction with
terminate="yes"
, or the xsl:assert
instruction.
It does not include errors that occur while evaluating
references to variables whose declaration and initialization is
outside the xsl:try
.
The existence of an xsl:try
instruction does not affect
the obligation of the processor to signal certain errors as static
errors, or its right to choose whether to signal some errors (such
as type
errors) statically or dynamically. Static errors are never
caught.
Some fatal errors arising in the processing environment, such as
running out of memory, may cause termination of the transformation
despite the presence of an xsl:try
instruction. This is
implementation-dependent.
If the sequence constructor or select
expression of
the xsl:try
causes
execution of xsl:result-document
,
xsl:message
, or
xsl:assert
instructions and fails with a dynamic error that is caught, it is
implementation-dependent whether these instructions have any
externally visible effect. The processor is not
required to roll back any changes made by these
instructions. The same applies to any side effects caused by
extension functions or extension instructions.
A serialization error that occurs during the serialization of a
final result tree produced using
xsl:result-document
is
treated as a dynamic error in the evaluation of the xsl:result-document
instruction, and may be caught by a containing xsl:try
instruction. A
serialization error that occurs while serializing the implicit
final result tree returned by the
initial template is treated as occurring
after the transformation has finished, and cannot be caught.
A validation error is treated as occurring in the instruction
that requested validation. For example, if the stylesheet is
producing XHTML output and requests validation of the entire result
document by means of the attribute validation="strict"
on the instruction that creates the outermost html
element, then a validation failure can be caught only at that
level. Although the validation error might be detected, for
example, while writing a p
element at a location where
no p
element is allowed, it is not treated as an error
in the instruction that writes the p
element and
cannot be caught at that level.
A type error may be caught if the processor raises it dynamically; this does not affect the processor's right to raise the error statically if it chooses.
The following rules are provided to define which expression is considered to fail when a type error occurs, and therefore where the error can be caught. The general principle is that where the semantics of a construct C place requirements on the type of some subexpression, a type error is an error in the evaluation of C, not in the evaluation of the subexpression.
For example, consider the following construct:
<xsl:variable name="v" as="xs:integer"> <xsl:sequence select="$foo"/> </xsl:variable>
The expected type of the result of the sequence constructor is
xs:integer
; if the value of variable $foo
turns out to be a string, then a type error will occur. It is not
possible to catch this by writing:
<xsl:variable name="v" as="xs:integer"> <xsl:try> <xsl:sequence select="$foo"/> <xsl:catch>...</xsl:catch> </xsl:try> </xsl:variable>
This fails to catch the error because the xsl:sequence
instruction is
deemed to evaluate successfully; the failure only occurs when the
result of this instruction is bound to the variable.
A similar rule applies to functions: if the body of a function computes a result which does not conform to the required type of the function result, it is not possible to catch this error within the function body itself; it can only be caught by the caller of the function. Similarly, if an expression used to compute an argument to a function returns a value of the wrong type for the function signature, this is not considered an error in this expression, but an error in evaluating the function call as a whole.
A consequence of these rules is that when a type error occurs while initializing a global variable (because the initializer returns a value of the wrong type, given the declared type of the variable), then this error cannot be caught.
Note:
Because processors are permitted to report type errors during
static analysis, it is unwise to attempt to recover from type
errors dynamically. The best strategy is generally to prevent their
occurrence. For example, rather than writing $p + 1
where $p
is a parameter of unknown type, and then
catching the type error that occurs if $p
is not
numeric, it is better first to test whether $p
is
numeric, perhaps by means of an expression such as $p
instance of my:numeric
, where my:numeric
is a
union type with xs:double
, xs:float
, and
xs:decimal
as its member types.
The fact that the application tries to catch errors does not
prevent the processor from organizing the evaluation in such a way
as to prevent errors occurring. For example exists(//a[10 div
. gt 5])
may still do an "early exit", rather than examining
every item in the sequence just to see if it triggers a
divide-by-zero error.
Except as specified above, the optimizer must not rearrange the evaluation (at compile time or at run time) so that expressions written to be subject to the try/catch are evaluated outside its scope, or expressions written to be external to the try/catch are evaluated within its scope. This does not prevent expressions being rearranged, but any expression that is so rearranged must carry its try/catch context with it.
Note:
If an error occurs while evaluating an instruction within
xsl:try
, then no
instruction within the xsl:try
has any effect on the
result returned by the xsl:try
instruction. This means
that if a processor is streaming the output to a serializer, it
needs to adopt a strategy such as buffering the output in memory so
that nothing is written until successful completion of the xsl:try
instruction, or
checkpointing the output so it can be rolled back when an error
occurs.
Note:
Use of try/catch may affect the ability of a processor to
perform streamed evaluation of a stylesheet. If the sequence
constructor contained within xsl:try
creates a sequence of ten
elements, and these form part of a final result tree, then if a
failure occurs while writing the tenth element, the work of
creating the previous nine must be "undone". In effect this means
that either the processor must delay sending the new elements to
the serializer until it is assured of success, or the serializer
must provide a mechanism to roll back elements already written.
The following example divides an employee's salary by the number of years they have served, catching the divide-by-zero error if the latter is zero.
<xsl:try select="salary div length-of-service"> <xsl:catch errors="err:FAOR0001" select="()"/> </xsl:try>
The following example generates a result tree and performs schema validation, outputting a warning message and serializing the invalid tree if validation fails.
<xsl:result-document href="out.xml"> <xsl:variable name="result"> <xsl:call-template name="construct-output"/> </xsl:variable> <xsl:try> <xsl:copy-of select="$result" validation="strict"/> <xsl:catch> <xsl:message>Warning: validation of result document failed: Error code: <xsl:value-of select="$err:code"/> Reason: <xsl:value-of select="$err:description"/> </xsl:message> <xsl:sequence select="$result"/> </xsl:catch> </xsl:try> </xsl:result-document>
The reason that the result tree is constructed in a variable in
this example is so that the unvalidated tree is available to be
used within the xsl:catch
element. An alternative approach would be to repeat the logic for
constructing the tree:
<xsl:try> <xsl:result-document href="out.xml" validation="strict"> <xsl:call-template name="construct-output"/> </xsl:result-document> <xsl:catch> <xsl:message>Warning: validation of result document failed: Error code: <xsl:value-of select="$err:code"/> Reason: <xsl:value-of select="$err:description"/> </xsl:message> <xsl:call-template name="construct-output"/> </xsl:catch> </xsl:try>
[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, a function parameter, or an
xsl:iterate
parameter. A parameter is a variable with the additional
property that its value can be set by the caller.]
[Definition: A variable is a binding between a name and a value. The value of a variable is any sequence (of nodes, atomic values, and/or function items), as defined in [Data Model].]
<!-- Category: declaration
-->
<!-- Category: instruction -->
<xsl:variable
name = eqname
select? = expression
as? = sequence-type
static? = "yes" | "no"
visibility? = "public" | "private" | "final" |
"abstract" >
<!-- 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 an EQName, 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 SequenceTypeXP30,
as defined in [XPath 3.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 XTTE0570] 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.
For the effect of the static
attribute, see
9.6 Static Variables and
Parameters.
The visibility
attribute must
not be specified for a local variable: that is, it is
allowed only when the parent element is
xsl:stylesheet
, xsl:transform
, or
xsl:override
.
If the visibility
attribute is present with the
value abstract
then the select
attribute
must be absent and the contained
sequence constructor must be empty. In this situation there is no
supplied value, and therefore the
constraint that the supplied value is consistent with the required
type does not apply.
<!-- Category: declaration
-->
<xsl:param
name = eqname
select? = expression
as? = sequence-type
required? = "yes" | "no"
tunnel? = "yes" | "no"
static? = "yes" | "no"
visibility? = "public" | "private" | "final" |
"abstract" >
<!-- 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
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
;
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
as a child of xsl:iterate
to define a
parameter that can vary from one iteration to the next.
The xsl:param
element
has a required name
attribute, which specifies the name of the parameter. The value of
the name
attribute is an EQName, which is
expanded as described in 5.1 Qualified
Names.
[ERR XTSE0580] It is a static error if the
values of the name
attribute of two sibling
xsl:param
elements
represent the same expanded QName.
Note:
For rules concerning stylesheet parameters, see 9.5 Global Variables and Parameters. Local variables may shadow template parameters and function parameters: see 9.9 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 whether the same
foo
element node will be used for each invocation.
However, it is permissible for the default value to 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 SequenceTypeXP30,
as defined in [XPath 3.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 XTTE0590] 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, or for parameters to xsl:iterate
, which are always
initialized to a default value. 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 XTTE0600] 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 a stylesheet parameter specifies required="yes"
and does not specify static="yes"
, then its visibility
must be public
, final
, or
abstract
. The default visibility of such a parameter
is public
.
[ERR XTSE3370] It is a static error if the the
visibility
attribute of a stylesheet parameter that
specifies required="yes"
and does not specify
static="yes"
is present with a value other than
public
, final
, or abstract
,
or if an xsl:expose
or
xsl:accept
declaration
attempts to modify the visibility of such a component to a value
other than public
, final
, or
abstract
.
Note:
This rule has the effect that after combining all the packages making up a stylesheet, the non-static stylesheet parameters whose values are required necessarily have distinct names, which simplifies the design of APIs.
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 XTDE0610] 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 dynamic error if the caller supplies
no value for the parameter.
For the effect of the static
attribute, see
9.6 Static Variables and
Parameters.
The visibility
attribute must
not be specified for a local parameter: that is, it is
allowed only when the parent element is
xsl:stylesheet
, xsl:transform
, or
xsl:override
.
If the visibility
attribute is present with the
value abstract
then the select
attribute
must be absent and the contained
sequence constructor must be empty. In this situation there is no
supplied value, and therefore the
constraint that the supplied value is consistent with the required
type does not apply.
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 a variable or the default value of a parameter in four different ways.
If the variable-binding element has a
select
attribute, then the value of the attribute
must be an expression and the supplied
value of the variable is the value that results from evaluating
the expression. In this case, the content of the variable-binding
element must be empty.
If the variable-binding element has
empty content and has neither a select
attribute nor
an as
attribute, then the supplied value of the
variable is a zero-length string. Thus
<xsl:variable name="x"/>
is equivalent to
<xsl:variable name="x" select="''"/>
If a variable-binding element has no
select
attribute and has non-empty content (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
is constructed with a document node having as its children the
sequence of nodes that results from evaluating the sequence
constructor and then applying the rules given in 5.8.1 Constructing Complex
Content. The value of the variable is then a singleton
sequence containing this document node. For further information,
see 9.4 Creating Implicit Document
Nodes.
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.8 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 document node whose content is obtained by evaluating the sequence constructor |
absent | present | present | Value is obtained by evaluating the
sequence constructor, adjusted to the type required by the
as attribute |
[ERR XTSE0620] 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 xs: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 a document node containing an empty element as a child:
<xsl:variable name="doc"><c/></xsl:variable>
The value of the following variable is a 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 a 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-sequence()"/>
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 values of all the td
elements,
space-separated (or with XSLT 1.0 behavior,
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 document node is created implicitly when evaluating an
xsl:variable
, xsl:param
, or xsl:with-param
element that
has non-empty content and that has no as
attribute.
The value of the variable is a single node, the document node of
a temporary tree. The content of the
document node is formed from the result of evaluating the sequence constructor contained
within the variable-binding element, as described in 5.8.1 Constructing Complex
Content.
Note:
The construct:
<xsl:variable name="tree"> <a/> </xsl:variable>
can be regarded as a shorthand for:
<xsl:variable name="tree" as="document-node()"> <xsl:document validation="preserve"> <a/> </xsl:document> </xsl:variable>
The base URI of the document node is taken from the base URI of the variable binding element in the stylesheet. (See Section 5.2 base-uri Accessor DM30 in [Data Model])
No document-level validation takes place (which means, for example, that there is no checking that ID values are unique). However, type annotations on nodes within the new tree are copied unchanged.
Note:
The base URI of other nodes in the tree is determined by the
rules for constructing complex content. The effect of these rules
is that 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. Thus,
the base URI of the document node will be equal to the base URI of
the variable-binding element, while 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.
The document-uri
and unparsed-entities
properties of the new document node are set to empty.
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
FO30
functions can be used to find nodes within a temporary tree,
by supplying the document node at the root of the tree as an
argument to the function or by making it the context
node.
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.6 Modes).
Typically, the template rules in module phase1.xsl
will be declared with mode="phase1"
, while those in
module phase2.xsl
will be declared with
mode="phase2"
:
<xsl:stylesheet version="3.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 different template rules are to be used when processing different trees, then unless nodes from different trees can 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 within its own declaration, and 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.
It is an error if no value is supplied for a mandatory stylesheet parameter [see ERR XTDE0050].
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 XTSE0630] It is a static error if a stylesheet contains more than one non-hidden 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 root node of the tree containing the initial context item. 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 item is supplied. The values of other components of the dynamic context are the initial values as defined in 5.4.3 Initializing the Dynamic Context and 5.4.4 Additional Dynamic Context Components used by XSLT.
The following example declares a global parameter
para-font-size
, which is referenced 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.
Static variables and parameters are global variables and can be
used in the same way as other global variables. In addition, they
can be used in [xsl:]use-when
expressions.
[Definition: A top-level variable-binding element having
the attribute static="yes"
declares a static
variable: that is, a global variable whose value is known
during static analysis of the stylesheet.]
[Definition: A static variable declared using an
xsl:param
element is
referred to as a static parameter.]
The static
attribute must
not be present on an xsl:variable
or xsl:param
element unless it is a
top-level element.
When the static
attribute is present with the value
yes
, the visibility
attribute
must not have a value other than
private
or final
.
Note:
This rule prevents static variables being overridden in another
package. Since the values of such variables may be used at compile
time (for example, during processing of [xsl:]use-when
expressions), the rule is necessary to ensure that packages can be
independently compiled.
Declaring a static variable or parameter with
visibility="final"
allows its value to be used in
ordinary (non-static) expressions in a using package, but use in
static expressions is possible only within the same package.
When the attribute static="yes"
is specified, the
xsl:variable
or
xsl:param
element
must have empty content. In the case of
xsl:variable
the
select
attribute must be present to define the value
of the variable.
If the select
attribute is present, then it is
evaluated using the rules for static expressions.
[Definition: A static expression is an XPath expression whose value must be computed during static analysis of the stylesheet.]
Static expressions appear in two contexts:
In [xsl:]use-when
attributes (see 3.14 Conditional Element
Inclusion)
In the select
attribute of static
variable declarations (xsl:variable
or xsl:param
with
static="yes"
).
There are no syntactic constraints on the XPath expression that can be used as a static expression. However, there are severe constraints on the information provided in its evaluation context. These constraints are designed to ensure that the expression can be evaluated at the earliest possible stage of stylesheet processing, without any dependency on information contained in the stylesheet itself or in any source document.
Specifically, the components of the static and dynamic context are defined by the following two tables:
Component | Value |
---|---|
XPath 1.0 compatibility mode | false |
Statically known namespaces | determined by the in-scope namespaces for the containing element in the stylesheet |
Default element/type namespace | determined by the
xpath-default-namespace attribute if present (see
5.2 Unprefixed Lexical QNames in
Expressions and Patterns); otherwise the null
namespace |
Default function namespace | The standard function namespace |
In-scope schema types | The type definitions that would be
available in the absence of any xsl:import-schema
declaration |
In-scope element declarations | None |
In-scope attribute declarations | None |
In-scope variables | The static variables visible
within the containing package whose declarations occur prior to the
element containing the static expression in stylesheet tree order.
Stylesheet tree order is the order that results when all xsl:import and xsl:include declarations are
replaced by the declarations in the imported or included stylesheet
module. A static variable is not in scope within its own
declaration, and it is in scope only within its declaring
package, not in any using packages. If two static variables
satisfying this rule have the same name and are both in scope, the
one that has highest import precedence is used (it is a
consequence of rules defined elsewhere that there cannot be more
than one declaration with highest import precedence). Note that the
declaration with highest import precedence is not necessarily the
one that appears last in stylesheet tree order; note also that
because forwards references are not allowed, the declaration that
is used will not necessarily be the one with highest import
precedence in the stylesheet as a whole. |
Context item static type | Absent |
Statically known function signatures | The core functions defined in
[Functions and Operators],
together with the functions element-available ,
function-available ,
type-available , and
system-property
defined in this specification, plus the set of extension functions
that are present in the static context of every XPath expression
(other than a use-when expression) within the content of the
element that is the parent of the use-when attribute.
Note that stylesheet functions are not
included in the context, which means that the function function-available will
return false in respect of such functions. The effect
of this rule is to ensure that function-available
returns true in respect of functions that can be called within the
scope of the use-when attribute. It also has the
effect that these extension functions will be recognized within the
use-when attribute itself; however, the fact that a
function is available in this sense gives no guarantee that a call
on the function will succeed. |
Statically known collations | Implementation-defined |
Default collation | The Unicode Codepoint Collation |
Static Base URI | The base URI of the containing element in the stylesheet document (see Section 5.2 base-uri Accessor DM30) |
Statically known documents | Implementation-defined |
Statically known collections | Implementation-defined |
Statically known default collection type | Implementation-defined |
Statically known decimal formats | A single unnamed decimal
format equivalent to the decimal format that is created by an
xsl:decimal-format
declaration with no attributes. |
Component | Value |
---|---|
Context item, position, and size | Absent |
Variable values | A value for every variable present in the in-scope variables. For static parameters where an external value is supplied: the externally-supplied value of the parameter. In all other cases: the value of the variable as defined in 9.3 Values of Variables and Parameters. |
Named functions | The function implementation corresponding to each function signature in the statically known function signatures |
Current dateTime | Implementation-defined |
Implicit timezone | Implementation-defined |
Default language | Implementation-defined |
Default calendar | Implementation-defined |
Default place | Implementation-defined |
Available documents | Implementation-defined |
Available collections | Implementation-defined |
Default collection | Implementation-defined |
Environment variables | Implementation-defined |
Within a stylesheet module, all static
expressions are evaluated in a single execution
scopeFO30. This need not be the same
execution scope as that used for static expressions in other
stylesheet modules, or as that used when evaluating XPath
expressions appearing elsewhere in the stylesheet module. This
means that a function such as current-date
FO30
will return the same result when called in different
[xsl:]use-when
expressions within the same stylesheet
module, but will not necessarily return the same result as the same
call in an [xsl:]use-when
expression within a
different stylesheet module, or as a call on the same function
executed during the transformation proper.
[Definition: As well as being allowed as a declaration, the xsl:variable
element is also
allowed in sequence constructors. Such a
variable is known as a local variable.]
An xsl:param
element
may also be used to create a variable binding with local scope:
[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.]
An xsl:param
element
may appear as a child of an xsl:iterate
instruction, before
any non-xsl:param
children of that element. This defines a parameter whose value may
be initialized on entry to the iteration, and which may be varied
each time round the iteration by use of an xsl:with-param
element in
the xsl:next-iteration
instruction.
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 (more specifically, a set of nodes) 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, with the following exceptions:
It is not visible in any region where it is shadowed by another variable binding.
It is not visible within the subtree rooted at an xsl:fallback
instruction that
is a sibling of the variable binding element.
It is not visible within the subtree rooted at an xsl:catch
instruction that is a
sibling of the variable binding element.
The binding is not visible for the xsl:variable
or xsl:param
element itself.
If a binding is visible for an element then it is visible for every attribute of that element and for every text node child of that element.
[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
element
shadows a
binding established by another local xsl:variable
or xsl:param
.
The following is not an error, but 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:variable name="x" select="1"/> <xsl:template name="foo"> <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 3.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.
<xsl:with-param
name = eqname
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 an EQName, which is
expanded as described in 5.1 Qualified
Names.
The xsl:with-param
element is
also used when passing parameters to an iteration of the xsl:iterate
instruction, or to
a dynamic invocation of an XPath expression using xsl:evaluate
. In
consequence, xsl:with-param
may appear
within xsl:apply-templates
,
xsl:apply-imports
,
xsl:call-template
,
xsl:evaluate
,
xsl:next-iteration
,
and xsl:next-match
.
(Arguments to stylesheet functions, however, are
supplied as part of an XPath function call: see 10.3 Stylesheet Functions.)
[ERR XTSE0670] It is a static error if two or
more sibling xsl:with-param
elements have
name
attributes that represent the same expanded
QName.
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.
In this situation, the supplied value of the parameter will
first be processed according to the rules of the as
attribute on the xsl:with-param
element, and
the resulting value will then be further processed according to the
rules of the as
attribute on the xsl:param
element.
For example, suppose the supplied value is a node with type
annotation xs:untypedAtomic
, and the xsl:with-param
element
specifies as="xs:integer"
, while the xsl:param
element specifies
as="xs:double"
. Then the node will first be atomized
and the resulting untyped atomic value will be cast to
xs:integer
. If this succeeds, the
xs:integer
will then be promoted to an
xs:double
.
The focus
used for computing the value specified by the xsl:with-param
element is
the same as that used for its parent instruction.
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. They
are used only when passing parameters to templates: for an xsl:with-param
element that
is a child of xsl:evaluate
or xsl:next-iteration
the
tunnel
attribute must either
be omitted or take the value no
.
In other cases it is a 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. [see
ERR XTDE0700]
[Definition: A circularity is said to exist if a construct such as a global variable, an attribute set, or a key, is defined in terms of itself. For example, 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. A circularity exists if it is impossible to do this for all global variable definitions.]
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 XTDE0640] In general, a circularity in a stylesheet is a 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 20.2
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 = eqname >
<!-- 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 an EQName, 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
and
visibility
attributes on an xsl:template
element have no
effect when the template is invoked by an xsl:apply-templates
instruction.
[ERR XTSE0650] 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 named template
visible in the containing package (this includes any template defined in
this package, as well as templates accepted from used packages
whose visibility in this package is not hidden
). For
more details of the process of binding the called template, see
3.6.2.6 Binding References to
Components.
[ERR XTSE0660] It is a static error if a package contains more than one non-hidden template with the same name and the same import precedence, unless it also contains a template with the same name and higher import precedence.
[ERR XTSE3340] It is a static error if an
xsl:template
declaration has the name xsl:initial-template
and
contains an xsl:param
that specifies required="yes"
.
The target template for an xsl:call-template
instruction is established using the binding rules described in
3.6.2.6 Binding References to
Components. This will always be a template whose
name
attribute matches the name
attribute
of the xsl:call-template
instruction. It may be a template defined in the same package that
has higher import precedence than any other
template with this name, or it may be a template accepted from a
used package, or (if the template is not defined as
private
or final
) it may be an overriding
template in a package that uses the containing package. 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.8 Sequence Constructors).
The template name xsl:initial-template
is specially
recognized in that it provides a default entry point for stylesheet
execution (see 2.3 Initiating a
Transformation.) A template with this name must not have any xsl:param
children that specify
required="yes"
. In all other respects a template with
this name behaves exactly like a template with any other name.
Parameters are passed to named templates using the xsl:with-param
element as a
child of the xsl:call-template
instruction.
[ERR XTSE0680] In the case of xsl:call-template
, it is
a static error to pass a non-tunnel parameter
named x to a template that does not have a
non-tunnel template parameter
named x, unless the xsl:call-template
instruction is processed with XSLT 1.0 behavior.
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 XTSE0690] 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 xsl:call-template
instruction.
This example defines a named template for a
numbered-block
with a parameter 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>
[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 a 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.8 Built-in Template Rules).
If a tunnel parameter is declared in an xsl:param
element with the
attribute tunnel="yes"
, then a dynamic error occurs
[see ERR
XTDE0700] if the set of tunnel parameters passed to the
template does not include a parameter with a matching expanded
QName.
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="{$equation-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 = eqname
use-attribute-sets? = eqnames
visibility? = "public" | "private" | "final" |
"abstract"
streamable? = "yes" | "no" >
<!-- Content: xsl:attribute* -->
</xsl:attribute-set>
Attribute sets generate named collections of
attributes that can be used repeatedly on different constructed
elements. The xsl:attribute-set
declaration is used to declare attribute sets. The required name
attribute specifies the
name of the attribute set. The value of the name
attribute is an EQName
, which is expanded as described
in 5.1 Qualified Names.
[Definition: An attribute set is defined as a set of
xsl:attribute-set
declarations in the same package that share the same expanded
QName.]
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.
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 an EQName, 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 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.8 Sequence Constructors) to
produce a sequence of attribute nodes. These attribute nodes are
appended to the result sequence.
[ERR XTSE0710] 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
whitespace-separated sequence of EQNames, or if it contains a
QName that does not match the name
attribute of any
xsl:attribute-set
declaration in the stylesheet.
[ERR XTSE0720] 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.
The visibility
attribute determines the potential
visibility of the attribute set in packages other than the
containing package. If the visibility
attribute is
present on any of the xsl:attribute-set
declarations making up the definition of an attribute
set (that is, all declarations within the same package sharing
the same name), then it must be present,
with the same value, on every xsl:attribute-set
declaration making up the definition of that attribute
set.
If the visibility
attribute is present with the
value abstract
then there must be no xsl:attribute
children
and no use-attribute-sets
attribute.
An attribute set may be designated as
streamable by including the attribute streamable="yes"
on each xsl:attribute-set
declaration making up the attribute set. If any xsl:attribute-set
declaration for an attribute set has the attribute
streamable="yes"
, then every xsl:attribute-set
declaration for that attribute set must
have the attribute streamable="yes"
.
An attribute set is guaranteed-streamable if every
xsl:attribute-set
declaration making up the attribute set, considered as a sequence constructor, is motionless
according to the analysis in 19.8.5 Classifying Attribute
Sets.
Specifying streamable="yes"
on an xsl:attribute-set
element
declares an intent that the attribute set should be guaranteed
streamable according to these criteria. The consequences of
declaring the attribute set to be streamable when it is not in fact
guaranteed streamable depend on the conformance level of the
processor, and are explained in 19.10 Streamability
Guarantees.
Note:
It is common for attribute sets to create attributes with
constant values, and such attribute sets will always be motionless
and therefore streamable. Although such cases are fairly simple for
a processor to detect, references to attribute sets are not
guaranteed streamable unless the attribute set is declared with the
attribute streamable="yes"
, which should therefore be
used if interoperable streaming is required.
Attribute sets are evaluated 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 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
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.9 Copying
Nodes.
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.
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.
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 = eqname
as? = sequence-type
visibility? = "public" | "private" | "final" |
"abstract"
override-extension-function? = "yes" | "no"
[override]? = "yes" |
"no"
identity-sensitive? = "yes" | "no"
cache? = "full" | "partial" | "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 an EQName, 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.
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.
The name of the function is given by the name
attribute; the arguments are defined by child xsl:param
elements; and the
return type is defined by the as
attribute. Together
these definitions constitute the function signature.
[ERR XTSE0740] It is a static error if a stylesheet function has a name that is in no 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 name of the function must not be in a reserved namespace: [see ERR XTSE0080]
[Definition: The arity of a
stylesheet function is the number of xsl:param
elements in the
function definition.] Optional
arguments are not allowed.
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.
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 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.
[ERR XTSE0760] 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.
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 3.0]. The rules that apply are those
for the case where XPath 1.0 compatibility
mode is set to false
.
[ERR XTTE0790] If the value of a parameter to a stylesheet function cannot be converted to the required type, a type error is signaled.
If the as
attribute is omitted, no conversion takes
place and any value is accepted.
The result of the function is the result of evaluating the contained sequence constructor.
Within the sequence constructor, the focus is initially absent; this means that any attempt to reference the context item, context position, or context size is a dynamic error. [ERR XPDY0002] XP30
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 optional as
attribute indicates the required
type of the result of the function. The value of the
as
attribute is a SequenceTypeXP30,
as defined in [XPath 3.0].
[ERR XTTE0780] If the as
attribute
is specified, then the result evaluated by the sequence constructor (see 5.8 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 the visibility
attribute is present with the
value abstract
then the sequence constructor defining the
function body must be empty.
A stylesheet function is included in the in-scope functions of the static context for all XPath expressions used in the containing package, unless
there is another stylesheet function with the same name and arity, and higher import precedence, or
the override-extension-function
or
override
attribute has the value no
and
there is already a function with the same name and arity in the in-scope
functions.
The visibility of the function in other packages
depends on the value of the visibility
attribute and
other factors, as described in 3.6
Packages
The optional
override-extension-function
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-extension-function
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-extension-function="yes"
ensures
interoperable behavior: the same code will execute with all
processors. Specifying
override-extension-function="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 (or a user's implementation
written as an extension function) to be used in preference to the
stylesheet implementation, which is useful when the extension
function is more efficient.
The override-extension-function
attribute does
not affect the rules for deciding which of several
stylesheet functions with the same
name and arity takes precedence.
The override
attribute is a deprecated synonym of
override-extension-function
, retained for
compatibility with XSLT 2.0. If both attributes are present then
they must have the same value.
[ERR XTSE0770] It is a static error for a package to contain two or more non-hidden 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.
When the xsl:function
declaration
appears as a child of xsl:override
, there
must be a stylesheet function with the
same expanded QName and arity in the package referenced by the
containing xsl:use-package
element;
the visibility of that function must be
public
or abstract
, and the overriding
and overridden functions must have the
same argument types and result type.
If a stylesheet function with a particular
expanded QName and arity exists in the stylesheet, then
a call to the
function-lookup
FO30 function
supplying that name and arity will return the function as a value.
This applies only if the static context for the call on
function-lookup
FO30 includes
the stylesheet function, which implies that the function is visible
in the containing package.
The function-available
function, when called with a particular expanded QName and
arity,
returns true if and only if a call on
function-lookup
FO30 with the
same arguments, in the same static context, would return a function
item.
Note:
For legacy reasons there is also a single-argument version of
function-available
,
which returns true if there is a function with the given name
regardless of arity.
The standard rules for
function-lookup
FO30 require
that if the supplied name and arity identify a context-dependent
function such as name#0
FO30
or lang#1
FO30
(call it F), then the returned function value includes
in its closure a copy of the static and dynamic context of the call
to
function-lookup
FO30, and the
context item for a subsequent dynamic call of F is taken
from this saved context. In the case where the context item is a
node in a streamed input document, saving the node is not possible.
In this case, therefore, the context is saved with an absent focus,
so the call on F will fail with a dynamic error saying
that there is no context item available.
Stylesheet functions have been designed to be largely deterministic: unless a stylesheet function calls some extension function which is itself non-deterministic, the function will return results that depend only on the supplied arguments. This property (coupled with the fact that the effect of calling extension functions is entirely implementation-dependent) enables a processor to implement various optimizations, such as removing invariant function calls from the body of a loop, or combining common sub-expressions,.
One exception to the intrinsic determinism of stylesheet
functions arises because constructed nodes have distinct identity.
This means that when a function that creates a new node is called,
two calls on the function will return nodes that can be
distinguished: for example, with such a function,
f:make-node() is f:make-node()
will return false. This
property of functions is called identity-sensitivity. If a
processor cannot determine by static analysis that the function is
not identity-sensitive, then it cannot perform optimizations that
would observably change this behavior.
To allow processors greater freedom to optimize calls on
stylesheet functions, the attribute
identity-sensitive="no"
may be specified (the default
is yes
). When the value no
is specified,
the stylesheet author is asserting that for any node passed in the
value of an argument to the function, and for any node returned as
a result, the stylesheet as a whole will give acceptable results if
the node is replaced by a different node that is deep-equal to the
original.
Note:
Note the term "acceptable". The result of the transformation may be different, but not in a way that the stylesheet author cares about.
Declaring a function with identity-sensitive="no"
might allow a call to the function to be moved out of a loop, so
the function is only called once before entry to the loop rather
than being called repeatedly within the loop. If the arguments to
the function depend only on global variables then it might enable
the function call to be moved into a global variable. It might also
enable some caching or memoization at the processor's
discretion.
Declaring a function with identity-sensitive="no"
might also allow nodes from a streamed input document to be passed
to the function, since the function is licensed to operate on a
deep copy of the node. However, the streamability analysis in this
specification does not take account of this possibility.
The cache
attribute is an optimization hint which
the processor can use or ignore at its discretion; however it
should be taken seriously, because it may make a difference to
whether execution of a stylesheet is practically feasible or
not.
The default value is cache="no".
The value cache="full"
encourages the processor to
retain memory of all previous calls of this function during the
same transformation and to reuse results from this memory whenever
possible. The value cache="partial"
encourages the
processor to retain such memory but to discard results if necessary
to keep the amount of memory used within bounds. The default value
cache="no"
encourages the processor not to retain
memory of previous calls.
In all cases the results must respect the semantics; for example
if an attribute node is supplied as the value of an argument, then
its identity must be assumed to be significant unless (a)
identity-sensitive="no"
is specified, or (b) the
processor is able to determine by static analysis that the identity
of the attribute node makes no difference to the result (for
example, because all references to the argument are atomizing
references).
Note:
Memoization using the cache
attribute may be more
effective if the attribute identity-sensitive="no"
is
also used, as this gives a processor more scope for optimization.
In particular, specifying cache="full"
by itself does
not remove the obligation of a processor to return distinct nodes
on each call of a function, whereas combining this with
identity-sensitive="no"
does remove this
obligation.
The following example creates a recursive 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="3.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>
XPath 3.0 introduces the ability to pass function items as argument to a function. A function that takes function items as arguments is known as a higher-order function.
The following example is a higher-order function that operates on any tree-structured data, for example an organization chart. Given as input a function that finds the direct subordinates of a node in this tree structure (for example, the direct reports of a manager, or the geographical subdivisions of an administrative area), it determines whether one object is present in the subtree rooted at another object (for example, whether one person is among the staff managed directly or indirectly by a manager, or whether one parcel of land is contained directly or indirectly within another parcel. The function does not check for cycles in the data.
<xsl:function name="f:is-subordinate" as="xs:boolean"> <xsl:param name="superior" as="node()"/> <xsl:param name="subordinate" as="node()"/> <xsl:param name="get-direct-children" as="function(node()) as node()*"/> <xsl:sequence select=" some $sub in $get-direct-children($superior) satisfies ($sub is $subordinate or f:is-subordinate($sub, $subordinate, $get-direct-children))"/> </xsl:function>
Given source data representing an organization chart in the form of elements such as:
<employee id="P57832" manager="P68951"/>
the following function can be defined to get the direct reports of a manager:
<xsl:function name="f:direct-reports" as="element(employee)*"> <xsl:param name="manager" as="element(employee)"/> <xsl:sequence select="$manager/../employee [@manager = $manager/@id]"/> </xsl:function>
It is then possible to test whether one employee $E
reports directly or indirectly to another employee $M
by means of the function call:
f:is-subordinate($M, $E, f:direct-reports#1)
<!-- Category: instruction
-->
<xsl:evaluate
xpath = expression
as? = sequence-type
base-uri? = { uri }
with-params? = expression
context-item? = expression
namespace-context? = expression
schema-aware? = { "yes" | "no" } >
<!-- Content: (xsl:with-param | xsl:fallback)* -->
</xsl:evaluate>
The xsl:evaluate
instruction constructs an XPath expression in the form of a string,
evaluates the expression in a specified context, and returns the
result of the evaluation.
The expression given as the value of the xpath
attribute is evaluated and the result is converted to a string
using the function conversion
rules.
[Definition: The string that results from evaluating the
expression in the xpath
attribute is referred to as
the target expression.]
[ERR XTDE3160] It is a dynamic error if the target expression is not a valid XPath 3.0 expression (that is, if a static error occurs when analyzing the string according to the rules of the XPath 3.0 specification).
The as
attribute, if present, indicates the
required type of the result. If the attribute is absent, the
required type is item()*
, which allows any result. The
result of evaluating the target expression is
converted to the required type using the function conversion rules. This
may cause a type error if conversion is not possible. The
result after conversion is returned as the result of the xsl:evaluate
instruction.
The target expression may contain variable references; the
values of such variables may be supplied using an xsl:with-param
child
instruction if the names of the variables are known statically, or
using a map supplied as the value of the expression in the
with-params
attribute if the names are only known
dynamically. If the with-params
attribute is present
then it must contain an expression whose value, when evaluated, is
of type map(xs:QName, item()*)
(see 21.1 Maps for details of maps).
The static contextXP30 for the target expression is as follows:
XPath 1.0 compatibility mode is false
.
Statically known namespaces and default element/type namespace:
if the namespace-context
attribute is present, then
its value is an expression whose required type is a single
node. The expression is evaluated, and the in-scope namespaces of
the resulting node are used as the statically known namespaces for
the target expression. The binding for the default namespace in the
in-scope namespaces is used as the default namespace for elements
and types in the target expression.
[ERR XTTE3170] It is a type error if the result
of evaluating the namespace-context
attribute of the
xsl:evaluate
instruction is anything other than a single node.
if the namespace-context
attribute is absent, then
the in-scope namespaces of the xsl:evaluate
instruction (with
the exception of any binding for the default namespace) are used as
the statically known namespaces for the target expression, and the
value of the innermost [xsl:]xpath-default-namespace
attribute, if any, is used as the default namespace for elements
and types in the target expression.
Note:
XPath 3.0 allows expanded names to be written in a
context-independent way using the syntax
Q{namespace-uri}local-name
Default function namespace: the standard function namespace.
In-scope schema definitions: if the schema-aware
attribute is present and has the effective value
yes
, then the in-scope schema definitions from the
stylesheet context (that is, the schema definitions imported using
xsl:import-schema
).
Otherwise, the built-in types (see 3.15 Built-in Types).
In-scope variables: the names of the in-scope variables are the
union of the names appearing in the name
attribute of
the contained xsl:with-param
elements, and
the names present as keys in the map obtained by evaluating the
with-params
attribute, if present. The corresponding
type is item()*
in the case of a name found as a key
in the with-params
map, or the type named in the
as
attribute of xsl:with-param
child
(defaulting to item()*
) otherwise.
Note:
Variables declared in the stylesheet in xsl:variable
or xsl:param
elements are
not in-scope within the target expression.
If variable names are present in both the static xsl:with-param
children and
also in the dynamic with-params
map, the value from
the latter takes precedence.
Function signatures: All core functions; constructor
functions for named simple types included in the
in-scope schema definitions; all user-defined functions and
accumulator functions present in the containing package provided
their visibility is not hidden
or
private
; and an implementation-defined set of
extension functions.
Note that this set deliberately excludes XSLT-defined functions
in the standard function namespace
including for example, key
,
current-group
, and
system-property
A
list of these functions is in G List of XSLT-defined
functions.
Statically known collations: the same as the collations available at this point in the stylesheet.
Default collation: the same as the default collation defined at
this point in the stylesheet (for example, by use of the
[xsl:]default-collation
attribute)
Base URI: if the base-uri
attribute is present,
then its effective value; otherwise, the base URI
of the xsl:evaluate
instruction.
Statically known documents: the empty set
Statically known collections: the empty set
Statically known default collection type:
node()*
The dynamic context for evaluation of the target expression is as follows:
The context item, position, and size depend on the result of
evaluating the expression in the context-item
attribute. If this attribute is absent, or if the result is an
empty sequence, then the context item, position, and size for
evaluation of the target expression are all absent. If the result of
evaluating the context-item
expression is a single
item, then the target expression is evaluated with a singleton focus based on this item.
[ERR XTTE3210] If the result of evaluating the
context-item
expression is a sequence containing more
than one item, then a type error is signaled.
The variable values consists of the values bound to
parameters defined either in the contained xsl:with-param
elements,
which are evaluated as described in 9.3 Values of Variables and
Parameters, or in the map that results from evaluation of
the expression in the with-params
attribute; if the
same QName is bound in both, the value in the
with-params
map takes precedence.
The XSLT-specific aspects of the dynamic context described in 5.4.4 Additional Dynamic Context Components used by XSLT are all absent.
All other aspects of the dynamic context are the same as the
dynamic context for the xsl:evaluate
instruction
itself.
xsl:evaluate
instructionThe XPath expression is evaluated in the same execution
scopeFO30 as the calling XSLT
transformation; this means that the results of deterministicFO30
functions such as doc
FO30
or
current-dateTime
FO30 will be
consistent between the calling stylesheet and the called XPath
expression.
It is a dynamic error if evaluation of the XPath expression fails with a dynamic error. The XPath-defined error code is used unchanged.
Note:
Implementations wanting to avoid the cost of repeated compilation of the same XPath expression should cache the compiled form internally.
Stylesheet authors need to be aware of the security risks
associated with the use of xsl:evaluate
. The instruction
should not be used to execute code from an untrusted source. To
avoid the risk of code injection, user-supplied data should never
be inserted into the expression using string concatenation, but
should always be referenced by use of parameters.
xsl:evaluate
as
an optional featureThe xsl:evaluate
instruction is newly introduced in XSLT 3.0. It is part of the
dynamic evaluation feature, which is an optional feature of the
specification (see 26.6
Dynamic Evaluation Feature). An XSLT 3.0 processor
may disable the feature, or allow users
to disable the feature. The processor may
be able to determine during static analysis whether or not the
feature is available, or it may only be
able to determine this during dynamic evaluation. In the first case
we refer to the feature being statically disabled, in the
second case to it being dynamically disabled.
If the feature is statically disabled, then:
A call to element-available('xsl:evaluate')
returns
false, wherever it appears;
A call to
system-property('xsl:supports-dynamic-evaluation')
returns "no", wherever it appears;
If an xsl:evaluate
instruction has an xsl:fallback
child, fallback
processing takes place;
No static error is raised if an xsl:evaluate
instruction is
present in the stylesheet (an error occurs only if it is actually
evaluated).
If the feature is dynamically disabled, then:
A call to element-available('xsl:evaluate')
appearing in a static expression (for example, in an
[xsl:]use-when
attribute) returns true;
A call to element-available('xsl:evaluate')
appearing anywhere else returns false;
A call to
system-property('xsl:supports-dynamic-evaluation')
appearing in a static expression (for example, in an
[xsl:]use-when
attribute) returns "yes";
A call to
system-property('xsl:supports-dynamic-evaluation')
appearing anywhere else returns "no";
If an xsl:evaluate
instruction has an xsl:fallback
child, fallback
processing takes place;
In the absence of an xsl:fallback
child, a dynamic
error is raised if an xsl:evaluate
instruction is
evaluated. The dynamic error may be caught using xsl:try
and xsl:catch
.
[ERR XTDE3175] It is a dynamic error if an
xsl:evaluate
instruction is evaluated when use of xsl:evaluate
has been
statically or dynamically disabled.
In consequence of these rules, the recommended approach for
stylesheet authors to write code that works whether or not xsl:evaluate
is enabled is to
use an xsl:fallback
child instruction. For example:
<xsl:variable name="isValid" as="xs:boolean"> <xsl:evaluate xpath="$validityCondition"> <xsl:fallback><xsl:sequence select="true()"/></xsl:fallback> </xsl:evaluate> </xsl:variable>
Note:
There may be circumstances where it is inappropriate to allow
use of xsl:evaluate
.
For example:
There may be security risks associated with the ability to execute code from an untrusted source, which cannot be inspected during static analysis.
There may be environments where the the available computing resources are sufficient to enable pre-compiled stylesheets to be executed, but not to enable XPath expressions to be compiled into executable code.
Processors that implement xsl:evaluate
should provide
mechanisms allowing calls on xsl:evaluate
to be disabled.
Implementations may disable the feature by default, and they may
disable it unconditionally.
xsl:evaluate
A common requirement is to sort a table on the value of an expression which is selected at run-time, perhaps by supplying the expression as a string-valued parameter to the stylesheet. Suppose that such an expression is supplied to the parameter:
<xsl:param name="sortkey" as="xs:string" select="'@name'"/>
Then the data may be sorted as follows:
<xsl:sort> <xsl:evaluate xpath="$sortkey" as="xs:string" context-item="."/> </xsl:sort>
Note the importance in this use case of caching the compiled expression, since it is evaluated repeatedly, once for each item in the list being sorted.
The
function-lookup
FO30 function,
if it were not available in the standard library, could be
implemented like this:
<xsl:function name="f:function-lookup"> <xsl:param name="name" as="xs:QName"/> <xsl:param name="arity" as="xs:integer"/> <xsl:evaluate xpath="'Q{' || namespace-uri-from-QName($name) || '}' || local-name-from-QName($name) || '#' || $arity"> <xsl:with-param name="name" as="xs:QName" select="$name"/> <xsl:with-param name="arity" as="xs:integer" select="$arity"/> </xsl:evaluate> </xsl:function>
The xsl:evaluate
instruction uses the supplied QName and arity to construct an
expression of the form Q{namespace-uri}local#arity
,
which is then evaluated to return a function item representing the
requested function.
This section describes instructions that directly create new nodes, or sequences of nodes, atomic values, and/or function items.
[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 23.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 (that is, the same namespace URI, local name, and namespace prefix). 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.8 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.8.1 Constructing Complex Content
The base URI of the new element is copied from the base URI of
the literal result element in the stylesheet, unless the content of
the new element includes an xml:base
attribute, in
which case the base URI of the new element is the value of that
attribute, resolved (if it is a relative URI
reference) against the base URI of the literal result
element in the stylesheet. (Note, however, that this is only
relevant when creating a parentless element. When the literal
result element is copied to form a child of an element or document
node, the base URI of the new copy is taken from that of its new
parent.)
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 value of the xsl:validation
attribute, if
present, must be one of the values strict
,
lax
, preserve
, or strip
. The
value of the xsl:type
attribute, if present, must be
an EQName identifying a type definition that
is present in the in-scope schema
components for the stylesheet. Neither attribute may be
specified as an attribute value template.
The effect of these attributes is described in 24.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.8.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
, xsl:copy
, or xsl:copy-of
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.8.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.
Although the above rules place namespace nodes before attributes, this is not strictly necessary, because the rules in 5.8.1 Constructing Complex Content allow the namespaces and attributes to appear in any order so long as both come before other kinds of node. The order of namespace nodes and attribute nodes in the sequence has no effect on the relative position of the nodes in document order once they are added to a tree.
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
expanded QName (that is, the same
namespace URI, local name, and namespace prefix) 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 xs: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 xs: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
xs:untypedAtomic
.
If the name of a constructed attribute is xml:id
,
the processor must perform attribute value normalization by
effectively applying the
normalize-space
FO30 function
to the value of the attribute, and the resulting attribute node
must be given the is-id
property.
Note:
If the attribute name is xml:space
, it is
not an error when the value is something other than
default
or preserve
. Although the XML
specification states that other values are erroneous, a document
containing such values is well-formed; if erroneous values are to
be rejected, schema validation should be used.
Note:
The xml:base
, xml:lang
,
xml:space
, and xml:id
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 it is
inadvisable to write these attributes as attribute value templates:
although an XSLT processor will understand this notation, the XML
parser will not. See also 11.1.5
Namespace Aliasing which describes how to use xsl:namespace-alias
with these attributes.
The same is true of the schema-defined attributes
xsi:type
, xsi:nil
,
xsi:noNamespaceSchemaLocation
, and
xsi:schemaLocation
. If the stylesheet is processed by
a schema processor, these attributes will be recognized and
interpreted by the schema processor, but in addition the XSLT
processor treats them like any other attribute on a literal result
element: that is, their effective value (after expanding
attribute value templates) is
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 XTSE0805] 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.
Note:
If there is a need to create attributes in the XSLT namespace,
this can be achieved using xsl:attribute
, or by means of
the xsl:namespace-alias
declaration.
The created element node will 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.5 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 23.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.
[ERR XTSE0808] It is a static error if a
namespace prefix is used within the
[xsl:]exclude-result-prefixes
attribute and there is
no namespace binding in scope for that prefix.
The default namespace of the parent element of the
[xsl:]exclude-result-prefixes
attribute (see Section 6.2
Element Nodes DM30) may be designated
as an excluded namespace by including #default
in the
list of namespace prefixes.
[ERR XTSE0809] It is a static error if the
value #default
is used within the
[xsl:]exclude-result-prefixes
attribute and the parent
element of the [xsl:]exclude-result-prefixes
attribute
has no default namespace.
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.8.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 a source tree, specifying the prefix in
the [xsl:]exclude-result-prefixes
attribute will avoid
superfluous namespace declarations in the serialized 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 serialized result tree.
For example, consider the following stylesheet:
<xsl:stylesheet 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"
(the processor may choose
a different namespace prefix if this is necessary to avoid
conflicts). 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.8.3 Namespace Fixup) to introduce a
namespace node for this namespace.
A literal result element may have an optional
xsl:inherit-namespaces
attribute, with the value
yes
or no
. The default value is
yes
. If the value is set to yes
, or is
omitted, then the namespace nodes created for the newly constructed
element are copied to the children and descendants of the newly
constructed element, as described in 5.8.1 Constructing Complex
Content. If the value is set to no
, then these
namespace nodes are not automatically copied to the children. This
may result in namespace undeclarations (such as
xmlns=""
or, in the case of XML 1.1,
xmlns:p=""
) appearing on the child elements when a
final result tree is serialized.
If a literal result element has an xsl:on-empty
attribute, then the value of the attribute must be an XPath expression. If the attribute is
present and the constructed element has no attributes and no
children, then instead of returning the constructed element,
the instruction returns the result of evaluating the expression in
the xsl:on-empty
attribute; if this expression
returns a node, the instruction returns a copy of this
node.
[ERR XTTE3300] It is a type error if the result
of evaluating the xsl:on-empty
attribute does not
satisfy the required type element()?
. That is, the
expression must deliver either a single element node, or an empty
sequence.
If the xsl:on-empty
expression is evaluated and
returns an empty sequence, then the xsl:validation
and
xsl:type
attributes are ignored. However, if the
result of the xsl:on-empty
expression is an element,
then it is subjected to validation as determined by these
attributes, along with [xsl:]default-validation
where
relevant.
Note that when a literal result element has one or more
attributes (other than attributes in the XSLT namespace), or when
it references a non-empty attribute set, the on-empty
attribute has no effect because these conditions will not be
satisfied.
The following example generates an events
element
if and only if there are one or more event
elements.
The code could be written like this:
<xsl:if test="exists(event)"> <events> <xsl:copy-of select="event"/> </events> </xsl:if>
However, the above code would not be guaranteed streamable. To make it streamable, it can be rewritten as:
<events xsl:on-empty="()"> <xsl:copy-of select="event"/> </events>
Note:
The reason for introducing the on-empty
attribute
is primarily to make it easier to write applications that conform
to the rules for guaranteed streamability. A common requirement is
to generate a wrapper element for a sequence of elements (for
example an events
wrapper for a sequence of
event
elements) only if the content sequence is
non-empty. Without the xsl:on-empty
attribute this is
difficult to achieve, because testing whether any
event
element exists and processing the set of
event
elements both count as consuming
instructions.
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.]
Either of the literal namespace URI or the target namespace URI can be null: this is treated as a reference to the set of names that are in no namespace.
<!-- 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 effect of an xsl:namespace-alias
declaration is local to the package in which it appears: that is, it
only affects the result of literal result
elements within the same package.
Where namespace aliasing changes the namespace URI part of the
expanded QName containing the name of an
element or attribute node, the namespace prefix in that expanded
QName is replaced by the prefix indicated by the
result-prefix
attribute of the xsl:namespace-alias
declaration.
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 no
default namespace is in force, specifying #default
denotes the null namespace URI. This allows elements that are in no
namespace in the stylesheet to acquire a namespace in the result
document, or vice versa.
If a literal namespace URI is declared to be an alias for multiple different target namespace URIs, then the declaration with the highest import precedence is used.
[ERR XTSE0810] It is a static error if
within a package 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 XTSE0812] It is a static error if a value
other than #default
is specified for either the
stylesheet-prefix
or the result-prefix
attributes of the xsl:namespace-alias
element when there is no in-scope binding for that namespace
prefix.
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.
xsl:namespace-alias
to
Generate a StylesheetWhen 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="3.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="3.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="3.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 possible to define an alias for the XML namespace.
<xsl:stylesheet xmlns:axml="http://www.example.com/alias-xml" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="3.0"> <xsl:namespace-alias stylesheet-prefix="axml" result-prefix="xml"/> <xsl:template match="/"> <name axml:space="preserve"> <first>James</first> <xsl:text> </xsl:text> <last>Clark</last> </name> </xsl:template> </xsl:stylesheet>
produces the output:
<name xml:space="preserve"><first>James</first> <last>Clark</last></name>
This allows an xml:space
attribute to be generated
in the output without affecting the way the stylesheet is parsed.
The same technique can be used for other attributes such as
xml:lang
, xml:base
, and
xml:id
.
Note:
Namespace aliasing is only necessary when literal result
elements are used. The problem of reserved namespaces does not
arise when using xsl:element
and xsl:attribute
to construct
the result tree. Therefore, as an alternative to
using xsl:namespace-alias
, it
is always possible to achieve the desired effect by replacing
literal result elements with xsl:element
and xsl:attribute
instructions.
xsl:element
<!-- Category: instruction
-->
<xsl:element
name = { qname }
namespace? = { uri }
inherit-namespaces? = "yes" | "no"
use-attribute-sets? = eqnames
type? = eqname
validation? = "strict" | "lax" | "preserve" |
"strip"
on-empty? = expression >
<!-- 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 result of evaluating the xsl:element
instruction,
in usual circumstances, is the newly constructed
element node.
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.8 Sequence
Constructors) is used to construct the content of the
element, as described in 5.8.1 Constructing Complex
Content.
The xsl:element
element may have a use-attribute-sets
attribute, whose
value is a whitespace-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.8.1
Constructing Complex Content.
The name
attribute is interpreted as an attribute value template, whose
effective value must be a lexical QName.
[ERR XTDE0820] It is a dynamic error if the
effective value of the name
attribute is not a lexical QName.
[ERR XTDE0830] In the case of an xsl:element
instruction with no
namespace
attribute, it is a dynamic error if the
effective value of the name
attribute is a lexical QName whose prefix is not declared
in an in-scope namespace declaration for the xsl:element
instruction.
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: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 must be in the lexical space of the
xs:anyURI
type. 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.
[ERR XTDE0835] It is a dynamic error if the
effective value of the
namespace
attribute is not in the lexical space of the
xs:anyURI
datatype or if it is the string
http://www.w3.org/2000/xmlns/
.
Note:
The XDM data model requires the name of a node to be an instance
of xs:QName
, and XML Schema defines the namespace part
of an xs:QName
to be an instance of
xs:anyURI
. However, the schema specification, and the
specifications that it refers to, give implementations some
flexibility in how strictly they enforce these constraints.
The prefix of the lexical QName specified in the
name
attribute (or the absence of a prefix) is copied
to the prefix part of the expanded QName representing the name
of the new element node. In the event of a conflict a prefix may
subsequently be added, changed, or removed during the namespace
fixup process (see 5.8.3 Namespace
Fixup). The term conflict here means any violation
of the constraints defined in [Data
Model], for example the use of the same prefix to refer to two
different namespaces in the element and in one of its attributes,
the use of the prefix xml
to refer to a namespace
other than the XML namespace, or any use of the prefix
xmlns
.
The xsl:element
instruction has an optional inherit-namespaces
attribute, with the value yes
or no
. The
default value is yes
. If the value is set to
yes
, or is omitted, then the namespace nodes created
for the newly constructed element (whether these were copied from
those of the source node, or generated as a result of namespace
fixup) are copied to the children and descendants of the newly
constructed element, as described in 5.8.1 Constructing Complex
Content. If the value is set to no
, then these
namespace nodes are not automatically copied to the children. This
may result in namespace undeclarations (such as
xmlns=""
or, in the case of XML Namespaces 1.1,
xmlns:p=""
) appearing on the child elements when a
final result tree is serialized.
The base URI of the new element is copied from the base URI of
the xsl:element
instruction in the stylesheet, unless the content of the new
element includes an xml:base
attribute, in which case
the base URI of the new element is the value of that attribute,
resolved (if it is a relative URI) against the base URI of the
xsl:element
instruction
in the stylesheet. (Note, however, that this is only relevant when
creating parentless elements. When the new element is copied to
form a child of an element or document node, the base URI of the
new copy is taken from that of its new parent.)
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 24.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.
If the on-empty
attribute is present and the
content of the constructed element as determined by the rules in
11.2.1 The Content of the
Constructed Element Node (that is, the result of evaluating
the sequence constructor and prepending any attributes generated by
the use-attribute-sets
attribute) is a sequence
containing nothing other than namespace nodes and zero-length text
nodes, then instead of returning the newly constructed element
node, the instruction returns the result of evaluating the
expression in the on-empty
attribute; if this
expression returns a node, the instruction returns a copy of this
node.
[ERR XTTE3310] It is a type error if the result
of evaluating the on-empty
attribute does not satisfy
the required type element()?
. That is, the expression
must deliver either a single element node, or an empty
sequence.
If the on-empty
expression is evaluated and returns
an empty sequence, then the validation
and
type
attributes are ignored. However, if the result of
the on-empty
expression is an element, then it is
subjected to validation as determined by these attributes, along
with [xsl:]default-validation
where relevant.
xsl:attribute
<!-- Category: instruction
-->
<xsl:attribute
name = { qname }
namespace? = { uri }
select? = expression
separator? = { string }
type? = eqname
validation? = "strict" | "lax" | "preserve" |
"strip"
on-empty? = expression >
<!-- 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 the select
attribute is present then the sequence constructor must be empty,
and if the sequence constructor is non-empty then the
select
attribute must be absent. If the
select
attribute is absent and the sequence
constructor is empty, then the string value of the new
attribute node will be a zero-length string. The way in which the
value is constructed is specified in 5.8.2 Constructing Simple
Content.
[ERR XTSE0840] 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.8.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 XTDE0850] It is a dynamic error if the
effective value of the name
attribute is not a lexical QName.
[ERR XTDE0855] In the case of an xsl:attribute
instruction
with no namespace
attribute, it is a dynamic
error if the effective value of the name
attribute is the string xmlns
.
[ERR XTDE0860] In the case of an xsl:attribute
instruction
with no namespace
attribute, it is a dynamic
error if the effective value of the name
attribute is a lexical QName whose prefix is not declared
in an in-scope namespace declaration for the xsl:attribute
instruction.
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 must be in the lexical space of the
xs:anyURI
type. 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.
[ERR XTDE0865] It is a dynamic error if the
effective value of the
namespace
attribute is not in the lexical space of the
xs:anyURI
datatype or if it is the string
http://www.w3.org/2000/xmlns/
.
Note:
The same considerations apply as for elements: [see ERR XTDE0835] in 11.2 Creating Element Nodes Using xsl:element .
The prefix of the lexical QName specified in the
name
attribute (or the absence of a prefix) is copied
to the prefix part of the expanded QName representing the name
of the new attribute node. In the event of a conflict this prefix
may subsequently be added, changed, or removed during the namespace
fixup process (see 5.8.3 Namespace
Fixup). If the attribute is in a non-null namespace and no
prefix is specified, then the namespace fixup process will invent a
prefix. The term conflict here means any violation of the
constraints defined in [Data
Model], for example the use of the same prefix to refer to two
different namespaces in the element and in one of its attributes,
the use of the prefix xml
to refer to a namespace
other than the XML namespace, or any use of the prefix
xmlns
.
If the name of a constructed attribute is xml:id
,
the processor must perform attribute value normalization by
effectively applying the
normalize-space
FO30 function
to the value of the attribute, and the resulting attribute node
must be given the is-id
property. This applies whether
the attribute is constructed using the xsl:attribute
instruction or
whether it is constructed using an attribute of a literal result
element. This does not imply any constraints on the value of the
attribute, or on its uniqueness, and it does not affect the
type annotation of the attribute, unless the
containing document is validated.
Note:
The effect of setting the is-id
property is that
the parent element can be located within the containing document by
use of the id
FO30
function. In effect, XSLT when constructing a document performs
some of the functions of an xml:id
processor, as
defined in [xml:id]; the other aspects of
xml:id
processing are performed during validation.
The following instruction creates the attribute
colors="red green blue"
:
<xsl:attribute name="colors" select="'red', 'green', 'blue'"/>
It is not an error to write:
<xsl:attribute name="xmlns:xsl" namespace="file://some.namespace" select="'http://www.w3.org/1999/XSL/Transform'"/>
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.8.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 24.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.
If the on-empty
attribute is present and the string
value of the constructed attribute is a zero-length string, then
instead of returning the constructed attribute, the instruction
returns the result of evaluating the expression in the
on-empty
attribute; if this expression returns a
node, the instruction returns a copy of the node..
[ERR XTTE3320] It is a type error if the result
of evaluating the on-empty
attribute does not satisfy
the required type attribute()?
. That is, the
expression must deliver either a single attribute node, or an empty
sequence.
If the on-empty
expression is evaluated and returns
an empty sequence, then the validation
and
type
attributes are ignored. However, if the result of
the on-empty
expression is an attribute node, then it
is subjected to validation as determined by these attributes, along
with [xsl:]default-validation
where relevant.
This section describes three different ways of creating text
nodes: by means of literal text nodes in the stylesheet, or by
using the xsl:text
and
xsl:value-of
instructions. It is also possible to create text nodes using the
xsl:number
instruction
described in 12 Numbering.
If and when the sequence that results from evaluating a sequence constructor is used to form the content of a node, as described in 5.8.2 Constructing Simple Content and 5.8.1 Constructing Complex Content, adjacent text nodes in the sequence are merged. Within the sequence itself, however, they exist as distinct nodes.
The following function returns a sequence of three text nodes:
<xsl:function name="f:wrap"> <xsl:param name="s"/> <xsl:text>(</xsl:text> <xsl:value-of select="$s"/> <xsl:text>)</xsl:text> </xsl:function>
When this function is called as follows:
<xsl:value-of select="f:wrap('---')"/>
the result is:
(---)
No additional spaces are inserted, because the calling xsl:value-of
instruction
merges adjacent text nodes before atomizing the sequence. However,
the result of the instruction:
<xsl:value-of select="data(f:wrap('---'))"/>
is:
( --- )
because in this case the three text nodes are atomized to form three strings, and spaces are inserted between adjacent strings.
It is possible to construct text nodes whose string value is zero-length. A zero-length text node, when atomized, produces a zero-length string. However, zero-length text nodes are ignored when they appear in a sequence that is used to form the content of a node, as described in 5.8.1 Constructing Complex Content and 5.8.2 Constructing Simple Content.
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.2 Stripping Whitespace from the Stylesheet 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.
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
25.1 Character Maps) or
disable-output-escaping
(see 25.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 construct 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 be
empty, in which case the result of evaluating the instruction is a
text node whose string value is the zero-length string.
The result of evaluating an xsl:text
instruction is the newly
constructed text node.
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.4 Stripping Whitespace from a
Source Tree).
For the effect of the deprecated
disable-output-escaping
attribute, see 25.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 generate computed text nodes. The xsl:value-of
instruction
computes the text using an expression that is specified as the value
of the select
attribute, or by means of contained
instructions. This might, for example, extract text from a
source tree or insert the value of a
variable.
<!-- 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.
The string value of the new text node may be defined either by
using the select
attribute, or by the sequence constructor (see 5.8 Sequence Constructors) that
forms the content of the xsl:value-of
element.
These are mutually exclusive: if the select
attribute is present then the sequence constructor must be empty,
and if the sequence constructor is non-empty then the
select
attribute must be absent. If the
select
attribute is absent and the sequence
constructor is empty, then the result of the instruction is a text
node whose string value is zero-length. The way in which the
value is constructed is specified in 5.8.2 Constructing Simple
Content.
[ERR XTSE0870] 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
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.8.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 the instruction is processed with
XSLT 1.0 behavior. 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.
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.9.2
Deep Copy.
For the effect of the deprecated
disable-output-escaping
attribute, see 25.2 Disabling Output
Escaping
<!-- Category: instruction
-->
<xsl:document
validation? = "strict" | "lax" | "preserve" |
"strip"
type? = eqname >
<!-- Content: sequence-constructor
-->
</xsl:document>
The xsl:document
instruction is used to create a new document node. The content of
the xsl:document
element is a sequence constructor for the
children of the new document node. 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.8.1 Constructing
Complex Content. The temporary tree rooted at
this document node forms the result tree.
Except in error situations, the result of evaluating the
xsl:document
instruction is a single node, the newly constructed document
node.
Note:
The new document is not serialized. To construct a document that
is to form a final result rather than an intermediate result, use
the xsl:result-document
instruction described in 24.1
Creating Final Result Trees.
The optional attributes type
and
validation
may be used on the xsl: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 24.2.2 Validating Document
Nodes.
The base URI of the new document node is taken from the base URI
of the xsl:document
instruction.
The document-uri
and unparsed-entities
properties of the new document node are set to empty.
The following example creates a temporary tree held in a
variable. The use of an enclosed xsl:document
instruction
ensures that uniqueness constraints defined in the schema for the
relevant elements are checked.
<xsl:variable name="tree" as="document-node()"> <xsl:document validation="strict"> <xsl:apply-templates/> </xsl:document> </xsl:variable>
<!-- 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 the
select
attribute is present then the sequence
constructor must be empty, and if the sequence constructor is
non-empty then the select
attribute must be absent. If
the select
attribute is absent and the sequence
constructor is empty, then 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.8.2 Constructing Simple
Content.
[ERR XTSE0880] 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 XDM attribute nodes, and cannot therefore be
constructed using xsl:attribute
instructions.
[ERR XTDE0890] It is a dynamic error if the
effective value of the name
attribute is not both an NCNameNames
and a PITargetXML.
Note:
Because these rules disallow the name xml
, the
xsl:processing-instruction
cannot be used to output an XML declaration. The xsl:output
declaration should be
used to control this instead (see 25
Serialization).
If the result of evaluating the content of the xsl:processing-instruction
contains the string ?>
, this string is modified by
inserting a space between the ?
and >
characters.
The base URI of the new processing-instruction is copied from
the base URI of the xsl:processing-instruction
element in the stylesheet. (Note, however, that this is only
relevant when creating a parentless processing instruction. When
the new processing instruction is copied to form a child of an
element or document node, the base URI of the new copy is taken
from that of its new parent.)
<!-- 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: if the select
attribute is present then the sequence constructor must be empty,
and if the sequence constructor is non-empty then the
select
attribute must be absent. Since the
string value of a namespace node cannot be a zero-length string,
either a select
attribute or a non-empty
sequence constructor must be
present. The way in which the value is constructed is
specified in 5.8.2
Constructing Simple Content.
[ERR XTDE0905] It is a dynamic error if the
string value of the new namespace node is not valid in the lexical
space of the datatype xs:anyURI
, or if it is the
string http://www.w3.org/2000/xmlns/
.
[ERR XTSE0910] 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.8.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 XTDE0920] It is a dynamic error if the
effective value of the name
attribute is neither a zero-length string nor an NCNameNames,
or if it is xmlns
.
[ERR XTDE0925] It is a dynamic error if the
xsl:namespace
instruction generates a namespace node whose name is
xml
and whose string value is not
http://www.w3.org/XML/1998/namespace
, or a namespace
node whose string value is
http://www.w3.org/XML/1998/namespace
and whose name is
not xml
.
[ERR XTDE0930] It is a dynamic error if
evaluating the select
attribute or the contained
sequence constructor of an xsl:namespace
instruction
results in a zero-length string.
For details of other error conditions that may arise, see 5.8 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 might, however, constrain the choice of prefixes when namespace fixup is performed.
Namespace prefixes for element and attribute names are initially established by the rules of the instruction that creates the element or attribute node, and in the event of conflicts, they may be changed by the namespace fixup process described in 5.8.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:
<xsl:element name="p:item" xmlns:p="http://www.example.com/p"> <xsl:namespace name="p">http://www.example.com/q</xsl:namespace> </xsl:element>
a possible serialization of the result tree is:
<ns0:item xmlns:ns0="http://www.example.com/p" xmlns:p="http://www.example.com/q"/>
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 [Namespaces in XML 1.1]). Namespace
undeclarations are generated automatically by the serializer if
undeclare-prefixes="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 construct 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 the select
attribute is present then the sequence constructor must be empty,
and if the sequence constructor is non-empty then the
select
attribute must be absent. If the
select
attribute is absent and the sequence
constructor is empty, then the string value of the new
comment node will be a zero-length string. The way in which the
value is constructed is specified in 5.8.2 Constructing Simple
Content.
[ERR XTSE0940] 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!-->
In the generated comment node, the processor must insert a space after any occurrence of
-
that is followed by another -
or that
ends the comment.
<!-- Category: instruction -->
<xsl:copy
select? = expression
copy-namespaces? = "yes" | "no"
inherit-namespaces? = "yes" | "no"
use-attribute-sets? = eqnames
type? = eqname
validation? = "strict" | "lax" | "preserve" |
"strip"
on-empty? = expression >
<!-- Content: sequence-constructor
-->
</xsl:copy>
The xsl:copy
instruction provides a way of copying a selected item. The
selected item is the item selected by evaluating the expression in
the select
attribute if present, or the context
item otherwise. If the selected item is a node,
evaluating the xsl:copy
instruction constructs a copy of the selected 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 selected item is an atomic value or
function item, the xsl:copy
instruction returns this
value. The sequence constructor is not
evaluated, and must not generate
any type errors.
When the selected 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. In the case of an attribute node, it will also have the same
values for the is-id
and is-idrefs
properties. The sequence constructor is not
evaluated, and must not generate
any type errors..
When the selected 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 selected node. The content of the new node is
formed by evaluating the sequence constructor
contained in the xsl:copy
instruction. If the select
attribute is present
then the sequence constructor is evaluated with the selected item
as the singleton focus; otherwise it is
evaluated using the context of the xsl:copy
instruction
unchanged. 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.8.1 Constructing
Complex Content.
If the select
expression returns an empty sequence,
the xsl:copy
instruction
returns an empty sequence, and the contained sequence constructor is not
evaluated.
[ERR XTTE3180] It is a type error if the result
of evaluating the select
expression is a sequence of
more than one item.
The xsl:copy
instruction has an optional use-attribute-sets
attribute, whose value is a whitespace-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.8.3 Namespace Fixup.
The xsl:copy
instruction has an optional inherit-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 the namespace nodes created for the newly
constructed element (whether these were copied from those of the
source node, or generated as a result of namespace fixup) are
copied to the children and descendants of the newly constructed
element, as described in 5.8.1 Constructing Complex
Content. If the value is set to no
, then these
namespace nodes are not automatically copied to the children. This
may result in namespace undeclarations (such as
xmlns=""
or, in the case of XML Namespaces 1.1,
xmlns:p=""
) appearing on the child elements when a
final result tree is serialized.
[ERR XTTE0950] It is a type error to use the
xsl:copy
or xsl:copy-of
instruction to copy
a node that has namespace-sensitive content if the
copy-namespaces
attribute has the value
no
and its explicit or implicit
validation
attribute has the value
preserve
. It is also a type error if either of these
instructions (with validation="preserve"
) is used to
copy an attribute having namespace-sensitive content, unless the
parent element is also copied. A node has namespace-sensitive
content if its typed value contains an item of type
xs:QName
or xs:NOTATION
or a type derived
therefrom. The reason this is an error is because the validity of
the content depends on the namespace context being preserved.
Note:
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.8.3 Namespace Fixup) when the
attribute is added to an element in the result tree, but if
namespace prefixes 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 nodes 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 24.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, except in the case of an
element node having an xml:base
attribute, in which
case the base URI of the new node is taken as the value of the
xml:base
attribute, resolved if it is relative against
the base URI of the xsl:copy
instruction. If the
copied node is subsequently attached as a child to a new element or
document node, the final copy of the node inherits its base URI
from its parent node, unless this is overridden using an
xml:base
attribute.
When an xml:id
attribute is copied, using either
the xsl:copy
or xsl:copy-of
instruction, it is
implementation-defined whether the
value of the attribute is subjected to attribute value
normalization (that is, effectively applying the
normalize-space
FO30
function).
Note:
In most cases the value will already have been subjected to attribute value normalization on the source tree, but if this processing has not been performed on the source tree, it is not an error for it to be performed on the result tree.
The effect of specifying an on-empty
attribute is
as follows.
If the result of the instruction in the absence of the
on-empty
attribute would be any of the following:
An empty sequence
An element or document node having no attributes and no children
A node of any other kind with a zero-length string value
then instead of returning this result, the instruction returns
the result of evaluating the expression in the
on-empty
attribute; if the result of this expression
is a node, the instruction returns a copy of this node.
[ERR XTTE3330] It is a type error if the result
of evaluating the on-empty
attribute does not satisfy
the required type node()?
. That is, the expression
must deliver either a single node, or an empty sequence.
If the on-empty
expression is evaluated and returns
an empty sequence, then the validation
and
type
attributes are ignored. However, if the result of
the on-empty
expression is a node, then it is
subjected to validation as determined by these attributes, along
with [xsl:]default-validation
where relevant.
<!-- Category: instruction
-->
<xsl:copy-of
select = expression
copy-namespaces? = "yes" | "no"
type? = eqname
validation? = "strict" | "lax" | "preserve" |
"strip" />
The xsl:copy-of
instruction can be used to construct a copy of a sequence of nodes,
atomic values, and/or function items 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, atomic values, and/or function items. 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.8.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.
The new element will have the same values of the
is-id
, is-idrefs
, and nilled
properties as the original element.
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 nod