 |
Qore json Module 1.8.2
|
|
Qore json Module 1.8.2
|
The json module allows for easy serialization and deserialization between JSON strings and Qore data structures. The module also provides functions for JSON-RPC support as well as a JsonRpcClient class for easier integration with JavaScript clients.
Overview of the functionality provided by this module:
This module is released under a choice of two licenses:
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 %requires directive as follows:
Also included with the binary json module:
JSON Serialization
| Qore Type | JSON-RPC Type | Description |
string | string | direct conversion to UTF-8 string |
int | number | direct conversion |
float | number | direct conversion |
bool | boolean | direct conversion |
date | string | date/time values are serialized to strings like: "2010-12-22 16:35:36.372996 Wed +01:00 (CET)"; intervals are serialized to ISO-8601 duration strings (ex: "PT2M1S") |
binary | string | binary values are serialized as base64 encoded strings |
list | array | direct conversion |
hash | struct | direct conversion |
NOTHING or NULL | null | direct conversion |
| all others | n/a | All other types will cause an JSON-RPC-SERIALIZATION-ERROR to be raised. |
JSON Deserialization
| JSON-RPC Type | Qore Type | Description |
string | string | direct conversion |
number | int or float | if the JSON number is an integer, it is converted as an int, otherwise as a float |
boolean | bool | direct conversion |
array | list | direct conversion |
struct | hash | direct conversion |
null | NOTHING | direct conversion |
This following functions provide automatic JSON serialization and deserialization:
Functions For JSON Serialization and Deserialization
| Function Name | Description |
| make_json() | Serializes qore data into a JSON string with optional verbose whitespace formatting for easier human readability |
| parse_json() | Parses a JSON string and returns the corresponding Qore data structure |
Deprecated JSON Functions
| Deprecated Function Name | New Function Name |
| makeFormattedJSONString() | make_json() |
| makeJSONString() | make_json() |
| parseJSON() | parse_json() |
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 "2.0" unless explicitly changed in the JsonRpcClient::constructor().
Classes Providing JSON-RPC Functionality
| Class | Description |
| JsonRpcClient | For communicating with JSON-RPC servers |
Functions Providing JSON-RPC Functionality
| Function Name | Description |
| make_jsonrpc_error() | a generic JSON-RPC error response string from the parameters passed with optional verbose whitespace formatting for easier human readability |
| make_jsonrpc_request() | Creates a JSON-RPC request string from the parameters passed with optional verbose whitespace formatting for easier human readability |
| make_jsonrpc_response() | Creates a JSON-RPC response string from the parameters passed with optional verbose whitespace formatting for easier human readability |
Deprecated JSON-RPC Functions
| Deprecated Function Name | New Function Name |
| makeFormattedJSONRPC11ErrorString() | support for the non-published JSON-RPC 1.1 protocol was deprecated in json 1.7 |
| makeFormattedJSONRPCErrorString() | make_jsonrpc_error() |
| makeFormattedJSONRPCRequestString() | make_jsonrpc_request() |
| makeFormattedJSONRPCResponseString() | make_jsonrpc_response() |
| makeJSONRPC11ErrorString() | support for the non-published JSON-RPC 1.1 protocol was deprecated in json 1.7 |
| makeJSONRPCErrorString() | make_jsonrpc_error() |
| makeJSONRPCRequestString() | make_jsonrpc_request() |
| makeJSONRPCResponseString() | make_jsonrpc_response() |
| make_jsonrpc11_error() | support for the non-published JSON-RPC 1.1 protocol was deprecated in json 1.7 |
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 "call-with-type-errors" warning is raised (assuming this warning is enabled), unless PO_REQUIRE_TYPES or PO_STRICT_ARGS is set. If PO_REQUIRE_TYPES or 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 RUNTIME_NOOP, except no runtime effect is caused by resolving a function or method tagged with NOOP at runtime; this tag only affects parse time resolution.
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 "call-with-type-errors" warning is raised (assuming this warning is enabled), unless PO_REQUIRE_TYPES or PO_STRICT_ARGS is set. If PO_REQUIRE_TYPES or 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 NOOP, except that RUNTIME_NOOP is also enforced at runtime.
This flag indicates that the function or method has no side effects; it only returns a value, for example.
This tag is identical to CONSTANT except that functions or methods tagged with RET_VALUE_ONLY could throw exceptions.
This flag indicates that the function or method has no side effects and does not throw any exceptions.
This tag is identical to RET_VALUE_ONLY except that functions or methods tagged with CONSTANT do not throw exceptions.
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 "deprecated" warning is raised (assuming this warning is enabled).
null according to the JSON speccharset=utf-8 in the Content-Type in JsonRpcClient; JSON messages are always serialized with UTF-8 encoding