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, xml) | 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. |
| parsehtml (s) | Parse a well-formed HTML file as a string. |
| basic_parse (s, all_text, html) | 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 name
- attr 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 representation
- is_file whether text_or_file is a file name or not
- use_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 name
- attrs 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 attribute
- v 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 name
- items 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' <br> 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 cached
- data 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 name
- dont_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, xml)
-
pretty-print an XML document
Parameters:
- t an XML document
- idn an initial indent (indents are all strings)
- indent an indent for each level
- attr_indent if given, indent each attribute pair and put on a separate line
- xml force prefacing with default or custom <?xml…>
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 document
- strsubst an optional function for handling string copying which could do substitution, etc.
- compare (t1, t2)
-
compare two documents.
Parameters:
- t1 any value
- t2 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 document
- depth_first visit child notes first, then the current node
- operation a function which will receive the current tag name and current node.
- parsehtml (s)
-
Parse a well-formed HTML file as a string.
Tags are case-insenstive, DOCTYPE is ignored, and empty elements can be .. empty.
Parameters:
- s the HTML
- basic_parse (s, all_text, html)
-
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.
- html if true, uses relaxed HTML rules for parsing