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.

Quickstart

Data used in quickstart code may not be accurate and is solely used to showcase NimYAML's features.

import yaml
type
    GenderKind* = enum
        male, female, other
    
    Person* = object
        name*: string
        gender*: GenderKind
        age*: int32
        spouse*: ref Person
        offspring*: seq[ref Person]

let input = newStringStream("""
%YAML 1.2
---
- &a
  name: Luke Skywalker
  gender: male
  age: 19
  spouse: ~
  offspring: []
- &b
  name: Han Solo
  gender: male
  age: 35
  spouse: &c
    name: Leia Organa
    gender: female
    age: 19
    spouse: *b
    offspring: []
  offspring: []
- *c
-
  name: Anakin Skywalker
  gender: male
  age: 42
  spouse: ~
  offspring: [*a, *c]
""")
var persons: seq[ref Person]
load(input, persons)
for person in persons:
  echo person.name, "\nage ", person.age
  if person.spouse != nil:
    echo "spouse: ", person.spouse.name
  for child in person.offspring:
    case child.gender
    of male: echo "son: ", child.name
    of female: echo "daughter: ", child.name
    of other: echo "child: ", child.name
  echo "------------------------"
dump(persons, newFileStream(stdout))

API Overview

NimYAML advocates parsing YAML input into native Nim types. Basic library types like integers, floats and strings, as well as all tuples, enums and objects without private fields are supported out-of-the-box. Reference types are also supported, and NimYAML is able to detect if a reference occurs more than once and will serialize it accordingly. This means that NimYAML is able to dump and load potentially cyclic objects.

While loading into and dumping from native Nim types is the preferred way to use NimYAML, it also gives you complete control over each processing step, so that you can for example only use the parser and process its event stream yourself. The following diagram gives an overview of NimYAML's features based on the YAML processing pipeline. The items and terminology YAML defines is shown in italic, NimYAML's implementation name is shown in bold.

Intermediate Representation

The base of all YAML processing with NimYAML is the YamlStream. This is basically an iterator over YamlStreamEvent objects. Every proc that represents a single stage of the loading or dumping process will either take a YamlStream as input or return a YamlStream. Procs that implement the whole process in one step hide the YamlStream from the user. Every proc that returns a YamlStream guarantees that this stream is well-formed according to the YAML specification.

This stream-oriented API can efficiently be used to parse large amounts of data. The drawback is that errors in the input are only discovered while processing the YamlStream. If the YamlStream encounters an exception while producing the next event, it will throw a YamlStreamError which contains the original exception as parent. The caller should know which exceptions are possible as parents of YamlStream because they know the source of the YamlStream they provided.

Loading YAML

For parsing, a YamlParser object is needed. This object stores some state while parsing that may be useful for error reporting to the user. The parse proc implements the YAML processing step of the same name. All syntax errors in the input character stream are processed by parse, which will raise a YamlParserError if it encounters a syntax error.

Transforming a YamlStream to a native YAML object is done via construct. It skips the compose step for efficiency reasons. As Nim is statically typed, you have to know the target type when you write your loading code. This is different from YAML APIs of dynamically typed languages. If you cannot know the type of your YAML input at compile time, you have to manually process the YamlStream to serve your needs.

If you want to load YAML character data directly into a native Nim variable, you can use load.

Dumping YAML

Dumping YAML is straightforward: You transform a variable into a YamlStream with represent and then write that to a stream using present. If you want to execute both steps at once, you can use dump.

The present step allows you to specify how you want the output YAML character stream to be formatted. Amongst other options, it is possible to output pure JSON, but only if the stream does not contain any constructs that cannot be presented in JSON.