Lua CJSON is a fast JSON encoding/parsing module for Lua
Clone or download
Pull request Compare This branch is 41 commits ahead, 14 commits behind mpx:master.
Type Name Latest commit message Commit time
Failed to load latest commit information.
devel Add original JSON parser design outline Dec 20, 2011
lua tests: now we use luajit to run the test suite. Nov 16, 2017
tests bumped version to Apr 19, 2018
.gitattributes Add .gitignore for object files, html, extra dirs Dec 20, 2011
.gitignore chore: ignored the generated test_case.lua file. Dec 18, 2016
.travis.yml travis: skipped the std lua 5.1 interpreter tests. Nov 16, 2017
CMakeLists.txt Remove ENABLE_CJSON_GLOBAL option Mar 4, 2012
LICENSE Update copyright date range to include 2012 Mar 4, 2012
Makefile travis-ci integration Apr 11, 2016
NEWS Add release notes for 2.1.0 release Mar 4, 2012 feature: set cjson.array_mt on decoded JSON arrays. Nov 17, 2017
THANKS Update THANKS for locale bug reporter Nov 27, 2011 Bump version to 2.1devel Mar 4, 2012
dtoa.c Use Javascript compat values for Infinity/NaN Mar 4, 2012
dtoa_config.h Add error checking to dtoa locking primitives Mar 4, 2012
fpconv.c feature: supports MS C compiler older than VC2012. Jan 31, 2017
fpconv.h fixed the warning "inline function ‘fpconv_init’ declared but never d… Nov 1, 2015
g_fmt.c Fix string length returned by g_fmt.c for |x|<1 Mar 4, 2012
lua-cjson- luarocks: bumped version to Apr 27, 2018
lua-cjson.spec Add release notes for 2.1.0 release Mar 4, 2012
lua_cjson.c bugfix: we now only apply the lightuserdata mask on platforms that ar… Dec 7, 2018
manual.txt Use Javascript compat values for Infinity/NaN Mar 4, 2012
performance.txt Update release date for 2.0.0 to 22 Jan 2012 Mar 4, 2012
rfc4627.txt Initial commit Apr 15, 2011 removed rpmbuild test Apr 24, 2016
strbuf.c Update copyright date range to include 2012 Mar 4, 2012
strbuf.h feature: supports MS C compiler older than VC2012. Jan 31, 2017


lua-cjson - Fast JSON encoding/parsing

Table of Contents


This fork of mpx/lua-cjson is included in the OpenResty bundle and includes a few bugfixes and improvements, especially to facilitate the encoding of empty tables as JSON Arrays.

Please refer to the lua-cjson documentation for standard usage, this README only provides informations regarding this fork's additions.

See mpx/master..openresty/master for the complete history of changes.

Back to TOC



syntax: cjson.encode_empty_table_as_object(true|false|"on"|"off")

Change the default behavior when encoding an empty Lua table.

By default, empty Lua tables are encoded as empty JSON Objects ({}). If this is set to false, empty Lua tables will be encoded as empty JSON Arrays instead ([]).

This method either accepts a boolean or a string ("on", "off").

Back to TOC


syntax: cjson.empty_array

A lightuserdata, similar to cjson.null, which will be encoded as an empty JSON Array by cjson.encode().

For example, since encode_empty_table_as_object is true by default:

local cjson = require "cjson"

local json = cjson.encode({
    foo = "bar",
    some_object = {},
    some_array = cjson.empty_array

This will generate:

    "foo": "bar",
    "some_object": {},
    "some_array": []

Back to TOC


syntax: setmetatable({}, cjson.array_mt)

When lua-cjson encodes a table with this metatable, it will systematically encode it as a JSON Array. The resulting, encoded Array will contain the array part of the table, and will be of the same length as the # operator on that table. Holes in the table will be encoded with the null JSON value.


local t = { "hello", "world" }
setmetatable(t, cjson.array_mt)
cjson.encode(t) -- ["hello","world"]


local t = {}
t[1] = "one"
t[2] = "two"
t[4] = "three" = "bar"
setmetatable(t, cjson.array_mt)
cjson.encode(t) -- ["one","two",null,"three"]

This value was introduced in the release of this module.

Back to TOC


syntax: setmetatable({}, cjson.empty_array_mt)

A metatable which can "tag" a table as a JSON Array in case it is empty (that is, if the table has no elements, cjson.encode() will encode it as an empty JSON Array).

Instead of:

local function serialize(arr)
    if #arr < 1 then
        arr = cjson.empty_array

    return cjson.encode({some_array = arr})

This is more concise:

local function serialize(arr)
    setmetatable(arr, cjson.empty_array_mt)

    return cjson.encode({some_array = arr})

Both will generate:

    "some_array": []

Back to TOC


syntax: cjson.encode_number_precision(precision)

This fork allows encoding of numbers with a precision up to 16 decimals (vs. 14 in mpx/lua-cjson).

Back to TOC


syntax: cjson.decode_array_with_array_mt(enabled)

default: false

If enabled, JSON Arrays decoded by cjson.decode will result in Lua tables with the array_mt metatable. This can ensure a 1-to-1 relationship between arrays upon multiple encoding/decoding of your JSON data with this module.

If disabled, JSON Arrays will be decoded to plain Lua tables, without the array_mt metatable.

The enabled argument is a boolean.


local cjson = require "cjson"

-- default behavior
local my_json = [[{"my_array":[]}]]
local t = cjson.decode(my_json)
cjson.encode(t) -- {"my_array":{}} back to an object

-- now, if this behavior is enabled

local my_json = [[{"my_array":[]}]]
local t = cjson.decode(my_json)
cjson.encode(t) -- {"my_array":[]} properly re-encoded as an array

Back to TOC