From 2eec88675ad262cb0e7a4c3ef92a5c40702859f6 Mon Sep 17 00:00:00 2001
From: dlichteblau <dlichteblau>
Date: Sun, 18 Feb 2007 11:07:39 +0000
Subject: [PATCH] klacks documentation

---
 README.html             |   8 +-
 doc/klacks.html         | 285 ++++++++++++++++++++++++++++++++++++++++
 doc/quickstart.html     |  17 +++
 klacks/klacks-impl.lisp |   1 +
 4 files changed, 308 insertions(+), 3 deletions(-)
 create mode 100644 doc/klacks.html
diff --git a/README.html b/README.html
index 0757f44..9769d97 100644
--- a/README.html
+++ b/README.html
@@ -86,11 +86,12 @@
     <p>
       CXML implements a <a
       href="http://www.w3.org/TR/REC-xml-names/">namespace-aware</a>,
-      validating SAX-like <a
+      validating <a
       href="http://www.w3.org/TR/2000/REC-xml-20001006">XML&nbsp;1.0</a>
       parser as well as the <a
       href="http://www.w3.org/TR/DOM-Level-2-Core/">DOM&nbsp;Level&nbsp;2&nbsp;Core</a>
-      interfaces.
+      interfaces.  Two parser interfaces are offered, one SAX-like, the
+      other similar to StAX.
     </p>
 
     <p>
@@ -107,8 +108,9 @@
 
     <a name="changes"/>
     <h2>Recent Changes</h2>
-    <p class="nomargin"><tt>rel-2006-xx-yy</tt></p>
+    <p class="nomargin"><tt>rel-2007-xx-yy</tt></p>
     <ul class="nomargin">
+      <li>New StAX-like parser interface.</li>
       <li>Serialization fixes (thanks to Nathan Bird, Donavon Keithley).</li>
       <li>characters.lisp cleanup (thanks to Nathan Bird).</li>
       <li>Namespace normalizer bugfixes.</li>
