JSON

Usage

use JSON;

or

import JSON;

Provides serialization in the JSON format.

Intended for use with IO support for serializers and deserializers.

type jsonWriter = fileWriter(serializerType = jsonSerializer, ?): Type Alias for an IO.fileWriter that uses a jsonSerializer

type jsonReader = fileReader(deserializerType = jsonDeserializer, ?): Type Alias for an IO.fileReader that uses a jsonDeserializer

record jsonSerializer

A JSON format serializer to be used by fileWriter.

Implements the ‘serializeValue’ method which is called by a fileWriter to produce a serialized representation of a value in JSON format.

Warning

This serializer is designed to generate valid JSON; however, no guarantees are made about the exact formatting w.r.t. whitespace, newlines or indentation.

See the IO Serializers technote for more information about serializers in general.

proc ref serializeValue(writer: jsonWriter, const val: ?t) throws

Serialize val with writer.

Numeric values are serialized as though they were written with the format of %i for integers and %er for real numbers. Please refer to the section on Formatted IO for more information.

Booleans are serialized as the literal strings true or false.

string values are serialized by wrapping the string in quotes, and escaping quotes inside the string. bytes values are also wrapped in quotes.

Enums are serialized using the name of the corresponding value. For example with an enum like enum colors {red, green blue}, the value red would be serialized as a string: "red".

The nil value and nilable class variables storing nil will be serialized as the text null.

Classes and records will have their serialize method invoked, passing in writer and this Serializer as arguments. Please see the serializers technote for more.

Classes and records are expected to implement the writeSerializable or serializable interface.

Arguments:

writer – The fileWriter used to write serialized output
val – The value to be serialized

proc startClass(writer: jsonWriter, name: string, size: int) throws

Start serializing a class by writing the character {.

Arguments:

writer – The fileWriter to be used when serializing
name – The name of the class type
size – The number of fields in the class

Returns:

A new AggregateSerializer

proc startRecord(writer: jsonWriter, name: string, size: int) throws

Start serializing a record by writing the character {.

Arguments:

writer – The fileWriter to be used when serializing
name – The name of the class type
size – The number of fields in the class

Returns:

A new AggregateSerializer

record AggregateSerializer

Returned by startClass or startRecord to provide the API for serializing classes or records.

Classes and records are serialized as JSON objects. For example, a class or record with integer fields x and y with values 0 and 5 would be serialized as {"x":0, "y":5}.

proc ref writeField(name: string, const field: ?) throws

Serialize field named name.

Serializes fields in the form "<name>":<field>. Adds a comma before the name if this is not the first field.

proc ref startClass(writer, name: string, size: int) throws

Start serializing a nested class inside the current class. In this format inheritance is not represented and parent fields are printed before child fields. For example, the following classes with values x=5 and y=2:

class Parent {
  var x : int;
}

class Child: Parent {
  var y : int;
}

would be serialized as:

{"x":5, "y":2}

Arguments:

writer – The fileWriter to be used when serializing. Must match the writer used to create current AggregateSerializer
name – The name of the class type
size – The number of fields in the class

Returns:

A new AggregateSerializer

proc endClass() throws: Ends serialization of the current class by writing the character }.

proc endRecord() throws: Ends serialization of the current record by writing the character }.

proc startTuple(writer: jsonWriter, size: int) throws

Start serializing a tuple by writing the character [.

In this format tuples are serialized as JSON lists. For example, the tuple (1, 2, 3) would be serialized as [1, 2, 3].

Arguments:

writer – The fileWriter to be used when serializing
size – The number of elements in the tuple

Returns:

A new ListSerializer

proc startList(writer: jsonWriter, size: int) throws

Start serializing a list by writing the character [.

Arguments:

writer – The fileWriter to be used when serializing
size – The number of elements in the list

Returns:

A new ListSerializer

record ListSerializer

Returned by startList or startTuple to provide the API for serializing JSON lists.

A list will be serialized as a comma-separated series of serialized elements between two square brackets. For example, serializing a list with elements 1, 2, and 3 will produce the text:

[1, 2, 3]

Empty lists will be serialized as [].

proc ref writeElement(const element: ?) throws

Serialize element.

Writes a leading comma before serializing the element if this is not the first element in the list.

proc endList() throws: Ends serialization of the current list by writing the character ].

proc endTuple() throws: Ends serialization of the current tuple by writing the character ].

