2004
Colin Adams and others
Colin
Adams
colin@colina.demon.co.uk Tuesday, April 13th, 2004

# Invoking the stand-alone XPath evaluator

To evaluate an XPath expression in a stand-alone environment (or equivalently, from a host language of your own devising), follow the following steps:

- Create an instance of `XM_XPATH_EVALUATOR`

- Build a static context.

- Call evaluate on the evaluator.

- Check for evaluation errors.

- Retrieving the results.

## Creating an evaluator

Call creation procedure make (digits, on_or_off) from class `XM_XPATH_EVALUATOR`. Digits is the precision for decimal arithmetic. It should be at least 18 (or 0, for infinite precision). On_or_off indicates wheter or not line numbering should be turned on for error messages.

`XM_XPATH_EVALUATOR` inherits from `XM_STRING_MODE`, so you should then call one of the string-mode setting procedures from that class on the evaluator. It will in turn call the same procedure on the Eiffel XML parser.

## Building a static context

Before calling evaluate, it is first necessary to create a static context. Two features are provided to do this:

- build_static_context a_source_uri: STRING xpath_one_compatibility: BOOLEAN warnings: BOOLEAN use_tiny_tree_model: BOOLEAN compact_tree: BOOLEAN

  The first argument is the URI of an XML source, against which the XPath expression will be evaluated.

  The second argument specifies if we should run in XPath 1.0 compatibility mode.

  The third argument requests warnings of differences between XPath 1.0 and XPath 1.0 compatibility mode. It is only meaningful if the second argument is True.

  The fourth argument specifies the tree model to use. If performace and/or memory usage are important to your application, then you should make measurements to see which tree model suits you best.

  The fifth argument specifies whether or not to compact the tree after parsing. it is not implemented at the time of writing.

  This feature parses a_source_uri as XML, and builds an instance of `XM_XPATH_DOCUMENT`. It sets was_build_error to true if any error was found, in which case error_message will contain the text of the parse error.

  If no error was detected, it then creates a static context, using the document node as the context item.

- set_static_context a_static_context: XM_XPATH_STAND_ALONE_CONTEXT

  This feature enables you to supply a tailored static context. You can also use it if you wish to perform an XPath evaluation without referencing an XML document (this is of rather limited usefulness, but you might want to use it for evaluating environment variables as booleans, for instance).

  Having built your static context, you may then declare variables, if you wish.

  See alsoTailoring the static context.

## Performing the evaluation

The sole argument to evaluate an_expression_text: STRING is the text of the XPath expression which you wish to evaluate.

## Checking for evaluation errors

After calling evaluate, check is_error to see if an error occured. if it did, then feature error_value contains the details of the error. See `XM_XPATH_ERROR_VALUE`.

## Retrieving the results of an evaluation

If the evaluation was successful, evaluated_items: DS_LINKED_LIST [XM_XPATH_ITEM] contains a list of results. These are all of type `XM_XPATH_ITEM`, representing an XPath item. An item may either be a node (`XM_XPATH_NODE`), or an atomic value (`XM_XPATH_ATOMIC_VALUE`).