Package cxml-stp

STP is a data structure for well-formed XML documents.

About This Package

Parsing and Serializing
Names and Namespace URIs
Subclasses of Node
Creating nodes
Listing Child Nodes
Adding and Removing Child Nodes
Elements and their Attributes

Parsing and Serializing

To parse into STP, use an STP builder together with a function generating SAX events:

This function creates SAX handler that constructs an STP document. ...

Serialize STP by sending SAX events for the tree to a sink:

This function generates SAX events representing node. ...

Names and Namespace URIs

STP represents namespace-well-formed documents only. All functions accepting names take a local-name and and a namespace URI as an argument. Qualified names are accepted where it makes sense, and named nodes have a namespace prefix that is taken into account for well-formedness checks.

There are two kinds of named nodes: element and attribute. Their slots are:

Returns the node's local name. ...

Returns the node's namespace URI. ...

Returns the node's namespace prefix. ...

For element, all of the above can be changed using SETF (subject to well-formedness checks).

For attribute, local-name can be changed directly, while URI and prefix always have to be changed in the same step using rename-attribute.

A node's qualified name can be be queried:

Returns the node's qualified name. ...



of-name is convenient when searching for elements or attributes:

This function creates a test function for nodes of this name. ...

Subclasses of Node

All STP nodes have a common superclass.

The superclass of all nodes. ...

Documents and elements can have children:

Instances of this class can have children. ...

Instances of this class represent an entire XML document. ...

Instances of this class represent XML elements with their attributes and namespaces. ...

Attributes belong to an element:

Instances of this class represent attributes of an element, excluding namespace declarations. ...

Other kinds of nodes:

Instances of this class represent XML comments.

Instances of this class represent the DOCTYPE declaration at the beginning of a document. ...

Instances of this class represent processing instructions.

Instances of this class represent text nodes.

Creating nodes

Nodes are created using the following functions:

This function creates an attribute node of the given value and name. ...

This function creates a comment node. ...

This function creates document. ...

This function creates a document-type node. ...

This function creates an element node of the given name. ...

This function creates a processing instruction. ...

This function creates a text node. ...

In addition, nodes can be copied including all their children:

This function copies a node recursively. ...

Listing Child Nodes

Nodes have an optional parent node and can have children.

Returns the node's parent. ...

If a node has a document as its ancestor, it can be found using the document function.

Returns the document node ancestor of node. ...

Since the parent slot needs to be updated when children are added or removed, the sequence of children is not exposed as a mutable Common Lisp sequence.

Returns a freshly consed list containing the child nodes of node.

Applies function to successive child nodes. ...

Executes body with var bound to successive child nodes.

The following DOM-like functions are also offered:

Returns child node n of parent ...

Returns first child of node, or nil.

Returns last child of node, or nil.

Returns the child preceding node in the child list of its parent. ...

Returns the child following node in the child list of its parent. ...

A wide variety of sequence-related functions is offered that work like the Common Lisp functions of the same name, but without the need to call list-children first:

Searches for a child node of parent that satisfies the test and returns it.


Searches for a child node of parent that satisfies predicate and returns it.


Searches for a child node of parent that satisfies the test and returns its position.


Searches for a child node of parent that satisfies the test and returns its position.


Counts (and returns the number of) parent's child nodes satisfying the test.

Counts (and returns the number of) parent's child nodes satisfying predicate.

Return a list of child nodes of parent from which nodes that do not satisfy predicate have been removed. ...

The functions listed above walk only across the direct children of the parent node. In addition, the node hierarchy can be mapped recursively using these functions:

Applies fn to successive descendants of node in pre-order.

Executes bode with var bound to successive descendants of node in pre-order.

Searches in pre-order for the first descendant of node that satisfies the test and returns it.


Return a list of descendant nodes of node in pre-order, from which nodes that do not satisfy predicate have been removed.



Adding and Removing Child Nodes

While all nodes can be asked for their children, only documents and elements permit actually adding children. (For all other nodes, the sequence of children appears as empty.)

The most flexible function capable of changing the child nodes is replace-children. Perhaps more common is insert-child, a specialized version for only one new child.

Adds child as a child node of parent at position position if allowed. ...

