The DOM implementation

CXML implements the DOM Level 2 Core interfaces. For details on DOM, please refer to the specification.

Parsing into DOM

To parse an XML document into a DOM tree, use the SAX parser with a DOM builder as the SAX handler. Example:

(cxml:parse-file "test.xml" (dom:make-dom-builder))

Function DOM:MAKE-DOM-BUILDER ()

Create a SAX handler which builds a DOM document.

Serializing DOM

The technique used to serialize a DOM document is to use a SAX serialization sink as the argument to dom:map-document, which generates SAX events for the DOM tree.

In addition, there are convenience functions like unparse-document as a thin wrapper around map-document.

Function DOM:MAP-DOCUMENT (handler document &key include-xmlns-attributes include-default-values include-doctype)

Traverse a DOM document and call SAX functions as if an XML representation of the document was processed by a SAX parser.

Keyword arguments:

include-xmlns-attributes -- defaults to sax:*include-xmlns-attributes*
include-doctype -- One of nil (no doctype declaration), :full-internal-subset (include a doctype declaration and the full internal subset), or :canonical-notations (write a doctype declaration with an internal subset including only notations, as required for canonical serialization).
include-default-values -- include attribute nodes with nil dom:specified.

Function CXML:UNPARSE-DOCUMENT (document stream &rest keys)

Function CXML:UNPARSE-DOCUMENT-TO-OCTETS (document &rest keys) => vector

Serialize a DOM document object. These convenience functions are wrappers around dom:map-document.

Keyword arguments are passed on to the sink. C.f. cxml:make-octet-vector-sink.

Notes:

If keyword argument canonical is specified as 2, a doctype declaration will be written that includes notations declared in the document.
If namespace processing is enabled (sax:*namespace-processing*), a namespace normalizer is used.

DOM/Lisp mapping

Note that there is no "standard" DOM mapping for Lisp.

DOM is specified in CORBA IDL, but it refrains from using object-oriented IDL features, allowing for a much more natural Lisp implemenation than the the ordinary IDL/Lisp mapping would. Differences between CXML's DOM and the direct IDL/Lisp mapping:

DOM function names are symbols in the DOM package (not the OP package).
DOM functions have proper required arguments, not a huge &rest lambda list.
Although most IDL interfaces are implemented as CLOS classes by CXML, the Lisp types of DOM objects is not documented and cannot be relied upon. A node's type can be determined using dom:node-type instead.
DOMString is mapped to rod, which is either an (unsigned-byte 16) array type or a string type.
The IDL/Lisp mapping maps CORBA enums to Lisp keywords. Unfortunately, the DOM IDL does not use enums. Instead, both exception types and node types are defined integer constants. CXML chooses to ignore this definition and uses keywords instead.
DOM uses StudlyCaps. Lisp programmers don't. We insert #\- before every upper case letter preceded by a lower case letter and before every upper case letter which is followed by a lower case letter, but preceded by a capital letter. This algorithms leads to the natural Lisp spelling of DOM function names.
Implementation note: DOM's NodeList does not necessarily map to a native "sequence" type. (For example, node lists are objects in Java, not arrays.) NodeList is specified to reflect changes done after a node list was created, so node lists cannot be Lisp lists. (A node list could be implemented as a CLOS object pointing to said list though.) Instead, CXML currently implements node lists as adjustable vectors. Note that code which relies on this implementation and uses Lisp sequence functions instead of sticking to dom:item and dom:length is not portable. As a compromise, you can use our extensions dom:map-node-list or dom:do-node-list, which can be implemented portably.