The API in this module supports a standard tree-oriented view of an
XML document. The object representation consumes more memory than
the more Lisp-like LXML representation, but the accessors are more
specific and allow a programming style very similar to that in other
languages that implement the DOM API.

The symbols naming objects in this module are in the
:net.xml.dom package. The DOM module is part of the SAX module,
so it is loaded when the SAX module is loaded. You can load the SAX
module (and therefore the DOM module) into Lisp by evaluating the
following form:

This DOM Level 1 implementation passes 155 key tests from the W3.org
DOM conformance test suite. The tests were translated manually from
the javascript source. More tests will be translated in the future.

The SAX parser implementation in Allegro CL (see
sax.htm) expands all entity
references. Consequently, a DOM tree created from a parse will never
contain any dom-entity-reference nodes.

We have followed the usual case-shift-to-hyphen translation of names
in the DOM spec and added the prefix dom-. For Example:

The name getElementsByTagName becomes the Lisp
symbol dom-get-elements-by-tag-name.

In addition, all the object classes have sub-classes named with a "dom1-"
prefix. Most of the methods in the API are specialized on the more abstract
"dom-" classes but the actual object instances will be instances of
the "dom1-" classes.

This implementation supports fully the "live" property of Node
objects.

This implementation supports the "live" property of NodeList and
NamedNodeMap objects that are immediate properties of Node objects.

The NodeList object returned by getElementsByTagName is not live in
the sense that if a child that meets the criteria of the search is
added to or deleted from the DOM tree, the NodeList object will not be
updated. It is not clear to us whether this behavior conforms to, or
violates the DOM spec.

For standard classes, methods and values, refer to the DOM spec (see
Section 1.0 DOM introduction for a link) for a detailed
description of the behavior. In this document we only describe any
variant or additional behavior.

For accessors described as read-only properties, the Lisp name is
only a reader method. For accessors described as properties, the
Lisp name is a reader method and a setf method.

The DOM spec uses the factory object model for the various create methods.
We implement a more Lisp-like view where the create methods may be specialized
on any dom-node instance.

The ownerDocument property of the new Node instance is copied from the
doc-or-node argument. If the doc-or-node argument is not supplied, a
node with a null ownerDocument property is created. Such a node can only
be inserted in other nodes with a null ownerDocument property.

The following extensions are added to the interface specified in
the DOM Level 1 document.

dom-parser

Class

Package: net.xml.dom

This DOM Object Class is the abstract class of all DOM parsers.

dom1-parser

Class

Package: net.xml.dom

This DOM Object Class is the class of the DOM Level 1 parser.

dom-child-node-list

Generic Function

Package: net.xml.dom

Arguments:

This generic function, an extended property of Node, retrieves the child nodes
of a dom-node instance as a simple Lisp list of nodes. This value
avoids the creation of the dom-node-list instance.

This value does not fully support the "live" nature of DOM tree
components: the nodes in the list, and the list itself, may be updated
and the changes take place in the DOM tree. But the list cannot be
updated to become empty, and an empty list cannot be augmented.

dom-create-document

Function

Package: net.xml.dom

Arguments: &key parser implementation

This generic function creates an instance of dom-document.

Normally such an instance is the result of parsing an XML document.

The implementation argument specifies the
implementation class of the of the DOM document instance. If the
implementation class is not specified, it is derived from the parser
instance.

The parser argument specifies the class of the parser that could have
been used to create the document. The default is dom1-parser.

dom-document-parser

Generic Function

Package: net.xml.dom

Arguments:

This generic function, an extended property of Document, returns the parser
object that parsed the document.

dom-dump

Generic Function

Package: net.xml.dom

Arguments:
node stream
&key depth

This generic function prints a detailed description of a DOM sub-tree on the
stream. If the depth argument is an integer, descend only to that
depth. This generic function is useful in debugging complex DOM trees.

dom-equal

Generic Function

Package: net.xml.dom

Arguments:
node1 node2
&key error-p ignore-whitespace

This generic function tests whether two nodes are equal. To be equal, element
names, values and attributes must be equal. Sub-elements must appear
in the same order, but attributes may be in any order.

When the error-p argument is non-nil, an error will be signaled at the point where the
inequality is detected. This may be a useful debugging feature when
large DOM trees must be compared.

When the ignore-whitespace argument is
non-nil, nodes consisting entirely of
whitespace are skipped, and text nodes that differ only by whitespace
characters are considered equal.

