Fork me on GitHub
NimYAML Home Testing Ground Docs: Overview Serialization Modules

Module yaml.serialization

This is the most high-level API of NimYAML. It enables you to parse YAML character streams directly into native YAML types and vice versa. It builds on top of the low-level parser and presenter APIs.

It is possible to define custom construction and serialization procs for any type. Please consult the serialization guide on the NimYAML website for more information.

Imports

tables, typetraits, strutils, macros, streams, times, parser, taglib, presenter, stream, ../private/internal, hints

Types

SerializationContext = ref object
  refs*: Table[pointer, AnchorId]
  style: AnchorStyle
  nextAnchorId*: AnchorId
  put*: proc (e: YamlStreamEvent) {.
raises: [], closure
.}
Context information for the process of serializing YAML from Nim values.   Source
ConstructionContext = ref object
  refs*: Table[AnchorId, pointer]
Context information for the process of constructing Nim values from YAML.   Source
YamlConstructionError = object of YamlLoadingError
  
Exception that may be raised when constructing data objects from a YamlStream. The fields line, column and lineContent are only available if the costructing proc also does parsing, because otherwise this information is not available to the costruction proc.   Source

Procs

proc newConstructionContext(): ConstructionContext {.
raises: [], tags: []
.}
  Source
proc newSerializationContext(s: AnchorStyle; putImpl: proc (e: YamlStreamEvent) {.
raises: [], closure
.}): SerializationContext {.
raises: [], tags: []
.}
  Source
proc yamlTag[](T: typedesc[string]): TagId {.
inline, noSideEffect, raises: []
.}
  Source
proc constructObject(s: var YamlStream; c: ConstructionContext; result: var string) {.
raises: [YamlConstructionError, YamlStreamError], tags: [WriteIOEffect, RootEffect]
.}
costructs a string from a YAML scalar   Source
proc representObject(value: string; ts: TagStyle; c: SerializationContext; tag: TagId) {.
raises: [], tags: [RootEffect]
.}
represents a string as YAML scalar   Source
proc constructObject[T: int8 | int16 | int32 | int64](s: var YamlStream;
    c: ConstructionContext; result: var T) {.
raises: [YamlConstructionError, YamlStreamError]
.}
constructs an integer value from a YAML scalar   Source
proc constructObject(s: var YamlStream; c: ConstructionContext; result: var int) {.
raises: [YamlConstructionError, YamlStreamError], inline, tags: [WriteIOEffect, RootEffect]
.}
constructs an integer of architecture-defined length by loading it into int32 and then converting it.   Source
proc representObject[T: int8 | int16 | int32 | int64](value: T; ts: TagStyle;
    c: SerializationContext; tag: TagId) {.
raises: []
.}
represents an integer value as YAML scalar   Source
proc representObject(value: int; tagStyle: TagStyle; c: SerializationContext;
                    tag: TagId) {.
raises: [YamlStreamError], inline, tags: [RootEffect]
.}
represent an integer of architecture-defined length by casting it to int32. on 64-bit systems, this may cause a RangeError.   Source
proc constructObject[T: uint8 | uint16 | uint32 | uint64](s: var YamlStream;
    c: ConstructionContext; result: var T) {.
raises: [YamlConstructionError, YamlStreamError]
.}
construct an unsigned integer value from a YAML scalar   Source
proc constructObject(s: var YamlStream; c: ConstructionContext; result: var uint) {.
raises: [YamlConstructionError, YamlStreamError], inline, tags: [WriteIOEffect, RootEffect]
.}
represent an unsigned integer of architecture-defined length by loading it into uint32 and then converting it.   Source
proc representObject[T: uint8 | uint16 | uint32 | uint64](value: T; ts: TagStyle;
    c: SerializationContext; tag: TagId) {.
raises: []
.}
represents an unsigned integer value as YAML scalar   Source
proc representObject(value: uint; ts: TagStyle; c: SerializationContext; tag: TagId) {.
raises: [YamlStreamError], inline, tags: [RootEffect]
.}
represent an unsigned integer of architecture-defined length by casting it to int32. on 64-bit systems, this may cause a RangeError.   Source
proc constructObject[T: float | float32 | float64](s: var YamlStream;
    c: ConstructionContext; result: var T) {.
raises: [YamlConstructionError, YamlStreamError]
.}
construct a float value from a YAML scalar   Source
proc representObject[T: float | float32 | float64](value: T; ts: TagStyle;
    c: SerializationContext; tag: TagId) {.
raises: []
.}
represents a float value as YAML scalar   Source
proc yamlTag[](T: typedesc[bool]): TagId {.
inline, raises: []
.}
  Source
