/** @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.

    Overview of the functionality provided by this module:
    - classes:
      - @ref Qore::Json::JsonRpcClient "JsonRpcClient"
    - functions:
      - @ref Qore::Json::make_json() "make_json()"
      - @ref Qore::Json::parse_json() "parse_json()"
      - @ref Qore::Json::make_jsonrpc_error() "make_jsonrpc_error()"
      - @ref Qore::Json::make_jsonrpc_request() "make_jsonrpc_request()"
      - @ref Qore::Json::make_jsonrpc_response() "make_jsonrpc_response()"
    - user modules:
      - <a href="../../JsonRpcConnection/html/index.html">JsonRpcConnection</a>
      - <a href="../../JsonRpcHandler/html/index.html">JsonRpcHandler</a>
      - <a href="../../McpServerHandler/html/index.html">McpServerHandler</a>

    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="../../JsonRpcConnection/html/index.html">JsonRpcConnection</a> user module
    - <a href="../../JsonRpcHandler/html/index.html">JsonRpcHandler</a> user module
    - <a href="../../McpServerHandler/html/index.html">McpServerHandler</a> user module

    @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)"; intervals are serialized to ISO-8601 duration strings \
        (ex: \c "PT2M1S")
    |\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 Functions</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 several versions of the JSON-RPC protocol; the default protocol
    version used is \c "2.0" unless explicitly changed in the
    @ref Qore::Json::JsonRpcClient::constructor() "JsonRpcClient::constructor()".

    <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_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()|support for the non-published JSON-RPC 1.1 protocol was deprecated in \
        json 1.7
    |@ref makeFormattedJSONRPCErrorString()|@ref make_jsonrpc_error()
    |@ref makeFormattedJSONRPCRequestString()|@ref make_jsonrpc_request()
    |@ref makeFormattedJSONRPCResponseString()|@ref make_jsonrpc_response()
    |@ref makeJSONRPC11ErrorString()|support for the non-published JSON-RPC 1.1 protocol was deprecated in json 1.7
    |@ref makeJSONRPCErrorString()|@ref make_jsonrpc_error()
    |@ref makeJSONRPCRequestString()|@ref make_jsonrpc_request()
    |@ref makeJSONRPCResponseString()|@ref make_jsonrpc_response()
    |@ref make_jsonrpc11_error()|support for the non-published JSON-RPC 1.1 protocol was deprecated in json 1.7

    @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 json_v1_9 json Module Version 1.9
    - added support for an MCP server with the <a href="../../McpServerHandler/html/index.html">McpServerHandler</a>
      module

    @subsection json_v1_8_2 json Module Version 1.8.2
    - fixed minor formatting issues in formatted JSON output for better readability and consistency
      (<a href="https://github.com/qorelanguage/qore/issues/4499">issue 4499</a>)

    @subsection json_v1_8_1 json Module Version 1.8.1
    - eliminated excess whitespace from compact JSON serialization
      (<a href="https://github.com/qorelanguage/qore/issues/4459">issue 4459</a>)

    @subsection json_v0_1_8 json Module Version 1.8
    - fixed a bug where numbers in scientific notation could not be parsed
      (<a href="https://github.com/qorelanguage/qore/issues/3707">issue 3707</a>)
    - implemented support for serializing connection objects
      (<a href="https://github.com/qorelanguage/qore/issues/3696">issue 3696</a>)
    - fixed the return types of deserialization to avoid type stripping
      (<a href="https://github.com/qorelanguage/qore/issues/3432">issue 3432</a>)
    - fixed output of excess noise in floating-point values
      (<a href="https://github.com/qorelanguage/qore/issues/3375">issue 3375</a>)
    - updated the <a href="../../JsonRpcConnection/html/index.html">JsonRpcConnection</a> module to support the
      updated abstract connection API
      (<a href="https://github.com/qorelanguage/qore/issues/2628">issue 2628</a>)
    - added support for serializing intervals to strings that can be manually converted to the original value
      (<a href="https://github.com/qorelanguage/qore/issues/3135">issue 3135</a>)

    @subsection json_v0_1_7 json Module Version 1.7
    - deprecated support for the non-published JSON-RPC 1.1 protocol
    - added support for JSON-RPC 2.0
    - added the <a href="../../JsonRpcConnection/html/index.html">JsonRpcConnection</a> user module
    - improved argument error messages with RPC calls in the
      <a href="../../JsonRpcHandler/html/index.html">JsonRpcHandler</a> module
      (<a href="https://github.com/qorelanguage/qore/issues/2573">issue 2573</a>)
    - fixed date serialization to use ISO-8601 format (instead of near-ISO-8601 format
      <a href="https://github.com/qorelanguage/qore/issues/2655">issue 2655</a>)

    @subsection json_v0_1_6 json Module 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 json_v0_1_5 json Module 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; less extraneous whitespace is used

    @subsection json_v0_1_4 json Module 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 json_v0_1_3 json Module 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 json_v0_1_2 json Module Version 1.2

    - fixed serialization/deserialization/escaping regarding control characters

    @subsection json_v0_1_1 json Module 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 json_v0_1_0 json Module Version 1.0

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