Provides an interface for XQuery evaluation and execution.

The XQuery class provides comprehensive support for executing XPath 2.0 and XQuery expressions, enabling 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 class 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 class implements core XQuery 1.0 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.

Informal support for XQuery 2.0 functionality is also included but the feature-set is not yet complete.

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. Expressions can be run in their own thread, with the result available in Result and ResultString on completion, but the targeted XML object will be locked for the duration of the query.

Evaluation Modes

There are two distinct methods 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:

objXQuery::create query { statement="/bookstore/book[@price < 10]/title" };
if (query.ok()) {
   XPathValue *result;
   if (!query->evaluate(xml)) {
      std::string_view str;
      query->getResultString(str);
      log.msg("Got: %s", str.data());
   }
}

Node iteration with callbacks:

objXQuery::create query { statement="//chapter[@status='draft']" };
if (query.ok()) {
   auto callback = C_FUNCTION(process_node);
   query->search(xml, &callback);
}

Extensions

The module includes several Kotuku-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.

Structure

The XQuery class consists of the following fields:

Actions

The following actions are currently supported:

Methods

The following methods are currently supported:

<function>
  <name>function-name</name>
  <parameters>
    <parameter>
      <name>param1</name>
      <type>type1</type>
    </parameter>
    ...
  </parameters>
  <returnType>type</returnType>
  <userDefined>true|false</userDefined>
  <signature>function-signature</signature>
  <ast>... serialized function body AST ...</ast>
</function>

XEF Type

Options for XQuery evaluation flags.

XIF Type

Result flags for InspectFunctions().

XPVT Type

Type descriptors for XPathValue

XQF Type

Flags indicating the features of a compiled XQuery expression.