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.
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.
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.
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.
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.
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.
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.
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.
Parameters
None beyond the parser receiver.
Return values
Throws
Throws for an invalid or destroyed parser.
Parameters
None beyond the parser receiver.
Return values
Throws
Throws for an invalid or destroyed parser.
Parameters
None beyond the parser receiver.
Return values
Throws
Throws for an invalid or destroyed parser.
Parameters
None beyond the parser receiver.
Return values
Throws
Throws for an invalid or destroyed parser.
Parameters
None beyond the parser receiver.
Return values
Throws
Throws for an invalid or destroyed 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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
-- 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
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
The xparser binding is registered by BAS. The optional xml2table module uses the standard string and table libraries.