From 3da66e89328792795c3f76b3d30eb873c4039c5a Mon Sep 17 00:00:00 2001 From: Jeremy Baxter Date: Sun, 9 Jul 2023 18:03:10 +1200 Subject: [PATCH] Complete json documentation --- ljson.c | 159 +++++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 118 insertions(+), 41 deletions(-) diff --git a/ljson.c b/ljson.c index d7a0e0a..7a3d714 100644 --- a/ljson.c +++ b/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 */