The Statically known function signaturesXP30 are the core functions defined in [Functions and Operators], the constructor functions for all the simple types in the in-scope schema definitionsXP30, the additional functions defined in this specification, the stylesheet functions defined in the stylesheet, plus any extension functions bound using implementation-defined mechanisms (see 23 Extensibility and Fallback).
Note:
It follows from the above that a conformant XSLT processor must implement the entire library of core functions defined in [Functions and Operators].
The statically known collationsXP30 are implementation-defined. However, the set of in-scope collations must always include the Unicode codepoint collation, defined in Section 5.3 Comparison of strings FO30.
The default
collationXP30 is defined by the value
of the [xsl:]default-collation
attribute on the
innermost enclosing element that has such an attribute. For
details, see 3.8.1 The
default-collation Attribute.
[Definition: In this specification the term default
collation means the collation that is used by XPath operators
such as eq
and lt
appearing in XPath
expressions within the stylesheet.]
This collation is also used by default when comparing strings in
the evaluation of the xsl:key
and xsl:for-each-group
elements. This may also (but need not
necessarily) be the same as the default collation used for xsl:sort
elements within the
stylesheet. Collations used by xsl:sort
are described in 13.1.3 Sorting Using
Collations.
The base URI is the base URI of the containing element in the stylesheet. The concept of the base URI of a node is defined in Section 5.2 base-uri Accessor DM30
The set of statically known documentsXP30 is implementation-defined.
The set of statically known collectionsXP30 is implementation-defined.
The statically known default collection typeXP30 is implementation-defined.
The set of statically
known decimal formatsXP30 is the set
of decimal formats defined by xsl:decimal-format
declarations in the stylesheet.
Some of the components of the XPath static context are used also
by XSLT elements. For example, the xsl:sort
element makes use of the
collations defined in the static context, and attributes such as
type
and as
may reference types defined
in the in-scope schema components.
Many top-level declarations in a stylesheet, and attributes on
the xsl:stylesheet
element, affect the behavior of instructions within the stylesheet.
Each of these constructs is described in its appropriate place in
this specification.
A number of these constructs are of particular significance because they are used by functions defined in XSLT, which are added to the library of functions available for use in XPath expressions within the stylesheet. These are:
The set of named keys, used by the key
function
The values of system properties, used by the system-property
function
The set of available instructions, used by the element-available
function
A dynamic function call clears the first of these components:
this means that a dynamic call to the key
function will always raise a
dynamic error (the key name is unknown). The values of system
properties and the set of available instructions, by contrast,
reflect the capabilities and configuration of the processor rather
than values specific to the stylesheet code itself; the result of a
dynamic call to system-property
or
element-available
will reflect the information available to the processor at
evaluation time.
Note:
If these functions are called within a static expression, the results will reflect the capabilities and configuration of the processor used to perform static analysis, while if they are called elsewhere, the results should reflect the capabilities and configuration of the processor used to perform dynamic evaluation, which might give a different result. These calls should not be pre-evaluated at compile time unless it is known that this will give the same result.
For convenience, the dynamic context is described in two parts: the focus, which represents the place in the source document that is currently being processed, and a collection of additional context variables.
A number of functions specified in [Functions and Operators] are defined to
be deterministicFO30,
meaning that if they are called twice during the same execution
scopeFO30, with the same arguments,
then they return the same results (see Section 1.6
Terminology FO30). In XSLT, the
execution of a stylesheet defines the execution scope. This means,
for example, that if the function
current-dateTime
FO30 is called
repeatedly during a transformation, it produces the same result
each time. By implication, the components of the dynamic context on
which these functions depend are also stable for the duration of
the transformation. Specifically, the following components defined
in Section
2.1.2 Dynamic Context XP30 must be
stable: function implementations, current
dateTime, implicit timezone, available
documents, available collections, and default
collection. The values of global variables and stylesheet
parameters are also stable for the duration of a transformation.
The focus is not stable; the additional dynamic context
components defined in 5.4.4 Additional Dynamic Context
Components used by XSLT are also not stable.
As specified in [Functions and
Operators], implementations may provide user options that relax
the requirement for the doc
FO30
and collection
FO30
functions (and therefore, by implication, the document
function) to return
stable results. By default, however, the functions must be stable.
The manner in which such user options are provided, if at all, is
implementation-defined.
XPath expressions contained in [xsl:]use-when
attributes are not considered to be evaluated "during the
transformation" as defined above. For details see 3.14 Conditional Element
Inclusion.
[Definition: A component of the context that has no value is said to be absent.] This is a distinguishable state, and is not the same as having the empty sequence as its value.
[Definition: When a sequence constructor is evaluated, the processor keeps track of which items are being processed by means of a set of implicit variables referred to collectively as the focus.] More specifically, the focus consists of the following three values:
[Definition: The
context item is the item currently being processed. An item
(see [Data Model]) is either an
atomic value (such as an integer, date, or string), a node,
or a function item. The context item is initially set
to the initial context item supplied
when the transformation is invoked (see 2.3 Initiating a Transformation). It
changes whenever instructions such as xsl:apply-templates
and
xsl:for-each
are used
to process a sequence of items; each item in such a sequence
becomes the context item while that item is being
processed.] The context item is
returned by the XPath expression .
(dot).
[Definition: The context position is the position
of the context item within the sequence of items currently being
processed. It changes whenever the context item changes. When an
instruction such as xsl:apply-templates
or
xsl:for-each
is used
to process a sequence of items, the first item in the sequence is
processed with a context position of 1, the second item with a
context position of 2, and so on.]
The context position is returned by the XPath expression
position()
.
[Definition: The
context size is the number of items in the sequence of items
currently being processed. It changes whenever instructions such as
xsl:apply-templates
and
xsl:for-each
are used
to process a sequence of items; during the processing of each one
of those items, the context size is set to the count of the number
of items in the sequence (or equivalently, the position of the last
item in the sequence).] The context
size is returned by the XPath expression last()
.
[Definition: If
the context item is a node (as distinct from an
atomic value such as an integer), then it is also referred to as
the context node. The context node is not an independent
variable, it changes whenever the context item changes. When the
context item is an atomic value or a function item,
there is no context node.] The
context node is returned by the XPath expression
self::node()
, and it is used as the starting node for
all relative path expressions.
Where the containing element of an XPath expression is an instruction or a literal result element, the initial context item, context position, and context size for the XPath expression are the same as the context item, context position, and context size for the evaluation of the containing instruction or literal result element.
For an XPath expression contained in a value template, the initial context item, context position, and context size for the XPath expression are the same as the context item, context position, and context size for the evaluation of the containing sequence constructor.
In other cases (for example, where the containing element is
xsl:sort
, xsl:with-param
, or xsl:key
), the rules are given in
the specification of the containing element.
The current
function
can be used within any XPath expression to select the item that was
supplied as the context item to the XPath expression by the XSLT
processor. Unlike .
(dot) this is unaffected by
changes to the context item that occur within the XPath expression.
The current
function is
described in 20.3.1
fn:current.
On completion of an instruction that changes the focus (such as
xsl:apply-templates
or xsl:for-each
), the
focus reverts to its previous value.
When a stylesheet function is called, the focus within the body of the function is initially absent. The focus is also absent on initial entry to the stylesheet if no initial context item is supplied.
When the focus is absent, evaluation of any expression that references the context item, context position, or context size results in a dynamic error [ERR XPDY0002] XP30
The description above gives an outline of the way the focus works. Detailed rules for the effect of each instruction are given separately with the description of that instruction. In the absence of specific rules, an instruction uses the same focus as its parent instruction.
[Definition: A singleton focus based on an item J has the context item (and therefore the context node, if J is a node) set to J, and the context position and context size both set to 1 (one).]
The previous section explained how the focus for an XPath expression appearing in an XSLT stylesheet is initialized. This section explains how the other components of the dynamic contextXP30 of an XPath expression are initialized.
The dynamic variablesXP30 are the current values of the in-scope variable binding elements.
The current date and time represents an implementation-dependent point in time during processing of the transformation; it does not change during the course of the transformation.
The implicit timezoneXP30 is implementation-defined.
The available documentsXP30, and the available collectionsXP30 are determined as part of the process for initiating a transformation (see 2.3 Initiating a Transformation).
The available
documentsXP30 are defined as part of
the XPath 3.0 dynamic context to support the doc
FO30
function, but this component is also referenced by the similar XSLT
document
function: see
20.1 fn:document. This variable
defines a mapping between URIs passed to the doc
FO30
or document
function and
the document nodes that are returned.
The mapping from URIs to document nodes is affected by xsl:strip-space
declarations and by the input-type-annotations
attribute, and may therefore vary from one package to another.
Note:
Defining this as part of the evaluation context is a formal way of specifying that the way in which URIs get turned into document nodes is outside the control of the language specification, and depends entirely on the run-time environment in which the transformation takes place.
The XSLT-defined document
function allows the use
of URI references containing fragment identifiers. The
interpretation of a fragment identifier depends on the media type
of the resource representation. Therefore, the information supplied
in available
documentsXP30 for XSLT processing
must provide not only a mapping from URIs to document nodes as
required by XPath, but also a mapping from URIs to media types.
The default collectionXP30 is implementation-defined. This allows options such as setting the default collection to be an empty sequence, or to be absent.
In addition to the values that make up the focus, an XSLT processor maintains a number of other dynamic context components that reflect aspects of the evaluation context. These components are fully described in the sections of the specification that maintain and use them. They are:
The current template rule, which is the
template rule most recently invoked by an
xsl:apply-templates
,
xsl:apply-imports
, or
xsl:next-match
instruction: see 6.9 Overriding
Template Rules;
The current mode, which is the mode set by the most recent
call of xsl:apply-templates
(for a full definition see 6.6
Modes);
The current group and current grouping key, which provide
information about the collection of items currently being processed
by an xsl:for-each-group
or xsl:merge
instruction: see 14.2.1
fn:current-group, 14.2.2
fn:current-grouping-key, and 15
Merging;
Note:
In XSLT 3.0 the initial value of these two properties is
"absent", which means that any reference to their values causes a
dynamic error. Previously, the initial value was an empty sequence.
The value is also set to "absent" by an xsl:for-each-group
instruction that binds variables to the current group value and/or current grouping key value
using the bind-group
or bind-grouping-key
attributes.
The current captured substrings:
this is a sequence of strings, which is maintained when a string is
matched against a regular expression using the xsl:analyze-string
instruction, and which is accessible using the regex-group
function: see
17.2 fn:regex-group.
The output state: this is a flag whose two
possible values are final output state and temporary output state. This flag
indicates whether instructions are currently writing to a final result tree or to an internal
data structure. The initial setting is final output state, and it is switched
to temporary output state by
instructions such as xsl:variable
. For more
details, see 24.1 Creating
Final Result Trees.
The following non-normative table summarizes the initial state of each of the components in the evaluation context, and the instructions which cause the state of the component to change.
| Component | Initial Setting | Set by | Cleared by |
|---|---|---|---|
| focus | singleton focus based on the initial context item if supplied | xsl:apply-templates ,
xsl:for-each , xsl:for-each-group ,
xsl:analyze-string ,
evaluation of patterns |
Calls to stylesheet functions |
| current template rule | If a named template is supplied as the entry point to the transformation, then absent; otherwise the initial template | xsl:apply-templates ,
xsl:apply-imports ,
xsl:next-match |
xsl:for-each , xsl:for-each-group ,
xsl:analyze-string ,
xsl:iterate ,
xsl:stream , xsl:merge , xsl:evaluate , and
calls to stylesheet functions, and dynamic
function calls. Also cleared while evaluating global
variables or default values of stylesheet parameters,
patterns, and the sequence constructors
contained in xsl:key and
xsl:sort . |
| current mode | the initial mode | xsl:apply-templates |
Calls to stylesheet functions. Also
cleared while evaluating global variables and stylesheet
parameters, patterns, and the sequence constructor
contained in xsl:key or
xsl:sort . Clearing the
current mode causes the current mode to be set to the default
(unnamed) mode. |
| current group | absent | xsl:for-each-group ,
xsl:merge |
Calls to stylesheet functions, dynamic
function calls, evaluation of global variables,
stylesheet parameters, and patterns, calls on xsl:for-each-group with
a bind-group attribute. |
| current grouping key | absent | xsl:for-each-group ,
xsl:merge |
Calls to stylesheet functions, dynamic
function calls, evaluation of global variables,
stylesheet parameters, and patterns, calls on xsl:for-each-group with
a bind-grouping-key attribute or with a
group-starting-with or group-ending-with
attribute. |
| current captured substrings | empty sequence | xsl:matching-substring |
xsl:non-matching-substring ;
Calls to stylesheet functions, dynamic
function calls, evaluation of global variables,
stylesheet parameters, and patterns |
| output state | final output state | Set to temporary output state by
instructions such as xsl:variable , xsl:attribute , etc., and by
calls on stylesheet functions |
None |
[Definition: The term non-contextual
function call is used to refer to function calls that do not
pass the dynamic context to the called function. This includes all
calls on stylesheet functions and all dynamic
function invocationsXP30, (that is
calls to function items as permitted by XPath 3.0). It does not
include calls to all core functions in particular those that
explicitly depend on the context, such as the current-group
and regex-group
functions. It is
implementation-defined whether,
and under what circumstances, calls to extension functions are
non-contextual.]
Named function references (such as position#0
) and
calls on
function-lookup
FO30 (for
example, function-lookup("position", 0)
) are defined
to retain the XPath static and dynamic context at the point of
invocation as part of the closure of the resulting function item,
and to use this preserved context when a dynamic function call is
subsequently made using the function item. This rule does not
extend to the XSLT extensions to the dynamic context defined in
this section. If a dynamic function call is made that depends on
the XSLT part of the dynamic context (for example,
regex-group#1(2)
), then the relevant components of the
context are cleared as described in the table above.
The definition of the
format-number
FO30 function is
now in [Functions and Operators].
What remains here is the definition of the xsl:decimal-format
declaration, which provides the context for this function when used
in an XSLT stylesheet.
<!-- Category: declaration
-->
<xsl:decimal-format
name? = eqname
decimal-separator? = char
grouping-separator? = char
infinity? = string
minus-sign? = char
NaN? = string
percent? = char
per-mille? = char
zero-digit? = char
digit? = char
pattern-separator? =
char />
The xsl:decimal-format
element sets the statically known decimal formats
component of the static context for XPath expressions, which
controls the interpretation of a picture string used by the
format-number
FO30
function.
[Definition: The picture string is the string
supplied as the second argument of the
format-number
FO30
function.]
Note:
The
format-number
FO30 function,
previously defined in this specification, is now a core function
defined in [Functions and
Operators].
A package may contain multiple xsl:decimal-format
declarations and may include or import stylesheet modules
that also contain xsl:decimal-format
declarations. The name of an xsl:decimal-format
declaration is the value of its name
attribute, if
any.
[Definition: All the xsl:decimal-format
declarations in a package that share the same name are
grouped into a named decimal format; those that have no name
are grouped into a single unnamed decimal format.]
The attributes of the xsl:decimal-format
declaration define the value of the corresponding attribute in the
relevant decimal format in the Statically
known decimal formatsXP30 component
of the static context for all XPath expressions in the package. The
attribute names used in the XSLT 3.0 syntax are the same as the
attribute names used in the definition of the static context,
except that the digit
attribute of xsl:decimal-format
corresponds to the digit-sign
attribute in the static
context.
The scope of an xsl:decimal-format
name
is the package in which it is declared; the name is available for
use only in calls to
format-number
FO30 that appear
within the same package.
If a package does not contain a declaration of the
unnamed decimal format, a declaration equivalent to an xsl:decimal-format
element with no attributes is implied.
The attributes of the xsl:decimal-format
declaration establish values for a number of variables used as
input to the algorithm followed by the
format-number
FO30 function. An
outline of the purpose of each attribute is given below; however,
the definitive explanations are given as part of the
specification of
format-number
FO30.
For any named decimal format, the effective value of
each attribute is taken from an xsl:decimal-format
declaration that has that name, and that specifies an explicit
value for the required attribute. If there is no such declaration,
the default value of the attribute is used. If there is more than
one such declaration, the one with highest import precedence is used.
For any unnamed decimal format, the effective value of
each attribute is taken from an xsl:decimal-format
declaration that is unnamed, and that specifies an explicit value
for the required attribute. If there is no such declaration, the
default value of the attribute is used. If there is more than one
such declaration, the one with highest import precedence
is used.
[ERR XTSE1290] It is a static error if a named
or unnamed decimal format contains two conflicting
values for the same attribute in different xsl:decimal-format
declarations having the same import precedence,
unless there is another definition of the same attribute with
higher import precedence.
The following attributes control the interpretation of
characters in the picture string supplied to the
format-number
FO30 function,
and also specify characters that may appear in the result of
formatting the number. In each case the value must be a single character [see
ERR XTSE0020].
decimal-separator
specifies the character used for
the decimal-separator-sign; the default value is the
period character (.
)
grouping-separator
specifies the character used for
the grouping-sign, which is typically used as a
thousands separator; the default value is the comma character
(,
)
percent
specifies the character used for the
percent-sign; the default value is the percent character
(%
)
per-mille
specifies the character used for the
per-mille-sign; the default value is the Unicode
per-mille character (#x2030)
zero-digit
specifies the character used for the
digit-zero-sign; the default value is the digit zero
(0
). This character must be
a digit (category Nd in the Unicode property database), and it
must have the numeric value zero. This
attribute implicitly defines the Unicode character that is used to
represent each of the values 0 to 9 in the final result string:
Unicode is organized so that each set of decimal digits forms a
contiguous block of characters in numerical sequence.
[ERR XTSE1295] It is a static error if the
character specified in the zero-digit
attribute is not
a digit or is a digit that does not have the numeric value
zero.
The following attributes control the interpretation of
characters in the picture string supplied to the
format-number
FO30 function. In
each case the value must be a single
character [see ERR
XTSE0020].
digit
specifies the character used for the
digit-sign in the picture string; the default
value is the number sign character (#
)
pattern-separator
specifies the character used for
the pattern-separator-sign, which separates positive and
negative sub-pictures in a picture string; the default
value is the semi-colon character (;
)
The following attributes specify characters or strings that may appear in the result of formatting the number:
infinity
specifies the string used for the
infinity-symbol; the default value is the string
Infinity
NaN
specifies the string used for the
NaN-symbol, which is used to represent the value NaN
(not-a-number); the default value is the string
NaN
minus-sign
specifies the character used for the
minus-symbol; the default value is the hyphen-minus
character (-
, #x2D). The value must be a single character.
[ERR XTSE1300] It is a static error if, for any named or unnamed decimal format, the variables representing characters used in a picture string do not each have distinct values. These variables are decimal-separator-sign, grouping-sign, percent-sign, per-mille-sign, digit-zero-sign, digit-sign, and pattern-separator-sign.
Every (named or unnamed) decimal format defined in a package is
added to the statically
known decimal formatsXP30 in the
static
contextXP30 of every expression in
the package, excluding expressions appearing in
[xsl:]use-when
attributes.
In XSLT 3.0, patterns can match any kind of item: atomic values and function items as well as nodes.
A template rule identifies the items to which it applies by means of a pattern. As well as being used in template rules, patterns are used for numbering (see 12 Numbering), for grouping (see 14 Grouping), and for declaring keys (see 20.2 Keys).
[Definition: A pattern specifies a set of conditions on an item. An item that satisfies the conditions matches the pattern; an item that does not satisfy the conditions does not match the pattern.]
There are two basic kinds of pattern: predicate patterns, and path patterns. Patterns may also be formed by combining other patterns using union, intersection, and difference operators.
A predicate pattern uses the syntax .[ Expr ]
written with zero or or more predicates in square brackets; it
matches an item if each of the predicates matches the context item.
The detailed semantics are given in 5.6.3 The Meaning of a Pattern.
This construct can be used to match items of any kind (nodes,
atomic values, and function items). For example, the pattern
.[starts-with(., '$')]
matches any string that starts
with the character "$", or a node whose atomized value starts with
"$". This example shows a predicate pattern with a single
predicate, but the grammar allows any number of predicates (zero or
more).
The syntax for path patterns is a subset of the syntax for expressions. Path patterns are used only for matching nodes; an item other than a node will never match a path pattern. As explained in detail below, a node matches a path pattern if the node can be selected by deriving an equivalent expression, and evaluating this expression with respect to some possible context.
Note:
The specification uses the phrases an item matches a pattern and a pattern matches an item interchangeably. They are equivalent: an item matches a pattern if and only if the pattern matches the item.
Here are some examples of patterns:
.
matches any item.
*
matches any element.
para
matches any para
element.
chapter|appendix
matches any chapter
element and any appendix
element.
olist/entry
matches any entry
element
with an olist
parent.
appendix//para
matches any para
element with an appendix
ancestor element.
schema-element(us:address)
matches any element that
is annotated as an instance of the type defined by the schema
element declaration us:address
, and whose name is
either us:address
or the name of another element in
its substitution group.
attribute(*, xs:date)
matches any attribute
annotated as being of type xs:date
.
/
matches a document node.
document-node()
matches a document node.
document-node(schema-element(my:invoice))
matches
the document node of a document whose document element is named
my:invoice
and matches the type defined by the global
element declaration my:invoice
.
text()
matches any text node.
namespace-node()
matches any namespace node.
node()
matches any node other than an attribute
node, namespace node, or document node.
id("W33")
matches the element with unique ID
W33
.
para[1]
matches any para
element that
is the first para
child element of its parent. It also
matches a parentless para
element.
//para
matches any para
element that
has a parent node.
bullet[position() mod 2 = 0]
matches any
bullet
element that is an even-numbered
bullet
child of its parent.
div[@class="appendix"]//p
matches any
p
element with a div
ancestor element
that has a class
attribute with value
appendix
.
@class
matches any class
attribute
(not any element that has a class
attribute).
@*
matches any attribute node.
$xyz
matches any node that is present in the value
of the variable $xyz
.
$xyz//*
matches any element that is a descendant of
a node that is present in the value of the variable
$xyz
.
doc('product.xml')//*
matches any element within
the document whose document URI is 'product.xml'.
.[. instance of node()]
matches any node. (Note the
distinction from the pattern node()
.)
.[. instance of xs:date]
matches any atomic value
of type xs:date
(or a type derived by restriction from
xs:date
).
.[. gt current-date()]
matches any date in the
future. It can match an atomic value of type xs:date
or xs:untypedAtomic
, or a node whose atomized value is
an xs:date
or xs:untypedAtomic
value.
.[starts-with(., 'e')]
matches any node or atomic
value that after conversion to a string using the function
conversion rules starts with the letter 'e'.
.[. instance of function(*)]
matches any function
item.
.[$f(.)]
matches any item provided that the call on
the function bound to the variable $f
returns a result
whose effective boolean value is true.
[ERR XTSE0340] Where an attribute is defined to contain a pattern, it is a static error if the pattern does not match the production Pattern30.
The grammar for patterns uses the notation defined in Section A.1.1 Notation XP30.
The lexical rules for patterns are the same as the lexical rules
for XPath expressions, as defined in Section A.2
Lexical structure XP30. Comments are
permitted between tokens, using the syntax (: ... :)
.
All other provisions of the XPath grammar apply where relevant, for
example the rules for whitespace handling and extra-grammatical
constraints.
| [1] | Pattern30 |
::= | PredicatePattern |
UnionExprP |
| [2] | PredicatePattern |
::= | "." PredicateListXP30 |
| [3] | UnionExprP |
::= | IntersectExceptExprP
(("union" | "|") IntersectExceptExprP)* |
| [4] | IntersectExceptExprP |
::= | PathExprP
(("intersect" | "except") PathExprP)* |
| [5] | PathExprP |
::= | RootedPath |
| [6] | RootedPath |
::= | (VarRefXP30
| FunctionCallP)
PredicateListXP30
(("/" | "//") RelativePathExprP)? |
| [7] | FunctionCallP |
::= | OuterFunctionName
ArgumentListP |
| [8] | OuterFunctionName |
::= | "doc" | "id" | "element-with-id" | "key" | PrefixedQName | URIQualifiedNameXP30 |
| [10] | ArgumentListP |
::= | "(" (ArgumentP ("," ArgumentP)*)? ")" |
| [11] | ArgumentP |
::= | VarRefXP30
| LiteralXP30 |
| [12] | RelativePathExprP |
::= | StepExprP
(("/" | "//") StepExprP)* |
| [13] | StepExprP |
::= | PostfixExprP | AxisStepP |
| [14] | PostfixExprP |
::= | ParenthesizedExprP
PredicateListXP30 |
| [15] | ParenthesizedExprP |
::= | "(" UnionExprP ")" |
| [16] | AxisStepP |
::= | ForwardStepP PredicateListXP30 |
| [17] | ForwardStepP |
::= | (ForwardAxisP NodeTestXP30)
| AbbrevForwardStepXP30 |
| [18] | ForwardAxisP |
::= | ("child" "::") |
| [122] | PrefixedQName |
::= | NCNameXP30
":" NCNameXP30 |
The names of these constructs are chosen to align with the XPath
3.0 grammar. Constructs whose names are suffixed with
P
are restricted forms of the corresponding XPath 3.0
construct without the suffix. Constructs labelled with the suffix
"XP30" are defined in [XPath 3.0].
In a FunctionCallP, the
EQName
used for the function name must have local part
doc
, id
, element-with-id
, or
key
, and must use the standard function namespace
either explicitly or implicitly.
Note:
As with XPath expressions, the pattern / union /*
can be parsed in two different ways, and the chosen interpretation
is to treat union
as an element name rather than as an
operator. The other interpretation can be achieved by writing
(/) union (/*)
The meaning of a pattern is defined formally as follows, where "if" is to be read as "if and only if".
If the pattern is a PredicatePattern PP, then it matches an item J if the XPath expression taking the same form as PP returns a non-empty sequence when evaluated with a singleton focus based on J.
Note:
The pattern .
, which is a
PredicatePattern
with an empty
PredicateList
, matches every item.
A predicate with the numeric value 1 (one) always matches, and a
predicate with any other numeric value never matches. Numeric
predicates in a PredicatePattern
are therefore not
useful, but are defined this way in the interests of consistency
with XPath.
Otherwise (the pattern is a PathPattern
), the
pattern is converted to an expression, called the equivalent
expression. The equivalent expression to a Pattern is the XPath
expression that takes the same lexical form as the
Pattern
as written, with the following adjustment:
If any PathExprP
in the Pattern
is a RelativePathExprP
, then the first
StepExprP
PS of this
RelativePathExprP
is adjusted to allow it to
match a parentless element, attribute, or namespace node. The
adjustment depends on the axis used in this step, whether it
appears explicitly or implicitly (according to the rules of
Section 3.3.5
Abbreviated Syntax XP30), and is made
as follows:
If the NodeTest
in PS is
document-node()
(optionally with arguments), and if no
explicit axis is specified, then the axis in step PS is
taken as self
rather than child
.
If PS uses the child axis (explicitly or implicitly),
and if the NodeTest
in PS is not
document-node()
(optionally with arguments), then the
axis in step PS is replaced by
child-or-top
, which is defined as follows. If the
context node is a parentless element, comment,
processing-instruction, or text node then the
child-or-top
axis selects the context node; otherwise
it selects the children of the context node. It is a forwards axis
whose principal node kind is element.
If PS uses the attribute axis (explicitly or
implicitly), then the axis in step PS is replaced by
attribute-or-top
, which is defined as follows. If the
context node is an attribute node with no parent, then the
attribute-or-top
axis selects the context node;
otherwise it selects the attributes of the context node. It is a
forwards axis whose principal node kind is attribute.
If PS uses the namespace axis (explicitly or
implicitly), then the axis in step PS is replaced
by namespace-or-top
, which is defined as follows. If
the context node is a namespace node with no parent, then the
namespace-or-top
axis selects the context node;
otherwise it selects the namespace nodes of the context node. It is
a forwards axis whose principal node kind is namespace.
The axes child-or-top
,
attribute-or-top
, and namespace-or-top
are introduced only for definitional purposes. They cannot be used
explicitly in a user-written pattern or expression.
Note:
The purpose of this adjustment is to ensure that a pattern such
as person
matches any element named
person
, even if it has no parent; and similarly, that
the pattern @width
matches any attribute named
width
, even a parentless attribute. The rule also
ensures that a pattern using a NodeTest
of the form
document-node(...)
matches a document node. The
pattern node()
will match any element, text node,
comment, or processing instruction, whether or not it has a parent.
For backwards compatibility reasons, the pattern
node()
, when used without an explicit axis, does not
match document nodes, attribute nodes, or namespace nodes. The
rules are also phrased to ensure that positional patterns of the
form para[1]
continue to count nodes relative to their
parent, if they have one. To match any node at all, XSLT 3.0
allows the pattern .[. instance of node()]
to be
used.
The meaning of the pattern is then defined in terms of the
semantics of the equivalent expression, denoted below as
EE
.
Specifically, an item N matches a pattern
P if the following applies, where EE
is the
equivalent expression to P:
N is a node, and the result of evaluating the
expression root(.)//(EE)
with a singleton focus based on N is
a sequence that includes the node N
If a pattern appears in an attribute of an element that is processed with XSLT 1.0 behavior (see 3.10 Backwards Compatible Processing), then the semantics of the pattern are defined on the basis that the equivalent XPath expression is evaluated with XPath 1.0 compatibility mode set to true.
The path pattern p
matches any p
element, because a p
element will always be present in
the result of evaluating the expression
root(.)//(child-or-top::p)
. Similarly, /
matches a document node, and only a document node, because the
result of the expression root(.)//(/)
returns
the root node of the tree containing the context node if and only
if it is a document node.
The path pattern node()
matches all nodes selected
by the expression root(.)//(child-or-top::node())
,
that is, all element, text, comment, and processing instruction
nodes, whether or not they have a parent. It does not match
attribute or namespace nodes because the expression does not select
nodes using the attribute or namespace axes. It does not match
document nodes because for backwards compatibility reasons the
child-or-top
axis does not match a document node.
The path pattern $V
matches all nodes selected by
the expression root(.)//($V)
, that is, all nodes in
the value of $V (which will typically be a global variable, though
when the pattern is used in contexts such as the xsl:number
or xsl:for-each-group
instructions, it can also be a local variable).
The path pattern doc('product.xml')//product
matches all nodes selected by the expression
root(.)//(doc('product.xml')//product)
, that is, all
product
elements in the document whose URI is
product.xml
.
Although the semantics of path patterns are specified formally
in terms of expression evaluation, it is possible to understand
pattern matching using a different model. A path pattern such as
book/chapter/section
can be examined from right to
left. A node will only match this pattern if it is a
section
element; and then, only if its parent is a
chapter
; and then, only if the parent of that
chapter
is a book
. When the pattern uses
the //
operator, one can still read it from right to
left, but this time testing the ancestors of a node rather than its
parent. For example appendix//section
matches every
section
element that has an ancestor
appendix
element.
The formal definition, however, is useful for understanding the
meaning of a pattern such as para[1]
. This matches any
node selected by the expression
root(.)//(child-or-top::para[1])
: that is, any
para
element that is the first para
child
of its parent, or a para
element that has no
parent.
Note:
An implementation, of course, may use any algorithm it wishes for evaluating patterns, so long as the result corresponds with the formal definition above. An implementation that followed the formal definition by evaluating the equivalent expression and then testing the membership of a specific node in the result would probably be very inefficient.
A dynamic error or type error that occurs during the evaluation of a pattern against a particular item has the effect that the item being tested is treated as not matching the pattern. The error does not cause the transformation to fail, and cannot be caught by a try/catch expression surrounding the instruction that causes the pattern to be evaluated.
Note:
The reason for this provision is that it is difficult for the stylesheet author to predict which predicates in a pattern will actually be evaluated. In the case of match patterns in template rules, it is not even possible to predict which patterns will be evaluated against a particular node.
There is a risk that ignoring errors in this way may make programming mistakes harder to debug. Implementations may mitigate this by providing warnings or other diagnostics when evaluation of a pattern triggers an error condition.
Static errors in patterns, including dynamic and type errors that are signaled statically as permitted by the specification, are reported in the normal way and cause the transformation to fail.
The string value of an attribute or text node in the stylesheet may in particular circumstances contain embedded expressions enclosed between curly brackets. Attributes and text nodes that use (or are permitted to use) this mechanism are referred to respectively as attribute value templates and text value templates..
[Definition: Collectively, attribute value templates and text value templates are referred to as value templates.]
A value template is a string consisting of an alternating
sequence of fixed parts and variable parts. A variable part
consists of an XPath expression enclosed in curly brackets
({}
). A fixed part may contain any characters, except
that a left curly bracket must be written
as {{
and a right curly bracket must be written as }}
.
Note:
An expression within a variable part may contain an unescaped curly bracket within a StringLiteralXP30 or within a comment.
Currently no XPath expression starts with an opening curly
bracket, so the use of {{
creates no ambiguity. If an
enclosed expression ends with a closing curly bracket, no
whitespace is required between this and the closing delimiter.
[ERR XTSE0350] It is a static error if an unescaped left curly bracket appears in a fixed part of a value template without a matching right curly bracket.
It is a static error if the string contained between matching curly brackets in a value template does not match the XPath production ExprXP30, or if it contains other XPath static errors. The error is signaled using the appropriate XPath error code.
[ERR XTSE0370] It is a static error if an unescaped right curly bracket occurs in a fixed part of a value template.
[Definition: The result of evaluating a value template is referred to as its effective value.] The effective value is the string obtained by concatenating the expansions of the fixed and variable parts:
The expansion of a fixed part is obtained by replacing any
double curly brackets ({{
or }}
) by the
corresponding single curly bracket.
The expansion of a variable part is obtained by evaluating the enclosed XPath expression and converting the resulting value to a string. This conversion is done using the rules given in 5.8.2 Constructing Simple Content.
Note:
This process can generate dynamic errors, for example if the sequence contains an element with a complex content type (which cannot be atomized).
In the case of an attribute value template, the effective value becomes the string value of the new attribute node. In the case of a text value template, the effective value becomes the string value of the new text node.
[Definition: In an attribute that is
designated as an attribute value template, such as an
attribute of a literal result element, an
expression can be used by surrounding the
expression with curly brackets ({}
), following the
general rules for value templates].
Curly brackets are not treated specially in an attribute value in an XSLT stylesheet unless the attribute is specifically designated as one that permits an attribute value template; in an element syntax summary, the value of such attributes is surrounded by curly brackets.
Note:
Not all attributes are designated as attribute value templates.
Attributes whose value is an expression or pattern, attributes of declaration elements and attributes that
refer to named XSLT objects are generally not designated as
attribute value templates (an exception is the format
attribute of xsl:result-document
).
Namespace declarations are not XDM attribute nodes and are
therefore never treated as attribute value templates.
If the element containing the attribute is processed with XSLT 1.0 behavior, then the rules for converting the value of the expression to a string (given in 5.7 Value Templates) are modified as follows. After atomizing the result of the expression, all items other than the first item in the resulting sequence are discarded, and the effective value is obtained by converting the first item in the sequence to a string. If the atomized sequence is empty, the result is a zero-length string.
Note:
The above rule applies to attribute value templates but not to text value templates, since the latter were not available in XSLT 1.0.
The following example creates an img
result element
from a photograph
element in the source; the value of
the src
and width
attributes are computed
using XPath expressions enclosed in attribute value templates:
<xsl:variable name="image-dir" select="'/images'"/> <xsl:template match="photograph"> <img src="{$image-dir}/{href}" width="{size/@width}"/> </xsl:template>
With this source
<photograph> <href>headquarters.jpg</href> <size width="300"/> </photograph>
the result would be
<img src="/images/headquarters.jpg" width="300"/>
The following example shows how the values in a sequence are output as a space-separated list. The following literal result element:
<temperature readings="{10.32, 5.50, 8.31}"/>
produces the output node:
<temperature readings="10.32 5.5 8.31"/>
Curly brackets are not recognized recursively inside expressions.
The standard attribute
[xsl:]expand-text
may appear on any element in the
stylesheet, and determines whether descendant text nodes of that
element are treated as text value templates. A text node in the
stylesheet is treated as a text value template if (a) it is part of
a sequence constructor, (b) there is
an ancestor element with an [xsl:]expand-text
attribute, and (c) on the innermost ancestor element that has such
an attribute, the value of the attribute is yes
. The
value of the attribute must be
yes
or no
.
This section describes how text nodes appearing in sequence
constructors are processed when the effective value is
yes
. Such text nodes are referred to as text value
templates.
[Definition: In a text node that is designated as a
text value template, expressions can be used by surrounding
each expression with curly brackets ({}
).]
The rules for text value templates are given in 5.7 Value Templates. A text node in a sequence constructor whose value is a text value template results in the construction of a text node in the result of the sequence constructor. The string value of that text node is obtained by computing the effective value of the value template.
Note:
The content of an xsl:text
element is not a sequence
constructor, and therefore cannot contain a text value
template.
The result of evaluating a text value template is a (possibly zero-length) text node. This text node becomes part of the result of the containing sequence constructor, and is thereafter handled exactly as if the value had appeared explicitly as a text node in the stylesheet.
The way in which the effective value is computed does not depend
on any separator
attribute on a containing xsl:value-of
or xsl:attribute
instruction.
The separator
attribute only affects how the text node
is combined with adjacent items in the result of the containing
sequence constructor.
Fixed parts consisting entirely of whitespace are significant and are handled in the same way as any other fixed part. This is different from the default treatment of "boundary space" in XQuery.
<xsl:variable name="id" select="'A123'"/> <xsl:variable name="step" select="5"/> <xsl:message expand-text="yes" >Processing id={$id}, step={$step}</xsl:message>
This will typically output the message text Processing
id=A123, step=5
.
<xsl:function name="f:sum" expand-text="yes" as="xs:integer"> <xsl:param name="x" as="xs:integer"/> <xsl:param name="y" as="xs:integer"/> {$x + $y} </xsl:function>
Note that although this is a very readable way of expressing the
computation performed by the function, the semantics are somewhat
complex, and this could mean that execution is inefficient. The
function computes the value of $x + $y
as an integer,
and then constructs a text node containing the string
representation of this integer (preceded and followed by
whitespace). Because the declared result type of the function is
xs:integer
, this text node is then atomized, giving an
xs:untypedAtomic
value, and the
xs:untypedAtomic
value is then cast to an
xs:integer
.
Note:
The main motivations for adding text value templates to the XSLT
language are firstly, to make it easier to construct parameterized
text in contexts such as xsl:value-of
and xsl:message
, and secondly, to
allow use of complex multi-line XPath expressions where maintaining
correct indentation is important for readability. The fact that XML
processors are required to normalize whitespace in attribute values
means that writing such expressions within a select
attribute is not ideal.
The facility is only present if enabled using the
[xsl:]expand-text
attribute. This is partly for
backwards compatibility, and partly to avoid creating difficulties
when constructing content that is rich in curly brackets, for
example Javascript code or CSS style sheets.
[Definition: A sequence constructor is a sequence of zero or more sibling nodes in the stylesheet that can be evaluated to return a sequence of nodes, atomic values, and function items. The way that the resulting sequence is used depends on the containing instruction.]
Many XSLT elements, and also literal result elements, are defined to take a sequence constructor as their content.
Four kinds of nodes may be encountered in a sequence constructor:
A Text node appearing in the stylesheet (if it has not been removed in the process of whitespace stripping: see 4.2 Stripping Whitespace from the Stylesheet) is processed as follows:
if the effective value of the standard attribute
[xsl:]expand-text
is no
, or in the
absence of this attribute, the text node in the stylesheet is
copied to create a new parentless text node in the result of the
sequence constructor.
Note:
For an xsl:text
element, the effective value of [xsl:]expand-text
is
always "no".
Otherwise (the effective value of [xsl:]expand-text
is yes
), the text node in the stylesheet is processed
as described in 5.7.2 Text Value
Templates.
A literal result element is evaluated to create a new parentless element node, having the same expanded QName as the literal result element: see 11.1 Literal Result Elements.
An XSLT instruction produces a sequence of zero, one,
or more items as its result. For most XSLT instructions, these
items are nodes, but some instructions (such as
xsl:sequence
and
xsl:copy-of
) can also
produce atomic values or function items. Several
instructions, such as xsl:element
, return a newly
constructed parentless node (which may have its own attributes,
namespaces, children, and other descendants). Other instructions,
such as xsl:if
, pass on the
items produced by their own nested sequence constructors. The
xsl:sequence
instruction may return atomic values, function items,
or existing nodes.
An extension instruction (see 23.2 Extension Instructions) also produces a sequence of items as its result.
The result of evaluating a sequence constructor is the sequence of items formed by concatenating the results of evaluating each of the nodes in the sequence constructor, retaining order.
There are several ways the result of a sequence constructor may be used.
The sequence may be bound to a variable or returned from a
stylesheet function, in which case it becomes available as a value
to be manipulated in arbitrary ways by XPath expressions. The
sequence is bound to a variable when the sequence constructor
appears within one of the elements xsl:variable
, xsl:param
, or xsl:with-param
, when this
instruction has an as
attribute. The sequence is
returned from a stylesheet function when the sequence constructor
appears within the xsl:function
element.
Note:
This will typically expose to the stylesheet elements,
attributes, and other nodes that have not yet been attached to a
parent node in a result tree. The semantics of XPath
expressions when applied to parentless nodes are well-defined;
however, such expressions should be used with care. For example,
the expression /
causes a type error if the root of
the tree containing the context node is not a document node.
Parentless attribute nodes require particular care because they have no namespace nodes associated with them. A parentless attribute node is not permitted to contain namespace-sensitive content (for example, a QName or an XPath expression) because there is no information enabling the prefix to be resolved to a namespace URI. Parentless attributes can be useful in an application (for example, they provide an alternative to the use of attribute sets: see 10.2 Named Attribute Sets) but they need to be handled with care.
The sequence may be returned as the result of the containing
element. This happens when the element containing the
sequence constructor is xsl:analyze-string
,
xsl:apply-imports
,
xsl:apply-templates
,
xsl:break
,
xsl:call-template
,
xsl:catch
,
xsl:choose
, xsl:fallback
, xsl:for-each
, xsl:for-each-group
,
xsl:fork
,
xsl:if
, xsl:iterate
, xsl:matching-substring
,
xsl:next-match
,
xsl:non-matching-substring
,
xsl:on-completion
,
xsl:otherwise
,
xsl:perform-sort
,
xsl:sequence
,
xsl:try
, or
xsl:when
.
The sequence may be used to construct the content of a new
element or document node. This happens when the sequence
constructor appears as the content of a literal result element, or of one
of the instructions xsl:copy
, xsl:element
, xsl:document
, xsl:result-document
,
xsl:assert
,
or xsl:message
. It also
happens when the sequence constructor is contained in one of the
elements xsl:variable
,
xsl:param
, or xsl:with-param
, when this
instruction has no as
attribute. For details, see
5.8.1 Constructing
Complex Content.
The sequence may be used to construct the string
value of an attribute node, text node, namespace node, comment
node, or processing instruction node. This happens when the
sequence constructor is contained in one of the elements xsl:attribute
, xsl:value-of
, xsl:namespace
, xsl:comment
, or xsl:processing-instruction
.
For details, see 5.8.2
Constructing Simple Content.
This section describes how the sequence obtained by evaluating a
sequence constructor may be used to
construct the children of a newly constructed document node, or the
children, attributes and namespaces of a newly constructed element
node. The sequence of items may be obtained by evaluating the
sequence constructor contained in an
instruction such as xsl:copy
, xsl:element
, xsl:document
, xsl:result-document
, or
a literal result element.
When constructing the content of an element, the
inherit-namespaces
attribute of the xsl:element
or xsl:copy
instruction, or the
xsl:inherit-namespaces
property of the literal result
element, determines whether namespace nodes are to be inherited.
The effect of this attribute is described in the rules that
follow.
The sequence is processed as follows (applying the rules in the order they are listed):
The containing instruction may generate attribute nodes and/or
namespace nodes, as specified in the rules for the individual
instruction. For example, these nodes may be produced by expanding
an [xsl:]use-attribute-sets
attribute, or by expanding
the attributes of a literal result
element. Any such nodes are prepended to the sequence produced
by evaluating the sequence constructor.
Any atomic value in the sequence is cast to a string.
Note:
Casting from xs:QName
or xs:NOTATION
to xs:string
always succeeds, because these values
retain a prefix for this purpose. However, there is no guarantee
that the prefix used will always be meaningful in the context where
the resulting string is used.
Any consecutive sequence of strings within the result sequence is converted to a single text node, whose string value contains the content of each of the strings in turn, with a single space (#x20) used as a separator between successive strings.
Any document node within the result sequence is replaced by a sequence containing each of its children, in document order.
Zero-length text nodes within the result sequence are removed.
Adjacent text nodes within the result sequence are merged into a single text node.
Invalid items in the result sequence are detected as follows.
[ERR XTDE0410] It is a dynamic error if the result sequence used to construct the content of an element node contains a namespace node or attribute node that is preceded in the sequence by a node that is neither a namespace node nor an attribute node.
[ERR XTDE0420] It is a dynamic error if the result sequence used to construct the content of a document node contains a namespace node or attribute node.
[ERR XTDE0430] It is a dynamic error if the result sequence contains two or more namespace nodes having the same name but different string values (that is, namespace nodes that map the same prefix to different namespace URIs).
[ERR XTDE0440] It is a dynamic error if the result sequence contains a namespace node with no name and the element node being constructed has a null namespace URI (that is, it is an error to define a default namespace when the element is in no namespace).
[ERR XTDE0450] It is a dynamic error if the result sequence contains a function item.
If the result sequence contains two or more namespace nodes with the same name (or no name) and the same string value (that is, two namespace nodes mapping the same prefix to the same namespace URI), then all but one of the duplicate nodes are discarded.
Note:
Since the order of namespace nodes is implementation-dependent, it is not significant which of the duplicates is retained.
If an attribute A in the result sequence has the same name as another attribute B that appears later in the result sequence, then attribute A is discarded from the result sequence. Before discarding attribute A, the processor may signal any type errors that would be signaled if attribute B were not present.
Each node in the resulting sequence is attached as a namespace,
attribute, or child of the newly constructed element or document
node. Conceptually this involves making a deep copy of the node; in
practice, however, copying the node will only be necessary if the
existing node can be referenced independently of the parent to
which it is being attached. When copying an element or processing
instruction node, its base URI property is changed to be the same
as that of its new parent, unless it has an xml:base
attribute (see [XML Base]) that overrides
this. If the copied element has an xml:base
attribute,
its base URI is the value of that attribute, resolved (if it is
relative) against the base URI of the new parent node.
If the newly constructed node is an element node, then namespace fixup is applied to this node, as described in 5.8.3 Namespace Fixup.
If the newly constructed node is an element node, and if namespaces are inherited, then each namespace node of the newly constructed element (including any produced as a result of the namespace fixup process) is copied to each descendant element of the newly constructed element, unless that element or an intermediate element already has a namespace node with the same name (or absence of a name) or that descendant element or an intermediate element is in no namespace and the namespace node has no name.
Consider the following stylesheet fragment:
<td> <xsl:attribute name="valign">top</xsl:attribute> <xsl:value-of select="@description"/> </td>
This fragment consists of a literal result element
td
, containing a sequence constructor that consists of
two instructions: xsl:attribute
and xsl:value-of
. The sequence
constructor is evaluated to produce a sequence of two nodes: a
parentless attribute node, and a parentless text node. The
td
instruction causes a td
element to be
created; the new attribute therefore becomes an attribute of the
new td
element, while the text node created by the
xsl:value-of
instruction becomes a child of the td
element (unless
it is zero-length, in which case it is discarded).
Consider the following stylesheet fragment:
<doc> <e><xsl:sequence select="1 to 5"/></e> <f> <xsl:for-each select="1 to 5"> <xsl:value-of select="."/> </xsl:for-each> </f> </doc>
This produces the output (when indented):
<doc> <e>1 2 3 4 5</e> <f>12345</f> </doc>
The difference between the two cases is that for the
e
element, the sequence constructor generates a
sequence of five atomic values, which are therefore separated by
spaces. For the f
element, the content is a sequence
of five text nodes, which are concatenated without space
separation.
It is important to be aware of the distinction between xsl:sequence
, which returns
the value of its select
expression unchanged, and
xsl:value-of
, which
constructs a text node.
The instructions xsl:attribute
, xsl:comment
, xsl:processing-instruction
,
xsl:namespace
, and
xsl:value-of
all
create nodes that cannot have children. Specifically, the xsl:attribute
instruction
creates an attribute node, xsl:comment
creates a comment
node, xsl:processing-instruction
creates a processing instruction node, xsl:namespace
creates a
namespace node, and xsl:value-of
creates a text
node. The string value of the new node is constructed using either
the select
attribute of the instruction, or the
sequence constructor that forms the
content of the instruction. The select
attribute
allows the content to be specified by means of an XPath expression,
while the sequence constructor allows it to be specified by means
of a sequence of XSLT instructions. The select
attribute or sequence constructor is evaluated to produce a result
sequence, and the string value of the new node is derived from
this result sequence according to the rules below.
These rules are also used to compute the effective value of an value template. In this case the sequence being processed is the result of evaluating an XPath expression enclosed between curly brackets, and the separator is a single space character.
Zero-length text nodes in the sequence are discarded.
Adjacent text nodes in the sequence are merged into a single text node.
The sequence is atomized (which may cause a dynamic error).
Every value in the atomized sequence is cast to a string.
The strings within the resulting sequence are concatenated, with
a (possibly zero-length) separator inserted between successive
strings. The default separator is a single space. In the case of
xsl:attribute
and
xsl:value-of
, a
different separator can be specified using the
separator
attribute of the instruction; it is
permissible for this to be a zero-length string, in which case the
strings are concatenated with no separator. In the case of xsl:comment
, xsl:processing-instruction
,
and xsl:namespace
,
and when expanding a value template, the
default separator cannot be changed.
In the case of xsl:processing-instruction
,
any leading spaces in the resulting string are removed.
The resulting string forms the string value of the new attribute, namespace, comment, processing-instruction, or text node.
Consider the following stylesheet fragment:
<doc> <xsl:attribute name="e" select="1 to 5"/> <xsl:attribute name="f"> <xsl:for-each select="1 to 5"> <xsl:value-of select="."/> </xsl:for-each> </xsl:attribute> <xsl:attribute name="g" expand-text="yes">{1 to 5}</xsl:attribute> </doc>
This produces the output:
<doc e="1 2 3 4 5" f="12345" g="1 2 3 4 5"/>
The difference between the three cases is as follows. For the
e
attribute, the sequence constructor generates a
sequence of five atomic values, which are therefore separated by
spaces. For the f
attribute, the content is supplied
as a sequence of five text nodes, which are concatenated without
space separation. For the g
attribute, the text value template constructs a text
node using the rules for constructing simple content, which insert
space separators between atomic values; the text node is then
atomized to form the value of the attribute.
Specifying separator=""
on the first xsl:attribute
instruction
would cause the attribute value to be e="12345"
. A
separator
attribute on the second xsl:attribute
instruction
would have no effect, since the separator only affects the way
adjacent atomic values are handled: separators are never inserted
between adjacent text nodes. A separator
on the
third xsl:attribute
instruction would also have no effect, because text value templates
are evaluated without regard to the containing
instruction.
Note:
If an attribute value template contains a sequence of fixed and
variable parts, no additional whitespace is inserted between the
expansions of the fixed and variable parts. For example, the
effective value of the attribute
a="chapters{4 to 6}"
is a="chapters4 5
6"
.
In a tree supplied to or constructed by an XSLT processor, the constraints relating to namespace nodes that are specified in [Data Model] must be satisfied. For example
If an element node has an expanded QName with a non-null namespace URI, then that element node must have at least one namespace node whose string value is the same as that namespace URI.
If an element node has an attribute node whose expanded QName has a non-null namespace URI, then the element must have at least one namespace node whose string value is the same as that namespace URI and whose name is non-empty.
Every element must have a namespace
node whose expanded QName has local-part
xml
and whose string value is
http://www.w3.org/XML/1998/namespace
. The namespace
prefix xml
must not be
associated with any other namespace URI, and the namespace URI
http://www.w3.org/XML/1998/namespace
must not be associated with any other prefix.
A namespace node must not have the
name xmlns
or the string value
http://www.w3.org/2000/xmlns/
.
[Definition: The rules for the individual XSLT instructions that construct a result tree (see 11 Creating Nodes and Sequences) prescribe some of the situations in which namespace nodes are written to the tree. These rules, however, are not sufficient to ensure that the prescribed constraints are always satisfied. The XSLT processor must therefore add additional namespace nodes to satisfy these constraints. This process is referred to as namespace fixup.]
The actual namespace nodes that are added to the tree by the namespace fixup process are implementation-dependent, provided firstly, that at the end of the process the above constraints must all be satisfied, and secondly, that a namespace node must not be added to the tree unless the namespace node is necessary either to satisfy these constraints, or to enable the tree to be serialized using the original namespace prefixes from the source document or stylesheet.
Namespace fixup must not result in an element having multiple namespace nodes with the same name.
Namespace fixup may, if necessary to
resolve conflicts, change the namespace prefix contained in the
QName value that holds the name of an element or attribute node.
This includes the option to add or remove a prefix. However,
namespace fixup must not change the
prefix component contained in a value of type xs:QName
or xs:NOTATION
that forms the typed value of an
element or attribute node.
Note:
Namespace fixup is not used to create namespace declarations for
xs:QName
or xs:NOTATION
values appearing
in the content of an element or attribute.
Where values acquire such types as the result of validation, namespace fixup does not come into play, because namespace fixup happens before validation: in this situation, it is the user's responsibility to ensure that the element being validated has the required namespace nodes to enable validation to succeed.
Where existing elements are copied along with their existing
type annotations (validation="preserve"
) the rules
require that existing namespace nodes are also copied, so that any
namespace-sensitive values remain valid.
Where existing attributes are copied along with their existing
type annotations, the rules of the XDM data model require that a
parentless attribute node cannot contain a namespace-sensitive
typed value; this means that it is an error to copy an attribute
using validation="preserve"
if it contains
namespace-sensitive content.
Namespace fixup is applied to every element that is constructed
using a literal result element, or one of
the instructions xsl:element
, xsl:copy
, or xsl:copy-of
. An implementation
is not required to perform namespace
fixup for elements in any source document, that is, for a document
in the initial input sequence, documents loaded using the document
, doc
FO30
or collection
FO30
function, documents supplied as the value of a stylesheet parameter, or documents
returned by an extension function or extension instruction.
Note:
A source document (an input document, a document returned by the
document
, doc
FO30
or collection
FO30
functions, a document returned by an extension function or
extension instruction, or a document supplied as a stylesheet
parameter) is required to satisfy the constraints described in
[Data Model], including the
constraints imposed by the namespace fixup process. The effect of
supplying a pseudo-document that does not meet these constraints is
implementation-dependent.
In an Infoset (see [XML Information
Set]) created from a document conforming to [Namespaces in XML], it will always be true that
if a parent element has an in-scope namespace with a non-empty
namespace prefix, then its child elements will also have an
in-scope namespace with the same namespace prefix, though possibly
with a different namespace URI. This constraint is removed in
[Namespaces in XML 1.1]. XSLT
3.0 supports the creation of result trees that do not
satisfy this constraint: the namespace fixup process does not add a
namespace node to an element merely because its parent node in the
result tree has such a namespace node.
However, the process of constructing the children of a new element,
which is described in 5.8.1 Constructing Complex
Content, does cause the namespaces of a parent element to
be inherited by its children unless this is prevented using
[xsl:]inherit-namespaces="no"
on the instruction that
creates the parent element.
Note:
This has implications on serialization, defined in [XSLT and XQuery
Serialization]. It means that it is possible to create
final result trees that cannot be
faithfully serialized as XML 1.0 documents. When such a result tree
is serialized as XML 1.0, namespace declarations written for the
parent element will be inherited by its child elements as if the
corresponding namespace nodes were present on the child element,
except in the case of the default namespace, which can be
undeclared using the construct xmlns=""
. When the same
result tree is serialized as XML 1.1, however, it is possible to
undeclare any namespace on the child element (for example,
xmlns:foo=""
) to prevent this inheritance taking
place.
[Definition: Within this specification, the term URI
Reference, unless otherwise stated, refers to a string in the
lexical space of the xs:anyURI
datatype as defined in
[XML Schema Part 2].] Note that this is a wider definition than
that in [RFC3986]: in particular, it is
designed to accommodate Internationalized Resource Identifiers
(IRIs) as described in [RFC3987], and thus
allows the use of non-ASCII characters without escaping.
URI References are used in XSLT with three main roles:
As namespace URIs
As collation URIs
As identifiers for resources such as stylesheet modules; these
resources are typically accessible using a protocol such as HTTP.
Examples of such identifiers are the URIs used in the
href
attributes of xsl:import
, xsl:include
, and xsl:result-document
.
The rules for namespace URIs are given in [Namespaces in XML] and [Namespaces in XML 1.1]. Those specifications deprecate the use of relative URI references as namespace URIs.
The rules for collation URIs are given in [Functions and Operators].
URI references used to identify external resources must conform
to the same rules as the locator attribute (href
)
defined in section 5.4 of [XLink]. If the URI
reference is relative, then it is resolved (unless otherwise
specified) against the base URI of the containing element node,
according to the rules of [RFC3986], after
first escaping all characters that need to be escaped to make it a
valid RFC3986 URI reference. (But a relative URI
reference in the href
attribute of
xsl:result-document
is
resolved against the Base Output URI.)
Other URI references appearing in an XSLT stylesheet document,
for example the system identifiers of external entities or the
value of the xml:base
attribute, must follow the rules
in their respective specifications.
The base URI of an element node in the stylesheet is determined
as defined in Section 5.2
base-uri Accessor DM30. Some
implementations may allow the output of the static analysis phase
of stylesheet processing (a "compiled stylesheet") to be evaluated
in a different location from that where static analysis took place.
Furthermore, stylesheet authors may in such cases which to avoid
exposing the location of resources that are private to the
development environment. If the base URI of an element in the
stylesheet is defined by an absolute URI appearing in an
xml:base
attribute within the stylesheet, this value
must be used as the static base URI. In
other cases where processing depends on the static base URI of a
stylesheet module, implementations may
use different values for the static base URI during static analysis
and during dynamic evaluation (for example, an implementation
may use different base URIs for resolving
xsl:import
module
references and for resolving a relative reference used as an
argument to the doc
FO30
function). In such cases an implementation must document how the static base URI is computed for
each situation in which it is required.
Template rules define the processing that can be applied to items that match a particular pattern.
<!-- Category: declaration
-->
<xsl:template
match? = pattern
name? = eqname
priority? = decimal
mode? = tokens
as? = sequence-type
visibility? = "public" | "private" | "final" |
"abstract" >
<!-- Content: (xsl:context-item?, xsl:param*, sequence-constructor)
-->
</xsl:template>
[Definition: An xsl:template
declaration
defines a template, which contains a sequence constructor ; this
sequence constructor is evaluated to determine the result of the
template. A template can serve either as a template
rule, invoked by matching items against a
pattern,
or as a named template, invoked explicitly by
name. It is also possible for the same template to serve in both
capacities.]
[ERR XTSE0500] An xsl:template
element
must have either a match
attribute or a name
attribute, or both. An xsl:template
element that has
no match
attribute must have
no mode
attribute and no priority
attribute. An xsl:template
element that has
no name
attribute must have
no visibility
attribute.
If an xsl:template
element has a match
attribute, then it is a template
rule. If it has a name
attribute, then it is a
named template.
A template may be invoked in a number of ways,
depending on whether it is a template rule, a named
template, or both. The result of invoking the template is the
result of evaluating the sequence constructor
contained in the xsl:template
element (see
5.8 Sequence
Constructors).
For details of the optional xsl:context-item
child
element, see 6.7.2
Declaring the context item for a template.
If an as
attribute of the xsl:template
element is
present, the as
attribute defines the required type of
the result. The result of evaluating the sequence constructor is then
converted to the required type using the function conversion rules. If
no as
attribute is specified, the default value is
item()*
, which permits any value. No conversion then
takes place.
[ERR XTTE0505] It is a type error if the result of evaluating the sequence constructor cannot be converted to the required type.
If the visibility
attribute is present with the
value abstract
then (a) the sequence constructor defining the
template body must be empty: that is, the
only permitted children are xsl:context-item
and
xsl:param
, and (b) there
must be no match
attribute.
If the parent of the xsl:template
element is an
xsl:override
element,
then there must be a name
attribute and no
match
attribute, and the package that is the target of the
containing xsl:use-package
element
must contain among its components a named template whose
symbolic identifier is the same as
this named template, and which has a compatible signature.
This section describes template rules. Named templates are described in 10.1 Named Templates.
A template rule is specified using the
xsl:template
element
with a match
attribute. The match
attribute is a Pattern
that identifies the items to which the rule applies.
The result of applying the template rule is the result of
evaluating the sequence constructor contained in the xsl:template
element, with the
matching item used as the context
item.
For example, an XML document might contain:
This is an <emph>important</emph> point.
The following template rule matches emph
elements and produces a fo:wrapper
element with a
font-weight
property of bold
.
<xsl:template match="emph"> <fo:wrapper font-weight="bold" xmlns:fo="http://www.w3.org/1999/XSL/Format"> <xsl:apply-templates/> </fo:wrapper> </xsl:template>
A template rule is evaluated when an xsl:apply-templates
instruction selects an item that matches the pattern
specified in the match
attribute. The xsl:apply-templates
instruction is described in the next section. If several template
rules match a selected item, only one of them is
evaluated, as described in 6.4 Conflict
Resolution for Template Rules.
<!-- Category: instruction
-->
<xsl:apply-templates
select? = expression
mode? = token >
<!-- Content: (xsl:sort
| xsl:with-param)* -->
</xsl:apply-templates>
The xsl:apply-templates
instruction takes as input a sequence of items
(typically nodes in a source tree), and produces as output a
sequence of items; these will often be nodes to be added to a
result tree.
If the instruction has one or more xsl:sort
children, then the input
sequence is sorted as described in 13
Sorting. The result of this sort is referred to below as
the sorted sequence; if there are no xsl:sort
elements, then the sorted
sequence is the same as the input sequence.
Each item in the input sequence is processed by
finding a template rule whose pattern matches that
item. If there is more than one such template rule,
the best among them is chosen, using rules described in 6.4 Conflict Resolution for Template Rules.
If there is no template rule whose pattern matches the
item, a built-in template rule is used (see 6.8 Built-in Template Rules). The
chosen template rule is evaluated. The rule that matches the
Nth item in the sorted sequence is
evaluated with that item as the context
item, with N as the context position,
and with the length of the sorted sequence as the context
size. Each template rule that is evaluated produces a sequence
of items as its result. The resulting sequences (one for each
item in the sorted sequence) are then concatenated, to
form a single sequence. They are concatenated retaining the order
of the items in the sorted sequence. The final
concatenated sequence forms the result of the xsl:apply-templates
instruction.
Suppose the source document is as follows:
<message>Proceed <emph>at once</emph> to the exit!</message>
This can be processed using the two template rules shown below.
<xsl:template match="message"> <p> <xsl:apply-templates select="child::node()"/> </p> </xsl:template> <xsl:template match="emph"> <b> <xsl:apply-templates select="child::node()"/> </b> </xsl:template>
There is no template rule for the document node; the built-in
template rule for this node will cause the message
element to be processed. The template rule for the
message
element causes a p
element to be
written to the result tree; the contents of this
p
element are constructed as the result of the
xsl:apply-templates
instruction. This instruction selects the three child nodes of the
message
element (a text node containing the value
"Proceed
", an emph
element node, and a
text node containing the value " to the exit!
"). The
two text nodes are processed using the built-in template rule for
text nodes, which returns a copy of the text node. The
emph
element is processed using the explicit template
rule that specifies match="emph"
.
When the emph
element is processed, this template
rule constructs a b
element. The contents of the
b
element are constructed by means of another xsl:apply-templates
instruction, which in this case selects a single node (the text
node containing the value "at once
"). This is again
processed using the built-in template rule for text nodes, which
returns a copy of the text node.
The final result of the match="message"
template
rule thus consists of a p
element node with three
children: a text node containing the value "Proceed
",
a b
element that is the parent of a text node
containing the value "at once
", and a text node
containing the value " to the exit!
". This result
tree might be serialized as:
<p>Proceed <b>at once</b> to the exit!</p>
The default value of the select
attribute is
child::node()
, which causes all the children of the
context node to be processed.
[ERR XTTE0510] It is a type error if an xsl:apply-templates
instruction with no select
attribute is evaluated when
the context item is not a node.
A select
attribute can be used to process
items selected by an expression instead of processing
all children. The value of the select
attribute is an
expression.
The following example processes all of the
given-name
children of the author
elements that are children of author-group
:
<xsl:template match="author-group"> <fo:wrapper> <xsl:apply-templates select="author/given-name"/> </fo:wrapper> </xsl:template>
It is also possible to process elements that are not descendants
of the context node. This example assumes that a
department
element has group
children and
employee
descendants. It finds an employee's
department and then processes the group
children of
the department
.
<xsl:template match="employee"> <fo:block> Employee <xsl:apply-templates select="name"/> belongs to group <xsl:apply-templates select="ancestor::department/group"/> </fo:block> </xsl:template>
It is possible to write template rules that are matched according to the schema-defined type of an element or attribute. The following example applies different formatting to the children of an element depending on their type:
<xsl:template match="product"> <table> <xsl:apply-templates select="*"/> </table> </xsl:template> <xsl:template match="product/*" priority="3"> <tr> <td><xsl:value-of select="name()"/></td> <td><xsl:next-match/></td> </tr> </xsl:template> <xsl:template match="product/element(*, xs:decimal) | product/element(*, xs:double)" priority="2"> <xsl:value-of select="format-number(xs:double(.), '#,###0.00')"/> </xsl:template> <xsl:template match="product/element(*, xs:date)" priority="2"> <xsl:value-of select="format-date(., '[Mn] [D], [Y]')"/> </xsl:template> <xsl:template match="product/*" priority="1.5"> <xsl:value-of select="."/> </xsl:template>
The xsl:next-match
instruction
is described in 6.9 Overriding Template
Rules.
Multiple xsl:apply-templates
elements can be used within a single template to do simple
reordering. The following example creates two HTML tables. The
first table is filled with domestic sales while the second table is
filled with foreign sales.
<xsl:template match="product"> <table> <xsl:apply-templates select="sales/domestic"/> </table> <table> <xsl:apply-templates select="sales/foreign"/> </table> </xsl:template>
It is possible for there to be two matching descendants where one is a descendant of the other. This case is not treated specially: both descendants will be processed as usual.
For example, given a source document
<doc><div><div></div></div></doc>
the rule
<xsl:template match="doc"> <xsl:apply-templates select=".//div"/> </xsl:template>
will process both the outer div
and inner
div
elements.
This means that if the template rule for the div
element processes its own children, then these grandchildren will
be processed more than once, which is probably not what is
required. The solution is to process one level at a time in a
recursive descent, by using select="div"
in place of
select=".//div"
This example reads a non-XML text file and processes it line-by-line, applying different template rules based on the content of each line:
<xsl:template name="main"> <xsl:apply-templates select="unparsed-text-lines('input.txt')"/> </xsl:template> <xsl:template match=".[starts-with(., '==')]"> <h2><xsl:value-of select="replace(., '==', '')"/></h2> </xsl:template> <xsl:template match=".[starts-with(., '::')]"> <p class="indent"><xsl:value-of select="replace(., '::', '')"/></p> </xsl:template> <xsl:template match="."> <p class="body"><xsl:value-of select="."/></p> </xsl:template>
Note:
The xsl:apply-templates
instruction is most commonly used to process nodes that are
descendants of the context node. Such use of xsl:apply-templates
cannot result in non-terminating processing loops. However, when
xsl:apply-templates
is
used to process elements that are not descendants of the context
node, the possibility arises of non-terminating loops. For
example,
<xsl:template match="foo"> <xsl:apply-templates select="."/> </xsl:template>
Implementations may be able to detect such loops in some cases, but the possibility exists that a stylesheet may enter a non-terminating loop that an implementation is unable to detect. This may present a denial of service security risk.
It is possible for a selected item to match more than one template rule with a given mode M. When this happens, only one template rule is evaluated for the item. The template rule to be used is determined as follows:
First, only the matching template rule or rules with the highest import precedence are considered. Other matching template rules with lower precedence are eliminated from consideration.
Next, of the remaining matching rules, only those with the highest priority are considered. Other matching template rules with lower priority are eliminated from consideration.
[Definition: The
priority of a template rule is specified by the
priority
attribute on the xsl:template
declaration. If
no priority is specified explicitly for a template rule, its
default priority is used, as defined in
6.5 Default Priority for Template
Rules.]
[ERR XTSE0530] The value of the
priority
attribute must
conform to the rules for the xs:decimal
type defined
in [XML Schema Part 2]. Negative values
are permitted.
If this leaves more than one matching template rule, then:
If the mode
M has an xsl:mode
declaration, and the
attribute value on-multiple-match="fail"
is specified
in the mode declaration, a dynamic error is signaled. The error is
treated as occurring in the xsl:apply-templates
instruction, and can be recovered by wrapping that instruction in
an xsl:try
instruction.
[ERR XTDE0540] It is a dynamic error if the
conflict resolution algorithm for template rules leaves more than
one matching template rule when the declaration of the
relevant mode
has an on-multiple-match
attribute with the value
fail
.
Otherwise, of the matching template rules that remain, the one that occurs last in declaration order is used.
Note:
This was a recoverable error in XSLT 2.0, meaning that it was
implementation-defined whether the error was signaled, or whether
the ambiguity was resolved by taking the last matching rule in
declaration order. In XSLT 3.0 this situation is not an error
unless the attribute value on-multiple-match="fail"
is
specified in the mode declaration. It is also possible to request
warnings when this condition arises, by means of the attribute
warning-on-multiple-match="yes"
.
[Definition: If no priority
attribute is
specified on an xsl:template
element, a
default priority is computed, based on the syntax of the
pattern
supplied in the match
attribute.] The rules are as follows.
If the top-level pattern is a ParenthesizedExprP then the outer parentheses are effectively stripped; these rules are applied recursively to the UnionExprP contained in the ParenthesizedExprP.
If the top-level pattern is a UnionExprP consisting of
multiple alternatives separated by |
or
union
, then the template rule is treated equivalently
to a set of template rules, one for each alternative. These
template rules are adjacent to each other in declaration order, and
the declaration order within this set of template rules (which
affects the result of xsl:next-match
if the
alternatives have the same default priority) is the order of
alternatives in the UnionExprP.
Note:
The splitting of a template rule into multiple rules occurs only
if there is no explicit priority
attribute.
If the top-level pattern is a IntersectExceptExprP
containing two or more PathExprP operands separated
by intersect
or except
operators, then
the priority of the pattern is that of the first PathExprP.
If the pattern is a PredicatePattern then
its priority is 1 (one), unless the PredicateList
is
empty, in which case the priority is −1 (minus one).
If the pattern is a PathExprP taking the form
/
, then the priority is −0.5 (minus 0.5).
If the pattern is a PathExprP taking the form of
an EQName
optionally preceded by a ForwardAxisP or has the
form processing-instruction(
StringLiteralXP30
)
or processing-instruction(
NCNameNames
)
optionally preceded by a ForwardAxisP, then the
priority is 0 (zero).
If the pattern is a PathExprP taking the form of
an ElementTestXP30
or AttributeTestXP30,
optionally preceded by a ForwardAxisP, then the
priority is as shown in the table below. In this table, the symbols
E, A, and T represent an arbitrary
element name, attribute name, and type name respectively, while the
symbol *
represents itself. The presence or absence of
the symbol ?
following a type name does not affect the
priority.
| Format | Priority | Notes |
|---|---|---|
element() |
−0.5 | (equivalent to * ) |
element(*) |
−0.5 | (equivalent to * ) |
attribute() |
−0.5 | (equivalent to @* ) |
attribute(*) |
−0.5 | (equivalent to @* ) |
element(E) |
0 | (equivalent to E) |
element(*,T) |
0 | (matches by type only) |
attribute(A) |
0 | (equivalent to @A ) |
attribute(*,T) |
0 | (matches by type only) |
element(E,T) |
0.25 | (matches by name and type) |
schema-element(E) |
0.25 | (matches by substitution group and type) |
attribute(A,T) |
0.25 | (matches by name and type) |
schema-attribute(A) |
0.25 | (matches by name and type) |
If the pattern is a PathExprP taking the form of a DocumentTestXP30, then if it includes no ElementTestXP30 or SchemaElementTestXP30 the priority is −0.5. If it does include an ElementTestXP30 or SchemaElementTestXP30, then the priority is the same as the priority of that ElementTestXP30 or SchemaElementTestXP30, computed according to the table above.
If the pattern is a PathExprP taking the form of
an NCNameNames:*
or *:
NCNameNames,
optionally preceded by a ForwardAxisP, then the
priority is −0.25.
If the pattern is a PathExprP taking the form of any other NodeTestXP30, optionally preceded by a ForwardAxisP, then the priority is −0.5.
In all other cases, the priority is +0.5.
Note:
In many cases this means that highly selective patterns have higher priority than less selective patterns. The most common kind of pattern (a pattern that tests for a node of a particular kind, with a particular expanded QName or a particular type) has priority 0. The next less specific kind of pattern (a pattern that tests for a node of a particular kind and an expanded QName with a particular namespace URI) has priority −0.25. Patterns less specific than this (patterns that just test for nodes of a given kind) have priority −0.5. Patterns that specify both the name and the required type have a priority of +0.25, putting them above patterns that only specify the name or the type. Patterns more specific than this, for example patterns that include predicates or that specify the ancestry of the required node, have priority 0.5.
However, it is not invariably true that a more selective pattern
has higher priority than a less selective pattern. For example, the
priority of the pattern node()[self::*]
is higher than
that of the pattern salary
. Similarly, the patterns
attribute(*, xs:decimal)
and attribute(*,
xs:short)
have the same priority, despite the fact that the
latter pattern matches a subset of the nodes matched by the former.
Therefore, to achieve clarity in a stylesheet it is good practice
to allocate explicit priorities.
[Definition: Modes allow a node
in a source tree to be processed multiple times,
each time producing a different result. They also allow different
sets of template rules to be active when processing
different trees, for example when processing documents loaded using
the document
function
(see 20.1 fn:document) or when
processing temporary trees.]
Modes are identified by an expanded QName; in addition
to any named modes, there is always one unnamed mode available.
Whether a mode is named or unnamed, its properties may be defined in an xsl:mode
declaration. If a mode
name is used (for example in an xsl:template
declaration or an
xsl:apply-templates
instruction) and no declaration of that mode appears in the
stylesheet, the mode is implicitly declared with default
properties.
<!-- Category: declaration -->
<xsl:mode
name? = eqname
streamable? = "yes" | "no"
on-no-match? = "deep-copy" | "shallow-copy" |
"deep-skip" | "shallow-skip" | "text-only-copy" | "fail"
on-multiple-match? = "use-last" | "fail"
warning-on-no-match? = "yes" | "no"
warning-on-multiple-match? = "yes" | "no"
typed? = "yes" | "no" | "strict" | "lax" |
"unspecified"
visibility? = "public" | "private" |
"final" >
<!-- Content: (xsl:context-item?) -->
</xsl:mode>
[Definition: There is always an unnamed mode
available. The unnamed mode is the default mode used when no
mode
attribute is specified on an xsl:apply-templates
instruction or xsl:template
declaration,
unless a different default mode has been specified using the
[xsl:]default-mode
attribute of a containing
element.]
Every mode other than the unnamed mode is identified by an expanded QName.
A stylesheet may contain multiple xsl:mode
declarations and may
include or import stylesheet modules that also
contain xsl:mode
declarations. The name of an xsl:mode
declaration is the value
of its name
attribute, if any.
[Definition: All the xsl:mode
declarations in a
stylesheet that share the same name are grouped into a named
mode definition; those that have no name are grouped into a
single unnamed mode definition.]
If a stylesheet does not contain a declaration of
the unnamed mode, a declaration is implied equivalent to an
xsl:mode
element with the
single attribute initial="yes"
. Similarly, if there is
a mode that is named in an xsl:template
or xsl:apply-templates
element, or in the [xsl:]default-mode
attribute
of a containing element, and the stylesheet does not
contain a declaration of that mode, then a declaration is implied
comprising an xsl:mode
element with a name
attribute plus the attribute
initial="yes"
.
The contained xsl:context-item
element,
if present, is used to declare requirements for the initial context item when this mode
is used as the initial mode. Therefore, there must be no
xsl:context-item
child if initial="no"
is specified.
[ERR XTSE0542] It is a static error if an
xsl:mode
declaration
specifying initial="no"
contains an xsl:context-item
element.
The attributes of the xsl:mode
declaration establish
values for a number of properties of a mode. The allowed values and
meanings of the attributes are given in the following table.
| Attribute | Values | Meaning |
|---|---|---|
| name | A EQName | Specifies the name of the mode. If
omitted, this xsl:mode
declaration provides properties of the unnamed mode |
| streamable | yes or no
(default no ) |
Determines whether template rules in
this mode are to be capable of being processed using streaming. If
the value yes is specified, then the body of any
template rule that uses this mode
must conform to the rules for streamable
templates given in 6.6.3
Streamable Templates. |
| on-no-match | One of deep-copy ,
shallow-copy , deep-skip ,
shallow-skip , text-only-copy or
fail (default text-only-copy ) |
Determines selection of the built-in
template rules that are used to process a
node when an xsl:apply-templates
instruction selects a node that does not match any user-written
template rule in the stylesheet. For details,
see 6.8 Built-in Template
Rules. |
| on-multiple-match | One of fail or
use-last (default use-last ) |
Defines the action to be taken when
xsl:apply-templates is
used in this mode and more than one user-written template
rule is available to process the node, having the same
import precedence and priority. The
value fail indicates that it is a dynamic
error if more than one template rule matches the node. The
value use-last indicates that the situation is not to
be treated as an error (the last template in declaration order is the one that is
used). |
| warning-on-no-match | One of yes or
no . The default is implementation-defined |
Requests the processor to output (or
not to output) a warning message in the case where an xsl:apply-templates
instruction selects a node that matches no template rule. The form
and destination of such warnings is implementation-defined. The
processor may ignore this attribute, for
example if the environment provides no suitable means of
communicating with the user. |
| warning-on-multiple-match | One of yes or
no . The default is implementation-defined |
Requests the processor to output a
warning message in the case where an xsl:apply-templates
instruction selects a node that matches multiple template rules
having the same import precedence and priority. The
form and destination of such warnings is implementation-defined. The
processor may ignore this attribute, for
example if the environment provides no suitable means of
communicating with the user. |
| typed | One of yes ,
no , strict , lax , or
unspecified . The default is
unspecified . |
Informs the processor
whether the nodes to be processed by template rules in this mode
are to be typed or untyped. If the value yes is
specified, then all nodes processed in this mode must be typed (a dynamic error occurs if xsl:apply-templates in
this mode selects an element or attribute whose type annotation is
xs:untyped or xs:untypedAtomic ). If the
value no is specified, then all nodes processed in
this mode must be untyped (a dynamic
error occurs if xsl:apply-templates in
this mode selects an element or attribute whose type annotation is
anything other than xs:untyped or
xs:untypedAtomic ). The value strict
is equivalent to yes , with the additional provision
that within the match pattern of every template rule in this mode,
any NameTest used as an AbbrevForwardStep
(with no preceding "@") in the ForwardStepP of the
first StepExprP of a RelativePathExprP is
interpreted as match="schema-element(product)" , while
match="product/code" is interpreted as
match="schema-element(product)/code" . The value
lax is equivalent to strict , except that
the interpretation of a NameTest as a
SchemaElementTest occurs only if it matches the name
of a global element declaration in the in-scope schema
declarations. The value unspecified is equivalent to
omitting the attribute, and places no constraints on whether the
nodes to be processed in this mode are typed or
untyped. |
| visibility | One of public ,
private , or final . The default is
private . |
See <IP_ADDRESS> Visibility of
Declarations. A mode is not eligible to be used as
the initial mode if its visibility is
private . |
[ERR XTTE3100] It is a type error if an xsl:apply-templates
instruction in a particular mode
selects an element or
attribute whose type is xs:untyped
or
xs:untypedAtomic
when the typed
attribute
of that mode specifies the value yes
,
strict
, or lax
.
[ERR XTTE3110] It is a type error if an xsl:apply-templates
instruction in a particular mode
selects an element or
attribute whose type is anything other than xs:untyped
or xs:untypedAtomic
when the typed
attribute of that mode specifies the value no
.
[Definition: A streamable mode is a mode that is declared in an
xsl:mode
declaration with
the attribute streamable="yes"
.]
For any named mode, the effective value of each attribute is taken
from an xsl:mode
declaration that has a matching name in its name
attribute, and that specifies an explicit value for the required
attribute. If there is more than one such declaration, the one with
highest import precedence is used.
For the unnamed mode, the effective value of each
attribute is taken from an xsl:mode
declaration that has no
name
attribute, and that specifies an explicit value
for the required attribute. If there is no such declaration, the
default value of the attribute is used. If there is more than one
such declaration, the one with highest import precedence
is used.
The above rules apply both to the attributes (other than
name
) of the xsl:mode
element itself, and to
the attributes of the contained xsl:context-item
element
if present.
[ERR XTSE0545] It is a static error if a named
or unnamed mode
contains two conflicting values for the same attribute in different
xsl:mode
declarations
having the same import precedence, unless there is
another definition of the same attribute with higher import
precedence. The attributes in question are the attributes other
than name
on the xsl:mode
element, and the
as
attribute on the contained xsl:context-item
element
if present.
If the initial context item supplied to a stylesheet is a streamed document node, then it is not permitted for the values of global variables to be dependent on the context item in a way that requires reading of the input stream. This constraint is enforced by the following static rule:
[ERR XTSE0548] It is a static error if there
is both (a) a mode definition in the stylesheet
that has the effective attribute values
streamable="yes"
and initial="yes"
, and
(b) a global variable in the stylesheet
whose initializing expression is not motionless with respect to its
context item, as defined in 19
Streamability.
A template rule is applicable to one or more
modes. The modes to which it is applicable are defined by the
mode
attribute of the xsl:template
element. If the
attribute is omitted, then the template rule is applicable to the
default mode specified in the
[xsl:]default-mode
attribute of the innermost
containing element that has such an attribute, which in turn
defaults to the unnamed mode. If the
mode
attribute is present, then its value must be a non-empty whitespace-separated list of
tokens, each of which defines a mode to which the template rule is
applicable. Each token must be one of the
following:
an EQName, which is expanded as described in 5.1 Qualified Names to define the name of the mode
the token #default
, to indicate that the template
rule is applicable to the default mode that would apply if
the mode
attribute were absent
the token #unnamed
, to indicate that the template
rule is applicable to the unnamed mode
the token #all
, to indicate that the template rule
is applicable to all modes (specifically, to the
unnamed mode and to every mode that is named
explicitly or implicitly in an xsl:apply-templates
instruction anywhere in the stylesheet).
[ERR XTSE0550] It is a static error if the
list of modes is empty, if the same token is included more than
once in the list, if the list contains an invalid token, or if the
token #all
appears together with any other value.
The xsl:apply-templates
element also has an optional mode
attribute. The value
of this attribute must be one of the
following:
an EQName, which is expanded as described in 5.1 Qualified Names to define the name of a mode
the token #default
, to indicate that the default
mode for the stylesheet module is to be
used
the token #unnamed
, to indicate that the unnamed
mode is to be used
the token #current
, to indicate that the current
mode is to be used
If the attribute is omitted, the default mode for the stylesheet module is used.
When searching for a template rule to process each
item selected by the xsl:apply-templates
instruction, only those template rules that are applicable to the
selected mode are considered.
[Definition: At
any point in the processing of a stylesheet, there is a current
mode. When the transformation is initiated, the current mode is
the initial mode, as described in
2.3 Initiating a Transformation.
Whenever an xsl:apply-templates
instruction is evaluated, the current mode becomes the mode
selected by this instruction.] When
a non-contextual function
call is made, the current mode is set to the unnamed
mode. While evaluating global variables and parameters, and the
sequence constructor contained in xsl:key
or xsl:sort
, the current mode is set
to the unnamed mode. No other instruction changes the current mode.
The current mode while evaluating an attribute set is the
same as the current mode of the caller. On completion of the
xsl:apply-templates
instruction, or on return from a stylesheet function call, the
current mode reverts to its previous value. The current mode is
used when an xsl:apply-templates
instruction uses the syntax mode="#current"
; it is
also used by the xsl:apply-imports
and
xsl:next-match
instructions (see 6.9 Overriding
Template Rules).
A template is guaranteed-streamable if and only if all the following conditions are satisfied:
The pattern defined in the match
attribute of the xsl:template
element
is a motionless pattern as defined in 19.8.9 Classifying Patterns.
The sequence constructor contained in
the body of the xsl:template
element is
grounded, as defined in 19 Streamability.
Every expression and contained sequence constructor in a contained
xsl:param
element (the
construct that provides the default value of the parameter)
is motionless.
Specifying streamable="yes"
on an xsl:mode
declaration declares an
intent that every template rule that includes that mode (explicitly
or implicitly, including by specifying #all
), should
be guaranteed streamable according to these criteria. The
consequences of declaring the mode to be streamable when there is
such a template rule that is not guaranteed streamable depend on
the conformance level of the processor, and are explained in
19.10 Streamability
Guarantees.
Processing of a document using streamable templates may be
initiated using code such as the following, where S
is
a mode declared with streamable="yes"
:
<xsl:stream href="bigdoc.xml"> <xsl:apply-templates mode="S"/> </xsl:stream>
Alternatively, streamed processing may be initiated by invoking the transformation with an initial mode declared as streamable, while supplying the initial context item (in an implementation-defined way) as a streamed document.
Note:
Invoking a streamable template using the construct
<xsl:apply-templates
select="doc('bigdoc.xml')"/>
does not ensure streamed
processing. As always, processors may use streamed processing if
they are able to do so, but when the doc
FO30
or document
functions are
used, processors are obliged to ensure that the results are
deterministic, which may be difficult to reconcile with streaming
(if the same document is read twice, the results must be
identical). The use of xsl:stream
does not offer the
same guarantees of determinism.
For an example of processing a collection of documents by use of
the function
uri-collection
FO30 in
conjunction with xsl:stream
, see 18.1.2 Examples of xsl:stream .
The xsl:context-item
element
is used for two purposes:
As a child of xsl:mode
,
it declares the required type of the initial context item that is
supplied by the calling application when this mode is used as the
initial mode.
As a child of xsl:template
, it declares the
required type of the context item when the containing template is
called using an xsl:call-template
instruction.
<xsl:context-item
as? = sequence-type
use? = "required" | "optional" |
"prohibited" />
If the as
attribute is present then its value must
be an ItemTypeXP30.
If the attribute is omitted this is equivalent to specifying
as="item()"
.
A type error is signaled if the supplied context
item does not match its required type. The error code is the same
as for xsl:param
:
[see ERR
XTTE0590].
This section applies when xsl:context-item
is used
to declare the initial context item for a mode.
When the xsl:context-item
element
appears as a child of xsl:mode
, the only permitted value
for the use
attribute is required
,
indicating that an initial context item must be supplied by the calling application when this
mode is selected as the initial mode. The context item that is
supplied will be converted to the declared type using the function conversion rules. This
may result in a type error if the conversion is not
possible.
Note:
If the ItemType
is one that can only be satisfied
by a schema-validated input document, for example
as="schema-element(invoice)"
, the processor may interpret
this as a request to apply schema validation to the input.
Similarly, if the KindTest
indicates that an element
node is required, the processor may interpret this as a request to
supply the document element rather than the document node of a
supplied input document.
If there is no xsl:context-item
element
for an xsl:mode
that
specifies initial="yes"
, this is equivalent to
specifying <xsl:context-item as="item()"/>
The following example declares two modes, both of which have
initial="yes"
meaning that they can be used as entry
points to the stylesheet. In the first mode, named
invoice
, the required context item is a
schema-validated invoice
element. In the second mode,
named po
, the required context item is a
schema-validated purchase-order
element. A third mode,
format-address
is declared with
initial="no"
so it cannot be used as an initial entry
point; this mode might be used when processing content that is
common to invoices and purchase orders.
<xsl:mode name="invoice" initial="yes" on-no-match="deep-copy"> <xsl:context-item as="schema-element(invoice)"/> </xsl:mode> <xsl:mode name="po" initial="yes" on-no-match="deep-copy"> <xsl:context-item as="schema-element(purchase-order)"/> </xsl:mode> <xsl:mode name="format-address" initial="no"/>
The xsl:context-item
element
can appear as a child of xsl:template
to define the
type of the context item passed to a named template. If the named
template is also the initial template, then this
constrains the initial context item for the
transformation as a whole.
If an xsl:context-item
element
is present as the first child element of xsl:template
, it defines
whether the template requires a context item to be supplied, and if
so, what the type of the context item must be. If this template is
the initial template, then this has the
effect of placing constraints on the initial context item for the
transformation as a whole.
The use
attribute of xsl:context-item
takes the
value required
, optional
, or
prohibited
. If the value required
is
specified, then there must be a context item. (This will
automatically be the case if the template is invoked using xsl:apply-templates
,
xsl:apply-imports
, or
xsl:next-match
, but
not if it is invoked using xsl:call-template
). If
the value optional
is specified, or if the attribute
is omitted, or if the xsl:context-item
element
is omitted, then there may or may not be a context item when the
template is invoked. If the containing xsl:template
element has no
name
attribute then the only permitted value is
required
. If the value prohibited
is
specified, then there will be no context item available to the body
template (if the calling template has a context item, it will not
be made available to the called template).
The as
attribute of the xsl:context-item
defines
the required type of the context item supplied to the template if
one is supplied. The default value is as="item()"
. If
a context item is supplied (which will automatically be the case if
the template is invoked using xsl:apply-templates
,
xsl:apply-imports
, or
xsl:next-match
) then
if will be converted to the required type by applying the function conversion rules; a
type
error [see ERR
XTTE0590] occurs if conversion to the required type is
not possible. The processor may signal a
type
error statically if the required context item type is
incompatible with the match
pattern, that is, if no
item that satisfies the match pattern can also satisfy the required
context item type.
The xsl:context-item
element
plays no part in deciding whether and when the template rule is
invoked in response to an xsl:apply-templates
instruction.
[ERR XTTE3090] It is a type error if the
xsl:context-item
child of xsl:template
specifies that a context item is required and none is supplied by
the caller, that is, if the context item is absent at the point
where xsl:call-template
is
evaluated.
When an item is selected by xsl:apply-templates
and
there is no user-specified template rule in the stylesheet
that can be used to process that item, then a built-in
template rule is evaluated instead.
The built-in template rules have lower import precedence than all other template rules. Thus, the stylesheet author can override a built-in template rule by including an explicit template rule.
There are six sets of built-in template rules available. The set
that is chosen is a property of the mode selected by the xsl:apply-templates
instruction. This property is set using the
on-no-match
attribute of the xsl:mode
declaration, which takes
one of the six values deep-copy
,
shallow-copy
, deep-skip
,
shallow-skip
, text-only-copy
, or
fail
, the default being text-only-copy
.
The effect of these six sets of built-in template rules is
explained in the following subsections.
The effect of processing a tree using a mode that specifies
on-no-match="text-only-copy"
is that the
textual content of the source document is retained while losing the
markup, except where explicit template rules dictate otherwise.
When an element is encountered for which there is no explicit
template rule, the processing continues
with the children of that element. Text nodes are copied to the
output.
The built-in rule for document nodes and element nodes is
equivalent to calling xsl:apply-templates
with no select
attribute, and with the
mode
attribute set to #current
. If the
built-in rule was invoked with parameters, those parameters are
passed on in the implicit xsl:apply-templates
instruction.
The built-in template rule for text and attribute nodes and atomic values returns a text node containing the string value of the context node. It is effectively:
<xsl:template match="text()|@*|xs:anyAtomicType" mode="M"> <xsl:value-of select="string(.)"/> </xsl:template>
Note:
This text node may have a string value that is zero-length.
The built-in template rule for processing instructions, comments, namespace nodes, and function items does nothing (it returns the empty sequence).
<xsl:template match="processing-instruction()|comment()|namespace-node()|function(*)" mode="M"/>
Suppose the stylesheet contains the following instruction:
<xsl:apply-templates select="title" mode="M"> <xsl:with-param name="init" select="10"/> </xsl:apply-templates>
If there is no explicit template rule that matches the
title
element, then the following implicit rule is
used:
<xsl:template match="title" mode="M"> <xsl:param name="init"/> <xsl:apply-templates mode="#current"> <xsl:with-param name="init" select="$init"/> </xsl:apply-templates> </xsl:template>
The effect of processing a tree using a mode that specifies
on-no-match="deep-copy"
is that an unmatched
element in the source tree is copied unchanged to the output,
together with its entire subtree. Other unmatched items are also
copied unchanged. The subtree is copied unconditionally, without
attempting to match nodes in the subtree against template
rules.
When this default action is selected for a mode M, all items (nodes, atomic values, and functions) are processed using a template rule that is equivalent to the following:
<xsl:template match="." mode="M"> <xsl:copy-of select="." validation="preserve"/> </xsl:template>
The effect of processing a tree using a mode that specifies
on-no-match="shallow-copy"
is that the source
tree is copied unchanged to the output, except for nodes where
different processing is specified using an explicit template
rule.
When this default action is selected for a mode M,
all items (nodes, atomic values, and functions) are
processed using a template rule that is equivalent to the
following, except that all parameters supplied in xsl:with-param
elements are
passed on implicitly to the called templates:
<xsl:template match="." mode="M"> <xsl:copy validation="preserve"> <xsl:apply-templates select="@*" mode="M"/> <xsl:apply-templates select="node()" mode="M"/> </xsl:copy> </xsl:template>
This rule is often referred to as the identity template, though it should be noted that it does not preserve node identity.
Note:
This rule differs from the traditional identity template rule by
using two xsl:apply-templates
instructions, one to process the attributes and one to process the
children. The only observable difference from the traditional
select="node() | @*
is that with two separate
instructions, the value of position()
in the called
templates forms one sequence starting at 1 for the attributes, and
a new sequence starting at 1 for the children.
A further reason for choosing this form is for streamability:
this formulation is guaranteed-streamable, whereas the
traditional form using select="node() | @*"
is not
(see <IP_ADDRESS>
Streamability of xsl:apply-templates).
The following stylesheet transforms an input document by
deleting all elements named note
, together with their
attributes and descendants:
<xsl:stylesheet version="3.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> <xsl:mode on-no-match="shallow-copy" streamable="yes"/> <xsl:template match="note"> <!-- no action --> </xsl:template> </xsl:stylesheet>
The effect of processing a tree using a mode that specifies
on-no-match="deep-skip"
is that where no explicit
template rule is specified for an element, that element and all its
descendants are ignored, and are not copied to the result tree.
The effect of choosing on-no-match="deep-skip"
is
as follows:
The built-in rule for document nodes is equivalent to calling
xsl:apply-templates
with no select
attribute, and with the
mode
attribute set to #current
. If the
built-in rule was invoked with parameters, those parameters are
passed on in the implicit xsl:apply-templates
instruction.
The built-in rule for all items other than document nodes (that is, for all other kinds of node, as well as atomic values and functions) is to do nothing, that is, to return an empty sequence (without applying templates to any children or ancestors).
The effect of processing a tree using a mode that specifies
on-no-match="shallow-skip"
is to drop both the
textual content and the markup from the result document, except
where there is an explicit user-written template rule that
dictates otherwise.
The built-in rule for document nodes and element nodes is the
same as for on-no-match="text-only-copy"
: that is, it
is equivalent to calling xsl:apply-templates
with no select
attribute, and with the
mode
attribute set to #current
. If the
built-in rule was invoked with parameters, those parameters are
passed on in the implicit xsl:apply-templates
instruction.
The built-in template rule for all other kinds of node, and for atomic values and functions, is empty: that is, when the item is matched, the built-in template rule returns an empty sequence.
The effect of choosing on-no-match="fail"
for a
mode is that
every item selected in an xsl:apply-templates
instruction must be matched by an explicit user-written template
rule.
The built-in template rule is effectively:
<xsl:template match="." mode="M"> <xsl:message terminate="yes" error-code="err:XTDE0555"/> </xsl:template>
with an implementation-dependent message body.
[ERR XTDE0555] It is a dynamic error if
xsl:apply-templates
,
xsl:apply-imports
or xsl:next-match
is
used to process a node using a mode whose declaration specifies
on-no-match="fail"
when there is no template
rule in the stylesheet whose match pattern matches that
node.
<!-- Category: instruction
-->
<xsl:apply-imports>
<!-- Content: xsl:with-param* -->
</xsl:apply-imports>
<!-- Category: instruction
-->
<xsl:next-match>
<!-- Content: (xsl:with-param | xsl:fallback)* -->
</xsl:next-match>
A template rule that is being used to
override another template rule (see 6.4
Conflict Resolution for Template Rules) can use the
xsl:apply-imports
or xsl:next-match
instruction to invoke the overridden template rule. The xsl:apply-imports
instruction only considers template rules in imported stylesheet
modules; the xsl:next-match
instruction
considers all other template rules of lower import precedence and/or priority,
and also declarations of the same precedence and priority
that appear earlier in declaration order. Both
instructions will invoke the built-in template rule for the
context item (see 6.8
Built-in Template Rules) if no other template rule is
found.
[Definition: At any point in the processing of a
stylesheet, there may be a current template
rule. Whenever a template rule is chosen as a result of
evaluating xsl:apply-templates
,
xsl:apply-imports
, or
xsl:next-match
, the
template rule becomes the current template rule for the evaluation
of the rule's sequence constructor. When an xsl:for-each
, xsl:for-each-group
,
xsl:analyze-string
,
xsl:iterate
,
xsl:stream
, xsl:merge
, or xsl:evaluate
instruction is evaluated, or when evaluating a sequence constructor
contained in an xsl:sort
or xsl:key
element, or when
a non-contextual function
call is made, the current template rule becomes
absent for the evaluation of that
instruction or function.]
The current template rule is not affected by invoking named templates (see 10.1 Named Templates) or named attribute sets (see 10.2 Named Attribute Sets). While evaluating a global variable or the default value of a stylesheet parameter (see 9.5 Global Variables and Parameters) the current template rule is absent.
Note:
These rules ensure that when xsl:apply-imports
or
xsl:next-match
is
called, the context item is the same as when the current
template rule was invoked.
Both xsl:apply-imports
and
xsl:next-match
search for a template rule that matches the
context item, and that is applicable
to the current mode (see 6.6
Modes). In choosing a template rule, they use the usual
criteria such as the priority and import precedence
of the template rules, but they consider as candidates only a
subset of the template rules in the stylesheet. This subset differs
between the two instructions:
The xsl:apply-imports
instruction considers as candidates only those template rules
contained in stylesheet levels that are descendants
in the import tree of the stylesheet level that contains the
current template rule.
Note:
This is not the same as saying that the search considers all template rules whose import precedence is lower than that of the current template rule.
The xsl:next-match
instruction
considers as candidates all those template rules that come after
the current template rule in the
ordering of template rules implied by the conflict resolution rules
given in 6.4 Conflict Resolution for
Template Rules. That is, it considers all template rules
with lower import precedence than the current template rule, plus the
template rules that are at the same import precedence that have
lower priority than the current template rule, plus
the template rules with the same import precedence and
priority that occur before the current template rule in declaration order.
Note:
As explained in 6.4 Conflict Resolution
for Template Rules, a template rule with no
priority
attribute, whose match pattern
contains multiple alternatives separated by |
, is
treated equivalently to a set of template rules, one for each
alternative. This means that where the same item
matches more than one alternative, it is possible for an xsl:next-match
instruction
to cause the current template rule to be invoked recursively. This
situation does not occur when the template rule has an
explicit priority.
If no matching template rule is found that satisfies these criteria, the built-in template rule for the context item is used (see 6.8 Built-in Template Rules).
An xsl:apply-imports
or
xsl:next-match
instruction may use xsl:with-param
child
elements to pass parameters to the chosen template rule (see
9.10 Setting Parameter Values). It
also passes on any tunnel parameters as described in
10.1.2 Tunnel Parameters.
[ERR XTDE0560] It is a dynamic error if
xsl:apply-imports
or xsl:next-match
is
evaluated when the current template rule is
absent.
xsl:apply-imports
For example, suppose the stylesheet doc.xsl
contains a template rule for example
elements:
<xsl:template match="example"> <pre><xsl:apply-templates/></pre> </xsl:template>
Another stylesheet could import doc.xsl
and modify
the treatment of example
elements as follows:
<xsl:import href="doc.xsl"/> <xsl:template match="example"> <div style="border: solid red"> <xsl:apply-imports/> </div> </xsl:template>
The combined effect would be to transform an
example
into an element of the form:
<div style="border: solid red"><pre>...</pre></div>
An xsl:fallback
instruction appearing as a child of an xsl:next-match
instruction
is ignored by an XSLT 2.0 or 3.0 processor, but can be
used to define fallback behavior when the stylesheet is processed
by an XSLT 1.0 processor with forwards compatible behavior.
A template rule may have parameters. The parameters are declared
in the body of the template using xsl:param
elements, as described
in 9.2 Parameters.
Values for these parameters may be supplied in the calling
xsl:apply-templates
,
xsl:apply-imports
, or
xsl:next-match
instruction by means of xsl:with-param
elements
appearing as children of the calling instruction. The expanded
QName represented by the name
attribute of the
xsl:with-param
element must match the expanded QName represented by the
name
attribute of the corresponding xsl:param
element.
[ERR XTDE0700] It is a dynamic error if a
template that is invoked using xsl:apply-templates
,
xsl:apply-imports
, or
xsl:next-match
declares a template parameter with
required="yes"
and no value for this parameter is
supplied by the calling instruction. The same error is reported in
the case of a tunnel parameter whether invoked using
one of these three instructions or by xsl:call-template
, as
explained in 10.1.2 Tunnel
Parameters.
It is not an error for these instructions to supply a parameter that does not match any parameter declared in the template rule that is invoked; unneeded parameter values are simply ignored.
A parameter may be declared as a tunnel parameter by
specifying tunnel="yes"
in the xsl:param
declaration; in this
case the caller must supply the value as a tunnel parameter by
specifying tunnel="yes"
in the corresponding xsl:with-param
element.
Tunnel parameters differ from ordinary template parameters in that
they are passed transparently through multiple template
invocations. They are fully described in 10.1.2 Tunnel Parameters.
XSLT offers two constructs for processing each item of a
sequence: xsl:for-each
and xsl:iterate
.
The main difference between the two constructs is that with
xsl:for-each
, the
processing applied to each item in the sequence is independent of
the processing applied to any other item; this means that the items
may be processed in any order or in parallel, though the order of
the output sequence is well defined and corresponds to the order of
the input (sorted if so requested). By contrast, with xsl:iterate
, the processing is
explicitly sequential: while one item is being processed, values
may be computed which are then available for use while the next