proc startArray(writer: jsonWriter, size: int) throws

Start serializing an array.

Arguments:

writer – The fileWriter to be used when serializing
size – The number of elements in the array

Returns:

A new ArraySerializer

record ArraySerializer

Returned by startArray to provide the API for serializing arrays.

In this format, a 1D array will be serialized as a JSON list. For example, an array with three values would be serialized as:

[1, 2, 3]

Multidimensional arrays will be serialized as JSON lists of lists:

[
 [0, 1, 2],
 [3, 4, 5],
 [6, 7, 8]
]

The indenting of these multidimensional arrays is not considered stable.

proc ref startDim(size: int) throws: Start serializing a new dimension of size size.

proc ref endDim() throws: End the current dimension.

proc ref writeElement(const element: ?) throws

Serialize element.

Writes a leading comma if this is not the first element in the row.

proc endArray() throws: Ends serialization of the current array.

proc startMap(writer: jsonWriter, size: int) throws

Start serializing a map by writing the character {.

Arguments:

writer – The fileWriter to be used when serializing
size – The number of entries in the map

Returns:

A new MapSerializer

record MapSerializer

Returned by startMap to provide the API for serializing maps.

Maps are serialized as JSON objects. For example, a map of strings to strings would be serialized as:

{
  "east": "west",
  "hello": "goodbye",
  "north": "south",
  "day": "night"
}

The indenting and whitespace of this example is not considered stable.

proc ref writeKey(const key: ?) throws

Serialize key.

Note

JSON itself only supports strings as names in objects. This module supports non-string key types by serializing them as an escaped JSON string containing the serialized key. For a simple integer key, this results in output like "123". For a record key with two integer fields, the output could look like:

"{\"x\":1, \"y\":2}"

Adds a leading comma if this is not the first pair in the map.

proc writeValue(const val: ?) throws: Serialize val, preceded by the character :.

proc endMap() throws: Ends serialization of the current map by writing the character }.

record jsonDeserializer

A JSON format deserializer to be used by fileReader.

See the serializers technote for a general overview of Deserializers and their usage.

Otherwise, please refer to jsonSerializer for a description of the JSON serialization format. Individual methods on this type may clarify behavior specific to deserialization.

Implements the deserializeType and deserializeValue methods which are called by a fileReader to deserialize a serialized representation of a type or value in JSON format.

This deserializer supports reading class and record fields out-of-order by default. I.e., the fields of a JSON object do not need to match the declaration order in a Chapel type definition to be deserialized into that type.

proc ref deserializeType(reader: jsonReader, type readType) : readType throws

Deserialize type readType with reader.

Classes and records will be deserialized using an appropriate initializer, passing in reader and this Deserializer as arguments. If an initializer is unavailable, this method may invoke the class or record’s deserialize method. Please see the serializers technote for more.

Classes and records are expected to implement either the initDeserializable or readDeserializable interfaces (or both). Alternatively, types implementing the entire serializable interface are also accepted.

Arguments:

reader – The fileReader from which types are deserialized
readType – The type to be deserialized

Returns:

A value of type readType.

proc ref deserializeValue(reader: jsonReader, ref val: ?readType) : void throws

Deserialize from reader directly into val.

Like deserializeType, but reads into an initialized value rather than creating a new value. For classes and records, this method will first attempt to invoke a deserialize method. If the deserialize method is unavailable, this method may fall back on invoking a suitable initializer and assigning the resulting value into val.. Please see the serializers technote for more.

Classes and records are expected to implement either the initDeserializable or readDeserializable interfaces (or both). Alternatively, types implementing the entire serializable interface are also accepted.

Arguments:

reader – The fileReader from which values are deserialized
val – The value into which this Deserializer will deserialize

proc startClass(reader: jsonReader, name: string) throws

