Qore JSON Module  1.4
 All Classes Namespaces Functions Groups
Qore JSON Module

Introduction

The json module allows for easy serialization and deserialization between <a href="http://www.json.org/"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.

This module is released under a choice of two licenses:

  • LGPL 2.1
  • 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 %requires directive as follows:

%requires json

Also included with the binary json 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.

Automatic JSON Serialization and Deserialization

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)"
list array direct conversion
hash struct direct conversion
NOTHING or NULL null directo 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
makeFormattedJSONString() Serializes qore data into a JSON string, formatted with line breaks for easier readability
makeJSONString() Serializes qore data into a JSON string, without any line breaks
parseJSON() Parses a JSON string and returns the corresponding qore data structure

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.

Classes Providing JSON-RPC Functionality

Class Description
JsonRpcClient For communicating with JSON-RPC servers

Functions Providing JSON-RPC Functionality

Function Name Description
makeFormattedJSONRPC11ErrorString() Creates a JSON-RPC 1.1 error response string from the parameters passed, formatted with line breaks for easier readability
makeFormattedJSONRPCErrorString() Creates a generic JSON-RPC error response string from the parameters passed, formatted with line breaks for easier readability
makeFormattedJSONRPCRequestString() Creates a JSON-RPC request string from the parameters passed, formatted with line breaks for easier readability
makeFormattedJSONRPCResponseString() Creates a JSON-RPC response string from the parameters passed, formatted with line breaks for easier readability
makeJSONRPC11ErrorString() Creates a JSON-RPC 1.1 error response string from the parameters passed, without any line breaks
makeJSONRPCErrorString() a generic JSON-RPC error response string from the parameters passed, without any line breaks
makeJSONRPCRequestString() Creates a JSON-RPC request string from the parameters passed, without any line breaks
makeJSONRPCResponseString() Creates a JSON-RPC response string from the parameters passed, without any line breaks

Function and Method Tags

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 "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.

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 "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.

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 CONSTANT except that functions or methods tagged with RET_VALUE_ONLY could throw exceptions.

CONSTANT

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.

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 "deprecated" warning is raised (assuming this warning is enabled).

Release Notes

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 XmlRpcHandler module for enhanced logging
  • source released under the MIT license as well as LGPL 2.1

Version 1.3

  • always include charset=utf-8 in Content-Type in JsonRpcClient; JSON messages are always serialized with UTF-8 encoding

Version 1.2

  • fixed serialization/deserialization/escaping regarding control characters

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)

Version 1.0

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