Klacks parser

The Klacks parser provides an alternative parsing interface, similar in concept to Java's Streaming API for XML (StAX).

It implements a streaming, "pull-based" API. This is different from SAX, which is a "push-based" model.

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.

Example

The following example illustrates creation of a klacks source, use of the consume function to read individual events, and shows some of the most common event types.

* (defparameter *source* (cxml:make-source "<example>text</example>"))
*SOURCE*
* (klacks:consume *source*)
:START-DOCUMENT
* (klacks:consume *source*)
:START-ELEMENT
NIL                      ;namespace URI
"example"                ;local name
"example"                ;qualified name
* (klacks:consume *source*)
:CHARACTERS
"text"
* (klacks:consume *source*)
:END-ELEMENT
NIL
"example"
"example"
* (klacks:consume *source*)
:END-DOCUMENT
* (klacks:consume *source*)
NIL

Klacks sources

To parse using Klacks, create an XML source first.

Function CXML:MAKE-SOURCE (input &key validate dtd root entity-resolver disallow-external-subset pathname)

Create and return a source for input.

Exact behaviour depends on input, which can be one of the following types:

pathname -- 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.
stream -- a Common Lisp stream with element-type (unsigned-byte 8). See below for information on how to close the stream.
octets -- an (unsigned-byte 8) array. The array is parsed directly, and interpreted according to the encoding it specifies.
string/rod -- a rod (or string on unicode-capable implementations). Parses an XML document from the input string that has already undergone external-format decoding.

Closing streams: Sources can refer to Lisp streams that need to be closed after parsing. This includes a stream passed explicitly as input, a stream created implicitly for the pathname case, as well as any streams created automatically for external parsed entities referred to by the document.

All these stream get closed automatically if end of file is reached normally. Use klacks:close-source or klacks:with-open-source to ensure that the streams get closed otherwise.

Keyword arguments have the same meaning as with the SAX parser, please refer to the documentation of parse-file for more information:

validate
dtd
root
entity-resolver
disallow-internal-subset

In addition, the following argument is for types of input other than pathname:

pathname -- If specified, defines the base URI of the document based on this pathname instance.

Events are read from the stream using the following functions:

Function KLACKS:PEEK (source)

=> :start-document
or => :start-document, version, encoding, standalonep
or => :dtd, name, public-id, system-id
or => :start-element, uri, lname, qname
or => :end-element, uri, lname, qname
or => :characters, data
or => :processing-instruction, target, data
or => :comment, data
or => :end-document, data
or => nil

peek returns the current event's key and main values.

Function KLACKS:CONSUME (source) => key, value*

Return the same values peek would, and in addition advance the source forward to the next event.

Function KLACKS:PEEK-VALUE (source) => value*

Like peek, but return only the values, not the key.

Function KLACKS:CURRENT-URI (source) => uri

Function KLACKS:CURRENT-LNAME (source) => string

Function KLACKS:CURRENT-QNAME (source) => string

If the current event is :start-element or :end-element, return the corresponding value. Else, signal an error.

Function KLACKS:CURRENT-CHARACTERS (source) => string

If the current event is :characters, return the character data value. Else, signal an error.

Function KLACKS:CURRENT-CDATA-SECTION-P (source) => boolean

If the current event is :characters, determine whether the data was specified using a CDATA section in the source document. Else, signal an error.

Function KLACKS:MAP-ATTRIBUTES (fn source)

Call fn for each attribute of the current start tag in turn, and pass the following values as arguments to the function:

namespace uri
local name
qualified name
attribute value
a boolean indicating whether the attribute was specified explicitly in the source document, rather than defaulted from a DTD

Only valid for :start-element.

Return a list of SAX attribute structures for the current start tag. Only valid for :start-element.

Function KLACKS:CLOSE-SOURCE (source)

Close all streams referred to by source.

Macro KLACKS:WITH-OPEN-SOURCE ((var source) &body body)

Evaluate source to create a source object, bind it to symbol var and evaluate body as an implicit progn. Call klacks:close-source to close the source after exiting body, whether normally or abnormally.