XSLT and XPath function reference in alphabetical order

(Excerpt from “XSLT 2.0 & XPath 2.0” by Frank Bongers, chapter 5, translated from German)

A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z

function-available

Category:

Information on the runtime environment

Origin:

XSLT 1.0

Return value:

A Boolean value true or false, depending on whether the requested function is available in the runtime environment or not.

Call/Arguments:

function-available($functionName, $arity?)

$functionName:

Obligatory. A xs:string string which is interpreted as name of the function. The string is understood as QName whose expanded form has to correspond to the expanded QName of the (extension) function. The argument must be enclosed in string delimiters if it is passed on as literal. (In this case, it is always possible but seldom useful to pass on a XPath expression which generates the string. However, if this does not result in a lexical QName, the function returns false.)

$arity:

(new in XSLT 2.0)

Optional. A xs:integer integer which has to correspond to the arity, which means the number of the arguments to be expected of the tested function. This argument is not available in XSLT 1.0.

Purpose of use:

The function-available() function tests whether a function is available in the current runtime environment of the stylesheet. The string passed on during the call is interpreted as QName of the function. As long as no second argument is passed on, the test is successful if a function of this name is in the scope, irrespective of the number of the arguments expected by the function.

If the name string of the function designated in this way has no prefix portion, it is regarded as located in the XSLT namespace. In this case it must be a valid XSLT function or XPath Core Function.

In contrast, an extension function defined by the processor manufacturer or a stylesheet function declared by the user with xsl:function must always have a prefix whose namespace is not null and unequal to the default namespace.

By means of the optional second argument, the number of arguments (arity) of the tested function can be adjusted. The test is only successful if the function exists and accepts the required number of arguments. (Please note: This argument is only available in XSLT 2.0.)

This test function is important in connection with the downward compatible stylesheet processing in order to ensure a fallback behaviour in the case of non-availability of a function (see example 4).

The existence of the call of an available function within a XPath expression is a priori no error – as long as this expression is not processed (in this case indeed, a runtime error would occur). In order to intercept this, function-available() is used.

Static errors which are reported when reading in the stylesheet for a context evaluated by the processor (see example 6) can be prevented by function-available() in connection with the use-when attribute by already stopping the reading in of the block.

Attention – Only the existence and the arity of the function are tested!
The test only ensures that a function with the requested identifier exists and provided that the arity is tested, it can work with the required number of arguments. However, there is no warranty that this function then is successfully called up: There is no way to find out in advance the data types required by the function for its arguments.

In addition, when declaring stylesheet functions by the override attribute, it is possible to give priority to a (same-named!) developer-defined extension function. This function may behave completely different as the actually desired function, but with the help of function-available() it cannot be distinguished from it.

Example 1 – testing an existing XSLT function:

function-available('format-number')

The format-number() function is a function available in XSLT, therefore in this case the value true is returned.

Example 2 – testing a non-existing XSLT function:

function-available('new-function')

Since no prefix was used during the query, a XSLT function is assumed! However, the new-function() function is (at least for the current status of XPath) not available, so the test returns false.

Example 3 – testing an extension function:

function-available('super:new-function')

If a namespace is defined for the super: prefix which is in the scope during the call, the requested super:new-function() function is regarded as extension function. If this function is known to the system, the value true is returned, otherwise false.

Example 4 – testing an extension function and its arity:

function-available('super:new-function',3)

Returns true if the function with the required name and the required number of input arguments is available, otherwise false.

In principle, XSLT allows a concurrent existence of two or more same-named functions which differ by the number of their arguments. However, with the test of example 3 one cannot differentiate between such name duplicates, so that such a test is not suitable to stop a subsequent function call with the wrong number of arguments.

Attention – Testing the expected data type is not possible!
A test of each data type of an input argument expected by the function is not possible. A runtime error can still occur, even if the function name and the number of arguments are correct, but not the data types expected for the arguments.

Example 5 – testing a stylesheet function (XSLT 2.0):

<!-- declaration: -->
<xsl:function name="my:function">
   <!-- instruction block of the function -->
   ...
</xsl:function>
...
<xsl:if test="function-available('my:function')">
   <!-- instructions using the function -->
   ...
</xsl:if>
...

A stylesheet function declared with xsl:function can also be tested with function-available(). This can be useful when processing with a XSLT 1.0 processor which ignores the function declaration and to whom the function is not available. (The passing on of an arity argument is counterproductive because error-prone for XSLT 1.0 processors!)

Example 6 – XPath 2.0 function vs. extension function:

If an extension function in a forward compatible mode working XSLT 1.0 processor shall be available as an alternative to a native XPath 2.0 function, where appropriate, it is necessary to prevent that a XSLT 2.0 processor which does not know this extension function reports a static error when reading in the stylesheet:

<xsl:stylesheet version="2.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:set="http://exslt.org/sets" extension-element-prefixes="set">
<xsl:template name="infoList">
  <xsl:param name="info" /> 
  <xsl:variable name="info_without_duplicates">
    <xsl:choose>
    <!-- a XSLT 1.0 processor skips this: -->
      <xsl:when test="number(system-property('xsl:version')) &gt; 2.0">
         <xsl:sequence select="distinct-values($info)"/>
      </xsl:when>
    <!-- calling extension function if available: -->
    <!-- otherwise XSLT 2.0 processor ignores block -->
      <xsl:when test="function-available('set:distinct')" use-when="function-available('set:distinct')">
          <xsl:value-of select="set:distinct($info)" />
      </xsl:when>
      <xsl:otherwise>
      <!-- alternative block -->
      ...
      </xsl:otherwise>
  </xsl:variable>
  <!-- further instructions -->
   ...
</xsl:template> 
</xsl:stylesheet>

In order to resolve the problem, the function-available() function is used in the second <xsl:when> element. A XSLT 1.0 processor ignores the use-when attribute (which it does not know) and only evaluates the test attribute. If the processor knows the extension function, it executes the function (in case this is not the case, a remedy can be produced in the <xsl:otherwise> block, for example in the form of the call of an EXSLT extension template).

During the processing, a XSLT 2.0 processor already executes the first <xsl:when> element. However, a problen occurs when reading in once the processor does not know the required extension function. At this point, a static error may be reported. With the help of the use-when attribute, in which the availability is also tested, the processor is induced to ignore the relevant <xsl:when> block.

Function definition:

XSLT 1.0:

function-available(string) => boolean

XSLT 2.0:

function-available($function-name as xs:string) as xs:boolean

function-available($function-name as xs:string,

$arity as xs:integer) as xs:boolean

   

<< back next >>

 

 

 


Copyright © Galileo Press, Bonn 2008
Printing of the online version is permitted exclusively for private use. Otherwise this chapter from the book "XSLT 2.0 & XPath 2.0" is subject to the same provisions as those applicable for the hardcover edition: The work including all its components is protected by copyright. All rights reserved, including reproduction, translation, microfilming as well as storage and processing in electronic systems.


Galileo Press, Rheinwerkallee 4, 53227 Bonn, Germany