If the ignore-whitespace argument is a sequence
of characters, then only the mentioned characters are considered to be
whitespace. Otherwise the XML definition of whitespace (#\Space #\Tab
#\Newline #\Return) is used.

dom-item-name

Generic Function

Package: net.xml.dom

Arguments:
dom-named-node-map index

This generic function, an extended method of NamedNodeMap, returns the name of
the specified item in the dom-named-node-map
argument, and avoids the creation of a dom-node instance.

dom-item-value

Generic Function

Package: net.xml.dom

Arguments:
dom-named-node-map index-or-name

This generic function, an extended method of NamedNodeMap, returns the value
associated with a name or index in a
dom-named-node-map instance, and avoids the
creation of a dom-node instance.

dom-list-elements-by-tag-name

Generic Function

Package: net.xml.dom

Arguments:
dom-element-or-dom-document tag-name

This extended method on Element and Document works on
dom-elements and
dom-documents. It is like
dom-get-elements-by-tag-name, but returns a Lisp list of
nodes. This LIST IS NOT LIVE.

dom-node-type-p

Generic Function

Package: net.xml.dom

This Lisp predicate tests the DOM type of a dom-node instance. The
type-name-or-number argument may be an integer, a dom-type constant,
or one of the keywords:

:dom-element-node

:dom-attribute-node

:dom-text-node

:dom-cdata-section-node

:dom-entity-reference-node

:dom-entity-node

:dom-processing-instruction-node

:dom-comment-node

:dom-document-node

:dom-document-type-node

:dom-document-fragment-node

:dom-notation-node

dom-print

Generic Function

Package: net.xml.dom

Arguments:
node stream
&key indent attrs if-exists
&allow-other-keys

This generic function pretty prints a node to a stream. The
node argument is returned.

The allowable values for the stream argument are
as follows:

a stream: then the output is to the stream and the stream is left
open.

a string or pathname: the output is to the file specified by the
pathname or string. The stream to the file is closed after the node is
printed. The if-exists keyword argument applies
to the open of the file; the default is :supersede.

NOTE: If the DOM tree was parsed from a file with whitespace
and newlines between the elements, there will be what looks like
excess newlines and whitespace in the output of dom-print. This is
because dom-print begins elements on new lines
with a consistent indentation.

If the indent argument is specified as nil in the call, then dom-print will not attempt to
insert indentation or newlines and the output will be very similar to
the original parsed file.

parse-to-dom

Generic Function

Package: net.xml.dom

Arguments:
string-or-stream
&key validate skip-ignorable class warn

This generic function returns two values: a dom-document instance, and a
parser instance.

The keyword arguments are passed through to the SAX parser (see
sax.htm). The default for
class is dom1-parser.

file-to-dom

Generic Function

Package: net.xml.dom

Arguments:
path
&key validate skip-ignorable class warn

This generic function returns two values: a dom-document instance, and a
parser instance.

The keyword arguments are passed through to the SAX parser (see
sax.htm). The default for
class is dom1-parser.

If the object argument evaluates to a
dom-object instance, then the lock associated with
the object is used while body is evaluated. A new
lock is created the first time the lock slot of the object is
referenced.

If the object argument evaluates to any other
value, then no locking takes place.

*dom-enforce-locks*

Variable

Package: net.xml.dom

When this variable is set to true, serial access to nodes is enforced.

If the value of this variable is nil (the
initial value), then no locking is done and multiple threads accessing
one DOM tree may see inconsistent states. This value is safe and
efficient if only one thread is known to access the DOM tree.

If the value of this variable is an instance of mp:process-lock, then
this one lock is used to serialize all access operations.

If the value of this variable is any other non-nil value, then a
separate lock is created for each DOM object instance. This allows
finer-grained access but uses more memory and increases the
oportunities for deadlocks.

This variable may be bound dynanmically to control the locking
strategy.

*dom-print-attrs*

Variable

Package: net.xml.dom

This variable specifies the maximum number of attributes on one
line. The initial value is 3.

*dom-print-indent*

Variable

Package: net.xml.dom

This variable specifies the indentation for each level. Ths initial
value is 2.

dom-condition

Class

Package: net.xml.dom

This class/DOM condition is the superclass of all DOM conditions.

dom-condition-code

Generic Function

Package: net.xml.dom

Arguments:
dom-condition

This is the slot reader for the data slot. It returns the numeric
condition code defined in the DOM Level 1 spec.

dom-condition-name

Generic Function

Package: net.xml.dom

Arguments:
dom-condition

This is the slot reader for the data slot. It returns a Lisp keyword
that names the condition.

dom-condition-string

Generic Function

Package: net.xml.dom

Arguments:
dom-condition

This is the slot reader for the data slot. It returns a string or a
list of strings that describe the condition in more detail.

dom-condition-note

Generic Function

Package: net.xml.dom

Arguments:
dom-condition

This is the slot reader for the data slot. It returns a format string
that describes the specific occurrence of the condition in more
detail. The data for the string is returned by dom-condition-data.

dom-condition-data

Generic Function

Package: net.xml.dom

Arguments:
dom-condition

This is the slot reader for the data slot. It returns the list of
format arguments for the format string in dom-condition-note.