proc constructObject(s: var YamlStream; c: ConstructionContext; result: var bool) {.
raises: [YamlConstructionError, YamlStreamError], tags: [WriteIOEffect, RootEffect]
.}
constructs a bool value from a YAML scalar   Source
proc representObject(value: bool; ts: TagStyle; c: SerializationContext; tag: TagId) {.
raises: [], tags: [RootEffect]
.}
represents a bool value as a YAML scalar   Source
proc constructObject(s: var YamlStream; c: ConstructionContext; result: var char) {.
raises: [YamlConstructionError, YamlStreamError], tags: [WriteIOEffect, RootEffect]
.}
constructs a char value from a YAML scalar   Source
proc representObject(value: char; ts: TagStyle; c: SerializationContext; tag: TagId) {.
raises: [], tags: [RootEffect]
.}
represents a char value as YAML scalar   Source
proc yamlTag[](T: typedesc[Time]): TagId {.
inline, raises: []
.}
  Source
proc constructObject(s: var YamlStream; c: ConstructionContext; result: var Time) {.
raises: [YamlConstructionError, YamlStreamError], tags: [WriteIOEffect, RootEffect, TimeEffect]
.}
  Source
proc representObject(value: Time; ts: TagStyle; c: SerializationContext; tag: TagId) {.
raises: [ValueError], tags: [TimeEffect, RootEffect]
.}
  Source
proc yamlTag[I](T: typedesc[seq[I]]): TagId {.
inline, raises: []
.}
  Source
proc yamlTag[I](T: typedesc[set[I]]): TagId {.
inline, raises: []
.}
  Source
proc constructObject[T](s: var YamlStream; c: ConstructionContext; result: var seq[T]) {.
raises: [YamlConstructionError, YamlStreamError]
.}
constructs a Nim seq from a YAML sequence   Source
proc constructObject[T](s: var YamlStream; c: ConstructionContext; result: var set[T]) {.
raises: [YamlConstructionError, YamlStreamError]
.}
constructs a Nim seq from a YAML sequence   Source
proc representObject[T](value: seq[T] | set[T]; ts: TagStyle; c: SerializationContext;
                       tag: TagId)
represents a Nim seq as YAML sequence   Source
proc yamlTag[I, V](T: typedesc[array[I, V]]): TagId {.
inline, raises: []
.}
  Source
proc constructObject[I, T](s: var YamlStream; c: ConstructionContext;
                         result: var array[I, T]) {.
raises: [YamlConstructionError, YamlStreamError]
.}
constructs a Nim array from a YAML sequence   Source
proc representObject[I, T](value: array[I, T]; ts: TagStyle; c: SerializationContext;
                         tag: TagId)
represents a Nim array as YAML sequence   Source
proc yamlTag[K, V](T: typedesc[Table[K, V]]): TagId {.
inline, raises: []
.}
  Source
proc constructObject[K, V](s: var YamlStream; c: ConstructionContext;
                         result: var Table[K, V]) {.
raises: [YamlConstructionError, YamlStreamError]
.}
constructs a Nim Table from a YAML mapping   Source
proc representObject[K, V](value: Table[K, V]; ts: TagStyle; c: SerializationContext;
                         tag: TagId)
represents a Nim Table as YAML mapping   Source
proc yamlTag[K, V](T: typedesc[OrderedTable[K, V]]): TagId {.
inline, raises: []
.}
  Source
proc constructObject[K, V](s: var YamlStream; c: ConstructionContext;
                         result: var OrderedTable[K, V]) {.
raises: [YamlConstructionError, YamlStreamError]
.}
constructs a Nim OrderedTable from a YAML mapping   Source
proc representObject[K, V](value: OrderedTable[K, V]; ts: TagStyle;
                         c: SerializationContext; tag: TagId)
  Source
proc yamlTag[](T: typedesc[object | enum]): TagId {.
inline, raises: []
.}
  Source
proc yamlTag[](T: typedesc[tuple]): TagId {.
inline, raises: []
.}
  Source
proc constructObject[O: object | tuple](s: var YamlStream; c: ConstructionContext;
                                    result: var O) {.
raises: [YamlConstructionError, YamlStreamError]
.}
constructs a Nim object or tuple from a YAML mapping   Source
proc representObject[O: object](value: O; ts: TagStyle; c: SerializationContext;
                              tag: TagId)
represents a Nim object or tuple as YAML mapping   Source
proc representObject[O: tuple](value: O; ts: TagStyle; c: SerializationContext;
                             tag: TagId)
  Source
