[Definition: A circularity is said to exist if a construct such as a global variable, an attribute set, or a key is defined in terms of itself. For example, if the expression or sequence constructor specifying the value of a global variable X references a global variable Y, then the value for Y must be computed before the value of X. A circularity exists if it is impossible to do this for all global variable definitions.]
The following two declarations create a circularity:
<xsl:variable name="x" select="$y+1"/> <xsl:variable name="y" select="$x+1"/>
The definition of a global variable can be circular
even if no other variable is involved. For example the
following two declarations (see 10.3 Stylesheet
Functions for an explanation of the xsl:function
element) also create a circularity:
<xsl:variable name="x" select="my:f()"/> <xsl:function name="my:f"> <xsl:sequence select="$x"/> </xsl:function>
The definition of a variable is also circular if the
evaluation of the variable invokes an xsl:apply-templates
instruction and the variable is referenced in the pattern
used in the match
attribute of any template
rule in the stylesheet. For example the
following definition is circular:
<xsl:variable name="x"> <xsl:apply-templates select="//param[1]"/> </xsl:variable> <xsl:template match="param[$x]">1</xsl:template>
Similarly, a variable definition is circular if it
causes a call on the key
function, and the
definition of that key refers
to that variable in its match
or
use
attributes. So the following definition
is circular:
<xsl:variable name="x" select="my:f(10)"/> <xsl:function name="my:f"> <xsl:param name="arg1"/> <xsl:sequence select="key('k', $arg1)"/> </xsl:function> <xsl:key name="k" match="item[@code=$x]" use="@desc"/>
[ERR XTDE0640] In general, a circularity in a stylesheet is a non-recoverable dynamic error. However, as with all other dynamic errors, an implementation will signal the error only if it actually executes the instructions and expressions that participate in the circularity. Because different implementations may optimize the execution of a stylesheet in different ways, it is implementation-dependent whether a particular circularity will actually be signaled.
For example, in the following declarations, the function
declares a local variable $b
, but it
returns a result that does not require the variable to be
evaluated. It is implementation-dependent
whether the value is actually evaluated, and it is
therefore implementation-dependent whether the circularity
is signaled as an error:
<xsl:variable name="x" select="my:f(1)/> <xsl:function name="my:f"> <xsl:param name="a"/> <xsl:variable name="b" select="$x"/> <xsl:sequence select="$a + 2"/> </xsl:function>
Circularities usually involve global variables or
parameters, but they can also exist between key definitions (see 16.3
Keys), between named attribute sets (see 10.2 Named Attribute Sets), or
between any combination of these constructs. For example, a
circularity exists if a key definition invokes a function
that references an attribute set that calls the key
function, supplying
the name of the original key definition as an argument.
Circularity is not the same as recursion. Stylesheet functions (see 10.3 Stylesheet Functions) and named templates (see 10.1 Named Templates) may call other functions and named templates without restriction. With careless coding, recursion may be non-terminating. Implementations are required to signal circularity as a dynamic error, but they are not required to detect non-terminating recursion.
This section describes three constructs that can be used to provide subroutine-like functionality that can be invoked from anywhere in the stylesheet: named templates (see 10.1 Named Templates), named attribute sets (see 10.2 Named Attribute Sets) and stylesheet functions (see 10.3 Stylesheet Functions).
<!-- Category:
instruction -->
<xsl:call-template
name = qname>
<!-- Content: xsl:with-param* -->
</xsl:call-template>
[Definition: Templates can be invoked by name. An
xsl:template
element with a name
attribute defines a
named template.] The
value of the name
attribute is a QName, which is expanded as
described in 5.1 Qualified
Names. If an xsl:template
element
has a name
attribute, it may, but need not,
also have a match
attribute. An xsl:call-template
instruction invokes a template by name; it has a
required name
attribute that identifies the template to be invoked.
Unlike xsl:apply-templates
,
the xsl:call-template
instruction does not change the focus.
The match
, mode
and
priority
attributes on an xsl:template
element
have no effect when the template is invoked by an xsl:call-template
instruction. Similarly, the name
attribute on
an xsl:template
element
has no effect when the template is invoked by
an xsl:apply-templates
instruction.
[ERR XTSE0650] It is a static error if
a stylesheet contains an xsl:call-template
instruction whose name
attribute does not
match the name
attribute of any xsl:template
in the
stylesheet.
[ERR XTSE0660] It is a static error if a stylesheet contains more than one template with the same name and the same import precedence, unless it also contains a template with the same name and higher import precedence.
The target template for an xsl:call-template
instruction is the template whose name
attribute matches the name
attribute of the
xsl:call-template
instruction and that has higher import
precedence than any other template with this name. The
result of evaluating an xsl:call-template
instruction is the sequence produced by evaluating the
sequence constructor
contained in its target template (see 5.7 Sequence
Constructors).
<xsl:with-param
name = qname
select? = expression
as? = sequence-type
tunnel? = "yes" | "no">
<!-- Content:
sequence-constructor -->
</xsl:with-param>
Parameters are passed to templates using the xsl:with-param
element. The required
name
attribute specifies the name of the
template parameter (the
variable the value of whose binding is to be replaced).
The value of the name
attribute is a
QName, which is
expanded as described in 5.1
Qualified Names.
xsl:with-param
is
allowed within xsl:call-template
,
xsl:apply-templates
,
xsl:apply-imports
,
and xsl:next-match
.
[ERR XTSE0670] It is a static error
if a single xsl:call-template
,
xsl:apply-templates
,
xsl:apply-imports
,
or xsl:next-match
element contains two or more xsl:with-param
elements with matching name
attributes.
The value of the parameter is specified in the same
way as for xsl:variable
and
xsl:param
(see
9.3 Values of Variables and
Parameters), taking account of the values
of the select
and as
attributes
and the content of the xsl:with-param
element, if any.
Note:
It is possible to have an as
attribute
on the xsl:with-param
element that differs from the as
attribute
on the corresponding xsl:param
element
describing the formal parameters of the called
template.
In this situation, the supplied value of the
parameter will first be processed according to the
rules of the as
attribute on the xsl:with-param
element, and the resulting value will then be further
processed according to the rules of the as
attribute on the xsl:param
element.
For example, suppose the supplied value is a node
with type annotation
xs:untypedAtomic
, and the
xsl:with-param
element specifies as="xs:integer"
, while
the xsl:param
element specifies as="xs:double"
. Then the
node will first be atomized and the resulting untyped
atomic value will be cast to xs:integer
.
If this succeeds, the xs:integer
will then
be promoted to an xs:double
.
The focus used
for computing the value specified by the xsl:with-param
element is the same as that used for the xsl:apply-templates
,
xsl:apply-imports
,
xsl:next-match
, or
xsl:call-template
element within which it occurs.
[ERR XTSE0680] In the case of xsl:call-template
,
it is a static error to pass a
non-tunnel parameter named x to a
template that does not have a template parameter named
x, unless backwards compatible
behavior is enabled for the xsl:call-template
instruction. This is not an error in the case of
xsl:apply-templates
,
xsl:apply-imports
,
and xsl:next-match
;
in these cases the parameter is simply ignored.
The optional tunnel
attribute may be used
to indicate that a parameter is a tunnel
parameter. The default is no
. Tunnel
parameters are described in 10.1.2 Tunnel Parameters
[ERR XTSE0690] It is a static error
if a template that is invoked using xsl:call-template
declares a template parameter
specifying required="yes"
and not
specifying tunnel="yes"
, if no value
for this parameter is supplied by the calling
instruction.
[ERR XTDE0700] In other cases, it is a
non-recoverable dynamic
error if the template that is invoked declares a
template parameter with
required="yes"
and no value for this
parameter is supplied by the calling instruction.
This example defines a named template for a
numbered-block
with an argument to control
the format of the number.
<xsl:template name="numbered-block"> <xsl:param name="format">1. </xsl:param> <fo:block> <xsl:number format="{$format}"/> <xsl:apply-templates/> </fo:block> </xsl:template> <xsl:template match="ol//ol/li"> <xsl:call-template name="numbered-block"> <xsl:with-param name="format">a. </xsl:with-param> </xsl:call-template> </xsl:template>
Note:
Arguments to stylesheet functions are supplied as part of an XPath function call: see 10.3 Stylesheet Functions
[Definition: A parameter passed to a template may be defined as a tunnel parameter. Tunnel parameters have the property that they are automatically passed on by the called template to any further templates that it calls, and so on recursively.] Tunnel parameters thus allow values to be set that are accessible during an entire phase of stylesheet processing, without the need for each template that is used during that phase to be aware of the parameter.
Note:
Tunnel parameters are conceptually similar to dynamically-scoped variables in some functional programming languages.
A tunnel parameter is created by
using an xsl:with-param
element that specifies tunnel="yes"
. A
template that requires access to the value of a tunnel
parameter must declare it using an xsl:param
element that
also specifies tunnel="yes"
.
On any template call using an xsl:apply-templates
,
xsl:call-template
,
xsl:apply-imports
or xsl:next-match
instruction, a set of tunnel parameters is passed
from the calling template to the called template. This
set consists of any parameters explicitly created using
<xsl:with-param tunnel="yes">
,
overlaid on a base set of tunnel parameters. If the
xsl:apply-templates
,
xsl:call-template
,
xsl:apply-imports
or xsl:next-match
instruction has an xsl:template
declaration as an ancestor element in the stylesheet,
then the base set consists of the tunnel parameters that
were passed to that template; otherwise (for example, if
the instruction is within a global variable declaration,
an attribute set declaration, or a
stylesheet function), the
base set is empty. If a parameter created using
<xsl:with-param tunnel="yes">
has the
same expanded-QName as a parameter in
the base set, then the parameter created using xsl:with-param
overrides the parameter in the base set; otherwise, the
parameter created using xsl:with-param
is
added to the base set.
When a template accesses the value of a tunnel
parameter by declaring it with xsl:param
tunnel="yes"
, this does not remove the parameter
from the base set of tunnel parameters that is passed on
to any templates called by this template.
Two sibling xsl:with-param
elements must have distinct parameter names, even if one
is a tunnel parameter and the other
is not. Equally, two sibling xsl:param
elements
representing template parameters must
have distinct parameter names, even if one is a tunnel
parameter and the other is not. However, the tunnel
parameters that are implicitly passed in a template call
may have names that duplicate the names of non-tunnel
parameters that are explicitly passed on the same
call.
Tunnel parameters are not passed in calls to stylesheet functions.
All other options of xsl:with-param
and
xsl:param
are
available with tunnel parameters just as with
non-tunnel parameters. For example, parameters may be
declared as mandatory or optional, a default value may be
specified, and a required type may be specified. If any
conversion is required from the supplied value of a
tunnel parameter to the required type specified in
xsl:param
, then
the converted value is used within the receiving
template, but the value that is passed on in any further
template calls is the original supplied value before
conversion. Equally, any default value is local to the
template: specifying a default value for a tunnel
parameter does not change the set of tunnel parameters
that is passed on in further template calls.
The set of tunnel parameters that is passed to the initial template is empty.
Tunnel parameters are passed unchanged through a built-in template rule (see 6.6 Built-in Template Rules).
Suppose that the equations in a scientific paper are to be sequentially numbered, but that the format of the number depends on the context in which the equations appear. It is possible to reflect this using a rule of the form:
<xsl:template match="equation"> <xsl:param name="equation-format" select="'(1)'" tunnel="yes"/> <xsl:number level="any" format="{$equation-format}"/> </xsl:template>
At any level of processing above this level, it is possible to determine how the equations will be numbered, for example:
<xsl:template match="appendix"> ... <xsl:apply-templates> <xsl:with-param name="equation-format" select="'[i]'" tunnel="yes"/> </xsl:apply-templates> ... </xsl:template>
The parameter value is passed transparently through
all the intermediate layers of template rules until it
reaches the rule with match="equation"
.
The effect is similar to using a global variable,
except that the parameter can take different values
during different phases of the transformation.
<!-- Category:
declaration -->
<xsl:attribute-set
name = qname
use-attribute-sets? =
qnames>
<!-- Content: xsl:attribute* -->
</xsl:attribute-set>
[Definition: The xsl:attribute-set
element defines a named attribute set: that is, a
collection of attribute definitions that can
be used repeatedly on different constructed
elements.]
The required name
attribute specifies the name of the attribute set. The
value of the name
attribute is a QName, which is expanded as
described in 5.1 Qualified
Names. The content of the xsl:attribute-set
element consists of zero or more xsl:attribute
instructions that are evaluated to produce the attributes
in the set.
The result of evaluating an attribute set is a sequence of attribute nodes. Evaluating the same attribute set more than once can produce different results, because although an attribute set does not have parameters, it may contain expressions or instructions whose value depends on the evaluation context.
Attribute sets are used by
specifying a use-attribute-sets
attribute on
the xsl:element
or xsl:copy
instruction, or by specifying an
xsl:use-attribute-sets
attribute on a literal
result element. An attribute set may be defined in terms of
other attribute sets by using the
use-attribute-sets
attribute on the xsl:attribute-set
element itself. The value of the
[xsl:]use-attribute-sets
attribute is in each
case a whitespace-separated list of names of attribute
sets. Each name is specified as a QName, which is expanded as described in
5.1 Qualified Names.
Specifying a use-attribute-sets
attribute
is broadly equivalent to adding xsl:attribute
instructions for each of the attributes in each of the
named attribute sets to the beginning of the content of the
instruction with the [xsl:]use-attribute-sets
attribute, in the same order in which the names of the
attribute sets are specified in the
use-attribute-sets
attribute.
More formally, an xsl:use-attribute-sets
attribute is expanded using the following recursive
algorithm, or any algorithm that produces the same
results:
The value of the attribute is tokenized as a list of QNames.
Each QName in the list is processed, in order, as follows:
The QName must match the name
attribute of one or more xsl:attribute-set
declarations in the stylesheet.
Each xsl:attribute-set
declaration whose name matches is processed as
follows. Where two such declarations have different
import precedence, the
one with lower import precedence is processed
first. Where two declarations have the same import
precedence, they are processed in declaration order.
If the xsl:attribute-set
declaration has a
use-attribute-sets
attribute, the
attribute is expanded by applying this
algorithm recursively.
If the xsl:attribute-set
declaration contains one or more xsl:attribute
instructions, these instructions are evaluated
(following the rules for evaluating a sequence
constructor: see 5.7 Sequence
Constructors) to produce a sequence of
attribute nodes. These attribute nodes are
appended to the result sequence.
The xsl:attribute
instructions are evaluated using the same focus as is used for evaluating the
element that is the parent of the
[xsl:]use-attribute-sets
attribute forming the
initial input to the algorithm. However, the static context
for the evaluation depends on the position of the xsl:attribute
instruction in the stylesheet: thus, only local variables
declared within an xsl:attribute
instruction, and global variables, are visible.
The set of attribute nodes produced by expanding
xsl:use-attribute-sets
may include several
attributes with the same name. When the attributes are
added to an element node, only the last of the duplicates
will take effect.
The way in which each instruction uses the results of
expanding the [xsl:]use-attribute-sets
attribute is described in the specification for the
relevant instruction: see 11.1 Literal Result
Elements, 11.2 Creating
Element Nodes Using xsl:element , and 11.9 Copying Nodes.
[ERR XTSE0710] It is a static error if
the value of the use-attribute-sets
attribute
of an xsl:copy
,
xsl:element
, or
xsl:attribute-set
element, or the xsl:use-attribute-sets
attribute of a literal result element, is
not a whitespace-separated sequence of
QNames, or if it
contains a QName that does not match the name
attribute of any xsl:attribute-set
declaration in the stylesheet.
[ERR XTSE0720] It is a static error if
an xsl:attribute-set
element directly or indirectly references itself via the
names contained in the use-attribute-sets
attribute.
Each attribute node produced by expanding an attribute
set has a type annotation determined by the
rules for the xsl:attribute
instruction that created the attribute node: see 11.3.1 Setting
the Type Annotation for a Constructed Attribute
Node. These type annotations may be preserved,
stripped, or replaced as determined by the rules for the
instruction that creates the element in which the
attributes are used.
Attribute sets are used as follows:
The xsl:copy
and xsl:element
instructions have an use-attribute-sets
attribute. The sequence of attribute nodes produced by
evaluating this attribute is prepended to the sequence
produced by evaluating the sequence constructor
contained within the instruction.
Literal result
elements allow an
xsl:use-attribute-sets
attribute, which is
evaluated in the same way as the
use-attribute-sets
attribute of xsl:element
and
xsl:copy
. The
sequence of attribute nodes produced by evaluating this
attribute is prepended to the sequence of attribute
nodes produced by evaluating the attributes of the
literal result element, which in turn is prepended to
the sequence produced by evaluating the sequence constructor
contained with the literal result element.
The following example creates a named attribute
set title-style
and uses it in a
template rule.
<xsl:template match="chapter/heading"> <fo:block font-stretch="condensed" xsl:use-attribute-sets="title-style"> <xsl:apply-templates/> </fo:block> </xsl:template> <xsl:attribute-set name="title-style"> <xsl:attribute name="font-size">12pt</xsl:attribute> <xsl:attribute name="font-weight">bold</xsl:attribute> </xsl:attribute-set>
The following example creates a named attribute set
base-style
and uses it in a template rule
with multiple specifications of the attributes:
is specified only in the attribute set
is specified in the attribute set, is specified on
the literal result element, and in an xsl:attribute
instruction
is specified in the attribute set, and on the literal result element
is specified in the attribute set, and in an
xsl:attribute
instruction
Stylesheet fragment:
<xsl:attribute-set name="base-style"> <xsl:attribute name="font-family">Univers</xsl:attribute> <xsl:attribute name="font-size">10pt</xsl:attribute> <xsl:attribute name="font-style">normal</xsl:attribute> <xsl:attribute name="font-weight">normal</xsl:attribute> </xsl:attribute-set> <xsl:template match="o"> <fo:block xsl:use-attribute-sets="base-style" font-size="12pt" font-style="italic"> <xsl:attribute name="font-size">14pt</xsl:attribute> <xsl:attribute name="font-weight">bold</xsl:attribute> <xsl:apply-templates/> </fo:block> </xsl:template>
Result:
<fo:block font-family="Univers" font-size="14pt" font-style="italic" font-weight="bold"> ... </fo:block>
[Definition: An xsl:function
declaration declares the name, parameters, and
implementation of a stylesheet function that can be
called from any XPath expression within the stylesheet.]
<!-- Category: declaration
-->
<xsl:function
name = qname
as? = sequence-type
override? = "yes" | "no">
<!-- Content: (xsl:param*,
sequence-constructor) -->
</xsl:function>
The xsl:function
declaration defines a stylesheet function that can
be called from any XPath expression used in the stylesheet
(including an XPath expression used within a predicate in a
pattern). The
name
attribute specifies the name of the
function. The value of the name
attribute is a
QName, which is
expanded as described in 5.1 Qualified
Names.
An xsl:function
declaration can only appear as a top-level element in a
stylesheet module.
[ERR XTSE0740] A stylesheet function must have a prefixed name, to remove any risk of a clash with a function in the default function namespace. It is a static error if the name has no prefix..
Note:
To prevent the namespace declaration used for the
function name appearing in the result document, use the
exclude-result-prefixes
attribute on the
xsl:stylesheet
element: see 11.1.3
Namespace Nodes for Literal Result Elements.
The prefix must not refer to a reserved namespace: [see ERR XTSE0080]
The content of the xsl:function
element
consists of zero or more xsl:param
elements that
specify the formal arguments of the function, followed by
a sequence constructor that
defines the value to be returned by the
function.
[Definition: The arity of a
stylesheet function is the number of xsl:param
elements in the
function definition.]
Optional arguments are not allowed.
[ERR XTSE0760] Because arguments to a
stylesheet function call must all
be specified, the xsl:param
elements within
an xsl:function
element
must not specify a default value:
this means they must be empty,
and must not have a
select
attribute.
A stylesheet function is included in the in-scope functions of the static context for all XPath expressions used in the stylesheet, unless
there is another stylesheet function with the same name and arity, and higher import precedence, or
the override
attribute has the value
no
and there is already a function with
the same name and arity in the in-scope functions.
The optional override
attribute defines
what happens if this function has the same name and
arity as a function
provided by the implementer or made available in the static
context using an implementation-defined mechanism. If the
override
attribute has the value
yes
, then this function is used in preference;
if it has the value no
, then the other
function is used in preference. The default value is
yes
.
Note:
Specifying override="yes"
ensures
interoperable behavior: the same code will execute with
all processors. Specifying override="no"
is
useful when writing a fallback implementation of a
function that is available with some processors but not
others: it allows the vendor's implementation of the
function (or a user's implementation written as an
extension function) to be used in preference to
the stylesheet implementation, which is useful when the
extension function is more efficient.
The override
attribute does not
affect the rules for deciding which of several stylesheet functions with
the same name and arity takes precedence.
[ERR XTSE0770] It is a static error for a stylesheet to contain two or more functions with the same expanded-QName, the same arity, and the same import precedence, unless there is another function with the same expanded-QName and arity, and a higher import precedence.
As defined in XPath, the function that is executed as the result of a function call is identified by looking in the in-scope functions of the static context for a function whose name and arity matches the name and number of arguments in the function call.
Note:
Functions are not polymorphic. Although the XPath function call mechanism allows two functions to have the same name and different arity, it does not allow them to be distinguished by the types of their arguments.
The optional as
attribute indicates the
required
type of the result of the function. The value of the
as
attribute is a SequenceType
XP, as defined in [XPath 2.0].
[ERR XTTE0780] If the as
attribute is specified, then the result evaluated by the
sequence constructor (see
5.7 Sequence
Constructors) is converted to the required type,
using the function conversion
rules. It is a type error if this conversion fails.
If the as
attribute is omitted, the calculated
result is used as supplied, and no conversion takes
place.
If a stylesheet function has been
defined with a particular expanded-QName, then a call on
function-available
will return true when called with an argument that is a
lexical
QName that expands to this same expanded-QName.
The xsl:param
elements define the formal arguments to the function. These
are interpreted positionally. When the function is called
using a function-call in an XPath expression, the first argument
supplied is assigned to the first xsl:param
element, the
second argument supplied is assigned to the second xsl:param
element, and so
on.
The as
attribute of the xsl:param
element defines
the required type of the parameter. The rules for
converting the values of the actual arguments supplied in
the function call to the types required by each xsl:param
element are
defined in [XPath 2.0]. The rules
that apply are those for the case where XPath 1.0 compatibility mode
is set to false
.
[ERR XTTE0790] If the value of a parameter to a stylesheet function cannot be converted to the required type, a type error is signaled.
If the as
attribute is omitted, no
conversion takes place and any value is accepted.
Within the body of a stylesheet function, the focus is initially undefined; this means that any attempt to reference the context item, context position, or context size is a non-recoverable dynamic error. [XPDY0002]
It is not possible within the body of the stylesheet function to access the values of local variables that were in scope in the place where the function call was written. Global variables, however, remain available.
The following example creates a recursive stylesheet function named
str:reverse
that reverses the words in a
supplied sentence, and then invokes this function from
within a template rule.
<xsl:transform xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:str="http://example.com/namespace" version="2.0" exclude-result-prefixes="str"> <xsl:function name="str:reverse" as="xs:string"> <xsl:param name="sentence" as="xs:string"/> <xsl:sequence select="if (contains($sentence, ' ')) then concat(str:reverse(substring-after($sentence, ' ')), ' ', substring-before($sentence, ' ')) else $sentence"/> </xsl:function> <xsl:template match="/"> <output> <xsl:value-of select="str:reverse('DOG BITES MAN')"/> </output> </xsl:template> </xsl:transform>
An alternative way of writing the same function is to implement the conditional logic at the XSLT level, thus:
<xsl:function name="str:reverse" as="xs:string"> <xsl:param name="sentence" as="xs:string"/> <xsl:choose> <xsl:when test="contains($sentence, ' ')"> <xsl:sequence select="concat(str:reverse(substring-after($sentence, ' ')), ' ', substring-before($sentence, ' '))"/> </xsl:when> <xsl:otherwise> <xsl:sequence select="$sentence"/> </xsl:otherwise> </xsl:choose> </xsl:function>
The following example illustrates the use of the
as
attribute in a function definition. It
returns a string containing the representation of its
integer argument, expressed as a roman numeral. For
example, the function call num:roman(7)
will
return the string "vii"
. This example uses
the xsl:number
instruction, described in 12
Numbering. The xsl:number
instruction
returns a text node, and the function conversion
rules are invoked to convert this text node to the
type declared in the xsl:function
element, namely xs:string
. So the text node
is atomized
to a string.
<xsl:function name="num:roman" as="xs:string"> <xsl:param name="value" as="xs:integer"/> <xsl:number value="$value" format="i"/> </xsl:function>
This section describes instructions that directly create new nodes, or sequences of nodes and atomic values.
[Definition: In a sequence constructor, an element in the stylesheet that does not belong to the XSLT namespace and that is not an extension instruction (see 18.2 Extension Instructions) is classified as a literal result element.] A literal result element is evaluated to construct a new element node with the same expanded-QName (that is, the same namespace URI, local name, and namespace prefix). The result of evaluating a literal result element is a node sequence containing one element, the newly constructed element node.
The content of the element is a sequence constructor (see 5.7 Sequence Constructors). The sequence obtained by evaluating this sequence constructor, after prepending any attribute nodes produced as described in 11.1.2 Attribute Nodes for Literal Result Elements and namespace nodes produced as described in 11.1.3 Namespace Nodes for Literal Result Elements, is used to construct the content of the element, following the rules in 5.7.1 Constructing Complex Content
The base URI of the new element is copied from the base
URI of the literal result element in the stylesheet, unless
the content of the new element includes an
xml:base
attribute, in which case the base URI
of the new element is the value of that attribute, resolved
(if it is a relative URI) against the base URI of the
literal result element in the stylesheet. (Note, however,
that this is only relevant when creating a parentless
element. When the literal result element is copied to form
a child of an element or document node, the base URI of the
new copy is taken from that of its new parent.)
The attributes xsl:type
and
xsl:validation
may be used on a literal
result element to invoke validation of the contents of
the element against a type definition or element
declaration in a schema, and to determine the type
annotation that the new element node will carry.
These attributes also affect the type annotation carried
by any elements and attributes that have the new element
node as an ancestor. These two attributes are both
optional, and if one is specified then the other
must be omitted.
The value of the xsl:validation
attribute, if present, must be one of the values
strict
, lax
,
preserve
, or strip
. The value
of the xsl:type
attribute, if present, must
be a QName
identifying a type definition that is present in the
in-scope schema
components for the stylesheet. Neither attribute may
be specified as an attribute value
template. The effect of these attributes is described
in 19.2 Validation.
Attribute nodes for a literal result element may be
created by including xsl:attribute
instructions within the sequence constructor.
Additionally, attribute nodes are created corresponding
to the attributes of the literal result element in the
stylesheet, and as a result of expanding the
xsl:use-attribute-sets
attribute of the
literal result element, if present.
The sequence that is used to construct the content of the literal result element (as described in 5.7.1 Constructing Complex Content) is the concatenation of the following four sequences, in order:
The sequence of namespace nodes produced as described in 11.1.3 Namespace Nodes for Literal Result Elements.
The sequence of attribute nodes produced by
expanding the xsl:use-attribute-sets
attribute (if present) following the rules given in
10.2 Named Attribute
Sets
The attributes produced by processing the attributes of the literal result element itself, other than attributes in the XSLT namespace. The way these are processed is described below.
The sequence produced by evaluating the contained sequence constructor, if the element is not empty.
Note:
The significance of this order is that an attribute
produced by an xsl:attribute
,
xsl:copy
, or
xsl:copy-of
instruction in the content of the literal result
element takes precedence over an attribute produced by
expanding an attribute of the literal result element
itself, which in turn takes precedence over an
attribute produced by expanding the
xsl:use-attribute-sets
attribute. This is
because of the rules in 5.7.1 Constructing
Complex Content, which specify that when two or
more attributes in the sequence have the same name, all
but the last of the duplicates are discarded.
Although the above rules place namespace nodes before attributes, this is not strictly necessary, because the rules in 5.7.1 Constructing Complex Content allow the namespaces and attributes to appear in any order so long as both come before other kinds of node. The order of namespace nodes and attribute nodes in the sequence has no effect on the relative position of the nodes in document order once they are added to a tree.
Each attribute of the literal result element, other than an attribute in the XSLT namespace, is processed to produce an attribute for the element in the result tree.
The value of such an attribute is interpreted as an
attribute value
template: it can therefore contain expressions
contained in curly brackets ({}
). The new
attribute node will have the same expanded-QName (that is,
the same namespace URI, local name, and namespace
prefix) as the attribute in the stylesheet tree,
and its string value will be the same as
the effective value of the
attribute in the stylesheet tree. The type
annotation on the attribute will initially be
xs:untypedAtomic
, and the
typed
value of the attribute node will be the same as its
string
value.
Note:
The eventual type annotation of the attribute
in the result tree depends on the
xsl:validation
and xsl:type
attributes of the parent literal result element, and on
the instructions used to create its ancestor elements.
If the xsl:validation
attribute is set to
preserve
or strip
, the type
annotation will be
xs:untypedAtomic
, and the
typed
value of the attribute node will be the same as its
string
value. If the xsl:validation
attribute
is set to strict
or lax
, or
if the xsl:type
attribute is used, the
type annotation on the attribute will be set as a
result of the schema validation process applied to the
parent element. If neither attribute is present, the
type annotation on the attribute will be
xs:untypedAtomic
.
If the name of a constructed attribute is
xml:id
, the processor must perform attribute
value normalization by effectively applying the
normalize-space
FO
function to the value of the attribute, and the resulting
attribute node must be given the is-id
property.
[ERR XTRE0795] It is a recoverable dynamic error if
the name of a constructed attribute is
xml:space
and the value is not either
default
or preserve
. The
optional recovery
action is to construct the attribute with the value
as requested.. This applies whether the attribute is
constructed using a literal result element, or by using
the xsl:attribute
,
xsl:copy
, or
xsl:copy-of
instructions.
Note:
The xml:base
, xml:lang
,
xml:space
, and xml:id
attributes have two effects in XSLT. They behave as
standard XSLT attributes, which means for example that
if they appear on a literal result element, they will
be copied to the result tree in the same way as
any other attribute. In addition, they have their
standard meaning as defined in the core XML
specifications. Thus, an xml:base
attribute in the stylesheet affects the base URI of the
element on which it appears, and an
xml:space
attribute affects the
interpretation of whitespace text nodes
within that element. One consequence of this is that it
is inadvisable to write these attributes as attribute
value templates: although an XSLT processor will
understand this notation, the XML parser will not. See
also 11.1.4 Namespace
Aliasing which describes how to use xsl:namespace-alias
with these attributes.
The same is true of the schema-defined attributes
xsi:type
, xsi:nil
,
xsi:noNamespaceSchemaLocation
,
and xsi:schemaLocation
. If the stylesheet
is processed by a schema processor, these attributes
will be recognized and interpreted by the schema
processor, but in addition the XSLT processor
treats them like any other attribute on a literal
result element: that is, their effective
value (after expanding attribute value
templates) is copied to the result tree in the same
way as any other attribute. If the result tree is
validated, the copied attributes will again be
recognized and interpreted by the schema processor.
None of these attributes will be generated in the result tree unless the stylesheet writes them to the result tree explicitly, in the same way as any other attribute.
[ERR XTSE0805] It is a static error if an attribute on a literal result element is in the XSLT namespace, unless it is one of the attributes explicitly defined in this specification.
Note:
If there is a need to create attributes in the XSLT
namespace, this can be achieved using xsl:attribute
, or
by means of the xsl:namespace-alias
declaration.
The created element node will have a copy of the namespace nodes that were present on the element node in the stylesheet tree with the exception of any namespace node whose string value is designated as an excluded namespace. Special considerations apply to aliased namespaces: see 11.1.4 Namespace Aliasing
The following namespaces are designated as excluded namespaces:
The XSLT namespace URI
(http://www.w3.org/1999/XSL/Transform
)
A namespace URI declared as an extension namespace (see 18.2 Extension Instructions)
A namespace URI designated by using an
[xsl:]exclude-result-prefixes
attribute
either on the literal result element itself or on an
ancestor element. The attribute must be in the XSLT namespace only if
its parent element is not in the XSLT
namespace.
The value of the attribute is either
#all
, or a whitespace-separated list of
tokens, each of which is either a namespace prefix or
#default
. The namespace bound to each of
the prefixes is designated as an excluded
namespace.
[ERR
XTSE0808] It is a static error if a
namespace prefix is used within the
[xsl:]exclude-result-prefixes
attribute
and there is no namespace binding in scope for that
prefix.
The default namespace of the parent element of the
[xsl:]exclude-result-prefixes
attribute
(see Section
6.2 Element NodesDM)
may be designated as an excluded namespace by
including #default
in the list of
namespace prefixes.
[ERR
XTSE0809] It is a static error if the value
#default
is used within the
[xsl:]exclude-result-prefixes
attribute
and the parent element of the
[xsl:]exclude-result-prefixes
attribute
has no default namespace.
The value #all
indicates that all
namespaces that are in scope for the stylesheet
element that is the parent of the
[xsl:]exclude-result-prefixes
attribute
are designated as excluded namespaces.
The designation of a namespace as an excluded
namespace is effective within the subtree of the
stylesheet module rooted at the element bearing the
[xsl:]exclude-result-prefixes
attribute;
a subtree rooted at an xsl:stylesheet
element does not include any stylesheet modules
imported or included by children of that xsl:stylesheet
element.
The excluded namespaces, as described above,
only affect namespace nodes copied from the
stylesheet when processing a literal result element.
There is no guarantee that an excluded namespace will not
appear on the result tree for some other reason.
Namespace nodes are also written to the result tree as
part of the process of namespace fixup (see 5.7.3 Namespace Fixup), or
as the result of instructions such as xsl:copy
and xsl:element
.
Note:
When a stylesheet uses a namespace declaration only
for the purposes of addressing a source tree, specifying the
prefix in the
[xsl:]exclude-result-prefixes
attribute
will avoid superfluous namespace declarations in the
serialized result tree. The attribute is
also useful to prevent namespaces used solely for the
naming of stylesheet functions or extension functions
from appearing in the serialized result tree.
For example, consider the following stylesheet:
<xsl:stylesheet xsl:version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:a="a.uri" xmlns:b="b.uri"> exclude-result-prefixes="#all"> <xsl:template match="/"> <foo xmlns:c="c.uri" xmlns:d="d.uri" xmlns:a2="a.uri" xsl:exclude-result-prefixes="c"/> </xsl:template> </xsl:stylesheet>
The result of this stylesheet will be:
<foo xmlns:d="d.uri"/>
The namespaces a.uri
and
b.uri
are excluded by virtue of the
exclude-result-prefixes
attribute on the
xsl:stylesheet
element, and the namespace c.uri
is
excluded by virtue of the
xsl:exclude-result-prefixes
attribute on
the foo
element. The setting
#all
does not affect the namespace
d.uri
because d.uri
is not an
in-scope namespace for the xsl:stylesheet
element. The element in the result tree does not have a
namespace node corresponding to
xmlns:a2="a.uri"
because the effect of
exclude-result-prefixes
is to designate
the namespace URI a.uri
as an excluded
namespace, irrespective of how many prefixes are bound
to this namespace URI.
If the stylesheet is changed so that the literal
result element has an attribute b:bar="3"
,
then the element in the result tree will typically have a
namespace declaration xmlns:b="b.uri"
(the processor may choose a different namespace
prefix if this is necessary to avoid conflicts).
The exclude-result-prefixes
attribute
makes b.uri
an excluded namespace, so the
namespace node is not automatically copied from the
stylesheet, but the presence of an attribute whose name
is in the namespace b.uri
forces the
namespace fixup process (see 5.7.3 Namespace Fixup) to
introduce a namespace node for this namespace.
A literal result element may have an optional
xsl:inherit-namespaces
attribute, with the
value yes
or no
. The default
value is yes
. If the value is set to
yes
, or is omitted, then the namespace nodes
created for the newly constructed element are copied to
the children and descendants of the newly constructed
element, as described in 5.7.1 Constructing
Complex Content. If the value is set to
no
, then these namespace nodes are not
automatically copied to the children. This may result in
namespace undeclarations (such as xmlns=""
or, in the case of XML 1.1, xmlns:p=""
)
appearing on the child elements when a final
result tree is serialized.
When a stylesheet is used to define a transformation whose output is itself a stylesheet module, or in certain other cases where the result document uses namespaces that it would be inconvenient to use in the stylesheet, namespace aliasing can be used to declare a mapping between a namespace URI used in the stylesheet and the corresponding namespace URI to be used in the result document.
[Definition: A namespace URI in the stylesheet tree that is being used to specify a namespace URI in the result tree is called a literal namespace URI.]
[Definition: The namespace URI that is to be used in the result tree as a substitute for a literal namespace URI is called the target namespace URI.]
Either of the literal namespace URI or the target namespace URI can be null: this is treated as a reference to the set of names that are in no namespace.
<!-- Category:
declaration -->
<xsl:namespace-alias
stylesheet-prefix = prefix
| "#default"
result-prefix = prefix |
"#default" />
[Definition: A stylesheet can use the
xsl:namespace-alias
element to declare that a literal namespace URI is
being used as an alias for a target namespace
URI.]
The effect is that when names in the namespace identified by the literal namespace URI are copied to the result tree, the namespace URI in the result tree will be the target namespace URI, instead of the literal namespace URI. This applies to:
the namespace URI in the expanded-QName of a literal result element in the stylesheet
the namespace URI in the expanded-QName of an attribute specified on a literal result element in the stylesheet
Where namespace aliasing changes the namespace URI
part of the expanded-QName containing the
name of an element or attribute node, the namespace
prefix in that expanded-QName is replaced by the prefix
indicated by the result-prefix
attribute of
the xsl:namespace-alias
declaration.
The xsl:namespace-alias
element declares that the namespace URI bound to the
prefix specified by the stylesheet-prefix
is
the literal namespace URI,
and the namespace URI bound to the prefix specified by
the result-prefix
attribute is the target namespace URI.
Thus, the stylesheet-prefix
attribute
specifies the namespace URI that will appear in the
stylesheet, and the result-prefix
attribute
specifies the corresponding namespace URI that will
appear in the result tree.
The default namespace (as declared by
xmlns
) may be specified by using
#default
instead of a prefix. If no
default namespace is in force, specifying
#default
denotes the null namespace URI.
This allows elements that are in no namespace in the
stylesheet to acquire a namespace in the result document,
or vice versa.
If a literal namespace URI is declared to be an alias for multiple different target namespace URIs, then the declaration with the highest import precedence is used.
[ERR XTSE0810] It is a static error
if there is more than one such declaration with the same
literal namespace URI and
the same import precedence and
different values for the target namespace URI,
unless there is also an xsl:namespace-alias
declaration with the same literal namespace URI and
a higher import precedence.
[ERR XTSE0812] It is a static error
if a value other than #default
is specified
for either the stylesheet-prefix
or the
result-prefix
attributes of the xsl:namespace-alias
element when there is no in-scope binding for that
namespace prefix.
When a literal result element is processed, its namespace nodes are handled as follows:
A namespace node whose string value is a literal namespace URI is not copied to the result tree.
A namespace node whose string value is a target namespace URI is copied to the result tree, whether or not the URI identifies an excluded namespace.
In the event that the same URI is used as a literal namespace URI and a target namespace URI, the second of these rules takes precedence.
Note:
These rules achieve the effect that the element
generated from the literal result element will have an
in-scope namespace node that binds the
result-prefix
to the target namespace URI,
provided that the namespace declaration associating
this prefix with this URI is in scope for both the
xsl:namespace-alias
instruction and for the literal result element.
Conversely, the stylesheet-prefix
and the
literal namespace URI
will not normally appear in the result tree.
When literal result elements are being used to create element, attribute, or namespace nodes that use the XSLT namespace URI, the stylesheet may use an alias.
For example, the stylesheet
<xsl:stylesheet version="2.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:fo="http://www.w3.org/1999/XSL/Format" xmlns:axsl="file://namespace.alias"> <xsl:namespace-alias stylesheet-prefix="axsl" result-prefix="xsl"/> <xsl:template match="/"> <axsl:stylesheet version="2.0"> <xsl:apply-templates/> </axsl:stylesheet> </xsl:template> <xsl:template match="elements"> <axsl:template match="/"> <axsl:comment select="system-property('xsl:version')"/> <axsl:apply-templates/> </axsl:template> </xsl:template> <xsl:template match="block"> <axsl:template match="{.}"> <fo:block><axsl:apply-templates/></fo:block> </axsl:template> </xsl:template> </xsl:stylesheet>
will generate an XSLT stylesheet from a document of the form:
<elements> <block>p</block> <block>h1</block> <block>h2</block> <block>h3</block> <block>h4</block> </elements>
The output of the transformation will be a
stylesheet such as the following. Whitespace has been
added for clarity. Note that an implementation may
output different namespace prefixes from those
appearing in this example; however, the rules guarantee
that there will be a namespace node that binds the
prefix xsl
to the URI
http://www.w3.org/1999/XSL/Transform
,
which makes it safe to use the QName
xsl:version
in the content of the
generated stylesheet.
<xsl:stylesheet version="2.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:fo="http://www.w3.org/1999/XSL/Format"> <xsl:template match="/"> <xsl:comment select="system-property('xsl:version')"/> <xsl:apply-templates/> </xsl:template> <xsl:template match="p"> <fo:block><xsl:apply-templates/></fo:block> </xsl:template> <xsl:template match="h1"> <fo:block><xsl:apply-templates/></fo:block> </xsl:template> <xsl:template match="h2"> <fo:block><xsl:apply-templates/></fo:block> </xsl:template> <xsl:template match="h3"> <fo:block><xsl:apply-templates/></fo:block> </xsl:template> <xsl:template match="h4"> <fo:block><xsl:apply-templates/></fo:block> </xsl:template> </xsl:stylesheet>
Note:
It may be necessary also to use aliases for
namespaces other than the XSLT namespace URI. For
example, it can be useful to define an alias for the
namespace
http://www.w3.org/2001/XMLSchema-instance
,
so that the stylesheet can use the attributes
xsi:type
, xsi:nil
, and
xsi:schemaLocation
on a literal result
element, without running the risk that a schema
processor will interpret these as applying to the
stylesheet itself. Equally, literal result elements
belonging to a namespace dealing with digital
signatures might cause XSLT stylesheets to be
mishandled by general-purpose security software; using
an alias for the namespace would avoid the possibility
of such mishandling.
It is possible to define an alias for the XML namespace.
<xsl:stylesheet xmlns:axml="http://www.example.com/alias-xml" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="2.0"> <xsl:namespace-alias stylesheet-prefix="axml" result-prefix="xml"/> <xsl:template match="/"> <name axml:space="preserve"> <first>James</first> <xsl:text> </xsl:text> <last>Clark</last> </name> </xsl:template> </xsl:stylesheet>
produces the output:
<name xml:space="preserve"><first>James</first> <last>Clark</last></name>
This allows an xml:space
attribute to
be generated in the output without affecting the way
the stylesheet is parsed. The same technique can be
used for other attributes such as
xml:lang
, xml:base
, and
xml:id
.
Note:
Namespace aliasing is only necessary when literal
result elements are used. The problem of reserved
namespaces does not arise when using xsl:element
and
xsl:attribute
to
construct the result tree. Therefore, as an
alternative to using xsl:namespace-alias
,
it is always possible to achieve the desired effect by
replacing literal result elements with xsl:element
and
xsl:attribute
instructions.
xsl:element
<!-- Category: instruction
-->
<xsl:element
name = { qname }
namespace? = { uri-reference }
inherit-namespaces? = "yes" | "no"
use-attribute-sets? = qnames
type? = qname
validation? = "strict" | "lax" | "preserve" |
"strip">
<!-- Content:
sequence-constructor -->
</xsl:element>
The xsl:element
instruction
allows an element to be created with a computed name. The
expanded-QName of the element to
be created is specified by a required name
attribute and an
optional namespace
attribute.
The content of the xsl:element
instruction
is a sequence constructor for the
children, attributes, and namespaces of the created
element. The sequence obtained by evaluating this sequence
constructor (see 5.7
Sequence Constructors) is used to construct the
content of the element, as described in 5.7.1 Constructing
Complex Content.
The xsl:element
element may
have a use-attribute-sets
attribute, whose
value is a whitespace-separated list of QNames that
identify xsl:attribute-set
declarations. If this attribute is present, it is expanded
as described in 10.2 Named
Attribute Sets to produce a sequence of attribute
nodes. This sequence is prepended to the sequence produced
as a result of evaluating the sequence constructor, as
described in 5.7.1 Constructing
Complex Content.
The result of evaluating the xsl:element
instruction, except in error cases, is the newly
constructed element node.
The name
attribute is interpreted as an
attribute value
template, whose effective value must be a lexical QName.
[ERR XTDE0820] It is a non-recoverable dynamic
error if the effective value of the
name
attribute is not a lexical
QName.
[ERR XTDE0830] In the case of an
xsl:element
instruction with no namespace
attribute, it is
a non-recoverable dynamic
error if the effective value of the
name
attribute is a QName whose prefix is not declared in an
in-scope namespace declaration for the xsl:element
instruction.
If the namespace
attribute is not present
then the QName is
expanded into an expanded-QName using the namespace
declarations in effect for the xsl:element
element,
including any default namespace declaration.
If the namespace
attribute is present, then
it too is interpreted as an attribute value
template. The effective value
must be in the lexical
space of the xs:anyURI
type. If the
string is zero-length, then the expanded-QName of the element
has a null namespace URI. Otherwise, the string is used as
the namespace URI of the expanded-QName of the element to
be created. The local part of the lexical QName specified by the
name
attribute is used as the local part of
the expanded-QName of the element to
be created.
[ERR XTDE0835] It is a non-recoverable dynamic
error if the effective value of the
namespace
attribute is not in the lexical
space of the xs:anyURI
data type.
Note:
The XDM data model requires the name of a
node to be an instance of xs:QName
, and XML
Schema defines the namespace part of an
xs:QName
to be an instance of
xs:anyURI
. However, the schema
specification, and the specifications that it refers to,
give implementations some flexibility in how strictly
they enforce these constraints.
The prefix of the lexical QName specified in the
name
attribute (or the absence of a prefix) is
copied to the prefix part of the expanded-QName representing
the name of the new element node. In the event of a
conflict a prefix may subsequently be added, changed,
or removed during the namespace fixup process (see
5.7.3 Namespace
Fixup).
The xsl:element
instruction
has an optional inherit-namespaces
attribute,
with the value yes
or no
. The
default value is yes
. If the value is set to
yes
, or is omitted, then the namespace nodes
created for the newly constructed element (whether these
were copied from those of the source node, or generated as
a result of namespace fixup) are copied to the children and
descendants of the newly constructed element, as described
in 5.7.1
Constructing Complex Content. If the value is set
to no
, then these namespace nodes are not
automatically copied to the children. This may result in
namespace undeclarations (such as xmlns=""
or,
in the case of XML Namespaces 1.1, xmlns:p=""
)
appearing on the child elements when a final
result tree is serialized.
The base URI of the new element is copied from the base
URI of the xsl:element
instruction
in the stylesheet, unless the content of the new element
includes an xml:base
attribute, in which case
the base URI of the new element is the value of that
attribute, resolved (if it is a relative URI) against the
base URI of the xsl:element
instruction
in the stylesheet. (Note, however, that this is only
relevant when creating parentless elements. When the new
element is copied to form a child of an element or document
node, the base URI of the new copy is taken from that of
its new parent.)
The optional attributes type
and
validation
may be used on the xsl:element
instruction to invoke validation of the contents of the
element against a type definition or element declaration
in a schema, and to determine the type
annotation that the new element node will carry.
These attributes also affect the type annotation carried
by any elements and attributes that have the new element
node as an ancestor. These two attributes are both
optional, and if one is specified then the other
must be omitted. The permitted
values of these attributes and their semantics are
described in 19.2
Validation.
Note:
The final type annotation of the element in the
result
tree also depends on the type
and
validation
attributes of the instructions
used to create the ancestors of the element.
xsl:attribute
<!-- Category: instruction
-->
<xsl:attribute
name = { qname }
namespace? = { uri-reference }
select? = expression
separator? = { string }
type? = qname
validation? = "strict" | "lax" | "preserve" |
"strip">
<!-- Content:
sequence-constructor -->
</xsl:attribute>
The xsl:attribute
element
can be used to add attributes to result elements whether
created by literal result elements in the stylesheet or by
instructions such as xsl:element
or xsl:copy
. The expanded-QName of the attribute to
be created is specified by a required name
attribute and an
optional namespace
attribute. Except in
error cases, the result of evaluating an xsl:attribute
instruction is the newly constructed attribute node.
The string value of the new attribute node may be
defined either by using the select
attribute,
or by the sequence constructor that
forms the content of the xsl:attribute
element. These are mutually exclusive. If neither is
present, the value of the new attribute node will be a
zero-length string. The way in which the value is
constructed is specified in 5.7.2 Constructing Simple
Content.
[ERR XTSE0840] It is a static error if
the select
attribute of the xsl:attribute
element
is present unless the element has empty content.
If the separator
attribute is present, then
the effective value of this attribute
is used to separate adjacent items in the result sequence,
as described in 5.7.2 Constructing Simple
Content. In the absence of this attribute, the
default separator is a single space (#x20) when the content
is specified using the select
attribute, or a
zero-length string when the content is specified using a
sequence constructor.
The name
attribute is interpreted as an
attribute value
template, whose effective value must be a lexical QName.
[ERR XTDE0850] It is a non-recoverable dynamic
error if the effective value of the
name
attribute is not a lexical
QName.
[ERR XTDE0855] In the case of an
xsl:attribute
instruction with no namespace
attribute, it is
a non-recoverable dynamic
error if the effective value of the
name
attribute is the string
xmlns
.
[ERR XTDE0860] In the case of an
xsl:attribute
instruction with no namespace
attribute, it is
a non-recoverable dynamic
error if the effective value of the
name
attribute is a lexical QName whose prefix is
not declared in an in-scope namespace declaration for the
xsl:attribute
instruction.
If the namespace
attribute is not present,
then the lexical QName is expanded into an
expanded-QName using the namespace
declarations in effect for the xsl:attribute
element, not including any default namespace
declaration.
If the namespace
attribute is present, then
it too is interpreted as an attribute value
template. The effective value
must be in the lexical
space of the xs:anyURI
type. If the
string is zero-length, then the expanded-QName of the
attribute has a null namespace URI. Otherwise, the string
is used as the namespace URI of the expanded-QName of the attribute to
be created. The local part of the lexical QName specified by the
name
attribute is used as the local part of
the expanded-QName of the attribute to
be created.
[ERR XTDE0865] It is a non-recoverable dynamic
error if the effective value of the
namespace
attribute is not in the lexical
space of the xs:anyURI
data type.
Note:
The same considerations apply as for elements: [see ERR XTDE0835] in 11.2 Creating Element Nodes Using xsl:element .
The prefix of the lexical QName specified in the
name
attribute (or the absence of a prefix) is
copied to the prefix part of the expanded-QName representing
the name of the new attribute node. In the event of a
conflict this prefix (or absence of a prefix) may
subsequently be changed during the namespace fixup process
(see 5.7.3 Namespace
Fixup). If the attribute is in a non-null namespace
and no prefix is specified, then the namespace fixup
process will invent a prefix.
If the name of a constructed attribute is
xml:id
, the processor must perform
attribute value normalization by effectively applying the
normalize-space
FO
function to the value of the attribute, and the
resulting attribute node must be given the
is-id
property. This applies whether the
attribute is constructed using the xsl:attribute
instruction or whether it is constructed using an attribute
of a literal result element. This does not imply any
constraints on the value of the attribute, or on its
uniqueness, and it does not affect the type annotation
of the attribute, unless the containing document is
validated.
Note:
The effect of setting the is-id
property
is that the parent element can be located within the
containing document by use of the id
FO function. In effect, XSLT when
constructing a document performs some of the functions of
an xml:id
processor, as defined in [xml:id]; the other aspects of
xml:id
processing are performed during
validation.
The following instruction creates the attribute
colors="red green blue"
:
<xsl:attribute name="colors" select="'red', 'green', 'blue'"/>
It is not an error to write:
<xsl:attribute name="xmlns:xsl" namespace="file://some.namespace">http://www.w3.org/1999/XSL/Transform</xsl:attribute>
However, this will not result in the namespace
declaration
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
being output. Instead, it will produce an attribute node
with local name xsl
, and with a
system-allocated namespace prefix mapped to the namespace
URI file://some.namespace
. This is because
the namespace fixup process is not allowed to use
xmlns
as the name of a namespace node.
As described in 5.7.1 Constructing Complex Content, in a sequence that is used to construct the content of an element, any attribute nodes must appear in the sequence before any element, text, comment, or processing instruction nodes. Where the sequence contains two or more attribute nodes with the same expanded-QName, the one that comes last is the only one that takes effect.
Note:
If a collection of attributes is generated repeatedly, this can be done conveniently by using named attribute sets: see 10.2 Named Attribute Sets
The optional attributes type
and
validation
may be used on the xsl:attribute
instruction to invoke validation of the contents of the
attribute against a type definition or attribute
declaration in a schema, and to determine the type
annotation that the new attribute node will carry.
These two attributes are both optional, and if one is
specified then the other must
be omitted. The permitted values of these attributes and
their semantics are described in 19.2 Validation.
Note:
The final type annotation of the attribute
in the result tree also depends on the
type
and validation
attributes of the instructions used to create the
ancestors of the attribute.
This section describes three different ways of creating
text nodes: by means of literal text nodes in the
stylesheet, or by using the xsl:text
and xsl:value-of
instructions. It is also possible to create text nodes
using the xsl:number
instruction
described in 12 Numbering.
If and when the sequence that results from evaluating a sequence constructor is used to form the content of a node, as described in 5.7.2 Constructing Simple Content and 5.7.1 Constructing Complex Content, adjacent text nodes in the sequence are merged. Within the sequence itself, however, they exist as distinct nodes.
The following function returns a sequence of three text nodes:
<xsl:function name="f:wrap"> <xsl:param name="s"/> <xsl:text>(</xsl:text> <xsl:value-of select="$s"/> <xsl:text>)</xsl:text> </xsl:function>
When this function is called as follows:
<xsl:value-of select="f:wrap('---')"/>
the result is:
(---)
No additional spaces are inserted, because the calling
xsl:value-of
instruction merges adjacent text nodes before atomizing
the sequence. However, the result of the instruction:
<xsl:value-of select="data(f:wrap('---'))"/>
is:
( --- )
because in this case the three text nodes are atomized to form three strings, and spaces are inserted between adjacent strings.
It is possible to construct text nodes whose string value is zero-length. A zero-length text node, when atomized, produces a zero-length string. However, zero-length text nodes are ignored when they appear in a sequence that is used to form the content of a node, as described in 5.7.1 Constructing Complex Content and 5.7.2 Constructing Simple Content.
A sequence constructor can contain text nodes. Each text node in a sequence constructor remaining after whitespace text nodes have been stripped as specified in 4.2 Stripping Whitespace from the Stylesheet will construct a new text node with the same string value. The resulting text node is added to the result of the containing sequence constructor.
Text is processed at the tree level. Thus, markup of
<
in a template will be represented
in the stylesheet tree by a text node that includes the
character <
. This will create a text node
in the result tree that contains a
<
character, which will be represented by
the markup <
(or an equivalent
character reference) when the result tree is serialized
as an XML document, unless otherwise specified using
character maps (see 20.1 Character Maps) or
disable-output-escaping
(see 20.2 Disabling Output
Escaping).
xsl:text
<!-- Category: instruction
-->
<xsl:text
[disable-output-escaping]? = "yes" |
"no">
<!-- Content: #PCDATA -->
</xsl:text>
The xsl:text
element is evaluated to contruct a new text node. The
content of the xsl:text
element is a
single text node whose value forms the string value
of the new text node. An xsl:text
element may be
empty, in which case the result of evaluating the
instruction is a text node whose string value is
the zero-length string.
The result of evaluating an xsl:text
instruction is
the newly constructed text node.
A text node that is an immediate child of an xsl:text
instruction
will not be stripped from the stylesheet tree, even if it
consists entirely of whitespace (see 4.4 Stripping Whitespace from a Source
Tree).
For the effect of the deprecated
disable-output-escaping
attribute, see
20.2 Disabling
Output Escaping
Note:
It is not always necessary to use the xsl:text
instruction
to write text nodes to the result tree. Literal text can be
written to the result tree by including it anywhere in
a sequence constructor,
while computed text can be output using the xsl:value-of
instruction. The principal reason for using xsl:text
is that it
offers improved control over whitespace handling.
xsl:value-of
Within a sequence constructor, the
xsl:value-of
instruction can be used to generate computed text nodes.
The xsl:value-of
instruction computes the text using an expression that is
specified as the value of the select
attribute, or by means of contained instructions. This
might, for example, extract text from a source tree or
insert the value of a variable.
<!-- Category:
instruction -->
<xsl:value-of
select? = expression
separator? = { string }
[disable-output-escaping]? = "yes" |
"no">
<!-- Content:
sequence-constructor -->
</xsl:value-of>
The xsl:value-of
instruction is evaluated to construct a new text node;
the result of the instruction is the newly constructed
text node.
The string value of the new text node may be defined
either by using the select
attribute, or by
the sequence constructor (see
5.7 Sequence
Constructors) that forms the content of the
xsl:value-of
element. These are mutually exclusive, and one of them
must be present. The way in which the value is
constructed is specified in 5.7.2 Constructing
Simple Content.
[ERR XTSE0870] It is a static error
if the select
attribute of the xsl:value-of
element
is present when the content of the element is non-empty,
or if the select
attribute is absent when
the content is empty.
If the separator
attribute is present,
then the effective value of this
attribute is used to separate adjacent items in the
result sequence, as described in 5.7.2 Constructing
Simple Content. In the absence of this attribute,
the default separator is a single space (#x20) when the
content is specified using the select
attribute, or a zero-length string when the content is
specified using a sequence constructor.
Special rules apply when backwards compatible
behavior is enabled for the instruction. If no
separator
attribute is present, and if the
select
attribute is present, then all items
in the atomized result sequence other than
the first are ignored.
The instruction:
<x><xsl:value-of select="1 to 4" separator="|"/></x>
produces the output:
<x>1|2|3|4</x>
Note:
The xsl:copy-of
element
can be used to copy a sequence of nodes to the
result
tree without atomization. See 11.9.2 Deep Copy.
For the effect of the deprecated
disable-output-escaping
attribute, see
20.2 Disabling
Output Escaping
<!-- Category: instruction
-->
<xsl:document
validation? = "strict" | "lax" | "preserve" |
"strip"
type? = qname>
<!-- Content:
sequence-constructor -->
</xsl:document>
The xsl:document
instruction is used to create a new document node. The
content of the xsl:document
element
is a sequence constructor for the
children of the new document node. A document node is
created, and the sequence obtained by evaluating the
sequence constructor is used to construct the content of
the document, as described in 5.7.1 Constructing
Complex Content. The temporary tree rooted at this
document node forms the result tree.
Except in error situations, the result of evaluating the
xsl:document
instruction is a single node, the newly constructed
document node.
Note:
The new document is not serialized. To construct a
document that is to form a final result rather than an
intermediate result, use the xsl:result-document
instruction described in 19.1 Creating Final Result
Trees.
The optional attributes type
and
validation
may be used on the xsl:document
instruction to validate the contents of the new document,
and to determine the type annotation that elements and
attributes within the result tree will carry. The permitted
values and their semantics are described in 19.2.2 Validating Document
Nodes.
The base URI of the new document node is taken from the
base URI of the xsl:document
instruction.
The document-uri
and
unparsed-entities
properties of the new
document node are set to empty.
The following example creates a temporary tree held in
a variable. The use of an enclosed xsl:document
instruction ensures that uniqueness constraints defined
in the schema for the relevant elements are checked.
<xsl:variable name="tree" as="document-node()"> <xsl:document validation="strict"> <xsl:apply-templates/> </xsl:document> </xsl:variable>
<!--
Category: instruction -->
<xsl:processing-instruction
name = { ncname }
select? = expression>
<!-- Content:
sequence-constructor -->
</xsl:processing-instruction>
The xsl:processing-instruction
element is evaluated to create a processing instruction
node.
The xsl:processing-instruction
element has a required
name
attribute that specifies the name of the
processing instruction node. The value of the
name
attribute is interpreted as an attribute value
template.
The string value of the new processing-instruction node
may be defined either by using the select
attribute, or by the sequence constructor that
forms the content of the xsl:processing-instruction
element. These are mutually exclusive. If neither is
present, the string value of the new processing-instruction
node will be a zero-length string. The way in which the
value is constructed is specified in 5.7.2 Constructing Simple
Content.
[ERR XTSE0880] It is a static error if
the select
attribute of the xsl:processing-instruction
element is present unless the element has empty
content.
Except in error situations, the result of evaluating the
xsl:processing-instruction
instruction is a single node, the newly constructed
processing instruction node.
This instruction:
<xsl:processing-instruction name="xml-stylesheet" select="('href="book.css"', 'type="text/css")"/>
creates the processing instruction
<?xml-stylesheet href="book.css" type="text/css"?>
Note that the xml-stylesheet
processing
instruction contains pseudo-attributes in the
form name="value"
. Although these have the
same textual form as attributes in an element start tag,
they are not represented as XDM attribute
nodes, and cannot therefore be constructed using xsl:attribute
instructions.
[ERR XTDE0890] It is a non-recoverable dynamic
error if the effective value of the
name
attribute is not both an NCName
Names and a PITarget
XML.
Note:
Because these rules disallow the name
xml
, the xsl:processing-instruction
cannot be used to output an XML declaration. The xsl:output
declaration
should be used to control this instead (see 20 Serialization).
If the result of evaluating the content of the xsl:processing-instruction
contains the string ?>
, this string is
modified by inserting a space between the ?
and >
characters.
The base URI of the new processing-instruction is copied
from the base URI of the xsl:processing-instruction
element in the stylesheet. (Note, however, that this is
only relevant when creating a parentless processing
instruction. When the new processing instruction is copied
to form a child of an element or document node, the base
URI of the new copy is taken from that of its new
parent.)
<!-- Category: instruction
-->
<xsl:namespace
name = { ncname }
select? = expression>
<!-- Content:
sequence-constructor -->
</xsl:namespace>
The xsl:namespace
element
is evaluated to create a namespace node. Except in error
situations, the result of evaluating the xsl:namespace
instruction is a single node, the newly constructed
namespace node.
The xsl:namespace
element
has a required name
attribute that specifies the name of the namespace node
(that is, the namespace prefix). The value of the
name
attribute is interpreted as an attribute value
template. If the effective value of the
name
attribute is a zero-length string, a
namespace node is added for the default namespace.
The string value of the new namespace node (that is, the
namespace URI) may be defined either by using the
select
attribute, or by the sequence constructor that
forms the content of the xsl:namespace
element. These are mutually exclusive. Since the string
value of a namespace node cannot be a zero-length string,
one of them must be present. The way in which the value is
constructed is specified in 5.7.2 Constructing Simple
Content.
[ERR XTDE0905] It is a non-recoverable dynamic
error if the string value of the new namespace node is
not valid in the lexical space of the data type
xs:anyURI
. [see ERR XTDE0835]
[ERR XTSE0910] It is a static error if
the select
attribute of the xsl:namespace
element
is present when the element has content other than one or
more xsl:fallback
instructions, or if the select
attribute is
absent when the element has empty content.
Note the restrictions described in 5.7.1 Constructing Complex Content for the position of a namespace node relative to other nodes in the node sequence returned by a sequence constructor.
This literal result element:
<data xsi:type="xs:integer" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <xsl:namespace name="xs" select="'http://www.w3.org/2001/XMLSchema'"/> <xsl:text>42</xsl:text> </data>
would typically cause the output document to contain the element:
<data xsi:type="xs:integer" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">42</data>
In this case, the element is constructed using a
literal result element, and the namespace
xmlns:xs="http://www.w3.org/2001/XMLSchema"
could therefore have been added to the result tree
simply by declaring it as one of the in-scope namespaces
in the stylesheet. In practice, the xsl:namespace
instruction is more likely to be useful in situations
where the element is constructed using an xsl:element
instruction, which does not copy all the in-scope
namespaces from the stylesheet.
[ERR XTDE0920] It is a non-recoverable dynamic
error if the effective value of the
name
attribute is neither a zero-length string
nor an NCName
Names, or if it is
xmlns
.
[ERR XTDE0925] It is a non-recoverable dynamic
error if the xsl:namespace
instruction generates a namespace node whose name is
xml
and whose string value is not
http://www.w3.org/XML/1998/namespace
, or a
namespace node whose string value is
http://www.w3.org/XML/1998/namespace
and whose
name is not xml
.
[ERR XTDE0930] It is a non-recoverable dynamic
error if evaluating the select
attribute or the contained sequence constructor of
an xsl:namespace
instruction results in a zero-length string.
For details of other error conditions that may arise, see 5.7 Sequence Constructors.
Note:
It is rarely necessary to use xsl:namespace
to
create a namespace node in the result tree; in most
circumstances, the required namespace nodes will be
created automatically, as a side-effect of writing
elements or attributes that use the namespace. An example
where xsl:namespace
is
needed is a situation where the required namespace is
used only within attribute values in the result document,
not in element or attribute names; especially where the
required namespace prefix or namespace URI is computed at
run-time and is not present in either the source document
or the stylesheet.
Adding a namespace node to the result tree will never change the expanded-QName of any element or attribute node in the result tree: that is, it will never change the namespace URI of an element or attribute. It might, however, constrain the choice of prefixes when namespace fixup is performed.
Namespace prefixes for element and attribute names are effectively established by the namespace fixup process described in 5.7.3 Namespace Fixup. The fixup process ensures that an element has in-scope namespace nodes for the namespace URIs used in the element name and in its attribute names, and the serializer will typically use these namespace nodes to determine the prefix to use in the serialized output. The fixup process cannot generate namespace nodes that are inconsistent with those already present in the tree. This means that it is not possible for the processor to decide the prefix to use for an element or for any of its attributes until all the namespace nodes for the element have been added.
If a namespace prefix is mapped to a particular
namespace URI using the xsl:namespace
instruction, or by using xsl:copy
or xsl:copy-of
to copy a
namespace node, this prevents the namespace fixup process
(and hence the serializer) from using the same prefix for
a different namespace URI on the same element.
Given the instruction:
<xsl:element name="p:item" xmlns:p="http://www.example.com/p"> <xsl:namespace name="p">http://www.example.com/q</xsl:namespace> </xsl:element>
a possible serialization of the result tree is:
<ns0:item xmlns:ns0="http://www.example.com/p" xmlns:p="http://www.example.com/q"/>
The processor must invent a namespace prefix for the
URI p.uri
; it cannot use the prefix
p
because that prefix has been explicitly
associated with a different URI.
Note:
The xsl:namespace
instruction cannot be used to generate a namespace
undeclaration of the form xmlns=""
(nor
the new forms of namespace undeclaration permitted in
[Namespaces in XML 1.1]).
Namespace undeclarations are generated automatically by
the serializer if
undeclare-prefixes="yes"
is
specified on xsl:output
, whenever a
parent element has a namespace node for the default
namespace prefix, and a child element has no namespace
node for that prefix.
<!-- Category: instruction
-->
<xsl:comment
select? = expression>
<!-- Content:
sequence-constructor -->
</xsl:comment>
The xsl:comment
element is
evaluated to contruct a new comment node. Except in error
cases, the result of evaluating the xsl:comment
instruction
is a single node, the newly constructed comment node.
The string value of the new comment node may be defined
either by using the select
attribute, or by
the sequence constructor that
forms the content of the xsl:comment
element.
These are mutually exclusive. If neither is present, the
value of the new comment node will be a zero-length string.
The way in which the value is constructed is specified in
5.7.2
Constructing Simple Content.
[ERR XTSE0940] It is a static error if
the select
attribute of the xsl:comment
element is
present unless the element has empty content.
For example, this
<xsl:comment>This file is automatically generated. Do not edit!</xsl:comment>
would create the comment
<!--This file is automatically generated. Do not edit!-->
In the generated comment node, the processor
must insert a space after any
occurrence of -
that is followed by another
-
or that ends the comment.
<!-- Category: instruction
-->
<xsl:copy
copy-namespaces? = "yes" | "no"
inherit-namespaces? = "yes" | "no"
use-attribute-sets? = qnames
type? = qname
validation? = "strict" | "lax" | "preserve" |
"strip">
<!-- Content:
sequence-constructor -->
</xsl:copy>
The xsl:copy
instruction provides a way of copying the context item.
If the context item is a node, evaluating
the xsl:copy
instruction constructs a copy of the context node, and
the result of the xsl:copy
instruction is
this newly constructed node. By default, the
namespace nodes of the context node are automatically
copied as well, but the attributes and children of the
node are not automatically copied.
When the context item is an atomic value,
the xsl:copy
instruction returns this value. The sequence constructor, if
present, is not evaluated.
When the context item is an attribute node,
text node, comment node, processing instruction node, or
namespace node, the xsl:copy
instruction
returns a new node that is a copy of the context node.
The new node will have the same node kind, name, and
string value as the context node. In the case of an
attribute node, it will also have the same values for the
is-id
and is-idrefs
properties. The sequence constructor,
if present, is not evaluated.
When the context item is a document node or
element node, the xsl:copy
instruction
returns a new node that has the same node kind and name
as the context node. The content of the new node is
formed by evaluating the sequence constructor
contained in the xsl:copy
instruction. The sequence obtained by evaluating
this sequence constructor is used (after prepending any
attribute nodes or namespace nodes as described in the
following paragraphs) to construct the content of the
document or element node, as described in 5.7.1 Constructing
Complex Content.
The identity transformation can be written using
xsl:copy
as
follows:
<xsl:template match="@*|node()"> <xsl:copy> <xsl:apply-templates select="@*|node()"/> </xsl:copy> </xsl:template>
This template rule can be used to copy any node in a
tree by applying template rules to its attributes and
children. It can be combined with additional template
rules that modify selected nodes, for example if all
nodes are to be copied except note
elements and their contents, this can be achieved by
using the identity template rule together with the
template rule:
<xsl:template match="note"/>
Note:
The xsl:copy
instruction
is most useful when copying element nodes. In other
cases, the xsl:copy-of
instruction is more flexible, because it has a
select
attribute allowing selection of the
nodes or values to be copied.
The xsl:copy
instruction has an optional
use-attribute-sets
attribute, whose value is
a whitespace-separated list of QNames that
identify xsl:attribute-set
declarations. This attribute is used only when copying
element nodes. This list is expanded as described in
10.2 Named Attribute
Sets to produce a sequence of attribute nodes.
This sequence is prepended to the sequence produced as a
result of evaluating the sequence
constructor.
The xsl:copy
instruction has an optional copy-namespaces
attribute, with the value yes
or
no
. The default value is yes
.
The attribute is used only when copying element nodes. If
the value is set to yes
, or is omitted, then
all the namespace nodes of the source element are copied
as namespace nodes for the result element. These copied
namespace nodes are prepended to the sequence produced as
a result of evaluating the sequence constructor (it
is immaterial whether they come before or after any
attribute nodes produced by expanding the
use-attribute-sets
attribute). If the value
is set to no
, then the namespace nodes are
not copied. However, namespace nodes will still be added
to the result element as required by the namespace fixup process:
see 5.7.3 Namespace
Fixup.
The xsl:copy
instruction has an optional
inherit-namespaces
attribute, with the value
yes
or no
. The default value is
yes
. The attribute is used only when copying
element nodes. If the value is set to yes
,
or is omitted, then the namespace nodes created for the
newly constructed element (whether these were copied from
those of the source node, or generated as a result of
namespace fixup) are copied to the children and
descendants of the newly constructed element, as
described in 5.7.1 Constructing
Complex Content. If the value is set to
no
, then these namespace nodes are not
automatically copied to the children. This may result in
namespace undeclarations (such as xmlns=""
or, in the case of XML Namespaces 1.1,
xmlns:p=""
) appearing on the child elements
when a final result tree is
serialized.
[ERR XTTE0950] It is a type error to use
the xsl:copy
or
xsl:copy-of
instruction to copy a node that has namespace-sensitive
content if the copy-namespaces
attribute has
the value no
and its explicit or implicit
validation
attribute has the value
preserve
. It is also a type error if either
of these instructions (with
validation="preserve"
) is used to copy an
attribute having namespace-sensitive content, unless the
parent element is also copied. A node has
namespace-sensitive content if its typed value contains
an item of type xs:QName
or
xs:NOTATION
or a type derived therefrom. The
reason this is an error is because the validity of the
content depends on the namespace context being
preserved.
Note:
When attribute nodes are copied, whether with
xsl:copy
or
with xsl:copy-of
, the
processor does not automatically copy any associated
namespace information. The namespace used in the
attribute name itself will be declared by virtue of the
namespace fixup process (see 5.7.3 Namespace Fixup)
when the attribute is added to an element in the
result
tree, but if namespace prefixes are
used in the content of the attribute (for example, if
the value of the attribute is an XPath expression) then
it is the responsibility of the stylesheet author to
ensure that suitable namespace nodes are added to the
result
tree. This can be achieved by copying the namespace
nodes using xsl:copy
, or by
generating them using xsl:namespace
.
The optional attributes type
and
validation
may be used on the xsl:copy
instruction to
validate the contents of an element, attribute or
document node against a type definition, element
declaration, or attribute declaration in a schema, and
thus to determine the type annotation that the new copy of
an element or attribute node will carry. These attributes
are ignored when copying an item that is not an element,
attribute or document node. When the node being copied is
an element or document node, these attributes also affect
the type annotation carried by any elements and
attributes that have the copied element or document node
as an ancestor. These two attributes are both optional,
and if one is specified then the other must be omitted. The permitted values of
these attributes and their semantics are described in
19.2 Validation.
Note:
The final type annotation of the node in the
result
tree also depends on the type
and
validation
attributes of the instructions
used to create the ancestors of the node.
The base URI of a node is copied, except in the
case of an element node having an xml:base
attribute, in which case the base URI of the new node is
taken as the value of the xml:base
attribute, resolved if it is relative against the base
URI of the xsl:copy
instruction. If the copied node is subsequently
attached as a child to a new element or document
node, the final copy of the node inherits its base
URI from its parent node, unless this is overridden using
an xml:base
attribute.
When an xml:id
attribute is copied, using
either the xsl:copy
or xsl:copy-of
instruction, it is implementation-defined
whether the value of the attribute is subjected to
attribute value normalization (that is, effectively
applying the
normalize-space
FO
function).
Note:
In most cases the value will already have been subjected to attribute value normalization on the source tree, but if this processing has not been performed on the source tree, it is not an error for it to be performed on the result tree.
<!-- Category: instruction
-->
<xsl:copy-of
select = expression
copy-namespaces? = "yes" | "no"
type? = qname
validation? = "strict" | "lax" | "preserve" |
"strip" />
The xsl:copy-of
instruction can be used to construct a copy of a sequence
of nodes and/or atomic values, with each new
node containing copies of all the children, attributes,
and (by default) namespaces of the original node,
recursively. The result of evaluating the instruction is
a sequence of items corresponding one-to-one
with the supplied sequence, and retaining its order.
The required
select
attribute contains an expression,
whose value may be any sequence of nodes and atomic
values. The items in this sequence are processed
as follows:
If the item is an element node, a new element is constructed and appended to the result sequence. The new element will have the same expanded-QName as the original, and it will have deep copies of the attribute nodes and children of the element node.
The new element will also have namespace nodes
copied from the original element node, unless they
are excluded by specifying
copy-namespaces="no"
. If this attribute
is omitted, or takes the value yes
, then
all the namespace nodes of the original element are
copied to the new element. If it takes the value
no
, then none of the namespace nodes are
copied: however, namespace nodes will still be
created in the result tree as required by the namespace fixup
process: see 5.7.3
Namespace Fixup. This attribute affects all
elements copied by this instruction: both elements
selected directly by the select
expression, and elements that
are descendants of nodes selected by the
select
expression.
The new element will have the same values of the
is-id
, is-idrefs
, and
nilled
properties as the original
element.
If the item is a document node, the instruction adds a new document node to the result sequence; the children of this document node will be one-to-one copies of the children of the original document node (each copied according to the rules for its own node kind).
If the item is an attribute or namespace node, or
a text node, a comment, or a processing instruction,
the same rules apply as with xsl:copy
(see
11.9.1 Shallow
Copy).
If the item is an atomic value, the value is
appended to the result sequence, as with xsl:sequence
.
The optional attributes type
and
validation
may be used on the xsl:copy-of
instruction to validate the contents of an element,
attribute or document node against a type definition,
element declaration, or attribute declaration in a schema
and thus to determine the type annotation that the new
copy of an element or attribute node will carry. These
attributes are applied individually to each element,
attribute, and document node that is selected by the
expression in the select
attribute. These
attributes are ignored when copying an item that is not
an element, attribute or document node.
The specified type
and
validation
apply directly only to elements,
attributes and document nodes created as copies of nodes
actually selected by the select
expression,
they do not apply to nodes that are implicitly copied
because they have selected nodes as an ancestor. However,
these attributes do indirectly affect the type
annotation carried by such implicitly copied nodes,
as a consequence of the validation process.
These two attributes are both optional, and if one is specified then the other must be omitted. The permitted values of these attributes and their semantics are described in 19.2 Validation.
Errors may occur when copying namespace-sensitive
elements or attributes using
validation="preserve"
. [see ERR
XTTE0950].
The base URI of a node is copied, except in the
case of an element node having an xml:base
attribute, in which case the base URI of the new node is
taken as the value of the xml:base
attribute, resolved if it is relative against the base
URI of the xsl:copy-of
instruction. If the copied node is subsequently
attached as a child to a new element or document
node, the final copy of the node inherits its base
URI from its parent node, unless this is overridden using
an xml:base
attribute.
<!-- Category: instruction
-->
<xsl:sequence
select = expression>
<!-- Content: xsl:fallback* -->
</xsl:sequence>
The xsl:sequence
instruction may be used within a sequence constructor to
construct a sequence of nodes and/or atomic values. This
sequence is returned as the result of the instruction.
Unlike most other instructions, xsl:sequence
can
return a sequence containing existing nodes, rather than
constructing new nodes. When xsl:sequence
is used
to add atomic values to a sequence, the effect is very
similar to the xsl:copy-of
instruction.
The items comprising the result sequence are selected
using the select
attribute.
Any contained xsl:fallback
instructions are ignored by an XSLT 2.0 processor, but can
be used to define fallback behavior for an XSLT 1.0
processor running in forwards compatibility mode.
For example, the following code:
<xsl:variable name="values" as="xs:integer*"> <xsl:sequence select="(1,2,3,4)"/> <xsl:sequence select="(8,9,10)"/> </xsl:variable> <xsl:value-of select="sum($values)"/>
produces the output: 37
The following code constructs a sequence containing
the value of the @price
attribute for
selected elements (which we assume to be typed as
xs:decimal
), or a computed price for those
elements that have no @price
attribute. It
then returns the average price:
<xsl:variable name="prices" as="xs:decimal*"> <xsl:for-each select="//product"> <xsl:choose> <xsl:when test="@price"> <xsl:sequence select="@price"/> </xsl:when> <xsl:otherwise> <xsl:sequence select="@cost * 1.5"/> </xsl:otherwise> </xsl:choose> </xsl:for-each> </xsl:variable> <xsl:value-of select="avg($prices)"/>
Note that the existing @price
attributes
could equally have been added to the $prices
sequence using xsl:copy-of
or
xsl:value-of
.
However, xsl:copy-of
would
create a copy of the attribute node, which is not needed
in this situation, while xsl:value-of
would
create a new text node, which then has to be converted to
an xs:decimal
. Using xsl:sequence
, which
in this case atomizes the existing attribute node and
adds an xs:decimal
atomic value to the
result sequence, is a more direct way of achieving the
same result.
This example could alternatively be solved at the XPath level:
<xsl:value-of select="avg(//product/(+@price, @cost*1.5)[1])"/>
(The apparently redundant +
operator is
there to atomize the attribute value: the expression on
the right hand side of the /
operator must
not return a mixture of nodes and atomic values.)
<!-- Category: instruction
-->
<xsl:number
value? = expression
select? = expression
level? = "single" | "multiple" | "any"
count? = pattern
from? = pattern
format? = { string }
lang? = { nmtoken }
letter-value? = { "alphabetic" | "traditional"
}
ordinal? = { string }
grouping-separator? = { char }
grouping-size? = { number
} />
The xsl:number
instruction is used to create a formatted number. The result
of the instruction is a newly constructed text node
containing the formatted number as its string value.
[Definition: The xsl:number
instruction
performs two tasks: firstly, determining a place
marker (this is a sequence of integers, to allow for
hierarchic numbering schemes such as 1.12.2
or
3(c)ii
), and secondly, formatting the place
marker for output as a text node in the result
sequence.] The place marker
to be formatted can either be supplied directly, in the
value
attribute, or it can be computed based on
the position of a selected node within the tree
that contains it.
[ERR XTSE0975] It is a static error if
the value
attribute of xsl:number
is present
unless the select
, level
,
count
, and from
attributes are all
absent.
Note:
The facilities described in this section are
specifically designed to enable the calculation and
formatting of section numbers, paragraph numbers, and the
like. For formatting of other numeric quantities, the
format-number
function may be more suitable: see 16.4 Number Formatting.
The place marker to be formatted may be
specified by an expression. The value
attribute contains the expression. The value of this
expression is atomized using the procedure defined
in [XPath 2.0], and each value
$V in the atomized sequence is then
converted to the integer value returned by the XPath
expression
xs:integer(round(number($V)))
. The
resulting sequence of integers is used as the place marker
to be formatted.
If backwards compatible behavior is enabled for the instruction, then:
all items in the atomized sequence after the first are discarded;
If the atomized sequence is empty, it is replaced by
a sequence containing the xs:double
value
NaN
as its only item;
If any value in the sequence cannot be converted to
an integer (this includes the case where the sequence
contains a NaN
value) then the string
NaN
is inserted into the formatted result
string in its proper position. The error described in
the following paragraph does not apply in this
case.
[ERR XTDE0980] It is a non-recoverable dynamic
error if any undiscarded item in the atomized sequence
supplied as the value of the value
attribute
of xsl:number
cannot be converted to an integer, or if the resulting
integer is less than 0 (zero).
Note:
The value zero does not arise when numbering nodes in
a source document, but it can arise in other numbering
sequences. It is permitted specifically because the rules
of the xsl:number
instruction
are also invoked by functions such as format-time
: the
minutes and seconds component of a time value can
legitimately be zero.
The resulting sequence is formatted as a string using
the effective values of the
attributes specified in 12.3 Number
to String Conversion Attributes; each of these
attributes is interpreted as an attribute value
template. After conversion, the xsl:number
element
constructs a new text node containing the resulting string,
and returns this node.
If no value
attribute is specified, then
the xsl:number
instruction returns a new text node containing a formatted
place
marker that is based on the position of a
selected node within its containing document. If the
select
attribute is present, then the
expression contained in the select
attribute
is evaluated to determine the selected node. If the
select
attribute is omitted, then the selected
node is the context node.
[ERR XTTE0990] It is a type error if the
xsl:number
instruction is evaluated, with no value
or
select
attribute, when the context item is
not a node.
[ERR XTTE1000] It is a type error if the
result of evaluating the select
attribute of
the xsl:number
instruction is anything other than a single node.
The following attributes control how the selected node is to be numbered:
The level
attribute specifies rules for
selecting the nodes that are taken into account in
allocating a number; it has the values
single
, multiple
or
any
. The default is
single
.
The count
attribute is a pattern that specifies
which nodes are to be counted at those levels. If
count
attribute is not specified, then it
defaults to the pattern that matches any node with the
same node kind as the
selected node and, if the
selected node has an expanded-QName, with the same
expanded-QName as the
selected node.
The from
attribute is a pattern that specifies
where counting starts.
In addition, the attributes specified in 12.3 Number to String Conversion
Attributes are used for number to string
conversion, as in the case when the value
attribute is specified.
The xsl:number
element first
constructs a sequence of positive integers using the
level
, count
and
from
attributes. Where level
is
single
or any
, this sequence will
either be empty or contain a single number; where
level
is multiple
, the sequence
may be of any length. The sequence is constructed as
follows:
Let matches-count($node)
be a function that
returns true if and only if the given node
$node
matches the pattern given in the
count
attribute, or the implied pattern
(according to the rules given above) if the
count
attribute is omitted.
Let matches-from($node)
be a function that
returns true if and only if the given node
$node
matches the pattern given in the
from
attribute, or if $node
is the root node of a tree. If the from
attribute is omitted, then the function returns true if and
only if $node
is the root node of a
tree.
Let $S
be the selected node.
When level="single"
:
Let $A
be the node sequence selected by
the following expression:
$S/ancestor-or-self::node()[matches-count(.)][1]
(this selects the innermost ancestor-or-self node
that matches the count
pattern)
Let $F
be the node sequence selected by
the expression
$S/ancestor-or-self::node()[matches-from(.)][1]
(this selects the innermost ancestor-or-self node
that matches the from
pattern):
Let $AF
be the value of:
$A[ancestor-or-self::node()[.
is $F]]
(this selects $A if it is in the subtree rooted at $F, or the empty sequence otherwise)
If $AF
is empty, return the empty
sequence, ()
Otherwise return the value of:
1 +
count($AF/preceding-sibling::node()[matches-count(.)])
(the number of preceding siblings of the counted
node that match the count
pattern, plus
one).
When level="multiple"
:
Let $A
be the node sequence selected by
the expression
$S/ancestor-or-self::node()[matches-count(.)]
(the set of ancestor-or-self nodes that match the
count
pattern)
Let $F
be the node sequence selected by
the expression
$S/ancestor-or-self::node()[matches-from(.)][1]
(the innermost ancestor-or-self node that matches
the from
pattern)
Let $AF
be the value of
$A[ancestor-or-self::node()[.
is $F]]
(the nodes selected in the first step that are in the subtree rooted at the node selected in the second step)
Return the result of the expression
for $af in $AF return
1+count($af/preceding-sibling::node()[matches-count(.)])
(a sequence of integers containing, for each of
these nodes, one plus the number of preceding siblings
that match the count
pattern)
When level="any"
:
Let $A
be the node sequence selected by
the expression
$S/(preceding::node()|ancestor-or-self::node())[matches-count(.)]
(the set of nodes consisting of the selected node
together with all nodes, other than attributes and
namespaces, that precede the selected node in document
order, provided that they match the count
pattern)
Let $F
be the node sequence selected by
the expression
$S/(preceding::node()|ancestor::node())[matches-from(.)][last()]
(the last node in document order that matches the
from
pattern and that precedes the
selected node, using the same definition)
Let $AF
be the node sequence $A[.
is $F or . >> $F]
.
(the nodes selected in the first step, excluding those that precede the node selected in the second step)
If $AF
is empty, return the empty
sequence, ()
Otherwise return the value of the expression
count($AF)
The sequence of numbers (the place marker) is then converted
into a string using the effective values of the
attributes specified in 12.3 Number
to String Conversion Attributes; each of these
attributes is interpreted as an attribute value
template. After conversion, the resulting string is
used to create a text node, which forms the result of
the xsl:number
instruction.
The following will number the items in an ordered list:
<xsl:template match="ol/item"> <fo:block> <xsl:number/> <xsl:text>. </xsl:text> <xsl:apply-templates/> </fo:block> </xsl:template>
The following two rules will number title
elements. This is intended for a document that contains a
sequence of chapters followed by a sequence of
appendices, where both chapters and appendices contain
sections, which in turn contain subsections. Chapters are
numbered 1, 2, 3; appendices are numbered A, B, C;
sections in chapters are numbered 1.1, 1.2, 1.3; sections
in appendices are numbered A.1, A.2, A.3.
Subsections within a chapter are numbered 1.1.1,
1.1.2, 1.1.3; subsections within an appendix are numbered
A.1.1, A.1.2, A.1.3.
<xsl:template match="title"> <fo:block> <xsl:number level="multiple" count="chapter|section|subsection" format="1.1 "/> <xsl:apply-templates/> </fo:block> </xsl:template> <xsl:template match="appendix//title" priority="1"> <fo:block> <xsl:number level="multiple" count="appendix|section|subsection" format="A.1 "/> <xsl:apply-templates/> </fo:block> </xsl:template>
The following attributes are used to control conversion of a sequence of numbers into a string. The numbers are integers greater than or equal to 0 (zero). The attributes are all optional.
The main attribute is format
. The default
value for the format
attribute is
1
. The format
attribute is split
into a sequence of tokens where each token is a maximal
sequence of alphanumeric characters or a maximal sequence
of non-alphanumeric characters. Alphanumeric means
any character that has a Unicode category of Nd, Nl, No,
Lu, Ll, Lt, Lm or Lo. The alphanumeric tokens (format
tokens) indicate the format to be used for each number
in the sequence; in most cases the format token is the same
as the required representation of the number 1 (one).
Each non-alphanumeric token is either a prefix, a separator, or a suffix. If there is a non-alphanumeric token but no format token, then the single non-alphanumeric token is used as both the prefix and the suffix. The prefix, if it exists, is the non-alphanumeric token that precedes the first format token: the prefix always appears exactly once in the constructed string, at the start. The suffix, if it exists, is the non-alphanumeric token that follows the last format token: the suffix always appears exactly once in the constructed string, at the end. All other non-alphanumeric tokens (those that occur between two format tokens) are separator tokens and are used to separate numbers in the sequence.
The nth format token is used to format the
nth number in the sequence. If there are more
numbers than format tokens, then the last format token is
used to format remaining numbers. If there are no format
tokens, then a format token of 1
is used to
format all numbers. Each number after the first is
separated from the preceding number by the separator token
preceding the format token used to format that number, or,
if that is the first format token, then by
.
(dot).
Given the sequence of numbers 5, 13, 7
and the format token A-001(i)
, the output
will be the string E-013(vii)
Format tokens are interpreted as follows:
Any token where the last character has a decimal
digit value of 1 (as specified in the Unicode character
property database), and the Unicode value of preceding
characters is one less than the Unicode value of the
last character generates a decimal representation of
the number where each number is at least as long as the
format token. The digits used in the decimal
representation are the set of digits containing the
digit character used in the format token. Thus,
a format token 1
generates the sequence
0 1 2 ... 10 11 12 ...
, and a format token
01
generates the sequence 00 01 02
... 09 10 11 12 ... 99 100 101
. A format
token of ١
(Arabic-Indic digit
one) generates the sequence ١
then
٢
then ٣
...
A format token A
generates the sequence
A B C ... Z AA AB AC...
.
A format token a
generates the sequence
a b c ... z aa ab ac...
.
A format token i
generates the sequence
i ii iii iv v vi vii viii ix x ...
.
A format token I
generates the sequence
I II III IV V VI VII VIII IX X ...
.
A format token w
generates numbers
written as lower-case words, for example in English,
one two three four ...
A format token W
generates numbers
written as upper-case words, for example in English,
ONE TWO THREE FOUR ...
A format token Ww
generates numbers
written as title-case words, for example in English,
One Two Three Four ...
Any other format token indicates a numbering
sequence in which that token represents the
number 1 (one) (but see the note below). It is
implementation-defined
which numbering sequences, additional to those listed
above, are supported. If an implementation does not
support a numbering sequence represented by the given
token, it must use a format
token of 1
.
Note:
In some traditional numbering sequences additional signs are added to denote that the letters should be interpreted as numbers; these are not included in the format token. An example, see also the example below, is classical Greek where a dexia keraia and sometimes an aristeri keraia is added.
For all format tokens other than the first kind above
(one that consists of decimal digits), there may be implementation-defined
lower and upper bounds on the range of numbers
that can be formatted using this format token; indeed, for
some numbering sequences there may be intrinsic limits.
For example, the formatting token
①
(circled digit one) has a range
of 1 to 20 imposed by the Unicode character
repertoire. For the numbering sequences described
above any upper bound imposed by the implementation
must not be less than 1000 (one
thousand) and any lower bound must not be greater than 1.
Numbers that fall outside this range must be formatted using the format token
1
. The numbering sequence associated with the
format token 1
has a lower bound of 0
(zero).
The above expansions of numbering sequences for format
tokens such as a
and i
are
indicative but not prescriptive. There are various
conventions in use for how alphabetic sequences continue
when the alphabet is exhausted, and differing conventions
for how roman numerals are written (for example,
IV
versus IIII
as the
representation of the number 4). Sometimes alphabetic
sequences are used that omit letters such as i
and o
. This specification does not prescribe
the detail of any sequence other than those sequences
consisting entirely of decimal digits.
Many numbering sequences are language-sensitive. This
applies especially to the sequence selected by the tokens
w
, W
and Ww
. It also
applies to other sequences, for example different languages
using the Cyrillic alphabet use different sequences of
characters, each starting with the letter #x410 (Cyrillic
capital letter A). In such cases, the lang
attribute specifies which language's conventions are to be
used; it has the same range of values as
xml:lang
(see [XML
1.0]). If no lang
value is specified, the
language that is used is implementation-defined.
The set of languages for which numbering is supported is
implementation-defined. If
a language is requested that is not supported, the
processor uses the language that it would use if the
lang
attribute were omitted.
If the optional ordinal
attribute is
present, and if its value is not a zero-length string, this
indicates a request to output ordinal numbers rather than
cardinal numbers. For example, in English, the value
ordinal="yes"
when used with the format token
1
outputs the sequence 1st 2nd 3rd 4th
...
, and when used with the format token
w
outputs the sequence first second
third fourth ...
. In some languages, ordinal numbers
vary depending on the grammatical context, for example they
may have different genders and may decline with the noun
that they qualify. In such cases the value of the
ordinal
attribute may be used to indicate the
variation of the ordinal number required. The way in which
the variation is indicated will depend on the conventions
of the language. For inflected languages that vary the
ending of the word, the preferred approach is to indicate
the required ending, preceded by a hyphen: for example in
German, appropriate values are -e, -er, -es,
-en
. It is implementation-defined
what combinations of values of the format token, the
language, and the ordinal
attribute are
supported. If ordinal numbering is not supported for
the combination of the format token, the language, and the
actual value of the ordinal
attribute, the
request is ignored and cardinal numbers are generated
instead.
The specification format="1" ordinal="-º"
lang="it"
, if supported, should produce the
sequence:
1º 2º 3º 4º ...
The specification format="Ww" ordinal="-o"
lang="it"
, if supported, should produce the
sequence:
Primo Secondo Terzo Quarto Quinto ...
The letter-value
attribute disambiguates
between numbering sequences that use letters. In many
languages there are two commonly used numbering sequences
that use letters. One numbering sequence assigns numeric
values to letters in alphabetic sequence, and the other
assigns numeric values to each letter in some other manner
traditional in that language. In English, these would
correspond to the numbering sequences specified by the
format tokens a
and i
. In some
languages, the first member of each sequence is the same,
and so the format token alone would be ambiguous. A value
of alphabetic
specifies the alphabetic
sequence; a value of traditional
specifies the
other sequence. If the letter-value
attribute
is not specified, then it is implementation-dependent
how any ambiguity is resolved.
Note:
Implementations may use extension attributes
on xsl:number
to provide additional control over the way in which
numbers are formatted.
The grouping-separator
attribute gives the
separator used as a grouping (for example, thousands)
separator in decimal numbering sequences, and the optional
grouping-size
specifies the size (normally 3)
of the grouping. For example,
grouping-separator=","
and
grouping-size="3"
would produce numbers of the
form 1,000,000
while
grouping-separator="."
and
grouping-size="2"
would produce numbers of the
form <IP_ADDRESS>
. If only one of the
grouping-separator
and
grouping-size
attributes is specified, then it
is ignored.
These examples use non-Latin characters which might not display correctly in all browsers, depending on the system configuration.
| Description | Format Token | Sequence |
|---|---|---|
| French cardinal words | format="Ww" lang="fr" |
Un, Deux, Trois, Quatre |
| German ordinal words | format="w" ordinal="-e"
lang="de" |
erste, zweite, dritte, vierte |
| Katakana numbering | format="ア" |
ア, イ, ウ, エ, オ, カ, キ, ク, ケ, コ, サ, シ, ス, セ, ソ, タ, チ, ツ, テ, ト, ナ, ニ, ヌ, ネ, ノ, ハ, ヒ, フ, ヘ, ホ, マ, ミ, ム, メ, モ, ヤ, ユ, ヨ, ラ, リ, ル, レ, ロ, ワ, ヰ, ヱ, ヲ, ン |
| Katakana numbering in iroha order | format="イ" |
イ, ロ, ハ, ニ, ホ, ヘ, ト, チ, リ, ヌ, ル, ヲ, ワ, カ, ヨ, タ, レ, ソ, ツ, ネ, ナ, ラ, ム, ウ, ヰ, ノ, オ, ク, ヤ, マ, ケ, フ, コ, エ, テ, ア, サ, キ, ユ, メ, ミ, シ, ヱ, ヒ, モ, セ, ス |
| Thai numbering | format="๑" |
๑, ๒, ๓, ๔, ๕, ๖, ๗, ๘, ๙, ๑๐, ๑๑, ๑๒, ๑๓, ๑๔, ๑๕, ๑๖, ๑๗, ๑๘, ๑๙, ๒๐ |
| Traditional Hebrew numbering | format="א"
letter-value="traditional" |
א, ב, ג, ד, ה, ו, ז, ח, ט, י, יא, יב, יג, יד, טו, טז, יז, יח, יט, כ |
| Traditional Georgian numbering | format="ა"
letter-value="traditional" |
ა, ბ, გ, დ, ე, ვ, ზ, ჱ, თ, ი, ია, იბ, იგ, იდ, იე, ივ, იზ, იჱ, ით, კ |
| Classical Greek numbering (see note) | format="α"
letter-value="traditional" |
αʹ, βʹ, γʹ, δʹ, εʹ, ϛʹ, ζʹ, ηʹ, θʹ, ιʹ, ιαʹ, ιβʹ, ιγʹ, ιδʹ, ιεʹ, ιϛʹ, ιζʹ, ιηʹ, ιθʹ, κʹ |
| Old Slavic numbering | format="а"
letter-value="traditional" |
А, В, Г, Д, Е, Ѕ, З, И, Ѳ, Ӏ, АӀ, ВӀ, ГӀ, ДӀ, ЕӀ, ЅӀ, ЗӀ, ИӀ, ѲӀ, К |
Note that Glassical Greek is an example where the format token is not the same as the representation of the number 1.
[Definition: A sort key
specification is a sequence of one or more adjacent
xsl:sort
elements
which together define rules for sorting the items in an input
sequence to form a sorted sequence.]
[Definition: Within a sort key specification, each
xsl:sort
element
defines one sort key component.] The first xsl:sort
element specifies
the primary component of the sort key specification, the
second xsl:sort
element specifies the secondary component of the sort key
specification and so on.
A sort key specification may occur immediately within an
xsl:apply-templates
,
xsl:for-each
,
xsl:perform-sort
, or
xsl:for-each-group
element.
Note:
When used within xsl:for-each
, xsl:for-each-group
,
or xsl:perform-sort
,
xsl:sort
elements
must occur before any other children.
xsl:sort
Element<xsl:sort
select? = expression
lang? = { nmtoken }
order? = { "ascending" | "descending" }
collation? = { uri }
stable? = { "yes" | "no" }
case-order? = { "upper-first" | "lower-first"
}
data-type? = { "text" | "number" |
qname-but-not-ncname }>
<!-- Content:
sequence-constructor -->
</xsl:sort>
The xsl:sort
element defines a sort key component. A sort key
component specifies how a sort key value is to be computed
for each item in the sequence being sorted, and also how
two sort key values are to be compared.
The value of a sort key component is
determined either by its select
attribute, or
by the contained sequence constructor. If
neither is present, the default is select="."
,
which has the effect of sorting on the actual value of the
item if it is an atomic value, or on the typed-value of the
item if it is a node. If a select
attribute is
present, its value must be an
XPath expression.
[ERR XTSE1015] It is a static error if
an xsl:sort
element with a select
attribute has non-empty
content.
Those attributes of the xsl:sort
elements whose
values are attribute value
templates are evaluated using the same focus as is used to evaluate the
select
attribute of the containing instruction
(specifically, xsl:apply-templates
,
xsl:for-each
,
xsl:for-each-group
,
or xsl:perform-sort
).
The stable
attribute is permitted only on
the first xsl:sort
element within a sort key specification
[ERR XTSE1017] It is a static error if
an xsl:sort
element other than the first in a sequence of sibling
xsl:sort
elements
has a stable
attribute.
[Definition: A sort key specification is
said to be stable if its first xsl:sort
element has no
stable
attribute, or has a stable
attribute whose effective value is
yes
.]
[Definition: The sequence to be sorted is referred to as the initial sequence.]
[Definition: The sequence after sorting as
defined by the xsl:sort
elements is
referred to as the sorted sequence.]
[Definition: For each item in the initial sequence, a value is computed for each sort key component within the sort key specification. The value computed for an item by using the Nth sort key component is referred to as the Nth sort key value of that item.]
The items in the initial sequence are ordered
into a sorted sequence by comparing
their sort key values. The relative
position of two items A and B in
the sorted sequence is determined as follows. The first
sort key value of A is compared with the first
sort key value of B, according to the rules of
the first sort key component. If,
under these rules, A is less than
B, then A will precede B
in the sorted sequence, unless the order
attribute of this sort key component specifies
descending
, in which case B will
precede A in the sorted sequence. If, however,
the relevant sort key values compare equal, then the
second sort key value of A is compared with
the second sort key value of B, according to
the rules of the second sort key component.
This continues until two sort key values are found that
compare unequal. If all the sort key values compare
equal, and the sort key
specification is stable, then A will
precede B in the sorted sequence if and
only if A preceded B in the
initial sequence. If all
the sort key values compare equal, and the sort key specification
is not stable,
then the relative order of A and B
in the sorted sequence is implementation-dependent.
Note:
If two items have equal sort key values,
and the sort is stable, then their order in the
sorted sequence will be the
same as their order in the initial sequence,
regardless of whether order="descending"
was specified on any or all of the sort
key components.
The Nth sort key value is computed by
evaluating either the select
attribute or
the contained sequence constructor of
the Nth xsl:sort
element, or the
expression .
(dot) if neither is present.
This evaluation is done with the focus set as follows:
The context item is the item in the initial sequence whose sort key value is being computed.
The context position is the position of that item in the initial sequence.
The context size is the size of the initial sequence.
Note:
As in any other XPath expression, the current
function
may be used within the select
expression
of xsl:sort
to
refer to the item that is the context item for the
expression as a whole; that is, the item whose
sort key value is being
computed.
The sort key values are atomized, and are then compared. The way they are compared depends on their data type, as described in the next section.
It is possible to force the system to compare
sort
key values using the rules for a particular data type
by including a cast as part of the sort
key component. For example, <xsl:sort
select="xs:date(@dob)"/>
will force the
attributes to be compared as dates. In the absence of
such a cast, the sort key values are compared using the
rules appropriate to their data type. Any values of type
xs:untypedAtomic
are cast to
xs:string
.
For backwards compatibility with XSLT 1.0, the
data-type
attribute remains available.
If this has the effective value
text
, the atomized sort key values are
converted to strings before being compared. If it has the
effective value number
, the atomized sort
key values are converted to doubles before being
compared. The conversion is done by using the
string
FO or
number
FO function as
appropriate. If the data-type
attribute has any other effective value, then the value
must be a lexical
QName with a non-empty prefix, and the effect
of the attribute is implementation-defined.
[ERR XTTE1020] If any sort key
value, after atomization and any type conversion
required by the
data-type
attribute, is a sequence
containing more than one item, then the effect depends on
whether the xsl:sort
element is
evaluated with backwards
compatible behavior. With backwards compatible
behavior, the effective sort key value is the first item
in the sequence. In other cases, this is a type error.
The set of sort key values (after any conversion) is first divided into two categories: empty values, and ordinary values. The empty sort key values represent those items where the sort key value is an empty sequence. These values are considered for sorting purposes to be equal to each other, but less than any other value. The remaining values are classified as ordinary values.
[ERR XTDE1030] It is a non-recoverable dynamic
error if, for any sort key component, the set
of sort key values evaluated for
all the items in the initial sequence, after any
type conversion requested, contains a pair of ordinary
values for which the result of the XPath lt
operator is an error.
Note:
The above error condition may occur if the values to
be sorted are of a type that does not support ordering
(for example, xs:QName
) or if the sequence
is heterogeneous (for example, if it contains both
strings and numbers). The error can generally be
prevented by invoking a cast or constructor function
within the sort key component.
The error condition is subject to the usual caveat that a processor is not required to evaluate any expression solely in order to determine whether it raises an error. For example, if there are several sort key components, then a processor is not required to evaluate or compare minor sort key values unless the corresponding major sort key values are equal.
In general, comparison of two ordinary values is
performed according to the rules of the XPath
lt
operator. To ensure a total
ordering, the same implementation of the lt
operator must be used for all
the comparisons: the one that is chosen is the one
appropriate to the most specific type to which all the
values can be converted by subtype substitution and/or
type promotion. For example, if the sequence contains
both xs:decimal
and xs:double
values, then the values are compared using
xs:double
comparison, even when comparing
two xs:decimal
values. NaN values,
for sorting purposes, are considered to be equal to each
other, and less than any other numeric value. Special
rules also apply to the xs:string
and
xs:anyURI
types, and types derived by
restriction therefrom,, as described in the next
section.
The rules given in this section apply when comparing
values whose type is xs:string
or a type
derived by restriction from xs:string
,
or whose type is xs:anyURI
or a type derived
by restriction from xs:anyURI
.
[Definition: Facilities in XSLT 2.0 and XPath 2.0 that require strings to be ordered rely on the concept of a named collation. A collation is a set of rules that determine whether two strings are equal, and if not, which of them is to be sorted before the other.] A collation is identified by a URI, but the manner in which this URI is associated with an actual rule or algorithm is implementation-defined.
The one collation URI that must be recognized by every
implementation is
http://www.w3.org/2005/xpath-functions/collation/codepoint
,
which provides the ability to compare strings based on
the Unicode codepoint values of the characters in the
string.
For more information about collations, see Section
7.3 Equality and Comparison of
StringsFO in [Functions and Operators]. Some
specifications, for example [UNICODE TR10], use the term
"collation" to describe rules that can be tailored or
parameterized for various purposes. In this
specification, a collation URI refers to a collation in
which all such parameters have already been fixed.
Therefore, if a collation URI is specified, other
attributes such as case-order
and
lang
are ignored.
Note:
The reason XSLT does not provide detailed mechanisms for defining collating sequences is that many implementations will re-use collating mechanisms available from the underlying implementation platform (for example, from the operating system or from the run-time library of a chosen programming language). These will inevitably differ from one XSLT implementation to another.
If the xsl:sort
element has a
collation
attribute, then the strings are
compared according to the rules for the named collation: that is,
they are compared using the XPath function call
compare($a, $b, $collation)
.