xml/sax
streaming (SAX) XML parsing over expat.
Since: 0.1.0
ParseOpts
(defstruct ParseOpts [])
limits and switches for one parse.
default-parse-opts
(default-parse-opts :)
the safe defaults.
ParseOpts
(sax-parse-file-opts "big.xml" (with (default-parse-opts) [max-bytes 0]) h)
Since: 0.1.0
SaxParser
(defstruct SaxParser :copy [raw : XmlSaxRaw handler : (fn [SaxEvent])
a push parser: a C parser plus the handler it feeds.
xml-backend-version
(xml-backend-version :)
the linked expat's version string.
cstr -- static, e.g. "expat_2.9.0".
(println (xml-backend-version))
Since: 0.1.0
sax-parse-string-opts
(sax-parse-string-opts [src : cstr opts : ParseOpts h : (fn [SaxEvent])
stream the events of an in-memory document.
| src | the document (UTF-8, or any encoding its XML declaration names | |
| that expat knows: UTF-8, UTF-16, ISO-8859-1, US-ASCII) | ||
| opts | limits and switches | |
| h | called once per event; return (Continue) or (Stop) |
(Result nil ParseError) -- ok when the document was well-formed or the handler stopped early; err (with every event before the error already delivered) otherwise.
(sax-parse-string-opts src (with (default-parse-opts) [namespaces false])
(fn [e : SaxEvent] : SaxControl (Continue)))
Since: 0.1.0
sax-parse-string
(sax-parse-string [src : cstr h : (fn [SaxEvent])
stream the events of an in-memory document with the
| src | the document | |
| h | called once per event; return (Continue) or (Stop) |
(Result nil ParseError)
(let [^mut n 0]
(sax-parse-string "<a><b/><b/></a>"
(fn [e : SaxEvent] : SaxControl
(match e
(StartElement name _) (do (set! n (+ n 1)) (Continue))
_ (Continue))))
n) ; => 3
Since: 0.1.0
sax-parse-file-opts
(sax-parse-file-opts [path : cstr opts : ParseOpts h : (fn [SaxEvent])
stream the events of a file, 64 KiB at a time.
| path | the file to parse | |
| opts | limits and switches | |
| h | called once per event |
(Result nil ParseError) -- an Io error when the file cannot be opened.
(sax-parse-file-opts "dump.xml" (with (default-parse-opts) [max-bytes 0]) h)
Since: 0.1.0
sax-parse-file
(sax-parse-file [path : cstr h : (fn [SaxEvent])
stream the events of a file with the safe defaults.
| path | the file to parse | |
| h | called once per event |
(Result nil ParseError)
(sax-parse-file "feed.xml" h)
Since: 0.1.0
sax-parser-new-opts
(sax-parser-new-opts [opts : ParseOpts h : (fn [SaxEvent])
a push parser with explicit options.
| opts | limits and switches | |
| h | called once per event as chunks are fed |
(Result SaxParser ParseError) -- err only when out of memory.
(sax-parser-new-opts (default-parse-opts) h)
Since: 0.1.0
sax-parser-new
(sax-parser-new [h : (fn [SaxEvent])
a push parser with the safe default options.
| h | called once per event as chunks are fed |
(Result SaxParser ParseError) -- err only when out of memory.
(match (sax-parser-new h)
(Ok p) (do (sax-feed! p "<a>") (sax-feed! p "</a>") (sax-finish! p)
(sax-parser-free p))
(Err e) ...)
Since: 0.1.0
sax-feed!
(sax-feed! [p : SaxParser chunk : cstr] :)
feed the next chunk of input and deliver its events.
| p | the push parser | |
| chunk | the next bytes (a NUL-terminated cstr) |
(Result nil ParseError) -- err once the input seen so far is malformed; every later call returns the same error.
(sax-feed! p "<item>he") (sax-feed! p "llo</item>")
Since: 0.1.0
sax-finish!
(sax-finish! [p : SaxParser] :)
signal the end of input and deliver the last events.
| p | the push parser |
(Result nil ParseError)
(sax-finish! p)
Since: 0.1.0
sax-parser-free
(sax-parser-free [p : SaxParser] :)
release a push parser.
| p | the parser, not used afterwards |
(sax-parser-free p)
Since: 0.1.0
Internal definitions
XmlSaxRaw-- internal: the C parser state (c/xml/turxml.c).__new-raw-- internal: allocate the C parser (NULL on OOM).__null?-- internal: is this a null pointer?__free-- internal: release the C parser.__set-string-- internal: parse `src` (borrowed for the parse).__set-file-- internal: parse a file; 0 or -1 (Io error recorded).__pump-- internal: feed the next source chunk; 1 more, 0 done, -1 error.__feed-- internal: feed a caller's chunk; 0 ok, -1 error.__next-- internal: advance to the next queued event; its kind or 0.__stop-- internal: the handler said Stop.__ev-name-- internal: the current event's name / target.__ev-text-- internal: the current event's text / PI data.__ev-pubid-- internal: doctype public id, or NULL.__ev-sysid-- internal: doctype system id, or NULL.__ev-nattrs-- internal: attribute count of the current start tag.__ev-attr-name-- internal: i-th attribute name.__ev-attr-value-- internal: i-th attribute value.__null-cstr?-- internal.__err-kind-- internal: the recorded ParseErrorKind ordinal.__err-msg-- internal: the recorded message (borrowed).__err-line-- internal.__err-col-- internal.__kind-of-- internal: ParseErrorKind from its ordinal.__error-- internal: the recorded error as a ParseError (msg copied).__oom-- internal: the error for a parser that could not be allocated.__id-string-- internal: a doctype identifier, the empty String if absent.__attrs-acc-- internal: the current start tag's attributes, built from__event-- internal: the current queued event as a SaxEvent.__deliver-- internal: hand every queued event to the handler. Returns__deliver-chunk-- internal: deliver one chunk's events inside a region.__run-- internal: pump the configured source to the end.__make-- internal: a C parser for these options, or none on OOM.__push-- internal: feed one chunk (or the end) and deliver its events.