169 lines
4.6 KiB
Plaintext
169 lines
4.6 KiB
Plaintext
= Lua CJSON 2.1devel Manual =
|
|
Mark Pulford <mark@kyne.com.au>
|
|
:revdate: 1st March 2012
|
|
|
|
Overview
|
|
--------
|
|
|
|
The Lua CJSON module provides JSON support for Lua.
|
|
|
|
*Features*::
|
|
- Fast, standards compliant encoding/parsing routines
|
|
- Full support for JSON with UTF-8, including decoding surrogate pairs
|
|
- Optional run-time support for common exceptions to the JSON
|
|
specification (infinity, NaN,..)
|
|
- No dependencies on other libraries
|
|
|
|
*Caveats*::
|
|
- UTF-16 and UTF-32 are not supported
|
|
|
|
Lua CJSON is covered by the MIT license. Review the file +LICENSE+ for
|
|
details.
|
|
|
|
API (Functions)
|
|
---------------
|
|
|
|
Synopsis
|
|
~~~~~~~~
|
|
|
|
[source,lua]
|
|
------------
|
|
|
|
-- Translate Lua value to/from JSON
|
|
text = cjson.encode(value)
|
|
value = cjson.decode(text)
|
|
|
|
|
|
Module Instantiation
|
|
~~~~~~~~~~~~~~~~~~~~
|
|
|
|
decode
|
|
~~~~~~
|
|
|
|
[source,lua]
|
|
------------
|
|
value = cjson.decode(json_text)
|
|
------------
|
|
|
|
+cjson.decode+ will deserialise any UTF-8 JSON string into a Lua value
|
|
or table.
|
|
|
|
UTF-16 and UTF-32 JSON strings are not supported.
|
|
|
|
+cjson.decode+ requires that any NULL (ASCII 0) and double quote (ASCII
|
|
34) characters are escaped within strings. All escape codes will be
|
|
decoded and other bytes will be passed transparently. UTF-8 characters
|
|
are not validated during decoding and should be checked elsewhere if
|
|
required.
|
|
|
|
JSON +null+ will be converted to a NULL +lightuserdata+ value. This can
|
|
be compared with +cjson.null+ for convenience.
|
|
|
|
By default, numbers incompatible with the JSON specification (infinity,
|
|
NaN, hexadecimal) can be decoded. This default can be changed with
|
|
<<decode_invalid_numbers,+cjson.decode_invalid_numbers+>>.
|
|
|
|
.Example: Decoding
|
|
[source,lua]
|
|
json_text = '[ true, { "foo": "bar" } ]'
|
|
value = cjson.decode(json_text)
|
|
-- Returns: { true, { foo = "bar" } }
|
|
|
|
[CAUTION]
|
|
Care must be taken after decoding JSON objects with numeric keys. Each
|
|
numeric key will be stored as a Lua +string+. Any subsequent code
|
|
assuming type +number+ may break.
|
|
|
|
|
|
[[encode]]
|
|
encode
|
|
~~~~~~
|
|
|
|
[source,lua]
|
|
------------
|
|
json_text = cjson.encode(value)
|
|
------------
|
|
|
|
+cjson.encode+ will serialise a Lua value into a string containing the
|
|
JSON representation.
|
|
|
|
+cjson.encode+ supports the following types:
|
|
|
|
- +boolean+
|
|
- +lightuserdata+ (NULL value only)
|
|
- +nil+
|
|
- +number+
|
|
- +string+
|
|
- +table+
|
|
|
|
The remaining Lua types will generate an error:
|
|
|
|
- +function+
|
|
- +lightuserdata+ (non-NULL values)
|
|
- +thread+
|
|
- +userdata+
|
|
|
|
By default, numbers are encoded with 14 significant digits. Refer to
|
|
<<encode_number_precision,+cjson.encode_number_precision+>> for details.
|
|
|
|
Lua CJSON will escape the following characters within each UTF-8 string:
|
|
|
|
- Control characters (ASCII 0 - 31)
|
|
- Double quote (ASCII 34)
|
|
- Forward slash (ASCII 47)
|
|
- Blackslash (ASCII 92)
|
|
- Delete (ASCII 127)
|
|
|
|
All other bytes are passed transparently.
|
|
|
|
[CAUTION]
|
|
=========
|
|
Lua CJSON will successfully encode/decode binary strings, but this is
|
|
technically not supported by JSON and may not be compatible with other
|
|
JSON libraries. To ensure the output is valid JSON, applications should
|
|
ensure all Lua strings passed to +cjson.encode+ are UTF-8.
|
|
|
|
Base64 is commonly used to encode binary data as the most efficient
|
|
encoding under UTF-8 can only reduce the encoded size by a further
|
|
~8%. Lua Base64 routines can be found in the
|
|
http://w3.impa.br/%7Ediego/software/luasocket/[LuaSocket] and
|
|
http://www.tecgraf.puc-rio.br/%7Elhf/ftp/lua/#lbase64[lbase64] packages.
|
|
=========
|
|
|
|
Lua CJSON uses a heuristic to determine whether to encode a Lua table as
|
|
a JSON array or an object. A Lua table with only positive integer keys
|
|
of type +number+ will be encoded as a JSON array. All other tables will
|
|
be encoded as a JSON object.
|
|
|
|
Lua CJSON does not use metamethods when serialising tables.
|
|
|
|
- +rawget+ is used to iterate over Lua arrays
|
|
- +next+ is used to iterate over Lua objects
|
|
|
|
Lua arrays with missing entries (_sparse arrays_) may optionally be
|
|
encoded in several different ways. Refer to
|
|
<<encode_sparse_array,+cjson.encode_sparse_array+>> for details.
|
|
|
|
JSON object keys are always strings. Hence +cjson.encode+ only supports
|
|
table keys which are type +number+ or +string+. All other types will
|
|
generate an error.
|
|
|
|
[NOTE]
|
|
Standards compliant JSON must be encapsulated in either an object (+{}+)
|
|
or an array (+[]+). If strictly standards compliant JSON is desired, a
|
|
table must be passed to +cjson.encode+.
|
|
|
|
By default, encoding the following Lua values will generate errors:
|
|
|
|
- Numbers incompatible with the JSON specification (infinity, NaN)
|
|
- Tables nested more than 1000 levels deep
|
|
- Excessively sparse Lua arrays
|
|
|
|
.Example: Encoding
|
|
[source,lua]
|
|
value = { true, { foo = "bar" } }
|
|
json_text = cjson.encode(value)
|
|
-- Returns: '[true,{"foo":"bar"}]'
|
|
|
|
// vi:ft=asciidoc tw=72:
|