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 Generate an ltn12-compatible sink.
 125
 126 @class function
 127 @sort 4
 128 @name parser.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())
 132 print(parser:get())`
 133 ]]
 134
 135 ---[[
 136 Serialize current parser state as JSON.
 137
 138 @class function
 139 @sort 5
 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"}'`
 146 ]]