Addons/api/expat

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 of expat_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:

0. The name of the element
1. a boxed list containing the names of the element's attributes
2. 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