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

Module yaml/serialization

    Dark Mode
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

data, parser, taglib, presenter, stream, internal, hints, annotations

Types

SerializationContext = ref object
  refs*: Table[pointer, tuple[a: Anchor, referenced: bool]]
  style: AnchorStyle
  nextAnchorId*: string
  put*: proc (e: Event) {...}{.raises: [], closure.}
Context information for the process of serializing YAML from Nim values.
ConstructionContext = ref object
  refs*: Table[Anchor, tuple[tag: Tag, p: pointer]]
Context information for the process of constructing Nim values from YAML.
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.

Procs

proc newConstructionContext(): ConstructionContext {...}{.raises: [], tags: [].}
proc newSerializationContext(s: AnchorStyle;
                             putImpl: proc (e: Event) {...}{.raises: [], closure.}): SerializationContext {...}{.
    raises: [], tags: [].}
proc newYamlConstructionError(s: YamlStream; mark: Mark; msg: string): ref YamlConstructionError {...}{.
    raises: [], tags: [RootEffect].}
proc yamlTag(T: typedesc[string]): Tag {...}{.inline, noSideEffect, raises: [].}
proc constructObject(s: var YamlStream; c: ConstructionContext;
                     result: var string) {...}{.
    raises: [YamlConstructionError, YamlStreamError], tags: [RootEffect].}
costructs a string from a YAML scalar
proc representObject(value: string; ts: TagStyle; c: SerializationContext;
                     tag: Tag) {...}{.raises: [], tags: [RootEffect].}
represents a string as YAML scalar
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
proc constructObject(s: var YamlStream; c: ConstructionContext; result: var int) {...}{.
    raises: [YamlConstructionError, YamlStreamError], inline, tags: [RootEffect].}
constructs an integer of architecture-defined length by loading it into int32 and then converting it.
proc representObject[T: int8 | int16 | int32 | int64](value: T; ts: TagStyle;
    c: SerializationContext; tag: Tag) {...}{.raises: [].}
