XPath and XPointer/Extension Functions for XPath in XSLT

From WikiContent

< XPath and XPointer(Difference between revisions)
Jump to: navigation, search
(Initial conversion from Docbook)
Current revision (09:53, 7 March 2008) (edit) (undo)
(Initial conversion from Docbook)
 
(One intermediate revision not shown.)

Current revision

XPath and XPointer

While XPath includes a powerful set of basic functions, some applications of XPath need to support capabilities that go beyond that core. Currently, the most widely used XPath-based application is, of course, XSLT; aside from proprietary extensions offered through the various XSLT processors, it acquires these extra capabilities by way of two commonly used sets of extension functions. (Don't count on their availability in other XPath-based contexts, although because of their usefulness they may be adopted elsewhere as well.)

The first set of functions comes from XSLT itself, providing access to path, node, and string-value handling facilities necessary for XSLT processing. The second set of functions comes from the independent Extensions to XSLT (EXSLT) project, providing support for a variety of tasks that weren't addressed in either XPath 1.0 or XSLT 1.0.

Contents

Additional Functions in XSLT 1.0

When XPath and XSLT were separated into two specifications, it was clear that there were some functions that relied on information available only through an understanding of the current XSLT processing context. These functions were kept in XSLT rather than in XPath, and (to repeat) may or may not be available in XPath processing in other contexts. You will see these functions used frequently in XSLT processing. Table A-1 lists the additional functions provided by XSLT 1.0.

Table A-1. Additional functions provided by XSLT 1.0

Function prototype Description
current( )
Returns a node-set containing only the current node of the document being processed.
document(object, node-set?)
Returns a node-set containing either a document representing the union of the arguments (if the node-set argument is present) or, more typically, the document identified by the URI in the argument (if the first and only argument is a string containing a URI pointing to XML content.)
format-number(number, string, string?)
Returns a string representing the number as formatted according to rules provided in the format pattern in the second argument, as well as the rules in an xsl:decimal-format element named by the optional third argument. Formatting patterns use the syntax of the Java JDK 1.1 DecimalFormat class.
function-available(string)
Returns a Boolean true or false, indicating whether the function named in the argument is available for use in the current XSLT processing environment. This is especially important in testing for the availability of EXSLT functions,, as well as extension functions that may be provided only by a given XSLT processor.
generate-id(node-set?)
Returns a string that can be used as a unique identifier for the first node in the node-set. Returns the empty string if the node-set is empty.
key(string, object)
Returns a node-set representing the content of a key created in the stylesheet using the xsl:key element.
system-property(string)
The string argument for this function must be a QName. Returns an object that represents the value of the system property identified by that name. All XSLT implementations must support xsl:version, xsl:vendor, and xsl:vendor-url.
unparsed-entity-uri (string)
Returns a string containing the URI of an unparsed entity declared using the string provided as the argument. If there is no entity declared using that name, it returns the empty string.


Again, these functions should be used only in the context of XSLT stylesheets. While some non-XSLT implementations of XPath may provide more general support for them, the functions' behavior in those other contexts might only more or less correspond to their behavior according to the XSLT specification.

Tip

The XSLT additional functions (and the XSLT features that provide the extra support they need) are all documented in the XSLT specification at http://www.w3.org/TR/xslt#add-func.

EXSLT Extensions

EXSLT is a community project that provides extra functionality for XSLT and XPath. While not a product of the W3C, the EXSLT foundation is implemented across a variety of XSLT and XPath processors. Some EXSLT extensions require support for elements in XSLT stylesheets and are thus tightly bound to XSLT; others are relatively free standing and may be usable in other XPath contexts. The EXSLT extensions can be supported either through direct implementation in XSLT processors or through the use of XSLT modules, which themselves provide support for EXSLT functions using scripting or XSLT. EXSLT extensions may be implemented either as XSLT templates or as functions. In XPath terms, only the functions approach is easily available.

EXSLT is divided into eight modules, each containing its own group of functions (and possibly elements) and using its own namespace to identify the module. Within those modules reside "Core" functionality, which all EXSLT implementations must support, as well as "Other" functionality, which EXSLT implementations may support. The following sections explain each module and its contents.

Tip

For additional information on EXSLT, including pointers to implementations and information on how to participate in creating or implementing EXSLT, see http://www.exslt.org.

EXSLT Functions Module

Despite its name, the EXSLT Functions module doesn't contain any functions. Instead, it contains three elements that may be used to define extension functions. All these elements are in the http://exslt.org/functions namespace, typically mapped to the func prefix. Table A-2 lists these elements and their uses.

Table A-2. EXSLT Functions module elements

Element name Description Status
func:function
Defines a named function visible throughout the XSLT stylesheet. Must appear in the top level of the XSLT stylesheet (that is, as a child of the root xsl:stylesheet element). Arguments are specified using xsl:param, while the return value is specified using func:result. Core
func:result
Used inside of func:function to specify the value returned by the function. Its select attribute identifies the value to return. Core
func:script
Used to define functions with scripting languages (such as ECMAScript). Not all processors support all scripting languages, so this is useful primarily when the particular implementation that will be used for processing is known in advance. Other


Using these elements, you can create new functions for a wide variety of processing tasks, if the rest of the EXSLT library proves insufficient.

EXSLT Dates-and-Times Module

The EXSLT Dates-and-times module provides a wide variety of tools for processing dates and times. All these elements and functions are in the http://exslt.org/dates-and-times namespace, typically mapped to the date prefix. Most of the module is simply functions, but there is also a date:date-format element for defining alternative formats to the ISO 8601 dates used by W3C XML Schema. Table A-3 lists this element and its use.

Table A-3. Table A-3: EXSLT Dates-and-times module element

Element name Description Status
date:date-format
Permits the use of date formats other than ISO 8601's Gregorian format. The name attribute identifies a QName for the format, the calendar attribute identifies the calendar type (gregorian is the default), lang identifies the language used, and first-day-of-week provides a named value (i.e., sunday) to be used for the first day of the week. Other


The date:date-format element hasn't yet been implemented as of June 2002. Most of the rest of the Dates-and-times module is widely implemented, so working with ISO 8601 dates using EXSLT is not very difficult. ISO 8601 dates use the general format:

CCYY-MM-DDThh:mm:ss(Z|((+|-)hh:mm))

XML Schema Part 2: Datatypes provides more information on date and time formats at http://www.w3.org/TR/xmlschema-2/.

The EXSLT Dates-and-times module offers the wide variety of functions listed in Table A-4.

Table A-4. EXSLT Dates-and-times module functions

Function prototype Description Status
date:date-time( )
Returns a string containing the current date and time in ISO 8601 format. Core
date:date(string?)
If the string argument is present, it returns a string containing the date portion of that ISO 8601 string. If the argument is not present, it returns the current date. Core
date:time(string?)
If the string argument is present, it returns a string containing the time portion of that ISO 8601 string. If the argument is not present, it returns the current time. Core
date:year(string?)
If the string argument is present, it returns a number containing the year portion of that ISO 8601 string. If the argument is not present, it returns the current year. Core
date:leap-year(string?)
If the string argument is present, it returns a Boolean identifying whether the date in that ISO 8601 string occurs in a leap year. If the argument is not present, it returns whether the current year is a leap year. Core
date:month-in-year(string?)
If the string argument is present, it returns a number containing the month portion of that ISO 8601 string. If the argument is not present, it returns the current month. Core
date:month-name(string?)
If the string argument is present, it returns a string containing the name of the month identified by that ISO 8601 string. If the argument is not present, it returns the current month name. Core
date:month-abbreviation(string?)
If the string argument is present, it returns a string containing an abbreviation for the name of the month identified by that ISO 8601 string. If the argument is not present, it returns the current month abbreviation. Core
date:week-in-year(string?)
If the string argument is present, it returns a number identifying the week of the year of the date in that ISO 8601 string. If the argument is not present, it returns the current week of the year. Core
date:day-in-year(string?)
If the string argument is present, it returns a number identifying the day of the year of the date in that ISO 8601 string. If the argument is not present, it returns the current day of the year. Core
date:day-in-month(string?)
If the string argument is present, it returns a number containing the day portion of that ISO 8601 string. If the argument is not present, it returns the current day. Core
date:day-of-week-in-month(string?)
If the string argument is present, it returns a number identifying which iteration of the current day of the week within the month for the date in that ISO 8601 string. If a date represents the second Friday in a month, the value is 2. If the argument is not present, it returns the value for the current date. Core
date:day-in-week(string?)
If the string argument is present, it returns a number identifying which iteration of the current day of the week within the month for the date in that ISO 8601 string. If a date represents the second Friday in a month, the value is 2. If the argument is not present, it returns the value for the current date. Core
date:day-name(string?)
If the string argument is present, it returns a string containing the name of the weekday identified by that ISO 8601 string. If the argument is not present, it returns the current weekday name. Core
date:day-abbreviation(string?)
If the string argument is present, it returns a string containing an abbreviation for the name of the weekday identified by that ISO 8601 string. If the argument is not present, it returns the current weekday abbreviation. Core
date:hour-in-day(string?)
If the string argument is present, it returns a number containing the hour portion of that ISO 8601 string. If the argument is not present, it returns the current hour. Core
date:minute-in-hour(string?)
If the string argument is present, it returns a number containing the minute portion of that ISO 8601 string. If the argument is not present, it returns the current minute. Core
date:second-in-minute(string?)
If the string argument is present, it returns a number containing the second portion of that ISO 8601 string. If the argument is not present, it returns the current second. Core
date:format-date(string, string)
Formats a date (given as the first string argument) according to the pattern identified by the second string argument and returns it as a string. Permitted patterns are xs:dateTime, xs:date, xs:time, xs:gYearMonth, xs:gYear, xs:gMonthDay, xs:gMonth, and xs:gDay. Other
date:parse-date(string, string)
The inverse of date:format-date, this function takes a string containing the date information and a pattern from the list above and returns a date in ISO 8601 format. Other
date:week-in-month(string?)
If the string argument is present, it returns a number identifying the week of the month into which the date specified by the ISO 8601 string falls. If the argument is not present, it returns the week for the current date. Other
date:difference(string, string)
Returns a string representation of the duration between the two dates passed as string arguments. Other
date:add(string, string)
Returns a string representation of the date produced by adding the date in the first string argument to the duration in the second string argument. Other
date:add-duration(string, string)
Returns a string representation of the duration produced by adding the duration in the first string argument to the duration in the second string argument. Other
date:sum(node-set)
Returns a string representation of the duration produced by adding the durations stored in the node-set argument. Other
date:seconds(string?)
Returns the number of seconds specified by the duration passed as a string. Other
date:duration(number?)
Returns a duration string corresponding to the number of seconds passed as an argument. Other


The Dates-and-times module largely provides functionality that may eventually be provided by XPath 2.0.

(Note that day and month names returned by various of the functions listed in Table A-4, such as date:day-name( ) and date:month-abbreviation( ), are the English-language forms, such as "Sunday" and "Jan." Also note that the abbreviation functions return the three-letter abbreviations for day and month names, e.g., "Thu" and "Sep" for Thursday and September, respectively.)

EXSLT Dynamic Module

The EXSLT Dynamic module provides support for the dynamic evalution of XPath expressions created during XSLT or other processing. All these functions are in the http://exslt.org/dynamic namespace, typically mapped to the dyn prefix. This module contains only functions.

None of the Dynamic module has been implemented as of June 2002. The functions it provides are listed in Table A-5, and you should check the documentation of your implementation to find out if any of this is supported.

Table A-5. EXSLT Dynamic module functions

Function prototype Description Status
dyn:evaluate(string)
Evaluates the string argument as an XPath expression and returns the result as an object. Other
dyn:min(node-set, string)
Returns a number representing the minimum value produced by applying the XPath expression passed as the second argument to the node-set passed as the first argument. Other
dyn:max(node-set, string)
Returns a number representing the maximum value produced by applying the XPath expression passed as the second argument to the node-set passed as the first argument. Other
dyn:sum(node-set, string)
Returns a number representing the sum of the values produced by applying the XPath expression passed as the second argument to the node-set passed as the first argument. Other
dyn:map(node-set, string)
Returns a node-set containing all the results produced by applying the XPath expression passed as the second argument to the node-set passed as the first argument. Other
dyn:closure(node-set, string)
Returns a node-set containing all the results produced by applying the XPath expression passed as the second argument to the node-set passed as the first argument, after those results are processed using the XPath expression repetitively until no results are left. Other

EXSLT Common Module

The EXSLT Common module provides one element for creating multiple output documents from a given transformation and two functions that address minor structural limitations of XSLT. The element and functions are in the http://exslt.org/common namespace, typically mapped to the exsl prefix. Table A-6 lists the one element and its use.

Table A-6. EXSLT Common module element

Element name Description Status
exsl:document
Provides support for the creation of multiple output documents in XSLT processing. Other


The exsl:document element is widely implemented in EXSLT-compliant processors. It has no effect on XPath processing.

The EXSLT Common module offers the functions listed in Table A-7.

Table A-7. EXSLT Common module functions

Function prototype Description Status
exsl:node-set(object)
Creates an XSLT node-set from an XSLT result tree fragment, permitting further processing of that information. Also converts strings into text nodes. Core
exsl:object-type(object)
Returns the type of the object as string, number, boolean, node-set, RTF, or external. Core


Some of this functionality will be provided in XSLT 2.0 or XPath 2.0.

EXSLT Math Module

The EXSLT Math module provides a variety of common mathematical functions and is easily used with XPath. All these functions are in the http://exslt.org/math namespace, typically mapped to the math prefix. With this module, you can use XPath to perform mathematical calculations on the contents of your documents, in ways far beyond the reach of XPath's own numeric functions and operators.

The EXSLT Math module offers the functions listed in Table A-8.

Table A-8. EXSLT Math module functions

Function prototype Description Status
math:min(node-set)
Returns a number representing the minimum numeric value contained in the node-set. Core
math:max(node-set)
Returns a number representing the maximum numeric value contained in the node-set. Core
math:highest(node-set)
Returns a node-set containing the nodes whose value is the maximum numeric value contained in the node-set. Core
math:lowest(node-set)
Returns a node-set containing the nodes whose value is the minimum numeric value contained in the node-set. Core
math:abs(number)
Returns a number containing the absolute value of the number passed as an argument. Other
math:sqrt(number)
Returns a number containing the square root of the number passed as an argument. Other
math:power(number, number)
Returns a number representing the value of the first number argument raised to the power of the second number argument. Other
math:constant(string, number)
Returns a constant specified by the string argument (PI, E, SQRRT2, LN2, LN10, LOG2E, SQRT1_2) to the precision specified by the number. Other
math:log(number)
Returns a number containing the natural logarithm (base e) of the number passed as an argument. Other
math:random( )
Returns a random value between 0 and 1. Other
math:sin(number)
Returns a number containing the sine of the number (in radians) passed as an argument. Other
math:cos(number)
Returns a number containing the cosine of the number (in radians) passed as an argument. Other
math:tan(number)
Returns a number containing the tangent of the number (in radians) passed as an argument. Other
math:asin(number)
Returns a number containing the arcsine of the number passed as an argument. Other
math:acos(number)
Returns a number containing the arccosine of the number passed as an argument. Other
math:atan(number)
Returns a number containing the arctangent of the number passed as an argument. Other
math:atan2(number, number)
Returns the angle (in radians) from the X axis to the point where X is the first number and Y is the second. Other
math:exp(number)
Returns a number containing the exponential of the number passed as an argument. Other


Various implementations provide different levels of support for the Math module.

EXSLT Regular Expressions Module

The EXSLT Regular Expressions module provides regular expression functionality through three functions. All these functions are in the http://exslt.org/regular-expressions namespace, typically mapped to the regexp prefix. With this module, you can use XPath to break down or lexically analyze the contents of your documents. The EXSLT Regular Expressions module offers the functions listed in Table A-9.

Table A-9. EXSLT Regular Expressions module functions

Function prototype Description Status
regexp:test(string, string, string?)
Returns a Boolean indicating whether the first string matches the regular expression identified by the second string. The third argument may contain flags for case sensitivity. Other
regexp:match(string, string, string?)
Returns a node-set containing the pieces from the first string as returned from the match against the second string. The third argument may contain flags for case sensitivity or requirements for a global match. Other
regexp:replace(string, string, string, string)
Returns a string containing a value produced by matching pieces of the first string against the regular expression in the second string and replacing those pieces with the string in the fourth argument. The third argument may contain flags for case sensitivity or requirements for a global match. Other


A variety of implementations for the Regular Expression module is available, though no processors support it natively.

EXSLT Sets Module

The EXSLT Sets module provides six functions for working with node-sets. All these functions are in the http://exslt.org/sets namespace, typically mapped to the set prefix. With this module, you can use XPath to compare node-sets. The EXSLT Sets module offers the functions listed in Table A-10.

Table A-10. EXSLT Sets module functions

Function prototype Description Status
set:difference(node-set, node-set)
Returns a node-set containing nodes that are in the first node-set argument but not in the second. Core
set:intersection(node-set, node-set)
Returns a node-set containing nodes that are in both the first node-set argument and the second. Core
set:distinct(node-set)
Returns a node-set containing a subset of nodes whose string values are unique within the node-set passed as an argument. Core
set:has-same-node(node-set, node-set)
Returns a Boolean value indicating whether the two node-sets have any nodes in common. Core
set:leading(node-set, 
node-set)
Returns a node-set containing the nodes in the first node-set that precede (in document order) those in the second node-set. Core
set:trailing(node-set, node-set)
Returns a node-set containing the nodes in the first node-set that follow (in document order) those in the second node-set. Core


The Sets module is built into every processor that supports EXSLT, and implementations are available for other processors as well.

EXSLT Strings Module

The EXSLT Strings module provides string-processing functionality through three functions. All these functions are in the http://exslt.org/strings namespace, typically mapped to the str prefix. With this module, you can use XPath to process the text contents of your documents using common string tools not otherwise provided by the XPath string functions. The EXSLT Strings module offers the functions listed in Table A-11.

Table A-11. EXSLT Strings module functions

Function prototype Description Status
str:tokenize(string, string?)
Returns a node-set of token elements, containing fragments from the first string argument as broken down at boundaries established by the second. If the second argument is empty, the first argument is tokenized into individual characters. Other
str:replace(string, object, object)
Returns a node-set. The first string argument is matched against the contents of the second argument, and those matches are replaced with the content of the third. Other
str:padding(number, string)
Returns a string containing characters of the string argument repeated to create the length the number argument specifies. Other
str:align(string, string, string?)
Returns the first string aligned to match the second string. The third argument specifies left, right, or center alignment. Other
str:encode-uri(string)
Returns a string that reflects the value of the string argument URI-encoded for use in web documents. Other
str:decode-uri(string)
Returns a string that reflects the value of the string argument URI-deoded for conversion from web documents. Other
str:concat(node-set)
Returns a string containing the values of all the nodes in the node-set argument concatentated as a single string. Other
str:split(string, string?)
Returns a node-set of token elements, containing fragments from the first string argument as broken down at boundaries established by the second. If the second argument is empty, the first argument is tokenized into individual characters. Other


A variety of implementations for the Strings module is available, though no processors support it natively.

Personal tools