slaxml

SLAXML is a pure-Lua SAX-like streaming XML parser. It is more robust than many (simpler) pattern-based parsers that exist (such as mine), properly supporting code like <expr test="5 > 7" />, CDATA nodes, comments, namespaces, and processing instructions.
It is currently not a truly valid XML parser, however, as it allows certain XML that is syntactically-invalid (not well-formed) to be parsed without reporting an error.
Features
Pure Lua in a single file (two files if you use the DOM parser).
Streaming parser does a single pass through the input and reports what it sees along the way.
Supports processing instructions (<?foo bar?>).
Supports comments (<!-- hello world -->).
Supports CDATA sections (<![CDATA[ whoa <xml> & other content as text ]]>).
Supports namespaces, resolving prefixes to the proper namespace URI (<foo xmlns="bar"> and <wrap xmlns:bar="bar"><bar:kittens/></wrap>).
Supports unescaped greater-than symbols in attribute content (a common failing for simpler pattern-based parsers).
Unescapes named XML entities (&lt; &gt; &amp; &quot; &apos;) and numeric entities (e.g. &#10;) in attributes and text nodes (but—properly—not in comments or CDATA). Properly handles edge cases like &#38;amp;.
Optionally ignore whitespace-only text nodes (as appear when indenting XML markup).
Includes a DOM parser that is both a convenient way to pull in XML to use as well as a nice example of using the streaming parser.
Does not add any keys to the global namespace.
Usage
1
local SLAXML = require 'slaxml'
2
​
3
local myxml = io.open('my.xml'):read('*all')
4
​
5
-- Specify as many/few of these as you like
6
parser = SLAXML:parser{
7
  startElement = function(name,nsURI,nsPrefix)       end, -- When "<foo" or <x:foo is seen
8
  attribute    = function(name,value,nsURI,nsPrefix) end, -- attribute found on current element
9
  closeElement = function(name,nsURI)                end, -- When "</foo>" or </x:foo> or "/>" is seen
10
  text         = function(text)                      end, -- text and CDATA nodes
11
  comment      = function(content)                   end, -- comments
12
  pi           = function(target,content)            end, -- processing instructions e.g. "<?yes mon?>"
13
}
14
​
15
-- Ignore whitespace-only text nodes and strip leading/trailing whitespace from text
16
-- (does not strip leading/trailing whitespace from CDATA)
17
parser:parse(myxml,{stripWhitespace=true})
Copied!
If you just want to see if it will parse your document correctly, you can simply do:
1
local SLAXML = require 'slaxml'
2
SLAXML:parse(myxml)
Copied!
…which will cause SLAXML to use its built-in callbacks that print the results as they are seen.
DOM Builder
If you simply want to build tables from your XML, you can alternatively:
1
local SLAXML = require 'slaxdom' -- also requires slaxml.lua; be sure to copy both files
2
local doc = SLAXML:dom(myxml)
Copied!
The returned table is a 'document' composed of tables for elements, attributes, text nodes, comments, and processing instructions. See the following documentation for what each supports.
DOM Table Features
Document - the root table returned from the SLAXML:dom() method.
doc.type : the string "document"
doc.name : the string "#doc"
doc.kids : an array table of child processing instructions, the root element, and comment nodes.
doc.root : the root element for the document
Element
someEl.type : the string "element"
someEl.name : the string name of the element (without any namespace prefix)
someEl.nsURI : the namespace URI for this element; nil if no namespace is applied
someEl.attr : a table of attributes, indexed by name and index
local value = someEl.attr['attribute-name'] : any namespace prefix of the attribute is not part of the name
local someAttr = someEl.attr[1] : an single attribute table (see below); useful for iterating all attributes of an element, or for disambiguating attributes with the same name in different namespaces
someEl.kids : an array table of child elements, text nodes, comment nodes, and processing instructions
someEl.el : an array table of child elements only
someEl.parent : reference to the parent element or document table
Attribute
someAttr.type : the string "attribute"
someAttr.name : the name of the attribute (without any namespace prefix)
someAttr.value : the string value of the attribute (with XML and numeric entities unescaped)
someAttr.nsURI : the namespace URI for the attribute; nil if no namespace is applied
someAttr.parent : reference to the owning element table
Text - for both CDATA and normal text nodes
someText.type : the string "text"
someText.name : the string "#text"
someText.value : the string content of the text node (with XML and numeric entities unescaped for non-CDATA elements)
someText.parent : reference to the parent element table
Comment
someComment.type : the string "comment"
someComment.name : the string "#comment"
someComment.value : the string content of the attribute
someComment.parent : reference to the parent element or document table
Processing Instruction
someComment.type : the string "pi"
someComment.name : the string name of the PI, e.g. <?foo …?> has a name of "foo"
someComment.value : the string content of the PI, i.e. everything but the name
someComment.parent : reference to the parent element or document table
Finding Text for a DOM Element
The following function can be used to calculate the "inner text" for an element:
1
function elementText(el)
2
  local pieces = {}
3
  for _,n in ipairs(el.kids) do
4
    if n.type=='element' then pieces[#pieces+1] = elementText(n)
5
    elseif n.type=='text' then pieces[#pieces+1] = n.value
6
    end
7
  end
8
  return table.concat(pieces)
9
end
10
​
11
local xml  = [[<p>Hello <em>you crazy <b>World</b></em>!</p>]]
12
local para = SLAXML:dom(xml).root
13
print(elementText(para)) --> "Hello you crazy World!"
Copied!
A Simpler DOM
If you want the DOM tables to be simpler-to-serialize you can supply the simple option via:
1
local dom = SLAXML:dom(myXML,{ simple=true })
Copied!
In this case no table will have a parent attribute, elements will not have the el collection, and the attr collection will be a simple array (without values accessible directly via attribute name). In short, the output will be a strict hierarchy with no internal references to other tables, and all data represented in exactly one spot.
Known Limitations / TODO
Does not require or enforce well-formed XML. Certain syntax errors are silently ignored and consumed. For example:
foo="yes & no" is seen as a valid attribute
<foo></bar> invokes startElement("foo") followed by closeElement("bar")
<foo> 5 < 6 </foo> is seen as valid text contents
No support for custom entity expansion other than the standard XML entities (&lt; &gt; &quot; &apos; &amp;) and numeric entities (e.g. &#10; or &#x3c;)
XML Declarations (<?xml version="1.x"?>) are incorrectly reported as Processing Instructions
No support for DTDs
No support for extended (Unicode) characters in element/attribute names
No support for charset
No support for XInclude​
Does not ensure that the reserved xml prefix is never redefined to an illegal namespace
Does not ensure that the reserved xmlns prefix is never used as an element prefix
History
v0.7 2014-Sep-26
Decodes entities above 127 as UTF8 (decimal and hexadecimal).
The encoding specified by the document is (still) ignored. If you parse an XML file encoded in some other format, that intermixes 'raw' high-byte characters with high-byte entities, the result will be a broken encoding.
v0.6.1 2014-Sep-25
Fixes Issue #6, adding support for ASCII hexadecimal entities (e.g. &#x3c;). (Thanks Leorex/Ben Bishop)
v0.6 2014-Apr-18
Fixes Issue #5 (and more): Namespace prefixes defined on element are now properly applied to the element itself and any attributes using them when the definitions appear later in source than the prefix usage. (Thanks Oliver Kroth.)
The streaming parser now supplies the namespace prefix for elements and attributes.
v0.5.3 2014-Feb-12
Fixes Issue #3: The reserved xml prefix may be used without pre-declaring it. (Thanks David Durkee.)
v0.5.2 2013-Nov-7
Lua 5.2 compatible
Parser now errors if it finishes without finding a root element, or if there are unclosed elements at the end. (Proper element pairing is not enforced by the parser, but is—as in previous releases—enforced by the DOM builder.)
v0.5.1 2013-Feb-18
<foo xmlns="bar"> now directly generates startElement("foo","bar") with no post callback for namespace required.
v0.5 2013-Feb-18
Use the local SLAXML=require 'slaxml' pattern to prevent any pollution of the global namespace.
v0.4.3 2013-Feb-17
Bugfix to allow empty attributes, i.e. foo=""
closeElement no longer includes namespace prefix in the name, includes the nsURI
v0.4 2013-Feb-16
DOM adds .parent references
SLAXML.ignoreWhitespace is now :parse(xml,{stripWhitespace=true})
"simple" mode for DOM parsing
v0.3 2013-Feb-15
Support namespaces for elements and attributes
<foo xmlns="barURI"> will call startElement("foo",nil) followed by namespace("barURI") (and then attribute("xmlns","barURI",nil)); you must apply the namespace to your element after creation.
Child elements without a namespace prefix that inherit a namespace will receive startElement("child","barURI")
<xy:foo> will call startElement("foo","uri-for-xy")
<foo xy:bar="yay"> will call attribute("bar","yay","uri-for-xy")
Runtime errors are generated for any namespace prefix that cannot be resolved
Add (optional) DOM parser that validates hierarchy and supports namespaces
v0.2 2013-Feb-15
Supports expanding numeric entities e.g. &#34; -> "
Utility functions are local to parsing (not spamming the global namespace)
v0.1 2013-Feb-7
Option to ignore whitespace-only text nodes
Supports unescaped > in attributes
Supports CDATA
Supports Comments
Supports Processing Instructions
License
Copyright © 2013 Gavin Kistner​
Licensed under the MIT License. See LICENSE.txt for more details.

Bundled Extensions - Previous

semver

Next - CommandPost API

Last modified 6mo ago