This is the root module of NimYAML, a package that provides facilities to generate and interpret YAML character streams. Importing this package will import NimYAML's high level loading & dumping API. Additional APIs must be imported explicitly.

There is no code in this package, all functionality is available via the exported sub-packages. You can import parts of the API by importing certain sub-packages only.

High Level Loading & Dumping

import yaml
# or alternatively:
import yaml / [loading, dumping, annotations, taglib, dom]

Enables you to load YAML data directly into native Nim types and reversely dump native Nim types into YAML documents. This API corresponds to the full Load / Dump process as defined in the YAML specification.

The module module yaml/loading provides the loading: load and loading: loadAs procs which load a single YAML document into a native Nim value.

The module yaml/dumping provides the dumping: Dumper object together with its dumping: dump methods that serialize a given Nim value into YAML.

The module yaml/annotations provides various pragmas that allow you to define how certain aspects of your types are to be serialized, e.g. whether Optional fields may be omitted.

The module yaml/taglib provides facilities that customize the YAML tags that are generated for your types. The primary usage for tags in the context of NimYAML is to define the type of a value in a heterogeneous collection node.

The following additional APIs extend the basic high-level API:

DOM API

Also exported by default, no import necessary

The module yaml/dom enables you to load YAML into dom: YamlNode objects and dump those back into YAML. This gives you a structured view of your YAML stream. The DOM API provides the types and their handling, which can then be used via the loading & dumping API.

You can use YamlNode objects inside other objects to hold subtrees of the input YAML, or you can load the whole YAML into a YamlNode.

YamlNode corresponds to the Representation (Node Graph) stage defined in the YAML specification.

Style API

# needs explicit import to use:
import yaml/style

The module yaml/style lets you define the preferred YAML node style of your objects and fields, giving you a greater control over how your generated YAML looks.

JSON API

# needs explicit import to use:
import yaml/tojson

The module yaml/tojson enables you to load YAML input into the stdlib's JsonNode structure. This can be useful for other libraries that expect JSON input. Mind that the loading & dumping API is able to read & write JSON files (since YAML is a superset of JSON), you don't need the JSON API for that.

Low Level Event Handling

NimYAML exposes lower-level APIs that allow you to access the different steps used for YAML loading & dumping. These APIs have at their core a stream: YamlStream which is an object that supplies a stream of data: Event. This corresponds to the Serialization (Event Tree) stage defined in the YAML specification.

Parsing & Presenting API

# needs explicit import to use:
import yaml / [parser, presenter, stream, data]

Provides parser: parse, a proc that feeds a YamlStream from YAML input, and presenter: present, which consumes a YamlStream and writes out YAML. You can use a stream: BufferYamlStream to supply manually generated events.

Native API

# needs explicit import to use:
import yaml/native

This part of the API takes care of generating Nim values from a YamlStream via construct, and transforming them back into a YamlStream via represent. This complements the Event API.

Typically, you'd only access this API when defining custom constructors and representers.

Hints API

# needs explicit import to use:
import yaml/hints

Provides type guessing, i.e. figuring out which type would be appropriate for a certain YAML scalar.

Imports

annotations, loading, dumping, taglib, dom