Javascript XPath

Revision as of 16:52, 10 September 2024

General

An XPath describes a path in an XML element.
XPath items are nodes in XML tree.
Example:

/bookstore/book[1]/text()

Items:

1. Root element whose tag MUST be bookstore
2. First root child with tag book
3. Text of the first root child with tag book

Constructor

• new XPath(str,flags])

Build an XPath from string description and parse flags.
Parameters:
str String description
flags Flags used by parser

Flags:

• XPath.StrictParse Enable strict path parse.

Path parse will fail in some conditions (e.g. found spaces where not expected or duplicate index in predicate)

• XPath.IgnoreEmptyResult Ignore (do not check) empty result when parsing steps.

Path parse will fail if a step would not select anything (e.g. previous step select an XML text: there is nothing after it)

• XPath.NoXmlNameCheck Do not check XML element tag or attribute name for valid XML charcaters.

Path parse will fail if this flag is not set and an invalid character is found in string

• new XPath(strOrXPath)

Build an XPath from string description or XPath object.
Parameters:
strOrXPath String description or XPath object (copy held XPath description only)

Static Methods

• escapeString(str[quot[,literal=true]])

Escape a string to be used in an XPath expression.
This function should be used when building an XPath from pieces.
Parameters:
str String to escape quot Optional string quoting (enclose) character. Allowed: ' or ". Default: "
literal True if string is going to be used as literal (e.g. in comparison), false XML string match (will be XML escaped)
Return: Escaped string

var str = "\"Literal\"<XML>";
var literal = XPath.escapeString(str);
var xml = XPath.escapeString(str,undefined,false);
// literal: """Literal""<XML>"
// xml: ""Literal"<XML>"

Methods

• valid()

Check if path is valid.
Return true if path is valid, false if not (parse failed).

• absolute()

Check if path is absolute.
Return true if path is an absolute one, false if not.

• getPath()

Retrieve the path string description.
Return string if path is valid, null if not.

• getItems([escape])

Retrieve the path items (steps).
Parameters:
escape Boolean. True to escape strings, false to return unescaped strings. Default: true
Return array of strings if path is valid, null if path is not valid.

 var x = new XPath("book[@attr='''Literal']/author[matches(text(),'<XML>')]");
 var escaped = x.getItems(); // ["book[@attr='''Literal']","author[matches(text(),'<XML>')]"]
 var unescaped = x.getItems(false); // ["book[@attr=''Literal']","author[matches(text(),'<XML>')]"]

• getError()

Retrieve an object describing the path parse error.
Return object if path is not valid, undefined if path is valid.

Properties:
status Integer. Internal failure code errorItem Integer. Index of failed path item error String. Error description. May not be present

• describeError()

Retrieve a string describing the path parse error.
Return string if path is not valid, undefined if path is valid.

Static Properties

• FindXml, FindText, FindAttr, FindAny

Flags to be used in * XML.getAnyByPath() function.

• StrictParse, IgnoreEmptyResult, NoXmlNameCheck

Parser flags to be used when building an XPath from string

References

• https://www.w3.org/TR/xpath-30/
• https://www.w3schools.com/xml/xpath_intro.asp
• https://en.wikipedia.org/wiki/XPath