Supported Lua Libraries

Standard Lua Libraries

Lua version: 5.3.5

Libraries that are implicitly loaded:

Name Reference

basic

https://www.lua.org/manual/5.3/manual.html#6.1

string

https://www.lua.org/manual/5.3/manual.html#6.4

table

https://www.lua.org/manual/5.3/manual.html#6.6

math

https://www.lua.org/manual/5.3/manual.html#6.7

package

https://www.lua.org/manual/5.3/manual.html#6.3

Libraries that need to be required:

Name Reference

utf8

https://www.lua.org/manual/5.3/manual.html#6.5

io

https://www.lua.org/manual/5.3/manual.html#6.8

os

https://www.lua.org/manual/5.3/manual.html#6.9

coroutine

https://www.lua.org/manual/5.3/manual.html#6.2

debug

https://www.lua.org/manual/5.3/manual.html#6.10

Extensions

rapidjson

Extended lua-rapidjson functions.

rapidjson.decode

rapidjson.decode(input [, parse_flags])

Description

Decodes JSON represented as a string to Lua table.

Return Type

Lua table if JSON is an object or array.
Return true, false, number and rapidjson.null respectively if JSON is a simple value.
On error returns nil and an error message as a second result when the passed string is not a valid JSON. If the error is returned as a second result, in addition to the encountered problem description, its location is shown as an offset in bytes. Can also raise Lua errors, in these cases, pcall can be used to catch the error.

For the decode function, the maximum depth of the JSON string is 256. If the decode function is used on a JSON string with a depth greater than 256, it will return an error.

Parameters

Name Type Optional Description

input

variant

no

Normally it’s a Lua table, but can also be a Boolean or a number.

parse_flags

number

yes

Optional bit mask.

parse_flags can be a combination of the following values

Value Description

0

No flags are set.

16

Parse number in full precision (but slower).

32

Allow one-line (//) and multi-line (/**/) comments. It is the default value.

256

Allow parsing NaN, Inf, Infinity, -Inf and -Infinity as doubles.

Examples

local JSON = require('rapidjson')

-- Don't use such stright comparison of floating point numbers in production.
return {
    full_precision = JSON.decode([[ { "abc":0.9868011474609375 } ]], 16).abc == 0.9868011474609375, -- true
           default = JSON.decode([[ { "abc":0.9868011474609375 } ]]    ).abc == 0.9868011474609375 -- false
}
local JSON = require('rapidjson')

return {JSON.decode([[ {
 "abc":1, // this is a one line comment
/* multi
"line":
"comment",
*/
"xyz": 2
} ]])} -- it is enabled by default

Result:

[{"abc":1,"xyz":2}]
local JSON = require('rapidjson')

return {JSON.decode([[ {
 "abc":1, // this is a one line comment
/* multi
"line":
"comment",
*/
"xyz": 2
} ]], 0)} -- explicitly disable comments

Result:

[null,"Missing a name for object member. (13)"]
local JSON = require('rapidjson')

local test_special_fp_nums = JSON.decode(
	[[{"valuePInf":Infinity,"valueNInf":-Infinity,"valuePInf2":Inf,"valueNInf2":-Inf,"valueNaN":NaN}]],
	256)
-- manually encode for Console in order to not be affected by its implementation of serialization
return JSON.encode(test_special_fp_nums, {write_flags=2, pretty=true})

Result:

{
    "valueNInf": -Infinity,
    "valueNaN": NaN,
    "valuePInf": Infinity,
    "valuePInf2": Infinity,
    "valueNInf2": -Infinity
}

rapidjson.dump

rapidjson.dump(input, file_path [, options])

Description

Writes Lua value into a JSON file. This function is a full equiualent to rapidjson.encode.

Return Type

Returns true on success.
Return nil on failure, plus an error message as a second result. Can raise Lua errors.

Parameters

Name Type Optional Description

input

variant

no

See rapidjson.encode.

file_path

string

no

A path to JSON file to write.

options

table

yes

See rapidjson.encode.

rapidjson.encode

rapidjson.encode(input [, options])

Description

Encodes Lua table to JSON string.

Return Type

String on success.
Return nil on failure, plus an error message as a second result. Can raise Lua errors.

Parameters

Name Type Optional Description

input

variant

no

Normally it’s a Lua table, but can also be a string, a Boolean, a number, or rapidjson.null.

options

table

yes

Optional table with fine tuning parameters.

options table can have the following fields

Name Type Description

pretty

Boolean

Set true to make output string to be pretty formated. Default is false.

sort_keys

Boolean

Set true to make JSON object keys be sorted. Default is false.

empty_table_as_array

Boolean

Set true to make empty table encode as JSON array. Default is false.

write_flags

Boolean

Set 2 to allow writing of Infinity, -Infinity and NaN values. Default is 0, and it throws an error if such values are encountered.
Note: non-standard field.

Examples

local JSON = require('rapidjson')

local testNaN = {
  valueNaN = 0/0,
  valueNInf = -1/0,
  valuePInf= 1/0
}

return JSON.encode(testNaN, {write_flags=2})

Result:

{"valueNInf":-Infinity,"valuePInf":Infinity,"valueNaN":NaN}

Compare with dkjson

local JSON = require('dkjson')

local testNaN = {
  valueNaN = 0/0,
  valueNInf = 1/0,
  valuePInf= -1/0
}

return JSON.encode(testNaN)

Result:

{"valueNaN":null,"valueNInf":null,"valuePInf":null}

rapidjson.load

rapidjson.load(file_path [, parse_flags])

Description

Loads JSON file into Lua table. This function is a full equiualent to rapidjson.decode.

Return Type

See rapidjson.decode.
Can raise Lua errors.

Parameters

Name Type Optional Description

file_path

string

no

A path to JSON file to load.

parse_flags

number

yes

Optional bit mask. See rapidjson.decode.