Javascript XPath

Revision as of 09:43, 11 September 2024

General

An XPath describes a path in an XML element.
XPath items are nodes in XML tree.
Each item selects one or more XML node(s) (element, attribute, text) starting from previous item result.
An absolute path starts with slash (/). First item selector applies to root element.
A relative path (not starting with slash) behaves like XML root element was already selected. First item selector applies to it.

String constants (used with operators or in function parameters) MUST be enclosed using ' or " character. E.g. 'some_string' or "some_string".
Delimiters MUST be escaped when present inside string value (e.g. some'_''string)

• Used with operators. Delimiter characters MUST be repeated: 'some''_''''string'
• Used in function parameters. Delimiter MUST be XML escaped:

  'some'_''string'

Node selector:

• Tag. E.g. book. Reserved char * matches any element tag name
• Attribute (starting with '@'. E.g. @type
• Text: text()
• Child text: child::text()

Node selector can be followed by one or more predicates enclosed in square brackets: [].
Predicates add more filtering criteria.
supported maximum number of predicates is 10. Parse will fail if the number of predicates exceeds this number.
Predicate types:

• Index. Numeric, decimal digits.

1 based index of node in parent. Allowed interval: [1..0xffffffff] (4 bytes unsigned integer excluding 0)

Index is handled by selector type, attributes indexes and child indexes are not overlapping

• Keyword last() - Identifies the last node (by type: element, attribute, text) in parent
• Comparison: VARIABLE<OPERATOR>VALUE

Operators:

* = Equality operator. VARIABLE is the same as VALUE

* != Inequality operator. VARIABLE is not the same as VALUE

VALUE: string literal. E.g. 'some_string' or "some_string". Enclosing characters MUST be escaped

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)

The following will fail if this flag is set:

book/author[1][1]

book/author [1]

• 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)

The following will fail if this flag is not set:

book/text()/author - An xml text can't have a child

book/author[1][2] - An xml child can't be in first and second position

• 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

The following will fail if this flag is not set: book/&author

• 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