Addons/api/expat

From J Wiki
Jump to navigation Jump to search
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 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:

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