Lua CJSON

https://kyne.au/~mark/software/lua-cjson-manual.html
Admin
Lua CJSON is a module that provides fast, standards-compliant JSON encoding and parsing support for...
Tokens:3,124
Snippets:45
Trust Score:5.3
Update:2 months ago
Show doc for...
Tokens:
Raw
### Build and Install via RPM

Source: https://kyne.au/~mark/software/lua-cjson-manual.html

Create and install an RPM package on Linux distributions.

```bash
rpmbuild -tb lua-cjson-2.1.0.tar.gz
rpm -Uvh $LUA_CJSON_RPM
```

--------------------------------

### Install via Make

Source: https://kyne.au/~mark/software/lua-cjson-manual.html

Standard installation command for Unix and Windows platforms using the provided Makefile.

```bash
make install
```

```bash
make
cp cjson.so $LUA_MODULE_DIRECTORY
```

--------------------------------

### Install via LuaRocks

Source: https://kyne.au/~mark/software/lua-cjson-manual.html

Use the LuaRocks package manager to build and install the module.

```bash
cd lua-cjson-2.1.0
luarocks make
```

--------------------------------

### Example: Encoding a table

Source: https://kyne.au/~mark/software/lua-cjson-manual.html

Demonstrates encoding a nested Lua table into a JSON string.

```lua
value = { true, { foo = "bar" } }
json_text = cjson.encode(value)
-- Returns: '[true,{"foo":"bar"}]'
```

--------------------------------

### Example: Recursive Lua table

Source: https://kyne.au/~mark/software/lua-cjson-manual.html

A table structure that would exceed the default recursion depth limit.

```lua
a = {}; a[1] = a
```

--------------------------------

### Configure and Build via CMake

Source: https://kyne.au/~mark/software/lua-cjson-manual.html

Generate build configuration and compile the module using CMake.

```bash
mkdir build
cd build
# Optional: export LUA_DIR=$LUA51_PREFIX
cmake ..
```

```bash
make install
# Or:
make
cp cjson.so $LUA_MODULE_DIRECTORY
```

--------------------------------

### Instantiate Lua CJSON Module

Source: https://kyne.au/~mark/software/lua-cjson-manual.html

Methods for importing the standard module, a safe variant, or creating an independent instance.

```lua
`local cjson = require "cjson"
local cjson2 = cjson.new()
local cjson_safe = require "cjson.safe"`
```

--------------------------------

### Lua CJSON API Synopsis

Source: https://kyne.au/~mark/software/lua-cjson-manual.html

Overview of the primary functions and configuration methods available in the Lua CJSON module.

```lua
`-- Module instantiation
local cjson = require "cjson"
local cjson2 = cjson.new()
local cjson_safe = require "cjson.safe"

-- Translate Lua value to/from JSON
text = cjson.encode(value)
value = cjson.decode(text)

-- Get and/or set Lua CJSON configuration
setting = cjson.decode_invalid_numbers([setting])
setting = cjson.encode_invalid_numbers([setting])
keep = cjson.encode_keep_buffer([keep])
depth = cjson.encode_max_depth([depth])
depth = cjson.decode_max_depth([depth])
convert, ratio, safe = cjson.encode_sparse_array([convert[, ratio[, safe]]])`
```

--------------------------------

### Encode a sparse array

Source: https://kyne.au/~mark/software/lua-cjson-manual.html

Demonstrates the default behavior of encoding a sparse Lua table into a JSON array using null values.

```lua
`cjson.encode({ [3] = "data" })
-- Returns: '[null,null,"data"]'`
```

--------------------------------

### Configure buffer reuse

Source: https://kyne.au/~mark/software/lua-cjson-manual.html

Toggles whether the JSON encoding buffer is reused between calls to improve performance.

```lua
keep = cjson.encode_keep_buffer([keep])
-- "keep" must be a boolean. Default: true.
```

--------------------------------

### Enable conversion of excessively sparse arrays

Source: https://kyne.au/~mark/software/lua-cjson-manual.html

