diff options
Diffstat (limited to 'manual.adoc')
-rw-r--r-- | manual.adoc | 613 |
1 files changed, 613 insertions, 0 deletions
diff --git a/manual.adoc b/manual.adoc new file mode 100644 index 0000000..83303a3 --- /dev/null +++ b/manual.adoc | |||
@@ -0,0 +1,613 @@ | |||
1 | = Lua CJSON 2.1devel Manual = | ||
2 | Mark Pulford <mark@kyne.com.au> | ||
3 | :revdate: August 2016 | ||
4 | |||
5 | Overview | ||
6 | -------- | ||
7 | |||
8 | The Lua CJSON module provides JSON support for Lua. | ||
9 | |||
10 | *Features*:: | ||
11 | - Fast, standards compliant encoding/parsing routines | ||
12 | - Full support for JSON with UTF-8, including decoding surrogate pairs | ||
13 | - Optional run-time support for common exceptions to the JSON | ||
14 | specification (infinity, NaN,..) | ||
15 | - No dependencies on other libraries | ||
16 | |||
17 | *Caveats*:: | ||
18 | - UTF-16 and UTF-32 are not supported | ||
19 | |||
20 | Lua CJSON is covered by the MIT license. Review the file +LICENSE+ for | ||
21 | details. | ||
22 | |||
23 | The current stable version of this software is available from the | ||
24 | http://www.kyne.com.au/%7Emark/software/lua-cjson.php[Lua CJSON website]. | ||
25 | |||
26 | Feel free to email me if you have any patches, suggestions, or comments. | ||
27 | |||
28 | |||
29 | Installation | ||
30 | ------------ | ||
31 | |||
32 | Lua CJSON requires either http://www.lua.org[Lua] 5.1, Lua 5.2, Lua 5.3, | ||
33 | or http://www.luajit.org[LuaJIT] to build. | ||
34 | |||
35 | The build method can be selected from 4 options: | ||
36 | |||
37 | Make:: Unix (including Linux, BSD, Mac OSX & Solaris), Windows | ||
38 | CMake:: Unix, Windows | ||
39 | RPM:: Linux | ||
40 | LuaRocks:: Unix, Windows | ||
41 | |||
42 | |||
43 | Make | ||
44 | ~~~~ | ||
45 | |||
46 | The included +Makefile+ has generic settings. | ||
47 | |||
48 | First, review and update the included makefile to suit your platform (if | ||
49 | required). | ||
50 | |||
51 | Next, build and install the module: | ||
52 | |||
53 | [source,sh] | ||
54 | make install | ||
55 | |||
56 | Or install manually into your Lua module directory: | ||
57 | |||
58 | [source,sh] | ||
59 | make | ||
60 | cp cjson.so $LUA_MODULE_DIRECTORY | ||
61 | |||
62 | |||
63 | CMake | ||
64 | ~~~~~ | ||
65 | |||
66 | http://www.cmake.org[CMake] can generate build configuration for many | ||
67 | different platforms (including Unix and Windows). | ||
68 | |||
69 | First, generate the makefile for your platform using CMake. If CMake is | ||
70 | unable to find Lua, manually set the +LUA_DIR+ environment variable to | ||
71 | the base prefix of your Lua 5.1 installation. | ||
72 | |||
73 | While +cmake+ is used in the example below, +ccmake+ or +cmake-gui+ may | ||
74 | be used to present an interface for changing the default build options. | ||
75 | |||
76 | [source,sh] | ||
77 | mkdir build | ||
78 | cd build | ||
79 | # Optional: export LUA_DIR=$LUA51_PREFIX | ||
80 | cmake .. | ||
81 | |||
82 | Next, build and install the module: | ||
83 | |||
84 | [source,sh] | ||
85 | make install | ||
86 | # Or: | ||
87 | make | ||
88 | cp cjson.so $LUA_MODULE_DIRECTORY | ||
89 | |||
90 | Review the | ||
91 | http://www.cmake.org/cmake/help/documentation.html[CMake documentation] | ||
92 | for further details. | ||
93 | |||
94 | |||
95 | RPM | ||
96 | ~~~ | ||
97 | |||
98 | Linux distributions using http://rpm.org[RPM] can create a package via | ||
99 | the included RPM spec file. Ensure the +rpm-build+ package (or similar) | ||
100 | has been installed. | ||
101 | |||
102 | Build and install the module via RPM: | ||
103 | |||
104 | [source,sh] | ||
105 | rpmbuild -tb lua-cjson-2.1devel.tar.gz | ||
106 | rpm -Uvh $LUA_CJSON_RPM | ||
107 | |||
108 | |||
109 | LuaRocks | ||
110 | ~~~~~~~~ | ||
111 | |||
112 | http://luarocks.org[LuaRocks] can be used to install and manage Lua | ||
113 | modules on a wide range of platforms (including Windows). | ||
114 | |||
115 | First, extract the Lua CJSON source package. | ||
116 | |||
117 | Next, install the module: | ||
118 | |||
119 | [source,sh] | ||
120 | cd lua-cjson-2.1devel | ||
121 | luarocks make | ||
122 | |||
123 | [NOTE] | ||
124 | LuaRocks does not support platform specific configuration for Solaris. | ||
125 | On Solaris, you may need to manually uncomment +USE_INTERNAL_ISINF+ in | ||
126 | the rockspec before building this module. | ||
127 | |||
128 | Review the http://luarocks.org/en/Documentation[LuaRocks documentation] | ||
129 | for further details. | ||
130 | |||
131 | |||
132 | [[build_options]] | ||
133 | Build Options (#define) | ||
134 | ~~~~~~~~~~~~~~~~~~~~~~~ | ||
135 | |||
136 | Lua CJSON offers several +#define+ build options to address portability | ||
137 | issues, and enable non-default features. Some build methods may | ||
138 | automatically set platform specific options if required. Other features | ||
139 | should be enabled manually. | ||
140 | |||
141 | USE_INTERNAL_ISINF:: Workaround for Solaris platforms missing +isinf+. | ||
142 | DISABLE_INVALID_NUMBERS:: Recommended on platforms where +strtod+ / | ||
143 | +sprintf+ are not POSIX compliant (eg, Windows MinGW). Prevents | ||
144 | +cjson.encode_invalid_numbers+ and +cjson.decode_invalid_numbers+ from | ||
145 | being enabled. However, +cjson.encode_invalid_numbers+ may still be | ||
146 | set to +"null"+. When using the Lua CJSON built-in floating point | ||
147 | conversion this option is unnecessary and is ignored. | ||
148 | |||
149 | |||
150 | Built-in floating point conversion | ||
151 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | ||
152 | |||
153 | Lua CJSON may be built with David Gay's | ||
154 | http://www.netlib.org/fp/[floating point conversion routines]. This can | ||
155 | increase overall performance by up to 50% on some platforms when | ||
156 | converting a large amount of numeric data. However, this option reduces | ||
157 | portability and is disabled by default. | ||
158 | |||
159 | USE_INTERNAL_FPCONV:: Enable internal number conversion routines. | ||
160 | IEEE_BIG_ENDIAN:: Must be set on big endian architectures. | ||
161 | MULTIPLE_THREADS:: Must be set if Lua CJSON may be used in a | ||
162 | multi-threaded application. Requires the _pthreads_ library. | ||
163 | |||
164 | |||
165 | API (Functions) | ||
166 | --------------- | ||
167 | |||
168 | Synopsis | ||
169 | ~~~~~~~~ | ||
170 | |||
171 | [source,lua] | ||
172 | ------------ | ||
173 | -- Module instantiation | ||
174 | local cjson = require "cjson" | ||
175 | local cjson2 = cjson.new() | ||
176 | local cjson_safe = require "cjson.safe" | ||
177 | |||
178 | -- Translate Lua value to/from JSON | ||
179 | text = cjson.encode(value) | ||
180 | value = cjson.decode(text) | ||
181 | |||
182 | -- Get and/or set Lua CJSON configuration | ||
183 | setting = cjson.decode_invalid_numbers([setting]) | ||
184 | setting = cjson.encode_invalid_numbers([setting]) | ||
185 | keep = cjson.encode_keep_buffer([keep]) | ||
186 | depth = cjson.encode_max_depth([depth]) | ||
187 | depth = cjson.decode_max_depth([depth]) | ||
188 | convert, ratio, safe = cjson.encode_sparse_array([convert[, ratio[, safe]]]) | ||
189 | ------------ | ||
190 | |||
191 | |||
192 | Module Instantiation | ||
193 | ~~~~~~~~~~~~~~~~~~~~ | ||
194 | |||
195 | [source,lua] | ||
196 | ------------ | ||
197 | local cjson = require "cjson" | ||
198 | local cjson2 = cjson.new() | ||
199 | local cjson_safe = require "cjson.safe" | ||
200 | ------------ | ||
201 | |||
202 | Import Lua CJSON via the Lua +require+ function. Lua CJSON does not | ||
203 | register a global module table. | ||
204 | |||
205 | The +cjson+ module will throw an error during JSON conversion if any | ||
206 | invalid data is encountered. Refer to <<encode,+cjson.encode+>> and | ||
207 | <<decode,+cjson.decode+>> for details. | ||
208 | |||
209 | The +cjson.safe+ module behaves identically to the +cjson+ module, | ||
210 | except when errors are encountered during JSON conversion. On error, the | ||
211 | +cjson_safe.encode+ and +cjson_safe.decode+ functions will return | ||
212 | +nil+ followed by the error message. | ||
213 | |||
214 | +cjson.new+ can be used to instantiate an independent copy of the Lua | ||
215 | CJSON module. The new module has a separate persistent encoding buffer, | ||
216 | and default settings. | ||
217 | |||
218 | Lua CJSON can support Lua implementations using multiple preemptive | ||
219 | threads within a single Lua state provided the persistent encoding | ||
220 | buffer is not shared. This can be achieved by one of the following | ||
221 | methods: | ||
222 | |||
223 | - Disabling the persistent encoding buffer with | ||
224 | <<encode_keep_buffer,+cjson.encode_keep_buffer+>> | ||
225 | - Ensuring each thread calls <<encode,+cjson.encode+>> separately (ie, | ||
226 | treat +cjson.encode+ as non-reentrant). | ||
227 | - Using a separate +cjson+ module table per preemptive thread | ||
228 | (+cjson.new+) | ||
229 | |||
230 | [NOTE] | ||
231 | Lua CJSON uses +strtod+ and +snprintf+ to perform numeric conversion as | ||
232 | they are usually well supported, fast and bug free. However, these | ||
233 | functions require a workaround for JSON encoding/parsing under locales | ||
234 | using a comma decimal separator. Lua CJSON detects the current locale | ||
235 | during instantiation to determine and automatically implement the | ||
236 | workaround if required. Lua CJSON should be reinitialised via | ||
237 | +cjson.new+ if the locale of the current process changes. Using a | ||
238 | different locale per thread is not supported. | ||
239 | |||
240 | |||
241 | [[decode]] | ||
242 | decode | ||
243 | ~~~~~~ | ||
244 | |||
245 | [source,lua] | ||
246 | ------------ | ||
247 | value = cjson.decode(json_text) | ||
248 | ------------ | ||
249 | |||
250 | +cjson.decode+ will deserialise any UTF-8 JSON string into a Lua value | ||
251 | or table. | ||
252 | |||
253 | UTF-16 and UTF-32 JSON strings are not supported. | ||
254 | |||
255 | +cjson.decode+ requires that any NULL (ASCII 0) and double quote (ASCII | ||
256 | 34) characters are escaped within strings. All escape codes will be | ||
257 | decoded and other bytes will be passed transparently. UTF-8 characters | ||
258 | are not validated during decoding and should be checked elsewhere if | ||
259 | required. | ||
260 | |||
261 | JSON +null+ will be converted to a NULL +lightuserdata+ value. This can | ||
262 | be compared with +cjson.null+ for convenience. | ||
263 | |||
264 | By default, numbers incompatible with the JSON specification (infinity, | ||
265 | NaN, hexadecimal) can be decoded. This default can be changed with | ||
266 | <<decode_invalid_numbers,+cjson.decode_invalid_numbers+>>. | ||
267 | |||
268 | .Example: Decoding | ||
269 | [source,lua] | ||
270 | json_text = '[ true, { "foo": "bar" } ]' | ||
271 | value = cjson.decode(json_text) | ||
272 | -- Returns: { true, { foo = "bar" } } | ||
273 | |||
274 | [CAUTION] | ||
275 | Care must be taken after decoding JSON objects with numeric keys. Each | ||
276 | numeric key will be stored as a Lua +string+. Any subsequent code | ||
277 | assuming type +number+ may break. | ||
278 | |||
279 | |||
280 | [[decode_invalid_numbers]] | ||
281 | decode_invalid_numbers | ||
282 | ~~~~~~~~~~~~~~~~~~~~~~ | ||
283 | |||
284 | [source,lua] | ||
285 | ------------ | ||
286 | setting = cjson.decode_invalid_numbers([setting]) | ||
287 | -- "setting" must be a boolean. Default: true. | ||
288 | ------------ | ||
289 | |||
290 | Lua CJSON may generate an error when trying to decode numbers not | ||
291 | supported by the JSON specification. _Invalid numbers_ are defined as: | ||
292 | |||
293 | - infinity | ||
294 | - NaN | ||
295 | - hexadecimal | ||
296 | |||
297 | Available settings: | ||
298 | |||
299 | +true+:: Accept and decode _invalid numbers_. This is the default | ||
300 | setting. | ||
301 | +false+:: Throw an error when _invalid numbers_ are encountered. | ||
302 | |||
303 | The current setting is always returned, and is only updated when an | ||
304 | argument is provided. | ||
305 | |||
306 | |||
307 | [[decode_max_depth]] | ||
308 | decode_max_depth | ||
309 | ~~~~~~~~~~~~~~~~ | ||
310 | |||
311 | [source,lua] | ||
312 | ------------ | ||
313 | depth = cjson.decode_max_depth([depth]) | ||
314 | -- "depth" must be a positive integer. Default: 1000. | ||
315 | ------------ | ||
316 | |||
317 | Lua CJSON will generate an error when parsing deeply nested JSON once | ||
318 | the maximum array/object depth has been exceeded. This check prevents | ||
319 | unnecessarily complicated JSON from slowing down the application, or | ||
320 | crashing the application due to lack of process stack space. | ||
321 | |||
322 | An error may be generated before the depth limit is hit if Lua is unable | ||
323 | to allocate more objects on the Lua stack. | ||
324 | |||
325 | By default, Lua CJSON will reject JSON with arrays and/or objects nested | ||
326 | more than 1000 levels deep. | ||
327 | |||
328 | The current setting is always returned, and is only updated when an | ||
329 | argument is provided. | ||
330 | |||
331 | |||
332 | [[encode]] | ||
333 | encode | ||
334 | ~~~~~~ | ||
335 | |||
336 | [source,lua] | ||
337 | ------------ | ||
338 | json_text = cjson.encode(value) | ||
339 | ------------ | ||
340 | |||
341 | +cjson.encode+ will serialise a Lua value into a string containing the | ||
342 | JSON representation. | ||
343 | |||
344 | +cjson.encode+ supports the following types: | ||
345 | |||
346 | - +boolean+ | ||
347 | - +lightuserdata+ (NULL value only) | ||
348 | - +nil+ | ||
349 | - +number+ | ||
350 | - +string+ | ||
351 | - +table+ | ||
352 | |||
353 | The remaining Lua types will generate an error: | ||
354 | |||
355 | - +function+ | ||
356 | - +lightuserdata+ (non-NULL values) | ||
357 | - +thread+ | ||
358 | - +userdata+ | ||
359 | |||
360 | By default, numbers are encoded with 14 significant digits. Refer to | ||
361 | <<encode_number_precision,+cjson.encode_number_precision+>> for details. | ||
362 | |||
363 | Lua CJSON will escape the following characters within each UTF-8 string: | ||
364 | |||
365 | - Control characters (ASCII 0 - 31) | ||
366 | - Double quote (ASCII 34) | ||
367 | - Forward slash (ASCII 47) | ||
368 | - Blackslash (ASCII 92) | ||
369 | - Delete (ASCII 127) | ||
370 | |||
371 | All other bytes are passed transparently. | ||
372 | |||
373 | [CAUTION] | ||
374 | ========= | ||
375 | Lua CJSON will successfully encode/decode binary strings, but this is | ||
376 | technically not supported by JSON and may not be compatible with other | ||
377 | JSON libraries. To ensure the output is valid JSON, applications should | ||
378 | ensure all Lua strings passed to +cjson.encode+ are UTF-8. | ||
379 | |||
380 | Base64 is commonly used to encode binary data as the most efficient | ||
381 | encoding under UTF-8 can only reduce the encoded size by a further | ||
382 | ~8%. Lua Base64 routines can be found in the | ||
383 | http://w3.impa.br/%7Ediego/software/luasocket/[LuaSocket] and | ||
384 | http://www.tecgraf.puc-rio.br/%7Elhf/ftp/lua/#lbase64[lbase64] packages. | ||
385 | ========= | ||
386 | |||
387 | Lua CJSON uses a heuristic to determine whether to encode a Lua table as | ||
388 | a JSON array or an object. A Lua table with only positive integer keys | ||
389 | of type +number+ will be encoded as a JSON array. All other tables will | ||
390 | be encoded as a JSON object. | ||
391 | |||
392 | Lua CJSON does not use metamethods when serialising tables. | ||
393 | |||
394 | - +rawget+ is used to iterate over Lua arrays | ||
395 | - +next+ is used to iterate over Lua objects | ||
396 | |||
397 | Lua arrays with missing entries (_sparse arrays_) may optionally be | ||
398 | encoded in several different ways. Refer to | ||
399 | <<encode_sparse_array,+cjson.encode_sparse_array+>> for details. | ||
400 | |||
401 | JSON object keys are always strings. Hence +cjson.encode+ only supports | ||
402 | table keys which are type +number+ or +string+. All other types will | ||
403 | generate an error. | ||
404 | |||
405 | [NOTE] | ||
406 | Standards compliant JSON must be encapsulated in either an object (+{}+) | ||
407 | or an array (+[]+). If strictly standards compliant JSON is desired, a | ||
408 | table must be passed to +cjson.encode+. | ||
409 | |||
410 | By default, encoding the following Lua values will generate errors: | ||
411 | |||
412 | - Numbers incompatible with the JSON specification (infinity, NaN) | ||
413 | - Tables nested more than 1000 levels deep | ||
414 | - Excessively sparse Lua arrays | ||
415 | |||
416 | These defaults can be changed with: | ||
417 | |||
418 | - <<encode_invalid_numbers,+cjson.encode_invalid_numbers+>> | ||
419 | - <<encode_max_depth,+cjson.encode_max_depth+>> | ||
420 | - <<encode_sparse_array,+cjson.encode_sparse_array+>> | ||
421 | |||
422 | .Example: Encoding | ||
423 | [source,lua] | ||
424 | value = { true, { foo = "bar" } } | ||
425 | json_text = cjson.encode(value) | ||
426 | -- Returns: '[true,{"foo":"bar"}]' | ||
427 | |||
428 | |||
429 | [[encode_invalid_numbers]] | ||
430 | encode_invalid_numbers | ||
431 | ~~~~~~~~~~~~~~~~~~~~~~ | ||
432 | [source,lua] | ||
433 | ------------ | ||
434 | setting = cjson.encode_invalid_numbers([setting]) | ||
435 | -- "setting" must a boolean or "null". Default: false. | ||
436 | ------------ | ||
437 | |||
438 | Lua CJSON may generate an error when encoding floating point numbers not | ||
439 | supported by the JSON specification (_invalid numbers_): | ||
440 | |||
441 | - infinity | ||
442 | - NaN | ||
443 | |||
444 | Available settings: | ||
445 | |||
446 | +true+:: Allow _invalid numbers_ to be encoded using the Javascript | ||
447 | compatible values +NaN+ and +Infinity+. This will generate | ||
448 | non-standard JSON, but these values are supported by some libraries. | ||
449 | +"null"+:: Encode _invalid numbers_ as a JSON +null+ value. This allows | ||
450 | infinity and NaN to be encoded into valid JSON. | ||
451 | +false+:: Throw an error when attempting to encode _invalid numbers_. | ||
452 | This is the default setting. | ||
453 | |||
454 | The current setting is always returned, and is only updated when an | ||
455 | argument is provided. | ||
456 | |||
457 | |||
458 | [[encode_keep_buffer]] | ||
459 | encode_keep_buffer | ||
460 | ~~~~~~~~~~~~~~~~~~ | ||
461 | |||
462 | [source,lua] | ||
463 | ------------ | ||
464 | keep = cjson.encode_keep_buffer([keep]) | ||
465 | -- "keep" must be a boolean. Default: true. | ||
466 | ------------ | ||
467 | |||
468 | Lua CJSON can reuse the JSON encoding buffer to improve performance. | ||
469 | |||
470 | Available settings: | ||
471 | |||
472 | +true+:: The buffer will grow to the largest size required and is not | ||
473 | freed until the Lua CJSON module is garbage collected. This is the | ||
474 | default setting. | ||
475 | +false+:: Free the encode buffer after each call to +cjson.encode+. | ||
476 | |||
477 | The current setting is always returned, and is only updated when an | ||
478 | argument is provided. | ||
479 | |||
480 | |||
481 | [[encode_max_depth]] | ||
482 | encode_max_depth | ||
483 | ~~~~~~~~~~~~~~~~ | ||
484 | |||
485 | [source,lua] | ||
486 | ------------ | ||
487 | depth = cjson.encode_max_depth([depth]) | ||
488 | -- "depth" must be a positive integer. Default: 1000. | ||
489 | ------------ | ||
490 | |||
491 | Once the maximum table depth has been exceeded Lua CJSON will generate | ||
492 | an error. This prevents a deeply nested or recursive data structure from | ||
493 | crashing the application. | ||
494 | |||
495 | By default, Lua CJSON will generate an error when trying to encode data | ||
496 | structures with more than 1000 nested tables. | ||
497 | |||
498 | The current setting is always returned, and is only updated when an | ||
499 | argument is provided. | ||
500 | |||
501 | .Example: Recursive Lua table | ||
502 | [source,lua] | ||
503 | a = {}; a[1] = a | ||
504 | |||
505 | |||
506 | [[encode_number_precision]] | ||
507 | encode_number_precision | ||
508 | ~~~~~~~~~~~~~~~~~~~~~~~ | ||
509 | |||
510 | [source,lua] | ||
511 | ------------ | ||
512 | precision = cjson.encode_number_precision([precision]) | ||
513 | -- "precision" must be an integer between 1 and 14. Default: 14. | ||
514 | ------------ | ||
515 | |||
516 | The amount of significant digits returned by Lua CJSON when encoding | ||
517 | numbers can be changed to balance accuracy versus performance. For data | ||
518 | structures containing many numbers, setting | ||
519 | +cjson.encode_number_precision+ to a smaller integer, for example +3+, | ||
520 | can improve encoding performance by up to 50%. | ||
521 | |||
522 | By default, Lua CJSON will output 14 significant digits when converting | ||
523 | a number to text. | ||
524 | |||
525 | The current setting is always returned, and is only updated when an | ||
526 | argument is provided. | ||
527 | |||
528 | |||
529 | [[encode_sparse_array]] | ||
530 | encode_sparse_array | ||
531 | ~~~~~~~~~~~~~~~~~~~ | ||
532 | |||
533 | [source,lua] | ||
534 | ------------ | ||
535 | convert, ratio, safe = cjson.encode_sparse_array([convert[, ratio[, safe]]]) | ||
536 | -- "convert" must be a boolean. Default: false. | ||
537 | -- "ratio" must be a positive integer. Default: 2. | ||
538 | -- "safe" must be a positive integer. Default: 10. | ||
539 | ------------ | ||
540 | |||
541 | Lua CJSON classifies a Lua table into one of three kinds when encoding a | ||
542 | JSON array. This is determined by the number of values missing from the | ||
543 | Lua array as follows: | ||
544 | |||
545 | Normal:: All values are available. | ||
546 | Sparse:: At least 1 value is missing. | ||
547 | Excessively sparse:: The number of values missing exceeds the configured | ||
548 | ratio. | ||
549 | |||
550 | Lua CJSON encodes sparse Lua arrays as JSON arrays using JSON +null+ for | ||
551 | the missing entries. | ||
552 | |||
553 | An array is excessively sparse when all the following conditions are | ||
554 | met: | ||
555 | |||
556 | - +ratio+ > +0+ | ||
557 | - _maximum_index_ > +safe+ | ||
558 | - _maximum_index_ > _item_count_ * +ratio+ | ||
559 | |||
560 | Lua CJSON will never consider an array to be _excessively sparse_ when | ||
561 | +ratio+ = +0+. The +safe+ limit ensures that small Lua arrays are always | ||
562 | encoded as sparse arrays. | ||
563 | |||
564 | By default, attempting to encode an _excessively sparse_ array will | ||
565 | generate an error. If +convert+ is set to +true+, _excessively sparse_ | ||
566 | arrays will be converted to a JSON object. | ||
567 | |||
568 | The current settings are always returned. A particular setting is only | ||
569 | changed when the argument is provided (non-++nil++). | ||
570 | |||
571 | .Example: Encoding a sparse array | ||
572 | [source,lua] | ||
573 | cjson.encode({ [3] = "data" }) | ||
574 | -- Returns: '[null,null,"data"]' | ||
575 | |||
576 | .Example: Enabling conversion to a JSON object | ||
577 | [source,lua] | ||
578 | cjson.encode_sparse_array(true) | ||
579 | cjson.encode({ [1000] = "excessively sparse" }) | ||
580 | -- Returns: '{"1000":"excessively sparse"}' | ||
581 | |||
582 | |||
583 | API (Variables) | ||
584 | --------------- | ||
585 | |||
586 | _NAME | ||
587 | ~~~~~ | ||
588 | |||
589 | The name of the Lua CJSON module (+"cjson"+). | ||
590 | |||
591 | |||
592 | _VERSION | ||
593 | ~~~~~~~~ | ||
594 | |||
595 | The version number of the Lua CJSON module (+"2.1devel"+). | ||
596 | |||
597 | |||
598 | null | ||
599 | ~~~~ | ||
600 | |||
601 | Lua CJSON decodes JSON +null+ as a Lua +lightuserdata+ NULL pointer. | ||
602 | +cjson.null+ is provided for comparison. | ||
603 | |||
604 | |||
605 | [sect1] | ||
606 | References | ||
607 | ---------- | ||
608 | |||
609 | - http://tools.ietf.org/html/rfc4627[RFC 4627] | ||
610 | - http://www.json.org/[JSON website] | ||
611 | |||
612 | |||
613 | // vi:ft=asciidoc tw=72: | ||