Update of /project/cxml/cvsroot/cxml/doc In directory clnet:/tmp/cvs-serv3570/doc
Modified Files: html.xsl klacks.xml Log Message: find-element, find-event
--- /project/cxml/cvsroot/cxml/doc/html.xsl 2007/02/18 15:27:30 1.2 +++ /project/cxml/cvsroot/cxml/doc/html.xsl 2007/02/18 16:46:32 1.3 @@ -58,7 +58,9 @@ <a href="klacks.html">Klacks parser</a> <ul class="sub"> <li><a href="klacks.html#sources">Parsing incrementally</a></li> + <li><a href="klacks.html#convenience">Convenience functions</a></li> <li><a href="klacks.html#klacksax">Bridging Klacks and SAX</a></li> + <li><a href="klacks.html#klacksax">Examples</a></li> </ul> </li> <li> --- /project/cxml/cvsroot/cxml/doc/klacks.xml 2007/02/18 15:27:30 1.3 +++ /project/cxml/cvsroot/cxml/doc/klacks.xml 2007/02/18 16:46:32 1.4 @@ -16,34 +16,9 @@ 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. + See below for <a href="#examples">examples</a>. </p> - <pre>* <b>(defparameter *source* (cxml:make-source "<example>text</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>
<a name="sources"/> <h3>Parsing incrementally using sources</h3> @@ -161,11 +136,11 @@ <tt>peek</tt> returns the current event's key and main values. </p> <p> - <div class="def">Function KLACKS:CONSUME (source) => key, value*</div> + <div class="def">Function KLACKS:PEEK-NEXT (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. + Advance the source forward to the next event and returns it + like <tt>peek</tt> would. </p> <p> <div class="def">Function KLACKS:PEEK-VALUE (source) => value*</div> @@ -174,6 +149,13 @@ Like <tt>peek</tt>, but return only the values, not the key. </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: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> @@ -231,11 +213,124 @@ exiting <tt>body</tt>, whether normally or abnormally. </p>
+ <a name="convenience"/> + <h3>Convenience functions</h3> + <p> + <div class="def">Function KLACKS:FIND-EVENT (source key)</div> + Read events from <tt>source</tt> and discard them until an event + of type <i>key</i> is found. Return values like <tt>peek</tt>, or + NIL if no such event was found. + </p> + <p> + <div class="def">Function KLACKS:FIND-ELEMENT (source &optional + lname uri)</div> + Read events from <tt>source</tt> and discard them until an event + of type :start-element is found with matching local name and + namespace uri is found. If <tt>lname</tt> is <tt>nil</tt>, any + tag name matches. If <tt>uri</tt> is <tt>nil</tt>, any + namespace matches. Return values like <tt>peek</tt> or NIL if no + such event was found. + </p> + <a name="klacksax"/> <h3>Bridging Klacks and SAX</h3> <p> + <div class="def">Function KLACKS:SERIALIZE-EVENT (source handler)</div> + Send the current klacks events from <tt>source</tt> as a SAX + events to the SAX <tt>handler</tt> and consume it. + </p> + <p> + <div class="def">Function KLACKS:SERIALIZE-ELEMENT (source handler + &key document-events)</div> + Read all klacks events from the following <tt>:start-element</tt> to + its <tt>:end-element</tt> and send them as SAX events + to <tt>handler</tt>. When this function is called, the current + event must be <tt>:start-element</tt>, else an error is + signalled. With <tt>document-events</tt> (the default), + <tt>sax:start-document</tt> and <tt>sax:end-document</tt> events + are sent around the element. + </p> + <p> <div class="def">Function KLACKS:SERIALIZE-SOURCE (source handler)</div> Read all klacks events from <tt>source</tt> and send them as SAX events to the SAX <tt>handler</tt>. </p> + + <a name="examples"/> + <h3>Examples</h3> + <p> + The following example illustrates creation of a klacks <tt>source</tt>, + use of the <tt>peek-next</tt> function to read individual events, + and shows some of the most common event types. + </p> + <pre>* <b>(defparameter *source* (cxml:make-source "<example>text</example>"))</b> +*SOURCE* + +* <b>(klacks:peek-next *source*)</b> +:START-DOCUMENT + +* <b>(klacks:peek-next *source*)</b> +:START-ELEMENT +NIL ;namespace URI +"example" ;local name +"example" ;qualified name + +* <b>(klacks:peek-next *source*)</b> +:CHARACTERS +"text" + +* <b>(klacks:peek-next *source*)</b> +:END-ELEMENT +NIL +"example" +"example" + +* <b>(klacks:peek-next *source*)</b> +:END-DOCUMENT + +* <b>(klacks:peek-next *source*)</b> +NIL</pre> + + <p> + In this example, <tt>find-element</tt> is used to skip over the + uninteresting events until the opening <tt>child1</tt> tag is + found. Then <tt>serialize-element</tt> is used to generate SAX + events for the following element, including its children, and an + xmls-compatible list structure is build from those + events. <tt>find-element</tt> skips over whitespace, + and <tt>find-event</tt> is used to parse up + to <tt>:end-document</tt>, ensuring that the source has been + closed. + </p> + <pre>* <b>(defparameter *source* + (cxml:make-source "<example> + <child1><p>foo</p></child1> + <child2 bar='baz'/> + </example>"))</b> +*SOURCE* + +* <b>(klacks:find-element *source* "child1")</b> +:START-ELEMENT +NIL +"child1" +"child1" + +* <b>(klacks:serialize-element *source* (cxml-xmls:make-xmls-builder))</b> +("child1" NIL ("p" NIL "foo")) + +* <b>(klacks:find-element *source*)</b> +:START-ELEMENT +NIL +"child2" +"child2" + +* <b>(klacks:serialize-element *source* (cxml-xmls:make-xmls-builder))</b> +("child2" (("bar" "baz"))) + +* <b>(klacks:find-event *source* :end-document)</b> +:END-DOCUMENT +NIL +NIL +NIL +</pre> </documentation>