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

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 nimyaml

Quickstart

Dumping Nim objects as YAML

code.nim out.yaml
import yaml
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)
dump(personList, s)
s.close()
 
%YAML 1.2
--- !nim:system:seq(nim:custom:Person)
-
  name: Karl Koch
  age: 23
-
  name: Peter Pan
  age: 12

Loading Nim objects from YAML

code.nim in.yaml
import yaml
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
type Person = object
  name: string
  age: int32

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

var s = newFileStream("out.yaml")
dump(personList, s, options = defineOptions(
    style = psCanonical,
    indentationStep = 3,
    newlines = nlLF,
    outputVersion = ov1_1))
s.close()
%YAML 1.1
--- !nim:system:seq(nim:custom:Person)
[
   !nim:custom:Person {
      ? !!str "name"
      : !!str "Karl Koch",
      ? !!str "age"
      : !nim:system:int32 "23"
   },
   !nim:custom:Person {
      ? !!str "name"
      : !!str "Peter Pan",
      ? !!str "age"
      : !nim:system:int32 "12"
   }
]

Dumping reference types and cyclic structures

code.nim out.yaml
import yaml
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)
dump(node1, s)
s.close()
%YAML 1.2
--- !nim:custom:NodeObj &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
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
--- !nim: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
type Mob = object
  level, experience: int32
  drops: seq[string]

setTagUriForType(Mob, "!Mob")
setTagUriForType(seq[string], "!Drops")

var mob = Mob(level: 42, experience: 1800, drops:
    @["Sword of Mob Slaying"])
var s = newFileStream("out.yaml", fmWrite)
dump(mob, s,
     options = defineOptions(tagStyle = tsAll))
s.close()
YAML 1.2
--- !Mob
!nim:field level: !nim:system:int32 42
!nim:field experience: !nim:system:int32 1800
!nim:field drops: !Drops [!!str Sword of Mob Slaying]

Dumping Nim objects as JSON

code.nim out.yaml
import yaml
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)
dump(personList, s,
     options = defineOptions(style = psJson))
s.close()
 
[
  {
    "name": "Karl Koch",
    "age": 23
  },
  {
    "name": "Peter Pan",
    "age": 12
  }
]

Loading Nim objects from JSON

code.nim in.yaml
import yaml
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

code.nim in.yaml
import yaml
type Person = object
  name: string

setTagUriForType(Person, "!nim:demo:Person",
                 yTagPerson)

var
  s = newFileStream("in.yaml", fmRead)
  context = newConstructionContext()
  parser = newYamlParser(serializationTagLibrary)
  events = parser.parse(s)

assert events.next().kind == yamlStartDoc
assert events.next().kind == yamlStartSeq
var nextEvent = events.peek()
while nextEvent.kind != yamlEndSeq:
  var curTag = nextEvent.tag()
  if curTag == yTagQuestionMark:
    # we only support implicitly tagged scalar events
    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
    events.constructChild(context, s)
    echo "got string: ", s
  of yTagInteger:
    var i: int32
    events.constructChild(context, i)
    echo "got integer: ", i
  of yTagBoolean:
    var b: bool
    events.constructChild(context, b)
    echo "got boolean: ", b
  else:
    # non-standard tag ids are not available
    # at compile time
    if curTag == yTagPerson:
      var p: Person
      events.constructChild(context, 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.finished()
s.close()
 
%YAML 1.2
--- !!seq
- this is a string
- 42
- false
- !!str 23
- !nim:demo:Person {name: Trillian}

Made with Nim. Generated: 2016-03-25 23:12:19 UTC