Common Lisp Package: XML.LOCATION

This package contains the public interface of the cmxl-location system. The main entry point is the generic function `loc', which creates `location' instances from XML documents and XPaths. The resulting objects can be queried and modified using the location-* accessors and the generic functions `name', `val' and `@'.

README:

FUNCTION

Public

->XML-CONVERSION-ERROR (VALUE TYPE DESTINATION &OPTIONAL FORMAT-CONTROL &REST FORMAT-ARGUMENTS)

Signal an `->xml-conversion-error' with data VALUE, TYPE and DESTINATION and optional FORMAT-CONTROL and FORMAT-ARGUMENTS.

ENSURE-LOCATION-CLASS (MIXINS)

Find or make the dynamic class composed of MIXINS.

LOCATION-CLASSES

Return list of all classes in the family.

XML->-CONVERSION-ERROR (VALUE TYPE &OPTIONAL FORMAT-CONTROL &REST FORMAT-ARGUMENTS)

Signal an `xml->-conversion-error' with data VALUE and TYPE and optional FORMAT-CONTROL and FORMAT-ARGUMENTS.

Private

%ADD-AVAILABLE-CONVERSION-METHODS (CONDITION STREAM)

Print a list of methods of the generic function associated to CONDITION onto STREAM.

%ADD-AVAILABLE-CONVERSION-METHODS-FOR-FUNCTION (FUNCTION STREAM)

Format the list of methods of the generic function designated by NAME onto STREAM.

%COMPUTE-LOCATION-CLASS (&REST ARGS &KEY (IF-MULTIPLE-MATCHES ERROR) (IF-NO-MATCH ERROR) (ASSIGN-MODE REPLACE) &ALLOW-OTHER-KEYS)

Compute a location class based on the values of IF-MULTIPLE-MATCHES and IF-NO-MATCH. This is a separate function to make it usable in compiler macros.

%EXPAND-XPATH-ELEMENT (SPEC)

When necessary, pad the list SPEC with nil elements such that its length becomes 3.

%LOCATION-ERROR-DOCUMENT-STRING (CONDITION)

Return a serialization of the XML document associated with CONDITION.

%MAKE-LOCATION-AND-PLACE-FORMS (DOCUMENT BINDINGS &KEY GLOBAL-ARGS WRITABLE?)

Generate location and place forms for DOCUMENT and BINDINGS. When WRITABLE? is non-nil, locations are created in the document if necessary. Return two values: + A list of location forms + A list of place forms

%MAKE-LOCATION-FORM (DOCUMENT PATH ARGS)

Make a form that creates the `location' instance for DOCUMENT, PATH and ARGS. Return two values: + a symbol for the variable that will hold the location instance + a form that should be evaluated to compute the location instance or nil, if a location variable emitted earlier can be reused.

%MAYBE-ADD-DEFAULT-NAMESPACES (NAMESPACES)

Add default namespaces as defined by `xpath::*dynamic-namespaces*' to NAMESPACES.

%PARSE-BINDINGS-AND-OPTIONS (BINDINGS-AND-OPTIONS)

Separate BINDINGS-AND-OPTIONS into binding forms and options. Return two values: the collected binding forms and a plist containing the collected options.

CLEAR-LOCATION-CLASSES!

Clear all previously defined dynamic classes.

Undocumented

%PARSE-LIST-OF-ATOMS (STRING)

%SIGNAL-NO-SUCH-ACCESSOR-FORM (SPEC ARGS)

%SPLIT-AT-WHITESPACE (STRING)

MACRO

Public

WITH-LOCATIONS ((&REST BINDINGS-AND-OPTIONS) DOCUMENT &BODY BODY)

Execute body with certain variables, specified by BINDINGS bound to locations in DOCUMENT. DOCUMENT has to be of type `stp:document'. BINDINGS-AND-OPTIONS specifies let-like (generalized) variable bindings according to the following syntax: BINDINGS ::= (BINDING* OPTION*) BINDING ::= (VAR-SPEC XPATH [ARG*]) VAR-SPEC ::= NAME-SPEC | VAL-SPEC | @-SPEC | LOC-SPEC NAME-SPEC ::= (:name SYMBOL [:prefix? BOOL]) VAL-SPEC ::= SYMBOL | (:val SYMBOL [:type TYPE]) @-SPEC ::= (:@ @-NAME [:type TYPE]) @-NAME ::= SYMBOL | (SYMBOL "STRING") LOC-SPEC ::= (:loc SYMBOL) OPTION ::= KEY VALUE In all cases, SYMBOL is the name of the generalized variable that is created by the binding. If the (SYMBOL "STRING") form of @-NAME is used, STRING specifies the name of the attribute independently of the variable name, otherwise the name of attribute is computed as (string SYMBOL). Instead of the keywords :name, :val and :@ symbols of the same name in the xml.location package can be used. Example: XLOC> (xloc:with-locations-r/o (((:@ (description-brief "brief")) "package/description") (description-long "package/description/text()") (author "package/author/text()") (dependencies "package/depend/@package" :if-multiple-matches :all) (build-dependencies "package/rosbuild2/depend/@package" :if-multiple-matches :all) ((:val messages :type 'list) "package/rosbuild2/msgs/text()") ((:val services :type 'list) "package/rosbuild2/srvs/text()")) doc (values author messages)) => "Joe User" '("msg/bla.msg")

WITH-LOCATIONS-R/O ((&REST BINDINGS-AND-OPTIONS) DOCUMENT &BODY BODY)

Like `with-locations', but binding places are not `setf'-able.

