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

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.