dokumentation aufgeteilt
This commit is contained in:
dlichteblau
39
README.html
39
README.html
@ -10,32 +10,6 @@
|
|||||||
<p>
|
<p>
|
||||||
<a href="README.html">CXML Homepage</a>
|
<a href="README.html">CXML Homepage</a>
|
||||||
</p>
|
</p>
|
||||||
<ul>
|
|
||||||
<li>
|
|
||||||
<a href="doc/installation.html">Installing Closure XML</a>
|
|
||||||
<ul>
|
|
||||||
<li><a href="doc/installation.html#download"><b>Download</b></a></li>
|
|
||||||
<li><a href="doc/installation.html#implementations">Implementation-specific notes</a></li>
|
|
||||||
<li><a href="doc/installation.html#compilation"><b>Compilation</b></a></li>
|
|
||||||
<li><a href="doc/installation.html#tests">Tests</a></li>
|
|
||||||
</ul>
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
<a href="doc/using.html">Using Closure XML</a>
|
|
||||||
<ul>
|
|
||||||
<li><a href="doc/using.html#quickstart"><b>Quick-Start Example</b></a></li>
|
|
||||||
<li><a href="doc/using.html#parser">Parsing and Validating</a></li>
|
|
||||||
<li><a href="doc/using.html#serialization">Serialization</a></li>
|
|
||||||
<li><a href="doc/using.html#misc">Miscellaneous Utility Functions</a></li>
|
|
||||||
<li><a href="doc/using.html#xmls">XMLS Compatibility</a></li>
|
|
||||||
<li><a href="doc/using.html#rods">Dealing with Rods</a></li>
|
|
||||||
<li><a href="doc/using.html#dtdcache">Caching of DTD Objects</a></li>
|
|
||||||
<li><a href="doc/using.html#catalogs">XML Catalogs</a></li>
|
|
||||||
<li><a href="doc/using.html#sax">SAX Interface</a></li>
|
|
||||||
<li><a href="doc/using.html#dom">DOM Notes</a></li>
|
|
||||||
</ul>
|
|
||||||
</li>
|
|
||||||
</ul>
|
|
||||||
</div>
|
</div>
|
||||||
|
|
||||||
<h1>Closure XML Parser</h1>
|
<h1>Closure XML Parser</h1>
|
||||||
@ -90,17 +64,8 @@
|
|||||||
<h2>Recent Changes</h2>
|
<h2>Recent Changes</h2>
|
||||||
<p class="nomargin"><tt>rel-2005-xx-yy</tt></p>
|
<p class="nomargin"><tt>rel-2005-xx-yy</tt></p>
|
||||||
<ul class="nomargin">
|
<ul class="nomargin">
|
||||||
<li>
|
<li>Implemented DOM 2 Core.</li>
|
||||||
Implemented DOM 2 Core.
|
<li>Error handling overhaul.</li>
|
||||||
(A handler for DOM 3-style namespace normalization is provided and
|
|
||||||
used by default for serialization of DOM documents if namespace
|
|
||||||
support is enabled.)
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
Error handling overhaul: All syntax errors should now be
|
|
||||||
reported as instances of <tt>well-formedness-violation</tt>. We
|
|
||||||
also print line number information.
|
|
||||||
</li>
|
|
||||||
<li>Support internal subset serialization.</li>
|
<li>Support internal subset serialization.</li>
|
||||||
<li>Gilbert Baumann has clarified the license as Lisp-LGPL.</li>
|
<li>Gilbert Baumann has clarified the license as Lisp-LGPL.</li>
|
||||||
<li>Use trivial-gray-streams.</li>
|
<li>Use trivial-gray-streams.</li>
|
||||||
|
|||||||
16
doc/cxml.css
16
doc/cxml.css
@ -5,19 +5,33 @@ div.sidebar {
|
|||||||
margin: 0em 2pt 1em 2em;
|
margin: 0em 2pt 1em 2em;
|
||||||
min-width: 15%;
|
min-width: 15%;
|
||||||
padding: 0pt 5pt 5pt 5pt;
|
padding: 0pt 5pt 5pt 5pt;
|
||||||
|
font-family: helvetica;
|
||||||
}
|
}
|
||||||
|
|
||||||
div.sidebar ul {
|
div.sidebar ul.main {
|
||||||
padding: 0pt 0pt 0pt 1em;
|
padding: 0pt 0pt 0pt 1em;
|
||||||
margin: 0 0 1em;
|
margin: 0 0 1em;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
div.sidebar ul.sub {
|
||||||
|
list-style-type: square;
|
||||||
|
padding: 0pt 0pt 0pt 1em;
|
||||||
|
margin: 0 0 1em;
|
||||||
|
}
|
||||||
|
|
||||||
|
div.sidebar ul.hack {
|
||||||
|
padding: 0 0 0 0;
|
||||||
|
margin: 0 0 1em;
|
||||||
|
list-style-type: none;
|
||||||
|
}
|
||||||
|
|
||||||
body {
|
body {
|
||||||
color: #000000;
|
color: #000000;
|
||||||
background-color: #ffffff;
|
background-color: #ffffff;
|
||||||
margin-right: 0pt;
|
margin-right: 0pt;
|
||||||
margin-bottom: 10%;
|
margin-bottom: 10%;
|
||||||
padding-left: 30px;
|
padding-left: 30px;
|
||||||
|
font-family: helvetica;
|
||||||
}
|
}
|
||||||
|
|
||||||
h1,h2,h3 {
|
h1,h2,h3 {
|
||||||
|
|||||||
156
doc/dom.html
Normal file
156
doc/dom.html
Normal file
@ -0,0 +1,156 @@
|
|||||||
|
<?xml version="1.0" encoding="iso-8859-1"?>
|
||||||
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||||||
|
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
|
||||||
|
<head>
|
||||||
|
<title>Closure XML</title>
|
||||||
|
<link rel="stylesheet" type="text/css" href="cxml.css"/>
|
||||||
|
</head>
|
||||||
|
<body>
|
||||||
|
<div class="sidebar">
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<h1>The DOM implementation</h1>
|
||||||
|
<p>
|
||||||
|
CXML implements the DOM Level 2 Core interfaces. For details
|
||||||
|
on DOM, please refer to the <a
|
||||||
|
href="http://www.w3.org/TR/DOM-Level-2-Core/core.html">specification</a>.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<a name="parser"/>
|
||||||
|
<h3>Parsing into DOM</h3>
|
||||||
|
<p>
|
||||||
|
To parse an XML document into a DOM tree, use the SAX parser with a
|
||||||
|
DOM builder as the SAX handler. Example:
|
||||||
|
</p>
|
||||||
|
<pre>(cxml:parse-file "test.xml" (dom:make-dom-builder))</pre>
|
||||||
|
<p>
|
||||||
|
<div class="def">Function DOM:MAKE-DOM-BUILDER ()</div>
|
||||||
|
Create a SAX handler which builds a DOM document.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<a name="serialization"/>
|
||||||
|
<h3>Serializing DOM</h3>
|
||||||
|
<p>
|
||||||
|
The technique used to serialize a DOM document is to use a SAX
|
||||||
|
serialization sink as the argument to <tt>dom:map-document</tt>,
|
||||||
|
which generates SAX events for the DOM tree.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
In addition, there are convenience functions like
|
||||||
|
<tt>unparse-document</tt> as a thin wrapper around
|
||||||
|
<tt>map-document</tt>.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
<div class="def">Function DOM:MAP-DOCUMENT (handler document &key include-xmlns-attributes include-default-values include-doctype)</div>
|
||||||
|
Traverse a DOM document and call SAX functions as if an XML
|
||||||
|
representation of the document was processed by a SAX parser.
|
||||||
|
</p>
|
||||||
|
<p>Keyword arguments:</p>
|
||||||
|
<ul>
|
||||||
|
<li>
|
||||||
|
<tt>include-xmlns-attributes</tt> -- defaults to
|
||||||
|
<tt>sax:*include-xmlns-attributes*</tt>
|
||||||
|
</li>
|
||||||
|
<li>
|
||||||
|
<tt>include-doctype</tt> -- One of <tt>nil</tt> (no doctype
|
||||||
|
declaration), <tt>:full-internal-subset</tt> (include a doctype
|
||||||
|
declaration and the full internal subset), or
|
||||||
|
<tt>:canonical-notations</tt> (write a doctype declaration
|
||||||
|
with an internal subset including only notations, as required
|
||||||
|
for canonical serialization).
|
||||||
|
</li>
|
||||||
|
<li>
|
||||||
|
<tt>include-default-values</tt> -- include attribute nodes with nil
|
||||||
|
<tt>dom:specified</tt>.
|
||||||
|
</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
<div class="def">Function CXML:UNPARSE-DOCUMENT (document stream &rest keys)</div>
|
||||||
|
<div class="def">Function CXML:UNPARSE-DOCUMENT-TO-OCTETS (document &rest keys) => vector</div>
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
Serialize a DOM document object. These convenience functions are
|
||||||
|
wrappers around <tt>dom:map-document</tt>.
|
||||||
|
</p>
|
||||||
|
<p>Keyword arguments are passed on to the sink. C.f. <a
|
||||||
|
href="using.html#serialization">cxml:make-octet-vector-sink</a>.</p>
|
||||||
|
<p>Notes:</p>
|
||||||
|
<ul>
|
||||||
|
<li>
|
||||||
|
If keyword argument <tt>canonical</tt> is specified as 2, a
|
||||||
|
doctype declaration will be written that includes notations
|
||||||
|
declared in the document.
|
||||||
|
</li>
|
||||||
|
<li>
|
||||||
|
If namespace processing is enabled
|
||||||
|
(<tt>sax:*namespace-processing*</tt>), a <a
|
||||||
|
href="using.html#misc">namespace normalizer</a> is used.
|
||||||
|
</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<a name="mapping"/>
|
||||||
|
<h3>DOM/Lisp mapping</h3>
|
||||||
|
<p>
|
||||||
|
Note that there is no "standard" DOM mapping for Lisp.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
DOM is <a
|
||||||
|
href="http://www.w3.org/TR/DOM-Level-2-Core/idl-definitions.html">specified
|
||||||
|
in CORBA IDL</a>, 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:
|
||||||
|
</p>
|
||||||
|
<ul>
|
||||||
|
<li>
|
||||||
|
DOM function names are symbols in the <tt>DOM</tt> package (not
|
||||||
|
the <tt>OP</tt> package).
|
||||||
|
</li>
|
||||||
|
<li>
|
||||||
|
DOM functions have proper required arguments, not a huge
|
||||||
|
<tt>&rest</tt> lambda list.
|
||||||
|
</li>
|
||||||
|
<li>
|
||||||
|
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
|
||||||
|
<tt>dom:node-type</tt> instead.
|
||||||
|
</li>
|
||||||
|
<li>
|
||||||
|
<tt>DOMString</tt> is mapped to <tt>rod</tt>, which is either
|
||||||
|
an <tt>(unsigned-byte 16)</tt> array type or a string type.
|
||||||
|
</li>
|
||||||
|
<li>
|
||||||
|
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.
|
||||||
|
</li>
|
||||||
|
<li>
|
||||||
|
DOM uses StudlyCaps. Lisp programmers don't. We
|
||||||
|
insert <tt>#\-</tt> 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.
|
||||||
|
</li>
|
||||||
|
<li>
|
||||||
|
Implementation note: DOM's <tt>NodeList</tt> does not
|
||||||
|
necessarily map to a native "sequence" type. (For example,
|
||||||
|
node lists are objects in Java, not arrays.)
|
||||||
|
<tt>NodeList</tt> 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 <tt>dom:item</tt> and <tt>dom:length</tt>
|
||||||
|
is not portable. As a compromise, you can use our
|
||||||
|
extensions <tt>dom:map-node-list</tt> or
|
||||||
|
<tt>dom:do-node-list</tt>, which can be implemented portably.
|
||||||
|
</li>
|
||||||
|
</ul>
|
||||||
|
</body>
|
||||||
|
</html>
|
||||||
@ -7,35 +7,6 @@
|
|||||||
</head>
|
</head>
|
||||||
<body>
|
<body>
|
||||||
<div class="sidebar">
|
<div class="sidebar">
|
||||||
<p>
|
|
||||||
<a href="../README.html">CXML Homepage</a>
|
|
||||||
</p>
|
|
||||||
<ul>
|
|
||||||
<li>
|
|
||||||
<a href="installation.html">Installing Closure XML</a>
|
|
||||||
<ul>
|
|
||||||
<li><a href="installation.html#download"><b>Download</b></a></li>
|
|
||||||
<li><a href="installation.html#implementations">Implementation-specific notes</a></li>
|
|
||||||
<li><a href="installation.html#compilation"><b>Compilation</b></a></li>
|
|
||||||
<li><a href="installation.html#tests">Tests</a></li>
|
|
||||||
</ul>
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
<a href="using.html">Using Closure XML</a>
|
|
||||||
<ul>
|
|
||||||
<li><a href="using.html#quickstart"><b>Quick-Start Example</b></a></li>
|
|
||||||
<li><a href="using.html#parser">Parsing and Validating</a></li>
|
|
||||||
<li><a href="using.html#serialization">Serialization</a></li>
|
|
||||||
<li><a href="using.html#misc">Miscellaneous Utility Functions</a></li>
|
|
||||||
<li><a href="using.html#xmls">XMLS Compatibility</a></li>
|
|
||||||
<li><a href="using.html#rods">Dealing with Rods</a></li>
|
|
||||||
<li><a href="using.html#dtdcache">Caching of DTD Objects</a></li>
|
|
||||||
<li><a href="using.html#catalogs">XML Catalogs</a></li>
|
|
||||||
<li><a href="using.html#sax">SAX Interface</a></li>
|
|
||||||
<li><a href="using.html#dom">DOM Notes</a></li>
|
|
||||||
</ul>
|
|
||||||
</li>
|
|
||||||
</ul>
|
|
||||||
</div>
|
</div>
|
||||||
<h1>Installation of Closure XML</h1>
|
<h1>Installation of Closure XML</h1>
|
||||||
|
|
||||||
|
|||||||
96
doc/quickstart.html
Normal file
96
doc/quickstart.html
Normal file
@ -0,0 +1,96 @@
|
|||||||
|
<?xml version="1.0" encoding="iso-8859-1"?>
|
||||||
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||||||
|
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
|
||||||
|
<head>
|
||||||
|
<title>Closure XML</title>
|
||||||
|
<link rel="stylesheet" type="text/css" href="cxml.css"/>
|
||||||
|
</head>
|
||||||
|
<body>
|
||||||
|
<div class="sidebar">
|
||||||
|
<p>
|
||||||
|
<a href="../README.html">CXML Homepage</a>
|
||||||
|
</p>
|
||||||
|
<ul class="main">
|
||||||
|
<li>
|
||||||
|
<a href="installation.html">Installing Closure XML</a>
|
||||||
|
<ul class="sub">
|
||||||
|
<li><a href="installation.html#download"><b>Download</b></a></li>
|
||||||
|
<li><a href="installation.html#implementations">Implementation-specific notes</a></li>
|
||||||
|
<li><a href="installation.html#compilation"><b>Compilation</b></a></li>
|
||||||
|
<li><a href="installation.html#tests">Tests</a></li>
|
||||||
|
</ul>
|
||||||
|
</li>
|
||||||
|
<li>
|
||||||
|
<ul class="hack">
|
||||||
|
<li>
|
||||||
|
<a href="using.html#quickstart"><b>Quick-Start Example</b></a>
|
||||||
|
</li>
|
||||||
|
</ul>
|
||||||
|
</li>
|
||||||
|
<li>
|
||||||
|
<a href="using.html">SAX parser</a>
|
||||||
|
<ul class="sub">
|
||||||
|
<li><a href="using.html#parser">Parsing and Validating</a></li>
|
||||||
|
<li><a href="using.html#serialization">Serialization</a></li>
|
||||||
|
<li><a href="using.html#misc">Miscellaneous SAX handlers</a></li>
|
||||||
|
<li><a href="using.html#rods">Dealing with Rods</a></li>
|
||||||
|
<li><a href="using.html#dtdcache">Caching of DTD Objects</a></li>
|
||||||
|
<li><a href="using.html#catalogs">XML Catalogs</a></li>
|
||||||
|
<li><a href="using.html#sax">SAX Interface</a></li>
|
||||||
|
</ul>
|
||||||
|
</li>
|
||||||
|
<li>
|
||||||
|
<a href="using.html">DOM implementation</a>
|
||||||
|
<ul class="sub">
|
||||||
|
<li><a href="dom.html#parser">Parsing with the DOM builder</a></li>
|
||||||
|
<li><a href="dom.html#serialization">Serialization</a></li>
|
||||||
|
<li><a href="dom.html#mapping">DOM/Lisp mapping</a></li>
|
||||||
|
</ul>
|
||||||
|
</li>
|
||||||
|
<li>
|
||||||
|
<ul class="hack">
|
||||||
|
<li><a href="xmls-compat.html">XMLS Builder</a></li>
|
||||||
|
</ul>
|
||||||
|
</li>
|
||||||
|
</ul>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<h1>Quick-Start Example</h1>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
Make sure to <a href="installation.html#installation">install and load</a> cxml first.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p>Create a test file called <tt>example.xml</tt>:</p>
|
||||||
|
<pre>* <b>(with-open-file (s "example.xml" :direction :output)
|
||||||
|
(write-string "<test a='b'><child/></test>" s))</b></pre>
|
||||||
|
|
||||||
|
<p>Parse <tt>example.xml</tt> into a DOM tree (<a href="using.html#parser">read
|
||||||
|
more</a>):</p>
|
||||||
|
<pre>* <b>(cxml:parse-file "example.xml" (dom:make-dom-builder))</b>
|
||||||
|
#<DOM-IMPL::DOCUMENT @ #x72206172>
|
||||||
|
;; save result for later:
|
||||||
|
* <b>(defparameter *example* *)</b>
|
||||||
|
*EXAMPLE*</pre>
|
||||||
|
|
||||||
|
<p>Inspect the DOM tree (<a href="using.html#dom">read more</a>):</p>
|
||||||
|
<pre>* <b>(dom:document-element *example*)</b>
|
||||||
|
#<DOM-IMPL::ELEMENT test @ #x722b6ba2>
|
||||||
|
* <b>(dom:tag-name (dom:document-element *example*))</b>
|
||||||
|
"test"
|
||||||
|
* <b>(dom:child-nodes (dom:document-element *example*))</b>
|
||||||
|
#(#<DOM-IMPL::ELEMENT child @ #x722b6d8a>)
|
||||||
|
* <b>(dom:get-attribute (dom:document-element *example*) "a")</b>
|
||||||
|
"b"</pre>
|
||||||
|
|
||||||
|
<p>Serialize the DOM document back into a stream (<a
|
||||||
|
href="using.html#serialization">read more</a>):</p>
|
||||||
|
<pre><b>(cxml:unparse-document *example* *standard-output*)</b>
|
||||||
|
<test a="b"><child></child></test></pre>
|
||||||
|
|
||||||
|
<p>As an alternative to DOM, parse into xmls-compatible list
|
||||||
|
structure (<a href="xmls-compat.html">read more</a>):</p>
|
||||||
|
<pre>* <b>(cxml:parse-file "example.xml" (cxml-xmls:make-xmls-builder))</b>
|
||||||
|
("test" (("a" "b")) ("child" NIL))</pre>
|
||||||
|
</body>
|
||||||
|
</html>
|
||||||
286
doc/using.html
286
doc/using.html
@ -7,79 +7,16 @@
|
|||||||
</head>
|
</head>
|
||||||
<body>
|
<body>
|
||||||
<div class="sidebar">
|
<div class="sidebar">
|
||||||
<p>
|
|
||||||
<a href="../README.html">CXML Homepage</a>
|
|
||||||
</p>
|
|
||||||
<ul>
|
|
||||||
<li>
|
|
||||||
<a href="installation.html">Installing Closure XML</a>
|
|
||||||
<ul>
|
|
||||||
<li><a href="installation.html#download"><b>Download</b></a></li>
|
|
||||||
<li><a href="installation.html#implementations">Implementation-specific notes</a></li>
|
|
||||||
<li><a href="installation.html#compilation"><b>Compilation</b></a></li>
|
|
||||||
<li><a href="installation.html#tests">Tests</a></li>
|
|
||||||
</ul>
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
<a href="using.html">Using Closure XML</a>
|
|
||||||
<ul>
|
|
||||||
<li><a href="using.html#quickstart"><b>Quick-Start Example</b></a></li>
|
|
||||||
<li><a href="using.html#parser">Parsing and Validating</a></li>
|
|
||||||
<li><a href="using.html#serialization">Serialization</a></li>
|
|
||||||
<li><a href="using.html#misc">Miscellaneous Utility Functions</a></li>
|
|
||||||
<li><a href="using.html#xmls">XMLS Compatibility</a></li>
|
|
||||||
<li><a href="using.html#rods">Dealing with Rods</a></li>
|
|
||||||
<li><a href="using.html#dtdcache">Caching of DTD Objects</a></li>
|
|
||||||
<li><a href="using.html#catalogs">XML Catalogs</a></li>
|
|
||||||
<li><a href="using.html#sax">SAX Interface</a></li>
|
|
||||||
<li><a href="using.html#dom">DOM Notes</a></li>
|
|
||||||
</ul>
|
|
||||||
</li>
|
|
||||||
</ul>
|
|
||||||
</div>
|
</div>
|
||||||
<h1>Using Closure XML</h1>
|
<h1>Using the SAX parser</h1>
|
||||||
|
|
||||||
<a name="quickstart"/>
|
|
||||||
<h3>Quick-Start Example</h3>
|
|
||||||
|
|
||||||
<p>
|
|
||||||
Make sure to <a href="installation.html#installation">install and load</a> cxml first.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p>Create a test file called <tt>example.xml</tt>:</p>
|
|
||||||
<pre>* <b>(with-open-file (s "example.xml" :direction :output)
|
|
||||||
(write-string "<test a='b'><child/></test>" s))</b></pre>
|
|
||||||
|
|
||||||
<p>Parse <tt>example.xml</tt> into a DOM tree (<a href="#parser">read
|
|
||||||
more</a>):</p>
|
|
||||||
<pre>* <b>(cxml:parse-file "example.xml" (dom:make-dom-builder))</b>
|
|
||||||
#<DOM-IMPL::DOCUMENT @ #x72206172>
|
|
||||||
;; save result for later:
|
|
||||||
* <b>(defparameter *example* *)</b>
|
|
||||||
*EXAMPLE*</pre>
|
|
||||||
|
|
||||||
<p>Inspect the DOM tree (<a href="#dom">read more</a>):</p>
|
|
||||||
<pre>* <b>(dom:document-element *example*)</b>
|
|
||||||
#<DOM-IMPL::ELEMENT test @ #x722b6ba2>
|
|
||||||
* <b>(dom:tag-name (dom:document-element *example*))</b>
|
|
||||||
"test"
|
|
||||||
* <b>(dom:child-nodes (dom:document-element *example*))</b>
|
|
||||||
#(#<DOM-IMPL::ELEMENT child @ #x722b6d8a>)
|
|
||||||
* <b>(dom:get-attribute (dom:document-element *example*) "a")</b>
|
|
||||||
"b"</pre>
|
|
||||||
|
|
||||||
<p>Serialize the DOM document back into a stream (<a
|
|
||||||
href="#serialization">read more</a>):</p>
|
|
||||||
<pre><b>(cxml:unparse-document *example* *standard-output*)</b>
|
|
||||||
<test a="b"><child></child></test></pre>
|
|
||||||
|
|
||||||
<p>As an alternative to DOM, parse into xmls-compatible list
|
|
||||||
structure (<a href="#xmls">read more</a>):</p>
|
|
||||||
<pre>* <b>(cxml:parse-file "example.xml" (cxml-xmls:make-xmls-builder))</b>
|
|
||||||
("test" (("a" "b")) ("child" NIL))</pre>
|
|
||||||
|
|
||||||
<a name="parser"/>
|
<a name="parser"/>
|
||||||
<h3>Parsing and Validating</h3>
|
<h3>Parsing and Validating</h3>
|
||||||
|
<p>
|
||||||
|
CXML is implemented as a SAX parser. (Refer to <a
|
||||||
|
href="dom.html#parser">make-dom-builder</a> for information about
|
||||||
|
DOM.)
|
||||||
|
</p>
|
||||||
<p>
|
<p>
|
||||||
<div class="def">Function CXML:PARSE-FILE (pathname handler &key ...)</div>
|
<div class="def">Function CXML:PARSE-FILE (pathname handler &key ...)</div>
|
||||||
<div class="def">Function CXML:PARSE-STREAM (stream handler &key ...)</div>
|
<div class="def">Function CXML:PARSE-STREAM (stream handler &key ...)</div>
|
||||||
@ -175,16 +112,29 @@
|
|||||||
<a name="serialization"/>
|
<a name="serialization"/>
|
||||||
<h3>Serialization</h3>
|
<h3>Serialization</h3>
|
||||||
<p>
|
<p>
|
||||||
<div class="def">Function CXML:UNPARSE-DOCUMENT (document stream &rest keys)</div>
|
Serialization is performed using <tt>sink</tt> objects. A sink
|
||||||
<div class="def">Function CXML:UNPARSE-DOCUMENT-TO-OCTETS (document &rest keys) => vector</div>
|
is an output stream for runes. There are different kinds of sinks
|
||||||
Serialize a DOM document object. These convenience functions are
|
for output to lisp streams, vectors, etc.
|
||||||
wrappers around <tt>dom:map-document</tt>.
|
</p>
|
||||||
|
<p>
|
||||||
|
Technically, sinks are SAX handlers that write XML output for SAX
|
||||||
|
events sent to them. In practise, user code would normally not
|
||||||
|
generate those SAX events manually, and instead use a function
|
||||||
|
like <a href="dom.html#serialization">dom:map-document</a> or <a
|
||||||
|
href="xmls-compat.html">xmls-compat:map-node</a> to serialize an
|
||||||
|
in-memory document.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
In addition to <tt>map-document</tt>, cxml has a set of
|
||||||
|
convenience macros for serialization (see below for
|
||||||
|
<tt>with-xml-output</tt>, <tt>with-element</tt>, etc).
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
<div class="def">Function CXML:MAKE-CHARACTER-STREAM-SINK (stream &rest keys) => sink</div>
|
||||||
|
<div class="def">Function CXML:MAKE-OCTET-VECTOR-SINK (&rest keys) => sink</div>
|
||||||
|
Return a handle suitable for event-based XML serialization.
|
||||||
</p>
|
</p>
|
||||||
<ul>
|
|
||||||
<li><tt>document</tt> -- a DOM document object</li>
|
|
||||||
<li><tt>stream</tt> -- a Common Lisp stream with element-type
|
|
||||||
<tt>character</tt></li>
|
|
||||||
</ul>
|
|
||||||
<p>Keyword arguments:</p>
|
<p>Keyword arguments:</p>
|
||||||
<ul>
|
<ul>
|
||||||
<li>
|
<li>
|
||||||
@ -231,12 +181,6 @@
|
|||||||
characters written by <tt>unparse-document</tt> are really UTF-8
|
characters written by <tt>unparse-document</tt> are really UTF-8
|
||||||
bytes encoded as characters.
|
bytes encoded as characters.
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
<p>
|
|
||||||
<div class="def">Function CXML:MAKE-CHARACTER-STREAM-SINK (stream &rest keys) => sink</div>
|
|
||||||
<div class="def">Function CXML:MAKE-OCTET-VECTOR-SINK (&rest keys) => sink</div>
|
|
||||||
Return a handle suitable for event-based XML serialization.
|
|
||||||
</p>
|
|
||||||
<p>
|
<p>
|
||||||
These function provide the low-level mechanism used by the DOM
|
These function provide the low-level mechanism used by the DOM
|
||||||
serialization functions. To serialize a document without building
|
serialization functions. To serialize a document without building
|
||||||
@ -272,7 +216,7 @@
|
|||||||
</foo></pre>
|
</foo></pre>
|
||||||
<p>
|
<p>
|
||||||
(Note that these functions accept both strings and rods, so we
|
(Note that these functions accept both strings and rods, so we
|
||||||
could write <tt>"foo"</tt> instead of <tt>#"foo"</tt> above.)
|
can write <tt>"foo"</tt> instead of <tt>#"foo"</tt> above.)
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
@ -303,7 +247,7 @@
|
|||||||
(sax:end-document sink))</pre>
|
(sax:end-document sink))</pre>
|
||||||
|
|
||||||
<a name="misc"/>
|
<a name="misc"/>
|
||||||
<h3>Miscellaneous Utility Functions</h3>
|
<h3>Miscellaneous SAX handlers</h3>
|
||||||
<p>
|
<p>
|
||||||
<div class="def">Function CXML:MAKE-VALIDATOR (dtd root)</div>
|
<div class="def">Function CXML:MAKE-VALIDATOR (dtd root)</div>
|
||||||
Create a SAX handler which validates against a DTD instance.
|
Create a SAX handler which validates against a DTD instance.
|
||||||
@ -337,82 +281,11 @@
|
|||||||
<p>
|
<p>
|
||||||
Return a SAX handler that performs <a
|
Return a SAX handler that performs <a
|
||||||
href="http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407/namespaces-algorithms.html#normalizeDocumentAlgo">DOM
|
href="http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407/namespaces-algorithms.html#normalizeDocumentAlgo">DOM
|
||||||
3-style namespace normalization</a> on Attribute lists in
|
3-style namespace normalization</a> on attribute lists in
|
||||||
<tt>start-element</tt> events before passing them on the next
|
<tt>start-element</tt> events before passing them on the next
|
||||||
handler.
|
handler.
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
<a name="xmls"/>
|
|
||||||
<h3>XMLS Compatibility</h3>
|
|
||||||
<p>
|
|
||||||
Like other XML parsers written in Lisp, CXML can work with
|
|
||||||
documents represented as list structures. The specific model
|
|
||||||
implemented by cxml is compatible with the <a
|
|
||||||
href="http://common-lisp.net/project/xmls/">xmls parser</a>. Xmls
|
|
||||||
list structures are a simpler and faster alternative to full DOM
|
|
||||||
document trees. They also serve as an example showing how to
|
|
||||||
implement user-defined document models as an independent layer
|
|
||||||
over the the base parser (c.f. <tt>xml/xmls-compat.lisp</tt> in
|
|
||||||
the cxml distribution). However, note that the list structures do
|
|
||||||
not include all information available in DOM documents and are
|
|
||||||
sometimes more difficult to work wth since many DOM functions
|
|
||||||
cannot be implemented on them.
|
|
||||||
</p>
|
|
||||||
<p>
|
|
||||||
<div class="def">Function CXML-XMLS:MAKE-XMLS-BUILDER (&key include-default-values)</div>
|
|
||||||
Create a SAX handler which builds XMLS list structures.
|
|
||||||
If <tt>include-default-values</tt> is true, default values for
|
|
||||||
attributes declared in a DTD are included as attributes in the
|
|
||||||
xmls output. <tt>include-default-values</tt> is true by default
|
|
||||||
and can be set to <tt>nil</tt> to suppress inclusion of default
|
|
||||||
values.
|
|
||||||
</p>
|
|
||||||
<p>
|
|
||||||
Example:
|
|
||||||
</p>
|
|
||||||
<pre>(cxml:parse-file "test.xml" (cxml-xmls:make-xmls-builder))</pre>
|
|
||||||
<p>
|
|
||||||
<div class="def">Function CXML-XMLS:MAP-NODE (handler node &key include-xmlns-attributes)</div>
|
|
||||||
Traverse an XMLS document/node and call SAX functions as if an XML
|
|
||||||
representation of the document were processed by a SAX parser.
|
|
||||||
</p>
|
|
||||||
<p>
|
|
||||||
Use this function to serialize XMLS data. For example, we could
|
|
||||||
define a replacement for <tt>xmls:write-xml</tt> like this:
|
|
||||||
</p>
|
|
||||||
<pre>(defun write-xml (stream node &key indent)
|
|
||||||
(let ((sink (cxml:make-character-stream-sink
|
|
||||||
stream :canonical nil :indentation indent)))
|
|
||||||
(cxml-xmls:map-node sink node)))</pre>
|
|
||||||
<p>
|
|
||||||
<div class="def">Function CXML-XMLS:MAKE-NODE (&key name ns attrs
|
|
||||||
children) => xmls node</div>
|
|
||||||
Build a list node of the form
|
|
||||||
(<em>name</em> ((<em>name</em> <em>value</em>)<em>*</em>) <em>child*</em>).
|
|
||||||
</p>
|
|
||||||
<p>
|
|
||||||
The node list's <tt>car</tt> can also be a cons of local <tt>name</tt>
|
|
||||||
and namespace prefix <tt>ns</tt>.
|
|
||||||
<em>fixme:</em> It is unclear to me how namespaces are meant to
|
|
||||||
work in xmls, since xmls documentation differs from how xmls
|
|
||||||
actually works in current releases. Usually applications need to
|
|
||||||
know both the namespace prefix <em>and</em> the namespace URI. We
|
|
||||||
currently follow the xmls <em>implementation</em> and use the
|
|
||||||
namespace prefix instead of following its <em>documentation</em> which
|
|
||||||
shows the URI. We do not follow xmls in munging xmlns attribute
|
|
||||||
values. Attributes themselves have namespaces and it is not clear
|
|
||||||
to me how that works in xmls.
|
|
||||||
</p>
|
|
||||||
<p>
|
|
||||||
<div class="def">Accessor CXML-XMLS:NODE-NAME (node)</div>
|
|
||||||
<div class="def">Accessor CXML-XMLS:NODE-NS (node)</div>
|
|
||||||
<div class="def">Accessor CXML-XMLS:NODE-ATTRS (node)</div>
|
|
||||||
<div class="def">Accessor CXML-XMLS:NODE-CHILDREN (node)</div>
|
|
||||||
Accessors for xmls node data.
|
|
||||||
</p>
|
|
||||||
<p>
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<a name="rods"/>
|
<a name="rods"/>
|
||||||
<h3>Dealing with Rods</h3>
|
<h3>Dealing with Rods</h3>
|
||||||
<p>
|
<p>
|
||||||
@ -648,102 +521,5 @@ NIL</pre>
|
|||||||
<p>
|
<p>
|
||||||
<i>fixme</i>: For more information on these functions refer to the docstrings.
|
<i>fixme</i>: For more information on these functions refer to the docstrings.
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
|
|
||||||
<a name="dom"/>
|
|
||||||
<h2>DOM Notes</h2>
|
|
||||||
<p>
|
|
||||||
CXML implements the DOM Level 2 Core interfaces. For details
|
|
||||||
on DOM, please refer to the <a
|
|
||||||
href="http://www.w3.org/TR/DOM-Level-2-Core/core.html">specification</a>.
|
|
||||||
</p>
|
|
||||||
<p>
|
|
||||||
However, note that there is no "standard" DOM mapping for Lisp. DOM
|
|
||||||
is <a
|
|
||||||
href="http://www.w3.org/TR/DOM-Level-2-Core/idl-definitions.html">specified
|
|
||||||
in CORBA IDL</a>, 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. The mapping chosen for
|
|
||||||
cxml is explained below.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<h3>Example</h3>
|
|
||||||
<pre>XML(97): (dom:node-type
|
|
||||||
(dom:document-element
|
|
||||||
(cxml:parse-file "~/test.xml" (dom:make-dom-builder))))
|
|
||||||
:ELEMENT</pre>
|
|
||||||
|
|
||||||
<h3>CXML-specific functions</h3>
|
|
||||||
<p>
|
|
||||||
<div class="def">Function DOM:MAKE-DOM-BUILDER ()</div>
|
|
||||||
Create a SAX handler which builds a DOM document. Example:
|
|
||||||
</p>
|
|
||||||
<pre>(cxml:parse-file "test.xml" (dom:make-dom-builder))</pre>
|
|
||||||
|
|
||||||
<p>
|
|
||||||
<div class="def">Function DOM:MAP-DOCUMENT (handler document &key include-xmlns-attributes include-default-values)</div>
|
|
||||||
Traverse a DOM document and call SAX functions as if an XML
|
|
||||||
representation of the document were processed by a SAX parser.
|
|
||||||
</p>
|
|
||||||
<p>
|
|
||||||
<tt>dom:map-document</tt> is the low-level building-block used to
|
|
||||||
implement the <a href="#serialization">serialization functions</a>
|
|
||||||
like <tt>unparse-document</tt>, but can also be used directly.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<h3>DOM/Lisp mapping</h3>
|
|
||||||
<p>
|
|
||||||
Differences between CXML's DOM and the direct IDL/Lisp mapping:
|
|
||||||
</p>
|
|
||||||
<ul>
|
|
||||||
<li>
|
|
||||||
DOM function names are symbols in the <tt>DOM</tt> package (not
|
|
||||||
the <tt>OP</tt> package).
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
DOM functions have proper required arguments, not a huge
|
|
||||||
<tt>&rest</tt> lambda list.
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
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
|
|
||||||
<tt>dom:node-type</tt> instead.
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
<tt>DOMString</tt> is mapped to <tt>rod</tt>, which is either
|
|
||||||
an <tt>(unsigned-byte 16)</tt> array type or a string type.
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
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.
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
DOM uses StudlyCaps. Lisp programmers don't. We
|
|
||||||
insert <tt>#\-</tt> 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.
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
Implementation note: DOM's <tt>NodeList</tt> does not
|
|
||||||
necessarily map to a native "sequence" type. (For example,
|
|
||||||
node lists are objects in Java, not arrays.)
|
|
||||||
<tt>NodeList</tt> 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 <tt>dom:item</tt> and <tt>dom:length</tt>
|
|
||||||
is not portable. As a compromise, you can use our
|
|
||||||
extensions <tt>dom:map-node-list</tt> or
|
|
||||||
<tt>dom:do-node-list</tt>, which can be implemented portably.
|
|
||||||
</li>
|
|
||||||
</ul>
|
|
||||||
</body>
|
</body>
|
||||||
</html>
|
</html>
|
||||||
|
|||||||
85
doc/xmls-compat.html
Normal file
85
doc/xmls-compat.html
Normal file
@ -0,0 +1,85 @@
|
|||||||
|
<?xml version="1.0" encoding="iso-8859-1"?>
|
||||||
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||||||
|
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
|
||||||
|
<head>
|
||||||
|
<title>Closure XML</title>
|
||||||
|
<link rel="stylesheet" type="text/css" href="cxml.css"/>
|
||||||
|
</head>
|
||||||
|
<body>
|
||||||
|
<div class="sidebar">
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<h1>XMLS Builder</h1>
|
||||||
|
<p>
|
||||||
|
Like other XML parsers written in Lisp, CXML can work with
|
||||||
|
documents represented as list structures. The specific model
|
||||||
|
implemented by cxml is compatible with the <a
|
||||||
|
href="http://common-lisp.net/project/xmls/">xmls parser</a>. Xmls
|
||||||
|
list structures are a simpler and faster alternative to full DOM
|
||||||
|
document trees. They also serve as an example showing how to
|
||||||
|
implement user-defined document models as an independent layer
|
||||||
|
over the the base parser (c.f. <tt>xml/xmls-compat.lisp</tt> in
|
||||||
|
the cxml distribution). However, note that the list structures do
|
||||||
|
not include all information available in DOM documents
|
||||||
|
(notably, things like <tt>dom:parent-node</tt>) and are
|
||||||
|
sometimes more difficult to work with because of that since many
|
||||||
|
DOM functions cannot be implemented on them.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
<div class="def">Function CXML-XMLS:MAKE-XMLS-BUILDER (&key include-default-values)</div>
|
||||||
|
Create a SAX handler which builds XMLS list structures.
|
||||||
|
If <tt>include-default-values</tt> is true, default values for
|
||||||
|
attributes declared in a DTD are included as attributes in the
|
||||||
|
xmls output. <tt>include-default-values</tt> is true by default
|
||||||
|
and can be set to <tt>nil</tt> to suppress inclusion of default
|
||||||
|
values.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
Example:
|
||||||
|
</p>
|
||||||
|
<pre>(cxml:parse-file "test.xml" (cxml-xmls:make-xmls-builder))</pre>
|
||||||
|
<p>
|
||||||
|
<div class="def">Function CXML-XMLS:MAP-NODE (handler node &key include-xmlns-attributes)</div>
|
||||||
|
Traverse an XMLS document/node and call SAX functions as if an XML
|
||||||
|
representation of the document were processed by a SAX parser.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
Use this function to serialize XMLS data. For example, we could
|
||||||
|
define a replacement for <tt>xmls:write-xml</tt> like this:
|
||||||
|
</p>
|
||||||
|
<pre>(defun write-xml (stream node &key indent)
|
||||||
|
(let ((sink (cxml:make-character-stream-sink
|
||||||
|
stream :canonical nil :indentation indent)))
|
||||||
|
(cxml-xmls:map-node sink node)))</pre>
|
||||||
|
<p>
|
||||||
|
<div class="def">Function CXML-XMLS:MAKE-NODE (&key name ns attrs
|
||||||
|
children) => xmls node</div>
|
||||||
|
Build a list node of the form
|
||||||
|
(<em>name</em> ((<em>name</em> <em>value</em>)<em>*</em>) <em>child*</em>).
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
The node list's <tt>car</tt> can also be a cons of local <tt>name</tt>
|
||||||
|
and namespace prefix <tt>ns</tt>.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
<em>fixme:</em> It is unclear to me how namespaces are meant to
|
||||||
|
work in xmls, since xmls documentation differs from how xmls
|
||||||
|
actually works in current releases. Usually applications need to
|
||||||
|
know both the namespace prefix <em>and</em> the namespace URI. We
|
||||||
|
currently follow the xmls <em>implementation</em> and use the
|
||||||
|
namespace prefix instead of following its <em>documentation</em> which
|
||||||
|
shows the URI. We do not follow xmls in munging xmlns attribute
|
||||||
|
values. Attributes themselves have namespaces and it is not clear
|
||||||
|
to me how that works in xmls.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
<div class="def">Accessor CXML-XMLS:NODE-NAME (node)</div>
|
||||||
|
<div class="def">Accessor CXML-XMLS:NODE-NS (node)</div>
|
||||||
|
<div class="def">Accessor CXML-XMLS:NODE-ATTRS (node)</div>
|
||||||
|
<div class="def">Accessor CXML-XMLS:NODE-CHILDREN (node)</div>
|
||||||
|
Accessors for xmls node data.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
</p>
|
||||||
|
</body>
|
||||||
|
</html>
|
||||||
Reference in New Issue
Block a user