About xpath:
Plexippus XPath is an XPath 1.0 implementation for Common Lisp.
Contents
Using XPath
Almost all uses of XPath involve the evaluate function, which can parse, compile, and invoke XPath expressions.Function evaluate (xpath context &optional unordered-p)
Arguments:
- xpath -- an XPath expression
- context -- an XPath context
- unordered-p -- specify true to get unordered node-set
Returns:
the result of evaluating xpath within the context
Details:
Evaluates an XPath expression
xpath can be a string, a sexpr-based XPath epression or a compiled expression. The context can be obtained using make-context. As an alternative, a node can be specifed.
If unordered-p is false (default) and value being returned is a node-set, it will be sorted using sort-node-set so its nodes will be in document order. If unordered-p is true, the order of the nodes is unspecified. Unordered mode can be significantly faster in some cases (and never slower).
xpath can be a string, a sexpr-based XPath epression or a compiled expression. The context can be obtained using make-context. As an alternative, a node can be specifed.
If unordered-p is false (default) and value being returned is a node-set, it will be sorted using sort-node-set so its nodes will be in document order. If unordered-p is true, the order of the nodes is unspecified. Unordered mode can be significantly faster in some cases (and never slower).
See also:
Macro xpath (form)
Compiling XPath dynamically
compile-xpath allows the compilation of XPath into a closure ahead of time, so that evaluate only needs to invoke that closure rather than having to re-compile it first.Although evaluate itself already performs caching of compiled closures, explicit precompilation can aid optimizations if one call site uses multiple XPath expressions.
Explicit compilation using compile-xpath is also required when using custom environment classes, since evaluate compiles expressions using the dynamic environment only.
parse-xpath can be used to translate the standard string representation of XPath into a Plexippus-specific sexp representation. Both compile-xpath and evaluate accept sexps instead of strings.
Function parse-xpath (str)
Arguments:
- str -- a string
Returns:
a s-expression-based XPath expression
Details:
Parses a string-based XPath expression into s-expression-based one.
Function compile-xpath (xpath &optional (environment (make-dynamic-environment *dynamic-namespaces*)))
Arguments:
- xpath -- an XPath expression
Returns:
a compiled XPath expression
Details:
Compiles an XPath expression
The xpath expression is compiled using current environment if it isn't compiled yet. xpath can be a string, a sexpr-based XPath epression or a compiled expression. In the latter case xpath argument value itself is returned.
The xpath expression is compiled using current environment if it isn't compiled yet. xpath can be a string, a sexpr-based XPath epression or a compiled expression. In the latter case xpath argument value itself is returned.
Type coercion
These correspond to the XPath functions boolean(), string(), and number(). In addition, node-set-value is provided, which turns nodes into node sets.Function boolean-value (value)
Arguments:
- value -- value of an XPath-supported type or an XML node
Returns:
an XPath boolean
Details:
Returns the value of XPath boolean() function.
For XML nodes returns the value of XPath boolean() function applied to the result of calling string-value for the specified value.
For XML nodes returns the value of XPath boolean() function applied to the result of calling string-value for the specified value.
See also:
Function string-value (value)
Arguments:
- value -- value of an XPath-supported type or an XML node
Returns:
an XPath string
Details:
Returns the value of XPath number() function.
For XML nodes returns the value of xpath-protocol:node-text applied to the specified value.
For XML nodes returns the value of xpath-protocol:node-text applied to the specified value.
See also:
Function number-value (value)
Arguments:
- value -- value of an XPath-supported type or an XML node
Returns:
an XPath number
Details:
Returns the value of XPath number() function.
For XML nodes returns the value of XPath number() function applied to the result of calling string-value for the specified value.
For XML nodes returns the value of XPath number() function applied to the result of calling string-value for the specified value.
See also:
Function node-set-value (value)
The dynamic environment
The default enviroment used by evaluate is the dynamic environment, backed by information bound in dynamic variables. The following macros are used to bind these variables. They have dynamic scope. (The dynamic environment is currently not capable of dynamic declarations for variables, but can be used with extension functions that are declared globally.)(The XPATH-SYS defined an environment protocol for user-defined environment classes.)
Macro with-namespaces ((&rest bindings) &body body)
Arguments:
- bindings -- bindings in the form (PREFIX VALUE). PREFIXes and VALUEs are evaluated
Returns:
the tresult of evaluating body
Details:
Provides namespace bindings for XPath compilation
Namespace bindings are used for compilation of XPath expressions. nil is equivalent of "" prefix. Bindings provided by this macro have dynamic scope.
Namespace bindings are used for compilation of XPath expressions. nil is equivalent of "" prefix. Bindings provided by this macro have dynamic scope.
Macro with-variables ((&rest bindings) &body body)
Arguments:
- bindings -- bindings in the form (QNAME VALUE). QNAMEs and VALUEs are evaluated
Returns:
the tresult of evaluating body
Details:
Provides bindings for XPath variables
Variable bindings are used for evaluation of compiled XPath expressions. Bindings provided by this macro have dynamic scope.
Variable bindings are used for evaluation of compiled XPath expressions. Bindings provided by this macro have dynamic scope.
The run-time context
Instead of passing a node to evaluate, user code can construct a full context object.The context object specifies values to be returned by position(), current(), and last().
Class context
Superclasses:
common-lisp:standard-object, sb-pcl::slot-object, common-lisp:t
Documented Subclasses:
None
Details:
Represents XPath context
Function make-context (node &optional (size 1) (position 1) (starting-node node))
Function context-node (context)
Arguments:
- context -- an XPath context
Returns:
an XML node
Details:
Returns the context node of the XPath context.
Function context-starting-node (context)
Arguments:
- context -- an XPath context
Returns:
an XML node
Details:
Returns the node for which the whole XPath expression is evaluated.
Function context-position (context)
Arguments:
- context -- an XPath context
Returns:
a positive integer
Details:
Returns the current position of the XPath context.
Function context-size (context)
Arguments:
- context -- an XPath context
Returns:
a non-negative number
Details:
Returns the size of context
If the context size was specified as a function, the result of calling that function is returned.
Node sets
Node sets are the XPath data type used to represent the results of evaluations that select multiple nodes. As sets, they never contain duplicates.In addition to the high-level functions defined here, the XPATH-SYS package defined several low-level node set functions. Please also refer to the description there for details on node set order.
Function first-node (node-set)
Function all-nodes (node-set)
Function map-node-set (func node-set)
Function map-node-set->list (func node-set)
Arguments:
- func -- a function
- node-set -- a node-set
Returns:
a list
Details:
Calls func for each node in node-set and conses up a list of its return values
The operation is performed lazily, i.e. if it's terminated via a non-local exit it doesn't necessarily cause the XPath engine to find out all nodes in the node-set internally.
The operation is performed lazily, i.e. if it's terminated via a non-local exit it doesn't necessarily cause the XPath engine to find out all nodes in the node-set internally.
See also:
Macro do-node-set ((var node-set &optional result) &body body)
Arguments:
- var -- symbol, a variable name
- node-set -- a node-set
- result -- a form
Returns:
the result of evaluating result
Details:
Executes body with var bound to successive nodes in node-set
The operation is performed lazily, i.e. if it's terminated via a non-local exit it doesn't necessarily cause the XPath engine to find out all nodes in the node-set internally.
Returns nil if result form isn't specified.
The operation is performed lazily, i.e. if it's terminated via a non-local exit it doesn't necessarily cause the XPath engine to find out all nodes in the node-set internally.
Returns nil if result form isn't specified.
See also:
Function make-node-set-iterator (node-set)
Function node-set-iterator-end-p (iterator)
Arguments:
- iterator -- a node-set iterator returned by make-node-set-iterator
Returns:
a generalized boolean
Details:
Returns true if iterator points to the end of its node set
See also:
Function node-set-iterator-next (iterator)
Arguments:
- iterator -- a node-set iterator returned by make-node-set-iterator
Returns:
the value of iterator
Details:
Advances iterator if it's not at the end of its node set, does nothing otherwise.
See also:
Function node-set-iterator-current (iterator)
Arguments:
- iterator -- a node-set iterator returned by make-node-set-iterator
Returns:
a node or nil
Details:
Returns current node of iterator or nil if it's at the end of its node set.
See also:
Function node-set-p (object)
Function node-set-empty-p (node-set)
Function list->node-set (list)
Function sort-node-set (node-set)
Miscellaneous
Other useful functions, variables, and classes:Macro with-plx-extensions (&body body)
Details:
Binds plx prefix to Plexippus XPath extensions namespace.
The following functions are currently available:
The following functions are currently available:
plx:matches(string, pattern, flags?)Returns true if string is matched by regular expression pattern, false otherwise. Optional flags specify modifiers (i, m, s). CL-PPCRE is used as regular expression engine.
plx:replace(string, pattern, replacement, flags?)Returns string with all matches of regular expression pattern replaced with replacement. Optional flags specify modifiers (i, m, s).
plx:current()Returns a node-set consisting of one node which was specifed as context node for expression evaluation. Analagous to current() function of XSLT.
plx:generate-id(node-set?)Returns an alphanumeric string that uniquely identifies the first node of the node-set (or context node if node-set isn't specified) within its document. Analagous to generate-id() of XSLT (except that the latter works across multiple documents).
See also:
*navigator*
Class xpath-error
Superclasses:
common-lisp:simple-error, common-lisp:simple-condition, common-lisp:error, common-lisp:serious-condition, common-lisp:condition, sb-pcl::slot-object, common-lisp:t
Documented Subclasses:
None
Details:
The class of all xpath errors.
Other functions in xpath
Function evaluate-compiled (compiled-xpath context &optional unordered-p)
Arguments:
- compiled-xpath -- a compiled XPath expression
- context -- an XPath context
- unordered-p -- specify true to get unordered node-set
Returns:
the result of evaluating compiled-xpath within the context
Details:
Evaluates a compiled XPath expression returned by compile-xpath
The context can be obtained using make-context. As an alternative, a node can be specifed.
If unordered-p is false (default) and value being returned is a node-set, it will be sorted using sort-node-set so its nodes will be in document order. If unordered-p is true, the order of the nodes is unspecified. Unordered mode can be significantly faster in some cases (and never slower).
The context can be obtained using make-context. As an alternative, a node can be specifed.
If unordered-p is false (default) and value being returned is a node-set, it will be sorted using sort-node-set so its nodes will be in document order. If unordered-p is true, the order of the nodes is unspecified. Unordered mode can be significantly faster in some cases (and never slower).
See also:
Function xpath-error (fmt &rest args)
Arguments:
- fmt -- format control string
- args -- format arguments
Details:
Signals the xpath-error condition with specified message.
See also:
Other classes in xpath
Class node-set
Superclasses:
common-lisp:standard-object, sb-pcl::slot-object, common-lisp:t
Documented Subclasses:
None
Returned by:
Details:
Represents an XPath node set
Other variables in xpath
Variable *navigator*
No documentation string. Possibly unimplemented or incomplete.
Index of exported symbols
xpath: | *navigator*, variable (undocumented) |
xpath: | all-nodes, function |
xpath: | boolean-value, function |
xpath: | compile-xpath, function |
xpath: | context, class |
xpath: | context-node, function |
xpath: | context-position, function |
xpath: | context-size, function |
xpath: | context-starting-node, function |
xpath: | do-node-set, macro |
xpath: | evaluate, function |
xpath: | evaluate-compiled, function |
xpath: | first-node, function |
xpath: | list->node-set, function |
xpath: | make-context, function |
xpath: | make-node-set-iterator, function |
xpath: | map-node-set, function |
xpath: | map-node-set->list, function |
xpath: | node-set, class |
xpath: | node-set-empty-p, function |
xpath: | node-set-iterator-current, function |
xpath: | node-set-iterator-end-p, function |
xpath: | node-set-iterator-next, function |
xpath: | node-set-p, function |
xpath: | node-set-value, function |
xpath: | number-value, function |
xpath: | parse-xpath, function |
xpath: | sort-node-set, function |
xpath: | string-value, function |
xpath: | with-namespaces, macro |
xpath: | with-plx-extensions, macro |
xpath: | with-variables, macro |
xpath: | xpath, macro |
xpath: | xpath-error, function |
xpath: | xpath-error, class |