Saxon.Api

 

 

Saxon.Api

Class XPathCompiler

public class XPathCompiler

An XPathCompiler object allows XPath queries to be compiled. The compiler holds information that represents the static context for the expression.

To construct an XPathCompiler, use the factory method NewXPathCompiler on the Processor object.

An XPathCompiler may be used repeatedly to compile multiple queries. Any changes made to the XPathCompiler (that is, to the static context) do not affect queries that have already been compiled. An XPathCompiler may be used concurrently in multiple threads, but it should not then be modified once initialized.

The XPathCompiler has the ability to maintain a cache of compiled expressions. This is active only if enabled by setting the Caching property. If caching is enabled, then the compiler will recognize an attempt to compile the same expression twice, and will avoid the cost of recompiling it. The cache is emptied by any method that changes the static context for subsequent expressions, for example, by setting the BaseUri property. Unless the cache is emptied, it grows indefinitely: compiled expressions are never discarded.

Property Summary
 bool AllowUndeclaredVariables

This property indicates whether the XPath expression may contain references to variables that have not been explicitly declared by calling DeclareVariable. The property is false by default (that is, variables must be declared).

 bool BackwardsCompatible

XPath 1.0 Backwards Compatibility Mode (that is, XPath 1.0 compatibility mode). If true, backwards compatibility mode is set. In backwards compatibility mode, more implicit type conversions are allowed in XPath expressions, for example it is possible to compare a number with a string. The default is false (backwards compatibility mode is off).

 string BaseUri

The base URI of the expression, which forms part of the static context of the expression. This is used for resolving any relative URIs appearing within the expression, for example in the argument to the doc() function.

 bool Caching

This property controls caching of compiled XPath expressions. If caching is enabled, then compiled expressions are saved in a cache and reused if the same expression is compiled again. The cache is cleared (invalidated) if any change is made to the properties of the XPathCompiler that would affect the validity of cached expressions. Caching is disabled by default.

 XdmItemType ContextItemType

The required context item type for the expression. This is used for optimizing the expression at compile time, and to check at run-time that the value supplied for the context item is the correct type.

 bool FastCompliation

Request fast compilation. Fast compilation will generally be achieved at the expense of run-time performance and quality of diagnostics. Fast compilation is a good trade-off if (a) the expression is known to be correct, and (b) once compiled, it is only executed once against a document of modest size.

 Processor Processor

Get the Processor from which this XPathCompiler was constructed

 bool SchemaAware

Say whether XPath expressions compiled using this XPathCompiler are schema-aware. They will automatically be schema-aware if the method XPathCompiler.ImportSchemaNamespace(String) is called. An XPath expression must be marked as schema-aware if it is to handle typed (validated) input documents.

 string XPathLanguageVersion

This property indicates which version of XPath language syntax is accepted. The accepted values are "2.0", "3.0", and "3.1". The default is "3.1".

 

Method Summary
 XPathExecutable Compile(string source)

Compile an expression supplied as a String.

 void DeclareCollation(Uri uri, CompareInfo compareInfo, CompareOptions options, bool isDefault)

Deprecated Since 9.6. All collations are now registered at the level of the Configuration. If this method is called, the effect is (a) the supplied collation is registered with the configuration, and (b) if isDefault=true, the collation becomes the default collation for this static context.
 void DeclareDefaultCollation(string uri)

Declare the default collation

 void DeclareNamespace(string prefix, string uri)

Declare a namespace for use by the XPath expression.

 void DeclareVariable(QName name)

Declare a variable for use by the XPath expression. If the expression refers to any variables, then they must be declared here, unless the AllowUndeclaredVariables property has been set to true.

 XdmValue Evaluate(string expression, XdmItem contextItem)

Compile and execute an expression supplied as a String, with a given context item.

 XdmItem EvaluateSingle(string expression, XdmItem contextItem)

Compile and execute an expression supplied as a String, with a given context item, where the expression is expected to return a single item as its result.

 string GetNamespaceURI(string lexicalName, bool useDefault)

Get the namespace URI part of a QName provided in lexical form (prefix:localname)

 void ImportSchemaNamespace(string uri)

Import schema definitions for a specified namespace. That is, add the element and attribute declarations and type definitions contained in a given namespace to the static context for the XPath expression.

 void SetDecimalFormatProperty(QName format, string property, string value)

Sets a property of a selected decimal format, for use by the format-number() function.

 

Property Detail

AllowUndeclaredVariables

public bool AllowUndeclaredVariables {get; set; }

