NimYAML Home Testing Ground Docs: Overview Serialization Modules NimYAML 2.x Source on GitHub

Module yaml/native

Search:
Group by:

This module transforms native Nim values into a stream of YAML events, and vice versa. The procs of this module must be available for name binding when using the loading and dumping APIs. A NimYAML consumer would rarely call this module's procs directly. The main entry points to this API are construct and represent; all other procs are usually called via instantiations of those two procs.

You can extend the procs defined here with own procs to define custom handling for native types. See the documentation on the NimYAML website for more information.

Imports

data, taglib, stream, internal, hints, annotations

Types

AnchorStyle = enum
  asNone, asTidy, asAlways
How ref object should be serialized.
  • asNone: No anchors will be written. Values present at multiple places in the content that is serialized will be duplicated at every occurrence. If the content is cyclic, this will raise a YamlSerializationError.
  • asTidy: Anchors will only be generated for objects that actually occur more than once in the content to be serialized. This is a bit slower and needs more memory than asAlways.
  • asAlways: Achors will be generated for every ref object in the content that is serialized, regardless of whether the object is referenced again afterwards.
ConstructionContext = object
  input*: YamlStream
  refs*: Table[Anchor, tuple[tag: Tag, p: pointer]]
Context information for the process of constructing Nim values from YAML. 
SerializationContext = object
  options*: SerializationOptions
  putImpl*: proc (ctx: var SerializationContext; e: Event) {....raises: [], closure.}
  overridingScalarStyle*: ScalarStyle = ssAny
  overridingCollectionStyle*: CollectionStyle = csAny
Context information for the process of serializing YAML from Nim values. 
SerializationOptions = object
  tagStyle*: TagStyle = tsNone
  anchorStyle*: AnchorStyle = asTidy
  handles*: seq[tuple[handle, uriPrefix: string]]

TagStyle = enum
  tsNone, tsRootOnly, tsAll
Whether object should be serialized with explicit tags.
  • tsNone: No tags will be outputted unless necessary.
  • tsRootOnly: A tag will only be outputted for the root tag and where necessary.
  • tsAll: Tags will be outputted for every object.
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. 
YamlSerializationError = object of ValueError
Exception that may be raised when serializing Nim values into YAML stream events.

Procs

proc construct[T](input: var YamlStream; target: var T) {.
    ...raises: [YamlStreamError, YamlConstructionError].}
