EXSLT - func:function - Version 2

The exsl:function element can only occur at the top level of the stylesheet. The exsl:function element declares an extension function that is visible everywhere: the extension function is added to the function library available to the expressions and patterns used in the XSLT stylesheet.

An exsl:function element must have a name attribute, indicating the name of the function. The value of the name attribute is a QName, which is expanded as described in Section 2.4 [Qualified Names] in the XSLT 1.0 Recommendation. It is an error if the namespace URI of the expanded name of the function is null - extension functions must not be in a null namespace.

Note: the rules on resolving qualified names entail that if no prefix is defined, the namespace URI resolves to the null namespace. Thus, it is an error if the qualified name specified does not have a prefix.

It is an error if a stylesheet contains more than one exsl:function element with the same name and the same import precedence. An XSLT processor may signal the error; if it does not signal the error, it must recover by using the function definition that occurs last in the stylesheet.

When an extension function defined with exsl:function is called, the content of the exsl:function is instantiated to give the result of the function.

Defining Function Arguments

Arguments for functions are defined with the xsl:param element, as specified in [11. Variables and Parameters] of [XSLT].

When an extension function is called, the values passed as arguments are assigned to parameters according to the position of the xsl:param. The first argument is assigned to the first parameter, the second to the second and so on. The presence of an xsl:param indicates that an argument is expected for the function but does not imply that an argument has to be passed to the function.

An XSLT processor must not signal an error if an extension function is called with fewer arguments than there are parameters defined for the extension function. It is an error to call a function with more arguments than there are parameters defined for the extension function. An XSLT processor may signal the error; if it does not signal the error, then it must recover by ignoring the extra arguments.

As an example, take the following function definition:

<exsl:function name="my:func">
   <xsl:param name="foo" />
   <xsl:param name="bar" select="false()" />
   ...
</exsl:function>

All the following function calls are legal:

my:func()
my:func('Fred')
my:func('Fred', true())
my:func('Fred', 'Barney')

The following function call is illegal:

my:func('Fred', true(), 'Barney')

The value specified by an xsl:param indicates the default value for an argument if that argument is not given in a function call, but does not indicate the acceptable value types for the function. The type of the value passed into the function can be tested with the exsl:object-type function.

Function Results

The content of the exsl:function element is a template. When the function is called, the template is instantiated to give the result of the function. The template is instantiated with the context node from the expression in which the function was called as the current node, and with the context node list from the expression in which the function was called as the current node list.

If the instantiation of the template results in the generation of result nodes, then the result of the function is a result tree fragment consisting of those nodes. For example a call to my:func as below will generate a result tree fragment consisting of a root node with a single foo element child.

<exsl:function name="my:func">
   <foo />
</exsl:function>

It is an error if a member of the sequence of nodes created by instantiating the template is an attribute node or a namespace node, since a root node cannot have an attribute node or a namespace node as a child. An XSLT processor may signal the error; if it does not signal the error, it must recover by not adding the attribute node or namespace node.

The result tree fragment that is the result of the function may be converted to a node set using the exsl:node-set function, to a string using the string function, or to a number using the number function.

Note: Applying the boolean function to the result tree fragment will always evaluate to true.

As discussed earlier in this section, generating result tree fragments only is not sufficient for many functions that involve manipulation of node sets. To enable functions to return node sets (and booleans), the instantiation of the content of the exsl:function element may involve the instantiation of an exsl:result element.