Addons/api/expat
User Guide | Installation | Development | Categories | Git | Build Log
The api/expat addon provides a J interface to the expat xml parser.
Typical use might start with:
require'api/expat'
coinsert'jexpat'
as the addon defines names in the jexpat locale and expects to work with callbacks in a locale which inherits from the jexpat
locale.
Generally speaking, the expat api is a sequential interface, exposing a small piece of the xml document at a time, rather than presenting the entire document as an array. This allows programmers to deal with the semi-structured character of xml, focusing on the heuristics or patterns specifically related to the documents of interest.
High level interface
expat_parse_xml
initializes and parses an xml document (its y
argument), handing control to four callback verbs which are expected to be defined in the current locale (which is expected to inherit from the jexpat
locale):
expat_initx
a monadic verb which runs at the start of xml processing. Initialize your globals here.expat_start_elementx
a dyad which runs each time an xml open tag is encountered.expat_end_elementx
a monadic verb which runs each time an xml close tag is encountered.expat_parse_xmlx
a monadic verb which runs after processing an xml document and which creates the result ofexpat_parse_xml
Generally speaking, the y argument to these verbs should be ignored.
The x argument to expat_start_elementx
is a three element boxed list:
- The name of the element
- a boxed list containing the names of the element's attributes
- a boxed list containing the names of the element's attributes' values
Also, expat_characterData
contains raw character data which was encountered before the current callback.
Low level verbs
"Low level verbs" are lightweight covers for the underlying expat library:
- Parser Creation Functions
XML_ParserCreate
XML_ParserFree
- Parsing Functions
XML_Parse
XML_StopParser
- Handler Setting Functions
XML_SetElementHandler
XML_SetCharacterDataHandler
- Parse Position and Error Reporting Functions
XML_GetErrorCode
XML_ErrorString
XML_GetCurrentLineNumber
XML_GetCurrentColumnNumber
The addon also defines some constants for use with the above verbs,
Specifically, it defines the truth values:
XML_FALSE XML_TRUE
And, it also defines three return codes:
XML_STATUS_ERROR XML_STATUS_OK XML_STATUS_SUSPENDED