Various convenience functions are offered in addition:

Adds child as the first child of parent, if allowed. ...

Adds child as the last child of parent, if allowed.

Signals an error if the child already has a parent.

Searches for a child node of parent that satisfies the test and removes it, if allowed.

Searches for an child node of parent that satisfies predicate and removes it, if allowed.

Removes child idx of parent, if allowed.

Adds new-child before ref-child as a child node of parent, if allowed. ...

Adds new-child after ref-child as a child node of parent, if allowed. ...

Adds new-child instead of old-child as a child node of parent, if allowed. ...

A node can also be deleted from its parent directly using detach.

This function removes a child node or attribute. ...

detach also works for attributes.

Elements and their Attributes

In addition to their children, elements have attributes and "extra namespaces".

Attributes themselves are nodes and be accessed using these functions:

Add a new attribute to element or replace an existing attribute node of the same name. ...

Remove an attribute node from element. ...

Searches for an attribute node of element with the specified local name and namespace URI and returns it. ...

Searches for an attribute node of element satisfying test ...

Returns a freshly consed list containing the attributes of element.

Applies fn to each attribute nodes of element. ...

Evaluate body with the specified attributes bound lexically as if they were variables.

Each entry in entries is a list of the form (variable-name attribute-name &optional uri), where variable-name is a symbol and attribute-name and uri are strings.

The macro with-attributes invokes attribute-value to access the attributes. specified by each entry. Both setf and setq can be used to set the value of the attribute.

As a shortcut, the attribute-value and its setf function allow access to attribute values by name, without having to look up the attribute node first:

Searches for an attribute node of element with the specified local name and namespace URI and returns its value. ...

There are three ways to declare a namespace: Using the name of the element, using the name of one of its attributes, or using an "extra namespace". A prefix can be looked up from any of these local declarations. It is also possible to look up a namespace while taking into account all declarations on parent elements.

Find the namespace prefix declared on element and return its namespace URI, or return nil if no such namespace was found. ...

Find the namespace prefix declared on element or its parent and return its namespace URI, or return nil if no such namespace was found. ...

Extra namespaces are needed only when a namespace must be declared even though there is no element or attribute referencing it through its name. For example, an attribute declared with type QName using RelaxNG/XSD must reference a namespace in scope.

Add an extra namespace to element that maps prefix to uri. ...

Removed the extra namespace declared on element for prefix.

Find the extra namespace named prefix declared on element and return its namespace URI, or return nil if no such namespace was found.

Call fn for each extra namespace declared on element with namespace prefix and URI as arguments.

Exported Symbol Index

*check-uri-syntax*, variable
add-attribute, function
add-extra-namespace, function
append-child, function
attribute, class
attribute-value, function
base-uri, function
child-position, function
child-position-if, function
comment, class
copy, function
count-children, function
count-children-if, function
data, function
delete-child, function
delete-child-if, function
delete-children, function
delete-nth-child, function
detach, function
do-children, macro
do-recursively, macro
document, function
document, class
document-element, function
document-type, function
document-type, class
dtd, function  (undocumented)
element, class
filter-children, function
filter-recursively, function
find-attribute-if, function
find-attribute-named, function
find-child, function
find-child-if, function
find-extra-namespace, function
find-local-namespace, function
find-namespace, function
find-recursively, function
find-recursively-if, function
first-child, function
insert-child, function
insert-child-after, function
insert-child-before, function
internal-subset, function
last-child, function
list-attributes, function
list-children, function
local-name, function
make-attribute, function
make-builder, function
make-comment, function
make-document, function
make-document-type, function
make-element, function
make-processing-instruction, function
make-text, function
map-attributes, function
map-children, function
map-extra-namespaces, function
map-recursively, function
namespace-prefix, function
namespace-uri, function
next-sibling, function
node, class
nth-child, function
number-of-children, function
of-name, function
parent, function
parent-node, class
prepend-child, function
previous-sibling, function
processing-instruction, class
public-id, function
qualified-name, function
remove-attribute, function
remove-extra-namespace, function
rename-attribute, function
replace-child, function
root, function
root-element-name, function
serialize, function
stp-error, class
string-value, function
system-id, function
target, function
text, class
value, function
with-attributes, macro