From fe25699a3ba84a35fac58bc7236ab6b3ff3e7ba3 Mon Sep 17 00:00:00 2001 From: Mark Pulford Date: Tue, 20 Dec 2011 00:14:16 +1030 Subject: Add UTF-8 caution to manual (and misc changes) --- manual.txt | 34 ++++++++++++++++++++++++---------- 1 file changed, 24 insertions(+), 10 deletions(-) diff --git a/manual.txt b/manual.txt index bb946fe..8a894c0 100644 --- a/manual.txt +++ b/manual.txt @@ -1,6 +1,6 @@ = Lua CJSON 1.0devel Manual = Mark Pulford -:revdate: 30th November 2011 +:revdate: November 30, 2011 Overview -------- @@ -8,7 +8,7 @@ Overview Lua CJSON provides fast JSON parsing and encoding support for Lua. .Features -- More than 10x to 20x faster than the efficient pure Lua JSON modules. +- More than 10x to 20x faster than efficient pure Lua JSON modules. - Full support for JSON with UTF-8, including decoding surrogate pairs. - Optional run-time support for common exceptions to the JSON @@ -48,10 +48,9 @@ Build options (#define) ~~~~~~~~~~~~~~~~~~~~~~~ Lua CJSON uses +strtod+(3) and +snprintf+(3) to perform numeric -conversion as they are usually well supported, fast and bug free. To -ensure JSON encoding/decoding works correctly under locales using -comma decimal separators, Lua CJSON may optionally be compiled with -one of the following preprocessor macros: +conversion as they are usually well supported, fast and bug free. Lua +CJSON may optionally be compiled with (only) one of the following +preprocessor macros to support locales with comma decimal separators: [horizontal] USE_POSIX_USELOCALE:: Thread safe. Supported by Linux and Mac OSX. @@ -222,9 +221,10 @@ The remaining Lua types will generate an error: - +userdata+ By default, numbers are encoded using the standard Lua number -+printf+(3) format ("%.14g"). ++printf+(3) format (+%.14g+). -Lua CJSON will escape the following characters within each string: +Lua CJSON will escape the following characters within each UTF-8 +string: - Control characters (ASCII 0 - 31) - Double quote (ASCII 34) @@ -232,8 +232,20 @@ Lua CJSON will escape the following characters within each string: - Blackslash (ASCII 92) - Delete (ASCII 127) -All other characters are passed transparently. Any UTF-8 error -checking must be done by the application. +All other characters 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. Applications should ensure all Lua strings passed to ++cjson.encode+ are valid UTF-8 to ensure the output is valid JSON. + +Base64 is a common way to transport binary data through JSON. Lua +Base64 routines can be found in the +http://w3.impa.br/~diego/software/luasocket/[LuaSocket] and +http://www.tecgraf.puc-rio.br/~lhf/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 integers @@ -256,6 +268,7 @@ generate an error. Standards compliant JSON must be encapsulated in either an object (+{}+) or an array (+[]+). Hence a table must be passed to +cjson.encode+ to generate standards compliant JSON output. +This may not be required by some applications. By default, the following Lua values will generate errors: @@ -430,4 +443,5 @@ References - http://tools.ietf.org/html/rfc4627[RFC 4627] - http://www.json.org/[JSON website] + // vi:tw=70: -- cgit v1.2.3-55-g6feb