1 --- LuCI JSON parsing and serialization library.
2 -- The luci.jsonc class is a high level Lua binding to the JSON-C library to
3 -- allow reading and writing JSON data with minimal overhead.
7 Construct a new luci.jsonc.parser instance.
11 @return A `luci.jsonc.parser` object representing a JSON-C tokener.
12 @usage `parser = luci.jsonc.new()`
16 Parse a complete JSON string and convert it into a Lua data structure.
20 @param json A string containing the JSON data to parse, must be either a
21 JSON array or a JSON object.
22 @return On success, a table containing the parsed JSON data is returned, on
23 failure the function returns `nil` and a string containing the reason of
25 @usage `data = luci.jsonc.parse('{ "name": "John", "age": 34 }')
26 print(data.name) -- "John"`
31 Convert given Lua data into a JSON string.
33 This function recursively converts the given Lua data into a JSON string,
34 ignoring any unsupported data. Lua tables are converted into JSON arrays if they
35 only contain integer keys, mixed tables are turned into JSON objects with any
36 existing numeric keys converted into strings.
38 Lua functions, coroutines and userdata objects are ignored and Lua numbers are
39 converted to integers if they do not contain fractional values.
44 @param data The Lua data to convert, can be a table, string, boolean or number.
45 @param pretty A boolean value indicating whether the resulting JSON should be
47 @return Returns a string containing the JSON representation of the given Lua
49 @usage `json = luci.jsonc.stringify({ item = true, values = { 1, 2, 3 } })
50 print(json) -- '{"item":true,"values":[1,2,3]}'`
55 --- LuCI JSON parser instance.
56 -- A JSON parser instance is useful to parse JSON data chunk by chunk, without
57 -- the need to assemble all data in advance.
59 module "luci.jsonc.parser"
62 Parses one chunk of JSON data.
68 @param json String containing the JSON fragment to parse
70 <li>`true` if a complete JSON object has been parsed and no further input is
72 <li>`false` if further input is required</li>
73 <li>`nil` if an error was encountered while parsing the current chunk.
74 In this case a string describing the parse error is returned as second
76 @usage `parser = luci.jsonc.new()
79 chunk = ... -- fetch a cunk of data, e.g. from a socket
80 finish, errmsg = <b>parser.parse(chunk)</b>
83 error("Cannot parse JSON: " .. errmsg)
86 if finish == true then
93 Convert parsed JSON data into Lua table.
99 @return Parsed JSON object converted into a Lua table or `nil` if the parser
100 didn't finish or encountered an error.
101 @usage `parser = luci.jsonc.new()
102 parser:parse('{ "example": "test" }')
105 print(data.example) -- "test"`
109 Put Lua data into the parser.
114 @see parser.stringify
115 @param data Lua data to put into the parser object. The data is converted to an
116 internal JSON representation that can be dumped with `stringify()`.
117 The conversion follows the rules described in `luci.jsonc.stringify`.
118 @return Nothing is returned.
119 @usage `parser = luci.jsonc.new()
120 parser:set({ "some", "data" })`
124 Generate an ltn12-compatible sink.
129 @return Returns a function that can be used as an ltn12 sink.
130 @usage `parser = luci.jsonc.new()
131 ltn12.pump.all(ltn12.source.file(io.input()), parser:sink())
136 Serialize current parser state as JSON.
140 @name parser.stringify
141 @param pretty A boolean value indicating whether the resulting JSON should be pretty printed.
142 @return Returns the serialized JSON data of this parser instance.
143 @usage `parser = luci.jsonc.new()
144 parser:parse('{ "example": "test" }')
145 print(parser:serialize()) -- '{"example":"test"}'`