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
  • decode_allow_comment

Description

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

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:

localcjson=require"cjson"localjson=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:

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

Or:

localt= {}
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:

localfunctionserialize(arr)
if#arr<1thenarr=cjson.empty_arrayendreturncjson.encode({some_array=arr})
end

This is more concise:

localfunctionserialize(arr)
setmetatable(arr, cjson.empty_array_mt)
returncjson.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:

localffi=require"ffi"localcjson=require"cjson"cjson.encode_skip_unsupported_value_types(true)
localt= {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:

localcjson=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:

localcjson=require"cjson"-- default behaviorlocalmy_json=[[{"my_array":[]}]]localt=cjson.decode(my_json)
cjson.encode(t) -- {"my_array":{}} back to an object-- now, if this behavior is enabledcjson.decode_array_with_array_mt(true)
localmy_json=[[{"my_array":[]}]]localt=cjson.decode(my_json)
cjson.encode(t) -- {"my_array":[]} properly re-encoded as an array

Back to TOC

decode_allow_comment

syntax:cjson.decode_allow_comment(enabled)

default: false

If enabled, allows JavaScript-style comments in cjson.decode input. Comments are treated as whitespace and may appear anywhere whitespace is valid in JSON. Supports single-line comments beginning with '//' and block comments enclosed with '/* ... */'.

Back to TOC