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 ajsonSerializer
- type jsonReader = fileReader(deserializerType = jsonDeserializer, ?)¶
Type Alias for an
IO.fileReader
that uses ajsonDeserializer
- 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
withwriter
.Numeric values are serialized as though they were written with the format of
%i
for integers and%er
forreal
numbers. Please refer to the section on Formatted IO for more information.Booleans are serialized as the literal strings
true
orfalse
.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 valuered
would be serialized as a string:"red"
.The
nil
value and nilable class variables storingnil
will be serialized as the textnull
.Classes and records will have their
serialize
method invoked, passing inwriter
and this Serializer as arguments. Please see the serializers technote for more.Classes and records are expected to implement the
writeSerializable
orserializable
interface.- Arguments:
writer – The
fileWriter
used to write serialized outputval – 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 serializingname – 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 serializingname – The name of the class type
size – The number of fields in the class
- Returns:
A new
AggregateSerializer
- record AggregateSerializer¶
Returned by
startClass
orstartRecord
to provide the API for serializing classes or records.Classes and records are serialized as JSON objects. For example, a
class
orrecord
with integer fieldsx
andy
with values0
and5
would be serialized as{"x":0, "y":5}
.- proc ref writeField(name: string, const field: ?) throws¶
Serialize
field
namedname
.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
andy=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 AggregateSerializername – 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 serializingsize – 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 serializingsize – The number of elements in the list
- Returns:
A new
ListSerializer
- record ListSerializer¶
Returned by
startList
orstartTuple
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
, and3
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 serializingsize – 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 serializingsize – 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
anddeserializeValue
methods which are called by afileReader
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
withreader
.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’sdeserialize
method. Please see the serializers technote for more.Classes and records are expected to implement either the
initDeserializable
orreadDeserializable
interfaces (or both). Alternatively, types implementing the entireserializable
interface are also accepted.- Arguments:
reader – The
fileReader
from which types are deserializedreadType – 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 intoval
.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 adeserialize
method. If thedeserialize
method is unavailable, this method may fall back on invoking a suitable initializer and assigning the resulting value intoval
.. Please see the serializers technote for more.Classes and records are expected to implement either the
initDeserializable
orreadDeserializable
interfaces (or both). Alternatively, types implementing the entireserializable
interface are also accepted.- Arguments:
reader – The
fileReader
from which values are deserializedval – 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 deserializingname – 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 deserializingname – The name of the record type
- Returns:
A new
AggregateDeserializer
- record AggregateDeserializer¶
Returned by
startClass
orstartRecord
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 typefieldType
.Note
The position of the underlying
fileReader
is undefined after a call toreadField
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 toreadField
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
orstartList
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
andreadValue
.
- 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 typeloadAs
. The type must support deserialization using thereadDeserializable
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
.
- 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 thewriteSerializable
interface.- Arguments:
arg – The value to serialize into a JSON string
- Returns:
A JSON string representing the Chapel value