/** @mainpage Qore JSON Module

    @tableofcontents

    @section jsonintro Introduction

    The json module allows for easy serialization and deserialization between <a href="http://www.json.org/">JSON</a> strings and %Qore data structures.  The module also provides functions for @ref JSONRPC support as well as a @ref Qore::Json::JsonRpcClient "JsonRpcClient" class for easier integration with JavaScript clients.

    This module is released under a choice of two licenses:
    - <a href="http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html">LGPL 2.1</a>
    - MIT (see COPYING.MIT in the source distribution for more information)
    .
    The module is tagged as such in the module's header (meaning it can be loaded unconditionally regardless of how the %Qore library was initialized).

    To use the module in a %Qore script, use the \c %%requires directive as follows:
    @code %requires json @endcode

    Also included with the binary json module:
    - <a href="../../JsonRpcHandler/html/index.html">JsonRpcHandler user module</a>

    @note JSON functionality was included in the main %Qore shared library until version 0.8.1, at which time the code was removed to make this module.

    @section jsonserialization Automatic JSON Serialization and Deserialization

    <b>JSON Serialization</b>
    |!%Qore Type|!JSON-RPC Type|!Description
    |\c string|\c string|direct conversion to UTF-8 string
    |\c int|\c number|direct conversion
    |\c float|\c number|direct conversion
    |\c bool|\c boolean|direct conversion
    |\c date|\c string|date/time values are serialized to strings like: \c "2010-12-22 16:35:36.372996 Wed +01:00 (CET)"
    |\c binary|\c string|binary values are serialized as base64 encoded strings
    |\c list|\c array|direct conversion
    |\c hash|\c struct|direct conversion
    |\c NOTHING or \c NULL|\c null|direct conversion
    |all others|n/a|All other types will cause an \c JSON-RPC-SERIALIZATION-ERROR to be raised.

    <b>JSON Deserialization</b>
    |!JSON-RPC Type|!%Qore Type|!Description
    |\c string|\c string|direct conversion
    |\c number|\c int or \c float|if the JSON number is an integer, it is converted as an \c int, otherwise as a \c float
    |\c boolean|\c bool|direct conversion
    |\c array|\c list|direct conversion
    |\c struct|\c hash|direct conversion
    |\c null|\c NOTHING|direct conversion

    This following functions provide automatic JSON serialization and deserialization:

    <b>Functions For JSON Serialization and Deserialization</b>
    |!Function Name|!Description
    |@ref make_json()|Serializes qore data into a JSON string with optional verbose whitespace formatting for easier human readability
    |@ref parse_json()|Parses a JSON string and returns the corresponding %Qore data structure

    <b>Deprecated JSON-RPC</b>
    |!Deprecated Function Name|!New Function Name
    |@ref makeFormattedJSONString()|@ref make_json()
    |@ref makeJSONString()|@ref make_json()
    |@ref parseJSON()|@ref parse_json()

    @section JSONRPC JSON-RPC

    JSON-RPC is a lightweight but powerful JSON over HTTP web service protocol.  The json module includes builtin support for this protocol as described here.

    Information about %Qore's JSON-RPC serialization can be found below.

    <b>Classes Providing JSON-RPC Functionality</b>
    |!Class|!Description
    |@ref Qore::Json::JsonRpcClient "JsonRpcClient"|For communicating with JSON-RPC servers

    <b>Functions Providing JSON-RPC Functionality</b>
    |!Function Name|!Description
    |@ref make_jsonrpc11_error()|Creates a JSON-RPC 1.1 error response string from the parameters passed with optional verbose whitespace formatting for easier human readability
    |@ref make_jsonrpc_error()|a generic JSON-RPC error response string from the parameters passed with optional verbose whitespace formatting for easier human readability
    |@ref make_jsonrpc_request()|Creates a JSON-RPC request string from the parameters passed with optional verbose whitespace formatting for easier human readability
    |@ref make_jsonrpc_response()|Creates a JSON-RPC response string from the parameters passed with optional verbose whitespace formatting for easier human readability

    <b>Deprecated JSON-RPC Functions</b>
    |!Deprecated Function Name|!New Function Name
    |@ref makeFormattedJSONRPC11ErrorString()|@ref make_jsonrpc11_error()
    |@ref makeFormattedJSONRPCErrorString()|@ref make_jsonrpc_error()
    |@ref makeFormattedJSONRPCRequestString()|@ref make_jsonrpc_request()
    |@ref makeFormattedJSONRPCResponseString()|@ref make_jsonrpc_response()
    |@ref makeJSONRPC11ErrorString()|@ref make_jsonrpc11_error()
    |@ref makeJSONRPCErrorString()|@ref make_jsonrpc_error()
    |@ref makeJSONRPCRequestString()|@ref make_jsonrpc_request()
    |@ref makeJSONRPCResponseString()|@ref make_jsonrpc_response()

    @section codetags Function and Method Tags

    @subsection NOOP NOOP

    Code with this flag makes no calculations, but rather returns a constant value. This flag is given to function and method variants that return a default value depending on the type of argument(s).  When variants with this flag are resolved at parse time, a \c "call-with-type-errors" warning is raised (assuming this warning is enabled), unless \c PO_REQUIRE_TYPES or \c PO_STRICT_ARGS is set.  If \c PO_REQUIRE_TYPES or \c PO_STRICT_ARGS is set, then these variants are inaccessible at parse time; resolving to a variant with this flag set at parse time causes an exception to be thrown.

    These variants are included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments.

    This tag is equal to @ref RUNTIME_NOOP, except no runtime effect is caused by resolving a function or method tagged with \c NOOP at runtime; this tag only affects parse time resolution.

    @subsection RUNTIME_NOOP RUNTIME_NOOP

    Code with this flag makes no calculations, but rather returns a constant value.  This flag is given to function and method variants that return a default value depending on the type of argument(s).  When variants with this flag are resolved at parse time, a \c "call-with-type-errors" warning is raised (assuming this warning is enabled), unless \c PO_REQUIRE_TYPES or \c PO_STRICT_ARGS is set.  If \c PO_REQUIRE_TYPES or \c PO_STRICT_ARGS is set, then these variants are inaccessible; resolving to a variant with this flag set at parse time or run time causes an exception to be thrown.

    These variants are included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments.

    This tag is equal to @ref NOOP, except that \c RUNTIME_NOOP is also enforced at runtime.

    @subsection RET_VALUE_ONLY RET_VALUE_ONLY

    This flag indicates that the function or method has no side effects; it only returns a value, for example.

    This tag is identical to @ref CONSTANT except that functions or methods tagged with \c RET_VALUE_ONLY could throw exceptions.

    @subsection CONSTANT CONSTANT

    This flag indicates that the function or method has no side effects and does not throw any exceptions.

    This tag is identical to @ref RET_VALUE_ONLY except that functions or methods tagged with \c CONSTANT do not throw exceptions.

    @subsection DEPRECATED DEPRECATED

    Code with this flag is deprecated and may be removed in a future version of this module; if a variant with this flag is resolved at parse time, a \c "deprecated" warning is raised (assuming this warning is enabled).

    @section jsonreleasenotes Release Notes

    @subsection v0_1_6 Version 1.6
    - @ref parse_json() now ignores UTF-8 and Unicode BOMs at the start of passed JSON string  (<a href="https://github.com/qorelanguage/qore/issues/1398">issue 1398</a>)
    - fixed a bug in request logging in the <a href="../../JsonRpcHandler/html/index.html">JsonRpcHandler</a> module (<a href="https://github.com/qorelanguage/qore/issues/1487">issue 1487</a>)
    - fixed a bug serializing hash keys with embedded quotes (<a href="https://github.com/qorelanguage/qore/issues/2242">issue 2242</a>)

    @subsection v0_1_5 Version 1.5
    - serialize binary values as base64-encoded strings
    - user modules moved to top-level qore module directory from version-specific module directory since they are valid for multiple versions of qore
    - serialize nan, +/-inf as \c null according to the JSON spec
    - added detection for invalid JSON-RPC calls and added a more user-friendly error message in the <a href="../../JsonRpcHandler/html/index.html">JsonRpcHandler</a> module
    - new functions added conforming to %Qore's function naming convention, old camel-case functions deprecated
    - JSON tests ported to QUnit
    - %Qore 0.8.12 required as a minimum to build
    - JSON output is more compact; fewer extransous whitespaces are used

    @subsection v0_1_4 Version 1.4

    - date/time values are always serialized with microseconds and in the local time zone for consistency's sake
    - fixed a crashing bug in the JSON control-character encoding algorithm
    - updated the <a href="../../JsonRpcHandler/html/index.html">JsonRpcHandler</a> module for enhanced logging
    - source released under the MIT license as well as LGPL 2.1

    @subsection v0_1_3 Version 1.3

    - always include \c charset=utf-8 in the \c Content-Type in @ref Qore::Json::JsonRpcClient "JsonRpcClient"; JSON messages are always serialized with UTF-8 encoding

    @subsection v0_1_2 Version 1.2

    - fixed serialization/deserialization/escaping regarding control characters

    @subsection v0_1_1 Version 1.1

    - added support for the new arbitrary-precision numeric type introduced in qore 0.8.6
    - serialize control characters with escape codes to be compatible with common Javascript JSON libraries (also corresponding deserialization support)

    @subsection v0_1_0 Version 1.0

    - Initial release of the json module
    - Requires qore 0.8.1+ to build and run

*/