- Encode and decode SOAP messages without having to deal directly with XML code
- Invoke remote Web Services without having to deal directly with SOAP messages
LuaSOAP provides a very simple API and an abstraction layer over XML avoiding manipulation of string representation of data structures.
LuaSOAP is a Lua library composed by a main module (
and some extensions:
The main module must be copied to your
package.path and the
other two files to a
soap directory in your
LuaSOAP elements are always represented by Lua tables except strings. A LuaSOAP element is a table of the form defined by the Lua Object Model from the LuaExpat library. The table has the following characteristics:
- a special field called
tagwith the element's name;
- a special optional field called
attrwith the element's attributes (see next section);
- the element's children are stored at the array-part of the table. A child could be an ordinary string or a LuaSOAP element (a Lua table following these same rules).
The special field
attr is a Lua table that stores
the LuaSOAP element's attributes as pairs
<key>=<value>. To assure an order (if
necessary), the sequence of keys should be placed at the
array-part of that table.
This documentation provides a detailed example which shows some common use cases.
Escaping and special characters
Since LuaSOAP 3.0, the library took the responsibility to escape data
inside LuaSOAP elements (
entries field of soap envelope; see
function soap.encode below).
Therefore, XML special characters such as
> are automatically converted to the corresponding XML
This documentation provides examples which show some common use cases.
soap implements all basic support for
encoding and decoding SOAP messages. There are two functions:
encode(args) => envelope
Builds a SOAP document containing a
SOAP-Envelopeelement. It receives a table with the following fields:
namespacea string with an URI indicating the namespace (
xmlns) atribute of the request,
methoda string with the method's name,
entriesan array (a table with numeric keys) of LuaSOAP elements,
header(optional) a table of headers (
soap:Headerelement; a LuaSOAP element too),
soapversion(optional; default = 1.1) a number with the SOAP version (currently supported versions are 1.1 and 1.2),
internal_namespace(optional; default = "") a string with the `internal' namespace (
The function can raise errors in case the
argstable is mal formed.
decode (method_response) => namespace, method_name, elements
Disassembles a SOAP document into Lua objects. It receives a string containing the SOAP document. The results are: the namespace (string), the SOAP-element method's name (string) and a table with the contents of the SOAP Body. Each element of the
elementstable can be a string or a LuaSOAP element.
soap.client implements a stand-alone client
which works over HTTP and is based on LuaSocket 2.0.
The following function is provided:
call (args) => namespace, method_name, elements
It encapsulates the call of
decodeover a connection to an HTTP server, thus the arguments are passed to the
encodefunction and the results received from the
decodefunction. It receives a table with the following fields:
urla string with the URL of the service (the protocol should be
https, which requires the load of LuaSec's
soapactiona string with the value of the
encoding(optional; default = "") a string with the text encoding (usually
- other arguments to the
decodefunction: the namespace (string), the SOAP-element method's name (string) and a table with the contents of the SOAP Body.
LuaSOAP client module was designed to work over HTTP (via LuaSocket's
socket.http module) and HTTPS (via LuaSec's
In fact, it could be used over other protocols since they provide
soap.client.call function inspects the URL to check
what protocol the SOAP message is supposed to be transfered upon.
Then, it looks for a function called
request at the
soap.client.protocol (where protocol is a
table which has an entry called
request which is a
function with the same signature of
Thus, the support fot HTTPS can be enabled by a program with the following lines:
local soap_client = require"soap.client" soap_client.https = require"ssl.https"
By following this approach, one could extend LuaSOAP to use another protocol
by implementing a function equivalent to LuaSocket's