Chapter 22. XPath Reference | XML in a Nutshell, 2nd Edition

CONTENTS

22.1 The XPath Data Model
22.2 Data Types
22.3 Location Paths
22.4 Predicates
22.5 XPath Functions

XPath is a non-XML syntax for expressions that identify particular nodes and groups of nodes in an XML document. It is used by both XPointer and XSLT, as well as by some native XML databases and query languages.

22.1 The XPath Data Model

XPath views each XML document as a tree of nodes. Each node has one of seven types:

Root: Each document has exactly one root node, which is the root of the tree. This node contains one comment node child for each comment outside the document element, one processing-instruction node child for each processing instruction outside the document element, and exactly one element node child for the document element. It does not contain any representation of the XML declaration, the document type declaration, or any whitespace that occurs before or after the root element. The root node has no parent node. The root node's value is the value of the document element.
Element: An element node represents an element. It has a name, a namespace URI, a parent node, and a list of child nodes, which may include other element nodes, comment nodes, processing-instruction nodes, and text nodes. An element node also has a list of attributes and a list of in-scope namespaces, none of which are considered to be children of the element. The value of an element node is the complete, parsed text between the element's start- and end-tags that remains after all tags, comments, and processing instructions are removed and all entity and character references are resolved.
Attribute: An attribute node represents an attribute. It has a name, a namespace URI, a value, and a parent element. However, although elements are parents of attributes, attributes are not children of their parent elements. The biological metaphor breaks down here. xmlns and xmlns:prefix attributes are not represented as attribute nodes. An attribute node's value is the normalized attribute value.
Text: Each text node represents the maximum possible contiguous run of text between tags, processing instructions, and comments. A text node has a parent node but does not have children. A text node's value is the text of the node.
Namespace: A namespace node represents a namespace in scope on an element. In general, each namespace declaration by an xmlns or xmlns:prefix attribute produces multiple namespace nodes in the document tree. Like attribute nodes, each namespace node has a parent element but is not the child of that parent. The name of a namespace node is the prefix. The value of a namespace node is the namespace URI.
Processing instruction: A processing-instruction node represents a processing instruction. It has a target, data, a parent node, and no children. The name of a processing-instruction node is its target. The value of a processing-instruction node is the data of the processing instruction, not including any initial whitespace.
Comment: A comment node represents a comment. It has a parent node and no children. The value of a comment is the string content of the comment, not including the .

The XML declaration and the document type declaration are not included in XPath's view of an XML document. All entity references, character references, and CDATA sections are resolved before the XPath tree is built. The references themselves are not included as a separate part of the tree.

22.2 Data Types

Each XPath expression evaluates to one of four types:

Boolean

A binary value that is either true or false. In XPath, Booleans are most commonly produced by using the comparison operators =, !=, <, >, <=, and >=. Multiple conditions can be combined using the and and or operators, which have their usual meaning in logic (e.g., 3>2 or 2>1 is true.) XPath does not offer Boolean literals. However, the true( ) and false( ) functions fill that need.

Number

All numbers in XPath, which are IEEE 754-compliant, 64-bit floating point numbers. This is the same as the double type in Java. Numbers range from 4.94065645841246544e-324d to 1.79769313486231570e+308d, and are either positive or negative. Numbers also include the special values Inf (positive infinity), -Inf (negative infinity), and NaN (not a number), which is used for the results of illegal operations, such as dividing by zero. XPath provides all the customary operators for working with numbers, including:

+: Addition
-: Subtraction; however, this operator should always be surrounded by whitespace to avoid accidental misinterpretation as part of an XML name
*: Multiplication
div: Division
mod: Taking the remainder

String

Sequence of zero or more Unicode characters. String literals are enclosed in either single or double quotes, as convenient. Unlike Java, XPath does not allow strings to be concatenated with the plus sign. However, the concat( ) function serves this purpose.

Node-set

Collection of zero or more nodes from an XML document. Location paths produce most node-sets. Generally, a single node-set can contain every kind of node: root, element, attribute, namespace, comment, processing instruction, and text. However, most node-sets contain a single type of node.

Some standards that use XPath also define additional data types. For instance, XSLT defines a result tree fragment type that represents the result of processing an XSLT instruction or instantiating a template. XPointer defines a location set type that extends node-sets to include points and ranges.

22.3 Location Paths

Node-sets are returned by location-path expressions. Location paths consist of location steps. Each location step contains an axis and a node test separated by a double colon. That is, a location step looks like this:

axis::node test

The axis specifies in which direction from the context node the processor searches for nodes. The node test specifies which nodes along that axis are selected. These are some location steps with different axes and node tests:

