forked from craigmj/json4lua
-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathindex.html
executable file
·394 lines (349 loc) · 15.8 KB
/
index.html
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
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
<html>
<head>
<title>JSON4Lua and JSONRPC4Lua</title>
<style type="text/css">
body {
font-family: Arial, Helvetica, Geneva;
font-size: 10pt;
}
.copyright {
color: #999999;
font-size: 8pt;
text-align:center;
}
.navBar {
border-left: 1px solid lightgray;
border-right: 1px solid lightgray;
border-bottom: 1px solid lightgray;
margin-top:5px;
margin-bottom: 5px;
}
.navBar h1 {
background-image: url('pics/lunartone.gif');
background-color: #e0c088;
color: white;
font-size: 9pt;
margin: 0px;
padding: 4px;
}
.navBar .navItem a {
color: #999999;
font-size: 8pt;
padding: 2px 2px 2px 10px;
text-decoration:none;
}
.navBar .navItem a:hover {
color: #ff9900;
text-decoration: underline;
}
.titleBar {
border-bottom: 2px dotted gray;
font-size: 20pt;
font-weight: bold;
margin-bottom: 15px;
width: 100%;
}
.workArea {
border: 1px none lightgray;
font-family: Times New Roman;
padding: 8px;
padding-left: 15px;
}
.workArea a {
font-weight: bold;
text-decoration: none;
}
.workArea a:hover {
color: #ff9900;
text-decoration: underline;
}
.workArea .downloadTable {
border: 1px solid lightgray;
padding: 0px;
margin: 0px;
}
.workArea .downloadTable * th {
background-color: #e0c088;
background-image: url('pics/lunartone.gif');
color: white;
}
.workArea .downloadTable * tr {
border: 1px solid lightgray;
}
.workArea .downloadTable * td {
vertical-align: top;
}
.workArea * dt {
font-size: 12pt;
margin-top: 10px;
}
.workArea * .example {
background-color: #ffffcc;
border: 1px dashed lightgray;
padding: 10px;
}
.workArea h1 {
font-size: 16pt;
font-weight: bold;
}
.workArea h2 {
font-size: 14pt;
font-weight: normal;
color: gray;
}
</style>
<body>
<table border="0">
<tr>
<td valign="top">
<img src="pics/json4lua.gif"><p/>
<!-- NAVIGATION BARS -->
<div class="navBar">
<h1>This Page</h1>
<div class="navItem"><a href="#news">Latest News</a></div>
<div class="navItem"><a href="#introduction">Introduction</a></div>
<div class="navItem"><a href="#licence">Licence</a></div>
<div class="navItem"><a href="#requirements">Requirements</a></div>
<div class="navItem"><a href="#download">Download</a></div>
<div class="navItem"><a href="#installation">Installation</a></div>
<div class="navItem"><a href="#usage">Usage & Reference</a>
<div class="navItem" style="margin-left: 4px"><a href="#json_decode">decode</a></div>
<div class="navItem" style="margin-left: 4px"><a href="#json_encode">encode</a></div>
<div class="navItem" style="margin-left: 4px"><a href="#json_null">null</a></div>
<div class="navItem" style="margin-left: 4px"><a href="#json_rpc_call">rpc.call</a></div>
<div class="navItem" style="margin-left: 4px"><a href="#json_rpc_proxy">rpc.proxy</a></div>
<div class="navItem" style="margin-left: 4px"><a href="#json_rpcserver_serve">rpcserver.serve</a></div>
</div>
<div class="navItem"><a href="#roadmap">History & Roadmap</a></div>
</div> <!-- end of navigation bar: This Site -->
<div class="navBar">
<h1>json.luaforge</h1>
<div class="navItem"><a href="http://luaforge.net/projects/json/">Summary</a></div>
<div class="navItem"><a href="http://luaforge.net/forum/?group_id=143">Forums</a></div>
<div class="navItem"><a href="http://luaforge.net/tracker/?group_id=143">Tracker</a></div>
<div class="navItem"><a href="http://luaforge.net/news/?group_id=143">News</a></div>
<!--<div class="navItem"><a href="http://luaforge.net/scm/?group_id=143">CVS</a></div>-->
<div class="navItem"><a href="http://luaforge.net/frs/?group_id=143">Files</a></div>
</div> <!-- end of navigation bar: json.luaforge -->
<div class="navBar">
<h1>Lua</h1>
<div class="navItem"><a href="http://www.lua.org/">Lua</a></div>
<div class="navItem"><a href="http://www.luaforge.net/">Lua Forge</a></div>
<div class="navItem"><a href="http://www.keplerproject.org/cgilua/">CGI Lua</a></div>
<div class="navItem"><a href="http://www.keplerproject.org/compat/">Lua compat-5.1</a></div>
<div class="navItem"><a href="http://www.cs.princeton.edu/~diego/professional/luasocket/">Lua Socket 2.0</a></div>
<div class="navItem"><a href="http://www.keplerproject.org/xavante/">Xavante</a></div>
</div> <!-- end of navigation bar: Lua Resources -->
<div class="navBar">
<h1>JSON</h1>
<div class="navItem"><a href="http://www.json.org/">json.org</a></div>
<div class="navItem"><a href="http://www.json-rpc.org/">json-rpc.org</a></div>
</div> <!-- end of navigation bar: Lua Resources -->
</td>
<!-- MAIN WORK AREA -->
<td valign="top" class="workArea">
<div class="titleBar">JSON4Lua and JSONRPC4Lua</div>
<!-- ***************** LATEST NEWS ***************** -->
<h1><a name="news"></a>Latest News</h1>
<p><small>(2009-08-06)</small> We've changed the JSON4Lua and JSONRPC4Lua licence from the GPL to the MIT licence, like Lua itself.</p>
<p>
The 0.9.20 release fixes a bug in Lua 5.1 operation, introduces a <a href="#json_null"><code>json.null</code></a> value to force null values in JSON encodings, improves performance (over 50% faster on some tests), and permits <code>/* comments */</code> in the JSON string being decoded.
</p>
<!-- ***************** INTRODUCTION ***************** -->
<h1><a name="introduction"></a>Introduction</h1>
JSON4Lua and JSONRPC4Lua implement <a href="http://www.json.org">JSON (JavaScript Object Notation)</a> encoding and decoding and a <a href="http://www.json-rpc.org/">JSON-RPC-over-http</a> client for <a href="http://www.lua.org/">Lua</a>.<p/>
JSON is JavaScript Object Notation, a simple encoding of Javascript-like objects that is ideal for lightweight transmission of relatively weakly-typed data.
A sub-package of JSON4Lua is JSONRPC4Lua, which provides a simple JSON-RPC-over-http client and server (in a CGILua environment) for Lua. Please seen the documentation below for JSONRPC4Lua.
<!-- ***************** LICENCE ***************** -->
<h1><a name="licence"></a>Licence</h1>
JSON4Lua is licensed under the MIT Consortium licence like Lua itself. Please see <a href="LICENCE.txt">LICENCE.txt</a> for details.<p/>
<!-- ***************** REQUIREMENTS ***************** -->
<a name="requirements"></a><h1>Requirements</h1>
JSON4Lua is a pure-Lua module that is Lua 5.0 compatible (if you have <a href="http://www.keplerproject.org/compat/">compat-5.1</a> for Lua 5.0). JSON4Lua also works (perfectly, I hope) under Lua 5.1, which is where I largely use it nowadays. Since Lua is platform independent, so is JSON4Lua.<p/>
The JSON4RPC sub-module requires <a href="http://www.cs.princeton.edu/~diego/professional/luasocket/">Lua Socket 2.0</a>. It uses <code>socket.http</code> for for the RPC over http connection. Socket 2.0 includes <code>ltn12</code>, which is also used by JSON4RPC.<p />
To use <code>json.rpcserver</code> you need a <a href="http://www.keplerproject.org/cgilua/">CGILua</a> enabled webserver. However, a quick <a href="cgilua_patch.html">patch</a> is required in CGILua 5.0 to support JSON-RPC.
<!-- ***************** START OF DOWNLOAD SECTION ***************** -->
<h1><a name="download"></a>Download</h1>
JSON4Lua is hosted on <a href="http://www.luaforge.net">LuaForge</a>.
<table cols="2" class="downloadTable">
<tr><th>Version</th><th>Date</th><th>Notes</th></tr>
<tr><td><a href="http://luaforge.net/frs/?group_id=143">0.9.30</a></td><td>6 August 2009</td><td>
Changed to MIT Licence.
</td></tr>
<tr><td><a href="http://luaforge.net/frs/?group_id=143">0.9.20</a></td><td>4 January 2006</td><td>
Introduction of local Lua functions for private functions (removed _ function prefix). <br />
Fixed Lua 5.1 compatibility issues.<br />
Introduced <code>json.null</code> to have null values in associative arrays.<br />
Performance improvement (more than 50% on some tests) through <code>table.concat</code> rather than <code>..</code> operator.<br/>
<code>json.decode</code> now ignores <code>/* */</code> comments in the JSON string.<br />
</td></tr>
<tr><td><a href="http://luaforge.net/frs/?group_id=143">0.9.10</a></td><td>20 December 2005</td><td>
Fixes bug with array representation when nil / null values occur in the array.<br />
Adds content-type header of <code>text/plain</code> to JSON RPC http requests.<br />
Introduces <code>json.rpcserver</code> module with simple JSON RPC enablement for Lua objects.<br />
Moved the <code>json.lua</code> file into the <code>json</code> directory. Ensure, therefore, that your <code>LUA_PATH</code> contains a module-finding form like <code>LUA_PATH = c:\proj\lua\?\?.lua;?.lua</code>.<br/>
</td></tr>
<tr>
<td><a href="http://luaforge.net/frs/?group_id=143">0.9.01</a></td>
<td>19 December 2005</td>
<td>Minor corrections to documentation.</td>
</tr>
<tr>
<td><a href="http://luaforge.net/frs/?group_id=143">0.9.00</a></td>
<td>19 December 2005</td>
<td>First release</td>
</tr>
</table>
<!-- END OF DOWNLOAD SECTION -->
<!-- ***************** START OF INSTALLATION SECTION ***************** -->
<h1><a name="installation"></a>Installation</h1>
As of version 0.9.10, all the JSON4Lua files are contained in the <code>json</code> subdirectory in the distribution zip.<p />
Simply copy the <code>json</code> subdirectory so that it is in your Lua path.<p />
Ensure that your <code>LUA_PATH</code> variable permits module resolution of the form <code>?/?.lua</code>.<p />
<b>Example</b>
<div class="example">
</div>
<h2>Using Windows</h2>
Under Windows, set your Lua path as (my Lua installation is in <code>c:\proj\lua\</code>): <p/>
<code>
set LUA_PATH=c:\proj\lua\?.lua;c:\proj\lua\?\?.lua;?.lua
</code><p/>
For compat-5.1.lua to start when Lua starts (if you're using Lua 5.0), you also need:<p/>
<code>
set LUA_INIT=@c:\proj\lua\compat-5.1.lua
</code><p />
You probably also want to set your library path:<p/>
<code>set LUA_CPATH=c:\proj\lua\lib\?.dll;?.dll</code>
<!------------------------ USAGE AND REFERENCE -------------------->
<h1><a name="usage"></a>Usage & Reference</h1>
The following functions in <b>JSON4Lua</b> and <b>JSONRPC4Lua</b> are of interest:<p />
<dl>
<dt><a name="json_encode"></a><code>string <b>json.encode</b>( lua_object )</code></dt>
<dd>Returns the Lua object JSON encoded into a string.<p/>
<b>Example</b>
<div class="example">
<code>
json = require("json")<br/>
print (json.encode( { 1, 2, 'fred', {first='mars',second='venus',third='earth'} } ))
</code><p/>
prints<p/><code> [1,2,"fred", {"first":"mars","second":"venus","third","earth"}]</code>
</div>
</dd>
<dt><a name="json_decode"></a><code>lua_object <b>json.decode</b>( json_string )</code></dt>
<dd>Decodes the JSON encoded data structure, and returns a Lua object with the appropriate data.<p/>
<b>Example</b>
<div class="example">
<code>
json = require("json")<br/>
testString = [[ { "one":1 , "two":2, "primes":[2,3,5,7] } ]]<br/>
o = json.decode(testString)<br/>
table.foreach(o,print)<br />
print ("Primes are:")<br />
table.foreach(o.primes,print)
</code><p/>
prints:<p/>
<pre>
one 1
two 2
primes table: 0032B928
Primes are:
1 2
2 3
3 5
4 7</pre>
</div></dd>
<dt><a name="json_null"></a><code><b>json.null</b></code></dt>
<dd>Returns a unique value that will be encoded as a <code>null</code> in a JSON encoding.
<p>This is necessary in one situation. In Lua, if a key in a table has a <code>nil</code> value, the key is simply discarded (since any non-existent key has a nil value). The encoding of arrays has been built to manage this nil-values in arrays, but associative arrays provide a problem. Consider:
<div class="example"><pre>t = { user="test", password=nil }</pre></div>
Since Lua simply discards the <code>password</code> key, JSON4Lua encodes this as the JSON string
<div class="example"><pre>{"user":"test"}</pre></div>
If, for some reason, your JSON RPC Server requires a defined <code>null</code> value, use the following code:
<div class="example"><pre>t = { user="test", password=json.null }</pre></div>
This will now correctly encode to:
<div class="example"><pre>{"user":"test","password":null}</pre></div>
Incidentally, <code>json.null</code> is simply a function that returns itself, so that you can use either <code>json.null</code> or <code>json.null()</code> as you fancy.
</dd>
<dt><a name="json_rpc_call"></a><code>result, error <b>json.rpc.call</b> ( url, method, ...)</code></dt>
<dd>Calls the named method on the given url with the arg parameters. Returns the result and the error. If <code>error</code> is <code>nil</code>, no error occurred.<p/>
<b>Example</b>
<div class="example">
<pre>require ("json.rpc")
result, error = json.rpc.call("http://jsolait.net/testj.py","echo","Test echo!")
print(result)</pre>
<p />prints<p />
<pre>Test echo!</pre>
</div>
</dd>
<dt><a name="json_rpc_proxy"></a><code>proxyServer = <b>json.rpc.proxy</b> (url)</code></dt>
<dd>Creates a proxy server object on which JSON-RPC calls can be made. Each call will return the <code>result, error</code>. If <code>error</code> is <code>nil</code>, no error occurred.<p/>
<b>Example</b>
<div class="example">
<pre>
require ("json.rpc")
server = json.rpc.proxy("http://jsolait.net/testj.py")
result, error = server.echo('Test echo!')
print(result)</pre>
<p />prints<p />
<pre>Test echo!</pre>
</div>
</dd>
<dt><a name="json_rpcserver_serve"></a><code><b>json.rpcserver.serve</b>(object[, packReturn])</code></dt>
<dd>
Handles an incoming CGILua request as a JSON RPC request and serves the request from
the given object.
<p />The optional <code>packReturn</code> parameter, if set <code>true</code>, will, if the requested
method returns more than one value, pack these returned values into an array. If only a single value
is returned, it is not packed into an array. If <code>packReturn</code> is <code>false</code> (or not set), only the first
return value from the requested method will be returned. This is necessitated since the JSON protocol does not permit a method call to return more than a single value.
<p/>
<code>serve</code> returns nothing.<p/>
<b>Example</b>
<div class="example">
<pre>
--
-- jsonrpc.lua
-- Installed in a CGILua webserver environment (with necessary CGI Lua 5.0 patch)
--
require ('json.rpcserver')
-- The Lua class that is to serve JSON RPC requests
local myServer = {
echo = function (msg) return msg end,
average = function(...)
local total=0
local count=0
for i=1, table.getn(arg) do
total = total + arg[i]
count = count + 1
end
return { average= total/count, sum = total, n=count }
end
}
json.rpcserver.serve(myServer)
</pre>
An example of using this JSON RPC server from a Lua file:
<pre>
require ('json.rpc')
local server = json.rpc.proxy('http://www.myserver.com/jsonrpc.lua')
table.foreach(server.average(10,15,23), print)
</pre>
Prints:
<pre>
average 16
sum 48
n 3
</pre>
</div>
</dd>
</dl>
<!-- ***************** HISTORY AND ROADMAP ***************** -->
<h1><a name="roadmap"></a>History & Roadmap</h1>
The downloads sections details the versions and their related histories. I will wait for Lua 5.1 to be final (expected late January) before making the JSON4Lua module beta. If no serious bugs or objections are encountered, I will make the module 1.0 on 1 April 2006 (to coincide with April Fool's day!)
</td>
</tr>
<tr>
<td colspan="2" class="copyright">© 2005, 2006 Craig Mason-Jones</td>
</tr>
</table>
</body>
</html>