Stanza
The stanza module provides several methods for building and manipulating stanza objects.
Utility functions
All of these functions create and return a new stanza object, on which you can call various methods, and which you may convert to a string of XML at any time with tostring(mystanza).
stanza(name, attr)
Creates a new stanza, with the specified name and attributes (attributes are standard key→value tables).
message(attr)
Helper for creating message stanzas, equivalent to stanza(“message”, attr).
presence(attr)
Helper for creating presence stanzas, equivalent to stanza(“presence”, attr).
iq(attr)
Helper for creating iq stanzas, equivalent to stanza(“iq”, attr).
Stanza objects
Properties
name
The name of the top tag of this object.
attr
A table of attributes for this object.
Numeric indexes
Every stanza object is itself an array of its child nodes, with strings for text nodes and stanza objects for child tags. Iterating over the children should be done using the children() method.
tags
An array that contains only the child tags of this stanza (i.e. excluding text nodes). Searching for specific tags should be done using the get_child() method. Iterating over the tags should be done with the childtags() method.
Putting these all together, a simple example:
print("You have received a"..mystanza.name.."stanza from"..mystanza.attr.from..".") print("It contains "..#mystanza.." child nodes, "..#mystanza.tags.." of which are tags.");
Methods
stanza:tag(name, attr)
Inserts a child tag with the specified name and attributes to the stanza.
Calls can be chained, for example:
local my_message = stanza.message({to = "myfriend@example.com", type = "chat" }) :tag("body"):text("Hello there!") print(my_message)
would produce:
<message to='myfriend@example.com' type='chat'> <body>Hello there!</body> </message>
stanza:children()
Returns an iterator for all the object's immediate children, which are either of type “string” (text nodes) or “table” (child tags, also valid stanza objects).
The iterator can be used with Lua's generic 'for' loop like so:
for childnode in mystanza:children() do print(childnode) end
stanza:childtags()
Like :children() also returns an iterator, but one that only iterates over child tags, and not text nodes.
stanza:get_child(name, xmlns)
Retrieves the first child tag that matches the given name and xmlns. If xmlns is nil or not given then it defaults to the current stanza object's xmlns.
message = stanza.message({ xmlns = "jabber:client" }) :tag("body"):text("Hello world"):up() :tag("delay", { xmlns = "urn:xmpp:delay", stamp = "2002-09-10T23:08:25Z" }) print("Body is:", message:get_child("body"):get_text()) print("Timestamp is:", message:get_child("delay", "urn:xmpp:delay").attr.stamp)
Returns nil if no matching tags are found.
Examples
Building a stanza
This example XML (taken from XEP-0092):
<iq type='result' to='romeo@montague.net/orchard' from='juliet@capulet.com/balcony' id='version_1'> <query xmlns='jabber:iq:version'> <name>Prosody</name> <version>0.5.1</version> <os>Ubuntu</os> </query> </iq>
Would be expressed in Lua as:
stanza.iq({ type = "result", to = "romeo@montague.net/orchard", from = "juliet@capulet.com/balcony", id = "version_1" }) :tag("query", { xmlns = "jabber:iq:version" }) :tag("name"):text("Prosody"):up() :tag("version"):text("0.4.0"):up() :tag("os"):text("Ubuntu"):up()
We also have a small command-line Lua script for converting any given XML to its Lua counterpart. It reads in XML and prints out the equivalent Lua representation. You can download it here, and simply run it with 'lua stanzaconv.lua'.