Configures the encoder to treat excessively sparse arrays as JSON objects instead of throwing an error.

```lua
`cjson.encode_sparse_array(true)
cjson.encode({ [1000] = "excessively sparse" })
-- Returns: '{"1000":"excessively sparse"}'`
```

--------------------------------

### Configure sparse array encoding

Source: https://kyne.au/~mark/software/lua-cjson-manual.html

Configures how Lua tables with missing indices are handled during JSON array encoding.

```lua
`convert, ratio, safe = cjson.encode_sparse_array([convert[, ratio[, safe]]])
-- "convert" must be a boolean. Default: false.
-- "ratio" must be a positive integer. Default: 2.
-- "safe" must be a positive integer. Default: 10.`
```

--------------------------------

### Configure maximum recursion depth

Source: https://kyne.au/~mark/software/lua-cjson-manual.html

Sets the maximum nesting depth for tables to prevent stack overflow errors.

```lua
depth = cjson.encode_max_depth([depth])
-- "depth" must be a positive integer. Default: 1000.
```

--------------------------------

### Configure invalid number handling

Source: https://kyne.au/~mark/software/lua-cjson-manual.html

Sets how the encoder handles infinity or NaN values. Default is false (throw error).

```lua
setting = cjson.encode_invalid_numbers([setting])
-- "setting" must a boolean or "null". Default: false.
```

--------------------------------

### cjson.decode

Source: https://kyne.au/~mark/software/lua-cjson-manual.html

Deserializes a UTF-8 JSON string into a Lua value or table.

```APIDOC
## cjson.decode(json_text)

### Description
Deserializes a UTF-8 JSON string into a Lua value or table. JSON `null` is converted to a NULL `lightuserdata` value.

### Parameters
- **json_text** (string) - Required - The JSON string to decode.

### Returns
- **value** (table/value) - The resulting Lua value or table.
```

--------------------------------

### Set Maximum Decoding Depth

Source: https://kyne.au/~mark/software/lua-cjson-manual.html

Configures the maximum nesting depth for arrays and objects to prevent stack overflow or performance issues.

```lua
`depth = cjson.decode_max_depth([depth])
-- "depth" must be a positive integer. Default: 1000.`
```

--------------------------------

### cjson.encode_sparse_array

Source: https://kyne.au/~mark/software/lua-cjson-manual.html

Configures how Lua CJSON handles sparse arrays during encoding.

```APIDOC
## cjson.encode_sparse_array([convert[, ratio[, safe]]])

### Description
Configures the behavior for encoding sparse Lua tables as JSON arrays. Allows control over whether excessively sparse arrays are converted to JSON objects or encoded with null values.

### Parameters
- **convert** (boolean) - Optional - If true, excessively sparse arrays are converted to JSON objects. Default: false.
- **ratio** (integer) - Optional - Positive integer used to determine if an array is excessively sparse. Default: 2.
- **safe** (integer) - Optional - Positive integer to ensure small arrays are always encoded as sparse. Default: 10.

### Returns
- **convert, ratio, safe** (tuple) - The current settings for sparse array encoding.
```

--------------------------------

### cjson.encode_max_depth

Source: https://kyne.au/~mark/software/lua-cjson-manual.html

Sets the maximum nesting depth for tables to prevent stack overflow errors.

```APIDOC
## cjson.encode_max_depth([depth])

### Description
Sets or retrieves the maximum table depth. Default is 1000.

### Parameters
- **depth** (integer) - Optional - The maximum number of nested tables allowed.
```

--------------------------------

### Configure Invalid Number Decoding

Source: https://kyne.au/~mark/software/lua-cjson-manual.html

Sets whether the decoder accepts non-standard JSON numbers like infinity, NaN, or hexadecimal values.

```lua
`setting = cjson.decode_invalid_numbers([setting])
-- "setting" must be a boolean. Default: true.`
```

--------------------------------

### cjson.decode_max_depth

Source: https://kyne.au/~mark/software/lua-cjson-manual.html

