4.2 Creating XML Parsers

Gamma provides several functions for creating and modifying XML parsers. The xml-primitive-make-parser and xml-primitive-set-handler are lower level interfaces, provided for those who wish to further extend Gamma functionality. Higher level interfaces are xml-make-parser and xml-set-handler which we recommend for regular users.

Scheme procedure: xml-primitive-make-parser enc sep

Return a new XML parser. If enc is given, it must be one of: ‘US-ASCII’, ‘UTF-8’, ‘UTF-16’, ‘ISO-8859-1’. If sep is given, the returned parser has namespace processing in effect. In that case, sep is a character which is used as a separator between the namespace URI and the local part of the name in returned namespace element and attribute names.

Scheme procedure: xml-set-encoding parser enc

Set the encoding to be used by the parser. The latter must be a value returned from a previous call to xml-primitive-make-parser or xml-make-parser.

The sequence:

 
  (let ((parser (xml-primitive-make-parser)))
    (xml-set-encoding parser encoding)
    …
   

is equivalent to:

 
  (let ((parser (xml-primitive-make-parser encoding)))
   …

and to:

 
  (let ((parser (xml-make-parser encoding)))
   …
Scheme procedure: xml-primitive-set-handler parser key handler

Set XML handler for an event. Arguments are:

parser

A valid XML parser

key

A key, identifying the event. For example, ‘#:start-element-handler’ sets handler which is called for start tags.

See section Expat Handlers, for its values and their meaning.

handler

Handler procedure.

Scheme function: xml-set-handler parser args…

Sets several handlers at once. Optional arguments (args) are constructed of keywords (as described in see handler-keyword), followed by their arguments, for example:

 
(xml-set-handler parser
      #:start-element-handler elt-start
      #:end-element-handler elt-end)
Scheme function: xml-make-parser [enc [sep]] args…

Create a parser and set its handlers. Optional enc and sep have the same meaning as in xml-primitive-make-parser. The rest of arguments define handlers for the new parser. They must be supplied in pairs: a keyword (as described in see handler-keyword), followed by its argument. For example:

 
(xml-make-parser "US-ASCII"
      #:start-element-handler elt-start
      #:end-element-handler elt-end)

This call creates a new parser for documents in ‘US-ASCII’ encoding and sets two handlers: for element start and for element end. This call is equivalent to:

 
(let ((p (xml-primitive-make-parser "US-ASCII")))
   (xml-primitive-set-handler p #:start-element-handler elt-start)
   (xml-primitive-set-handler p #:end-element-handler elt-end)
   …