represents an integer value as YAML scalar
proc representObject(value: int; tagStyle: TagStyle; c: SerializationContext;
                     tag: Tag) {...}{.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 RangeDefect.
proc constructObject[T: DefiniteUIntTypes](s: var YamlStream;
    c: ConstructionContext; result: var T) {...}{.
    raises: [YamlConstructionError, YamlStreamError].}
construct an unsigned integer value from a YAML scalar
proc constructObject(s: var YamlStream; c: ConstructionContext; result: var uint) {...}{.
    raises: [YamlConstructionError, YamlStreamError], inline, tags: [RootEffect].}
represent an unsigned integer of architecture-defined length by loading it into uint32 and then converting it.
proc representObject[T: uint8 | uint16 | uint32 | uint64](value: T;
    ts: TagStyle; c: SerializationContext; tag: Tag) {...}{.raises: [].}
represents an unsigned integer value as YAML scalar
proc representObject(value: uint; ts: TagStyle; c: SerializationContext;
                     tag: Tag) {...}{.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 RangeDefect.
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
proc representObject[T: float | float32 | float64](value: T; ts: TagStyle;
    c: SerializationContext; tag: Tag) {...}{.raises: [].}
represents a float value as YAML scalar
proc yamlTag(T: typedesc[bool]): Tag {...}{.inline, raises: [].}
proc constructObject(s: var YamlStream; c: ConstructionContext; result: var bool) {...}{.
    raises: [YamlConstructionError, YamlStreamError], tags: [RootEffect].}
constructs a bool value from a YAML scalar
proc representObject(value: bool; ts: TagStyle; c: SerializationContext;
                     tag: Tag) {...}{.raises: [], tags: [RootEffect].}
represents a bool value as a YAML scalar
proc constructObject(s: var YamlStream; c: ConstructionContext; result: var char) {...}{.
    raises: [YamlConstructionError, YamlStreamError], tags: [RootEffect].}
constructs a char value from a YAML scalar
proc representObject(value: char; ts: TagStyle; c: SerializationContext;
                     tag: Tag) {...}{.raises: [], tags: [RootEffect].}
represents a char value as YAML scalar
proc yamlTag(T: typedesc[Time]): Tag {...}{.inline, raises: [].}
proc constructObject(s: var YamlStream; c: ConstructionContext; result: var Time) {...}{.
    raises: [YamlConstructionError, YamlStreamError],
    tags: [RootEffect, TimeEffect].}
proc representObject(value: Time; ts: TagStyle; c: SerializationContext;
                     tag: Tag) {...}{.raises: [ValueError], tags: [RootEffect].}
proc yamlTag[I](T: typedesc[seq[I]]): Tag {...}{.inline, raises: [].}
proc yamlTag[I](T: typedesc[set[I]]): Tag {...}{.inline, raises: [].}
proc constructObject[T](s: var YamlStream; c: ConstructionContext;
                        result: var seq[T]) {...}{.
    raises: [YamlConstructionError, YamlStreamError].}
constructs a Nim seq from a YAML sequence
proc constructObject[T](s: var YamlStream; c: ConstructionContext;
                        result: var set[T]) {...}{.
    raises: [YamlConstructionError, YamlStreamError].}
constructs a Nim seq from a YAML sequence
proc representObject[T](value: seq[T] | set[T]; ts: TagStyle;
                        c: SerializationContext; tag: Tag)
represents a Nim seq as YAML sequence
proc yamlTag[I, V](T: typedesc[array[I, V]]): Tag {...}{.inline, raises: [].}
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
proc representObject[I, T](value: array[I, T]; ts: TagStyle;
                           c: SerializationContext; tag: Tag)
represents a Nim array as YAML sequence
proc yamlTag[K, V](T: typedesc[Table[K, V]]): Tag {...}{.inline, raises: [].}
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
proc representObject[K, V](value: Table[K, V]; ts: TagStyle;
                           c: SerializationContext; tag: Tag)
represents a Nim Table as YAML mapping
proc yamlTag[K, V](T: typedesc[OrderedTable[K, V]]): Tag {...}{.inline, raises: [].}
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
proc representObject[K, V](value: OrderedTable[K, V]; ts: TagStyle;
                           c: SerializationContext; tag: Tag)
proc yamlTag(T: typedesc[object | enum]): Tag {...}{.inline, raises: [].}
proc yamlTag(T: typedesc[tuple]): Tag {...}{.inline, raises: [].}
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.
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
proc representObject[O: object](value: O; ts: TagStyle; c: SerializationContext;
                                tag: Tag)
represents a Nim object or tuple as YAML mapping
proc representObject[O: tuple](value: O; ts: TagStyle; c: SerializationContext;
                               tag: Tag)
proc constructObject[O: enum](s: var YamlStream; c: ConstructionContext;
                              result: var O) {...}{.
    raises: [YamlConstructionError, YamlStreamError].}
constructs a Nim enum from a YAML scalar
proc representObject[O: enum](value: O; ts: TagStyle; c: SerializationContext;
                              tag: Tag) {...}{.raises: [].}
represents a Nim enum as YAML scalar
proc yamlTag[O](T: typedesc[ref O]): Tag {...}{.inline, raises: [].}
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.
proc constructChild(s: var YamlStream; c: ConstructionContext;
                    result: var string) {...}{.
    raises: [YamlConstructionError, YamlStreamError], tags: [RootEffect].}
Constructs a Nim value that is a string from a part of a YAML stream. This specialization takes care of possible nil strings.
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.
proc constructChild[T](s: var YamlStream; c: ConstructionContext;
                       result: var Option[T])
constructs an optional value. A value with a !!null tag will be loaded an empty value.
proc constructChild[O](s: var YamlStream; c: ConstructionContext;
                       result: var ref O) {...}{.
    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 object may be constructed from an alias node which will be resolved using the ConstructionContext.
proc representChild(value: string; ts: TagStyle; c: SerializationContext) {...}{.
    inline, raises: [], tags: [RootEffect].}
Represents a Nim string. Supports nil strings.
proc representChild[T](value: seq[T]; ts: TagStyle; c: SerializationContext)
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.
proc representChild[T](value: Option[T]; ts: TagStyle; c: SerializationContext)
represents an optional value. If the value is missing, a !!null scalar will be produced.
proc representChild[O](value: O; ts: TagStyle; c: SerializationContext)
Represents an arbitrary Nim object as YAML object.
proc construct[T](s: var YamlStream; target: var T) {...}{.
    raises: [YamlStreamError, YamlConstructionError].}
Constructs a Nim value from a YAML stream.
proc load[K](input: Stream | string; target: var K) {...}{.
    raises: [YamlConstructionError, IOError, OSError, YamlParserError].}
Loads a Nim value from a YAML character stream.
proc loadAs[K](input: string): K {...}{.raises: [YamlConstructionError, IOError,
    OSError, YamlParserError].}
Loads the given YAML input to a value of the type K and returns it
proc loadMultiDoc[K](input: Stream | string; target: var seq[K])
proc represent[T](value: T; ts: TagStyle = tsRootOnly; a: AnchorStyle = asTidy;
    handles: seq[tuple[handle, uriPrefix: string]] = @[
    ("!n!", nimyamlTagRepositoryPrefix)]): YamlStream
Represents a Nim value as YamlStream
proc dump[K](value: K; target: Stream; tagStyle: TagStyle = tsRootOnly;
             anchorStyle: AnchorStyle = asTidy;
             options: PresentationOptions = defaultPresentationOptions; handles: seq[
    tuple[handle, uriPrefix: string]] = @[("!n!", nimyamlTagRepositoryPrefix)]) {...}{.
    raises: [YamlPresenterJsonError, YamlPresenterOutputError, YamlStreamError].}
Dump a Nim value as YAML character stream. To prevent %TAG directives in the output, give handles = @[].
proc dump[K](value: K; tagStyle: TagStyle = tsRootOnly;
             anchorStyle: AnchorStyle = asTidy;
             options: PresentationOptions = defaultPresentationOptions; handles: seq[
    tuple[handle, uriPrefix: string]] = @[("!n!", nimyamlTagRepositoryPrefix)]): string
Dump a Nim value as YAML into a string. To prevent %TAG directives in the output, give handles = @[].

Templates

template presentTag(t: typedesc; ts: TagStyle): Tag
Get the Tag that represents the given type in the given style
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 Event in the content. Exceptions raised in the content will be automatically caught and wrapped in YamlConstructionError, which will then be raised.

Exports

hash, Tag, startDocEvent, $, yTagExclamationMark, Mark, startMapEvent, yTagBoolean, yTagOrderedMap, endSeqEvent, ==, endMapEvent, scalarEvent, yTagYaml, startSeqEvent, yAnchorNone, yTagSequence, ScalarStyle, startStreamEvent, defineCoreTag, defineTag, Properties, yTagInteger, CollectionStyle, ==, yTagSet, yTagNimField, startMapEvent, yTagValue, yTagString, properties, nimyamlTagRepositoryPrefix, yamlTagRepositoryPrefix, endStreamEvent, yTagMapping, endDocEvent, Event, scalarEvent, $, yTagBinary, hash, startSeqEvent, aliasEvent, yTagFloat, yTagNull, renderAttrs, yTagPairs, yTagQuestionMark, yTagMerge, ==, $, yTagTimestamp, EventKind, collectionStyle, Anchor, newBufferYamlStream, YamlStream, basicInit, BufferYamlStream, put, next, getLastTokenContext, YamlStreamError, peek=, peek, initYamlStream, items, mitems, sparse, transient, implicit, defaultVal, ignore