The state of a parser is held in a parser_state structure.
It should be cleared before usage, i.e. all fields should be set to
zero. To parse some text, the following fields need to be set:
-
text: The text to be parsed.
-
maxtext: The length of the text. Note that this field
alone determines the text length and not a trailing zero byte.
-
char_width: Character width (can be one or two).
-
buffer: To retrieve the parsed components of a document
such as tag names or attribute values, this field needs to point to a
preallocated memory area. The character width is the same as for the input text.
-
maxbuffer: This field determines the maximum number of
characters in the buffer field.
XML Parsing
To capture parsing events and process the components of an XML
document, callback functions need to be set. They are called with the
current parser_state structure. Currently, the following
callbacks can be set:
-
element_callback: Gets called whenever a tag name in a
start and end tag has been encountered.
-
attrname_callback: Is called for attribute names.
-
attrval_callback: Is called after an attribute value
has been parsed.
-
word_callback: Gets called for every word between tags,
seperated by whitespace.
-
ws_callback: Handles whitespace (carriage returns,
linefeeds, tabulators and space characters).
The value of the parsed component (tag name, attribute name etc) can
be found in the buffer field of the
parser_state structure. It will be in the same format (i.e. character width) as the input text.
The parser is started by calling tox_parse. The parser
parses one character at a time, making interruptions of the parsing
process at any time possible. The parser structure can be used
repeatedly after calling tox_parse, e.g. parsing blocks of
data coming over a socket connection.
HTML Parsing
HTML parsing is supported if the code is compiled with the macro HTML defined. In HTML mode, tox is much more forgiving and accepts otherwise incorrect XML code.
