Class TXQueryEngine

DescriptionHierarchyFieldsMethodsProperties

Unit

Declaration

type TXQueryEngine = class(TObject)

Description

This is the XPath/XQuery-engine

You can use this class to evaluate a XPath/XQuery-expression on a certain document tree.
For example, TXQueryEngine.evaluateStaticXPath2('expression', nil) returns the value of the evaluation of expression.

Syntax of a XQuery / XPath / Pseudo-XPath-Expression

This XQuery engine currently supports XPath 2.0, XQuery 1.0 and JSONiq, with some extensions and minor deviations.

Some very basic, standard XPath examples, for people who do not have seen XPath before:

Differences between this implementation and standard XPath/XQuery (most differences can be turned off with the respective option or the field in the default StaticContext):

Extended syntax:

New functions:

You can look at the unit tests in the tests directory to see many (> 3000) examples.

Using the class in FPC

The easiest way to evaluate a XQuery/XPath-expression is to call the class methods like TXQueryEngine.evaluateStaticXPath2('expression', nil) or TXQueryEngine.evaluateStaticXPath2('expression', nil).toInt64 which returns the value of the expression, converted to the corresponding type.
If you want to process a html/xml document, you have to pass the root TTreeNode (obtained by TTreeParser) instead of nil.


If you call TXQueryEngine.evaluateStaticXPath2('expression', nil) without a following toType-call, you obtain the result as an IXQValue. (see IXQValue on how to use it)
With a toType-call it is converted in the corresponding type, e.g. toInt64 returns a int64, toString a string, toNode a TTreeNode or toDecimal an extended.

You can also create a TXQueryEngine instance and then call parseXPath2('expression') and evaluateXPath2().
This is not as easy, but you have more options:
For the basic you can set separate root (/) (with the property RootElement) and parent elements (./) (with the property ParentElement), or you can read and define variables in the expression, or change other behaviours.



Compatibility to previous version
The following breaking changes occured to make it more standard compatible:

Hierarchy

Overview

Fields

Public RootElement: TTreeNode;
Public ParentElement: TTreeNode;
Public TextElement: TTreeNode;
Public CurrentDateTime: TDateTime;
Public ImplicitTimezone: TDateTime;
Public StaticContext: TXQStaticContext;
Public VariableChangelog: TXQVariableChangeLog;
Public OnEvaluateVariable: TXQEvaluateVariableEvent;
Public OnDefineVariable: TXQDefineVariableEvent;
Public OnDeclareExternalVariable: TXQDeclareExternalVariableEvent;
Public OnDeclareExternalFunction: TXQDeclareExternalFunctionEvent;
Public OnImportModule: TXQImportModuleEvent;
Public OnTrace: TXQTraceEvent;
Public OnCollection: TXQEvaluateVariableEvent;
Public OnParseDoc: TXQParseDocEvent;
Public AllowExtendedStrings: boolean;
Public AllowJSON: boolean;
Public AllowJSONLiterals: boolean;
Public GlobalNamespaces: TNamespaceList;
Public AutomaticallyRegisterParsedModules: boolean;

Methods

Public procedure clear;
Public function parseXPath2(s:string; sharedContext: TXQStaticContext = nil): IXQuery;
Public function parseXQuery1(s:string; sharedContext: TXQStaticContext = nil): IXQuery;
Public function parseCSS3(s:string): IXQuery;
Public function evaluate(tree:TTreeNode = nil): IXQValue;
Public constructor create;
Public destructor Destroy; override;
Public function evaluateXPath2(expression: string; tree:TTreeNode = nil): IXQValue;
Public function evaluateXQuery1(expression: string; tree:TTreeNode = nil): IXQValue;
Public function evaluateCSS3(expression: string; tree:TTreeNode = nil): IXQValue;
Public class function evaluateStaticXPath2(expression: string; tree:TTreeNode = nil): IXQValue;
Public class function evaluateStaticCSS3(expression: string; tree:TTreeNode = nil): IXQValue;
Public procedure registerModule(module: IXQuery);
Public function findModule(const namespaceURL: string): TXQuery;
Public class function findNativeModule(const ns: string): TXQNativeModule;
Public class procedure registerCollation(const collation: TXQCollation);
Public class function getCollation(id:string; base: string): TXQCollation;
Public class procedure registerNativeModule(const module: TXQNativeModule);

Properties

Public property LastQuery: IXQuery read FLastQuery;

Description

Fields

Public RootElement: TTreeNode;

Root element

Public ParentElement: TTreeNode;

Set this to the element you want as current. The XPath expressions will be evaluated relative to this, so e.g. @attrib will get you the attribute attrib of this element