Configures the maximum nesting depth for JSON objects and arrays during decoding.

```APIDOC
## cjson.decode_max_depth([depth])

### Description
Sets or retrieves the maximum allowed nesting depth for arrays and objects. This prevents stack overflow or performance issues with deeply nested JSON.

### Parameters
- **depth** (integer) - Optional - A positive integer representing the maximum depth. Defaults to 1000.
```

--------------------------------

### Configure number precision

Source: https://kyne.au/~mark/software/lua-cjson-manual.html

Sets the number of significant digits for numeric encoding. The precision must be an integer between 1 and 14.

```lua
`precision = cjson.encode_number_precision([precision])
-- "precision" must be an integer between 1 and 14. Default: 14.`
```

--------------------------------

### cjson.encode

Source: https://kyne.au/~mark/software/lua-cjson-manual.html

Serializes a Lua value into a string containing the JSON representation.

```APIDOC
## cjson.encode(value)

### Description
Serializes a Lua value into a JSON string. Supports boolean, nil, number, string, and table types.

### Parameters
- **value** (any) - Required - The Lua value to serialize.

### Returns
- **json_text** (string) - The resulting JSON string.
```

--------------------------------

### cjson.encode_keep_buffer

Source: https://kyne.au/~mark/software/lua-cjson-manual.html

Configures whether the JSON encoding buffer is reused to improve performance.

```APIDOC
## cjson.encode_keep_buffer([keep])

### Description
Sets or retrieves the buffer reuse setting. Default is true.

### Parameters
- **keep** (boolean) - Optional - 'true' to keep buffer, 'false' to free it after each call.
```

--------------------------------

### Encode Lua value to JSON string

Source: https://kyne.au/~mark/software/lua-cjson-manual.html

Serializes a Lua value into a JSON string representation.

```lua
json_text = cjson.encode(value)
```

--------------------------------

### Decode JSON String

Source: https://kyne.au/~mark/software/lua-cjson-manual.html

Deserializes a JSON string into a Lua value or table. Note that numeric keys in JSON objects are stored as strings in Lua.

```lua
`value = cjson.decode(json_text)`
```

```lua
`json_text = '[ true, { "foo": "bar" } ]'
value = cjson.decode(json_text)
-- Returns: { true, { foo = "bar" } }`
```

--------------------------------

### cjson.encode_invalid_numbers

Source: https://kyne.au/~mark/software/lua-cjson-manual.html

Configures how Lua CJSON handles floating point numbers not supported by the JSON specification (infinity, NaN).

```APIDOC
## cjson.encode_invalid_numbers([setting])

### Description
Sets or retrieves the behavior for encoding invalid numbers. Default is false.

### Parameters
- **setting** (boolean|string) - Optional - 'true' to allow, 'null' to encode as JSON null, 'false' to throw an error.
```

--------------------------------

### cjson.decode_invalid_numbers

Source: https://kyne.au/~mark/software/lua-cjson-manual.html

Configures whether the decoder accepts numbers not supported by the JSON specification (infinity, NaN, hexadecimal).

```APIDOC
## cjson.decode_invalid_numbers([setting])

### Description
Sets or retrieves the configuration for handling invalid numbers during decoding. Invalid numbers include infinity, NaN, and hexadecimal values.

### Parameters
- **setting** (boolean) - Optional - If true, invalid numbers are accepted. If false, an error is thrown. Defaults to true.
```

--------------------------------

### cjson.encode_number_precision

Source: https://kyne.au/~mark/software/lua-cjson-manual.html

Sets or retrieves the number of significant digits used when encoding numbers to JSON.

```APIDOC
## cjson.encode_number_precision([precision])

### Description
Sets the amount of significant digits returned by Lua CJSON when encoding numbers. This can be used to balance accuracy versus performance.

### Parameters
- **precision** (integer) - Optional - An integer between 1 and 14. Default is 14.

### Returns
- **precision** (integer) - The current or updated precision setting.
```
Tokens:
Raw