XML Path Language (XPath)
Resin 3.0

Features
Installation
Configuration
Web Applications
IOC/AOP
Resources
JSP
Quercus
Servlets and Filters
Databases
Admin (JMX)
CMP
EJB
Amber
EJB 3.0
Security
XML and XSLT
XTP
JMS
Performance
Protocols
Third-party
Troubleshooting/FAQ

Introduction
JAXP
User's Guide
Reference
FAQ
Scrapbook

XML Path Language (XPath)
XSLT-lite examples
XSLT Filter
User's Guide
User's Guide
XSLT-lite examples

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

  1. Index
  2. Basic Patterns
    1. Node Axes
      1. Expressions

        Index
        "string"String literals can use single or double quotes
        $varThe value of a variable
        exprParenthesized expressions
        *Selects all child elements
        .Selects the current node
        ..Selects the parent of current node
        /Selects the document node
        //bReturns elements in the entire document matching b
        @*Selects all attributes
        @attrSelects the attribute attr
        a + bArithmetic expressions
        a = bStandard comparisons
        a and bBoolean and
        a or bBoolean or
        a//bFor each node matching a, add the descendant nodes matching b to the result
        a/bFor each node matching a, add the nodes matching b to the result
        a[expr]Select only those nodes matching a which also satisfy the expression expr
        a[n]Selects the nth matching node matching a When a filter's expression is a number, XPath selects based on position
        ancestor-or-self::aSelects ancestors including the current node
        ancestor::aSelects matching ancestors
        attribute::aSelects attributes of the current element
        a|bAll nodes matching a or b
        child::aThe child axis selects children of the current node
        comment()Matches a comment
        descendant-or-self::aSelects descendants including the current node
        descendant::aThe descendant axis selects descendants of the current node
        expr/pathUses an expression as the start of a path
        following-sibling::aSelects nodes after the current node
        following::aSelects the first matching node following in document order, excluding descendants
        fun(arg1, ..., argn)Function calls
        nodeSelects all child elements with nodeName of node
        node()Matches an org
        not(expr)Boolean not
        ns:*Selects elements in the given namespace
        numberNumbers have the same syntax as Java doubles
        parent::aSelects the parent if it matches
        pathSelects nodes based on the path
        preceding-sibling::aSelects nodes before the current node
        preceding::aSelects the first matching node preceding in document order, excluding ancestors
        processing-instruction()Matches a org
        self::aSelects the current node
        text()Matches a org

        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.

        chapter/@title All title attributes of chapters.
        //var[@name='keywords']/@content The contents of all var keywords. A web spider might use this.

        @*

        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.

        .//image Any image descendant.
        .//image Any image descendant.

        ..

        Selects the parent of current node.

        ../brother All brothers.
        ../../aunt All aunts.
        //*[../@color='blue'] All elements with blue parents.

        /

        Selects the document node.

        Useful for finding constants in a document.

        /html The single root element.
        /html/head The HTML head section.
        /html/head/var All var tags.

        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.

        chapter[verse] Chapters with a verse.
        chapter[not(verse)] Chapters with no verses.
        chapter[not(verse) and not(section)] Chapters with neither verses nor sections.
        *[@color='blue'] Blue children.
        *[@color='blue'][position()=last() - 1] second to last blue child

        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]

        child[3] third child
        child/grandchild[1] first grandchild from every child (not only the first grandchild).
        child[last()] last child

        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,

        chapter/verse grandchildren verse with parent chapter.
        ../span sibling span elements.
        ./span children span elements.
        */* All grandchildren.
        *[color='blue']/verse All grandchildren verse elements with blue colored parents.
        a/b/c Great grandchildren c, with parent b and grandparent a.

        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.

        chapter//a All links contained in a chapter.
        .//image Any image descendant.

        //b

        Returns elements in the entire document matching b.

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

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

        a|b

        All nodes matching a or b.

        Some example interpretations,

        lion|tiger|bear Lions and tigers and bears.

        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.

        id('314')/@color The color attribute of the element with id 314.
        key('id', 'a')[@color='red'] Selects the node returned by key if they have a red color.

        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.

        child::chapter Select all chapter elements of the current node.
        child::text() All text children.
        child::comment() All comment children.
        /child::h1 Select all top-level h1 elements.

        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::a Select all hyperlinks below the current node.
        /descendant::table Select all tables in the document.
        child::section/descendant::image Select all images in a section.
        .[descendant::image] Selects the current node if it contains an image.

        descendant-or-self::a

        Selects descendants including the current node.

        attribute::a

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

        attribute::width Selects the width of the current node.
        image[attribute::width > 10] Selects image children with a width attribute greater than 10.

        following-sibling::a

        Selects nodes after the current node.

        following-sibling::chapter Selects following chapters.
        h3/following-sibling::text() Following text nodes after an h3.

        preceding-sibling::a

        Selects nodes before the current node.

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

        preceding-sibling::chapter Selects chapters before chapter 3.
        fun/preceding-sibling::comment() Selects the comments before a function.

        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()'.

        parent::chapter Selects the parent if it's a chapter.
        parent::*/@color Selects the color of the parent.

        ancestor::a

        Selects matching ancestors.

        following, preceding, ancestor and self partition the document.

        ancestor::section Selects ancestor sections.
        ancestor::*/@color Selects ancestor color attributes.

        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.

        self::chapter Selects the current node if it's a chapter.

        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.

        booleanTrue if path matches any nodes.
        stringThe text value of the first matching node.
        numberThe string value converted to a number.

        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 = bTrue if a equals b.
        a != bTrue if a is not equal to b.
        a < bTrue if a is less than b.
        a <= bTrue if a is less than or equal to b.
        a > bTrue if a is greater than b.
        a >= bTrue if a is greater than or equal to b.

        a + b

        Arithmetic expressions.

        - aUnary minus
        a + bAdd
        a - bSubstract
        a * bMultiply
        a div bDivide
        a mod bFloating point mod, like Java.

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


        User's Guide
        User's Guide
        XSLT-lite examples
        Copyright © 1998-2006 Caucho Technology, Inc. All rights reserved.
        Resin® is a registered trademark, and HardCoretm and Quercustm are trademarks of Caucho Technology, Inc.