EXSLT - func:function

Implementer Page: func.function.html
Element Package: func.function.zip

Element Syntax

<func:function
   name = QName>
   <-- Content: (xsl:param* | template) -->
</func:function>

The func:function element can only occur at the top level of the stylesheet. The func: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.

The EXSLT - Functions namespace (http://exslt.org/functions) is designated as an extension namespace within the subtree rooted at a func:function element. The effect of this is as if the func:function element had a xsl:extension-element-prefixes attribute defined on it, with one of the values within it being the prefix used for the EXSLT - Functions namespace (see [14.1 Extension Elements] in [XSLT]).

An func: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 [2.4 Qualified Names] in [XSLT]. 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.

If a stylesheet contains more than one func:function element with the same name, then the XSLT processor must use the function definition with the highest import precedence. It is an error if a stylesheet contains more than one func: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 func:function is called, the content of the func:function is instantiated to give the result of the function (see [func:result]).

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:

<func:function name="my:func">
   <xsl:param name="foo" />
   <xsl:param name="bar" select="false()" />
   ...
</func: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 may be tested with the exsl:object-type function if it is supported.

Function Results

The content of the func: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.

It is an error if the instantiation of the template results in the generation of result nodes. For example a call to my:func as below is an error.

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

The instantiation of the content of the func:function element may involve the instantiation of an func:result element to enable functions to return node sets (and booleans).

If no func:result element is instantiated, then the result of the function is an empty string.

Implementations

The following XSLT processors support func:function:

4XSLT, from 4Suite. (version 0.12.0a3)
SAXON 6.3 from Michael Kay (version 6.3)
libxslt from Daniel Veillard; implementation by Thomas Broyer (version 1.0.19)
Xalan-J from Apache (version 2.4.D1)

There are currently no third-party implementations of func:function.

Examples

Function

This use case tests the result of a function that involves a func:result element within a xsl:for-each element.

Source

<doc>
   <section index="section1"
            index2="atr2val">
      <section index="subSection1.1">
         <p>Hello</p>
         <p>Hello again.</p>
      </section>
   </section>
   <section index="section2">
      <p>Hello2</p>
      <section index="subSection2.1">
         <p>Hello</p>
         <p>Hello again.</p>
      </section>
      <section index="subSection2.2">
         <p>Hello</p>
         <p>Hello again.</p>
      </section>
      <p>Hello2 again.</p>
      <section index="subSection2.3">
         <p>Hello</p>
         <p>Hello again.</p>
      </section>
   </section>
</doc>

Stylesheet

<func:function name="my:count-elements">
   <xsl:for-each select="(//*)[1]">
      <func:result select="count(//*)" />
   </xsl:for-each>
</func:function>
<xsl:template match="/">
   <out>
      <xsl:value-of select="my:count-elements()" />
   </out>
</xsl:template>

Result

<out xmlns:my="my://own.uri">17</out>