Module pl.xml
XML LOM Utilities.
This implements some useful things on LOM documents, such as returned by lxp.lom.parse.
In particular, it can convert LOM back into XML text, with optional pretty-printing control.
It is s based on stanza.lua from Prosody
> d = xml.parse "<nodes><node id='1'>alice</node></nodes>"
> = d
<nodes><node id='1'>alice</node></nodes>
> = xml.tostring(d,'',' ')
<nodes>
<node id='1'>alice</node>
</nodes>
Can be used as a lightweight one-stop-shop for simple XML processing; a simple XML parser is included
but the default is to use lxp.lom if it can be found.
Prosody IM Copyright © 2008-2010 Matthew Wild Copyright © 2008-2010 Waqas Hussain— classic Lua XML parser by Roberto Ierusalimschy. modified to output LOM format. http://lua-users.org/wiki/LuaXmlSee the Guide
Dependencies: pl.utils
Soft Dependencies: lxp.lom (fallback is to use basic Lua parser)
Functions
| new (tag, attr) | create a new document node. |
| parse (text_or_file, is_file, use_basic) | parse an XML document. |
| Doc:addtag (tag, attrs) | convenient function to add a document node, This updates the last inserted position. |
| Doc:text (text) | convenient function to add a text node. |
| Doc:up () | go up one level in a document |
| Doc:add_direct_child (child) | append a child to a document directly. |
| Doc:add_child (child) | append a child to a document at the last element added |
| Doc:set_attribs (t) | set attributes of a document node. |
| Doc:set_attrib (a, v) | set a single attribute of a document node. |
| Doc:get_attribs () | access the attributes of a document node. |
| elem (tag, items) | function to create an element with a given tag name and a set of children. |
| tags (list) | given a list of names, return a number of element constructors. |
| Doc.subst (templ, data) | create a substituted copy of a document, |
| Doc:child_with_name (tag) | get the first child with a given tag name. |
| Doc:get_elements_with_name (tag, dont_recurse) | get all elements in a document that have a given tag. |
| Doc:childtags () | iterate over all child elements of a document node. |
| Doc:maptags (callback) | visit child element of a node and call a function, possibility modifying the document. |
| tostring (t, idn, indent, attr_indent) | pretty-print an XML document |
| Doc:get_text () | get the full text value of an element |
| clone (doc, strsubst) | make a copy of a document |
| compare (t1, t2) | compare two documents. |
| is_tag (d) | is this value a document element? |
| walk (doc, depth_first, operation) | call the desired function recursively over the document. |
| basic_parse (s, all_text) | Parse a simple XML document using a pure Lua parser based on Robero Ierusalimschy’s original version. |
Functions
- new (tag, attr)
-
create a new document node.
Parameters:
tag: the tag nameattr: optional attributes (table of name-value pairs)
- parse (text_or_file, is_file, use_basic)
-
parse an XML document. By default, this uses lxp.lom.parse, but
falls back to basic_parse, or if use_basic is true
Parameters:
text_or_file: file or string representationis_file: whether text_or_file is a file name or notuse_basic: do a basic parse
Returns:
- a parsed LOM document with the document metatatables set
- nil, error the error can either be a file error or a parse error
- Doc:addtag (tag, attrs)
-
convenient function to add a document node, This updates the last inserted position.
Parameters:
tag: a tag nameattrs: optional set of attributes (name-string pairs)
- Doc:text (text)
-
convenient function to add a text node. This updates the last inserted position.
Parameters:
text: a string
- Doc:up ()
- go up one level in a document
- Doc:add_direct_child (child)
-
append a child to a document directly.
Parameters:
child: a child node (either text or a document)
- Doc:add_child (child)
-
append a child to a document at the last element added
Parameters:
child: a child node (either text or a document)
- Doc:set_attribs (t)
-
set attributes of a document node.
Parameters:
t: a table containing attribute/value pairs
- Doc:set_attrib (a, v)
-
set a single attribute of a document node.
Parameters:
a: attributev: its value
- Doc:get_attribs ()
- access the attributes of a document node.
- elem (tag, items)
-
function to create an element with a given tag name and a set of children.
Parameters:
tag: a tag nameitems: either text or a table where the hash part is the attributes and the list part is the children.
- tags (list)
-
given a list of names, return a number of element constructors.
Parameters:
list: a list of names, or a comma-separated string.
Usage:
local parent,children = doc.tags 'parent,children'
doc = parent {child 'one', child 'two'} - Doc.subst (templ, data)
-
create a substituted copy of a document,
Parameters:
templ: may be a document or a string representation which will be parsed and cacheddata: a table of name-value pairs or a list of such tables
Returns:
-
an XML document
- Doc:child_with_name (tag)
-
get the first child with a given tag name.
Parameters:
tag: the tag name
- Doc:get_elements_with_name (tag, dont_recurse)
-
get all elements in a document that have a given tag.
Parameters:
tag: a tag namedont_recurse: optionally only return the immediate children with this tag name
Returns:
-
a list of elements
- Doc:childtags ()
- iterate over all child elements of a document node.
- Doc:maptags (callback)
-
visit child element of a node and call a function, possibility modifying the document.
Parameters:
callback: a function passed the node (text or element). If it returns nil, that node will be removed. If it returns a value, that will replace the current node.
- tostring (t, idn, indent, attr_indent)
-
pretty-print an XML document
Parameters:
t: an XML documentidn: an initial indent (indents are all strings)indent: an indent for each levelattr_indent: if given, indent each attribute pair and put on a separate line
Returns:
-
a string representation
- Doc:get_text ()
- get the full text value of an element
- clone (doc, strsubst)
-
make a copy of a document
Parameters:
doc: the original documentstrsubst: an optional function for handling string copying which could do substitution, etc.
- compare (t1, t2)
-
compare two documents.
Parameters:
t1: any valuet2: any value
- is_tag (d)
-
is this value a document element?
Parameters:
d: any value
- walk (doc, depth_first, operation)
-
call the desired function recursively over the document.
Parameters:
doc: the documentdepth_first: visit child notes first, then the current nodeoperation: a function which will receive the current tag name and current node.
- basic_parse (s, all_text)
-
Parse a simple XML document using a pure Lua parser based on Robero Ierusalimschy’s original version.
Parameters:
s: the XML document to be parsed.all_text: if true, preserves all whitespace. Otherwise only text containing non-whitespace is included.