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

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
• function (rapidjson.null only)
• number
• string
• table

The json object keys are sorted by the this function.

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

value:

When passed a table:

1. Trade as array if:
   • metatable field __jsontype set to array.
   • table contains only integer keys from 1 to n.
2. Otherwise the table are trade as object and integer keys are converted to string.

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, just the the metatable field __jsontype to 'object'.

obj = rapidjson.object([t])

t

Optinal 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.

• Follow integers are encoded as integers string.
  • 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' it passed table already have a metatable.
• fixes dump return value of false rather than nil.

• Initial release.