summaryrefslogtreecommitdiffhomepage
diff options
context:
space:
mode:
authorJo-Philipp Wich <jow@openwrt.org>2015-01-28 22:31:28 +0100
committerJo-Philipp Wich <jow@openwrt.org>2015-01-28 22:31:28 +0100
commitcf7e2695cc676dff02561a1a45d6de8140170b17 (patch)
tree6148dc6ae25945cc704062b624c2b19e33c198d3
parent7ca5222f4bd7a91ce58cc595f6082623045ebb22 (diff)
luci-lib-jsonc: add api documentation
Signed-off-by: Jo-Philipp Wich <jow@openwrt.org>
-rw-r--r--libs/luci-lib-jsonc/src/jsonc.luadoc134
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 0000000000..2ee9cebdc8
--- /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"}'`
+]]