diff options
author | Mark Pulford <mark@kyne.com.au> | 2011-12-12 23:23:32 +1030 |
---|---|---|
committer | Mark Pulford <mark@kyne.com.au> | 2011-12-12 23:23:32 +1030 |
commit | 71c5dd86f14a73d97e2cb57e81755c4844938697 (patch) | |
tree | 124d6c7a1d46463826cd9d45e288f200b7b05e08 /manual.txt | |
parent | bd994cd7976ac93c530792e3c0d6f45a33c757b4 (diff) | |
download | lua-cjson-71c5dd86f14a73d97e2cb57e81755c4844938697.tar.gz lua-cjson-71c5dd86f14a73d97e2cb57e81755c4844938697.tar.bz2 lua-cjson-71c5dd86f14a73d97e2cb57e81755c4844938697.zip |
Convert documentation to AsciiDoc
- Rename README to manual.txt and add AsciiDoc markup
- Rewrite some sections of documentation (more outstanding)
- Add "doc" Makefile target
- Update RPM spec file to include HTML output
Diffstat (limited to 'manual.txt')
-rw-r--r-- | manual.txt | 460 |
1 files changed, 460 insertions, 0 deletions
diff --git a/manual.txt b/manual.txt new file mode 100644 index 0000000..20d95bd --- /dev/null +++ b/manual.txt | |||
@@ -0,0 +1,460 @@ | |||
1 | Lua CJSON Manual | ||
2 | ================ | ||
3 | Mark Pulford <mark@kyne.com.au> | ||
4 | v1.0.4, November 30 2011 | ||
5 | |||
6 | Overview | ||
7 | -------- | ||
8 | |||
9 | Lua CJSON provides fast JSON parsing and encoding support for Lua. | ||
10 | |||
11 | .Features | ||
12 | - More than 10x to 20x faster than the efficient pure Lua JSON modules. | ||
13 | - Full support for JSON with UTF-8, including decoding surrogate | ||
14 | pairs. | ||
15 | - Optional run-time support for common exceptions to the JSON | ||
16 | specification (NaN, Inf,..). | ||
17 | |||
18 | .Caveats | ||
19 | - UTF-16 and UTF-32 are not supported. | ||
20 | - Multi-threading within a single Lua state is not supported. | ||
21 | However, this is not a recommended configuration under Lua. | ||
22 | |||
23 | Lua CJSON is covered by the MIT license. See the file +LICENSE+ for | ||
24 | details. | ||
25 | |||
26 | The latest version of this software is available from the | ||
27 | http://www.kyne.com.au/~mark/software/lua-cjson.php[Lua CJSON website]. | ||
28 | |||
29 | Feel free to email me if you have any patches, suggestions, or | ||
30 | comments. | ||
31 | |||
32 | |||
33 | Installation Methods | ||
34 | -------------------- | ||
35 | |||
36 | Lua CJSON requires either http://www.lua.org[Lua] or | ||
37 | http://www.luajit.org[LuaJIT] to build. | ||
38 | |||
39 | There are 3 build methods available: | ||
40 | |||
41 | - Make: POSIX, OSX | ||
42 | - RPM: Various Linux distributions | ||
43 | - http://www.luarocks.org[LuaRocks]: POSIX, OSX, Windows | ||
44 | |||
45 | |||
46 | Make | ||
47 | ~~~~ | ||
48 | |||
49 | Review and update the included Makefile to suit your platform. Next, | ||
50 | build and install the module: | ||
51 | |||
52 | [source,sh] | ||
53 | ----------- | ||
54 | make install | ||
55 | ----------- | ||
56 | |||
57 | Or install manually: | ||
58 | |||
59 | [source,sh] | ||
60 | ----------- | ||
61 | make | ||
62 | cp cjson.so $your_lua_module_directory | ||
63 | ----------- | ||
64 | |||
65 | |||
66 | RPM | ||
67 | ~~~ | ||
68 | |||
69 | Linux distributions using RPM should be able to create a package via | ||
70 | the included RPM spec file. Install the +rpm-build+ package (or | ||
71 | similar) then: | ||
72 | |||
73 | [source,sh] | ||
74 | ----------- | ||
75 | rpmbuild -tb lua-cjson-1.0.4.tar.gz | ||
76 | rpm -Uvh $newly_built_lua_cjson_rpm | ||
77 | ----------- | ||
78 | |||
79 | |||
80 | LuaRocks | ||
81 | ~~~~~~~~ | ||
82 | |||
83 | http://luarocks.org[LuaRocks] can be used to install and manage Lua | ||
84 | modules on a wide range of platforms (including Windows). | ||
85 | |||
86 | Extract the Lua CJSON source package into a directory and run: | ||
87 | |||
88 | [source,sh] | ||
89 | ----------- | ||
90 | cd lua-cjson-1.0.4 | ||
91 | luarocks make | ||
92 | ----------- | ||
93 | |||
94 | LuaRocks does not support platform specific configuration for Solaris. | ||
95 | On Solaris, you may need to manually uncomment +USE_INTERNAL_ISINF+ in | ||
96 | the rockspec before building this module. | ||
97 | |||
98 | See the http://luarocks.org/en/Documentation[LuaRocks documentation] for | ||
99 | further details. | ||
100 | |||
101 | |||
102 | Lua API | ||
103 | ------- | ||
104 | |||
105 | Synopsis | ||
106 | ~~~~~~~~ | ||
107 | |||
108 | [source,lua] | ||
109 | ------------ | ||
110 | require "cjson" | ||
111 | -- Or: | ||
112 | local cjson = require "cjson" | ||
113 | |||
114 | -- Translate Lua value to/from JSON | ||
115 | text = cjson.encode(value) | ||
116 | value = cjson.decode(text) | ||
117 | |||
118 | -- Get and/or set Lua CJSON configuration | ||
119 | setting = cjson.refuse_invalid_numbers([setting]) | ||
120 | depth = cjson.encode_max_depth([depth]) | ||
121 | convert, ratio, safe = cjson.encode_sparse_array([convert[, ratio[, safe]]]) | ||
122 | keep = cjson.encode_keep_buffer([keep]) | ||
123 | ------------ | ||
124 | |||
125 | |||
126 | cjson.encode | ||
127 | ~~~~~~~~~~~~ | ||
128 | |||
129 | [source,lua] | ||
130 | ------------ | ||
131 | json_text = cjson.encode(value) | ||
132 | ------------ | ||
133 | |||
134 | +cjson.encode+ will serialise a Lua value into a string containing the | ||
135 | JSON representation. | ||
136 | |||
137 | +cjson.encode+ supports the following types: | ||
138 | |||
139 | - +boolean+ | ||
140 | - +lightuserdata+ (NULL value only) | ||
141 | - +nil+ | ||
142 | - +number+ | ||
143 | - +string+ | ||
144 | - +table+ | ||
145 | |||
146 | The remaining Lua types cannot be serialised: | ||
147 | |||
148 | - +function+ | ||
149 | - +lightuserdata+ (non-NULL values) | ||
150 | - +thread+ | ||
151 | - +userdata+ | ||
152 | |||
153 | Numbers are encoded using the standard Lua number format. | ||
154 | |||
155 | Lua CJSON will escape the following characters within each string: | ||
156 | |||
157 | - Control characters (ASCII 0 - 31) | ||
158 | - Double quote (ASCII 34) | ||
159 | - Forward slash (ASCII 47) | ||
160 | - Blackslash (ASCII 92) | ||
161 | - Delete (ASCII 127) | ||
162 | |||
163 | All other characters are passed transparently. Any UTF-8 error | ||
164 | checking must be done by the application. | ||
165 | |||
166 | Lua CJSON uses a heuristic to determine whether to encode a Lua table | ||
167 | as a JSON array or an object. A Lua table which only has positive | ||
168 | integers (>0) keys of type +number+ will be encoded as a JSON array. | ||
169 | All other tables will be encoded as a JSON object. | ||
170 | |||
171 | Missing entries from sparse Lua arrays are encoded as +null+. For | ||
172 | example: | ||
173 | |||
174 | .Lua input | ||
175 | [source,lua] | ||
176 | ------------ | ||
177 | { [3] = "data" } | ||
178 | ------------ | ||
179 | |||
180 | .JSON output | ||
181 | [source,javascript] | ||
182 | ------------------- | ||
183 | [null,null,"data"] | ||
184 | ------------------- | ||
185 | |||
186 | [NOTE] | ||
187 | Standards compliant JSON must be encapsulated in either an | ||
188 | object (+{}+) or an array (+[]+). Hence a table must be passed to | ||
189 | +cjson.encode+ to generate standards compliant JSON output. | ||
190 | |||
191 | By default, the following will generate errors: | ||
192 | |||
193 | - Excessively <<sparse_arrays,sparse arrays>> | ||
194 | - More than 20 nested tables | ||
195 | - Invalid numbers (NaN, Infinity) | ||
196 | |||
197 | These defaults can be changed with: | ||
198 | |||
199 | - +cjson.encode_sparse_array+ | ||
200 | - +cjson.encode_max_depth+ | ||
201 | - +cjson.refuse_invalid_numbers+ | ||
202 | |||
203 | .Example: encoding | ||
204 | [source,lua] | ||
205 | ------------ | ||
206 | data_obj = { true, { foo = "bar" } } | ||
207 | data_json = cjson.encode(data_obj) | ||
208 | ------------ | ||
209 | |||
210 | |||
211 | cjson.decode | ||
212 | ~~~~~~~~~~~~ | ||
213 | |||
214 | [source,lua] | ||
215 | ------------ | ||
216 | value = cjson.decode(json_text) | ||
217 | ------------ | ||
218 | |||
219 | +cjson.decode+ will deserialise any UTF-8 JSON string into a Lua value | ||
220 | or table. It may return any of the types that +cjson.encode+ supports. | ||
221 | |||
222 | UTF-16 and UTF-32 JSON strings are not supported. | ||
223 | |||
224 | +cjson.decode+ requires that any NULL (ASCII 0) and double quote | ||
225 | (ASCII 34) characters are escaped within strings. All escape codes | ||
226 | will be decoded and other characters will be passed transparently. | ||
227 | UTF-8 characters are not validated during decoding and should be | ||
228 | checked elsewhere if required. | ||
229 | |||
230 | JSON +null+ will be converted to a NULL +lightuserdata+ value. This | ||
231 | can be compared with +cjson.null+ for convenience. | ||
232 | |||
233 | By default, _invalid_ numbers (NaN, Infinity, Hexidecimal) will be | ||
234 | decoded. This default can be changed with | ||
235 | +cjson.refuse_invalid_numbers+. | ||
236 | |||
237 | .Example: decoding | ||
238 | [source,lua] | ||
239 | ------------ | ||
240 | data_json = '[ true, { "foo": "bar" } ]' | ||
241 | data_obj = cjson.decode(data_json) | ||
242 | ------------ | ||
243 | |||
244 | |||
245 | cjson.refuse_invalid_numbers | ||
246 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
247 | |||
248 | [source,lua] | ||
249 | ------------ | ||
250 | setting = cjson.refuse_invalid_numbers([setting]) | ||
251 | -- "setting" must be on of: | ||
252 | -- false, "encode", "decode", "both", true | ||
253 | ------------ | ||
254 | |||
255 | Lua CJSON considers numbers which are outside the JSON specification to be | ||
256 | _invalid_: | ||
257 | |||
258 | - Infinity | ||
259 | - NaN | ||
260 | - Hexadecimal numbers | ||
261 | |||
262 | By default Lua CJSON will decode _invalid_ numbers, but will refuse to | ||
263 | encode them. | ||
264 | |||
265 | This setting can be configured separately for encoding and/or | ||
266 | decoding: | ||
267 | |||
268 | Enabled:: | ||
269 | an error will be generated if an _invalid_ number is found. | ||
270 | Disabled (encoding):: | ||
271 | NaN and Infinity can be encoded. | ||
272 | Disabled (decoding):: | ||
273 | All numbers supported by +strtod+(3) will be parsed. | ||
274 | |||
275 | |||
276 | [[sparse_arrays]] | ||
277 | cjson.encode_sparse_array | ||
278 | ~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
279 | |||
280 | [source,lua] | ||
281 | ------------ | ||
282 | convert, ratio, safe = cjson.encode_sparse_array([convert[, ratio[, safe]]]) | ||
283 | -- "convert" must be a boolean. Default: false. | ||
284 | -- "ratio" must be a positive integer (>0). Default: 2 | ||
285 | -- "safe" must be a positive integer (>0). Default: 10 | ||
286 | ------------ | ||
287 | |||
288 | A Lua array is sparse if it is missing a value for at least 1 index. | ||
289 | Lua CJSON encodes missing values as JSON +null+. Eg, Lua array: | ||
290 | |||
291 | .Lua input | ||
292 | [source,lua] | ||
293 | ------------ | ||
294 | { [3] = "sparse" } | ||
295 | ------------ | ||
296 | |||
297 | .JSON output | ||
298 | [source,javascript] | ||
299 | ------------------- | ||
300 | [null,null,"sparse"] | ||
301 | ------------------- | ||
302 | |||
303 | Lua CJSON detects excessively sparse arrays by comparing the number of | ||
304 | items in a Lua array with the maximum index. In particular: | ||
305 | |||
306 | ----- | ||
307 | maximum index > safe AND maximum index > array_items * ratio | ||
308 | ----- | ||
309 | |||
310 | By default, attempting to encode excessively sparse arrays will | ||
311 | generate an error. | ||
312 | |||
313 | If _convert_ is set to +true+, excessively sparse arrays will be | ||
314 | encoded as a JSON object: | ||
315 | |||
316 | .Lua input | ||
317 | [source,lua] | ||
318 | { [1000] = "excessively sparse" } | ||
319 | |||
320 | .JSON output | ||
321 | [source,javascript] | ||
322 | {"1000":"excessively sparse"} | ||
323 | |||
324 | Setting +ratio+ to +0+ disables checking for excessively sparse arrays. | ||
325 | |||
326 | |||
327 | cjson.encode_max_depth | ||
328 | ~~~~~~~~~~~~~~~~~~~~~~ | ||
329 | |||
330 | [source,lua] | ||
331 | ------------ | ||
332 | depth = cjson.encode_max_depth([depth]) | ||
333 | -- "depth" must be a positive integer (>0). | ||
334 | ------------ | ||
335 | |||
336 | By default, Lua CJSON will reject data structure with more than 20 nested | ||
337 | tables. | ||
338 | |||
339 | This check prevents a deeply nested or recursive data structure from | ||
340 | crashing the application. | ||
341 | |||
342 | .Example | ||
343 | [source,lua] | ||
344 | a = {}; b = { a }; a[1] = b | ||
345 | |||
346 | |||
347 | cjson.encode_number_precision | ||
348 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
349 | |||
350 | [source,lua] | ||
351 | ------------ | ||
352 | precision = cjson.encode_number_precision([precision]) | ||
353 | -- "precision" must be between 1 and 14 (inclusive) | ||
354 | ------------ | ||
355 | |||
356 | By default, Lua CJSON will output 14 significant digits when | ||
357 | converting a number to text. | ||
358 | |||
359 | Reducing number precision to _3_ can improve performance of number | ||
360 | heavy JSON conversions by up to 50%. | ||
361 | |||
362 | |||
363 | cjson.keep_encode_buffer | ||
364 | ~~~~~~~~~~~~~~~~~~~~~~~~ | ||
365 | |||
366 | [source,lua] | ||
367 | ------------ | ||
368 | keep = cjson.keep_encode_buffer([keep]) | ||
369 | -- "keep" must be a boolean | ||
370 | ------------ | ||
371 | |||
372 | By default, Lua CJSON will reuse the JSON encoding buffer to improve | ||
373 | performance. The buffer will grow to the largest size required and is | ||
374 | not freed until the Lua CJSON module is garbage collected. Setting this | ||
375 | option to +false+ will cause the buffer to be freed after each call to | ||
376 | +cjson.encode+. | ||
377 | |||
378 | |||
379 | cjson.version | ||
380 | ~~~~~~~~~~~~~ | ||
381 | |||
382 | [source,lua] | ||
383 | ------------ | ||
384 | ver = cjson.version | ||
385 | -- variable containing the package version (1.0.4) | ||
386 | ------------ | ||
387 | |||
388 | FIXME | ||
389 | |||
390 | |||
391 | JSON and handling under Lua CJSON | ||
392 | --------------------------------- | ||
393 | |||
394 | Nulls | ||
395 | ~~~~~ | ||
396 | |||
397 | Lua CJSON decodes JSON +null+ as a Lua lightuserdata NULL pointer. | ||
398 | |||
399 | As a convenience, +cjson.null+ is provided for comparison. | ||
400 | |||
401 | |||
402 | Table keys | ||
403 | ~~~~~~~~~~ | ||
404 | |||
405 | If all Lua table keys are type +number+ (not +string+), Lua CJSON will | ||
406 | encode the table as a JSON array. See | ||
407 | <<sparse_arrays,cjson.encode_sparse_array>> above for more details. | ||
408 | |||
409 | All other tables will be encoded as a JSON object. | ||
410 | |||
411 | JSON requires that object keys must be type string. +cjson.encode+ | ||
412 | will convert numeric keys to a string, and other non-string types will | ||
413 | generate an error. | ||
414 | |||
415 | [CAUTION] | ||
416 | ========= | ||
417 | Care must be taken when encoding/decoding objects which contain keys of type | ||
418 | +number+. | ||
419 | [source,lua] | ||
420 | ------------ | ||
421 | val = cjson.decode(cjson.encode{[1] = "1", a = "a"}) | ||
422 | -- Returns: { ["1"] = "1", ... | ||
423 | -- NOT: { [1] = "1", ... | ||
424 | ------------ | ||
425 | ========= | ||
426 | |||
427 | Metamethods | ||
428 | ~~~~~~~~~~~ | ||
429 | |||
430 | Lua CJSON does not use metamethods when serialising tables. | ||
431 | |||
432 | - +rawget+ is used to iterate over Lua arrays. | ||
433 | - +next+ is used to iterate over Lua objects. | ||
434 | |||
435 | |||
436 | Functions, Userdata, Threads | ||
437 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
438 | |||
439 | Lua CJSON will generate an error if asked to serialise Lua functions, | ||
440 | userdata, lightuserdata or threads. | ||
441 | |||
442 | |||
443 | Locales | ||
444 | ~~~~~~~ | ||
445 | |||
446 | Lua CJSON uses +strtod+(3) and +snprintf+(3) to perform numeric conversion | ||
447 | as they are usually well supported, fast and bug free. | ||
448 | |||
449 | To ensure JSON encoding/decoding works correctly for locales using | ||
450 | comma decimal separators, Lua CJSON must be compiled with either | ||
451 | +USE_POSIX_USELOCALE+ or +USE_POSIX_SETLOCALE+. See the +Makefile+ or the | ||
452 | rockspec for details. | ||
453 | |||
454 | |||
455 | [sect1] | ||
456 | References | ||
457 | ---------- | ||
458 | |||
459 | - http://tools.ietf.org/html/rfc4627[RFC 4627] | ||
460 | - http://www.json.org/[JSON website] | ||