--- LuCI JSON parsing and serialization library. -- The luci.jsonc class is a high level Lua binding to the JSON-C library to -- allow reading and writing JSON data with minimal overhead. module "luci.jsonc" ---[[ Construct a new luci.jsonc.parser instance. @class function @sort 1 @name new @return A `luci.jsonc.parser` object representing a JSON-C tokener. @usage `parser = luci.jsonc.new()` ]] ---[[ Parse a complete JSON string and convert it into a Lua data structure. @class function @sort 2 @name parse @param json A string containing the JSON data to parse, must be either a JSON array or a JSON object. @return On success, a table containing the parsed JSON data is returned, on failure the function returns `nil` and a string containing the reason of the parse error. @usage `data = luci.jsonc.parse('{ "name": "John", "age": 34 }') print(data.name) -- "John"` @see stringify ]] ---[[ Convert given Lua data into a JSON string. This function recursively converts the given Lua data into a JSON string, ignoring any unsupported data. Lua tables are converted into JSON arrays if they only contain integer keys, mixed tables are turned into JSON objects with any existing numeric keys converted into strings. Lua functions, coroutines and userdata objects are ignored and Lua numbers are converted to integers if they do not contain fractional values. @class function @sort 3 @name stringify @param data The Lua data to convert, can be a table, string, boolean or number. @param pretty A boolean value indicating whether the resulting JSON should be pretty printed. @return Returns a string containing the JSON representation of the given Lua data. @usage `json = luci.jsonc.stringify({ item = true, values = { 1, 2, 3 } }) print(json) -- '{"item":true,"values":[1,2,3]}'` @see parse ]] --- LuCI JSON parser instance. -- A JSON parser instance is useful to parse JSON data chunk by chunk, without -- the need to assemble all data in advance. -- @cstyle instance module "luci.jsonc.parser" ---[[ Parses one chunk of JSON data. @class function @sort 1 @name parser.parse @see parser.get @param json String containing the JSON fragment to parse @return @usage `parser = luci.jsonc.new() while true do chunk = ... -- fetch a cunk of data, e.g. from a socket finish, errmsg = parser.parse(chunk) if finish == nil then error("Cannot parse JSON: " .. errmsg) end if finish == true then break end end` ]] ---[[ Convert parsed JSON data into Lua table. @class function @sort 2 @name parser.get @see parser.parse @return Parsed JSON object converted into a Lua table or `nil` if the parser didn't finish or encountered an error. @usage `parser = luci.jsonc.new() parser:parse('{ "example": "test" }') data = parser:get() print(data.example) -- "test"` ]] ---[[ Put Lua data into the parser. @class function @sort 3 @name parser.set @see parser.stringify @param data Lua data to put into the parser object. The data is converted to an internal JSON representation that can be dumped with `stringify()`. The conversion follows the rules described in `luci.jsonc.stringify`. @return Nothing is returned. @usage `parser = luci.jsonc.new() parser:set({ "some", "data" })` ]] ---[[ Serialize current parser state as JSON. @class function @sort 4 @name parser.stringify @param pretty A boolean value indicating whether the resulting JSON should be pretty printed. @return Returns the serialized JSON data of this parser instance. @usage `parser = luci.jsonc.new() parser:parse('{ "example": "test" }') print(parser:serialize()) -- '{"example":"test"}'` ]]