9 Variables and Parameters

[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].]

9.1 Variables

<!-- 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.

9.2 Parameters

<!-- 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:

The attributes applicable to xsl:param depend on its parent element in the stylesheet, as defined by the following table:

Attributes of the xsl:param Element
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

9.2.1 The Required Type of a Parameter

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.

9.2.2 Default Values of Parameters

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.

9.3 Values of Variables and Parameters

A variable-binding element may specify the supplied value of a variable or the default value of a parameter in four different ways.

These combinations are summarized in the table below.

Effect of Different Attribute Combinations on xsl:variable
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.

Example: Values of Variables

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.

Example: Pitfalls with Numeric Predicates

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]"/>

9.4 Creating Implicit Document Nodes

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 idFO30 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.

Example: Two-Phase Transformation

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.

9.5 Global Variables and Parameters

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:

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.

Example: A Stylesheet Parameter

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.

9.6 Static Variables and Parameters

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:

  1. 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.

  2. 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.

9.7 Static Expressions

[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:

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:

Static Context Components for Static Expressions
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:
  1. the functions element-available, function-available, type-available, available-system-properties, and system-property defined in this specification;

  2. functions that appear in both this specification and in [Functions and Operators 3.1] (for example, the functions in the map namespaces, and a few others such as collation-key and json-to-xml);

  3. if XPath 3.1 is supported, functions defined in [Functions and Operators 3.1] in the fn, math, map, and array namespaces;

  4. constructor functions for built-in types;

  5. the set of extension functions that are present in the static context of every XPath expression (other than a static expression) within the content of the element that contains the static expression.

Note that stylesheet functions are not included in the context, which means that the function function-available will return false in respect of such functions, and function-lookupFO30 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.

 

Dynamic Context Components for Static Expressions
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-dateFO30 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.

9.8 Local Variables and Parameters

[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:

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.

9.9 Scope of Variables

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:

  1. It is not visible in any region where it is shadowed by another variable binding.

  2. It is not visible within the subtree rooted at an xsl:fallback instruction that is a sibling of the variable binding element.

  3. 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.

Example: Local Variable Shadowing a Global Variable

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.

Example: Misuse of Variable Shadowing

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.

9.10 Setting Parameter Values

<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]

9.11 Circular Definitions

[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.]

Example: Circular Variable Definitions

The following two declarations create a circularity:

<xsl:variable name="x" select="$y+1"/>
<xsl:variable name="y" select="$x+1"/>

 

Example: Circularity involving Variables and Functions

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>

 

Example: Circularity involving Variables and Templates

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>

 

Example: Circularity involving Variables and Keys

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"/>

 

Example: Circularity involving Attribute Sets

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).