aboutsummaryrefslogtreecommitdiff
path: root/manual.txt
diff options
context:
space:
mode:
authorMark Pulford <mark@kyne.com.au>2011-12-12 23:23:32 +1030
committerMark Pulford <mark@kyne.com.au>2011-12-12 23:23:32 +1030
commit71c5dd86f14a73d97e2cb57e81755c4844938697 (patch)
tree124d6c7a1d46463826cd9d45e288f200b7b05e08 /manual.txt
parentbd994cd7976ac93c530792e3c0d6f45a33c757b4 (diff)
downloadlua-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.txt460
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 @@
1Lua CJSON Manual
2================
3Mark Pulford <mark@kyne.com.au>
4v1.0.4, November 30 2011
5
6Overview
7--------
8
9Lua 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
23Lua CJSON is covered by the MIT license. See the file +LICENSE+ for
24details.
25
26The latest version of this software is available from the
27http://www.kyne.com.au/~mark/software/lua-cjson.php[Lua CJSON website].
28
29Feel free to email me if you have any patches, suggestions, or
30comments.
31
32
33Installation Methods
34--------------------
35
36Lua CJSON requires either http://www.lua.org[Lua] or
37http://www.luajit.org[LuaJIT] to build.
38
39There 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
46Make
47~~~~
48
49Review and update the included Makefile to suit your platform. Next,
50build and install the module:
51
52[source,sh]
53-----------
54make install
55-----------
56
57Or install manually:
58
59[source,sh]
60-----------
61make
62cp cjson.so $your_lua_module_directory
63-----------
64
65
66RPM
67~~~
68
69Linux distributions using RPM should be able to create a package via
70the included RPM spec file. Install the +rpm-build+ package (or
71similar) then:
72
73[source,sh]
74-----------
75rpmbuild -tb lua-cjson-1.0.4.tar.gz
76rpm -Uvh $newly_built_lua_cjson_rpm
77-----------
78
79
80LuaRocks
81~~~~~~~~
82
83http://luarocks.org[LuaRocks] can be used to install and manage Lua
84modules on a wide range of platforms (including Windows).
85
86Extract the Lua CJSON source package into a directory and run:
87
88[source,sh]
89-----------
90cd lua-cjson-1.0.4
91luarocks make
92-----------
93
94LuaRocks does not support platform specific configuration for Solaris.
95On Solaris, you may need to manually uncomment +USE_INTERNAL_ISINF+ in
96the rockspec before building this module.
97
98See the http://luarocks.org/en/Documentation[LuaRocks documentation] for
99further details.
100
101
102Lua API
103-------
104
105Synopsis
106~~~~~~~~
107
108[source,lua]
109------------
110require "cjson"
111-- Or:
112local cjson = require "cjson"
113
114-- Translate Lua value to/from JSON
115text = cjson.encode(value)
116value = cjson.decode(text)
117
118-- Get and/or set Lua CJSON configuration
119setting = cjson.refuse_invalid_numbers([setting])
120depth = cjson.encode_max_depth([depth])
121convert, ratio, safe = cjson.encode_sparse_array([convert[, ratio[, safe]]])
122keep = cjson.encode_keep_buffer([keep])
123------------
124
125
126cjson.encode
127~~~~~~~~~~~~
128
129[source,lua]
130------------
131json_text = cjson.encode(value)
132------------
133
134+cjson.encode+ will serialise a Lua value into a string containing the
135JSON 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
146The remaining Lua types cannot be serialised:
147
148- +function+
149- +lightuserdata+ (non-NULL values)
150- +thread+
151- +userdata+
152
153Numbers are encoded using the standard Lua number format.
154
155Lua 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
163All other characters are passed transparently. Any UTF-8 error
164checking must be done by the application.
165
166Lua CJSON uses a heuristic to determine whether to encode a Lua table
167as a JSON array or an object. A Lua table which only has positive
168integers (>0) keys of type +number+ will be encoded as a JSON array.
169All other tables will be encoded as a JSON object.
170
171Missing entries from sparse Lua arrays are encoded as +null+. For
172example:
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]
187Standards compliant JSON must be encapsulated in either an
188object (+{}+) or an array (+[]+). Hence a table must be passed to
189+cjson.encode+ to generate standards compliant JSON output.
190
191By 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
197These 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------------
206data_obj = { true, { foo = "bar" } }
207data_json = cjson.encode(data_obj)
208------------
209
210
211cjson.decode
212~~~~~~~~~~~~
213
214[source,lua]
215------------
216value = cjson.decode(json_text)
217------------
218
219+cjson.decode+ will deserialise any UTF-8 JSON string into a Lua value
220or table. It may return any of the types that +cjson.encode+ supports.
221
222UTF-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
226will be decoded and other characters will be passed transparently.
227UTF-8 characters are not validated during decoding and should be
228checked elsewhere if required.
229
230JSON +null+ will be converted to a NULL +lightuserdata+ value. This
231can be compared with +cjson.null+ for convenience.
232
233By default, _invalid_ numbers (NaN, Infinity, Hexidecimal) will be
234decoded. This default can be changed with
235+cjson.refuse_invalid_numbers+.
236
237.Example: decoding
238[source,lua]
239------------
240data_json = '[ true, { "foo": "bar" } ]'
241data_obj = cjson.decode(data_json)
242------------
243
244
245cjson.refuse_invalid_numbers
246~~~~~~~~~~~~~~~~~~~~~~~~~~~~
247
248[source,lua]
249------------
250setting = cjson.refuse_invalid_numbers([setting])
251-- "setting" must be on of:
252-- false, "encode", "decode", "both", true
253------------
254
255Lua CJSON considers numbers which are outside the JSON specification to be
256_invalid_:
257
258- Infinity
259- NaN
260- Hexadecimal numbers
261
262By default Lua CJSON will decode _invalid_ numbers, but will refuse to
263encode them.
264
265This setting can be configured separately for encoding and/or
266decoding:
267
268Enabled::
269 an error will be generated if an _invalid_ number is found.
270Disabled (encoding)::
271 NaN and Infinity can be encoded.
272Disabled (decoding)::
273 All numbers supported by +strtod+(3) will be parsed.
274
275
276[[sparse_arrays]]
277cjson.encode_sparse_array
278~~~~~~~~~~~~~~~~~~~~~~~~~
279
280[source,lua]
281------------
282convert, 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
288A Lua array is sparse if it is missing a value for at least 1 index.
289Lua 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
303Lua CJSON detects excessively sparse arrays by comparing the number of
304items in a Lua array with the maximum index. In particular:
305
306-----
307maximum index > safe AND maximum index > array_items * ratio
308-----
309
310By default, attempting to encode excessively sparse arrays will
311generate an error.
312
313If _convert_ is set to +true+, excessively sparse arrays will be
314encoded 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
324Setting +ratio+ to +0+ disables checking for excessively sparse arrays.
325
326
327cjson.encode_max_depth
328~~~~~~~~~~~~~~~~~~~~~~
329
330[source,lua]
331------------
332depth = cjson.encode_max_depth([depth])
333-- "depth" must be a positive integer (>0).
334------------
335
336By default, Lua CJSON will reject data structure with more than 20 nested
337tables.
338
339This check prevents a deeply nested or recursive data structure from
340crashing the application.
341
342.Example
343[source,lua]
344a = {}; b = { a }; a[1] = b
345
346
347cjson.encode_number_precision
348~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
349
350[source,lua]
351------------
352precision = cjson.encode_number_precision([precision])
353-- "precision" must be between 1 and 14 (inclusive)
354------------
355
356By default, Lua CJSON will output 14 significant digits when
357converting a number to text.
358
359Reducing number precision to _3_ can improve performance of number
360heavy JSON conversions by up to 50%.
361
362
363cjson.keep_encode_buffer
364~~~~~~~~~~~~~~~~~~~~~~~~
365
366[source,lua]
367------------
368keep = cjson.keep_encode_buffer([keep])
369-- "keep" must be a boolean
370------------
371
372By default, Lua CJSON will reuse the JSON encoding buffer to improve
373performance. The buffer will grow to the largest size required and is
374not freed until the Lua CJSON module is garbage collected. Setting this
375option to +false+ will cause the buffer to be freed after each call to
376+cjson.encode+.
377
378
379cjson.version
380~~~~~~~~~~~~~
381
382[source,lua]
383------------
384ver = cjson.version
385-- variable containing the package version (1.0.4)
386------------
387
388FIXME
389
390
391JSON and handling under Lua CJSON
392---------------------------------
393
394Nulls
395~~~~~
396
397Lua CJSON decodes JSON +null+ as a Lua lightuserdata NULL pointer.
398
399As a convenience, +cjson.null+ is provided for comparison.
400
401
402Table keys
403~~~~~~~~~~
404
405If all Lua table keys are type +number+ (not +string+), Lua CJSON will
406encode the table as a JSON array. See
407<<sparse_arrays,cjson.encode_sparse_array>> above for more details.
408
409All other tables will be encoded as a JSON object.
410
411JSON requires that object keys must be type string. +cjson.encode+
412will convert numeric keys to a string, and other non-string types will
413generate an error.
414
415[CAUTION]
416=========
417Care must be taken when encoding/decoding objects which contain keys of type
418+number+.
419[source,lua]
420------------
421val = cjson.decode(cjson.encode{[1] = "1", a = "a"})
422-- Returns: { ["1"] = "1", ...
423-- NOT: { [1] = "1", ...
424------------
425=========
426
427Metamethods
428~~~~~~~~~~~
429
430Lua 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
436Functions, Userdata, Threads
437~~~~~~~~~~~~~~~~~~~~~~~~~~~~
438
439Lua CJSON will generate an error if asked to serialise Lua functions,
440userdata, lightuserdata or threads.
441
442
443Locales
444~~~~~~~
445
446Lua CJSON uses +strtod+(3) and +snprintf+(3) to perform numeric conversion
447as they are usually well supported, fast and bug free.
448
449To ensure JSON encoding/decoding works correctly for locales using
450comma decimal separators, Lua CJSON must be compiled with either
451+USE_POSIX_USELOCALE+ or +USE_POSIX_SETLOCALE+. See the +Makefile+ or the
452rockspec for details.
453
454
455[sect1]
456References
457----------
458
459- http://tools.ietf.org/html/rfc4627[RFC 4627]
460- http://www.json.org/[JSON website]
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-03-17 03:03:12 +0000