Name
====

lua-cjson - Fast JSON encoding/parsing

Table of Contents
=================

* [Name](#name)
* [Description](#description)
* [Additions to mpx/lua](#additions)
    * [encode_empty_table_as_object](#encode_empty_table_as_object)
    * [empty_array](#empty_array)
    * [array_mt](#array_mt)
    * [empty_array_mt](#empty_array_mt)
    * [encode_number_precision](#encode_number_precision)
    * [encode_escape_forward_slash](#encode_escape_forward_slash)
    * [decode_array_with_array_mt](#decode_array_with_array_mt)

Description
===========

This fork of [mpx/lua-cjson](https://github.com/mpx/lua-cjson) is included in
the [OpenResty](https://openresty.org/) 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](http://www.kyne.com.au/~mark/software/lua-cjson.php)
for standard usage, this README only provides informations regarding this fork's additions.

See [`mpx/master..openresty/master`](https://github.com/mpx/lua-cjson/compare/master...openresty:master)
for the complete history of changes.

[Back to TOC](#table-of-contents)

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](#table-of-contents)

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:

```lua
local cjson = require "cjson"

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

This will generate:

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

[Back to TOC](#table-of-contents)

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:

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

Or:

```lua
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](#table-of-contents)

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:

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

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

This is more concise:

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

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

Both will generate:

```json
{
    "some_array": []
}
```

[Back to TOC](#table-of-contents)

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](#table-of-contents)

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](#table-of-contents)

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`](#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:

```lua
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](#table-of-contents)