xml.location

API Reference

xml.location

This system provides a convenient interface for manipulating XML data. It is inspired by the xmltio library.

XML.LOCATION.COMPAT

Internal compatibility package.
  • Macro 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.

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 `@'.
  • Condition LOCATION-ERROR  (ERROR)
    This condition class can be used to discriminate location-related errors.
  • Condition MISSING-XPATH-SOURCE  (ERROR)
    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.
  • Condition RESULT-CONDITION  (CONDITION)
    Subclasses of this condition are signaled when an XPath evaluation produces a result that is invalid in the a particular context.
  • Condition INVALID-RESULT-TYPE  (LOCATION-ERROR, RESULT-CONDITION)
    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.
  • Condition EMPTY-RESULT-SET  (LOCATION-ERROR, RESULT-CONDITION)
    This error is signaled when an XPath evaluation produces an empty result in a context that requires a non-empty result set.
  • Condition TOO-MANY-MATCHES-IN-RESULT-SET  (LOCATION-ERROR, RESULT-CONDITION)
    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.
  • Condition INVALID-BINDING-FORM  (ERROR)
    This error is signaled when an invalid binding form is encountered during expansion of the `with-locations' macro.
  • Condition NO-SUCH-ACCESSOR-FORM  (INVALID-BINDING-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.
  • Condition XPATH-CREATION-ERROR  (SIMPLE-ERROR)
    This error is signaled when the creation of a node based on a XPath fragment fails.
  • Condition CONVERSION-ERROR  (SIMPLE-ERROR)
    This error is signaled when a conversion fails.
  • Condition NO-CONVERSION-METHOD-MIXIN  (CONDITION)
    This condition class can be mixed into condition classes that indicate a conversion failure because of a missing conversion method.
  • Condition XML->-CONVERSION-ERROR  (CONVERSION-ERROR)
    This error is signaled when converting an XML location into a Lisp object with a certain type fails.
  • Function 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.
  • Condition NO-XML->-CONVERSION-METHOD  (XML->-CONVERSION-ERROR, NO-CONVERSION-METHOD-MIXIN)
    This error is signaled when no method is available to convert an XML location into a Lisp object with a certain type.
  • Condition ->XML-CONVERSION-ERROR  (CONVERSION-ERROR)
    This error is signaled when storing a value into an XML location with a certain type fails.
  • Function ->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.
  • Condition NO-->XML-CONVERSION-METHOD  (->XML-CONVERSION-ERROR, NO-CONVERSION-METHOD-MIXIN)
    This error is signaled when no method is available to store a value into an XML location with a certain type.
  • Variable *CL-NAMESPACES*
    '(xml.location:&default ("cl" . "http://common-lisp.net"))
    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.
  • Generic-Function LOCATION-DOCUMENT (location)
    Return the document (an stp:node instance) associated to LOCATION.
  • Generic-Function (setf LOCATION-DOCUMENT) (new-value location)
    Set NEW-VALUE as LOCATION's associated document. NEW-VALUE has to be an stp:node instance.
  • Generic-Function LOCATION-PATH (location)
    Return the XPath of LOCATION.
  • Generic-Function (setf LOCATION-PATH) (new-value location)
    Set NEW-VALUE as LOCATION's associated XPath. NEW-VALUE has to be a string.
  • Generic-Function LOCATION-RESULT (location)
    Return the node or node set that has been produced by evaluating LOCATION's associated XPath on LOCATION's associated document.
  • Generic-Function NAME (location &key prefix?)
    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.
  • Generic-Function (setf NAME) (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.
  • Generic-Function VAL (location &key type)
    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.
  • Generic-Function (setf VAL) (new-value location &key type)
    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.
  • Generic-Function @ (location name &key type)
    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.
  • Generic-Function (setf @) (new-value location name &key type)
    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.
  • Generic-Function MAKE-LOCATION-CLASS (mixins)
    Dynamically make a class composed of MIXINS.
  • Method MAKE-LOCATION-CLASS ((mixins list))
  • Method MAKE-LOCATION-CLASS ((mixins list))
  • Method MAKE-LOCATION-CLASS ((mixins list))
  • Function ENSURE-LOCATION-CLASS (mixins)
    Find or make the dynamic class composed of MIXINS.
  • Function LOCATION-CLASSES
    Return list of all classes in the family.
  • Generic-Function LOC (document path &rest args &key namespaces if-no-match if-multiple-matches assign-mode &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'.
  • Generic-Function XML-> (value type &key inner-types)
    Convert VALUE to the type designated by TYPE and, possibly INNER-TYPES. The result of the conversion is returned.
  • Generic-Function ->XML (value dest type &key inner-types)
    Convert VALUE to a suitable type and store the result of the conversion in the XML node DEST. Should return VALUE.
  • Method XML-> ((value t) (type t) &key inner-types)
  • Method ->XML ((value t) (dest t) (type t) &key inner-types)
  • Generic-Function CREATE-XPATH (document path)
    Ensure that the nodes referenced in PATH actually exist in DOCUMENT, creating them if necessary.
  • Method CREATE-XPATH ((document node) (path string))
  • Method CREATE-XPATH ((document node) (path list))
  • Class 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.
    DOCUMENT   Accessor: LOCATION-DOCUMENT
    The XML document to which the location refers.
    NAMESPACES   Accessor: LOCATION-NAMESPACES
    An alist of namespaces that should be available in the XPath of the location.
    PATH   Accessor: LOCATION-PATH
    An XPath that selects nodes in the document of the location.
    COMPILED-PATH   Accessor: LOCATION-COMPILED-PATH
    Compiled version of the XPath of the location.
    RESULT   Reader: LOCATION-RESULT
    The node-set produced by evaluating the XPath of the location to the document of the location.
  • Method (setf LOCATION-DOCUMENT) ((new-value t) (location location))
    Reset computed result of LOCATION when the document is changed.
  • Method (setf LOCATION-NAMESPACES) ((new-value t) (location location))
    Reset computed result of LOCATION when namespaces are changed.
  • Method (setf LOCATION-PATH) ((new-value t) (location location))
    Reset computed result of LOCATION when the path is changed.
  • Method (setf NAME) ((new-value string) (location location))
    Determine whether NEW-VALUE is qualified and call and appropriate next method.
  • Class SINGLETON-LOCATION  (LOCATION)
    This location class consists of an XML document along with an XPath that produces exactly one match in the document.
    IF-NO-MATCH
    Policy for the situation that the XPath evaluates to an empty node set.
    IF-MULTIPLE-MATCHES   Reader: LOCATION-IF-MULTIPLE-MATCHES
    Policy for the situation that the XPath evaluates to a node set that consists of more than one nodes.
  • Method NAME ((location singleton-location) &key prefix?)
  • Method (setf NAME) ((new-value string) (location singleton-location))
  • Method VAL ((location singleton-location) &key (type 'string))
  • Method (setf VAL) ((new-value t) (location singleton-location) &key (type :any))
  • Method @ ((location singleton-location) (name string) &key (type 'string))
  • Method (setf @) ((new-value t) (location singleton-location) (name string) &key (type 'string))
  • Method LOC ((location singleton-location) (path t) &rest args &key &allow-other-keys)
  • Class MULTI-LOCATION  (LOCATION)
    Instances of this class represent and operate on a set of XPath matches in a single document simultaneously.
    No slots.
  • Method NAME ((location multi-location) &key prefix?)
  • Method VAL ((location multi-location) &key (type 'string))
  • Method (setf VAL) ((new-value t) (location multi-location) &key (type :any))
  • Method (setf VAL) ((new-value list) (location multi-location) &key (type :any))
  • Method @ ((location multi-location) (name string) &key (type 'string))
  • Method (setf @) ((new-value t) (location multi-location) (name string) &key (type 'string))
  • Method LOC ((location multi-location) (path t) &rest args &key &allow-other-keys)
  • Method NAME ((location ignore-empty-result-mixin) &key &allow-other-keys)
  • Method (setf NAME) ((new-value t) (location ignore-empty-result-mixin))
  • Method VAL ((location ignore-empty-result-mixin) &key &allow-other-keys)
  • Method (setf VAL) ((new-value t) (location ignore-empty-result-mixin) &key &allow-other-keys)
  • Method @ ((location ignore-empty-result-mixin) (name t) &key &allow-other-keys)
  • Method (setf @) ((new-value t) (location ignore-empty-result-mixin) (name t) &key &allow-other-keys)
  • Class 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.
    No slots.
  • Class 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.
    No slots.
  • Method (setf VAL) ((new-value t) (location append-nodes-mixin) &key &allow-other-keys)
    Sibling creation invalidates our previous XPath evaluation result, so we have to re-evaluate.
  • Method XML-> ((value t) (type list) &key &allow-other-keys)
    Intended mainly to catch the case in which TYPE is nil.
  • Method XML-> ((value t) (type list) &key &allow-other-keys)
    Split composite type specification TYPE into head and tail.
  • Method XML-> ((value document) (type t) &rest args &key &allow-other-keys)
  • Method XML-> ((value text) (type t) &rest args &key &allow-other-keys)
    Extract text from text node VALUE for further conversion.
  • Method XML-> ((value text) (type (eql 'string)) &key &allow-other-keys)
    Fast-path method for text nodes if TYPE is string.
  • Method XML-> ((value attribute) (type t) &rest args &key &allow-other-keys)
    Extract attribute value from VALUE for further conversion.
  • Method XML-> ((value attribute) (type (eql 'string)) &key &allow-other-keys)
    Fast-path method for attribute nodes if TYPE is string.
  • Method XML-> ((value node) (type (eql 'string)) &key &allow-other-keys)
    Catch-all method for STP nodes that have no obvious string interpretation.
  • Method XML-> ((value string) (type t) &key &allow-other-keys)
    Convert intermediate string VALUE to requested type TYPE.
  • Method XML-> ((value string) (type (eql 'string)) &key &allow-other-keys)
    Fast-path method for string VALUE.
  • Method XML-> ((value string) (type (eql 'list)) &key (inner-types '(string) inner-types-supplied?))
    Convert intermediate string VALUE to requested list type TYPE.
  • Method XML-> ((value string) (type (eql 'type)) &key &allow-other-keys)
    Convert string VALUE to a Common Lisp type.
  • Method XML-> ((value node) (type class) &key &allow-other-keys)
    Interpret TYPE as a class name. Try to create an instance and load the contents of VALUE into that instance.
  • Method XML-> ((value node) (type symbol) &key &allow-other-keys)
    Interpret TYPE as a class name. Try to create an instance and load the contents of VALUE into that instance.
  • Method ->XML ((value t) (dest t) (type list) &key &allow-other-keys)
    Intended mainly to catch the case in which TYPE is nil.
  • Method ->XML ((value t) (dest t) (type list) &key &allow-other-keys)
    Split composite type specification TYPE into head and tail.
  • Method ->XML ((value t) (dest document) (type t) &rest args &key &allow-other-keys)
    Convert VALUE to string and store in DEST.
  • Method ->XML ((value t) (dest text) (type t) &key inner-types &allow-other-keys)
    Convert VALUE to string and store in DEST.
  • Method ->XML ((value string) (dest text) (type t) &key &allow-other-keys)
    Fast-path method for storing string VALUE into text node DEST.
  • Method ->XML ((value t) (dest attribute) (type t) &key &allow-other-keys)
    Convert VALUE to string and store in DEST.
  • Method ->XML ((value string) (dest attribute) (type t) &key &allow-other-keys)
    Fast-path method for storing string VALUE into text node DEST.
  • Method ->XML ((value string) (dest node) (type (eql 'string)) &key &allow-other-keys)
    Catch-all for STP nodes that do not have an obvious string interpretation.
  • Method ->XML ((value t) (dest (eql 'string)) (type t) &key &allow-other-keys)
    Convert VALUE to requested type string by `prin1'ing it.
  • Method ->XML ((value string) (dest (eql 'string)) (type t) &key &allow-other-keys)
    Fast-path method for string VALUE.
  • Method ->XML ((value sequence) (dest (eql 'string)) (type t) &key inner-types &allow-other-keys)
    Convert sequence VALUE to string by `format'ting.
  • Method ->XML ((value list) (dest (eql 'string)) (type (eql 'type)) &key &allow-other-keys)
    Convert VALUE to string by `prin1'ing it.
  • Method LOC ((document node) (path string) &rest args &key (if-multiple-matches :error) (if-no-match :error) (assign-mode :replace) &allow-other-keys)
    Create a location for DOCUMENT and PATH. The class of the location instance is determined based on the values of IF-MULTIPLE-MATCHES and IF-NO-MATCH.
  • Method LOC ((document string) (path t) &rest args)
    Parse DOCUMENT as XML document before constructing the location.
  • Method LOC ((document t) (path function) &rest args)
    Interpret PATH as compiled XPath, skipping the compilation step.
  • Macro 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")
  • Macro WITH-LOCATIONS-R/O ((&rest bindings-and-options) document &body body)
    Like `with-locations', but binding places are not `setf'-able.

xml.location-and-local-time

To and from XML conversion for local-time timestamps.

No packages.