child::set descendant-or-self::node( ) ancestor-or-self::* attribute::xlink:href

Each location step may be suffixed with one or more predicates enclosed in square brackets that further winnow the node-set. For example:

child::set[position( )=2] descendant-or-self::node( )[.='Eunice'] ancestor-or-self::*[position( )=2][.="Celeste"] attribute::xlink:href[starts-with('http')]

Each individual location step is itself a relative location path. The context node against which the relative location path is evaluated is established by some means external to XPath for example, by the current matched node in an XSLT template.

Location steps can be combined by separating them with forward slashes. Each step in the resulting location path sets the context node (or nodes) for the next path in the step. For example:

ancestor-or-self::*/child::*[position( )=1] child::document/child::set[position( )=2]/following-sibling::* descendant::node( )[.='Eunice']/attribute::ID

An absolute location path is formed by prefixing a forward slash to a relative location path. This sets the context node for the first step in the location path to the root of the document. For example, these are all absolute location paths:

/descendant::ship/ancestor-or-self::*/child::*[position( )=1] /child::document/child::set[position( )=2]/following-sibling::* /descendant::node( )[.='Eunice']/attribute::ID

Multiple location paths can be combined with the union operator (|) to form an expression that selects a node-set containing all the nodes identified by any of the location paths. For example, this expression selects a node-set containing all the set children of the context node, all the vector descendants of the context node, all ancestor elements of the context node and the root node, and all attributes of the context node named href:

child::set | descendant::vector | ancestor::* | attribute::href

22.3.1 Abbreviated Syntax

An abbreviated syntax is available for particularly common location steps. This is the syntax allowed in XSLT match patterns. In this syntax, five axes may use this shorthand:

.: The context node
..: The parent node
name: The child element or elements with the specified name
//: All descendants of the context node, and the context node itself
@ name: The attribute of the context node with the specified name

Using the abbreviated syntax, the previous examples can be rewritten in the following manner:

set descendant-or-self::node( ) ancestor-or-self::* @xlink:href set[position( )=2] descendant-or-self::node( )[.='Eunice'] ancestor-or-self::*[position( )=2][.="Celeste"] @xlink:href[starts-with('http')] ancestor-or-self::*/*[position( )=1] document/set[position( )=2]/following-sibling::* descendant::node( )[.='Eunice']/@ID //ship/ancestor-or-self::*/*[position( )=1] /document/set[position( )=2]/following-sibling::* /descendant::node( )[.='Eunice']/@ID set | .//vector | ancestor::* | @href

Not all location steps can be rewritten using the abbreviated syntax. In particular, only the child, self, attribute, descendant-or-self, and parent axes can be abbreviated. The remaining axes must be spelled out in full.

22.3.2 Axes

