You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
36697 lines
1.6 MiB
36697 lines
1.6 MiB
<?xml version="1.0" encoding="utf-8"?>
|
|
<!--XSLT Processor: SAXON 9.1.0.5 from Saxonica SAXON 9.1.0.5-->
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
|
|
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<html lang="EN" xmlns="http://www.w3.org/1999/xhtml" xml:lang="EN">
|
|
<head>
|
|
<meta name="generator" content=
|
|
"HTML Tidy for Windows (vers 14 October 2008), see www.w3.org" />
|
|
<title>XSL Transformations (XSLT) Version 2.1</title>
|
|
|
|
<style type="text/css">
|
|
/*<![CDATA[*/
|
|
code { font-family: monospace; }
|
|
|
|
div.constraint,
|
|
div.issue,
|
|
div.note,
|
|
div.notice { margin-left: 2em; }
|
|
|
|
div.issue
|
|
p.title { margin-left: -2em; }
|
|
|
|
ol.enumar { list-style-type: decimal; }
|
|
ol.enumla { list-style-type: lower-alpha; }
|
|
ol.enumlr { list-style-type: lower-roman; }
|
|
ol.enumua { list-style-type: upper-alpha; }
|
|
ol.enumur { list-style-type: upper-roman; }
|
|
|
|
li p { margin-top: 0.3em;
|
|
margin-bottom: 0.3em; }
|
|
|
|
sup small { font-style: italic;
|
|
color: #8F8F8F;
|
|
}
|
|
|
|
div.exampleInner pre { margin-left: 1em;
|
|
margin-top: 0em; margin-bottom: 0em}
|
|
div.exampleOuter {border: 4px double gray;
|
|
margin: 0em; padding: 0em}
|
|
div.exampleInner { background-color: #d5dee3;
|
|
border-top-width: 4px;
|
|
border-top-style: double;
|
|
border-top-color: #d3d3d3;
|
|
border-bottom-width: 4px;
|
|
border-bottom-style: double;
|
|
border-bottom-color: #d3d3d3;
|
|
padding: 4px; margin: 0em }
|
|
div.exampleWrapper { margin: 4px }
|
|
div.exampleHeader { font-weight: bold;
|
|
margin: 4px}
|
|
|
|
div.issue { border-bottom-color: black;
|
|
border-bottom-style: solid;
|
|
border-bottom-width: 1pt;
|
|
margin-bottom: 20pt;
|
|
}
|
|
|
|
th.issue-toc-head { border-bottom-color: black;
|
|
border-bottom-style: solid;
|
|
border-bottom-width: 1pt;
|
|
}
|
|
|
|
|
|
dd.indent { margin-left: 2em; }
|
|
p.element-syntax { border: solid thin; background-color: #ffccff }
|
|
p.element-syntax-chg { border: solid thick yellow; background-color: #ffccff }
|
|
div.proto { border: solid thin; background-color: #ffccff }
|
|
div.example { border: solid thin; background-color: #40e0d0; padding: 1em }
|
|
div.example-chg { border: solid thick yellow; background-color: #40e0d0; padding: 1em }
|
|
span.verb { font: small-caps 100% sans-serif }
|
|
span.error { font-size: small }
|
|
span.definition { font: small-caps 100% sans-serif }
|
|
span.grayed { color: gray }
|
|
/*]]>*/
|
|
</style>
|
|
<link rel="stylesheet" type="text/css" href=
|
|
"http://www.w3.org/StyleSheets/TR/W3C-WD.css" />
|
|
</head>
|
|
<body>
|
|
<div class="head">
|
|
<p><a href="http://www.w3.org/"><img src=
|
|
"http://www.w3.org/Icons/w3c_home" alt="W3C" height="48" width=
|
|
"72" /></a></p>
|
|
<h1><a name="title" id="title"></a>XSL Transformations (XSLT)
|
|
Version 2.1</h1>
|
|
<h2><a name="w3c-doctype" id="w3c-doctype"></a>W3C Working Draft 11
|
|
May 2010</h2>
|
|
<dl>
|
|
<dt>This version:</dt>
|
|
<dd><a href=
|
|
"http://www.w3.org/TR/2010/WD-xslt-21-20100511/">http://www.w3.org/TR/2010/WD-xslt-21-20100511/</a></dd>
|
|
<dt>Latest version:</dt>
|
|
<dd><a href=
|
|
"http://www.w3.org/TR/xslt-21/">http://www.w3.org/TR/xslt-21/</a><br />
|
|
</dd>
|
|
<dt>Editor:</dt>
|
|
<dd>Michael Kay, Saxonica <a href=
|
|
"http://www.saxonica.com/"><http://www.saxonica.com/></a></dd>
|
|
</dl>
|
|
<p>Please refer to the <a href=
|
|
"http://www.w3.org/XML/2010/qt-errata/xslt-21-errata.html"><strong>errata</strong></a>
|
|
for this document, which may include some normative
|
|
corrections.</p>
|
|
<p>See also <a href=
|
|
"http://www.w3.org/2003/03/Translations/byTechnology?technology=xslt-21">
|
|
<strong>translations</strong></a>.</p>
|
|
<p class="copyright"><a href=
|
|
"http://www.w3.org/Consortium/Legal/ipr-notice#Copyright">Copyright</a> © 2010 <a href="http://www.w3.org/"><acronym title="World Wide Web Consortium">W3C</acronym></a><sup>®</sup>
|
|
(<a href="http://www.csail.mit.edu/"><acronym title=
|
|
"Massachusetts Institute of Technology">MIT</acronym></a>, <a href=
|
|
"http://www.ercim.eu/"><acronym title=
|
|
"European Research Consortium for Informatics and Mathematics">ERCIM</acronym></a>,
|
|
<a href="http://www.keio.ac.jp/">Keio</a>), All Rights Reserved.
|
|
W3C <a href=
|
|
"http://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer">liability</a>,
|
|
<a href=
|
|
"http://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks">trademark</a>
|
|
and <a href=
|
|
"http://www.w3.org/Consortium/Legal/copyright-documents">document
|
|
use</a> rules apply.</p>
|
|
</div>
|
|
<hr />
|
|
<div>
|
|
<h2><a name="abstract" id="abstract"></a>Abstract</h2>
|
|
<p>This specification defines the syntax and semantics of XSLT
|
|
<span>2.1</span>, a language for transforming XML documents into
|
|
other XML documents.</p>
|
|
<p>XSLT 2.1 is a revised version of the XSLT 2.0 Recommendation
|
|
<a href="#xslt20">[XSLT 2.0]</a> published on 23 January 2007.</p>
|
|
<p>The primary purpose of the changes in this version of the
|
|
language is to enable transformations to be performed in streaming
|
|
mode, where neither the source document nor the result document is
|
|
ever held in memory in its entirety.</p>
|
|
<p>XSLT 2.1 is designed to be used in conjunction with XPath 2.1,
|
|
which is defined in <a href="#xpath-21">[XPath 2.1]</a>. XSLT
|
|
shares the same data model as XPath 2.1, which is defined in
|
|
<a href="#xpath-datamodel-11">[Data Model]</a>, and it uses the
|
|
library of functions and operators defined in <a href=
|
|
"#xpath-functions-11">[Functions and Operators]</a>. XPath 2.1 and
|
|
the underlying function library introduce a number of enhancements,
|
|
for example the availability of higher-order functions. Some of the
|
|
functions that were previously defined in <span>the XSLT 2.0</span>
|
|
specification, such as the <code>format-date</code> and
|
|
<code>format-number</code> functions, are now defined in the
|
|
standard function library to make them available to other host
|
|
languages.</p>
|
|
<p>XSLT 2.1 also includes optional facilities to serialize the
|
|
results of a transformation, by means of an interface to the
|
|
serialization component described in <a href=
|
|
"#xslt-xquery-serialization-11">[XSLT and XQuery
|
|
Serialization]</a>.</p>
|
|
<p><em>This document contains hyperlinks to specific sections or
|
|
definitions within other documents in this family of
|
|
specifications. These links are indicated visually by a superscript
|
|
identifying the target specification: for example XP for XPath, DM
|
|
for the XDM data model, FO for Functions and Operators.</em></p>
|
|
</div>
|
|
<div>
|
|
<h2><a name="status" id="status"></a>Status of this Document</h2>
|
|
<p><em>This section describes the status of this document at the
|
|
time of its publication. Other documents may supersede this
|
|
document. A list of current W3C publications and the latest
|
|
revision of this technical report can be found in the <a href=
|
|
"http://www.w3.org/TR/">W3C technical reports index.</a></em></p>
|
|
<p>This is a <a href=
|
|
"http://www.w3.org/2005/10/Process-20051014/tr.html#first-wd">First
|
|
Public Working Draft</a> as described in the <a href=
|
|
"http://www.w3.org/2005/10/Process-20051014/tr.html">http://www.w3.org/2005/10/Process-20051014/tr.html</a>
|
|
process document. It has been developed by the <a href=
|
|
"http://www.w3.org/Style/XSL/">W3C XSL Working Group</a>, which
|
|
is part of the <a href="http://www.w3.org/XML/Activity">XML
|
|
Activity</a>. The Working Group expects to advance this
|
|
specification to <a href=
|
|
"http://www.w3.org/2005/10/Process-20051014/tr.html#RecsW3C">Recommendation</a>
|
|
Status.</p>
|
|
<p>This specification has been developed in conjunction with
|
|
<a href="#xpath-21">[XPath 2.1]</a> and other documents that
|
|
underpin both XSLT and XQuery. Although the development of this
|
|
family of documents is coordinated, it has not been possible on
|
|
this occasion to publish them simultaneously, and there may
|
|
therefore be imperfect technical alignment between them. This will
|
|
be corrected in later drafts.</p>
|
|
<p>There are many open issues in this draft, as well as uncompleted
|
|
editorial work; known instances are flagged in the form of
|
|
editorial notes. Where these relate to technical issues, feedback
|
|
from readers will be especially welcome.</p>
|
|
<p>Please report errors in this document using W3C's <a href=
|
|
"http://www.w3.org/Bugs/Public/">public Bugzilla system</a>
|
|
(instructions can be found at <a href=
|
|
"http://www.w3.org/XML/2005/04/qt-bugzilla">http://www.w3.org/XML/2005/04/qt-bugzilla</a>).
|
|
If access to that system is not feasible, you may send your
|
|
comments to the W3C XSLT/XPath/XQuery public comments mailing list,
|
|
<a href=
|
|
"mailto:public-qt-comments@w3.org">public-qt-comments@w3.org</a>.
|
|
It will be very helpful if you include the string "[XSLT21]" in the
|
|
subject line of your report, whether made in Bugzilla or in email.
|
|
Please use multiple Bugzilla entries (or, if necessary, multiple
|
|
email messages) if you have more than one comment to make. Archives
|
|
of the comments and responses are available at <a href=
|
|
"http://lists.w3.org/Archives/Public/public-qt-comments/">http://lists.w3.org/Archives/Public/public-qt-comments/</a>.</p>
|
|
<p>Publication as a Working Draft does not imply endorsement by the
|
|
W3C Membership. This is a draft document and may be updated,
|
|
replaced or obsoleted by other documents at any time. It is
|
|
inappropriate to cite this document as other than work in
|
|
progress.</p>
|
|
<p>This document was produced by a group operating under the
|
|
<a href="http://www.w3.org/Consortium/Patent-Policy-20040205/">5
|
|
February 2004 W3C Patent Policy</a>. W3C maintains a <a href=
|
|
"http://www.w3.org/2004/01/pp-impl/19552/status#disclosures">public
|
|
list of any patent disclosures</a> made in connection with the
|
|
deliverables of the XSL Working Group; those pages also include
|
|
instructions for disclosing a patent. An individual who has actual
|
|
knowledge of a patent which the individual believes contains
|
|
<a href=
|
|
"http://www.w3.org/Consortium/Patent-Policy-20040205/#def-essential">
|
|
Essential Claim(s)</a> must disclose the information in accordance
|
|
with <a href=
|
|
"http://www.w3.org/Consortium/Patent-Policy-20040205/#sec-Disclosure">
|
|
section 6 of the W3C Patent Policy</a>.</p>
|
|
<p>For a list of changes, see <a href="#changes-since-2.0"><i>J
|
|
Changes since XSLT 2.0</i></a>.</p>
|
|
</div>
|
|
<div class="toc">
|
|
<h2><a name="contents" id="contents"></a>Table of Contents</h2>
|
|
<p class="toc">1 <a href="#introduction">Introduction</a><br />
|
|
    1.1 <a href="#what-is-xslt">What is
|
|
XSLT?</a><br />
|
|
    1.2 <a href="#whats-new-in-xslt2">What's
|
|
New in XSLT 2.1?</a><br />
|
|
2 <a href="#concepts">Concepts</a><br />
|
|
    2.1 <a href=
|
|
"#terminology">Terminology</a><br />
|
|
    2.2 <a href="#notation">Notation</a><br />
|
|
    2.3 <a href="#initiating">Initiating a
|
|
Transformation</a><br />
|
|
    2.4 <a href=
|
|
"#executing-a-transformation">Executing a Transformation</a><br />
|
|
    2.5 <a href="#context">The Evaluation
|
|
Context</a><br />
|
|
    2.6 <a href=
|
|
"#parsing-and-serialization">Parsing and Serialization</a><br />
|
|
    2.7 <a href=
|
|
"#extensibility">Extensibility</a><br />
|
|
    2.8 <a href=
|
|
"#stylesheets-and-schemas">Stylesheets and XML Schemas</a><br />
|
|
    2.9 <a href=
|
|
"#streaming-concepts">Streaming</a><br />
|
|
    2.10 <a href="#errors">Error
|
|
Handling</a><br />
|
|
3 <a href="#stylesheet-structure">Stylesheet Structure</a><br />
|
|
    3.1 <a href="#xslt-namespace">XSLT
|
|
Namespace</a><br />
|
|
    3.2 <a href="#reserved-namespaces">Reserved
|
|
Namespaces</a><br />
|
|
    3.3 <a href=
|
|
"#extension-attributes">Extension Attributes</a><br />
|
|
    3.4 <a href="#xslt-media-type">XSLT Media
|
|
Type</a><br />
|
|
    3.5 <a href="#standard-attributes">Standard
|
|
Attributes</a><br />
|
|
    3.6 <a href=
|
|
"#stylesheet-element">Stylesheet Element</a><br />
|
|
        3.6.1 <a href=
|
|
"#default-collation-attribute">The default-collation
|
|
attribute</a><br />
|
|
        3.6.2 <a href=
|
|
"#default-mode">The default-mode attribute</a><br />
|
|
        3.6.3 <a href=
|
|
"#user-defined-top-level">User-defined Data Elements</a><br />
|
|
    3.7 <a href=
|
|
"#simplified-stylesheet">Simplified Stylesheet Modules</a><br />
|
|
    3.8 <a href="#backwards">Backwards
|
|
Compatible Processing</a><br />
|
|
        3.8.1 <a href=
|
|
"#backwards-1.0">XSLT 1.0 compatibility mode</a><br />
|
|
        3.8.2 <a href=
|
|
"#backwards-2.0">XSLT 2.0 compatibility mode</a><br />
|
|
    3.9 <a href="#forwards">Forwards Compatible
|
|
Processing</a><br />
|
|
    3.10 <a href="#combining-modules">Combining
|
|
Stylesheet Modules</a><br />
|
|
        3.10.1 <a href=
|
|
"#locating-modules">Locating Stylesheet Modules</a><br />
|
|
        3.10.2 <a href=
|
|
"#include">Stylesheet Inclusion</a><br />
|
|
        3.10.3 <a href=
|
|
"#import">Stylesheet Import</a><br />
|
|
    3.11 <a href="#embedded">Embedded
|
|
Stylesheet Modules</a><br />
|
|
    3.12 <a href=
|
|
"#conditional-inclusion">Conditional Element Inclusion</a><br />
|
|
    3.13 <a href="#built-in-types">Built-in
|
|
Types</a><br />
|
|
    3.14 <a href="#import-schema">Importing
|
|
Schema Components</a><br />
|
|
4 <a href="#data-model">Data Model</a><br />
|
|
    4.1 <a href="#xml-versions">XML
|
|
Versions</a><br />
|
|
    4.2 <a href=
|
|
"#stylesheet-stripping">Stripping Whitespace from the
|
|
Stylesheet</a><br />
|
|
    4.3 <a href=
|
|
"#stripping-annotations">Stripping Type Annotations from a Source
|
|
Tree</a><br />
|
|
    4.4 <a href="#strip">Stripping Whitespace
|
|
from a Source Tree</a><br />
|
|
    4.5 <a href="#id-in-data-model">Attribute
|
|
Types and DTD Validation</a><br />
|
|
    4.6 <a href="#model-for-streaming">Data
|
|
Model for Streaming</a><br />
|
|
    4.7 <a href="#limits">Limits</a><br />
|
|
    4.8 <a href="#d-o-e-in-data-model">Disable
|
|
Output Escaping</a><br />
|
|
5 <a href="#constructs">Features of the XSLT Language</a><br />
|
|
    5.1 <a href="#qname">Qualified
|
|
Names</a><br />
|
|
    5.2 <a href="#unprefixed-qnames">Unprefixed
|
|
QNames in Expressions and Patterns</a><br />
|
|
    5.3 <a href=
|
|
"#expressions">Expressions</a><br />
|
|
    5.4 <a href=
|
|
"#static-and-dynamic-context">The Static and Dynamic
|
|
Context</a><br />
|
|
        5.4.1 <a href=
|
|
"#static-context">Initializing the Static Context</a><br />
|
|
        5.4.2 <a href=
|
|
"#additional-static-context">Additional Static Context Components
|
|
used by XSLT</a><br />
|
|
        5.4.3 <a href=
|
|
"#xpath-dynamic-context">Initializing the Dynamic Context</a><br />
|
|
            5.4.3.1
|
|
<a href="#focus">Maintaining Position: the Focus</a><br />
|
|
            5.4.3.2
|
|
<a href="#evaluation-context">Other components of the XPath Dynamic
|
|
Context</a><br />
|
|
        5.4.4 <a href=
|
|
"#additional-dynamic-context">Additional Dynamic Context Components
|
|
used by XSLT</a><br />
|
|
    5.5 <a href="#patterns">Patterns</a><br />
|
|
        5.5.1 <a href=
|
|
"#pattern-examples">Examples of Patterns</a><br />
|
|
        5.5.2 <a href=
|
|
"#pattern-syntax">Syntax of Patterns</a><br />
|
|
        5.5.3 <a href=
|
|
"#pattern-semantics">The Meaning of a Pattern</a><br />
|
|
        5.5.4 <a href=
|
|
"#pattern-errors">Errors in Patterns</a><br />
|
|
    5.6 <a href=
|
|
"#attribute-value-templates">Attribute Value Templates</a><br />
|
|
    5.7 <a href=
|
|
"#sequence-constructors">Sequence Constructors</a><br />
|
|
        5.7.1 <a href=
|
|
"#constructing-complex-content">Constructing Complex
|
|
Content</a><br />
|
|
        5.7.2 <a href=
|
|
"#constructing-simple-content">Constructing Simple
|
|
Content</a><br />
|
|
        5.7.3 <a href=
|
|
"#namespace-fixup">Namespace Fixup</a><br />
|
|
    5.8 <a href="#uri-references">URI
|
|
References</a><br />
|
|
6 <a href="#rules">Template Rules</a><br />
|
|
    6.1 <a href="#defining-templates">Defining
|
|
Templates</a><br />
|
|
    6.2 <a href=
|
|
"#defining-template-rules">Defining Template Rules</a><br />
|
|
    6.3 <a href="#applying-templates">Applying
|
|
Template Rules</a><br />
|
|
    6.4 <a href="#conflict">Conflict Resolution
|
|
for Template Rules</a><br />
|
|
    6.5 <a href="#default-priority">Default
|
|
Priority for Template Rules</a><br />
|
|
    6.6 <a href="#modes">Modes</a><br />
|
|
        6.6.1 <a href=
|
|
"#declaring-modes">Declaring Modes</a><br />
|
|
        6.6.2 <a href=
|
|
"#initial-context-for-mode">Declaring the initial context item for
|
|
a mode</a><br />
|
|
        6.6.3 <a href=
|
|
"#using-modes">Using Modes</a><br />
|
|
    6.7 <a href="#built-in-rule">Built-in
|
|
Template Rules</a><br />
|
|
        6.7.1 <a href=
|
|
"#built-in-templates-stringify">Built-in Templates:
|
|
stringify</a><br />
|
|
        6.7.2 <a href=
|
|
"#built-in-templates-discard">Built-in Templates: discard</a><br />
|
|
        6.7.3 <a href=
|
|
"#built-in-templates-copy">Built-in Templates: copy</a><br />
|
|
        6.7.4 <a href=
|
|
"#built-in-templates-fail">Built-in Templates: fail</a><br />
|
|
    6.8 <a href="#apply-imports">Overriding
|
|
Template Rules</a><br />
|
|
    6.9 <a href=
|
|
"#parameters-to-template-rules">Passing Parameters to Template
|
|
Rules</a><br />
|
|
7 <a href="#repetition">Repetition</a><br />
|
|
    7.1 <a href="#for-each">The xsl:for-each
|
|
instruction</a><br />
|
|
    7.2 <a href="#iterate">The xsl:iterate
|
|
instruction</a><br />
|
|
8 <a href="#conditionals">Conditional Processing</a><br />
|
|
    8.1 <a href="#xsl-if">Conditional
|
|
Processing with xsl:if</a><br />
|
|
    8.2 <a href="#xsl-choose">Conditional
|
|
Processing with xsl:choose</a><br />
|
|
    8.3 <a href=
|
|
"#try-catch">Try/Catch</a><br />
|
|
        8.3.1 <a href=
|
|
"#try-catch-examples">Try/Catch Examples</a><br />
|
|
9 <a href="#variables-and-parameters">Variables and
|
|
Parameters</a><br />
|
|
    9.1 <a href=
|
|
"#variables">Variables</a><br />
|
|
    9.2 <a href=
|
|
"#parameters">Parameters</a><br />
|
|
    9.3 <a href="#variable-values">Values of
|
|
Variables and Parameters</a><br />
|
|
    9.4 <a href="#temporary-trees">Creating
|
|
implicit document nodes</a><br />
|
|
    9.5 <a href="#global-variables">Global
|
|
Variables and Parameters</a><br />
|
|
    9.6 <a href="#local-variables">Local
|
|
Variables and Parameters</a><br />
|
|
    9.7 <a href="#scope-of-variables">Scope of
|
|
Variables</a><br />
|
|
    9.8 <a href="#with-param">Setting Parameter
|
|
Values</a><br />
|
|
    9.9 <a href="#circularity">Circular
|
|
Definitions</a><br />
|
|
10 <a href="#callable-components">Callable Components</a><br />
|
|
    10.1 <a href="#named-templates">Named
|
|
Templates</a><br />
|
|
        10.1.1 <a href=
|
|
"#call-template-params">Passing Parameters to Named
|
|
Templates</a><br />
|
|
        10.1.2 <a href=
|
|
"#tunnel-params">Tunnel Parameters</a><br />
|
|
    10.2 <a href="#attribute-sets">Named
|
|
Attribute Sets</a><br />
|
|
    10.3 <a href=
|
|
"#stylesheet-functions">Stylesheet Functions</a><br />
|
|
    10.4 <a href="#dynamic-xpath">Dynamic XPath
|
|
Evaluation</a><br />
|
|
11 <a href="#creating-new-nodes">Creating Nodes and
|
|
Sequences</a><br />
|
|
    11.1 <a href=
|
|
"#literal-result-element">Literal Result Elements</a><br />
|
|
        11.1.1 <a href=
|
|
"#setting-annotation-for-lre">Setting the Type Annotation for
|
|
Literal Result Elements</a><br />
|
|
        11.1.2 <a href=
|
|
"#attributes-for-lres">Attribute Nodes for Literal Result
|
|
Elements</a><br />
|
|
        11.1.3 <a href=
|
|
"#lre-namespaces">Namespace Nodes for Literal Result
|
|
Elements</a><br />
|
|
        11.1.4 <a href=
|
|
"#namespace-aliasing">Namespace Aliasing</a><br />
|
|
    11.2 <a href="#xsl-element">Creating
|
|
Element Nodes Using xsl:element</a><br />
|
|
        11.2.1 <a href=
|
|
"#annotation-for-constructed-element">Setting the Type Annotation
|
|
for a Constructed Element Node</a><br />
|
|
    11.3 <a href=
|
|
"#creating-attributes">Creating Attribute Nodes Using
|
|
xsl:attribute</a><br />
|
|
        11.3.1 <a href=
|
|
"#annotation-for-constructed-attribute">Setting the Type Annotation
|
|
for a Constructed Attribute Node</a><br />
|
|
    11.4 <a href=
|
|
"#creating-text-nodes">Creating Text Nodes</a><br />
|
|
        11.4.1 <a href=
|
|
"#literal-text-nodes">Literal Text Nodes</a><br />
|
|
        11.4.2 <a href=
|
|
"#xsl-text">Creating Text Nodes Using xsl:text</a><br />
|
|
        11.4.3 <a href=
|
|
"#value-of">Generating Text with xsl:value-of</a><br />
|
|
    11.5 <a href=
|
|
"#creating-document-nodes">Creating Document Nodes</a><br />
|
|
    11.6 <a href=
|
|
"#creating-processing-instructions">Creating Processing
|
|
Instructions</a><br />
|
|
    11.7 <a href=
|
|
"#creating-namespace-nodes">Creating Namespace Nodes</a><br />
|
|
    11.8 <a href="#creating-comments">Creating
|
|
Comments</a><br />
|
|
    11.9 <a href="#copying">Copying
|
|
Nodes</a><br />
|
|
        11.9.1 <a href=
|
|
"#shallow-copy">Shallow Copy</a><br />
|
|
        11.9.2 <a href=
|
|
"#copy-of">Deep Copy</a><br />
|
|
    11.10 <a href=
|
|
"#constructing-sequences">Constructing Sequences</a><br />
|
|
12 <a href="#number">Numbering</a><br />
|
|
    12.1 <a href=
|
|
"#formatting-supplied-number">Formatting a Supplied
|
|
Number</a><br />
|
|
    12.2 <a href=
|
|
"#numbering-based-on-position">Numbering based on Position in a
|
|
Document</a><br />
|
|
    12.3 <a href="#convert">Number to String
|
|
Conversion Attributes</a><br />
|
|
13 <a href="#sorting">Sorting</a><br />
|
|
    13.1 <a href="#xsl-sort">The xsl:sort
|
|
Element</a><br />
|
|
        13.1.1 <a href=
|
|
"#sorting-process">The Sorting Process</a><br />
|
|
        13.1.2 <a href=
|
|
"#comparing-sort-keys">Comparing Sort Key Values</a><br />
|
|
        13.1.3 <a href=
|
|
"#collating-sequences">Sorting Using Collations</a><br />
|
|
    13.2 <a href=
|
|
"#creating-sorted-sequence">Creating a Sorted Sequence</a><br />
|
|
    13.3 <a href="#sorted-iteration">Processing
|
|
a Sequence in Sorted Order</a><br />
|
|
14 <a href="#grouping">Grouping</a><br />
|
|
    14.1 <a href="#current-group">The Current
|
|
Group</a><br />
|
|
    14.2 <a href="#current-grouping-key">The
|
|
Current Grouping Key</a><br />
|
|
    14.3 <a href="#xsl-for-each-group">The
|
|
xsl:for-each-group Element</a><br />
|
|
    14.4 <a href="#grouping-examples">Examples
|
|
of Grouping</a><br />
|
|
    14.5 <a href=
|
|
"#non-transitivity">Non-Transitivity</a><br />
|
|
15 <a href="#merging">Merging</a><br />
|
|
    15.1 <a href=
|
|
"#merge-terminology">Terminology for merging</a><br />
|
|
    15.2 <a href="#merge-instruction">The
|
|
xsl:merge instruction</a><br />
|
|
    15.3 <a href=
|
|
"#merge-input-sequences">Selecting the sequences to be
|
|
merged</a><br />
|
|
    15.4 <a href="#merge-keys">Defining the
|
|
merge keys</a><br />
|
|
    15.5 <a href="#merge-action">The
|
|
xsl:merge-action element</a><br />
|
|
    15.6 <a href=
|
|
"#selective-processing-of-merge-inputs">Selective processing of
|
|
merge inputs</a><br />
|
|
    15.7 <a href=
|
|
"#merging-streamed-inputs">Merging streamed input
|
|
documents</a><br />
|
|
    15.8 <a href="#merge-examples">Examples of
|
|
xsl:merge</a><br />
|
|
16 <a href="#splitting">Splitting</a><br />
|
|
    16.1 <a href=
|
|
"#splitting-introduction">Introduction</a><br />
|
|
    16.2 <a href="#fork-instruction">The
|
|
xsl:fork instruction</a><br />
|
|
    16.3 <a href="#splitting-examples">Examples
|
|
of splitting with streamed data</a><br />
|
|
17 <a href="#regular-expressions">Regular Expressions</a><br />
|
|
    17.1 <a href="#analyze-string">The
|
|
xsl:analyze-string instruction</a><br />
|
|
    17.2 <a href="#regex-group">Captured
|
|
Substrings</a><br />
|
|
    17.3 <a href="#regex-examples">Examples of
|
|
Regular Expression Matching</a><br />
|
|
18 <a href="#streaming">Streaming</a><br />
|
|
    18.1 <a href="#stream-instruction">The
|
|
xsl:stream instruction</a><br />
|
|
        18.1.1 <a href=
|
|
"#stream-examples">Examples of xsl:stream</a><br />
|
|
    18.2 <a href=
|
|
"#streamable-templates">Streamable Templates</a><br />
|
|
    18.3 <a href=
|
|
"#streamable-patterns">Streamable patterns</a><br />
|
|
    18.4 <a href="#streamability">Streamability
|
|
Analysis</a><br />
|
|
        18.4.1 <a href=
|
|
"#building-expression-tree">Building an Expression Tree</a><br />
|
|
        18.4.2 <a href=
|
|
"#expanding-expr-tree">Expanding the Expression Tree</a><br />
|
|
            18.4.2.1
|
|
<a href="#expanding-xsl-number">Expanding the xsl:number
|
|
instruction</a><br />
|
|
            18.4.2.2
|
|
<a href="#expanding-xsl-merge">Expanding the xsl:merge
|
|
instruction</a><br />
|
|
        18.4.3 <a href=
|
|
"#analyzing-navigation">Analyzing Navigation</a><br />
|
|
            18.4.3.1
|
|
<a href="#marking-contributing-expr">Marking contributing child
|
|
constructs</a><br />
|
|
            18.4.3.2
|
|
<a href="#tracing-variable-references">Analyzing variable
|
|
references</a><br />
|
|
            18.4.3.3
|
|
<a href="#tracing-context-path">Tracing the Context of an
|
|
Expression</a><br />
|
|
        18.4.4 <a href=
|
|
"#streamability-choice-and-repetition">Analyzing choices,
|
|
repetition, and calls</a><br />
|
|
            18.4.4.1
|
|
<a href="#expr-tree-choices">Analyzing conditional
|
|
constructs</a><br />
|
|
            18.4.4.2
|
|
<a href="#expr-parallel-branches">Analyzing parallel
|
|
branches</a><br />
|
|
            18.4.4.3
|
|
<a href="#expr-tree-loops">Analyzing looping constructs</a><br />
|
|
            18.4.4.4
|
|
<a href="#expr-tree-sorting">Analyzing sorting constructs</a><br />
|
|
            18.4.4.5
|
|
<a href="#streamability-of-dynamic-invocation">Analyzing dynamic
|
|
invocation</a><br />
|
|
            18.4.4.6
|
|
<a href="#streamability-of-static-invocation">Analyzing calls to
|
|
functions, templates, and attribute sets</a><br />
|
|
            18.4.4.7
|
|
<a href="#streamability-iterate">Analyzing the streamability of
|
|
xsl:iterate</a><br />
|
|
        18.4.5 <a href=
|
|
"#streamability-conditions">Streamability Conditions</a><br />
|
|
        18.4.6 <a href=
|
|
"#notes-on-descendant-axis-streamability">Notes on the
|
|
streamability of paths using the descendant axis</a><br />
|
|
        18.4.7 <a href=
|
|
"#streamability-examples">Examples of streamability
|
|
analysis</a><br />
|
|
        18.4.8 <a href=
|
|
"#streamability-analysis-notes">Notes on the streamability
|
|
algorithm</a><br />
|
|
    18.5 <a href="#copy-of-function">The
|
|
copy-of function</a><br />
|
|
    18.6 <a href="#snapshot">The snapshot
|
|
function</a><br />
|
|
    18.7 <a href="#outermost">The outermost
|
|
function</a><br />
|
|
    18.8 <a href="#innermost">The innermost
|
|
function</a><br />
|
|
    18.9 <a href="#has-children">The
|
|
has-children function</a><br />
|
|
19 <a href="#add-func">Additional Functions</a><br />
|
|
    19.1 <a href=
|
|
"#multiple-source-documents">Multiple Source Documents</a><br />
|
|
        19.1.1 <a href=
|
|
"#document">The document function</a><br />
|
|
        19.1.2 <a href=
|
|
"#uri-collection">The uri-collection function</a><br />
|
|
    19.2 <a href="#unparsed-text">Reading Text
|
|
Files</a><br />
|
|
        19.2.1 <a href=
|
|
"#unparsed-text-function">The unparsed-text function</a><br />
|
|
        19.2.2 <a href=
|
|
"#unparsed-text-lines">The unparsed-text-lines function</a><br />
|
|
        19.2.3 <a href=
|
|
"#unparsed-text-available">The unparsed-text-available
|
|
function</a><br />
|
|
    19.3 <a href="#key">Keys</a><br />
|
|
        19.3.1 <a href=
|
|
"#xsl-key">The xsl:key Declaration</a><br />
|
|
        19.3.2 <a href=
|
|
"#keys">The key Function</a><br />
|
|
    19.4 <a href=
|
|
"#defining-decimal-format">Defining a Decimal Format</a><br />
|
|
    19.5 <a href="#misc-func">Miscellaneous
|
|
Additional Functions</a><br />
|
|
        19.5.1 <a href=
|
|
"#current-function">current</a><br />
|
|
        19.5.2 <a href=
|
|
"#unparsed-entity-uri">unparsed-entity-uri</a><br />
|
|
        19.5.3 <a href=
|
|
"#unparsed-entity-public-id">unparsed-entity-public-id</a><br />
|
|
        19.5.4 <a href=
|
|
"#system-property">system-property</a><br />
|
|
    19.7 <a href=
|
|
"#context-dependent-functions">Function items and
|
|
context-dependency</a><br />
|
|
20 <a href="#message">Messages</a><br />
|
|
21 <a href="#extension">Extensibility and Fallback</a><br />
|
|
    21.1 <a href=
|
|
"#extension-functions">Extension Functions</a><br />
|
|
        21.1.1 <a href=
|
|
"#testing-function-availability">Testing Availability of
|
|
Functions</a><br />
|
|
        21.1.2 <a href=
|
|
"#calling-extension-functions">Calling Extension
|
|
Functions</a><br />
|
|
        21.1.3 <a href=
|
|
"#external-objects">External Objects</a><br />
|
|
        21.1.4 <a href=
|
|
"#testing-type-availability">Testing Availability of
|
|
Types</a><br />
|
|
    21.2 <a href=
|
|
"#extension-instruction">Extension Instructions</a><br />
|
|
        21.2.1 <a href=
|
|
"#designating-extension-namespace">Designating an Extension
|
|
Namespace</a><br />
|
|
        21.2.2 <a href=
|
|
"#testing-instruction-available">Testing Availability of
|
|
Instructions</a><br />
|
|
        21.2.3 <a href=
|
|
"#fallback">Fallback</a><br />
|
|
22 <a href="#result-trees">Final Result Trees</a><br />
|
|
    22.1 <a href=
|
|
"#creating-result-trees">Creating Final Result Trees</a><br />
|
|
    22.2 <a href=
|
|
"#validation">Validation</a><br />
|
|
        22.2.1 <a href=
|
|
"#validating-constructed-nodes">Validating Constructed Elements and
|
|
Attributes</a><br />
|
|
            22.2.1.1
|
|
<a href="#validating-using-validation-attribute">Validation using
|
|
the [xsl:]validation Attribute</a><br />
|
|
            22.2.1.2
|
|
<a href="#validation-xsl-type">Validation using the [xsl:]type
|
|
Attribute</a><br />
|
|
            22.2.1.3
|
|
<a href="#validation-process">The Validation Process</a><br />
|
|
        22.2.2 <a href=
|
|
"#validating-document-nodes">Validating Document Nodes</a><br />
|
|
23 <a href="#serialization">Serialization</a><br />
|
|
    23.1 <a href="#character-maps">Character
|
|
Maps</a><br />
|
|
    23.2 <a href=
|
|
"#disable-output-escaping">Disabling Output Escaping</a><br />
|
|
24 <a href="#conformance">Conformance</a><br />
|
|
    24.1 <a href="#basic-conformance">Basic
|
|
XSLT Processor</a><br />
|
|
    24.2 <a href=
|
|
"#schema-aware-conformance">Schema-Aware XSLT Processor</a><br />
|
|
    24.3 <a href=
|
|
"#serialization-feature">Serialization Feature</a><br />
|
|
    24.4 <a href=
|
|
"#backwards-compatibility-feature">Compatibility Features</a><br />
|
|
    24.5 <a href="#streaming-feature">Streaming
|
|
Feature</a><br /></p>
|
|
<h3><a name="appendices" id="appendices"></a>Appendices</h3>
|
|
<p class="toc">A <a href="#references">References</a><br />
|
|
    A.1 <a href=
|
|
"#normative-references">Normative References</a><br />
|
|
    A.2 <a href="#other-references">Other
|
|
References</a><br />
|
|
B <a href="#glossary">Glossary</a> (Non-Normative)<br />
|
|
C <a href="#element-syntax-summary">Element Syntax Summary</a>
|
|
(Non-Normative)<br />
|
|
D <a href="#error-summary">Summary of Error Conditions</a>
|
|
(Non-Normative)<br />
|
|
E <a href="#implementation-defined-features">Checklist of
|
|
Implementation-Defined Features</a> (Non-Normative)<br />
|
|
F <a href="#XSLT-defined-functions">List of XSLT-defined
|
|
functions</a> (Non-Normative)<br />
|
|
G <a href="#schema-for-xslt">Schema for XSLT Stylesheets</a>
|
|
(Non-Normative)<br />
|
|
H <a href="#acknowledgements">Acknowledgements</a>
|
|
(Non-Normative)<br />
|
|
I <a href="#open-issues">Summary of Open Issues</a>
|
|
(Non-Normative)<br />
|
|
J <a href="#changes-since-2.0">Changes since XSLT 2.0</a>
|
|
(Non-Normative)<br />
|
|
K <a href="#incompatibilities">Incompatibilities with XSLT 2.0</a>
|
|
(Non-Normative)<br /></p>
|
|
</div>
|
|
<hr />
|
|
<div class="body">
|
|
<div class="div1">
|
|
<h2><a name="introduction" id="introduction"></a>1 <a href=
|
|
"#introduction" style="text-decoration: none">Introduction</a></h2>
|
|
<div class="div2">
|
|
<h3><a name="what-is-xslt" id="what-is-xslt"></a>1.1 <a href=
|
|
"#what-is-xslt" style="text-decoration: none">What is
|
|
XSLT?</a></h3>
|
|
<p>This specification defines the syntax and semantics of the XSLT
|
|
<span>2.1</span> language.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-stylesheet" id="dt-stylesheet" title="stylesheet"></a>A
|
|
transformation in the XSLT language is expressed in the form of a
|
|
<b>stylesheet</b>, whose syntax is well-formed XML <a href=
|
|
"#REC-xml">[XML 1.0]</a> conforming to the Namespaces in XML
|
|
Recommendation <a href="#xml-names">[Namespaces in
|
|
XML]</a>.<span class="definition">]</span></p>
|
|
<p>A stylesheet generally includes elements that are defined by
|
|
XSLT as well as elements that are not defined by XSLT. XSLT-defined
|
|
elements are distinguished by use of the namespace
|
|
<code>http://www.w3.org/1999/XSL/Transform</code> (see <a href=
|
|
"#xslt-namespace"><i>3.1 XSLT Namespace</i></a>), which is referred
|
|
to in this specification as the <a title="XSLT namespace" class=
|
|
"termref" href="#dt-xslt-namespace">XSLT namespace</a>. Thus this
|
|
specification is a definition of the syntax and semantics of the
|
|
XSLT namespace.</p>
|
|
<p>The term <a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a> reflects the fact that one of the
|
|
important roles of XSLT is to add styling information to an XML
|
|
source document, by transforming it into a document consisting of
|
|
XSL formatting objects (see <a href="#xsl11">[XSL-FO]</a>), or into
|
|
another presentation-oriented format such as HTML, XHTML, or SVG.
|
|
However, XSLT is used for a wide range of transformation tasks, not
|
|
exclusively for formatting and presentation applications.</p>
|
|
<p>A transformation expressed in XSLT describes rules for
|
|
transforming zero or more source trees into one or more result
|
|
trees. The structure of these trees is described in <a href=
|
|
"#xpath-datamodel-11">[Data Model]</a>. The transformation is
|
|
achieved by a set of <a title="template rule" class="termref" href=
|
|
"#dt-template-rule">template rules</a>. A template rule associates
|
|
a <a title="pattern" class="termref" href=
|
|
"#dt-pattern">pattern</a>, which matches nodes in the source
|
|
document, with a <a title="sequence constructor" class="termref"
|
|
href="#dt-sequence-constructor">sequence constructor</a>. In many
|
|
cases, evaluating the sequence constructor will cause new nodes to
|
|
be constructed, which can be used to produce part of a result tree.
|
|
The structure of the result trees can be completely different from
|
|
the structure of the source trees. In constructing a result tree,
|
|
nodes from the source trees can be filtered and reordered, and
|
|
arbitrary structure can be added. This mechanism allows a <a title=
|
|
"stylesheet" class="termref" href="#dt-stylesheet">stylesheet</a>
|
|
to be applicable to a wide class of documents that have similar
|
|
source tree structures.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-principal-stylesheet-module" id=
|
|
"dt-principal-stylesheet-module" title=
|
|
"principal stylesheet module"></a>A <a title="stylesheet" class=
|
|
"termref" href="#dt-stylesheet">stylesheet</a> may consist of
|
|
several <a title="stylesheet module" class="termref" href=
|
|
"#dt-stylesheet-module">stylesheet modules</a>, contained in
|
|
different XML documents. For a given transformation, one of these
|
|
functions as the <b>principal stylesheet module</b>. The complete
|
|
<a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a> is assembled by finding the
|
|
<a title="stylesheet module" class="termref" href=
|
|
"#dt-stylesheet-module">stylesheet modules</a> referenced directly
|
|
or indirectly from the principal stylesheet module using <a href=
|
|
"#element-include"><code>xsl:include</code></a> and <a href=
|
|
"#element-import"><code>xsl:import</code></a> elements: see
|
|
<a href="#include"><i>3.10.2 Stylesheet Inclusion</i></a> and
|
|
<a href="#import"><i>3.10.3 Stylesheet Import</i></a>.<span class=
|
|
"definition">]</span></p>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="whats-new-in-xslt2" id="whats-new-in-xslt2"></a>1.2
|
|
<a href="#whats-new-in-xslt2" style="text-decoration: none">What's
|
|
New in XSLT 2.1?</a></h3>
|
|
<p>The main focus for enhancements in XSLT 2.1 is the requirement
|
|
to enable streaming of source documents. This is needed when source
|
|
documents become too large to hold in main memory, and also for
|
|
applications where it is important to start delivering results
|
|
before the entire source document is available.</p>
|
|
<p>While implementations of XSLT that use streaming have always
|
|
been theoretically possible, the nature of the language has made it
|
|
very difficult to achieve this in practice. The approach adopted in
|
|
this specification is twofold: it identifies a set of restrictions
|
|
which, if followed by stylesheet authors, will enable
|
|
implementations to adopt a streaming mode of operation without
|
|
placing excessive demands on the optimization capabilities of the
|
|
processor; and it provides new constructs to indicate that
|
|
streaming is required, or to express transformations in a way that
|
|
makes it easier for the processor to adopt a streaming execution
|
|
plan.</p>
|
|
<p>Capabilities provided in this category include:</p>
|
|
<ul>
|
|
<li>
|
|
<p>A new <a href="#element-stream"><code>xsl:stream</code></a>
|
|
instruction, which reads and processes a source document in
|
|
streaming mode;</p>
|
|
</li>
|
|
<li>
|
|
<p>The ability to declare that a <a title="mode" class="termref"
|
|
href="#dt-mode">mode</a> is a streaming mode, in which case all the
|
|
template rules using that mode must be streamable;</p>
|
|
</li>
|
|
<li>
|
|
<p>A new <a href="#element-iterate"><code>xsl:iterate</code></a>
|
|
instruction, which iterates over the items in a sequence, allowing
|
|
parameters for the processing of one item to be set during the
|
|
processing of the previous item;</p>
|
|
</li>
|
|
<li>
|
|
<p>A new <a href="#element-merge"><code>xsl:merge</code></a>
|
|
instruction, allowing multiple input streams to be merged into a
|
|
single output stream;</p>
|
|
</li>
|
|
<li>
|
|
<p>A new <a href="#element-fork"><code>xsl:fork</code></a>
|
|
instruction, allowing multiple computations to be performed in
|
|
parallel during a single pass through an input document.</p>
|
|
</li>
|
|
</ul>
|
|
<p>Other significant features in XSLT 2.1 include:</p>
|
|
<ul>
|
|
<li>
|
|
<p>An <a href="#element-evaluate"><code>xsl:evaluate</code></a>
|
|
instruction allowing evaluation of XPath expressions that are
|
|
dynamically constructed as strings, or that are read from a source
|
|
document;</p>
|
|
</li>
|
|
<li>
|
|
<p>Enhancements to the syntax of <a title="pattern" class="termref"
|
|
href="#dt-pattern">patterns</a>, in particular enabling the
|
|
matching of atomic values as well as nodes;</p>
|
|
</li>
|
|
<li>
|
|
<p>An <a href="#element-try"><code>xsl:try</code></a> instruction
|
|
to allow recovery from dynamic errors;</p>
|
|
</li>
|
|
<li>
|
|
<p>The element <a href=
|
|
"#element-context-item"><code>xsl:context-item</code></a>, used to
|
|
declare the stylesheet's expectations of the initial context item
|
|
(notably, its type), given the initial mode.</p>
|
|
</li>
|
|
</ul>
|
|
<p>XSLT 2.1 also delivers enhancements made to the XPath language
|
|
and to the standard function library, including the following:</p>
|
|
<ul>
|
|
<li>
|
|
<p>Variables can now be bound in XPath using the <code>let</code>
|
|
expression.</p>
|
|
</li>
|
|
<li>
|
|
<p>Functions are now first class values, and can be passed as
|
|
arguments to other (higher-order) functions, making XSLT a
|
|
fully-fledged functional programming language.</p>
|
|
</li>
|
|
<li>
|
|
<p>A number of new functions are available, for example
|
|
trigonometric functions, and the functions <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-parse"><code>parse</code></a><sup><small>FO</small></sup>
|
|
and <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-serialize"><code>serialize</code></a><sup><small>FO</small></sup>
|
|
to convert between lexical and tree representations of XML.</p>
|
|
</li>
|
|
</ul>
|
|
<p>The XSL Working Group is designing other new features which it
|
|
hopes to include in the final XSLT 2.1 Recommendation, but which
|
|
are not yet advanced enough to include in this Working Draft.</p>
|
|
<p>A full list of changes is at <a href="#changes-since-2.0"><i>J
|
|
Changes since XSLT 2.0</i></a>.</p>
|
|
</div>
|
|
</div>
|
|
<div class="div1">
|
|
<h2><a name="concepts" id="concepts"></a>2 <a href="#concepts"
|
|
style="text-decoration: none">Concepts</a></h2>
|
|
<div class="div2">
|
|
<h3><a name="terminology" id="terminology"></a>2.1 <a href=
|
|
"#terminology" style="text-decoration: none">Terminology</a></h3>
|
|
<p>For a full glossary of terms, see <a href="#glossary"><i>B
|
|
Glossary</i></a>.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-processor" id="dt-processor" title="processor"></a>The software
|
|
responsible for transforming source trees into result trees using
|
|
an XSLT stylesheet is referred to as the <b>processor</b>. This is
|
|
sometimes expanded to <em>XSLT processor</em> to avoid any
|
|
confusion with other processors, for example an XML
|
|
processor.<span class="definition">]</span></p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-implementation" id="dt-implementation" title=
|
|
"implementation"></a>A specific product that performs the functions
|
|
of an <a title="processor" class="termref" href=
|
|
"#dt-processor">XSLT processor</a> is referred to as an
|
|
<b>implementation</b>. <span class="definition">]</span></p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-result-tree" id="dt-result-tree" title="result tree"></a>The
|
|
term <b>result tree</b> is used to refer to any tree constructed by
|
|
<a title="instruction" class="termref" href=
|
|
"#dt-instruction">instructions</a> in the stylesheet. A result tree
|
|
is either a <a title="final result tree" class="termref" href=
|
|
"#dt-final-result-tree">final result tree</a> or a <a title=
|
|
"temporary tree" class="termref" href=
|
|
"#dt-temporary-tree">temporary tree</a>.<span class=
|
|
"definition">]</span></p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-final-result-tree" id="dt-final-result-tree" title=
|
|
"final result tree"></a>A <b>final result tree</b> is a <a title=
|
|
"result tree" class="termref" href="#dt-result-tree">result
|
|
tree</a> that forms part of the final output of a transformation.
|
|
Once created, the contents of a final result tree are not
|
|
accessible within the stylesheet itself.<span class=
|
|
"definition">]</span> The <a href=
|
|
"#element-result-document"><code>xsl:result-document</code></a>
|
|
instruction always creates a final result tree, and a final result
|
|
tree may also be created implicitly by the <a title=
|
|
"initial template" class="termref" href=
|
|
"#dt-initial-template">initial template</a>. The conditions under
|
|
which this happens are described in <a href=
|
|
"#executing-a-transformation"><i>2.4 Executing a
|
|
Transformation</i></a>. A final result tree <span class=
|
|
"verb">may</span> be serialized as described in <a href=
|
|
"#serialization"><i>23 Serialization</i></a>.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-source-tree" id="dt-source-tree" title="source tree"></a>The
|
|
term <b>source tree</b> means any tree provided as input to the
|
|
transformation. This includes the document containing the
|
|
<span><a title="initial context item" class="termref" href=
|
|
"#dt-initial-context-item">initial context item</a></span> if any,
|
|
documents containing nodes supplied as the values of <a title=
|
|
"stylesheet parameter" class="termref" href=
|
|
"#dt-stylesheet-parameter">stylesheet parameters</a>, documents
|
|
obtained from the results of functions such as <a href=
|
|
"#function-document"><code>document</code></a>, <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-doc"><code>doc</code></a><sup><small>FO</small></sup>,
|
|
and <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-collection"><code>collection</code></a><sup><small>FO</small></sup>,
|
|
<span>documents read using the <a href=
|
|
"#element-stream"><code>xsl:stream</code></a> instruction,</span>
|
|
and documents returned by extension functions or extension
|
|
instructions. In the context of a particular XSLT instruction, the
|
|
term <b>source tree</b> means any tree provided as input to that
|
|
instruction; this may be a source tree of the transformation as a
|
|
whole, or it may be a <a title="temporary tree" class="termref"
|
|
href="#dt-temporary-tree">temporary tree</a> produced during the
|
|
course of the transformation.<span class="definition">]</span></p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-temporary-tree" id="dt-temporary-tree" title=
|
|
"temporary tree"></a>The term <b>temporary tree</b> means any tree
|
|
that is neither a <a title="source tree" class="termref" href=
|
|
"#dt-source-tree">source tree</a> nor a <a title=
|
|
"final result tree" class="termref" href=
|
|
"#dt-final-result-tree">final result tree</a>.<span class=
|
|
"definition">]</span> Temporary trees are used to hold intermediate
|
|
results during the execution of the transformation.</p>
|
|
<p>The use of the term "tree" in phrases such as <b>source
|
|
tree</b>, <b>result tree</b>, and <b>temporary tree</b> is not
|
|
confined to documents that the processor materializes in memory in
|
|
their entirety. The processor <span class="verb">may</span>, and in
|
|
some cases <span class="verb">must</span>, use streaming techniques
|
|
to limit the amount of memory used to hold source and result
|
|
documents. When streaming is used, the nodes of the tree may never
|
|
all be in memory at the same time, but at an abstract level the
|
|
information is still modeled as a tree of nodes, and the document
|
|
is therefore still described as a tree.</p>
|
|
<p>In this specification the phrases <span class=
|
|
"verb">must</span>, <span class="verb">must not</span>,
|
|
<span class="verb">should</span>, <span class="verb">should
|
|
not</span>, <span class="verb">may</span>, <span class=
|
|
"verb">required</span>, and <span class="verb">recommended</span>,
|
|
<span>when used in normative text and rendered in capitals,</span>
|
|
are to be interpreted as described in <a href=
|
|
"#RFC2119">[RFC2119]</a>.</p>
|
|
<p>Where the phrase <span class="verb">must</span>, <span class=
|
|
"verb">must not</span>, or <span class="verb">required</span>
|
|
relates to the behavior of the XSLT processor, then an
|
|
implementation is not conformant unless it behaves as specified,
|
|
subject to the more detailed rules in <a href="#conformance"><i>24
|
|
Conformance</i></a>.</p>
|
|
<p>Where the phrase <span class="verb">must</span>, <span class=
|
|
"verb">must not</span>, or <span class="verb">required</span>
|
|
relates to a stylesheet then the processor <span class=
|
|
"verb">must</span> enforce this constraint on stylesheets by
|
|
reporting an error if the constraint is not satisfied.</p>
|
|
<p>Where the phrase <span class="verb">should</span>, <span class=
|
|
"verb">should not</span>, or <span class="verb">recommended</span>
|
|
relates to a stylesheet then a processor <span class=
|
|
"verb">may</span> produce warning messages if the constraint is not
|
|
satisfied, but <span class="verb">must not</span> treat this as an
|
|
error.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-implementation-defined" id="dt-implementation-defined" title=
|
|
"implementation-defined"></a>In this specification, the term
|
|
<b>implementation-defined</b> refers to a feature where the
|
|
implementation is allowed some flexibility, and where the choices
|
|
made by the implementation <span class="verb">must</span> be
|
|
described in documentation that accompanies any conformance
|
|
claim.<span class="definition">]</span></p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-implementation-dependent" id="dt-implementation-dependent"
|
|
title="implementation-dependent"></a>The term
|
|
<b>implementation-dependent</b> refers to a feature where the
|
|
behavior <span class="verb">may</span> vary from one implementation
|
|
to another, and where the vendor is not expected to provide a full
|
|
specification of the behavior.<span class="definition">]</span>
|
|
(This might apply, for example, to limits on the size of source
|
|
documents that can be transformed.)</p>
|
|
<p>In all cases where this specification leaves the behavior
|
|
implementation-defined or implementation-dependent, the
|
|
implementation has the option of providing mechanisms that allow
|
|
the user to influence the behavior.</p>
|
|
<p>A paragraph labeled as a <b>Note</b> or described as an
|
|
<b>example</b> is non-normative.</p>
|
|
<p>Many terms used in this document are defined in the XPath
|
|
specification <a href="#xpath-21">[XPath 2.1]</a> or the XDM
|
|
specification <a href="#xpath-datamodel-11">[Data Model]</a>.
|
|
Particular attention is drawn to the following:</p>
|
|
<ul>
|
|
<li>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-atomization" id="dt-atomization" title="atomize"></a>The term
|
|
<b>atomization</b> is defined in <a href=
|
|
"http://www.w3.org/TR/xpath-21/#id-atomization">Section 2.4.2
|
|
Atomization</a><sup><small>XP21</small></sup>. It is a process that
|
|
takes as input a sequence of <span>items</span>, and returns a
|
|
sequence of atomic values, in which the nodes are replaced by their
|
|
typed values as defined in <a href="#xpath-datamodel-11">[Data
|
|
Model]</a>.<span class="definition">]</span> For some
|
|
<span>items</span> (for example, elements with element-only
|
|
content, <span>and function items</span>), atomization generates a
|
|
<a title="dynamic error" class="termref" href=
|
|
"#dt-dynamic-error">dynamic error</a>.</p>
|
|
</li>
|
|
<li>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-typed-value" id="dt-typed-value" title="typed value"></a>The
|
|
term <b>typed value</b> is defined in <a href=
|
|
"http://www.w3.org/TR/xpath-datamodel-11/#dm-typed-value">Section
|
|
5.15 typed-value Accessor</a><sup><small>DM11</small></sup>. Every
|
|
node except an element defined in the schema with element-only
|
|
content has a <a title="string value" class="termref" href=
|
|
"#dt-string-value">typed value</a>. For example, the <a title=
|
|
"typed value" class="termref" href="#dt-typed-value">typed
|
|
value</a> of an attribute of type <code>xs:IDREFS</code> is a
|
|
sequence of zero or more <code>xs:IDREF</code> values.<span class=
|
|
"definition">]</span></p>
|
|
</li>
|
|
<li>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-string-value" id="dt-string-value" title="string value"></a>The
|
|
term <b>string value</b> is defined in <a href=
|
|
"http://www.w3.org/TR/xpath-datamodel-11/#dm-string-value">Section
|
|
5.13 string-value Accessor</a><sup><small>DM11</small></sup>. Every
|
|
node has a <a title="string value" class="termref" href=
|
|
"#dt-string-value">string value</a>. For example, the <a title=
|
|
"string value" class="termref" href="#dt-string-value">string
|
|
value</a> of an element is the concatenation of the <a title=
|
|
"string value" class="termref" href="#dt-string-value">string
|
|
values</a> of all its descendant text nodes.<span class=
|
|
"definition">]</span></p>
|
|
</li>
|
|
<li>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-xpath-compat-mode" id="dt-xpath-compat-mode" title=
|
|
"XPath 1.0 compatibility mode"></a>The term <b>XPath 1.0
|
|
compatibility mode</b> is defined in <a href=
|
|
"http://www.w3.org/TR/xpath-21/#static_context">Section 2.1.1
|
|
Static Context</a><sup><small>XP21</small></sup>. This is a setting
|
|
in the static context of an XPath expression; it has two values,
|
|
<code>true</code> and <code>false</code>. When the value is set to
|
|
true, the semantics of function calls and certain other operations
|
|
are adjusted to give a greater degree of backwards compatibility
|
|
between <span>XPath 2.1</span> and XPath 1.0.<span class=
|
|
"definition">]</span></p>
|
|
</li>
|
|
</ul>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-core-function" id="dt-core-function" title=
|
|
"core function"></a>The term <b>core function</b> means a function
|
|
that is specified in <a href="#xpath-functions-11">[Functions and
|
|
Operators]</a> and that is in the <a title=
|
|
"standard function namespace" class="termref" href=
|
|
"#dt-standard-function-namespace">standard function
|
|
namespace</a>.<span class="definition">]</span></p>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="notation" id="notation"></a>2.2 <a href="#notation"
|
|
style="text-decoration: none">Notation</a></h3>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-xslt-element" id="dt-xslt-element" title="XSLT element"></a>An
|
|
<b>XSLT element</b> is an element in the <a title="XSLT namespace"
|
|
class="termref" href="#dt-xslt-namespace">XSLT namespace</a> whose
|
|
syntax and semantics are defined in this specification.<span class=
|
|
"definition">]</span> For a non-normative list of XSLT elements,
|
|
see <a href="#element-syntax-summary"><i>C Element Syntax
|
|
Summary</i></a>.</p>
|
|
<p>In this document the specification of each <a title=
|
|
"XSLT element" class="termref" href="#dt-xslt-element">XSLT
|
|
element</a> is preceded by a summary of its syntax in the form of a
|
|
model for elements of that element type. A full list of all these
|
|
specifications can be found in <a href=
|
|
"#element-syntax-summary"><i>C Element Syntax Summary</i></a>. The
|
|
meaning of syntax summary notation is as follows:</p>
|
|
<ul>
|
|
<li>
|
|
<p>An attribute that is <span class="verb">required</span> is shown
|
|
with its name in bold. An attribute that may be omitted is shown
|
|
with a question mark following its name.</p>
|
|
</li>
|
|
<li>
|
|
<p>An attribute that is <a title="deprecated" class="termref" href=
|
|
"#dt-deprecated">deprecated</a> is shown in a grayed font within
|
|
square brackets.</p>
|
|
</li>
|
|
<li>
|
|
<p>The string that occurs in the place of an attribute value
|
|
specifies the allowed values of the attribute. If this is
|
|
surrounded by curly brackets (<code>{...}</code>), then the
|
|
attribute value is treated as an <a title=
|
|
"attribute value template" class="termref" href=
|
|
"#dt-attribute-value-template">attribute value template</a>, and
|
|
the string occurring within curly brackets specifies the allowed
|
|
values of the result of evaluating the attribute value template.
|
|
Alternative allowed values are separated by <code>|</code>. A
|
|
quoted string indicates a value equal to that specific string. An
|
|
unquoted, italicized name specifies a particular type of value.</p>
|
|
<p>Except where the set of allowed values of an attribute is
|
|
specified using the italicized name <em>string</em> or
|
|
<em>char</em>, leading and trailing whitespace in the attribute
|
|
value is ignored. In the case of an <a title=
|
|
"attribute value template" class="termref" href=
|
|
"#dt-attribute-value-template">attribute value template</a>, this
|
|
applies to the <a title="effective value" class="termref" href=
|
|
"#dt-effective-value">effective value</a> obtained when the
|
|
attribute value template is expanded.</p>
|
|
</li>
|
|
<li>
|
|
<p>Unless the element is <span class="verb">required</span> to be
|
|
empty, the model element contains a comment specifying the allowed
|
|
content. The allowed content is specified in a similar way to an
|
|
element type declaration in XML; <em>sequence constructor</em>
|
|
means that any mixture of text nodes, <a title=
|
|
"literal result element" class="termref" href=
|
|
"#dt-literal-result-element">literal result elements</a>, <a title=
|
|
"extension instruction" class="termref" href=
|
|
"#dt-extension-instruction">extension instructions</a>, and
|
|
<a title="XSLT element" class="termref" href=
|
|
"#dt-xslt-element">XSLT elements</a> from the <a title=
|
|
"instruction" class="termref" href=
|
|
"#dt-instruction">instruction</a> category is allowed;
|
|
<em>other-declarations</em> means that any mixture of XSLT elements
|
|
from the <a title="declaration" class="termref" href=
|
|
"#dt-declaration">declaration</a> category, other than <a href=
|
|
"#element-import"><code>xsl:import</code></a>, is allowed, together
|
|
with <a title="user-defined data element" class="termref" href=
|
|
"#dt-data-element">user-defined data elements</a>.</p>
|
|
</li>
|
|
<li>
|
|
<p>The element is prefaced by comments indicating if it belongs to
|
|
the <code>instruction</code> category or <code>declaration</code>
|
|
category or both. The category of an element only affects whether
|
|
it is allowed in the content of elements that allow a <a title=
|
|
"sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> or
|
|
<em>other-declarations</em>.</p>
|
|
</li>
|
|
</ul>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e800" id=
|
|
"d7e800"></a>Example: Syntax Notation</div>
|
|
<p>This example illustrates the notation used to describe <a title=
|
|
"XSLT element" class="termref" href="#dt-xslt-element">XSLT
|
|
elements</a>.</p>
|
|
<p class="element-syntax"><a name="element-example-element" id=
|
|
"element-example-element"></a><code><!-- Category: instruction
|
|
--><br />
|
|
<xsl:example-element<br />
|
|
  <b>select</b> = <var>expression</var><br />
|
|
  debug? = { "yes" | "no" } ><br />
|
|
  <!-- Content: ((<a href=
|
|
"#element-variable">xsl:variable</a> | <a href=
|
|
"#element-param">xsl:param</a>)*, <a href=
|
|
"#element-sequence">xsl:sequence</a>) --><br />
|
|
</xsl:example-element></code></p>
|
|
<p>This example defines a (non-existent) element
|
|
<code>xsl:example-element</code>. The element is classified as an
|
|
instruction. It takes a mandatory <code>select</code> attribute,
|
|
whose value is an XPath <a title="expression" class="termref" href=
|
|
"#dt-expression">expression</a>, and an optional <code>debug</code>
|
|
attribute, whose value <span class="verb">must</span> be either
|
|
<code>yes</code> or <code>no</code>; the curly brackets indicate
|
|
that the value can be defined as an <a title=
|
|
"attribute value template" class="termref" href=
|
|
"#dt-attribute-value-template">attribute value template</a>,
|
|
allowing a value such as <code>debug="{$debug}"</code>, where the
|
|
<a title="variable" class="termref" href=
|
|
"#dt-variable">variable</a> <code>debug</code> is evaluated to
|
|
yield <code>"yes"</code> or <code>"no"</code> at run-time.</p>
|
|
<p>The content of an <code>xsl:example-element</code> instruction
|
|
is defined to be a sequence of zero or more <a href=
|
|
"#element-variable"><code>xsl:variable</code></a> and <a href=
|
|
"#element-param"><code>xsl:param</code></a> elements, followed by
|
|
an <a href="#element-sequence"><code>xsl:sequence</code></a>
|
|
element.</p>
|
|
</div>
|
|
<p><a name="err-XTSE0010" id="err-XTSE0010"><span class=
|
|
"error">[ERR XTSE0010]</span></a> A <a title="static error" class=
|
|
"termref" href="#dt-static-error">static error</a> is signaled if
|
|
an XSLT-defined element is used in a context where it is not
|
|
permitted, if a <span class="verb">required</span> attribute is
|
|
omitted, or if the content of the element does not correspond to
|
|
the content that is allowed for the element.</p>
|
|
<p>Attributes are validated as follows. These rules apply to the
|
|
value of the attribute after removing leading and trailing
|
|
whitespace.</p>
|
|
<ul>
|
|
<li>
|
|
<p><a name="err-XTSE0020" id="err-XTSE0020"><span class=
|
|
"error">[ERR XTSE0020]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> if an
|
|
attribute (other than an attribute written using curly brackets in
|
|
a position where an <a title="attribute value template" class=
|
|
"termref" href="#dt-attribute-value-template">attribute value
|
|
template</a> is permitted) contains a value that is not one of the
|
|
permitted values for that attribute.</p>
|
|
</li>
|
|
<li>
|
|
<p><a name="err-XTDE0030" id="err-XTDE0030"><span class=
|
|
"error">[ERR XTDE0030]</span></a> It is a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> if the
|
|
<a title="effective value" class="termref" href=
|
|
"#dt-effective-value">effective value</a> of an attribute written
|
|
using curly brackets, in a position where an <a title=
|
|
"attribute value template" class="termref" href=
|
|
"#dt-attribute-value-template">attribute value template</a> is
|
|
permitted, is a value that is not one of the permitted values for
|
|
that attribute. If the processor is able to detect the error
|
|
statically (for example, when any XPath expressions within the
|
|
curly brackets can be evaluated statically), then the processor may
|
|
optionally signal this as a static error.</p>
|
|
</li>
|
|
</ul>
|
|
<p>Special rules apply if the construct appears in part of the
|
|
<a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a> that is processed with <a title=
|
|
"forwards compatible behavior" class="termref" href=
|
|
"#dt-forwards-compatible-behavior">forwards compatible
|
|
behavior</a>: see <a href="#forwards"><i>3.9 Forwards Compatible
|
|
Processing</i></a>.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-deprecated" id="dt-deprecated" title="deprecated"></a>Some
|
|
constructs defined in this specification are described as being
|
|
<b>deprecated</b>. The use of this term implies that stylesheet
|
|
authors <span class="verb">should not</span> use the construct, and
|
|
that the construct may be removed in a later version of this
|
|
specification.<span class="definition">]</span> All constructs that
|
|
are <a title="deprecated" class="termref" href=
|
|
"#dt-deprecated">deprecated</a> in this specification are also (as
|
|
it happens) optional features that <a title="implementation" class=
|
|
"termref" href="#dt-implementation">implementations</a> are
|
|
<span class="verb">not required</span> to provide.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>This working draft includes a non-normative XML Schema for XSLT
|
|
<a title="stylesheet module" class="termref" href=
|
|
"#dt-stylesheet-module">stylesheet modules</a> (see <a href=
|
|
"#schema-for-xslt"><i>G Schema for XSLT Stylesheets</i></a>). The
|
|
syntax summaries described in this section are normative.</p>
|
|
</div>
|
|
<p>XSLT defines a set of standard functions which are additional to
|
|
those defined in <a href="#xpath-functions-11">[Functions and
|
|
Operators]</a>. The signatures of these functions are described
|
|
using the same notation as used in <a href=
|
|
"#xpath-functions-11">[Functions and Operators]</a>. The names of
|
|
these functions are all in the <a title=
|
|
"standard function namespace" class="termref" href=
|
|
"#dt-standard-function-namespace">standard function
|
|
namespace</a>.</p>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="initiating" id="initiating"></a>2.3 <a href=
|
|
"#initiating" style="text-decoration: none">Initiating a
|
|
Transformation</a></h3>
|
|
<p>This document does not specify any application programming
|
|
interfaces or other interfaces for initiating a transformation.
|
|
This section, however, describes the information that is supplied
|
|
when a transformation is initiated. Except where otherwise
|
|
indicated, the information is <span class=
|
|
"verb">required</span>.</p>
|
|
<p>Implementations <span class="verb">may</span> allow a
|
|
transformation to run as two or more phases, for example parsing,
|
|
compilation and execution. Such a distinction is outside the scope
|
|
of this specification, which treats transformation as a single
|
|
process controlled using a set of <a title="stylesheet module"
|
|
class="termref" href="#dt-stylesheet-module">stylesheet
|
|
modules</a>, supplied in the form of XML documents.</p>
|
|
<p>The following information is supplied to execute a
|
|
transformation:</p>
|
|
<ul>
|
|
<li>
|
|
<p>The <a title="stylesheet module" class="termref" href=
|
|
"#dt-stylesheet-module">stylesheet module</a> that is to act as the
|
|
<a title="principal stylesheet module" class="termref" href=
|
|
"#dt-principal-stylesheet-module">principal stylesheet module</a>
|
|
for the transformation. The complete <a title="stylesheet" class=
|
|
"termref" href="#dt-stylesheet">stylesheet</a> is assembled by
|
|
recursively expanding the <a href=
|
|
"#element-import"><code>xsl:import</code></a> and <a href=
|
|
"#element-include"><code>xsl:include</code></a> declarations in the
|
|
principal stylesheet module, as described in <a href=
|
|
"#include"><i>3.10.2 Stylesheet Inclusion</i></a> and <a href=
|
|
"#import"><i>3.10.3 Stylesheet Import</i></a>.</p>
|
|
</li>
|
|
<li>
|
|
<p>A set (possibly empty) of values for <a title=
|
|
"stylesheet parameter" class="termref" href=
|
|
"#dt-stylesheet-parameter">stylesheet parameters</a> (see <a href=
|
|
"#global-variables"><i>9.5 Global Variables and
|
|
Parameters</i></a>). These values are available for use within
|
|
<a title="expression" class="termref" href=
|
|
"#dt-expression">expressions</a> in the <a title="stylesheet"
|
|
class="termref" href="#dt-stylesheet">stylesheet</a>.</p>
|
|
</li>
|
|
<li>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-initial-context-item" id="dt-initial-context-item" title=
|
|
"initial context item"></a>An item that acts as the <b>initial
|
|
context item</b> for the transformation. This item is accessible
|
|
within the <a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a> as the initial value of the XPath
|
|
<a title="expression" class="termref" href=
|
|
"#dt-expression">expressions</a> <code>.</code> (dot) and
|
|
<code>self::node()</code>, as described in <a href=
|
|
"#focus"><i>5.4.3.1 Maintaining Position: the Focus</i></a>
|
|
<span class="definition">]</span>.</p>
|
|
<p>The value that can be supplied as the <span><a title=
|
|
"initial context item" class="termref" href=
|
|
"#dt-initial-context-item">initial context item</a></span> is
|
|
constrained by the <a href=
|
|
"#element-context-item"><code>xsl:context-item</code></a> element,
|
|
if defined for the chosen <a title="initial mode" class="termref"
|
|
href="#dt-initial-mode">initial mode</a>.</p>
|
|
<p>If no initial context item is supplied, then the <a title=
|
|
"context item" class="termref" href="#dt-context-item">context
|
|
item</a>, <a title="context position" class="termref" href=
|
|
"#dt-context-position">context position</a>, and <a title=
|
|
"context size" class="termref" href="#dt-context-size">context
|
|
size</a> will initially be undefined, and the evaluation of any
|
|
expression that references these values will result in a dynamic
|
|
error. (Note that the initial context size and context position
|
|
will always be 1 (one) when an <span><a title=
|
|
"initial context item" class="termref" href=
|
|
"#dt-initial-context-item">initial context item</a></span> is
|
|
supplied, and will be undefined if no initial context item is
|
|
supplied).</p>
|
|
</li>
|
|
<li>
|
|
<p>Optionally, the name of a <a title="named template" class=
|
|
"termref" href="#dt-named-template">named template</a> which is to
|
|
be executed as the entry point to the transformation. This template
|
|
<span class="verb">must</span> exist within the <a title=
|
|
"stylesheet" class="termref" href="#dt-stylesheet">stylesheet</a>.
|
|
If no named template is supplied, then the transformation starts
|
|
with the <a title="template rule" class="termref" href=
|
|
"#dt-template-rule">template rule</a> that best matches the
|
|
<span><a title="initial context item" class="termref" href=
|
|
"#dt-initial-context-item">initial context item</a></span>,
|
|
according to the rules defined in <a href="#conflict"><i>6.4
|
|
Conflict Resolution for Template Rules</i></a>. Either a named
|
|
template, or an initial context item, or both, <span class=
|
|
"verb">must</span> be supplied.</p>
|
|
</li>
|
|
<li>
|
|
<p>Optionally, an initial <a title="mode" class="termref" href=
|
|
"#dt-mode">mode</a>.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-initial-mode" id="dt-initial-mode" title="initial mode"></a>The
|
|
initial mode, if specified, <span class="verb">must</span> either
|
|
be the default mode, or a mode that is explicitly named in the
|
|
<code>mode</code> attribute of an <a href=
|
|
"#element-template"><code>xsl:template</code></a> declaration
|
|
within the stylesheet. If an initial mode is supplied, then in
|
|
searching for the <a title="template rule" class="termref" href=
|
|
"#dt-template-rule">template rule</a> that best matches the
|
|
<span><a title="initial context item" class="termref" href=
|
|
"#dt-initial-context-item">initial context item</a></span>, the
|
|
processor considers only those rules that apply to the initial
|
|
mode. If no initial mode is supplied, then the mode named in the
|
|
<code>default-mode</code> attribute of the <a href=
|
|
"#element-stylesheet"><code>xsl:stylesheet</code></a> element of
|
|
the <a title="principal stylesheet module" class="termref" href=
|
|
"#dt-principal-stylesheet-module">principal stylesheet module</a>
|
|
is used; or in the absence of such an attribute, the <a title=
|
|
"unnamed mode" class="termref" href="#dt-unnamed-mode">unnamed
|
|
mode</a>.<span class="definition">]</span></p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>If the initial mode is a <a title="streamable mode" class=
|
|
"termref" href="#dt-streamable-mode">streamable mode,</a> then
|
|
streaming will only be possible if the initial context item is a
|
|
node that is supplied in a form that allows such processing: for
|
|
example, as a reference to a stream of parsing events.</p>
|
|
</div>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>The design of the API for invoking a transformation <span class=
|
|
"verb">should</span> provide some means for users to designate the
|
|
<a title="unnamed mode" class="termref" href=
|
|
"#dt-unnamed-mode">unnamed mode</a> as the <a title="initial mode"
|
|
class="termref" href="#dt-initial-mode">initial mode</a> in cases
|
|
where it is not the default mode.</p>
|
|
</div>
|
|
</li>
|
|
<li>
|
|
<p>A base output URI. <span class=
|
|
"definition">[Definition: </span><a name="dt-base-output-uri"
|
|
id="dt-base-output-uri" title="base output URI"></a> The <b>base
|
|
output URI</b> is a URI to be used as the base URI when resolving a
|
|
relative URI <span>reference</span> allocated to a <a title=
|
|
"final result tree" class="termref" href=
|
|
"#dt-final-result-tree">final result tree</a>. If the
|
|
transformation generates more than one final result tree, then
|
|
typically each one will be allocated a URI relative to this base
|
|
URI. <span class="definition">]</span> The way in which a base
|
|
output URI is established is <a title="implementation-defined"
|
|
class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a>.</p>
|
|
</li>
|
|
<li>
|
|
<p>A mechanism for obtaining a document node and a media type,
|
|
given an absolute URI. The total set of available documents
|
|
(modeled as a mapping from URIs to document nodes) forms part of
|
|
the context for evaluating XPath expressions, specifically the
|
|
<a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-doc"><code>doc</code></a><sup><small>FO</small></sup>
|
|
function. The XSLT <a href=
|
|
"#function-document"><code>document</code></a> function
|
|
additionally requires the media type of the resource
|
|
representation, for use in interpreting any fragment identifier
|
|
present within a URI Reference.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>The set of documents that are available to the stylesheet is
|
|
<a title="implementation-dependent" class="termref" href=
|
|
"#dt-implementation-dependent">implementation-dependent</a>, as is
|
|
the processing that is carried out to construct a tree representing
|
|
the resource retrieved using a given URI. Some possible ways of
|
|
constructing a document (specifically, rules for constructing a
|
|
document from an Infoset or from a PSVI) are described in <a href=
|
|
"#xpath-datamodel-11">[Data Model]</a>.</p>
|
|
</div>
|
|
</li>
|
|
</ul>
|
|
<p><a name="err-XTDE0040" id="err-XTDE0040"><span class=
|
|
"error">[ERR XTDE0040]</span></a> It is a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> if the
|
|
invocation of the <a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a> specifies a template name that does
|
|
not match the <a title="expanded-QName" class="termref" href=
|
|
"#dt-expanded-qname">expanded-QName</a> of a named template defined
|
|
in the <a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a>.</p>
|
|
<p><a name="err-XTDE0045" id="err-XTDE0045"><span class=
|
|
"error">[ERR XTDE0045]</span></a> It is a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> if the
|
|
invocation of the <a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a> specifies an initial <a title=
|
|
"mode" class="termref" href="#dt-mode">mode</a> (other than the
|
|
default mode) that does not match the <a title="expanded-QName"
|
|
class="termref" href="#dt-expanded-qname">expanded-QName</a> in the
|
|
<code>mode</code> attribute of any template defined in the
|
|
<a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a>.</p>
|
|
<p><a name="err-XTDE0047" id="err-XTDE0047"><span class=
|
|
"error">[ERR XTDE0047]</span></a> It is a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> if the
|
|
invocation of the <a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a> specifies both an initial <a title=
|
|
"mode" class="termref" href="#dt-mode">mode</a> and an initial
|
|
template.</p>
|
|
<p><a name="err-XTDE0050" id="err-XTDE0050"><span class=
|
|
"error">[ERR XTDE0050]</span></a> It is a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> if the
|
|
stylesheet that is invoked declares a visible <a title=
|
|
"stylesheet parameter" class="termref" href=
|
|
"#dt-stylesheet-parameter">stylesheet parameter</a> with
|
|
<code>required="yes"</code> and no value for this parameter is
|
|
supplied during the invocation of the stylesheet. A stylesheet
|
|
parameter is visible if it is not masked by another global variable
|
|
or parameter with the same name and higher <a title=
|
|
"import precedence" class="termref" href=
|
|
"#dt-import-precedence">import precedence</a>.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-initial-template" id="dt-initial-template" title=
|
|
"initial template"></a>The transformation is performed by
|
|
evaluating an <b>initial template</b>. If a <a title=
|
|
"named template" class="termref" href="#dt-named-template">named
|
|
template</a> is supplied when the transformation is initiated, then
|
|
this is the initial template; otherwise, the initial template is
|
|
the <a title="template rule" class="termref" href=
|
|
"#dt-template-rule">template rule</a> selected according to the
|
|
rules of the <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>
|
|
instruction for processing the <span><a title=
|
|
"initial context item" class="termref" href=
|
|
"#dt-initial-context-item">initial context item</a></span> in the
|
|
initial <a title="mode" class="termref" href=
|
|
"#dt-mode">mode</a>.<span class="definition">]</span></p>
|
|
<p>Parameters passed to the transformation by the client
|
|
application are matched against <a title="stylesheet parameter"
|
|
class="termref" href="#dt-stylesheet-parameter">stylesheet
|
|
parameters</a> (see <a href="#global-variables"><i>9.5 Global
|
|
Variables and Parameters</i></a>), not against the <a title=
|
|
"template parameter" class="termref" href=
|
|
"#dt-template-parameter">template parameters</a> declared within
|
|
the <a title="initial template" class="termref" href=
|
|
"#dt-initial-template">initial template</a>. All <a title=
|
|
"template parameter" class="termref" href=
|
|
"#dt-template-parameter">template parameters</a> within the initial
|
|
template to be executed will take their default values.</p>
|
|
<p><a name="err-XTDE0060" id="err-XTDE0060"><span class=
|
|
"error">[ERR XTDE0060]</span></a> It is a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> if the
|
|
<a title="initial template" class="termref" href=
|
|
"#dt-initial-template">initial template</a> defines a <a title=
|
|
"template parameter" class="termref" href=
|
|
"#dt-template-parameter">template parameter</a> that specifies
|
|
<code>required="yes"</code>.</p>
|
|
<p>A <a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a> can process further source
|
|
documents in addition to those supplied when the transformation is
|
|
invoked. These additional documents can be loaded using the
|
|
functions <a href="#function-document"><code>document</code></a>
|
|
(see <a href="#document"><i>19.1.1 The document function</i></a>)
|
|
or <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-doc"><code>doc</code></a><sup><small>FO</small></sup>
|
|
or <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-collection"><code>collection</code></a><sup><small>FO</small></sup>
|
|
(see <a href="#xpath-functions-11">[Functions and Operators]</a>),
|
|
<span>or using the <a href=
|
|
"#element-stream"><code>xsl:stream</code></a> instruction</span>;
|
|
alternatively, they can be supplied as <a title=
|
|
"stylesheet parameter" class="termref" href=
|
|
"#dt-stylesheet-parameter">stylesheet parameters</a> (see <a href=
|
|
"#global-variables"><i>9.5 Global Variables and
|
|
Parameters</i></a>), or returned as the result of an <a title=
|
|
"extension function" class="termref" href=
|
|
"#dt-extension-function">extension function</a> (see <a href=
|
|
"#extension-functions"><i>21.1 Extension Functions</i></a>).</p>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="executing-a-transformation" id=
|
|
"executing-a-transformation"></a>2.4 <a href=
|
|
"#executing-a-transformation" style=
|
|
"text-decoration: none">Executing a Transformation</a></h3>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-template-rule" id="dt-template-rule" title=
|
|
"template rule"></a>A stylesheet contains a set of <b>template
|
|
rules</b> (see <a href="#rules"><i>6 Template Rules</i></a>). A
|
|
template rule has three parts: a <a title="pattern" class="termref"
|
|
href="#dt-pattern">pattern</a> that is matched against nodes, a
|
|
(possibly empty) set of <a title="template parameter" class=
|
|
"termref" href="#dt-template-parameter">template parameters</a>,
|
|
and a <a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> that is
|
|
evaluated to produce a sequence of items.<span class=
|
|
"definition">]</span> In many cases these items are newly
|
|
constructed nodes, which are then written to a <a title=
|
|
"result tree" class="termref" href="#dt-result-tree">result
|
|
tree</a>.</p>
|
|
<p>A transformation as a whole is executed by evaluating the
|
|
<a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> of the
|
|
<a title="initial template" class="termref" href=
|
|
"#dt-initial-template">initial template</a> as described in
|
|
<a href="#sequence-constructors"><i>5.7 Sequence
|
|
Constructors</i></a>.</p>
|
|
<p>The result sequence produced by evaluating the initial template
|
|
is handled as follows:</p>
|
|
<ol class="enumar">
|
|
<li>
|
|
<p>If the initial template has an <code>as</code> attribute, then
|
|
the result sequence of the initial template is checked against the
|
|
required type in the same way as for any other template.</p>
|
|
</li>
|
|
<li>
|
|
<p>If the result sequence is non-empty, then it is used to
|
|
construct an implicit <a title="final result tree" class="termref"
|
|
href="#dt-final-result-tree">final result tree</a>, following the
|
|
rules described in <a href="#constructing-complex-content"><i>5.7.1
|
|
Constructing Complex Content</i></a>: the effect is as if the
|
|
initial template <var>T</var> were called by an implicit template
|
|
of the form:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:template name="IMPLICIT">
|
|
<xsl:result-document href="">
|
|
<xsl:call-template name="T"/>
|
|
</xsl:result-document>
|
|
</xsl:template>
|
|
</pre></div>
|
|
</li>
|
|
</ol>
|
|
<p>An implicit result tree is also created when the result sequence
|
|
is empty, provided that no <a href=
|
|
"#element-result-document"><code>xsl:result-document</code></a>
|
|
instruction has been evaluated during the course of the
|
|
transformation. In this situation the implicit result tree will
|
|
consist of a document node with no children.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>This means that there is always at least one result tree. It
|
|
also means that if the content of the initial template is a single
|
|
<a href=
|
|
"#element-result-document"><code>xsl:result-document</code></a>
|
|
instruction, as in the example above, then only one result tree is
|
|
produced, not two. It is useful to make the result document
|
|
explicit as this is the only way of invoking document-level
|
|
validation.</p>
|
|
<p>If the result of the initial template is non-empty, and an
|
|
explicit <a href=
|
|
"#element-result-document"><code>xsl:result-document</code></a>
|
|
instruction has been evaluated with the empty attribute
|
|
<code>href=""</code>, then an error will occur <span class=
|
|
"error">[see <a href="#err-XTDE1490">ERR XTDE1490</a>]</span>,
|
|
since it is not possible to create two final result trees with the
|
|
same URI.</p>
|
|
</div>
|
|
<p>A <a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> is a sequence
|
|
of sibling nodes in the stylesheet, each of which is either an
|
|
<a title="XSLT instruction" class="termref" href=
|
|
"#dt-xslt-instruction">XSLT instruction</a>, a <a title=
|
|
"literal result element" class="termref" href=
|
|
"#dt-literal-result-element">literal result element</a>, a text
|
|
node, or an <a title="extension instruction" class="termref" href=
|
|
"#dt-extension-instruction">extension instruction</a>.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-instruction" id="dt-instruction" title="instruction"></a>An
|
|
<b>instruction</b> is either an <a title="XSLT instruction" class=
|
|
"termref" href="#dt-xslt-instruction">XSLT instruction</a> or an
|
|
<a title="extension instruction" class="termref" href=
|
|
"#dt-extension-instruction">extension instruction</a>.<span class=
|
|
"definition">]</span></p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-xslt-instruction" id="dt-xslt-instruction" title=
|
|
"XSLT instruction"></a>An <b>XSLT instruction</b> is an <a title=
|
|
"XSLT element" class="termref" href="#dt-xslt-element">XSLT
|
|
element</a> whose syntax summary in this specification contains the
|
|
annotation <code><!-- category: instruction
|
|
--></code>.<span class="definition">]</span></p>
|
|
<p><a title="extension instruction" class="termref" href=
|
|
"#dt-extension-instruction">Extension instructions</a> are
|
|
described in <a href="#extension-instruction"><i>21.2 Extension
|
|
Instructions</i></a>.</p>
|
|
<p>The main categories of <a title="XSLT instruction" class=
|
|
"termref" href="#dt-xslt-instruction">XSLT instruction</a> are as
|
|
follows:</p>
|
|
<ul>
|
|
<li>
|
|
<p>instructions that create new nodes: <a href=
|
|
"#element-document"><code>xsl:document</code></a>, <a href=
|
|
"#element-element"><code>xsl:element</code></a>, <a href=
|
|
"#element-attribute"><code>xsl:attribute</code></a>, <a href=
|
|
"#element-processing-instruction"><code>xsl:processing-instruction</code></a>,
|
|
<a href="#element-comment"><code>xsl:comment</code></a>, <a href=
|
|
"#element-value-of"><code>xsl:value-of</code></a>, <a href=
|
|
"#element-text"><code>xsl:text</code></a>, <a href=
|
|
"#element-namespace"><code>xsl:namespace</code></a>;</p>
|
|
</li>
|
|
<li>
|
|
<p>an instruction that returns an arbitrary sequence by evaluating
|
|
an XPath expression: <a href=
|
|
"#element-sequence"><code>xsl:sequence</code></a>;</p>
|
|
</li>
|
|
<li>
|
|
<p>instructions that cause conditional or repeated evaluation of
|
|
nested instructions: <a href="#element-if"><code>xsl:if</code></a>,
|
|
<a href="#element-choose"><code>xsl:choose</code></a>,
|
|
<span><a href="#element-try"><code>xsl:try</code></a>,</span>
|
|
<a href="#element-for-each"><code>xsl:for-each</code></a>, <a href=
|
|
"#element-for-each-group"><code>xsl:for-each-group</code></a>,
|
|
<span><a href="#element-fork"><code>xsl:fork</code></a>, <a href=
|
|
"#element-iterate"><code>xsl:iterate</code></a> and its subordinate
|
|
instructions <a href=
|
|
"#element-next-iteration"><code>xsl:next-iteration</code></a> and
|
|
<a href="#element-break"><code>xsl:break</code></a></span>;</p>
|
|
</li>
|
|
<li>
|
|
<p>instructions that invoke templates: <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>,
|
|
<a href=
|
|
"#element-apply-imports"><code>xsl:apply-imports</code></a>,
|
|
<a href=
|
|
"#element-call-template"><code>xsl:call-template</code></a>,
|
|
<a href="#element-next-match"><code>xsl:next-match</code></a>;</p>
|
|
</li>
|
|
<li>
|
|
<p>Instructions that declare variables: <a href=
|
|
"#element-variable"><code>xsl:variable</code></a>, <a href=
|
|
"#element-param"><code>xsl:param</code></a>;</p>
|
|
</li>
|
|
<li>
|
|
<p>other specialized instructions: <a href=
|
|
"#element-number"><code>xsl:number</code></a>, <a href=
|
|
"#element-analyze-string"><code>xsl:analyze-string</code></a>,
|
|
<a href="#element-message"><code>xsl:message</code></a>, <a href=
|
|
"#element-result-document"><code>xsl:result-document</code></a>,
|
|
<span><a href="#element-stream"><code>xsl:stream</code></a>,
|
|
<a href="#element-perform-sort"><code>xsl:perform-sort</code></a>,
|
|
<a href="#element-merge"><code>xsl:merge</code></a></span>.</p>
|
|
</li>
|
|
</ul>
|
|
<p>Often, a <a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> will include an
|
|
<a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>
|
|
instruction, which selects a sequence of nodes to be processed.
|
|
Each of the selected nodes is processed by searching the stylesheet
|
|
for a matching <a title="template rule" class="termref" href=
|
|
"#dt-template-rule">template rule</a> and evaluating the <a title=
|
|
"sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> of that
|
|
template rule. The resulting sequences of items are concatenated,
|
|
in order, to give the result of the <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>
|
|
instruction, as described in <a href="#applying-templates"><i>6.3
|
|
Applying Template Rules</i></a>; this sequence is often added to a
|
|
<a title="result tree" class="termref" href=
|
|
"#dt-result-tree">result tree</a>. Since the <a title=
|
|
"sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructors</a> of the
|
|
selected <a title="template rule" class="termref" href=
|
|
"#dt-template-rule">template rules</a> may themselves contain
|
|
<a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>
|
|
instructions, this results in a cycle of selecting nodes,
|
|
identifying <a title="template rule" class="termref" href=
|
|
"#dt-template-rule">template rules</a>, constructing sequences, and
|
|
constructing <a title="result tree" class="termref" href=
|
|
"#dt-result-tree">result trees</a>, that recurses through a
|
|
<a title="source tree" class="termref" href=
|
|
"#dt-source-tree">source tree</a>.</p>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="context" id="context"></a>2.5 <a href="#context"
|
|
style="text-decoration: none">The Evaluation Context</a></h3>
|
|
<p>The results of some expressions and instructions in a stylesheet
|
|
may depend on information provided contextually. This context
|
|
information is divided into two categories: the static context,
|
|
which is known during static analysis of the stylesheet, and the
|
|
dynamic context, which is not known until the stylesheet is
|
|
evaluated. Although information in the static context is known at
|
|
analysis time, it is sometimes used during stylesheet
|
|
evaluation.</p>
|
|
<p>Some context information can be set by means of declarations
|
|
within the stylesheet itself. For example, the namespace bindings
|
|
used for any XPath expression are determined by the namespace
|
|
declarations present in containing elements in the stylesheet.
|
|
Other information may be supplied externally or implicitly: an
|
|
example is the current date and time.</p>
|
|
<p>The context information used in processing an XSLT stylesheet
|
|
includes as a subset all the context information required when
|
|
evaluating XPath expressions. The <span>XPath 2.1</span>
|
|
specification defines a static and dynamic context that the host
|
|
language (in this case, XSLT) may initialize, which affects the
|
|
results of XPath expressions used in that context. XSLT augments
|
|
the context with additional information: this additional
|
|
information is used firstly by XSLT constructs outside the scope of
|
|
XPath (for example, the <a href=
|
|
"#element-sort"><code>xsl:sort</code></a> element), and secondly,
|
|
by functions that are defined in the XSLT specification (such as
|
|
<a href="#function-key"><code>key</code></a> and <a href=
|
|
"#function-current-group"><code>current-group</code></a>) that are
|
|
available for use in XPath expressions appearing within a
|
|
stylesheet.</p>
|
|
<p>The static context for an expression or other construct in a
|
|
stylesheet is determined by the place in which it appears
|
|
lexically. The details vary for different components of the static
|
|
context, but in general, elements within a stylesheet module affect
|
|
the static context for their descendant elements within the same
|
|
stylesheet module.</p>
|
|
<p>The dynamic context is maintained as a stack. When an
|
|
instruction or expression is evaluated, it may add dynamic context
|
|
information to the stack; when evaluation is complete, the dynamic
|
|
context reverts to its previous state. An expression that accesses
|
|
information from the dynamic context always uses the value at the
|
|
top of the stack.</p>
|
|
<p>The most commonly used component of the dynamic context is the
|
|
<a title="context item" class="termref" href=
|
|
"#dt-context-item">context item</a>. This is an implicit variable
|
|
whose value is the item currently being processed (it may be a
|
|
node, an atomic value, <span>or a function item</span>). The value
|
|
of the context item can be referenced within an XPath expression
|
|
using the expression <code>.</code> (dot).</p>
|
|
<p>Full details of the static and dynamic context are provided in
|
|
<a href="#static-and-dynamic-context"><i>5.4 The Static and Dynamic
|
|
Context</i></a>.</p>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="parsing-and-serialization" id=
|
|
"parsing-and-serialization"></a>2.6 <a href=
|
|
"#parsing-and-serialization" style="text-decoration: none">Parsing
|
|
and Serialization</a></h3>
|
|
<p>An XSLT <a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a> describes a process that constructs
|
|
a set of <a title="final result tree" class="termref" href=
|
|
"#dt-final-result-tree">final result trees</a> from a set of
|
|
<a title="source tree" class="termref" href=
|
|
"#dt-source-tree">source trees</a>.</p>
|
|
<p>The <a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a> does not describe how a <a title=
|
|
"source tree" class="termref" href="#dt-source-tree">source
|
|
tree</a> is constructed. Some possible ways of constructing source
|
|
trees are described in <a href="#xpath-datamodel-11">[Data
|
|
Model]</a>. Frequently an <a title="implementation" class="termref"
|
|
href="#dt-implementation">implementation</a> will operate in
|
|
conjunction with an XML parser (or more strictly, in the
|
|
terminology of <a href="#REC-xml">[XML 1.0]</a>, an <em>XML
|
|
processor</em>), to build a source tree from an input XML document.
|
|
An implementation <span class="verb">may</span> 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 <a href="#DOM-Level-2-Core">[DOM Level
|
|
2]</a>). This is outside the scope of this specification. Users
|
|
should be aware, however, that since the input to the
|
|
transformation is a tree conforming to the XDM data model as
|
|
described in <a href="#xpath-datamodel-11">[Data Model]</a>,
|
|
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 <a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a> 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.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-serialization" id="dt-serialization" title=
|
|
"serialization"></a>A frequent requirement is to output a <a title=
|
|
"final result tree" class="termref" href=
|
|
"#dt-final-result-tree">final result tree</a> as an XML document
|
|
(or in other formats such as HTML). This process is referred to as
|
|
<b>serialization</b>.<span class="definition">]</span></p>
|
|
<p>Like parsing, serialization is not part of the transformation
|
|
process, and it is not <span class="verb">required</span> that an
|
|
XSLT processor <span class="verb">must</span> be able to perform
|
|
serialization. However, for pragmatic reasons, this specification
|
|
describes declarations (the <a href=
|
|
"#element-output"><code>xsl:output</code></a> element and the
|
|
<a href="#element-character-map"><code>xsl:character-map</code></a>
|
|
declarations, see <a href="#serialization"><i>23
|
|
Serialization</i></a>), and attributes on the <a href=
|
|
"#element-result-document"><code>xsl:result-document</code></a>
|
|
instruction, that allow a <a title="stylesheet" class="termref"
|
|
href="#dt-stylesheet">stylesheet</a> to specify the desired
|
|
properties of a serialized output file. When serialization is not
|
|
being performed, either because the implementation does not support
|
|
the serialization option, or because the user is executing the
|
|
transformation in a way that does not invoke serialization, then
|
|
the content of the <a href=
|
|
"#element-output"><code>xsl:output</code></a> and <a href=
|
|
"#element-character-map"><code>xsl:character-map</code></a>
|
|
declarations has no effect. Under these circumstances the processor
|
|
<span class="verb">may</span> report any errors in an <a href=
|
|
"#element-output"><code>xsl:output</code></a> or <a href=
|
|
"#element-character-map"><code>xsl:character-map</code></a>
|
|
declaration, or in the serialization attributes of <a href=
|
|
"#element-result-document"><code>xsl:result-document</code></a>,
|
|
but is not <span class="verb">required</span> to do so.</p>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="extensibility" id="extensibility"></a>2.7 <a href=
|
|
"#extensibility" style=
|
|
"text-decoration: none">Extensibility</a></h3>
|
|
<p>XSLT defines a number of features that allow the language to be
|
|
extended by implementers, or, if implementers choose to provide the
|
|
capability, by users. These features have been designed, so far as
|
|
possible, so that they can be used without sacrificing
|
|
interoperability. Extensions other than those explicitly defined in
|
|
this specification are not permitted.</p>
|
|
<p>These features are all based on XML namespaces; namespaces are
|
|
used to ensure that the extensions provided by one implementer do
|
|
not clash with those of a different implementer.</p>
|
|
<p>The most common way of extending the language is by providing
|
|
additional functions, which can be invoked from XPath expressions.
|
|
These are known as <a title="extension function" class="termref"
|
|
href="#dt-extension-function">extension functions</a>, and are
|
|
described in <a href="#extension-functions"><i>21.1 Extension
|
|
Functions</i></a>.</p>
|
|
<p>It is also permissible to extend the language by providing new
|
|
<a title="instruction" class="termref" href=
|
|
"#dt-instruction">instructions</a>. These are referred to as
|
|
<a title="extension instruction" class="termref" href=
|
|
"#dt-extension-instruction">extension instructions</a>, and are
|
|
described in <a href="#extension-instruction"><i>21.2 Extension
|
|
Instructions</i></a>. A stylesheet that uses extension instructions
|
|
in a particular namespace must declare that it is doing so by using
|
|
the <code>[xsl:]extension-element-prefixes</code> attribute.</p>
|
|
<p>Extension instructions and extension functions defined according
|
|
to these rules <span class="verb">may</span> be provided by the
|
|
implementer of the XSLT processor, and the implementer <span class=
|
|
"verb">may</span> also provide facilities to allow users to create
|
|
further extension instructions and extension functions.</p>
|
|
<p>This specification defines how extension instructions and
|
|
extension functions are invoked, but the facilities for creating
|
|
new extension instructions and extension functions are <a title=
|
|
"implementation-defined" class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a>. For
|
|
further details, see <a href="#extension"><i>21 Extensibility and
|
|
Fallback</i></a>.</p>
|
|
<p>The XSLT language can also be extended by the use of <a title=
|
|
"extension attribute" class="termref" href=
|
|
"#dt-extension-attribute">extension attributes</a> (see <a href=
|
|
"#extension-attributes"><i>3.3 Extension Attributes</i></a>), and
|
|
by means of <a title="user-defined data element" class="termref"
|
|
href="#dt-data-element">user-defined data elements</a> (see
|
|
<a href="#user-defined-top-level"><i>3.6.3 User-defined Data
|
|
Elements</i></a>).</p>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="stylesheets-and-schemas" id=
|
|
"stylesheets-and-schemas"></a>2.8 <a href=
|
|
"#stylesheets-and-schemas" style=
|
|
"text-decoration: none">Stylesheets and XML Schemas</a></h3>
|
|
<p>An XSLT <a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a> can make use of information from a
|
|
schema. An XSLT transformation can take place in the absence of a
|
|
schema (and, indeed, in the absence of a DTD), but where the source
|
|
document has undergone schema validity assessment, the XSLT
|
|
processor has access to the type information associated with
|
|
individual nodes, not merely to the untyped text.</p>
|
|
<p>Information from a schema can be used both statically (when the
|
|
<a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a> is compiled), and dynamically
|
|
(during evaluation of the stylesheet to transform a source
|
|
document).</p>
|
|
<p>There are places within a <a title="stylesheet" class="termref"
|
|
href="#dt-stylesheet">stylesheet</a>, and within XPath <a title=
|
|
"expression" class="termref" href="#dt-expression">expressions</a>
|
|
and <a title="pattern" class="termref" href=
|
|
"#dt-pattern">patterns</a> in a <a title="stylesheet" class=
|
|
"termref" href="#dt-stylesheet">stylesheet</a>, where it is
|
|
possible to refer to named type definitions in a schema, or to
|
|
element and attribute declarations. For example, it is possible to
|
|
declare the types expected for the parameters of a function. This
|
|
is done using the <a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-SequenceType">SequenceType</a><sup><small>XP21</small></sup>
|
|
syntax defined in <a href="#xpath-21">[XPath 2.1]</a>.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-schema-component" id="dt-schema-component" title=
|
|
"schema component"></a>Type definitions and element and attribute
|
|
declarations are referred to collectively as <b>schema
|
|
components</b>.<span class="definition">]</span></p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-in-scope-schema-component" id="dt-in-scope-schema-component"
|
|
title="in-scope schema component"></a>The <a title=
|
|
"schema component" class="termref" href=
|
|
"#dt-schema-component">schema components</a> that may be referenced
|
|
by name in a <a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a> are referred to as the <b>in-scope
|
|
schema components</b>. This set is the same throughout all the
|
|
modules of a stylesheet.<span class="definition">]</span></p>
|
|
<p>The conformance rules for XSLT <span>2.1</span>, defined in
|
|
<a href="#conformance"><i>24 Conformance</i></a>, distinguish
|
|
between a <a title="basic XSLT processor" class="termref" href=
|
|
"#dt-basic-xslt-processor">basic XSLT processor</a> and a <a title=
|
|
"schema-aware XSLT processor" class="termref" href=
|
|
"#dt-schema-aware-xslt-processor">schema-aware XSLT processor</a>.
|
|
As the names suggest, a basic XSLT processor does not support the
|
|
features of XSLT that require access to schema information, either
|
|
statically or dynamically. A <a title="stylesheet" class="termref"
|
|
href="#dt-stylesheet">stylesheet</a> that works with a basic XSLT
|
|
processor will produce the same results with a schema-aware XSLT
|
|
processor provided that the source documents are untyped (that is,
|
|
they are not validated against a schema). However, if source
|
|
documents are validated against a schema then the results may be
|
|
different from the case where they are not validated. Some
|
|
constructs that work on untyped data may fail with typed data (for
|
|
example, an attribute of type <code>xs:date</code> cannot be used
|
|
as an argument of the <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-substring"><code>substring</code></a><sup><small>FO</small></sup>
|
|
function) and other constructs may produce different results
|
|
depending on the data type (for example, given the element
|
|
<code><product price="10.00" discount="2.00"/></code>, the
|
|
expression <code>@price gt @discount</code> will return true if the
|
|
attributes have type <code>xs:decimal</code>, but will return false
|
|
if they are untyped).</p>
|
|
<p>There is a standard set of type definitions that are always
|
|
available as <a title="in-scope schema component" class="termref"
|
|
href="#dt-in-scope-schema-component">in-scope schema components</a>
|
|
in every stylesheet. These are defined in <a href=
|
|
"#built-in-types"><i>3.13 Built-in Types</i></a>.</p>
|
|
<p>The remainder of this section describes facilities that are
|
|
available only with a <a title="schema-aware XSLT processor" class=
|
|
"termref" href="#dt-schema-aware-xslt-processor">schema-aware XSLT
|
|
processor</a>.</p>
|
|
<p>Additional <a title="schema component" class="termref" href=
|
|
"#dt-schema-component">schema components</a> (type definitions,
|
|
element declarations, and attribute declarations) may be added to
|
|
the <a title="in-scope schema component" class="termref" href=
|
|
"#dt-in-scope-schema-component">in-scope schema components</a> by
|
|
means of the <a href=
|
|
"#element-import-schema"><code>xsl:import-schema</code></a>
|
|
declaration in a stylesheet.</p>
|
|
<p>The <a href=
|
|
"#element-import-schema"><code>xsl:import-schema</code></a>
|
|
declaration may reference an external schema document by means of a
|
|
URI, or it may contain an inline <code>xs:schema</code>
|
|
element.</p>
|
|
<p>It is only necessary to import a schema explicitly if one or
|
|
more of its <a title="schema component" class="termref" href=
|
|
"#dt-schema-component">schema components</a> are referenced
|
|
explicitly by name in the <a title="stylesheet" class="termref"
|
|
href="#dt-stylesheet">stylesheet</a>; it is not necessary to import
|
|
a schema merely because the stylesheet is used to process a source
|
|
document that has been assessed against that schema. It is possible
|
|
to make use of the information resulting from schema assessment
|
|
(for example, the fact that a particular attribute holds a date)
|
|
even if no schema has been imported by the stylesheet.</p>
|
|
<p>Importing a schema does not of itself say anything about the
|
|
type of the source document that the <a title="stylesheet" class=
|
|
"termref" href="#dt-stylesheet">stylesheet</a> is expected to
|
|
process. The imported type definitions can be used for temporary
|
|
nodes or for nodes on a <a title="result tree" class="termref"
|
|
href="#dt-result-tree">result tree</a> just as much as for nodes in
|
|
source documents. It is possible to make assertions about the type
|
|
of an input document by means of tests within the <a title=
|
|
"stylesheet" class="termref" href="#dt-stylesheet">stylesheet</a>.
|
|
For example:</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e2013" id=
|
|
"d7e2013"></a>Example: Asserting the Required Type of the Source
|
|
Document</div>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:mode initial="yes">
|
|
<xsl:context-item required="yes"
|
|
as="document-node(schema-element(my:invoice))"/>
|
|
</xsl:mode>
|
|
</pre></div>
|
|
<p>This example will cause the transformation to fail with an error
|
|
message when the <a title="initial mode" class="termref" href=
|
|
"#dt-initial-mode">initial mode</a> is the unnamed mode, unless the
|
|
document element of the source document is valid against the
|
|
top-level element declaration <code>my:invoice</code>, and has been
|
|
annotated as such.</p>
|
|
</div>
|
|
<p>Equally, importing a schema does not of itself say anything
|
|
about the structure of the result tree. It is possible to request
|
|
validation of a result tree against the schema by using the
|
|
<a href="#element-result-document"><code>xsl:result-document</code></a>
|
|
instruction, for example:</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e2030" id=
|
|
"d7e2030"></a>Example: Requesting Validation of the Result
|
|
Document</div>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:template match="/">
|
|
<xsl:result-document validation="strict">
|
|
<xhtml:html>
|
|
<xsl:apply-templates/>
|
|
</xhtml:html>
|
|
</xsl:result-document>
|
|
</xsl:template>
|
|
|
|
</pre></div>
|
|
<p>This example will cause the transformation to fail with an error
|
|
message unless the document element of the result document is valid
|
|
against the top-level element declaration
|
|
<code>xhtml:html</code>.</p>
|
|
</div>
|
|
<p>It is possible that a source document may contain nodes whose
|
|
<a title="type annotation" class="termref" href=
|
|
"#dt-annotation">type annotation</a> is not one of the types
|
|
imported by the stylesheet. This creates a potential problem
|
|
because in the case of an expression such as <code>data(.) instance
|
|
of xs:integer</code> the system needs to know whether the type
|
|
named in the type annotation of the context node is derived by
|
|
restriction from the type <code>xs:integer</code>. This information
|
|
is not explicitly available in an XDM tree, as defined in <a href=
|
|
"#xpath-datamodel-11">[Data Model]</a>. The implementation may
|
|
choose one of several strategies for dealing with this
|
|
situation:</p>
|
|
<ol class="enumar">
|
|
<li>
|
|
<p>The processor may signal a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> if a
|
|
source document is found to contain a <a title="type annotation"
|
|
class="termref" href="#dt-annotation">type annotation</a> that is
|
|
not known to the processor.</p>
|
|
</li>
|
|
<li>
|
|
<p>The processor may maintain additional metadata, beyond that
|
|
described in <a href="#xpath-datamodel-11">[Data Model]</a>, that
|
|
allows the source document to be processed as if all the necessary
|
|
schema information had been imported using <a href=
|
|
"#element-import-schema"><code>xsl:import-schema</code></a>. Such
|
|
metadata might be held in the data structure representing the
|
|
source document itself, or it might be held in a system catalog or
|
|
repository.</p>
|
|
</li>
|
|
<li>
|
|
<p>The processor may be configured to use a fixed set of schemas,
|
|
which are automatically used to validate all source documents
|
|
before they can be supplied as input to a transformation. In this
|
|
case it is impossible for a source document to have a <a title=
|
|
"type annotation" class="termref" href="#dt-annotation">type
|
|
annotation</a> that the processor is not aware of.</p>
|
|
</li>
|
|
<li>
|
|
<p>The processor may be configured to treat the source document as
|
|
if no schema processing had been performed, that is, effectively to
|
|
strip all type annotations from elements and attributes on input,
|
|
marking them instead as having type <code>xs:untyped</code> and
|
|
<code>xs:untypedAtomic</code> respectively.</p>
|
|
</li>
|
|
</ol>
|
|
<p>Where a stylesheet author chooses to make assertions about the
|
|
types of nodes or of <a title="variable" class="termref" href=
|
|
"#dt-variable">variables</a> and <a title="parameter" class=
|
|
"termref" href="#dt-parameter">parameters</a>, it is possible for
|
|
an XSLT processor to perform static analysis of the <a title=
|
|
"stylesheet" class="termref" href="#dt-stylesheet">stylesheet</a>
|
|
(that is, analysis in the absence of any source document). Such
|
|
analysis <span class="verb">may</span> reveal errors that would
|
|
otherwise not be discovered until the transformation is actually
|
|
executed. An XSLT processor is not <span class=
|
|
"verb">required</span> to perform such static type-checking. Under
|
|
some circumstances (see <a href="#errors"><i>2.10 Error
|
|
Handling</i></a>) type errors that are detected early <span class=
|
|
"verb">may</span> be reported as static errors. In addition an
|
|
implementation <span class="verb">may</span> report any condition
|
|
found during static analysis as a warning, provided that this does
|
|
not prevent the stylesheet being evaluated as described by this
|
|
specification.</p>
|
|
<p>A <a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a> can also control the <a title=
|
|
"type annotation" class="termref" href="#dt-annotation">type
|
|
annotations</a> of nodes that it constructs in a <a title=
|
|
"final result tree" class="termref" href=
|
|
"#dt-final-result-tree">final result tree</a>, or in <a title=
|
|
"temporary tree" class="termref" href=
|
|
"#dt-temporary-tree">temporary trees</a>. This can be done in a
|
|
number of ways.</p>
|
|
<ul>
|
|
<li>
|
|
<p>It is possible to request explicit validation of a complete
|
|
document, that is, a tree rooted at a document node. This applies
|
|
both to temporary trees constructed using the <a href=
|
|
"#element-document"><code>xsl:document</code></a> (or <a href=
|
|
"#element-copy"><code>xsl:copy</code></a>) instruction and also to
|
|
<a title="final result tree" class="termref" href=
|
|
"#dt-final-result-tree">final result trees</a> constructed using
|
|
<a href=
|
|
"#element-result-document"><code>xsl:result-document</code></a>.
|
|
Validation is either strict or lax, as described in <a href=
|
|
"#xmlschema-1">[XML Schema Part 1]</a>. If validation of a
|
|
<a title="result tree" class="termref" href=
|
|
"#dt-result-tree">result tree</a> fails (strictly speaking, if the
|
|
outcome of the validity assessment is <code>invalid</code>), then
|
|
the transformation fails, but in all other cases, the element and
|
|
attribute nodes of the tree will be annotated with the names of the
|
|
types to which these nodes conform. These <a title=
|
|
"type annotation" class="termref" href="#dt-annotation">type
|
|
annotations</a> will be discarded if the result tree is serialized
|
|
as an XML document, but they remain available when the result tree
|
|
is passed to an application (perhaps another <a title="stylesheet"
|
|
class="termref" href="#dt-stylesheet">stylesheet</a>) for further
|
|
processing.</p>
|
|
</li>
|
|
<li>
|
|
<p>It is also possible to validate individual element and attribute
|
|
nodes as they are constructed. This is done using the
|
|
<code>type</code> and <code>validation</code> attributes of the
|
|
<a href="#element-element"><code>xsl:element</code></a>, <a href=
|
|
"#element-attribute"><code>xsl:attribute</code></a>, <a href=
|
|
"#element-copy"><code>xsl:copy</code></a>, and <a href=
|
|
"#element-copy-of"><code>xsl:copy-of</code></a> instructions, or
|
|
the <code>xsl:type</code> and <code>xsl:validation</code>
|
|
attributes of a literal result element.</p>
|
|
</li>
|
|
<li>
|
|
<p>When elements, attributes, or document nodes are copied, either
|
|
explicitly using the <a href=
|
|
"#element-copy"><code>xsl:copy</code></a> or <a href=
|
|
"#element-copy-of"><code>xsl:copy-of</code></a> instructions, or
|
|
implicitly when nodes in a sequence are attached to a new parent
|
|
node, the options <code>validation="strip"</code> and
|
|
<code>validation="preserve"</code> are available, to control
|
|
whether existing <a title="type annotation" class="termref" href=
|
|
"#dt-annotation">type annotations</a> are to be retained or
|
|
not.</p>
|
|
</li>
|
|
</ul>
|
|
<p>When nodes in a <a title="temporary tree" class="termref" href=
|
|
"#dt-temporary-tree">temporary tree</a> are validated, type
|
|
information is available for use by operations carried out on the
|
|
temporary tree, in the same way as for a source document that has
|
|
undergone schema assessment.</p>
|
|
<p>For details of how validation of element and attribute nodes
|
|
works, see <a href="#validation"><i>22.2 Validation</i></a>.</p>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="streaming-concepts" id="streaming-concepts"></a>2.9
|
|
<a href="#streaming-concepts" style=
|
|
"text-decoration: none">Streaming</a></h3>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-streaming" id="dt-streaming" title="streaming"></a>The term
|
|
<b>streaming</b> refers to a manner of processing in which
|
|
documents (such as source and result documents) are not represented
|
|
by a complete tree of nodes occupying memory proportional to
|
|
document size, but instead are processed "on the fly" as a sequence
|
|
of events, similar in concept to the stream of events notified by
|
|
an XML parser to represent markup in lexical XML.<span class=
|
|
"definition">]</span></p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-streamed-document" id="dt-streamed-document" title=
|
|
"streamed document"></a>A <b>streamed document</b> is a <a title=
|
|
"source tree" class="termref" href="#dt-source-tree">source
|
|
tree</a> that is processed using streaming, that is, without
|
|
constructing a complete tree of nodes in memory.<span class=
|
|
"definition">]</span></p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-streamed-document-node" id="dt-streamed-document-node" title=
|
|
"streamed node"></a>A <b>streamed node</b> is a node in a <a title=
|
|
"streamed document" class="termref" href=
|
|
"#dt-streamed-document">streamed document</a>.<span class=
|
|
"definition">]</span></p>
|
|
<p>Many processors implementing earlier versions of this
|
|
specification have adopted an architecture that allows streaming of
|
|
the <a title="result tree" class="termref" href=
|
|
"#dt-result-tree">result tree</a> directly to a serializer, without
|
|
first materializing the complete result tree in memory. Streaming
|
|
of the <a title="source tree" class="termref" href=
|
|
"#dt-source-tree">source tree</a>, however, has proved to be more
|
|
difficult without subsetting the language. This has created a
|
|
situation where documents exceeding the capacity of virtual memory
|
|
could not be transformed. XSLT 2.1 therefore introduces facilities
|
|
allowing stylesheets to be written in a way that makes streaming of
|
|
source documents possible, without excessive reliance on
|
|
processor-specific optimization techniques.</p>
|
|
<p>Streaming achieves two important objectives: it allows large
|
|
documents to be transformed without requiring correspondingly large
|
|
amounts of memory; and it allows the processor to start producing
|
|
output before it has finished receiving its input, thus reducing
|
|
latency.</p>
|
|
<p>This specification does not attempt to legislate precisely which
|
|
implementation techniques fall under the definition of streaming,
|
|
and which do not. A number of techniques are available that reduce
|
|
memory requirements, while still requiring a degree of buffering,
|
|
or allocation of memory to partial results. A stylesheet that
|
|
requests streaming of a source document is indicating that the
|
|
processor should avoid assuming that the entire source document
|
|
will fit in memory; in return, the stylesheet must be written in a
|
|
way that makes streaming possible. This specification does not
|
|
attempt to describe the algorithms that the processor should
|
|
actually use, or to impose quantitative constraints on the
|
|
resources that these algorithms should consume.</p>
|
|
<p>Nothing in this specification, nor in its predecessors <a href=
|
|
"#xslt">[XSLT 1.0]</a> and <a href="#xslt20">[XSLT 2.0]</a>,
|
|
prevents a processor using streaming whenever it sees an
|
|
opportunity to do so. However, experience has shown that in order
|
|
to achieve streaming, it is often necessary to write stylesheet
|
|
code in such a way as to make this possible. Therefore, XSLT 2.1
|
|
provides explicit constructs allowing the stylesheet author to
|
|
request streaming, and defines explicit static constraints on the
|
|
structure of the code which are designed to make streaming
|
|
possible.</p>
|
|
<p>A processor that claims conformance with the streaming option
|
|
offers a guarantee that when streaming is requested for a source
|
|
document, and when the stylesheet conforms to the rules that make
|
|
the processing <a title="guaranteed-streamable" class="termref"
|
|
href="#dt-guaranteed-streamable">guaranteed-streamable</a>, then an
|
|
algorithm will be adopted in which memory consumption is either
|
|
completely independent of document size, or increases only very
|
|
slowly as document size increases, allowing documents to be
|
|
processed that are orders-of-magnitude larger than the physical
|
|
memory available. A processor that does not claim conformance with
|
|
the streaming option must still process a stylesheet and deliver
|
|
the correct results, but is not required to use streaming
|
|
algorithms, and may therefore fail with out-of-memory errors when
|
|
presented with large source documents.</p>
|
|
<p>Apart from the fact that there are constructs to request
|
|
streaming, and rules that must be followed to guarantee that
|
|
streaming is possible, the language has been designed so there are
|
|
as few differences as possible between streaming and non-streaming
|
|
evaluation. The semantics of the language continue to be expressed
|
|
in terms of the XDM data model, which is substantively unchanged;
|
|
but readers must take care to observe that when terms like "node"
|
|
and "axis" are used, the concepts are completely abstract and may
|
|
have no direct representation in the run-time execution
|
|
environment.</p>
|
|
<p>Streamed processing of a document can be initiated in one of two
|
|
ways:</p>
|
|
<ul>
|
|
<li>
|
|
<p>The <a title="initial mode" class="termref" href=
|
|
"#dt-initial-mode">initial mode</a> can be declared as a <a title=
|
|
"streamable mode" class="termref" href=
|
|
"#dt-streamable-mode">streamable mode</a>. In this case the
|
|
<span><a title="initial context item" class="termref" href=
|
|
"#dt-initial-context-item">initial context item</a></span> will
|
|
generally be a document node, and it will be supplied by the
|
|
calling application in a form that allows streaming (that is, in
|
|
some form other than a tree in memory; for example, as a reference
|
|
to a push or pull XML parser primed to deliver a stream of events).
|
|
<span>The type of the <a title="initial context item" class=
|
|
"termref" href="#dt-initial-context-item">initial context item</a>
|
|
can be constrained using the <a href=
|
|
"#element-context-item"><code>xsl:context-item</code></a>
|
|
element.</span> In this case the <a title="template rule" class=
|
|
"termref" href="#dt-template-rule">template rule</a> that matches
|
|
the document node (in this mode) must be a <a title=
|
|
"streamable template" class="termref" href=
|
|
"#dt-streamable-template">streamable template</a>, which means that
|
|
it (as well as all other template rules using this <a title="mode"
|
|
class="termref" href="#dt-mode">mode</a>) must satisfy certain
|
|
statically checkable constraints to ensure that streaming is
|
|
possible.</p>
|
|
</li>
|
|
<li>
|
|
<p>Streamed processing of any document can be initiated using the
|
|
<a href="#element-stream"><code>xsl:stream</code></a> instruction.
|
|
This has an attribute <code>href</code> whose value is the URI of a
|
|
document to be processed using streaming, and the actual processing
|
|
to be applied is defined by the instructions written as children of
|
|
the <a href="#element-stream"><code>xsl:stream</code></a>
|
|
instruction. These instructions must satisfy the same rules as for
|
|
a <a title="streamable template" class="termref" href=
|
|
"#dt-streamable-template">streamable template</a>.</p>
|
|
</li>
|
|
</ul>
|
|
<p>The rules for streamability, which are defined in detail in
|
|
<a href="#streamability"><i>18.4 Streamability Analysis</i></a>,
|
|
impose two main constraints:</p>
|
|
<ul>
|
|
<li>
|
|
<p>The only nodes reachable from the node that is currently being
|
|
processed are its attributes and namespaces, its ancestors and
|
|
their attributes and namespaces, and its descendants and their
|
|
attributes and namespaces. The siblings of the node, and the
|
|
siblings of its ancestors, are not reachable in the tree, and any
|
|
attempt to use their values is a <a title="static error" class=
|
|
"termref" href="#dt-static-error">static error</a>. However,
|
|
constructs (for example, simple forms of <a href=
|
|
"#element-number"><code>xsl:number</code></a>, and simple
|
|
positional <a title="pattern" class="termref" href=
|
|
"#dt-pattern">patterns</a>) that require knowledge of the number of
|
|
preceding elements by name are permitted.</p>
|
|
</li>
|
|
<li>
|
|
<p>When processing a given node in the tree, each descendant node
|
|
can only be visited once. Essentially this allows two styles of
|
|
processing: either visit each of the children once, and then
|
|
process that child with the same restrictions applied; or process
|
|
all the descendants in a single pass, in which case it is not
|
|
possible while processing a descendant to make any further downward
|
|
selection.</p>
|
|
</li>
|
|
</ul>
|
|
<p>The second restriction, that only one visit to the children is
|
|
allowed, means that XSLT code that was not designed with streaming
|
|
in mind will often need to be rewritten to make it streamable. In
|
|
many cases it is possible to do this using a technique sometimes
|
|
called <em>windowing</em> or <em>burst-mode streaming</em> (note
|
|
this is not quite the same meaning as <em>windowing</em> in XQuery
|
|
1.1.). Many XML documents consist of a large number of elements,
|
|
each of manageable size, representing transactions or business
|
|
objects where each such element can be processed independently: in
|
|
such cases, an effective design pattern is to write a streaming
|
|
transformation that takes a snapshot of each element in turn,
|
|
processing the snapshot using the full power of the XSLT language.
|
|
Each snapshot is a tree built in memory and is therefore fully
|
|
navigable. For details see the <a href=
|
|
"#function-snapshot"><code>snapshot</code></a> and <a href=
|
|
"#function-copy-of"><code>copy-of</code></a> functions.</p>
|
|
<p>Streaming applications often fall into one of the following
|
|
categories:</p>
|
|
<ul>
|
|
<li>
|
|
<p>Aggregation applications, where a single aggregation operation
|
|
(perhaps <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-count"><code>count</code></a><sup><small>FO</small></sup>,
|
|
<a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-sum"><code>sum</code></a><sup><small>FO</small></sup>,
|
|
<a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-exists"><code>exists</code></a><sup><small>FO</small></sup>,
|
|
or <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-distinct-values"><code>
|
|
distinct-values</code></a><sup><small>FO</small></sup>) is applied
|
|
to a set of elements selected from the streamed source document by
|
|
means of a path expression.</p>
|
|
</li>
|
|
<li>
|
|
<p>Record-at-a-time applications, where the source document
|
|
consists of a long sequence of elements with similar structure
|
|
("records"), and each "record" is processed using the same logic,
|
|
independently of any other "records". This kind of processing is
|
|
facilitated using the <a href=
|
|
"#function-snapshot"><code>snapshot</code></a> and <a href=
|
|
"#function-copy-of"><code>copy-of</code></a> function mentioned
|
|
earlier.</p>
|
|
</li>
|
|
<li>
|
|
<p>Grouping applications, where the output follows the structure of
|
|
the input, except that an extra layer of hierarchy is added. For
|
|
example, the input might be a flat series of banking transactions
|
|
in date/time order, and the output might contain the same
|
|
transactions grouped by date.</p>
|
|
</li>
|
|
<li>
|
|
<p>Accumulator applications, which are the same as record-at-a-time
|
|
applications, except that the processing of one "record" might
|
|
depend on data encountered earlier in the document. A classical
|
|
example is processing a sequence of banking transactions in which
|
|
the input transaction contains a debit or credit amount, and the
|
|
output adds a running total (the account balance). The <a href=
|
|
"#element-iterate"><code>xsl:iterate</code></a> instruction has
|
|
been introduced to facilitate this style of processing.</p>
|
|
</li>
|
|
<li>
|
|
<p>Isomorphic transformations, in which there is an ordered (often
|
|
largely one-to-one) relationship between the nodes of the source
|
|
tree and the nodes of the result tree: for example, transformations
|
|
that involve only the renaming or selective deletion of nodes, or
|
|
scalar manipulations of the values held in the leaf nodes. Such
|
|
transformations are most conveniently expressed using recursive
|
|
application of template rules. This is possible with a streamed
|
|
input document only if all the template rules adhere to the
|
|
constraints required for streamability. To enforce these rules,
|
|
while still allowing unrestricted processing of other documents
|
|
within the same transformation, all streaming evaluation must be
|
|
carried out using a specific <a title="mode" class="termref" href=
|
|
"#dt-mode">mode</a>, which is declared to be a streaming mode by
|
|
means of an <a href="#element-mode"><code>xsl:mode</code></a>
|
|
declaration in the stylesheet.</p>
|
|
</li>
|
|
</ul>
|
|
<p>There are important classes of application in which streaming is
|
|
possible only if multiple streams can be processed in parallel.
|
|
This specification therefore provides facilities:</p>
|
|
<ol class="enumar">
|
|
<li>
|
|
<p>allowing two sorted input sequences to be merged into one sorted
|
|
output sequence (the <a href=
|
|
"#element-merge"><code>xsl:merge</code></a> instruction)</p>
|
|
</li>
|
|
<li>
|
|
<p>allowing multiple output sequences to be generated during a
|
|
single pass of an input sequence (the <a href=
|
|
"#element-fork"><code>xsl:fork</code></a> instruction).</p>
|
|
</li>
|
|
</ol>
|
|
<p>These facilities have been designed in such a way that they can
|
|
readily be implemented using streaming, that is, without
|
|
materializing the input or output sequences in memory.</p>
|
|
<blockquote>
|
|
<p><b><a name="issue-streaming-pessimism" id=
|
|
"issue-streaming-pessimism">Issue 1
|
|
(streaming-pessimism)</a>:</b></p>
|
|
<p>The design adopted in this specification works on the basis that
|
|
decisions about streamability should be made statically (at compile
|
|
time). Sometimes this means taking a pessimistic approach, that is,
|
|
rejecting a construct as non-streamable based on worst-case
|
|
assumptions. Two examples of this are (a) disallowing
|
|
<code><xsl:with-param name="p" select="@code"/></code> when
|
|
calling a streamable template, on the grounds that the called
|
|
template might perform disallowed navigation from the attribute
|
|
node; (b) disallowing use of the descendant axis in cases where it
|
|
might select two elements, one of which is an ancestor of the
|
|
other. An alternative design approach would allow optimistic
|
|
assumptions to be made in such cases, creating the risk of dynamic
|
|
errors: for example it might be a dynamic error in the first case
|
|
if the called template performs disallowed navigation from the
|
|
attribute node, and in the second case if the descendant axis
|
|
actually selects a node that is a descendant of another selected
|
|
node. The decision to make the analysis pessimistic interacts with
|
|
the strategy for fallback if streaming is not possible; a
|
|
non-streaming fallback is feasible if decisions are made
|
|
statically, but is not realistically possible if the problems are
|
|
only detected at execution time. The Working Group welcomes
|
|
discussion of this decision.</p>
|
|
</blockquote>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="errors" id="errors"></a>2.10 <a href="#errors" style=
|
|
"text-decoration: none">Error Handling</a></h3>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-static-error" id="dt-static-error" title="static error"></a>An
|
|
error that can be detected by examining a <a title="stylesheet"
|
|
class="termref" href="#dt-stylesheet">stylesheet</a> before
|
|
execution starts (that is, before the source document and values of
|
|
stylesheet parameters are available) is referred to as a <b>static
|
|
error</b>.<span class="definition">]</span></p>
|
|
<p>Errors classified in this specification as static errors
|
|
<span class="verb">must</span> be signaled by all implementations:
|
|
that is, the <a title="processor" class="termref" href=
|
|
"#dt-processor">processor</a> <span class="verb">must</span>
|
|
indicate that the error is present. A static error <span class=
|
|
"verb">must</span> be signaled even if it occurs in a part of the
|
|
<a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a> that is never evaluated. Static
|
|
errors are never recoverable. After signaling a static error, a
|
|
processor <span class="verb">may</span> continue for the purpose of
|
|
signaling additional errors, but it <span class="verb">must</span>
|
|
eventually terminate abnormally without producing any <a title=
|
|
"final result tree" class="termref" href=
|
|
"#dt-final-result-tree">final result tree</a>.</p>
|
|
<p>There is an exception to this rule when the stylesheet specifies
|
|
<a title="forwards compatible behavior" class="termref" href=
|
|
"#dt-forwards-compatible-behavior">forwards compatible behavior</a>
|
|
(see <a href="#forwards"><i>3.9 Forwards Compatible
|
|
Processing</i></a>).</p>
|
|
<p>Generally, errors in the structure of the <a title="stylesheet"
|
|
class="termref" href="#dt-stylesheet">stylesheet</a>, or in the
|
|
syntax of XPath <a title="expression" class="termref" href=
|
|
"#dt-expression">expressions</a> contained in the stylesheet, are
|
|
classified as <a title="static error" class="termref" href=
|
|
"#dt-static-error">static errors</a>. Where this specification
|
|
states that an element in the stylesheet <span class=
|
|
"verb">must</span> or <span class="verb">must not</span> appear in
|
|
a certain position, or that it <span class="verb">must</span> or
|
|
<span class="verb">must not</span> have a particular attribute, or
|
|
that an attribute <span class="verb">must</span> or <span class=
|
|
"verb">must not</span> have a value satisfying specified
|
|
conditions, then any contravention of this rule is a static error
|
|
unless otherwise specified.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-dynamic-error" id="dt-dynamic-error" title=
|
|
"dynamic error"></a>An error that is not detected until a source
|
|
document is being transformed is referred to as a <b>dynamic
|
|
error</b>.<span class="definition">]</span></p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-recoverable-error" id="dt-recoverable-error" title=
|
|
"recoverable error"></a>Some dynamic errors are classed as
|
|
<b>recoverable errors</b>. When a recoverable error occurs, this
|
|
specification allows the processor either to signal the error (by
|
|
reporting the error condition and terminating execution) or to take
|
|
a defined recovery action and continue processing.<span class=
|
|
"definition">]</span> It is <a title="implementation-defined"
|
|
class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a> whether the
|
|
error is signaled or the recovery action is taken. If the processor
|
|
chooses to signal the error rather than taking the recovery action,
|
|
the error is then treated in the same way as a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> and is
|
|
therefore eligible to be caught using <a href=
|
|
"#element-try"><code>xsl:try</code></a>/<a href=
|
|
"#element-catch"><code>xsl:catch</code></a>.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-optional-recovery-action" id="dt-optional-recovery-action"
|
|
title="optional recovery action"></a>If an implementation chooses
|
|
to recover from a <a title="recoverable error" class="termref"
|
|
href="#dt-recoverable-error">recoverable dynamic error</a>, it
|
|
<span class="verb">must</span> take the <b>optional recovery
|
|
action</b> defined for that error condition in this
|
|
specification.<span class="definition">]</span></p>
|
|
<p>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 <span class="verb">may</span> provide
|
|
options that can be set by the user. When an implementation chooses
|
|
to recover from a dynamic error, it <span class="verb">may</span>
|
|
also take other action, such as logging a warning message.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-nonrec-dynamic-error" id="dt-nonrec-dynamic-error" title=
|
|
"non-recoverable dynamic error"></a>A <a title="dynamic error"
|
|
class="termref" href="#dt-dynamic-error">dynamic error</a> that is
|
|
not recoverable is referred to as a <b>non-recoverable dynamic
|
|
error</b>. When a non-recoverable dynamic error occurs, the
|
|
<a title="processor" class="termref" href=
|
|
"#dt-processor">processor</a> <span class="verb">must</span> signal
|
|
the error, and <span>(unless the error is caught using <a href=
|
|
"#element-catch"><code>xsl:catch</code></a>)</span> the
|
|
transformation fails.<span class="definition">]</span></p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>The term <b>non-recoverable</b> is retained from earlier XSLT
|
|
versions, and implies that the processor will not recover from the
|
|
error on its own initiative. However, the introduction of <a href=
|
|
"#element-try"><code>xsl:try</code></a> and <a href=
|
|
"#element-catch"><code>xsl:catch</code></a> in XSLT 2.1 means that
|
|
such errors can now be recovered by means of application logic.</p>
|
|
</div>
|
|
<p>Because different implementations may optimize execution of the
|
|
<a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a> in different ways, the detection of
|
|
dynamic errors is to some degree <a title=
|
|
"implementation-dependent" class="termref" href=
|
|
"#dt-implementation-dependent">implementation-dependent</a>. In
|
|
cases where an implementation is able to produce the <a title=
|
|
"final result tree" class="termref" href=
|
|
"#dt-final-result-tree">final result trees</a> without evaluating a
|
|
particular construct, the implementation is never <span class=
|
|
"verb">required</span> to evaluate that construct solely in order
|
|
to determine whether doing so causes a dynamic error. For example,
|
|
if a <a title="variable" class="termref" href=
|
|
"#dt-variable">variable</a> is declared but never referenced, an
|
|
implementation <span class="verb">may</span> 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.</p>
|
|
<p>There are some cases where this specification requires that a
|
|
construct <span class="verb">must not</span> be evaluated: for
|
|
example, the content of an <a href=
|
|
"#element-if"><code>xsl:if</code></a> instruction <span class=
|
|
"verb">must not</span> be evaluated if the test condition is false.
|
|
This means that an implementation <span class="verb">must
|
|
not</span> signal any dynamic errors that would arise if the
|
|
construct were evaluated.</p>
|
|
<p>An implementation <span class="verb">may</span> signal a
|
|
<a title="dynamic error" class="termref" href=
|
|
"#dt-dynamic-error">dynamic error</a> 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 <a title="" class="termref"
|
|
href="#circularity">circularity</a> errors fall into this category:
|
|
see <a href="#circularity"><i>9.9 Circular Definitions</i></a>.</p>
|
|
<p>There are also some <a title="dynamic error" class="termref"
|
|
href="#dt-dynamic-error">dynamic errors</a> where the specification
|
|
gives a processor license to signal the error during the analysis
|
|
phase even if the construct might never be executed; an example is
|
|
the use of an invalid QName as a literal argument to a function
|
|
such as <a href="#function-key"><code>key</code></a>, or the use of
|
|
an invalid regular expression in the <code>regex</code> attribute
|
|
of the <a href=
|
|
"#element-analyze-string"><code>xsl:analyze-string</code></a>
|
|
instruction.</p>
|
|
<p>The XPath specification states (see <a href=
|
|
"http://www.w3.org/TR/xpath-21/#id-kinds-of-errors">Section 2.3.1
|
|
Kinds of Errors</a><sup><small>XP21</small></sup>) that if any
|
|
expression (at any level) can be evaluated during the analysis
|
|
phase (because all its explicit operands are known and it has no
|
|
dependencies on the dynamic context), then any error in performing
|
|
this evaluation <span class="verb">may</span> be reported as a
|
|
static error. For XPath expressions used in an XSLT stylesheet,
|
|
however, any such errors <span class="verb">must not</span> be
|
|
reported as static errors in the stylesheet unless they would occur
|
|
in every possible evaluation of that stylesheet; instead, they must
|
|
be signaled as dynamic errors, and signaled only if the XPath
|
|
expression is actually evaluated.</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e2657" id=
|
|
"d7e2657"></a>Example: Errors in Constant Subexpressions</div>
|
|
<p>An XPath processor may report statically that the expression
|
|
<code>1 div 0</code> fails with a "divide by zero" error. But
|
|
suppose this XPath expression occurs in an XSLT construct such
|
|
as:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:choose>
|
|
<xsl:when test="system-property('xsl:version') = '1.0'">
|
|
<xsl:value-of select="1 div 0"/>
|
|
</xsl:when>
|
|
<xsl:otherwise>
|
|
<xsl:value-of select="xs:double('INF')"/>
|
|
</xsl:otherwise>
|
|
</xsl:choose>
|
|
</pre></div>
|
|
<p>Then the XSLT processor must not report an error, because the
|
|
relevant XPath construct appears in a context where it will never
|
|
be executed by an XSLT 2.0 <span>or 2.1</span> processor. (An XSLT
|
|
1.0 processor will execute this code successfully, returning
|
|
positive infinity, because it uses double arithmetic rather than
|
|
decimal arithmetic.)</p>
|
|
</div>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-type-error" id="dt-type-error" title="type errors"></a>Certain
|
|
errors are classified as <b>type errors</b>. 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.<span class="definition">]</span>
|
|
If a type error occurs in an instruction that is actually
|
|
evaluated, then it <span class="verb">must</span> be signaled in
|
|
the same way as a <a title="non-recoverable dynamic error" class=
|
|
"termref" href="#dt-nonrec-dynamic-error">non-recoverable dynamic
|
|
error</a>. Alternatively, an implementation <span class=
|
|
"verb">may</span> signal a type error during the analysis phase in
|
|
the same way as a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a>, 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.</p>
|
|
<p>It is <a title="implementation-defined" class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a> whether
|
|
type errors are signaled statically.</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e2702" id=
|
|
"d7e2702"></a>Example: A Type Error</div>
|
|
<p>The following construct contains a type error, because
|
|
<code>42</code> is not allowed as the value of the
|
|
<code>select</code> expression of the <a href=
|
|
"#element-number"><code>xsl:number</code></a> instruction (it must
|
|
be a node). An implementation <span class="verb">may</span>
|
|
optionally signal this as a static error, even though the offending
|
|
instruction will never be evaluated, and the type error would
|
|
therefore never be signaled as a dynamic error.</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:if test="false()">
|
|
<xsl:number select="42"/>
|
|
</xsl:if>
|
|
</pre></div>
|
|
<p>On the other hand, in the following example it is not possible
|
|
to determine statically whether the operand of <span><a href=
|
|
"#element-number"><code>xsl:number</code></a></span> will have a
|
|
suitable dynamic type. An implementation <span class=
|
|
"verb">may</span> produce a warning in such cases, but it
|
|
<span class="verb">must not</span> treat it as an error.</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:template match="para">
|
|
<xsl:param name="p" as="item()"/>
|
|
<xsl:number select="$p"/>
|
|
</xsl:template>
|
|
</pre></div>
|
|
</div>
|
|
<p>If more than one error arises, an implementation is not
|
|
<span class="verb">required</span> to signal any errors other than
|
|
the first one that it detects. It is <a title=
|
|
"implementation-dependent" class="termref" href=
|
|
"#dt-implementation-dependent">implementation-dependent</a> which
|
|
of the several errors is signaled. This applies both to static
|
|
errors and to dynamic errors. An implementation is allowed to
|
|
signal more than one error, but if any errors have been signaled,
|
|
it <span class="verb">must not</span> finish as if the
|
|
transformation were successful.</p>
|
|
<p>When a transformation signals one or more dynamic errors, the
|
|
final state of any persistent resources updated by the
|
|
transformation is <a title="implementation-dependent" class=
|
|
"termref" href=
|
|
"#dt-implementation-dependent">implementation-dependent</a>.
|
|
Implementations are not <span class="verb">required</span> to
|
|
restore such resources to their initial state. In particular, where
|
|
a transformation produces multiple result documents, it is possible
|
|
that one or more serialized result documents <span class=
|
|
"verb">may</span> be written successfully before the transformation
|
|
terminates, but the application cannot rely on this behavior.</p>
|
|
<p>Everything said above about error handling applies equally to
|
|
errors in evaluating XSLT instructions, and errors in evaluating
|
|
XPath <a title="expression" class="termref" href=
|
|
"#dt-expression">expressions</a>. Static errors and dynamic errors
|
|
may occur in both cases.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-serialization-error" id="dt-serialization-error" title=
|
|
"serialization error"></a>If a transformation has successfully
|
|
produced a <a title="final result tree" class="termref" href=
|
|
"#dt-final-result-tree">final result tree</a>, 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
|
|
<b>serialization error</b>.<span class="definition">]</span> If the
|
|
processor performs serialization, then it <span class=
|
|
"verb">must</span> do so as specified in <a href=
|
|
"#serialization"><i>23 Serialization</i></a>, and in particular it
|
|
<span class="verb">must</span> signal any serialization errors that
|
|
occur.</p>
|
|
<p>Errors are identified by a QName. For errors defined in this
|
|
specification, the namespace of the QName is always
|
|
<code>http://www.w3.org/2005/xqt-errors</code> (and is therefore
|
|
not given explicitly), while the local part is an 8-character code
|
|
in the form <var>PPSSNNNN</var>. Here <var>PP</var> is always
|
|
<code>XT</code> (meaning XSLT), and <var>SS</var> is one of
|
|
<code>SE</code> (static error), <code>DE</code> (dynamic error),
|
|
<code>RE</code> (recoverable dynamic error), or <code>TE</code>
|
|
(type error). Note that the allocation of an error to one of these
|
|
categories is purely for convenience and carries no normative
|
|
implications about the way the error is handled. Many errors, for
|
|
example, can be reported either dynamically or statically. These
|
|
error codes are used to label error conditions in this
|
|
specification, and are summarized in <a href="#error-summary"><i>D
|
|
Summary of Error Conditions</i></a>).</p>
|
|
<p>Errors defined in related specifications (<a href=
|
|
"#xpath-21">[XPath 2.1]</a>, <a href=
|
|
"#xpath-functions-11">[Functions and Operators]</a> <a href=
|
|
"#xslt-xquery-serialization-11">[XSLT and XQuery
|
|
Serialization]</a>) use QNames with a similar structure, in the
|
|
same namespace. When errors occur in processing XPath expressions,
|
|
an XSLT processor <span class="verb">should</span> use the original
|
|
error code reported by the XPath processor, unless a more specific
|
|
XSLT error code is available.</p>
|
|
<p><span>Implementations <span class="verb">must</span> use the
|
|
codes defined in these specifications when signaling errors, to
|
|
ensure that <a href="#element-catch"><code>xsl:catch</code></a>
|
|
behaves in an interoperable way across implementations. Stylesheet
|
|
authors should note, however, that there are many examples of
|
|
errors where more than one rule in this specification is violated,
|
|
and where the processor therefore has discretion in deciding which
|
|
error code to associate with the condition: there is therefore no
|
|
guarantee that different processors will always use the same error
|
|
code for the same erroneous input.</span></p>
|
|
<p>Additional errors defined by an implementation (or by an
|
|
application) <span class="verb">may</span> use QNames in an
|
|
implementation-defined (or user-defined) namespace without risk of
|
|
collision.</p>
|
|
</div>
|
|
</div>
|
|
<div class="div1">
|
|
<h2><a name="stylesheet-structure" id="stylesheet-structure"></a>3
|
|
<a href="#stylesheet-structure" style=
|
|
"text-decoration: none">Stylesheet Structure</a></h2>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-stylesheet-module" id="dt-stylesheet-module" title=
|
|
"stylesheet module"></a>A <a title="stylesheet" class="termref"
|
|
href="#dt-stylesheet">stylesheet</a> consists of one or more
|
|
<b>stylesheet modules</b>, each one forming all or part of an XML
|
|
document.<span class="definition">]</span></p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>A stylesheet module is represented by an XDM element node (see
|
|
<a href="#xpath-datamodel-11">[Data Model]</a>). In the case of a
|
|
standard stylesheet module, this will be an <a href=
|
|
"#element-stylesheet"><code>xsl:stylesheet</code></a> or <a href=
|
|
"#element-transform"><code>xsl:transform</code></a> element. In the
|
|
case of a simplified stylesheet module, it can be any element (not
|
|
in the <a title="XSLT namespace" class="termref" href=
|
|
"#dt-xslt-namespace">XSLT namespace</a>) that has an
|
|
<code>xsl:version</code> attribute.</p>
|
|
<p>Although stylesheet modules will commonly be maintained in the
|
|
form of documents conforming to XML 1.0 or XML 1.1, this
|
|
specification does not mandate such a representation. As with
|
|
<a title="source tree" class="termref" href=
|
|
"#dt-source-tree">source trees</a>, the way in which stylesheet
|
|
modules are constructed, from textual XML or otherwise, is outside
|
|
the scope of this specification.</p>
|
|
</div>
|
|
<p>A stylesheet module is either a standard stylesheet module or a
|
|
simplified stylesheet module:</p>
|
|
<ul>
|
|
<li>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-standard-stylesheet-module" id="dt-standard-stylesheet-module"
|
|
title="standard stylesheet module"></a>A <b>standard stylesheet
|
|
module</b> is a tree, or part of a tree, consisting of an <a href=
|
|
"#element-stylesheet"><code>xsl:stylesheet</code></a> or <a href=
|
|
"#element-transform"><code>xsl:transform</code></a> element (see
|
|
<a href="#stylesheet-element"><i>3.6 Stylesheet Element</i></a>)
|
|
together with its descendant nodes and associated attributes and
|
|
namespaces.<span class="definition">]</span></p>
|
|
</li>
|
|
<li>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-simplified-stylesheet-module" id=
|
|
"dt-simplified-stylesheet-module" title=
|
|
"simplified stylesheet module"></a>A <b>simplified stylesheet
|
|
module</b> is a tree, or part of a tree, consisting of a <a title=
|
|
"literal result element" class="termref" href=
|
|
"#dt-literal-result-element">literal result element</a> together
|
|
with its descendant nodes and associated attributes and namespaces.
|
|
This element is not itself in the XSLT namespace, but it
|
|
<span class="verb">must</span> have an <code>xsl:version</code>
|
|
attribute, which implies that it <span class="verb">must</span>
|
|
have a namespace node that declares a binding for the XSLT
|
|
namespace. For further details see <a href=
|
|
"#simplified-stylesheet"><i>3.7 Simplified Stylesheet
|
|
Modules</i></a>. <span class="definition">]</span></p>
|
|
</li>
|
|
</ul>
|
|
<p>Both forms of stylesheet module (standard and simplified) can
|
|
exist either as an entire XML document, or embedded as part of
|
|
another XML document, typically but not necessarily a source
|
|
document that is to be processed using the stylesheet.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-standalone-stylesheet-module" id=
|
|
"dt-standalone-stylesheet-module" title=
|
|
"standalone stylesheet module"></a>A <b>standalone stylesheet
|
|
module</b> is a stylesheet module that comprises the whole of an
|
|
XML document.<span class="definition">]</span></p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-embedded-stylesheet-module" id="dt-embedded-stylesheet-module"
|
|
title="embedded stylesheet module"></a>An <b>embedded stylesheet
|
|
module</b> is a stylesheet module that is embedded within another
|
|
XML document, typically the source document that is being
|
|
transformed.<span class="definition">]</span> (see <a href=
|
|
"#embedded"><i>3.11 Embedded Stylesheet Modules</i></a>).</p>
|
|
<p>There are thus four kinds of stylesheet module:</p>
|
|
<blockquote>
|
|
<p>standalone standard stylesheet modules<br />
|
|
standalone simplified stylesheet modules<br />
|
|
embedded standard stylesheet modules<br />
|
|
embedded simplified stylesheet modules</p>
|
|
</blockquote>
|
|
<div class="div2">
|
|
<h3><a name="xslt-namespace" id="xslt-namespace"></a>3.1 <a href=
|
|
"#xslt-namespace" style="text-decoration: none">XSLT
|
|
Namespace</a></h3>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-xslt-namespace" id="dt-xslt-namespace" title=
|
|
"XSLT namespace"></a>The <b>XSLT namespace</b> has the URI
|
|
<code>http://www.w3.org/1999/XSL/Transform</code>. It is used to
|
|
identify elements, attributes, and other names that have a special
|
|
meaning defined in this specification.<span class=
|
|
"definition">]</span></p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>The <code>1999</code> 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 <a href=
|
|
"#stylesheet-element"><i>3.6 Stylesheet Element</i></a> and
|
|
<a href="#simplified-stylesheet"><i>3.7 Simplified Stylesheet
|
|
Modules</i></a>).</p>
|
|
</div>
|
|
<p>XSLT <a title="processor" class="termref" href=
|
|
"#dt-processor">processors</a> <span class="verb">must</span> use
|
|
the XML namespaces mechanism <a href="#xml-names">[Namespaces in
|
|
XML]</a> to recognize elements and attributes from this namespace.
|
|
Elements from the XSLT namespace are recognized only in the
|
|
<a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a> and not in the source document. The
|
|
complete list of XSLT-defined elements is specified in <a href=
|
|
"#element-syntax-summary"><i>C Element Syntax Summary</i></a>.
|
|
<a title="implementation" class="termref" href=
|
|
"#dt-implementation">Implementations</a> <span class="verb">must
|
|
not</span> extend the XSLT namespace with additional elements or
|
|
attributes. Instead, any extension <span class="verb">must</span>
|
|
be in a separate namespace. Any namespace that is used for
|
|
additional instruction elements <span class="verb">must</span> be
|
|
identified by means of the <a title="extension instruction" class=
|
|
"termref" href="#dt-extension-instruction">extension
|
|
instruction</a> mechanism specified in <a href=
|
|
"#extension-instruction"><i>21.2 Extension
|
|
Instructions</i></a>.</p>
|
|
<p>This specification uses a prefix of <code>xsl:</code> 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.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>Throughout this specification, an element or attribute that is
|
|
in no namespace, or an <a title="expanded-QName" class="termref"
|
|
href="#dt-expanded-qname">expanded-QName</a> whose namespace part
|
|
is an empty sequence, is referred to as having a <b>null namespace
|
|
URI</b>.</p>
|
|
</div>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>The conventions used for the names of <a title="XSLT element"
|
|
class="termref" href="#dt-xslt-element">XSLT elements</a>,
|
|
attributes and functions are that names are all lower-case, use
|
|
hyphens to separate words, and use abbreviations only if they
|
|
already appear in the syntax of a related language such as XML or
|
|
HTML. Names of types defined in XML Schema are regarded as single
|
|
words and are capitalized exactly as in XML Schema. This sometimes
|
|
leads to composite function names such as <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-current-dateTime"><code>
|
|
current-dateTime</code></a><sup><small>FO</small></sup>.</p>
|
|
</div>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="reserved-namespaces" id="reserved-namespaces"></a>3.2
|
|
<a href="#reserved-namespaces" style=
|
|
"text-decoration: none">Reserved Namespaces</a></h3>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-reserved-namespace" id="dt-reserved-namespace" title=
|
|
"reserved namespace"></a>The XSLT namespace, together with certain
|
|
other namespaces recognized by an XSLT processor, are classified as
|
|
<b>reserved namespaces</b> and <span class="verb">must</span> be
|
|
used only as specified in this and related
|
|
specifications.<span class="definition">]</span> The reserved
|
|
namespaces are those listed below.</p>
|
|
<ul>
|
|
<li>
|
|
<p>The <a title="XSLT namespace" class="termref" href=
|
|
"#dt-xslt-namespace">XSLT namespace</a>, described in <a href=
|
|
"#xslt-namespace"><i>3.1 XSLT Namespace</i></a>, is reserved.</p>
|
|
</li>
|
|
<li>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-standard-function-namespace" id=
|
|
"dt-standard-function-namespace" title=
|
|
"standard function namespace"></a>The <b>standard function
|
|
namespace</b> <code>http://www.w3.org/2005/xpath-functions</code>
|
|
is used for functions in the function library defined in <a href=
|
|
"#xpath-functions-11">[Functions and Operators]</a> and for
|
|
standard functions defined in this specification.<span class=
|
|
"definition">]</span></p>
|
|
</li>
|
|
<li>
|
|
<p>The namespace
|
|
<code>http://www.w3.org/2005/xpath-functions/math</code> is used
|
|
for mathematical functions in the function library defined in
|
|
<a href="#xpath-functions-11">[Functions and Operators]</a>.</p>
|
|
</li>
|
|
<li>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"xml-namespace" id="xml-namespace" title="XML namespace"></a>The
|
|
<b>XML namespace</b>, defined in <a href="#xml-names">[Namespaces
|
|
in XML]</a> as <code>http://www.w3.org/XML/1998/namespace</code>,
|
|
is used for attributes such as <code>xml:lang</code>,
|
|
<code>xml:space</code>, and <code>xml:id</code>.<span class=
|
|
"definition">]</span></p>
|
|
</li>
|
|
<li>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-schema-namespace" id="dt-schema-namespace" title=
|
|
"schema namespace"></a>The <b>schema namespace</b>
|
|
<code>http://www.w3.org/2001/XMLSchema</code> is used as defined in
|
|
<a href="#xmlschema-1">[XML Schema Part 1]</a><span class=
|
|
"definition">]</span>. In a <a title="stylesheet" class="termref"
|
|
href="#dt-stylesheet">stylesheet</a> this namespace may be used to
|
|
refer to built-in schema datatypes and to the constructor functions
|
|
associated with those datatypes.</p>
|
|
</li>
|
|
<li>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-schema-instance-namespace" id="dt-schema-instance-namespace"
|
|
title="schema instance namespace"></a>The <b>schema instance
|
|
namespace</b>
|
|
<code>http://www.w3.org/2001/XMLSchema-instance</code> is used as
|
|
defined in <a href="#xmlschema-1">[XML Schema Part
|
|
1]</a><span class="definition">]</span>. Attributes in this
|
|
namespace, if they appear in a <a title="stylesheet" class=
|
|
"termref" href="#dt-stylesheet">stylesheet</a>, are treated by the
|
|
XSLT processor in the same way as any other attributes.</p>
|
|
</li>
|
|
<li>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-standard-error-namespace" id="dt-standard-error-namespace"
|
|
title="standard error namespace"></a>The <b>standard error
|
|
namespace</b> <code>http://www.w3.org/2005/xqt-errors</code> is
|
|
used for error codes defined in this specification and related
|
|
specifications. It is also used for the names of certain predefined
|
|
variables accessible within the scope of an <a href=
|
|
"#element-catch"><code>xsl:catch</code></a> element.<span class=
|
|
"definition">]</span></p>
|
|
</li>
|
|
<li>
|
|
<p>The namespace <code>http://www.w3.org/2000/xmlns/</code> is
|
|
reserved for use as described in <a href="#xml-names">[Namespaces
|
|
in XML]</a>. No element or attribute node can have a name in this
|
|
namespace, and although the prefix <code>xmlns</code> is implicitly
|
|
bound to this namespace, no namespace node will ever define this
|
|
binding.</p>
|
|
</li>
|
|
</ul>
|
|
<p>Reserved namespaces may be used without restriction to refer to
|
|
the names of elements and attributes in source documents and result
|
|
documents. As far as the XSLT processor is concerned, reserved
|
|
namespaces other than the XSLT namespace may be used without
|
|
restriction in the names of <a title="literal result element"
|
|
class="termref" href="#dt-literal-result-element">literal result
|
|
elements</a> and <a title="user-defined data element" class=
|
|
"termref" href="#dt-data-element">user-defined data elements</a>,
|
|
and in the names of attributes of literal result elements or of
|
|
<a title="XSLT element" class="termref" href=
|
|
"#dt-xslt-element">XSLT elements</a>: but other processors
|
|
<span class="verb">may</span> impose restrictions or attach special
|
|
meaning to them. Reserved namespaces <span class="verb">must
|
|
not</span> be used, however, in the names of stylesheet-defined
|
|
objects such as <a title="variable" class="termref" href=
|
|
"#dt-variable">variables</a> and <a title="stylesheet function"
|
|
class="termref" href="#dt-stylesheet-function">stylesheet
|
|
functions</a>.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>With the exception of the XML namespace, any of the above
|
|
namespaces that are used in a stylesheet must be explicitly
|
|
declared with a namespace declaration. Although conventional
|
|
prefixes are used for these namespaces in this specification, any
|
|
prefix may be used in a user stylesheet.</p>
|
|
</div>
|
|
<p><a name="err-XTSE0080" id="err-XTSE0080"><span class=
|
|
"error">[ERR XTSE0080]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> to use a
|
|
<a title="reserved namespace" class="termref" href=
|
|
"#dt-reserved-namespace">reserved namespace</a> in the name of a
|
|
<a title="named template" class="termref" href=
|
|
"#dt-named-template">named template</a>, a <a title="mode" class=
|
|
"termref" href="#dt-mode">mode</a>, an <a title="attribute set"
|
|
class="termref" href="#dt-attribute-set">attribute set</a>, a
|
|
<a title="key" class="termref" href="#dt-key">key</a>, a <a title=
|
|
"decimal format" class="termref" href=
|
|
"#dt-decimal-format">decimal-format</a>, a <a title="variable"
|
|
class="termref" href="#dt-variable">variable</a> or <a title=
|
|
"parameter" class="termref" href="#dt-parameter">parameter</a>, a
|
|
<a title="stylesheet function" class="termref" href=
|
|
"#dt-stylesheet-function">stylesheet function</a>, a named
|
|
<a title="output definition" class="termref" href=
|
|
"#dt-output-definition">output definition</a>, or a <a title=
|
|
"character map" class="termref" href="#dt-character-map">character
|
|
map</a>.</p>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="extension-attributes" id=
|
|
"extension-attributes"></a>3.3 <a href="#extension-attributes"
|
|
style="text-decoration: none">Extension Attributes</a></h3>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-extension-attribute" id="dt-extension-attribute" title=
|
|
"extension attribute"></a>An element from the XSLT namespace may
|
|
have any attribute not from the XSLT namespace, provided that the
|
|
<a title="expanded-QName" class="termref" href=
|
|
"#dt-expanded-qname">expanded-QName</a> (see <a href=
|
|
"#xpath-21">[XPath 2.1]</a>) of the attribute has a non-null
|
|
namespace URI. These attributes are referred to as <b>extension
|
|
attributes</b>.<span class="definition">]</span> The presence of an
|
|
extension attribute <span class="verb">must not</span> cause the
|
|
<a title="final result tree" class="termref" href=
|
|
"#dt-final-result-tree">final result trees</a> produced by the
|
|
transformation to be different from the result trees that a
|
|
conformant XSLT <span>2.1</span> processor might produce. They
|
|
<span class="verb">must not</span> cause the processor to fail to
|
|
signal an error that a conformant processor is required to signal.
|
|
This means that an extension attribute <span class="verb">must
|
|
not</span> change the effect of any <a title="instruction" class=
|
|
"termref" href="#dt-instruction">instruction</a> except to the
|
|
extent that the effect is <a title="implementation-defined" class=
|
|
"termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a> or
|
|
<a title="implementation-dependent" class="termref" href=
|
|
"#dt-implementation-dependent">implementation-dependent</a>.</p>
|
|
<p>Furthermore, if serialization is performed using one of the
|
|
serialization methods <code>xml</code>, <code>xhtml</code>,
|
|
<code>html</code>, or <code>text</code> described in <a href=
|
|
"#xslt-xquery-serialization-11">[XSLT and XQuery
|
|
Serialization]</a>, the presence of an extension attribute must not
|
|
cause the serializer to behave in a way that is inconsistent with
|
|
the mandatory provisions of that specification.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p><a title="extension attribute" class="termref" href=
|
|
"#dt-extension-attribute">Extension attributes</a> may be used to
|
|
modify the behavior of <a title="extension function" class=
|
|
"termref" href="#dt-extension-function">extension functions</a> and
|
|
<a title="extension instruction" class="termref" href=
|
|
"#dt-extension-instruction">extension instructions</a>. They may be
|
|
used to select processing options in cases where the specification
|
|
leaves the behavior <a title="implementation-defined" class=
|
|
"termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a> or
|
|
<a title="implementation-dependent" class="termref" href=
|
|
"#dt-implementation-dependent">implementation-dependent</a>. They
|
|
may also be used for optimization hints, for diagnostics, or for
|
|
documentation.</p>
|
|
<p><a title="extension attribute" class="termref" href=
|
|
"#dt-extension-attribute">Extension attributes</a> <span class=
|
|
"verb">may</span> also be used to influence the behavior of the
|
|
serialization methods <code>xml</code>, <code>xhtml</code>,
|
|
<code>html</code>, or <code>text</code>, to the extent that the
|
|
behavior of the serialization method is <a title=
|
|
"implementation-defined" class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a> or
|
|
<a title="implementation-dependent" class="termref" href=
|
|
"#dt-implementation-dependent">implementation-dependent</a>. For
|
|
example, an extension attribute might be used to define the amount
|
|
of indentation to be used when <code>indent="yes"</code> is
|
|
specified. If a serialization method other than one of these four
|
|
is requested (using a prefixed QName in the method parameter) then
|
|
extension attributes may influence its behavior in arbitrary ways.
|
|
Extension attributes <span class="verb">must not</span> be used to
|
|
cause the four standard serialization methods to behave in a
|
|
non-conformant way, for example by failing to report serialization
|
|
errors that a serializer is <span class="verb">required</span> to
|
|
report. An implementation that wishes to provide such options must
|
|
create a new serialization method for the purpose.</p>
|
|
<p>An implementation that does not recognize the name of an
|
|
extension attribute, or that does not recognize its value,
|
|
<span class="verb">must</span> perform the transformation as if the
|
|
extension attribute were not present. As always, it is permissible
|
|
to produce warning messages.</p>
|
|
<p>The namespace used for an extension attribute will be copied to
|
|
the <a title="result tree" class="termref" href=
|
|
"#dt-result-tree">result tree</a> in the normal way if it is in
|
|
scope for a <a title="literal result element" class="termref" href=
|
|
"#dt-literal-result-element">literal result element</a>. This can
|
|
be prevented using the <code>[xsl:]exclude-result-prefixes</code>
|
|
attribute.</p>
|
|
</div>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e3362" id=
|
|
"d7e3362"></a>Example: An Extension Attribute for
|
|
<code>xsl:message</code></div>
|
|
<p>The following code might be used to indicate to a particular
|
|
implementation that the <a href=
|
|
"#element-message"><code>xsl:message</code></a> instruction is to
|
|
ask the user for confirmation before continuing with the
|
|
transformation:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:message abc:pause="yes"
|
|
xmlns:abc="http://vendor.example.com/xslt/extensions">
|
|
Phase 1 complete
|
|
</xsl:message>
|
|
</pre></div>
|
|
<p>Implementations that do not recognize the namespace
|
|
<code>http://vendor.example.com/xslt/extensions</code> will simply
|
|
ignore the extra attribute, and evaluate the <a href=
|
|
"#element-message"><code>xsl:message</code></a> instruction in the
|
|
normal way.</p>
|
|
</div>
|
|
<p><a name="err-XTSE0090" id="err-XTSE0090"><span class=
|
|
"error">[ERR XTSE0090]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> for an
|
|
element from the XSLT namespace to have an attribute whose
|
|
namespace is either null (that is, an attribute with an unprefixed
|
|
name) or the XSLT namespace, other than attributes defined for the
|
|
element in this document.</p>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="xslt-media-type" id="xslt-media-type"></a>3.4 <a href=
|
|
"#xslt-media-type" style="text-decoration: none">XSLT Media
|
|
Type</a></h3>
|
|
<p>The media type <code>application/xslt+xml</code> <span>has
|
|
been</span> registered for XSLT stylesheet modules.</p>
|
|
<p>The definition of the media type is at <a href=
|
|
"#XSLT-Mime-Type">[XSLT Media Type]</a>.</p>
|
|
<p>This media type <span class="verb">should</span> be used for an
|
|
XML document containing a <a title="standard stylesheet module"
|
|
class="termref" href="#dt-standard-stylesheet-module">standard
|
|
stylesheet module</a> at its top level, and it <span class=
|
|
"verb">may</span> also be used for a <a title=
|
|
"simplified stylesheet module" class="termref" href=
|
|
"#dt-simplified-stylesheet-module">simplified stylesheet
|
|
module</a>. It <span class="verb">should not</span> be used for an
|
|
XML document containing an <a title="embedded stylesheet module"
|
|
class="termref" href="#dt-embedded-stylesheet-module">embedded
|
|
stylesheet module</a>.</p>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="standard-attributes" id="standard-attributes"></a>3.5
|
|
<a href="#standard-attributes" style=
|
|
"text-decoration: none">Standard Attributes</a></h3>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-standard-attributes" id="dt-standard-attributes" title=
|
|
"standard attributes"></a>There are a number of <b>standard
|
|
attributes</b> that may appear on any <a title="XSLT element"
|
|
class="termref" href="#dt-xslt-element">XSLT element</a>:
|
|
specifically <code>version</code>,
|
|
<code>exclude-result-prefixes</code>,
|
|
<code>extension-element-prefixes</code>,
|
|
<code>xpath-default-namespace</code>,
|
|
<code>default-collation</code>, and
|
|
<code>use-when</code>.<span class="definition">]</span></p>
|
|
<p>These attributes may also appear on a <a title=
|
|
"literal result element" class="termref" href=
|
|
"#dt-literal-result-element">literal result element</a>, but in
|
|
this case, to distinguish them from user-defined attributes, the
|
|
names of the attributes are in the <a title="XSLT namespace" class=
|
|
"termref" href="#dt-xslt-namespace">XSLT namespace</a>. They are
|
|
thus typically written as <code>xsl:version</code>,
|
|
<code>xsl:exclude-result-prefixes</code>,
|
|
<code>xsl:extension-element-prefixes</code>,
|
|
<code>xsl:xpath-default-namespace</code>,
|
|
<code>xsl:default-collation</code>, or
|
|
<code>xsl:use-when</code>.</p>
|
|
<p>It is <span class="verb">recommended</span> that all these
|
|
attributes should also be permitted on <a title=
|
|
"extension instruction" class="termref" href=
|
|
"#dt-extension-instruction">extension instructions</a>, but this is
|
|
at the discretion of the implementer of each extension instruction.
|
|
They <span class="verb">may</span> also be permitted on <a title=
|
|
"user-defined data element" class="termref" href=
|
|
"#dt-data-element">user-defined data elements</a>, though they will
|
|
only have any useful effect in the case of data elements that are
|
|
designed to behave like XSLT declarations or instructions.</p>
|
|
<p>In the following descriptions, these attributes are referred to
|
|
generically as <code>[xsl:]version</code>, and so on.</p>
|
|
<p>These attributes all affect the element they appear on, together
|
|
with any elements and attributes that have that element as an
|
|
ancestor. The two forms with and without the XSLT namespace have
|
|
the same effect; the XSLT namespace is used for the attribute if
|
|
and only if its parent element is <em>not</em> in the XSLT
|
|
namespace.</p>
|
|
<p>In the case of <code>[xsl:]version</code>,
|
|
<code>[xsl:]xpath-default-namespace</code>, and
|
|
<code>[xsl:]default-collation</code>, the value can be overridden
|
|
by a different value for the same attribute appearing on a
|
|
descendant element. The effective value of the attribute for a
|
|
particular stylesheet element is determined by the innermost
|
|
ancestor-or-self element on which the attribute appears.</p>
|
|
<p>In an <a title="embedded stylesheet module" class="termref"
|
|
href="#dt-embedded-stylesheet-module">embedded stylesheet
|
|
module</a>, <a title="standard attributes" class="termref" href=
|
|
"#dt-standard-attributes">standard attributes</a> appearing on
|
|
ancestors of the outermost element of the stylesheet module have no
|
|
effect.</p>
|
|
<p>In the case of <code>[xsl:]exclude-result-prefixes</code> and
|
|
<code>[xsl:]extension-element-prefixes</code> the values are
|
|
cumulative. For these attributes, the value is given as a
|
|
whitespace-separated list of namespace prefixes, and the effective
|
|
value for an element is the combined set of namespace URIs
|
|
designated by the prefixes that appear in this attribute for that
|
|
element and any of its ancestor elements. Again, the two forms with
|
|
and without the XSLT namespace are equivalent.</p>
|
|
<p>The effect of the <code>[xsl:]use-when</code> attribute is
|
|
described in <a href="#conditional-inclusion"><i>3.12 Conditional
|
|
Element Inclusion</i></a>.</p>
|
|
<p>Because these attributes may appear on any <a title=
|
|
"XSLT element" class="termref" href="#dt-xslt-element">XSLT
|
|
element</a>, they are not listed in the syntax summary of each
|
|
individual element. Instead they are listed and described in the
|
|
entry for the <a href=
|
|
"#element-stylesheet"><code>xsl:stylesheet</code></a> and <a href=
|
|
"#element-transform"><code>xsl:transform</code></a> elements only.
|
|
This reflects the fact that these attributes are often used on the
|
|
<a href="#element-stylesheet"><code>xsl:stylesheet</code></a>
|
|
element only, in which case they apply to the entire <a title=
|
|
"stylesheet module" class="termref" href=
|
|
"#dt-stylesheet-module">stylesheet module</a>.</p>
|
|
<p>Note that the effect of these attributes does <em>not</em>
|
|
extend to <a title="stylesheet module" class="termref" href=
|
|
"#dt-stylesheet-module">stylesheet modules</a> referenced by
|
|
<a href="#element-include"><code>xsl:include</code></a> or <a href=
|
|
"#element-import"><code>xsl:import</code></a> declarations.</p>
|
|
<p>For the detailed effect of each attribute, see the following
|
|
sections:</p>
|
|
<dl>
|
|
<dt class="label"><code>[xsl:]version</code></dt>
|
|
<dd>
|
|
<p>see <a href="#backwards"><i>3.8 Backwards Compatible
|
|
Processing</i></a> and <a href="#forwards"><i>3.9 Forwards
|
|
Compatible Processing</i></a></p>
|
|
</dd>
|
|
<dt class="label"><code>[xsl:]xpath-default-namespace</code></dt>
|
|
<dd>
|
|
<p>see <a href="#unprefixed-qnames"><i>5.2 Unprefixed QNames in
|
|
Expressions and Patterns</i></a></p>
|
|
</dd>
|
|
<dt class="label"><code>[xsl:]exclude-result-prefixes</code></dt>
|
|
<dd>
|
|
<p>see <a href="#lre-namespaces"><i>11.1.3 Namespace Nodes for
|
|
Literal Result Elements</i></a></p>
|
|
</dd>
|
|
<dt class="label">
|
|
<code>[xsl:]extension-element-prefixes</code></dt>
|
|
<dd>
|
|
<p>see <a href="#extension-instruction"><i>21.2 Extension
|
|
Instructions</i></a></p>
|
|
</dd>
|
|
<dt class="label"><code>[xsl:]use-when</code></dt>
|
|
<dd>
|
|
<p>see <a href="#conditional-inclusion"><i>3.12 Conditional Element
|
|
Inclusion</i></a></p>
|
|
</dd>
|
|
<dt class="label"><code>[xsl:]default-collation</code></dt>
|
|
<dd>
|
|
<p>see <a href="#default-collation-attribute"><i>3.6.1 The
|
|
default-collation attribute</i></a></p>
|
|
</dd>
|
|
</dl>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="stylesheet-element" id="stylesheet-element"></a>3.6
|
|
<a href="#stylesheet-element" style=
|
|
"text-decoration: none">Stylesheet Element</a></h3>
|
|
<p class="element-syntax"><a name="element-stylesheet" id=
|
|
"element-stylesheet"></a><code><xsl:stylesheet<br />
|
|
  id? = <var>id</var><br />
|
|
  extension-element-prefixes? = <var>tokens</var><br />
|
|
  exclude-result-prefixes? = <var>tokens</var><br />
|
|
  <b>version</b> = <var>number</var><br />
|
|
  xpath-default-namespace? = <var>uri</var><br />
|
|
  default-validation? = "preserve" | "strip"<br />
|
|
  default-collation? = <var>uri-list</var><br />
|
|
  default-mode? = <var>qname</var> | "#unnamed"<br />
|
|
  input-type-annotations? = "preserve" | "strip" |
|
|
"unspecified" ><br />
|
|
  <!-- Content: (<a href=
|
|
"#element-import">xsl:import</a>*, <var>other-declarations</var>)
|
|
--><br />
|
|
</xsl:stylesheet></code></p>
|
|
<p class="element-syntax"><a name="element-transform" id=
|
|
"element-transform"></a><code><xsl:transform<br />
|
|
  id? = <var>id</var><br />
|
|
  extension-element-prefixes? = <var>tokens</var><br />
|
|
  exclude-result-prefixes? = <var>tokens</var><br />
|
|
  <b>version</b> = <var>number</var><br />
|
|
  xpath-default-namespace? = <var>uri</var><br />
|
|
  default-validation? = "preserve" | "strip"<br />
|
|
  default-collation? = <var>uri-list</var><br />
|
|
  default-mode? = <var>qname</var> | "#unnamed"<br />
|
|
  input-type-annotations? = "preserve" | "strip" |
|
|
"unspecified" ><br />
|
|
  <!-- Content: (<a href=
|
|
"#element-import">xsl:import</a>*, <var>other-declarations</var>)
|
|
--><br />
|
|
</xsl:transform></code></p>
|
|
<p>A stylesheet module is represented by an <a href=
|
|
"#element-stylesheet"><code>xsl:stylesheet</code></a> element in an
|
|
XML document. <a href=
|
|
"#element-transform"><code>xsl:transform</code></a> is allowed as a
|
|
synonym for <a href=
|
|
"#element-stylesheet"><code>xsl:stylesheet</code></a>; everything
|
|
this specification says about the <a href=
|
|
"#element-stylesheet"><code>xsl:stylesheet</code></a> element
|
|
applies equally to <a href=
|
|
"#element-transform"><code>xsl:transform</code></a>.</p>
|
|
<p>An <a href="#element-stylesheet"><code>xsl:stylesheet</code></a>
|
|
element <span class="verb">must</span> have a <code>version</code>
|
|
attribute, indicating the version of XSLT that the stylesheet
|
|
module requires.</p>
|
|
<p><a name="err-XTSE0110" id="err-XTSE0110"><span class=
|
|
"error">[ERR XTSE0110]</span></a> The value of the
|
|
<code>version</code> attribute <span class="verb">must</span> be a
|
|
number: specifically, it <span class="verb">must</span> be a a
|
|
valid instance of the type <code>xs:decimal</code> as defined in
|
|
<a href="#xmlschema-2">[XML Schema Part 2]</a>.</p>
|
|
<p>The <code>version</code> attribute is intended to indicate the
|
|
version of the XSLT specification against which the stylesheet is
|
|
written. In a stylesheet written to use XSLT 2.1, the value
|
|
<span class="verb">should</span> normally be set to
|
|
<code>2.1</code>. If the value is numerically less than
|
|
<code>2.1</code>, the stylesheet is processed using the rules for
|
|
<a title="backwards compatible behavior" class="termref" href=
|
|
"#dt-backwards-compatible-behavior">backwards compatible
|
|
behavior</a> (see <a href="#backwards"><i>3.8 Backwards Compatible
|
|
Processing</i></a>). If the value is numerically greater than
|
|
<code>2.1</code>, the stylesheet is processed using the rules for
|
|
<a title="forwards compatible behavior" class="termref" href=
|
|
"#dt-forwards-compatible-behavior">forwards compatible behavior</a>
|
|
(see <a href="#forwards"><i>3.9 Forwards Compatible
|
|
Processing</i></a>).</p>
|
|
<p>The effect of the <code>input-type-annotations</code> attribute
|
|
is described in <a href="#stripping-annotations"><i>4.3 Stripping
|
|
Type Annotations from a Source Tree</i></a>.</p>
|
|
<p>The <code>default-validation</code> attribute defines the
|
|
default value of the <code>validation</code> attribute of all
|
|
<a href="#element-document"><code>xsl:document</code></a>, <a href=
|
|
"#element-element"><code>xsl:element</code></a>, <a href=
|
|
"#element-attribute"><code>xsl:attribute</code></a>, <a href=
|
|
"#element-copy"><code>xsl:copy</code></a>, <a href=
|
|
"#element-copy-of"><code>xsl:copy-of</code></a>, and <a href=
|
|
"#element-result-document"><code>xsl:result-document</code></a>
|
|
instructions, and of the <code>xsl:validation</code> attribute of
|
|
all <a title="literal result element" class="termref" href=
|
|
"#dt-literal-result-element">literal result elements</a>. It also
|
|
determines the validation applied to the implicit <a title=
|
|
"final result tree" class="termref" href=
|
|
"#dt-final-result-tree">final result tree</a> created in the
|
|
absence of an <a href=
|
|
"#element-result-document"><code>xsl:result-document</code></a>
|
|
instruction. This default applies within the <a title=
|
|
"stylesheet module" class="termref" href=
|
|
"#dt-stylesheet-module">stylesheet module</a>: it does not extend
|
|
to included or imported stylesheet modules. If the attribute is
|
|
omitted, the default is <code>strip</code>. The permitted values
|
|
are <code>preserve</code> and <code>strip</code>. For details of
|
|
the effect of this attribute, see <a href="#validation"><i>22.2
|
|
Validation</i></a>.</p>
|
|
<p><a name="err-XTSE0120" id="err-XTSE0120"><span class=
|
|
"error">[ERR XTSE0120]</span></a> An <a href=
|
|
"#element-stylesheet"><code>xsl:stylesheet</code></a> element
|
|
<span class="verb">must not</span> have any text node children.
|
|
(This rule applies after stripping of <a title=
|
|
"whitespace text node" class="termref" href=
|
|
"#dt-whitespace-text-node">whitespace text nodes</a> as described
|
|
in <a href="#stylesheet-stripping"><i>4.2 Stripping Whitespace from
|
|
the Stylesheet</i></a>.)</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-top-level" id="dt-top-level" title="top-level"></a>An element
|
|
occurring as a child of an <a href=
|
|
"#element-stylesheet"><code>xsl:stylesheet</code></a> element is
|
|
called a <b>top-level</b> element.<span class=
|
|
"definition">]</span></p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-declaration" id="dt-declaration" title=
|
|
"declaration"></a>Top-level elements fall into two categories:
|
|
declarations, and user-defined data elements. Top-level elements
|
|
whose names are in the <a title="XSLT namespace" class="termref"
|
|
href="#dt-xslt-namespace">XSLT namespace</a> are
|
|
<b>declarations</b>. Top-level elements in any other namespace are
|
|
<a title="user-defined data element" class="termref" href=
|
|
"#dt-data-element">user-defined data elements</a> (see <a href=
|
|
"#user-defined-top-level"><i>3.6.3 User-defined Data
|
|
Elements</i></a>)<span class="definition">]</span>.</p>
|
|
<p>The <a title="declaration" class="termref" href=
|
|
"#dt-declaration">declaration</a> elements permitted in the
|
|
<a href="#element-stylesheet"><code>xsl:stylesheet</code></a>
|
|
element are:</p>
|
|
<blockquote>
|
|
<p><a href="#element-import"><code>xsl:import</code></a><br />
|
|
<a href="#element-include"><code>xsl:include</code></a><br />
|
|
<a href=
|
|
"#element-attribute-set"><code>xsl:attribute-set</code></a><br />
|
|
<a href=
|
|
"#element-character-map"><code>xsl:character-map</code></a><br />
|
|
<a href=
|
|
"#element-decimal-format"><code>xsl:decimal-format</code></a><br />
|
|
<a href="#element-function"><code>xsl:function</code></a><br />
|
|
<a href=
|
|
"#element-import-schema"><code>xsl:import-schema</code></a><br />
|
|
<a href="#element-key"><code>xsl:key</code></a><br />
|
|
<span><a href=
|
|
"#element-mode"><code>xsl:mode</code></a></span><br />
|
|
<a href=
|
|
"#element-namespace-alias"><code>xsl:namespace-alias</code></a><br />
|
|
|
|
<a href="#element-output"><code>xsl:output</code></a><br />
|
|
<a href="#element-param"><code>xsl:param</code></a><br />
|
|
<a href=
|
|
"#element-preserve-space"><code>xsl:preserve-space</code></a><br />
|
|
<a href=
|
|
"#element-strip-space"><code>xsl:strip-space</code></a><br />
|
|
<a href="#element-template"><code>xsl:template</code></a><br />
|
|
<a href="#element-variable"><code>xsl:variable</code></a></p>
|
|
</blockquote>
|
|
<p>Note that the <a href=
|
|
"#element-variable"><code>xsl:variable</code></a> and <a href=
|
|
"#element-param"><code>xsl:param</code></a> elements can act either
|
|
as <a title="declaration" class="termref" href=
|
|
"#dt-declaration">declarations</a> or as <a title="instruction"
|
|
class="termref" href="#dt-instruction">instructions</a>. A global
|
|
variable or parameter is defined using a declaration; a local
|
|
variable or parameter using an instruction.</p>
|
|
<p>If there are <a href=
|
|
"#element-import"><code>xsl:import</code></a> elements, these
|
|
<span class="verb">must</span> come before any other elements.
|
|
Apart from this, the child elements of the <a href=
|
|
"#element-stylesheet"><code>xsl:stylesheet</code></a> element may
|
|
appear in any order. <span>In most cases, the ordering of these
|
|
elements does not affect the results of the transformation;
|
|
however, as described in <a href="#conflict"><i>6.4 Conflict
|
|
Resolution for Template Rules</i></a>, when two template rules with
|
|
the same <a title="priority" class="termref" href=
|
|
"#dt-priority">priority</a> match the same nodes, there are
|
|
situations where the order of the template rules will affect which
|
|
is chosen.</span></p>
|
|
<div class="div3">
|
|
<h4><a name="default-collation-attribute" id=
|
|
"default-collation-attribute"></a>3.6.1 <a href=
|
|
"#default-collation-attribute" style=
|
|
"text-decoration: none">The</a> <code>default-collation</code>
|
|
<a href="#default-collation-attribute" style=
|
|
"text-decoration: none">attribute</a></h4>
|
|
<p>The <code>default-collation</code> attribute is a <a title=
|
|
"standard attributes" class="termref" href=
|
|
"#dt-standard-attributes">standard attribute</a> that may appear on
|
|
any element in the XSLT namespace, or (as
|
|
<code>xsl:default-collation</code>) on a <a title=
|
|
"literal result element" class="termref" href=
|
|
"#dt-literal-result-element">literal result element</a>.</p>
|
|
<p>The attribute is used to specify the default collation used by
|
|
all XPath expressions appearing in the attributes of this element,
|
|
or attributes of descendant elements, unless overridden by another
|
|
<code>default-collation</code> attribute on an inner element. It
|
|
also determines the collation used by certain XSLT constructs (such
|
|
as <a href="#element-key"><code>xsl:key</code></a> and <a href=
|
|
"#element-for-each-group"><code>xsl:for-each-group</code></a>)
|
|
within its scope.</p>
|
|
<p>The value of the attribute is a whitespace-separated list of
|
|
collation URIs. If any of these URIs is a relative URI
|
|
<span>reference</span>, then it is resolved relative to the base
|
|
URI of the attribute's parent element. If the implementation
|
|
recognizes one or more of the resulting absolute collation URIs,
|
|
then it uses the first one that it recognizes as the default
|
|
collation.</p>
|
|
<p><a name="err-XTSE0125" id="err-XTSE0125"><span class=
|
|
"error">[ERR XTSE0125]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> if the
|
|
value of an <code>[xsl:]default-collation</code> attribute, after
|
|
resolving against the base URI, contains no URI that the
|
|
implementation recognizes as a collation URI.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>The reason the attribute allows a list of collation URIs is that
|
|
collation URIs will often be meaningful only to one particular XSLT
|
|
implementation. Stylesheets designed to run with several different
|
|
implementations can therefore specify several different collation
|
|
URIs, one for use with each. To avoid the above error condition, it
|
|
is possible to specify the Unicode Codepoint Collation as the last
|
|
collation URI in the list.</p>
|
|
</div>
|
|
<p>The <code>[xsl:]default-collation</code> attribute does not
|
|
affect the collation used by <code>xsl:sort</code>.</p>
|
|
</div>
|
|
<div class="div3">
|
|
<h4><a name="default-mode" id="default-mode"></a>3.6.2 <a href=
|
|
"#default-mode" style="text-decoration: none">The</a>
|
|
<code>default-mode</code> <a href="#default-mode" style=
|
|
"text-decoration: none">attribute</a></h4>
|
|
<p>The <code>default-mode</code> attribute defines the default
|
|
value for the <a title="mode" class="termref" href=
|
|
"#dt-mode">mode</a> attribute of all <a href=
|
|
"#element-template"><code>xsl:template</code></a> and <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>
|
|
elements within the stylesheet module. It also determines which
|
|
mode is referred to when the token <code>#default</code> is used in
|
|
either of these attributes.</p>
|
|
<p>The value <span class="verb">must</span> either be a <a title=
|
|
"lexical QName" class="termref" href="#dt-lexical-qname">lexical
|
|
QName</a>, or the token <code>#unnamed</code> which refers to the
|
|
<a title="unnamed mode" class="termref" href=
|
|
"#dt-unnamed-mode">unnamed mode</a>. It is not necessary for the
|
|
referenced mode to be explicitly declared in an <a href=
|
|
"#element-mode"><code>xsl:mode</code></a> declaration.</p>
|
|
<p>If the <code>default-mode</code> attribute is omitted, then the
|
|
default mode for the stylesheet module is the <a title=
|
|
"unnamed mode" class="termref" href="#dt-unnamed-mode">unnamed
|
|
mode</a>. This is equivalent to specifying
|
|
<code>#unnamed</code>.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>This attribute is provided to support an approach to stylesheet
|
|
modularity in which all the template rules for one <a title="mode"
|
|
class="termref" href="#dt-mode">mode</a> are collected together
|
|
into a single <a title="stylesheet module" class="termref" href=
|
|
"#dt-stylesheet-module">stylesheet module</a>. Using this attribute
|
|
reduces the risk of forgetting to specify the mode in one or more
|
|
places where it is needed, and it also makes it easier to reuse an
|
|
existing stylesheet module that does not use modes in an
|
|
application where modes are needed to avoid conflicts with existing
|
|
template rules.</p>
|
|
</div>
|
|
<blockquote>
|
|
<p><b><a name="issue-chameleon-modes" id=
|
|
"issue-chameleon-modes">Issue 2 (chameleon-modes)</a>:</b></p>
|
|
<p>Would it be useful to be able to specify the default mode for an
|
|
included module on the <a href=
|
|
"#element-include"><code>xsl:include</code></a> element, in the
|
|
style of chameleon includes in XSD? The WG has discussed such a
|
|
feature; it is recognized that it would be useful, but it is not
|
|
clear whether it would be useful enough to justify the extra
|
|
complexity.</p>
|
|
</blockquote>
|
|
</div>
|
|
<div class="div3">
|
|
<h4><a name="user-defined-top-level" id=
|
|
"user-defined-top-level"></a>3.6.3 <a href=
|
|
"#user-defined-top-level" style=
|
|
"text-decoration: none">User-defined Data Elements</a></h4>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-data-element" id="dt-data-element" title=
|
|
"user-defined data element"></a>In addition to <a title=
|
|
"declaration" class="termref" href=
|
|
"#dt-declaration">declarations</a>, the <a href=
|
|
"#element-stylesheet"><code>xsl:stylesheet</code></a> element may
|
|
contain among its children any element not from the <a title=
|
|
"XSLT namespace" class="termref" href="#dt-xslt-namespace">XSLT
|
|
namespace</a>, provided that the <a title="expanded-QName" class=
|
|
"termref" href="#dt-expanded-qname">expanded-QName</a> of the
|
|
element has a non-null namespace URI. Such elements are referred to
|
|
as <b>user-defined data elements</b>.<span class=
|
|
"definition">]</span></p>
|
|
<p><a name="err-XTSE0130" id="err-XTSE0130"><span class=
|
|
"error">[ERR XTSE0130]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> if the
|
|
<a href="#element-stylesheet"><code>xsl:stylesheet</code></a>
|
|
element has a child element whose name has a null namespace
|
|
URI.</p>
|
|
<p>An implementation <span class="verb">may</span> attach an
|
|
<a title="implementation-defined" class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a> meaning to
|
|
user-defined data elements that appear in particular namespaces.
|
|
The set of namespaces that are recognized for such data elements is
|
|
<a title="implementation-defined" class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a>. The
|
|
presence of a user-defined data element <span class="verb">must
|
|
not</span> change the behavior of <a title="XSLT element" class=
|
|
"termref" href="#dt-xslt-element">XSLT elements</a> and functions
|
|
defined in this document; for example, it is not permitted for a
|
|
user-defined data element to specify that <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>
|
|
should use different rules to resolve conflicts. The constraints on
|
|
what user-defined data elements can and cannot do are exactly the
|
|
same as the constraints on <a title="extension attribute" class=
|
|
"termref" href="#dt-extension-attribute">extension attributes</a>,
|
|
described in <a href="#extension-attributes"><i>3.3 Extension
|
|
Attributes</i></a>. Thus, an implementation is always free to
|
|
ignore user-defined data elements, and <span class=
|
|
"verb">must</span> ignore such data elements without giving an
|
|
error if it does not recognize the namespace URI.</p>
|
|
<p>User-defined data elements can provide, for example,</p>
|
|
<ul>
|
|
<li>
|
|
<p>information used by <a title="extension instruction" class=
|
|
"termref" href="#dt-extension-instruction">extension
|
|
instructions</a> or <a title="extension function" class="termref"
|
|
href="#dt-extension-function">extension functions</a> (see <a href=
|
|
"#extension"><i>21 Extensibility and Fallback</i></a>),</p>
|
|
</li>
|
|
<li>
|
|
<p>information about what to do with any <a title=
|
|
"final result tree" class="termref" href=
|
|
"#dt-final-result-tree">final result tree</a>,</p>
|
|
</li>
|
|
<li>
|
|
<p>information about how to construct <a title="source tree" class=
|
|
"termref" href="#dt-source-tree">source trees</a>,</p>
|
|
</li>
|
|
<li>
|
|
<p>optimization hints for the <a title="processor" class="termref"
|
|
href="#dt-processor">processor</a>,</p>
|
|
</li>
|
|
<li>
|
|
<p>metadata about the stylesheet,</p>
|
|
</li>
|
|
<li>
|
|
<p>structured documentation for the stylesheet.</p>
|
|
</li>
|
|
</ul>
|
|
<p>A <a title="user-defined data element" class="termref" href=
|
|
"#dt-data-element">user-defined data element</a> <span class=
|
|
"verb">must not</span> precede an <a href=
|
|
"#element-import"><code>xsl:import</code></a> element within a
|
|
<a title="stylesheet module" class="termref" href=
|
|
"#dt-stylesheet-module">stylesheet module</a> <span class=
|
|
"error">[see <a href="#err-XTSE0200">ERR XTSE0200</a>]</span></p>
|
|
</div>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="simplified-stylesheet" id=
|
|
"simplified-stylesheet"></a>3.7 <a href="#simplified-stylesheet"
|
|
style="text-decoration: none">Simplified Stylesheet
|
|
Modules</a></h3>
|
|
<p>A simplified syntax is allowed for a <a title=
|
|
"stylesheet module" class="termref" href=
|
|
"#dt-stylesheet-module">stylesheet module</a> that defines only a
|
|
single template rule for the document node. The stylesheet module
|
|
may consist of just a <a title="literal result element" class=
|
|
"termref" href="#dt-literal-result-element">literal result
|
|
element</a> (see <a href="#literal-result-element"><i>11.1 Literal
|
|
Result Elements</i></a>) together with its contents. The literal
|
|
result element must have an <code>xsl:version</code> attribute (and
|
|
it must therefore also declare the XSLT namespace). Such a
|
|
stylesheet module is equivalent to a standard stylesheet module
|
|
whose <a href="#element-stylesheet"><code>xsl:stylesheet</code></a>
|
|
element contains a <a title="template rule" class="termref" href=
|
|
"#dt-template-rule">template rule</a> containing the literal result
|
|
element, minus its <code>xsl:version</code> attribute; the template
|
|
rule has a match <a title="pattern" class="termref" href=
|
|
"#dt-pattern">pattern</a> of <code>/</code>.</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e4302" id=
|
|
"d7e4302"></a>Example: A Simplified Stylesheet</div>
|
|
<p>For example:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<html xsl:version="2.1"
|
|
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>
|
|
</pre></div>
|
|
<p>has the same meaning as</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:stylesheet version="2.1"
|
|
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>
|
|
</pre></div>
|
|
<p>Note that it is not possible, using a simplified stylesheet, to
|
|
request that the serialized output contains a <code>DOCTYPE</code>
|
|
declaration. This can only be done by using a standard stylesheet
|
|
module, and using the <a href=
|
|
"#element-output"><code>xsl:output</code></a> element.</p>
|
|
</div>
|
|
<p>More formally, a simplified stylesheet module is equivalent to
|
|
the standard stylesheet module that would be generated by applying
|
|
the following transformation to the simplified stylesheet module,
|
|
invoking the transformation by calling the <a title=
|
|
"named template" class="termref" href="#dt-named-template">named
|
|
template</a> <code>expand</code>, with the containing literal
|
|
result element as the <a title="context node" class="termref" href=
|
|
"#dt-context-node">context node</a>:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:stylesheet version="2.1"
|
|
xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
|
|
|
|
<xsl:template name="expand">
|
|
<xsl:element name="xsl:stylesheet">
|
|
<xsl:attribute name="version" select="@xsl:version"/>
|
|
<xsl:element name="xsl:template">
|
|
<xsl:attribute name="match" select="'/'"/>
|
|
<xsl:copy-of select="."/>
|
|
</xsl:element>
|
|
</xsl:element>
|
|
</xsl:template>
|
|
|
|
</xsl:stylesheet>
|
|
</pre></div>
|
|
<p><a name="err-XTSE0150" id="err-XTSE0150"><span class=
|
|
"error">[ERR XTSE0150]</span></a> A <a title=
|
|
"literal result element" class="termref" href=
|
|
"#dt-literal-result-element">literal result element</a> that is
|
|
used as the outermost element of a simplified stylesheet module
|
|
<span class="verb">must</span> have an <code>xsl:version</code>
|
|
attribute. This indicates the version of XSLT that the stylesheet
|
|
requires. For this version of XSLT, the value will normally be
|
|
<code><span>2.1</span></code> ; the value <span class=
|
|
"verb">must</span> be a valid instance of the type
|
|
<code>xs:decimal</code> as defined in <a href="#xmlschema-2">[XML
|
|
Schema Part 2]</a>.</p>
|
|
<p>The allowed content of a literal result element when used as a
|
|
simplified stylesheet is the same as when it occurs within a
|
|
<a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a>. Thus, a
|
|
literal result element used as the document element of a simplified
|
|
stylesheet cannot contain <a title="declaration" class="termref"
|
|
href="#dt-declaration">declarations</a>. Simplified stylesheets
|
|
therefore cannot use <a title="template rule" class="termref" href=
|
|
"#dt-template-rule">template rules</a>, <a title="global variable"
|
|
class="termref" href="#dt-global-variable">global variables</a>,
|
|
<a title="stylesheet parameter" class="termref" href=
|
|
"#dt-stylesheet-parameter">stylesheet parameters</a>, <a title=
|
|
"stylesheet function" class="termref" href=
|
|
"#dt-stylesheet-function">stylesheet functions</a>, <a title="key"
|
|
class="termref" href="#dt-key">keys</a>, <a title="attribute set"
|
|
class="termref" href="#dt-attribute-set">attribute-sets</a>, or
|
|
<a title="output definition" class="termref" href=
|
|
"#dt-output-definition">output definitions</a>. In turn this means
|
|
that the only useful way to initiate the transformation is to
|
|
supply a document node as the <span><a title="initial context item"
|
|
class="termref" href="#dt-initial-context-item">initial context
|
|
item</a></span>, to be matched by the implicit
|
|
<code>match="/"</code> template rule using the <a title=
|
|
"unnamed mode" class="termref" href="#dt-unnamed-mode">unnamed
|
|
mode</a>.</p>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="backwards" id="backwards"></a>3.8 <a href="#backwards"
|
|
style="text-decoration: none">Backwards Compatible
|
|
Processing</a></h3>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-effective-version" id="dt-effective-version" title=
|
|
"effective version"></a>The <b>effective version</b> of an element
|
|
in the stylesheet is the decimal value of the
|
|
<code>[xsl:]version</code> attribute (see <a href=
|
|
"#standard-attributes"><i>3.5 Standard Attributes</i></a>) on that
|
|
element or on the innermost ancestor element that has such an
|
|
attribute, excluding the <code>version</code> attribute on an
|
|
<a href="#element-output"><code>xsl:output</code></a>
|
|
element.<span class="definition">]</span></p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-backwards-compatible-behavior" id=
|
|
"dt-backwards-compatible-behavior" title=
|
|
"backwards compatible behavior"></a>An element is processed with
|
|
<b>backwards compatible behavior</b> if its <a title=
|
|
"effective version" class="termref" href=
|
|
"#dt-effective-version">effective version</a> is less than
|
|
<code>2.1</code>.<span class="definition">]</span></p>
|
|
<p>Specifically:</p>
|
|
<ul>
|
|
<li>
|
|
<p>If the <a title="effective version" class="termref" href=
|
|
"#dt-effective-version">effective version</a> is equal to 1.0, then
|
|
the element is processed with XSLT 1.0 behavior as described in
|
|
<a href="#backwards-1.0"><i>3.8.1 XSLT 1.0 compatibility
|
|
mode</i></a>.</p>
|
|
</li>
|
|
<li>
|
|
<p>If the <a title="effective version" class="termref" href=
|
|
"#dt-effective-version">effective version</a> is equal to 2.0, then
|
|
the element is processed with XSLT 2.0 behavior as described in
|
|
<a href="#backwards-2.0"><i>3.8.2 XSLT 2.0 compatibility
|
|
mode</i></a>.</p>
|
|
</li>
|
|
<li>
|
|
<p>If the <a title="effective version" class="termref" href=
|
|
"#dt-effective-version">effective version</a> is any other value
|
|
less than 2.1, the <span class="verb">recommended</span> action is
|
|
to report a static error; however, processors <span class=
|
|
"verb">may</span> recognize such values and process the element in
|
|
an <a title="implementation-defined" class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a> way.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>XSLT 1.0 allowed the <code>version</code> attribute to take any
|
|
decimal value, and invoked forwards compatible processing for any
|
|
value other than 1.0. XSLT 2.0 allowed the attribute to take any
|
|
decimal value, and invoked backwards compatible (i.e.
|
|
1.0-compatible) processing for any value less than 2.0. Some
|
|
stylesheets may therefore be encountered that use values other than
|
|
1.0 or 2.0. In particular, the value 1.1 is sometimes encountered,
|
|
as it was used at one stage in a draft language proposal.</p>
|
|
</div>
|
|
</li>
|
|
</ul>
|
|
<p>These rules do not apply to the <a href=
|
|
"#element-output"><code>xsl:output</code></a> element, whose
|
|
<code>version</code> attribute has an entirely different purpose:
|
|
it is used to define the version of the output method to be used
|
|
for serialization.</p>
|
|
<p>It is <a title="implementation-defined" class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a> whether a
|
|
particular XSLT 2.1 implementation supports backwards compatible
|
|
behavior for any XSLT version earlier than XSLT 2.1.</p>
|
|
<p><a name="err-XTDE0160" id="err-XTDE0160"><span class=
|
|
"error">[ERR XTDE0160]</span></a> It is a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> if an
|
|
element has an <a title="effective version" class="termref" href=
|
|
"#dt-effective-version">effective version</a> of <var>V</var> (with
|
|
<var>V</var> < 2.1) when the implementation does not support
|
|
backwards compatible behavior for XSLT version <var>V</var>.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>By making use of backwards compatible behavior, it is possible
|
|
to write the stylesheet in a way that ensures that its results when
|
|
processed with an XSLT 2.1 processor are identical to the effects
|
|
of processing the same stylesheet using <span>a processor for an
|
|
earlier version of XSLT</span>. To assist with transition, some
|
|
parts of a stylesheet may be processed with backwards compatible
|
|
behavior enabled, and other parts with this behavior disabled.</p>
|
|
<p>All data values manipulated by an <span>XSLT 2.1</span>
|
|
processor are defined by the XDM data model, whether or not the
|
|
relevant expressions use backwards compatible behavior. Because the
|
|
same data model is used in both cases, expressions are fully
|
|
composable. The result of evaluating instructions or expressions
|
|
with backwards compatible behavior is fully defined in the
|
|
<span>XSLT 2.1</span> and <span>XPath 2.1</span> specifications, it
|
|
is not defined by reference to <span>earlier versions of the XSLT
|
|
and XPath specifications</span>.</p>
|
|
<p>To write a stylesheet that makes use of <span>features that are
|
|
new in version <var>N</var>, while also working with a processor
|
|
that only supports XSLT version <var>M</var> (<var>M</var> <
|
|
<var>N</var>)</span>, it is necessary to understand both the rules
|
|
for backwards compatible behavior in <span>XSLT version
|
|
<var>N</var></span>, and the rules for forwards compatible behavior
|
|
in <span>XSLT version <var>M</var></span>. If the <a href=
|
|
"#element-stylesheet"><code>xsl:stylesheet</code></a> element
|
|
specifies <code>version="2.0"</code> <span>or
|
|
<code>version="2.1"</code></span>, then an XSLT 1.0 processor will
|
|
ignore XSLT 2.0 <span>and XSLT 2.1</span><a title="declaration"
|
|
class="termref" href="#dt-declaration">declarations</a> that were
|
|
not defined in XSLT 1.0, for example <a href=
|
|
"#element-function"><code>xsl:function</code></a> and <a href=
|
|
"#element-import-schema"><code>xsl:import-schema</code></a>. If any
|
|
new <span>XSLT 2.1</span> instructions are used (for example
|
|
<a href="#element-evaluate"><code>xsl:evaluate</code></a> or
|
|
<a href="#element-stream"><code>xsl:stream</code></a>), or if new
|
|
<span>XPath 2.1</span> features are used (for example, new
|
|
functions, or <span>let</span> expressions), then the stylesheet
|
|
must provide fallback behavior that relies only on facilities
|
|
<span>available in the earliest XSLT version supported</span>. The
|
|
fallback behavior can be invoked by using the <a href=
|
|
"#element-fallback"><code>xsl:fallback</code></a> instruction, or
|
|
by testing the results of the <a href=
|
|
"#function-function-available"><code>function-available</code></a>
|
|
or <a href=
|
|
"#function-element-available"><code>element-available</code></a>
|
|
functions, or by testing the value of the <code>xsl:version</code>
|
|
property returned by the <a href=
|
|
"#function-system-property"><code>system-property</code></a>
|
|
function.</p>
|
|
</div>
|
|
<div class="div3">
|
|
<h4><a name="backwards-1.0" id="backwards-1.0"></a>3.8.1 <a href=
|
|
"#backwards-1.0" style="text-decoration: none">XSLT 1.0
|
|
compatibility mode</a></h4>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-xslt-10-behavior" id="dt-xslt-10-behavior" title=
|
|
"XSLT 1.0 behavior"></a>An element in the stylesheet is processed
|
|
with <b>XSLT 1.0 behavior</b> if its <a title="effective version"
|
|
class="termref" href="#dt-effective-version">effective version</a>
|
|
is equal to 1.0.<span class="definition">]</span></p>
|
|
<p>In this mode, if any attribute contains an XPath <a title=
|
|
"expression" class="termref" href="#dt-expression">expression</a>,
|
|
then the expression is evaluated with <a title=
|
|
"XPath 1.0 compatibility mode" class="termref" href=
|
|
"#dt-xpath-compat-mode">XPath 1.0 compatibility mode</a> set to
|
|
<code>true</code>. For details of this mode, see <a href=
|
|
"http://www.w3.org/TR/xpath-21/#static_context">Section 2.1.1
|
|
Static Context</a><sup><small>XP21</small></sup>.</p>
|
|
<p>Furthermore, in such an expression any function call for which
|
|
no implementation is available (unless it uses the <a title=
|
|
"standard function namespace" class="termref" href=
|
|
"#dt-standard-function-namespace">standard function namespace</a>)
|
|
is bound to a fallback error function whose effect when evaluated
|
|
is to raise a dynamic error <span class="error">[see <a href=
|
|
"#err-XTDE1425">ERR XTDE1425</a>]</span> . The effect is that with
|
|
backwards compatible behavior enabled, calls on <a title=
|
|
"extension function" class="termref" href=
|
|
"#dt-extension-function">extension functions</a> that are not
|
|
available in a particular implementation do not cause an error
|
|
unless the function call is actually evaluated. For further
|
|
details, see <a href="#extension-functions"><i>21.1 Extension
|
|
Functions</i></a>.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>This might appear to contradict the specification of XPath
|
|
<span>2.1</span>, which states that a static error [XPST0017] is
|
|
raised when an expression contains a call to a function that is not
|
|
present (with matching name and arity) in the static context. This
|
|
apparent contradiction is resolved by specifying that the XSLT
|
|
processor constructs a static context for the expression in which
|
|
every possible function name and arity (other than names in the
|
|
<a title="standard function namespace" class="termref" href=
|
|
"#dt-standard-function-namespace">standard function namespace</a>)
|
|
is present; when no other implementation of the function is
|
|
available, the function call is bound to a fallback error function
|
|
whose run-time effect is to raise a dynamic error.</p>
|
|
</div>
|
|
<p>Certain XSLT constructs also produce different results when XSLT
|
|
1.0 compatibility mode is enabled. This is described separately for
|
|
each such construct.</p>
|
|
</div>
|
|
<div class="div3">
|
|
<h4><a name="backwards-2.0" id="backwards-2.0"></a>3.8.2 <a href=
|
|
"#backwards-2.0" style="text-decoration: none">XSLT 2.0
|
|
compatibility mode</a></h4>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-xslt-20-behavior" id="dt-xslt-20-behavior" title=
|
|
"XSLT 2.0 behavior"></a>An element is processed with <b>XSLT 2.0
|
|
behavior</b> if its <a title="effective version" class="termref"
|
|
href="#dt-effective-version">effective version</a> is equal to
|
|
2.0.<span class="definition">]</span></p>
|
|
<p>In this working draft, no differences are defined for XSLT 2.0
|
|
behavior. An XSLT 2.1 processor will therefore produce the same
|
|
results whether the <a title="effective version" class="termref"
|
|
href="#dt-effective-version">effective version</a> of an element is
|
|
set to 2.0 or 2.1.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>An XSLT 2.0 processor, by contrast, will in some cases produce
|
|
different results in the two cases. For example, if the stylesheet
|
|
contains an <a href="#element-iterate"><code>xsl:iterate</code></a>
|
|
instruction with an <a href=
|
|
"#element-fallback"><code>xsl:fallback</code></a> child, an XSLT
|
|
2.1 processor will process the <a href=
|
|
"#element-iterate"><code>xsl:iterate</code></a> instruction
|
|
regardless whether the effective version is 2.0 or 2.1, while an
|
|
XSLT 2.0 processor will report a static error if the effective
|
|
version is 2.0, and will take the fallback action if the effective
|
|
version is 2.1.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="forwards" id="forwards"></a>3.9 <a href="#forwards"
|
|
style="text-decoration: none">Forwards Compatible
|
|
Processing</a></h3>
|
|
<p>The intent of forwards compatible behavior is to make it
|
|
possible to write a stylesheet that takes advantage of features
|
|
introduced in some version of XSLT subsequent to <span>XSLT
|
|
2.1</span>, while retaining the ability to execute the stylesheet
|
|
with an <span>XSLT 2.1</span> processor using appropriate fallback
|
|
behavior.</p>
|
|
<p>It is always possible to write conditional code to run under
|
|
different XSLT versions by using the <code>use-when</code> feature
|
|
described in <a href="#conditional-inclusion"><i>3.12 Conditional
|
|
Element Inclusion</i></a>. The rules for forwards compatible
|
|
behavior supplement this mechanism in two ways:</p>
|
|
<ul>
|
|
<li>
|
|
<p>certain constructs in the stylesheet that mean nothing to an
|
|
<span>XSLT 2.1</span> processor are ignored, rather than being
|
|
treated as errors.</p>
|
|
</li>
|
|
<li>
|
|
<p>explicit fallback behavior can be defined for instructions
|
|
defined in a future XSLT release, using the <a href=
|
|
"#element-fallback"><code>xsl:fallback</code></a> instruction.</p>
|
|
</li>
|
|
</ul>
|
|
<p>The detailed rules follow.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-forwards-compatible-behavior" id=
|
|
"dt-forwards-compatible-behavior" title=
|
|
"forwards compatible behavior"></a>An element is processed with
|
|
<b>forwards compatible behavior</b> if its <a title=
|
|
"effective version" class="termref" href=
|
|
"#dt-effective-version">effective version</a> is greater than
|
|
<code>2.1</code>.<span class="definition">]</span></p>
|
|
<p>These rules do not apply to the <code>version</code> attribute
|
|
of the <a href="#element-output"><code>xsl:output</code></a>
|
|
element, which has an entirely different purpose: it is used to
|
|
define the version of the output method to be used for
|
|
serialization.</p>
|
|
<p>When an element is processed with forwards compatible
|
|
behavior:</p>
|
|
<ul>
|
|
<li>
|
|
<p>if the element is in the XSLT namespace and appears as a child
|
|
of the <a href=
|
|
"#element-stylesheet"><code>xsl:stylesheet</code></a> element, and
|
|
XSLT <span>2.1</span> does not allow the element to appear as a
|
|
child of the <a href=
|
|
"#element-stylesheet"><code>xsl:stylesheet</code></a> element, then
|
|
the element and its content <span class="verb">must</span> be
|
|
ignored.</p>
|
|
</li>
|
|
<li>
|
|
<p>if the element has an attribute that XSLT <span>2.1</span> does
|
|
not allow the element to have, then the attribute <span class=
|
|
"verb">must</span> be ignored.</p>
|
|
</li>
|
|
<li>
|
|
<p>if the element is in the XSLT namespace and appears as part of a
|
|
<a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a>, and XSLT
|
|
<span>2.1</span> does not allow such elements to appear as part of
|
|
a sequence constructor, then:</p>
|
|
<ol class="enumar">
|
|
<li>
|
|
<p>If the element has one or more <a href=
|
|
"#element-fallback"><code>xsl:fallback</code></a> children, then no
|
|
error is reported either statically or dynamically, and the result
|
|
of evaluating the instruction is the concatenation of the sequences
|
|
formed by evaluating the sequence constructors within its <a href=
|
|
"#element-fallback"><code>xsl:fallback</code></a> children, in
|
|
document order. Siblings of the <a href=
|
|
"#element-fallback"><code>xsl:fallback</code></a> elements are
|
|
ignored, even if they are valid XSLT <span>2.1</span>
|
|
instructions.</p>
|
|
</li>
|
|
<li>
|
|
<p>If the element has no <a href=
|
|
"#element-fallback"><code>xsl:fallback</code></a> children, then a
|
|
static error is reported in the same way as if forwards compatible
|
|
behavior were not enabled.</p>
|
|
</li>
|
|
</ol>
|
|
</li>
|
|
</ul>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e4872" id=
|
|
"d7e4872"></a>Example: Forwards Compatible Behavior</div>
|
|
<p>For example, an XSLT <span>2.1</span> <a title="processor"
|
|
class="termref" href="#dt-processor">processor</a> will process the
|
|
following stylesheet without error, although the stylesheet
|
|
includes elements from the <a title="XSLT namespace" class=
|
|
"termref" href="#dt-xslt-namespace">XSLT namespace</a> that are not
|
|
defined in this specification:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:stylesheet version="17.0"
|
|
xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
|
|
<xsl:template match="/">
|
|
<xsl:exciting-new-17.0-feature>
|
|
<xsl:fly-to-the-moon/>
|
|
<xsl:fallback>
|
|
<html>
|
|
<head>
|
|
<title>XSLT 17.0 required</title>
|
|
</head>
|
|
<body>
|
|
<p>Sorry, this stylesheet requires XSLT 17.0.</p>
|
|
</body>
|
|
</html>
|
|
</xsl:fallback>
|
|
</xsl:exciting-new-17.0-feature>
|
|
</xsl:template>
|
|
</xsl:stylesheet>
|
|
</pre></div>
|
|
</div>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>If a stylesheet depends crucially on a <a title="declaration"
|
|
class="termref" href="#dt-declaration">declaration</a> introduced
|
|
by a version of XSLT after <span>2.1</span>, then the stylesheet
|
|
can use an <a href="#element-message"><code>xsl:message</code></a>
|
|
element with <code>terminate="yes"</code> (see <a href=
|
|
"#message"><i>20 Messages</i></a>) to ensure that implementations
|
|
that conform to an earlier version of XSLT will not silently ignore
|
|
the <a title="declaration" class="termref" href=
|
|
"#dt-declaration">declaration</a>.</p>
|
|
</div>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e4910" id=
|
|
"d7e4910"></a>Example: Testing the XSLT Version</div>
|
|
<p>For example,</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:stylesheet version="18.0"
|
|
xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
|
|
|
|
<xsl:important-new-17.0-declaration/>
|
|
|
|
<xsl:template match="/">
|
|
<xsl:choose>
|
|
<xsl:when test="number(system-property('xsl:version')) lt 17.0">
|
|
<xsl:message terminate="yes">
|
|
<xsl:text>Sorry, this stylesheet requires XSLT 17.0.</xsl:text>
|
|
</xsl:message>
|
|
</xsl:when>
|
|
<xsl:otherwise>
|
|
...
|
|
</xsl:otherwise>
|
|
</xsl:choose>
|
|
</xsl:template>
|
|
...
|
|
</xsl:stylesheet>
|
|
</pre></div>
|
|
</div>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="combining-modules" id="combining-modules"></a>3.10
|
|
<a href="#combining-modules" style=
|
|
"text-decoration: none">Combining Stylesheet Modules</a></h3>
|
|
<p>XSLT provides two mechanisms to construct a <a title=
|
|
"stylesheet" class="termref" href="#dt-stylesheet">stylesheet</a>
|
|
from multiple <a title="stylesheet module" class="termref" href=
|
|
"#dt-stylesheet-module">stylesheet modules</a>:</p>
|
|
<ul>
|
|
<li>
|
|
<p>an inclusion mechanism that allows stylesheet modules to be
|
|
combined without changing the semantics of the modules being
|
|
combined, and</p>
|
|
</li>
|
|
<li>
|
|
<p>an import mechanism that allows stylesheet modules to override
|
|
each other.</p>
|
|
</li>
|
|
</ul>
|
|
<div class="div3">
|
|
<h4><a name="locating-modules" id="locating-modules"></a>3.10.1
|
|
<a href="#locating-modules" style="text-decoration: none">Locating
|
|
Stylesheet Modules</a></h4>
|
|
<p>The include and import mechanisms use two declarations, <a href=
|
|
"#element-include"><code>xsl:include</code></a> and <a href=
|
|
"#element-import"><code>xsl:import</code></a>, which are defined in
|
|
the sections that follow.</p>
|
|
<p>These declarations use an <code>href</code> attribute, whose
|
|
value is a <a title="URI Reference" class="termref" href=
|
|
"#dt-uri-reference">URI reference</a>, to identify the <a title=
|
|
"stylesheet module" class="termref" href=
|
|
"#dt-stylesheet-module">stylesheet module</a> to be included or
|
|
imported. If the value of this attribute is a relative URI
|
|
<span>reference</span>, it is resolved as described in <a href=
|
|
"#uri-references"><i>5.8 URI References</i></a>.</p>
|
|
<p>After resolving against the base URI, the way in which the URI
|
|
reference is used to locate a representation of a <a title=
|
|
"stylesheet module" class="termref" href=
|
|
"#dt-stylesheet-module">stylesheet module</a>, and the way in which
|
|
the stylesheet module is constructed from that representation, are
|
|
<a title="implementation-defined" class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a>. In
|
|
particular, it is implementation-defined which URI schemes are
|
|
supported, whether fragment identifiers are supported, and what
|
|
media types are supported. Conventionally, the URI is a reference
|
|
to a resource containing the stylesheet module as a source XML
|
|
document, or it may include a fragment identifier that selects an
|
|
embedded stylesheet module within a source XML document; but the
|
|
implementation is free to use other mechanisms to locate the
|
|
stylesheet module identified by the URI reference.</p>
|
|
<p>The referenced <a title="stylesheet module" class="termref"
|
|
href="#dt-stylesheet-module">stylesheet module</a> may be any of
|
|
the four kinds of stylesheet module: that is, it may be <a title=
|
|
"standalone stylesheet module" class="termref" href=
|
|
"#dt-standalone-stylesheet-module">standalone</a> or <a title=
|
|
"embedded stylesheet module" class="termref" href=
|
|
"#dt-embedded-stylesheet-module">embedded</a>, and it may be
|
|
<a title="standard stylesheet module" class="termref" href=
|
|
"#dt-standard-stylesheet-module">standard</a> or <a title=
|
|
"simplified stylesheet module" class="termref" href=
|
|
"#dt-simplified-stylesheet-module">simplified</a>. If it is a
|
|
<a title="simplified stylesheet module" class="termref" href=
|
|
"#dt-simplified-stylesheet-module">simplified stylesheet module</a>
|
|
then it is transformed into the equivalent <a title=
|
|
"standard stylesheet module" class="termref" href=
|
|
"#dt-standard-stylesheet-module">standard stylesheet module</a> by
|
|
applying the transformation described in <a href=
|
|
"#simplified-stylesheet"><i>3.7 Simplified Stylesheet
|
|
Modules</i></a>.</p>
|
|
<p>Implementations <span class="verb">may</span> choose to accept
|
|
URI references containing a fragment identifier defined by
|
|
reference to the XPointer specification (see <a href=
|
|
"#xptr-framework">[XPointer Framework]</a>). Note that if the
|
|
implementation does not support the use of fragment identifiers in
|
|
the URI reference, then it will not be possible to include an
|
|
<a title="embedded stylesheet module" class="termref" href=
|
|
"#dt-embedded-stylesheet-module">embedded stylesheet
|
|
module</a>.</p>
|
|
<p><a name="err-XTSE0165" id="err-XTSE0165"><span class=
|
|
"error">[ERR XTSE0165]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> if the
|
|
processor is not able to retrieve the resource identified by the
|
|
URI reference, or if the resource that is retrieved does not
|
|
contain a stylesheet module conforming to this specification.</p>
|
|
</div>
|
|
<div class="div3">
|
|
<h4><a name="include" id="include"></a>3.10.2 <a href="#include"
|
|
style="text-decoration: none">Stylesheet Inclusion</a></h4>
|
|
<p class="element-syntax"><a name="element-include" id=
|
|
"element-include"></a><code><!-- Category: declaration
|
|
--><br />
|
|
<xsl:include<br />
|
|
  <b>href</b> =
|
|
<var>uri-reference</var> /></code></p>
|
|
<p>A stylesheet module may include another stylesheet module using
|
|
an <a href="#element-include"><code>xsl:include</code></a>
|
|
declaration.</p>
|
|
<p>The <a href="#element-include"><code>xsl:include</code></a>
|
|
declaration has a <span class="verb">required</span>
|
|
<code>href</code> attribute whose value is a URI reference
|
|
identifying the stylesheet module to be included. This attribute is
|
|
used as described in <a href="#locating-modules"><i>3.10.1 Locating
|
|
Stylesheet Modules</i></a>.</p>
|
|
<p><a name="err-XTSE0170" id="err-XTSE0170"><span class=
|
|
"error">[ERR XTSE0170]</span></a> An <a href=
|
|
"#element-include"><code>xsl:include</code></a> element
|
|
<span class="verb">must</span> be a <a title="top-level" class=
|
|
"termref" href="#dt-top-level">top-level</a> element.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-stylesheet-level" id="dt-stylesheet-level" title=
|
|
"stylesheet level"></a>A <b>stylesheet level</b> is a collection of
|
|
<a title="stylesheet module" class="termref" href=
|
|
"#dt-stylesheet-module">stylesheet modules</a> connected using
|
|
<a href="#element-include"><code>xsl:include</code></a>
|
|
declarations: specifically, two stylesheet modules <var>A</var> and
|
|
<var>B</var> are part of the same stylesheet level if one of them
|
|
includes the other by means of an <a href=
|
|
"#element-include"><code>xsl:include</code></a> declaration, or if
|
|
there is a third stylesheet module <var>C</var> that is in the same
|
|
stylesheet level as both <var>A</var> and <var>B</var>.<span class=
|
|
"definition">]</span></p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-declaration-order" id="dt-declaration-order" title=
|
|
"declaration order"></a>The <a title="declaration" class="termref"
|
|
href="#dt-declaration">declarations</a> within a <a title=
|
|
"stylesheet level" class="termref" href=
|
|
"#dt-stylesheet-level">stylesheet level</a> have a total ordering
|
|
known as <b>declaration order</b>. 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 <a href="#element-include"><code>xsl:include</code></a>
|
|
element that references it.<span class="definition">]</span> In
|
|
other respects, however, the effect of <a href=
|
|
"#element-include"><code>xsl:include</code></a> is not equivalent
|
|
to the effect that would be obtained by textual inclusion.</p>
|
|
<p><a name="err-XTSE0180" id="err-XTSE0180"><span class=
|
|
"error">[ERR XTSE0180]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> if a
|
|
stylesheet module directly or indirectly includes itself.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>It is not intrinsically an error for a <a title="stylesheet"
|
|
class="termref" href="#dt-stylesheet">stylesheet</a> 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
|
|
<var>B</var> includes stylesheet <var>A</var>, stylesheet
|
|
<var>C</var> includes stylesheet <var>A</var>, and stylesheet
|
|
<var>D</var> includes both stylesheet <var>B</var> and stylesheet
|
|
<var>C</var>, then <var>A</var> will be included indirectly by
|
|
<var>D</var> twice. If all of <var>B</var>, <var>C</var> and
|
|
<var>D</var> are used as independent stylesheets, then the error
|
|
can be avoided by separating everything in <var>B</var> other than
|
|
the inclusion of <var>A</var> into a separate stylesheet
|
|
<var>B'</var> and changing <var>B</var> to contain just inclusions
|
|
of <var>B'</var> and <var>A</var>, similarly for <var>C</var>, and
|
|
then changing <var>D</var> to include <var>A</var>, <var>B'</var>,
|
|
<var>C'</var>.</p>
|
|
</div>
|
|
</div>
|
|
<div class="div3">
|
|
<h4><a name="import" id="import"></a>3.10.3 <a href="#import"
|
|
style="text-decoration: none">Stylesheet Import</a></h4>
|
|
<p class="element-syntax"><a name="element-import" id=
|
|
"element-import"></a><code><!-- Category: declaration
|
|
--><br />
|
|
<xsl:import<br />
|
|
  <b>href</b> =
|
|
<var>uri-reference</var> /></code></p>
|
|
<p>A stylesheet module may import another <a title=
|
|
"stylesheet module" class="termref" href=
|
|
"#dt-stylesheet-module">stylesheet module</a> using an <a href=
|
|
"#element-import"><code>xsl:import</code></a> <a title=
|
|
"declaration" class="termref" href=
|
|
"#dt-declaration">declaration</a>. Importing a stylesheet module is
|
|
the same as including it (see <a href="#include"><i>3.10.2
|
|
Stylesheet Inclusion</i></a>) except that <a title="template rule"
|
|
class="termref" href="#dt-template-rule">template rules</a> and
|
|
other <a title="declaration" class="termref" href=
|
|
"#dt-declaration">declarations</a> in the importing module take
|
|
precedence over template rules and declarations in the imported
|
|
module; this is described in more detail below.</p>
|
|
<p>The <a href="#element-import"><code>xsl:import</code></a>
|
|
declaration has a <span class="verb">required</span>
|
|
<code>href</code> attribute whose value is a URI reference
|
|
identifying the stylesheet module to be included. This attribute is
|
|
used as described in <a href="#locating-modules"><i>3.10.1 Locating
|
|
Stylesheet Modules</i></a>.</p>
|
|
<p><a name="err-XTSE0190" id="err-XTSE0190"><span class=
|
|
"error">[ERR XTSE0190]</span></a> An <a href=
|
|
"#element-import"><code>xsl:import</code></a> element <span class=
|
|
"verb">must</span> be a <a title="top-level" class="termref" href=
|
|
"#dt-top-level">top-level</a> element.</p>
|
|
<p><a name="err-XTSE0200" id="err-XTSE0200"><span class=
|
|
"error">[ERR XTSE0200]</span></a> The <a href=
|
|
"#element-import"><code>xsl:import</code></a> element children
|
|
<span class="verb">must</span> precede all other element children
|
|
of an <a href="#element-stylesheet"><code>xsl:stylesheet</code></a>
|
|
element, including any <a href=
|
|
"#element-include"><code>xsl:include</code></a> element children
|
|
and any <a title="user-defined data element" class="termref" href=
|
|
"#dt-data-element">user-defined data elements</a>.</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e5303" id=
|
|
"d7e5303"></a>Example: Using <code>xsl:import</code></div>
|
|
<p>For example,</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:stylesheet version="2.1"
|
|
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>
|
|
</pre></div>
|
|
</div>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-import-tree" id="dt-import-tree" title="import tree"></a>The
|
|
<a title="stylesheet level" class="termref" href=
|
|
"#dt-stylesheet-level">stylesheet levels</a> making up a <a title=
|
|
"stylesheet" class="termref" href="#dt-stylesheet">stylesheet</a>
|
|
are treated as forming an <b>import tree</b>. In the import tree,
|
|
each stylesheet level has one child for each <a href=
|
|
"#element-import"><code>xsl:import</code></a> declaration that it
|
|
contains.<span class="definition">]</span> The ordering of the
|
|
children is the <a title="declaration order" class="termref" href=
|
|
"#dt-declaration-order">declaration order</a> of the <a href=
|
|
"#element-import"><code>xsl:import</code></a> declarations within
|
|
their stylesheet level.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-import-precedence" id="dt-import-precedence" title=
|
|
"import precedence"></a>A <a title="declaration" class="termref"
|
|
href="#dt-declaration">declaration</a> <var>D</var> in the
|
|
stylesheet is defined to have lower <b>import precedence</b> than
|
|
another declaration <var>E</var> if the stylesheet level containing
|
|
<var>D</var> would be visited before the stylesheet level
|
|
containing <var>E</var> 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.<span class=
|
|
"definition">]</span></p>
|
|
<p>For example, suppose</p>
|
|
<ul>
|
|
<li>
|
|
<p>stylesheet module <var>A</var> imports stylesheet modules
|
|
<var>B</var> and <var>C</var> in that order;</p>
|
|
</li>
|
|
<li>
|
|
<p>stylesheet module <var>B</var> imports stylesheet module
|
|
<var>D</var>;</p>
|
|
</li>
|
|
<li>
|
|
<p>stylesheet module <var>C</var> imports stylesheet module
|
|
<var>E</var>.</p>
|
|
</li>
|
|
</ul>
|
|
<p>Then the import tree has the following structure:</p>
|
|
<object type="image/svg+xml" codetype="image/svg+xml" data=
|
|
"img/fig1.svg"><span style=
|
|
"background-color:#FFFF20;padding-top:1pt;padding-bottom:1pt;">This
|
|
browser can't display the SVG file img/fig1.svg. Please upgrade
|
|
your browser or install the Adobe SVG Viewer.</span></object>
|
|
<p><em>Here you should see a diagram. If it does not appear
|
|
correctly in your browser, you need to install an SVG
|
|
Plugin.</em></p>
|
|
<p>The order of import precedence (lowest first) is <var>D</var>,
|
|
<var>B</var>, <var>E</var>, <var>C</var>, <var>A</var>.</p>
|
|
<p>In general, a <a title="declaration" class="termref" href=
|
|
"#dt-declaration">declaration</a> with higher import precedence
|
|
takes precedence over a declaration with lower import precedence.
|
|
This is defined in detail for each kind of declaration.</p>
|
|
<p><a name="err-XTSE0210" id="err-XTSE0210"><span class=
|
|
"error">[ERR XTSE0210]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> if a
|
|
stylesheet module directly or indirectly imports itself.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>The case where a stylesheet module with a particular URI is
|
|
imported several times is not treated specially. The effect is
|
|
exactly the same as if several stylesheet modules with different
|
|
URIs but identical content were imported. This might or might not
|
|
cause an error, depending on the content of the stylesheet
|
|
module.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="embedded" id="embedded"></a>3.11 <a href="#embedded"
|
|
style="text-decoration: none">Embedded Stylesheet Modules</a></h3>
|
|
<p>An <a title="embedded stylesheet module" class="termref" href=
|
|
"#dt-embedded-stylesheet-module">embedded stylesheet module</a> is
|
|
a <a title="stylesheet module" class="termref" href=
|
|
"#dt-stylesheet-module">stylesheet module</a> whose containing
|
|
element is not the outermost element of the containing XML
|
|
document. Both <a title="standard stylesheet module" class=
|
|
"termref" href="#dt-standard-stylesheet-module">standard stylesheet
|
|
modules</a> and <a title="simplified stylesheet module" class=
|
|
"termref" href="#dt-simplified-stylesheet-module">simplified
|
|
stylesheet modules</a> may be embedded in this way.</p>
|
|
<p>Two situations where embedded stylesheets may be useful are:</p>
|
|
<ul>
|
|
<li>
|
|
<p>The stylesheet may be embedded in the source document to be
|
|
transformed.</p>
|
|
</li>
|
|
<li>
|
|
<p>The stylesheet may be embedded in an XML document that describes
|
|
a sequence of processing of which the XSLT transformation forms
|
|
just one part.</p>
|
|
</li>
|
|
</ul>
|
|
<p>The <a href=
|
|
"#element-stylesheet"><code>xsl:stylesheet</code></a> element
|
|
<span class="verb">may</span> have an <code>id</code> attribute to
|
|
facilitate reference to the stylesheet module within the containing
|
|
document.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>In order for such an attribute value to be used as a fragment
|
|
identifier in a URI, the XDM attribute node must generally have the
|
|
<code>is-id</code> property: see <a href=
|
|
"http://www.w3.org/TR/xpath-datamodel-11/#dm-is-id">Section 5.5
|
|
is-id Accessor</a><sup><small>DM11</small></sup>. This property
|
|
will typically be set if the attribute is defined in a DTD as being
|
|
of type <code>ID</code>, or if is defined in a schema as being of
|
|
type <code>xs:ID</code>. It is also necessary that the media type
|
|
of the containing document should support the use of ID values as
|
|
fragment identifiers. <span>Such support is widespread in existing
|
|
products, and is endorsed in respect of the media type
|
|
<code>application/xml</code> by <a href="#xptr-framework">[XPointer
|
|
Framework]</a></span>.</p>
|
|
<p>An alternative, if the implementation supports it, is to use an
|
|
<code>xml:id</code> attribute. XSLT allows this attribute (like
|
|
other namespaced attributes) to appear on any <a title=
|
|
"XSLT element" class="termref" href="#dt-xslt-element">XSLT
|
|
element</a>.</p>
|
|
</div>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e5513" id=
|
|
"d7e5513"></a>Example: The <code>xml-stylesheet</code> Processing
|
|
Instruction</div>
|
|
<p>The following example shows how the <code>xml-stylesheet</code>
|
|
processing instruction (see <a href="#xml-stylesheet">[XML
|
|
Stylesheet]</a>) can be used to allow a source document to contain
|
|
its own stylesheet. The URI reference uses a fragment identifier to
|
|
locate the <a href=
|
|
"#element-stylesheet"><code>xsl:stylesheet</code></a> element:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<?xml-stylesheet type="application/xslt+xml" href="#style1"?>
|
|
<!DOCTYPE doc SYSTEM "doc.dtd">
|
|
<doc>
|
|
<head>
|
|
<xsl:stylesheet id="style1"
|
|
version="2.1"
|
|
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>
|
|
</pre></div>
|
|
</div>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>A stylesheet module that is embedded in the document to which it
|
|
is to be applied typically needs to contain a <a title=
|
|
"template rule" class="termref" href="#dt-template-rule">template
|
|
rule</a> that specifies that <a href=
|
|
"#element-stylesheet"><code>xsl:stylesheet</code></a> elements are
|
|
to be ignored.</p>
|
|
</div>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>The above example uses the pseudo-attribute
|
|
<code>type="application/xslt+xml"</code> in the
|
|
<code>xml-stylesheet</code> processing instruction to denote an
|
|
XSLT stylesheet. This is the officially registered media type for
|
|
XSLT: see <a href="#xslt-media-type"><i>3.4 XSLT Media
|
|
Type</i></a>. However, browsers developed before this media type
|
|
was registered are more likely to accept the unofficial designation
|
|
<code>type="text/xsl"</code>.</p>
|
|
</div>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>Support for the <code>xml-stylesheet</code> processing
|
|
instruction is not required for conformance with this
|
|
Recommendation. Implementations are not constrained in the
|
|
mechanisms they use to identify a stylesheet when a transformation
|
|
is initiated: see <a href="#initiating"><i>2.3 Initiating a
|
|
Transformation</i></a>.</p>
|
|
</div>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="conditional-inclusion" id=
|
|
"conditional-inclusion"></a>3.12 <a href="#conditional-inclusion"
|
|
style="text-decoration: none">Conditional Element
|
|
Inclusion</a></h3>
|
|
<p>Any element in the XSLT namespace may have a
|
|
<code>use-when</code> attribute whose value is an XPath expression
|
|
that can be evaluated statically. If the attribute is present and
|
|
the <a href="http://www.w3.org/TR/xpath-21/#dt-ebv">effective
|
|
boolean value</a><sup><small>XP21</small></sup> of the expression
|
|
is false, then the element, together with all the nodes having that
|
|
element as an ancestor, is effectively excluded from the <a title=
|
|
"stylesheet module" class="termref" href=
|
|
"#dt-stylesheet-module">stylesheet module</a>. When a node is
|
|
effectively excluded from a stylesheet module the stylesheet module
|
|
has the same effect as if the node were not there. Among other
|
|
things this means that no static or dynamic errors will be reported
|
|
in respect of the element and its contents, other than errors in
|
|
the <code>use-when</code> attribute itself.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>This does not apply to XML parsing or validation errors, which
|
|
will be reported in the usual way. It also does not apply to
|
|
attributes that are necessarily processed before
|
|
<code>[xsl:]use-when</code>, examples being <code>xml:space</code>
|
|
and <code>[xsl:]xpath-default-namespace</code>.</p>
|
|
</div>
|
|
<p>A <a title="literal result element" class="termref" href=
|
|
"#dt-literal-result-element">literal result element</a>, or any
|
|
other element within a <a title="stylesheet module" class="termref"
|
|
href="#dt-stylesheet-module">stylesheet module</a> that is not in
|
|
the XSLT namespace, may similarly carry an
|
|
<code>xsl:use-when</code> attribute.</p>
|
|
<p>If the <a href=
|
|
"#element-stylesheet"><code>xsl:stylesheet</code></a> or <a href=
|
|
"#element-transform"><code>xsl:transform</code></a> element itself
|
|
is effectively excluded, the effect is to exclude all the children
|
|
of the <a href=
|
|
"#element-stylesheet"><code>xsl:stylesheet</code></a> or <a href=
|
|
"#element-transform"><code>xsl:transform</code></a> element, but
|
|
not the <a href=
|
|
"#element-stylesheet"><code>xsl:stylesheet</code></a> or <a href=
|
|
"#element-transform"><code>xsl:transform</code></a> element or its
|
|
attributes.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>This allows all the declarations that depend on the same
|
|
condition to be included in one stylesheet module, and for their
|
|
inclusion or exclusion to be controlled by a single
|
|
<code>use-when</code> attribute at the level of the module.</p>
|
|
</div>
|
|
<p>Conditional element exclusion happens after stripping of
|
|
whitespace text nodes from the stylesheet, as described in <a href=
|
|
"#stylesheet-stripping"><i>4.2 Stripping Whitespace from the
|
|
Stylesheet</i></a>.</p>
|
|
<p>There are no syntactic constraints on the XPath expression that
|
|
can be used as the value of the <code>use-when</code> attribute.
|
|
However, there are severe constraints on the information provided
|
|
in its evaluation context. These constraints are designed to ensure
|
|
that the expression can be evaluated at the earliest possible stage
|
|
of stylesheet processing, without any dependency on information
|
|
contained in the stylesheet itself or in any source document.</p>
|
|
<p>Specifically, the components of the static and dynamic context
|
|
are defined by the following two tables:</p>
|
|
<table border="1" cellpadding="5" width="100%">
|
|
<caption>Static Context Components for <code>use-when</code>
|
|
Expressions</caption>
|
|
<col align="left" width="30%" span="1" />
|
|
<col align="left" span="1" />
|
|
<thead>
|
|
<tr>
|
|
<th colspan="1">Component</th>
|
|
<th colspan="1">Value</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td valign="top">XPath 1.0 compatibility mode</td>
|
|
<td>false</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">In scope namespaces</td>
|
|
<td>determined by the in-scope namespaces for the containing
|
|
element in the stylesheet</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">Default element/type namespace</td>
|
|
<td>determined by the <code>xpath-default-namespace</code>
|
|
attribute if present (see <a href="#unprefixed-qnames"><i>5.2
|
|
Unprefixed QNames in Expressions and Patterns</i></a>); otherwise
|
|
the null namespace</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">Default function namespace</td>
|
|
<td>The <a title="standard function namespace" class="termref"
|
|
href="#dt-standard-function-namespace">standard function
|
|
namespace</a></td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">In scope type definitions</td>
|
|
<td>The type definitions that would be available in the absence of
|
|
any <a href=
|
|
"#element-import-schema"><code>xsl:import-schema</code></a>
|
|
declaration</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">In scope element declarations</td>
|
|
<td>None</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">In scope attribute declarations</td>
|
|
<td>None</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">In scope variables</td>
|
|
<td>None</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">In scope functions</td>
|
|
<td>The <a title="core function" class="termref" href=
|
|
"#dt-core-function">core functions</a> defined in <a href=
|
|
"#xpath-functions-11">[Functions and Operators]</a>, together with
|
|
the functions <a href=
|
|
"#function-element-available"><code>element-available</code></a>,
|
|
<a href=
|
|
"#function-function-available"><code>function-available</code></a>,
|
|
<a href="#function-type-available"><code>type-available</code></a>,
|
|
and <a href=
|
|
"#function-system-property"><code>system-property</code></a>
|
|
defined in this specification, plus the set of extension functions
|
|
that are present in the static context of every XPath expression
|
|
(other than a use-when expression) within the content of the
|
|
element that is the parent of the <code>use-when</code> attribute.
|
|
Note that <a title="stylesheet function" class="termref" href=
|
|
"#dt-stylesheet-function">stylesheet functions</a> are <em>not</em>
|
|
included in the context, which means that the function <a href=
|
|
"#function-function-available"><code>function-available</code></a>
|
|
will return <code>false</code> in respect of such functions. The
|
|
effect of this rule is to ensure that <a href=
|
|
"#function-function-available"><code>function-available</code></a>
|
|
returns true in respect of functions that can be called within the
|
|
scope of the <code>use-when</code> attribute. It also has the
|
|
effect that these extensions functions will be recognized within
|
|
the <code>use-when</code> attribute itself; however, the fact that
|
|
a function is available in this sense gives no guarantee that a
|
|
call on the function will succeed.</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">In scope collations</td>
|
|
<td>Implementation-defined</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">Default collation</td>
|
|
<td>The Unicode Codepoint Collation</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">Base URI</td>
|
|
<td>The base URI of the containing element in the stylesheet</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">Statically known documents</td>
|
|
<td>None</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">Statically known collections</td>
|
|
<td>None</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top"><span>Statically known decimal formats</span></td>
|
|
<td><span>A single unnamed <a title="decimal format" class=
|
|
"termref" href="#dt-decimal-format">decimal format</a> equivalent
|
|
to the decimal format that is created by an <a href=
|
|
"#element-decimal-format"><code>xsl:decimal-format</code></a>
|
|
declaration with no attributes.</span></td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p> </p>
|
|
<table border="1" cellpadding="5" width="100%">
|
|
<caption>Dynamic Context Components for <code>use-when</code>
|
|
Expressions</caption>
|
|
<col align="left" width="30%" span="1" />
|
|
<col align="left" span="1" />
|
|
<thead>
|
|
<tr>
|
|
<th colspan="1">Component</th>
|
|
<th colspan="1">Value</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td valign="top">Context item, position, and size</td>
|
|
<td>Undefined</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">Dynamic variables</td>
|
|
<td>None</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">Current date and time</td>
|
|
<td>Implementation-defined</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">Implicit timezone</td>
|
|
<td>Implementation-defined</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">Available documents</td>
|
|
<td>None</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">Available collections</td>
|
|
<td>None</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>Within a <a title="stylesheet module" class="termref" href=
|
|
"#dt-stylesheet-module">stylesheet module</a>, all expressions
|
|
contained in <code>[xsl:]use-when</code> attributes are evaluated
|
|
in a single <a href=
|
|
"http://www.w3.org/TR/xpath-functions/#execution-scope">execution
|
|
scope</a><sup><small>FO</small></sup>. This need not be the same
|
|
execution scope as that used for <code>[xsl]:use-when</code>
|
|
expressions in other stylesheet modules, or as that used when
|
|
evaluating XPath expressions appearing elsewhere in the stylesheet
|
|
module. This means that a function such as <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-current-date"><code>current-date</code></a><sup><small>FO</small></sup>
|
|
will return the same result when called in different
|
|
<code>[xsl:]use-when</code> expressions within the same stylesheet
|
|
module, but will not necessarily return the same result as the same
|
|
call in an <code>[xsl:]use-when</code> expression within a
|
|
different stylesheet module, or as a call on the same function
|
|
executed during the transformation proper.</p>
|
|
<p>The use of <code>[xsl:]use-when</code> is illustrated in the
|
|
following examples.</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e5873" id=
|
|
"d7e5873"></a>Example: Using Conditional Exclusion to Achieve
|
|
Portability</div>
|
|
<p>This example demonstrates the use of the <code>use-when</code>
|
|
attribute to achieve portability of a stylesheet across
|
|
schema-aware and non-schema-aware processors.</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:import-schema schema-location="http://example.com/schema"
|
|
use-when="system-property('xsl:is-schema-aware')='yes'"/>
|
|
|
|
<xsl:template match="/"
|
|
use-when="system-property('xsl:is-schema-aware')='yes'"
|
|
priority="2">
|
|
<xsl:result-document validation="strict">
|
|
<xsl:apply-templates/>
|
|
</xsl:result-document>
|
|
</xsl:template>
|
|
|
|
<xsl:template match="/">
|
|
<xsl:apply-templates/>
|
|
</xsl:template>
|
|
</pre></div>
|
|
<p>The effect of these declarations is that a non-schema-aware
|
|
processor ignores the <a href=
|
|
"#element-import-schema"><code>xsl:import-schema</code></a>
|
|
declaration and the first template rule, and therefore generates no
|
|
errors in respect of the schema-related constructs in these
|
|
declarations.</p>
|
|
</div>
|
|
<p> </p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e5888" id=
|
|
"d7e5888"></a>Example: Including Variant Stylesheet Modules</div>
|
|
<p>This example includes different stylesheet modules depending on
|
|
which XSLT processor is in use.</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:include href="module-A.xsl"
|
|
use-when="system-property('xsl:vendor')='vendor-A'"/>
|
|
<xsl:include href="module-B.xsl"
|
|
use-when="system-property('xsl:vendor')='vendor-B'"/>
|
|
</pre></div>
|
|
</div>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="built-in-types" id="built-in-types"></a>3.13 <a href=
|
|
"#built-in-types" style="text-decoration: none">Built-in
|
|
Types</a></h3>
|
|
<p>Every XSLT <span>2.1</span> processor includes the following
|
|
named type definitions in the <a title="in-scope schema component"
|
|
class="termref" href="#dt-in-scope-schema-component">in-scope
|
|
schema components</a>:</p>
|
|
<ul>
|
|
<li>
|
|
<p><span>All built-in types defined in <a href="#xmlschema-2">[XML
|
|
Schema Part 2]</a>, including <code>xs:anyType</code> and
|
|
<code>xs:anySimpleType</code>.</span></p>
|
|
</li>
|
|
<li>
|
|
<p>The following types defined in <a href="#xpath-21">[XPath
|
|
2.1]</a>: <code>xs:yearMonthDuration</code>,
|
|
<code>xs:dayTimeDuration</code>, <code>xs:anyAtomicType</code>,
|
|
<code>xs:untyped</code>, and <code>xs:untypedAtomic</code>.</p>
|
|
</li>
|
|
</ul>
|
|
<blockquote>
|
|
<p><b><a name="xsd11-additional-types" id=
|
|
"xsd11-additional-types">Issue 3 (additional-types)</a>:</b></p>
|
|
<p>It is likely that the new types from XSD 1.1 will be added to
|
|
this list when XSD 1.1 becomes a Recommendation.</p>
|
|
</blockquote>
|
|
<p>A <a title="schema-aware XSLT processor" class="termref" href=
|
|
"#dt-schema-aware-xslt-processor">schema-aware XSLT processor</a>
|
|
additionally supports:</p>
|
|
<ul>
|
|
<li>
|
|
<p>User-defined types, and element and attribute declarations, that
|
|
are imported using an <a href=
|
|
"#element-import-schema"><code>xsl:import-schema</code></a>
|
|
declaration as described in <a href="#import-schema"><i>3.14
|
|
Importing Schema Components</i></a>. These may include both simple
|
|
and complex types.</p>
|
|
</li>
|
|
</ul>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>The names that are imported from the XML Schema namespace do not
|
|
include all the names of top-level types defined in either the
|
|
Schema for Schemas or the Schema for Datatypes. The Schema for
|
|
Datatypes, as well as defining built-in types such as
|
|
<code>xs:integer</code> and <code>xs:double</code>, also defines
|
|
types that are intended for use only within the Schema for
|
|
DataTypes, such as <code>xs:derivationControl</code>. A <a title=
|
|
"stylesheet" class="termref" href="#dt-stylesheet">stylesheet</a>
|
|
that is designed to process XML Schema documents as its input or
|
|
output may import the Schema for Schemas.</p>
|
|
</div>
|
|
<p>An implementation may define mechanisms that allow additional
|
|
<a title="schema component" class="termref" href=
|
|
"#dt-schema-component">schema components</a> to be added to the
|
|
<a title="in-scope schema component" class="termref" href=
|
|
"#dt-in-scope-schema-component">in-scope schema components</a> for
|
|
the stylesheet. For example, the mechanisms used to define
|
|
<a title="extension function" class="termref" href=
|
|
"#dt-extension-function">extension functions</a> (see <a href=
|
|
"#extension-functions"><i>21.1 Extension Functions</i></a>) may
|
|
also be used to import the types used in the interface to such
|
|
functions.</p>
|
|
<p>These <a title="schema component" class="termref" href=
|
|
"#dt-schema-component">schema components</a> are the only ones that
|
|
may be referenced in XPath expressions within the stylesheet, or in
|
|
the <code>[xsl:]type</code> and <code>as</code> attributes of those
|
|
elements that permit these attributes.</p>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="import-schema" id="import-schema"></a>3.14 <a href=
|
|
"#import-schema" style="text-decoration: none">Importing Schema
|
|
Components</a></h3>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>The facilities described in this section are not available with
|
|
a <a title="basic XSLT processor" class="termref" href=
|
|
"#dt-basic-xslt-processor">basic XSLT processor</a>. They require a
|
|
<a title="schema-aware XSLT processor" class="termref" href=
|
|
"#dt-schema-aware-xslt-processor">schema-aware XSLT processor</a>,
|
|
as described in <a href="#conformance"><i>24
|
|
Conformance</i></a>.</p>
|
|
</div>
|
|
<p class="element-syntax"><a name="element-import-schema" id=
|
|
"element-import-schema"></a><code><!-- Category: declaration
|
|
--><br />
|
|
<xsl:import-schema<br />
|
|
  namespace? = <var>uri-reference</var><br />
|
|
  schema-location? =
|
|
<var>uri-reference</var> ><br />
|
|
  <!-- Content: xs:schema? --><br />
|
|
</xsl:import-schema></code></p>
|
|
<p>The <a href=
|
|
"#element-import-schema"><code>xsl:import-schema</code></a>
|
|
declaration is used to identify <a title="schema component" class=
|
|
"termref" href="#dt-schema-component">schema components</a> (that
|
|
is, top-level type definitions and top-level element and attribute
|
|
declarations) that need to be available statically, that is, before
|
|
any source document is available. Names of such components used
|
|
statically within the <a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a> must refer to an <a title=
|
|
"in-scope schema component" class="termref" href=
|
|
"#dt-in-scope-schema-component">in-scope schema component</a>,
|
|
which means they must either be built-in types as defined in
|
|
<a href="#built-in-types"><i>3.13 Built-in Types</i></a>, or they
|
|
must be imported using an <a href=
|
|
"#element-import-schema"><code>xsl:import-schema</code></a>
|
|
declaration.</p>
|
|
<p>The <a href=
|
|
"#element-import-schema"><code>xsl:import-schema</code></a>
|
|
declaration identifies a namespace containing the names of the
|
|
components to be imported (or indicates that components whose names
|
|
are in no namespace are to be imported). The effect is that the
|
|
names of top-level element and attribute declarations and type
|
|
definitions from this namespace (or non-namespace) become available
|
|
for use within XPath expressions in the <a title="stylesheet"
|
|
class="termref" href="#dt-stylesheet">stylesheet</a>, and within
|
|
other stylesheet constructs such as the <code>type</code> and
|
|
<code>as</code> attributes of various <a title="XSLT element"
|
|
class="termref" href="#dt-xslt-element">XSLT elements</a>.</p>
|
|
<p>The same schema components are available in all stylesheet
|
|
modules; importing components in one stylesheet module makes them
|
|
available throughout the <a title="stylesheet" class="termref"
|
|
href="#dt-stylesheet">stylesheet</a>.</p>
|
|
<p>The <code>namespace</code> and <code>schema-location</code>
|
|
attributes are both optional.</p>
|
|
<p>If the <a href=
|
|
"#element-import-schema"><code>xsl:import-schema</code></a> element
|
|
contains an <code>xs:schema</code> element, then the
|
|
<code>schema-location</code> attribute <span class=
|
|
"verb">must</span> be absent, and one of the following <span class=
|
|
"verb">must</span> be true:</p>
|
|
<ul>
|
|
<li>
|
|
<p>the <code>namespace</code> attribute of the <a href=
|
|
"#element-import-schema"><code>xsl:import-schema</code></a> element
|
|
and the <code>targetNamespace</code> attribute of the
|
|
<code>xs:schema</code> element are both absent (indicating a
|
|
no-namespace schema), or</p>
|
|
</li>
|
|
<li>
|
|
<p>the <code>namespace</code> attribute of the <a href=
|
|
"#element-import-schema"><code>xsl:import-schema</code></a> element
|
|
and the <code>targetNamespace</code> attribute of the
|
|
<code>xs:schema</code> element are both present and both have the
|
|
same value, or</p>
|
|
</li>
|
|
<li>
|
|
<p>the <code>namespace</code> attribute of the <a href=
|
|
"#element-import-schema"><code>xsl:import-schema</code></a> element
|
|
is absent and the <code>targetNamespace</code> attribute of the
|
|
<code>xs:schema</code> element is present, in which case the target
|
|
namespace is as given on the <code>xs:schema</code> element.</p>
|
|
</li>
|
|
</ul>
|
|
<p><a name="err-XTSE0215" id="err-XTSE0215"><span class=
|
|
"error">[ERR XTSE0215]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> if an
|
|
<a href="#element-import-schema"><code>xsl:import-schema</code></a>
|
|
element that contains an <code>xs:schema</code> element has a
|
|
<code>schema-location</code> attribute, or if it has a
|
|
<code>namespace</code> attribute that conflicts with the target
|
|
namespace of the contained schema.</p>
|
|
<p>If two <a href=
|
|
"#element-import-schema"><code>xsl:import-schema</code></a>
|
|
declarations specify the same namespace, or if both specify no
|
|
namespace, then only the one with highest <a title=
|
|
"import precedence" class="termref" href=
|
|
"#dt-import-precedence">import precedence</a> is used. If this
|
|
leaves more than one, then all the declarations at the highest
|
|
import precedence are used (which may cause conflicts, as described
|
|
below).</p>
|
|
<p>After discarding any <a href=
|
|
"#element-import-schema"><code>xsl:import-schema</code></a>
|
|
declarations under the above rule, the effect of the remaining
|
|
<a href="#element-import-schema"><code>xsl:import-schema</code></a>
|
|
declarations is defined in terms of a hypothetical document called
|
|
the synthetic schema document, which is constructed as follows. The
|
|
synthetic schema document defines an arbitrary target namespace
|
|
that is different from any namespace actually used by the
|
|
application, and it contains <code>xs:import</code> elements
|
|
corresponding one-for-one with the <a href=
|
|
"#element-import-schema"><code>xsl:import-schema</code></a>
|
|
declarations in the <a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a>, with the following
|
|
correspondence:</p>
|
|
<ul>
|
|
<li>
|
|
<p>The <code>namespace</code> attribute of the
|
|
<code>xs:import</code> element is copied from the
|
|
<code>namespace</code> attribute of the <a href=
|
|
"#element-import-schema"><code>xsl:import-schema</code></a>
|
|
declaration if it is explicitly present, or is implied by the
|
|
<code>targetNamespace</code> attribute of a contained
|
|
<code>xs:schema</code> element, and is absent if it is absent.</p>
|
|
</li>
|
|
<li>
|
|
<p>The <code>schemaLocation</code> attribute of the
|
|
<code>xs:import</code> element is copied from the
|
|
<code>schema-location</code> attribute of the <a href=
|
|
"#element-import-schema"><code>xsl:import-schema</code></a>
|
|
declaration if present, and is absent if it is absent. If there is
|
|
a contained <code>xs:schema</code> element, the effective value of
|
|
the <code>schemaLocation</code> attribute is a URI referencing a
|
|
document containing a copy of the <code>xs:schema</code>
|
|
element.</p>
|
|
</li>
|
|
<li>
|
|
<p>The base URI of the <code>xs:import</code> element is the same
|
|
as the base URI of the <a href=
|
|
"#element-import-schema"><code>xsl:import-schema</code></a>
|
|
declaration.</p>
|
|
</li>
|
|
</ul>
|
|
<p>The schema components included in the <a title=
|
|
"in-scope schema component" class="termref" href=
|
|
"#dt-in-scope-schema-component">in-scope schema components</a>
|
|
(that is, the components whose names are available for use within
|
|
the stylesheet) are the top-level element and attribute
|
|
declarations and type definitions that are available for reference
|
|
within the synthetic schema document. See <a href=
|
|
"#xmlschema-1">[XML Schema Part 1]</a> (section 4.2.3,
|
|
<em>References to schema components across namespaces</em>).</p>
|
|
<p><a name="err-XTSE0220" id="err-XTSE0220"><span class=
|
|
"error">[ERR XTSE0220]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> if the
|
|
synthetic schema document does not satisfy the constraints
|
|
described in <a href="#xmlschema-1">[XML Schema Part 1]</a>
|
|
(section 5.1, <em>Errors in Schema Construction and
|
|
Structure</em>). This includes, without loss of generality,
|
|
conflicts such as multiple definitions of the same name.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>The synthetic schema document does not need to be constructed by
|
|
a real implementation. It is purely a mechanism for defining the
|
|
semantics of <a href=
|
|
"#element-import-schema"><code>xsl:import-schema</code></a> in
|
|
terms of rules that already exist within the XML Schema
|
|
specification. In particular, it implicitly defines the rules that
|
|
determine whether the set of <a href=
|
|
"#element-import-schema"><code>xsl:import-schema</code></a>
|
|
declarations are mutually consistent.</p>
|
|
<p>These rules do not cause names to be imported transitively. The
|
|
fact that a name is available for reference within a schema
|
|
document A does not of itself make the name available for reference
|
|
in a stylesheet that imports the target namespace of schema
|
|
document A. (See <a href="#xmlschema-1">[XML Schema Part 1]</a>
|
|
section 3.15.3, Constraints on XML Representations of Schemas.) The
|
|
stylesheet must import all the namespaces containing names that it
|
|
actually references.</p>
|
|
<p>The <code>namespace</code> attribute indicates that a schema for
|
|
the given namespace is required by the <a title="stylesheet" class=
|
|
"termref" href="#dt-stylesheet">stylesheet</a>. This information
|
|
may be enough on its own to enable an implementation to locate the
|
|
required schema components. The <code>namespace</code> attribute
|
|
may be omitted to indicate that a schema for names in no namespace
|
|
is being imported. The zero-length string is not a valid namespace
|
|
URI, and is therefore not a valid value for the
|
|
<code>namespace</code> attribute.</p>
|
|
<p>The <code>schema-location</code> attribute is a <a title=
|
|
"URI Reference" class="termref" href="#dt-uri-reference">URI
|
|
Reference</a> that gives a hint indicating where a schema document
|
|
or other resource containing the required definitions may be found.
|
|
It is likely that a <a title="schema-aware XSLT processor" class=
|
|
"termref" href="#dt-schema-aware-xslt-processor">schema-aware XSLT
|
|
processor</a> will be able to process a schema document found at
|
|
this location.</p>
|
|
<p>The XML Schema specification gives implementations flexibility
|
|
in how to handle multiple imports for the same namespace. Multiple
|
|
imports do not cause errors if the definitions do not conflict.</p>
|
|
<p>A consequence of these rules is that it is not intrinsically an
|
|
error if no schema document can be located for a namespace
|
|
identified in an <a href=
|
|
"#element-import-schema"><code>xsl:import-schema</code></a>
|
|
declaration. This will cause an error only if it results in the
|
|
stylesheet containing references to names that have not been
|
|
imported.</p>
|
|
<p>An inline schema document (using an <code>xs:schema</code>
|
|
element as a child of the <code>xsl:import-schema</code> element)
|
|
has the same status as an external schema document, in the sense
|
|
that it acts as a hint for a source of schema components in the
|
|
relevant namespace. To ensure that the inline schema document is
|
|
always used, it is advisable to use a target namespace that is
|
|
unique to this schema document.</p>
|
|
</div>
|
|
<p>The use of a namespace in an <a href=
|
|
"#element-import-schema"><code>xsl:import-schema</code></a>
|
|
declaration does not by itself associate any namespace prefix with
|
|
the namespace. If names from the namespace are used within the
|
|
stylesheet module then a namespace declaration must be included in
|
|
the stylesheet module, in the usual way.</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e6431" id=
|
|
"d7e6431"></a>Example: An Inline Schema Document</div>
|
|
<p>The following example shows an inline schema document. This
|
|
declares a simple type <code>local:yes-no</code>, which the
|
|
stylesheet then uses in the declaration of a variable.</p>
|
|
<p>The example assumes the namespace declaration
|
|
<code>xmlns:local="http://example.com/ns/yes-no"</code></p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:import-schema>
|
|
<xs:schema targetNamespace="http://example.com/ns/yes-no"
|
|
xmlns:xs="http://www.w3.org/2001/XMLSchema">
|
|
<xs:simpleType name="local:yes-no">
|
|
<xs:restriction base="xs:string">
|
|
<xs:enumeration value="yes"/>
|
|
<xs:enumeration value="no"/>
|
|
</xs:restriction>
|
|
</xs:simpleType>
|
|
</xs:schema>
|
|
</xsl:import-schema>
|
|
|
|
<xs:variable name="condition" select="'yes'" as="local:yes-no"/>
|
|
</pre></div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="div1">
|
|
<h2><a name="data-model" id="data-model"></a>4 <a href=
|
|
"#data-model" style="text-decoration: none">Data Model</a></h2>
|
|
<p>The data model used by XSLT is the <span>XPath 2.1 and XQuery
|
|
1.1</span> data model (XDM), as defined in <a href=
|
|
"#xpath-datamodel-11">[Data Model]</a>. XSLT operates on source,
|
|
result and stylesheet documents using the same data model.</p>
|
|
<p>This section elaborates on some particular features of XDM as it
|
|
is used by XSLT:</p>
|
|
<p>The rules in <a href="#stylesheet-stripping"><i>4.2 Stripping
|
|
Whitespace from the Stylesheet</i></a> and <a href="#strip"><i>4.4
|
|
Stripping Whitespace from a Source Tree</i></a> make use of the
|
|
concept of a whitespace text node.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-whitespace-text-node" id="dt-whitespace-text-node" title=
|
|
"whitespace text node"></a>A <b>whitespace text node</b> is a text
|
|
node whose content consists entirely of whitespace characters (that
|
|
is, #x09, #x0A, #x0D, or #x20).<span class=
|
|
"definition">]</span></p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>Features of a source XML document that are not represented in
|
|
the XDM tree will have no effect on the operation of an XSLT
|
|
stylesheet. Examples of such features are entity references, CDATA
|
|
sections, character references, whitespace within element tags, and
|
|
the choice of single or double quotes around attribute values.</p>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="xml-versions" id="xml-versions"></a>4.1 <a href=
|
|
"#xml-versions" style="text-decoration: none">XML Versions</a></h3>
|
|
<p>The XDM data model defined in <a href=
|
|
"#xpath-datamodel-11">[Data Model]</a> is capable of representing
|
|
either an XML 1.0 document (conforming to <a href="#REC-xml">[XML
|
|
1.0]</a> and <a href="#xml-names">[Namespaces in XML]</a>) or an
|
|
XML 1.1 document (conforming to <a href="#xml11">[XML 1.1]</a> and
|
|
<a href="#xml-names11">[Namespaces in XML 1.1]</a>), and it makes
|
|
no distinction between the two. In principle, therefore, XSLT
|
|
<span>2.1</span> can be used with either of these XML versions.</p>
|
|
<p>Construction of the XDM tree is outside the scope of this
|
|
specification, so XSLT <span>2.1</span> places no formal
|
|
requirements on an XSLT processor to accept input from either XML
|
|
1.0 documents or XML 1.1 documents or both. This specification does
|
|
define a serialization capability (see <a href=
|
|
"#serialization"><i>23 Serialization</i></a>), though from a
|
|
conformance point of view it is an optional feature. Although
|
|
facilities are described for serializing the XDM tree as either XML
|
|
1.0 or XML 1.1 (and controlling the choice), there is again no
|
|
formal requirement on an XSLT processor to support either or both
|
|
of these XML versions as serialization targets.</p>
|
|
<p>Because the XDM tree is the same whether the original document
|
|
was XML 1.0 or XML 1.1, the semantics of XSLT processing do not
|
|
depend on the version of XML used by the original document. There
|
|
is no reason in principle why all the input and output documents
|
|
used in a single transformation must conform to the same version of
|
|
XML.</p>
|
|
<p>Some of the syntactic constructs in XSLT <span>2.1</span> and
|
|
<span>XPath 2.1</span>, for example the productions <a href=
|
|
"http://www.w3.org/TR/2000/REC-xml-20001006#NT-Char">Char</a><sup><small>XML</small></sup>
|
|
and <a href=
|
|
"http://www.w3.org/TR/REC-xml-names/#NT-NCName">NCName</a><sup><small>Names</small></sup>,
|
|
are defined by reference to the XML and XML Namespaces
|
|
specifications. There are slight variations between the XML 1.0 and
|
|
XML 1.1 versions of these productions <span>(and, indeed, between
|
|
different editions of XML 1.0)</span>. Implementations <span class=
|
|
"verb">may</span> support <span>any</span> version; it is
|
|
<span class="verb">recommended</span> that an XSLT <span>2.1</span>
|
|
processor that implements the 1.1 versions <span class=
|
|
"verb">should</span> also provide a mode that supports the 1.0
|
|
versions. It is thus <a title="implementation-defined" class=
|
|
"termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a> whether the
|
|
XSLT processor supports XML 1.0 with XML Namespaces 1.0, or XML 1.1
|
|
with XML Namespaces 1.1, or supports both versions at user
|
|
option.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>The specification referenced as <a href="#xml-names">[Namespaces
|
|
in XML]</a> was actually published without a version number.</p>
|
|
</div>
|
|
<p><span>The current version of <a href="#xmlschema-2">[XML Schema
|
|
Part 2]</a> (that is, XSD 1.0) does not reference the XML 1.1
|
|
specifications.</span> This means that data types such as
|
|
<code>xs:NCName</code> and <code>xs:ID</code> are constrained by
|
|
the XML 1.0 rules, and do not allow the full range of values
|
|
permitted by XML 1.1. This situation will not be resolved until a
|
|
new version of <a href="#xmlschema-2">[XML Schema Part 2]</a>
|
|
becomes available; in the meantime, it is <span class=
|
|
"verb">recommended</span> that implementers wishing to support XML
|
|
1.1 should consult <a href="#SCHEMA-AND-XML-1.1">[XML Schema 1.0
|
|
and XML 1.1]</a> for guidance. An XSLT <span>2.1</span> processor
|
|
that supports XML 1.1 <span class="verb">should</span> implement
|
|
the rules in later versions of <a href="#xmlschema-2">[XML Schema
|
|
Part 2]</a> as they become available.</p>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="stylesheet-stripping" id=
|
|
"stylesheet-stripping"></a>4.2 <a href="#stylesheet-stripping"
|
|
style="text-decoration: none">Stripping Whitespace from the
|
|
Stylesheet</a></h3>
|
|
<p>The tree representing the stylesheet is preprocessed as
|
|
follows:</p>
|
|
<ol class="enumar">
|
|
<li>
|
|
<p>All comments and processing instructions are removed.</p>
|
|
</li>
|
|
<li>
|
|
<p>Any text nodes that are now adjacent to each other are
|
|
merged.</p>
|
|
</li>
|
|
<li>
|
|
<p>Any <a title="whitespace text node" class="termref" href=
|
|
"#dt-whitespace-text-node">whitespace text node</a> that satisfies
|
|
both the following conditions is removed from the tree:</p>
|
|
<ul>
|
|
<li>
|
|
<p>The parent of the text node is not an <a href=
|
|
"#element-text"><code>xsl:text</code></a> element</p>
|
|
</li>
|
|
<li>
|
|
<p>The text node does not have an ancestor element that has an
|
|
<code>xml:space</code> attribute with a value of
|
|
<code>preserve</code>, unless there is a closer ancestor element
|
|
having an <code>xml:space</code> attribute with a value of
|
|
<code>default</code>.</p>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
<p>Any <a title="whitespace text node" class="termref" href=
|
|
"#dt-whitespace-text-node">whitespace text node</a> whose parent is
|
|
one of the following elements is removed from the tree, regardless
|
|
of any <code>xml:space</code> attributes:</p>
|
|
<blockquote>
|
|
<p><a href=
|
|
"#element-analyze-string"><code>xsl:analyze-string</code></a><br />
|
|
<a href=
|
|
"#element-apply-imports"><code>xsl:apply-imports</code></a><br />
|
|
<a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a><br />
|
|
|
|
<a href=
|
|
"#element-attribute-set"><code>xsl:attribute-set</code></a><br />
|
|
<a href=
|
|
"#element-call-template"><code>xsl:call-template</code></a><br />
|
|
<a href=
|
|
"#element-character-map"><code>xsl:character-map</code></a><br />
|
|
<a href="#element-choose"><code>xsl:choose</code></a><br />
|
|
<span><a href=
|
|
"#element-evaluate"><code>xsl:evaluate</code></a></span><br />
|
|
<span><a href=
|
|
"#element-merge"><code>xsl:merge</code></a></span><br />
|
|
<span><a href=
|
|
"#element-merge-source"><code>xsl:merge-source</code></a></span><br />
|
|
|
|
<span><a href=
|
|
"#element-next-iteration"><code>xsl:next-iteration</code></a></span><br />
|
|
|
|
<a href="#element-next-match"><code>xsl:next-match</code></a><br />
|
|
<a href="#element-stylesheet"><code>xsl:stylesheet</code></a><br />
|
|
<a href="#element-transform"><code>xsl:transform</code></a></p>
|
|
</blockquote>
|
|
</li>
|
|
<li>
|
|
<p>Any <a title="whitespace text node" class="termref" href=
|
|
"#dt-whitespace-text-node">whitespace text node</a> whose immediate
|
|
following-sibling node is an <span><a href=
|
|
"#element-merge-key"><code>xsl:merge-key</code></a>,</span>
|
|
<a href="#element-param"><code>xsl:param</code></a>, or <a href=
|
|
"#element-sort"><code>xsl:sort</code></a> element is removed from
|
|
the tree, regardless of any <code>xml:space</code> attributes.</p>
|
|
</li>
|
|
<li>
|
|
<p>Any <a title="whitespace text node" class="termref" href=
|
|
"#dt-whitespace-text-node">whitespace text node</a> whose immediate
|
|
preceding-sibling node is an <a href=
|
|
"#element-catch"><code>xsl:catch</code></a> or <a href=
|
|
"#element-on-completion"><code>xsl:on-completion</code></a> element
|
|
is removed from the tree, regardless of any <code>xml:space</code>
|
|
attributes.</p>
|
|
</li>
|
|
</ol>
|
|
<p><a name="err-XTSE0260" id="err-XTSE0260"><span class=
|
|
"error">[ERR XTSE0260]</span></a> Within an <a title="XSLT element"
|
|
class="termref" href="#dt-xslt-element">XSLT element</a> that is
|
|
<span class="verb">required</span> to be empty, any content other
|
|
than comments or processing instructions, including any <a title=
|
|
"whitespace text node" class="termref" href=
|
|
"#dt-whitespace-text-node">whitespace text node</a> preserved using
|
|
the <code>xml:space="preserve"</code> attribute, is a <a title=
|
|
"static error" class="termref" href="#dt-static-error">static
|
|
error</a>.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>Using <code>xml:space="preserve"</code> in parts of the
|
|
stylesheet that contain <a title="sequence constructor" class=
|
|
"termref" href="#dt-sequence-constructor">sequence constructors</a>
|
|
will cause all text nodes in that part of the stylesheet, including
|
|
those that contain whitespace only, to be copied to the result of
|
|
the sequence constructor. When the result of the sequence
|
|
constructor is used to form the content of an element, this can
|
|
cause errors if such text nodes are followed by attribute nodes
|
|
generated using <a href=
|
|
"#element-attribute"><code>xsl:attribute</code></a>.</p>
|
|
</div>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>If an <code>xml:space</code> attribute is specified on a
|
|
<a title="literal result element" class="termref" href=
|
|
"#dt-literal-result-element">literal result element</a>, it will be
|
|
copied to the result tree in the same way as any other
|
|
attribute.</p>
|
|
</div>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="stripping-annotations" id=
|
|
"stripping-annotations"></a>4.3 <a href="#stripping-annotations"
|
|
style="text-decoration: none">Stripping Type Annotations from a
|
|
Source Tree</a></h3>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-annotation" id="dt-annotation" title="type annotation"></a>The
|
|
term <b>type annotation</b> is used in this specification to refer
|
|
to the value returned by the <code>dm:type-name</code> accessor of
|
|
a node: see <a href=
|
|
"http://www.w3.org/TR/xpath-datamodel-11/#dm-type-name">Section
|
|
5.14 type-name
|
|
Accessor</a><sup><small>DM11</small></sup>.<span class=
|
|
"definition">]</span></p>
|
|
<p>There is sometimes a requirement to write stylesheets that
|
|
produce the same results whether or not the source documents have
|
|
been validated against a schema. To achieve this, an option is
|
|
provided to remove any <a title="type annotation" class="termref"
|
|
href="#dt-annotation">type annotations</a> on element and attribute
|
|
nodes in a <a title="source tree" class="termref" href=
|
|
"#dt-source-tree">source tree</a>, replacing them with an
|
|
annotation of <code>xs:untyped</code> in the case of element nodes,
|
|
and <code>xs:untypedAtomic</code> in the case of attribute
|
|
nodes.</p>
|
|
<p>Such stripping of <a title="type annotation" class="termref"
|
|
href="#dt-annotation">type annotations</a> can be requested by
|
|
specifying <code>input-type-annotations="strip"</code> on the
|
|
<a href="#element-stylesheet"><code>xsl:stylesheet</code></a>
|
|
element. This attribute has three permitted values:
|
|
<code>strip</code>, <code>preserve</code>, and
|
|
<code>unspecified</code>. The default value is
|
|
<code>unspecified</code>. Stripping of type annotations takes place
|
|
if at least one <a title="stylesheet module" class="termref" href=
|
|
"#dt-stylesheet-module">stylesheet module</a> in the <a title=
|
|
"stylesheet" class="termref" href="#dt-stylesheet">stylesheet</a>
|
|
specifies <code>input-type-annotations="strip"</code>.</p>
|
|
<p><a name="err-XTSE0265" id="err-XTSE0265"><span class=
|
|
"error">[ERR XTSE0265]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> if there
|
|
is a <a title="stylesheet module" class="termref" href=
|
|
"#dt-stylesheet-module">stylesheet module</a> in the <a title=
|
|
"stylesheet" class="termref" href="#dt-stylesheet">stylesheet</a>
|
|
that specifies <code>input-type-annotations="strip"</code> and
|
|
another <a title="stylesheet module" class="termref" href=
|
|
"#dt-stylesheet-module">stylesheet module</a> that specifies
|
|
<code>input-type-annotations="preserve"</code>.</p>
|
|
<p>The <a title="source tree" class="termref" href=
|
|
"#dt-source-tree">source trees</a> to which this applies are the
|
|
same as those affected by <a href=
|
|
"#element-strip-space"><code>xsl:strip-space</code></a> and
|
|
<a href="#element-preserve-space"><code>xsl:preserve-space</code></a>:
|
|
see <a href="#strip"><i>4.4 Stripping Whitespace from a Source
|
|
Tree</i></a>.</p>
|
|
<p>When type annotations are stripped, the following changes are
|
|
made to the source tree:</p>
|
|
<ul>
|
|
<li>
|
|
<p>The type annotation of every element node is changed to
|
|
<code>xs:untyped</code></p>
|
|
</li>
|
|
<li>
|
|
<p>The type annotation of every attribute node is changed to
|
|
<code>xs:untypedAtomic</code></p>
|
|
</li>
|
|
<li>
|
|
<p>The typed value of every element and attribute node is set to be
|
|
the same as its string value, as an instance of
|
|
<code>xs:untypedAtomic</code>.</p>
|
|
</li>
|
|
<li>
|
|
<p>The <code>is-nilled</code> property of every element node is set
|
|
to <code>false</code>.</p>
|
|
</li>
|
|
</ul>
|
|
<p>The values of the <code>is-id</code> and <code>is-idrefs</code>
|
|
properties are not changed.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>Stripping type annotations does not necessarily return the
|
|
document to the state it would be in had validation not taken
|
|
place. In particular, any defaulted elements and attributes that
|
|
were added to the tree by the validation process will still be
|
|
present , and elements and attributes validated as IDs will still
|
|
be accessible using the <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-id"><code>id</code></a><sup><small>FO</small></sup>
|
|
function.</p>
|
|
</div>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="strip" id="strip"></a>4.4 <a href="#strip" style=
|
|
"text-decoration: none">Stripping Whitespace from a Source
|
|
Tree</a></h3>
|
|
<p>A <a title="source tree" class="termref" href=
|
|
"#dt-source-tree">source tree</a> supplied as input to the
|
|
transformation process may contain <a title="whitespace text node"
|
|
class="termref" href="#dt-whitespace-text-node">whitespace text
|
|
nodes</a> that are of no interest, and that do not need to be
|
|
retained by the transformation. Conceptually, an XSLT <a title=
|
|
"processor" class="termref" href="#dt-processor">processor</a>
|
|
makes a copy of the source tree from which unwanted <a title=
|
|
"whitespace text node" class="termref" href=
|
|
"#dt-whitespace-text-node">whitespace text nodes</a> have been
|
|
removed. This process is referred to as whitespace stripping.</p>
|
|
<p>For the purposes of this section, the term <b>source tree</b>
|
|
means the document containing the <a title="initial context item"
|
|
class="termref" href="#dt-initial-context-item">initial context
|
|
item</a> <span>if it is a node</span>, and any document returned by
|
|
the functions <a href=
|
|
"#function-document"><code>document</code></a>, <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-doc"><code>doc</code></a><sup><small>FO</small></sup>,
|
|
or <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-collection"><code>collection</code></a><sup><small>FO</small></sup>.
|
|
It does not include documents passed as the values of <a title=
|
|
"stylesheet parameter" class="termref" href=
|
|
"#dt-stylesheet-parameter">stylesheet parameters</a> or returned
|
|
from <a title="extension function" class="termref" href=
|
|
"#dt-extension-function">extension functions</a>.</p>
|
|
<p>The stripping process takes as input a set of element names
|
|
whose child <a title="whitespace text node" class="termref" href=
|
|
"#dt-whitespace-text-node">whitespace text nodes</a> are to be
|
|
preserved. The way in which this set of element names is
|
|
established using the <a href=
|
|
"#element-strip-space"><code>xsl:strip-space</code></a> and
|
|
<a href="#element-preserve-space"><code>xsl:preserve-space</code></a>
|
|
declarations is described later in this section.</p>
|
|
<p>A <a title="whitespace text node" class="termref" href=
|
|
"#dt-whitespace-text-node">whitespace text node</a> is preserved if
|
|
either of the following apply:</p>
|
|
<ul>
|
|
<li>
|
|
<p>The element name of the parent of the text node is in the set of
|
|
whitespace-preserving element names.</p>
|
|
</li>
|
|
<li>
|
|
<p>An ancestor element of the text node has an
|
|
<code>xml:space</code> attribute with a value of
|
|
<code>preserve</code>, and no closer ancestor element has
|
|
<code>xml:space</code> with a value of <code>default</code>.</p>
|
|
</li>
|
|
</ul>
|
|
<p>Otherwise, the <a title="whitespace text node" class="termref"
|
|
href="#dt-whitespace-text-node">whitespace text node</a> is
|
|
stripped.</p>
|
|
<p>The <code>xml:space</code> attributes are not removed from the
|
|
tree.</p>
|
|
<p class="element-syntax"><a name="element-strip-space" id=
|
|
"element-strip-space"></a><code><!-- Category: declaration
|
|
--><br />
|
|
<xsl:strip-space<br />
|
|
  <b>elements</b> =
|
|
<var>tokens</var> /></code></p>
|
|
<p class="element-syntax"><a name="element-preserve-space" id=
|
|
"element-preserve-space"></a><code><!-- Category: declaration
|
|
--><br />
|
|
<xsl:preserve-space<br />
|
|
  <b>elements</b> =
|
|
<var>tokens</var> /></code></p>
|
|
<p>The set of whitespace-preserving element names is specified by
|
|
<a href="#element-strip-space"><code>xsl:strip-space</code></a> and
|
|
<a href=
|
|
"#element-preserve-space"><code>xsl:preserve-space</code></a>
|
|
<a title="declaration" class="termref" href=
|
|
"#dt-declaration">declarations</a>. Whether an element name is
|
|
included in the set of whitespace-preserving names is determined by
|
|
the best match among all the <a href=
|
|
"#element-strip-space"><code>xsl:strip-space</code></a> or <a href=
|
|
"#element-preserve-space"><code>xsl:preserve-space</code></a>
|
|
declarations: it is included if and only if there is no match or
|
|
the best match is an <a href=
|
|
"#element-preserve-space"><code>xsl:preserve-space</code></a>
|
|
element. The <a href=
|
|
"#element-strip-space"><code>xsl:strip-space</code></a> and
|
|
<a href="#element-preserve-space"><code>xsl:preserve-space</code></a>
|
|
elements each have an <code>elements</code> attribute whose value
|
|
is a whitespace-separated list of <a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-NameTest">NameTests</a><sup><small>XP21</small></sup>;
|
|
an element name matches an <a href=
|
|
"#element-strip-space"><code>xsl:strip-space</code></a> or <a href=
|
|
"#element-preserve-space"><code>xsl:preserve-space</code></a>
|
|
element if it matches one of the <a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-NameTest">NameTests</a><sup><small>XP21</small></sup>.
|
|
An element matches a <a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-NameTest">NameTest</a><sup><small>XP21</small></sup>
|
|
if and only if the <a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-NameTest">NameTest</a><sup><small>XP21</small></sup>
|
|
would be true for the element as an XPath node test. When more than
|
|
one <a href="#element-strip-space"><code>xsl:strip-space</code></a>
|
|
and <a href=
|
|
"#element-preserve-space"><code>xsl:preserve-space</code></a>
|
|
element matches, the best matching element is determined by the
|
|
best matching <a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-NameTest">NameTest</a><sup><small>XP21</small></sup>.
|
|
This is determined in the same way as with <a title="template rule"
|
|
class="termref" href="#dt-template-rule">template rules</a>:</p>
|
|
<ul>
|
|
<li>
|
|
<p>First, any match with lower <a title="import precedence" class=
|
|
"termref" href="#dt-import-precedence">import precedence</a> than
|
|
another match is ignored.</p>
|
|
</li>
|
|
<li>
|
|
<p>Next, any match that has a lower <a title="default priority"
|
|
class="termref" href="#dt-default-priority">default priority</a>
|
|
than the <a title="default priority" class="termref" href=
|
|
"#dt-default-priority">default priority</a> of another match is
|
|
ignored.</p>
|
|
</li>
|
|
</ul>
|
|
<p><a name="err-XTRE0270" id="err-XTRE0270"><span class=
|
|
"error">[ERR XTRE0270]</span></a> It is a <a title=
|
|
"recoverable error" class="termref" href=
|
|
"#dt-recoverable-error">recoverable dynamic error</a> if this
|
|
leaves more than one match, unless all the matched declarations are
|
|
equivalent (that is, they are all <a href=
|
|
"#element-strip-space"><code>xsl:strip-space</code></a> or they are
|
|
all <a href=
|
|
"#element-preserve-space"><code>xsl:preserve-space</code></a>). The
|
|
<a title="optional recovery action" class="termref" href=
|
|
"#dt-optional-recovery-action">optional recovery action</a> is to
|
|
select, from the matches that are left, the one that occurs last in
|
|
<a title="declaration order" class="termref" href=
|
|
"#dt-declaration-order">declaration order</a>.</p>
|
|
<blockquote>
|
|
<p><b><a name="issue-multiple-match-on-strip-space" id=
|
|
"issue-multiple-match-on-strip-space">Issue 4
|
|
(multiple-match-on-strip-space)</a>:</b></p>
|
|
<p>We have changed the rules for handling ambiguous matches on
|
|
template rules. Should we make a corresponding change for ambiguous
|
|
matches on <a href=
|
|
"#element-strip-space"><code>xsl:strip-space</code></a>, or is this
|
|
overkill? What is the corresponding change anyway?</p>
|
|
</blockquote>
|
|
<p>If an element in a source document has a <a title=
|
|
"type annotation" class="termref" href="#dt-annotation">type
|
|
annotation</a> that is a simple type or a complex type with simple
|
|
content, then any whitespace text nodes among its children are
|
|
preserved, regardless of any <a href=
|
|
"#element-strip-space"><code>xsl:strip-space</code></a>
|
|
declarations. The reason for this is that stripping a whitespace
|
|
text node from an element with simple content could make the
|
|
element invalid: for example, it could cause the
|
|
<code>minLength</code> facet to be violated.</p>
|
|
<p>Stripping of <a title="type annotation" class="termref" href=
|
|
"#dt-annotation">type annotations</a> happens before stripping of
|
|
whitespace text nodes, so this situation will not occur if
|
|
<code>input-type-annotations="strip"</code> is specified.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>In <a href="#xpath-datamodel-11">[Data Model]</a>, processes are
|
|
described for constructing an XDM tree from an Infoset or from a
|
|
PSVI. Those processes deal with whitespace according to their own
|
|
rules, and the provisions in this section apply to the resulting
|
|
tree. In practice this means that elements that are defined in a
|
|
DTD or a Schema to contain element-only content will have <a title=
|
|
"whitespace text node" class="termref" href=
|
|
"#dt-whitespace-text-node">whitespace text nodes</a> stripped,
|
|
regardless of the <a href=
|
|
"#element-strip-space"><code>xsl:strip-space</code></a> and
|
|
<a href="#element-preserve-space"><code>xsl:preserve-space</code></a>
|
|
declarations in the stylesheet.</p>
|
|
<p>However, source trees are not necessarily constructed using
|
|
those processes; indeed, they are not necessarily constructed by
|
|
parsing XML documents. Nothing in the XSLT specification constrains
|
|
how the source tree is constructed, or what happens to <a title=
|
|
"whitespace text node" class="termref" href=
|
|
"#dt-whitespace-text-node">whitespace text nodes</a> during its
|
|
construction. The provisions in this section relate only to
|
|
whitespace text nodes that are present in the tree supplied as
|
|
input to the XSLT processor. The XSLT processor cannot preserve
|
|
whitespace text nodes unless they were actually present in the
|
|
supplied tree.</p>
|
|
</div>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="id-in-data-model" id="id-in-data-model"></a>4.5
|
|
<a href="#id-in-data-model" style="text-decoration: none">Attribute
|
|
Types and DTD Validation</a></h3>
|
|
<p>The mapping from the Infoset to the XDM data model, described in
|
|
<a href="#xpath-datamodel-11">[Data Model]</a>, does not retain
|
|
attribute types. This means, for example, that an attribute
|
|
described in the DTD as having attribute type <code>NMTOKENS</code>
|
|
will be annotated in the XDM tree as <code>xs:untypedAtomic</code>
|
|
rather than <code>xs:NMTOKENS</code>, and its typed value will
|
|
consist of a single <code>xs:untypedAtomic</code> value rather than
|
|
a sequence of <code>xs:NMTOKEN</code> values.</p>
|
|
<p>Attributes with a DTD-derived type of ID, IDREF, or IDREFS will
|
|
be marked in the XDM tree as having the <code>is-id</code> or
|
|
<code>is-idrefs</code> properties. It is these properties, rather
|
|
than any <a title="type annotation" class="termref" href=
|
|
"#dt-annotation">type annotation</a>, that are examined by the
|
|
functions <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-id"><code>id</code></a><sup><small>FO</small></sup>
|
|
and <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-idref"><code>idref</code></a><sup><small>FO</small></sup>
|
|
described in <a href="#xpath-functions-11">[Functions and
|
|
Operators]</a>.</p>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="model-for-streaming" id="model-for-streaming"></a>4.6
|
|
<a href="#model-for-streaming" style="text-decoration: none">Data
|
|
Model for Streaming</a></h3>
|
|
<p>The data model for nodes in a document that is being streamed is
|
|
no different from the standard XDM data model, in that it contains
|
|
the same objects (nodes) with the same properties and
|
|
relationships. The facilities for streaming do not change the data
|
|
model; instead they impose rules that limit the ability of
|
|
stylesheets to navigate the data model.</p>
|
|
<p>A useful way to visualize streaming is to suppose that at any
|
|
point in time, there is a current position in the streamed input
|
|
document which may be the start or end of the document, the start
|
|
or end tag of an element, or a text, comment, or processing
|
|
instruction node. From this position, the stylesheet has access to
|
|
the following information:</p>
|
|
<ul>
|
|
<li>
|
|
<p>Properties intrinsic to the node, such as its name, its base
|
|
URI, its type annotation, and its <code>is-id</code> and
|
|
<code>is-idref</code> properties.</p>
|
|
</li>
|
|
<li>
|
|
<p>The ancestors of the node (but navigation downwards from the
|
|
ancestors is not permitted).</p>
|
|
</li>
|
|
<li>
|
|
<p>The attributes of the node, and the attributes of its ancestors.
|
|
For each such attribute, all the properties of the node including
|
|
its string value and typed value are available, but there are
|
|
limitations that restrict navigation from the attribute node to
|
|
other nodes in the document.</p>
|
|
</li>
|
|
<li>
|
|
<p>The in-scope namespace bindings of the node.</p>
|
|
</li>
|
|
<li>
|
|
<p>In the case of attributes, text nodes, comments, and processing
|
|
instructions, the string value and typed value of the node.</p>
|
|
</li>
|
|
<li>
|
|
<p>Summary data about the preceding siblings of the node, and of
|
|
each of its ancestor nodes: specifically, for each distinct
|
|
combination of node kind, node name, and type annotation, a count
|
|
of the number of preceding siblings that have that combination of
|
|
properties. This information allows patterns such as
|
|
<code>match="para[1]"</code> to be used, and it permits some
|
|
limited use of the <a href=
|
|
"#element-number"><code>xsl:number</code></a> instruction.</p>
|
|
</li>
|
|
</ul>
|
|
<p>The children and other descendants of a node are not accessible
|
|
except as a by-product of changing the current position in the
|
|
document. The same applies to properties of an element or document
|
|
node that require examination of the node's descendants, that is,
|
|
the string value and typed value. This is enforced by means of a
|
|
rule that only one expression requiring downward navigation from a
|
|
node is permitted.</p>
|
|
<p>The detailed rules are defined in <a href=
|
|
"#streamability"><i>18.4 Streamability Analysis</i></a>.</p>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="limits" id="limits"></a>4.7 <a href="#limits" style=
|
|
"text-decoration: none">Limits</a></h3>
|
|
<p>The XDM data model (see <a href="#xpath-datamodel-11">[Data
|
|
Model]</a>) leaves it to the host language to define limits. This
|
|
section describes the limits that apply to XSLT.</p>
|
|
<p>Limits on some primitive data types are defined in <a href=
|
|
"#xmlschema-2">[XML Schema Part 2]</a>. Other limits, listed below,
|
|
are <a title="implementation-defined" class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a>. Note that
|
|
this does not necessarily mean that each limit must be a simple
|
|
constant: it may vary depending on environmental factors such as
|
|
available resources.</p>
|
|
<p>The following limits are <a title="implementation-defined"
|
|
class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a>:</p>
|
|
<ol class="enumar">
|
|
<li>
|
|
<p>For the <code>xs:decimal</code> type, the maximum number of
|
|
decimal digits (the <code>totalDigits</code> facet). This must be
|
|
at least 18 digits. (Note, however, that support for the full value
|
|
range of <code>xs:unsignedLong</code> requires 20 digits.)</p>
|
|
</li>
|
|
<li>
|
|
<p>For the types <code>xs:date</code>, <code>xs:time</code>,
|
|
<code>xs:dateTime</code>, <code>xs:gYear</code>, and
|
|
<code>xs:gYearMonth</code>: the range of values of the year
|
|
component, which must be at least +0001 to +9999; and the maximum
|
|
number of fractional second digits, which must be at least 3.</p>
|
|
</li>
|
|
<li>
|
|
<p>For the <code>xs:duration</code> type: the maximum absolute
|
|
values of the years, months, days, hours, minutes, and seconds
|
|
components.</p>
|
|
</li>
|
|
<li>
|
|
<p>For the <code>xs:yearMonthDuration</code> type: the maximum
|
|
absolute value, expressed as an integer number of months.</p>
|
|
</li>
|
|
<li>
|
|
<p>For the <code>xs:dayTimeDuration</code> type: the maximum
|
|
absolute value, expressed as a decimal number of seconds.</p>
|
|
</li>
|
|
<li>
|
|
<p>For the types <code>xs:string</code>, <code>xs:hexBinary</code>,
|
|
<code>xs:base64Binary</code>, <code>xs:QName</code>,
|
|
<code>xs:anyURI</code>, <code>xs:NOTATION</code>, and types derived
|
|
from them: the maximum length of the value.</p>
|
|
</li>
|
|
<li>
|
|
<p>For sequences, the maximum number of items in a sequence.</p>
|
|
</li>
|
|
</ol>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="d-o-e-in-data-model" id="d-o-e-in-data-model"></a>4.8
|
|
<a href="#d-o-e-in-data-model" style=
|
|
"text-decoration: none">Disable Output Escaping</a></h3>
|
|
<p>For backwards compatibility reasons, XSLT <span>2.1</span>
|
|
continues to support the <code>disable-output-escaping</code>
|
|
feature introduced in XSLT 1.0. This is an optional feature and
|
|
implementations are not <span class="verb">required</span> to
|
|
support it. A new facility, that of named <a title="character map"
|
|
class="termref" href="#dt-character-map">character maps</a> (see
|
|
<a href="#character-maps"><i>23.1 Character Maps</i></a>)
|
|
<span>was</span> introduced in XSLT 2.0. It provides similar
|
|
capabilities to <code>disable-output-escaping</code>, but without
|
|
distorting the data model.</p>
|
|
<p>If an <a title="implementation" class="termref" href=
|
|
"#dt-implementation">implementation</a> supports the
|
|
<code>disable-output-escaping</code> attribute of <a href=
|
|
"#element-text"><code>xsl:text</code></a> and <a href=
|
|
"#element-value-of"><code>xsl:value-of</code></a>, (see <a href=
|
|
"#disable-output-escaping"><i>23.2 Disabling Output
|
|
Escaping</i></a>), then the data model for trees constructed by the
|
|
<a title="processor" class="termref" href=
|
|
"#dt-processor">processor</a> is augmented with a boolean value
|
|
representing the value of this property. This boolean value,
|
|
however, can be set only within a <a title="final result tree"
|
|
class="termref" href="#dt-final-result-tree">final result tree</a>
|
|
that is being passed to the serializer.</p>
|
|
<p>Conceptually, each character in a text node on such a result
|
|
tree has a boolean property indicating whether the serializer is to
|
|
disable the normal rules for escaping of special characters (for
|
|
example, outputting of <code>&</code> as
|
|
<code>&amp;</code>) in respect of this character or attribute
|
|
node.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>In practice, the nodes in a <a title="final result tree" class=
|
|
"termref" href="#dt-final-result-tree">final result tree</a> will
|
|
often be streamed directly from the XSLT processor to the
|
|
serializer. In such an implementation,
|
|
<code>disable-output-escaping</code> can be viewed not so much a
|
|
property stored with nodes in the tree, but rather as additional
|
|
information passed across the interface between the XSLT processor
|
|
and the serializer.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="div1">
|
|
<h2><a name="constructs" id="constructs"></a>5 <a href=
|
|
"#constructs" style="text-decoration: none">Features of the XSLT
|
|
Language</a></h2>
|
|
<div class="div2">
|
|
<h3><a name="qname" id="qname"></a>5.1 <a href="#qname" style=
|
|
"text-decoration: none">Qualified Names</a></h3>
|
|
<p>The name of a stylesheet-defined object, specifically a
|
|
<a title="named template" class="termref" href=
|
|
"#dt-named-template">named template</a>, a <a title="mode" class=
|
|
"termref" href="#dt-mode">mode</a>, an <a title="attribute set"
|
|
class="termref" href="#dt-attribute-set">attribute set</a>, a
|
|
<a title="key" class="termref" href="#dt-key">key</a>, a <a title=
|
|
"decimal format" class="termref" href=
|
|
"#dt-decimal-format">decimal-format</a>, a <a title="variable"
|
|
class="termref" href="#dt-variable">variable</a> or <a title=
|
|
"parameter" class="termref" href="#dt-parameter">parameter</a>, a
|
|
<a title="stylesheet function" class="termref" href=
|
|
"#dt-stylesheet-function">stylesheet function</a>, a named
|
|
<a title="output definition" class="termref" href=
|
|
"#dt-output-definition">output definition</a>, or a <a title=
|
|
"character map" class="termref" href="#dt-character-map">character
|
|
map</a> is specified as a <a title="QName" class="termref" href=
|
|
"#dt-qname">QName</a> using the syntax for <a href=
|
|
"http://www.w3.org/TR/REC-xml-names/#NT-QName">QName</a><sup><small>Names</small></sup>
|
|
as defined in <a href="#xml-names">[Namespaces in XML]</a>.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-qname" id="dt-qname" title="QName"></a>A <b>QName</b> is always
|
|
written in the form <code>(NCName ":")? NCName</code>, that is, a
|
|
local name optionally preceded by a namespace prefix. When two
|
|
QNames are compared, however, they are considered equal if the
|
|
corresponding <a title="expanded-QName" class="termref" href=
|
|
"#dt-expanded-qname">expanded-QNames</a> are the same, as described
|
|
below.<span class="definition">]</span></p>
|
|
<p>Because an atomic value of type <code>xs:QName</code> is
|
|
sometimes referred to loosely as a QName, this specification also
|
|
uses the term <a title="lexical QName" class="termref" href=
|
|
"#dt-lexical-qname">lexical QName</a> to emphasize that it is
|
|
referring to a <a href=
|
|
"http://www.w3.org/TR/REC-xml-names/#NT-QName">QName</a><sup><small>Names</small></sup>
|
|
in its lexical form rather than its expanded form. This term is
|
|
used especially when strings containing lexical QNames are
|
|
manipulated as run-time values.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-lexical-qname" id="dt-lexical-qname" title=
|
|
"lexical QName"></a>A <b>lexical QName</b> is a string representing
|
|
a <a title="QName" class="termref" href="#dt-qname">QName</a> in
|
|
the form <code>(NCName ":")? NCName</code>, that is, a local name
|
|
optionally preceded by a namespace prefix.<span class=
|
|
"definition">]</span></p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-defining-element" id="dt-defining-element" title=
|
|
"defining element"></a>A string in the form of a lexical QName may
|
|
occur as the value of an attribute node in a stylesheet module, or
|
|
within an XPath <a title="expression" class="termref" href=
|
|
"#dt-expression">expression</a> 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 <b>defining element</b> of the
|
|
QName.<span class="definition">]</span></p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-expanded-qname" id="dt-expanded-qname" title=
|
|
"expanded-QName"></a>An <b>expanded-QName</b> contains a pair of
|
|
values, namely a local name and an optional namespace URI. It may
|
|
also contain a namespace prefix. Two expanded-QNames are equal if
|
|
the namespace URIs are the same (or both absent) and the local
|
|
names are the same. The prefix plays no part in the comparison, but
|
|
is used only if the expanded-QName needs to be converted back to a
|
|
string.<span class="definition">]</span></p>
|
|
<p>If the QName has a prefix, then the prefix is expanded into a
|
|
URI reference using the namespace declarations in effect on its
|
|
<a title="defining element" class="termref" href=
|
|
"#dt-defining-element">defining element</a>. The <a title=
|
|
"expanded-QName" class="termref" href=
|
|
"#dt-expanded-qname">expanded-QName</a> consisting of the local
|
|
part of the name and the possibly null URI reference is used as the
|
|
name of the object. The default namespace of the defining element
|
|
(see <a href=
|
|
"http://www.w3.org/TR/xpath-datamodel-11/#ElementNode">Section 6.2
|
|
Element Nodes</a><sup><small>DM11</small></sup>) is <em>not</em>
|
|
used for unprefixed names.</p>
|
|
<p>There are three cases where the default namespace of the
|
|
<a title="defining element" class="termref" href=
|
|
"#dt-defining-element">defining element</a> <em>is</em> used when
|
|
expanding an unprefixed QName:</p>
|
|
<ol class="enumar">
|
|
<li>
|
|
<p>Where a QName is used to define the name of an element being
|
|
constructed. This applies both to cases where the name is known
|
|
statically (that is, the name of a literal result element) and to
|
|
cases where it is computed dynamically (the value of the
|
|
<code>name</code> attribute of the <a href=
|
|
"#element-element"><code>xsl:element</code></a> instruction).</p>
|
|
</li>
|
|
<li>
|
|
<p>The default namespace is used when expanding the first argument
|
|
of the function <a href=
|
|
"#function-element-available"><code>element-available</code></a>.</p>
|
|
</li>
|
|
<li>
|
|
<p>The default namespace applies to any unqualified element names
|
|
appearing in the <code>cdata-section-elements</code> attribute of
|
|
<a href="#element-output"><code>xsl:output</code></a> or <a href=
|
|
"#element-result-document"><code>xsl:result-document</code></a></p>
|
|
</li>
|
|
</ol>
|
|
<p>In the case of an unprefixed QName used as a
|
|
<code>NameTest</code> within an XPath <a title="expression" class=
|
|
"termref" href="#dt-expression">expression</a> (see <a href=
|
|
"#expressions"><i>5.3 Expressions</i></a>) , and in certain other
|
|
contexts, the namespace to be used in expanding the QName may be
|
|
specified by means of the
|
|
<code>[xsl:]xpath-default-namespace</code> attribute, as specified
|
|
in <a href="#unprefixed-qnames"><i>5.2 Unprefixed QNames in
|
|
Expressions and Patterns</i></a>.</p>
|
|
<p><a name="err-XTSE0280" id="err-XTSE0280"><span class=
|
|
"error">[ERR XTSE0280]</span></a> In the case of a prefixed
|
|
<a title="QName" class="termref" href="#dt-qname">QName</a> used as
|
|
the value of an attribute in the <a title="stylesheet" class=
|
|
"termref" href="#dt-stylesheet">stylesheet</a>, or appearing within
|
|
an XPath <a title="expression" class="termref" href=
|
|
"#dt-expression">expression</a> in the stylesheet, it is a
|
|
<a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if the <a title=
|
|
"defining element" class="termref" href=
|
|
"#dt-defining-element">defining element</a> has no namespace node
|
|
whose name matches the prefix of the <a title="QName" class=
|
|
"termref" href="#dt-qname">QName</a>.</p>
|
|
<p><a name="err-XTDE0290" id="err-XTDE0290"><span class=
|
|
"error">[ERR XTDE0290]</span></a> Where the result of evaluating an
|
|
XPath expression (or an attribute value template) is required to be
|
|
a <a title="lexical QName" class="termref" href=
|
|
"#dt-lexical-qname">lexical QName</a>, then unless otherwise
|
|
specified it is a <a title="non-recoverable dynamic error" class=
|
|
"termref" href="#dt-nonrec-dynamic-error">non-recoverable dynamic
|
|
error</a> if the <a title="defining element" class="termref" href=
|
|
"#dt-defining-element">defining element</a> has no namespace node
|
|
whose name matches the prefix of the <a title="lexical QName"
|
|
class="termref" href="#dt-lexical-qname">lexical QName</a>. This
|
|
error <span class="verb">may</span> be signaled as a <a title=
|
|
"static error" class="termref" href="#dt-static-error">static
|
|
error</a> if the value of the expression can be determined
|
|
statically.</p>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="unprefixed-qnames" id="unprefixed-qnames"></a>5.2
|
|
<a href="#unprefixed-qnames" style=
|
|
"text-decoration: none">Unprefixed QNames in Expressions and
|
|
Patterns</a></h3>
|
|
<p>The attribute <code>[xsl:]xpath-default-namespace</code> (see
|
|
<a href="#standard-attributes"><i>3.5 Standard Attributes</i></a>)
|
|
may be used on an element in the <a title="stylesheet" class=
|
|
"termref" href="#dt-stylesheet">stylesheet</a> to define the
|
|
namespace that will be used for an unprefixed element name or type
|
|
name within an XPath expression, and in certain other contexts
|
|
listed below.</p>
|
|
<p>The value of the attribute is the namespace URI to be used.</p>
|
|
<p>For any element in the <a title="stylesheet" class="termref"
|
|
href="#dt-stylesheet">stylesheet</a>, this attribute has an
|
|
effective value, which is the value of the
|
|
<code>[xsl:]xpath-default-namespace</code> on that element or on
|
|
the innermost containing element that specifies such an attribute,
|
|
or the zero-length string if no containing element specifies such
|
|
an attribute.</p>
|
|
<p>For any element in the <a title="stylesheet" class="termref"
|
|
href="#dt-stylesheet">stylesheet</a>, the effective value of this
|
|
attribute determines the value of the <em>default namespace for
|
|
element and type names</em> in the static context of any XPath
|
|
expression contained in an attribute of that element (including
|
|
XPath expressions in <a title="attribute value template" class=
|
|
"termref" href="#dt-attribute-value-template">attribute value
|
|
templates</a>). The effect of this is specified in <a href=
|
|
"#xpath-21">[XPath 2.1]</a>; in summary, it determines the
|
|
namespace used for any unprefixed type name in the SequenceType
|
|
production, and for any element name appearing in a path expression
|
|
or in the SequenceType production.</p>
|
|
<p>The effective value of this attribute similarly applies to any
|
|
of the following constructs appearing within its scope:</p>
|
|
<ul>
|
|
<li>
|
|
<p>any unprefixed element name or type name used in a <a title=
|
|
"pattern" class="termref" href="#dt-pattern">pattern</a></p>
|
|
</li>
|
|
<li>
|
|
<p>any unprefixed element name used in the <code>elements</code>
|
|
attribute of the <a href=
|
|
"#element-strip-space"><code>xsl:strip-space</code></a> or <a href=
|
|
"#element-preserve-space"><code>xsl:preserve-space</code></a>
|
|
instructions</p>
|
|
</li>
|
|
<li>
|
|
<p>any unprefixed element name or type name used in the
|
|
<code>as</code> attribute of an <a title="XSLT element" class=
|
|
"termref" href="#dt-xslt-element">XSLT element</a></p>
|
|
</li>
|
|
<li>
|
|
<p>any unprefixed type name used in the <code>type</code> attribute
|
|
of an <a title="XSLT element" class="termref" href=
|
|
"#dt-xslt-element">XSLT element</a></p>
|
|
</li>
|
|
<li>
|
|
<p>any unprefixed type name used in the <code>xsl:type</code>
|
|
attribute of a <a title="literal result element" class="termref"
|
|
href="#dt-literal-result-element">literal result element</a>.</p>
|
|
</li>
|
|
</ul>
|
|
<p>The <code>[xsl:]xpath-default-namespace</code> attribute
|
|
<span class="verb">must</span> be in the <a title="XSLT namespace"
|
|
class="termref" href="#dt-xslt-namespace">XSLT namespace</a> if and
|
|
only if its parent element is <em>not</em> in the XSLT
|
|
namespace.</p>
|
|
<p>If the effective value of the attribute is a zero-length string,
|
|
which will be the case if it is explicitly set to a zero-length
|
|
string or if it is not specified at all, then an unprefixed element
|
|
name or type name refers to a name that is in no namespace. The
|
|
default namespace of the parent element (see <a href=
|
|
"http://www.w3.org/TR/xpath-datamodel-11/#ElementNode">Section 6.2
|
|
Element Nodes</a><sup><small>DM11</small></sup>) is <em>not</em>
|
|
used.</p>
|
|
<p>The attribute does not affect other names, for example function
|
|
names, variable names, or template names, or strings that are
|
|
interpreted as <a title="lexical QName" class="termref" href=
|
|
"#dt-lexical-qname">lexical QNames</a> during stylesheet
|
|
evaluation, such as the <a title="effective value" class="termref"
|
|
href="#dt-effective-value">effective value</a> of the
|
|
<code>name</code> attribute of <a href=
|
|
"#element-element"><code>xsl:element</code></a> or the string
|
|
supplied as the first argument to the <a href=
|
|
"#function-key"><code>key</code></a> function.</p>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="expressions" id="expressions"></a>5.3 <a href=
|
|
"#expressions" style="text-decoration: none">Expressions</a></h3>
|
|
<p>XSLT uses the expression language defined by <span>XPath
|
|
2.1</span> <a href="#xpath-21">[XPath 2.1]</a>. Expressions are
|
|
used in XSLT for a variety of purposes including:</p>
|
|
<ul>
|
|
<li>
|
|
<p>selecting nodes for processing;</p>
|
|
</li>
|
|
<li>
|
|
<p>specifying conditions for different ways of processing a
|
|
node;</p>
|
|
</li>
|
|
<li>
|
|
<p>generating text to be inserted in a <a title="result tree"
|
|
class="termref" href="#dt-result-tree">result tree</a>.</p>
|
|
</li>
|
|
</ul>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-expression" id="dt-expression" title="expression"></a>Within
|
|
this specification, the term <b>XPath expression</b>, or simply
|
|
<b>expression</b>, means a string that matches the production
|
|
<a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-Expr">Expr</a><sup><small>XP21</small></sup>
|
|
defined in <a href="#xpath-21">[XPath 2.1]</a>.<span class=
|
|
"definition">]</span></p>
|
|
<p>An XPath expression may occur as the value of certain attributes
|
|
on XSLT-defined elements, and also within curly brackets in
|
|
<a title="attribute value template" class="termref" href=
|
|
"#dt-attribute-value-template">attribute value templates</a>.</p>
|
|
<p>Except where <a title="forwards compatible behavior" class=
|
|
"termref" href="#dt-forwards-compatible-behavior">forwards
|
|
compatible behavior</a> is enabled (see <a href="#forwards"><i>3.9
|
|
Forwards Compatible Processing</i></a>), it is a <a title=
|
|
"static error" class="termref" href="#dt-static-error">static
|
|
error</a> if the value of such an attribute, or the text between
|
|
curly brackets in an attribute value template, does not match the
|
|
XPath production <a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-Expr">Expr</a><sup><small>XP21</small></sup>,
|
|
or if it fails to satisfy other static constraints defined in the
|
|
XPath specification, for example that all variable references
|
|
<span class="verb">must</span> refer to <a title="variable" class=
|
|
"termref" href="#dt-variable">variables</a> that are in scope.
|
|
Error codes are defined in <a href="#xpath-21">[XPath 2.1]</a>.</p>
|
|
<p>The transformation fails with a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> if any
|
|
XPath <a title="expression" class="termref" href=
|
|
"#dt-expression">expression</a> is evaluated and raises a dynamic
|
|
error. Error codes are defined in <a href="#xpath-21">[XPath
|
|
2.1]</a>.</p>
|
|
<p>The transformation fails with a <a title="type errors" class=
|
|
"termref" href="#dt-type-error">type error</a> if an XPath
|
|
<a title="expression" class="termref" href=
|
|
"#dt-expression">expression</a> raises a type error, or if the
|
|
result of evaluating the XPath <a title="expression" class=
|
|
"termref" href="#dt-expression">expression</a> is evaluated and
|
|
raises a type error, or if the XPath processor signals a type error
|
|
during static analysis of an <a title="expression" class="termref"
|
|
href="#dt-expression">expression</a>. Error codes are defined in
|
|
<a href="#xpath-21">[XPath 2.1]</a>.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-required-type" id="dt-required-type" title=
|
|
"required type"></a>The context within a <a title="stylesheet"
|
|
class="termref" href="#dt-stylesheet">stylesheet</a> where an XPath
|
|
<a title="expression" class="termref" href=
|
|
"#dt-expression">expression</a> appears may specify the <b>required
|
|
type</b> of the expression. The required type indicates the type of
|
|
the value that the expression is expected to return.<span class=
|
|
"definition">]</span> If no required type is specified, the
|
|
expression may return any value: in effect, the required type is
|
|
then <code>item()*</code>.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-function-conversion-rules" id="dt-function-conversion-rules"
|
|
title="function conversion rules"></a>Except where otherwise
|
|
indicated, the actual value of an <a title="expression" class=
|
|
"termref" href="#dt-expression">expression</a> is converted to the
|
|
<a title="required type" class="termref" href=
|
|
"#dt-required-type">required type</a> using the <b>function
|
|
conversion rules</b>. These are the rules defined in <a href=
|
|
"#xpath-21">[XPath 2.1]</a> for converting the supplied argument of
|
|
a function call to the required type of that argument, as defined
|
|
in the function signature. The relevant rules are those that apply
|
|
when <a title="XPath 1.0 compatibility mode" class="termref" href=
|
|
"#dt-xpath-compat-mode">XPath 1.0 compatibility mode</a> is set to
|
|
<code>false</code>.<span class="definition">]</span></p>
|
|
<p>This specification also invokes the <span>XPath 2.1</span>
|
|
<a title="function conversion rules" class="termref" href=
|
|
"#dt-function-conversion-rules">function conversion rules</a> to
|
|
convert the result of evaluating an XSLT <a title=
|
|
"sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> to a required
|
|
type (for example, the sequence constructor enclosed in an <a href=
|
|
"#element-variable"><code>xsl:variable</code></a>, <a href=
|
|
"#element-template"><code>xsl:template</code></a>, or <a href=
|
|
"#element-function"><code>xsl:function</code></a> element).</p>
|
|
<p>Any <a title="dynamic error" class="termref" href=
|
|
"#dt-dynamic-error">dynamic error</a> or <a title="type errors"
|
|
class="termref" href="#dt-type-error">type error</a> that occurs
|
|
when applying the <a title="function conversion rules" class=
|
|
"termref" href="#dt-function-conversion-rules">function conversion
|
|
rules</a> to convert a value to a required type results in the
|
|
transformation failing, in the same way as if the error had
|
|
occurred while evaluating an expression.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>Note the distinction between the two kinds of error that may
|
|
occur. Attempting to convert an integer to a date is a type error,
|
|
because such a conversion is never possible. Type errors can be
|
|
reported statically if they can be detected statically, whether or
|
|
not the construct in question is ever evaluated. Attempting to
|
|
convert the string <code>2003-02-29</code> to a date is a dynamic
|
|
error rather than a type error, because the problem is with this
|
|
particular value, not with its type. Dynamic errors are reported
|
|
only if the instructions or expressions that cause them are
|
|
actually evaluated.</p>
|
|
</div>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="static-and-dynamic-context" id=
|
|
"static-and-dynamic-context"></a>5.4 <a href=
|
|
"#static-and-dynamic-context" style="text-decoration: none">The
|
|
Static and Dynamic Context</a></h3>
|
|
<p>XPath defines the concept of an <a href=
|
|
"http://www.w3.org/TR/xpath-21/#dt-expression-context">expression
|
|
context</a><sup><small>XP21</small></sup> which contains all the
|
|
information that can affect the result of evaluating an <a title=
|
|
"expression" class="termref" href="#dt-expression">expression</a>.
|
|
The expression context has two parts, the <a href=
|
|
"http://www.w3.org/TR/xpath-21/#dt-static-context">static
|
|
context</a><sup><small>XP21</small></sup>, and the <a href=
|
|
"http://www.w3.org/TR/xpath-21/#dt-dynamic-context">dynamic
|
|
context</a><sup><small>XP21</small></sup>. The components that make
|
|
up the expression context are defined in the XPath specification
|
|
(see <a href="http://www.w3.org/TR/xpath-21/#context">Section 2.1
|
|
Expression Context</a><sup><small>XP21</small></sup>). This section
|
|
describes the way in which these components are initialized when an
|
|
XPath expression is contained within an XSLT stylesheet.</p>
|
|
<p>As well as providing values for the static and dynamic context
|
|
components defined in the XPath specification, XSLT defines
|
|
additional context components of its own. These context components
|
|
are used by XSLT instructions (for example, <a href=
|
|
"#element-next-match"><code>xsl:next-match</code></a> and <a href=
|
|
"#element-apply-imports"><code>xsl:apply-imports</code></a>), and
|
|
also by the functions in the extended function library described in
|
|
this specification.</p>
|
|
<p>The following four sections describe:</p>
|
|
<blockquote>
|
|
<p><a href="#static-context"><i>5.4.1 Initializing the Static
|
|
Context</i></a><br />
|
|
<a href="#additional-static-context"><i>5.4.2 Additional Static
|
|
Context Components used by XSLT</i></a><br />
|
|
<a href="#xpath-dynamic-context"><i>5.4.3 Initializing the Dynamic
|
|
Context</i></a><br />
|
|
<a href="#additional-dynamic-context"><i>5.4.4 Additional Dynamic
|
|
Context Components used by XSLT</i></a></p>
|
|
</blockquote>
|
|
<div class="div3">
|
|
<h4><a name="static-context" id="static-context"></a>5.4.1 <a href=
|
|
"#static-context" style="text-decoration: none">Initializing the
|
|
Static Context</a></h4>
|
|
<p>The <a href=
|
|
"http://www.w3.org/TR/xpath-21/#dt-static-context">static
|
|
context</a><sup><small>XP21</small></sup> of an XPath expression
|
|
appearing in an XSLT stylesheet is initialized as follows. In these
|
|
rules, the term <b>containing element</b> means the element within
|
|
the stylesheet that is the parent of the attribute whose value
|
|
contains the XPath expression in question, and the term
|
|
<b>enclosing element</b> means the containing element or any of its
|
|
ancestors.</p>
|
|
<ul>
|
|
<li>
|
|
<p><a title="XPath 1.0 compatibility mode" class="termref" href=
|
|
"#dt-xpath-compat-mode">XPath 1.0 compatibility mode</a> is set to
|
|
true if and only if the containing element is processed with
|
|
<a title="XSLT 1.0 behavior" class="termref" href=
|
|
"#dt-xslt-10-behavior">XSLT 1.0 behavior</a> (see <a href=
|
|
"#backwards"><i>3.8 Backwards Compatible Processing</i></a>).</p>
|
|
</li>
|
|
<li>
|
|
<p>The <a href=
|
|
"http://www.w3.org/TR/xpath-21/#dt-static-namespaces">statically
|
|
known namespaces</a><sup><small>XP21</small></sup> are the
|
|
namespace declarations that are in scope for the containing
|
|
element.</p>
|
|
</li>
|
|
<li>
|
|
<p>The <a href=
|
|
"http://www.w3.org/TR/xpath-21/#dt-def-elemtype-ns">default
|
|
element/type namespace</a><sup><small>XP21</small></sup> is the
|
|
namespace defined by the <code>[xsl:]xpath-default-namespace</code>
|
|
attribute on the innermost enclosing element that has such an
|
|
attribute, as described in <a href="#unprefixed-qnames"><i>5.2
|
|
Unprefixed QNames in Expressions and Patterns</i></a>. The value of
|
|
this attribute is a namespace URI. If there is no
|
|
<code>[xsl:]xpath-default-namespace</code> attribute on an
|
|
enclosing element, the default namespace for element names and type
|
|
names is the null namespace.</p>
|
|
</li>
|
|
<li>
|
|
<p>The <a href=
|
|
"http://www.w3.org/TR/xpath-21/#dt-def-fn-ns">default function
|
|
namespace</a><sup><small>XP21</small></sup> is the <a title=
|
|
"standard function namespace" class="termref" href=
|
|
"#dt-standard-function-namespace">standard function namespace</a>,
|
|
defined in <a href="#xpath-functions-11">[Functions and
|
|
Operators]</a>. This means that it is not necessary to declare this
|
|
namespace in the <a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a>, nor is it necessary to use the
|
|
prefix <code>fn</code> (or any other prefix) in calls to the
|
|
<a title="core function" class="termref" href=
|
|
"#dt-core-function">core functions</a>.</p>
|
|
</li>
|
|
<li>
|
|
<p>The <a href="http://www.w3.org/TR/xpath-21/#dt-issd">in-scope
|
|
schema definitions</a><sup><small>XP21</small></sup> for the XPath
|
|
expression are the same as the <a title="in-scope schema component"
|
|
class="termref" href="#dt-in-scope-schema-component">in-scope
|
|
schema components</a> for the <a title="stylesheet" class="termref"
|
|
href="#dt-stylesheet">stylesheet</a>, and are as specified in
|
|
<a href="#built-in-types"><i>3.13 Built-in Types</i></a>.</p>
|
|
</li>
|
|
<li>
|
|
<p>The <a href=
|
|
"http://www.w3.org/TR/xpath-21/#dt-in-scope-variables">in-scope
|
|
variables</a><sup><small>XP21</small></sup> are defined by the
|
|
<a title="variable-binding element" class="termref" href=
|
|
"#dt-variable-binding-element">variable binding elements</a> that
|
|
are in scope for the containing element (see <a href=
|
|
"#variables-and-parameters"><i>9 Variables and
|
|
Parameters</i></a>).</p>
|
|
</li>
|
|
<li>
|
|
<p>The <a href=
|
|
"http://www.w3.org/TR/xpath-21/#dt-context-item-static-type">context
|
|
item static type</a><sup><small>XP21</small></sup> may be
|
|
determined by an XSLT processor that performs static type
|
|
inferencing, using rules that are outside the scope of this
|
|
specification; if no static type inferencing is done, then the
|
|
context item static type for every XPath expression is
|
|
<code>item()</code>.</p>
|
|
</li>
|
|
<li>
|
|
<p>The <a href=
|
|
"http://www.w3.org/TR/xpath-21/#dt-function-signature">function
|
|
signatures</a><sup><small>XP21</small></sup> are the <a title=
|
|
"core function" class="termref" href="#dt-core-function">core
|
|
functions</a> defined in <a href="#xpath-functions-11">[Functions
|
|
and Operators]</a>, the constructor functions for all the atomic
|
|
types in the <a href=
|
|
"http://www.w3.org/TR/xpath-21/#dt-issd">in-scope schema
|
|
definitions</a><sup><small>XP21</small></sup>, the additional
|
|
functions defined in this specification, the <a title=
|
|
"stylesheet function" class="termref" href=
|
|
"#dt-stylesheet-function">stylesheet functions</a> defined in the
|
|
stylesheet, plus any <a title="extension function" class="termref"
|
|
href="#dt-extension-function">extension functions</a> bound using
|
|
<a title="implementation-defined" class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a> mechanisms
|
|
(see <a href="#extension"><i>21 Extensibility and
|
|
Fallback</i></a>).</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>It follows from the above that a conformant XSLT processor must
|
|
implement the entire library of <a title="core function" class=
|
|
"termref" href="#dt-core-function">core functions</a> defined in
|
|
<a href="#xpath-functions-11">[Functions and Operators]</a>.</p>
|
|
</div>
|
|
</li>
|
|
<li>
|
|
<p>The <a href=
|
|
"http://www.w3.org/TR/xpath-21/#dt-static-collations">statically
|
|
known collations</a><sup><small>XP21</small></sup> are <a title=
|
|
"implementation-defined" class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a>. However,
|
|
the set of in-scope collations <span class="verb">must</span>
|
|
always include the Unicode codepoint collation, defined in <a href=
|
|
"http://www.w3.org/TR/xpath-functions/#string-compare">Section 7.3
|
|
Equality and Comparison of
|
|
Strings</a><sup><small>FO</small></sup>.</p>
|
|
</li>
|
|
<li>
|
|
<p>The <a href=
|
|
"http://www.w3.org/TR/xpath-21/#dt-def-collation">default
|
|
collation</a><sup><small>XP21</small></sup> is defined by the value
|
|
of the <code>[xsl:]default-collation</code> attribute on the
|
|
innermost enclosing element that has such an attribute. For
|
|
details, see <a href="#default-collation-attribute"><i>3.6.1 The
|
|
default-collation attribute</i></a>.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-default-collation" id="dt-default-collation" title=
|
|
"default collation"></a>In this specification the term <b>default
|
|
collation</b> means the collation that is used by XPath operators
|
|
such as <code>eq</code> and <code>lt</code> appearing in XPath
|
|
expressions within the stylesheet.<span class=
|
|
"definition">]</span></p>
|
|
<p>This collation is also used by default when comparing strings in
|
|
the evaluation of the <a href=
|
|
"#element-key"><code>xsl:key</code></a> and <a href=
|
|
"#element-for-each-group"><code>xsl:for-each-group</code></a>
|
|
elements. This <span class="verb">may</span> also (but need not
|
|
necessarily) be the same as the default collation used for <a href=
|
|
"#element-sort"><code>xsl:sort</code></a> elements within the
|
|
stylesheet. Collations used by <a href=
|
|
"#element-sort"><code>xsl:sort</code></a> are described in <a href=
|
|
"#collating-sequences"><i>13.1.3 Sorting Using
|
|
Collations</i></a>.</p>
|
|
</li>
|
|
<li>
|
|
<p>The <a href="http://www.w3.org/TR/xpath-21/#dt-base-uri">base
|
|
URI</a><sup><small>XP21</small></sup> is the base URI of the
|
|
containing element in the stylesheet. The concept of the base URI
|
|
of a node is defined in <a href=
|
|
"http://www.w3.org/TR/xpath-datamodel-11/#dm-base-uri">Section 5.2
|
|
base-uri Accessor</a><sup><small>DM11</small></sup></p>
|
|
</li>
|
|
<li>
|
|
<p>The set of <a href=
|
|
"http://www.w3.org/TR/xpath-21/#dt-known-docs">statically known
|
|
documents</a><sup><small>XP21</small></sup> is <a title=
|
|
"implementation-defined" class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a>, and by
|
|
default is empty.</p>
|
|
</li>
|
|
<li>
|
|
<p>The set of <a href=
|
|
"http://www.w3.org/TR/xpath-21/#dt-known-collections">statically
|
|
known collections</a><sup><small>XP21</small></sup> is <a title=
|
|
"implementation-defined" class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a>, and by
|
|
default is empty.</p>
|
|
</li>
|
|
<li>
|
|
<p>The <a href=
|
|
"http://www.w3.org/TR/xpath-21/#dt-known-default-collection">statically
|
|
known default collection type</a><sup><small>XP21</small></sup> is
|
|
<a title="implementation-defined" class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a>, and by
|
|
default is <code>node()*</code>.</p>
|
|
</li>
|
|
<li>
|
|
<p>The set of <a href=
|
|
"http://www.w3.org/TR/xpath-21/#dt-static-decimal-formats">statically
|
|
known decimal formats</a><sup><small>XP21</small></sup> is the set
|
|
of decimal formats defined by <a href=
|
|
"#element-decimal-format"><code>xsl:decimal-format</code></a>
|
|
declarations in the stylesheet.</p>
|
|
</li>
|
|
</ul>
|
|
<blockquote>
|
|
<p><b><a name="issue-recommended-initial-context" id=
|
|
"issue-recommended-initial-context">Issue 5
|
|
(recommended-initial-context)</a>:</b></p>
|
|
<p>In the rules for defining the initial static context, we
|
|
sometimes say that the value is implementation-defined, and then
|
|
give a default. We need to be clearer what we are saying here.
|
|
Essentially the "default" is a recommendation to implementors about
|
|
what the value should be when users don't select anything
|
|
different. Perhaps if we have recommended defaults for some of
|
|
these values, we should have them for all.</p>
|
|
</blockquote>
|
|
</div>
|
|
<div class="div3">
|
|
<h4><a name="additional-static-context" id=
|
|
"additional-static-context"></a>5.4.2 <a href=
|
|
"#additional-static-context" style=
|
|
"text-decoration: none">Additional Static Context Components used
|
|
by XSLT</a></h4>
|
|
<p>Some of the components of the XPath static context are used also
|
|
by <a title="XSLT element" class="termref" href=
|
|
"#dt-xslt-element">XSLT elements</a>. For example, the <a href=
|
|
"#element-sort"><code>xsl:sort</code></a> element makes use of the
|
|
collations defined in the static context, and attributes such as
|
|
<code>type</code> and <code>as</code> may reference types defined
|
|
in the <a title="in-scope schema component" class="termref" href=
|
|
"#dt-in-scope-schema-component">in-scope schema components</a>.</p>
|
|
<p>Many top-level declarations in a stylesheet, and attributes on
|
|
the <a href="#element-stylesheet"><code>xsl:stylesheet</code></a>
|
|
element, affect the behavior of instructions within the stylesheet.
|
|
Each of these constructs is described in its appropriate place in
|
|
this specification.</p>
|
|
<p>A number of these constructs are of particular significance
|
|
because they are used by functions defined in XSLT, which are added
|
|
to the library of functions available for use in XPath expressions
|
|
within the stylesheet. These are:</p>
|
|
<ul>
|
|
<li>
|
|
<p>The set of named keys, used by the <a href=
|
|
"#function-key"><code>key</code></a> function</p>
|
|
</li>
|
|
<li>
|
|
<p>The values of system properties, used by the <a href=
|
|
"#function-system-property"><code>system-property</code></a>
|
|
function</p>
|
|
</li>
|
|
<li>
|
|
<p>The set of available instructions, used by the <a href=
|
|
"#function-element-available"><code>element-available</code></a>
|
|
function</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div class="div3">
|
|
<h4><a name="xpath-dynamic-context" id=
|
|
"xpath-dynamic-context"></a>5.4.3 <a href="#xpath-dynamic-context"
|
|
style="text-decoration: none">Initializing the Dynamic
|
|
Context</a></h4>
|
|
<p>For convenience, the dynamic context is described in two parts:
|
|
the <a title="focus" class="termref" href="#dt-focus">focus</a>,
|
|
which represents the place in the source document that is currently
|
|
being processed, and a collection of additional context
|
|
variables.</p>
|
|
<p>A number of functions specified in <a href=
|
|
"#xpath-functions-11">[Functions and Operators]</a> are defined to
|
|
be <a href=
|
|
"http://www.w3.org/TR/xpath-functions/#stable">stable</a><sup><small>FO</small></sup>,
|
|
meaning that if they are called twice during the same <a href=
|
|
"http://www.w3.org/TR/xpath-functions/#execution-scope">execution
|
|
scope</a><sup><small>FO</small></sup>, with the same arguments,
|
|
then they return the same results (see <a href=
|
|
"http://www.w3.org/TR/xpath-functions/#terminology">Section 1.7
|
|
Terminology</a><sup><small>FO</small></sup>). In XSLT, the
|
|
execution of a stylesheet defines the execution scope. This means,
|
|
for example, that if the function <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-current-dateTime"><code>
|
|
current-dateTime</code></a><sup><small>FO</small></sup> is called
|
|
repeatedly during a transformation, it produces the same result
|
|
each time. By implication, the components of the dynamic context on
|
|
which these functions depend are also stable for the duration of
|
|
the transformation. Specifically, the following components defined
|
|
in <a href="http://www.w3.org/TR/xpath-21/#eval_context">Section
|
|
2.1.2 Dynamic Context</a><sup><small>XP21</small></sup> must be
|
|
stable: <em>function implementations</em>, <em>current
|
|
dateTime</em>, <em>implicit timezone</em>, <em>available
|
|
documents</em>, <em>available collections</em>, and <em>default
|
|
collection</em>. The values of global variables and stylesheet
|
|
parameters are also stable for the duration of a transformation.
|
|
The focus is <em>not</em> stable; the additional dynamic context
|
|
components defined in <a href=
|
|
"#additional-dynamic-context"><i>5.4.4 Additional Dynamic Context
|
|
Components used by XSLT</i></a> are also <em>not</em> stable.</p>
|
|
<p>As specified in <a href="#xpath-functions-11">[Functions and
|
|
Operators]</a>, implementations may provide user options that relax
|
|
the requirement for the <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-doc"><code>doc</code></a><sup><small>FO</small></sup>
|
|
and <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-collection"><code>collection</code></a><sup><small>FO</small></sup>
|
|
functions (and therefore, by implication, the <a href=
|
|
"#function-document"><code>document</code></a> function) to return
|
|
stable results. By default, however, the functions must be stable.
|
|
The manner in which such user options are provided, if at all, is
|
|
<a title="implementation-defined" class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a>.</p>
|
|
<p>XPath expressions contained in <code>[xsl:]use-when</code>
|
|
attributes are not considered to be evaluated "during the
|
|
transformation" as defined above. For details see <a href=
|
|
"#conditional-inclusion"><i>3.12 Conditional Element
|
|
Inclusion</i></a>.</p>
|
|
<div class="div4">
|
|
<h5><a name="focus" id="focus"></a>5.4.3.1 <a href="#focus" style=
|
|
"text-decoration: none">Maintaining Position: the Focus</a></h5>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-focus" id="dt-focus" title="focus"></a>When a <a title=
|
|
"sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> is evaluated,
|
|
the <a title="processor" class="termref" href=
|
|
"#dt-processor">processor</a> keeps track of which items are being
|
|
processed by means of a set of implicit variables referred to
|
|
collectively as the <b>focus</b>.<span class="definition">]</span>
|
|
More specifically, the focus consists of the following three
|
|
values:</p>
|
|
<ul>
|
|
<li>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-context-item" id="dt-context-item" title="context item"></a>The
|
|
<b>context item</b> is the item currently being processed. An item
|
|
(see <a href="#xpath-datamodel-11">[Data Model]</a>) is either an
|
|
atomic value (such as an integer, date, or string), a node,
|
|
<span>or a function item</span>. The context item is initially set
|
|
to the <span><a title="initial context item" class="termref" href=
|
|
"#dt-initial-context-item">initial context item</a></span> supplied
|
|
when the transformation is invoked (see <a href=
|
|
"#initiating"><i>2.3 Initiating a Transformation</i></a>). It
|
|
changes whenever instructions such as <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a> and
|
|
<a href="#element-for-each"><code>xsl:for-each</code></a> are used
|
|
to process a sequence of items; each item in such a sequence
|
|
becomes the context item while that item is being
|
|
processed.<span class="definition">]</span> The context item is
|
|
returned by the XPath <a title="expression" class="termref" href=
|
|
"#dt-expression">expression</a> <code>.</code> (dot).</p>
|
|
</li>
|
|
<li>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-context-position" id="dt-context-position" title=
|
|
"context position"></a>The <b>context position</b> 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 <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a> or
|
|
<a href="#element-for-each"><code>xsl:for-each</code></a> 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.<span class="definition">]</span>
|
|
The context position is returned by the XPath <a title="expression"
|
|
class="termref" href="#dt-expression">expression</a>
|
|
<code>position()</code>.</p>
|
|
</li>
|
|
<li>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-context-size" id="dt-context-size" title="context size"></a>The
|
|
<b>context size</b> is the number of items in the sequence of items
|
|
currently being processed. It changes whenever instructions such as
|
|
<a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a> and
|
|
<a href="#element-for-each"><code>xsl:for-each</code></a> 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).<span class="definition">]</span> The context
|
|
size is returned by the XPath <a title="expression" class="termref"
|
|
href="#dt-expression">expression</a> <code>last()</code>.</p>
|
|
</li>
|
|
</ul>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-context-node" id="dt-context-node" title="context node"></a>If
|
|
the <a title="context item" class="termref" href=
|
|
"#dt-context-item">context item</a> is a node (as distinct from an
|
|
atomic value such as an integer), then it is also referred to as
|
|
the <b>context node</b>. The context node is not an independent
|
|
variable, it changes whenever the context item changes. When the
|
|
context item is an atomic value <span>or a function item</span>,
|
|
there is no context node.<span class="definition">]</span> The
|
|
context node is returned by the XPath <a title="expression" class=
|
|
"termref" href="#dt-expression">expression</a>
|
|
<code>self::node()</code>, and it is used as the starting node for
|
|
all relative path expressions.</p>
|
|
<p>Where the containing element of an XPath expression is an
|
|
<a title="instruction" class="termref" href=
|
|
"#dt-instruction">instruction</a> or a <a title=
|
|
"literal result element" class="termref" href=
|
|
"#dt-literal-result-element">literal result element</a>, the
|
|
initial context item, context position, and context size for the
|
|
XPath <a title="expression" class="termref" href=
|
|
"#dt-expression">expression</a> are the same as the <a title=
|
|
"context item" class="termref" href="#dt-context-item">context
|
|
item</a>, <a title="context position" class="termref" href=
|
|
"#dt-context-position">context position</a>, and <a title=
|
|
"context size" class="termref" href="#dt-context-size">context
|
|
size</a> for the evaluation of the containing instruction or
|
|
literal result element.</p>
|
|
<p>In other cases (for example, where the containing element is
|
|
<a href="#element-sort"><code>xsl:sort</code></a>, <a href=
|
|
"#element-with-param"><code>xsl:with-param</code></a>, or <a href=
|
|
"#element-key"><code>xsl:key</code></a>), the rules are given in
|
|
the specification of the containing element.</p>
|
|
<p>The <a href="#function-current"><code>current</code></a>
|
|
function can be used within any XPath <a title="expression" class=
|
|
"termref" href="#dt-expression">expression</a> to select the item
|
|
that was supplied as the context item to the XPath expression by
|
|
the XSLT processor. Unlike <code>.</code> (dot) this is unaffected
|
|
by changes to the context item that occur within the XPath
|
|
expression. The <a href=
|
|
"#function-current"><code>current</code></a> function is described
|
|
in <a href="#current-function"><i>19.5.1 current</i></a>.</p>
|
|
<p>On completion of an instruction that changes the <a title=
|
|
"focus" class="termref" href="#dt-focus">focus</a> (such as
|
|
<a href="#element-apply-templates"><code>xsl:apply-templates</code></a>
|
|
or <a href="#element-for-each"><code>xsl:for-each</code></a>), the
|
|
focus reverts to its previous value.</p>
|
|
<p>When a <a title="stylesheet function" class="termref" href=
|
|
"#dt-stylesheet-function">stylesheet function</a> is called, the
|
|
focus within the body of the function is initially undefined. The
|
|
focus is also undefined on initial entry to the <a title=
|
|
"stylesheet" class="termref" href="#dt-stylesheet">stylesheet</a>
|
|
if no <span><a title="initial context item" class="termref" href=
|
|
"#dt-initial-context-item">initial context item</a></span> is
|
|
supplied.</p>
|
|
<p>When the focus is undefined, evaluation of any <a title=
|
|
"expression" class="termref" href="#dt-expression">expression</a>
|
|
that references the context item, context position, or context size
|
|
results in a <a title="non-recoverable dynamic error" class=
|
|
"termref" href="#dt-nonrec-dynamic-error">non-recoverable dynamic
|
|
error</a> [XPDY0002]</p>
|
|
<p>The description above gives an outline of the way the <a title=
|
|
"focus" class="termref" href="#dt-focus">focus</a> 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.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-singleton-focus" id="dt-singleton-focus" title=
|
|
"singleton focus"></a>A <b>singleton focus</b> based on an item
|
|
<var>J</var> has the <span><a title="context item" class="termref"
|
|
href="#dt-context-item">context item</a> (and therefore the
|
|
<a title="context node" class="termref" href=
|
|
"#dt-context-node">context node</a>, if <var>J</var> is a
|
|
node)</span> set to <var>J</var>, and the <a title=
|
|
"context position" class="termref" href=
|
|
"#dt-context-position">context position</a> and <a title=
|
|
"context size" class="termref" href="#dt-context-size">context
|
|
size</a> both set to 1 (one).<span class="definition">]</span></p>
|
|
</div>
|
|
<div class="div4">
|
|
<h5><a name="evaluation-context" id=
|
|
"evaluation-context"></a>5.4.3.2 <a href="#evaluation-context"
|
|
style="text-decoration: none">Other components of the XPath Dynamic
|
|
Context</a></h5>
|
|
<p>The previous section explained how the <a title="focus" class=
|
|
"termref" href="#dt-focus">focus</a> for an XPath expression
|
|
appearing in an XSLT stylesheet is initialized. This section
|
|
explains how the other components of the <a href=
|
|
"http://www.w3.org/TR/xpath-21/#dt-dynamic-context">dynamic
|
|
context</a><sup><small>XP21</small></sup> of an XPath expression
|
|
are initialized.</p>
|
|
<ul>
|
|
<li>
|
|
<p>The <a href=
|
|
"http://www.w3.org/TR/xpath-21/#dt-variable-values">dynamic
|
|
variables</a><sup><small>XP21</small></sup> are the current values
|
|
of the in-scope <a title="variable-binding element" class="termref"
|
|
href="#dt-variable-binding-element">variable binding
|
|
elements</a>.</p>
|
|
</li>
|
|
<li>
|
|
<p>The <em>current date and time</em> represents an <a title=
|
|
"implementation-dependent" class="termref" href=
|
|
"#dt-implementation-dependent">implementation-dependent</a> point
|
|
in time during processing of the transformation; it does not change
|
|
during the course of the transformation.</p>
|
|
</li>
|
|
<li>
|
|
<p>The <a href=
|
|
"http://www.w3.org/TR/xpath-21/#dt-timezone">implicit
|
|
timezone</a><sup><small>XP21</small></sup> is <a title=
|
|
"implementation-defined" class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a>.</p>
|
|
</li>
|
|
<li>
|
|
<p>The <a href=
|
|
"http://www.w3.org/TR/xpath-21/#dt-known-docs">available
|
|
documents</a><sup><small>XP21</small></sup>, and the <a href=
|
|
"http://www.w3.org/TR/xpath-21/#dt-known-collections">available
|
|
collections</a><sup><small>XP21</small></sup> are determined as
|
|
part of the process for initiating a transformation (see <a href=
|
|
"#initiating"><i>2.3 Initiating a Transformation</i></a>).</p>
|
|
<p>The <a href=
|
|
"http://www.w3.org/TR/xpath-21/#dt-known-docs">available
|
|
documents</a><sup><small>XP21</small></sup> are defined as part of
|
|
the <span>XPath 2.1</span> dynamic context to support the <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-doc"><code>doc</code></a><sup><small>FO</small></sup>
|
|
function, but this component is also referenced by the similar XSLT
|
|
<a href="#function-document"><code>document</code></a> function:
|
|
see <a href="#document"><i>19.1.1 The document function</i></a>.
|
|
This variable defines a mapping between URIs passed to the <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-doc"><code>doc</code></a><sup><small>FO</small></sup>
|
|
or <a href="#function-document"><code>document</code></a> function
|
|
and the document nodes that are returned.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>Defining this as part of the evaluation context is a formal way
|
|
of specifying that the way in which URIs get turned into document
|
|
nodes is outside the control of the language specification, and
|
|
depends entirely on the run-time environment in which the
|
|
transformation takes place.</p>
|
|
</div>
|
|
<p>The XSLT-defined <a href=
|
|
"#function-document"><code>document</code></a> function allows the
|
|
use of URI references containing fragment identifiers. The
|
|
interpretation of a fragment identifier depends on the media type
|
|
of the resource representation. Therefore, the information supplied
|
|
in <a href="http://www.w3.org/TR/xpath-21/#dt-known-docs">available
|
|
documents</a><sup><small>XP21</small></sup> for XSLT processing
|
|
must provide not only a mapping from URIs to document nodes as
|
|
required by XPath, but also a mapping from URIs to media types.</p>
|
|
</li>
|
|
<li>
|
|
<p>The <a href=
|
|
"http://www.w3.org/TR/xpath-21/#dt-default-collection">default
|
|
collection</a><sup><small>XP21</small></sup> is <a title=
|
|
"implementation-defined" class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a>. This
|
|
allows options such as setting the default collection to be an
|
|
empty sequence, or to be undefined.</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
<div class="div3">
|
|
<h4><a name="additional-dynamic-context" id=
|
|
"additional-dynamic-context"></a>5.4.4 <a href=
|
|
"#additional-dynamic-context" style=
|
|
"text-decoration: none">Additional Dynamic Context Components used
|
|
by XSLT</a></h4>
|
|
<p>In addition to the values that make up the <a title="focus"
|
|
class="termref" href="#dt-focus">focus</a>, an XSLT processor
|
|
maintains a number of other dynamic context components that reflect
|
|
aspects of the evaluation context. These components are fully
|
|
described in the sections of the specification that maintain and
|
|
use them. They are:</p>
|
|
<ul>
|
|
<li>
|
|
<p>The <a title="current template rule" class="termref" href=
|
|
"#dt-current-template-rule">current template rule</a>, which is the
|
|
<a title="template rule" class="termref" href=
|
|
"#dt-template-rule">template rule</a> most recently invoked by an
|
|
<a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>,
|
|
<a href=
|
|
"#element-apply-imports"><code>xsl:apply-imports</code></a>, or
|
|
<a href="#element-next-match"><code>xsl:next-match</code></a>
|
|
instruction: see <a href="#apply-imports"><i>6.8 Overriding
|
|
Template Rules</i></a>;</p>
|
|
</li>
|
|
<li>
|
|
<p>The <a title="current mode" class="termref" href=
|
|
"#dt-current-mode">current mode</a>, which is the <a title="mode"
|
|
class="termref" href="#dt-mode">mode</a> set by the most recent
|
|
call of <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>
|
|
(for a full definition see <a href="#modes"><i>6.6
|
|
Modes</i></a>);</p>
|
|
</li>
|
|
<li>
|
|
<p>The <a title="current group" class="termref" href=
|
|
"#dt-current-group">current group</a> and <a title=
|
|
"current grouping key" class="termref" href=
|
|
"#dt-current-grouping-key">current grouping key</a>, which provide
|
|
information about the collection of items currently being processed
|
|
by an <a href=
|
|
"#element-for-each-group"><code>xsl:for-each-group</code></a>
|
|
instruction: see <a href="#current-group"><i>14.1 The Current
|
|
Group</i></a> and <a href="#current-grouping-key"><i>14.2 The
|
|
Current Grouping Key</i></a>;</p>
|
|
</li>
|
|
<li>
|
|
<p>The <a title="current captured substrings" class="termref" href=
|
|
"#dt-current-captured-substrings">current captured substrings</a>:
|
|
this is a sequence of strings, which is maintained when a string is
|
|
matched against a regular expression using the <a href=
|
|
"#element-analyze-string"><code>xsl:analyze-string</code></a>
|
|
instruction, and which is accessible using the <a href=
|
|
"#function-regex-group"><code>regex-group</code></a> function: see
|
|
<a href="#regex-group"><i>17.2 Captured Substrings</i></a>.</p>
|
|
</li>
|
|
<li>
|
|
<p>The <a title="output state" class="termref" href=
|
|
"#dt-output-state">output state</a>: this is a flag whose two
|
|
possible values are <a title="final output state" class="termref"
|
|
href="#dt-final-output-state">final output state</a> and <a title=
|
|
"temporary output state" class="termref" href=
|
|
"#dt-temporary-output-state">temporary output state</a>. This flag
|
|
indicates whether instructions are currently writing to a <a title=
|
|
"final result tree" class="termref" href=
|
|
"#dt-final-result-tree">final result tree</a> or to an internal
|
|
data structure. The initial setting is <a title=
|
|
"final output state" class="termref" href=
|
|
"#dt-final-output-state">final output state</a>, and it is switched
|
|
to <a title="temporary output state" class="termref" href=
|
|
"#dt-temporary-output-state">temporary output state</a> by
|
|
instructions such as <a href=
|
|
"#element-variable"><code>xsl:variable</code></a>. For more
|
|
details, see <a href="#creating-result-trees"><i>22.1 Creating
|
|
Final Result Trees</i></a>.</p>
|
|
</li>
|
|
</ul>
|
|
<p>The following non-normative table summarizes the initial state
|
|
of each of the components in the evaluation context, and the
|
|
instructions which cause the state of the component to change.</p>
|
|
<blockquote>
|
|
<p><b><a name="issue-normative-evaluation-context" id=
|
|
"issue-normative-evaluation-context">Issue 6
|
|
(normative-evaluation-context)</a>:</b></p>
|
|
<p>Although this table is described as non-normative, it may be
|
|
more complete than the same information given normatively
|
|
elsewhere.</p>
|
|
</blockquote>
|
|
<table border="1" cellpadding="5">
|
|
<thead>
|
|
<tr>
|
|
<th align="left" colspan="1">Component</th>
|
|
<th align="left" colspan="1">Initial Setting</th>
|
|
<th align="left" colspan="1">Set by</th>
|
|
<th align="left" colspan="1">Cleared by</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td valign="top"><a title="focus" class="termref" href=
|
|
"#dt-focus">focus</a></td>
|
|
<td valign="top">singleton focus based on the <span><a title=
|
|
"initial context item" class="termref" href=
|
|
"#dt-initial-context-item">initial context item</a></span> if
|
|
supplied</td>
|
|
<td valign="top"><a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>,
|
|
<a href="#element-for-each"><code>xsl:for-each</code></a>, <a href=
|
|
"#element-for-each-group"><code>xsl:for-each-group</code></a>,
|
|
<a href=
|
|
"#element-analyze-string"><code>xsl:analyze-string</code></a></td>
|
|
<td valign="top"><a title="non-contextual function call" class=
|
|
"termref" href="#dt-non-contextual-function-call">non-contextual
|
|
function calls</a></td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top"><a title="current template rule" class="termref"
|
|
href="#dt-current-template-rule">current template rule</a></td>
|
|
<td valign="top">If a <a title="named template" class="termref"
|
|
href="#dt-named-template">named template</a> is supplied as the
|
|
entry point to the transformation, then null; otherwise the
|
|
<a title="initial template" class="termref" href=
|
|
"#dt-initial-template">initial template</a></td>
|
|
<td valign="top"><a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>,
|
|
<a href=
|
|
"#element-apply-imports"><code>xsl:apply-imports</code></a>,
|
|
<a href="#element-next-match"><code>xsl:next-match</code></a></td>
|
|
<td valign="top"><a href=
|
|
"#element-for-each"><code>xsl:for-each</code></a>, <a href=
|
|
"#element-for-each-group"><code>xsl:for-each-group</code></a>,
|
|
<a href=
|
|
"#element-analyze-string"><code>xsl:analyze-string</code></a>,
|
|
<span><a href="#element-iterate"><code>xsl:iterate</code></a>,
|
|
<a href="#element-stream"><code>xsl:stream</code></a>, <a href=
|
|
"#element-merge"><code>xsl:merge</code></a>, <a href=
|
|
"#element-evaluate"><code>xsl:evaluate</code></a>,</span> and
|
|
<a title="non-contextual function call" class="termref" href=
|
|
"#dt-non-contextual-function-call">non-contextual function
|
|
calls</a>. Also cleared while evaluating global variables or
|
|
default values of stylesheet parameters, and the sequence
|
|
constructors contained in <a href=
|
|
"#element-key"><code>xsl:key</code></a> and <a href=
|
|
"#element-sort"><code>xsl:sort</code></a>.</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top"><a title="current mode" class="termref" href=
|
|
"#dt-current-mode">current mode</a></td>
|
|
<td valign="top">the initial <a title="mode" class="termref" href=
|
|
"#dt-mode">mode</a></td>
|
|
<td valign="top"><a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a></td>
|
|
<td valign="top"><a title="non-contextual function call" class=
|
|
"termref" href="#dt-non-contextual-function-call">non-contextual
|
|
function calls</a>, evaluation of global variables and stylesheet
|
|
parameters, evaluation of the sequence constructor contained in
|
|
<a href="#element-key"><code>xsl:key</code></a> or <a href=
|
|
"#element-sort"><code>xsl:sort</code></a>. Clearing the current
|
|
mode causes the current mode to be set to the default (unnamed)
|
|
mode.</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top"><a title="current group" class="termref" href=
|
|
"#dt-current-group">current group</a></td>
|
|
<td valign="top">empty sequence</td>
|
|
<td valign="top"><a href=
|
|
"#element-for-each-group"><code>xsl:for-each-group</code></a></td>
|
|
<td valign="top"><a title="non-contextual function call" class=
|
|
"termref" href="#dt-non-contextual-function-call">non-contextual
|
|
function calls</a></td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top"><a title="current grouping key" class="termref"
|
|
href="#dt-current-grouping-key">current grouping key</a></td>
|
|
<td valign="top">empty sequence</td>
|
|
<td valign="top"><a href=
|
|
"#element-for-each-group"><code>xsl:for-each-group</code></a></td>
|
|
<td valign="top"><a title="non-contextual function call" class=
|
|
"termref" href="#dt-non-contextual-function-call">non-contextual
|
|
function calls</a></td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top"><a title="current captured substrings" class=
|
|
"termref" href="#dt-current-captured-substrings">current captured
|
|
substrings</a></td>
|
|
<td valign="top">empty sequence</td>
|
|
<td valign="top"><a href=
|
|
"#element-matching-substring"><code>xsl:matching-substring</code></a></td>
|
|
<td valign="top"><a href=
|
|
"#element-non-matching-substring"><code>xsl:non-matching-substring</code></a>;
|
|
<span><a title="non-contextual function call" class="termref" href=
|
|
"#dt-non-contextual-function-call">non-contextual function
|
|
calls</a></span></td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top"><a title="output state" class="termref" href=
|
|
"#dt-output-state">output state</a></td>
|
|
<td valign="top"><a title="final output state" class="termref"
|
|
href="#dt-final-output-state">final output state</a></td>
|
|
<td valign="top">Set to <a title="temporary output state" class=
|
|
"termref" href="#dt-temporary-output-state">temporary output
|
|
state</a> by instructions such as <a href=
|
|
"#element-variable"><code>xsl:variable</code></a>, <a href=
|
|
"#element-attribute"><code>xsl:attribute</code></a>, etc., and by
|
|
calls on <a title="stylesheet function" class="termref" href=
|
|
"#dt-stylesheet-function">stylesheet functions</a></td>
|
|
<td valign="top">None</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-non-contextual-function-call" id=
|
|
"dt-non-contextual-function-call" title=
|
|
"non-contextual function call"></a>The term <b>non-contextual
|
|
function call</b> is used to refer to function calls that do not
|
|
pass the dynamic context to the called function. This includes all
|
|
calls on <a title="stylesheet function" class="termref" href=
|
|
"#dt-stylesheet-function">stylesheet functions</a> and all [TERMDEF
|
|
dt-dynamic-func-invoke IN XP21]dynamic function invocations, (that
|
|
is calls to function items as permitted by XPath 2.1). It does not
|
|
include calls to all <a title="core function" class="termref" href=
|
|
"#dt-core-function">core functions</a> in particular those that
|
|
explicitly depend on the context, such as the <a href=
|
|
"#function-current-group"><code>current-group</code></a> and
|
|
<a href="#function-regex-group"><code>regex-group</code></a>
|
|
functions. It is <a title="implementation-defined" class="termref"
|
|
href="#dt-implementation-defined">implementation-defined</a>
|
|
whether, and under what circumstances, calls to <a title=
|
|
"extension function" class="termref" href=
|
|
"#dt-extension-function">extension functions</a> are
|
|
non-contextual.<span class="definition">]</span></p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>A consequence of these rules is that whereas the function call
|
|
<code>current-group()</code> returns the contents of the <a title=
|
|
"current group" class="termref" href="#dt-current-group">current
|
|
group</a>, the dynamic function invocation
|
|
<code>current-group#0()</code> always returns the empty
|
|
sequence.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="patterns" id="patterns"></a>5.5 <a href="#patterns"
|
|
style="text-decoration: none">Patterns</a></h3>
|
|
<p>In XSLT 2.1, patterns can match any kind of item: atomic values
|
|
and function items as well as nodes.</p>
|
|
<p>A <a title="template rule" class="termref" href=
|
|
"#dt-template-rule">template rule</a> identifies the
|
|
<span>items</span> to which it applies by means of a pattern. As
|
|
well as being used in template rules, patterns are used for
|
|
numbering (see <a href="#number"><i>12 Numbering</i></a>), for
|
|
grouping (see <a href="#grouping"><i>14 Grouping</i></a>), and for
|
|
declaring <a title="" class="termref" href="#key">keys</a> (see
|
|
<a href="#key"><i>19.3 Keys</i></a>).</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-pattern" id="dt-pattern" title="pattern"></a>A <b>pattern</b>
|
|
specifies a set of conditions on an <span>item</span>. An
|
|
<span>item</span> that satisfies the conditions matches the
|
|
pattern; an <span>item</span> that does not satisfy the conditions
|
|
does not match the pattern.<span class="definition">]</span></p>
|
|
<p>There are two basic kinds of pattern: type patterns, and path
|
|
patterns. Patterns may also be formed by combining other patterns
|
|
using union, intersection, and difference operators.</p>
|
|
<p>A type pattern is written with a leading <code>~</code> (tilde)
|
|
followed by an <a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-ItemType">ItemType</a><sup><small>XP21</small></sup>
|
|
and an optional list of predicates: for example,
|
|
<code>~xs:anyAtomicValue</code> matches any atomic value,
|
|
<code>~xs:integer[. mod 2 = 0]</code> matches any even integer,
|
|
<code>~node()</code> matches any node, and
|
|
<code>~function()[empty(function-name(.))]</code> matches any
|
|
function item that refers to an anonymous function. An item matches
|
|
a type pattern if and only if the item is an instance of the
|
|
specified type and satisfies all the predicates.</p>
|
|
<p>The syntax for <span>path</span> patterns is a subset of the
|
|
syntax for <a title="expression" class="termref" href=
|
|
"#dt-expression">expressions</a>. <span>Path patterns are used only
|
|
for matching nodes; an item other than a node will never match a
|
|
path pattern.</span> As explained in detail below, a node matches a
|
|
<span>path</span> pattern if the node can be selected by deriving
|
|
an equivalent expression, and evaluating this expression with
|
|
respect to some possible context.</p>
|
|
<div class="div3">
|
|
<h4><a name="pattern-examples" id="pattern-examples"></a>5.5.1
|
|
<a href="#pattern-examples" style="text-decoration: none">Examples
|
|
of Patterns</a></h4>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e9197" id=
|
|
"d7e9197"></a>Example: Patterns</div>
|
|
<p>Here are some examples of patterns:</p>
|
|
<ul>
|
|
<li>
|
|
<p><code>para</code> matches any <code>para</code> element.</p>
|
|
</li>
|
|
<li>
|
|
<p><code>*</code> matches any element.</p>
|
|
</li>
|
|
<li>
|
|
<p><code>chapter|appendix</code> matches any <code>chapter</code>
|
|
element and any <code>appendix</code> element.</p>
|
|
</li>
|
|
<li>
|
|
<p><code>olist/entry</code> matches any <code>entry</code> element
|
|
with an <code>olist</code> parent.</p>
|
|
</li>
|
|
<li>
|
|
<p><code>appendix//para</code> matches any <code>para</code>
|
|
element with an <code>appendix</code> ancestor element.</p>
|
|
</li>
|
|
<li>
|
|
<p><code>schema-element(us:address)</code> matches any element that
|
|
is annotated as an instance of the type defined by the schema
|
|
element declaration <code>us:address</code>, and whose name is
|
|
either <code>us:address</code> or the name of another element in
|
|
its substitution group.</p>
|
|
</li>
|
|
<li>
|
|
<p><code>attribute(*, xs:date)</code> matches any attribute
|
|
annotated as being of type <code>xs:date</code>.</p>
|
|
</li>
|
|
<li>
|
|
<p><code>/</code> matches a document node.</p>
|
|
</li>
|
|
<li>
|
|
<p><code>document-node()</code> matches a document node.</p>
|
|
</li>
|
|
<li>
|
|
<p><code>document-node(schema-element(my:invoice))</code> matches
|
|
the document node of a document whose document element is named
|
|
<code>my:invoice</code> and matches the type defined by the global
|
|
element declaration <code>my:invoice</code>.</p>
|
|
</li>
|
|
<li>
|
|
<p><code>text()</code> matches any text node.</p>
|
|
</li>
|
|
<li>
|
|
<p><code>namespace-node()</code> matches any namespace node.</p>
|
|
</li>
|
|
<li>
|
|
<p><code>node()</code> matches any node other than an attribute
|
|
node, namespace node, or document node.</p>
|
|
</li>
|
|
<li>
|
|
<p><code>id("W33")</code> matches the element with unique ID
|
|
<code>W33</code>.</p>
|
|
</li>
|
|
<li>
|
|
<p><code>para[1]</code> matches any <code>para</code> element that
|
|
is the first <code>para</code> child element of its parent. It also
|
|
matches a parentless <code>para</code> element.</p>
|
|
</li>
|
|
<li>
|
|
<p><code>//para</code> matches any <code>para</code> element that
|
|
has a parent node.</p>
|
|
</li>
|
|
<li>
|
|
<p><code>bullet[position() mod 2 = 0]</code> matches any
|
|
<code>bullet</code> element that is an even-numbered
|
|
<code>bullet</code> child of its parent.</p>
|
|
</li>
|
|
<li>
|
|
<p><code>div[@class="appendix"]//p</code> matches any
|
|
<code>p</code> element with a <code>div</code> ancestor element
|
|
that has a <code>class</code> attribute with value
|
|
<code>appendix</code>.</p>
|
|
</li>
|
|
<li>
|
|
<p><code>@class</code> matches any <code>class</code> attribute
|
|
(<em>not</em> any element that has a <code>class</code>
|
|
attribute).</p>
|
|
</li>
|
|
<li>
|
|
<p><code>@*</code> matches any attribute node.</p>
|
|
</li>
|
|
<li>
|
|
<p><code>$xyz</code> matches any node that is present in the value
|
|
of the variable <code>$xyz</code>.</p>
|
|
</li>
|
|
<li>
|
|
<p><code>$xyz//*</code> matches any element that is a descendant of
|
|
a node that is present in the value of the variable
|
|
<code>$xyz</code>.</p>
|
|
</li>
|
|
<li>
|
|
<p><code>doc('product.xml')//*</code> matches any element within
|
|
the document whose document URI is 'product.xml'.</p>
|
|
</li>
|
|
<li>
|
|
<p><code>~item()</code> matches any item whatsoever.</p>
|
|
</li>
|
|
<li>
|
|
<p><code>~node()</code> matches any node. (Note the distinction
|
|
from the pattern <code>node()</code>.)</p>
|
|
</li>
|
|
<li>
|
|
<p><code>~element()</code> matches any element. (This is precisely
|
|
equivalent to the pattern <code>element()</code>.)</p>
|
|
</li>
|
|
<li>
|
|
<p><code>~xs:date</code> matches any atomic value of type
|
|
<code>xs:date</code> (or a type derived by restriction from
|
|
<code>xs:date</code>).</p>
|
|
</li>
|
|
<li>
|
|
<p><code>~xs:date[. gt current-date()]</code> matches any date in
|
|
the future.</p>
|
|
</li>
|
|
<li>
|
|
<p><code>~function()</code> matches any function item.</p>
|
|
</li>
|
|
<li>
|
|
<p><code>~function(xs:integer) as xs:integer</code> matches any
|
|
function item whose underlying function takes an integer argument
|
|
and returns an integer result.</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
<div class="div3">
|
|
<h4><a name="pattern-syntax" id="pattern-syntax"></a>5.5.2 <a href=
|
|
"#pattern-syntax" style="text-decoration: none">Syntax of
|
|
Patterns</a></h4>
|
|
<p><a name="err-XTSE0340" id="err-XTSE0340"><span class=
|
|
"error">[ERR XTSE0340]</span></a> Where an attribute is defined to
|
|
contain a <a title="pattern" class="termref" href=
|
|
"#dt-pattern">pattern</a>, it is a <a title="static error" class=
|
|
"termref" href="#dt-static-error">static error</a> if the pattern
|
|
does not match the production <a href=
|
|
"#NT-Pattern">Pattern</a>.</p>
|
|
<p>The grammar for patterns uses the notation defined in <a href=
|
|
"http://www.w3.org/TR/xpath-21/#EBNFNotation">Section A.1.1
|
|
Notation</a><sup><small>XP21</small></sup>.</p>
|
|
<p>The lexical rules for patterns are the same as the lexical rules
|
|
for XPath expressions, as defined in <a href=
|
|
"http://www.w3.org/TR/xpath-21/#lexical-structure">Section A.2
|
|
Lexical structure</a><sup><small>XP21</small></sup>. Comments are
|
|
permitted between tokens, using the syntax <code>(: ... :)</code>.
|
|
All other provisions of the XPath grammar apply where relevant, for
|
|
example the rules for whitespace handling and extra-grammatical
|
|
constraints.</p>
|
|
<p>If a pattern appears <span>in an attribute of an element that is
|
|
processed with <a title="XSLT 1.0 behavior" class="termref" href=
|
|
"#dt-xslt-10-behavior">XSLT 1.0 behavior</a></span> (see <a href=
|
|
"#backwards"><i>3.8 Backwards Compatible Processing</i></a>), then
|
|
the semantics of the pattern are defined on the basis that the
|
|
equivalent XPath expression is evaluated with <a title=
|
|
"XPath 1.0 compatibility mode" class="termref" href=
|
|
"#dt-xpath-compat-mode">XPath 1.0 compatibility mode</a> set to
|
|
true.</p>
|
|
<h5><a name="d7e9551" id="d7e9551"></a>Patterns</h5>
|
|
<table class="scrap" summary="Scrap">
|
|
<tbody>
|
|
<tr valign="baseline">
|
|
<td><a name="NT-Pattern" id=
|
|
"NT-Pattern"></a>[1]   </td>
|
|
<td><code>Pattern</code></td>
|
|
<td>   ::=   </td>
|
|
<td><code><a href="#NT-PatternTerm">PatternTerm</a> ( ('|' |
|
|
'union') <a href="#NT-Pattern">PatternTerm</a> )*</code></td>
|
|
</tr>
|
|
<tr valign="baseline">
|
|
<td><a name="NT-PatternTerm" id=
|
|
"NT-PatternTerm"></a>[2]   </td>
|
|
<td><code>PatternTerm</code></td>
|
|
<td>   ::=   </td>
|
|
<td><code><a href="#NT-BasicPattern">BasicPattern</a> (
|
|
('intersect' | 'except') <a href="#NT-Pattern">BasicPattern</a>
|
|
)*</code></td>
|
|
</tr>
|
|
<tr valign="baseline">
|
|
<td><a name="NT-BasicPattern" id=
|
|
"NT-BasicPattern"></a>[3]   </td>
|
|
<td><code>BasicPattern</code></td>
|
|
<td>   ::=   </td>
|
|
<td><code><a href="#NT-TypePattern">TypePattern</a> | <a href=
|
|
"#NT-TypePattern">PathPattern</a> | <a href=
|
|
"#NT-QualifiedPattern">QualifiedPattern</a></code></td>
|
|
</tr>
|
|
<tr valign="baseline">
|
|
<td><a name="NT-QualifiedPattern" id=
|
|
"NT-QualifiedPattern"></a>[4]   </td>
|
|
<td><code>QualifiedPattern</code></td>
|
|
<td>   ::=   </td>
|
|
<td><code>'(' <a href="#NT-Pattern">Pattern</a> ')' <a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-PredicateList">PredicateList</a><sup><small>XP21</small></sup></code></td>
|
|
</tr>
|
|
<tr valign="baseline">
|
|
<td><a name="NT-TypePattern" id=
|
|
"NT-TypePattern"></a>[5]   </td>
|
|
<td><code>TypePattern</code></td>
|
|
<td>   ::=   </td>
|
|
<td><code>'~' <a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-ItemType">ItemType</a><sup><small>XP21</small></sup>
|
|
<a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-PredicateList">PredicateList</a><sup><small>XP21</small></sup></code></td>
|
|
</tr>
|
|
<tr valign="baseline">
|
|
<td><a name="NT-PathPattern" id=
|
|
"NT-PathPattern"></a>[6]   </td>
|
|
<td><code>PathPattern</code></td>
|
|
<td>   ::=   </td>
|
|
<td><code><a href=
|
|
"#NT-RelativePathPattern">RelativePathPattern</a></code></td>
|
|
</tr>
|
|
<tr valign="baseline">
|
|
<td></td>
|
|
<td></td>
|
|
<td></td>
|
|
<td><code>| '/' <a href=
|
|
"#NT-RelativePathPattern">RelativePathPattern</a>?</code></td>
|
|
</tr>
|
|
<tr valign="baseline">
|
|
<td></td>
|
|
<td></td>
|
|
<td></td>
|
|
<td><code>| '//' <a href=
|
|
"#NT-RelativePathPattern">RelativePathPattern</a></code></td>
|
|
</tr>
|
|
<tr valign="baseline">
|
|
<td></td>
|
|
<td></td>
|
|
<td></td>
|
|
<td><code>| <a href=
|
|
"#NT-RootedPattern">RootedPattern</a></code></td>
|
|
</tr>
|
|
<tr valign="baseline">
|
|
<td><a name="NT-RootedPattern" id=
|
|
"NT-RootedPattern"></a>[7]   </td>
|
|
<td><code>RootedPattern</code></td>
|
|
<td>   ::=   </td>
|
|
<td><code>( <a href="#NT-VarRefRoot">VarRefRoot</a> | <a href=
|
|
"#NT-DocCall">DocCall</a> | <a href="#NT-IdCall">IdCall</a> |
|
|
<a href="#NT-ElementWithIdCall">ElementWithIdCall</a> | <a href=
|
|
"#NT-KeyCall">KeyCall</a> )</code></td>
|
|
</tr>
|
|
<tr valign="baseline">
|
|
<td></td>
|
|
<td></td>
|
|
<td></td>
|
|
<td><code>(('/' | '//') <a href=
|
|
"#NT-RelativePathPattern">RelativePathPattern</a>)?</code></td>
|
|
</tr>
|
|
<tr valign="baseline">
|
|
<td><a name="NT-VarRefRoot" id=
|
|
"NT-VarRefRoot"></a>[8]   </td>
|
|
<td><code>VarRefRoot</code></td>
|
|
<td>   ::=   </td>
|
|
<td><code><a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-VarRef">VarRef</a><sup><small>XP21</small></sup></code></td>
|
|
</tr>
|
|
<tr valign="baseline">
|
|
<td><a name="NT-RelativePathPattern" id=
|
|
"NT-RelativePathPattern"></a>[9]   </td>
|
|
<td><code>RelativePathPattern</code></td>
|
|
<td>   ::=   </td>
|
|
<td><code><a href="#NT-PatternStep">PatternStep</a> (('/' | '//')
|
|
<a href="#NT-PatternStep">PatternStep</a>)*</code></td>
|
|
</tr>
|
|
<tr valign="baseline">
|
|
<td><a name="NT-PatternStep" id=
|
|
"NT-PatternStep"></a>[10]   </td>
|
|
<td><code>PatternStep</code></td>
|
|
<td>   ::=   </td>
|
|
<td><code><a href="#NT-PatternAxis">PatternAxis</a>? <a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-NodeTest">NodeTest</a><sup><small>XP21</small></sup>
|
|
<a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-PredicateList">PredicateList</a><sup><small>XP21</small></sup></code></td>
|
|
</tr>
|
|
<tr valign="baseline">
|
|
<td><a name="NT-PatternAxis" id=
|
|
"NT-PatternAxis"></a>[11]   </td>
|
|
<td><code>PatternAxis</code></td>
|
|
<td>   ::=   </td>
|
|
<td><code>(('child' | 'attribute' | 'descendant' |
|
|
'descendant-or-self') '::') | '@'</code></td>
|
|
</tr>
|
|
<tr valign="baseline">
|
|
<td><a name="NT-DocCall" id=
|
|
"NT-DocCall"></a>[12]   </td>
|
|
<td><code>DocCall</code></td>
|
|
<td>   ::=   </td>
|
|
<td><code>'doc' '(' <a href="#NT-ArgValue">ArgValue</a>
|
|
')'</code></td>
|
|
</tr>
|
|
<tr valign="baseline">
|
|
<td><a name="NT-IdCall" id=
|
|
"NT-IdCall"></a>[13]   </td>
|
|
<td><code>IdCall</code></td>
|
|
<td>   ::=   </td>
|
|
<td><code>'id' '(' <a href="#NT-ArgValue">ArgValue</a> (','
|
|
<a href="#NT-ArgValue">ArgValue</a> )? ')'</code></td>
|
|
</tr>
|
|
<tr valign="baseline">
|
|
<td><a name="NT-ElementWithIdCall" id=
|
|
"NT-ElementWithIdCall"></a>[14]   </td>
|
|
<td><code>ElementWithIdCall</code></td>
|
|
<td>   ::=   </td>
|
|
<td><code>'element-with-id' '(' <a href="#NT-ArgValue">ArgValue</a>
|
|
(',' <a href="#NT-ArgValue">ArgValue</a> )? ')'</code></td>
|
|
</tr>
|
|
<tr valign="baseline">
|
|
<td><a name="NT-KeyCall" id=
|
|
"NT-KeyCall"></a>[15]   </td>
|
|
<td><code>KeyCall</code></td>
|
|
<td>   ::=   </td>
|
|
<td><code>'key' '(' <a href="#NT-ArgValue">ArgValue</a> ','
|
|
<a href="#NT-ArgValue">ArgValue</a> (',' <a href=
|
|
"#NT-ArgValue">ArgValue</a> )? ')'</code></td>
|
|
</tr>
|
|
<tr valign="baseline">
|
|
<td><a name="NT-ArgValue" id=
|
|
"NT-ArgValue"></a>[16]   </td>
|
|
<td><code>ArgValue</code></td>
|
|
<td>   ::=   </td>
|
|
<td><code><a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-Literal">Literal</a><sup><small>XP21</small></sup>
|
|
| <a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-VarRef">VarRef</a><sup><small>XP21</small></sup></code></td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>The constructs <a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-ItemType">ItemType</a><sup><small>XP21</small></sup>,
|
|
<a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-NodeTest">NodeTest</a><sup><small>XP21</small></sup>,
|
|
<a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-PredicateList">PredicateList</a><sup><small>XP21</small></sup>,
|
|
<a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-VarRef">VarRef</a><sup><small>XP21</small></sup>,
|
|
and <a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-Literal">Literal</a><sup><small>XP21</small></sup>
|
|
are part of the XPath expression language, and are defined in
|
|
<a href="#xpath-21">[XPath 2.1]</a>.</p>
|
|
<p>In a <code>DocCall</code>, <code>IdCall</code>,
|
|
<code>ElementWithIdCall</code>, or <code>KeyCall</code>, the
|
|
construct has the same semantics as a call to the corresponding
|
|
function in an XPath expression. In particular, the arguments
|
|
<span class="verb">must</span> (after conversion using the
|
|
<a title="function conversion rules" class="termref" href=
|
|
"#dt-function-conversion-rules">function conversion rules</a> if
|
|
necessary) be of the correct type required by the signature of the
|
|
function. The function conversion rules are applied with XPath 1.0
|
|
compatibility mode set to false. If an argument cannot be converted
|
|
to the required type, a type error results: if the type error can
|
|
be detected statically then it <span class="verb">may</span> be
|
|
signalled statically.</p>
|
|
</div>
|
|
<div class="div3">
|
|
<h4><a name="pattern-semantics" id="pattern-semantics"></a>5.5.3
|
|
<a href="#pattern-semantics" style="text-decoration: none">The
|
|
Meaning of a Pattern</a></h4>
|
|
<p>The meaning of a pattern is defined formally as follows, where
|
|
"if" is to be read as "if and only if".</p>
|
|
<ol class="enumar">
|
|
<li>
|
|
<p>An item matches the <a href="#NT-Pattern">Pattern</a> <code>A |
|
|
B</code> (or equivalently, <code>A union B</code>) if it matches
|
|
either <code>A</code> or <code>B</code> or both. (The operators
|
|
<code>|</code> and <code>union</code> are synonyms.)</p>
|
|
</li>
|
|
<li>
|
|
<p>An item matches the <a href="#NT-PatternTerm">PatternTerm</a>
|
|
<code>A intersect B</code> if it matches both <code>A</code> and
|
|
<code>B</code>.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>The operators <code>union</code>, <code>|</code>,
|
|
<code>intersect</code>, and <code>except</code> are analogous to
|
|
the XPath operators with the same representation, but there is a
|
|
difference: in patterns, the definition above gives these operators
|
|
a meaning when matching atomic values as well as when matching
|
|
nodes.</p>
|
|
</div>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>As with XPath expressions, the pattern <code>/ union /*</code>
|
|
can be parsed in two different ways, and the chosen interpretation
|
|
is to treat <code>union</code> as an element name rather than as an
|
|
operator. The other interpretation can b be achieved by writing
|
|
<code>(/) union (/*)</code></p>
|
|
</div>
|
|
</li>
|
|
<li>
|
|
<p>An item matches the <a href="#NT-PatternTerm">PatternTerm</a>
|
|
<code>A except B</code> if it matches <code>A</code> and does not
|
|
match <code>B</code>.</p>
|
|
</li>
|
|
<li>
|
|
<p>Multiple <code>intersect</code> and <code>except</code>
|
|
operators are applied from left to right: for example <code>A
|
|
intersect B except C</code> means <code>(A intersect B) except
|
|
C</code>: that is, the item must match both <code>A</code> and
|
|
<code>B</code>, and must not match <code>C</code>.</p>
|
|
</li>
|
|
<li>
|
|
<p>An item <var>J</var> matches a <a href=
|
|
"#NT-QualifiedPattern">QualifiedPattern</a> if <var>J</var> matches
|
|
the parenthesized <a href="#NT-Pattern">Pattern</a> and satisfies
|
|
each of the predicates in the <a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-PredicateList">PredicateList</a><sup><small>XP21</small></sup>.
|
|
The predicates are evaluated with a <a title="singleton focus"
|
|
class="termref" href="#dt-singleton-focus">singleton focus</a>
|
|
based on <var>J</var>.</p>
|
|
</li>
|
|
<li>
|
|
<p>An item <var>J</var> matches a <a href=
|
|
"#NT-TypePattern">TypePattern</a> if <var>J</var> is an instance of
|
|
the specified <a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-ItemType">ItemType</a><sup><small>XP21</small></sup>
|
|
and satisfies each of the predicates in the <a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-PredicateList">PredicateList</a><sup><small>XP21</small></sup>.
|
|
The predicates are evaluated with a <a title="singleton focus"
|
|
class="termref" href="#dt-singleton-focus">singleton focus</a>
|
|
based on <var>J</var>.</p>
|
|
</li>
|
|
<li>
|
|
<p>An item <var>N</var> matches a <a href=
|
|
"#NT-PathPattern">PathPattern</a> if <var>N</var> is a node and the
|
|
result of evaluating the expression <code>root(.)//(EE)</code> with
|
|
a <a title="singleton focus" class="termref" href=
|
|
"#dt-singleton-focus">singleton focus</a> based on <var>N</var> is
|
|
a sequence that includes the node <var>N</var>, where
|
|
<code>EE</code> is the <b>equivalent expression</b> to the <a href=
|
|
"#NT-PathPattern">PathPattern</a>, as defined below.</p>
|
|
<p>The concept of an <b>equivalent expression</b> is defined as
|
|
follows. In general, the equivalent expression to a <a href=
|
|
"#NT-PathPattern">PathPattern</a> is the XPath expression that
|
|
takes the same lexical form as the <code>PathPattern</code> as
|
|
written. However, if the <code>PathPattern</code> is a
|
|
<code>RelativePathPattern</code>, then the first
|
|
<code>PatternStep</code> <var>PS</var> of this
|
|
<code>RelativePathPattern</code> is adjusted to allow it to match a
|
|
parentless element, attribute, or namespace node. The adjustment
|
|
depends on the axis used in this step, whether it appears
|
|
explicitly or implicitly (according to the rules of <a href=
|
|
"http://www.w3.org/TR/xpath20/#abbrev">Section 3.2.4 Abbreviated
|
|
Syntax</a><sup><small>XP</small></sup>), and is made as
|
|
follows:</p>
|
|
<ol class="enumla">
|
|
<li>
|
|
<p>If the <code>NodeTest</code> in <var>PS</var> is
|
|
<code>document-node()</code> (optionally with arguments), and if no
|
|
explicit axis is specified, then the axis in step <var>PS</var> is
|
|
taken as <code>self</code> rather than <code>child</code>.</p>
|
|
</li>
|
|
<li>
|
|
<p>If <var>PS</var> uses the child axis (explicitly or implicitly),
|
|
and if the <code>NodeTest</code> in <var>PS</var> is not
|
|
<code>document-node()</code> (optionally with arguments), then the
|
|
axis in step <var>PS</var> is replaced by
|
|
<code>child-or-top</code>, which is defined as follows. If the
|
|
context node is a parentless element, comment,
|
|
processing-instruction, or text node then the
|
|
<code>child-or-top</code> axis selects the context node; otherwise
|
|
it selects the children of the context node. It is a forwards axis
|
|
whose principal node kind is element.</p>
|
|
</li>
|
|
<li>
|
|
<p>If <var>PS</var> uses the attribute axis (explicitly or
|
|
implicitly), then the axis in step <var>PS</var> is replaced by
|
|
<code>attribute-or-top</code>, which is defined as follows. If the
|
|
context node is an attribute node with no parent, then the
|
|
<code>attribute-or-top</code> axis selects the context node;
|
|
otherwise it selects the attributes of the context node. It is a
|
|
forwards axis whose principal node kind is attribute.</p>
|
|
</li>
|
|
<li>
|
|
<p>If <var>PS</var> uses the namespace axis (implicitly, by using
|
|
<code>namespace-node()</code> as a <code>KindTest</code>), then the
|
|
axis in step <var>PS</var> is replaced by
|
|
<code>namespace-or-top</code>, which is defined as follows. If the
|
|
context node is a namespace node with no parent, then the
|
|
<code>namespace-or-top</code> axis selects the context node;
|
|
otherwise it selects the namespace nodes of the context node. It is
|
|
a forwards axis whose principal node kind is namespace.</p>
|
|
<blockquote>
|
|
<p><b><a name="issue-implicit-namespace-axis" id=
|
|
"issue-implicit-namespace-axis">Issue 7
|
|
(implicit-namespace-axis)</a>:</b></p>
|
|
<p>In XPath 2.1, as currently defined, the path expression
|
|
<code>A/B/namespace-node()</code> selects nothing, because the
|
|
default axis for the abbreviated step <code>namespace-node()</code>
|
|
is <code>child</code> rather than <code>namespace</code>. This has
|
|
been raised as bug 9298. Perhaps we should allow the namespace axis
|
|
to be explicit in a pattern.</p>
|
|
</blockquote>
|
|
</li>
|
|
</ol>
|
|
<p>The axes <code>child-or-top</code>,
|
|
<code>attribute-or-top</code>, and <code>namespace-or-top</code>
|
|
are introduced only for definitional purposes. They cannot be used
|
|
explicitly in a user-written pattern or expression.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>The purpose of these adjustments is to ensure that a pattern
|
|
such as <code>person</code> matches any element named
|
|
<code>person</code>, even if it has no parent; and similarly, that
|
|
the pattern <code>@width</code> matches any attribute named
|
|
<code>width</code>, even a parentless attribute. The rule also
|
|
ensures that a pattern using a <code>NodeTest</code> of the form
|
|
<code>document-node(...)</code> matches a document node. The
|
|
pattern <code>node()</code> will match any element, text node,
|
|
comment, or processing instruction, whether or not it has a parent.
|
|
For backwards compatibility reasons, the pattern
|
|
<code>node()</code>, when used without an explicit axis, does not
|
|
match document nodes, attribute nodes, or namespace nodes. The
|
|
rules are also phrased to ensure that positional patterns of the
|
|
form <code>para[1]</code> continue to count nodes relative to their
|
|
parent, if they have one. To match any node at all, XSLT 2.1 allows
|
|
the pattern <code>~node()</code> to be used (note the tilde).</p>
|
|
</div>
|
|
</li>
|
|
</ol>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e10153" id=
|
|
"d7e10153"></a>Example: The Semantics of Path Patterns</div>
|
|
<p>The path pattern <code>p</code> matches any <code>p</code>
|
|
element, because a <code>p</code> element will always be present in
|
|
the result of evaluating the <a title="expression" class="termref"
|
|
href="#dt-expression">expression</a>
|
|
<code>root(.)//(child-or-top::p)</code>. Similarly, <code>/</code>
|
|
matches a document node, and only a document node, because the
|
|
result of the <a title="expression" class="termref" href=
|
|
"#dt-expression">expression</a> <code>root(.)//(/)</code> returns
|
|
the root node of the tree containing the context node if and only
|
|
if it is a document node.</p>
|
|
<p>The path pattern <code>node()</code> matches all nodes selected
|
|
by the expression <code>root(.)//(child-or-top::node())</code>,
|
|
that is, all element, text, comment, and processing instruction
|
|
nodes, whether or not they have a parent. It does not match
|
|
attribute or namespace nodes because the expression does not select
|
|
nodes using the attribute or namespace axes. It does not match
|
|
document nodes because for backwards compatibility reasons the
|
|
<code>child-or-top</code> axis does not match a document node.</p>
|
|
<p>The path pattern <code>$V</code> matches all nodes selected by
|
|
the expression <code>root(.)//($V)</code>, that is, all nodes in
|
|
the value of $V (which will typically be a global variable, though
|
|
when the pattern is used in contexts such as the <a href=
|
|
"#element-number"><code>xsl:number</code></a> or <a href=
|
|
"#element-for-each-group"><code>xsl:for-each-group</code></a>
|
|
instructions, it can also be a local variable).</p>
|
|
<p>The path pattern <code>doc('product.xml')//product</code>
|
|
matches all nodes selected by the expression
|
|
<code>root(.)//(doc('product.xml')//product)</code>, that is, all
|
|
<code>product</code> elements in the document whose URI is
|
|
<code>product.xml</code>.</p>
|
|
</div>
|
|
<p>Although the semantics of path patterns are specified formally
|
|
in terms of expression evaluation, it is possible to understand
|
|
pattern matching using a different model. A path pattern such as
|
|
<code>book/chapter/section</code> can be examined from right to
|
|
left. A node will only match this pattern if it is a
|
|
<code>section</code> element; and then, only if its parent is a
|
|
<code>chapter</code>; and then, only if the parent of that
|
|
<code>chapter</code> is a <code>book</code>. When the pattern uses
|
|
the <code>//</code> operator, one can still read it from right to
|
|
left, but this time testing the ancestors of a node rather than its
|
|
parent. For example <code>appendix//section</code> matches every
|
|
<code>section</code> element that has an ancestor
|
|
<code>appendix</code> element.</p>
|
|
<p>The formal definition, however, is useful for understanding the
|
|
meaning of a pattern such as <code>para[1]</code>. This matches any
|
|
node selected by the expression
|
|
<code>root(.)//(child-or-top::para[1])</code>: that is, any
|
|
<code>para</code> element that is the first <code>para</code> child
|
|
of its parent, or a <code>para</code> element that has no
|
|
parent.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>An implementation, of course, may use any algorithm it wishes
|
|
for evaluating patterns, so long as the result corresponds with the
|
|
formal definition above. An implementation that followed the formal
|
|
definition by evaluating the equivalent expression and then testing
|
|
the membership of a specific node in the result would probably be
|
|
very inefficient.</p>
|
|
</div>
|
|
</div>
|
|
<div class="div3">
|
|
<h4><a name="pattern-errors" id="pattern-errors"></a>5.5.4 <a href=
|
|
"#pattern-errors" style="text-decoration: none">Errors in
|
|
Patterns</a></h4>
|
|
<p>Any <a title="dynamic error" class="termref" href=
|
|
"#dt-dynamic-error">dynamic error</a> or <a title="type errors"
|
|
class="termref" href="#dt-type-error">type error</a> that occurs
|
|
during the evaluation of a <a title="pattern" class="termref" href=
|
|
"#dt-pattern">pattern</a> against a particular <span>item</span> is
|
|
treated as a <a title="recoverable error" class="termref" href=
|
|
"#dt-recoverable-error">recoverable error</a> even if the error
|
|
would not be recoverable under other circumstances. The <a title=
|
|
"optional recovery action" class="termref" href=
|
|
"#dt-optional-recovery-action">optional recovery action</a> is to
|
|
treat the pattern as not matching that node.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>The reason for this provision is that it is difficult for the
|
|
stylesheet author to predict which predicates in a pattern will
|
|
actually be evaluated. In the case of match patterns in template
|
|
rules, it is not even possible to predict which patterns will be
|
|
evaluated against a particular node. Making errors in patterns
|
|
recoverable enables an implementation, if it chooses to do so, to
|
|
report such errors while stylesheets are under development, while
|
|
masking them if they occur during production running.</p>
|
|
</div>
|
|
<p>There are several particular cases where a processor
|
|
<span class="verb">must not</span> raise a dynamic error:</p>
|
|
<ul>
|
|
<li>
|
|
<p>When evaluating a <a href="#NT-PathPattern">PathPattern</a> that
|
|
starts with <code>/</code> or <code>//</code> or <span>with a call
|
|
on <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-id"><code>id</code></a><sup><small>FO</small></sup>,
|
|
<a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-element-with-id"><code>
|
|
element-with-id</code></a><sup><small>FO</small></sup>, or <a href=
|
|
"#function-key"><code>key</code></a></span>, the result of testing
|
|
this pattern against a node in a tree whose root is not a document
|
|
node must be a non-match, rather than a dynamic error. This rule
|
|
applies to each <a href="#NT-PathPattern">PathPattern</a> within a
|
|
<a href="#NT-Pattern">Pattern</a>.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>Without the above rule, any attempt to apply templates to a
|
|
parentless element node would create the risk of a dynamic error if
|
|
the stylesheet has a template rule specifying
|
|
<code>match="/"</code>.</p>
|
|
</div>
|
|
</li>
|
|
<li>
|
|
<p>When matching an atomic value against a <a href=
|
|
"#NT-PathPattern">PathPattern</a>, the result <span class=
|
|
"verb">must</span> always be a non-match, rather than a dynamic
|
|
error.</p>
|
|
</li>
|
|
<li>
|
|
<p>A processor <span class="verb">must not</span> evaluate a
|
|
predicate within a pattern unless the item matches the part of the
|
|
pattern that is qualified by the predicate. (Or equivalently, if it
|
|
does evaluate the predicate, it must not signal an error when the
|
|
evaluation fails.) For example, evaluation of the pattern
|
|
<code>~xs:integer[. gt 5]</code> must not cause an error when
|
|
testing an item of type <code>xs:date</code>, and the pattern
|
|
<code>$var[child::*]</code> must not cause an error when testing an
|
|
atomic value. If there are multiple predicates, they must be
|
|
evaluated from left to right.</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="attribute-value-templates" id=
|
|
"attribute-value-templates"></a>5.6 <a href=
|
|
"#attribute-value-templates" style=
|
|
"text-decoration: none">Attribute Value Templates</a></h3>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-attribute-value-template" id="dt-attribute-value-template"
|
|
title="attribute value template"></a>In an attribute that is
|
|
designated as an <b>attribute value template</b>, such as an
|
|
attribute of a <a title="literal result element" class="termref"
|
|
href="#dt-literal-result-element">literal result element</a>, an
|
|
<a title="expression" class="termref" href=
|
|
"#dt-expression">expression</a> can be used by surrounding the
|
|
expression with curly brackets (<code>{}</code>)<span class=
|
|
"definition">]</span>.</p>
|
|
<p>An attribute value template consists of an alternating sequence
|
|
of fixed parts and variable parts. A variable part consists of an
|
|
XPath <a title="expression" class="termref" href=
|
|
"#dt-expression">expression</a> enclosed in curly brackets
|
|
(<code>{}</code>). A fixed part may contain any characters, except
|
|
that a left curly bracket <span class="verb">must</span> be written
|
|
as <code>{{</code> and a right curly bracket <span class=
|
|
"verb">must</span> be written as <code>}}</code>. <span>If the
|
|
XPath expression ends with a closing curly bracket, this must be
|
|
separated from the delimiting closing bracket by
|
|
whitespace.</span></p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>An expression within a variable part may contain an unescaped
|
|
curly bracket within a <a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-StringLiteral">StringLiteral</a><sup><small>XP21</small></sup>
|
|
or within a comment.</p>
|
|
<p>Currently no XPath expression starts with an opening curly
|
|
bracket, and the only XPath expression that can end in a closing
|
|
curly bracket is an inline function literal, which cannot usefully
|
|
appear in an attribute value template.</p>
|
|
</div>
|
|
<p><a name="err-XTSE0350" id="err-XTSE0350"><span class=
|
|
"error">[ERR XTSE0350]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> if an
|
|
unescaped left curly bracket appears in a fixed part of an
|
|
attribute value template without a matching right curly
|
|
bracket.</p>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if the string contained between
|
|
matching curly brackets in an attribute value template does not
|
|
match the XPath production <a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-Expr">Expr</a><sup><small>XP21</small></sup>,
|
|
or if it contains other XPath static errors. The error is signaled
|
|
using the appropriate XPath error code.</p>
|
|
<p><a name="err-XTSE0370" id="err-XTSE0370"><span class=
|
|
"error">[ERR XTSE0370]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> if an
|
|
unescaped right curly bracket occurs in a fixed part of an
|
|
attribute value template.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-effective-value" id="dt-effective-value" title=
|
|
"effective value"></a>The result of evaluating an attribute value
|
|
template is referred to as the <b>effective value</b> of the
|
|
attribute.<span class="definition">]</span> The effective value is
|
|
the string obtained by concatenating the expansions of the fixed
|
|
and variable parts:</p>
|
|
<ul>
|
|
<li>
|
|
<p>The expansion of a fixed part is obtained by replacing any
|
|
double curly brackets (<code>{{</code> or <code>}}</code>) by the
|
|
corresponding single curly bracket.</p>
|
|
</li>
|
|
<li>
|
|
<p>The expansion of a variable part is obtained by evaluating the
|
|
enclosed XPath <a title="expression" class="termref" href=
|
|
"#dt-expression">expression</a> and converting the resulting value
|
|
to a string. This conversion is done using the rules given in
|
|
<a href="#constructing-simple-content"><i>5.7.2 Constructing Simple
|
|
Content</i></a>.</p>
|
|
</li>
|
|
</ul>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>This process can generate dynamic errors, for example if the
|
|
sequence contains an element with a complex content type (which
|
|
cannot be atomized).</p>
|
|
</div>
|
|
<p><span>If the element containing the attribute is processed with
|
|
<a title="XSLT 1.0 behavior" class="termref" href=
|
|
"#dt-xslt-10-behavior">XSLT 1.0 behavior</a>, then the rules for
|
|
converting the value of the expression to a string are modified as
|
|
follows.</span> After <a title="atomize" class="termref" href=
|
|
"#dt-atomization">atomizing</a> the result of the expression, all
|
|
items other than the first item in the resulting sequence are
|
|
discarded, and the effective value is obtained by converting the
|
|
first item in the sequence to a string. If the atomized sequence is
|
|
empty, the result is a zero-length string.</p>
|
|
<p>Curly brackets are not treated specially in an attribute value
|
|
in an XSLT <a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a> unless the attribute is
|
|
specifically designated as one that permits an attribute value
|
|
template; in an element syntax summary, the value of such
|
|
attributes is surrounded by curly brackets.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>Not all attributes are designated as attribute value templates.
|
|
Attributes whose value is an <a title="expression" class="termref"
|
|
href="#dt-expression">expression</a> or <a title="pattern" class=
|
|
"termref" href="#dt-pattern">pattern</a>, attributes of <a title=
|
|
"declaration" class="termref" href=
|
|
"#dt-declaration">declaration</a> elements and attributes that
|
|
refer to named XSLT objects are generally not designated as
|
|
attribute value templates (an exception is the <code>format</code>
|
|
attribute of <a href=
|
|
"#element-result-document"><code>xsl:result-document</code></a>).
|
|
Namespace declarations are not XDM attribute nodes and are
|
|
therefore never treated as attribute value templates.</p>
|
|
</div>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e10506" id=
|
|
"d7e10506"></a>Example: Attribute Value Templates</div>
|
|
<p>The following example creates an <code>img</code> result element
|
|
from a <code>photograph</code> element in the source; the value of
|
|
the <code>src</code> and <code>width</code> attributes are computed
|
|
using XPath expressions enclosed in attribute value templates:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:variable name="image-dir" select="'/images'"/>
|
|
|
|
<xsl:template match="photograph">
|
|
<img src="{$image-dir}/{href}" width="{size/@width}"/>
|
|
</xsl:template>
|
|
</pre></div>
|
|
<p>With this source</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<photograph>
|
|
<href>headquarters.jpg</href>
|
|
<size width="300"/>
|
|
</photograph>
|
|
</pre></div>
|
|
<p>the result would be</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<img src="/images/headquarters.jpg" width="300"/>
|
|
</pre></div>
|
|
</div>
|
|
<p> </p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e10533" id=
|
|
"d7e10533"></a>Example: Producing a Space-Separated List</div>
|
|
<p>The following example shows how the values in a sequence are
|
|
output as a space-separated list. The following literal result
|
|
element:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<temperature readings="{10.32, 5.50, 8.31}"/>
|
|
</pre></div>
|
|
<p>produces the output node:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<temperature readings="10.32 5.5 8.31"/>
|
|
</pre></div>
|
|
</div>
|
|
<p>Curly brackets are <em>not</em> recognized recursively inside
|
|
expressions.</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e10549" id=
|
|
"d7e10549"></a>Example: Curly Brackets can not be Nested</div>
|
|
<p>For example:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<a href="#{id({@ref})/title}">
|
|
</pre></div>
|
|
<p>is <em>not</em> allowed. Instead, use simply:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<a href="#{id(@ref)/title}">
|
|
</pre></div>
|
|
</div>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="sequence-constructors" id=
|
|
"sequence-constructors"></a>5.7 <a href="#sequence-constructors"
|
|
style="text-decoration: none">Sequence Constructors</a></h3>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-sequence-constructor" id="dt-sequence-constructor" title=
|
|
"sequence constructor"></a>A <b>sequence constructor</b> is a
|
|
sequence of zero or more sibling nodes in the <a title="stylesheet"
|
|
class="termref" href="#dt-stylesheet">stylesheet</a> that can be
|
|
evaluated to return a sequence of nodes, atomic values, <span>and
|
|
function items</span>. The way that the resulting sequence is used
|
|
depends on the containing instruction.<span class=
|
|
"definition">]</span></p>
|
|
<p>Many <a title="XSLT element" class="termref" href=
|
|
"#dt-xslt-element">XSLT elements</a>, and also <a title=
|
|
"literal result element" class="termref" href=
|
|
"#dt-literal-result-element">literal result elements</a>, are
|
|
defined to take a <a title="sequence constructor" class="termref"
|
|
href="#dt-sequence-constructor">sequence constructor</a> as their
|
|
content.</p>
|
|
<p>Four kinds of nodes may be encountered in a sequence
|
|
constructor:</p>
|
|
<ul>
|
|
<li>
|
|
<p>A <em>Text node</em> appearing in the <a title="stylesheet"
|
|
class="termref" href="#dt-stylesheet">stylesheet</a> (if it has not
|
|
been removed in the process of whitespace stripping: see <a href=
|
|
"#stylesheet-stripping"><i>4.2 Stripping Whitespace from the
|
|
Stylesheet</i></a>) is copied to create a new parentless text
|
|
node.</p>
|
|
</li>
|
|
<li>
|
|
<p>A <a title="literal result element" class="termref" href=
|
|
"#dt-literal-result-element">literal result element</a> is
|
|
evaluated to create a new parentless element node, having the same
|
|
<a title="expanded-QName" class="termref" href=
|
|
"#dt-expanded-qname">expanded-QName</a> as the literal result
|
|
element: see <a href="#literal-result-element"><i>11.1 Literal
|
|
Result Elements</i></a>.</p>
|
|
</li>
|
|
<li>
|
|
<p>An XSLT <a title="instruction" class="termref" href=
|
|
"#dt-instruction">instruction</a> produces a sequence of zero, one,
|
|
or more items as its result. For most XSLT instructions, these
|
|
items are nodes, but some instructions (<span>such as</span>
|
|
<a href="#element-sequence"><code>xsl:sequence</code></a> and
|
|
<a href="#element-copy-of"><code>xsl:copy-of</code></a>) can also
|
|
produce atomic values <span>or function items</span>. Several
|
|
instructions, such as <a href=
|
|
"#element-element"><code>xsl:element</code></a>, return a newly
|
|
constructed parentless node (which may have its own attributes,
|
|
namespaces, children, and other descendants). Other instructions,
|
|
such as <a href="#element-if"><code>xsl:if</code></a>, pass on the
|
|
items produced by their own nested sequence constructors. The
|
|
<a href="#element-sequence"><code>xsl:sequence</code></a>
|
|
instruction may return atomic values, <span>function items</span>,
|
|
or existing nodes.</p>
|
|
</li>
|
|
<li>
|
|
<p>An <a title="extension instruction" class="termref" href=
|
|
"#dt-extension-instruction">extension instruction</a> (see <a href=
|
|
"#extension-instruction"><i>21.2 Extension Instructions</i></a>)
|
|
also produces a sequence of items as its result.</p>
|
|
</li>
|
|
</ul>
|
|
<p>The result of evaluating a <a title="sequence constructor"
|
|
class="termref" href="#dt-sequence-constructor">sequence
|
|
constructor</a> is the sequence of items formed by concatenating
|
|
the results of evaluating each of the nodes in the sequence
|
|
constructor, retaining order.</p>
|
|
<p>There are several ways the result of a sequence constructor may
|
|
be used.</p>
|
|
<ul>
|
|
<li>
|
|
<p>The sequence may be bound to a variable or returned from a
|
|
stylesheet function, in which case it becomes available as a value
|
|
to be manipulated in arbitrary ways by XPath expressions. The
|
|
sequence is bound to a variable when the sequence constructor
|
|
appears within one of the elements <a href=
|
|
"#element-variable"><code>xsl:variable</code></a>, <a href=
|
|
"#element-param"><code>xsl:param</code></a>, or <a href=
|
|
"#element-with-param"><code>xsl:with-param</code></a>, when this
|
|
instruction has an <code>as</code> attribute. The sequence is
|
|
returned from a stylesheet function when the sequence constructor
|
|
appears within the <a href=
|
|
"#element-function"><code>xsl:function</code></a> element.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>This will typically expose to the stylesheet elements,
|
|
attributes, and other nodes that have not yet been attached to a
|
|
parent node in a <a title="result tree" class="termref" href=
|
|
"#dt-result-tree">result tree</a>. The semantics of XPath
|
|
expressions when applied to parentless nodes are well-defined;
|
|
however, such expressions should be used with care. For example,
|
|
the expression <code>/</code> causes a type error if the root of
|
|
the tree containing the context node is not a document node.</p>
|
|
<p>Parentless attribute nodes require particular care because they
|
|
have no namespace nodes associated with them. A parentless
|
|
attribute node is not permitted to contain namespace-sensitive
|
|
content (for example, a QName or an XPath expression) because there
|
|
is no information enabling the prefix to be resolved to a namespace
|
|
URI. Parentless attributes can be useful in an application (for
|
|
example, they provide an alternative to the use of attribute sets:
|
|
see <a href="#attribute-sets"><i>10.2 Named Attribute Sets</i></a>)
|
|
but they need to be handled with care.</p>
|
|
</div>
|
|
</li>
|
|
<li>
|
|
<p>The sequence may be returned as the result of the containing
|
|
element. This happens when the <span>element</span> containing the
|
|
sequence constructor is <a href=
|
|
"#element-analyze-string"><code>xsl:analyze-string</code></a>,
|
|
<a href=
|
|
"#element-apply-imports"><code>xsl:apply-imports</code></a>,
|
|
<a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>,
|
|
<span><a href="#element-break"><code>xsl:break</code></a></span>,
|
|
<a href=
|
|
"#element-call-template"><code>xsl:call-template</code></a>,
|
|
<span><a href="#element-catch"><code>xsl:catch</code></a></span>,
|
|
<a href="#element-choose"><code>xsl:choose</code></a>, <a href=
|
|
"#element-fallback"><code>xsl:fallback</code></a>, <a href=
|
|
"#element-for-each"><code>xsl:for-each</code></a>, <a href=
|
|
"#element-for-each-group"><code>xsl:for-each-group</code></a>,
|
|
<span><a href="#element-fork"><code>xsl:fork</code></a></span>,
|
|
<a href="#element-if"><code>xsl:if</code></a>, <span><a href=
|
|
"#element-iterate"><code>xsl:iterate</code></a></span>, <a href=
|
|
"#element-matching-substring"><code>xsl:matching-substring</code></a>,
|
|
<a href="#element-next-match"><code>xsl:next-match</code></a>,
|
|
<a href=
|
|
"#element-non-matching-substring"><code>xsl:non-matching-substring</code></a>,
|
|
<span><a href=
|
|
"#element-on-completion"><code>xsl:on-completion</code></a></span>,
|
|
<a href="#element-otherwise"><code>xsl:otherwise</code></a>,
|
|
<a href="#element-perform-sort"><code>xsl:perform-sort</code></a>,
|
|
<a href="#element-sequence"><code>xsl:sequence</code></a>,
|
|
<span><a href="#element-try"><code>xsl:try</code></a></span>, or
|
|
<a href="#element-when"><code>xsl:when</code></a>.</p>
|
|
</li>
|
|
<li>
|
|
<p>The sequence may be used to construct the content of a new
|
|
element or document node. This happens when the sequence
|
|
constructor appears as the content of a <a title=
|
|
"literal result element" class="termref" href=
|
|
"#dt-literal-result-element">literal result element</a>, or of one
|
|
of the instructions <a href=
|
|
"#element-copy"><code>xsl:copy</code></a>, <a href=
|
|
"#element-element"><code>xsl:element</code></a>, <a href=
|
|
"#element-document"><code>xsl:document</code></a>, <a href=
|
|
"#element-result-document"><code>xsl:result-document</code></a>, or
|
|
<a href="#element-message"><code>xsl:message</code></a>. It also
|
|
happens when the sequence constructor is contained in one of the
|
|
elements <a href="#element-variable"><code>xsl:variable</code></a>,
|
|
<a href="#element-param"><code>xsl:param</code></a>, <a href=
|
|
"#element-with-param"><code>xsl:with-param</code></a>, or
|
|
<span><a href=
|
|
"#element-context-item"><code>xsl:context-item</code></a></span>,
|
|
when this instruction has no <code>as</code> attribute. For
|
|
details, see <a href="#constructing-complex-content"><i>5.7.1
|
|
Constructing Complex Content</i></a>.</p>
|
|
</li>
|
|
<li>
|
|
<p>The sequence may be used to construct the <a title=
|
|
"string value" class="termref" href="#dt-string-value">string
|
|
value</a> of an attribute node, text node, namespace node, comment
|
|
node, or processing instruction node. This happens when the
|
|
sequence constructor is contained in one of the elements <a href=
|
|
"#element-attribute"><code>xsl:attribute</code></a>, <a href=
|
|
"#element-value-of"><code>xsl:value-of</code></a>, <a href=
|
|
"#element-namespace"><code>xsl:namespace</code></a>, <a href=
|
|
"#element-comment"><code>xsl:comment</code></a>, or <a href=
|
|
"#element-processing-instruction"><code>xsl:processing-instruction</code></a>.
|
|
For details, see <a href="#constructing-simple-content"><i>5.7.2
|
|
Constructing Simple Content</i></a>.</p>
|
|
</li>
|
|
</ul>
|
|
<div class="div3">
|
|
<h4><a name="constructing-complex-content" id=
|
|
"constructing-complex-content"></a>5.7.1 <a href=
|
|
"#constructing-complex-content" style=
|
|
"text-decoration: none">Constructing Complex Content</a></h4>
|
|
<p>This section describes how the sequence obtained by evaluating a
|
|
<a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> may be used to
|
|
construct the children of a newly constructed document node, or the
|
|
children, attributes and namespaces of a newly constructed element
|
|
node. The sequence of items may be obtained by evaluating the
|
|
<a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> contained in an
|
|
instruction such as <a href=
|
|
"#element-copy"><code>xsl:copy</code></a>, <a href=
|
|
"#element-element"><code>xsl:element</code></a>, <a href=
|
|
"#element-document"><code>xsl:document</code></a>, <a href=
|
|
"#element-result-document"><code>xsl:result-document</code></a>, or
|
|
a <a title="literal result element" class="termref" href=
|
|
"#dt-literal-result-element">literal result element</a>.</p>
|
|
<p>When constructing the content of an element, the
|
|
<code>inherit-namespaces</code> attribute of the <a href=
|
|
"#element-element"><code>xsl:element</code></a> or <a href=
|
|
"#element-copy"><code>xsl:copy</code></a> instruction, or the
|
|
<code>xsl:inherit-namespaces</code> property of the literal result
|
|
element, determines whether namespace nodes are to be inherited.
|
|
The effect of this attribute is described in the rules that
|
|
follow.</p>
|
|
<p>The sequence is processed as follows (applying the rules in the
|
|
order they are listed):</p>
|
|
<ol class="enumar">
|
|
<li>
|
|
<p>The containing instruction may generate attribute nodes and/or
|
|
namespace nodes, as specified in the rules for the individual
|
|
instruction. For example, these nodes may be produced by expanding
|
|
an <code>[xsl:]use-attribute-sets</code> attribute, or by expanding
|
|
the attributes of a <a title="literal result element" class=
|
|
"termref" href="#dt-literal-result-element">literal result
|
|
element</a>. Any such nodes are prepended to the sequence produced
|
|
by evaluating the <a title="sequence constructor" class="termref"
|
|
href="#dt-sequence-constructor">sequence constructor</a>.</p>
|
|
</li>
|
|
<li>
|
|
<p>Any atomic value in the sequence is cast to a string.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>Casting from <code>xs:QName</code> or <code>xs:NOTATION</code>
|
|
to <code>xs:string</code> always succeeds, because these values
|
|
retain a prefix for this purpose. However, there is no guarantee
|
|
that the prefix used will always be meaningful in the context where
|
|
the resulting string is used.</p>
|
|
</div>
|
|
</li>
|
|
<li>
|
|
<p>Any consecutive sequence of strings within the result sequence
|
|
is converted to a single text node, whose <a title="string value"
|
|
class="termref" href="#dt-string-value">string value</a> contains
|
|
the content of each of the strings in turn, with a single space
|
|
(#x20) used as a separator between successive strings.</p>
|
|
</li>
|
|
<li>
|
|
<p>Any document node within the result sequence is replaced by a
|
|
sequence containing each of its children, in document order.</p>
|
|
</li>
|
|
<li>
|
|
<p>Zero-length text nodes within the result sequence are
|
|
removed.</p>
|
|
</li>
|
|
<li>
|
|
<p>Adjacent text nodes within the result sequence are merged into a
|
|
single text node.</p>
|
|
</li>
|
|
<li>
|
|
<p>Invalid <span>items in the result sequence</span> are detected
|
|
as follows.</p>
|
|
<p><a name="err-XTDE0410" id="err-XTDE0410"><span class=
|
|
"error">[ERR XTDE0410]</span></a> It is a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> if the
|
|
result sequence used to construct the content of an element node
|
|
contains a namespace node or attribute node that is preceded in the
|
|
sequence by a node that is neither a namespace node nor an
|
|
attribute node.</p>
|
|
<p><a name="err-XTDE0420" id="err-XTDE0420"><span class=
|
|
"error">[ERR XTDE0420]</span></a> It is a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> if the
|
|
result sequence used to construct the content of a document node
|
|
contains a namespace node or attribute node.</p>
|
|
<p><a name="err-XTDE0430" id="err-XTDE0430"><span class=
|
|
"error">[ERR XTDE0430]</span></a> It is a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> if the
|
|
result sequence contains two or more namespace nodes having the
|
|
same name but different <a title="string value" class="termref"
|
|
href="#dt-string-value">string values</a> (that is, namespace nodes
|
|
that map the same prefix to different namespace URIs).</p>
|
|
<p><a name="err-XTDE0440" id="err-XTDE0440"><span class=
|
|
"error">[ERR XTDE0440]</span></a> It is a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> if the
|
|
result sequence contains a namespace node with no name and the
|
|
element node being constructed has a null namespace URI (that is,
|
|
it is an error to define a default namespace when the element is in
|
|
no namespace).</p>
|
|
<p><a name="err-XTDE0450" id="err-XTDE0450"><span class=
|
|
"error">[ERR XTDE0450]</span></a> It is a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> if the
|
|
result sequence contains a function item.</p>
|
|
</li>
|
|
<li>
|
|
<p>If the result sequence contains two or more namespace nodes with
|
|
the same name (or no name) and the same <a title="string value"
|
|
class="termref" href="#dt-string-value">string value</a> (that is,
|
|
two namespace nodes mapping the same prefix to the same namespace
|
|
URI), then all but one of the duplicate nodes are discarded.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>Since the order of namespace nodes is undefined, it is not
|
|
significant which of the duplicates is retained.</p>
|
|
</div>
|
|
</li>
|
|
<li>
|
|
<p>If an attribute <var>A</var> in the result sequence has the same
|
|
name as another attribute <var>B</var> that appears later in the
|
|
result sequence, then attribute <var>A</var> is discarded from the
|
|
result sequence. Before discarding attribute <var>A</var>, the
|
|
processor <span class="verb">may</span> signal any <a title=
|
|
"type errors" class="termref" href="#dt-type-error">type errors</a>
|
|
that would be signaled if attribute <var>B</var> were not
|
|
present.</p>
|
|
</li>
|
|
<li>
|
|
<p>Each node in the resulting sequence is attached as a namespace,
|
|
attribute, or child of the newly constructed element or document
|
|
node. Conceptually this involves making a deep copy of the node; in
|
|
practice, however, copying the node will only be necessary if the
|
|
existing node can be referenced independently of the parent to
|
|
which it is being attached. When copying an element or processing
|
|
instruction node, its base URI property is changed to be the same
|
|
as that of its new parent, unless it has an <code>xml:base</code>
|
|
attribute (see <a href="#xmlbase">[XML Base]</a>) that overrides
|
|
this. If the copied element has an <code>xml:base</code> attribute,
|
|
its base URI is the value of that attribute, resolved (if it is
|
|
relative) against the base URI of the new parent node.</p>
|
|
</li>
|
|
<li>
|
|
<p>If the newly constructed node is an element node, then namespace
|
|
fixup is applied to this node, as described in <a href=
|
|
"#namespace-fixup"><i>5.7.3 Namespace Fixup</i></a>.</p>
|
|
</li>
|
|
<li>
|
|
<p>If the newly constructed node is an element node, and if
|
|
namespaces are inherited, then each namespace node of the newly
|
|
constructed element (including any produced as a result of the
|
|
namespace fixup process) is copied to each descendant element of
|
|
the newly constructed element, unless that element or an
|
|
intermediate element already has a namespace node with the same
|
|
name (or absence of a name) or that descendant element or an
|
|
intermediate element is in no namespace and the namespace node has
|
|
no name.</p>
|
|
</li>
|
|
</ol>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e11049" id=
|
|
"d7e11049"></a>Example: A Sequence Constructor for Complex
|
|
Content</div>
|
|
<p>Consider the following stylesheet fragment:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<td>
|
|
<xsl:attribute name="valign">top</xsl:attribute>
|
|
<xsl:value-of select="@description"/>
|
|
</td>
|
|
</pre></div>
|
|
<p>This fragment consists of a literal result element
|
|
<code>td</code>, containing a sequence constructor that consists of
|
|
two instructions: <a href=
|
|
"#element-attribute"><code>xsl:attribute</code></a> and <a href=
|
|
"#element-value-of"><code>xsl:value-of</code></a>. The sequence
|
|
constructor is evaluated to produce a sequence of two nodes: a
|
|
parentless attribute node, and a parentless text node. The
|
|
<code>td</code> instruction causes a <code>td</code> element to be
|
|
created; the new attribute therefore becomes an attribute of the
|
|
new <code>td</code> element, while the text node created by the
|
|
<a href="#element-value-of"><code>xsl:value-of</code></a>
|
|
instruction becomes a child of the <code>td</code> element (unless
|
|
it is zero-length, in which case it is discarded).</p>
|
|
</div>
|
|
<p> </p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e11083" id=
|
|
"d7e11083"></a>Example: Space Separators in Element Content</div>
|
|
<p>Consider the following stylesheet fragment:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<doc>
|
|
<e><xsl:sequence select="1 to 5"/></e>
|
|
<f>
|
|
<xsl:for-each select="1 to 5">
|
|
<xsl:value-of select="."/>
|
|
</xsl:for-each>
|
|
</f>
|
|
</doc>
|
|
</pre></div>
|
|
<p>This produces the output (when indented):</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<doc>
|
|
<e>1 2 3 4 5</e>
|
|
<f>12345</f>
|
|
</doc>
|
|
</pre></div>
|
|
<p>The difference between the two cases is that for the
|
|
<code>e</code> element, the sequence constructor generates a
|
|
sequence of five atomic values, which are therefore separated by
|
|
spaces. For the <code>f</code> element, the content is a sequence
|
|
of five text nodes, which are concatenated without space
|
|
separation.</p>
|
|
<p>It is important to be aware of the distinction between <a href=
|
|
"#element-sequence"><code>xsl:sequence</code></a>, which returns
|
|
the value of its <code>select</code> expression unchanged, and
|
|
<a href="#element-value-of"><code>xsl:value-of</code></a>, which
|
|
constructs a text node.</p>
|
|
</div>
|
|
</div>
|
|
<div class="div3">
|
|
<h4><a name="constructing-simple-content" id=
|
|
"constructing-simple-content"></a>5.7.2 <a href=
|
|
"#constructing-simple-content" style=
|
|
"text-decoration: none">Constructing Simple Content</a></h4>
|
|
<p>The instructions <a href=
|
|
"#element-attribute"><code>xsl:attribute</code></a>, <a href=
|
|
"#element-comment"><code>xsl:comment</code></a>, <a href=
|
|
"#element-processing-instruction"><code>xsl:processing-instruction</code></a>,
|
|
<a href="#element-namespace"><code>xsl:namespace</code></a>, and
|
|
<a href="#element-value-of"><code>xsl:value-of</code></a> all
|
|
create nodes that cannot have children. Specifically, the <a href=
|
|
"#element-attribute"><code>xsl:attribute</code></a> instruction
|
|
creates an attribute node, <a href=
|
|
"#element-comment"><code>xsl:comment</code></a> creates a comment
|
|
node, <a href=
|
|
"#element-processing-instruction"><code>xsl:processing-instruction</code></a>
|
|
creates a processing instruction node, <a href=
|
|
"#element-namespace"><code>xsl:namespace</code></a> creates a
|
|
namespace node, and <a href=
|
|
"#element-value-of"><code>xsl:value-of</code></a> creates a text
|
|
node. The string value of the new node is constructed using either
|
|
the <code>select</code> attribute of the instruction, or the
|
|
<a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> that forms the
|
|
content of the instruction. The <code>select</code> attribute
|
|
allows the content to be specified by means of an XPath expression,
|
|
while the sequence constructor allows it to be specified by means
|
|
of a sequence of XSLT instructions. The <code>select</code>
|
|
attribute or sequence constructor is evaluated to produce a result
|
|
sequence, and the <a title="string value" class="termref" href=
|
|
"#dt-string-value">string value</a> of the new node is derived from
|
|
this result sequence according to the rules below.</p>
|
|
<p>These rules are also used to compute the <a title=
|
|
"effective value" class="termref" href=
|
|
"#dt-effective-value">effective value</a> of an <a title=
|
|
"attribute value template" class="termref" href=
|
|
"#dt-attribute-value-template">attribute value template</a>. In
|
|
this case the sequence being processed is the result of evaluating
|
|
an XPath expression enclosed between curly brackets, and the
|
|
separator is a single space character.</p>
|
|
<ol class="enumar">
|
|
<li>
|
|
<p>Zero-length text nodes in the sequence are discarded.</p>
|
|
</li>
|
|
<li>
|
|
<p>Adjacent text nodes in the sequence are merged into a single
|
|
text node.</p>
|
|
</li>
|
|
<li>
|
|
<p>The sequence is <a title="atomize" class="termref" href=
|
|
"#dt-atomization">atomized</a> <span>(which may cause a dynamic
|
|
error)</span>.</p>
|
|
</li>
|
|
<li>
|
|
<p>Every value in the atomized sequence is cast to a string.</p>
|
|
</li>
|
|
<li>
|
|
<p>The strings within the resulting sequence are concatenated, with
|
|
a (possibly zero-length) separator inserted between successive
|
|
strings. The default separator is a single space. In the case of
|
|
<a href="#element-attribute"><code>xsl:attribute</code></a> and
|
|
<a href="#element-value-of"><code>xsl:value-of</code></a>, a
|
|
different separator can be specified using the
|
|
<code>separator</code> attribute of the instruction; it is
|
|
permissible for this to be a zero-length string, in which case the
|
|
strings are concatenated with no separator. In the case of <a href=
|
|
"#element-comment"><code>xsl:comment</code></a>, <a href=
|
|
"#element-processing-instruction"><code>xsl:processing-instruction</code></a>,
|
|
and <a href="#element-namespace"><code>xsl:namespace</code></a>,
|
|
and when expanding an <a title="attribute value template" class=
|
|
"termref" href="#dt-attribute-value-template">attribute value
|
|
template</a>, the default separator cannot be changed.</p>
|
|
</li>
|
|
<li>
|
|
<p>In the case of <a href=
|
|
"#element-processing-instruction"><code>xsl:processing-instruction</code></a>,
|
|
any leading spaces in the resulting string are removed.</p>
|
|
</li>
|
|
<li>
|
|
<p>The resulting string forms the <a title="string value" class=
|
|
"termref" href="#dt-string-value">string value</a> of the new
|
|
attribute, namespace, comment, processing-instruction, or text
|
|
node.</p>
|
|
</li>
|
|
</ol>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e11229" id=
|
|
"d7e11229"></a>Example: Space Separators in Attribute Content</div>
|
|
<p>Consider the following stylesheet fragment:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<doc>
|
|
<xsl:attribute name="e" select="1 to 5"/>
|
|
<xsl:attribute name="f">
|
|
<xsl:for-each select="1 to 5">
|
|
<xsl:value-of select="."/>
|
|
</xsl:for-each>
|
|
</xsl:attribute>
|
|
</doc>
|
|
</pre></div>
|
|
<p>This produces the output:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<doc e="1 2 3 4 5" f="12345"/>
|
|
</pre></div>
|
|
<p>The difference between the two cases is that for the
|
|
<code>e</code> attribute, the sequence constructor generates a
|
|
sequence of five atomic values, which are therefore separated by
|
|
spaces. For the <code>f</code> attribute, the content is supplied
|
|
as a sequence of five text nodes, which are concatenated without
|
|
space separation.</p>
|
|
<p>Specifying <code>separator=""</code> on the first <a href=
|
|
"#element-attribute"><code>xsl:attribute</code></a> instruction
|
|
would cause the attribute value to be <code>e="12345"</code>. A
|
|
<code>separator</code> attribute on the second <a href=
|
|
"#element-attribute"><code>xsl:attribute</code></a> instruction
|
|
would have no effect, since the separator only affects the way
|
|
adjacent atomic values are handled: separators are never inserted
|
|
between adjacent text nodes.</p>
|
|
</div>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>If an attribute value template contains a sequence of fixed and
|
|
variable parts, no additional whitespace is inserted between the
|
|
expansions of the fixed and variable parts. For example, the
|
|
<a title="effective value" class="termref" href=
|
|
"#dt-effective-value">effective value</a> of the attribute
|
|
<code>a="chapters{4 to 6}"</code> is <code>a="chapters4 5
|
|
6"</code>.</p>
|
|
</div>
|
|
</div>
|
|
<div class="div3">
|
|
<h4><a name="namespace-fixup" id="namespace-fixup"></a>5.7.3
|
|
<a href="#namespace-fixup" style="text-decoration: none">Namespace
|
|
Fixup</a></h4>
|
|
<p>In a tree supplied to or constructed by an XSLT processor, the
|
|
constraints relating to namespace nodes that are specified in
|
|
<a href="#xpath-datamodel-11">[Data Model]</a> <span class=
|
|
"verb">must</span> be satisfied. For example</p>
|
|
<ul>
|
|
<li>
|
|
<p>If an element node has an <a title="expanded-QName" class=
|
|
"termref" href="#dt-expanded-qname">expanded-QName</a> with a
|
|
non-null namespace URI, then that element node <span class=
|
|
"verb">must</span> have at least one namespace node whose <a title=
|
|
"string value" class="termref" href="#dt-string-value">string
|
|
value</a> is the same as that namespace URI.</p>
|
|
</li>
|
|
<li>
|
|
<p>If an element node has an attribute node whose <a title=
|
|
"expanded-QName" class="termref" href=
|
|
"#dt-expanded-qname">expanded-QName</a> has a non-null namespace
|
|
URI, then the element <span class="verb">must</span> have at least
|
|
one namespace node whose <a title="string value" class="termref"
|
|
href="#dt-string-value">string value</a> is the same as that
|
|
namespace URI and whose name is non-empty.</p>
|
|
</li>
|
|
<li>
|
|
<p>Every element <span class="verb">must</span> have a namespace
|
|
node whose <a title="expanded-QName" class="termref" href=
|
|
"#dt-expanded-qname">expanded-QName</a> has local-part
|
|
<code>xml</code> and whose <a title="string value" class="termref"
|
|
href="#dt-string-value">string value</a> is
|
|
<code>http://www.w3.org/XML/1998/namespace</code>. The namespace
|
|
prefix <code>xml</code> must not be associated with any other
|
|
namespace URI, and the namespace URI
|
|
<code>http://www.w3.org/XML/1998/namespace</code> must not be
|
|
associated with any other prefix.</p>
|
|
</li>
|
|
<li>
|
|
<p>A namespace node <span class="verb">must not</span> have the
|
|
name <code>xmlns</code> or the string value
|
|
<code>http://www.w3.org/2000/xmlns/</code>.</p>
|
|
</li>
|
|
</ul>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-namespace-fixup" id="dt-namespace-fixup" title=
|
|
"namespace fixup"></a>The rules for the individual XSLT
|
|
instructions that construct a <a title="result tree" class=
|
|
"termref" href="#dt-result-tree">result tree</a> (see <a href=
|
|
"#creating-new-nodes"><i>11 Creating Nodes and Sequences</i></a>)
|
|
prescribe some of the situations in which namespace nodes are
|
|
written to the tree. These rules, however, are not sufficient to
|
|
ensure that the prescribed constraints are always satisfied. The
|
|
XSLT processor <span class="verb">must</span> therefore add
|
|
additional namespace nodes to satisfy these constraints. This
|
|
process is referred to as <b>namespace fixup</b>.<span class=
|
|
"definition">]</span></p>
|
|
<p>The actual namespace nodes that are added to the tree by the
|
|
namespace fixup process are <a title="implementation-dependent"
|
|
class="termref" href=
|
|
"#dt-implementation-dependent">implementation-dependent</a>,
|
|
provided firstly, that at the end of the process the above
|
|
constraints <span class="verb">must</span> all be satisfied, and
|
|
secondly, that a namespace node <span class="verb">must not</span>
|
|
be added to the tree unless the namespace node is necessary either
|
|
to satisfy these constraints, or to enable the tree to be
|
|
serialized using the original namespace prefixes from the source
|
|
document or <a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a>.</p>
|
|
<p>Namespace fixup <span class="verb">must not</span> result in an
|
|
element having multiple namespace nodes with the same name.</p>
|
|
<p>Namespace fixup <span class="verb">may</span>, if necessary to
|
|
resolve conflicts, change the namespace prefix contained in the
|
|
QName value that holds the name of an element or attribute node.
|
|
This includes the option to add or remove a prefix. However,
|
|
namespace fixup <span class="verb">must not</span> change the
|
|
prefix component contained in a value of type <code>xs:QName</code>
|
|
or <code>xs:NOTATION</code> that forms the typed value of an
|
|
element or attribute node.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>Namespace fixup is not used to create namespace declarations for
|
|
<code>xs:QName</code> or <code>xs:NOTATION</code> values appearing
|
|
in the content of an element or attribute.</p>
|
|
<p>Where values acquire such types as the result of validation,
|
|
namespace fixup does not come into play, because namespace fixup
|
|
happens before validation: in this situation, it is the user's
|
|
responsibility to ensure that the element being validated has the
|
|
required namespace nodes to enable validation to succeed.</p>
|
|
<p>Where existing elements are copied along with their existing
|
|
type annotations (<code>validation="preserve"</code>) the rules
|
|
require that existing namespace nodes are also copied, so that any
|
|
namespace-sensitive values remain valid.</p>
|
|
<p>Where existing attributes are copied along with their existing
|
|
type annotations, the rules of the XDM data model require that a
|
|
parentless attribute node cannot contain a namespace-sensitive
|
|
typed value; this means that it is an error to copy an attribute
|
|
using <code>validation="preserve"</code> if it contains
|
|
namespace-sensitive content.</p>
|
|
</div>
|
|
<p>Namespace fixup is applied to every element that is constructed
|
|
using a <a title="literal result element" class="termref" href=
|
|
"#dt-literal-result-element">literal result element</a>, or one of
|
|
the instructions <a href=
|
|
"#element-element"><code>xsl:element</code></a>, <a href=
|
|
"#element-copy"><code>xsl:copy</code></a>, or <a href=
|
|
"#element-copy-of"><code>xsl:copy-of</code></a>. An implementation
|
|
is not <span class="verb">required</span> to perform namespace
|
|
fixup for elements in any source document, that is, for a document
|
|
in the initial input sequence, documents loaded using the <a href=
|
|
"#function-document"><code>document</code></a>, <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-doc"><code>doc</code></a><sup><small>FO</small></sup>
|
|
or <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-collection"><code>collection</code></a><sup><small>FO</small></sup>
|
|
function, documents supplied as the value of a <a title=
|
|
"stylesheet parameter" class="termref" href=
|
|
"#dt-stylesheet-parameter">stylesheet parameter</a>, or documents
|
|
returned by an <a title="extension function" class="termref" href=
|
|
"#dt-extension-function">extension function</a> or <a title=
|
|
"extension instruction" class="termref" href=
|
|
"#dt-extension-instruction">extension instruction</a>.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>A source document (an input document, a document returned by the
|
|
<a href="#function-document"><code>document</code></a>, <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-doc"><code>doc</code></a><sup><small>FO</small></sup>
|
|
or <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-collection"><code>collection</code></a><sup><small>FO</small></sup>
|
|
functions, a document returned by an extension function or
|
|
extension instruction, or a document supplied as a stylesheet
|
|
parameter) is required to satisfy the constraints described in
|
|
<a href="#xpath-datamodel-11">[Data Model]</a>, including the
|
|
constraints imposed by the namespace fixup process. The effect of
|
|
supplying a pseudo-document that does not meet these constraints is
|
|
undefined.</p>
|
|
</div>
|
|
<p>In an Infoset (see <a href="#xml-infoset">[XML Information
|
|
Set]</a>) created from a document conforming to <a href=
|
|
"#xml-names">[Namespaces in XML]</a>, it will always be true that
|
|
if a parent element has an in-scope namespace with a non-empty
|
|
namespace prefix, then its child elements will also have an
|
|
in-scope namespace with the same namespace prefix, though possibly
|
|
with a different namespace URI. This constraint is removed in
|
|
<a href="#xml-names11">[Namespaces in XML 1.1]</a>. XSLT
|
|
<span>2.1</span> supports the creation of result trees that do not
|
|
satisfy this constraint: the namespace fixup process does not add a
|
|
namespace node to an element merely because its parent node in the
|
|
<a title="result tree" class="termref" href=
|
|
"#dt-result-tree">result tree</a> has such a namespace node.
|
|
However, the process of constructing the children of a new element,
|
|
which is described in <a href=
|
|
"#constructing-complex-content"><i>5.7.1 Constructing Complex
|
|
Content</i></a>, does cause the namespaces of a parent element to
|
|
be inherited by its children unless this is prevented using
|
|
<code>[xsl:]inherit-namespaces="no"</code> on the instruction that
|
|
creates the parent element.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>This has implications on serialization, defined in <a href=
|
|
"#xslt-xquery-serialization-11">[XSLT and XQuery
|
|
Serialization]</a>. It means that it is possible to create
|
|
<a title="final result tree" class="termref" href=
|
|
"#dt-final-result-tree">final result trees</a> that cannot be
|
|
faithfully serialized as XML 1.0 documents. When such a result tree
|
|
is serialized as XML 1.0, namespace declarations written for the
|
|
parent element will be inherited by its child elements as if the
|
|
corresponding namespace nodes were present on the child element,
|
|
except in the case of the default namespace, which can be
|
|
undeclared using the construct <code>xmlns=""</code>. When the same
|
|
result tree is serialized as XML 1.1, however, it is possible to
|
|
undeclare any namespace on the child element (for example,
|
|
<code>xmlns:foo=""</code>) to prevent this inheritance taking
|
|
place.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="uri-references" id="uri-references"></a>5.8 <a href=
|
|
"#uri-references" style="text-decoration: none">URI
|
|
References</a></h3>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-uri-reference" id="dt-uri-reference" title=
|
|
"URI Reference"></a>Within this specification, the term <b>URI
|
|
Reference</b>, unless otherwise stated, refers to a string in the
|
|
lexical space of the <code>xs:anyURI</code> data type as defined in
|
|
<a href="#xmlschema-2">[XML Schema Part 2]</a>.<span class=
|
|
"definition">]</span> Note that this is a wider definition than
|
|
that in <a href="#RFC3986">[RFC3986]</a>: in particular, it is
|
|
designed to accommodate Internationalized Resource Identifiers
|
|
(IRIs) as described in <a href="#RFC3987">[RFC3987]</a>, and thus
|
|
allows the use of non-ASCII characters without escaping.</p>
|
|
<p>URI References are used in XSLT with three main roles:</p>
|
|
<ul>
|
|
<li>
|
|
<p>As namespace URIs</p>
|
|
</li>
|
|
<li>
|
|
<p>As collation URIs</p>
|
|
</li>
|
|
<li>
|
|
<p>As identifiers for resources such as stylesheet modules; these
|
|
resources are typically accessible using a protocol such as HTTP.
|
|
Examples of such identifiers are the URIs used in the
|
|
<code>href</code> attributes of <a href=
|
|
"#element-import"><code>xsl:import</code></a>, <a href=
|
|
"#element-include"><code>xsl:include</code></a>, and <a href=
|
|
"#element-result-document"><code>xsl:result-document</code></a>.</p>
|
|
</li>
|
|
</ul>
|
|
<p>The rules for namespace URIs are given in <a href=
|
|
"#xml-names">[Namespaces in XML]</a> and <a href=
|
|
"#xml-names11">[Namespaces in XML 1.1]</a>. Those specifications
|
|
deprecate the use of relative URI <span>references</span> as
|
|
namespace URIs.</p>
|
|
<p>The rules for collation URIs are given in <a href=
|
|
"#xpath-functions-11">[Functions and Operators]</a>.</p>
|
|
<p>URI references used to identify external resources must conform
|
|
to the same rules as the locator attribute (<code>href</code>)
|
|
defined in section 5.4 of <a href="#xlink">[XLink]</a>. If the URI
|
|
reference is relative, then it is resolved (unless otherwise
|
|
specified) against the base URI of the containing element node,
|
|
according to the rules of <a href="#RFC3986">[RFC3986]</a>, after
|
|
first escaping all characters that need to be escaped to make it a
|
|
valid RFC3986 URI reference. (But a relative URI
|
|
<span>reference</span> in the <code>href</code> attribute of
|
|
<a href=
|
|
"#element-result-document"><code>xsl:result-document</code></a> is
|
|
resolved against the <a title="base output URI" class="termref"
|
|
href="#dt-base-output-uri">Base Output URI</a>.)</p>
|
|
<p>Other URI references appearing in an XSLT stylesheet document,
|
|
for example the system identifiers of external entities or the
|
|
value of the <code>xml:base</code> attribute, must follow the rules
|
|
in their respective specifications.</p>
|
|
</div>
|
|
</div>
|
|
<div class="div1">
|
|
<h2><a name="rules" id="rules"></a>6 <a href="#rules" style=
|
|
"text-decoration: none">Template Rules</a></h2>
|
|
<p>Template rules define the processing that can be applied to
|
|
<span>items</span> that match a particular <a title="pattern"
|
|
class="termref" href="#dt-pattern">pattern</a>.</p>
|
|
<div class="div2">
|
|
<h3><a name="defining-templates" id="defining-templates"></a>6.1
|
|
<a href="#defining-templates" style=
|
|
"text-decoration: none">Defining Templates</a></h3>
|
|
<p class="element-syntax"><a name="element-template" id=
|
|
"element-template"></a><code><!-- Category: declaration
|
|
--><br />
|
|
<xsl:template<br />
|
|
  match? = <var>pattern</var><br />
|
|
  name? = <var>qname</var><br />
|
|
  priority? = <var>number</var><br />
|
|
  mode? = <var>tokens</var><br />
|
|
  as? = <var>sequence-type</var> ><br />
|
|
  <!-- Content: (<a href=
|
|
"#element-param">xsl:param</a>*, <var>sequence-constructor</var>)
|
|
--><br />
|
|
</xsl:template></code></p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-template" id="dt-template" title="template"></a>An <a href=
|
|
"#element-template"><code>xsl:template</code></a> declaration
|
|
defines a <b>template</b>, which contains a <a title=
|
|
"sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> for creating
|
|
nodes, atomic values, <span>and/or function items</span>. A
|
|
template can serve either as a <a title="template rule" class=
|
|
"termref" href="#dt-template-rule">template rule</a>, invoked by
|
|
matching <span>items</span> against a <a title="pattern" class=
|
|
"termref" href="#dt-pattern">pattern</a>, or as a <a title=
|
|
"named template" class="termref" href="#dt-named-template">named
|
|
template</a>, invoked explicitly by name. It is also possible for
|
|
the same template to serve in both capacities.<span class=
|
|
"definition">]</span></p>
|
|
<p><a name="err-XTSE0500" id="err-XTSE0500"><span class=
|
|
"error">[ERR XTSE0500]</span></a> An <a href=
|
|
"#element-template"><code>xsl:template</code></a> element
|
|
<span class="verb">must</span> have either a <code>match</code>
|
|
attribute or a <code>name</code> attribute, or both. An <a href=
|
|
"#element-template"><code>xsl:template</code></a> element that has
|
|
no <code>match</code> attribute <span class="verb">must</span> have
|
|
no <code>mode</code> attribute and no <code>priority</code>
|
|
attribute.</p>
|
|
<p>If an <a href="#element-template"><code>xsl:template</code></a>
|
|
element has a <code>match</code> attribute, then it is a <a title=
|
|
"template rule" class="termref" href="#dt-template-rule">template
|
|
rule</a>. If it has a <code>name</code> attribute, then it is a
|
|
<a title="named template" class="termref" href=
|
|
"#dt-named-template">named template</a>.</p>
|
|
<p>A <a title="template" class="termref" href=
|
|
"#dt-template">template</a> may be invoked in a number of ways,
|
|
depending on whether it is a <a title="template rule" class=
|
|
"termref" href="#dt-template-rule">template rule</a>, a <a title=
|
|
"named template" class="termref" href="#dt-named-template">named
|
|
template</a>, or both. The result of invoking the template is the
|
|
result of evaluating the <a title="sequence constructor" class=
|
|
"termref" href="#dt-sequence-constructor">sequence constructor</a>
|
|
contained in the <a href=
|
|
"#element-template"><code>xsl:template</code></a> element (see
|
|
<a href="#sequence-constructors"><i>5.7 Sequence
|
|
Constructors</i></a>).</p>
|
|
<p>If an <code>as</code> attribute is present, the <code>as</code>
|
|
attribute defines the required type of the result. The result of
|
|
evaluating the <a title="sequence constructor" class="termref"
|
|
href="#dt-sequence-constructor">sequence constructor</a> is then
|
|
converted to the required type using the <a title=
|
|
"function conversion rules" class="termref" href=
|
|
"#dt-function-conversion-rules">function conversion rules</a>. If
|
|
no <code>as</code> attribute is specified, the default value is
|
|
<code>item()*</code>, which permits any value. No conversion then
|
|
takes place.</p>
|
|
<p><a name="err-XTTE0505" id="err-XTTE0505"><span class=
|
|
"error">[ERR XTTE0505]</span></a> It is a <a title="type errors"
|
|
class="termref" href="#dt-type-error">type error</a> if the result
|
|
of evaluating the <a title="sequence constructor" class="termref"
|
|
href="#dt-sequence-constructor">sequence constructor</a> cannot be
|
|
converted to the required type.</p>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="defining-template-rules" id=
|
|
"defining-template-rules"></a>6.2 <a href=
|
|
"#defining-template-rules" style="text-decoration: none">Defining
|
|
Template Rules</a></h3>
|
|
<p>This section describes <a title="template rule" class="termref"
|
|
href="#dt-template-rule">template rules</a>. <a title=
|
|
"named template" class="termref" href="#dt-named-template">Named
|
|
templates</a> are described in <a href="#named-templates"><i>10.1
|
|
Named Templates</i></a>.</p>
|
|
<p>A <a title="template rule" class="termref" href=
|
|
"#dt-template-rule">template rule</a> is specified using the
|
|
<a href="#element-template"><code>xsl:template</code></a> element
|
|
with a <code>match</code> attribute. The <code>match</code>
|
|
attribute is a <a href="#NT-Pattern">Pattern</a> that identifies
|
|
the <span>items</span> to which the rule applies. The result of
|
|
applying the template rule is the result of evaluating the sequence
|
|
constructor contained in the <a href=
|
|
"#element-template"><code>xsl:template</code></a> element, with the
|
|
matching <span>item</span> used as the <span><a title=
|
|
"context item" class="termref" href="#dt-context-item">context
|
|
item</a></span>.</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e11801" id=
|
|
"d7e11801"></a>Example: A simple Template Rule</div>
|
|
<p>For example, an XML document might contain:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
This is an <emph>important</emph> point.
|
|
</pre></div>
|
|
<p>The following <a title="template rule" class="termref" href=
|
|
"#dt-template-rule">template rule</a> matches <code>emph</code>
|
|
elements and produces a <code>fo:wrapper</code> element with a
|
|
<code>font-weight</code> property of <code>bold</code>.</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:template match="emph">
|
|
<fo:wrapper font-weight="bold"
|
|
xmlns:fo="http://www.w3.org/1999/XSL/Format">
|
|
<xsl:apply-templates/>
|
|
</fo:wrapper>
|
|
</xsl:template>
|
|
</pre></div>
|
|
</div>
|
|
<p>A <a title="template rule" class="termref" href=
|
|
"#dt-template-rule">template rule</a> is evaluated when an <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>
|
|
instruction selects <span>an item</span> that matches the pattern
|
|
specified in the <code>match</code> attribute. The <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>
|
|
instruction is described in the next section. If several template
|
|
rules match a selected <span>item</span>, only one of them is
|
|
evaluated, as described in <a href="#conflict"><i>6.4 Conflict
|
|
Resolution for Template Rules</i></a>.</p>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="applying-templates" id="applying-templates"></a>6.3
|
|
<a href="#applying-templates" style=
|
|
"text-decoration: none">Applying Template Rules</a></h3>
|
|
<p class="element-syntax"><a name="element-apply-templates" id=
|
|
"element-apply-templates"></a><code><!-- Category: instruction
|
|
--><br />
|
|
<xsl:apply-templates<br />
|
|
  select? = <var>expression</var><br />
|
|
  mode? = <var>token</var> ><br />
|
|
  <!-- Content: (<a href="#element-sort">xsl:sort</a>
|
|
| <a href="#element-with-param">xsl:with-param</a>)* --><br />
|
|
</xsl:apply-templates></code></p>
|
|
<p>The <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>
|
|
instruction takes as input a sequence of <span>items</span>
|
|
(typically nodes in a <a title="source tree" class="termref" href=
|
|
"#dt-source-tree">source tree</a>), and produces as output a
|
|
sequence of items; these will often be nodes to be added to a
|
|
<a title="result tree" class="termref" href=
|
|
"#dt-result-tree">result tree</a>.</p>
|
|
<p>If the instruction has one or more <a href=
|
|
"#element-sort"><code>xsl:sort</code></a> children, then the input
|
|
sequence is sorted as described in <a href="#sorting"><i>13
|
|
Sorting</i></a>. The result of this sort is referred to below as
|
|
the <b>sorted sequence</b>; if there are no <a href=
|
|
"#element-sort"><code>xsl:sort</code></a> elements, then the sorted
|
|
sequence is the same as the input sequence.</p>
|
|
<p>Each <span>item</span> in the input sequence is processed by
|
|
finding a <a title="template rule" class="termref" href=
|
|
"#dt-template-rule">template rule</a> whose <a title="pattern"
|
|
class="termref" href="#dt-pattern">pattern</a> matches that
|
|
<span>item</span>. If there is more than one such template rule,
|
|
the best among them is chosen, using rules described in <a href=
|
|
"#conflict"><i>6.4 Conflict Resolution for Template Rules</i></a>.
|
|
If there is no template rule whose pattern matches the
|
|
<span>item</span>, a built-in template rule is used (see <a href=
|
|
"#built-in-rule"><i>6.7 Built-in Template Rules</i></a>). The
|
|
chosen template rule is evaluated. The rule that matches the
|
|
<var>N</var>th <span>item</span> in the sorted sequence is
|
|
evaluated with that <span>item</span> as the <a title=
|
|
"context item" class="termref" href="#dt-context-item">context
|
|
item</a>, with <var>N</var> as the <a title="context position"
|
|
class="termref" href="#dt-context-position">context position</a>,
|
|
and with the length of the sorted sequence as the <a title=
|
|
"context size" class="termref" href="#dt-context-size">context
|
|
size</a>. Each template rule that is evaluated produces a sequence
|
|
of items as its result. The resulting sequences (one for each
|
|
<span>item</span> in the sorted sequence) are then concatenated, to
|
|
form a single sequence. They are concatenated retaining the order
|
|
of the <span>items</span> in the sorted sequence. The final
|
|
concatenated sequence forms the result of the <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>
|
|
instruction.</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e11944" id=
|
|
"d7e11944"></a>Example: Applying Template Rules</div>
|
|
<p>Suppose the source document is as follows:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<message>Proceed <emph>at once</emph> to the exit!</message>
|
|
</pre></div>
|
|
<p>This can be processed using the two template rules shown
|
|
below.</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:template match="message">
|
|
<p>
|
|
<xsl:apply-templates select="child::node()"/>
|
|
</p>
|
|
</xsl:template>
|
|
|
|
<xsl:template match="emph">
|
|
<b>
|
|
<xsl:apply-templates select="child::node()"/>
|
|
</b>
|
|
</xsl:template>
|
|
</pre></div>
|
|
<p>There is no template rule for the document node; the built-in
|
|
template rule for this node will cause the <code>message</code>
|
|
element to be processed. The template rule for the
|
|
<code>message</code> element causes a <code>p</code> element to be
|
|
written to the <a title="result tree" class="termref" href=
|
|
"#dt-result-tree">result tree</a>; the contents of this
|
|
<code>p</code> element are constructed as the result of the
|
|
<a href="#element-apply-templates"><code>xsl:apply-templates</code></a>
|
|
instruction. This instruction selects the three child nodes of the
|
|
<code>message</code> element (a text node containing the value
|
|
"<code>Proceed</code> ", an <code>emph</code> element node, and a
|
|
text node containing the value " <code>to the exit!</code>"). The
|
|
two text nodes are processed using the built-in template rule for
|
|
text nodes, which returns a copy of the text node. The
|
|
<code>emph</code> element is processed using the explicit template
|
|
rule that specifies <code>match="emph"</code>.</p>
|
|
<p>When the <code>emph</code> element is processed, this template
|
|
rule constructs a <code>b</code> element. The contents of the
|
|
<code>b</code> element are constructed by means of another <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>
|
|
instruction, which in this case selects a single node (the text
|
|
node containing the value "<code>at once</code>"). This is again
|
|
processed using the built-in template rule for text nodes, which
|
|
returns a copy of the text node.</p>
|
|
<p>The final result of the <code>match="message"</code> template
|
|
rule thus consists of a <code>p</code> element node with three
|
|
children: a text node containing the value "<code>Proceed</code> ",
|
|
a <code>b</code> element that is the parent of a text node
|
|
containing the value "<code>at once</code>", and a text node
|
|
containing the value " <code>to the exit!</code>". This <a title=
|
|
"result tree" class="termref" href="#dt-result-tree">result
|
|
tree</a> might be serialized as:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<p>Proceed <b>at once</b> to the exit!</p>
|
|
</pre></div>
|
|
</div>
|
|
<p>The default value of the <code>select</code> attribute is
|
|
<code>child::node()</code>, which causes all the children of the
|
|
context node to be processed.</p>
|
|
<p><a name="err-XTTE0510" id="err-XTTE0510"><span class=
|
|
"error">[ERR XTTE0510]</span></a> It is a <a title="type errors"
|
|
class="termref" href="#dt-type-error">type error</a> if an <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>
|
|
instruction with no <code>select</code> attribute is evaluated when
|
|
the <a title="context item" class="termref" href=
|
|
"#dt-context-item">context item</a> is not a node.</p>
|
|
<p>A <code>select</code> attribute can be used to process
|
|
<span>items</span> selected by an expression instead of processing
|
|
all children. The value of the <code>select</code> attribute is an
|
|
<a title="expression" class="termref" href=
|
|
"#dt-expression">expression</a>.</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e12108" id=
|
|
"d7e12108"></a>Example: Applying Templates to Selected Nodes</div>
|
|
<p>The following example processes all of the
|
|
<code>given-name</code> children of the <code>author</code>
|
|
elements that are children of <code>author-group</code>:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:template match="author-group">
|
|
<fo:wrapper>
|
|
<xsl:apply-templates select="author/given-name"/>
|
|
</fo:wrapper>
|
|
</xsl:template>
|
|
</pre></div>
|
|
</div>
|
|
<p> </p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e12124" id=
|
|
"d7e12124"></a>Example: Applying Templates to Nodes that are not
|
|
Descendants</div>
|
|
<p>It is also possible to process elements that are not descendants
|
|
of the context node. This example assumes that a
|
|
<code>department</code> element has <code>group</code> children and
|
|
<code>employee</code> descendants. It finds an employee's
|
|
department and then processes the <code>group</code> children of
|
|
the <code>department</code>.</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<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>
|
|
</pre></div>
|
|
</div>
|
|
<p> </p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e12146" id=
|
|
"d7e12146"></a>Example: Matching Nodes by Schema-Defined
|
|
Types</div>
|
|
<p>It is possible to write template rules that are matched
|
|
according to the schema-defined type of an element or attribute.
|
|
The following example applies different formatting to the children
|
|
of an element depending on their type:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:template match="product">
|
|
<table>
|
|
<xsl:apply-templates select="*"/>
|
|
</table>
|
|
</xsl:template>
|
|
|
|
<xsl:template match="product/*" priority="3">
|
|
<tr>
|
|
<td><xsl:value-of select="name()"/></td>
|
|
<td><xsl:next-match/></td>
|
|
</tr>
|
|
</xsl:template>
|
|
|
|
<xsl:template match="product/element(*, xs:decimal) |
|
|
product/element(*, xs:double)" priority="2">
|
|
<xsl:value-of select="format-number(xs:double(.), '#,###0.00')"/>
|
|
</xsl:template>
|
|
|
|
<xsl:template match="product/element(*, xs:date)" priority="2">
|
|
<xsl:value-of select="format-date(., '[Mn] [D], [Y]')"/>
|
|
</xsl:template>
|
|
|
|
<xsl:template match="product/*" priority="1.5">
|
|
<xsl:value-of select="."/>
|
|
</xsl:template>
|
|
</pre></div>
|
|
<p>The <a href=
|
|
"#element-next-match"><code>xsl:next-match</code></a> instruction
|
|
is described in <a href="#apply-imports"><i>6.8 Overriding Template
|
|
Rules</i></a>.</p>
|
|
</div>
|
|
<p> </p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e12160" id=
|
|
"d7e12160"></a>Example: Re-ordering Elements in the Result
|
|
Tree</div>
|
|
<p>Multiple <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>
|
|
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.</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:template match="product">
|
|
<table>
|
|
<xsl:apply-templates select="sales/domestic"/>
|
|
</table>
|
|
<table>
|
|
<xsl:apply-templates select="sales/foreign"/>
|
|
</table>
|
|
</xsl:template>
|
|
</pre></div>
|
|
</div>
|
|
<p> </p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e12170" id=
|
|
"d7e12170"></a>Example: Processing Recursive Structures</div>
|
|
<p>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.</p>
|
|
<p>For example, given a source document</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<doc><div><div></div></div></doc>
|
|
</pre></div>
|
|
<p>the rule</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:template match="doc">
|
|
<xsl:apply-templates select=".//div"/>
|
|
</xsl:template>
|
|
</pre></div>
|
|
<p>will process both the outer <code>div</code> and inner
|
|
<code>div</code> elements.</p>
|
|
<p>This means that if the template rule for the <code>div</code>
|
|
element processes its own children, then these grandchildren will
|
|
be processed more than once, which is probably not what is
|
|
required. The solution is to process one level at a time in a
|
|
recursive descent, by using <code>select="div"</code> in place of
|
|
<code>select=".//div"</code></p>
|
|
</div>
|
|
<p> </p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e12202" id=
|
|
"d7e12202"></a>Example: Applying Templates to Atomic Values</div>
|
|
<p>This example reads a non-XML text file and processes it
|
|
line-by-line, applying different template rules based on the
|
|
content of each line:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:template name="main">
|
|
<xsl:apply-templates select="unparsed-text-lines('input.txt')"/>
|
|
</xsl:template>
|
|
|
|
<xsl:template match="~xs:string[starts-with(., '==')]">
|
|
<h2><xsl:value-of select="replace(., '==', '')"/></h2>
|
|
</xsl:template>
|
|
|
|
<xsl:template match="~xs:string[starts-with(., '::')]">
|
|
<p class="indent"><xsl:value-of select="replace(., '::', '')"/></p>
|
|
</xsl:template>
|
|
|
|
<xsl:template match="~xs:string">
|
|
<p class="body"><xsl:value-of select="."/></p>
|
|
</xsl:template>
|
|
|
|
</pre></div>
|
|
</div>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>The <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>
|
|
instruction is most commonly used to process nodes that are
|
|
descendants of the context node. Such use of <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>
|
|
cannot result in non-terminating processing loops. However, when
|
|
<a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a> is
|
|
used to process elements that are not descendants of the context
|
|
node, the possibility arises of non-terminating loops. For
|
|
example,</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:template match="foo">
|
|
<xsl:apply-templates select="."/>
|
|
</xsl:template>
|
|
</pre></div>
|
|
<p>Implementations may be able to detect such loops in some cases,
|
|
but the possibility exists that a <a title="stylesheet" class=
|
|
"termref" href="#dt-stylesheet">stylesheet</a> may enter a
|
|
non-terminating loop that an implementation is unable to detect.
|
|
This may present a denial of service security risk.</p>
|
|
</div>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="conflict" id="conflict"></a>6.4 <a href="#conflict"
|
|
style="text-decoration: none">Conflict Resolution for Template
|
|
Rules</a></h3>
|
|
<p>It is possible for <span>a selected item</span> to match more
|
|
than one <a title="template rule" class="termref" href=
|
|
"#dt-template-rule">template rule</a> with a given <a title="mode"
|
|
class="termref" href="#dt-mode">mode</a> <var>M</var>. When this
|
|
happens, only one template rule is evaluated for the
|
|
<span>item</span>. The template rule to be used is determined as
|
|
follows:</p>
|
|
<ol class="enumar">
|
|
<li>
|
|
<p>First, only the matching template rule or rules with the highest
|
|
<a title="import precedence" class="termref" href=
|
|
"#dt-import-precedence">import precedence</a> are considered. Other
|
|
matching template rules with lower precedence are eliminated from
|
|
consideration.</p>
|
|
</li>
|
|
<li>
|
|
<p>Next, of the remaining matching rules, only those with the
|
|
highest priority are considered. Other matching template rules with
|
|
lower priority are eliminated from consideration.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-priority" id="dt-priority" title="priority"></a>The
|
|
<b>priority</b> of a template rule is specified by the
|
|
<code>priority</code> attribute on the <a href=
|
|
"#element-template"><code>xsl:template</code></a> declaration. If
|
|
no priority is specified explicitly for a template rule, its
|
|
<a title="default priority" class="termref" href=
|
|
"#dt-default-priority">default priority</a> is used, as defined in
|
|
<a href="#default-priority"><i>6.5 Default Priority for Template
|
|
Rules</i></a>.<span class="definition">]</span></p>
|
|
<p><a name="err-XTSE0530" id="err-XTSE0530"><span class=
|
|
"error">[ERR XTSE0530]</span></a> The value of the
|
|
<code>priority</code> attribute <span class="verb">must</span>
|
|
conform to the rules for the <code>xs:decimal</code> type defined
|
|
in <a href="#xmlschema-2">[XML Schema Part 2]</a>. Negative values
|
|
are permitted.</p>
|
|
</li>
|
|
<li>
|
|
<p>If this leaves more than one matching template rule, then:</p>
|
|
<ol class="enumla">
|
|
<li>
|
|
<p>If the <a title="mode" class="termref" href="#dt-mode">mode</a>
|
|
<var>M</var> has an <a href=
|
|
"#element-mode"><code>xsl:mode</code></a> declaration, and the
|
|
attribute value <code>on-multiple-match="fail"</code> is specified
|
|
in the mode declaration, a dynamic error is signalled. The error is
|
|
treated as occurring in the <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>
|
|
instruction, and can be recovered by wrapping that instruction in
|
|
an <a href="#element-try"><code>xsl:try</code></a> instruction.</p>
|
|
<p><a name="err-XTRE0540" id="err-XTRE0540"><span class=
|
|
"error">[ERR XTRE0540]</span></a> It is a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> if the
|
|
conflict resolution algorithm for template rules leaves more than
|
|
one matching template rule <span>when the declaration of the
|
|
relevant <a title="mode" class="termref" href="#dt-mode">mode</a>
|
|
has in <code>on-multiple-match</code> attribute with the value
|
|
<code>fail</code></span>.</p>
|
|
</li>
|
|
<li>
|
|
<p>Otherwise, of the matching template rules that remain, the one
|
|
that occurs last in <a title="declaration order" class="termref"
|
|
href="#dt-declaration-order">declaration order</a> is used.</p>
|
|
</li>
|
|
</ol>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>This was a recoverable error in XSLT 2.0, meaning that it was
|
|
implementation-defined whether the error was signaled, or whether
|
|
the ambiguity was resolved by taking the last matching rule in
|
|
declaration order. The choice of error code reflects this legacy.
|
|
In XSLT 2.1 this situation is not an error unless the attribute
|
|
value <code>on-multiple-match="fail"</code> is specified in the
|
|
mode declaration. It is also possible to request warnings when this
|
|
condition arises, by means of the attribute
|
|
<span><code>warnings-on-multiple-match="yes"</code></span>.</p>
|
|
</div>
|
|
<blockquote>
|
|
<p><b><a name="issue-define-warning-codes" id=
|
|
"issue-define-warning-codes">Issue 8
|
|
(define-warning-codes)</a>:</b></p>
|
|
<p>Should we define warning codes in the same way as we define
|
|
error codes?</p>
|
|
</blockquote>
|
|
</li>
|
|
</ol>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="default-priority" id="default-priority"></a>6.5
|
|
<a href="#default-priority" style="text-decoration: none">Default
|
|
Priority for Template Rules</a></h3>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-default-priority" id="dt-default-priority" title=
|
|
"default priority"></a>If no <code>priority</code> attribute is
|
|
specified on an <a href=
|
|
"#element-template"><code>xsl:template</code></a> element, a
|
|
<b>default priority</b> is computed, based on the syntax of the
|
|
<a title="pattern" class="termref" href="#dt-pattern">pattern</a>
|
|
supplied in the <code>match</code> attribute.<span class=
|
|
"definition">]</span> The rules are as follows.</p>
|
|
<ol class="enumar">
|
|
<li>
|
|
<p>If the top-level pattern consists of multiple alternatives
|
|
separated by <code>|</code> , then the template rule is treated
|
|
equivalently to a set of template rules, one for each alternative.
|
|
However, it is not an error if an <span>item</span> matches more
|
|
than one of the alternatives.</p>
|
|
</li>
|
|
<li>
|
|
<p>If the top-level pattern is a <a href=
|
|
"#NT-PatternTerm">PatternTerm</a> containing two or more <a href=
|
|
"#NT-BasicPattern">BasicPatterns</a> separated by
|
|
<code>intersect</code> or <code>except</code> operators, then the
|
|
priority of the pattern is that of the first <a href=
|
|
"#NT-BasicPattern">BasicPattern</a>.</p>
|
|
</li>
|
|
<li>
|
|
<p>If the pattern (in its entirety) is a <a href=
|
|
"#NT-TypePattern">TypePattern</a> with an empty <a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-PredicateList">PredicateList</a><sup><small>XP21</small></sup>,
|
|
then:</p>
|
|
<ol class="enumla">
|
|
<li>
|
|
<p>If the <a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-ItemType">ItemType</a><sup><small>XP21</small></sup>
|
|
is <code>item()</code>, the priority is −2 (minus two).</p>
|
|
</li>
|
|
<li>
|
|
<p>If the <a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-ItemType">ItemType</a><sup><small>XP21</small></sup>
|
|
is <code>node()</code>, <code>function()</code>, or
|
|
<code>xs:anyAtomicType</code>, the priority is −1 (minus one).</p>
|
|
</li>
|
|
<li>
|
|
<p>If the <a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-ItemType">ItemType</a><sup><small>XP21</small></sup>
|
|
is any other atomic type, the priority is the priority associated
|
|
with its base type plus 1. This means for example that the priority
|
|
of <code>~xs:decimal</code> is 0 (zero), and the priority of
|
|
<code>~xs:integer</code> is +1 (plus one).</p>
|
|
</li>
|
|
<li>
|
|
<p>If the <a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-ItemType">ItemType</a><sup><small>XP21</small></sup>
|
|
is any other <a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-NodeTest">NodeTest</a><sup><small>XP21</small></sup>,
|
|
the priority is the same as when that NodeTest appears as a pattern
|
|
in its own right (see below). For example, the priority of
|
|
<code>~element()</code> is −0.5 (minus 0.5), while that of
|
|
<code>~element(E)</code> is 0 (zero).</p>
|
|
</li>
|
|
<li>
|
|
<p>If the <a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-ItemType">ItemType</a><sup><small>XP21</small></sup>
|
|
is a <a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-TypedFunctionTest">TypedFunctionTest</a><sup><small>XP21</small></sup>,
|
|
the priority is 0 (zero).</p>
|
|
</li>
|
|
</ol>
|
|
</li>
|
|
<li>
|
|
<p>If the pattern (in its entirety) is a <a href=
|
|
"#NT-TypePattern">TypePattern</a> with a non-empty <a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-PredicateList">PredicateList</a><sup><small>XP21</small></sup>,
|
|
then the priority is that of the <a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-ItemType">ItemType</a><sup><small>XP21</small></sup>
|
|
in the absence of the <a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-PredicateList">PredicateList</a><sup><small>XP21</small></sup>,
|
|
as given above, plus 0.5. So, for example, the priority of the
|
|
pattern <code>~xs:integer[. gt 0]</code> is +1.5.</p>
|
|
</li>
|
|
<li>
|
|
<p>If the pattern is a <a href="#NT-PathPattern">PathPattern</a>
|
|
taking the form <code>/</code>, then the priority is −0.5 (minus
|
|
0.5).</p>
|
|
</li>
|
|
<li>
|
|
<p>If the pattern is a <a href="#NT-PathPattern">PathPattern</a>
|
|
taking the form of a <a title="QName" class="termref" href=
|
|
"#dt-qname">QName</a> optionally preceded by a <a href=
|
|
"#NT-PatternAxis">PatternAxis</a> or has the form
|
|
<code>processing-instruction(</code> <a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-StringLiteral">StringLiteral</a><sup><small>XP21</small></sup>
|
|
<code>)</code> or <code>processing-instruction(</code> <a href=
|
|
"http://www.w3.org/TR/REC-xml-names/#NT-NCName">NCName</a><sup><small>Names</small></sup>
|
|
<code>)</code> optionally preceded by a <a href=
|
|
"#NT-PatternAxis">PatternAxis</a>, then the priority is 0
|
|
(zero).</p>
|
|
</li>
|
|
<li>
|
|
<p>If the pattern is a <a href="#NT-PathPattern">PathPattern</a>
|
|
taking the form of an <a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-ElementTest">ElementTest</a><sup><small>XP21</small></sup>
|
|
or <a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-AttributeTest">AttributeTest</a><sup><small>XP21</small></sup>,
|
|
optionally preceded by a <a href="#NT-PatternAxis">PatternAxis</a>,
|
|
then the priority is as shown in the table below. In this table,
|
|
the symbols <var>E</var>, <var>A</var>, and <var>T</var> represent
|
|
an arbitrary element name, attribute name, and type name
|
|
respectively, while the symbol <code>*</code> represents itself.
|
|
The presence or absence of the symbol <code>?</code> following a
|
|
type name does not affect the priority.</p>
|
|
<table border="1" cellpadding="5">
|
|
<thead>
|
|
<tr>
|
|
<th align="left" colspan="1">Format</th>
|
|
<th align="left" colspan="1">Priority</th>
|
|
<th align="left" colspan="1">Notes</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td><code>element()</code></td>
|
|
<td>−0.5</td>
|
|
<td>(equivalent to <code>*</code>)</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>element(*)</code></td>
|
|
<td>−0.5</td>
|
|
<td>(equivalent to <code>*</code>)</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>attribute()</code></td>
|
|
<td>−0.5</td>
|
|
<td>(equivalent to <code>@*</code>)</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>attribute(*)</code></td>
|
|
<td>−0.5</td>
|
|
<td>(equivalent to <code>@*</code>)</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>element(<var>E</var>)</code></td>
|
|
<td>0</td>
|
|
<td>(equivalent to E)</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>element(*,<var>T</var>)</code></td>
|
|
<td>0</td>
|
|
<td>(matches by type only)</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>attribute(<var>A</var>)</code></td>
|
|
<td>0</td>
|
|
<td>(equivalent to <code>@A</code>)</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>attribute(*,<var>T</var>)</code></td>
|
|
<td>0</td>
|
|
<td>(matches by type only)</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>element(<var>E</var>,<var>T</var>)</code></td>
|
|
<td>0.25</td>
|
|
<td>(matches by name and type)</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>schema-element(<var>E</var>)</code></td>
|
|
<td>0.25</td>
|
|
<td>(matches by substitution group and type)</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>attribute(<var>A</var>,<var>T</var>)</code></td>
|
|
<td>0.25</td>
|
|
<td>(matches by name and type)</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>schema-attribute(<var>A</var>)</code></td>
|
|
<td>0.25</td>
|
|
<td>(matches by name and type)</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</li>
|
|
<li>
|
|
<p>If the pattern is a <a href="#NT-PathPattern">PathPattern</a>
|
|
taking the form of a <a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-DocumentTest">DocumentTest</a><sup><small>XP21</small></sup>,
|
|
then if it includes no <a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-ElementTest">ElementTest</a><sup><small>XP21</small></sup>
|
|
or <a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-SchemaElementTest">SchemaElementTest</a><sup><small>XP21</small></sup>
|
|
the priority is −0.5. If it does include an <a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-ElementTest">ElementTest</a><sup><small>XP21</small></sup>
|
|
or <a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-SchemaElementTest">SchemaElementTest</a><sup><small>XP21</small></sup>,
|
|
then the priority is the same as the priority of that <a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-ElementTest">ElementTest</a><sup><small>XP21</small></sup>
|
|
or <a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-SchemaElementTest">SchemaElementTest</a><sup><small>XP21</small></sup>,
|
|
computed according to the table above.</p>
|
|
</li>
|
|
<li>
|
|
<p>If the pattern is a <a href="#NT-PathPattern">PathPattern</a>
|
|
taking the form of an <a href=
|
|
"http://www.w3.org/TR/REC-xml-names/#NT-NCName">NCName</a><sup><small>Names</small></sup><code>:*</code>
|
|
or <code>*:</code><a href=
|
|
"http://www.w3.org/TR/REC-xml-names/#NT-NCName">NCName</a><sup><small>Names</small></sup>,
|
|
optionally preceded by a <a href="#NT-PatternAxis">PatternAxis</a>,
|
|
then the priority is −0.25.</p>
|
|
</li>
|
|
<li>
|
|
<p>If the pattern is a <a href="#NT-PathPattern">PathPattern</a>
|
|
taking the form of any other <a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-NodeTest">NodeTest</a><sup><small>XP21</small></sup>,
|
|
optionally preceded by a <a href="#NT-PatternAxis">PatternAxis</a>,
|
|
then the priority is −0.5.</p>
|
|
</li>
|
|
<li>
|
|
<p>In all other cases, the priority is +0.5.</p>
|
|
</li>
|
|
</ol>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>In many cases this means that highly selective patterns have
|
|
higher priority than less selective patterns. The most common kind
|
|
of pattern (a pattern that tests for a node of a particular kind,
|
|
with a particular <a title="expanded-QName" class="termref" href=
|
|
"#dt-expanded-qname">expanded-QName</a> or a particular type) has
|
|
priority 0. The next less specific kind of pattern (a pattern that
|
|
tests for a node of a particular kind and an <a title=
|
|
"expanded-QName" class="termref" href=
|
|
"#dt-expanded-qname">expanded-QName</a> with a particular namespace
|
|
URI) has priority −0.25. Patterns less specific than this (patterns
|
|
that just test for nodes of a given kind) have priority −0.5.
|
|
Patterns that specify both the name and the required type have a
|
|
priority of +0.25, putting them above patterns that only specify
|
|
the name <em>or</em> the type. Patterns more specific than this,
|
|
for example patterns that include predicates or that specify the
|
|
ancestry of the required node, have priority 0.5.</p>
|
|
<p>In the case of a <a href="#NT-TypePattern">TypePattern</a>, the
|
|
default priority reflects the position of the type in the type
|
|
hierarchy.</p>
|
|
<p>However, it is not invariably true that a more selective pattern
|
|
has higher priority than a less selective pattern. For example, the
|
|
priority of the pattern <code>node()[self::*]</code> is higher than
|
|
that of the pattern <code>salary</code>. Similarly, the patterns
|
|
<code>attribute(*, xs:decimal)</code> and <code>attribute(*,
|
|
xs:short)</code> have the same priority, despite the fact that the
|
|
latter pattern matches a subset of the nodes matched by the former.
|
|
Therefore, to achieve clarity in a <a title="stylesheet" class=
|
|
"termref" href="#dt-stylesheet">stylesheet</a> it is good practice
|
|
to allocate explicit priorities.</p>
|
|
</div>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="modes" id="modes"></a>6.6 <a href="#modes" style=
|
|
"text-decoration: none">Modes</a></h3>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-mode" id="dt-mode" title="mode"></a> <b>Modes</b> allow a node
|
|
in a <a title="source tree" class="termref" href=
|
|
"#dt-source-tree">source tree</a> to be processed multiple times,
|
|
each time producing a different result. They also allow different
|
|
sets of <a title="template rule" class="termref" href=
|
|
"#dt-template-rule">template rules</a> to be active when processing
|
|
different trees, for example when processing documents loaded using
|
|
the <a href="#function-document"><code>document</code></a> function
|
|
(see <a href="#document"><i>19.1.1 The document function</i></a>)
|
|
or when processing <a title="temporary tree" class="termref" href=
|
|
"#dt-temporary-tree">temporary trees</a>.<span class=
|
|
"definition">]</span></p>
|
|
<p>Modes are identified by a <a title="QName" class="termref" href=
|
|
"#dt-qname">QName</a>; in addition to any named modes, there is
|
|
always one unnamed mode available. Whether a mode is named or
|
|
unnamed, its properties <span class="verb">may</span> be defined in
|
|
an <a href="#element-mode"><code>xsl:mode</code></a> declaration.
|
|
If a mode name is used (for example in an <a href=
|
|
"#element-template"><code>xsl:template</code></a> declaration or an
|
|
<a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>
|
|
instruction) and no declaration of that mode appears in the
|
|
stylesheet, the mode is implicitly declared with default
|
|
properties.</p>
|
|
<div class="div3">
|
|
<h4><a name="declaring-modes" id="declaring-modes"></a>6.6.1
|
|
<a href="#declaring-modes" style="text-decoration: none">Declaring
|
|
Modes</a></h4>
|
|
<p class="element-syntax"><a name="element-mode" id=
|
|
"element-mode"></a><code><!-- Category: declaration --><br />
|
|
<xsl:mode<br />
|
|
  name? = <var>qname</var><br />
|
|
  streamable? = "yes" | "no"<br />
|
|
  initial? = "yes" | "no"<br />
|
|
  on-no-match? = "stringify" | "discard" | "copy" |
|
|
"fail"<br />
|
|
  on-multiple-match? = "use-last" | "fail"<br />
|
|
  warning-on-no-match? = "yes" | "no"<br />
|
|
  warning-on-multiple-match? = "yes" |
|
|
"no" ><br />
|
|
  <!-- Content: (<a href=
|
|
"#element-context-item">xsl:context-item</a>?) --><br />
|
|
</xsl:mode></code></p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-unnamed-mode" id="dt-unnamed-mode" title=
|
|
"unnamed mode"></a>There is always an <b>unnamed mode</b>
|
|
available. The unnamed mode is the default mode used when no
|
|
<code>mode</code> attribute is specified on an <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>
|
|
instruction or <a href=
|
|
"#element-template"><code>xsl:template</code></a> declaration,
|
|
unless a different default mode has been specified using the
|
|
<code>default-mode</code> attribute of the containing <a href=
|
|
"#element-stylesheet"><code>xsl:stylesheet</code></a>
|
|
element.<span class="definition">]</span></p>
|
|
<p>Every <a title="mode" class="termref" href="#dt-mode">mode</a>
|
|
other than the <a title="unnamed mode" class="termref" href=
|
|
"#dt-unnamed-mode">unnamed mode</a> is identified by a <a title=
|
|
"QName" class="termref" href="#dt-qname">QName</a>.</p>
|
|
<p>A <a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a> may contain multiple <a href=
|
|
"#element-mode"><code>xsl:mode</code></a> declarations and may
|
|
include or import <a title="stylesheet module" class="termref"
|
|
href="#dt-stylesheet-module">stylesheet modules</a> that also
|
|
contain <a href="#element-mode"><code>xsl:mode</code></a>
|
|
declarations. The name of an <a href=
|
|
"#element-mode"><code>xsl:mode</code></a> declaration is the value
|
|
of its <code>name</code> attribute, if any.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-mode-definition" id="dt-mode-definition" title=
|
|
"mode definition"></a>All the <a href=
|
|
"#element-mode"><code>xsl:mode</code></a> declarations in a
|
|
stylesheet that share the same name are grouped into a named
|
|
<b>mode definition</b>; those that have no name are grouped into a
|
|
single unnamed mode definition.<span class=
|
|
"definition">]</span></p>
|
|
<p>If a <a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a> does not contain a declaration of
|
|
the unnamed mode, a declaration is implied equivalent to an
|
|
<a href="#element-mode"><code>xsl:mode</code></a> element with the
|
|
single attribute <code>initial="yes"</code>. Similarly, if there is
|
|
a mode that is named in an <a href=
|
|
"#element-template"><code>xsl:template</code></a> or <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>
|
|
element, or in the <code>default-mode</code> attribute of an
|
|
<a href="#element-stylesheet"><code>xsl:stylesheet</code></a>
|
|
element, and the <a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a> does not contain a declaration of
|
|
that mode, then a declaration is implied comprising an <a href=
|
|
"#element-mode"><code>xsl:mode</code></a> element with a
|
|
<code>name</code> attribute plus the attribute
|
|
<code>initial="yes"</code>.</p>
|
|
<p>The contained <a href=
|
|
"#element-context-item"><code>xsl:context-item</code></a> element,
|
|
if present, is used to declare requirements for the <a title=
|
|
"initial context item" class="termref" href=
|
|
"#dt-initial-context-item">initial context item</a> when this mode
|
|
is used as the <a title="initial mode" class="termref" href=
|
|
"#dt-initial-mode">initial mode</a>. Therefore, there must be no
|
|
<a href="#element-context-item"><code>xsl:context-item</code></a>
|
|
child if <code>initial="no"</code> is specified.</p>
|
|
<p><a name="err-XTSE0542" id="err-XTSE0542"><span class=
|
|
"error">[ERR XTSE0542]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> if an
|
|
<a href="#element-mode"><code>xsl:mode</code></a> declaration
|
|
specifying <code>initial="no"</code> contains an <a href=
|
|
"#element-context-item"><code>xsl:context-item</code></a>
|
|
element.</p>
|
|
<p>The attributes of the <a href=
|
|
"#element-mode"><code>xsl:mode</code></a> declaration establish
|
|
values for a number of properties of a mode. The allowed values and
|
|
meanings of the attributes are given in the following table.</p>
|
|
<table border="1" summary="Editorial note">
|
|
<tr>
|
|
<td align="left" valign="top" width="50%"><b>Editorial
|
|
note</b></td>
|
|
<td align="right" valign="top" width="50%"> </td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="2" align="left" valign="top">Need to make the
|
|
formatting of tables more consistent. Also consider whether a
|
|
tabular style could be more generally used for describing the
|
|
attributes of particular elements (and consider custom markup for
|
|
generating the table).</td>
|
|
</tr>
|
|
</table>
|
|
<table cellpadding="5" width="100%">
|
|
<thead>
|
|
<tr>
|
|
<th colspan="1">Attribute</th>
|
|
<th colspan="1">Values</th>
|
|
<th colspan="1">Meaning</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td valign="top">name</td>
|
|
<td valign="top">A <a title="lexical QName" class="termref" href=
|
|
"#dt-lexical-qname">lexical QName</a></td>
|
|
<td valign="top">Specifies the name of the mode. If omitted, this
|
|
<a href="#element-mode"><code>xsl:mode</code></a> declaration
|
|
provides properties of the <a title="unnamed mode" class="termref"
|
|
href="#dt-unnamed-mode">unnamed mode</a></td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">streamable</td>
|
|
<td valign="top"><code>yes</code> or <code>no</code> (default
|
|
<code>no</code>)</td>
|
|
<td valign="top">Determines whether template rules in this mode are
|
|
to be capable of being processed using <a title="streaming" class=
|
|
"termref" href="#dt-streaming">streaming</a>. If the value
|
|
<code>yes</code> is specified, then the body of any <a title=
|
|
"template rule" class="termref" href="#dt-template-rule">template
|
|
rule</a> that uses this mode <span class="verb">must</span> conform
|
|
to the rules for streamable templates given in <a href=
|
|
"#streamable-templates"><i>18.2 Streamable Templates</i></a>.</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">initial</td>
|
|
<td valign="top"><code>yes</code> or <code>no</code> (default
|
|
<code>yes</code>)</td>
|
|
<td valign="top">Determines whether this mode can be used as the
|
|
<a title="initial mode" class="termref" href=
|
|
"#dt-initial-mode">initial mode</a> when the transformation is
|
|
invoked. If the value <code>yes</code> is specified, or if the
|
|
attribute is omitted, then the mode is eligible to be used as the
|
|
<a title="initial mode" class="termref" href=
|
|
"#dt-initial-mode">initial mode</a>; if the value <code>no</code>
|
|
is specified then processing in the mode can only be achieved by
|
|
means of an <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>
|
|
instruction within the stylesheet that names this mode.</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">on-no-match</td>
|
|
<td valign="top">One of <code>stringify</code>,
|
|
<code>discard</code>, <code>copy</code>, or <code>fail</code>
|
|
(default <code>stringify</code>)</td>
|
|
<td valign="top">Determines selection of the built-in <a title=
|
|
"template rule" class="termref" href="#dt-template-rule">template
|
|
rules</a> that are used to process a node when an <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>
|
|
instruction selects a node that does not match any user-written
|
|
<a title="template rule" class="termref" href=
|
|
"#dt-template-rule">template rule</a> in the <a title="stylesheet"
|
|
class="termref" href="#dt-stylesheet">stylesheet</a>. For details,
|
|
see <a href="#built-in-rule"><i>6.7 Built-in Template
|
|
Rules</i></a>.</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">on-multiple-match</td>
|
|
<td valign="top">One of <code>fail</code> or <code>use-last</code>
|
|
(default <code>use-last</code>)</td>
|
|
<td valign="top">Defines the action to be taken when <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a> is
|
|
used in this mode and more than one user-written <a title=
|
|
"template rule" class="termref" href="#dt-template-rule">template
|
|
rule</a> is available to process the node, having the same
|
|
<a title="import precedence" class="termref" href=
|
|
"#dt-import-precedence">import precedence</a> and <a title=
|
|
"priority" class="termref" href="#dt-priority">priority</a>. The
|
|
value <code>fail</code> indicates that it is a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> if
|
|
more than one template rule matches the node. The value
|
|
<code>use-last</code> indicates that the situation is not to be
|
|
treated as an error (the last template in <a title=
|
|
"declaration order" class="termref" href=
|
|
"#dt-declaration-order">declaration order</a> is the one that is
|
|
used).</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">warning-on-no-match</td>
|
|
<td valign="top">One of <code>yes</code> or <code>no</code>. The
|
|
default is <a title="implementation-defined" class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a></td>
|
|
<td valign="top">Requests the <a title="processor" class="termref"
|
|
href="#dt-processor">processor</a> to output (or not to output) a
|
|
warning message in the case where an <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>
|
|
instruction selects a node that matches no template rule. The form
|
|
and destination of such warnings is <a title=
|
|
"implementation-defined" class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a>. The
|
|
processor <span class="verb">may</span> ignore this attribute, for
|
|
example if the environment provides no suitable means of
|
|
communicating with the user.</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">warning-on-multiple-match</td>
|
|
<td valign="top">One of <code>yes</code> or <code>no</code>. The
|
|
default is <a title="implementation-defined" class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a></td>
|
|
<td valign="top">Requests the <a title="processor" class="termref"
|
|
href="#dt-processor">processor</a> to output a warning message in
|
|
the case where an <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>
|
|
instruction selects a node that matches multiple template rules
|
|
having the same <a title="import precedence" class="termref" href=
|
|
"#dt-import-precedence">import precedence</a> and <a title=
|
|
"priority" class="termref" href="#dt-priority">priority</a>. The
|
|
form and destination of such warnings is <a title=
|
|
"implementation-defined" class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a>. The
|
|
processor <span class="verb">may</span> ignore this attribute, for
|
|
example if the environment provides no suitable means of
|
|
communicating with the user.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-streamable-mode" id="dt-streamable-mode" title=
|
|
"streamable mode"></a>A <b>streamable mode</b> is a <a title="mode"
|
|
class="termref" href="#dt-mode">mode</a> that is declared in an
|
|
<a href="#element-mode"><code>xsl:mode</code></a> declaration with
|
|
the attribute <code>streamable="yes"</code>.<span class=
|
|
"definition">]</span></p>
|
|
<p>For any named <a title="mode" class="termref" href=
|
|
"#dt-mode">mode</a>, the effective value of each attribute is taken
|
|
from an <a href="#element-mode"><code>xsl:mode</code></a>
|
|
declaration that has a matching name in its <code>name</code>
|
|
attribute, and that specifies an explicit value for the required
|
|
attribute. If there is more than one such declaration, the one with
|
|
highest <a title="import precedence" class="termref" href=
|
|
"#dt-import-precedence">import precedence</a> is used.</p>
|
|
<p>For the <a title="unnamed mode" class="termref" href=
|
|
"#dt-unnamed-mode">unnamed mode</a>, the effective value of each
|
|
attribute is taken from an <a href=
|
|
"#element-mode"><code>xsl:mode</code></a> declaration that has no
|
|
<code>name</code> attribute, and that specifies an explicit value
|
|
for the required attribute. If there is no such declaration, the
|
|
default value of the attribute is used. If there is more than one
|
|
such declaration, the one with highest <a title="import precedence"
|
|
class="termref" href="#dt-import-precedence">import precedence</a>
|
|
is used.</p>
|
|
<p>The above rules apply both to the attributes (other than
|
|
<code>name</code>) of the <a href=
|
|
"#element-mode"><code>xsl:mode</code></a> element itself, and to
|
|
the attributes of the contained <a href=
|
|
"#element-context-item"><code>xsl:context-item</code></a> element
|
|
if present.</p>
|
|
<p><a name="err-XTSE0545" id="err-XTSE0545"><span class=
|
|
"error">[ERR XTSE0545]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> if a named
|
|
or unnamed <a title="mode" class="termref" href="#dt-mode">mode</a>
|
|
contains two conflicting values for the same attribute in different
|
|
<a href="#element-mode"><code>xsl:mode</code></a> declarations
|
|
having the same <a title="import precedence" class="termref" href=
|
|
"#dt-import-precedence">import precedence</a>, unless there is
|
|
another definition of the same attribute with higher import
|
|
precedence. The attributes in question are the attributes other
|
|
than <code>name</code> on the <a href=
|
|
"#element-mode"><code>xsl:mode</code></a> element, and the
|
|
<code>as</code> attribute on the contained <a href=
|
|
"#element-context-item"><code>xsl:context-item</code></a> element
|
|
if present.</p>
|
|
<p>If the <a title="initial context item" class="termref" href=
|
|
"#dt-initial-context-item">initial context item</a> supplied to a
|
|
stylesheet is a streamed document node, then it is not permitted
|
|
for the values of global variables to be dependent on the context
|
|
item in a way that requires reading of the input stream. This
|
|
constraint is enforced by the following static rule:</p>
|
|
<p><a name="err-XTSE0548" id="err-XTSE0548"><span class=
|
|
"error">[ERR XTSE0548]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> if there
|
|
is both (a) a <a title="mode definition" class="termref" href=
|
|
"#dt-mode-definition">mode definition</a> in the <a title=
|
|
"stylesheet" class="termref" href="#dt-stylesheet">stylesheet</a>
|
|
that has the effective attribute values
|
|
<code>streamable="yes"</code> and <code>initial="yes"</code>, and
|
|
(b) a <a title="global variable" class="termref" href=
|
|
"#dt-global-variable">global variable</a> in the <a title=
|
|
"stylesheet" class="termref" href="#dt-stylesheet">stylesheet</a>
|
|
whose initializing expression is not <a title="motionless" class=
|
|
"termref" href="#dt-motionless">motionless</a> with respect to its
|
|
context item, as defined in <a href="#streamability"><i>18.4
|
|
Streamability Analysis</i></a>.</p>
|
|
</div>
|
|
<div class="div3">
|
|
<h4><a name="initial-context-for-mode" id=
|
|
"initial-context-for-mode"></a>6.6.2 <a href=
|
|
"#initial-context-for-mode" style="text-decoration: none">Declaring
|
|
the initial context item for a mode</a></h4>
|
|
<p>Given a <a title="mode" class="termref" href="#dt-mode">mode</a>
|
|
that is used as the <a title="initial mode" class="termref" href=
|
|
"#dt-initial-mode">initial mode</a>, the <a href=
|
|
"#element-context-item"><code>xsl:context-item</code></a> element
|
|
may be used to constrain the type of the <span><a title=
|
|
"initial context item" class="termref" href=
|
|
"#dt-initial-context-item">initial context item</a></span> that is
|
|
supplied by the calling application.</p>
|
|
<p class="element-syntax"><a name="element-context-item" id=
|
|
"element-context-item"></a><code><xsl:context-item<br />
|
|
  as? = <var>ItemType</var> /></code></p>
|
|
<p>If the <code>as</code> attribute is present then its value must
|
|
be an <a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-KindTest">ItemType</a><sup><small>XP21</small></sup>.
|
|
When this mode (the mode defined in the containing <a href=
|
|
"#element-mode"><code>xsl:mode</code></a> declaration) is used as
|
|
the <a title="initial mode" class="termref" href=
|
|
"#dt-initial-mode">initial mode</a>, then an <a title=
|
|
"initial context item" class="termref" href=
|
|
"#dt-initial-context-item">initial context item</a> must be
|
|
supplied externally, and its value will be converted to this type
|
|
using the <a title="function conversion rules" class="termref"
|
|
href="#dt-function-conversion-rules">function conversion rules</a>;
|
|
this may result in a <a title="type errors" class="termref" href=
|
|
"#dt-type-error">type errors</a> if the conversion is not
|
|
possible.</p>
|
|
<p>If the <code>as</code> attribute is omitted this is equivalent
|
|
to specifying <code>as="item()"</code>.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>If the <code>ItemType</code> is one that can only be satisfied
|
|
by a schema-validated input document, for example
|
|
<code>as="schema-element(invoice)"</code>, the <a title="processor"
|
|
class="termref" href="#dt-processor">processor</a> <span class=
|
|
"verb">may</span> interpret this as a request to apply schema
|
|
validation to the input. Similarly, if the <code>KindTest</code>
|
|
indicates that an element node is required, the processor
|
|
<span class="verb">may</span> interpret this as a request to supply
|
|
the document element rather than the document node of a supplied
|
|
input document.</p>
|
|
</div>
|
|
<p>If there is no <a href=
|
|
"#element-context-item"><code>xsl:context-item</code></a> element
|
|
for an <a href="#element-mode"><code>xsl:mode</code></a> that
|
|
specifies <code>initial="yes"</code>, this is equivalent to
|
|
specifying <code><xsl:context-item as="item()"/></code></p>
|
|
<p>A <a title="type errors" class="termref" href=
|
|
"#dt-type-error">type errors</a> is signalled if the supplied
|
|
context item does not match its required type. The error codes is
|
|
the same as for <a href="#element-param"><code>xsl:param</code></a>
|
|
<span class="error">[see <a href="#err-XTTE0590">ERR
|
|
XTTE0590</a>]</span>.</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e13514" id=
|
|
"d7e13514"></a>Example: Declaring the Required Context Item</div>
|
|
<p>The following example declares two modes, both of which have
|
|
<code>initial="yes"</code> meaning that they can be used as entry
|
|
points to the stylesheet. In the first mode, named
|
|
<code>invoice</code>, the required context item is a
|
|
schema-validated <code>invoice</code> element. In the second mode,
|
|
named <code>po</code>, the required context item is a
|
|
schema-validated <code>purchase-order</code> element. A third mode,
|
|
<code>format-address</code> is declared with
|
|
<code>initial="no"</code> so it cannot be used as an initial entry
|
|
point; this mode might be used when processing content that is
|
|
common to invoices and purchase orders.</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:mode name="invoice" initial="yes" on-no-match="copy">
|
|
<xsl:context-item as="schema-element(invoice)">
|
|
</xsl:mode>
|
|
<xsl:mode name="po" initial="yes" on-no-match="copy">
|
|
<xsl:context-item as="schema-element(purchase-order)">
|
|
</xsl:mode>
|
|
<xsl:mode name="format-address" initial="no"/>
|
|
</pre></div>
|
|
</div>
|
|
<blockquote>
|
|
<p><b><a name="issue-declaring-context-item-for-initial-template"
|
|
id="issue-declaring-context-item-for-initial-template">Issue 9
|
|
(declaring-context-item-for-initial-template)</a>:</b></p>
|
|
<p>It would also be useful to be able to declare the required type
|
|
of the context item (or to say that there is none) when starting
|
|
the transformation with an <a title="initial template" class=
|
|
"termref" href="#dt-initial-template">initial named
|
|
template</a></p>
|
|
</blockquote>
|
|
</div>
|
|
<div class="div3">
|
|
<h4><a name="using-modes" id="using-modes"></a>6.6.3 <a href=
|
|
"#using-modes" style="text-decoration: none">Using Modes</a></h4>
|
|
<p>A <a title="template rule" class="termref" href=
|
|
"#dt-template-rule">template rule</a> is applicable to one or more
|
|
modes. The modes to which it is applicable are defined by the
|
|
<code>mode</code> attribute of the <a href=
|
|
"#element-template"><code>xsl:template</code></a> element. If the
|
|
attribute is omitted, then the template rule is applicable to the
|
|
<span>default mode specified in the <code>default-mode</code>
|
|
attribute of the containing <a href=
|
|
"#element-stylesheet"><code>xsl:stylesheet</code></a> element,
|
|
which in turn defaults to the <a title="unnamed mode" class=
|
|
"termref" href="#dt-unnamed-mode">unnamed mode</a>.</span> If the
|
|
<code>mode</code> attribute is present, then its value <span class=
|
|
"verb">must</span> be a non-empty whitespace-separated list of
|
|
tokens, each of which defines a mode to which the template rule is
|
|
applicable. Each token <span class="verb">must</span> be one of the
|
|
following:</p>
|
|
<ul>
|
|
<li>
|
|
<p>a <a title="QName" class="termref" href="#dt-qname">QName</a>,
|
|
which is expanded as described in <a href="#qname"><i>5.1 Qualified
|
|
Names</i></a> to define the name of the mode</p>
|
|
</li>
|
|
<li>
|
|
<p>the token <code>#default</code>, to indicate that the template
|
|
rule is applicable to the <span>default mode for the stylesheet
|
|
module</span></p>
|
|
</li>
|
|
<li>
|
|
<p>the token <code>#unnamed</code>, to indicate that the template
|
|
rule is applicable to the <a title="unnamed mode" class="termref"
|
|
href="#dt-unnamed-mode">unnamed mode</a></p>
|
|
</li>
|
|
<li>
|
|
<p>the token <code>#all</code>, to indicate that the template rule
|
|
is applicable to all modes (specifically, to the
|
|
<span>unnamed</span> mode and to every mode that is named
|
|
<span>explicitly or implicitly</span> in an <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>
|
|
instruction anywhere in the stylesheet).</p>
|
|
</li>
|
|
</ul>
|
|
<p><a name="err-XTSE0550" id="err-XTSE0550"><span class=
|
|
"error">[ERR XTSE0550]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> if the
|
|
list is empty, if the same token is included more than once in the
|
|
list, if the list contains an invalid token, or if the token
|
|
<code>#all</code> appears together with any other value.</p>
|
|
<p>The <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>
|
|
element also has an optional <code>mode</code> attribute. The value
|
|
of this attribute <span class="verb">must</span> be one of the
|
|
following:</p>
|
|
<ul>
|
|
<li>
|
|
<p>a <a title="QName" class="termref" href="#dt-qname">QName</a>,
|
|
which is expanded as described in <a href="#qname"><i>5.1 Qualified
|
|
Names</i></a> to define the name of a mode</p>
|
|
</li>
|
|
<li>
|
|
<p>the token <code>#default</code>, to indicate that the default
|
|
mode <span>for the <a title="stylesheet module" class="termref"
|
|
href="#dt-stylesheet-module">stylesheet module</a></span> is to be
|
|
used</p>
|
|
</li>
|
|
<li>
|
|
<p>the token <code>#unnamed</code>, to indicate that the <a title=
|
|
"unnamed mode" class="termref" href="#dt-unnamed-mode">unnamed
|
|
mode</a> is to be used</p>
|
|
</li>
|
|
<li>
|
|
<p>the token <code>#current</code>, to indicate that the <a title=
|
|
"current mode" class="termref" href="#dt-current-mode">current
|
|
mode</a> is to be used</p>
|
|
</li>
|
|
</ul>
|
|
<p>If the attribute is omitted, the default mode <span>for the
|
|
<a title="stylesheet module" class="termref" href=
|
|
"#dt-stylesheet-module">stylesheet module</a></span> is used.</p>
|
|
<p>When searching for a template rule to process each
|
|
<span>item</span> selected by the <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>
|
|
instruction, only those template rules that are applicable to the
|
|
selected mode are considered.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-current-mode" id="dt-current-mode" title="current mode"></a>At
|
|
any point in the processing of a stylesheet, there is a <b>current
|
|
mode</b>. When the transformation is initiated, the current mode is
|
|
the <span><a title="initial mode" class="termref" href=
|
|
"#dt-initial-mode">initial mode</a></span>, as described in
|
|
<a href="#initiating"><i>2.3 Initiating a Transformation</i></a>.
|
|
Whenever an <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>
|
|
instruction is evaluated, the current mode becomes the mode
|
|
selected by this instruction.<span class="definition">]</span> When
|
|
a stylesheet function is called, the current mode is set to the
|
|
<a title="unnamed mode" class="termref" href=
|
|
"#dt-unnamed-mode">unnamed mode</a>. While evaluating global
|
|
variables and parameters, and the sequence constructor contained in
|
|
<a href="#element-key"><code>xsl:key</code></a> or <a href=
|
|
"#element-sort"><code>xsl:sort</code></a>, the current mode is set
|
|
to the unnamed mode. No other instruction changes the current mode.
|
|
The current mode while evaluating an <a title="attribute set"
|
|
class="termref" href="#dt-attribute-set">attribute set</a> is the
|
|
same as the current mode of the caller. On completion of the
|
|
<a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>
|
|
instruction, or on return from a stylesheet function call, the
|
|
current mode reverts to its previous value. The current mode is
|
|
used when an <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>
|
|
instruction uses the syntax <code>mode="#current"</code>; it is
|
|
also used by the <a href=
|
|
"#element-apply-imports"><code>xsl:apply-imports</code></a> and
|
|
<a href="#element-next-match"><code>xsl:next-match</code></a>
|
|
instructions (see <a href="#apply-imports"><i>6.8 Overriding
|
|
Template Rules</i></a>).</p>
|
|
</div>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="built-in-rule" id="built-in-rule"></a>6.7 <a href=
|
|
"#built-in-rule" style="text-decoration: none">Built-in Template
|
|
Rules</a></h3>
|
|
<p>When a node is selected by <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a> and
|
|
there is no user-specified <a title="template rule" class="termref"
|
|
href="#dt-template-rule">template rule</a> in the <a title=
|
|
"stylesheet" class="termref" href="#dt-stylesheet">stylesheet</a>
|
|
that can be used to process that node, then a built-in template
|
|
rule is evaluated instead.</p>
|
|
<p>The built-in <a title="template rule" class="termref" href=
|
|
"#dt-template-rule">template rules</a> have lower <a title=
|
|
"import precedence" class="termref" href=
|
|
"#dt-import-precedence">import precedence</a> than all other
|
|
template rules. Thus, the stylesheet author can override a built-in
|
|
template rule by including an explicit template rule.</p>
|
|
<p>There are four sets of built-in template rules available. The
|
|
set that is chosen is a property of the <a title="mode" class=
|
|
"termref" href="#dt-mode">mode</a> selected by the <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>
|
|
instruction. This property is set using the
|
|
<code>on-no-match</code> attribute of the <a href=
|
|
"#element-mode"><code>xsl:mode</code></a> declaration, which takes
|
|
one of the four values <code>stringify</code>, <code>copy</code>,
|
|
<code>discard</code>, or <code>fail</code>, the default being
|
|
<code>stringify</code>. The effect of these four sets of built-in
|
|
template rules is explained in the following subsections.</p>
|
|
<div class="div3">
|
|
<h4><a name="built-in-templates-stringify" id=
|
|
"built-in-templates-stringify"></a>6.7.1 <a href=
|
|
"#built-in-templates-stringify" style=
|
|
"text-decoration: none">Built-in Templates: stringify</a></h4>
|
|
<p>The general effect of choosing
|
|
<code>on-no-match="stringify"</code> for a <a title="mode" class=
|
|
"termref" href="#dt-mode">mode</a> is to retain the textual content
|
|
of the source document while losing the markup. When an element is
|
|
encountered for which there is no explicit <a title="template rule"
|
|
class="termref" href="#dt-template-rule">template rule</a>, the
|
|
processing continues with the children of that element. Text nodes
|
|
are copied to the output.</p>
|
|
<p>The built-in rule for document nodes and element nodes is
|
|
equivalent to calling <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>
|
|
with no <code>select</code> attribute, and with the
|
|
<code>mode</code> attribute set to <code>#current</code>. If the
|
|
built-in rule was invoked with parameters, those parameters are
|
|
passed on in the implicit <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>
|
|
instruction.</p>
|
|
<p>The built-in <a title="template rule" class="termref" href=
|
|
"#dt-template-rule">template rule</a> for text and attribute nodes
|
|
<span>and atomic values</span> returns a text node containing the
|
|
<a title="string value" class="termref" href=
|
|
"#dt-string-value">string value</a> of the context node. It is
|
|
effectively:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:template match="text()|@*|xs:anyAtomicType" mode="M">
|
|
<xsl:value-of select="string(.)"/>
|
|
</xsl:template>
|
|
</pre></div>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>This text node may have a string value that is zero-length.</p>
|
|
</div>
|
|
<p>The built-in <a title="template rule" class="termref" href=
|
|
"#dt-template-rule">template rule</a> for processing instructions,
|
|
comments, namespace nodes, and function items does nothing (it
|
|
returns the empty sequence).</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:template
|
|
match="processing-instruction()|comment()|namespace-node()|function()"
|
|
mode="M"/>
|
|
</pre></div>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e13881" id=
|
|
"d7e13881"></a>Example: Using a Built-In Template Rule</div>
|
|
<p>Suppose the stylesheet contains the following instruction:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:apply-templates select="title" mode="M">
|
|
<xsl:with-param name="init" select="10"/>
|
|
</xsl:apply-templates>
|
|
</pre></div>
|
|
<p>If there is no explicit template rule that matches the
|
|
<code>title</code> element, then the following implicit rule is
|
|
used:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:template match="title" mode="M">
|
|
<xsl:param name="init"/>
|
|
<xsl:apply-templates mode="#current">
|
|
<xsl:with-param name="init" select="$init"/>
|
|
</xsl:apply-templates>
|
|
</xsl:template>
|
|
</pre></div>
|
|
</div>
|
|
</div>
|
|
<div class="div3">
|
|
<h4><a name="built-in-templates-discard" id=
|
|
"built-in-templates-discard"></a>6.7.2 <a href=
|
|
"#built-in-templates-discard" style=
|
|
"text-decoration: none">Built-in Templates: discard</a></h4>
|
|
<p>The general effect of choosing
|
|
<code>on-no-match="discard"</code> for a <a title="mode" class=
|
|
"termref" href="#dt-mode">mode</a> is to omit both the text and the
|
|
markup from the result document, except in the case of items that
|
|
are matched by explicit user-written <a title="template rule"
|
|
class="termref" href="#dt-template-rule">template rules</a>.</p>
|
|
<p>The built-in rule for document nodes and element nodes is the
|
|
same as for <code>on-no-match="stringify"</code>: that is, it is
|
|
equivalent to calling <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>
|
|
with no <code>select</code> attribute, and with the
|
|
<code>mode</code> attribute set to <code>#current</code>. If the
|
|
built-in rule was invoked with parameters, those parameters are
|
|
passed on in the implicit <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>
|
|
instruction.</p>
|
|
<p>The built-in template rule for all other kinds of node, and for
|
|
atomic values and function items, is empty: that is, when the item
|
|
is matched, the built-in template rule returns an empty
|
|
sequence.</p>
|
|
</div>
|
|
<div class="div3">
|
|
<h4><a name="built-in-templates-copy" id=
|
|
"built-in-templates-copy"></a>6.7.3 <a href=
|
|
"#built-in-templates-copy" style="text-decoration: none">Built-in
|
|
Templates: copy</a></h4>
|
|
<p>The general effect of choosing <code>on-no-match="copy"</code>
|
|
for a <a title="mode" class="termref" href="#dt-mode">mode</a> is
|
|
that the source tree is copied unchanged to the output, except for
|
|
nodes where different processing is specified using an explicit
|
|
<a title="template rule" class="termref" href=
|
|
"#dt-template-rule">template rule</a>.</p>
|
|
<p>When this default action is selected for a mode <var>M</var>,
|
|
all items are processed using a template rule that is equivalent to
|
|
the following, except that all parameters supplied in <a href=
|
|
"#element-with-param"><code>xsl:with-param</code></a> elements are
|
|
passed on implicitly to the called templates:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:template match="~item()" mode="M">
|
|
<xsl:copy validation="preserve">
|
|
<xsl:apply-templates select="@*" mode="M"/>
|
|
<xsl:apply-templates select="node()" mode="M"/>
|
|
</xsl:copy>
|
|
</xsl:template>
|
|
</pre></div>
|
|
<p>This rule is often referred to as the <em>identity
|
|
template</em>, though it should be noted that it does not preserve
|
|
node identity.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>This rule differs from the "traditional" identity template rule
|
|
by using two <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>
|
|
instructions, one to process the attributes and one to process the
|
|
children. The only observable difference is that with two separate
|
|
instructions, the value of <code>position()</code> in the called
|
|
templates forms one sequence starting at 1 for the attributes, and
|
|
a new sequence starting at 1 for the children.</p>
|
|
</div>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e13970" id=
|
|
"d7e13970"></a>Example: Modified Identity Transformation</div>
|
|
<p>The following stylesheet transforms an input document by
|
|
deleting all elements named <code>note</code>, together with their
|
|
attributes and descendants:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:stylesheet version="2.1"
|
|
xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
|
|
|
|
<xsl:mode on-no-match="copy" streamable="yes"/>
|
|
|
|
<xsl:template match="note">
|
|
<!-- no action -->
|
|
</xsl:template>
|
|
|
|
</xsl:stylesheet>
|
|
</pre></div>
|
|
</div>
|
|
</div>
|
|
<div class="div3">
|
|
<h4><a name="built-in-templates-fail" id=
|
|
"built-in-templates-fail"></a>6.7.4 <a href=
|
|
"#built-in-templates-fail" style="text-decoration: none">Built-in
|
|
Templates: fail</a></h4>
|
|
<p>The general effect of choosing <code>on-no-match="fail"</code>
|
|
for a <a title="mode" class="termref" href="#dt-mode">mode</a> is
|
|
that every node selected in an <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>
|
|
instruction must be matched by an explicit user-written <a title=
|
|
"template rule" class="termref" href="#dt-template-rule">template
|
|
rules</a>.</p>
|
|
<p>The built-in template rule is effectively:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:template match="~item()" mode="M">
|
|
<xsl:message error-code="err:XTDE0555"/>
|
|
</xsl:template>
|
|
</pre></div>
|
|
<p>with an <a title="implementation-dependent" class="termref"
|
|
href="#dt-implementation-dependent">implementation-dependent</a>
|
|
message body.</p>
|
|
<p><a name="err-XTDE0555" id="err-XTDE0555"><span class=
|
|
"error">[ERR XTDE0555]</span></a> It is a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> if
|
|
<a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>,
|
|
<a href="#element-apply-imports"><code>xsl:apply-imports</code></a>
|
|
or <a href="#element-next-match"><code>xsl:next-match</code></a> is
|
|
used to process a node using a mode whose declaration specifies
|
|
<code>on-no-match="fail"</code> when there is no <a title=
|
|
"template rule" class="termref" href="#dt-template-rule">template
|
|
rule</a> in the <a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a> whose match pattern matches that
|
|
node.</p>
|
|
</div>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="apply-imports" id="apply-imports"></a>6.8 <a href=
|
|
"#apply-imports" style="text-decoration: none">Overriding Template
|
|
Rules</a></h3>
|
|
<p class="element-syntax"><a name="element-apply-imports" id=
|
|
"element-apply-imports"></a><code><!-- Category: instruction
|
|
--><br />
|
|
<xsl:apply-imports><br />
|
|
  <!-- Content: <a href=
|
|
"#element-with-param">xsl:with-param</a>* --><br />
|
|
</xsl:apply-imports></code></p>
|
|
<p class="element-syntax"><a name="element-next-match" id=
|
|
"element-next-match"></a><code><!-- Category: instruction
|
|
--><br />
|
|
<xsl:next-match><br />
|
|
  <!-- Content: (<a href=
|
|
"#element-with-param">xsl:with-param</a> | <a href=
|
|
"#element-fallback">xsl:fallback</a>)* --><br />
|
|
</xsl:next-match></code></p>
|
|
<p>A <a title="template rule" class="termref" href=
|
|
"#dt-template-rule">template rule</a> that is being used to
|
|
override another template rule (see <a href="#conflict"><i>6.4
|
|
Conflict Resolution for Template Rules</i></a>) can use the
|
|
<a href="#element-apply-imports"><code>xsl:apply-imports</code></a>
|
|
or <a href="#element-next-match"><code>xsl:next-match</code></a>
|
|
instruction to invoke the overridden template rule. The <a href=
|
|
"#element-apply-imports"><code>xsl:apply-imports</code></a>
|
|
instruction only considers template rules in imported stylesheet
|
|
modules; the <a href=
|
|
"#element-next-match"><code>xsl:next-match</code></a> instruction
|
|
considers all other template rules of lower <a title=
|
|
"import precedence" class="termref" href=
|
|
"#dt-import-precedence">import precedence</a> and/or priority. Both
|
|
instructions will invoke the built-in template rule for the
|
|
<span>context item</span> (see <a href="#built-in-rule"><i>6.7
|
|
Built-in Template Rules</i></a>) if no other template rule is
|
|
found.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-current-template-rule" id="dt-current-template-rule" title=
|
|
"current template rule"></a>At any point in the processing of a
|
|
<a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a>, there may be a <b>current template
|
|
rule</b>. Whenever a <a title="template rule" class="termref" href=
|
|
"#dt-template-rule">template rule</a> is chosen as a result of
|
|
evaluating <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>,
|
|
<a href=
|
|
"#element-apply-imports"><code>xsl:apply-imports</code></a>, or
|
|
<a href="#element-next-match"><code>xsl:next-match</code></a>, the
|
|
template rule becomes the current template rule for the evaluation
|
|
of the rule's sequence constructor. When an <a href=
|
|
"#element-for-each"><code>xsl:for-each</code></a>, <a href=
|
|
"#element-for-each-group"><code>xsl:for-each-group</code></a>,
|
|
<a href=
|
|
"#element-analyze-string"><code>xsl:analyze-string</code></a>,
|
|
<span><a href="#element-iterate"><code>xsl:iterate</code></a>,
|
|
<a href="#element-stream"><code>xsl:stream</code></a>, <a href=
|
|
"#element-merge"><code>xsl:merge</code></a>, or <a href=
|
|
"#element-evaluate"><code>xsl:evaluate</code></a></span>
|
|
instruction is evaluated, or when evaluating a sequence constructor
|
|
contained in an <a href="#element-sort"><code>xsl:sort</code></a>
|
|
or <a href="#element-key"><code>xsl:key</code></a> element, or when
|
|
a <a title="stylesheet function" class="termref" href=
|
|
"#dt-stylesheet-function">stylesheet function</a> is called (see
|
|
<a href="#stylesheet-functions"><i>10.3 Stylesheet
|
|
Functions</i></a>), the current template rule becomes null for the
|
|
evaluation of that instruction or function.<span class=
|
|
"definition">]</span></p>
|
|
<p>The current template rule is not affected by invoking named
|
|
templates (see <a href="#named-templates"><i>10.1 Named
|
|
Templates</i></a>) or named attribute sets (see <a href=
|
|
"#attribute-sets"><i>10.2 Named Attribute Sets</i></a>). While
|
|
evaluating a <a title="global variable" class="termref" href=
|
|
"#dt-global-variable">global variable</a> or the default value of a
|
|
<a title="stylesheet parameter" class="termref" href=
|
|
"#dt-stylesheet-parameter">stylesheet parameter</a> (see <a href=
|
|
"#global-variables"><i>9.5 Global Variables and Parameters</i></a>)
|
|
the current template rule is null.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>These rules ensure that when <a href=
|
|
"#element-apply-imports"><code>xsl:apply-imports</code></a> or
|
|
<a href="#element-next-match"><code>xsl:next-match</code></a> is
|
|
called, the <a title="context item" class="termref" href=
|
|
"#dt-context-item">context item</a> is the same as when the current
|
|
template rule was invoked.</p>
|
|
</div>
|
|
<p>Both <a href=
|
|
"#element-apply-imports"><code>xsl:apply-imports</code></a> and
|
|
<a href="#element-next-match"><code>xsl:next-match</code></a>
|
|
search for a <a title="template rule" class="termref" href=
|
|
"#dt-template-rule">template rule</a> that matches the
|
|
<span><a title="context item" class="termref" href=
|
|
"#dt-context-item">context item</a></span>, and that is applicable
|
|
to the <a title="current mode" class="termref" href=
|
|
"#dt-current-mode">current mode</a> (see <a href="#modes"><i>6.6
|
|
Modes</i></a>). In choosing a template rule, they use the usual
|
|
criteria such as the priority and <a title="import precedence"
|
|
class="termref" href="#dt-import-precedence">import precedence</a>
|
|
of the template rules, but they consider as candidates only a
|
|
subset of the template rules in the <a title="stylesheet" class=
|
|
"termref" href="#dt-stylesheet">stylesheet</a>. This subset differs
|
|
between the two instructions:</p>
|
|
<ul>
|
|
<li>
|
|
<p>The <a href=
|
|
"#element-apply-imports"><code>xsl:apply-imports</code></a>
|
|
instruction considers as candidates only those template rules
|
|
contained in <a title="stylesheet level" class="termref" href=
|
|
"#dt-stylesheet-level">stylesheet levels</a> that are descendants
|
|
in the <a title="import tree" class="termref" href=
|
|
"#dt-import-tree">import tree</a> of the <a title=
|
|
"stylesheet level" class="termref" href=
|
|
"#dt-stylesheet-level">stylesheet level</a> that contains the
|
|
<a title="current template rule" class="termref" href=
|
|
"#dt-current-template-rule">current template rule</a>.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>This is <em>not</em> the same as saying that the search
|
|
considers all template rules whose import precedence is lower than
|
|
that of the current template rule.</p>
|
|
</div>
|
|
</li>
|
|
<li>
|
|
<p>The <a href=
|
|
"#element-next-match"><code>xsl:next-match</code></a> instruction
|
|
considers as candidates all those template rules that come after
|
|
the <a title="current template rule" class="termref" href=
|
|
"#dt-current-template-rule">current template rule</a> in the
|
|
ordering of template rules implied by the conflict resolution rules
|
|
given in <a href="#conflict"><i>6.4 Conflict Resolution for
|
|
Template Rules</i></a>. That is, it considers all template rules
|
|
with lower <a title="import precedence" class="termref" href=
|
|
"#dt-import-precedence">import precedence</a> than the <a title=
|
|
"current template rule" class="termref" href=
|
|
"#dt-current-template-rule">current template rule</a>, plus the
|
|
template rules that are at the same import precedence that have
|
|
lower priority than the current template rule, <span>plus
|
|
the</span> template rules with the same import precedence and
|
|
priority that occur before the current template rule in <a title=
|
|
"declaration order" class="termref" href=
|
|
"#dt-declaration-order">declaration order</a>.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>As explained in <a href="#conflict"><i>6.4 Conflict Resolution
|
|
for Template Rules</i></a>, a template rule whose match pattern
|
|
contains multiple alternatives separated by <code>|</code> is
|
|
treated equivalently to a set of template rules, one for each
|
|
alternative. This means that where the same <span>item</span>
|
|
matches more than one alternative, and the alternatives have
|
|
different priority, it is possible for an <a href=
|
|
"#element-next-match"><code>xsl:next-match</code></a> instruction
|
|
to cause the current template rule to be invoked recursively. This
|
|
situation does not occur when the alternatives have the same
|
|
priority.</p>
|
|
</div>
|
|
</li>
|
|
</ul>
|
|
<p>If no matching template rule is found that satisfies these
|
|
criteria, the built-in template rule for the <span>context
|
|
item</span> is used (see <a href="#built-in-rule"><i>6.7 Built-in
|
|
Template Rules</i></a>).</p>
|
|
<p>An <a href=
|
|
"#element-apply-imports"><code>xsl:apply-imports</code></a> or
|
|
<a href="#element-next-match"><code>xsl:next-match</code></a>
|
|
instruction may use <a href=
|
|
"#element-with-param"><code>xsl:with-param</code></a> child
|
|
elements to pass parameters to the chosen <a title="template rule"
|
|
class="termref" href="#dt-template-rule">template rule</a> (see
|
|
<a href="#with-param"><i>9.8 Setting Parameter Values</i></a>). It
|
|
also passes on any <a title="tunnel parameter" class="termref"
|
|
href="#dt-tunnel-parameter">tunnel parameters</a> as described in
|
|
<a href="#tunnel-params"><i>10.1.2 Tunnel Parameters</i></a>.</p>
|
|
<p><a name="err-XTDE0560" id="err-XTDE0560"><span class=
|
|
"error">[ERR XTDE0560]</span></a> It is a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> if
|
|
<a href="#element-apply-imports"><code>xsl:apply-imports</code></a>
|
|
or <a href="#element-next-match"><code>xsl:next-match</code></a> is
|
|
evaluated when the <a title="current template rule" class="termref"
|
|
href="#dt-current-template-rule">current template rule</a> is
|
|
null.</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e14299" id=
|
|
"d7e14299"></a>Example: Using <code>xsl:apply-imports</code></div>
|
|
<p>For example, suppose the stylesheet <code>doc.xsl</code>
|
|
contains a <a title="template rule" class="termref" href=
|
|
"#dt-template-rule">template rule</a> for <code>example</code>
|
|
elements:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:template match="example">
|
|
<pre><xsl:apply-templates/></pre>
|
|
</xsl:template>
|
|
</pre></div>
|
|
<p>Another stylesheet could import <code>doc.xsl</code> and modify
|
|
the treatment of <code>example</code> elements as follows:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:import href="doc.xsl"/>
|
|
|
|
<xsl:template match="example">
|
|
<div style="border: solid red">
|
|
<xsl:apply-imports/>
|
|
</div>
|
|
</xsl:template>
|
|
</pre></div>
|
|
<p>The combined effect would be to transform an
|
|
<code>example</code> into an element of the form:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<div style="border: solid red"><pre>...</pre></div>
|
|
</pre></div>
|
|
</div>
|
|
<p>An <a href="#element-fallback"><code>xsl:fallback</code></a>
|
|
instruction appearing as a child of an <a href=
|
|
"#element-next-match"><code>xsl:next-match</code></a> instruction
|
|
is ignored by an XSLT 2.0 <span>or 2.1</span> processor, but can be
|
|
used to define fallback behavior when the stylesheet is processed
|
|
by an XSLT 1.0 processor with forwards compatible behavior.</p>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="parameters-to-template-rules" id=
|
|
"parameters-to-template-rules"></a>6.9 <a href=
|
|
"#parameters-to-template-rules" style=
|
|
"text-decoration: none">Passing Parameters to Template
|
|
Rules</a></h3>
|
|
<p>A template rule may have parameters. The parameters are declared
|
|
in the body of the template using <a href=
|
|
"#element-param"><code>xsl:param</code></a> elements, as described
|
|
in <a href="#parameters"><i>9.2 Parameters</i></a>.</p>
|
|
<p>Values for these parameters may be supplied in the calling
|
|
<a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>,
|
|
<a href=
|
|
"#element-apply-imports"><code>xsl:apply-imports</code></a>, or
|
|
<a href="#element-next-match"><code>xsl:next-match</code></a>
|
|
instruction by means of <a href=
|
|
"#element-with-param"><code>xsl:with-param</code></a> elements
|
|
appearing as children of the calling instruction. The <a title=
|
|
"expanded-QName" class="termref" href="#dt-expanded-qname">expanded
|
|
QName</a> represented by the <code>name</code> attribute of the
|
|
<a href="#element-with-param"><code>xsl:with-param</code></a>
|
|
element must match the <a title="expanded-QName" class="termref"
|
|
href="#dt-expanded-qname">expanded QName</a> represented by the
|
|
<code>name</code> attribute of the corresponding <a href=
|
|
"#element-param"><code>xsl:param</code></a> element.</p>
|
|
<p><a name="err-XTDE0700" id="err-XTDE0700"><span class=
|
|
"error">[ERR XTDE0700]</span></a> It is a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> if a
|
|
template that is invoked using <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>,
|
|
<a href=
|
|
"#element-apply-imports"><code>xsl:apply-imports</code></a>, or
|
|
<a href="#element-next-match"><code>xsl:next-match</code></a>
|
|
declares a <a title="template parameter" class="termref" href=
|
|
"#dt-template-parameter">template parameter</a> with
|
|
<code>required="yes"</code> and no value for this parameter is
|
|
supplied by the calling instruction. The same error is reported in
|
|
the case of a <a title="tunnel parameter" class="termref" href=
|
|
"#dt-tunnel-parameter">tunnel parameter</a> whether invoked using
|
|
one of these three instructions or by <a href=
|
|
"#element-call-template"><code>xsl:call-template</code></a>, as
|
|
explained in <a href="#tunnel-params"><i>10.1.2 Tunnel
|
|
Parameters</i></a>.</p>
|
|
<p>It is not an error for these instructions to supply a parameter
|
|
that does not match any parameter declared in the template rule
|
|
that is invoked; unneeded parameter values are simply ignored.</p>
|
|
<p>A parameter may be declared as a <a title="tunnel parameter"
|
|
class="termref" href="#dt-tunnel-parameter">tunnel parameter</a> by
|
|
specifying <code>tunnel="yes"</code> in the <a href=
|
|
"#element-param"><code>xsl:param</code></a> declaration; in this
|
|
case the caller must supply the value as a tunnel parameter by
|
|
specifying <code>tunnel="yes"</code> in the corresponding <a href=
|
|
"#element-with-param"><code>xsl:with-param</code></a> element.
|
|
Tunnel parameters differ from ordinary template parameters in that
|
|
they are passed transparently through multiple template
|
|
invocations. They are fully described in <a href=
|
|
"#tunnel-params"><i>10.1.2 Tunnel Parameters</i></a>.</p>
|
|
</div>
|
|
</div>
|
|
<div class="div1">
|
|
<h2><a name="repetition" id="repetition"></a>7 <a href=
|
|
"#repetition" style="text-decoration: none">Repetition</a></h2>
|
|
<p>XSLT offers two constructs for processing each item of a
|
|
sequence: <a href="#element-for-each"><code>xsl:for-each</code></a>
|
|
and <a href="#element-iterate"><code>xsl:iterate</code></a>.</p>
|
|
<p>The main difference between the two constructs is that with
|
|
<a href="#element-for-each"><code>xsl:for-each</code></a>, the
|
|
processing applied to each item in the sequence is independent of
|
|
the processing applied to any other item; this means that the items
|
|
may be processed in any order or in parallel, though the order of
|
|
the output sequence is well defined and corresponds to the order of
|
|
the input (sorted if so requested). By contrast, with <a href=
|
|
"#element-iterate"><code>xsl:iterate</code></a>, the processing is
|
|
explicitly sequential: while one item is being processed, values
|
|
may be computed which are then available for use while the next
|
|
item is being processed. This makes <a href=
|
|
"#element-iterate"><code>xsl:iterate</code></a> suitable for tasks
|
|
such as creating a running total over a sequence of financial
|
|
transactions.</p>
|
|
<p>A further difference is that <a href=
|
|
"#element-for-each"><code>xsl:for-each</code></a> permits sorting
|
|
of the input sequence, while <a href=
|
|
"#element-iterate"><code>xsl:iterate</code></a> does not.</p>
|
|
<div class="div2">
|
|
<h3><a name="for-each" id="for-each"></a>7.1 <a href="#for-each"
|
|
style="text-decoration: none">The</a> <code>xsl:for-each</code>
|
|
<a href="#for-each" style=
|
|
"text-decoration: none">instruction</a></h3>
|
|
<p class="element-syntax"><a name="element-for-each" id=
|
|
"element-for-each"></a><code><!-- Category: instruction
|
|
--><br />
|
|
<xsl:for-each<br />
|
|
  <b>select</b> = <var>expression</var> ><br />
|
|
  <!-- Content: (<a href=
|
|
"#element-sort">xsl:sort</a>*, <var>sequence-constructor</var>)
|
|
--><br />
|
|
</xsl:for-each></code></p>
|
|
<p>The <a href="#element-for-each"><code>xsl:for-each</code></a>
|
|
instruction processes each item in a sequence of items, evaluating
|
|
the <a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> within the
|
|
<a href="#element-for-each"><code>xsl:for-each</code></a>
|
|
instruction once for each item in that sequence.</p>
|
|
<p>The <code>select</code> attribute is <span class=
|
|
"verb">required</span>; it contains an <a title="expression" class=
|
|
"termref" href="#dt-expression">expression</a> which is evaluated
|
|
to produce a sequence, called the input sequence. If there is an
|
|
<a href="#element-sort"><code>xsl:sort</code></a> element present
|
|
(see <a href="#sorting"><i>13 Sorting</i></a>) the input sequence
|
|
is sorted to produce a sorted sequence. Otherwise, the sorted
|
|
sequence is the same as the input sequence.</p>
|
|
<p>The <a href="#element-for-each"><code>xsl:for-each</code></a>
|
|
instruction contains a <a title="sequence constructor" class=
|
|
"termref" href="#dt-sequence-constructor">sequence constructor</a>.
|
|
The <a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> is evaluated
|
|
once for each item in the sorted sequence, with the <a title=
|
|
"focus" class="termref" href="#dt-focus">focus</a> set as
|
|
follows:</p>
|
|
<ul>
|
|
<li>
|
|
<p>The <a title="context item" class="termref" href=
|
|
"#dt-context-item">context item</a> is the item being
|
|
processed.</p>
|
|
</li>
|
|
<li>
|
|
<p>The <a title="context position" class="termref" href=
|
|
"#dt-context-position">context position</a> is the position of this
|
|
item in the sorted sequence.</p>
|
|
</li>
|
|
<li>
|
|
<p>The <a title="context size" class="termref" href=
|
|
"#dt-context-size">context size</a> is the size of the sorted
|
|
sequence (which is the same as the size of the input sequence).</p>
|
|
</li>
|
|
</ul>
|
|
<p>For each item in the input sequence, evaluating the <a title=
|
|
"sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> produces a
|
|
sequence of items (see <a href="#sequence-constructors"><i>5.7
|
|
Sequence Constructors</i></a>). These output sequences are
|
|
concatenated; if item <var>Q</var> follows item <var>P</var> in the
|
|
sorted sequence, then the result of evaluating the sequence
|
|
constructor with <var>Q</var> as the context item is concatenated
|
|
after the result of evaluating the sequence constructor with
|
|
<var>P</var> as the context item. The result of the <a href=
|
|
"#element-for-each"><code>xsl:for-each</code></a> instruction is
|
|
the concatenated sequence of items.</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e14583" id=
|
|
"d7e14583"></a>Example: Using <code>xsl:for-each</code></div>
|
|
<p>For example, given an XML document with this structure</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<customers>
|
|
<customer>
|
|
<name>...</name>
|
|
<order>...</order>
|
|
<order>...</order>
|
|
</customer>
|
|
<customer>
|
|
<name>...</name>
|
|
<order>...</order>
|
|
<order>...</order>
|
|
</customer>
|
|
</customers>
|
|
</pre></div>
|
|
<p>the following would create an HTML document containing a table
|
|
with a row for each <code>customer</code> element</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<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>
|
|
</pre></div>
|
|
</div>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="iterate" id="iterate"></a>7.2 <a href="#iterate"
|
|
style="text-decoration: none">The</a> <code>xsl:iterate</code>
|
|
<a href="#iterate" style=
|
|
"text-decoration: none">instruction</a></h3>
|
|
<p class="element-syntax"><a name="element-iterate" id=
|
|
"element-iterate"></a><code><!-- Category: instruction
|
|
--><br />
|
|
<xsl:iterate<br />
|
|
  <b>select</b> = <var>expression</var> ><br />
|
|
  <!-- Content: (<a href=
|
|
"#element-param">xsl:param</a>*, <var>sequence-constructor</var>,
|
|
<a href="#element-on-completion">xsl:on-completion</a>?)
|
|
--><br />
|
|
</xsl:iterate></code></p>
|
|
<p class="element-syntax"><a name="element-next-iteration" id=
|
|
"element-next-iteration"></a><code><!-- Category: instruction
|
|
--><br />
|
|
<xsl:next-iteration><br />
|
|
  <!-- Content: (<a href=
|
|
"#element-with-param">xsl:with-param</a>*) --><br />
|
|
</xsl:next-iteration></code></p>
|
|
<p class="element-syntax"><a name="element-break" id=
|
|
"element-break"></a><code><!-- Category: instruction
|
|
--><br />
|
|
<xsl:break><br />
|
|
  <!-- Content: (<var>sequence-constructor</var>)
|
|
--><br />
|
|
</xsl:break></code></p>
|
|
<p class="element-syntax"><a name="element-on-completion" id=
|
|
"element-on-completion"></a><code><xsl:on-completion><br />
|
|
  <!-- Content: (<var>sequence-constructor</var>)
|
|
--><br />
|
|
</xsl:on-completion></code></p>
|
|
<p>The <code>select</code> attribute is <span class=
|
|
"verb">required</span>; it contains an <a title="expression" class=
|
|
"termref" href="#dt-expression">expression</a> which is evaluated
|
|
to produce a sequence, called the input sequence.</p>
|
|
<p>The <a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> contained in
|
|
the <a href="#element-iterate"><code>xsl:iterate</code></a>
|
|
instruction is evaluated once for each item in the input sequence,
|
|
in order, or until the loop exits by evaluating an <a href=
|
|
"#element-break"><code>xsl:break</code></a> instruction, whichever
|
|
is earlier. Within the <a title="sequence constructor" class=
|
|
"termref" href="#dt-sequence-constructor">sequence constructor</a>
|
|
that forms the body of the <a href=
|
|
"#element-iterate"><code>xsl:iterate</code></a> instruction, the
|
|
<a title="context item" class="termref" href=
|
|
"#dt-context-item">context item</a> is set to each item from the
|
|
value of the <code>select</code> expression in turn; the <a title=
|
|
"context position" class="termref" href=
|
|
"#dt-context-position">context position</a> reflects the position
|
|
of this item in the input sequence, and the <a title="context size"
|
|
class="termref" href="#dt-context-size">context size</a> is the
|
|
number of items in the input sequence (which may be greater than
|
|
the number of iterations, if the loop exits prematurely using
|
|
<a href="#element-break"><code>xsl:break</code></a>).</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>If <a href="#element-iterate"><code>xsl:iterate</code></a> is
|
|
used in conjunction with <a href=
|
|
"#element-stream"><code>xsl:stream</code></a> to achieve streaming,
|
|
calls on the function <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-last"><code>last</code></a><sup><small>FO</small></sup>
|
|
will be disallowed.</p>
|
|
</div>
|
|
<p>The effect of <a href=
|
|
"#element-next-iteration"><code>xsl:next-iteration</code></a> is to
|
|
cause the iteration to continue by processing the next item in the
|
|
input sequence, potentially with different values for the iteration
|
|
parameters. The effect of <a href=
|
|
"#element-break"><code>xsl:break</code></a> is to cause the
|
|
iteration to finish, whether or not all the items in the input
|
|
sequence have been processed. In both cases the affected iteration
|
|
is the one controlled by the innermost ancestor <a href=
|
|
"#element-iterate"><code>xsl:iterate</code></a> element.</p>
|
|
<p>The instructions <a href=
|
|
"#element-next-iteration"><code>xsl:next-iteration</code></a> and
|
|
<a href="#element-break"><code>xsl:break</code></a> are allowed
|
|
only as descendants of an <a href=
|
|
"#element-iterate"><code>xsl:iterate</code></a> instruction, and
|
|
only in a <a title="tail position" class="termref" href=
|
|
"#dt-tail-position">tail position</a> within the <a title=
|
|
"sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> forming the
|
|
body of the <a href="#element-iterate"><code>xsl:iterate</code></a>
|
|
instruction.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-tail-position" id="dt-tail-position" title=
|
|
"tail position"></a>An <a title="instruction" class="termref" href=
|
|
"#dt-instruction">instruction</a> <var>J</var> is in a <b>tail
|
|
position</b> within a <a title="sequence constructor" class=
|
|
"termref" href="#dt-sequence-constructor">sequence constructor</a>
|
|
<var>SC</var> if it satisfies one of the following
|
|
conditions:<span class="definition">]</span></p>
|
|
<ul>
|
|
<li>
|
|
<p><var>J</var> is the last instruction in <var>SC</var>, ignoring
|
|
any <a href="#element-fallback"><code>xsl:fallback</code></a>
|
|
instructions.</p>
|
|
</li>
|
|
<li>
|
|
<p><var>J</var> is in a <a title="tail position" class="termref"
|
|
href="#dt-tail-position">tail position</a> within the sequence
|
|
constructor that forms the body of an <a href=
|
|
"#element-if"><code>xsl:if</code></a> instruction that is itself in
|
|
a <a title="tail position" class="termref" href=
|
|
"#dt-tail-position">tail position</a> within <var>SC</var>.</p>
|
|
</li>
|
|
<li>
|
|
<p><var>J</var> is in a <a title="tail position" class="termref"
|
|
href="#dt-tail-position">tail position</a> within the sequence
|
|
constructor that forms the body of an <a href=
|
|
"#element-when"><code>xsl:when</code></a> or <a href=
|
|
"#element-otherwise"><code>xsl:otherwise</code></a> branch of an
|
|
<a href="#element-choose"><code>xsl:choose</code></a> instruction
|
|
that is itself in a <a title="tail position" class="termref" href=
|
|
"#dt-tail-position">tail position</a> within <var>SC</var>.</p>
|
|
</li>
|
|
<li>
|
|
<p><var>J</var> is in a <a title="tail position" class="termref"
|
|
href="#dt-tail-position">tail position</a> within the sequence
|
|
constructor that forms the body of an <a href=
|
|
"#element-try"><code>xsl:try</code></a> instruction that is itself
|
|
in a <a title="tail position" class="termref" href=
|
|
"#dt-tail-position">tail position</a> within <var>SC</var> (that
|
|
is, it is immediately followed by an <a href=
|
|
"#element-catch"><code>xsl:catch</code></a> element, ignoring any
|
|
<a href="#element-fallback"><code>xsl:fallback</code></a>
|
|
elements).</p>
|
|
</li>
|
|
<li>
|
|
<p><var>J</var> is in a <a title="tail position" class="termref"
|
|
href="#dt-tail-position">tail position</a> within the sequence
|
|
constructor that forms the body of an <a href=
|
|
"#element-catch"><code>xsl:catch</code></a> element within an
|
|
<a href="#element-try"><code>xsl:try</code></a> instruction that is
|
|
itself in a <a title="tail position" class="termref" href=
|
|
"#dt-tail-position">tail position</a> within <var>SC</var>.</p>
|
|
</li>
|
|
</ul>
|
|
<p><a name="err-XTSE2110" id="err-XTSE2110"><span class=
|
|
"error">[ERR XTSE2110]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> if an
|
|
<a href="#element-break"><code>xsl:break</code></a> or <a href=
|
|
"#element-next-iteration"><code>xsl:next-iteration</code></a>
|
|
element appears other than in a <a title="tail position" class=
|
|
"termref" href="#dt-tail-position">tail position</a> within the
|
|
<a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> forming the
|
|
body of an <a href="#element-iterate"><code>xsl:iterate</code></a>
|
|
instruction.</p>
|
|
<p><a name="err-XTSE2120" id="err-XTSE2120"><span class=
|
|
"error">[ERR XTSE2120]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> if the
|
|
<code>name</code> attribute of an <a href=
|
|
"#element-with-param"><code>xsl:with-param</code></a> child of an
|
|
<a href=
|
|
"#element-next-iteration"><code>xsl:next-iteration</code></a>
|
|
element does not match the <code>name</code> attribute of an
|
|
<a href="#element-param"><code>xsl:param</code></a> child of the
|
|
<span>innermost</span> containing <a href=
|
|
"#element-iterate"><code>xsl:iterate</code></a> instruction.</p>
|
|
<p>Parameter names in <a href=
|
|
"#element-with-param"><code>xsl:with-param</code></a> must be
|
|
unique: <span class="error">[see <a href="#err-XTSE0670">ERR
|
|
XTSE0670</a>]</span>.</p>
|
|
<p>The result of the <a href=
|
|
"#element-iterate"><code>xsl:iterate</code></a> instruction is the
|
|
concatenation of the sequences that result from the repeated
|
|
evaluation of the contained <a title="sequence constructor" class=
|
|
"termref" href="#dt-sequence-constructor">sequence constructor</a>,
|
|
followed by the sequence that results from evaluating the <a title=
|
|
"sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> contained
|
|
within the <a href="#element-break"><code>xsl:break</code></a> or
|
|
<a href="#element-on-completion"><code>xsl:on-completion</code></a>
|
|
element if any.</p>
|
|
<p>Any <a href="#element-param"><code>xsl:param</code></a> element
|
|
that appears as a child of <a href=
|
|
"#element-iterate"><code>xsl:iterate</code></a> declares a
|
|
parameter whose value may vary from one iteration to the next. The
|
|
initial value of the parameter is the value obtained according to
|
|
the rules given in <a href="#variable-values"><i>9.3 Values of
|
|
Variables and Parameters</i></a>. The dynamic context for
|
|
evaluating the initial value of an <a href=
|
|
"#element-param"><code>xsl:param</code></a> element is the same as
|
|
the dynamic context for evaluating the <code>select</code>
|
|
expression of the <a href=
|
|
"#element-iterate"><code>xsl:iterate</code></a> instruction (the
|
|
context item is thus <em>not</em> the first item in the input
|
|
sequence).</p>
|
|
<p>On the first iteration a parameter always takes its initial
|
|
value (which may depend on variables or other aspects of the
|
|
dynamic context). Subsequently:</p>
|
|
<ul>
|
|
<li>
|
|
<p>If an <a href=
|
|
"#element-next-iteration"><code>xsl:next-iteration</code></a>
|
|
instruction is evaluated, then parameter values for processing the
|
|
next item in the input sequence can be set in the <a href=
|
|
"#element-with-param"><code>xsl:with-param</code></a> children of
|
|
that instruction; in the absence of an <a href=
|
|
"#element-with-param"><code>xsl:with-param</code></a> element that
|
|
names a particular parameter, that parameter will retain its value
|
|
from the previous iteration.</p>
|
|
</li>
|
|
<li>
|
|
<p>If an <a href="#element-break"><code>xsl:break</code></a>
|
|
instruction is evaluated, no further items in the input sequence
|
|
are processed.</p>
|
|
</li>
|
|
<li>
|
|
<p>If neither an <a href=
|
|
"#element-next-iteration"><code>xsl:next-iteration</code></a> nor
|
|
an <a href="#element-break"><code>xsl:break</code></a> instruction
|
|
is evaluated, then the next item in the input sequence is processed
|
|
using parameter values that are unchanged from the previous
|
|
iteration.</p>
|
|
</li>
|
|
</ul>
|
|
<p>The <a href=
|
|
"#element-next-iteration"><code>xsl:next-iteration</code></a>
|
|
instruction contributes nothing to the result sequence
|
|
(technically, it returns an empty sequence). The instruction
|
|
supplies parameter values for the next iteration, which are
|
|
evaluated according to the rules given in <a href=
|
|
"#with-param"><i>9.8 Setting Parameter Values</i></a>; if there are
|
|
no further items in the input sequence then it supplies parameter
|
|
values for use while evaluating the body of the <a href=
|
|
"#element-on-completion"><code>xsl:on-completion</code></a> element
|
|
if any.</p>
|
|
<p>The <a href="#element-break"><code>xsl:break</code></a>
|
|
instruction indicates that the iteration should terminate without
|
|
processing any remaining items from the input sequence. The
|
|
contained sequence constructor is evaluated using the same context
|
|
item, position, and size as the <a href=
|
|
"#element-break"><code>xsl:break</code></a> instruction itself, and
|
|
the result is appended to the result of the <a href=
|
|
"#element-iterate"><code>xsl:iterate</code></a> instruction as a
|
|
whole.</p>
|
|
<p>If neither an <a href=
|
|
"#element-next-iteration"><code>xsl:next-iteration</code></a> nor
|
|
an <a href="#element-break"><code>xsl:break</code></a> instruction
|
|
is evaluated, the next item in the input sequence is processed with
|
|
parameter values unchanged from the previous iteration; if there
|
|
are no further items in the input sequence, the iteration
|
|
terminates.</p>
|
|
<p>The optional <a href=
|
|
"#element-on-completion"><code>xsl:on-completion</code></a> element
|
|
(which is not technically an <a title="instruction" class="termref"
|
|
href="#dt-instruction">instruction</a> and is not technically part
|
|
of the <a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a>) is evaluated
|
|
when the input sequence is exhausted. It is not evaluated if the
|
|
evaluation is terminated using <a href=
|
|
"#element-break"><code>xsl:break</code></a>. During evaluation of
|
|
this sequence constructor the context item, position, and size are
|
|
undefined (that is, any reference to these values is an error).
|
|
However, the values of the parameters to <a href=
|
|
"#element-iterate"><code>xsl:iterate</code></a> are available, and
|
|
take the values supplied by the <a href=
|
|
"#element-next-iteration"><code>xsl:next-iteration</code></a>
|
|
instruction evaluated while processing the last item in the
|
|
sequence.</p>
|
|
<p>If the input sequence is empty, then the result of the <a href=
|
|
"#element-iterate"><code>xsl:iterate</code></a> instruction is the
|
|
result of evaluating the <a title="sequence constructor" class=
|
|
"termref" href="#dt-sequence-constructor">sequence constructor</a>
|
|
forming the body of the <a href=
|
|
"#element-on-completion"><code>xsl:on-completion</code></a>
|
|
element, using the initial values of the <a href=
|
|
"#element-param"><code>xsl:param</code></a> elements. If there is
|
|
no <a href=
|
|
"#element-on-completion"><code>xsl:on-completion</code></a>
|
|
element, the result is an empty sequence.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>Conceptually, <a href=
|
|
"#element-iterate"><code>xsl:iterate</code></a> behaves like a
|
|
tail-recursive function. The <a href=
|
|
"#element-next-iteration"><code>xsl:next-iteration</code></a>
|
|
instruction then represents the recursive call, supplying the tail
|
|
of the input sequence as an implicit parameter. There are two main
|
|
reasons for providing the <a href=
|
|
"#element-iterate"><code>xsl:iterate</code></a> instruction. One is
|
|
that many XSLT users find writing recursive functions to be a
|
|
difficult skill, and this construct promises to be easier to learn.
|
|
The other is that recursive function calls are difficult for an
|
|
optimizer to analyze. Because <a href=
|
|
"#element-iterate"><code>xsl:iterate</code></a> is more constrained
|
|
than a general-purpose head-tail recursive function, it should be
|
|
more amenable to optimization. In particular, when the instruction
|
|
is used in conjunction with <a href=
|
|
"#element-stream"><code>xsl:stream</code></a>, it is designed to
|
|
make it easy for the implementation to use streaming techniques,
|
|
processing the nodes in an input document sequentially as they are
|
|
read, without building the entire document tree in memory.</p>
|
|
</div>
|
|
<blockquote>
|
|
<p><b><a name="issue-iterate-empty" id="issue-iterate-empty">Issue
|
|
10 (iterate-empty)</a>:</b></p>
|
|
<p>The Working Group is considering whether more control is needed
|
|
over how an empty sequence is processed. Currently, whether a
|
|
sequence is processed using <a href=
|
|
"#element-for-each"><code>xsl:for-each</code></a>, <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>, or
|
|
<a href="#element-iterate"><code>xsl:iterate</code></a>, there is
|
|
no easy way to define special code for handling an empty sequence
|
|
in a way that satisfies the rules for streamability, because one
|
|
downward selection is needed to test for emptiness, another to
|
|
perform iteration when non-empty. One possible solution is the
|
|
proposed <a href=
|
|
"#function-has-children"><code>has-children</code></a>
|
|
function.</p>
|
|
</blockquote>
|
|
<p>The examples below use <a href=
|
|
"#element-iterate"><code>xsl:iterate</code></a> in conjunction with
|
|
the <a href="#element-stream"><code>xsl:stream</code></a>
|
|
instruction. This is not the only way of using <a href=
|
|
"#element-iterate"><code>xsl:iterate</code></a>, but it illustrates
|
|
the way in which the two features can be combined to achieve
|
|
streaming of a large input document.</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e15084" id=
|
|
"d7e15084"></a>Example: Using <code>xsl:iterate</code> to compute
|
|
cumulative totals</div>
|
|
<p>Suppose that the input XML document has this structure</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<transactions>
|
|
<transaction date="2008-09-01" value="12.00"/>
|
|
<transaction date="2008-09-01" value="8.00"/>
|
|
<transaction date="2008-09-02" value="-2.00"/>
|
|
<transaction date="2008-09-02" value="5.00"/>
|
|
</transactions>
|
|
</pre></div>
|
|
<p>and that the requirement is to transform this to:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<account>
|
|
<balance date="2008-09-01" value="12.00"/>
|
|
<balance date="2008-09-01" value="20.00"/>
|
|
<balance date="2008-09-02" value="18.00"/>
|
|
<balance date="2008-09-02" value="23.00"/>
|
|
</account>
|
|
</pre></div>
|
|
<p>This can be achieved using the following code, which is designed
|
|
to process the transaction file using streaming:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<account>
|
|
<xsl:stream href="transactions.xml">
|
|
<xsl:iterate select="transactions/transaction">
|
|
<xsl:param name="balance" select="0.00" as="xs:decimal"/>
|
|
<xsl:variable name="newBalance"
|
|
select="$balance + xs:decimal(@value)"/>
|
|
<balance date="{@date}" value="{$newBalance}"/>
|
|
<xsl:next-iteration>
|
|
<xsl:with-param name="balance" select="$newBalance"/>
|
|
</xsl:next-iteration>
|
|
</xsl:iterate>
|
|
</xsl:stream>
|
|
</account>
|
|
</pre></div>
|
|
<p>The following example modifies this by only outputting the
|
|
information for the first day's transactions:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<account>
|
|
<xsl:stream href="'transactions.xml">
|
|
<xsl:iterate select="transactions/transaction">
|
|
<xsl:param name="balance" select="0.00" as="xs:decimal"/>
|
|
<xsl:param name="prevDate" select="()" as="xs:date?"/>
|
|
<xsl:variable name="newBalance"
|
|
select="$balance + xs:decimal(@value)"/>
|
|
<xsl:variable name="thisDate"
|
|
select="xs:date(@date)"/>
|
|
<xsl:choose>
|
|
<xsl:when test="empty($prevDate) or $thisDate eq $prevDate">
|
|
<balance date="{$thisDate}"
|
|
value="{format-number($newBalance, '0.00')}"/>
|
|
<xsl:next-iteration>
|
|
<xsl:with-param name="balance" select="$newBalance"/>
|
|
<xsl:with-param name="prevDate" select="$thisDate"/>
|
|
</xsl:next-iteration>
|
|
</xsl:when>
|
|
<xsl:otherwise>
|
|
<xsl:break/>
|
|
</xsl:otherwise>
|
|
</xsl:choose>
|
|
</xsl:iterate>
|
|
</xsl:stream>
|
|
</account>
|
|
</pre></div>
|
|
<p>The following code outputs the balance only at the end of each
|
|
day, together with the final balance:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<account>
|
|
<xsl:stream href="transactions.xml">
|
|
<xsl:iterate select="transactions/transaction">
|
|
<xsl:param name="balance" select="0.00" as="xs:decimal"/>
|
|
<xsl:param name="prevDate" select="()" as="xs:date?"/>
|
|
<xsl:variable name="newBalance"
|
|
select="$balance + xs:decimal(@value)"/>
|
|
<xsl:variable name="thisDate" select="xs:date(@date)"/>
|
|
<xsl:if test="exists($prevDate) and $thisDate ne $prevDate">
|
|
<balance date="{$prevDate}"
|
|
value="{format-number($balance, '0.00')}"/>
|
|
</xsl:if>
|
|
<xsl:next-iteration>
|
|
<xsl:with-param name="balance" select="$newBalance"/>
|
|
<xsl:with-param name="prevDate" select="$thisDate"/>
|
|
</xsl:next-iteration>
|
|
<xsl:on-completion>
|
|
<balance date="{$prevDate}"
|
|
value="{format-number($balance, '0.00')}"/>
|
|
</xsl:on-completion>
|
|
</xsl:iterate>
|
|
</xsl:stream>
|
|
</account>
|
|
</pre></div>
|
|
<p>If the sequence of transactions is empty, this code outputs a
|
|
single element: <code><balance date=""
|
|
value="0.00"/></code>.</p>
|
|
</div>
|
|
<p> </p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e15116" id=
|
|
"d7e15116"></a>Example: Collecting multiple values in a single
|
|
pass</div>
|
|
<p>Problem: Given a sequence of <code>employee</code> elements,
|
|
find the employees having the highest and lowest salary, while
|
|
processing each employee only once.</p>
|
|
<p>Solution:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:stream href="employees.xml">
|
|
<xsl:iterate select="employees/employee">
|
|
<xsl:param name="highest" as="element(employee)*"/>
|
|
<xsl:param name="lowest" as="element(employee)*"/>
|
|
<xsl:variable name="is-new-highest" as=xs:boolean"
|
|
select="empty($highest[@salary ge current()/@salary])"/>
|
|
<xsl:variable name="is-equal-highest" as=xs:boolean"
|
|
select="exists($highest[@salary eq current()/@salary])"/>
|
|
<xsl:variable name="is-new-lowest" as=xs:boolean"
|
|
select="empty($lowest[@salary le current()/@salary])"/>
|
|
<xsl:variable name="is-equal-lowest" as=xs:boolean"
|
|
select="exists($lowest[@salary eq current()/@salary])"/>
|
|
<xsl:variable name="new-highest-set" as=element(employee)*"
|
|
select="if ($is-new-highest) then .
|
|
else if ($is-equal-highest) then ($highest, .)
|
|
else $highest"/>
|
|
<xsl:variable name="new-lowest-set" as=element(employee)*"
|
|
select="if ($is-new-lowest) then .
|
|
else if ($is-equal-lowest) then ($lowest, .)
|
|
else $lowest"/>
|
|
<xsl:next-iteration>
|
|
<xsl:with-param name="highest" select="$new-highest-set"/>
|
|
<xsl:with-param name="lowest" select="$new-lowest-set"/>
|
|
</xsl:next-iteration>
|
|
<xsl:on-completion>
|
|
<highest-paid-employees>
|
|
<xsl:value-of select="$highest/name"/>
|
|
</highest-paid-employees>
|
|
<lowest-paid-employees>
|
|
<xsl:value-of select="$lowest/name"/>
|
|
</lowest-paid-employees>
|
|
</xsl:on-completion>
|
|
</xsl:iterate>
|
|
</xsl:stream>
|
|
</pre></div>
|
|
<p>If the input sequence is empty, this code outputs an empty
|
|
<code>highest-paid-employees</code> element and an empty
|
|
<code>lowest-paid-employees</code> element.</p>
|
|
</div>
|
|
<p> </p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e15136" id=
|
|
"d7e15136"></a>Example: Processing the last item in a sequence
|
|
specially</div>
|
|
<p>When streaming, some limited look-ahead is needed to determine
|
|
whether the item being processed is the last in a sequence. The
|
|
<a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-last"><code>last</code></a><sup><small>FO</small></sup>
|
|
function cannot be used in <a title="guaranteed-streamable" class=
|
|
"termref" href=
|
|
"#dt-guaranteed-streamable">guaranteed-streamable</a> code. The
|
|
<a href="#element-iterate"><code>xsl:iterate</code></a> instruction
|
|
provides a solution to this problem.</p>
|
|
<p>Problem: render the last paragraph in a section in some special
|
|
way, for example by using bold face. (The actual rendition is
|
|
achieved by processing the paragraph with mode
|
|
<code>last-para</code>.)</p>
|
|
<p>The solution uses <a href=
|
|
"#element-iterate"><code>xsl:iterate</code></a> to maintain a
|
|
one-element lookahead by explicit coding:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:template match="section" mode="streaming">
|
|
<xsl:iterate select="para">
|
|
<xsl:param name="prev" select="()" as="element(para)?"/>
|
|
<xsl:if test="$prev">
|
|
<xsl:apply-templates select="$prev"/>
|
|
</xsl:if>
|
|
<xsl:next-iteration>
|
|
<xsl:param name="prev" select="."/>
|
|
</xsl:next-iteration>
|
|
<xsl:on-completion>
|
|
<xsl:apply-templates select="$prev" mode="last-para"/>
|
|
</xsl:on-completion>
|
|
</xsl:iterate>
|
|
</xsl:template>
|
|
</pre></div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="div1">
|
|
<h2><a name="conditionals" id="conditionals"></a>8 <a href=
|
|
"#conditionals" style="text-decoration: none">Conditional
|
|
Processing</a></h2>
|
|
<p>There are two instructions in XSLT that support conditional
|
|
processing: <a href="#element-if"><code>xsl:if</code></a> and
|
|
<a href="#element-choose"><code>xsl:choose</code></a>. The <a href=
|
|
"#element-if"><code>xsl:if</code></a> instruction provides simple
|
|
if-then conditionality; the <a href=
|
|
"#element-choose"><code>xsl:choose</code></a> instruction supports
|
|
selection of one choice when there are several possibilities.</p>
|
|
<p>XSLT 2.1 also supports <a href=
|
|
"#element-try"><code>xsl:try</code></a> and <a href=
|
|
"#element-catch"><code>xsl:catch</code></a> which define
|
|
conditional processing to handle <a title="dynamic error" class=
|
|
"termref" href="#dt-dynamic-error">dynamic errors</a>.</p>
|
|
<div class="div2">
|
|
<h3><a name="xsl-if" id="xsl-if"></a>8.1 <a href="#xsl-if" style=
|
|
"text-decoration: none">Conditional Processing with</a> <a href=
|
|
"#element-if"><code>xsl:if</code></a> <a href="#xsl-if" style=
|
|
"text-decoration: none"></a></h3>
|
|
<p class="element-syntax"><a name="element-if" id=
|
|
"element-if"></a><code><!-- Category: instruction --><br />
|
|
<xsl:if<br />
|
|
  <b>test</b> = <var>expression</var> ><br />
|
|
  <!-- Content: <var>sequence-constructor</var>
|
|
--><br />
|
|
</xsl:if></code></p>
|
|
<p>The <a href="#element-if"><code>xsl:if</code></a> element has a
|
|
mandatory <code>test</code> attribute, which specifies an <a title=
|
|
"expression" class="termref" href="#dt-expression">expression</a>.
|
|
The content is a <a title="sequence constructor" class="termref"
|
|
href="#dt-sequence-constructor">sequence constructor</a>.</p>
|
|
<p>The result of the <a href="#element-if"><code>xsl:if</code></a>
|
|
instruction depends on the <a href=
|
|
"http://www.w3.org/TR/xpath-21/#dt-ebv">effective boolean
|
|
value</a><sup><small>XP21</small></sup> of the expression in the
|
|
<code>test</code> attribute. The rules for determining the
|
|
effective boolean value of an expression are given in <a href=
|
|
"#xpath-21">[XPath 2.1]</a>: they are the same as the rules used
|
|
for XPath conditional expressions.</p>
|
|
<p>If the effective boolean value of the <a title="expression"
|
|
class="termref" href="#dt-expression">expression</a> is true, then
|
|
the <a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> is evaluated
|
|
(see <a href="#sequence-constructors"><i>5.7 Sequence
|
|
Constructors</i></a>), and the resulting node sequence is returned
|
|
as the result of the <a href="#element-if"><code>xsl:if</code></a>
|
|
instruction; otherwise, the sequence constructor is not evaluated,
|
|
and the empty sequence is returned.</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e15242" id=
|
|
"d7e15242"></a>Example: Using <code>xsl:if</code></div>
|
|
<p>In the following example, the names in a group of names are
|
|
formatted as a comma separated list:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:template match="namelist/name">
|
|
<xsl:apply-templates/>
|
|
<xsl:if test="not(position()=last())">, </xsl:if>
|
|
</xsl:template>
|
|
</pre></div>
|
|
<p>The following colors every other table row yellow:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<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>
|
|
</pre></div>
|
|
</div>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="xsl-choose" id="xsl-choose"></a>8.2 <a href=
|
|
"#xsl-choose" style="text-decoration: none">Conditional Processing
|
|
with</a> <a href="#element-choose"><code>xsl:choose</code></a>
|
|
<a href="#xsl-choose" style="text-decoration: none"></a></h3>
|
|
<p class="element-syntax"><a name="element-choose" id=
|
|
"element-choose"></a><code><!-- Category: instruction
|
|
--><br />
|
|
<xsl:choose><br />
|
|
  <!-- Content: (<a href=
|
|
"#element-when">xsl:when</a>+, <a href=
|
|
"#element-otherwise">xsl:otherwise</a>?) --><br />
|
|
</xsl:choose></code></p>
|
|
<p class="element-syntax"><a name="element-when" id=
|
|
"element-when"></a><code><xsl:when<br />
|
|
  <b>test</b> = <var>expression</var> ><br />
|
|
  <!-- Content: <var>sequence-constructor</var>
|
|
--><br />
|
|
</xsl:when></code></p>
|
|
<p class="element-syntax"><a name="element-otherwise" id=
|
|
"element-otherwise"></a><code><xsl:otherwise><br />
|
|
  <!-- Content: <var>sequence-constructor</var>
|
|
--><br />
|
|
</xsl:otherwise></code></p>
|
|
<p>The <a href="#element-choose"><code>xsl:choose</code></a>
|
|
element selects one among a number of possible alternatives. It
|
|
consists of a sequence of one or more <a href=
|
|
"#element-when"><code>xsl:when</code></a> elements followed by an
|
|
optional <a href=
|
|
"#element-otherwise"><code>xsl:otherwise</code></a> element. Each
|
|
<a href="#element-when"><code>xsl:when</code></a> element has a
|
|
single attribute, <code>test</code>, which specifies an <a title=
|
|
"expression" class="termref" href="#dt-expression">expression</a>.
|
|
The content of the <a href=
|
|
"#element-when"><code>xsl:when</code></a> and <a href=
|
|
"#element-otherwise"><code>xsl:otherwise</code></a> elements is a
|
|
<a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a>.</p>
|
|
<p>When an <a href="#element-choose"><code>xsl:choose</code></a>
|
|
element is processed, each of the <a href=
|
|
"#element-when"><code>xsl:when</code></a> elements is tested in
|
|
turn (that is, in the order that the elements appear in the
|
|
stylesheet), until one of the <a href=
|
|
"#element-when"><code>xsl:when</code></a> elements is satisfied. If
|
|
none of the <a href="#element-when"><code>xsl:when</code></a>
|
|
elements is satisfied, then the <a href=
|
|
"#element-otherwise"><code>xsl:otherwise</code></a> element is
|
|
considered, as described below.</p>
|
|
<p>An <a href="#element-when"><code>xsl:when</code></a> element is
|
|
satisfied if the <a href=
|
|
"http://www.w3.org/TR/xpath-21/#dt-ebv">effective boolean
|
|
value</a><sup><small>XP21</small></sup> of the <a title=
|
|
"expression" class="termref" href="#dt-expression">expression</a>
|
|
in its <code>test</code> attribute is <code>true</code>. The rules
|
|
for determining the effective boolean value of an expression are
|
|
given in <a href="#xpath-21">[XPath 2.1]</a>: they are the same as
|
|
the rules used for XPath conditional expressions.</p>
|
|
<p>The content of the first, and only the first, <a href=
|
|
"#element-when"><code>xsl:when</code></a> element that is satisfied
|
|
is evaluated, and the resulting sequence is returned as the result
|
|
of the <a href="#element-choose"><code>xsl:choose</code></a>
|
|
instruction. If no <a href=
|
|
"#element-when"><code>xsl:when</code></a> element is satisfied, the
|
|
content of the <a href=
|
|
"#element-otherwise"><code>xsl:otherwise</code></a> element is
|
|
evaluated, and the resulting sequence is returned as the result of
|
|
the <a href="#element-choose"><code>xsl:choose</code></a>
|
|
instruction. If no <a href=
|
|
"#element-when"><code>xsl:when</code></a> element is satisfied, and
|
|
no <a href="#element-otherwise"><code>xsl:otherwise</code></a>
|
|
element is present, the result of the <a href=
|
|
"#element-choose"><code>xsl:choose</code></a> instruction is an
|
|
empty sequence.</p>
|
|
<p>Only the sequence constructor of the selected <a href=
|
|
"#element-when"><code>xsl:when</code></a> or <a href=
|
|
"#element-otherwise"><code>xsl:otherwise</code></a> instruction is
|
|
evaluated. The <code>test</code> expressions for <a href=
|
|
"#element-when"><code>xsl:when</code></a> instructions after the
|
|
selected one are not evaluated.</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e15387" id=
|
|
"d7e15387"></a>Example: Using <code>xsl:choose</code></div>
|
|
<p>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.</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<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>
|
|
</pre></div>
|
|
</div>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="try-catch" id="try-catch"></a>8.3 <a href="#try-catch"
|
|
style="text-decoration: none">Try/Catch</a></h3>
|
|
<p>The <a href="#element-try"><code>xsl:try</code></a> instruction
|
|
can be used to trap dynamic errors occurring within the expression
|
|
it wraps; the recovery action if such errors occur is defined using
|
|
a child <a href="#element-catch"><code>xsl:catch</code></a>
|
|
element.</p>
|
|
<p class="element-syntax"><a name="element-try" id=
|
|
"element-try"></a><code><!-- Category: instruction --><br />
|
|
<xsl:try<br />
|
|
  select? = <var>expression</var> ><br />
|
|
  <!-- Content: (<var>sequence-constructor</var>,
|
|
<a href="#element-catch">xsl:catch</a>, (<a href=
|
|
"#element-catch">xsl:catch</a> | <a href=
|
|
"#element-fallback">xsl:fallback</a>)*) --><br />
|
|
</xsl:try></code></p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>Because a sequence constructor may contain an <a href=
|
|
"#element-fallback"><code>xsl:fallback</code></a> element, the
|
|
effect of this content model is that an <a href=
|
|
"#element-fallback"><code>xsl:fallback</code></a> instruction may
|
|
appear as a child of <a href=
|
|
"#element-try"><code>xsl:try</code></a> in any position.</p>
|
|
</div>
|
|
<p class="element-syntax"><a name="element-catch" id=
|
|
"element-catch"></a><code><xsl:catch<br />
|
|
  errors? = <var>tokens</var><br />
|
|
  select? = <var>expression</var> ><br />
|
|
  <!-- Content: <var>sequence-constructor</var>
|
|
--><br />
|
|
</xsl:catch></code></p>
|
|
<p>An <a href="#element-try"><code>xsl:try</code></a> instruction
|
|
evaluates either the expression contained in its
|
|
<code>select</code> attribute, or its contained <a title=
|
|
"sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a>, and returns
|
|
the result of that evaluation if it succeeds without error. If a
|
|
<a title="dynamic error" class="termref" href=
|
|
"#dt-dynamic-error">dynamic error</a> occurs during the evaluation,
|
|
the processor evaluates the first <a href=
|
|
"#element-catch"><code>xsl:catch</code></a> child element
|
|
applicable to the error, and returns that result instead.</p>
|
|
<p>If the <a href="#element-try"><code>xsl:try</code></a> element
|
|
has a <code>select</code> attribute, then it must have no children
|
|
other than <a href="#element-catch"><code>xsl:catch</code></a> and
|
|
<a href="#element-fallback"><code>xsl:fallback</code></a>. That is,
|
|
the <code>select</code> attribute and the contained sequence
|
|
constructor are mutually exclusive. If neither is present, the
|
|
result of the <a href="#element-try"><code>xsl:try</code></a> is an
|
|
empty sequence (no dynamic error can occur in this case).</p>
|
|
<p><a name="err-XTSE2130" id="err-XTSE2130"><span class=
|
|
"error">[ERR XTSE2130]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> if the
|
|
<code>select</code> attribute of the <a href=
|
|
"#element-try"><code>xsl:try</code></a> element is present and the
|
|
element has children other than <a href=
|
|
"#element-catch"><code>xsl:catch</code></a> and <a href=
|
|
"#element-fallback"><code>xsl:fallback</code></a> elements.</p>
|
|
<p>Any <a href="#element-fallback"><code>xsl:fallback</code></a>
|
|
children of the <a href="#element-try"><code>xsl:try</code></a>
|
|
element are ignored by an XSLT 2.1 processor, but can be used to
|
|
define the recovery action taken by an XSLT 1.0 or XSLT 2.0
|
|
processor operating with <a title="forwards compatible behavior"
|
|
class="termref" href="#dt-forwards-compatible-behavior">forwards
|
|
compatible behavior</a>.</p>
|
|
<p>The <a href="#element-catch"><code>xsl:catch</code></a> element
|
|
has an optional <code>errors</code> attribute, which lists the
|
|
error conditions that the <a href=
|
|
"#element-catch"><code>xsl:catch</code></a> element is designed to
|
|
intercept. The default value is <code>errors="*"</code>, which
|
|
catches all errors. The value is a whitespace-separated list of
|
|
<a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-NameTest">NameTests</a><sup><small>XP21</small></sup>;
|
|
an <a href="#element-catch"><code>xsl:catch</code></a> element
|
|
catches an error condition if this list includes a
|
|
<code>NameTest</code> that matches the error code associated with
|
|
that error condition.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>Error codes are QNames. Those defined in this specification and
|
|
in related specifications are all in the <a title=
|
|
"standard error namespace" class="termref" href=
|
|
"#dt-standard-error-namespace">standard error namespace</a>, and
|
|
may therefore be caught using an <a href=
|
|
"#element-catch"><code>xsl:catch</code></a> element such as
|
|
<code><xsl:catch errors="err:FODC0001 err:FODC0005"></code>
|
|
where the namespace prefix <code>err</code> is bound to this
|
|
namespace. Errors defined by implementors, and errors raised by an
|
|
explicit call of the <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-error"><code>error</code></a><sup><small>FO</small></sup>
|
|
function or by use of the <a href=
|
|
"#element-message"><code>xsl:message</code></a> instruction,
|
|
<span class="verb">may</span> use error codes in other
|
|
namespaces.</p>
|
|
</div>
|
|
<p>If more than one <a href=
|
|
"#element-catch"><code>xsl:catch</code></a> element matches an
|
|
error, the error is processed using the first one that matches, in
|
|
document order. If no <a href=
|
|
"#element-catch"><code>xsl:catch</code></a> matches the error, then
|
|
the error is not caught (that is, evaluation of the <a href=
|
|
"#element-try"><code>xsl:try</code></a> element fails with the
|
|
dynamic error).</p>
|
|
<p>An <a href="#element-catch"><code>xsl:catch</code></a> element
|
|
may have either a <code>select</code> attribute, or a contained
|
|
<a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a>.</p>
|
|
<p><a name="err-XTSE2140" id="err-XTSE2140"><span class=
|
|
"error">[ERR XTSE2140]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> if the
|
|
<code>select</code> attribute of the <a href=
|
|
"#element-catch"><code>xsl:catch</code></a> element is present
|
|
unless the element has empty content.</p>
|
|
<p>The result of evaluating the <a href=
|
|
"#element-catch"><code>xsl:catch</code></a> element is the result
|
|
of evaluating the XPath expression in its <code>select</code>
|
|
attribute or the result of evaluating the contained sequence
|
|
constructor; if neither is present, the result is an empty
|
|
sequence. This result is delivered as the result of the
|
|
<code>xsl:try</code> instruction.</p>
|
|
<p>If a dynamic error occurs during the evaluation of <a href=
|
|
"#element-catch"><code>xsl:catch</code></a>, it causes the
|
|
containing <a href="#element-try"><code>xsl:try</code></a> to fail
|
|
with this error. The error is not caught by other sibling <a href=
|
|
"#element-catch"><code>xsl:catch</code></a> elements within the
|
|
same <a href="#element-try"><code>xsl:try</code></a> instruction,
|
|
but it may be caught by an <a href=
|
|
"#element-try"><code>xsl:try</code></a> instruction at an outer
|
|
level, or by an <a href="#element-try"><code>xsl:try</code></a>
|
|
instruction nested within the <a href=
|
|
"#element-catch"><code>xsl:catch</code></a>.</p>
|
|
<p>Within the <code>select</code> expression, or within the
|
|
sequence constructor contained by the <a href=
|
|
"#element-catch"><code>xsl:catch</code></a> element, a number of
|
|
variables are implicitly declared, giving information about the
|
|
error that occurred. These are lexically scoped to the
|
|
<code>xsl:catch</code> element. These variables are all in the
|
|
<a title="standard error namespace" class="termref" href=
|
|
"#dt-standard-error-namespace">standard error namespace</a>, and
|
|
they are initialized as described in the following table:</p>
|
|
<table border="1" cellpadding="5">
|
|
<thead>
|
|
<tr>
|
|
<th align="left" colspan="1">Variable</th>
|
|
<th align="left" colspan="1">Type</th>
|
|
<th align="left" colspan="1">Value</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td valign="top">err:code</td>
|
|
<td valign="top">xs:QName</td>
|
|
<td valign="top">The error code</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">err:description</td>
|
|
<td valign="top">xs:string</td>
|
|
<td valign="top">A description of the error condition</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">err:value</td>
|
|
<td valign="top">item()*</td>
|
|
<td valign="top">Value associated with the error. For an error
|
|
raised by calling the <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-error"><code>error</code></a><sup><small>FO</small></sup>
|
|
function, this is the value of the third argument (if supplied).
|
|
For an error raised by evaluating <a href=
|
|
"#element-message"><code>xsl:message</code></a> with
|
|
<code>terminate="yes"</code>, this is the document node at the root
|
|
of the tree containing the XML message body.</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">err:module</td>
|
|
<td valign="top">xs:string?</td>
|
|
<td valign="top">The URI (or system ID) of the stylesheet module
|
|
containing the instruction where the error occurred; an empty
|
|
sequence if the information is not available.</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">err:line-number</td>
|
|
<td valign="top">xs:integer?</td>
|
|
<td valign="top">The line number within the stylesheet module of
|
|
the instruction where the error occurred; an empty sequence if the
|
|
information is not available. The value <span class=
|
|
"verb">may</span> be approximate.</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">err:column-number</td>
|
|
<td valign="top">xs:integer?</td>
|
|
<td valign="top">The column number within the stylesheet module of
|
|
the instruction where the error occurred; an empty sequence if the
|
|
information is not available. The value <span class=
|
|
"verb">may</span> be approximate.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>Variables declared within the sequence constructor of the
|
|
<a href="#element-try"><code>xsl:try</code></a> element (and not
|
|
within an <a href="#element-catch"><code>xsl:catch</code></a>) are
|
|
not visible within the <a href=
|
|
"#element-catch"><code>xsl:catch</code></a> element.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>Within an <a href="#element-catch"><code>xsl:catch</code></a> it
|
|
is possible to re-throw the error using the function call
|
|
<code>error($err:code, $err:description, $err:value)</code>.</p>
|
|
</div>
|
|
<p>The following additional rules apply to the catching of
|
|
errors:</p>
|
|
<ol class="enumar">
|
|
<li>
|
|
<p>All dynamic errors occurring during the evaluation of the
|
|
<a href="#element-try"><code>xsl:try</code></a> sequence
|
|
constructor or <code>select</code> expression are caught (provided
|
|
they match one of the <a href=
|
|
"#element-catch"><code>xsl:catch</code></a> elements).</p>
|
|
<ul>
|
|
<li>
|
|
<p>This includes errors occurring in functions or templates invoked
|
|
in the course of this evaluation, unless already caught by a nested
|
|
<a href="#element-try"><code>xsl:try</code></a>.</p>
|
|
</li>
|
|
<li>
|
|
<p>It also includes errors caused by calling the <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-error"><code>error</code></a><sup><small>FO</small></sup>
|
|
function or the <a href=
|
|
"#element-message"><code>xsl:message</code></a> instruction with
|
|
<code>terminate="yes"</code>.</p>
|
|
</li>
|
|
<li>
|
|
<p>It does not include errors that occur while evaluating
|
|
references to variables whose declaration and initialization is
|
|
outside the <a href="#element-try"><code>xsl:try</code></a>.</p>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
<p>The existence of an <a href=
|
|
"#element-try"><code>xsl:try</code></a> instruction does not affect
|
|
the right of the processor to recover, or not recover, from errors
|
|
classified as <a title="recoverable error" class="termref" href=
|
|
"#dt-recoverable-error">recoverable dynamic errors</a>. An <a href=
|
|
"#element-catch"><code>xsl:catch</code></a> element will be
|
|
activated only if the processor chooses to signal the error rather
|
|
than taking the defined recovery action.</p>
|
|
</li>
|
|
<li>
|
|
<p>The existence of an <a href=
|
|
"#element-try"><code>xsl:try</code></a> instruction does not affect
|
|
the obligation of the processor to signal certain errors as static
|
|
errors, or its right to choose whether to signal some errors (such
|
|
as type errors) statically or dynamically. Static errors are never
|
|
caught.</p>
|
|
</li>
|
|
<li>
|
|
<p>Some fatal errors arising in the processing environment, such as
|
|
running out of memory, may cause termination of the transformation
|
|
despite the presence of an <a href=
|
|
"#element-try"><code>xsl:try</code></a> instruction. This is
|
|
<a title="implementation-dependent" class="termref" href=
|
|
"#dt-implementation-dependent">implementation-dependent</a>.</p>
|
|
</li>
|
|
<li>
|
|
<p>If the sequence constructor or <code>select</code> expression of
|
|
the <a href="#element-try"><code>xsl:try</code></a> causes
|
|
execution of <a href=
|
|
"#element-result-document"><code>xsl:result-document</code></a> or
|
|
<a href="#element-message"><code>xsl:message</code></a>
|
|
instructions and fails with a dynamic error that is caught, it is
|
|
implementation-dependent whether these instructions have any
|
|
externally visible effect. The processor is <span class="verb">not
|
|
required</span> to do a "rollback" of any changes made by these
|
|
instructions. The same applies to any side effects caused by
|
|
extension functions or extension instructions.</p>
|
|
</li>
|
|
<li>
|
|
<p>If the <a href="#element-try"><code>xsl:try</code></a> element
|
|
appears in a context where it is required to deliver a value of a
|
|
specified type (for example, if it appears as the body of a
|
|
stylesheet function), then any error that occurs because it
|
|
delivers a value of the wrong type, or an error that occurs during
|
|
conversion to the required type (for example, during atomization),
|
|
is treated as occurring within the scope of the <a href=
|
|
"#element-try"><code>xsl:try</code></a> instruction.</p>
|
|
</li>
|
|
<li>
|
|
<p>When an instruction <var>J</var> computes a value that will
|
|
inevitably cause some outer-level instruction <var>O</var> to fail
|
|
with a dynamic error, then the failure <span class=
|
|
"verb">may</span> be treated as occurring in <var>J</var>, in which
|
|
case it will be caught by an <a href=
|
|
"#element-try"><code>xsl:try</code></a> instruction whose scope
|
|
includes <var>J</var> but does not include <var>O</var>. For
|
|
example, creating an element may fail because the element is not
|
|
allowed by the content model of a containing element; although the
|
|
specification describes this as a failure associated with the
|
|
construction of the containing element, a processor is allowed to
|
|
detect the error as soon as it becomes inevitable.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>The effect of this rule is that when stylesheet output is
|
|
streamed to a schema validator or to a serializer, errors detected
|
|
by the validation or serialization process may be treated if they
|
|
occurred in the instruction that generated the offending output;
|
|
however, stylesheet authors cannot rely on this. In fact, where
|
|
serialization is applied to a <a title="final result tree" class=
|
|
"termref" href="#dt-final-result-tree">final result tree</a>, there
|
|
is no guarantee that it will be possible to catch the error at all,
|
|
since serialization is outside the scope of the transformation
|
|
process proper.</p>
|
|
</div>
|
|
</li>
|
|
<li>
|
|
<p>The fact that the application tries to catch errors does not
|
|
prevent the processor from organizing the evaluation in such a way
|
|
as to prevent errors occurring. For example <code>exists(//a[10 div
|
|
. gt 5])</code> may still do an "early exit", rather than examining
|
|
every item in the sequence just to see if it triggers a
|
|
divide-by-zero error.</p>
|
|
</li>
|
|
<li>
|
|
<p>A failure occurring while evaluating the match pattern of a
|
|
template rule, if not treated as a recoverable error, is treated as
|
|
occurring during the evaluation of the calling <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>
|
|
instruction (or <a href=
|
|
"#element-apply-imports"><code>xsl:apply-imports</code></a> or
|
|
<a href="#element-next-match"><code>xsl:next-match</code></a> if
|
|
appropriate).</p>
|
|
</li>
|
|
<li>
|
|
<p>Except as specified above, the optimizer must not rearrange the
|
|
evaluation (at compile time or at run time) so that expressions
|
|
written to be subject to to the try/catch are evaluated outside its
|
|
scope, or expressions written to be external to the try/catch are
|
|
evaluated within its scope. This does not prevent expressions being
|
|
rearranged, but any expression that is so rearranged must carry its
|
|
try/catch context with it.</p>
|
|
</li>
|
|
</ol>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>If an error occurs while evaluating an instruction within
|
|
<a href="#element-try"><code>xsl:try</code></a>, then no
|
|
instruction within the <a href=
|
|
"#element-try"><code>xsl:try</code></a> has any effect on the
|
|
result returned by the <a href=
|
|
"#element-try"><code>xsl:try</code></a> instruction. This means
|
|
that if a processor is streaming the output to a serializer, it
|
|
needs to adopt a strategy such as buffering the output in memory so
|
|
that nothing is written until successful completion of the <a href=
|
|
"#element-try"><code>xsl:try</code></a> instruction, or
|
|
checkpointing the output so it can be rolled back when an error
|
|
occurs.</p>
|
|
</div>
|
|
<blockquote>
|
|
<p><b><a name="issue-try-catch-output-buffering" id=
|
|
"issue-try-catch-output-buffering">Issue 11
|
|
(try-catch-output-buffering)</a>:</b></p>
|
|
<p>The rules appear inconsistent: if the processor is obliged to
|
|
buffer "immediate" output from the xsl:try element before sending
|
|
it the serializer, should not the same requirement apply also to
|
|
xsl:result-document (rule 5)? And if output has to be buffered, is
|
|
rule 7 appropriate, allowing serialization errors to be detected
|
|
"on the fly"?</p>
|
|
</blockquote>
|
|
<div class="div3">
|
|
<h4><a name="try-catch-examples" id="try-catch-examples"></a>8.3.1
|
|
<a href="#try-catch-examples" style=
|
|
"text-decoration: none">Try/Catch Examples</a></h4>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e15899" id=
|
|
"d7e15899"></a>Example: Catching a divide-by-zero error</div>
|
|
<p>The following example divides an employee's salary by the number
|
|
of years they have served, catching the error if the latter is
|
|
zero.</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:try select="salary div length-of-service">
|
|
<xsl:catch errors="err:FAOR0001" select="()"/>
|
|
</xsl:try>
|
|
</pre></div>
|
|
</div>
|
|
<p> </p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e15906" id=
|
|
"d7e15906"></a>Example: Catching an error during result-tree
|
|
validation</div>
|
|
<p>The following example generates a result tree and performs
|
|
schema validation, outputting a warning message and serializing the
|
|
invalid tree if validation fails.</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:result-document href="out.xml">
|
|
<xsl:variable name="result">
|
|
<xsl:call-template name="construct-output"/>
|
|
</xsl:variable>
|
|
<xsl:try>
|
|
<xsl:copy-of select="$result" validation="strict"/>
|
|
<xsl:catch>
|
|
<xsl:message>Warning: validation of result document failed:
|
|
Error code: <xsl:value-of select="$err:code"/>
|
|
Reason: <xsl:value-of select="$err:description"/>
|
|
</xsl:message>
|
|
<xsl:sequence select="$result"/>
|
|
</xsl:catch>
|
|
</xsl:try>
|
|
</xsl:result-document>
|
|
</pre></div>
|
|
<p>The reason that the result tree is constructed in a variable in
|
|
this example is so that the unvalidated tree is available to be
|
|
used within the <a href="#element-catch"><code>xsl:catch</code></a>
|
|
element. An alternative approach would be to repeat the logic for
|
|
constructing the tree:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:try>
|
|
<xsl:result-document href="out.xml" validation="strict">
|
|
<xsl:call-template name="construct-output"/>
|
|
</xsl:result-document>
|
|
<xsl:catch>
|
|
<xsl:message>Warning: validation of result document failed:
|
|
Error code: <xsl:value-of select="$err:code"/>
|
|
Reason: <xsl:value-of select="$err:description"/>
|
|
</xsl:message>
|
|
<xsl:call-template name="construct-output"/>
|
|
</xsl:catch>
|
|
</xsl:try>
|
|
</pre></div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="div1">
|
|
<h2><a name="variables-and-parameters" id=
|
|
"variables-and-parameters"></a>9 <a href=
|
|
"#variables-and-parameters" style="text-decoration: none">Variables
|
|
and Parameters</a></h2>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-variable-binding-element" id="dt-variable-binding-element"
|
|
title="variable-binding element"></a>The two elements <a href=
|
|
"#element-variable"><code>xsl:variable</code></a> and <a href=
|
|
"#element-param"><code>xsl:param</code></a> are referred to as
|
|
<b>variable-binding elements</b> <span class=
|
|
"definition">]</span>.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-variable" id="dt-variable" title="variable"></a>The <a href=
|
|
"#element-variable"><code>xsl:variable</code></a> element declares
|
|
a <b>variable</b>, which may be a <a title="global variable" class=
|
|
"termref" href="#dt-global-variable">global variable</a> or a
|
|
<a title="local variable" class="termref" href=
|
|
"#dt-local-variable">local variable</a>.<span class=
|
|
"definition">]</span></p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-parameter" id="dt-parameter" title="parameter"></a>The <a href=
|
|
"#element-param"><code>xsl:param</code></a> element declares a
|
|
<b>parameter</b>, which may be a <a title="stylesheet parameter"
|
|
class="termref" href="#dt-stylesheet-parameter">stylesheet
|
|
parameter</a>, a <a title="template parameter" class="termref"
|
|
href="#dt-template-parameter">template parameter</a>, a <a title=
|
|
"function parameter" class="termref" href=
|
|
"#dt-function-parameter">function parameter</a><span>, or an
|
|
<a href="#element-iterate"><code>xsl:iterate</code></a>
|
|
parameter</span>. A parameter is a <a title="variable" class=
|
|
"termref" href="#dt-variable">variable</a> with the additional
|
|
property that its value can be set by the caller.<span class=
|
|
"definition">]</span></p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-value" id="dt-value" title="value"></a>A variable is a binding
|
|
between a name and a value. The <b>value</b> of a variable is any
|
|
sequence (of nodes, atomic values, <span>and/or function
|
|
items</span>), as defined in <a href="#xpath-datamodel-11">[Data
|
|
Model]</a>.<span class="definition">]</span></p>
|
|
<div class="div2">
|
|
<h3><a name="variables" id="variables"></a>9.1 <a href="#variables"
|
|
style="text-decoration: none">Variables</a></h3>
|
|
<p class="element-syntax"><a name="element-variable" id=
|
|
"element-variable"></a><code><!-- Category: declaration
|
|
--><br />
|
|
<!-- Category: instruction --><br />
|
|
<xsl:variable<br />
|
|
  <b>name</b> = <var>qname</var><br />
|
|
  select? = <var>expression</var><br />
|
|
  as? = <var>sequence-type</var> ><br />
|
|
  <!-- Content: <var>sequence-constructor</var>
|
|
--><br />
|
|
</xsl:variable></code></p>
|
|
<p>The <a href="#element-variable"><code>xsl:variable</code></a>
|
|
element has a <span class="verb">required</span> <code>name</code>
|
|
attribute, which specifies the name of the variable. The value of
|
|
the <code>name</code> attribute is a <a title="QName" class=
|
|
"termref" href="#dt-qname">QName</a>, which is expanded as
|
|
described in <a href="#qname"><i>5.1 Qualified Names</i></a>.</p>
|
|
<p>The <a href="#element-variable"><code>xsl:variable</code></a>
|
|
element has an optional <code>as</code> attribute, which specifies
|
|
the <a title="required type" class="termref" href=
|
|
"#dt-required-type">required type</a> of the variable. The value of
|
|
the <code>as</code> attribute is a <a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-SequenceType">SequenceType</a><sup><small>XP21</small></sup>,
|
|
as defined in <a href="#xpath-21">[XPath 2.1]</a>.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-supplied-value" id="dt-supplied-value" title=
|
|
"supplied value"></a>The value of the variable is computed using
|
|
the <a title="expression" class="termref" href=
|
|
"#dt-expression">expression</a> given in the <code>select</code>
|
|
attribute or the contained <a title="sequence constructor" class=
|
|
"termref" href="#dt-sequence-constructor">sequence constructor</a>,
|
|
as described in <a href="#variable-values"><i>9.3 Values of
|
|
Variables and Parameters</i></a>. This value is referred to as the
|
|
<b>supplied value</b> of the variable.<span class=
|
|
"definition">]</span> If the <a href=
|
|
"#element-variable"><code>xsl:variable</code></a> element has a
|
|
<code>select</code> attribute, then the sequence constructor
|
|
<span class="verb">must</span> be empty.</p>
|
|
<p>If the <code>as</code> attribute is specified, then the
|
|
<a title="supplied value" class="termref" href=
|
|
"#dt-supplied-value">supplied value</a> of the variable is
|
|
converted to the required type, using the <a title=
|
|
"function conversion rules" class="termref" href=
|
|
"#dt-function-conversion-rules">function conversion rules</a>.</p>
|
|
<p><a name="err-XTTE0570" id="err-XTTE0570"><span class=
|
|
"error">[ERR XTTE0570]</span></a> It is a <a title="type errors"
|
|
class="termref" href="#dt-type-error">type error</a> if the
|
|
<a title="supplied value" class="termref" href=
|
|
"#dt-supplied-value">supplied value</a> of a variable cannot be
|
|
converted to the required type.</p>
|
|
<p>If the <code>as</code> attribute is omitted, the <a title=
|
|
"supplied value" class="termref" href="#dt-supplied-value">supplied
|
|
value</a> of the variable is used directly, and no conversion takes
|
|
place.</p>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="parameters" id="parameters"></a>9.2 <a href=
|
|
"#parameters" style="text-decoration: none">Parameters</a></h3>
|
|
<p class="element-syntax"><a name="element-param" id=
|
|
"element-param"></a><code><!-- Category: declaration
|
|
--><br />
|
|
<xsl:param<br />
|
|
  <b>name</b> = <var>qname</var><br />
|
|
  select? = <var>expression</var><br />
|
|
  as? = <var>sequence-type</var><br />
|
|
  required? = "yes" | "no"<br />
|
|
  tunnel? = "yes" | "no" ><br />
|
|
  <!-- Content: <var>sequence-constructor</var>
|
|
--><br />
|
|
</xsl:param></code></p>
|
|
<p>The <a href="#element-param"><code>xsl:param</code></a> element
|
|
may be used:</p>
|
|
<ul>
|
|
<li>
|
|
<p>as a child of <a href=
|
|
"#element-stylesheet"><code>xsl:stylesheet</code></a>, to define a
|
|
parameter to the transformation</p>
|
|
</li>
|
|
<li>
|
|
<p>as a child of <a href=
|
|
"#element-template"><code>xsl:template</code></a> to define a
|
|
parameter to a template, which may be supplied when the template is
|
|
invoked using <a href=
|
|
"#element-call-template"><code>xsl:call-template</code></a>,
|
|
<a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>,
|
|
<a href="#element-apply-imports"><code>xsl:apply-imports</code></a>
|
|
or <a href=
|
|
"#element-next-match"><code>xsl:next-match</code></a>;</p>
|
|
</li>
|
|
<li>
|
|
<p>as a child of <a href=
|
|
"#element-function"><code>xsl:function</code></a> to define a
|
|
parameter to a stylesheet function, which may be supplied when the
|
|
function is called from an XPath <a title="expression" class=
|
|
"termref" href="#dt-expression">expression</a></p>
|
|
</li>
|
|
<li>
|
|
<p>as a child of <a href=
|
|
"#element-iterate"><code>xsl:iterate</code></a> to define a
|
|
parameter that can vary from one iteration to the next.</p>
|
|
</li>
|
|
</ul>
|
|
<p>The <a href="#element-param"><code>xsl:param</code></a> element
|
|
has a <span class="verb">required</span> <code>name</code>
|
|
attribute, which specifies the name of the parameter. The value of
|
|
the <code>name</code> attribute is a <a title="QName" class=
|
|
"termref" href="#dt-qname">QName</a>, which is expanded as
|
|
described in <a href="#qname"><i>5.1 Qualified Names</i></a>.</p>
|
|
<p><a name="err-XTSE0580" id="err-XTSE0580"><span class=
|
|
"error">[ERR XTSE0580]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> if the
|
|
values of the <code>name</code> attribute of two <span>sibling
|
|
<a href="#element-param"><code>xsl:param</code></a> elements
|
|
represent the same expanded <a title="QName" class="termref" href=
|
|
"#dt-qname">QName</a></span>.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>For rules concerning stylesheet parameters, see <a href=
|
|
"#global-variables"><i>9.5 Global Variables and Parameters</i></a>.
|
|
Local variables may <a title="shadows" class="termref" href=
|
|
"#dt-shadows">shadow</a> template parameters and function
|
|
parameters: see <a href="#scope-of-variables"><i>9.7 Scope of
|
|
Variables</i></a>.</p>
|
|
</div>
|
|
<p>The <a title="supplied value" class="termref" href=
|
|
"#dt-supplied-value">supplied value</a> of the parameter is the
|
|
value supplied by the caller. If no value was supplied by the
|
|
caller, and if the parameter is not mandatory, then the supplied
|
|
value is computed using the <a title="expression" class="termref"
|
|
href="#dt-expression">expression</a> given in the
|
|
<code>select</code> attribute or the contained <a title=
|
|
"sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a>, as described
|
|
in <a href="#variable-values"><i>9.3 Values of Variables and
|
|
Parameters</i></a>. If the <a href=
|
|
"#element-param"><code>xsl:param</code></a> element has a
|
|
<code>select</code> attribute, then the sequence constructor
|
|
<span class="verb">must</span> be empty.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>This specification does not dictate whether and when the default
|
|
value of a parameter is evaluated. For example, if the default is
|
|
specified as <code><xsl:param
|
|
name="p"><foo/></xsl:param></code>, then it is not
|
|
specified whether a distinct <code>foo</code> element node will be
|
|
created on each invocation of the template, or whether the same
|
|
<code>foo</code> element node will be used for each invocation.
|
|
However, it is permissible for the default value to depend on the
|
|
values of other parameters, or on the evaluation context, in which
|
|
case the default must effectively be evaluated on each
|
|
invocation.</p>
|
|
</div>
|
|
<p>The <a href="#element-param"><code>xsl:param</code></a> element
|
|
has an optional <code>as</code> attribute, which specifies the
|
|
<a title="required type" class="termref" href=
|
|
"#dt-required-type">required type</a> of the parameter. The value
|
|
of the <code>as</code> attribute is a <a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-SequenceType">SequenceType</a><sup><small>XP21</small></sup>,
|
|
as defined in <a href="#xpath-21">[XPath 2.1]</a>.</p>
|
|
<p>If the <code>as</code> attribute is specified, then the
|
|
<a title="supplied value" class="termref" href=
|
|
"#dt-supplied-value">supplied value</a> of the parameter is
|
|
converted to the required type, using the <a title=
|
|
"function conversion rules" class="termref" href=
|
|
"#dt-function-conversion-rules">function conversion rules</a>.</p>
|
|
<p><a name="err-XTTE0590" id="err-XTTE0590"><span class=
|
|
"error">[ERR XTTE0590]</span></a> It is a <a title="type errors"
|
|
class="termref" href="#dt-type-error">type error</a> if the
|
|
conversion of the <a title="supplied value" class="termref" href=
|
|
"#dt-supplied-value">supplied value</a> of a parameter to its
|
|
required type fails.</p>
|
|
<p>If the <code>as</code> attribute is omitted, the <a title=
|
|
"supplied value" class="termref" href="#dt-supplied-value">supplied
|
|
value</a> of the parameter is used directly, and no conversion
|
|
takes place.</p>
|
|
<p>The optional <code>required</code> attribute may be used to
|
|
indicate that a parameter is mandatory. This attribute may be
|
|
specified for <a title="stylesheet parameter" class="termref" href=
|
|
"#dt-stylesheet-parameter">stylesheet parameters</a> and for
|
|
<a title="template parameter" class="termref" href=
|
|
"#dt-template-parameter">template parameters</a>; it <span class=
|
|
"verb">must not</span> be specified for <a title=
|
|
"function parameter" class="termref" href=
|
|
"#dt-function-parameter">function parameters</a>, which are always
|
|
mandatory, <span>or for parameters to <a href=
|
|
"#element-iterate"><code>xsl:iterate</code></a>, which are always
|
|
initialized to a default value</span>. A parameter is mandatory if
|
|
it is a <a title="function parameter" class="termref" href=
|
|
"#dt-function-parameter">function parameter</a> or if the
|
|
<code>required</code> attribute is present and has the value
|
|
<code>yes</code>. Otherwise, the parameter is optional. If the
|
|
parameter is mandatory, then the <a href=
|
|
"#element-param"><code>xsl:param</code></a> element <span class=
|
|
"verb">must</span> be empty and <span class="verb">must not</span>
|
|
have a <code>select</code> attribute.</p>
|
|
<p><a name="err-XTTE0600" id="err-XTTE0600"><span class=
|
|
"error">[ERR XTTE0600]</span></a> If a default value is given
|
|
explicitly, that is, if there is either a <code>select</code>
|
|
attribute or a non-empty <a title="sequence constructor" class=
|
|
"termref" href="#dt-sequence-constructor">sequence constructor</a>,
|
|
then it is a <a title="type errors" class="termref" href=
|
|
"#dt-type-error">type error</a> if the default value cannot be
|
|
converted to the required type, using the <a title=
|
|
"function conversion rules" class="termref" href=
|
|
"#dt-function-conversion-rules">function conversion rules</a>.</p>
|
|
<p>If an optional parameter has no <code>select</code> attribute
|
|
and has an empty <a title="sequence constructor" class="termref"
|
|
href="#dt-sequence-constructor">sequence constructor</a>, and if
|
|
there is no <code>as</code> attribute, then the default value of
|
|
the parameter is a zero length string.</p>
|
|
<p><a name="err-XTDE0610" id="err-XTDE0610"><span class=
|
|
"error">[ERR XTDE0610]</span></a> If an optional parameter has no
|
|
<code>select</code> attribute and has an empty <a title=
|
|
"sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a>, and if there
|
|
is an <code>as</code> attribute, then the default value of the
|
|
parameter is an empty sequence. If the empty sequence is not a
|
|
valid instance of the required type defined in the <code>as</code>
|
|
attribute, then the parameter is treated as a required parameter,
|
|
which means that it is a <a title="non-recoverable dynamic error"
|
|
class="termref" href="#dt-nonrec-dynamic-error">non-recoverable
|
|
dynamic error</a> if the caller supplies no value for the
|
|
parameter.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>The effect of these rules is that specifying <code><xsl:param
|
|
name="p" as="xs:date" select="2"/></code> is an error, but if
|
|
the default value of the parameter is never used, then the
|
|
processor has discretion whether or not to report the error. By
|
|
contrast, <code><xsl:param name="p" as="xs:date"/></code> is
|
|
treated as if <code>required="yes"</code> had been specified: the
|
|
empty sequence is not a valid instance of <code>xs:date</code>, so
|
|
in effect there is no default value and the parameter is therefore
|
|
treated as being mandatory.</p>
|
|
</div>
|
|
<p>The optional <code>tunnel</code> attribute may be used to
|
|
indicate that a parameter is a <a title="tunnel parameter" class=
|
|
"termref" href="#dt-tunnel-parameter">tunnel parameter</a>. The
|
|
default is <code>no</code>; the value <code>yes</code> may be
|
|
specified only for <a title="template parameter" class="termref"
|
|
href="#dt-template-parameter">template parameters</a>. Tunnel
|
|
parameters are described in <a href="#tunnel-params"><i>10.1.2
|
|
Tunnel Parameters</i></a></p>
|
|
<blockquote>
|
|
<p><b><a name="fixed-value-attributes" id=
|
|
"fixed-value-attributes">Issue 12 (value-attributes)</a>:</b></p>
|
|
<p>The treatment of <code>tunnel</code> and <code>required</code>
|
|
is inconsistent in the case where the attribute makes no sense. In
|
|
one case we allow the parameter to be present so long as it has its
|
|
"fixed" value, in the other case we require it to be omitted. The
|
|
WG has decided in principle that where only one value makes sense
|
|
for an attribute, it should be legal to specify the attribute and
|
|
give it that value. However, where an attribute makes no sense in a
|
|
particular context, it will still be an error to include it: for
|
|
example the <code>from</code> attribute of <a href=
|
|
"#element-number"><code>xsl:number</code></a> must be omitted if
|
|
the <code>value</code> attribute is present.</p>
|
|
<p>Editor to implement WG decision.</p>
|
|
</blockquote>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="variable-values" id="variable-values"></a>9.3 <a href=
|
|
"#variable-values" style="text-decoration: none">Values of
|
|
Variables and Parameters</a></h3>
|
|
<p>A <a title="variable-binding element" class="termref" href=
|
|
"#dt-variable-binding-element">variable-binding element</a> may
|
|
specify the <a title="supplied value" class="termref" href=
|
|
"#dt-supplied-value">supplied value</a> of a <a title="variable"
|
|
class="termref" href="#dt-variable">variable</a> <span>or the
|
|
default value of a</span> <a title="parameter" class="termref"
|
|
href="#dt-parameter">parameter</a> in four different ways.</p>
|
|
<ul>
|
|
<li>
|
|
<p>If the <a title="variable-binding element" class="termref" href=
|
|
"#dt-variable-binding-element">variable-binding element</a> has a
|
|
<code>select</code> attribute, then the value of the attribute
|
|
<span class="verb">must</span> be an <a title="expression" class=
|
|
"termref" href="#dt-expression">expression</a> and the <a title=
|
|
"supplied value" class="termref" href="#dt-supplied-value">supplied
|
|
value</a> of the variable is the value that results from evaluating
|
|
the expression. In this case, the content of the variable-binding
|
|
element <span class="verb">must</span> be empty.</p>
|
|
</li>
|
|
<li>
|
|
<p>If the <a title="variable-binding element" class="termref" href=
|
|
"#dt-variable-binding-element">variable-binding element</a> has
|
|
empty content and has neither a <code>select</code> attribute nor
|
|
an <code>as</code> attribute, then the <a title="supplied value"
|
|
class="termref" href="#dt-supplied-value">supplied value</a> of the
|
|
variable is a zero-length string. Thus</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:variable name="x"/>
|
|
</pre></div>
|
|
<p>is equivalent to</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:variable name="x" select="''"/>
|
|
</pre></div>
|
|
</li>
|
|
<li>
|
|
<p>If a <a title="variable-binding element" class="termref" href=
|
|
"#dt-variable-binding-element">variable-binding element</a> has no
|
|
<code>select</code> attribute and has non-empty content (that is,
|
|
the variable-binding element has one or more child nodes), and has
|
|
no <code>as</code> attribute, then the content of the
|
|
variable-binding element specifies the <a title="supplied value"
|
|
class="termref" href="#dt-supplied-value">supplied value</a>. The
|
|
content of the variable-binding element is a <a title=
|
|
"sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a>; a new document
|
|
is constructed with a document node having as its children the
|
|
sequence of nodes that results from evaluating the sequence
|
|
constructor and then applying the rules given in <a href=
|
|
"#constructing-complex-content"><i>5.7.1 Constructing Complex
|
|
Content</i></a>. The value of the variable is then a singleton
|
|
sequence containing this document node. For further information,
|
|
see <a href="#temporary-trees"><i>9.4 Creating implicit document
|
|
nodes</i></a>.</p>
|
|
</li>
|
|
<li>
|
|
<p>If a <a title="variable-binding element" class="termref" href=
|
|
"#dt-variable-binding-element">variable-binding element</a> has an
|
|
<code>as</code> attribute but no <code>select</code> attribute,
|
|
then the <a title="supplied value" class="termref" href=
|
|
"#dt-supplied-value">supplied value</a> is the sequence that
|
|
results from evaluating the (possibly empty) <a title=
|
|
"sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> contained
|
|
within the variable-binding element (see <a href=
|
|
"#sequence-constructors"><i>5.7 Sequence Constructors</i></a>).</p>
|
|
</li>
|
|
</ul>
|
|
<p>These combinations are summarized in the table below.</p>
|
|
<table border="1" cellpadding="5">
|
|
<col width="12%" span="1" />
|
|
<col width="12%" span="1" />
|
|
<col width="12%" span="1" />
|
|
<col span="1" />
|
|
<thead>
|
|
<tr>
|
|
<th align="left" colspan="1">select attribute</th>
|
|
<th align="left" colspan="1">as attribute</th>
|
|
<th align="left" colspan="1">content</th>
|
|
<th align="left" colspan="1">Effect</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td valign="top">present</td>
|
|
<td valign="top">absent</td>
|
|
<td valign="top">empty</td>
|
|
<td valign="top">Value is obtained by evaluating the
|
|
<code>select</code> attribute</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">present</td>
|
|
<td valign="top">present</td>
|
|
<td valign="top">empty</td>
|
|
<td valign="top">Value is obtained by evaluating the
|
|
<code>select</code> attribute, adjusted to the type required by the
|
|
<code>as</code> attribute</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">present</td>
|
|
<td valign="top">absent</td>
|
|
<td valign="top">present</td>
|
|
<td valign="top">Static error</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">present</td>
|
|
<td valign="top">present</td>
|
|
<td valign="top">present</td>
|
|
<td valign="top">Static error</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">absent</td>
|
|
<td valign="top">absent</td>
|
|
<td valign="top">empty</td>
|
|
<td valign="top">Value is a zero-length string</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">absent</td>
|
|
<td valign="top">present</td>
|
|
<td valign="top">empty</td>
|
|
<td valign="top">Value is an empty sequence, provided the
|
|
<code>as</code> attribute permits an empty sequence</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">absent</td>
|
|
<td valign="top">absent</td>
|
|
<td valign="top">present</td>
|
|
<td valign="top">Value is a document node whose content is obtained
|
|
by evaluating the sequence constructor</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">absent</td>
|
|
<td valign="top">present</td>
|
|
<td valign="top">present</td>
|
|
<td valign="top">Value is obtained by evaluating the sequence
|
|
constructor, adjusted to the type required by the <code>as</code>
|
|
attribute</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p><a name="err-XTSE0620" id="err-XTSE0620"><span class=
|
|
"error">[ERR XTSE0620]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> if a
|
|
<a title="variable-binding element" class="termref" href=
|
|
"#dt-variable-binding-element">variable-binding element</a> has a
|
|
<code>select</code> attribute and has non-empty content.</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e16701" id=
|
|
"d7e16701"></a>Example: Values of Variables</div>
|
|
<p>The value of the following variable is the sequence of integers
|
|
(1, 2, 3):</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:variable name="i" as="xs:integer*" select="1 to 3"/>
|
|
</pre></div>
|
|
<p>The value of the following variable is an integer, assuming that
|
|
the attribute <code>@size</code> exists, and is annotated either as
|
|
an integer, or as <code>xs:untypedAtomic</code>:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:variable name="i" as="xs:integer" select="@size"/>
|
|
</pre></div>
|
|
<p>The value of the following variable is a zero-length string:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:variable name="z"/>
|
|
</pre></div>
|
|
<p>The value of the following variable is a document node
|
|
containing an empty element as a child:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:variable name="doc"><c/></xsl:variable>
|
|
</pre></div>
|
|
<p>The value of the following variable is a sequence of integers
|
|
(2, 4, 6):</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:variable name="seq" as="xs:integer*">
|
|
<xsl:for-each select="1 to 3">
|
|
<xsl:sequence select=".*2"/>
|
|
</xsl:for-each>
|
|
</xsl:variable>
|
|
</pre></div>
|
|
<p>The value of the following variable is a sequence of parentless
|
|
attribute nodes:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:variable name="attset" as="attribute()+">
|
|
<xsl:attribute name="x">2</xsl:attribute>
|
|
<xsl:attribute name="y">3</xsl:attribute>
|
|
<xsl:attribute name="z">4</xsl:attribute>
|
|
</xsl:variable>
|
|
</pre></div>
|
|
<p>The value of the following variable is an empty sequence:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:variable name="empty" as="empty-sequence()"/>
|
|
</pre></div>
|
|
</div>
|
|
<p>The actual value of the variable depends on the <a title=
|
|
"supplied value" class="termref" href="#dt-supplied-value">supplied
|
|
value</a>, as described above, and the required type, which is
|
|
determined by the value of the <code>as</code> attribute.</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e16747" id=
|
|
"d7e16747"></a>Example: Pitfalls with Numeric Predicates</div>
|
|
<p>When a variable is used to select nodes by position, be careful
|
|
not to do:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:variable name="n">2</xsl:variable>
|
|
...
|
|
<xsl:value-of select="td[$n]"/>
|
|
</pre></div>
|
|
<p>This will output the values of all the <code>td</code> elements,
|
|
space-separated (or <span>with <a title="XSLT 1.0 behavior" class=
|
|
"termref" href="#dt-xslt-10-behavior">XSLT 1.0 behavior</a></span>,
|
|
the value of the first <code>td</code> element), because the
|
|
variable <code>n</code> will be bound to a node, not a number.
|
|
Instead, do one of the following:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:variable name="n" select="2"/>
|
|
...
|
|
<xsl:value-of select="td[$n]"/>
|
|
</pre></div>
|
|
<p>or</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:variable name="n">2</xsl:variable>
|
|
...
|
|
<xsl:value-of select="td[position()=$n]"/>
|
|
</pre></div>
|
|
<p>or</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:variable name="n" as="xs:integer">2</xsl:variable>
|
|
...
|
|
<xsl:value-of select="td[$n]"/>
|
|
</pre></div>
|
|
</div>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="temporary-trees" id="temporary-trees"></a>9.4 <a href=
|
|
"#temporary-trees" style="text-decoration: none">Creating implicit
|
|
document nodes</a></h3>
|
|
<p>A document node is created implicitly when evaluating an
|
|
<a href="#element-variable"><code>xsl:variable</code></a>, <a href=
|
|
"#element-param"><code>xsl:param</code></a>, or <a href=
|
|
"#element-with-param"><code>xsl:with-param</code></a> element that
|
|
has non-empty content and that has no <code>as</code> attribute.
|
|
The value of the <a title="variable" class="termref" href=
|
|
"#dt-variable">variable</a> is a single node, the document node of
|
|
a <a title="temporary tree" class="termref" href=
|
|
"#dt-temporary-tree">temporary tree</a>. The content of the
|
|
document node is formed from the result of evaluating the <a title=
|
|
"sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> contained
|
|
within the variable-binding element, as described in <a href=
|
|
"#constructing-complex-content"><i>5.7.1 Constructing Complex
|
|
Content</i></a>.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>The construct:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:variable name="tree">
|
|
<a/>
|
|
</xsl:variable>
|
|
</pre></div>
|
|
<p>can be regarded as a shorthand for:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:variable name="tree" as="document-node()">
|
|
<xsl:document validation="preserve">
|
|
<a/>
|
|
</xsl:document>
|
|
</xsl:variable>
|
|
</pre></div>
|
|
</div>
|
|
<p>The base URI of the document node is taken from the base URI of
|
|
the variable binding element in the stylesheet. (See <a href=
|
|
"http://www.w3.org/TR/xpath-datamodel-11/#dm-base-uri">Section 5.2
|
|
base-uri Accessor</a><sup><small>DM11</small></sup> in <a href=
|
|
"#xpath-datamodel-11">[Data Model]</a>)</p>
|
|
<p>No document-level validation takes place (which means, for
|
|
example, that there is no checking that ID values are unique).
|
|
However, type annotations on nodes within the new tree are copied
|
|
unchanged.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>The base URI of other nodes in the tree is determined by the
|
|
rules for constructing complex content. The effect of these rules
|
|
is that the base URI of a node in the temporary tree is determined
|
|
as if all the nodes in the temporary tree came from a single entity
|
|
whose URI was the base URI of the <a title=
|
|
"variable-binding element" class="termref" href=
|
|
"#dt-variable-binding-element">variable-binding element</a>. Thus,
|
|
the base URI of the document node will be equal to the base URI of
|
|
the variable-binding element, while an <code>xml:base</code>
|
|
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.</p>
|
|
</div>
|
|
<p>The <code>document-uri</code> and <code>unparsed-entities</code>
|
|
properties of the new document node are set to empty.</p>
|
|
<p>A <a title="temporary tree" class="termref" href=
|
|
"#dt-temporary-tree">temporary tree</a> 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 <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a> and
|
|
<a href="#element-for-each"><code>xsl:for-each</code></a>. Also,
|
|
the <a href="#function-key"><code>key</code></a> and <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-id"><code>id</code></a><sup><small>FO</small></sup>
|
|
functions can be used to find nodes within a temporary tree,
|
|
<span>by supplying the document node at the root of the tree as an
|
|
argument to the function or by making it the context
|
|
node</span>.</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e16864" id=
|
|
"d7e16864"></a>Example: Two-Phase Transformation</div>
|
|
<p>For example, the following stylesheet uses a temporary tree as
|
|
the intermediate result of a two-phase transformation, using
|
|
different <a title="mode" class="termref" href="#dt-mode">modes</a>
|
|
for the two phases (see <a href="#modes"><i>6.6 Modes</i></a>).
|
|
Typically, the template rules in module <code>phase1.xsl</code>
|
|
will be declared with <code>mode="phase1"</code>, while those in
|
|
module <code>phase2.xsl</code> will be declared with
|
|
<code>mode="phase2"</code>:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:stylesheet
|
|
version="2.1"
|
|
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>
|
|
</pre></div>
|
|
</div>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>The algorithm for matching nodes against template rules is
|
|
exactly the same regardless which tree the nodes come from. If
|
|
different template rules are to be used when processing different
|
|
trees, then unless nodes from different trees can be distinguished
|
|
by means of <a title="pattern" class="termref" href=
|
|
"#dt-pattern">patterns</a>, it is a good idea to use <a title=
|
|
"mode" class="termref" href="#dt-mode">modes</a> to ensure that
|
|
each tree is processed using the appropriate set of template
|
|
rules.</p>
|
|
</div>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="global-variables" id="global-variables"></a>9.5
|
|
<a href="#global-variables" style="text-decoration: none">Global
|
|
Variables and Parameters</a></h3>
|
|
<p>Both <a href="#element-variable"><code>xsl:variable</code></a>
|
|
and <a href="#element-param"><code>xsl:param</code></a> are allowed
|
|
as <a title="declaration" class="termref" href=
|
|
"#dt-declaration">declaration</a> elements: that is, they may
|
|
appear as children of the <a href=
|
|
"#element-stylesheet"><code>xsl:stylesheet</code></a> element.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-global-variable" id="dt-global-variable" title=
|
|
"global variable"></a>A top-level <a title=
|
|
"variable-binding element" class="termref" href=
|
|
"#dt-variable-binding-element">variable-binding element</a>
|
|
declares a <b>global variable</b> that is visible everywhere
|
|
(except where it is <a title="shadows" class="termref" href=
|
|
"#dt-shadows">shadowed</a> by another binding).<span class=
|
|
"definition">]</span></p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-stylesheet-parameter" id="dt-stylesheet-parameter" title=
|
|
"stylesheet parameter"></a>A top-level <a href=
|
|
"#element-param"><code>xsl:param</code></a> element declares a
|
|
<b>stylesheet parameter</b>. A stylesheet parameter is a global
|
|
variable with the additional property that its value can be
|
|
supplied by the caller when a transformation is
|
|
initiated.<span class="definition">]</span> As described in
|
|
<a href="#parameters"><i>9.2 Parameters</i></a>, a stylesheet
|
|
parameter may be declared as being mandatory, or may have a default
|
|
value specified for use when no value is supplied by the caller.
|
|
The mechanism by which the caller supplies a value for a stylesheet
|
|
parameter is <a title="implementation-defined" class="termref"
|
|
href="#dt-implementation-defined">implementation-defined</a>. An
|
|
XSLT <a title="processor" class="termref" href=
|
|
"#dt-processor">processor</a> <span class="verb">must</span>
|
|
provide such a mechanism.</p>
|
|
<p>It is an error if no value is supplied for a mandatory
|
|
stylesheet parameter <span class="error">[see <a href=
|
|
"#err-XTDE0050">ERR XTDE0050</a>]</span>.</p>
|
|
<p>If a <a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a> contains more than one binding for
|
|
a global variable of a particular name, then the binding with the
|
|
highest <a title="import precedence" class="termref" href=
|
|
"#dt-import-precedence">import precedence</a> is used.</p>
|
|
<p><a name="err-XTSE0630" id="err-XTSE0630"><span class=
|
|
"error">[ERR XTSE0630]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> if a
|
|
<a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a> contains more than one binding of a
|
|
global variable with the same name and same <a title=
|
|
"import precedence" class="termref" href=
|
|
"#dt-import-precedence">import precedence</a>, unless it also
|
|
contains another binding with the same name and higher import
|
|
precedence.</p>
|
|
<p>For a global variable or the default value of a stylesheet
|
|
parameter, the <a title="expression" class="termref" href=
|
|
"#dt-expression">expression</a> or <a title="sequence constructor"
|
|
class="termref" href="#dt-sequence-constructor">sequence
|
|
constructor</a> specifying the variable value is evaluated with a
|
|
<a title="singleton focus" class="termref" href=
|
|
"#dt-singleton-focus">singleton focus</a> based on the root node of
|
|
the tree containing the <span><a title="initial context item"
|
|
class="termref" href="#dt-initial-context-item">initial context
|
|
item</a></span>. An XPath error will be reported if the evaluation
|
|
of a global variable or parameter references the context item,
|
|
context position, or context size when no initial context item is
|
|
supplied. The values of other components of the dynamic context are
|
|
the initial values as defined in <a href=
|
|
"#xpath-dynamic-context"><i>5.4.3 Initializing the Dynamic
|
|
Context</i></a> and <a href="#additional-dynamic-context"><i>5.4.4
|
|
Additional Dynamic Context Components used by XSLT</i></a>.</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e17004" id=
|
|
"d7e17004"></a>Example: A Stylesheet Parameter</div>
|
|
<p>The following example declares a global parameter
|
|
<code>para-font-size</code>, which is referenced in an <a title=
|
|
"attribute value template" class="termref" href=
|
|
"#dt-attribute-value-template">attribute value template</a>.</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:param name="para-font-size" as="xs:string">12pt</xsl:param>
|
|
|
|
<xsl:template match="para">
|
|
<fo:block font-size="{$para-font-size}">
|
|
<xsl:apply-templates/>
|
|
</fo:block>
|
|
</xsl:template>
|
|
</pre></div>
|
|
<p>The implementation must provide a mechanism allowing the user to
|
|
supply a value for the parameter <code>para-font-size</code> when
|
|
invoking the stylesheet; the value <code>12pt</code> acts as a
|
|
default.</p>
|
|
</div>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="local-variables" id="local-variables"></a>9.6 <a href=
|
|
"#local-variables" style="text-decoration: none">Local Variables
|
|
and Parameters</a></h3>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-local-variable" id="dt-local-variable" title=
|
|
"local variable"></a>As well as being allowed as a <a title=
|
|
"declaration" class="termref" href=
|
|
"#dt-declaration">declaration</a>, the <a href=
|
|
"#element-variable"><code>xsl:variable</code></a> element is also
|
|
allowed in <a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructors</a>. Such a
|
|
variable is known as a <b>local variable</b>.<span class=
|
|
"definition">]</span></p>
|
|
<p>An <a href="#element-param"><code>xsl:param</code></a> element
|
|
may also be used to create a variable binding with local scope:</p>
|
|
<ul>
|
|
<li>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-template-parameter" id="dt-template-parameter" title=
|
|
"template parameter"></a> An <a href=
|
|
"#element-param"><code>xsl:param</code></a> element may appear as a
|
|
child of an <a href=
|
|
"#element-template"><code>xsl:template</code></a> element, before
|
|
any non-<a href="#element-param"><code>xsl:param</code></a>
|
|
children of that element. Such a parameter is known as a
|
|
<b>template parameter</b>. A template parameter is a <a title=
|
|
"local variable" class="termref" href="#dt-local-variable">local
|
|
variable</a> with the additional property that its value can be set
|
|
when the template is called, using any of the instructions <a href=
|
|
"#element-call-template"><code>xsl:call-template</code></a>,
|
|
<a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>,
|
|
<a href=
|
|
"#element-apply-imports"><code>xsl:apply-imports</code></a>, or
|
|
<a href=
|
|
"#element-next-match"><code>xsl:next-match</code></a>.<span class=
|
|
"definition">]</span></p>
|
|
</li>
|
|
<li>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-function-parameter" id="dt-function-parameter" title=
|
|
"function parameter"></a> An <a href=
|
|
"#element-param"><code>xsl:param</code></a> element may appear as a
|
|
child of an <a href=
|
|
"#element-function"><code>xsl:function</code></a> element, before
|
|
any non-<a href="#element-param"><code>xsl:param</code></a>
|
|
children of that element. Such a parameter is known as a
|
|
<b>function parameter</b>. A function parameter is a <a title=
|
|
"local variable" class="termref" href="#dt-local-variable">local
|
|
variable</a> with the additional property that its value can be set
|
|
when the function is called, using a function call in an XPath
|
|
<a title="expression" class="termref" href=
|
|
"#dt-expression">expression</a>.<span class=
|
|
"definition">]</span></p>
|
|
</li>
|
|
<li>
|
|
<p>An <a href="#element-param"><code>xsl:param</code></a> element
|
|
may appear as a child of an <a href=
|
|
"#element-iterate"><code>xsl:iterate</code></a> instruction, before
|
|
any non-<a href="#element-param"><code>xsl:param</code></a>
|
|
children of that element. This defines a parameter whose value may
|
|
be initialized on entry to the iteration, and which may be varied
|
|
each time round the iteration by use of an <a href=
|
|
"#element-with-param"><code>xsl:with-param</code></a> element in
|
|
the <a href=
|
|
"#element-next-iteration"><code>xsl:next-iteration</code></a>
|
|
instruction.</p>
|
|
</li>
|
|
</ul>
|
|
<p>The result of evaluating a local <a href=
|
|
"#element-variable"><code>xsl:variable</code></a> or <a href=
|
|
"#element-param"><code>xsl:param</code></a> element (that is, the
|
|
contribution it makes to the result of the <a title=
|
|
"sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> it is part of)
|
|
is an empty sequence.</p>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="scope-of-variables" id="scope-of-variables"></a>9.7
|
|
<a href="#scope-of-variables" style="text-decoration: none">Scope
|
|
of Variables</a></h3>
|
|
<p>For any <a title="variable-binding element" class="termref"
|
|
href="#dt-variable-binding-element">variable-binding element</a>,
|
|
there is a region (more specifically, a set of element nodes) of
|
|
the <a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a> within which the binding is
|
|
visible. The set of variable bindings in scope for an XPath
|
|
<a title="expression" class="termref" href=
|
|
"#dt-expression">expression</a> consists of those bindings that are
|
|
visible at the point in the stylesheet where the expression
|
|
occurs.</p>
|
|
<p>A global <a title="variable-binding element" class="termref"
|
|
href="#dt-variable-binding-element">variable binding element</a> is
|
|
visible everywhere in the <a title="stylesheet" class="termref"
|
|
href="#dt-stylesheet">stylesheet</a> (including other <a title=
|
|
"stylesheet module" class="termref" href=
|
|
"#dt-stylesheet-module">stylesheet modules</a>) except within the
|
|
<a href="#element-variable"><code>xsl:variable</code></a> or
|
|
<a href="#element-param"><code>xsl:param</code></a> element itself
|
|
and any region where it is <a title="shadows" class="termref" href=
|
|
"#dt-shadows">shadowed</a> by another variable binding.</p>
|
|
<p>A local <a title="variable-binding element" class="termref"
|
|
href="#dt-variable-binding-element">variable binding element</a> is
|
|
visible for all following siblings and their descendants, with
|
|
<span>the following</span> exceptions:</p>
|
|
<ol class="enumar">
|
|
<li>
|
|
<p>It is not visible in any region where it is <a title="shadows"
|
|
class="termref" href="#dt-shadows">shadowed</a> by another variable
|
|
binding.</p>
|
|
</li>
|
|
<li>
|
|
<p>It is not visible within the subtree rooted at an <a href=
|
|
"#element-fallback"><code>xsl:fallback</code></a> instruction that
|
|
is a sibling of the variable binding element.</p>
|
|
</li>
|
|
<li>
|
|
<p>It is not visible within the subtree rooted at an <a href=
|
|
"#element-catch"><code>xsl:catch</code></a> instruction that is a
|
|
sibling of the variable binding element.</p>
|
|
</li>
|
|
</ol>
|
|
<p>The binding is not visible for the <a href=
|
|
"#element-variable"><code>xsl:variable</code></a> or <a href=
|
|
"#element-param"><code>xsl:param</code></a> element itself.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-shadows" id="dt-shadows" title="shadows"></a>A binding
|
|
<b>shadows</b> another binding if the binding occurs at a point
|
|
where the other binding is visible, and the bindings have the same
|
|
name. <span class="definition">]</span> It is not an error if a
|
|
binding established by a local <a href=
|
|
"#element-variable"><code>xsl:variable</code></a> or <a href=
|
|
"#element-param"><code>xsl:param</code></a> <a title="shadows"
|
|
class="termref" href="#dt-shadows">shadows</a> a global binding. In
|
|
this case, the global binding will not be visible in the region of
|
|
the <a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a> where it is shadowed by the other
|
|
binding.</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e17230" id=
|
|
"d7e17230"></a>Example: Local Variable Shadowing a Global
|
|
Variable</div>
|
|
<p>The following is allowed:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:param name="x" select="1"/>
|
|
<xsl:template name="foo">
|
|
<xsl:variable name="x" select="2"/>
|
|
</xsl:template>
|
|
</pre></div>
|
|
</div>
|
|
<p>It is also not an error if a binding established by a local
|
|
<a href="#element-variable"><code>xsl:variable</code></a> element
|
|
<a title="shadows" class="termref" href="#dt-shadows">shadows</a> a
|
|
binding established by another local <a href=
|
|
"#element-variable"><code>xsl:variable</code></a> or <a href=
|
|
"#element-param"><code>xsl:param</code></a>.</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e17251" id=
|
|
"d7e17251"></a>Example: Misuse of Variable Shadowing</div>
|
|
<p>The following is not an error, but the effect is probably not
|
|
what was intended. The template outputs <code><x
|
|
value="1"/></code>, because the declaration of the inner
|
|
variable named <code>$x</code> has no effect on the value of the
|
|
outer variable named <code>$x</code>.</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:variable name="x" select="1"/>
|
|
<xsl:template name="foo">
|
|
<xsl:for-each select="1 to 5">
|
|
<xsl:variable name="x" select="$x+1"/>
|
|
</xsl:for-each>
|
|
<x value="{$x}"/>
|
|
</xsl:template>
|
|
</pre></div>
|
|
</div>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>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.</p>
|
|
<p>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.</p>
|
|
</div>
|
|
<p>As well as global variables and local variables, an XPath
|
|
<a title="expression" class="termref" href=
|
|
"#dt-expression">expression</a> may also declare range variables
|
|
for use locally within an expression. For details, see <a href=
|
|
"#xpath-21">[XPath 2.1]</a>.</p>
|
|
<p>Where a reference to a variable occurs in an XPath expression,
|
|
it is resolved first by reference to range variables that are in
|
|
scope, then by reference to local variables and parameters, and
|
|
finally by reference to global variables and parameters. A range
|
|
variable may shadow a local variable or a global variable. XPath
|
|
also allows a range variable to shadow another range variable.</p>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="with-param" id="with-param"></a>9.8 <a href=
|
|
"#with-param" style="text-decoration: none">Setting Parameter
|
|
Values</a></h3>
|
|
<p class="element-syntax"><a name="element-with-param" id=
|
|
"element-with-param"></a><code><xsl:with-param<br />
|
|
  <b>name</b> = <var>qname</var><br />
|
|
  select? = <var>expression</var><br />
|
|
  as? = <var>sequence-type</var><br />
|
|
  tunnel? = "yes" | "no" ><br />
|
|
  <!-- Content: <var>sequence-constructor</var>
|
|
--><br />
|
|
</xsl:with-param></code></p>
|
|
<p>Parameters are passed to templates using the <a href=
|
|
"#element-with-param"><code>xsl:with-param</code></a> element. The
|
|
<span class="verb">required</span> <code>name</code> attribute
|
|
specifies the name of the <a title="template parameter" class=
|
|
"termref" href="#dt-template-parameter">template parameter</a> (the
|
|
variable the value of whose binding is to be replaced). The value
|
|
of the <code>name</code> attribute is a <a title="QName" class=
|
|
"termref" href="#dt-qname">QName</a>, which is expanded as
|
|
described in <a href="#qname"><i>5.1 Qualified Names</i></a>.</p>
|
|
<p><span>The <a href=
|
|
"#element-with-param"><code>xsl:with-param</code></a> element is
|
|
also used when passing parameters to an iteration of the <a href=
|
|
"#element-iterate"><code>xsl:iterate</code></a> instruction, or to
|
|
a dynamic invocation of an XPath expression using <a href=
|
|
"#element-evaluate"><code>xsl:evaluate</code></a>. In
|
|
consequence,</span> <a href=
|
|
"#element-with-param"><code>xsl:with-param</code></a> may appear
|
|
within <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>,
|
|
<a href=
|
|
"#element-apply-imports"><code>xsl:apply-imports</code></a>,
|
|
<a href=
|
|
"#element-call-template"><code>xsl:call-template</code></a>,
|
|
<span><a href="#element-evaluate"><code>xsl:evaluate</code></a>,
|
|
<a href=
|
|
"#element-next-iteration"><code>xsl:next-iteration</code></a>,</span>
|
|
and <a href="#element-next-match"><code>xsl:next-match</code></a>.
|
|
(Arguments to <a title="stylesheet function" class="termref" href=
|
|
"#dt-stylesheet-function">stylesheet functions</a>, however, are
|
|
supplied as part of an XPath function call: see <a href=
|
|
"#stylesheet-functions"><i>10.3 Stylesheet Functions</i></a>.)</p>
|
|
<p><a name="err-XTSE0670" id="err-XTSE0670"><span class=
|
|
"error">[ERR XTSE0670]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> if two or
|
|
more sibling <a href=
|
|
"#element-with-param"><code>xsl:with-param</code></a> elements have
|
|
<code>name</code> attributes that represent the same <a title=
|
|
"expanded-QName" class="termref" href="#dt-expanded-qname">expanded
|
|
QName</a>.</p>
|
|
<p>The value of the parameter is specified in the same way as for
|
|
<a href="#element-variable"><code>xsl:variable</code></a> and
|
|
<a href="#element-param"><code>xsl:param</code></a> (see <a href=
|
|
"#variable-values"><i>9.3 Values of Variables and
|
|
Parameters</i></a>), taking account of the values of the
|
|
<code>select</code> and <code>as</code> attributes and the content
|
|
of the <a href=
|
|
"#element-with-param"><code>xsl:with-param</code></a> element, if
|
|
any.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>It is possible to have an <code>as</code> attribute on the
|
|
<a href="#element-with-param"><code>xsl:with-param</code></a>
|
|
element that differs from the <code>as</code> attribute on the
|
|
corresponding <a href="#element-param"><code>xsl:param</code></a>
|
|
element.</p>
|
|
<p>In this situation, the supplied value of the parameter will
|
|
first be processed according to the rules of the <code>as</code>
|
|
attribute on the <a href=
|
|
"#element-with-param"><code>xsl:with-param</code></a> element, and
|
|
the resulting value will then be further processed according to the
|
|
rules of the <code>as</code> attribute on the <a href=
|
|
"#element-param"><code>xsl:param</code></a> element.</p>
|
|
<p>For example, suppose the supplied value is a node with <a title=
|
|
"type annotation" class="termref" href="#dt-annotation">type
|
|
annotation</a> <code>xs:untypedAtomic</code>, and the <a href=
|
|
"#element-with-param"><code>xsl:with-param</code></a> element
|
|
specifies <code>as="xs:integer"</code>, while the <a href=
|
|
"#element-param"><code>xsl:param</code></a> element specifies
|
|
<code>as="xs:double"</code>. Then the node will first be atomized
|
|
and the resulting untyped atomic value will be cast to
|
|
<code>xs:integer</code>. If this succeeds, the
|
|
<code>xs:integer</code> will then be promoted to an
|
|
<code>xs:double</code>.</p>
|
|
</div>
|
|
<p>The <a title="focus" class="termref" href="#dt-focus">focus</a>
|
|
used for computing the value specified by the <a href=
|
|
"#element-with-param"><code>xsl:with-param</code></a> element is
|
|
the same as that used for <span>its parent <a title="instruction"
|
|
class="termref" href="#dt-instruction">instruction</a></span>.</p>
|
|
<p>The optional <code>tunnel</code> attribute may be used to
|
|
indicate that a parameter is a <a title="tunnel parameter" class=
|
|
"termref" href="#dt-tunnel-parameter">tunnel parameter</a>. The
|
|
default is <code>no</code>. Tunnel parameters are described in
|
|
<a href="#tunnel-params"><i>10.1.2 Tunnel Parameters</i></a>. They
|
|
are used only when passing parameters to templates: for an <a href=
|
|
"#element-with-param"><code>xsl:with-param</code></a> element that
|
|
is a child of <a href=
|
|
"#element-evaluate"><code>xsl:evaluate</code></a> or <a href=
|
|
"#element-next-iteration"><code>xsl:next-iteration</code></a> the
|
|
<code>tunnel</code> attribute <span class="verb">must</span> either
|
|
be omitted or take the value <code>no</code>.</p>
|
|
<p>In other cases it is a <a title="non-recoverable dynamic error"
|
|
class="termref" href="#dt-nonrec-dynamic-error">non-recoverable
|
|
dynamic error</a> if the template that is invoked declares a
|
|
<a title="template parameter" class="termref" href=
|
|
"#dt-template-parameter">template parameter</a> with
|
|
<code>required="yes"</code> and no value for this parameter is
|
|
supplied by the calling instruction. <span class="error">[see
|
|
<a href="#err-XTDE0700">ERR XTDE0700</a>]</span></p>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="circularity" id="circularity"></a>9.9 <a href=
|
|
"#circularity" style="text-decoration: none">Circular
|
|
Definitions</a></h3>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-circularity" id="dt-circularity" title="circularity"></a>A
|
|
<b>circularity</b> is said to exist if a construct such as a
|
|
<a title="global variable" class="termref" href=
|
|
"#dt-global-variable">global variable</a>, an <a title=
|
|
"attribute set" class="termref" href="#dt-attribute-set">attribute
|
|
set</a>, or a <a title="key" class="termref" href=
|
|
"#dt-key">key</a>, is defined in terms of itself. For example, if
|
|
the <a title="expression" class="termref" href=
|
|
"#dt-expression">expression</a> or <a title="sequence constructor"
|
|
class="termref" href="#dt-sequence-constructor">sequence
|
|
constructor</a> specifying the value of a <a title=
|
|
"global variable" class="termref" href="#dt-global-variable">global
|
|
variable</a> <var>X</var> references a global variable
|
|
<var>Y</var>, then the value for <var>Y</var> <span class=
|
|
"verb">must</span> be computed before the value of <var>X</var>. A
|
|
circularity exists if it is impossible to do this for all global
|
|
variable definitions.<span class="definition">]</span></p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e17570" id=
|
|
"d7e17570"></a>Example: Circular Variable Definitions</div>
|
|
<p>The following two declarations create a circularity:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:variable name="x" select="$y+1"/>
|
|
<xsl:variable name="y" select="$x+1"/>
|
|
</pre></div>
|
|
</div>
|
|
<p> </p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e17577" id=
|
|
"d7e17577"></a>Example: Circularity involving Variables and
|
|
Functions</div>
|
|
<p>The definition of a global variable can be circular even if no
|
|
other variable is involved. For example the following two
|
|
declarations (see <a href="#stylesheet-functions"><i>10.3
|
|
Stylesheet Functions</i></a> for an explanation of the <a href=
|
|
"#element-function"><code>xsl:function</code></a> element) also
|
|
create a circularity:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:variable name="x" select="my:f()"/>
|
|
|
|
<xsl:function name="my:f">
|
|
<xsl:sequence select="$x"/>
|
|
</xsl:function>
|
|
</pre></div>
|
|
</div>
|
|
<p> </p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e17589" id=
|
|
"d7e17589"></a>Example: Circularity involving Variables and
|
|
Templates</div>
|
|
<p>The definition of a variable is also circular if the evaluation
|
|
of the variable invokes an <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>
|
|
instruction and the variable is referenced in the pattern used in
|
|
the <code>match</code> attribute of any template rule in the
|
|
<a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a>. For example the following
|
|
definition is circular:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:variable name="x">
|
|
<xsl:apply-templates select="//param[1]"/>
|
|
</xsl:variable>
|
|
|
|
<xsl:template match="param[$x]">1</xsl:template>
|
|
</pre></div>
|
|
</div>
|
|
<p> </p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e17605" id=
|
|
"d7e17605"></a>Example: Circularity involving Variables and
|
|
Keys</div>
|
|
<p>Similarly, a variable definition is circular if it causes a call
|
|
on the <a href="#function-key"><code>key</code></a> function, and
|
|
the definition of that <a title="" class="termref" href=
|
|
"#key">key</a> refers to that variable in its <code>match</code> or
|
|
<code>use</code> attributes. So the following definition is
|
|
circular:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:variable name="x" select="my:f(10)"/>
|
|
|
|
<xsl:function name="my:f">
|
|
<xsl:param name="arg1"/>
|
|
<xsl:sequence select="key('k', $arg1)"/>
|
|
</xsl:function>
|
|
|
|
<xsl:key name="k" match="item[@code=$x]" use="@desc"/>
|
|
</pre></div>
|
|
</div>
|
|
<p><a name="err-XTDE0640" id="err-XTDE0640"><span class=
|
|
"error">[ERR XTDE0640]</span></a> In general, a <a title=
|
|
"circularity" class="termref" href=
|
|
"#dt-circularity">circularity</a> in a <a title="stylesheet" class=
|
|
"termref" href="#dt-stylesheet">stylesheet</a> is a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a>.
|
|
However, as with all other dynamic errors, an implementation will
|
|
signal the error only if it actually executes the instructions and
|
|
expressions that participate in the circularity. Because different
|
|
implementations may optimize the execution of a stylesheet in
|
|
different ways, it is <a title="implementation-dependent" class=
|
|
"termref" href=
|
|
"#dt-implementation-dependent">implementation-dependent</a> whether
|
|
a particular circularity will actually be signaled.</p>
|
|
<p>For example, in the following declarations, the function
|
|
declares a local variable <code>$b</code>, but it returns a result
|
|
that does not require the variable to be evaluated. It is <a title=
|
|
"implementation-dependent" class="termref" href=
|
|
"#dt-implementation-dependent">implementation-dependent</a> whether
|
|
the value is actually evaluated, and it is therefore
|
|
implementation-dependent whether the circularity is signaled as an
|
|
error:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:variable name="x" select="my:f(1)/>
|
|
|
|
<xsl:function name="my:f">
|
|
<xsl:param name="a"/>
|
|
<xsl:variable name="b" select="$x"/>
|
|
<xsl:sequence select="$a + 2"/>
|
|
</xsl:function>
|
|
</pre></div>
|
|
<p>Circularities usually involve global variables or parameters,
|
|
but they can also exist between <a title="" class="termref" href=
|
|
"#key">key</a> definitions (see <a href="#key"><i>19.3
|
|
Keys</i></a>), between named <a title="attribute set" class=
|
|
"termref" href="#dt-attribute-set">attribute sets</a> (see <a href=
|
|
"#attribute-sets"><i>10.2 Named Attribute Sets</i></a>), or between
|
|
any combination of these constructs. For example, a circularity
|
|
exists if a key definition invokes a function that references an
|
|
attribute set that calls the <a href=
|
|
"#function-key"><code>key</code></a> function, supplying the name
|
|
of the original key definition as an argument.</p>
|
|
<p>Circularity is not the same as recursion. Stylesheet functions
|
|
(see <a href="#stylesheet-functions"><i>10.3 Stylesheet
|
|
Functions</i></a>) and named templates (see <a href=
|
|
"#named-templates"><i>10.1 Named Templates</i></a>) may call other
|
|
functions and named templates without restriction. With careless
|
|
coding, recursion may be non-terminating. Implementations are
|
|
<span class="verb">required</span> to signal circularity as a
|
|
<a title="dynamic error" class="termref" href=
|
|
"#dt-dynamic-error">dynamic error</a>, but they are not
|
|
<span class="verb">required</span> to detect non-terminating
|
|
recursion.</p>
|
|
</div>
|
|
</div>
|
|
<div class="div1">
|
|
<h2><a name="callable-components" id="callable-components"></a>10
|
|
<a href="#callable-components" style=
|
|
"text-decoration: none">Callable Components</a></h2>
|
|
<p>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 <a href=
|
|
"#named-templates"><i>10.1 Named Templates</i></a>), named
|
|
attribute sets (see <a href="#attribute-sets"><i>10.2 Named
|
|
Attribute Sets</i></a>), and <a title="stylesheet function" class=
|
|
"termref" href="#dt-stylesheet-function">stylesheet functions</a>
|
|
(see <a href="#stylesheet-functions"><i>10.3 Stylesheet
|
|
Functions</i></a>).</p>
|
|
<div class="div2">
|
|
<h3><a name="named-templates" id="named-templates"></a>10.1
|
|
<a href="#named-templates" style="text-decoration: none">Named
|
|
Templates</a></h3>
|
|
<p class="element-syntax"><a name="element-call-template" id=
|
|
"element-call-template"></a><code><!-- Category: instruction
|
|
--><br />
|
|
<xsl:call-template<br />
|
|
  <b>name</b> = <var>qname</var> ><br />
|
|
  <!-- Content: <a href=
|
|
"#element-with-param">xsl:with-param</a>* --><br />
|
|
</xsl:call-template></code></p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-named-template" id="dt-named-template" title=
|
|
"named template"></a>Templates can be invoked by name. An <a href=
|
|
"#element-template"><code>xsl:template</code></a> element with a
|
|
<code>name</code> attribute defines a <b>named
|
|
template</b>.<span class="definition">]</span> The value of the
|
|
<code>name</code> attribute is a <a title="QName" class="termref"
|
|
href="#dt-qname">QName</a>, which is expanded as described in
|
|
<a href="#qname"><i>5.1 Qualified Names</i></a>. If an <a href=
|
|
"#element-template"><code>xsl:template</code></a> element has a
|
|
<code>name</code> attribute, it may, but need not, also have a
|
|
<code>match</code> attribute. An <a href=
|
|
"#element-call-template"><code>xsl:call-template</code></a>
|
|
instruction invokes a template by name; it has a <span class=
|
|
"verb">required</span> <code>name</code> attribute that identifies
|
|
the template to be invoked. Unlike <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>,
|
|
the <a href=
|
|
"#element-call-template"><code>xsl:call-template</code></a>
|
|
instruction does not change the <a title="focus" class="termref"
|
|
href="#dt-focus">focus</a>.</p>
|
|
<p>The <code>match</code>, <code>mode</code> and
|
|
<code>priority</code> attributes on an <a href=
|
|
"#element-template"><code>xsl:template</code></a> element have no
|
|
effect when the <a title="template" class="termref" href=
|
|
"#dt-template">template</a> is invoked by an <a href=
|
|
"#element-call-template"><code>xsl:call-template</code></a>
|
|
instruction. Similarly, the <code>name</code> attribute on an
|
|
<a href="#element-template"><code>xsl:template</code></a> element
|
|
has no effect when the template is invoked by an <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>
|
|
instruction.</p>
|
|
<p><a name="err-XTSE0650" id="err-XTSE0650"><span class=
|
|
"error">[ERR XTSE0650]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> if a
|
|
<a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a> contains an <a href=
|
|
"#element-call-template"><code>xsl:call-template</code></a>
|
|
instruction whose <code>name</code> attribute does not match the
|
|
<code>name</code> attribute of any <a href=
|
|
"#element-template"><code>xsl:template</code></a> in the <a title=
|
|
"stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a>.</p>
|
|
<p><a name="err-XTSE0660" id="err-XTSE0660"><span class=
|
|
"error">[ERR XTSE0660]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> if a
|
|
<a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a> contains more than one <a title=
|
|
"template" class="termref" href="#dt-template">template</a> with
|
|
the same name and the same <a title="import precedence" class=
|
|
"termref" href="#dt-import-precedence">import precedence</a>,
|
|
unless it also contains a <a title="template" class="termref" href=
|
|
"#dt-template">template</a> with the same name and higher <a title=
|
|
"import precedence" class="termref" href=
|
|
"#dt-import-precedence">import precedence</a>.</p>
|
|
<p>The target <a title="template" class="termref" href=
|
|
"#dt-template">template</a> for an <a href=
|
|
"#element-call-template"><code>xsl:call-template</code></a>
|
|
instruction is the template whose <code>name</code> attribute
|
|
matches the <code>name</code> attribute of the <a href=
|
|
"#element-call-template"><code>xsl:call-template</code></a>
|
|
instruction and that has higher <a title="import precedence" class=
|
|
"termref" href="#dt-import-precedence">import precedence</a> than
|
|
any other template with this name. The result of evaluating an
|
|
<a href="#element-call-template"><code>xsl:call-template</code></a>
|
|
instruction is the sequence produced by evaluating the <a title=
|
|
"sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> contained in
|
|
its target <a title="template" class="termref" href=
|
|
"#dt-template">template</a> (see <a href=
|
|
"#sequence-constructors"><i>5.7 Sequence Constructors</i></a>).</p>
|
|
<div class="div3">
|
|
<h4><a name="call-template-params" id=
|
|
"call-template-params"></a>10.1.1 <a href="#call-template-params"
|
|
style="text-decoration: none">Passing Parameters to Named
|
|
Templates</a></h4>
|
|
<p>Parameters are passed to named templates using the <a href=
|
|
"#element-with-param"><code>xsl:with-param</code></a> element as a
|
|
child of the <a href=
|
|
"#element-call-template"><code>xsl:call-template</code></a>
|
|
instruction.</p>
|
|
<p><a name="err-XTSE0680" id="err-XTSE0680"><span class=
|
|
"error">[ERR XTSE0680]</span></a> In the case of <a href=
|
|
"#element-call-template"><code>xsl:call-template</code></a>, it is
|
|
a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> to pass a non-tunnel parameter
|
|
named <var>x</var> to a template that does not have a <a title=
|
|
"template parameter" class="termref" href=
|
|
"#dt-template-parameter">template parameter</a> named <var>x</var>,
|
|
unless <span>the <a href=
|
|
"#element-call-template"><code>xsl:call-template</code></a>
|
|
instruction is processed with <a title="XSLT 1.0 behavior" class=
|
|
"termref" href="#dt-xslt-10-behavior">XSLT 1.0 behavior</a></span>.
|
|
This is not an error in the case of <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>,
|
|
<a href=
|
|
"#element-apply-imports"><code>xsl:apply-imports</code></a>, and
|
|
<a href="#element-next-match"><code>xsl:next-match</code></a>; in
|
|
these cases the parameter is simply ignored.</p>
|
|
<p>The optional <code>tunnel</code> attribute may be used to
|
|
indicate that a parameter is a <a title="tunnel parameter" class=
|
|
"termref" href="#dt-tunnel-parameter">tunnel parameter</a>. The
|
|
default is <code>no</code>. Tunnel parameters are described in
|
|
<a href="#tunnel-params"><i>10.1.2 Tunnel Parameters</i></a></p>
|
|
<p><a name="err-XTSE0690" id="err-XTSE0690"><span class=
|
|
"error">[ERR XTSE0690]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> if a
|
|
template that is invoked using <a href=
|
|
"#element-call-template"><code>xsl:call-template</code></a>
|
|
declares a <a title="template parameter" class="termref" href=
|
|
"#dt-template-parameter">template parameter</a> specifying
|
|
<code>required="yes"</code> and not specifying
|
|
<code>tunnel="yes"</code>, if no value for this parameter is
|
|
supplied by the calling <a href=
|
|
"#element-call-template"><code>xsl:call-template</code></a>
|
|
instruction.</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e17960" id=
|
|
"d7e17960"></a>Example: Calling a Named Template with a
|
|
Parameter</div>
|
|
<p>This example defines a named template for a
|
|
<code>numbered-block</code> with a parameter to control the format
|
|
of the number.</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<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>
|
|
</pre></div>
|
|
</div>
|
|
</div>
|
|
<div class="div3">
|
|
<h4><a name="tunnel-params" id="tunnel-params"></a>10.1.2 <a href=
|
|
"#tunnel-params" style="text-decoration: none">Tunnel
|
|
Parameters</a></h4>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-tunnel-parameter" id="dt-tunnel-parameter" title=
|
|
"tunnel parameter"></a>A parameter passed to a template may be
|
|
defined as a <b>tunnel parameter</b>. Tunnel parameters have the
|
|
property that they are automatically passed on by the called
|
|
template to any further templates that it calls, and so on
|
|
recursively.<span class="definition">]</span> Tunnel parameters
|
|
thus allow values to be set that are accessible during an entire
|
|
phase of stylesheet processing, without the need for each template
|
|
that is used during that phase to be aware of the parameter.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>Tunnel parameters are conceptually similar to dynamically scoped
|
|
variables in some functional programming languages.</p>
|
|
</div>
|
|
<p>A <a title="tunnel parameter" class="termref" href=
|
|
"#dt-tunnel-parameter">tunnel parameter</a> is created by using an
|
|
<a href="#element-with-param"><code>xsl:with-param</code></a>
|
|
element that specifies <code>tunnel="yes"</code>. A template that
|
|
requires access to the value of a tunnel parameter must declare it
|
|
using an <a href="#element-param"><code>xsl:param</code></a>
|
|
element that also specifies <code>tunnel="yes"</code>.</p>
|
|
<p>On any template call using an <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>,
|
|
<a href=
|
|
"#element-call-template"><code>xsl:call-template</code></a>,
|
|
<a href="#element-apply-imports"><code>xsl:apply-imports</code></a>
|
|
or <a href="#element-next-match"><code>xsl:next-match</code></a>
|
|
instruction, a set of <a title="tunnel parameter" class="termref"
|
|
href="#dt-tunnel-parameter">tunnel parameters</a> is passed from
|
|
the calling template to the called template. This set consists of
|
|
any parameters explicitly created using <code><xsl:with-param
|
|
tunnel="yes"></code>, overlaid on a base set of tunnel
|
|
parameters. If the <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>,
|
|
<a href=
|
|
"#element-call-template"><code>xsl:call-template</code></a>,
|
|
<a href="#element-apply-imports"><code>xsl:apply-imports</code></a>
|
|
or <a href="#element-next-match"><code>xsl:next-match</code></a>
|
|
instruction has an <a href=
|
|
"#element-template"><code>xsl:template</code></a> declaration as an
|
|
ancestor element in the stylesheet, then the base set consists of
|
|
the tunnel parameters that were passed to that template; otherwise
|
|
(for example, if the instruction is within a global variable
|
|
declaration, an <a title="attribute set" class="termref" href=
|
|
"#dt-attribute-set">attribute set</a> declaration, or a <a title=
|
|
"stylesheet function" class="termref" href=
|
|
"#dt-stylesheet-function">stylesheet function</a>), the base set is
|
|
empty. If a parameter created using <code><xsl:with-param
|
|
tunnel="yes"></code> has the same <a title="expanded-QName"
|
|
class="termref" href="#dt-expanded-qname">expanded-QName</a> as a
|
|
parameter in the base set, then the parameter created using
|
|
<a href="#element-with-param"><code>xsl:with-param</code></a>
|
|
overrides the parameter in the base set; otherwise, the parameter
|
|
created using <a href=
|
|
"#element-with-param"><code>xsl:with-param</code></a> is added to
|
|
the base set.</p>
|
|
<p>When a template accesses the value of a <a title=
|
|
"tunnel parameter" class="termref" href=
|
|
"#dt-tunnel-parameter">tunnel parameter</a> by declaring it with
|
|
<code>xsl:param tunnel="yes"</code>, this does not remove the
|
|
parameter from the base set of tunnel parameters that is passed on
|
|
to any templates called by this template.</p>
|
|
<p>Two sibling <a href=
|
|
"#element-with-param"><code>xsl:with-param</code></a> elements
|
|
<span class="verb">must</span> have distinct parameter names, even
|
|
if one is a <a title="tunnel parameter" class="termref" href=
|
|
"#dt-tunnel-parameter">tunnel parameter</a> and the other is not.
|
|
Equally, two sibling <a href=
|
|
"#element-param"><code>xsl:param</code></a> elements representing
|
|
<a title="template parameter" class="termref" href=
|
|
"#dt-template-parameter">template parameters</a> <span class=
|
|
"verb">must</span> have distinct parameter names, even if one is a
|
|
<a title="tunnel parameter" class="termref" href=
|
|
"#dt-tunnel-parameter">tunnel parameter</a> and the other is not.
|
|
However, the tunnel parameters that are implicitly passed in a
|
|
template call <span class="verb">may</span> have names that
|
|
duplicate the names of non-tunnel parameters that are explicitly
|
|
passed on the same call.</p>
|
|
<p><a title="tunnel parameter" class="termref" href=
|
|
"#dt-tunnel-parameter">Tunnel parameters</a> are not passed in
|
|
calls to <a title="stylesheet function" class="termref" href=
|
|
"#dt-stylesheet-function">stylesheet functions</a>.</p>
|
|
<p>All other options of <a href=
|
|
"#element-with-param"><code>xsl:with-param</code></a> and <a href=
|
|
"#element-param"><code>xsl:param</code></a> are available with
|
|
<a title="tunnel parameter" class="termref" href=
|
|
"#dt-tunnel-parameter">tunnel parameters</a> just as with
|
|
non-tunnel parameters. For example, parameters may be declared as
|
|
mandatory or optional, a default value may be specified, and a
|
|
required type may be specified. If any conversion is required from
|
|
the supplied value of a tunnel parameter to the required type
|
|
specified in <a href="#element-param"><code>xsl:param</code></a>,
|
|
then the converted value is used within the receiving template, but
|
|
the value that is passed on in any further template calls is the
|
|
original supplied value before conversion. Equally, any default
|
|
value is local to the template: specifying a default value for a
|
|
tunnel parameter does not change the set of tunnel parameters that
|
|
is passed on in further template calls.</p>
|
|
<p>The set of <a title="tunnel parameter" class="termref" href=
|
|
"#dt-tunnel-parameter">tunnel parameters</a> that is passed to the
|
|
<a title="initial template" class="termref" href=
|
|
"#dt-initial-template">initial template</a> is empty.</p>
|
|
<p><a title="tunnel parameter" class="termref" href=
|
|
"#dt-tunnel-parameter">Tunnel parameters</a> are passed unchanged
|
|
through a built-in template rule (see <a href=
|
|
"#built-in-rule"><i>6.7 Built-in Template Rules</i></a>).</p>
|
|
<p>If a tunnel parameter is declared in an <a href=
|
|
"#element-param"><code>xsl:param</code></a> element with the
|
|
attribute <code>tunnel="yes"</code>, then a non-recoverable dynamic
|
|
error occurs <span class="error">[see <a href="#err-XTDE0700">ERR
|
|
XTDE0700</a>]</span> if the set of tunnel parameters passed to the
|
|
template does not include a parameter with a matching <a title=
|
|
"expanded-QName" class="termref" href="#dt-expanded-qname">expanded
|
|
QName</a>.</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e18142" id=
|
|
"d7e18142"></a>Example: Using Tunnel Parameters</div>
|
|
<p>Suppose that the equations in a scientific paper are to be
|
|
sequentially numbered, but that the format of the number depends on
|
|
the context in which the equations appear. It is possible to
|
|
reflect this using a rule of the form:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:template match="equation">
|
|
<xsl:param name="equation-format" select="'(1)'" tunnel="yes"/>
|
|
<xsl:number level="any" format="{$equation-format}"/>
|
|
</xsl:template>
|
|
</pre></div>
|
|
<p>At any level of processing above this level, it is possible to
|
|
determine how the equations will be numbered, for example:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:template match="appendix">
|
|
...
|
|
<xsl:apply-templates>
|
|
<xsl:with-param name="equation-format" select="'[i]'" tunnel="yes"/>
|
|
</xsl:apply-templates>
|
|
...
|
|
</xsl:template>
|
|
</pre></div>
|
|
<p>The parameter value is passed transparently through all the
|
|
intermediate layers of template rules until it reaches the rule
|
|
with <code>match="equation"</code>. The effect is similar to using
|
|
a global variable, except that the parameter can take different
|
|
values during different phases of the transformation.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="attribute-sets" id="attribute-sets"></a>10.2 <a href=
|
|
"#attribute-sets" style="text-decoration: none">Named Attribute
|
|
Sets</a></h3>
|
|
<p class="element-syntax"><a name="element-attribute-set" id=
|
|
"element-attribute-set"></a><code><!-- Category: declaration
|
|
--><br />
|
|
<xsl:attribute-set<br />
|
|
  <b>name</b> = <var>qname</var><br />
|
|
  use-attribute-sets? = <var>qnames</var> ><br />
|
|
  <!-- Content: <a href=
|
|
"#element-attribute">xsl:attribute</a>* --><br />
|
|
</xsl:attribute-set></code></p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-attribute-set" id="dt-attribute-set" title=
|
|
"attribute set"></a>The <a href=
|
|
"#element-attribute-set"><code>xsl:attribute-set</code></a> element
|
|
defines a named <b>attribute set</b>: that is, a collection of
|
|
attribute definitions that can be used repeatedly on different
|
|
constructed elements.<span class="definition">]</span></p>
|
|
<p>The <span class="verb">required</span> <code>name</code>
|
|
attribute specifies the name of the attribute set. The value of the
|
|
<code>name</code> attribute is a <a title="QName" class="termref"
|
|
href="#dt-qname">QName</a>, which is expanded as described in
|
|
<a href="#qname"><i>5.1 Qualified Names</i></a>. The content of the
|
|
<a href="#element-attribute-set"><code>xsl:attribute-set</code></a>
|
|
element consists of zero or more <a href=
|
|
"#element-attribute"><code>xsl:attribute</code></a> instructions
|
|
that are evaluated to produce the attributes in the set.</p>
|
|
<p>The result of evaluating an attribute set is a sequence of
|
|
attribute nodes. Evaluating the same attribute set more than once
|
|
can produce different results, because although an attribute set
|
|
does not have parameters, it may contain expressions or
|
|
instructions whose value depends on the evaluation context.</p>
|
|
<p><a title="attribute set" class="termref" href=
|
|
"#dt-attribute-set">Attribute sets</a> are used by specifying a
|
|
<code>use-attribute-sets</code> attribute on the <a href=
|
|
"#element-element"><code>xsl:element</code></a> or <a href=
|
|
"#element-copy"><code>xsl:copy</code></a> instruction, or by
|
|
specifying an <code>xsl:use-attribute-sets</code> attribute on a
|
|
literal result element. An attribute set may be defined in terms of
|
|
other attribute sets by using the <code>use-attribute-sets</code>
|
|
attribute on the <a href=
|
|
"#element-attribute-set"><code>xsl:attribute-set</code></a> element
|
|
itself. The value of the <code>[xsl:]use-attribute-sets</code>
|
|
attribute is in each case a whitespace-separated list of names of
|
|
attribute sets. Each name is specified as a <a title="QName" class=
|
|
"termref" href="#dt-qname">QName</a>, which is expanded as
|
|
described in <a href="#qname"><i>5.1 Qualified Names</i></a>.</p>
|
|
<p>Specifying a <code>use-attribute-sets</code> attribute is
|
|
broadly equivalent to adding <a href=
|
|
"#element-attribute"><code>xsl:attribute</code></a> instructions
|
|
for each of the attributes in each of the named attribute sets to
|
|
the beginning of the content of the instruction with the
|
|
<code>[xsl:]use-attribute-sets</code> attribute, in the same order
|
|
in which the names of the attribute sets are specified in the
|
|
<code>use-attribute-sets</code> attribute.</p>
|
|
<p>More formally, an <code>xsl:use-attribute-sets</code> attribute
|
|
is expanded using the following recursive algorithm, or any
|
|
algorithm that produces the same results:</p>
|
|
<ul>
|
|
<li>
|
|
<p>The value of the attribute is tokenized as a list of QNames.</p>
|
|
</li>
|
|
<li>
|
|
<p>Each QName in the list is processed, in order, as follows:</p>
|
|
<ul>
|
|
<li>
|
|
<p>The QName must match the <code>name</code> attribute of one or
|
|
more <a href=
|
|
"#element-attribute-set"><code>xsl:attribute-set</code></a>
|
|
declarations in the stylesheet.</p>
|
|
</li>
|
|
<li>
|
|
<p>Each <a href=
|
|
"#element-attribute-set"><code>xsl:attribute-set</code></a>
|
|
declaration whose name matches is processed as follows. Where two
|
|
such declarations have different <a title="import precedence"
|
|
class="termref" href="#dt-import-precedence">import precedence</a>,
|
|
the one with lower import precedence is processed first. Where two
|
|
declarations have the same import precedence, they are processed in
|
|
<a title="declaration order" class="termref" href=
|
|
"#dt-declaration-order">declaration order</a>.</p>
|
|
<ul>
|
|
<li>
|
|
<p>If the <a href=
|
|
"#element-attribute-set"><code>xsl:attribute-set</code></a>
|
|
declaration has a <code>use-attribute-sets</code> attribute, the
|
|
attribute is expanded by applying this algorithm recursively.</p>
|
|
</li>
|
|
<li>
|
|
<p>If the <a href=
|
|
"#element-attribute-set"><code>xsl:attribute-set</code></a>
|
|
declaration contains one or more <a href=
|
|
"#element-attribute"><code>xsl:attribute</code></a> instructions,
|
|
these instructions are evaluated (following the rules for
|
|
evaluating a <a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a>: see <a href=
|
|
"#sequence-constructors"><i>5.7 Sequence Constructors</i></a>) to
|
|
produce a sequence of attribute nodes. These attribute nodes are
|
|
appended to the result sequence.</p>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
<p>The <a href="#element-attribute"><code>xsl:attribute</code></a>
|
|
instructions are evaluated using the same <a title="focus" class=
|
|
"termref" href="#dt-focus">focus</a> as is used for evaluating the
|
|
element that is the parent of the
|
|
<code>[xsl:]use-attribute-sets</code> attribute forming the initial
|
|
input to the algorithm. However, the static context for the
|
|
evaluation depends on the position of the <a href=
|
|
"#element-attribute"><code>xsl:attribute</code></a> instruction in
|
|
the stylesheet: thus, only local variables declared within an
|
|
<a href="#element-attribute"><code>xsl:attribute</code></a>
|
|
instruction, and global variables, are visible.</p>
|
|
<p>The set of attribute nodes produced by expanding
|
|
<code>xsl:use-attribute-sets</code> may include several attributes
|
|
with the same name. When the attributes are added to an element
|
|
node, only the last of the duplicates will take effect.</p>
|
|
<p>The way in which each instruction uses the results of expanding
|
|
the <code>[xsl:]use-attribute-sets</code> attribute is described in
|
|
the specification for the relevant instruction: see <a href=
|
|
"#literal-result-element"><i>11.1 Literal Result Elements</i></a>,
|
|
<a href="#xsl-element"><i>11.2 Creating Element Nodes Using
|
|
xsl:element</i></a> , and <a href="#copying"><i>11.9 Copying
|
|
Nodes</i></a>.</p>
|
|
<p><a name="err-XTSE0710" id="err-XTSE0710"><span class=
|
|
"error">[ERR XTSE0710]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> if the
|
|
value of the <code>use-attribute-sets</code> attribute of an
|
|
<a href="#element-copy"><code>xsl:copy</code></a>, <a href=
|
|
"#element-element"><code>xsl:element</code></a>, or <a href=
|
|
"#element-attribute-set"><code>xsl:attribute-set</code></a>
|
|
element, or the <code>xsl:use-attribute-sets</code> attribute of a
|
|
<a title="literal result element" class="termref" href=
|
|
"#dt-literal-result-element">literal result element</a>, is not a
|
|
whitespace-separated sequence of <a title="QName" class="termref"
|
|
href="#dt-qname">QNames</a>, or if it contains a QName that does
|
|
not match the <code>name</code> attribute of any <a href=
|
|
"#element-attribute-set"><code>xsl:attribute-set</code></a>
|
|
declaration in the stylesheet.</p>
|
|
<p><a name="err-XTSE0720" id="err-XTSE0720"><span class=
|
|
"error">[ERR XTSE0720]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> if an
|
|
<a href="#element-attribute-set"><code>xsl:attribute-set</code></a>
|
|
element directly or indirectly references itself via the names
|
|
contained in the <code>use-attribute-sets</code> attribute.</p>
|
|
<p>Each attribute node produced by expanding an attribute set has a
|
|
<a title="type annotation" class="termref" href=
|
|
"#dt-annotation">type annotation</a> determined by the rules for
|
|
the <a href="#element-attribute"><code>xsl:attribute</code></a>
|
|
instruction that created the attribute node: see <a href=
|
|
"#annotation-for-constructed-attribute"><i>11.3.1 Setting the Type
|
|
Annotation for a Constructed Attribute Node</i></a>. These type
|
|
annotations may be preserved, stripped, or replaced as determined
|
|
by the rules for the instruction that creates the element in which
|
|
the attributes are used.</p>
|
|
<p>Attribute sets are used as follows:</p>
|
|
<ul>
|
|
<li>
|
|
<p>The <a href="#element-copy"><code>xsl:copy</code></a> and
|
|
<a href="#element-element"><code>xsl:element</code></a>
|
|
instructions have an <code>use-attribute-sets</code> attribute. The
|
|
sequence of attribute nodes produced by evaluating this attribute
|
|
is prepended to the sequence produced by evaluating the <a title=
|
|
"sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> contained
|
|
within the instruction.</p>
|
|
</li>
|
|
<li>
|
|
<p><a title="literal result element" class="termref" href=
|
|
"#dt-literal-result-element">Literal result elements</a> allow an
|
|
<code>xsl:use-attribute-sets</code> attribute, which is evaluated
|
|
in the same way as the <code>use-attribute-sets</code> attribute of
|
|
<a href="#element-element"><code>xsl:element</code></a> and
|
|
<a href="#element-copy"><code>xsl:copy</code></a>. The sequence of
|
|
attribute nodes produced by evaluating this attribute is prepended
|
|
to the sequence of attribute nodes produced by evaluating the
|
|
attributes of the literal result element, which in turn is
|
|
prepended to the sequence produced by evaluating the <a title=
|
|
"sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> contained with
|
|
the literal result element.</p>
|
|
</li>
|
|
</ul>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e18447" id=
|
|
"d7e18447"></a>Example: Using Attribute Sets</div>
|
|
<p>The following example creates a named <a title="attribute set"
|
|
class="termref" href="#dt-attribute-set">attribute set</a>
|
|
<code>title-style</code> and uses it in a <a title="template rule"
|
|
class="termref" href="#dt-template-rule">template rule</a>.</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<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>
|
|
</pre></div>
|
|
</div>
|
|
<p> </p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e18463" id=
|
|
"d7e18463"></a>Example: Overriding Attributes in an Attribute
|
|
Set</div>
|
|
<p>The following example creates a named attribute set
|
|
<code>base-style</code> and uses it in a template rule with
|
|
multiple specifications of the attributes:</p>
|
|
<dl>
|
|
<dt class="label">font-family</dt>
|
|
<dd>
|
|
<p>is specified only in the attribute set</p>
|
|
</dd>
|
|
<dt class="label">font-size</dt>
|
|
<dd>
|
|
<p>is specified in the attribute set, is specified on the literal
|
|
result element, and in an <a href=
|
|
"#element-attribute"><code>xsl:attribute</code></a> instruction</p>
|
|
</dd>
|
|
<dt class="label">font-style</dt>
|
|
<dd>
|
|
<p>is specified in the attribute set, and on the literal result
|
|
element</p>
|
|
</dd>
|
|
<dt class="label">font-weight</dt>
|
|
<dd>
|
|
<p>is specified in the attribute set, and in an <a href=
|
|
"#element-attribute"><code>xsl:attribute</code></a> instruction</p>
|
|
</dd>
|
|
</dl>
|
|
<p>Stylesheet fragment:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:attribute-set name="base-style">
|
|
<xsl:attribute name="font-family">Univers</xsl:attribute>
|
|
<xsl:attribute name="font-size">10pt</xsl:attribute>
|
|
<xsl:attribute name="font-style">normal</xsl:attribute>
|
|
<xsl:attribute name="font-weight">normal</xsl:attribute>
|
|
</xsl:attribute-set>
|
|
|
|
<xsl:template match="o">
|
|
<fo:block xsl:use-attribute-sets="base-style"
|
|
font-size="12pt"
|
|
font-style="italic">
|
|
<xsl:attribute name="font-size">14pt</xsl:attribute>
|
|
<xsl:attribute name="font-weight">bold</xsl:attribute>
|
|
<xsl:apply-templates/>
|
|
</fo:block>
|
|
</xsl:template>
|
|
</pre></div>
|
|
<p>Result:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<fo:block font-family="Univers"
|
|
font-size="14pt"
|
|
font-style="italic"
|
|
font-weight="bold">
|
|
...
|
|
</fo:block>
|
|
</pre></div>
|
|
</div>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="stylesheet-functions" id=
|
|
"stylesheet-functions"></a>10.3 <a href="#stylesheet-functions"
|
|
style="text-decoration: none">Stylesheet Functions</a></h3>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-stylesheet-function" id="dt-stylesheet-function" title=
|
|
"stylesheet function"></a>An <a href=
|
|
"#element-function"><code>xsl:function</code></a> declaration
|
|
declares the name, parameters, and implementation of a
|
|
<b>stylesheet function</b> that can be called from any XPath
|
|
<a title="expression" class="termref" href=
|
|
"#dt-expression">expression</a> within the <a title="stylesheet"
|
|
class="termref" href="#dt-stylesheet">stylesheet</a>.<span class=
|
|
"definition">]</span></p>
|
|
<p class="element-syntax"><a name="element-function" id=
|
|
"element-function"></a><code><!-- Category: declaration
|
|
--><br />
|
|
<xsl:function<br />
|
|
  <b>name</b> = <var>qname</var><br />
|
|
  as? = <var>sequence-type</var><br />
|
|
  override? = "yes" | "no" ><br />
|
|
  <!-- Content: (<a href=
|
|
"#element-param">xsl:param</a>*, <var>sequence-constructor</var>)
|
|
--><br />
|
|
</xsl:function></code></p>
|
|
<p>The <a href="#element-function"><code>xsl:function</code></a>
|
|
declaration defines a <a title="stylesheet function" class=
|
|
"termref" href="#dt-stylesheet-function">stylesheet function</a>
|
|
that can be called from any XPath <a title="expression" class=
|
|
"termref" href="#dt-expression">expression</a> used in the
|
|
<a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a> (including an XPath expression used
|
|
within a predicate in a <a title="pattern" class="termref" href=
|
|
"#dt-pattern">pattern</a>). The <code>name</code> attribute
|
|
specifies the name of the function. The value of the
|
|
<code>name</code> attribute is a <a title="QName" class="termref"
|
|
href="#dt-qname">QName</a>, which is expanded as described in
|
|
<a href="#qname"><i>5.1 Qualified Names</i></a>.</p>
|
|
<p>An <a href="#element-function"><code>xsl:function</code></a>
|
|
declaration can only appear as a top-level element in a stylesheet
|
|
module.</p>
|
|
<p><a name="err-XTSE0740" id="err-XTSE0740"><span class=
|
|
"error">[ERR XTSE0740]</span></a> A <a title="stylesheet function"
|
|
class="termref" href="#dt-stylesheet-function">stylesheet
|
|
function</a> <span class="verb">must</span> have a prefixed name,
|
|
to remove any risk of a clash with a function in the default
|
|
function namespace. It is a <a title="static error" class="termref"
|
|
href="#dt-static-error">static error</a> if the name has no
|
|
prefix..</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>To prevent the namespace declaration used for the function name
|
|
appearing in the result document, use the
|
|
<code>exclude-result-prefixes</code> attribute on the <a href=
|
|
"#element-stylesheet"><code>xsl:stylesheet</code></a> element: see
|
|
<a href="#lre-namespaces"><i>11.1.3 Namespace Nodes for Literal
|
|
Result Elements</i></a>.</p>
|
|
<p>The prefix <span class="verb">must not</span> refer to a
|
|
<a title="reserved namespace" class="termref" href=
|
|
"#dt-reserved-namespace">reserved namespace</a>: <span class=
|
|
"error">[see <a href="#err-XTSE0080">ERR XTSE0080</a>]</span></p>
|
|
</div>
|
|
<p>The content of the <a href=
|
|
"#element-function"><code>xsl:function</code></a> element consists
|
|
of zero or more <a href="#element-param"><code>xsl:param</code></a>
|
|
elements that specify the formal arguments of the function,
|
|
followed by a <a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> that defines
|
|
the value to be returned by the function.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-arity" id="dt-arity" title="arity"></a>The <b>arity</b> of a
|
|
stylesheet function is the number of <a href=
|
|
"#element-param"><code>xsl:param</code></a> elements in the
|
|
function definition.<span class="definition">]</span> Optional
|
|
arguments are not allowed.</p>
|
|
<p><a name="err-XTSE0760" id="err-XTSE0760"><span class=
|
|
"error">[ERR XTSE0760]</span></a> Because arguments to a stylesheet
|
|
function call <span class="verb">must</span> all be specified, the
|
|
<a href="#element-param"><code>xsl:param</code></a> elements within
|
|
an <a href="#element-function"><code>xsl:function</code></a>
|
|
element <span class="verb">must not</span> specify a default value:
|
|
this means they <span class="verb">must</span> be empty, and
|
|
<span class="verb">must not</span> have a <code>select</code>
|
|
attribute.</p>
|
|
<p>A <a title="stylesheet function" class="termref" href=
|
|
"#dt-stylesheet-function">stylesheet function</a> is included in
|
|
the <em>in-scope functions</em> of the static context for all XPath
|
|
expressions used in the <a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a>, unless</p>
|
|
<ul>
|
|
<li>
|
|
<p>there is another <a title="stylesheet function" class="termref"
|
|
href="#dt-stylesheet-function">stylesheet function</a> with the
|
|
same name and <a title="arity" class="termref" href=
|
|
"#dt-arity">arity</a>, and higher <a title="import precedence"
|
|
class="termref" href="#dt-import-precedence">import precedence</a>,
|
|
or</p>
|
|
</li>
|
|
<li>
|
|
<p>the <code>override</code> attribute has the value
|
|
<code>no</code> and there is already a function with the same name
|
|
and <a title="arity" class="termref" href="#dt-arity">arity</a> in
|
|
the in-scope functions.</p>
|
|
</li>
|
|
</ul>
|
|
<p>The optional <code>override</code> attribute defines what
|
|
happens if this function has the same name and <a title="arity"
|
|
class="termref" href="#dt-arity">arity</a> as a function provided
|
|
by the implementer or made available in the static context using an
|
|
implementation-defined mechanism. If the <code>override</code>
|
|
attribute has the value <code>yes</code>, then this function is
|
|
used in preference; if it has the value <code>no</code>, then the
|
|
other function is used in preference. The default value is
|
|
<code>yes</code>.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>Specifying <code>override="yes"</code> ensures interoperable
|
|
behavior: the same code will execute with all processors.
|
|
Specifying <code>override="no"</code> is useful when writing a
|
|
fallback implementation of a function that is available with some
|
|
processors but not others: it allows the vendor's implementation of
|
|
the function (or a user's implementation written as an extension
|
|
function) to be used in preference to the stylesheet
|
|
implementation, which is useful when the extension function is more
|
|
efficient.</p>
|
|
<p>The <code>override</code> attribute does <em>not</em> affect the
|
|
rules for deciding which of several <a title="stylesheet function"
|
|
class="termref" href="#dt-stylesheet-function">stylesheet
|
|
functions</a> with the same name and <a title="arity" class=
|
|
"termref" href="#dt-arity">arity</a> takes precedence.</p>
|
|
</div>
|
|
<p><a name="err-XTSE0770" id="err-XTSE0770"><span class=
|
|
"error">[ERR XTSE0770]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> for a
|
|
<a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a> to contain two or more functions
|
|
with the same <a title="expanded-QName" class="termref" href=
|
|
"#dt-expanded-qname">expanded-QName</a>, the same <a title="arity"
|
|
class="termref" href="#dt-arity">arity</a>, and the same <a title=
|
|
"import precedence" class="termref" href=
|
|
"#dt-import-precedence">import precedence</a>, unless there is
|
|
another function with the same <a title="expanded-QName" class=
|
|
"termref" href="#dt-expanded-qname">expanded-QName</a> and arity,
|
|
and a higher import precedence.</p>
|
|
<p>As defined in XPath, the function that is executed as the result
|
|
of a function call is identified by looking in the in-scope
|
|
functions of the static context for a function whose name and
|
|
<a title="arity" class="termref" href="#dt-arity">arity</a> matches
|
|
the name and number of arguments in the function call.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>Functions are not polymorphic. Although the XPath function call
|
|
mechanism allows two functions to have the same name and different
|
|
<a title="arity" class="termref" href="#dt-arity">arity</a>, it
|
|
does not allow them to be distinguished by the types of their
|
|
arguments.</p>
|
|
</div>
|
|
<p>The optional <code>as</code> attribute indicates the <a title=
|
|
"required type" class="termref" href="#dt-required-type">required
|
|
type</a> of the result of the function. The value of the
|
|
<code>as</code> attribute is a <a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-SequenceType">SequenceType</a><sup><small>XP21</small></sup>,
|
|
as defined in <a href="#xpath-21">[XPath 2.1]</a>.</p>
|
|
<p><a name="err-XTTE0780" id="err-XTTE0780"><span class=
|
|
"error">[ERR XTTE0780]</span></a> If the <code>as</code> attribute
|
|
is specified, then the result evaluated by the <a title=
|
|
"sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> (see <a href=
|
|
"#sequence-constructors"><i>5.7 Sequence Constructors</i></a>) is
|
|
converted to the required type, using the <a title=
|
|
"function conversion rules" class="termref" href=
|
|
"#dt-function-conversion-rules">function conversion rules</a>. It
|
|
is a <a title="type errors" class="termref" href=
|
|
"#dt-type-error">type error</a> if this conversion fails. If the
|
|
<code>as</code> attribute is omitted, the calculated result is used
|
|
as supplied, and no conversion takes place.</p>
|
|
<p>If a <a title="stylesheet function" class="termref" href=
|
|
"#dt-stylesheet-function">stylesheet function</a> has been defined
|
|
with a particular <a title="expanded-QName" class="termref" href=
|
|
"#dt-expanded-qname">expanded-QName</a>, then a call on <a href=
|
|
"#function-function-available"><code>function-available</code></a>
|
|
will return true when called with an argument that is a <a title=
|
|
"lexical QName" class="termref" href="#dt-lexical-qname">lexical
|
|
QName</a> that expands to this same <a title="expanded-QName"
|
|
class="termref" href="#dt-expanded-qname">expanded-QName</a>.</p>
|
|
<p>The <a href="#element-param"><code>xsl:param</code></a> elements
|
|
define the formal arguments to the function. These are interpreted
|
|
positionally. When the function is called using a function-call in
|
|
an XPath <a title="expression" class="termref" href=
|
|
"#dt-expression">expression</a>, the first argument supplied is
|
|
assigned to the first <a href=
|
|
"#element-param"><code>xsl:param</code></a> element, the second
|
|
argument supplied is assigned to the second <a href=
|
|
"#element-param"><code>xsl:param</code></a> element, and so on.</p>
|
|
<p>The <code>as</code> attribute of the <a href=
|
|
"#element-param"><code>xsl:param</code></a> element defines the
|
|
required type of the parameter. The rules for converting the values
|
|
of the actual arguments supplied in the function call to the types
|
|
required by each <a href=
|
|
"#element-param"><code>xsl:param</code></a> element are defined in
|
|
<a href="#xpath-21">[XPath 2.1]</a>. The rules that apply are those
|
|
for the case where <a title="XPath 1.0 compatibility mode" class=
|
|
"termref" href="#dt-xpath-compat-mode">XPath 1.0 compatibility
|
|
mode</a> is set to <code>false</code>.</p>
|
|
<p><a name="err-XTTE0790" id="err-XTTE0790"><span class=
|
|
"error">[ERR XTTE0790]</span></a> If the value of a parameter to a
|
|
<a title="stylesheet function" class="termref" href=
|
|
"#dt-stylesheet-function">stylesheet function</a> cannot be
|
|
converted to the required type, a <a title="type errors" class=
|
|
"termref" href="#dt-type-error">type error</a> is signaled.</p>
|
|
<p>If the <code>as</code> attribute is omitted, no conversion takes
|
|
place and any value is accepted.</p>
|
|
<p>Within the body of a stylesheet function, the <a title="focus"
|
|
class="termref" href="#dt-focus">focus</a> is initially undefined;
|
|
this means that any attempt to reference the context item, context
|
|
position, or context size is a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a>.
|
|
[XPDY0002]</p>
|
|
<p>It is not possible within the body of the <a title=
|
|
"stylesheet function" class="termref" href=
|
|
"#dt-stylesheet-function">stylesheet function</a> 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.</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e18913" id=
|
|
"d7e18913"></a>Example: A Stylesheet Function</div>
|
|
<p>The following example creates a recursive <a title=
|
|
"stylesheet function" class="termref" href=
|
|
"#dt-stylesheet-function">stylesheet function</a> named
|
|
<code>str:reverse</code> that reverses the words in a supplied
|
|
sentence, and then invokes this function from within a <a title=
|
|
"template rule" class="termref" href="#dt-template-rule">template
|
|
rule</a>.</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:transform
|
|
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
|
|
xmlns:xs="http://www.w3.org/2001/XMLSchema"
|
|
xmlns:str="http://example.com/namespace"
|
|
version="2.1"
|
|
exclude-result-prefixes="str">
|
|
|
|
<xsl:function name="str:reverse" as="xs:string">
|
|
<xsl:param name="sentence" as="xs:string"/>
|
|
<xsl:sequence
|
|
select="if (contains($sentence, ' '))
|
|
then concat(str:reverse(substring-after($sentence, ' ')),
|
|
' ',
|
|
substring-before($sentence, ' '))
|
|
else $sentence"/>
|
|
</xsl:function>
|
|
|
|
<xsl:template match="/">
|
|
<output>
|
|
<xsl:value-of select="str:reverse('DOG BITES MAN')"/>
|
|
</output>
|
|
</xsl:template>
|
|
|
|
</xsl:transform>
|
|
</pre></div>
|
|
<p>An alternative way of writing the same function is to implement
|
|
the conditional logic at the XSLT level, thus:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:function name="str:reverse" as="xs:string">
|
|
<xsl:param name="sentence" as="xs:string"/>
|
|
<xsl:choose>
|
|
<xsl:when test="contains($sentence, ' ')">
|
|
<xsl:sequence
|
|
select="concat(str:reverse(substring-after($sentence, ' ')),
|
|
' ',
|
|
substring-before($sentence, ' '))"/>
|
|
</xsl:when>
|
|
<xsl:otherwise>
|
|
<xsl:sequence select="$sentence"/>
|
|
</xsl:otherwise>
|
|
</xsl:choose>
|
|
</xsl:function>
|
|
</pre></div>
|
|
</div>
|
|
<p> </p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e18933" id=
|
|
"d7e18933"></a>Example: Declaring the Return Type of a
|
|
Function</div>
|
|
<p>The following example illustrates the use of the <code>as</code>
|
|
attribute in a function definition. It returns a string containing
|
|
the representation of its integer argument, expressed as a roman
|
|
numeral. For example, the function call <code>num:roman(7)</code>
|
|
will return the string <code>"vii"</code>. This example uses the
|
|
<a href="#element-number"><code>xsl:number</code></a> instruction,
|
|
described in <a href="#number"><i>12 Numbering</i></a>. The
|
|
<a href="#element-number"><code>xsl:number</code></a> instruction
|
|
returns a text node, and the <a title="function conversion rules"
|
|
class="termref" href="#dt-function-conversion-rules">function
|
|
conversion rules</a> are invoked to convert this text node to the
|
|
type declared in the <a href=
|
|
"#element-function"><code>xsl:function</code></a> element, namely
|
|
<code>xs:string</code>. So the text node is <a title="atomize"
|
|
class="termref" href="#dt-atomization">atomized</a> to a
|
|
string.</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:function name="num:roman" as="xs:string">
|
|
<xsl:param name="value" as="xs:integer"/>
|
|
<xsl:number value="$value" format="i"/>
|
|
</xsl:function>
|
|
</pre></div>
|
|
</div>
|
|
<p> </p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e18970" id=
|
|
"d7e18970"></a>Example: A Higher-Order Function</div>
|
|
<p>XPath 2.1 introduces the ability to pass function items as
|
|
argument to a function. A function that takes function items as
|
|
arguments is known as a higher-order function.</p>
|
|
<p>The following example is a higher-order function that operates
|
|
on any tree-structured data, for example an organization chart.
|
|
Given as input a function that finds the direct subordinates of a
|
|
node in this tree structure (for example, the direct reports of a
|
|
manager, or the geographical subdivisions of an administrative
|
|
area), it determines whether one object is present in the subtree
|
|
rooted at another object (for example, whether one person is among
|
|
the staff managed directly or indirectly by a manager, or whether
|
|
one parcel of land is contained directly or indirectly within
|
|
another parcel. The function does not check for cycles in the
|
|
data.</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:function name="f:is-subordinate" as="xs:boolean">
|
|
<xsl:param name="superior"
|
|
as="node()"/>
|
|
<xsl:param name="subordinate"
|
|
as="node()"/>
|
|
<xsl:param name="get-direct-children"
|
|
as="function(node()) as node()*"/>
|
|
<xsl:sequence select="
|
|
some $sub in $get-direct-children($superior) satisfies
|
|
($sub is $subordinate or
|
|
f:is-subordinate($sub, $subordinate,
|
|
$get-direct-children))"/>
|
|
</xsl:function>
|
|
</pre></div>
|
|
<p>Given source data representing an organization chart in the form
|
|
of elements such as:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<employee id="P57832" manager="P68951"/>
|
|
</pre></div>
|
|
<p>the following function can be defined to get the direct reports
|
|
of a manager:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:function name="f:direct-reports"
|
|
as="element(employee)*">
|
|
<xsl:param name="manager" as="element(employee)"/>
|
|
<xsl:sequence select="$manager/../employee
|
|
[@manager = current()/@id]"/>
|
|
</xsl:function>
|
|
</pre></div>
|
|
<p>It is then possible to test whether one employee $E reports
|
|
directly or indirectly to another employee $M by means of the
|
|
function call:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
f:is-subordinate($M, $E, f:direct-reports#1)
|
|
</pre></div>
|
|
</div>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="dynamic-xpath" id="dynamic-xpath"></a>10.4 <a href=
|
|
"#dynamic-xpath" style="text-decoration: none">Dynamic XPath
|
|
Evaluation</a></h3>
|
|
<p class="element-syntax"><a name="element-evaluate" id=
|
|
"element-evaluate"></a><code><!-- Category: instruction
|
|
--><br />
|
|
<xsl:evaluate<br />
|
|
  <b>xpath</b> = <var>expression</var><br />
|
|
  as? = <var>sequence-type</var><br />
|
|
  base-uri? = { <var>URI</var> }<br />
|
|
  namespace-context? = <var>expression</var><br />
|
|
  schema-aware? = { "yes" | "no" } ><br />
|
|
  <!-- Content: (<a href=
|
|
"#element-with-param">xsl:with-param</a> | <a href=
|
|
"#element-fallback">xsl:fallback</a>)* --><br />
|
|
</xsl:evaluate></code></p>
|
|
<p>The <a href="#element-evaluate"><code>xsl:evaluate</code></a>
|
|
instruction constructs an XPath expression in the form of a string,
|
|
evaluates the expression in a specified context, and returns the
|
|
result of the evaluation.</p>
|
|
<p>The expression given as the value of the <code>xpath</code>
|
|
attribute is evaluated and the result is converted to a string
|
|
using the <a title="function conversion rules" class="termref"
|
|
href="#dt-function-conversion-rules">function conversion
|
|
rules</a>.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-target-expression" id="dt-target-expression" title=
|
|
"target expression"></a>The string that results from evaluating the
|
|
expression in the <code>xpath</code> attribute is referred to as
|
|
the <b>target expression</b>.<span class="definition">]</span></p>
|
|
<p><a name="err-XTDE2150" id="err-XTDE2150"><span class=
|
|
"error">[ERR XTDE2150]</span></a> It is a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> if the
|
|
<a title="target expression" class="termref" href=
|
|
"#dt-target-expression">target expression</a> is not a legal XPath
|
|
2.1 expression (that is, if a static error occurs when analyzing
|
|
the string according to the rules of the XPath 2.1
|
|
specification).</p>
|
|
<p>The <code>as</code> attribute, if present, indicates the
|
|
required type of the result. If the attribute is absent, the
|
|
required type is <code>item()*</code>, which allows any result. The
|
|
result of evaluating the <a title="target expression" class=
|
|
"termref" href="#dt-target-expression">target expression</a> is
|
|
converted to the required type using the <a title=
|
|
"function conversion rules" class="termref" href=
|
|
"#dt-function-conversion-rules">function conversion rules</a>. This
|
|
may cause a <a title="type errors" class="termref" href=
|
|
"#dt-type-error">type error</a> if conversion is not possible. The
|
|
result after conversion is returned as the result of the <a href=
|
|
"#element-evaluate"><code>xsl:evaluate</code></a> instruction.</p>
|
|
<p>The <a href=
|
|
"http://www.w3.org/TR/xpath-21/#dt-static-context">static
|
|
context</a><sup><small>XP21</small></sup> for the <a title=
|
|
"target expression" class="termref" href=
|
|
"#dt-target-expression">target expression</a> is as follows:</p>
|
|
<ul>
|
|
<li>
|
|
<p>XPath 1.0 compatibility mode is <code>false</code>.</p>
|
|
</li>
|
|
<li>
|
|
<p>Statically known namespaces and default element/type
|
|
namespace:</p>
|
|
<ul>
|
|
<li>
|
|
<p>if the <code>namespace-context</code> attribute is present, then
|
|
its value is an <a title="expression" class="termref" href=
|
|
"#dt-expression">expression</a> whose required type is a single
|
|
node. The expression is evaluated, and the in-scope namespaces of
|
|
the resulting node are used as the statically known namespaces for
|
|
the target expression. The binding for the default namespace in the
|
|
in-scope namespaces is used as the default namespace for elements
|
|
and types in the target expression.</p>
|
|
<p><a name="err-XTTE2160" id="err-XTTE2160"><span class=
|
|
"error">[ERR XTTE2160]</span></a> It is a <a title="type errors"
|
|
class="termref" href="#dt-type-error">type error</a> if the result
|
|
of evaluating the <code>namespace-context</code> attribute of the
|
|
<a href="#element-evaluate"><code>xsl:evaluate</code></a>
|
|
instruction is anything other than a single node.</p>
|
|
</li>
|
|
<li>
|
|
<p>if the <code>namespace-context</code> attribute is absent, then
|
|
the in-scope namespaces of the <a href=
|
|
"#element-evaluate"><code>xsl:evaluate</code></a> instruction (with
|
|
the exception of any binding for the default namespace) are used as
|
|
the statically known namespaces for the target expression, and the
|
|
value of the innermost <code>[xsl:]xpath-default-namespace</code>
|
|
attribute, if any, is used as the default namespace for elements
|
|
and types in the target expression.</p>
|
|
</li>
|
|
</ul>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>XPath 2.1 allows expanded names to be written in a
|
|
context-independent way using the syntax
|
|
<code>"namespace-uri":local-name</code></p>
|
|
</div>
|
|
</li>
|
|
<li>
|
|
<p>Default function namespace: the <a title=
|
|
"standard function namespace" class="termref" href=
|
|
"#dt-standard-function-namespace">standard function
|
|
namespace</a>.</p>
|
|
</li>
|
|
<li>
|
|
<p>In-scope schema definitions: if the <code>schema-aware</code>
|
|
attribute is present and has the <a title="effective value" class=
|
|
"termref" href="#dt-effective-value">effective value</a>
|
|
<code>yes</code>, then the in-scope schema definitions from the
|
|
stylesheet context (that is, the schema definitions imported using
|
|
<a href=
|
|
"#element-import-schema"><code>xsl:import-schema</code></a>).
|
|
Otherwise, the built-in types (see <a href=
|
|
"#built-in-types"><i>3.13 Built-in Types</i></a>).</p>
|
|
</li>
|
|
<li>
|
|
<p>In-scope variables: the variables defined in the contained
|
|
<a href="#element-with-param"><code>xsl:with-param</code></a>
|
|
elements.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>Variables declared in the stylesheet in <a href=
|
|
"#element-variable"><code>xsl:variable</code></a> or <a href=
|
|
"#element-param"><code>xsl:param</code></a> elements are
|
|
<em>not</em> in-scope within the target expression.</p>
|
|
</div>
|
|
</li>
|
|
<li>
|
|
<p>Function signatures: All <a title="core function" class=
|
|
"termref" href="#dt-core-function">core functions</a>; constructor
|
|
functions for atomic types included in the in-scope schema
|
|
definitions; user-defined functions declared using <a href=
|
|
"#element-function"><code>xsl:function</code></a>; and an <a title=
|
|
"implementation-defined" class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a> set of
|
|
<a title="extension function" class="termref" href=
|
|
"#dt-extension-function">extension functions</a>.</p>
|
|
<p>Note that this set deliberately excludes XSLT-defined functions
|
|
in the <a title="standard function namespace" class="termref" href=
|
|
"#dt-standard-function-namespace">standard function namespace</a>
|
|
including for example, <a href=
|
|
"#function-key"><code>key</code></a>, <a href=
|
|
"#function-current-group"><code>current-group</code></a>, and
|
|
<a href=
|
|
"#function-system-property"><code>system-property</code></a> A list
|
|
of these functions is in <a href="#XSLT-defined-functions"><i>F
|
|
List of XSLT-defined functions</i></a>.</p>
|
|
</li>
|
|
<li>
|
|
<p>Statically known collections: the same as the collations
|
|
available at this point in the stylesheet.</p>
|
|
</li>
|
|
<li>
|
|
<p>Default collation: the same as the default collation defined at
|
|
this point in the stylesheet (for example, by use of the
|
|
<code>[xsl:]default-collation</code> attribute)</p>
|
|
</li>
|
|
<li>
|
|
<p>Base URI: if the <code>base-uri</code> attribute is present,
|
|
then its <a title="effective value" class="termref" href=
|
|
"#dt-effective-value">effective value</a>; otherwise, the base URI
|
|
of the <a href="#element-evaluate"><code>xsl:evaluate</code></a>
|
|
instruction.</p>
|
|
</li>
|
|
<li>
|
|
<p>Statically known documents: the empty set</p>
|
|
</li>
|
|
<li>
|
|
<p>Statically known collections: the empty set</p>
|
|
</li>
|
|
<li>
|
|
<p>Statically known default collection type:
|
|
<code>node()*</code></p>
|
|
</li>
|
|
</ul>
|
|
<p>The dynamic context for evaluation of the target expression is
|
|
the same as the dynamic context for the <a href=
|
|
"#element-evaluate"><code>xsl:evaluate</code></a> instruction (in
|
|
particular, the <a title="focus" class="termref" href=
|
|
"#dt-focus">focus</a> is the same), except for the variable values:
|
|
this consists of the values bound to parameters defined in the
|
|
contained <a href=
|
|
"#element-with-param"><code>xsl:with-param</code></a> elements,
|
|
which are evaluated as described in <a href=
|
|
"#variable-values"><i>9.3 Values of Variables and
|
|
Parameters</i></a>.</p>
|
|
<p>An XSLT 2.1 <a title="processor" class="termref" href=
|
|
"#dt-processor">processor</a> will ignore any <a href=
|
|
"#element-fallback"><code>xsl:fallback</code></a> children of the
|
|
<a href="#element-evaluate"><code>xsl:evaluate</code></a>
|
|
instruction; they can be used to define the behavior of an XSLT 1.0
|
|
or XSLT 2.0 processor when this instruction is encountered.</p>
|
|
<p>The XPath expression is evaluated in the same <a href=
|
|
"http://www.w3.org/TR/xpath-functions/#execution-scope">execution
|
|
scope</a><sup><small>FO</small></sup> as the calling XSLT
|
|
transformation; this means that the results of <a href=
|
|
"http://www.w3.org/TR/xpath-functions/#stable">stable</a><sup><small>FO</small></sup>
|
|
functions such as <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-doc"><code>doc</code></a><sup><small>FO</small></sup>
|
|
or <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-current-dateTime"><code>
|
|
current-dateTime</code></a><sup><small>FO</small></sup> will be
|
|
consistent between the calling stylesheet and the called XPath
|
|
expression.</p>
|
|
<p>It is a <a title="non-recoverable dynamic error" class="termref"
|
|
href="#dt-nonrec-dynamic-error">non-recoverable dynamic error</a>
|
|
if evaluation of the XPath expression fails with a dynamic error.
|
|
The XPath-defined error code is used unchanged.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>Implementations wanting to avoid the cost of repeated
|
|
compilation of the same XPath expression should cache the compiled
|
|
form internally.</p>
|
|
</div>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e19291" id=
|
|
"d7e19291"></a>Example: Using a dynamic sort key</div>
|
|
<p>A common requirement is to sort a table on the value of an
|
|
expression which is selected at run-time, perhaps by supplying the
|
|
expression as a string-valued parameter to the stylesheet. Suppose
|
|
that such an expression is supplied to the parameter:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:param name="sortkey" as="xs:string" select="'@name'"/>
|
|
</pre></div>
|
|
<p>Then the data may be sorted as follows:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:sort>
|
|
<xsl:evaluate xpath="$sortkey" as="xs:string"/>
|
|
</xsl:sort>
|
|
</pre></div>
|
|
<p>Note the importance in this use case of caching the compiled
|
|
expression, since it is evaluated repeatedly, once for each item in
|
|
the list being sorted.</p>
|
|
</div>
|
|
<blockquote>
|
|
<p><b><a name="issue-evaluate-optional-feature" id=
|
|
"issue-evaluate-optional-feature">Issue 13
|
|
(evaluate-optional-feature)</a>:</b></p>
|
|
<p>The Working Group has not yet decided whether <a href=
|
|
"#element-evaluate"><code>xsl:evaluate</code></a> will be an
|
|
optional feature of the language, or whether all implementations
|
|
will be required to provide it.</p>
|
|
</blockquote>
|
|
</div>
|
|
</div>
|
|
<div class="div1">
|
|
<h2><a name="creating-new-nodes" id="creating-new-nodes"></a>11
|
|
<a href="#creating-new-nodes" style=
|
|
"text-decoration: none">Creating Nodes and Sequences</a></h2>
|
|
<p>This section describes instructions that directly create new
|
|
nodes, or sequences of nodes, atomic values, <span>and/or function
|
|
items</span>.</p>
|
|
<div class="div2">
|
|
<h3><a name="literal-result-element" id=
|
|
"literal-result-element"></a>11.1 <a href="#literal-result-element"
|
|
style="text-decoration: none">Literal Result Elements</a></h3>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-literal-result-element" id="dt-literal-result-element" title=
|
|
"literal result element"></a>In a <a title="sequence constructor"
|
|
class="termref" href="#dt-sequence-constructor">sequence
|
|
constructor</a>, an element in the <a title="stylesheet" class=
|
|
"termref" href="#dt-stylesheet">stylesheet</a> that does not belong
|
|
to the <a title="XSLT namespace" class="termref" href=
|
|
"#dt-xslt-namespace">XSLT namespace</a> and that is not an
|
|
<a title="extension instruction" class="termref" href=
|
|
"#dt-extension-instruction">extension instruction</a> (see <a href=
|
|
"#extension-instruction"><i>21.2 Extension Instructions</i></a>) is
|
|
classified as a <b>literal result element</b>.<span class=
|
|
"definition">]</span> A literal result element is evaluated to
|
|
construct a new element node with the same <a title=
|
|
"expanded-QName" class="termref" href=
|
|
"#dt-expanded-qname">expanded-QName</a> (that is, the same
|
|
namespace URI, local name, and namespace prefix). The result of
|
|
evaluating a literal result element is a node sequence containing
|
|
one element, the newly constructed element node.</p>
|
|
<p>The content of the element is a <a title="sequence constructor"
|
|
class="termref" href="#dt-sequence-constructor">sequence
|
|
constructor</a> (see <a href="#sequence-constructors"><i>5.7
|
|
Sequence Constructors</i></a>). The sequence obtained by evaluating
|
|
this sequence constructor, after prepending any attribute nodes
|
|
produced as described in <a href="#attributes-for-lres"><i>11.1.2
|
|
Attribute Nodes for Literal Result Elements</i></a> and namespace
|
|
nodes produced as described in <a href="#lre-namespaces"><i>11.1.3
|
|
Namespace Nodes for Literal Result Elements</i></a>, is used to
|
|
construct the content of the element, following the rules in
|
|
<a href="#constructing-complex-content"><i>5.7.1 Constructing
|
|
Complex Content</i></a></p>
|
|
<p>The base URI of the new element is copied from the base URI of
|
|
the literal result element in the stylesheet, unless the content of
|
|
the new element includes an <code>xml:base</code> attribute, in
|
|
which case the base URI of the new element is the value of that
|
|
attribute, resolved (if it is a relative URI
|
|
<span>reference</span>) against the base URI of the literal result
|
|
element in the stylesheet. (Note, however, that this is only
|
|
relevant when creating a parentless element. When the literal
|
|
result element is copied to form a child of an element or document
|
|
node, the base URI of the new copy is taken from that of its new
|
|
parent.)</p>
|
|
<div class="div3">
|
|
<h4><a name="setting-annotation-for-lre" id=
|
|
"setting-annotation-for-lre"></a>11.1.1 <a href=
|
|
"#setting-annotation-for-lre" style="text-decoration: none">Setting
|
|
the Type Annotation for Literal Result Elements</a></h4>
|
|
<p>The attributes <code>xsl:type</code> and
|
|
<code>xsl:validation</code> may be used on a literal result element
|
|
to invoke validation of the contents of the element against a type
|
|
definition or element declaration in a schema, and to determine the
|
|
<a title="type annotation" class="termref" href=
|
|
"#dt-annotation">type annotation</a> that the new element node will
|
|
carry. These attributes also affect the type annotation carried by
|
|
any elements and attributes that have the new element node as an
|
|
ancestor. These two attributes are both optional, and if one is
|
|
specified then the other <span class="verb">must</span> be
|
|
omitted.</p>
|
|
<p>The value of the <code>xsl:validation</code> attribute, if
|
|
present, must be one of the values <code>strict</code>,
|
|
<code>lax</code>, <code>preserve</code>, or <code>strip</code>. The
|
|
value of the <code>xsl:type</code> attribute, if present, must be a
|
|
<a title="QName" class="termref" href="#dt-qname">QName</a>
|
|
identifying a type definition that is present in the <a title=
|
|
"in-scope schema component" class="termref" href=
|
|
"#dt-in-scope-schema-component">in-scope schema components</a> for
|
|
the stylesheet. Neither attribute may be specified as an <a title=
|
|
"attribute value template" class="termref" href=
|
|
"#dt-attribute-value-template">attribute value template.</a> The
|
|
effect of these attributes is described in <a href=
|
|
"#validation"><i>22.2 Validation</i></a>.</p>
|
|
</div>
|
|
<div class="div3">
|
|
<h4><a name="attributes-for-lres" id=
|
|
"attributes-for-lres"></a>11.1.2 <a href="#attributes-for-lres"
|
|
style="text-decoration: none">Attribute Nodes for Literal Result
|
|
Elements</a></h4>
|
|
<p>Attribute nodes for a literal result element may be created by
|
|
including <a href=
|
|
"#element-attribute"><code>xsl:attribute</code></a> instructions
|
|
within the <a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a>. Additionally,
|
|
attribute nodes are created corresponding to the attributes of the
|
|
literal result element in the stylesheet, and as a result of
|
|
expanding the <code>xsl:use-attribute-sets</code> attribute of the
|
|
literal result element, if present.</p>
|
|
<p>The sequence that is used to construct the content of the
|
|
literal result element (as described in <a href=
|
|
"#constructing-complex-content"><i>5.7.1 Constructing Complex
|
|
Content</i></a>) is the concatenation of the following four
|
|
sequences, in order:</p>
|
|
<ol class="enumar">
|
|
<li>
|
|
<p>The sequence of namespace nodes produced as described in
|
|
<a href="#lre-namespaces"><i>11.1.3 Namespace Nodes for Literal
|
|
Result Elements</i></a>.</p>
|
|
</li>
|
|
<li>
|
|
<p>The sequence of attribute nodes produced by expanding the
|
|
<code>xsl:use-attribute-sets</code> attribute (if present)
|
|
following the rules given in <a href="#attribute-sets"><i>10.2
|
|
Named Attribute Sets</i></a></p>
|
|
</li>
|
|
<li>
|
|
<p>The attributes produced by processing the attributes of the
|
|
literal result element itself, other than attributes in the
|
|
<a title="" class="termref" href="#xslt-namespace">XSLT
|
|
namespace</a>. The way these are processed is described below.</p>
|
|
</li>
|
|
<li>
|
|
<p>The sequence produced by evaluating the contained <a title=
|
|
"sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a>, if the element
|
|
is not empty.</p>
|
|
</li>
|
|
</ol>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>The significance of this order is that an attribute produced by
|
|
an <code>xsl:attribute</code>, <a href=
|
|
"#element-copy"><code>xsl:copy</code></a>, or <a href=
|
|
"#element-copy-of"><code>xsl:copy-of</code></a> instruction in the
|
|
content of the literal result element takes precedence over an
|
|
attribute produced by expanding an attribute of the literal result
|
|
element itself, which in turn takes precedence over an attribute
|
|
produced by expanding the <code>xsl:use-attribute-sets</code>
|
|
attribute. This is because of the rules in <a href=
|
|
"#constructing-complex-content"><i>5.7.1 Constructing Complex
|
|
Content</i></a>, which specify that when two or more attributes in
|
|
the sequence have the same name, all but the last of the duplicates
|
|
are discarded.</p>
|
|
<p>Although the above rules place namespace nodes before
|
|
attributes, this is not strictly necessary, because the rules in
|
|
<a href="#constructing-complex-content"><i>5.7.1 Constructing
|
|
Complex Content</i></a> allow the namespaces and attributes to
|
|
appear in any order so long as both come before other kinds of
|
|
node. The order of namespace nodes and attribute nodes in the
|
|
sequence has no effect on the relative position of the nodes in
|
|
document order once they are added to a tree.</p>
|
|
</div>
|
|
<p>Each attribute of the literal result element, other than an
|
|
attribute in the <a title="XSLT namespace" class="termref" href=
|
|
"#dt-xslt-namespace">XSLT namespace</a>, is processed to produce an
|
|
attribute for the element in the <a title="result tree" class=
|
|
"termref" href="#dt-result-tree">result tree</a>.</p>
|
|
<p>The value of such an attribute is interpreted as an <a title=
|
|
"attribute value template" class="termref" href=
|
|
"#dt-attribute-value-template">attribute value template</a>: it can
|
|
therefore contain <a title="expression" class="termref" href=
|
|
"#dt-expression">expressions</a> contained in curly brackets
|
|
(<code>{}</code>). The new attribute node will have the same
|
|
<a title="expanded-QName" class="termref" href=
|
|
"#dt-expanded-qname">expanded-QName</a> (that is, the same
|
|
namespace URI, local name, and namespace prefix) as the attribute
|
|
in the stylesheet tree, and its <a title="string value" class=
|
|
"termref" href="#dt-string-value">string value</a> will be the same
|
|
as the <a title="effective value" class="termref" href=
|
|
"#dt-effective-value">effective value</a> of the attribute in the
|
|
stylesheet tree. The <a title="type annotation" class="termref"
|
|
href="#dt-annotation">type annotation</a> on the attribute will
|
|
initially be <code>xs:untypedAtomic</code>, and the <a title=
|
|
"typed value" class="termref" href="#dt-typed-value">typed
|
|
value</a> of the attribute node will be the same as its <a title=
|
|
"string value" class="termref" href="#dt-string-value">string
|
|
value</a>.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>The eventual <a title="type annotation" class="termref" href=
|
|
"#dt-annotation">type annotation</a> of the attribute in the
|
|
<a title="result tree" class="termref" href=
|
|
"#dt-result-tree">result tree</a> depends on the
|
|
<code>xsl:validation</code> and <code>xsl:type</code> attributes of
|
|
the parent literal result element, and on the instructions used to
|
|
create its ancestor elements. If the <code>xsl:validation</code>
|
|
attribute is set to <code>preserve</code> or <code>strip</code>,
|
|
the type annotation will be <code>xs:untypedAtomic</code>, and the
|
|
<a title="typed value" class="termref" href="#dt-typed-value">typed
|
|
value</a> of the attribute node will be the same as its <a title=
|
|
"string value" class="termref" href="#dt-string-value">string
|
|
value</a>. If the <code>xsl:validation</code> attribute is set to
|
|
<code>strict</code> or <code>lax</code>, or if the
|
|
<code>xsl:type</code> attribute is used, the type annotation on the
|
|
attribute will be set as a result of the schema validation process
|
|
applied to the parent element. If neither attribute is present, the
|
|
type annotation on the attribute will be
|
|
<code>xs:untypedAtomic</code>.</p>
|
|
</div>
|
|
<p>If the name of a constructed attribute is <code>xml:id</code>,
|
|
the processor must perform attribute value normalization by
|
|
effectively applying the <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-normalize-space"><code>
|
|
normalize-space</code></a><sup><small>FO</small></sup> function to
|
|
the value of the attribute, and the resulting attribute node must
|
|
be given the <code>is-id</code> property.</p>
|
|
<p><a name="err-XTRE0795" id="err-XTRE0795"><span class=
|
|
"error">[ERR XTRE0795]</span></a> It is a <a title=
|
|
"recoverable error" class="termref" href=
|
|
"#dt-recoverable-error">recoverable dynamic error</a> if the name
|
|
of a constructed attribute is <code>xml:space</code> and the value
|
|
is not either <code>default</code> or <code>preserve</code>. The
|
|
<a title="optional recovery action" class="termref" href=
|
|
"#dt-optional-recovery-action">optional recovery action</a> is to
|
|
construct the attribute with the value as requested. . This applies
|
|
whether the attribute is constructed using a literal result
|
|
element, or by using the <a href=
|
|
"#element-attribute"><code>xsl:attribute</code></a>, <a href=
|
|
"#element-copy"><code>xsl:copy</code></a>, or <a href=
|
|
"#element-copy-of"><code>xsl:copy-of</code></a> instructions.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>The <code>xml:base</code>, <code>xml:lang</code>,
|
|
<code>xml:space</code>, and <code>xml:id</code> 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 <a title="result tree" class="termref"
|
|
href="#dt-result-tree">result tree</a> in the same way as any other
|
|
attribute. In addition, they have their standard meaning as defined
|
|
in the core XML specifications. Thus, an <code>xml:base</code>
|
|
attribute in the stylesheet affects the base URI of the element on
|
|
which it appears, and an <code>xml:space</code> attribute affects
|
|
the interpretation of <a title="whitespace text node" class=
|
|
"termref" href="#dt-whitespace-text-node">whitespace text nodes</a>
|
|
within that element. One consequence of this is that it is
|
|
inadvisable to write these attributes as attribute value templates:
|
|
although an XSLT processor will understand this notation, the XML
|
|
parser will not. See also <a href="#namespace-aliasing"><i>11.1.4
|
|
Namespace Aliasing</i></a> which describes how to use <a href=
|
|
"#element-namespace-alias"><code>xsl:namespace-alias</code></a>
|
|
with these attributes.</p>
|
|
<p>The same is true of the schema-defined attributes
|
|
<code>xsi:type</code>, <code>xsi:nil</code>,
|
|
<code>xsi:noNamespaceSchemaLocation</code>, and
|
|
<code>xsi:schemaLocation</code>. If the stylesheet is processed by
|
|
a schema processor, these attributes will be recognized and
|
|
interpreted by the schema processor, but in addition the XSLT
|
|
processor treats them like any other attribute on a literal result
|
|
element: that is, their <a title="effective value" class="termref"
|
|
href="#dt-effective-value">effective value</a> (after expanding
|
|
<a title="attribute value template" class="termref" href=
|
|
"#dt-attribute-value-template">attribute value templates</a>) is
|
|
copied to the result tree in the same way as any other attribute.
|
|
If the <a title="result tree" class="termref" href=
|
|
"#dt-result-tree">result tree</a> is validated, the copied
|
|
attributes will again be recognized and interpreted by the schema
|
|
processor.</p>
|
|
<p>None of these attributes will be generated in the <a title=
|
|
"result tree" class="termref" href="#dt-result-tree">result
|
|
tree</a> unless the stylesheet writes them to the result tree
|
|
explicitly, in the same way as any other attribute.</p>
|
|
</div>
|
|
<p><a name="err-XTSE0805" id="err-XTSE0805"><span class=
|
|
"error">[ERR XTSE0805]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> if an
|
|
attribute on a literal result element is in the <a title=
|
|
"XSLT namespace" class="termref" href="#dt-xslt-namespace">XSLT
|
|
namespace</a>, unless it is one of the attributes explicitly
|
|
defined in this specification.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>If there is a need to create attributes in the XSLT namespace,
|
|
this can be achieved using <a href=
|
|
"#element-attribute"><code>xsl:attribute</code></a>, or by means of
|
|
the <a href=
|
|
"#element-namespace-alias"><code>xsl:namespace-alias</code></a>
|
|
declaration.</p>
|
|
</div>
|
|
</div>
|
|
<div class="div3">
|
|
<h4><a name="lre-namespaces" id="lre-namespaces"></a>11.1.3
|
|
<a href="#lre-namespaces" style="text-decoration: none">Namespace
|
|
Nodes for Literal Result Elements</a></h4>
|
|
<p>The created element node will have a copy of the namespace nodes
|
|
that were present on the element node in the stylesheet tree with
|
|
the exception of any namespace node whose <a title="string value"
|
|
class="termref" href="#dt-string-value">string value</a> is
|
|
designated as an <b>excluded namespace</b>. Special considerations
|
|
apply to aliased namespaces: see <a href=
|
|
"#namespace-aliasing"><i>11.1.4 Namespace Aliasing</i></a></p>
|
|
<p>The following namespaces are designated as excluded
|
|
namespaces:</p>
|
|
<ul>
|
|
<li>
|
|
<p>The <a title="XSLT namespace" class="termref" href=
|
|
"#dt-xslt-namespace">XSLT namespace</a> URI
|
|
(<code>http://www.w3.org/1999/XSL/Transform</code>)</p>
|
|
</li>
|
|
<li>
|
|
<p>A namespace URI declared as an extension namespace (see <a href=
|
|
"#extension-instruction"><i>21.2 Extension
|
|
Instructions</i></a>)</p>
|
|
</li>
|
|
<li>
|
|
<p>A namespace URI designated by using an
|
|
<code>[xsl:]exclude-result-prefixes</code> attribute either on the
|
|
literal result element itself or on an ancestor element. The
|
|
attribute <span class="verb">must</span> be in the XSLT namespace
|
|
only if its parent element is <em>not</em> in the XSLT
|
|
namespace.</p>
|
|
<p>The value of the attribute is either <code>#all</code>, or a
|
|
whitespace-separated list of tokens, each of which is either a
|
|
namespace prefix or <code>#default</code>. The namespace bound to
|
|
each of the prefixes is designated as an excluded namespace.</p>
|
|
<p><a name="err-XTSE0808" id="err-XTSE0808"><span class=
|
|
"error">[ERR XTSE0808]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> if a
|
|
namespace prefix is used within the
|
|
<code>[xsl:]exclude-result-prefixes</code> attribute and there is
|
|
no namespace binding in scope for that prefix.</p>
|
|
<p>The default namespace of the parent element of the
|
|
<code>[xsl:]exclude-result-prefixes</code> attribute (see <a href=
|
|
"http://www.w3.org/TR/xpath-datamodel-11/#ElementNode">Section 6.2
|
|
Element Nodes</a><sup><small>DM11</small></sup>) may be designated
|
|
as an excluded namespace by including <code>#default</code> in the
|
|
list of namespace prefixes.</p>
|
|
<p><a name="err-XTSE0809" id="err-XTSE0809"><span class=
|
|
"error">[ERR XTSE0809]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> if the
|
|
value <code>#default</code> is used within the
|
|
<code>[xsl:]exclude-result-prefixes</code> attribute and the parent
|
|
element of the <code>[xsl:]exclude-result-prefixes</code> attribute
|
|
has no default namespace.</p>
|
|
<p>The value <code>#all</code> indicates that all namespaces that
|
|
are in scope for the stylesheet element that is the parent of the
|
|
<code>[xsl:]exclude-result-prefixes</code> attribute are designated
|
|
as excluded namespaces.</p>
|
|
<p>The designation of a namespace as an excluded namespace is
|
|
effective within the subtree of the stylesheet module rooted at the
|
|
element bearing the <code>[xsl:]exclude-result-prefixes</code>
|
|
attribute; a subtree rooted at an <a href=
|
|
"#element-stylesheet"><code>xsl:stylesheet</code></a> element does
|
|
not include any stylesheet modules imported or included by children
|
|
of that <a href=
|
|
"#element-stylesheet"><code>xsl:stylesheet</code></a> element.</p>
|
|
</li>
|
|
</ul>
|
|
<p>The excluded namespaces, as described above, <em>only</em>
|
|
affect namespace nodes copied from the stylesheet when processing a
|
|
literal result element. There is no guarantee that an excluded
|
|
namespace will not appear on the <a title="result tree" class=
|
|
"termref" href="#dt-result-tree">result tree</a> for some other
|
|
reason. Namespace nodes are also written to the result tree as part
|
|
of the process of namespace fixup (see <a href=
|
|
"#namespace-fixup"><i>5.7.3 Namespace Fixup</i></a>), or as the
|
|
result of instructions such as <a href=
|
|
"#element-copy"><code>xsl:copy</code></a> and <a href=
|
|
"#element-element"><code>xsl:element</code></a>.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>When a stylesheet uses a namespace declaration only for the
|
|
purposes of addressing a <a title="source tree" class="termref"
|
|
href="#dt-source-tree">source tree</a>, specifying the prefix in
|
|
the <code>[xsl:]exclude-result-prefixes</code> attribute will avoid
|
|
superfluous namespace declarations in the serialized <a title=
|
|
"result tree" class="termref" href="#dt-result-tree">result
|
|
tree</a>. The attribute is also useful to prevent namespaces used
|
|
solely for the naming of stylesheet functions or extension
|
|
functions from appearing in the serialized result tree.</p>
|
|
</div>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e19838" id=
|
|
"d7e19838"></a>Example: Excluding Namespaces from the Result
|
|
Tree</div>
|
|
<p>For example, consider the following stylesheet:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:stylesheet xsl:version="1.0"
|
|
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
|
|
xmlns:a="a.uri"
|
|
xmlns:b="b.uri">
|
|
exclude-result-prefixes="#all">
|
|
|
|
<xsl:template match="/">
|
|
<foo xmlns:c="c.uri" xmlns:d="d.uri" xmlns:a2="a.uri"
|
|
xsl:exclude-result-prefixes="c"/>
|
|
</xsl:template>
|
|
|
|
</xsl:stylesheet>
|
|
</pre></div>
|
|
<p>The result of this stylesheet will be:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<foo xmlns:d="d.uri"/>
|
|
</pre></div>
|
|
<p>The namespaces <code>a.uri</code> and <code>b.uri</code> are
|
|
excluded by virtue of the <code>exclude-result-prefixes</code>
|
|
attribute on the <a href=
|
|
"#element-stylesheet"><code>xsl:stylesheet</code></a> element, and
|
|
the namespace <code>c.uri</code> is excluded by virtue of the
|
|
<code>xsl:exclude-result-prefixes</code> attribute on the
|
|
<code>foo</code> element. The setting <code>#all</code> does not
|
|
affect the namespace <code>d.uri</code> because <code>d.uri</code>
|
|
is not an in-scope namespace for the <a href=
|
|
"#element-stylesheet"><code>xsl:stylesheet</code></a> element. The
|
|
element in the <a title="result tree" class="termref" href=
|
|
"#dt-result-tree">result tree</a> does not have a namespace node
|
|
corresponding to <code>xmlns:a2="a.uri"</code> because the effect
|
|
of <code>exclude-result-prefixes</code> is to designate the
|
|
namespace URI <code>a.uri</code> as an excluded namespace,
|
|
irrespective of how many prefixes are bound to this namespace
|
|
URI.</p>
|
|
<p>If the stylesheet is changed so that the literal result element
|
|
has an attribute <code>b:bar="3"</code>, then the element in the
|
|
<a title="result tree" class="termref" href=
|
|
"#dt-result-tree">result tree</a> will typically have a namespace
|
|
declaration <code>xmlns:b="b.uri"</code> (the processor may choose
|
|
a different namespace prefix if this is necessary to avoid
|
|
conflicts). The <code>exclude-result-prefixes</code> attribute
|
|
makes <code>b.uri</code> an excluded namespace, so the namespace
|
|
node is not automatically copied from the stylesheet, but the
|
|
presence of an attribute whose name is in the namespace
|
|
<code>b.uri</code> forces the namespace fixup process (see <a href=
|
|
"#namespace-fixup"><i>5.7.3 Namespace Fixup</i></a>) to introduce a
|
|
namespace node for this namespace.</p>
|
|
</div>
|
|
<p>A literal result element may have an optional
|
|
<code>xsl:inherit-namespaces</code> attribute, with the value
|
|
<code>yes</code> or <code>no</code>. The default value is
|
|
<code>yes</code>. If the value is set to <code>yes</code>, or is
|
|
omitted, then the namespace nodes created for the newly constructed
|
|
element are copied to the children and descendants of the newly
|
|
constructed element, as described in <a href=
|
|
"#constructing-complex-content"><i>5.7.1 Constructing Complex
|
|
Content</i></a>. If the value is set to <code>no</code>, then these
|
|
namespace nodes are not automatically copied to the children. This
|
|
may result in namespace undeclarations (such as
|
|
<code>xmlns=""</code> or, in the case of XML 1.1,
|
|
<code>xmlns:p=""</code>) appearing on the child elements when a
|
|
<a title="final result tree" class="termref" href=
|
|
"#dt-final-result-tree">final result tree</a> is serialized.</p>
|
|
</div>
|
|
<div class="div3">
|
|
<h4><a name="namespace-aliasing" id="namespace-aliasing"></a>11.1.4
|
|
<a href="#namespace-aliasing" style=
|
|
"text-decoration: none">Namespace Aliasing</a></h4>
|
|
<p>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.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-literal-namespace-uri" id="dt-literal-namespace-uri" title=
|
|
"literal namespace URI"></a>A namespace URI in the stylesheet tree
|
|
that is being used to specify a namespace URI in the <a title=
|
|
"result tree" class="termref" href="#dt-result-tree">result
|
|
tree</a> is called a <b>literal namespace URI</b>.<span class=
|
|
"definition">]</span></p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-target-namespace-uri" id="dt-target-namespace-uri" title=
|
|
"target namespace URI"></a>The namespace URI that is to be used in
|
|
the <a title="result tree" class="termref" href=
|
|
"#dt-result-tree">result tree</a> as a substitute for a <a title=
|
|
"literal namespace URI" class="termref" href=
|
|
"#dt-literal-namespace-uri">literal namespace URI</a> is called the
|
|
<b>target namespace URI</b>.<span class="definition">]</span></p>
|
|
<p>Either of the <a title="literal namespace URI" class="termref"
|
|
href="#dt-literal-namespace-uri">literal namespace URI</a> or the
|
|
<a title="target namespace URI" class="termref" href=
|
|
"#dt-target-namespace-uri">target namespace URI</a> can be
|
|
<em>null</em>: this is treated as a reference to the set of names
|
|
that are in no namespace.</p>
|
|
<p class="element-syntax"><a name="element-namespace-alias" id=
|
|
"element-namespace-alias"></a><code><!-- Category: declaration
|
|
--><br />
|
|
<xsl:namespace-alias<br />
|
|
  <b>stylesheet-prefix</b> = <var>prefix</var> |
|
|
"#default"<br />
|
|
  <b>result-prefix</b> = <var>prefix</var> |
|
|
"#default" /></code></p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-alias" id="dt-alias" title="alias"></a>A stylesheet can use the
|
|
<a href=
|
|
"#element-namespace-alias"><code>xsl:namespace-alias</code></a>
|
|
element to declare that a <a title="literal namespace URI" class=
|
|
"termref" href="#dt-literal-namespace-uri">literal namespace
|
|
URI</a> is being used as an <b>alias</b> for a <a title=
|
|
"target namespace URI" class="termref" href=
|
|
"#dt-target-namespace-uri">target namespace URI</a>.<span class=
|
|
"definition">]</span></p>
|
|
<p>The effect is that when names in the namespace identified by the
|
|
<a title="literal namespace URI" class="termref" href=
|
|
"#dt-literal-namespace-uri">literal namespace URI</a> are copied to
|
|
the <a title="result tree" class="termref" href=
|
|
"#dt-result-tree">result tree</a>, the namespace URI in the result
|
|
tree will be the <a title="target namespace URI" class="termref"
|
|
href="#dt-target-namespace-uri">target namespace URI</a>, instead
|
|
of the literal namespace URI. This applies to:</p>
|
|
<ul>
|
|
<li>
|
|
<p>the namespace URI in the <a title="expanded-QName" class=
|
|
"termref" href="#dt-expanded-qname">expanded-QName</a> of a literal
|
|
result element in the stylesheet</p>
|
|
</li>
|
|
<li>
|
|
<p>the namespace URI in the <a title="expanded-QName" class=
|
|
"termref" href="#dt-expanded-qname">expanded-QName</a> of an
|
|
attribute specified on a literal result element in the
|
|
stylesheet</p>
|
|
</li>
|
|
</ul>
|
|
<p>Where namespace aliasing changes the namespace URI part of the
|
|
<a title="expanded-QName" class="termref" href=
|
|
"#dt-expanded-qname">expanded-QName</a> containing the name of an
|
|
element or attribute node, the namespace prefix in that
|
|
expanded-QName is replaced by the prefix indicated by the
|
|
<code>result-prefix</code> attribute of the <a href=
|
|
"#element-namespace-alias"><code>xsl:namespace-alias</code></a>
|
|
declaration.</p>
|
|
<p>The <a href=
|
|
"#element-namespace-alias"><code>xsl:namespace-alias</code></a>
|
|
element declares that the namespace URI bound to the prefix
|
|
specified by the <code>stylesheet-prefix</code> is the <a title=
|
|
"literal namespace URI" class="termref" href=
|
|
"#dt-literal-namespace-uri">literal namespace URI</a>, and the
|
|
namespace URI bound to the prefix specified by the
|
|
<code>result-prefix</code> attribute is the <a title=
|
|
"target namespace URI" class="termref" href=
|
|
"#dt-target-namespace-uri">target namespace URI</a>. Thus, the
|
|
<code>stylesheet-prefix</code> attribute specifies the namespace
|
|
URI that will appear in the stylesheet, and the
|
|
<code>result-prefix</code> attribute specifies the corresponding
|
|
namespace URI that will appear in the <a title="result tree" class=
|
|
"termref" href="#dt-result-tree">result tree</a>.</p>
|
|
<p>The default namespace (as declared by <code>xmlns</code>) may be
|
|
specified by using <code>#default</code> instead of a prefix. If no
|
|
default namespace is in force, specifying <code>#default</code>
|
|
denotes the null namespace URI. This allows elements that are in no
|
|
namespace in the stylesheet to acquire a namespace in the result
|
|
document, or vice versa.</p>
|
|
<p>If a <a title="literal namespace URI" class="termref" href=
|
|
"#dt-literal-namespace-uri">literal namespace URI</a> is declared
|
|
to be an alias for multiple different <a title=
|
|
"literal namespace URI" class="termref" href=
|
|
"#dt-literal-namespace-uri">target namespace URIs</a>, then the
|
|
declaration with the highest <a title="import precedence" class=
|
|
"termref" href="#dt-import-precedence">import precedence</a> is
|
|
used.</p>
|
|
<p><a name="err-XTSE0810" id="err-XTSE0810"><span class=
|
|
"error">[ERR XTSE0810]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> if there
|
|
is more than one such declaration with the same <a title=
|
|
"literal namespace URI" class="termref" href=
|
|
"#dt-literal-namespace-uri">literal namespace URI</a> and the same
|
|
<a title="import precedence" class="termref" href=
|
|
"#dt-import-precedence">import precedence</a> and different values
|
|
for the <a title="target namespace URI" class="termref" href=
|
|
"#dt-target-namespace-uri">target namespace URI</a>, unless there
|
|
is also an <a href=
|
|
"#element-namespace-alias"><code>xsl:namespace-alias</code></a>
|
|
declaration with the same <a title="literal namespace URI" class=
|
|
"termref" href="#dt-literal-namespace-uri">literal namespace
|
|
URI</a> and a higher import precedence.</p>
|
|
<p><a name="err-XTSE0812" id="err-XTSE0812"><span class=
|
|
"error">[ERR XTSE0812]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> if a value
|
|
other than <code>#default</code> is specified for either the
|
|
<code>stylesheet-prefix</code> or the <code>result-prefix</code>
|
|
attributes of the <a href=
|
|
"#element-namespace-alias"><code>xsl:namespace-alias</code></a>
|
|
element when there is no in-scope binding for that namespace
|
|
prefix.</p>
|
|
<p>When a literal result element is processed, its namespace nodes
|
|
are handled as follows:</p>
|
|
<ul>
|
|
<li>
|
|
<p>A namespace node whose string value is a <a title=
|
|
"literal namespace URI" class="termref" href=
|
|
"#dt-literal-namespace-uri">literal namespace URI</a> is not copied
|
|
to the <a title="result tree" class="termref" href=
|
|
"#dt-result-tree">result tree</a>.</p>
|
|
</li>
|
|
<li>
|
|
<p>A namespace node whose string value is a <a title=
|
|
"target namespace URI" class="termref" href=
|
|
"#dt-target-namespace-uri">target namespace URI</a> is copied to
|
|
the <a title="result tree" class="termref" href=
|
|
"#dt-result-tree">result tree</a>, whether or not the URI
|
|
identifies an excluded namespace.</p>
|
|
</li>
|
|
</ul>
|
|
<p>In the event that the same URI is used as a <a title=
|
|
"literal namespace URI" class="termref" href=
|
|
"#dt-literal-namespace-uri">literal namespace URI</a> and a
|
|
<a title="target namespace URI" class="termref" href=
|
|
"#dt-target-namespace-uri">target namespace URI</a>, the second of
|
|
these rules takes precedence.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>These rules achieve the effect that the element generated from
|
|
the literal result element will have an in-scope namespace node
|
|
that binds the <code>result-prefix</code> to the <a title=
|
|
"target namespace URI" class="termref" href=
|
|
"#dt-target-namespace-uri">target namespace URI</a>, provided that
|
|
the namespace declaration associating this prefix with this URI is
|
|
in scope for both the <a href=
|
|
"#element-namespace-alias"><code>xsl:namespace-alias</code></a>
|
|
instruction and for the literal result element. Conversely, the
|
|
<code>stylesheet-prefix</code> and the <a title=
|
|
"literal namespace URI" class="termref" href=
|
|
"#dt-literal-namespace-uri">literal namespace URI</a> will not
|
|
normally appear in the <a title="result tree" class="termref" href=
|
|
"#dt-result-tree">result tree</a>.</p>
|
|
</div>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e20211" id=
|
|
"d7e20211"></a>Example: Using <code>xsl:namespace-alias</code> to
|
|
Generate a Stylesheet</div>
|
|
<p>When literal result elements are being used to create element,
|
|
attribute, or namespace nodes that use the <a title=
|
|
"XSLT namespace" class="termref" href="#dt-xslt-namespace">XSLT
|
|
namespace</a> URI, the stylesheet may use an alias.</p>
|
|
<p>For example, the stylesheet</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:stylesheet
|
|
version="2.1"
|
|
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
|
|
xmlns:fo="http://www.w3.org/1999/XSL/Format"
|
|
xmlns:axsl="file://namespace.alias">
|
|
|
|
<xsl:namespace-alias stylesheet-prefix="axsl" result-prefix="xsl"/>
|
|
|
|
<xsl:template match="/">
|
|
<axsl:stylesheet version="2.1">
|
|
<xsl:apply-templates/>
|
|
</axsl:stylesheet>
|
|
</xsl:template>
|
|
|
|
<xsl:template match="elements">
|
|
<axsl:template match="/">
|
|
<axsl:comment select="system-property('xsl:version')"/>
|
|
<axsl:apply-templates/>
|
|
</axsl:template>
|
|
</xsl:template>
|
|
|
|
<xsl:template match="block">
|
|
<axsl:template match="{.}">
|
|
<fo:block><axsl:apply-templates/></fo:block>
|
|
</axsl:template>
|
|
</xsl:template>
|
|
|
|
</xsl:stylesheet>
|
|
</pre></div>
|
|
<p>will generate an XSLT stylesheet from a document of the
|
|
form:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<elements>
|
|
<block>p</block>
|
|
<block>h1</block>
|
|
<block>h2</block>
|
|
<block>h3</block>
|
|
<block>h4</block>
|
|
</elements>
|
|
</pre></div>
|
|
<p>The output of the transformation will be a stylesheet such as
|
|
the following. Whitespace has been added for clarity. Note that an
|
|
implementation may output different namespace prefixes from those
|
|
appearing in this example; however, the rules guarantee that there
|
|
will be a namespace node that binds the prefix <code>xsl</code> to
|
|
the URI <code>http://www.w3.org/1999/XSL/Transform</code>, which
|
|
makes it safe to use the QName <code>xsl:version</code> in the
|
|
content of the generated stylesheet.</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:stylesheet
|
|
version="2.1"
|
|
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
|
|
xmlns:fo="http://www.w3.org/1999/XSL/Format">
|
|
|
|
<xsl:template match="/">
|
|
<xsl:comment select="system-property('xsl:version')"/>
|
|
<xsl:apply-templates/>
|
|
</xsl:template>
|
|
|
|
<xsl:template match="p">
|
|
<fo:block><xsl:apply-templates/></fo:block>
|
|
</xsl:template>
|
|
|
|
<xsl:template match="h1">
|
|
<fo:block><xsl:apply-templates/></fo:block>
|
|
</xsl:template>
|
|
|
|
<xsl:template match="h2">
|
|
<fo:block><xsl:apply-templates/></fo:block>
|
|
</xsl:template>
|
|
|
|
<xsl:template match="h3">
|
|
<fo:block><xsl:apply-templates/></fo:block>
|
|
</xsl:template>
|
|
|
|
<xsl:template match="h4">
|
|
<fo:block><xsl:apply-templates/></fo:block>
|
|
</xsl:template>
|
|
|
|
</xsl:stylesheet>
|
|
</pre></div>
|
|
</div>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>It may be necessary also to use aliases for namespaces other
|
|
than the XSLT namespace URI. For example, it can be useful to
|
|
define an alias for the namespace
|
|
<code>http://www.w3.org/2001/XMLSchema-instance</code>, so that the
|
|
stylesheet can use the attributes <code>xsi:type</code>,
|
|
<code>xsi:nil</code>, and <code>xsi:schemaLocation</code> on a
|
|
literal result element, without running the risk that a schema
|
|
processor will interpret these as applying to the stylesheet
|
|
itself. Equally, literal result elements belonging to a namespace
|
|
dealing with digital signatures might cause XSLT stylesheets to be
|
|
mishandled by general-purpose security software; using an alias for
|
|
the namespace would avoid the possibility of such mishandling.</p>
|
|
</div>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e20258" id=
|
|
"d7e20258"></a>Example: Aliasing the XML Namespace</div>
|
|
<p>It is possible to define an alias for the XML namespace.</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:stylesheet xmlns:axml="http://www.example.com/alias-xml"
|
|
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
|
|
version="2.1">
|
|
|
|
<xsl:namespace-alias stylesheet-prefix="axml" result-prefix="xml"/>
|
|
|
|
<xsl:template match="/">
|
|
<name axml:space="preserve">
|
|
<first>James</first>
|
|
<xsl:text> </xsl:text>
|
|
<last>Clark</last>
|
|
</name>
|
|
</xsl:template>
|
|
|
|
</xsl:stylesheet>
|
|
</pre></div>
|
|
<p>produces the output:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<name xml:space="preserve"><first>James</first> <last>Clark</last></name>
|
|
</pre></div>
|
|
<p>This allows an <code>xml:space</code> attribute to be generated
|
|
in the output without affecting the way the stylesheet is parsed.
|
|
The same technique can be used for other attributes such as
|
|
<code>xml:lang</code>, <code>xml:base</code>, and
|
|
<code>xml:id</code>.</p>
|
|
</div>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>Namespace aliasing is only necessary when literal result
|
|
elements are used. The problem of reserved namespaces does not
|
|
arise when using <a href=
|
|
"#element-element"><code>xsl:element</code></a> and <a href=
|
|
"#element-attribute"><code>xsl:attribute</code></a> to construct
|
|
the <a title="result tree" class="termref" href=
|
|
"#dt-result-tree">result tree</a>. Therefore, as an alternative to
|
|
using <a href=
|
|
"#element-namespace-alias"><code>xsl:namespace-alias</code></a>, it
|
|
is always possible to achieve the desired effect by replacing
|
|
literal result elements with <a href=
|
|
"#element-element"><code>xsl:element</code></a> and <a href=
|
|
"#element-attribute"><code>xsl:attribute</code></a>
|
|
instructions.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="xsl-element" id="xsl-element"></a>11.2 <a href=
|
|
"#xsl-element" style="text-decoration: none">Creating Element Nodes
|
|
Using</a> <code>xsl:element</code> <a href="#xsl-element" style=
|
|
"text-decoration: none"></a></h3>
|
|
<p class="element-syntax"><a name="element-element" id=
|
|
"element-element"></a><code><!-- Category: instruction
|
|
--><br />
|
|
<xsl:element<br />
|
|
  <b>name</b> = { <var>qname</var> }<br />
|
|
  namespace? = { <var>uri-reference</var> }<br />
|
|
  inherit-namespaces? = "yes" | "no"<br />
|
|
  use-attribute-sets? = <var>qnames</var><br />
|
|
  type? = <var>qname</var><br />
|
|
  validation? = "strict" | "lax" | "preserve" |
|
|
"strip" ><br />
|
|
  <!-- Content: <var>sequence-constructor</var>
|
|
--><br />
|
|
</xsl:element></code></p>
|
|
<p>The <a href="#element-element"><code>xsl:element</code></a>
|
|
instruction allows an element to be created with a computed name.
|
|
The <a title="expanded-QName" class="termref" href=
|
|
"#dt-expanded-qname">expanded-QName</a> of the element to be
|
|
created is specified by a <span class="verb">required</span>
|
|
<code>name</code> attribute and an optional <code>namespace</code>
|
|
attribute.</p>
|
|
<p>The content of the <a href=
|
|
"#element-element"><code>xsl:element</code></a> instruction is a
|
|
<a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> for the
|
|
children, attributes, and namespaces of the created element. The
|
|
sequence obtained by evaluating this sequence constructor (see
|
|
<a href="#sequence-constructors"><i>5.7 Sequence
|
|
Constructors</i></a>) is used to construct the content of the
|
|
element, as described in <a href=
|
|
"#constructing-complex-content"><i>5.7.1 Constructing Complex
|
|
Content</i></a>.</p>
|
|
<p>The <a href="#element-element"><code>xsl:element</code></a>
|
|
element may have a <code>use-attribute-sets</code> attribute, whose
|
|
value is a whitespace-separated list of QNames that identify
|
|
<a href="#element-attribute-set"><code>xsl:attribute-set</code></a>
|
|
declarations. If this attribute is present, it is expanded as
|
|
described in <a href="#attribute-sets"><i>10.2 Named Attribute
|
|
Sets</i></a> to produce a sequence of attribute nodes. This
|
|
sequence is prepended to the sequence produced as a result of
|
|
evaluating the <a title="sequence constructor" class="termref"
|
|
href="#dt-sequence-constructor">sequence constructor</a>, as
|
|
described in <a href="#constructing-complex-content"><i>5.7.1
|
|
Constructing Complex Content</i></a>.</p>
|
|
<p>The result of evaluating the <a href=
|
|
"#element-element"><code>xsl:element</code></a> instruction, except
|
|
in error cases, is the newly constructed element node.</p>
|
|
<p>The <code>name</code> attribute is interpreted as an <a title=
|
|
"attribute value template" class="termref" href=
|
|
"#dt-attribute-value-template">attribute value template</a>, whose
|
|
<a title="effective value" class="termref" href=
|
|
"#dt-effective-value">effective value</a> <span class=
|
|
"verb">must</span> be a <a title="lexical QName" class="termref"
|
|
href="#dt-lexical-qname">lexical QName</a>.</p>
|
|
<p><a name="err-XTDE0820" id="err-XTDE0820"><span class=
|
|
"error">[ERR XTDE0820]</span></a> It is a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> if the
|
|
<a title="effective value" class="termref" href=
|
|
"#dt-effective-value">effective value</a> of the <code>name</code>
|
|
attribute is not a <a title="lexical QName" class="termref" href=
|
|
"#dt-lexical-qname">lexical QName</a>.</p>
|
|
<p><a name="err-XTDE0830" id="err-XTDE0830"><span class=
|
|
"error">[ERR XTDE0830]</span></a> In the case of an <a href=
|
|
"#element-element"><code>xsl:element</code></a> instruction with no
|
|
<code>namespace</code> attribute, it is a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> if the
|
|
<a title="effective value" class="termref" href=
|
|
"#dt-effective-value">effective value</a> of the <code>name</code>
|
|
attribute is a <a title="QName" class="termref" href=
|
|
"#dt-qname">QName</a> whose prefix is not declared in an in-scope
|
|
namespace declaration for the <a href=
|
|
"#element-element"><code>xsl:element</code></a> instruction.</p>
|
|
<p>If the <code>namespace</code> attribute is not present then the
|
|
<a title="QName" class="termref" href="#dt-qname">QName</a> is
|
|
expanded into an <a title="expanded-QName" class="termref" href=
|
|
"#dt-expanded-qname">expanded-QName</a> using the namespace
|
|
declarations in effect for the <a href=
|
|
"#element-element"><code>xsl:element</code></a> element, including
|
|
any default namespace declaration.</p>
|
|
<p>If the <code>namespace</code> attribute is present, then it too
|
|
is interpreted as an <a title="attribute value template" class=
|
|
"termref" href="#dt-attribute-value-template">attribute value
|
|
template</a>. The <a title="effective value" class="termref" href=
|
|
"#dt-effective-value">effective value</a> <span class=
|
|
"verb">must</span> be in the lexical space of the
|
|
<code>xs:anyURI</code> type. If the string is zero-length, then the
|
|
<a title="expanded-QName" class="termref" href=
|
|
"#dt-expanded-qname">expanded-QName</a> of the element has a null
|
|
namespace URI. Otherwise, the string is used as the namespace URI
|
|
of the <a title="expanded-QName" class="termref" href=
|
|
"#dt-expanded-qname">expanded-QName</a> of the element to be
|
|
created. The local part of the <a title="lexical QName" class=
|
|
"termref" href="#dt-lexical-qname">lexical QName</a> specified by
|
|
the <code>name</code> attribute is used as the local part of the
|
|
<a title="expanded-QName" class="termref" href=
|
|
"#dt-expanded-qname">expanded-QName</a> of the element to be
|
|
created.</p>
|
|
<p><a name="err-XTDE0835" id="err-XTDE0835"><span class=
|
|
"error">[ERR XTDE0835]</span></a> It is a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> if the
|
|
<a title="effective value" class="termref" href=
|
|
"#dt-effective-value">effective value</a> of the
|
|
<code>namespace</code> attribute is not in the lexical space of the
|
|
<code>xs:anyURI</code> data type or if it is the string
|
|
<code>http://www.w3.org/2000/xmlns/</code>.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>The XDM data model requires the name of a node to be an instance
|
|
of <code>xs:QName</code>, and XML Schema defines the namespace part
|
|
of an <code>xs:QName</code> to be an instance of
|
|
<code>xs:anyURI</code>. However, the schema specification, and the
|
|
specifications that it refers to, give implementations some
|
|
flexibility in how strictly they enforce these constraints.</p>
|
|
</div>
|
|
<p>The prefix of the <a title="lexical QName" class="termref" href=
|
|
"#dt-lexical-qname">lexical QName</a> specified in the
|
|
<code>name</code> attribute (or the absence of a prefix) is copied
|
|
to the prefix part of the <a title="expanded-QName" class="termref"
|
|
href="#dt-expanded-qname">expanded-QName</a> representing the name
|
|
of the new element node. In the event of a conflict a prefix may
|
|
subsequently be added, changed, or removed during the namespace
|
|
fixup process (see <a href="#namespace-fixup"><i>5.7.3 Namespace
|
|
Fixup</i></a>). The term <em>conflict</em> here means any violation
|
|
of the constraints defined in <a href="#xpath-datamodel-11">[Data
|
|
Model]</a>, for example the use of the same prefix to refer to two
|
|
different namespaces in the element and in one of its attributes,
|
|
the use of the prefix <code>xml</code> to refer to a namespace
|
|
other than the XML namespace, or any use of the prefix
|
|
<code>xmlns</code>.</p>
|
|
<p>The <a href="#element-element"><code>xsl:element</code></a>
|
|
instruction has an optional <code>inherit-namespaces</code>
|
|
attribute, with the value <code>yes</code> or <code>no</code>. The
|
|
default value is <code>yes</code>. If the value is set to
|
|
<code>yes</code>, or is omitted, then the namespace nodes created
|
|
for the newly constructed element (whether these were copied from
|
|
those of the source node, or generated as a result of namespace
|
|
fixup) are copied to the children and descendants of the newly
|
|
constructed element, as described in <a href=
|
|
"#constructing-complex-content"><i>5.7.1 Constructing Complex
|
|
Content</i></a>. If the value is set to <code>no</code>, then these
|
|
namespace nodes are not automatically copied to the children. This
|
|
may result in namespace undeclarations (such as
|
|
<code>xmlns=""</code> or, in the case of XML Namespaces 1.1,
|
|
<code>xmlns:p=""</code>) appearing on the child elements when a
|
|
<a title="final result tree" class="termref" href=
|
|
"#dt-final-result-tree">final result tree</a> is serialized.</p>
|
|
<p>The base URI of the new element is copied from the base URI of
|
|
the <a href="#element-element"><code>xsl:element</code></a>
|
|
instruction in the stylesheet, unless the content of the new
|
|
element includes an <code>xml:base</code> attribute, in which case
|
|
the base URI of the new element is the value of that attribute,
|
|
resolved (if it is a relative URI) against the base URI of the
|
|
<a href="#element-element"><code>xsl:element</code></a> instruction
|
|
in the stylesheet. (Note, however, that this is only relevant when
|
|
creating parentless elements. When the new element is copied to
|
|
form a child of an element or document node, the base URI of the
|
|
new copy is taken from that of its new parent.)</p>
|
|
<div class="div3">
|
|
<h4><a name="annotation-for-constructed-element" id=
|
|
"annotation-for-constructed-element"></a>11.2.1 <a href=
|
|
"#annotation-for-constructed-element" style=
|
|
"text-decoration: none">Setting the Type Annotation for a
|
|
Constructed Element Node</a></h4>
|
|
<p>The optional attributes <code>type</code> and
|
|
<code>validation</code> may be used on the <a href=
|
|
"#element-element"><code>xsl:element</code></a> instruction to
|
|
invoke validation of the contents of the element against a type
|
|
definition or element declaration in a schema, and to determine the
|
|
<a title="type annotation" class="termref" href=
|
|
"#dt-annotation">type annotation</a> that the new element node will
|
|
carry. These attributes also affect the type annotation carried by
|
|
any elements and attributes that have the new element node as an
|
|
ancestor. These two attributes are both optional, and if one is
|
|
specified then the other <span class="verb">must</span> be omitted.
|
|
The permitted values of these attributes and their semantics are
|
|
described in <a href="#validation"><i>22.2 Validation</i></a>.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>The final type annotation of the element in the <a title=
|
|
"result tree" class="termref" href="#dt-result-tree">result
|
|
tree</a> also depends on the <code>type</code> and
|
|
<code>validation</code> attributes of the instructions used to
|
|
create the ancestors of the element.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="creating-attributes" id="creating-attributes"></a>11.3
|
|
<a href="#creating-attributes" style=
|
|
"text-decoration: none">Creating Attribute Nodes Using</a>
|
|
<code>xsl:attribute</code> <a href="#creating-attributes" style=
|
|
"text-decoration: none"></a></h3>
|
|
<p class="element-syntax"><a name="element-attribute" id=
|
|
"element-attribute"></a><code><!-- Category: instruction
|
|
--><br />
|
|
<xsl:attribute<br />
|
|
  <b>name</b> = { <var>qname</var> }<br />
|
|
  namespace? = { <var>uri-reference</var> }<br />
|
|
  select? = <var>expression</var><br />
|
|
  separator? = { <var>string</var> }<br />
|
|
  type? = <var>qname</var><br />
|
|
  validation? = "strict" | "lax" | "preserve" |
|
|
"strip" ><br />
|
|
  <!-- Content: <var>sequence-constructor</var>
|
|
--><br />
|
|
</xsl:attribute></code></p>
|
|
<p>The <a href="#element-attribute"><code>xsl:attribute</code></a>
|
|
element can be used to add attributes to result elements whether
|
|
created by literal result elements in the stylesheet or by
|
|
instructions such as <a href=
|
|
"#element-element"><code>xsl:element</code></a> or <a href=
|
|
"#element-copy"><code>xsl:copy</code></a>. The <a title=
|
|
"expanded-QName" class="termref" href=
|
|
"#dt-expanded-qname">expanded-QName</a> of the attribute to be
|
|
created is specified by a <span class="verb">required</span>
|
|
<code>name</code> attribute and an optional <code>namespace</code>
|
|
attribute. Except in error cases, the result of evaluating an
|
|
<a href="#element-attribute"><code>xsl:attribute</code></a>
|
|
instruction is the newly constructed attribute node.</p>
|
|
<p>The string value of the new attribute node may be defined either
|
|
by using the <code>select</code> attribute, or by the <a title=
|
|
"sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> that forms the
|
|
content of the <a href=
|
|
"#element-attribute"><code>xsl:attribute</code></a> element. These
|
|
are mutually exclusive. If neither is present, the value of the new
|
|
attribute node will be a zero-length string. The way in which the
|
|
value is constructed is specified in <a href=
|
|
"#constructing-simple-content"><i>5.7.2 Constructing Simple
|
|
Content</i></a>.</p>
|
|
<p><a name="err-XTSE0840" id="err-XTSE0840"><span class=
|
|
"error">[ERR XTSE0840]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> if the
|
|
<code>select</code> attribute of the <a href=
|
|
"#element-attribute"><code>xsl:attribute</code></a> element is
|
|
present unless the element has empty content.</p>
|
|
<p>If the <code>separator</code> attribute is present, then the
|
|
<a title="effective value" class="termref" href=
|
|
"#dt-effective-value">effective value</a> of this attribute is used
|
|
to separate adjacent items in the result sequence, as described in
|
|
<a href="#constructing-simple-content"><i>5.7.2 Constructing Simple
|
|
Content</i></a>. In the absence of this attribute, the default
|
|
separator is a single space (#x20) when the content is specified
|
|
using the <code>select</code> attribute, or a zero-length string
|
|
when the content is specified using a <a title=
|
|
"sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a>.</p>
|
|
<p>The <code>name</code> attribute is interpreted as an <a title=
|
|
"attribute value template" class="termref" href=
|
|
"#dt-attribute-value-template">attribute value template</a>, whose
|
|
<a title="effective value" class="termref" href=
|
|
"#dt-effective-value">effective value</a> <span class=
|
|
"verb">must</span> be a <a title="lexical QName" class="termref"
|
|
href="#dt-lexical-qname">lexical QName</a>.</p>
|
|
<p><a name="err-XTDE0850" id="err-XTDE0850"><span class=
|
|
"error">[ERR XTDE0850]</span></a> It is a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> if the
|
|
<a title="effective value" class="termref" href=
|
|
"#dt-effective-value">effective value</a> of the <code>name</code>
|
|
attribute is not a <a title="lexical QName" class="termref" href=
|
|
"#dt-lexical-qname">lexical QName</a>.</p>
|
|
<p><a name="err-XTDE0855" id="err-XTDE0855"><span class=
|
|
"error">[ERR XTDE0855]</span></a> In the case of an <a href=
|
|
"#element-attribute"><code>xsl:attribute</code></a> instruction
|
|
with no <code>namespace</code> attribute, it is a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> if the
|
|
<a title="effective value" class="termref" href=
|
|
"#dt-effective-value">effective value</a> of the <code>name</code>
|
|
attribute is the string <code>xmlns</code>.</p>
|
|
<p><a name="err-XTDE0860" id="err-XTDE0860"><span class=
|
|
"error">[ERR XTDE0860]</span></a> In the case of an <a href=
|
|
"#element-attribute"><code>xsl:attribute</code></a> instruction
|
|
with no <code>namespace</code> attribute, it is a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> if the
|
|
<a title="effective value" class="termref" href=
|
|
"#dt-effective-value">effective value</a> of the <code>name</code>
|
|
attribute is a <a title="lexical QName" class="termref" href=
|
|
"#dt-lexical-qname">lexical QName</a> whose prefix is not declared
|
|
in an in-scope namespace declaration for the <a href=
|
|
"#element-attribute"><code>xsl:attribute</code></a>
|
|
instruction.</p>
|
|
<p>If the <code>namespace</code> attribute is not present, then the
|
|
<a title="lexical QName" class="termref" href=
|
|
"#dt-lexical-qname">lexical QName</a> is expanded into an <a title=
|
|
"expanded-QName" class="termref" href=
|
|
"#dt-expanded-qname">expanded-QName</a> using the namespace
|
|
declarations in effect for the <a href=
|
|
"#element-attribute"><code>xsl:attribute</code></a> element,
|
|
<em>not</em> including any default namespace declaration.</p>
|
|
<p>If the <code>namespace</code> attribute is present, then it too
|
|
is interpreted as an <a title="attribute value template" class=
|
|
"termref" href="#dt-attribute-value-template">attribute value
|
|
template</a>. The <a title="effective value" class="termref" href=
|
|
"#dt-effective-value">effective value</a> <span class=
|
|
"verb">must</span> be in the lexical space of the
|
|
<code>xs:anyURI</code> type. If the string is zero-length, then the
|
|
<a title="expanded-QName" class="termref" href=
|
|
"#dt-expanded-qname">expanded-QName</a> of the attribute has a null
|
|
namespace URI. Otherwise, the string is used as the namespace URI
|
|
of the <a title="expanded-QName" class="termref" href=
|
|
"#dt-expanded-qname">expanded-QName</a> of the attribute to be
|
|
created. The local part of the <a title="lexical QName" class=
|
|
"termref" href="#dt-lexical-qname">lexical QName</a> specified by
|
|
the <code>name</code> attribute is used as the local part of the
|
|
<a title="expanded-QName" class="termref" href=
|
|
"#dt-expanded-qname">expanded-QName</a> of the attribute to be
|
|
created.</p>
|
|
<p><a name="err-XTDE0865" id="err-XTDE0865"><span class=
|
|
"error">[ERR XTDE0865]</span></a> It is a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> if the
|
|
<a title="effective value" class="termref" href=
|
|
"#dt-effective-value">effective value</a> of the
|
|
<code>namespace</code> attribute is not in the lexical space of the
|
|
<code>xs:anyURI</code> data type or if it is the string
|
|
<code>http://www.w3.org/2000/xmlns/</code>.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>The same considerations apply as for elements: <span class=
|
|
"error">[see <a href="#err-XTDE0835">ERR XTDE0835</a>]</span> in
|
|
<a href="#xsl-element"><i>11.2 Creating Element Nodes Using
|
|
xsl:element</i></a> .</p>
|
|
</div>
|
|
<p>The prefix of the <a title="lexical QName" class="termref" href=
|
|
"#dt-lexical-qname">lexical QName</a> specified in the
|
|
<code>name</code> attribute (or the absence of a prefix) is copied
|
|
to the prefix part of the <a title="expanded-QName" class="termref"
|
|
href="#dt-expanded-qname">expanded-QName</a> representing the name
|
|
of the new attribute node. In the event of a conflict this prefix
|
|
may subsequently be added, changed, or removed during the namespace
|
|
fixup process (see <a href="#namespace-fixup"><i>5.7.3 Namespace
|
|
Fixup</i></a>). If the attribute is in a non-null namespace and no
|
|
prefix is specified, then the namespace fixup process will invent a
|
|
prefix. The term <em>conflict</em> here means any violation of the
|
|
constraints defined in <a href="#xpath-datamodel-11">[Data
|
|
Model]</a>, for example the use of the same prefix to refer to two
|
|
different namespaces in the element and in one of its attributes,
|
|
the use of the prefix <code>xml</code> to refer to a namespace
|
|
other than the XML namespace, or any use of the prefix
|
|
<code>xmlns</code>.</p>
|
|
<p>If the name of a constructed attribute is <code>xml:id</code>,
|
|
the processor must perform attribute value normalization by
|
|
effectively applying the <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-normalize-space"><code>
|
|
normalize-space</code></a><sup><small>FO</small></sup> function to
|
|
the value of the attribute, and the resulting attribute node must
|
|
be given the <code>is-id</code> property. This applies whether the
|
|
attribute is constructed using the <a href=
|
|
"#element-attribute"><code>xsl:attribute</code></a> instruction or
|
|
whether it is constructed using an attribute of a literal result
|
|
element. This does not imply any constraints on the value of the
|
|
attribute, or on its uniqueness, and it does not affect the
|
|
<a title="type annotation" class="termref" href=
|
|
"#dt-annotation">type annotation</a> of the attribute, unless the
|
|
containing document is validated.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>The effect of setting the <code>is-id</code> property is that
|
|
the parent element can be located within the containing document by
|
|
use of the <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-id"><code>id</code></a><sup><small>FO</small></sup>
|
|
function. In effect, XSLT when constructing a document performs
|
|
some of the functions of an <code>xml:id</code> processor, as
|
|
defined in <a href="#xml-id">[xml:id]</a>; the other aspects of
|
|
<code>xml:id</code> processing are performed during validation.</p>
|
|
</div>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e21002" id=
|
|
"d7e21002"></a>Example: Creating a List-Valued Attribute</div>
|
|
<p>The following instruction creates the attribute
|
|
<code>colors="red green blue"</code>:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:attribute name="colors" select="'red', 'green', 'blue'"/>
|
|
</pre></div>
|
|
</div>
|
|
<p> </p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e21012" id=
|
|
"d7e21012"></a>Example: Namespaces are not Attributes</div>
|
|
<p>It is not an error to write:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:attribute name="xmlns:xsl"
|
|
namespace="file://some.namespace"
|
|
select="'http://www.w3.org/1999/XSL/Transform'"/>
|
|
</pre></div>
|
|
<p>However, this will not result in the namespace declaration
|
|
<code>xmlns:xsl="http://www.w3.org/1999/XSL/Transform"</code> being
|
|
output. Instead, it will produce an attribute node with local name
|
|
<code>xsl</code>, and with a system-allocated namespace prefix
|
|
mapped to the namespace URI <code>file://some.namespace</code>.
|
|
This is because the namespace fixup process is not allowed to use
|
|
<code>xmlns</code> as the name of a namespace node.</p>
|
|
</div>
|
|
<p>As described in <a href="#constructing-complex-content"><i>5.7.1
|
|
Constructing Complex Content</i></a>, in a sequence that is used to
|
|
construct the content of an element, any attribute nodes
|
|
<span class="verb">must</span> appear in the sequence before any
|
|
element, text, comment, or processing instruction nodes. Where the
|
|
sequence contains two or more attribute nodes with the same
|
|
<a title="expanded-QName" class="termref" href=
|
|
"#dt-expanded-qname">expanded-QName</a>, the one that comes last is
|
|
the only one that takes effect.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>If a collection of attributes is generated repeatedly, this can
|
|
be done conveniently by using named attribute sets: see <a href=
|
|
"#attribute-sets"><i>10.2 Named Attribute Sets</i></a></p>
|
|
</div>
|
|
<div class="div3">
|
|
<h4><a name="annotation-for-constructed-attribute" id=
|
|
"annotation-for-constructed-attribute"></a>11.3.1 <a href=
|
|
"#annotation-for-constructed-attribute" style=
|
|
"text-decoration: none">Setting the Type Annotation for a
|
|
Constructed Attribute Node</a></h4>
|
|
<p>The optional attributes <code>type</code> and
|
|
<code>validation</code> may be used on the <a href=
|
|
"#element-attribute"><code>xsl:attribute</code></a> instruction to
|
|
invoke validation of the contents of the attribute against a type
|
|
definition or attribute declaration in a schema, and to determine
|
|
the <a title="type annotation" class="termref" href=
|
|
"#dt-annotation">type annotation</a> that the new attribute node
|
|
will carry. These two attributes are both optional, and if one is
|
|
specified then the other <span class="verb">must</span> be omitted.
|
|
The permitted values of these attributes and their semantics are
|
|
described in <a href="#validation"><i>22.2 Validation</i></a>.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>The final <a title="type annotation" class="termref" href=
|
|
"#dt-annotation">type annotation</a> of the attribute in the
|
|
<a title="result tree" class="termref" href=
|
|
"#dt-result-tree">result tree</a> also depends on the
|
|
<code>type</code> and <code>validation</code> attributes of the
|
|
instructions used to create the ancestors of the attribute.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="creating-text-nodes" id="creating-text-nodes"></a>11.4
|
|
<a href="#creating-text-nodes" style=
|
|
"text-decoration: none">Creating Text Nodes</a></h3>
|
|
<p>This section describes three different ways of creating text
|
|
nodes: by means of literal text nodes in the stylesheet, or by
|
|
using the <a href="#element-text"><code>xsl:text</code></a> and
|
|
<a href="#element-value-of"><code>xsl:value-of</code></a>
|
|
instructions. It is also possible to create text nodes using the
|
|
<a href="#element-number"><code>xsl:number</code></a> instruction
|
|
described in <a href="#number"><i>12 Numbering</i></a>.</p>
|
|
<p>If and when the sequence that results from evaluating a
|
|
<a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> is used to form
|
|
the content of a node, as described in <a href=
|
|
"#constructing-simple-content"><i>5.7.2 Constructing Simple
|
|
Content</i></a> and <a href=
|
|
"#constructing-complex-content"><i>5.7.1 Constructing Complex
|
|
Content</i></a>, adjacent text nodes in the sequence are merged.
|
|
Within the sequence itself, however, they exist as distinct
|
|
nodes.</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e21112" id=
|
|
"d7e21112"></a>Example: A sequence of text nodes</div>
|
|
<p>The following function returns a sequence of three text
|
|
nodes:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:function name="f:wrap">
|
|
<xsl:param name="s"/>
|
|
<xsl:text>(</xsl:text>
|
|
<xsl:value-of select="$s"/>
|
|
<xsl:text>)</xsl:text>
|
|
</xsl:function>
|
|
</pre></div>
|
|
<p>When this function is called as follows:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:value-of select="f:wrap('---')"/>
|
|
</pre></div>
|
|
<p>the result is:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
(---)
|
|
</pre></div>
|
|
<p>No additional spaces are inserted, because the calling <a href=
|
|
"#element-value-of"><code>xsl:value-of</code></a> instruction
|
|
merges adjacent text nodes before atomizing the sequence. However,
|
|
the result of the instruction:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:value-of select="data(f:wrap('---'))"/>
|
|
</pre></div>
|
|
<p>is:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
( --- )
|
|
</pre></div>
|
|
<p>because in this case the three text nodes are atomized to form
|
|
three strings, and spaces are inserted between adjacent
|
|
strings.</p>
|
|
</div>
|
|
<p>It is possible to construct text nodes whose string value is
|
|
zero-length. A zero-length text node, when atomized, produces a
|
|
zero-length string. However, zero-length text nodes are ignored
|
|
when they appear in a sequence that is used to form the content of
|
|
a node, as described in <a href=
|
|
"#constructing-complex-content"><i>5.7.1 Constructing Complex
|
|
Content</i></a> and <a href="#constructing-simple-content"><i>5.7.2
|
|
Constructing Simple Content</i></a>.</p>
|
|
<div class="div3">
|
|
<h4><a name="literal-text-nodes" id="literal-text-nodes"></a>11.4.1
|
|
<a href="#literal-text-nodes" style="text-decoration: none">Literal
|
|
Text Nodes</a></h4>
|
|
<p>A <a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> can contain
|
|
text nodes. Each text node in a sequence constructor remaining
|
|
after <a title="whitespace text node" class="termref" href=
|
|
"#dt-whitespace-text-node">whitespace text nodes</a> have been
|
|
stripped as specified in <a href="#stylesheet-stripping"><i>4.2
|
|
Stripping Whitespace from the Stylesheet</i></a> will construct a
|
|
new text node with the same <a title="string value" class="termref"
|
|
href="#dt-string-value">string value</a>. The resulting text node
|
|
is added to the result of the containing sequence constructor.</p>
|
|
<p>Text is processed at the tree level. Thus, markup of
|
|
<code>&lt;</code> in a template will be represented in the
|
|
stylesheet tree by a text node that includes the character
|
|
<code><</code>. This will create a text node in the <a title=
|
|
"result tree" class="termref" href="#dt-result-tree">result
|
|
tree</a> that contains a <code><</code> character, which will be
|
|
represented by the markup <code>&lt;</code> (or an equivalent
|
|
character reference) when the result tree is serialized as an XML
|
|
document, unless otherwise specified using <a title="character map"
|
|
class="termref" href="#dt-character-map">character maps</a> (see
|
|
<a href="#character-maps"><i>23.1 Character Maps</i></a>) or
|
|
<code>disable-output-escaping</code> (see <a href=
|
|
"#disable-output-escaping"><i>23.2 Disabling Output
|
|
Escaping</i></a>).</p>
|
|
</div>
|
|
<div class="div3">
|
|
<h4><a name="xsl-text" id="xsl-text"></a>11.4.2 <a href="#xsl-text"
|
|
style="text-decoration: none">Creating Text Nodes Using</a>
|
|
<code>xsl:text</code> <a href="#xsl-text" style=
|
|
"text-decoration: none"></a></h4>
|
|
<p class="element-syntax"><a name="element-text" id=
|
|
"element-text"></a><code><!-- Category: instruction --><br />
|
|
<xsl:text<br />
|
|
  <span class="grayed">[disable-output-escaping]?</span>
|
|
= "yes" | "no" ><br />
|
|
  <!-- Content: #PCDATA --><br />
|
|
</xsl:text></code></p>
|
|
<p>The <a href="#element-text"><code>xsl:text</code></a> element is
|
|
evaluated to construct a new text node. The content of the <a href=
|
|
"#element-text"><code>xsl:text</code></a> element is a single text
|
|
node whose value forms the <a title="string value" class="termref"
|
|
href="#dt-string-value">string value</a> of the new text node. An
|
|
<a href="#element-text"><code>xsl:text</code></a> element may be
|
|
empty, in which case the result of evaluating the instruction is a
|
|
text node whose string value is the zero-length string.</p>
|
|
<p>The result of evaluating an <a href=
|
|
"#element-text"><code>xsl:text</code></a> instruction is the newly
|
|
constructed text node.</p>
|
|
<p>A text node that is an immediate child of an <a href=
|
|
"#element-text"><code>xsl:text</code></a> instruction will not be
|
|
stripped from the stylesheet tree, even if it consists entirely of
|
|
whitespace (see <a href="#strip"><i>4.4 Stripping Whitespace from a
|
|
Source Tree</i></a>).</p>
|
|
<p>For the effect of the <a title="deprecated" class="termref"
|
|
href="#dt-deprecated">deprecated</a>
|
|
<code>disable-output-escaping</code> attribute, see <a href=
|
|
"#disable-output-escaping"><i>23.2 Disabling Output
|
|
Escaping</i></a></p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>It is not always necessary to use the <a href=
|
|
"#element-text"><code>xsl:text</code></a> instruction to write text
|
|
nodes to the <a title="result tree" class="termref" href=
|
|
"#dt-result-tree">result tree</a>. Literal text can be written to
|
|
the result tree by including it anywhere in a <a title=
|
|
"sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a>, while computed
|
|
text can be output using the <a href=
|
|
"#element-value-of"><code>xsl:value-of</code></a> instruction. The
|
|
principal reason for using <a href=
|
|
"#element-text"><code>xsl:text</code></a> is that it offers
|
|
improved control over whitespace handling.</p>
|
|
</div>
|
|
</div>
|
|
<div class="div3">
|
|
<h4><a name="value-of" id="value-of"></a>11.4.3 <a href="#value-of"
|
|
style="text-decoration: none">Generating Text with</a> <a href=
|
|
"#element-value-of"><code>xsl:value-of</code></a> <a href=
|
|
"#value-of" style="text-decoration: none"></a></h4>
|
|
<p>Within a <a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a>, the <a href=
|
|
"#element-value-of"><code>xsl:value-of</code></a> instruction can
|
|
be used to generate computed text nodes. The <a href=
|
|
"#element-value-of"><code>xsl:value-of</code></a> instruction
|
|
computes the text using an <a title="expression" class="termref"
|
|
href="#dt-expression">expression</a> that is specified as the value
|
|
of the <code>select</code> attribute, or by means of contained
|
|
instructions. This might, for example, extract text from a
|
|
<a title="source tree" class="termref" href=
|
|
"#dt-source-tree">source tree</a> or insert the value of a
|
|
variable.</p>
|
|
<p class="element-syntax"><a name="element-value-of" id=
|
|
"element-value-of"></a><code><!-- Category: instruction
|
|
--><br />
|
|
<xsl:value-of<br />
|
|
  select? = <var>expression</var><br />
|
|
  separator? = { <var>string</var> }<br />
|
|
  <span class="grayed">[disable-output-escaping]?</span>
|
|
= "yes" | "no" ><br />
|
|
  <!-- Content: <var>sequence-constructor</var>
|
|
--><br />
|
|
</xsl:value-of></code></p>
|
|
<p>The <a href="#element-value-of"><code>xsl:value-of</code></a>
|
|
instruction is evaluated to construct a new text node; the result
|
|
of the instruction is the newly constructed text node.</p>
|
|
<p>The string value of the new text node may be defined either by
|
|
using the <code>select</code> attribute, or by the <a title=
|
|
"sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> (see <a href=
|
|
"#sequence-constructors"><i>5.7 Sequence Constructors</i></a>) that
|
|
forms the content of the <a href=
|
|
"#element-value-of"><code>xsl:value-of</code></a> element. These
|
|
are mutually exclusive, and one of them must be present. The way in
|
|
which the value is constructed is specified in <a href=
|
|
"#constructing-simple-content"><i>5.7.2 Constructing Simple
|
|
Content</i></a>.</p>
|
|
<p><a name="err-XTSE0870" id="err-XTSE0870"><span class=
|
|
"error">[ERR XTSE0870]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> if the
|
|
<code>select</code> attribute of the <a href=
|
|
"#element-value-of"><code>xsl:value-of</code></a> element is
|
|
present when the content of the element is non-empty, or if the
|
|
<code>select</code> attribute is absent when the content is
|
|
empty.</p>
|
|
<p>If the <code>separator</code> attribute is present, then the
|
|
<a title="effective value" class="termref" href=
|
|
"#dt-effective-value">effective value</a> of this attribute is used
|
|
to separate adjacent items in the result sequence, as described in
|
|
<a href="#constructing-simple-content"><i>5.7.2 Constructing Simple
|
|
Content</i></a>. In the absence of this attribute, the default
|
|
separator is a single space (#x20) when the content is specified
|
|
using the <code>select</code> attribute, or a zero-length string
|
|
when the content is specified using a <a title=
|
|
"sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a>.</p>
|
|
<p><span>Special rules apply when the instruction is processed with
|
|
<a title="XSLT 1.0 behavior" class="termref" href=
|
|
"#dt-xslt-10-behavior">XSLT 1.0 behavior</a>.</span> If no
|
|
<code>separator</code> attribute is present, and if the
|
|
<code>select</code> attribute is present, then all items in the
|
|
<a title="atomize" class="termref" href=
|
|
"#dt-atomization">atomized</a> result sequence other than the first
|
|
are ignored.</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e21369" id=
|
|
"d7e21369"></a>Example: Generating a List with Separators</div>
|
|
<p>The instruction:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<x><xsl:value-of select="1 to 4" separator="|"/></x>
|
|
</pre></div>
|
|
<p>produces the output:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<x>1|2|3|4</x>
|
|
</pre></div>
|
|
</div>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>The <a href="#element-copy-of"><code>xsl:copy-of</code></a>
|
|
element can be used to copy a sequence of nodes to the <a title=
|
|
"result tree" class="termref" href="#dt-result-tree">result
|
|
tree</a> without <a title="atomize" class="termref" href=
|
|
"#dt-atomization">atomization</a>. See <a href="#copy-of"><i>11.9.2
|
|
Deep Copy</i></a>.</p>
|
|
</div>
|
|
<p>For the effect of the <a title="deprecated" class="termref"
|
|
href="#dt-deprecated">deprecated</a>
|
|
<code>disable-output-escaping</code> attribute, see <a href=
|
|
"#disable-output-escaping"><i>23.2 Disabling Output
|
|
Escaping</i></a></p>
|
|
</div>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="creating-document-nodes" id=
|
|
"creating-document-nodes"></a>11.5 <a href=
|
|
"#creating-document-nodes" style="text-decoration: none">Creating
|
|
Document Nodes</a></h3>
|
|
<p class="element-syntax"><a name="element-document" id=
|
|
"element-document"></a><code><!-- Category: instruction
|
|
--><br />
|
|
<xsl:document<br />
|
|
  validation? = "strict" | "lax" | "preserve" |
|
|
"strip"<br />
|
|
  type? = <var>qname</var> ><br />
|
|
  <!-- Content: <var>sequence-constructor</var>
|
|
--><br />
|
|
</xsl:document></code></p>
|
|
<p>The <a href="#element-document"><code>xsl:document</code></a>
|
|
instruction is used to create a new document node. The content of
|
|
the <a href="#element-document"><code>xsl:document</code></a>
|
|
element is a <a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> for the
|
|
children of the new document node. A document node is created, and
|
|
the sequence obtained by evaluating the sequence constructor is
|
|
used to construct the content of the document, as described in
|
|
<a href="#constructing-complex-content"><i>5.7.1 Constructing
|
|
Complex Content</i></a>. The <a title="temporary tree" class=
|
|
"termref" href="#dt-temporary-tree">temporary tree</a> rooted at
|
|
this document node forms the <a title="result tree" class="termref"
|
|
href="#dt-result-tree">result tree</a>.</p>
|
|
<p>Except in error situations, the result of evaluating the
|
|
<a href="#element-document"><code>xsl:document</code></a>
|
|
instruction is a single node, the newly constructed document
|
|
node.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>The new document is not serialized. To construct a document that
|
|
is to form a final result rather than an intermediate result, use
|
|
the <a href=
|
|
"#element-result-document"><code>xsl:result-document</code></a>
|
|
instruction described in <a href="#creating-result-trees"><i>22.1
|
|
Creating Final Result Trees</i></a>.</p>
|
|
</div>
|
|
<p>The optional attributes <code>type</code> and
|
|
<code>validation</code> may be used on the <a href=
|
|
"#element-document"><code>xsl:document</code></a> instruction to
|
|
validate the contents of the new document, and to determine the
|
|
<a title="type annotation" class="termref" href=
|
|
"#dt-annotation">type annotation</a> that elements and attributes
|
|
within the <a title="result tree" class="termref" href=
|
|
"#dt-result-tree">result tree</a> will carry. The permitted values
|
|
and their semantics are described in <a href=
|
|
"#validating-document-nodes"><i>22.2.2 Validating Document
|
|
Nodes</i></a>.</p>
|
|
<p>The base URI of the new document node is taken from the base URI
|
|
of the <a href="#element-document"><code>xsl:document</code></a>
|
|
instruction.</p>
|
|
<p>The <code>document-uri</code> and <code>unparsed-entities</code>
|
|
properties of the new document node are set to empty.</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e21485" id=
|
|
"d7e21485"></a>Example: Checking Uniqueness Constraints in a
|
|
Temporary Tree</div>
|
|
<p>The following example creates a temporary tree held in a
|
|
variable. The use of an enclosed <a href=
|
|
"#element-document"><code>xsl:document</code></a> instruction
|
|
ensures that uniqueness constraints defined in the schema for the
|
|
relevant elements are checked.</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:variable name="tree" as="document-node()">
|
|
<xsl:document validation="strict">
|
|
<xsl:apply-templates/>
|
|
</xsl:document>
|
|
</xsl:variable>
|
|
</pre></div>
|
|
</div>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="creating-processing-instructions" id=
|
|
"creating-processing-instructions"></a>11.6 <a href=
|
|
"#creating-processing-instructions" style=
|
|
"text-decoration: none">Creating Processing Instructions</a></h3>
|
|
<p class="element-syntax"><a name="element-processing-instruction"
|
|
id="element-processing-instruction"></a><code><!-- Category:
|
|
instruction --><br />
|
|
<xsl:processing-instruction<br />
|
|
  <b>name</b> = { <var>ncname</var> }<br />
|
|
  select? = <var>expression</var> ><br />
|
|
  <!-- Content: <var>sequence-constructor</var>
|
|
--><br />
|
|
</xsl:processing-instruction></code></p>
|
|
<p>The <a href=
|
|
"#element-processing-instruction"><code>xsl:processing-instruction</code></a>
|
|
element is evaluated to create a processing instruction node.</p>
|
|
<p>The <a href=
|
|
"#element-processing-instruction"><code>xsl:processing-instruction</code></a>
|
|
element has a <span class="verb">required</span> <code>name</code>
|
|
attribute that specifies the name of the processing instruction
|
|
node. The value of the <code>name</code> attribute is interpreted
|
|
as an <a title="attribute value template" class="termref" href=
|
|
"#dt-attribute-value-template">attribute value template</a>.</p>
|
|
<p>The string value of the new processing-instruction node may be
|
|
defined either by using the <code>select</code> attribute, or by
|
|
the <a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> that forms the
|
|
content of the <a href=
|
|
"#element-processing-instruction"><code>xsl:processing-instruction</code></a>
|
|
element. These are mutually exclusive. If neither is present, the
|
|
string value of the new processing-instruction node will be a
|
|
zero-length string. The way in which the value is constructed is
|
|
specified in <a href="#constructing-simple-content"><i>5.7.2
|
|
Constructing Simple Content</i></a>.</p>
|
|
<p><a name="err-XTSE0880" id="err-XTSE0880"><span class=
|
|
"error">[ERR XTSE0880]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> if the
|
|
<code>select</code> attribute of the <a href=
|
|
"#element-processing-instruction"><code>xsl:processing-instruction</code></a>
|
|
element is present unless the element has empty content.</p>
|
|
<p>Except in error situations, the result of evaluating the
|
|
<a href="#element-processing-instruction"><code>xsl:processing-instruction</code></a>
|
|
instruction is a single node, the newly constructed processing
|
|
instruction node.</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e21563" id=
|
|
"d7e21563"></a>Example: Creating a Processing Instruction</div>
|
|
<p>This instruction:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:processing-instruction name="xml-stylesheet"
|
|
select="('href=&quot;book.css&quot;', 'type=&quot;text/css&quot;)"/>
|
|
</pre></div>
|
|
<p>creates the processing instruction</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<?xml-stylesheet href="book.css" type="text/css"?>
|
|
</pre></div>
|
|
<p>Note that the <code>xml-stylesheet</code> processing instruction
|
|
contains <em>pseudo-attributes</em> in the form
|
|
<code>name="value"</code>. Although these have the same textual
|
|
form as attributes in an element start tag, they are not
|
|
represented as XDM attribute nodes, and cannot therefore be
|
|
constructed using <a href=
|
|
"#element-attribute"><code>xsl:attribute</code></a>
|
|
instructions.</p>
|
|
</div>
|
|
<p><a name="err-XTDE0890" id="err-XTDE0890"><span class=
|
|
"error">[ERR XTDE0890]</span></a> It is a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> if the
|
|
<a title="effective value" class="termref" href=
|
|
"#dt-effective-value">effective value</a> of the <code>name</code>
|
|
attribute is not both an <a href=
|
|
"http://www.w3.org/TR/REC-xml-names/#NT-NCName">NCName</a><sup><small>Names</small></sup>
|
|
and a <a href=
|
|
"http://www.w3.org/TR/2000/REC-xml-20001006#NT-PITarget">PITarget</a><sup><small>XML</small></sup>.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>Because these rules disallow the name <code>xml</code>, the
|
|
<a href=
|
|
"#element-processing-instruction"><code>xsl:processing-instruction</code></a>
|
|
cannot be used to output an XML declaration. The <a href=
|
|
"#element-output"><code>xsl:output</code></a> declaration should be
|
|
used to control this instead (see <a href="#serialization"><i>23
|
|
Serialization</i></a>).</p>
|
|
</div>
|
|
<p>If the result of evaluating the content of the <a href=
|
|
"#element-processing-instruction"><code>xsl:processing-instruction</code></a>
|
|
contains the string <code>?></code>, this string is modified by
|
|
inserting a space between the <code>?</code> and <code>></code>
|
|
characters.</p>
|
|
<p>The base URI of the new processing-instruction is copied from
|
|
the base URI of the <a href=
|
|
"#element-processing-instruction"><code>xsl:processing-instruction</code></a>
|
|
element in the stylesheet. (Note, however, that this is only
|
|
relevant when creating a parentless processing instruction. When
|
|
the new processing instruction is copied to form a child of an
|
|
element or document node, the base URI of the new copy is taken
|
|
from that of its new parent.)</p>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="creating-namespace-nodes" id=
|
|
"creating-namespace-nodes"></a>11.7 <a href=
|
|
"#creating-namespace-nodes" style="text-decoration: none">Creating
|
|
Namespace Nodes</a></h3>
|
|
<p class="element-syntax"><a name="element-namespace" id=
|
|
"element-namespace"></a><code><!-- Category: instruction
|
|
--><br />
|
|
<xsl:namespace<br />
|
|
  <b>name</b> = { <var>ncname</var> }<br />
|
|
  select? = <var>expression</var> ><br />
|
|
  <!-- Content: <var>sequence-constructor</var>
|
|
--><br />
|
|
</xsl:namespace></code></p>
|
|
<p>The <a href="#element-namespace"><code>xsl:namespace</code></a>
|
|
element is evaluated to create a namespace node. Except in error
|
|
situations, the result of evaluating the <a href=
|
|
"#element-namespace"><code>xsl:namespace</code></a> instruction is
|
|
a single node, the newly constructed namespace node.</p>
|
|
<p>The <a href="#element-namespace"><code>xsl:namespace</code></a>
|
|
element has a <span class="verb">required</span> <code>name</code>
|
|
attribute that specifies the name of the namespace node (that is,
|
|
the namespace prefix). The value of the <code>name</code> attribute
|
|
is interpreted as an <a title="attribute value template" class=
|
|
"termref" href="#dt-attribute-value-template">attribute value
|
|
template</a>. If the <a title="effective value" class="termref"
|
|
href="#dt-effective-value">effective value</a> of the
|
|
<code>name</code> attribute is a zero-length string, a namespace
|
|
node is added for the default namespace.</p>
|
|
<p>The string value of the new namespace node (that is, the
|
|
namespace URI) may be defined either by using the
|
|
<code>select</code> attribute, or by the <a title=
|
|
"sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> that forms the
|
|
content of the <a href=
|
|
"#element-namespace"><code>xsl:namespace</code></a> element. These
|
|
are mutually exclusive. Since the string value of a namespace node
|
|
cannot be a zero-length string, one of them must be present. The
|
|
way in which the value is constructed is specified in <a href=
|
|
"#constructing-simple-content"><i>5.7.2 Constructing Simple
|
|
Content</i></a>.</p>
|
|
<p><a name="err-XTDE0905" id="err-XTDE0905"><span class=
|
|
"error">[ERR XTDE0905]</span></a> It is a non-recoverable dynamic
|
|
error if the string value of the new namespace node is not valid in
|
|
the lexical space of the data type <code>xs:anyURI</code>, or if it
|
|
is the string <code>http://www.w3.org/2000/xmlns/</code>.</p>
|
|
<p><a name="err-XTSE0910" id="err-XTSE0910"><span class=
|
|
"error">[ERR XTSE0910]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> if the
|
|
<code>select</code> attribute of the <a href=
|
|
"#element-namespace"><code>xsl:namespace</code></a> element is
|
|
present when the element has content other than one or more
|
|
<a href="#element-fallback"><code>xsl:fallback</code></a>
|
|
instructions, or if the <code>select</code> attribute is absent
|
|
when the element has empty content.</p>
|
|
<p>Note the restrictions described in <a href=
|
|
"#constructing-complex-content"><i>5.7.1 Constructing Complex
|
|
Content</i></a> for the position of a namespace node relative to
|
|
other nodes in the node sequence returned by a sequence
|
|
constructor.</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e21747" id=
|
|
"d7e21747"></a>Example: Constructing a QName-Valued Attribute</div>
|
|
<p>This literal result element:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<data xsi:type="xs:integer"
|
|
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
|
|
<xsl:namespace name="xs"
|
|
select="'http://www.w3.org/2001/XMLSchema'"/>
|
|
<xsl:text>42</xsl:text>
|
|
</data>
|
|
</pre></div>
|
|
<p>would typically cause the output document to contain the
|
|
element:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<data xsi:type="xs:integer"
|
|
xmlns:xs="http://www.w3.org/2001/XMLSchema"
|
|
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">42</data>
|
|
</pre></div>
|
|
<p>In this case, the element is constructed using a literal result
|
|
element, and the namespace
|
|
<code>xmlns:xs="http://www.w3.org/2001/XMLSchema"</code> could
|
|
therefore have been added to the <a title="result tree" class=
|
|
"termref" href="#dt-result-tree">result tree</a> simply by
|
|
declaring it as one of the in-scope namespaces in the stylesheet.
|
|
In practice, the <a href=
|
|
"#element-namespace"><code>xsl:namespace</code></a> instruction is
|
|
more likely to be useful in situations where the element is
|
|
constructed using an <a href=
|
|
"#element-element"><code>xsl:element</code></a> instruction, which
|
|
does not copy all the in-scope namespaces from the stylesheet.</p>
|
|
</div>
|
|
<p><a name="err-XTDE0920" id="err-XTDE0920"><span class=
|
|
"error">[ERR XTDE0920]</span></a> It is a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> if the
|
|
<a title="effective value" class="termref" href=
|
|
"#dt-effective-value">effective value</a> of the <code>name</code>
|
|
attribute is neither a zero-length string nor an <a href=
|
|
"http://www.w3.org/TR/REC-xml-names/#NT-NCName">NCName</a><sup><small>Names</small></sup>,
|
|
or if it is <code>xmlns</code>.</p>
|
|
<p><a name="err-XTDE0925" id="err-XTDE0925"><span class=
|
|
"error">[ERR XTDE0925]</span></a> It is a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> if the
|
|
<a href="#element-namespace"><code>xsl:namespace</code></a>
|
|
instruction generates a namespace node whose name is
|
|
<code>xml</code> and whose string value is not
|
|
<code>http://www.w3.org/XML/1998/namespace</code>, or a namespace
|
|
node whose string value is
|
|
<code>http://www.w3.org/XML/1998/namespace</code> and whose name is
|
|
not <code>xml</code>.</p>
|
|
<p><a name="err-XTDE0930" id="err-XTDE0930"><span class=
|
|
"error">[ERR XTDE0930]</span></a> It is a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> if
|
|
evaluating the <code>select</code> attribute or the contained
|
|
<a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> of an <a href=
|
|
"#element-namespace"><code>xsl:namespace</code></a> instruction
|
|
results in a zero-length string.</p>
|
|
<p>For details of other error conditions that may arise, see
|
|
<a href="#sequence-constructors"><i>5.7 Sequence
|
|
Constructors</i></a>.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>It is rarely necessary to use <a href=
|
|
"#element-namespace"><code>xsl:namespace</code></a> to create a
|
|
namespace node in the <a title="result tree" class="termref" href=
|
|
"#dt-result-tree">result tree</a>; in most circumstances, the
|
|
required namespace nodes will be created automatically, as a
|
|
side-effect of writing elements or attributes that use the
|
|
namespace. An example where <a href=
|
|
"#element-namespace"><code>xsl:namespace</code></a> 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.</p>
|
|
<p>Adding a namespace node to the <a title="result tree" class=
|
|
"termref" href="#dt-result-tree">result tree</a> will never change
|
|
the <a title="expanded-QName" class="termref" href=
|
|
"#dt-expanded-qname">expanded-QName</a> of any element or attribute
|
|
node in the result tree: that is, it will never change the
|
|
namespace URI of an element or attribute. It might, however,
|
|
constrain the choice of prefixes when namespace fixup is
|
|
performed.</p>
|
|
<p>Namespace prefixes for element and attribute names are initially
|
|
established by the rules of the instruction that creates the
|
|
element or attribute node, and in the event of conflicts, they may
|
|
be changed by the namespace fixup process described in <a href=
|
|
"#namespace-fixup"><i>5.7.3 Namespace Fixup</i></a>. The fixup
|
|
process ensures that an element has in-scope namespace nodes for
|
|
the namespace URIs used in the element name and in its attribute
|
|
names, and the serializer will typically use these namespace nodes
|
|
to determine the prefix to use in the serialized output. The fixup
|
|
process cannot generate namespace nodes that are inconsistent with
|
|
those already present in the tree. This means that it is not
|
|
possible for the processor to decide the prefix to use for an
|
|
element or for any of its attributes until all the namespace nodes
|
|
for the element have been added.</p>
|
|
<p>If a namespace prefix is mapped to a particular namespace URI
|
|
using the <a href=
|
|
"#element-namespace"><code>xsl:namespace</code></a> instruction, or
|
|
by using <a href="#element-copy"><code>xsl:copy</code></a> or
|
|
<a href="#element-copy-of"><code>xsl:copy-of</code></a> to copy a
|
|
namespace node, this prevents the namespace fixup process (and
|
|
hence the serializer) from using the same prefix for a different
|
|
namespace URI on the same element.</p>
|
|
</div>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e21885" id=
|
|
"d7e21885"></a>Example: Conflicting Namespace Prefixes</div>
|
|
<p>Given the instruction:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:element name="p:item"
|
|
xmlns:p="http://www.example.com/p">
|
|
<xsl:namespace name="p">http://www.example.com/q</xsl:namespace>
|
|
</xsl:element>
|
|
</pre></div>
|
|
<p>a possible serialization of the <a title="result tree" class=
|
|
"termref" href="#dt-result-tree">result tree</a> is:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<ns0:item
|
|
xmlns:ns0="http://www.example.com/p"
|
|
xmlns:p="http://www.example.com/q"/>
|
|
</pre></div>
|
|
<p>The processor must invent a namespace prefix for the URI
|
|
<code>p.uri</code>; it cannot use the prefix <code>p</code> because
|
|
that prefix has been explicitly associated with a different
|
|
URI.</p>
|
|
</div>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>The <a href="#element-namespace"><code>xsl:namespace</code></a>
|
|
instruction cannot be used to generate a <b>namespace
|
|
undeclaration</b> of the form <code>xmlns=""</code> (nor the new
|
|
forms of namespace undeclaration permitted in <a href=
|
|
"#xml-names11">[Namespaces in XML 1.1]</a>). Namespace
|
|
undeclarations are generated automatically by the serializer if
|
|
<code>undeclare-prefixes="yes"</code> is specified on <a href=
|
|
"#element-output"><code>xsl:output</code></a>, whenever a parent
|
|
element has a namespace node for the default namespace prefix, and
|
|
a child element has no namespace node for that prefix.</p>
|
|
</div>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="creating-comments" id="creating-comments"></a>11.8
|
|
<a href="#creating-comments" style="text-decoration: none">Creating
|
|
Comments</a></h3>
|
|
<p class="element-syntax"><a name="element-comment" id=
|
|
"element-comment"></a><code><!-- Category: instruction
|
|
--><br />
|
|
<xsl:comment<br />
|
|
  select? = <var>expression</var> ><br />
|
|
  <!-- Content: <var>sequence-constructor</var>
|
|
--><br />
|
|
</xsl:comment></code></p>
|
|
<p>The <a href="#element-comment"><code>xsl:comment</code></a>
|
|
element is evaluated to construct a new comment node. Except in
|
|
error cases, the result of evaluating the <a href=
|
|
"#element-comment"><code>xsl:comment</code></a> instruction is a
|
|
single node, the newly constructed comment node.</p>
|
|
<p>The string value of the new comment node may be defined either
|
|
by using the <code>select</code> attribute, or by the <a title=
|
|
"sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> that forms the
|
|
content of the <a href=
|
|
"#element-comment"><code>xsl:comment</code></a> element. These are
|
|
mutually exclusive. If neither is present, the value of the new
|
|
comment node will be a zero-length string. The way in which the
|
|
value is constructed is specified in <a href=
|
|
"#constructing-simple-content"><i>5.7.2 Constructing Simple
|
|
Content</i></a>.</p>
|
|
<p><a name="err-XTSE0940" id="err-XTSE0940"><span class=
|
|
"error">[ERR XTSE0940]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> if the
|
|
<code>select</code> attribute of the <a href=
|
|
"#element-comment"><code>xsl:comment</code></a> element is present
|
|
unless the element has empty content.</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e21974" id=
|
|
"d7e21974"></a>Example: Generating a Comment Node</div>
|
|
<p>For example, this</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:comment>This file is automatically generated. Do not edit!</xsl:comment>
|
|
</pre></div>
|
|
<p>would create the comment</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<!--This file is automatically generated. Do not edit!-->
|
|
</pre></div>
|
|
</div>
|
|
<p>In the generated comment node, the processor <span class=
|
|
"verb">must</span> insert a space after any occurrence of
|
|
<code>-</code> that is followed by another <code>-</code> or that
|
|
ends the comment.</p>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="copying" id="copying"></a>11.9 <a href="#copying"
|
|
style="text-decoration: none">Copying Nodes</a></h3>
|
|
<div class="div3">
|
|
<h4><a name="shallow-copy" id="shallow-copy"></a>11.9.1 <a href=
|
|
"#shallow-copy" style="text-decoration: none">Shallow Copy</a></h4>
|
|
<p class="element-syntax"><a name="element-copy" id=
|
|
"element-copy"></a><code><!-- Category: instruction --><br />
|
|
<xsl:copy<br />
|
|
  select? = <var>expression</var><br />
|
|
  copy-namespaces? = "yes" | "no"<br />
|
|
  inherit-namespaces? = "yes" | "no"<br />
|
|
  use-attribute-sets? = <var>qnames</var><br />
|
|
  type? = <var>qname</var><br />
|
|
  validation? = "strict" | "lax" | "preserve" |
|
|
"strip" ><br />
|
|
  <!-- Content: <var>sequence-constructor</var>
|
|
--><br />
|
|
</xsl:copy></code></p>
|
|
<p>The <a href="#element-copy"><code>xsl:copy</code></a>
|
|
instruction provides a way of copying <span>a selected item. The
|
|
selected item is the item selected by evaluating the expression in
|
|
the <code>select</code> attribute if present, or the <a title=
|
|
"context item" class="termref" href="#dt-context-item">context
|
|
item</a> otherwise</span>. If the selected item is a node,
|
|
evaluating the <a href="#element-copy"><code>xsl:copy</code></a>
|
|
instruction constructs a copy of the selected node, and the result
|
|
of the <a href="#element-copy"><code>xsl:copy</code></a>
|
|
instruction is this newly constructed node. By default, the
|
|
namespace nodes of the context node are automatically copied as
|
|
well, but the attributes and children of the node are not
|
|
automatically copied.</p>
|
|
<p>When the <span>selected item</span> is an atomic value <span>or
|
|
function item</span>, the <a href=
|
|
"#element-copy"><code>xsl:copy</code></a> instruction returns this
|
|
value. The <a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a>, if present, is
|
|
not evaluated, <span>and <span class="verb">must not</span>
|
|
generate any <a title="type errors" class="termref" href=
|
|
"#dt-type-error">type errors</a>.</span></p>
|
|
<p>When the <span>selected item</span> is an attribute node, text
|
|
node, comment node, processing instruction node, or namespace node,
|
|
the <a href="#element-copy"><code>xsl:copy</code></a> instruction
|
|
returns a new node that is a copy of the context node. The new node
|
|
will have the same node kind, name, and string value as the context
|
|
node. In the case of an attribute node, it will also have the same
|
|
values for the <code>is-id</code> and <code>is-idrefs</code>
|
|
properties. The <a title="sequence constructor" class="termref"
|
|
href="#dt-sequence-constructor">sequence constructor</a>, if
|
|
present, is not evaluated, <span>and <span class="verb">must
|
|
not</span> generate any <a title="type errors" class="termref"
|
|
href="#dt-type-error">type errors</a>.</span>.</p>
|
|
<p>When the <span>selected item</span> is a document node or
|
|
element node, the <a href="#element-copy"><code>xsl:copy</code></a>
|
|
instruction returns a new node that has the same node kind and name
|
|
as the <span>selected</span> node. The content of the new node is
|
|
formed by evaluating the <a title="sequence constructor" class=
|
|
"termref" href="#dt-sequence-constructor">sequence constructor</a>
|
|
contained in the <a href="#element-copy"><code>xsl:copy</code></a>
|
|
instruction. The sequence obtained by evaluating this sequence
|
|
constructor is used (after prepending any attribute nodes or
|
|
namespace nodes as described in the following paragraphs) to
|
|
construct the content of the document or element node, as described
|
|
in <a href="#constructing-complex-content"><i>5.7.1 Constructing
|
|
Complex Content</i></a>.</p>
|
|
<p>If the <code>select</code> expression returns an empty sequence,
|
|
the <a href="#element-copy"><code>xsl:copy</code></a> instruction
|
|
returns an empty sequence, and the contained <a title=
|
|
"sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> is not
|
|
evaluated.</p>
|
|
<p><a name="err-XTTE2170" id="err-XTTE2170"><span class=
|
|
"error">[ERR XTTE2170]</span></a> It is a <a title="type errors"
|
|
class="termref" href="#dt-type-error">type error</a> if the result
|
|
of evaluating the <code>select</code> expression is a sequence of
|
|
more than one item.</p>
|
|
<p>The <a href="#element-copy"><code>xsl:copy</code></a>
|
|
instruction has an optional <code>use-attribute-sets</code>
|
|
attribute, whose value is a whitespace-separated list of QNames
|
|
that identify <a href=
|
|
"#element-attribute-set"><code>xsl:attribute-set</code></a>
|
|
declarations. This attribute is used only when copying element
|
|
nodes. This list is expanded as described in <a href=
|
|
"#attribute-sets"><i>10.2 Named Attribute Sets</i></a> to produce a
|
|
sequence of attribute nodes. This sequence is prepended to the
|
|
sequence produced as a result of evaluating the <a title=
|
|
"sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a>.</p>
|
|
<p>The <a href="#element-copy"><code>xsl:copy</code></a>
|
|
instruction has an optional <code>copy-namespaces</code> attribute,
|
|
with the value <code>yes</code> or <code>no</code>. The default
|
|
value is <code>yes</code>. The attribute is used only when copying
|
|
element nodes. If the value is set to <code>yes</code>, or is
|
|
omitted, then all the namespace nodes of the source element are
|
|
copied as namespace nodes for the result element. These copied
|
|
namespace nodes are prepended to the sequence produced as a result
|
|
of evaluating the <a title="sequence constructor" class="termref"
|
|
href="#dt-sequence-constructor">sequence constructor</a> (it is
|
|
immaterial whether they come before or after any attribute nodes
|
|
produced by expanding the <code>use-attribute-sets</code>
|
|
attribute). If the value is set to <code>no</code>, then the
|
|
namespace nodes are not copied. However, namespace nodes will still
|
|
be added to the result element as <span class=
|
|
"verb">required</span> by the namespace fixup process: see <a href=
|
|
"#namespace-fixup"><i>5.7.3 Namespace Fixup</i></a>.</p>
|
|
<p>The <a href="#element-copy"><code>xsl:copy</code></a>
|
|
instruction has an optional <code>inherit-namespaces</code>
|
|
attribute, with the value <code>yes</code> or <code>no</code>. The
|
|
default value is <code>yes</code>. The attribute is used only when
|
|
copying element nodes. If the value is set to <code>yes</code>, or
|
|
is omitted, then the namespace nodes created for the newly
|
|
constructed element (whether these were copied from those of the
|
|
source node, or generated as a result of namespace fixup) are
|
|
copied to the children and descendants of the newly constructed
|
|
element, as described in <a href=
|
|
"#constructing-complex-content"><i>5.7.1 Constructing Complex
|
|
Content</i></a>. If the value is set to <code>no</code>, then these
|
|
namespace nodes are not automatically copied to the children. This
|
|
may result in namespace undeclarations (such as
|
|
<code>xmlns=""</code> or, in the case of XML Namespaces 1.1,
|
|
<code>xmlns:p=""</code>) appearing on the child elements when a
|
|
<a title="final result tree" class="termref" href=
|
|
"#dt-final-result-tree">final result tree</a> is serialized.</p>
|
|
<p><a name="err-XTTE0950" id="err-XTTE0950"><span class=
|
|
"error">[ERR XTTE0950]</span></a> It is a <a title="type errors"
|
|
class="termref" href="#dt-type-error">type error</a> to use the
|
|
<a href="#element-copy"><code>xsl:copy</code></a> or <a href=
|
|
"#element-copy-of"><code>xsl:copy-of</code></a> instruction to copy
|
|
a node that has namespace-sensitive content if the
|
|
<code>copy-namespaces</code> attribute has the value
|
|
<code>no</code> and its explicit or implicit
|
|
<code>validation</code> attribute has the value
|
|
<code>preserve</code>. It is also a type error if either of these
|
|
instructions (with <code>validation="preserve"</code>) is used to
|
|
copy an attribute having namespace-sensitive content, unless the
|
|
parent element is also copied. A node has namespace-sensitive
|
|
content if its typed value contains an item of type
|
|
<code>xs:QName</code> or <code>xs:NOTATION</code> or a type derived
|
|
therefrom. The reason this is an error is because the validity of
|
|
the content depends on the namespace context being preserved.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>When attribute nodes are copied, whether with <a href=
|
|
"#element-copy"><code>xsl:copy</code></a> or with <a href=
|
|
"#element-copy-of"><code>xsl:copy-of</code></a>, the processor does
|
|
not automatically copy any associated namespace information. The
|
|
namespace used in the attribute name itself will be declared by
|
|
virtue of the namespace fixup process (see <a href=
|
|
"#namespace-fixup"><i>5.7.3 Namespace Fixup</i></a>) when the
|
|
attribute is added to an element in the <a title="result tree"
|
|
class="termref" href="#dt-result-tree">result tree</a>, but if
|
|
namespace prefixes are used in the content of the attribute (for
|
|
example, if the value of the attribute is an XPath expression) then
|
|
it is the responsibility of the stylesheet author to ensure that
|
|
suitable namespace nodes are added to the <a title="result tree"
|
|
class="termref" href="#dt-result-tree">result tree</a>. This can be
|
|
achieved by copying the namespace nodes using <a href=
|
|
"#element-copy"><code>xsl:copy</code></a>, or by generating them
|
|
using <a href=
|
|
"#element-namespace"><code>xsl:namespace</code></a>.</p>
|
|
</div>
|
|
<p>The optional attributes <code>type</code> and
|
|
<code>validation</code> may be used on the <a href=
|
|
"#element-copy"><code>xsl:copy</code></a> instruction to validate
|
|
the contents of an element, attribute or document node against a
|
|
type definition, element declaration, or attribute declaration in a
|
|
schema, and thus to determine the <a title="type annotation" class=
|
|
"termref" href="#dt-annotation">type annotation</a> that the new
|
|
copy of an element or attribute node will carry. These attributes
|
|
are ignored when copying an item that is not an element, attribute
|
|
or document node. When the node being copied is an element or
|
|
document node, these attributes also affect the type annotation
|
|
carried by any elements and attributes that have the copied element
|
|
or document node as an ancestor. These two attributes are both
|
|
optional, and if one is specified then the other <span class=
|
|
"verb">must</span> be omitted. The permitted values of these
|
|
attributes and their semantics are described in <a href=
|
|
"#validation"><i>22.2 Validation</i></a>.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>The final <a title="type annotation" class="termref" href=
|
|
"#dt-annotation">type annotation</a> of the node in the <a title=
|
|
"result tree" class="termref" href="#dt-result-tree">result
|
|
tree</a> also depends on the <code>type</code> and
|
|
<code>validation</code> attributes of the instructions used to
|
|
create the ancestors of the node.</p>
|
|
</div>
|
|
<p>The base URI of a node is copied, except in the case of an
|
|
element node having an <code>xml:base</code> attribute, in which
|
|
case the base URI of the new node is taken as the value of the
|
|
<code>xml:base</code> attribute, resolved if it is relative against
|
|
the base URI of the <a href=
|
|
"#element-copy"><code>xsl:copy</code></a> instruction. If the
|
|
copied node is subsequently attached as a child to a new element or
|
|
document node, the final copy of the node inherits its base URI
|
|
from its parent node, unless this is overridden using an
|
|
<code>xml:base</code> attribute.</p>
|
|
<p>When an <code>xml:id</code> attribute is copied, using either
|
|
the <a href="#element-copy"><code>xsl:copy</code></a> or <a href=
|
|
"#element-copy-of"><code>xsl:copy-of</code></a> instruction, it is
|
|
<a title="implementation-defined" class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a> whether the
|
|
value of the attribute is subjected to attribute value
|
|
normalization (that is, effectively applying the <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-normalize-space"><code>
|
|
normalize-space</code></a><sup><small>FO</small></sup>
|
|
function).</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>In most cases the value will already have been subjected to
|
|
attribute value normalization on the source tree, but if this
|
|
processing has not been performed on the source tree, it is not an
|
|
error for it to be performed on the result tree.</p>
|
|
</div>
|
|
<blockquote>
|
|
<p><b><a name="issue-context-in-shallow-copy" id=
|
|
"issue-context-in-shallow-copy">Issue 14
|
|
(context-in-shallow-copy)</a>:</b></p>
|
|
<p>Should the contained sequence constructor be evaluated with the
|
|
selected node as the context item? Use cases such as use in
|
|
<a href="#element-function"><code>xsl:function</code></a> probably
|
|
would suggest yes.</p>
|
|
</blockquote>
|
|
</div>
|
|
<div class="div3">
|
|
<h4><a name="copy-of" id="copy-of"></a>11.9.2 <a href="#copy-of"
|
|
style="text-decoration: none">Deep Copy</a></h4>
|
|
<p class="element-syntax"><a name="element-copy-of" id=
|
|
"element-copy-of"></a><code><!-- Category: instruction
|
|
--><br />
|
|
<xsl:copy-of<br />
|
|
  <b>select</b> = <var>expression</var><br />
|
|
  copy-namespaces? = "yes" | "no"<br />
|
|
  type? = <var>qname</var><br />
|
|
  validation? = "strict" | "lax" | "preserve" |
|
|
"strip" /></code></p>
|
|
<p>The <a href="#element-copy-of"><code>xsl:copy-of</code></a>
|
|
instruction can be used to construct a copy of a sequence of nodes,
|
|
atomic values, <span>and/or function items</span> with each new
|
|
node containing copies of all the children, attributes, and (by
|
|
default) namespaces of the original node, recursively. The result
|
|
of evaluating the instruction is a sequence of items corresponding
|
|
one-to-one with the supplied sequence, and retaining its order.</p>
|
|
<p>The <span class="verb">required</span> <code>select</code>
|
|
attribute contains an <a title="expression" class="termref" href=
|
|
"#dt-expression">expression</a>, whose value may be any sequence of
|
|
nodes, atomic values, <span>and/or function items</span>. The items
|
|
in this sequence are processed as follows:</p>
|
|
<ul>
|
|
<li>
|
|
<p>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
|
|
<a title="expanded-QName" class="termref" href=
|
|
"#dt-expanded-qname">expanded-QName</a> as the original, and it
|
|
will have deep copies of the attribute nodes and children of the
|
|
element node.</p>
|
|
<p>The new element will also have namespace nodes copied from the
|
|
original element node, unless they are excluded by specifying
|
|
<code>copy-namespaces="no"</code>. If this attribute is omitted, or
|
|
takes the value <code>yes</code>, then all the namespace nodes of
|
|
the original element are copied to the new element. If it takes the
|
|
value <code>no</code>, then none of the namespace nodes are copied:
|
|
however, namespace nodes will still be created in the <a title=
|
|
"result tree" class="termref" href="#dt-result-tree">result
|
|
tree</a> as <span class="verb">required</span> by the namespace
|
|
fixup process: see <a href="#namespace-fixup"><i>5.7.3 Namespace
|
|
Fixup</i></a>. This attribute affects all elements copied by this
|
|
instruction: both elements selected directly by the
|
|
<code>select</code> <a title="expression" class="termref" href=
|
|
"#dt-expression">expression</a>, and elements that are descendants
|
|
of nodes selected by the <code>select</code> expression.</p>
|
|
<p>The new element will have the same values of the
|
|
<code>is-id</code>, <code>is-idrefs</code>, and <code>nilled</code>
|
|
properties as the original element.</p>
|
|
</li>
|
|
<li>
|
|
<p>If the item is a document node, the instruction adds a new
|
|
document node to the result sequence; the children of this document
|
|
node will be one-to-one copies of the children of the original
|
|
document node (each copied according to the rules for its own node
|
|
kind).</p>
|
|
</li>
|
|
<li>
|
|
<p>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
|
|
<a href="#element-copy"><code>xsl:copy</code></a> (see <a href=
|
|
"#shallow-copy"><i>11.9.1 Shallow Copy</i></a>).</p>
|
|
</li>
|
|
<li>
|
|
<p>If the item is an atomic value <span>or a function item</span>,
|
|
the value is appended to the result sequence, as with <a href=
|
|
"#element-sequence"><code>xsl:sequence</code></a>.</p>
|
|
</li>
|
|
</ul>
|
|
<p>The optional attributes <code>type</code> and
|
|
<code>validation</code> may be used on the <a href=
|
|
"#element-copy-of"><code>xsl:copy-of</code></a> instruction to
|
|
validate the contents of an element, attribute or document node
|
|
against a type definition, element declaration, or attribute
|
|
declaration in a schema and thus to determine the <a title=
|
|
"type annotation" class="termref" href="#dt-annotation">type
|
|
annotation</a> that the new copy of an element or attribute node
|
|
will carry. These attributes are applied individually to each
|
|
element, attribute, and document node that is selected by the
|
|
expression in the <code>select</code> attribute. These attributes
|
|
are ignored when copying an item that is not an element, attribute
|
|
or document node.</p>
|
|
<p>The specified <code>type</code> and <code>validation</code>
|
|
apply directly only to elements, attributes and document nodes
|
|
created as copies of nodes actually selected by the
|
|
<code>select</code> expression, they do not apply to nodes that are
|
|
implicitly copied because they have selected nodes as an ancestor.
|
|
However, these attributes do indirectly affect the <a title=
|
|
"type annotation" class="termref" href="#dt-annotation">type
|
|
annotation</a> carried by such implicitly copied nodes, as a
|
|
consequence of the validation process.</p>
|
|
<p>These two attributes are both optional, and if one is specified
|
|
then the other <span class="verb">must</span> be omitted. The
|
|
permitted values of these attributes and their semantics are
|
|
described in <a href="#validation"><i>22.2 Validation</i></a>.</p>
|
|
<p>Errors may occur when copying namespace-sensitive elements or
|
|
attributes using <code>validation="preserve"</code>. <span class=
|
|
"error">[see <a href="#err-XTTE0950">ERR XTTE0950</a>]</span>.</p>
|
|
<p>The base URI of a node is copied, except in the case of an
|
|
element node having an <code>xml:base</code> attribute, in which
|
|
case the base URI of the new node is taken as the value of the
|
|
<code>xml:base</code> attribute, resolved if it is relative against
|
|
the base URI of the <a href=
|
|
"#element-copy-of"><code>xsl:copy-of</code></a> instruction. If the
|
|
copied node is subsequently attached as a child to a new element or
|
|
document node, the final copy of the node inherits its base URI
|
|
from its parent node, unless this is overridden using an
|
|
<code>xml:base</code> attribute.</p>
|
|
</div>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="constructing-sequences" id=
|
|
"constructing-sequences"></a>11.10 <a href=
|
|
"#constructing-sequences" style=
|
|
"text-decoration: none">Constructing Sequences</a></h3>
|
|
<p class="element-syntax"><a name="element-sequence" id=
|
|
"element-sequence"></a><code><!-- Category: instruction
|
|
--><br />
|
|
<xsl:sequence<br />
|
|
  <b>select</b> = <var>expression</var> ><br />
|
|
  <!-- Content: <var>sequence-constructor</var>
|
|
--><br />
|
|
</xsl:sequence></code></p>
|
|
<p>The <a href="#element-sequence"><code>xsl:sequence</code></a>
|
|
instruction may be used within a <a title="sequence constructor"
|
|
class="termref" href="#dt-sequence-constructor">sequence
|
|
constructor</a> to construct a sequence of nodes, atomic values,
|
|
<span>and/or function items</span>. This sequence is returned as
|
|
the result of the instruction. Unlike most other instructions,
|
|
<a href="#element-sequence"><code>xsl:sequence</code></a> can
|
|
return a sequence containing existing nodes, rather than
|
|
constructing new nodes. When <a href=
|
|
"#element-sequence"><code>xsl:sequence</code></a> is used to add
|
|
atomic values <span>or function items</span> to a sequence, the
|
|
effect is very similar to the <a href=
|
|
"#element-copy-of"><code>xsl:copy-of</code></a> instruction.</p>
|
|
<p>The items comprising the result sequence are evaluated either
|
|
using the <code>select</code> attribute, or using the contained
|
|
<a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a>. These are
|
|
mutually exclusive; if the instruction has a <code>select</code>
|
|
attribute, then it <span class="verb">must</span> have no children
|
|
other than <a href=
|
|
"#element-fallback"><code>xsl:fallback</code></a> instructions. If
|
|
there is no <code>select</code> attribute and no contained
|
|
<a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a>, the result is
|
|
an empty sequence.</p>
|
|
<p>Any contained <a href=
|
|
"#element-fallback"><code>xsl:fallback</code></a> instructions are
|
|
ignored by an XSLT 2.0 <span>or 2.1</span> processor, but can be
|
|
used to define fallback behavior for an XSLT 1.0 processor running
|
|
in forwards compatibility mode.</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e22613" id=
|
|
"d7e22613"></a>Example: Constructing a Sequence of Integers</div>
|
|
<p>For example, the following code:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:variable name="values" as="xs:integer*">
|
|
<xsl:sequence select="(1,2,3,4)"/>
|
|
<xsl:sequence select="(8,9,10)"/>
|
|
</xsl:variable>
|
|
<xsl:value-of select="sum($values)"/>
|
|
</pre></div>
|
|
<p>produces the output: <code>37</code></p>
|
|
</div>
|
|
<p> </p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e22625" id=
|
|
"d7e22625"></a>Example: Using <code>xsl:for-each</code> to
|
|
Construct a Sequence</div>
|
|
<p>The following code constructs a sequence containing the value of
|
|
the <code>@price</code> attribute for selected elements (which we
|
|
assume to be typed as <code>xs:decimal</code>), or a computed price
|
|
for those elements that have no <code>@price</code> attribute. It
|
|
then returns the average price:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:variable name="prices" as="xs:decimal*">
|
|
<xsl:for-each select="//product">
|
|
<xsl:choose>
|
|
<xsl:when test="@price">
|
|
<xsl:sequence select="@price"/>
|
|
</xsl:when>
|
|
<xsl:otherwise>
|
|
<xsl:sequence select="@cost * 1.5"/>
|
|
</xsl:otherwise>
|
|
</xsl:choose>
|
|
</xsl:for-each>
|
|
</xsl:variable>
|
|
<xsl:value-of select="avg($prices)"/>
|
|
</pre></div>
|
|
<p>Note that the existing <code>@price</code> attributes could
|
|
equally have been added to the <code>$prices</code> sequence using
|
|
<a href="#element-copy-of"><code>xsl:copy-of</code></a> or <a href=
|
|
"#element-value-of"><code>xsl:value-of</code></a>. However,
|
|
<a href="#element-copy-of"><code>xsl:copy-of</code></a> would
|
|
create a copy of the attribute node, which is not needed in this
|
|
situation, while <a href=
|
|
"#element-value-of"><code>xsl:value-of</code></a> would create a
|
|
new text node, which then has to be converted to an
|
|
<code>xs:decimal</code>. Using <a href=
|
|
"#element-sequence"><code>xsl:sequence</code></a>, which in this
|
|
case atomizes the existing attribute node and adds an
|
|
<code>xs:decimal</code> atomic value to the result sequence, is a
|
|
more direct way of achieving the same result.</p>
|
|
<p>This example could alternatively be solved at the XPath
|
|
level:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:value-of select="avg(//product/(+@price, @cost*1.5)[1])"/>
|
|
</pre></div>
|
|
<p>The apparently redundant <code>+</code> operator is there to
|
|
atomize the attribute value: the expression on the right hand side
|
|
of the <code>/</code> operator must not return a <span>sequence
|
|
containing both nodes and non-nodes (atomic values or function
|
|
items).</span></p>
|
|
</div>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>The main use case for allowing <a href=
|
|
"#element-sequence"><code>xsl:sequence</code></a> to contain a
|
|
sequence constructor is to allow the instructions within an
|
|
<a href="#element-fork"><code>xsl:fork</code></a> element to be
|
|
divided into groups.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="div1">
|
|
<h2><a name="number" id="number"></a>12 <a href="#number" style=
|
|
"text-decoration: none">Numbering</a></h2>
|
|
<p class="element-syntax"><a name="element-number" id=
|
|
"element-number"></a><code><!-- Category: instruction
|
|
--><br />
|
|
<xsl:number<br />
|
|
  value? = <var>expression</var><br />
|
|
  select? = <var>expression</var><br />
|
|
  level? = "single" | "multiple" | "any"<br />
|
|
  count? = <var>pattern</var><br />
|
|
  from? = <var>pattern</var><br />
|
|
  format? = { <var>string</var> }<br />
|
|
  lang? = { <var>nmtoken</var> }<br />
|
|
  letter-value? = { "alphabetic" | "traditional" }<br />
|
|
  ordinal? = { <var>string</var> }<br />
|
|
  grouping-separator? = { <var>char</var> }<br />
|
|
  grouping-size? = { <var>number</var>
|
|
} /></code></p>
|
|
<p>The <a href="#element-number"><code>xsl:number</code></a>
|
|
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 <a title="string value" class="termref"
|
|
href="#dt-string-value">string value</a>.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-place-marker" id="dt-place-marker" title="place marker"></a>The
|
|
<a href="#element-number"><code>xsl:number</code></a> instruction
|
|
performs two tasks: firstly, determining a <b>place marker</b>
|
|
(this is a sequence of integers, to allow for hierarchic numbering
|
|
schemes such as <code>1.12.2</code> or <code>3(c)ii</code>), and
|
|
secondly, formatting the place marker for output as a text node in
|
|
the result sequence.<span class="definition">]</span> The place
|
|
marker to be formatted can either be supplied directly, in the
|
|
<code>value</code> attribute, or it can be computed based on the
|
|
position of a selected node within the tree that contains it.</p>
|
|
<p><a name="err-XTSE0975" id="err-XTSE0975"><span class=
|
|
"error">[ERR XTSE0975]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> if the
|
|
<code>value</code> attribute of <a href=
|
|
"#element-number"><code>xsl:number</code></a> is present unless the
|
|
<code>select</code>, <code>level</code>, <code>count</code>, and
|
|
<code>from</code> attributes are all absent.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>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 <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-format-number"><code>
|
|
format-number</code></a><sup><small>FO</small></sup> function may
|
|
be more suitable: see <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-format-number">Section
|
|
4.6.2</a> <sup><small>FO11</small></sup>.</p>
|
|
<p>Furthermore, formatting of integers where there is no
|
|
requirement to calculate the position of a node in the document can
|
|
now be accomplished using the <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-format-number"><code>
|
|
format-number</code></a><sup><small>FO</small></sup> function,
|
|
which borrows many concepts from the <a href=
|
|
"#element-number"><code>xsl:number</code></a> specification.</p>
|
|
</div>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>See <a href="#expanding-xsl-number"><i>18.4.2.1 Expanding the
|
|
xsl:number instruction</i></a> for analysis of the effect of the
|
|
<a href="#element-number"><code>xsl:number</code></a> instruction
|
|
on streamability.</p>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="formatting-supplied-number" id=
|
|
"formatting-supplied-number"></a>12.1 <a href=
|
|
"#formatting-supplied-number" style=
|
|
"text-decoration: none">Formatting a Supplied Number</a></h3>
|
|
<p>The <a title="place marker" class="termref" href=
|
|
"#dt-place-marker">place marker</a> to be formatted may be
|
|
specified by an expression. The <code>value</code> attribute
|
|
contains the <a title="expression" class="termref" href=
|
|
"#dt-expression">expression</a>. The value of this expression is
|
|
<a title="atomize" class="termref" href=
|
|
"#dt-atomization">atomized</a> using the procedure defined in
|
|
<a href="#xpath-21">[XPath 2.1]</a>, and each value <var>$V</var>
|
|
in the atomized sequence is then converted to the integer value
|
|
returned by the XPath expression
|
|
<code>xs:integer(round(number($V)))</code>. The resulting sequence
|
|
of integers is used as the place marker to be formatted.</p>
|
|
<p>If the instruction is processed with <a title=
|
|
"XSLT 1.0 behavior" class="termref" href=
|
|
"#dt-xslt-10-behavior">XSLT 1.0 behavior</a>, then:</p>
|
|
<ul>
|
|
<li>
|
|
<p>all items in the <a title="atomize" class="termref" href=
|
|
"#dt-atomization">atomized</a> sequence after the first are
|
|
discarded;</p>
|
|
</li>
|
|
<li>
|
|
<p>If the atomized sequence is empty, it is replaced by a sequence
|
|
containing the <code>xs:double</code> value <code>NaN</code> as its
|
|
only item;</p>
|
|
</li>
|
|
<li>
|
|
<p>If any value in the sequence cannot be converted to an integer
|
|
(this includes the case where the sequence contains a
|
|
<code>NaN</code> value) then the string <code>NaN</code> is
|
|
inserted into the formatted result string in its proper position.
|
|
The error described in the following paragraph does not apply in
|
|
this case.</p>
|
|
</li>
|
|
</ul>
|
|
<p><a name="err-XTDE0980" id="err-XTDE0980"><span class=
|
|
"error">[ERR XTDE0980]</span></a> It is a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> if any
|
|
undiscarded item in the atomized sequence supplied as the value of
|
|
the <code>value</code> attribute of <a href=
|
|
"#element-number"><code>xsl:number</code></a> cannot be converted
|
|
to an integer, or if the resulting integer is less than 0
|
|
(zero).</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>The value zero does not arise when numbering nodes in a source
|
|
document, but it can arise in other numbering sequences. It is
|
|
permitted specifically because the rules of the <a href=
|
|
"#element-number"><code>xsl:number</code></a> instruction are also
|
|
invoked by functions such as <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-format-time"><code>format-time</code></a><sup><small>FO</small></sup>:
|
|
the minutes and seconds component of a time value can legitimately
|
|
be zero.</p>
|
|
</div>
|
|
<p>The resulting sequence is formatted as a string using the
|
|
<a title="effective value" class="termref" href=
|
|
"#dt-effective-value">effective values</a> of the attributes
|
|
specified in <a href="#convert"><i>12.3 Number to String Conversion
|
|
Attributes</i></a>; each of these attributes is interpreted as an
|
|
<a title="attribute value template" class="termref" href=
|
|
"#dt-attribute-value-template">attribute value template</a>. After
|
|
conversion, the <a href=
|
|
"#element-number"><code>xsl:number</code></a> element constructs a
|
|
new text node containing the resulting string, and returns this
|
|
node.</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e22911" id=
|
|
"d7e22911"></a>Example: Numbering a Sorted List</div>
|
|
<p>The following example numbers a sorted list:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<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>
|
|
</pre></div>
|
|
</div>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="numbering-based-on-position" id=
|
|
"numbering-based-on-position"></a>12.2 <a href=
|
|
"#numbering-based-on-position" style=
|
|
"text-decoration: none">Numbering based on Position in a
|
|
Document</a></h3>
|
|
<p>If no <code>value</code> attribute is specified, then the
|
|
<a href="#element-number"><code>xsl:number</code></a> instruction
|
|
returns a new text node containing a formatted <a title=
|
|
"place marker" class="termref" href="#dt-place-marker">place
|
|
marker</a> that is based on the position of a selected node within
|
|
its containing document. If the <code>select</code> attribute is
|
|
present, then the expression contained in the <code>select</code>
|
|
attribute is evaluated to determine the selected node. If the
|
|
<code>select</code> attribute is omitted, then the selected node is
|
|
the <a title="context node" class="termref" href=
|
|
"#dt-context-node">context node</a>.</p>
|
|
<p><a name="err-XTTE0990" id="err-XTTE0990"><span class=
|
|
"error">[ERR XTTE0990]</span></a> It is a <a title="type errors"
|
|
class="termref" href="#dt-type-error">type error</a> if the
|
|
<a href="#element-number"><code>xsl:number</code></a> instruction
|
|
is evaluated, with no <code>value</code> or <code>select</code>
|
|
attribute, when the <a title="context item" class="termref" href=
|
|
"#dt-context-item">context item</a> is not a node.</p>
|
|
<p><a name="err-XTTE1000" id="err-XTTE1000"><span class=
|
|
"error">[ERR XTTE1000]</span></a> It is a <a title="type errors"
|
|
class="termref" href="#dt-type-error">type error</a> if the result
|
|
of evaluating the <code>select</code> attribute of the <a href=
|
|
"#element-number"><code>xsl:number</code></a> instruction is
|
|
anything other than a single node.</p>
|
|
<p>The following attributes control how the selected node is to be
|
|
numbered:</p>
|
|
<ul>
|
|
<li>
|
|
<p>The <code>level</code> attribute specifies rules for selecting
|
|
the nodes that are taken into account in allocating a number; it
|
|
has the values <code>single</code>, <code>multiple</code> or
|
|
<code>any</code>. The default is <code>single</code>.</p>
|
|
</li>
|
|
<li>
|
|
<p>The <code>count</code> attribute is a <a title="pattern" class=
|
|
"termref" href="#dt-pattern">pattern</a> that specifies which nodes
|
|
are to be counted at those levels. If <code>count</code> attribute
|
|
is not specified, then it defaults to the pattern that matches any
|
|
node with the same node kind as the selected node and, if the
|
|
selected node has an <a title="expanded-QName" class="termref"
|
|
href="#dt-expanded-qname">expanded-QName</a>, with the same
|
|
<a title="expanded-QName" class="termref" href=
|
|
"#dt-expanded-qname">expanded-QName</a> as the selected node.</p>
|
|
</li>
|
|
<li>
|
|
<p>The <code>from</code> attribute is a <a title="pattern" class=
|
|
"termref" href="#dt-pattern">pattern</a> that specifies where
|
|
counting starts.</p>
|
|
</li>
|
|
</ul>
|
|
<p>In addition, the attributes specified in <a href=
|
|
"#convert"><i>12.3 Number to String Conversion Attributes</i></a>
|
|
are used for number to string conversion, as in the case when the
|
|
<code>value</code> attribute is specified.</p>
|
|
<p>The <a href="#element-number"><code>xsl:number</code></a>
|
|
element first constructs a sequence of positive integers using the
|
|
<code>level</code>, <code>count</code> and <code>from</code>
|
|
attributes. Where <code>level</code> is <code>single</code> or
|
|
<code>any</code>, this sequence will either be empty or contain a
|
|
single number; where <code>level</code> is <code>multiple</code>,
|
|
the sequence may be of any length. The sequence is constructed as
|
|
follows:</p>
|
|
<p>Let <code>matches-count($node)</code> be a function that returns
|
|
true if and only if the given node <code>$node</code> matches the
|
|
pattern given in the <code>count</code> attribute, or the implied
|
|
pattern (according to the rules given above) if the
|
|
<code>count</code> attribute is omitted.</p>
|
|
<p>Let <code>matches-from($node)</code> be a function that returns
|
|
true if and only if the given node <code>$node</code> matches the
|
|
pattern given in the <code>from</code> attribute, or if
|
|
<code>$node</code> is the root node of a tree. If the
|
|
<code>from</code> attribute is omitted, then the function returns
|
|
true if and only if <code>$node</code> is the root node of a
|
|
tree.</p>
|
|
<p>Let <code>$S</code> be the selected node.</p>
|
|
<p>When <code>level="single"</code>:</p>
|
|
<ul>
|
|
<li>
|
|
<p>Let <code>$A</code> be the node sequence selected by the
|
|
following expression:</p>
|
|
<p>
|
|
<code>   $S/ancestor-or-self::node()[matches-count(.)][1]</code></p>
|
|
<p>(this selects the innermost ancestor-or-self node that matches
|
|
the <code>count</code> pattern)</p>
|
|
</li>
|
|
<li>
|
|
<p>Let <code>$F</code> be the node sequence selected by the
|
|
expression</p>
|
|
<p>
|
|
<code>   $S/ancestor-or-self::node()[matches-from(.)][1]</code></p>
|
|
<p>(this selects the innermost ancestor-or-self node that matches
|
|
the <code>from</code> pattern):</p>
|
|
</li>
|
|
<li>
|
|
<p>Let <code>$AF</code> be the value of:</p>
|
|
<p><code>   $A[ancestor-or-self::node()[. is
|
|
$F]]</code></p>
|
|
<p>(this selects $A if it is in the subtree rooted at $F, or the
|
|
empty sequence otherwise)</p>
|
|
</li>
|
|
<li>
|
|
<p>If <code>$AF</code> is empty, return the empty sequence,
|
|
<code>()</code></p>
|
|
</li>
|
|
<li>
|
|
<p>Otherwise return the value of:</p>
|
|
<p><code>   1 +
|
|
count($AF/preceding-sibling::node()[matches-count(.)])</code></p>
|
|
<p>(the number of preceding siblings of the counted node that match
|
|
the <code>count</code> pattern, plus one).</p>
|
|
</li>
|
|
</ul>
|
|
<p>When <code>level="multiple"</code>:</p>
|
|
<ul>
|
|
<li>
|
|
<p>Let <code>$A</code> be the node sequence selected by the
|
|
expression</p>
|
|
<p>
|
|
<code>   $S/ancestor-or-self::node()[matches-count(.)]</code></p>
|
|
<p>(the set of ancestor-or-self nodes that match the
|
|
<code>count</code> pattern)</p>
|
|
</li>
|
|
<li>
|
|
<p>Let <code>$F</code> be the node sequence selected by the
|
|
expression</p>
|
|
<p>
|
|
<code>   $S/ancestor-or-self::node()[matches-from(.)][1]</code></p>
|
|
<p>(the innermost ancestor-or-self node that matches the
|
|
<code>from</code> pattern)</p>
|
|
</li>
|
|
<li>
|
|
<p>Let <code>$AF</code> be the value of</p>
|
|
<p><code>   $A[ancestor-or-self::node()[. is
|
|
$F]]</code></p>
|
|
<p>(the nodes selected in the first step that are in the subtree
|
|
rooted at the node selected in the second step)</p>
|
|
</li>
|
|
<li>
|
|
<p>Return the result of the expression</p>
|
|
<p><code>   for $af in $AF return
|
|
1+count($af/preceding-sibling::node()[matches-count(.)])</code></p>
|
|
<p>(a sequence of integers containing, for each of these nodes, one
|
|
plus the number of preceding siblings that match the
|
|
<code>count</code> pattern)</p>
|
|
</li>
|
|
</ul>
|
|
<p>When <code>level="any"</code>:</p>
|
|
<ul>
|
|
<li>
|
|
<p>Let <code>$A</code> be the node sequence selected by the
|
|
expression</p>
|
|
<p>
|
|
<code>   $S/(preceding::node()|ancestor-or-self::node())[matches-count(.)]</code></p>
|
|
<p>(the set of nodes consisting of the selected node together with
|
|
all nodes, other than attributes and namespaces, that precede the
|
|
selected node in document order, provided that they match the
|
|
<code>count</code> pattern)</p>
|
|
</li>
|
|
<li>
|
|
<p>Let <code>$F</code> be the node sequence selected by the
|
|
expression</p>
|
|
<p>
|
|
<code>   $S/(preceding::node()|ancestor::node())[matches-from(.)][last()]</code></p>
|
|
<p>(the last node in document order that matches the
|
|
<code>from</code> pattern and that precedes the selected node,
|
|
using the same definition)</p>
|
|
</li>
|
|
<li>
|
|
<p>Let <code>$AF</code> be the node sequence <code>$A[. is $F or .
|
|
>> $F]</code>.</p>
|
|
<p>(the nodes selected in the first step, excluding those that
|
|
precede the node selected in the second step)</p>
|
|
</li>
|
|
<li>
|
|
<p>If <code>$AF</code> is empty, return the empty sequence,
|
|
<code>()</code></p>
|
|
</li>
|
|
<li>
|
|
<p>Otherwise return the value of the expression
|
|
<code>count($AF)</code></p>
|
|
</li>
|
|
</ul>
|
|
<p>The sequence of numbers (the <a title="place marker" class=
|
|
"termref" href="#dt-place-marker">place marker</a>) is then
|
|
converted into a string using the <a title="effective value" class=
|
|
"termref" href="#dt-effective-value">effective values</a> of the
|
|
attributes specified in <a href="#convert"><i>12.3 Number to String
|
|
Conversion Attributes</i></a>; each of these attributes is
|
|
interpreted as an <a title="attribute value template" class=
|
|
"termref" href="#dt-attribute-value-template">attribute value
|
|
template</a>. After conversion, the resulting string is used to
|
|
create a text node, which forms the result of the <a href=
|
|
"#element-number"><code>xsl:number</code></a> instruction.</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e23324" id=
|
|
"d7e23324"></a>Example: Numbering the Items in an Ordered
|
|
List</div>
|
|
<p>The following will number the items in an ordered list:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:template match="ol/item">
|
|
<fo:block>
|
|
<xsl:number/>
|
|
<xsl:text>. </xsl:text>
|
|
<xsl:apply-templates/>
|
|
</fo:block>
|
|
</xsl:template>
|
|
</pre></div>
|
|
</div>
|
|
<p> </p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e23331" id=
|
|
"d7e23331"></a>Example: Multi-Level Numbering</div>
|
|
<p>The following two rules will number <code>title</code> elements.
|
|
This is intended for a document that contains a sequence of
|
|
chapters followed by a sequence of appendices, where both chapters
|
|
and appendices contain sections, which in turn contain subsections.
|
|
Chapters are numbered 1, 2, 3; appendices are numbered A, B, C;
|
|
sections in chapters are numbered 1.1, 1.2, 1.3; sections in
|
|
appendices are numbered A.1, A.2, A.3. Subsections within a chapter
|
|
are numbered 1.1.1, 1.1.2, 1.1.3; subsections within an appendix
|
|
are numbered A.1.1, A.1.2, A.1.3.</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<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>
|
|
</pre></div>
|
|
</div>
|
|
<p> </p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e23341" id=
|
|
"d7e23341"></a>Example: Numbering Notes within a Chapter</div>
|
|
<p>This example numbers notes sequentially within a chapter:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:template match="note">
|
|
<fo:block>
|
|
<xsl:number level="any" from="chapter" format="(1) "/>
|
|
<xsl:apply-templates/>
|
|
</fo:block>
|
|
</xsl:template>
|
|
</pre></div>
|
|
</div>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="convert" id="convert"></a>12.3 <a href="#convert"
|
|
style="text-decoration: none">Number to String Conversion
|
|
Attributes</a></h3>
|
|
<blockquote>
|
|
<p><b><a name="issue-refactor-format-integer" id=
|
|
"issue-refactor-format-integer">Issue 15
|
|
(refactor-format-integer)</a>:</b></p>
|
|
<p>The functionality described here has been encapsulated in a new
|
|
function, <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-format-integer"><code>
|
|
format-integer</code></a><sup><small>FO</small></sup>. The
|
|
specification can be simplified by referring to the specification
|
|
of that function.</p>
|
|
</blockquote>
|
|
<p>The following attributes are used to control conversion of a
|
|
sequence of numbers into a string. The numbers are integers greater
|
|
than or equal to 0 (zero). The attributes are all optional.</p>
|
|
<p>The main attribute is <code>format</code>. The default value for
|
|
the <code>format</code> attribute is <code>1</code>. The
|
|
<code>format</code> 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.
|
|
<em>Alphanumeric</em> means any character that has a Unicode
|
|
category of Nd, Nl, No, Lu, Ll, Lt, Lm or Lo. The alphanumeric
|
|
tokens (<em>format tokens</em>) indicate the format to be used for
|
|
each number in the sequence; in most cases the format token is the
|
|
same as the required representation of the number 1 (one).</p>
|
|
<p>Each non-alphanumeric token is either a prefix, a separator, or
|
|
a suffix. If there is a non-alphanumeric token but no format token,
|
|
then the single non-alphanumeric token is used as both the prefix
|
|
and the suffix. The prefix, if it exists, is the non-alphanumeric
|
|
token that precedes the first format token: the prefix always
|
|
appears exactly once in the constructed string, at the start. The
|
|
suffix, if it exists, is the non-alphanumeric token that follows
|
|
the last format token: the suffix always appears exactly once in
|
|
the constructed string, at the end. All other non-alphanumeric
|
|
tokens (those that occur between two format tokens) are
|
|
<em>separator tokens</em> and are used to separate numbers in the
|
|
sequence.</p>
|
|
<p>The <var>n</var>th format token is used to format the
|
|
<var>n</var>th number in the sequence. If there are more numbers
|
|
than format tokens, then the last format token is used to format
|
|
remaining numbers. If there are no format tokens, then a format
|
|
token of <code>1</code> is used to format all numbers. Each number
|
|
after the first is separated from the preceding number by the
|
|
separator token preceding the format token used to format that
|
|
number, or, if that is the first format token, then by
|
|
<code>.</code> (dot).</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e23399" id=
|
|
"d7e23399"></a>Example: Formatting a List of Numbers</div>
|
|
<p>Given the sequence of numbers <code>5, 13, 7</code> and the
|
|
format token <code>A-001(i)</code>, the output will be the string
|
|
<code>E-013(vii)</code></p>
|
|
</div>
|
|
<p>Format tokens are interpreted as follows:</p>
|
|
<ul>
|
|
<li>
|
|
<p>Any token where the last character has a decimal digit value of
|
|
1 (as specified in the Unicode character property database), and
|
|
the Unicode value of preceding characters is one less than the
|
|
Unicode value of the last character generates a decimal
|
|
representation of the number where each number is at least as long
|
|
as the format token. The digits used in the decimal representation
|
|
are the set of digits containing the digit character used in the
|
|
format token. Thus, a format token <code>1</code> generates the
|
|
sequence <code>0 1 2 ... 10 11 12 ...</code>, and a format token
|
|
<code>01</code> generates the sequence <code>00 01 02 ... 09 10 11
|
|
12 ... 99 100 101</code>. A format token of
|
|
<code>&#x661;</code> (Arabic-Indic digit one) generates the
|
|
sequence <code>١</code> then <code>٢</code> then <code>٣</code>
|
|
...</p>
|
|
</li>
|
|
<li>
|
|
<p>A format token <code>A</code> generates the sequence <code>A B C
|
|
... Z AA AB AC...</code>.</p>
|
|
</li>
|
|
<li>
|
|
<p>A format token <code>a</code> generates the sequence <code>a b c
|
|
... z aa ab ac...</code>.</p>
|
|
</li>
|
|
<li>
|
|
<p>A format token <code>i</code> generates the sequence <code>i ii
|
|
iii iv v vi vii viii ix x ...</code>.</p>
|
|
</li>
|
|
<li>
|
|
<p>A format token <code>I</code> generates the sequence <code>I II
|
|
III IV V VI VII VIII IX X ...</code>.</p>
|
|
</li>
|
|
<li>
|
|
<p>A format token <code>w</code> generates numbers written as
|
|
lower-case words, for example in English, <code>one two three four
|
|
...</code></p>
|
|
</li>
|
|
<li>
|
|
<p>A format token <code>W</code> generates numbers written as
|
|
upper-case words, for example in English, <code>ONE TWO THREE FOUR
|
|
...</code></p>
|
|
</li>
|
|
<li>
|
|
<p>A format token <code>Ww</code> generates numbers written as
|
|
title-case words, for example in English, <code>One Two Three Four
|
|
...</code></p>
|
|
</li>
|
|
<li>
|
|
<p>Any other format token indicates a numbering sequence in which
|
|
that token represents the number 1 (one) (but see the note below).
|
|
It is <a title="implementation-defined" class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a> which
|
|
numbering sequences, additional to those listed above, are
|
|
supported. If an implementation does not support a numbering
|
|
sequence represented by the given token, it <span class=
|
|
"verb">must</span> use a format token of <code>1</code>.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>In some traditional numbering sequences additional signs are
|
|
added to denote that the letters should be interpreted as numbers;
|
|
these are not included in the format token. An example, see also
|
|
the example below, is classical Greek where a <em>dexia keraia</em>
|
|
and sometimes an <em>aristeri keraia</em> is added.</p>
|
|
</div>
|
|
</li>
|
|
</ul>
|
|
<p>For all format tokens other than the first kind above (one that
|
|
consists of decimal digits), there <span class="verb">may</span> be
|
|
<a title="implementation-defined" class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a> lower and
|
|
upper bounds on the range of numbers that can be formatted using
|
|
this format token; indeed, for some numbering sequences there may
|
|
be intrinsic limits. For example, the formatting token
|
|
<code>&#x2460;</code> (circled digit one) has a range of 1 to
|
|
20 imposed by the Unicode character repertoire. For the numbering
|
|
sequences described above any upper bound imposed by the
|
|
implementation <span class="verb">must not</span> be less than 1000
|
|
(one thousand) and any lower bound must not be greater than 1.
|
|
Numbers that fall outside this range <span class="verb">must</span>
|
|
be formatted using the format token <code>1</code>. The numbering
|
|
sequence associated with the format token <code>1</code> has a
|
|
lower bound of 0 (zero).</p>
|
|
<p>The above expansions of numbering sequences for format tokens
|
|
such as <code>a</code> and <code>i</code> are indicative but not
|
|
prescriptive. There are various conventions in use for how
|
|
alphabetic sequences continue when the alphabet is exhausted, and
|
|
differing conventions for how roman numerals are written (for
|
|
example, <code>IV</code> versus <code>IIII</code> as the
|
|
representation of the number 4). Sometimes alphabetic sequences are
|
|
used that omit letters such as <code>i</code> and <code>o</code>.
|
|
This specification does not prescribe the detail of any sequence
|
|
other than those sequences consisting entirely of decimal
|
|
digits.</p>
|
|
<p>Many numbering sequences are language-sensitive. This applies
|
|
especially to the sequence selected by the tokens <code>w</code>,
|
|
<code>W</code> and <code>Ww</code>. It also applies to other
|
|
sequences, for example different languages using the Cyrillic
|
|
alphabet use different sequences of characters, each starting with
|
|
the letter #x410 (Cyrillic capital letter A). In such cases, the
|
|
<code>lang</code> attribute specifies which language's conventions
|
|
are to be used; it has the same range of values as
|
|
<code>xml:lang</code> (see <a href="#REC-xml">[XML 1.0]</a>). If no
|
|
<code>lang</code> value is specified, the language that is used is
|
|
<a title="implementation-defined" class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a>. The set of
|
|
languages for which numbering is supported is <a title=
|
|
"implementation-defined" class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a>. If a
|
|
language is requested that is not supported, the processor uses the
|
|
language that it would use if the <code>lang</code> attribute were
|
|
omitted.</p>
|
|
<p>If the optional <code>ordinal</code> attribute is present, and
|
|
if its value is not a zero-length string, this indicates a request
|
|
to output ordinal numbers rather than cardinal numbers. For
|
|
example, in English, the value <code>ordinal="yes"</code> when used
|
|
with the format token <code>1</code> outputs the sequence <code>1st
|
|
2nd 3rd 4th ...</code>, and when used with the format token
|
|
<code>w</code> outputs the sequence <code>first second third fourth
|
|
...</code>. In some languages, ordinal numbers vary depending on
|
|
the grammatical context, for example they may have different
|
|
genders and may decline with the noun that they qualify. In such
|
|
cases the value of the <code>ordinal</code> attribute may be used
|
|
to indicate the variation of the ordinal number required. The way
|
|
in which the variation is indicated will depend on the conventions
|
|
of the language. For inflected languages that vary the ending of
|
|
the word, the preferred approach is to indicate the required
|
|
ending, preceded by a hyphen: for example in German, appropriate
|
|
values are <code>-e, -er, -es, -en</code>. It is <a title=
|
|
"implementation-defined" class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a> what
|
|
combinations of values of the format token, the language, and the
|
|
<code>ordinal</code> attribute are supported. If ordinal numbering
|
|
is not supported for the combination of the format token, the
|
|
language, and the actual value of the <code>ordinal</code>
|
|
attribute, the request is ignored and cardinal numbers are
|
|
generated instead.</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e23673" id=
|
|
"d7e23673"></a>Example: Ordinal Numbering in Italian</div>
|
|
<p>The specification <code>format="1" ordinal="-º"
|
|
lang="it"</code>, if supported, should produce the sequence:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
1º 2º 3º 4º ...
|
|
</pre></div>
|
|
<p>The specification <code>format="Ww" ordinal="-o"
|
|
lang="it"</code>, if supported, should produce the sequence:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
Primo Secondo Terzo Quarto Quinto ...
|
|
</pre></div>
|
|
</div>
|
|
<p>The <code>letter-value</code> 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 <code>a</code> and <code>i</code>. In some languages, the
|
|
first member of each sequence is the same, and so the format token
|
|
alone would be ambiguous. A value of <code>alphabetic</code>
|
|
specifies the alphabetic sequence; a value of
|
|
<code>traditional</code> specifies the other sequence. If the
|
|
<code>letter-value</code> attribute is not specified, then it is
|
|
<a title="implementation-dependent" class="termref" href=
|
|
"#dt-implementation-dependent">implementation-dependent</a> how any
|
|
ambiguity is resolved.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>Implementations may use <a title="extension attribute" class=
|
|
"termref" href="#dt-extension-attribute">extension attributes</a>
|
|
on <a href="#element-number"><code>xsl:number</code></a> to provide
|
|
additional control over the way in which numbers are formatted.</p>
|
|
</div>
|
|
<p>The <code>grouping-separator</code> attribute gives the
|
|
separator used as a grouping (for example, thousands) separator in
|
|
decimal numbering sequences, and the optional
|
|
<code>grouping-size</code> specifies the size (normally 3) of the
|
|
grouping. For example, <code>grouping-separator=","</code> and
|
|
<code>grouping-size="3"</code> would produce numbers of the form
|
|
<code>1,000,000</code> while <code>grouping-separator="."</code>
|
|
and <code>grouping-size="2"</code> would produce numbers of the
|
|
form <code>1.00.00.00</code>. If only one of the
|
|
<code>grouping-separator</code> and <code>grouping-size</code>
|
|
attributes is specified, then it is ignored.</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e23756" id=
|
|
"d7e23756"></a>Example: Format Tokens and the Resulting
|
|
Sequences</div>
|
|
<p>These examples use non-Latin characters which might not display
|
|
correctly in all browsers, depending on the system
|
|
configuration.</p>
|
|
<table border="1" cellpadding="5">
|
|
<thead>
|
|
<tr>
|
|
<th align="left" colspan="1">Description</th>
|
|
<th align="left" colspan="1">Format Token</th>
|
|
<th align="left" colspan="1">Sequence</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>French cardinal words</td>
|
|
<td><code>format="Ww" lang="fr"</code></td>
|
|
<td>Un, Deux, Trois, Quatre</td>
|
|
</tr>
|
|
<tr>
|
|
<td>German ordinal words</td>
|
|
<td><code>format="w" ordinal="-e" lang="de"</code></td>
|
|
<td>erste, zweite, dritte, vierte</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Katakana numbering</td>
|
|
<td><code>format="&#x30A2;"</code></td>
|
|
<td>ア, イ, ウ, エ, オ, カ, キ, ク, ケ, コ, サ, シ, ス, セ, ソ, タ, チ, ツ, テ, ト, ナ,
|
|
ニ, ヌ, ネ, ノ, ハ, ヒ, フ, ヘ, ホ, マ, ミ, ム, メ, モ, ヤ, ユ, ヨ, ラ, リ, ル, レ, ロ,
|
|
ワ, ヰ, ヱ, ヲ, ン</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Katakana numbering in iroha order</td>
|
|
<td><code>format="&#x30A4;"</code></td>
|
|
<td>イ, ロ, ハ, ニ, ホ, ヘ, ト, チ, リ, ヌ, ル, ヲ, ワ, カ, ヨ, タ, レ, ソ, ツ, ネ, ナ,
|
|
ラ, ム, ウ, ヰ, ノ, オ, ク, ヤ, マ, ケ, フ, コ, エ, テ, ア, サ, キ, ユ, メ, ミ, シ, ヱ,
|
|
ヒ, モ, セ, ス</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Thai numbering</td>
|
|
<td><code>format="&#x0E51;"</code></td>
|
|
<td>๑, ๒, ๓, ๔, ๕, ๖, ๗, ๘, ๙, ๑๐, ๑๑, ๑๒, ๑๓, ๑๔, ๑๕, ๑๖, ๑๗, ๑๘,
|
|
๑๙, ๒๐</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Traditional Hebrew numbering</td>
|
|
<td><code>format="&#x05D0;"
|
|
letter-value="traditional"</code></td>
|
|
<td>א, ב, ג, ד, ה, ו, ז, ח, ט, י, יא, יב, יג, יד, טו, טז, יז, יח,
|
|
יט, כ</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Traditional Georgian numbering</td>
|
|
<td><code>format="&#x10D0;"
|
|
letter-value="traditional"</code></td>
|
|
<td>ა, ბ, გ, დ, ე, ვ, ზ, ჱ, თ, ი, ია, იბ, იგ, იდ, იე, ივ, იზ, იჱ,
|
|
ით, კ</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Classical Greek numbering (see note)</td>
|
|
<td><code>format="&#x03B1;"
|
|
letter-value="traditional"</code></td>
|
|
<td>αʹ, βʹ, γʹ, δʹ, εʹ, ϛʹ, ζʹ, ηʹ, θʹ, ιʹ, ιαʹ, ιβʹ, ιγʹ, ιδʹ,
|
|
ιεʹ, ιϛʹ, ιζʹ, ιηʹ, ιθʹ, κʹ</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Old Slavic numbering</td>
|
|
<td><code>format="&#x0430;"
|
|
letter-value="traditional"</code></td>
|
|
<td>А, В, Г, Д, Е, Ѕ, З, И, Ѳ, Ӏ, АӀ, ВӀ, ГӀ, ДӀ, ЕӀ, ЅӀ, ЗӀ, ИӀ,
|
|
ѲӀ, К</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>Note that Classical Greek is an example where the format token
|
|
is not the same as the representation of the number 1.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="div1">
|
|
<h2><a name="sorting" id="sorting"></a>13 <a href="#sorting" style=
|
|
"text-decoration: none">Sorting</a></h2>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-sort-key-specification" id="dt-sort-key-specification" title=
|
|
"sort key specification"></a>A <b>sort key specification</b> is a
|
|
sequence of one or more adjacent <a href=
|
|
"#element-sort"><code>xsl:sort</code></a> elements which together
|
|
define rules for sorting the items in an input sequence to form a
|
|
sorted sequence.<span class="definition">]</span></p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-sort-key-component" id="dt-sort-key-component" title=
|
|
"sort key component"></a>Within a <a title="sort key specification"
|
|
class="termref" href="#dt-sort-key-specification">sort key
|
|
specification</a>, each <a href=
|
|
"#element-sort"><code>xsl:sort</code></a> element defines one
|
|
<b>sort key component</b>.<span class="definition">]</span> The
|
|
first <a href="#element-sort"><code>xsl:sort</code></a> element
|
|
specifies the primary component of the sort key specification, the
|
|
second <a href="#element-sort"><code>xsl:sort</code></a> element
|
|
specifies the secondary component of the sort key specification,
|
|
and so on.</p>
|
|
<p>A sort key specification may occur immediately within an
|
|
<a href="#element-apply-templates"><code>xsl:apply-templates</code></a>,
|
|
<a href="#element-for-each"><code>xsl:for-each</code></a>, <a href=
|
|
"#element-perform-sort"><code>xsl:perform-sort</code></a>, or
|
|
<a href=
|
|
"#element-for-each-group"><code>xsl:for-each-group</code></a>
|
|
element.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>When used within <a href=
|
|
"#element-for-each"><code>xsl:for-each</code></a>, <a href=
|
|
"#element-for-each-group"><code>xsl:for-each-group</code></a>, or
|
|
<a href="#element-perform-sort"><code>xsl:perform-sort</code></a>,
|
|
<a href="#element-sort"><code>xsl:sort</code></a> elements must
|
|
occur before any other children.</p>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="xsl-sort" id="xsl-sort"></a>13.1 <a href="#xsl-sort"
|
|
style="text-decoration: none">The</a> <a href=
|
|
"#element-sort"><code>xsl:sort</code></a> <a href="#xsl-sort"
|
|
style="text-decoration: none">Element</a></h3>
|
|
<p class="element-syntax"><a name="element-sort" id=
|
|
"element-sort"></a><code><xsl:sort<br />
|
|
  select? = <var>expression</var><br />
|
|
  lang? = { <var>nmtoken</var> }<br />
|
|
  order? = { "ascending" | "descending" }<br />
|
|
  collation? = { <var>uri</var> }<br />
|
|
  stable? = { "yes" | "no" }<br />
|
|
  case-order? = { "upper-first" | "lower-first" }<br />
|
|
  data-type? = { "text" | "number" |
|
|
<var>qname-but-not-ncname</var> } ><br />
|
|
  <!-- Content: <var>sequence-constructor</var>
|
|
--><br />
|
|
</xsl:sort></code></p>
|
|
<p>The <a href="#element-sort"><code>xsl:sort</code></a> element
|
|
defines a <a title="sort key component" class="termref" href=
|
|
"#dt-sort-key-component">sort key component</a>. A sort key
|
|
component specifies how a <a title="sort key value" class="termref"
|
|
href="#dt-sort-key-value">sort key value</a> is to be computed for
|
|
each item in the sequence being sorted, and also how two sort key
|
|
values are to be compared.</p>
|
|
<p>The value of a <a title="sort key component" class="termref"
|
|
href="#dt-sort-key-component">sort key component</a> is determined
|
|
either by its <code>select</code> attribute or by the contained
|
|
<a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a>. If neither is
|
|
present, the default is <code>select="."</code>, which has the
|
|
effect of sorting on the actual value of the item if it is an
|
|
atomic value, or on the typed-value of the item if it is a node. If
|
|
a <code>select</code> attribute is present, its value <span class=
|
|
"verb">must</span> be an XPath <a title="expression" class=
|
|
"termref" href="#dt-expression">expression</a>.</p>
|
|
<p><a name="err-XTSE1015" id="err-XTSE1015"><span class=
|
|
"error">[ERR XTSE1015]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> if an
|
|
<a href="#element-sort"><code>xsl:sort</code></a> element with a
|
|
<code>select</code> attribute has non-empty content.</p>
|
|
<p>Those attributes of the <a href=
|
|
"#element-sort"><code>xsl:sort</code></a> elements whose values are
|
|
<a title="attribute value template" class="termref" href=
|
|
"#dt-attribute-value-template">attribute value templates</a> are
|
|
evaluated using the same <a title="focus" class="termref" href=
|
|
"#dt-focus">focus</a> as is used to evaluate the
|
|
<code>select</code> attribute of the containing instruction
|
|
(specifically, <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>,
|
|
<a href="#element-for-each"><code>xsl:for-each</code></a>, <a href=
|
|
"#element-for-each-group"><code>xsl:for-each-group</code></a>, or
|
|
<a href=
|
|
"#element-perform-sort"><code>xsl:perform-sort</code></a>).</p>
|
|
<p>The <code>stable</code> attribute is permitted only on the first
|
|
<a href="#element-sort"><code>xsl:sort</code></a> element within a
|
|
<a title="sort key specification" class="termref" href=
|
|
"#dt-sort-key-specification">sort key specification</a></p>
|
|
<p><a name="err-XTSE1017" id="err-XTSE1017"><span class=
|
|
"error">[ERR XTSE1017]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> if an
|
|
<a href="#element-sort"><code>xsl:sort</code></a> element other
|
|
than the first in a sequence of sibling <a href=
|
|
"#element-sort"><code>xsl:sort</code></a> elements has a
|
|
<code>stable</code> attribute.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-stable" id="dt-stable" title="stable"></a>A <a title=
|
|
"sort key specification" class="termref" href=
|
|
"#dt-sort-key-specification">sort key specification</a> is said to
|
|
be <b>stable</b> if its first <a href=
|
|
"#element-sort"><code>xsl:sort</code></a> element has no
|
|
<code>stable</code> attribute, or has a <code>stable</code>
|
|
attribute whose <a title="effective value" class="termref" href=
|
|
"#dt-effective-value">effective value</a> is
|
|
<code>yes</code>.<span class="definition">]</span></p>
|
|
<div class="div3">
|
|
<h4><a name="sorting-process" id="sorting-process"></a>13.1.1
|
|
<a href="#sorting-process" style="text-decoration: none">The
|
|
Sorting Process</a></h4>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-initial-sequence" id="dt-initial-sequence" title=
|
|
"initial sequence"></a>The sequence to be sorted is referred to as
|
|
the <b>initial sequence</b>.<span class="definition">]</span></p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-sorted-sequence" id="dt-sorted-sequence" title=
|
|
"sorted sequence"></a>The sequence after sorting as defined by the
|
|
<a href="#element-sort"><code>xsl:sort</code></a> elements is
|
|
referred to as the <b>sorted sequence</b>.<span class=
|
|
"definition">]</span></p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-sort-key-value" id="dt-sort-key-value" title=
|
|
"sort key value"></a> For each item in the <a title=
|
|
"initial sequence" class="termref" href=
|
|
"#dt-initial-sequence">initial sequence</a>, a value is computed
|
|
for each <a title="sort key component" class="termref" href=
|
|
"#dt-sort-key-component">sort key component</a> within the
|
|
<a title="sort key specification" class="termref" href=
|
|
"#dt-sort-key-specification">sort key specification</a>. The value
|
|
computed for an item by using the <var>N</var>th sort key component
|
|
is referred to as the <var>N</var>th <b>sort key value</b> of that
|
|
item.<span class="definition">]</span></p>
|
|
<p>The items in the <a title="initial sequence" class="termref"
|
|
href="#dt-initial-sequence">initial sequence</a> are ordered into a
|
|
<a title="sorted sequence" class="termref" href=
|
|
"#dt-sorted-sequence">sorted sequence</a> by comparing their
|
|
<a title="sort key value" class="termref" href=
|
|
"#dt-sort-key-value">sort key values</a>. The relative position of
|
|
two items <var>A</var> and <var>B</var> in the sorted sequence is
|
|
determined as follows. The first sort key value of <var>A</var> is
|
|
compared with the first sort key value of <var>B</var>, according
|
|
to the rules of the first <a title="sort key component" class=
|
|
"termref" href="#dt-sort-key-component">sort key component</a>. If,
|
|
under these rules, <var>A</var> is less than <var>B</var>, then
|
|
<var>A</var> will precede <var>B</var> in the sorted sequence,
|
|
unless the <code>order</code> attribute of this <a title=
|
|
"sort key component" class="termref" href=
|
|
"#dt-sort-key-component">sort key component</a> specifies
|
|
<code>descending</code>, in which case <var>B</var> will precede
|
|
<var>A</var> in the sorted sequence. If, however, the relevant sort
|
|
key values compare equal, then the second sort key value of
|
|
<var>A</var> is compared with the second sort key value of
|
|
<var>B</var>, according to the rules of the second <a title=
|
|
"sort key component" class="termref" href=
|
|
"#dt-sort-key-component">sort key component</a>. This continues
|
|
until two sort key values are found that compare unequal. If all
|
|
the sort key values compare equal, and the <a title=
|
|
"sort key specification" class="termref" href=
|
|
"#dt-sort-key-specification">sort key specification</a> is
|
|
<a title="stable" class="termref" href="#dt-stable">stable</a>,
|
|
then <var>A</var> will precede <var>B</var> in the <a title=
|
|
"sorted sequence" class="termref" href="#dt-sorted-sequence">sorted
|
|
sequence</a> if and only if <var>A</var> preceded <var>B</var> in
|
|
the <a title="initial sequence" class="termref" href=
|
|
"#dt-initial-sequence">initial sequence</a>. If all the sort key
|
|
values compare equal, and the <a title="sort key specification"
|
|
class="termref" href="#dt-sort-key-specification">sort key
|
|
specification</a> is not <a title="stable" class="termref" href=
|
|
"#dt-stable">stable</a>, then the relative order of <var>A</var>
|
|
and <var>B</var> in the <a title="sorted sequence" class="termref"
|
|
href="#dt-sorted-sequence">sorted sequence</a> is <a title=
|
|
"implementation-dependent" class="termref" href=
|
|
"#dt-implementation-dependent">implementation-dependent</a>.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>If two items have equal <a title="sort key value" class=
|
|
"termref" href="#dt-sort-key-value">sort key values</a>, and the
|
|
sort is <a title="stable" class="termref" href=
|
|
"#dt-stable">stable</a>, then their order in the <a title=
|
|
"sorted sequence" class="termref" href="#dt-sorted-sequence">sorted
|
|
sequence</a> will be the same as their order in the <a title=
|
|
"initial sequence" class="termref" href=
|
|
"#dt-initial-sequence">initial sequence</a>, regardless of whether
|
|
<code>order="descending"</code> was specified on any or all of the
|
|
<a title="sort key component" class="termref" href=
|
|
"#dt-sort-key-component">sort key components</a>.</p>
|
|
</div>
|
|
<p>The <var>N</var>th sort key value is computed by evaluating
|
|
either the <code>select</code> attribute or the contained <a title=
|
|
"sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> of the
|
|
<var>N</var>th <a href="#element-sort"><code>xsl:sort</code></a>
|
|
element, or the expression <code>.</code> (dot) if neither is
|
|
present. This evaluation is done with the <a title="focus" class=
|
|
"termref" href="#dt-focus">focus</a> set as follows:</p>
|
|
<ul>
|
|
<li>
|
|
<p>The <a title="context item" class="termref" href=
|
|
"#dt-context-item">context item</a> is the item in the <a title=
|
|
"initial sequence" class="termref" href=
|
|
"#dt-initial-sequence">initial sequence</a> whose <a title=
|
|
"sort key value" class="termref" href="#dt-sort-key-value">sort key
|
|
value</a> is being computed.</p>
|
|
</li>
|
|
<li>
|
|
<p>The <a title="context position" class="termref" href=
|
|
"#dt-context-position">context position</a> is the position of that
|
|
item in the initial sequence.</p>
|
|
</li>
|
|
<li>
|
|
<p>The <a title="context size" class="termref" href=
|
|
"#dt-context-size">context size</a> is the size of the initial
|
|
sequence.</p>
|
|
</li>
|
|
</ul>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>As in any other XPath expression, the <a href=
|
|
"#function-current"><code>current</code></a> function may be used
|
|
within the <code>select</code> expression of <a href=
|
|
"#element-sort"><code>xsl:sort</code></a> to refer to the item that
|
|
is the context item for the expression as a whole; that is, the
|
|
item whose <a title="sort key value" class="termref" href=
|
|
"#dt-sort-key-value">sort key value</a> is being computed.</p>
|
|
</div>
|
|
<p>The <a title="sort key value" class="termref" href=
|
|
"#dt-sort-key-value">sort key values</a> are <a title="atomize"
|
|
class="termref" href="#dt-atomization">atomized</a>, and are then
|
|
compared. The way they are compared depends on their data type, as
|
|
described in the next section.</p>
|
|
</div>
|
|
<div class="div3">
|
|
<h4><a name="comparing-sort-keys" id=
|
|
"comparing-sort-keys"></a>13.1.2 <a href="#comparing-sort-keys"
|
|
style="text-decoration: none">Comparing Sort Key Values</a></h4>
|
|
<p>It is possible to force the system to compare <a title=
|
|
"sort key value" class="termref" href="#dt-sort-key-value">sort key
|
|
values</a> using the rules for a particular data type by including
|
|
a cast as part of the <a title="sort key component" class="termref"
|
|
href="#dt-sort-key-component">sort key component</a>. For example,
|
|
<code><xsl:sort select="xs:date(@dob)"/></code> will force
|
|
the attributes to be compared as dates. In the absence of such a
|
|
cast, the sort key values are compared using the rules appropriate
|
|
to their data type. Any values of type
|
|
<code>xs:untypedAtomic</code> are cast to
|
|
<code>xs:string</code>.</p>
|
|
<p>For backwards compatibility with XSLT 1.0, the
|
|
<code>data-type</code> attribute remains available. If this has the
|
|
<a title="effective value" class="termref" href=
|
|
"#dt-effective-value">effective value</a> <code>text</code>, the
|
|
atomized <a title="sort key value" class="termref" href=
|
|
"#dt-sort-key-value">sort key values</a> are converted to strings
|
|
before being compared. If it has the effective value
|
|
<code>number</code>, the atomized sort key values are converted to
|
|
doubles before being compared. The conversion is done by using the
|
|
<a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-string"><code>string</code></a><sup><small>FO</small></sup>
|
|
or <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-number"><code>number</code></a><sup><small>FO</small></sup>
|
|
function as appropriate. If the <code>data-type</code> attribute
|
|
has any other <a title="effective value" class="termref" href=
|
|
"#dt-effective-value">effective value</a>, then the value
|
|
<span class="verb">must</span> be a <a title="lexical QName" class=
|
|
"termref" href="#dt-lexical-qname">lexical QName</a> with a
|
|
non-empty prefix, and the effect of the attribute is <a title=
|
|
"implementation-defined" class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a>.</p>
|
|
<p><a name="err-XTTE1020" id="err-XTTE1020"><span class=
|
|
"error">[ERR XTTE1020]</span></a> If any <a title="sort key value"
|
|
class="termref" href="#dt-sort-key-value">sort key value</a>, after
|
|
<a title="atomize" class="termref" href=
|
|
"#dt-atomization">atomization</a> and any type conversion
|
|
<span class="verb">required</span> by the <code>data-type</code>
|
|
attribute, is a sequence containing more than one item, then the
|
|
effect depends on whether the <a href=
|
|
"#element-sort"><code>xsl:sort</code></a> element <span>is
|
|
processed with <a title="XSLT 1.0 behavior" class="termref" href=
|
|
"#dt-xslt-10-behavior">XSLT 1.0 behavior</a>. With XSLT 1.0
|
|
behavior,</span> the effective sort key value is the first item in
|
|
the sequence. In other cases, this is a <a title="type errors"
|
|
class="termref" href="#dt-type-error">type error</a>.</p>
|
|
<p>The set of <a title="sort key value" class="termref" href=
|
|
"#dt-sort-key-value">sort key values</a> (after any conversion) is
|
|
first divided into two categories: empty values, and ordinary
|
|
values. The empty sort key values represent those items where the
|
|
sort key value is an empty sequence. These values are considered
|
|
for sorting purposes to be equal to each other, but less than any
|
|
other value. The remaining values are classified as ordinary
|
|
values.</p>
|
|
<p><a name="err-XTDE1030" id="err-XTDE1030"><span class=
|
|
"error">[ERR XTDE1030]</span></a> It is a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> if,
|
|
for any <a title="sort key component" class="termref" href=
|
|
"#dt-sort-key-component">sort key component</a>, the set of
|
|
<a title="sort key value" class="termref" href=
|
|
"#dt-sort-key-value">sort key values</a> evaluated for all the
|
|
items in the <a title="initial sequence" class="termref" href=
|
|
"#dt-initial-sequence">initial sequence</a>, after any type
|
|
conversion requested, contains a pair of ordinary values for which
|
|
the result of the XPath <code>lt</code> operator is an error.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>The above error condition may occur if the values to be sorted
|
|
are of a type that does not support ordering (for example,
|
|
<code>xs:QName</code>) or if the sequence is heterogeneous (for
|
|
example, if it contains both strings and numbers). The error can
|
|
generally be prevented by invoking a cast or constructor function
|
|
within the sort key component.</p>
|
|
<p>The error condition is subject to the usual caveat that a
|
|
processor is not required to evaluate any expression solely in
|
|
order to determine whether it raises an error. For example, if
|
|
there are several sort key components, then a processor is not
|
|
required to evaluate or compare minor sort key values unless the
|
|
corresponding major sort key values are equal.</p>
|
|
</div>
|
|
<p>In general, comparison of two ordinary values is performed
|
|
according to the rules of the XPath <code>lt</code> operator. To
|
|
ensure a total ordering, the same implementation of the
|
|
<code>lt</code> operator <span class="verb">must</span> be used for
|
|
all the comparisons: the one that is chosen is the one appropriate
|
|
to the most specific type to which all the values can be converted
|
|
by subtype substitution and/or type promotion. For example, if the
|
|
sequence contains both <code>xs:decimal</code> and
|
|
<code>xs:double</code> values, then the values are compared using
|
|
<code>xs:double</code> comparison, even when comparing two
|
|
<code>xs:decimal</code> values. NaN values, for sorting purposes,
|
|
are considered to be equal to each other, and less than any other
|
|
numeric value. Special rules also apply to the
|
|
<code>xs:string</code> and <code>xs:anyURI</code> types, and types
|
|
derived by restriction therefrom, as described in the next
|
|
section.</p>
|
|
</div>
|
|
<div class="div3">
|
|
<h4><a name="collating-sequences" id=
|
|
"collating-sequences"></a>13.1.3 <a href="#collating-sequences"
|
|
style="text-decoration: none">Sorting Using Collations</a></h4>
|
|
<p>The rules given in this section apply when comparing values
|
|
whose type is <code>xs:string</code> or a type derived by
|
|
restriction from <code>xs:string</code>, or whose type is
|
|
<code>xs:anyURI</code> or a type derived by restriction from
|
|
<code>xs:anyURI</code>.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-collation" id="dt-collation" title="collation"></a>Facilities
|
|
in XSLT <span>2.1</span> and XPath <span>2.1</span> that require
|
|
strings to be ordered rely on the concept of a named
|
|
<b>collation</b>. A collation is a set of rules that determine
|
|
whether two strings are equal, and if not, which of them is to be
|
|
sorted before the other.<span class="definition">]</span> A
|
|
collation is identified by a URI, but the manner in which this URI
|
|
is associated with an actual rule or algorithm is <a title=
|
|
"implementation-defined" class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a>.</p>
|
|
<p>The one collation URI that <span class="verb">must</span> be
|
|
recognized by every implementation is
|
|
<code>http://www.w3.org/2005/xpath-functions/collation/codepoint</code>,
|
|
which provides the ability to compare strings based on the Unicode
|
|
codepoint values of the characters in the string.</p>
|
|
<p>For more information about collations, see <a href=
|
|
"http://www.w3.org/TR/xpath-functions/#string-compare">Section 7.3
|
|
Equality and Comparison of Strings</a><sup><small>FO</small></sup>
|
|
in <a href="#xpath-functions-11">[Functions and Operators]</a>.
|
|
Some specifications, for example <a href="#UNICODE-TR10">[UNICODE
|
|
TR10]</a>, use the term "collation" to describe rules that can be
|
|
tailored or parameterized for various purposes. In this
|
|
specification, a collation URI refers to a collation in which all
|
|
such parameters have already been fixed. Therefore, if a collation
|
|
URI is specified, other attributes such as <code>case-order</code>
|
|
and <code>lang</code> are ignored.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>The reason XSLT does not provide detailed mechanisms for
|
|
defining collating sequences is that many implementations will
|
|
re-use collating mechanisms available from the underlying
|
|
implementation platform (for example, from the operating system or
|
|
from the run-time library of a chosen programming language). These
|
|
will inevitably differ from one XSLT implementation to another.</p>
|
|
</div>
|
|
<p>If the <a href="#element-sort"><code>xsl:sort</code></a> element
|
|
has a <code>collation</code> attribute, then the strings are
|
|
compared according to the rules for the named <a title="collation"
|
|
class="termref" href="#dt-collation">collation</a>: that is, they
|
|
are compared using the XPath function call <code>compare($a, $b,
|
|
$collation)</code>.</p>
|
|
<p>If the <a title="effective value" class="termref" href=
|
|
"#dt-effective-value">effective value</a> of the
|
|
<code>collation</code> attribute of <a href=
|
|
"#element-sort"><code>xsl:sort</code></a> is a relative URI, then
|
|
it is resolved against the base URI of the <a href=
|
|
"#element-sort"><code>xsl:sort</code></a> element.</p>
|
|
<p><a name="err-XTDE1035" id="err-XTDE1035"><span class=
|
|
"error">[ERR XTDE1035]</span></a> It is a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> if the
|
|
<code>collation</code> attribute of <a href=
|
|
"#element-sort"><code>xsl:sort</code></a> (after resolving against
|
|
the base URI) is not a URI that is recognized by the implementation
|
|
as referring to a collation.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>It is entirely for the implementation to determine whether it
|
|
recognizes a particular collation URI. For example, if the
|
|
implementation allows collation URIs to contain parameters in the
|
|
query part of the URI, it is the implementation that determines
|
|
whether a URI containing an unknown or invalid parameter is or is
|
|
not a recognized collation URI. The fact that this error is
|
|
described as non-recoverable thus does not prevent an
|
|
implementation applying a fallback collation if it chooses to do
|
|
so.</p>
|
|
</div>
|
|
<p>The <code>lang</code> and <code>case-order</code> attributes are
|
|
ignored if a <code>collation</code> attribute is present. But in
|
|
the absence of a <code>collation</code> attribute, these attributes
|
|
provide input to an <a title="implementation-defined" class=
|
|
"termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a> algorithm
|
|
to locate a suitable collation:</p>
|
|
<ul>
|
|
<li>
|
|
<p>The <code>lang</code> attribute indicates that a collation
|
|
suitable for a particular natural language <span class=
|
|
"verb">should</span> be used. The <a title="effective value" class=
|
|
"termref" href="#dt-effective-value">effective value</a> of the
|
|
attribute <span class="verb">must</span> be a value that would be
|
|
valid for the <code>xml:lang</code> attribute (see <a href=
|
|
"#REC-xml">[XML 1.0]</a>).</p>
|
|
</li>
|
|
<li>
|
|
<p>The <code>case-order</code> attribute indicates whether the
|
|
desired collation <span class="verb">should</span> sort upper-case
|
|
letters before lower-case or vice versa. The <a title=
|
|
"effective value" class="termref" href=
|
|
"#dt-effective-value">effective value</a> of the attribute
|
|
<span class="verb">must</span> be either <code>lower-first</code>
|
|
(indicating that lower-case letters precede upper-case letters in
|
|
the collating sequence) or <code>upper-first</code> (indicating
|
|
that upper-case letters precede lower-case).</p>
|
|
<p>When <code>lower-first</code> is requested, the returned
|
|
collation <span class="verb">should</span> have the property that
|
|
when two strings differ only in the case of one or more characters,
|
|
then a string in which the first differing character is lower-case
|
|
should precede a string in which the corresponding character is
|
|
title-case, which should in turn precede a string in which the
|
|
corresponding character is upper-case. When upper-first is
|
|
requested, the returned collation <span class="verb">should</span>
|
|
have the property that when two strings differ only in the case of
|
|
one or more characters, then a string in which the first differing
|
|
character is upper-case should precede a string in which the
|
|
corresponding character is title-case, which should in turn precede
|
|
a string in which the corresponding character is lower-case.</p>
|
|
<p>So, for example, if <code>lang="en"</code>, then <code>A a B
|
|
b</code> are sorted with <code>case-order="upper-first"</code> and
|
|
<code>a A b B</code> are sorted with
|
|
<code>case-order="lower-first"</code>.</p>
|
|
<p>As a further example, if lower-first is requested, then a sorted
|
|
sequence might be "MacAndrew, macintosh, macIntosh, Macintosh,
|
|
MacIntosh, macintoshes, Macintoshes, McIntosh". If upper-first is
|
|
requested, the same sequence would sort as "MacAndrew, MacIntosh,
|
|
Macintosh, macIntosh, macintosh, MacIntoshes, macintoshes,
|
|
McIntosh".</p>
|
|
</li>
|
|
</ul>
|
|
<p>If none of the <code>collation</code>, <code>lang</code>, or
|
|
<code>case-order</code> attributes is present, the collation is
|
|
chosen in an <a title="implementation-defined" class="termref"
|
|
href="#dt-implementation-defined">implementation-defined</a> way.
|
|
It is not <span class="verb">required</span> that the default
|
|
collation for sorting should be the same as the <a title=
|
|
"default collation" class="termref" href=
|
|
"#dt-default-collation">default collation</a> used when evaluating
|
|
XPath expressions, as described in <a href=
|
|
"#static-context"><i>5.4.1 Initializing the Static Context</i></a>
|
|
and <a href="#default-collation-attribute"><i>3.6.1 The
|
|
default-collation attribute</i></a>.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>It is usually appropriate, when sorting, to use a strong
|
|
collation, that is, one that takes account of secondary differences
|
|
(accents) and tertiary differences (case) between strings that are
|
|
otherwise equal. A weak collation, which ignores such differences,
|
|
may be more suitable when comparing strings for equality.</p>
|
|
<p>Useful background information on international sorting is
|
|
provided in <a href="#UNICODE-TR10">[UNICODE TR10]</a>. The
|
|
<code>case-order</code> attribute may be interpreted as described
|
|
in section 6.6 of <a href="#UNICODE-TR10">[UNICODE TR10]</a>.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="creating-sorted-sequence" id=
|
|
"creating-sorted-sequence"></a>13.2 <a href=
|
|
"#creating-sorted-sequence" style="text-decoration: none">Creating
|
|
a Sorted Sequence</a></h3>
|
|
<p class="element-syntax"><a name="element-perform-sort" id=
|
|
"element-perform-sort"></a><code><!-- Category: instruction
|
|
--><br />
|
|
<xsl:perform-sort<br />
|
|
  select? = <var>expression</var> ><br />
|
|
  <!-- Content: (<a href=
|
|
"#element-sort">xsl:sort</a>+, <var>sequence-constructor</var>)
|
|
--><br />
|
|
</xsl:perform-sort></code></p>
|
|
<p>The <a href=
|
|
"#element-perform-sort"><code>xsl:perform-sort</code></a>
|
|
instruction is used to return a <a title="sorted sequence" class=
|
|
"termref" href="#dt-sorted-sequence">sorted sequence</a>.</p>
|
|
<p>The <a title="initial sequence" class="termref" href=
|
|
"#dt-initial-sequence">initial sequence</a> is obtained either by
|
|
evaluating the <code>select</code> attribute or by evaluating the
|
|
contained sequence constructor (but not both). If there is no
|
|
<code>select</code> attribute and no sequence constructor then the
|
|
<a title="initial sequence" class="termref" href=
|
|
"#dt-initial-sequence">initial sequence</a> (and therefore, the
|
|
<a title="sorted sequence" class="termref" href=
|
|
"#dt-sorted-sequence">sorted sequence</a>) is an empty
|
|
sequence.</p>
|
|
<p><a name="err-XTSE1040" id="err-XTSE1040"><span class=
|
|
"error">[ERR XTSE1040]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> if an
|
|
<a href="#element-perform-sort"><code>xsl:perform-sort</code></a>
|
|
instruction with a <code>select</code> attribute has any content
|
|
other than <a href="#element-sort"><code>xsl:sort</code></a> and
|
|
<a href="#element-fallback"><code>xsl:fallback</code></a>
|
|
instructions.</p>
|
|
<p>The result of the <a href=
|
|
"#element-perform-sort"><code>xsl:perform-sort</code></a>
|
|
instruction is the result of sorting its <a title=
|
|
"initial sequence" class="termref" href=
|
|
"#dt-initial-sequence">initial sequence</a> using its contained
|
|
<a title="sort key specification" class="termref" href=
|
|
"#dt-sort-key-specification">sort key specification</a>.</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e24837" id=
|
|
"d7e24837"></a>Example: Sorting a Sequence of Atomic Values</div>
|
|
<p>The following stylesheet function sorts a sequence of atomic
|
|
values using the value itself as the sort key.</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:function name="local:sort"
|
|
as="xs:anyAtomicType*">
|
|
<xsl:param name="in" as="xs:anyAtomicType*"/>
|
|
<xsl:perform-sort select="$in">
|
|
<xsl:sort select="."/>
|
|
</xsl:perform-sort>
|
|
</xsl:function>
|
|
</pre></div>
|
|
</div>
|
|
<p> </p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e24844" id=
|
|
"d7e24844"></a>Example: Writing a Function to Perform a Sort</div>
|
|
<p>The following example defines a function that sorts books by
|
|
price, and uses this function to output the five books that have
|
|
the lowest prices:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:function name="bib:books-by-price"
|
|
as="schema-element(bib:book)*">
|
|
<xsl:param name="in" as="schema-element(bib:book)*"/>
|
|
<xsl:perform-sort select="$in">
|
|
<xsl:sort select="xs:decimal(bib:price)"/>
|
|
</xsl:perform-sort>
|
|
</xsl:function>
|
|
...
|
|
<xsl:copy-of select="bib:books-by-price(//bib:book)
|
|
[position() = 1 to 5]"/>
|
|
|
|
|
|
</pre></div>
|
|
</div>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="sorted-iteration" id="sorted-iteration"></a>13.3
|
|
<a href="#sorted-iteration" style=
|
|
"text-decoration: none">Processing a Sequence in Sorted
|
|
Order</a></h3>
|
|
<p>When used within <a href=
|
|
"#element-for-each"><code>xsl:for-each</code></a> or <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>, a
|
|
<a title="sort key specification" class="termref" href=
|
|
"#dt-sort-key-specification">sort key specification</a> indicates
|
|
that the sequence of items selected by that instruction is to be
|
|
processed in sorted order, not in the order of the supplied
|
|
sequence.</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e24865" id=
|
|
"d7e24865"></a>Example: Processing Elements in Sorted Order</div>
|
|
<p>For example, suppose an employee database has the form</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<employees>
|
|
<employee>
|
|
<name>
|
|
<given>James</given>
|
|
<family>Clark</family>
|
|
</name>
|
|
...
|
|
</employee>
|
|
</employees>
|
|
</pre></div>
|
|
<p>Then a list of employees sorted by name could be generated
|
|
using:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<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>
|
|
</pre></div>
|
|
</div>
|
|
<p>When used within <a href=
|
|
"#element-for-each-group"><code>xsl:for-each-group</code></a>, a
|
|
<a title="sort key specification" class="termref" href=
|
|
"#dt-sort-key-specification">sort key specification</a> indicates
|
|
the order in which the groups are to be processed. For the effect
|
|
of <a href=
|
|
"#element-for-each-group"><code>xsl:for-each-group</code></a>, see
|
|
<a href="#grouping"><i>14 Grouping</i></a>.</p>
|
|
</div>
|
|
</div>
|
|
<div class="div1">
|
|
<h2><a name="grouping" id="grouping"></a>14 <a href="#grouping"
|
|
style="text-decoration: none">Grouping</a></h2>
|
|
<p>The facilities described in this section are designed to allow
|
|
items in a sequence to be grouped based on common values; for
|
|
example it allows grouping of elements having the same value for a
|
|
particular attribute, or elements with the same name, or elements
|
|
with common values for any other <a title="expression" class=
|
|
"termref" href="#dt-expression">expression</a>. 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.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>Simple elimination of duplicates can also be achieved using the
|
|
function <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-distinct-values"><code>
|
|
distinct-values</code></a><sup><small>FO</small></sup> in the
|
|
<a title="core function" class="termref" href=
|
|
"#dt-core-function">core function</a> library: see <a href=
|
|
"#xpath-functions-11">[Functions and Operators]</a>.</p>
|
|
</div>
|
|
<p>In addition these facilities allow grouping based on sequential
|
|
position, for example selecting groups of adjacent
|
|
<code>para</code> 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.</p>
|
|
<p>For each group of items identified, it is possible to evaluate a
|
|
<a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> 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.</p>
|
|
<p>It is also possible for one item to participate in more than one
|
|
group.</p>
|
|
<div class="div2">
|
|
<h3><a name="current-group" id="current-group"></a>14.1 <a href=
|
|
"#current-group" style="text-decoration: none">The Current
|
|
Group</a></h3>
|
|
<a name="function-current-group" id="function-current-group"></a>
|
|
<div class="proto"><code class=
|
|
"function">current-group</code>()<code class=
|
|
"as"> as </code><code class=
|
|
"return-type">item()*</code></div>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-current-group" id="dt-current-group" title=
|
|
"current group"></a>The evaluation context for XPath <a title=
|
|
"expression" class="termref" href="#dt-expression">expressions</a>
|
|
includes a component called the <b>current group</b>, which is a
|
|
sequence. <span class="definition">]</span></p>
|
|
<p>The current group is bound during evaluation of the <a href=
|
|
"#element-for-each-group"><code>xsl:for-each-group</code></a>
|
|
instruction and during evaluation of the <a href=
|
|
"#element-merge"><code>xsl:merge</code></a> instruction. If neither
|
|
instruction is being evaluated, it will be an empty sequence.</p>
|
|
<p>The scope of the current group is dynamic: its value is retained
|
|
through calls on named templates, template rules, functions, and
|
|
attribute sets.</p>
|
|
<p>The function <a href=
|
|
"#function-current-group"><code>current-group</code></a> returns
|
|
the sequence of items making up the current group.</p>
|
|
<blockquote>
|
|
<p><b><a name="issue-current-group-source-argument" id=
|
|
"issue-current-group-source-argument">Issue 16
|
|
(current-group-source-argument)</a>:</b></p>
|
|
<p>The WG has considered a variant of <a href=
|
|
"#function-current-group"><code>current-group</code></a> for use
|
|
within <a href=
|
|
"#element-merge-action"><code>xsl:merge-action</code></a> which
|
|
would get the subset of the current group applicable to one named
|
|
merge source. This is superseded in this draft by the <a href=
|
|
"#function-current-merge-inputs"><code>current-merge-inputs</code></a>
|
|
function, which provides this capability and more. However, the
|
|
function call <code>current-group(sourcename)</code> could still be
|
|
useful because it is simpler. Also, allowing a parameter to
|
|
<code>current-group</code> opens the way to do similar things in
|
|
the context of <a href=
|
|
"#element-for-each-group"><code>xsl:for-each-group</code></a>, such
|
|
as using the source names "matching" and "non-matching" to
|
|
distinguish nodes that matched (or failed to match) the
|
|
<code>group-starting-with</code> and <code>group-ending-with</code>
|
|
patterns.</p>
|
|
</blockquote>
|
|
<p><a name="err-XTSE1060" id="err-XTSE1060"><span class=
|
|
"error">[ERR XTSE1060]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> if the
|
|
<a href="#function-current-group"><code>current-group</code></a>
|
|
function is used within a <a title="pattern" class="termref" href=
|
|
"#dt-pattern">pattern</a>.</p>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="current-grouping-key" id=
|
|
"current-grouping-key"></a>14.2 <a href="#current-grouping-key"
|
|
style="text-decoration: none">The Current Grouping Key</a></h3>
|
|
<a name="function-current-grouping-key" id=
|
|
"function-current-grouping-key"></a>
|
|
<div class="proto"><code class=
|
|
"function">current-grouping-key</code>()<code class=
|
|
"as"> as </code><code class=
|
|
"return-type">xs:anyAtomicType?</code></div>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-current-grouping-key" id="dt-current-grouping-key" title=
|
|
"current grouping key"></a>The evaluation context for XPath
|
|
<a title="expression" class="termref" href=
|
|
"#dt-expression">expressions</a> includes a component called the
|
|
<b>current grouping key</b>, which is <span>a sequence of atomic
|
|
values</span>. The current grouping key is the <a title=
|
|
"grouping key" class="termref" href="#dt-grouping-key">grouping
|
|
key</a> shared in common by all the items within the <a title=
|
|
"current group" class="termref" href="#dt-current-group">current
|
|
group</a>.<span class="definition">]</span></p>
|
|
<p>The current grouping key is bound during evaluation of the
|
|
<a href=
|
|
"#element-for-each-group"><code>xsl:for-each-group</code></a>
|
|
instruction and during evaluation of the <a href=
|
|
"#element-merge"><code>xsl:merge</code></a> instruction. If neither
|
|
instruction is being evaluated, it will be an empty sequence.</p>
|
|
<p>While an <a href=
|
|
"#element-for-each-group"><code>xsl:for-each-group</code></a>
|
|
instruction with a <code>group-by</code> or
|
|
<code>group-adjacent</code> attribute is being evaluated, the
|
|
<a title="current grouping key" class="termref" href=
|
|
"#dt-current-grouping-key">current grouping key</a> will be a
|
|
single atomic value.</p>
|
|
<p>While the <a href=
|
|
"#element-merge-action"><code>xsl:merge-action</code></a> part of
|
|
an <a href="#element-merge"><code>xsl:merge</code></a> instruction
|
|
is being evaluated, the current grouping key will be a sequence of
|
|
atomic values, one for each component of the grouping key, as
|
|
defined by the <a href=
|
|
"#element-merge-key"><code>xsl:merge-key</code></a> elements.</p>
|
|
<p>At other times, the current grouping key will be the empty
|
|
sequence.</p>
|
|
<p>The function <a href=
|
|
"#function-current-grouping-key"><code>current-grouping-key</code></a>
|
|
returns the <a title="current grouping key" class="termref" href=
|
|
"#dt-current-grouping-key">current grouping key</a>.</p>
|
|
<p><span>The <a title="grouping key" class="termref" href=
|
|
"#dt-grouping-key">grouping keys</a> of all items in a group are
|
|
not necessarily identical. For example, one might be an
|
|
<code>xs:float</code> while another is a numerically equal
|
|
<code>xs:decimal</code></span>. The <a href=
|
|
"#function-current-grouping-key"><code>current-grouping-key</code></a>
|
|
function <span>returns</span> the grouping key of the <a title=
|
|
"initial item" class="termref" href="#dt-initial-item">initial
|
|
item</a> in the group, after atomization and casting of
|
|
<code>xs:untypedAtomic</code> values to <code>xs:string</code>.</p>
|
|
<p>The function takes no arguments.</p>
|
|
<p><a name="err-XTSE1070" id="err-XTSE1070"><span class=
|
|
"error">[ERR XTSE1070]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> if the
|
|
<a href=
|
|
"#function-current-grouping-key"><code>current-grouping-key</code></a>
|
|
function is used within a <a title="pattern" class="termref" href=
|
|
"#dt-pattern">pattern</a>.</p>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="xsl-for-each-group" id="xsl-for-each-group"></a>14.3
|
|
<a href="#xsl-for-each-group" style="text-decoration: none">The</a>
|
|
<code>xsl:for-each-group</code> <a href="#xsl-for-each-group"
|
|
style="text-decoration: none">Element</a></h3>
|
|
<p class="element-syntax"><a name="element-for-each-group" id=
|
|
"element-for-each-group"></a><code><!-- Category: instruction
|
|
--><br />
|
|
<xsl:for-each-group<br />
|
|
  <b>select</b> = <var>expression</var><br />
|
|
  group-by? = <var>expression</var><br />
|
|
  group-adjacent? = <var>expression</var><br />
|
|
  group-starting-with? = <var>pattern</var><br />
|
|
  group-ending-with? = <var>pattern</var><br />
|
|
  collation? = { <var>uri</var> } ><br />
|
|
  <!-- Content: (<a href=
|
|
"#element-sort">xsl:sort</a>*, <var>sequence-constructor</var>)
|
|
--><br />
|
|
</xsl:for-each-group></code></p>
|
|
<p>This element is an <a title="instruction" class="termref" href=
|
|
"#dt-instruction">instruction</a> that may be used anywhere within
|
|
a <a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a>.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-group" id="dt-group" title="group"></a>The <a href=
|
|
"#element-for-each-group"><code>xsl:for-each-group</code></a>
|
|
instruction allocates the items in an input sequence into
|
|
<b>groups</b> of items (that is, it establishes a collection of
|
|
sequences) based either on common values of a grouping key, or on a
|
|
<a title="pattern" class="termref" href="#dt-pattern">pattern</a>
|
|
that the initial or final <span>item</span> in a group must
|
|
match.<span class="definition">]</span> The <a title=
|
|
"sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> that forms the
|
|
content of the <a href=
|
|
"#element-for-each-group"><code>xsl:for-each-group</code></a>
|
|
instruction is evaluated once for each of these groups.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-population" id="dt-population" title="population"></a>The
|
|
sequence of items to be grouped, which is referred to as the
|
|
<b>population</b>, is determined by evaluating the XPath <a title=
|
|
"expression" class="termref" href="#dt-expression">expression</a>
|
|
contained in the <code>select</code> attribute.<span class=
|
|
"definition">]</span></p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-population-order" id="dt-population-order" title=
|
|
"population order"></a>The population is treated as a sequence; the
|
|
order of items in this sequence is referred to as <b>population
|
|
order</b> <span class="definition">]</span>.</p>
|
|
<p>A group is never empty. If the population is empty, the number
|
|
of groups will be zero.</p>
|
|
<p>The assignment of items to groups depends on the
|
|
<code>group-by</code>, <code>group-adjacent</code>,
|
|
<code>group-starting-with</code>, and
|
|
<code>group-ending-with</code> attributes.</p>
|
|
<p><a name="err-XTSE1080" id="err-XTSE1080"><span class=
|
|
"error">[ERR XTSE1080]</span></a> These four attributes are
|
|
mutually exclusive: it is a <a title="static error" class="termref"
|
|
href="#dt-static-error">static error</a> if none of these four
|
|
attributes is present or if more than one of them is present.</p>
|
|
<p><a name="err-XTSE1090" id="err-XTSE1090"><span class=
|
|
"error">[ERR XTSE1090]</span></a> It is an error to specify the
|
|
<code>collation</code> attribute if neither the
|
|
<code>group-by</code> attribute nor <code>group-adjacent</code>
|
|
attribute is specified.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-grouping-key" id="dt-grouping-key" title="grouping key"></a>If
|
|
either of the <code>group-by</code> or <code>group-adjacent</code>
|
|
attributes is present, then for each item in the <a title=
|
|
"population" class="termref" href="#dt-population">population</a> a
|
|
set of <b>grouping keys</b> is calculated, as follows: the
|
|
expression contained in the <code>group-by</code> or
|
|
<code>group-adjacent</code> attribute is evaluated; the result is
|
|
atomized; and any <code>xs:untypedAtomic</code> values are cast to
|
|
<code>xs:string</code>. The grouping keys are the distinct atomic
|
|
values present in the result sequence. <span class=
|
|
"definition">]</span></p>
|
|
<p>When calculating grouping keys for an item in the population,
|
|
the <a title="expression" class="termref" href=
|
|
"#dt-expression">expression</a> contained in the
|
|
<code>group-by</code> or <code>group-adjacent</code> attribute is
|
|
evaluated with that item as the <a title="context item" class=
|
|
"termref" href="#dt-context-item">context item</a>, with its
|
|
position in <a title="population order" class="termref" href=
|
|
"#dt-population-order">population order</a> as the <a title=
|
|
"context position" class="termref" href=
|
|
"#dt-context-position">context position</a>, and with the size of
|
|
the population as the <a title="context size" class="termref" href=
|
|
"#dt-context-size">context size</a>.</p>
|
|
<p>If the <code>group-by</code> attribute is present, then an item
|
|
in the population <span class="verb">may</span> have multiple
|
|
grouping keys: that is, the <code>group-by</code> expression
|
|
evaluates to a sequence. The item is included in as many groups as
|
|
there are distinct grouping keys (which may be zero). If the
|
|
<code>group-adjacent</code> attribute is used, then each item in
|
|
the population <span class="verb">must</span> have exactly one
|
|
grouping key value.</p>
|
|
<p><a name="err-XTTE1100" id="err-XTTE1100"><span class=
|
|
"error">[ERR XTTE1100]</span></a> It is a <a title="type errors"
|
|
class="termref" href="#dt-type-error">type error</a> if the result
|
|
of evaluating the <code>group-adjacent</code> expression is an
|
|
empty sequence or a sequence containing more than one item.</p>
|
|
<p><a title="grouping key" class="termref" href=
|
|
"#dt-grouping-key">Grouping keys</a> are compared using the rules
|
|
for the <code>eq</code> operator appropriate to their dynamic type.
|
|
Values of type <code>xs:untypedAtomic</code> are cast to
|
|
<code>xs:string</code> before the comparison. Two items that are
|
|
not comparable using the <code>eq</code> operator are considered to
|
|
be not equal, that is, they are allocated to different groups. If
|
|
the values are strings, or untyped atomic values, then if there is
|
|
a <code>collation</code> attribute the values are compared using
|
|
the collation specified as the <a title="effective value" class=
|
|
"termref" href="#dt-effective-value">effective value</a> of the
|
|
<code>collation</code> attribute, resolved if relative against the
|
|
base URI of the <a href=
|
|
"#element-for-each-group"><code>xsl:for-each-group</code></a>
|
|
element. If there is no <code>collation</code> attribute then the
|
|
<a title="default collation" class="termref" href=
|
|
"#dt-default-collation">default collation</a> is used.</p>
|
|
<p>For the purposes of grouping, the value <code>NaN</code> is
|
|
considered equal to itself.</p>
|
|
<p><a name="err-XTDE1110" id="err-XTDE1110"><span class=
|
|
"error">[ERR XTDE1110]</span></a> It is a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> if the
|
|
collation URI specified to <a href=
|
|
"#element-for-each-group"><code>xsl:for-each-group</code></a>
|
|
(after resolving against the base URI) is a collation that is not
|
|
recognized by the implementation. (For notes, <span class=
|
|
"error">[see <a href="#err-XTDE1035">ERR XTDE1035</a>]</span>.)</p>
|
|
<p>For more information on collations, see <a href=
|
|
"#collating-sequences"><i>13.1.3 Sorting Using
|
|
Collations</i></a>.</p>
|
|
<p>The way in which an <a href=
|
|
"#element-for-each-group"><code>xsl:for-each-group</code></a>
|
|
element is evaluated depends on which of the four group-defining
|
|
attributes is present:</p>
|
|
<ul>
|
|
<li>
|
|
<p>If the <code>group-by</code> attribute is present, the items in
|
|
the <a title="population" class="termref" href=
|
|
"#dt-population">population</a> are examined, in population order.
|
|
For each item <var>J</var>, the expression in the
|
|
<code>group-by</code> attribute is evaluated to produce a sequence
|
|
of zero or more <a title="grouping key" class="termref" href=
|
|
"#dt-grouping-key">grouping key</a> values. For each one of these
|
|
<a title="grouping key" class="termref" href=
|
|
"#dt-grouping-key">grouping keys</a>, if there is already a group
|
|
created to hold items having that grouping key value, <var>J</var>
|
|
is <span>appended</span> to that group; otherwise a new group is
|
|
created for items with that grouping key value, and <var>J</var>
|
|
becomes its first member.</p>
|
|
<p>An item in the population may thus be <span>appended</span> to
|
|
zero, one, or many groups. An item will never be
|
|
<span>appended</span> more than once to the same group; if two or
|
|
more grouping keys for the same item are equal, then the duplicates
|
|
are ignored. An <em>item</em> here means the item at a particular
|
|
position within the population—if the population contains the same
|
|
node at several different positions in the sequence then a group
|
|
may indeed contain duplicate nodes.</p>
|
|
<p>The number of groups will be the same as the number of distinct
|
|
grouping key values present in the <a title="population" class=
|
|
"termref" href="#dt-population">population</a>.</p>
|
|
<p>If the population contains values of different numeric types
|
|
that differ from each other by small amounts, then the
|
|
<code>eq</code> operator is not transitive, because of rounding
|
|
effects occurring during type promotion. The effect of this is
|
|
described in <a href="#non-transitivity"><i>14.5
|
|
Non-Transitivity</i></a>.</p>
|
|
</li>
|
|
<li>
|
|
<p>If the <code>group-adjacent</code> attribute is present, the
|
|
items in the <a title="population" class="termref" href=
|
|
"#dt-population">population</a> are examined, in population order.
|
|
If an item has the same value for the <a title="grouping key"
|
|
class="termref" href="#dt-grouping-key">grouping key</a> as its
|
|
preceding item within the <a title="population" class="termref"
|
|
href="#dt-population">population</a> (in <a title=
|
|
"population order" class="termref" href=
|
|
"#dt-population-order">population order</a>), then it is
|
|
<span>appended</span> to the same group as its preceding item;
|
|
otherwise a new group is created and the item becomes its first
|
|
member.</p>
|
|
</li>
|
|
<li>
|
|
<p>If the <code>group-starting-with</code> attribute is present,
|
|
then its value <span class="verb">must</span> be a <a href=
|
|
"#NT-Pattern">pattern</a>.</p>
|
|
<p>The <span>items</span> in the <a title="population" class=
|
|
"termref" href="#dt-population">population</a> are examined in
|
|
<a title="population order" class="termref" href=
|
|
"#dt-population-order">population order</a>. If an
|
|
<span>item</span> matches the pattern, or is the first
|
|
<span>item</span> in the population, then a new group is created
|
|
and the <span>item</span> becomes its first member. Otherwise, the
|
|
<span>item</span> is <span>appended</span> to the same group as its
|
|
preceding <span>item</span> within the population.</p>
|
|
</li>
|
|
<li>
|
|
<p>If the <code>group-ending-with</code> attribute is present, then
|
|
its value <span class="verb">must</span> be a <a href=
|
|
"#NT-Pattern">pattern</a>.</p>
|
|
<p>The <span>items</span> in the <a title="population" class=
|
|
"termref" href="#dt-population">population</a> are examined in
|
|
<a title="population order" class="termref" href=
|
|
"#dt-population-order">population order</a>. If an
|
|
<span>item</span> is the first <span>item</span> in the population,
|
|
or if the previous <span>item</span> in the population matches the
|
|
pattern, then a new group is created and the <span>item</span>
|
|
becomes its first member. Otherwise, the <span>item</span> is
|
|
<span>appended</span> to the same group as its preceding
|
|
<span>item</span> within the population.</p>
|
|
</li>
|
|
</ul>
|
|
<p>In all cases the order of items within each group is
|
|
predictable, and reflects the original <a title="population order"
|
|
class="termref" href="#dt-population-order">population order</a>,
|
|
in that the items are processed in population order and each item
|
|
is appended at the end of zero or more groups.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>As always, a different algorithm may be used if it achieves the
|
|
same effect.</p>
|
|
</div>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-initial-item" id="dt-initial-item" title="initial item"></a>For
|
|
each <a title="group" class="termref" href="#dt-group">group</a>,
|
|
the item within the group that is first in <a title=
|
|
"population order" class="termref" href=
|
|
"#dt-population-order">population order</a> is known as the
|
|
<b>initial item</b> of the group.<span class=
|
|
"definition">]</span></p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-first-appearance" id="dt-first-appearance" title=
|
|
"order of first appearance"></a>There is a <span>total</span>
|
|
ordering among <a title="group" class="termref" href=
|
|
"#dt-group">groups</a> referred to as the <b>order of first
|
|
appearance</b>. A group <var>G</var> is defined to precede a group
|
|
<var>H</var> in order of first appearance if the <a title=
|
|
"initial item" class="termref" href="#dt-initial-item">initial
|
|
item</a> of <var>G</var> precedes the initial item of <var>H</var>
|
|
in population order. If two groups <var>G</var> and <var>H</var>
|
|
have the same initial item (because the item is in both groups)
|
|
then <var>G</var> precedes <var>H</var> if the <a title=
|
|
"grouping key" class="termref" href="#dt-grouping-key">grouping
|
|
key</a> of <var>G</var> precedes the grouping key of <var>H</var>
|
|
in the sequence that results from evaluating the
|
|
<code>group-by</code> expression of this initial item.<span class=
|
|
"definition">]</span></p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-processing-order" id="dt-processing-order" title=
|
|
"processing order"></a>There is another <span>total</span> ordering
|
|
among groups referred to as <b>processing order</b>. If group
|
|
<var>R</var> precedes group <var>S</var> in processing order, then
|
|
in the result sequence returned by the <a href=
|
|
"#element-for-each-group"><code>xsl:for-each-group</code></a>
|
|
instruction the items generated by processing group <var>R</var>
|
|
will precede the items generated by processing group
|
|
<var>S</var>.<span class="definition">]</span></p>
|
|
<p>If there are no <a href=
|
|
"#element-sort"><code>xsl:sort</code></a> elements immediately
|
|
within the <a href=
|
|
"#element-for-each-group"><code>xsl:for-each-group</code></a>
|
|
element, the <a title="processing order" class="termref" href=
|
|
"#dt-processing-order">processing order</a> of the <a title="group"
|
|
class="termref" href="#dt-group">groups</a> is the <a title=
|
|
"order of first appearance" class="termref" href=
|
|
"#dt-first-appearance">order of first appearance</a>.</p>
|
|
<p>Otherwise, the <a href="#element-sort"><code>xsl:sort</code></a>
|
|
elements immediately within the <a href=
|
|
"#element-for-each-group"><code>xsl:for-each-group</code></a>
|
|
element define the processing order of the <a title="group" class=
|
|
"termref" href="#dt-group">groups</a> (see <a href="#sorting"><i>13
|
|
Sorting</i></a>). They do not affect the order of items within each
|
|
group. Multiple <a title="sort key component" class="termref" href=
|
|
"#dt-sort-key-component">sort key components</a> are allowed, and
|
|
are evaluated in major-to-minor order. If two groups have the same
|
|
values for all their sort key components, they are processed in
|
|
<a title="order of first appearance" class="termref" href=
|
|
"#dt-first-appearance">order of first appearance</a> if the
|
|
<a title="sort key specification" class="termref" href=
|
|
"#dt-sort-key-specification">sort key specification</a> is
|
|
<a title="stable" class="termref" href="#dt-stable">stable</a>,
|
|
otherwise in an <a title="implementation-dependent" class="termref"
|
|
href="#dt-implementation-dependent">implementation-dependent</a>
|
|
order.</p>
|
|
<p>The <code>select</code> <a title="expression" class="termref"
|
|
href="#dt-expression">expression</a> of an <a href=
|
|
"#element-sort"><code>xsl:sort</code></a> element is evaluated once
|
|
for each <a title="group" class="termref" href=
|
|
"#dt-group">group</a>. During this evaluation, the <a title=
|
|
"context item" class="termref" href="#dt-context-item">context
|
|
item</a> is the <a title="initial item" class="termref" href=
|
|
"#dt-initial-item">initial item</a> of the group, the <a title=
|
|
"context position" class="termref" href=
|
|
"#dt-context-position">context position</a> is the position of this
|
|
item within the set of initial items (that is, one item for each
|
|
group in the <a title="population" class="termref" href=
|
|
"#dt-population">population</a>) in <a title="population order"
|
|
class="termref" href="#dt-population-order">population order</a>,
|
|
the <a title="context size" class="termref" href=
|
|
"#dt-context-size">context size</a> is the number of groups, the
|
|
<a title="current group" class="termref" href=
|
|
"#dt-current-group">current group</a> is the group whose <a title=
|
|
"sort key value" class="termref" href="#dt-sort-key-value">sort key
|
|
value</a> is being determined, and the <a title=
|
|
"current grouping key" class="termref" href=
|
|
"#dt-current-grouping-key">current grouping key</a> is the grouping
|
|
key for that group. If the <a href=
|
|
"#element-for-each-group"><code>xsl:for-each-group</code></a>
|
|
instruction uses the <code>group-starting-with</code> or
|
|
<code>group-ending-with</code> attributes, then the current
|
|
grouping key is the empty sequence.</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e25808" id=
|
|
"d7e25808"></a>Example: Sorting Groups</div>
|
|
<p>For example, this means that if the <a title="grouping key"
|
|
class="termref" href="#dt-grouping-key">grouping key</a> is
|
|
<code>@category</code>, you can sort the groups in order of their
|
|
grouping key by writing <code><xsl:sort
|
|
select="current-grouping-key()"/></code>; or you can sort the
|
|
groups in order of size by writing <code><xsl:sort
|
|
select="count(current-group())"/></code></p>
|
|
</div>
|
|
<p>The <a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> contained in
|
|
the <a href=
|
|
"#element-for-each-group"><code>xsl:for-each-group</code></a>
|
|
element is evaluated once for each of the <a title="group" class=
|
|
"termref" href="#dt-group">groups</a>, in <a title=
|
|
"processing order" class="termref" href=
|
|
"#dt-processing-order">processing order</a>. The sequences that
|
|
result are concatenated, in <a title="processing order" class=
|
|
"termref" href="#dt-processing-order">processing order</a>, to form
|
|
the result of the <a href=
|
|
"#element-for-each-group"><code>xsl:for-each-group</code></a>
|
|
element. Within the <a title="sequence constructor" class="termref"
|
|
href="#dt-sequence-constructor">sequence constructor</a>, the
|
|
<a title="context item" class="termref" href=
|
|
"#dt-context-item">context item</a> is the <a title="initial item"
|
|
class="termref" href="#dt-initial-item">initial item</a> of the
|
|
relevant group, the <a title="context position" class="termref"
|
|
href="#dt-context-position">context position</a> is the position of
|
|
this <span>group in the <a title="processing order" class="termref"
|
|
href="#dt-processing-order">processing order</a> of the
|
|
groups</span>, the <a title="context size" class="termref" href=
|
|
"#dt-context-size">context size</a> is the number of groups, the
|
|
<a title="current group" class="termref" href=
|
|
"#dt-current-group">current group</a> is the <a title="group"
|
|
class="termref" href="#dt-group">group</a> being processed, and the
|
|
<a title="current grouping key" class="termref" href=
|
|
"#dt-current-grouping-key">current grouping key</a> is the grouping
|
|
key for that group. If the <a href=
|
|
"#element-for-each-group"><code>xsl:for-each-group</code></a>
|
|
instruction uses the <code>group-starting-with</code> or
|
|
<code>group-ending-with</code> attributes, then the current
|
|
grouping key is the empty sequence. This has the effect that within
|
|
the <a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a>, a call on
|
|
<code>position()</code> takes successive values <code>1, 2, ...
|
|
last()</code>.</p>
|
|
<p>During the evaluation of a <a title="stylesheet function" class=
|
|
"termref" href="#dt-stylesheet-function">stylesheet function</a>,
|
|
the <a title="current group" class="termref" href=
|
|
"#dt-current-group">current group</a> and <a title=
|
|
"current grouping key" class="termref" href=
|
|
"#dt-current-grouping-key">current grouping key</a> are set to the
|
|
empty sequence, and revert to their previous values on completion
|
|
of evaluation of the stylesheet function.</p>
|
|
<p>On completion of the evaluation of the <a href=
|
|
"#element-for-each-group"><code>xsl:for-each-group</code></a>
|
|
instruction, the <a title="current group" class="termref" href=
|
|
"#dt-current-group">current group</a> and <a title=
|
|
"current grouping key" class="termref" href=
|
|
"#dt-current-grouping-key">current grouping key</a> revert to their
|
|
previous value.</p>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="grouping-examples" id="grouping-examples"></a>14.4
|
|
<a href="#grouping-examples" style="text-decoration: none">Examples
|
|
of Grouping</a></h3>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e25922" id=
|
|
"d7e25922"></a>Example: Grouping Nodes based on Common Values</div>
|
|
<p>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.</p>
|
|
<p>Source XML document:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<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>
|
|
</pre></div>
|
|
<p>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 <code>pop</code> attribute for the cities in
|
|
that country.</p>
|
|
<p>Desired output:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<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>
|
|
</pre></div>
|
|
<p>Solution:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<table xsl:version="2.1" 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>
|
|
</pre></div>
|
|
</div>
|
|
<p> </p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e25945" id=
|
|
"d7e25945"></a>Example: A Composite Grouping Key</div>
|
|
<p>Sometimes it is necessary to use a composite grouping key: for
|
|
example, suppose the source document is similar to the one used in
|
|
the previous examples, but allows multiple entries for the same
|
|
country and city, such as:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<cities>
|
|
<city name="Milano" country="Italia" year="1950" pop="5.23"/>
|
|
<city name="Milano" country="Italia" year="1960" pop="5.29"/>
|
|
<city name="Padova" country="Italia" year="1950" pop="0.69"/>
|
|
<city name="Padova" country="Italia" year="1960" pop="0.93"/>
|
|
<city name="Paris" country="France" year="1951" pop="7.2"/>
|
|
<city name="Paris" country="France" year="1961" pop="7.6"/>
|
|
</cities>
|
|
</pre></div>
|
|
<p>Now suppose we want to list the average value of
|
|
<code>@pop</code> for each (country, name) combination. One way to
|
|
handle this is to concatenate the parts of the key, for example
|
|
<code><xsl:for-each-group select="concat(@country, '/',
|
|
@name)"></code>. A more flexible solution is to nest one
|
|
<a href="#element-for-each-group"><code>xsl:for-each-group</code></a>
|
|
element directly inside another:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:for-each-group select="cities/city" group-by="@country">
|
|
<xsl:for-each-group select="current-group()" group-by="@name">
|
|
<p><xsl:value-of select="@name"/>, <xsl:value-of select="@country"/>:
|
|
<xsl:value-of select="avg(current-group()/@pop)"/></p>
|
|
</xsl:for-each-group>
|
|
</xsl:for-each-group>
|
|
</pre></div>
|
|
<p>The two approaches are not precisely equivalent. If the code
|
|
were changed to output the value of <code>position()</code>
|
|
alongside <code>@name</code> then the first approach (a single
|
|
<a href=
|
|
"#element-for-each-group"><code>xsl:for-each-group</code></a>
|
|
element with a compound key) would number the groups (1, 2, 3),
|
|
while the second approach (two nested <a href=
|
|
"#element-for-each-group"><code>xsl:for-each-group</code></a>
|
|
elements) would number them (1, 2, 1).</p>
|
|
</div>
|
|
<p> </p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e25979" id=
|
|
"d7e25979"></a>Example: Identifying a Group by its Initial
|
|
Element</div>
|
|
<p>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 <code>h2</code> element, followed by all the
|
|
<code>p</code> elements up to the next <code>h2</code> element.</p>
|
|
<p>Source XML document:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<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>
|
|
</pre></div>
|
|
<p>Desired output:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<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 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>
|
|
</pre></div>
|
|
<p>Solution:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<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>
|
|
</pre></div>
|
|
<p>The use of <code>title="{self::h2}"</code> rather than
|
|
<code>title="{.}"</code> is to handle the case where the first
|
|
element is not an <code>h2</code> element.</p>
|
|
</div>
|
|
<p> </p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e26016" id=
|
|
"d7e26016"></a>Example: Identifying a Group by its Final
|
|
Element</div>
|
|
<p>The next example illustrates how a group of related elements can
|
|
be identified by the last element in the group, rather than the
|
|
first. Here the absence of the attribute
|
|
<code>continued="yes"</code> indicates the end of the group.</p>
|
|
<p>Source XML document:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<doc>
|
|
<page continued="yes">Some text</page>
|
|
<page continued="yes">More text</page>
|
|
<page>Yet more text</page>
|
|
<page continued="yes">Some words</page>
|
|
<page continued="yes">More words</page>
|
|
<page>Yet more words</page>
|
|
</doc>
|
|
</pre></div>
|
|
<p>Desired output:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<doc>
|
|
<pageset>
|
|
<page>Some text</page>
|
|
<page>More text</page>
|
|
<page>Yet more text</page>
|
|
</pageset>
|
|
<pageset>
|
|
<page>Some words</page>
|
|
<page>More words</page>
|
|
<page>Yet more words</page>
|
|
</pageset>
|
|
</doc>
|
|
</pre></div>
|
|
<p>Solution:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:template match="doc">
|
|
<doc>
|
|
<xsl:for-each-group select="*"
|
|
group-ending-with="page[not(@continued='yes')]">
|
|
<pageset>
|
|
<xsl:for-each select="current-group()">
|
|
<page><xsl:value-of select="."/></page>
|
|
</xsl:for-each>
|
|
</pageset>
|
|
</xsl:for-each-group>
|
|
</doc>
|
|
</xsl:template>
|
|
</pre></div>
|
|
</div>
|
|
<p> </p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e26036" id=
|
|
"d7e26036"></a>Example: Adding an Element to Several Groups</div>
|
|
<p>The next example shows how an item can be added to multiple
|
|
groups. Book titles will be added to one group for each indexing
|
|
term marked up within the title.</p>
|
|
<p>Source XML document:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<titles>
|
|
<title>A Beginner's Guide to <ix>Java</ix></title>
|
|
<title>Learning <ix>XML</ix></title>
|
|
<title>Using <ix>XML</ix> with <ix>Java</ix></title>
|
|
</titles>
|
|
</pre></div>
|
|
<p>Desired output:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<h2>Java</h2>
|
|
<p>A Beginner's Guide to Java</p>
|
|
<p>Using XML with Java</p>
|
|
<h2>XML</h2>
|
|
<p>Learning XML</p>
|
|
<p>Using XML with Java</p>
|
|
</pre></div>
|
|
<p>Solution:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:template match="titles">
|
|
<xsl:for-each-group select="title" group-by="ix">
|
|
<h2><xsl:value-of select="current-grouping-key()"/></h2>
|
|
<xsl:for-each select="current-group()">
|
|
<p><xsl:value-of select="."/></p>
|
|
</xsl:for-each>
|
|
</xsl:for-each-group>
|
|
</xsl:template>
|
|
</pre></div>
|
|
</div>
|
|
<p> </p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e26053" id=
|
|
"d7e26053"></a>Example: Grouping Alternating Sequences of
|
|
Elements</div>
|
|
<p>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.</p>
|
|
<p>Source XML document:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<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>
|
|
</pre></div>
|
|
<p>Desired output:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<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>
|
|
</pre></div>
|
|
<p>Solution:</p>
|
|
<p>This requires creating a <code>p</code> element around the
|
|
maximal sequence of sibling nodes that does not include a
|
|
<code>ul</code> or <code>ol</code> element.</p>
|
|
<p>This can be done by using <code>group-adjacent</code>, with a
|
|
grouping key that is true if the element is a <code>ul</code> or
|
|
<code>ol</code> element, and false otherwise:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:template match="p">
|
|
<xsl:for-each-group select="node()"
|
|
group-adjacent="self::ul or self::ol">
|
|
<xsl:choose>
|
|
<xsl:when test="current-grouping-key()">
|
|
<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>
|
|
</pre></div>
|
|
</div>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="non-transitivity" id="non-transitivity"></a>14.5
|
|
<a href="#non-transitivity" style=
|
|
"text-decoration: none">Non-Transitivity</a></h3>
|
|
<p>If the population contains values of different numeric types
|
|
that differ from each other by small amounts, then the
|
|
<code>eq</code> operator is not transitive, because of rounding
|
|
effects occurring during type promotion. It is thus possible to
|
|
have three values <var>A</var>, <var>B</var>, and <var>C</var>
|
|
among the grouping keys of the population such that <code>A eq
|
|
B</code>, <code>B eq C</code>, but <code>A ne C</code>.</p>
|
|
<p>For example, this arises when computing</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:for-each-group group-by="." select="
|
|
xs:float('1.0'),
|
|
xs:decimal('1.0000000000100000000001',
|
|
xs:double( '1.00000000001')">
|
|
</pre></div>
|
|
<p>because the values of type <code>xs:float</code> and
|
|
<code>xs:double</code> both compare equal to the value of type
|
|
<code>xs:decimal</code> but not equal to each other.</p>
|
|
<p>In this situation the results <span class="verb">must</span> be
|
|
equivalent to the results obtained by the following algorithm:</p>
|
|
<ul>
|
|
<li>
|
|
<p>For each item <var>J</var> in the <a title="population" class=
|
|
"termref" href="#dt-population">population</a> in <a title=
|
|
"population order" class="termref" href=
|
|
"#dt-population-order">population order</a>, for each of the
|
|
<a title="grouping key" class="termref" href=
|
|
"#dt-grouping-key">grouping keys</a> <var>K</var> for that item in
|
|
sequence, the processor identifies those existing groups
|
|
<var>G</var> such that the grouping key of the <a title=
|
|
"initial item" class="termref" href="#dt-initial-item">initial
|
|
item</a> of <var>G</var> is equal to <var>K</var>.</p>
|
|
</li>
|
|
<li>
|
|
<p>If there is exactly one group <var>G</var>, then <var>J</var> is
|
|
added to this group, unless <var>J</var> is already a member of
|
|
this group.</p>
|
|
</li>
|
|
<li>
|
|
<p>If there is no group <var>G</var>, then a new group is created
|
|
with <var>J</var> as its first item.</p>
|
|
</li>
|
|
<li>
|
|
<p>If there is more than one group <var>G</var> (which can only
|
|
happen in exceptional circumstances involving non-transitivity),
|
|
then one of these groups is selected in an implementation-dependent
|
|
way, and <var>J</var> is added to this group, unless <var>J</var>
|
|
is already a member of this group.</p>
|
|
</li>
|
|
</ul>
|
|
<p>The effect of these rules is that (a) every item in a
|
|
non-singleton group has a grouping key that is equal to that of at
|
|
least one other item in that group, (b) for any two distinct
|
|
groups, there is at least one pair of items (one from each group)
|
|
whose grouping keys are not equal to each other.</p>
|
|
</div>
|
|
</div>
|
|
<div class="div1">
|
|
<h2><a name="merging" id="merging"></a>15 <a href="#merging" style=
|
|
"text-decoration: none">Merging</a></h2>
|
|
<p>The <a href="#element-merge"><code>xsl:merge</code></a>
|
|
instruction allows a sorted sequence of items to be constructed by
|
|
merging several input sequences, each of which is already sorted.
|
|
Each input sequence <span class="verb">must</span> have a merge key
|
|
(one or more atomic values that can be computed as a function of
|
|
the items in the sequence); the input sequence <span class=
|
|
"verb">must</span> be pre-sorted on the value of its merge keys;
|
|
and the merge keys for the different input sequences <span class=
|
|
"verb">must</span> be compatible in the sense that <span>key values
|
|
from an item in one sequence are always comparable with key values
|
|
from an item in a different sequence</span>.</p>
|
|
<p>For example, if two log files contain details of events sorted
|
|
by date and time, then the <a href=
|
|
"#element-merge"><code>xsl:merge</code></a> instruction can be used
|
|
to combine these into a single sequence that is also sorted by date
|
|
and time.</p>
|
|
<p>The data written to the output sequence can be computed in an
|
|
arbitrary way from the data in the input sequences.</p>
|
|
<p>The <a href="#element-merge"><code>xsl:merge</code></a>
|
|
instruction checks that the input sequences are correctly sorted
|
|
and signals a dynamic error if they are not. It does not actually
|
|
perform the sorting.</p>
|
|
<p>The <a href="#element-merge"><code>xsl:merge</code></a>
|
|
instruction can be used to merge several sequences of items that
|
|
all have the same structure (more precisely, sequences whose merge
|
|
keys are computed in the same way): for example, log files created
|
|
by the same application running on different machines in a server
|
|
farm. Alternatively, <a href=
|
|
"#element-merge"><code>xsl:merge</code></a> can be used to merge
|
|
sequences that have different structure (sequences whose merge keys
|
|
are computed in different ways), provided that the computed merge
|
|
keys are compatible: an example might be two log files created by
|
|
different applications, using different XML vocabularies, that both
|
|
contain timestamped events but represent the timestamp in different
|
|
ways. The <a href=
|
|
"#element-merge-source"><code>xsl:merge-source</code></a> element
|
|
represents a <span>set of input sequences that follow common
|
|
rules</span>, including the rules for computing the merge key. The
|
|
<a href="#element-merge"><code>xsl:merge</code></a> operation may
|
|
take any number of <a href=
|
|
"#element-merge-source"><code>xsl:merge-source</code></a> elements
|
|
representing different <span>rules for</span> input sequences, and
|
|
each <a href=
|
|
"#element-merge-source"><code>xsl:merge-source</code></a> element
|
|
may describe any number (zero or more) of input sequences. The
|
|
number of input sequences to the merging operation is thus
|
|
<span>fixed only at the time the <a href=
|
|
"#element-merge"><code>xsl:merge</code></a> instruction is
|
|
evaluated, and <span class="verb">may</span> vary from one
|
|
evaluation to another</span>.</p>
|
|
<p>The following examples illustrate some of the possibilities. The
|
|
detailed explanation of the constructs used follows later in this
|
|
section.</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e26279" id=
|
|
"d7e26279"></a>Example: Merging all the files in a collection</div>
|
|
<p>This example takes as input a homogeneous collection of XML log
|
|
files each of which contains a sorted sequence of
|
|
<code>event</code> elements with a <code>timestamp</code> attribute
|
|
validated as an instance of <code>xs:dateTime</code>. It merges the
|
|
events from the input files into a single sorted output file.</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:result-document href="merged-events.xml">
|
|
<events>
|
|
<xsl:merge>
|
|
<xsl:merge-source select="collection('log-files')">
|
|
<xsl:merge-input select="events/event">
|
|
<xsl:merge-key select="@timestamp"/>
|
|
</xsl:merge-input>
|
|
</xsl:merge-source>
|
|
<xsl:merge-action>
|
|
<xsl:copy-of select="current-group()"/>
|
|
</xsl:merge-action>
|
|
</xsl:merge>
|
|
</events>
|
|
</xsl:result-document>
|
|
</pre></div>
|
|
<p>The example assumes that there are <span>several input files
|
|
each of which has</span> a structure similar to the following, in
|
|
which the <code>timestamp</code> attribute has a typed value that
|
|
is an instance of <code>xs:dateTime</code>:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<events>
|
|
<event timestamp="2009-08-20T12:01:01Z">Transaction T1234 started</event>
|
|
<event timestamp="2009-08-20T12:01:08Z">Transaction T1235 started</event>
|
|
<event timestamp="2009-08-20T12:01:12Z">Transaction T1235 ended</event>
|
|
<event timestamp="2009-08-20T12:01:15Z">Transaction T1234 ended</event>
|
|
</events>
|
|
</pre></div>
|
|
<p>The output file will have the same structure, and will contain
|
|
copies of all the <code>event</code> elements from all of the input
|
|
files, in sorted order. <span>Note that multiple events with the
|
|
same timestamp can occur either within a single file or across
|
|
multiple files: the order of appearance of these events in the
|
|
output file corresponds to the order of the log files within the
|
|
collection (which might or might not be predictable, depending on
|
|
the implementation).</span></p>
|
|
</div>
|
|
<p> </p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e26315" id=
|
|
"d7e26315"></a>Example: Merging two heterogeneous files</div>
|
|
<p>This example takes as input two log files with different
|
|
structure, producing a single merged output in which the entries
|
|
have a common structure:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:result-document href="merged-events.xml">
|
|
<events>
|
|
<xsl:merge>
|
|
<xsl:merge-source select="doc('log-file-1.xml')">
|
|
<xsl:merge-input select="events/event">
|
|
<xsl:merge-key select="@timestamp"/>
|
|
</xsl:merge-input>
|
|
</xsl:merge-source>
|
|
<xsl:merge-source select="doc('log-files-2.xml')">
|
|
<xsl:merge-input select="log/day/record">
|
|
<xsl:merge-key select="dateTime(../@date, time)"/>
|
|
</xsl:merge-input>
|
|
</xsl:merge-source>
|
|
<xsl:merge-action>
|
|
<xsl:apply-templates select="current-group()"
|
|
mode="standardize-log-entry">
|
|
</xsl:merge-action>
|
|
</xsl:merge>
|
|
</events>
|
|
</xsl:result-document>
|
|
</pre></div>
|
|
<p>Here the first input file has a structure similar to that shown
|
|
in the previous example, while the second input has a different
|
|
structure, of the form:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<log>
|
|
<day date="2009-08-20">
|
|
<record>
|
|
<time>12:01:09-05:00</time>
|
|
<message>Temperature 15.4C</message>
|
|
</record>
|
|
<record>
|
|
<time>12:03:00-05:00</time>
|
|
<message>Temperature 18.2C</message>
|
|
</record>
|
|
</day>
|
|
</log>
|
|
</pre></div>
|
|
<p>The templates in mode <code>standardize-log-entry</code> convert
|
|
the log entries to a common output format, for example:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:template match="event" mode="standardize-log-entry"
|
|
as="schema-element(event)">
|
|
<xsl:copy-of select-"." validation="preserve"/>
|
|
</xsl:template>
|
|
|
|
<xsl:template match="record" mode="standardize-log-entry"
|
|
as="schema-element(event)">
|
|
<event timestamp="{dateTime(../@date, time)}" xsl:validation="strict">
|
|
<xsl:value-of select="message"/>
|
|
</event>
|
|
</xsl:template>
|
|
</pre></div>
|
|
</div>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>The <a href="#element-merge"><code>xsl:merge</code></a>
|
|
instruction is designed to enable streaming of data, so that there
|
|
is no need to allocate memory to hold the input sequences. However,
|
|
there is no requirement that an implementation should actually use
|
|
streaming to perform the processing.</p>
|
|
</div>
|
|
<blockquote>
|
|
<p><b><a name="issue-streamability-of-merge" id=
|
|
"issue-streamability-of-merge">Issue 17
|
|
(streamability-of-merge)</a>:</b></p>
|
|
<p>The <a href="#element-merge"><code>xsl:merge</code></a>
|
|
instruction is designed to achieve streamability in the case where
|
|
the anchor nodes are the document nodes of distinct documents and
|
|
the merge keys are <a title="motionless" class="termref" href=
|
|
"#dt-motionless">motionless</a> expressions. However, unlike other
|
|
constructs, there is no provision for users to indicate that
|
|
streaming is required, and no analysis of the conditions under
|
|
which it is guaranteed.</p>
|
|
</blockquote>
|
|
<div class="div2">
|
|
<h3><a name="merge-terminology" id="merge-terminology"></a>15.1
|
|
<a href="#merge-terminology" style=
|
|
"text-decoration: none">Terminology for merging</a></h3>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-merge-source-definition" id="dt-merge-source-definition" title=
|
|
"merge source definition"></a>A <b>merge source definition</b> is
|
|
the definition of one kind of input to the merge operation. It
|
|
selects zero or more <a title="merge input sequence" class=
|
|
"termref" href="#dt-merge-input-sequence">merge input
|
|
sequences</a>, and it includes a <a title="merge key specification"
|
|
class="termref" href="#dt-merge-key-specification">merge key
|
|
specification</a> to define how the <span><a title=
|
|
"merge key value" class="termref" href="#dt-merge-key-value">merge
|
|
key values</a></span> are computed for each such merge input
|
|
sequence.<span class="definition">]</span> A merge source
|
|
definition corresponds to an <a href=
|
|
"#element-merge-source"><code>xsl:merge-source</code></a> element
|
|
in the stylesheet.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-merge-input-sequence" id="dt-merge-input-sequence" title=
|
|
"merge input sequence"></a>A <b>merge input sequence</b> is an
|
|
arbitrary <a href=
|
|
"http://www.w3.org/TR/xpath-datamodel-11/#dt-sequence">sequence</a><sup><small>DM11</small></sup>
|
|
of items which is already sorted according to the <a title=
|
|
"merge key specification" class="termref" href=
|
|
"#dt-merge-key-specification">merge key specification</a> for the
|
|
corresponding <a title="merge source definition" class="termref"
|
|
href="#dt-merge-source-definition">merge source
|
|
definition</a>.<span class="definition">]</span></p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-merge-key-specification" id="dt-merge-key-specification" title=
|
|
"merge key specification"></a>A <b>merge key specification</b>
|
|
consists of one or more adjacent <a href=
|
|
"#element-merge-key"><code>xsl:merge-key</code></a> elements which
|
|
together define how the <a title="merge input sequence" class=
|
|
"termref" href="#dt-merge-input-sequence">merge input sequences</a>
|
|
selected by a <a title="merge source definition" class="termref"
|
|
href="#dt-merge-source-definition">merge source definition</a> are
|
|
sorted. Each <a href=
|
|
"#element-merge-key"><code>xsl:merge-key</code></a> element defines
|
|
one <a title="merge key component" class="termref" href=
|
|
"#dt-merge-key-component">merge key component</a>.<span class=
|
|
"definition">]</span> For example, a merge key specification for a
|
|
log file might specify two merge key components, <code>date</code>
|
|
and <code>time</code>.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-merge-key-component" id="dt-merge-key-component" title=
|
|
"merge key component"></a>A <b>merge key component</b> specifies
|
|
one component of a <a title="merge key specification" class=
|
|
"termref" href="#dt-merge-key-specification">merge key
|
|
specification</a>; it corresponds to a single <a href=
|
|
"#element-merge-key"><code>xsl:merge-key</code></a> element in the
|
|
stylesheet.<span class="definition">]</span></p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-merge-key-value" id="dt-merge-key-value" title=
|
|
"merge key value"></a> For each item in a <a title=
|
|
"merge input sequence" class="termref" href=
|
|
"#dt-merge-input-sequence">merge input sequence</a>, a value is
|
|
computed for each <a title="merge key component" class="termref"
|
|
href="#dt-merge-key-component">merge key component</a> within the
|
|
<a title="merge key specification" class="termref" href=
|
|
"#dt-merge-key-specification">merge key specification</a>. The
|
|
value computed for an item by using the <var>N</var>th <a title=
|
|
"merge key component" class="termref" href=
|
|
"#dt-merge-key-component">merge key component</a> is referred to as
|
|
the <var>N</var>th <b>merge key value</b> of that item.<span class=
|
|
"definition">]</span></p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-composite-merge-key-value" id="dt-composite-merge-key-value"
|
|
title="composite merge key value"></a> The ordered collection of
|
|
<a title="merge key value" class="termref" href=
|
|
"#dt-merge-key-value">merge key values</a> computed for one item in
|
|
a <a title="merge input sequence" class="termref" href=
|
|
"#dt-merge-input-sequence">merge input sequence</a> (one for each
|
|
<a title="merge key component" class="termref" href=
|
|
"#dt-merge-key-component">merge key component</a> within the
|
|
<a title="merge key specification" class="termref" href=
|
|
"#dt-merge-key-specification">merge key specification</a>) is
|
|
referred to as a <b>composite merge key value</b>.<span class=
|
|
"definition">]</span></p>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="merge-instruction" id="merge-instruction"></a>15.2
|
|
<a href="#merge-instruction" style="text-decoration: none">The</a>
|
|
<a href="#element-merge"><code>xsl:merge</code></a> <a href=
|
|
"#merge-instruction" style=
|
|
"text-decoration: none">instruction</a></h3>
|
|
<p class="element-syntax"><a name="element-merge" id=
|
|
"element-merge"></a><code><!-- Category: instruction
|
|
--><br />
|
|
<xsl:merge><br />
|
|
  <!-- Content: (<a href=
|
|
"#element-merge-source">xsl:merge-source</a>+, <a href=
|
|
"#element-merge-action">xsl:merge-action</a>, <a href=
|
|
"#element-fallback">xsl:fallback</a>*) --><br />
|
|
</xsl:merge></code></p>
|
|
<p>The effect of the <a href=
|
|
"#element-merge"><code>xsl:merge</code></a> instruction is to
|
|
produce a sorted result sequence from a number of pre-sorted input
|
|
sequences.</p>
|
|
<p>The input sequences to the merge operation are defined by the
|
|
<a href="#element-merge-source"><code>xsl:merge-source</code></a>
|
|
child elements, as described in the next section.</p>
|
|
<p>The sequence constructor contained in the <a href=
|
|
"#element-merge-action"><code>xsl:merge-action</code></a> element
|
|
is evaluated once for each distinct <a title=
|
|
"composite merge key value" class="termref" href=
|
|
"#dt-composite-merge-key-value">composite merge key value</a> to
|
|
form a partial result sequence. The result of the <a href=
|
|
"#element-merge"><code>xsl:merge</code></a> instruction is the
|
|
concatenation of these partial result sequences. For example, the
|
|
action might be to copy the items from all the input sequences to
|
|
the result sequence without change; or it might be to select the
|
|
items from one input sequence in preference to the others. In the
|
|
general case, the items in the partial result sequence are produced
|
|
by an arbitrary computation that has access to the items (from the
|
|
various input sequences) that share the same value for the
|
|
composite merge key.</p>
|
|
<p>The <a href=
|
|
"#element-merge-source"><code>xsl:merge-source</code></a> and
|
|
<a href="#element-merge-action"><code>xsl:merge-action</code></a>
|
|
elements are described in the following sections.</p>
|
|
<p>Any <a href="#element-fallback"><code>xsl:fallback</code></a>
|
|
children of the <a href="#element-merge"><code>xsl:merge</code></a>
|
|
instruction are ignored by an XSLT 2.1 processor, but are used by
|
|
an XSLT 1.0 or XSLT 2.0 processor to <span>perform fallback
|
|
processing</span>.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>An <a href="#element-merge"><code>xsl:merge</code></a>
|
|
instruction that has no input sequences returns an empty sequence.
|
|
An <a href="#element-merge"><code>xsl:merge</code></a> instruction
|
|
with a single input sequence performs processing that is very
|
|
similar in concept to <a href=
|
|
"#element-for-each-group"><code>xsl:for-each-group</code></a> with
|
|
the <code>group-adjacent</code> attribute, except that it requires
|
|
the input to be sorted on the grouping key.</p>
|
|
</div>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="merge-input-sequences" id=
|
|
"merge-input-sequences"></a>15.3 <a href="#merge-input-sequences"
|
|
style="text-decoration: none">Selecting the sequences to be
|
|
merged</a></h3>
|
|
<p class="element-syntax"><a name="element-merge-source" id=
|
|
"element-merge-source"></a><code><xsl:merge-source<br />
|
|
  select? = <var>expression</var><br />
|
|
  name? = <var>QName</var> ><br />
|
|
  <!-- Content: <a href=
|
|
"#element-merge-input">xsl:merge-input</a> --><br />
|
|
</xsl:merge-source></code></p>
|
|
<p class="element-syntax"><a name="element-merge-input" id=
|
|
"element-merge-input"></a><code><xsl:merge-input<br />
|
|
  select? = <var>expression</var> ><br />
|
|
  <!-- Content: (<var>sequence-constructor</var>,
|
|
<a href="#element-merge-key">xsl:merge-key</a>+) --><br />
|
|
</xsl:merge-input></code></p>
|
|
<p>Each <a href=
|
|
"#element-merge-source"><code>xsl:merge-source</code></a> element
|
|
defines a collection of <a title="merge input sequence" class=
|
|
"termref" href="#dt-merge-input-sequence">merge input
|
|
sequences</a>. The selection of items in these input sequences is a
|
|
two-stage process: the <code>select</code> attribute of the
|
|
<a href="#element-merge-source"><code>xsl:merge-source</code></a>
|
|
element is an expression that selects a sequence of <em>anchor
|
|
items</em>, and for each anchor item, the <code>select</code>
|
|
attribute or <a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> of the <a href=
|
|
"#element-merge-input"><code>xsl:merge-input</code></a> element is
|
|
evaluated to select the items that make up one merge input
|
|
sequence.</p>
|
|
<p>The <code>select</code> attribute of the <a href=
|
|
"#element-merge-source"><code>xsl:merge-source</code></a> element
|
|
is evaluated with the dynamic context of the containing <a href=
|
|
"#element-merge"><code>xsl:merge</code></a> instruction. If the
|
|
<code>select</code> attribute is omitted, the default value is
|
|
<code>.</code>, which selects the context item.</p>
|
|
<p>The <code>select</code> attribute of <a href=
|
|
"#element-merge-input"><code>xsl:merge-input</code></a> and the
|
|
contained <a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> are mutually
|
|
exclusive: if the <code>select</code> attribute is present, the
|
|
sequence constructor must be empty, and if the sequence constructor
|
|
is non-empty, the <code>select</code> attribute must be absent.</p>
|
|
<p>The <code>select</code> expression or the contained sequence
|
|
constructor of the <a href=
|
|
"#element-merge-input"><code>xsl:merge-input</code></a> instruction
|
|
is evaluated once for each anchor item selected by the containing
|
|
<a href="#element-merge-source"><code>xsl:merge-source</code></a>
|
|
element. Each evaluation produces a sequence, which acts as one of
|
|
the input sequences for the merge operation. The <a title="focus"
|
|
class="termref" href="#dt-focus">focus</a> for the evaluation is as
|
|
follows:</p>
|
|
<ul>
|
|
<li>
|
|
<p>The <a title="context item" class="termref" href=
|
|
"#dt-context-item">context item</a> is the anchor item</p>
|
|
</li>
|
|
<li>
|
|
<p>The <a title="context position" class="termref" href=
|
|
"#dt-context-position">context position</a> is the position of the
|
|
anchor item within the sequence of anchor items</p>
|
|
</li>
|
|
<li>
|
|
<p>The <a title="context size" class="termref" href=
|
|
"#dt-context-size">context size</a> is the number of anchor
|
|
items.</p>
|
|
</li>
|
|
</ul>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>The <a href="#element-merge-key"><code>xsl:merge-key</code></a>
|
|
element appears at the end of the sequence constructor because the
|
|
computation of the merge key takes the result of the sequence
|
|
constructor as its input.</p>
|
|
</div>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e26656" id=
|
|
"d7e26656"></a>Example: Merging several documents with the same
|
|
structure</div>
|
|
<p>The following <a href=
|
|
"#element-merge-source"><code>xsl:merge-source</code></a> element
|
|
selects two anchor items (the root nodes of two documents), and for
|
|
each of these it selects an input sequence consisting of selected
|
|
<code>event</code> elements within the relevant document.</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:merge-source select="doc('log-A.xml'), doc('log-B.xml')">
|
|
<xsl:merge-input select="events/event">
|
|
<xsl:merge-key select="@timestamp" order="ascending"/>
|
|
</xsl:merge-input>
|
|
</xsl:merge-source>
|
|
</pre></div>
|
|
<p>This example can be extended to merge any number of input
|
|
documents with the same structure:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:merge-source select="collection('log-collection')">
|
|
<xsl:merge-input select="*/event">
|
|
<xsl:merge-key select="@time" order="ascending"/>
|
|
</xsl:merge-input>
|
|
</xsl:merge-source>
|
|
</pre></div>
|
|
<p>In both the above examples the anchor items are document nodes,
|
|
and the items in the input sequence are elements within the
|
|
document that is rooted at this node. This is a common usage
|
|
pattern, but by no means the only way in which the construct can be
|
|
used.</p>
|
|
</div>
|
|
<p>The number of anchor items selected by an <a href=
|
|
"#element-merge-source"><code>xsl:merge-source</code></a> element,
|
|
and therefore the number of input sequences, is variable, but the
|
|
input sequences selected by one <a href=
|
|
"#element-merge-source"><code>xsl:merge-source</code></a> element
|
|
must all use the same expressions to select the items in the input
|
|
sequence and to compute their merge keys. If different expressions
|
|
are needed for different input sequences, then multiple <a href=
|
|
"#element-merge-source"><code>xsl:merge-source</code></a> elements
|
|
can be used.</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e26687" id=
|
|
"d7e26687"></a>Example: Merging two documents with different
|
|
structure</div>
|
|
<p>The following code merges two log files having different
|
|
internal structure:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:merge-source>
|
|
<xsl:merge-input select="doc('event-log.xml')/*/event">
|
|
<xsl:merge-key select="@timestamp"/>
|
|
</xsl:merge-input>
|
|
</xsl:merge-source>
|
|
<xsl:merge-source>
|
|
<xsl:merge-input select="doc('error-log.xml')//error">
|
|
<xsl:merge-key select="dateTime(@date, @time)"/>
|
|
</xsl:merge-input>
|
|
</xsl:merge-source>
|
|
</pre></div>
|
|
<p>Although the merge keys are computed in different ways for the
|
|
two input sequences, the keys must be compatible across the two
|
|
sequences: in this case they are both atomic values of type
|
|
<code>xs:dateTime</code>.</p>
|
|
</div>
|
|
<p>In the common case where there is only one input sequence of a
|
|
particular kind, the <code>select</code> attribute of <a href=
|
|
"#element-merge-source"><code>xsl:merge-source</code></a> may be
|
|
omitted; its default value is <code>.</code> (dot), which has the
|
|
effect that the <code>select</code> expression of the <a href=
|
|
"#element-merge-input"><code>xsl:merge-input</code></a> element is
|
|
evaluated relative to the <a title="focus" class="termref" href=
|
|
"#dt-focus">focus</a> of the <a href=
|
|
"#element-merge"><code>xsl:merge</code></a> instruction itself.</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e26723" id=
|
|
"d7e26723"></a>Example: Sorting before merging</div>
|
|
<p>Where one or more of the inputs to the merging process is not
|
|
pre-sorted, an <a href=
|
|
"#element-perform-sort"><code>xsl:perform-sort</code></a>
|
|
instruction can be used as a child of <a href=
|
|
"#element-merge-input"><code>xsl:merge-input</code></a>. For
|
|
example:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:merge-source>
|
|
<xsl:merge-input select="doc('event-log.xml')/*/event">
|
|
<xsl:merge-key select="@timestamp"/>
|
|
</xsl:merge-input>
|
|
</xsl:merge-source>
|
|
<xsl:merge-source>
|
|
<xsl:merge-input>
|
|
<xsl:perform-sort select="doc('error-log.xml')//error">
|
|
<xsl:sort select="@time"/>
|
|
</xsl:perform-sort>
|
|
<xsl:merge-key select="dateTime(current-date(), @time)"/>
|
|
</xsl:merge-input>
|
|
</xsl:merge-source>
|
|
</pre></div>
|
|
</div>
|
|
<p>An <a href=
|
|
"#element-merge-source"><code>xsl:merge-source</code></a> element
|
|
has an optional <code>name</code> attribute, whose value is a
|
|
<a title="expanded-QName" class="termref" href=
|
|
"#dt-expanded-qname">QName</a>. This name, if specified, may be
|
|
used while evaluating the <a href=
|
|
"#element-merge-action"><code>xsl:merge-action</code></a> to
|
|
identify from which source a particular item was read. For details,
|
|
see <a href="#selective-processing-of-merge-inputs"><i>15.6
|
|
Selective processing of merge inputs</i></a></p>
|
|
<p><a name="err-XTSE2185" id="err-XTSE2185"><span class=
|
|
"error">[ERR XTSE2185]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> if two
|
|
sibling <a href=
|
|
"#element-merge-source"><code>xsl:merge-source</code></a> elements
|
|
have <code>name</code> attributes whose value is the same expanded
|
|
QName.</p>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="merge-keys" id="merge-keys"></a>15.4 <a href=
|
|
"#merge-keys" style="text-decoration: none">Defining the merge
|
|
keys</a></h3>
|
|
<p>All the input sequences to the merge operation must be already
|
|
sorted: the sorting will not be performed by the merge operation.
|
|
The keys on which the input sequences are sorted are referred to as
|
|
merge keys.</p>
|
|
<p>The merge key for each type of input sequence (that is, for each
|
|
<a href="#element-merge-source"><code>xsl:merge-source</code></a>
|
|
element) is defined by a sequence of <a href=
|
|
"#element-merge-key"><code>xsl:merge-key</code></a> element
|
|
children of the <a href=
|
|
"#element-merge-input"><code>xsl:merge-input</code></a> element.
|
|
Each <a href="#element-merge-key"><code>xsl:merge-key</code></a>
|
|
element defines one merge key component. The syntax and semantics
|
|
of an <a href="#element-merge-key"><code>xsl:merge-key</code></a>
|
|
element are closely based on the rules for the <a href=
|
|
"#element-sort"><code>xsl:sort</code></a> element (the only
|
|
exception being the absence of the <code>stable</code> attribute);
|
|
the difference is that <a href=
|
|
"#element-merge-key"><code>xsl:merge-key</code></a> elements do not
|
|
cause a sort to take place, they merely declare the existing sort
|
|
order of the input sequence.</p>
|
|
<p class="element-syntax"><a name="element-merge-key" id=
|
|
"element-merge-key"></a><code><xsl:merge-key<br />
|
|
  select? = <var>expression</var><br />
|
|
  lang? = { <var>nmtoken</var> }<br />
|
|
  order? = { "ascending" | "descending" }<br />
|
|
  collation? = { <var>uri</var> }<br />
|
|
  case-order? = { "upper-first" | "lower-first" }<br />
|
|
  data-type? = { "text" | "number" |
|
|
<var>qname-but-not-ncname</var> } ><br />
|
|
  <!-- Content: <var>sequence-constructor</var>
|
|
--><br />
|
|
</xsl:merge-key></code></p>
|
|
<p>The <code>select</code> attrbute and the contained <a title=
|
|
"sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> are mutually
|
|
exclusive:</p>
|
|
<p><a name="err-XTSE2190" id="err-XTSE2190"><span class=
|
|
"error">[ERR XTSE2190]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> if an
|
|
<a href="#element-merge-key"><code>xsl:merge-key</code></a> element
|
|
with a <code>select</code> attribute has non-empty content.</p>
|
|
<p>The effect of the <a href=
|
|
"#element-merge-key"><code>xsl:merge-key</code></a> elements is
|
|
defined in terms of the rules for an equivalent sequence of
|
|
<a href="#element-sort"><code>xsl:sort</code></a> elements: if the
|
|
rules for sorting (see <a href="#sorting-process"><i>13.1.1 The
|
|
Sorting Process</i></a>) with <code>stable="yes"</code> would place
|
|
an item <var>A</var> before an item <var>B</var> in the <a title=
|
|
"sorted sequence" class="termref" href="#dt-sorted-sequence">sorted
|
|
sequence</a> produced by the sorting process, then <var>A</var>
|
|
must precede <var>B</var> in the input sequence to the merging
|
|
process.</p>
|
|
<p>The merge keys of the various input sequences to a merge
|
|
operation must be compatible with each other, since the merge
|
|
operation will decide the ordering of the result sequence by
|
|
comparing merge key values across input sequences. This means that
|
|
across all the <a href=
|
|
"#element-merge-source"><code>xsl:merge-source</code></a> children
|
|
of an <a href="#element-merge"><code>xsl:merge</code></a>
|
|
instruction:</p>
|
|
<ul>
|
|
<li>
|
|
<p>Each <a href=
|
|
"#element-merge-source"><code>xsl:merge-source</code></a> element
|
|
<span class="verb">must</span> have the same number of <a href=
|
|
"#element-merge-key"><code>xsl:merge-key</code></a> grandchild
|
|
elements; let this number be <var>N</var></p>
|
|
</li>
|
|
<li>
|
|
<p>For each integer <var>J</var> in 1..<var>N</var>, consider the
|
|
set of <a href="#element-merge-key"><code>xsl:merge-key</code></a>
|
|
elements that are in position <var>J</var> among the <a href=
|
|
"#element-merge-key"><code>xsl:merge-key</code></a> children of
|
|
their parent <a href=
|
|
"#element-merge-input"><code>xsl:merge-input</code></a> element.
|
|
All the <a href="#element-merge-key"><code>xsl:merge-key</code></a>
|
|
elements in this set <span class="verb">must</span> have the same
|
|
<a title="effective value" class="termref" href=
|
|
"#dt-effective-value">effective value</a> for their
|
|
<code>lang</code>, <code>order</code>, <code>collation</code>,
|
|
<code>case-order</code>, and <code>data-type</code> attributes,
|
|
where having the same effective value in this case means that
|
|
either both attributes must be absent, or both must be present and
|
|
evaluate to the same value; and in addition in the case of
|
|
<code>collation</code> the absolute URI must be the same after
|
|
resolving against the base URI.</p>
|
|
</li>
|
|
</ul>
|
|
<p>If any of the attributes <code>lang</code>, <code>order</code>,
|
|
<code>collation</code>, <code>case-order</code>, or
|
|
<code>data-type</code> are <a title="attribute value template"
|
|
class="termref" href="#dt-attribute-value-template">attribute value
|
|
templates</a>, then their <a title="effective value" class=
|
|
"termref" href="#dt-effective-value">effective values</a> are
|
|
evaluated using the <a title="focus" class="termref" href=
|
|
"#dt-focus">focus</a> of the containing <a href=
|
|
"#element-merge"><code>xsl:merge</code></a> instruction.</p>
|
|
<p><a name="err-XTSE2200" id="err-XTSE2200"><span class=
|
|
"error">[ERR XTSE2200]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> if the
|
|
number of <a href=
|
|
"#element-merge-key"><code>xsl:merge-key</code></a> grandchildren
|
|
of a <a href=
|
|
"#element-merge-source"><code>xsl:merge-source</code></a> element
|
|
is not equal to the number of <a href=
|
|
"#element-merge-key"><code>xsl:merge-key</code></a> grandchildren
|
|
of another <a href=
|
|
"#element-merge-source"><code>xsl:merge-source</code></a> child of
|
|
the same <a href="#element-merge"><code>xsl:merge</code></a>
|
|
instruction.</p>
|
|
<p><a name="err-XTSE2210" id="err-XTSE2210"><span class=
|
|
"error">[ERR XTSE2210]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> if there
|
|
are two <a href="#element-merge-key"><code>xsl:merge-key</code></a>
|
|
grandchildren of an <a href=
|
|
"#element-merge"><code>xsl:merge</code></a> instruction that occupy
|
|
corresponding positions among the <a href=
|
|
"#element-merge-key"><code>xsl:merge-key</code></a> children of two
|
|
different <a href=
|
|
"#element-merge-input"><code>xsl:merge-input</code></a> elements
|
|
and that have differing <a title="effective value" class="termref"
|
|
href="#dt-effective-value">effective values</a> for any of the
|
|
attributes <code>lang</code>, <code>order</code>,
|
|
<code>collation</code>, <code>case-order</code>, or
|
|
<code>data-type</code>. Values are considered to differ if the
|
|
attribute is present on one element and not on the other, or if it
|
|
is present on both elements with <a title="effective value" class=
|
|
"termref" href="#dt-effective-value">effective values</a> that are
|
|
not equal to each other. In the case of the <code>collation</code>
|
|
attribute, the values are compared as absolute URIs after resolving
|
|
against the base URI.</p>
|
|
<p><a name="err-XTDE2220" id="err-XTDE2220"><span class=
|
|
"error">[ERR XTDE2220]</span></a> It is a <a title="dynamic error"
|
|
class="termref" href="#dt-dynamic-error">dynamic error</a> if any
|
|
input sequence to an <a href=
|
|
"#element-merge"><code>xsl:merge</code></a> instruction contains
|
|
two items that are not correctly sorted according to the merge key
|
|
values defined on the <a href=
|
|
"#element-merge-key"><code>xsl:merge-key</code></a> children of the
|
|
corresponding <a href=
|
|
"#element-merge-input"><code>xsl:merge-input</code></a> element,
|
|
when compared using the collation rules defined by the attributes
|
|
of the corresponding <a href=
|
|
"#element-merge-key"><code>xsl:merge-key</code></a> children of the
|
|
<a href="#element-merge"><code>xsl:merge</code></a>
|
|
instruction.</p>
|
|
<p><a name="err-XTTE2230" id="err-XTTE2230"><span class=
|
|
"error">[ERR XTTE2230]</span></a> It is a <a title="type errors"
|
|
class="termref" href="#dt-type-error">type error</a> if some item
|
|
selected by a particular merge key in one input sequence is not
|
|
comparable using the XPath <code>le</code> operator with some item
|
|
selected by the corresponding sort key in another input
|
|
sequence.</p>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="merge-action" id="merge-action"></a>15.5 <a href=
|
|
"#merge-action" style="text-decoration: none">The</a> <a href=
|
|
"#element-merge-action"><code>xsl:merge-action</code></a> <a href=
|
|
"#merge-action" style="text-decoration: none">element</a></h3>
|
|
<p>The <a href=
|
|
"#element-merge-action"><code>xsl:merge-action</code></a> child of
|
|
an <a href="#element-merge"><code>xsl:merge</code></a> instruction
|
|
defines the processing to be applied for each distinct set of merge
|
|
key values found in the input sequences to the <a href=
|
|
"#element-merge"><code>xsl:merge</code></a> instruction.</p>
|
|
<p class="element-syntax"><a name="element-merge-action" id=
|
|
"element-merge-action"></a><code><xsl:merge-action><br />
|
|
  <!-- Content: (<var>sequence-constructor</var>)
|
|
--><br />
|
|
</xsl:merge-action></code></p>
|
|
<p>The merge key values for each item in an input sequence are
|
|
calculated based on the corresponding <a href=
|
|
"#element-merge-key"><code>xsl:merge-key</code></a> elements, in
|
|
the same way as <a title="sort key value" class="termref" href=
|
|
"#dt-sort-key-value">sort key values</a> are calculated using a
|
|
sequence of <a href="#element-sort"><code>xsl:sort</code></a>
|
|
elements (see <a href="#sorting-process"><i>13.1.1 The Sorting
|
|
Process</i></a>). If several items from the same or from different
|
|
input sequences have the same values for all their merge keys
|
|
(comparing pairwise), then they are considered to form a group. The
|
|
sequence constructor contained in the <a href=
|
|
"#element-merge-action"><code>xsl:merge-action</code></a> element
|
|
is evaluated once for each such group of items, and the result of
|
|
the <a href="#element-merge"><code>xsl:merge</code></a> instruction
|
|
is the concatenation of the results obtained by processing each
|
|
group in turn.</p>
|
|
<p><span>The groups are processed one by one, based on the values
|
|
of the merge keys for the group.</span> If group <var>G</var> has a
|
|
set of merge key values <var>M</var>, while group <var>H</var> has
|
|
a set of merge key values <var>N</var>, then in the result of the
|
|
<a href="#element-merge"><code>xsl:merge</code></a> instruction,
|
|
the result of processing group <var>G</var> will precede the result
|
|
of processing <var>H</var> if and only if <var>M</var> precedes
|
|
<var>N</var> in the sort order defined by the <code>lang</code>,
|
|
<code>order</code>, <code>collation</code>,
|
|
<code>case-order</code>, and <code>data-type</code> attributes of
|
|
the merge key definitions.</p>
|
|
<p>Generally, two sets of sort key values are distinct if any
|
|
corresponding items in the two sets of values do not compare equal
|
|
under the rules for the XPath <code>eq</code> operator, under the
|
|
collating rules for the corresponding merge key definition. In rare
|
|
cases, when considering more than two sets of sort key values,
|
|
ambiguities may arise because of the non-transitivity of the
|
|
<code>eq</code> operator when applied across different numeric
|
|
types. In this situation, the partitioning of items into sets
|
|
having distinct key values is handled in the same way as for
|
|
<a href=
|
|
"#element-for-each-group"><code>xsl:for-each-group</code></a> (see
|
|
<a href="#non-transitivity"><i>14.5 Non-Transitivity</i></a>), and
|
|
is to some extent <a title="implementation-dependent" class=
|
|
"termref" href=
|
|
"#dt-implementation-dependent">implementation-dependent</a>.</p>
|
|
<p>While evaluating the sequence constructor contained within the
|
|
<a href="#element-merge-action"><code>xsl:merge-action</code></a>
|
|
element, the expression <code>current-grouping-key()[N]</code>
|
|
returns the value of the <var>Nth</var> merge key. There may be
|
|
several input items having merge keys that are equal but
|
|
distinguishable (for example the number 1.0 as a float and as a
|
|
double, or the strings "A" and "a" under a case-blind collation);
|
|
in this case the result of the <a href=
|
|
"#function-current-grouping-key"><code>current-grouping-key</code></a>
|
|
is the value of the grouping key computed for the first item in the
|
|
current group, after atomization and casting of
|
|
<code>xs:untypedAtomic</code> to <code>xs:string</code>.</p>
|
|
<p>While evaluating the sequence constructor contained within the
|
|
<a href="#element-merge-action"><code>xsl:merge-action</code></a>
|
|
element, the function <code>current-group()</code> (with no
|
|
arguments) returns the set of items (zero or more from each input
|
|
sequence) that have this set of values as their merge key value. It
|
|
is possible to distinguish which items came from which merge
|
|
source: see <a href="#selective-processing-of-merge-inputs"><i>15.6
|
|
Selective processing of merge inputs</i></a>.</p>
|
|
<p>Within the result of the <a href=
|
|
"#function-current-group"><code>current-group</code></a> function,
|
|
the ordering of items from the input sequences is as follows, in
|
|
major-to-minor order:</p>
|
|
<ul>
|
|
<li>
|
|
<p>Items are first ordered by the <a href=
|
|
"#element-merge-source"><code>xsl:merge-source</code></a> element
|
|
that defined the input sequence from which the item was taken;
|
|
items from <a href=
|
|
"#element-merge-source"><code>xsl:merge-source</code></a>
|
|
<var>A</var> precede items from <a href=
|
|
"#element-merge-source"><code>xsl:merge-source</code></a>
|
|
<var>B</var> if <var>A</var> precedes <var>B</var> in document
|
|
order within the stylesheet.</p>
|
|
</li>
|
|
<li>
|
|
<p>Items from different input sequences selected by the same
|
|
<a href="#element-merge-source"><code>xsl:merge-source</code></a>
|
|
element are then ordered based on the order of the anchor items in
|
|
the sequence selected by evaluating the <code>select</code>
|
|
attribute of the <a href=
|
|
"#element-merge-source"><code>xsl:merge-source</code></a>
|
|
element.</p>
|
|
</li>
|
|
<li>
|
|
<p>Finally, duplicate items from the same input sequence retain
|
|
their order from the input sequence.</p>
|
|
</li>
|
|
</ul>
|
|
<p>The <a title="focus" class="termref" href="#dt-focus">focus</a>
|
|
for evaluation of the sequence constructor contained in the
|
|
<a href="#element-merge-source"><code>xsl:merge-source</code></a>
|
|
element is as follows:</p>
|
|
<ul>
|
|
<li>
|
|
<p>The <a title="context item" class="termref" href=
|
|
"#dt-context-item">context item</a> is the first item in the
|
|
current group, that is <code>current-group()[1]</code></p>
|
|
</li>
|
|
<li>
|
|
<p>The <a title="context position" class="termref" href=
|
|
"#dt-context-position">context position</a> is the position of the
|
|
current group within the sequence of groups (so the first
|
|
evaluation of <a href=
|
|
"#element-merge-action"><code>xsl:merge-action</code></a> has
|
|
<code>position()=1</code>, the second has
|
|
<code>position()=2</code>, and so on).</p>
|
|
</li>
|
|
<li>
|
|
<p>The <a title="context size" class="termref" href=
|
|
"#dt-context-size">context size</a> is the number of groups, that
|
|
is, the number of distinct sets of merge key values.</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="selective-processing-of-merge-inputs" id=
|
|
"selective-processing-of-merge-inputs"></a>15.6 <a href=
|
|
"#selective-processing-of-merge-inputs" style=
|
|
"text-decoration: none">Selective processing of merge
|
|
inputs</a></h3>
|
|
<p>During the processing of <a href=
|
|
"#element-merge-action"><code>xsl:merge-action</code></a>, there
|
|
will in general be one or more items with the same values for their
|
|
merge keys, together forming the current group. Within the current
|
|
group, each item originates from one merge input, which in turn is
|
|
associated with one merge source. A merge source may be identified
|
|
by a QName (the value of the <code>name</code> attribute on the
|
|
<a href="#element-merge-source"><code>xsl:merge-source</code></a>
|
|
element). For each merge source, there are zero or more merge
|
|
inputs, which are identified by positive integers representing the
|
|
position of the anchor item for the merge input within the sequence
|
|
of anchor items selected by the <code>select</code> attribute of
|
|
the <a href=
|
|
"#element-merge-source"><code>xsl:merge-source</code></a> element.
|
|
Since duplicate merge keys are allowed within a single input, each
|
|
merge input contributes zero or more items to the current
|
|
group.</p>
|
|
<p>The function <a href=
|
|
"#function-current-merge-inputs"><code>current-merge-inputs</code></a>
|
|
may be used to obtain the items within the current group that are
|
|
associated with each named merge source, and with each merge input
|
|
within that source. The function takes as input the name of the
|
|
merge source (as a lexical QName, expanded using the in-scope
|
|
namespaces from the static context), and it returns a sequence of
|
|
accessors, one accessor for each merge input within the merge
|
|
source, corresponding one-to-one with the sequence of anchor items
|
|
selected by the <code>select</code> attribute of the <a href=
|
|
"#element-merge-source"><code>xsl:merge-source</code></a> element.
|
|
Each accessor is a zero-argument anonymous function which when
|
|
invoked returns the sequence of zero or more items (each a member
|
|
of the current group) that derive from the corresponding merge
|
|
input.</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e27341" id=
|
|
"d7e27341"></a>Example: Selective processing of merge inputs</div>
|
|
<p>Consider a situation where there are two merge sources, named
|
|
"master" and "update"; the master source identifies a single merge
|
|
input file (the master file), while the update source identifies a
|
|
set of <var>N</var> update files, perhaps one for each day of the
|
|
week. The required logic is that if a merge key is present only in
|
|
the master file, then the corresponding item should be copied to
|
|
the output; if it is present in a single update file then that item
|
|
replaces the corresponding item from the master file; if it is
|
|
present in several update files, then an error is raised. This can
|
|
be achieved as follows:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:merge>
|
|
<xsl:merge-source name="master" select="doc('master.xml')">
|
|
<xsl:merge-input select="/*/*">
|
|
<xsl:merge-key select="@key"/>
|
|
</xsl:merge-input>
|
|
</xsl:merge-source>
|
|
<xsl:merge-source name="update" select="collection('updates')">
|
|
<xsl:merge-input select="/*/*">
|
|
<xsl:merge-key select="@affected-key"/>
|
|
</xsl:merge-input>
|
|
</xsl:merge-source>
|
|
<xsl:merge-action>
|
|
<xsl:variable name="update-accessors"
|
|
select="current-merge-inputs('update')"
|
|
as="(function() as item()*)*"/>
|
|
<xsl:variable name="number-of-updates"
|
|
select="count($update-accessors[exists(.())])"
|
|
as="xs:integer"/>
|
|
<xsl:choose>
|
|
<xsl:when test="$number-of-updates = 0">
|
|
<xsl:copy-of select="current-merge-inputs('master')()"/>
|
|
</xsl:when>
|
|
<xsl:when test="$number-of-updates = 1">
|
|
<xsl:copy-of select="for $a in $update-accessors return $a()"/>
|
|
</xsl:when>
|
|
<xsl:otherwise>
|
|
<xsl:message>
|
|
Multiple updates for the same master record!
|
|
</xsl:message>
|
|
</xsl:otherwise>
|
|
</xsl:choose>
|
|
</xsl:merge-action>
|
|
</xsl:merge>
|
|
|
|
</pre></div>
|
|
<p>Some words of explanation:</p>
|
|
<ul>
|
|
<li>
|
|
<p>The variable <code>$number-of-updates</code> is computed as the
|
|
number of accessors for the update source, filtered to select only
|
|
those for which the accessor returns a non-empty sequence. The
|
|
expression <code>.()</code> invokes the accessor that is the
|
|
current item.</p>
|
|
</li>
|
|
<li>
|
|
<p>The expression <code>current-merge-inputs('master')</code>
|
|
obtains a sequence of accessors for all the merge inputs associated
|
|
with the master source. There is only one, so it returns a single
|
|
accessor, which is invoked directly (using <code>()</code>) to
|
|
obtain the item in the master file.</p>
|
|
</li>
|
|
<li>
|
|
<p>The expression <code>for $a in $update-accessors return
|
|
$a()</code> invokes all the accessors associated with the update
|
|
source, and concatenates their results; although all but one of the
|
|
accessors will return an empty sequence, this is <span>a convenient
|
|
way of obtaining the one sequence that is non-empty.</span></p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<p>The function <a href=
|
|
"#function-current-merge-inputs"><code>current-merge-inputs</code></a>
|
|
is defined as follows:</p>
|
|
<a name="function-current-merge-inputs" id=
|
|
"function-current-merge-inputs"></a>
|
|
<div class="proto">
|
|
<table border="0" cellpadding="0" cellspacing="0">
|
|
<tr>
|
|
<td valign="baseline"><code class=
|
|
"function">current-merge-inputs</code>(</td>
|
|
<td valign="baseline"><code class="arg">$source-name</code></td>
|
|
<td valign="baseline"><code class=
|
|
"as"> as </code><code class=
|
|
"type">xs:string</code>)<code class=
|
|
"as"> as </code><code class="return-type">(function() as
|
|
item()*)</code></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<p>The function takes as input the name of a merge source,
|
|
expressed as a <a title="lexical QName" class="termref" href=
|
|
"#dt-lexical-qname">lexical QName</a></p>
|
|
<p><a name="err-XTDE2240" id="err-XTDE2240"><span class=
|
|
"error">[ERR XTDE2240]</span></a> It is a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> 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
|
|
<a href="#element-merge-source"><code>xsl:merge-source</code></a>
|
|
element in the <a title="current merge activation" class="termref"
|
|
href="#dt-current-merge-activation">current merge activation</a>,
|
|
<span>or if there is no <a title="current merge activation" class=
|
|
"termref" href="#dt-current-merge-activation">current merge
|
|
activation</a></span>. If the processor is able to detect the error
|
|
statically (for example, when the argument is supplied as a string
|
|
literal), then the processor <span class="verb">may</span>
|
|
optionally signal this as a <a title="static error" class="termref"
|
|
href="#dt-static-error">static error</a>.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-current-merge-activation" id="dt-current-merge-activation"
|
|
title="current merge activation"></a>During each evaluation of the
|
|
<a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> contained in an
|
|
<a href="#element-merge-action"><code>xsl:merge-action</code></a>
|
|
element, there is a <b>current merge activation</b>.<span class=
|
|
"definition">]</span></p>
|
|
<p>The <a title="current merge activation" class="termref" href=
|
|
"#dt-current-merge-activation">current merge activation</a> has the
|
|
following properties:</p>
|
|
<ul>
|
|
<li>
|
|
<p>The <a href="#element-merge"><code>xsl:merge</code></a> element
|
|
<var>M</var> that is the parent of the <a href=
|
|
"#element-merge-action"><code>xsl:merge-action</code></a> element
|
|
being evaluated</p>
|
|
</li>
|
|
<li>
|
|
<p>A mapping <var>SA</var> from each <a href=
|
|
"#element-merge-source"><code>xsl:merge-source</code></a> child of
|
|
<var>M</var> to the sequence of anchor items selected by evaluating
|
|
the (implicit or explicit) <code>select</code> expression on that
|
|
<a href="#element-merge-source"><code>xsl:merge-source</code></a>
|
|
element</p>
|
|
</li>
|
|
<li>
|
|
<p>A current <a title="composite merge key value" class="termref"
|
|
href="#dt-composite-merge-key-value">composite merge key
|
|
value</a></p>
|
|
</li>
|
|
</ul>
|
|
<blockquote>
|
|
<p><b><a name="issue-current-merge-activation" id=
|
|
"issue-current-merge-activation">Issue 18
|
|
(current-merge-activation)</a>:</b></p>
|
|
<p>The concept of the <b>current-merge-activation</b> needs to be
|
|
and incorporated into the dynamic context.</p>
|
|
</blockquote>
|
|
<p>For each anchor item <var>A</var> in the mapping <var>SA</var>,
|
|
there is an associated <a title="merge input sequence" class=
|
|
"termref" href="#dt-merge-input-sequence">merge input sequence</a>
|
|
obtained by evaluating the <code>select</code> expression of the
|
|
<a href="#element-merge-input"><code>xsl:merge-input</code></a>
|
|
child of the corresponding <a href=
|
|
"#element-merge-source"><code>xsl:merge-source</code></a> element
|
|
with <var>A</var> as the context item.</p>
|
|
<p>The <a href=
|
|
"#function-current-merge-inputs"><code>current-merge-inputs</code></a>
|
|
function returns a sequence of function items, referred to as
|
|
accessors. Each accessor is an anonymous function with an arity of
|
|
zero. The sequence of accessors corresponds one-to-one with the
|
|
sequence of anchor items defined by the mapping <var>SA</var> for
|
|
the selected <a href=
|
|
"#element-merge-source"><code>xsl:merge-source</code></a> in the
|
|
<a title="current merge activation" class="termref" href=
|
|
"#dt-current-merge-activation">current merge activation</a>.
|
|
Invoking the <var>N</var>th accessor function returns selected
|
|
items from the <a title="merge input sequence" class="termref"
|
|
href="#dt-merge-input-sequence">merge input sequence</a> associated
|
|
with the <var>N</var>th anchor item in this sequence. The selected
|
|
items are those whose whose <a title="composite merge key value"
|
|
class="termref" href="#dt-composite-merge-key-value">composite
|
|
merge key value</a> is equal to the composite merge key value of
|
|
the <a title="current merge activation" class="termref" href=
|
|
"#dt-current-merge-activation">current merge activation</a>. The
|
|
selected items are returned retaining their order from the
|
|
<a title="merge input sequence" class="termref" href=
|
|
"#dt-merge-input-sequence">merge input sequence</a>.</p>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="merging-streamed-inputs" id=
|
|
"merging-streamed-inputs"></a>15.7 <a href=
|
|
"#merging-streamed-inputs" style="text-decoration: none">Merging
|
|
streamed input documents</a></h3>
|
|
<p>An important reason for introducing the <a href=
|
|
"#element-merge"><code>xsl:merge</code></a> instruction is to allow
|
|
elements from several input documents to be merged without
|
|
constructing the entire tree representation of the input documents
|
|
in memory. This can be achieved by using <a href=
|
|
"#element-merge"><code>xsl:merge</code></a> in conjunction with the
|
|
<a href="#element-stream"><code>xsl:stream</code></a> instruction
|
|
defined in <a href="#streaming"><i>18 Streaming</i></a>.</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e27548" id=
|
|
"d7e27548"></a>Example: Merging two streamed documents with
|
|
different structure</div>
|
|
<p>The following code merges two log files having different
|
|
internal structure:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:merge>
|
|
<xsl:merge-source>
|
|
<xsl:merge-input>
|
|
<xsl:merge-key select="@timestamp"/>
|
|
<xsl:stream href="event-log.xml">
|
|
<xsl:copy-of select="*/event"/>
|
|
</xsl:stream>
|
|
</xsl:merge-input>
|
|
</xsl:merge-source>
|
|
<xsl:merge-source>
|
|
<xsl:merge-input>
|
|
<xsl:merge-key select="dateTime(@date, @time)"/>
|
|
<xsl:stream href="error-log.xml">
|
|
<xsl:copy-of select="*/event"/>
|
|
</xsl:stream>
|
|
</xsl:merge-input>
|
|
</xsl:merge-source>
|
|
<xsl:merge-action>
|
|
<xsl:sequence select="current-group()"/>
|
|
</xsl:merge-action>
|
|
</xsl:merge>
|
|
</pre></div>
|
|
<p>Within the <a href="#element-stream"><code>xsl:stream</code></a>
|
|
instructions, it is necessary to use <a href=
|
|
"#element-copy-of"><code>xsl:copy-of</code></a> rather than
|
|
<a href="#element-sequence"><code>xsl:sequence</code></a> because
|
|
the <a href="#element-stream"><code>xsl:stream</code></a>
|
|
instruction is not allowed to return streamed nodes. An intelligent
|
|
optimizer might be able to use streaming to execute this code,
|
|
avoiding the need to copy the <code>event</code> elements to
|
|
temporary trees held in memory.</p>
|
|
</div>
|
|
<p> </p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e27572" id=
|
|
"d7e27572"></a>Example: Merging a collection of streamed
|
|
documents</div>
|
|
<p>The following code merges the top-level elements (that is, the
|
|
children of the outermost element) of a collection of input
|
|
documents into a single result document.</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:merge>
|
|
<xsl:merge-source select="uri-collection('log-collection')">
|
|
<xsl:merge-input>
|
|
<xsl:merge-key select="@timestamp" order="ascending"/>
|
|
<xsl:stream href="{.}">
|
|
<xsl:copy-of select="events/event"/>
|
|
</xsl:stream>
|
|
</xsl:merge-input>
|
|
</xsl:merge-source>
|
|
<xsl:merge-action>
|
|
<xsl:sequence select="current-group()"/>
|
|
</xsl:merge-action>
|
|
</xsl:merge>
|
|
</pre></div>
|
|
<p>In this example the <a href=
|
|
"#function-uri-collection"><code>uri-collection</code></a> function
|
|
is used to retrieve the document URIs of the documents in a
|
|
collection, without retrieving the <span>documents
|
|
themselves</span>. These URIs are used as the anchor items of the
|
|
<a href="#element-merge-source"><code>xsl:merge-source</code></a>,
|
|
and the individual input sequences are selected from these URIs by
|
|
using the <a href="#element-stream"><code>xsl:stream</code></a>
|
|
instruction. As with the previous example, an intelligent optimizer
|
|
might avoid building each <code>event</code> element as a tree in
|
|
memory.</p>
|
|
</div>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="merge-examples" id="merge-examples"></a>15.8 <a href=
|
|
"#merge-examples" style="text-decoration: none">Examples of
|
|
xsl:merge</a></h3>
|
|
<p>Previous sections introduced examples designed to illustrate
|
|
some specific features of the <a href=
|
|
"#element-merge"><code>xsl:merge</code></a> instruction. This
|
|
section provides some further examples to illustrate different ways
|
|
in which the instruction can be used.</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e27604" id=
|
|
"d7e27604"></a>Example: Applying transactions to a master
|
|
file</div>
|
|
<p>This example applies transactions from a transaction file to a
|
|
master file. Records in the master file for which there is no
|
|
corresponding transaction are copied unchanged. The transaction
|
|
file contains instructions to delete, replace, or insert records
|
|
identified by an ID value. The master file is known to be sorted on
|
|
the ID value; the transaction file is unsorted.</p>
|
|
<p>Master file document structure:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<data>
|
|
<record ID="A0001"><...></record>
|
|
<record ID="A0002"><...></record>
|
|
<record ID="A0003"><...></record>
|
|
</data>
|
|
</pre></div>
|
|
<p>Transaction file document structure:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<transactions>
|
|
<update record="A0004" action="insert"><...></update>
|
|
<update record="A0002" action="delete"/>
|
|
<update record="A0003" action="replace"><...></update>
|
|
</transactions>
|
|
</pre></div>
|
|
<p>Solution:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:merge>
|
|
<xsl:merge-source select="doc('master.xml')" name="master">
|
|
<xsl:merge-input select="data/record">
|
|
<xsl:merge-key select="@ID"/>
|
|
</xsl:merge-input>
|
|
</xsl:merge-source>
|
|
<xsl:merge-source name="updates">
|
|
<xsl:merge-input>
|
|
<xsl:perform-sort select="
|
|
doc('transactions.xml')/transactions/update">
|
|
<xsl:sort select="@record" order="ascending"/>
|
|
</xsl:perform-sort>
|
|
<xsl:merge-key select="@record"/>
|
|
</xsl:merge-input>
|
|
</xsl:merge-source>
|
|
<xsl:merge-action>
|
|
<xsl:variable name="master" select="current-group('master')"/>
|
|
<xsl:variable name="update" select="current-group('updates')"/>
|
|
<xsl:choose>
|
|
<xsl:when test="empty($update)">
|
|
<xsl:copy-of select="$master"/>
|
|
</xsl:when>
|
|
<xsl:when test="$update/@action=('insert', 'replace')">
|
|
<record ID="{current-grouping-key()}">
|
|
<xsl:copy-of select="$update/*"/>
|
|
</record>
|
|
</xsl:when>
|
|
<xsl:when test="$update/@action='delete'"/>
|
|
</xsl:choose>
|
|
</xsl:merge-action>
|
|
</xsl:merge>
|
|
</pre></div>
|
|
<p>If there are multiple transaction files, represented say by the
|
|
contents of a collection named
|
|
<code>transaction-files.collection</code>, they can be handled by
|
|
replacing the second <a href=
|
|
"#element-merge-source"><code>xsl:merge-source</code></a> in the
|
|
above example with the following code:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:merge-source name="updates"
|
|
select="collection('transaction-files.collection')">
|
|
<xsl:merge-input>
|
|
<xsl:perform-sort select="/transactions/update">
|
|
<xsl:sort select="@record" order="ascending"/>
|
|
</xsl:perform-sort>
|
|
<xsl:merge-key select="@record"/>
|
|
</xsl:merge-input>
|
|
</xsl:merge-source>
|
|
</pre></div>
|
|
</div>
|
|
<p> </p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e27631" id=
|
|
"d7e27631"></a>Example: Merging two sequences of numbers</div>
|
|
<p>The <a href="#element-merge"><code>xsl:merge</code></a>
|
|
instruction can be used to determine the union, intersection, or
|
|
difference of two sequences of numbers (or other atomic values).
|
|
This code gives the union:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:merge>
|
|
<xsl:merge-source>
|
|
<xsl:merge-input select="1 to 30">
|
|
<xsl:merge-key select="."/>
|
|
</xsl:merge-input>
|
|
</xsl:merge-source>
|
|
<xsl:merge-source>
|
|
<xsl:merge-input select="20 to 40">
|
|
<xsl:merge-key select="."/>
|
|
</xsl:merge-input>
|
|
</xsl:merge-source>
|
|
<xsl:merge-action>
|
|
<xsl:value-of select="current-grouping-key()"/>
|
|
</xsl:merge-action>
|
|
</xsl:merge>
|
|
|
|
</pre></div>
|
|
<p>While this gives the intersection:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:merge>
|
|
<xsl:merge-source>
|
|
<xsl:merge-input select="1 to 30">
|
|
<xsl:merge-key select="."/>
|
|
</xsl:merge-input>
|
|
</xsl:merge-source>
|
|
<xsl:merge-source>
|
|
<xsl:merge-input select="20 to 40">
|
|
<xsl:merge-key select="."/>
|
|
</xsl:merge-input>
|
|
</xsl:merge-source>
|
|
<xsl:merge-action>
|
|
<xsl:if test="count(current-group()) eq 2"
|
|
<xsl:value-of select="current-grouping-key()"/>
|
|
</xsl:if>
|
|
</xsl:merge-action>
|
|
</xsl:merge>
|
|
|
|
</pre></div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="div1">
|
|
<h2><a name="splitting" id="splitting"></a>16 <a href="#splitting"
|
|
style="text-decoration: none">Splitting</a></h2>
|
|
<div class="div2">
|
|
<h3><a name="splitting-introduction" id=
|
|
"splitting-introduction"></a>16.1 <a href="#splitting-introduction"
|
|
style="text-decoration: none">Introduction</a></h3>
|
|
<p>Sometimes it is convenient to be able to compute multiple
|
|
results during a single scan of the input data. For example, a
|
|
transformation may wish to rename selected elements, and also to
|
|
output a count of how many elements have been renamed.
|
|
Traditionally in a functional language this means computing two
|
|
separate functions of the input sequence, which (in the absence of
|
|
sophisticated optimization) will result in the input being scanned
|
|
twice. This is inconsistent with streaming, where the input is only
|
|
available to be scanned once, and it can also lead to poor
|
|
performance in non-streaming applications.</p>
|
|
<p>To meet this requirement, XSLT 2.1 introduces the instruction
|
|
<a href="#element-fork"><code>xsl:fork</code></a>. The content of
|
|
this instruction is a <a title="sequence constructor" class=
|
|
"termref" href="#dt-sequence-constructor">sequence constructor</a>,
|
|
and in a formal sense the effect of the instruction is simply to
|
|
return the result of evaluating the sequence constructor. However,
|
|
the presence of the instruction affects the analysis of
|
|
streamability (see <a href="#streamability"><i>18.4 Streamability
|
|
Analysis</i></a>). In particular, when <a href=
|
|
"#element-fork"><code>xsl:fork</code></a> is used in a context
|
|
where streaming is required, each independent instruction within
|
|
the sequence constructor must be streamable, but the analysis
|
|
assumes that these instructions can all be evaluated during a
|
|
single pass of the streamed input document.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>The semantics of the instruction require a number of result
|
|
sequences to be computed during a single pass of the input. A
|
|
processor <span class="verb">may</span> interpret this as a request
|
|
to use multiple threads. However, implementations using a single
|
|
thread are feasible, and this instruction is not intended primarily
|
|
as a means for stylesheet authors to express their intentions with
|
|
regard to multi-threaded execution.</p>
|
|
</div>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>Because multiple results are computed during a single pass of
|
|
the input, and then concatenated into a single sequence, this
|
|
instruction will generally involve some buffering of results. The
|
|
amount of memory used <span class="verb">should not</span> exceed
|
|
that needed to hold the results of the instruction. However, within
|
|
this principle, implementations may adopt a variety of strategies
|
|
for evaluation; for example, there may be cases where buffering of
|
|
the input is more efficient than buffering of output.</p>
|
|
<p>Generally, stylesheet authors indicate that buffering of input
|
|
is the preferred strategy by using the <a href=
|
|
"#function-copy-of"><code>copy-of</code></a> or <a href=
|
|
"#function-snapshot"><code>snapshot</code></a> functions, and
|
|
indicate that buffering of output is preferred by using <a href=
|
|
"#element-fork"><code>xsl:fork</code></a>. However, conformant
|
|
processors are not constrained in their choice of evaluation
|
|
strategies.</p>
|
|
</div>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e27689" id=
|
|
"d7e27689"></a>Example: Splitting a transaction file</div>
|
|
<p>Consider a transaction file that contains a sequence of debits
|
|
and credits:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<transactions>
|
|
<transaction value="5.60"/>
|
|
<transaction value="11.20"/>
|
|
<transaction value="-3.40"/>
|
|
<transaction value="8.90"/>
|
|
<transaction value="-1.99"/>
|
|
</transactions>
|
|
</pre></div>
|
|
<p>where the requirement is to split this into two separate files
|
|
containing credits and debits respectively.</p>
|
|
<p>This can be achieved in <a title="guaranteed-streamable" class=
|
|
"termref" href=
|
|
"#dt-guaranteed-streamable">guaranteed-streamable</a> code as
|
|
follows:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:stream href="transactions.xml">
|
|
<xsl:fork>
|
|
<xsl:result-document name="credits.xml">
|
|
<credits>
|
|
<xsl:copy-of select="transactions/transaction[@value ge 0]"/>
|
|
</credits>
|
|
</xsl:result-document>
|
|
<xsl:result-document name="debits.xml">
|
|
<debits>
|
|
<xsl:copy-of select="transactions/transaction[@value lt 0]"/>
|
|
</debits>
|
|
</xsl:result-document>
|
|
</xsl:fork>
|
|
</xsl:stream>
|
|
|
|
</pre></div>
|
|
<p>In the absence of the <a href=
|
|
"#element-fork"><code>xsl:fork</code></a> instruction, this would
|
|
not be streamable, because the construct includes two downwards
|
|
selections in the input document (represented by the path
|
|
expressions <code>transactions/transaction[@value ge 0]</code> and
|
|
<code>transactions/transaction[@value lt 0]</code>). With the
|
|
addition of the <a href="#element-fork"><code>xsl:fork</code></a>
|
|
instruction, however, each <a href=
|
|
"#element-result-document"><code>xsl:result-document</code></a>
|
|
instruction is allowed to make a downwards selection.</p>
|
|
<p>One possible implementation model for this is as follows: a
|
|
single thread reads the source document, and sends parsing events
|
|
such as start-element and end-element to two other threads, each of
|
|
which is writing one of the two result documents. Each of these
|
|
implements the downwards-selecting path expression using a process
|
|
that waits until the next <code>transaction</code> start-element
|
|
event is received; when this event is received, the process
|
|
examines the <code>@value</code> attribute to determine whether or
|
|
not this transaction is to be copied; if it is, then all events
|
|
until the matching <code>transaction</code> end-element event are
|
|
copied to the serializer for the result document; otherwise, these
|
|
events are discarded.</p>
|
|
</div>
|
|
<p>The <a href="#element-sequence"><code>xsl:sequence</code></a>
|
|
instruction may be used as a child of <a href=
|
|
"#element-fork"><code>xsl:fork</code></a> to break the instructions
|
|
within <a href="#element-fork"><code>xsl:fork</code></a> into a
|
|
number of separate groups, each of which is considered as (and
|
|
indeed is) a separate instruction operating in a single pass over
|
|
the data.</p>
|
|
<p>The following section describes the <a href=
|
|
"#element-fork"><code>xsl:fork</code></a> instruction more
|
|
formally.</p>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="fork-instruction" id="fork-instruction"></a>16.2
|
|
<a href="#fork-instruction" style="text-decoration: none">The</a>
|
|
<code>xsl:fork</code> <a href="#fork-instruction" style=
|
|
"text-decoration: none">instruction</a></h3>
|
|
<p class="element-syntax"><a name="element-fork" id=
|
|
"element-fork"></a><code><!-- Category: instruction --><br />
|
|
<xsl:fork><br />
|
|
  <!-- Content: (<var>sequence-constructor</var>)
|
|
--><br />
|
|
</xsl:fork></code></p>
|
|
<p>The result of the <a href=
|
|
"#element-fork"><code>xsl:fork</code></a> instruction is the result
|
|
of evaluating its contained <a title="sequence constructor" class=
|
|
"termref" href="#dt-sequence-constructor">sequence
|
|
constructor</a>.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-dependent-instruction" id="dt-dependent-instruction" title=
|
|
"dependent (instruction)"></a>Among the <a title="instruction"
|
|
class="termref" href="#dt-instruction">instructions</a> directly
|
|
contained in a <a title="sequence constructor" class="termref"
|
|
href="#dt-sequence-constructor">sequence constructor</a>, an
|
|
instruction <var>I</var> is defined to be <b>dependent</b> on an
|
|
instruction <var>J</var> if <var>J</var> is a <a title=
|
|
"variable-binding element" class="termref" href=
|
|
"#dt-variable-binding-element">variable binding</a> and
|
|
<var>I</var> contains a reference to that variable, or if there is
|
|
an instruction <var>K</var> such that <var>I</var> depends on
|
|
<var>K</var> and <var>K</var> depends on <var>J</var>.<span class=
|
|
"definition">]</span></p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-independent-instruction" id="dt-independent-instruction" title=
|
|
"independent (instruction)"></a>Two <a title="instruction" class=
|
|
"termref" href="#dt-instruction">instructions</a> with a <a title=
|
|
"sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> are defined to
|
|
be <b>independent</b> if neither <a title="dependent (instruction)"
|
|
class="termref" href="#dt-dependent-instruction">depends</a> on the
|
|
other.<span class="definition">]</span></p>
|
|
<p>By using the <a href="#element-fork"><code>xsl:fork</code></a>
|
|
instruction, the stylesheet author is suggesting to the <a title=
|
|
"processor" class="termref" href="#dt-processor">processor</a> that
|
|
it would be beneficial to evaluate <a title=
|
|
"independent (instruction)" class="termref" href=
|
|
"#dt-independent-instruction">independent instructions</a> during a
|
|
single pass of a streamed input document. The processor is not
|
|
<span class="verb">required</span> to take any notice of this
|
|
suggestion.</p>
|
|
<p>The presence of an <a href=
|
|
"#element-fork"><code>xsl:fork</code></a> instruction affects the
|
|
analysis of streamability, as described in <a href=
|
|
"#streamability"><i>18.4 Streamability Analysis</i></a>.</p>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="splitting-examples" id="splitting-examples"></a>16.3
|
|
<a href="#splitting-examples" style=
|
|
"text-decoration: none">Examples of splitting with streamed
|
|
data</a></h3>
|
|
<p>This section gives examples of how splitting using <a href=
|
|
"#element-fork"><code>xsl:fork</code></a> can be used to enable
|
|
streaming of input documents in cases where several results need to
|
|
be computed during a single pass over the input data.</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e27856" id=
|
|
"d7e27856"></a>Example: Deleting elements, and counting
|
|
deletions</div>
|
|
<p>In this example the input is a narrative document containing
|
|
<code>note</code> elements at any level of nesting. The requirement
|
|
is to output a copy of the input document in which (a) the
|
|
<code>note</code> elements have been removed, and (b) a
|
|
<code>footnote</code> is added at the end indicating how many
|
|
<code>note</code> elements have been deleted.</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:mode on-no-match="copy" streamable="yes"/>
|
|
|
|
<xsl:template match="note"/>
|
|
|
|
<xsl:template match="/*">
|
|
<xsl:fork>
|
|
<xsl:apply-templates/>
|
|
<footnote>
|
|
<p>Removed <xsl:value-of select="count(.//note)"/>
|
|
note elements.</p>
|
|
</footnote>
|
|
</xsl:fork>
|
|
</xsl:template>
|
|
|
|
</pre></div>
|
|
<p>The <a href="#element-fork"><code>xsl:fork</code></a>
|
|
instruction contains two independent instructions in its sequence
|
|
constructor. These can therefore be evaluated in the same pass over
|
|
the input data. The first instruction (the <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>
|
|
instruction) causes everything except the <code>note</code>
|
|
elements to be copied to the result; the second instruction (the
|
|
literal result element <code>footnote</code>) outputs a count of
|
|
the number of descendant <code>note</code> elements.</p>
|
|
<p>Note that although the processing makes a single pass over the
|
|
input stream, there is some buffering of results required, because
|
|
the results of the instructions within the <a href=
|
|
"#element-fork"><code>xsl:fork</code></a> instruction need to be
|
|
concatenated. In this case an intelligent implementation might be
|
|
able to restrict the buffered data to a single integer.</p>
|
|
<p>In a formal sense, however, the result is exactly the same as if
|
|
the <a href="#element-fork"><code>xsl:fork</code></a> element were
|
|
not there.</p>
|
|
</div>
|
|
<p> </p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e27902" id=
|
|
"d7e27902"></a>Example: Statistical analysis of a document</div>
|
|
<p>This example computes the proportion of the words in a document
|
|
that are contained in headings and in footnotes. It does this in a
|
|
single streaming pass of the input document.</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:template match="doc">
|
|
<xsl:fork>
|
|
<xsl:variable name="wordCount"
|
|
select="count(.//text()/tokenize(., '\s+'))"/>
|
|
<xsl:variable name="footnoteWordCount"
|
|
select="count(.//footnote/text()/tokenize(., '\s+'))"/>
|
|
<xsl:variable name="headingWordCount"
|
|
select="count(.//heading/text()/tokenize(., '\s+'))"/>
|
|
<result metric="proportion of words in footnotes"
|
|
value="{$footnoteWordCount div $wordCount}"/>
|
|
<result metric="proportion of words in headings"
|
|
value="{$headingWordCount div $wordCount}"/>
|
|
</xsl:fork>
|
|
</xsl:template>
|
|
</pre></div>
|
|
<p>In this example, there are five instructions within the <a href=
|
|
"#element-fork"><code>xsl:fork</code></a> instruction. The three
|
|
variable bindings are independent of each other, and can therefore
|
|
be evaluated in a single pass through the streamed input document.
|
|
The two literal result elements cannot be evaluated until the
|
|
values of the relevant variables are available; but they do not
|
|
access the source document, and therefore do not place any
|
|
constraints on streamability.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="div1">
|
|
<h2><a name="regular-expressions" id="regular-expressions"></a>17
|
|
<a href="#regular-expressions" style=
|
|
"text-decoration: none">Regular Expressions</a></h2>
|
|
<p>The <a title="core function" class="termref" href=
|
|
"#dt-core-function">core function</a> library for XPath 2.1 defines
|
|
three <span>basic</span> functions that make use of regular
|
|
expressions:</p>
|
|
<ul>
|
|
<li>
|
|
<p><a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-matches"><code>matches</code></a><sup><small>FO</small></sup>
|
|
returns a boolean result that indicates whether or not a string
|
|
matches a given regular expression.</p>
|
|
</li>
|
|
<li>
|
|
<p><a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-replace"><code>replace</code></a><sup><small>FO</small></sup>
|
|
takes a string as input and returns a string obtained by replacing
|
|
all substrings that match a given regular expression with a
|
|
replacement string.</p>
|
|
</li>
|
|
<li>
|
|
<p><a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-tokenize"><code>tokenize</code></a><sup><small>FO</small></sup>
|
|
returns a sequence of strings formed by breaking a supplied input
|
|
string at any separator that matches a given regular
|
|
expression.</p>
|
|
</li>
|
|
</ul>
|
|
<p>These functions are described in <a href=
|
|
"#xpath-functions-11">[Functions and Operators]</a>.</p>
|
|
<p>For more complex string processing than is possible using these
|
|
functions, XSLT provides an instruction <a href=
|
|
"#element-analyze-string"><code>xsl:analyze-string</code></a>,
|
|
which is defined in this section.</p>
|
|
<p>The regular expressions used by this instruction, and the flags
|
|
that control the interpretation of these regular expressions,
|
|
<span class="verb">must</span> conform to the syntax defined in
|
|
<a href="#xpath-functions-11">[Functions and Operators]</a> (see
|
|
<a href=
|
|
"http://www.w3.org/TR/xpath-functions/#regex-syntax">Section 7.6.1
|
|
Regular Expression Syntax</a><sup><small>FO</small></sup>), which
|
|
is itself based on the syntax defined in <a href=
|
|
"#xmlschema-2">[XML Schema Part 2]</a>.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>XPath 2.1 adds a fourth function, <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-analyze-string"><code>
|
|
analyze-string</code></a><sup><small>FO</small></sup>, whose
|
|
functionality is closely modeled on the <a href=
|
|
"#element-analyze-string"><code>xsl:analyze-string</code></a>
|
|
instruction described in this section, repackaging the facilities
|
|
in the form of a function.</p>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="analyze-string" id="analyze-string"></a>17.1 <a href=
|
|
"#analyze-string" style="text-decoration: none">The</a>
|
|
<code>xsl:analyze-string</code> <a href="#analyze-string" style=
|
|
"text-decoration: none">instruction</a></h3>
|
|
<p class="element-syntax"><a name="element-analyze-string" id=
|
|
"element-analyze-string"></a><code><!-- Category: instruction
|
|
--><br />
|
|
<xsl:analyze-string<br />
|
|
  <b>select</b> = <var>expression</var><br />
|
|
  <b>regex</b> = { <var>string</var> }<br />
|
|
  flags? = { <var>string</var> } ><br />
|
|
  <!-- Content: (<a href=
|
|
"#element-matching-substring">xsl:matching-substring</a>?, <a href=
|
|
"#element-non-matching-substring">xsl:non-matching-substring</a>?,
|
|
<a href="#element-fallback">xsl:fallback</a>*) --><br />
|
|
</xsl:analyze-string></code></p>
|
|
<p class="element-syntax"><a name="element-matching-substring" id=
|
|
"element-matching-substring"></a><code><xsl:matching-substring><br />
|
|
|
|
  <!-- Content: <var>sequence-constructor</var>
|
|
--><br />
|
|
</xsl:matching-substring></code></p>
|
|
<p class="element-syntax"><a name="element-non-matching-substring"
|
|
id=
|
|
"element-non-matching-substring"></a><code><xsl:non-matching-substring><br />
|
|
|
|
  <!-- Content: <var>sequence-constructor</var>
|
|
--><br />
|
|
</xsl:non-matching-substring></code></p>
|
|
<p>The <a href=
|
|
"#element-analyze-string"><code>xsl:analyze-string</code></a>
|
|
instruction takes as input a string (the result of evaluating the
|
|
expression in the <code>select</code> attribute) and a regular
|
|
expression (the effective value of the <code>regex</code>
|
|
attribute).</p>
|
|
<p>If the result of evaluating the <code>select</code> expression
|
|
is not a string, it is converted to a string by applying the
|
|
<a title="function conversion rules" class="termref" href=
|
|
"#dt-function-conversion-rules">function conversion rules</a>.</p>
|
|
<p>The <code>flags</code> attribute may be used to control the
|
|
interpretation of the regular expression. If the attribute is
|
|
omitted, the effect is the same as supplying a zero-length string.
|
|
This is interpreted in the same way as the <code>$flags</code>
|
|
attribute of the functions <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-matches"><code>matches</code></a><sup><small>FO</small></sup>,
|
|
<a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-replace"><code>replace</code></a><sup><small>FO</small></sup>,
|
|
and <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-tokenize"><code>tokenize</code></a><sup><small>FO</small></sup>.
|
|
Specifically, if it contains the letter <code>m</code>, the match
|
|
operates in multiline mode. If it contains the letter
|
|
<code>s</code>, it operates in dot-all mode. If it contains the
|
|
letter <code>i</code>, it operates in case-insensitive mode. If it
|
|
contains the letter <code>x</code>, then whitespace within the
|
|
regular expression is ignored. For more detailed specifications of
|
|
these modes, see <a href="#xpath-functions-11">[Functions and
|
|
Operators]</a> (<a href=
|
|
"http://www.w3.org/TR/xpath-functions/#flags">Section 7.6.1.1
|
|
Flags</a><sup><small>FO</small></sup>).</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>Because the <code>regex</code> attribute is an attribute value
|
|
template, curly brackets within the regular expression must be
|
|
doubled. For example, to match a sequence of one to five
|
|
characters, write <code>regex=".{{1,5}}"</code>. For regular
|
|
expressions containing many curly brackets it may be more
|
|
convenient to use a notation such as
|
|
<code>regex="{'[0-9]{1,5}[a-z]{3}[0-9]{1,2}'}"</code>, or to use a
|
|
variable.</p>
|
|
</div>
|
|
<p>The <a href=
|
|
"#element-analyze-string"><code>xsl:analyze-string</code></a>
|
|
instruction may have two child elements: <a href=
|
|
"#element-matching-substring"><code>xsl:matching-substring</code></a>
|
|
and <a href=
|
|
"#element-non-matching-substring"><code>xsl:non-matching-substring</code></a>.
|
|
Both elements are optional, and neither may appear more than once.
|
|
At least one of them must be present. If both are present, the
|
|
<a href=
|
|
"#element-matching-substring"><code>xsl:matching-substring</code></a>
|
|
element must come first.</p>
|
|
<p>The content of the <a href=
|
|
"#element-analyze-string"><code>xsl:analyze-string</code></a>
|
|
instruction must take one of the following forms:</p>
|
|
<ol class="enumar">
|
|
<li>
|
|
<p>A single <a href=
|
|
"#element-matching-substring"><code>xsl:matching-substring</code></a>
|
|
instruction, followed by zero or more <a href=
|
|
"#element-fallback"><code>xsl:fallback</code></a> instructions</p>
|
|
</li>
|
|
<li>
|
|
<p>A single <a href=
|
|
"#element-non-matching-substring"><code>xsl:non-matching-substring</code></a>
|
|
instruction, followed by zero or more <a href=
|
|
"#element-fallback"><code>xsl:fallback</code></a> instructions</p>
|
|
</li>
|
|
<li>
|
|
<p>A single <a href=
|
|
"#element-matching-substring"><code>xsl:matching-substring</code></a>
|
|
instruction, followed by a single <a href=
|
|
"#element-non-matching-substring"><code>xsl:non-matching-substring</code></a>
|
|
instruction, followed by zero or more <a href=
|
|
"#element-fallback"><code>xsl:fallback</code></a> instructions</p>
|
|
</li>
|
|
</ol>
|
|
<p><a name="err-XTSE1130" id="err-XTSE1130"><span class=
|
|
"error">[ERR XTSE1130]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> if the
|
|
<a href=
|
|
"#element-analyze-string"><code>xsl:analyze-string</code></a>
|
|
instruction contains neither an <a href=
|
|
"#element-matching-substring"><code>xsl:matching-substring</code></a>
|
|
nor an <a href=
|
|
"#element-non-matching-substring"><code>xsl:non-matching-substring</code></a>
|
|
element.</p>
|
|
<p>Any <a href="#element-fallback"><code>xsl:fallback</code></a>
|
|
elements among the children of the <a href=
|
|
"#element-analyze-string"><code>xsl:analyze-string</code></a>
|
|
instruction are ignored by an XSLT 2.0 <span>or 2.1</span>
|
|
processor, but allow fallback behavior to be defined when the
|
|
stylesheet is used with an XSLT 1.0 processor operating with
|
|
forwards-compatible behavior.</p>
|
|
<p>This instruction is designed to process all the non-overlapping
|
|
substrings of the input string that match the regular expression
|
|
supplied.</p>
|
|
<p><a name="err-XTDE1140" id="err-XTDE1140"><span class=
|
|
"error">[ERR XTDE1140]</span></a> It is a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> if the
|
|
<a title="effective value" class="termref" href=
|
|
"#dt-effective-value">effective value</a> of the <code>regex</code>
|
|
attribute does not conform to the <span class=
|
|
"verb">required</span> syntax for regular expressions, as specified
|
|
in <a href="#xpath-functions-11">[Functions and Operators]</a>. If
|
|
the regular expression is known statically (for example, if the
|
|
attribute does not contain any <a title="expression" class=
|
|
"termref" href="#dt-expression">expressions</a> enclosed in curly
|
|
brackets) then the processor <span class="verb">may</span> signal
|
|
the error as a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a>.</p>
|
|
<p><a name="err-XTDE1145" id="err-XTDE1145"><span class=
|
|
"error">[ERR XTDE1145]</span></a> It is a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> if the
|
|
<a title="effective value" class="termref" href=
|
|
"#dt-effective-value">effective value</a> of the <code>flags</code>
|
|
attribute has a value other than the values defined in <a href=
|
|
"#xpath-functions-11">[Functions and Operators]</a>. If the value
|
|
of the attribute is known statically (for example, if the attribute
|
|
does not contain any <a title="expression" class="termref" href=
|
|
"#dt-expression">expressions</a> enclosed in curly brackets) then
|
|
the processor <span class="verb">may</span> signal the error as a
|
|
<a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a>.</p>
|
|
<p><a name="err-XTDE1150" id="err-XTDE1150"><span class=
|
|
"error">[ERR XTDE1150]</span></a> It is a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> if the
|
|
<a title="effective value" class="termref" href=
|
|
"#dt-effective-value">effective value</a> of the <code>regex</code>
|
|
attribute is a regular expression that matches a zero-length
|
|
string: or more specifically, if the regular expression
|
|
<code>$r</code> and flags <code>$f</code> are such that
|
|
<code>matches("", $r, $f)</code> returns true. If the regular
|
|
expression is known statically (for example, if the attribute does
|
|
not contain any <a title="expression" class="termref" href=
|
|
"#dt-expression">expressions</a> enclosed in curly brackets) then
|
|
the processor <span class="verb">may</span> signal the error as a
|
|
<a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a>.</p>
|
|
<p>The <a href=
|
|
"#element-analyze-string"><code>xsl:analyze-string</code></a>
|
|
instruction starts at the beginning of the input string and
|
|
attempts to find the first substring that matches the regular
|
|
expression. If there are several matches, the first match is
|
|
defined to be the one whose starting position comes first in the
|
|
string. If several alternatives within the regular expression both
|
|
match at the same position in the input string, then the match that
|
|
is chosen is the first alternative that matches. For example, if
|
|
the input string is <code>The quick brown fox jumps</code> and the
|
|
regular expression is <code>jump|jumps</code>, then the match that
|
|
is chosen is <code>jump</code>.</p>
|
|
<p>Having found the first match, the instruction proceeds to find
|
|
the second and subsequent matches by repeating the search, starting
|
|
at the first character that was not included in the previous
|
|
match.</p>
|
|
<p>The input string is thus partitioned into a sequence of
|
|
substrings, some of which match the regular expression, others
|
|
which do not match it. Each substring will contain at least one
|
|
character. This sequence of substrings is processed using the
|
|
<span>instructions within the contained <a href=
|
|
"#element-matching-substring"><code>xsl:matching-substring</code></a>
|
|
and <a href=
|
|
"#element-non-matching-substring"><code>xsl:non-matching-substring</code></a>
|
|
elements</span>. A matching substring is processed using the
|
|
<a href=
|
|
"#element-matching-substring"><code>xsl:matching-substring</code></a>
|
|
element, a non-matching substring using the <a href=
|
|
"#element-non-matching-substring"><code>xsl:non-matching-substring</code></a>
|
|
element. Each of these elements takes a <a title=
|
|
"sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> as its content.
|
|
If the element is absent, the effect is the same as if it were
|
|
present with empty content. In processing each substring, the
|
|
contents of the substring will be the <a title="context item"
|
|
class="termref" href="#dt-context-item">context item</a> (as a
|
|
value of type <code>xs:string</code>); the position of the
|
|
substring within the sequence of matching and non-matching
|
|
substrings will be the <a title="context position" class="termref"
|
|
href="#dt-context-position">context position</a>; and the number of
|
|
matching and non-matching substrings will be the <a title=
|
|
"context size" class="termref" href="#dt-context-size">context
|
|
size</a>.</p>
|
|
<p>If the input is a zero-length string, the number of substrings
|
|
will be zero, so neither the <a href=
|
|
"#element-matching-substring"><code>xsl:matching-substring</code></a>
|
|
nor <a href=
|
|
"#element-non-matching-substring"><code>xsl:non-matching-substring</code></a>
|
|
elements will be evaluated.</p>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="regex-group" id="regex-group"></a>17.2 <a href=
|
|
"#regex-group" style="text-decoration: none">Captured
|
|
Substrings</a></h3>
|
|
<a name="function-regex-group" id="function-regex-group"></a>
|
|
<div class="proto"><code class=
|
|
"function">regex-group</code>(<code class=
|
|
"arg">$group-number</code><code class=
|
|
"as"> as </code><code class=
|
|
"type">xs:integer</code>)<code class=
|
|
"as"> as </code><code class=
|
|
"return-type">xs:string</code></div>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-current-captured-substrings" id=
|
|
"dt-current-captured-substrings" title=
|
|
"current captured substrings"></a>While the <a href=
|
|
"#element-matching-substring"><code>xsl:matching-substring</code></a>
|
|
instruction is active, a set of <b>current captured substrings</b>
|
|
is available, corresponding to the parenthesized sub-expressions of
|
|
the regular expression.<span class="definition">]</span> These
|
|
captured substrings are accessible using the function <a href=
|
|
"#function-regex-group"><code>regex-group</code></a>. This function
|
|
takes an integer argument to identify the group, and returns a
|
|
string representing the captured substring.</p>
|
|
<p>The <var>N</var>th captured substring (where <var>N</var> >
|
|
0) is the string matched by the subexpression contained by the
|
|
<var>N</var>th left parenthesis in the regex, <span>excluding any
|
|
non-capturing groups, which are written as
|
|
<code>(?:xxx)</code></span>. The zeroeth captured substring is the
|
|
string that matches the entire regex. This means that the value of
|
|
<code>regex-group(0)</code> is initially the same as the value of
|
|
<code>.</code> (dot).</p>
|
|
<p>The function returns the zero-length string if there is no
|
|
captured substring with the relevant number. This can occur for a
|
|
number of reasons:</p>
|
|
<ol class="enumar">
|
|
<li>
|
|
<p>The number is negative.</p>
|
|
</li>
|
|
<li>
|
|
<p>The regular expression does not contain a parenthesized
|
|
sub-expression with the given number.</p>
|
|
</li>
|
|
<li>
|
|
<p>The parenthesized sub-expression exists, and did not match any
|
|
part of the input string.</p>
|
|
</li>
|
|
<li>
|
|
<p>The parenthesized sub-expression exists, and matched a
|
|
zero-length substring of the input string.</p>
|
|
</li>
|
|
</ol>
|
|
<p>The set of captured substrings is a context variable with
|
|
dynamic scope. It is initially an empty sequence. During the
|
|
evaluation of an <a href=
|
|
"#element-matching-substring"><code>xsl:matching-substring</code></a>
|
|
instruction it is set to the sequence of matched substrings for
|
|
that regex match. During the evaluation of an <a href=
|
|
"#element-non-matching-substring"><code>xsl:non-matching-substring</code></a>
|
|
instruction or a <a title="pattern" class="termref" href=
|
|
"#dt-pattern">pattern</a> or a <a title="stylesheet function"
|
|
class="termref" href="#dt-stylesheet-function">stylesheet
|
|
function</a> it is set to an empty sequence. On completion of an
|
|
instruction that changes the value, the variable reverts to its
|
|
previous value.</p>
|
|
<p>The value of the <a title="current captured substrings" class=
|
|
"termref" href="#dt-current-captured-substrings">current captured
|
|
substrings</a> is unaffected through calls of <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>,
|
|
<a href=
|
|
"#element-call-template"><code>xsl:call-template</code></a>,
|
|
<a href="#element-apply-imports"><code>xsl:apply-imports</code></a>
|
|
or <a href="#element-next-match"><code>xsl:next-match</code></a>,
|
|
or by expansion of named <a title="attribute set" class="termref"
|
|
href="#dt-attribute-set">attribute sets</a>.</p>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="regex-examples" id="regex-examples"></a>17.3 <a href=
|
|
"#regex-examples" style="text-decoration: none">Examples of Regular
|
|
Expression Matching</a></h3>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e28410" id=
|
|
"d7e28410"></a>Example: Replacing Characters by Elements</div>
|
|
<p>Problem: replace all newline characters in the
|
|
<code>abstract</code> element by empty <code>br</code>
|
|
elements:</p>
|
|
<p>Solution:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:analyze-string select="abstract" regex="\n">
|
|
<xsl:matching-substring>
|
|
<br/>
|
|
</xsl:matching-substring>
|
|
<xsl:non-matching-substring>
|
|
<xsl:value-of select="."/>
|
|
</xsl:non-matching-substring>
|
|
</xsl:analyze-string>
|
|
</pre></div>
|
|
</div>
|
|
<p> </p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e28425" id=
|
|
"d7e28425"></a>Example: Recognizing non-XML Markup Structure</div>
|
|
<p>Problem: replace all occurrences of <code>[...]</code> in the
|
|
<code>body</code> by <code>cite</code> elements, retaining the
|
|
content between the square brackets as the content of the new
|
|
element.</p>
|
|
<p>Solution:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:analyze-string select="body" regex="\[(.*?)\]">
|
|
<xsl:matching-substring>
|
|
<cite><xsl:value-of select="regex-group(1)"/></cite>
|
|
</xsl:matching-substring>
|
|
<xsl:non-matching-substring>
|
|
<xsl:value-of select="."/>
|
|
</xsl:non-matching-substring>
|
|
</xsl:analyze-string>
|
|
</pre></div>
|
|
<p>Note that this simple approach fails if the <code>body</code>
|
|
element contains markup that needs to be retained. In this case it
|
|
is necessary to apply the regular expression processing to each
|
|
text node individually. If the <code>[...]</code> constructs span
|
|
multiple text nodes (for example, because there are elements within
|
|
the square brackets) then it probably becomes necessary to make two
|
|
or more passes over the data.</p>
|
|
</div>
|
|
<p> </p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e28451" id=
|
|
"d7e28451"></a>Example: Parsing a Date</div>
|
|
<p>Problem: the input string contains a date such as <code>23 March
|
|
2002</code>. Convert it to the form <code>2002-03-23</code>.</p>
|
|
<p>Solution (with no error handling if the input format is
|
|
incorrect):</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:variable name="months"
|
|
select="'January', 'February', 'March', ..."/>
|
|
|
|
<xsl:analyze-string select="normalize-space($input)"
|
|
regex="([0-9]{{1,2}})\s([A-Z][a-z]+)\s([0-9]{{4}})">
|
|
<xsl:matching-substring>
|
|
<xsl:number value="regex-group(3)" format="0001"/>
|
|
<xsl:text>-</xsl:text>
|
|
<xsl:number value="index-of($months, regex-group(2))" format="01"/>
|
|
<xsl:text>-</xsl:text>
|
|
<xsl:number value="regex-group(1)" format="01"/>
|
|
</xsl:matching-substring>
|
|
</xsl:analyze-string>
|
|
</pre></div>
|
|
<p>Note the use of <code>normalize-space</code> to simplify the
|
|
work done by the regular expression, and the use of doubled curly
|
|
brackets because the <code>regex</code> attribute is an attribute
|
|
value template.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="div1">
|
|
<h2><a name="streaming" id="streaming"></a>18 <a href="#streaming"
|
|
style="text-decoration: none">Streaming</a></h2>
|
|
<p>This specification provides a number of facilities designed to
|
|
enable <a title="streaming" class="termref" href=
|
|
"#dt-streaming">streaming</a>: that is, transformation of a source
|
|
document on-the-fly, as it is parsed, without constructing a
|
|
complete tree representation of the document in memory.</p>
|
|
<p>These facilities include:</p>
|
|
<ul>
|
|
<li>
|
|
<p>The <a href="#element-stream"><code>xsl:stream</code></a>
|
|
instruction, which reads an external document (identified by URI)
|
|
and initiates streaming of that document.</p>
|
|
</li>
|
|
<li>
|
|
<p>Streaming templates, which allow rule-based invocation of
|
|
template rules applied to the nodes in a <a title=
|
|
"streamed document" class="termref" href=
|
|
"#dt-streamed-document">streamed document</a>.</p>
|
|
</li>
|
|
</ul>
|
|
<p>These facilities impose constraints on the stylesheet code to
|
|
ensure that a streamable evaluation is possible. Much of this
|
|
section is concerned with the definition of the rules for
|
|
streamability.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-guaranteed-streamable" id="dt-guaranteed-streamable" title=
|
|
"guaranteed-streamable"></a>A <b>guaranteed-streamable</b>
|
|
construct is a <a title="construct" class="termref" href=
|
|
"#dt-construct">construct</a> that follows the rules given in
|
|
<a href="#streamability"><i>18.4 Streamability Analysis</i></a>.
|
|
Every <a title="processor" class="termref" href=
|
|
"#dt-processor">processor</a> that claims conformance as a
|
|
<a title="streaming feature" class="termref" href=
|
|
"#dt-streaming-feature">streaming processor</a> <span class=
|
|
"verb">must</span> be able to process such a construct using
|
|
streaming, that is, by processing the contents of the source
|
|
document on the fly as it is read, without the need to buffer the
|
|
entire document or any entire element in memory. <span class=
|
|
"definition">]</span></p>
|
|
<p>In certain contexts, in particular the <a href=
|
|
"#element-stream"><code>xsl:stream</code></a> instruction and a
|
|
<a title="template rule" class="termref" href=
|
|
"#dt-template-rule">template rule</a> whose <a title="mode" class=
|
|
"termref" href="#dt-mode">mode</a> is declared with
|
|
<code>streamable="yes"</code>, the stylesheet author has the
|
|
opportunity to request that evaluation should using streaming. In
|
|
this case the rules are as follows:</p>
|
|
<p>For a streaming processor:</p>
|
|
<ul>
|
|
<li>
|
|
<p>If the construct conforms to the rules for being <a title=
|
|
"guaranteed-streamable" class="termref" href=
|
|
"#dt-guaranteed-streamable">guaranteed-streamable</a> then it
|
|
<span class="verb">must</span> be processed using streaming.</p>
|
|
</li>
|
|
<li>
|
|
<p>If the construct is not <a title="guaranteed-streamable" class=
|
|
"termref" href=
|
|
"#dt-guaranteed-streamable">guaranteed-streamable</a> then it
|
|
<span class="verb">must</span> still be processed: the
|
|
specification imposes no rules on how it is processed (it might or
|
|
might not use streaming).</p>
|
|
</li>
|
|
<li>
|
|
<p>If the evaluation does not use streaming (which will only happen
|
|
if the construct is not <a title="guaranteed-streamable" class=
|
|
"termref" href=
|
|
"#dt-guaranteed-streamable">guaranteed-streamable</a>) then the
|
|
processor <span class="verb">should</span> signal a warning
|
|
indicating that streaming was not possible; the processor
|
|
<span class="verb">may</span> provide a user option to abandon
|
|
processing in this case.</p>
|
|
</li>
|
|
</ul>
|
|
<p>For a non-streaming processor, the processor <span class=
|
|
"verb">must</span> evaluate the <span>construct</span> delivering
|
|
the same results as if execution used streaming, but with no
|
|
constraints on the evaluation strategy. (Processing <span class=
|
|
"verb">may</span>, of course, fail due to insufficient memory being
|
|
available, or for other reasons.)</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>This specification does not attempt to legislate precisely what
|
|
constitutes evaluation "using streaming". The most important test
|
|
is that the amount of memory needed should be for practical
|
|
purposes independent of the size of the source document, and in
|
|
particular that the finite size of memory available should not
|
|
impose a limit on the size of source document that can be
|
|
processed.</p>
|
|
<p>The rules are designed to ensure that streaming processors can
|
|
analyze streamability using rules different from those in this
|
|
specification, provided that all constructs that are <a title=
|
|
"guaranteed-streamable" class="termref" href=
|
|
"#dt-guaranteed-streamable">guaranteed-streamable</a> according to
|
|
this specification are actually streamable by the implementation.
|
|
Furthermore, non-streaming processors are not required to analyze
|
|
streamability at all.</p>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="stream-instruction" id="stream-instruction"></a>18.1
|
|
<a href="#stream-instruction" style="text-decoration: none">The</a>
|
|
<code>xsl:stream</code> <a href="#stream-instruction" style=
|
|
"text-decoration: none">instruction</a></h3>
|
|
<p class="element-syntax"><a name="element-stream" id=
|
|
"element-stream"></a><code><!-- Category: instruction
|
|
--><br />
|
|
<xsl:stream<br />
|
|
  <b>href</b> = { <var>uri-reference</var>
|
|
} ><br />
|
|
  <!-- Content: <var>sequence-constructor</var>
|
|
--><br />
|
|
</xsl:stream></code></p>
|
|
<p>The <a href="#element-stream"><code>xsl:stream</code></a>
|
|
instruction reads a source document whose URI is supplied, and
|
|
processes the content of the document using streaming by evaluating
|
|
the contained <a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a>.</p>
|
|
<p>For example, if a document represents a book holding a sequence
|
|
of chapters, then the following code can be used to split the book
|
|
into multiple XML files, one per chapter, without allocating memory
|
|
to hold the entire book in memory at one time:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:stream href="book.xml">
|
|
<xsl:for-each select="book/chapter">
|
|
<xsl:result-document href="chapter{position()}.xml">
|
|
<xsl:copy-of select="."/>
|
|
</xsl:result-document>
|
|
</xsl:for-each>
|
|
</xsl:stream>
|
|
</pre></div>
|
|
<p>The document to be read is determined by the <a title=
|
|
"effective value" class="termref" href=
|
|
"#dt-effective-value">effective value</a> of the <code>href</code>
|
|
attribute (which is defined as an <a title=
|
|
"attribute value template" class="termref" href=
|
|
"#dt-attribute-value-template">attribute value template</a>).
|
|
<span>This <span class="verb">must</span> be a valid URI reference.
|
|
If it is an absolute URI reference, it is used as is; if it is a
|
|
relative URI reference, it is made absolute by resolving it against
|
|
the base URI of the <a href=
|
|
"#element-stream"><code>xsl:stream</code></a> element</span>. The
|
|
process of obtaining a document node given a URI is the same as for
|
|
the <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-doc"><code>doc</code></a><sup><small>FO</small></sup>
|
|
function. However, unlike the <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-doc"><code>doc</code></a><sup><small>FO</small></sup>
|
|
function, the <a href="#element-stream"><code>xsl:stream</code></a>
|
|
instruction offers no guarantee that the resulting document will be
|
|
stable (that is, that multiple calls specifying the same URI will
|
|
return the same document).</p>
|
|
<p>Specifically, if the <a href=
|
|
"#element-stream"><code>xsl:stream</code></a> instruction is
|
|
evaluated several times (or if different <a href=
|
|
"#element-stream"><code>xsl:stream</code></a> instructions are
|
|
evaluated) with the same URI (<span>after making it
|
|
absolute</span>) as the value of the <code>href</code> attribute,
|
|
it is <a title="implementation-dependent" class="termref" href=
|
|
"#dt-implementation-dependent">implementation-dependent</a> whether
|
|
the same nodes or different nodes are returned on each occasion; it
|
|
is also possible that the actual document content will be
|
|
different.</p>
|
|
<p>The result of the <a href=
|
|
"#element-stream"><code>xsl:stream</code></a> instruction is the
|
|
same as the result of the following (non-streaming) process:</p>
|
|
<ol class="enumar">
|
|
<li>
|
|
<p>The source document is read from the supplied URI and parsed to
|
|
form an instance of the XDM data model. This is the <a title=
|
|
"streamed document" class="termref" href=
|
|
"#dt-streamed-document">streamed document</a>.</p>
|
|
</li>
|
|
<li>
|
|
<p>The contained sequence constructor is evaluated with the
|
|
<span>document</span> node of the <a title="streamed document"
|
|
class="termref" href="#dt-streamed-document">streamed document</a>
|
|
as the context item, and with the context position and context size
|
|
set to one, and the resulting sequence is returned as the result of
|
|
the <a href="#element-stream"><code>xsl:stream</code></a>
|
|
instruction.</p>
|
|
</li>
|
|
</ol>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>The rules for streamability ensure that the sequence constructor
|
|
(and therefore the <a href=
|
|
"#element-stream"><code>xsl:stream</code></a> instruction) cannot
|
|
return any nodes from the <a title="streamed document" class=
|
|
"termref" href="#dt-streamed-document">streamed document</a>. For
|
|
example, it cannot contain the instruction <code><xsl:sequence
|
|
select="//chapter"/></code>. If nodes from this document are to
|
|
be returned, they must first be copied, for example by <span>using
|
|
the <a href="#element-copy-of"><code>xsl:copy-of</code></a>
|
|
instruction or by</span> calling the <a href=
|
|
"#function-copy-of"><code>copy-of</code></a> or <a href=
|
|
"#function-snapshot"><code>snapshot</code></a> functions.</p>
|
|
<p>Because the <a href=
|
|
"#element-stream"><code>xsl:stream</code></a> instruction cannot
|
|
return nodes from the streamed document, any nodes it does return
|
|
will be conventional (unstreamed) nodes that can be processed
|
|
without restriction. For example, if <a href=
|
|
"#element-stream"><code>xsl:stream</code></a> is invoked within a
|
|
<a title="stylesheet function" class="termref" href=
|
|
"#dt-stylesheet-function">stylesheet function</a>
|
|
<code>f:firstChapter</code>, and the sequence constructor consists
|
|
of the instruction <code><xsl:copy-of
|
|
select="//chapter"/></code>, then the calling code can
|
|
manipulate the resulting <code>chapter</code> elements as ordinary
|
|
trees rooted at parentless element nodes.</p>
|
|
</div>
|
|
<div class="div3">
|
|
<h4><a name="stream-examples" id="stream-examples"></a>18.1.1
|
|
<a href="#stream-examples" style="text-decoration: none">Examples
|
|
of</a> <code>xsl:stream</code> <a href="#stream-examples" style=
|
|
"text-decoration: none"></a></h4>
|
|
<p>The <a href="#element-stream"><code>xsl:stream</code></a>
|
|
instruction can be used to initiate processing of a document using
|
|
streaming with a variety of coding styles, illustrated in the
|
|
examples below.</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e28739" id=
|
|
"d7e28739"></a>Example: Using <a href=
|
|
"#element-stream"><code>xsl:stream</code></a> with aggregate
|
|
functions</div>
|
|
<p>The following example computes the number of transactions in a
|
|
transaction file</p>
|
|
<p>Input:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<transactions>
|
|
<transaction value="12.51"/>
|
|
<transaction value="3.99"/>
|
|
</transactions>
|
|
</pre></div>
|
|
<p>Stylesheet code:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:stream href="transactions.xml">
|
|
<count>
|
|
<xsl:value-of select="count(transactions/transaction)"/>
|
|
</count>
|
|
</xsl:stream>
|
|
</pre></div>
|
|
<p>Result:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<count>2</count>
|
|
</pre></div>
|
|
<p>The following example computes the highest-value transaction in
|
|
the same input file:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:stream href="transactions.xml">
|
|
<maxValue>
|
|
<xsl:value-of select="max(transactions/transaction/@value)"/>
|
|
</maxValue>
|
|
</xsl:stream>
|
|
</pre></div>
|
|
<p>Result:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<maxValue>12.51</maxValue>
|
|
</pre></div>
|
|
<p>To compute both the count and the maximum value in a single pass
|
|
over the input, it is necessary to use <a href=
|
|
"#element-fork"><code>xsl:fork</code></a>:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:stream href="transactions.xml">
|
|
<xsl:fork>
|
|
<count>
|
|
<xsl:value-of select="count(transactions/transaction)"/>
|
|
</count>
|
|
<maxValue>
|
|
<xsl:value-of select="max(transactions/transaction/@value)"/>
|
|
</maxValue>
|
|
</xsl:fork>
|
|
</xsl:stream>
|
|
</pre></div>
|
|
</div>
|
|
<p> </p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e28775" id=
|
|
"d7e28775"></a>Example: Using <a href=
|
|
"#element-stream"><code>xsl:stream</code></a> with <a href=
|
|
"#element-for-each"><code>xsl:for-each</code></a> to process a
|
|
collection of input documents</div>
|
|
<p>This example displays a list of the chapter titles extracted
|
|
from each book in a collection of books.</p>
|
|
<p>Each input document is assumed to have a structure such as:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<book>
|
|
<chapter number-of-pages="18">
|
|
<title>The first chapter of book A</title>
|
|
...
|
|
</chapter>
|
|
<chapter number-of-pages="15">
|
|
<title>The second chapter of book A</title>
|
|
...
|
|
</chapter>
|
|
<chapter number-of-pages="12">
|
|
<title>The third chapter of book A</title>
|
|
...
|
|
</chapter>
|
|
</book>
|
|
</pre></div>
|
|
<p>Stylesheet code:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<chapter-titles>
|
|
<xsl:for-each select="uri-collection('books')">
|
|
<xsl:stream href="{.}">
|
|
<xsl:for-each select="book/chapter">
|
|
<title><xsl:value-of select="title"/></title>
|
|
</xsl:for-each>
|
|
</xsl:stream>
|
|
</xsl:for-each>
|
|
</chapter-titles>
|
|
</pre></div>
|
|
<p>Output:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<chapter-titles>
|
|
<title>The first chapter of book A</title>
|
|
<title>The second chapter of book A</title>
|
|
...
|
|
<title>The first chapter of book B</title>
|
|
...
|
|
</chapter-titles>
|
|
</pre></div>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>This example uses the function <a href=
|
|
"#function-uri-collection"><code>uri-collection</code></a> to
|
|
obtain the document URIs of all the documents in a collection, so
|
|
that each one can be processed in turn using <a href=
|
|
"#element-stream"><code>xsl:stream</code></a>.</p>
|
|
</div>
|
|
</div>
|
|
<p> </p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e28807" id=
|
|
"d7e28807"></a>Example: Using <a href=
|
|
"#element-stream"><code>xsl:stream</code></a> with <a href=
|
|
"#element-iterate"><code>xsl:iterate</code></a></div>
|
|
<p>This example assumes that the input is a book with multiple
|
|
chapters, as shown in the previous example, with the page count for
|
|
each chapter given as an attribute of the chapter. The
|
|
transformation determines the starting page number for each chapter
|
|
by accumulating the page counts for previous chapters, and rounding
|
|
up to an odd number if necessary.</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<chapter-start-page>
|
|
<xsl:stream href="book.xml">
|
|
<xsl:iterate select="book/chapter">
|
|
<xsl:param name="start-page" select="1"/>
|
|
<chapter title="{title}" start-page="{$start-page}"/>
|
|
<xsl:next-iteration>
|
|
<xsl:with-param name="start-page"
|
|
select="$start-page + @number-of-pages +
|
|
(@number-of-pages mod 2)"/>
|
|
</xsl:next-iteration>
|
|
</xsl:iterate>
|
|
</xsl:stream>
|
|
</chapter-start-page>
|
|
</pre></div>
|
|
<p>Output:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<chapter-start-page>
|
|
<chapter title="The first chapter of book A" start-page="1"/>
|
|
<chapter title="The second chapter of book A" start-page="19"/>
|
|
<chapter title="The third chapter of book A" start-page="35"/>
|
|
...
|
|
</chapter-start-page>
|
|
|
|
</pre></div>
|
|
</div>
|
|
<p> </p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e28824" id=
|
|
"d7e28824"></a>Example: Using <a href=
|
|
"#element-stream"><code>xsl:stream</code></a> with <a href=
|
|
"#element-for-each-group"><code>xsl:for-each-group</code></a></div>
|
|
<p>This example assumes that the input is a book with multiple
|
|
chapters, and that each chapter belongs to a part, which is present
|
|
as an attribute of the chapter (for example, chapters 1-4 might
|
|
constitute Part 1, the next three chapters forming Part 2, and so
|
|
on):</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<book>
|
|
<chapter part="1">
|
|
<title>The first chapter of book A</title>
|
|
...
|
|
</chapter>
|
|
<chapter part="1">
|
|
<title>The second chapter of book A</title>
|
|
...
|
|
</chapter>
|
|
...
|
|
<chapter part="2">
|
|
<title>The fifth chapter of book A</title>
|
|
...
|
|
</chapter>
|
|
</book>
|
|
</pre></div>
|
|
<p>The transformation copies the full text of the chapters,
|
|
creating an extra level of hierarchy for the parts.</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<book>
|
|
<xsl:stream href="book.xml">
|
|
<xsl:for-each-group select="book/chapter" group-adjacent="@part">
|
|
<part number="{current-grouping-key()}">
|
|
<xsl:copy-of select="current-group()"/>
|
|
</part>
|
|
</xsl:for-each-group>
|
|
</xsl:stream>
|
|
</book>
|
|
</pre></div>
|
|
<p>Output:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<book>
|
|
<part number="1">
|
|
<chapter title="The first chapter of book A" part="1">
|
|
...
|
|
</chapter>
|
|
<chapter title="The second chapter of book A" part="1">
|
|
...
|
|
</chapter>
|
|
...
|
|
</part>
|
|
<part number="2">
|
|
<chapter title="The fifth chapter of book A" part="2">
|
|
...
|
|
</chapter>
|
|
...
|
|
</part>
|
|
</book>
|
|
|
|
</pre></div>
|
|
</div>
|
|
<p> </p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e28845" id=
|
|
"d7e28845"></a>Example: Using <a href=
|
|
"#element-stream"><code>xsl:stream</code></a> with <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a></div>
|
|
<p>This example copies an XML document while deleting all the
|
|
<code>ednote</code> elements at any level of the tree, together
|
|
with their descendants. This example is a complete stylesheet,
|
|
which is intended to be evaluated by nominating <code>main</code>
|
|
as the <a title="initial template" class="termref" href=
|
|
"#dt-initial-template">initial template</a>. The use of
|
|
<code>on-no-match="copy"</code> in the <a href=
|
|
"#element-mode"><code>xsl:mode</code></a> declaration means that
|
|
the built-in template rule copies nodes unchanged, except where
|
|
overridden by a user-defined template rule.</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:transform version="2.1" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
|
|
|
|
<xsl:mode name="delete-ednotes" streaming="yes" on-no-match="copy"/>
|
|
|
|
<xsl:template name="main">
|
|
<xsl:stream href="book.xml">
|
|
<xsl:apply-templates mode="delete-ednotes"/>
|
|
</xsl:stream>
|
|
</xsl:template>
|
|
|
|
<xsl:template match="ednote" mode="delete-ednotes"/>
|
|
|
|
</xsl:transform>
|
|
</pre></div>
|
|
<p>Additional template rules could be added to process other
|
|
elements and attributes in the same pass through the data: for
|
|
example, to modify the value of a <code>last-updated</code>
|
|
attribute (wherever it appears) to the current date and time, the
|
|
following rule suffices:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:template match="@last-updated">
|
|
<xsl:attribute name="last-updated" select="current-dateTime()"/>
|
|
</xsl:template>
|
|
</pre></div>
|
|
</div>
|
|
<p> </p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e28880" id=
|
|
"d7e28880"></a>Example: Using <a href=
|
|
"#element-stream"><code>xsl:stream</code></a> with <a href=
|
|
"#element-merge"><code>xsl:merge</code></a></div>
|
|
<p>This example builds a file representing the index of a book from
|
|
files containing the index for each chapter. The chapter-level
|
|
index files contain entries of the form <code><entry term="XML"
|
|
page="27"/></code> sorted first alphabetically by term and then
|
|
numerically by page number; the sort order for the combined index
|
|
is the same.</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<index>
|
|
<xsl:merge>
|
|
<xsl:merge-source select="uri-collection('chapter-indexes')">
|
|
<xsl:merge-input>
|
|
<xsl:stream href="{.}">
|
|
<xsl:copy-of select="index/entry"/>
|
|
</xsl:stream>
|
|
<xsl:merge-key select="string(@term)"/>
|
|
<xsl:merge-key select="xs:integer(@page)"/>
|
|
</xsl:merge-input>
|
|
</xsl:merge-source>
|
|
<xsl:merge-action>
|
|
<xsl:copy-of select="current-group()[1]"/>
|
|
</xsl:merge-action>
|
|
</xsl:merge>
|
|
</index>
|
|
</pre></div>
|
|
<p>In cases where two chapter indexes contain entries for the same
|
|
term, they will normally have different page numbers, and will
|
|
therefore go in separate groups. Their order in the output is based
|
|
on the ordering of the merge keys, which means entries with the
|
|
same term appear in page number order. In the unlikely case that
|
|
two files contain entries where both the term and the page number
|
|
are the same (or, perhaps more plausibly, where such duplicates
|
|
occur within a single input file), the <a href=
|
|
"#element-merge-action"><code>xsl:merge-action</code></a> ensures
|
|
that only the first of the duplicates will be copied.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="streamable-templates" id=
|
|
"streamable-templates"></a>18.2 <a href="#streamable-templates"
|
|
style="text-decoration: none">Streamable Templates</a></h3>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-streamable-template" id="dt-streamable-template" title=
|
|
"streamable template"></a>If any of the <a title="mode" class=
|
|
"termref" href="#dt-mode">modes</a> to which a <a title=
|
|
"template rule" class="termref" href="#dt-template-rule">template
|
|
rule</a> is applicable is a <a title="streamable mode" class=
|
|
"termref" href="#dt-streamable-mode">streamable mode</a>, then the
|
|
template rule <span class="verb">must</span> satisfy certain rules
|
|
to ensure that it can be evaluated using streaming. A template that
|
|
satisfies these rules is referred to as a <b>streamable
|
|
template</b>.<span class="definition">]</span> Specifically:</p>
|
|
<ul>
|
|
<li>
|
|
<p>The <a title="pattern" class="termref" href=
|
|
"#dt-pattern">pattern</a> defined in the <code>match</code>
|
|
attribute of the <a href=
|
|
"#element-template"><code>xsl:template</code></a> element must be a
|
|
<a title="streamable pattern" class="termref" href=
|
|
"#dt-streamable-pattern">streamable pattern</a> as defined in
|
|
<a href="#streamable-patterns"><i>18.3 Streamable
|
|
patterns</i></a>.</p>
|
|
</li>
|
|
<li>
|
|
<p>The <a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> contained in
|
|
the body of the <a href=
|
|
"#element-template"><code>xsl:template</code></a> element
|
|
<span class="verb">must</span> be a <a title=
|
|
"guaranteed-streamable" class="termref" href=
|
|
"#dt-guaranteed-streamable">guaranteed streamable</a> sequence
|
|
constructor, as defined in <a href="#streamability"><i>18.4
|
|
Streamability Analysis</i></a>.</p>
|
|
</li>
|
|
</ul>
|
|
<blockquote>
|
|
<p><b><a name="issue-streamable-template-terminology" id=
|
|
"issue-streamable-template-terminology">Issue 19
|
|
(streamable-template-terminology)</a>:</b></p>
|
|
<p>It might be more consistent to use "guaranteed-streamable
|
|
template" rather than "streamable template".</p>
|
|
</blockquote>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="streamable-patterns" id="streamable-patterns"></a>18.3
|
|
<a href="#streamable-patterns" style=
|
|
"text-decoration: none">Streamable patterns</a></h3>
|
|
<p><a title="pattern" class="termref" href=
|
|
"#dt-pattern">Patterns</a> appear in XSLT in a number of contexts:
|
|
most notably as match patterns in <a title="template rule" class=
|
|
"termref" href="#dt-template-rule">template rules</a>, but also in
|
|
<a title="key" class="termref" href="#dt-key">key</a> definitions
|
|
and in attributes of the <a href=
|
|
"#element-number"><code>xsl:number</code></a> and <a href=
|
|
"#element-for-each-group"><code>xsl:for-each-group</code></a>
|
|
instructions.</p>
|
|
<p>In general, it is difficult to predict how often a pattern will
|
|
be evaluated, or which nodes it will be evaluated against. The
|
|
rules for matching nodes against a pattern are therefore designed
|
|
to make it possible to test the pattern against a node in a
|
|
streamed input document without changing the current position of
|
|
the stream. In particular, if the node is an element, the rules
|
|
make it possible to test whether the node matches the pattern while
|
|
the stream is positioned at the element's start tag.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-streamable-pattern" id="dt-streamable-pattern" title=
|
|
"streamable pattern"></a>A <a title="pattern" class="termref" href=
|
|
"#dt-pattern">pattern</a> is a <b>streamable pattern</b> if it can
|
|
be tested against a node in a <a title="streamed document" class=
|
|
"termref" href="#dt-streamed-document">streamed document</a>
|
|
without access to the descendants of the node.<span class=
|
|
"definition">]</span> Specifically, a pattern is streamable if it
|
|
satisfies all the following conditions:</p>
|
|
<ol class="enumar">
|
|
<li>
|
|
<p>It <span class="verb">must not</span> contain any of the
|
|
constructs <a href="#NT-VarRefRoot">VarRefRoot</a>, <a href=
|
|
"#NT-IdCall">IdCall</a>, <a href=
|
|
"#NT-ElementWithIdCall">ElementWithIdCall</a>, or <a href=
|
|
"#NT-KeyCall">KeyCall</a></p>
|
|
<blockquote>
|
|
<p><b><a name="issue-prohibit-doc-in-patterns" id=
|
|
"issue-prohibit-doc-in-patterns">Issue 20
|
|
(prohibit-doc-in-patterns)</a>:</b></p>
|
|
<p>Given that <a href="#element-stream"><code>xsl:stream</code></a>
|
|
might not yield stable results, it might make sense to prohibit
|
|
<code>DocCall</code> here as well - it's highly implementation
|
|
dependent whether the same node from the streamed document would
|
|
occur in the document returned by the <code>doc</code> function
|
|
call.</p>
|
|
</blockquote>
|
|
</li>
|
|
<li>
|
|
<p>In any <a href="#NT-PatternStep">PatternStep</a> within the
|
|
pattern, the <a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-PredicateList">PredicateList</a><sup><small>XP21</small></sup>
|
|
<span class="verb">must</span> contain at most one <a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-Predicate">Predicate</a><sup><small>XP21</small></sup>.</p>
|
|
</li>
|
|
<li>
|
|
<p>In any <a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-Predicate">Predicate</a><sup><small>XP21</small></sup>
|
|
within the pattern, the expression within the predicate
|
|
<span class="verb">must</span> be <a title="motionless" class=
|
|
"termref" href="#dt-motionless">motionless</a> with respect to its
|
|
context item, as defined in <a href=
|
|
"#streamability-conditions"><i>18.4.5 Streamability
|
|
Conditions</i></a>.</p>
|
|
</li>
|
|
</ol>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>Informally, the expression in a predicate is <a title=
|
|
"motionless" class="termref" href="#dt-motionless">motionless</a>
|
|
if it can be evaluated without reading the children or descendants
|
|
of the context node. The term "motionless" is chosen to convey the
|
|
idea that the pattern can be evaluated without repositioning the
|
|
input stream.</p>
|
|
<p>The effect of these rules is that it is always possible to
|
|
determine whether an element matches the pattern while processing
|
|
the start tag of the element, and without advancing the stream
|
|
beyond the start tag of the element.</p>
|
|
<p>The use of <a href="#NT-VarRefRoot">VarRefRoot</a> is prohibited
|
|
because the test would never be satisfied: a variable reference
|
|
outside a predicate would necessarily be a reference to a global
|
|
variable, and no global variable can ever be bound to a node in a
|
|
streamed input document.</p>
|
|
<p>The use of <a href="#NT-IdCall">IdCall</a> and <a href=
|
|
"#NT-ElementWithIdCall">ElementWithIdCall</a> is prohibited because
|
|
(in the case of an ID-valued element, as distinct from an ID-valued
|
|
attribute) the ID value is not known until the element content has
|
|
been read.</p>
|
|
<p>The use of <a href="#NT-KeyCall">KeyCall</a> is prohibited
|
|
because keys, in general, cannot be evaluated without access to the
|
|
content of an element, and the use case is not important enough to
|
|
justify isolating those cases where streaming evaluation would
|
|
actually be feasible.</p>
|
|
<p>The reason for the restriction to a single predicate is to
|
|
disallow pattern steps such as <code>match="p[@a=2 and
|
|
@b=3][5]"</code>, where the first predicate applies some complex
|
|
boolean filter, and the second is positional. This would
|
|
potentially require maintaining a complex set of counting
|
|
variables. In principle one could allow multiple predicates
|
|
provided that only the first one depends on the context position;
|
|
but it is not always possible to identify positional predicates by
|
|
static analysis, and in any case such analysis is outside the scope
|
|
of this specification. Patterns such as <code>match="p[1]"</code>
|
|
are permitted, however: to evaluate such a pattern, a streaming
|
|
processor must typically maintain a count of how many nodes of each
|
|
unique combination of (node-kind, node-name, type-annotation) have
|
|
been encountered at each level of the XML hierarchy.</p>
|
|
<p>The analysis depends on the fact that in both XML Schema 1.0 and
|
|
XML Schema 1.1, the type of an element is known as soon as its
|
|
start tag has been processed, before examining its content. This
|
|
principle has been preserved in the design of new features such
|
|
<em>conditional type assignment</em> in XML Schema 1.1. Clearly the
|
|
validity of the element against this type is not established until
|
|
the content has been read; but if the element is found to be
|
|
invalid, the XSLT processing will always fail, so assuming the type
|
|
makes no difference to the outcome.</p>
|
|
</div>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="streamability" id="streamability"></a>18.4 <a href=
|
|
"#streamability" style="text-decoration: none">Streamability
|
|
Analysis</a></h3>
|
|
<p>The rules for streamable templates, and also the rules for the
|
|
<a href="#element-stream"><code>xsl:stream</code></a> instruction,
|
|
require that the contained <a title="sequence constructor" class=
|
|
"termref" href="#dt-sequence-constructor">sequence constructor</a>
|
|
<span class="verb">must</span> be <a title="guaranteed-streamable"
|
|
class="termref" href=
|
|
"#dt-guaranteed-streamable">guaranteed-streamable</a>. For
|
|
generality, we define streamability as a property of any <a title=
|
|
"construct" class="termref" href="#dt-construct">construct</a>, of
|
|
which a sequence constructor is but one kind. The term <a title=
|
|
"construct" class="termref" href="#dt-construct">construct</a> is
|
|
defined in <a href="#building-expression-tree"><i>18.4.1 Building
|
|
an Expression Tree</i></a>.</p>
|
|
<p>The assessment of a <a title="construct" class="termref" href=
|
|
"#dt-construct">construct</a> to determine whether it is a
|
|
<a title="guaranteed-streamable" class="termref" href=
|
|
"#dt-guaranteed-streamable">guaranteed-streamable</a> construct is
|
|
done as described in the following rules:</p>
|
|
<ol class="enumar">
|
|
<li>
|
|
<p>Optionally, the construct <span class="verb">may</span> be
|
|
rewritten by the <a title="processor" class="termref" href=
|
|
"#dt-processor">processor</a> in an <a title=
|
|
"implementation-dependent" class="termref" href=
|
|
"#dt-implementation-dependent">implementation-dependent</a> way,
|
|
replacing it by an optimized equivalent. This optimization
|
|
<span class="verb">may</span> cause a construct that would
|
|
otherwise be non-streamable to become streamable, but it
|
|
<span class="verb">must not</span> cause a streamable construct to
|
|
become non-streamable (for example, the inverse of either of the
|
|
above).</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>For example, the expression <code>A[B or C]</code> might be
|
|
rewritten as <code>A[*[self::B or self::C]]</code>: the expression
|
|
as written is not streamable because it makes two downward
|
|
selections, but the rewritten expression is streamable because it
|
|
only has one. Similarly, the expression <code>//A/B</code> might be
|
|
rewritten as <code>//B[parent::A]</code></p>
|
|
</div>
|
|
</li>
|
|
<li>
|
|
<p>An expression tree is constructed representing the structure of
|
|
the <a title="construct" class="termref" href=
|
|
"#dt-construct">construct</a>, in terms of its contained
|
|
instructions, XPath expressions, and other constructs.</p>
|
|
</li>
|
|
<li>
|
|
<p>The expression tree is expanded to make all navigation within
|
|
the <span><a title="streamed document" class="termref" href=
|
|
"#dt-streamed-document">streamed document</a></span> explicit; for
|
|
example, a construct that atomizes a node is expanded to include a
|
|
path expression that makes access to all the text node descendants
|
|
of that node.</p>
|
|
</li>
|
|
<li>
|
|
<p>A path map is constructed defining the navigation routes
|
|
followed by the <span><a title="construct" class="termref" href=
|
|
"#dt-construct">construct</a></span>, starting at the context
|
|
node.</p>
|
|
</li>
|
|
<li>
|
|
<p>This path map is examined to determine whether it contains any
|
|
paths, or combinations of paths, that are inconsistent with
|
|
streaming.</p>
|
|
</li>
|
|
</ol>
|
|
<p>These steps are explained in more detail in the following
|
|
subsections. The section ends with some worked examples: see
|
|
<a href="#streamability-examples"><i>18.4.7 Examples of
|
|
streamability analysis</i></a>.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>Streamability analysis is done on the stylesheet as it exists
|
|
after processing of <code>[xsl:]use-when</code> attributes as
|
|
described in <a href="#conditional-inclusion"><i>3.12 Conditional
|
|
Element Inclusion</i></a>. An expression that appears in an
|
|
<code>[xsl:]use-when</code> attribute itself cannot access any
|
|
source document, and therefore cannot affect streamability.</p>
|
|
</div>
|
|
<div class="div3">
|
|
<h4><a name="building-expression-tree" id=
|
|
"building-expression-tree"></a>18.4.1 <a href=
|
|
"#building-expression-tree" style="text-decoration: none">Building
|
|
an Expression Tree</a></h4>
|
|
<p>The first stage in analyzing a <a title="construct" class=
|
|
"termref" href="#dt-construct">construct</a> (typically the content
|
|
of an <a href="#element-stream"><code>xsl:stream</code></a>
|
|
instruction or a <a title="template rule" class="termref" href=
|
|
"#dt-template-rule">template rule</a>) to determine whether it is
|
|
streamable is to create a representation of the construct in the
|
|
form of an expression tree. The expression tree represents the
|
|
syntactic structure of the construct.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-e-node" id="dt-e-node" title="e-node"></a>To distinguish nodes
|
|
in an expression tree from other kinds of node in other kinds of
|
|
tree, we refer to them as <b>e-nodes</b>.<span class=
|
|
"definition">]</span></p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-construct" id="dt-construct" title="construct"></a>An <a title=
|
|
"e-node" class="termref" href="#dt-e-node">e-node</a> (a node in
|
|
the expression tree) represents a <b>construct</b>. A
|
|
<b>construct</b> is a <span>fragment of</span> a stylesheet that
|
|
can be evaluated <span>or invoked</span> to produce a
|
|
value.<span class="definition">]</span>. Specifically, it is one of
|
|
the following:</p>
|
|
<ul>
|
|
<li>
|
|
<p>an <a title="instruction" class="termref" href=
|
|
"#dt-instruction">instruction</a></p>
|
|
</li>
|
|
<li>
|
|
<p>an <a title="expression" class="termref" href=
|
|
"#dt-expression">expression</a></p>
|
|
</li>
|
|
<li>
|
|
<p>a <a title="pattern" class="termref" href=
|
|
"#dt-pattern">pattern</a></p>
|
|
</li>
|
|
<li>
|
|
<p>a <a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a></p>
|
|
</li>
|
|
<li>
|
|
<p>an <a title="attribute value template" class="termref" href=
|
|
"#dt-attribute-value-template">attribute value template</a></p>
|
|
</li>
|
|
<li>
|
|
<p>a <a title="stylesheet function" class="termref" href=
|
|
"#dt-stylesheet-function">stylesheet function</a></p>
|
|
</li>
|
|
<li>
|
|
<p>a <a title="template" class="termref" href=
|
|
"#dt-template">template</a></p>
|
|
</li>
|
|
<li>
|
|
<p>an <a title="attribute set" class="termref" href=
|
|
"#dt-attribute-set">attribute set</a></p>
|
|
</li>
|
|
<li>
|
|
<p>an <code>[xsl:]use-attribute-sets</code> attribute</p>
|
|
</li>
|
|
<li>
|
|
<p>an <a href="#element-when"><code>xsl:when</code></a>, <a href=
|
|
"#element-otherwise"><code>xsl:otherwise</code></a>, <a href=
|
|
"#element-matching-substring"><code>xsl:matching-substring</code></a>,
|
|
<a href=
|
|
"#element-non-matching-substring"><code>xsl:non-matching-substring</code></a>,
|
|
<a href="#element-with-param"><code>xsl:with-param</code></a>,
|
|
<a href="#element-catch"><code>xsl:catch</code></a> or <a href=
|
|
"#element-on-completion"><code>xsl:on-completion</code></a> element
|
|
(these elements have a structural role within an <a title=
|
|
"instruction" class="termref" href=
|
|
"#dt-instruction">instruction</a>, but they are not themselves
|
|
instructions)</p>
|
|
</li>
|
|
</ul>
|
|
<p>Some <span><a title="construct" class="termref" href=
|
|
"#dt-construct">constructs</a></span> perform navigation that
|
|
cannot be statically analyzed and that can potentially visit all
|
|
parts of the tree containing the context node. An example is an
|
|
<a href="#element-evaluate"><code>xsl:evaluate</code></a>
|
|
instruction. This is fatal to streaming only if the context node is
|
|
a node in the streamed input document. The expression
|
|
<code>preceding::*</code> is used as a convenient surrogate for an
|
|
expression that can navigate anywhere in the tree, and the presence
|
|
of this expression in the data flow graph will ensure that the
|
|
streamability analysis produces the correct result.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>Many processors will build some kind of expression tree for
|
|
purposes unrelated to streamability analysis. In practice the same
|
|
tree is likely to be used for other operations such as type
|
|
analysis and optimization.</p>
|
|
<p>Because static type inferencing is not prescribed by this
|
|
specification, the algorithms described in this section do not rely
|
|
on type inferencing. In practice, where the static type of an
|
|
expression has already been determined, the processor will be able
|
|
to recognize that some of the steps described in these rules are
|
|
not always necessary.</p>
|
|
</div>
|
|
<p>In principle an expression tree can be constructed for each
|
|
<a title="stylesheet function" class="termref" href=
|
|
"#dt-stylesheet-function">stylesheet function</a>, <a title=
|
|
"template" class="termref" href="#dt-template">template</a>, and
|
|
<a title="attribute set" class="termref" href=
|
|
"#dt-attribute-set">attribute set</a>: its root e-node represents
|
|
the function, template, or attribute set. In practice, however,
|
|
expressions trees are only needed for constructs that are subject
|
|
to streamability analysis: this includes the content of <a href=
|
|
"#element-stream"><code>xsl:stream</code></a> instructions,
|
|
<a title="template rule" class="termref" href=
|
|
"#dt-template-rule">template rules</a> that use a streamable
|
|
<a title="mode" class="termref" href="#dt-mode">mode</a>, and the
|
|
templates, functions, and attribute sets that these call, to any
|
|
depth.</p>
|
|
<p>The children of an <a title="e-node" class="termref" href=
|
|
"#dt-e-node">e-node</a> are determined as described in the table
|
|
below.</p>
|
|
<table border="1" cellpadding="5">
|
|
<thead>
|
|
<tr>
|
|
<th align="left" colspan="1">Parent e-node</th>
|
|
<th align="left" colspan="1">Child e-nodes</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td valign="top"><a title="template" class="termref" href=
|
|
"#dt-template">Template</a></td>
|
|
<td valign="top">The <a title="pattern" class="termref" href=
|
|
"#dt-pattern">pattern</a> in the <code>match</code> attribute if
|
|
present; the <a href="#element-param"><code>xsl:param</code></a>
|
|
elements used to bind default values to the template's parameters;
|
|
and the <a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> that forms the
|
|
body of the template.</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top"><a title="stylesheet function" class="termref"
|
|
href="#dt-stylesheet-function">Stylesheet function</a></td>
|
|
<td valign="top">The <a title="sequence constructor" class=
|
|
"termref" href="#dt-sequence-constructor">sequence constructor</a>
|
|
that forms the body of the function.</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top"><a title="attribute set" class="termref" href=
|
|
"#dt-attribute-set">Attribute set</a></td>
|
|
<td valign="top">The sequence of <a href=
|
|
"#element-attribute"><code>xsl:attribute</code></a> elements that
|
|
forms the body of the attribute set, treated as a <a title=
|
|
"sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a>; plus the
|
|
<code>use-attribute-sets</code> attribute if present.</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">Variable binding element (<a href=
|
|
"#element-variable"><code>xsl:variable</code></a>, <a href=
|
|
"#element-param"><code>xsl:param</code></a>, <a href=
|
|
"#element-with-param"><code>xsl:with-param</code></a>)</td>
|
|
<td valign="top">The <a title="expression" class="termref" href=
|
|
"#dt-expression">expression</a> in the <code>select</code>
|
|
attribute, or the contained <a title="sequence constructor" class=
|
|
"termref" href="#dt-sequence-constructor">sequence
|
|
constructor</a>.</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top"><a title="sequence constructor" class="termref"
|
|
href="#dt-sequence-constructor">Sequence constructor</a></td>
|
|
<td valign="top">The <a title="instruction" class="termref" href=
|
|
"#dt-instruction">instructions</a> within the sequence constructor,
|
|
including any <a title="literal result element" class="termref"
|
|
href="#dt-literal-result-element">literal result elements</a>. It
|
|
is not necessary to include literal text nodes on the tree, since
|
|
they never affect streamability. A sequence constructor comprising
|
|
a single instruction can safely be elided from the tree (that is,
|
|
replaced by its children).</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top"><a title="literal result element" class="termref"
|
|
href="#dt-literal-result-element">Literal result element</a></td>
|
|
<td valign="top">The <a title="sequence constructor" class=
|
|
"termref" href="#dt-sequence-constructor">sequence constructor</a>
|
|
used to construct the content of the new element, plus any
|
|
<a title="attribute value template" class="termref" href=
|
|
"#dt-attribute-value-template">attribute value templates</a> and
|
|
<code>xsl:use-attribute-sets</code> attributes used to construct
|
|
its attributes. An attribute whose value is known statically can be
|
|
omitted from the tree, since it does not affect the streamability
|
|
of the construct.</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top"><a title="attribute value template" class=
|
|
"termref" href="#dt-attribute-value-template">Attribute value
|
|
template</a></td>
|
|
<td valign="top">The XPath expressions contained within curly
|
|
brackets in the attribute value. Any fixed text outside the curly
|
|
brackets can be omitted from the tree, since it does not affect the
|
|
streamability of the construct.</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top"><a href="#element-if"><code>xsl:if</code></a>
|
|
instruction</td>
|
|
<td valign="top">An <a href="#element-if"><code>xsl:if</code></a>
|
|
instruction is rewritten as if it were an XPath <code>if .. then ..
|
|
else ()</code> expression, so that the subsequent analysis can
|
|
treat all conditionals in the same way. The corresponding e-node
|
|
will therefore have three children, one representing the
|
|
<code>test</code> condition, one representing the <a title=
|
|
"sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> contained
|
|
within the <a href="#element-if"><code>xsl:if</code></a>
|
|
instruction, and one representing the empty sequence.</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top"><a href=
|
|
"#element-choose"><code>xsl:choose</code></a> instruction</td>
|
|
<td valign="top">An <a href=
|
|
"#element-choose"><code>xsl:choose</code></a> instruction is
|
|
rewritten as a tree of <code>if .. then .. else ..</code>
|
|
conditional expressions: a second <a href=
|
|
"#element-when"><code>xsl:when</code></a> thus becomes a nested
|
|
conditional within the <code>else</code> branch of the first, and
|
|
so on. The e-node that results will always have three children,
|
|
representing the test condition, the <code>then</code> branch, and
|
|
the <code>else</code> branch. This rewrite is done because it makes
|
|
the subsequent analysis easier, in particular, the determination of
|
|
which subexpressions are mutually exclusive.</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top"><a href="#element-try"><code>xsl:try</code></a>
|
|
instruction</td>
|
|
<td valign="top">The e-node corresponding to an <a href=
|
|
"#element-try"><code>xsl:try</code></a> instruction has two
|
|
children, one for the <a title="sequence constructor" class=
|
|
"termref" href="#dt-sequence-constructor">sequence constructor</a>
|
|
or <code>select</code> expression defining the non-error result of
|
|
the instruction, and one for the set of <a href=
|
|
"#element-catch"><code>xsl:catch</code></a> elements. If there are
|
|
multiple <a href="#element-catch"><code>xsl:catch</code></a>
|
|
elements, these are rewritten as if there were a single <a href=
|
|
"#element-catch"><code>xsl:catch</code></a> containing a
|
|
conditional expression (or set of nested conditionals) performing
|
|
tests on the value of the error code.</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top"><a href=
|
|
"#element-for-each"><code>xsl:for-each</code></a> instruction</td>
|
|
<td valign="top">The <code>select</code> expression, plus the
|
|
<a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> representing
|
|
the body of the instruction. If there are any <a href=
|
|
"#element-sort"><code>xsl:sort</code></a> children, then a
|
|
<code>sort</code> e-node is inserted into the tree to represent the
|
|
sorting operation. This e-node has the <a href=
|
|
"#element-for-each"><code>xsl:for-each</code></a> instruction as
|
|
its parent, and the <code>select</code> expression of the <a href=
|
|
"#element-for-each"><code>xsl:for-each</code></a> instruction as
|
|
its child; in addition, it has as children <span>the
|
|
<code>select</code> expression of the <a href=
|
|
"#element-sort"><code>xsl:sort</code></a> element, plus</span> any
|
|
expressions that appear in <a title="attribute value template"
|
|
class="termref" href="#dt-attribute-value-template">attribute value
|
|
templates</a> among the attributes of the <a href=
|
|
"#element-sort"><code>xsl:sort</code></a> elements (used, for
|
|
example, to compute the collation URI).</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top"><a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>
|
|
instruction</td>
|
|
<td valign="top">The <code>select</code> expression, or an e-node
|
|
representing the expression <code>child::node()</code> if the
|
|
<code>select</code> attribute is omitted; plus variable binding
|
|
elements representing the <a href=
|
|
"#element-with-param"><code>xsl:with-param</code></a> children. If
|
|
there are any <a href="#element-sort"><code>xsl:sort</code></a>
|
|
children, then a <code>sort</code> e-node is inserted into the tree
|
|
to represent the sorting operation: <span>for an illustration of
|
|
this, see <a href="#expr-tree-sorting"><i>18.4.4.4 Analyzing
|
|
sorting constructs</i></a></span>. This e-node has the <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>
|
|
instruction as its parent, and the <code>select</code> expression
|
|
of the <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>
|
|
instruction as its child; in addition, it has as children any
|
|
expressions that appear in <a title="attribute value template"
|
|
class="termref" href="#dt-attribute-value-template">attribute value
|
|
templates</a> among the attributes of the <a href=
|
|
"#element-sort"><code>xsl:sort</code></a> elements (used, for
|
|
example, to compute the collation URI).</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top"><a href=
|
|
"#element-perform-sort"><code>xsl:perform-sort</code></a>
|
|
instruction</td>
|
|
<td valign="top">The <code>select</code> expression <span>or
|
|
contained <a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a></span>,
|
|
together with any expressions that appear in <a title=
|
|
"attribute value template" class="termref" href=
|
|
"#dt-attribute-value-template">attribute value templates</a> among
|
|
the attributes of the <a href=
|
|
"#element-sort"><code>xsl:sort</code></a> elements (used, for
|
|
example, to compute the collation URI).</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top"><a href=
|
|
"#element-for-each-group"><code>xsl:for-each-group</code></a>
|
|
instruction</td>
|
|
<td valign="top">The contained <a title="sequence constructor"
|
|
class="termref" href="#dt-sequence-constructor">sequence
|
|
constructor</a>, plus a <code>group</code> e-node whose children
|
|
are the <code>select</code> expression, the expressions appearing
|
|
in the attributes <code>group-by</code>,
|
|
<code>group-adjacent</code>, and any expression appearing in an
|
|
<a title="attribute value template" class="termref" href=
|
|
"#dt-attribute-value-template">attribute value template</a> in the
|
|
<code>collation</code> attribute. If the instruction has <a href=
|
|
"#element-sort"><code>xsl:sort</code></a> children, then a
|
|
<code>sort</code> e-node is inserted into the tree with the
|
|
<code>xsl:for-each-group</code> instruction as its parent and the
|
|
<code>group</code> e-node as its child; in addition, it has as
|
|
children any expressions that appear in <a title=
|
|
"attribute value template" class="termref" href=
|
|
"#dt-attribute-value-template">attribute value templates</a> among
|
|
the attributes of the <a href=
|
|
"#element-sort"><code>xsl:sort</code></a> elements (used, for
|
|
example, to compute the collation URI). The <a title="pattern"
|
|
class="termref" href="#dt-pattern">pattern</a> appearing in the
|
|
<code>group-starting-with</code> or <code>group-ending-with</code>
|
|
attributes (if present) is analyzed to determine whether it is a
|
|
<a title="streamable pattern" class="termref" href=
|
|
"#dt-streamable-pattern">streamable pattern</a>: if it is, then it
|
|
does not need to be represented on the expression tree; if it is
|
|
not, then a child e-node representing the expression
|
|
<code>preceding::*</code> is added to the tree, indicating
|
|
non-streamable navigation.</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top"><a href=
|
|
"#element-iterate"><code>xsl:iterate</code></a> instruction</td>
|
|
<td valign="top">The <code>select</code> expression; the contained
|
|
<a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a>; the
|
|
<code>select</code> expressions of all contained
|
|
<code>xsl:param</code> elements; the <a href=
|
|
"#element-on-completion"><code>xsl:on-completion</code></a> element
|
|
if present.</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top"><a href=
|
|
"#element-analyze-string"><code>xsl:analyze-string</code></a>
|
|
instruction</td>
|
|
<td valign="top">The <code>select</code> expression; any expression
|
|
appearing in an <a title="attribute value template" class="termref"
|
|
href="#dt-attribute-value-template">attribute value template</a> in
|
|
the <code>regex</code> or <code>flags</code> attributes; the
|
|
<code>xsl:matching-substring</code> and
|
|
<code>xsl:non-matching-substring</code> elements.</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top"><a href=
|
|
"#element-merge"><code>xsl:merge</code></a> instruction</td>
|
|
<td valign="top">See <a href="#expanding-xsl-merge"><i>18.4.2.2
|
|
Expanding the xsl:merge instruction</i></a>.</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top"><a href=
|
|
"#element-number"><code>xsl:number</code></a> instruction</td>
|
|
<td valign="top">See <a href="#expanding-xsl-number"><i>18.4.2.1
|
|
Expanding the xsl:number instruction</i></a>.</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top"><a href=
|
|
"#element-evaluate"><code>xsl:evaluate</code></a> instruction</td>
|
|
<td valign="top">The expressions in the <code>xpath</code> and
|
|
<code>namespace-context</code> attributes; any expression appearing
|
|
in an <a title="attribute value template" class="termref" href=
|
|
"#dt-attribute-value-template">attribute value template</a> in the
|
|
<code>base-uri</code> attribute; any child <a href=
|
|
"#element-with-param"><code>xsl:with-param</code></a> elements;
|
|
plus an e-node representing the expression
|
|
<code>preceding::*</code> (because the navigation performed by the
|
|
dynamic XPath expression is statically unpredictable).
|
|
<blockquote>
|
|
<p><b><a name="issue-streamable-dynamic-evaluate" id=
|
|
"issue-streamable-dynamic-evaluate">Issue 21
|
|
(streamable-dynamic-evaluate)</a>:</b></p>
|
|
<p>This might be a case where deferring decisions on streamability
|
|
until execution time might be appropriate. There might be scope to
|
|
provide an attribute on <a href=
|
|
"#element-evaluate"><code>xsl:evaluate</code></a> that asserts
|
|
streamability (perhaps <a title="motionless" class="termref" href=
|
|
"#dt-motionless">motionless</a> streamability), with this assertion
|
|
being checked at execution time when the actual XPath expression is
|
|
known.</p>
|
|
</blockquote>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top"><a href=
|
|
"#element-sequence"><code>xsl:sequence</code></a> instruction</td>
|
|
<td valign="top">The <a href=
|
|
"#element-sequence"><code>xsl:sequence</code></a> instruction does
|
|
not need to be represented by an e-node on the expression tree; it
|
|
can be replaced by the e-node representing its <code>select</code>
|
|
expression.</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">Other XSLT instructions</td>
|
|
<td valign="top">An e-node representing each XPath expression
|
|
appearing in an attribute of the instruction (including <a title=
|
|
"attribute value template" class="termref" href=
|
|
"#dt-attribute-value-template">attribute value templates</a>), any
|
|
<code>use-attribute-sets</code> attribute, plus the <a title=
|
|
"sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> forming the
|
|
body of the instruction, if any.</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top"><a href="#element-when"><code>xsl:when</code></a>,
|
|
<a href="#element-otherwise"><code>xsl:otherwise</code></a>,
|
|
<a href=
|
|
"#element-matching-substring"><code>xsl:matching-substring</code></a>,
|
|
<a href=
|
|
"#element-non-matching-substring"><code>xsl:non-matching-substring</code></a>,
|
|
<a href="#element-catch"><code>xsl:catch</code></a>, <a href=
|
|
"#element-on-completion"><code>xsl:on-completion</code></a>
|
|
element</td>
|
|
<td valign="top">The contained <a title="sequence constructor"
|
|
class="termref" href="#dt-sequence-constructor">sequence
|
|
constructor</a>.</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top">XPath expressions</td>
|
|
<td valign="top">
|
|
<ul>
|
|
<li>
|
|
<p>Every XPath <a title="expression" class="termref" href=
|
|
"#dt-expression">expression</a> is represented by an e-node whose
|
|
subtree corresponds to the syntactic structure of the expression
|
|
when parsed according to the XPath grammar.</p>
|
|
</li>
|
|
<li>
|
|
<p>An expression that matches productions at several levels in the
|
|
grammar only needs to be represented by a single e-node in the
|
|
tree: for example <code>3</code> will be represented as an
|
|
<code>IntegerLiteral</code>, despite being also a
|
|
<code>PrimaryExpr</code>, a <code>FilterExpr</code>, a
|
|
<code>StepExpr</code>, a <code>PathExpr</code>, and so on.</p>
|
|
</li>
|
|
<li>
|
|
<p>Grammar productions that are not themselves expressions are not
|
|
represented by further child e-nodes. For example, the expression
|
|
<code>@price + 2</code> will be represented by an e-node
|
|
corresponding to the <code>+</code> operator, with two children,
|
|
representing the axis step <code>attribute::price</code> and the
|
|
numeric literal <code>2</code> respectively. The expression
|
|
<code>@price instance of xs:decimal</code> is represented by an
|
|
e-node corresponding to the operator <code>instance of
|
|
xs:decimal</code>, with a single child representing the axis step
|
|
<code>attribute::price</code>. This is because the <a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-SequenceType">SequenceType</a><sup><small>XP21</small></sup>
|
|
<code>xs:decimal</code> is not itself an <a title="expression"
|
|
class="termref" href="#dt-expression">expression</a> and plays no
|
|
role in the streamability analysis.</p>
|
|
</li>
|
|
<li>
|
|
<p>A parenthesized expression is not represented explicitly as an
|
|
e-node, since the tree structure directly captures all the
|
|
information conveyed by the parentheses. For example, the
|
|
expression <code>$a*($b+2)</code> is represented by a tree
|
|
consisting of an e-node representing the <code>*</code> operator
|
|
with two children, one representing the variable reference
|
|
<code>$a</code>, the other representing the <code>+</code>
|
|
operator, which in turn has two children representing the operands
|
|
<code>$b</code> and <code>2</code> respectively.</p>
|
|
</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e29947" id=
|
|
"d7e29947"></a>Example: An expression tree</div>
|
|
<p>Consider the instruction:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:stream href="books.xml">
|
|
<inventory date="{format-date(current-date(), '[D] [MNn] [Y]')}">
|
|
<xsl:value-of select="count(descendant::book)"/>
|
|
</inventory>
|
|
</xsl:stream>
|
|
</pre></div>
|
|
<p>The expression tree for the <a href=
|
|
"#element-stream"><code>xsl:stream</code></a> instruction is shown
|
|
below:</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>Below this paragraph is an SVG diagram. To view it, you need a
|
|
browser that is capable of displaying SVG graphics.</p>
|
|
</div>
|
|
<object type="image/svg+xml" codetype="image/svg+xml" data=
|
|
"img/fig2.svg"><span style=
|
|
"background-color:#FFFF20;padding-top:1pt;padding-bottom:1pt;">This
|
|
browser can't display the SVG file img/fig2.svg. Please upgrade
|
|
your browser or install the Adobe SVG Viewer.</span></object>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>This tree has been simplified slightly: as suggested in the
|
|
rules above, the e-nodes representing sequence constructors
|
|
comprising a single instruction have been elided.</p>
|
|
<p>In practice an implementation can simplify the tree further
|
|
without affecting the subsequent analysis. For example, leaf
|
|
e-nodes representing literal values can be stripped, and in many
|
|
cases intermediate e-nodes representing functions or operators can
|
|
be elided.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="div3">
|
|
<h4><a name="expanding-expr-tree" id=
|
|
"expanding-expr-tree"></a>18.4.2 <a href="#expanding-expr-tree"
|
|
style="text-decoration: none">Expanding the Expression
|
|
Tree</a></h4>
|
|
<p>After the expression tree has been built as described in the
|
|
preceding section, it <span class="verb">must</span> be expanded to
|
|
reflect the implicit navigation carried out by certain instructions
|
|
and expressions. The general rule here is that wherever an
|
|
expression appears on the tree whose evaluation might access one or
|
|
more nodes, the expression is rewritten as a path expression that
|
|
explicitly accesses all the nodes that will be required to evaluate
|
|
the containing expression. Since the expression tree is used only
|
|
to analyze the navigation performed by the stylesheet, and not
|
|
actually to perform any evaluation, it is not necessary that the
|
|
replacement expression be semantically equivalent to the original;
|
|
the only requirement is that it perform equivalent navigation in
|
|
the source tree. For example, the expression <code>string(x)</code>
|
|
can be replaced by
|
|
<span><code>x/descendant-or-self::text()</code></span>, since
|
|
evaluation of the string value of a node involves access to the
|
|
node itself and to all its descendant text nodes.</p>
|
|
<p>The operation of expanding the tree is described here in terms
|
|
of source-level rewrites to certain constructs. For example,
|
|
<code>data(x)</code> is said to be rewritten as
|
|
<code>x/descendant-or-self::text()</code>. This is shorthand for
|
|
saying that the part of the expression tree representing the first
|
|
construct is replaced by the expression tree of the second
|
|
construct.</p>
|
|
<p>The most common rewrite operation is <a title="atomize" class=
|
|
"termref" href="#dt-atomization">atomization</a>. The function
|
|
<a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-data"><code>data</code></a><sup><small>FO</small></sup>,
|
|
and many other functions, perform atomization on the nodes supplied
|
|
to their arguments. Many operators, such as arithmetic and
|
|
comparison operators, do the same, as also do XSLT instructions
|
|
like <a href="#element-value-of"><code>xsl:value-of</code></a> and
|
|
<a href="#element-comment"><code>xsl:comment</code></a>, and
|
|
<a title="attribute value template" class="termref" href=
|
|
"#dt-attribute-value-template">attribute value templates</a>.
|
|
Atomization also occurs when a value is bound to a variable
|
|
declared with an atomic type, and when the result of a function or
|
|
template declared with an atomic type is computed. To atomize a
|
|
node it is necessary to access all its descendant text nodes. Any
|
|
function call, operator, or instruction that atomizes one or more
|
|
of its operands is first rewritten to add a call on <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-data"><code>data</code></a><sup><small>FO</small></sup>
|
|
around each such operand, and this is then processed as described
|
|
in the table below. For example, the expression <code>item[x =
|
|
3]</code> is rewritten <code>item[data(x) = 3]</code>, which is
|
|
then rewritten as <code>item[child::x/descendant-or-self::text() =
|
|
3]</code>.</p>
|
|
<p>In principle any expression X that appears in an atomizing
|
|
context should be replaced by the fragment
|
|
<code>X/descendant-or-self::text()</code>. This expansion is
|
|
clearly unnecessary where X returns an atomic value, or indeed
|
|
where it returns a node other than an element or document node; and
|
|
if type inferencing has shown this to be the case then the
|
|
expansion can be avoided. However, it does not affect the
|
|
streamability analysis if it is done unconditionally.</p>
|
|
<p>The same expansion applies to expressions (such as the <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-string"><code>string</code></a><sup><small>FO</small></sup>
|
|
and <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-string-length"><code>
|
|
string-length</code></a><sup><small>FO</small></sup> functions)
|
|
that compute the string value of the supplied node, and to the
|
|
<a href="#element-copy-of"><code>xsl:copy-of</code></a> instruction
|
|
which accesses all descendant nodes. It also applies to the
|
|
<a href="#function-copy-of"><code>copy-of</code></a> and <a href=
|
|
"#function-snapshot"><code>snapshot</code></a> functions, and to
|
|
any instruction that invokes the rules in <a href=
|
|
"#constructing-complex-content"><i>5.7.1 Constructing Complex
|
|
Content</i></a> or <a href="#constructing-simple-content"><i>5.7.2
|
|
Constructing Simple Content</i></a>, which both implicitly copy or
|
|
atomize the results of instructions in a contained <a title=
|
|
"sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a>.</p>
|
|
<p>The following table gives the expansion needed for other
|
|
constructs that need expanding. Some more complex constructs are
|
|
discussed in the following sections. Others not explicitly
|
|
described <span class="verb">should</span> be handled by applying
|
|
the same general principles. Remember that in each case the
|
|
rewritten expression does not need to deliver the same result; its
|
|
purpose is to identify the implicit navigation performed by each
|
|
operation and describe it in terms of axis steps.</p>
|
|
<p>The expansion continues recursively until no further expansion
|
|
is defined: for example <code>string()</code> is expanded first to
|
|
<code>string(.)</code>, and then to
|
|
<code>./descendant-or-self::text()</code>.</p>
|
|
<table border="1" cellpadding="5">
|
|
<thead>
|
|
<tr>
|
|
<th colspan="1">Expression</th>
|
|
<th colspan="1">Rewrite</th>
|
|
<th colspan="1">Notes</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td><code>data(X)</code></td>
|
|
<td><code>X/descendant-or-self::text()</code></td>
|
|
<td> </td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>string(X)</code></td>
|
|
<td><code>X/descendant-or-self::text()</code></td>
|
|
<td> </td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>base-uri()</code>, <code>document-uri()</code>,
|
|
<code>generate-id()</code>, <code>local-name()</code>,
|
|
<code>name()</code>, <code>namespace-uri()</code>,
|
|
<code>normalize-space()</code>, <code>number()</code>,
|
|
<code>root()</code>, <code>string()</code>,
|
|
<code>string-length()</code></td>
|
|
<td><code>base-uri(.)</code>, <code>document-uri(.)</code>,
|
|
<code>generate-id(.)</code>, <code>local-name(.)</code>,
|
|
<code>name(.)</code>, <code>namespace-uri(.)</code>,
|
|
<code>normalize-space(.)</code>, <code>number(.)</code>,
|
|
<code>root(.)</code>, <code>string(.)</code>,
|
|
<code>string-length(.)</code></td>
|
|
<td>These functions take the context item as an implicit argument
|
|
when called with zero arguments. The expansion makes the dependency
|
|
on the context item explicit.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>copy-of(X)</code></td>
|
|
<td><code>X/descendant-or-self::node()</code></td>
|
|
<td> </td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>snapshot(X)</code></td>
|
|
<td><code>X/descendant-or-self::node()</code></td>
|
|
<td>The fact that the <a href=
|
|
"#function-snapshot"><code>snapshot</code></a> function also
|
|
accesses ancestors and their attributes can be ignored, as it does
|
|
not affect the subsequent analysis.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>/</code></td>
|
|
<td><code>ancestor-or-self::document-node()</code></td>
|
|
<td>It is useful to rewrite this as <code>self::node()</code> if it
|
|
is known that the context node is a document node.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>/X</code></td>
|
|
<td><code>ancestor-or-self::document-node()/X</code></td>
|
|
<td>It is useful to rewrite this as <code>child::X</code> if it is
|
|
known that the context node is a document node.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>root(X)</code></td>
|
|
<td><code>X/ancestor-or-self::node()</code></td>
|
|
<td>While an implementation might not need to visit all the
|
|
ancestors in order to find the root, the effect on streamability is
|
|
the same as if it did. Specifically, access to ancestor nodes is
|
|
permitted in a streamable expression, but access to descendants of
|
|
the ancestors is not.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>key(K, V)</code>, <code>key(K, V, R)</code></td>
|
|
<td><code>(K, V, ancestor::node()/preceding::*)</code>, <code>(K,
|
|
V, R/preceding::*)</code></td>
|
|
<td>Although there are some cases where the <a href=
|
|
"#function-key"><code>key</code></a> function could theoretically
|
|
be evaluated in streaming mode, the analysis is complex and offers
|
|
few benefits; the function can be viewed as a hint to the processor
|
|
to perform a search by building indexes or hash tables, and this
|
|
strategy is inconsistent with streaming. However, use of the
|
|
function is consistent with streaming if it is used to search a
|
|
document other than the streamed input document. The two-argument
|
|
function <code>key(K, V)</code> can be expanded to <code>key(K, V,
|
|
ancestor::node())</code>; the third argument <code>R</code> can
|
|
then be expanded to <code>R/preceding::*</code>.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>id(V)</code> and <code>id(V, R)</code></td>
|
|
<td><code>(V, ancestor::node()/preceding::*)</code>, <code>(V,
|
|
R/preceding::*)</code></td>
|
|
<td>Although the <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-id"><code>id</code></a><sup><small>FO</small></sup>
|
|
function could in many cases be evaluated in streaming mode, doing
|
|
so is unlikely to be useful in practice. This is because detecting
|
|
that an element has the required ID value in the case of ID-valued
|
|
element content (as distinct from attribute content) requires
|
|
reading the descendants of the element, and this leaves little
|
|
scope for the application to do anything useful with the element
|
|
once it has been found. Therefore, the <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-id"><code>id</code></a><sup><small>FO</small></sup>
|
|
is considered non-streamable if applied to the streamed input
|
|
document. This is reflected in the expression tree by first
|
|
expanding the second argument of the function (defaulting it to
|
|
<code>ancestor::node()</code>), and then</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>element-with-id(V)</code> and <code>element-with-id(V,
|
|
R)</code></td>
|
|
<td><code>(V, ancestor::node()/preceding::*)</code>, <code>(V,
|
|
R/preceding::*)</code></td>
|
|
<td>See <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-id"><code>id</code></a><sup><small>FO</small></sup>
|
|
function above.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>lang(L)</code></td>
|
|
<td><code>ancestor-or-self::*/@xml:lang = L</code></td>
|
|
<td>This will generally be streamable, assuming <code>L</code> does
|
|
not navigate within the streamed input document.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>lang(L, N)</code></td>
|
|
<td><code>N/ancestor-or-self::*/@xml:lang = L</code></td>
|
|
<td> </td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>unparsed-entity-uri(N),
|
|
unparsed-entity-public-id(N)</code></td>
|
|
<td><code>ancestor-or-self::document-node()</code></td>
|
|
<td>This will generally be streamable. A streaming processor is
|
|
expected to retain the unparsed entities declared on the streamed
|
|
input document.
|
|
<blockquote>
|
|
<p><b><a name="issue-unparsed-entities-not-at-start" id=
|
|
"issue-unparsed-entities-not-at-start">Issue 22
|
|
(unparsed-entities-not-at-start)</a>:</b></p>
|
|
<p>There is an edge-case problem here: comments and processing
|
|
instructions can precede the <code>DOCTYPE</code> declaration, and
|
|
while processing such comments and processing instructions, the
|
|
unparsed entities referenced in the DTD are not yet known. A
|
|
possible solution would be to require buffering of such comments
|
|
and processing instructions until the DTD has been read. Note that
|
|
the path analysis can establish that a stylesheet makes reference
|
|
to unparsed entities in the streamed document, so it might be
|
|
possible to provide this capability without imposing any costs on
|
|
users who don't use it.</p>
|
|
<p>Another problem with similar consequences is that an expression
|
|
such as <code>/ instance of document-node(element(A))</code> cannot
|
|
be evaluated until the first element start tag has been
|
|
processed.</p>
|
|
</blockquote>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>xsl:copy-of select="N"</code></td>
|
|
<td><code>N/descendant-or-self::node()</code></td>
|
|
<td> </td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>xsl:copy</code> with no <code>select</code>
|
|
attribute</td>
|
|
<td><code><xsl:copy select="."/></code></td>
|
|
<td> </td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>xsl:merge-source</code> with no <code>select</code>
|
|
attribute</td>
|
|
<td><code><xsl:merge-source select="."/></code></td>
|
|
<td> </td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>xsl:number</code></td>
|
|
<td>See <a href="#expanding-xsl-number"><i>18.4.2.1 Expanding the
|
|
xsl:number instruction</i></a></td>
|
|
<td></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>xsl:evaluate xpath="EXP"</code></td>
|
|
<td><code>EXP, preceding::*</code></td>
|
|
<td>As well as any navigation needed to evaluate the expression
|
|
given in the <code>xpath</code> attribute, the instruction
|
|
evaluates the expression, which may perform unpredictable
|
|
navigation from the context item. This is reflected by adding an
|
|
e-node representing the non-streamable <code>preceding::*</code>
|
|
step to the expression tree.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<div class="div4">
|
|
<h5><a name="expanding-xsl-number" id=
|
|
"expanding-xsl-number"></a>18.4.2.1 <a href="#expanding-xsl-number"
|
|
style="text-decoration: none">Expanding the</a>
|
|
<code>xsl:number</code> <a href="#expanding-xsl-number" style=
|
|
"text-decoration: none">instruction</a></h5>
|
|
<p>In general, the <code>xsl:number</code> instruction is not
|
|
<a title="guaranteed-streamable" class="termref" href=
|
|
"#dt-guaranteed-streamable">guaranteed-streamable</a> because it
|
|
computes a number by navigating backwards through the document to
|
|
count preceding nodes. However, there are several common cases
|
|
where streamed evaluation of <a href=
|
|
"#element-number"><code>xsl:number</code></a> is possible.</p>
|
|
<ol class="enumar">
|
|
<li>
|
|
<p>When the <a href="#element-number"><code>xsl:number</code></a>
|
|
instruction has a <code>value</code> attribute, it can be expanded
|
|
in the expression tree in the same way as any other construct. Its
|
|
children in the tree are the <code>value</code> expression, plus
|
|
any expressions that appear within <a title=
|
|
"attribute value template" class="termref" href=
|
|
"#dt-attribute-value-template">attribute value templates</a> in
|
|
other attributes of the instruction.</p>
|
|
</li>
|
|
<li>
|
|
<p>When <a href="#element-number"><code>xsl:number</code></a> has
|
|
no <code>value</code> attribute, streamed evaluation is possible if
|
|
the node selected by the <code>select</code> expression (or its
|
|
default, <code>.</code> (dot)) is in a document other than the
|
|
streamed input document</p>
|
|
</li>
|
|
<li>
|
|
<p>When the selected node is in the streamed input document and
|
|
<code>level="single"</code> or <code>level="multiple"</code> is
|
|
specified, streaming is possible if the following conditions are
|
|
true:</p>
|
|
<ol class="enumla">
|
|
<li>
|
|
<p>The <code>count</code> attribute is either omitted, or is a
|
|
<a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-NodeTest">NodeTest</a><sup><small>XP21</small></sup>.</p>
|
|
</li>
|
|
<li>
|
|
<p>The <code>from</code> attribute is either omitted, or is a
|
|
<a title="streamable pattern" class="termref" href=
|
|
"#dt-streamable-pattern">streamable pattern</a></p>
|
|
</li>
|
|
<li>
|
|
<p>The instruction satisfies the general constraints on
|
|
streamability that apply to every <a title="construct" class=
|
|
"termref" href="#dt-construct">construct</a>: for example, the
|
|
XPath expressions appearing in the instruction (<span>the
|
|
<code>select</code> expression</span> and any <a title=
|
|
"attribute value template" class="termref" href=
|
|
"#dt-attribute-value-template">attribute value templates</a>) do
|
|
not make multiple downward selections.</p>
|
|
</li>
|
|
</ol>
|
|
<p>The reason that the <code>count</code> pattern is restricted to
|
|
be a simple <a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-NodeTest">NodeTest</a><sup><small>XP21</small></sup>
|
|
is that it is applied to preceding-siblings of the node that is
|
|
being numbered. The processing model assumes that the processor
|
|
will maintain limited information about the number of
|
|
preceding-siblings of the current node and all its ancestors,
|
|
specifically, the number of preceding siblings for every
|
|
combination of node-kind, node-name, and type-annotation. This
|
|
information is sufficient to establish how many preceding siblings
|
|
match any given <a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-NodeTest">NodeTest</a><sup><small>XP21</small></sup>,
|
|
but it is not sufficient to do the same for an arbitrary <a title=
|
|
"pattern" class="termref" href="#dt-pattern">pattern</a>, even a
|
|
<a title="streamable pattern" class="termref" href=
|
|
"#dt-streamable-pattern">streamable pattern</a>.</p>
|
|
<p>By contrast, the <code>from</code> pattern is applied only to
|
|
the node being numbered and its ancestors, and for these nodes
|
|
there is sufficient information to test any <a title=
|
|
"streamable pattern" class="termref" href=
|
|
"#dt-streamable-pattern">streamable pattern</a>.</p>
|
|
</li>
|
|
<li>
|
|
<p>When the selected node is in the <a title="streamed document"
|
|
class="termref" href="#dt-streamed-document">streamed document</a>
|
|
and <code>level="any"</code> is specified, streaming can be
|
|
achieved by tallying the counted nodes as they are encountered in
|
|
the input stream, so that the count is already available when the
|
|
selected node comes to be read. This requires analysis of the
|
|
stylesheet to determine all <code>xsl:number level="any"</code>
|
|
instructions that could possibly be evaluated on nodes in the
|
|
streamed document. The relevant instructions are those that appear
|
|
in the data flow graph (see <a href=
|
|
"#analyzing-navigation"><i>18.4.3 Analyzing Navigation</i></a>) on
|
|
paths emanating from the construct whose streamability is being
|
|
analyzed.</p>
|
|
<p>These <a href="#element-number"><code>xsl:number</code></a>
|
|
instructions <span class="verb">must</span> satisfy the following
|
|
conditions for streaming to be possible:</p>
|
|
<ol class="enumla">
|
|
<li>
|
|
<p>The <code>count</code> attribute is present, and is a <a title=
|
|
"streamable pattern" class="termref" href=
|
|
"#dt-streamable-pattern">streamable pattern</a>. (An implementation
|
|
might be able to relax this condition by allowing the
|
|
<code>count</code> attribute to be omitted in cases where the
|
|
node-kind and node-name of the context node can be determined by
|
|
static analysis. However, this analysis is outside the scope of
|
|
this specification, so such instructions are not <a title=
|
|
"guaranteed-streamable" class="termref" href=
|
|
"#dt-guaranteed-streamable">guaranteed-streamable</a>.)</p>
|
|
</li>
|
|
<li>
|
|
<p>The <code>from</code> attribute is either omitted, or is a
|
|
<a title="streamable pattern" class="termref" href=
|
|
"#dt-streamable-pattern">streamable pattern</a>.</p>
|
|
</li>
|
|
<li>
|
|
<p>The <code>select</code> attribute takes its default value of
|
|
<code>.</code> (dot).</p>
|
|
</li>
|
|
<li>
|
|
<p>The instruction satisfies the general constraints on
|
|
streamability that apply to every <a title="construct" class=
|
|
"termref" href="#dt-construct">construct</a>: for example, the
|
|
<a title="attribute value template" class="termref" href=
|
|
"#dt-attribute-value-template">attribute value templates</a> used
|
|
in the instruction do not make multiple downward selections.</p>
|
|
</li>
|
|
</ol>
|
|
<p>A possible implementation strategy is then for the processor,
|
|
while reading nodes from the input stream, to test every node
|
|
against the <code>from</code> and <code>count</code> patterns of
|
|
each reachable <code>xsl:number level="any"</code> instruction. For
|
|
each such instruction, a counter is maintained. When a node matches
|
|
the <code>from</code> pattern, the counter is reset to zero. When
|
|
it matches the <code>count</code> pattern, the counter is
|
|
incremented. When the <a href=
|
|
"#element-number"><code>xsl:number</code></a> instruction is then
|
|
evaluated against the context node, the relevant counter already
|
|
contains the required number.</p>
|
|
</li>
|
|
</ol>
|
|
<p>Although <code>xsl:number</code> is specified in terms of XPath
|
|
expressions that navigate to nodes that precede the context node in
|
|
document order, this navigation does not need to be represented in
|
|
the expression tree, because a streaming implementation is expected
|
|
to maintain counters as the stream is read to make such navigation
|
|
unnecessary.</p>
|
|
<p>So the effect on the expression tree is as follows:</p>
|
|
<ol class="enumar">
|
|
<li>
|
|
<p>The <a href="#element-number"><code>xsl:number</code></a> e-node
|
|
is given children corresponding to the <code>select</code> and
|
|
<code>value</code> expressions, and to any expressions contained in
|
|
attribute value templates, in the normal way.</p>
|
|
</li>
|
|
<li>
|
|
<p>If the instruction is not streamable according to the rules
|
|
given above, then the <a href=
|
|
"#element-number"><code>xsl:number</code></a> expression
|
|
<code>N</code> is expanded to <code>N/preceding::*</code> to
|
|
indicate non-streamable navigation.</p>
|
|
</li>
|
|
</ol>
|
|
</div>
|
|
<div class="div4">
|
|
<h5><a name="expanding-xsl-merge" id=
|
|
"expanding-xsl-merge"></a>18.4.2.2 <a href="#expanding-xsl-merge"
|
|
style="text-decoration: none">Expanding the</a>
|
|
<code>xsl:merge</code> <a href="#expanding-xsl-merge" style=
|
|
"text-decoration: none">instruction</a></h5>
|
|
<p>If <a href="#element-merge"><code>xsl:merge</code></a>
|
|
instruction takes its input by navigating from the <a title=
|
|
"context node" class="termref" href="#dt-context-node">context
|
|
node</a>, then the streamability rules are the same as for any
|
|
other instruction. For example, the following construct is not
|
|
<a title="guaranteed-streamable" class="termref" href=
|
|
"#dt-guaranteed-streamable">guaranteed-streamable</a> because it
|
|
makes two downwards selections from the context item (to the
|
|
elements <code>credits</code> and <code>debits</code>):</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:merge>
|
|
<xsl:merge-source select="credits, debits">
|
|
<xsl:merge-input select="transaction">
|
|
<xsl:merge-key select="timestamp"/>
|
|
</xsl:merge-input
|
|
</xsl:merge-source>
|
|
<xsl:merge-action>
|
|
<xsl:copy-of select="current-group()"/>
|
|
</xsl:merge-action>
|
|
</xsl:merge
|
|
</pre></div>
|
|
<p>Similarly, the following is not streamable, for the same
|
|
reason:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:merge>
|
|
<xsl:merge-source select="credits">
|
|
<xsl:merge-input select="transaction">
|
|
<xsl:merge-key select="timestamp"/>
|
|
</xsl:merge-input>
|
|
</xsl:merge-source>
|
|
<xsl:merge-source select="debits">
|
|
<xsl:merge-input select="transaction"/>
|
|
<xsl:merge-key select="timestamp"/>
|
|
</xsl:merge-source>
|
|
<xsl:merge-action>
|
|
<xsl:copy-of select="current-group()"/>
|
|
</xsl:merge-action>
|
|
</xsl:merge
|
|
</pre></div>
|
|
<p>If <a href="#element-merge"><code>xsl:merge</code></a> is to
|
|
operate on streamed input, this is achieved by using <a href=
|
|
"#element-stream"><code>xsl:stream</code></a> within the <a href=
|
|
"#element-merge-input"><code>xsl:merge-input</code></a>
|
|
instruction. The streamability then depends on analysis of the
|
|
<a href="#element-stream"><code>xsl:stream</code></a> instruction
|
|
alone.</p>
|
|
<p>For the purposes of this analysis, therefore, <a href=
|
|
"#element-merge"><code>xsl:merge</code></a> is not essentially
|
|
different from any other instruction. The structure in the
|
|
expression tree matches the syntactic structure:</p>
|
|
<ul>
|
|
<li>
|
|
<p>The e-node representing the <a href=
|
|
"#element-merge"><code>xsl:merge</code></a> element has one child
|
|
for each <a href=
|
|
"#element-merge-source"><code>xsl:merge-source</code></a> element,
|
|
and one for the <a href=
|
|
"#element-merge-action"><code>xsl:merge-action</code></a>.</p>
|
|
</li>
|
|
<li>
|
|
<p>The e-node representing the <a href=
|
|
"#element-merge-source"><code>xsl:merge-source</code></a> element
|
|
has one child for the <code>select</code> expression and one for
|
|
the <a href="#element-merge-input"><code>xsl:merge-input</code></a>
|
|
element.</p>
|
|
</li>
|
|
<li>
|
|
<p>The e-node representing the <a href=
|
|
"#element-merge-input"><code>xsl:merge-input</code></a> element has
|
|
one child for its <code>select</code> attribute or contained
|
|
sequence constructor, plus additional children for the expressions
|
|
contained in any <a href=
|
|
"#element-merge-key"><code>xsl:merge-key</code></a> children.</p>
|
|
</li>
|
|
</ul>
|
|
<p>In the subsequent analysis, as explained in later sections, it
|
|
is necessary to take account of the fact that (a) the
|
|
<code>select</code> expressions of both <a href=
|
|
"#element-merge-source"><code>xsl:merge-source</code></a> and
|
|
<a href="#element-merge-input"><code>xsl:merge-input</code></a>
|
|
change the <a title="focus" class="termref" href=
|
|
"#dt-focus">focus</a>, and (b) some of the contained expressions
|
|
are evaluated repeatedly, meaning that <a href=
|
|
"#element-merge"><code>xsl:merge</code></a> <span>is treated as a
|
|
looping construct (see <a href="#expr-tree-loops"><i>18.4.4.3
|
|
Analyzing looping constructs</i></a>)</span> .</p>
|
|
</div>
|
|
</div>
|
|
<div class="div3">
|
|
<h4><a name="analyzing-navigation" id=
|
|
"analyzing-navigation"></a>18.4.3 <a href="#analyzing-navigation"
|
|
style="text-decoration: none">Analyzing Navigation</a></h4>
|
|
<p>Having built the expression tree, the next step is to analyze
|
|
where <a title="construct" class="termref" href=
|
|
"#dt-construct">constructs</a> derive their input. The objective
|
|
here is twofold:</p>
|
|
<ul>
|
|
<li>
|
|
<p>Firstly, it is necessary to determine which <a title="construct"
|
|
class="termref" href="#dt-construct">constructs</a> operate on data
|
|
that comes from the <span><a title="streamed document" class=
|
|
"termref" href="#dt-streamed-document">streamed
|
|
document</a></span>. If a construct is actually operating on other
|
|
(non-streamed) input documents, then it is able to access that data
|
|
without constraints.</p>
|
|
</li>
|
|
<li>
|
|
<p>Secondly, where constructs operate on the streamed document, it
|
|
is necessary to determine whether they do so in a way that permits
|
|
streaming. This requires analysis of the navigation paths through
|
|
the streamed document.</p>
|
|
</li>
|
|
</ul>
|
|
<p>This analysis creates a new graph, <span>known as the <b>data
|
|
flow graph</b>,</span> showing a different kind of relationship
|
|
between the <a title="e-node" class="termref" href=
|
|
"#dt-e-node">e-nodes</a> of the expression tree: the arcs in this
|
|
graph show where nodes returned by one construct are used as input
|
|
to another construct. These data flows can arise in a number of
|
|
ways:</p>
|
|
<ul>
|
|
<li>
|
|
<p>A child construct can return nodes that participate directly in
|
|
the result of its parent construct. For example, when the
|
|
<code>union</code> operator is used, the result of the union
|
|
expression includes the nodes returned by both its operand
|
|
expressions.</p>
|
|
</li>
|
|
<li>
|
|
<p>When a variable is bound to a node or nodes, there is a data
|
|
flow from the construct used to initialize the variable to every
|
|
variable reference that refers to this variable binding.</p>
|
|
</li>
|
|
<li>
|
|
<p>When a construct sets the context item, there is a data flow
|
|
from the child construct that sets the context item to every
|
|
context-dependent construct that uses this new context.</p>
|
|
</li>
|
|
<li>
|
|
<p>When a construct calls a <a title="stylesheet function" class=
|
|
"termref" href="#dt-stylesheet-function">stylesheet function</a> or
|
|
a <a title="named template" class="termref" href=
|
|
"#dt-named-template">named template</a>, there is a data flow from
|
|
the construct that sets the value of a parameter to the function or
|
|
template to the variable binding in the called function or
|
|
template.</p>
|
|
</li>
|
|
<li>
|
|
<p>When parameters are supplied from one iteration of <a href=
|
|
"#element-iterate"><code>xsl:iterate</code></a> to the next using
|
|
<a href="#element-with-param"><code>xsl:with-param</code></a>
|
|
elements within <a href=
|
|
"#element-next-iteration"><code>xsl:next-iteration</code></a>,
|
|
there is a data flow from the <a href=
|
|
"#element-with-param"><code>xsl:with-param</code></a> element that
|
|
sets the parameter value to the <a href=
|
|
"#element-param"><code>xsl:param</code></a> element that receives
|
|
it.</p>
|
|
</li>
|
|
</ul>
|
|
<p>The following sections describe in more detail how these data
|
|
flows are modeled. In all cases they result in arcs being added to
|
|
the data flow graph.</p>
|
|
<div class="div4">
|
|
<h5><a name="marking-contributing-expr" id=
|
|
"marking-contributing-expr"></a>18.4.3.1 <a href=
|
|
"#marking-contributing-expr" style="text-decoration: none">Marking
|
|
contributing child constructs</a></h5>
|
|
<p>An arc is created in the data flow graph from any <a title=
|
|
"e-node" class="termref" href="#dt-e-node">e-node</a> to its parent
|
|
in the expression tree if the child <a title="construct" class=
|
|
"termref" href="#dt-construct">construct</a> returns <a href=
|
|
"http://www.w3.org/TR/xpath-datamodel-11/#dt-node">nodes</a><sup><small>DM11</small></sup>
|
|
that form part of the result of the parent construct.</p>
|
|
<p>The following table lists constructs that return nodes
|
|
contributed by one of their child constructs, referred to as a
|
|
<b>contributing construct</b>.</p>
|
|
<table border="1">
|
|
<thead>
|
|
<tr>
|
|
<th colspan="1">Construct</th>
|
|
<th colspan="1">Contribution</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>Path expression <code>A/B</code></td>
|
|
<td><code>B</code> is a contributing construct.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Filter expression <code>S[P]</code></td>
|
|
<td><code>S</code> is a contributing construct.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Union expression <code>P|Q</code></td>
|
|
<td><code>P</code> and <code>Q</code> are both contributing
|
|
constructs.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Difference expression <code>P except Q</code></td>
|
|
<td><code>P</code> is a contributing construct.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Intersection expression <code>P intersect Q</code></td>
|
|
<td><code>P</code> and <code>Q</code> are both contributing
|
|
constructs.
|
|
<blockquote>
|
|
<p><b><a name="issue-intersect" id="issue-intersect">Issue 23
|
|
(intersect)</a>:</b></p>
|
|
<p>It might be safe to treat one of the operands as
|
|
non-contributing, but the Working Group has not been able to
|
|
demonstrate this to its satisfaction. Note that if one of the
|
|
operands selects nodes from the streamed input and the other does
|
|
not, then the intersection will not contain any nodes from the
|
|
streamed input.</p>
|
|
</blockquote>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Comma expression <code>P, Q</code></td>
|
|
<td><code>P</code> and <code>Q</code> are both contributing
|
|
constructs.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">Sequence constructor</a></td>
|
|
<td>The <a title="instruction" class="termref" href=
|
|
"#dt-instruction">instructions</a> within the sequence constructor
|
|
are all contributing constructs.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>XSLT variable binding (<a href=
|
|
"#element-variable"><code>xsl:variable</code></a>, <a href=
|
|
"#element-param"><code>xsl:param</code></a>, <a href=
|
|
"#element-with-param"><code>xsl:with-param</code></a>)</td>
|
|
<td>The initializer of the variable binding (that is, the
|
|
<code>select</code> expression or the contained sequence
|
|
constructor) is a contributing construct. However, in the case
|
|
where there is no <code>as</code> attribute, so a new document node
|
|
is created, the sequence constructor is not a contributing
|
|
construct. Also, the initializer is not a contributing construct in
|
|
the case where the variable is declared with an atomic type, as any
|
|
nodes delivered by the initializer will then be atomized. The
|
|
implicit navigation required to perform this atomization must be
|
|
made explicit on the expression tree.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>XPath variable binding (<code>for</code>,
|
|
<code>let</code>)</td>
|
|
<td>In the case of <code>for</code> and <code>let</code>
|
|
expressions, the expression in the <code>return</code> clause is a
|
|
contributing expression to the result of the <code>for</code> or
|
|
<code>let</code> expression. In the case of <code>some</code> and
|
|
<code>every</code> expressions, the result is a boolean, so there
|
|
is no contributing subexpression.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Conditional <code>if (C) then T else E</code></td>
|
|
<td><code>T</code> and <code>E</code> are both contributing
|
|
constructs (<code>C</code> is not). This applies whether the
|
|
conditional originated as an XPath <code>if</code> expression, or
|
|
as an <a href="#element-if"><code>xsl:if</code></a> or <a href=
|
|
"#element-choose"><code>xsl:choose</code></a> instruction.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Instructions <a href=
|
|
"#element-for-each"><code>xsl:for-each</code></a>, <a href=
|
|
"#element-for-each-group"><code>xsl:for-each-group</code></a>,
|
|
<span><a href=
|
|
"#element-stream"><code>xsl:stream</code></a></span></td>
|
|
<td>The contained <a title="sequence constructor" class="termref"
|
|
href="#dt-sequence-constructor">sequence constructor</a> is a
|
|
contributing construct.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Instruction <a href=
|
|
"#element-iterate"><code>xsl:iterate</code></a></td>
|
|
<td>The contained <a title="sequence constructor" class="termref"
|
|
href="#dt-sequence-constructor">sequence constructor</a> and the
|
|
<a href="#element-on-completion"><code>xsl:on-completion</code></a>
|
|
child are contributing constructs.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Instruction <a href=
|
|
"#element-perform-sort"><code>xsl:perform-sort</code></a></td>
|
|
<td>The <code>select</code> expression and the contained <a title=
|
|
"sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> are
|
|
contributing constructs.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Instruction <a href=
|
|
"#element-analyze-string"><code>xsl:analyze-string</code></a></td>
|
|
<td>The <a href=
|
|
"#element-matching-substring"><code>xsl:matching-substring</code></a>
|
|
and <a href=
|
|
"#element-non-matching-substring"><code>xsl:non-matching-substring</code></a>
|
|
children are contributing constructs.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Instruction <a href=
|
|
"#element-merge"><code>xsl:merge</code></a></td>
|
|
<td>The contained <a href=
|
|
"#element-merge-action"><code>xsl:merge-action</code></a> element
|
|
is a contributing construct.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Instruction <a href=
|
|
"#element-try"><code>xsl:try</code></a></td>
|
|
<td>The contained <a title="sequence constructor" class="termref"
|
|
href="#dt-sequence-constructor">sequence constructor</a> and each
|
|
contained <a href="#element-catch"><code>xsl:catch</code></a>
|
|
element is a contributing construct.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Elements <a href="#element-when"><code>xsl:when</code></a>,
|
|
<a href="#element-otherwise"><code>xsl:otherwise</code></a>,
|
|
<a href=
|
|
"#element-matching-substring"><code>xsl:matching-substring</code></a>,
|
|
<a href=
|
|
"#element-non-matching-substring"><code>xsl:non-matching-substring</code></a>,
|
|
<a href="#element-catch"><code>xsl:catch</code></a>, <a href=
|
|
"#element-on-completion"><code>xsl:on-completion</code></a>,
|
|
<a href=
|
|
"#element-merge-action"><code>xsl:merge-action</code></a></td>
|
|
<td>The contained <a title="sequence constructor" class="termref"
|
|
href="#dt-sequence-constructor">sequence constructor</a> is a
|
|
contributing construct.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Functions <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-remove"><code>remove</code></a><sup><small>FO</small></sup>,
|
|
<a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-subsequence"><code>subsequence</code></a><sup><small>FO</small></sup>,
|
|
<a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-reverse"><code>reverse</code></a><sup><small>FO</small></sup>,
|
|
<a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-trace"><code>trace</code></a><sup><small>FO</small></sup>,
|
|
<a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-unordered"><code>unordered</code></a><sup><small>FO</small></sup>,
|
|
<a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-one-or-more"><code>one-or-more</code></a><sup><small>FO</small></sup>,
|
|
<a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-exactly-one"><code>exactly-one</code></a><sup><small>FO</small></sup>,
|
|
<a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-zero-or-one"><code>zero-or-one</code></a><sup><small>FO</small></sup>,
|
|
<a href="#function-innermost"><code>innermost</code></a>, <a href=
|
|
"#function-outermost"><code>outermost</code></a></td>
|
|
<td>The first argument is a contributing construct.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Function <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-insert-before"><code>
|
|
insert-before</code></a><sup><small>FO</small></sup></td>
|
|
<td>The first and third arguments are contributing constructs.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Operation <code>sort</code> (the e-node that is added to the
|
|
tree by operations that perform sorting)</td>
|
|
<td>The subexpression representing the <code>select</code>
|
|
expression (the sequence being sorted) is a contributing
|
|
construct.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<div class="div4">
|
|
<h5><a name="tracing-variable-references" id=
|
|
"tracing-variable-references"></a>18.4.3.2 <a href=
|
|
"#tracing-variable-references" style=
|
|
"text-decoration: none">Analyzing variable references</a></h5>
|
|
<p>In the data flow graph, an arc is created from a variable
|
|
binding construct to every variable reference that refers to that
|
|
variable.</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e31158" id=
|
|
"d7e31158"></a>Example: Data flow with variables</div>
|
|
<p>Consider the construct:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:template name="example">
|
|
<xsl:variable name="doc-A" select="doc('a.xml')"/>
|
|
<xsl:stream href="b.xml">
|
|
<xsl:sequence
|
|
select="count($doc-A/descendant::*) + count(descendant::*)"/>
|
|
</xsl:stream>
|
|
</xsl:template>
|
|
</pre></div>
|
|
<p>The expression tree for this template is as follows (note that
|
|
sequence constructors containing a single instruction have again
|
|
been elided):</p>
|
|
<object type="image/svg+xml" codetype="image/svg+xml" data=
|
|
"img/fig3.svg"><span style=
|
|
"background-color:#FFFF20;padding-top:1pt;padding-bottom:1pt;">This
|
|
browser can't display the SVG file img/fig3.svg. Please upgrade
|
|
your browser or install the Adobe SVG Viewer.</span></object>
|
|
<p>After adding the links from contributing subexpressions to their
|
|
parent expression, and from the variable declaration to its
|
|
reference, the data flow graph is like this:</p>
|
|
<object type="image/svg+xml" codetype="image/svg+xml" data=
|
|
"img/fig4.svg"><span style=
|
|
"background-color:#FFFF20;padding-top:1pt;padding-bottom:1pt;">This
|
|
browser can't display the SVG file img/fig4.svg. Please upgrade
|
|
your browser or install the Adobe SVG Viewer.</span></object></div>
|
|
</div>
|
|
<div class="div4">
|
|
<h5><a name="tracing-context-path" id=
|
|
"tracing-context-path"></a>18.4.3.3 <a href="#tracing-context-path"
|
|
style="text-decoration: none">Tracing the Context of an
|
|
Expression</a></h5>
|
|
<p>In the same way as the previous step created arcs in the data
|
|
flow graph from an <a title="e-node" class="termref" href=
|
|
"#dt-e-node">e-node</a> representing a variable declaration to an
|
|
e-node representing a variable reference, this step creates an arc
|
|
from an e-node representing a <a title="construct" class="termref"
|
|
href="#dt-construct">construct</a> that sets the context item to an
|
|
e-node representing a reference to the context item. This creates
|
|
one arc pointing to each e-node representing any of the
|
|
following:</p>
|
|
<ul>
|
|
<li>
|
|
<p>The context item expression <code>.</code></p>
|
|
</li>
|
|
<li>
|
|
<p>An axis step, for example <code>@status</code></p>
|
|
</li>
|
|
<li>
|
|
<p>The expression <code>last()</code> (but not
|
|
<code>position()</code>, since calls on the <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-position"><code>position</code></a><sup><small>FO</small></sup>
|
|
function never affect the streamability analysis).</p>
|
|
</li>
|
|
</ul>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>Other expressions that might appear to be dependent on the
|
|
context item have already been rewritten to make the dependency
|
|
explicit: for example <code>name()</code> has been rewritten as
|
|
<code>name(.)</code>, while <code>/</code> has been rewritten as
|
|
<code>ancestor-or-self::document-node()</code>, as described in
|
|
<a href="#expanding-expr-tree"><i>18.4.2 Expanding the Expression
|
|
Tree</i></a></p>
|
|
<p>It would be possible to handle axis steps in the same way, by
|
|
rewriting <code>@status</code> as <code>./@status</code>. However,
|
|
if applied repeatedly, the resulting expression would be expanded
|
|
again, leading to infinite recursion.</p>
|
|
</div>
|
|
<p>The instructions <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>,
|
|
<a href=
|
|
"#element-apply-imports"><code>xsl:apply-imports</code></a>, and
|
|
<a href="#element-next-match"><code>xsl:next-match</code></a> are
|
|
not considered to depend on the context item: they are considered
|
|
separately: see <a href=
|
|
"#streamability-of-dynamic-invocation"><i>18.4.4.5 Analyzing
|
|
dynamic invocation</i></a></p>
|
|
<p>The origin of the arc is the construct that sets the context
|
|
item for this expression. This is found by searching for the
|
|
nearest ancestor e-node that represents a construct that changes
|
|
the focus. An example of such an construct is a path expression
|
|
<code>A/B</code>. This has two subexpressions: <code>A</code>,
|
|
which sets the focus, and <code>B</code>, which is evaluated with
|
|
the new focus. Other context-changing constructs similarly have a
|
|
child construct that acts as focus setter and another (or several)
|
|
that are evaluated using the new focus. These are shown in the
|
|
table below:</p>
|
|
<table border="1" cellpadding="5">
|
|
<thead>
|
|
<tr>
|
|
<th align="left" colspan="1">Construct</th>
|
|
<th align="left" colspan="1">Context-setting construct</th>
|
|
<th align="left" colspan="1">Construct(s) evaluated with the new
|
|
focus</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>Path expression A/B</td>
|
|
<td>A</td>
|
|
<td>B</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Filter expression A[B]</td>
|
|
<td>A</td>
|
|
<td>B</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#element-for-each"><code>xsl:for-each</code></a></td>
|
|
<td><code>select</code> expression</td>
|
|
<td>the contained sequence constructor, and the <code>select</code>
|
|
attributes of any <a href="#element-sort"><code>xsl:sort</code></a>
|
|
keys</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href=
|
|
"#element-for-each-group"><code>xsl:for-each-group</code></a></td>
|
|
<td><code>select</code> expression</td>
|
|
<td>the contained sequence constructor, and the <code>select</code>
|
|
attributes of any <a href="#element-sort"><code>xsl:sort</code></a>
|
|
keys</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#element-iterate"><code>xsl:iterate</code></a></td>
|
|
<td><code>select</code> expression</td>
|
|
<td>the contained sequence constructor <span>and any <a href=
|
|
"#element-on-completion"><code>xsl:on-completion</code></a>
|
|
child</span></td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href=
|
|
"#element-analyze-string"><code>xsl:analyze-string</code></a></td>
|
|
<td><code>select</code> expression</td>
|
|
<td>the sequence constructors within the <a href=
|
|
"#element-matching-substring"><code>xsl:matching-substring</code></a>
|
|
and <a href=
|
|
"#element-non-matching-substring"><code>xsl:non-matching-substring</code></a>
|
|
children</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#element-stream"><code>xsl:stream</code></a></td>
|
|
<td>the <code>xsl:stream</code> instruction itself</td>
|
|
<td>the contained sequence constructor</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href=
|
|
"#element-perform-sort"><code>xsl:perform-sort</code></a></td>
|
|
<td><code>select</code> expression <span>or the contained <a title=
|
|
"sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a></span></td>
|
|
<td>the <code>select</code> expressions of the <a href=
|
|
"#element-sort"><code>xsl:sort</code></a> keys</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href=
|
|
"#element-merge-source"><code>xsl:merge-source</code></a></td>
|
|
<td><code>select</code> expression</td>
|
|
<td>the <code>select</code> expression or the contained <a title=
|
|
"sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> of the <a href=
|
|
"#element-merge-input"><code>xsl:merge-input</code></a>
|
|
children</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href=
|
|
"#element-merge-input"><code>xsl:merge-input</code></a></td>
|
|
<td><code>select</code> expression or the contained <a title=
|
|
"sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a></td>
|
|
<td>the <code>select</code> expressions of the <a href=
|
|
"#element-merge-key"><code>xsl:merge-key</code></a> children, and
|
|
the <a href=
|
|
"#element-merge-action"><code>xsl:merge-action</code></a> element.
|
|
Note that context for the <a href=
|
|
"#element-merge-action"><code>xsl:merge-action</code></a> element
|
|
is set by each of the <a href=
|
|
"#element-merge-input"><code>xsl:merge-input</code></a> elements,
|
|
so in general there will be multiple arcs to the <a href=
|
|
"#element-merge-action"><code>xsl:merge-action</code></a>
|
|
e-node.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>Having found an <a title="e-node" class="termref" href=
|
|
"#dt-e-node">e-node</a> <var>E</var> that represents a
|
|
context-dependent construct, the relevant context-setting construct
|
|
can be found by searching the ancestors of the e-node until a
|
|
context-changing construct <var>C</var> is found, provided that
|
|
<var>E</var> is within the subexpression that uses the new context.
|
|
The context-setting construct is then the subexpression of
|
|
<var>C</var> that sets the context item, shown in the table
|
|
above.</p>
|
|
<p>If the search for ancestor e-nodes finds no context-changing
|
|
construct, then the context-setting construct is deemed to be the
|
|
e-node at the root of the tree, for example an e-node representing
|
|
an <a href="#element-template"><code>xsl:template</code></a>
|
|
declaration.</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e31478" id=
|
|
"d7e31478"></a>Example: Adding context arcs to the data flow
|
|
graph</div>
|
|
<p>This example builds on the example in the previous section.
|
|
After adding the links from context-setting constructs to
|
|
context-using constructs, the data flow graph is like this:</p>
|
|
<object type="image/svg+xml" codetype="image/svg+xml" data=
|
|
"img/fig5.svg"><span style=
|
|
"background-color:#FFFF20;padding-top:1pt;padding-bottom:1pt;">This
|
|
browser can't display the SVG file img/fig5.svg. Please upgrade
|
|
your browser or install the Adobe SVG Viewer.</span></object>
|
|
<p>It can now be clearly seen that there are two navigation paths
|
|
performed by this template, from document <code>a.xml</code> to its
|
|
descendant elements, and from <code>b.xml</code> to its descendant
|
|
elements. The streamability analysis will in due course examine the
|
|
paths in the data flow graph emanating from the e-node representing
|
|
the <a href="#element-stream"><code>xsl:stream</code></a>
|
|
instruction to determine whether they conform to the rules for
|
|
streamable navigation (which they do).</p>
|
|
<p>The navigation paths relating to <code>a.xml</code> do not need
|
|
to be streamable, because this document is being accessed using
|
|
non-streaming interfaces; however, it is necessary to construct the
|
|
paths before it can be determined which document is being accessed
|
|
by which expressions.</p>
|
|
</div>
|
|
<p>There are some special cases:</p>
|
|
<ol class="enumar">
|
|
<li>
|
|
<p>If <var>E</var> represents a call on the function <a href=
|
|
"#function-current"><code>current</code></a>, then the search for a
|
|
context-changing ancestor e-node skips all e-nodes that represent
|
|
containing XPath expressions (that is, the search only considers
|
|
XSLT constructs that set the context).</p>
|
|
</li>
|
|
<li>
|
|
<p>If <var>E</var> represents a call on the function <a href=
|
|
"#function-current-group"><code>current-group</code></a>, that
|
|
appears nested within an <a href=
|
|
"#element-for-each-group"><code>xsl:for-each-group</code></a>
|
|
instruction that is itself within the expression tree, is treated
|
|
as if it were the axis step <code>child::node()</code>. Although
|
|
this bears no relationship to the actual navigation path in the
|
|
source tree, it has the correct result in the context of
|
|
streamability analysis. This is because grouping essentially
|
|
performs two nested iterations over the items in an input sequence
|
|
(one over the groups, one over the items of each group) and this
|
|
processing structure is the same as if there were an extra level of
|
|
nodes in the source tree. If there is no enclosing <a href=
|
|
"#element-for-each-group"><code>xsl:for-each-group</code></a>
|
|
instruction within the expression tree (which is possible because
|
|
the <a title="current group" class="termref" href=
|
|
"#dt-current-group">current group</a> has dynamic scope) then the
|
|
call on <a href=
|
|
"#function-current-group"><code>current-group</code></a> can be
|
|
treated as if it were a reference to a global variable; it has no
|
|
bearing on the path analysis.</p>
|
|
</li>
|
|
</ol>
|
|
<blockquote>
|
|
<p><b><a name="issue-streamability-of-grouping" id=
|
|
"issue-streamability-of-grouping">Issue 24
|
|
(streamability-of-grouping)</a>:</b></p>
|
|
<p>The analysis of the streamability of grouping needs a more
|
|
thorough exposition; although the rules given might well be
|
|
correct, they are not convincingly explained.</p>
|
|
</blockquote>
|
|
<p>At this stage it is possible to detect some conditions that will
|
|
render an expression non-streamable, without the need to do further
|
|
analysis. If we are testing an <a href=
|
|
"#element-stream"><code>xsl:stream</code></a> or <a href=
|
|
"#element-template"><code>xsl:template</code></a> construct for
|
|
streamability, then if any of the following e-nodes are present on
|
|
a path in the data flow graph starting at that construct, the
|
|
construct is not streamable:</p>
|
|
<ul>
|
|
<li>
|
|
<p>An axis step using any of the axes
|
|
<code>following-sibling</code>, <code>preceding-sibling</code>,
|
|
<code>following</code>, or <code>preceding</code></p>
|
|
</li>
|
|
<li>
|
|
<p>A call on the <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-last"><code>last</code></a><sup><small>FO</small></sup>
|
|
function</p>
|
|
</li>
|
|
<li>
|
|
<p>A <code>sort</code> node</p>
|
|
</li>
|
|
<li>
|
|
<p>A call on the <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-reverse"><code>reverse</code></a><sup><small>FO</small></sup>
|
|
function</p>
|
|
</li>
|
|
<li>
|
|
<p>An <a href=
|
|
"#element-for-each-group"><code>xsl:for-each-group</code></a>
|
|
instruction with a <code>group-by</code> attribute.</p>
|
|
</li>
|
|
</ul>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="avoiding-last" id=
|
|
"avoiding-last"></a>Example: Avoiding the use of
|
|
<code>last()</code></div>
|
|
<p>Use of the <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-last"><code>last</code></a><sup><small>FO</small></sup>
|
|
function can often cause code to become non-streamable. In some
|
|
cases the problem is easily avoided by rearranging the code. For
|
|
example, the following template inserts a <code><br/></code>
|
|
element after every line of a poem except the last:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:for-each select="poem/lines">
|
|
<xsl:value-of select="."/>
|
|
<xsl:if test="position() ne last()"><br/></xsl:if>
|
|
</xsl:for-each>
|
|
</pre></div>
|
|
<p>This code is not streamable, but it can easily be rewritten to
|
|
make it streamable by instead inserting the
|
|
<code><br/></code> element before every line except the
|
|
first:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:for-each select="poem/lines">
|
|
<xsl:if test="position() ne 1"><br/></xsl:if>
|
|
<xsl:value-of select="."/>
|
|
</xsl:for-each>
|
|
</pre></div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="div3">
|
|
<h4><a name="streamability-choice-and-repetition" id=
|
|
"streamability-choice-and-repetition"></a>18.4.4 <a href=
|
|
"#streamability-choice-and-repetition" style=
|
|
"text-decoration: none">Analyzing choices, repetition, and
|
|
calls</a></h4>
|
|
<p>The previous section established a data flow graph sufficient to
|
|
identify the navigation routes through a document used within an
|
|
individual function or template. This is not yet sufficient to
|
|
establish whether the navigation is <a title=
|
|
"guaranteed-streamable" class="termref" href=
|
|
"#dt-guaranteed-streamable">guaranteed-streamable</a>:</p>
|
|
<ul>
|
|
<li>
|
|
<p>Conditional branches in the logic can make a construct
|
|
streamable based on knowledge that two navigation paths are
|
|
mutually exclusive at run-time (the logic will only follow one of
|
|
them). Conditional branches arise most obviously from use of an
|
|
<a href="#element-choose"><code>xsl:choose</code></a> instruction
|
|
or an XPath <code>if</code> expression; however they also arise
|
|
with <a href="#element-catch"><code>xsl:catch</code></a>, and the
|
|
same analysis is used with <a href=
|
|
"#element-fork"><code>xsl:fork</code></a>.</p>
|
|
</li>
|
|
<li>
|
|
<p>Iteration in the logic, on the other hand, can make a construct
|
|
non-streamable, because it is in the nature of streaming that
|
|
descendant nodes can only be visited once.</p>
|
|
</li>
|
|
<li>
|
|
<p>To get a complete picture of the navigation routes followed, it
|
|
is necessary to trace paths through function and template calls and
|
|
invocations of <a title="attribute set" class="termref" href=
|
|
"#dt-attribute-set">attribute sets</a>.</p>
|
|
</li>
|
|
</ul>
|
|
<p>These factors are considered in the sections that follow.</p>
|
|
<div class="div4">
|
|
<h5><a name="expr-tree-choices" id="expr-tree-choices"></a>18.4.4.1
|
|
<a href="#expr-tree-choices" style=
|
|
"text-decoration: none">Analyzing conditional constructs</a></h5>
|
|
<p>It is necessary to identify <a title="construct" class="termref"
|
|
href="#dt-construct">constructs</a> that are mutually exclusive, in
|
|
the sense that when one construct is evaluated the other will not
|
|
be evaluated. This is because a <a title="guaranteed-streamable"
|
|
class="termref" href=
|
|
"#dt-guaranteed-streamable">guaranteed-streamable</a> construct is
|
|
only allowed to traverse the children of a node once, but
|
|
performing two traversals in mutually exclusive branches of a
|
|
conditional does not violate this condition. For example, the
|
|
expression <code>if (@a) then child::title else
|
|
child::subtitle</code> is potentially streamable even though it
|
|
contains two downward selections.</p>
|
|
<p>Recall that when building the expression tree, <span>an <a href=
|
|
"#element-if"><code>xsl:if</code></a> instruction was converted to
|
|
an (if-then-else) expression, in which the else branch is always an
|
|
empty sequence, and</span> an <a href=
|
|
"#element-choose"><code>xsl:choose</code></a>stream instruction was
|
|
decomposed into a set of binary (if-then-else) tests
|
|
<span>Furthermore, a sequence of <a href=
|
|
"#element-catch"><code>xsl:catch</code></a> clauses was reduced to
|
|
a single <a href="#element-catch"><code>xsl:catch</code></a>
|
|
construct containing internal <code>if-then-else</code> constructs
|
|
to test the error code. Thus all conditional expressions have been
|
|
reduced to a common form.</span></p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-mutually-exclusive" id="dt-mutually-exclusive" title=
|
|
"mutually exclusive"></a>Two <a title="e-node" class="termref"
|
|
href="#dt-e-node">e-nodes</a> in the expression tree are defined to
|
|
be <b>mutually exclusive</b> if they have a common ancestor
|
|
<code>if</code> e-node, and if one is a descendant of the
|
|
<code>then</code> child of that <code>if</code>, while the other is
|
|
a descendant of the <code>else</code> child. Two e-nodes are also
|
|
<b>mutually exclusive</b> if they are <a title=
|
|
"mutually independent" class="termref" href=
|
|
"#dt-mutually-independent">mutually independent</a> as defined in
|
|
<a href="#expr-parallel-branches"><i>18.4.4.2 Analyzing parallel
|
|
branches</i></a>.<span class="definition">]</span></p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e31742" id=
|
|
"d7e31742"></a>Example: Conditional branches</div>
|
|
<p>Consider the template</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:template name="t">
|
|
<xsl:choose>
|
|
<xsl:when test="@code=23>
|
|
<xsl:sequence select="firstName"/>
|
|
</xsl:when>
|
|
<xsl:when test="@code=24>
|
|
<xsl:sequence select="lastName"/>
|
|
</xsl:when>
|
|
<xsl:when test="@code=if (@married) then 31 else 32">
|
|
<xsl:sequence select="formerName"/>
|
|
</xsl:when>
|
|
<xsl:otherwise>
|
|
<xsl:sequence select="concat(firstName, lastName)"/>
|
|
</xsl:otherwise>
|
|
</xsl:choose>
|
|
</xsl:template>
|
|
|
|
</pre></div>
|
|
<p>The combined expression tree and data flow graph for this
|
|
template is shown below. (To avoid complicating the diagram
|
|
unnecessarily, data flows from the <a href=
|
|
"#element-sequence"><code>xsl:sequence</code></a> instructions back
|
|
via the if/then/else expressions to the root e-node labeled
|
|
<a href="#element-template"><code>xsl:template</code></a> are not
|
|
shown.)</p>
|
|
<object type="image/svg+xml" codetype="image/svg+xml" data=
|
|
"img/fig6.svg" width="800" height="800"><span style=
|
|
"background-color:#FFFF20;padding-top:1pt;padding-bottom:1pt;">This
|
|
browser can't display the SVG file img/fig6.svg. Please upgrade
|
|
your browser or install the Adobe SVG Viewer.</span></object>
|
|
<p>Later, the streamability analysis will test whether there are
|
|
two paths starting at the <a href=
|
|
"#element-template"><code>xsl:template</code></a> that both contain
|
|
downward selections and are not mutually exclusive. In fact there
|
|
are five paths here that contain a downward selection (all those to
|
|
e-nodes that use the child axis), and they are all mutually
|
|
exclusive except those that include the two subexpressions of the
|
|
<code>concat()</code> node. In consequence, this template is not
|
|
<a title="guaranteed-streamable" class="termref" href=
|
|
"#dt-guaranteed-streamable">guaranteed-streamable</a>.</p>
|
|
</div>
|
|
</div>
|
|
<div class="div4">
|
|
<h5><a name="expr-parallel-branches" id=
|
|
"expr-parallel-branches"></a>18.4.4.2 <a href=
|
|
"#expr-parallel-branches" style="text-decoration: none">Analyzing
|
|
parallel branches</a></h5>
|
|
<p>When the <a href="#element-fork"><code>xsl:fork</code></a>
|
|
instruction is used, instructions within its sequence constructor
|
|
can be evaluated in parallel, during a single pass of the streamed
|
|
input document.</p>
|
|
<p>Recall that two instructions directly contained within an
|
|
<a href="#element-fork"><code>xsl:fork</code></a> instruction are
|
|
defined to be <b>independent</b> if neither is dependent on the
|
|
other (that is, in all cases except where one instruction binds a
|
|
variable that is used by the other). Extending this concept:</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-mutually-independent" id="dt-mutually-independent" title=
|
|
"mutually independent"></a>Two e-nodes are <b>mutually
|
|
independent</b> if they share an e-node representing an <a href=
|
|
"#element-fork"><code>xsl:fork</code></a> instruction as a common
|
|
ancestor, and if they occur in separate subtrees rooted at
|
|
different children of the <a href=
|
|
"#element-fork"><code>xsl:fork</code></a> instruction, such that
|
|
neither subtree is dependent (directly or indirectly) on the value
|
|
of a variable bound by the other subtree.<span class=
|
|
"definition">]</span></p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>From the point of view of streamability analysis, e-nodes that
|
|
are <a title="mutually independent" class="termref" href=
|
|
"#dt-mutually-independent">mutually independent</a> are treated in
|
|
the same way as those that are <a title="mutually exclusive" class=
|
|
"termref" href="#dt-mutually-exclusive">mutually exclusive</a>
|
|
because they occur in different branches of a conditional.</p>
|
|
</div>
|
|
</div>
|
|
<div class="div4">
|
|
<h5><a name="expr-tree-loops" id="expr-tree-loops"></a>18.4.4.3
|
|
<a href="#expr-tree-loops" style="text-decoration: none">Analyzing
|
|
looping constructs</a></h5>
|
|
<p>It is necessary to identify constructs that are evaluated
|
|
repeatedly, in the sense that when their parent construct is
|
|
evaluated, the child construct is evaluated more than once. This is
|
|
because a streamable construct is only allowed to traverse the
|
|
children of a node once. For example, the expression <code>for $a
|
|
in 1 to 5 return child::*</code> is not streamable: it performs
|
|
multiple traversals of the children of the context node even though
|
|
there is only a single subexpression that does downwards
|
|
navigation.</p>
|
|
<p>A number of constructs are recognized as looping constructs, in
|
|
that they cause one of their sub-constructs to be evaluated more
|
|
than once, with differences in the dynamic context (either a
|
|
different focus, or different variable values). In each case the
|
|
construct has one child construct whose evaluation returns a
|
|
sequence, which is evaluated once, and another child construct that
|
|
is evaluated repeatedly: we will refer to the first subconstruct as
|
|
the <em>controlling expression</em> and the second as the
|
|
<em>controlled expression</em>.</p>
|
|
<p>To analyze this situation, it is necessary to examine arcs in
|
|
the data flow graph that start on an e-node <var>S</var>
|
|
representing a construct that is outside a loop, and end on an
|
|
e-node <var>E</var> that is inside the loop. This is consistent
|
|
with streaming only where <var>S</var> is the controlling
|
|
expression for the loop.</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e31876" id=
|
|
"d7e31876"></a>Example: A streamable loop</div>
|
|
<p>Consider the construct</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:template match="department">
|
|
<xsl:for-each select="employee">
|
|
<a><xsl:value-of select="salary"/></a>
|
|
</xsl:for-each>
|
|
</xsl:template>
|
|
</pre></div>
|
|
<p>The expression tree and data flow graph for this construct are
|
|
shown below. (Again, the expansion of axis steps such as
|
|
<code>child::employee</code> to <code>./child::employee</code> has
|
|
been omitted.)</p>
|
|
<object type="image/svg+xml" codetype="image/svg+xml" data=
|
|
"img/fig7.svg"><span style=
|
|
"background-color:#FFFF20;padding-top:1pt;padding-bottom:1pt;">This
|
|
browser can't display the SVG file img/fig7.svg. Please upgrade
|
|
your browser or install the Adobe SVG Viewer.</span></object>
|
|
<p>This is streamable because the arcs from the <a href=
|
|
"#element-template"><code>xsl:template</code></a> e-node to the
|
|
e-node representing the <code>select</code> expression, and that
|
|
from the <code>select</code> expression into the body of the loop,
|
|
are both permitted under the rules below.</p>
|
|
</div>
|
|
<p> </p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e31917" id=
|
|
"d7e31917"></a>Example: A non-streamable loop</div>
|
|
<p>Consider the construct</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:template match="department">
|
|
<xsl:param name="required" select="()"/>
|
|
<a>
|
|
<xsl:value-of select="for $i in $required
|
|
return employee[@id=$i]/name"/>
|
|
</a>
|
|
</xsl:template>
|
|
</pre></div>
|
|
<p>The expression tree and data flow graph for this construct are
|
|
shown below.</p>
|
|
<object type="image/svg+xml" codetype="image/svg+xml" data=
|
|
"img/fig8.svg"><span style=
|
|
"background-color:#FFFF20;padding-top:1pt;padding-bottom:1pt;">This
|
|
browser can't display the SVG file img/fig8.svg. Please upgrade
|
|
your browser or install the Adobe SVG Viewer.</span></object>
|
|
<p>This is not streamable because the arc from the e-node
|
|
representing the <a href=
|
|
"#element-template"><code>xsl:template</code></a> to the e-node
|
|
representing the step <code>child::employee</code> crosses into the
|
|
loop in a way that is not allowed.</p>
|
|
</div>
|
|
<p>The looping constructs are listed in the table below.</p>
|
|
<table border="1" cellpadding="5">
|
|
<thead>
|
|
<tr>
|
|
<th colspan="1">Looping construct</th>
|
|
<th colspan="1">Controlling expression</th>
|
|
<th colspan="1">Controlled expression</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td><a href="#element-for-each"><code>xsl:for-each</code></a></td>
|
|
<td>the <code>select</code> expression</td>
|
|
<td>the contained sequence constructor; plus the
|
|
<code>select</code> expression of any child <code>xsl:sort</code>
|
|
elements</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href=
|
|
"#element-for-each-group"><code>xsl:for-each-group</code></a></td>
|
|
<td>the <code>select</code> expression</td>
|
|
<td>the contained sequence constructor; plus the
|
|
<code>group-by</code> and <code>group-adjacent</code> expressions,
|
|
and the <code>select</code> expression of any child
|
|
<code>xsl:sort</code> elements</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#element-iterate"><code>xsl:iterate</code></a></td>
|
|
<td>the <code>select</code> expression</td>
|
|
<td>the contained sequence constructor</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href=
|
|
"#element-analyze-string"><code>xsl:analyze-string</code></a></td>
|
|
<td>the <code>select</code> expression</td>
|
|
<td>the sequence constructors contained in the <a href=
|
|
"#element-matching-substring"><code>xsl:matching-substring</code></a>
|
|
and <a href=
|
|
"#element-non-matching-substring"><code>xsl:non-matching-substring</code></a>
|
|
children</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href=
|
|
"#element-merge-source"><code>xsl:merge-source</code></a></td>
|
|
<td>the <code>select</code> expression of the
|
|
<code>xsl:merge-source</code> element</td>
|
|
<td>the <code>select</code> expression of its <a href=
|
|
"#element-merge-input"><code>xsl:merge-input</code></a> child</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#element-merge"><code>xsl:merge</code></a></td>
|
|
<td>the <code>select</code> expressions of the
|
|
<code>xsl:merge-input</code> elements</td>
|
|
<td>the sequence constructor contained in the <a href=
|
|
"#element-merge-action"><code>xsl:merge-action</code></a> child;
|
|
plus the <code>select</code> expression of any child
|
|
<code>xsl:merge-key</code> elements</td>
|
|
</tr>
|
|
<tr>
|
|
<td>XPath <code>for</code> expression</td>
|
|
<td>the <code>in</code> expression</td>
|
|
<td>the <code>return</code> expression</td>
|
|
</tr>
|
|
<tr>
|
|
<td>XPath <code>some/every</code> expression</td>
|
|
<td>the <code>in</code> expression</td>
|
|
<td>the <code>satisfies</code> expression</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Path expression (<code>A/B</code>)</td>
|
|
<td>the first operand, <code>A</code></td>
|
|
<td>the second operand, <code>B</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>Filter expression (<code>A[B]</code>)</td>
|
|
<td>the sequence being filtered, <code>A</code></td>
|
|
<td>the predicate, <code>B</code></td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-repeating-arc" id="dt-repeating-arc" title=
|
|
"repeating arc"></a>An arc in the data flow graph is a <b>repeating
|
|
arc</b> if it ends at an <a title="e-node" class="termref" href=
|
|
"#dt-e-node">e-node</a> that is <span>within the subtree rooted
|
|
at</span> the e-node representing a <em>controlled expression</em>,
|
|
and starts at an e-node that is outside the tree rooted at the
|
|
corresponding <em>looping construct</em>.<span class=
|
|
"definition">]</span></p>
|
|
<p>When such an arc forms part of a path starting at a construct
|
|
whose streamability is being tested, it will cause the construct to
|
|
be deemed non-streamable. However, an arc from outside the looping
|
|
construct to the controlling expression, and an arc from the
|
|
controlling expression to the controlled expression, do not cause
|
|
non-streamability.</p>
|
|
<blockquote>
|
|
<p><b><a name="issue-data-flow-into-a-loop" id=
|
|
"issue-data-flow-into-a-loop">Issue 25
|
|
(data-flow-into-a-loop)</a>:</b></p>
|
|
<p>The rules prohibiting data flows into the body of a loop may be
|
|
stricter than is necessary: they are designed to prevent repeated
|
|
evaluation of a downward selection, but as written, they also
|
|
disallow motionless expressions such as <code>$var/@name</code> or
|
|
<code>name($var)</code></p>
|
|
</blockquote>
|
|
</div>
|
|
<div class="div4">
|
|
<h5><a name="expr-tree-sorting" id="expr-tree-sorting"></a>18.4.4.4
|
|
<a href="#expr-tree-sorting" style=
|
|
"text-decoration: none">Analyzing sorting constructs</a></h5>
|
|
<p>Where an expression sorts nodes from a streamed input document
|
|
into some order other than document order, the effect is to make
|
|
the code non-streamable. An example is an <a href=
|
|
"#element-for-each"><code>xsl:for-each</code></a> instruction
|
|
containing an <a href="#element-sort"><code>xsl:sort</code></a>
|
|
child element.</p>
|
|
<p>In building the expression tree <span>according to the rules in
|
|
<a href="#building-expression-tree"><i>18.4.1 Building an
|
|
Expression Tree</i></a></span>, a construct of the form:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:for-each select="IN">
|
|
<xsl:sort select="KEY"/>
|
|
<xsl:sequence select="OUT"/>
|
|
</xsl:for-each>
|
|
|
|
</pre></div>
|
|
<p>was rewritten to make the expression <code>IN</code> a
|
|
subexpression of an e-node representing the sorting operation, so
|
|
the expression tree is:</p>
|
|
<object type="image/svg+xml" codetype="image/svg+xml" data=
|
|
"img/fig9.svg"><span style=
|
|
"background-color:#FFFF20;padding-top:1pt;padding-bottom:1pt;">This
|
|
browser can't display the SVG file img/fig9.svg. Please upgrade
|
|
your browser or install the Adobe SVG Viewer.</span></object>
|
|
<p>If the subsequent analysis of the data flow graph reveals that
|
|
the expression <code>IN</code> contains nodes from the streamed
|
|
input, the presence of the <code>sort</code> e-node will result in
|
|
the entire construct being deemed non-streamable, because a sort
|
|
operation (in the worst case) needs to read all its input into
|
|
memory before it can produce any output. (If the sort operation is
|
|
sorting data from another source then this is not incompatible with
|
|
streaming: it may involve allocating memory, but the requirement to
|
|
stream the input document has been satisfied.)</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e32213" id=
|
|
"d7e32213"></a>Example: Non-streamable sorting</div>
|
|
<p>Consider the template rule</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:template match="department">
|
|
<xsl:for-each select="employee">
|
|
<xsl:sort select="@empNr"/>
|
|
<xsl:copy-of select="."/>
|
|
</xsl:for-each>
|
|
</xsl:template>
|
|
</pre></div>
|
|
<p>The expression tree and data flow graph for this template are
|
|
shown below:</p>
|
|
<object type="image/svg+xml" codetype="image/svg+xml" data=
|
|
"img/fig10.svg"><span style=
|
|
"background-color:#FFFF20;padding-top:1pt;padding-bottom:1pt;">This
|
|
browser can't display the SVG file img/fig10.svg. Please upgrade
|
|
your browser or install the Adobe SVG Viewer.</span></object>
|
|
<p>This template is not streamable, because the data flow graph
|
|
contains a <code>sort</code> construct on a path reachable from the
|
|
<a href="#element-template"><code>xsl:template</code></a>
|
|
construct.</p>
|
|
</div>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-reordering-construct" id="dt-reordering-construct" title=
|
|
"reordering construct"></a>Sorting is just one example of an
|
|
operation on a sequence whose output is not streamable with respect
|
|
to its input. In general we refer to any <a title="construct"
|
|
class="termref" href="#dt-construct">construct</a> that requires to
|
|
hold its entire input sequence in memory in order to compute its
|
|
result as a <b>reordering construct</b>.<span class=
|
|
"definition">]</span></p>
|
|
<p>The following is a complete list of constructs that are
|
|
classified as <a title="reordering construct" class="termref" href=
|
|
"#dt-reordering-construct">reordering constructs</a>:</p>
|
|
<ul>
|
|
<li>
|
|
<p>The <code>sort</code> e-node created on the expression tree for
|
|
any <a title="instruction" class="termref" href=
|
|
"#dt-instruction">instruction</a> having an <a href=
|
|
"#element-sort"><code>xsl:sort</code></a> element as a child.</p>
|
|
</li>
|
|
<li>
|
|
<p>The function <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-reverse"><code>reverse</code></a><sup><small>FO</small></sup></p>
|
|
</li>
|
|
<li>
|
|
<p>The function <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-last"><code>last</code></a><sup><small>FO</small></sup>
|
|
(see below)</p>
|
|
</li>
|
|
<li>
|
|
<p>the <code>xsl:for-each-group</code> instruction when used with a
|
|
<code>group-by</code> attribute</p>
|
|
</li>
|
|
</ul>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e32296" id=
|
|
"d7e32296"></a>Example: The <code>last</code> function</div>
|
|
<p>This example shows how the analysis is done for the <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-last"><code>last</code></a><sup><small>FO</small></sup>
|
|
function. As described in <a href=
|
|
"#tracing-context-path"><i>18.4.3.3 Tracing the Context of an
|
|
Expression</i></a>, this expression is considered to depend on the
|
|
context item, and therefore has an inward arc in the data flow
|
|
graph from the expression that sets the context item.</p>
|
|
<p>Consider the template rule</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:template match="department">
|
|
<xsl:for-each select="employee">
|
|
<xsl:if test="position() = last()">
|
|
<xsl:value-of select="surname"/>
|
|
</xsl:if>
|
|
</xsl:for-each>
|
|
</xsl:template>
|
|
</pre></div>
|
|
<p>The expression tree and data flow graph for this template are
|
|
shown below:</p>
|
|
<object type="image/svg+xml" codetype="image/svg+xml" data=
|
|
"img/fig11.svg"><span style=
|
|
"background-color:#FFFF20;padding-top:1pt;padding-bottom:1pt;">This
|
|
browser can't display the SVG file img/fig11.svg. Please upgrade
|
|
your browser or install the Adobe SVG Viewer.</span></object>
|
|
<p>This example is not streamable, because the reordering construct
|
|
<code>last()</code> is present on a data flow path starting at the
|
|
<a href="#element-template"><code>xsl:template</code></a>
|
|
construct.</p>
|
|
</div>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>Any expressions appearing in attribute value templates of the
|
|
<a href="#element-sort"><code>xsl:sort</code></a> element (for
|
|
example, the <code>collation</code> attribute) must be analyzed in
|
|
the usual way: the focus for these expressions is the same as the
|
|
focus for the <code>select</code> expression of the containing
|
|
instruction (for example, <a href=
|
|
"#element-for-each"><code>xsl:for-each</code></a>). Even if the
|
|
<code>select</code> expression does not force a streamability
|
|
problem by reordering the nodes in the streamed input, there is
|
|
potential for these additional attributes to disrupt streamability
|
|
by making downwards selections from a streamed input node.</p>
|
|
</div>
|
|
</div>
|
|
<div class="div4">
|
|
<h5><a name="streamability-of-dynamic-invocation" id=
|
|
"streamability-of-dynamic-invocation"></a>18.4.4.5 <a href=
|
|
"#streamability-of-dynamic-invocation" style=
|
|
"text-decoration: none">Analyzing dynamic invocation</a></h5>
|
|
<p>A number of constructs cause invocation of a function, template,
|
|
or expression that cannot be identified statically. These
|
|
constructs include <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>,
|
|
<a href=
|
|
"#element-apply-imports"><code>xsl:apply-imports</code></a>,
|
|
<a href="#element-next-match"><code>xsl:next-match</code></a>,
|
|
<a href="#element-evaluate"><code>xsl:evaluate</code></a>, and
|
|
dynamic function invocations in XPath.</p>
|
|
<p>The instructions <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>,
|
|
<a href=
|
|
"#element-apply-imports"><code>xsl:apply-imports</code></a>, and
|
|
<a href="#element-next-match"><code>xsl:next-match</code></a> cause
|
|
a template to be invoked dynamically. There are two cases to
|
|
consider:</p>
|
|
<ul>
|
|
<li>
|
|
<p>If the invocation is in a streamable mode, then the called
|
|
template is guaranteed to be streamable, which means the caller can
|
|
reliably assume that the called template will only navigate within
|
|
the subtrees of the selected nodes. The effect of the called
|
|
template can therefore be simulated by adding the navigation step
|
|
<code>descendant-or-self::node()</code> to the nodes selected by
|
|
the <code>select</code> expression (in the case of <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>) or
|
|
the context item (in the case of <a href=
|
|
"#element-apply-imports"><code>xsl:apply-imports</code></a> and
|
|
<a href="#element-next-match"><code>xsl:next-match</code></a>)</p>
|
|
</li>
|
|
<li>
|
|
<p>If the invocation is in a non-streamable mode, then the caller
|
|
cannot make any assumptions about the navigation performed by the
|
|
called template. <span>This can be simulated by adding the
|
|
navigation step <code>X/preceding::*</code> to the nodes selected
|
|
by the <code>select</code> expression (in the case of <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>) or
|
|
the context item (in the case of <a href=
|
|
"#element-apply-imports"><code>xsl:apply-imports</code></a> and
|
|
<a href=
|
|
"#element-next-match"><code>xsl:next-match</code></a>).</span> If
|
|
the selected nodes are in the <a title="streamed document" class=
|
|
"termref" href="#dt-streamed-document">streamed document</a> this
|
|
will inevitably cause the construct to be deemed
|
|
non-streamable.</p>
|
|
</li>
|
|
</ul>
|
|
<p>Any <code>xsl:with-param</code> elements used within an <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>,
|
|
<a href=
|
|
"#element-apply-imports"><code>xsl:apply-imports</code></a>,
|
|
<a href="#element-next-match"><code>xsl:next-match</code></a>, or
|
|
<a href="#element-evaluate"><code>xsl:evaluate</code></a>
|
|
instruction, as well as the arguments to a dynamic function
|
|
invocation, are handled as follows: the initializing expression
|
|
<code>X</code> (the expression that evaluates the argument to be
|
|
passed) is replaced by <code>X/preceding::*</code>, reflecting the
|
|
ability of the called component to navigate anywhere within a tree
|
|
that contains nodes passed as parameter values, as well as the
|
|
<a title="atomize" class="termref" href=
|
|
"#dt-atomization">atomization</a> that may be performed in the
|
|
course of parameter passing.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>This expansion isn't needed if the type of the parameter value
|
|
is always atomic. However, this specification does not assume that
|
|
the processor is able to perform static type inferencing. If the
|
|
parameter value is atomic, this expansion will do no harm as it
|
|
does not affect the path analysis.</p>
|
|
<p>The effect of this rule is that nodes within a streamed document
|
|
cannot be passed as parameters to a called template. This disallows
|
|
some cases that might be completely innocent, for example passing
|
|
an attribute node which the called template then atomizes. In
|
|
effect it is a pessimistic strategy: it disallows things that
|
|
cannot be determined statically to be safe. An alternative might be
|
|
to allow a more optimistic approach, in which it is permitted to
|
|
pass such a parameter, and a dynamic error is then signalled if the
|
|
called template uses it in an inappropriate way, for example by
|
|
navigating outside the subtree that is available when
|
|
streaming.</p>
|
|
</div>
|
|
<p>In the case of <a href=
|
|
"#element-evaluate"><code>xsl:evaluate</code></a>, the dynamically
|
|
invoked XPath expression can perform arbitrary navigation not only
|
|
from any nodes passed using <a href=
|
|
"#element-with-param"><code>xsl:with-param</code></a>, but also
|
|
from the context item. This is represented by adding the expression
|
|
<code>./preceding::*</code> as an additional subexpression on the
|
|
expression tree.</p>
|
|
</div>
|
|
<div class="div4">
|
|
<h5><a name="streamability-of-static-invocation" id=
|
|
"streamability-of-static-invocation"></a>18.4.4.6 <a href=
|
|
"#streamability-of-static-invocation" style=
|
|
"text-decoration: none">Analyzing calls to functions, templates,
|
|
and attribute sets</a></h5>
|
|
<p>Calls on <a title="stylesheet function" class="termref" href=
|
|
"#dt-stylesheet-function">stylesheet functions</a>, <a title=
|
|
"named template" class="termref" href="#dt-named-template">named
|
|
templates</a>, and <a title="attribute set" class="termref" href=
|
|
"#dt-attribute-set">attribute sets</a> can be resolved at this
|
|
stage: a data flow graph is constructed that combines the
|
|
navigation performed by the calling template or function with that
|
|
performed by its callee.</p>
|
|
<p>Parameters in a function call or in <a href=
|
|
"#element-call-template"><code>xsl:call-template</code></a> are
|
|
handled by creating an arc in the data flow graph from the
|
|
expression that sets the parameter (in the caller) to the variable
|
|
binding construct in the callee. The return value is represented by
|
|
an arc from the root e-node of the expression tree representing the
|
|
callee, to the e-node representing the function or template
|
|
invocation.</p>
|
|
<p>In the case of named templates and attribute sets, the context
|
|
item is passed implicitly, which is represented by (a) treating the
|
|
calling construct as one that has an intrinsic dependency on the
|
|
context item, and (b) creating an arc from the calling construct to
|
|
the root e-node of the callee. This is illustrated in the examples
|
|
below.</p>
|
|
<p>If an argument or parameter has a declared type that is atomic,
|
|
then the parameter passing may invoke atomization, which may
|
|
require navigation to descendant nodes. In this case an e-node
|
|
representing the step <code>descendant::text()</code> must be
|
|
inserted into the arc connecting the caller to the callee. It is
|
|
not necessary to represent atomization of the returned result in
|
|
the same way, because this operation will already be reflected in
|
|
the expression tree of the callee.</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e32503" id=
|
|
"d7e32503"></a>Example: Analyzing a function call</div>
|
|
<p>Consider a calling template and a called function as
|
|
follows:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:template match="employee">
|
|
<e><xsl:value-of select="f:salary(.)"/></e>
|
|
</xsl:template>
|
|
<xsl:function name="f:salary" as="xs:decimal">
|
|
<xsl:param name="emp" as="element(employee)"/>
|
|
<xsl:choose>
|
|
<xsl:when test="$emp/hourly-pay">
|
|
<xsl:sequence select="$emp/hourly-pay * 1924"/>
|
|
</xsl:when>
|
|
<xsl:otherwise>
|
|
<xsl:sequence select="$emp/annual-salary"/>
|
|
</xsl:otherwise>
|
|
</xsl:choose>
|
|
</xsl:function>
|
|
</pre></div>
|
|
<p>The two expression trees (one for the template, one for the
|
|
called function) are linked in the data flow graph as shown
|
|
below.</p>
|
|
<object type="image/svg+xml" codetype="image/svg+xml" data=
|
|
"img/fig12.svg" width="800" height="380"><span style=
|
|
"background-color:#FFFF20;padding-top:1pt;padding-bottom:1pt;">This
|
|
browser can't display the SVG file img/fig12.svg. Please upgrade
|
|
your browser or install the Adobe SVG Viewer.</span></object>
|
|
<p>Analysis of the data flow graph will show that the template is
|
|
not streamable. There are three paths originating at the <a href=
|
|
"#element-template"><code>xsl:template</code></a> e-node that make
|
|
downward selections and are not mutually exclusive (two select
|
|
<code>$emp/hourly-pay</code>, one selects
|
|
<code>$emp/annual-salary)</code>. Two of these are <a title=
|
|
"mutually exclusive" class="termref" href=
|
|
"#dt-mutually-exclusive">mutually exclusive</a>, but the third is
|
|
not. If the properties of the employee were held in attributes
|
|
rather than child elements, however, the template would be
|
|
streamable.</p>
|
|
</div>
|
|
<p>Note that a data flow graph needs to be constructed
|
|
independently for each supposedly streamable template. Constructing
|
|
a global data flow graph could create spurious paths that affect
|
|
the analysis.</p>
|
|
<p>Where there are several calls to the same function, the paths in
|
|
the data flow graph from the root <a href=
|
|
"#element-template"><code>xsl:template</code></a> e-node will no
|
|
longer form a tree (paths may converge); and where a function or
|
|
template is recursive, the graph may contain cycles. This is not
|
|
necessarily incompatible with the template being streamable.</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e32576" id=
|
|
"d7e32576"></a>Example: A streamable recursive template</div>
|
|
<p>This example shows a recursive function that counts how many
|
|
immediate ancestor <code>div</code> elements a given element has,
|
|
and a streamable template that calls this function.</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:template match="p" mode="streamable">
|
|
<out>Nesting depth: <xsl:value-of select="f:div-depth(.)"/></out>
|
|
</xsl:template>
|
|
|
|
<xsl:function name="f:nesting-depth" as="xs:integer">
|
|
<xsl:param name="this" as="element()"/>
|
|
<xsl:sequence select="if ($this/parent::div)
|
|
then 1 + f:nesting-depth($this/parent::div)
|
|
else 0"/>
|
|
</xsl:function>
|
|
</pre></div>
|
|
<p>The two expression trees (for the template and the function) are
|
|
shown in the diagram below, together with the data flow graph.</p>
|
|
<object type="image/svg+xml" codetype="image/svg+xml" data=
|
|
"img/fig13.svg"><span style=
|
|
"background-color:#FFFF20;padding-top:1pt;padding-bottom:1pt;">This
|
|
browser can't display the SVG file img/fig13.svg. Please upgrade
|
|
your browser or install the Adobe SVG Viewer.</span></object>
|
|
<p>Note the cycle from the <a href=
|
|
"#element-param"><code>xsl:param</code></a> element to the variable
|
|
reference <code>$this</code> used in the recursive function call,
|
|
to the <code>parent::div</code> step and then the containing path
|
|
expression. This cycle is not inconsistent with streamability,
|
|
because streamable code can make an indefinite number of upwards
|
|
steps (the ancestors of a node are always available). The fact that
|
|
there is only one axis step on this cycle reflects the fact that
|
|
each recursive invocation of the function moves one step up the
|
|
ancestor axis.</p>
|
|
</div>
|
|
</div>
|
|
<div class="div4">
|
|
<h5><a name="streamability-iterate" id=
|
|
"streamability-iterate"></a>18.4.4.7 <a href=
|
|
"#streamability-iterate" style="text-decoration: none">Analyzing
|
|
the streamability of</a> <a href=
|
|
"#element-iterate"><code>xsl:iterate</code></a></h5>
|
|
<p>The <a href="#element-iterate"><code>xsl:iterate</code></a>
|
|
instruction is a looping construct, and as such its analysis is
|
|
described in <a href="#expr-tree-loops"><i>18.4.4.3 Analyzing
|
|
looping constructs</i></a>.</p>
|
|
<p>In addition, in <a href=
|
|
"#element-iterate"><code>xsl:iterate</code></a> there is a data
|
|
flow from an <a href=
|
|
"#element-with-param"><code>xsl:with-param</code></a> element
|
|
within the <a href=
|
|
"#element-next-iteration"><code>xsl:next-iteration</code></a>
|
|
element, to the corresponding <a href=
|
|
"#element-param"><code>xsl:param</code></a> element. As with a
|
|
recursive function call, this causes cycles in the data flow graph,
|
|
but such cycles are not necessarily fatal to streamability.</p>
|
|
</div>
|
|
</div>
|
|
<div class="div3">
|
|
<h4><a name="streamability-conditions" id=
|
|
"streamability-conditions"></a>18.4.5 <a href=
|
|
"#streamability-conditions" style=
|
|
"text-decoration: none">Streamability Conditions</a></h4>
|
|
<p>The streamability of a construct <var>C</var> can be determined
|
|
by examining the paths in the data flow graph that emanate from the
|
|
<a title="e-node" class="termref" href="#dt-e-node">e-node</a>
|
|
representing <var>C</var> in the expression tree. A <em>path</em>
|
|
here is any sequence of arcs in the data flow graph. Note that
|
|
because the data flow graph may have cycles, a path can be infinite
|
|
(and there can also be an infinite number of paths). Paths that do
|
|
not start from <var>C</var> can be ignored.</p>
|
|
<p>A construct <var>C</var> is <a title="guaranteed-streamable"
|
|
class="termref" href=
|
|
"#dt-guaranteed-streamable">guaranteed-streamable</a> with respect
|
|
to its context item if the set of paths starting at <var>C</var> in
|
|
the data flow graph satisfies all the following conditions:</p>
|
|
<ol class="enumar">
|
|
<li>
|
|
<p>No path contains an <a title="e-node" class="termref" href=
|
|
"#dt-e-node">e-node</a> representing a sideways axis step
|
|
(following, preceding, following-sibling, or
|
|
preceding-sibling).</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>Although there might be streaming techniques that allow such
|
|
axes to be used, perhaps with the help of buffering, such
|
|
techniques are out of scope for this specification and code that
|
|
uses them is therefore not <a title="guaranteed-streamable" class=
|
|
"termref" href=
|
|
"#dt-guaranteed-streamable">guaranteed-streamable</a>.</p>
|
|
</div>
|
|
</li>
|
|
<li>
|
|
<p>No path contains an <a title="e-node" class="termref" href=
|
|
"#dt-e-node">e-node</a> representing an upwards axis step (parent,
|
|
ancestor, or ancestor-or-self) followed immediately or otherwise by
|
|
an <a title="e-node" class="termref" href="#dt-e-node">e-node</a>
|
|
representing a downward step (child, descendant, or
|
|
descendant-or-self).</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>The processing model for streaming used in this specification
|
|
assumes that while passing through a streamed document, the
|
|
processor will retain information about the ancestors of the node
|
|
at the current position of the stream, together with their
|
|
attributes. However, retaining information about the descendants of
|
|
these ancestors would be inconsistent with streaming. Therefore, it
|
|
is possible to navigate upwards to ancestors, but not downwards
|
|
from the ancestors to other parts of the document.</p>
|
|
</div>
|
|
</li>
|
|
<li>
|
|
<p>No path contains an <a title="e-node" class="termref" href=
|
|
"#dt-e-node">e-node</a> representing a descendant or
|
|
descendant-or-self axis step followed immediately or otherwise by
|
|
an <a title="e-node" class="termref" href="#dt-e-node">e-node</a>
|
|
representing a downward step (child, descendant, or
|
|
descendant-or-self).</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>For discussion of the reasons for this restriction and the
|
|
possible ways in which it might be relaxed, see <a href=
|
|
"#notes-on-descendant-axis-streamability"><i>18.4.6 Notes on the
|
|
streamability of paths using the descendant axis</i></a>.</p>
|
|
</div>
|
|
</li>
|
|
<li>
|
|
<p>Given any pair of paths <var>P</var> and <var>Q</var>, excluding
|
|
their <a title="common prefix" class="termref" href=
|
|
"#dt-common-prefix">common prefix</a> if any, every <a title=
|
|
"e-node" class="termref" href="#dt-e-node">e-node</a> in
|
|
<var>P</var> that represents a downward step (child, descendant, or
|
|
descendant-or-self) is <a title="mutually exclusive" class=
|
|
"termref" href="#dt-mutually-exclusive">mutually exclusive</a> with
|
|
every e-node representing a downward step in <var>Q</var>.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-common-prefix" id="dt-common-prefix" title=
|
|
"common prefix"></a>The <b>common prefix</b> of two paths in the
|
|
data flow graph contains the arcs that are present in both paths
|
|
before the paths diverge.<span class="definition">]</span></p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>This rule is trivially satisfied if <var>P</var> and
|
|
<var>Q</var> are the same path, or if one is a prefix of the other,
|
|
or if either <var>P</var> or <var>Q</var> contains no downward
|
|
selections.</p>
|
|
<p>So in practice it is only necessary to examine distinct paths
|
|
that contain one or more downward selections from the point at
|
|
which the paths diverge, and to check whether any downward
|
|
selections in one arm are mutually exclusive with the downward
|
|
selections in the other arm (that is, that they occur in different
|
|
branches of a conditional such as <a href=
|
|
"#element-choose"><code>xsl:choose</code></a>, or in independent
|
|
instructions within an <a href=
|
|
"#element-fork"><code>xsl:fork</code></a> instruction).</p>
|
|
<p>The rule reflects the fact that in streaming mode, the
|
|
descendants of a node can only be visited once. This rule therefore
|
|
imposes a static constraint on streamable constructs that they must
|
|
not make more than one downward selection, unless those downward
|
|
selections are in mutually exclusive branches of a conditional, so
|
|
that only one of them will ever be evaluated, or in independent
|
|
branches of an <a href="#element-fork"><code>xsl:fork</code></a>
|
|
instruction, so that they are evaluated during a single pass of the
|
|
input document.</p>
|
|
</div>
|
|
</li>
|
|
<li>
|
|
<p>No path contains a <a title="repeating arc" class="termref"
|
|
href="#dt-repeating-arc">repeating arc</a>. (See <a href=
|
|
"#expr-tree-loops"><i>18.4.4.3 Analyzing looping
|
|
constructs</i></a>.)</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>This complements the previous rule, by stating that if there is
|
|
a downward selection to access descendants of a node, it must not
|
|
occur in a loop where it can be executed more than once.</p>
|
|
</div>
|
|
</li>
|
|
<li>
|
|
<p>No path contains an <a title="e-node" class="termref" href=
|
|
"#dt-e-node">e-node</a> representing a <a title=
|
|
"reordering construct" class="termref" href=
|
|
"#dt-reordering-construct">reordering construct</a>. (See <a href=
|
|
"#expr-tree-sorting"><i>18.4.4.4 Analyzing sorting
|
|
constructs</i></a>.)</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>Examples of <a title="reordering construct" class="termref"
|
|
href="#dt-reordering-construct">reordering constructs</a> are the
|
|
<code>sort</code> node added to the expression tree in response to
|
|
an <a href="#element-sort"><code>xsl:sort</code></a> child of
|
|
<a href="#element-for-each"><code>xsl:for-each</code></a> or
|
|
<a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>, or
|
|
a call on the functions <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-reverse"><code>reverse</code></a><sup><small>FO</small></sup>
|
|
or <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-last"><code>last</code></a><sup><small>FO</small></sup>.
|
|
These constructs have the characteristic that they need to read
|
|
their full input sequence before producing any output, which is
|
|
clearly incompatible with streaming.</p>
|
|
</div>
|
|
</li>
|
|
<li>
|
|
<p>No non-empty path returns to the <a title="e-node" class=
|
|
"termref" href="#dt-e-node">e-node</a> representing the starting
|
|
construct <var>C</var>.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>Such a path would indicate that the supposedly streamable
|
|
construct is capable of returning (as all or part of its result) a
|
|
node from the streamed input document. In general this is not
|
|
allowed, because there is no way of analyzing what the caller
|
|
attempts to do with the returned node, and in particular, no way of
|
|
determining that what it does is compatible with streaming. This
|
|
restriction is particularly necessary when the construct being
|
|
analyzed is a <a title="template rule" class="termref" href=
|
|
"#dt-template-rule">template rule</a>, because each template rule
|
|
in a streamable mode is analyzed independently of the others.</p>
|
|
<p>It might be possible to relax the rule in the case of the
|
|
<a href="#element-stream"><code>xsl:stream</code></a> instruction,
|
|
where there is more scope to pursue the analysis beyond the
|
|
instruction itself.</p>
|
|
</div>
|
|
</li>
|
|
</ol>
|
|
<p>The above rules establish that a <a title="construct" class=
|
|
"termref" href="#dt-construct">construct</a> can be evaluated
|
|
<span>using <a title="streaming" class="termref" href=
|
|
"#dt-streaming">streaming</a></span> with respect to a given
|
|
context node; in the case of an element node this will typically
|
|
involve reading the input stream from the start tag of the element
|
|
until the end tag of the same element. For some situations, notably
|
|
evaluation of <a title="pattern" class="termref" href=
|
|
"#dt-pattern">patterns</a>, a stronger test is required: the
|
|
construct must be evaluated while the stream is positioned at the
|
|
start tag, and without changing the position of the input stream.
|
|
This is achieved by the definition that follows.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-motionless" id="dt-motionless" title="motionless"></a>A
|
|
construct <var>C</var> is <b>motionless</b> with respect to its
|
|
context item if (a) it is <a title="guaranteed-streamable" class=
|
|
"termref" href=
|
|
"#dt-guaranteed-streamable">guaranteed-streamable</a> with respect
|
|
to its context item (as defined above), and (b) in the set of paths
|
|
starting at <var>C</var> in the data flow graph, no path contains a
|
|
downward step (child, descendant, or
|
|
descendant-or-self).<span class="definition">]</span></p>
|
|
</div>
|
|
<div class="div3">
|
|
<h4><a name="notes-on-descendant-axis-streamability" id=
|
|
"notes-on-descendant-axis-streamability"></a>18.4.6 <a href=
|
|
"#notes-on-descendant-axis-streamability" style=
|
|
"text-decoration: none">Notes on the streamability of paths using
|
|
the descendant axis</a></h4>
|
|
<p><em>This section is a commentary describing future work; it will
|
|
not form part of the final specification.</em></p>
|
|
<blockquote>
|
|
<p><b><a name="issue-descendant-then-child" id=
|
|
"issue-descendant-then-child">Issue 26
|
|
(descendant-then-child)</a>:</b></p>
|
|
<p>The restriction that a path such as <code>.//section/head</code>
|
|
is non-streamable is too severe; it needs to be relaxed.</p>
|
|
</blockquote>
|
|
<p>In the analysis given in the previous section, a path containing
|
|
a descendant step followed by a child step is deemed
|
|
non-streamable. For example, this applies to the path expression
|
|
<code>.//section/head</code>. In fact, it even applies to the path
|
|
expression <code>.//employee</code>, because this is merely an
|
|
abbreviation for
|
|
<code>./descendant-or-self::node()/child::employee</code></p>
|
|
<p>This restriction is probably unacceptable. This section
|
|
discusses how it can be relaxed.</p>
|
|
<p>The reason for the restriction is that a nested-loop evaluation
|
|
of the expression is not guaranteed to return results in document
|
|
order. Consider for example the perverse case of a document where
|
|
the <code>head</code> element of a <code>section</code> appears at
|
|
the end:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<section nr="1">
|
|
<section nr="1.1">
|
|
<head>section 1.1</head>
|
|
</section>
|
|
<section nr="1.2">
|
|
<head>section 1.2</head>
|
|
</section>
|
|
<head>section 1</head>
|
|
</section>
|
|
</pre></div>
|
|
<p>While the instruction <code><xsl:value-of
|
|
select="//section/head"/></code> will output the headings in
|
|
document order as <code>"section 1.1 section 1.2 section 1"</code>,
|
|
the <a href="#element-for-each"><code>xsl:for-each</code></a>
|
|
instruction</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:for-each select="//section">
|
|
<xsl:value-of select="head"/>
|
|
</xsl:for-each>
|
|
</pre></div>
|
|
<p>will output them in "logical order" as <code>"section 1 section
|
|
1.1 section 1.2"</code> (ignoring whitespace). Here the output is
|
|
not in the same order as the input, so by definition the construct
|
|
is not fully streamable -- some kind of buffering is needed, either
|
|
of the input or the output.</p>
|
|
<p>There are several possible ways one could relax the rules to
|
|
make such expressions streamable.</p>
|
|
<ol class="enumar">
|
|
<li>
|
|
<p>One could make a distinction between path expressions (which
|
|
return results in document order) and nested loops such as <a href=
|
|
"#element-for-each"><code>xsl:for-each</code></a> (which do
|
|
not).</p>
|
|
<p>Currently the data flow graph makes no distinction between the
|
|
two cases: the data flow graph for the two cases is exactly the
|
|
same. We could modify the analysis so that the path
|
|
<code>.//section/head</code> is treated effectively as
|
|
<code>./descendant::head[parent::section]</code>, which is
|
|
<a title="guaranteed-streamable" class="termref" href=
|
|
"#dt-guaranteed-streamable">guaranteed-streamable</a> under the
|
|
current rules.</p>
|
|
</li>
|
|
<li>
|
|
<p>One could go further and make all downwards paths <a title=
|
|
"guaranteed-streamable" class="termref" href=
|
|
"#dt-guaranteed-streamable">guaranteed-streamable</a>, even if they
|
|
use nested-loop constructs such as <a href=
|
|
"#element-for-each"><code>xsl:for-each</code></a>. This has the
|
|
advantage that it would license the use of instructions such as
|
|
this:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:for-each select=".//employee">
|
|
<xsl:value-of select="emp-nr"/>
|
|
</xsl:for-each>
|
|
|
|
</pre></div>
|
|
<p>which most users would expect to be streamable, and which in
|
|
practice are streamable in nearly all commonly encountered cases.
|
|
There are then two ways one could deal with the unusual cases that
|
|
are not actually streamable (that is, the cases where the order of
|
|
the output is not the same as the order of the input):</p>
|
|
<ul>
|
|
<li>
|
|
<p>One could require the processor to perform buffering in this
|
|
situation, to achieve the necessary reordering of the output (note
|
|
that no buffering is needed unless the structure is actually
|
|
recursive, that is, the descendant axis actually selects a node
|
|
that is a descendant of another selected node)</p>
|
|
<p>An existing implementation has shown that this is a feasible
|
|
approach; but it does have the disadvantage that the worst-case
|
|
memory requirement is unpredictable.</p>
|
|
</li>
|
|
<li>
|
|
<p>One could require the processor to signal a dynamic error in
|
|
this case.</p>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
<p>One could in principle make the rules schema-aware, so that the
|
|
expression <code>.//employee</code> becomes <a title=
|
|
"guaranteed-streamable" class="termref" href=
|
|
"#dt-guaranteed-streamable">guaranteed-streamable</a> if the schema
|
|
indicates that an <code>employee</code> element cannot contain
|
|
another <code>employee</code> element. However, doing this in an
|
|
interoperable way would require a complete definition of the static
|
|
type inferencing rules, which is a major undertaking; it would also
|
|
require users to write schema-aware stylesheets, which for many
|
|
would be a major change from current practice.</p>
|
|
</li>
|
|
<li>
|
|
<p>One could make the <code>for</code> expression streamable only
|
|
in the case where the <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-unordered"><code>unordered</code></a><sup><small>FO</small></sup>
|
|
function has been used to relax the ordering rules, by writing
|
|
<code>for $s in unordered(//section) return
|
|
$s/last-changed</code></p>
|
|
</li>
|
|
</ol>
|
|
<p>In the meantime, note that the <a href=
|
|
"#function-outermost"><code>outermost</code></a> function is
|
|
provided to enable paths that are potentially recursive to be
|
|
declared, in effect, as selecting non-nested nodes, which
|
|
guarantees the streamability of an expression that uses this
|
|
function (though this has not yet been factored into the
|
|
streamability rules).</p>
|
|
</div>
|
|
<div class="div3">
|
|
<h4><a name="streamability-examples" id=
|
|
"streamability-examples"></a>18.4.7 <a href=
|
|
"#streamability-examples" style="text-decoration: none">Examples of
|
|
streamability analysis</a></h4>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e33006" id=
|
|
"d7e33006"></a>Example: Analysis of an <code>xsl:stream</code>
|
|
instruction using <code>xsl:iterate</code></div>
|
|
<p>Consider the following instruction:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:stream href="transactions.xml">
|
|
<xsl:iterate select="account/transaction">
|
|
<xsl:param name="balance" select="0.00" as="xs:decimal"/>
|
|
<xsl:variable name="newBalance" select="$balance + xs:decimal(@value)"/>
|
|
<balance date="{@date}" value="{$newBalance}"/>
|
|
<xsl:next-iteration>
|
|
<xsl:with-param name="balance" select="$newBalance"/>
|
|
</xsl:next-iteration>
|
|
</xsl:iterate>
|
|
</xsl:stream>
|
|
</pre></div>
|
|
<p>The expression tree for this and data flow graph for this
|
|
construct are shown below.</p>
|
|
<p>Some simplifying assumptions have been made in creating this
|
|
graph. No data flow arcs are shown for values that are known to be
|
|
atomic, such as the variables <code>$balance</code> and
|
|
<code>$newBalance</code>, because these can never affect the
|
|
streamability analysis. Equally, no <code>descendant-or-self</code>
|
|
steps have been added to reflect atomization of nodes that are
|
|
known to be attributes.</p>
|
|
<object type="image/svg+xml" codetype="image/svg+xml" data=
|
|
"img/fig14.svg" width="800" height="300"><span style=
|
|
"background-color:#FFFF20;padding-top:1pt;padding-bottom:1pt;">This
|
|
browser can't display the SVG file img/fig14.svg. Please upgrade
|
|
your browser or install the Adobe SVG Viewer.</span></object>
|
|
<p>The data flow graph can be seen more clearly by showing only the
|
|
data flow paths starting from the <a href=
|
|
"#element-stream"><code>xsl:stream</code></a> instruction and the
|
|
e-nodes they connect (these arcs are shown in red on the previous
|
|
diagram):</p>
|
|
<object type="image/svg+xml" codetype="image/svg+xml" data=
|
|
"img/fig15.svg"><span style=
|
|
"background-color:#FFFF20;padding-top:1pt;padding-bottom:1pt;">This
|
|
browser can't display the SVG file img/fig15.svg. Please upgrade
|
|
your browser or install the Adobe SVG Viewer.</span></object>
|
|
<p>There are thus two navigation paths emanating from the <a href=
|
|
"#element-stream"><code>xsl:stream</code></a> instruction, both of
|
|
the form <code>child/child/attribute</code>. All the conditions for
|
|
streamability are satisfied, so the <a href=
|
|
"#element-stream"><code>xsl:stream</code></a> construct is
|
|
<a title="guaranteed-streamable" class="termref" href=
|
|
"#dt-guaranteed-streamable">guaranteed-streamable</a>.</p>
|
|
</div>
|
|
<p> </p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e33088" id=
|
|
"d7e33088"></a>Example: Analysis of a template rule including a
|
|
choice</div>
|
|
<p>In this example we assume that mode <code>M</code> has been
|
|
declared to be a <a title="streamable mode" class="termref" href=
|
|
"#dt-streamable-mode">streamable mode</a>, so we need to check that
|
|
the template rule is streamable.</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:template match="para" mode="M">
|
|
<xsl:choose>
|
|
<xsl:when test="ancestor::para">
|
|
<span>
|
|
<xsl:apply-templates mode="M"/>
|
|
</span>
|
|
</xsl:when>
|
|
<xsl:otherwise>
|
|
<p>
|
|
<xsl:apply-templates mode="M"/>
|
|
</p>
|
|
</xsl:otherwise>
|
|
</xsl:choose>
|
|
</xsl:template>
|
|
</pre></div>
|
|
<p>The resulting expression tree and data flow graph are shown
|
|
below.</p>
|
|
<p>The expression tree has been extended with
|
|
<code>descendant-or-self</code> steps in four places:</p>
|
|
<ul>
|
|
<li>
|
|
<p>Both calls of <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>
|
|
appear in the content of <a title="literal result element" class=
|
|
"termref" href="#dt-literal-result-element">literal result
|
|
elements</a>. This means that in constructing the parent element,
|
|
the value returned by the <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>
|
|
instruction will be copied. Copying navigates to all the descendant
|
|
nodes, so a <code>descendant-or-self</code> step is added to
|
|
reflect this.</p>
|
|
</li>
|
|
<li>
|
|
<p>Both calls of <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a> are
|
|
invoking a template in a streamable mode, and can therefore assume
|
|
that the template being invoked follows the rules for streamable
|
|
templates. Such templates must be assumed to process the subtree
|
|
under the selected nodes, which is reflected by adding a
|
|
<code>descendant-or-self</code> step to the <code>select</code>
|
|
expression. (The <code>child::node()</code> step that represents
|
|
the default value of the <code>select</code> attribute has also
|
|
been made explicit.)</p>
|
|
</li>
|
|
</ul>
|
|
<object type="image/svg+xml" codetype="image/svg+xml" data=
|
|
"img/fig16.svg" width="800" height="430"><span style=
|
|
"background-color:#FFFF20;padding-top:1pt;padding-bottom:1pt;">This
|
|
browser can't display the SVG file img/fig16.svg. Please upgrade
|
|
your browser or install the Adobe SVG Viewer.</span></object>
|
|
<p>The data flow paths emanating from the <a href=
|
|
"#element-template"><code>xsl:template</code></a> construct can be
|
|
seen more clearly if everything else is removed:</p>
|
|
<object type="image/svg+xml" codetype="image/svg+xml" data=
|
|
"img/fig17.svg"><span style=
|
|
"background-color:#FFFF20;padding-top:1pt;padding-bottom:1pt;">This
|
|
browser can't display the SVG file img/fig17.svg. Please upgrade
|
|
your browser or install the Adobe SVG Viewer.</span></object>
|
|
<p>At first sight, this violates the rule that there must be only
|
|
one path that makes a downward selection. However, closer
|
|
examination shows that the two paths are mutually exclusive because
|
|
they occur in different branches of a conditional instruction. The
|
|
template is therefore <a title="guaranteed-streamable" class=
|
|
"termref" href=
|
|
"#dt-guaranteed-streamable">guaranteed-streamable</a>.</p>
|
|
</div>
|
|
<p> </p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e33194" id=
|
|
"d7e33194"></a>Example: A non-streamable example using local
|
|
variables</div>
|
|
<p>This example attempts to select all the transactions in a
|
|
banking file where the amount exceeds $1000 and the bank branch is
|
|
Skipton.</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:stream href="transactions.xml">
|
|
<xsl:for-each select="account/transaction">
|
|
<xsl:variable name="branch"
|
|
select="doc('branches.xml')/descendant::branch
|
|
[code = current()/branchCode]"/>
|
|
<xsl:copy-of
|
|
select=".[amount gt 1000.00 and $branch/name eq 'Skipton']"/>
|
|
</xsl:for-each>
|
|
</xsl:stream>
|
|
</pre></div>
|
|
<p>The raw expression tree for the <a href=
|
|
"#element-stream"><code>xsl:stream</code></a> instruction is like
|
|
this:</p>
|
|
<object type="image/svg+xml" codetype="image/svg+xml" data=
|
|
"img/fig18.svg" width="800" height="420"><span style=
|
|
"background-color:#FFFF20;padding-top:1pt;padding-bottom:1pt;">This
|
|
browser can't display the SVG file img/fig18.svg. Please upgrade
|
|
your browser or install the Adobe SVG Viewer.</span></object>
|
|
<p>This tree must first be expanded to include the effects of
|
|
atomization. The result of <code>child::code</code> is atomized,
|
|
because it is an argument to a comparison operator. The same
|
|
applies to <code>child::branch</code>, <code>child::amount</code>,
|
|
and <code>child::name</code>. All these expressions therefore have
|
|
an implicit <code>descendant-or-self::node()</code> added to them.
|
|
In addition, the <a href=
|
|
"#element-copy-of"><code>xsl:copy-of</code></a> instruction also
|
|
accesses all the descendant nodes of the node being copied, so this
|
|
results in another implicit <code>descendant-or-self::node()</code>
|
|
bing added to the tree.</p>
|
|
<p>After adding these nodes, and tracing the use of variables and
|
|
context, the expression tree and its data flow graph look like
|
|
this. For space reasons, the
|
|
<code>descendant-or-self::node()</code> e-nodes are labelled
|
|
"//"</p>
|
|
<object type="image/svg+xml" codetype="image/svg+xml" data=
|
|
"img/fig19.svg" width="800" height="500"><span style=
|
|
"background-color:#FFFF20;padding-top:1pt;padding-bottom:1pt;">This
|
|
browser can't display the SVG file img/fig19.svg. Please upgrade
|
|
your browser or install the Adobe SVG Viewer.</span></object>
|
|
<p>The paths emanating from the root e-node (the <a href=
|
|
"#element-stream"><code>xsl:stream</code></a> instruction) can be
|
|
seen on the simplified diagram:</p>
|
|
<object type="image/svg+xml" codetype="image/svg+xml" data=
|
|
"img/fig20.svg"><span style=
|
|
"background-color:#FFFF20;padding-top:1pt;padding-bottom:1pt;">This
|
|
browser can't display the SVG file img/fig20.svg. Please upgrade
|
|
your browser or install the Adobe SVG Viewer.</span></object>
|
|
<p>In this tree there are three paths in which
|
|
<code>child::transaction</code> is followed by a downward
|
|
selection. The construct is therefore not streamable, and the
|
|
processor must report a static error.</p>
|
|
<p>The code can be made streamable by including a call to the
|
|
<a href="#function-copy-of"><code>copy-of</code></a> function,
|
|
thus:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:stream href="transactions.xml">
|
|
<xsl:for-each select="account/transaction/copy-of()">
|
|
<xsl:variable name="branch"
|
|
select="doc('branches.xml')//branch[code = current()/branchCode]"/>
|
|
<xsl:copy-of select=".[amount gt 1000.00 and $branch/name eq 'Skipton']"/>
|
|
</xsl:for-each>
|
|
</xsl:stream>
|
|
</pre></div>
|
|
<p>The effect of this on the path analysis is that all the three
|
|
selections that previously depended on
|
|
<code>child::transaction</code> now depend on the result of the
|
|
<code>copy-of()</code> call. This always returns newly constructed
|
|
nodes, so these dependencies no longer lead back to the <a href=
|
|
"#element-stream"><code>xsl:stream</code></a> instruction, and can
|
|
therefore be excluded from the path map.</p>
|
|
</div>
|
|
</div>
|
|
<div class="div3">
|
|
<h4><a name="streamability-analysis-notes" id=
|
|
"streamability-analysis-notes"></a>18.4.8 <a href=
|
|
"#streamability-analysis-notes" style="text-decoration: none">Notes
|
|
on the streamability algorithm</a></h4>
|
|
<p>The algorithm for creating a path map representing the axes of
|
|
navigation through a source document is inspired by the algorithms
|
|
used for document projection in <a href="#marian-simeon">[Marian
|
|
& Siméon]</a>.</p>
|
|
<p>There are a number of differences, however:</p>
|
|
<ol class="enumar">
|
|
<li>
|
|
<p>The algorithm published by Marian and Siméon is for XQuery
|
|
rather than XSLT. Moreover, it is for a core subset of XQuery,
|
|
since the authors were able to build on previous work showing that
|
|
XQuery, already a smaller language than XSLT, could be reduced to
|
|
an even smaller core. The analysis for XSLT is inevitably more
|
|
complex because of the need to handle dynamic template invocation.
|
|
However, a practical implementation could simplify the expression
|
|
tree very substantially before analysis starts, since much of the
|
|
information on the tree makes no contribution to the analysis.</p>
|
|
</li>
|
|
<li>
|
|
<p>Marian and Siméon analyze the paths followed by a query in order
|
|
to determine which parts of the input tree are reachable. This
|
|
means, for example, that duplicate paths can be eliminated, and
|
|
that it makes no difference whether two paths are mutually
|
|
exclusive. For streamability analysis, multiple instances of
|
|
navigation to the same place are significant, and it is also
|
|
necessary to consider the paths as a tree, not simply as a set of
|
|
independent paths from the root to the leaves.</p>
|
|
</li>
|
|
</ol>
|
|
</div>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="copy-of-function" id="copy-of-function"></a>18.5
|
|
<a href="#copy-of-function" style="text-decoration: none">The
|
|
copy-of function</a></h3>
|
|
<a name="function-copy-of" id="function-copy-of"></a>
|
|
<div class="proto"><code class=
|
|
"function">copy-of</code>()<code class=
|
|
"as"> as </code><code class=
|
|
"return-type">node()</code></div>
|
|
<div class="proto"><code class=
|
|
"function">copy-of</code>(<code class=
|
|
"arg">$node</code><code class="as"> as </code><code class="type">node()?</code>)<code class="as"> as </code><code class="return-type">node()?</code></div>
|
|
<p>The zero-argument form of this function has the same effect as
|
|
calling <code>copy-of(.)</code>, that is, supplying the context
|
|
item as an implicit argument.</p>
|
|
<p>The function returns a deep copy of the node supplied as the
|
|
argument <code>$node</code>. If the argument is an empty sequence,
|
|
the function returns an empty sequence. The effect is the same as
|
|
that of the <a href="#element-copy-of"><code>xsl:copy-of</code></a>
|
|
instruction with <code>copy-namespaces</code> set to
|
|
<code>yes</code> and <code>validation</code> set to
|
|
<code>preserve</code>.</p>
|
|
<p>If the function is called more than once with the same argument,
|
|
it is <a title="implementation-dependent" class="termref" href=
|
|
"#dt-implementation-dependent">implementation-dependent</a> whether
|
|
each call returns the same node, or whether multiple calls return
|
|
different nodes. That is, the result of the expression
|
|
<code>copy-of($X) is copy-of($X)</code> is <a title=
|
|
"implementation-dependent" class="termref" href=
|
|
"#dt-implementation-dependent">implementation-dependent</a>.</p>
|
|
<p>The <a href="#function-copy-of"><code>copy-of</code></a>
|
|
function is available for use (and is primarily intended for use)
|
|
when a source document is processed using streaming. It can also be
|
|
used when not streaming. The effect is to take a copy of the
|
|
subtree rooted at the current node, and to make this available as a
|
|
normal tree, that can be processed without any of the restrictions
|
|
that apply while streaming, for example only being able to process
|
|
children once. The copy, of course, does not include siblings or
|
|
ancestors of the context node, so any attempt to navigate to
|
|
siblings or ancestors will result in an empty sequence being
|
|
returned.</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e33448" id=
|
|
"d7e33448"></a>Example: Using <code>copy-of()</code> while
|
|
streaming</div>
|
|
<p>This example copies from the source document all employees who
|
|
work in marketing and are based in Dubai. Because there are two
|
|
accesses using the child axis, it is not possible to do this
|
|
without buffering each employee in memory, which can be achieved
|
|
using the <a href="#function-copy-of"><code>copy-of</code></a>
|
|
function.</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:stream href="employees.xml">
|
|
<xsl:sequence select="employees/employee/copy-of()
|
|
[department='Marketing' and location='Dubai']"/>
|
|
</xsl:stream>
|
|
</pre></div>
|
|
</div>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="snapshot" id="snapshot"></a>18.6 <a href="#snapshot"
|
|
style="text-decoration: none">The snapshot function</a></h3>
|
|
<a name="function-snapshot" id="function-snapshot"></a>
|
|
<div class="proto"><code class=
|
|
"function">snapshot</code>()<code class=
|
|
"as"> as </code><code class=
|
|
"return-type">node()</code></div>
|
|
<div class="proto"><code class=
|
|
"function">snapshot</code>(<code class=
|
|
"arg">$node</code><code class=
|
|
"as"> as </code><code class="type">node()?</code>)<code class="as"> as </code><code class="return-type">node()?</code></div>
|
|
<p>The zero-argument form of this function has the same effect as
|
|
calling <code>snapshot(.)</code>, that is, supplying the context
|
|
item as an implicit argument.</p>
|
|
<p>The function returns a <a title="snapshot" class="termref" href=
|
|
"#dt-snapshot">snapshot</a> of the node supplied as the argument
|
|
<code>$node</code>. If the argument is an empty sequence, the
|
|
function returns an empty sequence.</p>
|
|
<p>If the function is called more than once with the same argument,
|
|
it is <a title="implementation-dependent" class="termref" href=
|
|
"#dt-implementation-dependent">implementation-dependent</a> whether
|
|
each call returns the same node, or whether multiple calls return
|
|
different nodes. That is, the result of the expression
|
|
<code>snapshot($X) is snapshot($X)</code> is <a title=
|
|
"implementation-dependent" class="termref" href=
|
|
"#dt-implementation-dependent">implementation-dependent</a>.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-snapshot" id="dt-snapshot" title="snapshot"></a>A
|
|
<b>snapshot</b> of a node <var>N</var> is a deep copy of
|
|
<var>N</var>, as produced by the <a href=
|
|
"#element-copy-of"><code>xsl:copy-of</code></a> instruction with
|
|
<code>copy-namespaces</code> set to <code>yes</code> and
|
|
<code>validation</code> set to <code>preserve</code>, with the
|
|
additional property that for every ancestor of <var>N</var>, the
|
|
copy also has a corresponding ancestor whose name, node-kind, and
|
|
base URI are the same as the corresponding ancestor of
|
|
<var>N</var>, and that has copies of the attributes and namespaces
|
|
of the corresponding ancestor of <var>N</var>. But the ancestor has
|
|
a type annotation of <code>xs:anyType</code>, has the properties
|
|
<code>nilled</code>, <code>is-ID</code>, and <code>is-IDREF</code>
|
|
set to false, and has no children other than the child that is a
|
|
copy of <var>N</var> or one of its ancestors.<span class=
|
|
"definition">]</span></p>
|
|
<p>More formally, a <a title="snapshot" class="termref" href=
|
|
"#dt-snapshot">snapshot</a> of a node is the result of the
|
|
following function.</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:function name="fn:snapshot" as="node()?">
|
|
<xsl:param name="node" as="node()?"/>
|
|
<xsl:sequence select="f:parent-copy($node, $node/ancestor::node(), 1)"/>
|
|
</xsl:function>
|
|
|
|
<xsl:function name="f:parent-copy" as="node()?">
|
|
<xsl:param name="node" as="node()?"/>
|
|
<xsl:param name="ancestors" as="node()*"/>
|
|
<xsl:param name="level" as="xs:integer"/>
|
|
<xsl:choose>
|
|
<xsl:when test="empty($node)">
|
|
<xsl:sequence select="()"/>
|
|
</xsl:when>
|
|
<xsl:when test="empty($ancestors)">
|
|
<xsl:sequence select="$node/descendant-or-self::node()[$level]"/>
|
|
</xsl:when>
|
|
<xsl:otherwise>
|
|
<xsl:variable name="p" as="node()?">
|
|
<xsl:for-each select="$ancestors[last()]">
|
|
<xsl:copy validation="strip">
|
|
<xsl:copy-of select="@*" validation="preserve"/>
|
|
<xsl:copy-of select="$node" validation="preserve"/>
|
|
</xsl:copy>
|
|
</xsl:for-each>
|
|
</xsl:variable>
|
|
<xsl:sequence select="f:parent-copy($p,
|
|
$ancestors[position() lt last()], $level+1)"/>
|
|
</xsl:otherwise>
|
|
</xsl:choose>
|
|
</xsl:function>
|
|
</pre></div>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>The <code><xsl:when test="empty($ancestors)"></code>
|
|
branch of this code is a little obscure. At this stage
|
|
<code>$node</code> represents the root of a constructed tree that
|
|
includes copies of all the ancestors of the original node supplied
|
|
to the <a href="#function-snapshot"><code>snapshot</code></a>
|
|
function, together with that node and all its descendants. The
|
|
result of the <a href=
|
|
"#function-snapshot"><code>snapshot</code></a> function is not
|
|
<code>$node</code> (the root of this constructed tree), but rather
|
|
the node within the constructed tree that corresponds to the
|
|
original node. This can be found by searching the descendants of
|
|
<code>$node</code>. In fact it is the node that is found
|
|
<code>$level</code> nodes below <code>$node</code>, which can be
|
|
selected as <code>$node/descendant-or-self::node()[$level]</code>
|
|
because each relevant node has exactly one child.</p>
|
|
</div>
|
|
<blockquote>
|
|
<p><b><a name="issue-snapshot-on-root-node" id=
|
|
"issue-snapshot-on-root-node">Issue 27
|
|
(snapshot-on-root-node)</a>:</b></p>
|
|
<p>The code given here is incorrect in the case where
|
|
<code>snapshot</code> is applied to a parentless node: it should
|
|
return a copy of the node, but actually returns the original.</p>
|
|
</blockquote>
|
|
<p>The <a href="#function-snapshot"><code>snapshot</code></a>
|
|
function is available for use (and is primarily intended for use)
|
|
when a source document is processed using streaming. It can also be
|
|
used when not streaming. The effect is to take a copy of the
|
|
subtree rooted at the current node, along with copies of the
|
|
ancestors and their attributes, and to make this available as a
|
|
normal tree, that can be processed without any of the restrictions
|
|
that apply while streaming, for example only being able to process
|
|
children once. The copy, of course, does not include siblings of
|
|
the context node or of its ancestors, so any attempt to navigate to
|
|
these siblings will result in an empty sequence being returned.</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e33596" id=
|
|
"d7e33596"></a>Example: Using <code>snapshot()</code> while
|
|
streaming</div>
|
|
<p>This example copies from the source document all employees who
|
|
work in marketing and are based in Dubai. It assumes that employees
|
|
are grouped by location. Because there are two accesses using the
|
|
child axis (referencing <code>department</code> and
|
|
<code>salary</code>), it is not possible to do this without
|
|
buffering each employee in memory. The <a href=
|
|
"#function-snapshot"><code>snapshot</code></a> function is used in
|
|
preference to the simpler <a href=
|
|
"#function-copy-of"><code>copy-of</code></a> so that access to
|
|
attributes of the parent <code>location</code> element remains
|
|
possible.</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:stream href="employees.xml">
|
|
<xsl:for-each select="locations/location[@name='Dubai']
|
|
/employee/snapshot()[department='Marketing']">
|
|
<employee>
|
|
<location code="{../@code}"/>
|
|
<salary value="{salary}"/>
|
|
</employee>
|
|
</xsl:for-each>
|
|
</xsl:stream>
|
|
</pre></div>
|
|
</div>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="outermost" id="outermost"></a>18.7 <a href=
|
|
"#outermost" style="text-decoration: none">The outermost
|
|
function</a></h3>
|
|
<a name="function-outermost" id="function-outermost"></a>
|
|
<div class="proto"><code class=
|
|
"function">outermost</code>(<code class=
|
|
"arg">$nodes</code><code class=
|
|
"as"> as </code><code class=
|
|
"type">node()*</code>)<code class=
|
|
"as"> as </code><code class=
|
|
"return-type">node()*</code></div>
|
|
<p>The <a href="#function-outermost"><code>outermost</code></a>
|
|
takes as input a sequence of nodes, and returns those nodes within
|
|
the sequence that have no ancestor that is itself a member of the
|
|
sequence; the nodes are returned in document order with duplicates
|
|
eliminated.</p>
|
|
<p>That is, the effect of the function is equivalent to the
|
|
expression:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
$nodes[not(ancestor::node() intersect $nodes)]
|
|
</pre></div>
|
|
<p>For example, the expression <code>outermost(//table)</code>
|
|
selects every <code>table</code> element that is not nested within
|
|
another <code>table</code> element.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>As noted in <a href=
|
|
"#notes-on-descendant-axis-streamability"><i>18.4.6 Notes on the
|
|
streamability of paths using the descendant axis</i></a>, path
|
|
expressions such as <code>.//section/head</code> cause a problem in
|
|
streamability analysis because there is no guarantee that a
|
|
nested-loop evaluation of the expression will deliver nodes in
|
|
document order. This is caused by the fact that
|
|
<code>section</code> elements can potentially contain further
|
|
<code>section</code> elements.</p>
|
|
<p>This is not the case for the expression
|
|
<code>outermost(.//section)/head</code>: for this expression, a
|
|
nested-loop evaluation strategy will return the nodes in document
|
|
order.</p>
|
|
<p>There are two situations in which the <a href=
|
|
"#function-outermost"><code>outermost</code></a> function can
|
|
potentially be useful. Firstly, if it is known that
|
|
<code>section</code> elements will never be nested, the expression
|
|
<code>outermost(.//section)</code> is equivalent to
|
|
<code>.//section</code>, but is more tractable in terms of its
|
|
streamability. Secondly, if the <code>section</code> elements are
|
|
nested, there may well be cases where only the outermost sections
|
|
are to be processed.</p>
|
|
<blockquote>
|
|
<p><b><a name="issue-streamability-of-outermost" id=
|
|
"issue-streamability-of-outermost">Issue 28
|
|
(streamability-of-outermost)</a>:</b></p>
|
|
<p>Note however that the streamability analysis as currently
|
|
written does not take calls on the <code>outermost</code> function
|
|
into account.</p>
|
|
</blockquote>
|
|
</div>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="innermost" id="innermost"></a>18.8 <a href=
|
|
"#innermost" style="text-decoration: none">The innermost
|
|
function</a></h3>
|
|
<a name="function-innermost" id="function-innermost"></a>
|
|
<div class="proto"><code class=
|
|
"function">innermost</code>(<code class=
|
|
"arg">$nodes</code><code class=
|
|
"as"> as </code><code class=
|
|
"type">node()*</code>)<code class=
|
|
"as"> as </code><code class=
|
|
"return-type">node()*</code></div>
|
|
<p>The <a href="#function-innermost"><code>innermost</code></a>
|
|
takes as input a sequence of nodes, and returns every node within
|
|
the sequence <span>that is not an ancestor of another node
|
|
within</span> the sequence; the nodes are returned in document
|
|
order with duplicates eliminated.</p>
|
|
<p>That is, the effect of the function is equivalent to the
|
|
expression:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
$nodes except $nodes/ancestor::node()
|
|
</pre></div>
|
|
<p>For example, the expression <code>innermost(//table)</code>
|
|
selects every <code>table</code> element that does not contain a
|
|
nested <code>table</code> element.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>Unlike the <a href=
|
|
"#function-outermost"><code>outermost</code></a> function, this
|
|
function does not help in making expressions streamable. It is
|
|
provided purely for symmetry.</p>
|
|
</div>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="has-children" id="has-children"></a>18.9 <a href=
|
|
"#has-children" style="text-decoration: none">The has-children
|
|
function</a></h3>
|
|
<a name="function-has-children" id="function-has-children"></a>
|
|
<div class="proto"><code class=
|
|
"function">has-children</code>()<code class=
|
|
"as"> as </code><code class=
|
|
"return-type">xs:boolean</code></div>
|
|
<p><em>To be specified.</em></p>
|
|
<blockquote>
|
|
<p><b><a name="issue-has-children" id="issue-has-children">Issue 29
|
|
(has-children)</a>:</b></p>
|
|
<p>The Working Group is considering defining a function
|
|
<code>has-children</code> which returns true if the context item
|
|
has one or more child nodes. This function would be defined as
|
|
<a title="motionless" class="termref" href=
|
|
"#dt-motionless">motionless</a>, allowing it to be used for example
|
|
in the predicate of a pattern. Implementation requires a
|
|
one-parser-event lookahead. The primary use case is for creating
|
|
lists or tables in streaming mode, where the wrapper element (for
|
|
example <code>ul</code> or <code>table</code>) is to be generated
|
|
only if the list is non-empty. Most current solutions to this
|
|
problem require two downward selections, one to test if the list is
|
|
empty and one to iterate over its contents. There is a solution
|
|
using <a href=
|
|
"#element-for-each-group"><code>xsl:for-each-group</code></a> to
|
|
generate a singleton group, but it involves rather artificial
|
|
coding.</p>
|
|
</blockquote>
|
|
</div>
|
|
</div>
|
|
<div class="div1">
|
|
<h2><a name="add-func" id="add-func"></a>19 <a href="#add-func"
|
|
style="text-decoration: none">Additional Functions</a></h2>
|
|
<p>This section describes XSLT-specific additions to the <a title=
|
|
"core function" class="termref" href="#dt-core-function">core
|
|
function</a> library. Some of these additional functions also make
|
|
use of information specified by <a title="declaration" class=
|
|
"termref" href="#dt-declaration">declarations</a> in the
|
|
stylesheet; this section also describes these declarations.</p>
|
|
<div class="div2">
|
|
<h3><a name="multiple-source-documents" id=
|
|
"multiple-source-documents"></a>19.1 <a href=
|
|
"#multiple-source-documents" style="text-decoration: none">Multiple
|
|
Source Documents</a></h3>
|
|
<div class="div3">
|
|
<h4><a name="document" id="document"></a>19.1.1 <a href="#document"
|
|
style="text-decoration: none">The</a> <code>document</code>
|
|
<a href="#document" style="text-decoration: none">function</a></h4>
|
|
<a name="function-document" id="function-document"></a>
|
|
<div class="proto"><code class=
|
|
"function">document</code>(<code class=
|
|
"arg">$uri-sequence</code><code class=
|
|
"as"> as </code><code class=
|
|
"type">item()*</code>)<code class=
|
|
"as"> as </code><code class=
|
|
"return-type">node()*</code></div>
|
|
<div class="proto"><code class=
|
|
"function">document</code>(<code class=
|
|
"arg">$uri-sequence</code><code class=
|
|
"as"> as </code><code class="type">item()*</code>,
|
|
<code class="arg">$base-node</code><code class=
|
|
"as"> as </code><code class=
|
|
"type">node()</code>)<code class=
|
|
"as"> as </code><code class=
|
|
"return-type">node()*</code></div>
|
|
<p>The <a href="#function-document"><code>document</code></a>
|
|
function allows access to XML documents identified by a URI.</p>
|
|
<p>The first argument contains a sequence of URI references. The
|
|
second argument, if present, is a node whose base URI is used to
|
|
resolve any relative URI references contained in the first
|
|
argument.</p>
|
|
<p>A sequence of absolute URI references is obtained as
|
|
follows.</p>
|
|
<ul>
|
|
<li>
|
|
<p>For an item in <code>$uri-sequence</code> that is an instance of
|
|
<code>xs:string</code>, <code>xs:anyURI</code>, or
|
|
<code>xs:untypedAtomic</code>, the value is cast to
|
|
<code>xs:anyURI</code>. If the resulting URI reference is an
|
|
absolute URI reference then it is used <em>as is</em>. If it is a
|
|
relative URI reference, then it is resolved against the base URI of
|
|
<code>$base-node</code> if supplied, or against the base URI from
|
|
the static context otherwise (this will usually be the base URI of
|
|
the stylesheet module). A relative URI <span>reference</span> is
|
|
resolved against a base URI using the rules defined in <a href=
|
|
"#RFC3986">[RFC3986]</a>.</p>
|
|
</li>
|
|
<li>
|
|
<p>For an item in <code>$uri-sequence</code> that is a node, the
|
|
node is <a title="atomize" class="termref" href=
|
|
"#dt-atomization">atomized</a>. The result <span class=
|
|
"verb">must</span> be a sequence whose items are all instances of
|
|
<code>xs:string</code>, <code>xs:anyURI</code>, or
|
|
<code>xs:untypedAtomic</code>. Each of these values is cast to
|
|
<code>xs:anyURI</code>, and if the resulting URI reference is an
|
|
absolute URI reference then it is used <em>as is</em>. If it is a
|
|
relative URI reference, then it is resolved against the base URI of
|
|
<code>$base-node</code> if supplied, or against the base URI of the
|
|
node that contained it otherwise.</p>
|
|
</li>
|
|
</ul>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>The XPath rules for function calling ensure that it is a type
|
|
error if the supplied value of the second argument is anything
|
|
other than a single node. If <a title=
|
|
"XPath 1.0 compatibility mode" class="termref" href=
|
|
"#dt-xpath-compat-mode">XPath 1.0 compatibility mode</a> is
|
|
enabled, then a sequence of nodes may be supplied, and the first
|
|
node in the sequence will be used.</p>
|
|
</div>
|
|
<p>Each of these absolute URI references is then processed as
|
|
follows. Any fragment identifier that is present in the URI
|
|
reference is removed, and the resulting absolute URI is cast to a
|
|
string and then passed to the <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-doc"><code>doc</code></a><sup><small>FO</small></sup>
|
|
function defined in <a href="#xpath-functions-11">[Functions and
|
|
Operators]</a>. This returns a document node. If an error occurs
|
|
during evaluation of the <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-doc"><code>doc</code></a><sup><small>FO</small></sup>
|
|
function, the processor <span class="verb">may</span> either signal
|
|
this error in the normal way, or <span class="verb">may</span>
|
|
recover by ignoring the failure, in which case the failing URI will
|
|
not contribute any nodes to the result of the <a href=
|
|
"#function-document"><code>document</code></a> function.</p>
|
|
<p>If the URI reference contained no fragment identifier, then this
|
|
document node is included in the sequence of nodes returned by the
|
|
<a href="#function-document"><code>document</code></a>
|
|
function.</p>
|
|
<p>If the URI reference contained a fragment identifier, then the
|
|
fragment identifier is interpreted according to the rules for the
|
|
media type of the resource representation identified by the URI,
|
|
and is used to select zero or more nodes that are
|
|
descendant-or-self nodes of the returned document node. As
|
|
described in <a href="#initiating"><i>2.3 Initiating a
|
|
Transformation</i></a>, the media type is available as part of the
|
|
evaluation context for a transformation.</p>
|
|
<p><a name="err-XTRE1160" id="err-XTRE1160"><span class=
|
|
"error">[ERR XTRE1160]</span></a> When a URI reference contains a
|
|
fragment identifier, it is a <a title="recoverable error" class=
|
|
"termref" href="#dt-recoverable-error">recoverable dynamic
|
|
error</a> if the media type is not one that is recognized by the
|
|
processor, or if the fragment identifier does not conform to the
|
|
rules for fragment identifiers for that media type, or if the
|
|
fragment identifier selects something other than a sequence of
|
|
nodes (for example, if it selects a range of characters within a
|
|
text node). The <a title="optional recovery action" class="termref"
|
|
href="#dt-optional-recovery-action">optional recovery action</a> is
|
|
to ignore the fragment identifier and return the document node. The
|
|
set of media types recognized by a processor is <a title=
|
|
"implementation-defined" class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a>.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>The recovery action here is different from XSLT 1.0</p>
|
|
</div>
|
|
<p>The sequence of nodes returned by the function is in document
|
|
order, with no duplicates. This order has no necessary relationship
|
|
to the order in which URIs were supplied in the
|
|
<code>$uri-sequence</code> argument.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>One effect of these rules is that unless XML entities or
|
|
<code>xml:base</code> are used, and provided that the base URI of
|
|
the stylesheet module is known, <code>document("")</code> refers to
|
|
the document node of the containing stylesheet module (the
|
|
definitive rules are in <a href="#RFC3986">[RFC3986]</a>). The XML
|
|
resource containing the stylesheet module is processed exactly as
|
|
if it were any other XML document, for example there is no special
|
|
recognition of <a href="#element-text"><code>xsl:text</code></a>
|
|
elements, and no special treatment of comments and processing
|
|
instructions.</p>
|
|
</div>
|
|
</div>
|
|
<div class="div3">
|
|
<h4><a name="uri-collection" id="uri-collection"></a>19.1.2
|
|
<a href="#uri-collection" style="text-decoration: none">The</a>
|
|
<code>uri-collection</code> <a href="#uri-collection" style=
|
|
"text-decoration: none">function</a></h4>
|
|
<a name="function-uri-collection" id="function-uri-collection"></a>
|
|
<div class="proto"><code class=
|
|
"function">uri-collection</code>()<code class=
|
|
"as"> as </code><code class=
|
|
"return-type">xs:string*</code></div>
|
|
<div class="proto"><code class=
|
|
"function">uri-collection</code>(<code class=
|
|
"arg">$href</code><code class=
|
|
"as"> as </code><code class="type">xs:string?</code>)<code class="as"> as </code><code class="return-type">xs:string*</code></div>
|
|
<p>The <a href=
|
|
"#function-uri-collection"><code>uri-collection</code></a> returns
|
|
the document URIs of the documents in a collection. Unlike the
|
|
<a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-collection"><code>collection</code></a><sup><small>FO</small></sup>
|
|
function, it does not retrieve the documents themselves.</p>
|
|
<p>The zero-argument form of the function returns the URIs of the
|
|
documents in the default collection. If the value of the default
|
|
collection is undefined an error is raised (<a href=
|
|
"http://www.w3.org/TR/xpath-functions/#ERRFODC0002" title=
|
|
"FODC0002"><span class="error">[ERR FODC0002]</span></a>
|
|
<sup><small>FO</small></sup>).</p>
|
|
<p>The single-argument form returns the URIs of the documents in
|
|
the collection with a given collection URI. If the value of the
|
|
argument is an empty sequence, the action is as for the
|
|
zero-argument form of the function. If the argument is a relative
|
|
URI <span>reference</span>, it is resolved against the base URI
|
|
property of the static context. If the argument is not a valid
|
|
<code>xs:anyURI</code>, or if the dynamic context does not include
|
|
a collection with this URI, then an error is raised (<a href=
|
|
"http://www.w3.org/TR/xpath-functions/#ERRFODC0004" title=
|
|
"FODC0004"><span class="error">[ERR FODC0004]</span></a>
|
|
<sup><small>FO</small></sup>).</p>
|
|
<p>The function is defined so that the expression <code>for $u in
|
|
uri-collection(X) return doc($u)</code>, if it succeeds, will
|
|
always return the same result as the expression
|
|
<code>collection(X)</code>.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>There are several reasons it might be appropriate to retrieve
|
|
the URIs of the documents in a collection without retrieving the
|
|
documents themselves. For example:</p>
|
|
<ul>
|
|
<li>
|
|
<p>It allows the documents to be processed in streaming mode using
|
|
<a href="#element-stream"><code>xsl:stream</code></a></p>
|
|
</li>
|
|
<li>
|
|
<p>It allows recovery from failures to read, parse, or validate
|
|
individual documents, by calling the <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-doc"><code>doc</code></a><sup><small>FO</small></sup>
|
|
function within the scope of an <a href=
|
|
"#element-try"><code>xsl:try</code></a> instruction</p>
|
|
</li>
|
|
<li>
|
|
<p>It allows access to non-XML documents within a collection using
|
|
the <a href=
|
|
"#function-unparsed-text"><code>unparsed-text</code></a>
|
|
function</p>
|
|
</li>
|
|
<li>
|
|
<p>It allows selection of which documents to read based on their
|
|
URI, for example they can be filtered to select those whose URIs
|
|
end in <code>.xml</code></p>
|
|
</li>
|
|
</ul>
|
|
<p>However, there may be collections that cannot be processed in
|
|
this way: specifically, those that contain nodes other than
|
|
document nodes, and those that contain document nodes having no
|
|
document URI. Conversely, there may be collections (such as those
|
|
containing non-XML resources) that can be processed using the
|
|
<a href="#function-uri-collection"><code>uri-collection</code></a>
|
|
function but not the <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-collection"><code>collection</code></a><sup><small>FO</small></sup>
|
|
function.</p>
|
|
</div>
|
|
<blockquote>
|
|
<p><b><a name="issue-transfer-uri-collection" id=
|
|
"issue-transfer-uri-collection">Issue 30
|
|
(transfer-uri-collection)</a>:</b></p>
|
|
<p>A decision in principle has been reached for
|
|
<code>uri-collection</code> to become a standard XPath 2.1
|
|
function.</p>
|
|
</blockquote>
|
|
</div>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="unparsed-text" id="unparsed-text"></a>19.2 <a href=
|
|
"#unparsed-text" style="text-decoration: none">Reading Text
|
|
Files</a></h3>
|
|
<div class="div3">
|
|
<h4><a name="unparsed-text-function" id=
|
|
"unparsed-text-function"></a>19.2.1 <a href=
|
|
"#unparsed-text-function" style="text-decoration: none">The</a>
|
|
<code>unparsed-text</code> <a href="#unparsed-text-function" style=
|
|
"text-decoration: none">function</a></h4>
|
|
<a name="function-unparsed-text" id="function-unparsed-text"></a>
|
|
<div class="proto"><code class=
|
|
"function">unparsed-text</code>(<code class=
|
|
"arg">$href</code><code class=
|
|
"as"> as </code><code class="type">xs:string?</code>)<code class="as"> as </code><code class="return-type">xs:string?</code></div>
|
|
<div class="proto"><code class=
|
|
"function">unparsed-text</code>(<code class=
|
|
"arg">$href</code><code class=
|
|
"as"> as </code><code class="type">xs:string?</code>,
|
|
<code class="arg">$encoding</code><code class=
|
|
"as"> as </code><code class=
|
|
"type">xs:string</code>)<code class=
|
|
"as"> as </code><code class=
|
|
"return-type">xs:string?</code></div>
|
|
<blockquote>
|
|
<p><b><a name="issue-transfer-unparsed-text" id=
|
|
"issue-transfer-unparsed-text">Issue 31
|
|
(transfer-unparsed-text)</a>:</b></p>
|
|
<p>A decision in principle has been reached for
|
|
<code>unparsed-text</code> and <code>unparsed-text-available</code>
|
|
to become standard XPath 2.1 functions.</p>
|
|
</blockquote>
|
|
<p>The <a href=
|
|
"#function-unparsed-text"><code>unparsed-text</code></a> function
|
|
reads an external resource (for example, a file) and returns its
|
|
contents as a string.</p>
|
|
<p>The <code>$href</code> argument <span class="verb">must</span>
|
|
be a string in the form of a URI <span>reference, which</span>
|
|
<span class="verb">must</span> contain no fragment identifier, and
|
|
<span class="verb">must</span> identify a resource that can be read
|
|
as text. If the URI is a relative URI <span>reference</span>, then
|
|
it is resolved relative to the base URI from the static
|
|
context.</p>
|
|
<p>If the value of the <code>$href</code> argument is an empty
|
|
sequence, the function returns an empty sequence.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>If a different base URI is appropriate (for example, when
|
|
resolving a relative URI <span>reference</span> read from a source
|
|
document) <span>then the stylesheet author should</span> resolve
|
|
the relative URI <span>reference</span> using the <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-resolve-uri"><code>resolve-uri</code></a><sup><small>FO</small></sup>
|
|
function before passing it to the <a href=
|
|
"#function-unparsed-text"><code>unparsed-text</code></a>
|
|
function.</p>
|
|
</div>
|
|
<p>The <code>$encoding</code> argument, if present, is the name of
|
|
an encoding. The values for this attribute follow the same rules as
|
|
for the <code>encoding</code> attribute in an XML declaration. The
|
|
only values which every <a title="implementation" class="termref"
|
|
href="#dt-implementation">implementation</a> is <span class=
|
|
"verb">required</span> to recognize are <code>utf-8</code> and
|
|
<code>utf-16</code>.</p>
|
|
<p>The encoding of the external resource is determined as
|
|
follows:</p>
|
|
<ol class="enumar">
|
|
<li>
|
|
<p>external encoding information is used if available,
|
|
otherwise</p>
|
|
</li>
|
|
<li>
|
|
<p>if the media type of the resource is <code>text/xml</code> or
|
|
<code>application/xml</code> (see <a href=
|
|
"#RFC2376">[RFC2376]</a>), or if it matches the conventions
|
|
<code>text/*+xml</code> or <code>application/*+xml</code> (see
|
|
<a href="#RFC3023">[RFC3023]</a> and/or its successors), then the
|
|
encoding is recognized as specified in <a href="#REC-xml">[XML
|
|
1.0]</a>, otherwise</p>
|
|
</li>
|
|
<li>
|
|
<p>the value of the <code>$encoding</code> argument is used if
|
|
present, otherwise</p>
|
|
</li>
|
|
<li>
|
|
<p>the processor <span class="verb">may</span> use <a title=
|
|
"implementation-defined" class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a> heuristics
|
|
to determine the likely encoding, otherwise</p>
|
|
</li>
|
|
<li>
|
|
<p>UTF-8 is assumed.</p>
|
|
</li>
|
|
</ol>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>The above rules are chosen for consistency with <a href=
|
|
"#xinclude">[XInclude]</a>. Files with an XML media type are
|
|
treated specially because there are use cases for this function
|
|
where the retrieved text is to be included as unparsed XML within a
|
|
CDATA section of a containing document, and because processors are
|
|
likely to be able to reuse the code that performs encoding
|
|
detection for XML external entities.</p>
|
|
</div>
|
|
<p><a name="err-XTDE1170" id="err-XTDE1170"><span class=
|
|
"error">[ERR XTDE1170]</span></a> It is a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> if a
|
|
URI contains a fragment identifier, or if it cannot be used to
|
|
retrieve a resource containing text.</p>
|
|
<p><a name="err-XTDE1190" id="err-XTDE1190"><span class=
|
|
"error">[ERR XTDE1190]</span></a> It is a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> if a
|
|
resource contains octets that cannot be decoded into Unicode
|
|
characters using the specified encoding, or if the resulting
|
|
characters are not permitted XML characters. This includes the case
|
|
where the <a title="processor" class="termref" href=
|
|
"#dt-processor">processor</a> does not support the requested
|
|
encoding.</p>
|
|
<p><a name="err-XTDE1200" id="err-XTDE1200"><span class=
|
|
"error">[ERR XTDE1200]</span></a> It is a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> if the
|
|
second argument of the <a href=
|
|
"#function-unparsed-text"><code>unparsed-text</code></a> function
|
|
is omitted and the <a title="processor" class="termref" href=
|
|
"#dt-processor">processor</a> cannot infer the encoding using
|
|
external information and the encoding is not UTF-8.</p>
|
|
<p>The result is a string containing the text of the resource
|
|
retrieved using the URI.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>If the text file contains characters such as <code><</code>
|
|
and <code>&</code>, these will typically be output as
|
|
<code>&lt;</code> and <code>&amp;</code> when the string is
|
|
written to a <a title="final result tree" class="termref" href=
|
|
"#dt-final-result-tree">final result tree</a> 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 the
|
|
<code>disable-output-escaping</code> attribute of the <a href=
|
|
"#element-value-of"><code>xsl:value-of</code></a> instruction (see
|
|
<a href="#disable-output-escaping"><i>23.2 Disabling Output
|
|
Escaping</i></a>). Note, however, that implementations are not
|
|
required to support this feature.</p>
|
|
</div>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e34258" id=
|
|
"d7e34258"></a>Example: Copying Unparsed HTML Boilerplate</div>
|
|
<p>This example attempts to read an HTML file and copy it, as HTML,
|
|
to the serialized output file:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<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>
|
|
</pre></div>
|
|
</div>
|
|
<p> </p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e34265" id=
|
|
"d7e34265"></a>Example: Splitting an Input File into a Sequence of
|
|
Lines</div>
|
|
<p>Often it is necessary to split a text file into a sequence of
|
|
lines, representing each line as a string. This can be achieved by
|
|
using the <a href=
|
|
"#function-unparsed-text"><code>unparsed-text</code></a> function
|
|
in conjunction with the XPath <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-tokenize"><code>tokenize</code></a><sup><small>FO</small></sup>
|
|
function. For example:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:for-each select="tokenize(unparsed-text($in), '\r?\n')">
|
|
...
|
|
</xsl:for-each>
|
|
</pre></div>
|
|
<p>Note that the <a href=
|
|
"#function-unparsed-text"><code>unparsed-text</code></a> function
|
|
does not normalize line endings. This example has been written to
|
|
recognize both Unix and Windows conventions for end-of-line, namely
|
|
a single newline (#x0A) character or a carriage return / line feed
|
|
pair (#x0D #x0A). <span>It differs from the <a href=
|
|
"#function-unparsed-text-lines"><code>unparsed-text-lines</code></a>
|
|
function, however, in that it does not recognize a carriage return
|
|
on its own as a line ending, and it does not give special treatment
|
|
to a newline appearing at the end of the file.</span></p>
|
|
</div>
|
|
</div>
|
|
<div class="div3">
|
|
<h4><a name="unparsed-text-lines" id=
|
|
"unparsed-text-lines"></a>19.2.2 <a href="#unparsed-text-lines"
|
|
style="text-decoration: none">The</a>
|
|
<code>unparsed-text-lines</code> <a href="#unparsed-text-lines"
|
|
style="text-decoration: none">function</a></h4>
|
|
<a name="function-unparsed-text-lines" id=
|
|
"function-unparsed-text-lines"></a>
|
|
<div class="proto"><code class=
|
|
"function">unparsed-text-lines</code>(<code class=
|
|
"arg">$href</code><code class=
|
|
"as"> as </code><code class="type">xs:string?</code>)<code class="as"> as </code><code class="return-type">xs:string?*</code></div>
|
|
<div class="proto"><code class=
|
|
"function">unparsed-text-lines</code>(<code class=
|
|
"arg">$href</code><code class=
|
|
"as"> as </code><code class="type">xs:string?</code>,
|
|
<code class="arg">$encoding</code><code class=
|
|
"as"> as </code><code class=
|
|
"type">xs:string</code>)<code class=
|
|
"as"> as </code><code class=
|
|
"return-type">xs:string?*</code></div>
|
|
<p>The <a href=
|
|
"#function-unparsed-text-lines"><code>unparsed-text-lines</code></a>
|
|
function reads an external resource (for example, a file) and
|
|
returns its contents as a sequence of strings, separated at newline
|
|
boundaries.</p>
|
|
<p>The result of the single-argument function is the same as the
|
|
result of the expression <code>tokenize(unparsed-text($href),
|
|
'\r\n|\r|\n')[not(position()=last() and .='')]</code>. The result
|
|
of the two-argument function is the same as the result of the
|
|
expression <code>tokenize(unparsed-text($href, $encoding),
|
|
'\r\n|\r|\n'))[not(position()=last() and .='')]</code>.</p>
|
|
<p>The result is a thus a sequence of strings containing the text
|
|
of the resource retrieved using the URI, each string representing
|
|
one line of text. Lines are separated by one of the sequences #x0A,
|
|
#x0D, or #x0D #x0A. The characters representing the newline are not
|
|
included in the returned strings. If there are two adjacent newline
|
|
sequences, a zero-length string will be returned to represent the
|
|
empty line; but if the external resource ends with a newline
|
|
sequence, no zero-length string will be returned as the last item
|
|
in the result.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>This function has been added in XSLT 2.1 for three reasons: to
|
|
do the line splitting in a way consistent with the rules applied
|
|
during XML parsing; to do it without recourse to regular
|
|
expressions (which is likely to be more efficient), and to make it
|
|
easier for processors to read the input file line by line, which is
|
|
likely to use less memory.</p>
|
|
</div>
|
|
</div>
|
|
<div class="div3">
|
|
<h4><a name="unparsed-text-available" id=
|
|
"unparsed-text-available"></a>19.2.3 <a href=
|
|
"#unparsed-text-available" style="text-decoration: none">The
|
|
unparsed-text-available function</a></h4>
|
|
<p>Because errors in evaluating the <a href=
|
|
"#function-unparsed-text"><code>unparsed-text</code></a> <span>and
|
|
<a href=
|
|
"#function-unparsed-text-lines"><code>unparsed-text-lines</code></a></span>
|
|
functions are non-recoverable, two functions are provided to allow
|
|
a stylesheet to determine whether a call with particular arguments
|
|
would succeed:</p>
|
|
<a name="function-unparsed-text-available" id=
|
|
"function-unparsed-text-available"></a>
|
|
<div class="proto"><code class=
|
|
"function">unparsed-text-available</code>(<code class=
|
|
"arg">$href</code><code class=
|
|
"as"> as </code><code class="type">xs:string?</code>)<code class="as"> as </code><code class="return-type">xs:boolean</code></div>
|
|
<div class="proto">
|
|
<table border="0" cellpadding="0" cellspacing="0">
|
|
<tr>
|
|
<td valign="baseline" rowspan="2"><code class=
|
|
"function">unparsed-text-available</code>(</td>
|
|
<td valign="baseline"><code class="arg">$href</code></td>
|
|
<td valign="baseline"><code class=
|
|
"as"> as </code><code class=
|
|
"type">xs:string?</code>,</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="baseline"><code class="arg">$encoding</code></td>
|
|
<td valign="baseline"><code class=
|
|
"as"> as </code><code class=
|
|
"type">xs:string?</code>)<code class=
|
|
"as"> as </code><code class=
|
|
"return-type">xs:boolean</code></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<p>The <a href=
|
|
"#function-unparsed-text-available"><code>unparsed-text-available</code></a>
|
|
function determines whether a call on the <a href=
|
|
"#function-unparsed-text"><code>unparsed-text</code></a> function
|
|
with identical arguments would return a string.</p>
|
|
<p>If the first argument is an empty sequence, the function returns
|
|
false. If the second argument is an empty sequence, the function
|
|
behaves as if the second argument were omitted.</p>
|
|
<p>In other cases, the function returns true if a call on <a href=
|
|
"#function-unparsed-text"><code>unparsed-text</code></a> with the
|
|
same arguments would succeed, and false if a call on <a href=
|
|
"#function-unparsed-text"><code>unparsed-text</code></a> with the
|
|
same arguments would fail with a non-recoverable dynamic error.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>This requires that the <a href=
|
|
"#function-unparsed-text-available"><code>unparsed-text-available</code></a>
|
|
function should actually attempt to read the resource identified by
|
|
the URI, and check that it is correctly encoded and contains no
|
|
characters that are invalid in XML. Implementations may avoid the
|
|
cost of repeating these checks for example by caching the validated
|
|
contents of the resource, to anticipate a subsequent call on the
|
|
<a href="#function-unparsed-text"><code>unparsed-text</code></a>
|
|
<span>or <a href=
|
|
"#function-unparsed-text-lines"><code>unparsed-text-lines</code></a></span>
|
|
function. Alternatively, implementations may be able to rewrite an
|
|
expression such as <code>if (unparsed-text-available(A)) then
|
|
unparsed-text(A) else ...</code> to generate a single call
|
|
internally.</p>
|
|
</div>
|
|
<p>The functions <a href=
|
|
"#function-unparsed-text"><code>unparsed-text</code></a>,
|
|
<span><a href=
|
|
"#function-unparsed-text-lines"><code>unparsed-text-lines</code></a></span>
|
|
, and <a href=
|
|
"#function-unparsed-text-available"><code>unparsed-text-available</code></a>
|
|
have the same requirement for <a href=
|
|
"http://www.w3.org/TR/xpath-functions/#stable">stability</a><sup><small>FO</small></sup>
|
|
as the functions <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-doc"><code>doc</code></a><sup><small>FO</small></sup>
|
|
and <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-doc-available"><code>
|
|
doc-available</code></a><sup><small>FO</small></sup> defined in
|
|
<a href="#xpath-functions-11">[Functions and Operators]</a>. This
|
|
means that unless the user has explicitly stated a requirement for
|
|
a reduced level of stability, either of these functions if called
|
|
twice with the same arguments during the course of a transformation
|
|
<span class="verb">must</span> return the same results each time;
|
|
moreover, the results of a call on <a href=
|
|
"#function-unparsed-text-available"><code>unparsed-text-available</code></a>
|
|
<span class="verb">must</span> be consistent with the results of a
|
|
subsequent call on <a href=
|
|
"#function-unparsed-text"><code>unparsed-text</code></a> <span>or
|
|
<a href=
|
|
"#function-unparsed-text-lines"><code>unparsed-text-lines</code></a></span>
|
|
with the same arguments.</p>
|
|
<blockquote>
|
|
<p><b><a name="issue-function-stability" id=
|
|
"issue-function-stability">Issue 32
|
|
(function-stability)</a>:</b></p>
|
|
<p>The functions in this specification need to be classified more
|
|
clearly in terms of their stability properties, along the lines
|
|
being developed in Functions and Operators.</p>
|
|
</blockquote>
|
|
</div>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="key" id="key"></a>19.3 <a href="#key" style=
|
|
"text-decoration: none">Keys</a></h3>
|
|
<p>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.</p>
|
|
<div class="div3">
|
|
<h4><a name="xsl-key" id="xsl-key"></a>19.3.1 <a href="#xsl-key"
|
|
style="text-decoration: none">The</a> <a href=
|
|
"#element-key"><code>xsl:key</code></a> <a href="#xsl-key" style=
|
|
"text-decoration: none">Declaration</a></h4>
|
|
<p class="element-syntax"><a name="element-key" id=
|
|
"element-key"></a><code><!-- Category: declaration --><br />
|
|
<xsl:key<br />
|
|
  <b>name</b> = <var>qname</var><br />
|
|
  <b>match</b> = <var>pattern</var><br />
|
|
  use? = <var>expression</var><br />
|
|
  collation? = <var>uri</var> ><br />
|
|
  <!-- Content: <var>sequence-constructor</var>
|
|
--><br />
|
|
</xsl:key></code></p>
|
|
<p>The <a href="#element-key"><code>xsl:key</code></a> <a title=
|
|
"declaration" class="termref" href=
|
|
"#dt-declaration">declaration</a> is used to declare <a title="key"
|
|
class="termref" href="#dt-key">keys</a>. The <code>name</code>
|
|
attribute specifies the name of the key. The value of the
|
|
<code>name</code> attribute is a <a title="QName" class="termref"
|
|
href="#dt-qname">QName</a>, which is expanded as described in
|
|
<a href="#qname"><i>5.1 Qualified Names</i></a>. The
|
|
<code>match</code> attribute is a <a href=
|
|
"#NT-Pattern">Pattern</a>; an <a href=
|
|
"#element-key"><code>xsl:key</code></a> element applies to all
|
|
nodes that match the pattern specified in the <code>match</code>
|
|
attribute.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-key" id="dt-key" title="key"></a>A <b>key</b> is defined as a
|
|
set of <a href="#element-key"><code>xsl:key</code></a> declarations
|
|
in the <a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a> that share the same
|
|
name.<span class="definition">]</span></p>
|
|
<p>The value of the key may be specified either using the
|
|
<code>use</code> attribute or by means of the contained <a title=
|
|
"sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a>.</p>
|
|
<p><a name="err-XTSE1205" id="err-XTSE1205"><span class=
|
|
"error">[ERR XTSE1205]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> if an
|
|
<a href="#element-key"><code>xsl:key</code></a> declaration has a
|
|
<code>use</code> attribute and has non-empty content, or if it has
|
|
empty content and no <code>use</code> attribute.</p>
|
|
<p>If the <code>use</code> attribute is present, its value is an
|
|
<a title="expression" class="termref" href=
|
|
"#dt-expression">expression</a> specifying the values of the key.
|
|
The expression will be evaluated with <span>a <a title=
|
|
"singleton focus" class="termref" href=
|
|
"#dt-singleton-focus">singleton focus</a> based on the node that
|
|
matches the pattern</span>. The result of evaluating the expression
|
|
is <a title="atomize" class="termref" href=
|
|
"#dt-atomization">atomized</a>.</p>
|
|
<p>Similarly, if a <a title="sequence constructor" class="termref"
|
|
href="#dt-sequence-constructor">sequence constructor</a> is
|
|
present, it is used to determine the values of the key. The
|
|
sequence constructor will be evaluated with the node that matches
|
|
the pattern as the context node. The result of evaluating the
|
|
sequence constructor is <a title="atomize" class="termref" href=
|
|
"#dt-atomization">atomized</a>.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-key-specifier" id="dt-key-specifier" title=
|
|
"key specifier"></a>The expression in the <code>use</code>
|
|
attribute and the <a title="sequence constructor" class="termref"
|
|
href="#dt-sequence-constructor">sequence constructor</a> within an
|
|
<a href="#element-key"><code>xsl:key</code></a> declaration are
|
|
referred to collectively as the <b>key specifier</b>. The key
|
|
specifier determines the values that may be used to find a node
|
|
using this <a title="key" class="termref" href=
|
|
"#dt-key">key</a>.<span class="definition">]</span></p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>There is no requirement that all the values of a key should have
|
|
the same type.</p>
|
|
</div>
|
|
<p>The presence of an <a href=
|
|
"#element-key"><code>xsl:key</code></a> declaration makes it easy
|
|
to find a node that matches the <code>match</code> pattern if any
|
|
of the values of the <a title="key specifier" class="termref" href=
|
|
"#dt-key-specifier">key specifier</a> (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 <a title="key specifier"
|
|
class="termref" href="#dt-key-specifier">key specifier</a> in
|
|
general returns a sequence of values, and any one of these may be
|
|
used to locate the node.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>An <a href="#element-key"><code>xsl:key</code></a> declaration
|
|
is not bound to a specific source document. The source document to
|
|
which it applies is determined only when the <a href=
|
|
"#function-key"><code>key</code></a> function is used to locate
|
|
nodes using the key. Keys can be used to locate nodes within any
|
|
source document (including temporary trees), but each use of the
|
|
<a href="#function-key"><code>key</code></a> function searches one
|
|
document only.</p>
|
|
</div>
|
|
<p>The optional <code>collation</code> attribute is used only when
|
|
deciding whether two strings are equal for the purposes of key
|
|
matching. Specifically, two values <code>$a</code> and
|
|
<code>$b</code> are considered equal if the result of the function
|
|
call <code>compare($a, $b, $collation)</code> is zero. The
|
|
effective collation for an <a href=
|
|
"#element-key"><code>xsl:key</code></a> declaration is the
|
|
collation specified in its <code>collation</code> attribute if
|
|
present, resolved against the base URI of the <a href=
|
|
"#element-key"><code>xsl:key</code></a> element, or the <a title=
|
|
"default collation" class="termref" href=
|
|
"#dt-default-collation">default collation</a> that is in scope for
|
|
the <a href="#element-key"><code>xsl:key</code></a> declaration
|
|
otherwise; the effective collation must be the same for all the
|
|
<a href="#element-key"><code>xsl:key</code></a> declarations making
|
|
up a <a title="key" class="termref" href="#dt-key">key</a>.</p>
|
|
<p><a name="err-XTSE1210" id="err-XTSE1210"><span class=
|
|
"error">[ERR XTSE1210]</span></a> It is a static error if the
|
|
<a href="#element-key"><code>xsl:key</code></a> declaration has a
|
|
<code>collation</code> attribute whose value (after resolving
|
|
against the base URI) is not a URI recognized by the implementation
|
|
as referring to a collation.</p>
|
|
<p><a name="err-XTSE1220" id="err-XTSE1220"><span class=
|
|
"error">[ERR XTSE1220]</span></a> It is a static error if there are
|
|
several <a href="#element-key"><code>xsl:key</code></a>
|
|
declarations in the <a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a> with the same key name and
|
|
different effective collations. Two collations are the same if
|
|
their URIs are equal under the rules for comparing
|
|
<code>xs:anyURI</code> values, or if the implementation can
|
|
determine that they are different URIs referring to the same
|
|
collation.</p>
|
|
<p>It is possible to have:</p>
|
|
<ul>
|
|
<li>
|
|
<p>multiple <a href="#element-key"><code>xsl:key</code></a>
|
|
declarations with the same name;</p>
|
|
</li>
|
|
<li>
|
|
<p>a node that matches the <code>match</code> patterns of several
|
|
different <a href="#element-key"><code>xsl:key</code></a>
|
|
declarations, whether these have the same key name or different key
|
|
names;</p>
|
|
</li>
|
|
<li>
|
|
<p>a node that returns more than one value from its <a title=
|
|
"key specifier" class="termref" href="#dt-key-specifier">key
|
|
specifier</a>;</p>
|
|
</li>
|
|
<li>
|
|
<p>a key value that identifies more than one node (the key values
|
|
for different nodes do not need to be unique).</p>
|
|
</li>
|
|
</ul>
|
|
<p>An <a href="#element-key"><code>xsl:key</code></a> declaration
|
|
with higher <a title="import precedence" class="termref" href=
|
|
"#dt-import-precedence">import precedence</a> does not override
|
|
another of lower import precedence; all the <a href=
|
|
"#element-key"><code>xsl:key</code></a> declarations in the
|
|
stylesheet are effective regardless of their import precedence.</p>
|
|
</div>
|
|
<div class="div3">
|
|
<h4><a name="keys" id="keys"></a>19.3.2 <a href="#keys" style=
|
|
"text-decoration: none">The</a> <a href=
|
|
"#function-key"><code>key</code></a> <a href="#keys" style=
|
|
"text-decoration: none">Function</a></h4>
|
|
<a name="function-key" id="function-key"></a>
|
|
<div class="proto"><code class="function">key</code>(<code class=
|
|
"arg">$key-name</code><code class=
|
|
"as"> as </code><code class="type">xs:string</code>,
|
|
<code class="arg">$key-value</code><code class=
|
|
"as"> as </code><code class=
|
|
"type">xs:anyAtomicType*</code>)<code class=
|
|
"as"> as </code><code class=
|
|
"return-type">node()*</code></div>
|
|
<div class="proto">
|
|
<table border="0" cellpadding="0" cellspacing="0">
|
|
<tr>
|
|
<td valign="baseline" rowspan="3"><code class=
|
|
"function">key</code>(</td>
|
|
<td valign="baseline"><code class="arg">$key-name</code></td>
|
|
<td valign="baseline"><code class=
|
|
"as"> as </code><code class="type">xs:string</code>,</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="baseline"><code class="arg">$key-value</code></td>
|
|
<td valign="baseline"><code class=
|
|
"as"> as </code><code class=
|
|
"type">xs:anyAtomicType*</code>,</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="baseline"><code class="arg">$top</code></td>
|
|
<td valign="baseline"><code class=
|
|
"as"> as </code><code class=
|
|
"type">node()</code>)<code class=
|
|
"as"> as </code><code class=
|
|
"return-type">node()*</code></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<p>The <a href="#function-key"><code>key</code></a> function does
|
|
for keys what the <span><a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-element-with-id"><code>
|
|
element-with-id</code></a><sup><small>FO</small></sup></span>
|
|
function does for IDs.</p>
|
|
<p>The <code>$key-name</code> argument specifies the name of the
|
|
<a title="key" class="termref" href="#dt-key">key</a>. The value of
|
|
the argument <span class="verb">must</span> be a <a title=
|
|
"lexical QName" class="termref" href="#dt-lexical-qname">lexical
|
|
QName</a>, which is expanded as described in <a href=
|
|
"#qname"><i>5.1 Qualified Names</i></a>.</p>
|
|
<p><a name="err-XTDE1260" id="err-XTDE1260"><span class=
|
|
"error">[ERR XTDE1260]</span></a> It is a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> 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
|
|
<a href="#element-key"><code>xsl:key</code></a> declaration in the
|
|
<a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a>. If the processor is able to detect
|
|
the error statically (for example, when the argument is supplied as
|
|
a string literal), then the processor <span class="verb">may</span>
|
|
optionally signal this as a <a title="static error" class="termref"
|
|
href="#dt-static-error">static error</a>.</p>
|
|
<p>The <code>$key-value</code> argument to the <a href=
|
|
"#function-key"><code>key</code></a> function is considered as a
|
|
sequence. The set of requested key values is formed by atomizing
|
|
the supplied value of the argument, using the standard <a title=
|
|
"function conversion rules" class="termref" href=
|
|
"#dt-function-conversion-rules">function conversion rules</a>. Each
|
|
of the resulting atomic values is considered as a requested key
|
|
value. The result of the function is a sequence of nodes, in
|
|
document order and with duplicates removed, comprising those nodes
|
|
in the selected subtree (see below) that are matched by an <a href=
|
|
"#element-key"><code>xsl:key</code></a> declaration whose name is
|
|
the same as the supplied key name, where the result of evaluating
|
|
the <a title="key specifier" class="termref" href=
|
|
"#dt-key-specifier">key specifier</a> contains a value that is
|
|
equal to one of these requested key values, under the rules
|
|
appropriate to the XPath <code>eq</code> operator for the two
|
|
values in question, using the <code>collation</code> attributes of
|
|
the <a href="#element-key"><code>xsl:key</code></a> declaration
|
|
when comparing strings. No error is reported if two values are
|
|
encountered that are not comparable; they are regarded for the
|
|
purposes of this function as being not equal.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>Under the rules for the <code>eq</code> operator, untyped atomic
|
|
values are converted to strings, not to the type of the other
|
|
operand. This means, for example, that if the expression in the
|
|
<code>use</code> attribute returns a date, supplying an untyped
|
|
atomic value in the call to the <a href=
|
|
"#function-key"><code>key</code></a> function will return an empty
|
|
sequence.</p>
|
|
</div>
|
|
<p>If the second argument is an empty sequence, the result of the
|
|
function will be an empty sequence.</p>
|
|
<p>Different rules apply when <span><a title="XSLT 1.0 behavior"
|
|
class="termref" href="#dt-xslt-10-behavior">XSLT 1.0 compatible
|
|
behavior</a> is enabled. Specifically, if any of the <a href=
|
|
"#element-key"><code>xsl:key</code></a> elements in the definition
|
|
of the <a title="key" class="termref" href="#dt-key">key</a> is
|
|
processed with XSLT 1.0 behavior</span>, then the value of the
|
|
<a title="key specifier" class="termref" href=
|
|
"#dt-key-specifier">key specifier</a> and the value of the second
|
|
argument of the <a href="#function-key"><code>key</code></a>
|
|
function are both converted after atomization to a sequence of
|
|
strings, by applying a cast to each item in the sequence, before
|
|
performing the comparison.</p>
|
|
<p>The third argument is used to identify the selected subtree. If
|
|
the argument is present, the selected subtree is the set of nodes
|
|
that have <var>$top</var> as an ancestor-or-self node. If the
|
|
argument is omitted, the selected subtree is the document
|
|
containing the context node. This means that the third argument
|
|
effectively defaults to <code>/</code>.</p>
|
|
<p><a name="err-XTDE1270" id="err-XTDE1270"><span class=
|
|
"error">[ERR XTDE1270]</span></a> It is a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> to
|
|
call the <a href="#function-key"><code>key</code></a> function with
|
|
two arguments if there is no <a title="context node" class=
|
|
"termref" href="#dt-context-node">context node</a>, or if the root
|
|
of the tree containing the context node is not a document node; or
|
|
to call the function with three arguments if the root of the tree
|
|
containing the node supplied in the third argument is not a
|
|
document node.</p>
|
|
<p>The result of the <a href="#function-key"><code>key</code></a>
|
|
function can be described more specifically as follows. The result
|
|
is a sequence containing every node <var>$N</var> that satisfies
|
|
the following conditions:</p>
|
|
<ul>
|
|
<li>
|
|
<p><code>$N/ancestor-or-self::node() intersect $top</code> is
|
|
non-empty. (If the third argument is omitted, <code>$top</code>
|
|
defaults to <code>/</code>)</p>
|
|
</li>
|
|
<li>
|
|
<p><var>$N</var> matches the pattern specified in the
|
|
<code>match</code> attribute of an <a href=
|
|
"#element-key"><code>xsl:key</code></a> declaration whose
|
|
<code>name</code> attribute matches the name specified in the
|
|
<code>$key-name</code> argument.</p>
|
|
</li>
|
|
<li>
|
|
<p>When the <a title="key specifier" class="termref" href=
|
|
"#dt-key-specifier">key specifier</a> of that <a href=
|
|
"#element-key"><code>xsl:key</code></a> declaration is evaluated
|
|
with a <a title="singleton focus" class="termref" href=
|
|
"#dt-singleton-focus">singleton focus</a> based on <var>$N</var>,
|
|
the <a title="atomize" class="termref" href=
|
|
"#dt-atomization">atomized</a> value of the resulting sequence
|
|
includes a value that compares equal to at least one item in the
|
|
atomized value of the sequence supplied as <code>$key-value</code>,
|
|
under the rules of the <code>eq</code> operator with the collation
|
|
selected as described above.</p>
|
|
</li>
|
|
</ul>
|
|
<p>The sequence returned by the <a href=
|
|
"#function-key"><code>key</code></a> function will be in document
|
|
order, with duplicates (that is, nodes having the same identity)
|
|
removed.</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e34915" id=
|
|
"d7e34915"></a>Example: Using a Key to Follow
|
|
Cross-References</div>
|
|
<p>For example, given a declaration</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:key name="idkey" match="div" use="@id"/>
|
|
</pre></div>
|
|
<p>an expression <code>key("idkey",@ref)</code> will return the
|
|
same nodes as <code>id(@ref)</code>, assuming that the only ID
|
|
attribute declared in the XML source document is:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<!ATTLIST div id ID #IMPLIED>
|
|
</pre></div>
|
|
<p>and that the <code>ref</code> attribute of the context node
|
|
contains no whitespace.</p>
|
|
<p>Suppose a document describing a function library uses a
|
|
<code>prototype</code> element to define functions</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<prototype name="sqrt" return-type="xs:double">
|
|
<arg type="xs:double"/>
|
|
</prototype>
|
|
</pre></div>
|
|
<p>and a <code>function</code> element to refer to function
|
|
names</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<function>sqrt</function>
|
|
</pre></div>
|
|
<p>Then the stylesheet could generate hyperlinks between the
|
|
references and definitions as follows:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<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>
|
|
</pre></div>
|
|
</div>
|
|
<p>When called with two arguments, the <a href=
|
|
"#function-key"><code>key</code></a> function always returns nodes
|
|
that are in the same document as the context node. To retrieve a
|
|
node from any other document, it is necessary either to change the
|
|
context node, or to supply a third argument.</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e34961" id=
|
|
"d7e34961"></a>Example: Using Keys to Reference other
|
|
Documents</div>
|
|
<p>For example, suppose a document contains bibliographic
|
|
references in the form
|
|
<code><bibref>XSLT</bibref></code>, and there is a
|
|
separate XML document <code>bib.xml</code> containing a
|
|
bibliographic database with entries in the form:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<entry name="XSLT">...</entry>
|
|
</pre></div>
|
|
<p>Then the stylesheet could use the following to transform the
|
|
<code>bibref</code> elements:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<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>
|
|
</pre></div>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>This relies on the ability in XPath 2.0 to have a function call
|
|
on the right-hand side of the <code>/</code> operator in a path
|
|
expression.</p>
|
|
</div>
|
|
<p>The following code would also work:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:key name="bib" match="entry" use="@name"/>
|
|
|
|
<xsl:template match="bibref">
|
|
<xsl:apply-templates select="key('bib', ., document('bib.xml'))"/>
|
|
</xsl:template>
|
|
</pre></div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="defining-decimal-format" id=
|
|
"defining-decimal-format"></a>19.4 <a href=
|
|
"#defining-decimal-format" style="text-decoration: none">Defining a
|
|
Decimal Format</a></h3>
|
|
<p class="element-syntax"><a name="element-decimal-format" id=
|
|
"element-decimal-format"></a><code><!-- Category: declaration
|
|
--><br />
|
|
<xsl:decimal-format<br />
|
|
  name? = <var>qname</var><br />
|
|
  decimal-separator? = <var>char</var><br />
|
|
  grouping-separator? = <var>char</var><br />
|
|
  infinity? = <var>string</var><br />
|
|
  minus-sign? = <var>char</var><br />
|
|
  NaN? = <var>string</var><br />
|
|
  percent? = <var>char</var><br />
|
|
  per-mille? = <var>char</var><br />
|
|
  zero-digit? = <var>char</var><br />
|
|
  digit? = <var>char</var><br />
|
|
  pattern-separator? =
|
|
<var>char</var> /></code></p>
|
|
<p>The <a href=
|
|
"#element-decimal-format"><code>xsl:decimal-format</code></a>
|
|
element controls the interpretation of a <a title="picture string"
|
|
class="termref" href="#dt-picture-string">picture string</a> used
|
|
by the <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-format-number"><code>
|
|
format-number</code></a><sup><small>FO</small></sup> function.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-picture-string" id="dt-picture-string" title=
|
|
"picture string"></a>The <b>picture string</b> is the string
|
|
supplied as the second argument of the <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-format-number"><code>
|
|
format-number</code></a><sup><small>FO</small></sup>
|
|
function.<span class="definition">]</span></p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>The <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-format-number"><code>
|
|
format-number</code></a><sup><small>FO</small></sup> function,
|
|
previously defined in this specification, is now a core function
|
|
defined in <a href="#xpath-functions-11">[Functions and
|
|
Operators]</a>.</p>
|
|
</div>
|
|
<p>A <a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a> may contain multiple <a href=
|
|
"#element-decimal-format"><code>xsl:decimal-format</code></a>
|
|
declarations and may include or import <a title="stylesheet module"
|
|
class="termref" href="#dt-stylesheet-module">stylesheet modules</a>
|
|
that also contain <a href=
|
|
"#element-decimal-format"><code>xsl:decimal-format</code></a>
|
|
declarations. The name of an <a href=
|
|
"#element-decimal-format"><code>xsl:decimal-format</code></a>
|
|
declaration is the value of its <code>name</code> attribute, if
|
|
any.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-decimal-format" id="dt-decimal-format" title=
|
|
"decimal format"></a>All the <a href=
|
|
"#element-decimal-format"><code>xsl:decimal-format</code></a>
|
|
declarations in a stylesheet that share the same name are grouped
|
|
into a named <b>decimal format</b>; those that have no name are
|
|
grouped into a single unnamed decimal format.<span class=
|
|
"definition">]</span></p>
|
|
<p>If a <a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a> does not contain a declaration of
|
|
the unnamed decimal format, a declaration equivalent to an <a href=
|
|
"#element-decimal-format"><code>xsl:decimal-format</code></a>
|
|
element with no attributes is implied.</p>
|
|
<p>The attributes of the <a href=
|
|
"#element-decimal-format"><code>xsl:decimal-format</code></a>
|
|
declaration establish values for a number of variables used as
|
|
input to the algorithm followed by the <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-format-number"><code>
|
|
format-number</code></a><sup><small>FO</small></sup> function. An
|
|
outline of the purpose of each attribute is given below; however,
|
|
the definitive explanations are given <span>as part of the
|
|
specification of <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-format-number"><code>
|
|
format-number</code></a><sup><small>FO</small></sup></span>.</p>
|
|
<p>For any named <a title="decimal format" class="termref" href=
|
|
"#dt-decimal-format">decimal format</a>, the effective value of
|
|
each attribute is taken from an <a href=
|
|
"#element-decimal-format"><code>xsl:decimal-format</code></a>
|
|
declaration that has that name, and that specifies an explicit
|
|
value for the required attribute. If there is no such declaration,
|
|
the default value of the attribute is used. If there is more than
|
|
one such declaration, the one with highest <a title=
|
|
"import precedence" class="termref" href=
|
|
"#dt-import-precedence">import precedence</a> is used.</p>
|
|
<p>For any unnamed <a title="decimal format" class="termref" href=
|
|
"#dt-decimal-format">decimal format</a>, the effective value of
|
|
each attribute is taken from an <a href=
|
|
"#element-decimal-format"><code>xsl:decimal-format</code></a>
|
|
declaration that is unnamed, and that specifies an explicit value
|
|
for the required attribute. If there is no such declaration, the
|
|
default value of the attribute is used. If there is more than one
|
|
such declaration, the one with highest <a title="import precedence"
|
|
class="termref" href="#dt-import-precedence">import precedence</a>
|
|
is used.</p>
|
|
<p><a name="err-XTSE1290" id="err-XTSE1290"><span class=
|
|
"error">[ERR XTSE1290]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> if a named
|
|
or unnamed <a title="decimal format" class="termref" href=
|
|
"#dt-decimal-format">decimal format</a> contains two conflicting
|
|
values for the same attribute in different <a href=
|
|
"#element-decimal-format"><code>xsl:decimal-format</code></a>
|
|
declarations having the same <a title="import precedence" class=
|
|
"termref" href="#dt-import-precedence">import precedence</a>,
|
|
unless there is another definition of the same attribute with
|
|
higher import precedence.</p>
|
|
<p>The following attributes control the interpretation of
|
|
characters in the <a title="picture string" class="termref" href=
|
|
"#dt-picture-string">picture string</a> supplied to the <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-format-number"><code>
|
|
format-number</code></a><sup><small>FO</small></sup> function, and
|
|
also specify characters that may appear in the result of formatting
|
|
the number. In each case the value <span class="verb">must</span>
|
|
be a single character <span class="error">[see <a href=
|
|
"#err-XTSE0020">ERR XTSE0020</a>]</span>.</p>
|
|
<ul>
|
|
<li>
|
|
<p><code>decimal-separator</code> specifies the character used for
|
|
the <var>decimal-separator-sign</var>; the default value is the
|
|
period character (<code>.</code>)</p>
|
|
</li>
|
|
<li>
|
|
<p><code>grouping-separator</code> specifies the character used for
|
|
the <var>grouping-sign</var>, which is typically used as a
|
|
thousands separator; the default value is the comma character
|
|
(<code>,</code>)</p>
|
|
</li>
|
|
<li>
|
|
<p><code>percent</code> specifies the character used for the
|
|
<var>percent-sign</var>; the default value is the percent character
|
|
(<code>%</code>)</p>
|
|
</li>
|
|
<li>
|
|
<p><code>per-mille</code> specifies the character used for the
|
|
<var>per-mille-sign</var>; the default value is the Unicode
|
|
per-mille character (#x2030)</p>
|
|
</li>
|
|
<li>
|
|
<p><code>zero-digit</code> specifies the character used for the
|
|
<var>digit-zero-sign</var>; the default value is the digit zero
|
|
(<code>0</code>). This character <span class="verb">must</span> be
|
|
a digit (category Nd in the Unicode property database), and it
|
|
<span class="verb">must</span> have the numeric value zero. This
|
|
attribute implicitly defines the Unicode character that is used to
|
|
represent each of the values 0 to 9 in the final result string:
|
|
Unicode is organized so that each set of decimal digits forms a
|
|
contiguous block of characters in numerical sequence.</p>
|
|
</li>
|
|
</ul>
|
|
<p><a name="err-XTSE1295" id="err-XTSE1295"><span class=
|
|
"error">[ERR XTSE1295]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> if the
|
|
character specified in the <code>zero-digit</code> attribute is not
|
|
a digit or is a digit that does not have the numeric value
|
|
zero.</p>
|
|
<p>The following attributes control the interpretation of
|
|
characters in the <a title="picture string" class="termref" href=
|
|
"#dt-picture-string">picture string</a> supplied to the <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-format-number"><code>
|
|
format-number</code></a><sup><small>FO</small></sup> function. In
|
|
each case the value <span class="verb">must</span> be a single
|
|
character <span class="error">[see <a href="#err-XTSE0020">ERR
|
|
XTSE0020</a>]</span>.</p>
|
|
<ul>
|
|
<li>
|
|
<p><code>digit</code> specifies the character used for the
|
|
<var>digit-sign</var> in the <a title="picture string" class=
|
|
"termref" href="#dt-picture-string">picture string</a>; the default
|
|
value is the number sign character (<code>#</code>)</p>
|
|
</li>
|
|
<li>
|
|
<p><code>pattern-separator</code> specifies the character used for
|
|
the <var>pattern-separator-sign</var>, which separates positive and
|
|
negative sub-pictures in a <a title="picture string" class=
|
|
"termref" href="#dt-picture-string">picture string</a>; the default
|
|
value is the semi-colon character (<code>;</code>)</p>
|
|
</li>
|
|
</ul>
|
|
<p>The following attributes specify characters or strings that may
|
|
appear in the result of formatting the number:</p>
|
|
<ul>
|
|
<li>
|
|
<p><code>infinity</code> specifies the string used for the
|
|
<var>infinity-symbol</var>; the default value is the string
|
|
<code>Infinity</code></p>
|
|
</li>
|
|
<li>
|
|
<p><code>NaN</code> specifies the string used for the
|
|
<var>NaN-symbol</var>, which is used to represent the value NaN
|
|
(not-a-number); the default value is the string
|
|
<code>NaN</code></p>
|
|
</li>
|
|
<li>
|
|
<p><code>minus-sign</code> specifies the character used for the
|
|
<var>minus-symbol</var>; the default value is the hyphen-minus
|
|
character (<code>-</code>, #x2D). The value <span class=
|
|
"verb">must</span> be a single character.</p>
|
|
</li>
|
|
</ul>
|
|
<p><a name="err-XTSE1300" id="err-XTSE1300"><span class=
|
|
"error">[ERR XTSE1300]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> if, for
|
|
any named or unnamed decimal format, the variables representing
|
|
characters used in a <a title="picture string" class="termref"
|
|
href="#dt-picture-string">picture string</a> do not each have
|
|
distinct values. These variables are
|
|
<var>decimal-separator-sign</var>, <var>grouping-sign</var>,
|
|
<var>percent-sign</var>, <var>per-mille-sign</var>,
|
|
<var>digit-zero-sign</var>, <var>digit-sign</var>, and
|
|
<var>pattern-separator-sign</var>.</p>
|
|
<p>Every (named or unnamed) decimal format defined in the <a title=
|
|
"stylesheet" class="termref" href="#dt-stylesheet">stylesheet</a>
|
|
is added to the <a href=
|
|
"http://www.w3.org/TR/xpath-21/#dt-static-decimal-formats">statically
|
|
known decimal formats</a><sup><small>XP21</small></sup> in the
|
|
<a href="http://www.w3.org/TR/xpath-21/#dt-static-context">static
|
|
context</a><sup><small>XP21</small></sup> of every expression in
|
|
the <a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a>, excluding expressions appearing in
|
|
<code>[xsl:]use-when</code> attributes.</p>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="misc-func" id="misc-func"></a>19.5 <a href=
|
|
"#misc-func" style="text-decoration: none">Miscellaneous Additional
|
|
Functions</a></h3>
|
|
<div class="div3">
|
|
<h4><a name="current-function" id="current-function"></a>19.5.1
|
|
<a href="#current-function" style=
|
|
"text-decoration: none">current</a></h4>
|
|
<a name="function-current" id="function-current"></a>
|
|
<div class="proto"><code class=
|
|
"function">current</code>()<code class=
|
|
"as"> as </code><code class=
|
|
"return-type">item()</code></div>
|
|
<p>The <a href="#function-current"><code>current</code></a>
|
|
function, used within an XPath <a title="expression" class=
|
|
"termref" href="#dt-expression">expression</a>, returns the item
|
|
that was the <a title="context item" class="termref" href=
|
|
"#dt-context-item">context item</a> at the point where the
|
|
expression was invoked from the XSLT <a title="stylesheet" class=
|
|
"termref" href="#dt-stylesheet">stylesheet</a>. 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,</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:value-of select="current()"/>
|
|
</pre></div>
|
|
<p>means the same as</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:value-of select="."/>
|
|
</pre></div>
|
|
<p>However, within square brackets, or on the right-hand side of
|
|
the <code>/</code> operator, the current item is generally
|
|
different from the context item.</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e36065" id=
|
|
"d7e36065"></a>Example: Using the <code>current</code>
|
|
Function</div>
|
|
<p>For example,</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:apply-templates select="//glossary/entry[@name=current()/@ref]"/>
|
|
</pre></div>
|
|
<p>will process all <code>entry</code> elements that have a
|
|
<code>glossary</code> parent element and that have a
|
|
<code>name</code> attribute with value equal to the value of the
|
|
current item's <code>ref</code> attribute. This is different
|
|
from</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:apply-templates select="//glossary/entry[@name=./@ref]"/>
|
|
</pre></div>
|
|
<p>which means the same as</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:apply-templates select="//glossary/entry[@name=@ref]"/>
|
|
</pre></div>
|
|
<p>and so would process all <code>entry</code> elements that have a
|
|
<code>glossary</code> parent element and that have a
|
|
<code>name</code> attribute and a <code>ref</code> attribute with
|
|
the same value.</p>
|
|
</div>
|
|
<p>If the <a href="#function-current"><code>current</code></a>
|
|
function is used within a <a title="pattern" class="termref" href=
|
|
"#dt-pattern">pattern</a>, its value is the <span>item</span> that
|
|
is being matched against the pattern.</p>
|
|
<p><a name="err-XTDE1360" id="err-XTDE1360"><span class=
|
|
"error">[ERR XTDE1360]</span></a> If the <a href=
|
|
"#function-current"><code>current</code></a> function is evaluated
|
|
within an expression that is evaluated when the context item is
|
|
undefined, a <a title="non-recoverable dynamic error" class=
|
|
"termref" href="#dt-nonrec-dynamic-error">non-recoverable dynamic
|
|
error</a> occurs.</p>
|
|
</div>
|
|
<div class="div3">
|
|
<h4><a name="unparsed-entity-uri" id=
|
|
"unparsed-entity-uri"></a>19.5.2 <a href="#unparsed-entity-uri"
|
|
style="text-decoration: none">unparsed-entity-uri</a></h4>
|
|
<a name="function-unparsed-entity-uri" id=
|
|
"function-unparsed-entity-uri"></a>
|
|
<div class="proto"><code class=
|
|
"function">unparsed-entity-uri</code>(<code class=
|
|
"arg">$entity-name</code><code class=
|
|
"as"> as </code><code class=
|
|
"type">xs:string</code>)<code class=
|
|
"as"> as </code><code class=
|
|
"return-type">xs:anyURI</code></div>
|
|
<p>The <a href=
|
|
"#function-unparsed-entity-uri"><code>unparsed-entity-uri</code></a>
|
|
function returns the URI of the unparsed entity whose name is given
|
|
by the value of the <code>$entity-name</code> argument, in the
|
|
document containing the <a title="context node" class="termref"
|
|
href="#dt-context-node">context node</a>. It returns the
|
|
zero-length <code>xs:anyURI</code> if there is no such entity. This
|
|
function maps to the <code>dm:unparsed-entity-system-id</code>
|
|
accessor defined in <a href="#xpath-datamodel-11">[Data
|
|
Model]</a>.</p>
|
|
<p><a name="err-XTDE1370" id="err-XTDE1370"><span class=
|
|
"error">[ERR XTDE1370]</span></a> It is a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> if the
|
|
<a href=
|
|
"#function-unparsed-entity-uri"><code>unparsed-entity-uri</code></a>
|
|
function is called when there is no <a title="context node" class=
|
|
"termref" href="#dt-context-node">context node</a>, or when the
|
|
root of the tree containing the context node is not a document
|
|
node.</p>
|
|
</div>
|
|
<div class="div3">
|
|
<h4><a name="unparsed-entity-public-id" id=
|
|
"unparsed-entity-public-id"></a>19.5.3 <a href=
|
|
"#unparsed-entity-public-id" style=
|
|
"text-decoration: none">unparsed-entity-public-id</a></h4>
|
|
<a name="function-unparsed-entity-public-id" id=
|
|
"function-unparsed-entity-public-id"></a>
|
|
<div class="proto"><code class=
|
|
"function">unparsed-entity-public-id</code>(<code class=
|
|
"arg">$entity-name</code><code class=
|
|
"as"> as </code><code class=
|
|
"type">xs:string</code>)<code class=
|
|
"as"> as </code><code class=
|
|
"return-type">xs:string</code></div>
|
|
<p>The <a href=
|
|
"#function-unparsed-entity-public-id"><code>unparsed-entity-public-id</code></a>
|
|
function returns the public identifier of the unparsed entity whose
|
|
name is given by the value of the <code>$entity-name</code>
|
|
argument, in the document containing the <a title="context node"
|
|
class="termref" href="#dt-context-node">context node</a>. It
|
|
returns the zero-length string if there is no such entity, or if
|
|
the entity has no public identifier. This function maps to the
|
|
<code>dm:unparsed-entity-public-id</code> accessor defined in
|
|
<a href="#xpath-datamodel-11">[Data Model]</a>.</p>
|
|
<p><a name="err-XTDE1380" id="err-XTDE1380"><span class=
|
|
"error">[ERR XTDE1380]</span></a> It is a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> if the
|
|
<a href=
|
|
"#function-unparsed-entity-public-id"><code>unparsed-entity-public-id</code></a>
|
|
function is called when there is no <a title="context node" class=
|
|
"termref" href="#dt-context-node">context node</a>, or when the
|
|
root of the tree containing the context node is not a document
|
|
node.</p>
|
|
</div>
|
|
<div class="div3">
|
|
<h4><a name="system-property" id="system-property"></a>19.5.4
|
|
<a href="#system-property" style=
|
|
"text-decoration: none">system-property</a></h4>
|
|
<a name="function-system-property" id=
|
|
"function-system-property"></a>
|
|
<div class="proto"><code class=
|
|
"function">system-property</code>(<code class=
|
|
"arg">$property-name</code><code class=
|
|
"as"> as </code><code class=
|
|
"type">xs:string</code>)<code class=
|
|
"as"> as </code><code class=
|
|
"return-type">xs:string</code></div>
|
|
<p>The <code>$property-name</code> argument <span class=
|
|
"verb">must</span> evaluate to a <a title="lexical QName" class=
|
|
"termref" href="#dt-lexical-qname">lexical QName</a>. The <a title=
|
|
"lexical QName" class="termref" href="#dt-lexical-qname">lexical
|
|
QName</a> is expanded as described in <a href="#qname"><i>5.1
|
|
Qualified Names</i></a>.</p>
|
|
<p><a name="err-XTDE1390" id="err-XTDE1390"><span class=
|
|
"error">[ERR XTDE1390]</span></a> It is a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> if the
|
|
value is not a valid QName, or if there is no namespace declaration
|
|
in scope for the prefix of the QName. If the processor is able to
|
|
detect the error statically (for example, when the argument is
|
|
supplied as a string literal), then the processor <span class=
|
|
"verb">may</span> optionally signal this as a <a title=
|
|
"static error" class="termref" href="#dt-static-error">static
|
|
error</a>.</p>
|
|
<p>The <a href=
|
|
"#function-system-property"><code>system-property</code></a>
|
|
function returns a string representing the value of the system
|
|
property identified by the name. If there is no such system
|
|
property, the zero-length string is returned.</p>
|
|
<p>Implementations <span class="verb">must</span> provide the
|
|
following system properties, which are all in the <a title=
|
|
"XSLT namespace" class="termref" href="#dt-xslt-namespace">XSLT
|
|
namespace</a>:</p>
|
|
<ul>
|
|
<li>
|
|
<p><code>xsl:version</code>, a number giving the version of XSLT
|
|
implemented by the <a title="processor" class="termref" href=
|
|
"#dt-processor">processor</a>; for implementations conforming to
|
|
the version of XSLT specified by this document, this is the string
|
|
<span><code>"2.1"</code></span>. The value will always be a string
|
|
in the lexical space of the decimal data type defined in XML Schema
|
|
(see <a href="#xmlschema-2">[XML Schema Part 2]</a>). This allows
|
|
the value to be converted to a number for the purpose of magnitude
|
|
comparisons.</p>
|
|
</li>
|
|
<li>
|
|
<p><code>xsl:vendor</code>, a string identifying the implementer of
|
|
the <a title="processor" class="termref" href=
|
|
"#dt-processor">processor</a></p>
|
|
</li>
|
|
<li>
|
|
<p><code>xsl:vendor-url</code>, a string containing a URL
|
|
identifying the implementer of the <a title="processor" class=
|
|
"termref" href="#dt-processor">processor</a>; typically this is the
|
|
host page (home page) of the implementer's Web site.</p>
|
|
</li>
|
|
<li>
|
|
<p><code>xsl:product-name</code>, a string containing the name of
|
|
the implementation, as defined by the implementer. This
|
|
<span class="verb">should</span> normally remain constant from one
|
|
release of the product to the next. It <span class=
|
|
"verb">should</span> also be constant across platforms in cases
|
|
where the same source code is used to produce compatible products
|
|
for multiple execution platforms.</p>
|
|
</li>
|
|
<li>
|
|
<p><code>xsl:product-version</code>, a string identifying the
|
|
version of the implementation, as defined by the implementer. This
|
|
<span class="verb">should</span> normally vary from one release of
|
|
the product to the next, and at the discretion of the implementer
|
|
it <span class="verb">may</span> also vary across different
|
|
execution platforms.</p>
|
|
</li>
|
|
<li>
|
|
<p><code>xsl:is-schema-aware</code>, returns the string
|
|
<code>"yes"</code> in the case of a processor that claims
|
|
conformance as a <a title="schema-aware XSLT processor" class=
|
|
"termref" href="#dt-schema-aware-xslt-processor">schema-aware XSLT
|
|
processor</a>, or <code>"no"</code> in the case of a <a title=
|
|
"basic XSLT processor" class="termref" href=
|
|
"#dt-basic-xslt-processor">basic XSLT processor</a>.</p>
|
|
</li>
|
|
<li>
|
|
<p><code>xsl:supports-serialization</code>, returns the string
|
|
<code>"yes"</code> in the case of a processor that offers the
|
|
<a title="serialization feature" class="termref" href=
|
|
"#dt-serialization-feature">serialization feature</a>, or
|
|
<code>"no"</code> otherwise.</p>
|
|
</li>
|
|
<li>
|
|
<p><code>xsl:supports-backwards-compatibility</code>, returns the
|
|
string <code>"yes"</code> in the case of a processor that offers
|
|
the <span><a title="XSLT 1.0 compatibility feature" class="termref"
|
|
href="#dt-1.0-compatibility-feature">XSLT 1.0 compatibility
|
|
feature</a></span>, or <code>"no"</code> otherwise.</p>
|
|
</li>
|
|
<li>
|
|
<p><code>xsl:supports-1.0-compatibility</code>, returns the string
|
|
<code>"yes"</code> in the case of a processor that offers the
|
|
<a title="XSLT 1.0 compatibility feature" class="termref" href=
|
|
"#dt-1.0-compatibility-feature">XSLT 1.0 compatibility feature</a>,
|
|
or <code>"no"</code> otherwise.</p>
|
|
</li>
|
|
<li>
|
|
<p><code>xsl:supports-2.0-compatibility</code>, returns the string
|
|
<code>"yes"</code> in the case of a processor that offers the
|
|
<a title="XSLT 2.0 compatibility feature" class="termref" href=
|
|
"#dt-2.0-compatibility-feature">XSLT 2.0 compatibility feature</a>,
|
|
or <code>"no"</code> otherwise.</p>
|
|
</li>
|
|
<li>
|
|
<p><code>xsl:supports-namespace-axis</code>, returns the string
|
|
<code>"yes"</code> in the case of a processor that offers the XPath
|
|
namespace axis even when not in backwards compatible mode, or
|
|
<code>"no"</code> otherwise. Note that a processor that supports
|
|
backwards compatible mode must support the namespace axis when in
|
|
that mode, so this property is not relevant to that case.</p>
|
|
</li>
|
|
<li>
|
|
<p><code>xsl:supports-streaming</code>, returns the string
|
|
<code>"yes"</code> in the case of a processor that offers the
|
|
streaming feature (see <a href="#streaming-feature"><i>24.5
|
|
Streaming Feature</i></a>), or <code>"no"</code> otherwise.</p>
|
|
</li>
|
|
</ul>
|
|
<p>Some of these properties relate to the conformance levels and
|
|
features offered by the <a title="processor" class="termref" href=
|
|
"#dt-processor">processor</a>: these options are described in
|
|
<a href="#conformance"><i>24 Conformance</i></a>.</p>
|
|
<p>The actual values returned for the above properties are
|
|
<a title="implementation-defined" class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a>.</p>
|
|
<p>The set of system properties that are supported, in addition to
|
|
those listed above, is also <a title="implementation-defined"
|
|
class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a>.
|
|
Implementations <span class="verb">must not</span> define
|
|
additional system properties in the XSLT namespace.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>An implementation must not return the value
|
|
<code><span>2.1</span></code> as the value of the
|
|
<code>xsl:version</code> system property unless it is conformant to
|
|
XSLT <span>2.1</span>.</p>
|
|
<p>It is recognized that vendors who are enhancing XSLT 1.0
|
|
<span>or 2.0</span> 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.1, this specification cannot define their
|
|
behavior. However, implementers of such products are encouraged to
|
|
return a value for the <code>xsl:version</code> system property
|
|
that is intermediate between 1.0 and 2.1, and to provide the
|
|
<a href=
|
|
"#function-element-available"><code>element-available</code></a>
|
|
and <a href=
|
|
"#function-function-available"><code>function-available</code></a>
|
|
functions to allow users to test which features have been fully
|
|
implemented.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="context-dependent-functions" id=
|
|
"context-dependent-functions"></a>19.7 <a href=
|
|
"#context-dependent-functions" style=
|
|
"text-decoration: none">Function items and
|
|
context-dependency</a></h3>
|
|
<p><em>This section describes unfinished work.</em></p>
|
|
<p>The XPath 2.1 specification introduces the ability for functions
|
|
to be manipulated as values. In the draft of XPath 2.1 that is
|
|
current at the time of writing, there are no rules describing how
|
|
context-dependent function items (such as <code>position#0</code>
|
|
or <code>static-base-uri#0</code>) are to be handled. The expected
|
|
resolution is that (a) binding a function item to a function that
|
|
depends on the static context (for example any function that
|
|
depends on the default collation) will use the static context at
|
|
the point where the function item is created, while (b) binding of
|
|
function items to functions that depend on non-stable parts of the
|
|
dynamic context (for example <code>position#0</code> or
|
|
<code>name#0</code>) will not be allowed.</p>
|
|
<p>Similar rules may need to be defined for XSLT-specific functions
|
|
such as <a href="#function-key"><code>key</code></a> or <a href=
|
|
"#function-current-group"><code>current-group</code></a> that
|
|
depend on the XSLT-specific parts of the static and dynamic
|
|
context.</p>
|
|
<blockquote>
|
|
<p><b><a name="issue-context-dependent-functions" id=
|
|
"issue-context-dependent-functions">Issue 33
|
|
(context-dependent-functions)</a>:</b></p>
|
|
<p>The rules for binding of function items to context-dependent
|
|
functions need to be defined.</p>
|
|
</blockquote>
|
|
</div>
|
|
</div>
|
|
<div class="div1">
|
|
<h2><a name="message" id="message"></a>20 <a href="#message" style=
|
|
"text-decoration: none">Messages</a></h2>
|
|
<p class="element-syntax"><a name="element-message" id=
|
|
"element-message"></a><code><!-- Category: instruction
|
|
--><br />
|
|
<xsl:message<br />
|
|
  select? = <var>expression</var><br />
|
|
  terminate? = { "yes" | "no" }<br />
|
|
  error-code? = { <var>QName</var> } ><br />
|
|
  <!-- Content: <var>sequence-constructor</var>
|
|
--><br />
|
|
</xsl:message></code></p>
|
|
<p>The <a href="#element-message"><code>xsl:message</code></a>
|
|
instruction sends a message in an <a title="implementation-defined"
|
|
class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a> way. The
|
|
<a href="#element-message"><code>xsl:message</code></a> instruction
|
|
causes the creation of a new document, which is typically
|
|
serialized and output to an <a title="implementation-defined"
|
|
class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a>
|
|
destination. The result of the <a href=
|
|
"#element-message"><code>xsl:message</code></a> instruction is an
|
|
empty sequence.</p>
|
|
<p>The content of the message may be specified by using either or
|
|
both of the optional <code>select</code> attribute and the
|
|
<a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> that forms the
|
|
content of the <a href=
|
|
"#element-message"><code>xsl:message</code></a> instruction.</p>
|
|
<p>If the <a href="#element-message"><code>xsl:message</code></a>
|
|
instruction contains a <a title="sequence constructor" class=
|
|
"termref" href="#dt-sequence-constructor">sequence constructor</a>,
|
|
then the sequence obtained by evaluating this sequence constructor
|
|
is used to construct the content of the new document node, as
|
|
described in <a href="#constructing-complex-content"><i>5.7.1
|
|
Constructing Complex Content</i></a>.</p>
|
|
<p>If the <a href="#element-message"><code>xsl:message</code></a>
|
|
instruction has a <code>select</code> attribute, then the value of
|
|
the attribute <span class="verb">must</span> be an XPath
|
|
expression. The effect of the <a href=
|
|
"#element-message"><code>xsl:message</code></a> instruction is then
|
|
the same as if a single <a href=
|
|
"#element-copy-of"><code>xsl:copy-of</code></a> instruction with
|
|
this <code>select</code> attribute were added to the start of the
|
|
<a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a>.</p>
|
|
<p>If the <a href="#element-message"><code>xsl:message</code></a>
|
|
instruction has no content and no <code>select</code> attribute,
|
|
then an empty message is produced.</p>
|
|
<p>The tree produced by the <a href=
|
|
"#element-message"><code>xsl:message</code></a> instruction is not
|
|
technically a <a title="final result tree" class="termref" href=
|
|
"#dt-final-result-tree">final result tree</a>. The tree has no URI
|
|
and processors are not <span class="verb">required</span> to make
|
|
the tree accessible to applications.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>In many cases, the XML document produced using <a href=
|
|
"#element-message"><code>xsl:message</code></a> will consist of a
|
|
document node owning a single text node. However, it may contain a
|
|
more complex structure.</p>
|
|
</div>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>An implementation might implement <a href=
|
|
"#element-message"><code>xsl:message</code></a> by popping up an
|
|
alert box or by writing to a log file. Because the order of
|
|
execution of instructions is implementation-defined, the order in
|
|
which such messages appear is not predictable.</p>
|
|
</div>
|
|
<p>The <code>terminate</code> attribute is interpreted as an
|
|
<a title="attribute value template" class="termref" href=
|
|
"#dt-attribute-value-template">attribute value template</a>.</p>
|
|
<p>If the <a title="effective value" class="termref" href=
|
|
"#dt-effective-value">effective value</a> of the
|
|
<code>terminate</code> attribute is <code>yes</code>, then the
|
|
<a title="processor" class="termref" href=
|
|
"#dt-processor">processor</a> <span class="verb">must</span>
|
|
<span>signal a <a title="non-recoverable dynamic error" class=
|
|
"termref" href="#dt-nonrec-dynamic-error">non-recoverable dynamic
|
|
error</a></span> after sending the message. <span>This error may be
|
|
caught in the same way as any other dynamic error using <a href=
|
|
"#element-catch"><code>xsl:catch</code></a>.</span> The default
|
|
value is <code>no</code>. Note that because the order of evaluation
|
|
of instructions is <a title="implementation-dependent" class=
|
|
"termref" href=
|
|
"#dt-implementation-dependent">implementation-dependent</a>, this
|
|
gives no guarantee that any particular instruction will or will not
|
|
be evaluated before processing terminates.</p>
|
|
<p>The optional <code>error-code</code> attribute may be used to
|
|
indicate the error code associated with the message. This may be
|
|
used irrespective of the value of <code>terminate</code>. The error
|
|
code is a <a title="QName" class="termref" href=
|
|
"#dt-qname">QName</a>, supplied as a <a title="lexical QName"
|
|
class="termref" href="#dt-lexical-qname">lexical QName</a>. If no
|
|
error code is specified, or if the value is not a valid QName, the
|
|
error code will have local part <code>XTMM9000</code> and namespace
|
|
URI <code>http://www.w3.org/2005/xqt-errors</code>. User-defined
|
|
error codes <span class="verb">should</span> be in a namespace
|
|
other than <code>http://www.w3.org/2005/xqt-errors</code>. When the
|
|
value of <code>terminate</code> is <code>yes</code>, the error code
|
|
may be matched in an <a href=
|
|
"#element-catch"><code>xsl:catch</code></a> element to catch the
|
|
error and cause processing to continue normally.</p>
|
|
<p><a name="err-XTMM9000" id="err-XTMM9000"><span class=
|
|
"error">[ERR XTMM9000]</span></a> When a transformation is
|
|
terminated by use of <code>xsl:message terminate="yes"</code>, the
|
|
effect is the same as when a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> occurs
|
|
during the transformation. <span>The default error code is
|
|
<code>XTMM9000</code>; this may be overridden using the
|
|
<code>error-code</code> attribute of the <a href=
|
|
"#element-message"><code>xsl:message</code></a>
|
|
instruction.</span></p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e38029" id=
|
|
"d7e38029"></a>Example: Localizing Messages</div>
|
|
<p>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 <a title="stylesheet" class=
|
|
"termref" href="#dt-stylesheet">stylesheet</a>. For example,
|
|
suppose messages for a language <code><var>L</var></code> are
|
|
stored in an XML file <code>resources/<var>L</var>.xml</code> in
|
|
the form:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<messages>
|
|
<message name="problem">A problem was detected.</message>
|
|
<message name="error">An error was detected.</message>
|
|
</messages>
|
|
</pre></div>
|
|
<p>Then a stylesheet could use the following approach to localize
|
|
messages:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<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 select="string($messages/message[@name=$name])"/>
|
|
</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>
|
|
</pre></div>
|
|
</div>
|
|
<p>Any <a title="dynamic error" class="termref" href=
|
|
"#dt-dynamic-error">dynamic error</a> that occurs while evaluating
|
|
the <code>select</code> expression or the contained <a title=
|
|
"sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a>, and any
|
|
<a title="serialization error" class="termref" href=
|
|
"#dt-serialization-error">serialization error</a> that occurs while
|
|
processing the result, is treated as a <a title="recoverable error"
|
|
class="termref" href="#dt-recoverable-error">recoverable error</a>
|
|
even if the error would not be recoverable under other
|
|
circumstances. The <a title="optional recovery action" class=
|
|
"termref" href="#dt-optional-recovery-action">optional recovery
|
|
action</a> is <a title="implementation-dependent" class="termref"
|
|
href=
|
|
"#dt-implementation-dependent">implementation-dependent</a>.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>An example of such an error is the serialization error that
|
|
occurs when processing the instruction <code><xsl:message
|
|
select="@code"/></code> (on the grounds that free-standing
|
|
attributes cannot be serialized). Making such errors recoverable
|
|
means that it is implementation-defined whether or not they are
|
|
signaled to the user and whether they cause termination of the
|
|
transformation. If the processor chooses to recover from the error,
|
|
the content of any resulting message is
|
|
implementation-dependent.</p>
|
|
<p>One possible recovery action is to include a description of the
|
|
error in the generated message text.</p>
|
|
</div>
|
|
</div>
|
|
<div class="div1">
|
|
<h2><a name="extension" id="extension"></a>21 <a href="#extension"
|
|
style="text-decoration: none">Extensibility and Fallback</a></h2>
|
|
<p>XSLT allows two kinds of extension, extension instructions and
|
|
extension functions.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-extension-instruction" id="dt-extension-instruction" title=
|
|
"extension instruction"></a>An <b>extension instruction</b> is an
|
|
element within a <a title="sequence constructor" class="termref"
|
|
href="#dt-sequence-constructor">sequence constructor</a> that is in
|
|
a namespace (not the <a title="XSLT namespace" class="termref"
|
|
href="#dt-xslt-namespace">XSLT namespace</a>) designated as an
|
|
extension namespace.<span class="definition">]</span></p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-extension-function" id="dt-extension-function" title=
|
|
"extension function"></a>An <b>extension function</b> is a function
|
|
that is available for use within an XPath <a title="expression"
|
|
class="termref" href="#dt-expression">expression</a>, other than a
|
|
<a title="core function" class="termref" href=
|
|
"#dt-core-function">core function</a> defined in <a href=
|
|
"#xpath-functions-11">[Functions and Operators]</a>, an additional
|
|
function defined in this XSLT specification, a constructor function
|
|
named after an atomic type, or a <a title="stylesheet function"
|
|
class="termref" href="#dt-stylesheet-function">stylesheet
|
|
function</a> defined using an <a href=
|
|
"#element-function"><code>xsl:function</code></a>
|
|
declaration.<span class="definition">]</span>.</p>
|
|
<p>This specification does not define any mechanism for creating or
|
|
binding implementations of <a title="extension instruction" class=
|
|
"termref" href="#dt-extension-instruction">extension
|
|
instructions</a> or <a title="extension function" class="termref"
|
|
href="#dt-extension-function">extension functions</a>, and it is
|
|
not <span class="verb">required</span> that implementations support
|
|
any such mechanism. Such mechanisms, if they exist, are <a title=
|
|
"implementation-defined" class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a>. Therefore,
|
|
an XSLT stylesheet that <span class="verb">must</span> 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 happens 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.</p>
|
|
<div class="div2">
|
|
<h3><a name="extension-functions" id="extension-functions"></a>21.1
|
|
<a href="#extension-functions" style=
|
|
"text-decoration: none">Extension Functions</a></h3>
|
|
<p>The set of functions that can be called from a <a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-FunctionCall">FunctionCall</a><sup><small>XP21</small></sup>
|
|
within an XPath <a title="expression" class="termref" href=
|
|
"#dt-expression">expression</a> may include one or more <a title=
|
|
"extension function" class="termref" href=
|
|
"#dt-extension-function">extension functions</a>. The <a title=
|
|
"expanded-QName" class="termref" href=
|
|
"#dt-expanded-qname">expanded-QName</a> of an extension function
|
|
always has a non-null namespace URI.</p>
|
|
<div class="div3">
|
|
<h4><a name="testing-function-availability" id=
|
|
"testing-function-availability"></a>21.1.1 <a href=
|
|
"#testing-function-availability" style=
|
|
"text-decoration: none">Testing Availability of Functions</a></h4>
|
|
<p>The <a href=
|
|
"#function-function-available"><code>function-available</code></a>
|
|
function can be used with the <code>[xsl:]use-when</code> attribute
|
|
(see <a href="#conditional-inclusion"><i>3.12 Conditional Element
|
|
Inclusion</i></a>) to explicitly control how a stylesheet behaves
|
|
if a particular extension function is not available.</p>
|
|
<a name="function-function-available" id=
|
|
"function-function-available"></a>
|
|
<div class="proto"><code class=
|
|
"function">function-available</code>(<code class=
|
|
"arg">$function-name</code><code class=
|
|
"as"> as </code><code class=
|
|
"type">xs:string</code>)<code class=
|
|
"as"> as </code><code class=
|
|
"return-type">xs:boolean</code></div>
|
|
<div class="proto">
|
|
<table border="0" cellpadding="0" cellspacing="0">
|
|
<tr>
|
|
<td valign="baseline" rowspan="2"><code class=
|
|
"function">function-available</code>(</td>
|
|
<td valign="baseline"><code class="arg">$function-name</code></td>
|
|
<td valign="baseline"><code class=
|
|
"as"> as </code><code class="type">xs:string</code>,</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="baseline"><code class="arg">$arity</code></td>
|
|
<td valign="baseline"><code class=
|
|
"as"> as </code><code class=
|
|
"type">xs:integer</code>)<code class=
|
|
"as"> as </code><code class=
|
|
"return-type">xs:boolean</code></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<p>A function is said to be available within an XPath expression if
|
|
it is present in the <a href=
|
|
"http://www.w3.org/TR/xpath-21/#dt-function-signature">in-scope
|
|
functions</a><sup><small>XP21</small></sup> for that expression
|
|
(see <a href="#static-context"><i>5.4.1 Initializing the Static
|
|
Context</i></a>). Functions in the static context are uniquely
|
|
identified by the name of the function (a QName) in combination
|
|
with its <a title="arity" class="termref" href=
|
|
"#dt-arity">arity</a>.</p>
|
|
<p>The value of the <code>$function-name</code> argument
|
|
<span class="verb">must</span> be a string containing a <a title=
|
|
"lexical QName" class="termref" href="#dt-lexical-qname">lexical
|
|
QName</a>. The lexical QName is expanded into an <a title=
|
|
"expanded-QName" class="termref" href=
|
|
"#dt-expanded-qname">expanded-QName</a> using the namespace
|
|
declarations in scope for the <a title="expression" class="termref"
|
|
href="#dt-expression">expression</a>. If the lexical QName is
|
|
unprefixed, then the <a title="standard function namespace" class=
|
|
"termref" href="#dt-standard-function-namespace">standard function
|
|
namespace</a> is used in the expanded QName.</p>
|
|
<p>The two-argument version of the <a href=
|
|
"#function-function-available"><code>function-available</code></a>
|
|
function returns true if and only if there is an available function
|
|
whose name matches the value of the <code>$function-name</code>
|
|
argument and whose <a title="arity" class="termref" href=
|
|
"#dt-arity">arity</a> matches the value of the <code>$arity</code>
|
|
argument.</p>
|
|
<p>The single-argument version of the <a href=
|
|
"#function-function-available"><code>function-available</code></a>
|
|
function returns true if and only if there is at least one
|
|
available function (with some arity) whose name matches the value
|
|
of the <code>$function-name</code> argument.</p>
|
|
<p><a name="err-XTDE1400" id="err-XTDE1400"><span class=
|
|
"error">[ERR XTDE1400]</span></a> It is a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> if the
|
|
argument does not evaluate to a string that is a valid <a title=
|
|
"QName" class="termref" href="#dt-qname">QName</a>, or if there is
|
|
no namespace declaration in scope for the prefix of the <a title=
|
|
"QName" class="termref" href="#dt-qname">QName</a>. If the
|
|
processor is able to detect the error statically (for example, when
|
|
the argument is supplied as a string literal), then the processor
|
|
<span class="verb">may</span> optionally signal this as a <a title=
|
|
"static error" class="termref" href="#dt-static-error">static
|
|
error</a>.</p>
|
|
<p><span>When the containing expression is evaluated with <a title=
|
|
"XPath 1.0 compatibility mode" class="termref" href=
|
|
"#dt-xpath-compat-mode">XPath 1.0 compatibility mode</a> set to
|
|
true</span>, the <a href=
|
|
"#function-function-available"><code>function-available</code></a>
|
|
function returns false in respect of a function name and arity for
|
|
which no implementation is available (other than the fallback error
|
|
function that raises a dynamic error whenever it is called). This
|
|
means that it is possible (as in XSLT 1.0) to use logic such as the
|
|
following to test whether a function is available before calling
|
|
it:</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e38288" id=
|
|
"d7e38288"></a>Example: Calling an extension function with
|
|
backwards compatibility enabled</div>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<summary xsl:version="1.0">
|
|
<xsl:choose>
|
|
<xsl:when test="function-available('my:summary')">
|
|
<xsl:value-of select="my:summary()"/>
|
|
</xsl:when>
|
|
<xsl:otherwise>
|
|
<xsl:text>Summary not available</xsl:text>
|
|
</xsl:otherwise>
|
|
</xsl:choose>
|
|
</summary>
|
|
</pre></div>
|
|
</div>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>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 types
|
|
of the arguments expected.</p>
|
|
</div>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e38307" id=
|
|
"d7e38307"></a>Example: Stylesheet portable between XSLT 1.0, XSLT
|
|
2.0, and XSLT 2.1</div>
|
|
<p>A stylesheet that is designed to use XSLT 2.0 facilities when
|
|
running under an <span>XSLT 2.0 or XSLT 2.1 processor</span>, but
|
|
to fall back to XSLT 1.0 capabilities when not, might be written
|
|
using the code:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<out xsl:version="2.0">
|
|
<xsl:choose>
|
|
<xsl:when test="function-available('matches')">
|
|
<xsl:value-of select="matches($input, '[a-z]*')"/>
|
|
</xsl:when>
|
|
<xsl:otherwise>
|
|
<xsl:value-of select="string-length(
|
|
translate($in, 'abcdefghijklmnopqrstuvwxyz', '')) = 0"/>
|
|
</xsl:otherwise>
|
|
</xsl:choose>
|
|
</out>
|
|
</pre></div>
|
|
<p>Here an <span>XSLT 2.0 or XSLT 2.1</span> processor will always
|
|
take the <a href="#element-when"><code>xsl:when</code></a> branch,
|
|
while a 1.0 processor will follow the <a href=
|
|
"#element-otherwise"><code>xsl:otherwise</code></a> branch. The
|
|
single-argument version of the <a href=
|
|
"#function-function-available"><code>function-available</code></a>
|
|
function is used here, because that is the only version available
|
|
in XSLT 1.0. Under the rules of XSLT 1.0, the call on the
|
|
<code>matches</code> function is not an error, because it is never
|
|
evaluated.</p>
|
|
</div>
|
|
<p> </p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e38334" id=
|
|
"d7e38334"></a>Example: Stylesheet portable between XSLT 2.1 and a
|
|
future version of XSLT</div>
|
|
<p>A stylesheet that is designed to use facilities in some future
|
|
XSLT version when they are available, but to fall back to
|
|
<span>XSLT 2.0 or XSLT 2.1</span> capabilities when not, might be
|
|
written using code such as the following. This hypothesizes the
|
|
availability in some future version of a function <code>pad</code>
|
|
which pads a string to a fixed length with spaces:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:value-of select="pad($input, 10)"
|
|
use-when="function-available('pad', 2)"/>
|
|
<xsl:value-of select="concat($input, string-join(
|
|
for $i in 1 to 10 - string-length($input)
|
|
return ' ', ''))"
|
|
use-when="not(function-available('pad', 2))"/>
|
|
|
|
</pre></div>
|
|
<p>In this case the two-argument version of <a href=
|
|
"#function-function-available"><code>function-available</code></a>
|
|
is used, because there is no requirement for this code to run under
|
|
XSLT 1.0.</p>
|
|
</div>
|
|
</div>
|
|
<div class="div3">
|
|
<h4><a name="calling-extension-functions" id=
|
|
"calling-extension-functions"></a>21.1.2 <a href=
|
|
"#calling-extension-functions" style=
|
|
"text-decoration: none">Calling Extension Functions</a></h4>
|
|
<p>If the function name used in a <a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-FunctionCall">FunctionCall</a><sup><small>XP21</small></sup>
|
|
within an XPath <a title="expression" class="termref" href=
|
|
"#dt-expression">expression</a> identifies an extension function,
|
|
then to evaluate the <a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-FunctionCall">FunctionCall</a><sup><small>XP21</small></sup>,
|
|
the processor will first evaluate each of the arguments in the
|
|
<a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-FunctionCall">FunctionCall</a><sup><small>XP21</small></sup>.
|
|
If the processor has information about the data types expected by
|
|
the extension function, then it <span class="verb">may</span>
|
|
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
|
|
<span class="verb">may</span> 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.</p>
|
|
<p><a name="err-XTDE1420" id="err-XTDE1420"><span class=
|
|
"error">[ERR XTDE1420]</span></a> It is a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> 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.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>Implementations may also provide mechanisms allowing extension
|
|
functions to report recoverable dynamic errors, or to execute
|
|
within an environment that treats some or all of the errors listed
|
|
above as recoverable.</p>
|
|
</div>
|
|
<p><a name="err-XTDE1425" id="err-XTDE1425"><span class=
|
|
"error">[ERR XTDE1425]</span></a> <span>When the containing element
|
|
is processed with <a title="XSLT 1.0 behavior" class="termref"
|
|
href="#dt-xslt-10-behavior">XSLT 1.0 behavior</a>,</span> it is a
|
|
<a title="non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> to
|
|
evaluate an extension function call if no implementation of the
|
|
extension function is available.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>When <span>XSLT 1.0 behavior</span> is not enabled, this is a
|
|
static error [XPST0017].</p>
|
|
</div>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>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.</p>
|
|
</div>
|
|
<p>Implementations are not <span class="verb">required</span> to
|
|
perform full validation of values returned by extension functions.
|
|
It is an error for an extension function to return a string
|
|
containing characters that are not permitted in XML, but the
|
|
consequences of this error are <a title="implementation-defined"
|
|
class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a>. The
|
|
implementation <span class="verb">may</span> raise an error,
|
|
<span class="verb">may</span> convert the string to a string
|
|
containing valid characters only, or <span class="verb">may</span>
|
|
treat the invalid characters as if they were permitted
|
|
characters.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>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 <a title="processor" class="termref" href=
|
|
"#dt-processor">processor</a> executes. Implementations may
|
|
therefore provide mechanisms that restrict the use of extension
|
|
functions by untrusted stylesheets.</p>
|
|
</div>
|
|
<p>All observations in this section regarding the errors that can
|
|
occur when invoking extension functions apply equally when invoking
|
|
<a title="extension instruction" class="termref" href=
|
|
"#dt-extension-instruction">extension instructions</a>.</p>
|
|
</div>
|
|
<div class="div3">
|
|
<h4><a name="external-objects" id="external-objects"></a>21.1.3
|
|
<a href="#external-objects" style="text-decoration: none">External
|
|
Objects</a></h4>
|
|
<p>An implementation <span class="verb">may</span> allow an
|
|
extension function to return an object that does not have any
|
|
natural representation in the XDM data model, whether as an atomic
|
|
value, a node, <span>or a function item</span>. For example, an
|
|
extension function <code>sql:connect</code> might return an object
|
|
that represents a connection to a relational database; the
|
|
resulting connection object might be passed as an argument to calls
|
|
on other extension functions such as <code>sql:insert</code> and
|
|
<code>sql:select</code>.</p>
|
|
<p>The way in which such objects are represented in the type system
|
|
is <a title="implementation-defined" class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a>. They might
|
|
be represented by a completely new data type, or they might be
|
|
mapped to existing data types such as <code>integer</code>,
|
|
<code>string</code>, or <code>anyURI</code>.</p>
|
|
</div>
|
|
<div class="div3">
|
|
<h4><a name="testing-type-availability" id=
|
|
"testing-type-availability"></a>21.1.4 <a href=
|
|
"#testing-type-availability" style="text-decoration: none">Testing
|
|
Availability of Types</a></h4>
|
|
<p>The <a href=
|
|
"#function-type-available"><code>type-available</code></a> function
|
|
can be used to control how a stylesheet behaves if a particular
|
|
schema type is not available in the static context.</p>
|
|
<a name="function-type-available" id="function-type-available"></a>
|
|
<div class="proto"><code class=
|
|
"function">type-available</code>(<code class=
|
|
"arg">$type-name</code><code class=
|
|
"as"> as </code><code class=
|
|
"type">xs:string</code>)<code class=
|
|
"as"> as </code><code class=
|
|
"return-type">xs:boolean</code></div>
|
|
<p>A schema type (that is, a simple type or a complex type) is said
|
|
to be available within an XPath expression if it is a type
|
|
definition that is present in the <a href=
|
|
"http://www.w3.org/TR/xpath-21/#dt-is-types">in-scope schema
|
|
types</a><sup><small>XP21</small></sup> for that expression (see
|
|
<a href="#static-context"><i>5.4.1 Initializing the Static
|
|
Context</i></a>). This includes built-in types, types imported
|
|
using <a href=
|
|
"#element-import-schema"><code>xsl:import-schema</code></a>, and
|
|
extension types defined by the implementation.</p>
|
|
<p>The value of the <code>$type-name</code> argument <span class=
|
|
"verb">must</span> be a string containing a <a title=
|
|
"lexical QName" class="termref" href="#dt-lexical-qname">lexical
|
|
QName</a>. The lexical QName is expanded into an <a title=
|
|
"expanded-QName" class="termref" href=
|
|
"#dt-expanded-qname">expanded-QName</a> using the namespace
|
|
declarations in scope for the <a title="expression" class="termref"
|
|
href="#dt-expression">expression</a>. If the lexical QName is
|
|
unprefixed, then the default namespace is used in the expanded
|
|
QName.</p>
|
|
<p>The function returns true if and only if there is an available
|
|
type whose name matches the value of the <code>$type-name</code>
|
|
argument.</p>
|
|
<p><a name="err-XTDE1428" id="err-XTDE1428"><span class=
|
|
"error">[ERR XTDE1428]</span></a> It is a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> if the
|
|
argument does not evaluate to a string that is a valid <a title=
|
|
"QName" class="termref" href="#dt-qname">QName</a>, or if there is
|
|
no namespace declaration in scope for the prefix of the <a title=
|
|
"QName" class="termref" href="#dt-qname">QName</a>. If the
|
|
processor is able to detect the error statically (for example, when
|
|
the argument is supplied as a string literal), then the processor
|
|
<span class="verb">may</span> optionally signal this as a <a title=
|
|
"static error" class="termref" href="#dt-static-error">static
|
|
error</a>.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>The <a href=
|
|
"#function-type-available"><code>type-available</code></a> function
|
|
is of limited use within an <code>[xsl:]use-when</code> expression,
|
|
because the static context for the expression does not include any
|
|
user-defined types.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="extension-instruction" id=
|
|
"extension-instruction"></a>21.2 <a href="#extension-instruction"
|
|
style="text-decoration: none">Extension Instructions</a></h3>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-extension-namespace" id="dt-extension-namespace" title=
|
|
"extension namespace"></a>The <a title="extension instruction"
|
|
class="termref" href="#dt-extension-instruction">extension
|
|
instruction</a> mechanism allows namespaces to be designated as
|
|
<b>extension namespaces</b>. When a namespace is designated as an
|
|
extension namespace and an element with a name from that namespace
|
|
occurs in a <a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a>, then the
|
|
element is treated as an <a title="instruction" class="termref"
|
|
href="#dt-instruction">instruction</a> rather than as a <a title=
|
|
"literal result element" class="termref" href=
|
|
"#dt-literal-result-element">literal result
|
|
element</a>.<span class="definition">]</span> The namespace
|
|
determines the semantics of the instruction.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>Since an element that is a child of an <a href=
|
|
"#element-stylesheet"><code>xsl:stylesheet</code></a> element is
|
|
not occurring <em>in a <a title="sequence constructor" class=
|
|
"termref" href="#dt-sequence-constructor">sequence
|
|
constructor</a></em> , <a title="user-defined data element" class=
|
|
"termref" href="#dt-data-element">user-defined data elements</a>
|
|
(see <a href="#user-defined-top-level"><i>3.6.3 User-defined Data
|
|
Elements</i></a>) are not extension elements as defined here, and
|
|
nothing in this section applies to them.</p>
|
|
</div>
|
|
<div class="div3">
|
|
<h4><a name="designating-extension-namespace" id=
|
|
"designating-extension-namespace"></a>21.2.1 <a href=
|
|
"#designating-extension-namespace" style=
|
|
"text-decoration: none">Designating an Extension Namespace</a></h4>
|
|
<p>A namespace is designated as an extension namespace by using an
|
|
<code>[xsl:]extension-element-prefixes</code> attribute on an
|
|
element in the stylesheet (see <a href=
|
|
"#standard-attributes"><i>3.5 Standard Attributes</i></a>). The
|
|
attribute <span class="verb">must</span> be in the XSLT namespace
|
|
only if its parent element is <em>not</em> 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 extension namespace.</p>
|
|
<p>The default namespace (as declared by <code>xmlns</code>) may be
|
|
designated as an extension namespace by including
|
|
<code>#default</code> in the list of namespace prefixes.</p>
|
|
<p><a name="err-XTSE1430" id="err-XTSE1430"><span class=
|
|
"error">[ERR XTSE1430]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> if there
|
|
is no namespace bound to the prefix on the element bearing the
|
|
<code>[xsl:]extension-element-prefixes</code> attribute or, when
|
|
<code>#default</code> is specified, if there is no default
|
|
namespace.</p>
|
|
<p>The designation of a namespace as an extension namespace is
|
|
effective for the element bearing the
|
|
<code>[xsl:]extension-element-prefixes</code> attribute and for all
|
|
descendants of that element within the same stylesheet module.</p>
|
|
</div>
|
|
<div class="div3">
|
|
<h4><a name="testing-instruction-available" id=
|
|
"testing-instruction-available"></a>21.2.2 <a href=
|
|
"#testing-instruction-available" style=
|
|
"text-decoration: none">Testing Availability of
|
|
Instructions</a></h4>
|
|
<p>The <a href=
|
|
"#function-element-available"><code>element-available</code></a>
|
|
function can be used with the <a href=
|
|
"#element-choose"><code>xsl:choose</code></a> and <a href=
|
|
"#element-if"><code>xsl:if</code></a> instructions, or with the
|
|
<code>[xsl:]use-when</code> attribute (see <a href=
|
|
"#conditional-inclusion"><i>3.12 Conditional Element
|
|
Inclusion</i></a>) to explicitly control how a stylesheet behaves
|
|
when a particular XSLT instruction or extension instruction is (or
|
|
is not) available.</p>
|
|
<a name="function-element-available" id=
|
|
"function-element-available"></a>
|
|
<div class="proto"><code class=
|
|
"function">element-available</code>(<code class=
|
|
"arg">$element-name</code><code class=
|
|
"as"> as </code><code class=
|
|
"type">xs:string</code>)<code class=
|
|
"as"> as </code><code class=
|
|
"return-type">xs:boolean</code></div>
|
|
<p>The value of the <code>$element-name</code> argument
|
|
<span class="verb">must</span> be a string containing a <a title=
|
|
"QName" class="termref" href="#dt-qname">QName</a>. The <a title=
|
|
"QName" class="termref" href="#dt-qname">QName</a> is expanded into
|
|
an <a title="expanded-QName" class="termref" href=
|
|
"#dt-expanded-qname">expanded-QName</a> using the namespace
|
|
declarations in scope for the <a title="expression" class="termref"
|
|
href="#dt-expression">expression</a>. If there is a default
|
|
namespace in scope, then it is used to expand an unprefixed
|
|
<a title="QName" class="termref" href="#dt-qname">QName</a>. The
|
|
<a href=
|
|
"#function-element-available"><code>element-available</code></a>
|
|
function returns true if and only if the <a title="expanded-QName"
|
|
class="termref" href="#dt-expanded-qname">expanded-QName</a> is the
|
|
name of an <a title="instruction" class="termref" href=
|
|
"#dt-instruction">instruction</a>. If the <a title="expanded-QName"
|
|
class="termref" href="#dt-expanded-qname">expanded-QName</a> has a
|
|
namespace URI equal to the <a title="XSLT namespace" class=
|
|
"termref" href="#dt-xslt-namespace">XSLT namespace</a> URI, then it
|
|
refers to an element defined by XSLT. Otherwise, it refers to an
|
|
<a title="extension instruction" class="termref" href=
|
|
"#dt-extension-instruction">extension instruction</a>. If the
|
|
<a title="expanded-QName" class="termref" href=
|
|
"#dt-expanded-qname">expanded-QName</a> has a null namespace URI,
|
|
the <a href=
|
|
"#function-element-available"><code>element-available</code></a>
|
|
function will return false.</p>
|
|
<p><a name="err-XTDE1440" id="err-XTDE1440"><span class=
|
|
"error">[ERR XTDE1440]</span></a> It is a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> if the
|
|
argument does not evaluate to a string that is a valid <a title=
|
|
"QName" class="termref" href="#dt-qname">QName</a>, or if there is
|
|
no namespace declaration in scope for the prefix of the <a title=
|
|
"QName" class="termref" href="#dt-qname">QName</a>. If the
|
|
processor is able to detect the error statically (for example, when
|
|
the argument is supplied as a string literal), then the processor
|
|
<span class="verb">may</span> optionally signal this as a <a title=
|
|
"static error" class="termref" href="#dt-static-error">static
|
|
error</a>.</p>
|
|
<p>If the <a title="expanded-QName" class="termref" href=
|
|
"#dt-expanded-qname">expanded-QName</a> is in the <a title=
|
|
"XSLT namespace" class="termref" href="#dt-xslt-namespace">XSLT
|
|
namespace</a>, the function returns true if and only if the
|
|
expanded QName is the name of an <a title="XSLT instruction" class=
|
|
"termref" href="#dt-xslt-instruction">XSLT instruction</a>, that
|
|
is, an <a title="XSLT element" class="termref" href=
|
|
"#dt-xslt-element">XSLT element</a> whose syntax summary in this
|
|
specification classifies it as an <a title="instruction" class=
|
|
"termref" href="#dt-instruction">instruction</a>.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>Although the result of applying this function to a name in the
|
|
XSLT namespace when using a conformant XSLT <span>2.1</span>
|
|
processor is entirely predictable, the function is useful in cases
|
|
where the stylesheet might be executing under a processor that
|
|
implements some other version of XSLT with different rules.</p>
|
|
</div>
|
|
<p>If the <a title="expanded-QName" class="termref" href=
|
|
"#dt-expanded-qname">expanded-QName</a> is not in the <a title=
|
|
"XSLT namespace" class="termref" href="#dt-xslt-namespace">XSLT
|
|
namespace</a>, the function returns true if and only if the
|
|
processor has an implementation available of an <a title=
|
|
"extension instruction" class="termref" href=
|
|
"#dt-extension-instruction">extension instruction</a> with the
|
|
given expanded QName. This applies whether or not the namespace has
|
|
been designated as an <a title="extension namespace" class=
|
|
"termref" href="#dt-extension-namespace">extension
|
|
namespace</a>.</p>
|
|
<p>If the processor does not have an implementation of a particular
|
|
extension instruction available, and such an extension instruction
|
|
is evaluated, then the processor <span class="verb">must</span>
|
|
perform fallback for the element as specified in <a href=
|
|
"#fallback"><i>21.2.3 Fallback</i></a>. An implementation
|
|
<span class="verb">must not</span> signal an error merely because
|
|
the stylesheet contains an extension instruction for which no
|
|
implementation is available.</p>
|
|
</div>
|
|
<div class="div3">
|
|
<h4><a name="fallback" id="fallback"></a>21.2.3 <a href="#fallback"
|
|
style="text-decoration: none">Fallback</a></h4>
|
|
<p class="element-syntax"><a name="element-fallback" id=
|
|
"element-fallback"></a><code><!-- Category: instruction
|
|
--><br />
|
|
<xsl:fallback><br />
|
|
  <!-- Content: <var>sequence-constructor</var>
|
|
--><br />
|
|
</xsl:fallback></code></p>
|
|
<p>The content of an <a href=
|
|
"#element-fallback"><code>xsl:fallback</code></a> element is a
|
|
<a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a>, and when
|
|
performing fallback, the value returned by the <a href=
|
|
"#element-fallback"><code>xsl:fallback</code></a> element is the
|
|
result of evaluating this sequence constructor.</p>
|
|
<p>When not performing fallback, evaluating an <a href=
|
|
"#element-fallback"><code>xsl:fallback</code></a> element returns
|
|
an empty sequence: the content of the <a href=
|
|
"#element-fallback"><code>xsl:fallback</code></a> element is
|
|
ignored.</p>
|
|
<p>There are two situations where a <a title="processor" class=
|
|
"termref" href="#dt-processor">processor</a> 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 <span>2.1</span>, is evaluated within a region of the
|
|
stylesheet for which <a title="forwards compatible behavior" class=
|
|
"termref" href="#dt-forwards-compatible-behavior">forwards
|
|
compatible behavior</a> is enabled.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>Fallback processing is not invoked in other situations, for
|
|
example it is not invoked when an XPath expression uses
|
|
unrecognized syntax or contains a call to an unknown function. To
|
|
handle such situations dynamically, the stylesheet should call
|
|
functions such as <a href=
|
|
"#function-system-property"><code>system-property</code></a> and
|
|
<a href=
|
|
"#function-function-available"><code>function-available</code></a>
|
|
to decide what capabilities are available.</p>
|
|
</div>
|
|
<p><a name="err-XTDE1450" id="err-XTDE1450"><span class=
|
|
"error">[ERR XTDE1450]</span></a> When a <a title="processor"
|
|
class="termref" href="#dt-processor">processor</a> performs
|
|
fallback for an <a title="extension instruction" class="termref"
|
|
href="#dt-extension-instruction">extension instruction</a> that is
|
|
not recognized, if the instruction element has one or more <a href=
|
|
"#element-fallback"><code>xsl:fallback</code></a> children, then
|
|
the content of each of the <a href=
|
|
"#element-fallback"><code>xsl:fallback</code></a> children
|
|
<span class="verb">must</span> be evaluated; it is a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> if it
|
|
has no <a href="#element-fallback"><code>xsl:fallback</code></a>
|
|
children.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>This is different from the situation with unrecognized <a title=
|
|
"XSLT element" class="termref" href="#dt-xslt-element">XSLT
|
|
elements</a>. As explained in <a href="#forwards"><i>3.9 Forwards
|
|
Compatible Processing</i></a>, an unrecognized XSLT element
|
|
appearing within a <a title="sequence constructor" class="termref"
|
|
href="#dt-sequence-constructor">sequence constructor</a> is a
|
|
static error unless (a) <a title="forwards compatible behavior"
|
|
class="termref" href="#dt-forwards-compatible-behavior">forwards
|
|
compatible behavior</a> is enabled, and (b) the instruction has an
|
|
<a href="#element-fallback"><code>xsl:fallback</code></a>
|
|
child.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="div1">
|
|
<h2><a name="result-trees" id="result-trees"></a>22 <a href=
|
|
"#result-trees" style="text-decoration: none">Final Result
|
|
Trees</a></h2>
|
|
<p>The output of a transformation is a set of one or more <a title=
|
|
"final result tree" class="termref" href=
|
|
"#dt-final-result-tree">final result trees</a>.</p>
|
|
<p>A <a title="final result tree" class="termref" href=
|
|
"#dt-final-result-tree">final result tree</a> can be created
|
|
explicitly, by evaluating an <a href=
|
|
"#element-result-document"><code>xsl:result-document</code></a>
|
|
instruction. As explained in <a href=
|
|
"#executing-a-transformation"><i>2.4 Executing a
|
|
Transformation</i></a>, a final result tree is also created
|
|
implicitly if no <a href=
|
|
"#element-result-document"><code>xsl:result-document</code></a>
|
|
instruction is evaluated, or if the result of evaluating the
|
|
<a title="initial template" class="termref" href=
|
|
"#dt-initial-template">initial template</a> is a non-empty
|
|
sequence.</p>
|
|
<p>The way in which a <a title="final result tree" class="termref"
|
|
href="#dt-final-result-tree">final result tree</a> is delivered to
|
|
an application is <a title="implementation-defined" class="termref"
|
|
href="#dt-implementation-defined">implementation-defined</a>.</p>
|
|
<p>Serialization of <a title="final result tree" class="termref"
|
|
href="#dt-final-result-tree">final result trees</a> is described
|
|
further in <a href="#serialization"><i>23 Serialization</i></a></p>
|
|
<div class="div2">
|
|
<h3><a name="creating-result-trees" id=
|
|
"creating-result-trees"></a>22.1 <a href="#creating-result-trees"
|
|
style="text-decoration: none">Creating Final Result Trees</a></h3>
|
|
<p class="element-syntax"><a name="element-result-document" id=
|
|
"element-result-document"></a><code><!-- Category: instruction
|
|
--><br />
|
|
<xsl:result-document<br />
|
|
  format? = { <var>qname</var> }<br />
|
|
  href? = { <var>uri-reference</var> }<br />
|
|
  validation? = "strict" | "lax" | "preserve" |
|
|
"strip"<br />
|
|
  type? = <var>qname</var><br />
|
|
  method? = { "xml" | "html" | "xhtml" | "text" |
|
|
<var>qname-but-not-ncname</var> }<br />
|
|
  byte-order-mark? = { "yes" | "no" }<br />
|
|
  cdata-section-elements? = { <var>qnames</var> }<br />
|
|
  doctype-public? = { <var>string</var> }<br />
|
|
  doctype-system? = { <var>string</var> }<br />
|
|
  encoding? = { <var>string</var> }<br />
|
|
  escape-uri-attributes? = { "yes" | "no" }<br />
|
|
  include-content-type? = { "yes" | "no" }<br />
|
|
  indent? = { "yes" | "no" }<br />
|
|
  media-type? = { <var>string</var> }<br />
|
|
  normalization-form? = { "NFC" | "NFD" | "NFKC" | "NFKD"
|
|
| "fully-normalized" | "none" | <var>nmtoken</var> }<br />
|
|
  omit-xml-declaration? = { "yes" | "no" }<br />
|
|
  standalone? = { "yes" | "no" | "omit" }<br />
|
|
  suppress-indentation? = { <var>qnames</var> }<br />
|
|
  undeclare-prefixes? = { "yes" | "no" }<br />
|
|
  use-character-maps? = <var>qnames</var><br />
|
|
  output-version? = { <var>nmtoken</var>
|
|
} ><br />
|
|
  <!-- Content: <var>sequence-constructor</var>
|
|
--><br />
|
|
</xsl:result-document></code></p>
|
|
<p>The <a href=
|
|
"#element-result-document"><code>xsl:result-document</code></a>
|
|
instruction is used to create a <a title="final result tree" class=
|
|
"termref" href="#dt-final-result-tree">final result tree</a>. The
|
|
content of the <a href=
|
|
"#element-result-document"><code>xsl:result-document</code></a>
|
|
element is a <a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> for the
|
|
children of the document node of the tree. A document node is
|
|
created, and the sequence obtained by evaluating the sequence
|
|
constructor is used to construct the content of the document, as
|
|
described in <a href="#constructing-complex-content"><i>5.7.1
|
|
Constructing Complex Content</i></a>. The tree rooted at this
|
|
document node forms the final result tree.</p>
|
|
<p>The <a href=
|
|
"#element-result-document"><code>xsl:result-document</code></a>
|
|
instruction defines the URI of the result tree, and may optionally
|
|
specify the output format to be used for serializing this tree.</p>
|
|
<p>The <a title="effective value" class="termref" href=
|
|
"#dt-effective-value">effective value</a> of the
|
|
<code>format</code> attribute, if specified, <span class=
|
|
"verb">must</span> be a <a title="lexical QName" class="termref"
|
|
href="#dt-lexical-qname">lexical QName</a>. The QName is expanded
|
|
using the namespace declarations in scope for the <a href=
|
|
"#element-result-document"><code>xsl:result-document</code></a>
|
|
element. The <a title="expanded-QName" class="termref" href=
|
|
"#dt-expanded-qname">expanded-QName</a> <span class=
|
|
"verb">must</span> match the expanded QName of a named <a title=
|
|
"output definition" class="termref" href=
|
|
"#dt-output-definition">output definition</a> in the <a title=
|
|
"stylesheet" class="termref" href="#dt-stylesheet">stylesheet</a>.
|
|
This identifies the <a href=
|
|
"#element-output"><code>xsl:output</code></a> declaration that will
|
|
control the serialization of the <a title="final result tree"
|
|
class="termref" href="#dt-final-result-tree">final result tree</a>
|
|
(see <a href="#serialization"><i>23 Serialization</i></a>), if the
|
|
result tree is serialized. If the <code>format</code> attribute is
|
|
omitted, the unnamed <a title="output definition" class="termref"
|
|
href="#dt-output-definition">output definition</a> is used to
|
|
control serialization of the result tree.</p>
|
|
<p><a name="err-XTDE1460" id="err-XTDE1460"><span class=
|
|
"error">[ERR XTDE1460]</span></a> It is a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> if the
|
|
<a title="effective value" class="termref" href=
|
|
"#dt-effective-value">effective value</a> of the
|
|
<code>format</code> attribute is not a valid <a title=
|
|
"lexical QName" class="termref" href="#dt-lexical-qname">lexical
|
|
QName</a>, or if it does not match the <a title="expanded-QName"
|
|
class="termref" href="#dt-expanded-qname">expanded-QName</a> of an
|
|
<a title="output definition" class="termref" href=
|
|
"#dt-output-definition">output definition</a> in the <a title=
|
|
"stylesheet" class="termref" href="#dt-stylesheet">stylesheet</a>.
|
|
If the processor is able to detect the error statically (for
|
|
example, when the <code>format</code> attribute contains no curly
|
|
brackets), then the processor <span class="verb">may</span>
|
|
optionally signal this as a <a title="static error" class="termref"
|
|
href="#dt-static-error">static error</a>.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>The only way to select the unnamed <a title="output definition"
|
|
class="termref" href="#dt-output-definition">output definition</a>
|
|
is to omit the <code>format</code> attribute.</p>
|
|
</div>
|
|
<p>The attributes <code>method</code>, <code>byte-order-mark</code>
|
|
<code>cdata-section-elements</code>, <code>doctype-public</code>,
|
|
<code>doctype-system</code>, <code>encoding</code>,
|
|
<code>escape-uri-attributes</code>, <code>indent</code>,
|
|
<code>media-type</code>, <code>normalization-form</code>,
|
|
<code>omit-xml-declaration</code>, <code>standalone</code>,
|
|
<span><code>suppress-indentation</code>,</span>
|
|
<code>undeclare-prefixes</code>, <code>use-character-maps</code>,
|
|
and <code>output-version</code> may be used to override attributes
|
|
defined in the selected <a title="output definition" class=
|
|
"termref" href="#dt-output-definition">output definition</a>.</p>
|
|
<p>With the exception of <code>use-character-maps</code>, these
|
|
attributes are all defined as <a title="attribute value template"
|
|
class="termref" href="#dt-attribute-value-template">attribute value
|
|
templates</a>, so their values may be set dynamically. For any of
|
|
these attributes that is present on the <a href=
|
|
"#element-result-document"><code>xsl:result-document</code></a>
|
|
instruction, the <a title="effective value" class="termref" href=
|
|
"#dt-effective-value">effective value</a> of the attribute
|
|
overrides or supplements the corresponding value from the output
|
|
definition. This works in the same way as when one <a href=
|
|
"#element-output"><code>xsl:output</code></a> declaration overrides
|
|
another:</p>
|
|
<ul>
|
|
<li>
|
|
<p>In the case of <code>cdata-section-elements</code> <span>and
|
|
<code>suppress-indentation</code></span>, the value of the
|
|
serialization parameter is the union of the expanded names of the
|
|
elements named in this instruction and the elements named in the
|
|
selected output definition;</p>
|
|
</li>
|
|
<li>
|
|
<p>In the case of <code>use-character-maps</code>, the character
|
|
maps referenced in this instruction supplement and take precedence
|
|
over those defined in the selected output definition;</p>
|
|
</li>
|
|
<li>
|
|
<p>In all other cases, the effective value of an attribute actually
|
|
present on this instruction takes precedence over the value defined
|
|
in the selected output definition.</p>
|
|
</li>
|
|
</ul>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>In the case of the attributes <code>method</code>,
|
|
<code>cdata-section-elements</code>,
|
|
<span><code>suppress-indentation</code></span>, and
|
|
<code>use-character-maps</code>, the <a title="effective value"
|
|
class="termref" href="#dt-effective-value">effective value</a> of
|
|
the attribute contains one or more lexical QNames. The prefix in
|
|
such a QName is expanded using the in-scope namespaces for the
|
|
<code>xsl:result-document</code> element. In the case of
|
|
<code>cdata-section-elements</code> <span>and
|
|
<code>suppress-indentation</code></span>, an unprefixed element
|
|
name is expanded using the default namespace.</p>
|
|
</div>
|
|
<p>The <code>output-version</code> attribute on the <a href=
|
|
"#element-result-document"><code>xsl:result-document</code></a>
|
|
instruction overrides the <code>version</code> attribute on
|
|
<a href="#element-output"><code>xsl:output</code></a> (it has been
|
|
renamed because <code>version</code> is available with a different
|
|
meaning as a standard attribute: see <a href=
|
|
"#standard-attributes"><i>3.5 Standard Attributes</i></a>). In all
|
|
other cases, attributes correspond if they have the same name.</p>
|
|
<p>There are some serialization parameters that apply to some
|
|
output methods but not to others. For example, the
|
|
<code>indent</code> attribute has no effect on the
|
|
<code>text</code> output method. If a value is supplied for an
|
|
attribute that is inapplicable to the output method, its value is
|
|
not passed to the serializer. The processor <span class=
|
|
"verb">may</span> validate the value of such an attribute, but is
|
|
not <span class="verb">required</span> to do so.</p>
|
|
<p>The <code>href</code> attribute is optional. The default value
|
|
is the zero-length string. The <a title="effective value" class=
|
|
"termref" href="#dt-effective-value">effective value</a> of the
|
|
attribute <span class="verb">must</span> be a <a title=
|
|
"URI Reference" class="termref" href="#dt-uri-reference">URI
|
|
Reference</a>, which may be absolute or relative. There
|
|
<span class="verb">may</span> be <a title="implementation-defined"
|
|
class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a>
|
|
restrictions on the form of absolute URI that may be used, but the
|
|
implementation is not <span class="verb">required</span> to enforce
|
|
any restrictions. Any legal relative URI <span>reference</span>
|
|
<span class="verb">must</span> be accepted. Note that the
|
|
zero-length string is a legal relative URI
|
|
<span>reference</span>.</p>
|
|
<p>The base URI of the document node at the root of the <a title=
|
|
"final result tree" class="termref" href=
|
|
"#dt-final-result-tree">final result tree</a> is based on the
|
|
<a title="effective value" class="termref" href=
|
|
"#dt-effective-value">effective value</a> of the <code>href</code>
|
|
attribute. If the <a title="effective value" class="termref" href=
|
|
"#dt-effective-value">effective value</a> is a relative URI
|
|
<span>reference</span>, then it is resolved relative to the
|
|
<a title="base output URI" class="termref" href=
|
|
"#dt-base-output-uri">base output URI</a>. If the implementation
|
|
provides an API to access final result trees, then it <span class=
|
|
"verb">must</span> allow a final result tree to be identified by
|
|
means of this base URI.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>The base URI of the <a title="final result tree" class="termref"
|
|
href="#dt-final-result-tree">final result tree</a> is not
|
|
necessarily the same thing as the URI of its serialized
|
|
representation on disk, if any. For example, a server (or browser
|
|
client) might store final result trees only in memory, or in an
|
|
internal disk cache. As long as the processor satisfies requests
|
|
for those URIs, it is irrelevant where they are actually written on
|
|
disk, if at all.</p>
|
|
</div>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>It will often be the case that one <a title="final result tree"
|
|
class="termref" href="#dt-final-result-tree">final result tree</a>
|
|
contains links to another final result tree produced during the
|
|
same transformation, in the form of a relative URI
|
|
<span>reference</span>. 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.</p>
|
|
<p>As well as being potentially significant in any API that
|
|
provides access to final result trees, the base URI of the new
|
|
document node is relevant if the final result tree, rather than
|
|
being serialized, is supplied as input to a further
|
|
transformation.</p>
|
|
</div>
|
|
<p>The optional attributes <code>type</code> and
|
|
<code>validation</code> may be used on the <a href=
|
|
"#element-result-document"><code>xsl:result-document</code></a>
|
|
instruction to validate the contents of the new document, and to
|
|
determine the <a title="type annotation" class="termref" href=
|
|
"#dt-annotation">type annotation</a> that elements and attributes
|
|
within the <a title="final result tree" class="termref" href=
|
|
"#dt-final-result-tree">final result tree</a> will carry. The
|
|
permitted values and their semantics are described in <a href=
|
|
"#validating-document-nodes"><i>22.2.2 Validating Document
|
|
Nodes</i></a>.</p>
|
|
<p>A <a title="processor" class="termref" href=
|
|
"#dt-processor">processor</a> <span class="verb">may</span> allow a
|
|
<a title="final result tree" class="termref" href=
|
|
"#dt-final-result-tree">final result tree</a> to be serialized.
|
|
Serialization is described in <a href="#serialization"><i>23
|
|
Serialization</i></a>. However, an implementation (for example, a
|
|
<a title="processor" class="termref" href=
|
|
"#dt-processor">processor</a> running in an environment with no
|
|
access to writable filestore) is not <span class=
|
|
"verb">required</span> to support the serialization of <a title=
|
|
"final result tree" class="termref" href=
|
|
"#dt-final-result-tree">final result trees</a>. An implementation
|
|
that does not support the serialization of final result trees
|
|
<span class="verb">may</span> ignore the <code>format</code>
|
|
attribute and the serialization attributes. Such an implementation
|
|
<span class="verb">must</span> provide the application with some
|
|
means of access to the (un-serialized) result tree, using its URI
|
|
to identify it.</p>
|
|
<p>Implementations may provide additional mechanisms, outside the
|
|
scope of this specification, for defining the way in which
|
|
<a title="final result tree" class="termref" href=
|
|
"#dt-final-result-tree">final result trees</a> are processed. Such
|
|
mechanisms <span class="verb">may</span> make use of the
|
|
XSLT-defined attributes on the <a href=
|
|
"#element-result-document"><code>xsl:result-document</code></a>
|
|
and/or <a href="#element-output"><code>xsl:output</code></a>
|
|
elements, or they <span class="verb">may</span> use additional
|
|
elements or attributes in an <a title="implementation-defined"
|
|
class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a>
|
|
namespace.</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e39467" id=
|
|
"d7e39467"></a>Example: Multiple Result Documents</div>
|
|
<p>The following example takes an XHTML document as input, and
|
|
breaks it up so that the text following each <h1> element is
|
|
included in a separate document. A new document
|
|
<code>toc.html</code> is constructed to act as an index:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:stylesheet
|
|
version="2.1"
|
|
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
|
|
xmlns:xhtml="http://www.w3.org/1999/xhtml">
|
|
|
|
<xsl:output name="toc-format" method="xhtml" indent="yes"
|
|
doctype-system="http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"
|
|
doctype-public="-//W3C//DTD XHTML 1.0 Strict//EN"/>
|
|
|
|
<xsl:output name="section-format" method="xhtml" indent="no"
|
|
doctype-system="http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"
|
|
doctype-public="-//W3C//DTD XHTML 1.0 Transitional//EN"/>
|
|
|
|
<xsl:template match="/">
|
|
<xsl:result-document href="toc.html"
|
|
format="toc-format"
|
|
validation="strict">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head><title>Table of Contents</title></head>
|
|
<body>
|
|
<h1>Table of Contents</h1>
|
|
<xsl:for-each select="/*/xhtml:body/(*[1] | xhtml:h1)">
|
|
<p>
|
|
<a href="section{position()}.html">
|
|
<xsl:value-of select="."/>
|
|
</a>
|
|
</p>
|
|
</xsl:for-each>
|
|
</body>
|
|
</html>
|
|
</xsl:result-document>
|
|
<xsl:for-each-group select="/*/xhtml:body/*" group-starting-with="xhtml:h1">
|
|
<xsl:result-document href="section{position()}.html"
|
|
format="section-format" validation="strip">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head><title><xsl:value-of select="."/></title></head>
|
|
<body>
|
|
<xsl:copy-of select="current-group()"/>
|
|
</body>
|
|
</html>
|
|
</xsl:result-document>
|
|
</xsl:for-each-group>
|
|
</xsl:template>
|
|
|
|
</xsl:stylesheet>
|
|
</pre></div>
|
|
</div>
|
|
<p>There are restrictions on the use of the <a href=
|
|
"#element-result-document"><code>xsl:result-document</code></a>
|
|
instruction, designed to ensure that the results are fully
|
|
interoperable even when processors optimize the sequence in which
|
|
instructions are evaluated. Informally, the restriction is that the
|
|
<a href=
|
|
"#element-result-document"><code>xsl:result-document</code></a>
|
|
instruction can only be used while writing a final result tree, not
|
|
while writing to a temporary tree or a sequence. This restriction
|
|
is defined formally as follows.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-output-state" id="dt-output-state" title=
|
|
"output state"></a>Each instruction in the <a title="stylesheet"
|
|
class="termref" href="#dt-stylesheet">stylesheet</a> is evaluated
|
|
in one of two possible <b>output states</b>: <a title=
|
|
"final output state" class="termref" href=
|
|
"#dt-final-output-state">final output state</a> or <a title=
|
|
"temporary output state" class="termref" href=
|
|
"#dt-temporary-output-state">temporary output state</a>
|
|
<span class="definition">]</span>.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-final-output-state" id="dt-final-output-state" title=
|
|
"final output state"></a>The first of the two <a title=
|
|
"output state" class="termref" href="#dt-output-state">output
|
|
states</a> is called <b>final output</b> state. This state applies
|
|
when instructions are writing to a <a title="final result tree"
|
|
class="termref" href="#dt-final-result-tree">final result
|
|
tree</a>.<span class="definition">]</span></p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-temporary-output-state" id="dt-temporary-output-state" title=
|
|
"temporary output state"></a>The second of the two <a title=
|
|
"output state" class="termref" href="#dt-output-state">output
|
|
states</a> is called <b>temporary output</b> state. This state
|
|
applies when instructions are writing to a <a title=
|
|
"temporary tree" class="termref" href=
|
|
"#dt-temporary-tree">temporary tree</a> or any other non-final
|
|
destination.<span class="definition">]</span></p>
|
|
<p>The instructions in the <a title="initial template" class=
|
|
"termref" href="#dt-initial-template">initial template</a> are
|
|
evaluated in <a title="final output state" class="termref" href=
|
|
"#dt-final-output-state">final output state</a>. An instruction is
|
|
evaluated in the same <a title="output state" class="termref" href=
|
|
"#dt-output-state">output state</a> as its calling instruction,
|
|
except that <a href=
|
|
"#element-variable"><code>xsl:variable</code></a>, <a href=
|
|
"#element-param"><code>xsl:param</code></a>, <a href=
|
|
"#element-with-param"><code>xsl:with-param</code></a>, <a href=
|
|
"#element-attribute"><code>xsl:attribute</code></a>, <a href=
|
|
"#element-comment"><code>xsl:comment</code></a>, <a href=
|
|
"#element-processing-instruction"><code>xsl:processing-instruction</code></a>,
|
|
<a href="#element-namespace"><code>xsl:namespace</code></a>,
|
|
<a href="#element-value-of"><code>xsl:value-of</code></a>, <a href=
|
|
"#element-function"><code>xsl:function</code></a>, <a href=
|
|
"#element-key"><code>xsl:key</code></a>, <a href=
|
|
"#element-sort"><code>xsl:sort</code></a>, and <a href=
|
|
"#element-message"><code>xsl:message</code></a> always evaluate the
|
|
instructions in their contained <a title="sequence constructor"
|
|
class="termref" href="#dt-sequence-constructor">sequence
|
|
constructor</a> in <a title="temporary output state" class=
|
|
"termref" href="#dt-temporary-output-state">temporary output
|
|
state</a>.</p>
|
|
<p><a name="err-XTDE1480" id="err-XTDE1480"><span class=
|
|
"error">[ERR XTDE1480]</span></a> It is a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> to
|
|
evaluate the <a href=
|
|
"#element-result-document"><code>xsl:result-document</code></a>
|
|
instruction in <a title="temporary output state" class="termref"
|
|
href="#dt-temporary-output-state">temporary output state</a>.</p>
|
|
<p><a name="err-XTDE1490" id="err-XTDE1490"><span class=
|
|
"error">[ERR XTDE1490]</span></a> It is a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> for a
|
|
transformation to generate two or more <a title="final result tree"
|
|
class="termref" href="#dt-final-result-tree">final result trees</a>
|
|
with the same URI.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>Note, this means that it is an error to evaluate more than one
|
|
<a href=
|
|
"#element-result-document"><code>xsl:result-document</code></a>
|
|
instruction that omits the <code>href</code> attribute, or to
|
|
evaluate any <a href=
|
|
"#element-result-document"><code>xsl:result-document</code></a>
|
|
instruction that omits the <code>href</code> attribute if an
|
|
initial <a title="final result tree" class="termref" href=
|
|
"#dt-final-result-tree">final result tree</a> is created
|
|
implicitly.</p>
|
|
</div>
|
|
<p>Technically, the result of evaluating the <a href=
|
|
"#element-result-document"><code>xsl:result-document</code></a>
|
|
instruction is an empty sequence. This means it does not contribute
|
|
any nodes to the result of the sequence constructor it is part
|
|
of.</p>
|
|
<p><a name="err-XTRE1495" id="err-XTRE1495"><span class=
|
|
"error">[ERR XTRE1495]</span></a> It is a <a title=
|
|
"recoverable error" class="termref" href=
|
|
"#dt-recoverable-error">recoverable dynamic error</a> for a
|
|
transformation to generate two or more <a title="final result tree"
|
|
class="termref" href="#dt-final-result-tree">final result trees</a>
|
|
with URIs that identify the same physical resource. The <a title=
|
|
"optional recovery action" class="termref" href=
|
|
"#dt-optional-recovery-action">optional recovery action</a> is
|
|
<a title="implementation-dependent" class="termref" href=
|
|
"#dt-implementation-dependent">implementation-dependent</a>, since
|
|
it may be impossible for the processor to detect the error.</p>
|
|
<p><a name="err-XTRE1500" id="err-XTRE1500"><span class=
|
|
"error">[ERR XTRE1500]</span></a> It is a <a title=
|
|
"recoverable error" class="termref" href=
|
|
"#dt-recoverable-error">recoverable dynamic error</a> for a
|
|
<a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a> to write to an external resource
|
|
and read from the same resource during a single transformation,
|
|
whether or not the same URI is used to access the resource in both
|
|
cases. The <a title="optional recovery action" class="termref"
|
|
href="#dt-optional-recovery-action">optional recovery action</a> is
|
|
<a title="implementation-dependent" class="termref" href=
|
|
"#dt-implementation-dependent">implementation-dependent</a>:
|
|
implementations are not <span class="verb">required</span> to
|
|
detect the error condition. Note that if the error is not detected,
|
|
it is undefined whether the document that is read from the resource
|
|
reflects its state before or after the result tree is written.</p>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="validation" id="validation"></a>22.2 <a href=
|
|
"#validation" style="text-decoration: none">Validation</a></h3>
|
|
<p>It is possible to control the <a title="type annotation" class=
|
|
"termref" href="#dt-annotation">type annotation</a> applied to
|
|
individual element and attribute nodes as they are constructed.
|
|
This is done using the <code>type</code> and
|
|
<code>validation</code> attributes of the <a href=
|
|
"#element-element"><code>xsl:element</code></a>, <a href=
|
|
"#element-attribute"><code>xsl:attribute</code></a>, <a href=
|
|
"#element-copy"><code>xsl:copy</code></a>, <a href=
|
|
"#element-copy-of"><code>xsl:copy-of</code></a>, <a href=
|
|
"#element-document"><code>xsl:document</code></a>, and <a href=
|
|
"#element-result-document"><code>xsl:result-document</code></a>
|
|
instructions, or the <code>xsl:type</code> and
|
|
<code>xsl:validation</code> attributes of a <a title=
|
|
"literal result element" class="termref" href=
|
|
"#dt-literal-result-element">literal result element</a>.</p>
|
|
<p>The <code>[xsl:]type</code> attribute is used to request
|
|
validation of an element or attribute against a specific simple or
|
|
complex type defined in a schema. The <code>[xsl:]validation</code>
|
|
attribute is used to request validation against the global element
|
|
or attribute declaration whose name matches the name of the element
|
|
or attribute being validated.</p>
|
|
<p>The <code>[xsl:]type</code> and <code>[xsl:]validation</code>
|
|
attributes are mutually exclusive. Both are optional, but if one is
|
|
present then the other <span class="verb">must</span> be omitted.
|
|
If both attributes are omitted, the effect is the same as
|
|
specifying the <code>validation</code> attribute with the value
|
|
specified in the <code>default-validation</code> attribute of the
|
|
containing <a href=
|
|
"#element-stylesheet"><code>xsl:stylesheet</code></a> element; if
|
|
this is not specified, the effect is the same as specifying
|
|
<code>validation="strip"</code>.</p>
|
|
<p><a name="err-XTSE1505" id="err-XTSE1505"><span class=
|
|
"error">[ERR XTSE1505]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> if both
|
|
the <code>[xsl:]type</code> and <code>[xsl:]validation</code>
|
|
attributes are present on the <a href=
|
|
"#element-element"><code>xsl:element</code></a>, <a href=
|
|
"#element-attribute"><code>xsl:attribute</code></a>, <a href=
|
|
"#element-copy"><code>xsl:copy</code></a>, <a href=
|
|
"#element-copy-of"><code>xsl:copy-of</code></a>, <a href=
|
|
"#element-document"><code>xsl:document</code></a>, or <a href=
|
|
"#element-result-document"><code>xsl:result-document</code></a>
|
|
instructions, or on a <a title="literal result element" class=
|
|
"termref" href="#dt-literal-result-element">literal result
|
|
element</a>.</p>
|
|
<p>The detailed rules for validation vary depending on the kind of
|
|
node being validated. The rules for element and attribute nodes are
|
|
given in <a href="#validating-constructed-nodes"><i>22.2.1
|
|
Validating Constructed Elements and Attributes</i></a>, while those
|
|
for document nodes are given in <a href=
|
|
"#validating-document-nodes"><i>22.2.2 Validating Document
|
|
Nodes</i></a>.</p>
|
|
<div class="div3">
|
|
<h4><a name="validating-constructed-nodes" id=
|
|
"validating-constructed-nodes"></a>22.2.1 <a href=
|
|
"#validating-constructed-nodes" style=
|
|
"text-decoration: none">Validating Constructed Elements and
|
|
Attributes</a></h4>
|
|
<div class="div4">
|
|
<h5><a name="validating-using-validation-attribute" id=
|
|
"validating-using-validation-attribute"></a>22.2.1.1 <a href=
|
|
"#validating-using-validation-attribute" style=
|
|
"text-decoration: none">Validation using the</a>
|
|
<code>[xsl:]validation</code> <a href=
|
|
"#validating-using-validation-attribute" style=
|
|
"text-decoration: none">Attribute</a></h5>
|
|
<p>The <code>[xsl:]validation</code> attribute defines the
|
|
validation action to be taken. It determines not only the <a title=
|
|
"type annotation" class="termref" href="#dt-annotation">type
|
|
annotation</a> of the node that is constructed by the relevant
|
|
instruction itself, but also the type annotations of all element
|
|
and attribute nodes that have the constructed node as an ancestor.
|
|
Conceptually, the validation requested for a child element or
|
|
attribute node is applied before the validation requested for its
|
|
parent element. For example, if the instruction that constructs a
|
|
child element specifies <code>validation="strict"</code>, this will
|
|
cause the child element to be checked against an element
|
|
declaration, but if the instruction that constructs its parent
|
|
element specifies <code>validation="strip"</code>, then the final
|
|
effect will be that the child node is annotated as
|
|
<code>xs:untyped</code>.</p>
|
|
<p>In the paragraphs below, the term <em>contained nodes</em> means
|
|
the elements and attributes that have the newly constructed node as
|
|
an ancestor.</p>
|
|
<ul>
|
|
<li>
|
|
<p>The value <code>strip</code> indicates that the new node and
|
|
each of the contained nodes will have the <a title=
|
|
"type annotation" class="termref" href="#dt-annotation">type
|
|
annotation</a> <code>xs:untyped</code> if it is an element, or
|
|
<code>xs:untypedAtomic</code> if it is an attribute. Any previous
|
|
type annotation present on a contained element or attribute node
|
|
(for example, a type annotation that is present on an element
|
|
copied from a source document) is also replaced by
|
|
<code>xs:untyped</code> or <code>xs:untypedAtomic</code> as
|
|
appropriate. The typed value of the node is changed to be the same
|
|
as its string value, as an instance of
|
|
<code>xs:untypedAtomic</code>. In the case of elements the
|
|
<code>nilled</code> property is set to <code>false</code>. The
|
|
values of the <code>is-id</code> and <code>is-idrefs</code>
|
|
properties are unchanged. Schema validation is not invoked.</p>
|
|
</li>
|
|
<li>
|
|
<p>The value <code>preserve</code> indicates that nodes that are
|
|
copied will retain their <a title="type annotation" class="termref"
|
|
href="#dt-annotation">type annotations</a>, but nodes whose content
|
|
is newly constructed will be annotated as <code>xs:anyType</code>
|
|
in the case of elements, or <code>xs:untypedAtomic</code> in the
|
|
case of attributes. Schema validation is not invoked. The detailed
|
|
effect depends on the instruction:</p>
|
|
<ul>
|
|
<li>
|
|
<p>In the case of <a href=
|
|
"#element-element"><code>xsl:element</code></a> and literal result
|
|
elements, the new element has a <a title="type annotation" class=
|
|
"termref" href="#dt-annotation">type annotation</a> of
|
|
<code>xs:anyType</code>, and the type annotations of contained
|
|
nodes are retained unchanged.</p>
|
|
</li>
|
|
<li>
|
|
<p>In the case of <a href=
|
|
"#element-attribute"><code>xsl:attribute</code></a>, the effect is
|
|
exactly the same as specifying <code>validation="strip"</code>:
|
|
that is, the new attribute will have the type annotation
|
|
<code>xs:untypedAtomic</code>.</p>
|
|
</li>
|
|
<li>
|
|
<p>In the case of <a href=
|
|
"#element-copy-of"><code>xsl:copy-of</code></a>, all the nodes that
|
|
are copied will retain their type annotations unchanged.</p>
|
|
</li>
|
|
<li>
|
|
<p>In the case of <a href=
|
|
"#element-copy"><code>xsl:copy</code></a>, the effect depends on
|
|
the kind of node being copied.</p>
|
|
<ol class="enumar">
|
|
<li>
|
|
<p>Where the node being copied is an attribute, the copied
|
|
attribute will retain its <a title="type annotation" class=
|
|
"termref" href="#dt-annotation">type annotation</a>.</p>
|
|
</li>
|
|
<li>
|
|
<p>Where the node being copied is an element, the copied element
|
|
will have a <a title="type annotation" class="termref" href=
|
|
"#dt-annotation">type annotation</a> of <code>xs:anyType</code>
|
|
(because this instruction does not copy the content of the element,
|
|
it would be wrong to assume that the type is unchanged); but any
|
|
contained nodes will have their type annotations retained in the
|
|
same way as with <a href=
|
|
"#element-element"><code>xsl:element</code></a>.</p>
|
|
</li>
|
|
</ol>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
<p>The value <code>strict</code> indicates that <a title=
|
|
"type annotation" class="termref" href="#dt-annotation">type
|
|
annotations</a> are established by performing strict schema
|
|
validity assessment on the element or attribute node created by
|
|
this instruction as follows:</p>
|
|
<ul>
|
|
<li>
|
|
<p>In the case of an element, a top-level element declaration is
|
|
identified whose local name and namespace (if any) match the name
|
|
of the element, and schema-validity assessment is carried out
|
|
according to the rules defined in <a href="#xmlschema-1">[XML
|
|
Schema Part 1]</a> (section 3.3.4 "Element Declaration Validation
|
|
Rules", validation rule "Schema-Validity Assessment (Element)",
|
|
clauses 1.1 and 2, using the top-level element declaration as the
|
|
"declaration stipulated by the processor", which is mentioned in
|
|
clause 1.1.1.1). The element is considered valid if the result of
|
|
the schema validity assessment is a PSVI in which the relevant
|
|
element node has a <code>validity</code> property whose value is
|
|
<code>valid</code>. If there is no matching element declaration, or
|
|
if the element is not considered valid, the transformation fails
|
|
<span class="error">[see <a href="#err-XTTE1510">ERR
|
|
XTTE1510</a>]</span>, <span class="error">[see <a href=
|
|
"#err-XTTE1512">ERR XTTE1512</a>]</span>. In effect this means that
|
|
the element being validated <span class="verb">must</span> be
|
|
declared using a top-level declaration in the schema, and
|
|
<span class="verb">must</span> conform to its declaration. The
|
|
process of validation applies recursively to contained elements and
|
|
attributes to the extent required by the schema definition.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>It is not an error if the identified type definition is a simple
|
|
type, although <a href="#xmlschema-1">[XML Schema Part 1]</a> does
|
|
not define explicitly that this case is permitted.</p>
|
|
</div>
|
|
</li>
|
|
<li>
|
|
<p>In the case of an attribute, a top-level attribute declaration
|
|
is identified whose local name and namespace (if any) match the
|
|
name of the attribute, and schema-validity assessment is carried
|
|
out according to the rules defined in <a href="#xmlschema-1">[XML
|
|
Schema Part 1]</a> (section 3.2.4 "Attribute Declaration Validation
|
|
Rules", validation rule "Schema-Validity Assessment (Attribute)").
|
|
The attribute is considered valid if the result of the schema
|
|
validity assessment is a PSVI in which the relevant attribute node
|
|
has a <code>validity</code> property whose value is
|
|
<code>valid</code>. If the attribute is not considered valid, the
|
|
transformation fails <span class="error">[see <a href=
|
|
"#err-XTTE1510">ERR XTTE1510</a>]</span>. In effect this means that
|
|
the attribute being validated <span class="verb">must</span> be
|
|
declared using a top-level declaration in the schema, and
|
|
<span class="verb">must</span> conform to its declaration.</p>
|
|
</li>
|
|
<li>
|
|
<p>The schema components used to validate an element or attribute
|
|
may be located in any way described by <a href="#xmlschema-1">[XML
|
|
Schema Part 1]</a> (see section 4.3.2, <em>How schema documents are
|
|
located on the Web</em>). The components in the schema constructed
|
|
from the synthetic schema document (see <a href=
|
|
"#import-schema"><i>3.14 Importing Schema Components</i></a>) will
|
|
always be available for validating constructed nodes; if additional
|
|
schema components are needed, they <span class="verb">may</span> be
|
|
located in other ways, for example implicitly from knowledge of the
|
|
namespace in which the elements and attributes appear, or using the
|
|
<code>xsi:schemaLocation</code> attribute of elements within the
|
|
tree being validated.</p>
|
|
</li>
|
|
<li>
|
|
<p>If no validation is performed for a node, which can happen when
|
|
the schema specifies <code>lax</code> or <code>skip</code>
|
|
validation for that node or for a subtree, then the node is
|
|
annotated as <code>xs:anyType</code> in the case of an element, and
|
|
<code>xs:untypedAtomic</code> in the case of an attribute.</p>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
<p>The value <code>lax</code> has the same effect as the value
|
|
<code>strict</code>, except that whereas <code>strict</code>
|
|
validation fails if there is no matching top-level element
|
|
declaration or if the outcome of validity assessment is a
|
|
<code>validity</code> property of <code>invalid</code> or
|
|
<code>notKnown</code>, <code>lax</code> validation fails only if
|
|
the outcome of validity assessment is a <code>validity</code>
|
|
property of <code>invalid</code>. That is, <code>lax</code>
|
|
validation does not cause a type error when the outcome is
|
|
<code>notKnown</code>.</p>
|
|
<p>In practice this means that the element or attribute being
|
|
validated <span class="verb">must</span> conform to its declaration
|
|
if a top-level declaration is available. If no such declaration is
|
|
available, then the element or attribute is not validated, but its
|
|
attributes and children are validated, again with lax validation.
|
|
Any nodes whose validation outcome is a <code>validity</code>
|
|
property of <code>notKnown</code> are annotated as
|
|
<code>xs:anyType</code> in the case of an element, and
|
|
<code>xs:untypedAtomic</code> in the case of an attribute.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>When the parent element lacks a declaration, the XML Schema
|
|
specification defines the recursive checking of children and
|
|
attributes as optional. For this specification, this recursive
|
|
checking is required.</p>
|
|
</div>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>If an element that is being validated has an
|
|
<code>xsi:type</code> attribute, then the value of the
|
|
<code>xsi:type</code> attribute will be taken into account when
|
|
performing the validation. However, the presence of an
|
|
<code>xsi:type</code> attribute will not of itself cause an element
|
|
to be validated: if validation against a named type is required, as
|
|
distinct from validation against a top-level element declaration,
|
|
then it must be requested using the XSLT <code>[xsl:]type</code>
|
|
attribute on the instruction that invokes the validation, as
|
|
described in section <a href="#validation-xsl-type"><i>22.2.1.2
|
|
Validation using the [xsl:]type Attribute</i></a></p>
|
|
</div>
|
|
</li>
|
|
</ul>
|
|
<p><a name="err-XTTE1510" id="err-XTTE1510"><span class=
|
|
"error">[ERR XTTE1510]</span></a> If the <code>validation</code>
|
|
attribute of an <a href=
|
|
"#element-element"><code>xsl:element</code></a>, <a href=
|
|
"#element-attribute"><code>xsl:attribute</code></a>, <a href=
|
|
"#element-copy"><code>xsl:copy</code></a>, <a href=
|
|
"#element-copy-of"><code>xsl:copy-of</code></a>, or <a href=
|
|
"#element-result-document"><code>xsl:result-document</code></a>
|
|
instruction, or the <code>xsl:validation</code> attribute of a
|
|
literal result element, has the effective value
|
|
<code>strict</code>, and schema validity assessment concludes that
|
|
the validity of the element or attribute is invalid or unknown, a
|
|
type error occurs. As with other type errors, the error
|
|
<span class="verb">may</span> be signaled statically if it can be
|
|
detected statically.</p>
|
|
<p><a name="err-XTTE1512" id="err-XTTE1512"><span class=
|
|
"error">[ERR XTTE1512]</span></a> If the <code>validation</code>
|
|
attribute of an <a href=
|
|
"#element-element"><code>xsl:element</code></a>, <a href=
|
|
"#element-attribute"><code>xsl:attribute</code></a>, <a href=
|
|
"#element-copy"><code>xsl:copy</code></a>, <a href=
|
|
"#element-copy-of"><code>xsl:copy-of</code></a>, or <a href=
|
|
"#element-result-document"><code>xsl:result-document</code></a>
|
|
instruction, or the <code>xsl:validation</code> attribute of a
|
|
literal result element, has the effective value
|
|
<code>strict</code>, and there is no matching top-level declaration
|
|
in the schema, then a type error occurs. As with other type errors,
|
|
the error <span class="verb">may</span> be signaled statically if
|
|
it can be detected statically.</p>
|
|
<p><a name="err-XTTE1515" id="err-XTTE1515"><span class=
|
|
"error">[ERR XTTE1515]</span></a> If the <code>validation</code>
|
|
attribute of an <a href=
|
|
"#element-element"><code>xsl:element</code></a>, <a href=
|
|
"#element-attribute"><code>xsl:attribute</code></a>, <a href=
|
|
"#element-copy"><code>xsl:copy</code></a>, <a href=
|
|
"#element-copy-of"><code>xsl:copy-of</code></a>, or <a href=
|
|
"#element-result-document"><code>xsl:result-document</code></a>
|
|
instruction, or the <code>xsl:validation</code> attribute of a
|
|
literal result element, has the effective value <code>lax</code>,
|
|
and schema validity assessment concludes that the element or
|
|
attribute is invalid, a type error occurs. As with other type
|
|
errors, the error <span class="verb">may</span> be signaled
|
|
statically if it can be detected statically.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>No mechanism is provided to validate an element or attribute
|
|
against a local declaration in a schema. Such validation can
|
|
usually be achieved by applying validation to a containing element
|
|
for which a top-level element declaration exists.</p>
|
|
</div>
|
|
</div>
|
|
<div class="div4">
|
|
<h5><a name="validation-xsl-type" id=
|
|
"validation-xsl-type"></a>22.2.1.2 <a href="#validation-xsl-type"
|
|
style="text-decoration: none">Validation using the</a>
|
|
<code>[xsl:]type</code> <a href="#validation-xsl-type" style=
|
|
"text-decoration: none">Attribute</a></h5>
|
|
<p>The <code>[xsl:]type</code> attribute takes as its value a
|
|
<code>QName</code>. This <span class="verb">must</span> be the name
|
|
of a type definition included in the <a title=
|
|
"in-scope schema component" class="termref" href=
|
|
"#dt-in-scope-schema-component">in-scope schema components</a> for
|
|
the stylesheet. If the QName has no prefix, it is expanded using
|
|
the default namespace established using the effective
|
|
<code>[xsl:]xpath-default-namespace</code> attribute if there is
|
|
one; otherwise, it is taken as being a name in no namespace.</p>
|
|
<p>If the <code>[xsl:]type</code> attribute is present, then the
|
|
newly constructed element or attribute is validated against the
|
|
type definition identified by this attribute.</p>
|
|
<ul>
|
|
<li>
|
|
<p>In the case of an element, schema-validity assessment is carried
|
|
out according to the rules defined in <a href="#xmlschema-1">[XML
|
|
Schema Part 1]</a> (section 3.3.4 "Element Declaration Validation
|
|
Rules", validation rule "Schema-Validity Assessment (Element)",
|
|
clauses 1.2 and 2), using this type definition as the
|
|
"processor-stipulated type definition". The element is considered
|
|
valid if the result of the schema validity assessment is a PSVI in
|
|
which the relevant element node has a <code>validity</code>
|
|
property whose value is <code>valid</code>.</p>
|
|
</li>
|
|
<li>
|
|
<p>In the case of an attribute, the attribute is considered valid
|
|
if (in the terminology of XML Schema) the attribute's normalized
|
|
value is locally valid with respect to that type definition
|
|
according to the rules for "String Valid" (<a href=
|
|
"#xmlschema-1">[XML Schema Part 1]</a>, section 3.14.4).
|
|
(Normalization here refers to the process of normalizing whitespace
|
|
according to the rules of the <code>whiteSpace</code> facet for the
|
|
data type).</p>
|
|
</li>
|
|
<li>
|
|
<p>If the element or attribute is not considered valid, as defined
|
|
above, the transformation fails <span class="error">[see <a href=
|
|
"#err-XTTE1540">ERR XTTE1540</a>]</span>.</p>
|
|
</li>
|
|
</ul>
|
|
<p><a name="err-XTSE1520" id="err-XTSE1520"><span class=
|
|
"error">[ERR XTSE1520]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> if the
|
|
value of the <code>type</code> attribute of an <a href=
|
|
"#element-element"><code>xsl:element</code></a>, <a href=
|
|
"#element-attribute"><code>xsl:attribute</code></a>, <a href=
|
|
"#element-copy"><code>xsl:copy</code></a>, <a href=
|
|
"#element-copy-of"><code>xsl:copy-of</code></a>, <a href=
|
|
"#element-document"><code>xsl:document</code></a>, or <a href=
|
|
"#element-result-document"><code>xsl:result-document</code></a>
|
|
instruction, or the <code>xsl:type</code> attribute of a literal
|
|
result element, is not a valid <code>QName</code>, or if it uses a
|
|
prefix that is not defined in an in-scope namespace declaration, or
|
|
if the QName is not the name of a type definition included in the
|
|
<a title="in-scope schema component" class="termref" href=
|
|
"#dt-in-scope-schema-component">in-scope schema components</a> for
|
|
the stylesheet.</p>
|
|
<p><a name="err-XTSE1530" id="err-XTSE1530"><span class=
|
|
"error">[ERR XTSE1530]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> if the
|
|
value of the <code>type</code> attribute of an <a href=
|
|
"#element-attribute"><code>xsl:attribute</code></a> instruction
|
|
refers to a complex type definition.</p>
|
|
<p><a name="err-XTTE1540" id="err-XTTE1540"><span class=
|
|
"error">[ERR XTTE1540]</span></a> It is a <a title="type errors"
|
|
class="termref" href="#dt-type-error">type error</a> if an
|
|
<code>[xsl:]type</code> attribute is defined for a constructed
|
|
element or attribute, and the outcome of schema validity assessment
|
|
against that type is that the <code>validity</code> property of
|
|
that element or attribute information item is other than
|
|
<code>valid</code>.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>Like other type errors, this error may be signaled statically if
|
|
it can be detected statically. For example, the instruction
|
|
<code><xsl:attribute name="dob"
|
|
type="xs:date">1999-02-29</xsl:attribute></code> may
|
|
result in a static error being signaled. If the error is not
|
|
signaled statically, it will be signaled when the instruction is
|
|
evaluated.</p>
|
|
</div>
|
|
</div>
|
|
<div class="div4">
|
|
<h5><a name="validation-process" id=
|
|
"validation-process"></a>22.2.1.3 <a href="#validation-process"
|
|
style="text-decoration: none">The Validation Process</a></h5>
|
|
<p>As well as checking for validity against the schema, the
|
|
validity assessment process causes <a title="type annotation"
|
|
class="termref" href="#dt-annotation">type annotations</a> to be
|
|
associated with element and attribute nodes. If default values for
|
|
elements or attributes are defined in the schema, the validation
|
|
process will where necessary create new nodes containing these
|
|
default values.</p>
|
|
<p>Validation of an element or attribute node only takes into
|
|
account constraints on the content of the element or attribute.
|
|
Validation rules affecting the document as a whole are not applied.
|
|
Specifically, this means:</p>
|
|
<ul>
|
|
<li>
|
|
<p>The validation rule "Validation Root Valid (ID/IDREF)" is not
|
|
applied. This means that validation will not fail if there are
|
|
non-unique ID values or dangling IDREF values in the subtree being
|
|
validated.</p>
|
|
</li>
|
|
<li>
|
|
<p>The validation rule "Validation Rule: Identity-constraint
|
|
Satisfied" <span class="verb">should</span> be applied.</p>
|
|
</li>
|
|
<li>
|
|
<p>There is no check that the document contains unparsed entities
|
|
whose names match the values of nodes of type
|
|
<code>xs:ENTITY</code> or <code>xs:ENTITIES</code>. (XSLT
|
|
<span>2.1</span> provides no facility to construct unparsed
|
|
entities within a tree.)</p>
|
|
</li>
|
|
<li>
|
|
<p>There is no check that the document contains notations whose
|
|
names match the values of nodes of type <code>xs:NOTATION</code>.
|
|
(The XDM data model makes no provision for notations to be
|
|
represented in the tree.)</p>
|
|
</li>
|
|
</ul>
|
|
<p>With these caveats, validating a newly constructed element,
|
|
using strict or lax validation, is equivalent to the following
|
|
steps:</p>
|
|
<ol class="enumar">
|
|
<li>
|
|
<p>The element is serialized to textual XML form, according to the
|
|
rules defined in <a href="#xslt-xquery-serialization-11">[XSLT and
|
|
XQuery Serialization]</a> using the XML output method, with all
|
|
parameters defaulted. Note that this process discards any existing
|
|
<a title="type annotation" class="termref" href=
|
|
"#dt-annotation">type annotations</a>.</p>
|
|
</li>
|
|
<li>
|
|
<p>The resulting XML document is parsed to create an XML
|
|
Information Set (see <a href="#xml-infoset">[XML Information
|
|
Set]</a>.)</p>
|
|
</li>
|
|
<li>
|
|
<p>The Information Set produced in the previous step is validated
|
|
according to the rules in <a href="#xmlschema-1">[XML Schema Part
|
|
1]</a>. The result of this step is a Post-Schema Validation Infoset
|
|
(PSVI). If the validation process is not successful (as defined
|
|
above), a type error is raised.</p>
|
|
</li>
|
|
<li>
|
|
<p>The PSVI produced in the previous step is converted back into
|
|
the XDM data model by the mapping described in <a href=
|
|
"#xpath-datamodel-11">[Data Model]</a> (<a href=
|
|
"http://www.w3.org/TR/xpath-datamodel-11/#PSVI2Types">Section 3.3.1
|
|
Mapping PSVI Additions to Node
|
|
Properties</a><sup><small>DM11</small></sup>). This process creates
|
|
nodes with simple or complex <a title="type annotation" class=
|
|
"termref" href="#dt-annotation">type annotations</a> based on the
|
|
types established during schema validation.</p>
|
|
</li>
|
|
</ol>
|
|
<p>Validating an attribute using strict or lax validation requires
|
|
a modified version of this procedure. A copy of the attribute is
|
|
first added to an element node that is created for the purpose, and
|
|
namespace fixup (see <a href="#namespace-fixup"><i>5.7.3 Namespace
|
|
Fixup</i></a>) is performed on this element node. The name of this
|
|
element is of no consequence, but it must be the same as the name
|
|
of a synthesized element declaration of the form:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xs:element name="E">
|
|
<xs:complexType>
|
|
<xs:sequence/>
|
|
<xs:attribute ref="A"/>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
</pre></div>
|
|
<p>where A is the name of the attribute being validated.</p>
|
|
<p>This synthetic element is then validated using the procedure
|
|
given above for validating elements, and if it is found to be
|
|
valid, a copy of the validated attribute is made, retaining its
|
|
<a title="type annotation" class="termref" href=
|
|
"#dt-annotation">type annotation</a>, but detaching it from the
|
|
containing element (and thus, from any namespace nodes).</p>
|
|
<p>The XDM data model does not permit an attribute node with no
|
|
parent to have a typed value that includes a namespace-qualified
|
|
name, that is, a value whose type is derived from
|
|
<code>xs:QName</code> or <code>xs:NOTATION</code>. This restriction
|
|
is imposed because these types rely on the namespace nodes of a
|
|
containing element to resolve namespace prefixes. Therefore, it is
|
|
an error to validate a parentless attribute against such a type.
|
|
This affects the instructions <a href=
|
|
"#element-attribute"><code>xsl:attribute</code></a>, <a href=
|
|
"#element-copy"><code>xsl:copy</code></a>, and <a href=
|
|
"#element-copy-of"><code>xsl:copy-of</code></a>.</p>
|
|
<p><a name="err-XTTE1545" id="err-XTTE1545"><span class=
|
|
"error">[ERR XTTE1545]</span></a> A <a title="type errors" class=
|
|
"termref" href="#dt-type-error">type error</a> occurs if a
|
|
<code>type</code> or <code>validation</code> attribute is defined
|
|
(explicitly or implicitly) for an instruction that constructs a new
|
|
attribute node, if the effect of this is to cause the attribute
|
|
value to be validated against a type that is derived from, or
|
|
constructed by list or union from, the primitive types
|
|
<code>xs:QName</code> or <code>xs:NOTATION</code>.</p>
|
|
</div>
|
|
</div>
|
|
<div class="div3">
|
|
<h4><a name="validating-document-nodes" id=
|
|
"validating-document-nodes"></a>22.2.2 <a href=
|
|
"#validating-document-nodes" style=
|
|
"text-decoration: none">Validating Document Nodes</a></h4>
|
|
<p>It is possible to apply validation to a document node. This
|
|
happens when a new document node is constructed by one of the
|
|
instructions <a href=
|
|
"#element-document"><code>xsl:document</code></a>, <a href=
|
|
"#element-result-document"><code>xsl:result-document</code></a>,
|
|
<a href="#element-copy"><code>xsl:copy</code></a>, or <a href=
|
|
"#element-copy-of"><code>xsl:copy-of</code></a>, and this
|
|
instruction has a <code>type</code> attribute, or a
|
|
<code>validation</code> attribute with the value
|
|
<code>strict</code> or <code>lax</code>.</p>
|
|
<p>Document-level validation is not applied to the document node
|
|
that is created implicitly when a variable-binding element has no
|
|
<code>select</code> attribute and no <code>as</code> attribute (see
|
|
<a href="#temporary-trees"><i>9.4 Creating implicit document
|
|
nodes</i></a>). This is equivalent to using
|
|
<code>validation="preserve"</code> on <a href=
|
|
"#element-document"><code>xsl:document</code></a>: nodes within
|
|
such trees retain their <a title="type annotation" class="termref"
|
|
href="#dt-annotation">type annotation</a>. Similarly, validation is
|
|
not applied to document nodes created using <a href=
|
|
"#element-message"><code>xsl:message</code></a>.</p>
|
|
<p>The values <code>validation="preserve"</code> and
|
|
<code>validation="strip"</code> do not request validation. In the
|
|
first case, all element and attribute nodes within the tree rooted
|
|
at the new document node retain their <a title="type annotation"
|
|
class="termref" href="#dt-annotation">type annotations</a>. In the
|
|
second case, elements within the tree have their type annotation
|
|
set to <code>xs:untyped</code>, while attributes have their type
|
|
annotation set to <code>xs:untypedAtomic</code>.</p>
|
|
<p>When validation is requested for a document node (that is, when
|
|
<code>validation</code> is set to <code>strict</code> or
|
|
<code>lax</code>, or when a <code>type</code> attribute is
|
|
present), the following processing takes place:</p>
|
|
<ul>
|
|
<li>
|
|
<p><a name="err-XTTE1550" id="err-XTTE1550"><span class=
|
|
"error">[ERR XTTE1550]</span></a> A <a title="type errors" class=
|
|
"termref" href="#dt-type-error">type error</a> occurs unless the
|
|
children of the document node comprise exactly one element node, no
|
|
text nodes, and zero or more comment and processing instruction
|
|
nodes, in any order.</p>
|
|
</li>
|
|
<li>
|
|
<p>The single element node child is validated, using the supplied
|
|
values of the <code>validation</code> and <code>type</code>
|
|
attributes, as described in <a href=
|
|
"#validating-constructed-nodes"><i>22.2.1 Validating Constructed
|
|
Elements and Attributes</i></a>.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>The <code>type</code> attribute on <a href=
|
|
"#element-document"><code>xsl:document</code></a> and <a href=
|
|
"#element-result-document"><code>xsl:result-document</code></a>,
|
|
and on <a href="#element-copy"><code>xsl:copy</code></a> and
|
|
<a href="#element-copy-of"><code>xsl:copy-of</code></a> when
|
|
copying a document node, thus refers to the required type of the
|
|
element node that is the only element child of the document node.
|
|
It does not refer to the type of the document node itself.</p>
|
|
</div>
|
|
</li>
|
|
<li>
|
|
<p>The validation rule "Validation Root Valid (ID/IDREF)" is
|
|
applied to the single element node child of the document node. This
|
|
means that validation will fail if there are non-unique ID values
|
|
or dangling IDREF values in the document tree.</p>
|
|
</li>
|
|
<li>
|
|
<p>Identity constraints, as defined in section 3.11 of <a href=
|
|
"#xmlschema-1">[XML Schema Part 1]</a>, are checked. (This refers
|
|
to constraints defined using <code>xs:unique</code>,
|
|
<code>xs:key</code>, and <code>xs:keyref</code>.)</p>
|
|
</li>
|
|
<li>
|
|
<p>There is no check that the tree contains unparsed entities whose
|
|
names match the values of nodes of type <code>xs:ENTITY</code> or
|
|
<code>xs:ENTITIES</code>. This is because there is no facility in
|
|
XSLT <span>2.1</span> to create unparsed entities in a <a title=
|
|
"result tree" class="termref" href="#dt-result-tree">result
|
|
tree</a>. It is possible to add unparsed entity declarations to the
|
|
result document by referencing a suitable DOCTYPE during
|
|
serialization.</p>
|
|
</li>
|
|
<li>
|
|
<p>There is no check that the document contains notations whose
|
|
names match the values of nodes of type <code>xs:NOTATION</code>.
|
|
This is because notations are not part of the XDM data model. It is
|
|
possible to add notations to the result document by referencing a
|
|
suitable DOCTYPE during serialization.</p>
|
|
</li>
|
|
<li>
|
|
<p>All other children of the document node (comments and processing
|
|
instructions) are copied unchanged.</p>
|
|
</li>
|
|
</ul>
|
|
<p><a name="err-XTTE1555" id="err-XTTE1555"><span class=
|
|
"error">[ERR XTTE1555]</span></a> It is a <a title="type errors"
|
|
class="termref" href="#dt-type-error">type error</a> if, when
|
|
validating a document node, document-level constraints are not
|
|
satisfied. These constraints include identity constraints
|
|
(<code>xs:unique</code>, <code>xs:key</code>, and
|
|
<code>xs:keyref</code>) and ID/IDREF constraints.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="div1">
|
|
<h2><a name="serialization" id="serialization"></a>23 <a href=
|
|
"#serialization" style=
|
|
"text-decoration: none">Serialization</a></h2>
|
|
<p>A <a title="processor" class="termref" href=
|
|
"#dt-processor">processor</a> <span class="verb">may</span> output
|
|
a <a title="final result tree" class="termref" href=
|
|
"#dt-final-result-tree">final result tree</a> as a sequence of
|
|
octets, although it is not <span class="verb">required</span> to be
|
|
able to do so (see <a href="#conformance"><i>24
|
|
Conformance</i></a>). Stylesheet authors can use <a href=
|
|
"#element-output"><code>xsl:output</code></a> declarations to
|
|
specify how they wish result trees to be serialized. If a processor
|
|
serializes a final result tree, it <span class="verb">must</span>
|
|
do so as specified by these declarations.</p>
|
|
<p>The rules governing the output of the serializer are defined in
|
|
<a href="#xslt-xquery-serialization-11">[XSLT and XQuery
|
|
Serialization]</a>. The serialization is controlled using a number
|
|
of serialization parameters. The values of these serialization
|
|
parameters may be set within the <a title="stylesheet" class=
|
|
"termref" href="#dt-stylesheet">stylesheet</a>, using the <a href=
|
|
"#element-output"><code>xsl:output</code></a>, <a href=
|
|
"#element-result-document"><code>xsl:result-document</code></a>,
|
|
and <a href=
|
|
"#element-character-map"><code>xsl:character-map</code></a>
|
|
declarations.</p>
|
|
<p class="element-syntax"><a name="element-output" id=
|
|
"element-output"></a><code><!-- Category: declaration
|
|
--><br />
|
|
<xsl:output<br />
|
|
  name? = <var>qname</var><br />
|
|
  method? = "xml" | "html" | "xhtml" | "text" |
|
|
<var>qname-but-not-ncname</var><br />
|
|
  byte-order-mark? = "yes" | "no"<br />
|
|
  cdata-section-elements? = <var>qnames</var><br />
|
|
  doctype-public? = <var>string</var><br />
|
|
  doctype-system? = <var>string</var><br />
|
|
  encoding? = <var>string</var><br />
|
|
  escape-uri-attributes? = "yes" | "no"<br />
|
|
  include-content-type? = "yes" | "no"<br />
|
|
  indent? = "yes" | "no"<br />
|
|
  media-type? = <var>string</var><br />
|
|
  normalization-form? = "NFC" | "NFD" | "NFKC" | "NFKD" |
|
|
"fully-normalized" | "none" | <var>nmtoken</var><br />
|
|
  omit-xml-declaration? = "yes" | "no"<br />
|
|
  standalone? = "yes" | "no" | "omit"<br />
|
|
  suppress-indentation? = <var>qnames</var><br />
|
|
  undeclare-prefixes? = "yes" | "no"<br />
|
|
  use-character-maps? = <var>qnames</var><br />
|
|
  version? = <var>nmtoken</var> /></code></p>
|
|
<p>The <a href="#element-output"><code>xsl:output</code></a>
|
|
declaration is optional; if used, it <span class="verb">must</span>
|
|
always appear as a <a title="top-level" class="termref" href=
|
|
"#dt-top-level">top-level</a> element within a stylesheet
|
|
module.</p>
|
|
<p>A <a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a> may contain multiple <a href=
|
|
"#element-output"><code>xsl:output</code></a> declarations and may
|
|
include or import stylesheet modules that also contain <a href=
|
|
"#element-output"><code>xsl:output</code></a> declarations. The
|
|
name of an <a href="#element-output"><code>xsl:output</code></a>
|
|
declaration is the value of its <code>name</code> attribute, if
|
|
any.</p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-output-definition" id="dt-output-definition" title=
|
|
"output definition"></a>All the <a href=
|
|
"#element-output"><code>xsl:output</code></a> declarations in a
|
|
stylesheet that share the same name are grouped into a named
|
|
<b>output definition</b>; those that have no name are grouped into
|
|
a single unnamed output definition.<span class=
|
|
"definition">]</span></p>
|
|
<p>A stylesheet always includes an unnamed <a title=
|
|
"output definition" class="termref" href=
|
|
"#dt-output-definition">output definition</a>; in the absence of an
|
|
unnamed <a href="#element-output"><code>xsl:output</code></a>
|
|
declaration, the unnamed output definition is equivalent to the one
|
|
that would be used if the stylesheet contained an <a href=
|
|
"#element-output"><code>xsl:output</code></a> declaration having no
|
|
attributes.</p>
|
|
<p>A named <a title="output definition" class="termref" href=
|
|
"#dt-output-definition">output definition</a> is used when its name
|
|
matches the <code>format</code> attribute used in an <a href=
|
|
"#element-result-document"><code>xsl:result-document</code></a>
|
|
element. The unnamed output definition is used when an <a href=
|
|
"#element-result-document"><code>xsl:result-document</code></a>
|
|
element omits the <code>format</code> attribute. It is also used
|
|
when serializing the <a title="final result tree" class="termref"
|
|
href="#dt-final-result-tree">final result tree</a> that is created
|
|
implicitly in the absence of an <a href=
|
|
"#element-result-document"><code>xsl:result-document</code></a>
|
|
element.</p>
|
|
<p>All the <a href="#element-output"><code>xsl:output</code></a>
|
|
elements making up an <a title="output definition" class="termref"
|
|
href="#dt-output-definition">output definition</a> are effectively
|
|
merged. For those attributes whose values are namespace-sensitive,
|
|
the merging is done after <a title="lexical QName" class="termref"
|
|
href="#dt-lexical-qname">lexical QNames</a> have been converted
|
|
into <a title="expanded-QName" class="termref" href=
|
|
"#dt-expanded-qname">expanded QNames</a>. For the
|
|
<code>cdata-section-elements</code> <span>and
|
|
<code>suppress-indentation</code></span> attributes, the output
|
|
definition uses the union of the values from all the constituent
|
|
<a href="#element-output"><code>xsl:output</code></a> declarations.
|
|
For the <code>use-character-maps</code> attribute, the output
|
|
definition uses the concatenation of the sequences of <a title=
|
|
"expanded-QName" class="termref" href="#dt-expanded-qname">expanded
|
|
QNames</a> values from all the constituent <a href=
|
|
"#element-output"><code>xsl:output</code></a> declarations, taking
|
|
them in order of increasing <a title="import precedence" class=
|
|
"termref" href="#dt-import-precedence">import precedence</a>, or
|
|
where several have the same import precedence, in <a title=
|
|
"declaration order" class="termref" href=
|
|
"#dt-declaration-order">declaration order</a>. For other
|
|
attributes, the <a title="output definition" class="termref" href=
|
|
"#dt-output-definition">output definition</a> uses the value of
|
|
that attribute from the <a href=
|
|
"#element-output"><code>xsl:output</code></a> declaration with the
|
|
highest <a title="import precedence" class="termref" href=
|
|
"#dt-import-precedence">import precedence</a>.</p>
|
|
<p><a name="err-XTSE1560" id="err-XTSE1560"><span class=
|
|
"error">[ERR XTSE1560]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> if two
|
|
<a href="#element-output"><code>xsl:output</code></a> declarations
|
|
within an <a title="output definition" class="termref" href=
|
|
"#dt-output-definition">output definition</a> specify explicit
|
|
values for the same attribute (other than
|
|
<code>cdata-section-elements</code> and
|
|
<code>use-character-maps</code>), with the values of the attributes
|
|
being not equal, unless there is another <a href=
|
|
"#element-output"><code>xsl:output</code></a> declaration within
|
|
the same <a title="output definition" class="termref" href=
|
|
"#dt-output-definition">output definition</a> that has higher
|
|
import precedence and that specifies an explicit value for the same
|
|
attribute.</p>
|
|
<p>If none of the <a href=
|
|
"#element-output"><code>xsl:output</code></a> declarations within
|
|
an <a title="output definition" class="termref" href=
|
|
"#dt-output-definition">output definition</a> specifies a value for
|
|
a particular attribute, then the corresponding serialization
|
|
parameter takes a default value. The default value depends on the
|
|
chosen output method.</p>
|
|
<p>There are some serialization parameters that apply to some
|
|
output methods but not to others. For example, the
|
|
<code>indent</code> attribute has no effect on the
|
|
<code>text</code> output method. If a value is supplied for an
|
|
attribute that is inapplicable to the output method, its value is
|
|
not passed to the serializer. The processor <span class=
|
|
"verb">may</span> validate the value of such an attribute, but is
|
|
not <span class="verb">required</span> to do so.</p>
|
|
<p>An implementation <span class="verb">may</span> allow the
|
|
attributes of the <a href=
|
|
"#element-output"><code>xsl:output</code></a> declaration to be
|
|
overridden, or the default values to be changed, using the API that
|
|
controls the transformation.</p>
|
|
<p>The location to which <a title="final result tree" class=
|
|
"termref" href="#dt-final-result-tree">final result trees</a> are
|
|
serialized (whether in filestore or elsewhere) is <a title=
|
|
"implementation-defined" class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a> (which in
|
|
practice <span class="verb">may</span> mean that it is controlled
|
|
using an implementation-defined API). However, these locations
|
|
<span class="verb">must</span> satisfy the constraint that when two
|
|
<a title="final result tree" class="termref" href=
|
|
"#dt-final-result-tree">final result trees</a> are both created
|
|
(implicitly or explicitly) using relative URI
|
|
<span>references</span> in the <code>href</code> attribute of the
|
|
<a href=
|
|
"#element-result-document"><code>xsl:result-document</code></a>
|
|
instruction, then these relative URI <span>references</span> may be
|
|
used to construct references from one tree to the other, and such
|
|
references <span class="verb">must</span> remain valid when both
|
|
result trees are serialized.</p>
|
|
<p>The <code>method</code> attribute on the <a href=
|
|
"#element-output"><code>xsl:output</code></a> element identifies
|
|
the overall method that is to be used for outputting the <a title=
|
|
"final result tree" class="termref" href=
|
|
"#dt-final-result-tree">final result tree</a>.</p>
|
|
<p><a name="err-XTSE1570" id="err-XTSE1570"><span class=
|
|
"error">[ERR XTSE1570]</span></a> The value <span class=
|
|
"verb">must</span> (if present) be a valid <a title="QName" class=
|
|
"termref" href="#dt-qname">QName</a>. If the <a title="QName"
|
|
class="termref" href="#dt-qname">QName</a> does not have a prefix,
|
|
then it identifies a method specified in <a href=
|
|
"#xslt-xquery-serialization-11">[XSLT and XQuery Serialization]</a>
|
|
and <span class="verb">must</span> be one of <code>xml</code>,
|
|
<code>html</code>, <code>xhtml</code>, or <code>text</code>. If the
|
|
<a title="QName" class="termref" href="#dt-qname">QName</a> has a
|
|
prefix, then the <a title="QName" class="termref" href=
|
|
"#dt-qname">QName</a> is expanded into an <a title="expanded-QName"
|
|
class="termref" href="#dt-expanded-qname">expanded-QName</a> as
|
|
described in <a href="#qname"><i>5.1 Qualified Names</i></a>; the
|
|
<a title="expanded-QName" class="termref" href=
|
|
"#dt-expanded-qname">expanded-QName</a> identifies the output
|
|
method; the behavior in this case is not specified by this
|
|
document.</p>
|
|
<p>The default for the <code>method</code> attribute depends on the
|
|
contents of the tree being serialized, and is chosen as follows. If
|
|
the document node of the <a title="final result tree" class=
|
|
"termref" href="#dt-final-result-tree">final result tree</a> 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:</p>
|
|
<ul>
|
|
<li>
|
|
<p>If the <a title="expanded-QName" class="termref" href=
|
|
"#dt-expanded-qname">expanded-QName</a> of this first element child
|
|
has local part <code>html</code> (in lower case), and namespace URI
|
|
<code>http://www.w3.org/1999/xhtml</code>, then the default output
|
|
method is normally <code>xhtml</code>. However, if the
|
|
<code>version</code> attribute of the <a href=
|
|
"#element-stylesheet"><code>xsl:stylesheet</code></a> element of
|
|
the <a title="principal stylesheet module" class="termref" href=
|
|
"#dt-principal-stylesheet-module">principal stylesheet module</a>
|
|
has the value <code>1.0</code>, and if the result tree is generated
|
|
implicitly (rather than by an explicit <a href=
|
|
"#element-result-document"><code>xsl:result-document</code></a>
|
|
instruction), then the default output method in this situation is
|
|
<code>xml</code>.</p>
|
|
</li>
|
|
<li>
|
|
<p>If the <a title="expanded-QName" class="termref" href=
|
|
"#dt-expanded-qname">expanded-QName</a> of this first element child
|
|
has local part <code>html</code> (in any combination of upper and
|
|
lower case) and a null namespace URI, then the default output
|
|
method is <code>html</code>.</p>
|
|
</li>
|
|
</ul>
|
|
<p>In all other cases, the default output method is
|
|
<code>xml</code>.</p>
|
|
<p>The default output method is used if the selected <a title=
|
|
"output definition" class="termref" href=
|
|
"#dt-output-definition">output definition</a> does not include a
|
|
<code>method</code> attribute.</p>
|
|
<p>The other attributes on <a href=
|
|
"#element-output"><code>xsl:output</code></a> provide parameters
|
|
for the output method. The following attributes are allowed:</p>
|
|
<ul>
|
|
<li>
|
|
<p>The value of the <code>encoding</code> attribute provides the
|
|
value of the <code>encoding</code> parameter to the serialization
|
|
method. The default value is <a title="implementation-defined"
|
|
class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a>, but in the
|
|
case of the <code>xml</code> and <code>xhtml</code> methods it
|
|
<span class="verb">must</span> be either <code>UTF-8</code> or
|
|
<code>UTF-16</code>.</p>
|
|
</li>
|
|
<li>
|
|
<p>The <code>byte-order-mark</code> attribute defines whether a
|
|
byte order mark is written at the start of the file. If the value
|
|
<code>yes</code> is specified, a byte order mark is written; if
|
|
<code>no</code> is specified, no byte order mark is written. The
|
|
default value depends on the encoding used. If the encoding is
|
|
<code>UTF-16</code>, the default is <code>yes</code>; for
|
|
<code>UTF-8</code> it is <a title="implementation-defined" class=
|
|
"termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a>, and for
|
|
all other encodings it is <code>no</code>. The value of the byte
|
|
order mark indicates whether high order bytes are written before or
|
|
after low order bytes; the actual byte order used is <a title=
|
|
"implementation-dependent" class="termref" href=
|
|
"#dt-implementation-dependent">implementation-dependent</a>, unless
|
|
it is defined by the selected encoding.</p>
|
|
</li>
|
|
<li>
|
|
<p>The <code>cdata-section-elements</code> attribute is a
|
|
whitespace-separated list of QNames. The default value is an empty
|
|
list. After expansion of these names using the in-scope namespace
|
|
declarations for the <a href=
|
|
"#element-output"><code>xsl:output</code></a> declaration in which
|
|
they appear, this list of names provides the value of the
|
|
<code>cdata-section-elements</code> parameter to the serialization
|
|
method. In the case of an unprefixed name, the default namespace
|
|
(that is, the namespace declared using <code>xmlns="uri"</code>) is
|
|
used.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>This differs from the rule for most other QNames used in a
|
|
stylesheet. The reason is that these names refer to elements in the
|
|
result document, and therefore follow the same convention as the
|
|
name of a literal result element or the <code>name</code> attribute
|
|
of <a href="#element-element"><code>xsl:element</code></a>.</p>
|
|
</div>
|
|
</li>
|
|
<li>
|
|
<p>The value of the <code>doctype-system</code> attribute provides
|
|
the value of the <code>doctype-system</code> parameter to the
|
|
serialization method. By default, the parameter is not
|
|
supplied.</p>
|
|
</li>
|
|
<li>
|
|
<p>The value of the <code>doctype-public</code> attribute provides
|
|
the value of the <code>doctype-public</code> parameter to the
|
|
serialization method. By default, the parameter is not
|
|
supplied.</p>
|
|
<p>The value of <code>doctype-public</code> must conform to the
|
|
rules for a <a href=
|
|
"http://www.w3.org/TR/2000/REC-xml-20001006#NT-PubidLiteral">PubidLiteral</a><sup><small>XML</small></sup>
|
|
(see <a href="#REC-xml">[XML 1.0]</a>).</p>
|
|
</li>
|
|
<li>
|
|
<p>The value of the <code>escape-uri-attributes</code> attribute
|
|
provides the value of the <code>escape-uri-attributes</code>
|
|
parameter to the serialization method. The default value is
|
|
<code>yes</code>.</p>
|
|
</li>
|
|
<li>
|
|
<p>The value of the <code>include-content-type</code> attribute
|
|
provides the value of the <code>include-content-type</code>
|
|
parameter to the serialization method. The default value is
|
|
<code>yes</code>.</p>
|
|
</li>
|
|
<li>
|
|
<p>The value of the <code>indent</code> attribute provides the
|
|
value of the <code>indent</code> parameter to the serialization
|
|
method. The default value is <code>yes</code> in the case of the
|
|
<code>html</code> and <code>xhtml</code> output methods,
|
|
<code>no</code> in the case of the <code>xml</code> output
|
|
method.</p>
|
|
</li>
|
|
<li>
|
|
<p>The value of the <code>media-type</code> attribute provides the
|
|
value of the <code>media-type</code> parameter to the serialization
|
|
method. The default value is <code>text/xml</code> in the case of
|
|
the <code>xml</code> output method, <code>text/html</code> in the
|
|
case of the <code>html</code> and <code>xhtml</code> output
|
|
methods, and <code>text/plain</code> in the case of the
|
|
<code>text</code> output method.</p>
|
|
</li>
|
|
<li>
|
|
<p>The value of the <code>normalization-form</code> attribute
|
|
provides the value of the <code>normalization-form</code> parameter
|
|
to the serialization method. A value that is an
|
|
<code>NMTOKEN</code> other than one of those enumerated for the
|
|
<code>normalization-form</code> attribute specifies an
|
|
implementation-defined normalization form; the behavior in this
|
|
case is not specified by this document. The default value is
|
|
<code>none</code>.</p>
|
|
</li>
|
|
<li>
|
|
<p>The value of the <code>omit-xml-declaration</code> attribute
|
|
provides the value of the <code>omit-xml-declaration</code>
|
|
parameter to the serialization method. The default value is
|
|
<code>no</code>.</p>
|
|
</li>
|
|
<li>
|
|
<p>The value of the <code>standalone</code> attribute provides the
|
|
value of the <code>standalone</code> parameter to the serialization
|
|
method. The default value is <code>omit</code>; this means that no
|
|
<code>standalone</code> attribute is to be included in the XML
|
|
declaration.</p>
|
|
</li>
|
|
<li>
|
|
<p>The <code>suppress-indentation</code> attribute is a
|
|
whitespace-separated list of QNames. The default value is an empty
|
|
list. After expansion of these names using the in-scope namespace
|
|
declarations for the <a href=
|
|
"#element-output"><code>xsl:output</code></a> declaration in which
|
|
they appear, this list of names provides the value of the
|
|
<code>suppress-indentation</code> parameter to the serialization
|
|
method. In the case of an unprefixed name, the default namespace
|
|
(that is, the namespace declared using <code>xmlns="uri"</code>) is
|
|
used.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>This differs from the rule for most other QNames used in a
|
|
stylesheet. The reason is that these names refer to elements in the
|
|
result document, and therefore follow the same convention as the
|
|
name of a literal result element or the <code>name</code> attribute
|
|
of <a href="#element-element"><code>xsl:element</code></a>.</p>
|
|
</div>
|
|
</li>
|
|
<li>
|
|
<p>The <code>undeclare-prefixes</code> attribute is relevant only
|
|
when producing output with <code>method="xml"</code> and
|
|
<code>version="1.1"</code> (or later). It defines whether namespace
|
|
undeclarations (of the form <code>xmlns:foo=""</code>) <span class=
|
|
"verb">should</span> be output when a child element has no
|
|
namespace node with the same name (that is, namespace prefix) as a
|
|
namespace node of its parent element. The default value is
|
|
<code>no</code>: this means that namespace undeclarations are not
|
|
output, which has the effect that when the resulting XML is
|
|
reparsed, the new tree may contain namespace nodes on the child
|
|
element that were not there in the original tree before
|
|
serialization.</p>
|
|
</li>
|
|
<li>
|
|
<p>The <code>use-character-maps</code> attribute provides a list of
|
|
named character maps that are used in conjunction with this
|
|
<a title="output definition" class="termref" href=
|
|
"#dt-output-definition">output definition</a>. The way this
|
|
attribute is used is described in <a href="#character-maps"><i>23.1
|
|
Character Maps</i></a>. The default value is an empty list.</p>
|
|
</li>
|
|
<li>
|
|
<p>The value of the <code>version</code> attribute provides the
|
|
value of the <code>version</code> parameter to the serialization
|
|
method. The set of permitted values, and the default value, are
|
|
<a title="implementation-defined" class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a>. A
|
|
<a title="serialization error" class="termref" href=
|
|
"#dt-serialization-error">serialization error</a> will be reported
|
|
if the requested version is not supported by the
|
|
implementation.</p>
|
|
</li>
|
|
</ul>
|
|
<p>If the processor performs serialization, then it must signal any
|
|
non-recoverable serialization errors that occur. These have the
|
|
same effect as <a title="non-recoverable dynamic error" class=
|
|
"termref" href="#dt-nonrec-dynamic-error">non-recoverable dynamic
|
|
errors</a>: that is, the processor must signal the error and must
|
|
not finish as if the transformation had been successful.</p>
|
|
<div class="div2">
|
|
<h3><a name="character-maps" id="character-maps"></a>23.1 <a href=
|
|
"#character-maps" style="text-decoration: none">Character
|
|
Maps</a></h3>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-character-map" id="dt-character-map" title=
|
|
"character map"></a>A <b>character map</b> allows a specific
|
|
character appearing in a text or attribute node in the <a title=
|
|
"final result tree" class="termref" href=
|
|
"#dt-final-result-tree">final result tree</a> to be substituted by
|
|
a specified string of characters during serialization.<span class=
|
|
"definition">]</span> The effect of character maps is defined in
|
|
<a href="#xslt-xquery-serialization-11">[XSLT and XQuery
|
|
Serialization]</a>.</p>
|
|
<p>The character map that is supplied as a parameter to the
|
|
serializer is determined from the <a href=
|
|
"#element-character-map"><code>xsl:character-map</code></a>
|
|
elements referenced from the <a href=
|
|
"#element-output"><code>xsl:output</code></a> declaration for the
|
|
selected <a title="output definition" class="termref" href=
|
|
"#dt-output-definition">output definition</a>.</p>
|
|
<p>The <a href=
|
|
"#element-character-map"><code>xsl:character-map</code></a> element
|
|
is a declaration that may appear as a child of the <a href=
|
|
"#element-stylesheet"><code>xsl:stylesheet</code></a> element.</p>
|
|
<p class="element-syntax"><a name="element-character-map" id=
|
|
"element-character-map"></a><code><!-- Category: declaration
|
|
--><br />
|
|
<xsl:character-map<br />
|
|
  <b>name</b> = <var>qname</var><br />
|
|
  use-character-maps? = <var>qnames</var> ><br />
|
|
  <!-- Content: (<a href=
|
|
"#element-output-character">xsl:output-character</a>*) --><br />
|
|
</xsl:character-map></code></p>
|
|
<p>The <a href=
|
|
"#element-character-map"><code>xsl:character-map</code></a>
|
|
declaration declares a character map with a name and a set of
|
|
character mappings. The character mappings are specified by means
|
|
of <a href=
|
|
"#element-output-character"><code>xsl:output-character</code></a>
|
|
elements contained either directly within the <a href=
|
|
"#element-character-map"><code>xsl:character-map</code></a>
|
|
element, or in further character maps referenced in the
|
|
<code>use-character-maps</code> attribute.</p>
|
|
<p>The <span class="verb">required</span> <code>name</code>
|
|
attribute provides a name for the character map. When a character
|
|
map is used by an <a title="output definition" class="termref"
|
|
href="#dt-output-definition">output definition</a> or another
|
|
character map, the character map with the highest <a title=
|
|
"import precedence" class="termref" href=
|
|
"#dt-import-precedence">import precedence</a> is used.</p>
|
|
<p><a name="err-XTSE1580" id="err-XTSE1580"><span class=
|
|
"error">[ERR XTSE1580]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> if the
|
|
<a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a> contains two or more character maps
|
|
with the same name and the same <a title="import precedence" class=
|
|
"termref" href="#dt-import-precedence">import precedence</a>,
|
|
unless it also contains another character map with the same name
|
|
and higher import precedence.</p>
|
|
<p>The optional <code>use-character-maps</code> attribute lists the
|
|
names of further character maps that are included into this
|
|
character map.</p>
|
|
<p><a name="err-XTSE1590" id="err-XTSE1590"><span class=
|
|
"error">[ERR XTSE1590]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> if a name
|
|
in the <code>use-character-maps</code> attribute of the <a href=
|
|
"#element-output"><code>xsl:output</code></a> or <a href=
|
|
"#element-character-map"><code>xsl:character-map</code></a>
|
|
elements does not match the <code>name</code> attribute of any
|
|
<a href="#element-character-map"><code>xsl:character-map</code></a>
|
|
in the <a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a>.</p>
|
|
<p><a name="err-XTSE1600" id="err-XTSE1600"><span class=
|
|
"error">[ERR XTSE1600]</span></a> It is a <a title="static error"
|
|
class="termref" href="#dt-static-error">static error</a> if a
|
|
character map references itself, directly or indirectly, via a name
|
|
in the <code>use-character-maps</code> attribute.</p>
|
|
<p>It is not an error if the same character map is referenced more
|
|
than once, directly or indirectly.</p>
|
|
<p>An <a title="output definition" class="termref" href=
|
|
"#dt-output-definition">output definition</a>, after recursive
|
|
expansion of character maps referenced via its
|
|
<code>use-character-maps</code> attribute, may contain several
|
|
mappings for the same character. In this situation, the last
|
|
character mapping takes precedence. To establish the ordering, the
|
|
following rules are used:</p>
|
|
<ul>
|
|
<li>
|
|
<p>Within a single <a href=
|
|
"#element-character-map"><code>xsl:character-map</code></a>
|
|
element, the characters defined in character maps referenced in the
|
|
<code>use-character-maps</code> attribute are considered before the
|
|
characters defined in the child <a href=
|
|
"#element-output-character"><code>xsl:output-character</code></a>
|
|
elements.</p>
|
|
</li>
|
|
<li>
|
|
<p>The character maps referenced in a single
|
|
<code>use-character-maps</code> attribute are considered in the
|
|
order in which they are listed in that attribute. The expansion is
|
|
depth-first: each referenced character map is fully expanded before
|
|
the next one is considered.</p>
|
|
</li>
|
|
<li>
|
|
<p>Two <a href=
|
|
"#element-output-character"><code>xsl:output-character</code></a>
|
|
elements appearing as children of the same <a href=
|
|
"#element-character-map"><code>xsl:character-map</code></a> element
|
|
are considered in document order.</p>
|
|
</li>
|
|
</ul>
|
|
<p>The <a href=
|
|
"#element-output-character"><code>xsl:output-character</code></a>
|
|
element is defined as follows:</p>
|
|
<p class="element-syntax"><a name="element-output-character" id=
|
|
"element-output-character"></a><code><xsl:output-character<br />
|
|
  <b>character</b> = <var>char</var><br />
|
|
  <b>string</b> = <var>string</var> /></code></p>
|
|
<p>The character map that is passed as a parameter to the
|
|
serializer contains a mapping for the character specified in the
|
|
<code>character</code> attribute to the string specified in the
|
|
<code>string</code> attribute.</p>
|
|
<p>Character mapping is not applied to characters for which output
|
|
escaping has been disabled as described in <a href=
|
|
"#disable-output-escaping"><i>23.2 Disabling Output
|
|
Escaping</i></a>.</p>
|
|
<p>If a character is mapped, then it is not subjected to XML or
|
|
HTML escaping.</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e41690" id=
|
|
"d7e41690"></a>Example: Using Character Maps to Generate Non-XML
|
|
Output</div>
|
|
<p>Character maps can be useful when producing serialized output in
|
|
a format that resembles, but is not strictly conformant to, HTML or
|
|
XML. For example, when the output is a JSP page, there might be a
|
|
need to generate the output:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<jsp:setProperty name="user" property="id" value='<%= "id" + idValue %>'/>
|
|
</pre></div>
|
|
<p>Although this output is not well-formed XML or HTML, it is valid
|
|
in Java Server Pages. This can be achieved by allocating three
|
|
Unicode characters (which are not needed for any other purpose) to
|
|
represent the strings <code><%</code>, <code>%></code>, and
|
|
<code>"</code>, for example:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:character-map name="jsp">
|
|
<xsl:output-character character="«" string="&lt;%"/>
|
|
<xsl:output-character character="»" string="%&gt;"/>
|
|
<xsl:output-character character="§" string='"'/>
|
|
</xsl:character-map>
|
|
</pre></div>
|
|
<p>When this character map is referenced in the <a href=
|
|
"#element-output"><code>xsl:output</code></a> declaration, the
|
|
required output can be produced by writing the following in the
|
|
stylesheet:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<jsp:setProperty name="user" property="id" value='«= §id§ + idValue »'/>
|
|
</pre></div>
|
|
<p>This works on the assumption that when an apostrophe or
|
|
quotation mark is generated as part of an attribute value by the
|
|
use of character maps, the serializer will (where possible) use the
|
|
other choice of delimiter around the attribute value.</p>
|
|
</div>
|
|
<p> </p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e41719" id=
|
|
"d7e41719"></a>Example: Constructing a Composite Character
|
|
Map</div>
|
|
<p>The following example illustrates a composite character map
|
|
constructed in a modular fashion:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:output name="htmlDoc" use-character-maps="htmlDoc" />
|
|
|
|
<xsl:character-map name="htmlDoc"
|
|
use-character-maps="html-chars doc-entities windows-format" />
|
|
|
|
<xsl:character-map name="html-chars"
|
|
use-character-maps="latin1 ..." />
|
|
|
|
<xsl:character-map name="latin1">
|
|
<xsl:output-character character="&#160;" string="&amp;nbsp;" />
|
|
<xsl:output-character character="&#161;" string="&amp;iexcl;" />
|
|
...
|
|
</xsl:character-map>
|
|
|
|
<xsl:character-map name="doc-entities">
|
|
<xsl:output-character character="&#xE400;" string="&amp;t-and-c;" />
|
|
<xsl:output-character character="&#xE401;" string="&amp;chap1;" />
|
|
<xsl:output-character character="&#xE402;" string="&amp;chap2;" />
|
|
...
|
|
</xsl:character-map>
|
|
|
|
<xsl:character-map name="windows-format">
|
|
<!-- newlines as CRLF -->
|
|
<xsl:output-character character="&#xA;" string="&#xD;&#xA;" />
|
|
|
|
<!-- tabs as three spaces -->
|
|
<xsl:output-character character="&#x9;" string=" " />
|
|
|
|
<!-- images for special characters -->
|
|
<xsl:output-character character="&#xF001;"
|
|
string="&lt;img src='special1.gif' /&gt;" />
|
|
<xsl:output-character character="&#xF002;"
|
|
string="&lt;img src='special2.gif' /&gt;" />
|
|
...
|
|
</xsl:character-map>
|
|
</pre></div>
|
|
</div>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="disable-output-escaping" id=
|
|
"disable-output-escaping"></a>23.2 <a href=
|
|
"#disable-output-escaping" style="text-decoration: none">Disabling
|
|
Output Escaping</a></h3>
|
|
<p>Normally, when using the XML, HTML, or XHTML output method, the
|
|
serializer will escape special characters such as
|
|
<code>&</code> and <code><</code> when outputting text
|
|
nodes. This ensures that the output is well-formed. 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 defines a mechanism for disabling output escaping.</p>
|
|
<p>This feature is <a title="deprecated" class="termref" href=
|
|
"#dt-deprecated">deprecated</a>.</p>
|
|
<p>This is an optional feature: it is not <span class=
|
|
"verb">required</span> that a XSLT processor that implements the
|
|
serialization option <span class="verb">should</span> offer the
|
|
ability to disable output escaping, and there is no conformance
|
|
level that requires this feature.</p>
|
|
<p>This feature requires an extension to the serializer described
|
|
in <a href="#xslt-xquery-serialization-11">[XSLT and XQuery
|
|
Serialization]</a>. Conceptually, the <a title="final result tree"
|
|
class="termref" href="#dt-final-result-tree">final result tree</a>
|
|
provides an additional boolean property
|
|
<code>disable-escaping</code> associated with every character in a
|
|
text node. When this property is set, the normal action of the
|
|
serializer to escape special characters such as <code>&</code>
|
|
and <code><</code> is suppressed.</p>
|
|
<p>An <a href="#element-value-of"><code>xsl:value-of</code></a> or
|
|
<a href="#element-text"><code>xsl:text</code></a> element may have
|
|
a <code>disable-output-escaping</code> attribute; the allowed
|
|
values are <code>yes</code> or <code>no</code>. The default is
|
|
<code>no</code>; if the value is <code>yes</code>, then every
|
|
character in the text node generated by evaluating the <a href=
|
|
"#element-value-of"><code>xsl:value-of</code></a> or <a href=
|
|
"#element-text"><code>xsl:text</code></a> element <span class=
|
|
"verb">should</span> have the <code>disable-output</code> property
|
|
set.</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e41802" id=
|
|
"d7e41802"></a>Example: Disable Output Escaping</div>
|
|
<p>For example,</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<xsl:text disable-output-escaping="yes">&lt;</xsl:text>
|
|
</pre></div>
|
|
<p>should generate the single character <code><</code>.</p>
|
|
</div>
|
|
<p>If output escaping is disabled for an <a href=
|
|
"#element-value-of"><code>xsl:value-of</code></a> or <a href=
|
|
"#element-text"><code>xsl:text</code></a> instruction evaluated
|
|
when <a title="temporary output state" class="termref" href=
|
|
"#dt-temporary-output-state">temporary output state</a> is in
|
|
effect, the request to disable output escaping is ignored.</p>
|
|
<p>If output escaping is disabled for text within an element that
|
|
would normally be output using a CDATA section, because the element
|
|
is listed in the <code>cdata-section-elements</code>, then the
|
|
relevant text will not be included in a CDATA section. In effect,
|
|
CDATA is treated as an alternative escaping mechanism, which is
|
|
disabled by the <code>disable-output-escaping</code> option.</p>
|
|
<div class="example">
|
|
<div class="exampleHeader"><a name="d7e41833" id=
|
|
"d7e41833"></a>Example: Interaction of Output Escaping and
|
|
CDATA</div>
|
|
<p>For example, if <code><xsl:output
|
|
cdata-section-elements="title"/></code> is specified, then the
|
|
following instructions:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<title>
|
|
<xsl:text disable-output-escaping="yes">This is not &lt;hr/&gt;
|
|
good coding practice</xsl:text>
|
|
</title>
|
|
</pre></div>
|
|
<p>should generate the output:</p>
|
|
<div class="exampleInner">
|
|
<pre>
|
|
<title><![CDATA[This is not ]]><hr/><![CDATA[ good coding practice]]></title>
|
|
</pre></div>
|
|
</div>
|
|
<p>The <code>disable-output-escaping</code> attribute may be used
|
|
with the <code>html</code> output method as well as with the
|
|
<code>xml</code> output method. The <code>text</code> output method
|
|
ignores the <code>disable-output-escaping</code> attribute, since
|
|
it does not perform any output escaping.</p>
|
|
<p>A <a title="processor" class="termref" href=
|
|
"#dt-processor">processor</a> will only be able to disable output
|
|
escaping if it controls how the <a title="final result tree" class=
|
|
"termref" href="#dt-final-result-tree">final result tree</a> is
|
|
output. This might not always be the case. For example, the result
|
|
tree might be used as a <a title="source tree" class="termref"
|
|
href="#dt-source-tree">source tree</a> for another XSLT
|
|
transformation instead of being output. It is <a title=
|
|
"implementation-defined" class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a> whether
|
|
(and under what circumstances) disabling output escaping is
|
|
supported.</p>
|
|
<p><a name="err-XTRE1620" id="err-XTRE1620"><span class=
|
|
"error">[ERR XTRE1620]</span></a> It is a <a title=
|
|
"recoverable error" class="termref" href=
|
|
"#dt-recoverable-error">recoverable dynamic error</a> if an
|
|
<a href="#element-value-of"><code>xsl:value-of</code></a> or
|
|
<a href="#element-text"><code>xsl:text</code></a> instruction
|
|
specifies that output escaping is to be disabled and the
|
|
implementation does not support this. The <a title=
|
|
"optional recovery action" class="termref" href=
|
|
"#dt-optional-recovery-action">optional recovery action</a> is to
|
|
ignore the <code>disable-output-escaping</code> attribute.</p>
|
|
<p><a name="err-XTRE1630" id="err-XTRE1630"><span class=
|
|
"error">[ERR XTRE1630]</span></a> It is a <a title=
|
|
"recoverable error" class="termref" href=
|
|
"#dt-recoverable-error">recoverable dynamic error</a> if an
|
|
<a href="#element-value-of"><code>xsl:value-of</code></a> or
|
|
<a href="#element-text"><code>xsl:text</code></a> instruction
|
|
specifies that output escaping is to be disabled when writing to a
|
|
<a title="final result tree" class="termref" href=
|
|
"#dt-final-result-tree">final result tree</a> that is not being
|
|
serialized. The <a title="optional recovery action" class="termref"
|
|
href="#dt-optional-recovery-action">optional recovery action</a> is
|
|
to ignore the <code>disable-output-escaping</code> attribute.</p>
|
|
<p>If output escaping is disabled for a character that is not
|
|
representable in the encoding that the <a title="processor" class=
|
|
"termref" href="#dt-processor">processor</a> is using for output,
|
|
the request to disable output escaping is ignored in respect of
|
|
that character.</p>
|
|
<p>Since disabling output escaping might not work with all
|
|
implementations and can result in XML that is not well-formed, it
|
|
<span class="verb">should</span> be used only when there is no
|
|
alternative.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>The facility to define character maps for use during
|
|
serialization, as described in <a href="#character-maps"><i>23.1
|
|
Character Maps</i></a>, has been produced as an alternative
|
|
mechanism that can be used in many situations where disabling of
|
|
output escaping was previously necessary, without the same
|
|
difficulties.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="div1">
|
|
<h2><a name="conformance" id="conformance"></a>24 <a href=
|
|
"#conformance" style="text-decoration: none">Conformance</a></h2>
|
|
<p>A <a title="processor" class="termref" href=
|
|
"#dt-processor">processor</a> that claims conformance with this
|
|
specification <span class="verb">must</span> claim conformance
|
|
either as a <a title="basic XSLT processor" class="termref" href=
|
|
"#dt-basic-xslt-processor">basic XSLT processor</a> or as a
|
|
<a title="schema-aware XSLT processor" class="termref" href=
|
|
"#dt-schema-aware-xslt-processor">schema-aware XSLT processor</a>.
|
|
The rules for these two conformance levels are defined in the
|
|
following sections.</p>
|
|
<p>A processor that claims conformance at either of these two
|
|
levels <span class="verb">may</span> additionally claim conformance
|
|
with either or both of the following optional features: the
|
|
serialization feature, defined in <a href=
|
|
"#serialization-feature"><i>24.3 Serialization Feature</i></a>, and
|
|
the backwards compatibility feature, defined in <a href=
|
|
"#backwards-compatibility-feature"><i>24.4 Compatibility
|
|
Features</i></a>.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>There is no conformance level or feature defined in this
|
|
specification that requires implementation of the static typing
|
|
features described in <a href="#xpath-21">[XPath 2.1]</a>. An XSLT
|
|
processor may provide a user option to invoke static typing, but to
|
|
be conformant with this specification it must allow a stylesheet to
|
|
be processed with static typing disabled. The interaction of XSLT
|
|
stylesheets with the static typing feature of <span>XPath
|
|
2.1</span> has not been specified, so the results of using static
|
|
typing, if available, are implementation-defined.</p>
|
|
</div>
|
|
<p>An XSLT processor takes as its inputs a stylesheet and one or
|
|
more XDM trees conforming to the data model defined in <a href=
|
|
"#xpath-datamodel-11">[Data Model]</a>. It is not <span class=
|
|
"verb">required</span> that the processor supports any particular
|
|
method of constructing XDM trees, but conformance can only be
|
|
tested if it provides a mechanism that enables XDM trees
|
|
representing the stylesheet and primary source document to be
|
|
constructed and supplied as input to the processor.</p>
|
|
<p>The output of the XSLT processor consists of zero or more
|
|
<a title="final result tree" class="termref" href=
|
|
"#dt-final-result-tree">final result trees</a>. It is not
|
|
<span class="verb">required</span> that the processor supports any
|
|
particular method of accessing a final result tree, but if it does
|
|
not support the serialization module, conformance can only be
|
|
tested if it provides some alternative mechanism that enables
|
|
access to the results of the transformation.</p>
|
|
<p>Certain facilities in this specification are described as
|
|
producing <a title="implementation-defined" class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a> results. A
|
|
claim that asserts conformance with this specification <span class=
|
|
"verb">must</span> be accompanied by documentation stating the
|
|
effect of each implementation-defined feature. For convenience, a
|
|
non-normative checklist of implementation-defined features is
|
|
provided at <a href="#implementation-defined-features"><i>E
|
|
Checklist of Implementation-Defined Features</i></a>.</p>
|
|
<p>A conforming <a title="processor" class="termref" href=
|
|
"#dt-processor">processor</a> <span class="verb">must</span> signal
|
|
any <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> occurring in the stylesheet, or
|
|
in any XPath <a title="expression" class="termref" href=
|
|
"#dt-expression">expression</a>, except where specified otherwise
|
|
either for individual error conditions or under the general
|
|
provisions for <a title="forwards compatible behavior" class=
|
|
"termref" href="#dt-forwards-compatible-behavior">forwards
|
|
compatible behavior</a> (see <a href="#forwards"><i>3.9 Forwards
|
|
Compatible Processing</i></a>). After signaling such an error, the
|
|
processor <span class="verb">may</span> continue for the purpose of
|
|
signaling additional errors, but <span class="verb">must</span>
|
|
terminate abnormally without performing any transformation.</p>
|
|
<p>When a <a title="dynamic error" class="termref" href=
|
|
"#dt-dynamic-error">dynamic error</a> occurs during the course of a
|
|
transformation, the action depends on whether the error is
|
|
classified as a <a title="recoverable error" class="termref" href=
|
|
"#dt-recoverable-error">recoverable error</a>. If a non-recoverable
|
|
error occurs, the processor <span class="verb">must</span> signal
|
|
it and <span class="verb">must</span> eventually terminate
|
|
abnormally. If a recoverable error occurs, the processor
|
|
<span class="verb">must</span> either signal it and terminate
|
|
abnormally, or it <span class="verb">must</span> take the defined
|
|
recovery action and continue processing.</p>
|
|
<p>Some errors, notably <a title="type errors" class="termref"
|
|
href="#dt-type-error">type errors</a>, <span class=
|
|
"verb">may</span> be treated as <a title="static error" class=
|
|
"termref" href="#dt-static-error">static errors</a> or <a title=
|
|
"dynamic error" class="termref" href="#dt-dynamic-error">dynamic
|
|
errors</a> at the discretion of the processor.</p>
|
|
<p>A conforming processor <span class="verb">may</span> impose
|
|
limits on the processing resources consumed by the processing of a
|
|
stylesheet.</p>
|
|
<div class="div2">
|
|
<h3><a name="basic-conformance" id="basic-conformance"></a>24.1
|
|
<a href="#basic-conformance" style="text-decoration: none">Basic
|
|
XSLT Processor</a></h3>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-basic-xslt-processor" id="dt-basic-xslt-processor" title=
|
|
"basic XSLT processor"></a>A <b>basic XSLT processor</b> is an XSLT
|
|
processor that implements all the mandatory requirements of this
|
|
specification with the exception of certain explicitly identified
|
|
constructs related to schema processing.<span class=
|
|
"definition">]</span> These constructs are listed below.</p>
|
|
<p>The mandatory requirements of this specification are taken to
|
|
include the mandatory requirements of <span>XPath 2.1</span>, as
|
|
described in <a href="#xpath-21">[XPath 2.1]</a>. A requirement is
|
|
mandatory unless the specification includes wording (such as the
|
|
use of the words <span class="verb">should</span> or <span class=
|
|
"verb">may</span>) that clearly indicates that it is optional.</p>
|
|
<p>A <a title="basic XSLT processor" class="termref" href=
|
|
"#dt-basic-xslt-processor">basic XSLT processor</a> <span class=
|
|
"verb">must</span> enforce the following restrictions. It
|
|
<span class="verb">must</span> signal a static or dynamic error
|
|
when the restriction is violated, as described below.</p>
|
|
<p><a name="err-XTSE1650" id="err-XTSE1650"><span class=
|
|
"error">[ERR XTSE1650]</span></a> A <a title="basic XSLT processor"
|
|
class="termref" href="#dt-basic-xslt-processor">basic XSLT
|
|
processor</a> <span class="verb">must</span> signal a <a title=
|
|
"static error" class="termref" href="#dt-static-error">static
|
|
error</a> if the <a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a> includes an <a href=
|
|
"#element-import-schema"><code>xsl:import-schema</code></a>
|
|
declaration.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>A processor that rejects an <a href=
|
|
"#element-import-schema"><code>xsl:import-schema</code></a>
|
|
declaration will also reject any reference to a user-defined type
|
|
defined in a schema, or to a user-defined element or attribute
|
|
declaration; it will not, however, reject references to the
|
|
built-in types listed in <a href="#built-in-types"><i>3.13 Built-in
|
|
Types</i></a>.</p>
|
|
</div>
|
|
<p>A <a title="basic XSLT processor" class="termref" href=
|
|
"#dt-basic-xslt-processor">basic XSLT processor</a> is not able to
|
|
validate input documents, and is not able to handle input documents
|
|
containing type annotations other than <code>xs:untyped</code> or
|
|
<code>xs:untypedAtomic</code>. Therefore, such a processor
|
|
<span class="verb">must</span> treat any
|
|
<code>[xsl:]validation</code> or <code>default-validation</code>
|
|
attribute with a value of <code>preserve</code> or <code>lax</code>
|
|
as if the value were <code>strip</code>.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>The values <code>lax</code> and <code>preserve</code> indicate
|
|
that the validation to be applied depends on the calling
|
|
application, so it is appropriate for the request to be treated
|
|
differently by different kinds of processor. By contrast,
|
|
requesting <code>strict</code> validation, either through the
|
|
<code>[xsl:]validation</code> attribute or the <code>type</code>
|
|
attribute, indicates that the stylesheet is expecting to deal with
|
|
typed data, and therefore cannot be processed without performing
|
|
the validation.</p>
|
|
</div>
|
|
<p><a name="err-XTSE1660" id="err-XTSE1660"><span class=
|
|
"error">[ERR XTSE1660]</span></a> A <a title="basic XSLT processor"
|
|
class="termref" href="#dt-basic-xslt-processor">basic XSLT
|
|
processor</a> <span class="verb">must</span> signal a <a title=
|
|
"static error" class="termref" href="#dt-static-error">static
|
|
error</a> if the <a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a> includes an <code>[xsl:]type</code>
|
|
attribute, or an <code>[xsl:]validation</code> or
|
|
<code>default-validation</code> attribute with a value other than
|
|
<code>strip</code><span>, <code>preserve</code>, or
|
|
<code>lax</code></span>.</p>
|
|
<p>A <a title="basic XSLT processor" class="termref" href=
|
|
"#dt-basic-xslt-processor">basic XSLT processor</a> constrains the
|
|
data model as follows:</p>
|
|
<ul>
|
|
<li>
|
|
<p>Atomic values <span class="verb">must</span> belong to one of
|
|
the atomic types listed in <a href="#built-in-types"><i>3.13
|
|
Built-in Types</i></a> (except as noted below).</p>
|
|
<p>An atomic value may also belong to an implementation-defined
|
|
type that has been added to the context for use with <a title=
|
|
"extension function" class="termref" href=
|
|
"#dt-extension-function">extension functions</a> or <a title=
|
|
"extension instruction" class="termref" href=
|
|
"#dt-extension-instruction">extension instructions</a>.</p>
|
|
<p>The set of constructor functions available are limited to those
|
|
that construct values of the above atomic types.</p>
|
|
<p>The static context, which defines the full set of type names
|
|
recognized by an XSLT processor and also by the XPath processor,
|
|
includes these atomic types, plus <code>xs:anyType</code>,
|
|
<code>xs:anySimpleType</code>, <code>xs:untyped</code>, and
|
|
<code>xs:anyAtomicType</code>.</p>
|
|
</li>
|
|
<li>
|
|
<p>Element nodes <span class="verb">must</span> be annotated with
|
|
the <a title="type annotation" class="termref" href=
|
|
"#dt-annotation">type annotation</a> <code>xs:untyped</code>, and
|
|
attribute nodes with the type annotation
|
|
<code>xs:untypedAtomic</code>.</p>
|
|
</li>
|
|
</ul>
|
|
<p><a name="err-XTDE1665" id="err-XTDE1665"><span class=
|
|
"error">[ERR XTDE1665]</span></a> A <a title="basic XSLT processor"
|
|
class="termref" href="#dt-basic-xslt-processor">basic XSLT
|
|
processor</a> <span class="verb">must</span> raise a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> if the
|
|
input to the processor includes a node with a <a title=
|
|
"type annotation" class="termref" href="#dt-annotation">type
|
|
annotation</a> other than <code>xs:untyped</code> or
|
|
<code>xs:untypedAtomic</code>, or an atomic value of a type other
|
|
than those which a basic XSLT processor supports. This error will
|
|
not arise if the <code>input-type-annotations</code> attribute is
|
|
set to <code>strip</code>.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>Although this is expressed in terms of a requirement to detect
|
|
invalid input, an alternative approach is for a basic XSLT
|
|
processor to prevent this error condition occurring, by not
|
|
providing any interfaces that would allow the situation to arise. A
|
|
processor might, for example, implement a mapping from the PSVI to
|
|
the data model that loses all non-trivial <a title=
|
|
"type annotation" class="termref" href="#dt-annotation">type
|
|
annotations</a>; or it might not accept input from a PSVI at
|
|
all.</p>
|
|
<p>The phrase <em>input to the processor</em> is deliberately wide:
|
|
it includes the tree containing the <span><a title=
|
|
"initial context item" class="termref" href=
|
|
"#dt-initial-context-item">initial context item</a></span>, trees
|
|
passed as <a title="stylesheet parameter" class="termref" href=
|
|
"#dt-stylesheet-parameter">stylesheet parameters</a>, trees
|
|
accessed using the <a href=
|
|
"#function-document"><code>document</code></a>, <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-doc"><code>doc</code></a><sup><small>FO</small></sup>,
|
|
and <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-collection"><code>collection</code></a><sup><small>FO</small></sup>
|
|
functions, and trees returned by <a title="extension function"
|
|
class="termref" href="#dt-extension-function">extension
|
|
functions</a> and <a title="extension instruction" class="termref"
|
|
href="#dt-extension-instruction">extension instructions</a>.</p>
|
|
</div>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="schema-aware-conformance" id=
|
|
"schema-aware-conformance"></a>24.2 <a href=
|
|
"#schema-aware-conformance" style=
|
|
"text-decoration: none">Schema-Aware XSLT Processor</a></h3>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-schema-aware-xslt-processor" id=
|
|
"dt-schema-aware-xslt-processor" title=
|
|
"schema-aware XSLT processor"></a>A <b>schema-aware XSLT
|
|
processor</b> is an XSLT processor that implements all the
|
|
mandatory requirements of this specification, including those
|
|
features that a <a title="basic XSLT processor" class="termref"
|
|
href="#dt-basic-xslt-processor">basic XSLT processor</a> signals as
|
|
an error. The mandatory requirements of this specification are
|
|
taken to include the mandatory requirements of <span>XPath
|
|
2.1</span>, as described in <a href="#xpath-21">[XPath 2.1]</a>. A
|
|
requirement is mandatory unless the specification includes wording
|
|
(such as the use of the words <span class="verb">should</span> or
|
|
<span class="verb">may</span>) that clearly indicates that it is
|
|
optional.<span class="definition">]</span></p>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="serialization-feature" id=
|
|
"serialization-feature"></a>24.3 <a href="#serialization-feature"
|
|
style="text-decoration: none">Serialization Feature</a></h3>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-serialization-feature" id="dt-serialization-feature" title=
|
|
"serialization feature"></a>A processor that claims conformance
|
|
with the <b>serialization feature</b> <span class=
|
|
"verb">must</span> support the conversion of a <a title=
|
|
"final result tree" class="termref" href=
|
|
"#dt-final-result-tree">final result tree</a> to a sequence of
|
|
octets following the rules defined in <a href=
|
|
"#serialization"><i>23 Serialization</i></a>.<span class=
|
|
"definition">]</span> It <span class="verb">must</span> respect all
|
|
the attributes of the <a href=
|
|
"#element-output"><code>xsl:output</code></a> and <a href=
|
|
"#element-character-map"><code>xsl:character-map</code></a>
|
|
declarations, and <span class="verb">must</span> provide all four
|
|
output methods, <code>xml</code>, <code>xhtml</code>,
|
|
<code>html</code>, and <code>text</code>. Where the specification
|
|
uses words such as <span class="verb">must</span> and <span class=
|
|
"verb">required</span>, then it <span class="verb">must</span>
|
|
serialize the result tree in precisely the way described; in other
|
|
cases it <span class="verb">may</span> use an alternative,
|
|
equivalent representation.</p>
|
|
<p>A processor may claim conformance with the serialization feature
|
|
whether or not it supports the setting
|
|
<code>disable-output-escaping="yes"</code> on <a href=
|
|
"#element-text"><code>xsl:text</code></a>, or <a href=
|
|
"#element-value-of"><code>xsl:value-of</code></a>.</p>
|
|
<p>A processor that does not claim conformance with the
|
|
serialization feature <span class="verb">must not</span> signal an
|
|
error merely because the <a title="stylesheet" class="termref"
|
|
href="#dt-stylesheet">stylesheet</a> contains <a href=
|
|
"#element-output"><code>xsl:output</code></a> or <a href=
|
|
"#element-character-map"><code>xsl:character-map</code></a>
|
|
declarations, or serialization attributes on the <a href=
|
|
"#element-result-document"><code>xsl:result-document</code></a>
|
|
instruction. Such a processor <span class="verb">may</span> check
|
|
that these declarations and attributes have valid values, but is
|
|
not <span class="verb">required</span> to do so. Apart from
|
|
optional validation, these declarations <span class=
|
|
"verb">should</span> be ignored.</p>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="backwards-compatibility-feature" id=
|
|
"backwards-compatibility-feature"></a>24.4 <a href=
|
|
"#backwards-compatibility-feature" style=
|
|
"text-decoration: none">Compatibility Features</a></h3>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-1.0-compatibility-feature" id="dt-1.0-compatibility-feature"
|
|
title="XSLT 1.0 compatibility feature"></a>A processor that claims
|
|
conformance with the <b>XSLT 1.0 compatibility feature</b>
|
|
<span class="verb">must</span> support the processing of stylesheet
|
|
instructions and XPath expressions with <a title=
|
|
"XSLT 1.0 behavior" class="termref" href=
|
|
"#dt-xslt-10-behavior">XSLT 1.0 behavior</a>, as defined in
|
|
<a href="#backwards"><i>3.8 Backwards Compatible
|
|
Processing</i></a>.<span class="definition">]</span></p>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-2.0-compatibility-feature" id="dt-2.0-compatibility-feature"
|
|
title="XSLT 2.0 compatibility feature"></a>A processor that claims
|
|
conformance with the <b>XSLT 2.0 compatibility feature</b>
|
|
<span class="verb">must</span> support the processing of stylesheet
|
|
instructions and XPath expressions with <a title=
|
|
"XSLT 2.0 behavior" class="termref" href=
|
|
"#dt-xslt-20-behavior">XSLT 2.0 behavior</a>, as defined in
|
|
<a href="#backwards"><i>3.8 Backwards Compatible
|
|
Processing</i></a>.<span class="definition">]</span></p>
|
|
<p>Note that a processor that does not claim conformance with the
|
|
<a title="XSLT 1.0 compatibility feature" class="termref" href=
|
|
"#dt-1.0-compatibility-feature">XSLT 1.0 compatibility feature</a>
|
|
<span class="verb">must</span> raise a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> if an
|
|
instruction is evaluated whose <a title="effective version" class=
|
|
"termref" href="#dt-effective-version">effective version</a> is
|
|
1.0; and similarly, a processor that does not claim conformance
|
|
with the <a title="XSLT 2.0 compatibility feature" class="termref"
|
|
href="#dt-2.0-compatibility-feature">XSLT 2.0 compatibility
|
|
feature</a> <span class="verb">must</span> raise a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> if an
|
|
instruction is evaluated whose <a title="effective version" class=
|
|
"termref" href="#dt-effective-version">effective version</a> is
|
|
2.0. <span class="error">[see <a href="#err-XTDE0160">ERR
|
|
XTDE0160</a>]</span>.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>The reason this is a dynamic error rather than a static error is
|
|
to allow stylesheets to contain conditional logic, following
|
|
different paths depending on whether the XSLT processor implements
|
|
<span>XSLT 1.0, 2.0, or 2.1</span>. The selection of which path to
|
|
use can be controlled by using the <a href=
|
|
"#function-system-property"><code>system-property</code></a>
|
|
function to test the <code>xsl:version</code> system property.</p>
|
|
</div>
|
|
<p>A processor that claims conformance with the <a title=
|
|
"XSLT 1.0 compatibility feature" class="termref" href=
|
|
"#dt-1.0-compatibility-feature">XSLT 1.0 compatibility feature</a>
|
|
<span class="verb">must</span> permit the use of the namespace axis
|
|
in XPath expressions when backwards compatible behavior is enabled.
|
|
In all other circumstances, support for the namespace axis is
|
|
optional.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>Currently, there are no incompatibilities between 2.1 and 2.0
|
|
that justify this machinery. This will be reviewed at a later stage
|
|
of development of the specification.</p>
|
|
</div>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="streaming-feature" id="streaming-feature"></a>24.5
|
|
<a href="#streaming-feature" style=
|
|
"text-decoration: none">Streaming Feature</a></h3>
|
|
<p><span class="definition">[Definition: </span><a name=
|
|
"dt-streaming-feature" id="dt-streaming-feature" title=
|
|
"streaming feature"></a>A processor that claims conformance with
|
|
the <b>streaming feature</b> <span class="verb">must</span>
|
|
....<span class="definition">]</span></p>
|
|
<blockquote>
|
|
<p><b><a name="issue-streaming-conformance" id=
|
|
"issue-streaming-conformance">Issue 34
|
|
(streaming-conformance)</a>:</b></p>
|
|
<p>We need to define the conformance rules for streaming
|
|
processors.</p>
|
|
</blockquote>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="back">
|
|
<div class="div1">
|
|
<h2><a name="references" id="references"></a>A <a href=
|
|
"#references" style="text-decoration: none">References</a></h2>
|
|
<div class="div2">
|
|
<h3><a name="normative-references" id=
|
|
"normative-references"></a>A.1 <a href="#normative-references"
|
|
style="text-decoration: none">Normative References</a></h3>
|
|
<dl>
|
|
<dt class="label"><span><a name="xpath-datamodel-11" id=
|
|
"xpath-datamodel-11"></a>Data Model</span></dt>
|
|
<dd>
|
|
<div><a href=
|
|
"http://www.w3.org/TR/xpath-datamodel-11/"><cite>XQuery and XPath
|
|
Data Model (XDM) 1.1</cite></a>, Norman Walsh, John Snelson,
|
|
Editors. World Wide Web Consortium, 15 December 2009. This version
|
|
is http://www.w3.org/TR/2009/WD-xpath-datamodel-11-20091215/. The
|
|
<a href="http://www.w3.org/TR/xpath-datamodel-11/">latest
|
|
version</a> is available at
|
|
http://www.w3.org/TR/xpath-datamodel-11/.</div>
|
|
</dd>
|
|
<dt class="label"><span><a name="xpath-functions-11" id=
|
|
"xpath-functions-11"></a>Functions and Operators</span></dt>
|
|
<dd>
|
|
<div><a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/"><cite>XQuery and XPath
|
|
Functions and Operators 1.1</cite></a>, Michael Kay, Editor. World
|
|
Wide Web Consortium, 15 December 2009. This version is
|
|
http://www.w3.org/TR/2009/WD-xpath-functions-11-20091215/. The
|
|
<a href="http://www.w3.org/TR/xpath-functions-11/">latest
|
|
version</a> is available at
|
|
http://www.w3.org/TR/xpath-functions-11/.</div>
|
|
</dd>
|
|
<dt class="label"><span><a name="xml-infoset" id=
|
|
"xml-infoset"></a>XML Information Set</span></dt>
|
|
<dd>
|
|
<div><a href="http://www.w3.org/TR/xml-infoset"><cite>XML
|
|
Information Set (Second Edition)</cite></a>, Richard Tobin and John
|
|
Cowan, Editors. World Wide Web Consortium, 04 Feb 2004.
|
|
This version is http://www.w3.org/TR/2004/REC-xml-infoset-20040204.
|
|
The <a href="http://www.w3.org/TR/xml-infoset">latest version</a>
|
|
is available at http://www.w3.org/TR/xml-infoset.</div>
|
|
</dd>
|
|
<dt class="label"><span><a name="ISO3166" id="ISO3166"></a>ISO
|
|
3166-1</span></dt>
|
|
<dd>
|
|
<div>ISO (International Organization for Standardization) <em>Codes
|
|
for the representation of names of countries and their subdivisions
|
|
- Part 1: Country codes</em> ISO 3166-1:1997. Second edition,
|
|
2006-11-20.</div>
|
|
</dd>
|
|
<dt class="label"><span><a name="ISO8601" id="ISO8601"></a>ISO
|
|
8601</span></dt>
|
|
<dd>
|
|
<div>ISO (International Organization for Standardization) <em>Data
|
|
elements and interchange formats - Information interchange -
|
|
Representation of dates and times.</em> ISO 8601:2004, Third
|
|
edition, 2004-12-03.</div>
|
|
</dd>
|
|
<dt class="label"><span><a name="xslt-xquery-serialization-11" id=
|
|
"xslt-xquery-serialization-11"></a>XSLT and XQuery
|
|
Serialization</span></dt>
|
|
<dd>
|
|
<div><a href=
|
|
"http://www.w3.org/TR/xslt-xquery-serialization-11/"><cite>XSLT and
|
|
XQuery Serialization 1.1</cite></a>, Henry Zongaro, Editor. World
|
|
Wide Web Consortium, 15 December 2009. This version is
|
|
http://www.w3.org/TR/2009/WD-xslt-xquery-serialization-11-20091215/.
|
|
The <a href=
|
|
"http://www.w3.org/TR/xslt-xquery-serialization-11/">latest
|
|
version</a> is available at
|
|
http://www.w3.org/TR/xslt-xquery-serialization-11/.</div>
|
|
</dd>
|
|
<dt class="label"><span><a name="REC-xml" id="REC-xml"></a>XML
|
|
1.0</span></dt>
|
|
<dd>
|
|
<div>World Wide Web Consortium. <em>Extensible Markup Language
|
|
(XML) 1.0. W3C Recommendation.</em> See <a href=
|
|
"http://www.w3.org/TR/REC-xml">http://www.w3.org/TR/REC-xml</a>.
|
|
The edition of XML 1.0 must be no earlier than the Third Edition;
|
|
the edition used is <a title="implementation-defined" class=
|
|
"termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a>, but we
|
|
recommend that implementations use the latest version.</div>
|
|
</dd>
|
|
<dt class="label"><span><a name="xml11" id="xml11"></a>XML
|
|
1.1</span></dt>
|
|
<dd>
|
|
<div><a href="http://www.w3.org/TR/xml11/"><cite>Extensible Markup
|
|
Language (XML) 1.1 (Second Edition)</cite></a>, Eve Maler, Jean
|
|
Paoli, John Cowan, <em>et. al.</em>, Editors. World Wide Web
|
|
Consortium, 16 Aug 2006. This version is
|
|
http://www.w3.org/TR/2006/REC-xml11-20060816. The <a href=
|
|
"http://www.w3.org/TR/xml11/">latest version</a> is available at
|
|
http://www.w3.org/TR/xml11/.</div>
|
|
</dd>
|
|
<dt class="label"><span><a name="xmlbase" id="xmlbase"></a>XML
|
|
Base</span></dt>
|
|
<dd>
|
|
<div><a href="http://www.w3.org/TR/xmlbase/"><cite>XML Base (Second
|
|
Edition)</cite></a>, Jonathan Marsh and Richard Tobin, Editors.
|
|
World Wide Web Consortium, 28 Jan 2009. This version is
|
|
http://www.w3.org/TR/2009/REC-xmlbase-20090128/. The <a href=
|
|
"http://www.w3.org/TR/xmlbase/">latest version</a> is available at
|
|
http://www.w3.org/TR/xmlbase/.</div>
|
|
</dd>
|
|
<dt class="label"><span><a name="xml-id" id=
|
|
"xml-id"></a>xml:id</span></dt>
|
|
<dd>
|
|
<div><a href="http://www.w3.org/TR/xml-id/"><cite>xml:id Version
|
|
1.0</cite></a>, Norman Walsh, Daniel Veillard, and Jonathan Marsh,
|
|
Editors. World Wide Web Consortium, 09 Sep 2005. This
|
|
version is http://www.w3.org/TR/2005/REC-xml-id-20050909/. The
|
|
<a href="http://www.w3.org/TR/xml-id/">latest version</a> is
|
|
available at http://www.w3.org/TR/xml-id/.</div>
|
|
</dd>
|
|
<dt class="label"><span><a name="xml-names" id=
|
|
"xml-names"></a>Namespaces in XML</span></dt>
|
|
<dd>
|
|
<div><a href="http://www.w3.org/TR/xml-names"><cite>Namespaces in
|
|
XML 1.0 (Third Edition)</cite></a>, Dave Hollander, Richard Tobin,
|
|
Tim Bray, <em>et. al.</em>, Editors. World Wide Web Consortium,
|
|
08 Dec 2009. This version is
|
|
http://www.w3.org/TR/2009/REC-xml-names-20091208/. The <a href=
|
|
"http://www.w3.org/TR/xml-names">latest version</a> is available at
|
|
http://www.w3.org/TR/xml-names.</div>
|
|
</dd>
|
|
<dt class="label"><span><a name="xml-names11" id=
|
|
"xml-names11"></a>Namespaces in XML 1.1</span></dt>
|
|
<dd>
|
|
<div><a href="http://www.w3.org/TR/xml-names11/"><cite>Namespaces
|
|
in XML 1.1 (Second Edition)</cite></a>, Dave Hollander, Tim Bray,
|
|
Andrew Layman, and Richard Tobin, Editors. World Wide Web
|
|
Consortium, 16 Aug 2006. This version is
|
|
http://www.w3.org/TR/2006/REC-xml-names11-20060816. The <a href=
|
|
"http://www.w3.org/TR/xml-names11/">latest version</a> is available
|
|
at http://www.w3.org/TR/xml-names11/.</div>
|
|
</dd>
|
|
<dt class="label"><span><a name="xmlschema-1" id=
|
|
"xmlschema-1"></a>XML Schema Part 1</span></dt>
|
|
<dd>
|
|
<div><a href="http://www.w3.org/TR/xmlschema-1/"><cite>XML Schema
|
|
Part 1: Structures Second Edition</cite></a>, David Beech, Henry S.
|
|
Thompson, Murray Maloney, and Noah Mendelsohn, Editors. World Wide
|
|
Web Consortium, 28 Oct 2004. This version is
|
|
http://www.w3.org/TR/2004/REC-xmlschema-1-20041028/. The <a href=
|
|
"http://www.w3.org/TR/xmlschema-1/">latest version</a> is available
|
|
at http://www.w3.org/TR/xmlschema-1/.</div>
|
|
</dd>
|
|
<dt class="label"><span><a name="xmlschema-2" id=
|
|
"xmlschema-2"></a>XML Schema Part 2</span></dt>
|
|
<dd>
|
|
<div><a href="http://www.w3.org/TR/xmlschema-2/"><cite>XML Schema
|
|
Part 2: Datatypes Second Edition</cite></a>, Ashok Malhotra and
|
|
Paul V. Biron, Editors. World Wide Web Consortium,
|
|
28 Oct 2004. This version is
|
|
http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/. The <a href=
|
|
"http://www.w3.org/TR/xmlschema-2/">latest version</a> is available
|
|
at http://www.w3.org/TR/xmlschema-2/.</div>
|
|
</dd>
|
|
<dt class="label"><span><a name="xpath-21" id="xpath-21"></a>XPath
|
|
2.1</span></dt>
|
|
<dd>
|
|
<div><a href="http://www.w3.org/TR/xpath-21/"><cite>XML Path
|
|
Language (XPath) 2.1</cite></a>, Jonathan Robie, Don Chamberlin,
|
|
Michael Dyck, John Snelson, Editors. World Wide Web Consortium, 15
|
|
December 2009. This version is
|
|
http://www.w3.org/TR/2009/WD-xpath-21-20091215/. The <a href=
|
|
"http://www.w3.org/TR/xpath-21/">latest version</a> is available at
|
|
http://www.w3.org/TR/xpath-21/.</div>
|
|
</dd>
|
|
<dt class="label"><span><a name="XSLT-Mime-Type" id=
|
|
"XSLT-Mime-Type"></a>XSLT Media Type</span></dt>
|
|
<dd>
|
|
<div>World Wide Web Consortium. <em>Registration of MIME Media Type
|
|
application/xslt+xml</em>. In <a href=
|
|
"http://www.w3.org/TR/2007/REC-xslt20-20070123/#media-type-registration">
|
|
Appendix B.1 of the XSLT 2.0 specification.</a></div>
|
|
</dd>
|
|
</dl>
|
|
</div>
|
|
<div class="div2">
|
|
<h3><a name="other-references" id="other-references"></a>A.2
|
|
<a href="#other-references" style="text-decoration: none">Other
|
|
References</a></h3>
|
|
<dl>
|
|
<dt class="label"><span><a name="CALCALC" id=
|
|
"CALCALC"></a>Calendrical Calculations</span></dt>
|
|
<dd>
|
|
<div>Edward M. Reingold and Nachum Dershowitz. <em>Calendrical
|
|
Calculations Millennium edition (2nd Edition)</em>. Cambridge
|
|
University Press, ISBN 0 521 77752 6</div>
|
|
</dd>
|
|
<dt class="label"><span><a name="DOM-Level-2-Core" id=
|
|
"DOM-Level-2-Core"></a>DOM Level 2</span></dt>
|
|
<dd>
|
|
<div><a href=
|
|
"http://www.w3.org/TR/DOM-Level-2-Core/"><cite>Document Object
|
|
Model (DOM) Level 2 Core Specification</cite></a>, Philippe Le
|
|
Hégaret, Steve Byrne, Gavin Nicol, <em>et. al.</em>, Editors. World
|
|
Wide Web Consortium, 13 Nov 2000. This version is
|
|
http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113. The
|
|
<a href="http://www.w3.org/TR/DOM-Level-2-Core/">latest version</a>
|
|
is available at http://www.w3.org/TR/DOM-Level-2-Core/.</div>
|
|
</dd>
|
|
<dt class="label"><span><a name="RFC2119" id=
|
|
"RFC2119"></a>RFC2119</span></dt>
|
|
<dd>
|
|
<div>S. Bradner. <em>Key words for use in RFCs to Indicate
|
|
Requirement Levels</em>. IETF RFC 2119. See <a href=
|
|
"http://www.ietf.org/rfc/rfc2119.txt">http://www.ietf.org/rfc/rfc2119.txt</a>.</div>
|
|
</dd>
|
|
<dt class="label"><span><a name="RFC2376" id=
|
|
"RFC2376"></a>RFC2376</span></dt>
|
|
<dd>
|
|
<div>E. Whitehead, M. Murata. <em>XML Media Types</em>. IETF RFC
|
|
2376. See <a href=
|
|
"http://www.ietf.org/rfc/rfc2376.txt">http://www.ietf.org/rfc/rfc2376.txt</a>.</div>
|
|
</dd>
|
|
<dt class="label"><span><a name="RFC3023" id=
|
|
"RFC3023"></a>RFC3023</span></dt>
|
|
<dd>
|
|
<div>M. Murata, S. St.Laurent, and D. Cohn. <em>XML Media
|
|
Types</em>. IETF RFC 3023. See <a href=
|
|
"http://www.ietf.org/rfc/rfc3023.txt">http://www.ietf.org/rfc/rfc3023.txt</a>.
|
|
References to RFC 3023 should be taken to refer to any document
|
|
that supersedes RFC 3023.</div>
|
|
</dd>
|
|
<dt class="label"><span><a name="RFC3986" id=
|
|
"RFC3986"></a>RFC3986</span></dt>
|
|
<dd>
|
|
<div>T. Berners-Lee, R. Fielding, and L. Masinter. <em>Uniform
|
|
Resource Identifiers (URI): Generic Syntax</em>. IETF RFC 3986. See
|
|
<a href=
|
|
"http://www.ietf.org/rfc/rfc3986.txt">http://www.ietf.org/rfc/rfc3986.txt</a>.</div>
|
|
</dd>
|
|
<dt class="label"><span><a name="RFC3987" id=
|
|
"RFC3987"></a>RFC3987</span></dt>
|
|
<dd>
|
|
<div>M. Duerst, M. Suignard. <em>Internationalized Resource
|
|
Identifiers (IRIs)</em>. IETF RFC 3987. See <a href=
|
|
"http://www.ietf.org/rfc/rfc3987.txt">http://www.ietf.org/rfc/rfc3987.txt</a>.</div>
|
|
</dd>
|
|
<dt class="label"><span><a name="marian-simeon" id=
|
|
"marian-simeon"></a>Marian & Siméon</span></dt>
|
|
<dd>
|
|
<div>Amélie Marian and Jérôme Siméon. <em>Projecting XML
|
|
Documents</em>. VLDB'2003, Berlin, Germany, September 2003. See
|
|
<a href=
|
|
"http://portal.acm.org/citation.cfm?id=1315471">http://portal.acm.org/citation.cfm?id=1315471</a></div>
|
|
</dd>
|
|
<dt class="label"><span><a name="STX" id="STX"></a>STX</span></dt>
|
|
<dd>
|
|
<div>Petr Cimprich <em>et al</em>, <em>Streaming Transformations
|
|
for XML (STX) Version 1.0</em>. Working Draft 27 April 2007. See
|
|
<a href=
|
|
"http://stx.sourceforge.net/documents/spec-stx-20070427.html">http://stx.sourceforge.net/documents/spec-stx-20070427.html</a></div>
|
|
</dd>
|
|
<dt class="label"><span><a name="UNICODE-TR10" id=
|
|
"UNICODE-TR10"></a>UNICODE TR10</span></dt>
|
|
<dd>
|
|
<div>Unicode Consortium. <em>Unicode Technical Standard #10.
|
|
Unicode Collation Algorithm</em>. Unicode Technical Report. See
|
|
<a href=
|
|
"http://www.unicode.org/unicode/reports/tr10/">http://www.unicode.org/unicode/reports/tr10/</a>.</div>
|
|
</dd>
|
|
<dt class="label"><span><a name="xinclude" id=
|
|
"xinclude"></a>XInclude</span></dt>
|
|
<dd>
|
|
<div><a href="http://www.w3.org/TR/xinclude/"><cite>XML Inclusions
|
|
(XInclude) Version 1.0 (Second Edition)</cite></a>, Daniel
|
|
Veillard, David Orchard, and Jonathan Marsh, Editors. World Wide
|
|
Web Consortium, 15 Nov 2006. This version is
|
|
http://www.w3.org/TR/2006/REC-xinclude-20061115/. The <a href=
|
|
"http://www.w3.org/TR/xinclude/">latest version</a> is available at
|
|
http://www.w3.org/TR/xinclude/.</div>
|
|
</dd>
|
|
<dt class="label"><span><a name="xlink" id=
|
|
"xlink"></a>XLink</span></dt>
|
|
<dd>
|
|
<div><a href="http://www.w3.org/TR/xlink/"><cite>XML Linking
|
|
Language (XLink) Version 1.0</cite></a>, Eve Maler, Steven DeRose,
|
|
and David Orchard, Editors. World Wide Web Consortium,
|
|
27 Jun 2001. This version is
|
|
http://www.w3.org/TR/2001/REC-xlink-20010627/. The <a href=
|
|
"http://www.w3.org/TR/xlink/">latest version</a> is available at
|
|
http://www.w3.org/TR/xlink/.</div>
|
|
</dd>
|
|
<dt class="label"><span><a name="SCHEMA-AND-XML-1.1" id=
|
|
"SCHEMA-AND-XML-1.1"></a>XML Schema 1.0 and XML 1.1</span></dt>
|
|
<dd>
|
|
<div>World Wide Web Consortium. <em>Processing XML 1.1 documents
|
|
with XML Schema 1.0 processors</em>. W3C Working Group Note 11 May
|
|
2005. See <a href=
|
|
"http://www.w3.org/TR/2005/NOTE-xml11schema10-20050511/">http://www.w3.org/TR/2005/NOTE-xml11schema10-20050511/</a></div>
|
|
</dd>
|
|
<dt class="label"><span><a name="xml-stylesheet" id=
|
|
"xml-stylesheet"></a>XML Stylesheet</span></dt>
|
|
<dd>
|
|
<div><a href=
|
|
"http://www.w3.org/TR/xml-stylesheet"><cite>Associating Style
|
|
Sheets with XML documents</cite></a>, James Clark, Editor. World
|
|
Wide Web Consortium, 29 Jun 1999. This version is
|
|
http://www.w3.org/1999/06/REC-xml-stylesheet-19990629. The <a href=
|
|
"http://www.w3.org/TR/xml-stylesheet">latest version</a> is
|
|
available at http://www.w3.org/TR/xml-stylesheet.</div>
|
|
</dd>
|
|
<dt class="label"><span><a name="xptr-framework" id=
|
|
"xptr-framework"></a>XPointer Framework</span></dt>
|
|
<dd>
|
|
<div><a href="http://www.w3.org/TR/xptr-framework/"><cite>XPointer
|
|
Framework</cite></a>, Jonathan Marsh, Paul Grosso, Eve Maler, and
|
|
Norman Walsh, Editors. World Wide Web Consortium,
|
|
25 Mar 2003. This version is
|
|
http://www.w3.org/TR/2003/REC-xptr-framework-20030325/. The
|
|
<a href="http://www.w3.org/TR/xptr-framework/">latest version</a>
|
|
is available at http://www.w3.org/TR/xptr-framework/.</div>
|
|
</dd>
|
|
<dt class="label"><span><a name="xsl11" id=
|
|
"xsl11"></a>XSL-FO</span></dt>
|
|
<dd>
|
|
<div><a href="http://www.w3.org/TR/xsl11/"><cite>Extensible
|
|
Stylesheet Language (XSL) Version 1.1</cite></a>, Anders Berglund,
|
|
Editor. World Wide Web Consortium, 05 Dec 2006. This
|
|
version is http://www.w3.org/TR/2006/REC-xsl11-20061205/. The
|
|
<a href="http://www.w3.org/TR/xsl11/">latest version</a> is
|
|
available at http://www.w3.org/TR/xsl11/.</div>
|
|
</dd>
|
|
<dt class="label"><span><a name="xslt" id="xslt"></a>XSLT
|
|
1.0</span></dt>
|
|
<dd>
|
|
<div><a href="http://www.w3.org/TR/xslt"><cite>XSL Transformations
|
|
(XSLT) Version 1.0</cite></a>, James Clark, Editor. World Wide Web
|
|
Consortium, 16 Nov 1999. This version is
|
|
http://www.w3.org/TR/1999/REC-xslt-19991116. The <a href=
|
|
"http://www.w3.org/TR/xslt">latest version</a> is available at
|
|
http://www.w3.org/TR/xslt.</div>
|
|
</dd>
|
|
<dt class="label"><span><a name="xslt20" id="xslt20"></a>XSLT
|
|
2.0</span></dt>
|
|
<dd>
|
|
<div><a href="http://www.w3.org/TR/xslt20"><cite>XSL
|
|
Transformations (XSLT) Version 2.0</cite></a>, Michael Kay, Editor.
|
|
World Wide Web Consortium, 23 January 2007. This version is
|
|
http://www.w3.org/TR/2007/REC-xslt20-20070123/. The <a href=
|
|
"http://www.w3.org/TR/xslt20/">latest version</a> is available at
|
|
http://www.w3.org/TR/xslt20/.</div>
|
|
</dd>
|
|
</dl>
|
|
</div>
|
|
</div>
|
|
<div class="div1">
|
|
<h2><a name="glossary" id="glossary"></a>B Glossary
|
|
(Non-Normative)</h2>
|
|
<dl>
|
|
<dt><a href="#dt-alias">alias</a></dt>
|
|
<dd>
|
|
<p>A stylesheet can use the <a href=
|
|
"#element-namespace-alias"><code>xsl:namespace-alias</code></a>
|
|
element to declare that a <a title="literal namespace URI" class=
|
|
"termref" href="#dt-literal-namespace-uri">literal namespace
|
|
URI</a> is being used as an <b>alias</b> for a <a title=
|
|
"target namespace URI" class="termref" href=
|
|
"#dt-target-namespace-uri">target namespace URI</a>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-arity">arity</a></dt>
|
|
<dd>
|
|
<p>The <b>arity</b> of a stylesheet function is the number of
|
|
<a href="#element-param"><code>xsl:param</code></a> elements in the
|
|
function definition.</p>
|
|
</dd>
|
|
<dt><a href="#dt-atomization">atomize</a></dt>
|
|
<dd>
|
|
<p>The term <b>atomization</b> is defined in <a href=
|
|
"http://www.w3.org/TR/xpath-21/#id-atomization">Section 2.4.2
|
|
Atomization</a><sup><small>XP21</small></sup>. It is a process that
|
|
takes as input a sequence of <span>items</span>, and returns a
|
|
sequence of atomic values, in which the nodes are replaced by their
|
|
typed values as defined in <a href="#xpath-datamodel-11">[Data
|
|
Model]</a>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-attribute-set">attribute set</a></dt>
|
|
<dd>
|
|
<p>The <a href=
|
|
"#element-attribute-set"><code>xsl:attribute-set</code></a> element
|
|
defines a named <b>attribute set</b>: that is, a collection of
|
|
attribute definitions that can be used repeatedly on different
|
|
constructed elements.</p>
|
|
</dd>
|
|
<dt><a href="#dt-attribute-value-template">attribute value
|
|
template</a></dt>
|
|
<dd>
|
|
<p>In an attribute that is designated as an <b>attribute value
|
|
template</b>, such as an attribute of a <a title=
|
|
"literal result element" class="termref" href=
|
|
"#dt-literal-result-element">literal result element</a>, an
|
|
<a title="expression" class="termref" href=
|
|
"#dt-expression">expression</a> can be used by surrounding the
|
|
expression with curly brackets (<code>{}</code>)</p>
|
|
</dd>
|
|
<dt><a href="#dt-backwards-compatible-behavior">backwards
|
|
compatible behavior</a></dt>
|
|
<dd>
|
|
<p>An element is processed with <b>backwards compatible
|
|
behavior</b> if its <a title="effective version" class="termref"
|
|
href="#dt-effective-version">effective version</a> is less than
|
|
<code>2.1</code>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-base-output-uri">base output URI</a></dt>
|
|
<dd>
|
|
<p>The <b>base output URI</b> is a URI to be used as the base URI
|
|
when resolving a relative URI <span>reference</span> allocated to a
|
|
<a title="final result tree" class="termref" href=
|
|
"#dt-final-result-tree">final result tree</a>. If the
|
|
transformation generates more than one final result tree, then
|
|
typically each one will be allocated a URI relative to this base
|
|
URI.</p>
|
|
</dd>
|
|
<dt><a href="#dt-basic-xslt-processor">basic XSLT
|
|
processor</a></dt>
|
|
<dd>
|
|
<p>A <b>basic XSLT processor</b> is an XSLT processor that
|
|
implements all the mandatory requirements of this specification
|
|
with the exception of certain explicitly identified constructs
|
|
related to schema processing.</p>
|
|
</dd>
|
|
<dt><a href="#dt-character-map">character map</a></dt>
|
|
<dd>
|
|
<p>A <b>character map</b> allows a specific character appearing in
|
|
a text or attribute node in the <a title="final result tree" class=
|
|
"termref" href="#dt-final-result-tree">final result tree</a> to be
|
|
substituted by a specified string of characters during
|
|
serialization.</p>
|
|
</dd>
|
|
<dt><a href="#dt-circularity">circularity</a></dt>
|
|
<dd>
|
|
<p>A <b>circularity</b> is said to exist if a construct such as a
|
|
<a title="global variable" class="termref" href=
|
|
"#dt-global-variable">global variable</a>, an <a title=
|
|
"attribute set" class="termref" href="#dt-attribute-set">attribute
|
|
set</a>, or a <a title="key" class="termref" href=
|
|
"#dt-key">key</a>, is defined in terms of itself. For example, if
|
|
the <a title="expression" class="termref" href=
|
|
"#dt-expression">expression</a> or <a title="sequence constructor"
|
|
class="termref" href="#dt-sequence-constructor">sequence
|
|
constructor</a> specifying the value of a <a title=
|
|
"global variable" class="termref" href="#dt-global-variable">global
|
|
variable</a> <var>X</var> references a global variable
|
|
<var>Y</var>, then the value for <var>Y</var> <span class=
|
|
"verb">must</span> be computed before the value of <var>X</var>. A
|
|
circularity exists if it is impossible to do this for all global
|
|
variable definitions.</p>
|
|
</dd>
|
|
<dt><a href="#dt-collation">collation</a></dt>
|
|
<dd>
|
|
<p>Facilities in XSLT <span>2.1</span> and XPath <span>2.1</span>
|
|
that require strings to be ordered rely on the concept of a named
|
|
<b>collation</b>. A collation is a set of rules that determine
|
|
whether two strings are equal, and if not, which of them is to be
|
|
sorted before the other.</p>
|
|
</dd>
|
|
<dt><a href="#dt-common-prefix">common prefix</a></dt>
|
|
<dd>
|
|
<p>The <b>common prefix</b> of two paths in the data flow graph
|
|
contains the arcs that are present in both paths before the paths
|
|
diverge.</p>
|
|
</dd>
|
|
<dt><a href="#dt-composite-merge-key-value">composite merge key
|
|
value</a></dt>
|
|
<dd>
|
|
<p>The ordered collection of <a title="merge key value" class=
|
|
"termref" href="#dt-merge-key-value">merge key values</a> computed
|
|
for one item in a <a title="merge input sequence" class="termref"
|
|
href="#dt-merge-input-sequence">merge input sequence</a> (one for
|
|
each <a title="merge key component" class="termref" href=
|
|
"#dt-merge-key-component">merge key component</a> within the
|
|
<a title="merge key specification" class="termref" href=
|
|
"#dt-merge-key-specification">merge key specification</a>) is
|
|
referred to as a <b>composite merge key value</b>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-construct">construct</a></dt>
|
|
<dd>
|
|
<p>An <a title="e-node" class="termref" href=
|
|
"#dt-e-node">e-node</a> (a node in the expression tree) represents
|
|
a <b>construct</b>. A <b>construct</b> is a <span>fragment
|
|
of</span> a stylesheet that can be evaluated <span>or
|
|
invoked</span> to produce a value.</p>
|
|
</dd>
|
|
<dt><a href="#dt-context-item">context item</a></dt>
|
|
<dd>
|
|
<p>The <b>context item</b> is the item currently being processed.
|
|
An item (see <a href="#xpath-datamodel-11">[Data Model]</a>) is
|
|
either an atomic value (such as an integer, date, or string), a
|
|
node, <span>or a function item</span>. The context item is
|
|
initially set to the <span><a title="initial context item" class=
|
|
"termref" href="#dt-initial-context-item">initial context
|
|
item</a></span> supplied when the transformation is invoked (see
|
|
<a href="#initiating"><i>2.3 Initiating a Transformation</i></a>).
|
|
It changes whenever instructions such as <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a> and
|
|
<a href="#element-for-each"><code>xsl:for-each</code></a> are used
|
|
to process a sequence of items; each item in such a sequence
|
|
becomes the context item while that item is being processed.</p>
|
|
</dd>
|
|
<dt><a href="#dt-context-node">context node</a></dt>
|
|
<dd>
|
|
<p>If the <a title="context item" class="termref" href=
|
|
"#dt-context-item">context item</a> is a node (as distinct from an
|
|
atomic value such as an integer), then it is also referred to as
|
|
the <b>context node</b>. The context node is not an independent
|
|
variable, it changes whenever the context item changes. When the
|
|
context item is an atomic value <span>or a function item</span>,
|
|
there is no context node.</p>
|
|
</dd>
|
|
<dt><a href="#dt-context-position">context position</a></dt>
|
|
<dd>
|
|
<p>The <b>context position</b> 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
|
|
<a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a> or
|
|
<a href="#element-for-each"><code>xsl:for-each</code></a> 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.</p>
|
|
</dd>
|
|
<dt><a href="#dt-context-size">context size</a></dt>
|
|
<dd>
|
|
<p>The <b>context size</b> is the number of items in the sequence
|
|
of items currently being processed. It changes whenever
|
|
instructions such as <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a> and
|
|
<a href="#element-for-each"><code>xsl:for-each</code></a> 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).</p>
|
|
</dd>
|
|
<dt><a href="#dt-core-function">core function</a></dt>
|
|
<dd>
|
|
<p>The term <b>core function</b> means a function that is specified
|
|
in <a href="#xpath-functions-11">[Functions and Operators]</a> and
|
|
that is in the <a title="standard function namespace" class=
|
|
"termref" href="#dt-standard-function-namespace">standard function
|
|
namespace</a>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-current-captured-substrings">current captured
|
|
substrings</a></dt>
|
|
<dd>
|
|
<p>While the <a href=
|
|
"#element-matching-substring"><code>xsl:matching-substring</code></a>
|
|
instruction is active, a set of <b>current captured substrings</b>
|
|
is available, corresponding to the parenthesized sub-expressions of
|
|
the regular expression.</p>
|
|
</dd>
|
|
<dt><a href="#dt-current-group">current group</a></dt>
|
|
<dd>
|
|
<p>The evaluation context for XPath <a title="expression" class=
|
|
"termref" href="#dt-expression">expressions</a> includes a
|
|
component called the <b>current group</b>, which is a sequence.</p>
|
|
</dd>
|
|
<dt><a href="#dt-current-grouping-key">current grouping
|
|
key</a></dt>
|
|
<dd>
|
|
<p>The evaluation context for XPath <a title="expression" class=
|
|
"termref" href="#dt-expression">expressions</a> includes a
|
|
component called the <b>current grouping key</b>, which is <span>a
|
|
sequence of atomic values</span>. The current grouping key is the
|
|
<a title="grouping key" class="termref" href=
|
|
"#dt-grouping-key">grouping key</a> shared in common by all the
|
|
items within the <a title="current group" class="termref" href=
|
|
"#dt-current-group">current group</a>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-current-merge-activation">current merge
|
|
activation</a></dt>
|
|
<dd>
|
|
<p>During each evaluation of the <a title="sequence constructor"
|
|
class="termref" href="#dt-sequence-constructor">sequence
|
|
constructor</a> contained in an <a href=
|
|
"#element-merge-action"><code>xsl:merge-action</code></a> element,
|
|
there is a <b>current merge activation</b>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-current-mode">current mode</a></dt>
|
|
<dd>
|
|
<p>At any point in the processing of a stylesheet, there is a
|
|
<b>current mode</b>. When the transformation is initiated, the
|
|
current mode is the <span><a title="initial mode" class="termref"
|
|
href="#dt-initial-mode">initial mode</a></span>, as described in
|
|
<a href="#initiating"><i>2.3 Initiating a Transformation</i></a>.
|
|
Whenever an <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>
|
|
instruction is evaluated, the current mode becomes the mode
|
|
selected by this instruction.</p>
|
|
</dd>
|
|
<dt><a href="#dt-current-template-rule">current template
|
|
rule</a></dt>
|
|
<dd>
|
|
<p>At any point in the processing of a <a title="stylesheet" class=
|
|
"termref" href="#dt-stylesheet">stylesheet</a>, there may be a
|
|
<b>current template rule</b>. Whenever a <a title="template rule"
|
|
class="termref" href="#dt-template-rule">template rule</a> is
|
|
chosen as a result of evaluating <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>,
|
|
<a href=
|
|
"#element-apply-imports"><code>xsl:apply-imports</code></a>, or
|
|
<a href="#element-next-match"><code>xsl:next-match</code></a>, the
|
|
template rule becomes the current template rule for the evaluation
|
|
of the rule's sequence constructor. When an <a href=
|
|
"#element-for-each"><code>xsl:for-each</code></a>, <a href=
|
|
"#element-for-each-group"><code>xsl:for-each-group</code></a>,
|
|
<a href=
|
|
"#element-analyze-string"><code>xsl:analyze-string</code></a>,
|
|
<span><a href="#element-iterate"><code>xsl:iterate</code></a>,
|
|
<a href="#element-stream"><code>xsl:stream</code></a>, <a href=
|
|
"#element-merge"><code>xsl:merge</code></a>, or <a href=
|
|
"#element-evaluate"><code>xsl:evaluate</code></a></span>
|
|
instruction is evaluated, or when evaluating a sequence constructor
|
|
contained in an <a href="#element-sort"><code>xsl:sort</code></a>
|
|
or <a href="#element-key"><code>xsl:key</code></a> element, or when
|
|
a <a title="stylesheet function" class="termref" href=
|
|
"#dt-stylesheet-function">stylesheet function</a> is called (see
|
|
<a href="#stylesheet-functions"><i>10.3 Stylesheet
|
|
Functions</i></a>), the current template rule becomes null for the
|
|
evaluation of that instruction or function.</p>
|
|
</dd>
|
|
<dt><a href="#dt-decimal-format">decimal format</a></dt>
|
|
<dd>
|
|
<p>All the <a href=
|
|
"#element-decimal-format"><code>xsl:decimal-format</code></a>
|
|
declarations in a stylesheet that share the same name are grouped
|
|
into a named <b>decimal format</b>; those that have no name are
|
|
grouped into a single unnamed decimal format.</p>
|
|
</dd>
|
|
<dt><a href="#dt-declaration">declaration</a></dt>
|
|
<dd>
|
|
<p>Top-level elements fall into two categories: declarations, and
|
|
user-defined data elements. Top-level elements whose names are in
|
|
the <a title="XSLT namespace" class="termref" href=
|
|
"#dt-xslt-namespace">XSLT namespace</a> are <b>declarations</b>.
|
|
Top-level elements in any other namespace are <a title=
|
|
"user-defined data element" class="termref" href=
|
|
"#dt-data-element">user-defined data elements</a> (see <a href=
|
|
"#user-defined-top-level"><i>3.6.3 User-defined Data
|
|
Elements</i></a>)</p>
|
|
</dd>
|
|
<dt><a href="#dt-declaration-order">declaration order</a></dt>
|
|
<dd>
|
|
<p>The <a title="declaration" class="termref" href=
|
|
"#dt-declaration">declarations</a> within a <a title=
|
|
"stylesheet level" class="termref" href=
|
|
"#dt-stylesheet-level">stylesheet level</a> have a total ordering
|
|
known as <b>declaration order</b>. 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 <a href="#element-include"><code>xsl:include</code></a>
|
|
element that references it.</p>
|
|
</dd>
|
|
<dt><a href="#dt-default-collation">default collation</a></dt>
|
|
<dd>
|
|
<p>In this specification the term <b>default collation</b> means
|
|
the collation that is used by XPath operators such as
|
|
<code>eq</code> and <code>lt</code> appearing in XPath expressions
|
|
within the stylesheet.</p>
|
|
</dd>
|
|
<dt><a href="#dt-default-priority">default priority</a></dt>
|
|
<dd>
|
|
<p>If no <code>priority</code> attribute is specified on an
|
|
<a href="#element-template"><code>xsl:template</code></a> element,
|
|
a <b>default priority</b> is computed, based on the syntax of the
|
|
<a title="pattern" class="termref" href="#dt-pattern">pattern</a>
|
|
supplied in the <code>match</code> attribute.</p>
|
|
</dd>
|
|
<dt><a href="#dt-defining-element">defining element</a></dt>
|
|
<dd>
|
|
<p>A string in the form of a lexical QName may occur as the value
|
|
of an attribute node in a stylesheet module, or within an XPath
|
|
<a title="expression" class="termref" href=
|
|
"#dt-expression">expression</a> 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 <b>defining element</b> of the
|
|
QName.</p>
|
|
</dd>
|
|
<dt><a href="#dt-dependent-instruction">dependent
|
|
(instruction)</a></dt>
|
|
<dd>
|
|
<p>Among the <a title="instruction" class="termref" href=
|
|
"#dt-instruction">instructions</a> directly contained in a
|
|
<a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a>, an instruction
|
|
<var>I</var> is defined to be <b>dependent</b> on an instruction
|
|
<var>J</var> if <var>J</var> is a <a title=
|
|
"variable-binding element" class="termref" href=
|
|
"#dt-variable-binding-element">variable binding</a> and
|
|
<var>I</var> contains a reference to that variable, or if there is
|
|
an instruction <var>K</var> such that <var>I</var> depends on
|
|
<var>K</var> and <var>K</var> depends on <var>J</var>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-deprecated">deprecated</a></dt>
|
|
<dd>
|
|
<p>Some constructs defined in this specification are described as
|
|
being <b>deprecated</b>. The use of this term implies that
|
|
stylesheet authors <span class="verb">should not</span> use the
|
|
construct, and that the construct may be removed in a later version
|
|
of this specification.</p>
|
|
</dd>
|
|
<dt><a href="#dt-dynamic-error">dynamic error</a></dt>
|
|
<dd>
|
|
<p>An error that is not detected until a source document is being
|
|
transformed is referred to as a <b>dynamic error</b>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-e-node">e-node</a></dt>
|
|
<dd>
|
|
<p>To distinguish nodes in an expression tree from other kinds of
|
|
node in other kinds of tree, we refer to them as
|
|
<b>e-nodes</b>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-effective-value">effective value</a></dt>
|
|
<dd>
|
|
<p>The result of evaluating an attribute value template is referred
|
|
to as the <b>effective value</b> of the attribute.</p>
|
|
</dd>
|
|
<dt><a href="#dt-effective-version">effective version</a></dt>
|
|
<dd>
|
|
<p>The <b>effective version</b> of an element in the stylesheet is
|
|
the decimal value of the <code>[xsl:]version</code> attribute (see
|
|
<a href="#standard-attributes"><i>3.5 Standard Attributes</i></a>)
|
|
on that element or on the innermost ancestor element that has such
|
|
an attribute, excluding the <code>version</code> attribute on an
|
|
<a href="#element-output"><code>xsl:output</code></a> element.</p>
|
|
</dd>
|
|
<dt><a href="#dt-embedded-stylesheet-module">embedded stylesheet
|
|
module</a></dt>
|
|
<dd>
|
|
<p>An <b>embedded stylesheet module</b> is a stylesheet module that
|
|
is embedded within another XML document, typically the source
|
|
document that is being transformed.</p>
|
|
</dd>
|
|
<dt><a href="#dt-expanded-qname">expanded-QName</a></dt>
|
|
<dd>
|
|
<p>An <b>expanded-QName</b> contains a pair of values, namely a
|
|
local name and an optional namespace URI. It may also contain a
|
|
namespace prefix. Two expanded-QNames are equal if the namespace
|
|
URIs are the same (or both absent) and the local names are the
|
|
same. The prefix plays no part in the comparison, but is used only
|
|
if the expanded-QName needs to be converted back to a string.</p>
|
|
</dd>
|
|
<dt><a href="#dt-expression">expression</a></dt>
|
|
<dd>
|
|
<p>Within this specification, the term <b>XPath expression</b>, or
|
|
simply <b>expression</b>, means a string that matches the
|
|
production <a href=
|
|
"http://www.w3.org/TR/xpath-21/#prod-xpath21-Expr">Expr</a><sup><small>XP21</small></sup>
|
|
defined in <a href="#xpath-21">[XPath 2.1]</a>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-extension-attribute">extension attribute</a></dt>
|
|
<dd>
|
|
<p>An element from the XSLT namespace may have any attribute not
|
|
from the XSLT namespace, provided that the <a title=
|
|
"expanded-QName" class="termref" href=
|
|
"#dt-expanded-qname">expanded-QName</a> (see <a href=
|
|
"#xpath-21">[XPath 2.1]</a>) of the attribute has a non-null
|
|
namespace URI. These attributes are referred to as <b>extension
|
|
attributes</b>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-extension-function">extension function</a></dt>
|
|
<dd>
|
|
<p>An <b>extension function</b> is a function that is available for
|
|
use within an XPath <a title="expression" class="termref" href=
|
|
"#dt-expression">expression</a>, other than a <a title=
|
|
"core function" class="termref" href="#dt-core-function">core
|
|
function</a> defined in <a href="#xpath-functions-11">[Functions
|
|
and Operators]</a>, an additional function defined in this XSLT
|
|
specification, a constructor function named after an atomic type,
|
|
or a <a title="stylesheet function" class="termref" href=
|
|
"#dt-stylesheet-function">stylesheet function</a> defined using an
|
|
<a href="#element-function"><code>xsl:function</code></a>
|
|
declaration.</p>
|
|
</dd>
|
|
<dt><a href="#dt-extension-instruction">extension
|
|
instruction</a></dt>
|
|
<dd>
|
|
<p>An <b>extension instruction</b> is an element within a <a title=
|
|
"sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> that is in a
|
|
namespace (not the <a title="XSLT namespace" class="termref" href=
|
|
"#dt-xslt-namespace">XSLT namespace</a>) designated as an extension
|
|
namespace.</p>
|
|
</dd>
|
|
<dt><a href="#dt-extension-namespace">extension namespace</a></dt>
|
|
<dd>
|
|
<p>The <a title="extension instruction" class="termref" href=
|
|
"#dt-extension-instruction">extension instruction</a> mechanism
|
|
allows namespaces to be designated as <b>extension namespaces</b>.
|
|
When a namespace is designated as an extension namespace and an
|
|
element with a name from that namespace occurs in a <a title=
|
|
"sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a>, then the
|
|
element is treated as an <a title="instruction" class="termref"
|
|
href="#dt-instruction">instruction</a> rather than as a <a title=
|
|
"literal result element" class="termref" href=
|
|
"#dt-literal-result-element">literal result element</a>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-final-output-state">final output state</a></dt>
|
|
<dd>
|
|
<p>The first of the two <a title="output state" class="termref"
|
|
href="#dt-output-state">output states</a> is called <b>final
|
|
output</b> state. This state applies when instructions are writing
|
|
to a <a title="final result tree" class="termref" href=
|
|
"#dt-final-result-tree">final result tree</a>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-final-result-tree">final result tree</a></dt>
|
|
<dd>
|
|
<p>A <b>final result tree</b> is a <a title="result tree" class=
|
|
"termref" href="#dt-result-tree">result tree</a> that forms part of
|
|
the final output of a transformation. Once created, the contents of
|
|
a final result tree are not accessible within the stylesheet
|
|
itself.</p>
|
|
</dd>
|
|
<dt><a href="#dt-focus">focus</a></dt>
|
|
<dd>
|
|
<p>When a <a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> is evaluated,
|
|
the <a title="processor" class="termref" href=
|
|
"#dt-processor">processor</a> keeps track of which items are being
|
|
processed by means of a set of implicit variables referred to
|
|
collectively as the <b>focus</b>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-forwards-compatible-behavior">forwards compatible
|
|
behavior</a></dt>
|
|
<dd>
|
|
<p>An element is processed with <b>forwards compatible behavior</b>
|
|
if its <a title="effective version" class="termref" href=
|
|
"#dt-effective-version">effective version</a> is greater than
|
|
<code>2.1</code>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-function-conversion-rules">function conversion
|
|
rules</a></dt>
|
|
<dd>
|
|
<p>Except where otherwise indicated, the actual value of an
|
|
<a title="expression" class="termref" href=
|
|
"#dt-expression">expression</a> is converted to the <a title=
|
|
"required type" class="termref" href="#dt-required-type">required
|
|
type</a> using the <b>function conversion rules</b>. These are the
|
|
rules defined in <a href="#xpath-21">[XPath 2.1]</a> for converting
|
|
the supplied argument of a function call to the required type of
|
|
that argument, as defined in the function signature. The relevant
|
|
rules are those that apply when <a title=
|
|
"XPath 1.0 compatibility mode" class="termref" href=
|
|
"#dt-xpath-compat-mode">XPath 1.0 compatibility mode</a> is set to
|
|
<code>false</code>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-function-parameter">function parameter</a></dt>
|
|
<dd>
|
|
<p>An <a href="#element-param"><code>xsl:param</code></a> element
|
|
may appear as a child of an <a href=
|
|
"#element-function"><code>xsl:function</code></a> element, before
|
|
any non-<a href="#element-param"><code>xsl:param</code></a>
|
|
children of that element. Such a parameter is known as a
|
|
<b>function parameter</b>. A function parameter is a <a title=
|
|
"local variable" class="termref" href="#dt-local-variable">local
|
|
variable</a> with the additional property that its value can be set
|
|
when the function is called, using a function call in an XPath
|
|
<a title="expression" class="termref" href=
|
|
"#dt-expression">expression</a>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-global-variable">global variable</a></dt>
|
|
<dd>
|
|
<p>A top-level <a title="variable-binding element" class="termref"
|
|
href="#dt-variable-binding-element">variable-binding element</a>
|
|
declares a <b>global variable</b> that is visible everywhere
|
|
(except where it is <a title="shadows" class="termref" href=
|
|
"#dt-shadows">shadowed</a> by another binding).</p>
|
|
</dd>
|
|
<dt><a href="#dt-group">group</a></dt>
|
|
<dd>
|
|
<p>The <a href=
|
|
"#element-for-each-group"><code>xsl:for-each-group</code></a>
|
|
instruction allocates the items in an input sequence into
|
|
<b>groups</b> of items (that is, it establishes a collection of
|
|
sequences) based either on common values of a grouping key, or on a
|
|
<a title="pattern" class="termref" href="#dt-pattern">pattern</a>
|
|
that the initial or final <span>item</span> in a group must
|
|
match.</p>
|
|
</dd>
|
|
<dt><a href="#dt-grouping-key">grouping key</a></dt>
|
|
<dd>
|
|
<p>If either of the <code>group-by</code> or
|
|
<code>group-adjacent</code> attributes is present, then for each
|
|
item in the <a title="population" class="termref" href=
|
|
"#dt-population">population</a> a set of <b>grouping keys</b> is
|
|
calculated, as follows: the expression contained in the
|
|
<code>group-by</code> or <code>group-adjacent</code> attribute is
|
|
evaluated; the result is atomized; and any
|
|
<code>xs:untypedAtomic</code> values are cast to
|
|
<code>xs:string</code>. The grouping keys are the distinct atomic
|
|
values present in the result sequence.</p>
|
|
</dd>
|
|
<dt><a href=
|
|
"#dt-guaranteed-streamable">guaranteed-streamable</a></dt>
|
|
<dd>
|
|
<p>A <b>guaranteed-streamable</b> construct is a <a title=
|
|
"construct" class="termref" href="#dt-construct">construct</a> that
|
|
follows the rules given in <a href="#streamability"><i>18.4
|
|
Streamability Analysis</i></a>. Every <a title="processor" class=
|
|
"termref" href="#dt-processor">processor</a> that claims
|
|
conformance as a <a title="streaming feature" class="termref" href=
|
|
"#dt-streaming-feature">streaming processor</a> <span class=
|
|
"verb">must</span> be able to process such a construct using
|
|
streaming, that is, by processing the contents of the source
|
|
document on the fly as it is read, without the need to buffer the
|
|
entire document or any entire element in memory.</p>
|
|
</dd>
|
|
<dt><a href="#dt-implementation">implementation</a></dt>
|
|
<dd>
|
|
<p>A specific product that performs the functions of an <a title=
|
|
"processor" class="termref" href="#dt-processor">XSLT processor</a>
|
|
is referred to as an <b>implementation</b>.</p>
|
|
</dd>
|
|
<dt><a href=
|
|
"#dt-implementation-defined">implementation-defined</a></dt>
|
|
<dd>
|
|
<p>In this specification, the term <b>implementation-defined</b>
|
|
refers to a feature where the implementation is allowed some
|
|
flexibility, and where the choices made by the implementation
|
|
<span class="verb">must</span> be described in documentation that
|
|
accompanies any conformance claim.</p>
|
|
</dd>
|
|
<dt><a href=
|
|
"#dt-implementation-dependent">implementation-dependent</a></dt>
|
|
<dd>
|
|
<p>The term <b>implementation-dependent</b> refers to a feature
|
|
where the behavior <span class="verb">may</span> vary from one
|
|
implementation to another, and where the vendor is not expected to
|
|
provide a full specification of the behavior.</p>
|
|
</dd>
|
|
<dt><a href="#dt-import-precedence">import precedence</a></dt>
|
|
<dd>
|
|
<p>A <a title="declaration" class="termref" href=
|
|
"#dt-declaration">declaration</a> <var>D</var> in the stylesheet is
|
|
defined to have lower <b>import precedence</b> than another
|
|
declaration <var>E</var> if the stylesheet level containing
|
|
<var>D</var> would be visited before the stylesheet level
|
|
containing <var>E</var> 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.</p>
|
|
</dd>
|
|
<dt><a href="#dt-import-tree">import tree</a></dt>
|
|
<dd>
|
|
<p>The <a title="stylesheet level" class="termref" href=
|
|
"#dt-stylesheet-level">stylesheet levels</a> making up a <a title=
|
|
"stylesheet" class="termref" href="#dt-stylesheet">stylesheet</a>
|
|
are treated as forming an <b>import tree</b>. In the import tree,
|
|
each stylesheet level has one child for each <a href=
|
|
"#element-import"><code>xsl:import</code></a> declaration that it
|
|
contains.</p>
|
|
</dd>
|
|
<dt><a href="#dt-in-scope-schema-component">in-scope schema
|
|
component</a></dt>
|
|
<dd>
|
|
<p>The <a title="schema component" class="termref" href=
|
|
"#dt-schema-component">schema components</a> that may be referenced
|
|
by name in a <a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a> are referred to as the <b>in-scope
|
|
schema components</b>. This set is the same throughout all the
|
|
modules of a stylesheet.</p>
|
|
</dd>
|
|
<dt><a href="#dt-independent-instruction">independent
|
|
(instruction)</a></dt>
|
|
<dd>
|
|
<p>Two <a title="instruction" class="termref" href=
|
|
"#dt-instruction">instructions</a> with a <a title=
|
|
"sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> are defined to
|
|
be <b>independent</b> if neither <a title="dependent (instruction)"
|
|
class="termref" href="#dt-dependent-instruction">depends</a> on the
|
|
other.</p>
|
|
</dd>
|
|
<dt><a href="#dt-initial-context-item">initial context
|
|
item</a></dt>
|
|
<dd>
|
|
<p>An item that acts as the <b>initial context item</b> for the
|
|
transformation. This item is accessible within the <a title=
|
|
"stylesheet" class="termref" href="#dt-stylesheet">stylesheet</a>
|
|
as the initial value of the XPath <a title="expression" class=
|
|
"termref" href="#dt-expression">expressions</a> <code>.</code>
|
|
(dot) and <code>self::node()</code>, as described in <a href=
|
|
"#focus"><i>5.4.3.1 Maintaining Position: the Focus</i></a></p>
|
|
</dd>
|
|
<dt><a href="#dt-initial-item">initial item</a></dt>
|
|
<dd>
|
|
<p>For each <a title="group" class="termref" href=
|
|
"#dt-group">group</a>, the item within the group that is first in
|
|
<a title="population order" class="termref" href=
|
|
"#dt-population-order">population order</a> is known as the
|
|
<b>initial item</b> of the group.</p>
|
|
</dd>
|
|
<dt><a href="#dt-initial-mode">initial mode</a></dt>
|
|
<dd>
|
|
<p>The initial mode, if specified, <span class="verb">must</span>
|
|
either be the default mode, or a mode that is explicitly named in
|
|
the <code>mode</code> attribute of an <a href=
|
|
"#element-template"><code>xsl:template</code></a> declaration
|
|
within the stylesheet. If an initial mode is supplied, then in
|
|
searching for the <a title="template rule" class="termref" href=
|
|
"#dt-template-rule">template rule</a> that best matches the
|
|
<span><a title="initial context item" class="termref" href=
|
|
"#dt-initial-context-item">initial context item</a></span>, the
|
|
processor considers only those rules that apply to the initial
|
|
mode. If no initial mode is supplied, then the mode named in the
|
|
<code>default-mode</code> attribute of the <a href=
|
|
"#element-stylesheet"><code>xsl:stylesheet</code></a> element of
|
|
the <a title="principal stylesheet module" class="termref" href=
|
|
"#dt-principal-stylesheet-module">principal stylesheet module</a>
|
|
is used; or in the absence of such an attribute, the <a title=
|
|
"unnamed mode" class="termref" href="#dt-unnamed-mode">unnamed
|
|
mode</a>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-initial-sequence">initial sequence</a></dt>
|
|
<dd>
|
|
<p>The sequence to be sorted is referred to as the <b>initial
|
|
sequence</b>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-initial-template">initial template</a></dt>
|
|
<dd>
|
|
<p>The transformation is performed by evaluating an <b>initial
|
|
template</b>. If a <a title="named template" class="termref" href=
|
|
"#dt-named-template">named template</a> is supplied when the
|
|
transformation is initiated, then this is the initial template;
|
|
otherwise, the initial template is the <a title="template rule"
|
|
class="termref" href="#dt-template-rule">template rule</a> selected
|
|
according to the rules of the <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>
|
|
instruction for processing the <span><a title=
|
|
"initial context item" class="termref" href=
|
|
"#dt-initial-context-item">initial context item</a></span> in the
|
|
initial <a title="mode" class="termref" href=
|
|
"#dt-mode">mode</a>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-instruction">instruction</a></dt>
|
|
<dd>
|
|
<p>An <b>instruction</b> is either an <a title="XSLT instruction"
|
|
class="termref" href="#dt-xslt-instruction">XSLT instruction</a> or
|
|
an <a title="extension instruction" class="termref" href=
|
|
"#dt-extension-instruction">extension instruction</a>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-key">key</a></dt>
|
|
<dd>
|
|
<p>A <b>key</b> is defined as a set of <a href=
|
|
"#element-key"><code>xsl:key</code></a> declarations in the
|
|
<a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a> that share the same name.</p>
|
|
</dd>
|
|
<dt><a href="#dt-key-specifier">key specifier</a></dt>
|
|
<dd>
|
|
<p>The expression in the <code>use</code> attribute and the
|
|
<a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> within an
|
|
<a href="#element-key"><code>xsl:key</code></a> declaration are
|
|
referred to collectively as the <b>key specifier</b>. The key
|
|
specifier determines the values that may be used to find a node
|
|
using this <a title="key" class="termref" href=
|
|
"#dt-key">key</a>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-lexical-qname">lexical QName</a></dt>
|
|
<dd>
|
|
<p>A <b>lexical QName</b> is a string representing a <a title=
|
|
"QName" class="termref" href="#dt-qname">QName</a> in the form
|
|
<code>(NCName ":")? NCName</code>, that is, a local name optionally
|
|
preceded by a namespace prefix.</p>
|
|
</dd>
|
|
<dt><a href="#dt-literal-namespace-uri">literal namespace
|
|
URI</a></dt>
|
|
<dd>
|
|
<p>A namespace URI in the stylesheet tree that is being used to
|
|
specify a namespace URI in the <a title="result tree" class=
|
|
"termref" href="#dt-result-tree">result tree</a> is called a
|
|
<b>literal namespace URI</b>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-literal-result-element">literal result
|
|
element</a></dt>
|
|
<dd>
|
|
<p>In a <a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a>, an element in
|
|
the <a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a> that does not belong to the
|
|
<a title="XSLT namespace" class="termref" href=
|
|
"#dt-xslt-namespace">XSLT namespace</a> and that is not an
|
|
<a title="extension instruction" class="termref" href=
|
|
"#dt-extension-instruction">extension instruction</a> (see <a href=
|
|
"#extension-instruction"><i>21.2 Extension Instructions</i></a>) is
|
|
classified as a <b>literal result element</b>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-local-variable">local variable</a></dt>
|
|
<dd>
|
|
<p>As well as being allowed as a <a title="declaration" class=
|
|
"termref" href="#dt-declaration">declaration</a>, the <a href=
|
|
"#element-variable"><code>xsl:variable</code></a> element is also
|
|
allowed in <a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructors</a>. Such a
|
|
variable is known as a <b>local variable</b>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-merge-input-sequence">merge input
|
|
sequence</a></dt>
|
|
<dd>
|
|
<p>A <b>merge input sequence</b> is an arbitrary <a href=
|
|
"http://www.w3.org/TR/xpath-datamodel-11/#dt-sequence">sequence</a><sup><small>DM11</small></sup>
|
|
of items which is already sorted according to the <a title=
|
|
"merge key specification" class="termref" href=
|
|
"#dt-merge-key-specification">merge key specification</a> for the
|
|
corresponding <a title="merge source definition" class="termref"
|
|
href="#dt-merge-source-definition">merge source definition</a>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-merge-key-component">merge key component</a></dt>
|
|
<dd>
|
|
<p>A <b>merge key component</b> specifies one component of a
|
|
<a title="merge key specification" class="termref" href=
|
|
"#dt-merge-key-specification">merge key specification</a>; it
|
|
corresponds to a single <a href=
|
|
"#element-merge-key"><code>xsl:merge-key</code></a> element in the
|
|
stylesheet.</p>
|
|
</dd>
|
|
<dt><a href="#dt-merge-key-specification">merge key
|
|
specification</a></dt>
|
|
<dd>
|
|
<p>A <b>merge key specification</b> consists of one or more
|
|
adjacent <a href=
|
|
"#element-merge-key"><code>xsl:merge-key</code></a> elements which
|
|
together define how the <a title="merge input sequence" class=
|
|
"termref" href="#dt-merge-input-sequence">merge input sequences</a>
|
|
selected by a <a title="merge source definition" class="termref"
|
|
href="#dt-merge-source-definition">merge source definition</a> are
|
|
sorted. Each <a href=
|
|
"#element-merge-key"><code>xsl:merge-key</code></a> element defines
|
|
one <a title="merge key component" class="termref" href=
|
|
"#dt-merge-key-component">merge key component</a>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-merge-key-value">merge key value</a></dt>
|
|
<dd>
|
|
<p>For each item in a <a title="merge input sequence" class=
|
|
"termref" href="#dt-merge-input-sequence">merge input sequence</a>,
|
|
a value is computed for each <a title="merge key component" class=
|
|
"termref" href="#dt-merge-key-component">merge key component</a>
|
|
within the <a title="merge key specification" class="termref" href=
|
|
"#dt-merge-key-specification">merge key specification</a>. The
|
|
value computed for an item by using the <var>N</var>th <a title=
|
|
"merge key component" class="termref" href=
|
|
"#dt-merge-key-component">merge key component</a> is referred to as
|
|
the <var>N</var>th <b>merge key value</b> of that item.</p>
|
|
</dd>
|
|
<dt><a href="#dt-merge-source-definition">merge source
|
|
definition</a></dt>
|
|
<dd>
|
|
<p>A <b>merge source definition</b> is the definition of one kind
|
|
of input to the merge operation. It selects zero or more <a title=
|
|
"merge input sequence" class="termref" href=
|
|
"#dt-merge-input-sequence">merge input sequences</a>, and it
|
|
includes a <a title="merge key specification" class="termref" href=
|
|
"#dt-merge-key-specification">merge key specification</a> to define
|
|
how the <span><a title="merge key value" class="termref" href=
|
|
"#dt-merge-key-value">merge key values</a></span> are computed for
|
|
each such merge input sequence.</p>
|
|
</dd>
|
|
<dt><a href="#dt-mode">mode</a></dt>
|
|
<dd>
|
|
<p><b>Modes</b> allow a node in a <a title="source tree" class=
|
|
"termref" href="#dt-source-tree">source tree</a> to be processed
|
|
multiple times, each time producing a different result. They also
|
|
allow different sets of <a title="template rule" class="termref"
|
|
href="#dt-template-rule">template rules</a> to be active when
|
|
processing different trees, for example when processing documents
|
|
loaded using the <a href=
|
|
"#function-document"><code>document</code></a> function (see
|
|
<a href="#document"><i>19.1.1 The document function</i></a>) or
|
|
when processing <a title="temporary tree" class="termref" href=
|
|
"#dt-temporary-tree">temporary trees</a>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-mode-definition">mode definition</a></dt>
|
|
<dd>
|
|
<p>All the <a href="#element-mode"><code>xsl:mode</code></a>
|
|
declarations in a stylesheet that share the same name are grouped
|
|
into a named <b>mode definition</b>; those that have no name are
|
|
grouped into a single unnamed mode definition.</p>
|
|
</dd>
|
|
<dt><a href="#dt-motionless">motionless</a></dt>
|
|
<dd>
|
|
<p>A construct <var>C</var> is <b>motionless</b> with respect to
|
|
its context item if (a) it is <a title="guaranteed-streamable"
|
|
class="termref" href=
|
|
"#dt-guaranteed-streamable">guaranteed-streamable</a> with respect
|
|
to its context item (as defined above), and (b) in the set of paths
|
|
starting at <var>C</var> in the data flow graph, no path contains a
|
|
downward step (child, descendant, or descendant-or-self).</p>
|
|
</dd>
|
|
<dt><a href="#dt-mutually-exclusive">mutually exclusive</a></dt>
|
|
<dd>
|
|
<p>Two <a title="e-node" class="termref" href=
|
|
"#dt-e-node">e-nodes</a> in the expression tree are defined to be
|
|
<b>mutually exclusive</b> if they have a common ancestor
|
|
<code>if</code> e-node, and if one is a descendant of the
|
|
<code>then</code> child of that <code>if</code>, while the other is
|
|
a descendant of the <code>else</code> child. Two e-nodes are also
|
|
<b>mutually exclusive</b> if they are <a title=
|
|
"mutually independent" class="termref" href=
|
|
"#dt-mutually-independent">mutually independent</a> as defined in
|
|
<a href="#expr-parallel-branches"><i>18.4.4.2 Analyzing parallel
|
|
branches</i></a>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-mutually-independent">mutually
|
|
independent</a></dt>
|
|
<dd>
|
|
<p>Two e-nodes are <b>mutually independent</b> if they share an
|
|
e-node representing an <a href=
|
|
"#element-fork"><code>xsl:fork</code></a> instruction as a common
|
|
ancestor, and if they occur in separate subtrees rooted at
|
|
different children of the <a href=
|
|
"#element-fork"><code>xsl:fork</code></a> instruction, such that
|
|
neither subtree is dependent (directly or indirectly) on the value
|
|
of a variable bound by the other subtree.</p>
|
|
</dd>
|
|
<dt><a href="#dt-named-template">named template</a></dt>
|
|
<dd>
|
|
<p>Templates can be invoked by name. An <a href=
|
|
"#element-template"><code>xsl:template</code></a> element with a
|
|
<code>name</code> attribute defines a <b>named template</b>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-namespace-fixup">namespace fixup</a></dt>
|
|
<dd>
|
|
<p>The rules for the individual XSLT instructions that construct a
|
|
<a title="result tree" class="termref" href=
|
|
"#dt-result-tree">result tree</a> (see <a href=
|
|
"#creating-new-nodes"><i>11 Creating Nodes and Sequences</i></a>)
|
|
prescribe some of the situations in which namespace nodes are
|
|
written to the tree. These rules, however, are not sufficient to
|
|
ensure that the prescribed constraints are always satisfied. The
|
|
XSLT processor <span class="verb">must</span> therefore add
|
|
additional namespace nodes to satisfy these constraints. This
|
|
process is referred to as <b>namespace fixup</b>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-non-contextual-function-call">non-contextual
|
|
function call</a></dt>
|
|
<dd>
|
|
<p>The term <b>non-contextual function call</b> is used to refer to
|
|
function calls that do not pass the dynamic context to the called
|
|
function. This includes all calls on <a title="stylesheet function"
|
|
class="termref" href="#dt-stylesheet-function">stylesheet
|
|
functions</a> and all [TERMDEF dt-dynamic-func-invoke IN
|
|
XP21]dynamic function invocations, (that is calls to function items
|
|
as permitted by XPath 2.1). It does not include calls to all
|
|
<a title="core function" class="termref" href=
|
|
"#dt-core-function">core functions</a> in particular those that
|
|
explicitly depend on the context, such as the <a href=
|
|
"#function-current-group"><code>current-group</code></a> and
|
|
<a href="#function-regex-group"><code>regex-group</code></a>
|
|
functions. It is <a title="implementation-defined" class="termref"
|
|
href="#dt-implementation-defined">implementation-defined</a>
|
|
whether, and under what circumstances, calls to <a title=
|
|
"extension function" class="termref" href=
|
|
"#dt-extension-function">extension functions</a> are
|
|
non-contextual.</p>
|
|
</dd>
|
|
<dt><a href="#dt-nonrec-dynamic-error">non-recoverable dynamic
|
|
error</a></dt>
|
|
<dd>
|
|
<p>A <a title="dynamic error" class="termref" href=
|
|
"#dt-dynamic-error">dynamic error</a> that is not recoverable is
|
|
referred to as a <b>non-recoverable dynamic error</b>. When a
|
|
non-recoverable dynamic error occurs, the <a title="processor"
|
|
class="termref" href="#dt-processor">processor</a> <span class=
|
|
"verb">must</span> signal the error, and <span>(unless the error is
|
|
caught using <a href=
|
|
"#element-catch"><code>xsl:catch</code></a>)</span> the
|
|
transformation fails.</p>
|
|
</dd>
|
|
<dt><a href="#dt-optional-recovery-action">optional recovery
|
|
action</a></dt>
|
|
<dd>
|
|
<p>If an implementation chooses to recover from a <a title=
|
|
"recoverable error" class="termref" href=
|
|
"#dt-recoverable-error">recoverable dynamic error</a>, it
|
|
<span class="verb">must</span> take the <b>optional recovery
|
|
action</b> defined for that error condition in this
|
|
specification.</p>
|
|
</dd>
|
|
<dt><a href="#dt-first-appearance">order of first
|
|
appearance</a></dt>
|
|
<dd>
|
|
<p>There is a <span>total</span> ordering among <a title="group"
|
|
class="termref" href="#dt-group">groups</a> referred to as the
|
|
<b>order of first appearance</b>. A group <var>G</var> is defined
|
|
to precede a group <var>H</var> in order of first appearance if the
|
|
<a title="initial item" class="termref" href=
|
|
"#dt-initial-item">initial item</a> of <var>G</var> precedes the
|
|
initial item of <var>H</var> in population order. If two groups
|
|
<var>G</var> and <var>H</var> have the same initial item (because
|
|
the item is in both groups) then <var>G</var> precedes <var>H</var>
|
|
if the <a title="grouping key" class="termref" href=
|
|
"#dt-grouping-key">grouping key</a> of <var>G</var> precedes the
|
|
grouping key of <var>H</var> in the sequence that results from
|
|
evaluating the <code>group-by</code> expression of this initial
|
|
item.</p>
|
|
</dd>
|
|
<dt><a href="#dt-output-definition">output definition</a></dt>
|
|
<dd>
|
|
<p>All the <a href="#element-output"><code>xsl:output</code></a>
|
|
declarations in a stylesheet that share the same name are grouped
|
|
into a named <b>output definition</b>; those that have no name are
|
|
grouped into a single unnamed output definition.</p>
|
|
</dd>
|
|
<dt><a href="#dt-output-state">output state</a></dt>
|
|
<dd>
|
|
<p>Each instruction in the <a title="stylesheet" class="termref"
|
|
href="#dt-stylesheet">stylesheet</a> is evaluated in one of two
|
|
possible <b>output states</b>: <a title="final output state" class=
|
|
"termref" href="#dt-final-output-state">final output state</a> or
|
|
<a title="temporary output state" class="termref" href=
|
|
"#dt-temporary-output-state">temporary output state</a></p>
|
|
</dd>
|
|
<dt><a href="#dt-parameter">parameter</a></dt>
|
|
<dd>
|
|
<p>The <a href="#element-param"><code>xsl:param</code></a> element
|
|
declares a <b>parameter</b>, which may be a <a title=
|
|
"stylesheet parameter" class="termref" href=
|
|
"#dt-stylesheet-parameter">stylesheet parameter</a>, a <a title=
|
|
"template parameter" class="termref" href=
|
|
"#dt-template-parameter">template parameter</a>, a <a title=
|
|
"function parameter" class="termref" href=
|
|
"#dt-function-parameter">function parameter</a><span>, or an
|
|
<a href="#element-iterate"><code>xsl:iterate</code></a>
|
|
parameter</span>. A parameter is a <a title="variable" class=
|
|
"termref" href="#dt-variable">variable</a> with the additional
|
|
property that its value can be set by the caller.</p>
|
|
</dd>
|
|
<dt><a href="#dt-pattern">pattern</a></dt>
|
|
<dd>
|
|
<p>A <b>pattern</b> specifies a set of conditions on an
|
|
<span>item</span>. An <span>item</span> that satisfies the
|
|
conditions matches the pattern; an <span>item</span> that does not
|
|
satisfy the conditions does not match the pattern.</p>
|
|
</dd>
|
|
<dt><a href="#dt-picture-string">picture string</a></dt>
|
|
<dd>
|
|
<p>The <b>picture string</b> is the string supplied as the second
|
|
argument of the <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-format-number"><code>
|
|
format-number</code></a><sup><small>FO</small></sup> function.</p>
|
|
</dd>
|
|
<dt><a href="#dt-place-marker">place marker</a></dt>
|
|
<dd>
|
|
<p>The <a href="#element-number"><code>xsl:number</code></a>
|
|
instruction performs two tasks: firstly, determining a <b>place
|
|
marker</b> (this is a sequence of integers, to allow for hierarchic
|
|
numbering schemes such as <code>1.12.2</code> or
|
|
<code>3(c)ii</code>), and secondly, formatting the place marker for
|
|
output as a text node in the result sequence.</p>
|
|
</dd>
|
|
<dt><a href="#dt-population">population</a></dt>
|
|
<dd>
|
|
<p>The sequence of items to be grouped, which is referred to as the
|
|
<b>population</b>, is determined by evaluating the XPath <a title=
|
|
"expression" class="termref" href="#dt-expression">expression</a>
|
|
contained in the <code>select</code> attribute.</p>
|
|
</dd>
|
|
<dt><a href="#dt-population-order">population order</a></dt>
|
|
<dd>
|
|
<p>The population is treated as a sequence; the order of items in
|
|
this sequence is referred to as <b>population order</b></p>
|
|
</dd>
|
|
<dt><a href="#dt-principal-stylesheet-module">principal stylesheet
|
|
module</a></dt>
|
|
<dd>
|
|
<p>A <a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a> may consist of several <a title=
|
|
"stylesheet module" class="termref" href=
|
|
"#dt-stylesheet-module">stylesheet modules</a>, contained in
|
|
different XML documents. For a given transformation, one of these
|
|
functions as the <b>principal stylesheet module</b>. The complete
|
|
<a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a> is assembled by finding the
|
|
<a title="stylesheet module" class="termref" href=
|
|
"#dt-stylesheet-module">stylesheet modules</a> referenced directly
|
|
or indirectly from the principal stylesheet module using <a href=
|
|
"#element-include"><code>xsl:include</code></a> and <a href=
|
|
"#element-import"><code>xsl:import</code></a> elements: see
|
|
<a href="#include"><i>3.10.2 Stylesheet Inclusion</i></a> and
|
|
<a href="#import"><i>3.10.3 Stylesheet Import</i></a>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-priority">priority</a></dt>
|
|
<dd>
|
|
<p>The <b>priority</b> of a template rule is specified by the
|
|
<code>priority</code> attribute on the <a href=
|
|
"#element-template"><code>xsl:template</code></a> declaration. If
|
|
no priority is specified explicitly for a template rule, its
|
|
<a title="default priority" class="termref" href=
|
|
"#dt-default-priority">default priority</a> is used, as defined in
|
|
<a href="#default-priority"><i>6.5 Default Priority for Template
|
|
Rules</i></a>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-processing-order">processing order</a></dt>
|
|
<dd>
|
|
<p>There is another <span>total</span> ordering among groups
|
|
referred to as <b>processing order</b>. If group <var>R</var>
|
|
precedes group <var>S</var> in processing order, then in the result
|
|
sequence returned by the <a href=
|
|
"#element-for-each-group"><code>xsl:for-each-group</code></a>
|
|
instruction the items generated by processing group <var>R</var>
|
|
will precede the items generated by processing group
|
|
<var>S</var>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-processor">processor</a></dt>
|
|
<dd>
|
|
<p>The software responsible for transforming source trees into
|
|
result trees using an XSLT stylesheet is referred to as the
|
|
<b>processor</b>. This is sometimes expanded to <em>XSLT
|
|
processor</em> to avoid any confusion with other processors, for
|
|
example an XML processor.</p>
|
|
</dd>
|
|
<dt><a href="#dt-qname">QName</a></dt>
|
|
<dd>
|
|
<p>A <b>QName</b> is always written in the form <code>(NCName ":")?
|
|
NCName</code>, that is, a local name optionally preceded by a
|
|
namespace prefix. When two QNames are compared, however, they are
|
|
considered equal if the corresponding <a title="expanded-QName"
|
|
class="termref" href="#dt-expanded-qname">expanded-QNames</a> are
|
|
the same, as described below.</p>
|
|
</dd>
|
|
<dt><a href="#dt-recoverable-error">recoverable error</a></dt>
|
|
<dd>
|
|
<p>Some dynamic errors are classed as <b>recoverable errors</b>.
|
|
When a recoverable error occurs, this specification allows the
|
|
processor either to signal the error (by reporting the error
|
|
condition and terminating execution) or to take a defined recovery
|
|
action and continue processing.</p>
|
|
</dd>
|
|
<dt><a href="#dt-reordering-construct">reordering
|
|
construct</a></dt>
|
|
<dd>
|
|
<p>Sorting is just one example of an operation on a sequence whose
|
|
output is not streamable with respect to its input. In general we
|
|
refer to any <a title="construct" class="termref" href=
|
|
"#dt-construct">construct</a> that requires to hold its entire
|
|
input sequence in memory in order to compute its result as a
|
|
<b>reordering construct</b>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-repeating-arc">repeating arc</a></dt>
|
|
<dd>
|
|
<p>An arc in the data flow graph is a <b>repeating arc</b> if it
|
|
ends at an <a title="e-node" class="termref" href=
|
|
"#dt-e-node">e-node</a> that is <span>within the subtree rooted
|
|
at</span> the e-node representing a <em>controlled expression</em>,
|
|
and starts at an e-node that is outside the tree rooted at the
|
|
corresponding <em>looping construct</em>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-required-type">required type</a></dt>
|
|
<dd>
|
|
<p>The context within a <a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a> where an XPath <a title=
|
|
"expression" class="termref" href="#dt-expression">expression</a>
|
|
appears may specify the <b>required type</b> of the expression. The
|
|
required type indicates the type of the value that the expression
|
|
is expected to return.</p>
|
|
</dd>
|
|
<dt><a href="#dt-reserved-namespace">reserved namespace</a></dt>
|
|
<dd>
|
|
<p>The XSLT namespace, together with certain other namespaces
|
|
recognized by an XSLT processor, are classified as <b>reserved
|
|
namespaces</b> and <span class="verb">must</span> be used only as
|
|
specified in this and related specifications.</p>
|
|
</dd>
|
|
<dt><a href="#dt-result-tree">result tree</a></dt>
|
|
<dd>
|
|
<p>The term <b>result tree</b> is used to refer to any tree
|
|
constructed by <a title="instruction" class="termref" href=
|
|
"#dt-instruction">instructions</a> in the stylesheet. A result tree
|
|
is either a <a title="final result tree" class="termref" href=
|
|
"#dt-final-result-tree">final result tree</a> or a <a title=
|
|
"temporary tree" class="termref" href=
|
|
"#dt-temporary-tree">temporary tree</a>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-schema-component">schema component</a></dt>
|
|
<dd>
|
|
<p>Type definitions and element and attribute declarations are
|
|
referred to collectively as <b>schema components</b>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-schema-instance-namespace">schema instance
|
|
namespace</a></dt>
|
|
<dd>
|
|
<p>The <b>schema instance namespace</b>
|
|
<code>http://www.w3.org/2001/XMLSchema-instance</code> is used as
|
|
defined in <a href="#xmlschema-1">[XML Schema Part 1]</a></p>
|
|
</dd>
|
|
<dt><a href="#dt-schema-namespace">schema namespace</a></dt>
|
|
<dd>
|
|
<p>The <b>schema namespace</b>
|
|
<code>http://www.w3.org/2001/XMLSchema</code> is used as defined in
|
|
<a href="#xmlschema-1">[XML Schema Part 1]</a></p>
|
|
</dd>
|
|
<dt><a href="#dt-schema-aware-xslt-processor">schema-aware XSLT
|
|
processor</a></dt>
|
|
<dd>
|
|
<p>A <b>schema-aware XSLT processor</b> is an XSLT processor that
|
|
implements all the mandatory requirements of this specification,
|
|
including those features that a <a title="basic XSLT processor"
|
|
class="termref" href="#dt-basic-xslt-processor">basic XSLT
|
|
processor</a> signals as an error. The mandatory requirements of
|
|
this specification are taken to include the mandatory requirements
|
|
of <span>XPath 2.1</span>, as described in <a href=
|
|
"#xpath-21">[XPath 2.1]</a>. A requirement is mandatory unless the
|
|
specification includes wording (such as the use of the words
|
|
<span class="verb">should</span> or <span class="verb">may</span>)
|
|
that clearly indicates that it is optional.</p>
|
|
</dd>
|
|
<dt><a href="#dt-sequence-constructor">sequence
|
|
constructor</a></dt>
|
|
<dd>
|
|
<p>A <b>sequence constructor</b> is a sequence of zero or more
|
|
sibling nodes in the <a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a> that can be evaluated to return a
|
|
sequence of nodes, atomic values, <span>and function items</span>.
|
|
The way that the resulting sequence is used depends on the
|
|
containing instruction.</p>
|
|
</dd>
|
|
<dt><a href="#dt-serialization">serialization</a></dt>
|
|
<dd>
|
|
<p>A frequent requirement is to output a <a title=
|
|
"final result tree" class="termref" href=
|
|
"#dt-final-result-tree">final result tree</a> as an XML document
|
|
(or in other formats such as HTML). This process is referred to as
|
|
<b>serialization</b>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-serialization-error">serialization error</a></dt>
|
|
<dd>
|
|
<p>If a transformation has successfully produced a <a title=
|
|
"final result tree" class="termref" href=
|
|
"#dt-final-result-tree">final result tree</a>, 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
|
|
<b>serialization error</b>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-serialization-feature">serialization
|
|
feature</a></dt>
|
|
<dd>
|
|
<p>A processor that claims conformance with the <b>serialization
|
|
feature</b> <span class="verb">must</span> support the conversion
|
|
of a <a title="final result tree" class="termref" href=
|
|
"#dt-final-result-tree">final result tree</a> to a sequence of
|
|
octets following the rules defined in <a href=
|
|
"#serialization"><i>23 Serialization</i></a>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-shadows">shadows</a></dt>
|
|
<dd>
|
|
<p>A binding <b>shadows</b> another binding if the binding occurs
|
|
at a point where the other binding is visible, and the bindings
|
|
have the same name.</p>
|
|
</dd>
|
|
<dt><a href="#dt-simplified-stylesheet-module">simplified
|
|
stylesheet module</a></dt>
|
|
<dd>
|
|
<p>A <b>simplified stylesheet module</b> is a tree, or part of a
|
|
tree, consisting of a <a title="literal result element" class=
|
|
"termref" href="#dt-literal-result-element">literal result
|
|
element</a> together with its descendant nodes and associated
|
|
attributes and namespaces. This element is not itself in the XSLT
|
|
namespace, but it <span class="verb">must</span> have an
|
|
<code>xsl:version</code> attribute, which implies that it
|
|
<span class="verb">must</span> have a namespace node that declares
|
|
a binding for the XSLT namespace. For further details see <a href=
|
|
"#simplified-stylesheet"><i>3.7 Simplified Stylesheet
|
|
Modules</i></a>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-singleton-focus">singleton focus</a></dt>
|
|
<dd>
|
|
<p>A <b>singleton focus</b> based on an item <var>J</var> has the
|
|
<span><a title="context item" class="termref" href=
|
|
"#dt-context-item">context item</a> (and therefore the <a title=
|
|
"context node" class="termref" href="#dt-context-node">context
|
|
node</a>, if <var>J</var> is a node)</span> set to <var>J</var>,
|
|
and the <a title="context position" class="termref" href=
|
|
"#dt-context-position">context position</a> and <a title=
|
|
"context size" class="termref" href="#dt-context-size">context
|
|
size</a> both set to 1 (one).</p>
|
|
</dd>
|
|
<dt><a href="#dt-snapshot">snapshot</a></dt>
|
|
<dd>
|
|
<p>A <b>snapshot</b> of a node <var>N</var> is a deep copy of
|
|
<var>N</var>, as produced by the <a href=
|
|
"#element-copy-of"><code>xsl:copy-of</code></a> instruction with
|
|
<code>copy-namespaces</code> set to <code>yes</code> and
|
|
<code>validation</code> set to <code>preserve</code>, with the
|
|
additional property that for every ancestor of <var>N</var>, the
|
|
copy also has a corresponding ancestor whose name, node-kind, and
|
|
base URI are the same as the corresponding ancestor of
|
|
<var>N</var>, and that has copies of the attributes and namespaces
|
|
of the corresponding ancestor of <var>N</var>. But the ancestor has
|
|
a type annotation of <code>xs:anyType</code>, has the properties
|
|
<code>nilled</code>, <code>is-ID</code>, and <code>is-IDREF</code>
|
|
set to false, and has no children other than the child that is a
|
|
copy of <var>N</var> or one of its ancestors.</p>
|
|
</dd>
|
|
<dt><a href="#dt-sort-key-component">sort key component</a></dt>
|
|
<dd>
|
|
<p>Within a <a title="sort key specification" class="termref" href=
|
|
"#dt-sort-key-specification">sort key specification</a>, each
|
|
<a href="#element-sort"><code>xsl:sort</code></a> element defines
|
|
one <b>sort key component</b>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-sort-key-specification">sort key
|
|
specification</a></dt>
|
|
<dd>
|
|
<p>A <b>sort key specification</b> is a sequence of one or more
|
|
adjacent <a href="#element-sort"><code>xsl:sort</code></a> elements
|
|
which together define rules for sorting the items in an input
|
|
sequence to form a sorted sequence.</p>
|
|
</dd>
|
|
<dt><a href="#dt-sort-key-value">sort key value</a></dt>
|
|
<dd>
|
|
<p>For each item in the <a title="initial sequence" class="termref"
|
|
href="#dt-initial-sequence">initial sequence</a>, a value is
|
|
computed for each <a title="sort key component" class="termref"
|
|
href="#dt-sort-key-component">sort key component</a> within the
|
|
<a title="sort key specification" class="termref" href=
|
|
"#dt-sort-key-specification">sort key specification</a>. The value
|
|
computed for an item by using the <var>N</var>th sort key component
|
|
is referred to as the <var>N</var>th <b>sort key value</b> of that
|
|
item.</p>
|
|
</dd>
|
|
<dt><a href="#dt-sorted-sequence">sorted sequence</a></dt>
|
|
<dd>
|
|
<p>The sequence after sorting as defined by the <a href=
|
|
"#element-sort"><code>xsl:sort</code></a> elements is referred to
|
|
as the <b>sorted sequence</b>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-source-tree">source tree</a></dt>
|
|
<dd>
|
|
<p>The term <b>source tree</b> means any tree provided as input to
|
|
the transformation. This includes the document containing the
|
|
<span><a title="initial context item" class="termref" href=
|
|
"#dt-initial-context-item">initial context item</a></span> if any,
|
|
documents containing nodes supplied as the values of <a title=
|
|
"stylesheet parameter" class="termref" href=
|
|
"#dt-stylesheet-parameter">stylesheet parameters</a>, documents
|
|
obtained from the results of functions such as <a href=
|
|
"#function-document"><code>document</code></a>, <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-doc"><code>doc</code></a><sup><small>FO</small></sup>,
|
|
and <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-collection"><code>collection</code></a><sup><small>FO</small></sup>,
|
|
<span>documents read using the <a href=
|
|
"#element-stream"><code>xsl:stream</code></a> instruction,</span>
|
|
and documents returned by extension functions or extension
|
|
instructions. In the context of a particular XSLT instruction, the
|
|
term <b>source tree</b> means any tree provided as input to that
|
|
instruction; this may be a source tree of the transformation as a
|
|
whole, or it may be a <a title="temporary tree" class="termref"
|
|
href="#dt-temporary-tree">temporary tree</a> produced during the
|
|
course of the transformation.</p>
|
|
</dd>
|
|
<dt><a href="#dt-stable">stable</a></dt>
|
|
<dd>
|
|
<p>A <a title="sort key specification" class="termref" href=
|
|
"#dt-sort-key-specification">sort key specification</a> is said to
|
|
be <b>stable</b> if its first <a href=
|
|
"#element-sort"><code>xsl:sort</code></a> element has no
|
|
<code>stable</code> attribute, or has a <code>stable</code>
|
|
attribute whose <a title="effective value" class="termref" href=
|
|
"#dt-effective-value">effective value</a> is <code>yes</code>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-standalone-stylesheet-module">standalone
|
|
stylesheet module</a></dt>
|
|
<dd>
|
|
<p>A <b>standalone stylesheet module</b> is a stylesheet module
|
|
that comprises the whole of an XML document.</p>
|
|
</dd>
|
|
<dt><a href="#dt-standard-attributes">standard attributes</a></dt>
|
|
<dd>
|
|
<p>There are a number of <b>standard attributes</b> that may appear
|
|
on any <a title="XSLT element" class="termref" href=
|
|
"#dt-xslt-element">XSLT element</a>: specifically
|
|
<code>version</code>, <code>exclude-result-prefixes</code>,
|
|
<code>extension-element-prefixes</code>,
|
|
<code>xpath-default-namespace</code>,
|
|
<code>default-collation</code>, and <code>use-when</code>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-standard-error-namespace">standard error
|
|
namespace</a></dt>
|
|
<dd>
|
|
<p>The <b>standard error namespace</b>
|
|
<code>http://www.w3.org/2005/xqt-errors</code> is used for error
|
|
codes defined in this specification and related specifications. It
|
|
is also used for the names of certain predefined variables
|
|
accessible within the scope of an <a href=
|
|
"#element-catch"><code>xsl:catch</code></a> element.</p>
|
|
</dd>
|
|
<dt><a href="#dt-standard-function-namespace">standard function
|
|
namespace</a></dt>
|
|
<dd>
|
|
<p>The <b>standard function namespace</b>
|
|
<code>http://www.w3.org/2005/xpath-functions</code> is used for
|
|
functions in the function library defined in <a href=
|
|
"#xpath-functions-11">[Functions and Operators]</a> and for
|
|
standard functions defined in this specification.</p>
|
|
</dd>
|
|
<dt><a href="#dt-standard-stylesheet-module">standard stylesheet
|
|
module</a></dt>
|
|
<dd>
|
|
<p>A <b>standard stylesheet module</b> is a tree, or part of a
|
|
tree, consisting of an <a href=
|
|
"#element-stylesheet"><code>xsl:stylesheet</code></a> or <a href=
|
|
"#element-transform"><code>xsl:transform</code></a> element (see
|
|
<a href="#stylesheet-element"><i>3.6 Stylesheet Element</i></a>)
|
|
together with its descendant nodes and associated attributes and
|
|
namespaces.</p>
|
|
</dd>
|
|
<dt><a href="#dt-static-error">static error</a></dt>
|
|
<dd>
|
|
<p>An error that can be detected by examining a <a title=
|
|
"stylesheet" class="termref" href="#dt-stylesheet">stylesheet</a>
|
|
before execution starts (that is, before the source document and
|
|
values of stylesheet parameters are available) is referred to as a
|
|
<b>static error</b>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-streamable-mode">streamable mode</a></dt>
|
|
<dd>
|
|
<p>A <b>streamable mode</b> is a <a title="mode" class="termref"
|
|
href="#dt-mode">mode</a> that is declared in an <a href=
|
|
"#element-mode"><code>xsl:mode</code></a> declaration with the
|
|
attribute <code>streamable="yes"</code>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-streamable-pattern">streamable pattern</a></dt>
|
|
<dd>
|
|
<p>A <a title="pattern" class="termref" href=
|
|
"#dt-pattern">pattern</a> is a <b>streamable pattern</b> if it can
|
|
be tested against a node in a <a title="streamed document" class=
|
|
"termref" href="#dt-streamed-document">streamed document</a>
|
|
without access to the descendants of the node.</p>
|
|
</dd>
|
|
<dt><a href="#dt-streamable-template">streamable template</a></dt>
|
|
<dd>
|
|
<p>If any of the <a title="mode" class="termref" href=
|
|
"#dt-mode">modes</a> to which a <a title="template rule" class=
|
|
"termref" href="#dt-template-rule">template rule</a> is applicable
|
|
is a <a title="streamable mode" class="termref" href=
|
|
"#dt-streamable-mode">streamable mode</a>, then the template rule
|
|
<span class="verb">must</span> satisfy certain rules to ensure that
|
|
it can be evaluated using streaming. A template that satisfies
|
|
these rules is referred to as a <b>streamable template</b>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-streamed-document">streamed document</a></dt>
|
|
<dd>
|
|
<p>A <b>streamed document</b> is a <a title="source tree" class=
|
|
"termref" href="#dt-source-tree">source tree</a> that is processed
|
|
using streaming, that is, without constructing a complete tree of
|
|
nodes in memory.</p>
|
|
</dd>
|
|
<dt><a href="#dt-streamed-document-node">streamed node</a></dt>
|
|
<dd>
|
|
<p>A <b>streamed node</b> is a node in a <a title=
|
|
"streamed document" class="termref" href=
|
|
"#dt-streamed-document">streamed document</a>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-streaming">streaming</a></dt>
|
|
<dd>
|
|
<p>The term <b>streaming</b> refers to a manner of processing in
|
|
which documents (such as source and result documents) are not
|
|
represented by a complete tree of nodes occupying memory
|
|
proportional to document size, but instead are processed "on the
|
|
fly" as a sequence of events, similar in concept to the stream of
|
|
events notified by an XML parser to represent markup in lexical
|
|
XML.</p>
|
|
</dd>
|
|
<dt><a href="#dt-streaming-feature">streaming feature</a></dt>
|
|
<dd>
|
|
<p>A processor that claims conformance with the <b>streaming
|
|
feature</b> <span class="verb">must</span> ....</p>
|
|
</dd>
|
|
<dt><a href="#dt-string-value">string value</a></dt>
|
|
<dd>
|
|
<p>The term <b>string value</b> is defined in <a href=
|
|
"http://www.w3.org/TR/xpath-datamodel-11/#dm-string-value">Section
|
|
5.13 string-value Accessor</a><sup><small>DM11</small></sup>. Every
|
|
node has a <a title="string value" class="termref" href=
|
|
"#dt-string-value">string value</a>. For example, the <a title=
|
|
"string value" class="termref" href="#dt-string-value">string
|
|
value</a> of an element is the concatenation of the <a title=
|
|
"string value" class="termref" href="#dt-string-value">string
|
|
values</a> of all its descendant text nodes.</p>
|
|
</dd>
|
|
<dt><a href="#dt-stylesheet">stylesheet</a></dt>
|
|
<dd>
|
|
<p>A transformation in the XSLT language is expressed in the form
|
|
of a <b>stylesheet</b>, whose syntax is well-formed XML <a href=
|
|
"#REC-xml">[XML 1.0]</a> conforming to the Namespaces in XML
|
|
Recommendation <a href="#xml-names">[Namespaces in XML]</a>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-stylesheet-function">stylesheet function</a></dt>
|
|
<dd>
|
|
<p>An <a href="#element-function"><code>xsl:function</code></a>
|
|
declaration declares the name, parameters, and implementation of a
|
|
<b>stylesheet function</b> that can be called from any XPath
|
|
<a title="expression" class="termref" href=
|
|
"#dt-expression">expression</a> within the <a title="stylesheet"
|
|
class="termref" href="#dt-stylesheet">stylesheet</a>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-stylesheet-level">stylesheet level</a></dt>
|
|
<dd>
|
|
<p>A <b>stylesheet level</b> is a collection of <a title=
|
|
"stylesheet module" class="termref" href=
|
|
"#dt-stylesheet-module">stylesheet modules</a> connected using
|
|
<a href="#element-include"><code>xsl:include</code></a>
|
|
declarations: specifically, two stylesheet modules <var>A</var> and
|
|
<var>B</var> are part of the same stylesheet level if one of them
|
|
includes the other by means of an <a href=
|
|
"#element-include"><code>xsl:include</code></a> declaration, or if
|
|
there is a third stylesheet module <var>C</var> that is in the same
|
|
stylesheet level as both <var>A</var> and <var>B</var>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-stylesheet-module">stylesheet module</a></dt>
|
|
<dd>
|
|
<p>A <a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a> consists of one or more
|
|
<b>stylesheet modules</b>, each one forming all or part of an XML
|
|
document.</p>
|
|
</dd>
|
|
<dt><a href="#dt-stylesheet-parameter">stylesheet
|
|
parameter</a></dt>
|
|
<dd>
|
|
<p>A top-level <a href="#element-param"><code>xsl:param</code></a>
|
|
element declares a <b>stylesheet parameter</b>. A stylesheet
|
|
parameter is a global variable with the additional property that
|
|
its value can be supplied by the caller when a transformation is
|
|
initiated.</p>
|
|
</dd>
|
|
<dt><a href="#dt-supplied-value">supplied value</a></dt>
|
|
<dd>
|
|
<p>The value of the variable is computed using the <a title=
|
|
"expression" class="termref" href="#dt-expression">expression</a>
|
|
given in the <code>select</code> attribute or the contained
|
|
<a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a>, as described
|
|
in <a href="#variable-values"><i>9.3 Values of Variables and
|
|
Parameters</i></a>. This value is referred to as the <b>supplied
|
|
value</b> of the variable.</p>
|
|
</dd>
|
|
<dt><a href="#dt-tail-position">tail position</a></dt>
|
|
<dd>
|
|
<p>An <a title="instruction" class="termref" href=
|
|
"#dt-instruction">instruction</a> <var>J</var> is in a <b>tail
|
|
position</b> within a <a title="sequence constructor" class=
|
|
"termref" href="#dt-sequence-constructor">sequence constructor</a>
|
|
<var>SC</var> if it satisfies one of the following conditions:</p>
|
|
</dd>
|
|
<dt><a href="#dt-target-expression">target expression</a></dt>
|
|
<dd>
|
|
<p>The string that results from evaluating the expression in the
|
|
<code>xpath</code> attribute is referred to as the <b>target
|
|
expression</b>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-target-namespace-uri">target namespace
|
|
URI</a></dt>
|
|
<dd>
|
|
<p>The namespace URI that is to be used in the <a title=
|
|
"result tree" class="termref" href="#dt-result-tree">result
|
|
tree</a> as a substitute for a <a title="literal namespace URI"
|
|
class="termref" href="#dt-literal-namespace-uri">literal namespace
|
|
URI</a> is called the <b>target namespace URI</b>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-template">template</a></dt>
|
|
<dd>
|
|
<p>An <a href="#element-template"><code>xsl:template</code></a>
|
|
declaration defines a <b>template</b>, which contains a <a title=
|
|
"sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> for creating
|
|
nodes, atomic values, <span>and/or function items</span>. A
|
|
template can serve either as a <a title="template rule" class=
|
|
"termref" href="#dt-template-rule">template rule</a>, invoked by
|
|
matching <span>items</span> against a <a title="pattern" class=
|
|
"termref" href="#dt-pattern">pattern</a>, or as a <a title=
|
|
"named template" class="termref" href="#dt-named-template">named
|
|
template</a>, invoked explicitly by name. It is also possible for
|
|
the same template to serve in both capacities.</p>
|
|
</dd>
|
|
<dt><a href="#dt-template-parameter">template parameter</a></dt>
|
|
<dd>
|
|
<p>An <a href="#element-param"><code>xsl:param</code></a> element
|
|
may appear as a child of an <a href=
|
|
"#element-template"><code>xsl:template</code></a> element, before
|
|
any non-<a href="#element-param"><code>xsl:param</code></a>
|
|
children of that element. Such a parameter is known as a
|
|
<b>template parameter</b>. A template parameter is a <a title=
|
|
"local variable" class="termref" href="#dt-local-variable">local
|
|
variable</a> with the additional property that its value can be set
|
|
when the template is called, using any of the instructions <a href=
|
|
"#element-call-template"><code>xsl:call-template</code></a>,
|
|
<a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>,
|
|
<a href=
|
|
"#element-apply-imports"><code>xsl:apply-imports</code></a>, or
|
|
<a href="#element-next-match"><code>xsl:next-match</code></a>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-template-rule">template rule</a></dt>
|
|
<dd>
|
|
<p>A stylesheet contains a set of <b>template rules</b> (see
|
|
<a href="#rules"><i>6 Template Rules</i></a>). A template rule has
|
|
three parts: a <a title="pattern" class="termref" href=
|
|
"#dt-pattern">pattern</a> that is matched against nodes, a
|
|
(possibly empty) set of <a title="template parameter" class=
|
|
"termref" href="#dt-template-parameter">template parameters</a>,
|
|
and a <a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> that is
|
|
evaluated to produce a sequence of items.</p>
|
|
</dd>
|
|
<dt><a href="#dt-temporary-output-state">temporary output
|
|
state</a></dt>
|
|
<dd>
|
|
<p>The second of the two <a title="output state" class="termref"
|
|
href="#dt-output-state">output states</a> is called <b>temporary
|
|
output</b> state. This state applies when instructions are writing
|
|
to a <a title="temporary tree" class="termref" href=
|
|
"#dt-temporary-tree">temporary tree</a> or any other non-final
|
|
destination.</p>
|
|
</dd>
|
|
<dt><a href="#dt-temporary-tree">temporary tree</a></dt>
|
|
<dd>
|
|
<p>The term <b>temporary tree</b> means any tree that is neither a
|
|
<a title="source tree" class="termref" href=
|
|
"#dt-source-tree">source tree</a> nor a <a title=
|
|
"final result tree" class="termref" href=
|
|
"#dt-final-result-tree">final result tree</a>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-top-level">top-level</a></dt>
|
|
<dd>
|
|
<p>An element occurring as a child of an <a href=
|
|
"#element-stylesheet"><code>xsl:stylesheet</code></a> element is
|
|
called a <b>top-level</b> element.</p>
|
|
</dd>
|
|
<dt><a href="#dt-tunnel-parameter">tunnel parameter</a></dt>
|
|
<dd>
|
|
<p>A parameter passed to a template may be defined as a <b>tunnel
|
|
parameter</b>. Tunnel parameters have the property that they are
|
|
automatically passed on by the called template to any further
|
|
templates that it calls, and so on recursively.</p>
|
|
</dd>
|
|
<dt><a href="#dt-annotation">type annotation</a></dt>
|
|
<dd>
|
|
<p>The term <b>type annotation</b> is used in this specification to
|
|
refer to the value returned by the <code>dm:type-name</code>
|
|
accessor of a node: see <a href=
|
|
"http://www.w3.org/TR/xpath-datamodel-11/#dm-type-name">Section
|
|
5.14 type-name Accessor</a><sup><small>DM11</small></sup>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-type-error">type errors</a></dt>
|
|
<dd>
|
|
<p>Certain errors are classified as <b>type errors</b>. 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.</p>
|
|
</dd>
|
|
<dt><a href="#dt-typed-value">typed value</a></dt>
|
|
<dd>
|
|
<p>The term <b>typed value</b> is defined in <a href=
|
|
"http://www.w3.org/TR/xpath-datamodel-11/#dm-typed-value">Section
|
|
5.15 typed-value Accessor</a><sup><small>DM11</small></sup>. Every
|
|
node except an element defined in the schema with element-only
|
|
content has a <a title="string value" class="termref" href=
|
|
"#dt-string-value">typed value</a>. For example, the <a title=
|
|
"typed value" class="termref" href="#dt-typed-value">typed
|
|
value</a> of an attribute of type <code>xs:IDREFS</code> is a
|
|
sequence of zero or more <code>xs:IDREF</code> values.</p>
|
|
</dd>
|
|
<dt><a href="#dt-unnamed-mode">unnamed mode</a></dt>
|
|
<dd>
|
|
<p>There is always an <b>unnamed mode</b> available. The unnamed
|
|
mode is the default mode used when no <code>mode</code> attribute
|
|
is specified on an <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>
|
|
instruction or <a href=
|
|
"#element-template"><code>xsl:template</code></a> declaration,
|
|
unless a different default mode has been specified using the
|
|
<code>default-mode</code> attribute of the containing <a href=
|
|
"#element-stylesheet"><code>xsl:stylesheet</code></a> element.</p>
|
|
</dd>
|
|
<dt><a href="#dt-uri-reference">URI Reference</a></dt>
|
|
<dd>
|
|
<p>Within this specification, the term <b>URI Reference</b>, unless
|
|
otherwise stated, refers to a string in the lexical space of the
|
|
<code>xs:anyURI</code> data type as defined in <a href=
|
|
"#xmlschema-2">[XML Schema Part 2]</a>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-data-element">user-defined data element</a></dt>
|
|
<dd>
|
|
<p>In addition to <a title="declaration" class="termref" href=
|
|
"#dt-declaration">declarations</a>, the <a href=
|
|
"#element-stylesheet"><code>xsl:stylesheet</code></a> element may
|
|
contain among its children any element not from the <a title=
|
|
"XSLT namespace" class="termref" href="#dt-xslt-namespace">XSLT
|
|
namespace</a>, provided that the <a title="expanded-QName" class=
|
|
"termref" href="#dt-expanded-qname">expanded-QName</a> of the
|
|
element has a non-null namespace URI. Such elements are referred to
|
|
as <b>user-defined data elements</b>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-value">value</a></dt>
|
|
<dd>
|
|
<p>A variable is a binding between a name and a value. The
|
|
<b>value</b> of a variable is any sequence (of nodes, atomic
|
|
values, <span>and/or function items</span>), as defined in <a href=
|
|
"#xpath-datamodel-11">[Data Model]</a>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-variable">variable</a></dt>
|
|
<dd>
|
|
<p>The <a href="#element-variable"><code>xsl:variable</code></a>
|
|
element declares a <b>variable</b>, which may be a <a title=
|
|
"global variable" class="termref" href="#dt-global-variable">global
|
|
variable</a> or a <a title="local variable" class="termref" href=
|
|
"#dt-local-variable">local variable</a>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-variable-binding-element">variable-binding
|
|
element</a></dt>
|
|
<dd>
|
|
<p>The two elements <a href=
|
|
"#element-variable"><code>xsl:variable</code></a> and <a href=
|
|
"#element-param"><code>xsl:param</code></a> are referred to as
|
|
<b>variable-binding elements</b></p>
|
|
</dd>
|
|
<dt><a href="#dt-whitespace-text-node">whitespace text
|
|
node</a></dt>
|
|
<dd>
|
|
<p>A <b>whitespace text node</b> is a text node whose content
|
|
consists entirely of whitespace characters (that is, #x09, #x0A,
|
|
#x0D, or #x20).</p>
|
|
</dd>
|
|
<dt><a href="#xml-namespace">XML namespace</a></dt>
|
|
<dd>
|
|
<p>The <b>XML namespace</b>, defined in <a href=
|
|
"#xml-names">[Namespaces in XML]</a> as
|
|
<code>http://www.w3.org/XML/1998/namespace</code>, is used for
|
|
attributes such as <code>xml:lang</code>, <code>xml:space</code>,
|
|
and <code>xml:id</code>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-xpath-compat-mode">XPath 1.0 compatibility
|
|
mode</a></dt>
|
|
<dd>
|
|
<p>The term <b>XPath 1.0 compatibility mode</b> is defined in
|
|
<a href="http://www.w3.org/TR/xpath-21/#static_context">Section
|
|
2.1.1 Static Context</a><sup><small>XP21</small></sup>. This is a
|
|
setting in the static context of an XPath expression; it has two
|
|
values, <code>true</code> and <code>false</code>. When the value is
|
|
set to true, the semantics of function calls and certain other
|
|
operations are adjusted to give a greater degree of backwards
|
|
compatibility between <span>XPath 2.1</span> and XPath 1.0.</p>
|
|
</dd>
|
|
<dt><a href="#dt-xslt-10-behavior">XSLT 1.0 behavior</a></dt>
|
|
<dd>
|
|
<p>An element in the stylesheet is processed with <b>XSLT 1.0
|
|
behavior</b> if its <a title="effective version" class="termref"
|
|
href="#dt-effective-version">effective version</a> is equal to
|
|
1.0.</p>
|
|
</dd>
|
|
<dt><a href="#dt-1.0-compatibility-feature">XSLT 1.0 compatibility
|
|
feature</a></dt>
|
|
<dd>
|
|
<p>A processor that claims conformance with the <b>XSLT 1.0
|
|
compatibility feature</b> <span class="verb">must</span> support
|
|
the processing of stylesheet instructions and XPath expressions
|
|
with <a title="XSLT 1.0 behavior" class="termref" href=
|
|
"#dt-xslt-10-behavior">XSLT 1.0 behavior</a>, as defined in
|
|
<a href="#backwards"><i>3.8 Backwards Compatible
|
|
Processing</i></a>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-xslt-20-behavior">XSLT 2.0 behavior</a></dt>
|
|
<dd>
|
|
<p>An element is processed with <b>XSLT 2.0 behavior</b> if its
|
|
<a title="effective version" class="termref" href=
|
|
"#dt-effective-version">effective version</a> is equal to 2.0.</p>
|
|
</dd>
|
|
<dt><a href="#dt-2.0-compatibility-feature">XSLT 2.0 compatibility
|
|
feature</a></dt>
|
|
<dd>
|
|
<p>A processor that claims conformance with the <b>XSLT 2.0
|
|
compatibility feature</b> <span class="verb">must</span> support
|
|
the processing of stylesheet instructions and XPath expressions
|
|
with <a title="XSLT 2.0 behavior" class="termref" href=
|
|
"#dt-xslt-20-behavior">XSLT 2.0 behavior</a>, as defined in
|
|
<a href="#backwards"><i>3.8 Backwards Compatible
|
|
Processing</i></a>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-xslt-element">XSLT element</a></dt>
|
|
<dd>
|
|
<p>An <b>XSLT element</b> is an element in the <a title=
|
|
"XSLT namespace" class="termref" href="#dt-xslt-namespace">XSLT
|
|
namespace</a> whose syntax and semantics are defined in this
|
|
specification.</p>
|
|
</dd>
|
|
<dt><a href="#dt-xslt-instruction">XSLT instruction</a></dt>
|
|
<dd>
|
|
<p>An <b>XSLT instruction</b> is an <a title="XSLT element" class=
|
|
"termref" href="#dt-xslt-element">XSLT element</a> whose syntax
|
|
summary in this specification contains the annotation <code><!--
|
|
category: instruction --></code>.</p>
|
|
</dd>
|
|
<dt><a href="#dt-xslt-namespace">XSLT namespace</a></dt>
|
|
<dd>
|
|
<p>The <b>XSLT namespace</b> has the URI
|
|
<code>http://www.w3.org/1999/XSL/Transform</code>. It is used to
|
|
identify elements, attributes, and other names that have a special
|
|
meaning defined in this specification.</p>
|
|
</dd>
|
|
</dl>
|
|
</div>
|
|
<div class="div1">
|
|
<h2><a name="element-syntax-summary" id=
|
|
"element-syntax-summary"></a>C Element Syntax Summary
|
|
(Non-Normative)</h2>
|
|
<p>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 sequence constructor.
|
|
These elements are:</p>
|
|
<ul>
|
|
<li>Literal result elements</li>
|
|
<li>Extension instructions, if so defined</li>
|
|
</ul>
|
|
<p><b><a href=
|
|
"#element-analyze-string">xsl:analyze-string</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Category:</i> instruction</p>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary">
|
|
<code><xsl:analyze-string<br />
|
|
  <b>select</b> = <var>expression</var><br />
|
|
  <b>regex</b> = { <var>string</var> }<br />
|
|
  flags? = { <var>string</var> } ><br />
|
|
  <!-- Content: (<a href=
|
|
"#element-matching-substring">xsl:matching-substring</a>?, <a href=
|
|
"#element-non-matching-substring">xsl:non-matching-substring</a>?,
|
|
<a href="#element-fallback">xsl:fallback</a>*) --><br />
|
|
</xsl:analyze-string></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li>any XSLT element whose content model is <i>sequence
|
|
constructor</i></li>
|
|
<li>any literal result element</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href=
|
|
"#element-apply-imports">xsl:apply-imports</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Category:</i> instruction</p>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary">
|
|
<code><xsl:apply-imports><br />
|
|
  <!-- Content: <a href=
|
|
"#element-with-param">xsl:with-param</a>* --><br />
|
|
</xsl:apply-imports></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li>any XSLT element whose content model is <i>sequence
|
|
constructor</i></li>
|
|
<li>any literal result element</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href=
|
|
"#element-apply-templates">xsl:apply-templates</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Category:</i> instruction</p>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary">
|
|
<code><xsl:apply-templates<br />
|
|
  select? = <var>expression</var><br />
|
|
  mode? = <var>token</var> ><br />
|
|
  <!-- Content: (<a href="#element-sort">xsl:sort</a>
|
|
| <a href="#element-with-param">xsl:with-param</a>)* --><br />
|
|
</xsl:apply-templates></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li>any XSLT element whose content model is <i>sequence
|
|
constructor</i></li>
|
|
<li>any literal result element</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href="#element-attribute">xsl:attribute</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Category:</i> instruction</p>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary"><code><xsl:attribute<br />
|
|
  <b>name</b> = { <var>qname</var> }<br />
|
|
  namespace? = { <var>uri-reference</var> }<br />
|
|
  select? = <var>expression</var><br />
|
|
  separator? = { <var>string</var> }<br />
|
|
  type? = <var>qname</var><br />
|
|
  validation? = "strict" | "lax" | "preserve" |
|
|
"strip" ><br />
|
|
  <!-- Content: <var>sequence-constructor</var>
|
|
--><br />
|
|
</xsl:attribute></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li><a href="#element-attribute-set">xsl:attribute-set</a></li>
|
|
<li>any XSLT element whose content model is <i>sequence
|
|
constructor</i></li>
|
|
<li>any literal result element</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href=
|
|
"#element-attribute-set">xsl:attribute-set</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Category:</i> declaration</p>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary"><code><xsl:attribute-set<br />
|
|
  <b>name</b> = <var>qname</var><br />
|
|
  use-attribute-sets? = <var>qnames</var> ><br />
|
|
  <!-- Content: <a href=
|
|
"#element-attribute">xsl:attribute</a>* --><br />
|
|
</xsl:attribute-set></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li><a href="#element-stylesheet">xsl:stylesheet</a></li>
|
|
<li><a href="#element-transform">xsl:transform</a></li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href="#element-break">xsl:break</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Category:</i> instruction</p>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary"><code><xsl:break><br />
|
|
  <!-- Content: (<var>sequence-constructor</var>)
|
|
--><br />
|
|
</xsl:break></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li>any XSLT element whose content model is <i>sequence
|
|
constructor</i></li>
|
|
<li>any literal result element</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href=
|
|
"#element-call-template">xsl:call-template</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Category:</i> instruction</p>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary"><code><xsl:call-template<br />
|
|
  <b>name</b> = <var>qname</var> ><br />
|
|
  <!-- Content: <a href=
|
|
"#element-with-param">xsl:with-param</a>* --><br />
|
|
</xsl:call-template></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li>any XSLT element whose content model is <i>sequence
|
|
constructor</i></li>
|
|
<li>any literal result element</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href="#element-catch">xsl:catch</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary"><code><xsl:catch<br />
|
|
  errors? = <var>tokens</var><br />
|
|
  select? = <var>expression</var> ><br />
|
|
  <!-- Content: <var>sequence-constructor</var>
|
|
--><br />
|
|
</xsl:catch></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li><a href="#element-try">xsl:try</a></li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href=
|
|
"#element-character-map">xsl:character-map</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Category:</i> declaration</p>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary"><code><xsl:character-map<br />
|
|
  <b>name</b> = <var>qname</var><br />
|
|
  use-character-maps? = <var>qnames</var> ><br />
|
|
  <!-- Content: (<a href=
|
|
"#element-output-character">xsl:output-character</a>*) --><br />
|
|
</xsl:character-map></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li><a href="#element-stylesheet">xsl:stylesheet</a></li>
|
|
<li><a href="#element-transform">xsl:transform</a></li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href="#element-choose">xsl:choose</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Category:</i> instruction</p>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary"><code><xsl:choose><br />
|
|
  <!-- Content: (<a href=
|
|
"#element-when">xsl:when</a>+, <a href=
|
|
"#element-otherwise">xsl:otherwise</a>?) --><br />
|
|
</xsl:choose></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li>any XSLT element whose content model is <i>sequence
|
|
constructor</i></li>
|
|
<li>any literal result element</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href="#element-comment">xsl:comment</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Category:</i> instruction</p>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary"><code><xsl:comment<br />
|
|
  select? = <var>expression</var> ><br />
|
|
  <!-- Content: <var>sequence-constructor</var>
|
|
--><br />
|
|
</xsl:comment></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li>any XSLT element whose content model is <i>sequence
|
|
constructor</i></li>
|
|
<li>any literal result element</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href="#element-context-item">xsl:context-item</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary"><code><xsl:context-item<br />
|
|
  as? = <var>ItemType</var> /></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li><a href="#element-mode">xsl:mode</a></li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href="#element-copy">xsl:copy</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Category:</i> instruction</p>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary"><code><xsl:copy<br />
|
|
  select? = <var>expression</var><br />
|
|
  copy-namespaces? = "yes" | "no"<br />
|
|
  inherit-namespaces? = "yes" | "no"<br />
|
|
  use-attribute-sets? = <var>qnames</var><br />
|
|
  type? = <var>qname</var><br />
|
|
  validation? = "strict" | "lax" | "preserve" |
|
|
"strip" ><br />
|
|
  <!-- Content: <var>sequence-constructor</var>
|
|
--><br />
|
|
</xsl:copy></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li>any XSLT element whose content model is <i>sequence
|
|
constructor</i></li>
|
|
<li>any literal result element</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href="#element-copy-of">xsl:copy-of</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Category:</i> instruction</p>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary"><code><xsl:copy-of<br />
|
|
  <b>select</b> = <var>expression</var><br />
|
|
  copy-namespaces? = "yes" | "no"<br />
|
|
  type? = <var>qname</var><br />
|
|
  validation? = "strict" | "lax" | "preserve" |
|
|
"strip" /></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li>any XSLT element whose content model is <i>sequence
|
|
constructor</i></li>
|
|
<li>any literal result element</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href=
|
|
"#element-decimal-format">xsl:decimal-format</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Category:</i> declaration</p>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary">
|
|
<code><xsl:decimal-format<br />
|
|
  name? = <var>qname</var><br />
|
|
  decimal-separator? = <var>char</var><br />
|
|
  grouping-separator? = <var>char</var><br />
|
|
  infinity? = <var>string</var><br />
|
|
  minus-sign? = <var>char</var><br />
|
|
  NaN? = <var>string</var><br />
|
|
  percent? = <var>char</var><br />
|
|
  per-mille? = <var>char</var><br />
|
|
  zero-digit? = <var>char</var><br />
|
|
  digit? = <var>char</var><br />
|
|
  pattern-separator? =
|
|
<var>char</var> /></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li><a href="#element-stylesheet">xsl:stylesheet</a></li>
|
|
<li><a href="#element-transform">xsl:transform</a></li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href="#element-document">xsl:document</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Category:</i> instruction</p>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary"><code><xsl:document<br />
|
|
  validation? = "strict" | "lax" | "preserve" |
|
|
"strip"<br />
|
|
  type? = <var>qname</var> ><br />
|
|
  <!-- Content: <var>sequence-constructor</var>
|
|
--><br />
|
|
</xsl:document></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li>any XSLT element whose content model is <i>sequence
|
|
constructor</i></li>
|
|
<li>any literal result element</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href="#element-element">xsl:element</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Category:</i> instruction</p>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary"><code><xsl:element<br />
|
|
  <b>name</b> = { <var>qname</var> }<br />
|
|
  namespace? = { <var>uri-reference</var> }<br />
|
|
  inherit-namespaces? = "yes" | "no"<br />
|
|
  use-attribute-sets? = <var>qnames</var><br />
|
|
  type? = <var>qname</var><br />
|
|
  validation? = "strict" | "lax" | "preserve" |
|
|
"strip" ><br />
|
|
  <!-- Content: <var>sequence-constructor</var>
|
|
--><br />
|
|
</xsl:element></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li>any XSLT element whose content model is <i>sequence
|
|
constructor</i></li>
|
|
<li>any literal result element</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href="#element-evaluate">xsl:evaluate</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Category:</i> instruction</p>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary"><code><xsl:evaluate<br />
|
|
  <b>xpath</b> = <var>expression</var><br />
|
|
  as? = <var>sequence-type</var><br />
|
|
  base-uri? = { <var>URI</var> }<br />
|
|
  namespace-context? = <var>expression</var><br />
|
|
  schema-aware? = { "yes" | "no" } ><br />
|
|
  <!-- Content: (<a href=
|
|
"#element-with-param">xsl:with-param</a> | <a href=
|
|
"#element-fallback">xsl:fallback</a>)* --><br />
|
|
</xsl:evaluate></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li>any XSLT element whose content model is <i>sequence
|
|
constructor</i></li>
|
|
<li>any literal result element</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href="#element-fallback">xsl:fallback</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Category:</i> instruction</p>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary"><code><xsl:fallback><br />
|
|
  <!-- Content: <var>sequence-constructor</var>
|
|
--><br />
|
|
</xsl:fallback></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li>any XSLT element whose content model is <i>sequence
|
|
constructor</i></li>
|
|
<li>any literal result element</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href="#element-for-each">xsl:for-each</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Category:</i> instruction</p>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary"><code><xsl:for-each<br />
|
|
  <b>select</b> = <var>expression</var> ><br />
|
|
  <!-- Content: (<a href=
|
|
"#element-sort">xsl:sort</a>*, <var>sequence-constructor</var>)
|
|
--><br />
|
|
</xsl:for-each></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li>any XSLT element whose content model is <i>sequence
|
|
constructor</i></li>
|
|
<li>any literal result element</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href=
|
|
"#element-for-each-group">xsl:for-each-group</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Category:</i> instruction</p>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary">
|
|
<code><xsl:for-each-group<br />
|
|
  <b>select</b> = <var>expression</var><br />
|
|
  group-by? = <var>expression</var><br />
|
|
  group-adjacent? = <var>expression</var><br />
|
|
  group-starting-with? = <var>pattern</var><br />
|
|
  group-ending-with? = <var>pattern</var><br />
|
|
  collation? = { <var>uri</var> } ><br />
|
|
  <!-- Content: (<a href=
|
|
"#element-sort">xsl:sort</a>*, <var>sequence-constructor</var>)
|
|
--><br />
|
|
</xsl:for-each-group></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li>any XSLT element whose content model is <i>sequence
|
|
constructor</i></li>
|
|
<li>any literal result element</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href="#element-fork">xsl:fork</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Category:</i> instruction</p>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary"><code><xsl:fork><br />
|
|
  <!-- Content: (<var>sequence-constructor</var>)
|
|
--><br />
|
|
</xsl:fork></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li>any XSLT element whose content model is <i>sequence
|
|
constructor</i></li>
|
|
<li>any literal result element</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href="#element-function">xsl:function</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Category:</i> declaration</p>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary"><code><xsl:function<br />
|
|
  <b>name</b> = <var>qname</var><br />
|
|
  as? = <var>sequence-type</var><br />
|
|
  override? = "yes" | "no" ><br />
|
|
  <!-- Content: (<a href=
|
|
"#element-param">xsl:param</a>*, <var>sequence-constructor</var>)
|
|
--><br />
|
|
</xsl:function></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li><a href="#element-stylesheet">xsl:stylesheet</a></li>
|
|
<li><a href="#element-transform">xsl:transform</a></li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href="#element-if">xsl:if</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Category:</i> instruction</p>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary"><code><xsl:if<br />
|
|
  <b>test</b> = <var>expression</var> ><br />
|
|
  <!-- Content: <var>sequence-constructor</var>
|
|
--><br />
|
|
</xsl:if></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li>any XSLT element whose content model is <i>sequence
|
|
constructor</i></li>
|
|
<li>any literal result element</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href="#element-import">xsl:import</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Category:</i> declaration</p>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary"><code><xsl:import<br />
|
|
  <b>href</b> =
|
|
<var>uri-reference</var> /></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li><a href="#element-stylesheet">xsl:stylesheet</a></li>
|
|
<li><a href="#element-transform">xsl:transform</a></li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href=
|
|
"#element-import-schema">xsl:import-schema</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Category:</i> declaration</p>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary"><code><xsl:import-schema<br />
|
|
  namespace? = <var>uri-reference</var><br />
|
|
  schema-location? =
|
|
<var>uri-reference</var> ><br />
|
|
  <!-- Content: xs:schema? --><br />
|
|
</xsl:import-schema></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li><a href="#element-stylesheet">xsl:stylesheet</a></li>
|
|
<li><a href="#element-transform">xsl:transform</a></li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href="#element-include">xsl:include</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Category:</i> declaration</p>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary"><code><xsl:include<br />
|
|
  <b>href</b> =
|
|
<var>uri-reference</var> /></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li><a href="#element-stylesheet">xsl:stylesheet</a></li>
|
|
<li><a href="#element-transform">xsl:transform</a></li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href="#element-iterate">xsl:iterate</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Category:</i> instruction</p>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary"><code><xsl:iterate<br />
|
|
  <b>select</b> = <var>expression</var> ><br />
|
|
  <!-- Content: (<a href=
|
|
"#element-param">xsl:param</a>*, <var>sequence-constructor</var>,
|
|
<a href="#element-on-completion">xsl:on-completion</a>?)
|
|
--><br />
|
|
</xsl:iterate></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li>any XSLT element whose content model is <i>sequence
|
|
constructor</i></li>
|
|
<li>any literal result element</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href="#element-key">xsl:key</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Category:</i> declaration</p>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary"><code><xsl:key<br />
|
|
  <b>name</b> = <var>qname</var><br />
|
|
  <b>match</b> = <var>pattern</var><br />
|
|
  use? = <var>expression</var><br />
|
|
  collation? = <var>uri</var> ><br />
|
|
  <!-- Content: <var>sequence-constructor</var>
|
|
--><br />
|
|
</xsl:key></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li><a href="#element-stylesheet">xsl:stylesheet</a></li>
|
|
<li><a href="#element-transform">xsl:transform</a></li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href=
|
|
"#element-matching-substring">xsl:matching-substring</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary">
|
|
<code><xsl:matching-substring><br />
|
|
  <!-- Content: <var>sequence-constructor</var>
|
|
--><br />
|
|
</xsl:matching-substring></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li><a href="#element-analyze-string">xsl:analyze-string</a></li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href="#element-merge">xsl:merge</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Category:</i> instruction</p>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary"><code><xsl:merge><br />
|
|
  <!-- Content: (<a href=
|
|
"#element-merge-source">xsl:merge-source</a>+, <a href=
|
|
"#element-merge-action">xsl:merge-action</a>, <a href=
|
|
"#element-fallback">xsl:fallback</a>*) --><br />
|
|
</xsl:merge></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li>any XSLT element whose content model is <i>sequence
|
|
constructor</i></li>
|
|
<li>any literal result element</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href="#element-merge-action">xsl:merge-action</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary">
|
|
<code><xsl:merge-action><br />
|
|
  <!-- Content: (<var>sequence-constructor</var>)
|
|
--><br />
|
|
</xsl:merge-action></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li><a href="#element-merge">xsl:merge</a></li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href="#element-merge-input">xsl:merge-input</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary"><code><xsl:merge-input<br />
|
|
  select? = <var>expression</var> ><br />
|
|
  <!-- Content: (<var>sequence-constructor</var>,
|
|
<a href="#element-merge-key">xsl:merge-key</a>+) --><br />
|
|
</xsl:merge-input></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li><a href="#element-merge-source">xsl:merge-source</a></li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href="#element-merge-key">xsl:merge-key</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary"><code><xsl:merge-key<br />
|
|
  select? = <var>expression</var><br />
|
|
  lang? = { <var>nmtoken</var> }<br />
|
|
  order? = { "ascending" | "descending" }<br />
|
|
  collation? = { <var>uri</var> }<br />
|
|
  case-order? = { "upper-first" | "lower-first" }<br />
|
|
  data-type? = { "text" | "number" |
|
|
<var>qname-but-not-ncname</var> } ><br />
|
|
  <!-- Content: <var>sequence-constructor</var>
|
|
--><br />
|
|
</xsl:merge-key></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li><a href="#element-merge-input">xsl:merge-input</a></li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href="#element-merge-source">xsl:merge-source</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary"><code><xsl:merge-source<br />
|
|
  select? = <var>expression</var><br />
|
|
  name? = <var>QName</var> ><br />
|
|
  <!-- Content: <a href=
|
|
"#element-merge-input">xsl:merge-input</a> --><br />
|
|
</xsl:merge-source></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li><a href="#element-merge">xsl:merge</a></li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href="#element-message">xsl:message</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Category:</i> instruction</p>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary"><code><xsl:message<br />
|
|
  select? = <var>expression</var><br />
|
|
  terminate? = { "yes" | "no" }<br />
|
|
  error-code? = { <var>QName</var> } ><br />
|
|
  <!-- Content: <var>sequence-constructor</var>
|
|
--><br />
|
|
</xsl:message></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li>any XSLT element whose content model is <i>sequence
|
|
constructor</i></li>
|
|
<li>any literal result element</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href="#element-mode">xsl:mode</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Category:</i> declaration</p>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary"><code><xsl:mode<br />
|
|
  name? = <var>qname</var><br />
|
|
  streamable? = "yes" | "no"<br />
|
|
  initial? = "yes" | "no"<br />
|
|
  on-no-match? = "stringify" | "discard" | "copy" |
|
|
"fail"<br />
|
|
  on-multiple-match? = "use-last" | "fail"<br />
|
|
  warning-on-no-match? = "yes" | "no"<br />
|
|
  warning-on-multiple-match? = "yes" |
|
|
"no" ><br />
|
|
  <!-- Content: (<a href=
|
|
"#element-context-item">xsl:context-item</a>?) --><br />
|
|
</xsl:mode></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li><a href="#element-stylesheet">xsl:stylesheet</a></li>
|
|
<li><a href="#element-transform">xsl:transform</a></li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href="#element-namespace">xsl:namespace</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Category:</i> instruction</p>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary"><code><xsl:namespace<br />
|
|
  <b>name</b> = { <var>ncname</var> }<br />
|
|
  select? = <var>expression</var> ><br />
|
|
  <!-- Content: <var>sequence-constructor</var>
|
|
--><br />
|
|
</xsl:namespace></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li>any XSLT element whose content model is <i>sequence
|
|
constructor</i></li>
|
|
<li>any literal result element</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href=
|
|
"#element-namespace-alias">xsl:namespace-alias</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Category:</i> declaration</p>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary">
|
|
<code><xsl:namespace-alias<br />
|
|
  <b>stylesheet-prefix</b> = <var>prefix</var> |
|
|
"#default"<br />
|
|
  <b>result-prefix</b> = <var>prefix</var> |
|
|
"#default" /></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li><a href="#element-stylesheet">xsl:stylesheet</a></li>
|
|
<li><a href="#element-transform">xsl:transform</a></li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href=
|
|
"#element-next-iteration">xsl:next-iteration</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Category:</i> instruction</p>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary">
|
|
<code><xsl:next-iteration><br />
|
|
  <!-- Content: (<a href=
|
|
"#element-with-param">xsl:with-param</a>*) --><br />
|
|
</xsl:next-iteration></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li>any XSLT element whose content model is <i>sequence
|
|
constructor</i></li>
|
|
<li>any literal result element</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href="#element-next-match">xsl:next-match</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Category:</i> instruction</p>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary">
|
|
<code><xsl:next-match><br />
|
|
  <!-- Content: (<a href=
|
|
"#element-with-param">xsl:with-param</a> | <a href=
|
|
"#element-fallback">xsl:fallback</a>)* --><br />
|
|
</xsl:next-match></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li>any XSLT element whose content model is <i>sequence
|
|
constructor</i></li>
|
|
<li>any literal result element</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href=
|
|
"#element-non-matching-substring">xsl:non-matching-substring</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary">
|
|
<code><xsl:non-matching-substring><br />
|
|
  <!-- Content: <var>sequence-constructor</var>
|
|
--><br />
|
|
</xsl:non-matching-substring></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li><a href="#element-analyze-string">xsl:analyze-string</a></li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href="#element-number">xsl:number</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Category:</i> instruction</p>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary"><code><xsl:number<br />
|
|
  value? = <var>expression</var><br />
|
|
  select? = <var>expression</var><br />
|
|
  level? = "single" | "multiple" | "any"<br />
|
|
  count? = <var>pattern</var><br />
|
|
  from? = <var>pattern</var><br />
|
|
  format? = { <var>string</var> }<br />
|
|
  lang? = { <var>nmtoken</var> }<br />
|
|
  letter-value? = { "alphabetic" | "traditional" }<br />
|
|
  ordinal? = { <var>string</var> }<br />
|
|
  grouping-separator? = { <var>char</var> }<br />
|
|
  grouping-size? = { <var>number</var>
|
|
} /></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li>any XSLT element whose content model is <i>sequence
|
|
constructor</i></li>
|
|
<li>any literal result element</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href=
|
|
"#element-on-completion">xsl:on-completion</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary">
|
|
<code><xsl:on-completion><br />
|
|
  <!-- Content: (<var>sequence-constructor</var>)
|
|
--><br />
|
|
</xsl:on-completion></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li><a href="#element-iterate">xsl:iterate</a></li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href="#element-otherwise">xsl:otherwise</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary"><code><xsl:otherwise><br />
|
|
  <!-- Content: <var>sequence-constructor</var>
|
|
--><br />
|
|
</xsl:otherwise></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li><a href="#element-choose">xsl:choose</a></li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href="#element-output">xsl:output</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Category:</i> declaration</p>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary"><code><xsl:output<br />
|
|
  name? = <var>qname</var><br />
|
|
  method? = "xml" | "html" | "xhtml" | "text" |
|
|
<var>qname-but-not-ncname</var><br />
|
|
  byte-order-mark? = "yes" | "no"<br />
|
|
  cdata-section-elements? = <var>qnames</var><br />
|
|
  doctype-public? = <var>string</var><br />
|
|
  doctype-system? = <var>string</var><br />
|
|
  encoding? = <var>string</var><br />
|
|
  escape-uri-attributes? = "yes" | "no"<br />
|
|
  include-content-type? = "yes" | "no"<br />
|
|
  indent? = "yes" | "no"<br />
|
|
  media-type? = <var>string</var><br />
|
|
  normalization-form? = "NFC" | "NFD" | "NFKC" | "NFKD" |
|
|
"fully-normalized" | "none" | <var>nmtoken</var><br />
|
|
  omit-xml-declaration? = "yes" | "no"<br />
|
|
  standalone? = "yes" | "no" | "omit"<br />
|
|
  suppress-indentation? = <var>qnames</var><br />
|
|
  undeclare-prefixes? = "yes" | "no"<br />
|
|
  use-character-maps? = <var>qnames</var><br />
|
|
  version? = <var>nmtoken</var> /></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li><a href="#element-stylesheet">xsl:stylesheet</a></li>
|
|
<li><a href="#element-transform">xsl:transform</a></li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href=
|
|
"#element-output-character">xsl:output-character</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary">
|
|
<code><xsl:output-character<br />
|
|
  <b>character</b> = <var>char</var><br />
|
|
  <b>string</b> = <var>string</var> /></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li><a href="#element-character-map">xsl:character-map</a></li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href="#element-param">xsl:param</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Category:</i> declaration</p>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary"><code><xsl:param<br />
|
|
  <b>name</b> = <var>qname</var><br />
|
|
  select? = <var>expression</var><br />
|
|
  as? = <var>sequence-type</var><br />
|
|
  required? = "yes" | "no"<br />
|
|
  tunnel? = "yes" | "no" ><br />
|
|
  <!-- Content: <var>sequence-constructor</var>
|
|
--><br />
|
|
</xsl:param></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li><a href="#element-stylesheet">xsl:stylesheet</a></li>
|
|
<li><a href="#element-transform">xsl:transform</a></li>
|
|
<li><a href="#element-function">xsl:function</a></li>
|
|
<li><a href="#element-template">xsl:template</a></li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href="#element-perform-sort">xsl:perform-sort</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Category:</i> instruction</p>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary"><code><xsl:perform-sort<br />
|
|
  select? = <var>expression</var> ><br />
|
|
  <!-- Content: (<a href=
|
|
"#element-sort">xsl:sort</a>+, <var>sequence-constructor</var>)
|
|
--><br />
|
|
</xsl:perform-sort></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li>any XSLT element whose content model is <i>sequence
|
|
constructor</i></li>
|
|
<li>any literal result element</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href=
|
|
"#element-preserve-space">xsl:preserve-space</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Category:</i> declaration</p>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary">
|
|
<code><xsl:preserve-space<br />
|
|
  <b>elements</b> =
|
|
<var>tokens</var> /></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li><a href="#element-stylesheet">xsl:stylesheet</a></li>
|
|
<li><a href="#element-transform">xsl:transform</a></li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href=
|
|
"#element-processing-instruction">xsl:processing-instruction</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Category:</i> instruction</p>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary">
|
|
<code><xsl:processing-instruction<br />
|
|
  <b>name</b> = { <var>ncname</var> }<br />
|
|
  select? = <var>expression</var> ><br />
|
|
  <!-- Content: <var>sequence-constructor</var>
|
|
--><br />
|
|
</xsl:processing-instruction></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li>any XSLT element whose content model is <i>sequence
|
|
constructor</i></li>
|
|
<li>any literal result element</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href=
|
|
"#element-result-document">xsl:result-document</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Category:</i> instruction</p>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary">
|
|
<code><xsl:result-document<br />
|
|
  format? = { <var>qname</var> }<br />
|
|
  href? = { <var>uri-reference</var> }<br />
|
|
  validation? = "strict" | "lax" | "preserve" |
|
|
"strip"<br />
|
|
  type? = <var>qname</var><br />
|
|
  method? = { "xml" | "html" | "xhtml" | "text" |
|
|
<var>qname-but-not-ncname</var> }<br />
|
|
  byte-order-mark? = { "yes" | "no" }<br />
|
|
  cdata-section-elements? = { <var>qnames</var> }<br />
|
|
  doctype-public? = { <var>string</var> }<br />
|
|
  doctype-system? = { <var>string</var> }<br />
|
|
  encoding? = { <var>string</var> }<br />
|
|
  escape-uri-attributes? = { "yes" | "no" }<br />
|
|
  include-content-type? = { "yes" | "no" }<br />
|
|
  indent? = { "yes" | "no" }<br />
|
|
  media-type? = { <var>string</var> }<br />
|
|
  normalization-form? = { "NFC" | "NFD" | "NFKC" | "NFKD"
|
|
| "fully-normalized" | "none" | <var>nmtoken</var> }<br />
|
|
  omit-xml-declaration? = { "yes" | "no" }<br />
|
|
  standalone? = { "yes" | "no" | "omit" }<br />
|
|
  suppress-indentation? = { <var>qnames</var> }<br />
|
|
  undeclare-prefixes? = { "yes" | "no" }<br />
|
|
  use-character-maps? = <var>qnames</var><br />
|
|
  output-version? = { <var>nmtoken</var>
|
|
} ><br />
|
|
  <!-- Content: <var>sequence-constructor</var>
|
|
--><br />
|
|
</xsl:result-document></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li>any XSLT element whose content model is <i>sequence
|
|
constructor</i></li>
|
|
<li>any literal result element</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href="#element-sequence">xsl:sequence</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Category:</i> instruction</p>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary"><code><xsl:sequence<br />
|
|
  <b>select</b> = <var>expression</var> ><br />
|
|
  <!-- Content: <var>sequence-constructor</var>
|
|
--><br />
|
|
</xsl:sequence></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li>any XSLT element whose content model is <i>sequence
|
|
constructor</i></li>
|
|
<li>any literal result element</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href="#element-sort">xsl:sort</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary"><code><xsl:sort<br />
|
|
  select? = <var>expression</var><br />
|
|
  lang? = { <var>nmtoken</var> }<br />
|
|
  order? = { "ascending" | "descending" }<br />
|
|
  collation? = { <var>uri</var> }<br />
|
|
  stable? = { "yes" | "no" }<br />
|
|
  case-order? = { "upper-first" | "lower-first" }<br />
|
|
  data-type? = { "text" | "number" |
|
|
<var>qname-but-not-ncname</var> } ><br />
|
|
  <!-- Content: <var>sequence-constructor</var>
|
|
--><br />
|
|
</xsl:sort></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li><a href="#element-apply-templates">xsl:apply-templates</a></li>
|
|
<li><a href="#element-for-each">xsl:for-each</a></li>
|
|
<li><a href="#element-for-each-group">xsl:for-each-group</a></li>
|
|
<li><a href="#element-perform-sort">xsl:perform-sort</a></li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href="#element-stream">xsl:stream</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Category:</i> instruction</p>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary"><code><xsl:stream<br />
|
|
  <b>href</b> = { <var>uri-reference</var>
|
|
} ><br />
|
|
  <!-- Content: <var>sequence-constructor</var>
|
|
--><br />
|
|
</xsl:stream></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li>any XSLT element whose content model is <i>sequence
|
|
constructor</i></li>
|
|
<li>any literal result element</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href="#element-strip-space">xsl:strip-space</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Category:</i> declaration</p>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary"><code><xsl:strip-space<br />
|
|
  <b>elements</b> =
|
|
<var>tokens</var> /></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li><a href="#element-stylesheet">xsl:stylesheet</a></li>
|
|
<li><a href="#element-transform">xsl:transform</a></li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href="#element-stylesheet">xsl:stylesheet</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary"><code><xsl:stylesheet<br />
|
|
  id? = <var>id</var><br />
|
|
  extension-element-prefixes? = <var>tokens</var><br />
|
|
  exclude-result-prefixes? = <var>tokens</var><br />
|
|
  <b>version</b> = <var>number</var><br />
|
|
  xpath-default-namespace? = <var>uri</var><br />
|
|
  default-validation? = "preserve" | "strip"<br />
|
|
  default-collation? = <var>uri-list</var><br />
|
|
  default-mode? = <var>qname</var> | "#unnamed"<br />
|
|
  input-type-annotations? = "preserve" | "strip" |
|
|
"unspecified" ><br />
|
|
  <!-- Content: (<a href=
|
|
"#element-import">xsl:import</a>*, <var>other-declarations</var>)
|
|
--><br />
|
|
</xsl:stylesheet></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li>None</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href="#element-template">xsl:template</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Category:</i> declaration</p>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary"><code><xsl:template<br />
|
|
  match? = <var>pattern</var><br />
|
|
  name? = <var>qname</var><br />
|
|
  priority? = <var>number</var><br />
|
|
  mode? = <var>tokens</var><br />
|
|
  as? = <var>sequence-type</var> ><br />
|
|
  <!-- Content: (<a href=
|
|
"#element-param">xsl:param</a>*, <var>sequence-constructor</var>)
|
|
--><br />
|
|
</xsl:template></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li><a href="#element-stylesheet">xsl:stylesheet</a></li>
|
|
<li><a href="#element-transform">xsl:transform</a></li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href="#element-text">xsl:text</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Category:</i> instruction</p>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary"><code><xsl:text<br />
|
|
  <span class="grayed">[disable-output-escaping]?</span>
|
|
= "yes" | "no" ><br />
|
|
  <!-- Content: #PCDATA --><br />
|
|
</xsl:text></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li>any XSLT element whose content model is <i>sequence
|
|
constructor</i></li>
|
|
<li>any literal result element</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href="#element-transform">xsl:transform</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary"><code><xsl:transform<br />
|
|
  id? = <var>id</var><br />
|
|
  extension-element-prefixes? = <var>tokens</var><br />
|
|
  exclude-result-prefixes? = <var>tokens</var><br />
|
|
  <b>version</b> = <var>number</var><br />
|
|
  xpath-default-namespace? = <var>uri</var><br />
|
|
  default-validation? = "preserve" | "strip"<br />
|
|
  default-collation? = <var>uri-list</var><br />
|
|
  default-mode? = <var>qname</var> | "#unnamed"<br />
|
|
  input-type-annotations? = "preserve" | "strip" |
|
|
"unspecified" ><br />
|
|
  <!-- Content: (<a href=
|
|
"#element-import">xsl:import</a>*, <var>other-declarations</var>)
|
|
--><br />
|
|
</xsl:transform></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li>None</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href="#element-try">xsl:try</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Category:</i> instruction</p>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary"><code><xsl:try<br />
|
|
  select? = <var>expression</var> ><br />
|
|
  <!-- Content: (<var>sequence-constructor</var>,
|
|
<a href="#element-catch">xsl:catch</a>, (<a href=
|
|
"#element-catch">xsl:catch</a> | <a href=
|
|
"#element-fallback">xsl:fallback</a>)*) --><br />
|
|
</xsl:try></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li>any XSLT element whose content model is <i>sequence
|
|
constructor</i></li>
|
|
<li>any literal result element</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href="#element-value-of">xsl:value-of</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Category:</i> instruction</p>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary"><code><xsl:value-of<br />
|
|
  select? = <var>expression</var><br />
|
|
  separator? = { <var>string</var> }<br />
|
|
  <span class="grayed">[disable-output-escaping]?</span>
|
|
= "yes" | "no" ><br />
|
|
  <!-- Content: <var>sequence-constructor</var>
|
|
--><br />
|
|
</xsl:value-of></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li>any XSLT element whose content model is <i>sequence
|
|
constructor</i></li>
|
|
<li>any literal result element</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href="#element-variable">xsl:variable</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Category:</i> declaration instruction</p>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary"><code><xsl:variable<br />
|
|
  <b>name</b> = <var>qname</var><br />
|
|
  select? = <var>expression</var><br />
|
|
  as? = <var>sequence-type</var> ><br />
|
|
  <!-- Content: <var>sequence-constructor</var>
|
|
--><br />
|
|
</xsl:variable></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li><a href="#element-stylesheet">xsl:stylesheet</a></li>
|
|
<li><a href="#element-transform">xsl:transform</a></li>
|
|
<li><a href="#element-function">xsl:function</a></li>
|
|
<li>any XSLT element whose content model is <i>sequence
|
|
constructor</i></li>
|
|
<li>any literal result element</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href="#element-when">xsl:when</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary"><code><xsl:when<br />
|
|
  <b>test</b> = <var>expression</var> ><br />
|
|
  <!-- Content: <var>sequence-constructor</var>
|
|
--><br />
|
|
</xsl:when></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li><a href="#element-choose">xsl:choose</a></li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b><a href="#element-with-param">xsl:with-param</a></b></p>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="10%"> </td>
|
|
<td>
|
|
<p><i>Model:</i></p>
|
|
<p class="element-syntax-summary"><code><xsl:with-param<br />
|
|
  <b>name</b> = <var>qname</var><br />
|
|
  select? = <var>expression</var><br />
|
|
  as? = <var>sequence-type</var><br />
|
|
  tunnel? = "yes" | "no" ><br />
|
|
  <!-- Content: <var>sequence-constructor</var>
|
|
--><br />
|
|
</xsl:with-param></code></p>
|
|
<p><i>Permitted parent elements:</i></p>
|
|
<ul>
|
|
<li><a href="#element-apply-templates">xsl:apply-templates</a></li>
|
|
<li><a href="#element-apply-imports">xsl:apply-imports</a></li>
|
|
<li><a href="#element-call-template">xsl:call-template</a></li>
|
|
<li><a href="#element-next-match">xsl:next-match</a></li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="div1">
|
|
<h2><a name="error-summary" id="error-summary"></a>D Summary of
|
|
Error Conditions (Non-Normative)</h2>
|
|
<p>This appendix provides a summary of error conditions that a
|
|
processor may signal. This list includes all error codes defined in
|
|
this specification, but this is not an exhaustive list of all
|
|
errors that can occur. Implementations <span class=
|
|
"verb">must</span> signal errors using these error codes, and
|
|
applications can test for these codes; however, when more than one
|
|
rule in the specification is violated, different processors will
|
|
not necessarily signal the same error code. Implementations are not
|
|
<span class="verb">required</span> to signal errors using the
|
|
descriptive text used here.</p>
|
|
<div class="note">
|
|
<p class="prefix"><b>Note:</b></p>
|
|
<p>The appendix is non-normative because the same information is
|
|
given normatively elsewhere.</p>
|
|
</div>
|
|
<p><b>Static errors</b></p>
|
|
<dl>
|
|
<dt><a href="#err-XTSE0010"><span class="error">ERR
|
|
XTSE0010</span></a></dt>
|
|
<dd>
|
|
<p>A <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> is signaled if an XSLT-defined
|
|
element is used in a context where it is not permitted, if a
|
|
<span class="verb">required</span> attribute is omitted, or if the
|
|
content of the element does not correspond to the content that is
|
|
allowed for the element.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE0020"><span class="error">ERR
|
|
XTSE0020</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if an attribute (other than an
|
|
attribute written using curly brackets in a position where an
|
|
<a title="attribute value template" class="termref" href=
|
|
"#dt-attribute-value-template">attribute value template</a> is
|
|
permitted) contains a value that is not one of the permitted values
|
|
for that attribute.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE0080"><span class="error">ERR
|
|
XTSE0080</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> to use a <a title=
|
|
"reserved namespace" class="termref" href=
|
|
"#dt-reserved-namespace">reserved namespace</a> in the name of a
|
|
<a title="named template" class="termref" href=
|
|
"#dt-named-template">named template</a>, a <a title="mode" class=
|
|
"termref" href="#dt-mode">mode</a>, an <a title="attribute set"
|
|
class="termref" href="#dt-attribute-set">attribute set</a>, a
|
|
<a title="key" class="termref" href="#dt-key">key</a>, a <a title=
|
|
"decimal format" class="termref" href=
|
|
"#dt-decimal-format">decimal-format</a>, a <a title="variable"
|
|
class="termref" href="#dt-variable">variable</a> or <a title=
|
|
"parameter" class="termref" href="#dt-parameter">parameter</a>, a
|
|
<a title="stylesheet function" class="termref" href=
|
|
"#dt-stylesheet-function">stylesheet function</a>, a named
|
|
<a title="output definition" class="termref" href=
|
|
"#dt-output-definition">output definition</a>, or a <a title=
|
|
"character map" class="termref" href="#dt-character-map">character
|
|
map</a>.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE0090"><span class="error">ERR
|
|
XTSE0090</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> for an element from the XSLT
|
|
namespace to have an attribute whose namespace is either null (that
|
|
is, an attribute with an unprefixed name) or the XSLT namespace,
|
|
other than attributes defined for the element in this document.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE0110"><span class="error">ERR
|
|
XTSE0110</span></a></dt>
|
|
<dd>
|
|
<p>The value of the <code>version</code> attribute <span class=
|
|
"verb">must</span> be a number: specifically, it <span class=
|
|
"verb">must</span> be a a valid instance of the type
|
|
<code>xs:decimal</code> as defined in <a href="#xmlschema-2">[XML
|
|
Schema Part 2]</a>.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE0120"><span class="error">ERR
|
|
XTSE0120</span></a></dt>
|
|
<dd>
|
|
<p>An <a href="#element-stylesheet"><code>xsl:stylesheet</code></a>
|
|
element <span class="verb">must not</span> have any text node
|
|
children.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE0125"><span class="error">ERR
|
|
XTSE0125</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if the value of an
|
|
<code>[xsl:]default-collation</code> attribute, after resolving
|
|
against the base URI, contains no URI that the implementation
|
|
recognizes as a collation URI.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE0130"><span class="error">ERR
|
|
XTSE0130</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if the <a href=
|
|
"#element-stylesheet"><code>xsl:stylesheet</code></a> element has a
|
|
child element whose name has a null namespace URI.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE0150"><span class="error">ERR
|
|
XTSE0150</span></a></dt>
|
|
<dd>
|
|
<p>A <a title="literal result element" class="termref" href=
|
|
"#dt-literal-result-element">literal result element</a> that is
|
|
used as the outermost element of a simplified stylesheet module
|
|
<span class="verb">must</span> have an <code>xsl:version</code>
|
|
attribute.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE0165"><span class="error">ERR
|
|
XTSE0165</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if the processor is not able to
|
|
retrieve the resource identified by the URI reference [ in the
|
|
<code>href</code> attribute of <a href=
|
|
"#element-include"><code>xsl:include</code></a> or <a href=
|
|
"#element-import"><code>xsl:import</code></a> ] , or if the
|
|
resource that is retrieved does not contain a stylesheet module
|
|
conforming to this specification.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE0170"><span class="error">ERR
|
|
XTSE0170</span></a></dt>
|
|
<dd>
|
|
<p>An <a href="#element-include"><code>xsl:include</code></a>
|
|
element <span class="verb">must</span> be a <a title="top-level"
|
|
class="termref" href="#dt-top-level">top-level</a> element.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE0180"><span class="error">ERR
|
|
XTSE0180</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if a stylesheet module directly
|
|
or indirectly includes itself.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE0190"><span class="error">ERR
|
|
XTSE0190</span></a></dt>
|
|
<dd>
|
|
<p>An <a href="#element-import"><code>xsl:import</code></a> element
|
|
<span class="verb">must</span> be a <a title="top-level" class=
|
|
"termref" href="#dt-top-level">top-level</a> element.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE0200"><span class="error">ERR
|
|
XTSE0200</span></a></dt>
|
|
<dd>
|
|
<p>The <a href="#element-import"><code>xsl:import</code></a>
|
|
element children <span class="verb">must</span> precede all other
|
|
element children of an <a href=
|
|
"#element-stylesheet"><code>xsl:stylesheet</code></a> element,
|
|
including any <a href=
|
|
"#element-include"><code>xsl:include</code></a> element children
|
|
and any <a title="user-defined data element" class="termref" href=
|
|
"#dt-data-element">user-defined data elements</a>.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE0210"><span class="error">ERR
|
|
XTSE0210</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if a stylesheet module directly
|
|
or indirectly imports itself.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE0215"><span class="error">ERR
|
|
XTSE0215</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if an <a href=
|
|
"#element-import-schema"><code>xsl:import-schema</code></a> element
|
|
that contains an <code>xs:schema</code> element has a
|
|
<code>schema-location</code> attribute, or if it has a
|
|
<code>namespace</code> attribute that conflicts with the target
|
|
namespace of the contained schema.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE0220"><span class="error">ERR
|
|
XTSE0220</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if the synthetic schema
|
|
document does not satisfy the constraints described in <a href=
|
|
"#xmlschema-1">[XML Schema Part 1]</a> (section 5.1, <em>Errors in
|
|
Schema Construction and Structure</em>). This includes, without
|
|
loss of generality, conflicts such as multiple definitions of the
|
|
same name.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE0260"><span class="error">ERR
|
|
XTSE0260</span></a></dt>
|
|
<dd>
|
|
<p>Within an <a title="XSLT element" class="termref" href=
|
|
"#dt-xslt-element">XSLT element</a> that is <span class=
|
|
"verb">required</span> to be empty, any content other than comments
|
|
or processing instructions, including any <a title=
|
|
"whitespace text node" class="termref" href=
|
|
"#dt-whitespace-text-node">whitespace text node</a> preserved using
|
|
the <code>xml:space="preserve"</code> attribute, is a <a title=
|
|
"static error" class="termref" href="#dt-static-error">static
|
|
error</a>.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE0265"><span class="error">ERR
|
|
XTSE0265</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if there is a <a title=
|
|
"stylesheet module" class="termref" href=
|
|
"#dt-stylesheet-module">stylesheet module</a> in the <a title=
|
|
"stylesheet" class="termref" href="#dt-stylesheet">stylesheet</a>
|
|
that specifies <code>input-type-annotations="strip"</code> and
|
|
another <a title="stylesheet module" class="termref" href=
|
|
"#dt-stylesheet-module">stylesheet module</a> that specifies
|
|
<code>input-type-annotations="preserve"</code>.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE0280"><span class="error">ERR
|
|
XTSE0280</span></a></dt>
|
|
<dd>
|
|
<p>In the case of a prefixed <a title="QName" class="termref" href=
|
|
"#dt-qname">QName</a> used as the value of an attribute in the
|
|
<a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a>, or appearing within an XPath
|
|
<a title="expression" class="termref" href=
|
|
"#dt-expression">expression</a> in the stylesheet, it is a
|
|
<a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if the <a title=
|
|
"defining element" class="termref" href=
|
|
"#dt-defining-element">defining element</a> has no namespace node
|
|
whose name matches the prefix of the <a title="QName" class=
|
|
"termref" href="#dt-qname">QName</a>.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE0340"><span class="error">ERR
|
|
XTSE0340</span></a></dt>
|
|
<dd>
|
|
<p>Where an attribute is defined to contain a <a title="pattern"
|
|
class="termref" href="#dt-pattern">pattern</a>, it is a <a title=
|
|
"static error" class="termref" href="#dt-static-error">static
|
|
error</a> if the pattern does not match the production <a href=
|
|
"#NT-Pattern">Pattern</a>.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE0350"><span class="error">ERR
|
|
XTSE0350</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if an unescaped left curly
|
|
bracket appears in a fixed part of an attribute value template
|
|
without a matching right curly bracket.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE0370"><span class="error">ERR
|
|
XTSE0370</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if an unescaped right curly
|
|
bracket occurs in a fixed part of an attribute value template.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE0500"><span class="error">ERR
|
|
XTSE0500</span></a></dt>
|
|
<dd>
|
|
<p>An <a href="#element-template"><code>xsl:template</code></a>
|
|
element <span class="verb">must</span> have either a
|
|
<code>match</code> attribute or a <code>name</code> attribute, or
|
|
both. An <a href="#element-template"><code>xsl:template</code></a>
|
|
element that has no <code>match</code> attribute <span class=
|
|
"verb">must</span> have no <code>mode</code> attribute and no
|
|
<code>priority</code> attribute.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE0530"><span class="error">ERR
|
|
XTSE0530</span></a></dt>
|
|
<dd>
|
|
<p>The value of the <code>priority</code> attribute [ of the
|
|
<a href="#element-template"><code>xsl:template</code></a> element]
|
|
<span class="verb">must</span> conform to the rules for the
|
|
<code>xs:decimal</code> type defined in <a href="#xmlschema-2">[XML
|
|
Schema Part 2]</a>. Negative values are permitted.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE0542"><span class="error">ERR
|
|
XTSE0542</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if an <a href=
|
|
"#element-mode"><code>xsl:mode</code></a> declaration specifying
|
|
<code>initial="no"</code> contains an <a href=
|
|
"#element-context-item"><code>xsl:context-item</code></a>
|
|
element.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE0545"><span class="error">ERR
|
|
XTSE0545</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if a named or unnamed <a title=
|
|
"mode" class="termref" href="#dt-mode">mode</a> contains two
|
|
conflicting values for the same attribute in different <a href=
|
|
"#element-mode"><code>xsl:mode</code></a> declarations having the
|
|
same <a title="import precedence" class="termref" href=
|
|
"#dt-import-precedence">import precedence</a>, unless there is
|
|
another definition of the same attribute with higher import
|
|
precedence. The attributes in question are the attributes other
|
|
than <code>name</code> on the <a href=
|
|
"#element-mode"><code>xsl:mode</code></a> element, and the
|
|
<code>as</code> attribute on the contained <a href=
|
|
"#element-context-item"><code>xsl:context-item</code></a> element
|
|
if present.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE0548"><span class="error">ERR
|
|
XTSE0548</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if there is both (a) a
|
|
<a title="mode definition" class="termref" href=
|
|
"#dt-mode-definition">mode definition</a> in the <a title=
|
|
"stylesheet" class="termref" href="#dt-stylesheet">stylesheet</a>
|
|
that has the effective attribute values
|
|
<code>streamable="yes"</code> and <code>initial="yes"</code>, and
|
|
(b) a <a title="global variable" class="termref" href=
|
|
"#dt-global-variable">global variable</a> in the <a title=
|
|
"stylesheet" class="termref" href="#dt-stylesheet">stylesheet</a>
|
|
whose initializing expression is not <a title="motionless" class=
|
|
"termref" href="#dt-motionless">motionless</a> with respect to its
|
|
context item, as defined in <a href="#streamability"><i>18.4
|
|
Streamability Analysis</i></a>.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE0550"><span class="error">ERR
|
|
XTSE0550</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if the list [of modes in the
|
|
<code>mode</code> attribute of <a href=
|
|
"#element-template"><code>xsl:template</code></a> ] is empty, if
|
|
the same token is included more than once in the list, if the list
|
|
contains an invalid token, or if the token <code>#all</code>
|
|
appears together with any other value.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE2110"><span class="error">ERR
|
|
XTSE2110</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if an <a href=
|
|
"#element-break"><code>xsl:break</code></a> or <a href=
|
|
"#element-next-iteration"><code>xsl:next-iteration</code></a>
|
|
element appears other than in a <a title="tail position" class=
|
|
"termref" href="#dt-tail-position">tail position</a> within the
|
|
<a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> forming the
|
|
body of an <a href="#element-iterate"><code>xsl:iterate</code></a>
|
|
instruction.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE2120"><span class="error">ERR
|
|
XTSE2120</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if the <code>name</code>
|
|
attribute of an <a href=
|
|
"#element-with-param"><code>xsl:with-param</code></a> child of an
|
|
<a href=
|
|
"#element-next-iteration"><code>xsl:next-iteration</code></a>
|
|
element does not match the <code>name</code> attribute of an
|
|
<a href="#element-param"><code>xsl:param</code></a> child of the
|
|
<span>innermost</span> containing <a href=
|
|
"#element-iterate"><code>xsl:iterate</code></a> instruction.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE2130"><span class="error">ERR
|
|
XTSE2130</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if the <code>select</code>
|
|
attribute of the <a href="#element-try"><code>xsl:try</code></a>
|
|
element is present and the element has children other than <a href=
|
|
"#element-catch"><code>xsl:catch</code></a> and <a href=
|
|
"#element-fallback"><code>xsl:fallback</code></a> elements.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE2140"><span class="error">ERR
|
|
XTSE2140</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if the <code>select</code>
|
|
attribute of the <a href=
|
|
"#element-catch"><code>xsl:catch</code></a> element is present
|
|
unless the element has empty content.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE0580"><span class="error">ERR
|
|
XTSE0580</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if the values of the
|
|
<code>name</code> attribute of two <span>sibling <a href=
|
|
"#element-param"><code>xsl:param</code></a> elements represent the
|
|
same expanded <a title="QName" class="termref" href=
|
|
"#dt-qname">QName</a></span>.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE0620"><span class="error">ERR
|
|
XTSE0620</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if a <a title=
|
|
"variable-binding element" class="termref" href=
|
|
"#dt-variable-binding-element">variable-binding element</a> has a
|
|
<code>select</code> attribute and has non-empty content.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE0630"><span class="error">ERR
|
|
XTSE0630</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if a <a title="stylesheet"
|
|
class="termref" href="#dt-stylesheet">stylesheet</a> contains more
|
|
than one binding of a global variable with the same name and same
|
|
<a title="import precedence" class="termref" href=
|
|
"#dt-import-precedence">import precedence</a>, unless it also
|
|
contains another binding with the same name and higher import
|
|
precedence.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE0670"><span class="error">ERR
|
|
XTSE0670</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if two or more sibling <a href=
|
|
"#element-with-param"><code>xsl:with-param</code></a> elements have
|
|
<code>name</code> attributes that represent the same <a title=
|
|
"expanded-QName" class="termref" href="#dt-expanded-qname">expanded
|
|
QName</a>.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE0650"><span class="error">ERR
|
|
XTSE0650</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if a <a title="stylesheet"
|
|
class="termref" href="#dt-stylesheet">stylesheet</a> contains an
|
|
<a href="#element-call-template"><code>xsl:call-template</code></a>
|
|
instruction whose <code>name</code> attribute does not match the
|
|
<code>name</code> attribute of any <a href=
|
|
"#element-template"><code>xsl:template</code></a> in the <a title=
|
|
"stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a>.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE0660"><span class="error">ERR
|
|
XTSE0660</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if a <a title="stylesheet"
|
|
class="termref" href="#dt-stylesheet">stylesheet</a> contains more
|
|
than one <a title="template" class="termref" href=
|
|
"#dt-template">template</a> with the same name and the same
|
|
<a title="import precedence" class="termref" href=
|
|
"#dt-import-precedence">import precedence</a>, unless it also
|
|
contains a <a title="template" class="termref" href=
|
|
"#dt-template">template</a> with the same name and higher <a title=
|
|
"import precedence" class="termref" href=
|
|
"#dt-import-precedence">import precedence</a>.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE0680"><span class="error">ERR
|
|
XTSE0680</span></a></dt>
|
|
<dd>
|
|
<p>In the case of <a href=
|
|
"#element-call-template"><code>xsl:call-template</code></a>, it is
|
|
a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> to pass a non-tunnel parameter
|
|
named <var>x</var> to a template that does not have a <a title=
|
|
"template parameter" class="termref" href=
|
|
"#dt-template-parameter">template parameter</a> named <var>x</var>,
|
|
unless <span>the <a href=
|
|
"#element-call-template"><code>xsl:call-template</code></a>
|
|
instruction is processed with <a title="XSLT 1.0 behavior" class=
|
|
"termref" href="#dt-xslt-10-behavior">XSLT 1.0
|
|
behavior</a></span>.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE0690"><span class="error">ERR
|
|
XTSE0690</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if a template that is invoked
|
|
using <a href=
|
|
"#element-call-template"><code>xsl:call-template</code></a>
|
|
declares a <a title="template parameter" class="termref" href=
|
|
"#dt-template-parameter">template parameter</a> specifying
|
|
<code>required="yes"</code> and not specifying
|
|
<code>tunnel="yes"</code>, if no value for this parameter is
|
|
supplied by the calling <a href=
|
|
"#element-call-template"><code>xsl:call-template</code></a>
|
|
instruction.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE0710"><span class="error">ERR
|
|
XTSE0710</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if the value of the
|
|
<code>use-attribute-sets</code> attribute of an <a href=
|
|
"#element-copy"><code>xsl:copy</code></a>, <a href=
|
|
"#element-element"><code>xsl:element</code></a>, or <a href=
|
|
"#element-attribute-set"><code>xsl:attribute-set</code></a>
|
|
element, or the <code>xsl:use-attribute-sets</code> attribute of a
|
|
<a title="literal result element" class="termref" href=
|
|
"#dt-literal-result-element">literal result element</a>, is not a
|
|
whitespace-separated sequence of <a title="QName" class="termref"
|
|
href="#dt-qname">QNames</a>, or if it contains a QName that does
|
|
not match the <code>name</code> attribute of any <a href=
|
|
"#element-attribute-set"><code>xsl:attribute-set</code></a>
|
|
declaration in the stylesheet.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE0720"><span class="error">ERR
|
|
XTSE0720</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if an <a href=
|
|
"#element-attribute-set"><code>xsl:attribute-set</code></a> element
|
|
directly or indirectly references itself via the names contained in
|
|
the <code>use-attribute-sets</code> attribute.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE0740"><span class="error">ERR
|
|
XTSE0740</span></a></dt>
|
|
<dd>
|
|
<p>A <a title="stylesheet function" class="termref" href=
|
|
"#dt-stylesheet-function">stylesheet function</a> <span class=
|
|
"verb">must</span> have a prefixed name, to remove any risk of a
|
|
clash with a function in the default function namespace. It is a
|
|
<a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if the name has no prefix.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE0760"><span class="error">ERR
|
|
XTSE0760</span></a></dt>
|
|
<dd>
|
|
<p>Because arguments to a stylesheet function call <span class=
|
|
"verb">must</span> all be specified, the <a href=
|
|
"#element-param"><code>xsl:param</code></a> elements within an
|
|
<a href="#element-function"><code>xsl:function</code></a> element
|
|
<span class="verb">must not</span> specify a default value: this
|
|
means they <span class="verb">must</span> be empty, and
|
|
<span class="verb">must not</span> have a <code>select</code>
|
|
attribute.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE0770"><span class="error">ERR
|
|
XTSE0770</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> for a <a title="stylesheet"
|
|
class="termref" href="#dt-stylesheet">stylesheet</a> to contain two
|
|
or more functions with the same <a title="expanded-QName" class=
|
|
"termref" href="#dt-expanded-qname">expanded-QName</a>, the same
|
|
<a title="arity" class="termref" href="#dt-arity">arity</a>, and
|
|
the same <a title="import precedence" class="termref" href=
|
|
"#dt-import-precedence">import precedence</a>, unless there is
|
|
another function with the same <a title="expanded-QName" class=
|
|
"termref" href="#dt-expanded-qname">expanded-QName</a> and arity,
|
|
and a higher import precedence.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE0805"><span class="error">ERR
|
|
XTSE0805</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if an attribute on a literal
|
|
result element is in the <a title="XSLT namespace" class="termref"
|
|
href="#dt-xslt-namespace">XSLT namespace</a>, unless it is one of
|
|
the attributes explicitly defined in this specification.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE0808"><span class="error">ERR
|
|
XTSE0808</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if a namespace prefix is used
|
|
within the <code>[xsl:]exclude-result-prefixes</code> attribute and
|
|
there is no namespace binding in scope for that prefix.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE0809"><span class="error">ERR
|
|
XTSE0809</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if the value
|
|
<code>#default</code> is used within the
|
|
<code>[xsl:]exclude-result-prefixes</code> attribute and the parent
|
|
element of the <code>[xsl:]exclude-result-prefixes</code> attribute
|
|
has no default namespace.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE0810"><span class="error">ERR
|
|
XTSE0810</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if there is more than one such
|
|
declaration [more than one <a href=
|
|
"#element-namespace-alias"><code>xsl:namespace-alias</code></a>
|
|
declaration] with the same <a title="literal namespace URI" class=
|
|
"termref" href="#dt-literal-namespace-uri">literal namespace
|
|
URI</a> and the same <a title="import precedence" class="termref"
|
|
href="#dt-import-precedence">import precedence</a> and different
|
|
values for the <a title="target namespace URI" class="termref"
|
|
href="#dt-target-namespace-uri">target namespace URI</a>, unless
|
|
there is also an <a href=
|
|
"#element-namespace-alias"><code>xsl:namespace-alias</code></a>
|
|
declaration with the same <a title="literal namespace URI" class=
|
|
"termref" href="#dt-literal-namespace-uri">literal namespace
|
|
URI</a> and a higher import precedence.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE0812"><span class="error">ERR
|
|
XTSE0812</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if a value other than
|
|
<code>#default</code> is specified for either the
|
|
<code>stylesheet-prefix</code> or the <code>result-prefix</code>
|
|
attributes of the <a href=
|
|
"#element-namespace-alias"><code>xsl:namespace-alias</code></a>
|
|
element when there is no in-scope binding for that namespace
|
|
prefix.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE0840"><span class="error">ERR
|
|
XTSE0840</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if the <code>select</code>
|
|
attribute of the <a href=
|
|
"#element-attribute"><code>xsl:attribute</code></a> element is
|
|
present unless the element has empty content.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE0870"><span class="error">ERR
|
|
XTSE0870</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if the <code>select</code>
|
|
attribute of the <a href=
|
|
"#element-value-of"><code>xsl:value-of</code></a> element is
|
|
present when the content of the element is non-empty, or if the
|
|
<code>select</code> attribute is absent when the content is
|
|
empty.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE0880"><span class="error">ERR
|
|
XTSE0880</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if the <code>select</code>
|
|
attribute of the <a href=
|
|
"#element-processing-instruction"><code>xsl:processing-instruction</code></a>
|
|
element is present unless the element has empty content.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE0910"><span class="error">ERR
|
|
XTSE0910</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if the <code>select</code>
|
|
attribute of the <a href=
|
|
"#element-namespace"><code>xsl:namespace</code></a> element is
|
|
present when the element has content other than one or more
|
|
<a href="#element-fallback"><code>xsl:fallback</code></a>
|
|
instructions, or if the <code>select</code> attribute is absent
|
|
when the element has empty content.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE0940"><span class="error">ERR
|
|
XTSE0940</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if the <code>select</code>
|
|
attribute of the <a href=
|
|
"#element-comment"><code>xsl:comment</code></a> element is present
|
|
unless the element has empty content.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTTE0950"><span class="error">ERR
|
|
XTTE0950</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="type errors" class="termref" href=
|
|
"#dt-type-error">type error</a> to use the <a href=
|
|
"#element-copy"><code>xsl:copy</code></a> or <a href=
|
|
"#element-copy-of"><code>xsl:copy-of</code></a> instruction to copy
|
|
a node that has namespace-sensitive content if the
|
|
<code>copy-namespaces</code> attribute has the value
|
|
<code>no</code> and its explicit or implicit
|
|
<code>validation</code> attribute has the value
|
|
<code>preserve</code>. It is also a type error if either of these
|
|
instructions (with <code>validation="preserve"</code>) is used to
|
|
copy an attribute having namespace-sensitive content, unless the
|
|
parent element is also copied. A node has namespace-sensitive
|
|
content if its typed value contains an item of type
|
|
<code>xs:QName</code> or <code>xs:NOTATION</code> or a type derived
|
|
therefrom. The reason this is an error is because the validity of
|
|
the content depends on the namespace context being preserved.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE0975"><span class="error">ERR
|
|
XTSE0975</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if the <code>value</code>
|
|
attribute of <a href="#element-number"><code>xsl:number</code></a>
|
|
is present unless the <code>select</code>, <code>level</code>,
|
|
<code>count</code>, and <code>from</code> attributes are all
|
|
absent.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE1015"><span class="error">ERR
|
|
XTSE1015</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if an <a href=
|
|
"#element-sort"><code>xsl:sort</code></a> element with a
|
|
<code>select</code> attribute has non-empty content.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE1017"><span class="error">ERR
|
|
XTSE1017</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if an <a href=
|
|
"#element-sort"><code>xsl:sort</code></a> element other than the
|
|
first in a sequence of sibling <a href=
|
|
"#element-sort"><code>xsl:sort</code></a> elements has a
|
|
<code>stable</code> attribute.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE1040"><span class="error">ERR
|
|
XTSE1040</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if an <a href=
|
|
"#element-perform-sort"><code>xsl:perform-sort</code></a>
|
|
instruction with a <code>select</code> attribute has any content
|
|
other than <a href="#element-sort"><code>xsl:sort</code></a> and
|
|
<a href="#element-fallback"><code>xsl:fallback</code></a>
|
|
instructions.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE1060"><span class="error">ERR
|
|
XTSE1060</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if the <a href=
|
|
"#function-current-group"><code>current-group</code></a> function
|
|
is used within a <a title="pattern" class="termref" href=
|
|
"#dt-pattern">pattern</a>.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE1070"><span class="error">ERR
|
|
XTSE1070</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if the <a href=
|
|
"#function-current-grouping-key"><code>current-grouping-key</code></a>
|
|
function is used within a <a title="pattern" class="termref" href=
|
|
"#dt-pattern">pattern</a>.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE1080"><span class="error">ERR
|
|
XTSE1080</span></a></dt>
|
|
<dd>
|
|
<p>These four attributes [the <code>group-by</code>,
|
|
<code>group-adjacent</code>, <code>group-starting-with</code>, and
|
|
<code>group-ending-with</code> attributes of <a href=
|
|
"#element-for-each-group"><code>xsl:for-each-group</code></a> ] are
|
|
mutually exclusive: it is a <a title="static error" class="termref"
|
|
href="#dt-static-error">static error</a> if none of these four
|
|
attributes is present or if more than one of them is present.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE1090"><span class="error">ERR
|
|
XTSE1090</span></a></dt>
|
|
<dd>
|
|
<p>It is an error to specify the <code>collation</code> attribute
|
|
if neither the <code>group-by</code> attribute nor
|
|
<code>group-adjacent</code> attribute is specified.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE2185"><span class="error">ERR
|
|
XTSE2185</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if two sibling <a href=
|
|
"#element-merge-source"><code>xsl:merge-source</code></a> elements
|
|
have <code>name</code> attributes whose value is the same expanded
|
|
QName.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE2190"><span class="error">ERR
|
|
XTSE2190</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if an <a href=
|
|
"#element-merge-key"><code>xsl:merge-key</code></a> element with a
|
|
<code>select</code> attribute has non-empty content.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE2200"><span class="error">ERR
|
|
XTSE2200</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if the number of <a href=
|
|
"#element-merge-key"><code>xsl:merge-key</code></a> grandchildren
|
|
of a <a href=
|
|
"#element-merge-source"><code>xsl:merge-source</code></a> element
|
|
is not equal to the number of <a href=
|
|
"#element-merge-key"><code>xsl:merge-key</code></a> grandchildren
|
|
of another <a href=
|
|
"#element-merge-source"><code>xsl:merge-source</code></a> child of
|
|
the same <a href="#element-merge"><code>xsl:merge</code></a>
|
|
instruction.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE2210"><span class="error">ERR
|
|
XTSE2210</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if there are two <a href=
|
|
"#element-merge-key"><code>xsl:merge-key</code></a> grandchildren
|
|
of an <a href="#element-merge"><code>xsl:merge</code></a>
|
|
instruction that occupy corresponding positions among the <a href=
|
|
"#element-merge-key"><code>xsl:merge-key</code></a> children of two
|
|
different <a href=
|
|
"#element-merge-input"><code>xsl:merge-input</code></a> elements
|
|
and that have differing <a title="effective value" class="termref"
|
|
href="#dt-effective-value">effective values</a> for any of the
|
|
attributes <code>lang</code>, <code>order</code>,
|
|
<code>collation</code>, <code>case-order</code>, or
|
|
<code>data-type</code>. Values are considered to differ if the
|
|
attribute is present on one element and not on the other, or if it
|
|
is present on both elements with <a title="effective value" class=
|
|
"termref" href="#dt-effective-value">effective values</a> that are
|
|
not equal to each other. In the case of the <code>collation</code>
|
|
attribute, the values are compared as absolute URIs after resolving
|
|
against the base URI.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTDE2220"><span class="error">ERR
|
|
XTDE2220</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="dynamic error" class="termref" href=
|
|
"#dt-dynamic-error">dynamic error</a> if any input sequence to an
|
|
<a href="#element-merge"><code>xsl:merge</code></a> instruction
|
|
contains two items that are not correctly sorted according to the
|
|
merge key values defined on the <a href=
|
|
"#element-merge-key"><code>xsl:merge-key</code></a> children of the
|
|
corresponding <a href=
|
|
"#element-merge-input"><code>xsl:merge-input</code></a> element,
|
|
when compared using the collation rules defined by the attributes
|
|
of the corresponding <a href=
|
|
"#element-merge-key"><code>xsl:merge-key</code></a> children of the
|
|
<a href="#element-merge"><code>xsl:merge</code></a>
|
|
instruction.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTTE2230"><span class="error">ERR
|
|
XTTE2230</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="type errors" class="termref" href=
|
|
"#dt-type-error">type error</a> if some item selected by a
|
|
particular merge key in one input sequence is not comparable using
|
|
the XPath <code>le</code> operator with some item selected by the
|
|
corresponding sort key in another input sequence.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE1130"><span class="error">ERR
|
|
XTSE1130</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if the <a href=
|
|
"#element-analyze-string"><code>xsl:analyze-string</code></a>
|
|
instruction contains neither an <a href=
|
|
"#element-matching-substring"><code>xsl:matching-substring</code></a>
|
|
nor an <a href=
|
|
"#element-non-matching-substring"><code>xsl:non-matching-substring</code></a>
|
|
element.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE1205"><span class="error">ERR
|
|
XTSE1205</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if an <a href=
|
|
"#element-key"><code>xsl:key</code></a> declaration has a
|
|
<code>use</code> attribute and has non-empty content, or if it has
|
|
empty content and no <code>use</code> attribute.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE1210"><span class="error">ERR
|
|
XTSE1210</span></a></dt>
|
|
<dd>
|
|
<p>It is a static error if the <a href=
|
|
"#element-key"><code>xsl:key</code></a> declaration has a
|
|
<code>collation</code> attribute whose value (after resolving
|
|
against the base URI) is not a URI recognized by the implementation
|
|
as referring to a collation.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE1220"><span class="error">ERR
|
|
XTSE1220</span></a></dt>
|
|
<dd>
|
|
<p>It is a static error if there are several <a href=
|
|
"#element-key"><code>xsl:key</code></a> declarations in the
|
|
<a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a> with the same key name and
|
|
different effective collations. Two collations are the same if
|
|
their URIs are equal under the rules for comparing
|
|
<code>xs:anyURI</code> values, or if the implementation can
|
|
determine that they are different URIs referring to the same
|
|
collation.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE1290"><span class="error">ERR
|
|
XTSE1290</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if a named or unnamed <a title=
|
|
"decimal format" class="termref" href="#dt-decimal-format">decimal
|
|
format</a> contains two conflicting values for the same attribute
|
|
in different <a href=
|
|
"#element-decimal-format"><code>xsl:decimal-format</code></a>
|
|
declarations having the same <a title="import precedence" class=
|
|
"termref" href="#dt-import-precedence">import precedence</a>,
|
|
unless there is another definition of the same attribute with
|
|
higher import precedence.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE1295"><span class="error">ERR
|
|
XTSE1295</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if the character specified in
|
|
the <code>zero-digit</code> attribute is not a digit or is a digit
|
|
that does not have the numeric value zero.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE1300"><span class="error">ERR
|
|
XTSE1300</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if, for any named or unnamed
|
|
decimal format, the variables representing characters used in a
|
|
<a title="picture string" class="termref" href=
|
|
"#dt-picture-string">picture string</a> do not each have distinct
|
|
values. These variables are <var>decimal-separator-sign</var>,
|
|
<var>grouping-sign</var>, <var>percent-sign</var>,
|
|
<var>per-mille-sign</var>, <var>digit-zero-sign</var>,
|
|
<var>digit-sign</var>, and <var>pattern-separator-sign</var>.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE1430"><span class="error">ERR
|
|
XTSE1430</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if there is no namespace bound
|
|
to the prefix on the element bearing the
|
|
<code>[xsl:]extension-element-prefixes</code> attribute or, when
|
|
<code>#default</code> is specified, if there is no default
|
|
namespace.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE1505"><span class="error">ERR
|
|
XTSE1505</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if both the
|
|
<code>[xsl:]type</code> and <code>[xsl:]validation</code>
|
|
attributes are present on the <a href=
|
|
"#element-element"><code>xsl:element</code></a>, <a href=
|
|
"#element-attribute"><code>xsl:attribute</code></a>, <a href=
|
|
"#element-copy"><code>xsl:copy</code></a>, <a href=
|
|
"#element-copy-of"><code>xsl:copy-of</code></a>, <a href=
|
|
"#element-document"><code>xsl:document</code></a>, or <a href=
|
|
"#element-result-document"><code>xsl:result-document</code></a>
|
|
instructions, or on a <a title="literal result element" class=
|
|
"termref" href="#dt-literal-result-element">literal result
|
|
element</a>.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE1520"><span class="error">ERR
|
|
XTSE1520</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if the value of the
|
|
<code>type</code> attribute of an <a href=
|
|
"#element-element"><code>xsl:element</code></a>, <a href=
|
|
"#element-attribute"><code>xsl:attribute</code></a>, <a href=
|
|
"#element-copy"><code>xsl:copy</code></a>, <a href=
|
|
"#element-copy-of"><code>xsl:copy-of</code></a>, <a href=
|
|
"#element-document"><code>xsl:document</code></a>, or <a href=
|
|
"#element-result-document"><code>xsl:result-document</code></a>
|
|
instruction, or the <code>xsl:type</code> attribute of a literal
|
|
result element, is not a valid <code>QName</code>, or if it uses a
|
|
prefix that is not defined in an in-scope namespace declaration, or
|
|
if the QName is not the name of a type definition included in the
|
|
<a title="in-scope schema component" class="termref" href=
|
|
"#dt-in-scope-schema-component">in-scope schema components</a> for
|
|
the stylesheet.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE1530"><span class="error">ERR
|
|
XTSE1530</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if the value of the
|
|
<code>type</code> attribute of an <a href=
|
|
"#element-attribute"><code>xsl:attribute</code></a> instruction
|
|
refers to a complex type definition</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE1560"><span class="error">ERR
|
|
XTSE1560</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if two <a href=
|
|
"#element-output"><code>xsl:output</code></a> declarations within
|
|
an <a title="output definition" class="termref" href=
|
|
"#dt-output-definition">output definition</a> specify explicit
|
|
values for the same attribute (other than
|
|
<code>cdata-section-elements</code> and
|
|
<code>use-character-maps</code>), with the values of the attributes
|
|
being not equal, unless there is another <a href=
|
|
"#element-output"><code>xsl:output</code></a> declaration within
|
|
the same <a title="output definition" class="termref" href=
|
|
"#dt-output-definition">output definition</a> that has higher
|
|
import precedence and that specifies an explicit value for the same
|
|
attribute.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE1570"><span class="error">ERR
|
|
XTSE1570</span></a></dt>
|
|
<dd>
|
|
<p>The value [of the <code>method</code> attribute on <a href=
|
|
"#element-output"><code>xsl:output</code></a> ] <span class=
|
|
"verb">must</span> (if present) be a valid <a title="QName" class=
|
|
"termref" href="#dt-qname">QName</a>. If the <a title="QName"
|
|
class="termref" href="#dt-qname">QName</a> does not have a prefix,
|
|
then it identifies a method specified in <a href=
|
|
"#xslt-xquery-serialization-11">[XSLT and XQuery Serialization]</a>
|
|
and <span class="verb">must</span> be one of <code>xml</code>,
|
|
<code>html</code>, <code>xhtml</code>, or <code>text</code>.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE1580"><span class="error">ERR
|
|
XTSE1580</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if the <a title="stylesheet"
|
|
class="termref" href="#dt-stylesheet">stylesheet</a> contains two
|
|
or more character maps with the same name and the same <a title=
|
|
"import precedence" class="termref" href=
|
|
"#dt-import-precedence">import precedence</a>, unless it also
|
|
contains another character map with the same name and higher import
|
|
precedence.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE1590"><span class="error">ERR
|
|
XTSE1590</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if a name in the
|
|
<code>use-character-maps</code> attribute of the <a href=
|
|
"#element-output"><code>xsl:output</code></a> or <a href=
|
|
"#element-character-map"><code>xsl:character-map</code></a>
|
|
elements does not match the <code>name</code> attribute of any
|
|
<a href="#element-character-map"><code>xsl:character-map</code></a>
|
|
in the <a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a>.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE1600"><span class="error">ERR
|
|
XTSE1600</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a> if a character map references
|
|
itself, directly or indirectly, via a name in the
|
|
<code>use-character-maps</code> attribute.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE1650"><span class="error">ERR
|
|
XTSE1650</span></a></dt>
|
|
<dd>
|
|
<p>A <a title="basic XSLT processor" class="termref" href=
|
|
"#dt-basic-xslt-processor">basic XSLT processor</a> <span class=
|
|
"verb">must</span> signal a <a title="static error" class="termref"
|
|
href="#dt-static-error">static error</a> if the <a title=
|
|
"stylesheet" class="termref" href="#dt-stylesheet">stylesheet</a>
|
|
includes an <a href=
|
|
"#element-import-schema"><code>xsl:import-schema</code></a>
|
|
declaration.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTSE1660"><span class="error">ERR
|
|
XTSE1660</span></a></dt>
|
|
<dd>
|
|
<p>A <a title="basic XSLT processor" class="termref" href=
|
|
"#dt-basic-xslt-processor">basic XSLT processor</a> <span class=
|
|
"verb">must</span> signal a <a title="static error" class="termref"
|
|
href="#dt-static-error">static error</a> if the <a title=
|
|
"stylesheet" class="termref" href="#dt-stylesheet">stylesheet</a>
|
|
includes an <code>[xsl:]type</code> attribute, or an
|
|
<code>[xsl:]validation</code> or <code>default-validation</code>
|
|
attribute with a value other than <code>strip</code><span>,
|
|
<code>preserve</code>, or <code>lax</code></span>.</p>
|
|
</dd>
|
|
</dl>
|
|
<p><b>Type errors</b></p>
|
|
<dl>
|
|
<dt><a href="#err-XTTE0505"><span class="error">ERR
|
|
XTTE0505</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="type errors" class="termref" href=
|
|
"#dt-type-error">type error</a> if the result of evaluating the
|
|
<a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> cannot be
|
|
converted to the required type.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTTE0510"><span class="error">ERR
|
|
XTTE0510</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="type errors" class="termref" href=
|
|
"#dt-type-error">type error</a> if an <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>
|
|
instruction with no <code>select</code> attribute is evaluated when
|
|
the <a title="context item" class="termref" href=
|
|
"#dt-context-item">context item</a> is not a node.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTTE0570"><span class="error">ERR
|
|
XTTE0570</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="type errors" class="termref" href=
|
|
"#dt-type-error">type error</a> if the <a title="supplied value"
|
|
class="termref" href="#dt-supplied-value">supplied value</a> of a
|
|
variable cannot be converted to the required type.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTTE0590"><span class="error">ERR
|
|
XTTE0590</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="type errors" class="termref" href=
|
|
"#dt-type-error">type error</a> if the conversion of the <a title=
|
|
"supplied value" class="termref" href="#dt-supplied-value">supplied
|
|
value</a> of a parameter to its required type fails.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTTE0600"><span class="error">ERR
|
|
XTTE0600</span></a></dt>
|
|
<dd>
|
|
<p>If a default value is given explicitly, that is, if there is
|
|
either a <code>select</code> attribute or a non-empty <a title=
|
|
"sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a>, then it is a
|
|
<a title="type errors" class="termref" href="#dt-type-error">type
|
|
error</a> if the default value cannot be converted to the required
|
|
type, using the <a title="function conversion rules" class=
|
|
"termref" href="#dt-function-conversion-rules">function conversion
|
|
rules</a>.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTTE0780"><span class="error">ERR
|
|
XTTE0780</span></a></dt>
|
|
<dd>
|
|
<p>If the <code>as</code> attribute [of <a href=
|
|
"#element-function"><code>xsl:function</code></a> ] is specified,
|
|
then the result evaluated by the <a title="sequence constructor"
|
|
class="termref" href="#dt-sequence-constructor">sequence
|
|
constructor</a> (see <a href="#sequence-constructors"><i>5.7
|
|
Sequence Constructors</i></a>) is converted to the required type,
|
|
using the <a title="function conversion rules" class="termref"
|
|
href="#dt-function-conversion-rules">function conversion rules</a>.
|
|
It is a <a title="type errors" class="termref" href=
|
|
"#dt-type-error">type error</a> if this conversion fails.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTTE0790"><span class="error">ERR
|
|
XTTE0790</span></a></dt>
|
|
<dd>
|
|
<p>If the value of a parameter to a <a title="stylesheet function"
|
|
class="termref" href="#dt-stylesheet-function">stylesheet
|
|
function</a> cannot be converted to the required type, a <a title=
|
|
"type errors" class="termref" href="#dt-type-error">type error</a>
|
|
is signaled.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTTE2160"><span class="error">ERR
|
|
XTTE2160</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="type errors" class="termref" href=
|
|
"#dt-type-error">type error</a> if the result of evaluating the
|
|
<code>namespace-context</code> attribute of the <a href=
|
|
"#element-evaluate"><code>xsl:evaluate</code></a> instruction is
|
|
anything other than a single node.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTTE2170"><span class="error">ERR
|
|
XTTE2170</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="type errors" class="termref" href=
|
|
"#dt-type-error">type error</a> if the result of evaluating the
|
|
<code>select</code> expression [of the <a href=
|
|
"#element-copy"><code>xsl:copy</code></a> element] is a sequence of
|
|
more than one item.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTTE0990"><span class="error">ERR
|
|
XTTE0990</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="type errors" class="termref" href=
|
|
"#dt-type-error">type error</a> if the <a href=
|
|
"#element-number"><code>xsl:number</code></a> instruction is
|
|
evaluated, with no <code>value</code> or <code>select</code>
|
|
attribute, when the <a title="context item" class="termref" href=
|
|
"#dt-context-item">context item</a> is not a node.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTTE1000"><span class="error">ERR
|
|
XTTE1000</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="type errors" class="termref" href=
|
|
"#dt-type-error">type error</a> if the result of evaluating the
|
|
<code>select</code> attribute of the <a href=
|
|
"#element-number"><code>xsl:number</code></a> instruction is
|
|
anything other than a single node.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTTE1020"><span class="error">ERR
|
|
XTTE1020</span></a></dt>
|
|
<dd>
|
|
<p>If any <a title="sort key value" class="termref" href=
|
|
"#dt-sort-key-value">sort key value</a>, after <a title="atomize"
|
|
class="termref" href="#dt-atomization">atomization</a> and any type
|
|
conversion <span class="verb">required</span> by the
|
|
<code>data-type</code> attribute, is a sequence containing more
|
|
than one item, then the effect depends on whether the <a href=
|
|
"#element-sort"><code>xsl:sort</code></a> element <span>is
|
|
processed with <a title="XSLT 1.0 behavior" class="termref" href=
|
|
"#dt-xslt-10-behavior">XSLT 1.0 behavior</a>. With XSLT 1.0
|
|
behavior,</span> the effective sort key value is the first item in
|
|
the sequence. In other cases, this is a <a title="type errors"
|
|
class="termref" href="#dt-type-error">type error</a>.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTTE1100"><span class="error">ERR
|
|
XTTE1100</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="type errors" class="termref" href=
|
|
"#dt-type-error">type error</a> if the result of evaluating the
|
|
<code>group-adjacent</code> expression is an empty sequence or a
|
|
sequence containing more than one item.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTTE1510"><span class="error">ERR
|
|
XTTE1510</span></a></dt>
|
|
<dd>
|
|
<p>If the <code>validation</code> attribute of an <a href=
|
|
"#element-element"><code>xsl:element</code></a>, <a href=
|
|
"#element-attribute"><code>xsl:attribute</code></a>, <a href=
|
|
"#element-copy"><code>xsl:copy</code></a>, <a href=
|
|
"#element-copy-of"><code>xsl:copy-of</code></a>, or <a href=
|
|
"#element-result-document"><code>xsl:result-document</code></a>
|
|
instruction, or the <code>xsl:validation</code> attribute of a
|
|
literal result element, has the effective value
|
|
<code>strict</code>, and schema validity assessment concludes that
|
|
the validity of the element or attribute is invalid or unknown, a
|
|
type error occurs. As with other type errors, the error
|
|
<span class="verb">may</span> be signaled statically if it can be
|
|
detected statically.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTTE1512"><span class="error">ERR
|
|
XTTE1512</span></a></dt>
|
|
<dd>
|
|
<p>If the <code>validation</code> attribute of an <a href=
|
|
"#element-element"><code>xsl:element</code></a>, <a href=
|
|
"#element-attribute"><code>xsl:attribute</code></a>, <a href=
|
|
"#element-copy"><code>xsl:copy</code></a>, <a href=
|
|
"#element-copy-of"><code>xsl:copy-of</code></a>, or <a href=
|
|
"#element-result-document"><code>xsl:result-document</code></a>
|
|
instruction, or the <code>xsl:validation</code> attribute of a
|
|
literal result element, has the effective value
|
|
<code>strict</code>, and there is no matching top-level declaration
|
|
in the schema, then a type error occurs. As with other type errors,
|
|
the error <span class="verb">may</span> be signaled statically if
|
|
it can be detected statically.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTTE1515"><span class="error">ERR
|
|
XTTE1515</span></a></dt>
|
|
<dd>
|
|
<p>If the <code>validation</code> attribute of an <a href=
|
|
"#element-element"><code>xsl:element</code></a>, <a href=
|
|
"#element-attribute"><code>xsl:attribute</code></a>, <a href=
|
|
"#element-copy"><code>xsl:copy</code></a>, <a href=
|
|
"#element-copy-of"><code>xsl:copy-of</code></a>, or <a href=
|
|
"#element-result-document"><code>xsl:result-document</code></a>
|
|
instruction, or the <code>xsl:validation</code> attribute of a
|
|
literal result element, has the effective value <code>lax</code>,
|
|
and schema validity assessment concludes that the element or
|
|
attribute is invalid, a type error occurs. As with other type
|
|
errors, the error <span class="verb">may</span> be signaled
|
|
statically if it can be detected statically.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTTE1540"><span class="error">ERR
|
|
XTTE1540</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="type errors" class="termref" href=
|
|
"#dt-type-error">type error</a> if an <code>[xsl:]type</code>
|
|
attribute is defined for a constructed element or attribute, and
|
|
the outcome of schema validity assessment against that type is that
|
|
the <code>validity</code> property of that element or attribute
|
|
information item is other than <code>valid</code>.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTTE1545"><span class="error">ERR
|
|
XTTE1545</span></a></dt>
|
|
<dd>
|
|
<p>A <a title="type errors" class="termref" href=
|
|
"#dt-type-error">type error</a> occurs if a <code>type</code> or
|
|
<code>validation</code> attribute is defined (explicitly or
|
|
implicitly) for an instruction that constructs a new attribute
|
|
node, if the effect of this is to cause the attribute value to be
|
|
validated against a type that is derived from, or constructed by
|
|
list or union from, the primitive types <code>xs:QName</code> or
|
|
<code>xs:NOTATION</code>.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTTE1550"><span class="error">ERR
|
|
XTTE1550</span></a></dt>
|
|
<dd>
|
|
<p>A <a title="type errors" class="termref" href=
|
|
"#dt-type-error">type error</a> occurs [when a document node is
|
|
validated] unless the children of the document node comprise
|
|
exactly one element node, no text nodes, and zero or more comment
|
|
and processing instruction nodes, in any order.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTTE1555"><span class="error">ERR
|
|
XTTE1555</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="type errors" class="termref" href=
|
|
"#dt-type-error">type error</a> if, when validating a document
|
|
node, document-level constraints are not satisfied. These
|
|
constraints include identity constraints (<code>xs:unique</code>,
|
|
<code>xs:key</code>, and <code>xs:keyref</code>) and ID/IDREF
|
|
constraints.</p>
|
|
</dd>
|
|
</dl>
|
|
<p><b>Dynamic errors</b></p>
|
|
<dl>
|
|
<dt><a href="#err-XTDE0030"><span class="error">ERR
|
|
XTDE0030</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="non-recoverable dynamic error" class="termref"
|
|
href="#dt-nonrec-dynamic-error">non-recoverable dynamic error</a>
|
|
if the <a title="effective value" class="termref" href=
|
|
"#dt-effective-value">effective value</a> of an attribute written
|
|
using curly brackets, in a position where an <a title=
|
|
"attribute value template" class="termref" href=
|
|
"#dt-attribute-value-template">attribute value template</a> is
|
|
permitted, is a value that is not one of the permitted values for
|
|
that attribute. If the processor is able to detect the error
|
|
statically (for example, when any XPath expressions within the
|
|
curly brackets can be evaluated statically), then the processor may
|
|
optionally signal this as a static error.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTDE0040"><span class="error">ERR
|
|
XTDE0040</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="non-recoverable dynamic error" class="termref"
|
|
href="#dt-nonrec-dynamic-error">non-recoverable dynamic error</a>
|
|
if the invocation of the <a title="stylesheet" class="termref"
|
|
href="#dt-stylesheet">stylesheet</a> specifies a template name that
|
|
does not match the <a title="expanded-QName" class="termref" href=
|
|
"#dt-expanded-qname">expanded-QName</a> of a named template defined
|
|
in the <a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a>.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTDE0045"><span class="error">ERR
|
|
XTDE0045</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="non-recoverable dynamic error" class="termref"
|
|
href="#dt-nonrec-dynamic-error">non-recoverable dynamic error</a>
|
|
if the invocation of the <a title="stylesheet" class="termref"
|
|
href="#dt-stylesheet">stylesheet</a> specifies an initial <a title=
|
|
"mode" class="termref" href="#dt-mode">mode</a> (other than the
|
|
default mode) that does not match the <a title="expanded-QName"
|
|
class="termref" href="#dt-expanded-qname">expanded-QName</a> in the
|
|
<code>mode</code> attribute of any template defined in the
|
|
<a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a>.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTDE0047"><span class="error">ERR
|
|
XTDE0047</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="non-recoverable dynamic error" class="termref"
|
|
href="#dt-nonrec-dynamic-error">non-recoverable dynamic error</a>
|
|
if the invocation of the <a title="stylesheet" class="termref"
|
|
href="#dt-stylesheet">stylesheet</a> specifies both an initial
|
|
<a title="mode" class="termref" href="#dt-mode">mode</a> and an
|
|
initial template.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTDE0050"><span class="error">ERR
|
|
XTDE0050</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="non-recoverable dynamic error" class="termref"
|
|
href="#dt-nonrec-dynamic-error">non-recoverable dynamic error</a>
|
|
if the stylesheet that is invoked declares a visible <a title=
|
|
"stylesheet parameter" class="termref" href=
|
|
"#dt-stylesheet-parameter">stylesheet parameter</a> with
|
|
<code>required="yes"</code> and no value for this parameter is
|
|
supplied during the invocation of the stylesheet. A stylesheet
|
|
parameter is visible if it is not masked by another global variable
|
|
or parameter with the same name and higher <a title=
|
|
"import precedence" class="termref" href=
|
|
"#dt-import-precedence">import precedence</a>.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTDE0060"><span class="error">ERR
|
|
XTDE0060</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="non-recoverable dynamic error" class="termref"
|
|
href="#dt-nonrec-dynamic-error">non-recoverable dynamic error</a>
|
|
if the <a title="initial template" class="termref" href=
|
|
"#dt-initial-template">initial template</a> defines a <a title=
|
|
"template parameter" class="termref" href=
|
|
"#dt-template-parameter">template parameter</a> that specifies
|
|
<code>required="yes"</code>.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTDE0160"><span class="error">ERR
|
|
XTDE0160</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="non-recoverable dynamic error" class="termref"
|
|
href="#dt-nonrec-dynamic-error">non-recoverable dynamic error</a>
|
|
if an element has an <a title="effective version" class="termref"
|
|
href="#dt-effective-version">effective version</a> of <var>V</var>
|
|
(with <var>V</var> < 2.1) when the implementation does not
|
|
support backwards compatible behavior for XSLT version
|
|
<var>V</var>.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTRE0270"><span class="error">ERR
|
|
XTRE0270</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="recoverable error" class="termref" href=
|
|
"#dt-recoverable-error">recoverable dynamic error</a> if this [the
|
|
process of finding an <a href=
|
|
"#element-strip-space"><code>xsl:strip-space</code></a> or <a href=
|
|
"#element-preserve-space"><code>xsl:preserve-space</code></a>
|
|
declaration to match an element in the source document] leaves more
|
|
than one match, unless all the matched declarations are equivalent
|
|
(that is, they are all <a href=
|
|
"#element-strip-space"><code>xsl:strip-space</code></a> or they are
|
|
all <a href=
|
|
"#element-preserve-space"><code>xsl:preserve-space</code></a>).<br />
|
|
|
|
<i>    Action:</i> The <a title=
|
|
"optional recovery action" class="termref" href=
|
|
"#dt-optional-recovery-action">optional recovery action</a> is to
|
|
select, from the matches that are left, the one that occurs last in
|
|
<a title="declaration order" class="termref" href=
|
|
"#dt-declaration-order">declaration order</a>.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTDE0290"><span class="error">ERR
|
|
XTDE0290</span></a></dt>
|
|
<dd>
|
|
<p>Where the result of evaluating an XPath expression (or an
|
|
attribute value template) is required to be a <a title=
|
|
"lexical QName" class="termref" href="#dt-lexical-qname">lexical
|
|
QName</a>, then unless otherwise specified it is a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> if the
|
|
<a title="defining element" class="termref" href=
|
|
"#dt-defining-element">defining element</a> has no namespace node
|
|
whose name matches the prefix of the <a title="lexical QName"
|
|
class="termref" href="#dt-lexical-qname">lexical QName</a>. This
|
|
error <span class="verb">may</span> be signaled as a <a title=
|
|
"static error" class="termref" href="#dt-static-error">static
|
|
error</a> if the value of the expression can be determined
|
|
statically.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTDE0410"><span class="error">ERR
|
|
XTDE0410</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="non-recoverable dynamic error" class="termref"
|
|
href="#dt-nonrec-dynamic-error">non-recoverable dynamic error</a>
|
|
if the result sequence used to construct the content of an element
|
|
node contains a namespace node or attribute node that is preceded
|
|
in the sequence by a node that is neither a namespace node nor an
|
|
attribute node.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTDE0420"><span class="error">ERR
|
|
XTDE0420</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="non-recoverable dynamic error" class="termref"
|
|
href="#dt-nonrec-dynamic-error">non-recoverable dynamic error</a>
|
|
if the result sequence used to construct the content of a document
|
|
node contains a namespace node or attribute node.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTDE0430"><span class="error">ERR
|
|
XTDE0430</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="non-recoverable dynamic error" class="termref"
|
|
href="#dt-nonrec-dynamic-error">non-recoverable dynamic error</a>
|
|
if the result sequence contains two or more namespace nodes having
|
|
the same name but different <a title="string value" class="termref"
|
|
href="#dt-string-value">string values</a> (that is, namespace nodes
|
|
that map the same prefix to different namespace URIs).</p>
|
|
</dd>
|
|
<dt><a href="#err-XTDE0440"><span class="error">ERR
|
|
XTDE0440</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="non-recoverable dynamic error" class="termref"
|
|
href="#dt-nonrec-dynamic-error">non-recoverable dynamic error</a>
|
|
if the result sequence contains a namespace node with no name and
|
|
the element node being constructed has a null namespace URI (that
|
|
is, it is an error to define a default namespace when the element
|
|
is in no namespace).</p>
|
|
</dd>
|
|
<dt><a href="#err-XTDE0450"><span class="error">ERR
|
|
XTDE0450</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="non-recoverable dynamic error" class="termref"
|
|
href="#dt-nonrec-dynamic-error">non-recoverable dynamic error</a>
|
|
if the result sequence contains a function item.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTRE0540"><span class="error">ERR
|
|
XTRE0540</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="non-recoverable dynamic error" class="termref"
|
|
href="#dt-nonrec-dynamic-error">non-recoverable dynamic error</a>
|
|
if the conflict resolution algorithm for template rules leaves more
|
|
than one matching template rule <span>when the declaration of the
|
|
relevant <a title="mode" class="termref" href="#dt-mode">mode</a>
|
|
has in <code>on-multiple-match</code> attribute with the value
|
|
<code>fail</code></span>.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTDE0555"><span class="error">ERR
|
|
XTDE0555</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="non-recoverable dynamic error" class="termref"
|
|
href="#dt-nonrec-dynamic-error">non-recoverable dynamic error</a>
|
|
if <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>,
|
|
<a href="#element-apply-imports"><code>xsl:apply-imports</code></a>
|
|
or <a href="#element-next-match"><code>xsl:next-match</code></a> is
|
|
used to process a node using a mode whose declaration specifies
|
|
<code>on-no-match="fail"</code> when there is no <a title=
|
|
"template rule" class="termref" href="#dt-template-rule">template
|
|
rule</a> in the <a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a> whose match pattern matches that
|
|
node.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTDE0560"><span class="error">ERR
|
|
XTDE0560</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="non-recoverable dynamic error" class="termref"
|
|
href="#dt-nonrec-dynamic-error">non-recoverable dynamic error</a>
|
|
if <a href=
|
|
"#element-apply-imports"><code>xsl:apply-imports</code></a> or
|
|
<a href="#element-next-match"><code>xsl:next-match</code></a> is
|
|
evaluated when the <a title="current template rule" class="termref"
|
|
href="#dt-current-template-rule">current template rule</a> is
|
|
null.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTDE0700"><span class="error">ERR
|
|
XTDE0700</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="non-recoverable dynamic error" class="termref"
|
|
href="#dt-nonrec-dynamic-error">non-recoverable dynamic error</a>
|
|
if a template that is invoked using <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>,
|
|
<a href=
|
|
"#element-apply-imports"><code>xsl:apply-imports</code></a>, or
|
|
<a href="#element-next-match"><code>xsl:next-match</code></a>
|
|
declares a <a title="template parameter" class="termref" href=
|
|
"#dt-template-parameter">template parameter</a> with
|
|
<code>required="yes"</code> and no value for this parameter is
|
|
supplied by the calling instruction. The same error is reported in
|
|
the case of a <a title="tunnel parameter" class="termref" href=
|
|
"#dt-tunnel-parameter">tunnel parameter</a> whether invoked using
|
|
one of these three instructions or by <a href=
|
|
"#element-call-template"><code>xsl:call-template</code></a>, as
|
|
explained in <a href="#tunnel-params"><i>10.1.2 Tunnel
|
|
Parameters</i></a>.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTDE0610"><span class="error">ERR
|
|
XTDE0610</span></a></dt>
|
|
<dd>
|
|
<p>If an optional parameter has no <code>select</code> attribute
|
|
and has an empty <a title="sequence constructor" class="termref"
|
|
href="#dt-sequence-constructor">sequence constructor</a>, and if
|
|
there is an <code>as</code> attribute, then the default value of
|
|
the parameter is an empty sequence. If the empty sequence is not a
|
|
valid instance of the required type defined in the <code>as</code>
|
|
attribute, then the parameter is treated as a required parameter,
|
|
which means that it is a <a title="non-recoverable dynamic error"
|
|
class="termref" href="#dt-nonrec-dynamic-error">non-recoverable
|
|
dynamic error</a> if the caller supplies no value for the
|
|
parameter.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTDE0640"><span class="error">ERR
|
|
XTDE0640</span></a></dt>
|
|
<dd>
|
|
<p>In general, a <a title="circularity" class="termref" href=
|
|
"#dt-circularity">circularity</a> in a <a title="stylesheet" class=
|
|
"termref" href="#dt-stylesheet">stylesheet</a> is a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a>.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTDE2150"><span class="error">ERR
|
|
XTDE2150</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="non-recoverable dynamic error" class="termref"
|
|
href="#dt-nonrec-dynamic-error">non-recoverable dynamic error</a>
|
|
if the <a title="target expression" class="termref" href=
|
|
"#dt-target-expression">target expression</a> [of an <a href=
|
|
"#element-evaluate"><code>xsl:evaluate</code></a> instruction] is
|
|
not a legal XPath 2.1 expression (that is, if a static error occurs
|
|
when analyzing the string according to the rules of the XPath 2.1
|
|
specification).</p>
|
|
</dd>
|
|
<dt><a href="#err-XTRE0795"><span class="error">ERR
|
|
XTRE0795</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="recoverable error" class="termref" href=
|
|
"#dt-recoverable-error">recoverable dynamic error</a> if the name
|
|
of a constructed attribute is <code>xml:space</code> and the value
|
|
is not either <code>default</code> or <code>preserve</code>.<br />
|
|
<i>    Action:</i> The <a title=
|
|
"optional recovery action" class="termref" href=
|
|
"#dt-optional-recovery-action">optional recovery action</a> is to
|
|
construct the attribute with the value as requested.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTDE0820"><span class="error">ERR
|
|
XTDE0820</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="non-recoverable dynamic error" class="termref"
|
|
href="#dt-nonrec-dynamic-error">non-recoverable dynamic error</a>
|
|
if the <a title="effective value" class="termref" href=
|
|
"#dt-effective-value">effective value</a> of the <code>name</code>
|
|
attribute [of the <a href=
|
|
"#element-element"><code>xsl:element</code></a> instruction] is not
|
|
a <a title="lexical QName" class="termref" href=
|
|
"#dt-lexical-qname">lexical QName</a>.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTDE0830"><span class="error">ERR
|
|
XTDE0830</span></a></dt>
|
|
<dd>
|
|
<p>In the case of an <a href=
|
|
"#element-element"><code>xsl:element</code></a> instruction with no
|
|
<code>namespace</code> attribute, it is a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> if the
|
|
<a title="effective value" class="termref" href=
|
|
"#dt-effective-value">effective value</a> of the <code>name</code>
|
|
attribute is a <a title="QName" class="termref" href=
|
|
"#dt-qname">QName</a> whose prefix is not declared in an in-scope
|
|
namespace declaration for the <a href=
|
|
"#element-element"><code>xsl:element</code></a> instruction.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTDE0835"><span class="error">ERR
|
|
XTDE0835</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="non-recoverable dynamic error" class="termref"
|
|
href="#dt-nonrec-dynamic-error">non-recoverable dynamic error</a>
|
|
if the <a title="effective value" class="termref" href=
|
|
"#dt-effective-value">effective value</a> of the
|
|
<code>namespace</code> attribute [of the <a href=
|
|
"#element-element"><code>xsl:element</code></a> instruction] is not
|
|
in the lexical space of the <code>xs:anyURI</code> data type or if
|
|
it is the string <code>http://www.w3.org/2000/xmlns/</code>.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTDE0850"><span class="error">ERR
|
|
XTDE0850</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="non-recoverable dynamic error" class="termref"
|
|
href="#dt-nonrec-dynamic-error">non-recoverable dynamic error</a>
|
|
if the <a title="effective value" class="termref" href=
|
|
"#dt-effective-value">effective value</a> of the <code>name</code>
|
|
attribute [of an <a href=
|
|
"#element-attribute"><code>xsl:attribute</code></a> instruction] is
|
|
not a <a title="lexical QName" class="termref" href=
|
|
"#dt-lexical-qname">lexical QName</a>.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTDE0855"><span class="error">ERR
|
|
XTDE0855</span></a></dt>
|
|
<dd>
|
|
<p>In the case of an <a href=
|
|
"#element-attribute"><code>xsl:attribute</code></a> instruction
|
|
with no <code>namespace</code> attribute, it is a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> if the
|
|
<a title="effective value" class="termref" href=
|
|
"#dt-effective-value">effective value</a> of the <code>name</code>
|
|
attribute is the string <code>xmlns</code>.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTDE0860"><span class="error">ERR
|
|
XTDE0860</span></a></dt>
|
|
<dd>
|
|
<p>In the case of an <a href=
|
|
"#element-attribute"><code>xsl:attribute</code></a> instruction
|
|
with no <code>namespace</code> attribute, it is a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> if the
|
|
<a title="effective value" class="termref" href=
|
|
"#dt-effective-value">effective value</a> of the <code>name</code>
|
|
attribute is a <a title="lexical QName" class="termref" href=
|
|
"#dt-lexical-qname">lexical QName</a> whose prefix is not declared
|
|
in an in-scope namespace declaration for the <a href=
|
|
"#element-attribute"><code>xsl:attribute</code></a>
|
|
instruction.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTDE0865"><span class="error">ERR
|
|
XTDE0865</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="non-recoverable dynamic error" class="termref"
|
|
href="#dt-nonrec-dynamic-error">non-recoverable dynamic error</a>
|
|
if the <a title="effective value" class="termref" href=
|
|
"#dt-effective-value">effective value</a> of the
|
|
<code>namespace</code> attribute [of the <a href=
|
|
"#element-attribute"><code>xsl:attribute</code></a> instruction] is
|
|
not in the lexical space of the <code>xs:anyURI</code> data type or
|
|
if it is the string <code>http://www.w3.org/2000/xmlns/</code>.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTDE0890"><span class="error">ERR
|
|
XTDE0890</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="non-recoverable dynamic error" class="termref"
|
|
href="#dt-nonrec-dynamic-error">non-recoverable dynamic error</a>
|
|
if the <a title="effective value" class="termref" href=
|
|
"#dt-effective-value">effective value</a> of the <code>name</code>
|
|
attribute [of the <a href=
|
|
"#element-processing-instruction"><code>xsl:processing-instruction</code></a>
|
|
instruction] is not both an <a href=
|
|
"http://www.w3.org/TR/REC-xml-names/#NT-NCName">NCName</a><sup><small>Names</small></sup>
|
|
and a <a href=
|
|
"http://www.w3.org/TR/2000/REC-xml-20001006#NT-PITarget">PITarget</a><sup><small>XML</small></sup>.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTDE0905"><span class="error">ERR
|
|
XTDE0905</span></a></dt>
|
|
<dd>
|
|
<p>It is a non-recoverable dynamic error if the string value of the
|
|
new namespace node is not valid in the lexical space of the data
|
|
type <code>xs:anyURI</code>, or if it is the string
|
|
<code>http://www.w3.org/2000/xmlns/</code>.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTDE0920"><span class="error">ERR
|
|
XTDE0920</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="non-recoverable dynamic error" class="termref"
|
|
href="#dt-nonrec-dynamic-error">non-recoverable dynamic error</a>
|
|
if the <a title="effective value" class="termref" href=
|
|
"#dt-effective-value">effective value</a> of the <code>name</code>
|
|
attribute [of the <a href=
|
|
"#element-namespace"><code>xsl:namespace</code></a> instruction] is
|
|
neither a zero-length string nor an <a href=
|
|
"http://www.w3.org/TR/REC-xml-names/#NT-NCName">NCName</a><sup><small>Names</small></sup>,
|
|
or if it is <code>xmlns</code>.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTDE0925"><span class="error">ERR
|
|
XTDE0925</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="non-recoverable dynamic error" class="termref"
|
|
href="#dt-nonrec-dynamic-error">non-recoverable dynamic error</a>
|
|
if the <a href="#element-namespace"><code>xsl:namespace</code></a>
|
|
instruction generates a namespace node whose name is
|
|
<code>xml</code> and whose string value is not
|
|
<code>http://www.w3.org/XML/1998/namespace</code>, or a namespace
|
|
node whose string value is
|
|
<code>http://www.w3.org/XML/1998/namespace</code> and whose name is
|
|
not <code>xml</code>.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTDE0930"><span class="error">ERR
|
|
XTDE0930</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="non-recoverable dynamic error" class="termref"
|
|
href="#dt-nonrec-dynamic-error">non-recoverable dynamic error</a>
|
|
if evaluating the <code>select</code> attribute or the contained
|
|
<a title="sequence constructor" class="termref" href=
|
|
"#dt-sequence-constructor">sequence constructor</a> of an <a href=
|
|
"#element-namespace"><code>xsl:namespace</code></a> instruction
|
|
results in a zero-length string.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTDE0980"><span class="error">ERR
|
|
XTDE0980</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="non-recoverable dynamic error" class="termref"
|
|
href="#dt-nonrec-dynamic-error">non-recoverable dynamic error</a>
|
|
if any undiscarded item in the atomized sequence supplied as the
|
|
value of the <code>value</code> attribute of <a href=
|
|
"#element-number"><code>xsl:number</code></a> cannot be converted
|
|
to an integer, or if the resulting integer is less than 0
|
|
(zero).</p>
|
|
</dd>
|
|
<dt><a href="#err-XTDE1030"><span class="error">ERR
|
|
XTDE1030</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="non-recoverable dynamic error" class="termref"
|
|
href="#dt-nonrec-dynamic-error">non-recoverable dynamic error</a>
|
|
if, for any <a title="sort key component" class="termref" href=
|
|
"#dt-sort-key-component">sort key component</a>, the set of
|
|
<a title="sort key value" class="termref" href=
|
|
"#dt-sort-key-value">sort key values</a> evaluated for all the
|
|
items in the <a title="initial sequence" class="termref" href=
|
|
"#dt-initial-sequence">initial sequence</a>, after any type
|
|
conversion requested, contains a pair of ordinary values for which
|
|
the result of the XPath <code>lt</code> operator is an error.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTDE1035"><span class="error">ERR
|
|
XTDE1035</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="non-recoverable dynamic error" class="termref"
|
|
href="#dt-nonrec-dynamic-error">non-recoverable dynamic error</a>
|
|
if the <code>collation</code> attribute of <a href=
|
|
"#element-sort"><code>xsl:sort</code></a> (after resolving against
|
|
the base URI) is not a URI that is recognized by the implementation
|
|
as referring to a collation.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTDE1110"><span class="error">ERR
|
|
XTDE1110</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="non-recoverable dynamic error" class="termref"
|
|
href="#dt-nonrec-dynamic-error">non-recoverable dynamic error</a>
|
|
if the collation URI specified to <a href=
|
|
"#element-for-each-group"><code>xsl:for-each-group</code></a>
|
|
(after resolving against the base URI) is a collation that is not
|
|
recognized by the implementation. (For notes, <span class=
|
|
"error">[see <a href="#err-XTDE1035">ERR XTDE1035</a>]</span>.)</p>
|
|
</dd>
|
|
<dt><a href="#err-XTDE2240"><span class="error">ERR
|
|
XTDE2240</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="non-recoverable dynamic error" class="termref"
|
|
href="#dt-nonrec-dynamic-error">non-recoverable dynamic error</a>
|
|
if the value [of the first argument to the <a href=
|
|
"#function-current-merge-inputs"><code>current-merge-inputs</code></a>
|
|
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 <a href=
|
|
"#element-merge-source"><code>xsl:merge-source</code></a> element
|
|
in the <a title="current merge activation" class="termref" href=
|
|
"#dt-current-merge-activation">current merge activation</a>,
|
|
<span>or if there is no <a title="current merge activation" class=
|
|
"termref" href="#dt-current-merge-activation">current merge
|
|
activation</a></span>. If the processor is able to detect the error
|
|
statically (for example, when the argument is supplied as a string
|
|
literal), then the processor <span class="verb">may</span>
|
|
optionally signal this as a <a title="static error" class="termref"
|
|
href="#dt-static-error">static error</a>.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTDE1140"><span class="error">ERR
|
|
XTDE1140</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="non-recoverable dynamic error" class="termref"
|
|
href="#dt-nonrec-dynamic-error">non-recoverable dynamic error</a>
|
|
if the <a title="effective value" class="termref" href=
|
|
"#dt-effective-value">effective value</a> of the <code>regex</code>
|
|
attribute [of the <a href=
|
|
"#element-analyze-string"><code>xsl:analyze-string</code></a>
|
|
instruction] does not conform to the <span class=
|
|
"verb">required</span> syntax for regular expressions, as specified
|
|
in <a href="#xpath-functions-11">[Functions and Operators]</a>. If
|
|
the regular expression is known statically (for example, if the
|
|
attribute does not contain any <a title="expression" class=
|
|
"termref" href="#dt-expression">expressions</a> enclosed in curly
|
|
brackets) then the processor <span class="verb">may</span> signal
|
|
the error as a <a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a>.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTDE1145"><span class="error">ERR
|
|
XTDE1145</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="non-recoverable dynamic error" class="termref"
|
|
href="#dt-nonrec-dynamic-error">non-recoverable dynamic error</a>
|
|
if the <a title="effective value" class="termref" href=
|
|
"#dt-effective-value">effective value</a> of the <code>flags</code>
|
|
attribute [of the <a href=
|
|
"#element-analyze-string"><code>xsl:analyze-string</code></a>
|
|
instruction] has a value other than the values defined in <a href=
|
|
"#xpath-functions-11">[Functions and Operators]</a>. If the value
|
|
of the attribute is known statically (for example, if the attribute
|
|
does not contain any <a title="expression" class="termref" href=
|
|
"#dt-expression">expressions</a> enclosed in curly brackets) then
|
|
the processor <span class="verb">may</span> signal the error as a
|
|
<a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a>.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTDE1150"><span class="error">ERR
|
|
XTDE1150</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="non-recoverable dynamic error" class="termref"
|
|
href="#dt-nonrec-dynamic-error">non-recoverable dynamic error</a>
|
|
if the <a title="effective value" class="termref" href=
|
|
"#dt-effective-value">effective value</a> of the <code>regex</code>
|
|
attribute [of the <a href=
|
|
"#element-analyze-string"><code>xsl:analyze-string</code></a>
|
|
instruction] is a regular expression that matches a zero-length
|
|
string: or more specifically, if the regular expression
|
|
<code>$r</code> and flags <code>$f</code> are such that
|
|
<code>matches("", $r, $f)</code> returns true. If the regular
|
|
expression is known statically (for example, if the attribute does
|
|
not contain any <a title="expression" class="termref" href=
|
|
"#dt-expression">expressions</a> enclosed in curly brackets) then
|
|
the processor <span class="verb">may</span> signal the error as a
|
|
<a title="static error" class="termref" href=
|
|
"#dt-static-error">static error</a>.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTRE1160"><span class="error">ERR
|
|
XTRE1160</span></a></dt>
|
|
<dd>
|
|
<p>When a URI reference [supplied to the <a href=
|
|
"#function-document"><code>document</code></a> function] contains a
|
|
fragment identifier, it is a <a title="recoverable error" class=
|
|
"termref" href="#dt-recoverable-error">recoverable dynamic
|
|
error</a> if the media type is not one that is recognized by the
|
|
processor, or if the fragment identifier does not conform to the
|
|
rules for fragment identifiers for that media type, or if the
|
|
fragment identifier selects something other than a sequence of
|
|
nodes (for example, if it selects a range of characters within a
|
|
text node).<br />
|
|
<i>    Action:</i> The <a title=
|
|
"optional recovery action" class="termref" href=
|
|
"#dt-optional-recovery-action">optional recovery action</a> is to
|
|
ignore the fragment identifier and return the document node.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTDE1170"><span class="error">ERR
|
|
XTDE1170</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="non-recoverable dynamic error" class="termref"
|
|
href="#dt-nonrec-dynamic-error">non-recoverable dynamic error</a>
|
|
if a URI [supplied in the first argument to the <a href=
|
|
"#function-unparsed-text"><code>unparsed-text</code></a> function]
|
|
contains a fragment identifier, or if it cannot be used to retrieve
|
|
a resource containing text.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTDE1190"><span class="error">ERR
|
|
XTDE1190</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="non-recoverable dynamic error" class="termref"
|
|
href="#dt-nonrec-dynamic-error">non-recoverable dynamic error</a>
|
|
if a resource [retrieved using the <a href=
|
|
"#function-unparsed-text"><code>unparsed-text</code></a> function]
|
|
contains octets that cannot be decoded into Unicode characters
|
|
using the specified encoding, or if the resulting characters are
|
|
not permitted XML characters. This includes the case where the
|
|
<a title="processor" class="termref" href=
|
|
"#dt-processor">processor</a> does not support the requested
|
|
encoding.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTDE1200"><span class="error">ERR
|
|
XTDE1200</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="non-recoverable dynamic error" class="termref"
|
|
href="#dt-nonrec-dynamic-error">non-recoverable dynamic error</a>
|
|
if the second argument of the <a href=
|
|
"#function-unparsed-text"><code>unparsed-text</code></a> function
|
|
is omitted and the <a title="processor" class="termref" href=
|
|
"#dt-processor">processor</a> cannot infer the encoding using
|
|
external information and the encoding is not UTF-8.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTDE1260"><span class="error">ERR
|
|
XTDE1260</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="non-recoverable dynamic error" class="termref"
|
|
href="#dt-nonrec-dynamic-error">non-recoverable dynamic error</a>
|
|
if the value [of the first argument to the <a href=
|
|
"#function-key"><code>key</code></a> 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 <a href=
|
|
"#element-key"><code>xsl:key</code></a> declaration in the
|
|
<a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a>. If the processor is able to detect
|
|
the error statically (for example, when the argument is supplied as
|
|
a string literal), then the processor <span class="verb">may</span>
|
|
optionally signal this as a <a title="static error" class="termref"
|
|
href="#dt-static-error">static error</a>.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTDE1270"><span class="error">ERR
|
|
XTDE1270</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="non-recoverable dynamic error" class="termref"
|
|
href="#dt-nonrec-dynamic-error">non-recoverable dynamic error</a>
|
|
to call the <a href="#function-key"><code>key</code></a> function
|
|
with two arguments if there is no <a title="context node" class=
|
|
"termref" href="#dt-context-node">context node</a>, or if the root
|
|
of the tree containing the context node is not a document node; or
|
|
to call the function with three arguments if the root of the tree
|
|
containing the node supplied in the third argument is not a
|
|
document node.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTDE1360"><span class="error">ERR
|
|
XTDE1360</span></a></dt>
|
|
<dd>
|
|
<p>If the <a href="#function-current"><code>current</code></a>
|
|
function is evaluated within an expression that is evaluated when
|
|
the context item is undefined, a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a>
|
|
occurs.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTDE1370"><span class="error">ERR
|
|
XTDE1370</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="non-recoverable dynamic error" class="termref"
|
|
href="#dt-nonrec-dynamic-error">non-recoverable dynamic error</a>
|
|
if the <a href=
|
|
"#function-unparsed-entity-uri"><code>unparsed-entity-uri</code></a>
|
|
function is called when there is no <a title="context node" class=
|
|
"termref" href="#dt-context-node">context node</a>, or when the
|
|
root of the tree containing the context node is not a document
|
|
node.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTDE1380"><span class="error">ERR
|
|
XTDE1380</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="non-recoverable dynamic error" class="termref"
|
|
href="#dt-nonrec-dynamic-error">non-recoverable dynamic error</a>
|
|
if the <a href=
|
|
"#function-unparsed-entity-public-id"><code>unparsed-entity-public-id</code></a>
|
|
function is called when there is no <a title="context node" class=
|
|
"termref" href="#dt-context-node">context node</a>, or when the
|
|
root of the tree containing the context node is not a document
|
|
node.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTDE1390"><span class="error">ERR
|
|
XTDE1390</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="non-recoverable dynamic error" class="termref"
|
|
href="#dt-nonrec-dynamic-error">non-recoverable dynamic error</a>
|
|
if the value [supplied as the <code>$property-name</code> argument
|
|
to the <a href=
|
|
"#function-system-property"><code>system-property</code></a>
|
|
function] is not a valid QName, or if there is no namespace
|
|
declaration in scope for the prefix of the QName. If the processor
|
|
is able to detect the error statically (for example, when the
|
|
argument is supplied as a string literal), then the processor
|
|
<span class="verb">may</span> optionally signal this as a <a title=
|
|
"static error" class="termref" href="#dt-static-error">static
|
|
error</a>.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTMM9000"><span class="error">ERR
|
|
XTMM9000</span></a></dt>
|
|
<dd>
|
|
<p>When a transformation is terminated by use of <code>xsl:message
|
|
terminate="yes"</code>, the effect is the same as when a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> occurs
|
|
during the transformation. <span>The default error code is
|
|
<code>XTMM9000</code>; this may be overridden using the
|
|
<code>error-code</code> attribute of the <a href=
|
|
"#element-message"><code>xsl:message</code></a>
|
|
instruction.</span></p>
|
|
</dd>
|
|
<dt><a href="#err-XTDE1400"><span class="error">ERR
|
|
XTDE1400</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="non-recoverable dynamic error" class="termref"
|
|
href="#dt-nonrec-dynamic-error">non-recoverable dynamic error</a>
|
|
if the argument [passed to the <a href=
|
|
"#function-function-available"><code>function-available</code></a>
|
|
function] does not evaluate to a string that is a valid <a title=
|
|
"QName" class="termref" href="#dt-qname">QName</a>, or if there is
|
|
no namespace declaration in scope for the prefix of the <a title=
|
|
"QName" class="termref" href="#dt-qname">QName</a>. If the
|
|
processor is able to detect the error statically (for example, when
|
|
the argument is supplied as a string literal), then the processor
|
|
<span class="verb">may</span> optionally signal this as a <a title=
|
|
"static error" class="termref" href="#dt-static-error">static
|
|
error</a>.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTDE1420"><span class="error">ERR
|
|
XTDE1420</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="non-recoverable dynamic error" class="termref"
|
|
href="#dt-nonrec-dynamic-error">non-recoverable dynamic error</a>
|
|
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.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTDE1425"><span class="error">ERR
|
|
XTDE1425</span></a></dt>
|
|
<dd>
|
|
<p><span>When the containing element is processed with <a title=
|
|
"XSLT 1.0 behavior" class="termref" href=
|
|
"#dt-xslt-10-behavior">XSLT 1.0 behavior</a>,</span> it is a
|
|
<a title="non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> to
|
|
evaluate an extension function call if no implementation of the
|
|
extension function is available.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTDE1428"><span class="error">ERR
|
|
XTDE1428</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="non-recoverable dynamic error" class="termref"
|
|
href="#dt-nonrec-dynamic-error">non-recoverable dynamic error</a>
|
|
if the argument [passed to the <a href=
|
|
"#function-type-available"><code>type-available</code></a>
|
|
function] does not evaluate to a string that is a valid <a title=
|
|
"QName" class="termref" href="#dt-qname">QName</a>, or if there is
|
|
no namespace declaration in scope for the prefix of the <a title=
|
|
"QName" class="termref" href="#dt-qname">QName</a>. If the
|
|
processor is able to detect the error statically (for example, when
|
|
the argument is supplied as a string literal), then the processor
|
|
<span class="verb">may</span> optionally signal this as a <a title=
|
|
"static error" class="termref" href="#dt-static-error">static
|
|
error</a>.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTDE1440"><span class="error">ERR
|
|
XTDE1440</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="non-recoverable dynamic error" class="termref"
|
|
href="#dt-nonrec-dynamic-error">non-recoverable dynamic error</a>
|
|
if the argument [passed to the <a href=
|
|
"#function-element-available"><code>element-available</code></a>
|
|
function] does not evaluate to a string that is a valid <a title=
|
|
"QName" class="termref" href="#dt-qname">QName</a>, or if there is
|
|
no namespace declaration in scope for the prefix of the <a title=
|
|
"QName" class="termref" href="#dt-qname">QName</a>. If the
|
|
processor is able to detect the error statically (for example, when
|
|
the argument is supplied as a string literal), then the processor
|
|
<span class="verb">may</span> optionally signal this as a <a title=
|
|
"static error" class="termref" href="#dt-static-error">static
|
|
error</a>.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTDE1450"><span class="error">ERR
|
|
XTDE1450</span></a></dt>
|
|
<dd>
|
|
<p>When a <a title="processor" class="termref" href=
|
|
"#dt-processor">processor</a> performs fallback for an <a title=
|
|
"extension instruction" class="termref" href=
|
|
"#dt-extension-instruction">extension instruction</a> that is not
|
|
recognized, if the instruction element has one or more <a href=
|
|
"#element-fallback"><code>xsl:fallback</code></a> children, then
|
|
the content of each of the <a href=
|
|
"#element-fallback"><code>xsl:fallback</code></a> children
|
|
<span class="verb">must</span> be evaluated; it is a <a title=
|
|
"non-recoverable dynamic error" class="termref" href=
|
|
"#dt-nonrec-dynamic-error">non-recoverable dynamic error</a> if it
|
|
has no <a href="#element-fallback"><code>xsl:fallback</code></a>
|
|
children.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTDE1460"><span class="error">ERR
|
|
XTDE1460</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="non-recoverable dynamic error" class="termref"
|
|
href="#dt-nonrec-dynamic-error">non-recoverable dynamic error</a>
|
|
if the <a title="effective value" class="termref" href=
|
|
"#dt-effective-value">effective value</a> of the
|
|
<code>format</code> attribute [of an <a href=
|
|
"#element-result-document"><code>xsl:result-document</code></a>
|
|
element] is not a valid <a title="lexical QName" class="termref"
|
|
href="#dt-lexical-qname">lexical QName</a>, or if it does not match
|
|
the <a title="expanded-QName" class="termref" href=
|
|
"#dt-expanded-qname">expanded-QName</a> of an <a title=
|
|
"output definition" class="termref" href=
|
|
"#dt-output-definition">output definition</a> in the <a title=
|
|
"stylesheet" class="termref" href="#dt-stylesheet">stylesheet</a>.
|
|
If the processor is able to detect the error statically (for
|
|
example, when the <code>format</code> attribute contains no curly
|
|
brackets), then the processor <span class="verb">may</span>
|
|
optionally signal this as a <a title="static error" class="termref"
|
|
href="#dt-static-error">static error</a>.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTDE1480"><span class="error">ERR
|
|
XTDE1480</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="non-recoverable dynamic error" class="termref"
|
|
href="#dt-nonrec-dynamic-error">non-recoverable dynamic error</a>
|
|
to evaluate the <a href=
|
|
"#element-result-document"><code>xsl:result-document</code></a>
|
|
instruction in <a title="temporary output state" class="termref"
|
|
href="#dt-temporary-output-state">temporary output state</a>.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTDE1490"><span class="error">ERR
|
|
XTDE1490</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="non-recoverable dynamic error" class="termref"
|
|
href="#dt-nonrec-dynamic-error">non-recoverable dynamic error</a>
|
|
for a transformation to generate two or more <a title=
|
|
"final result tree" class="termref" href=
|
|
"#dt-final-result-tree">final result trees</a> with the same
|
|
URI.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTRE1495"><span class="error">ERR
|
|
XTRE1495</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="recoverable error" class="termref" href=
|
|
"#dt-recoverable-error">recoverable dynamic error</a> for a
|
|
transformation to generate two or more <a title="final result tree"
|
|
class="termref" href="#dt-final-result-tree">final result trees</a>
|
|
with URIs that identify the same physical resource. The <a title=
|
|
"optional recovery action" class="termref" href=
|
|
"#dt-optional-recovery-action">optional recovery action</a> is
|
|
<a title="implementation-dependent" class="termref" href=
|
|
"#dt-implementation-dependent">implementation-dependent</a>, since
|
|
it may be impossible for the processor to detect the error.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTRE1500"><span class="error">ERR
|
|
XTRE1500</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="recoverable error" class="termref" href=
|
|
"#dt-recoverable-error">recoverable dynamic error</a> for a
|
|
<a title="stylesheet" class="termref" href=
|
|
"#dt-stylesheet">stylesheet</a> to write to an external resource
|
|
and read from the same resource during a single transformation,
|
|
whether or not the same URI is used to access the resource in both
|
|
cases.<br />
|
|
<i>    Action:</i> The <a title=
|
|
"optional recovery action" class="termref" href=
|
|
"#dt-optional-recovery-action">optional recovery action</a> is
|
|
<a title="implementation-dependent" class="termref" href=
|
|
"#dt-implementation-dependent">implementation-dependent</a>:
|
|
implementations are not <span class="verb">required</span> to
|
|
detect the error condition. Note that if the error is not detected,
|
|
it is undefined whether the document that is read from the resource
|
|
reflects its state before or after the result tree is written.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTRE1620"><span class="error">ERR
|
|
XTRE1620</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="recoverable error" class="termref" href=
|
|
"#dt-recoverable-error">recoverable dynamic error</a> if an
|
|
<a href="#element-value-of"><code>xsl:value-of</code></a> or
|
|
<a href="#element-text"><code>xsl:text</code></a> instruction
|
|
specifies that output escaping is to be disabled and the
|
|
implementation does not support this.<br />
|
|
<i>    Action:</i> The <a title=
|
|
"optional recovery action" class="termref" href=
|
|
"#dt-optional-recovery-action">optional recovery action</a> is to
|
|
ignore the <code>disable-output-escaping</code> attribute.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTRE1630"><span class="error">ERR
|
|
XTRE1630</span></a></dt>
|
|
<dd>
|
|
<p>It is a <a title="recoverable error" class="termref" href=
|
|
"#dt-recoverable-error">recoverable dynamic error</a> if an
|
|
<a href="#element-value-of"><code>xsl:value-of</code></a> or
|
|
<a href="#element-text"><code>xsl:text</code></a> instruction
|
|
specifies that output escaping is to be disabled when writing to a
|
|
<a title="final result tree" class="termref" href=
|
|
"#dt-final-result-tree">final result tree</a> that is not being
|
|
serialized.<br />
|
|
<i>    Action:</i> The <a title=
|
|
"optional recovery action" class="termref" href=
|
|
"#dt-optional-recovery-action">optional recovery action</a> is to
|
|
ignore the <code>disable-output-escaping</code> attribute.</p>
|
|
</dd>
|
|
<dt><a href="#err-XTDE1665"><span class="error">ERR
|
|
XTDE1665</span></a></dt>
|
|
<dd>
|
|
<p>A <a title="basic XSLT processor" class="termref" href=
|
|
"#dt-basic-xslt-processor">basic XSLT processor</a> <span class=
|
|
"verb">must</span> raise a <a title="non-recoverable dynamic error"
|
|
class="termref" href="#dt-nonrec-dynamic-error">non-recoverable
|
|
dynamic error</a> if the input to the processor includes a node
|
|
with a <a title="type annotation" class="termref" href=
|
|
"#dt-annotation">type annotation</a> other than
|
|
<code>xs:untyped</code> or <code>xs:untypedAtomic</code>, or an
|
|
atomic value of a type other than those which a basic XSLT
|
|
processor supports.</p>
|
|
</dd>
|
|
</dl>
|
|
</div>
|
|
<div class="div1">
|
|
<h2><a name="implementation-defined-features" id=
|
|
"implementation-defined-features"></a>E Checklist of
|
|
Implementation-Defined Features (Non-Normative)</h2>
|
|
<p>This appendix provides a summary of XSLT language features whose
|
|
effect is explicitly <a title="implementation-defined" class=
|
|
"termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a>. The
|
|
conformance rules (see <a href="#conformance"><i>24
|
|
Conformance</i></a>) require vendors to provide documentation that
|
|
explains how these choices have been exercised.</p>
|
|
<ol>
|
|
<li>
|
|
<p>The way in which a <a title="base output URI" class="termref"
|
|
href="#dt-base-output-uri">base output URI</a> is established is
|
|
<a title="implementation-defined" class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a> (See
|
|
<a href="#initiating"><i>2.3 Initiating a
|
|
Transformation</i></a>)</p>
|
|
</li>
|
|
<li>
|
|
<p>The way in which an XSLT processor is invoked, and the way in
|
|
which values are supplied for the source document, starting node,
|
|
<a title="stylesheet parameter" class="termref" href=
|
|
"#dt-stylesheet-parameter">stylesheet parameters</a>, and <a title=
|
|
"base output URI" class="termref" href="#dt-base-output-uri">base
|
|
output URI</a>, are implementation-defined. (See <a href=
|
|
"#initiating"><i>2.3 Initiating a Transformation</i></a>)</p>
|
|
</li>
|
|
<li>
|
|
<p>The mechanisms for creating new <a title="extension instruction"
|
|
class="termref" href="#dt-extension-instruction">extension
|
|
instructions</a> and <a title="extension function" class="termref"
|
|
href="#dt-extension-function">extension functions</a> are <a title=
|
|
"implementation-defined" class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a>. (See
|
|
<a href="#extensibility"><i>2.7 Extensibility</i></a>)</p>
|
|
</li>
|
|
<li>
|
|
<p>Where the specification provides a choice between signaling a
|
|
dynamic error or recovering, the decision that is made (but not the
|
|
recovery action itself) is <a title="implementation-defined" class=
|
|
"termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a>. (See
|
|
<a href="#errors"><i>2.10 Error Handling</i></a>)</p>
|
|
</li>
|
|
<li>
|
|
<p>It is <a title="implementation-defined" class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a> whether
|
|
type errors are signaled statically. (See <a href="#errors"><i>2.10
|
|
Error Handling</i></a>)</p>
|
|
</li>
|
|
<li>
|
|
<p>The set of namespaces that are specially recognized by the
|
|
implementation (for example, for user-defined data elements, and
|
|
<a title="extension attribute" class="termref" href=
|
|
"#dt-extension-attribute">extension attributes</a>) is <a title=
|
|
"implementation-defined" class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a>. (See
|
|
<a href="#user-defined-top-level"><i>3.6.3 User-defined Data
|
|
Elements</i></a>)</p>
|
|
</li>
|
|
<li>
|
|
<p>The effect of user-defined data elements whose name is in a
|
|
namespace recognized by the implementation is <a title=
|
|
"implementation-defined" class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a>. (See
|
|
<a href="#user-defined-top-level"><i>3.6.3 User-defined Data
|
|
Elements</i></a>)</p>
|
|
</li>
|
|
<li>
|
|
<p>If the <a title="effective version" class="termref" href=
|
|
"#dt-effective-version">effective version</a> of any element in the
|
|
stylesheet is not 1.0 or 2.0 but is less than 2.1, the <span class=
|
|
"verb">recommended</span> action is to report a static error;
|
|
however, processors <span class="verb">may</span> recognize such
|
|
values and process the element in an <a title=
|
|
"implementation-defined" class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a> way. (See
|
|
<a href="#backwards"><i>3.8 Backwards Compatible
|
|
Processing</i></a>)</p>
|
|
</li>
|
|
<li>
|
|
<p>It is implementation-defined whether an <span>XSLT 2.1</span>
|
|
processor supports backwards compatible behavior for any XSLT
|
|
version earlier than XSLT 2.1. (See <a href="#backwards"><i>3.8
|
|
Backwards Compatible Processing</i></a>)</p>
|
|
</li>
|
|
<li>
|
|
<p>It is implementation-defined what forms of URI reference are
|
|
acceptable in the <code>href</code> attribute of the <a href=
|
|
"#element-include"><code>xsl:include</code></a> and <a href=
|
|
"#element-import"><code>xsl:import</code></a> elements, for
|
|
example, the URI schemes that may be used, the forms of fragment
|
|
identifier that may be used, and the media types that are
|
|
supported. (See <a href="#locating-modules"><i>3.10.1 Locating
|
|
Stylesheet Modules</i></a>)</p>
|
|
</li>
|
|
<li>
|
|
<p>An implementation may define mechanisms, above and beyond
|
|
<a href="#element-import-schema"><code>xsl:import-schema</code></a>
|
|
that allow <a title="schema component" class="termref" href=
|
|
"#dt-schema-component">schema components</a> such as type
|
|
definitions to be made available within a stylesheet. (See <a href=
|
|
"#built-in-types"><i>3.13 Built-in Types</i></a>)</p>
|
|
</li>
|
|
<li>
|
|
<p>It is implementation-defined which versions of XML and XML
|
|
Namespaces (1.0 and/or 1.1) are supported. (See <a href=
|
|
"#xml-versions"><i>4.1 XML Versions</i></a>)</p>
|
|
</li>
|
|
<li>
|
|
<p>Limits on the value space of primitive data types, where not
|
|
fixed by <a href="#xmlschema-2">[XML Schema Part 2]</a>, are
|
|
implementation-defined. (See <a href="#limits"><i>4.7
|
|
Limits</i></a>)</p>
|
|
</li>
|
|
<li>
|
|
<p>The set of <a href=
|
|
"http://www.w3.org/TR/xpath-21/#dt-known-docs">statically known
|
|
documents</a><sup><small>XP21</small></sup> is <a title=
|
|
"implementation-defined" class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a>, and by
|
|
default is empty. (See <a href="#static-context"><i>5.4.1
|
|
Initializing the Static Context</i></a>)</p>
|
|
</li>
|
|
<li>
|
|
<p>The set of <a href=
|
|
"http://www.w3.org/TR/xpath-21/#dt-known-collections">statically
|
|
known collections</a><sup><small>XP21</small></sup> is <a title=
|
|
"implementation-defined" class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a>, and by
|
|
default is empty. (See <a href="#static-context"><i>5.4.1
|
|
Initializing the Static Context</i></a>)</p>
|
|
</li>
|
|
<li>
|
|
<p>The <a href=
|
|
"http://www.w3.org/TR/xpath-21/#dt-known-default-collection">statically
|
|
known default collection type</a><sup><small>XP21</small></sup> is
|
|
<a title="implementation-defined" class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a>, and by
|
|
default is <code>node()*</code>. (See <a href=
|
|
"#static-context"><i>5.4.1 Initializing the Static
|
|
Context</i></a>)</p>
|
|
</li>
|
|
<li>
|
|
<p>Implementations may provide user options that relax the
|
|
requirement for the <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-doc"><code>doc</code></a><sup><small>FO</small></sup>
|
|
and <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-collection"><code>collection</code></a><sup><small>FO</small></sup>
|
|
functions (and therefore, by implication, the <a href=
|
|
"#function-document"><code>document</code></a> function) to return
|
|
stable results. The manner in which such user options are provided,
|
|
if at all, is <a title="implementation-defined" class="termref"
|
|
href="#dt-implementation-defined">implementation-defined</a>. (See
|
|
<a href="#xpath-dynamic-context"><i>5.4.3 Initializing the Dynamic
|
|
Context</i></a>)</p>
|
|
</li>
|
|
<li>
|
|
<p>The implicit timezone for a transformation is
|
|
implementation-defined. (See <a href=
|
|
"#evaluation-context"><i>5.4.3.2 Other components of the XPath
|
|
Dynamic Context</i></a>)</p>
|
|
</li>
|
|
<li>
|
|
<p>The <a href=
|
|
"http://www.w3.org/TR/xpath-21/#dt-default-collection">default
|
|
collection</a><sup><small>XP21</small></sup> is <a title=
|
|
"implementation-defined" class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a>. (See
|
|
<a href="#evaluation-context"><i>5.4.3.2 Other components of the
|
|
XPath Dynamic Context</i></a>)</p>
|
|
</li>
|
|
<li>
|
|
<p>It is <a title="implementation-defined" class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a> whether,
|
|
and under what circumstances, calls to <a title=
|
|
"extension function" class="termref" href=
|
|
"#dt-extension-function">extension functions</a> are <a title=
|
|
"non-contextual function call" class="termref" href=
|
|
"#dt-non-contextual-function-call">non-contextual</a>. (See
|
|
<a href="#additional-dynamic-context"><i>5.4.4 Additional Dynamic
|
|
Context Components used by XSLT</i></a>)</p>
|
|
</li>
|
|
<li>
|
|
<p>The default values for the <code>warning-on-no-match</code> and
|
|
<code>warning-on-multiple-match</code> attributes of <a href=
|
|
"#element-mode"><code>xsl:mode</code></a> are <a title=
|
|
"implementation-defined" class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a>. (See
|
|
<a href="#declaring-modes"><i>6.6.1 Declaring Modes</i></a>)</p>
|
|
</li>
|
|
<li>
|
|
<p>The mechanism by which the caller supplies a value for a
|
|
<a title="stylesheet parameter" class="termref" href=
|
|
"#dt-stylesheet-parameter">stylesheet parameter</a> is <a title=
|
|
"implementation-defined" class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a>. (See
|
|
<a href="#global-variables"><i>9.5 Global Variables and
|
|
Parameters</i></a>)</p>
|
|
</li>
|
|
<li>
|
|
<p>The set of extension functions available in the static context
|
|
for the target expression of <a href=
|
|
"#element-evaluate"><code>xsl:evaluate</code></a> is <a title=
|
|
"implementation-defined" class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a>. (See
|
|
<a href="#dynamic-xpath"><i>10.4 Dynamic XPath
|
|
Evaluation</i></a>)</p>
|
|
</li>
|
|
<li>
|
|
<p>If an <code>xml:id</code> attribute that has not been subjected
|
|
to attribute value normalization is copied from a source tree to a
|
|
result tree, it is implementation-defined whether attribute value
|
|
normalization will be applied during the copy process. (See
|
|
<a href="#shallow-copy"><i>11.9.1 Shallow Copy</i></a>)</p>
|
|
</li>
|
|
<li>
|
|
<p>The numbering sequences supported by the <a href=
|
|
"#element-number"><code>xsl:number</code></a> instructions, beyond
|
|
those defined in this specification, are implementation-defined.
|
|
(See <a href="#convert"><i>12.3 Number to String Conversion
|
|
Attributes</i></a>)</p>
|
|
</li>
|
|
<li>
|
|
<p>There <span class="verb">may</span> be implementation-defined
|
|
upper bounds on the numbers that can be formatted by <a href=
|
|
"#element-number"><code>xsl:number</code></a> using any particular
|
|
numbering sequence. (See <a href="#convert"><i>12.3 Number to
|
|
String Conversion Attributes</i></a>)</p>
|
|
</li>
|
|
<li>
|
|
<p>The set of languages for which numbering is supported by
|
|
<a href="#element-number"><code>xsl:number</code></a>, and the
|
|
method of choosing a default language, are implementation-defined.
|
|
(See <a href="#convert"><i>12.3 Number to String Conversion
|
|
Attributes</i></a>)</p>
|
|
</li>
|
|
<li>
|
|
<p>With <a href="#element-number"><code>xsl:number</code></a>, it
|
|
is <a title="implementation-defined" class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a> what
|
|
combinations of values of the format token, the language, and the
|
|
<code>ordinal</code> attribute are supported. (See <a href=
|
|
"#convert"><i>12.3 Number to String Conversion
|
|
Attributes</i></a>)</p>
|
|
</li>
|
|
<li>
|
|
<p>If the <code>data-type</code> attribute of the <a href=
|
|
"#element-sort"><code>xsl:sort</code></a> element has a value other
|
|
than <code>text</code> or <code>number</code>, the effect is
|
|
implementation-defined. (See <a href=
|
|
"#comparing-sort-keys"><i>13.1.2 Comparing Sort Key
|
|
Values</i></a>)</p>
|
|
</li>
|
|
<li>
|
|
<p>The facilities for defining collations and allocating URIs to
|
|
identify them are implementation-defined. (See <a href=
|
|
"#collating-sequences"><i>13.1.3 Sorting Using
|
|
Collations</i></a>)</p>
|
|
</li>
|
|
<li>
|
|
<p>The algorithm used by <a href=
|
|
"#element-sort"><code>xsl:sort</code></a> to locate a collation,
|
|
given the values of the <code>lang</code> and
|
|
<code>case-order</code> attributes, is implementation-defined. (See
|
|
<a href="#collating-sequences"><i>13.1.3 Sorting Using
|
|
Collations</i></a>)</p>
|
|
</li>
|
|
<li>
|
|
<p>The set of media types recognized by the processor, for the
|
|
purpose of interpreting fragment identifiers in URI references
|
|
passed to the <a href=
|
|
"#function-document"><code>document</code></a> function, is
|
|
implementation-defined. (See <a href="#document"><i>19.1.1 The
|
|
document function</i></a>)</p>
|
|
</li>
|
|
<li>
|
|
<p>The set of encodings recognized by the <a href=
|
|
"#function-unparsed-text"><code>unparsed-text</code></a> function,
|
|
other than <code>utf-8</code> and <code>utf-16</code>, is <a title=
|
|
"implementation-defined" class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a>. (See
|
|
<a href="#unparsed-text-function"><i>19.2.1 The unparsed-text
|
|
function</i></a>)</p>
|
|
</li>
|
|
<li>
|
|
<p>If no encoding is specified on a call to the <a href=
|
|
"#function-unparsed-text"><code>unparsed-text</code></a> function,
|
|
the processor <span class="verb">may</span> use <a title=
|
|
"implementation-defined" class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a> heuristics
|
|
to determine the likely encoding. (See <a href=
|
|
"#unparsed-text-function"><i>19.2.1 The unparsed-text
|
|
function</i></a>)</p>
|
|
</li>
|
|
<li>
|
|
<p>The values returned by the <a href=
|
|
"#function-system-property"><code>system-property</code></a>
|
|
function, and the names of the additional properties that are
|
|
recognized, are implementation-defined. (See <a href=
|
|
"#system-property"><i>19.5.4 system-property</i></a>)</p>
|
|
</li>
|
|
<li>
|
|
<p>The destination and formatting of messages written using the
|
|
<a href="#element-message"><code>xsl:message</code></a> instruction
|
|
are implementation-defined. (See <a href="#message"><i>20
|
|
Messages</i></a>)</p>
|
|
</li>
|
|
<li>
|
|
<p>This specification does not define any mechanism for creating or
|
|
binding implementations of <a title="extension instruction" class=
|
|
"termref" href="#dt-extension-instruction">extension
|
|
instructions</a> or <a title="extension function" class="termref"
|
|
href="#dt-extension-function">extension functions</a>, and it is
|
|
not <span class="verb">required</span> that implementations support
|
|
any such mechanism. Such mechanisms, if they exist, are <a title=
|
|
"implementation-defined" class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a>. (See
|
|
<a href="#extension"><i>21 Extensibility and Fallback</i></a>)</p>
|
|
</li>
|
|
<li>
|
|
<p>The effect of an extension function returning a string
|
|
containing characters that are not legal in XML is
|
|
implementation-defined. (See <a href=
|
|
"#calling-extension-functions"><i>21.1.2 Calling Extension
|
|
Functions</i></a>)</p>
|
|
</li>
|
|
<li>
|
|
<p>The way in which external objects are represented in the type
|
|
system is implementation-defined. (See <a href=
|
|
"#external-objects"><i>21.1.3 External Objects</i></a>)</p>
|
|
</li>
|
|
<li>
|
|
<p>The way in which a final result tree is delivered to an
|
|
application is implementation-defined. (See <a href=
|
|
"#result-trees"><i>22 Final Result Trees</i></a>)</p>
|
|
</li>
|
|
<li>
|
|
<p>There <span class="verb">may</span> be <a title=
|
|
"implementation-defined" class="termref" href=
|
|
"#dt-implementation-defined">implementation-defined</a>
|
|
restrictions on the form of absolute URI that may be used in the
|
|
<code>href</code> attribute of the <a href=
|
|
"#element-result-document"><code>xsl:result-document</code></a>
|
|
instruction. (See <a href="#creating-result-trees"><i>22.1 Creating
|
|
Final Result Trees</i></a>)</p>
|
|
</li>
|
|
<li>
|
|
<p>Implementations <span class="verb">may</span> provide additional
|
|
mechanisms allowing users to define the way in which <a title=
|
|
"final result tree" class="termref" href=
|
|
"#dt-final-result-tree">final result trees</a> are processed. (See
|
|
<a href="#creating-result-trees"><i>22.1 Creating Final Result
|
|
Trees</i></a>)</p>
|
|
</li>
|
|
<li>
|
|
<p>If serialization is supported, then the location to which a
|
|
<a title="final result tree" class="termref" href=
|
|
"#dt-final-result-tree">final result tree</a> is serialized is
|
|
implementation-defined, subject to the constraint that relative URI
|
|
<span>references</span> used to reference one tree from another
|
|
remain valid. (See <a href="#serialization"><i>23
|
|
Serialization</i></a>)</p>
|
|
</li>
|
|
<li>
|
|
<p>The default value of the <code>encoding</code> attribute of the
|
|
<a href="#element-output"><code>xsl:output</code></a> element is
|
|
implementation-defined. (See <a href="#serialization"><i>23
|
|
Serialization</i></a>)</p>
|
|
</li>
|
|
<li>
|
|
<p>It is implementation-defined which versions of XML, HTML, and
|
|
XHTML are supported in the <code>version</code> attribute of the
|
|
<a href="#element-output"><code>xsl:output</code></a> declaration.
|
|
(See <a href="#serialization"><i>23 Serialization</i></a>)</p>
|
|
</li>
|
|
<li>
|
|
<p>The default value of the <code>byte-order-mark</code>
|
|
serialization parameter is implementation-defined in the case of
|
|
UTF-8 encoding. (See <a href="#serialization"><i>23
|
|
Serialization</i></a>)</p>
|
|
</li>
|
|
<li>
|
|
<p>It is implementation-defined whether, and under what
|
|
circumstances, disabling output escaping is supported. (See
|
|
<a href="#disable-output-escaping"><i>23.2 Disabling Output
|
|
Escaping</i></a>)</p>
|
|
</li>
|
|
</ol>
|
|
</div>
|
|
<div class="div1">
|
|
<h2><a name="XSLT-defined-functions" id=
|
|
"XSLT-defined-functions"></a>F List of XSLT-defined functions
|
|
(Non-Normative)</h2>
|
|
<p>This appendix acts as an index of functions defined in this
|
|
specification, to augment the set of functions defined in <a href=
|
|
"#xpath-functions-11">[Functions and Operators]</a>.</p>
|
|
<!--XSLT Processor: SAXON 9.1.0.5 from Saxonica SAXON 9.1.0.5-->
|
|
<dl>
|
|
<dt class="label"><a href=
|
|
"#function-copy-of"><code>copy-of</code></a></dt>
|
|
<dd>See <a href="#copy-of-function"><i>18.5 The copy-of
|
|
function</i></a></dd>
|
|
<dt class="label"><a href=
|
|
"#function-current"><code>current</code></a></dt>
|
|
<dd>See <a href="#current-function"><i>19.5.1 current</i></a></dd>
|
|
<dt class="label"><a href=
|
|
"#function-current-group"><code>current-group</code></a></dt>
|
|
<dd>See <a href="#current-group"><i>14.1 The Current
|
|
Group</i></a></dd>
|
|
<dt class="label"><a href=
|
|
"#function-current-grouping-key"><code>current-grouping-key</code></a></dt>
|
|
<dd>See <a href="#current-grouping-key"><i>14.2 The Current
|
|
Grouping Key</i></a></dd>
|
|
<dt class="label"><a href=
|
|
"#function-current-merge-inputs"><code>current-merge-inputs</code></a></dt>
|
|
<dd>See <a href="#selective-processing-of-merge-inputs"><i>15.6
|
|
Selective processing of merge inputs</i></a></dd>
|
|
<dt class="label"><a href=
|
|
"#function-document"><code>document</code></a></dt>
|
|
<dd>See <a href="#document"><i>19.1.1 The document
|
|
function</i></a></dd>
|
|
<dt class="label"><a href=
|
|
"#function-element-available"><code>element-available</code></a></dt>
|
|
<dd>See <a href="#testing-instruction-available"><i>21.2.2 Testing
|
|
Availability of Instructions</i></a></dd>
|
|
<dt class="label"><a href=
|
|
"#function-function-available"><code>function-available</code></a></dt>
|
|
<dd>See <a href="#testing-function-availability"><i>21.1.1 Testing
|
|
Availability of Functions</i></a></dd>
|
|
<dt class="label"><a href=
|
|
"#function-has-children"><code>has-children</code></a></dt>
|
|
<dd>See <a href="#has-children"><i>18.9 The has-children
|
|
function</i></a></dd>
|
|
<dt class="label"><a href=
|
|
"#function-innermost"><code>innermost</code></a></dt>
|
|
<dd>See <a href="#innermost"><i>18.8 The innermost
|
|
function</i></a></dd>
|
|
<dt class="label"><a href="#function-key"><code>key</code></a></dt>
|
|
<dd>See <a href="#keys"><i>19.3.2 The key Function</i></a></dd>
|
|
<dt class="label"><a href=
|
|
"#function-outermost"><code>outermost</code></a></dt>
|
|
<dd>See <a href="#outermost"><i>18.7 The outermost
|
|
function</i></a></dd>
|
|
<dt class="label"><a href=
|
|
"#function-regex-group"><code>regex-group</code></a></dt>
|
|
<dd>See <a href="#regex-group"><i>17.2 Captured
|
|
Substrings</i></a></dd>
|
|
<dt class="label"><a href=
|
|
"#function-snapshot"><code>snapshot</code></a></dt>
|
|
<dd>See <a href="#snapshot"><i>18.6 The snapshot
|
|
function</i></a></dd>
|
|
<dt class="label"><a href=
|
|
"#function-system-property"><code>system-property</code></a></dt>
|
|
<dd>See <a href="#system-property"><i>19.5.4
|
|
system-property</i></a></dd>
|
|
<dt class="label"><a href=
|
|
"#function-type-available"><code>type-available</code></a></dt>
|
|
<dd>See <a href="#testing-type-availability"><i>21.1.4 Testing
|
|
Availability of Types</i></a></dd>
|
|
<dt class="label"><a href=
|
|
"#function-unparsed-entity-public-id"><code>unparsed-entity-public-id</code></a></dt>
|
|
<dd>See <a href="#unparsed-entity-public-id"><i>19.5.3
|
|
unparsed-entity-public-id</i></a></dd>
|
|
<dt class="label"><a href=
|
|
"#function-unparsed-entity-uri"><code>unparsed-entity-uri</code></a></dt>
|
|
<dd>See <a href="#unparsed-entity-uri"><i>19.5.2
|
|
unparsed-entity-uri</i></a></dd>
|
|
<dt class="label"><a href=
|
|
"#function-unparsed-text"><code>unparsed-text</code></a></dt>
|
|
<dd>See <a href="#unparsed-text-function"><i>19.2.1 The
|
|
unparsed-text function</i></a></dd>
|
|
<dt class="label"><a href=
|
|
"#function-unparsed-text-available"><code>unparsed-text-available</code></a></dt>
|
|
<dd>See <a href="#unparsed-text-available"><i>19.2.3 The
|
|
unparsed-text-available function</i></a></dd>
|
|
<dt class="label"><a href=
|
|
"#function-unparsed-text-lines"><code>unparsed-text-lines</code></a></dt>
|
|
<dd>See <a href="#unparsed-text-lines"><i>19.2.2 The
|
|
unparsed-text-lines function</i></a></dd>
|
|
<dt class="label"><a href=
|
|
"#function-uri-collection"><code>uri-collection</code></a></dt>
|
|
<dd>See <a href="#uri-collection"><i>19.1.2 The uri-collection
|
|
function</i></a></dd>
|
|
</dl>
|
|
</div>
|
|
<div class="div1">
|
|
<h2><a name="schema-for-xslt" id="schema-for-xslt"></a>G Schema for
|
|
XSLT Stylesheets (Non-Normative)</h2>
|
|
<blockquote>
|
|
<p><b><a name="issue-schema-for-xslt21" id=
|
|
"issue-schema-for-xslt21">Issue 35 (schema-for-xslt21)</a>:</b></p>
|
|
<p>This schema needs to be updated for XSLT 2.1</p>
|
|
</blockquote>
|
|
<p>The following schema describes the structure of an XSLT
|
|
stylesheet module. It does not define all the constraints that
|
|
apply to a stylesheet (for example, it does not attempt to define a
|
|
data type that precisely represents attributes containing XPath
|
|
<a title="expression" class="termref" href=
|
|
"#dt-expression">expressions</a>). However, every valid stylesheet
|
|
module conforms to this schema, unless it contains elements that
|
|
invoke <a title="forwards compatible behavior" class="termref"
|
|
href="#dt-forwards-compatible-behavior">forwards compatible
|
|
behavior</a>.</p>
|
|
<p>A copy of this schema is available at <a href=
|
|
"http://www.w3.org/2007/schema-for-xslt20.xsd">http://www.w3.org/2007/schema-for-xslt20.xsd</a></p>
|
|
</div>
|
|
<div class="div1">
|
|
<h2><a name="acknowledgements" id="acknowledgements"></a>H
|
|
Acknowledgements (Non-Normative)</h2>
|
|
<p>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.</p>
|
|
<p>The chair of the XSL WG is Sharon Adler, IBM. The XSL Working
|
|
Group includes two overlapping teams working on XSLT and XSL
|
|
Formatting Objects. The members of the XSL WG currently engaged in
|
|
XSLT activities, and their current affiliations, are:</p>
|
|
<dl>
|
|
<dt class="label">Anders Berglund</dt>
|
|
<dd>
|
|
<p>Invited expert</p>
|
|
</dd>
|
|
<dt class="label">Oliver Becker</dt>
|
|
<dd>
|
|
<p>Invited expert</p>
|
|
</dd>
|
|
<dt class="label">Carine Bournez</dt>
|
|
<dd>
|
|
<p>W3C</p>
|
|
</dd>
|
|
<dt class="label">Petr Cimprich</dt>
|
|
<dd>
|
|
<p>Invited expert</p>
|
|
</dd>
|
|
<dt class="label">Russell Davoli</dt>
|
|
<dd>
|
|
<p>Intel</p>
|
|
</dd>
|
|
<dt class="label">Nikolay Fiykov</dt>
|
|
<dd>
|
|
<p>Nokia</p>
|
|
</dd>
|
|
<dt class="label">Florent Georges</dt>
|
|
<dd>
|
|
<p>Invited expert</p>
|
|
</dd>
|
|
<dt class="label">Xin (Edward) Jiang</dt>
|
|
<dd>
|
|
<p>Invited expert</p>
|
|
</dd>
|
|
<dt class="label">Michael Kay</dt>
|
|
<dd>
|
|
<p>Invited expert</p>
|
|
</dd>
|
|
<dt class="label">Jirka Kosek</dt>
|
|
<dd>
|
|
<p>Invited expert</p>
|
|
</dd>
|
|
<dt class="label">Dmitriy Shabanov</dt>
|
|
<dd>
|
|
<p>Invited expert</p>
|
|
</dd>
|
|
<dt class="label">C. Michael Sperberg-McQueen</dt>
|
|
<dd>
|
|
<p>Invited expert</p>
|
|
</dd>
|
|
<dt class="label">Mohamed Zergaoui</dt>
|
|
<dd>
|
|
<p>Innovimax</p>
|
|
</dd>
|
|
<dt class="label">Henry Zongaro</dt>
|
|
<dd>
|
|
<p>IBM</p>
|
|
</dd>
|
|
</dl>
|
|
<p>The Working Group wishes to acknowledge the pioneering work of
|
|
the developers of STX (see <a href="#STX">[STX]</a>) which has
|
|
formed an important intellectual input to the design of XSLT 2.1
|
|
and has demonstrated the feasibility of creating a streaming
|
|
transformation language based on the core XSLT concept of recursive
|
|
descent of the source tree using rule-based templates.</p>
|
|
<p>The SVG diagrams in this specification are drawn using <a href=
|
|
"http://www.graphviz.org/">GraphViz</a> from AT&T Research, in
|
|
conjunction with the <a href=
|
|
"http://www.martin-loetzsch.de/DOTML/">DotML</a> markup language
|
|
developed by Martin Loetzsch.</p>
|
|
</div>
|
|
<div class="div1">
|
|
<h2><a name="open-issues" id="open-issues"></a>I Summary of Open
|
|
Issues (Non-Normative)</h2>
|
|
<blockquote>
|
|
<p><b><a href="#issue-streaming-pessimism">Issue 1
|
|
(streaming-pessimism)</a>:</b></p>
|
|
<p>The design adopted in this specification works on the basis that
|
|
decisions about streamability should be made statically (at compile
|
|
time). Sometimes this means taking a pessimistic approach, that is,
|
|
rejecting a construct as non-streamable based on worst-case
|
|
assumptions. Two examples of this are (a) disallowing
|
|
<code><xsl:with-param name="p" select="@code"/></code> when
|
|
calling a streamable template, on the grounds that the called
|
|
template might perform disallowed navigation from the attribute
|
|
node; (b) disallowing use of the descendant axis in cases where it
|
|
might select two elements, one of which is an ancestor of the
|
|
other. An alternative design approach would allow optimistic
|
|
assumptions to be made in such cases, creating the risk of dynamic
|
|
errors: for example it might be a dynamic error in the first case
|
|
if the called template performs disallowed navigation from the
|
|
attribute node, and in the second case if the descendant axis
|
|
actually selects a node that is a descendant of another selected
|
|
node. The decision to make the analysis pessimistic interacts with
|
|
the strategy for fallback if streaming is not possible; a
|
|
non-streaming fallback is feasible if decisions are made
|
|
statically, but is not realistically possible if the problems are
|
|
only detected at execution time. The Working Group welcomes
|
|
discussion of this decision.</p>
|
|
</blockquote>
|
|
<blockquote>
|
|
<p><b><a href="#issue-chameleon-modes">Issue 2
|
|
(chameleon-modes)</a>:</b></p>
|
|
<p>Would it be useful to be able to specify the default mode for an
|
|
included module on the <a href=
|
|
"#element-include"><code>xsl:include</code></a> element, in the
|
|
style of chameleon includes in XSD? The WG has discussed such a
|
|
feature; it is recognized that it would be useful, but it is not
|
|
clear whether it would be useful enough to justify the extra
|
|
complexity.</p>
|
|
</blockquote>
|
|
<blockquote>
|
|
<p><b><a href="#xsd11-additional-types">Issue 3
|
|
(additional-types)</a>:</b></p>
|
|
<p>It is likely that the new types from XSD 1.1 will be added to
|
|
this list when XSD 1.1 becomes a Recommendation.</p>
|
|
</blockquote>
|
|
<blockquote>
|
|
<p><b><a href="#issue-multiple-match-on-strip-space">Issue 4
|
|
(multiple-match-on-strip-space)</a>:</b></p>
|
|
<p>We have changed the rules for handling ambiguous matches on
|
|
template rules. Should we make a corresponding change for ambiguous
|
|
matches on <a href=
|
|
"#element-strip-space"><code>xsl:strip-space</code></a>, or is this
|
|
overkill? What is the corresponding change anyway?</p>
|
|
</blockquote>
|
|
<blockquote>
|
|
<p><b><a href="#issue-recommended-initial-context">Issue 5
|
|
(recommended-initial-context)</a>:</b></p>
|
|
<p>In the rules for defining the initial static context, we
|
|
sometimes say that the value is implementation-defined, and then
|
|
give a default. We need to be clearer what we are saying here.
|
|
Essentially the "default" is a recommendation to implementors about
|
|
what the value should be when users don't select anything
|
|
different. Perhaps if we have recommended defaults for some of
|
|
these values, we should have them for all.</p>
|
|
</blockquote>
|
|
<blockquote>
|
|
<p><b><a href="#issue-normative-evaluation-context">Issue 6
|
|
(normative-evaluation-context)</a>:</b></p>
|
|
<p>Although this table is described as non-normative, it may be
|
|
more complete than the same information given normatively
|
|
elsewhere.</p>
|
|
</blockquote>
|
|
<blockquote>
|
|
<p><b><a href="#issue-implicit-namespace-axis">Issue 7
|
|
(implicit-namespace-axis)</a>:</b></p>
|
|
<p>In XPath 2.1, as currently defined, the path expression
|
|
<code>A/B/namespace-node()</code> selects nothing, because the
|
|
default axis for the abbreviated step <code>namespace-node()</code>
|
|
is <code>child</code> rather than <code>namespace</code>. This has
|
|
been raised as bug 9298. Perhaps we should allow the namespace axis
|
|
to be explicit in a pattern.</p>
|
|
</blockquote>
|
|
<blockquote>
|
|
<p><b><a href="#issue-define-warning-codes">Issue 8
|
|
(define-warning-codes)</a>:</b></p>
|
|
<p>Should we define warning codes in the same way as we define
|
|
error codes?</p>
|
|
</blockquote>
|
|
<blockquote>
|
|
<p><b><a href=
|
|
"#issue-declaring-context-item-for-initial-template">Issue 9
|
|
(declaring-context-item-for-initial-template)</a>:</b></p>
|
|
<p>It would also be useful to be able to declare the required type
|
|
of the context item (or to say that there is none) when starting
|
|
the transformation with an <a title="initial template" class=
|
|
"termref" href="#dt-initial-template">initial named
|
|
template</a></p>
|
|
</blockquote>
|
|
<blockquote>
|
|
<p><b><a href="#issue-iterate-empty">Issue 10
|
|
(iterate-empty)</a>:</b></p>
|
|
<p>The Working Group is considering whether more control is needed
|
|
over how an empty sequence is processed. Currently, whether a
|
|
sequence is processed using <a href=
|
|
"#element-for-each"><code>xsl:for-each</code></a>, <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>, or
|
|
<a href="#element-iterate"><code>xsl:iterate</code></a>, there is
|
|
no easy way to define special code for handling an empty sequence
|
|
in a way that satisfies the rules for streamability, because one
|
|
downward selection is needed to test for emptiness, another to
|
|
perform iteration when non-empty. One possible solution is the
|
|
proposed <a href=
|
|
"#function-has-children"><code>has-children</code></a>
|
|
function.</p>
|
|
</blockquote>
|
|
<blockquote>
|
|
<p><b><a href="#issue-try-catch-output-buffering">Issue 11
|
|
(try-catch-output-buffering)</a>:</b></p>
|
|
<p>The rules appear inconsistent: if the processor is obliged to
|
|
buffer "immediate" output from the xsl:try element before sending
|
|
it the serializer, should not the same requirement apply also to
|
|
xsl:result-document (rule 5)? And if output has to be buffered, is
|
|
rule 7 appropriate, allowing serialization errors to be detected
|
|
"on the fly"?</p>
|
|
</blockquote>
|
|
<blockquote>
|
|
<p><b><a href="#fixed-value-attributes">Issue 12
|
|
(value-attributes)</a>:</b></p>
|
|
<p>The treatment of <code>tunnel</code> and <code>required</code>
|
|
is inconsistent in the case where the attribute makes no sense. In
|
|
one case we allow the parameter to be present so long as it has its
|
|
"fixed" value, in the other case we require it to be omitted. The
|
|
WG has decided in principle that where only one value makes sense
|
|
for an attribute, it should be legal to specify the attribute and
|
|
give it that value. However, where an attribute makes no sense in a
|
|
particular context, it will still be an error to include it: for
|
|
example the <code>from</code> attribute of <a href=
|
|
"#element-number"><code>xsl:number</code></a> must be omitted if
|
|
the <code>value</code> attribute is present.</p>
|
|
<p>Editor to implement WG decision.</p>
|
|
</blockquote>
|
|
<blockquote>
|
|
<p><b><a href="#issue-evaluate-optional-feature">Issue 13
|
|
(evaluate-optional-feature)</a>:</b></p>
|
|
<p>The Working Group has not yet decided whether <a href=
|
|
"#element-evaluate"><code>xsl:evaluate</code></a> will be an
|
|
optional feature of the language, or whether all implementations
|
|
will be required to provide it.</p>
|
|
</blockquote>
|
|
<blockquote>
|
|
<p><b><a href="#issue-context-in-shallow-copy">Issue 14
|
|
(context-in-shallow-copy)</a>:</b></p>
|
|
<p>Should the contained sequence constructor be evaluated with the
|
|
selected node as the context item? Use cases such as use in
|
|
<a href="#element-function"><code>xsl:function</code></a> probably
|
|
would suggest yes.</p>
|
|
</blockquote>
|
|
<blockquote>
|
|
<p><b><a href="#issue-refactor-format-integer">Issue 15
|
|
(refactor-format-integer)</a>:</b></p>
|
|
<p>The functionality described here has been encapsulated in a new
|
|
function, <a href=
|
|
"http://www.w3.org/TR/xpath-functions-11/#func-format-integer"><code>
|
|
format-integer</code></a><sup><small>FO</small></sup>. The
|
|
specification can be simplified by referring to the specification
|
|
of that function.</p>
|
|
</blockquote>
|
|
<blockquote>
|
|
<p><b><a href="#issue-current-group-source-argument">Issue 16
|
|
(current-group-source-argument)</a>:</b></p>
|
|
<p>The WG has considered a variant of <a href=
|
|
"#function-current-group"><code>current-group</code></a> for use
|
|
within <a href=
|
|
"#element-merge-action"><code>xsl:merge-action</code></a> which
|
|
would get the subset of the current group applicable to one named
|
|
merge source. This is superseded in this draft by the <a href=
|
|
"#function-current-merge-inputs"><code>current-merge-inputs</code></a>
|
|
function, which provides this capability and more. However, the
|
|
function call <code>current-group(sourcename)</code> could still be
|
|
useful because it is simpler. Also, allowing a parameter to
|
|
<code>current-group</code> opens the way to do similar things in
|
|
the context of <a href=
|
|
"#element-for-each-group"><code>xsl:for-each-group</code></a>, such
|
|
as using the source names "matching" and "non-matching" to
|
|
distinguish nodes that matched (or failed to match) the
|
|
<code>group-starting-with</code> and <code>group-ending-with</code>
|
|
patterns.</p>
|
|
</blockquote>
|
|
<blockquote>
|
|
<p><b><a href="#issue-streamability-of-merge">Issue 17
|
|
(streamability-of-merge)</a>:</b></p>
|
|
<p>The <a href="#element-merge"><code>xsl:merge</code></a>
|
|
instruction is designed to achieve streamability in the case where
|
|
the anchor nodes are the document nodes of distinct documents and
|
|
the merge keys are <a title="motionless" class="termref" href=
|
|
"#dt-motionless">motionless</a> expressions. However, unlike other
|
|
constructs, there is no provision for users to indicate that
|
|
streaming is required, and no analysis of the conditions under
|
|
which it is guaranteed.</p>
|
|
</blockquote>
|
|
<blockquote>
|
|
<p><b><a href="#issue-current-merge-activation">Issue 18
|
|
(current-merge-activation)</a>:</b></p>
|
|
<p>The concept of the <b>current-merge-activation</b> needs to be
|
|
and incorporated into the dynamic context.</p>
|
|
</blockquote>
|
|
<blockquote>
|
|
<p><b><a href="#issue-streamable-template-terminology">Issue 19
|
|
(streamable-template-terminology)</a>:</b></p>
|
|
<p>It might be more consistent to use "guaranteed-streamable
|
|
template" rather than "streamable template".</p>
|
|
</blockquote>
|
|
<blockquote>
|
|
<p><b><a href="#issue-prohibit-doc-in-patterns">Issue 20
|
|
(prohibit-doc-in-patterns)</a>:</b></p>
|
|
<p>Given that <a href="#element-stream"><code>xsl:stream</code></a>
|
|
might not yield stable results, it might make sense to prohibit
|
|
<code>DocCall</code> here as well - it's highly implementation
|
|
dependent whether the same node from the streamed document would
|
|
occur in the document returned by the <code>doc</code> function
|
|
call.</p>
|
|
</blockquote>
|
|
<blockquote>
|
|
<p><b><a href="#issue-streamable-dynamic-evaluate">Issue 21
|
|
(streamable-dynamic-evaluate)</a>:</b></p>
|
|
<p>This might be a case where deferring decisions on streamability
|
|
until execution time might be appropriate. There might be scope to
|
|
provide an attribute on <a href=
|
|
"#element-evaluate"><code>xsl:evaluate</code></a> that asserts
|
|
streamability (perhaps <a title="motionless" class="termref" href=
|
|
"#dt-motionless">motionless</a> streamability), with this assertion
|
|
being checked at execution time when the actual XPath expression is
|
|
known.</p>
|
|
</blockquote>
|
|
<blockquote>
|
|
<p><b><a href="#issue-unparsed-entities-not-at-start">Issue 22
|
|
(unparsed-entities-not-at-start)</a>:</b></p>
|
|
<p>There is an edge-case problem here: comments and processing
|
|
instructions can precede the <code>DOCTYPE</code> declaration, and
|
|
while processing such comments and processing instructions, the
|
|
unparsed entities referenced in the DTD are not yet known. A
|
|
possible solution would be to require buffering of such comments
|
|
and processing instructions until the DTD has been read. Note that
|
|
the path analysis can establish that a stylesheet makes reference
|
|
to unparsed entities in the streamed document, so it might be
|
|
possible to provide this capability without imposing any costs on
|
|
users who don't use it.</p>
|
|
<p>Another problem with similar consequences is that an expression
|
|
such as <code>/ instance of document-node(element(A))</code> cannot
|
|
be evaluated until the first element start tag has been
|
|
processed.</p>
|
|
</blockquote>
|
|
<blockquote>
|
|
<p><b><a href="#issue-intersect">Issue 23 (intersect)</a>:</b></p>
|
|
<p>It might be safe to treat one of the operands as
|
|
non-contributing, but the Working Group has not been able to
|
|
demonstrate this to its satisfaction. Note that if one of the
|
|
operands selects nodes from the streamed input and the other does
|
|
not, then the intersection will not contain any nodes from the
|
|
streamed input.</p>
|
|
</blockquote>
|
|
<blockquote>
|
|
<p><b><a href="#issue-streamability-of-grouping">Issue 24
|
|
(streamability-of-grouping)</a>:</b></p>
|
|
<p>The analysis of the streamability of grouping needs a more
|
|
thorough exposition; although the rules given might well be
|
|
correct, they are not convincingly explained.</p>
|
|
</blockquote>
|
|
<blockquote>
|
|
<p><b><a href="#issue-data-flow-into-a-loop">Issue 25
|
|
(data-flow-into-a-loop)</a>:</b></p>
|
|
<p>The rules prohibiting data flows into the body of a loop may be
|
|
stricter than is necessary: they are designed to prevent repeated
|
|
evaluation of a downward selection, but as written, they also
|
|
disallow motionless expressions such as <code>$var/@name</code> or
|
|
<code>name($var)</code></p>
|
|
</blockquote>
|
|
<blockquote>
|
|
<p><b><a href="#issue-descendant-then-child">Issue 26
|
|
(descendant-then-child)</a>:</b></p>
|
|
<p>The restriction that a path such as <code>.//section/head</code>
|
|
is non-streamable is too severe; it needs to be relaxed.</p>
|
|
</blockquote>
|
|
<blockquote>
|
|
<p><b><a href="#issue-snapshot-on-root-node">Issue 27
|
|
(snapshot-on-root-node)</a>:</b></p>
|
|
<p>The code given here is incorrect in the case where
|
|
<code>snapshot</code> is applied to a parentless node: it should
|
|
return a copy of the node, but actually returns the original.</p>
|
|
</blockquote>
|
|
<blockquote>
|
|
<p><b><a href="#issue-streamability-of-outermost">Issue 28
|
|
(streamability-of-outermost)</a>:</b></p>
|
|
<p>Note however that the streamability analysis as currently
|
|
written does not take calls on the <code>outermost</code> function
|
|
into account.</p>
|
|
</blockquote>
|
|
<blockquote>
|
|
<p><b><a href="#issue-has-children">Issue 29
|
|
(has-children)</a>:</b></p>
|
|
<p>The Working Group is considering defining a function
|
|
<code>has-children</code> which returns true if the context item
|
|
has one or more child nodes. This function would be defined as
|
|
<a title="motionless" class="termref" href=
|
|
"#dt-motionless">motionless</a>, allowing it to be used for example
|
|
in the predicate of a pattern. Implementation requires a
|
|
one-parser-event lookahead. The primary use case is for creating
|
|
lists or tables in streaming mode, where the wrapper element (for
|
|
example <code>ul</code> or <code>table</code>) is to be generated
|
|
only if the list is non-empty. Most current solutions to this
|
|
problem require two downward selections, one to test if the list is
|
|
empty and one to iterate over its contents. There is a solution
|
|
using <a href=
|
|
"#element-for-each-group"><code>xsl:for-each-group</code></a> to
|
|
generate a singleton group, but it involves rather artificial
|
|
coding.</p>
|
|
</blockquote>
|
|
<blockquote>
|
|
<p><b><a href="#issue-transfer-uri-collection">Issue 30
|
|
(transfer-uri-collection)</a>:</b></p>
|
|
<p>A decision in principle has been reached for
|
|
<code>uri-collection</code> to become a standard XPath 2.1
|
|
function.</p>
|
|
</blockquote>
|
|
<blockquote>
|
|
<p><b><a href="#issue-transfer-unparsed-text">Issue 31
|
|
(transfer-unparsed-text)</a>:</b></p>
|
|
<p>A decision in principle has been reached for
|
|
<code>unparsed-text</code> and <code>unparsed-text-available</code>
|
|
to become standard XPath 2.1 functions.</p>
|
|
</blockquote>
|
|
<blockquote>
|
|
<p><b><a href="#issue-function-stability">Issue 32
|
|
(function-stability)</a>:</b></p>
|
|
<p>The functions in this specification need to be classified more
|
|
clearly in terms of their stability properties, along the lines
|
|
being developed in Functions and Operators.</p>
|
|
</blockquote>
|
|
<blockquote>
|
|
<p><b><a href="#issue-context-dependent-functions">Issue 33
|
|
(context-dependent-functions)</a>:</b></p>
|
|
<p>The rules for binding of function items to context-dependent
|
|
functions need to be defined.</p>
|
|
</blockquote>
|
|
<blockquote>
|
|
<p><b><a href="#issue-streaming-conformance">Issue 34
|
|
(streaming-conformance)</a>:</b></p>
|
|
<p>We need to define the conformance rules for streaming
|
|
processors.</p>
|
|
</blockquote>
|
|
<blockquote>
|
|
<p><b><a href="#issue-schema-for-xslt21">Issue 35
|
|
(schema-for-xslt21)</a>:</b></p>
|
|
<p>This schema needs to be updated for XSLT 2.1</p>
|
|
</blockquote>
|
|
</div>
|
|
<div class="div1">
|
|
<h2><a name="changes-since-2.0" id="changes-since-2.0"></a>J
|
|
Changes since XSLT 2.0 (Non-Normative)</h2>
|
|
<ol class="enumar">
|
|
<li>
|
|
<p>A new <a href="#element-iterate"><code>xsl:iterate</code></a>
|
|
instruction is added. This allows iterative processing of a
|
|
sequence, with the ability for the processing of one item to depend
|
|
on the results of processing of previous items, and with the
|
|
ability to terminate the iteration before all the items in the
|
|
sequence have been processed.</p>
|
|
</li>
|
|
<li>
|
|
<p>A new <a href="#element-mode"><code>xsl:mode</code></a>
|
|
declaration is added, together with the ability for a stylesheet
|
|
module to declare a default mode. A mode may be declared to be
|
|
streamable, and rules are given that constrain what the template
|
|
rules in a streamable mode can do. A default mode can be declared
|
|
for a stylesheet module, making it easier to reuse existing
|
|
stylesheet modules to construct a composite stylesheet. The
|
|
<a href="#element-mode"><code>xsl:mode</code></a> declaration may
|
|
contain an <a href=
|
|
"#element-context-item"><code>xsl:context-item</code></a> element
|
|
to declare the expected type of the <a title="initial context item"
|
|
class="termref" href="#dt-initial-context-item">initial context
|
|
item</a> when this mode is the <a title="initial mode" class=
|
|
"termref" href="#dt-initial-mode">initial mode</a>.</p>
|
|
</li>
|
|
<li>
|
|
<p>A new instruction <a href=
|
|
"#element-stream"><code>xsl:stream</code></a> is provided, to read
|
|
and process an input document using streaming</p>
|
|
</li>
|
|
<li>
|
|
<p>A new instruction <a href=
|
|
"#element-merge"><code>xsl:merge</code></a> is provided. This
|
|
allows several input sequences to be merged into a single output
|
|
sequence, based on the value of a merge key.</p>
|
|
</li>
|
|
<li>
|
|
<p>A new function <a href=
|
|
"#function-unparsed-text-lines"><code>unparsed-text-lines</code></a>
|
|
is provided. This is similar to the <a href=
|
|
"#function-unparsed-text"><code>unparsed-text</code></a> function,
|
|
but delivers the result as a sequence of strings, rather than as a
|
|
single string.</p>
|
|
</li>
|
|
<li>
|
|
<p>New functions <a href=
|
|
"#function-innermost"><code>innermost</code></a> and <a href=
|
|
"#function-outermost"><code>outermost</code></a> are provided.
|
|
Where elements are recursively nested, these provide a simple way
|
|
to identify those nodes within a set of nodes that (a) have no
|
|
descendants within the set, or (b) have no ancestors. The intention
|
|
of these functions is to make streaming of documents easier when
|
|
they contain recursive structures.</p>
|
|
</li>
|
|
<li>
|
|
<p>New functions <a href=
|
|
"#function-copy-of"><code>copy-of</code></a> and <a href=
|
|
"#function-snapshot"><code>snapshot</code></a> are provided, to
|
|
enable streaming applications to operate in "windowing" mode, where
|
|
the input document is divided into a sequence of small subtrees
|
|
processed one at a time.</p>
|
|
</li>
|
|
<li>
|
|
<p>A new <a href="#element-try"><code>xsl:try</code></a>
|
|
instruction is provided, to allow recovery from dynamic errors.</p>
|
|
</li>
|
|
<li>
|
|
<p>A new <a href="#element-evaluate"><code>xsl:evaluate</code></a>
|
|
instruction is provided, to allow evaluation of XPath expressions
|
|
constructed dynamically from strings, or read from a source
|
|
document.</p>
|
|
</li>
|
|
<li>
|
|
<p>A new <a href="#element-fork"><code>xsl:fork</code></a>
|
|
instruction is introduced to allow multiple results to be computed
|
|
during a single pass of a streamed input document.</p>
|
|
</li>
|
|
<li>
|
|
<p>The syntax of <a title="pattern" class="termref" href=
|
|
"#dt-pattern">patterns</a> has been generalized. Patterns may now
|
|
match any item (not only nodes). In consequence, <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a> can
|
|
now process sequences of atomic values as well as nodes, and
|
|
<a href=
|
|
"#element-for-each-group"><code>xsl:for-each-group</code></a> with
|
|
the <code>group-starting-with</code> and
|
|
<code>group-ending-with</code> options can also process atomic
|
|
sequences. As a further consequence, the <a title=
|
|
"initial context item" class="termref" href=
|
|
"#dt-initial-context-item">initial context item</a> supplied when
|
|
initiating a transformation is no longer required to be a node.</p>
|
|
</li>
|
|
<li>
|
|
<p>The <a href="#element-copy"><code>xsl:copy</code></a>
|
|
instruction now has a <code>select</code> attribute, which is
|
|
convenient when it is used inside a function where there is no
|
|
context item.</p>
|
|
</li>
|
|
<li>
|
|
<p>A <a title="basic XSLT processor" class="termref" href=
|
|
"#dt-basic-xslt-processor">basic XSLT Processor</a> now recognizes
|
|
all the built-in types defined in XML Schema.</p>
|
|
</li>
|
|
<li>
|
|
<p>A <a title="basic XSLT processor" class="termref" href=
|
|
"#dt-basic-xslt-processor">basic XSLT Processor</a> will now accept
|
|
the attribute <code>validation="lax"</code> and interpret it in the
|
|
same way as a schema-aware processor when there is no schema
|
|
component available to perform the validation.</p>
|
|
</li>
|
|
<li>
|
|
<p>Some functions, including <code>generate-id</code>,
|
|
<code>format-date</code>, <code>format-dateTime</code>,
|
|
<code>format-number</code>, and <code>format-time</code> have been
|
|
moved from this specification to the core Functions and Operators
|
|
specification, to make them available in other host languages.</p>
|
|
</li>
|
|
</ol>
|
|
</div>
|
|
<div class="div1">
|
|
<h2><a name="incompatibilities" id="incompatibilities"></a>K
|
|
Incompatibilities with XSLT 2.0 (Non-Normative)</h2>
|
|
<p>This section lists all known incompatibilities with XSLT 2.0,
|
|
that is, situations where a stylesheet that is error-free according
|
|
to the XSLT 2.0 specification and where all elements have an
|
|
effective version of <code>2.0</code> or less, will produce
|
|
different results depending on whether it is run under an XSLT 2.0
|
|
processor or an XSLT 2.1 processor.</p>
|
|
<ol class="enumar">
|
|
<li>
|
|
<p>XSLT 2.0 gave implementations freedom what to do when a node
|
|
selected by <a href=
|
|
"#element-apply-templates"><code>xsl:apply-templates</code></a>
|
|
matched more than one <a title="template rule" class="termref"
|
|
href="#dt-template-rule">template rule</a>. XSLT 2.1 is more
|
|
prescriptive in this situation. The behavior prescribed in XSLT 2.1
|
|
(selecting the template rule that is last in <a title=
|
|
"declaration order" class="termref" href=
|
|
"#dt-declaration-order">declaration order</a>) is compatible with
|
|
the action of some XSLT 2.0 processors but not necessarily
|
|
others.</p>
|
|
</li>
|
|
</ol>
|
|
</div>
|
|
</div>
|
|
</body>
|
|
</html>
|