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