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

NimYAML

Introduction

NimYAML is a pure YAML implementation for Nim. It is able to read from and write to YAML character streams, and to serialize from and construct to native Nim types. It exclusively supports YAML 1.2.

Source code can be found on GitHub. You can install it with Nimble:

nimble install yaml

NimYAML 2.x

NimYAML 2.0.0 introduced some breaking changes. Read about migrating to the new version here.

Quickstart

Dumping Nim objects as YAML

code.nim out.yaml 
import yaml, streams
type Person = object
  name : string
  age  : int32

var personList = newSeq[Person]()
personList.add(Person(name: "Karl Koch", age: 23))
personList.add(Person(name: "Peter Pan", age: 12))

var s = newFileStream("out.yaml", fmWrite)
Dumper().dump(personList, s)
s.close()
 
- name: Karl Koch
  age: 23
- name: Peter Pan
  age: 12

Loading Nim objects from YAML

code.nim in.yaml 
import yaml, streams
type Person = object
  name : string
  age  : int32

var personList: seq[Person]
var s = newFileStream("in.yaml")
load(s, personList)
s.close()
 
%YAML 1.2
---
- { name: Karl Koch, age: 23 }
- { name: Peter Pan, age: 12 }

Customizing output style

code.nim out.yaml 
import yaml, streams
type Person = object
  name: string
  age: int32

var personList = newSeq[Person]()
personList.add(Person(name: "Karl Koch", age: 23))
personList.add(Person(name: "Peter Pan", age: 12))

var s = newFileStream("out.yaml", fmWrite)
var dumper = canonicalDumper()
dumper.serialization.handles = initNimYamlTagHandle()
dumper.presentation.indentationStep = 3
dumper.presentation.newlines = nlLF
dumper.presentation.outputVersion = ov1_1
dumper.dump(personList, s)
s.close()
 
%YAML 1.1
%TAG !n! tag:nimyaml.org,2016:
--- !n!system:seq(tag:nimyaml.org;2016:custom:Person)
[
   !n!custom:Person {
      ?  !n!field "name"
      :  !!str "Karl Koch",
      ?  !n!field "age"
      :  !n!system:int32 "23"
   },
   !n!custom:Person {
      ?  !n!field "name"
      :  !!str "Peter Pan",
      ?  !n!field "age"
      :  !n!system:int32 "12"
   }
]

Dumping reference types and cyclic structures

code.nim out.yaml 
import yaml, streams
type
  Node = ref NodeObj
  NodeObj = object
    name: string
    left, right: Node

var node1, node2, node3: Node
new(node1); new(node2); new(node3)
node1.name = "Node 1"
node2.name = "Node 2"
node3.name = "Node 3"
node1.left = node2
node1.right = node3
node2.right = node3
node3.left = node1

var s = newFileStream("out.yaml", fmWrite)
Dumper().dump(node1, s)
s.close()
 
--- &a
name: Node 1
left:
  name: Node 2
  left: !!null ~
  right: &b
    name: Node 3
    left: *a
    right: !!null ~
right: *b

Loading reference types and cyclic structures

code.nim in.yaml 
import yaml, streams
type
  Node = ref NodeObj
  NodeObj = object
    name: string
    left, right: Node

var node1: Node

var s = newFileStream("in.yaml")
load(s, node1)
s.close()
 
%YAML 1.2
%TAG !n! tag:nimyaml.org,2016:
--- !n!custom:NodeObj &a
name: Node 1
left:
  name: Node 2
  left: ~
  right: &b
    name: Node 3
    left: *a
    right: ~
right: *b

Defining a custom tag uri for a type

code.nim out.yaml 
import yaml, streams
type Mob = object
  level, experience: int32
  drops: seq[string]

setTag(Mob, Tag("!Mob"))
setTag(seq[string], Tag("!Drops"))

var mob = Mob(level: 42, experience: 1800, drops:
    @["Sword of Mob Slaying"])
