4.5 Expat Handlers

This section describes all available element handlers. For clarity, each handler is described in its own subsection. For each handler, we indicate a keyword that is used when registering this handler and the handler prototype.

To register handlers, use xml-make-parser or xml-set-handler functions. See section Creating XML Parsers, for a detailed discussion of these functions.

4.5.1 start-element-handler

Handler Keyword: #:start-element-handler

Sets handler for start (and empty) tags.

The handler must be defined as follows:

Handler prototype: start-element name attrs

Arguments:

name

Element name.

attrs

A list of element attributes. Each attribute is represented by a cons (‘car’ holds attribute name, ‘cdr’ holds its value).

4.5.2 end-element-handler

Handler Keyword: #:end-element-handler

Sets handler for end (and empty) tags. An empty tag generates a call to both start and end handlers (in that order).

The handler must be defined as follows:

Handler prototype: end-element name

Arguments:

name

Element name

4.5.3 character-data-handler

Handler Keyword: #:character-data-handler

Sets a text handler. A single block of contiguous text free of markup may result in a sequence of calls to this handler. So, if you are searching for a pattern in the text, it may be split across calls to this handler.

The handler itself is defined as:

Handler prototype: character-data text

Arguments:

text

The text.

4.5.4 processing-instruction-handler

Handler Keyword: #:processing-instruction-handler

Set a handler for processing instructions.

Handler prototype: processing-instruction target data

Arguments are:

target

First word in the processing instruction.

data

The rest of the characters in the processing instruction, after target and whitespace following it.

4.5.5 comment-handler

Handler Keyword: #:comment-handler

Sets a handler for comments.

Handler prototype: comment text
text

The text inside the comment delimiters.

4.5.6 start-cdata-section-handler

Handler Keyword: #:start-cdata-section-handler

Sets a handler that gets called at the beginning of a CDATA section.

The handler is defined as follows:

Handler prototype: start-cdata-section

4.5.7 end-cdata-section-handler

Handler Keyword: #:end-cdata-section-handler

Sets a handler that gets called at the end of a CDATA section.

The handler is defined as:

Handler prototype: end-cdata-section

4.5.8 default-handler

Handler Keyword: #:default-handler

Sets a handler for any characters in the document which wouldn't otherwise be handled. This includes both data for which no handlers can be set (like some kinds of DTD declarations) and data which could be reported but which currently has no handler set.

Handler prototype: default text
text

A string containing all non-handled characters, which are passed exactly as they were present in the input XML document except that they will be encoded in UTF-8 or UTF-16. Line boundaries are not normalized. Note that a byte order mark character is not passed to the default handler. There are no guarantees about how characters are divided between calls to the default handler: for example, a comment might be split between multiple calls. Setting the ‘default’ handler has the side effect of turning off expansion of references to internally defined general entities. Such references are passed to the default handler verbatim.

4.5.9 default-handler-expand

Handler Keyword: #:default-handler-expand

This sets a default handler as above, but does not inhibit the expansion of internal entity references. Any entity references are not passed to the handler.

The handler prototype is the same as in default-handler.

4.5.10 skipped-entity-handler

Handler Keyword: #:skipped-entity-handler

Set a skipped entity handler, i.e. a handler which is called if:

Handler prototype: skipped-entity entity-name parameter?

Arguments are:

entity-name

Name of the entity.

parameter?

This argument is #t if the entity is a parameter, and #f otherwise.

4.5.11 start-namespace-decl-handler

Handler Keyword: #:start-namespace-decl-handler

Set a handler to be called when a namespace is declared.

Handler prototype: start-namespace-decl prefix uri

Arguments:

prefix

Namespace prefix.

uri

Namespace URI.

4.5.12 end-namespace-decl-handler

Handler Keyword: #:end-namespace-decl-handler

Set a handler to be called when leaving the scope of a namespace declaration. This will be called, for each namespace declaration, after the handler for the end tag of the element in which the namespace was declared.

The handler prototype is:

Handler prototype: end-namespace-decl prefix

4.5.13 xml-decl-handler

Handler Keyword: #:xml-decl-handler

Sets a handler that is called for XML declarations and also for text declarations discovered in external entities.

Handler prototype: xml-decl version encoding . detail

Arguments:

version

Version specification (string), or #f, for text declarations.

encoding

Encoding. May be #f.

detail

Unspecified’, if there was no standalone parameter in the declaration. Otherwise, #t or #f depending on whether it was given as ‘yes’ or ‘no’.

4.5.14 start-doctype-decl-handler

Handler Keyword: #:start-doctype-decl-handler

Set a handler that is called at the start of a ‘DOCTYPE’ declaration, before any external or internal subset is parsed.

Handler prototype: start-doctype-decl name sysid pubid   has-internal-subset?

Arguments:

name

Declaration name.

sysid

System ID. May be #f.

pubid

Public ID. May be #f.

has-internal-subset?

#t if the ‘DOCTYPE’ declaration has an internal subset, #f otherwise.

4.5.15 end-doctype-decl-handler

Handler Keyword: #:end-doctype-decl-handler

Set a handler that is called at the end of a ‘DOCTYPE’ declaration, after parsing any external subset.

The handler takes no arguments:

Handler prototype: end-doctype-decl

4.5.16 attlist-decl-handler

Handler Keyword: #:attlist-decl-handler

Sets a handler for ‘attlist’ declarations in the DTD. This handler is called for each attribute, which means, in particular, that a single attlist declaration with multiple attributes causes multiple calls to this handler.

The handler prototype is:

Handler prototype: attlist-decl el-name att-name att-type detail

Argument:

el-name

Name of the element for which the attribute is being declared.

att-name

Attribute name.

detail

Default value, if el-name is a ‘#FIXED’ attribute, #t, if it is a ‘#REQUIRED’ attribute, and #f, if it is a ‘#IMPLIED’ attribute.

4.5.17 entity-decl-handler

Handler Keyword: #:entity-decl-handler

Sets a handler that will be called for all entity declarations.

Handler prototype: entity-decl name param? value base sys-id pub-id   notation

Arguments:

name

Entity name.

param?

For parameter entities, #t. Otherwise, #f.

value

For internal entities, entity value. Otherwise, #f.

base

Base.

sys-id

System ID. For internal entities – #f.

pub-id

Public ID. For internal entities – #f.

notation

Notation name, for unparsed entity declarations. Otherwise, #f. Unparsed are entity declarations that have a notation (‘NDATA’) field, such as:

 
<!ENTITY logo SYSTEM "images/logo.gif" NDATA gif>

4.5.18 notation-decl-handler

Handler Keyword: #:notation-decl-handler

Sets a handler that receives notation declarations.

Handler prototype is:

Handler prototype: notation-decl notation-name base   system-id public-id

4.5.19 not-standalone-handler

Handler Keyword: #:not-standalone-handler

Sets a handler that is called if the document is not standalone, i.e. when there is an external subset or a reference to a parameter entity, but does not have ‘standalone’ set to "yes" in an XML declaration.

The handler takes no arguments:

Handler prototype: not-standalone