You are looking at historical revision 20425 of this page. It may differ significantly from its current revision.
Oleg Kiselyov's XML parser.
See the official SSAX homepage for comprehensive documentation.
ssax:xml->sxml[procedure] (ssax:xml->sxml PORT NAMESPACE-PREFIX-ASSIG)
This procedure reads XML data from PORT and returns an SXML representation. NAMESPACE-PREFIX-ASSIG is an alist that maps user prefixes (symbols) to namespaces (URI strings).
ssax:make-parser[syntax] (ssax:make-parser TAG1 PROC1 [TAG2 PROC2 ...])
Create a custom XML parser; an instance of the XML parsing framework. This will be a SAX, a DOM or a specialized parser depending on the supplied user-handlers.
The arguments to ssax::make-parser are type/procedure pairs, interleaved in the argument list. In other words, TAG1, TAG2 etc are unquoted(!) symbols that identify the type of procedure that follows the tag; see below for the list of allowed tags.
The output of this macro is a procedure that represents a parser which accepts two arguments, PORT and SEED. PORT is the port from which to read the XML data and SEED is the initial value of an accumulator that will be passed into the first procedure, where it can be appended to and returned. Then this value will be passed on to the next procedure and so on to eventually obtain a result, in a FOLD-like fashion.
Given below are tags and signatures of the corresponding procedures. Not all tags have to be specified. If some are omitted, reasonable defaults will apply. SEED always represents the current value of the accumulator that will eventually be returned by the parser.
- Tag: DOCTYPE
- Handler-procedure: PORT DOCNAME SYSTEMID INTERNAL-SUBSET? SEED
If INTERNAL-SUBSET? is #t, the current position in the port is right after we have read #\[ that begins the internal DTD subset. We must finish reading of this subset before we return (or must call ssax:skip-internal-dtd if we aren't interested in reading it).
The port at exit must be at the first symbol after the whole DOCTYPE declaration. The handler-procedure must generate four values:
ELEMS ENTITIES NAMESPACES SEED
See xml-decl::elems for ELEMS. It may be #f to switch off the validation. NAMESPACES will typically contain user prefixes for selected URI symbols. The default handler-procedure skips the internal subset, if any, and returns (values #f '() '() SEED).
- Tag: UNDECL-ROOT
- Handler-procedure: ELEM-GI SEED
ELEM-GI is an UNRES-NAME of the root element. This procedure is called when an XML document under parsing contains no DOCTYPE declaration. The handler-procedure, as a DOCTYPE handler procedure above, must generate four values:
ELEMS ENTITIES NAMESPACES SEED
The default handler-procedure returns (values #f '() '() seed)
- Tag: NEW-LEVEL-SEED
- Handler-procedure: ELEM-GI ATTRIBUTES NAMESPACES EXPECTED-CONTENT SEED
See ssax:make-elem-parser NEW-LEVEL-SEED.
- Tag: FINISH-ELEMENT
- Handler-procedure: ELEM-GI ATTRIBUTES NAMESPACES PARENT-SEED SEED
See ssax:make-elem-parser FINISH-ELEM.
- Tag: CHAR-DATA-HANDLER
- Handler-procedure: STRING1 STRING2 SEED
See ssax:make-elem-parser CHAR-DATA-HANDLER.
- Tag: PI
- Handler-procedure: PORT PI-TAG SEED
See ssax:make-pi-parser. The default value is '().
ssax:make-pi-parser[syntax] (ssax:make-pi-parser PI-HANDLERS)
Create a parser to parse and process one Processing Instruction (PI) element. PI-HANDLERS is an alist (PI-TAG . PI-HANDLER) where PI-TAG is the name of the processing instruction and PI-HANDLER is a procedure PORT PI-TAG SEED.
The handler should read the rest of the PI from PORT, up to and including the combination "?>" that terminates the PI. The handler should return a new seed.
One of the PI-TAGs may be the symbol *DEFAULT*. The corresponding handler will handle PIs that no other handler will. If the *DEFAULT* PI-TAG is not specified, ssax:make-pi-parser will assume the default handler that skips the body of the PI.
ssax:make-elem-parser[syntax] (ssax:make-elem-parser NEW-LEVEL-SEED FINISH-ELEM CHAR-DATA-HANDLER PI-HANDLERS)
Create a parser to parse and process one element, including its character content or children elements. The parser is typically applied to the root element of a document.
The generated parser is a
procedure START-TAG-HEAD PORT ELEMS ENTITIES NAMESPACES PRESERVE-WS? SEED
procedure ELEM-GI ATTRIBUTES NAMESPACES EXPECTED-CONTENT SEED
where ELEM-GI is a RES-NAME of the element about to be processed. This procedure is to generate the seed to be passed to handlers that process the content of the element.
procedure ELEM-GI ATTRIBUTES NAMESPACES PARENT-SEED SEED
This procedure is called when parsing of ELEM-GI is finished. The SEED is the result from the last content parser (or from new-level-seed if the element has the empty content). PARENT-SEED is the same seed as was passed to new-level-seed. The procedure is to generate a seed that will be the result of the element parser.
CHAR-DATA-HANDLER A string handler.
procedure STRING1 STRING2 SEED
The procedure is supposed to handle a chunk of character data STRING1 followed by a chunk of character data STRING2. STRING2 is a short string, often "\n" and even "" Returns a new SEED.
xml-token-kind[syntax] (xml-token-kind TOKEN)
Returns the TAG-KIND of the supplied TOKEN.
- TAG-KIND A symbol 'START, 'END, 'PI, 'DECL, 'COMMENT, 'CDSECT or 'ENTITY-REF that identifies a markup token.
xml-token-head[syntax] (xml-token-head TOKEN) =>
Returns the UNRES-NAME of the supplied TOKEN. For xml-tokens of kinds 'COMMENT and 'CDSECT, the head is #f.
- UNRES-NAME A name (called GI in the XML Recommendation) as given in an xml document for a markup token: start-tag, PI target, attribute name. If a GI is an NCName, UNRES-NAME is this NCName converted into a Scheme symbol. If a GI is a QName, UNRES-NAME is a pair of symbols: (PREFIX . LOCALPART).
ssax:xml->sxml will convert numeric entities to UTF-8 byte sequences. It does not depend on the utf8 egg for this.
Otherwise, UTF-8 operation is not well tested.
Oleg Kiselyov, with some Chicken-specific modifications by Kirill Lisovsky. Minor changes by felix winkelmann to make the code suitable as an extension library.
- 5.0.0 Port to Chicken 4; fresh import of the clean upstream CVS tree (which now has downcased names)
- 4.9.8 Convert numeric entities > 255 to UTF-8 [Jim Ursetto]
- 4.9.7 Using ##sys#read/peek-char instead of read/peek-char [Daishi Kato]
- 4.9.6 parser-error now raises a condition [Daishi Kato]
- 4.9.5 Fixed bug in error-reporting function
- 4.9.4 Replaced (apply string-append ...) calls with string-concatenate
- 4.9.3 Adapted to new setup scheme. Fixed a reentrancy-bug [Thanks to Bruce Butterfield]
- 4.9.2 SSAX:warn adds newline [Thanks to Sunnan]
- 4.9.1 Fixed exports for case-sensitivity.