JSON module¶

This module implements the JSON (JavaScript Object Notation) format, specified by RFC 7159. This is an open standard format commonly used to represent key-value objects.

Note

To use the features of this module, you have to put a special import statement at the begining of your HXM file: use json;

Module functions¶

json.parse(reader)¶

json.parse(reader, options)

json.parse(filename)

json.parse(filename, options)

json.parse(filename, charset)

json.parse(filename, charset, options)

Converts the given file to a Hexaly Modeler value. You can provide the filename to parse or you can directly provide the stream to read, previously opened with io.openRead(). When using a filename, you can also specify the encoding. If no encoding is provided, UTF-8 is assumed.

Several options can be used to customize the behavior of the parser. These options must be specified in a map. The supported options are detailed at the end of this page.

Parameters:

filename (String) – Path to the JSON file to convert.
stream (StreamReader) – Stream previously opened with io.openRead().
charset (Charset) – Encoding used to convert bytes to characters.
options (Map) – Optional parameters to customize the behavior of the parser.

Return type:

Map, String, integer, double or nil

json.deserialize(content)¶

json.deserialize(content, options)

Identical to parse() but the JSON content is taken from a string instead of a file.

Parameters:

content (String) – JSON content to parse.
options (Map) – Optional parameters to customize the behavior of the parser.

Return type:

Map, String, integer, double or nil

json.dump(value, writer)¶

json.dump(value, writer, options)

json.dump(value, filename)

json.dump(value, filename, options)

json.dump(value, filename, charset)

json.dump(value, filename, charset, options)

Writes the JSON representation of a value in a file. The file can be provided as a filename or as a stream writer previously opened with io.openWrite() or io.openAppend(). When using a filename, you can also specify the encoding. If no encoding is provided, UTF-8 is assumed.

Several options can be used to customize the behavior of the writer. These options must be specified in a map. The supported options are detailed at the end of this page.

Parameters:

value – Value to encode. Only boolean, integers, doubles, strings, maps and nil are accepted.
filename (String) – Path to the destination file.
stream (StreamWriter) – Stream previously opened with io.openWrite() or io.openAppend().
charset (Charset) – Encoding used to convert characters to bytes.
options (Map) – Optional parameters to customize the behavior of the writer.

json.serialize(content)¶

json.serialize(content, options)

Identical to dump() but the converted value is returned as a string.

Parameters:

content (String) – JSON content to parse.
options (Map) – Optional parameters to customize the behavior of the parser.

Return type:

Map, String, integer, double or nil

Behavior of the parser¶

Null¶

null is converted to nil in Hexaly Modeler.

Booleans¶

Boolean values (true, false) are simply converted to their Hexaly Modeler equivalent.

Numbers¶

A JSON number with a decimal separator will be converted to a double floating point number in Hexaly Modeler. Otherwise it is converted to a 64-bit integer. Integers too large to fit in 64 bits will throw an exception, except if the option allowOverlongIntegers is activated. In that case, overlong integers are simply converted to doubles. This option is disabled by default.

NaN or Infinity are not officialy supported by JSON, even if they are valid JavaScript values. They can nevertheless be correctly translated to Hexaly Modeler if the respective options allowNaN or allowInfinity are used. These options are disabled by default.

Strings¶

JSON strings are simply converted to Hexaly Modeler strings. Depending on the charset used to parse the file, any valid unicode character can be used in a JSON string. It will be correctly parsed and handled. JSON standard also supports unicode escape sequences in the form of \uXXXX. If an invalid escape sequence is encountered, an error will be thrown. You can also choose to ignore invalid sequences, or replace invalid sequences by toggling the option ignoreInvalidUnicodeEscapeSequences or replaceInvalidUnicodeEscapeSequences.

Arrays and objects¶

JSON objects and JSON arrays are transformed into maps which are the only data structure used in Hexaly Modeler to represent both arrays and key-value sets. Note that unlike JSON, null (and therefore nil) values are not allowed in maps. All keys with a null value will simply be ignored. Array cells with a null value will also be ignored, but the next key will still be incremented by 1. For instance, the JSON array [42, nil, "foobar"] will be converted to {0: 42, 2: "foobar"} and the JSON object { "myKey": 42.4, "key2": null } will be converted to { "myKey": 42.4 }. For more details on maps, consult the Map module.

Options summary¶

Option name	Default value	Description
allowInfinity	false	Allows the special Javascript keyword `Infinity`.
allowNaN	false	Allows the special Javascript keyword `NaN`.
allowTrailingComma	false	Allows trailing commas at the end of a JSON array or a JSON object such as `[12, -4,]`.
allowComments	false	Allows single-line and multi-lines Javascript comments in JSON. When enabled, comments are simply read and discarded.
allowOverlongIntegers	false	JSON does not specify how numbers are converted or represented. This module assumes that without a decimal separator, numbers are integers provided that they fit in 64 bits. If the number is too big, an exception is thrown. Enable this option if you want to convert overlong integers to floating point numbers rather than throwing exceptions.
ignoreInvalidUnicodeEscapeSequences	false	Ignore invalid unicode escape sequences (`\uXXXX`) rather than throwing exceptions.
replaceInvalidUnicodeEscapeSequences	false	Replace invalid unicode escape sequences (`\uXXXX`) by special unicode character U+FFFD rather than throwing exceptions.
internProperties	true	Tells the parser to reuse the same strings for object properties rather than creating new duplicated ones. This option reduces the memory consumption of large JSONs but slightly decreases the parsing speed.
internStrings	false	Same as previous option but applies to all strings.

Behavior of the writer¶

Boolean, strings and numbers are correctly converted to their JSON counterpart except for nan and inf values. The JSON standard does not support non-finite numbers and an exception will be thrown if they are encountered. To change this behavior, use the options allowNaN or allowInfinity.

The behavior is more complex for maps. Depending on the nature of the keys, they are either converted into JSON arrays or JSON objects:

If the map is solely composed of positive integer keys, then it is transformed into a JSON array.
Otherwise, the writer tries to save it as a JSON object.

For arrays¶

If the Hexaly Modeler map has holes (i.e. the integer keys do not start from zero or are not consecutive), the writer fills them with cells set to null. For instance, the map {"hello", 2: -462.3} will be converted to the JSON array ["hello", null, -462.3]. A null cell is therefore inserted in place of the missing key 1.

For objects¶

All other maps (those that do not consist exclusively of positive integer keys) will be written as JSON objects. In this case, the writer expects only strings as keys. If a non-string key is encountered, an exception will be thrown. You can change this behavior and skip non supported keys with the special option skipInvalidKeys. This option is disabled by default and only apply to keys, not values.

Non supported values, always throw an exception.

Options summary¶

Option name	Default value	Description
allowInfinity	false	Allows the special Javascript keyword `Infinity`.
allowNaN	false	Allows the special Javascript keyword `NaN`.
skipInvalidKeys	false	Instructs the writer to ignore keys that are not strings when writing maps.
indent	nil	Enables or not the indentation. If this option is set to nil or false, the writer tries to save the JSON file in its most compact representation, without any line breaks or white spaces. If this option is set to true, the writer will automatically indent the JSON file with 4 spaces. If `indent` is a string, that string is used to indent the document.