Source Edit

The writer module contains utilities for implementing custom CBOR output, both when implementing writeValue to provide custom serialization of a type and when streaming CBOR directly without first creating Nim objects.

CBOR values are generally written using writeValue. It is also possible to stream the fields 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.

Imports

format, types

Types

CborWriter[Flavor] = object: Source Edit

Procs

proc beginArray(w: var CborWriter; length = -1) {....raises: [IOError], raises: [], gcsafe.}: Start writing a Cbor array. Must be closed with a matching endArray. Source Edit
proc beginBytes(w: var CborWriter; length = -1) {....raises: [IOError], raises: [], gcsafe.}: Source Edit
proc beginObject(w: var CborWriter; length = -1) {....raises: [IOError], raises: [], gcsafe.}: Start writing an object, to be followed by fields.

Must be closed with a matching endObject.

See also writeObject.

Use writeField to add fields to the object.
Source Edit
proc beginText(w: var CborWriter; length = -1) {....raises: [IOError], raises: [], gcsafe.}: Source Edit
proc endArray(w: var CborWriter; stopCode = true) {....raises: [IOError], raises: [], gcsafe.}: Finish writing a Cbor array started with beginArray. Source Edit
proc endBytes(w: var CborWriter; stopCode = true) {....raises: [IOError], raises: [], gcsafe.}: Source Edit
proc endObject(w: var CborWriter; stopCode = true) {....raises: [IOError], raises: [], gcsafe.}: Finish writing an object started with beginObject. Source Edit
proc endText(w: var CborWriter; stopCode = true) {....raises: [IOError], raises: [], gcsafe.}: Source Edit
func init(W: type CborWriter; stream: OutputStream): W:type {....raises: [], gcsafe.}: Initialize a new CborWriter with the given output stream.

The writer generally does not need closing or flushing, which instead is managed by the stream itself.
Source Edit
proc toCbor(v: auto; Flavor = DefaultFlavor): seq[byte] {....raises: [], gcsafe.}: Convert a value to its Cbor byte string representation. Source Edit
proc write(w: var CborWriter; val: bool) {....raises: [IOError], raises: [], gcsafe.}: Source Edit
proc write(w: var CborWriter; val: CborBytes) {....raises: [IOError], raises: [], gcsafe.}: Source Edit
proc write(w: var CborWriter; val: CborSimpleValue) {....raises: [IOError], raises: [], gcsafe.}: Source Edit
proc write(w: var CborWriter; val: CborTag) {....raises: [IOError], raises: [], gcsafe.}: Source Edit
proc write(w: var CborWriter; val: CborVoid) {....raises: [IOError], raises: [], gcsafe.}: Source Edit
proc write(w: var CborWriter; val: cstring) {....raises: [IOError], raises: [], gcsafe.}: Source Edit
proc write(w: var CborWriter; val: openArray[char]) {....raises: [IOError], raises: [], gcsafe.}: Source Edit
proc write(w: var CborWriter; val: seq[byte]) {....raises: [IOError], raises: [], gcsafe.}: Source Edit
proc write(w: var CborWriter; value: CborNumber) {....raises: [IOError], raises: [], gcsafe.}: Source Edit
proc write(w: var CborWriter; value: CborObjectType) {....raises: [IOError], raises: [], gcsafe.}: Source Edit
proc write(w: var CborWriter; value: CborValue) {....raises: [IOError], raises: [], gcsafe.}: Source Edit
proc write[T: distinct](w: var CborWriter; val: T) {....raises: [IOError], raises: [], gcsafe.}: Source Edit
proc write[T: object](w: var CborWriter; value: T) {....raises: [IOError], raises: [], gcsafe.}: Source Edit
proc write[T: range](w: var CborWriter; val: T) {....raises: [IOError], raises: [], gcsafe.}: Source Edit
proc write[T: SomeFloat](w: var CborWriter; val: T) {....raises: [IOError], raises: [], gcsafe.}: Source Edit
proc write[T: SomeInteger](w: var CborWriter; val: T) {....raises: [IOError], raises: [], gcsafe.}: Source Edit
proc write[T: tuple](w: var CborWriter; value: T) {....raises: [IOError], raises: [], gcsafe.}: Source Edit
proc write[T](w: var CborWriter; val: ref T) {....raises: [IOError], raises: [], gcsafe.}: Source Edit
proc write[T](w: var CborWriter; values: openArray[T]) {....raises: [IOError], raises: [], gcsafe.}: Write a collection as a Cbor array. Source Edit
proc writeByte(w: var CborWriter; x: byte) {....raises: [IOError], raises: [], gcsafe.}: Source Edit
proc writeChar(w: var CborWriter; x: char) {....raises: [IOError], raises: [], gcsafe.}: Source Edit
proc writeField[V: not void](w: var CborWriter; name: string; value: V) {. ...raises: [IOError], raises: [], gcsafe.}: Write a field of an object, i.e., the name followed by the value.

