Name

lua-cjson - Fast JSON encoding/parsing

Table of Contents

• 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
  • encode_skip_unsupported_value_types
  • encode_indent
  • decode_array_with_array_mt

Description

This is TES3MP's fork of OpenResty's fork of mpx/lua-cjson.

OpenResty's fork is included in the OpenResty bundle and includes a few bugfixes and improvements, especially to facilitate the encoding of empty tables as JSON Arrays.

TES3MP's fork of that aims to gradually provide additional configuration options to replicate the functionality of the otherwise much slower dkjson.

Please refer to the lua-cjson documentation for standard usage of the original project. This README only provides informations regarding the additions in the OpenResty and TES3MP forks.

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

Back to TOC

TES3MP Additions

decode_null_as_lightuserdata

syntax: cjson.decode_null_as_lightuserdata(true|false)

By default, null values in JSON files are converted to NULL lightuserdata values.

Setting this option to false makes them get converted to nil values instead.

Back to TOC

OpenResty Additions

encode_empty_table_as_object

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

empty_array

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

array_mt

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

empty_array_mt

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

encode_number_precision

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

encode_escape_forward_slash

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

encode_skip_unsupported_value_types

syntax: cjson.encode_skip_unsupported_value_types(enabled)

default: false

If enabled, cjson will not throw exception when there are unsupported types in the Lua table.

For example:

local ffi = require "ffi"
local cjson = require "cjson"
cjson.encode_skip_unsupported_value_types(true)
local t = {key = "val"}

t.cdata = ffi.new("char[?]", 100)
print(cjson.encode(t))

This will generate:

{"key":"val"}

Back to TOC

encode_indent

syntax: cjson.encode_indent(indent)

If non-empty string provided, JSON values encoded by cjson.encode() will be formatted in a human-readable way, using indent for indentation at each nesting level. Also enables newlines and a space after colons.

Example:

local cjson = require "cjson"

cjson.encode_indent("  ")
print(cjson.encode({ a = 1, b = { c = 2 } }))
-- {
--   "a": 1,
--   "b": {
--     "c": 2
--   }
-- }

Back to TOC

decode_array_with_array_mt

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

Back to TOC