NimYAML Home Testing Ground Docs: Overview Serialization Modules NimYAML 2.x Source on GitHub

yaml

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

Exports

transient, ScalarStyle, collection, CollectionStyle, ignore, sparse, implicit, defaultVal, scalar, startMapEvent, YamlStreamError, endMapEvent, hash, constructObject, newBufferYamlStream, defineCoreTag, startStreamEvent, collectionStyle, yamlTag, ==, yTagExclamationMark, peek=, yTagValue, yTagNull, yamlTag, EventKind, hash, representObject, YamlStream, constructChild, startMapEvent, startSeqEvent, constructChild, yTagInteger, constructObject, constructionError, yTagSet, loadAs, representChild, nimyamlTagRepositoryPrefix, endDocEvent, yTagMapping, implicit, ScalarStyle, constructObject, ==, $, presentTag, CollectionStyle, YamlConstructionError, $, SerializationOptions, yamlTag, constructObject, Anchor, representChild, Tag, newYamlConstructionError, defineTag, representObject, yTagTimestamp, YamlLoadingError, defaultVal, $, scalar, constructObject, load, yamlTag, constructObjectDefault, construct, ==, representObject, yTagNimField, Mark, transient, representObject, yTagYaml, constructObject, startSeqEvent, endSeqEvent, ConstructionContext, scalarEvent, yamlTagRepositoryPrefix, yamlTag, constructObject, representChild, Event, constructObject, representObject, representObject, yTagBoolean, put, hasSpecificTag, constructChild, getLastTokenContext, yamlTag, constructObject, representObject, yAnchorNone, yTagPairs, constructObject, yamlTag, yTagOrderedMap, representChild, Properties, collection, mitems, constructObject, constructScalarItem, ignore, representObject, emptyProperties, put, startDocEvent, constructChild, basicInit, endStreamEvent, constructChild, initConstructionContext, peek, representObject, initYamlStream, constructObject, constructObject, constructChild, items, AnchorStyle, BufferYamlStream, yTagString, next, TagStyle, yamlTag, represent, yTagSequence, yTagBinary, scalarEvent, representObject, yTagMerge, renderAttrs, sparse, representObject, constructObject, SerializationContext, constructObject, representChild, constructObjectDefault, representObject, representChild, properties, initSerializationContext, yamlTag, representObject, representObject, yamlTag, YamlSerializationError, yamlTag, representObject, constructObject, yTagQuestionMark, representObject, loadMultiDoc, yTagFloat, aliasEvent, startMapEvent, YamlStreamError, endMapEvent, setJsonStyle, hash, constructObject, newBufferYamlStream, defineCoreTag, startStreamEvent, collectionStyle, yamlTag, setBlockOnlyStyle, ==, yTagExclamationMark, peek=, yTagValue, yTagNull, yamlTag, EventKind, hash, representObject, YamlStream, constructChild, startMapEvent, startSeqEvent, constructChild, yTagInteger, constructObject, constructionError, yTagSet, representChild, nimyamlTagRepositoryPrefix, Dumper, endDocEvent, yTagMapping, implicit, ScalarStyle, dump, constructObject, ==, $, presentTag, CollectionStyle, YamlConstructionError, $, SerializationOptions, yamlTag, constructObject, Anchor, representChild, Tag, newYamlConstructionError, defineTag, representObject, yTagTimestamp, YamlLoadingError, defaultVal, $, scalar, constructObject, yamlTag, setCanonicalStyle, constructObjectDefault, construct, ==, representObject, yTagNimField, Mark, transient, minimalDumper, representObject, yTagYaml, constructObject, startSeqEvent, endSeqEvent, ConstructionContext, scalarEvent, setExplanatoryStyle, yamlTagRepositoryPrefix, yamlTag, constructObject, representChild, Event, constructObject, representObject, representObject, yTagBoolean, put, hasSpecificTag, constructChild, getLastTokenContext, yamlTag, constructObject, representObject, yAnchorNone, yTagPairs, constructObject, yamlTag, transform, yTagOrderedMap, representChild, Properties, collection, mitems, constructObject, constructScalarItem, ignore, representObject, emptyProperties, put, startDocEvent, constructChild, basicInit, endStreamEvent, constructChild, initConstructionContext, peek, representObject, initYamlStream, blockOnlyDumper, constructObject, setDefaultStyle, constructObject, constructChild, canonicalDumper, items, AnchorStyle, BufferYamlStream, transform, yTagString, next, TagStyle, jsonDumper, yamlTag, represent, yTagSequence, yTagBinary, scalarEvent, dump, representObject, yTagMerge, renderAttrs, sparse, representObject, constructObject, SerializationContext, constructObject, representChild, constructObjectDefault, representObject, representChild, properties, initSerializationContext, yamlTag, representObject, representObject, explanatoryDumper, yamlTag, setMinimalStyle, YamlSerializationError, yamlTag, representObject, constructObject, yTagQuestionMark, representObject, yTagFloat, aliasEvent, yamlTag, yTagNimFloat32, yTagNimInt8, yamlTag, yamlTag, yamlTag, yamlTag, setTagUri, nimTag, yamlTag, yamlTag, yTagNimUInt32, yamlTag, initNimYamlTagHandle, yamlTag, yTagNimUInt64, yTagNimFloat64, yamlTag, setTagUri, yTagNimInt32, yTagNimInt64, setTag, setTag, yTagNimInt16, yamlTag, yTagNimChar, yTagNimUInt16, yTagNimUInt8, YamlNodeObj, []=, constructChild, items, ==, loadFlattened, hash, newYamlNode, []=, newYamlNode, mitems, YamlNodeKind, mpairs, $, [], [], representChild, newYamlNode, YamlNode, len, pairs, []