This property indicates whether the XPath expression may contain references to variables that have not been explicitly declared by calling DeclareVariable. The property is false by default (that is, variables must be declared).

If undeclared variables are permitted, then it is possible to determine after compiling the expression which variables it refers to by calling the method EnumerateExternalVariables on the XPathExecutable object.

BackwardsCompatible

public bool BackwardsCompatible {get; set; }

XPath 1.0 Backwards Compatibility Mode (that is, XPath 1.0 compatibility mode). If true, backwards compatibility mode is set. In backwards compatibility mode, more implicit type conversions are allowed in XPath expressions, for example it is possible to compare a number with a string. The default is false (backwards compatibility mode is off).

Setting XPath 1.0 compatibility mode does not prevent the use of constructs defined in a later XPath version; rather, it modifies the semantics of some constructs.

BaseUri

public string BaseUri {get; set; }

The base URI of the expression, which forms part of the static context of the expression. This is used for resolving any relative URIs appearing within the expression, for example in the argument to the doc() function.

Caching

public bool Caching {get; set; }

This property controls caching of compiled XPath expressions. If caching is enabled, then compiled expressions are saved in a cache and reused if the same expression is compiled again. The cache is cleared (invalidated) if any change is made to the properties of the XPathCompiler that would affect the validity of cached expressions. Caching is disabled by default.

ContextItemType

public XdmItemType ContextItemType {get; set; }

The required context item type for the expression. This is used for optimizing the expression at compile time, and to check at run-time that the value supplied for the context item is the correct type.

FastCompliation

public bool FastCompliation {get; set; }

Request fast compilation. Fast compilation will generally be achieved at the expense of run-time performance and quality of diagnostics. Fast compilation is a good trade-off if (a) the expression is known to be correct, and (b) once compiled, it is only executed once against a document of modest size.

Set to true to request fast compilation; set to false to revert to the optimization options defined in the Configuration.

Processor

public Processor Processor {get; }

Get the Processor from which this XPathCompiler was constructed

SchemaAware

public bool SchemaAware {get; set; }

Say whether XPath expressions compiled using this XPathCompiler are schema-aware. They will automatically be schema-aware if the method XPathCompiler.ImportSchemaNamespace(String) is called. An XPath expression must be marked as schema-aware if it is to handle typed (validated) input documents.

XPathLanguageVersion

public string XPathLanguageVersion {get; set; }

This property indicates which version of XPath language syntax is accepted. The accepted values are "2.0", "3.0", and "3.1". The default is "3.1".

Requesting a value other than 3.1 restricts the XPath grammar to constructs defined in the appropriate version, and uses the appropriate subsets of the functions in the standard function library. However, the semantics of remaining constructs will generally follow the XPath 3.1 rules. For example, there is a rule in XPath 2.0 that casting to xs:QName is only permitted if the operand is a string literal, but this is not enforced when this property is set to "2.0".

There is no support for XPath 1.0.

Method Detail

Compile

public XPathExecutable Compile(string source)
throws
StaticError

Compile an expression supplied as a String.

Parameters:

source - A string containing the source text of the XPath expression

Returns:

An XPathExecutable which represents the compiled XPath expression object. The XPathExecutable may be run as many times as required, in the same or a different thread. The XPathExecutable is not affected by any changes made to the XPathCompiler once it has been compiled.

Throws:

StaticError -  Throws a Saxon.Api.StaticError if there is any static error in the XPath expression. This includes both syntax errors, semantic errors such as references to undeclared functions or variables, and statically-detected type errors.

DeclareCollation

public void DeclareCollation(Uri uri,
CompareInfo compareInfo,
CompareOptions options,
bool isDefault)

Deprecated Since 9.6. All collations are now registered at the level of the Configuration. If this method is called, the effect is (a) the supplied collation is registered with the configuration, and (b) if isDefault=true, the collation becomes the default collation for this static context.

Create a collation based on a given CompareInfo and CompareOptions

In the current and recent releases of Saxon, collations are always defined at the level of a Configuration. Declaring a collation here may therefore have wider effects than intended. It is recommended not to use this method, but to use Processor.DeclareCollation(Uri,CompareInfo,CompareOptions) instead.

Parameters:

uri - The collation URI to be used within the XPath expression to refer to this collation
compareInfo - The CompareInfo, which determines the language-specific collation rules to be used
options - Options to be used in performing comparisons, for example whether they are to be case-blind and/or accent-blind
isDefault - If true, this collation will be used as the default collation

DeclareDefaultCollation

public void DeclareDefaultCollation(string uri)

Declare the default collation

Parameters:

