4c19cf0e5951a7c73f6afa08814912b55a40cae4
[project/luci.git] / documentation / api / modules / luci.jsonc.parser.html
1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
2    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
3 <html>
4 <head>
5     <title>Reference</title>
6     <link rel="stylesheet" href="../luadoc.css" type="text/css" />
7         <!--meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/-->
8 </head>
9
10 <body>
11 <div id="container">
12
13 <div id="product">
14         <div id="product_logo"></div>
15         <div id="product_name"><big><b></b></big></div>
16         <div id="product_description"></div>
17 </div> <!-- id="product" -->
18
19 <div id="main">
20
21 <div id="navigation">
22
23
24 <h1>LuaDoc</h1>
25 <ul>
26         
27         <li><a href="../index.html">Index</a></li>
28         
29 </ul>
30
31
32 <!-- Module list -->
33
34 <h1>Modules</h1>
35 <ul>
36
37         <li>
38                 <a href="../modules/luci.dispatcher.html">luci.dispatcher</a>
39         </li>
40
41         <li>
42                 <a href="../modules/luci.http.html">luci.http</a>
43         </li>
44
45         <li>
46                 <a href="../modules/luci.http.protocol.html">luci.http.protocol</a>
47         </li>
48
49         <li>
50                 <a href="../modules/luci.http.protocol.conditionals.html">luci.http.protocol.conditionals</a>
51         </li>
52
53         <li>
54                 <a href="../modules/luci.http.protocol.date.html">luci.http.protocol.date</a>
55         </li>
56
57         <li>
58                 <a href="../modules/luci.http.protocol.mime.html">luci.http.protocol.mime</a>
59         </li>
60
61         <li>
62                 <a href="../modules/luci.i18n.html">luci.i18n</a>
63         </li>
64
65         <li>
66                 <a href="../modules/luci.ip.html">luci.ip</a>
67         </li>
68
69         <li>
70                 <a href="../modules/luci.ip.cidr.html">luci.ip.cidr</a>
71         </li>
72
73         <li>
74                 <a href="../modules/luci.json.html">luci.json</a>
75         </li>
76
77         <li>
78                 <a href="../modules/luci.jsonc.html">luci.jsonc</a>
79         </li>
80
81         <li><strong>luci.jsonc.parser</strong></li>
82         
83         <li>
84                 <a href="../modules/luci.model.ipkg.html">luci.model.ipkg</a>
85         </li>
86
87         <li>
88                 <a href="../modules/luci.model.uci.html">luci.model.uci</a>
89         </li>
90
91         <li>
92                 <a href="../modules/luci.rpcc.html">luci.rpcc</a>
93         </li>
94
95         <li>
96                 <a href="../modules/luci.rpcc.ruci.html">luci.rpcc.ruci</a>
97         </li>
98
99         <li>
100                 <a href="../modules/luci.sys.html">luci.sys</a>
101         </li>
102
103         <li>
104                 <a href="../modules/luci.sys.init.html">luci.sys.init</a>
105         </li>
106
107         <li>
108                 <a href="../modules/luci.sys.iptparser.html">luci.sys.iptparser</a>
109         </li>
110
111         <li>
112                 <a href="../modules/luci.sys.net.html">luci.sys.net</a>
113         </li>
114
115         <li>
116                 <a href="../modules/luci.sys.process.html">luci.sys.process</a>
117         </li>
118
119         <li>
120                 <a href="../modules/luci.sys.user.html">luci.sys.user</a>
121         </li>
122
123         <li>
124                 <a href="../modules/luci.sys.wifi.html">luci.sys.wifi</a>
125         </li>
126
127         <li>
128                 <a href="../modules/luci.util.html">luci.util</a>
129         </li>
130
131         <li>
132                 <a href="../modules/nixio.html">nixio</a>
133         </li>
134
135         <li>
136                 <a href="../modules/nixio.CHANGELOG.html">nixio.CHANGELOG</a>
137         </li>
138
139         <li>
140                 <a href="../modules/nixio.CryptoHash.html">nixio.CryptoHash</a>
141         </li>
142
143         <li>
144                 <a href="../modules/nixio.File.html">nixio.File</a>
145         </li>
146
147         <li>
148                 <a href="../modules/nixio.README.html">nixio.README</a>
149         </li>
150
151         <li>
152                 <a href="../modules/nixio.Socket.html">nixio.Socket</a>
153         </li>
154
155         <li>
156                 <a href="../modules/nixio.TLSContext.html">nixio.TLSContext</a>
157         </li>
158
159         <li>
160                 <a href="../modules/nixio.TLSSocket.html">nixio.TLSSocket</a>
161         </li>
162
163         <li>
164                 <a href="../modules/nixio.UnifiedIO.html">nixio.UnifiedIO</a>
165         </li>
166
167         <li>
168                 <a href="../modules/nixio.bin.html">nixio.bin</a>
169         </li>
170
171         <li>
172                 <a href="../modules/nixio.bit.html">nixio.bit</a>
173         </li>
174
175         <li>
176                 <a href="../modules/nixio.crypto.html">nixio.crypto</a>
177         </li>
178
179         <li>
180                 <a href="../modules/nixio.fs.html">nixio.fs</a>
181         </li>
182
183 </ul>
184
185
186
187 <!-- File list -->
188
189
190
191
192
193
194
195 </div><!-- id="navigation" -->
196
197 <div id="content">
198
199 <h1>Object Instance <code>luci.jsonc.parser</code></h1>
200
201 <p>
202  LuCI JSON parser instance. 
203  A JSON parser instance is useful to parse JSON data chunk by chunk, without 
204  the need to assemble all data in advance.</p>
205
206
207
208
209
210
211
212 <h2>Functions</h2>
213 <table class="function_list">
214
215         <tr>
216         <td class="name" nowrap><a href="#parser.parse">parser:parse</a>&nbsp;(json)</td>
217         <td class="summary">
218  
219 Parses one chunk of JSON data.</td>
220         </tr>
221
222         <tr>
223         <td class="name" nowrap><a href="#parser.get">parser:get</a>&nbsp;()</td>
224         <td class="summary">
225  
226 Convert parsed JSON data into Lua table.</td>
227         </tr>
228
229         <tr>
230         <td class="name" nowrap><a href="#parser.set">parser:set</a>&nbsp;(data)</td>
231         <td class="summary">
232  
233 Put Lua data into the parser.</td>
234         </tr>
235
236         <tr>
237         <td class="name" nowrap><a href="#parser.stringify">parser:stringify</a>&nbsp;(pretty)</td>
238         <td class="summary">
239  
240 Serialize current parser state as JSON.</td>
241         </tr>
242
243 </table>
244
245
246
247
248
249
250 <br/>
251 <br/>
252
253
254 <h2><a name="functions"></a>Functions</h2>
255 <dl class="function">
256
257
258
259 <dt><a name="parser.parse"></a><strong>parser:parse</strong>&nbsp;(json)</dt>
260 <dd>
261
262  
263 Parses one chunk of JSON data. 
264
265
266
267 <h3>Parameters</h3>
268 <ul>
269         
270         <li>
271           json: String containing the JSON fragment to parse
272         </li>
273         
274 </ul>
275
276
277
278
279 <h3>Usage:</h3>
280 <pre>parser = luci.jsonc.new() 
281  
282 while true do 
283         chunk = ...  -- fetch a cunk of data, e.g. from a socket 
284         finish, errmsg = <b>parser.parse(chunk)</b> 
285  
286         if finish == nil then 
287                 error("Cannot parse JSON: " .. errmsg) 
288         end 
289  
290         if finish == true then 
291                 break 
292         end 
293 end</pre>
294
295
296
297 <h3>Return value:</h3>
298 <ul> 
299         <li><code>true</code> if a complete JSON object has been parsed and no further input is 
300             expected.</li> 
301         <li><code>false</code> if further input is required</li> 
302         <li><code>nil</code> if an error was encountered while parsing the current chunk. 
303             In this case a string describing the parse error is returned as second 
304             value.</li></ul>
305
306
307
308 <h3>See also:</h3>
309 <ul>
310         
311         <li><a href="#parser.get">
312                 parser:get
313         </a>
314         
315 </ul>
316
317 </dd>
318
319
320
321
322 <dt><a name="parser.get"></a><strong>parser:get</strong>&nbsp;()</dt>
323 <dd>
324
325  
326 Convert parsed JSON data into Lua table. 
327
328
329
330
331
332
333 <h3>Usage:</h3>
334 <pre>parser = luci.jsonc.new() 
335 parser:parse('{ "example": "test" }') 
336  
337 data = parser:get() 
338 print(data.example)  -- "test"</pre>
339
340
341
342 <h3>Return value:</h3>
343 Parsed JSON object converted into a Lua table or <code>nil</code> if the parser 
344         didn't finish or encountered an error.
345
346
347
348 <h3>See also:</h3>
349 <ul>
350         
351         <li><a href="#parser.parse">
352                 parser:parse
353         </a>
354         
355 </ul>
356
357 </dd>
358
359
360
361
362 <dt><a name="parser.set"></a><strong>parser:set</strong>&nbsp;(data)</dt>
363 <dd>
364
365  
366 Put Lua data into the parser. 
367
368
369
370 <h3>Parameters</h3>
371 <ul>
372         
373         <li>
374           data: Lua data to put into the parser object. The data is converted to an 
375         internal JSON representation that can be dumped with <code>stringify()</code>. 
376         The conversion follows the rules described in <code>luci.jsonc.stringify</code>.
377         </li>
378         
379 </ul>
380
381
382
383
384 <h3>Usage:</h3>
385 <pre>parser = luci.jsonc.new() 
386 parser:set({ "some", "data" })</pre>
387
388
389
390 <h3>Return value:</h3>
391 Nothing is returned.
392
393
394
395 <h3>See also:</h3>
396 <ul>
397         
398         <li><a href="#parser.stringify">
399                 parser:stringify
400         </a>
401         
402 </ul>
403
404 </dd>
405
406
407
408
409 <dt><a name="parser.stringify"></a><strong>parser:stringify</strong>&nbsp;(pretty)</dt>
410 <dd>
411
412  
413 Serialize current parser state as JSON. 
414
415
416
417 <h3>Parameters</h3>
418 <ul>
419         
420         <li>
421           pretty: A boolean value indicating whether the resulting JSON should be pretty printed.
422         </li>
423         
424 </ul>
425
426
427
428
429 <h3>Usage:</h3>
430 <pre>parser = luci.jsonc.new() 
431 parser:parse('{ "example": "test" }') 
432 print(parser:serialize())  -- '{"example":"test"}'</pre>
433
434
435
436 <h3>Return value:</h3>
437 Returns the serialized JSON data of this parser instance.
438
439
440
441 </dd>
442
443
444 </dl>
445
446
447
448
449
450 </div> <!-- id="content" -->
451
452 </div> <!-- id="main" -->
453
454 <div id="about">
455         <p><a href="http://validator.w3.org/check?uri=referer"><img src="http://www.w3.org/Icons/valid-xhtml10" alt="Valid XHTML 1.0!" height="31" width="88" /></a></p>
456 </div> <!-- id="about" -->
457
458 </div> <!-- id="container" -->
459 </body>
460 </html>