Private

DEFINE-DYNAMIC-CLASS-FAMILY (NAME &REST DOC-AND-OPTIONS)

Define a family of classes in the category NAME. Classes in the family are fully specified by their respective sets of superclasses. No further structure is added. For a family named NAME, the following things are defined: + *NAME-classes* [variable] + make-NAME-class [generic function] + make-NAME-class list [method] + ensure-NAME-class [function] + NAME-classes [function] Unless the :package option is supplied, all names will be interned in NAME's package. Using the :package option, a different package can be specified. When supplied, the value of the :package option is evaluated. Valid options and their respective defaults are: + package [(package-name (symbol-package name))] The package in which defined variables and functions will be placed. + metaclass ['standard-class] The metaclass that should be used for classes in the family. + common-superclasses [nil] A list of superclasses that should be added to all classes in the family. List elements can either be classes or lists of the form (PLACEMENT CLASS) where PLACEMENT is either :start or :end and CLASS is a class. PLACEMENT controls where a superclass is inserted into the list of superclasses. The default placement is :end. + sort-mixins? [nil] If non-nil, the list of mixin classes is sorted (according to their `class-name's as strings) prior to looking for or creating a dynamic class. Generated documentation is available for the symbol NAME using type :dynamic-class-family.

GENERIC-FUNCTION

Public

->XML (VALUE DEST TYPE &KEY INNER-TYPES &ALLOW-OTHER-KEYS)

Convert VALUE to a suitable type and store the result of the conversion in the XML node DEST. Should return VALUE.

@ (LOCATION NAME &KEY TYPE (TYPE 'STRING) &ALLOW-OTHER-KEYS)

Return the value of the attribute named NAME of the node represented by LOCATION. If TYPE is supplied, a type conversion may be performed. LOCATION has to represent an element node. If NAME is a qualified name of the form PREFIX:LOCAL-NAME, LOCATION has to contain an entry for PREFIX in its namespace table.

SETF@ (NEW-VALUE LOCATION NAME &KEY TYPE (TYPE 'STRING) &ALLOW-OTHER-KEYS)

Set NEW-VALUE as the value of the attribute named NAME of the node represented by LOCATION. If TYPE is supplied, a type conversion may be performed prior to assigning the value. LOCATION has to represent an element node. If NAME is a qualified name of the form PREFIX:LOCAL-NAME, LOCATION has to contain an entry for PREFIX in its namespace table.

LOC (DOCUMENT PATH &REST ARGS &KEY NAMESPACES IF-NO-MATCH IF-MULTIPLE-MATCHES ASSIGN-MODE (IF-MULTIPLE-MATCHES ERROR) (IF-NO-MATCH ERROR) (ASSIGN-MODE REPLACE) &ALLOW-OTHER-KEYS)

Construct and return a new location object that represents the nodes resulting from applying the XPath PATH to the XML document DOCUMENT. ARGS are passed to the `make-instance' call that creates a `location' instance. NAMESPACES can be an alist of the form ((PREFIX . NAMESPACE)*) that specifies XML namespaces that should be made available in PATH. IF-NO-MATCH specifies the policy for dealing with the situation that the node set produced by evaluating PATH on DOCUMENT is empty. Valid values: :error (the default) Signal an `empty-result-set' error. :create Try to create a location which matches PATH in DOCUMENT, then return the created location. :do-nothing. Return a location object that does not have an associated location in document. IF-MULTIPLE-MATCHES specifies the policy for dealing with the situation that the node set produced by evaluating PATH on DOCUMENT consists of multiple nodes. Valid values are: :error (the default) Signal a `too-many-matches-in-result-set' error. :first Return a location object corresponding to the first location in DOCUMENT which matches PATH. :any Return a location object corresponding to an arbitrary location in DOCUMENT which matches PATH. :last. Return a location object corresponding to the last location in DOCUMENT which matches PATH. :all Return a location object corresponding to the set of matching locations. Operations on the location object affect all locations simultaneously. ASSIGN-MODE specifies the semantics of assigning values to `val' places of the location: :set An assigned value replaces the previous value. :append Subsequently assigned values are stored in newly appended sibling locations. The type of the returned `location' instance can depend on the arguments but is a sub-type of `location'.

MAKE-LOCATION-CLASS (MIXINS)

Dynamically make a class composed of MIXINS.

NAME (LOCATION &KEY PREFIX? &ALLOW-OTHER-KEYS)

Return the name of the node represented by LOCATION. If PREFIX? is non-nil, the concatenation of the prefix and the local name is returned.

SETFNAME (NEW-VALUE LOCATION)

Set NEW-VALUE as the local name of the node represented by LOCATION. If NEW-VALUE is a qualified name of the form PREFIX:LOCAL-NAME, LOCATION has to have an entry for PREFIX in its namespace table.

VAL (LOCATION &KEY TYPE (TYPE 'STRING) &ALLOW-OTHER-KEYS)

Return the value of the node represented by LOCATION. If TYPE is supplied, a type conversion may be performed. When LOCATION represents an element node, TYPE has to be supplied. For attribute and text nodes, the text value is returned in that case.

SETFVAL (NEW-VALUE LOCATION &KEY TYPE (TYPE ANY) &ALLOW-OTHER-KEYS)

Set NEW-VALUE as the value of the node represented by LOCATION. If TYPE is supplied, a type conversion may be performed prior to assigning the value. When LOCATION represents an element node, TYPE has to be supplied. For attribute and text nodes, NEW-VALUE has to be a string in that case.

XML-> (VALUE TYPE &KEY INNER-TYPES &ALLOW-OTHER-KEYS)

Convert VALUE to the type designated by TYPE and, possibly INNER-TYPES. The result of the conversion is returned.

Undocumented

CONVERSION-ERROR-DESTINATION (CONDITION)

CONVERSION-ERROR-FUNCTION (CONDITION)

CONVERSION-ERROR-TYPE (CONDITION)

CONVERSION-ERROR-VALUE (CONDITION)

INVALID-BINDING-FORM-FORM (CONDITION)

INVALID-BINDING-FORM-NAME (CONDITION)

INVALID-BINDING-FORM-SPEC (CONDITION)

LOCATION-ERROR-DOCUMENT (CONDITION)

LOCATION-ERROR-PATH (CONDITION)

RESULT-CONDITION-RESULT (CONDITION)

XPATH-CREATION-ERROR-LOCATION (CONDITION)

XPATH-CREATION-ERROR-NAME (CONDITION)

XPATH-CREATION-ERROR-PREDICATE (CONDITION)

XPATH-CREATION-ERROR-TYPE (CONDITION)

Private

COMPILE! (LOCATION)

Compile XPath associated to LOCATION.

CREATE-XPATH (DOCUMENT PATH)

Ensure that the nodes referenced in PATH actually exist in DOCUMENT, creating them if necessary.

CREATE-XPATH-ELEMENT (LOCATION TYPE NAME PREDICATE &REST PREDICATES)

Create the XPath element designated by TYPE, NAME and PREDICATE in LOCATION.

CREATE-XPATH-SIBLING (DOCUMENT PATH)

Create a "sibling" path of PATH by duplicating the node designated by PATH and appending the result to the children of the parent of the node designated by PATH.

EVALUATE! (LOCATION)

Evaluate XPath associated to LOCATION on the document associated to LOCATION.

LOCATION-ATTRIBUTE (LOCATION NAME &KEY (URI ) &ALLOW-OTHER-KEYS)

Return the attribute(s) designated by NAME in LOCATION.

MAYBE-DECODE-QNAME (LOCATION NAME)

If NAME is qualified, decode it into local-name prefix and uri using the configured namespaces of LOCATION. Return the components as multiple value. If NAME is not qualified, the secondary and tertiary values are both nil.

Undocumented

%PARSE-ACCESS-SPEC (SPEC &REST ARGS &KEY INNER-SPECS LOCATION-VAR &ALLOW-OTHER-KEYS)

LOCATION-ERROR-EXPECTED (CONDITION)

SLOT-ACCESSOR

Public

LOCATION-DOCUMENT (LOCATION)

The Return the document (an stp:node instance) associated to LOCATION.

SETFLOCATION-DOCUMENT (NEW-VALUE LOCATION)

The Set NEW-VALUE as LOCATION's associated document. NEW-VALUE has to be an stp:node instance.

LOCATION-NAMESPACES (OBJECT)

An alist of namespaces that should be available in the XPath of the location.

SETFLOCATION-NAMESPACES (NEW-VALUE OBJECT)

Reset computed result of LOCATION when namespaces are changed.

LOCATION-PATH (LOCATION)

The Return the XPath of LOCATION.

SETFLOCATION-PATH (NEW-VALUE LOCATION)

The Set NEW-VALUE as LOCATION's associated XPath. NEW-VALUE has to be a string.

LOCATION-RESULT (LOCATION)

The Return the node or node set that has been produced by evaluating LOCATION's associated XPath on LOCATION's associated document.

Private

LOCATION-COMPILED-PATH (OBJECT)

Compiled version of the XPath of the location.

SETFLOCATION-COMPILED-PATH (NEW-VALUE OBJECT)

Reset computed result of LOCATION when the compiled path is changed.

LOCATION-IF-MULTIPLE-MATCHES (OBJECT)

Policy for the situation that the XPath evaluates to a node set that consists of more than one nodes.

VARIABLE

Public

*CL-NAMESPACES*

Namespace list with a made-up Common Lisp namespace. This namespace should be used when Common Lisp-specific data has to be stored in XML documents in order to represent objects without loss of information.

Private

*LOCATION-CLASSES*

Association of lists of mixins to previously created classes.

CLASS

Public

APPEND-NODES-MIXIN

This mixin changes the default replacing assignment behavior to an appending assignment behavior. That is, assignments to the `val' place of locations create siblings of the node designated by the final XPath component and assign values to these new nodes.

CREATE-MISSING-NODES-MIXIN

This class adds the automatic creation of XML nodes that are references in the path but missing in the document to location classes.

LOCATION

A location consists of an XML document and an XPath that refers to nodes in the document. Technically the location uses the node set resulting from evaluating the XPath on the document as a concrete representation of this relation. Operation on the location are carried out on the node or nodes of the node set.

MULTI-LOCATION

Instances of this class represent and operate on a set of XPath matches in a single document simultaneously.

SINGLETON-LOCATION

This location class consists of an XML document along with an XPath that produces exactly one match in the document.

Private

IGNORE-EMPTY-RESULT-MIXIN

This mixin class adds the behavior of turning the methods `name', `val' and `@' (and their `setf' variants) into no-ops if the result set is empty.

CONDITION

Public

->XML-CONVERSION-ERROR (VALUE TYPE DESTINATION &OPTIONAL FORMAT-CONTROL &REST FORMAT-ARGUMENTS)

This error is signaled when storing a value into an XML location with a certain type fails.

CONVERSION-ERROR

This error is signaled when a conversion fails.

EMPTY-RESULT-SET

This error is signaled when an XPath evaluation produces an empty result in a context that requires a non-empty result set.

INVALID-BINDING-FORM

This error is signaled when an invalid binding form is encountered during expansion of the `with-locations' macro.

INVALID-RESULT-TYPE

This error is signaled when an XPath evaluation produces a result which is not of the correct type for the context in which it occurs.

LOCATION-ERROR

This condition class can be used to discriminate location-related errors.

MISSING-XPATH-SOURCE

This condition is signaled when recompilation of an XPath would be required but the XPath source is not available. This can happen, for example, when the namespace table of a location is changed.

NO-->XML-CONVERSION-METHOD

This error is signaled when no method is available to store a value into an XML location with a certain type.

NO-CONVERSION-METHOD-MIXIN

This condition class can be mixed into condition classes that indicate a conversion failure because of a missing conversion method.

NO-SUCH-ACCESSOR-FORM

This error is signaled if a binding form is encountered within a use of in the `with-locations' macro which contains an unknown accessor.

NO-XML->-CONVERSION-METHOD

This error is signaled when no method is available to convert an XML location into a Lisp object with a certain type.

RESULT-CONDITION

Subclasses of this condition are signaled when an XPath evaluation produces a result that is invalid in the a particular context.

TOO-MANY-MATCHES-IN-RESULT-SET

This error is signaled when an XPath evaluation produces a result set that consists of multiple elements in a context that permits at most one element.

XML->-CONVERSION-ERROR (VALUE TYPE &OPTIONAL FORMAT-CONTROL &REST FORMAT-ARGUMENTS)

This error is signaled when converting an XML location into a Lisp object with a certain type fails.

XPATH-CREATION-ERROR

This error is signaled when the creation of a node based on a XPath fragment fails.