diff --git a/doc/klacks.html b/doc/klacks.html
new file mode 100644
index 0000000..7db7577
--- /dev/null
+++ b/doc/klacks.html
@@ -0,0 +1,285 @@
+<?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 class="sidebar-title">
+	<a href="README.html">Closure XML</a>
+      </div>
+      <div class="sidebar-main">
+      <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">Compilation</a></li>
+	    <li><a href="installation.html#tests">Tests</a></li>
+          </ul>
+	</li>
+        <li>
+          <ul class="hack">
+            <li>
+              <a href="quickstart.html"><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">Recoders</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="klacks.html">Klacks parser</a>
+          <ul class="hack">
+            <li><a href="klacks.html#parsing">Parsing incrementally</a></li>
+            <li><a href="klacks.html#sax">Bridging Klacks and SAX</a></li>
+          </ul>
+        </li>
+	<li>
+          <a href="dom.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>
+    </div>
+
+    <h1>Klacks parser</h1>
+    <p>
+      The Klacks parser provides an alternative parsing interface,
+      similar in concept to Java's <a
+      href="http://jcp.org/en/jsr/detail?id=173">Streaming API for
+      XML</a> (StAX).
+    </p>
+    <p>
+      It implements a streaming, "pull-based" API.  This is different
+      from SAX, which is a "push-based" model.
+    </p>
+    <p>
+      Klacks is implemented using the same code base as the SAX parser
+      and has the same parsing characteristics (validation, namespace
+      support, entity resolution) while offering a more flexible interface
+      than SAX.
+    </p>
+
+    <h3>Example</h3>
+    <p>
+      The following example illustrates creation of a klacks <tt>source</tt>,
+      use of the <tt>consume</tt> function to read individual events,
+      and shows some of the most common event types.
+    </p>
+    <pre>* <b>(defparameter *source* (cxml:make-source "&lt;example>text&lt;/example>"))</b>
+*SOURCE*
+* <b>(klacks:consume *source*)</b>
+:START-DOCUMENT
+* <b>(klacks:consume *source*)</b>
+:START-ELEMENT
+NIL                      ;namespace URI
+"example"                ;local name
+"example"                ;qualified name
+* <b>(klacks:consume *source*)</b>
+:CHARACTERS
+"text"
+* <b>(klacks:consume *source*)</b>
+:END-ELEMENT
+NIL
+"example"
+"example"
+* <b>(klacks:consume *source*)</b>
+:END-DOCUMENT
+* <b>(klacks:consume *source*)</b>
+NIL</pre>
+
+    <h3>Klacks sources</h3>
+    <p>
+      To parse using Klacks, create an XML <tt>source</tt> first.
+    </p>
+    <p>
+      <div class="def">Function CXML:MAKE-SOURCE (input &key validate
+      dtd root entity-resolver disallow-external-subset pathname)</div>
+      Create and return a source for <tt>input</tt>.
+    </p>
+    <p>
+      Exact behaviour depends on <tt>input</tt>, which can
+      be one of the following types:
+    </p>
+    <ul>
+      <li>
+	<tt>pathname</tt> -- a Common Lisp pathname.  
+	Open the file specified by the pathname and create a source for
+	the resulting stream.  See below for information on how to
+        close the stream.
+      </li>
+      <li><tt>stream</tt> -- a Common Lisp stream with element-type
+        <tt>(unsigned-byte 8)</tt>.  See below for information on how to
+        close the stream.
+      </li>
+      <li>
+	<tt>octets</tt> -- an <tt>(unsigned-byte 8)</tt> array.
+	The array is parsed directly, and interpreted according to the
+	encoding it specifies.
+      </li>
+      <li>
+	<tt>string</tt>/<tt>rod</tt> -- a rod (or <tt>string</tt> on
+	unicode-capable implementations).
+	Parses an XML document from the input string that has already
+	undergone external-format decoding.
+      </li>
+    </ul>
+    <p>
+      <b>Closing streams:</b> Sources can refer to Lisp streams that
+      need to be closed after parsing.  This includes a stream passed
+      explicitly as <tt>input</tt>, a stream created implicitly for the
+      <tt>pathname</tt> case, as well as any streams created
+      automatically for external parsed entities referred to by the
+      document.
+    </p>
+    <p>
+      All these stream get closed automatically if end of file is
+      reached normally.  Use <tt>klacks:close-source</tt> or
+      <tt>klacks:with-open-source</tt> to ensure that the streams get
+      closed otherwise.
+    </p>
+    <p>
+      <b>Keyword arguments</b> have the same meaning as with the SAX parser,
+      please refer to the documentation of <a
+      href="using.html#parser">parse-file</a> for more information:
+    </p>
+    <ul>
+      <li>
+        <tt>validate</tt>
+      </li>
+      <li>
+        <tt>dtd</tt>
+      </li>
+      <li><tt>root</tt>
+      </li>
+      <li>
+        <tt>entity-resolver</tt>
+      </li>
+      <li>
+        <tt>disallow-internal-subset</tt>
+      </li>
+    </ul>
+    <p>
+      In addition, the following argument is for types of <tt>input</tt>
+      other than <tt>pathname</tt>:
+    </p>
+    <ul>
+      <li>
+        <tt>pathname</tt> -- If specified, defines the base URI of the
+        document based on this pathname instance.
+      </li>
+    </ul>
+
+    <p>
+      Events are read from the stream using the following functions:
+    </p>
+    <p>
+      <div class="def">Function KLACKS:PEEK (source)</div>
+     <p> => :start-document<br/>
+          or => :start-document, version, encoding, standalonep<br/>
+          or => :dtd, name, public-id, system-id<br/>
+          or => :start-element, uri, lname, qname<br/>
+          or => :end-element, uri, lname, qname<br/>
+          or => :characters, data<br/>
+          or => :processing-instruction, target, data<br/>
+          or => :comment, data<br/>
+          or => :end-document, data<br/>
+          or => nil
+    </p>
+    <p>
+      <tt>peek</tt> returns the current event's key and main values.
+    </p>
+    <p>
+      <div class="def">Function KLACKS:CONSUME (source) => key, value*</div>
+    </p>
+    <p>
+      Return the same values <tt>peek</tt> would, and in addition
+      advance the source forward to the next event.
+    </p>
+    <p>
+      <div class="def">Function KLACKS:PEEK-VALUE (source) => value*</div>
+    </p>
+    <p>
+      Like <tt>peek</tt>, but return only the values, not the key.
+    </p>
+    <p>
+      <div class="def">Function KLACKS:CURRENT-URI (source) => uri</div>
+      <div class="def">Function KLACKS:CURRENT-LNAME (source) => string</div>
+      <div class="def">Function KLACKS:CURRENT-QNAME (source) => string</div>
+    </p>
+    <p>
+     If the current event is :start-element or :end-element, return the
+     corresponding value.  Else, signal an error.
+    </p>
+    <p>
+      <div class="def">Function KLACKS:CURRENT-CHARACTERS (source) => string</div>
+    </p>
+    <p>
+     If the current event is :characters, return the character data
+     value.  Else, signal an error.
+    </p>
+    <p>
+      <div class="def">Function KLACKS:CURRENT-CDATA-SECTION-P (source) => boolean</div>
+    </p>
+    <p>
+     If the current event is :characters, determine whether the data was
+     specified using a CDATA section in the source document.  Else,
+     signal an error.
+    </p>
+    <p>
+      <div class="def">Function KLACKS:MAP-ATTRIBUTES (fn source)</div>
+    </p>
+    <p>
+     Call <tt>fn</tt> for each attribute of the current start tag in
+     turn, and pass the following values as arguments to the function:
+	<ul>
+	  <li>namespace uri</li>
+	  <li>local name</li>
+	  <li>qualified name</li>
+	  <li>attribute value</li>
+	  <li>a boolean indicating whether the attribute was specified
+	  explicitly in the source document, rather than defaulted from
+	  a DTD</li>
+	</ul>
+     Only valid for :start-element.
+    </p>
+    <p>
+     Return a list of SAX attribute structures for the current start tag.
+     Only valid for :start-element.
+    </p>
+
+    <p>
+      <div class="def">Function KLACKS:CLOSE-SOURCE (source)</div>
+      Close all streams referred to by <tt>source</tt>.
+    </p>
+    <p>
+      <div class="def">Macro KLACKS:WITH-OPEN-SOURCE ((var source) &body body)</div>
+      Evaluate <tt>source</tt> to create a source object, bind it to
+      symbol <tt>var</tt> and evaluate <tt>body</tt> as an implicit progn.
+      Call <tt>klacks:close-source</tt> to close the source after
+      exiting <tt>body</tt>, whether normally or abnormally.
+    </p>
+  </body>
+</html>
diff --git a/doc/quickstart.html b/doc/quickstart.html
index 74a598d..e2ed18e 100644
--- a/doc/quickstart.html
+++ b/doc/quickstart.html
@@ -94,5 +94,22 @@
     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>
+
+    <p>Use klacks to read events from the parser incrementally.  The
+    following example looks only for :start-element and :end-element
+    events and prints them (<a href="klacks.html">read more</a>):</p>
+    <pre>* <b>(klacks:with-open-source
+    (s (cxml:make-source #p"example.xml"))
+  (loop
+      for key = (klacks:peek s)
+      while key
+      do
+	(case key
+	  (:start-element
+	    (format t "~A {" (klacks:current-qname s)))
+	  (:end-element
+	    (format t "}")))
+	(klacks:consume s)))</b>
+test {child {}}</pre>
   </body>
 </html>
diff --git a/klacks/klacks-impl.lisp b/klacks/klacks-impl.lisp
index 125ca3b..960bda4 100644
--- a/klacks/klacks-impl.lisp
+++ b/klacks/klacks-impl.lisp
@@ -249,6 +249,7 @@
 (defun klacks/eof (source input)
   (with-source (source current-key current-values)
     (p/eof input)
+    (klacks:close-source source)
     (setf current-key :end-document)
     (setf current-values nil)
     (lambda () (klacks/nil source))))
