xparser - Lua XML Parser

Introduction

xparser reads XML in chunks and calls Lua functions as it encounters elements, text, and other XML content. Use it to process a stream without first building a table for the whole document. For a table representation, see xml2table.lua. See also the JSON API.

The parser accepts UTF-8, including an optional leading UTF-8 byte order mark. It accepts XML 1.0 in UTF-8 only. It checks the DOCTYPE header and internal-subset boundaries, but does not validate DTD declaration bodies, apply default attributes, expand declared entities, or load external resources. Parameter-entity references between declarations are rejected. Namespace-qualified names pass to callbacks without namespace resolution.

Implementation

Create a parser with xparser.create(), feed it nonempty strings with parser:parse(), call parser:finish() after the last chunk, and call parser:destroy() to release it. The parser is a userdata object. It also supports automatic cleanup through Lua's garbage collector and to-be-closed variables.

Successful parsing returns true, complete. The boolean complete becomes true when the root element has closed. A successful call with complete == false needs more input. Comments and processing instructions can follow the root element. Call parser:finish() after all input has arrived: it also detects an incomplete trailing comment, processing instruction, or UTF-8 sequence. Root completion alone does not check those cases. There is no end-of-document callback.

Malformed XML and errors raised inside callbacks are reported as return values. Incorrect API use, such as a wrong argument type or calling a destroyed parser, throws a Lua error. Each function below lists its own throw conditions. As with other Lua APIs, memory exhaustion in Lua allocations can also raise a Lua error; the listed programmer-error checks are separate from that runtime condition.

Constructor

xparser.create([handlers [, context [, textmode]]])

Create an independent parser. If supplied, the INIT handler runs during this call.

Parameters

Return values

Throws

Throws if handlers is supplied without being a table, a recognized handler is neither a function nor nil, or textmode is not one of the supported strings. INIT exceptions are caught, logged through the BAS error handler, and returned as nil plus a string message.

Parser methods

In each method below, parser is the userdata returned by xparser.create(). The colon supplies this receiver as the first argument. Do not call parse, finish, reset, or destroy on a parser from one of that same parser's callbacks, or from a finalizer while an operation on that parser is active. Read-only methods remain available inside callbacks.

parser:parse(data)

Process the next input chunk. Handlers run synchronously on the Lua stack that calls this method.

Parameters

Return values

After a parsing error or callback interruption, reset the parser before using it for another document. Input after the interruption has not been consumed. Custom callback results can resemble the normal result shapes; choose distinguishable results if your caller needs to tell them apart.

Throws

Throws for an invalid or destroyed parser, a data argument that cannot be read as a Lua string, or a call from the same parser's callback. Malformed XML does not throw. Exceptions raised in handlers are caught and returned as described above.

parser:finish()

Declare the end of input after the last parse call. This checks for a complete document, including any trailing comments or processing instructions. It does not invoke handlers.

Parameters

None beyond the parser receiver.

Return values

After success or failure, call reset before parsing another document. A callback that stops parsing also requires reset; finish cannot validate the unconsumed input after that callback.

Throws

Throws for an invalid or destroyed parser, or an operation already active on the same parser.

parser:reset([full])

Reset the parser for another document, preserving the installed handlers, context, and textmode. If installed, RESET runs before the internal state is cleared.

Parameters

Return values

Throws

Throws for an invalid or destroyed parser, or a call from the same parser's callback. Exceptions in RESET are caught.

parser:destroy()

Release the native parser and call TERM if installed. Repeated calls are harmless. The same cleanup is used by the __gc and __close metamethods.

Parameters

None beyond the parser receiver.

Return values

None. TERM return values are discarded.

Throws

Throws for an invalid receiver or a call from the same parser's callback. An already destroyed parser does not cause an error. Exceptions in TERM are caught and logged; cleanup continues and destroy does not return the error.

parser:count()

Parameters

None beyond the parser receiver.

Return values

Throws

Throws for an invalid or destroyed parser.

parser:line()

Parameters

None beyond the parser receiver.

Return values

Throws

Throws for an invalid or destroyed parser.

parser:col()

Parameters

None beyond the parser receiver.

Return values

Throws

Throws for an invalid or destroyed parser.

parser:depth()

Parameters

None beyond the parser receiver.

Return values

Throws

Throws for an invalid or destroyed parser.

parser:has_doc()

Parameters

None beyond the parser receiver.

Return values

Throws

Throws for an invalid or destroyed parser.

tostring(parser)

Parameters

Return values

Throws

The parser's __tostring implementation throws if directly called with an invalid receiver. Converting a valid or destroyed parser does not report an operational error.

Parser state

The userdata has no documented writable fields. Use the methods above to read its state and supply application state through context. The binding does not expose init, get_state, get_pos, get_depth, get_context, or get_events methods. Use count, line, col, and depth for position and nesting information; create another parser to install different handlers or a different textmode.

