Copyright ©2001 W3C® (MIT, INRIA, Keio), All Rights Reserved. W3C liability, trademark, document use and software licensing rules apply.
This specification defines the syntax and semantics of XSLT, which is a language for transforming XML documents into other XML documents.
XSLT is designed for use as part of XSL, which is a stylesheet language for XML. In addition to XSLT, XSL includes an XML vocabulary for specifying formatting (see [XSL Formatting Objects]). XSL Formatting Objects are frequently used as the output of an XSLT transformation.
XSLT is also designed to be used independently of XSL Formatting Objects. It is often used to produce HTML and XHTML documents, as well as for transformation of application-specific message formats.
This document is the first published Working Draft of XSLT 2.0. It is published in order to provide the XSLT user community with a preview of the revised language specification, and to obtain feedback. It is a draft document and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use W3C Working Drafts as reference material or to cite them as other than "work in progress". While prototype implementations are encouraged, users and vendors are advised that this working draft cannot be regarded as a stable specification.
This document is a revised version of the XSLT 1.0 Recommendation [XSLT 1.0] published on 16 November 1999. The changes made in this document are intended to meet the requirements for XSLT 1.1 and XSLT 2.0 described in [XSLT 1.1 Requirements] and [XSLT 2.0 Requirements] and to incorporate fixes for errors that have been detected in XSLT 1.0. A summary of the changes since XSLT 1.0 is included in [J Changes from XSLT 1.0].
XSLT 2.0 is designed to be used together with XPath 2.0, which has been developed by the W3C XSL Working Group in collaboration with the XML Query Working Group. The current specification of XPath 2.0 can be found in [XPath 2.0].
NOTE: This specification supersedes XSLT 1.1 (see [XSLT 1.1 WD]), which was never developed beyond the Working Draft stage.
Comments on this specification may be sent to xsl-editors@w3.org; archives of the comments are available, and it is possible to subscribe to the list. Public discussion of XSL, including XSL Transformations, takes place on the XSL-List mailing list.
The English version of this specification is the only normative version. However, for translations of this document, see http://www.w3.org/Style/XSL/translations.html.
A list of current W3C Recommendations and other technical documents can be found at http://www.w3.org/TR/.
This specification has been produced as part of the W3C Style activity.
This specification defines the syntax and semantics of the XSLT
language. A
transformation in the XSLT language is expressed
in the form of a stylesheet, whose syntax is
well-formed XML [XML] conforming to the
Namespaces in XML Recommendation [XML Names].
A stylesheet generally includes both elements that are defined by XSLT
and elements that are not defined by XSLT. XSLT-defined elements are
distinguished by belonging to a
specific XML namespace (http://www.w3.org/1999/XSL/Transform
:
see [2.1 XSLT Namespace]),
which is referred to in this specification as the XSLT
namespace. Thus this specification is a definition of
the syntax and semantics of the XSLT namespace.
NOTE: The term stylesheet reflects the fact that one of the important roles of XSLT is to add styling information to an XML source document, by transforming it into a document consisting of XSL formatting objects, or into another presentation-oriented format such as HTML, XHTML, or SVG.
The software responsible for transforming a source document into a result document is referred to as the processor. This is sometimes expanded to XSLT processor to avoid any confusion with other processors, for example an XML processor. A specific product that performs the functions of an XSLT processor is referred to as an implementation.
A transformation expressed in XSLT describes rules for transforming a source tree into a result tree. The transformation is achieved by a set of template rules. A template rule associates a pattern, which matches nodes in the source document, with a content constructor, which can be evaluated to produce part of the result tree. The structure of the result tree can be completely different from the structure of the source tree. In constructing the result tree, nodes from the source tree can be filtered and reordered, and arbitrary structure can be added. This mechanism allows a stylesheet to be applicable to a wide class of documents that have similar source tree structures.
NOTE: More generally, a transformation can process several source trees and produce several result trees.
A
stylesheet may consist of several stylesheet modules,
contained in different XML documents. One of these functions as the
principal stylesheet module. The complete stylesheet is
assembled by finding the stylesheet modules referenced
directly or indirectly from the
principal stylesheet module using xsl:include
and
xsl:import
elements: see [2.8.1 Stylesheet Inclusion] and
[2.8.2 Stylesheet Import].
This document does not specify how a transformation is initiated. The transformation process takes as its main input a source tree referred to as the principal source document. The structure of this tree is described in [Data Model], augmented by additional specifications in this document (see [3 Data Model]).
Issue (document-collection): There are suggestions that it should be possible to supply a collection of source documents as input. In this case, it is unclear whether any one of these would be specially identified as the principal source document, or whether the transformation would be applied to each of them independently.
In addition the transformation requires identification of the principal stylesheet module, and optionally, values for one or more stylesheet parameters (see [6.2 Global Variables and Parameters]).
A stylesheet can process further source documents in addition to the principal source document. These additional documents can be loaded using the document function (see [14.1 Multiple Source Documents]), or they can be supplied as stylesheet parameters (see [6.2 Global Variables and Parameters]), or as the result of an extension function (see [16.1 Extension Functions]
NOTE: Sometimes it is useful to write an XSLT stylesheet that does not require input from a principal source document. However, the semantics of the language require that a principal source document is always present. Implementors may provide a mechanism that supplies a default document, containing just a document node with no children, as the principal source document to be used in the absence of any other source document.
A stylesheet contains a set of template rules. A template rule has two parts: a pattern which is matched against nodes in the source tree and a content constructor which is evaluated to produce a sequence of nodes: these nodes are typically used to form part of the result tree. This allows a stylesheet to be applicable to a wide class of documents that have similar source tree structures.
A content constructor is evaluated for a particular node in the source tree, to create part of the result tree. A content constructor can contain elements (called literal result elements) and text nodes that specify part of the result structure directly. A content constructor can also contain elements from the XSLT namespace that are instructions for creating parts of the result tree.
When a content constructor is evaluated, each instruction is
evaluated to produce a sequence of zero or more nodes; the result of
the content constructor as a whole is a sequence of nodes formed by concatenating the
results of each of the instructions and literal results nodes that it contains,
in the order that they appear in the content constructor. The resulting
nodes are typically attached as children to an element or document node
constructed by the instruction
that contains the content constructor, thus forming a tree.
During this process, adjacent
text nodes will be merged into a single text node.
When a content constructor
is evaluated to create new nodes, the tree to which these nodes are added is referred
to as the current result tree. When
the transformation is initiated, a result tree is created, and becomes the current result tree.
This tree is referred to as the principal result tree. Various XSLT instructions,
(including xsl:variable
and xsl:result-document
) establish a new current result tree
for the nodes created by the content constructor that they contain.
The elements occurring within a content constructor are classified as being either literal result elements or instructions. If the element is in the XSLT namespace, or in a namespace designated as an extension namespace, then it is an instruction. Otherwise, it is a literal result element.
The element syntax summary notation used to describe the syntax of XSLT-defined elements is described in [20 Notation], and a full list of these elements is provided in [C Element Syntax Summary]
Instructions can select and process other nodes in a source tree. The typical way of processing a source node is to create a sequence of result nodes by finding the applicable template rule and evaluating its content constructor. Note that source nodes are processed only if they are selected by such an instruction.
Instructions that select nodes from the source document, or that derive information from these nodes for inclusion in the result document, always access the source tree by means of an Expression in the XPath language, described in [XPath 2.0]. A stylesheet written to use XSLT 2.0 will contain expressions whose syntax and semantics are defined by XPath 2.0 (but see also [2.6 Backwards-Compatible Processing] and [2.7 Forwards-Compatible Processing]).
Execution of a stylesheet against the principal source document proceeds by creating a document node for the principal result tree, finding the template rule that matches the document node of the source tree, and evaluating the content constructor of this template rule to create the children of the new document node. By the time evaluation of this content constructor is complete, these children will typically each act as the parent of further result nodes, so a complete tree is constructed.
It is also possible for the execution of a stylesheet to start at a node in the source document other than the document node, determined by the implementation-specific mechanism for invoking a stylesheet. In this situation, the complete tree remains available for processing by the stylesheet; the only difference is the choice of the node used when applying the first template rule.
In the process of finding the applicable template rule, more than one template rule may have a pattern that matches a given node. However, only one template rule will be applied. The method for deciding which template rule to apply is described in [5.4 Conflict Resolution for Template Rules].
A single content constructor by itself has considerable power. It can create structures of arbitrary complexity; it can pull string values out of arbitrary locations in the source tree; and it can generate structures that are repeated according to the occurrence of nodes in the source tree.
For simple transformations where the structure of the result tree is independent of the structure of the source tree, a stylesheet can often consist of only a single literal result element, containing a content constructor which functions as a template for building the complete result tree. Transformations on XML documents that represent data with a regular and predictable structure (for example, data extracted from a relational database) are often of this kind. XSLT allows a simplified syntax for such stylesheets (see [2.5 Simplified Stylesheet Modules]).
When a content constructor is evaluated, the processor keeps track of which nodes are being processed by means of a set of implicit variables referred to collectively as the focus. More specifically, the focus consists of the following five values:
The context item is the item currently
being processed. An item (see [Data Model]) is either a simple value (such as an
integer, date, or string), or a node. If the context item is a node, then it will always be
a node in the context document. The initial context node is the same as the context document.
It changes
whenever instructions such as xsl:apply-templates
and xsl:for-each
are used to process a sequence of items; each item in such a sequence becomes the context item
while that item is being processed. The context item is returned by the XPath
expression .
(dot).
The context position is the position of
the context item within the sequence of items currently being processed. It changes whenever the
context item changes. When an instruction such as xsl:apply-templates
or
xsl:for-each
is used to process
a sequence of items, the first item in the sequence is processed with a context position of 1, the
second item with a context position of 2, and so on. The context position is returned
by the XPath expression position()
.
The context size is the number of items in
the sequence of items currently being processed. It changes
whenever instructions such as xsl:apply-templates
and xsl:for-each
are used to process a sequence of items; during the processing of each one of those items, the
context size is set to the count of the number of items in the sequence (or equivalently, the position
of the last item in the sequence). The context size is returned
by the XPath expression last()
.
If the context item
is a node (as distinct
from a simple value such as an integer), then it is also referred to as the context node.
The context node is not an independent variable, it changes whenever the context item changes. When
the context item is a simple value, there is no context node: its value is an empty sequence.
The context node is returned by the XPath expression self::node()
, and it is used
as the starting node for all relative path expressions.
The context document
is the source document currently being processed. This is initially set to the document
node of the principal source document.
It changes
when instructions such as xsl:apply-templates
and xsl:for-each
are used to process nodes in a document other than the principal source document. When such
an instruction is processing a node, the context document is the document containing that node. When such
an instruction is processing a simple value (an item that is not a node), the context document is the
same as the context document for the content constructor containing the
xsl:apply-templates
or xsl:for-each
instruction. The
context document is returned by the XPath expression /
(slash), and it
is used as the starting node for all absolute path expressions.
On completion of an instruction which changes the focus
(such as xsl:apply-templates
or
xsl:for-each
), the focus reverts to its previous value.
The description above gives an outline of the way the focus works. Detailed rules for the effect of each instruction are given separately with the description of that instruction. In the absence of specific rules, an instruction uses the same focus as its parent instruction.
Sometimes the focus is based on a single node rather than a sequence. A singleton focus based on a node N has the context item (and therefore the context node) set to N, the context document set to the document containing N, and the context position and context size both set to 1 (one).
As explained in the previous section, an XSLT stylesheet describes a process that constructs a result tree from a source tree.
The stylesheet does not describe how the source tree is constructed. Frequently an implementation will operate in conjunction with an XML parser (or more strictly, in the terminology of [XML], an XML processor), to build the source tree from an input XML document. An implementation may also provide an application programming interface allowing the tree to be constructed directly, or allowing it to be supplied in the form of a DOM Document object (see [DOM2]). This is outside the scope of this specification. Users should be aware, however, that since the input to the transformation is a tree conforming to the data model described in [Data Model], constructs that might exist in the original XML document, or in the DOM, but which are not within the scope of the data model, cannot be processed by the stylesheet and cannot be guaranteed to remain unchanged in the transformation output. Such constructs include CDATA section boundaries, the use of entity references, and the DOCTYPE declaration and internal DTD subset.
A frequent requirement is to
output the result tree as an XML document (or in other formats such as HTML).
This process is referred to as
serialization.
Like parsing, serialization is not part of the transformation
process, and it is not required that an XSLT processor should be able to perform
serialization. However, for pragmatic reasons, this specification describes a declaration
(the xsl:output
element, see [18 Serialization]) which allows a
stylesheet to specify the desired properties of a serialized output file. Implementations
that do not serialize the result tree are allowed to ignore this declaration.
Because it is a common requirement to perform a transformation on a document while retaining lexical characteristics such as CDATA section boundaries, entity references, and the like, an appendix to this specification (see [F Representation of Lexical XML Constructs]) describes a way in which these constructs can be represented within the data model by means of elements in a special namespace. If such a representation is chosen, the tree is transformed in the same way as any other tree. The process of constructing such a tree is something that happens before XSLT transformation starts, and the process of interpreting such a tree and reconstituting the lexical representation is part of the serialization process. Neither of these processes is properly within the scope of XSLT transformation, and therefore, this specification places no requirement on an XSLT processor to support this representation of lexical properties.
XSLT provides two "hooks" for extending the language, one hook for extending the set of instruction elements used in content constructors and one hook for extending the set of functions used in XPath expressions. These hooks are both based on XML namespaces: see [16 Extensibility and Fallback] for further details. Extension instructions and extension functions defined according to these rules may be provided by the implementor of the XSLT processor, and the implementor may also provide facilities to allow users to create further extension instructions and extension functions. This specification defines how extension instructions and extension functions are invoked, but does not define how new extension instructions and extension functions are to be implemented.
An error that is detected by examining a stylesheet before execution starts (that is, before the source document and values of stylesheet parameters are available) is referred to as a static error. Errors classified in this specification as static errors must be signaled by all implementations: that is, the processor must indicate that the error is present, and it must not use the stylesheet to produce a result tree. A static error must be signaled even if it occurs in a part of the stylesheet that is never evaluated.
There is an exception to this rule when the stylesheet specifies forwards-compatible behavior (see [2.7 Forwards-Compatible Processing]).
Generally, errors in the structure of the stylesheet, or in the syntax of XPath expressions contained in the stylesheet, are classified as static errors. Where this specification states that an element in the stylesheet must or must not appear in a certain position, or that it must or must not have a particular attribute, or that an attribute must or must not have a value satisfying specified conditions, then any contravention of this rule is a static error unless otherwise specified.
An error that is not detected until a source document is being transformed is referred to as a dynamic error. In many cases, this specification allows an implementation to decide whether dynamic errors should be signaled (by reporting the error condition and terminating execution) or whether recovery action should be taken. If the implementation does choose to take recovery action, it must take the recovery action defined in this specification.
When the implementation makes the choice between signaling a dynamic error or recovering, it is not restricted in how it makes the choice; for example, it may provide options that can be set by the user. When an implementation chooses to recover from a dynamic error, it is also allowed to take other action, such as logging a warning message.
Because different implementations may optimize execution of the stylesheet in different ways, the detection of dynamic errors will not necessarily be consistent between one implementation and another. In cases where an implementation is able to produce the result tree without evaluating a particular construct, the implementation is never required to evaluate that construct solely in order to determine whether doing so causes a dynamic error. For example, if a variable is declared but never referenced, an implementation can choose whether or not to evaluate the variable declaration, which means that if evaluating the variable declaration causes a dynamic error, some implementations will signal this error and others will not.
There are some cases where this specification requires that a construct must
not be evaluated: for example, the content of an xsl:if
instruction
must not be evaluated if the test condition is false. This means that an implementation
must not report any dynamic errors that would arise if the construct were evaluated.
An implementation may signal a dynamic error before any source document is available, but only if it can determine that the error would be signaled for every possible source document and every possible set of parameter values. For example, some circularity errors fall into this category: see [6.3 Circular Definitions].
Certain errors are classified as type errors.
A type error occurs when the value supplied as input to an operation is of the wrong type
for that operation, for example when an integer is supplied to an operation that expects
a node. If a type error occurs in an instruction that is actually evaluated, then it must
be reported as a dynamic error. An implementation
may also, optionally, report a type error as a static error,
even if it occurs in part of the stylesheet that is never evaluated, provided it can establish
that execution of a particular construct would never succeed. For example, the following
construct contains a type error, because 42
is not allowed as an operand of the
xsl:apply-templates
instruction. An implementation may optionally report this as a
static error, even though the offending instruction will never be evaluated, and the type error would
therefore never be reported as a dynamic error.
<xsl:if test="false()"> <xsl:apply-templates select="42"/> </xsl:if>
If more than one error arises, an implementation is not required to signal any errors other than the first one that it detects. This applies both to static errors and to dynamic errors. An implementation is allowed to signal more than one error, but if any errors have been signaled, it must not produce a result tree.
Everything said above about error handling applies equally to errors in evaluating XSLT instructions, and errors in evaluating XPath expressions. Static errors and dynamic errors may occur in both cases.
If a transformation has successfully produced a result tree, it is still possible that errors may occur in serializing the result tree. For example, it may be impossible to serialize the result tree using the encoding selected by the user. Such an error is referred to as a serialization error. As with other aspects of serialization, this specification imposes no mandatory requirements on the way in which an implementation handles serialization errors: see [18 Serialization].
A stylesheet consists of one or more stylesheet modules, each one forming all or part of a well-formed XML document. There are three kinds of stylesheet module:
xsl:stylesheet
or xsl:transform
element
as its document element (see [2.4 Stylesheet Element]).xsl:stylesheet
or xsl:transform
element
embedded within another XML document, typically the principal
source document (see [2.9 Embedded Stylesheet Modules]).Issue (embedded-simplified-stylesheets): This classification would imply that embedded stylesheet modules cannot be simplified stylesheets. The Working Group does not intend to disallow use of embedded simplified stylesheet modules, and will re-work the text before final publication to permit this combination.
The XSLT namespace
has the URI http://www.w3.org/1999/XSL/Transform
. It is used to identify
elements, attributes, and other names that have a special meaning defined in
this specification.
NOTE: The 1999
in the URI indicates the year in which
the URI was allocated by the W3C. It does not indicate the version of
XSLT being used, which is specified by attributes (see [2.4 Stylesheet Element] and [2.5 Simplified Stylesheet Modules]).
XSLT processors must use the XML namespaces mechanism [XML Names] to recognize elements and attributes from this namespace. Elements from the XSLT namespace are recognized only in the stylesheet and not in the source document. The complete list of XSLT-defined elements is specified in [C Element Syntax Summary]. Implementations must not extend the XSLT namespace with additional elements or attributes. Instead, any extension must be in a separate namespace. Any namespace that is used for additional instruction elements must be identified by means of the extension instruction mechanism specified in [16.2 Extension Instructions].
This specification uses a prefix of xsl:
for referring
to elements in the XSLT namespace. However, XSLT stylesheets are free
to use any prefix, provided that there is a namespace declaration that
binds the prefix to the URI of the XSLT namespace.
An element from the XSLT namespace may have any attribute not from the XSLT namespace, provided that the expanded-name (see [XPath 2.0]) of the attribute has a non-null namespace URI. The presence of such attributes must not change the behavior of XSLT elements and functions defined in this document or in the XPath specification, though they may be used to modify the behavior of extension functions and extension instructions. Thus, an implementation is always free to ignore such attributes, and must ignore such attributes without giving an error if it does not recognize the namespace URI. Such attributes can provide, for example, unique identifiers, optimization hints, or documentation.
For example, the following code might be used to provide a hint to a particular implementation that a call to an extension function has side effects:
<xsl:value-of select="abc:set-property('someprop', 3)" abc:side-effects="yes" xmlns:abc="http://some.vendor.com/xslt/extensions"/>
[ERR001] It is a static error for an element from the XSLT namespace to have an attribute with an expanded-name that has a null namespace URI (i.e. an attribute with an unprefixed name) other than attributes defined for the element in this document.
NOTE: The conventions used for the names of XSLT elements, attributes and functions are that names are all lower-case, use hyphens to separate words, and use abbreviations only if they already appear in the syntax of a related language such as XML or HTML.
The MIME media types text/xml
and
application/xml
[RFC2376] should be used
for XSLT stylesheets. It is possible that a media type will be
registered specifically for XSLT stylesheets; if and when it is, that
media type may also be used.
There are a number of
standard attributes that may appear on any XSLT element: specifically
version
, exclude-result-prefixes
,
extension-element-prefixes
, and
default-xpath-namespace
.
These attributes may also appear on a
literal result element,
but in this case, to distinguish them from user-defined attributes, the
names of the attributes are in the XSLT namespace.
They are thus typically
written as xsl:version
, xsl:exclude-result-prefixes
,
xsl:extension-element-prefixes
, or
xsl:default-xpath-namespace
.
It is recommended that these attributes should also be permitted on extension instructions, but this is at the discretion of the implementor of each extension instruction. They may also be permitted on user-defined data elements, though they will only have any useful effect in the case of data elements that are designed to behave like XSLT declarations or instructions.
In the following descriptions, these attributes are referred to
generically as [xsl:]version
, and so on.
These attributes all affect the element they appear on, and any descendant elements of the element they appear on, together with attributes of those descendant elements. The two forms with and without the XSLT namespace have the same effect; the XSLT namespace is used for the attribute if and only if its parent element is not in the XSLT namespace.
In the case of [xsl:]version
and
[xsl:]default-xpath-namespace
the value
can be overridden by a different value for the
same attribute appearing on a descendant element. The effective value of the
attribute for a particular stylesheet element is determined by the innermost
containing element on which the attribute appears.
In the case of [xsl:]exclude-result-prefixes
and
[xsl:]extension-element-prefixes
the values are cumulative. For these
attributes, the value is a whitespace-separated list of namespace prefixes, and the
effective value for an element is the combined set of prefixes that appear in this
attribute for that element and any of its ancestor elements. Again, the
two forms with and without the XSLT namespace are equivalent.
Because these attributes may appear on any XSLT element, they are not listed
in the syntax summary of each individual element. Instead they are listed and
described in the description of the xsl:stylesheet
and
xsl:transform
elements only.
This reflects the fact that these attributes are often used on the
xsl:stylesheet
element, in which case they apply to the entire
stylesheet module.
Note that the effect of these attributes does not extend to
stylesheet modules referenced
by xsl:include
or xsl:import
declarations.
For the detailed effect of each attribute, see the following sections:
[xsl:]version
: see [2.6 Backwards-Compatible Processing] and
[2.7 Forwards-Compatible Processing][xsl:]default-xpath-namespace
: see
[4.4 Unprefixed Names in Expressions and Patterns].[xsl:]exclude-result-prefixes
: see
[8.1.2 Namespace Nodes for Literal Result Elements].[xsl:]extension-element-prefixes
: see
[16.2 Extension Instructions].<xsl:stylesheet
id = id
extension-element-prefixes = tokens
exclude-result-prefixes = tokens
version = number
default-xpath-namespace = uri>
<!-- Content: (xsl:import*, top-level-elements) -->
</xsl:stylesheet>
<xsl:transform
id = id
extension-element-prefixes = tokens
exclude-result-prefixes = tokens
version = number
default-xpath-namespace = uri>
<!-- Content: (xsl:import*, top-level-elements) -->
</xsl:transform>
A stylesheet module is represented by an xsl:stylesheet
element in an XML document. xsl:transform
is allowed as
a synonym for xsl:stylesheet
; everything
this specification says about the xsl:stylesheet
element applies
equally to xsl:transform
.
[ERR002] An xsl:stylesheet
element must have a
version
attribute, indicating the version of XSLT that
the stylesheet requires.
[ERR003] The value of the version attribute
must be a number. For this version of XSLT, the value should normally
be 2.0
. When the value is less than 2.0, backwards-compatible
processing behavior is enabled (see [2.6 Backwards-Compatible Processing]). When the value
is greater than 2.0,
forwards-compatible behavior
is enabled (see [2.7 Forwards-Compatible Processing]).
[ERR004] An xsl:stylesheet
element must have
no text node children, other than text nodes consisting entirely of whitespace.
An element occurring as
a child of an xsl:stylesheet
element is called a
top-level element.
Top-level elements fall into two categories: declarations, and user-defined data elements. Top-level elements whose names are in the XSLT namespace are declarations. Top-level elements in any other namespace are user-defined data elements (see [2.4.1 User-defined Data Elements])
The xsl:stylesheet
element may contain the following types
of declaration:
xsl:import
xsl:include
xsl:attribute-set
xsl:decimal-format
xsl:destination
xsl:function
xsl:key
xsl:namespace-alias
xsl:output
xsl:param
xsl:preserve-space
xsl:sort-key
xsl:strip-space
xsl:template
xsl:variable
The order in which the children of the xsl:stylesheet
element occur is not significant except for xsl:import
elements and for error recovery. Users are free to order the elements
as they prefer, and stylesheet creation tools need not provide control
over the order in which the elements occur.
In addition to
declarations,
the xsl:stylesheet
element may contain
any element not from the XSLT namespace,
provided that the
expanded-name of the element has a non-null namespace URI. Such
elements are referred to as user-defined data elements.
[ERR005] It is a static error
if the xsl:stylesheet
element has
a child element having a null namespace URI.
The presence of
a data element must not change the behavior of XSLT elements
and functions defined in this document; for example, it is not
permitted for a data element to specify that
xsl:apply-templates
should use different rules to resolve
conflicts. Thus, an implementation is always free to ignore data elements,
and must ignore a data element without giving
an error if it does not recognize the namespace URI. Data elements can
provide, for example,
information used by extension instructions or extension functions (see [16 Extensibility and Fallback]),
information about what to do with the result tree,
information about how to obtain the source tree,
optimization hints for the processor,
metadata about the stylesheet,
structured documentation for the stylesheet.
[ERR006] A user-defined data element
must not precede an xsl:import
element within a
stylesheet module.
A simplified syntax is allowed for a stylesheet module
that consists of only a single template rule for the document node.
The stylesheet module may consist of
just a literal result element
(see [8.1 Literal Result Elements]). Such a stylesheet is equivalent to a
standard stylesheet module whose xsl:stylesheet
element contains a
template rule containing the literal result element;
the template rule has a match pattern of /
.
For example
<html xsl:version="2.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml"> <head> <title>Expense Report Summary</title> </head> <body> <p>Total Amount: <xsl:value-of select="expense-report/total"/></p> </body> </html>
has the same meaning as
<xsl:stylesheet version="2.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml"> <xsl:template match="/"> <html> <head> <title>Expense Report Summary</title> </head> <body> <p>Total Amount: <xsl:value-of select="expense-report/total"/></p> </body> </html> </xsl:template> </xsl:stylesheet>
More formally, a simplified stylesheet module is equivalent to the standard stylesheet module that would be generated by applying the following transformation to the simplified stylesheet module:
<xsl:stylesheet version="2.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> <xsl:template match="/"> <xsl:element name="xsl:stylesheet"> <xsl:attribute name="version"> <xsl:value-of select="*/@xsl:version"/> </xsl:attribute> <xsl:element name="xsl:template"> <xsl:attribute name="match">/</xsl:attribute> <xsl:copy-of select="*"/> </xsl:element> </xsl:element> </xsl:template> </xsl:stylesheet>
[ERR007] A literal result element that
is the document element of a
simplified stylesheet module must have
an xsl:version
attribute. This
indicates the version of XSLT that the stylesheet requires.
For this version of XSLT, the value should normally be 2.0
; the
value must be a NumericLiteral
as defined in [XPath 2.0].
Other
literal result elements may also
have an xsl:version
attribute. When the xsl:version
attribute is numerically less than
2.0
, backwards-compatible processing behavior is enabled (see [2.6 Backwards-Compatible Processing]).
When the xsl:version
attribute is numerically greater than 2.0
,
forwards-compatible behavior
is enabled (see [2.7 Forwards-Compatible Processing]).
The allowed content of a literal result element when used as a simplified stylesheet is the same as when it occurs within a content constructor. Thus, a literal result element used as the document element of a simplified stylesheet cannot contain declarations.
An element
enables backwards-compatible behavior for itself, its
attributes, its descendants and their attributes if either it has an
[xsl:]version
attribute (see [2.3 Standard Attributes])
whose value is less than 2.0
.
An element
that has an [xsl:]version
attribute whose value is greater than or equal to
2.0
disables backwards-compatible behavior for itself, its attributes, its
descendants and their attributes. The compatibility
behavior established by an element overrides
any compatibility behavior established by an ancestor element.
If an attribute containing an XPath expression is processed with backwards-compatible behavior, then:
It is constrained to use syntax permitted by XPath 1.0
It is guaranteed to return the same result as would be returned by XPath 1.0, after conversion of any variables that it references to the equivalent XPath 1.0 data type. This conversion is done as follows. Any numeric value is converted to the nearest XPath 1.0 number. Boolean values remain as booleans; any other simple value is converted to a string. [ERR008] If the value is an empty sequence or a sequence that consists entirely of nodes, then it is converted to a node-set; it is a dynamic error if the value is any other sequence of two or more items. The processor must signal the error. The result of the expression is converted to an XPath 2.0 value by representing any node-set as a sequence of nodes in document order.
An XSLT 2.0 implementation is not obliged to support backwards-compatible behavior. [ERR009] If an implementation does not support backwards-compatible behavior, then it is a dynamic error if any element is evaluated that enables backwards-compatible behavior. The processor must signal the error.
An element enables
forwards-compatible behavior for itself, its
attributes, its descendants and their attributes if it has an
[xsl:]version
attribute (see [2.3 Standard Attributes])
whose value is greater than 2.0
.
An element that has an [xsl:]version
attribute
whose value is less than or equal to 2.0
disables forwards-compatible behavior for itself, its attributes, its
descendants and their attributes.
The compatibility behavior established by an element overrides
any compatibility behavior established by an ancestor element.
Within a section of a stylesheet where forwards-compatible behavior is enabled, errors that would normally be static errors are treated instead as dynamic errors. This means that no error is reported unless the construct containing the error is actually evaluated.
This means, for example, that when an element is processed with forwards-compatible behavior:
if it is a top-level element and XSLT 2.0 does not allow such elements as top-level elements, then the element must be ignored along with its content;
if it is an element in a content constructor and XSLT 2.0 does not allow such elements to occur in content constructors, then if the element is not evaluated, no error must be signaled, and if the element is evaluated, the processor must perform fallback for the element as specified in [16.2.3 Fallback];
if the element has an attribute that XSLT 2.0 does not allow the element to have or if the element has an optional attribute with a value that XSLT 2.0 does not allow the attribute to have, then the attribute must be ignored.
if an attribute of the element contains an XPath expression that does not match the allowed syntax of an XPath 2.0 expression, or one that calls a function with an unprefixed name that is not defined in XPath 2.0 or XSLT 2.0, or that calls such a function with the wrong number or type of arguments, the error must not be signaled unless the expression is actually evaluated.
Thus, any XSLT 2.0 processor must be able to process the following stylesheet without error, although the stylesheet includes elements from the XSLT namespace that are not defined in this specification:
<xsl:stylesheet version="17.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> <xsl:template match="/"> <xsl:choose> <xsl:when test="system-property('xsl:version') >= 17.0"> <xsl:exciting-new-17.0-feature/> </xsl:when> <xsl:otherwise> <html> <head> <title>XSLT 17.0 required</title> </head> <body> <p>Sorry, this stylesheet requires XSLT 17.0.</p> </body> </html> </xsl:otherwise> </xsl:choose> </xsl:template> </xsl:stylesheet>
NOTE: If a stylesheet depends crucially on a declaration introduced by a version of XSLT after 2.0, then the stylesheet can use anxsl:message
element withterminate="yes"
(see [15 Messages]) to ensure that implementations that conform to an earlier version of XSLT will not silently ignore the declaration. For example,<xsl:stylesheet version="18.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> <xsl:important-new-17.0-declaration/> <xsl:template match="/"> <xsl:choose> <xsl:when test="system-property('xsl:version') < 17.0"> <xsl:message terminate="yes"> <xsl:text>Sorry, this stylesheet requires XSLT 17.0.</xsl:text> </xsl:message> </xsl:when> <xsl:otherwise> ... </xsl:otherwise> </xsl:choose> </xsl:template> ... </xsl:stylesheet>
XSLT provides two mechanisms to construct a stylesheet from multiple stylesheet modules:
<!-- Category: declaration -->
<xsl:include
href = uri-reference />
A stylesheet module may include another stylesheet module using an
xsl:include
declaration. The xsl:include
declaration
has an href
attribute whose value is a URI reference
identifying the stylesheet module to be included. A relative URI is resolved
relative to the base URI of the xsl:include
declaration (see
[Data Model]).
[ERR010] The xsl:include
element is allowed only as a
top-level element.
A stylesheet level
is a collection of stylesheet modules connected
using xsl:include
declarations:
specifically, two stylesheet modules A and B are part of the same
stylesheet level if one of them includes the other by means of an xsl:include
declaration, or if there is a third stylesheet module C that is in the same
stylesheet level as both A and B.
The
declarations within a
stylesheet level have a total ordering known
as declaration order. The order of declarations within a stylesheet
level is the same as the document order that would result if each stylesheet module were
inserted textually in place of the xsl:include
element that references it.
In other respects, however, the effect of xsl:include
is not equivalent to
the effect that would be obtained by textual inclusion.
The included stylesheet module may be any of the three kinds of stylesheet module: a standard stylesheet module, a simplified stylesheet module, or an embedded stylesheet module.
Issue (include-fragment): Is it permitted for the URI reference used in
xsl:include
andxsl:import
to include a fragment identifier, to reference an embedded stylesheet module? And if so, what is the form of the fragment identifier? This isn't clear at 1.0.
[ERR011] It is an static error if a stylesheet module directly or indirectly includes itself.
NOTE: It is not intrinsically an error for a stylesheet to include the same module more than once. However, doing so can cause errors because of duplicate definitions. Such multiple inclusions are less obvious when they are indirect. For example, if stylesheet B includes stylesheet A, stylesheet C includes stylesheet A, and stylesheet D includes both stylesheet B and stylesheet C, then A will be included indirectly by D twice. If all of B, C and D are used as independent stylesheets, then the error can be avoided by separating everything in B other than the inclusion of A into a separate stylesheet B' and changing B to contain just inclusions of B' and A, similarly for C, and then changing D to include A, B', C'.
<!-- Category: declaration -->
<xsl:import
href = uri-reference />
A stylesheet module may import another
stylesheet module using an
xsl:import
declaration.
Importing a stylesheet is the same
as including it (see [2.8.1 Stylesheet Inclusion]) except that
template rules
and other declarations in the
importing stylesheet take precedence over
template rules and declarations in the imported stylesheet; this is
described in more detail below. The xsl:import
declaration
has an href
attribute whose value is a URI reference
identifying the stylesheet to be imported. A relative URI is resolved
relative to the base URI of the xsl:import
element (see
[Data Model]).
[ERR012] The xsl:import
declaration
is allowed only as a top-level element.
[ERR013] The
xsl:import
element children must precede all other
element children of an xsl:stylesheet
element, including
any xsl:include
element children and any
user-defined data elements.
For example,
<xsl:stylesheet version="2.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> <xsl:import href="article.xsl"/> <xsl:import href="bigfont.xsl"/> <xsl:attribute-set name="note-style"> <xsl:attribute name="font-style">italic</xsl:attribute> </xsl:attribute-set> </xsl:stylesheet>
The
stylesheet levels
making up a stylesheet are
treated as forming an import tree. In the import tree,
each stylesheet level has one child for each
xsl:import
declaration that it contains. The ordering
of the children is the declaration order
of the xsl:import
declarations within their stylesheet level.
A declaration
D in the stylesheet
is defined to have lower import precedence than another
declaration E if the stylesheet level containing D would be
visited before the stylesheet level containing E in a
post-order traversal of the import tree (that is, a traversal of the
import tree in which a stylesheet level is visited
after its children). Two declarations within the same stylesheet level have
the same import precedence.
For example, suppose
stylesheet module A imports stylesheet modules B and C in that order;
stylesheet module B imports stylesheet module D;
stylesheet module C imports stylesheet module E.
Then the order of import precedence (lowest first) is D, B, E, C, A.
In general, a declaration with higher import precedence takes precedence over a declaration with lower import precedence. This is defined in detail for each kind of declaration.
[ERR014] It is a static error if a stylesheet module directly or indirectly imports itself.
NOTE: The case where a stylesheet with a particular URI is imported in multiple places is not treated specially. The resulting stylesheet will contain multiple declarations that are identical in content but that differ in their import precedence.
A standard stylesheet module is a complete XML document with the
xsl:stylesheet
element as its document element. However,
a stylesheet module may also be embedded in another resource. Two forms
of embedding are possible:
xsl:stylesheet
element may occur in an XML
document other than as the document element.To facilitate the second form of embedding, the
xsl:stylesheet
element is allowed to have an ID attribute
that specifies a unique identifier.
NOTE: In order for such an attribute to be used with the XPath id function, it must actually be declared in the DTD as being of type ID. The same requirement typically applies if the identifier is to be used as a fragment identifier in a URI reference.
The following example shows how the xml-stylesheet
processing instruction [XML Stylesheet] can be used to allow a
source document to contain its own stylesheet. The URI reference uses a
relative URI with a fragment identifier to locate the
xsl:stylesheet
element:
<?xml-stylesheet type="text/xml" href="#style1"?> <!DOCTYPE doc SYSTEM "doc.dtd"> <doc> <head> <xsl:stylesheet id="style1" version="2.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:fo="http://www.w3.org/1999/XSL/Format"> <xsl:import href="doc.xsl"/> <xsl:template match="id('foo')"> <fo:block font-weight="bold"><xsl:apply-templates/></fo:block> </xsl:template> <xsl:template match="xsl:stylesheet"> <!-- ignore --> </xsl:template> </xsl:stylesheet> </head> <body> <para id="foo"> ... </para> </body> </doc>
NOTE: A stylesheet module that is embedded in the document to which it is
to be applied or that may be included or imported into a stylesheet that is so embedded typically needs
to contain a template rule that specifies that
xsl:stylesheet
elements are to be ignored.
NOTE: The above example uses the pseudo-attributetype="text/xml"
in thexml-stylesheet
processing instruction to denote an XSLT stylesheet. This usage was defined provisionally in XSLT 1.0, and is subject to change. In the absence of a registered media type for XSLT stylesheets, some vendors' products have adopted different conventions, notablytype="text/xsl"
.
NOTE: Support for the xml-stylesheet
processing instruction is not
a requirement for conformance with this Recommendation.
The data model used by XSLT is as defined in [Data Model], with the additions described in this section. XSLT operates on source, result and stylesheet documents using the same data model.
Features of a source XML document that are not represented in the tree defined by the data model will have no effect on the operation of an XSLT stylesheet. Examples of such features are entity references, CDATA sections, character references, whitespace within element tags, and the choice of single or double quotes around attribute values.
The data model defined in [Data Model] allows a node to be part of a tree whose root is a node other than a document node.
Although such nodes may exist transiently during the course of XSLT processing, every node that is processed by an XSLT stylesheet (that is, a node that may be returned in the result of an expression) will belong to a tree whose root is a document node.
Ed. Note: This section can be removed when it is confirmed that the data model permits "well-balanced" trees. At the time of writing, this is still an open issue in the data model (Issue 0041).
The normal restrictions on the children of the document node are relaxed for the result tree and for temporary trees constructed during the evaluation of the stylesheet. The document node of such a tree may have any sequence of nodes as children that would be possible for an element node. In particular, it may have text node children, and any number of element node children. When written out using the XML output method (see [18 Serialization]), it is possible that a result tree will not be a well-formed XML document; however, it will always be a well-formed external general parsed entity.
For example, a stylesheet might produce the following output. This is a well-formed external general parsed entity, but it is not a well-formed XML document:
<?xml version="1.0" encoding="iso-8859-1"?>A <i>fine</i> mess!
When a source tree is created by parsing a well-formed XML document, the document node of the source tree will automatically satisfy the normal restrictions of having no text node children and exactly one element child. When a source tree is created in some other way, for example by using the DOM, the usual restrictions are relaxed for the source tree as for the result tree.
Ed. Note: Unparsed entities don't currently appear in the data model, though we have asked for them to be added. This section can be deleted when the Data Model is updated to support unparsed entities.
The document node has a mapping that gives the URI for each unparsed entity declared in the document's DTD. The URI is generated from the system identifier and public identifier specified in the entity declaration. The processor may use the public identifier to generate a URI for the entity instead of the URI specified in the system identifier. If the processor does not use the public identifier to generate the URI, it must use the system identifier; if the system identifier is a relative URI, it must be resolved into an absolute URI using the URI of the resource containing the entity declaration as the base URI [RFC2396].
Issue (whitespace-and-schema): If an element has element content, as defined in the schema or DTD, the default should be to strip whitespace nodes rather than preserving them.
The source document supplied as input to the transformation process may contain whitespace nodes (that is, text nodes consisting solely of whitespace characters) that are of no interest, and that do not need to be retained by the transformation. Conceptually, such whitespace nodes may be removed from the tree before the transformation commences. This process is referred to as whitespace stripping. The source tree itself must not be modified: the processor may implement whitespace stripping either by creating a copy of the tree from which the whitespace nodes have been removed, or by working on a virtual tree in which the whitespace nodes are treated as if they were absent.
The stripping process takes as input a set of element names whose child whitespace nodes must be preserved. The stripping process is applied to both stylesheets and source documents, but the set of whitespace-preserving element names is determined differently for stylesheets and for source documents.
NOTE: Where multiple transformations are to be applied to the same source document, a useful optimization is to do the whitespace stripping only once. Implementations may therefore allow whitespace stripping to be controlled as a separate operation from the rest of the transformation process.
A text node is preserved if any of the following apply:
The element name of the parent of the text node is in the set of whitespace-preserving element names.
The text node contains at least one non-whitespace character. As in XML, a whitespace character is #x20, #x9, #xD or #xA.
An ancestor element of the text node has an
xml:space
attribute with a value of
preserve
, and no closer ancestor element has
xml:space
with a value of
default
.
Otherwise, the text node is stripped.
The xml:space
attributes are not removed from the
tree.
NOTE: This implies that if an xml:space
attribute is
specified on a literal result element,
it will be included in the result.
For stylesheets, the set of whitespace-preserving element names
consists of just xsl:text
.
Processing instructions and comments in a stylesheet module are ignored: the stylesheet module is treated as if the processing instructions and comments were not there. This also means that sibling text nodes that are separated by a processing instruction or comment in a stylesheet module are concatenated into a single text node; and a text node is classified as a whitespace text node for the purpose of whitespace stripping only after this concatenation has taken place.
The content model for some XSLT elements (for example
xsl:stylesheet
and xsl:choose
) does not permit text nodes
as children of these elements. If the xml:space="preserve"
attribute
is used to suppress the stripping of whitespace text nodes within such elements,
then any whitespace used for the layout of such elements will be retained in the
stylesheet tree in the form of whitespace text nodes. Such text nodes should not be reported
as an error. [ERR015] Within an XSLT element that is required to be empty,
any content other than comments or processing instructions, including any whitespace-only
text node preserved using the xml:space="preserve"
attribute, is a
static error.
<!-- Category: declaration -->
<xsl:strip-space
elements = tokens />
<!-- Category: declaration -->
<xsl:preserve-space
elements = tokens />
For source documents, the set of
whitespace-preserving element names is specified by
xsl:strip-space
and xsl:preserve-space
declarations. Whether an
element name is included in the set of whitespace-preserving names is
determined by the best match amongst xsl:strip-space
or
xsl:preserve-space
declarations: it is included if and only
if there is no match or the best match is an
xsl:preserve-space
element. The
xsl:strip-space
and xsl:preserve-space
elements each have an elements
attribute whose value is a
whitespace-separated list of NameTests; an element name matches an
xsl:strip-space
or xsl:preserve-space
element if it matches one of the NameTests.
An element matches a NameTest if and only if the NameTest would be true for the
element as an XPath node
test. When more than one xsl:strip-space
and
xsl:preserve-space
element matches, the best matching
element is determined by the best matching NameTest. This is determined in the
same way as with template rules:
First, any match with lower import precedence than another match is ignored.
Next, any match that has a lower default priority than the default priority of another match is ignored.
[ERR016] It is an dynamic error if this leaves more than one match. The processor must either signal the error, of must recover by choosing, from amongst the matches that are left, the one that occurs last in declaration order.
NOTE: A source document is supplied as input to the XSLT processor in the form of a tree. Nothing in this specification states that this tree must be built by parsing an XML document; nor does it state that the application that constructs the tree is required to treat whitespace in any particular way. The provisions in this section relate only to whitespace text nodes that are present in the tree supplied as input to the processor. In particular, the processor cannot preserve whitespace text nodes unless they were actually present in the supplied tree.
Ed. Note: The process of namespace fixup would ideally be described along with the node construction functions defined in the XPath 2.0 data model.
Issue (shared-namespace-node-fixup): This section needs to be revised if namespace nodes are to be held at document level.
In a tree constructed by parsing an XML document, the following constraints relating to namespace nodes will be satisfied:
If an element node has an expanded-name with a non-null namespace URI, then that element node will have at least one namespace node whose string-value is the same as that namespace URI.
If an attribute node has an expanded-name with a non-null namespace URI, then the parent element of that attribute will have at least one namespace node whose string-value is the same as that namespace URI and whose expanded-name has a non-empty local part.
If an element node has a namespace node with an expanded-name with a non-empty local part, then every child element of that element will also have a namespace node with that expanded-name (possibly with a different string-value).
Every element has a namespace node whose expanded-name has
local-part xml
and whose string-value is
http://www.w3.org/XML/1998/namespace
.
However, when a tree is being constructed as the result of an XSLT
transformation, these constraints might not be satisfied
unless special action is taken.
In particular,
since xsl:element
and xsl:attribute
instructions do not create namespace nodes, they will often cause
these constraints not to be satisfied.
The process of
namespace fixup modifies a tree by adding
namespace nodes so that it satisfies all constraints affecting namespace nodes.
What namespace nodes are added and where they are added by
namespace fixup is implementation-dependent, provided that the
resulting tree satisfies the constraints and provided that all
namespaces nodes in the resulting tree are allowable,
where a namespace node is allowable for an element E
if any of the following conditions applies:
The namespace node was in the tree before namespace fixup.
The local-part of the expanded-name of the namespace node is
xml
and its string-value is
http://www.w3.org/XML/1998/namespace
.
The namespace node has a string-value equal to the namespace URI of the expanded-name of element E.
The namespace node has a string-value equal to the namespace URI of the expanded-name of an attribute of element E; this applies only if the local part of the expanded-name of the namespace node is non-empty.
Element E has a parent element with a namespace node that is allowable and that has the same expanded-name and same string-value as the other namespace node; this applies only if the local part of the expanded-name of the namespace node is non-empty.
Namespace fixup must not result in an element having multiple namespace nodes with the same expanded-name.
Namespace fixup is performed in two situations:
It is applied to a result tree, before the result tree is made available to the calling application (whether by serialization or otherwise: see [18 Serialization]).
It is applied to a temporary tree, before the temporary tree is made available for processing by stylesheet instructions. (see [6.1 Values of Variables and Parameters]).
There is no requirement to perform namespace fixup for the principal source document, nor for any document loaded using the document function, nor for any document supplied as the value of a global parameter, nor for any document returned by an extension function. [ERR017] It is a dynamic error if such a document does not already satisfy the constraints listed above . The processor may signal the error, or may recover by performing namespace fixup, or may produce implementation-defined results.
If an implementation supports
the disable-output-escaping
attribute
of xsl:text
and xsl:value-of
(see [18.5 Disabling Output Escaping]), then the data model
for trees constructed by the processor is augmented with a boolean value
representing the value of this property.
Conceptually, each character in a text node on a result tree has a boolean
property indicating whether the serializer should disable the normal rules
for escaping of special characters (for example, outputting of &
as &
) in respect of this character.
This property is preserved when a text node is copied using xsl:copy
or xsl:copy-of
.
NOTE: There are many ways an implementation can avoid the overhead of actually storing a boolean flag with every character.
The name of an internal XSLT object, specifically a named template (see [7.1 Named Templates]), a mode (see [5.6 Modes]), an attribute set (see [7.2 Named Attribute Sets]), a key (see [14.3 Keys]), a named sort specification (see [12.3 Using Named Sort Specifications]), a decimal-format (see [14.4 Number Formatting]), a variable or parameter (see [6 Variables and Parameters]), a stylesheet function (see [7.3 Stylesheet Functions]), or a named output definition (see [18 Serialization]), is specified as a QName.
A QName is
always written in the form NCName (":" NCName)?
, that is, a local name
optionally qualified by a namespace prefix. When two QNames are compared, however,
they are considered equal if the corresponding
expanded QNames are the same.
An expanded QName is a pair of values containing a namespace URI and a local name. A QName is expanded by replacing the namespace prefix with the corresponding namespace URI, from the namespace declarations that are in scope at the point where the QName is written. Two expanded QNames are equal if the namespace URIs are the same and the local names are the same.
QNames always occur either as the value of an attribute node in a stylesheet module, or within an XPath expression contained in such an attribute node, or as the result of evaluating an XPath expression contained in such an attribute node. The element containing this attribute node is referred to as the defining element of the QName.
Issue (leading-colon-in-qname): The current XPath grammar allows a QName to contain a leading colon. This leading colon is not considered part of the QName as far as XSLT is concerned, and is not permitted in contexts other than an XPath expression.
If the QName has a prefix, then the
prefix is expanded into a URI reference using the namespace
declarations in effect on its defining element. The
expanded QName
consisting of the local part of the name and the possibly null URI
reference is used as the name of the object. The default namespace (as defined by
a namespace declaration of the form xmlns="some.uri"
) is
not used for unprefixed names.
In the case of an unprefixed QName used as a NameTest
within an XPath expression
(see [4.2 Expressions]) or within a pattern (see [4.3 Patterns]), the namespace
to be used in expanding the QName may be specified by means of the [xsl:]default-xpath-namespace
attribute, as specified in [4.4 Unprefixed Names in Expressions and Patterns].
[ERR018] In the case of a QName used as the value of an attribute in the stylesheet, or appearing within the text of an XPath expression in the the stylesheet, it is a static error if the defining element has no namespace node whose name matches the prefix of the QName.
[ERR019] In the case of a QName produced by evaluating an XPath expression, it is a dynamic error if the defining element has no namespace node whose name matches the prefix of the QName. The error is a dynamic error even if the value of the expression is known statically, for example if the QName is written as a string literal. The required action depends on the defining element.
XSLT uses the expression language defined by XPath 2.0 [XPath 2.0]. Expressions are used in XSLT for a variety of purposes including:
An expression must match the XPath production Expr.
An XPath expression may occur as the value of certain attributes on XSLT-defined elements, and also within curly braces in attribute value templates.
[ERR020] It is a static error if the value of such an attribute, or the text between curly braces in an attribute value template, does not match the XPath production Expr, or if it fails to satisfy other static constraints defined in the XPath specification, for example that all variable references must refer to variables that are in scope.
The context within a stylesheet where an XPath expression may appear determines the required type of the expression. The required type indicates the data type of value that the expression is expected to return.
[ERR021] It is a type error if an XPath expression contains a type error, or if the type of the XPath expression is incompatible with the required type. The processor must either signal a type error as a static error, or must attempt to recover by converting the result of the expression to the required type using the standard type conversion rules; if conversion is not possible under these rules, the processor must signal a dynamic error
Issue (type-compatibility): We need to provide a more rigorous definition of what it means for the supplied value to be compatible with the required type.
The context for evaluation of an XPath expression is determined according to the following rules. The context has two parts: the static context, and the dynamic expression evaluation context.
The static context depends on the element in the stylesheet that contains the attribute holding the XPath expression ("the containing element") as follows:
The type exception policy is, by default, flexible, meaning that the system attempts to convert supplied values to the required type when possible. An implementation may provide the alternative policy, strict, as a user-selectable option.
The in-scope namespaces are the namespace declarations that are in scope for the containing element.
The default namespace for element names is the namespace defined by the
innermost [xsl:]default-xpath-namespace
attribute, as described in
[4.4 Unprefixed Names in Expressions and Patterns].
The default namespace for function names is the namespace
http://www.w3.org/2001/12/xquery-operators
,
defined in [Functions and Operators]. This means that it is not necessary to declare this
namespace in the stylesheet, nor to use the prefix xf
used in the
specification of the core functions.
Ed. Note: The current draft of the Functions & Operators document includes an issue suggesting this namespace may change.
The in-scope type definitions includes the built-in types of XML Schema (see [XML Schema]), plus any types imported using implementation-defined mechanisms.
The in-scope variables are the variable-bindings that are in scope for the containing element (see [6 Variables and Parameters]).
The in-scope functions are the core functions defined by XPath, the additional functions defined in this specification, the stylesheet functions defined in the stylesheet, plus any extension functions bound using implementation-defined mechanisms (see [16 Extensibility and Fallback]). [ERR022] It is a dynamic error for an expression to call any function that is not included in the in-scope functions. The processor must signal the error, but only if the function call is actually evaluated.
The in-scope collations are implementation-defined.
Issue (stylesheet-defined-collations): Should the stylesheet define names of collations? If so, how are they to be described? Should we encourage portability by providing some indirection between the collation name and the underlying collation? But if this is to aid portability, there needs to be a way of selecting different mappings based on the XSLT implementation.
The default collation is implementation-defined.
The base URI is the base URI of the containing element.
The evaluation context, which includes the focus, is determined as follows:
Where the containing element is an instruction or a literal result element, the focus is established as follows. In other cases, the rules are given for the specific containing element.
A template rule identifies the nodes to which it applies by means of a pattern. As well as being used in template rules, patterns are used for numbering (see [9 Numbering]), for grouping (see [13 Grouping]), and for declaring keys (see [14.3 Keys]).
A pattern specifies a set of conditions on a node. A node that satisfies the conditions matches the pattern; a node that does not satisfy the conditions does not match the pattern. The syntax for patterns is a subset of the syntax for expressions. As explained in detail below, a node matches a pattern if the node can be selected by evaluating this expression with respect to some possible context.
Here are some examples of patterns:
para
matches any para
element
*
matches any element
chapter|appendix
matches any
chapter
element and any appendix
element
olist/item
matches any item
element with
an olist
parent
appendix//para
matches any para
element with
an appendix
ancestor element
/
matches the document node
of any source document
text()
matches any text node
node()
matches any node other than an attribute
node, namespace node, or document node
id("W11")
matches the element with unique ID
W11
para[1]
matches any para
element
that is the first para
child element of its
parent
item[position() mod 2 = 1]
matches any
item
element that is an odd-numbered item
child of its parent.
div[@class="appendix"]//p
matches any
p
element with a div
ancestor element that
has a class
attribute with value
appendix
@class
matches any class
attribute
(not any element that has a class
attribute)
@*
matches any attribute node
[ERR023] Where an attribute is
defined to contain a pattern,
it is a static error if the
pattern does not match the production Pattern.
Every pattern is a legal XPath
expression, but the converse is not true: 2+2
is an example of a legal XPath expression that is not a pattern.
The XPath expressions that can be used as patterns are those that
match the grammar for Pattern, given below.
Informally, a Pattern is
a set of path expressions separated by |
, where each step
in the path expression is constrained to be an AxisStepExpr that uses only the
child
or attribute
axes. Patterns may
also use the //
operator, and they may start with an
id or key function call
provided its arguments are string literals. Predicates in a pattern
(the construct enclosed between square brackets)
can contain arbitrary
XPath expressions in the same way as predicates in a path expression.
If a pattern occurs in part of the stylesheet where backwards compatible behavior is enabled (see [2.6 Backwards-Compatible Processing]), then the pattern is restricted to use the syntax for patterns defined in XSLT 1.0, and will match a node if and only if it would have matched that node under the rules defined in XSLT 1.0.
[1] | Pattern | ::= | PathPattern | |
| Pattern ('|' | 'union') PathPattern | ||||
[2] | PathPattern | ::= | RelativePathPattern | |
| '/' RelativePathPattern? | ||||
| '//' RelativePathPattern | ||||
| IdKeyPattern (('/' | '//') RelativePathPattern)? | ||||
[3] | RelativePathPattern | ::= | PatternStep (('/' | '//') RelativePathPattern)? | |
[4] | PatternStep | ::= | PatternAxis? NodeTest ( '[' Expr ']' )* | |
[5] | PatternAxis | ::= | ('child' | 'attribute' | '@') '::' | |
[6] | IdKeyPattern | ::= | 'id' '(' StringLiteral ')' | |
| 'key' '(' StringLiteral ',' StringLiteral ')' |
The constructs NodeTest, StringLiteral, and Expr are part of the XPath expression language, and are defined in [XPath 2.0].
The meaning of a pattern is defined formally as follows. To determine whether
a node N matches a pattern PAT, evaluate the expression
//(PAT)
with a
singleton focus based on N.
If the result is a sequence of nodes that includes N, then node N
matches the pattern; otherwise node N does not match the pattern.
This expression is constructed by textually inserting the pattern PAT
exactly as written in the stylesheet.
For example, p
matches any p
element,
because a p
element will always be present in the result
of evaluating the expression //(p)
. Similarly, /
matches a document node, and only a document node, because the result of the
expression //(/)
when applied using a particular document as
context document
returns only the document node of that document.
NOTE: Although the semantics of patterns are specified formally in terms of expression evaluation, it is possible to understand pattern matching using a different model. In a pattern,|
indicates alternatives; a pattern with one or more|
separated alternatives matches if any one of the alternatives matches. A pattern such asbook/chapter/section
can be examined from right to left. A node will only match this pattern if it is asection
element; and then, only if its parent is achapter
; and then, only if the parent of thatchapter
is abook
. When the pattern uses the//
operator, one can still read it from right to left, but this time testing the ancestors of a node rather than its parent. For exampleappendix//section
matches everysection
element that has an ancestorappendix
element. The formal definition, however, is useful for understanding the meaning of a pattern such asitem[1]
. This matches any node selected by the expression//(item[1])
: that is, anyitem
element that is the firstitem
child of its parent.
The pattern node()
matches all nodes selected by the expression
//(node())
, that is, all element, text, comment, and processing
instruction nodes. It does not match attribute or namespace nodes because the
expression does not select nodes using the attribute or namespace axes.
NOTE: An implementation, of course, may use any algorithm it wishes for evaluating patterns, so long as the result corresponds with the formal definition above. An implementation that followed the formal semantics by evaluating the equivalent expression and then testing the membership of a specific node in the result would probably be very inefficient.
The attribute [xsl:]default-xpath-namespace
(see [2.3 Standard Attributes]) may be used
on an element in the stylesheet to define the namespace URI that will be
used for an unprefixed name used as a NameTest within a step
of an XPath PathExpression
or an XSLT Pattern occurring in an attribute
of that stylesheet element or an attribute
of a descendant of that stylesheet element.
This default namespace URI applies only to a NameTest applied to an axis whose
principal node type is elements: it does not apply when the step is using the attribute or namespace axis.
The default namespace URI for such a name is the value of the
[xsl:]default-xpath-namespace
attribute on the innermost ancestor element that has
such an attribute, considering all ancestor elements of the attribute
containing the XPath expression or XSLT pattern.
The [xsl:]default-xpath-namespace
attribute must be in the
XSLT namespace only if its parent element is not in the XSLT namespace.
In the absence of this attribute, an unqualified NameTest
(that
is, a NameTest
that is an NCName
) matches
an expanded QName whose namespace URI is null: the default namespace (as defined by
an xmlns="some-uri"
declaration) is not used.
The default-xpath-namespace
only affects unqualified names (names
containing no colon) used
in a NameTest
. It does not affect other names, for example function names,
variable names, or names used as arguments to the key or
system-property functions.
Issue (runtime-namespace-selection): The default-xpath-namespace facility as proposed here doesn't meet the requirement to match multiple namespaces, or to decide at run-time which namespace to match - as exemplified by the XHTML scenario.
Ed. Note: Do we need to add this attribute to all element proformas and to the DTD?
In an
attribute that is designated as an
attribute value template, such as an attribute of a
literal result element,
an expression can be used by surrounding
the expression with curly braces ({}
).
An attribute value template consists of an alternating
sequence of fixed parts and variable parts. A variable part consists of
an XPath expression enclosed
in curly braces ({}
). A fixed part
may contain any characters, except that a left curly brace must be written as
{{
and a right curly brace must be written as }}
.
NOTE: An expression within a variable part may contain an unescaped curly brace within a StringLiteral.
[ERR024] It is a static error if a left curly brace appears in an attribute value template without a matching right curly brace.
[ERR025] It is a static error if the string contained between matching curly braces in an attribute value template does not match the XPath production Expr.
[ERR026] It is a static error if a right curly brace occurs in an attribute value template outside an expression without being followed by a second right curly brace. A right curly brace inside a StringLiteral in an expression is not recognized as terminating the expression.
The required type of each expression
within an attribute value template is xsd:string
.
The
result of evaluating an attribute value template is referred to as the
effective value of the attribute. The effective value
is the string obtained by concatenating the expansions
of the fixed and variable parts. The expansion of a fixed part is obtained by
replacing any double curly braces ({{
or }}
) by the
corresponding single curly brace. The expansion of a variable part is obtained
by evaluating the enclosed XPath
expression and converting the resulting value to a string as if by a
call to the string function.
Curly braces are not treated specially in an attribute value in an XSLT stylesheet unless the attribute is specifically designated as one that permits an attribute value template; in an element syntax summary, the value of such attributes is surrounded by curly braces.
NOTE: Not all attributes are interpreted as attribute value templates. Attributes whose value is an expression or pattern, attributes of top-level elements and attributes that refer to named XSLT objects are not interpreted as attribute value templates. In addition,xmlns
attributes are not interpreted as attribute value templates; it would not be conformant with the XML Namespaces Recommendation to do this. Two exceptions are thexsl:output
andxsl:destination
declarations: although these are top-level elements, many of their attributes are interpreted as attribute value templates.
The following example creates an img
result element
from a photograph
element in the source; the value of the
src
attribute of the img
element is computed
from the value of the image-dir
variable and the
string-value of the href
child of the
photograph
element; the value of the width
attribute of the img
element is computed from the value
of the width
attribute of the size
child of
the photograph
element:
<xsl:variable name="image-dir">/images</xsl:variable> <xsl:template match="photograph"> <img src="{$image-dir}/{href}" width="{size/@width}"/> </xsl:template>
With this source
<photograph> <href>headquarters.jpg</href> <size width="300"/> </photograph>
the result would be
<img src="/images/headquarters.jpg" width="300"/>
Curly braces are not recognized recursively inside expressions. For example:
<a href="#{id({@ref})/title}">
is not allowed. Instead, use simply:
<a href="#{id(@ref)/title}">
NOTE: The term content constructor replaces template as used in XSLT 1.0. The change is made partly for clarity (to avoid confusion with template rules and named templates), but also to reflect a more formal definition of the semantics. Whereas XSLT 1.0 described a template as a sequence of instructions that write to the result tree, XSLT 2.0 describes a content constructor as something that can be evaluated to return a sequence of nodes; what happens to these nodes depends on the containing instruction.
Many XSLT elements (including literal result elements) are defined to take as their content a content constructor.
A content constructor is a sequence of nodes in the stylesheet that, when evaluated, constructs and returns a sequence of new nodes suitable for adding to the result tree. This sequence is referred to below as the result sequence.
Four kinds of nodes may be encountered in a content constructor:
Text nodes appearing in the stylesheet (if they have not been removed in the process of whitespace stripping: see [3.4 Whitespace Stripping]) are copied to create a new text node in the result sequence.
Literal result elements are evaluated to create a new element node, having the same name as the literal result element, which is added to the result sequence: see [8.1 Literal Result Elements]
XSLT instructions produce
a sequence of zero, one, or more nodes as their
result. These nodes are added to the result sequence. Some instructions,
such as xsl:element
, return a newly-constructed node (which may
have its own attributes, namespaces, children, and other descendants); others, such
as xsl:if
, return nodes produced by their own nested content
constructors.
Extension instructions also produce a sequence of nodes as their result, which is added to the result sequence.
The node sequences produced by each node in the content constructor are concatenated to form a single result sequence. This concatenation retains the order of the nodes within the content constructor: if while evaluating a content constructor, node M is constructed by instruction I, and node N is constructed by a different instruction J, then N will appear after M in the result sequence if and only if J follows I in document order. This does not mean that the nodes in a content constructor must be evaluated sequentially: on the contrary, they may be evaluated in any order, or in parallel, provided that their results are assembled in the correct sequence on completion.
If the result sequence contains two or more adjacent text nodes, these adjacent text nodes are concatenated to form a single text node.
The result sequence will never contain a document node. [ERR027] It is an dynamic error if an extension instruction attempts to return a sequence containing a document node. The processor must signal the error.
[ERR028] It is a dynamic error if the result sequence (after concatenating the results of individual instructions) contains a namespace node that is preceded in the sequence by a node that is not a namespace node. The processor must either signal the error, or must recover by ignoring the offending namespace node.
Issue (must-namespaces-precede-attributes): It appears that several implementations currently allow a namespace node to be added after adding attributes (using
xsl:copy
). This seems convenient for the user, and the Working Group is inclined to allow it. To achieve this, we will need to define some conflict resolution if the namespace clashes with an existing attribute.
[ERR029] It is a dynamic error if the result sequence (after concatenating the results of individual instructions) contains an attribute node that is preceded in the sequence by a node that is neither a namespace node nor an attribute node. The processor must either signal the error, or must recover by ignoring the offending attribute node.
What actually happens to the nodes in the result sequence depends on the element containing the
content constructor. Some elements, such as xsl:if
, simply return the
sequence of nodes, which are added to the result of the content constructor containing
the xsl:if
instruction. Other elements, such as xsl:element
,
xsl:comment
, and xsl:variable
, construct a new node, and use the
value returned by the content constructor to create the children or the text content of
the new node.
Specifically:
[ERR030] Elements such as xsl:variable
, xsl:param
,
xsl:message
, and xsl:result-document
construct a new document node,
and use the result sequence returned by the content constructor to form the children of
this document node. In this case it is an dynamic error
if the result sequence contains namespace
or attribute nodes. The processor must either signal the error, or must recover by ignoring the offending
nodes. The elements, comments, processing instructions, and text nodes
in the node sequence form the children of the newly constructed document node.
Elements such as xsl:element
, xsl:copy
,
and literal result elements construct a new element node,
and use the result sequence returned by the content constructor to form the children of
this element node. The elements, comments, processing instructions, and text nodes
in the result sequence form the children of the newly constructed document node.
Any namespace nodes in the result sequence are merged with any existing namespace nodes in the same document, for the same namespace prefix and URI, and are then added to the in-scope namespaces of the target element. [ERR031] It is a dynamic error to add a namespace node to an element if the element already has a namespace node with the same name, unless both namespace nodes have the same string-value, in which case the duplicate is ignored. It is also a dynamic error to add a namespace node to an element if the namespace node has a null name and the element has a null namespace URI. In both cases the processor must either signal the error, or must recover by ignoring the offending namespace node.
Any attribute nodes in the result sequence are added to the target element. If the target element already has an attribute with the same expanded QName, the new attribute overwrites the existing attribute. If two or more attributes in the result sequence have the same expanded QName, the one that appears latest in the result sequence is the only one that is used.
The xsl:comment
, xsl:attribute
,
xsl:processing-instruction
, xsl:text
,
and xsl:namespace
elements
create nodes that cannot have children. In these
cases the result sequence produced by the content constructor is used to establish the
string-value of the new node.
[ERR032] It is a dynamic error
if the result sequence contains nodes other
than text nodes. The processor must either signal the error, or must recover by ignoring
the non-text nodes together with their content.
The xsl:apply-templates
instruction
takes as input a sequence of nodes in the source tree, and produces
as output a sequence of nodes which are typically added to the result
tree. Each node in the input sequence is processed by finding a
template rule whose pattern
matches that node. If there is more than one,
the best among them is chosen; if there is none, a built-in template rule
is used. The content constructor that
forms the body of the chosen template rule
is evaluated to produce a sequence of nodes. The resulting sequences of nodes
(one for each node in the input sequence) are then concatenated, to form
a single sequence. They are concatenated retaining the order of the nodes
in the original input sequence, unless a different order is requested using
xsl:sort
.
The final concatenated sequence of nodes forms the result of the
xsl:apply-templates
instruction: what happens to it next
depends on the context in which the xsl:apply-templates
instruction appeared.
Ed. Note: Given that the above paragraph explains an important concept, it could be more clearly written.
The stylesheet as a whole is evaluated by evaluating
an implicit xsl:apply-templates
instruction with
the document node (that is, the root)
of the principal
source document as the (singleton) input node sequence.
NOTE: An implementation may also allow processing to start with some different node sequence, using mechanisms outside the scope of this specification.
A content constructor will often contain an
xsl:apply-templates
instruction selecting the children of the
node as the input sequence for processing.
This will cause a template rule to be invoked
for each of these children. The nodes constructed by the content constructor
for a child node can be added as children to the nodes constructed by
the content constructor for their parent. Thus it is possible to construct a result tree
whose structure corresponds to the structure of the source tree.
Implementations are free to process the source document in any way that produces the same result as if it were processed using this processing model.
<!-- Category: declaration -->
<xsl:template
match = pattern
name = qname
priority = number
mode = qname>
<!-- Content: (xsl:param*, content-constructor) -->
</xsl:template>
A template rule is specified with the xsl:template
element. The match
attribute is a Pattern that identifies the source node or nodes
to which the rule applies. The match
attribute is
required unless the xsl:template
element has a
name
attribute (see [7.1 Named Templates]).
It is an static error for
the value of the match
attribute to
contain a Variable.
The result of applying the template rule is the
result of evaluating the content constructor contained in the
xsl:template
element, with the matching node used
as the context node
Issue (variables-in-match-patterns): Is the rule excluding a Variable useful? Its main purpose is to prevent circularity, where a global variable issues xsl:apply-templates and the variable needs to be evaluated to determine the match. But the rule is not sufficient to prevent circularity, because the template rule, once selected, can contain instructions that reference the global variable. However, it might be useful to retain the rule because it helps processors optimize matching of template rules. Also note, the rule needs to be phrased so that range variables declared locally within a sub-expression are permitted.
For example, an XML document might contain:
This is an <emph>important</emph> point.
The following template rule matches emph
elements and
produces a fo:wrapper
formatting object with a
font-weight
property of bold
.
<xsl:template match="emph"> <fo:wrapper font-weight="bold"> <xsl:apply-templates/> </fo:wrapper> </xsl:template>
NOTE: Examples in this document use thefo:
prefix for the namespacehttp://www.w3.org/1999/XSL/Format
, which is the namespace of the formatting objects defined in [XSL Formatting Objects].
As described next, the xsl:apply-templates
element
recursively processes the children of the source element.
<!-- Category: instruction -->
<xsl:apply-templates
select = node-sequence-expression
mode = qname>
<!-- Content: (xsl:sort | xsl:with-param)* -->
</xsl:apply-templates>
This example creates a block for a chapter
element and
then processes its immediate children.
<xsl:template match="chapter"> <fo:block> <xsl:apply-templates/> </fo:block> </xsl:template>
In the absence of a select
attribute, the
xsl:apply-templates
instruction processes all of the
children of the context node, including text nodes.
[ERR033] It is a dynamic error if
the context item is not a node.
The processor must either signal the error, or
must recover by returning an empty sequence.
Whitespace text nodes that have been stripped as specified in [3.4 Whitespace Stripping] will not be processed. If stripping of whitespace nodes has not been enabled for an element, then all whitespace in the content of the element will be processed as text, and thus whitespace between child elements will count in determining the position of a child element as returned by the position function.
A select
attribute can be used to process nodes
selected by an expression instead of processing all children. The
value of the select
attribute is an
expression. The expression must
evaluate to a sequence (which can contain
zero, one, or more nodes). The selected nodes are processed in
the order of this sequence, unless a sorting specification is present (see
[12 Sorting]).
[ERR034] It is a dynamic error if
the sequence returned by the select
expression
contains an item that is not a node.
The processor must either signal the error, or must recover by ignoring the offending
items.
NOTE: In XSLT 1.0, the select
attribute selected a set of nodes, which
by default were processed in document order. In XSLT 2.0, it selects a sequence of nodes.
In cases that would have been valid in XSLT 1.0, the expression will return a sequence of
nodes in document order, so the effect is the same.
The following example processes all of the
author
children of the author-group
:
<xsl:template match="author-group"> <fo:wrapper> <xsl:apply-templates select="author"/> </fo:wrapper> </xsl:template>
The following example processes all of the given-name
s
of the author
s that are children of
author-group
:
<xsl:template match="author-group"> <fo:wrapper> <xsl:apply-templates select="author/given-name"/> </fo:wrapper> </xsl:template>
This example processes all of the heading
descendant
elements of the book
element.
<xsl:template match="book"> <fo:block> <xsl:apply-templates select=".//heading"/> </fo:block> </xsl:template>
It is also possible to process elements that are not descendants of
the context node. This example assumes that a department
element has group
children and employee
descendants. It finds an employee's department and then processes
the group
children of the department
.
<xsl:template match="employee"> <fo:block> Employee <xsl:apply-templates select="name"/> belongs to group <xsl:apply-templates select="ancestor::department/group"/> </fo:block> </xsl:template>
Multiple xsl:apply-templates
elements can be used within a
single template to do simple reordering. The following example
creates two HTML tables. The first table is filled with domestic sales
while the second table is filled with foreign sales.
<xsl:template match="product"> <table> <xsl:apply-templates select="sales/domestic"/> </table> <table> <xsl:apply-templates select="sales/foreign"/> </table> </xsl:template>
NOTE: It is possible for there to be two matching descendants where one is a descendant of the other. This case is not treated specially: both descendants will be processed as usual. For example, given a source document<doc><div><div></div></div></doc>the rule<xsl:template match="doc"> <xsl:apply-templates select=".//div"/> </xsl:template>will process both the outerdiv
and innerdiv
elements.
NOTE: Typically,xsl:apply-templates
is used to process only nodes that are descendants of the context node. Such use ofxsl:apply-templates
cannot result in non-terminating processing loops. However, whenxsl:apply-templates
is used to process elements that are not descendants of the context node, the possibility arises of non-terminating loops. For example,<xsl:template match="foo"> <xsl:apply-templates select="."/> </xsl:template>Implementations may be able to detect such loops in some cases, but the possibility exists that a stylesheet may enter a non-terminating loop that an implementation is unable to detect. This may present a denial of service security risk.
It is possible for a node in a source document to match more than one template rule. The template rule to be used is determined as follows:
First, all matching template rules that have lower import precedence than the matching template rule or rules with the highest import precedence are eliminated from consideration.
Next, all matching template rules that have lower priority
than the matching template rule or rules with the highest priority are
eliminated from consideration. The priority of a template rule is
specified by the priority
attribute on the template rule.
[ERR035] The value of this
must be a real number (positive or negative),
matching the production NumericLiteral
with an optional leading minus sign (-
).
[ERR036] If an xsl:template
element does not have
a match
attribute, then it must not have a priority
attribute.
If no priority
attribute is specified on the xsl:template
element, the default
priority is computed as follows:
If the pattern contains multiple alternatives separated by
|
, then it is treated equivalently to a set of template
rules, one for each alternative. Note, however, that
it is not an error if a node matches more than one of the alternatives.
If the pattern has the form of a QName optionally preceded by a PatternAxis
or has the form
processing-instruction(
StringLiteral)
optionally preceded by a PatternAxis,
then the priority is 0.
If the pattern has the form NCName:*
or *:
NCName,
optionally preceded by a PatternAxis,
then the priority is -0.25.
Otherwise, if the pattern consists of just a NodeTest optionally preceded by a PatternAxis, then the priority is -0.5.
Otherwise, the priority is 0.5.
NOTE: In many cases this means that highly-selective patterns have higher priority than less-selective patterns. The most common kind of pattern (a pattern that tests for a node with a particular type and a particular expanded-name) has priority 0. The next less specific kind of pattern (a pattern that tests for a node with a particular type and an expanded-name with a particular namespace URI) has priority -0.25. Patterns less specific than this (patterns that just tests for nodes with particular types) have priority -0.5. Patterns more specific than the most common kind of pattern have priority 0.5. However, it is not invariably true that a more selective pattern has higher priority than a less selective pattern. For example, the priority of the patternnode()[self::*]
is higher than that of the patternitem
. Therefore, to achieve clarity in a stylesheet it is good practice to allocate explicit priorities.
[ERR037] It is a dynamic error if this leaves more than one matching template rule. The processor must either signal the error, or must recover by choosing, from amongst the matching template rules that are left, the one that occurs last in declaration order.
<!-- Category: instruction -->
<xsl:apply-imports>
<!-- Content: xsl:with-param* -->
</xsl:apply-imports>
A template rule that
is being used to override a template rule in
an imported stylesheet (see [5.4 Conflict Resolution for Template Rules]) can use the
xsl:apply-imports
element to invoke the overridden
template rule.
At any point in the processing
of a stylesheet, there may be a
current template rule. Whenever a template rule is
chosen by matching a pattern, the template rule becomes the current
template rule for the evaluation of the rule's content constructor. When an
xsl:for-each
or xsl:for-each-group
instruction is evaluated, the current
template rule becomes null for the evaluation of the content of the
xsl:for-each
or xsl:for-each-group
instruction.
The current template rule is not affected by invoking named templates (see [7.1 Named Templates]), named attribute sets (see [7.2 Named Attribute Sets]), nor stylesheet functions (see [7.3 Stylesheet Functions]). While evaluating a global variable or parameter (see [6.2 Global Variables and Parameters]) the current template rule is null.
xsl:apply-imports
searches for
a template rule that matches the
context node, and whose mode is the same as the current template
rule's mode (see [5.6 Modes]). In choosing
a template rule, it uses the usual criteria such as the priority and
import precedence of
the template rules, but it considers as candidates
only those template rules contained in stylesheet levels
that are descendants in the import tree
of the stylesheet
level that contains the
current template rule.
NOTE: This is not the same as saying that the search considers all template rules whose import precedence is lower than that of the current template rule.
If no matching template rule is found that satisfies these criteria, the built-in template rule for the node type is used (see [5.7 Built-in Template Rules]).
[ERR038] It is an error if the xsl:apply-imports
instruction is evaluated when the context item
is not a node. The processor
must either signal the error, or must recover by returning an empty sequence.
An xsl:apply-imports
element may use
xsl:with-param
child elements to pass
parameters to the chosen template rule
(see [7.1.1 Passing Parameters to Templates]).
[ERR039] It is a dynamic error if
xsl:apply-imports
is evaluated when the
current template rule is null.
The processor must signal the error.
For example, suppose the stylesheet doc.xsl
contains a
template rule for example
elements:
<xsl:template match="example"> <pre><xsl:apply-templates/></pre> </xsl:template>
Another stylesheet could import doc.xsl
and modify the
treatment of example
elements as follows:
<xsl:import href="doc.xsl"/> <xsl:template match="example"> <div style="border: solid red"> <xsl:apply-imports/> </div> </xsl:template>
The combined effect would be to transform an example
into an element of the form:
<div style="border: solid red"><pre>...</pre></div>
Modes allow a node in the source tree to be processed multiple times, each time producing a different result. They also allow different sets of template rules to be active when processing different trees, for example when processing documents loaded using the document function (see [14.1 Multiple Source Documents]) or when processing temporary trees (see [6 Variables and Parameters])
Both xsl:template
and xsl:apply-templates
have an optional mode
attribute. The value of the
mode
attribute is a QName, which is expanded as described
in [4.1 Qualified Names].
If an xsl:apply-templates
element has a
mode
attribute, then it applies only to those template
rules from xsl:template
elements that have a
mode
attribute with the same value; if an
xsl:apply-templates
element does not have a
mode
attribute, then it applies only to those template
rules from xsl:template
elements that do not have a
mode
attribute.
[ERR040] If an xsl:template
element does not have
a match
attribute, then it is a
static error if it has a mode
attribute.
There is a built-in template rule to allow recursive processing to continue in the absence of a successful pattern match by an explicit template rule in the stylesheet. This template rule applies to both element nodes and the document node. The following shows the equivalent of the built-in template rule:
<xsl:template match="*|/"> <xsl:apply-templates/> </xsl:template>
There is also a built-in template rule
for each mode, which allows
recursive processing to continue in the same mode in the absence of a
successful pattern match by an explicit template rule in the
stylesheet. This template rule applies to both element nodes and the
document node. The following shows the equivalent of the built-in
template rule for mode m
.
<xsl:template match="*|/" mode="m"> <xsl:apply-templates mode="m"/> </xsl:template>
Issue (parameters-with-built-in-templates): Would it be useful to define that parameters to a built in template are passed through unchanged? This is a frequent source of user bewilderment. The change would be technically backwards incompatible, but very unlikely to have adverse effects.
There is also a built-in template rule for text and attribute nodes that copies text through:
<xsl:template match="text()|@*"> <xsl:value-of select="."/> </xsl:template>
The built-in template rule for processing instructions and comments is to do nothing.
<xsl:template match="processing-instruction()|comment()"/>
The built-in template rule for namespace nodes is also to do nothing. There is no pattern that can match a namespace node; so, the built-in template rule is the only template rule that is applied for namespace nodes.
The built-in template rules for text, attribute, comment, processing-instruction, and namespace nodes for a specific mode are the same as the rules shown above that apply where no mode is specified.
The built-in template rules have lower import precedence than all other template rules. Thus, the stylesheet author can override a built-in template rule by including an explicit template rule.
<!-- Category: declaration -->
<!-- Category: instruction -->
<xsl:variable
name = qname
select = expression
type = datatype>
<!-- Content: content-constructor -->
</xsl:variable>
<!-- Category: declaration -->
<xsl:param
name = qname
select = expression
type = datatype>
<!-- Content: content-constructor -->
</xsl:param>
The
two elements xsl:variable
and xsl:param
are referred to as variable-binding elements.
A variable is a name that may be bound to a value. The value to
which a variable is bound (the value of the variable) can
be an object of any of the types that can be returned by expressions.
There are two elements that can be used to bind variables:
xsl:variable
and xsl:param
. The difference
is that the value specified on the xsl:param
variable is
only a default value for the binding; when the template or stylesheet
within which the xsl:param
element occurs is invoked,
parameters may be passed that are used in place of the default
values.
Both xsl:variable
and xsl:param
have a
required name
attribute, which specifies the name of the
variable. The value of the name
attribute is a QName, which is expanded as described
in [4.1 Qualified Names].
Both xsl:variable
and xsl:param
have an
optional type
attribute, which specifies the
required type of the
variable. The value of the type
attribute is a DataType,
as defined in [XPath 2.0]. The result of evaluating the expression contained
in the select
attribute, or in the case of xsl:param
,
the value supplied by the caller, is referred to as the supplied value of the variable.
[ERR041] If the type
attribute
is specified, then the supplied value of the
variable is converted to the required type, using the rules for the XPath cast
expression. It is a type error
if this conversion fails.
If the type
attribute is omitted, the supplied value of the variable is used
directly, and no conversion takes place.
Issue (variable-type-semantics): We need to say more about the permitted values of the type attribute, and their meaning, once the XPath rules are clearer. For example, are all the permitted names of types known statically, and if so, where do these names come from?
Issue (variable-type-conversion): Should the
type
attribute onxsl:variable
cause the supplied value to be converted to the required type, or should it cause a dynamic error to be signaled if the supplied value does not conform to the required type: perhaps with conversion as a recovery action?
For any use of these variable-binding elements, there is a region of the stylesheet tree within which the binding is visible. The set of variable bindings in scope for an expression consists of those bindings that are visible at the point in the stylesheet where the expression occurs.
A variable-binding element can specify the value of the variable in three alternative ways.
[ERR042] If the variable-binding element has a select
attribute, then the value of the attribute must be an
expression and the value of the variable
is the value that results from evaluating the expression. In this
case, the content of the variable-binding element must be empty.
If a variable-binding element has no select
attribute and has non-empty content (i.e. the variable-binding element
has one or more child nodes), then the content of the
variable-binding element specifies the value. The content of the
variable-binding element is a
content constructor; a new
document (referred to as a temporary tree) is constructed with a document
node having as its children
the sequence of nodes that results from evaluating the content constructor.
Namespace fixup is
performed on the temporary tree (see [3.5 Namespace Fixup]). The
value of the variable is a single node, the document node
of the temporary tree.
The base URI of a node in the
temporary tree is determined as
if all the nodes in the temporary tree came from a single entity whose URI
was the base URI of the variable-binding element (see [Data Model]).
Thus, the base URI of the document node will be equal
to the base URI of the variable-binding element; an
xml:base
attribute within the temporary tree will change the
base URI for its parent element and that element's descendants, just
as it would within a document constructed by parsing.
A temporary tree is
available for processing
in exactly the same way as any source document. For example, its nodes
are accessible using path expressions, and they can be processed using
instructions such as xsl:apply-templates
and xsl:for-each
.
For example, the following stylesheet uses a temporary tree as the intermediate
result of a two-phase transformation, using different modes for the two phases
(see [5.6 Modes]):
Ed. Note: We need to add examples to clarify how the
type
attribute works, especially with temporary trees.
<xsl:stylesheet version="2.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> <xsl:import href="phase1.xsl"/> <xsl:import href="phase2.xsl"/> <xsl:variable name="intermediate"> <xsl:apply-templates select="/" mode="phase1"/> </xsl:variable> <xsl:template match="/"> <xsl:apply-templates select="$intermediate" mode="phase2"/> </xsl:template> </xsl:stylesheet>
NOTE: The algorithm for matching nodes against template rules is exactly the same regardless which tree the nodes come from; if nodes from different trees cannot be distinguished by their expanded QName, it is therefore a good idea to use modes to ensure that each tree is processed using the appropriate set of template rules.
If the variable-binding element has empty content and does not have
a select
attribute, then the value of the variable is an
empty string. Thus
<xsl:variable name="x"/>
is equivalent to
<xsl:variable name="x" select="''"/>
NOTE: When a variable is used to select nodes by position, be careful not to do:<xsl:variable name="n">2</xsl:variable> ... <xsl:value-of select="item[$n]"/>This will output the value of the first item element, because the variablen
will be bound to a node, not a number. Instead, do either<xsl:variable name="n" select="2"/> ... <xsl:value-of select="item[$n]"/>or<xsl:variable name="n">2</xsl:variable> ... <xsl:value-of select="item[position()=$n]"/>
Both xsl:variable
and xsl:param
are
allowed as top-level elements.
A top-level variable-binding element declares a global variable that
is visible everywhere (except where it
is shadowed by another
binding). A top-level xsl:param
element
declares a global parameter to the stylesheet; XSLT does not define the
mechanism by which parameters are passed to the stylesheet.
If a stylesheet contains more than one binding for a global variable of a particular name, then the binding with the highest import precedence is used. [ERR043] It is a static error if a stylesheet contains more than one binding of a global variable with the same name and same import precedence.
For a global variable or parameter, the expression or content constructor specifying the variable value is evaluated with a singleton focus based on the document node of the principal source document.
The following example declares a global variable para-font-size
,
which it references in an attribute value template.
<xsl:variable name="para-font-size">12pt</xsl:variable> <xsl:template match="para"> <fo:block font-size="{$para-font-size}"> <xsl:apply-templates/> </fo:block> </xsl:template>
If the expression or content constructor specifying the value of a global variable X references a global variable Y, then the value for Y must be computed before the value of X. If it is impossible to do this for all global variable definitions, then a circularity is said to exist.
For example 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 [7.3 Stylesheet Functions] for
an explanation of the xsl:function
element) also create a circularity:
<xsl:variable name="x" select="f()"/> <xsl:function name="f"> <xsl:result select="$x"/> </xsl:function>
[ERR044] In general, a circularity in a stylesheet is a dynamic error. The processor must signal the 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, a circularity that is signaled as an error by one implementation will not necessarily be signaled by another implementation.
For example, in the following declarations, the function declares a default value for a parameter, but it returns a result that does not require the default value to be evaluated. It is implementation-defined whether the default value is actually evaluated, and it is therefore implementation-defined whether the circularity is signaled as an error:
<xsl:variable name="x" select="f(1)/> <xsl:function name="f"> <xsl:param name="a" select="$x"/> <xsl:result select="$a"/> </xsl:function>
Circularities usually involve global variables or parameters, but they can also exist between key definitions (see [14.3 Keys]), between named attribute sets (see [7.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 a global variable that uses 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 [7.3 Stylesheet Functions]) and named templates (see [7.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.
As well as being allowed as top-level elements, both
xsl:variable
and xsl:param
are also
allowed in content constructors
and within the xsl:function
element
(see [7.3 Stylesheet Functions]. Such a variable
or parameter is known as a local variable or parameter.
A local xsl:variable
is allowed anywhere
within a content constructor that an instruction is allowed.
Within an xsl:function
element, it
is allowed after any xsl:param
elements and before the
xsl:result
element.
In these cases, the
binding is visible for all following siblings and their descendants.
Note that the binding is not visible for the xsl:variable
element itself.
A local xsl:param
is allowed only as a child
at the beginning of an xsl:template
or xsl:function
element. In this
context, the binding is visible for all following siblings and their
descendants. Note that the binding is not visible for the
xsl:param
element itself.
The result of evaluating
a local xsl:variable
or xsl:param
element (that is,
the contribution it makes to the result of the
content constructor it is part of)
is an empty sequence.
A binding shadows another
binding if the binding occurs at a point where the other binding is visible, and
the bindings have the same name.
It is a static error if
a binding established by a local xsl:variable
or
xsl:param
element shadows
another binding established by another local xsl:variable
or xsl:param
. It is not an error if a binding
established by a local xsl:variable
or xsl:param
shadows a global binding. In this case, the global
binding will not be visible in the region of the stylesheet where it
is shadowed by the other binding. Thus, the following is an error:
<xsl:template name="foo"> <xsl:param name="x" select="1"/> <xsl:variable name="x" select="2"/> </xsl:template>
However, the following is allowed:
<xsl:param name="x" select="1"/> <xsl:template name="foo"> <xsl:variable name="x" select="2"/> </xsl:template>
NOTE: Once a variable has been given a value, the value cannot subsequently be changed. XSLT does not provide an equivalent to the assignment operator available in many procedural programming languages. This is because an assignment operator would make it harder to create an implementation that processes a document other than in a batch-like way, starting at the beginning and continuing through to the end.
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 [7.1 Named Templates]), named attribute sets (see [7.2 Named Attribute Sets]) and stylesheet functions (see [7.3 Stylesheet Functions]).
<!-- Category: instruction -->
<xsl:call-template
name = qname>
<!-- Content: xsl:with-param* -->
</xsl:call-template>
Templates can be invoked by name.
An xsl:template
element with a name
attribute specifies a named template.
The value of the name
attribute is a QName, which is expanded as described
in [4.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
element 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 do not affect whether the template
is invoked by an xsl:call-template
element. Similarly,
the name
attribute on an xsl:template
element does not affect whether the template is invoked by an
xsl:apply-templates
element.
[ERR045] It is a static error if a stylesheet contains more than one template with the same name and same import precedence.
The result of evaluating an xsl:call-template
instruction is the node sequence produced by evaluating the content constructor
contained in the associated xsl:template
element.
<xsl:with-param
name = qname
select = expression>
<!-- Content: content-constructor -->
</xsl:with-param>
Issue (add-type-to-with-param): Should we add a type attribute to xsl:with-param, for symmetry with xsl:variable and xsl:param?
Issue (with-param-verbosity): Should we introduce an alternative and less verbose syntax for passing parameters when invoking a template?
Parameters are passed to templates using the
xsl:with-param
element. The required name
attribute specifies the name of the 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 [4.1 Qualified Names].
xsl:with-param
is allowed
within xsl:call-template
,
xsl:apply-templates
and xsl:apply-imports
.
It is a static error if
a single xsl:call-template
,
xsl:apply-templates
or xsl:apply-imports
element contains more than one xsl:with-param
element
with the same name.
The value of the parameter is
specified in the same way as for xsl:variable
and
xsl:param
. The focus used
for computing the value specified by xsl:with-param
element is the same as that used for the
xsl:apply-templates
, xsl:apply-imports
, or
xsl:call-template
element within which it occurs. It is not an error to pass a
parameter x to a template that does not have an
xsl:param
element for x; the parameter is
simply ignored.
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 [7.3 Stylesheet Functions]
<!-- Category: declaration -->
<xsl:attribute-set
name = qname
use-attribute-sets = qnames>
<!-- Content: xsl:attribute* -->
</xsl:attribute-set>
The xsl:attribute-set
element defines a named set of
attributes. The name
attribute specifies the name of the
attribute set. The value of the name
attribute is a QName, which is expanded as described
in [4.1 Qualified Names]. The content of the xsl:attribute-set
element consists of zero or more xsl:attribute
elements
that specify the attributes in the set.
Attribute sets are used by specifying a
use-attribute-sets
attribute on the xsl:element
,
xsl:copy
(see [8.8 Copying Nodes from the Source Tree to the Result Tree]) or
xsl:attribute-set
elements.
The value of the use-attribute-sets
attribute is a whitespace-separated
list of names of attribute sets. Each name is specified as a QName, which is expanded as described
in [4.1 Qualified Names]. Specifying a
use-attribute-sets
attribute is equivalent to adding
xsl:attribute
elements for each of the attributes in each
of the named attribute sets to the beginning of the content of the
element with the use-attribute-sets
attribute, in the
same order in which the names of the attribute sets are specified in
the use-attribute-sets
attribute.
[ERR046] It is a
dynamic error if use
of use-attribute-sets
attributes on
xsl:attribute-set
elements causes an attribute set to
use itself, directly or indirectly.
The processor must signal the error
Attribute sets can also be used by specifying an
xsl:use-attribute-sets
attribute on
a literal result element.
The value of the xsl:use-attribute-sets
attribute is a whitespace-separated list of names of attribute sets.
The xsl:use-attribute-sets
attribute has the same effect
as the use-attribute-sets
attribute on
xsl:element
with the additional rule that attributes
specified on the literal result element itself are treated as if they
were specified by xsl:attribute
elements before any
actual xsl:attribute
elements but after any
xsl:attribute
elements implied by the
xsl:use-attribute-sets
attribute. Thus, in
the node sequence produced by evaluating the content constructor for a literal
result element, attributes from attribute sets named in an
xsl:use-attribute-sets
attribute will appear first, in
the order listed in the attribute; these
will be followed by attributes specified on the
literal result element will be added; finally, any attributes
specified by xsl:attribute
elements will appear. Since
in a sequence of attribute nodes produced by a content constructor,
only the last attribute with a given expanded QName
has any effect (see [4.6 Content Constructors]),
this means that attributes specified
in attribute sets can be overridden by attributes specified on the
literal result element itself.
The content constructor
within each xsl:attribute
element in an
xsl:attribute-set
element is evaluated each time the
attribute set is used; it is evaluated using the same
focus
as is used for evaluating the element bearing
the use-attribute-sets
or
xsl:use-attribute-sets
attribute. However, it is the
position in the stylesheet of the xsl:attribute
element
rather than of the element bearing the use-attribute-sets
or xsl:use-attribute-sets
attribute that determines which
variable bindings are visible (see [6 Variables and Parameters]); thus,
only global variables and parameters are visible.
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>
Multiple definitions of an attribute set with the same expanded-name are merged. An attribute from a definition that has higher import precedence takes precedence over an attribute from a definition that has lower import precedence. [ERR047] It is a dynamic error if there are two attribute sets that have the same expanded-name and equal import precedence and that both contain the same attribute, unless there is a definition of the attribute set with higher import precedence that also contains the attribute. The processor must either signal the error, or must recover by choosing from amongst the definitions that specify the attribute that have the highest import precedence the one that was specified last in declaration order.
Where the attributes in an
attribute set were specified is relevant only in merging the
attributes into the attribute set; it makes no difference when the
attribute set is used. For each
attribute set name occurring in a use-attribute-sets
attribute on
an xsl:attribute-set
element, all definitions of an
attribute set with that name must be merged before the
use-attribute-sets
attribute is replaced by the
equivalent sequence of xsl:attribute
child elements. Any
use-attribute-sets
attribute on an
xsl:attribute-set
element must be replaced by the
equivalent sequence of xsl:attribute
child elements
before that xsl:attribute-set
element is
merged with other xsl:attribute-set
elements with the
same expanded-name. When xsl:attribute-set
elements with
the same expanded-name are merged, any xsl:attribute
child elements added to replace a use-attribute-sets
attribute are treated exactly as if they had originally been specified
in the stylesheet as child elements.
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.
[ERR048] A stylesheet function must have a prefixed name,
to remove any risk of a clash with a system-defined function. 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 theexclude-result-prefixes
attribute on thexsl:stylesheet
element: see [8.1.2 Namespace Nodes for Literal Result Elements].
<!-- Category: declaration -->
<xsl:function
name = qname>
<!-- Content: (xsl:param*, xsl:variable*, xsl:result) -->
</xsl:function>
The xsl:function
element
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 [4.1 Qualified Names]: it must have a prefix.
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
zero or more xsl:variable
elements that can be used
to compute intermediate results, followed by a mandatory
xsl:result
element that defines the value to be
returned by the function.
NOTE: There are no special restrictions on what can appear within anxsl:variable
element. For example, thexsl:variable
element can containxsl:apply-templates
orxsl:call-template
instructions.
If a stylesheet contains declarations of two or more stylesheet functions with the same expanded QName, the one with highest import precedence is used. [ERR049] It is a static error for a stylesheet to contain two or more functions with the same expanded QName and the same import precedence, unless there is another function with the same expanded QName and a higher import precedence.
If a stylesheet function has been defined with a particular expanded QName, then a call on function-available will return true when called with an argument that is a QName that expands to this same expanded QName.
A stylesheet function defined using the xsl:function
element is used in
preference to any function bound using an implemention-defined mechanism. It therefore takes precedence over
any extension function of the same expanded
name that is provided by the implementation.
Issue (user-functions-vs-vendor-functions): Should user-defined functions override vendor-defined functions of the same name, as specified here, or should it be the other way around?
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.
[ERR050] It is an static error if there are
more arguments supplied in the function call than
there are xsl:param
elements in the function definition. It is
not an error if there are fewer arguments supplied: any excess xsl:param
elements will take their default values (see [7.1.1 Passing Parameters to Templates]).
Issue (too-many-params-error): Should it be a static or a dynamic error if too many parameters are supplied? It's described here as a static error, because it can be detected statically, even though this seems inconsistent with the fact that it's a dynamic error if the function doesn't exist, which is done so that function-available() works.
Within the body of the function, the
focus
is the same as the focus
at the point in the XPath expression where the function is
called. This focus is used to evaluate expressions contained in
xsl:param
, xsl:variable
, and xsl:result
elements within the function.
The static context
for these expressions is determined by the position of
the element within the stylesheet. Specifically, this means
that 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.
Any xsl:variable
elements within the function are evaluated
in the normal way: (see [6 Variables and Parameters]).
<xsl:result
select = expression
type = datatype>
<!-- Content: content-constructor -->
</xsl:result>
The xsl:result
element always appears (and only appears) as the last
child of an xsl:function
element. It defines the result that is returned
when the function is evaluated.
The value is established in the same way as for an xsl:variable
element:
if there is a select
attribute, the result is obtained by evaluating
the expression contained in the select
attribute;
if the xsl:result
element is not empty, the result is the document node of
a temporary tree constructed as described in
[6.1 Values of Variables and Parameters] obtained by
evaluating the content constructor and
adding the resulting sequence of nodes to a newly-constructed document node.
If there is no select
attribute and no content constructor, the result
is an empty string; it is an static error if
there is both a select
attribute
and a non-empty content constructor.
The optional type
attribute indicates the
required type of the result.
The value of the type
attribute is a DataType, as defined in [XPath 2.0].
[ERR051] If the type
attribute
is specified, then the calculated result is converted to the required type,
using the rules for the XPath cast
expression. It is a type error
if this conversion fails.
If the type
attribute is omitted, the calculated result is used
as supplied, and no conversion takes place.
Issue (result-type-optional): Should the
type
attribute ofxsl:result
be mandatory?
The following example creates a stylesheet function
named
str:reverse
that reverses the words in a supplied sentence,
and then invokes this function from within a template rule.
<xsl:transform xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:str="http://user.com/namespace" version="2.0" exclude-result-prefixes="str"> <xsl:function name="str:reverse"> <xsl:param name="sentence"/> <xsl:result 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>
The following example illustrates the use of variables 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 [9 Numbering].
<xsl:function name="num:roman"> <xsl:param name="value" type="xs:integer"/> <xsl:variable name="roman-number" type="xs:string"> <xsl:number value="$value" format="i"/> </xsl:variable> <xsl:result select="string($roman-number)" type="xs:string"/> </xsl:function>
This section describes instructions that directly create new nodes. These nodes will typically be assembled to form the result tree.
In a content constructor, an element in the stylesheet that does not belong to the XSLT namespace and that is not an extension instruction (see [16.2 Extension Instructions]) is classified as a literal result element. A literal result element is evaluated to construct a new element node with the same expanded QName. The result of evaluating a literal result element is a node sequence containing one element, the newly-constructed element node.
The content of the element is a content constructor, which is evaluated to return a sequence of nodes that define the attributes and children of the created element node. The children of the newly-constructed element node will be the sequence of elements, text nodes, comment nodes, and processing instructions that results from evaluating this content constructor.
Issue (define-lre-element-type): Should we add an
xsl:type
attribute to literal result elements, to define the type of the newly-constructed element node? Alternatively, shouldxsi:type
be used with this meaning? What are the rules governing its use?
Issue (lre-element-typed-value): Should we provide a way of supplying the typed value of literal result element, as distinct from its string value, perhaps by means of a
xsl:select
attribute on the literal result element?
The created element node will have an attribute corresponding to each attribute node that is present on the element node in the stylesheet tree, other than attributes with names in the XSLT namespace.
The value of an attribute of a literal result element is
interpreted as an attribute
value template: it can therefore contain expressions contained
in curly braces ({}
). The attribute node created in the result
tree will have the same name as the attribute in the source tree, and its
string-value will be the same as the effective value
of the attribute in the source tree.
Additional attributes may be generated by including xsl:attribute
instructions in the content constructor, or by specifying the xsl:use-attribute-sets
attribute on the literal result element itself. The way in which conflicts among these
attributes are resolved is described in [7.2 Named Attribute Sets].
NOTE: Thexml:base
,xml:lang
andxml:space
attributes have two effects in XSLT. They behave as standard XSLT attributes, which means for example that if they appear on a literal result element, they will be copied to the result tree in the same way as any other attribute. In addition, they have their standard meaning as defined in the core XML specifications. Thus, anxml:base
attribute in the stylesheet affects the base URI of the element on which it appears, and anxml:space
attribute affects the interpretation of whitespace nodes within that element. One consequence of this is that these attributes should not be written as attribute value templates: although an XSLT processor will understand this notation, the XML parser will not. None of these attributes will be generated in the result tree unless the stylesheet writes them to the result tree explicitly.
The created element node will also have a copy of the namespace
nodes that were present on the element node in the stylesheet tree
with the exception of any namespace node whose string-value is the
XSLT namespace URI
(http://www.w3.org/1999/XSL/Transform
), a
namespace URI declared as an extension namespace (see [16.2 Extension Instructions]),
or a namespace URI designated as an
excluded namespace.
NOTE: These exceptions only affect namespace nodes copied from the stylesheet when processing a literal result element. They do not affect namespace nodes written to the result tree using instructions such asxsl:copy
andxsl:element
, and they do not affect namespace nodes created under the rules for namespace fixup (see [3.5 Namespace Fixup]).
A namespace URI is designated as an excluded
namespace by using an [xsl:]exclude-result-prefixes
attribute
either on the literal result element itself
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 a whitespace-separated
list of namespace prefixes. The namespace bound to each of the
prefixes is designated as an excluded namespace. It is a
static error if
there is no namespace bound to the prefix on the element bearing the
[xsl:]exclude-result-prefixes
attribute. The default
namespace (as declared by xmlns
) may be designated as an
excluded namespace by including #default
in the list of
namespace prefixes. The designation of a namespace as an excluded
namespace is effective within the subtree of the stylesheet 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.
NOTE: When a stylesheet uses a namespace declaration only for the
purposes of addressing the source tree, specifying the prefix in the
[xsl:]exclude-result-prefixes
attribute will avoid superfluous
namespace declarations in the result tree. The attribute is also useful
to prevent namespaces used solely for the naming of extension functions from
appearing in the result tree.
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.
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. This applies to:
the namespace URI in the expanded-name of a literal result element in the stylesheet
the namespace URI in the expanded-name of an attribute specified on a literal result element in the stylesheet
the string-value of a namespace node on a literal result element in the stylesheet.
<!-- Category: declaration -->
<xsl:namespace-alias
stylesheet-prefix = prefix | "#default"
result-prefix = prefix | "#default" />
A stylesheet can use the
xsl:namespace-alias
element to declare that one namespace
URI is an alias for another namespace URI. When
a literal namespace
URI has been declared to be an alias for another namespace
URI, then the namespace URI in the result tree will be the namespace
URI that the literal namespace URI is an alias for, instead of the
literal namespace URI itself. The xsl:namespace-alias
element declares that the namespace URI bound to the prefix specified
by the stylesheet-prefix
attribute is an alias for the
namespace URI bound to the prefix specified by the
result-prefix
attribute. Thus, the
stylesheet-prefix
attribute specifies the namespace URI
that will appear in the stylesheet, and the
result-prefix
attribute specifies the corresponding
namespace URI that will appear in the result tree. The default
namespace (as declared by xmlns
) may be specified by
using #default
instead of a prefix. If a namespace URI
is declared to be an alias for multiple different namespace URIs, then
the declaration with the highest import precedence is used. [ERR052] It is
a dynamic error if there is more
than one such declaration and different values for namespace-uri
.
The processor must
either signal the error, or
must recover by choosing, from amongst the declarations with the
highest import precedence, the one that occurs last in
declaration order.
When literal result elements are being used to create element, attribute, or namespace nodes that use the XSLT namespace URI, the stylesheet should 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="http://www.w3.org/1999/XSL/TransformAlias"> <xsl:namespace-alias stylesheet-prefix="axsl" result-prefix="xsl"/> <xsl:template match="/"> <axsl:stylesheet> <xsl:apply-templates/> </axsl:stylesheet> </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>
NOTE: It may be necessary also to use aliases for namespaces other than the XSLT namespace URI. For example, 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.
xsl:element
<!-- Category: instruction -->
<xsl:element
name = { qname }
namespace = { uri-reference }
use-attribute-sets = qnames>
<!-- Content: content-constructor -->
</xsl:element>
Issue (define-element-type): Should we add a
type
attribute toxsl:element
, to define the type of the newly-constructed element node? If so, what are the rules governing its use?
Issue (element-typed-value): Should we provide a way of supplying the typed value of a new element node, as distinct from its string value, perhaps by means of a
select
attribute on thexsl:element
instruction?
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
content constructor for the
attributes and children of the created element.
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.
[ERR053] It is an dynamic error if
the effective value is not a QName.
The processor must either signal
the error, or must recover by making the result
of evaluating the xsl:element
element be the sequence of nodes created by evaluating
the content of the xsl:element
element, excluding
any initial attribute nodes.
If the namespace
attribute is
not present then the QName is
expanded into an expanded-name using the namespace declarations in
effect for the xsl:element
element, including any default
namespace declaration.
If the namespace
attribute is present, then it too is
interpreted as an attribute
value template. The effective value
should be a URI reference. It is not an
error if the string is not a syntactically legal URI reference. If
the string is empty, then the expanded-name of the element has a null
namespace URI. Otherwise, the string is used as the namespace URI of
the expanded-name of the element to be created. The local part of the
QName specified by the
name
attribute is used as the local part of the
expanded-name of the element to be created.
Implementations may make use of the prefix of the QName specified in the
name
attribute when selecting the prefix used for
outputting the created element as XML; however, they are not required
to do so.
For the effect of the use-attribute-sets
attribute, see [7.2 Named Attribute Sets]
xsl:attribute
<!-- Category: instruction -->
<xsl:attribute
name = { qname }
namespace = { uri-reference }>
<!-- Content: content-constructor -->
</xsl:attribute>
Issue (define-attribute-type): Should we add a
type
attribute toxsl:attribute
, to define the type of the newly-constructed attribute node? If so, what are the rules governing its use?
Issue (attribute-typed-value): Should we provide a way of supplying the typed value of a new attribute node, as distinct from its string value, perhaps by means of a
select
attribute on thexsl:attribute
element?
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
. The expanded QName of the
attribute to be created is specified by a required name
attribute and an optional namespace
attribute.
The result of evaluating an xsl:attribute
instruction
is the newly-constructed attribute node.
The content of the
xsl:attribute
element is a content constructor for the value of the
created attribute.
The name
attribute is interpreted as an attribute value template.
[ERR054] It is a dynamic error if
the effective value
is not a QName or is the string
xmlns
. The processor must either signal the error,
or must recover by not adding the attribute
to the result tree.
If the namespace
attribute is not
present, then the QName is
expanded into an expanded-name using the namespace declarations in
effect for the xsl:attribute
element, not
including any default namespace declaration.
If the namespace
attribute is present, then it too is
interpreted as an attribute
value template. The effective value
should be a URI reference. It is not an error if the string is not
a syntactically legal URI reference. If the string is empty, then the
expanded-name of the attribute has a null namespace URI. Otherwise,
the string is used as the namespace URI of the expanded-name of the
attribute to be created. The local part of the QName specified by the
name
attribute is used as the local part of the
expanded-name of the attribute to be created.
Implementations may make use of the prefix of the
QName specified in the
name
attribute when selecting the prefix used for
outputting the created attribute as XML; however, they are not
required to do so and, if the prefix is xmlns
, they must
not do so. Thus, although it is not an error to do:
<xsl:attribute name="xmlns:xsl" namespace="whatever">http://www.w3.org/1999/XSL/Transform</xsl:attribute>
it will not result in a namespace declaration being output.
As described in [4.6 Content Constructors], any attribute nodes must appear in the result of evaluating a content constructor before any element, text, comment, or processing instruction nodes, but after any namespace nodes. Where the result of the content constructor contains two or more attribute nodes with the same expanded QName, the one that comes last is the only one that takes effect. When evaluating the content of a node other than an element, returning a node sequence that includes attribute nodes is a dynamic error; the recovery action (if any) depends on the instruction that makes use of the constructed node sequence.
NOTE: When anxsl:attribute
element contains a text node with a newline, then the XML output must contain a character reference. For example,<xsl:attribute name="a">x y</xsl:attribute>will result in the outputa="x
y"(or with any equivalent character reference). The XML output cannot bea="x y"This is because XML 1.0 requires newline characters in attribute values to be normalized into spaces but requires character references to newline characters not to be normalized. The attribute values in the data model represent the attribute value after normalization. If a newline occurring in an attribute value in the tree were output as a newline character rather than as character reference, then the attribute value in the tree created by reparsing the XML would contain a space not a newline, which would mean that the tree had not been output correctly.
A content constructor can also contain text nodes. Each text node in a content constructor remaining after whitespace has been stripped as specified in [3.4 Whitespace Stripping] will construct a text node with the same string-value. The resulting text node is added to the result of the containing content constructor. When the resulting content is added to a result tree, adjacent text nodes in the result tree are automatically merged.
Note that 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 externalized as an XML document
(unless output escaping is disabled as described in [18.5 Disabling Output Escaping]).
xsl:text
<!-- Category: instruction -->
<xsl:text
disable-output-escaping = "yes" | "no">
<!-- Content: content-constructor -->
</xsl:text>
The xsl:text
element is evaluated to contruct a
new text node. The content of the
xsl:text
element is a
content constructor for the string-value of
the text node.
The result of evaluating the xsl:text
instruction is
a single node, the newly-constructed text node.
Text nodes that are immediate children of the xsl:text
instruction
will not be stripped from the stylesheet tree, even if they consist entirely of whitespace
(see [3.4 Whitespace Stripping]).
For the effect of the disable-output-escaping
attribute,
see [18.5 Disabling Output Escaping]
NOTE: It is not always necessary to use thexsl: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 content constructor, while computed text can be output using thexsl:value-of
instruction. The principal reason for usingxsl:text
is that it offers improved control over whitespace handling.
<!-- Category: instruction -->
<xsl:processing-instruction
name = { ncname }>
<!-- Content: content-constructor -->
</xsl:processing-instruction>
The xsl:processing-instruction
element is evaluated
to create a processing instruction node. The content of the
xsl:processing-instruction
element is a
content constructor for the
string-value of the 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.
Except in error situations, the result of evaluating the
xsl:processing-instruction
instruction is
a single node, the newly-constructed processing instruction.
For example, this
<xsl:processing-instruction name="xml-stylesheet">href="book.css" type="text/css"</xsl:processing-instruction>
would create the processing instruction
<?xml-stylesheet href="book.css" type="text/css"?>
[ERR055] It is a dynamic error if the
effective value of the
name
attribute is not both an NCName and a PITarget.
The processor must either signal
the error, or must recover by
returning an empty sequence.
NOTE: This means thatxsl:processing-instruction
cannot be used to output an XML declaration. Thexsl:output
declaration should be used to control this instead (see [18 Serialization]).
[ERR056] It is a dynamic error if
the result of evaluating the content of the
xsl:processing-instruction
contains the string
?>
. The processor must either signal the error, or
must recover by inserting a space after any
occurrence of ?
that is followed by a >
<!-- Category: instruction -->
<xsl:namespace
name = { ncname }>
<!-- Content: content-constructor -->
</xsl:namespace>
The xsl:namespace
element is evaluated
to create a namespace node. The content of the
xsl:namespace
element is a
content constructor for the
string-value of the namespace node (that is, the namespace URI). 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.
Except in error situations, the result of evaluating the
xsl:namespace
instruction is
a single node, the newly-constructed namespace node.
Note the restrictions described in [4.6 Content Constructors]
for the position of a namespace node relative to other nodes in the node sequence
returned by a content constructor.
For example, this
<xsl:namespace name="xsd">http://www.w3.org/2001/XMLSchema</xsl:namespace>
would typically cause the output document to contain the namespace declaration:
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
[ERR057] It is a dynamic error if the
effective value of the
name
attribute
is neither an empty string nor an NCName.
The processor must either signal the error,
or must recover by returning an empty sequence.
[ERR058] It is an dynamic error if
evaluating the content of
xsl:namespace
results in an empty string.
The processor must either signal the error,
or must recover by returning an empty sequence.
NOTE: It is rarely necessary to usexsl: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 wherexsl: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.
Ed. Note: We need to add text explaining how the new namespace node is effectively merged with other matching namespace nodes in the same document, once the data model is finalized.
<!-- Category: instruction -->
<xsl:comment>
<!-- Content: content-constructor -->
</xsl:comment>
The xsl:comment
element is evaluated to contruct a
new comment node. The content of the
xsl:comment
element is a content constructor for the string-value of
the comment node.
The result of evaluating the xsl:comment
instruction is
a single node, the newly-constructed comment node.
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!-->
[ERR059] It is a dynamic error if
the result of evaluating the content of the
xsl:comment
contains the string --
or ends
with -
. The processor must either signal the error,
or must recover by inserting a space after
any occurrence of -
that is followed by another
-
or that ends the comment.
<!-- Category: instruction -->
<xsl:copy
use-attribute-sets = qnames>
<!-- Content: content-constructor -->
</xsl:copy>
The xsl:copy
instruction provides an easy way of copying
the context item. If the
context item is a node,
and is not a document 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.
The namespace nodes of the
context node are automatically copied as well, but the attributes and
children of the node are not automatically copied. The content of the
xsl:copy
element is a
content constructor for the
attributes and children of the created node;
the content constructor is evaluated only for
nodes of types that can have children (that is, document nodes and element nodes).
The xsl:copy
element may have a
use-attribute-sets
attribute (see [7.2 Named Attribute Sets]). This is used only when copying element
nodes.
The document node is treated specially because the document node of a
result tree is created implicitly. When the context item is a document
node, xsl:copy
will not create a document node, but will just
evaluate the content constructor, and return the
resulting node sequence as the result of the xsl:copy
instruction.
For example, 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>
[ERR060] When the context item is an attribute node, then if it would be a
dynamic error
to use xsl:attribute
to create an attribute with the same
name as the context item, then it is also a
dynamic error to use
xsl:copy
(see [8.3 Creating Attribute Nodes using xsl:attribute
]).
The processor must either signal the error, or must recover by
returning an empty sequence.
When the context item is a namespace node,
then xsl:copy
constructs a new namespace node as a copy
of the context node (that is, a namespace node with the same expanded QName
and string-value. As described
in detail in [4.6 Content Constructors], it will generally be an error
if this namespace node is preceded in the constructed node sequence by
any node other than another namespace node, or if the namespace node cannot
be added to a containing element without a conflict arising.
When the context item is not a node, the effect of the
xsl:copy
instruction is the same as evaluating the instruction
<xsl:value-of select="."/>
.
The following example shows how xml:lang
attributes
can be easily copied through from source to result. If a stylesheet
defines the following named template:
<xsl:template name="apply-templates-copy-lang"> <xsl:for-each select="@xml:lang"> <xsl:copy/> </xsl:for-each> <xsl:apply-templates/> </xsl:template>
then it can simply do
<xsl:call-template name="apply-templates-copy-lang"/>
instead of
<xsl:apply-templates/>
when it wants to copy the xml:lang
attribute.
Ed. Note: This is a poor example because it would be easier to write <xsl:copy-of select="@xml:lang"/>
<!-- Category: instruction -->
<xsl:copy-of
select = expression
separator = { string } />
The xsl:copy-of
instruction can be used to
construct a copy of a sequence of nodes, with each new node containing
copies of all the children, attributes, and namespace of the original node,
recursively. The result of evaluating the instruction is a sequence
of new nodes corresponding one-to-one with the supplied node sequence,
and retaining its order. (This correspondence does not apply when copying
a document node: see below).
The xsl:copy-of
instruction can also be used to
copy simple values.
The mandatory select
attribute contains an expression.
The required type
of this expression is sequence
, which means that any sequence can be supplied.
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 copies of the attribute nodes, namespace nodes and children of the element node.
If the item is a document node, the instruction copies the children of the document node (each according to the rules for its own node type) and adds the copies, in order, to the result sequence.
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 [8.8 Copying Nodes from the Source Tree to the Result Tree]).
If the item is a
simple value, the result is converted to a string, a new text node is constructed with
this string as its string-value, and the new text node is
appended to the result sequence, as with xsl:value-of
.
If the separator
attribute is present,
then its effective value (a string)
is inserted as a text node into the result sequence
after the result of processing each item in the input sequence, other than the last. If the
separator
attribute is absent, the effect is the same as supplying
an empty string.
For example, the instruction:
<x><xsl:copy-of select="(1,2,3,4)" separator="|"/></x>
produces the output:
<x>1|2|3|4</x>
xsl:value-of
Within a content constructor,
the xsl:value-of
instruction can be
used to compute generated text, for example by extracting text from
the source tree or by inserting the value of a variable. The
xsl:value-of
instruction computes this text using an expression that is specified as the
value of the select
attribute.
NOTE: An alternative way of computing a string value,
applicable only when the resulting
text is to be used within a generated attribute node, is to use an
attribute value template,
enclosing the expression in curly braces ({}
) within an
attribute of a literal result element.
<!-- Category: instruction -->
<xsl:value-of
select = expression
separator = { string }
disable-output-escaping = "yes" | "no" />
The xsl:value-of
instruction is evaluated to construct a
new text node; the result of the instruction is the newly-constructed text node.
But if the rules below produce a text node whose string
value is the empty string, the result of the instruction is an empty sequence.
The required select
attribute is an expression.
The required type
of this expression is sequence
, which means that the result of the
expression may be any sequence.
If the sequence is empty, no text node will be created.
If the sequence contains a single item, the resulting text node will have
a string-value that is the same as the string-value of this item.
If the sequence contains more than one item, the effect depends on whether
the separator
attribute is present.
If the separator
attribute is present,
then the string-value of the newly constructed text node will be the
concatenation of the string-values of the items in the sequence that
results from evaluating the select
attribute, with each
of these string-values except the last being followed by the
string that is the effective value of
the separator
attribute. If the
separator
attribute is absent, then (for backwards compatibility with XSLT 1.0)
all items in the input sequence other than the first are ignored.
If the effective value of the separator
attribute is an empty string, then
all items in the input sequence are processed and the results are concatenated
with no separator.
For example, the instruction:
<x><xsl:value-of select="(1,2,3,4)" separator="|"/></x>
produces the output:
<x>1|2|3|4</x>
NOTE: Theseparator
attribute is used only when theselect
expression produces a sequence of items. It is not used when theselect
expression returns a single node whose typed-value is a sequence, for example a node of type IDREFS. The string-value of such a node is obtained in the normal way, as if by calling the string function.
NOTE: The xsl:copy-of
element can be used to copy
a sequence of nodes
to the result tree without converting to a string. See [8.8.2 Deep Copy].
For example, the following creates an HTML paragraph from a
person
element with given-name
and
family-name
attributes. The paragraph will contain the value
of the given-name
attribute of the context node followed
by a space and the value of the family-name
attribute of the
context node.
<xsl:template match="person"> <p> <xsl:value-of select="@given-name"/> <xsl:text> </xsl:text> <xsl:value-of select="@family-name"/> </p> </xsl:template>
For another example, the following creates an HTML paragraph from a
person
element with given-name
and
family-name
children elements. The paragraph will
contain the string-value of the first given-name
child
element of the context node followed by a space and the string-value
of the first family-name
child element of the context
node.
<xsl:template match="person"> <p> <xsl:value-of select="given-name"/> <xsl:text> </xsl:text> <xsl:value-of select="family-name"/> </p> </xsl:template>
The following precedes each procedure
element with a
paragraph containing the security level of the procedure. It assumes
that the security level that applies to a procedure is determined by a
security
attribute on the procedure element or on an
ancestor element of the procedure. It also assumes that if more than
one such element has a security
attribute then the
security level is determined by the element that is closest to the
procedure.
<xsl:template match="procedure"> <fo:block> <xsl:value-of select="ancestor-or-self::*[@security][1]/@security"/> </fo:block> <xsl:apply-templates/> </xsl:template>
For the effect of the disable-output-escaping
attribute,
see [18.5 Disabling Output Escaping]
<!-- Category: instruction -->
<xsl:number
level = "single" | "multiple" | "any"
count = pattern
from = pattern
value = number-expression
format = { string }
lang = { nmtoken }
letter-value = { "alphabetic" | "traditional" }
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.
The
xsl:number
instruction performs
two tasks: firstly, determining a place marker to be formatted (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 tree.
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 the context node in the source
tree.
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 [14.4 Number Formatting].
The place marker
to be formatted may be
specified by an expression. The value
attribute contains
the expression.
The required type of the expression
is xsd:integer*
, that is, a sequence of integers. The expression
is evaluated, to produce a sequence, and each item
in this sequence is converted to an integer using the rules
of the XPath cast
construct.
[ERR061] It is a dynamic error if any item in the sequence cannot be converted to an integer, or if the resulting integer is less than 1 (one). The processor must either signal the error, or must recover by converting that member to a string as if by a call to the string function and inserting the resulting string into the formatted result string in its proper position.
Otherwise, the sequence is
formatted as a string using the effective values
of the attributes specified in [9.3 Number to String Conversion Attributes]; each of these attributes is
interpreted as an attribute
value template. After conversion, the xsl:number
element constructs a new text node containing the resulting string, and returns this node.
The following example numbers a sorted list:
<xsl:template match="items"> <xsl:for-each select="item"> <xsl:sort select="."/> <p> <xsl:number value="position()" format="1. "/> <xsl:value-of select="."/> </p> </xsl:for-each> </xsl:template>
If no value
attribute is specified, then the
xsl:number
instruction returns a new text
node containing a formatted
place marker that is based on the position
of the context node within its tree. Without
loss of generality, the tree containing the context node is referred to in this section
as the source tree.
[ERR062] It is a
dynamic error if the
xsl:number
instruction is evaluated, with no value
attribute,
when the context item is not a node.
The processor must either signal the error,
or must recover by returning an empty sequence.
The following attributes control how the context node is to be numbered:
The level
attribute specifies what levels of the
source tree should be considered; it has the values
single
, multiple
or any
. The
default is single
.
The count
attribute is
a pattern that specifies
which nodes should 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 type as the context node and, if
the context node has an expanded-name, with the same expanded-name as
the context node.
The from
attribute is
a pattern that specifies
where counting starts.
In addition, the attributes specified in [9.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 the given
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 the given
node matches the pattern given in the from
attribute (this function
is not used if the from
attribute is omitted).
When level="single"
:
Let $A
be the node sequence selected by the expression
ancestor-or-self::node()[matches-count(.)][last()]
If the from
pattern is specified, let
$F
be the node sequence selected by the expression
ancestor::node()[matches-from(.)][last()]
otherwise let $F
be the root node, /
Let $AF
be the value of
$A intersect ($F/descendant::node())
If $AF
is empty, return the empty sequence, ()
Otherwise return the value of
1 + count($AF/preceding-sibling::node()[matches-count()])
When level="multiple"
:
Let $A
be the node sequence selected by the expression
ancestor-or-self::node()[matches-count(.)]
If the from
pattern is specified, let
$F
be the node sequence selected by the expression
ancestor::node()[matches-from(.)][last()]
otherwise let $F
be the root node, /
Let $AF
be the value of
$A intersect ($F/descendant::node())
Return the result of the expression
for $af in $AF return 1+count($af/preceding-sibling::node()[matches-count(.)])
When level="any"
:
Let $A
be the node sequence selected by the expression
(preceding::node()|ancestor-or-self::node())[matches-count(.)]
If the from
pattern is specified, let
$F
be the node sequence selected by the expression
(preceding::node()|ancestor::node())[matches-from(.)][last()]
and let $AF
be
the node sequence $A[. >> $F]
. Otherwise, let $AF
be the
sequence $A
.
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 [9.3 Number to String Conversion Attributes]; each of these attributes is interpreted as an attribute value template. After conversion, the resulting string is inserted in the result tree.
For example, 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.
<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 example numbers notes sequentially within a chapter:
<xsl:template match="note"> <fo:block> <xsl:number level="any" from="chapter" format="(1) "/> <xsl:apply-templates/> </fo:block> </xsl:template>
The following example will number H4
elements in HTML
with a three-part label:
<xsl:template match="H4"> <fo:block> <xsl:number level="any" from="H1" count="H2"/> <xsl:text>.</xsl:text> <xsl:number level="any" from="H2" count="H3"/> <xsl:text>.</xsl:text> <xsl:number level="any" from="H3" count="H4"/> <xsl:text> </xsl:text> <xsl:apply-templates/> </fo:block> </xsl:template>
The following attributes are used to control conversion of a sequence of numbers into a string. The numbers are integers greater than 0. The attributes are all optional.
The main attribute is format
. The default value for
the format
attribute is 1
. The
format
attribute is split into a sequence of tokens where
each token is a maximal sequence of alphanumeric characters or a
maximal sequence of non-alphanumeric characters. Alphanumeric means
any character that has a Unicode category of Nd, Nl, No, Lu, Ll, Lt,
Lm or Lo. The alphanumeric tokens (format tokens) specify the format
to be used for each number in the sequence. If the first token is a
non-alphanumeric token, then the constructed string will start with
that token; if the last token is non-alphanumeric token, then the
constructed string will end with that token. Non-alphanumeric tokens
that occur between two format tokens are separator tokens that are
used to join numbers in the sequence. The nth format token
will be used to format the nth number in the sequence. If
there are more numbers than format tokens, then the last format token
will be used to format remaining numbers. If there are no format
tokens, then a format token of 1
is used to format all
numbers. The format token specifies the string to be used to
represent the number 1. Each number after the first will be separated
from the preceding number by the separator token preceding the format
token used to format that number, or, if there are no separator
tokens, then by .
(a period character).
Format tokens are a superset of the allowed values for the
type
attribute for the OL
element in HTML
4.0 and 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. Thus, a format token 1
generates the
sequence 1 2 ... 10 11 12 ...
, and a format token
01
generates the sequence 01 02 ... 09 10 11 12
... 99 100 101
.
A format token 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 ...
.
Any other format token indicates a numbering sequence that
starts with that token. If an implementation does not support a
numbering sequence that starts with that token, it must use a format
token of 1
.
For all format tokens other than the first kind above
(one that consists of decimal digits), the implementation may impose an upper
bound on the range of numbers that can be formatted using this format
token. For the numbering sequences described above, this upper bound must not be
less than 1000 (one thousand). Numbers that exceed the upper bound
must be formatted using the format token 1
.
When numbering with an alphabetic sequence, the lang
attribute specifies which language's alphabet is to be used; it has
the same range of values as xml:lang
[XML];
if no lang
value is specified, the language should be
determined from the system environment. Implementations should document
for which languages they support numbering.
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: It is possible for two conforming implementations not to convert a number to exactly the same string. Some implementations might not support some languages. Furthermore, there may be variations possible in the way conversions are performed for any particular language that are not specifiable by the attributes onxsl:number
. Future versions of XSLT may provide additional attributes to provide control over these variations. Implementations may also use implementation-specific namespaced attributes onxsl:number
for this.
The grouping-separator
attribute gives the separator
used as a grouping (e.g. 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
. If only one
of the grouping-separator
and grouping-size
attributes is specified, then it is ignored.
Here are some examples of conversion specifications:
format="ア"
specifies Katakana
numbering
format="イ"
specifies Katakana
numbering in the "iroha" order
format="๑"
specifies numbering with
Thai digits
format="א" letter-value="traditional"
specifies "traditional" Hebrew numbering
format="ა" letter-value="traditional"
specifies Georgian numbering
format="α" letter-value="traditional"
specifies "classical" Greek numbering
format="а" letter-value="traditional"
specifies Old Slavic numbering
<!-- Category: instruction -->
<xsl:for-each
select = sequence-expression>
<!-- Content: (xsl:sort*, content-constructor) -->
</xsl:for-each>
The xsl:for-each
instruction
processes each item in a sequence of items, evaluating the
content constructor
within the xsl:for-each
instruction once for each item
in that sequence.
The select
attribute is required, and
the expression must evaluate to a sequence,
called the input sequence. If there is an xsl:sort
element present (see [12 Sorting]) the input sequence
is sorted to produce a sorted sequence. Otherwise, the sorted sequence
is the same as the input sequence.
The xsl:for-each
instruction contains a
content constructor, which is
evaluated once for each item in the sorted sequence.
The content constructor
is evaluated with the focus set as follows:
xsl:for-each
instruction. For each item in the input sequence, evaluating the
content constructor produces a sequence
of output nodes; these output sequences are concatenated in the same order as the
sorted sequence. The result of the xsl:for-each
instruction
is the concatenated sequence of output nodes.
NOTE: With XSLT 1.0, the selected nodes were processed in document order. With XSLT 2.0, XPath expressions that would have been valid under XPath 1.0 (such as path expressions and union expressions) will return a sequence of nodes that is already in document order, so backwards compatibility is maintained.
For example, given an XML document with this structure
<customers> <customer> <name>...</name> <order>...</order> <order>...</order> </customer> <customer> <name>...</name> <order>...</order> <order>...</order> </customer> </customers>
the following would create an HTML document containing a table with
a row for each customer
element
<xsl:template match="/"> <html> <head> <title>Customers</title> </head> <body> <table> <tbody> <xsl:for-each select="customers/customer"> <tr> <th> <xsl:apply-templates select="name"/> </th> <xsl:for-each select="order"> <td> <xsl:apply-templates/> </td> </xsl:for-each> </tr> </xsl:for-each> </tbody> </table> </body> </html> </xsl:template>
There are two instructions in XSLT that support conditional
processing in a template: xsl:if
and
xsl:choose
. The xsl:if
instruction provides
simple if-then conditionality; the xsl:choose
instruction
supports selection of one choice when there are several
possibilities.
xsl:if
<!-- Category: instruction -->
<xsl:if
test = expression>
<!-- Content: content-constructor -->
</xsl:if>
The xsl:if
element has a test
attribute,
which specifies an expression.
The content is a
content constructor.
The required type of the expression
in the test
attribute is xsd:boolean
. Type conversion
follows the XPath rules for other boolean contexts, which means that
a value of ()
(the empty sequence) is treated as false.
If the result of evaluating the expression is true, then
the content constructor is evaluated,
and the resulting node sequence is returned as the result of
the xsl:if
instruction; otherwise, an empty sequence is returned.
In the following example, the names in a group of names are formatted as a comma separated list:
<xsl:template match="namelist/name"> <xsl:apply-templates/> <xsl:if test="not(position()=last())">, </xsl:if> </xsl:template>
The following colors every other table row yellow:
<xsl:template match="item"> <tr> <xsl:if test="position() mod 2 = 0"> <xsl:attribute name="bgcolor">yellow</xsl:attribute> </xsl:if> <xsl:apply-templates/> </tr> </xsl:template>
xsl:choose
<!-- Category: instruction -->
<xsl:choose>
<!-- Content: (xsl:when+, xsl:otherwise?) -->
</xsl:choose>
<xsl:when
test = expression>
<!-- Content: content-constructor -->
</xsl:when>
<xsl:otherwise>
<!-- Content: content-constructor -->
</xsl:otherwise>
The xsl:choose
element selects one among a number of
possible alternatives. It consists of a sequence of
xsl:when
elements followed by an optional
xsl:otherwise
element. Each xsl:when
element has a single attribute, test
, which specifies an
expression. The content of the
xsl:when
and xsl:otherwise
elements is a
content constructor.
The required type of the expression
in the test
attribute of the
xsl:when
element is xsd:boolean
. Type conversion
follows the XPath rules for a choice context, which means that
a value of ()
(the empty sequence) is treated as false.
When an xsl:choose
element is processed, each
of the xsl:when
elements is tested in turn,
until one of the expressions evaluates to true. The content
of the first, and only the first, xsl:when
element whose
test is true is evaluated,
and the resulting node sequence is returned as the result of the
xsl:choose
instruction.
If no xsl:when
condition is true,
the content of the xsl:otherwise
element is
evaluated, and the resulting node sequence is returned as the result
of the xsl:choose
instruction.
If no xsl:when
element is true, and no
xsl:otherwise
element is present, the result of the
xsl:choose
instruction
is an empty sequence.
The content constructors for xsl:when
and xsl:otherwise
instructions other than the selected one are not evaluated, and the select
expressions
for xsl:when
instructions after the selected one are not evaluated.
The following example enumerates items in an ordered list using arabic numerals, letters, or roman numerals depending on the depth to which the ordered lists are nested.
<xsl:template match="orderedlist/listitem"> <fo:list-item indent-start='2pi'> <fo:list-item-label> <xsl:variable name="level" select="count(ancestor::orderedlist) mod 3"/> <xsl:choose> <xsl:when test='$level=1'> <xsl:number format="i"/> </xsl:when> <xsl:when test='$level=2'> <xsl:number format="a"/> </xsl:when> <xsl:otherwise> <xsl:number format="1"/> </xsl:otherwise> </xsl:choose> <xsl:text>. </xsl:text> </fo:list-item-label> <fo:list-item-body> <xsl:apply-templates/> </fo:list-item-body> </fo:list-item> </xsl:template>
A
sort 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.
Within a
sort specification, each
xsl:sort
element provides one sort key definition.
The first xsl:sort
element specifies the primary part of the sort specification, the second xsl:sort
element specifies the secondary part of the sort specification and so on.
A sort specification may occur as the content of
an xsl:sort-key
declaration at the top level of a stylesheet module, or it may occur
immediately within an xsl:apply-templates
,
xsl:for-each
, or xsl:for-each-group
element.
[ERR063] When used within xsl:for-each
or
xsl:for-each-group
, xsl:sort
elements must occur before any other children.
xsl:sort
Element<xsl:sort
select = expression
lang = { nmtoken }
data-type = { "text" | "number" | qname-but-not-ncname }
order = { "ascending" | "descending" }
collation = { qname }
case-order = { "upper-first" | "lower-first" } />
Those attributes of the xsl:sort
elements whose values
are attribute value templates
are evaluated using the outer focus.
If the element that contains the xsl:sort
elements is an xsl:sort-key
declaration, then the outer focus is a singleton
focus based on the document node of the principal
source document. Otherwise, the outer focus is the focus used to evaluate the
select
attribute of the containing instruction
(for example, xsl:for-each
or xsl:apply-templates
).
The sequence to be sorted
is referred to as the initial sequence.
The sequence after sorting
as defined by the xsl:sort
elements
is referred to as the sorted sequence.
For each item in the initial sequence,
a value is computed
for each sort key definition
within the sort specification.
The value computed for an item by using the Nth sort key definition
is referred to as the Nth sort key of that item.
Specifically, the
Nth sort key is computed by evaluating the expression contained in the
select
attribute of the Nth xsl:sort
element,
if there is such an attribute.
If there is no select
attribute,
the sort key is computed by taking the actual item
in the initial sequence if it is a simple value, or the typed-value of this
item if it is a node.
The expression in the select
attribute of the xsl:sort
element
is evaluated with the focus set as follows:
If the xsl:sort
element has a data-type
attribute, then the sort key is converted to the target data type before comparing
it with other items.
[ERR064] The target data type for each xsl:sort
element is determined
by the effective value of its
data-type
attribute. If
this has the value text
, the target data type is xsd:string
.
If it has the value number
, the target data type is xsd:double
.
Otherwise, the target data type must be the name of a primitive data type in XML Schema
(see [XML Schema]).
It is a dynamic error if any other value is
supplied. The processor must either signal the error, or must recover
by continuing as if the data-type
attribute were not specified.
Each sort key is converted to the target data type using the rules for the
XPath cast
expression. [ERR065] It
is a dynamic error if any value obtained by
evaluating the select
attribute of an xsl:sort
element
cannot be converted to the target data type.
The processor must either signal the error,
or must recover by treating the value as being less than any value for which conversion succeeds, but equal
to any other value for which conversion fails. This means that values that cannot
be converted to the target data type will appear together at the start of the sorted
sequence if order is ascending, or at the end if order is descending.
If there is no data-type
attribute, then the computed sort keys are not converted
before comparison, except in the case where the data type of a computed sort key is a complex
type, in which case it is converted to a string as if by the XPath string function.
The items in the initial sequence
are ordered into a sorted sequence by comparing their
sort keys. The relative position of two items A and B in the sorted
sequence is determined as follows. The first sort key of A is compared
with the first sort key of B, according to the rules of the first
sort key definition. 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 definition specifies
descending
, in which case B will precede A
in the sorted sequence. If, however, the relevant sort keys compare equal,
then the second sort key of A is compared
with the second sort key of B, according to the rules of the second sort key definition.
This continues until two sort keys are found that compare unequal. If all
the sort keys compare equal, then A will precede B in the
sorted sequence if
A preceded B in the initial sequence,
and vice versa.
In general, comparison of two values is performed according to the rules of the
XPath lt
operator. However, special rules
apply to the string data type,
as described below. [ERR066] It is a
dynamic error if, for any
sort key definition,
the set of sort keys evaluated for all the items in the
initial sequence, after any type conversion requested,
contains a pair of values for which the result of the
XPath lt
operator is an error or an empty sequence.
The processor must either signal the error,
or must recover by assigning an arbitrary ordering to any such
pair of values.
[ERR067] It is a dynamic error if
the effective value
of the data-type
attribute of the xsl:sort
element is
a data type for which no ordering
relation is defined, other than the values xsd:string
or
text
, which are synonymous.
The processor must signal the error, or must recover by
continuing as if the data-type
attribute were omitted.
For comparison of string values, special rules apply. If the xsl:sort
element has a
collation
attribute, then the strings are compared according to the rules for the named
collating sequence: that is, they are compared using the XPath
function call xf:compare($a, $b, $collation)
.
The lang
and case-order
attributes are
ignored if a collation
attribute
is present. But in the absence of a collation
attribute, these attributes provide input to an
implementation-defined algorithm to identify a suitable collation:
lang
attribute indicates that a collation
suitable for a particular natural language is required. The
effective value of
the attribute must be a value that would be valid for the
xml:lang
attribute (see [XML]).case-order
attribute indicates whether
the desired collation should sort upper-case letters before
lower case or vice versa. The
effective value of
the attribute must be either lower-first
(indicating
that lower-case letters precede upper-case letters in the collating
sequence) or upper-first
(indicating that upper-case
letters precede lower-case).In the absence of any of these attributes, the default collation is used.
NOTE: It is possible for two conforming implementations not to sort exactly the same. Some implementations might not support some languages. Furthermore, there may be variations possible in the sorting of any particular language that are not specified by the attributes onxsl:sort
, for example, whether Hiragana or Katakana is sorted first in Japanese. Future versions of XSLT may provide additional attributes to provide control over these variations. Implementations may also use implementation-specific namespaced attributes onxsl:sort
for this.
NOTE: It is recommended that implementors consult [UNICODE TR10] for information on internationalized sorting.
When used within xsl:for-each
or
xsl:apply-templates
, a
sort specification indicates that
the sequence of items selected by that instruction should be processed
in sorted order, not in the order of the supplied sequence.
For example, suppose an employee database has the form
<employees> <employee> <name> <given>James</given> <family>Clark</family> </name> ... </employee> </employees>
Then a list of employees sorted by name could be generated using:
<xsl:template match="employees"> <ul> <xsl:apply-templates select="employee"> <xsl:sort select="name/family"/> <xsl:sort select="name/given"/> </xsl:apply-templates> </ul> </xsl:template> <xsl:template match="employee"> <li> <xsl:value-of select="name/given"/> <xsl:text> </xsl:text> <xsl:value-of select="name/family"/> </li> </xsl:template>
When used within xsl:for-each-group
, a
sort specification
indicates the order in which the groups should be processed.
For the effect of xsl:for-each-group
, see
[13 Grouping]
<!-- Category: declaration -->
<xsl:sort-key
name = qname>
<!-- Content: (xsl:sort+) -->
</xsl:sort-key>
Issue (converge-with-sortby): While the facility for named sort keys meets the requirement to be able to sort arbitrary sequences, the XSL Working Group would prefer to find a way of converging this capability with the
sortby
syntax proposed for use in XQuery.
A
named sort specification is defined
by an xsl:sort-key
declaration. This is a top-level
element in the stylesheet. The name
attribute is mandatory.
The value of the name
attribute is a QName, which is expanded as described
in [4.1 Qualified Names]: it need not have a prefix.
The content of the xsl:sort-key
element consists of one or more xsl:sort
elements
that define the components of the
sort specification,
in major to minor order.
If a stylesheet contains declarations of two or more named sort specifications with the same expanded QName, the one with highest import precedence is used. [ERR068] It is a static error for a stylesheet to contain two or more named sort specifications with the same expanded QName and the same import precedence, unless there is another named sort specification with the same expanded QName and a higher import precedence.
Function: sequence sort(string, sequence)
In an XPath expression used within an XSLT stylesheet, an additional function sort is available, which sorts a sequence using a named sort specification.
The first argument is evaluated as a string; its value must be a QName whose expanded QName is the same as the name of a named sort specification defined in the stylesheet. [ERR069] It is a dynamic error if the first argument of the sort function does not match the name of any named sort specification in the stylesheet. The processor must signal the error.
The second argument is evaluated as a sequence. This sequence forms the initial sequence for the sort. The sequence is sorted according to the rules for the named sort specification, and the result of the function call is the resulting sorted sequence.
The facilities described in this section are designed to allow users to group nodes in a document based on common string values, common names, or commmon values for any other expression. Since grouping identifies items with duplicate values, the same facilities also allow selection of the distinct values in a sequence of items, that is, the elimination of duplicates.
In addition these facilities allow grouping based on sequential position, e.g.
selecting groups of adjacent PARA
elements. The facilities also provide an easy
way to do fixed-size grouping, for example identifying groups of three adjacent nodes,
which is useful when arranging data in multiple columns.
For each group of items identified, it is possible to evaluate a content constructor for the group. Grouping is nestable to multiple levels so that groups of distinct items can be identified, then from among the distinct groups selected, further sub-grouping of distinct items in the current group can be done.
Function: sequence current-group()
The evaluation context for
XPath expressions includes an additional value
called the current group, which is a sequence. The current group is the collection of
related items that are processed collectively in one iteration of the xsl:for-each-group
element.
While an xsl:for-each-group
instruction is being evaluated,
the current group will be non-empty. At other times, it will be an empty sequence.
The function current-group returns the current group.
The function takes no arguments.
[ERR070] The current-group function must not be used within a pattern.
xsl:for-each-group
Element<!-- Category: instruction -->
<xsl:for-each-group
select = expression
group-by = expression
group-adjacent = expression
group-starting-with = pattern>
<!-- Content: (xsl:sort*, content-constructor) -->
</xsl:for-each-group>
This element is an instruction that may be used anywhere within a content constructor.
The xsl:for-each-group
instruction partitions a sequence into
groups of items (that is, it establishes a set of sequences) based either on common
values of a grouping key, or on
a pattern that the initial node in a group must match.
The content constructor that forms the content of the
xsl:for-each-group
instruction is evaluated once
for each of these groups. A group is never empty.
The sequence of items
to be grouped, which
is referred to as the population,
is determined by evaluating the XPath expression contained in the
select
attribute.
The required type
of this expression is sequence
.
The population is treated as a sequence;
the order of
items in this sequence is referred to as population order. If the
population is empty, the number of groups will be zero. Each item
in the population is assigned to exactly one group: the assignment
of items to groups depends on the group-by
,
group-adjacent
, and group-starting-with
attributes.
[ERR071] These three attributes
are mutually exclusive: exactly one of the
three attributes must be present.
If the group-by
attribute is present, then
the group-by
expression
is evaluated once for each item
in the population, with that item as the context item, with its position,
in population order, as the
context position, and with the size of the
population as the context size.
The required type
of this expression is xsd:string
.
The result
of evaluating the group-by
expression is converted to a string; the
resulting string is known as the grouping key for that item.
All items that have the same value for the grouping key are assigned to
the same group, and the number of groups is the same as the number of
distinct grouping key values present in the population.
Issue (grouping-with-collation): The Working Group has decided in principle to add a
collation
attribute toxsl:for-each-group
, to specify the collation under which strings are compared for equality.
Issue (grouping-with-other-datatypes): Should we allow grouping based on key values whose data type is other than string?
If the group-adjacent
attribute is present, the
items in the population are examined, in population order.
The group-adjacent
expression
is evaluated once for each item
in the population, with that item as the context item, with its position,
in population order, as the context position, and with the size of the
population as the context size.
The required type
of this expression is xsd:string
.
The result
of evaluating the group-adjacent
expression is converted to a string; the
resulting string is known as the grouping key for that node. If an item
has the same value for the grouping key as its preceding node within
the population
(in population order), then it is assigned to the same group as its
preceding node; otherwise a new group is created and the item
becomes its first member.
If the group-starting-with
attribute is present, then its value must be
a pattern. In this case, the items in the population must all be nodes.
[ERR072] It is a dynamic error if the
result of evaluating the select
expression is not a node.
The processor must signal the error.
The nodes in the population are examined in population order. If a node matches the pattern, or is the first node in the population, then a new group is created and the node becomes its first member. Otherwise, the node is assigned to the same group as its preceding node within the population.
Issue (group-ending-with): A use case has also been identified for a
group-ending-with
attribute. This arises when all but the last item in a sequence carries a continuation marker of some kind.
For each group, the item within the group that is first in population order is known as the initial item of the group.
There is an ordering among groups referred to as the order of first appearance. A group G is defined to precede a group H in order of first appearance if the initial item of G precedes the initial item of H in population order.
There is another ordering among groups referred to as processing order.
If there are no xsl:sort
elements immediately within
the xsl:for-each-group
element, the processing order of
the groups is the order of first appearance.
Otherwise, the xsl:sort
elements immediately within
the xsl:for-each-group
element define the processing
order of the groups (see [12 Sorting]).
They do not affect the order of items within each group.
Multiple sort keys are allowed, and are evaluated in major-to-minor
order. If two groups have the same values for all their sort keys,
they are processed in order of first appearance.
The select
expression of an xsl:sort
element is
evaluated once for each group. During this evaluation, the context item is the initial item of the group,
the context position is the position
of this item within the
set of initial items (that is, one item for each group in the
population) in
population order,
the context size
is the number of groups,
and the
current group is the group
whose sort key is being determined. This means that if
the grouping key is
"@category"
, you can sort the groups in order of
their grouping key by writing <xsl:sort select="@category"/>
;
or you can sort the groups in order of size by writing
<xsl:sort select="count(current-group())" data-type="number">
If there are attribute value templates present in the
xsl:sort
element, the focus for evaluation
of the contained expressions is the same as the focus
for evaluation of the select
attribute of
the containing xsl:for-each-group
instruction.
The content constructor contained
by the xsl:for-each-group
element is evaluated once for each of the groups, in
processing order. The node sequences that result are concatenated,
in processing order, to form the result of the xsl:for-each-group
element. Within the content constructor, the
context item is
the initial item of the relevant group, the
context position is
the position of this item among
the set of initial items (one item for each group)
arranged in processing order of the groups,
the context size is the number of groups,
and the
current group
is the group being processed. This has the effect that
within the the content constructor, a call on position()
takes
successive values 1, 2, ... last()
.
On completion of the evaluation of the xsl:for-each-group
, the
current group reverts to its previous value.
The following example groups a list of nodes based on common values. The resulting groups are numbered but unsorted, and a total is calculated for each group.
Source XML document:
<cities> <city name="Milano" country="Italia" pop="5"/> <city name="Paris" country="France" pop="7"/> <city name="München" country="Deutschland" pop="4"/> <city name="Lyon" country="France" pop="2"/> <city name="Venezia" country="Italia" pop="1"/> </cities>
More specifically, the aim is to produce a four-column table,
containing one row for each distinct country. The four columns are to contain
first, a sequence number giving the number of the row;
second, the name of the country, third, a comma-separated
alphabetical list of the city names within that
country, and fourth, the sum of the pop
attribute for
the cities in that country.
Desired output:
<table> <tr> <th>Position</th> <th>Country</th> <th>List of Cities</th> <th>Population</th> </tr> <tr> <td>1</td> <td>Italia</td> <td>Milano, Venezia</td> <td>6</td> </tr> <tr> <td>2</td> <td>France</td> <td>Lyon, Paris</td> <td>9</td> </tr> <tr> <td>3</td> <td>Deutschland</td> <td>München</td> <td>4</td> </tr> </table>
Solution:
<table xsl:version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> <tr> <th>Position</th> <th>Country</th> <th>City List</th> <th>Population</th> </tr> <xsl:for-each-group select="cities/city" group-by="@country"> <tr> <td><xsl:value-of select="position()"/></td> <td><xsl:value-of select="@country"/></td> <td> <xsl:value-of select="current-group()/@name" separator=","> </td> <td><xsl:value-of select="sum(current-group()/@pop)"/></td> </tr> </xsl:for-each-group> </table>
The following example uses the same source document, this time grouping the cities according to the initial letter of the city name. The groups are sorted, and the result includes a count of the nodes within the group. The heading contains a count of the number of groups:
Desired output:
<html> <body> <h2>L (1)</h2><p>Lyon</p> <h2>M (2)</h2><p>Milano</p><p>München</p> <h2>P (1)</h2><p>Paris</p> <h2>V (1)</h2><p>Venezia</p> </body> </html>
Solution:
<html xsl:version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> <body> <xsl:for-each-group select="cities/city" group-by="substring(@name,1,1)"> <xsl:sort select="substring(@name,1,1)"/> <h2> <xsl:value-of select="upper-case(substring(@name,1,1))"/> <xsl:text> (</xsl:text> <xsl:value-of select="count(current-group())"/> <xsl:text>)</xsl:text> </h2> <xsl:for-each select="current-group()"> <p><xsl:value-of select="@name"/></p> </xsl:for-each> </xsl:for-each-group> </body> </html>
The next example identifies a group not by the presence of a common value, but rather
by adjacency in document order. A group consists of an h2
element,
followed by all the p
elements up to the next h2
element.
Source XML document:
<body> <h2>Introduction</h2> <p>XSLT is used to write stylesheets.</p> <p>XQuery is used to query XML databases.</p> <h2>What is a stylesheet?</h2> <p>A stylesheet is an XML document used to define a transformation.</p> <p>Stylesheets may be written in XSLT.</p> <p>XSLT 2.0 introduces new grouping constructs.</p> </body>
Desired output:
<chapter> <section title="Introduction"> <para>XSLT is used to write stylesheets.</para> <para>XQuery is used to query XML databases.</para> </section> <section title="What is a stylesheet?"> <para>A stylesheet is an XML document used to define a transformation.</para> <para>Stylesheets may be written in XSLT.</para> <para>XSLT 2.0 introduces new grouping constructs.</para> </section> </chapter>
Solution:
<xsl:template match="body"> <chapter> <xsl:for-each-group select="*" group-starting-with="h2" > <section title="{self::h2}"> <xsl:for-each select="current-group()[self::p]"> <para><xsl:value-of select="."/></para> </xsl:for-each> </section> </xsl:for-each-group> </chapter> </xsl:template>
The use of title="{self::h2}"
rather than title="{.}"
is
to handle the case where the first element is not an h2
element.
In the final example, the membership of a node within a group is based both on adjacency of the nodes in document order, and on common values. In this case, the grouping key is a boolean condition, true or false, so the effect is that a grouping establishes a maximal sequence of nodes for which the condition is true, followed by a maximal sequence for which it is false, and so on.
Source XML document:
<p>Do <em>not</em>: <ul> <li>talk,</li> <li>eat, or</li> <li>use your mobile telephone</li> </ul> while you are in the cinema.</p>
Desired output:
<p>Do <em>not</em>:</p> <ul> <li>talk,</li> <li>eat, or</li> <li>use your mobile telephone</li> </ul> <p>while you are in the cinema.</p>
Solution:
This requires creating a p
element around the maximal sequence
of sibling nodes that does not include a ul
or ol
element.
This can be done by using group-adjacent
, with a grouping key that is true
if the element is a ul
or ol
element, and false otherwise:
<xsl:template match="p"> <xsl:for-each-group select="node()" group-adjacent="self::ul or self::ol"> <xsl:choose> <xsl:when test="self::ul or self::ol"> <xsl:copy-of select="current-group()"/> </xsl:when> <xsl:otherwise> <p> <xsl:copy-of select="current-group()"> </p> </xsl:otherwise> </xsl:choose> </xsl:for-each-group> </xsl:template>
This section describes XSLT-specific additions to the core XPath function library. Some of these additional functions also make use of information specified by declarations in the stylesheet; this section also describes these declarations.
Issue (namespace-for-additional-functions): Should functions defined in XSLT (additional to those defined in XPath) use a different namespace, perhaps the XSLT namespace, to avoid any future conflicts with functions defined in the core?
Issue (document-function-in-core): The Functions and Operators specification (see [Functions and Operators]) describes an
xf:document
function which should supersede the one described here, allowing this section to be removed. However, at present the specification here is rather more complete.
Function: node * document(sequence, node?)
The document function allows access to XML documents other than the principal source document.
Call the value supplied as the first argument to the document function arg1 (in general this is a sequence), and call the value supplied as the second argument arg2. [ERR073] It is a dynamic error if arg2 is an empty sequence, or a sequence whose first item is not a node, unless all the URIs in arg1 are absolute URIs; The processor must either signal the error, or must recover by returning an empty sequence. If arg2 is a sequence of more than one node, the effect is as if only the first node in the sequence were supplied.
The result of the document function
can be explained in terms of an internal primitive function one-doc
which takes a requested URI and a base URI as arguments, and returns a node sequence
as its result. The result of the document function is the union
of the node sequences obtained by calling one-doc
once for each
member of the sequence arg1.
The one-doc
function retrieves a document
a document using a request URI R and a base URI B.
For a member of arg1 that is a node N,
the one-doc
function is called with the string-value of N
as the request URI, and with a base URI that is the base URI of arg2 if
arg2 was supplied, or the base URI of N otherwise.
For a member of the arg1 that is a simple value,
the one-doc
function is called using
a request URI obtained by converting that simple value to a string as if by using
the string function, and a base URI that is the base URI of arg2
if arg2 was supplied, or the base URI of the
stylesheet element containing the call
to the document function otherwise.
The internal one-doc
function operates as follows.
The resource identified by the URI is retrieved. The data resulting from the retrieval action is parsed as an XML document and a tree is constructed in accordance with the data model (see [3 Data Model]). [ERR074] An error retrieving the resource , is classed as a dynamic error. The processor must either signal the error, or must recover by returning an empty sequence. One possible kind of retrieval error is that the implementation does not support the URI scheme used by the URI. An implementation is not required to support any particular URI schemes. The documentation for an implementation should specify which URI schemes the implementation supports.
If the URI reference does not contain a fragment identifier, then the document node of the document is returned. If the URI reference does contain a fragment identifier, the function returns a node-sequence containing the nodes in the tree identified by the fragment identifier of the URI reference. The semantics of the fragment identifier are dependent on the media type of the result of retrieving the URI. [ERR075] An error in processing the fragment identifier is classed as a dynamic error; The processor must either signal the error, or must recover by returning an empty sequence. Possible errors include:
The fragment identifier identifies something that cannot be represented by an XSLT node sequence (such as a range of characters within a text node).
The implementation does not support fragment identifiers for the media-type of the retrieval result. An implementation is not required to support any particular media types. The documentation for an implementation should specify for which media types the implementation supports fragment identifiers.
The data resulting from the retrieval action is parsed as an XML
document regardless of the media type of the retrieval result; if the
top-level media type is text
, then it is parsed in the
same way as if the media type were text/xml
; otherwise,
it is parsed in the same way as if the media type were
application/xml
.
Issue (document-fragment-id): Should we be more prescriptive about the form of fragment identifier supported by the document function? Should we perhaps (following XInclude) mandate that it should be treated as an XPointer? Should we drop the notion that the form of fragment identifier depends on the media type, given that we are going to treat the actual media type as text/xml regardless?
NOTE: Since there is no top-levelxml
media type, data with a media type other thantext/xml
orapplication/xml
may in fact be XML.
The URI reference may be relative. The base URI (see [Data Model])
of the node in the second argument is used as the base
URI for resolving the
relative URI into an absolute URI.
Note that specifying a zero-length URI reference has
the same effect as specifying the base URI of the node containing the URI reference;
this means that unless XML entities or xml:base
are used,
document("")
refers to the document node of the stylesheet module;
the tree representation of the stylesheet module is exactly the same as if
the XML document containing the stylesheet was the
principal source
document.
NOTE: When a stylesheet module is loaded as a source document, the rules for whitespace stripping (see [3.4 Whitespace Stripping]) are those that apply to source documents, not those that apply to stylesheet documents.
Two documents are treated as the same document if they are identified by the same URI. The URI used for the comparison is the absolute URI into which any relative URI was resolved and does not include any fragment identifier. One document node is treated as the same node as another document node if the two nodes are from the same document. Thus, the following expression (if it does not cause an error) will always be true:
generate-id(document("foo.xml"))=generate-id(document("foo.xml"))
The document function gives rise to the possibility that a node sequence may contain nodes from more than one document. The concept of document order still applies, and is defined in [Data Model].
Function: sequence unparsed-text(sequence, string?)
The unparsed-text reads one or more external files and returns the contents of each one as a string.
The first argument is treated as a sequence. Each item in the sequence, when converted to a string, must be a URI. The URI must contain no fragment identifier, and must identify a resource that can be read as text. If the URI is a relative URI, then:
The second argument, if present, is the name of an encoding. This encoding is used to
translate the contents of the file into a string. The values for this attribute follow
the same rules as for the encoding attribute in an XML declaration. The only values which
every implementation is obliged to recognize are utf-8
and utf-16
.
If the second argument is omitted,
the implementation may attempt to infer the encoding of the file by using external information
(such as an HTTP header) or by auto-recognition using techniques such as those described
in [XML].
[ERR076] It is a dynamic error if a URI cannot be used to retrieve a resource containing text. The processor must either signal the error, or must recover by treating the URI as if it referenced a resource containing a zero-length string.
[ERR077] It is a dynamic error if a resource contains characters that are not valid XML characters. The processor must either signal the error, or must recover in an implementation-defined way; one possible outcome is that the processor will produce an output file that is not well-formed XML.
[ERR078] It is a dynamic error if a resource contains bytes that cannot be decoded into valid XML characters using the specified encoding. This includes the case where the processor does not support the requested encoding. The processor must signal the error.
[ERR079] It is a dynamic error if the second argument of the unparsed-text function is omitted and the processor cannot infer the encoding using external information.The processor must signal the error.
The result is a sequence of strings, containing one string for each URI in the sequence supplied as the first argument; each string holds the text of the resource retrieved using the URI in the corresponding position of the sequence.
NOTE: If the text file contains characters such as<
and&
, these will typically be output as<
and&
when the string is written to the result tree and serialized as XML or HTML. If these characters actually represent markup (for example, if the text file contains HTML), then the stylesheet can attempt to write them as markup to the output file using thedisable-output-escaping
attribute of thexsl:value-of
instruction (see [18.5 Disabling Output Escaping]. Note, however, that implementations are not required to support this feature.
The following example attempts to read an HTML file and copy it, as HTML, to the serialized output file:
<xsl:output method="html"/> <xsl:template match="/"> <xsl:value-of select="unparsed-text('header.html', 'iso-8859-1')" disable-output-escaping="yes"/> <xsl:apply-templates/> <xsl:value-of select="unparsed-text('footer.html', 'iso-8859-1')" disable-output-escaping="yes"/> </xsl:template>
Keys provide a way to work with documents that contain an implicit cross-reference structure. They make it easier to locate the nodes within a document that have a given value for a given attribute or child element, and they provide a hint to the implementation that certain access paths in the document need to be efficient.
xsl:key
Declaration<!-- Category: declaration -->
<xsl:key
name = qname
match = pattern
use = expression />
The xsl:key
declaration
is used to declare keys. The
name
attribute specifies the name of the key. The value
of the name
attribute is a QName, which is expanded as described
in [4.1 Qualified Names]. The match
attribute is a Pattern; an xsl:key
element
applies to all nodes that match the pattern
specified in the match
attribute. The use
attribute is
an expression specifying the
values of the key; the expression will be evaluated with the node that
matches the pattern as the context node.
The required type
of the expression is xsd:string*
, which means that the result of
evaluating the expression is treated as a sequence of strings, by taking the string value
of each item in the sequence.
The presence of an xsl:key
declaration makes it
easy to find a node that matches the match
pattern if any of the values
of the use
expression (when applied to that node) are known. It also provides
a hint to the implementation that access to the nodes by means of these values needs
to be efficient (many implementations are likely to
construct an index or hash table to achieve this.)
Note that the use
expression in general returns a sequence of values, and any one
of these may be used to locate the node.
It is possible to have:
match
patterns of several different key declarations;use
expression;An xsl:key
declaration with higher
import precedence does
not override another of lower import precedence; all the xsl:key
declarations
in the stylesheet are effective regardless of their import precedence.
Issue (collation-in-keys): Should
xsl:key
specify a collation to be used for matching strings?
Issue (datatype-in-keys): Should
xsl:key
allow comparison of values using data types other than string?
[ERR080] It is a static error for
the value of either the use
attribute or the match
attribute
to contain a Variable other than
a range variable defined within the XPath expression containing the
Variable, or a call to the
key function.
[ERR081] It is a dynamic error
if evaluating either the use
attribute or the match
attribute
results in a call on the key function, with
the name of this key definition as the first argument.
The processor must signal the error.
Function: node * key(string, sequence)
The key function does for keys what the id function does for IDs.
The first argument specifies the name of the key. The value of the argument must be a QName, which is expanded as described in [4.1 Qualified Names]. [ERR082] It is a dynamic error if the value is not a valid QName, or if there is no namespace declaration in scope for the prefix of the QName, or if the name obtained by expanding the QName is not the same as the expanded name of any key declaration in the stylesheet. The processor must signal these errors.
The second argument to the
key function is regarded as a sequence. The set of requested
key values is formed by converting each member of this sequence to a string
as if by a call to the
string function. The result of the function is
a sequence of nodes, in document order and with duplicates removed,
comprising those nodes in the
context document that
are matched by an xsl:key
declaration whose name is the same as the
supplied key name, and whose value is equal to one of these requested key values.
Issue (sequence-valued-keys): What if the second argument to key() is an attribute of type IDREFS? We should consider the typed-value of the nodes in the sequence, not just the string value.
More formally, if the result of evaluating the second argument of the key function is denoted by $V, the result returned by the key function is the union of the node sequences selected by the expression
//(MATCH)/self::node()[(USE) = $V]
applied to all xsl:key
declarations whose name
matches the
name given as the first argument to the key function,
where MATCH is the pattern given in the match
attribute of the
xsl:key
declaration, and USE is the expression
given in its use
attribute. The values of the match
and
use
attributes are textually substituted into the above expression. Note that
the predicate (USE) = $V
typically has a sequence on both
sides of the equals sign: it returns true if any of the values returned by the USE
expression is equal to any of the values in $V.
NOTE: The reason that/self::node()
appears in the above expression is to ensure that any calls ofposition()
orlast()
within the USE expression evaluate to 1 (one). This is necessary to retain compatibility with the XSLT 1.0 specification.
For example, given a declaration
<xsl:key name="idkey" match="div" use="@id"/>
an expression key("idkey",@ref)
will return the same
nodes as id(@ref)
, assuming that the only ID attribute
declared in the XML source document is:
<!ATTLIST div id ID #IMPLIED>
and that the ref
attribute of the context node
contains no whitespace.
Suppose a document describing a function library uses a
prototype
element to define functions
<prototype name="key" return-type="node-set"> <arg type="string"/> <arg type="object"/> </prototype>
and a function
element to refer to function names
<function>key</function>
Then the stylesheet could generate hyperlinks between the references and definitions as follows:
<xsl:key name="func" match="prototype" use="@name"/> <xsl:template match="function"> <b> <a href="#{generate-id(key('func',.))}"> <xsl:apply-templates/> </a> </b> </xsl:template> <xsl:template match="prototype"> <p><a name="{generate-id()}"> <b>Function: </b> ... </a></p> </xsl:template>
The key always
returns nodes that are in the context document; to
retrieve a key from any other document, it is necessary first to
change the context document. For
example, suppose a document contains bibliographic references in the
form <bibref>XSLT</bibref>
, and there is a
separate XML document bib.xml
containing a bibliographic
database with entries in the form:
<entry name="XSLT">...</entry>
Then the stylesheet could use the following to transform the
bibref
elements:
<xsl:key name="bib" match="entry" use="@name"/> <xsl:template match="bibref"> <xsl:variable name="name" select="."/> <xsl:apply-templates select="document('bib.xml')/key('bib',$name)"/> </xsl:template>
NOTE: This relies on the ability in XPath 2.0 to have any function call
on the right-hand side of the /
operator in a path expression.
Function: string format-number(double, string, string?)
The format-number function formats
a number as a string using the picture string
specified by the
second argument and the decimal-format named by the third argument, or
the default decimal-format, if there is no third argument.
The number is supplied as the value of the first argument. The required type
of this argument is xsd:double
; if the value is not of the right type, it
is converted using the standard conversion rules.
The decimal-format name must be a QName, which is expanded as
described in [4.1 Qualified Names]. The result of the function is the formatted string
representation of the supplied number.
[ERR083] It is a dynamic error if the stylesheet does not contain a declaration of the decimal-format with the expanded QName specified as the third argument. The processor must either signal the error, or must recover by ignoring the third argument.
NOTE: Stylesheets can use other facilities in XPath to control rounding.
<!-- Category: declaration -->
<xsl:decimal-format
name = qname
decimal-separator = char
grouping-separator = char
infinity = string
minus-sign = char
NaN = string
percent = char
per-mille = char
zero-digit = char
digit = char
pattern-separator = char />
The xsl:decimal-format
element declares a
decimal-format, which controls the interpretation of a picture string
used by the format-number function. If there is
a name
attribute, then the element declares a named
decimal-format; otherwise, it declares the default decimal-format.
The value of the name
attribute is a QName, which is expanded as described
in [4.1 Qualified Names].
[ERR084] It is a static error
to declare either the
default decimal-format or a decimal-format with a given name more than
once (even with different import
precedence), unless it is declared every time with the same
value for all attributes (taking into account any default values).
If a stylesheet does not contain a declaration of
the default decimal format, a declaration equivalent to
an xsl:decimal-format
element with no attributes
is implied.
The attributes of the xsl:decimal-format
declaration establish values for a number of variables used as input to
the algorithm followed by the format-number function.
An outline of the purpose of each attribute is given below; however, the definitive
explanations are given later, as part of the description of this algorithm.
The following attributes both control the interpretation of characters in the picture string supplied to the format-number function, and also specify characters that may appear in the result of formatting the number. In each case the value must be a single character.
decimal-separator
specifies the character used
for the decimal-separator-sign; the default value is the period character
(.
)
grouping-separator
specifies the character used
for the grouping-sign, which is typically used as a thousands
separator; the default value is the
comma character (,
)
percent
specifies the character used for the
percent-sign; the default value is the percent character
(%
)
per-mille
specifies the character used for the
per-mille-sign; the default value is the Unicode per-mille character
(#x2030)
zero-digit
specifies the character used for the
digit-zero-sign; the default value is the digit zero
(0
). This character must be a digit (category Nd in
the Unicode property database), and it must have the numeric value zero.
This attribute implicitly allocates the corresponding set of Unicode
digit characters to represent the values 0 to 9.
The following attributes control the interpretation of characters in the picture string supplied to the format-number function. In each case the value must be a single character.
digit
specifies the character used for the digit-sign
in the picture string; the default value is the number sign character
(#
)
pattern-separator
specifies the character used
for the pattern-separator-sign, which
separates positive and negative sub-pictures in a picture string; the
default value is the semi-colon character (;
)
The following attributes specify characters or strings that may appear in the result of formatting the number:
infinity
specifies the string used for the
infinity-symbol; the default value is the string
Infinity
NaN
specifies the string used for the
NaN-symbol, which is used to represent the value NaN (not-a-number);
the default value is the string NaN
minus-sign
specifies the character used for the
minus-symbol; the default value is the hyphen-minus character
(-
, #x2D). The value must be a single character.
[ERR085] It is a static error if, for any named or unnamed decimal format, the variables representing characters used in a picture string do not each have distinct values. These variables are decimal-separator-sign, grouping-sign, percent-sign, per-mille-sign, digit-zero-sign, digit-sign, and pattern-separator-sign.
The behavior of the format-number function is described here by means of an algorithm; an implementation may use any algorithm that delivers the same result.
The formatting of a number is controlled by a picture string. The picture string is a sequence of characters, in which the characters assigned to the variables decimal-separator-sign, grouping-sign, percent-sign, per-mille-sign, zero-digit-sign, digit-sign and pattern-separator-sign are classified as active characters, and all other characters are classified as passive characters.
Formatting is centered around the decimal-separator-sign, which can have a whole-part before and fractional-part after. The passive characters in the pattern string define a prefix and suffix portion.
The evaluation of the format-number function
is described below in two phases, an anaysis phase and a formatting
phase. The analysis phase takes as its inputs the picture string
and the variables derived from the relevant xsl:decimal-format
declaration,
and produces as its output a number of variables with defined values.
The formatting phase takes as its inputs the number to be formatted
and the variables produced by the analysis phase, and produces as
its output a string containing a formatted representation of the number.
Issue (format-number-left-to-right): This version of the format-number specification makes the presumption that numbers will be formatted with the most significant digit on the left. Do we want to make this assumption?
This phase of the algorithm analyses
the picture string and the attribute settings of
the xsl:decimal-format
declaration, and has the effect
of setting the values of various variables, which are used in the
subsequent formatting phase. These variables are listed below.
Each is shown with its initial setting and its data type.
In the third column
of this table, the word "single" means the one picture string that formats both positive
and negative numbers, as contrasted to the two "positive" and "negative"
sub-pictures that occur when the whole pattern has a pattern-separator.
[ERR086] The picture string must conform to the following rules . It is a dynamic error if the picture string does not satisfy these rules. The processor must either signal the error, or must recover by ignoring those characters in the supplied picture string that make the picture string invalid. If a valid picture string cannot be constructed, the processor may recover by returning the string obtained by applying the string function to the supplied number.
Note that in these rules "preceded" and "followed" refer to characters anywhere in the string, they are not to be read as "immediately preceded" and "immediately followed".
Inconsistent spacing of grouping separators is not an error. The only significant grouping separators are those closest to the decimal separator, on either side of it. Any others are ignored.
Issue (scientific-notation): There is a requirement to allow scientific notation in format-number() (it is permitted in the JDK 1.2 version of the original specification). The Working Group intends to add this capability before final publication of XSLT 2.0.
The following variables apply to the picture string as a whole:
digit-range-mapping (boolean, initially false): Indicates
whether the standard ASCII digits (0-9) have been replaced by another set of digits.
This property applies to the picture string as a whole, and is derived from the
xsl:decimal-format
declaration rather than the pattern string.
two-sub-pictures (boolean initially false): Indicates whether positive and negative sub-pictures exist. It is true if the picture string includes a pattern-separator-sign. This variable applies to the picture string as a whole.
The following variables apply to the picture string as a whole, if two-sub-pictures is false, or to the positive sub-picture alone if two-sub-pictures is true:
fractional-part-grouping (boolean, initially false): Indicates whether the fractional part will be grouped.
fractional-part-grouping-size (numeric, initially zero): Indicates the grouping-size for the fractional part.
integer-mode (boolean, initially true): Indicates whether the pattern lacks a decimal-separator and hence forces output as an integer.
maximum-fractional-part-size (numeric, initially zero): Indicates the largest number of digits possible for the fractional part.
maximum-whole-part-size (numeric, initially one). Indicates the largest number of digits possible for the whole part.
minimum-fractional-part-size (numeric, initially zero). Indicates the smallest number of digits possible for the fractional part.
minimum-whole-part-size (numeric, initially one). Indicates the smallest number of digits possible for the whole part.
overflow-threshold (numeric, initially 10). The value is always a power of 10; it indicates the smallest number that is too large to fit the whole part.
is-percent (boolean, initially false). Indicates whether the number is to be processed as a percentage.
is-per-mille (boolean, initially false). Indicates whether the number is to be processed as a per-mille.
prefix (string, initially empty). Indicates the string of passive characters to appear before the number.
prefix-exists (boolean, initially false). Indicates whether the prefix is non-null.
suffix (string, initially empty). Indicates the string of passive characters to appear after the number.
suffix-exists (boolean, initially false). Indicates whether the suffix is non-null.
whole-part-grouping (boolean, initially false). Indicates whether the whole part will be grouped.
whole-part-grouping-size (numeric, initially zero). Indicates the grouping-size for the whole part.
The following variables apply to the negative sub-picture, when there are two sub-pictures:
neg-fractional-part-grouping (boolean, initially false). Indicates, for negative numbers, whether the fractional part will be grouped.
neg-fractional-part-grouping-size (numeric, initially zero). Indicates, for negative numbers, the grouping size for the fractional part.
neg-integer-mode (boolean, initially true). Indicates, for negative numbers, whether the pattern lacks a decimal-separator and hence forces integer output.
neg-maximum-fractional-part-size (numeric, initially zero). Indicates, for negative numbers, the largest number of digits possible for the fractional part.
neg-maximum-whole-part-size (numeric, initially one). Indicates, for negative numbers, the largest number of digits possible for the whole part.
neg-minimum-fractional-part-size (numeric, initially 0). Indicates, for negative numbers, the smallest number of digits possible for the fractional part.
neg-minimum-whole-part-size (numeric, initially one). Indicate, for negative numbers, the smallest number of digits possible for the whole part.
neg-overflow-threshold (numeric, initially 10). Indicates, for negative numbers, the absolute value of the smallest number that is too large to fit the whole part (always a power of 10).
neg-is-percent (boolean, initially false). Indicates, for negative numbers, whether the number is to be processed as a percentage.
neg-is-per-mille (boolean, initially false). Indicates, for negative numbers, whether the number is to be processed as a per-mille.
neg-prefix (string, initially empty). Indicates, for negative numbers, the string of passive characters to appear before the number.
neg-prefix-exists (boolean, initially false). Indicates whether the prefix for negative numbers is non-null.
neg-suffix (string, initially empty). Indicates, for negative numbers, the string of passive characters to appear after the number.
neg-suffix-exists (boolean, initially false). Indicates, for negative numbers, whether the suffix is non-null.
neg-whole-part-grouping (boolean, initially false). Indicates, for negative numbers, whether the whole part will be grouped.
neg-whole-part-grouping-size (numeric, initially zero). Indicates, for negative numbers, the grouping size for the whole part.
Issue (position-percent): Must the percent or per-mille sign be immediately after the last digit or decimal-separator? Suggestion: keep the set of legal positions down to the minimum set that will satisfy all world cultures.
The algorithm is as follows:
If zero-digit is not "0", set digit-range-mapping to true and populate a mapping table for digits 0-9 (output characters for digits 1-9 must bear the same relationship to Basic Latin digits 1-9 as the requested zero-digit bears to Basic Latin digit 0). If two-sub-pictures is true, perform the remaining steps separately for the positive and negative patterns, otherwise set the properties for negative numbers to the same values as the positive-number properties, except for neg-prefix and neg-prefix-exists, which are always set separately.
Look for a decimal-separator-sign within the subpattern. If one is found, set integer-mode to false. If none is found, leave integer-mode set to true; add an implicit decimal-separator-sign just after the last (least significant) digit-sign or zero-digit-sign in the subpattern; and leave the minimum-fractional-part-size and maximum-fractional-part-size set to zero.
From the decimal-separator-sign, step through characters in order of increasing significance (that is, to the left) looking for an occurrence of the grouping-separator-sign. If none is found before the first occurrence of a passive character, leave the whole-part-grouping property set to false. When one is found, set the whole-part-grouping property to true and the whole-part-grouping-size to the number of characters between the decimal-separator-sign and the first grouping-separator-sign. (All other occurrences farther left are ignored.)
If there is a digit-sign immediately to the left of the (actual or implied) decimal-separator-sign, set the minimum-whole-part-size to zero (unless integer-mode is true, in which case leave it at 1) and step through the characters in order of increasing significance (that is, to the left) looking for a passive character. If there is a zero-digit-sign immediately to the left of the decimal-separator, step through the characters in order of increasing significance (that is, to the left) looking for either a digit-sign or passive character. As soon as a character other than a zero-digit-sign or grouping-separator-sign is found, set minimum-whole-part-size to the number of zero-digit-signs found on this side of the decimal-separator. When a passive character is encountered, set the maximum-whole-part-size to the total number of digit-sign and zero-digit-sign characters found on this side of the decimal-separator. Set overflow-threshold to ten raised to the power of maximum-whole-part-size.
Take all characters from the just-encountered passive character to the beginning of the picture string as the prefix. Set prefix-exists to true if there are any. If two-sub-pictures is false, set neg-prefix by copying the prefix (if any) and then appending the minus-sign character (i.e., making it the character that will be adjacent to the following number), and set neg-prefix-exists to true. If two-sub-pictures is true, then when analyzing the negative pattern, take all characters from the first-encountered (rightmost) passive character to the beginning of the format string as the neg-prefix. Set neg-prefix-exists true if there are any.
From the (actual) decimal-separator-sign, step through characters in order of decreasing significance (that is, to the right) looking for an occurrence of the grouping-separator-sign. If none is found before the first occurrence of a passive character, leave fractional-part-grouping set to false. When one is found, set fractional-part-grouping to true and fractional-part-grouping-size to the number of characters between the decimal-separator-sign and the first grouping-separator-sign. (All other occurrences further to the right are ignored.)
If there is a digit-sign adjacent to the decimal-separator-sign on the fractional side, leave the minimum-fractional-part-size set to zero and step through the characters in order of decreasing significance (that is, to the right) looking for a passive character, percent-sign, or per-mille-sign. If there is a zero-digit-sign adjacent to the decimal-separator-sign, step through the characters in order of decreasing significance (that is, to the right) looking for an either a digit-sign, passive character, percent-sign, or per-mille-sign. As soon as a character other than zero-digit-sign or grouping-separator-sign is found, set minimum-fractional-part-size to the number of zero-digit-signs found on this side of the decimal-separator-sign. When a passive character, percent-sign, or per-mille-sign is encountered, set maximum-fractional-part-size to the total number of digit-sign and zero-digit-sign characters found on this side of the decimal-separator.
If a percent-sign was encountered, set is-percent to true. If a per-mille-sign was encountered, set is-per-mille property true.
Take all characters from the first-encountered passive character on the fractional side, or the percent-sign or per-mille-sign, to the end of the format string as the suffix. Include the percent-sign or per-mille-sign, if any, as the first character of the suffix. Set suffix-exists true if there are any characters.
Reminder: if two-sub-pictures is true, perform all steps except the first one above once for each sub-picture. Otherwise, set all the attributes for the negative pattern except neg-prefix and neg-prefix-exists to be the same as the corresponding values for the positive pattern. Always set neg-prefix and neg-prefix-exists as described in step 5.
This algorithm describes the second phase of processing of the
format-number function. It takes as input a number to be formatted
(referred to as the input number, and the variables set up by
analysing the xsl:decimal-format
declaration and the
picture string, as described above.
The result of this algorithm is
a string, which forms the return value of
the format-number function.
The algorithm for this second stage of processing is as follows:
If the input number is NaN (not a number), return the concatenation of the prefix, the specified NaN-symbol, and the suffix, where the prefix and suffix are taken from the positive sub-picture if two-sub-pictures is true.
If the input number is positive infinity, return the concatenation of the prefix, the infinity-symbol, and the suffix.
If the input number is negative infinity, return the concatenation of the neg-prefix, the infinity-symbol, and the neg-suffix.
If the input number is positive (>= 0) and is-percent is true, multiply the number by 100. If the number is positive and is-per-mille is true, multiply the number by 1000. If the number is negative and neg-is-percent is true, multiply the number by 100. If the number is negative and neg-is-per-mille is true, multiply the number by 1000. The resulting number is referred to below as the adjusted number.
If the absolute value of the adjusted number is numerically greater than or equal to the overflow-threshold, then: if the adjusted number is positive, return the concatenation of the prefix, the overflow filler, and the suffix; if the adjusted number is negative, return the concatenation of the neg-prefix, the overflow filler, and the neg-suffix.
Issue (overflow-filler): Should overflows be represented by a filler pattern? What is the overflow filler pattern? Suggestion: use the digit character (default #) literally in place of all digits, and show decimal and grouping separators literally. This will take up the same space as a value with the maximum number of displayable decimal places, and have separators aligned.
(Integer case) If the adjusted number is positive and integer-mode is true, or if it is negative and neg-integer-mode is true, round the number to the nearest integer using the rules for the XPath round function. If the adjusted number is negative, use the properties pertaining to the negative sub-pattern. If the number of digits is less than minimum-whole-part-size, prepend zero-digit-sign characters to pad out to that size. Map all digits if the digit-range-mapping property is true. If whole-part-grouping is true, count digits from the decimal-separator-sign in the direction of increasing significance, and when more than whole-part-grouping-size digits are found, insert a grouping-separator-sign to set off whole-part-grouping-size digits on the less significant side, repeating so that there are not more than whole-part-grouping-size digits in any group, and the leading character of the whole-part is a digit rather than grouping-separator-sign. If the adjusted number is positive, return the concatenation of the prefix, the string conversion of the number, and the suffix. If the adjusted number is negative, return the concatenation of the neg-prefix, the string conversion of the number, and the neg-suffix.
Render the whole-part as a string. If the adjusted number is negative, use the properties pertaining to the negative sub-picture. If the number of digits is less than minimum-whole-part-size, prepend zero-digit characters to pad out to that size. Map all digits if the digit-range-mapping property is true. If whole-part-grouping is true, count digits from the decimal separator in the direction of increasing significance, and when more than whole-part-grouping-size digits are found, insert a grouping-separator to set off whole-part-grouping-size digits on the less significant side, repeating so that there are not more than whole-part-grouping-size digits in any group, and the leading character of the whole-part is a digit rather than grouping-separator-sign. (Note: the result of this step could be a zero-length string.)
Render the fractional-part as a string. If the adjusted number is negative, use the properties pertaining to the negative sub-pattern. If the number of digits is less than minimum-fractional-part-size, append zero-digit-sign characters to pad out to that size. If the number of digits is greater than maximum-fractional-part-size, set the least significant displayed digit by rounding as if it were the whole-part and following digits were the fractional-part in the XPath rounding procedure, but ignoring any sign that may result. Map all digits if the digit-range-mapping property is true. If fractional-part-grouping is true, count digits from the decimal-separator-sign in the direction of decreasing significance, and when more than fractional-part-grouping-size digits are found, insert a grouping-separator to set off fractional-part-grouping-size digits on the more significant side, repeating so that there are not more than fractional-part-grouping-size digits in any group, and the trailing character of the fractional-part is a digit rather than grouping-separator. (Note: the result of this step could be a zero-length string. It could also be a string of zeroes.)
If the adjusted number is positive, return the concatenation of the prefix, the whole-part as rendered above, the decimal-separator-sign, the fractional-part as rendered above, and the suffix. If the adjusted number is negative, return the concatenation of the neg-prefix, the whole-part as rendered above, the decimal-separator-sign, the fractional-part as rendered above, and the neg-suffix.
In certain circumstances, it is useful in a stylesheet to evaluate XPath expressions that are not hard-coded in the stylesheet text. For example, XPath expressions may be read from the source document, or supplied to the stylesheet as parameters, or constructed as a string from run-time information. A common requirement is for an application to allow the user to select the key that should be used for sorting output, and a natural mechanism for implementing this is to allow the sort key to be passed to the stylesheet as a string parameter, with the string containing an XPath expression to be used as the sort key.
The current function, used within an XPath expression, returns the item that was the context item at the point where the expression was invoked from the XSLT stylesheet. This is referred to as the current item. For an outermost expression (an expression not occurring within another expression), the current item is always the same as the context item. Thus,
<xsl:value-of select="current()"/>
means the same as
<xsl:value-of select="."/>
However, within square brackets, or on the
right-hand side of the /
operator,
the current item is generally
different from the context item. For example,
<xsl:apply-templates select="//glossary/item[@name=current()/@ref]"/>
will process all item
elements that have a
glossary
parent element and that have a name
attribute with value equal to the value of the current item's
ref
attribute. This is different from
<xsl:apply-templates select="//glossary/item[@name=./@ref]"/>
which means the same as
<xsl:apply-templates select="//glossary/item[@name=@ref]"/>
and so would process all item
elements that have a
glossary
parent element and that have a name
attribute and a ref
attribute with the same value.
[ERR089] It is a static error to use the current function in a pattern.
[ERR090] It is a dynamic error if the current function is called while evaluating a pattern. The processor must signal the error.
Function: string unparsed-entity-uri(string)
The unparsed-entity-uri returns the URI of the unparsed entity with the specified name in the context document (see [3.3 Unparsed Entities]). It returns the empty string if there is no such entity.
Function: string generate-id(node?)
The generate-id function returns a string that uniquely identifies a given node. The unique identifier must consist of ASCII alphanumeric characters and must start with an alphabetic character. Thus, the string is syntactically an XML name. An implementation is free to generate an identifier in any convenient way provided that it always generates the same identifier for the same node and that different identifiers are always generated from different nodes. An implementation is under no obligation to generate the same identifiers each time a document is transformed. There is no guarantee that a generated unique identifier will be distinct from any unique IDs specified in the source document. If the argument is an empty sequence, the empty sequence is returned. If the argument is omitted, it defaults to the context node.
[ERR091] It is a dynamic error if value of the argument is a sequence other than an empty sequence or a sequence containing a single node. If the first item in the sequence is not a node, the processor must signal the error. If the first item in the sequence is a node, the processor may signal the error, or may recover by returning the string that identifies the first node in the sequence.
Ed. Note: This should be covered by the standard fallback type conversion rules, but in the current XPath draft, no fallback rules are given for functions that expect a single node.
Function: string system-property(string)
The argument must evaluate to a string that is a QName. The QName is expanded into a name using the namespace declarations in scope for the expression. [ERR092] It is a dynamic error if the value is not a valid QName, or if there is no namespace declaration in scope for the prefix of the QName. The processor must signal these errors.
The system-property function returns a string representing the value of the system property identified by the name. If there is no such system property, the empty string should be returned.
Implementations must provide the following system properties, which are all in the XSLT namespace:
xsl:version
, a number giving the version of XSLT
implemented by the processor; for implementations conforming to the
version of XSLT specified by this document, this is the string
"2.0"
. The value will always be a string in the lexical
space of the decimal data type defined in XML Schema (see [XML Schema])
This allows the value to be converted to a number for the purpose
of magnitude comparisons.xsl:vendor
, a string identifying the implementor of the
processorxsl:vendor-url
, a string containing a URL
identifying the implementor of the processor; typically this is the
host page (home page) of the implementor's Web site.xsl:product-name
, a string containing the name
of the implementation, as defined by the implementor. This should normally
remain constant from one release of the product to the next. It should also be
constant across platforms in cases where the same source code is used to produce
compatible products for multiple execution platforms.
xsl:product-version
, a string identifying the version
of the implementation, as defined by the implementor. This should normally
vary from one release of the product to the next, and at the discretion
of the implementor it may also vary across different execution platforms.NOTE: An implementation must not return the value2.0
as the value of thexsl:version
system property unless it is conformant to XSLT 2.0. It is recognized that vendors who are enhancing XSLT 1.0 processors may wish to release interim implementations before all the mandatory features of this specification are implemented. Since such products are not conformant to XSLT 2.0, this specification cannot define their behavior. However, implementors of such products are encouraged to return a value for thexsl:version
system property that is intermediate between 1.0 and 2.0, and to provide the element-available and function-available functions to allow users to test which features have been fully implemented.
Implementations must not define additional system properties in the XSLT namespace.
<!-- Category: instruction -->
<xsl:message
terminate = "yes" | "no">
<!-- Content: content-constructor -->
</xsl:message>
The xsl:message
instruction sends a message in a way
that is dependent on the implementation. The content of the
xsl:message
instruction is a
content constructor. The
content constructor is evaluated, and the resulting sequence of nodes is
added to a newly-created document node, to create an XML fragment.
This XML fragment forms the content of the
message. The message is output to an implementation-defined
destination. The result of the xsl:message
instruction is an empty
sequence.
NOTE: An implementation might implement xsl:message
by
popping up an alert box or by writing to a log file.
If the terminate
attribute has the value
yes
, then the processor must
terminate processing after sending the message. The default value is no
.
One convenient way to do localization is to put the localized
information (message text, etc.) in an XML document, which becomes an
additional input file to the stylesheet. For example, suppose
messages for a language L
are stored in an XML
file resources/L.xml
in the form:
<messages> <message name="problem">A problem was detected.</message> <message name="error">An error was detected.</message> </messages>
Then a stylesheet could use the following approach to localize messages:
<xsl:param name="lang" select="'en'"/> <xsl:variable name="messages" select="document(concat('resources/', $lang, '.xml'))/messages"/> <xsl:template name="localized-message"> <xsl:param name="name"/> <xsl:message> <xsl:value-of select="$messages/message[@name=$name]"/> </xsl:message> </xsl:template> <xsl:template name="problem"> <xsl:call-template name="localized-message"/> <xsl:with-param name="name">problem</xsl:with-param> </xsl:call-template> </xsl:template>
XSLT allows two kinds of extension, extension instructions and
extension functions.
An
extension instruction is an element within a
content constructor that is in
a namespace (not the XSLT namespace)
designated as an extension namespace.
An
extension function is a function that is available for
use within an XPath expression, other than a core function defined
in the XPath specification, an additional function defined in this
XSLT specification, or a stylesheet
function defined using an xsl:function
declaration..
This specification does not define any mechanism for creating or binding implementations of extension instructions or extension functions, and does not require that implementations support any such mechanism. Therefore, an XSLT stylesheet that must be portable between XSLT implementations cannot rely on particular extensions being available. XSLT provides mechanisms that allow an XSLT stylesheet to determine whether the implementation makes particular extensions available, and to specify what should happen if those extensions are not available. If an XSLT stylesheet is careful to make use of these mechanisms, it is possible for it to take advantage of extensions and still retain portability.
If the FunctionName used in a FunctionCall within an XPath expression is not an NCName (that is, if it contains a colon), and if the stylesheet contains no stylesheet function with a matching expanded QName, then it is treated as a call to an extension function. The QName used as the FunctionName is expanded using the namespace declarations in scope at the point in the stylesheet where the expression appears.
The function-available function can be used with the
xsl:choose
and xsl:if
instructions to
explicitly control how a stylesheet should behave if a particular
extension function is not available.
Function: boolean function-available(string)
A function name is said to be available if it matches the name of a core function defined in XPath, or the name of an additional function defined in this XSLT specification, or the name of a stylesheet function, or if the processor is able to locate an implementation of an extension function with a matching name.
The function-available function returns true if the function name supplied as its argument is available; otherwise it returns false.
The value of the first argument must be a string containing a QName. The QName is expanded into an expanded QName using the namespace declarations in scope for the expression. The function-available function returns true if and only if the expanded-name is the name of a function in the function library. If the expanded-name has a non-null namespace URI, then it refers to a stylesheet function or extension function; otherwise, it refers to a function defined by XPath or XSLT.
[ERR093] It is a dynamic error if the argument does not evaluate to a string that is a valid QName, or if there is no namespace declaration in scope for the prefix of the QName. The processor must either signal the error, or must recover by returning the value false.
NOTE: The fact that a function with a given name is available gives no guarantee that any particular call on the function will be successful. For example, it is not possible to determine the number of arguments expected, nor their types.
[ERR094] It is a dynamic error if a FunctionCall within an XPath expression is evaluated, when the function in question is not available. The processor must signal the error. An implementation must not signal a static error merely because an expression contains a call to an extension function for which no implementation is available.
If the FunctionName used in a FunctionCall within an XPath expression identifies an extension function, then to evaluate the FunctionCall, the processor will first evaluate each of the arguments in the FunctionCall. If the processor has information about the data types expected by the extension function, then it may perform any necessary type conversions between the XPath data types and those defined by the implementation language. If multiple extension functions are available with the same name, the processor may decide which one to invoke based on the number of arguments, the types of the arguments, or any other criteria. The result returned by the implementation is returned as the result of the function call, again after any necessary conversions between the data types of the implementation language and those of XPath. The details of such type conversions are outside the scope of this specification.
[ERR095] It is a dynamic error if the arguments supplied to a call on an extension function do not satisfy the rules defined for that particular extension function, or if the extension function reports an error, or if the result of the extension function cannot be converted to an XPath value.The processor must signal the error.
NOTE: There is no prohibition on calling extension functions that have side-effects (for example, an extension function that writes data to a file). However, the order of execution of XSLT instructions is not defined in this specification, so the effects of such functions are unpredictable.
NOTE: Implementations are not required to perform full validation of values returned by extension functions. For example, the effect of returning a string containing characters that are not legal XML characters is implementation-defined.
NOTE: The ability to execute extension functions represents a potential security weakness, since untrusted stylesheets may invoke code that has privileged access to resources on the machine where the processor executes. Implementations may therefore provide mechanisms that restrict the use of extension functions by untrusted stylesheets.
Issue (external-objects): Do we want to keep the description of external objects (which was introduced in the XSLT 1.1 Working Draft)? What are the data model implications?
Support for extension functions introduces an additional data-type into the expression language. This additional data type is called an external object. A variable may be bound to an object of type external object instead of one of the XPath data-types. An external object represents an object that is not convertible to one of the XPath data types, which is created by an external programming language and returned by an extension function. Expressions can only return values of type external object by referencing variables of type external object or calling extension functions that return an external object.
An external object may only be passed as an argument to another
extension function.
[ERR096] It is a dynamic error
to attempt to copy an external object to a result tree, or to convert it
(implicitly or explicitly) to any of the XPath data types.
The processor must signal the error.
So, for example, if the myvar
variable is bound an
external object, then the following are dynamic
errors, which a processor must signal:
<xsl:copy-of select="$myvar"/> <!--
Cannot copy to result tree -->
<xsl:value-of select="$myvar"/> <!--
Cannot implicitly convert to String -->
<xsl:value-of select="string($myvar)"/>
<!-- Cannot explicitly convert to String -->
If an external object is passed to an extension function with an expanded QName whose namespace URI is different from the namespace URI of the expanded QName of the extension function that returned that external object, the behavior is implementation-dependent.
An extension function can
be used to convert the argument to a
string or return an XML fragment to be copied to the result tree if
desired. For example, assuming the myext:print()
extension function accepts an argument of a compatible data type and
returns a string, the following is allowed:
<!-- Convert to string with extension function --> <xsl:value-of select="myext:print($myvar)"/>
Issue (null-external-object): Should the spec have the concept that an external object may be null, and provide a way for testing this, for example, by conversion to
boolean
?
Ed. Note: Define the idea that an external object "wraps" an object created by an external programming language.
The extension instruction mechanism allows namespaces to be designated as extension namespaces. When a namespace is designated as an extension namespace and an element with a name from that namespace occurs in a content constructor, then the element is treated as an instruction rather than as a literal result element. The namespace determines the semantics of the instruction.
NOTE: Since an element that is a child of an
xsl:stylesheet
element is not occurring in a
content constructor,
non-XSLT top-level elements are not extension
elements as defined here, and nothing in this section applies to
them.
A namespace is designated as an extension namespace by using an
[xsl:]extension-element-prefixes
attribute on an
element in the stylesheet (see [2.3 Standard Attributes]).
The attribute must be in the XSLT namespace
only if its parent element is not in the XSLT namespace.
The value of the attributes is a
whitespace-separated list of namespace prefixes. The namespace bound
to each of the prefixes is designated as an extension namespace. [ERR097] It
is a static error
if there is no namespace bound to the prefix on the
element bearing the [xsl:]extension-element-prefixes
attribute.
The default
namespace (as declared by xmlns
) may be designated as an
extension namespace by including #default
in the list of
namespace prefixes. The designation of a namespace as an extension
namespace is effective for
the element bearing the [xsl:]extension-element-prefixes
attribute
and for all descendants of that element within the same stylesheet module.
The element-available function can be used with the
xsl:choose
and xsl:if
instructions to
explicitly control how a stylesheet should behave if a particular
extension instruction is not available.
Function: boolean element-available(string)
The value of the first argument must be a string containing a QName. The QName is expanded into an expanded QName using the namespace declarations in scope for the expression. If there is a default namespace in scope, then it is used to expand an unprefixed QName. The element-available function returns true if and only if the expanded-name is the name of an instruction. If the expanded-name has a namespace URI equal to the XSLT namespace URI, then it refers to an element defined by XSLT. Otherwise, it refers to an extension instruction. If the expanded-name has a null namespace URI, the element-available function will return false.
[ERR098] It is a dynamic error if the argument does not evaluate to a string that is a valid QName, or if there is no namespace declaration in scope for the prefix of the QName. The processor must either signal the error, or must recover by returning the value false.
If the processor does not have an implementation of a particular extension instruction available, then the element-available function must return false for the name of the element. When such an extension instruction is evaluated, then the processor must perform fallback for the element as specified in [16.2.3 Fallback]. An implementation must not signal an error merely because a template contains an extension instruction for which no implementation is available.
If the processor has an implementation of a particular extension instruction available, then the element-available function must return true for the name of the element.
<!-- Category: instruction -->
<xsl:fallback>
<!-- Content: content-constructor -->
</xsl:fallback>
Normally, evaluating an xsl:fallback
element returns
an empty sequence: the content of the xsl:fallback
element is ignored.
However, when a processor performs fallback for an
instruction element, if the instruction
element has one or more
xsl:fallback
children, then the content of each of the
xsl:fallback
children must be evaluated;
if it has no xsl:fallback
children, a
dynamic error must be signaled.
The content of an xsl:fallback
element is a
content constructor,
and when performing fallback, the value
returned by the xsl:fallback
element
is the result of evaluating this content constructor.
There are two situations where a processor performs fallback: when an extension instruction that is not available is evaluated, and when an instruction in the XSLT namespace, that is not defined in XSLT 2.0, is evaluated with region of the stylesheet for which forwards compatible behavior.
The output of a transformation is a set of final result trees. One of these is the
principal result tree, the others are referred to as secondary result trees. The
principal result tree is the current result tree
when the transformation is initiated; a secondary result tree is created using an
xsl:result-document
instruction, and becomes the current result tree while the
xsl:result-document
instruction is being evaluated.
Ed. Note: The term "final result tree" seems oxymoronic. Perhaps we should just call them "result trees". In this case the term "current result tree" needs to change, perhaps to "current destination", to reflect the fact that the destination might be a temporary tree rather than a [final] result tree.
The way in which a final result tree is delivered to an application is implementation-defined.
A final result tree has a URI. If the implementation provides an API to access final result trees, then it must allow a final result tree to be identified by means of this URI.
NOTE: The URI of the result tree is not the same thing as the URI of its serialized representation on disk, if any. For example, a server (or browser client) might store the result trees only in memory, or in an internal disk cache. As long as it satisfies requests for those URIs, it is irrelevant where they are actually written on disk, if at all.
The URI of the principal result tree is specified using the href
attribute of
an xsl:destination
declaration;
the URI of a secondary result tree is specified using the
href
attribute of an xsl:result-document
instruction.
If the URI for a secondary
result tree is relative, it is resolved relative to the base URI of the principal result tree. If the
URI for the principal result tree is relative, it is resolved relative to an implementation-defined
base URI.
NOTE: It will often be the case that one result tree contains links to another result tree produced during the same transformation, in the form of a relative URI. The mechanism of associating a URI with a final result tree has been chosen to allow the integrity of such links to be preserved when the trees are serialized.
NOTE: The URI of a result tree is unrelated to the base URI of its document node.
Serialization of final result trees is described further in [18 Serialization]
<!-- Category: declaration -->
<xsl:destination
format = qname
href = { uri-reference } />
The xsl:destination
element is used to define the URI
of the principal result
tree, and optionally to specify the output format to be used for serializing this tree.
Issue (destination-element-name): Is it possible to find a better name for the
xsl:destination
element? The namexsl:principal-result
has been suggested.
The value of the format
attribute, if specified, must be a QName.
The QName is expanded using the namespace declarations in scope for the
xsl:destination
element. The expanded QName must match the expanded
QName of a named output definition in the stylesheet.
This identifies
the xsl:output
declaration that will control the serialization of the
result tree (see [18 Serialization]), if the result tree is serialized. If the
format
attribute is omitted, the unnamed
output definition
is used to control serialization of the principal result tree.
[ERR099] It is a static error if the
value of the format
attribute
is not a valid QName, or if it does not match the expanded QName of an
output definition in the stylesheet.
If there is more than one xsl:destination
element at the top level
of the stylesheet, the one with highest import precedence
is used. [ERR100] It is a static error if
there is more than one xsl:result-document
element at the top level
of the stylesheet with the same import precedence, unless there is also another
xsl:result-document
element at the top level of the stylesheet
with a higher import precedence.
If there is no xsl:destination
element at the top level
of the stylesheet, the effect is the same as specifying a single top-level
xsl:result-document
element with no attributes.
The href
attribute defines the URI of the principal result tree. The
attribute value template is expanded using
a singleton focus based on the document node
of the principal source document.
The effective value of the attribute must be a URI.
The implementation may place restrictions on the form of absolute URI
that may be used, but it is not required to enforce any restrictions.
Any legal relative URI must be accepted.
If the effective value is a relative URI, then it is resolved relative to an implementation-defined base URI.
The href
attribute may be omitted,
in which case the URI of the principal result tree is implementation-defined.
NOTE: The main reason to specify a URI for the principal result tree is to allow it to be referenced by links from a secondary result tree.
<!-- Category: instruction -->
<xsl:result-document
format = qname
href = { uri-reference }>
<!-- Content: content-constructor -->
</xsl:result-document>
The xsl:result-document
instruction is used to create a
secondary result tree. The content of the
xsl:result-document
element is a
content constructor; this is evaluated
to create a sequence of nodes. A document node is created with this
sequence of nodes as its children. The tree rooted at this document node
forms the secondary result tree.
The xsl:result-document
instruction defines the URI
of a secondary final result
tree, and may optionally specify the output format to be used for serializing this tree.
The value of the format
attribute, if specified, must be a QName.
The QName is expanded using the namespace declarations in scope for the
xsl:result-document
element. The expanded QName must match the expanded
QName of a named output definition in the stylesheet.
This identifies
the xsl:output
declaration that will control the serialization of the
result tree (see [18 Serialization]), if the result tree is serialized. If the
format
attribute is omitted, the unnamed
output definition
is used to control serialization of the result tree.
[ERR101] It is a static error if the
value of the format
attribute
is not a valid QName, or if it does not match the expanded QName of an
output definition in the stylesheet.
The href
attribute is mandatory.
The effective value of the attribute must be a URI.
The implementation may place restrictions on the form of absolute URI
that may be used, but it is not required to enforce any restrictions.
Any legal relative URI must be accepted.
If the effective value is a relative URI, then it is resolved relative to the URI of the principal result tree.
A processor may allow a secondary result tree
to be serialized, just as it may allow the principal result tree to be serialized.
Serialization is described in [18 Serialization].
However, an implementation (for example,
a processor running in an environment with no access
to writable filestore) is not required to
support the serialization of secondary result trees. An implementation that does not support
the serialization of secondary result trees must ignore the format
attribute.
Such an implementation
must provide the application with some means of access to the (un-serialized) result tree,
using its URI to identify it.
For example, the following would create a principal result document specifying an HTML frameset with two frames, together with two secondary result documents, one for the contents of each frame:
<xsl:template match="/"> <html> <head><title>Frame example</title></head> <frameset cols="20%, 80%"> <frame src="toc.html"/> <xsl:result-document href="toc.html"> <html> <head><title>Table of Contents</title></head> <body> <xsl:apply-templates mode="toc" select="*"/> </body> </html> </xsl:result-document> <frame src="body.html"/> <xsl:result-document href="body.html"> <html> <head><title>Body</title></head> <body> <xsl:apply-templates select="*"/> </body> </html> </xsl:result-document> </frameset> </html> </xsl:template>
[ERR102] It is a dynamic
error to evaluate the xsl:result-document
instruction when
the current result tree is
neither the principal result tree, nor a secondary result tree. The
processor must signal the error..
This means, for example,
that it is an error to use xsl:result-document
when the current result tree
is a temporary tree created using xsl:variable
, or a tree created using
xsl:message
, xsl:attribute
, etc.
[ERR103] It is a dynamic error for a transformation to generate two or more result trees with the same URI. The processor must signal the error.
Technically, the result of evaluating the xsl:result-document
instruction is an empty sequence. This means it does not contribute any nodes to
the result of the content constructor it is part of.
A processor may output a final result tree as a sequence of
bytes, although it is not required to be able to do so (see [19 Conformance]).
Stylesheet authors can use the xsl:output
declaration
to specify how they wish result trees to be serialized.
If a processor serializes the result tree, it should do so
as specified by these elements; however, it is not required to do so.
<!-- Category: declaration -->
<xsl:output
name = qname
method = { "xml" | "html" | "xhtml" | "text" | qname-but-not-ncname }
version = { nmtoken }
encoding = { string }
omit-xml-declaration = { "yes" | "no" }
standalone = { "yes" | "no" }
doctype-public = { string }
doctype-system = { string }
cdata-section-elements = { qnames }
indent = { "yes" | "no" }
media-type = { string }
include-content-type = { "yes" | "no" }
escape-uri-attributes = { "yes" | "no" } />
The xsl:output
declaration is optional; if used, it must always
appear as a top-level element within a stylesheet.
All attributes on xsl:output
are interpreted as
attribute value
templates. Expressions recognized in the attributes of
xsl:output
are evaluated with a
singleton focus based on the
document node of the principal source document.
[ERR104] It is a dynamic error
if the value of an attribute
does not conform to the rules listed below.
The processor must either signal the error,
or must recover by using the default value
for that attribute.
A stylesheet may contain multiple xsl:output
declarations
and may include or import stylesheet modules that also contain
xsl:output
declarations. The name of an xsl:output
declaration
is the effective value of its name
attribute, if any.
All
the xsl:output
declarations in a stylsheet
that share the same name are grouped into a named output definition;
those that have no name are grouped into a a single unnamed output definition.
A named output definition is used when its name matches the format
attribute
used in an xsl:result-document
element. The unnamed output definition is used
when an xsl:result-document
element omits the format
attribute.
All the xsl:output
elements making up an output definition are effectively merged.
For the
cdata-section-elements
attribute, the output definition uses
the union of the effective values from all the constituent xsl:output
declarations.
For other attributes, the
output definition uses the effective value
of that attribute from the
xsl:output
declaration with the
highest import precedence.
[ERR105] It is a
dynamic error
if two xsl:output
declarations within an
output definition specify
explicit values for the same attribute (other than cdata-section-elements
),
with the effective values of the attributes being not equal,
and with neither of these declarations being overridden
by an xsl:output
declaration with higher import precedence that specifies
an explicit value for the same attribute.
The processor must either signal the error,
or must recover by using the value that occurs last in
declaration order.
The values of attributes are defaulted after the
xsl:output
elements have been merged; different output
methods may have different default values for an attribute.
Issue (more-than-one-output-value): Is it an error if an attribute of xsl:output is specified more than once, but they all have the same value? An analogy with xsl:decimal-format would suggest not. This would also seem to be the only excuse for making this a dynamic error rather than a static one.
An implementation may allow the attributes of the xsl:output
declaration
to be overridden using the API that controls the transformation.
Before a final result tree is serialized, namespace fixup is performed (see [3.5 Namespace Fixup]).
The location to which result trees are serialized (whether in filestore
or elsewhere) is implementation-defined (which in practice
may mean that it is controlled using an implementation-defined API).
However, these locations must satisfy the constraint that
any relative URI used to reference one result tree from another remains valid when
all the result trees are serialized. So, with the example in [17.2 Secondary Result Trees],
the HTML document produced by
serializing the principal result tree would contain valid references to the HTML documents
produced by serializing the result trees denoted by href="toc.html"
and
href="body.html"
respectively.
The method
attribute on the xsl:output
element
identifies the overall method that should be used for outputting the
result tree. [ERR106] The value
must be a valid QName.
If the QName does not have a prefix, then it
identifies a method specified in this document and must be one of
xml
, html
, xhtml
,
or text
. If the QName has a prefix, then the QName
is expanded into an expanded QName as described
in [4.1 Qualified Names]; the expanded-name identifies the output
method; the behavior in this case is not specified by this
document.
The default for the method
attribute is chosen as
follows. If the document node of the result tree has an element
child, and any text nodes preceding the first element child of the document
node of the result tree contain only whitespace characters, then:
If the expanded-name of this first element child has local part
html
(in lower case), and namespace URI http://www.w3.org/1999/xhtml
,
then the default output method is xhtml
.
If the expanded-name of this first element child has local part
html
(in any combination of upper and lower case) and a
null namespace URI, then the default output method is html
.
In all other cases, the default output method
is xml
.
The default output method
should be used if there are no xsl:output
elements or if
none of the xsl:output
elements specifies a value for the
method
attribute.
The other attributes on xsl:output
provide parameters
for the output method. The following attributes are allowed:
version
specifies the version of the output
method
indent
specifies whether the processor may
add additional whitespace when outputting the result tree; the value
must be yes
or no
encoding
specifies the preferred character
encoding that the processor should use to encode sequences of
characters as sequences of bytes; the value of the attribute should be
treated case-insensitively; the value must contain only characters in
the range #x21 to #x7E (i.e. printable ASCII characters); the value
should either be a charset
registered with the Internet
Assigned Numbers Authority [IANA], [RFC2278] or start with X-
media-type
specifies the media type (MIME
content type) of the data that results from outputting the result
tree; the charset
parameter should not be specified
explicitly; instead, when the top-level media type is
text
, a charset
parameter should be added
according to the character encoding actually used by the output
method
doctype-system
specifies the system identifier
to be used in the document type declaration
doctype-public
specifies the public identifier
to be used in the document type declaration
omit-xml-declaration
specifies whether the XSLT
processor should output an XML declaration; the value must be
yes
or no
standalone
specifies whether the processor
should output a standalone document declaration; the value must be
yes
or no
cdata-section-elements
specifies a list of the
names of elements whose text node children should be output using
CDATA sections
include-content-type
specifies whether the XSLT
processor should add a meta
element in HTML and XHTML output. The value must be
yes
or no
; the default is yes
escape-uri-attributes
specifies whether the processor
should escape URI-valued attributes in HTML and XHTML output using the
method recommended in [RFC2396] (section 2.4.1).
The value must be
yes
or no
; the default is yes
The detailed semantics of each attribute will be described separately for each output method for which it is applicable. If the semantics of an attribute are not described for an output method, then it is not applicable to that output method.
The xml
output method outputs the result tree as
an XML entity that should satisfy the rules for either
a well-formed XML document entity, or a
well-formed XML external general parsed entity, or both.
If the document node of
the result tree has a single element node child and no text node
children, then the serialized output should be a well-formed XML document
entity conforming to
the XML Namespaces Recommendation [XML Names].
If the result tree does not take this form, then the
serialized output should be an entity which, when
referenced within a trivial XML document
wrapper like this
<!DOCTYPE doc [ <!ENTITY e SYSTEM "entity-URI"> ]> <doc>&e;</doc>
where entity-URI
is a URI for the entity,
produces a
document which should itself be a well-formed XML document conforming to
the XML Namespaces Recommendation [XML Names].
In addition, the output should be such that if a new tree was constructed by parsing the XML document as specified in [3 Data Model], then the new tree would be the same as the result tree, with the following possible exceptions:
If the document was produced by adding a document wrapper,
as described above,
then it will contain an extra doc
element as the document element.
The order of attribute and namespace nodes in the two trees may be different.
The base URIs of nodes in the two trees may be different.
The new tree may contain additional attributes resulting from the expansion of default values in its DTD or schema.
Issue (result-tree-PSVI): The rules for serialization of the result tree consider it only as an infoset; the rules need to be enhanced to allow for (potential loss of) PSVI information on the tree.
[ERR107] It is a
serialization error
to request the output of a document type declaration, or of a
standalone
attribute, if the result tree contains
text nodes or multiple element nodes as children of the root node.
The processor may signal the error, or may recover
by ignoring the request to output a document type declaration
or standalone
attribute.
The version
attribute specifies the version of XML to
be used for outputting the result tree. If the processor does
not support this version of XML, it should use a version of XML that
it does support. The version output in the XML declaration (if an XML
declaration is output) should correspond to the version of XML that
the processor used for outputting the result tree. The value of the
version
attribute should match the VersionNum production of the XML
Recommendation [XML]. The default value is
1.0
.
The encoding
attribute specifies the preferred
encoding to use for outputting the result tree. Processors are
required to respect values of UTF-8
and
UTF-16
.
[ERR108] A serialization error
occurs when an output encoding other than UTF-8
or UTF-16
is requested,
if the implementation does not support that encoding.
The processor may
signal the error, or may recover by using UTF-8
or
UTF-16
instead.
The processor must not use an
encoding whose name does not match the EncName production of the XML
Recommendation [XML]. If no encoding
attribute is specified, then the processor should use either
UTF-8
or UTF-16
.
It is possible that the result tree will contain a character that cannot be represented in the encoding that the processor is using for output. In this case, if the character occurs in a context where XML recognizes character references (i.e. in the value of an attribute node or text node), then the character should be output as a character reference. [ERR109] A serialization error occurs if such a character appears in a context where character references are not allowed (for example if the character occurs in the name of an element). The processor should signal the error.
If the indent
attribute has the value
yes
, then the xml
output method may output
whitespace in addition to the whitespace in the result tree (possibly
based on whitespace stripped from either the source document or the
stylesheet) in order to indent the result nicely; if the
indent
attribute has the value no
, it should
not output any additional whitespace. The default value is
no
. The xml
output method should use an
algorithm to output additional whitespace that ensures that the result
if whitespace were to be stripped from the output using the process
described in [3.4 Whitespace Stripping] with the set of
whitespace-preserving elements consisting of just
xsl:text
would be the same when additional whitespace is
output as when additional whitespace is not output.
NOTE: It is usually not safe to use indent="yes"
with
document types that include element types with mixed content.
The cdata-section-elements
attribute contains a
whitespace-separated list of QNames. Each QName is expanded into an
expanded-name using the namespace declarations in effect on the
xsl:output
element in which the QName occurs; if there is a default
namespace, it is used for QNames
that do not have a prefix. The expansion is performed before the
merging of multiple xsl:output
elements into a single
effective xsl:output
element. If the expanded-name of the
parent of a text node is a member of the list, then the text node
should be output as a CDATA section. For example,
<xsl:output cdata-section-elements="example"/>
would cause a literal result element written in the stylesheet as
<example><foo></example>
or as
<example><![CDATA[<foo>]]></example>
to be output as
<example><![CDATA[<foo>]]></example>
If the text node contains the sequence of characters
]]>
, then the currently open CDATA section should be
closed following the ]]
and a new CDATA section opened
before the >
. For example, a literal result element
written in the stylesheet as
<example>]]></example>
would be output as
<example><![CDATA[]]]]><![CDATA[>]]></example>
If the text node contains a character that is not representable in the character encoding being used to output the result tree, then the currently open CDATA section should be closed before the character, the character should be output using a character reference or entity reference, and a new CDATA section should be opened for any further characters in the text node.
CDATA sections should not be used except where they have been
explicitly requested by the user, either by using the
cdata-section-elements
attribute,
or by using some other implementation-defined mechanism.
NOTE: This is phrased to permit an implementor to provide an option that attempts to preserve CDATA sections present in the source document.
The xml
output method should output an XML declaration
unless the omit-xml-declaration
attribute has the value
yes
. The XML declaration should include both version
information and an encoding declaration. If the
standalone
attribute is specified, it should include a
standalone document declaration with the same value as the value as
the value of the standalone
attribute. Otherwise, it
should not include a standalone document declaration; this ensures
that it is both an XML
declaration (allowed at the beginning of a document entity) and a text
declaration (allowed at the beginning of an external general parsed
entity).
The omit-xml-declaration
attribute
should be ignored if the standalone
attribute is present, or if
the encoding
attribute specifies a value other than UTF-8 or UTF-16.
If the doctype-system
attribute is specified, the
xml
output method should output a document type
declaration immediately before the first element. The name following
<!DOCTYPE
should be the name of the first element. If
doctype-public
attribute is also specified, then the
xml
output method should output PUBLIC
followed by the public identifier and then the system identifier;
otherwise, it should output SYSTEM
followed by the system
identifier. The internal subset should be empty. The
doctype-public
attribute should be ignored unless the
doctype-system
attribute is specified.
The media-type
attribute is applicable for the
xml
output method. The default value for the
media-type
attribute is text/xml
.
The xhtml
output method serializes the result
tree as XML, using the HTML compatibility guidelines defined in
the XHTML specification.
It is entirely the responsibility of the stylesheet author to ensure that the result tree conforms to the [XHTML] specification. It is not an error if the result tree is invalid XHTML.
The serialization of the result tree follows the same rules
as for the xml
output method, with the exceptions noted
below. These differences are based on the HTML compatibility guidelines
published in Appendix C of [XHTML], which are
designed to ensure that as far as possible, XHTML is rendered correctly on
user agents designed originally to handle HTML.
The serializer should include a space before the trailing
/
and >
of empty elements,
e.g. <br />
, <hr />
and
<img src="karen.jpg" alt="Karen" />
.
Also, the serializer should use the minimized tag syntax for empty elements,
e.g. <br />
, as the alternative syntax
<br></br>
allowed by XML gives uncertain results
in many existing user agents.
Given an empty instance of an element whose content model is not EMPTY
(for example, an empty title or paragraph)
the serializer should not use the minimized form (e.g. use <p> </p>
and not <p />
).
The serializer should avoid outputting line breaks and multiple whitespace characters within attribute values. These are handled inconsistently by user agents.
If there is a head
element, then
unless the include-content-type
attribute is present and has the value "no"
,
the
xhtml
output method should add a meta
element
immediately after the start-tag of the head
element
specifying the character encoding actually used. For example,
<head> <meta http-equiv="Content-Type" content="text/html; charset=EUC-JP"> ...
The content type should be set to
the value given for the media-type
attribute;
the default value for XHTML 1.0 is text/html
.
Unless the escape-uri-attributes
attribute
is present and has the value no
, the html
output method should escape non-ASCII
characters in URI attribute values using the method recommended in
[RFC2396] (section 2.4.1).
The html
output method outputs the result tree as
HTML; for example,
<xsl:stylesheet version="2.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> <xsl:output method="html"/> <xsl:template match="/"> <html> <xsl:apply-templates/> </html> </xsl:template> ... </xsl:stylesheet>
The version
attribute indicates the version of the
HTML. The default value is 4.0
, which specifies that the
result should be output as HTML conforming to the HTML 4.0
Recommendation [HTML].
The html
output method should not output an element
differently from the xml
output method unless the
expanded-name of the element has a null namespace URI; an element
whose expanded-name has a non-null namespace URI should be output as
XML. If the expanded-name of the element has a null namespace URI,
but the local part of the expanded-name is not recognized as the name
of an HTML element, the element should output in the same way as a
non-empty, inline element such as span
.
The html
output method should not output an end-tag
for empty elements. For HTML 4.0, the empty elements are
area
, base
, basefont
,
br
, col
, frame
,
hr
, img
, input
,
isindex
, link
, meta
and
param
. For example, an element written as
<br/>
or <br></br>
in the
stylesheet should be output as <br>
.
The html
output method should recognize the names of
HTML elements regardless of case. For example, elements named
br
, BR
or Br
should all be
recognized as the HTML br
element and output without an
end-tag.
The html
output method should not perform escaping for
the content of the script
and style
elements. For example, a literal result element written in the
stylesheet as
<script>if (a < b) foo()</script>
or
<script><![CDATA[if (a < b) foo()]]></script>
should be output as
<script>if (a < b) foo()</script>
The html
output method should not escape
<
characters occurring in attribute values.
If the indent
attribute has the value
yes
, then the html
output method may add or
remove whitespace as it outputs the result tree, so long as it does
not change how an HTML user agent would render the output. The
default value is yes
.
Unless the escape-uri-attributes
attribute
is present and has the value no
, the html
output method should escape non-ASCII
characters in URI attribute values using the method recommended in
[RFC2396] (section 2.4.1).
The html
output method may output a character using a
character entity reference, if one is defined for it in the version of
HTML that the output method is using.
The html
output method should terminate processing
instructions with >
rather than
?>
.
The html
output method should output boolean
attributes (that is attributes with only a single allowed value that
is equal to the name of the attribute) in minimized form. For example,
a start-tag written in the stylesheet as
<OPTION selected="selected">
should be output as
<OPTION selected>
The html
output method should not escape a
&
character occurring in an attribute value
immediately followed by a {
character (see Section
B.7.1 of the HTML 4.0 Recommendation). For example, a start-tag
written in the stylesheet as
<BODY bgcolor='&{{randomrbg}};'>
should be output as
<BODY bgcolor='&{randomrbg};'>
The encoding
attribute specifies the preferred
encoding to be used. If there is a HEAD
element, then
unless the include-content-type
attribute is present and has the value "no"
,
the
html
output method should add a META
element
immediately after the start-tag of the HEAD
element
specifying the character encoding actually used. For example,
<HEAD> <META http-equiv="Content-Type" content="text/html; charset=EUC-JP"> ...
The content type should be set to
the value given for the media-type
attribute;
the default value is text/html
.
[ERR110] It is possible that the result tree
will contain a character that
cannot be represented in the encoding that the processor is using
for output. In this case, if the character occurs in a context where
HTML recognizes character references, then the character should be
output as a character entity reference or decimal numeric character
reference; otherwise (for example, in a
script
or style
element or in a comment),
the processor should signal a
serialization error.
If the doctype-public
or doctype-system
attributes are specified, then the html
output method
should output a document type declaration immediately before the first
element. The name following <!DOCTYPE
should be
HTML
or html
. If the
doctype-public
attribute is specified, then the output
method should output PUBLIC
followed by the specified
public identifier; if the doctype-system
attribute is
also specified, it should also output the specified system identifier
following the public identifier. If the doctype-system
attribute is specified but the doctype-public
attribute
is not specified, then the output method should output
SYSTEM
followed by the specified system identifier.
The media-type
attribute is applicable for the
html
output method. The default value is
text/html
.
The text
output method outputs the result tree by
outputting the string-value of every text node in the result tree in
document order without any escaping.
The media-type
attribute is applicable for the
text
output method. The default value for the
media-type
attribute is text/plain
.
The encoding
attribute identifies the encoding that
the text
output method should use to convert sequences of
characters to sequences of bytes. The default is system-dependent.
[ERR111] If
the result tree contains a character that cannot be represented in the
encoding that the processor is using for output, the implementation
should signal a serialization error.
Normally, the xml
output method escapes &
and <
(and possibly other characters) when outputting text nodes. This
ensures that the output is well-formed XML. However, it is sometimes
convenient to be able to produce output that is almost, but not quite
well-formed XML; for example, the output may include ill-formed
sections which are intended to be transformed into well-formed XML by
a subsequent non-XML-aware process. For this reason, XSLT provides a
mechanism for disabling output escaping. An xsl:value-of
or xsl:text
element may have a
disable-output-escaping
attribute; the allowed values are
yes
or no
; the default is no
;
if the value is yes
, then a text node generated by
evaluating the xsl:value-of
or xsl:text
element should be output without any escaping. For example,
<xsl:text disable-output-escaping="yes"><</xsl:text>
should generate the single character <
.
[ERR112] It is a dynamic error for
output escaping to be disabled for a text node
that is used for something other than a text node in the result tree.
Thus, it is an error to disable output escaping for an
xsl:value-of
or xsl:text
element that is
used to generate the string-value of a comment, processing instruction
or attribute node; it is also a
dynamic error to convert a node to a
number or a string if the node is, or contains, a text node for which escaping
was disabled. In both cases, the processor must either signal the error,
of must recover by ignoring the
disable-output-escaping
attribute.
When a text node is copied, either by
using xsl:copy
or by applying
xsl:copy-of
to that node or one of its ancestors, and when
escaping was disabled for some or all of the characters within that text node,
then escaping should also be disabled for the resulting copy of those characters.
For example
<xsl:variable name="x"> <xsl:text disable-output-escaping="yes"><</xsl:text> </xsl:variable> <xsl:copy-of select="$x"/>
should output <
not
<
.
Text nodes for which escaping is disabled are subject to merging with text nodes that are adjacent in the result tree in the same way as text nodes for which is escaping is not disabled. An element or document node in the result tree never has two consecutive text node children. Thus, it is possible for escaping to be disabled for some but not all of the characters in a text node.
The disable-output-escaping
attribute may be used with
the html
output method as well as with the
xml
output method. The text
output method
ignores the disable-output-escaping
attribute, since it
does not perform any output escaping.
A processor will only be able to disable output escaping if
it controls how the result tree is output. This might not always be the
case. For example, the result tree might be used as the source tree for
another XSLT transformation instead of being output. An implementation
is not required to support disabling output escaping.
[ERR113] It is
a serialization error
if an
xsl:value-of
or xsl:text
instruction specifies that
output escaping should be disabled and the implementation does not
support this. The processor must either signal the error,
of must recover by not disabling output escaping.
[ERR114] It is a serialization error if output escaping is disabled for a character that is not representable in the encoding that the processor is using for output. The processor must either signal the error, of must recover by not disabling output escaping.
Since disabling output escaping might not work with all implementations and can result in XML that is not well-formed, it should be used only when there is no alternative.
A conforming processor must be able to use a stylesheet to transform source trees into result trees as specified in this document. A conforming processor need not be able to serialize the result in XML or in any other form.
NOTE: Implementations are strongly encouraged to provide a way to verify that the processor is behaving conformingly by allowing result trees to be output as XML or by providing access to result trees through a standard API such as the DOM or SAX.
A conforming processor must signal any errors except for those that this document specifically allows a processor not to signal. A conforming processor may continue after signaling an error, but if it does so, it must either take the recovery action defined in this document, or it must eventually terminate without producing a result tree.
However, a processor will not be considered as failing to conform to this specification solely because it implements constructs that are introduced in a later version of this specification.
NOTE: This means that a processor that implements all of version 2.0 and a few features of version 3.0 can claim conformance with XSLT 2.0. This differs from the situation with XSLT 1.0, where implementing selected XSLT 2.0 constructs makes a processor technically non-conformant with XSLT 1.0.
A conforming processor may impose limits on the processing resources consumed by the processing of a stylesheet.
The specification of each XSLT-defined element type is preceded by a summary of its syntax in the form of a model for elements of that element type. The meaning of syntax summary notation is as follows:
An attribute is required if and only if its name is in bold.
The string that occurs in the place of an attribute value
specifies the allowed values of the attribute. If this is surrounded
by curly braces, then the attribute value is treated as an
attribute value template,
and the string occurring within curly braces specifies the allowed
values of the result of evaluating the attribute value template.
Alternative allowed values are separated by |
. A quoted
string indicates a value equal to that specific string. An unquoted,
italicized name specifies a particular type of value.
If the element is allowed not to be empty, then the element contains a comment specifying the allowed content. The allowed content is specified in a similar way to an element type declaration in XML; template means that any mixture of text nodes, literal result elements, extension instructions, and XSLT elements from the instruction category is allowed; top-level-elements means that any mixture of XSLT elements from the declaration category is allowed, together with user-defined data elements.
The element is prefaced by comments indicating if it belongs
to the instruction
category or
declaration
category or both. The category of an
element just affects whether it is allowed in the content of elements
that allow a content constructor or
top-level-elements.
[ERR115] A static error is signaled if an XSLT-defined element is used in a context where it is not permitted, if a required attribute is omitted, or if the content of the element does not correspond to the content that is allowed for the element. [ERR116] It is a static error if an attribute (other than an attribute written using curly braces in a position where an attribute value template is permitted) contains a value that is not one of the permitted values for that attribute. [ERR117] It is a dynamic error if the effective value of an attribute written using curly braces, in a position where an attribute value template is permitted, is a value that is not one of the permitted values for that attribute.
Special rules apply if the construct appears in part of the stylesheet that is processed with forwards-compatible behavior: see [2.7 Forwards-Compatible Processing].
alias | A stylesheet can use the
| |
allowable | What namespace nodes are added and where they are added by namespace fixup is implementation-dependent, provided that the resulting tree satisfies the constraints and provided that all namespaces nodes in the resulting tree are allowable, where a namespace node is allowable for an element E if any of the following conditions applies: | |
attribute value template | In an
attribute that is designated as an
attribute value template, such as an attribute of a
literal result element,
an expression can be used by surrounding
the expression with curly braces ( | |
circularity | If the expression or content constructor specifying the value of a global variable X references a global variable Y, then the value for Y must be computed before the value of X. If it is impossible to do this for all global variable definitions, then a circularity is said to exist. | |
content constructor | A content constructor is a sequence of nodes in the stylesheet that, when evaluated, constructs and returns a sequence of new nodes suitable for adding to the result tree. | |
context document | The context document
is the source document currently being processed. This is initially set to the document
node of the principal source document.
It changes
when instructions such as | |
context item | The context item is the item currently
being processed. An item (see [Data Model]) is either a simple value (such as an
integer, date, or string), or a node. If the context item is a node, then it will always be
a node in the context document. The initial context node is the same as the context document.
It changes
whenever instructions such as | |
context node | If the context item is a node (as distinct from a simple value such as an integer), then it is also referred to as the context node. The context node is not an independent variable, it changes whenever the context item changes. When the context item is a simple value, there is no context node: its value is an empty sequence. | |
context position | The context position is the position of
the context item within the sequence of items currently being processed. It changes whenever the
context item changes. When an instruction such as | |
context size | The context size is the number of items in
the sequence of items currently being processed. It changes
whenever instructions such as | |
current group | The evaluation context for
XPath expressions includes an additional value
called the current group, which is a sequence. The current group is the collection of
related items that are processed collectively in one iteration of the | |
current result tree | When a content constructor is evaluated to create new nodes, the tree to which these nodes are added is referred to as the current result tree | |
current template rule | At any point in the processing
of a stylesheet, there may be a
current template rule. Whenever a template rule is
chosen by matching a pattern, the template rule becomes the current
template rule for the evaluation of the rule's content constructor. When an
| |
declaration | Top-level elements fall into two categories: declarations, and user-defined data elements. Top-level elements whose names are in the XSLT namespace are declarations. Top-level elements in any other namespace are user-defined data elements (see [2.4.1 User-defined Data Elements]) | |
declaration order | The
declarations within a
stylesheet level have a total ordering known
as declaration order. The order of declarations within a stylesheet
level is the same as the document order that would result if each stylesheet module were
inserted textually in place of the | |
default priority | If no | |
dynamic error | An error that is not detected until a source document is being transformed is referred to as a dynamic error. | |
effective value | The result of evaluating an attribute value template is referred to as the effective value of the attribute. | |
embedded stylesheet module | an
embedded stylesheet module
consists of an | |
expanded QName | An expanded QName is a pair of values containing a namespace URI and a local name. A QName is expanded by replacing the namespace prefix with the corresponding namespace URI, from the namespace declarations that are in scope at the point where the QName is written. Two expanded QNames are equal if the namespace URIs are the same and the local names are the same. | |
expression | An expression must match the XPath production Expr. | |
extension function | An
extension function is a function that is available for
use within an XPath expression, other than a core function defined
in the XPath specification, an additional function defined in this
XSLT specification, or a stylesheet
function defined using an | |
extension instruction | An extension instruction is an element within a content constructor that is in a namespace (not the XSLT namespace) designated as an extension namespace | |
extension namespace | The extension instruction mechanism allows namespaces to be designated as extension namespaces. When a namespace is designated as an extension namespace and an element with a name from that namespace occurs in a content constructor, then the element is treated as an instruction rather than as a literal result element. | |
external object | Support for extension functions introduces an additional data-type into the expression language. This additional data type is called an external object. A variable may be bound to an object of type external object instead of one of the XPath data-types. An external object represents an object that is not convertible to one of the XPath data types, which is created by an external programming language and returned by an extension function. Expressions can only return values of type external object by referencing variables of type external object or calling extension functions that return an external object. | |
focus | When a content constructor is evaluated, the processor keeps track of which nodes are being processed by means of a set of implicit variables referred to collectively as the focus. | |
forwards-compatible behavior | An element enables
forwards-compatible behavior for itself, its
attributes, its descendants and their attributes if it has an
| |
group | The | |
grouping key | The result
of evaluating the | |
implementation | A specific product that performs the functions of an XSLT processor is referred to as an implementation | |
import precedence | A declaration D in the stylesheet is defined to have lower import precedence than another declaration E if the stylesheet level containing D would be visited before the stylesheet level containing E in a post-order traversal of the import tree (that is, a traversal of the import tree in which a stylesheet level is visited after its children). Two declarations within the same stylesheet level have the same import precedence. | |
import tree | The
stylesheet levels
making up a stylesheet are
treated as forming an import tree. In the import tree,
each stylesheet level has one child for each
| |
initial sequence | The sequence to be sorted is referred to as the initial sequence. | |
instruction | The elements occurring within a content constructor are classified as being either literal result elements or instructions. If the element is in the XSLT namespace, or in a namespace designated as an extension namespace, then it is an instruction. Otherwise, it is a literal result element. | |
literal namespace URI | 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. | |
literal result element | In a content constructor, an element in the stylesheet that does not belong to the XSLT namespace and that is not an extension instruction (see [16.2 Extension Instructions]) is classified as a literal result element. | |
mode | Modes allow a node in the source tree to be processed multiple times, each time producing a different result. They also allow different sets of template rules to be active when processing different trees, for example when processing documents loaded using the document function (see [14.1 Multiple Source Documents]) or when processing temporary trees (see [6 Variables and Parameters]) | |
named sort specification | A
named sort specification is defined
by an | |
named template | Templates can be invoked by name.
An | |
namespace fixup | The process of namespace fixup modifies a tree by adding namespace nodes so that it satisfies all constraints affecting namespace nodes. | |
order of first appearance | There is an ordering among groups referred to as the order of first appearance. A group G is defined to precede a group H in order of first appearance if the initial item of G precedes the initial item of H in population order. | |
output definition | All
the | |
pattern | A pattern specifies a set of conditions on a node. A node that satisfies the conditions matches the pattern; a node that does not satisfy the conditions does not match the pattern. The syntax for patterns is a subset of the syntax for expressions. | |
picture string | The formatting of a number is controlled by a picture string. The picture string is a sequence of characters, in which the characters assigned to the variables decimal-separator-sign, grouping-sign, percent-sign, per-mille-sign, zero-digit-sign, digit-sign and pattern-separator-sign are classified as active characters, and all other characters are classified as passive characters. | |
place marker | The
| |
population | The sequence of items
to be grouped, which
is referred to as the population,
is determined by evaluating the XPath expression contained in the
| |
population order | The population is treated as a sequence; the order of items in this sequence is referred to as population order | |
principal result tree | When the transformation is initiated, a result tree is created, and becomes the current result tree. This tree is referred to as the principal result tree | |
principal source document | The transformation process takes as its main input a source tree referred to as the principal source document | |
principal stylesheet module | A
stylesheet may consist of several stylesheet modules,
contained in different XML documents. One of these functions as the
principal stylesheet module. The complete stylesheet is
assembled by finding the stylesheet modules referenced
directly or indirectly from the
principal stylesheet module using | |
processor | The software responsible for transforming a source document into a result document is referred to as the processor. This is sometimes expanded to XSLT processor to avoid any confusion with other processors, for example an XML processor. | |
QName | A QName is
always written in the form | |
required type | The context within a stylesheet where an XPath expression may appear determines the required type of the expression. The required type indicates the data type of value that the expression is expected to return. | |
serialization | A frequent requirement is to output the result tree as an XML document (or in other formats such as HTML). This process is referred to as serialization. | |
serialization error | If a transformation has successfully produced a result tree, it is still possible that errors may occur in serializing the result tree. For example, it may be impossible to serialize the result tree using the encoding selected by the user. Such an error is referred to as a serialization error. | |
shadows | A binding shadows another binding if the binding occurs at a point where the other binding is visible, and the bindings have the same name. | |
simplified stylesheet module | a simplified stylesheet module is an XML document whose document element is a literal result element (see [2.5 Simplified Stylesheet Modules]), which contains embedded XSLT instructions. | |
singleton focus | A singleton focus based on a node N has the context item (and therefore the context node) set to N, the context document set to the document containing N, and the context position and context size both set to 1 (one). | |
sort key | For each item in the initial sequence, a value is computed for each sort key definition within the sort specification. The value computed for an item by using the Nth sort key definition is referred to as the Nth sort key of that item. | |
sort key definition | Within a
sort specification, each
| |
sort specification | A
sort specification
is a sequence of one or more adjacent | |
sorted sequence | The sequence after sorting
as defined by the | |
standard attributes | There are a number of
standard attributes that may appear on any XSLT element: specifically
| |
standard stylesheet module | a
standard stylesheet module is an XML document
having an | |
static error | An error that is detected by examining a stylesheet before execution starts (that is, before the source document and values of stylesheet parameters are available) is referred to as a static error. | |
stylesheet | A transformation in the XSLT language is expressed in the form of a stylesheet, whose syntax is well-formed XML [XML] conforming to the Namespaces in XML Recommendation [XML Names]. | |
stylesheet function | An | |
stylesheet level | A stylesheet level
is a collection of stylesheet modules connected
using | |
stylesheet module | A stylesheet consists of one or more stylesheet modules, each one forming all or part of a well-formed XML document. | |
template rule | A stylesheet contains a set of template rules. A template rule has two parts: a pattern which is matched against nodes in the source tree and a content constructor which is evaluated to produce a sequence of nodes: these nodes are typically used to form part of the result tree. | |
If a variable-binding element has no | ||
top-level | An element occurring as
a child of an | |
type errors | Certain errors are classified as type errors. A type error occurs when the value supplied as input to an operation is of the wrong type for that operation, for example when an integer is supplied to an operation that expects a node. | |
user-defined data element | In addition to
declarations,
the | |
value | The value to which a variable is bound (the value of the variable) can be an object of any of the types that can be returned by expressions. | |
variable-binding element | The
two elements | |
XSLT namespace | The XSLT namespace
has the URI |
The syntax of each XSLT element is summarized below, together with the context in the stylesheet where the element may appear. Some elements (specifically, instructions) are allowed as a child of any element that is allowed to contain a content constructor. These elements are:
xsl:attribute
xsl:comment
xsl:copy
xsl:element
xsl:fallback
xsl:for-each
xsl:for-each-group
xsl:if
xsl:message
xsl:namespace
xsl:otherwise
xsl:param
xsl:processing-instruction
xsl:result
xsl:result-document
xsl:template
xsl:text
xsl:variable
xsl:when
xsl:with-param
Category: instruction Model:
Permitted parent elements:
|
Category: instruction Model:
Permitted parent elements:
|
Category: instruction Model:
Permitted parent elements:
|
Category: declaration Model:
Permitted parent elements:
|
Category: instruction Model:
Permitted parent elements:
|
Category: instruction Model:
Permitted parent elements:
|
Category: instruction Model:
Permitted parent elements:
|
Category: instruction Model:
Permitted parent elements:
|
Category: instruction Model:
Permitted parent elements:
|
Category: declaration Model:
Permitted parent elements:
|
Category: declaration Model:
Permitted parent elements:
|
Category: instruction Model:
Permitted parent elements:
|
Category: instruction Model:
Permitted parent elements:
|
Category: instruction Model:
Permitted parent elements:
|
Category: instruction Model:
Permitted parent elements:
|
Category: declaration Model:
Permitted parent elements:
|
Category: instruction Model:
Permitted parent elements:
|
Category: declaration Model:
Permitted parent elements:
|
Category: declaration Model:
Permitted parent elements:
|
Category: declaration Model:
Permitted parent elements:
|
Category: instruction Model:
Permitted parent elements:
|
Category: instruction Model:
Permitted parent elements:
|
Category: declaration Model:
Permitted parent elements:
|
Category: instruction Model:
Permitted parent elements:
|
Model:
Permitted parent elements:
|
Category: declaration Model:
Permitted parent elements:
|
Category: declaration Model:
Permitted parent elements:
|
Category: declaration Model:
Permitted parent elements:
|
Category: instruction Model:
Permitted parent elements:
|
Model:
Permitted parent elements:
|
Category: instruction Model:
Permitted parent elements:
|
Model:
Permitted parent elements:
|
Category: declaration Model:
Permitted parent elements:
|
Category: declaration Model:
Permitted parent elements:
|
Model:
Permitted parent elements:
|
Category: declaration Model:
Permitted parent elements:
|
Category: instruction Model:
Permitted parent elements:
|
Model:
Permitted parent elements:
|
Category: instruction Model:
Permitted parent elements:
|
Category: declaration Model:
Permitted parent elements:
|
Model:
Permitted parent elements:
|
Model:
Permitted parent elements:
|
This appendix provides a summary of error conditions that a processor may signal. This list is not exhaustive or definitive. The errors are numbered for ease of reference, but there is no implication that an implementation should report errors using these error codes, or that applications can test for these codes. Moreover, implementations are not required to report errors using the descriptive text used here.
Static errors
It is a static error for an element from the XSLT namespace to have an attribute with an expanded-name that has a null namespace URI (i.e. an attribute with an unprefixed name) other than attributes defined for the element in this document. | |
An | |
The value of the version attribute
[of the | |
An | |
It is a static error
if the | |
A user-defined data element
must not precede an | |
A literal result element that
is the document element of a
simplified stylesheet module must have
an | |
The | |
It is an static error if a stylesheet module directly or indirectly includes itself. | |
The | |
The
| |
It is a static error if a stylesheet module directly or indirectly imports itself. | |
Within an XSLT element that is required to be empty,
any content other than comments or processing instructions, including any whitespace-only
text node preserved using the | |
In the case of a QName used as the value of an attribute in the stylesheet, or appearing within the text of an XPath expression in the the stylesheet, it is a static error if the defining element has no namespace node whose name matches the prefix of the QName. | |
It is a static error if the value of such an attribute, or the text between curly braces in an attribute value template, does not match the XPath production Expr, or if it fails to satisfy other static constraints defined in the XPath specification, for example that all variable references must refer to variables that are in scope. | |
Where an attribute is defined to contain a pattern, it is a static error if the pattern does not match the production Pattern. | |
It is a static error if a left curly brace appears in an attribute value template without a matching right curly brace. | |
It is a static error if the string contained between matching curly braces in an attribute value template does not match the XPath production Expr. | |
It is a static error if a right curly brace occurs in an attribute value template outside an expression without being followed by a second right curly brace. | |
The value of this
[the | |
If an | |
If an | |
If the variable-binding element has a | |
It is a static error if a stylesheet contains more than one binding of a global variable with the same name and same import precedence. | |
It is a static error if a stylesheet contains more than one template with the same name and same import precedence. | |
A stylesheet function must have a prefixed name, to remove any risk of a clash with a system-defined function. It is a static error if the name has no prefix. | |
It is a static error for a stylesheet to contain two or more functions with the same expanded QName and the same import precedence, unless there is another function with the same expanded QName and a higher import precedence. | |
When used within | |
It is a static error for a stylesheet to contain two or more named sort specifications with the same expanded QName and the same import precedence, unless there is another named sort specification with the same expanded QName and a higher import precedence. | |
The current-group function must not be used within a pattern. | |
These three attributes
[the | |
It is a static error for
the value of either the | |
It is a static error to declare either the default decimal-format or a decimal-format with a given name more than once (even with different import precedence), unless it is declared every time with the same value for all attributes (taking into account any default values). | |
It is a static error if, for any named or unnamed decimal format, the variables representing characters used in a picture string do not each have distinct values. These variables are decimal-separator-sign, grouping-sign, percent-sign, per-mille-sign, digit-zero-sign, digit-sign, and pattern-separator-sign. | |
It is a static error to use the current function in a pattern. | |
It
is a static error
if there is no namespace bound to the prefix on the
element bearing the | |
It is a static error if the
value of the | |
It is a static error if
there is more than one | |
It is a static error if the
value of the | |
A static error is signaled if an XSLT-defined element is used in a context where it is not permitted, if a required attribute is omitted, or if the content of the element does not correspond to the content that is allowed for the element. | |
It is a static error if an attribute (other than an attribute written using curly braces in a position where an attribute value template is permitted) contains a value that is not one of the permitted values for that attribute. |
Type errors
It is a
type error
if an XPath expression contains a type error, or if the type
of the XPath expression is incompatible with the
required type.
| |
If the | |
If the |
Dynamic errors
If the value
[returned by an XPath expression with backwards-compatible behavior]
is an empty sequence or a sequence that consists entirely of nodes,
then it is converted to a node-set; it is a dynamic error
if the value is any other sequence of two or more items.
| |
If an implementation does not support backwards-compatible
behavior, then it is a dynamic error
if any element is evaluated that enables
backwards-compatible behavior.
| |
It is an dynamic error if
this [the process of finding an | |
It is a dynamic error if
such a document [a source document, a document returned by the document
or by an extension function, or supplied as a stylesheet parameter] does
not already
satisfy the constraints listed above [in summary, that the namespace nodes
on the tree are consistent with those produced by parsing a well-formed document
conforming to the XML Namespaces Recommendation] .
| |
In the case of a QName produced by evaluating an XPath expression, it is a dynamic error if the defining element has no namespace node whose name matches the prefix of the QName. The error is a dynamic error even if the value of the expression is known statically, for example if the QName is written as a string literal. | |
It is a dynamic error for
an expression to call any function that is not included in the in-scope functions.
| |
It is an
dynamic error
if an extension instruction
attempts to return a sequence containing a document node.
| |
It is a dynamic error if
the result sequence [returned by a content constructor]
(after concatenating the results of individual instructions) contains a namespace node that is preceded
in the sequence by a node that is not a namespace node.
| |
It is a dynamic error if the
result sequence [returned by a content constructor]
(after concatenating the results of individual instructions) contains an attribute node that is preceded
in the sequence by a node that is neither a namespace node nor an attribute node.
| |
Elements such as | |
It is a dynamic error to add
a namespace node to an element if the
element already has a namespace node with the same name, unless both
namespace nodes have the same string-value, in which case
the duplicate is ignored. It is also a
dynamic error to add a namespace node to an
element if the namespace node has a null name and the element has a
null namespace URI. | |
It is a dynamic error
if the result sequence [produced by the | |
It is a dynamic error if
[ | |
It is a dynamic error if
the sequence returned by the | |
It is a dynamic error if
this [the conflict resolution algorithm for template rules]
leaves more than one matching template
rule. | |
It is an error if the | |
It is a dynamic error if
| |
In general, a circularity
in a stylesheet is a dynamic error.
| |
It is a
dynamic error if use
of | |
It
is a dynamic error if there
are two attribute sets that have the same
expanded-name and equal import precedence and that both contain
the same attribute, unless there is a definition of the attribute set
with higher import
precedence that also contains the attribute. | |
It is an static error if there are
more arguments supplied in the function call than
there are | |
It is
a dynamic error if there is more
than one such declaration [more than one | |
It is an dynamic error if
the effective value [of the | |
It is a dynamic error if
the effective value
[of the | |
It is a dynamic error if the
effective value of the
| |
It is a dynamic error if
the result of evaluating the content of the
| |
It is a dynamic error if the
effective value of the
| |
It is an dynamic error if
evaluating the content of
| |
It is a dynamic error if
the result of evaluating the content of the
| |
When the context item is an attribute node, then if it would be a
dynamic error
to use | |
It is a dynamic error
if any item in the sequence [supplied as the value of the | |
It is a
dynamic error if the
| |
The target data type for each | |
It
is a dynamic error if any value obtained by
evaluating the | |
It is a
dynamic error if, for any
sort key definition,
the set of sort keys evaluated for all the items in the
initial sequence, after any type conversion requested,
contains a pair of values for which the result of the
XPath | |
It is a dynamic error if
the effective value
of the | |
It is a
dynamic error if the first argument of the sort
function does not match the name of any named sort specification in the stylesheet.
| |
It is a dynamic error if the
result of evaluating the | |
It is a
dynamic error if
arg2 [the second argument to
the document function] is an empty sequence,
or a sequence whose first item is not a node,
unless all the URIs in arg1 are absolute URIs;
| |
An
error retrieving the resource [identified by the document
function] , is classed as a
dynamic error.
| |
An
error in processing the fragment identifier [contained in a URI reference passed to the
document function] is classed as a
dynamic error;
| |
It is a dynamic error
if a URI
[supplied in the first argument to the unparsed-text function]
cannot be used to retrieve a resource containing text.
| |
It is a dynamic error
if a resource
[retrieved using the unparsed-text function]
contains characters that are not valid XML characters.
| |
It is a dynamic error
if a resource
[retrieved using the unparsed-text function]
contains bytes that cannot be decoded into valid XML characters
using the specified encoding. This includes the case where the
processor does not support
the requested encoding.
| |
It is a dynamic error
if the second argument of the unparsed-text function is omitted and the
processor cannot infer the encoding using
external information. | |
It is a dynamic error
if evaluating either the | |
It is a
dynamic error if the value
[of the first argument to the key function] is
not a valid QName, or if there is no
namespace declaration in scope for the prefix of the QName, or if the
name obtained by expanding the QName is not the same as the expanded
name of any key declaration in the stylesheet. | |
It is a
dynamic error if the stylesheet
does not contain a declaration of the decimal-format with the
expanded QName specified as the
third argument [ to the format-number function] .
| |
The picture string
[supplied to the format-number function]
must conform to the following rules [see full specification] .
It is a dynamic error if the picture string
does not satisfy these rules. | |
It is a
dynamic error if
the current function is called while
evaluating a pattern. | |
It is a dynamic
error if value of the argument
[to the generate-id]
is a sequence other than an empty sequence or a sequence containing a single
node. | |
It is a
dynamic error if the value
[supplied as the first argument to the
system-property function] is
not a valid QName, or if there is no
namespace declaration in scope for the prefix of the QName.
| |
It is a dynamic error
if the argument
[passed to the function-available function]
does not evaluate to a string that is a valid QName,
or if there is no namespace declaration in scope for the prefix of the QName.
| |
It is a dynamic error if
a FunctionCall within an XPath expression
is evaluated, when the function in question is not available.
| |
It is a dynamic
error if the arguments supplied to a call on an extension function do
not satisfy the rules defined for that particular extension function, or if the
extension function reports an error, or if the result of the extension function
cannot be converted to an XPath value. | |
It is a dynamic error
to attempt to copy an external object to a result tree, or to convert it
(implicitly or explicitly) to any of the XPath data types.
| |
It is a dynamic error
if the argument
[passed to the element-available function]
does not evaluate to a string that is a valid QName,
or if there is no namespace declaration in scope for the prefix of the QName.
| |
It is a dynamic
error to evaluate the | |
It is a dynamic
error for a transformation to generate two or more result trees with the same URI.
| |
It is a dynamic error
if the value of an attribute [of the | |
It is a
dynamic error
if two | |
It is a dynamic error for
output escaping to be disabled for a text node
that is used for something other than a text node in the result tree.
Thus, it is an error to disable output escaping for an
| |
It is a dynamic error if the effective value of an attribute written using curly braces, in a position where an attribute value template is permitted, is a value that is not one of the permitted values for that attribute. |
Serialization errors
The value
[of the | |
It is a
serialization error
to request the output of a document type declaration, or of a
| |
A serialization error
occurs when an output encoding other than | |
A serialization error
occurs if such a character
[a character that cannot be represented in the
encoding that the processor is using for output]
appears in a context where character references are not allowed
(for example if the character occurs in the name of an element).
| |
It is possible that the result tree
will contain a character that
cannot be represented in the encoding that the processor is using
for output. In this case, if the character occurs in a context where
HTML recognizes character references, then the character should be
output as a character entity reference or decimal numeric character
reference; otherwise (for example, in a
| |
If the result tree contains a character that cannot be represented in the encoding that the processor is using for output, the implementation should signal a serialization error. | |
It is
a serialization error
if an
| |
It is
a serialization error
if output escaping is disabled for a character that is not
representable in the encoding that the processor is using for
output. |
Ed. Note: The DTD for XSLT Stylesheets is not included in this draft. The XSL Working Group intends to provide a DTD and/or Schema for XSLT stylesheets in the final version of this Recommendation.
Sometimes it is useful, when performing a transformation, to retain lexical detail from the source document within the result document. Examples of such details include entity references and CDATA section boundaries. Since these details do not form part of the data model, they are normally lost in the course of transformation, which can make subsequent editing of the document more difficult.
This appendix therefore defines a way in which these lexical details can
be represented within the data model, by means of elements in a special namespace,
specifically http://www.w3.org/2001/XSL/Transform/LexicalMapping
,
with a conventional prefix of lex
.
The process that builds the source tree for a transformation may use
this mapping to represent lexical constructs encountered in the source document,
and the serializer may interpret the elements in this namespace as directives
to reproduce these lexical constructs on output.
There is no requirement that XSLT processors must support this mapping.
The transformation itself does not treat these elements
specially; they will be visible to the stylesheet in the same way as any other
element, and what happens to them is entirely under the control of the
stylesheet author. A stylesheet is free to copy these elements, or to ignore them,
or to create new elements in this namespace as directives to the serializer.
If an implementation chooses to support these mappings, it is suggested that this should be done by means of a user option that causes the tree construction process to create the relevant elements, and the serializer to interpret them. This option should not be the default mode of processing.
The elements are listed below:
Element Name | Attributes | Meaning |
---|---|---|
lex:cdata-section |
None | Defines a CDATA section. The content of the CDATA section
is represented in the form of child nodes of the lex:cdata-section
element. |
lex:entity-reference |
name | Marks the point in the source text where a general entity reference
occurred. The name attribute gives the name of the entity.
The expanded content of the entity is represented in the form of child
nodes of the lex:entity-reference element. Note that
entity references within attribute values cannot be represented
this way. |
lex:doctype |
name, public-id, system-id | Marks the point in the source text where the DOCTYPE declaration
occurred. The name
attribute gives the name of the document type.
The optional system-id attribute gives
the system identifier of the external DTD subset.
The optional public-id attribute gives
the public identifier of the external DTD subset. |
lex:element-declaration |
name, model | Represents an element declaration within the internal DTD subset.
This element will appear only as a child of lex:doctype .
The name
attribute gives the name of the element type.
The model attribute gives
the content model of the element type, as an unparsed string. This
may be normalized, for example by expansion of parameter entities, removal
of whitespace, at implementor option. |
lex:attribute-declaration |
element-name, attribute-name, attribute-type, optional, default-value | Represents an attribute declaration within the internal DTD subset.
This element will appear only as a child of lex:doctype .
The element-name
attribute gives the name of the element.
The attribute-name
attribute gives the name of the attribute.
The attribute-type attribute gives
the attribute type, for example CDATA or IDREFS .
The optional attribute takes the value FIXED ,
REQUIRED , or IMPLIED ; it is omitted if none
of these is applicable.
The default-value attribute gives the default value for
the attribute if one has been defined; if not, this attribute is omitted.
|
lex:notation-declaration |
name, system-id, public-id | Represents an notation declaration within the internal DTD subset.
This element will appear only as a child of lex:doctype .
The name
attribute gives the name of the notation.
The optional system-id attribute gives
the system identifier of the notation.
The optional public-id attribute gives
the public identifier of the notation. |
lex:unparsed-entity-declaration |
name, system-id, public-id, notation-name | Represents an unparsed entity declaration within the internal DTD subset.
This element will appear only as a child of lex:doctype .
The name
attribute gives the name of the unparsed entity.
The system-id attribute gives
the system identifier of the unparsed entity.
The optional public-id attribute gives
the public identifier of the unparsed entity.
The notation-name
attribute gives the name of the associated notation.
|
Note that even when using this representation of the lexical structure of an XML document, the tree will contain attribute nodes representing attributes whose values were defaulted from the DTD. A stylesheet that wishes to avoid outputting such attributes must include the necessary logic to avoid this; it is not possible from the tree representation to determine whether the attribute was actually present in the original XML instance.
This specification was developed and approved for publication by the W3C XSL Working Group (WG). WG approval of this specification does not necessarily imply that all WG members voted for its approval.
The current chair of the XSL WG is Sharon Adler, IBM. The other members of the XSL WG are:
Principal | Alternate | Affiliation |
---|---|---|
Amr Yassin | - | Philips Electronics |
Sanjiva Weerawarana | Anders Berglund | IBM |
Henry Thompson | - | HCRC Language Technology Group, University of Edinburgh |
Bob Lojek | - | Mozquito Technologies |
Jeff Caruso | Andrew Greene | Pageflex, Inc. |
Paul Grosso | - | Arbortext |
Michael Kay | Juliane Harbarth | Software AG Inc |
Jeremy Richman | - | Interleaf |
Norm Walsh | Tony Graham | Sun Microsystems Inc. |
Scott Boag | - | Lotus Development Corporation |
Scott Parnell | - | Xerox |
Perin Blanchard | Shon Vella | Novell, Inc. |
Jonathan Marsh | Ashok Malhotra | Microsoft Corporation |
Zarella Rendon | - | DataChannel |
Bill Lindsey | - | B-Bop |
Chris Maden | Ray Waldin | Lexica |
Peter Van der Beken | - | Netscape/AOL |
Evan Lenz | - | XYZFind Corp. |
Dipak Chopra | - | SAP Labs |
Mark Scardina | K Karun | Oracle |
Daniela Florescu | - | Propel |
Alex Milowski | - | Markup Technology Ltd. |
Kristoffer Rose | IBM |
The W3C representative on the XSL WG is Max Froumentin.
The following individuals made significant contributions to XSLT 2.0 while they were members of the WG:
This specification builds on the success of the XSLT 1.0 Recommendation. For a list of contributors to XSLT 1.0, see [XSLT 1.0].
This section provides a checklist of progress against the published XSLT 2.0 Requirements document.
Requirement 1
Must Maintain Backwards Compatibility with XSLT 1.1 [Read this as "with XSLT 1.0"]
Any stylesheet whose behavior is fully defined in XSLT 1.0 and which generates no errors will produce the same result tree under XSLT 2.0
Response
See [J.1 Incompatible Changes]
Requirement 2
Must Match Elements with Null Values
A stylesheet should be able to match elements and attributes whose value is explicitly null.
Response
This has been handled as an XPath 2.0 requirement.
Requirement 3
Should Allow Included Documents to "Encapsulate" Local Stylesheets
XSLT 2.0 SHOULD define a mechanism to allow the templates in a stylesheet associated with a secondary source document, to be imported and used to format the included fragment, taking precedence over any applicable templates in the current stylesheet.
Response
No progress has been made against this requirement.
Requirement 4
Could Support Accessing Infoset Items for XML Declaration
A stylesheet COULD be able to access information like the version and encoding from the XML declaration of a document.
Response
This is not easy: this information is not readily available from XML parsers? Apparently some of this information is being added to the DOM.
Requirement 5
Could Provide QName Aware String Functions
Users manipulating documents (e.g. stylesheets, schemas) that have QName-valued element or attribute content need functions that take a string containing a QName as their argument, convert it to an expanded QName using either the namespace declarations in scope at that point in the stylesheet, or the namespace declarations in scope for a specific source node, and return properties of the expanded QName such as its namespace URI and local name.
Response
Functions operating on QNames are included in the XPath 2.0 operators and functions document.
Requirement 6
Could Enable Constructing a Namespace with Computed Name
Provide an xsl:namespace
analog to
xsl:element
for constructing
a namespace node with a computed prefix and URI.
Response
An xsl:namespace
instruction has been added: see
[8.6 Creating Namespace Nodes].
Requirement 7
Could Simplify Resolving Prefix Conflicts in QName-Valued Attributes
XSLT 2.0 could simplify the renaming of conflicting namespace prefixes in result tree fragments, particularly for attributes declared in a schema as being QNames. Once the processor knows an attribute value is a QName, an XSLT processor should be able to rename prefixes and generate namespace declarations to preserve the semantics of that attribute value, just as it does for attribute names.
Response
If an attribute is typed as a QName in the schema, the new XPath 2.0 functions can be used to manipulate it as required at application level. This may be sufficient to meet the requirement.
Requirement 8
Could Support XHTML Output Method
Complementing the existing output methods for html, xml, and text, an xhtml output method could be provided to simplify transformations which target XHTML output.
Response
An XHTML output method is now provided.
Requirement 9
Must Allow Matching on Default Namespace Without Explicit Prefix
Many users stumble trying to match an element with a default namespace.
Response
A new [xsl:]default-xpath-namespace
attribute
is provided for this purpose.
Requirement 10
Must Add Date Formatting Functions
One of the more frequent requests from XSLT 1.0 users is the ability to format date information with similar control to XSLT's format-number(). XML Schema introduces several kinds of date and time datatypes which will further increase the demand for date formatting during transformations. Functionality similar to that provided by java.text.SimpleDateFormat. A date analog of XSLT's named xsl:decimal-format may be required to handle locale-specific date formatting issues.
Response
Date manipulation functions are included in XPath 2.0, but no formatting capability is provided yet. The XSL Working Group intends to provide such a function in the final Recommendation.
Requirement 11
Must Simplify Accessing Id's and Key's in Other Documents
Currently it is cumbersome to lookup nodes by id() or key() in documents other than the source document. Users must first use an xsl:for-each instruction, selecting the desired document() to make it the current node, then relative XPath expressions within the scope of the xsl:for-each can refer to id() or key() as desired.
Response
The requirement is met by the generalization of path syntax in XPath 2.0
Requirement 12
Should Provide Function to Absolutize Relative URIs
There SHOULD be a way in XSLT 2.0 to create an absolute URI. The functionality should allow passing a node-set and return a string value representing the absolute URI resolved with respect to the base URI of the current node.
Response
This requirement has not yet been addressed.
Requirement 13
Should Include Unparsed Text from an External Resource
Frequently stylesheets must import text from external resources. Today users have to resort to extension functions to accomplish this because XSLT 1.0 only provides the document() function which, while useful, can only read external resources that are well-formed XML documents.
Response
A function unparsed-text has been added.
Requirement 14
Should Allow Authoring Extension Functions in XSLT
As part of the XSLT 1.1 work done on extension functions, a proposal to author XSLT extension functions in XSLT itself was deferred for reconsideration in XSLT 2.0. This would allow the functions in an extension namespace to be implemented in "pure" XSLT, without resulting to external programming languages.
Response
A solution to this requirement, the xsl:function
element,
is included in this specification.
See [7.3 Stylesheet Functions].
Requirement 15
Should Output Character Entity References Instead of Numeric Character Entities
Users have frequently requested the ability to have the output of their transformation use (named) character references instead of the numeric character entity. The ability to control this preference as the level of the whole document is sufficient. For example, rather than seeing   in the output, the user could request to see the equivalent instead.
Response
This requirement has not yet been addressed.
Requirement 16
Should Construct Entity Reference by Name
Analogous to the ability to create elements and attributes, users have expressed a desire to construct named entity references.
Response
An appendix has been added (see [F Representation of Lexical XML Constructs]) defining a method of representing the lexical structure of an XML document within the data model. If this representation is used, elements representing entity references can be constructed in the result tree.
Requirement 17
Should Support for Unicode String Normalization
For reliable string comparison of Unicode strings, users need the ability to apply Unicode normalization before comparing the strings.
Response
This requirement has been addressed in XPath 2.0.
Requirement 18
Should Standardize Extension Element Language Bindings
XSLT 1.1 undertook the standarization of language bindings for XSLT extension functions. For XSLT 2.0, analogous bindings should be provided for extension elements [now renamed extension instructions].
Response
The XSL Working Group has decided not to pursue this requirement, and the attempt to standardize language bindings for extension functions that appeared in the XSLT 1.1 Working Draft has now been withdrawn. The Working Group decided that language bindings would be better published separately from the core XSLT specification.
Requirement 19
Could Improve Efficiency of Transformations on Large Documents
Many useful transformations take place on large documents consisting of thousands of repeating "sub-documents". Today transformations over these documents are impractical due to the need to have the entire source tree in memory. Enabling "progressive" transformations, where the processor is able to produce progressively more output as more input is received, is tantamount to avoiding the need for XSLT processors to have random access to the entire source document. This might be accomplished by:
Identifying a core subset of XPath that does not require random access to the source tree, or
Consider a "transform all subtrees" mode where the stylesheet says, "Apply the transformation implied by this stylesheet to each node that matches XXX, considered as the root of a separate tree, and copy all the results of these mini-transformations as separate subtrees on to the final result tree."
Response
This requirement has not been addressed.
Requirement 20
Could Support for Reverse IDREF attributes
Given a particular value of an ID, produce a list of all elements that have an IDREF or IDREFS attribute which refers to this ID.
This functionality can be accomplished using the current <xsl:key> and key() mechanism.
Response
An idref() function is included in XPath 2.0 Functions and Operators
Requirement 21
Could Support for Case-Insensitive Comparisons
XSLT 2.0 could expand its comparison functionality to include support for case-insensitive string comparison.
Response
This is an XPath 2.0 requirement. XPath 2.0 Functions and Operators includes functions to convert strings to uppercase or lowercase, it also includes functions to compare strings using a named collating sequence, which provides the option of using a collating sequence that treats uppercase and lowercase as equal.
Requirement 22
Could Support Lexigraphic String Comparisons
We don't let users compare strings like $x > 'a'.
Response
This requirement has been addressed in XPath 2.0.
Requirement 23
Could Allow Comparing Nodes Based on Document Order
Support the ability to test whether one node comes before another in document order.
Response
This requirement has been addressed in XPath 2.0.
Requirement 24
Could Improve Support for Unparsed Entities
In XSLT 1.0 there is an asymmetry in support for unparsed entities. They can be handled on input but not on output. In particular, there is no way to do an identity transformation that preserves them. At a minimum we need the ability to retrieve the Public ID of an unparsed entity.
Response
An appendix has been added (see [F Representation of Lexical XML Constructs]) defining a method of representing the lexical structure of an XML document within the data model. If this representation is used, additional information about unparsed entities is available from the source tree, and elements representing unparsed entities can be added to the result tree.
Requirement 25
Could Allow Processing a Node with the "Next Best Matching" Template
In the construction of large stylesheets for complex documents, it is often
necessary to construct templates that implement special behavior for a particular
instance of an element, and then apply the normal styling for that element.
Currently this is not possible because xsl:apply-templates
specifies
that for any given node only a single template will be selected and instantiated.
Currently the processor determines a list of matching templates and then
discards all but the one with the highest priority. In order to support this
requirement, the processor would retain the list of matching templates sorted
in priority order. A new instruction, for example xsl:next-match
,
in a template would simply trigger the next template in the list of matching
templates. This "next best match" recursion naturally bottoms out at the
builtin template which can be seen as the lowest priority matching template
for every match pattern.
Response
The working group has discussed this requirement but has not yet produced a proposal that is ready for publication.
Requirement 26
Could Make Coercions Symmetric By Allowing Scalar to Nodeset Conversion
Presently, no datatype can be coerced or cast to a node-set. By allowing a string value to convert to a node-set, some user "gotchas" could be avoided.
Response
The availability of sequences of strings or numbers probably meets most of the use-cases envisaged by this requirement.
Requirement 27
Must Simplify Constructing and Copying Typed Content
It MUST be possible to construct XML Schema-typed elements and attributes. In addition, when copying an element or an attribute to the result, it should be possible to preserve the type during the process.
Response
This is work in progress. Facilities for associating type information with constructed elements and attributes are likely to appear in future drafts of XSLT 2.0.
Requirement 28
Must Support Sorting Nodes Based on XML Schema Type
XSLT 1.0 supports sorting based on string-valued and number-valued expressions. XML Schema: Datatypes introduces new scalar types (for example, date) with well-known sort orders. It MUST be possible to sort based on these extended set of scalar data types. Since XML Schema: Datatypes does not define an ordering for complex types, this sorting support should only be considered for simple types.
Should be consistent with whatever we define for the matrix of conversion and comparisons.
Response
Sorting based on any schema-defined primitive data type is included in this specification.
Requirement 29
Could Support Scientific Notation in Number Formatting
Several users have requested the ability to have the existing format-number() function extended to format numbers using Scientific Notation.
Response
The specification for the format-number has been rewritten to remove the dependency on the JDK 1.1 specification. It could be further enhanced to introduce scientific notation (which would represent an upgrade to the JDK 1.2 specification). Simple scientific formatting is now available through support for the schema-defined xsd:float and xsd:double data types.
Requirement 30
Could Provide Ability to Detect Whether "Rich" Schema Information is Available
A stylesheet that requires XML Schema type-related functionality
could be able to test whether a "rich" Post-Schema-Validated
Infoset is available from the XML Schema processor, so that
the stylesheet can provide fallback behavior or choose to exit
with xsl:message abort="yes"
.
Response
XPath 2.0 allows expressions to determine the type of element and attribute nodes, using information from the schema. The details of how these expressions behave when there is no schema are defined in the XPath specifications.
Requirement 31
Must Simplify Grouping
Grouping is complicated in XSLT 1.0. It MUST be possible for users to group nodes in a document based on common string-values, common names, or common values for any other expression
In addition XSLT must allow grouping based on sequential position, e.g. selecting groups of adjacent <P> elements. Ideally it should also make it easier to do fixed-size grouping as well, e.g. groups of three adjacent nodes, for laying out data in multiple columns. For each group of nodes identified, it must be possible to instantiate a template for the group. Grouping must be "nestable" to multiple levels so that groups of distinct nodes can be identified, then from among the distinct groups selected, further sub-grouping of distinct node in the current group can be done.
Response
A new xsl:for-each-group
instruction is provided: see
[13 Grouping]. In addition, many of the new functions and operators provided
in XPath 2.0 make these algorithms easier to write.
Issue 1: binding-to-schema
Description: Do we need to say anything, or add any capabilities, for binding a stylesheet to a schema? Presumably the names of types used in variable declarations must be known statically, which implies that a schema is available statically.
Issue 2: document-collection
Description: There are suggestions that it should be possible to supply a collection of source documents as input. In this case, it is unclear whether any one of these would be specially identified as the principal source document, or whether the transformation would be applied to each of them independently.
Issue 4: embedded-simplified-stylesheets
Description: This classification would imply that embedded stylesheet modules cannot be simplified stylesheets. The Working Group does not intend to disallow use of embedded simplified stylesheet modules, and will re-work the text before final publication to permit this combination.
Issue 8: include-fragment
Description: Is it permitted for the
URI reference used in xsl:include
and xsl:import
to include
a fragment identifier, to reference an embedded stylesheet module?
And if so, what is the form of the fragment identifier?
This isn't clear at 1.0.
Issue 9: schema-explanation
Description: We need to say something here about schemas and DTDs.
Issue 10: public-identifiers
Description: There is a requirement to add support for the public identifier of unparsed entities. The Working Group intends to add this feature before final publication of XSLT 2.0.
Issue 11: whitespace-and-schema
Description: If an element has element content, as defined in the schema or DTD, the default should be to strip whitespace nodes rather than preserving them.
Issue 13: shared-namespace-node-fixup
Description: This section needs to be revised if namespace nodes are to be held at document level.
Issue 14: d-o-e-on-attributes
Description: Should we allow disable-output-escaping on xsl:attribute?
Issue 15: restrict-d-o-e
Description: It is proposed that we should restrict the use of disable-output-escaping so it can only be used on a final result tree. This would avoid distorting the data model.
Issue 16: leading-colon-in-qname
Description: The current XPath grammar allows a QName to contain a leading colon. This leading colon is not considered part of the QName as far as XSLT is concerned, and is not permitted in contexts other than an XPath expression.
Issue 17: type-compatibility
Description: We need to provide a more rigorous definition of what it means for the supplied value to be compatible with the required type.
Issue 18: statically-known-types
Description: Are any types, other than those defined in XML Schema (such as xsd:integer) known statically?
Issue 19: stylesheet-defined-collations
Description: Should the stylesheet define names of collations? If so, how are they to be described? Should we encourage portability by providing some indirection between the collation name and the underlying collation? But if this is to aid portability, there needs to be a way of selecting different mappings based on the XSLT implementation.
Issue 20: default-collation
Description: Should there be facilities in XSLT to select the default collation? If so, how should this be scoped?
Issue 29: runtime-namespace-selection
Description: The default-xpath-namespace facility as proposed here doesn't meet the requirement to match multiple namespaces, or to decide at run-time which namespace to match - as exemplified by the XHTML scenario.
Issue 30: must-namespaces-precede-attributes
Description: It appears
that several implementations
currently allow a namespace node to be added after adding attributes (using
xsl:copy
). This seems
convenient for the user, and the Working Group is inclined to allow it.
To achieve this, we will need to define some conflict
resolution if the namespace clashes with an existing attribute.
Issue 31: use-constructor-semantics
Description: The above text should be rewritten to provide a formal mapping to the constructor functions defined in the data model.
Issue 32: variables-in-match-patterns
Description: Is the rule excluding a Variable useful? Its main purpose is to prevent circularity, where a global variable issues xsl:apply-templates and the variable needs to be evaluated to determine the match. But the rule is not sufficient to prevent circularity, because the template rule, once selected, can contain instructions that reference the global variable. However, it might be useful to retain the rule because it helps processors optimize matching of template rules. Also note, the rule needs to be phrased so that range variables declared locally within a sub-expression are permitted.
Issue 34: parameters-with-built-in-templates
Description: Would it be useful to define that parameters to a built in template are passed through unchanged? This is a frequent source of user bewilderment. The change would be technically backwards incompatible, but very unlikely to have adverse effects.
Issue 35: variable-type-semantics
Description: We need to say more about the permitted values of the type attribute, and their meaning, once the XPath rules are clearer. For example, are all the permitted names of types known statically, and if so, where do these names come from?
Issue 36: variable-type-conversion
Description: Should
the type
attribute on xsl:variable
cause the supplied value to
be converted to the required type, or should it cause a dynamic error to be
signaled if the supplied value does not conform to the required type: perhaps
with conversion as a recovery action?
Issue 38: xpath-variable-shadowing
Description: Can variables declared within an XPath 2.0 expression shadow variables declared at XSLT level?
Issue 39: add-type-to-with-param
Description: Should we add a type attribute to xsl:with-param, for symmetry with xsl:variable and xsl:param?
Issue 40: with-param-verbosity
Description: Should we introduce an alternative and less verbose syntax for passing parameters when invoking a template?
Issue 41: user-functions-vs-vendor-functions
Description: Should user-defined functions override vendor-defined functions of the same name, as specified here, or should it be the other way around?
Issue 42: too-many-params-error
Description: Should it be a static or a dynamic error if too many parameters are supplied? It's described here as a static error, because it can be detected statically, even though this seems inconsistent with the fact that it's a dynamic error if the function doesn't exist, which is done so that function-available() works.
Issue 43: result-type-optional
Description:
Should the type
attribute of xsl:result
be mandatory?
Issue 44: define-lre-element-type
Description: Should
we add an xsl:type
attribute to literal result elements, to define
the type of the newly-constructed element node? Alternatively, should xsi:type
be used with this meaning? What are the rules governing its use?
Issue 45: lre-element-typed-value
Description: Should
we provide a way of supplying the typed value of literal result element, as distinct from
its string value, perhaps by means of a xsl:select
attribute on the
literal result element?
Issue 46: define-element-type
Description: Should
we add a type
attribute to xsl:element
, to define
the type of the newly-constructed element node? If so, what are the rules
governing its use?
Issue 47: element-typed-value
Description: Should
we provide a way of supplying the typed value of a new element node, as distinct from
its string value, perhaps by means of a select
attribute on the
xsl:element
instruction?
Issue 48: define-attribute-type
Description: Should
we add a type
attribute to xsl:attribute
, to define
the type of the newly-constructed attribute node? If so, what are the rules
governing its use?
Issue 49: attribute-typed-value
Description: Should
we provide a way of supplying the typed value of a new attribute node, as distinct from
its string value, perhaps by means of a select
attribute on the
xsl:attribute
element?
Issue 53: converge-with-sortby
Description: While the
facility for named sort keys meets the requirement to be able to sort arbitrary
sequences, the XSL Working Group would prefer to find a way of converging this
capability with the sortby
syntax proposed for use in XQuery.
Issue 54: grouping-with-collation
Description: The Working Group has decided
in principle to add a collation
attribute to xsl:for-each-group
, to specify the
collation under which strings are compared for equality.
Issue 55: grouping-with-other-datatypes
Description: Should we allow grouping based on key values whose data type is other than string?
Issue 56: group-ending-with
Description: A use case has
also been identified for a group-ending-with
attribute. This arises
when all but the last item in a sequence carries a continuation marker of some kind.
Issue 57: namespace-for-additional-functions
Description: Should functions defined in XSLT (additional to those defined in XPath) use a different namespace, perhaps the XSLT namespace, to avoid any future conflicts with functions defined in the core?
Issue 58: document-function-in-core
Description: The
Functions and Operators specification (see [Functions and Operators]) describes an xf:document
function which should supersede the one described here, allowing this section
to be removed. However, at present the specification here is rather more complete.
Issue 59: document-fragment-id
Description: Should we be more prescriptive about the form of fragment identifier supported by the document function? Should we perhaps (following XInclude) mandate that it should be treated as an XPointer? Should we drop the notion that the form of fragment identifier depends on the media type, given that we are going to treat the actual media type as text/xml regardless?
Issue 60: collation-in-keys
Description: Should xsl:key
specify a collation to be used for matching strings?
Issue 61: datatype-in-keys
Description: Should xsl:key
allow comparison of values using data types other than string?
Issue 62: sequence-valued-keys
Description: What if the second argument to key() is an attribute of type IDREFS? We should consider the typed-value of the nodes in the sequence, not just the string value.
Issue 65: format-number-left-to-right
Description: This version of the format-number specification makes the presumption that numbers will be formatted with the most significant digit on the left. Do we want to make this assumption?
Issue 69: format-currency-sign
Description: Should the prohibition on ¤ continue? Suggestion: start allowing it.
Issue 70: scientific-notation
Description: There is a requirement to allow scientific notation in format-number() (it is permitted in the JDK 1.2 version of the original specification). The Working Group intends to add this capability before final publication of XSLT 2.0.
Issue 71: position-percent
Description: Must the percent or per-mille sign be immediately after the last digit or decimal-separator? Suggestion: keep the set of legal positions down to the minimum set that will satisfy all world cultures.
Issue 72: overflow-filler
Description: Should overflows be represented by a filler pattern? What is the overflow filler pattern? Suggestion: use the digit character (default #) literally in place of all digits, and show decimal and grouping separators literally. This will take up the same space as a value with the maximum number of displayable decimal places, and have separators aligned.
Issue 73: evaluate-function
Description: There is at present no consensus within the working group that such a function should be provided, as it has significant implications on the run-time architecture of the processor, as well as the ability to do static optimization.
Issue 74: variables-in-evaluate
Description: Do we want to allow dyamically constructed expressions to contain variable references and/or calls on non-core functions? The current text is a compromise, it effectively makes it an implementor option.
Issue 75: format-date-time
Description: There is a need for an additional function to format dates and times.
Issue 76: current-in-pattern
Description: The rule banning use of current() in a pattern could be relaxed. For example, it would be simpler to say that current() refers to the node being tested against the pattern.
Issue 77: message-destination
Description: Should we provide attributes to control the formatting and/or destination of messages? Indeed, is there any real difference between a message and a secondary result document?
Issue 78: external-objects
Description: Do we want to keep the description of external objects (which was introduced in the XSLT 1.1 Working Draft)? What are the data model implications?
Issue 79: null-external-object
Description: Should the spec have the
concept that an external object may be null, and provide a way for
testing this, for example, by conversion to
boolean
?
Issue 80: destination-element-name
Description: Is it possible to find
a better name for the xsl:destination
element? The name xsl:principal-result
has been suggested.
Issue 82: more-than-one-output-value
Description: Is it an error if an attribute of xsl:output is specified more than once, but they all have the same value? An analogy with xsl:decimal-format would suggest not. This would also seem to be the only excuse for making this a dynamic error rather than a static one.
Issue 83: result-tree-PSVI
Description: The rules for serialization of the result tree consider it only as an infoset; the rules need to be enhanced to allow for (potential loss of) PSVI information on the tree.
Issue 85: XHTML-v11
Description: We currently reference XHTML 1.0. We need to examine the possible impact of XHTML 1.1.
Issue 86: conformance-modules
Description: Should we introduce multiple conformance levels or modules, recognizing that serialization is a separate specification to which processors may or may not conform?
Issue 3: type-errors
Description: Do we want all type-checking errors to be dynamic errors, as described above? In XSLT 1.0, it's unclear whether implementations are required to report the above as an error, or even whether they are permitted to do so.
Resolution: Type errors may be reported statically as an implementation option.
Issue 5: import-first
Description: Is there still any value in the rule that xsl:import elements must come first, given that promotion is needed in the case where a module is imported into an included module?
Resolution: Keep the rule, it's not broken so don't fix it.
Issue 6: import-before-user-defined
Description: Can a user-defined top-level element come before an xsl:import element?
Resolution: No, it can't.
Issue 7: compatibility-static-error
Description: Should it be a static error to invoke backwards compatible behavior with a processor that doesn't support it?
Resolution: No, it should be a dynamic error. This allows the user to test system properties at run-time and take an alternative path.
Issue 12: stripping-optional
Description: Should we relax the rules on
whitespace stripping? When the processor is supplied with
an immutable tree as input, it imposes a very significant performance overhead,
which may be quite unjustified. Really, whitespace stripping should be part of
the tree construction process, not part of the transformation proper. Perhaps
we should say something like "there may be operational circumstances in which
whitespace stripping is infeasible. In such circumstances, a processor
may reject an xsl:strip-space
declaration as an error."
Resolution: Leave the specification unchanged.
Issue 21: pattern-compatibility
Description: We need to define the backwards compatibility rules, if patterns contain XPath expressions that are not 100% backwards compatible.
Resolution: The rules are now defined.
Issue 22: allow-intersect-in-patterns
Description: Should we allow the intersect
and except
operators in patterns? If so, what are the implications on
priority of template rules?
Resolution: Don't allow intersect and except in patterns.
Issue 23: id-in-patterns
Description: In patterns, id() and key() with literal arguments are virtually useless in practice. Should we generalize them to allow the argument to be a global parameter?
Resolution: No change needed from XSLT 1.0. The existing facility might not be very useful, but it's not broken.
Issue 24: xsl-default-namespace-lre
Description: Should an xsl:default-xpath-namespace
attribute be allowed on literal result elements?
Resolution: Yes, it is now allowed.
Issue 25: default-prefix-or-uri
Description: Should the value of the attribute be a namespace prefix or a namespace URI? We usually use a prefix, but in this case I can see no merit in requiring the namespace to be declared in the stylesheet.
Resolution: The value is a namespace URI.
Issue 26: xsl-default-namespace-everywhere
Description: Should the new attribute be allowed on elements where it has no effect, e.g. xsl:decimal-format?.
Resolution: It is now allowed everywhere, for simplicity
Issue 27: other-general-attributes
Description: Should we allow other "inheritable" attributes, e.g. version, extension-element-prefixes, to be used on any XSLT element? At present they are only allowed on the xsl:stylesheet element or on literal result elements, which can be very restrictive.
Resolution: The rules have been generalized so all these attributes can appear anywhere.
Issue 28: xsl-default-namespace-in-xpath
Description: We need to ensure that XPath 2.0 allows the default namespace to be specified as part of the context.
Resolution: It is defined in the current XPath draft.
Issue 33: apply-templates-on-non-nodes
Description: What happens
when the value of the expression
in the select
attribute is a simple value, or a sequence
that contains a simple value? If heterogeneous sequences are disallowed,
we can make this an error, as in XSLT 1.0. If they are permitted, the
best approach may be to say that there is a built-in rule for simple values
that converts the value to a string and outputs it. This isn't likely to
be very useful, but it's simple enough to implement and to explain.
Resolution: Treated as a recoverable dynamic error.
Issue 37: variable-type-mandatory
Description: Should we
make the type
attribute on xsl:variable
mandatory (but
with provision for backwards compatibility), or allow a mode of execution in which the
attribute is mandatory?
Resolution: The Working Group decided that this attribute should not be mandatory.
Issue 50: xsl-value-of-first-node-semantics
Description: Do we want xsl:value-of
to retain first-node semantics as in XPath 1.0? If the value is a sequence, should it be the first
in document order or the first in sequence order? What if the value is a sequence of simple values?
Resolution: Retain XSLT 1.0 behavior in the absence of the new separator attribute.
Issue 51: for-each-and-sequences
Description: We need
to decide how xsl:for-each
should handle
sequences of simple values, or heterogeneous sequences.
Resolution: Any kind of sequence can be processed; the generalization of context node to context item makes this possible.
Issue 52: descending-duplicates
Description: We are saying here that with order="descending", duplicates are delivered in reverse document order. XSLT 1.0 implied that they were delivered in forwards document order.
Resolution: They are now in forwards order (again). It has to be this way, because there might be multiple sort keys.
Issue 63: format-number-and-jdk
Description: The JDK 1.1 specification is insufficiently rigorous. Is there anything better available?
Resolution: A new specification, independent of the JDK, has been written.
Issue 64: invalid-format-pattern
Description: Need to specify what happens if the format pattern is invalid. Is there a recovery action?
Resolution: The number should be output using standard conversion to a string.
Issue 66: decimal-format-grouping-size
Description: The
xsl:number
instruction uses an explicit option to set
grouping-size, while in format-number() it is derived by inspection of
the pattern. Should the two work the same way, which
would mean adding a grouping-size to xsl:decimal-format?
Resolution: Leave the spec unchanged: it's not broken
Issue 67: allow-grouping-in-fractional-part
Description: Should it be possible to use grouping-separators in the fractional part?
Resolution: Yes, the current algorithm allows it. This is because (a) it's functionally beneficial, and (b) there may be a culture in the world that wants them.
Issue 68: error-multiple-clusters-active-characters
Description: Should it be an error to have more than one cluster of digit and/or zero-digit characters, or should all clusters after the first just be assumed to be part of the suffix?
Resolution: Make it an error, because it almost always would be, and the stylesheet writer should use concat() for all but the simplest prefixes and suffixes anyway.
Issue 81: message-document
Description: What should happen if
xsl:result-document
occurs inside
xsl:message
?
Resolution: It's an error.
Issue 84: XHTML-URI-escaping
Description: Should the XHTML output method perform URI escaping of attributes that are known to be URI values, in the same way as the HTML output method?
Resolution: Yes, but under the control of a new escape-uri-attributes attribute on xsl:output.
This section lists all known cases where a stylesheet that was valid (produced no errors) under XSLT 1.0, and whose behavior was fully specified by XSLT 1.0, will produce different results under XSLT 2.0.
Most of the discussion is concerned with compatibility in the absence of a schema: that is, it is assumed that the source document being transformed has no schema when processed using XSLT 1.0, and that no schema is added when moving to XSLT 2.0. Some additional factors that come into play when a schema is added are noted at the end of the section.
If the source documents supplied as input to a transformation contain no type information generated from a schema (or by generating a PSVI from information in the DTD), then the known areas of incompatibility are as follows:
A stylesheet that specifies a version number other than 1.0 was defined in XSLT 1.0 to execute in forwards-compatible mode; if such a stylesheet used features that are not defined in XSLT 2.0 then errors may be reported by an XSLT 2.0 processor that would not be reported by an XSLT 1.0 processor.
If the xsl:number
element was called with a value
attribute whose value was a node-set containing more than one node, then an XSLT 1.0
processor would output the numeric value of the first node in the node-set. An
XSLT 2.0 processor will output the numeric value of every node in the equivalent
node sequence. If the node-set was empty, an XSLT 1.0 processor would output "NaN";
an XSLT 2.0 processor will output nothing.
At XSLT 1.0 the system-property function, when called with a first
argument of "xsl:version"
, returned 1.0 as a number. At XSLT 2.0 it returns "2.0"
as a string.
When the data-type
attribute of xsl:sort
has the value number
, an XSLT 1.0 processor would evaluate the sort key as a string,
and convert the result to a number. An XSLT 2.0 processor evaluates the sort key as a number
directly. This only affects the outcome in cases where conversion of a number to a string and then
back to a number does not produce the original number, as is the case for example with the number
Positive Infinity
.
The specification of the format-number function has been rewritten to remove the normative dependency on the Java JDK 1.1 specification. The JDK 1.1 specification left aspects of the behavior undefined; it is therefore possible that some cases will give different results. The ability to include literal text in the format picture (enclosed in single quotes) has been removed; any stylesheet that uses this feature will need to be modified, for example to display the literal text using the concat function instead.
If no output method is explicitly requested, and the first element node output appears to be an XHTML document element, the output method now defaults to XHTML; previously the XML output method would have been used.
This section provides a summary of the main areas of incompatibility between XPath 2.0 and XPath 1.0. Many of these are areas where the specification still has open issues outstanding, so this list should not be taken as final. It is the intention of the working group to review all known incompatibilities before final publication.
The list given here assumes (a) that the source document is processed
in the absence of a schema, and (b) that the policy for handling type exceptions
is flexible
: that is, that the software attempts wherever possible
to perform conversions from the supplied type of a value to the type required
by the operation or function where it is used.
In the description below, the terms node-set and number are used with their XPath 1.0 meanings, that is, to describe expressions which according to the rules of XPath 1.0 would have generated a node-set or a number respecively.
The rules for comparing a node-set to a boolean have changed. In XPath 1.0,
an expression such as $nodeset=true()
was evaluated by converting the
node-set to a boolean and comparing the result: so this expression would return true
if $nodeset
was non-empty. In XPath 2.0, this expression is handled in
the same way as other comparisons between a sequence and a singleton: it is true if
$nodeset
contains at least one node whose typed value is true
.
The rules for converting a string to a boolean have changed, so they are now
aligned with XML Schema. In XPath 2.0, the strings "0"
and "false"
are treated as false, while in XPath 1.0, they were treated as true. All other strings
are converted in the same way as XPath 1.0.
Additional numeric types have been introduced, with the effect that arithmetic may now be done as an integer, decimal, or single-precision floating point calculation where previously it was always performed as double-precision floating point. This may affect the precision of the results, and may cause errors if division by zero is attempted.
The rules for converting numbers to strings have changed. These will affect the
way numbers are displayed in the output of a stylesheet. The output format depends on
the data type of the result: floating point values, for example, will be displayed using
scientific notation. The result of a decimal calculation such as 1.5 + 3.5
will be displayed as 5.0
, not 5
as previously. The general
rule is that the resulting string uses the canonical lexical representation for the
data type as defined in XML Schema.
The rules for converting strings to numbers have changed. A string that cannot
be interpreted as a number now (subject to resolution of an open issue) produces an
error, whereas in XPath 1.0 it produced the value NaN
(not a number).
The representation of special values such as Infinity has been aligned with XML Schema.
Strings containing a leading plus sign, or numbers in scientific notation, may now
be converted to ordinary numeric values, whereas in XPath 1.0 they were converted
to NaN
.
Many operations in XPath 2.0 produce an empty sequence as their result
when one of the arguments or operands is an empty sequence. With XPath 1.0, the result
of such an operation was typically an empty string or the numeric value NaN
.
Examples include the arithmetic operators, and functions such as substring
and
name
. Functions also produce an empty sequence when applied to an argument
for which no other value is defined; for example, applying the name
function
to a text node now produces the empty sequence. This means, for example, that with
XPath 1.0 the expression child::node()[name()!='item']
would return all the children
of an element, except for elements named item
; with XPath 2.0 it will exclude
text and comment nodes, because the condition ()!='item'
is treated as
false.
In XPath 1.0, the sum of an empty node-set was zero. At XPath 2.0, it is an empty sequence.
In XPath 1.0, an equality comparison involving an element node was performed by
comparing its string value, that is, the string obtained by concatenating all its
text node descendants. In XPath 2.0, it is an error to use an element node in such
a comparison unless it has simple content. However, because the =
operator
tests whether any pair of items from the two operands are equal, this error will generally
be masked, so a comparison such as PERSON='abc'
, where PERSON
is
an element with one or more child elements, will now always return false.
In XPath 1.0, the <
and >
operators, when applied
to two strings, attempted to convert both the strings to numbers and then made a numeric
comparison between the results. In XPath 2.0, subject to resolution of an open issue,
it is proposed that these operators should perform a lexicographic comparison using the
default collating sequence.
In XPath 1.0, functions and operators that compared strings (for example, the
=
operator and the contains
function) worked on the basis of
character-by-character equality of Unicode codepoints, allowing Unicode normalization
at the discretion of the implementor. In XPath 2.0 (subject to resolution of open issues),
these comparisons are done using the default collating sequence. The working group may
define mechanisms allowing codepoint comparison to be selected as the default collating
sequence, but there is no such mechanism in the current draft.
If an arithmetic operator is applied to an operand that is a sequence of two or more nodes, at XPath 1.0 the numeric value of the first node in the sequence was used. At XPath 2.0, this is an error. (The current XPath 2.0 specification does not invoke fallback conversion in this case).
In the XPath 1.0 data model, an element node had a namespace node for each in-scope
namespace. The parent of the namespace node was the element node, and the namespace nodes
for one element were distinct from those of any other element (as revealed, for example,
using the union operator |
). In XPath 2.0 (subject to resolution of open
issues) element nodes will still have namespace nodes for all the in-scope namespaces,
but these namespace nodes will be shared by different elements in the same document: that
is, there will be a many-to-many relationship between element nodes and namespace nodes.
This will affect any code that attempts to find the parent or ancestors of a namespace
node, or that tries to count namespace nodes or to form a union between two sets of namespace
nodes.
An XSLT 1.0 processor ignored all information about data types that might be obtained from a schema or DTD associated with a source document. An XSLT 2.0 processor will take account of such information. This may lead to a number of differences in behavior. An implementation may provide facilities to handle the document as if the schema information were not available. This section attempts only to give some examples of the kind of differences that might be expected when schema information is made available:
Operations such as sorting will be sensitive to the data type of the items
being sorted. For example, if the data type of the sort key is defined in the schema
as a date, then in the absence of a data-type
attribute on the
xsl:sort
element, the sequence will be sorted in date order. With XSLT 1.0,
the dates would be compared and sorted as strings.
XSLT 1.1 was published as a working draft (see [XSLT 1.1 WD]) on 10 December 2000. Subsequently, the XSL Working Group decided not to take XSLT 1.1 forwards to Recommendation status, but rather to use the document as a baseline for the development of XSLT 2.0.
The following were the principal changes between XSLT 1.0 and XSLT 1.1. These changes are retained in this XSLT 2.0 working draft, except where noted.
The result tree fragment data-type is eliminated. Variable-binding elements with content now construct node-sets (see [6.1 Values of Variables and Parameters]).
Instead of the allowing the output method complete freedom to add namespace nodes, a process of namespace fixup is applied to the result tree before it is output; this same namespace fixup process is also applied to documents constructed variable-binding elements with content (see [3.5 Namespace Fixup]).
Support for XML Base has been added.
A transformation can produce multiple result trees. This facility has been significantly amended in XSLT 2.0 (see [17.2 Secondary Result Trees]).
The attributes on xsl:output
are now interpreted as attribute value templates.
An xsl:apply-imports
element is allowed to have
parameters (see [5.5 Overriding Template Rules] and [7.1.1 Passing Parameters to Templates]).
Language bindings were introduced allowing extension functions to be written in Java or JavaScript. This feature has not been retained in this XSLT 2.0 working draft, because the Working Group decided that standardization of language bindings was a matter best handled separately from the core XSLT specification.
Extension functions are allowed to return "external" objects, which do not have any of the builtin XPath types.
Reported errors in XSLT 1.0 were also fixed.
This section summarizes the changes that have been made in this draft. These are arranged in three groups. Firstly, the changes that pervade the entire text. Secondly, the major new features introduced. And thirdly, a catalog of minor technical changes.
There has been significant re-arrangement of the text. More terminology definitions have been hyperlinked, and a glossary (see [B Glossary]) has been added.
The specifications of some features (notably keys, xsl:number
,
the format-number function, and the xsl:import
mechanism) have been rewritten to make them clearer and more precise.
A number of changes have been made to support the XPath 2.0 data model,
notably the support for sequences as a replacement for the node-sets of XPath 1.0. This
has affected the specification of elements such as xsl:for-each
,
xsl:value-of
, and xsl:sort
.
The processing model is described differently: instead of instructions "writing to the result tree", they now return nodes or node-sequences. This change is largely one of terminology: it paves the way to a more formal definition of the language, sharing a common semantic model with the draft XML Query specifications, and mapping directly to the constructor functions defined in the data model.
The description of the evaluation context has been changed. The concept of current node and current node list have been replaced by the XPath concepts of context item, context position, and context size.
With the introduction of support for XML Schema within XPath 2.0, XSLT has moved in the direction of supporting stronger data typing, while retaining backwards compatibility. In particular, the types of variables and parameters can now be specified explicitly.
The description of error handling has been improved (see [1.7 Error Handling]). This formalizes the difference between static and dynamic errors, and tightens the rules that define which errors must be reported under which conditions.
Facilities are introduced for grouping of nodes (the xsl:for-each-group
instruction, and the current-group()
function).
See [13 Grouping]
It is now possible to create user-defined functions within the stylesheet, that can be called from XPath expressions. See [7.3 Stylesheet Functions].
The facility for multiple output documents, already introduced in the XSLT 1.1 Working Draft, is significantly revised. It now separates the production of multiple result trees from their serialization, and defines more carefully the rules that apply to the creation of links between the different result trees by means of relative URIs. See [17.2 Secondary Result Trees].
An XHTML output method has been added. See [18.2 XHTML Output Method].
A new xsl:sort-key
declaration is available to define named
sort specifications, supporting
an additional sort to allow a sequence to be sorted from within an XPath
expression. A collation
attribute has been added to
the xsl:sort
element to allow sorting using a user-defined collating sequence.
The text for [4.3 Patternspatterns] has been revised to align it with the new XPath grammar. The formal semantics of patterns has been simplified: this became possible because of the extra compositionality now available in the expression grammar. The syntax and semantics of patterns remains essentially unchanged, except that XPath 2.0 expressions can be used within predicates.
A backwards-compatible processing mode is introduced. See [2.6 Backwards-Compatible Processing]
The system-property function now always
returns a string. Two new system properties product-name
and
product-version
have been defined. See [14.6.4 system-property()].
Namespace fixup is no longer required for documents supplied as source documents or returned by extension functions. See [3.5 Namespace Fixup].
With <xsl:message terminate="yes">
, the processor now
must terminate processing. Previously the word should was
used. See [15 Messages].
It is now specified that the omit-xml-declaration
attribute is ignored
if standalone
or encoding
needs to be included in the
XML declaration. See [18.1 XML Output Method].
A new include-content-type
attribute has been added to xsl:output
to suppress the generation of a meta
element in HTML and XHTML output.
A new instruction xsl:namespace
is available, for creating
namespace nodes: see [8.6 Creating Namespace Nodes].
A new [xsl:]default-xpath-namespace
attribute is available to define
the default namespace for unqualified names in an XPath expression or XSLT pattern.
The attributes [xsl:]version
, [xsl:]exclude-result-prefixes
,
and [xsl:]extension-element-prefixes
, as well as the new
[xsl:]default-xpath-namespace
, can be used on any XSLT element, not only on
xsl:stylesheet
and on literal result elements as before. In particular, they
can now be used on the xsl:template
element.
The xsl:text
instruction has been brought into line with
xsl:attribute
, xsl:comment
, and the like.
It is now possible to use instructions such as xsl:value-of
and xsl:if
within an xsl:text
element.
A new unparsed-text function is introduced. It allows the contents of an external text file to be read as a string.