NimYAML - YAML implementation for Nim

NimYAML is a pure Nim YAML implementation without any dependencies other than Nim's standard library. It enables you to serialize Nim objects to a YAML stream and back. It also provides a low-level event-based API.

Documentation, examples and an online demo are available here. Releases are available as tags in this repository and can be fetched via nimble:

nimble install yaml

Status

This library is stable. NimYAML passes all tests of the current YAML 1.2 test suite. This project follows SemVer.

I am committed to maintaining the library, but will seldom introduce new features. PRs are welcome.

Dependencies

NimYAML requires Nim 2.0.0 or later. The last version supporting Nim 1.6.x is v1.1.0. Use this in your .nimble file if you haven't migrated to Nim 2.x yet:

requires "yaml ^= 1.1.0"

Missing Features

Be aware that serialization currently doesn't support the following features in types that are used for loading and dumping:

Polymorphism: If a field has a type ref Parent, you cannot load a ref Child into it.
Generic objects: The code auto-generating loading and dumping functions currently cannot process instances of generic objects anywhere in the type you want to load/dump.
Default values: NimYAML uses its own {.defaultVal: "foo".} pragma. It currently cannot process default values introduced in Nim 2.0.

Developers

Nix users can nix develop to get a devshell with the required Nim version. You'll need to have Flakes enabled.

nim test # runs all tests
nim lexerTests # run lexer tests
nim parserTests # run parser tests (git-clones yaml-dev-kit)
nim nativeTests # runs native value tests
nim quickstartTests # run tests for quickstart snippets from documentation
nim clean # guess
nim build # build a library

When debugging crashes in this library, use the d:debug compile flag to enable printing of the internal stack traces for calls to internalError and yAssert.

Web Documentation

The online documentation on nimyaml.org, including the testing ground, is generated via Nix Flake.

You can build & run the docs server at via

nix run .#webdocs

It can be deployed to NixOS by importing the Flake's NixOS module and then doing

services.nimyaml-webdocs.enable = true;

This will run the documentation server locally at 127.0.0.1:5000. Since there isn't much of a use-case for third parties to host this documentation, there is no support for running the server without Nix.

License

MIT

Support this Project

If you want to support this project financially, there's a GitHub Sponsor button to the right.

flyx / NimYAML

readme