lua-cjson - Fast JSON encoding/parsing

• Name
• Description
• Additions to mpx/lua
  • encode_empty_table_as_object
  • empty_array
  • array_mt
  • empty_array_mt
  • encode_number_precision
  • encode_escape_forward_slash
  • decode_array_with_array_mt
  • decode_big_numbers_as_strings

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.

Example:

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

Or:

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

This value was introduced in the 2.1.0.5 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
    end

    return cjson.encode({some_array = arr})
end

This is more concise:

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

    return cjson.encode({some_array = arr})
end

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.encode_escape_forward_slash(enabled)

default: true

If enabled, forward slash '/' will be encoded as '\/'.

If disabled, forward slash '/' will be encoded as '/' (no escape is applied).

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.

Example:

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
cjson.decode_array_with_array_mt(true)

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

syntax: cjson.decode_big_numbers_as_strings(true|false)

Aas you know, Lua 5.1 uses one single number representation which can be chosen at compile time and since it is often set to IEEE 754 double precision floating point, one cannot store a 64 bit integer with full precision.

Default false. If this is set to true, then any numbers that may result in a precision loss will be preserved as a string.

Based on the commits: https://github.com/brimworks/lua-cjson/commit/48ab7055a1fa13a8f7e9a6242237a40f68f0f847 and https://github.com/yongboy/lua-cjson/commit/8f31894ce6ba0677d44b8abc2fc4a2adb6254922

Back to TOC