Evaluating XPath expressions

The functions presented here evaluate an XPath 1.0 expression in the context of the node being queried.

Namespaces

Namespace prefixes in the query expression are resolved into namespace URIs using the prefix map provided to the query functions as a second argument. If the map argument is omitted or null, the default prefix map is used for resolving prefixes.

Result data types

The value of an XPath 1.0 expression can have several data types (a node set with several elements, the text value of an attribute, a number returned by the count() function, the Boolean result of a comparison). The value is converted to the function's result data type using XPath 1.0 semantics – which may very well differ from the conversion semantics in the scripting language. For example the XPath 1.0 conversion from string to Boolean returns true for all non-empty strings (including the string "false").

Functions

evalToNodes( xpath : String, prefix-map : Map ) : NodeList: Evaluates an XPath 1.0 expression in the node's context. If the result is a non-empty node-set, returns a list of the nodes in the set. Otherwise returns an empty list.
evalToNode( xpath : String, prefix-map : Map ) : Node: Evaluates an XPath 1.0 expression in the node's context. If the result is a non-empty node-set, returns the first node in the set. Otherwise returns null.
evalToString( xpath : String, prefix-map : Map ) : String: Evaluates an XPath 1.0 expression in the node's context and converts the result to a string value with the XPath 1.0 string() function.
evalToNumber( xpath : String, prefix-map : Map ) : Number: Evaluates an XPath 1.0 expression in the node's context and converts the result to a numeric value with the XPath 1.0 number() function.
evalToBoolean( xpath : String, prefix-map : Map ) : Boolean: Evaluates an XPath 1.0 expression in the node's context and converts the result to a Boolean value with the XPath 1.0 boolean() function.

Note: The methods to evaluate XPath expressions will throw the exception in case the node object does not represent a valid XML node. This will happen, for example, in case the Document node was created by opening a not well-formed XML file. It is recommended to use try-catch blocks when using these methods.

For the given document (fragment of books.xml)

<?xml version="1.0"?>
<catalog>
   <book id="bk101">
      <author>Gambardella, Matthew</author>
      <title>XML Developer's Guide</title>
      <genre>Computer</genre>
      <price>44.95</price>
      <publish_date>2000-10-01</publish_date>
      <description>An in-depth look at creating applications 
      with XML.</description>
   </book>
   <book id="bk102">
      <author>Ralls, Kim</author>
      <title>Midnight Rain</title>
      <genre>Fantasy</genre>
      <price>5.95</price>
      <publish_date>2000-12-16</publish_date>
      <description>A former architect battles corporate zombies, 
      an evil sorceress, and her own childhood to become queen 
      of the world.</description>
   </book>
   <book id="bk103">
      <author>Corets, Eva</author>
      <title>Maeve Ascendant</title>
      <genre>Fantasy</genre>
      <price>5.95</price>
      <publish_date>2000-11-17</publish_date>
      <description>After the collapse of a nanotechnology 
      society in England, the young survivors lay the 
      foundation for a new society.</description>
   </book>
   <book id="bk104">
      <author>Corets, Eva</author>
      <title>Oberon's Legacy</title>
      <genre>Fantasy</genre>
      <price>5.95</price>
      <publish_date>2001-03-10</publish_date>
      <description>In post-apocalypse England, the mysterious 
      agent known only as Oberon helps to create a new life 
      for the inhabitants of London. Sequel to Maeve 
      Ascendant.</description>
   </book>
</catalog>

we get the following results:

var doc = new Document(job.getPath()); //job = sample document
var root = doc.getDocumentElement();
var list = root.evalToNodes("book",null);

var node = root.evalToNode("book");
var exists = Boolean(root.evalToBoolean("book[@id=\"bk1090\"]"));
var price = root.evalToNumber("book[@id=\"bk104\"]/price");
var fbgenre = root.evalToString("book/genre");
var genre = root.evalToString("book[@id=\"bk103\"]/genre");

//number of 'book' tags = 4
job.log(1,"number of 'book' tags = " + list.length);
//basename: book
job.log(1,"basename: " + node.getBaseName());
//id: bk101
job.log(1,"id: " + node.getAttributeValue("id"));
//parent basename: catalog
job.log(1,"parent basename: " + node.getParentNode().getBaseName());
//bk103 genre: Fantasy
job.log(1,"bk103 genre: " + genre);
//first book genre: Computer
job.log(1,"first book genre: " + fbgenre);
//bk104 price: 5.95
job.log(1,"bk104 price: " + price);
//exists bk1090: false
job.log(1,"exists bk1090: " + exists);