Module json

Manipulation of JavaScript Object Notation (JSON) values.

Implementation from lua-cjson, with some additional modifications.

Features

  • Fast, standards compliant encoding/parsing routines

  • Full support for JSON with UTF-8, including decoding surrogate pairs

  • Optional run-time support for common exceptions to the JSON specification (infinity, NaN, etc.)

  • No dependencies on other libraries

Caveats

  • UTF-16 and UTF-32 are not supported

Settings

decode:invalid-numbers Configures handling of invalid numbers while decoding; numbers not supported by the JSON specification.
decode:max-depth Configures the maximum number of nested arrays/objects allowed when decoding.
encode:invalid-numbers Configures handling of invalid numbers while encoding; numbers not supported by the JSON specification.
encode:keep-buffer Determine whether or not the JSON encoding buffer should be reused after each call to encode.
encode:max-depth Configures the maximum number of nested arrays/objects allowed when encoding.
encode:number-precision Configures the amount of significant digits returned when encoding numbers.
encode:sparse-array Configures handling of extremely sparse arrays; lists with holes.

Functions

encode (t) Returns the given Lua table encoded as a JSON object.
decode (j) Returns the given JSON object decoded into a Lua table.
config (setting, ...) Gets/sets configuration values used when encoding or decoding JSON objects.
new () Creates and returns a new independent copy of the module, with default settings and a separate persistent encoding buffer.

Fields

_NAME The name of the module, provided for compatibility with lua-cjson.
_VERSION The version of lua-cjson used in the library.
null null value used when decoding JSON objects.


Settings

decode:invalid-numbers
Configures handling of invalid numbers while decoding; numbers not supported by the JSON specification. Invalid numbers are defined as:

  • infinity
  • NaN
  • hexadecimals

Parameters:

  • convert boolean Whether or not to accept and decode invalid numbers.

Usage:

    json.config("decode:invalid-numbers", false)
decode:max-depth
Configures the maximum number of nested arrays/objects allowed when decoding.

Parameters:

  • depth integer Max depth allowed when decoding.

Usage:

    json.config("decode:max-depth", 4)
encode:invalid-numbers
Configures handling of invalid numbers while encoding; numbers not supported by the JSON specification. Invalid numbers are defined as:

  • infinity
  • NaN
  • hexadecimals

Parameters:

  • convert boolean Whether or not to accept and encode invalid numbers.

Usage:

    json.config("encode:invalid-numbers", false)
encode:keep-buffer
Determine whether or not the JSON encoding buffer should be reused after each call to encode.

If true, the buffer will grow to the largest size required and is not freed until the module is garbage collected. This is the default setting.

If false, the encode buffer is freed after each call.

Parameters:

  • keep integer Whether or not the JSON encoding buffer should be reused.

Usage:

    json.config("encode:keep-buffer", false)
encode:max-depth
Configures the maximum number of nested arrays/objects allowed when encoding.

Parameters:

  • depth integer Max depth allowed when encoding.

Usage:

    json.config("encode:max-depth", 4)
encode:number-precision
Configures the amount of significant digits returned when encoding numbers. This can be used to balance accuracy versus performance.

Parameters:

  • precision integer Amount of significant digits to return in floating-point numbers (must be between 1 and 14, default 14)

Usage:

    json.config("encode:number-precision", 2)
encode:sparse-array
Configures handling of extremely sparse arrays; lists with holes.

Parameters:

  • safe integer Always use an array when the max index is larger than this value. (optional)
  • convert boolean Whether or not to convert extremely sparse arrays into objects. (optional)
  • ration integer 0: always allow sparse; 1: never allow sparse; >1: use ratio (optional)

Functions

encode (t)
Returns the given Lua table encoded as a JSON object.

Parameters:

  • t table The table to encode.

Usage:

    local t = {
	key = "value",
	x = 4,
	y = 16.789,
	t = {
		hello = "world"
	}
}
local j = json.encode(t)
decode (j)
Returns the given JSON object decoded into a Lua table.

Parameters:

  • j string The JSON object to decode.

Usage:

    local j = [[
{
	"key": "value",
	"x": 4,
	"y": 16.789,
	"obj": {
		"hello": "world"
	}
}
]]
local t = json.decode(j)
config (setting, ...)
Gets/sets configuration values used when encoding or decoding JSON objects.

The setting paramater is a string containing either "encode:" or "decode:", followed by the name of the setting. Available settings can be found in the Settings section.

The current setting is always returned, and is only updated when an argument is provided.

Parameters:

  • setting string The setting to get/set.
  • ...

Usage:

    json.config("encode:max-depth", 3)
new ()
Creates and returns a new independent copy of the module, with default settings and a separate persistent encoding buffer.

Fields

_NAME
The name of the module, provided for compatibility with lua-cjson. Normally this will just be "json".
  • _NAME
_VERSION
The version of lua-cjson used in the library.
  • _VERSION
null
null value used when decoding JSON objects.

JSON null is decoded as a Lua lightuserdata NULL pointer. json.null is provided for comparison.

  • null
generated by LDoc 1.4.6 Last updated 2023-12-27 20:06:03