The writer module contains utilities for implementing custom JSON output, both when implementing writeValue to provide custom serialization of a type and when streaming JSON directly without first creating Nim objects.
The API closely follows the JSON grammar.
JSON values are generally written using writeValue. It is also possible to stream the members and elements of objects/arrays using the writeArray/writeObject templates - alternatively, the low-level begin{Array,Object} and end{Array,Object} helpers provide fine-grained writing access.
Finally, streamElement can be used when direct access to the stream is needed, for example to efficiently encode a value without intermediate allocations.
Types
JsonWriter[Flavor] = object hasPrettyOutput*: bool
- Source Edit
Procs
proc beginArray(w: var JsonWriter) {....raises: [IOError], raises: [], gcsafe.}
- Start writing a JSON array. Must be closed with a matching endArray. Source Edit
proc beginObject(w: var JsonWriter) {....raises: [IOError], raises: [], gcsafe.}
-
Start writing an object, to be followed by member fields.
Must be closed with a matching endObject.
See also writeObject.
Use writeMember to add member fields to the object.
Source Edit proc beginObject(w: var JsonWriter; O: type) {....raises: [IOError], raises: [], gcsafe.}
-
Start writing an object with type annotation, to be followed by member fields.
Must be closed with a matching endObject.
Source Edit proc endArray(w: var JsonWriter) {....raises: [IOError], raises: [], gcsafe.}
- Finish writing a JSON array started with beginArray. Source Edit
proc endObject(w: var JsonWriter) {....raises: [IOError], raises: [], gcsafe.}
- Finish writing an object started with beginObject. Source Edit
func init(W: type JsonWriter; stream: OutputStream; pretty = false; typeAnnotations = false): W:type {....raises: [], gcsafe.}
-
Initialize a new JsonWriter with the given output stream. Optionally enables pretty output and type annotations.
The writer generally does not need closing or flushing, which instead is managed by the stream itself.
Source Edit proc writeArray[C: not void](w: var JsonWriter; values: C) {....raises: [IOError], raises: [], gcsafe.}
- Write a collection as a JSON array. Source Edit
proc writeIterable(w: var JsonWriter; collection: auto) {....raises: [IOError], raises: [], gcsafe.}
- Write each element of a collection as a JSON array. Source Edit
proc writeMember[V: not void](w: var JsonWriter; name: string; value: V) {. ...raises: [IOError], raises: [], gcsafe.}
- Write name and value as a JSON member / field of an object. Source Edit
proc writeName(w: var JsonWriter; name: string) {....raises: [IOError], raises: [], gcsafe.}
- Write the name part of the member of an object, to be followed by the value. Source Edit
proc writeRecordValue(w: var JsonWriter; value: object | tuple) {. ...raises: [IOError], raises: [], gcsafe.}
-
Write a record or tuple as a JSON object.
This function exists to satisfy the nim-serialization API - use writeValue to serialize objects when using Jsonwriter.
Source Edit proc writeValue(w: var JsonWriter; value: JsonNumber) {....raises: [IOError], raises: [], gcsafe.}
- Source Edit
proc writeValue(w: var JsonWriter; value: JsonObjectType) {....raises: [IOError], raises: [], gcsafe.}
- Source Edit
proc writeValue(w: var JsonWriter; value: JsonValue) {....raises: [IOError], raises: [], gcsafe.}
- Source Edit
proc writeValue[V: not void](w: var JsonWriter; value: V) {....raises: [IOError], raises: [], gcsafe.}
-
Write value as JSON - this is the main entry point for converting "anything" to JSON.
See also writeMember.
Source Edit
Iterators
iterator stepwiseArrayCreation[C](w: var JsonWriter; collection: C): auto {. ...raises: [IOError], raises: [], gcsafe.}
- Iterate over the members of a collection, expecting each member to be written directly to the stream. Source Edit
Templates
template beginRecord(w: var JsonWriter) {..}
- Alias for beginObject, for record serialization. Source Edit
template beginRecord(w: var JsonWriter; T: type) {..}
- Alias for beginObject with type, for record serialization. Source Edit
template configureJsonSerialization(Flavor: type; T: type[enum]; enumRep: static[EnumRepresentation]) {..}
- Configure JSON serialization for an enum type and flavor with a specific representation. Source Edit
template configureJsonSerialization(T: type[enum]; enumRep: static[EnumRepresentation]) {..}
- Configure JSON serialization for an enum type with a specific representation. Source Edit
template endRecord(w: var JsonWriter) {..}
- Alias for endObject, for record serialization. Source Edit
template PreferredOutputType(T`gensym0: type Json): type {..}
- Source Edit
template serializesAsTextInJson(T: type[enum]) {..}
- Configure an enum type to serialize as text in JSON. Source Edit
template shouldWriteObjectField[FieldType](field: FieldType): bool {..}
- Template to determine if an object field should be written. Called when omitsOptionalField is enabled - the field is omitted if the template returns false. Source Edit
template streamElement(w: var JsonWriter; streamVar: untyped; body: untyped) {..}
-
Write an element giving direct access to the underlying stream - each separate JSON value needs to be written in its own streamElement block.
Within the streamElement block, do not use writeValue and other high-level helpers as these already perform the element tracking done in streamElement.
Source Edit template writeArray[T: void](w: var JsonWriter; body: T) {..}
- Write a JSON array using a code block for its elements. Source Edit
template writeField(w: var JsonWriter; name: string; value: auto) {..}
- Alias for writeMember, for record serialization. Source Edit
template writeFieldName(w: var JsonWriter; name: string) {..}
- Alias for writeName, for record serialization. Source Edit
template writeMember[T: void](w: var JsonWriter; name: string; body: T) {..}
-
Write a member field of an object, i.e., the name followed by the value.
Optional field handling is not performed and must be done manually.
Source Edit template writeObject[T: void](w: var JsonWriter; body: T) {..}
- Write a JSON object using a code block for its fields. Source Edit
template writeObject[T: void](w: var JsonWriter; O: type; body: T) {..}
- Write a JSON object with type annotation using a code block for its fields. Source Edit
template writeObjectField[FieldType, RecordType](w: var JsonWriter; record: RecordType; fieldName: static string; field: FieldType) {..}
- Write a field of a record or tuple as a JSON object member. Source Edit
template WriterType(T`gensym0: type Json; F`gensym0: distinct type = DefaultFlavor): type {..}
- Source Edit
template writeValue(w: var JsonWriter; value: enum) {..}
- Write an enum value as JSON according to the flavor's enum representation. Source Edit
Exports
-
flavorRequiresAllFields, flavorAllowsUnknownFields, flavorSkipNullFields, createJsonFlavor, flavorEnumRep, DummyFlavor, typeClassOrMemberAutoSerialize, generateJsonAutoSerializationAddon, automaticPrimitivesSerialization, typeClassOrMemberAutoSerialize, automaticBuiltinSerialization, EnumRepresentation, flavorEnumRep, automaticBuiltinSerialization, typeAutoSerialize, flavorOmitsOptionalFields, flavorUsesAutomaticObjectSerialization, flavorRequiresAllFields, flavorAllowsUnknownFields, Json, typeAutoSerialize, flavorOmitsOptionalFields, automaticSerialization, automaticSerialization, automaticPrimitivesSerialization, flavorEnumRep, supports, flavorUsesAutomaticObjectSerialization, flavorSkipNullFields, mimeType, JsonValue, JsonSign, isFloat, JsonError, JsonReaderFlag, ==, JsonNumber, JsonString, defaultJsonReaderConf, maxPortableInt, JsonReaderConf, toInt, hasExponent, $, JsonVoid, ==, valueType, JsonReaderFlags, JsonValueRef, defaultJsonReaderFlags, JsonObjectType, JsonValueKind, minPortableInt, JsonString