About xpath:

Plexippus XPath is an XPath 1.0 implementation for Common Lisp.

About xpath-sys:

The XPATH-SYS package provides an API for extensions to Plexippus XPath.

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).
See also:

Macro xpath (form)
Arguments:
  • form -- a sexpr-based XPath form
Returns:
a list consisting of symbol XPATH and the form
Details:
This macro is used to specify sexpr-based XPath expression for evaluate
See also:

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.

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.
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.
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.
See also:

Function node-set-value (value)
Arguments:
  • value -- value of an XPath-supported type or an XML node
Returns:
a node-set
Details:
Returns the value of XPath node-set() function.

For XML nodes returns a node-set consisting of the single node specified by value.
See also:

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.

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.

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))
Arguments:
  • node -- an XML node
  • size -- context size, a non-negative integer or a function without arguments returning non-negative integer
  • position -- context position, a positive integer
Details:
Makes a context object.
See also:

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)
Arguments:
Returns:
a node-set or nil
Details:
Returns the first node in the node-set or nil if it's empty.
See also:

Function all-nodes (node-set)
Arguments:
Returns:
a list of nodes
Details:
Returns all nodes of the node-set as a list.
See also:

Function map-node-set (func node-set)
Arguments:
  • func -- a function
  • node-set -- a node-set
Returns:
nil
Details:
Calls func for each node 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.
See also:

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.
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.
See also:

Function make-node-set-iterator (node-set)
Arguments:
Returns:
a node-set iterator
Details:
Creates a node set iterator for node-set

Node set iterators can be used to iterate over node-sets. This can be done without causing the XPath engine to find out all their nodes and using non-local exits.
See also:

Function node-set-iterator-end-p (iterator)
Arguments:
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:
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:
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)
Arguments:
  • object -- a value of any type
Returns:
a generalized boolean
Details:
Returns true if object is a node-set
See also:

Function node-set-empty-p (node-set)
Arguments:
Returns:
a generalized boolean
Details:
Returns true if node-set is empty
See also:

Function list->node-set (list)
Arguments:
  • list -- a list of nodes
Returns:
a node-set
Details:
Makes a node-set from the list of nodes.
See also:

Function sort-node-set (node-set)
Arguments:
Returns:
a sorted version of node-set
Details:
Sorts the node-set according to document order.
See also:

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:

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).
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 variables in xpath

Variable *navigator*

No documentation string. Possibly unimplemented or incomplete.


Pipes

Pipes are lazy lists, inspired by their implementation in Norvig's 'Paradigms of Artificial Intelligence Programming'.

Macro make-pipe (head tail)
Arguments:
  • head -- pipe head (evaluated)
  • tail -- tail expression
Returns:
a pipe
Details:
Constructs a pipe (lazy list).

The head expression is evaluated immediatelly. The value of head will be returned by pipe-head called for the pipe object returned by make-pipe. Evaluation of tail expression is delayed until pipe-tail is called for the pipe returned by this function. Evaluation of tail expression should produce a pipe or a list.
See also:

Function pipe-head (pipe)
Arguments:
  • pipe -- a pipe
Returns:
an object
Details:
Returns the head of the pipe.

Function pipe-tail (pipe)
Arguments:
  • pipe -- a pipe
Returns:
an object
Details:
Returns the tail of the list.

First time pipe-tail is called it causes pipe tail expression to be evaluated and remembered for later calls.

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. Conceptually, they are unordered, with the most important order defined on them being the document order.

As a data structure though, node sets are backed by a pipe, and the order of elements in that pipe is well-documented: By default, the pipe of returned node sets is sorted into document order. When unordered results are requested, the order is usually not specified, but in some cases, are already sorted according to the axis being queried, which is usually sorted either in document order,or in reverse document order. See xpath:evaluate for the unordered argument.

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


Function make-node-set (pipe &optional (ordering unordered))
Arguments:
  • pipe -- a pipe
  • ordering -- one of :document-order, :reverse-document-order, :unordered
Returns:
a node-set
Details:
Makes a node-set containing nodes from the pipe with specified ordering.
See also:

Function pipe-of (node-set)
Arguments:
Returns:
a pipe
Details:
Returns the pipe that contains the elements of the node-set.
See also:

Implementing environments

Environments provide compilation-time configuration for XPath. An environment is a CLOS object, which is queried by the compiler using generic functions that users can implement on their own subclasses of xpath::environment.

