| JSON4Lua and JSONRPC4Lua # 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 JSON4Lua and JSONRPC4Lua implement JSON (JavaScript Object Notation) encoding and decoding and a JSON-RPC-over-http client for Lua. 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 JSON4Lua is licensed under the MIT Consortium licence like Lua itself. Please see LICENCE.txt for details. # Requirements JSON4Lua is a pure-Lua module that is Lua 5.0 compatible (if you have compat-5.1 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. 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 JSON4Lua is hosted on LuaForge.
Version | Date | Notes
--- | --- | ---
0.9.30 | 6 August 2009 | Changed to MIT Licence.
0.9.20 | 4 January 2006 | Introduction of local Lua functions for private functions (removed _ function prefix). Fixed Lua 5.1 compatibility issues. Introduced `json.null` to have null values in associative arrays. Performance improvement (more than 50% on some tests) through `table.concat` rather than `..` operator. `json.decode` now ignores `/* */` comments in the JSON string.
0.9.10 | 20 December 2005 | Fixes bug with array representation when nil / null values occur in the array. Adds content-type header of `text/plain` to JSON RPC http requests. Introduces `json.rpcserver` module with simple JSON RPC enablement for Lua objects. Moved the `json.lua` file into the `json` directory. Ensure, therefore, that your `LUA_PATH` contains a module-finding form like `LUA_PATH = c:\proj\lua\?\?.lua;?.lua`.
0.9.01 | 19 December 2005 | Minor corrections to documentation.
0.9.00 | 19 December 2005 | First release
  # Installation As of version 0.9.10, all the JSON4Lua files are contained in the `json` subdirectory in the distribution zip. 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 Under Windows, set your Lua path as (my Lua installation is in `c:\proj\lua\`): `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 The following functions in JSON4Lua and JSONRPC4Lua are of interest: `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 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!)
© 2005, 2006 Craig Mason-Jones