LuaSOAP: SOAP interface to the Lua programming language

LuaSOAP Reference Manual

SOAP interface to the Lua programming language

home · introduction · soap elements · basic · client · examples · related docs

Introduction

LuaSOAP is a Lua library to ease the use of SOAP. It enables a Lua program to:

Encode and decode SOAP messages without having to deal directly with XML code

LuaSOAP provides a very simple API and an abstraction layer over XML avoiding manipulation of string representation of data structures.

LuaSOAP is based on LuaExpat and on Lua 5.0.
The abstraction layer over HTTP depends on LuaSocket 2.0.

SOAP elements

SOAP elements are always represented by Lua tables except strings. A SOAP 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 tag with the element's name;
a special optional field called attr with 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 SOAP element (a Lua table following these same rules).

Attributes

The special field attr is a Lua table that stores the SOAP 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 the table.

Basic support

The file soap.lua implements all basic support for encoding and decoding SOAP messages. There are two functions:

encode (namespace, element_name, entries, headers*) => envelope
Builds a SOAP document containing a SOAP-Envelope element. It receives two strings with the namespace (an URI) and the SOAP-element's name and, as the third argument, a table with zero or more SOAP elements. An optional fourth argument can be used to generate the SOAP Header (it must be a SOAP element too). The result is a string containing the SOAP document.
decode (method_response) => namespace, element_name, elements
Disassembles a SOAP document into Lua objects. It receives a string containing the SOAP document. The result are the namespace (string), the SOAP-element's name (string) and a table with the contents of the SOAP Body. Each element of this table can be a string or a SOAP element.

Client side

The file soap.http.lua implements a simple stand-alone client based on LuaSocket 2.0. The following function is provided:

call (url, namespace, element_name, entries, headers*)
It encapsulates the call of encode and decode over a connection to an HTTP server. The result is the same as decode function: the namespace (string), the SOAP-element's name (string) and a table with the contents of the SOAP Body.

Examples

Client example

Below is a small sample code displaying the use of the library in a client application.

require "soap/http"
local ns, meth, ent = soap.http.call ("http://soap.4s4c.com/ssss4c/soap.asp", "http://simon.fell.com/calc", "doubler", {
        {
            tag = "nums",
            attr = {
                ["xmlns:SOAP-ENC"] = "http://schemas.xmlsoap.org/soap/encoding/",
                ["SOAP-ENC:arrayType"] = "xsd:int[5]",
            },
            { tag = "number", 10 },
            { tag = "number", 20 },
            { tag = "number", 30 },
            { tag = "number", 50 },
            { tag = "number", 100 },
        },
    })
print("namespace = ", ns, "element name = ", meth)
for i, elem in ipairs (ent[1]) do print (elem[1]) end