Each XPath location step moves along an axis from a context node. The context node is a particular root, element, attribute, comment, processing-instruction, namespace, or text node in the XML document. (In practice, it's almost always an element node or the root node.) The context node may be a node selected by the previous location step in the location path, or it may be determined by extra-XPath rules, such as which node is matched by an xsl:template element.

However the context node is determined, it has some relationship to every other node in the document. The various axes divide the document into different, overlapping sets, depending on their relationship to the context node. There are exactly 13 axes you can use in an XPath location step:

child: All children of the context node. Only root and element nodes have children. Attribute and namespace nodes are not children of any node, though they do have parent nodes.
descendant: All nodes contained inside the context node, that is, a child node, a child of a child node, a child of a child of a child node, and so on. Only root and element nodes have descendants. Like the child axis, the descendant axis never contains attribute or namespace nodes.
descendant-or-self: Any descendant of the context node or the context node itself. // is an abbreviation for /descendant-or-self::node( )/.
parent: The element or root node that immediately contains the context node. Only the root node does not have a parent node. .. is an abbreviation for parent::node( ).
ancestor: The root node and all element nodes that contain the context node. The root node itself has no ancestors.
ancestor-or-self: All ancestors of the context node, as well as the node itself.
following-sibling: All nodes that follow the end of the context node and have the same parent node. Attribute and namespace nodes do not have siblings.
preceding-sibling: All nodes that precede the start of the context node and have the same parent node. Attribute and namespace nodes do not have siblings.
following: All nodes that begin after the context node ends, except for attribute nodes and namespace nodes; that is, all nodes after the context node except descendants.
preceding: All nodes that end before the context node begins, except for attribute nodes and namespace nodes; that is, all nodes before the context node except ancestors.
attribute: All attributes of the context node; the axis is empty if the context node is not an element node. This axis does not contain xmlns and xmlns:prefix attributes. @name is an abbreviation for attribute::name.
namespace: All namespaces in scope (not merely declared) on the context node; this axis is empty if the context node is not an element node.
self: The context node itself. A single period (.) is an abbreviation for self::node.

22.3.3 Node Tests

Each location step has at least an axis and a node test. The node test further refines the nodes selected by the location step. In an unabbreviated location step, a double colon (::) separates the axis from the node test. There are seven kinds of node tests:

name: An XML name matches all elements with the same name. However, along the attribute axis it matches all attributes with the same name instead; along the namespace axis it matches all namespaces with that prefix. As usual, if the element or attribute name is prefixed, only the URI to which the prefix is mapped matters, not the prefix itself.
prefix: *: Along most axes, this node test matches all element nodes whose namespace URIs are the same as the namespace URI to which this prefix is mapped, regardless of name. However, along the attribute axis, this node test matches all attribute nodes whose namespace URIs are the same as the namespace URI to which this prefix is mapped.
comment( ): This includes all comment nodes.
text( ): This includes all text nodes. Each text node is a maximum contiguous run of text between other types of nodes.
processing-instruction( )
processing-instruction(' target'): With no arguments, this node test selects all processing instructions. With a single string argument, it selects all processing instructions that have the specified target.
node( ): This node test selects all nodes, regardless of type: attribute, namespace, element, text, comment, processing instruction, and root.
*: This test normally selects all element nodes, regardless of name. However, if the axis is the attribute axis, then it selects all attribute nodes. If the axis is the namespace axis, then it selects all namespace nodes.

22.4 Predicates

Each location step may have zero or more predicates. A predicate is an XPath expression enclosed in square brackets that follows the node test in the location step. This expression most commonly, but not necessarily, returns a Boolean value. In the following location path:

/person[position()=1]/profession[.="physicist"][position( )<3]

[position( )=1], [.="physicist"], and [position( )<3] are predicates. An XPath processor works from left to right in an expression. After it has evaluated everything that precedes the predicate, it's left with a context node list that may contain no nodes, one node, or more than one node. For most axes, including child, following-sibling, following, and descendant, this list is in document order. For the ancestor, preceding, and preceding-sibling axes, this list is in reverse document order.

The predicate is evaluated against each node in the context node list. If the expression returns true, then that node is retained in the list. If the expression returns false, then the node is removed from the list. If the expression returns a number, then the node being evaluated is left in the list if and only if the number is the same as the position of that node in the context node list. If the expression returns a non-Boolean, non-number type, then that return value is converted to a Boolean using the boolean( ) function, described later, to determine whether it retains the node in the set.

22.5 XPath Functions

XPath 1.0 defines 27 built-in functions for use in XPath expressions. Various technologies that use XPath, such as XSLT and XPointer, also extend this list with functions they need. XSLT even allows user-defined extension functions.

Every function is evaluated in the context of a particular node, called the context node. The higher-level specification in which XPath is used, such as XSLT or XPointer, decides exactly how this context node is determined. In some cases the function operates on the context node. In other cases it operates on the argument, if present, and the context node, if no argument exists. The context node is ignored in other cases.

In the following sections, each function is described with at least one signature in this form:

return-type function-name(type argument, type argument, ...)

Compared to languages like Java, XPath argument lists are quite loose. Some XPath functions take a variable number of arguments and fill in the arguments that are omitted with default values or the context node.

Furthermore, XPath is weakly typed. If you pass an argument of the wrong type to an XPath function, it generally converts that argument to the appropriate type using the boolean( ), string( ), or number( ) functions, described later. The exceptions to the weak-typing rule are the functions that take a node-set as an argument. Standard XPath 1.0 provides no means of converting anything that isn't a node-set into a node-set. In some cases a function can operate equally well on multiple argument types. In this case, its type is given simply as object.

boolean( )

boolean boolean(object o)

The boolean( ) function converts its argument to a Boolean according to these rules:

Zero and NaN are false. All other numbers are true.
Empty node-sets are false. Nonempty node-sets are true.
Empty strings are false. Nonempty strings are true.

ceiling( )

number ceiling(number x)

The ceiling( ) function returns the smallest integer greater than or equal to x. For example, ceiling(3.141592) is 4. ceiling(-3.141592)is -3. Before the ceiling is calculated, non-number types are converted to numbers as if by the number( ) function.

concat( )

string concat(string s1, string s2) string concat(string s1, string s2, string s3) string concat(string s1, string s2, string s3, string s4) ...

This function concatenates its arguments in order from left to right and returns the combined string. It may take two or more arguments. Nonstrings may be passed to this function as well, in which case they're converted to strings automatically as if by the string( ) function.

contains( )

boolean contains(string s1, string s2)

This function returns true if s2 is a substring of s1 that is, if s1 contains s2 false otherwise. For example, contains("A very Charming cat", "Charm") is true, but contains("A very Charming cat", "Marjorie") is false. The test is case-sensitive. For example, contains("A very charming cat", "Charm") is false. Nonstrings may also be passed to this function, in which case they're automatically converted to strings as if by the string( ) function.

count( )

number count(node-set set)

The count( ) function returns the number of nodes in the argument node-set, that is, the length of the set.

false( )

boolean false( )

The false( ) function always returns false. It makes up for the lack of Boolean literals in XPath.

floor(3e )

number floor(number x)

The floor( ) function returns the greatest integer less than or equal to x. For example, floor(3.141592) is 3. floor(-3.141592)is -4. Before their floor is calculated, non-number types are converted to numbers as if by the number( ) function.

id( )

node-set id(string IDs) node-set id(node-set IDs)

The id( ) function returns a node-set containing all elements in the document with any of the specified IDs. If the argument is a string, then this string is interpreted as a whitespace-separated list of IDs, and the function returns a node-set containing any elements that have an ID matching one of these IDs. If the argument is a node-set, then each node in the set is converted to a string, which is in turn treated as a white-space-separated list of IDs. The returned node-set contains all the elements whose ID matches any ID in the string value of any of these nodes. Finally, if the argument is any other type, then it's converted to a string, as by the string( ) function, and it returns the same result as passing that string value to id( ) directly.

lang( )

boolean lang(string languageCode)

The lang( ) function returns true if the context node is written in the language specified by the languageCode argument; false otherwise. The nearest xml:lang attribute on the context node or one of its ancestors determines the language of any given node. If no such xml:lang attribute exists, then lang( ) returns false.

The lang( ) function takes into account country and other subcodes before making its determination. For example, lang('fr') returns true for elements whose language code is fr-FR, fr-CA, or fr. However, lang('fr-FR') is not true for elements whose language code is fr-CA or fr.

last( )

number last( )

The last( ) function returns the size of (i.e., the number of nodes in) the context node-set.

local-name( )

string local-name( ) string local-name(node-set nodes)

With no arguments, this function returns the context node's local name, that is, the part of the name after the colon, or the entire name if it isn't prefixed. For a node-set argument, it returns the local name of the first node in the node-set. If the node-set is empty or the first node in the set does not have a name (e.g., it's a comment or root node), then it returns the empty string.

name( )

string name( ) string name(node-set nodes)

With no arguments, this function returns the qualified (prefixed) name of the context node or the empty string if the context node does not have a name (e.g., it's a comment or root node). With a node-set as an argument, it returns the qualified name of the first node in the node-set. If the node-set is empty or if the set's first node does not have a name, then it returns the empty string.

namespace-uri( )

string namespace-uri( ) string namespace-uri(node-set nodes)

With no arguments, this function returns the namespace URI of the context node. With a node-set as an argument, it returns the namespace URI of the first node in the node-set. If this node does not have a namespace URI (i.e., it's not an element or an attribute node; it is an element or attribute node, but is not in any namespace; or the node-set is empty), then it returns the empty string.

normalize-space( )

string normalize-space( ) string normalize-space(string s)

The normalize-space( ) function strips all leading and trailing whitespace from its argument and replaces each run of whitespace with a single space character. Among other effects, this removes all line breaks. If the argument is omitted, it normalizes the string value of the context node. A nonstring may be passed to this function, in which case it's automatically converted to a string, as if by the string( ) function, and that string is normalized and returned.

not( )

boolean not(boolean b)

The not( ) function inverts its argument; that is, false becomes true and true becomes false. For example, not(3 > 2) is false, and not(2+2=5) is true. Non-Booleans are converted as by the boolean( ) function before being processed.

number( )

number number( ) number number(object o)

The number( ) function converts its argument to a number according to these rules:

A string is converted by first stripping leading and trailing whitespace and then picking the IEEE 754 value that is closest (according to the IEEE 754 round-to-nearest rule) to the mathematical value represented by the string. If the string does not seem to represent a number, it is converted to NaN. Exponential notation (e.g., 75.2E-12) is not recognized.
True Booleans are converted to 1; false Booleans are converted to 0.
Node-sets are first converted to a string as if by the string( ) function. The resulting string is then converted to a number.

If the argument is omitted, then it converts the context node.

position( )

number position( )

The position( ) function returns a number equal to the position of the current node in the context node-set. For most axes it counts forward from the context node. However, if the axis in use is ancestor, ancestor-or-self, preceding, or preceding-sibling, then it counts backward from the context node instead.

round( )

number round(number x)

The round( ) function returns the integer closest to x. For example, round(3.141592) returns 3. round(-3.141592) returns -3. If two integers are equally close to x, then the one that is closer to positive infinity is returned. For example, round(3.5) returns 4, and round(-3.5) returns -3. Non-number types are converted to numbers as if by the number( ) function, before rounding.

starts-with( )

boolean starts-with(string s1, string s2)

The starts-with( ) function returns true if s1 starts with s2; false otherwise. For example, starts-with("Charming cat", "Charm") is true, but starts-with ("Charming cat", "Marjorie") is false. The test is case-sensitive. For example, starts-with("Charming cat", "charm") is false. Nonstrings may be passed to this function as well, in which case they're automatically converted to strings as if by the string( ) function, before the test is made.

string( )

string string( ) string string(object o)

The string( ) function converts an object to a string according to these rules:

A node-set is converted to the string value of the first node in the node-set. If the node-set is empty, it's converted to the empty string.
A number is converted to a string as follows:
- NaN is converted to the string NaN.
- Positive Inf is converted to the string Infinity.
- Negative Inf is converted to the string -Infinity.
- Integers are converted to their customary English form with no decimal point and no leading zeros. A minus sign is used if the number is negative, but no plus sign is used for positive numbers.
- Nonintegers (numbers with nonzero fractional parts) are converted to their customary English form with a decimal point, with at least one digit before the decimal point and at least one digit after the decimal point. A minus sign is used if the number is negative, but no plus sign is used for positive numbers.
A Boolean with the value true is converted to the English word "true." A Boolean with the value false is converted to the English word "false." Lowercase is always used.

The object to be converted is normally passed as an argument, but if omitted, the context node is converted instead.

The XPath specification specifically notes that the "string function is not intended for converting numbers into strings for presentation to users." The primary problem is that it's not localizable and not attractive for large numbers. If you intend to show a string to an end user, use the format-number( ) function and/or xsl:number element in XSLT instead.

string-length( )

number string-length(string s) number string-length( )

The string-length( ) function returns the number of characters in its argument. For example, string-length("Charm") returns 5. If the argument is omitted, it returns the number of characters in the string value of the context node. A nonstring may be passed to this function, in which case it's automatically converted to a string, as if by the string( ) function, and that string's length is returned.

substring( )

string substring(string s, number index, number length) string substring(string s, number index)

The substring( ) function returns the substring of s starting at index and continuing for length characters. The first character in the string is at position 1 (not 0, as in Java and JavaScript). For example, substring('Charming cat', 1, 5) returns "Charm". If length is omitted, then the substring to the end of the string is returned. For example, substring('Charming cat', 10) returns "cat". As usual, any type of object may be passed to this function in place of the normal argument, in which case it is automatically converted to the correct type.

substring-after( )

string substring-after(string s1, string s2)

The substring-after( ) function returns the substring of s1 that follows the first occurrence of s2 in s1, or it returns the empty string, if s1 does not contain s2. For example, substring-after('Charming cat', 'harm') returns "ing cat". The test is case-sensitive. As usual, nonstring objects may be passed to this function, in which case they're automatically converted to strings as if by the string( ) function.

substring-before( )

string substring-before(string s1, string s2)

The substring-before( ) function returns the substring of s1 that precedes the first occurrence of the s2 in s1, or it returns the empty string if s1 does not contain s2. For example, substring-before('Charming cat', 'ing') returns "Charm". The test is case-sensitive. Nonstring objects may be passed to this function, in which case they're automatically converted to strings as if by the string( ) function.

sum( )

number sum(node-set nodes)

The sum( ) function converts each node in the node-set to a number, as if by the number( ) function, then it adds up those numbers and returns the sum.

translate( )

string translate(string s1, string s2, string s3)

The translate( ) function looks in s1 for any characters found in s2. It replaces each character with the corresponding character from s3. For example, translate("XML in a Nutshell", " ", "_") replaces the spaces with underscores and returns "XML_in_a_Nutshell". translate("XML in a Nutshell", "XMLN", "xmln") replaces the uppercase letters with lowercase letters and returns "xml in a nutshell". If s3 is shorter than s2, then characters in s1 and s2 with no corresponding character in s3 are simply deleted. For example, translate("XML in a Nutshell", " ", "") deletes the spaces and returns "XMLinaNutshell". Once again, nonstring objects may be passed to this function, in which case they're automatically converted to strings, as if by the string( ) function.

true( )

boolean true( )

The true( ) function simply returns true. It makes up for the lack of Boolean literals in XPath.

CONTENTS