Module pl.xml

XML LOM Utilities.

This implements some useful things on [LOM](http://matthewwild.co.uk/projects/luaexpat/lom.html) 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](http://hg.prosody.im/trunk/file/4621c92d2368/util/stanza.lua)

> d = xml.parse "alice" > = d alice > = xml.tostring(d,'',' ') alice

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 (C) 2008-2010 Matthew Wild
 Copyright (C) 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

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 2022-04-25 14:03:04