Skip to content

What yamldoc does not do

An honest list. Some of it is absent by design, some of it is out of reach of the addressing model, and the rest is queued.

Deliberately absent

These are decisions, recorded in the specs, and they will not change without a new one:

  • No file I/O. Bytes in, bytes out. You own the read and the write.
  • No merging, precedence or overlay semantics between documents or files, and no meaning assigned to document order.
  • No application schema. The library interprets YAML's own schemas, Core, JSON, Failsafe and YAML 1.1's, well enough to know that yes is a boolean under 1.1 and a string under 1.2. What a value should be is your business.
  • No formatting. It is not a linter or a pretty-printer. It writes new source in the style of the source around it and leaves everything else alone.
  • No automatic correction of invalid input. A file that does not parse is an error; a file that parses but does not mean anything is reported by Validate and refused by edits that depend on the broken part.
  • No implicit writes through aliases. See What is preserved.
  • No concurrent editing. A File is single-writer. Committed snapshots may be read concurrently; a second Edit while one is open is ErrActiveTransaction.

See Mechanism, not policy for why the line is where it is.

A dotted path has no quoting

A path is a dotted list of string mapping keys with [n] brackets and nothing else: a bracket is an index on a sequence and an integer key on a mapping. It cannot reach a key containing a dot or a bracket, or a key of any other non-string type; StringStep and KeyStep can. An index past a sequence's end is ErrNotFound, not padding. Paths and steps has the whole grammar.

Documents are edited, not authored

An empty stream can be given its first document with CreateDocument. A stream that already has documents keeps exactly that many: no document can be added, removed or reordered. A document whose root is a scalar or a sequence cannot have a mapping key created in it, because there is no mapping to put it in; its root can be replaced.

Queued

  • Explicit style, tag and anchor operations. A tag or anchor survives an edit that does not change its type, and a change of type through a tagged node is refused with ErrTagIntent. There is no API yet to change a tag, add an anchor or switch a scalar's style deliberately.
  • Public import paths for the value types. Profile, Version, Location and their kin are the engine's internal types under public names, which is the same type for every purpose; they get packages of their own when a consumer needs them without the engine (spec 0008 D184).

What is not a limitation, despite appearances

Worth stating, because each of these gets reported as a bug.

  • {} on the line below after removing the last key. Deliberate. An empty mapping and an absent key are different states, and the marker sits on the former child's line so a comment after the last entry keeps its owner.
  • Remove of an absent key returning an error. Deliberate. Silence there hides a typo in a key name. RemoveIfPresent says the other thing.
  • A comment directly above a removed key going with it. Deliberate, and decided: a blank line between comment and key is what makes a section comment. See Comment ownership.
  • Refusing to write through an alias. Deliberate. The library cannot tell whether you mean the shared value or this one use of it.
  • A flow collection closed at column one under a block key failing to parse. That is invalid YAML (yaml-test-suite VJP3/00); goccy accepted it, the engine follows the standard. Indent the closer.
  • Node.String returning ErrKind for 42. Reads are typed. Value gives you whatever it is; Raw gives you the bytes.