doc/xmls-compat.xml

   1 <documentation title="CXML XMLS Compatibility">
   2     <h1>XMLS Builder</h1>
   3     <p>
   4       Like other XML parsers written in Lisp, CXML can work with
   5       documents represented as list structures. The specific model
   6       implemented by cxml is compatible with the <a
   7       href="http://common-lisp.net/project/xmls/">xmls parser</a>.  Xmls
   8       list structures are a simpler and faster alternative to full DOM
   9       document trees.  They also serve as an example showing how to
  10       implement user-defined document models as an independent layer
  11       over the the base parser (c.f. <tt>xml/xmls-compat.lisp</tt> in
  12       the cxml distribution).  However, note that the list structures do
  13       not include all information available in DOM documents
  14       (notably, things like <tt>dom:parent-node</tt>) and are
  15       sometimes more difficult to work with because of that since many
  16       DOM functions cannot be implemented on them.
  17     </p>
  18     <p>
  19       <b>New namespace handling:</b>
  20       XMLS compatibility is not <i>bug-for-bug</i>-compatible with
  21       XMLS any more.  There is now a mode using pairs of local name
  22       and namespace URI, and a second mode using qualified names
  23       only.  The old behaviour using pairs of prefix and local names
  24       was removed.
  25     </p>
  26 <!--
  27     <p>
  28       <strike>
  29         fixme: It is unclear to me how namespaces are meant to
  30         work in xmls, since xmls documentation differs from how xmls
  31         actually works in current releases.  Usually applications need to
  32         know both the namespace prefix <em>and</em> the namespace URI.  We
  33         currently follow the xmls <em>implementation</em> and use the
  34         namespace prefix instead of following its <em>documentation</em> which
  35         shows the URI.  We do not follow xmls in munging xmlns attribute
  36         values.  Attributes themselves have namespaces and it is not clear
  37         to me how that works in xmls.
  38       </strike>
  39     </p>
  40 -->
  41     <p>
  42       <div class="def">Function CXML-XMLS:MAKE-XMLS-BUILDER (&amp;key include-default-values include-namespace-uri)</div>
  43       Create a SAX handler which builds XMLS list structures.&#160;
  44       If <tt>include-default-values</tt> is true, default values for
  45       attributes declared in a DTD are included as attributes in the
  46       xmls output.  <tt>include-default-values</tt> is true by default
  47       and can be set to <tt>nil</tt> to suppress inclusion of default
  48       values.
  49     </p>
  50     <p>
  51       If <tt>include-namespace-uri</tt> is true (the default), node
  52       names and attribute names are pairs of local name and namespace
  53       URI. (Except for attributes without a namespace, which are named
  54       using a string.) Otherwise, nodes and attributes are named by
  55       their qualified name.
  56     </p>
  57     <p>
  58       Example:
  59     </p>
  60     <pre>(cxml:parse-file "test.xml" (cxml-xmls:make-xmls-builder))</pre>
  61     <p>
  62       <div class="def">Function CXML-XMLS:MAP-NODE (handler node &amp;key include-xmlns-attributes include-namespace-uri)</div>
  63       Traverse an XMLS document/node and call SAX functions as if an XML
  64       representation of the document were processed by a SAX parser.
  65     </p>
  66     <p>
  67       Use this function to serialize XMLS data.  For example, we could
  68       define a replacement for <tt>xmls:write-xml</tt> like this:
  69     </p>
  70     <pre>(defun write-xml (stream node &amp;key indent)
  71   (let ((sink (cxml:make-character-stream-sink
  72                stream :canonical nil :indentation indent)))
  73     (cxml-xmls:map-node sink node)))</pre>
  74     <p>
  75       <div class="def">Function CXML-XMLS:MAKE-NODE (&amp;key name ns attrs
  76       children) => xmls node</div>
  77       Build a list node of the form
  78       (<em>name</em>&#160;((<em>name</em>&#160;<em>value</em>)<em>*</em>)&#160;<em>child*</em>).
  79     </p>
  80     <p>
  81       The node list's <tt>car</tt> can also be a cons of local <tt>name</tt>
  82       and namespace prefix <tt>ns</tt>.
  83     </p>
  84     <p>
  85       <div class="def">Accessor CXML-XMLS:NODE-NAME (node)</div>
  86       <div class="def">Accessor CXML-XMLS:NODE-NS (node)</div>
  87       <div class="def">Accessor CXML-XMLS:NODE-ATTRS (node)</div>
  88       <div class="def">Accessor CXML-XMLS:NODE-CHILDREN (node)</div>
  89       Accessors for xmls node data.
  90     </p>
  91     <p>
  92       <div class="def">Accessor CXML-XMLS:MAKE-XPATH-NAVIGATOR ()</div>
  93       Creates a navigator object for use with Plexippus XPath.
  94     </p>
  95     <p>
  96       Note that the navigator object caches parts of the document
  97       structure, so when re-using a navigator across XPath evalutions,
  98       make sure not to modify the list structure.
  99     </p>
 100     <p>
 101       Example:
 102     </p>
 103     <pre>CL-USER> (defparameter *test-document*
 104            (cxml:parse
 105             "&lt;foo a='b'>
 106                &lt;a id='1'/> &lt;b id='2'/> &lt;c id='3'/>
 107                &lt;a id='4'/> &lt;b id='5'/> &lt;c id='6'/>
 108                &lt;a id='7'/> &lt;b id='8'/> &lt;c id='9'/>
 109                &lt;last/>
 110              &lt;/foo>"
 111             (cxml-xmls:make-xmls-builder)))
 112 *TEST-DOCUMENT*</pre>
 113 <pre>CL-USER> (let ((xpath:*navigator* (cxml-xmls:make-xpath-navigator)))
 114            (xpath:evaluate "//c[position()=2]|//a[@id='1']"
 115                            *test-document*))
 116 #&lt;XPATH:NODE-SET (a ((id 1))), ... {27C751F1}></pre>
 117 <pre>CL-USER> (xpath:all-nodes *)
 118 (("a" (("id" "1"))) ("c" (("id" "6"))))</pre>
 119 </documentation>