go-yaml Documentation

For low-level manipulation of the YAML Abstract Syntax Tree (AST), use the Node-level API. This is useful when you need to preserve comments, handle complex structures programmatically, or perform strict unmarshaling in custom types.

Key patterns include:

• node.Load(): Loads YAML into a Node representation. When used with WithKnownFields(), it allows for strict field checking even within custom UnmarshalYAML implementations.
• node.Dump(): Encodes Node structures into YAML with specific formatting options.
• Programmatic Building: You can manually construct complex Node structures and then dump them.

The internal/libyaml testing framework uses a data-driven approach to separate test logic from test data. This allows for adding new test cases by simply creating YAML files without writing new Go code.

Core Architecture:

1. Test Data: Stored in YAML files within the testdata/ directory.
2. Test Logic: Implemented in Go files (*_test.go).
3. One-to-one Pairing: Each test data file (e.g., testdata/foo.yaml) has a corresponding Go test file (foo_test.go).

Key Components:

• TestCase struct: An umbrella structure that uses interface{} fields to hold various test types. The framework performs post-processing to convert these generic fields into specific types like WantEvents, WantTokens, or WantSpecs after loading.

The go-yaml library classifies comments based on their position relative to YAML nodes to ensure they can be preserved during round-tripping or presented in a Node tree.

Public Comment Types

• HeadComment: Lines preceding a node with no blank line separation (e.g., # comment\nkey: value).
• LineComment: Comments on the same line as a node, following its value (e.g., key: value # inline comment).
• FootComment: Comments appearing after a node but before any blank lines (e.g., key: value\n# trailing comment).

Internal Comment Types (Parsing only)

• TailComment: A foot comment at the end of a block mapping value.
• stem_comment: A comment on an entry immediately preceding a nested structure.

The Dump stack is the pipeline that transforms Go values into YAML text. It follows a push-based architecture where lower stages push data to higher stages. The sequence of stages is:

1. Representer: Converts Go values into Events. It handles type dispatch, field filtering (including ,inline tags), key sorting, and style selection.
2. Serializer: Converts Node trees into Events. It performs tag elision checks and determines when to use flow style.
3. Emitter: Converts Events into UTF-8 YAML text, handling line wrapping, indentation, and final style selection.
4. Writer: Flushes the output buffer to the final destination.

Comments are processed through a pipeline to ensure they are correctly associated with the appropriate YAML nodes:

1. Scanner: Identifies and classifies comments (Head, Foot, or Line) based on indentation, flow context (e.g., inside [...] or {...}), and empty line boundaries.
2. Parser: Accumulates comment tokens and attaches them to events. It handles special logic like splitting document headers at empty lines and transforming sequence entry line comments into head comments.
3. Composer: Transfers comments from events to the final Node tree. It applies reassignment rules, such as moving dedented comments from a key's FootComment to the parent mapping's FootComment, or moving a mapping's FootComment to its last key.

When configuring a yaml.NewDumper or yaml.NewLoader, you can combine preset functions (like yaml.WithV3Defaults()) with specific overrides.

Crucial Rule: Options are applied left-to-right. A later option will override any conflicting setting from an earlier option.

// Start with v3 defaults (4-space), then override to 2-space
dumper, _ := yaml.NewDumper(writer,
    yaml.WithV3Defaults(),
    yaml.WithIndent(2),  // This wins
)

The choice of API depends on your data volume and whether you need custom configuration:

• Use Dump/Load for config files, API responses, or test data where you need options but not streaming.
• Use NewDumper/NewLoader for large files, network streams, or processing documents incrementally.
• Use Marshal/Unmarshal for quick scripts or upgrading existing v3 code where default formatting is sufficient.

v4 introduces StreamNode, which allows access to stream-level metadata like encoding, %YAML version directives, and %TAG directives. This metadata is stored in Node.Stream and is only non-nil when the node is a StreamNode.

To use this, you must enable stream nodes during loading using yaml.WithStreamNodes(). When enabled, the loader emits nodes in a pattern: [Stream, Doc, Stream, Doc, ..., Stream].

loader := yaml.NewLoader(reader, yaml.WithStreamNodes())
for {
    var node yaml.Node
    err := loader.Load(&node)
    if errors.Is(err, io.EOF) {
        break
    }
    if node.Kind == yaml.StreamNode && node.Stream != nil {
        enc := node.Stream.Encoding
        ver := node.Stream.Version        // *yaml.VersionDirective
        tags := node.Stream.TagDirectives // []yaml.TagDirective
    }
}