uri - the absolute URI of the default collation. This URI must identify a known collation; either one that has been explicitly declared, or one that is recognized implicitly, such as a UCA collation

DeclareNamespace

public void DeclareNamespace(string prefix,
string uri)

Declare a namespace for use by the XPath expression.

Parameters:

prefix - The namespace prefix to be declared. Use a zero-length string to declare the default namespace (that is, the default namespace for elements and types).
uri - The namespace URI. It is possible to specify a zero-length string to "undeclare" a namespace.

DeclareVariable

public void DeclareVariable(QName name)

Declare a variable for use by the XPath expression. If the expression refers to any variables, then they must be declared here, unless the AllowUndeclaredVariables property has been set to true.

Parameters:

name - The name of the variable, as a QName

Evaluate

public XdmValue Evaluate(string expression,
XdmItem contextItem)
throws
StaticError,
DynamicError

Compile and execute an expression supplied as a String, with a given context item.

Parameters:

expression - A string containing the source text of the XPath expression
contextItem - The context item to be used for evaluation of the XPath expression. May be null, in which case the expression is evaluated without any context item.

Returns:

An XdmValue which is the result of evaluating the XPath expression.

Throws:

StaticError -  Throws a Saxon.Api.StaticError if there is any static error in the XPath expression. This includes both syntax errors, semantic errors such as references to undeclared functions or variables, and statically-detected type errors.
DynamicError -  Throws a Saxon.Api.DynamicError if there is any dynamic error during evaluation of the XPath expression. This includes, for example, referring to the context item if no context item was supplied.

EvaluateSingle

public XdmItem EvaluateSingle(string expression,
XdmItem contextItem)
throws
StaticError,
DynamicError

Compile and execute an expression supplied as a String, with a given context item, where the expression is expected to return a single item as its result.

Parameters:

expression - A string containing the source text of the XPath expression
contextItem - The context item to be used for evaluation of the XPath expression. May be null, in which case the expression is evaluated without any context item.

Returns:

If the XPath expression returns a singleton, then the the XdmItem which is the result of evaluating the XPath expression. If the expression returns an empty sequence, then null. If the expression returns a sequence containing more than one item, then the first item in the result.

Throws:

StaticError -  Throws a Saxon.Api.StaticError if there is any static error in the XPath expression. This includes both syntax errors, semantic errors such as references to undeclared functions or variables, and statically-detected type errors.
DynamicError -  Throws a Saxon.Api.DynamicError if there is any dynamic error during evaluation of the XPath expression. This includes, for example, referring to the context item if no context item was supplied.

GetNamespaceURI

public string GetNamespaceURI(string lexicalName,
bool useDefault)

Get the namespace URI part of a QName provided in lexical form (prefix:localname)

Parameters:

lexicalName - The lexical QName. This may either be a plain NCName (a local name with no prefix or colon) or a lexical name using a prefix that is bound to a namespace.
useDefault - Set to true if the default namespace for elements and types is to be used in the case where there is no prefix. If false, no prefix means no namespace.

Returns:

The namespace URI associated with the prefix (or absence thereof) in the supplied lexical QName. The "null namespace" is represented by a zero length string. The method returns null if there is no known binding for the prefix used in the lexical QName.

ImportSchemaNamespace

public void ImportSchemaNamespace(string uri)

Import schema definitions for a specified namespace. That is, add the element and attribute declarations and type definitions contained in a given namespace to the static context for the XPath expression.

This method will not cause the schema to be loaded. That must be done separately, using the SchemaManager. This method will not fail if the schema has not been loaded (but in that case the set of declarations and definitions made available to the XPath expression is empty). The schema document for the specified namespace may be loaded before or after this method is called.

This method does not bind a prefix to the namespace. That must be done separately, using the DeclareNamespace method.

Parameters:

uri - The namespace URI whose declarations and type definitions are to be made available for use within the XPath expression.

SetDecimalFormatProperty

public void SetDecimalFormatProperty(QName format,
string property,
string value)

Sets a property of a selected decimal format, for use by the format-number() function.

This method checks that the value is valid for the particular property, but it does not check that all the values for the decimal format are consistent (for example, that the decimal separator and grouping separator have different values). This consistency check is performed only when the decimal format is used.

Parameters:

format - The name of the decimal format whose property is to be set. Supply null to set a property of the default (unnamed) decimal format. This correponds to a name used in the third argument of format-number().
property - The name of the property to set: one of "decimal-separator", "grouping-separator", "infinity", "NaN", "minus-sign", "percent", "per-mille", "zero-digit", "digit", or "pattern-separator".
value - The new value for the property.