# 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 "<nodes>alice</nodes>" > = d <nodes>alice</nodes> > = xml.tostring(d,'',' ') <nodes> alice </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 (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.3 Last updated Tue, 18 Aug 2015 11:21:53 +0200