Constructs a Nim value from a YAML stream. 
proc constructChild(ctx: var ConstructionContext; result: var string) {.
    ...raises: [YamlConstructionError, YamlStreamError], tags: [RootEffect],
    forbids: [].}
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[I, T](ctx: var ConstructionContext; result: var array[I, T])
proc constructChild[O](ctx: var 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 constructChild[T](ctx: var ConstructionContext; result: var Option[T])
constructs an optional value. A value with a !!null tag will be loaded an empty value. 
proc constructChild[T](ctx: var 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](ctx: var 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 constructionError(s: YamlStream; mark: Mark; msg: string): ref YamlConstructionError {.
    ...raises: [], tags: [RootEffect], forbids: [].}
proc constructObject(ctx: var ConstructionContext; result: var bool) {.
    ...raises: [YamlConstructionError, YamlStreamError], tags: [RootEffect],
    forbids: [].}
constructs a bool value from a YAML scalar 
proc constructObject(ctx: var ConstructionContext; result: var char) {.
    ...raises: [YamlConstructionError, YamlStreamError], tags: [RootEffect],
    forbids: [].}
constructs a char value from a YAML scalar 
proc constructObject(ctx: var ConstructionContext; result: var int) {.
    ...raises: [YamlConstructionError, YamlStreamError], inline,
    ...tags: [RootEffect], forbids: [].}
constructs an integer of architecture-defined length by loading it into int32 and then converting it. 
proc constructObject(ctx: var ConstructionContext; result: var string) {.
    ...raises: [YamlConstructionError, YamlStreamError], tags: [RootEffect],
    forbids: [].}
constructs a string from a YAML scalar 
proc constructObject(ctx: var ConstructionContext; result: var Time) {.
    ...raises: [YamlConstructionError, YamlStreamError],
    tags: [RootEffect, TimeEffect], forbids: [].}
proc constructObject(ctx: var ConstructionContext; result: var uint) {.
    ...raises: [YamlConstructionError, YamlStreamError], inline,
    ...tags: [RootEffect], forbids: [].}
represent an unsigned integer of architecture-defined length by loading it into uint32 and then converting it. 
proc constructObject[I, T](ctx: var ConstructionContext; result: var array[I, T]) {.
    ...raises: [YamlConstructionError, YamlStreamError].}
constructs a Nim array from a YAML sequence 
proc constructObject[K, V](ctx: var ConstructionContext;
                           result: var OrderedTable[K, V]) {.
    ...raises: [YamlConstructionError, YamlStreamError].}
constructs a Nim OrderedTable from a YAML mapping 
proc constructObject[K, V](ctx: var ConstructionContext; result: var Table[K, V]) {.
    ...raises: [YamlConstructionError, YamlStreamError].}
constructs a Nim Table from a YAML mapping 
proc constructObject[O: enum](ctx: var ConstructionContext; result: var O) {.
    ...raises: [YamlConstructionError, YamlStreamError].}
constructs a Nim enum from a YAML scalar 
proc constructObject[O: object | tuple](ctx: var ConstructionContext;
                                        result: var O) {.
    ...raises: [YamlConstructionError, YamlStreamError].}
Overridable default implementation for custom object and tuple types 
proc constructObject[T: DefiniteUIntTypes](ctx: var ConstructionContext;
    result: var T) {....raises: [YamlConstructionError, YamlStreamError].}
construct an unsigned integer value from a YAML scalar 
proc constructObject[T: float | float32 | float64](ctx: var ConstructionContext;
    result: var T) {....raises: [YamlConstructionError, YamlStreamError].}
construct a float value from a YAML scalar 
proc constructObject[T: int8 | int16 | int32 | int64](
    ctx: var ConstructionContext; result: var T) {.
    ...raises: [YamlConstructionError, YamlStreamError].}
constructs an integer value from a YAML scalar 
proc constructObject[T](ctx: var ConstructionContext; result: var seq[T]) {.
    ...raises: [YamlConstructionError, YamlStreamError].}
constructs a Nim seq from a YAML sequence 
proc constructObject[T](ctx: var ConstructionContext; result: var set[T]) {.
    ...raises: [YamlConstructionError, YamlStreamError].}
constructs a Nim seq from a YAML sequence 
proc constructObjectDefault(ctx: var ConstructionContext; result: var RootObj) {.
    ...raises: [], tags: [], forbids: [].}
proc constructObjectDefault[O: object | tuple](ctx: var 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 initConstructionContext(input: YamlStream): ConstructionContext {.
    ...raises: [], tags: [], forbids: [].}
proc initSerializationContext(options: SerializationOptions; putImpl: proc (
    ctx: var SerializationContext; e: Event) {....raises: [], closure.}): SerializationContext {.
    ...raises: [], tags: [], forbids: [].}
proc newYamlConstructionError(s: YamlStream; mark: Mark; msg: string): ref YamlConstructionError {.
    ...raises: [], tags: [RootEffect], forbids: [].}
proc presentTag(ctx: var SerializationContext; t: typedesc): Tag {.inline.}
Get the Tag that represents the given type in the given style 
proc put(ctx: var SerializationContext; e: Event) {....raises: [],
    tags: [RootEffect], forbids: [].}
proc represent[T](value: T;
                  options: SerializationOptions = SerializationOptions()): YamlStream
Represents a Nim value as YamlStream 
proc representChild(ctx: var SerializationContext; value: string) {.inline,
    ...raises: [], tags: [RootEffect], forbids: [].}
Represents a Nim string. Supports nil strings. 
proc representChild[I, T](ctx: var SerializationContext; value: array[I, T]) {.
    ...raises: [YamlSerializationError].}
proc representChild[O](ctx: var SerializationContext; value: O) {.
    ...raises: [YamlSerializationError].}
Represents an arbitrary Nim object as YAML object. 
proc representChild[O](ctx: var SerializationContext; value: ref O) {.
    ...raises: [YamlSerializationError].}
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](ctx: var SerializationContext; value: Option[T]) {.
    ...raises: [YamlSerializationError].}
represents an optional value. If the value is missing, a !!null scalar will be produced. 
proc representChild[T](ctx: var SerializationContext; value: seq[T]) {.
    ...raises: [YamlSerializationError].}
proc representObject(ctx: var SerializationContext; value: bool; tag: Tag) {.
    ...raises: [], tags: [RootEffect], forbids: [].}
represents a bool value as a YAML scalar 
proc representObject(ctx: var SerializationContext; value: char; tag: Tag) {.
    ...raises: [], tags: [RootEffect], forbids: [].}
represents a char value as YAML scalar 
proc representObject(ctx: var SerializationContext; value: int; tag: Tag) {.
    ...raises: [YamlSerializationError], inline, ...tags: [RootEffect], forbids: [].}
represent an integer of architecture-defined length by casting it to int32. on 64-bit systems, this may cause a RangeDefect. 
proc representObject(ctx: var SerializationContext; value: string; tag: Tag) {.
    ...raises: [], tags: [RootEffect], forbids: [].}
represents a string as YAML scalar 
proc representObject(ctx: var SerializationContext; value: Time; tag: Tag) {.
    ...raises: [], tags: [RootEffect], forbids: [].}
proc representObject(ctx: var SerializationContext; value: uint; tag: Tag) {.
    ...raises: [YamlSerializationError], inline, ...tags: [RootEffect], forbids: [].}
represent an unsigned integer of architecture-defined length by casting it to int32. on 64-bit systems, this may cause a RangeDefect. 
proc representObject[I, T](ctx: var SerializationContext; value: array[I, T];
                           tag: Tag) {....raises: [YamlSerializationError].}
represents a Nim array as YAML sequence 
proc representObject[K, V](ctx: var SerializationContext;
                           value: OrderedTable[K, V]; tag: Tag) {.
    ...raises: [YamlSerializationError].}
proc representObject[K, V](ctx: var SerializationContext; value: Table[K, V];
                           tag: Tag) {....raises: [YamlSerializationError].}
represents a Nim Table as YAML mapping 
proc representObject[O: enum](ctx: var SerializationContext; value: O; tag: Tag) {.
    ...raises: [].}
represents a Nim enum as YAML scalar 
proc representObject[O: object](ctx: var SerializationContext; value: O;
                                tag: Tag) {....raises: [YamlSerializationError].}
represents a Nim object or tuple as YAML mapping 
proc representObject[O: tuple](ctx: var SerializationContext; value: O; tag: Tag) {.
    ...raises: [YamlSerializationError].}
proc representObject[T: float | float32 | float64](
    ctx: var SerializationContext; value: T; tag: Tag) {....raises: [].}
represents a float value as YAML scalar 
proc representObject[T: int8 | int16 | int32 | int64](
    ctx: var SerializationContext; value: T; tag: Tag) {....raises: [].}
represents an integer value as YAML scalar 
proc representObject[T: uint8 | uint16 | uint32 | uint64](
    ctx: var SerializationContext; value: T; tag: Tag) {....raises: [].}
represents an unsigned integer value as YAML scalar 
proc representObject[T](ctx: var SerializationContext; value: seq[T] | set[T];
                        tag: Tag) {....raises: [YamlSerializationError].}
represents a Nim seq as YAML sequence 
proc yamlTag(T: typedesc[bool]): Tag {.inline, ...raises: [].}
proc yamlTag(T: typedesc[object | enum]): Tag {.inline, ...raises: [].}
proc yamlTag(T: typedesc[string]): Tag {.inline, noSideEffect, ...raises: [].}
proc yamlTag(T: typedesc[Time]): Tag {.inline, ...raises: [].}
proc yamlTag(T: typedesc[tuple]): Tag {.inline, ...raises: [].}
proc yamlTag[I, V](T: typedesc[array[I, V]]): Tag {.inline, ...raises: [].}
proc yamlTag[I](T: typedesc[seq[I]]): Tag {.inline, ...raises: [].}
proc yamlTag[I](T: typedesc[set[I]]): Tag {.inline, ...raises: [].}
proc yamlTag[K, V](T: typedesc[OrderedTable[K, V]]): Tag {.inline, ...raises: [].}
proc yamlTag[K, V](T: typedesc[Table[K, V]]): Tag {.inline, ...raises: [].}
proc yamlTag[O](T: typedesc[ref O]): Tag {.inline, ...raises: [].}

Templates

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

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

Made with Nim.