Merge pull request #416 from fabio70mi/patch-1
[project/luci.git] / libs / luci-lib-jsonc / src / jsonc.luadoc
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.
4 module "luci.jsonc"
5
6 ---[[
7 Construct a new luci.jsonc.parser instance.
8 @class function
9 @sort 1
10 @name new
11 @return A `luci.jsonc.parser` object representing a JSON-C tokener.
12 @usage `parser = luci.jsonc.new()`
13 ]]
14
15 ---[[
16 Parse a complete JSON string and convert it into a Lua data structure.
17 @class function
18 @sort 2
19 @name parse
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
24         the parse error.
25 @usage `data = luci.jsonc.parse('{ "name": "John", "age": 34 }')
26 print(data.name)  -- "John"`
27 @see stringify
28 ]]
29
30 ---[[
31 Convert given Lua data into a JSON string.
32
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.
37
38 Lua functions, coroutines and userdata objects are ignored and Lua numbers are
39 converted to integers if they do not contain fractional values.
40
41 @class function
42 @sort 3
43 @name stringify
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
46         pretty printed.
47 @return Returns a string containing the JSON representation of the given Lua
48         data.
49 @usage `json = luci.jsonc.stringify({ item = true, values = { 1, 2, 3 } })
50 print(json)  -- '{"item":true,"values":[1,2,3]}'`
51 @see parse
52 ]]
53
54
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.
58 -- @cstyle instance
59 module "luci.jsonc.parser"
60
61 ---[[
62 Parses one chunk of JSON data.
63
64 @class function
65 @sort 1
66 @name parser.parse
67 @see parser.get
68 @param json  String containing the JSON fragment to parse
69 @return <ul>
70         <li>`true` if a complete JSON object has been parsed and no further input is
71             expected.</li>
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
75             value.</li></ul>
76 @usage `parser = luci.jsonc.new()
77
78 while true do
79         chunk = ...  -- fetch a cunk of data, e.g. from a socket
80         finish, errmsg = <b>parser.parse(chunk)</b>
81
82         if finish == nil then
83                 error("Cannot parse JSON: " .. errmsg)
84         end
85
86         if finish == true then
87                 break
88         end
89 end`
90 ]]
91
92 ---[[
93 Convert parsed JSON data into Lua table.
94
95 @class function
96 @sort 2
97 @name parser.get
98 @see parser.parse
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" }')
103
104 data = parser:get()
105 print(data.example)  -- "test"`
106 ]]
107
108 ---[[
109 Put Lua data into the parser.
110
111 @class function
112 @sort 3
113 @name parser.set
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" })`
121 ]]
122
123 ---[[
124 Serialize current parser state as JSON.
125
126 @class function
127 @sort 4
128 @name parser.stringify
129 @param pretty A boolean value indicating whether the resulting JSON should be pretty printed.
130 @return Returns the serialized JSON data of this parser instance.
131 @usage `parser = luci.jsonc.new()
132 parser:parse('{ "example": "test" }')
133 print(parser:serialize())  -- '{"example":"test"}'`
134 ]]