Use the RapidJSON module to encode and decode large documents quickly. It is similar to the standard JSON module, but can handle large amounts of data without risk of raising execution count errors.
To use the RapidJSON module, add the following line to your script:
rapidjson = require("rapidjson")
Note that you can assign any local variable name to the require("rapidjson")
object.
Encode a Lua table to JSON string. JSON object keys are sorted by this function.
The function supports the following types:
The function does not support:
string = rapidjson.encode(value [, option])
When passed as a table:
__jsontype
set to array
.When passed with true
, false
, number and rapidjson.null
, simply encode as a simple JSON value.
A optional table contains the following field:
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
.JSON string on success. Returns nil on failure, plus an error message as a second result.
local rapidjson = require('rapidjson') print( rapidjson.encode({}) ) -- '{}' print( rapidjson.encode(rapidjson.object()) ) --> '{}' print( rapidjson.encode(rapidjson.array()) ) --> '[]' print( rapidjson.encode(setmetatable({}, {__jsontype='object'})) ) --> '{}' print( rapidjson.encode(setmetatable({}, {__jsontype='array'})) ) --> '[]' print( rapidjson.encode(true) ) --> 'true' print( rapidjson.encode(rapidjson.null) ) --> 'null' print( rapidjson.encode(123) ) --> '123.0' or '123' in Lua 5.3. print( rapidjson.encode({true, false}) ) --> '[true, false]' print( rapidjson.encode({a=true, b=false}) ) --> '{"a":true,"b":false]'
Debug Output
{} {} [] {} [] true null 123 [true,false] {"a":true,"b":false}
rapidjson = require("rapidjson") function TablePretty(tbl,sort) return rapidjson.encode(tbl,{ pretty=true, sort_keys=sort }) end test = { ["Top Level Item"]={ Value=math.pi, Str="String", Options={1,2,3,4} -- an "array" } } print(TablePretty(test,true))
{ "Top Level Item": { "Options": [ 1, 2, 3, 4 ], "Str": "String", "Value": 3.141592653589793 } }
Decode JSON to a Lua table.
value = rapidjson.decode(jsonstring)
jsonstring : A JSON value string to be decoded.
Return table if JSON is an object or array.
Return true
, false
, number and rapidjson.null
respectively if JSON is a simple value.
Return nil plus an error message as a second result when passed string is not a valid JSON.
Load JSON file into Lua table.
value = rapidjson.load(filename)
filename : The JSON file to be loaded.
Return table if file contains an object or array.
Return true
, false
, number and rapidjson.null
respectively if file contains a simple value.
Return nil plus an error message as a second result when passed file is not valid JSON file.
Dump a Lua value to a JSON file.
success, err = rapidjson.dump(value, filename [, option])
value : Same as in rapidjson.encode()
.
filename : The file path string where to save the rapidjson string.
option : Same as in options in rapidjson.encode()
.
local rapidjson = require('rapidjson') rapidjson.dump({rapidjson.null}, 'media/test.json') rapidjson.dump({rapidjson.null}, 'media/test-pretty.json', {pretty=true})
Note: For security and stability reasons, the media/
folder (when running a design on a Core) and design/
folder (when emulating) and their subfolders are the only locations within the file system accessible by the Lua libraries.
The placeholder for null values in rapidjson.
local rapidjson = require('rapidjson') rapidjson.decode('[null]') --> {rapidjson.null} rapidjson.encode({rapidjson.null}) --> '[null]'
Create a new empty table that has the metatable field __jsontype
set as 'object'
so that the encode
and dump
function will encode it as a JSON object.
When passed a valid table:
__jsontype
to 'object'
.obj = rapidjson.object([t])
t : Optional table to set the metatable with meta field __jsontype
set as 'object'
.
Origin passed in table when passed with a table. Or new created table.
Same as rapidjson.object(), except the metatable field __jsontype
is set as 'array'
. The encode
and dump
function will encode it as JSON array.
See rapidjson.object() for usage.
Returns the RapidJSON name or version.
A string that is "rapidjson"
.
The current loaded rapidjson version. "scm"
when not built with luarocks.
Portions of this topic are reprinted under permission of the lua-rapidjson license.
Software and Firmware | Resources | QSC Self Help Portal | Q-SYS Help Feedback
Copyright © 2019 QSC, LLC. Click here for trademark and other legal notices. |