📖 2 min read (~ 400 words).

Parser

Parsing

f, err := parser.ParseBytes(src, parser.WithComments())
if err != nil {
	// ...
}
for _, doc := range f.Docs {
	// doc.Body is the root node of one document
}

ParseFile reads a path. parser.New builds a Parser you can hold and reuse with a fixed set of options.

An *ast.File holds every document in the stream, in Docs. A stream with one document has one entry; --- starts another.

The options

optionwhat it changes
WithCommentskeeps comments. They are dropped by default, before the grouping ever sees them.
WithYAMLVersionreads under 1.0, 1.1 or 1.2 rather than the document’s own directive
WithAnchorspublishes anchors declared in another parse
WithMergeKeysresolves a bare << as a merge key at any version, and changes nothing else
WithLaxTagsreads !!int abc as the text abc instead of refusing the document
WithAllowDuplicateMapKeyaccepts a repeated key instead of refusing it
WithJSONCompatiblereports 1: and "1": in one mapping as ErrNotJSON, since both write the JSON name "1"
WithOmitNodePathsstops recording each node’s path
WithChunkSizehow many tokens one chunk of the token arena holds
WithOnCompletecalls a function with each node as the parser finishes it
WithOmitNodePaths turns off more than it says

Node paths are what ast.Node.GetPath returns and what a CommentMap is keyed by. Omit them and GetPath returns "", and the map codec.CommentToMap fills comes back keyed by empty strings. Neither reports anything.

Paths are recorded by default and cost little. Reach for this only when you have measured that they cost you.

Anchors across a parse

The parser owns the anchor table. It resolves every alias against the anchors of the document holding it, and refuses one that names none — so a fragment meant to be read beside other files has to be handed their anchors:

f, err := parser.ParseBytes(fragment, parser.WithAnchors(anchors))

Pass ast.DocumentNode.Anchors from the parse that declared them. This is also what codec.ReferenceFiles needs when you drive the decode from a node you parsed yourself.

Reading a node as the parser finishes it

WithOnComplete reports each node in completion order — a node’s children before the node itself.

Note

This is the seam a streaming API will use, and it is marked an experiment in the source. It is not a streaming API: ParseBytes still reads the whole document before it returns. See Status.