/ README.md
README.md
1 # NimYAML - YAML implementation for Nim 2 3  4 5 NimYAML is a pure Nim YAML implementation without any dependencies other than 6 Nim's standard library. It enables you to serialize Nim objects to a YAML stream 7 and back. It also provides a low-level event-based API. 8 9 Documentation, examples and an online demo are available [here][1]. Releases are 10 available as tags in this repository and can be fetched via nimble: 11 12 nimble install yaml 13 14 ## Status 15 16 This library is stable. 17 NimYAML passes all tests of the current [YAML 1.2 test suite][4]. 18 This project follows [SemVer][5]. 19 20 I am committed to maintaining the library, but will seldom introduce new features. 21 PRs are welcome. 22 23 ## Dependencies 24 25 NimYAML requires Nim 2.0.0 or later. 26 The last version supporting Nim 1.6.x is `v1.1.0`. 27 Use this in your `.nimble` file if you haven't migrated to Nim 2.x yet: 28 29 ```nim 30 requires "yaml ^= 1.1.0" 31 ``` 32 33 ## Missing Features 34 35 Be aware that serialization currently doesn't support the following features in types that are used for loading and dumping: 36 37 * Polymorphism: If a field has a type `ref Parent`, you cannot load a `ref Child` into it. 38 * 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. 39 * Default values: NimYAML uses its own `{.defaultVal: "foo".}` pragma. 40 It currently cannot process default values introduced in Nim 2.0. 41 42 ## Developers 43 44 Nix users can `nix develop` to get a devshell with the required Nim version. You'll need to have Flakes enabled. 45 46 ```bash 47 nim test # runs all tests 48 nim lexerTests # run lexer tests 49 nim parserTests # run parser tests (git-clones yaml-dev-kit) 50 nim nativeTests # runs native value tests 51 nim quickstartTests # run tests for quickstart snippets from documentation 52 nim clean # guess 53 nim build # build a library 54 ``` 55 56 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`. 57 58 ### Web Documentation 59 60 The online documentation on [nimyaml.org][1], including the 61 testing ground, is generated via [Nix Flake][3]. 62 63 You can build & run the docs server at via 64 65 ```bash 66 nix run .#webdocs 67 ``` 68 69 It can be deployed to NixOS by importing the Flake's NixOS module and then doing 70 71 ```nix 72 services.nimyaml-webdocs.enable = true; 73 ``` 74 75 This will run the documentation server locally at `127.0.0.1:5000`. 76 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. 77 78 ## License 79 80 [MIT][2] 81 82 ## Support this Project 83 84 If you want to support this project financially, there's a GitHub Sponsor button to the right. 85 86 [1]: https://nimyaml.org 87 [2]: copying.txt 88 [3]: https://nixos.wiki/wiki/Flakes 89 [4]: https://github.com/yaml/yaml-test-suite 90 [5]: https://semver.org