Start deserializing a class by reading the character {.

Arguments:

reader – The fileReader to use when deserializing
name – The name of the class type

Returns:

A new AggregateDeserializer

proc startRecord(reader: jsonReader, name: string) throws

Start deserializing a record by reading the character {.

Arguments:

reader – The fileReader to use when deserializing
name – The name of the record type

Returns:

A new AggregateDeserializer

record AggregateDeserializer

Returned by startClass or startRecord to provide the API for deserializing classes or records.

See jsonSerializer.AggregateSerializer for details of the JSON format for classes and records.

proc readField(name: string, type fieldType) : fieldType throws

Deserialize a field named name of type fieldType.

Note

The position of the underlying fileReader is undefined after a call to readField in order to support out-of-order reading.

Returns:: A deserialized value of type fieldType.

proc readField(name: string, ref field) throws: Deserialize a field named name in-place.

Note

The position of the underlying fileReader is undefined after a call to readField in order to support out-of-order reading.

proc ref startClass(reader, name: string)

Start deserializing a nested class inside the current class.

See jsonSerializer.AggregateSerializer.startClass for details on inheritance on the JSON format.

Returns:: A new AggregateDeserializer

proc endClass() throws: End deserialization of the current class by reading the character }.

proc endRecord() throws: End deserialization of the current record by reading the character }.

proc startTuple(reader: jsonReader) throws

Start deserializing a tuple by reading the character [.

Arguments:: reader – The fileReader to use when deserializing
Returns:: A new ListDeserializer

proc startList(reader: jsonReader) throws

Start deserializing a list by reading the character [.

Arguments:: reader – The fileReader to use when deserializing
Returns:: A new ListDeserializer

record ListDeserializer

Returned by startTuple or startList to provide the API for deserializing tuples or lists.

See jsonSerializer.ListSerializer for details of the JSON format for tuples and lists.

proc ref readElement(type eltType) : eltType throws

Deserialize and return an element.

Returns:: A deserialized value of type eltType.

proc ref readElement(ref element) throws: Deserialize element in-place.

proc endList() throws: End deserialization of the current list by reading the character ].

proc endTuple() throws: End deserialization of the current tuple by reading the character ].

proc hasMore() : bool throws

Returns:: Returns true if there are more elements to read.

proc startArray(reader: jsonReader) throws

Start deserializing an array.

Arguments:: reader – The fileReader to use when deserializing
Returns:: A new ArrayDeserializer

record ArrayDeserializer

Returned by startArray to provide the API for deserializing arrays.

See jsonSerializer.ArraySerializer for details of the JSON format for arrays.

proc ref startDim() throws: Inform the ArrayDeserializer to start deserializing a new dimension.

proc ref endDim() throws: End deserialization of the current dimension.

proc ref readElement(type eltType) : eltType throws

Deserialize and return an element of the array.

Returns:: A deserialized value of type eltType.

proc ref readElement(ref element) throws: Deserialize element in-place as an element of the array.

proc endArray() throws: End deserialization of the current array.

proc startMap(reader: jsonReader) throws

Start deserializing a map by reading the character {.

Arguments:: reader – The fileReader to use when deserializing
Returns:: A new MapDeserializer

record MapDeserializer

Returned by startMap to provide the API for deserializing arrays.

See jsonSerializer.MapSerializer for details of the JSON format for maps.

proc ref readKey(type keyType) : keyType throws: Deserialize and return a key of type keyType.

proc ref readKey(ref key: ?t) throws: Deserialize key in-place as a key of the map.

proc readValue(type valType) : valType throws: Deserialize and return a value of type valType.

proc readValue(ref value) throws: Deserialize value in-place as a value of the map.

proc endMap() throws: End deserialization of the current map by reading the character }.

proc hasMore() : bool throws

Returns:: Returns true if there are more elements to read.

Warning

Behavior of ‘hasMore’ is undefined when called between readKey and readValue.

proc fromJson(jsonString: string, type loadAs) : loadAs throws

Warning

fromJson is unstable

Given a JSON string, use the jsonDeserializer to deserialize it into a value of type loadAs. The type must support deserialization using the readDeserializable interface.

Arguments:

jsonString – The JSON string to parse into a Chapel value
loadAs – The type to deserialize the JSON string into

Returns:

A value of type loadAs.

Warning

Errors thrown from this function can only be caught if loadAs is a default-initializable type.

proc toJson(arg) : string throws

Warning

toJson is unstable

Given a Chapel value, serialize it into a JSON string using the jsonSerializer. The type must support serialization using the writeSerializable interface.

Arguments:: arg – The value to serialize into a JSON string
Returns:: A JSON string representing the Chapel value