The default environment class implements a `dynamic' environment, backed by information bound in dynamic variables, so that typical uses of XPath work without special environment classes.

Function environment-find-namespace (environment prefix)
Arguments:
  • environment -- an XPath environment object
  • prefix -- prefix part of a QName
Details:
Returns namespace URI for specified prefix.

Function environment-find-variable (environment local-name uri)
Arguments:
  • environment -- an XPath environment object
  • local-name -- local part of expanded-name of the function
  • uri -- namespace URI of the function
Returns:
XPath variable "thunk"
Details:
Finds an XPath variable by local-name and uri.

XPath variable is represented by a "thunk". A "thunk" is a function that takes an instance of context as its argument and returns the value of one of XPath types.
See also:

Function environment-find-function (environment local-name uri)
Arguments:
  • environment -- an XPath environment object
  • local-name -- local part of expanded-name of the function
  • uri -- namespace URI of the function
Returns:
an XPath function or nil if it cannot be found
Details:
Finds an XPath function by local-name and uri.

XPath function is a Lisp function that takes zero or more "thunks" as its arguments (corresponding to XPath expressions passed as function arguments) and returns a new "thunk". A "thunk" is a function that takes an instance of context as its argument and returns the value of one of XPath types.
See also:

Defining extension functions

XPath defines built-in functions in the empty namespace. Using the extension API, user code can implement XPath functions addressed using other namespaces.

Macro define-extension (name uri &optional documentation)
Arguments:
  • name -- the name of XPath extension (a symbol)
  • uri -- URI corresponding to XPath extension (a string)
  • documentation -- documentation string for the XPath extension
Details:
Defines an XPath extension with specified name and uri.

An XPath extension is a collection of XPath functions that are defined using one of define-xpath-function/lazy, define-xpath-function/eager or define-xpath-function/single-type macros. In order to use the extension, one must bind a prefix string to its uri using with-namespaces macro.

Example: 
   (defparameter *my-namespace* "http://example.net/my-xpath-extension")


   (xpath-sys:define-extension
       my-ext *my-namespace*
     "My Extension")


   (xpath-sys:define-xpath-function/single-type my-ext add-quotes string (string)
     (concat "\"" string "\""))


   (defun get-my-quoted-string(doc)
     (with-namespaces (("my" *my-namespace*))
       (evaluate "add-quotes(//some-element)" doc)))
See also:

Macro define-xpath-function/lazy (ext name args &body body)
Arguments:
  • ext -- name of an XPath extension (a symbol)
  • name -- XPath function name
  • args -- XPath function arguments
Details:
Defines an XPath function, "lazy" style.

The body is evaluated during compilation of XPath expressions each time the function being defined is referenced. It's passed a list of "thunks" corresponding to XPath function arguments and should return a new "thunk". A "thunk" is a function that takes an XPath context as argument and returns value of one of XPath types (string, boolean, number, node set).

Example: 
   (define-xpath-function/lazy my-ext my-if (v if-part else-part)
     #'(lambda (ctx)
         (if (boolean-value (funcall v ctx))
             (funcall if-part ctx)
             (funcall else-part ctx))))
See also:

Macro define-xpath-function/eager (ext name args &body body)
Arguments:
  • ext -- name of an XPath extension (a symbol)
  • name -- XPath function name
  • args -- XPath function arguments
Details:
Defines an XPath function, "eager" style.

The body is evaluated during evaluation of XPath expressions each time the function being defined is called. It's passed a list of values corresponding to XPath function arguments and should return a value of one of XPath types (string, boolean, number, node set).

Example: 
   (define-xpath-function/eager my-ext join (delim node-set)
     (reduce (lambda (a b) (concatenate 'string a delim b))
             (map-node-set->list #'string-value node-set)))
See also:

Macro define-xpath-function/single-type (ext name type args &body body)
Arguments:
  • ext -- name of an XPath extension (a symbol)
  • name -- XPath function name
  • args -- XPath function arguments
Details:
Defines an XPath function, "eager" style with automatic type conversion.

The body is evaluated during evaluation of XPath expressions each time the function being defined is called. It's passed a list of values corresponding to XPath function arguments and should return a value of one of XPath types (string, boolean, number, node set). Argument values are automatically converted to specified XPath type.

Example: 
   (xpath-sys:define-xpath-function/single-type my-ext add-quotes string (string)
     (concat "\"" string "\""))
See also:

Function find-xpath-function (local-name uri)
Arguments:
  • local-name -- local part of the function name
  • uri -- namespace URI of the function
Returns:
an XPath function object
Details:
Performs an XPath function lookup using standard lookup rules

All defined extensions for the namespace specified by uri are scanned for function with specified local-name.

Profiling support

The profiling facility records the run time of XPath evaluations and pattern matching.

Function enable-profiling (&optional (verbosep t))
Returns:
nil
Details:
Enables profiling.

Resets any existing profile samples and enables profiling for future XPath compilations.

Previously returned closures that were created with profiling disabled are not affected by this setting, but closures created during an earlier profiling session will start sampling again.

But note that evaluate, node-matches-p, and pattern-case will recompile their cached closure when this setting has changed.

Profiling is not thread safe.

See also:

Function disable-profiling ()
Returns:
nil
Details:
Disables profiling.

Disables profiling for future XPath compilations, but keeps recorded profiling samples for report.

Previously returned closures that were created with profiling enabled will not record samples until profiling is re-activated.

See also:

Function report (&key (group-identical-expressions t))
Arguments:
  • group-identical-expressions -- Boolean, indicates whether times recorded for closures that were compiled separately, but for the same expression, are to be summed together. Default is T.
Details:
Shows profiling output.

Shows cumulative run time and real time, number of calls, and average run time for each XPath expression or XPattern matcher that was invoked.
See also:

Miscellaneous functions

Other useful functions:

Function get-node-id (node-or-node-set)
Arguments:
  • node-or-node-set -- a node-set or a single XML node
Returns:
an alphanumeric string
Details:
Generates an unique identifier for the first node node-set (or, if a node is specified, for that node).

This function is similar to the generate-id() XSLT function, but its results are unique only within its document, whereas XSLT also prepends an ID designating the document.
See also:

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-sys:define-extension, macro
xpath-sys:define-xpath-function/eager, macro
xpath-sys:define-xpath-function/lazy, macro
xpath-sys:define-xpath-function/single-type, macro
xpath-sys:disable-profiling, function
xpath:do-node-set, macro
xpath-sys:enable-profiling, function
xpath-sys:environment-find-function, function
xpath-sys:environment-find-namespace, function
xpath-sys:environment-find-variable, function
xpath:evaluate, function
xpath:evaluate-compiled, function
xpath-sys:find-xpath-function, function
xpath:first-node, function
xpath-sys:get-node-id, function
xpath:list->node-set, function
xpath:make-context, function
xpath-sys:make-node-set, function
xpath:make-node-set-iterator, function
xpath-sys:make-pipe, macro
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-sys:pipe-head, function
xpath-sys:pipe-of, function
xpath-sys:pipe-tail, function
xpath-sys:report, 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