Lua XML-RPC
XML-RPC interface to the Lua programming language

Introduction

Lua XML-RPC is a Lua library that can be used to build XML-RPC clients and servers. It enables a Lua program to:

  • Encode and decode XML-RPC messages without handling XML code
  • Transform Lua data structures into XML-RPC data types and vice-versa

Lua XML-RPC provides a simple API and an abstraction layer over XML avoiding manipulation of string representation of data structures.

Lua XML-RPC is based on LuaExpat and on Lua 5.1. The abstraction layer over HTTP depends on LuaSocket 2.0.2.

Installation

Lua XML-RPC is composed by three Lua files:

init.lua
Main source file providing the API
http.lua
API to call XML-RPC via HTTP
server.lua
Server side API

These files should be copied to a directory named xmlrpc created in your LUA_PATH.

Lua XML-RPC follows the package model for Lua 5.1, therefore it should be "installed". Refer to Compat-5.1 configuration section about how to install the module.

Data types

XML-RPC elements are usually represented by the simplest correspondent Lua object. When the correspondance is not obvious, a Lua table is used with a field specifying the element.

From XML-RPC to Lua

When converting from XML-RPC element to a Lua data item or table, a table with a field tag is used. The child elements are stored at numbered indexes and white space is ignored.

XML-RPC data type(s) Lua object
double
int
i4 		number
string string
boolean boolean
struct
arrray 		table
other elements 
{
		tag = "element name",
		[1] = <first child>,
		[2] = <second child>,
		[3] = ...,
		}

From Lua to XML-RPC

A conversion from a Lua data item or table to an XML-RPC element can be made automatically or explicitly. The automatic conversion rules are:

Lua object XML-RPC data type
number int or double
string string
boolean boolean
{ key = val } 
		<struct>
		<member>
		<name>key</name>
		<value>val</value>
		</member>
		</struct>
val is converted according to the same rules.

Ifn case of a table that has numeric keys, the resulting struct will have the string representation of these numbers as keys (e.g. "1" instead of 1). The library tries to convert integral numbers to integer types, otherwise converting them to floating point numbers.

Library functions

The xmlrpc.lua file implements the functions that encode and decode XML-RPC messages and transform data types between the Lua and XML-RPC. The functions are:

clEncode (method_name [, params]) => method_call
Build a XML-RPC document containing a methodCall element. It receives a string with the method's name and an optional list of parameters. The result is a string containing the XML-RPC document.
clDecode (method_response) => ok, results
Disassemble the server response into a Lua object. It receives a string containing the XML-RPC document representing the methodResponse element. The result is a boolean indicating wether the call was successful or not followed by the resulting objects (typically a methodResponse has only one value so only one Lua object will be returned). In case of error the false value is followed by the XMLRPC faultString and the faultCode. This values are extracted from the fault element.
srvDecode (method_call) => method_name, list_params
Disassemble the client request into a method's name and a table with the list of parameters. It receives a string containing the XML-RPC document representing the methodCall element. The result is a string with the name of the method to be called and a Lua table with the arguments to the call.
srvEncode (object, is_fault) => method_response
Build a XML-RPC document containing a methodResponse element. It receives a Lua object (a number, a string, a table, a "created typed value" etc.) with the return value of the call. The result is a string containing the XML-RPC document. Note that XML-RPC defines that a response only returns one value so a Lua function that returns more than one value has to pack them into a table to guarantee that all of them will be returned. The second parameter (is_fault) can be used to force a fault element to be generated instead of a params. In this case, the Lua object must be a table with the members faultCode and faultString.
srvMethods (tab_or_func)
Register the methods on the server. The parameter can be a table or a dispatching function. If a table is given it can have one level of objects with the corresponding methods. If a function is given, it will replace the dispatcher.
dispatch (method_name) => function
Returns a Lua function that implements the method call. Note that the object is encapsulated into that function so that the call will be turned into a real method call.

Client side

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

call (url, method [, params])
Execute the call to method at location url with the given params (if any). The method and params parameters will be just passed to clEncode function. The result is the same as clDecode function: a boolean indicating whether the call was successful or not, followed by the response value (if successful) or by the faultString and the faultCode (if the call fails).

Server side

The distribution also offers a simple XML-RPC server implemented over a CGI launcher. This launcher just have to offer a way to decode POST data and to send data back to the client.

The tests directory contains a file named cgi.lua, which implements an example of a simple XML-RPC server using the package post (which parses incoming POST data from the http server). An appropriate environment for writing Lua functions is implemented; a new assert function generates a XML-RPC fault in case of a false condition; a respond function creates the correct header for the responses. The main goal of cgi.lua is to give a starting point for other implementations.

References

Related documentation can be found at: http://www.xmlrpc.com.

Valid XHTML 1.0!