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 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 !!str level: !nim:system:int32 42 !!str experience: !nim:system:int32 1800 !!str drops: !Drops [!!str Sword of Mob Slaying]

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
!!str level: !nim:system:int32 42
!!str experience: !nim:system:int32 1800
!!str 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 } ]

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