--- 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" })`
]]

---[[
Generate an ltn12-compatible sink.

@class function
@sort 4
@name parser.sink
@return Returns a function that can be used as an ltn12 sink.
@usage `parser = luci.jsonc.new()
ltn12.pump.all(ltn12.source.file(io.input()), parser:sink())
print(parser:get())`
]]

---[[
Serialize current parser state as JSON.

@class function
@sort 5
@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"}'`
]]