diff options
| -rw-r--r-- | libs/luci-lib-jsonc/src/jsonc.luadoc | 134 |
1 files changed, 134 insertions, 0 deletions
diff --git a/libs/luci-lib-jsonc/src/jsonc.luadoc b/libs/luci-lib-jsonc/src/jsonc.luadoc new file mode 100644 index 000000000..2ee9cebdc --- /dev/null +++ b/libs/luci-lib-jsonc/src/jsonc.luadoc @@ -0,0 +1,134 @@ +--- 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 <ul> + <li>`true` if a complete JSON object has been parsed and no further input is + expected.</li> + <li>`false` if further input is required</li> + <li>`nil` if an error was encountered while parsing the current chunk. + In this case a string describing the parse error is returned as second + value.</li></ul> +@usage `parser = luci.jsonc.new() + +while true do + chunk = ... -- fetch a cunk of data, e.g. from a socket + finish, errmsg = <b>parser.parse(chunk)</b> + + 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"}'` +]] |