ToC | DocOverview | CGDoc | RelNotes | FAQ | Index | PermutedIndex
| Allegro CL version 11.0

## 1.0 DOM introduction

This module implements the full Document Object Model (DOM) Level 1 Core API. It is based on the Document Object Model (DOM) Level 1 Specification (Second Edition), Version 1.0, W3C Working Draft 29 September, 2000 (see www.w3.org/TR/2000/WD-DOM-Level-1-20000929/).

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:

    (require :sax)

### Examples

There are examples of using DOM in examples/xml/dom-code.cl (that file is downloaded with the DOM patch). See Examples using the DOM.

    ;;
    ;; copyright (c) 2004 Franz Inc, Oakland, CA

    (in-package :user)

    (eval-when (compile load eval) (require :sax))

    (defpackage :user (:use :net.xml.dom))

    ;;;
    ;;; Some programming examples using the DOM Level 1 API
    ;;;

    (defparameter *dom-ex1-data*

      ;; Sample file noDTDXMLfile.xml from domtest-ecmascript-120499.zip
      ;; at http://www.w3.org/DOM/Test/

    "<?xml version='1.0'?>
    <staff>
     <employee>
      <employeeId>EMP0001</employeeId>
      <name>Margaret Martin</name>
      <position>Accountant</position>
      <salary>56,000</salary>
      <gender>Female</gender>
      <address domestic='Yes'>1230 North Ave. Dallas, Texas 98551</address>
     </employee>
     </staff>

    "
    )

    (defun dom-ex1 ()

      ;; Parse an XML document and walk the resulting DOM tree

      (let* ((doc (parse-to-dom *dom-ex1-data*))
         (root (dom-document-element doc))
        )
        (format t "~%The root element is ~A~%" (dom-tag-name root))

        (dolist (c (dom-child-node-list root))
          (format t "~&  Child node: ~S~%" c))

        (let* ((addr (dom-list-elements-by-tag-name root "address"))
           (attrs (dom-attributes (first addr))))
          (format t "~&  The address element has ~S attributes~%"
                  (dom-length attrs)))

        doc))

    (defun dom-ex2 (&optional (file t))

      ;; Build a DOM tree from parts and print the result

      (let ((doc (dom-create-document))
        staff emp)
        (dom-append-child doc (setf staff (dom-create-element doc "staff")))
        (dom-append-child staff (setf emp (dom-create-element doc "employee")))

        (flet ((add (parent doc name text &aux child)
            (dom-append-child parent (setf child
                                                   (dom-create-element doc name)))
            (dom-append-child child (dom-create-text-node doc text))
            child))
          (add emp doc "employeeId" "EMP00002")
          (add emp doc "name" "Alter Ego")
          (add emp doc "position" "Auditor")
          (add emp doc "salary" "65,000")
          (add emp doc "gender" "Male")
          (dom-set-attribute
           (add emp doc "address" "Port Ludlow, WA")
           "domestic" "Yes")
          )

        (dom-print doc file)

        doc))

    ;;  Here we run the functions:

    cl-user(18): (dom-ex1)

    The root element is staff
      Child node: #<dom1-text -2- @ #x10ca93fa>
      Child node: #<dom1-element employee(13) @ #x10ca95ca>
      Child node: #<dom1-text -2- @ #x10caa4da>
      The address element has 1 attributes
    #<dom1-document (1) @ #x10ca46c2>
    cl-user(19): (dom-ex2)
    <staff>
      <employee>
        <employeeId>EMP00002</employeeId>
        <name>Alter Ego</name>
        <position>Auditor</position>
        <salary>65,000</salary>
        <gender>Male</gender>
        <address domestic='Yes'>Port Ludlow, WA
        </address>
      </employee>
    </staff>
    #<dom1-document (1) @ #x11148e42>
    cl-user(20):

### 1.1 Status and conformance

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.html) expands all entity references. Consequently, a DOM tree created from a parse will never contain any dom-entity-reference nodes.

## 2.0 Naming conventions

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.

## 3.0 DOM Ref: 1.1.1. The DOM Structure Model

Objects in the DOM are 'live'.

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.

## 4.0 Standard classes, methods, values

