A very fast json module for LuaJIT 2.0/2.1 and Lua 5.1/5.2/5.3.

Based on the very fast RapidJSON C++ library.

See project homepage for more informations, bug report and feature request.

luarocks install rapidjson

or if you like to use your own version of RapidJSON, use:

luarocks install rapidjson RAPIDJSON_INCLUDE_DIRS=path/to/rapidjson/include/dir

local rapidjson = require('rapidjson')

rapidjson.encode()
rapidjson.decode()

rapidjson.load()
rapidjson.dump()

Clone or download source code, in the project root folder:

luarocks install dromozoa-utf8
luarocks install busted
luarocks make
busted

To compare speed of rapidjson and other json libraries:

lua performance/run.lua

Decode json to lua table.

value = rapidjson.decode(jsonstring)

jsonstring

A json value string to be decoded.

Return table if json is an object or array.

Return true, false, number and rapidjson.null respectively if json is a simple value.

Return nil plus an error message as a second result when passed string is not valid json string.

• When passed value is not (convertable to) string.

Encode lua table to json string.

supports the following types:

• boolean
• rapidjson.null (it is actually a function)
• number
• string
• table

The json object keys are sorted by the this function.

string = rapidjson.encode(value [, option])

value:

When passed a table:

1. it is encoded as json array if:
   • meta field __jsontype set to array.
   • table contains length > 0.
2. otherwise the table is encoded as json object and non string keys and its values are ignored.

When passed with true, false, number and rapidjson.null, simply encode as simple json value.

option:

A optional table contains follow field:

• pretty boolean: Set true to make output string to be pretty formated. Default is false.
• sort_keys boolean: Set true to make json object keys be sorted. Default is false.

Return encoded json string on success. Return nil on failure, plus an error message as a second result.

• When option passed a value other than table.

local rapidjson = require('rapidjson')

rapidjson.encode({})     -- '{}'

rapidjson.encode(rapidjson.object()) --> '{}'
rapidjson.encode(rapidjson.array()) --> '[]'

rapidjson.encode(setmetatable({}, {__jsontype='object'})) --> '{}'
rapidjson.encode(setmetatable({}, {__jsontype='array'})) --> '[]'

rapidjson.encode(true) --> 'true'
rapidjson.encode(rapidjson.null) --> 'null'
rapidjson.encode(123) --> '123.0' or '123' in Lua 5.3.


rapidjson.encode({true, false}) --> '[true, false]'

rapidjson.encode({a=true, b=false}) --> '{"a":true,"b":false]'

Load json file into lua table.

value = rapidjson.load(filename)

filename

Json file to be loaded.

Return table if file contains an object or array.

Return true, false, number and rapidjson.null respectively if file contains a simple value.

Return nil plus an error message as a second result when passed file is not valid json file.

• When passed filename is not (convertable to) string.

Dump lua value to json file.

success, err = rapidjson.dump(value, filename [, option])

value

Same as in rapidjson.encode().

filename

The file path string where to save dumpped rapidjson.

option:

Same as in options in rapidjson.encode().

bool: success

Return true on success.

Return false plus an error message as a second result when:

• Value can't be encoded.
• filename can't be opened for write.

• When passed filename is not (convertable to) string.
• When passed option is not table, nil or none.

local rapidjson = require('rapidjson')

rapidjson.dump({rapidjson.null}, 'test.json')
rapidjson.dump({rapidjson.null}, 'test-pretty.json', {pretty=true})

The placeholder for null values in rapidjson.

eg.

local rapidjson = require('rapidjson')

rapidjson.decode('[null]') --> {rapidjson.null}
rapidjson.encode({rapidjson.null}) --> '[null]'

Create a new empty table that have metatable field __jsontype set as 'object' so that the encode and dump function will encode it as json object.

When passed an valid table:

• Passed table do not have metatable, just set above metatable for the table.
• Passed table already have metatable, set the metatable field __jsontype to 'object'.

obj = rapidjson.object([t])

t

Optional table to be set the metatable with meta field __jsontype set as 'object'.

Origin passed in table when passed with a table. Or new created table.

Same as rapidjson.array() except the metatable field __jsontype is set as 'array'. And the encode and dump function will encode it as json array.

A string that is "rapidjson".

The current loaded rapidjson version. "scm" when not build with luarocks.

1. Pass all unit tests.
2. Update version in rapidjson-..*-1.rockspec and update the name of the rockspec file.
3. Tag source code with that version (..*), and push.
4. luarocks upload rapidjson-*.*.*-1.rockspec

• CMakeLists.txt supports command line defined RAPIDJSON_INCLUDE_DIRS to specified RapidJSON include directory.
• Keeps only necessary RapidJSON header files and docs make the rock much smaller.

• Update RapidJSON to latest HEAD version.

• Fixes Windows dll.

• Checks circular reference when encoding tables.
• A table is encoded as json array if:
  • have meta field __jsontype set to 'array'.
  • don't have meta filed __jsontype and length > 0.
• When table is encoded as json object, only string keys and its values are encoded.
• Integers are decoded to lua_Integer if it can be stored in lua_Integer.

• Follow integers are encoded as integers.
  • Lua 5.3 integers.
  • Integers stored in double and in between:
    • [INT64_MIN..INT64_MAX] on 64 bit Lua or
    • [INT32_MIN..INT32_MAX] in 32 bit Lua.
• CI scripts updated, thanks @ignacio

• Rename module to rapidjson.
• Added option.sort_keys option to rapidjson.encode() and rapidjson.dump(), and default value for sort_keys is false.
• Added rapidjson._NAME ("rapidjson") and rapidjson._VERSION.
• rapidjson.object() and rapidjson.array() just set metatable field __jsontype to 'object' and 'array' if passed table already have a metatable.
• fixes dump return value of false rather than nil.

• Initial release.