<title>XML Path Language (XPath)</title>

<p><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. 

<p>Java applications can use the
<a href='../javadoc/com/caucho/xpath/package-frame.html'>xpath</a>
package to use XPath with an XML tree.

<p>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.

<p>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'.

<objsummary/>

<section name='Basic' title='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.

<defun name=node title='node'>
<sum>Selects all child elements with nodeName of <var/node/>.</sum>

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

top = xml.documentElement

for (var node in top.select('a'))
  writeln(node.nodeName, ': ', node.attribute.id);
</example>
<results>
a: 1
a: 3
</results>
</example>

</defun>

<defun name=star title='*'>
<sum>Selects all child elements.</sum>
</defun>

<defun name=attr title='@attr'>
<sum>Selects the attribute <var/attr/>.</sum>

<egtable>
<example>chapter/@title</example>
<results>All title attributes of chapters.</results>

<example>//var[@name='keywords']/@content</example>
<results>The contents of all var keywords.
A web spider might use this.
</results>
</egtable>
</defun>

<defun name=starattr title='@*'>
<sum>Selects all attributes.</sum>
</defun>

<defun name=starattr title='ns:*'>
<sum>Selects elements in the given namespace.</sum> Namespace patterns
only make sense in the context of XSL, where the namespace
declarations have been made.
</defun>

<defun name=node title='node()'>
<sum>Matches an <a href='../javadoc/org/w3c/dom/Element.html'>element</a>.</sum>
</defun>

<defun name=text title='text()'>
<sum>Matches a <a href='../javadoc/org/w3c/dom/Text.html'>text</a> node.</sum>
</defun>

<defun name=comment title='comment()'>
<sum>Matches a comment.</sum>
</defun>

<defun name=pi title='processing-instruction()'>
<sum>Matches a <a href='../javadoc/org/w3c/dom/ProcessingInstruction.html'>processing instruction</a> node.</sum>
</defun>
<!--
<defun name=er title='er()'>
<sum>Matches an <a href='../javadoc/org/w3c/dom/EntityReference.html'>entity reference</a> node.</sum>
</defun>
-->

<defun name=dot title='.'>
<sum>Selects the current node.</sum>

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

<egtable>
<example>.//image</example>
<results>Any image descendant.</results>

<example>.//image</example>
<results>Any image descendant.</results>
</egtable>

</defun>

<defun name=parent title='..'>
<sum>Selects the parent of current node.</sum>

<egtable>
<example>../brother</example>
<results>All brothers.</results>
<example>../../aunt</example>
<results>All aunts.</results>
<example>//*[../@color='blue']</example>
<results>All elements with blue parents.</results>
</egtable>
</defun>

<defun name=root title='/'>
<sum>Selects the document node.</sum>

<p>Useful for finding constants in a document.

<egtable>
<example>/html</example>
<results>The single root element.</results>
<example>/html/head</example>
<results>The HTML head section.</results>
<example>/html/head/var</example>
<results>All var tags.</results>
</egtable>
</defun>

<defun name=filter title='a[expr]'>
<sum>Select only those nodes matching <var/a/> which also satisfy the
expression <var/expr/>.</sum>

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

<egtable>
<example>chapter[verse]</example>
<results>Chapters with a verse.</results>

<example>chapter[not(verse)]</example>
<results>Chapters with no verses.</results>

<example>chapter[not(verse) and not(section)]</example>
<results>Chapters with neither verses 
nor sections.</results>

<example>*[@color='blue']</example>
<results>Blue children.</results>

<example>*[@color='blue'][position()=last() - 1]</example>
<results>second to last blue child</results>

</egtable>
</defun>

<defun name=nth-filter title='a[n]'>
<sum>Selects the <var/n/>th matching node matching <var/a/></sum>
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.

<p/>The position filter is equivalent to
<code><var/a/>[position()=<var/n/>]</code>

<egtable>
<example>child[3]</example>
<results>third child</results>

<example>child/grandchild[1]</example>
<results>first grandchild from every child (not only the first
grandchild).</results>

<example>child[last()]</example>
<results>last child</results>
</egtable>