Optional fields may get omitted depending on the Flavor.
Source Edit
proc writeIterable(w: var CborWriter; collection: auto) {....raises: [IOError], raises: [], gcsafe.}: Write each element of a collection as a Cbor array. Source Edit
proc writeName(w: var CborWriter; name: string) {....raises: [IOError], raises: [], gcsafe.}: Write the name part of the field of an object, to be followed by the value. Source Edit
proc writeValue(w: var CborWriter; value: CborNumber) {....raises: [IOError], raises: [], gcsafe.}: Source Edit

Templates

template configureCborSerialization(Flavor: type; T: type[enum]; enumRep: static[EnumRepresentation]) {..}: Configure Cbor serialization for an enum type and flavor with a specific representation. Source Edit
template configureCborSerialization(T: type[enum]; enumRep: static[EnumRepresentation]) {..}: Configure Cbor serialization for an enum type with a specific representation. Source Edit
template PreferredOutputType(T`gensym0: type Cbor): type {..}: 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 CborWriter; streamVar: untyped; body: untyped) {..}: Write an element giving direct access to the underlying stream - each separate Cbor 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 write(w: var CborWriter; value: enum) {..}: Write an enum value as Cbor according to the flavor's enum representation. Source Edit
template writeArray[T: void](w: var CborWriter; body: T) {..}: Write a Cbor array using a code block for its elements. Source Edit
template writeBytes(w: var CborWriter; body: untyped) {..}: Source Edit
template writeBytes(w: var CborWriter; length: int; body: untyped) {..}: Write a Cbor bytes; use writeByte to write the bytes. Source Edit
template writeField[T: void](w: var CborWriter; name: string; body: T) {..}: Write a 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 CborWriter; body: T) {..}: Write a Cbor object using a code block for its fields. Source Edit
template writeObjectField[FieldType, ObjectType](w: var CborWriter; obj: ObjectType; fieldName: static string; field: FieldType) {..}: Write a field of an object. Source Edit
template Writer(T`gensym0: type Cbor; F`gensym0: distinct type = DefaultFlavor): type {..}: Source Edit
template writeRecordValue(w: var CborWriter; value: object) {..}: This exists for nim-serialization integration Source Edit
template WriterType(T`gensym0: type Cbor; F`gensym0: distinct type = DefaultFlavor): type {..}: Source Edit
template writeText(w: var CborWriter; body: untyped) {..}: Source Edit
template writeText(w: var CborWriter; length: int; body: untyped) {..}: Write a Cbor text; use writeChar to write the characters. Source Edit
template writeValue[U: Writer(Cbor); W: array](w`gensym45: var U; value`gensym45: W) {..}: Source Edit
template writeValue[U: Writer(Cbor); W: bool](w`gensym10: var U; value`gensym10: W) {..}: Source Edit
template writeValue[U: Writer(Cbor); W: CborBytes](w`gensym99: var U; value`gensym99: W) {..}: Source Edit
template writeValue[U: Writer(Cbor); W: CborNumber](w`gensym71: var U; value`gensym71: W) {..}: Source Edit
template writeValue[U: Writer(Cbor); W: CborSimpleValue](w`gensym94: var U; value`gensym94: W) {..}: Source Edit
template writeValue[U: Writer(Cbor); W: CborTag](w`gensym76: var U; value`gensym76: W) {..}: Source Edit
template writeValue[U: Writer(Cbor); W: CborValueRef](w`gensym86: var U; value`gensym86: W) {..}: Source Edit
template writeValue[U: Writer(Cbor); W: CborVoid](w`gensym81: var U; value`gensym81: W) {..}: Source Edit
template writeValue[U: Writer(Cbor); W: cstring](w`gensym50: var U; value`gensym50: W) {..}: Source Edit
template writeValue[U: Writer(Cbor); W: distinct](w`gensym65: var U; value`gensym65: W) {..}: Source Edit
template writeValue[U: Writer(Cbor); W: enum](w`gensym25: var U; value`gensym25: W) {..}: Source Edit
template writeValue[U: Writer(Cbor); W: object](w`gensym105: var U; value`gensym105: W) {..}: Source Edit
template writeValue[U: Writer(Cbor); W: openArray](w`gensym55: var U; value`gensym55: W) {..}: Source Edit
template writeValue[U: Writer(Cbor); W: ptr](w`gensym20: var U; value`gensym20: W) {..}: Source Edit
template writeValue[U: Writer(Cbor); W: range](w`gensym60: var U; value`gensym60: W) {..}: Source Edit
template writeValue[U: Writer(Cbor); W: ref](w`gensym15: var U; value`gensym15: W) {..}: Source Edit
template writeValue[U: Writer(Cbor); W: seq](w`gensym40: var U; value`gensym40: W) {..}: Source Edit
template writeValue[U: Writer(Cbor); W: SomeFloat](w`gensym35: var U; value`gensym35: W) {..}: Source Edit
template writeValue[U: Writer(Cbor); W: SomeInteger](w`gensym30: var U; value`gensym30: W) {..}: Source Edit
template writeValue[U: Writer(Cbor); W: string](w`gensym5: var U; value`gensym5: W) {..}: Source Edit
template writeValue[U: Writer(Cbor); W: TT`gensym85](w`gensym91: var U; value`gensym91: W) {..}: Source Edit
template writeValue[U: Writer(Cbor); W: tuple](w`gensym110: var U; value`gensym110: W) {..}: Source Edit

