nyaml

Spec-compliant YAML 1.2 parser and emitter for Erlang/OTP 27+.

Getting started

%% rebar.config
{deps, [nyaml]}.

Decoding

{ok, #{<<"server">> := #{<<"port">> := 8080}}} =
    nyaml:decode(<<"server:\n  port: 8080\n">>),
{ok, [First, Second]} = nyaml:decode_all(<<"---\nfirst\n---\nsecond">>),
{ok, Config} = nyaml:decode_file("config.yaml").

decode/1 gives the first document of the stream, decode_all/1 gives every one. Both take #{schema => core | extended} in their arity 2 form. The core schema is the default and resolves the tags of the JSON schema alone. The extended schema adds the types of the YAML 1.1 type repository that this library carries: !!binary into {binary, Bytes}, the merge key <<, and the y, yes, on, and off boolean tokens under an explicit !!bool.

Encoding

{ok, <<"a:\n  - 1\n  - 2\n">>} = nyaml:encode(#{<<"a">> => [1, 2]}).

encode/1 writes block style for a collection with content and flow style for an empty one. A property test round-trips every shape of t:nyaml:yaml_value/0 through encode/1 and decode/1.

Type mapping

YAML	Erlang
null, ~, empty	null
true, false	true, false
123, -45, 0xFF, 0o10	integer()
3.14	float()
.inf, -.inf, .nan	infinity, negative_infinity, nan
plain, "quoted"	binary()
[a, b]	list()
{a: 1}	map()
2024-01-15T10:30:00	calendar:datetime()

A key resolves under the same rules as a value, so 1: a gives #{1 => <<"a">>}. Quote a key to keep it a string.

Features

• Full YAML 1.2 syntax block and flow collections, block scalars with every indentation and chomping indicator, multi-document streams, anchors, aliases, tags, and %YAML and %TAG directives
• 100% test suite compliance 402 of 402 cases of the official yaml-test-suite, 308 valid cases parsed and 94 invalid cases rejected, none skipped
• Two tag schemas the JSON tags of the YAML 1.2 core schema, and the YAML 1.1 type repository under #{schema => extended}
• Every encoding UTF-8, UTF-16 (BE/LE), and UTF-32 (BE/LE), detected from the byte order mark or the byte pattern
• Emitter block style output, round-trip verified against the parser by a property test
• Idiomatic Erlang every function gives {ok, Value} or {error, Reason} and never throws
• No dependencies only OTP kernel and stdlib

Documentation

nyaml on HexDocs

Development

The compliance suite runs against the official yaml-test-suite, vendored as a git submodule that is pinned to the data-2022-01-17 tag. Clone with --recurse-submodules, or run git submodule update --init before rebar3 compliance.

License

Apache License 2.0