proc constructObject[O: enum](s: var YamlStream; c: ConstructionContext; result: var O) {.
raises: [YamlConstructionError, YamlStreamError]
.}
constructs a Nim enum from a YAML scalar   Source
proc representObject[O: enum](value: O; ts: TagStyle; c: SerializationContext;
                            tag: TagId) {.
raises: []
.}
represents a Nim enum as YAML scalar   Source
proc yamlTag[O](T: typedesc[ref O]): TagId {.
inline, raises: []
.}
  Source
proc constructChild[T](s: var YamlStream; c: ConstructionContext; result: var T) {.
raises: [YamlConstructionError, YamlStreamError]
.}
Constructs an arbitrary Nim value from a part of a YAML stream. The stream will advance until after the finishing token that was used for constructing the value. The ConstructionContext is needed for potential child objects which may be refs.   Source
proc constructChild(s: var YamlStream; c: ConstructionContext; result: var string) {.
raises: [YamlConstructionError, YamlStreamError], tags: [WriteIOEffect, RootEffect]
.}
Constructs a Nim value that is a string from a part of a YAML stream. This specialization takes care of possible nil strings.   Source
proc constructChild[T](s: var YamlStream; c: ConstructionContext; result: var seq[T]) {.
raises: [YamlConstructionError, YamlStreamError]
.}
Constructs a Nim value that is a string from a part of a YAML stream. This specialization takes care of possible nil seqs.   Source
proc constructChild[O](s: var YamlStream; c: ConstructionContext; result: var ref O) {.
raises: [YamlStreamError]
.}
Constructs an arbitrary Nim value from a part of a YAML stream. The stream will advance until after the finishing token that was used for constructing the value. The object may be constructed from an alias node which will be resolved using the ConstructionContext.   Source
proc representChild(value: string; ts: TagStyle; c: SerializationContext) {.
inline, raises: [], tags: [RootEffect]
.}
Represents a Nim string. Supports nil strings.   Source
proc representChild[T](value: seq[T]; ts: TagStyle; c: SerializationContext)
  Source
proc representChild[O](value: ref O; ts: TagStyle; c: SerializationContext) {.
raises: []
.}
Represents an arbitrary Nim reference value as YAML object. The object may be represented as alias node if it is already present in the SerializationContext.   Source
proc representChild[O](value: O; ts: TagStyle; c: SerializationContext)
Represents an arbitrary Nim object as YAML object.   Source
proc construct[T](s: var YamlStream; target: var T) {.
raises: [YamlStreamError]
.}
Constructs a Nim value from a YAML stream.   Source
proc load[K](input: Stream | string; target: var K) {.
raises: [YamlConstructionError, IOError, YamlParserError]
.}
Loads a Nim value from a YAML character stream.   Source
proc loadMultiDoc[K](input: Stream | string; target: var seq[K])
  Source
proc represent[T](value: T; ts: TagStyle = tsRootOnly; a: AnchorStyle = asTidy): YamlStream
Represents a Nim value as YamlStream   Source
proc dump[K](value: K; target: Stream; tagStyle: TagStyle = tsRootOnly;
            anchorStyle: AnchorStyle = asTidy;
            options: PresentationOptions = defaultPresentationOptions) {.
raises: [YamlPresenterJsonError, YamlPresenterOutputError, YamlStreamError]
.}
Dump a Nim value as YAML character stream.   Source
proc dump[K](value: K; tagStyle: TagStyle = tsRootOnly;
            anchorStyle: AnchorStyle = asTidy;
            options: PresentationOptions = defaultPresentationOptions): string
Dump a Nim value as YAML into a string   Source

Macros

macro markAsTransient[](t: typedesc; field: untyped): typed
  Source
macro setDefaultValue[](t: typedesc; field: untyped; value: typed): typed
  Source
macro ignoreInputKey[](t: typedesc; name: string{lit}): typed
  Source

Templates

template presentTag[](t: typedesc; ts: TagStyle): TagId
Get the TagId that represents the given type in the given style   Source
template constructScalarItem[](s: var YamlStream; i: untyped; t: typedesc;
                              content: untyped)
Helper template for implementing constructObject for types that are constructed from a scalar. i is the identifier that holds the scalar as YamlStreamEvent in the content. Exceptions raised in the content will be automatically catched and wrapped in YamlConstructionError, which will then be raised.   Source
template markAsImplicit[](t: typedesc): typed
Mark a variant object type as implicit. This requires the type to consist of nothing but a case expression and each branch of the case expression containing exactly one field - with the exception that one branch may contain zero fields.   Source