[Definition: The two
elements xsl:variable
and xsl:param
are referred to
as variable-binding elements
].
[Definition: The xsl:variable
element
declares a variable, which may be a global variable or a local
variable.]
[Definition: The xsl:param
element
declares a parameter, which may be a stylesheet parameter, a template parameter, a function parameter, or an xsl:iterate
parameter. A parameter is a
variable with the additional property that
its value can be set by the caller.]
[Definition: A variable is a binding between a name and a value. The value of a variable is any sequence (of nodes, atomic values, and/or function items), as defined in [XDM 3.0].]
<!-- Category: declaration -->
<!-- Category: instruction -->
<xsl:variable
name = eqname
select? = expression
as? = sequence-type
static? = boolean
visibility? = "public" | "private" | "final" | "abstract" >
<!-- Content: sequence-constructor -->
</xsl:variable>
The xsl:variable
element has a required
name
attribute, which specifies the name of the variable. The value of
the name
attribute is an EQName, which is expanded as described in
5.1.1 Qualified Names.
The xsl:variable
element has an optional as
attribute,
which specifies the required type of the
variable. The value of the as
attribute is a
SequenceType.
[Definition: The value of the variable is
computed using the expression given in the
select
attribute or the contained sequence constructor, as described in
9.3 Values of Variables and Parameters. This value is referred to as the
supplied value of the variable.] If the
xsl:variable
element has a select
attribute, then
the sequence constructor must be empty.
If the as
attribute is specified, then the supplied value of the variable is converted to
the required type, using the function
conversion rules.
[ERR XTTE0570] It is a type error if the supplied value of a variable cannot be converted to the required type.
If the as
attribute is omitted, the supplied value of the variable is used directly, and no conversion
takes place.
For the effect of the static
attribute, see 9.6 Static Variables and Parameters.
The visibility
attribute must not
be specified for a local variable: that is, it is allowed only when the parent
element is xsl:stylesheet
, xsl:transform
,
xsl:package
or
xsl:override
.
If the visibility
attribute is present with the value
abstract
then the select
attribute
must be absent and the contained sequence constructor
must be empty. In this situation there is no supplied value, and therefore the constraint
that the supplied value is consistent with the required type does not apply.
<!-- Category: declaration -->
<xsl:param
name = eqname
select? = expression
as? = sequence-type
required? = boolean
tunnel? = boolean
static? = boolean >
<!-- Content: sequence-constructor -->
</xsl:param>
The xsl:param
element may be used:
As a child of xsl:stylesheet
or xsl:package
, to
define a parameter to the transformation. Stylesheet parameters are set by the
calling application: see 2.3.2 Priming a Stylesheet.
As a child of xsl:template
to define a parameter to a
template, which may be supplied when the template is invoked using
xsl:call-template
, xsl:apply-templates
,
xsl:apply-imports
or xsl:next-match
.
Template parameters are set
by means of an xsl:with-param
child element of the invoking
instruction, as described in 9.10 Setting Parameter Values.
As a child of xsl:function
to define a parameter to a
stylesheet function, which may be supplied when the function is called from an
XPath expression. Function parameters are set
positionally by means of the argument list in an XPath function call.
As a child of xsl:iterate
to define a parameter that can vary
from one iteration to the next. Iteration parameters always take their default
values for the first iteration, and in subsequent iterations are set using an
xsl:with-param
child of the
xsl:next-iteration
instruction.
The attributes applicable to xsl:param
depend on its parent element in the stylesheet, as defined by the following
table:
Parent Element | name | select | as | required | tunnel | static |
---|---|---|---|---|---|---|
xsl:package |
mandatory | optional | optional | yes|no | no | yes|no |
xsl:stylesheet |
mandatory | optional | optional | yes|no | no | yes|no |
xsl:template |
mandatory | optional | optional | yes|no | yes|no | no |
xsl:function |
mandatory | disallowed | optional | yes | no | no |
xsl:iterate |
mandatory | mandatory | optional | no | no | no |
In the table, the entries for the name
,
select
, and as
attributes indicate whether the attribute
must appear, is optional, or must be absent; the entries for the
required
, tunnel
, and static
attributes
indicate the values that are permitted if the attribute is present, with the default
value shown in bold. (The value yes
can also be written
true
or 1
, while no
can also be written
false
or 0
.)
The name
attribute is mandatory: it specifies the name of the parameter.
The value of the name
attribute is an EQName, which is expanded as described in
5.1.1 Qualified Names.
[ERR XTSE0580] It is a static error if the values of
the name
attribute of two sibling
xsl:param
elements represent the same expanded QName.
If the xsl:param
element has a select
attribute, then
the sequence constructor must be empty.
The static
attribute can take the value yes
only on stylesheet parameters, and is explained in
9.5 Global Variables and Parameters.
Note:
Local variables may shadow template parameters and function parameters: see 9.9 Scope of Variables.
The optional tunnel
attribute may be used to indicate that a parameter
is a tunnel parameter. The default is
no
; the value yes
may be specified only for template parameters. Tunnel parameters are
described in 10.1.3 Tunnel Parameters
The xsl:param
element has an optional as
attribute,
which specifies the required type of the parameter. The value
of the as
attribute is a
SequenceType.
If the as
attribute is omitted, then the
required type is item()*
.
The supplied value 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 default value is used as the supplied value as described in 9.2.2 Default Values of Parameters.
The supplied value of the parameter is converted to the required type using the function conversion rules.
[ERR XTTE0590] It is a type error if the conversion of the supplied value of a parameter to its required type fails.
The optional required
attribute of
xsl:param
may be used to indicate that a stylesheet parameter or template parameter is
mandatory. The only value permitted for a function parameter
is yes
(these are always mandatory), and the only value permitted for
a parameter to xsl:iterate
is no
(these are always
initialized to a default value).
[Definition: A parameter is
explicitly mandatory if it is a function parameter, or if the
required
attribute is present and has the value
yes
.] If a parameter is explicitly mandatory, then the
xsl:param
element must be empty and
must not have a select
attribute.
If a parameter is not explicitly mandatory, then it may have a
default value. The default value is obtained by evaluating the expression given in the select
attribute or the contained sequence
constructor, as described in 9.3 Values of Variables and Parameters.
Note:
This specification does not dictate whether and when the default value of a
parameter is evaluated. For example, if the default is specified as
<xsl:param name="p"><foo/></xsl:param>
, then
it is not specified whether a distinct foo
element node will be
created on each invocation of the template, or whether the same
foo
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.
[Definition: An explicit
default for a parameter is indicated by the presence of either a
select
attribute or a non-empty sequence
constructor.]
[Definition: If a parameter that is
not explicitly mandatory has no explicit default value, then it has an implicit
default value, which is the empty sequence if there is an
as
attribute, or a zero-length string if not.]
[Definition: If a parameter
has an implicit default value which cannot be converted to
the required type (that is, if it has an as
attribute which does not permit the empty sequence), then the parameter is
implicitly mandatory.]
Note:
The effect of these rules is that specifying <xsl:param name="p"
as="xs:date" select="2"/>
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, <xsl:param name="p"
as="xs:date"/>
is treated as if required="yes"
had
been specified: the empty sequence is not a valid instance of
xs:date
, so in effect there is no default value and the
parameter is therefore treated as being mandatory.
Various errors can arise with regard to mandatory parameters when no value is
supplied. In the rules below, non-tunnel means: not having a
tunnel
attribute with the value yes
.
[ERR XTSE3520] It is a static error if a parameter to xsl:iterate
is
implicitly mandatory.
[ERR XTSE0690] It is a static error if a
package contains both (a) a
named template named T that is not overridden by another
named template of higher import precedence and that has an explicitly mandatory non-tunnel parameter named
P, and (b) an xsl:call-template
instruction whose name
attribute equals T and
that has no non-tunnel xsl:with-param
child element
whose name
attribute equals P. (All names are
compared as QNames.)
[ERR XTDE0700] It is a dynamic error if a template that has an explicitly mandatory or implicitly mandatory parameter is invoked without supplying a value for that parameter.
This includes the following cases:
The template is invoked using xsl:apply-templates
,
xsl:apply-imports
, or
xsl:next-match
and there is no
xsl:with-param
child whose name
and
tunnel
attributes match the corresponding attributes
of the mandatory parameter.
The mandatory parameter is a tunnel parameter, and the template is
invoked using xsl:call-template
, and there is no
xsl:with-param
child whose name
and
tunnel
attributes match the corresponding attributes
of the mandatory parameter.
The template is invoked as the entry point to the transformation, either by invoking an initial mode (2.3.3 Apply-Templates Invocation) or by invoking an initial template (2.3.4 Call-Template Invocation) and no value is supplied for the mandatory parameter by the calling application.
A variable-binding element may specify the supplied value of a variable or the default value of a parameter in four different ways.
If the variable-binding
element has a select
attribute, then the value of the
attribute must be an expression and the supplied
value of the variable is the value that results from evaluating
the expression. In this case, the content of the variable-binding element
must be empty.
If the variable-binding
element has empty content and has neither a select
attribute nor an as
attribute, then the supplied value of the variable is a
zero-length string. Thus
<xsl:variable name="x"/>
is equivalent to
<xsl:variable name="x" select="''"/>
If a variable-binding
element has no select
attribute and has non-empty
content (that is, the variable-binding element has one or more child nodes),
and has no as
attribute, then the content of the variable-binding
element specifies the supplied
value. The content of the variable-binding element is a sequence constructor; 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 5.7.1 Constructing Complex Content. The value of
the variable is then a singleton sequence containing this document node. For
further information, see 9.4 Creating Implicit Document Nodes.
If a variable-binding
element has an as
attribute but no
select
attribute, then the supplied value is the sequence that results from evaluating the
(possibly empty) sequence
constructor contained within the variable-binding element (see
5.7 Sequence Constructors).
These combinations are summarized in the table below.
select attribute | as attribute | content | Effect |
---|---|---|---|
present | absent | empty | Value is obtained by evaluating the select
attribute
|
present | present | empty | Value is obtained by evaluating the select
attribute, adjusted to the type required by the as
attribute
|
present | absent | present | Static error |
present | present | present | Static error |
absent | absent | empty | Value is a zero-length string |
absent | present | empty | Value is an empty sequence, provided the as
attribute permits an empty sequence
|
absent | absent | present | Value is a document node whose content is obtained by evaluating the sequence constructor |
absent | present | present | Value is obtained by evaluating the sequence constructor,
adjusted to the type required by the as attribute
|
[ERR XTSE0620] It is a static error if a variable-binding element has a
select
attribute and has non-empty content.
The value of the following variable is the sequence of integers (1, 2, 3):
<xsl:variable name="i" as="xs:integer*" select="1 to 3"/>
The value of the following variable is an integer, assuming that the attribute
@size
exists, and is annotated either as an integer, or as
xs:untypedAtomic
:
<xsl:variable name="i" as="xs:integer" select="@size"/>
The value of the following variable is a zero-length string:
<xsl:variable name="z"/>
The value of the following variable is a document node containing an empty element as a child:
<xsl:variable name="doc"><c/></xsl:variable>
The value of the following variable is a sequence of integers (2, 4, 6):
<xsl:variable name="seq" as="xs:integer*"> <xsl:for-each select="1 to 3"> <xsl:sequence select=".*2"/> </xsl:for-each> </xsl:variable>
The value of the following variable is a sequence of parentless attribute nodes:
<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>
The value of the following variable is an empty sequence:
<xsl:variable name="empty" as="empty-sequence()"/>
The actual value of the variable depends on the supplied value, as described above, and the required type, which is
determined by the value of the as
attribute.
When a variable is used to select nodes by position, be careful not to do:
<xsl:variable name="n">2</xsl:variable> ... <xsl:value-of select="td[$n]"/>
This will output the values of all the td
elements, space-separated
(or with XSLT 1.0
behavior, the value of the first td
element), because the variable n
will be bound to a node, not a
number. Instead, do one of the following:
<xsl:variable name="n" select="2"/> ... <xsl:value-of select="td[$n]"/>
or
<xsl:variable name="n">2</xsl:variable> ... <xsl:value-of select="td[position()=$n]"/>
or
<xsl:variable name="n" as="xs:integer">2</xsl:variable> ... <xsl:value-of select="td[$n]"/>
A document node is created implicitly when evaluating an
xsl:variable
, xsl:param
, or
xsl:with-param
element that has non-empty content and that has no
as
attribute. The value of the variable is this newly constructed
document node.
The content of the
document node is formed from the result of evaluating the sequence constructor contained within the
variable-binding element, as described in 5.7.1 Constructing Complex Content.
Note:
The construct:
<xsl:variable name="tree"> <a/> </xsl:variable>
can be regarded as a shorthand for:
<xsl:variable name="tree" as="document-node()"> <xsl:document validation="preserve"> <a/> </xsl:document> </xsl:variable>
The base URI of the document node is taken from the base URI of the variable binding element in the stylesheet. (See Section 5.2 base-uri Accessor DM30 in [XDM 3.0])
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.
Note:
The base URI of other nodes in the tree is determined by the rules for
constructing complex content (see 5.7.1 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 variable-binding element. Thus, the base URI of the document node
will be equal to the base URI of the variable-binding element, while an
xml:base
attribute within the temporary tree will change the base
URI for its parent element and that element’s descendants, just as it would
within a document constructed by parsing.
The document-uri
and unparsed-entities
properties of the
new document node are set to empty.
A temporary tree is available for
processing in exactly the same way as any source document. For example, its nodes
are
accessible using path expressions, and they can be processed using instructions such
as xsl:apply-templates
and xsl:for-each
. Also, the
key
and id
FO30 functions can be used to
find nodes within a temporary tree, by supplying the
document node at the root of the tree as an argument to the function or by making
it the context node.
The following stylesheet uses a temporary tree as the intermediate
result of a two-phase transformation, using different modes for the two phases (see 6.6 Modes). Typically,
the template rules in module phase1.xsl
will be declared with
mode="phase1"
, while those in module phase2.xsl
will
be declared with mode="phase2"
:
<xsl:stylesheet version="3.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> <xsl:import href="phase1.xsl"/> <xsl:import href="phase2.xsl"/> <xsl:variable name="intermediate"> <xsl:apply-templates select="/" mode="phase1"/> </xsl:variable> <xsl:template match="/"> <xsl:apply-templates select="$intermediate" mode="phase2"/> </xsl:template> </xsl:stylesheet>
Note:
The algorithm for matching nodes against template rules is exactly the same regardless which tree the nodes come from. If different template rules are to be used when processing different trees, then unless nodes from different trees can be distinguished by means of patterns, it is a good idea to use modes to ensure that each tree is processed using the appropriate set of template rules.
Both xsl:variable
and xsl:param
are allowed as
declaration elements: that is, they may
appear as children of the xsl:package
or
xsl:stylesheet
element.
[Definition: A top-level variable-binding element declares a global variable that is visible everywhere (except within its own declaration, and where it is shadowed by another binding).]
[Definition: A top-level
xsl:param
element declares a stylesheet
parameter. 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.] As described in 9.2 Parameters, 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 implementation-defined. An XSLT processor
must provide such a mechanism.
It is an error if no value is supplied for a mandatory stylesheet parameter [see ERR XTDE0050].
If a stylesheet contains more than one binding for a global variable of a particular name, then the binding with the highest import precedence is used.
[ERR XTSE0630] It is a static error if a package contains more than one non-hidden binding of a global variable with the same name and same import precedence, unless it also contains another binding with the same name and higher import precedence.
For a global variable or the default value of a stylesheet parameter, the expression or sequence constructor specifying the variable value is evaluated with a singleton focus as follows:
If the declaration appears within the top-level package
(including within an xsl:override
element in the top-level
package), then the focus is based on the global context item if supplied, or absent otherwise.
If the declaration appears within a library package, then the focus is absent.
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 the focus is absent. The values of other components of the dynamic context are the initial values as defined in 5.3.3 Initializing the Dynamic Context and 5.3.4 Additional Dynamic Context Components used by XSLT.
The visibility of a stylesheet parameter is always (implicitly) private
if the
parameter is static
, or public
if the parameter is
non-static.
Note:
This rule has the effect that after combining all the packages making up a stylesheet, the non-static stylesheet parameters whose values are required necessarily have distinct names, which simplifies the design of APIs.
For the effect of the static
attribute, see 9.6 Static Variables and Parameters.
The visibility
attribute must
not be specified for a local variable: that is, it is allowed only when
the parent element is xsl:package
, xsl:stylesheet
,
xsl:transform
, or xsl:override
.
If the visibility
attribute is present with the value
abstract
then the select
attribute
must be absent and the contained sequence constructor
must be empty. In this situation there is no supplied value, and therefore the constraint
that the supplied value is consistent with the required type does not apply.
The following example declares a global parameter para-font-size
,
which is referenced in an attribute
value template.
<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>
The implementation must provide a mechanism allowing the user to supply a value
for the parameter para-font-size
when invoking the stylesheet; the
value 12pt
acts as a default.
Static variables and parameters are global variables and can be used in the same way
as other global variables. In addition, they can be used in
[xsl:]use-when
expressions and in shadow attributes.
[Definition: A top-level
variable-binding element
having the attribute static="yes"
declares a static
variable: that is, a global variable whose value is
known during static analysis of the stylesheet.]
[Definition: A static variable declared using an xsl:param
element
is referred to as a static parameter.]
The static
attribute must not
take the value yes
on an
xsl:variable
or xsl:param
element unless it is a
top-level element.
When the static
attribute is present with the value
yes
, the visibility
attribute must
not have a value other than private
.
Note:
This rule prevents static variables being overridden in another package. Since the
values of such variables may be used at compile time (for example, during
processing of [xsl:]use-when
expressions), the rule is necessary to
ensure that packages can be independently compiled.
It is possible to make the value of a static variable or parameter available in a using package by binding a non-static public variable to its value, for example:
<xsl:param name="DEBUG" static="yes" select="true()"/> <xsl:variable name="tracing" static="no" visibility="public" select="$DEBUG"/>
When the attribute static="yes"
is specified, the
xsl:variable
or xsl:param
element
must have empty content. In the case of
xsl:variable
the select
attribute must be present to
define the value of the variable [see ERR XTSE0010].
If the select
attribute is present, then it is evaluated using the rules
for static expressions.
The rules for the scope of static variables, and the
handling of duplicate declarations, are similar to the rules for non-static
variables, but with additional constraints designed to disallow forwards references.
The reason for disallowing forwards references is to ensure that
use-when
attributes can always be evaluated as early as possible, and
in particular to ensure that the value of a use-when
attribute never has
circular dependencies. The additional constraints are as follows:
The static context for evaluation of a static expression
only contains those static
variables visible within the containing package whose declarations
occur prior to the element containing the static expression in stylesheet tree
order. Stylesheet tree order is the order that results when all
xsl:import
and xsl:include
declarations
are replaced by the declarations in the imported or included stylesheet module.
A static variable is not in scope within its own declaration.
If two static variables declared within the same package have the same name,
the one that has higher import precedence is used (it is a
consequence of rules defined elsewhere that there cannot be more than one
declaration with highest import precedence). However, if the declaration with
higher import precedence occurs after the one with lower import precedence in
stylesheet tree order, then the two declarations must be consistent. For this
purpose two declarations are consistent if (a) they are either both
xsl:variable
elements, or both xsl:param
elements, and (b) if the variables are initialized (that is, if the elements
are xsl:variable
elements, or if they are
xsl:param
elements and no value for the parameter is
externally supplied) then the values of both variables must be identicalFO30, and must not contain
function items.
Note:
This rule ensures that when a static variable reference is encountered, the value of the most recently declared static variable with that name can be used, knowing that this value cannot be overridden by a subsequent declaration having higher import precedence.
[ERR XTSE3450] It is a static error if a
variable declared with static="yes"
is inconsistent with
another static variable of the same name that is declared earlier in
stylesheet tree order and that has lower import precedence.
[Definition: A static expression is an XPath expression whose value must be computed during static analysis of the stylesheet.]
Static expressions appear in a number of contexts, in particular:
In [xsl:]use-when
attributes (see 3.13.1 Conditional Element Inclusion);
In the select
attribute of static variable
declarations (xsl:variable
or xsl:param
with
static="yes"
);
In shadow attributes (see 3.13.2 Shadow Attributes).
There are no syntactic constraints on the XPath expression that can be used as a static expression. 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.
Specifically, the components of the static and dynamic context are defined by the following two tables:
Component | Value |
---|---|
XPath 1.0 compatibility mode | false |
Statically known namespaces | determined by the in-scope namespaces for the containing element in the stylesheet |
Default element/type namespace | determined by the xpath-default-namespace attribute if present
(see 5.1.2 Unprefixed Lexical QNames in Expressions and Patterns); otherwise the null namespace
|
Default function namespace | The standard function namespace |
In-scope schema types | The type definitions that would be available in the absence of any
xsl:import-schema declaration
|
In-scope element declarations | None |
In-scope attribute declarations | None |
In-scope variables | The static
variables visible within the containing package whose
declarations occur prior to the element containing the static expression in
stylesheet tree order. Stylesheet tree order is the order that results when
all xsl:import and xsl:include
declarations are replaced by the declarations in the imported or included
stylesheet module. A static variable is not in scope within its own
declaration, and it is in scope only within its
declaring package, not in any using packages. If two static
variables satisfying this rule have the same name and are both in scope, the
one that appears most recently in stylesheet tree order is used; as a
consequence of rules defined elsewhere this will always be consistent with
the declaration having highest import precedence.
|
Context item static type | Absent |
Statically known function signatures | The functions defined in [Functions and Operators 3.0] in the fn
and math namespaces, together with:
function-available will return false in
respect of such functions, and function-lookup FO30 will
fail to find them. The effect of this rule is to ensure that
function-available returns true in respect of
functions that can be called within the static expression. It also has the
effect that these extension functions will be recognized within the static
expression itself; however, the fact that a function is available in this
sense gives no guarantee that a call on the function will succeed.
|
Statically known collations | Implementation-defined |
Default collation | The Unicode Codepoint Collation |
Static Base URI | The base URI of the containing element in the stylesheet document (see Section 5.2 base-uri Accessor DM30) |
Statically known documents | Implementation-defined |
Statically known collections | Implementation-defined |
Statically known default collection type | Implementation-defined |
Statically known decimal formats | A single unnamed decimal format
equivalent to the decimal format that is created by an
xsl:decimal-format declaration with no attributes.
|
Component | Value |
---|---|
Context item, position, and size | Absent |
Variable values | A value for every variable present in the in-scope variables. For static parameters where an external value is supplied: the externally-supplied value of the parameter. In all other cases: the value of the variable as defined in 9.3 Values of Variables and Parameters. |
Named functions | The function implementation corresponding to each function signature in the statically known function signatures |
Current dateTime | Implementation-defined |
Implicit timezone | Implementation-defined |
Default language | Implementation-defined |
Default calendar | Implementation-defined |
Default place | Implementation-defined |
Available documents | Implementation-defined |
Available collections | Implementation-defined |
Default collection | Implementation-defined |
Environment variables | Implementation-defined |
Within a stylesheet module, all static
expressions are evaluated in a single execution scopeFO30. This need not be the same execution scope as that
used for static 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 current-date
FO30 will return the same
result when called in different [xsl:]use-when
expressions within the
same stylesheet module, but will not necessarily return the same result as the same
call in an [xsl:]use-when
expression within a different stylesheet
module, or as a call on the same function executed during the transformation
proper.
If a static error is present in a static expression, it is treated in the same way as any other static error in the stylesheet module. If a dynamic error occurs during evaluation of a static expression, it is treated as a static error in the analysis of the stylesheet, while retaining its original error code.
[Definition: As well as being allowed as a
declaration, the
xsl:variable
element is also allowed in sequence constructors. Such a variable
is known as a local variable.]
An xsl:param
element may also be used to create a variable binding
with local scope:
[Definition: An
xsl:param
element may appear as a child of an
xsl:template
element, before any
non-xsl:param
children of that element. Such a parameter
is known as a template parameter. A template parameter is a
local variable with the
additional property that its value can be set when the template is called,
using any of the instructions xsl:call-template
,
xsl:apply-templates
, xsl:apply-imports
,
or xsl:next-match
.]
[Definition: An
xsl:param
element may appear as a child of an
xsl:function
element, before any
non-xsl:param
children of that element. Such a parameter
is known as a function parameter. A function parameter is a
local variable with the
additional property that its value can be set when the function is called,
using a function call in an XPath expression.]
An xsl:param
element may appear as a child
of an xsl:iterate
instruction, before any
non-xsl:param
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
xsl:with-param
element in the
xsl:next-iteration
instruction.
The result of evaluating a local xsl:variable
or
xsl:param
element (that is, the contribution it makes to the
result of the sequence constructor it is part of) is an empty
sequence.
For any variable-binding element, there is a region (more specifically, a set of nodes) of the stylesheet within which the binding is visible. The set of variable bindings in scope for an XPath expression consists of those bindings that are visible at the point in the stylesheet where the expression occurs.
A global variable binding
element is visible everywhere in the containing package
(including other stylesheet modules) except within the xsl:variable
or
xsl:param
element itself and any region where it is shadowed by another variable binding.
(For rules regarding the visibility of the variable
in other packages, see 3.5.3.1 Visibility of Components.)
A local variable binding element is visible for all following siblings and their descendants, with the following exceptions:
It is not visible in any region where it is shadowed by another variable binding.
It is not visible within the subtree rooted at an xsl:fallback
instruction that is a sibling of the variable binding element.
It is not visible within the subtree rooted at an
xsl:catch
instruction that is a sibling of the variable
binding element.
The binding is not visible for the xsl:variable
or
xsl:param
element itself.
If a binding is visible for an element then it is visible for every attribute of that element and for every text node child of that element.
[Definition: A binding shadows another
binding if the binding occurs at a point where the other binding is visible, and
the bindings have the same name. ] It is not an error if a binding
established by a local xsl:variable
or xsl:param
shadows a global binding. In this case, the
global binding will not be visible in the region of the stylesheet where it is shadowed by the other binding.
The following is allowed:
<xsl:param name="x" select="1"/> <xsl:template name="foo"> <xsl:variable name="x" select="2"/> </xsl:template>
It is also not an error if a binding established by a local
xsl:variable
element shadows
a binding established by another local xsl:variable
or
xsl:param
.
The following is not an error, but the effect is probably not what was intended.
The template outputs <x value="1"/>
, because the declaration of
the inner variable named $x
has no effect on the value of the outer
variable named $x
.
<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>
Note:
Once a variable has been given a value, the value cannot subsequently be changed. XSLT does not provide an equivalent to the assignment operator available in many procedural programming languages.
This is because an assignment operator would make it harder to create an implementation that processes a document other than in a batch-like way, starting at the beginning and continuing through to the end.
As well as global variables and local variables, an XPath expression may also declare range variables for use locally within an expression. For details, see [XPath 3.0].
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.
<xsl:with-param
name = eqname
select? = expression
as? = sequence-type
tunnel? = boolean >
<!-- Content: sequence-constructor -->
</xsl:with-param>
Parameters are passed to templates using the xsl:with-param
element.
The required
name
attribute specifies the name of the template parameter (the variable the value
of whose binding is to be replaced). The value of the name
attribute is
an EQName,
which is expanded as described in 5.1.1 Qualified Names.
The xsl:with-param
element is also used
when passing parameters to an iteration of the xsl:iterate
instruction, or to a dynamic invocation of an XPath expression using
xsl:evaluate
. In consequence,
xsl:with-param
may appear within
xsl:apply-templates
, xsl:apply-imports
,
xsl:call-template
, xsl:evaluate
, xsl:next-iteration
,
and xsl:next-match
. (Arguments to stylesheet functions, however, are supplied
as part of an XPath function call: see 10.3 Stylesheet Functions.)
[ERR XTSE0670] It is a static error
if two or more sibling xsl:with-param
elements have
name
attributes that represent the same expanded QName.
The value of the parameter is specified in the same way as for
xsl:variable
and xsl:param
(see 9.3 Values of Variables and Parameters), taking account of the values of the select
and as
attributes and the content of the xsl:with-param
element, if any.
Note:
It is possible to have an as
attribute on the
xsl:with-param
element that differs from the as
attribute on the corresponding xsl:param
element.
In this situation, the supplied value of the parameter will first be processed
according to the rules of the as
attribute on the
xsl:with-param
element, and the resulting value will then be
further processed according to the rules of the as
attribute on the
xsl:param
element.
For example, suppose the supplied value is a node with type annotation
xs:untypedAtomic
, and the xsl:with-param
element
specifies as="xs:integer"
, while the xsl:param
element specifies as="xs:double"
. Then the node will first be
atomized and the resulting untyped atomic value will be cast to
xs:integer
. If this succeeds, the xs:integer
will
then be promoted to an xs:double
.
The focus used for computing the value specified by
the xsl:with-param
element is the same as that used for its parent instruction.
The optional tunnel
attribute may be used to indicate that a parameter
is a tunnel parameter. The default is
no
. Tunnel parameters are described in 10.1.3 Tunnel Parameters. They are used only when passing parameters to templates: for an
xsl:with-param
element that is a child of
xsl:evaluate
or xsl:next-iteration
the
tunnel
attribute must either be omitted or take
the value no
.
In other cases it is a dynamic error if the template that is
invoked declares a template parameter
with required="yes"
and no value for this parameter is supplied by the
calling instruction. [see ERR XTDE0700]
[Definition: A circularity is said to exist if a construct such as a global variable, an attribute set, or a key, is defined in terms of itself. For example, if the expression or sequence constructor specifying the value of a global variable X references a global variable Y, then the value for Y must be computed before the value of X. A circularity exists if it is impossible to do this for all global variable definitions.]
The following two declarations create a circularity:
<xsl:variable name="x" select="$y+1"/> <xsl:variable name="y" select="$x+1"/>
The definition of a global variable can be circular even if no other variable is
involved. For example the following two declarations (see 10.3 Stylesheet Functions for an explanation of the
xsl:function
element) also create a circularity:
<xsl:variable name="x" select="my:f()"/> <xsl:function name="my:f"> <xsl:sequence select="$x"/> </xsl:function>
The definition of a variable is also circular if the evaluation of the variable
invokes an xsl:apply-templates
instruction and the variable is
referenced in the pattern used in the match
attribute of any template
rule in the stylesheet. For example the
following definition is circular:
<xsl:variable name="x"> <xsl:apply-templates select="//param[1]"/> </xsl:variable> <xsl:template match="param[$x]">1</xsl:template>
Similarly, a variable definition is circular if it causes a call on the
key
function, and the definition of that key refers to that variable in its match
or
use
attributes. So the following definition is circular:
<xsl:variable name="x" select="my:f(10, /)"/> <xsl:function name="my:f"> <xsl:param name="arg1"/> <xsl:param name="top"/> <xsl:sequence select="key('k', $arg1, $top)"/> </xsl:function> <xsl:key name="k" match="item[@code=$x]" use="@desc"/>
An attribute set is circular if its use-attribute-sets
attribute
references itself, directly or indirectly. So the following definitions establish
a circularity:
<xsl:attribute-set name="a" use-attribute-sets="b"/> <xsl:attribute-set name="b" use-attribute-sets="a"/>
Because attribute sets can invoke functions, global variables, or templates, and can also include instructions such as literal result elements that themselves invoke attribute sets, examples of circularity involving attribute sets can be more complex than this simple example illustrates. It is also possible to construct examples in which self-reference among attribute sets could be regarded as (terminating or non-terminating) recursion. However, because such self-references have no practical utility, any requirement to evaluate an attribute set in the course of its own evaluation is considered an error.
Note:
In previous versions of this specification, self-reference among attribute sets was defined as a static error. In XSLT 3.0 it is not always detectable statically, because attribute sets can bind to each other across package boundaries. Nevertheless, in cases where a processor can detect a static circularity, it can report this error during the analysis phase, under the general provision for reporting dynamic errors during stylesheet analysis if execution can never succeed.
[ERR XTDE0640] In general, a circularity in a stylesheet is a dynamic error. However, as with all other dynamic errors, an implementation will signal the error only if it actually executes the instructions and expressions that participate in the circularity. Because different implementations may optimize the execution of a stylesheet in different ways, it is implementation-dependent whether a particular circularity will actually be signaled.
For example, in the following declarations, the function declares a local variable
$b
, but it returns a result that does not require the variable to be
evaluated. It is implementation-dependent whether the value is actually evaluated, and
it is therefore implementation-dependent whether the circularity is signaled as an
error:
<xsl:variable name="x" select="my:f(1)"/> <xsl:function name="my:f"> <xsl:param name="a"/> <xsl:variable name="b" select="$x"/> <xsl:sequence select="$a + 2"/> </xsl:function>
Although a circularity is detected as a dynamic error,
there is no unique instruction whose evaluation triggers the error condition, and
the
result of any attempt to catch the error using an xsl:try
instruction is therefore implementation-dependent.
Circularities usually involve global variables or parameters, but they can also exist
between key definitions (see 20.2 Keys),
between named attribute sets (see 10.2 Named Attribute Sets), or between any combination of these constructs. For
example, a circularity exists if a key definition invokes a function that references
an attribute set that calls the key
function, supplying the name
of the original key definition as an argument.
Circularity is not the same as recursion. Stylesheet functions (see 10.3 Stylesheet Functions) and named templates (see 10.1 Named Templates) may call other functions and named templates without restriction. With careless coding, recursion may be non-terminating. Implementations are required to signal circularity as a dynamic error, but they are not required to detect non-terminating recursion.
The requirement to report a circularity as a dynamic error overrides the rule that dynamic errors in evaluating patterns are normally masked (by treating the pattern as not matching).