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/LuaXml
 
See 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:

  1. a parsed LOM document with the document metatatables set
  2. 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
generated by LDoc 1.4.6 Last updated 2017-07-18 16:28:41