Exports

defaultBuiltinWriter, flavorAllowsUnknownFields, flavorSkipNullFields, defaultReader, defaultPrimitiveWriter, defaultPrimitiveSerialization, defaultObjectWriter, EnumRepresentation, mimeType, Cbor, flavorUsesAutomaticObjectSerialization, flavorEnumRep, flavorOmitsOptionalFields, supports, defaultWriters, flavorRequiresAllFields, flavorEnumRep, defaultObjectReader, defaultReaders, defaultPrimitiveReader, defaultSerialization, createCborFlavor, defaultObjectSerialization, flavorEnumRep, defaultBuiltinSerialization, defaultBuiltinReader, defaultSerialization, defaultWriter, isUndefined, isTrue, CborNumber, CborMajor, cborFalse, toInt, ==, $, CborError, CborSign, ==, cborMinorLen8, cborMinorLen0, defaultCborReaderConf, cborMinorLen1, contains, cborNull, cborTrue, cborMinorLens, CborValue, cborMinorIndef, CborTag, cborMinorLen2, CborSimpleValue, ==, toInt, toBytes, add, cborMinorLen4, CborValueKind, cborUndefined, ==, isFalsy, ==, isNullish, isNull, CborReaderConf, isFalse, CborValueRef, toInt, CborBytes, CborVoid, cborBreakStopCode, CborObjectType

cbor_serialization/writer

Imports

Types

Procs

Templates

Exports