Expat Module Function Reference

Synopsis

Instantiate a new Expat_Type object

Usage

Expat_Type xml_new()

Description

This function instantiates and returns an Expat_Type. The Expat_Type is an opaque type, but its internals can be accessed with the dot operator like in a structure:

.userdata

see xml_set_user_data

.startelementhandler

see xml_set_start_element_handler

.endelementhandler

see xml_set_end_element_handler

.characterdatahandler

see xml_set_character_data_handler

.defaulthandler

see xml_set_default_handler

The following properties do nothing unless the Expat parser was created with xml_new_ns:

.startnamespacedeclhandler

see xml_set_start_namespace_decl_handler

.endnamespacedeclhandler

see xml_set_end_namespace_decl_handler

The following properties are read-only and correspond to the C functions XML_GetErrorCode etc:

.errorcode

the error status of the parser. This will be ExpatError or a subclass thereof, not expat's internal error code.

.errorstring

the description of the error status.

.currentbyteindex

the byte offset of the position.

.currentline

the line number of the position. The first line is reported as 1.

.currentcolumn

the offset, from the beginning of the current line, of the position.

.parsingstatus

a struct {Int_Type parsing, Int_Type finalbuffer}. .parsing.parsingstatus can take on four values:

     XML_INITIALIZED
     XML_PARSING
     XML_FINISHED
     XML_SUSPENDED

.parsing.finalbuffer is one if the final buffer is being processed - that is, when xml_parse was called with the third argument 1.

See Also

xml_parse, xml_new_ns

Synopsis

Instantiate an Expat_Type object with namespace processing

Usage

Expat_Type xml_new_ns(Char_Type sep)

Description

Constructs a new parser that has namespace processing in effect. Namespace expanded element names and attribute names are returned as a concatenation of the namespace URI, sep, and the local part of the name. This means that you should pick a character for sep that can't be part of a legal URI.

See Also

xml_parse, xml_new

Synopsis

parse part of and xml document

Usage

xml_parse(Expat_Type p, String_Type s, Int_Type isFinal)

Description

Parse some more of the document. The string s is a buffer containing part (or perhaps all) of the document. The isFinal parameter informs the parser that this is the last piece of the document. Frequently, the last piece is empty (i.e. len is zero). If a parse error occurred, an ExpatError is thrown.

See Also

xml_new, xml_stop_parser

Synopsis

stop parsing

Usage

xml_stop_parser(Expat_Type p, Int_Type resumable)

Description

Stops parsing, causing xml_parse to return. Must be called from within a call-back handler, except when aborting (when resumable is 0) an already suspended parser.

See Also

xml_new, xml_resume_parser

Synopsis

resume parsing

Usage

xml_resume_parser(Expat_Type p)

Description

Resumes parsing after it has been suspended with xml_stop_parser. Must not be called from within a handler call-back.

See Also

xml_new, xml_stop_parser

Synopsis

set the start element handler

Usage

xml_set_start_element_handler(Expat_Type p, Ref_Type handler)

Description

Set the handler for start elements. The handler should have the prototype

  handler(p, name, atttributes)
  Expat_Type p;
  String_Type name;
  Array_Type[Struct_Type{name, value}] atttributes;

The handler can acces the parser's userdata with xml_get_user_data(p) or as p.userdata.

Notes

To unset the handler, set it to NULL

See Also

xml_new, xml_parse

Synopsis

set the end element handler

Usage

xml_set_end_element_handler(Expat_Type p, Ref_Type handler)

Description

Set the handler for end elements. The handler should have the prototype

  handler(p, name)
  Expat_Type p;
  String_Type name;

The handler can acces the parser's userdata with xml_get_user_data(p) or as p.userdata.

Notes

To unset the handler, set it to NULL

See Also

xml_new, xml_parse

Synopsis

set the start namespace_decl handler

Usage

xml_set_start_namespace_decl_handler(Expat_Type p, Ref_Type handler)

Description

Set a handler to be called when a namespace is declared. Namespace declarations occur inside start tags. But the namespace declaration start handler is called before the start tag handler for each namespace declared in that start tag. The handler should have the prototype

  handler(p, prefix, uri)
  Expat_Type p;
  String_Type  or NULL prefix;
  String_Type or NULL uri;

Notes

To unset the handler, set it to NULL

See Also

xml_new_ns, xml_parse

Synopsis

set the end namespace_decl handler

Usage

xml_set_end_namespace_decl_handler(Expat_Type p, Ref_Type handler)

Description

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 should have the prototype

  handler(p, prefix)
  Expat_Type p;
  String_Type or NULL prefix;

Notes

To unset the handler, set it to NULL

See Also

xml_new_ns, xml_parse

Synopsis

set the character data handler

Usage

xml_set_character_data_handler(Expat_Type p, Ref_Type handler)

Description

Set the handler for character data. The handler should have the prototype

  handler(p, data)
  Expat_Type p;
  String_Type data;

The handler can acces the parser's userdata with xml_get_user_data(p) or as p.userdata.

Notes

To unset the handler, set it to NULL

See Also

xml_new, xml_parse

Synopsis

set the character data handler

Usage

xml_set_default_handler(Expat_Type p, Ref_Type handler)

Description

Sets a handler for any characters in the document which wouldn't otherwise be handled. The handler should have the prototype

  handler(p, data)
  Expat_Type p;
  String_Type data;

Notes

To unset the handler, set it to NULL

See Also

xml_new, xml_parse

Synopsis

Set the user data associated with an XML parser

Usage

xml_set_user_data(Expat_Type p, AnyType data)

Description

This sets the user data pointer that gets passed to handlers.

See Also

xml_new, xml_get_user_data

Synopsis

Get the user data associated with an XML parser

Usage

AnyType xml_get_user_data(Expat_Type p)

Description

This gets the user data pointer that gets passed to handlers.

See Also

xml_new, xml_set_user_data