Event handlers

All handlers are optional functions stored under the exact event names below. Each receives context as its first argument, even when context is nil. The parser object is not passed as an argument. Keep a reference in your context or closure if a handler needs to call a read-only parser method.

Callbacks run inside the initiating create, parse, reset, or destroy call and cannot yield. The binding catches and logs Lua errors raised by handlers, including attempts to yield or to call parse, finish, reset, or destroy on the same parser. The initiating method determines how the caught error is returned, as documented above.

Event names and values

In the parameter tables, attributes is a new table containing string keys mapped to string values, plus integer keys 1 through n listing the attribute names in input order. qname is the element name as written, including any namespace prefix. All text and name arguments are Lua strings.

Lifecycle handlers

INIT(context)

Called during construction, before parsing.

Parameters

Return values

Throws

An exception raised by your handler is caught and logged; create returns nil and a string message.

RESET(context)

Called by reset before parser state is cleared. The full argument is not forwarded.

Parameters

Return values

Throws

An exception raised by your handler is caught and logged; reset returns nil and a string message and still clears the parser state.

TERM(context)

Called during destruction, including automatic cleanup. Use it to release resources held by your context.

Parameters

Return values

Throws

An exception raised by your handler is caught and logged. Destruction continues; no error value is returned.

XML handlers

START(context)

Called before consuming the first character after construction or reset. It receives no attributes argument.

Parameters

Return values

Throws

An exception raised by your handler is caught and logged; parse returns nil and a string message.

XML(context, attributes)

Called for an XML declaration.

Parameters

Return values

Throws

An exception raised by your handler is caught and logged; parse returns nil and a string message.

START_ELEMENT(context, qname, attributes)

Called after a nonempty opening tag.

Parameters

Return values

Throws

An exception raised by your handler is caught and logged; parse returns nil and a string message.

END_ELEMENT(context, qname)

Called after a closing tag.

Parameters

Return values

Throws

An exception raised by your handler is caught and logged; parse returns nil and a string message.

EMPTY_ELEMENT(context, qname, attributes)

Called for a self-closing tag such as <item/>. It replaces separate START_ELEMENT and END_ELEMENT calls for that tag.

Parameters

Return values

Throws

An exception raised by your handler is caught and logged; parse returns nil and a string message.

TEXT(context, text)

Called for text between tags. A single element can produce several text events when other content separates its text.

Parameters

Return values

Throws

An exception raised by your handler is caught and logged; parse returns nil and a string message.

CDATA(context, text)

Called for a CDATA section.

Parameters

Return values

Throws

An exception raised by your handler is caught and logged; parse returns nil and a string message.

COMMENT(context, text)

Called for an XML comment.

Parameters

Return values

Throws

An exception raised by your handler is caught and logged; parse returns nil and a string message.

PI(context, name, body)

Called for a processing instruction other than the XML declaration.

Parameters

Return values

Throws

An exception raised by your handler is caught and logged; parse returns nil and a string message.

Sample event handlers

Read a document in chunks

-- Keep application state in context; callback arguments do not include the parser.
local context = {names = {}}
local parser, err = xparser.create({
   START_ELEMENT = function(ctx, name)
      ctx.names[#ctx.names + 1] = name
   end,
   EMPTY_ELEMENT = function(ctx, name)
      ctx.names[#ctx.names + 1] = name
   end
}, context)
assert(parser, err) -- This example treats initialization failure as fatal.

for _, chunk in ipairs({"<root>", "<item/></root>"}) do
   local ok, result = parser:parse(chunk)
   if not ok then
      parser:destroy()
      error(result) -- The caller chooses to throw; parse returned the error.
   end
end
local ok, err = parser:finish() -- Also checks incomplete trailing syntax.
parser:destroy()
assert(ok, err)
print(table.concat(context.names, ", ")) -- root, item

Convert XML to a table

The xml2table Lua module provides a handler table for xparser. It builds a document table and returns "DONE", document when the root closes. It is separate from the C binding and must be available in the installed Lua resources.

Parameters

Use the module table as the handlers argument to xparser.create. The module's INIT handler creates a context table when context is nil; an explicitly supplied context must be a table.

Return values

Throws

The parse method has the same programmer-error checks as parser:parse. Module callback exceptions are caught by the binding. Loading the module with require can throw if the module is unavailable.

The completed document and element tables have the following fields:

-- The module supplies callbacks; no global xml2table variable is installed.
local handlers = require("xml2table")
local parser, err = xparser.create(handlers)
assert(parser, err)
local status, document = parser:parse("<root><item>value</item></root>")
parser:destroy()
assert(status == "DONE", document)
print(document.elements.root.elements.item.text) -- value

Lua libraries required

The xparser binding is registered by BAS. The optional xml2table module uses the standard string and table libraries.