Public TextElement: TTreeNode;

Use this to override the text node returned by text(). This is useful if you have an element <a>xx<b/>yy</a>. If TextNode is nil text() will return xx, but you can set it to yy. However, ./text() will always return xx.

Public CurrentDateTime: TDateTime;

Current time

Public ImplicitTimezone: TDateTime;

Local timezone (nan = unknown, 0 = utc).

Public StaticContext: TXQStaticContext;

XQuery static context, defining various default values.

Public VariableChangelog: TXQVariableChangeLog;

All global variables that have been set (if a variable was overriden, it stores the old and new value)

Public OnEvaluateVariable: TXQEvaluateVariableEvent;

Event called if a variable has to be read. (Defaults to @VariableChangelog.evaluateVariable, but can be changed)

Public OnDefineVariable: TXQDefineVariableEvent;

Event called if a variable is set (Defaults to @VariableChangelog.defineVariable, but can be changed)

Public OnDeclareExternalVariable: TXQDeclareExternalVariableEvent;

Event called to import a variable that is declared as "declare variable ... external" in a XQuery expression

Public OnDeclareExternalFunction: TXQDeclareExternalFunctionEvent;

Event called to import a function that is declared as "declare function ... external" in a XQuery expression.

Public OnImportModule: TXQImportModuleEvent;

Event called to import a XQuery module that has not previously be defined

Public OnTrace: TXQTraceEvent;

Event called by fn:trace

Public OnCollection: TXQEvaluateVariableEvent;

Event called by fn:collection

Public OnParseDoc: TXQParseDocEvent;

Event called by fn:doc (if nil, a default xml parser is used)

Public AllowExtendedStrings: boolean;

If strings with x-prefixes are allowed, like x"foo{$variable}bar" to embed xquery expressions in strings

Public AllowJSON: boolean;

If {"foo": bar} and [..] can be used to create json objects/arrays (default false, unless xquery_json was loaded, then it is true)

Public AllowJSONLiterals: boolean;

If true/false/null literals are treated like true()/false()/jn:null() (default true! However, this option is ignored and handled as false, if allowJSON is false).

Public GlobalNamespaces: TNamespaceList;

Globally defined namespaces

Public AutomaticallyRegisterParsedModules: boolean;
 

Methods

Public procedure clear;

Clears all data.

Public function parseXPath2(s:string; sharedContext: TXQStaticContext = nil): IXQuery;

Parses a new XPath 2.0 expression and stores it in tokenized form.

Public function parseXQuery1(s:string; sharedContext: TXQStaticContext = nil): IXQuery;

Parses a new XQuery expression and stores it in tokenized form.

Public function parseCSS3(s:string): IXQuery;

Parses a new CSS 3.0 Selector expression and stores it in tokenized form.

Public function evaluate(tree:TTreeNode = nil): IXQValue;

Evaluates a previously parsed query and returns its value as TXQValue

Public constructor create;
 
Public destructor Destroy; override;
 
Public function evaluateXPath2(expression: string; tree:TTreeNode = nil): IXQValue;

Evaluates an XPath 2.0 expression with a certain tree element as current node.

Public function evaluateXQuery1(expression: string; tree:TTreeNode = nil): IXQValue;

Evaluates an XQuery 1.0 expression with a certain tree element as current node.

Public function evaluateCSS3(expression: string; tree:TTreeNode = nil): IXQValue;

Evaluates an CSS 3 Selector expression with a certain tree element as current node.

Public class function evaluateStaticXPath2(expression: string; tree:TTreeNode = nil): IXQValue;

Evaluates an expression with a certain tree element as current node.

Public class function evaluateStaticCSS3(expression: string; tree:TTreeNode = nil): IXQValue;

Evaluates an expression with a certain tree element as current node.

Public procedure registerModule(module: IXQuery);

Registers an XQuery module. A XQuery module is created by parsing (not evaluating) a XQuery expression that contains a "module" declaration

Public function findModule(const namespaceURL: string): TXQuery;

Finds a certain registered XQuery module

Public class function findNativeModule(const ns: string): TXQNativeModule;

Finds a native module.

Public class procedure registerCollation(const collation: TXQCollation);

Registers a collation for custom string comparisons

Public class function getCollation(id:string; base: string): TXQCollation;

Returns the collation for an url id

Public class procedure registerNativeModule(const module: TXQNativeModule);
 

Properties

Public property LastQuery: IXQuery read FLastQuery;

Last parsed query


Generated by PasDoc 0.11.0 on 2013-07-13 02:13:22