Latest News

(2009-08-06) We've changed the JSON4Lua and JSONRPC4Lua licence from the GPL to the MIT licence, like Lua itself.

The 0.9.20 release fixes a bug in Lua 5.1 operation, introduces a json.null value to force null values in JSON encodings, improves performance (over 50% faster on some tests), and permits /* comments */ in the JSON string being decoded.

Introduction

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

Requirements

The JSON4RPC sub-module requires Lua Socket 2.0. It uses socket.http for for the RPC over http connection. Socket 2.0 includes ltn12, which is also used by JSON4RPC.

To use json.rpcserver you need a CGILua enabled webserver. However, a quick patch is required in CGILua 5.0 to support JSON-RPC.

Download

Installation

Simply copy the json subdirectory so that it is in your Lua path.

Ensure that your LUA_PATH variable permits module resolution of the form ?/?.lua.

Example

Using Windows

set LUA_PATH=c:\proj\lua\?.lua;c:\proj\lua\?\?.lua;?.lua

For compat-5.1.lua to start when Lua starts (if you're using Lua 5.0), you also need:

set LUA_INIT=@c:\proj\lua\compat-5.1.lua

You probably also want to set your library path:

set LUA_CPATH=c:\proj\lua\lib\?.dll;?.dll

Usage & Reference

string json.encode( lua_object )

Returns the Lua object JSON encoded into a string.

Example

json = require("json")
print (json.encode( { 1, 2, 'fred', {first='mars',second='venus',third='earth'} } ))

prints

[1,2,"fred", {"first":"mars","second":"venus","third","earth"}]

lua_object json.decode( json_string )

Decodes the JSON encoded data structure, and returns a Lua object with the appropriate data.

Example

json = require("json")
testString = [[ { "one":1 , "two":2, "primes":[2,3,5,7] } ]]
o = json.decode(testString)
table.foreach(o,print)
print ("Primes are:")
table.foreach(o.primes,print)

prints:

one		1
two		2
primes		table: 0032B928
Primes are:
1		2
2		3
3		5
4		7

json.null

Returns a unique value that will be encoded as a null in a JSON encoding.

This is necessary in one situation. In Lua, if a key in a table has a nil 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:

t = { user="test", password=nil }

Since Lua simply discards the password key, JSON4Lua encodes this as the JSON string

{"user":"test"}

If, for some reason, your JSON RPC Server requires a defined null value, use the following code:

t = { user="test", password=json.null }

This will now correctly encode to:

{"user":"test","password":null}

Incidentally, json.null is simply a function that returns itself, so that you can use either json.null or json.null() as you fancy.

result, error json.rpc.call ( url, method, ...)

Calls the named method on the given url with the arg parameters. Returns the result and the error. If error is nil, no error occurred.

Example

require ("json.rpc")
result, error = json.rpc.call("http://jsolait.net/testj.py","echo","Test echo!")
print(result)

prints

Test echo!

proxyServer = json.rpc.proxy (url)

Creates a proxy server object on which JSON-RPC calls can be made. Each call will return the result, error. If error is nil, no error occurred.

Example

require ("json.rpc")
server = json.rpc.proxy("http://jsolait.net/testj.py")
result, error  = server.echo('Test echo!')
print(result)

prints

Test echo!

json.rpcserver.serve(object[, packReturn])

Handles an incoming CGILua request as a JSON RPC request and serves the request from the given object.

The optional packReturn parameter, if set true, 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 packReturn is false (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.

serve returns nothing.

Example

--
-- 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)

An example of using this JSON RPC server from a Lua file:

require ('json.rpc')
local server = json.rpc.proxy('http://www.myserver.com/jsonrpc.lua')
table.foreach(server.average(10,15,23), print)

Prints:

average	16
sum	48
n	3

History & Roadmap