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

Module yaml.annotations

    Dark Mode
Search:
Group by:

This module provides annotations for object fields that customize (de)serialization behavior of those fields.

Templates

template defaultVal(value: typed) {...}{.pragma.}

This annotation can be put on an object field. During deserialization, if no value for this field is given, the value parameter of this annotation is used as value.

Example usage:

type MyObject = object
  a {.defaultVal: "foo".}: string
  c {.defaultVal: (1,2).}: tuple[x, y: int]
template sparse() {...}{.pragma.}

This annotation can be put on an object type. During deserialization, the input may omit any field that has an Option[T] type (for any concrete T) and that field will be treated as if it had the annotation {.defaultVal: none(T).}.

Example usage:

type MyObject {.sparse.} = object
  a: Option[string]
  b: Option[int]
template transient() {...}{.pragma.}

This annotation can be put on an object field. Any object field carrying this annotation will not be serialized to YAML and cannot be given a value when deserializing. Giving a value for this field during deserialization is an error.

Example usage:

type MyObject = object
  a {.transient.}, b: string
  c {.transient.}: int
template ignore(keys: openArray[string]) {...}{.pragma.}

This annotation can be put on an object type. All keys with the given names in the input YAML mapping will be ignored when deserializing a value of this type. This can be used to ignore parts of the YAML structure.

You may use it with an empty list ({.ignore: [].}) to ignore all unknown keys.

Example usage:

type MyObject {.ignore: ["c"].} = object
  a, b: string
template implicit() {...}{.pragma.}

This annotation declares 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.

Example usage:

ContainerKind = enum
  ckString, ckInt

type MyObject {.implicit.} = object
  case kind: ContainerKind
  of ckString:
    strVal: string
  of ckInt:
    intVal: int