doc/dom.xml

   1 <documentation title="CXML W3C DOM">
   2   <h1>W3C DOM</h1>
   3   <p>
   4     CXML implements the DOM Level 2 Core interfaces.&#160; For details
   5     on DOM, please refer to the <a
   6                                    href="http://www.w3.org/TR/DOM-Level-2-Core/core.html">specification</a>.
   7   </p>
   8
   9   <a name="parser"/>
  10   <h3>Parsing into DOM</h3>
  11   <p>
  12     To parse an XML document into a DOM tree, use the SAX parser with a
  13     DOM builder as the SAX handler.  Example:
  14   </p>
  15   <pre>(cxml:parse-file "test.xml" (cxml-dom:make-dom-builder))</pre>
  16   <p>
  17     <div class="def">Function CXML-DOM:MAKE-DOM-BUILDER ()</div>
  18     Create a SAX handler which builds a DOM document.
  19     <p>
  20     </p>
  21     This functions returns a DOM builder that will work with the default
  22     configuration of the SAX parser and is guaranteed to use
  23     characters/strings instead of runes/rods, if that makes a
  24     difference on the Lisp in question.
  25     <p>
  26     </p>
  27     This is the same as <tt>rune-dom:make-dom-builder</tt> on Lisps
  28     with Unicode support, and the same as
  29     <tt>utf8-dom:make-dom-builder</tt> otherwise.
  30   </p>
  31
  32   <p>
  33     <div class="def">Function RUNE-DOM:MAKE-DOM-BUILDER ()</div>
  34     Create a SAX handler which builds a DOM document using runes and rods.
  35   </p>
  36
  37   <p>
  38     <div class="def">Function UTF8-DOM:MAKE-DOM-BUILDER ()</div>
  39     (Only on Lisps without Unicode support:)
  40     Create a SAX handler which builds a DOM document using
  41     UTF-8-encoded strings.
  42   </p>
  43
  44   <a name="serialization"/>
  45   <h3>Serializing DOM</h3>
  46   <p>
  47     To serialize a DOM document, use a SAX serialization sink as the
  48     argument to <tt>dom:map-document</tt>, which generates SAX events
  49     for the DOM tree.
  50   </p>
  51   <p>
  52     Applications dealing with namespaces might want to inject a
  53     <a href="sax.html#misc">namespace normalizer</a> into the
  54     sink chain.
  55   </p>
  56   <p>
  57     <div class="def">Function DOM:MAP-DOCUMENT (handler document &amp;key include-xmlns-attributes include-default-values include-doctype)</div>
  58     Traverse a DOM document and call SAX functions as if an XML
  59     representation of the document was processed by a SAX parser.
  60   </p>
  61   <p>Keyword arguments:</p>
  62   <ul>
  63     <li>
  64       <tt>include-xmlns-attributes</tt> -- defaults to
  65       <tt>sax:*include-xmlns-attributes*</tt>
  66     </li>
  67     <li>
  68       <tt>include-doctype</tt> -- One of <tt>nil</tt> (no doctype
  69       declaration), <tt>:full-internal-subset</tt> (include a doctype
  70       declaration and the full internal subset), or
  71       <tt>:canonical-notations</tt> (write a doctype declaration
  72       with an internal subset including only notations, as required
  73       for canonical serialization).
  74     </li>
  75     <li>
  76       <tt>include-default-values</tt> -- include attribute nodes with nil
  77       <tt>dom:specified</tt>.
  78     </li>
  79     <li>
  80       <tt>recode</tt> -- (ignored on Lisps with Unicode support.) If
  81       true, recode UTF-8 strings to rods.   Defaults to true if used
  82       with a UTF-8 DOM document.  It can be set to false manually to
  83       suppress recoding in this case.
  84     </li>
  85   </ul>
  86
  87   <a name="mapping"/>
  88   <h3>DOM/Lisp mapping</h3>
  89   <p>
  90     Note that there is no "standard" DOM mapping for Lisp.
  91   </p>
  92   <p>
  93     DOM is <a
  94               href="http://www.w3.org/TR/DOM-Level-2-Core/idl-definitions.html">specified
  95       in CORBA IDL</a>, but it refrains from using object-oriented IDL
  96     features, allowing for a much more natural Lisp implemenation than
  97     the the ordinary IDL/Lisp mapping would.&#160;
  98     Differences between CXML's DOM and the direct IDL/Lisp mapping:
  99   </p>
 100   <ul>
 101     <li>
 102       DOM function names are symbols in the <tt>DOM</tt> package (not
 103       the <tt>OP</tt> package).
 104     </li>
 105     <li>
 106       DOM functions have proper required arguments, not a huge
 107       <tt>&amp;rest</tt> lambda list.
 108     </li>
 109     <li>
 110       Although most IDL interfaces are implemented as CLOS classes by
 111       CXML, the Lisp types of DOM objects is not documented and cannot
 112       be relied upon.&#160; A node's type can be determined using
 113       <tt>dom:node-type</tt> instead.
 114     </li>
 115     <li>
 116       <tt>DOMString</tt> is mapped to <tt>rod</tt>, which is either
 117       an <tt>(unsigned-byte 16)</tt> array type or a string type.
 118     </li>
 119     <li>
 120       The IDL/Lisp mapping maps CORBA enums to Lisp keywords.&#160;
 121       Unfortunately, the DOM IDL does not use enums.&#160; Instead,
 122       both exception types and node types are defined integer
 123       constants.&#160; CXML chooses to ignore this definition and uses
 124       keywords instead.
 125     </li>
 126     <li>
 127       DOM uses StudlyCaps.&#160; Lisp programmers don't.&#160; We
 128       insert <tt>#\-</tt> before every upper case letter preceded by a
 129       lower case letter and before every upper case letter which is
 130       followed by a lower case letter, but preceded by a capital
 131       letter.&#160; This algorithms leads to the natural Lisp spelling
 132       of DOM function names.
 133     </li>
 134     <li>
 135       Implementation note: DOM's <tt>NodeList</tt> does not
 136       necessarily map to a native "sequence" type.&#160; (For example,
 137       node lists are objects in Java, not arrays.)&#160;
 138       <tt>NodeList</tt> is specified to reflect changes done after a
 139       node list was created, so node lists cannot be Lisp lists.&#160;
 140       (A node list could be implemented as a CLOS object pointing to
 141       said list though.)&#160; Instead, CXML currently implements node
 142       lists as adjustable vectors.&#160; Note that code which relies on
 143       this implementation and uses Lisp sequence functions
 144       instead of sticking to <tt>dom:item</tt> and <tt>dom:length</tt>
 145       is not portable.&#160; As a compromise, you can use our
 146       extensions <tt>dom:map-node-list</tt> or
 147       <tt>dom:do-node-list</tt>, which can be implemented portably.
 148     </li>
 149   </ul>
 150 </documentation>