</defun>

<defun name=compose title='a/b'>
<sum>For each node matching <var/a/>, add the nodes matching <var/b/>
to the result.</sum>

<p>The following is almost a definition of a/b. 
<example>
for (var a in node.select('a')) {
  for (var b in a.select('b')) {
    // possible duplicates if a or b
    // are weird patterns.
  }
}
</example>

Some example interpretations, 
<egtable>
<example>chapter/verse</example>
<results>grandchildren verse with 
parent chapter.</results>

<example>../span</example>
<results>sibling span elements.</results>

<example>./span</example>
<results>children span elements.</results>

<example>*/*</example>
<results>All grandchildren.</results>

<example>*[color='blue']/verse</example>
<results>All grandchildren verse elements
with blue colored parents.</results>

<example>a/b/c</example>
<results>Great grandchildren c, with
parent b and grandparent a.</results>
</egtable>
</defun>

<defun name=descendant title='a//b'>
<sum>For each node matching <var/a/>, add the descendant nodes
matching <var/b/> to the result.</sum>  The '//' operator selects all
descendants matching <var/b/>.  The '/' operator selects all children
matching <var/b/>.

<egtable>
<example>chapter//a</example>
<results>All links contained in a chapter.</results>

<example>.//image</example>
<results>Any image descendant.</results>
</egtable>
</defun>

<defun name=root-descendant title='//b'>
<sum>Returns elements in the entire document matching <var/b/>.</sum>

<p>This is equivalent to /.//<var/b/>, but less weird.

<egtable>
<example>//image</example>
<results>All images in the document</results>
<example>//a[@href='http://www.caucho.com']</example>
<results>All links to caucho</results>
</egtable>

</defun>

<defun name=union title='a|b'>
<sum>All nodes matching <var/a/> or <var/b/>.</sum>

Some example interpretations, 
<egtable>
<example>lion|tiger|bear</example>
<results>Lions and tigers and bears.
</results>
</egtable>
</defun>

<defun name=exprroot title='expr/path'>
<sum>Uses an expression as the start of a path.</sum>  Usually,
<var/expr/> will be a special function call, like the <code/id()/>
function.  <code/expr[expr]/> is also allowed.

<egtable>
<example>id('314')/@color</example>
<results>The color attribute of the element with id 314.</results>

<example>key('id', 'a')[@color='red']</example>
<results>Selects the node returned by key if they have a red color.
</results>
</egtable>
</defun>

</section>

<section name='Axis' title='Node Axes'>

<defun name=child title='child::a'>

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

<egtable>
<example>child::chapter</example>
<results>Select all chapter elements of the current node.</results>

<example>child::text()</example>
<results>All text children.</results>

<example>child::comment()</example>
<results>All comment children.</results>

<example>/child::h1</example>
<results>Select all top-level h1 elements.</results>
</egtable>
</defun>

<defun name=descendant title='descendant::a'>

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

<egtable>
<example>descendant::a</example>
<results>Select all hyperlinks below the current node.</results>

<example>/descendant::table</example>
<results>Select all tables in the document.</results>

<example>child::section/descendant::image</example>
<results>Select all images in a section.</results>

<example>.[descendant::image]</example>
<results>Selects the current node if it contains an image.</results>
</egtable>
</defun>

<defun name=descendant-or-self title='descendant-or-self::a'>

<sum>Selects descendants including the current node.</sum>
</defun>

<defun name=attribute title='attribute::a'>

<sum>Selects attributes of the current element.</sum>  It is 
equivalent to @<var/a/>.

<egtable>
<example>attribute::width</example>
<results>Selects the width of the current node.</results>

<example>image[attribute::width > 10]</example>
<results>Selects image children with a width attribute
greater than 10.</results>
</egtable>
</defun>

<defun name=following-sibling title='following-sibling::a'>

<sum>Selects nodes after the current node.</sum>

<egtable>
<example>following-sibling::chapter</example>
<results>Selects following chapters.</results>

<example>h3/following-sibling::text()</example>
<results>Following text nodes after an h3.</results>
</egtable>
</defun>

<defun name=preceding-sibling title='preceding-sibling::a'>

<sum>Selects nodes before the current node.</sum>

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

<egtable>
<example>preceding-sibling::chapter</example>
<results>Selects chapters before chapter 3.</results>

<example>fun/preceding-sibling::comment()</example>
<results>Selects the comments before a function.</results>
</egtable>
</defun>

<defun name=following title='following::a'>

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

<p>following, preceding, ancestor and self partition the document.
</defun>

<defun name=preceding title='preceding::a'>

<sum>Selects the first matching node preceding in document order, excluding
ancestors.</sum>  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.

<p>following, preceding, ancestor and self partition the document.
</defun>

<defun name=parent title='parent::a'>

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

<egtable>
<example>parent::chapter</example>
<results>Selects the parent if it's a chapter.</results>

<example>parent::*/@color</example>
<results>Selects the color of the parent.</results>
</egtable>
</defun>

