1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<head>
<title>Lua XML-RPC: XML-RPC interface to the Lua programming language</title>
<link rel="stylesheet" href="http://www.keplerproject.org/doc.css" type="text/css"/>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
</head>
<body>
<div id="container">
<div id="product">
<div id="product_logo">
<a href="http://www.keplerproject.org">
<img alt="Lua XML-RPC logo" src="luaxmlrpc.png"/>
</a>
</div>
<div id="product_name"><big><strong>Lua XML-RPC</strong></big></div>
<div id="product_description">XML-RPC interface to the Lua programming language</div>
</div> <!-- id="product" -->
<div id="main">
<div id="navigation">
<h1>Lua XML-RPC</h1>
<ul>
<li><a href="index.html">Home</a>
<ul>
<li><a href="index.html#overview">Overview</a></li>
<li><a href="index.html#status">Status</a></li>
<li><a href="index.html#download">Download</a></li>
<li><a href="index.html#history">History</a></li>
<li><a href="index.html#credits">Credits</a></li>
<li><a href="index.html#contact">Contact</a></li>
</ul>
</li>
<li><strong>Manual</strong>
<ul>
<li><a href="manual.html#introduction">Introduction</a></li>
<li><a href="manual.html#installation">Installation</a></li>
<li><a href="manual.html#data_types">Data types</a></li>
<li><a href="manual.html#functions">Library functions</a></li>
<li><a href="manual.html#client">Client side</a></li>
<li><a href="manual.html#server">Server side</a></li>
<li><a href="manual.html#references">References</a></li>
</ul>
</li>
<li><a href="examples.html">Examples</a></li>
<li><a href="license.html">License</a></li>
</ul>
</div> <!-- id="navigation" -->
<div id="content">
<h2><a name="introduction"></a>Introduction</h2>
<p>Lua XML-RPC is a <a href="http://www.lua.org">Lua</a> library that can be used
to build <a href="http://www.xmlrpc.com">XML-RPC</a> clients and
servers. It enables a Lua program to:</p>
<ul>
<li>Encode and decode XML-RPC messages without handling XML code</li>
<li>Transform Lua data structures into XML-RPC data types and vice-versa</li>
</ul>
<p>Lua XML-RPC provides a simple API and an abstraction layer over XML avoiding
manipulation of string representation of data structures.</p>
<p>Lua XML-RPC is based on
<a href="http://www.keplerproject.org/luaexpat">LuaExpat</a> and on
<a href="http://www.lua.org">Lua 5.1</a>.
The abstraction layer over HTTP depends on
<a href="http://w3.impa.br/~diego/software/luasocket/">LuaSocket 2.0.2</a>.</p>
<h2><a name="installation"></a>Installation</h2>
<p>Lua XML-RPC is composed by three Lua files:
<dl>
<dt><code>init.lua</code></dt>
<dd>Main source file providing the API</dd>
<dt><code>http.lua</code></dt>
<dd>API to call XML-RPC via HTTP</dd>
<dt><code>server.lua</code></dt>
<dd>Server side API</dd>
</dl>
</p>
These files should be copied to a directory named <code>xmlrpc</code> created in your
<code>LUA_PATH</code>.</p>
<p>Lua XML-RPC follows the
<a href="http://www.keplerproject.org/compat/">package model</a>
for Lua 5.1, therefore it should be "installed". Refer to
<a href="http://www.keplerproject.org/compat/manual.html#configuration">
Compat-5.1 configuration</a> section about how to install the module.</p>
<h2><a name="data_types"></a>Data types</h2>
<p>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.</p>
<h3><a name="xr2lua"></a>From XML-RPC to Lua</h3>
<p>When converting from XML-RPC element to a Lua data item or table,
a table with a field <code>tag</code> is used. The child elements are
stored at numbered indexes and white space is ignored.</p>
<table>
<tr>
<th>XML-RPC data type(s)</th>
<th>Lua object</th>
</tr>
<tr>
<td>
double<br />
int<br />
i4
</td>
<td>number</td>
</tr>
<tr>
<td>string</td>
<td>string</td>
</tr>
<tr>
<td>boolean</td>
<td>boolean</td>
</tr>
<tr>
<td>
struct<br />
arrray
</td>
<td>table</td>
</tr>
<tr>
<td>other elements</td>
<td>
<pre>{
tag = "element name",
[1] = <first child>,
[2] = <second child>,
[3] = ...,
}</pre>
</td>
</tr>
</table>
<h3><a name="lua2xr"></a>From Lua to XML-RPC</h3>
<p>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:</p>
<table>
<tr>
<th>Lua object</th>
<th>XML-RPC data type</th>
</tr>
<tr>
<td>number</td>
<td>int or double</td>
</tr>
<tr>
<td>string</td>
<td>string</td>
</tr>
<tr>
<td>boolean</td>
<td>boolean</td>
</tr>
<tr>
<td><code>{ key = val }</code></td>
<td>
<pre>
<struct>
<member>
<name>key</name>
<value><em>val</em></value>
</member>
</struct>
</pre>
<small><em>val</em> is converted according to the same rules.</small>
</td>
</tr>
</table>
<p>Ifn case of a table that has numeric keys, the resulting struct will
have the string representation of these numbers as keys (e.g.
<code>"1"</code> instead of <code>1</code>). The library tries to
convert integral numbers to integer types, otherwise converting
them to floating point numbers.</p>
<h2><a name="functions"></a>Library functions</h2>
<p>The <code>xmlrpc.lua</code> file implements the functions that encode and decode XML-RPC messages and transform
data types between the Lua and XML-RPC. The functions are:</p>
<dl>
<dt><a name="clEncode"></a><strong><code>clEncode (method_name [, params]) => method_call</code></strong></dt>
<dd>Build a XML-RPC document containing a <code>methodCall</code>
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.</dd>
<dt><a name="clDecode"></a><strong><code>clDecode (method_response) => ok, results</code></strong></dt>
<dd>Disassemble the server response into a Lua object. It receives a
string containing the XML-RPC document representing the
<code>methodResponse</code> 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
<code>false</code> value is followed by the XMLRPC
<em>faultString</em> and the <em>faultCode</em>. This values are
extracted from the <code>fault</code> element.</dd>
<dt><a name="srvDecode"></a><strong><code>srvDecode (method_call) => method_name, list_params</code></strong></dt>
<dd>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 <code>methodCall</code> 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.</dd>
<dt><a name="srvEncode"></a><strong><code>srvEncode (object, is_fault) => method_response</code></strong></dt>
<dd>Build a XML-RPC document containing a <code>methodResponse</code>
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 <em>one</em> value so a
Lua function that returns more than one value has to <em>pack</em>
them into a table to guarantee that all of them will be returned.
The second parameter (<code>is_fault</code>) can be used to force a
<code>fault</code> element to be generated instead of a
<code>params</code>. In this case, the Lua object must be a table
with the members <code>faultCode</code> and
<code>faultString</code>.</dd>
<dt><a name="srvMethods"></a><strong><code>srvMethods (tab_or_func)</code></strong></dt>
<dd>Register the methods on the server. The parameter can be a table
or a dispatching function. If a <em>table</em> is given it can have
one level of objects with the corresponding methods. If a
<em>function</em> is given, it will replace the dispatcher.</dd>
<dt><a name="dispatch"></a><strong><code>dispatch (method_name) => function</code></strong></dt>
<dd>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.</dd>
</dl>
<h2><a name="client"></a>Client side</h2>
<p>The <code>http.lua</code> file implements a simple
stand-alone client based on
<a href="http://w3.impa.br/~diego/software/luasocket/">LuaSocket 2.0.2</a>. The
following function is provided:</p>
<dl>
<dt><a name="call"></a><strong><code>call (url, method [, params])</code></strong></dt>
<dd>Execute the call to <code>method</code> at location
<code>url</code> with the given <code>params</code> (if any). The
<code>method</code> and <code>params</code> parameters will be just
passed to <a href="#clEncode">clEncode</a> function. The result is
the same as <a href="#clDecode">clDecode</a> function: a boolean
indicating whether the call was successful or not, followed by the
response value (if successful) or by the <em>faultString</em> and the
<em>faultCode</em> (if the call fails).</dd>
</dl>
<h2><a name="server"></a>Server side</h2>
<p>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.</p>
<p>The <code>tests</code> directory contains a file named
<code>cgi.lua</code>, which implements an example of a simple XML-RPC
server using the package <code>post</code> (which parses incoming
POST data from the http server). An appropriate environment for
writing Lua functions is implemented; a new <code>assert</code>
function generates a XML-RPC fault in case of a false condition; a
<code>respond</code> function creates the correct header for the
responses. The main goal of <code>cgi.lua</code> is to give a
starting point for other implementations.</p>
<h2><a name="references"></a>References</h2>
<p>Related documentation can be found at: <a href="http://www.xmlrpc.com">http://www.xmlrpc.com</a>.</p>
</div> <!-- id="content" -->
</div> <!-- id="main" -->
<div id="about">
<p>
<a href="http://validator.w3.org/check?uri=referer">
valid
</a>
</p>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>
</html>
|
