openresty-1.15.8.3.tar.gz

= 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. The latest version of this software is available from the http://www.kyne.com.au/%7Emark/software/lua-cjson.php[Lua CJSON website]. Feel free to email me if you have any patches, suggestions, or comments. Installation ------------ Lua CJSON requires either http://www.lua.org[Lua] 5.1, Lua 5.2, or http://www.luajit.org[LuaJIT] to build. The build method can be selected from 4 options: Make:: Unix (including Linux, BSD, Mac OSX & Solaris), Windows CMake:: Unix, Windows RPM:: Linux LuaRocks:: Unix, Windows Make ~~~~ The included +Makefile+ has generic settings. First, review and update the included makefile to suit your platform (if required). Next, build and install the module: [source,sh] make install Or install manually into your Lua module directory: [source,sh] make cp cjson.so $LUA_MODULE_DIRECTORY CMake ~~~~~ http://www.cmake.org[CMake] can generate build configuration for many different platforms (including Unix and Windows). First, generate the makefile for your platform using CMake. If CMake is unable to find Lua, manually set the +LUA_DIR+ environment variable to the base prefix of your Lua 5.1 installation. While +cmake+ is used in the example below, +ccmake+ or +cmake-gui+ may be used to present an interface for changing the default build options. [source,sh] mkdir build cd build # Optional: export LUA_DIR=$LUA51_PREFIX cmake .. Next, build and install the module: [source,sh] make install # Or: make cp cjson.so $LUA_MODULE_DIRECTORY Review the http://www.cmake.org/cmake/help/documentation.html[CMake documentation] for further details. RPM ~~~ Linux distributions using http://rpm.org[RPM] can create a package via the included RPM spec file. Ensure the +rpm-build+ package (or similar) has been installed. Build and install the module via RPM: [source,sh] rpmbuild -tb lua-cjson-2.1devel.tar.gz rpm -Uvh $LUA_CJSON_RPM LuaRocks ~~~~~~~~ http://luarocks.org[LuaRocks] can be used to install and manage Lua modules on a wide range of platforms (including Windows). First, extract the Lua CJSON source package. Next, install the module: [source,sh] cd lua-cjson-2.1devel luarocks make [NOTE] LuaRocks does not support platform specific configuration for Solaris. On Solaris, you may need to manually uncomment +USE_INTERNAL_ISINF+ in the rockspec before building this module. Review the http://luarocks.org/en/Documentation[LuaRocks documentation] for further details. [[build_options]] Build Options (#define) ~~~~~~~~~~~~~~~~~~~~~~~ Lua CJSON offers several +#define+ build options to address portability issues, and enable non-default features. Some build methods may automatically set platform specific options if required. Other features should be enabled manually. USE_INTERNAL_ISINF:: Workaround for Solaris platforms missing +isinf+. DISABLE_INVALID_NUMBERS:: Recommended on platforms where +strtod+ / +sprintf+ are not POSIX compliant (eg, Windows MinGW). Prevents +cjson.encode_invalid_numbers+ and +cjson.decode_invalid_numbers+ from being enabled. However, +cjson.encode_invalid_numbers+ may still be set to +"null"+. When using the Lua CJSON built-in floating point conversion this option is unnecessary and is ignored. Built-in floating point conversion ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Lua CJSON may be built with David Gay's http://www.netlib.org/fp/[floating point conversion routines]. This can increase overall performance by up to 50% on some platforms when converting a large amount of numeric data. However, this option reduces portability and is disabled by default. USE_INTERNAL_FPCONV:: Enable internal number conversion routines. IEEE_BIG_ENDIAN:: Must be set on big endian architectures. MULTIPLE_THREADS:: Must be set if Lua CJSON may be used in a multi-threaded application. Requires the _pthreads_ library. API (Functions) --------------- Synopsis ~~~~~~~~ [source,lua] ------------ -- Module instantiation local cjson = require "cjson" local cjson2 = cjson.new() local cjson_safe = require "cjson.safe" -- Translate Lua value to/from JSON text = cjson.encode(value) value = cjson.decode(text) -- Get and/or set Lua CJSON configuration setting = cjson.decode_invalid_numbers([setting]) setting = cjson.encode_invalid_numbers([setting]) keep = cjson.encode_keep_buffer([keep]) depth = cjson.encode_max_depth([depth]) depth = cjson.decode_max_depth([depth]) convert, ratio, safe = cjson.encode_sparse_array([convert[, ratio[, safe]]]) ------------ Module Instantiation ~~~~~~~~~~~~~~~~~~~~ [source,lua] ------------ local cjson = require "cjson" local cjson2 = cjson.new() local cjson_safe = require "cjson.safe" ------------ Import Lua CJSON via the Lua +require+ function. Lua CJSON does not register a global module table. The +cjson+ module will throw an error during JSON conversion if any invalid data is encountered. Refer to <<cjson_encode,+cjson.encode+>> and <<cjson_decode,+cjson.decode+>> for details. The +cjson.safe+ module behaves identically to the +cjson+ module, except when errors are encountered during JSON conversion. On error, the +cjson_safe.encode+ and +cjson_safe.decode+ functions will return +nil+ followed by the error message. +cjson.new+ can be used to instantiate an independent copy of the Lua CJSON module. The new module has a separate persistent encoding buffer, and default settings. Lua CJSON can support Lua implementations using multiple preemptive threads within a single Lua state provided the persistent encoding buffer is not shared. This can be achieved by one of the following methods: - Disabling the persistent encoding buffer with <<encode_keep_buffer,+cjson.encode_keep_buffer+>> - Ensuring each thread calls <<encode,+cjson.encode+>> separately (ie, treat +cjson.encode+ as non-reentrant). - Using a separate +cjson+ module table per preemptive thread (+cjson.new+) [NOTE] Lua CJSON uses +strtod+ and +snprintf+ to perform numeric conversion as they are usually well supported, fast and bug free. However, these functions require a workaround for JSON encoding/parsing under locales using a comma decimal separator. Lua CJSON detects the current locale during instantiation to determine and automatically implement the workaround if required. Lua CJSON should be reinitialised via +cjson.new+ if the locale of the current process changes. Using a different locale per thread is not supported. 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.