/** @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>
    @htmlonly <style><!-- td.qore { background-color: #5b9409; color: white; } --></style> @endhtmlonly
    <table>
      <tr>
        <td class="qore"><b>%Qore Type</b></td>
        <td class="qore"><b>JSON-RPC Type</b></td>
        <td class="qore"><b>Description</b></td>
      </tr>
      <tr>
        <td>\c string</td>
        <td>\c string</td>
        <td>direct conversion to UTF-8 string</td>
      </tr>
      <tr>
        <td>\c int</td>
        <td>\c number</td>
        <td>direct conversion</td>
      </tr>
      <tr>
        <td>\c float</td>
        <td>\c number</td>
        <td>direct conversion</td>
      </tr>
      <tr>
        <td>\c bool</td>
        <td>\c boolean</td>
        <td>direct conversion</td>
      </tr>
      <tr>
        <td>\c date</td>
        <td>\c string</td>
        <td>date/time values are serialized to strings like: \c "2010-12-22 16:35:36.372996 Wed +01:00 (CET)"</td>
      </tr>
      <tr>
        <td>\c binary</td>
        <td>\c string</td>
        <td>binary values are serialized as base64 encoded strings</td>
      </tr>
      <tr>
        <td>\c list</td>
        <td>\c array</td>
        <td>direct conversion</td>
      </tr>
      <tr>
        <td>\c hash</td>
        <td>\c struct</td>
        <td>direct conversion</td>
      </tr>
      <tr>
        <td>\c NOTHING or \c NULL</td>
        <td>\c null</td>
        <td>direct conversion</td>
      </tr>
      <tr>
        <td>all others</td>
        <td>n/a</td>
        <td>All other types will cause an \c JSON-RPC-SERIALIZATION-ERROR to be raised.</td>
      </tr>
    </table>

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

    This following functions provide automatic JSON serialization and deserialization:

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

    <b>Deprecated JSON-RPC</b>
    <table>
      <tr>
        <td class="qore"><b>Deprecated Function Name</b></td>
        <td class="qore"><b>New Function Name</b></td>
      </tr>
      <tr>
        <td>@ref makeFormattedJSONString()</td>
        <td>@ref make_json()</td>
      </tr>
      <tr>
        <td>@ref makeJSONString()</td>
        <td>@ref make_json()</td>
      </tr>
      <tr>
        <td>@ref parseJSON()</td>
        <td>@ref parse_json()</td>
      </tr>
    </table>

    @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>
    <table>
      <tr>
        <td class="qore"><b>Class</b></td>
        <td class="qore"><b>Description</b></td>
      </tr>
      <tr>
        <td>@ref Qore::Json::JsonRpcClient "JsonRpcClient"</td>
        <td>For communicating with JSON-RPC servers</td>
      </tr>
    </table>

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

    <b>Deprecated JSON-RPC Functions</b>
    <table>
      <tr>
        <td class="qore"><b>Deprecated Function Name</b></td>
        <td class="qore"><b>New Function Name</b></td>
      </tr>
      <tr>
        <td>@ref makeFormattedJSONRPC11ErrorString()</td>
        <td>@ref make_jsonrpc11_error()</td>
      </tr>
      <tr>
        <td>@ref makeFormattedJSONRPCErrorString()</td>
        <td>@ref make_jsonrpc_error()</td>
      </tr>
      <tr>
        <td>@ref makeFormattedJSONRPCRequestString()</td>
        <td>@ref make_jsonrpc_request()</td>
      </tr>
      <tr>
        <td>@ref makeFormattedJSONRPCResponseString()</td>
        <td>@ref make_jsonrpc_response()</td>
      </tr>
      <tr>
        <td>@ref makeJSONRPC11ErrorString()</td>
        <td>@ref make_jsonrpc11_error()</td>
      </tr>
      <tr>
        <td>@ref makeJSONRPCErrorString()</td>
        <td>@ref make_jsonrpc_error()</td>
      </tr>
      <tr>
        <td>@ref makeJSONRPCRequestString()</td>
        <td>@ref make_jsonrpc_request()</td>
      </tr>
      <tr>
        <td>@ref makeJSONRPCResponseString()</td>
        <td>@ref make_jsonrpc_response()</td>
      </tr>
    </table>

    @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

*/