luci-lib-jsonc: add api documentation

[project/luci.git] / libs / luci-lib-jsonc / src / jsonc.luadoc

diff --git a/libs/luci-lib-jsonc/src/jsonc.luadoc b/libs/luci-lib-jsonc/src/jsonc.luadoc
new file mode 100644 (file)
index 0000000..2ee9ceb
--- /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"}'`
+]]