Javascript XPath

Revision as of 13:53, 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)

• String literal (used with operators). Delimiter characters MUST be repeated: 'some''_''''string'
• 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.
Predicates:

• 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

VARIABLEs. A VARIABLE defines the contents to be compared with VALUE

* @attr_name. Use an attribute named attr_name of the current node. Fails if there is no attribute with this name

* text(). Use current node XML text. Fails if there is not text

* Else. VARIABLE is handled as XML tag. Check for an XML child element with given tag. Use its XML text. Fails if there is no child or there is no text in in it

• Variable presence

* @attr_name. Matches if current node has an attribute named attr_name

* text(). Matches if current node has a non empty xml text

* Else. Value is handled as as XML tag. Match if current node has a child name with given tag

• Functions (match if true is returned)

* matches(VARIABLE,regexp[,flags]), notMatches(VARIABLE,regexp[,flags]). Regular expression (NOT) match

Matches if current node has requested VARIABLE function returns true

Parameters:

VARIABLE: See VARIABLEs in comparison description

regexp: String constant describing the regular expression. Delimiter MUST be XML escaped

flags: String constant with regular expression flags: i(case insensitive) b(Basic POSIX regular expression). Delimiter MUST be XML escaped

Examples

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