<defun name=ancestor title='ancestor::a'>

<sum>Selects matching ancestors.</sum>

<p/>following, preceding, ancestor and self partition the document.
<egtable>
<example>ancestor::section</example>
<results>Selects ancestor sections.</results>

<example>ancestor::*/@color</example>
<results>Selects ancestor color attributes.</results>
</egtable>
</defun>

<defun name=ancestor-or-self title='ancestor-or-self::a'>
Selects ancestors including the current node.
</defun>

<defun name=self title='self::a'>

<sum>Selects the current node.</sum> '.' is equivalent to 'self::node()'.

<p/>following, preceding, ancestor and self partition the document.

<egtable>
<example>self::chapter</example>
<results>Selects the current node if it's a chapter.</results>
</egtable>
</defun>

</section>

<section name='expr' title='Expressions'>

<defun name='expr-path' title='path'>
<sum>Selects nodes based on the <var/path/>.</sum>

<p/>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.

<deftable>
<tr><td>boolean<td>True if <var/path/> matches any nodes.
<tr><td>string<td>The text value of the first matching node.
<tr><td>number<td>The string value converted to a number.
</deftable>
</defun>

<defun name='number' title='number'>
<sum>Numbers have the same syntax as Java doubles.</sum>
</defun>

<defun name='string' title='"string"'>
<sum>String literals can use single or double quotes.</sum>
</defun>

<defun name='equals' title='a = b'>
<sum>Standard comparisons.</sum>

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.
<ol>
<li>boolean
<li>number
<li>string
</ol>

<p/>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.

<deftable>
<tr><td>a = b<td>True if a equals b.
<tr><td>a != b<td>True if a is not equal to b.
<tr><td>a < b<td>True if a is less than b.
<tr><td>a <= b<td>True if a is less than or equal to b.
<tr><td>a > b<td>True if a is greater than b.
<tr><td>a >= b<td>True if a is greater than or equal to b.
</deftable>
</defun>

<defun name='equals' title='a + b'>
<sum>Arithmetic expressions.</sum>

<deftable>
<tr><td> - a<td>Unary minus
<tr><td>a + b<td>Add
<tr><td>a - b<td>Substract
<tr><td>a * b<td>Multiply
<tr><td>a div b<td>Divide
<tr><td>a mod b<td>Floating point mod, like Java.
</deftable>
</defun>

<defun name='group' title='(expr)'>
<sum>Parenthesized expressions.</sum>
</defun>

<defun name='fun' title='fun(arg1, ..., argn)'>
<sum>Function calls.</sum>

The function library is in the <a href='xpath-fun.xtp'>XPath function</a> section.
</defun>

<defun name='not' title='not(expr)'>
<sum>Boolean not.</sum>
</defun>

<defun name='or' title='a or b'>
<sum>Boolean or.</sum>
</defun>

<defun name='and' title='a and b'>
<sum>Boolean and.</sum>
</defun>

<defun name='var' title='$var'>
<sum>The value of a variable.</sum>  Variables, in general, only make
sense in a context like XSL.  Normal use of XPath outside of XSL will
not use variables.
</defun>

</section>
