Resin can use XPath, the XML Path Language, to select nodes from an XML tree. Scripts can select all 'table' children, or even all 'table' elements in an entire HTML file. The XPath language is exceptionally rich. It can describe an incredible number of node selections.

Java applications can use the com.caucho.xpath package to use XPath with an XML tree.

The XML Path Language describes nodes in an XML tree. It's a mini-language for specifying nodes patterns, like regular expressions are a mini-language for specifying text patterns.

The language selects sets of nodes. Each operator in XPath selects a new set based on the old set of nodes. For example, given a set of chapters, XPath can select all sections in those chapters, chapters with 'advanced' attributes, or grandchildren with 'color' attributes of 'blue'.

Basic Patterns

The basic XPath patterns cover 90% of the cases that most stylesheets will need. Because the pattern language is based on familiar filesystem paths, the most useful patterns should be easy.

node

Selects all child elements with nodeName of node.

xml = caucho.xml.Xml.parseString(@<<END);
<top>
  <a id='1'/>
  <b>
    <a id='2'/>
  </b>
  <a id='3'/>
</top>
END

top = xml.documentElement

for (var node in top.select('a'))
  writeln(node.nodeName, ': ', node.attribute.id);

a: 1
a: 3

*

Selects all child elements.

@attr

Selects the attribute attr.

@*

Selects all attributes.

ns:*

Selects elements in the given namespace. Namespace patterns only make sense in the context of XSL, where the namespace declarations have been made.

node()

Matches an org.w3c.dom.Node.

text()

Matches a org.w3c.dom.Text node.

comment()

Matches a comment.

processing-instruction()

Matches a org.w3c.dom.ProcessingInstruction node.

.

Selects the current node.

The current node is primarily useful for descendant patterns. for some filter patterns.

..

Selects the parent of current node.

/

Selects the document node.

Useful for finding constants in a document.

a[expr]

Select only those nodes matching a which also satisfy the expression expr.

The expression b is a combination of and, or, not, comparisons and XPath patterns. An XPath expression, e.g. chapter/verse, is true if at least one node matches the pattern.

a[n]

Selects the nth matching node matching a When a filter's expression is a number, XPath selects based on position. This special case of the filter pattern treats selections as ordered lists.

The position filter is equivalent to a[position()=n]

a/b

For each node matching a, add the nodes matching b to the result.

The following is almost a definition of a/b.

for (var a in node.select('a')) {
  for (var b in a.select('b')) {
    // possible duplicates if a or b
    // are weird patterns.
  }
}

Some example interpretations,

a//b

For each node matching a, add the descendant nodes matching b to the result. The '//' operator selects all descendants matching b. The '/' operator selects all children matching b.

//b

Returns elements in the entire document matching b.

This is equivalent to /.//b, but less weird.

a|b

All nodes matching a or b.

Some example interpretations,

expr/path

Uses an expression as the start of a path. Usually, expr will be a special function call, like the id() function. expr[expr] is also allowed.

Node Axes

child::a

The child axis selects children of the current node. It is entirely equivalent to the usual slash notation. So child::a/child::b is the same as a/b.

descendant::a

The descendant axis selects descendants of the current node. It is equivalent to '//'. So child::a//child::b is the same as a//b.

descendant-or-self::a

Selects descendants including the current node.

attribute::a

Selects attributes of the current element. It is equivalent to @a.

following-sibling::a

Selects nodes after the current node.

preceding-sibling::a

Selects nodes before the current node.

preceding-siblings:: counts positions backwards. So preceding-sibling::a[1] selects the closest preceding sibling.

following::a

Selects the first matching node following in document order, excluding descendants. In other words, the following axis will scan through every node in document order, starting with getNextSibling().

following, preceding, ancestor and self partition the document.

preceding::a

Selects the first matching node preceding in document order, excluding ancestors. In other words, the preceding axis will scan through every node in document order, starting with the root and ending in the current node, but it will skip ancestors.

following, preceding, ancestor and self partition the document.

parent::a

Selects the parent if it matches. The '..' pattern from the core is equivalent to 'parent::node()'.

ancestor::a

Selects matching ancestors.

following, preceding, ancestor and self partition the document.

ancestor-or-self::a

Selects ancestors including the current node.

self::a

Selects the current node. '.' is equivalent to 'self::node()'.

following, preceding, ancestor and self partition the document.

Expressions

path

Selects nodes based on the path.

The path interpretation depends on the context. When filtering nodes, the path expression is a boolean. Any matching node will return true. When the value is a string, as in the xsl:value-of, then the textValue is used.

number

Numbers have the same syntax as Java doubles.

"string"

String literals can use single or double quotes.

a = b

Standard comparisons.

XPath converts the arguments to a common type before comparison. The conversion priority is boolean, number, string. In other words, if either arg is a boolean, a boolean comparison is used.

1. boolean
2. number
3. string

Node-sets, e.g. chapter/@color, are compared differently. Each node in the node set is compared. If any matches, then the comparison is true.

a + b

Arithmetic expressions.

(expr)

Parenthesized expressions.

fun(arg1, ..., argn)

Function calls.

The function library is in the XPath function section.

not(expr)

Boolean not.

a or b

Boolean or.

a and b

Boolean and.

$var

The value of a variable. Variables, in general, only make sense in a context like XSL. Normal use of XPath outside of XSL will not use variables.