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

Module yaml.serialization

Search:
Group by:

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, parseutils, parser, taglib, presenter, stream, private/internal, hints

Types

SerializationContext = ref object
  when not false:
      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
  when not false:
      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: DefiniteUIntTypes](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 constructObjectDefault[O: object | tuple](s: var YamlStream;
    c: ConstructionContext; result: var O) {.
raises: [YamlConstructionError,
    YamlStreamError]
.}
Constructs a Nim object or tuple from a YAML mapping. This is the default implementation for custom objects and tuples and should not be redefined. If you are adding a custom constructObject() implementation, you can use this proc to call the default implementation within it.   Source 
proc constructObject[O: object | tuple](s: var YamlStream; c: ConstructionContext;
                                    result: var O) {.

    raises: [YamlConstructionError, YamlStreamError]
.}
Overridable default implementation for custom object and tuple types   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

Mark an object field as transient, meaning that this object field will not be serialized when an object instance is dumped as YAML, and also that the field is not expected to be given in YAML input that is loaded to an object instance.

Example usage:

type MyObject = object
  a, b: string
  c: int
markAsTransient(MyObject, a)
markAsTransient(MyObject, c)

This does not work if the object has been marked as implicit.

  Source 
macro setDefaultValue(t: typedesc; field: untyped; value: typed): typed

Set the default value of an object field. Fields with default values may be absent in YAML input when loading an instance of the object. If the field is absent in the YAML input, the default value is assigned to the field.

Example usage:

type MyObject = object
  a, b: string
  c: tuple[x, y: int]
setDefaultValue(MyObject, a, "foo")
setDefaultValue(MyObject, c, (1, 2))
  Source 
macro ignoreInputKey(t: typedesc; name: string{lit}): typed

Tell NimYAML that when loading an object of type t, any mapping key named name shall be ignored. Note that this even ignores the key if the value of that key is necessary to construct a value of type t, making deserialization fail.

Example usage:

type MyObject = object
  a, b: string
ignoreInputKey(MyObject, "c")
  Source 
macro ignoreUnknownKeys(t: typedesc): typed

Tell NimYAML that when loading an object or tuple of type t, any mapping key that does not map to an existing field inside the object or tuple shall be ignored.

Example usage:

type MyObject = object
  a, b: string
ignoreUnknownKeys(MyObject)
  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

Made with Nim. Generated: 2017-09-20 19:08:37 UTC