Formata.Codec.YAML (formata v0.3.5)

Copy Markdown View Source

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 to nil.
  • 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_key errors.
  • Anchors and aliases are expanded; anchors, comments, formatting and key order are not preserved.
  • .inf, -.inf, .nan become :infinity, :negative_infinity, :nan.
  • Timestamps are not resolved by the parser's YAML core schema: 2001-12-14 decodes 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 (default 128); root depth is zero and mapping keys, values and sequence elements add one.
  • :max_nodes — positive maximum expanded node count (default 100_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.