Provides XPath 2.0 and XQuery support for the XML module.

The XPath module provides comprehensive support for XPath 2.0 and XQuery languages, enabling powerful querying and navigation of XML documents. It operates in conjunction with the XML class to provide a standards-compliant query engine with extensive functionality.

XPath 2.0 Path Expressions

The module supports the full XPath 2.0 specification for navigating XML documents, including all 13 standard axes (child, descendant, descendant-or-self, following, following-sibling, parent, ancestor, ancestor-or-self, preceding, preceding-sibling, self, attribute, and namespace), node tests for element names, wildcards (*), and attribute selectors (@attr), numeric position filters ([1], [2]), comparison operators, and complex boolean expressions in predicates. Both absolute paths (/root/element), relative paths (element/subelement), and recursive descent (//element) are supported.

XQuery Language Support

The module implements core XQuery functionality including FLWOR expressions (for, let, where, order by, and return clauses) for advanced querying, sequence operations for constructing, filtering, and manipulating sequences of nodes and values, and a comprehensive type system supporting strings, numbers, booleans, node sets, dates, durations, and QNames.

Function Library

A rich set of standard functions is provided across multiple categories:

• Node Functions: position(), last(), count(), id(), name(), local-name(), namespace-uri(), root(), node-name(), base-uri()
• String Functions: concat(), substring(), contains(), starts-with(), ends-with(), string-length(), normalize-space(), upper-case(), lower-case(), translate(), string-join(), encode-for-uri(), escape-html-uri()
• Numeric Functions: number(), sum(), floor(), ceiling(), round(), round-half-to-even(), abs(), min(), max(), avg()
• Boolean Functions: boolean(), not(), true(), false(), exists(), empty(), lang()
• Sequence Functions: distinct-values(), index-of(), insert-before(), remove(), reverse(), subsequence(), unordered(), deep-equal(), zero-or-one(), one-or-more(), exactly-one()
• Regular Expressions: matches(), replace(), tokenize(), analyze-string()
• Date and Time Functions: current-date(), current-time(), current-dateTime(), date and time component extractors, timezone adjustments, duration calculations
• Document Functions: doc(), doc-available(), collection(), unparsed-text(), unparsed-text-lines(), document-uri()
• QName Functions: QName(), resolve-QName(), prefix-from-QName(), local-name-from-QName(), namespace-uri-from-QName(), namespace-uri-for-prefix(), in-scope-prefixes()
• URI Functions: resolve-uri(), iri-to-uri()
• Formatting Functions: format-date(), format-time(), format-dateTime(), format-integer()
• Utility Functions: error(), trace()

Expression Compilation

XPath and XQuery expressions are compiled into an optimised internal representation for efficient reuse. Compiled expressions are thread-safe and can be shared across multiple XML documents. The compilation step validates syntax and reports detailed error messages. Compiled expressions are managed as resources and can be freed when no longer needed.

Evaluation Modes

The module provides two distinct modes for query evaluation. Value evaluation returns typed results (&XPathValue) that can represent node sets, strings, numbers, booleans, dates, or sequences. Node iteration invokes a callback function for each matching node, enabling streaming processing of large result sets.

Usage Patterns

Compiling and evaluating queries:

APTR query;
if (xp::Compile(xml, "/bookstore/book[@price < 10]/title", &query) IS ERR::Okay) {
   XPathValue *result;
   if (xp::Evaluate(xml, query, &result) IS ERR::Okay) {
      // Process result...
      FreeResource(result);
   }
   FreeResource(query);
}

Node iteration with callbacks:

APTR query;
if (xp::Compile(xml, "//chapter[@status='draft']", &query) IS ERR::Okay) {
   auto callback = C_FUNCTION(process_node);
   xp::Query(xml, query, &callback);
   FreeResource(query);
}

Extensions

The module includes several Parasol-specific extensions beyond the standard specification. Content matching with the [=...] syntax allows matching on encapsulated content, e.g., /menu[=contentmatch]. Backslash (\) can be used as an escape character in attribute strings. The @* syntax matches any attribute, e.g., /root/section[@*="alpha"].

Functions

Classes

XQuery

Constants

XPathNodeType

XPathNodeType Type