For standard classes, methods and values, refer to the DOM spec (see 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.

### 4.1 Standard classes

Class name | Type | Notes
`dom-attr` | Dom Node Class | DOM Object: Attr
`dom-cdata-section` | Dom Node Class | DOM Object: CDATASection
`dom-character-data` | Dom Node Class | DOM Object: CharacterData
`dom-comment` | Dom Node Class | DOM Object: Comment
`dom-document` | Dom Node Class | DOM Object: Document
`dom-document-fragment` | Dom Node Class | DOM Object: DocumentFragment
`dom-document-type` | Dom Node Class | DOM Object: DocumentType
`dom-element` | Dom Node Class | DOM Object: Element
`dom-entity` | Dom Node Class | DOM Object: Entity
`dom-entity-reference` | Dom Node Class | DOM Object: EntityReference
`dom-node` | Dom Node Class | DOM Object: Node
`dom-notation` | Dom Node Class | DOM Object: Notation
`dom-processing-instruction` | Dom Node Class | DOM Object: ProcessingInstruction
`dom-text` | Dom Node Class | DOM Object: Text
`dom1-attr` | Dom Node Class | DOM Level 1 Core Object: Attr
`dom1-cdata-section` | Dom Node Class | DOM Level 1 Core Object: CDATASection
`dom1-character-data` | Dom Node Class | DOM Level 1 Core Object: CharacterData
`dom1-comment` | Dom Node Class | DOM Level 1 Core Object: Comment
`dom1-document` | Dom Node Class | DOM Level 1 Core Object: Document
`dom1-document-fragment` | Dom Node Class | DOM Level 1 Core Object: DocumentFragment
`dom1-document-type` | Dom Node Class | DOM Level 1 Core Object: DocumentType
`dom1-element` | Dom Node Class | DOM Level 1 Core Object: Element
`dom1-entity` | Dom Node Class | DOM Level 1 Core Object: Entity
`dom1-entity-reference` | Dom Node Class | DOM Level 1 Core Object: EntityReference
`dom1-node` | Dom Node Class | DOM Level 1 Core Object: Node
`dom1-notation` | Dom Node Class | DOM Level 1 Core Object: Notation
`dom1-processing-instruction` | Dom Node Class | DOM Level 1 Core Object: ProcessingInstruction
`dom1-text` | Dom Node Class | DOM Level 1 Core Object: Text
`dom-implementation` | Class Function | DOM Level 1 Core read-only property of Document: implementation is a DOMImplementation object DOM Object: DOMImplementation
`dom-named-node-map` | Dom Object Class | DOM Object: NamedNodeMap
`dom-node-list` | Dom Object Class | DOM Object: NodeList
`dom1-implementation` | Class | DOM Level 1 Core Object: DOMImplementation
`dom1-named-node-map` | Dom Object Class | DOM Level 1 Core Object: NamedNodeMap
`dom1-node-list` | Dom Object Class | DOM Level 1 Core Object: NodeList

### 4.2 Standard methods and functions

Name | Type | Notes
dom-append-child | Generic Function | DOM Level 1 Core method of Node: appendChild(newChild)
dom-append-data | Generic Function | DOM Level 1 Core method of CharacterData: appendData(arg) has no return value.
dom-attributes | Generic Function | DOM Level 1 Core read-only property of Node: attributes is a NamedNodeMap object.
dom-child-nodes | Generic Function | DOM Level 1 Core read-only property of Node: childNodes is a NodeList object.
dom-clone-node | Generic Function | DOM Level 1 Core method of Node: cloneNode(deep)
dom-create-attribute | Generic Function | DOM Level 1 Core method of Document: createAttribute(name) implemented as Generic Function: dom-create-attribute doc-or-node name 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.
dom-create-cdata-section | Generic Function | DOM Level 1 Core method of Document: createCDATASection(data) implemented as Generic Function: dom-create-cdata-section doc-or-node data
dom-create-comment | Generic Function | DOM Level 1 Core method of Document: createComment(data) implemented as Generic Function: dom-create-comment doc-or-node data
dom-create-document-fragment | Generic Function | DOM Level 1 Core method of Document: createDocumentFragment() implemented as Generic Function: dom-create-document-fragment doc-or-node
dom-create-element | Generic Function | DOM Level 1 Core method of Document: createElement(tagname) implemented as Generic Function: dom-create-element doc-or-node tag
dom-create-entity-reference | Generic Function | DOM Level 1 Core method of Document: createEntityReference(name) implemented as Generic Function: dom-create-entity-reference doc-or-node name
dom-create-processing-instruction | Generic Function | DOM Level 1 Core method of Document: createProcessingInstruction(target, data) implemented as Generic Function: dom-create-processing-instruction doc-or-node target data
dom-create-text-node | Generic Function | DOM Level 1 Core method of Document: createTextNode(data) implemented as Generic Function: dom-create-text-node doc-or-node data
dom-data | Generic Function | DOM Level 1 Core property of CharacterData: data is of type String.
dom-delete-data | Generic Function | DOM Level 1 Core method of CharacterData: deleteData(offset, count) has no return value.
dom-doctype | Generic Function | DOM Level 1 Core read-only property of Document: doctype is a DocumentType object
dom-document-element | Generic Function | DOM Level 1 Core read-only property of Document: documentElement is an Element object
dom-entities | Generic Function | DOM Level 1 Core read-only property of DocumentType: entities is a NamedNodeMap object.
dom-first-child | Generic Function | DOM Level 1 Core read-only property of Node: firstChild
dom-get-attribute | Generic Function | DOM Level 1 Core method of Element: getAttribute(name) returns a String.
dom-get-attribute-node | Generic Function | DOM Level 1 Core method of Element: getAttributeNode(name)
dom-get-elements-by-tag-name | Generic Function | DOM Level 1 Core method of Element: getElementsByTagName(tagname) returns a NodeList object. This LIST IS NOT LIVE. DOM Level 1 Core method of Document: getElementsByTagName(tagname) returns a NodeList object. This LIST IS NOT LIVE.
dom-get-named-item | Generic Function | DOM Level 1 Core method of NamedNodeMap: getNamedItem(name) returns a Node object.
dom-has-child-nodes | Generic Function | DOM Level 1 Core method of Node: hasChildNodes()
dom-has-feature | Generic Function | DOM Level 1 Core method of DOMImplementation: hasFeature(feature, version)
dom-implementation | Generic Function | DOM Level 1 Core read-only property of Document: implementation is a DOMImplementation object
dom-insert-before | Generic Function | DOM Level 1 Core method of Node: insertBefore(newChild, refChild)
dom-insert-data | Generic Function | DOM Level 1 Core method of CharacterData: insertData(offset, arg) has no return value.
dom-item | Generic Function | DOM Level 1 Core method of NamedNodeMap: item(index) returns a Node object. - DOM Level 1 Core method of NodeList: item(index) returns a Node object
dom-last-child | Generic Function | DOM Level 1 Core read-only property of Node: lastChild
dom-length | Generic Function | DOM Level 1 Core read-only property of CharacterData: length is of type Number. - DOM Level 1 Core read-only property of NamedNodeMap: length - DOM Level 1 Core read-only property of NodeList: length
dom-name | Generic Function | DOM Level 1 Core read-only property of DocumentType: name is of type String. - DOM Level 1 Core read-only property of Attr: name is of type String.
dom-next-sibling | Generic Function | DOM Level 1 Core read-only property of Node: nextSibling
dom-node-name | Generic Function | DOM Level 1 Core read-only property of Node: nodeName
dom-node-type | Generic Function | DOM Level 1 Core read-only property of Node: nodeType
dom-node-value | Generic Function | DOM Level 1 Core property of Node: nodeValue
dom-normalize | Generic Function | DOM Level 1 Core method of Element: normalize()
dom-notation-name | Generic Function | DOM Level 1 Core read-only property of Entity: notationName
dom-notations | Generic Function | DOM Level 1 Core read-only property of DocumentType: notations is a NamedNodeMap object.
dom-owner-document | Generic Function | DOM Level 1 Core read-only property of Node: ownerDocument
dom-parent-node | Generic Function | DOM Level 1 Core read-only property of Node: parentNode
dom-previous-sibling | Generic Function | DOM Level 1 Core read-only property of Node: previousSibling
dom-public-id | Generic Function | DOM Level 1 Core read-only property of Notation: publicId
dom-remove-attribute | Generic Function | DOM Level 1 Core method of Element: removeAttribute(name)
dom-remove-attribute-node | Generic Function | DOM Level 1 Core method of Element: removeAttributeNode(oldAttr)
dom-remove-child | Generic Function | DOM Level 1 Core method of Node: removeChild(oldChild)
dom-remove-named-item | Generic Function | DOM Level 1 Core method of NamedNodeMap: removeNamedItem(name) returns a Node object.
dom-replace-child | Generic Function | DOM Level 1 Core method of Node: replaceChild(newChild, oldChild)
dom-replace-data | Generic Function | DOM Level 1 Core method of CharacterData: replaceData(offset, count, arg) has no return value.
dom-set-attribute | Generic Function | DOM Level 1 Core method of Element: setAttribute(name, value)
dom-set-attribute-node | Generic Function | DOM Level 1 Core method of Element: setAttributeNode(newAttr)
dom-set-named-item | Generic Function | DOM Level 1 Core method of NamedNodeMap: setNamedItem(arg) The arg parameter is a Node object.
dom-specified | Generic Function | DOM Level 1 Core read-only property of Attr: specified is of type Boolean.
dom-split-text | Generic Function | DOM Level 1 Core method of Text: splitText(offset) returns a Text object.
dom-substring-data | Generic Function | DOM Level 1 Core method of CharacterData: substringData(offset, count) returns a String.
dom-system-id | Generic Function | DOM Level 1 Core read-only property of Notation: systemId
dom-tag-name | Generic Function | DOM Level 1 Core read-only property of Element: tagName
dom-target | Generic Function | DOM Level 1 property of ProcessingInstruction: data is of type String. DOM Level 1 read-only property of ProcessingInstruction: target is of type String.
dom-value | Generic Function | DOM Level 1 Core property of Attr: value is of type String.

### 4.3 Standard values

Name | Type | Notes
`dom-attribute-node` | Lisp Constant | DOM Level 1 Core constant of Node: ATTRIBUTE_NODE is value 2.
`dom-cdata-section-node` | Lisp Constant | DOM Level 1 Core constant of Node: CDATA_SECTION_NODE is value 4.
`dom-comment-node` | Lisp Constant | DOM Level 1 Core constant of Node: COMMENT_NODE is value 8.
`dom-document-fragment-node` | Lisp Constant | DOM Level 1 Core constant of Node: DOCUMENT_FRAGMENT_NODE is value 11.
`dom-document-node` | Lisp Constant | DOM Level 1 Core constant of Node: DOCUMENT_NODE is value 9.
`dom-document-type-node` | Lisp Constant | DOM Level 1 Core constant of Node: DOCUMENT_TYPE_NODE is value 10.
`dom-element-node` | Lisp Constant | DOM Level 1 Core constant of Node: ELEMENT_NODE is value 1.
`dom-entity-node` | Lisp Constant | DOM Level 1 Core constant of Node: ENTITY_NODE is value 6.
`dom-entity-reference-node` | Lisp Constant | DOM Level 1 Core constant of Node: ENTITY_REFERENCE_NODE is value 5.
`dom-notation-node` | Lisp Constant | DOM Level 1 Core constant of Node: NOTATION_NODE is value 12.
`dom-processing-instruction-node` | Lisp Constant | DOM Level 1 Core constant of Node: PROCESSING_INSTRUCTION_NODE is value 7.
`dom-text-node` | Lisp Constant | DOM Level 1 Core constant of Node: TEXT_NODE is value 3.

### 4.4 Standard conditions

Name | Type | Notes
`dom-domstring-size-err` | DOM Condition | DOM Level 1 Core condition code DOMSTRING_SIZE_ERR: the specified range of text does not fit into a DOMString
`dom-hierarchy-request-err` | DOM Condition | DOM Level 1 Core condition code HIERARCHY_REQUEST_ERR: If any node is inserted somewhere it doesn't belong
`dom-index-size-err` | DOM Condition | DOM Level 1 Core condition code INDEX_SIZE_ERR: index or size is negative, or greater than the allowed value
`dom-inuse-attribute-err` | DOM Condition | DOM Level 1 Core condition code INUSE_ATTRIBUTE_ERR: an attempt is made to add an attribute that is already in use elsewhere
`dom-invalid-character-err` | DOM Condition | DOM Level 1 Core condition code INVALID_CHARACTER_ERR: an invalid or illegal character is specified, such as in a name
`dom-no-data-allowed-err` | DOM Condition | DOM Level 1 Core condition code NO_DATA_ALLOWED_ERR: data is specified for a node which does not support data
`dom-no-modification-allowed-err` | DOM Condition | DOM Level 1 Core condition code NO_MODIFICATION_ALLOWED_ERR: an attempt is made to modify an object where modifications are not allowed
`dom-not-found-err` | DOM Condition | DOM Level 1 Core condition code NOT_FOUND_ERR: an attempt is made to reference a node in a context where it does not exist
`dom-not-supported-err` | DOM Condition | DOM Level 1 Core condition code NOT_SUPPORTED_ERR: the implementation does not support the type of object requested
`dom-wrong-document-err` | DOM Condition | DOM Level 1 Core condition code WRONG_DOCUMENT_ERR: If a node is used in a different document than the one that created it (that doesn't support it)

### 4.5 Additional classes, methods, functions, and variables

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-element`s and `dom-document`s. It is like dom-get-elements-by-tag-name, but returns a Lisp list of nodes. This LIST IS NOT LIVE.

## dom-node-list-nodes

Generic Function, package: net.xml.dom

Arguments:

This Extended method of NodeList returns a Lisp list of `dom-node` instances and thus allows typical Lisp list operations without going through `dom-node-list` accessors.

This list is not entirely "live", as described earlier.

## dom-node-type-p

Generic Function, package: net.xml.dom

Arguments: dom-node type-name-or-number

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 (entity-replacement *dom-print-entity-replacement*) &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`.
- `t`: output is to *standard-output*.
- `nil`: two values are returned: the node argument, and a string containing the output.

The keyword arguments indent and attrs rebind the values of *dom-print-indent* and *dom-print-attrs* during the call to dom-print.

The keyword argument entity-replacement affects how some of the XML syntax characters are rendered in the output. When the value is `nil`, there is no entity replacement at all, meaning characters like & are left alone and entities like `&` are converted to & (this is the default, and legacy behavior). When the value is `:min`, the reserved XML characters are printed as the entities `&` and `&lt;`. If a string value cannot be printed with one of the two quote characters, the string output may show `&quot;` or `&apos;` as required. With the `:min` value the output of dom-print should be legal XML (although not necessarily identical to the originally parsed XML). If the argument is omitted, the value is taken from the variable *dom-print-entity-replacement*. Here is an example. Note the ampersand (&) in the string is plain text in the first result and an entity in the second.

    cg-user(16): (net.xml.dom:dom-print
                    (net.xml.dom:parse-to-dom
                        "<a href=\"pic.png?a&b\"></a>") nil
                        :entity-replacement nil )
    #<net.xml.dom:dom1-document (1) @ #x2029f5052>
    "<a href='pic.png?a&b' />"
    cg-user(17): (net.xml.dom:dom-print
                    (net.xml.dom:parse-to-dom
                        "<a href=\"pic.png?a&b\"></a>") nil
                        :entity-replacement :min)
    #<net.xml.dom:dom1-document (1) @ #x202a27182>
    "<a href='pic.png?a&b' />"

The function dom-print-min is dom-print with the entity-replacement argument set to `:min`.

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.

## *dom-print-entity-replacement*

Variable, package: net.xml.dom

Initially `nil`. This variable supplies the default value for the entity-replacement keyword argument to dom-print. See dom-print for further information.

## dom-print-min

Generic Function, package: net.xml.dom

Arguments: node stream &key indent attrs if-exists (entity-replacement :min) &allow-other-keys

Essentially dom-print with the entity-replacement keyword argument defaulting to :min. See dom-print for more information.

## 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.html). 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.html). The default for class is `dom1-parser`.

## with-serial-lock

Macro, package: net.xml.dom

Arguments: (object) &body body

The behavior depends on the setting of the global variable *dom-enforce-locks*.

If the value of *dom-enforce-locks* is `nil`, no locking takes place while body is evaluated. If the value of *dom-enforce-locks* is an instance of mp:process-lock, then the global lock is used.

Otherwise, the value of object is examined:

- 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.

## 5.0 Examples using the DOM

Here are the examples of using DOM in examples/xml/dom-code.cl (that file is downloaded with the DOM patch).

    ;;
    ;; copyright (c) 2004 Franz Inc, Oakland, CA

    (in-package :user)

    ;;  The DOM module is part of the SAX module
    (eval-when (compile load eval) (require :sax))

    (defpackage :user (:use :net.xml.dom))

    ;;;
    ;;; Some programming examples using the DOM Level 1 API
    ;;;

    (defparameter *dom-ex1-data*

      ;; Sample file noDTDXMLfile.xml from domtest-ecmascript-120499.zip
      ;; at http://www.w3.org/DOM/Test/

    "<?xml version='1.0'?>
    <staff>
     <employee>
      <employeeId>EMP0001</employeeId>
      <name>Margaret Martin</name>
      <position>Accountant</position>
      <salary>56,000</salary>
      <gender>Female</gender>
      <address domestic='Yes'>1230 North Ave. Dallas, Texas 98551</address>
     </employee>
     </staff>

    "
    )

    (defun dom-ex1 ()

      ;; Parse an XML document and walk the resulting DOM tree

      (let* ((doc (parse-to-dom *dom-ex1-data*))
         (root (dom-document-element doc))
        )
        (format t "~%The root element is ~A~%" (dom-tag-name root))

        (dolist (c (dom-child-node-list root))
          (format t "~&  Child node: ~S~%" c))

        (let* ((addr (dom-list-elements-by-tag-name root "address"))
           (attrs (dom-attributes (first addr))))
          (format t "~&  The address element has ~S attributes~%"
                  (dom-length attrs)))

        doc))

    (defun dom-ex2 (&optional (file t))

      ;; Build a DOM tree from parts and print the result

      (let ((doc (dom-create-document))
        staff emp)
        (dom-append-child doc (setf staff (dom-create-element doc "staff")))
        (dom-append-child staff (setf emp (dom-create-element doc "employee")))

        (flet ((add (parent doc name text &aux child)
            (dom-append-child parent (setf child
                                                   (dom-create-element doc name)))
            (dom-append-child child (dom-create-text-node doc text))
            child))
          (add emp doc "employeeId" "EMP00002")
          (add emp doc "name" "Alter Ego")
          (add emp doc "position" "Auditor")
          (add emp doc "salary" "65,000")
          (add emp doc "gender" "Male")
          (dom-set-attribute
           (add emp doc "address" "Port Ludlow, WA")
           "domestic" "Yes")
          )

        (dom-print doc file)

        doc))

    ;;  Here we run the functions:

    cl-user(18): (dom-ex1)

    The root element is staff
      Child node: #<dom1-text -2- @ #x10ca93fa>
      Child node: #<dom1-element employee(13) @ #x10ca95ca>
      Child node: #<dom1-text -2- @ #x10caa4da>
      The address element has 1 attributes
    #<dom1-document (1) @ #x10ca46c2>
    cl-user(19): (dom-ex2)
    <staff>
      <employee>
        <employeeId>EMP00002</employeeId>
        <name>Alter Ego</name>
        <position>Auditor</position>
        <salary>65,000</salary>
        <gender>Male</gender>
        <address domestic='Yes'>Port Ludlow, WA
        </address>
      </employee>
    </staff>
    #<dom1-document (1) @ #x11148e42>
    cl-user(20):

## 6.0 Index for DOM

- dom-append-child: Standard function
- dom-append-data: Standard function
- dom-attr: Standard class
- dom-attribute-node: Standard value
- dom-attributes: Standard function
- dom-cdata-section-node: Standard value
- dom-cdata-section: Standard class
- dom-character-data: Standard class
- dom-child-node-list: Generic Function
- dom-child-nodes: Standard function
- dom-clone-node: Standard function
- dom-comment-node: Standard value
- dom-comment: Standard class
- dom-condition: class
- dom-condition-code: generic function
- dom-condition-data: generic function
- dom-condition-name: generic function
- dom-condition-note: generic function
- dom-condition-string: generic function
- dom-create-attribute: Standard function
- dom-create-cdata-section: Standard function
- dom-create-comment: Standard function
- dom-create-document: Function
- dom-create-document-fragment: Standard function
- dom-create-element: Standard function
- dom-create-entity-reference: Standard function
- dom-create-processing-instruction: Standard function
- dom-create-text-node: Standard function
- dom-data: Standard function
- dom-delete-data: Standard function
- dom-doctype: Standard function
- dom-document-element: Standard function
- dom-document-fragment-node: Standard value
- dom-document-fragment: Standard class
- dom-document-node: Standard value
- dom-document-parser: Generic Function
- dom-document-type-node: Standard value
- dom-document-type: Standard class
- dom-document: Standard class
- dom-domstring-size-err: Standard condition
- dom-dump: Generic Function
- dom-element-node: Standard value
- dom-element: Standard class
- *dom-enforce-locks*: variable
- dom-entities: Standard function
- dom-entity-node: Standard value
- dom-entity-reference-node: Standard value
- dom-entity-reference: Standard class
- dom-entity: Standard class
- dom-equal: Generic Function
- dom-first-child: Standard function
- dom-get-attribute-node: Standard function
- dom-get-attribute: Standard function
- dom-get-elements-by-tag-name: Standard function
- dom-get-named-item: Standard function
- dom-has-child-nodes: Standard function
- dom-has-feature: Standard function
- dom-hierarchy-request-err: Standard condition
- dom-implementation: Standard class
- dom-implementation: Standard function
- dom-index-size-err: Standard condition
- dom-insert-before: Standard function
- dom-insert-data: Standard function
- dom-inuse-attribute-err: Standard condition
- dom-invalid-character-err: Standard condition
- dom-item-name: Generic Function
- dom-item-value: Generic Function
- dom-item: Standard function
- dom-last-child: Standard function
- dom-length: Standard function
- dom-list-elements-by-tag-name: Generic Function
- dom-name: Standard function
- dom-named-node-map: Standard class
- dom-next-sibling: Standard function
- dom-no-data-allowed-err: Standard condition
- dom-no-modification-allowed-err: Standard condition
- dom-node-list-nodes: Generic Function
- dom-node-list: Standard class
- dom-node-name: Standard function
- dom-node-type-p: Generic Function
- dom-node-type: Standard function
- dom-node-value: Standard function
- dom-node: Standard class
- dom-normalize: Standard function
- dom-not-found-err: Standard condition
- dom-not-supported-err: Standard condition
- dom-notation-name: Standard function
- dom-notation-node: Standard value
- dom-notation: Standard class
- dom-notations: Standard function
- dom-owner-document: Standard function
- dom-parent-node: Standard function
- dom-parser: class
- dom-previous-sibling: Standard function
- dom-print: Generic Function
- *dom-print-attrs*: variable
- *dom-print-indent*: variable
- dom-processing-instruction-node: Standard value
- dom-processing-instruction: Standard class
- dom-public-id: Standard function
- dom-remove-attribute-node: Standard function
- dom-remove-attribute: Standard function
- dom-remove-child: Standard function
- dom-remove-named-item: Standard function
- dom-replace-child: Standard function
- dom-replace-data: Standard function
- dom-set-attribute-node: Standard function
- dom-set-attribute: Standard function
- dom-set-named-item: Standard function
- dom-specified: Standard function
- dom-split-text: Standard function
- dom-substring-data: Standard function
- dom-system-id: Standard function
- dom-tag-name: Standard function
- dom-target: Standard function
- dom-text-node: Standard value
- dom-text: Standard class
- dom-value: Standard function
- dom-wrong-document-err: Standard condition
- dom1-attr: Standard class
- dom1-cdata-section: Standard class
- dom1-character-data: Standard class
- dom1-comment: Standard class
- dom1-document-fragment: Standard class
- dom1-document-type: Standard class
- dom1-document: Standard class
- dom1-element: Standard class
- dom1-entity-reference: Standard class
- dom1-entity: Standard class
- dom1-implementation: Standard class
- dom1-named-node-map: Standard class
- dom1-node-list: Standard class
- dom1-node: Standard class
- dom1-notation: Standard class
- dom1-parser: class
- dom1-processing-instruction: Standard class
- dom1-text: Standard class
- file-to-dom: Generic Function
- parse-to-dom: Generic Function
- with-serial-lock: Macro

Copyright (c) Franz Inc. Lafayette, CA., USA. All rights reserved.

ToC | DocOverview | CGDoc | RelNotes | FAQ | Index | PermutedIndex
| Allegro CL version 11.0