Penlight

• Index

Contents

• Functions

Modules

• pl
• pl.Date
• pl.List
• pl.Map
• pl.MultiMap
• pl.OrderedMap
• pl.Set
• pl.app
• pl.array2d
• pl.class
• pl.comprehension
• pl.config
• pl.data
• pl.dir
• pl.file
• pl.func
• pl.input
• pl.lapp
• pl.lexer
• pl.luabalanced
• pl.operator
• pl.path
• pl.permute
• pl.pretty
• pl.seq
• pl.sip
• pl.strict
• pl.stringio
• pl.stringx
• pl.tablex
• pl.template
• pl.test
• pl.text
• pl.utils
• pl.xml

Topics

• 01-introduction.md
• 02-arrays.md
• 03-strings.md
• 04-paths.md
• 05-dates.md
• 06-data.md
• 07-functional.md
• 08-additional.md
• 09-discussion.md

Examples

• seesubst.lua
• sipscan.lua
• symbols.lua
• test-cmp.lua
• test-data.lua
• test-listcallbacks.lua
• test-pretty.lua
• test-symbols.lua
• testapp.lua
• testclone.lua
• testconfig.lua
• testglobal.lua
• testinputfields.lua
• testinputfields2.lua
• testxml.lua
• which.lua

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)	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 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' 

  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)

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

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.

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.