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

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 }

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" } ]

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

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

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 setTagUriForType(Mob, "!Mob") var mob = Mob(level: 42, experience: 1800) var s = newFileStream("out.yaml", fmWrite) dump(mob, s) s.close()	%YAML 1.2 --- !Mob level: 42 experience: 1800

code.nim

out.yaml

import yaml
type Mob = object
    level, experience: int32

setTagUriForType(Mob, "!Mob")

var mob = Mob(level: 42, experience: 1800)
var s = newFileStream("out.yaml", fmWrite)
dump(mob, s)
s.close()

%YAML 1.2
--- !Mob
level: 42
experience: 1800

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 } ]

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 } ]

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
  }
]