From ffb9aa79eb828118b0ebd214d2e47a324df9bd74 Mon Sep 17 00:00:00 2001 From: Mark Pulford Date: Sun, 8 May 2011 23:38:34 +0930 Subject: Add documentation (README) --- README | 211 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 211 insertions(+) create mode 100644 README (limited to 'README') diff --git a/README b/README new file mode 100644 index 0000000..71ad376 --- /dev/null +++ b/README @@ -0,0 +1,211 @@ +Lua CJSON v1.0 +============== + +Lua CJSON is covered by the MIT license. See the file "LICENSE" for +details. + +Lua CJSON provides fast JSON parsing and encoding support for Lua. + +Features: +- 10x to 20x quicker (or more) than the fastest pure Lua JSON modules. +- Full support for JSON with UTF-8, including decoding surrogate + pairs. +- Optionally supports common JSON extensions (NaN, Inf,..). + +Caveats: +- UTF-16 and UTF-32 are not supported. +- Multiple OS threads within a single Lua state are not currently + supported. + +To obtain the latest version of Lua CJSON visit: + + http://www.kyne.com.au/~mark/software/lua-cjson.php + +Feel free to email me if you have any patches, suggestions, or comments. + +- Mark Pulford + + +Installing +========== + +Build requirements: +- Lua (http://www.lua.org/) +Or: +- LuaJIT (http://www.luajit.org/) + +The included Makefile should be reviewed and updated based on the +location of your Lua header and library directories. Then: + + # make + # make install + OR + # cp cjson.so [your_module_directory] + +Linux distributions using RPM should be able to build a package with +the following command: + + # rpmbuild -tb lua-cjson-1.0.tar.gz + + +Lua CJSON API +============= + +Synopsis +-------- + + require "cjson" + -- Or: + local cjson = require "cjson" + + -- Translate Lua value to/from JSON + text = cjson.encode(value) + value = cjson.decode(text) + + -- Get and/or Set CJSON configuration + setting = cjson.refuse_invalid_numbers([setting]) + depth = cjson.encode_max_depth([depth]) + convert, ratio, safe = cjson.encode_sparse_array([convert[, ratio[, safe]]]) + + +Encoding +-------- + + json_text = cjson.encode(value) + +cjson.encode() will serialise the following types: + * number, string, table, boolean, lightuserdata (NULL) or nil + +The remaining Lua types cannot be serialised: + * thread, userdata, lightuserdata (non-NULL), function + +Numbers are encoded using the standard Lua number format. + +ASCII 0 - 31, double-quote, forward-slash, black-slash and ASCII 127 +are escaped when encoding strings. Other octets are passed +transparently. It is expected the application will perform UTF-8 error +checking if required. + +If a Lua table only contains positive integer keys (>0) it is encoded +as an array, otherwise it will be encoded as an object. + +A Lua table will only recognised as an array if all keys are type +"number", and are positive integers (>0). Otherwise CJSON will encode +the table as a JSON object. + +CJSON will also recognise and handle sparse arrays. Missing entries +will be encoded as "null". Eg: + { [3] = "data" } +becomes: + [ null, null, "data" ] + +Note: standards compliant JSON must be encapsulated in either an +object ({}) or an array ([]). Hence you must pass a table to +cjson.encode() if you want to generate standards compliant JSON +output. + +By default, errors will be raised for: +- Excessively sparse arrays (see below) +- More than 20 nested tables +- Invalid numbers (NaN, Infinity) + +These defaults can be changed with: +- cjson.encode_sparse_array() +- cjson.encode_max_depth() +- cjson.refuse_invalid_numbers() + +Example: + data_obj = { true, { foo = "bar" } } + data_json = cjson.encode(data_obj) + + +Decoding +-------- + + value = cjson.decode(json_text) + +cjson.decode() will deserialise any UTF-8 JSON string into a Lua data +structure. It can return any of the types that cjson.encode() +supports. + +UTF-16 and UTF-32 JSON strings are not supported. + +CJSON only requires that NULL (\0) and double quote (\") are escaped +within strings. All other octets will be passed transparently. UTF-8 +characters are not validated and should be checked elsewhere if +desired. + +JSON "null" will be converted to a NULL lightuserdata value. This can +be compared with cjson.null for convenience. + +By default, invalid numbers (NaN, Infinity, Hex) will be decoded +correctly. + +Example: + data_json = '[ true, { "foo": "bar" } ]' + data_obj = cjson.decode(data_json) + + +Invalid numbers +--------------- + + setting = cjson.refuse_invalid_numbers([setting]) + -- "setting" must be on of: + -- false, "encode", "decode", "both", true + +CJSON considers numbers which are outside the JSON specification to be +"invalid". Eg: +- Infinity +- NaN +- Hexadecimal numbers + +This setting can be configured separately for encoding and/or +decoding: +- Enabled: an error will be generated if an invalid number is found. +- Disabled (encoding): NaN and Infinity can be encoded. +- Disabled (decoding): All numbers supported by strtod(3) will be + parsed. + + +Sparse arrays +------------- + + convert, ratio, safe = cjson.encode_sparse_array([convert[, ratio[, safe]]]) + -- "convert" must be a boolean. Default: false. + -- "ratio" must be a positive integer (>0). Default: 2 + -- "safe" must be a positive integer (>0). Default: 10 + +CJSON detects excessively sparse arrays by comparing the number of +items in an array with the maximum index. An excessively sparse array +is defined as: + + max_index > safe AND max_index > items * ratio + +Eg: + { [1000] = "excessively sparse array" } + +Setting "ratio" to 0 disables checking for excessively sparse arrays. + +When "convert" is enabled, CJSON will encode excessively sparse arrays +as JSON objects. + + +Nested tables +------------- + + depth = cjson.encode_max_depth([depth]) + -- "depth" must be a positive integer (>0). + +By default, CJSON will reject data structure with more than 20 nested +tables. + +This check is used to prevent a nested data structure from crashing +the application. Eg: + a = {}; b = { a }; a[1] = b + + +References +========== + +- http://tools.ietf.org/html/rfc4627 +- http://www.json.org/ -- cgit v1.2.3-55-g6feb