Complete json documentation

ljson.c

@@ -1,10 +1,23 @@
 /***
- * Manipulation of JavaScript Object Notation
+ * Manipulation of JavaScript Object Notation (JSON) values.
- * (JSON) values.
  *
- * Implementation from
+ * Implementation from [lua-cjson](https://github.com/openresty/lua-cjson),
- * [lua-cjson](https://github.com/openresty/lua-cjson),
+ * with some additional modifications.
- * 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
+ * Returns the given Lua table encoded as a JSON object.
- * as a JSON object.
  *
  * @function encode
  * @usage
@@ -34,8 +48,7 @@ local j = json.encode(t)
  */
 
 /***
- * Returns the given JSON object decoded
+ * Returns the given JSON object decoded into a Lua table.
- * 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
+ * The *setting* paramater is a string containing either *"encode:"* or
- * containing either "encode:" or "decode:"
+ * *"decode:"*, followed by the name of the setting. Available settings
- * followed by the name of the setting.
+ * can be found in the [Settings](#Settings) section.
- * 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
+ * Creates and returns a new independent copy of the module,
- * module, with default settings and a separate
+ * with default settings and a separate persistent encoding buffer.
- * persistent encoding buffer.
  *
  * @function new
  */
 
+/* -=[ Fields ]=- */
+
 /***
- * The name of the module, provided for
+ * The name of the module, provided for compatibility with
- * compatibility with lua-cjson.
+ * lua-cjson. Normally this will just be *"json"*.
- * 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
+ * @field null
- * @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
  */
+
+/* -=[ Configuration options ]=- */
+
+/* Decoding */
+
 /***
- * Configures the maximum number of nested
+ * Configures handling of invalid numbers while decoding;
- * arrays/objects allowed when encoding.
+ * numbers not supported by the JSON specification.
+ * Invalid numbers are defined as:
+ *
+ *  - infinity
+ *  - NaN
+ *  - hexadecimals
  *
  * **Parameters:**
  *
- * @setting encode:max-depth
+ * @setting decode:invalid-numbers
- * @tparam integer depth Max depth allowed.
+ * @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
+ * Determine whether or not the JSON encoding buffer
- * digits returned when encoding numbers.
+ * should be reused after each call to *encode*.
- * This can be used to balance accuracy
+ *
- * versus performance.
+ * 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
+ * @usage json.config("encode:number-precision", 2)
- * digits to return in floating-point numbers (must
+ * @tparam integer precision Amount of significant digits to return in
- * be between 1 and 14, default 14)
+ *   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
  */