Document Object Model (DOM) in Allegro Common Lisp

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

4.2 Standard methods and functions

4.3 Standard values

4.4 Standard conditions

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-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-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-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 <. If a string value cannot be printed with one of the two quote characters, the string output may show " or ' 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.