var s = newFileStream("out.yaml", fmWrite)
var dumper = Dumper()
dumper.serialization.tagStyle = tsAll
dumper.serialization.handles = initNimYamlTagHandle()
dumper.dump(mob, s)
s.close()
 
%TAG !n! tag:nimyaml.org,2016:
--- !Mob
!n!field level: !n!system:int32 42
!n!field experience: !n!system:int32 1800
!n!field drops: !Drops [!!str Sword of Mob Slaying]

Dumping Nim objects as JSON

code.nim out.yaml 
import yaml, streams
type Person = object
  name : string
  age  : int32

var personList = newSeq[Person]()
personList.add(Person(name: "Karl Koch", age: 23))
personList.add(Person(name: "Peter Pan", age: 12))

var s = newFileStream("out.yaml", fmWrite)
jsonDumper().dump(personList, s)
s.close()
 
[
  {
    "name": "Karl Koch",
    "age": 23
  },
  {
    "name": "Peter Pan",
    "age": 12
  }
]

Loading Nim objects from JSON

code.nim in.yaml 
import yaml, streams
type Person = object
  name : string
  age  : int32

var personList: seq[Person]

var s = newFileStream("in.yaml")
load(s, personList)
s.close()
 
[
  {
    "name": "Karl Koch",
    "age": 23
  },
  {
    "name": "Peter Pan",
    "age": 12
  }
]

Processing a Sequence of Heterogeneous Items

… With variant objects


.. raw:: html
  <table class="quickstart-example"><thead><tr>
    <th>code.nim</th>
    <th>in.yaml</th>
  </th></tr></thead><tbody><tr><td>

.. code:: nim
   :file: snippets/quickstart/08/00/00-code.nim

.. raw:: html
  </td>
  <td>

.. code:: yaml
   :file: snippets/quickstart/08/00/01-in.yaml

.. raw:: html
  </td></tr></tbody></table>

… With the Sequential API

code.nim in.yaml 
import yaml, yaml/data, yaml/parser, yaml/hints, streams
type Person = object
  name: string

setTag(Person, nimTag("demo:Person"), yTagPerson)

var
  s = newFileStream("in.yaml", fmRead)
  yamlParser = initYamlParser()
  events = yamlParser.parse(s)
  context = initConstructionContext(events)

assert events.next().kind == yamlStartStream
assert events.next().kind == yamlStartDoc
assert events.next().kind == yamlStartSeq
var nextEvent = events.peek()
while nextEvent.kind != yamlEndSeq:
  var curTag = nextEvent.properties().tag
  if curTag == yTagQuestionMark:
    # we only support implicitly tagged scalars
    assert nextEvent.kind == yamlScalar
    case guessType(nextEvent.scalarContent)
    of yTypeInteger: curTag = yTagInteger
    of yTypeBoolTrue, yTypeBoolFalse:
      curTag = yTagBoolean
    of yTypeUnknown: curTag = yTagString
    else: assert false, "Type not supported!"
  elif curTag == yTagExclamationMark:
    curTag = yTagString
  case curTag
  of yTagString:
    var s: string
    context.constructChild(s)
    echo "got string: ", s
  of yTagInteger:
    var i: int32
    context.constructChild(i)
    echo "got integer: ", i
  of yTagBoolean:
    var b: bool
    context.constructChild(b)
    echo "got boolean: ", b
  of yTagPerson:
    var p: Person
    context.constructChild(p)
    echo "got Person with name: ", p.name
  else: assert false, "unsupported tag: " & $curTag
  nextEvent = events.peek()
assert events.next().kind == yamlEndSeq
assert events.next().kind == yamlEndDoc
assert events.next().kind == yamlEndStream
s.close()
 
%YAML 1.2
%TAG !n! tag:nimyaml.org,2016:
--- !!seq
- this is a string
- 42
- false
- !!str 23
- !n!demo:Person {name: Trillian}

Made with Nim.