Single-document YAML codec: decoding with Formata.YAML.Reader, encoding
with Formata.YAML.Writer.
Decoding
- Exactly one document is accepted. A stream containing more than one
document is rejected with
:parse/:multiple_documents; Formata never silently picks one. An empty stream decodes tonil. - Mapping keys stay as decoded (strings for plain keys; YAML integer or boolean keys stay integers/booleans). No atoms are created from content.
- Duplicate mapping keys are rejected with
:parse/:duplicate_key, including the line/column reported by the parser. - Plain implicit merge keys (
<<) are rejected with:unsupported/:merge_key; quoted or explicitly string-tagged<<keys stay literal. - Null and float scalar keys remain distinct values (including normalized
special floats). Sequence/mapping keys are
:unsupported_keyerrors. - Anchors and aliases are expanded; anchors, comments, formatting and key order are not preserved.
.inf,-.inf,.nanbecome:infinity,:negative_infinity,:nan.- Timestamps are not resolved by the parser's YAML core schema:
2001-12-14decodes as the string"2001-12-14". - Syntax errors carry the line/column reported by the parser.
Options (also enforced for encoding and its read-back check):
:max_depth— non-negative maximum node depth (default128); root depth is zero and mapping keys, values and sequence elements add one.:max_nodes— positive maximum expanded node count (default100_000), including mapping keys and every occurrence of an aliased subtree.
Limits are finite and local to each call. Parsing stops before an alias
exceeds a limit; validation, normalization and conversion share one bounded
traversal. The parser also bounds pending syntax before construction. An
explicit %YAML 1.1 directive selects that schema; otherwise YAML 1.2 core
scalar resolution applies. Timestamps remain strings in both schemas.
Encoding
The YAML domain is nil, booleans, integers, floats (including the
special-float atoms), UTF-8 strings, lists, and maps whose keys are strings,
integers, or booleans. Date/Time/DateTime values are rejected because
they do not decode back to the same values; convert them explicitly with
Formata.Transform.temporal_to_iso8601/1.
Every encoded document is decoded again and compared with the input. If the
emitted YAML would read back as a different value (for example a string that
the emitter left unquoted although it resolves to a number), encoding fails
with :encode / :roundtrip_mismatch instead of returning lossy output.