Complete json documentation
This commit is contained in:
parent
9e9d3e0213
commit
3da66e8932
1 changed files with 118 additions and 41 deletions
159
ljson.c
159
ljson.c
|
|
@ -1,10 +1,23 @@
|
|||
/***
|
||||
* Manipulation of JavaScript Object Notation
|
||||
* (JSON) values.
|
||||
* Manipulation of JavaScript Object Notation (JSON) values.
|
||||
*
|
||||
* Implementation from
|
||||
* [lua-cjson](https://github.com/openresty/lua-cjson),
|
||||
* with some additional modifications
|
||||
* Implementation from [lua-cjson](https://github.com/openresty/lua-cjson),
|
||||
* with some additional modifications.
|
||||
*
|
||||
* **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, etc.)
|
||||
*
|
||||
* - No dependencies on other libraries
|
||||
*
|
||||
* **Caveats**
|
||||
*
|
||||
* - UTF-16 and UTF-32 are not supported
|
||||
*
|
||||
* @module json
|
||||
*/
|
||||
|
|
@ -15,9 +28,10 @@
|
|||
#include "lcallisto.h"
|
||||
|
||||
|
||||
/* -=[ Functions ]=- */
|
||||
|
||||
/***
|
||||
* Returns the given Lua table encoded
|
||||
* as a JSON object.
|
||||
* Returns the given Lua table encoded as a JSON object.
|
||||
*
|
||||
* @function encode
|
||||
* @usage
|
||||
|
|
@ -34,8 +48,7 @@ local j = json.encode(t)
|
|||
*/
|
||||
|
||||
/***
|
||||
* Returns the given JSON object decoded
|
||||
* into a Lua table.
|
||||
* Returns the given JSON object decoded into a Lua table.
|
||||
*
|
||||
* @function decode
|
||||
* @usage
|
||||
|
|
@ -57,29 +70,31 @@ local t = json.decode(j)
|
|||
* Gets/sets configuration values used when
|
||||
* encoding or decoding JSON objects.
|
||||
*
|
||||
* The *setting* paramater is a string
|
||||
* containing either "encode:" or "decode:"
|
||||
* followed by the name of the setting.
|
||||
* Settings can be found in the
|
||||
* [Settings](#Settings) section.
|
||||
* The *setting* paramater is a string containing either *"encode:"* or
|
||||
* *"decode:"*, followed by the name of the setting. Available settings
|
||||
* can be found in the [Settings](#Settings) section.
|
||||
*
|
||||
* The current setting is always returned, and is only updated
|
||||
* when an argument is provided.
|
||||
*
|
||||
* @function config
|
||||
* @usage json.config("encode:max-depth", 3)
|
||||
* @tparam string setting The setting to get/set.
|
||||
* @param ...
|
||||
*/
|
||||
|
||||
/***
|
||||
* Creates and returns a new independent copy of the
|
||||
* module, with default settings and a separate
|
||||
* persistent encoding buffer.
|
||||
* Creates and returns a new independent copy of the module,
|
||||
* with default settings and a separate persistent encoding buffer.
|
||||
*
|
||||
* @function new
|
||||
*/
|
||||
|
||||
/* -=[ Fields ]=- */
|
||||
|
||||
/***
|
||||
* The name of the module, provided for
|
||||
* compatibility with lua-cjson.
|
||||
* Normally this will just be *"json"*.
|
||||
* The name of the module, provided for compatibility with
|
||||
* lua-cjson. Normally this will just be *"json"*.
|
||||
*
|
||||
* @field _NAME
|
||||
*/
|
||||
|
|
@ -92,26 +107,32 @@ local t = json.decode(j)
|
|||
*/
|
||||
|
||||
/***
|
||||
* Configures handling of extremely sparse arrays.
|
||||
* null value used when decoding JSON objects.
|
||||
*
|
||||
* **Parameters:**
|
||||
* JSON *null* is decoded as a Lua lightuserdata `NULL` pointer.
|
||||
* *json.null* is provided for comparison.
|
||||
*
|
||||
* @setting encode:sparse-array
|
||||
* @tparam integer safe Always use an array when
|
||||
* the max index is larger than this value.
|
||||
* @tparam boolean convert Whether or not to convert
|
||||
* extremely sparse arrays into objects.
|
||||
* @tparam integer ration *0*: always allow sparse;
|
||||
* *1*: never allow sparse; *>1*: use ratio
|
||||
* @field null
|
||||
*/
|
||||
|
||||
/* -=[ Configuration options ]=- */
|
||||
|
||||
/* Decoding */
|
||||
|
||||
/***
|
||||
* Configures the maximum number of nested
|
||||
* arrays/objects allowed when encoding.
|
||||
* Configures handling of invalid numbers while decoding;
|
||||
* numbers not supported by the JSON specification.
|
||||
* Invalid numbers are defined as:
|
||||
*
|
||||
* - infinity
|
||||
* - NaN
|
||||
* - hexadecimals
|
||||
*
|
||||
* **Parameters:**
|
||||
*
|
||||
* @setting encode:max-depth
|
||||
* @tparam integer depth Max depth allowed.
|
||||
* @setting decode:invalid-numbers
|
||||
* @usage json.config("decode:invalid-numbers", false)
|
||||
* @tparam boolean convert Whether or not to accept and decode invalid numbers.
|
||||
*/
|
||||
/***
|
||||
* Configures the maximum number of nested
|
||||
|
|
@ -120,20 +141,76 @@ local t = json.decode(j)
|
|||
* **Parameters:**
|
||||
*
|
||||
* @setting decode:max-depth
|
||||
* @tparam integer depth Max depth allowed.
|
||||
* @usage json.config("decode:max-depth", 4)
|
||||
* @tparam integer depth Max depth allowed when decoding.
|
||||
*/
|
||||
|
||||
/* Encoding */
|
||||
|
||||
/***
|
||||
* Configures handling of invalid numbers while encoding;
|
||||
* numbers not supported by the JSON specification.
|
||||
* Invalid numbers are defined as:
|
||||
*
|
||||
* - infinity
|
||||
* - NaN
|
||||
* - hexadecimals
|
||||
*
|
||||
* **Parameters:**
|
||||
*
|
||||
* @setting encode:invalid-numbers
|
||||
* @usage json.config("encode:invalid-numbers", false)
|
||||
* @tparam boolean convert Whether or not to accept and encode invalid numbers.
|
||||
*/
|
||||
/***
|
||||
* Configures the amount of significant
|
||||
* digits returned when encoding numbers.
|
||||
* This can be used to balance accuracy
|
||||
* versus performance.
|
||||
* Determine whether or not the JSON encoding buffer
|
||||
* should be reused after each call to *encode*.
|
||||
*
|
||||
* If *true*, the buffer will grow to the largest size
|
||||
* required and is not freed until the module is garbage
|
||||
* collected. This is the default setting.
|
||||
*
|
||||
* If *false*, the encode buffer is freed after each call.
|
||||
*
|
||||
* **Parameters:**
|
||||
*
|
||||
* @setting encode:keep-buffer
|
||||
* @usage json.config("encode:keep-buffer", false)
|
||||
* @tparam integer keep Whether or not the JSON encoding buffer should be reused.
|
||||
*/
|
||||
/***
|
||||
* Configures the maximum number of nested
|
||||
* arrays/objects allowed when encoding.
|
||||
*
|
||||
* **Parameters:**
|
||||
*
|
||||
* @setting encode:max-depth
|
||||
* @usage json.config("encode:max-depth", 4)
|
||||
* @tparam integer depth Max depth allowed when encoding.
|
||||
*/
|
||||
/***
|
||||
* Configures the amount of significant digits returned when encoding
|
||||
* numbers. This can be used to balance accuracy versus performance.
|
||||
*
|
||||
* **Parameters:**
|
||||
*
|
||||
* @setting encode:number-precision
|
||||
* @tparam integer precision Amount of significant
|
||||
* digits to return in floating-point numbers (must
|
||||
* be between 1 and 14, default 14)
|
||||
* @usage json.config("encode:number-precision", 2)
|
||||
* @tparam integer precision Amount of significant digits to return in
|
||||
* floating-point numbers (must be between 1 and 14, default 14)
|
||||
*/
|
||||
/***
|
||||
* Configures handling of extremely sparse arrays.
|
||||
*
|
||||
* **Parameters:**
|
||||
*
|
||||
* @setting encode:sparse-array
|
||||
* @tparam[opt] integer safe Always use an array when the max index is
|
||||
* larger than this value.
|
||||
* @tparam[opt] boolean convert Whether or not to convert extremely sparse
|
||||
* arrays into objects.
|
||||
* @tparam[opt] integer ration *0*: always allow sparse; *1*: never allow
|
||||
* sparse; *>1*: use ratio
|
||||
*/
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue