mirror of https://github.com/status-im/NimYAML.git
85 lines
2.8 KiB
Nim
85 lines
2.8 KiB
Nim
# NimYAML - YAML implementation in Nim
|
|
# (c) Copyright 2016-2020 Felix Krause
|
|
#
|
|
# See the file "copying.txt", included in this
|
|
# distribution, for details about the copyright.
|
|
|
|
## =======================
|
|
## Module yaml/annotations
|
|
## =======================
|
|
##
|
|
## This module provides annotations for object fields that customize
|
|
## (de)serialization behavior of those fields.
|
|
|
|
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:
|
|
##
|
|
## .. code-block::
|
|
## 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).}``. Fields of ``none(T)`` value are omitted
|
|
## during serialization.
|
|
##
|
|
## Example usage:
|
|
##
|
|
## .. code-block::
|
|
## 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:
|
|
##
|
|
## .. code-block::
|
|
## 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:
|
|
##
|
|
## .. code-block::
|
|
## 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:
|
|
##
|
|
## .. code-block::
|
|
## ContainerKind = enum
|
|
## ckString, ckInt
|
|
##
|
|
## type MyObject {.implicit.} = object
|
|
## case kind: ContainerKind
|
|
## of ckString:
|
|
## strVal: string
|
|
## of ckInt:
|
|
## intVal: int
|