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<EMAIL_ADDRESS>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
<IP_ADDRESS>
Visibility of Components
<IP_ADDRESS>
Visibility of Declarations
<IP_ADDRESS>
Exposing Components
<IP_ADDRESS>
Accepting Components
<IP_ADDRESS>
Overriding Named
Components from a Used Package
<IP_ADDRESS>
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
<IP_ADDRESS>
Maintaining Position: the Focus
<IP_ADDRESS>
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
<IP_ADDRESS>
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
<IP_ADDRESS>
Streamability of
Literal Result Elements
<IP_ADDRESS>
Streamability of
extension instructions
<IP_ADDRESS>
Streamability of
xsl:analyze-string
<IP_ADDRESS>
Streamability of
xsl:apply-imports
<IP_ADDRESS>
Streamability of
xsl:apply-templates
<IP_ADDRESS>
Streamability of
xsl:assert
<IP_ADDRESS>
Streamability of
xsl:attribute
<IP_ADDRESS>
Streamability of
xsl:break
<IP_ADDRESS>
Streamability of
xsl:call-template
<IP_ADDRESS>
Streamability of
xsl:choose
<IP_ADDRESS>
Streamability of
xsl:comment
<IP_ADDRESS>
Streamability of
xsl:copy
<IP_ADDRESS>
Streamability of
xsl:copy-of
<IP_ADDRESS>
Streamability of
xsl:document
<IP_ADDRESS>
Streamability of
xsl:element
<IP_ADDRESS>
Streamability of
xsl:evaluate
<IP_ADDRESS>
Streamability of
xsl:for-each
<IP_ADDRESS>
Streamability of
xsl:for-each-group
<IP_ADDRESS>
Streamability of
xsl:fork
<IP_ADDRESS>
Streamability of xsl:if
<IP_ADDRESS>
Streamability of
xsl:iterate
<IP_ADDRESS>
Streamability of xsl:map
<IP_ADDRESS>
Streamability of
xsl:map-entry
<IP_ADDRESS>
Streamability of
xsl:merge
<IP_ADDRESS>
Streamability of
xsl:message
<IP_ADDRESS>
Streamability of
xsl:namespace
<IP_ADDRESS>
Streamability of
xsl:next-iteration
<IP_ADDRESS>
Streamability of
xsl:next-match
<IP_ADDRESS>
Streamability of
xsl:number
<IP_ADDRESS>
Streamability of
xsl:perform-sort
<IP_ADDRESS>
Streamability
of xsl:processing-instruction
<IP_ADDRESS>
Streamability of
xsl:result-document
<IP_ADDRESS>
Streamability of
xsl:sequence
<IP_ADDRESS>
Streamability of
xsl:stream
<IP_ADDRESS>
Streamability of
xsl:text
<IP_ADDRESS>
Streamability of xsl:try
<IP_ADDRESS>
Streamability of
xsl:value-of
<IP_ADDRESS>
Streamability of
xsl:variable
19.8.5 Classifying Attribute Sets
19.8.6 Classifying Value Templates
19.8.7 Classifying Expressions
<IP_ADDRESS>
Streamability of for
expressions
<IP_ADDRESS>
Streamability of
Quantified Expressions
<IP_ADDRESS>
Streamability of if
expressions
<IP_ADDRESS>
Streamability of
union, intersect, and except expressions
<IP_ADDRESS>
Streamability of
Simple Mapping Expressions
<IP_ADDRESS>
Streamability of Path
Expressions
<IP_ADDRESS>
Streamability of Axis
Steps
<IP_ADDRESS>
Streamability of
Filter Expressions
<IP_ADDRESS>
Streamability of
Dynamic Function Calls
<IP_ADDRESS>
Streamability of
Variable References
<IP_ADDRESS>
Streamability
of the Context Item Expression
<IP_ADDRESS>
Streamability of
Function Calls
<IP_ADDRESS>
Streamability of
Named Function References
<IP_ADDRESS>
Streamability of
Inline Function Declarations
<IP_ADDRESS>
Streamability of map
expressions
19.8.8 Classifying Calls to Built-In
Functions
<IP_ADDRESS>
Streamability of the
accumulator-after function
<IP_ADDRESS>
Streamability of the
accumulator-before function
<IP_ADDRESS>
Streamability of the current
function
<IP_ADDRESS>
Streamability of the
current-group function
<IP_ADDRESS>
Streamability of
the current-grouping-key function
<IP_ADDRESS>
Streamability of the
function-lookup function
<IP_ADDRESS>
Streamability of the last
function
<IP_ADDRESS>
Streamability of the
outermost function
<IP_ADDRESS>
Streamability of the position
function
<IP_ADDRESS>
Streamability of the root
function
<IP_ADDRESS>
Streamability
of the unparsed-entity-public-id function
<IP_ADDRESS>
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
<IP_ADDRESS>
map:new
<IP_ADDRESS>
map:keys
<IP_ADDRESS>
map:contains
<IP_ADDRESS>
map:get
<IP_ADDRESS>
map:entry
<IP_ADDRESS>
map:remove
<IP_ADDRESS>
map:for-each-entry
<IP_ADDRESS>
fn:collation-key
<IP_ADDRESS>
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
<IP_ADDRESS>
Validation using
the [xsl:]validation Attribute
<IP_ADDRESS>
Validation using the [xsl:]type
Attribute
<IP_ADDRESS>
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 <IP_ADDRESS> 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
<IP_ADDRESS>
.
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 <IP_ADDRESS> 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.