go-yaml

https://github.com/yaml/go-yaml
Admin
A Go package that enables programs to encode and decode YAML values, based on a pure Go port of the...
Tokens:63,834
Snippets:549
Trust Score:7.4
License:Apache-2.0
Update:4 weeks ago
Show doc for...
Tokens:
Raw
### Run example from example directory

Source: https://github.com/yaml/go-yaml/blob/main/example/README.md

Alternative way to run from within the example directory.

```bash
cd example
go run basic_loader.go
```

--------------------------------

### Run example directly

Source: https://github.com/yaml/go-yaml/blob/main/example/README.md

Run the basic_loader example using the Go command.

```bash
go run example/basic_loader.go
```

--------------------------------

### Install go-yaml with go get

Source: https://github.com/yaml/go-yaml/blob/main/README.md

Install the go-yaml package using the go get command. The import path is go.yaml.in/yaml/v4.

```bash
go get go.yaml.in/yaml/v4
```

--------------------------------

### Install go-yaml CLI with go install

Source: https://github.com/yaml/go-yaml/blob/main/_autodocs/api-reference/cli.md

Installs the go-yaml command-line tool from the repository using the Go toolchain. Requires Go to be installed and the module path to be accessible.

```bash
go install go.yaml.in/yaml/v4/cmd/go-yaml@latest
```

--------------------------------

### WithExplicitStart: Example Output

Source: https://github.com/yaml/go-yaml/blob/main/docs/options.md

Example YAML output showing WithExplicitStart(true) and WithExplicitStart(false) (default).

```yaml
# WithExplicitStart(true)
---
name: test

# WithExplicitStart(false) - default
name: test
```

--------------------------------

### Get a shell with the makefile environment

Source: https://github.com/yaml/go-yaml/blob/main/CONTRIBUTING.md

Run one of these commands to get a subshell with the same binaries that the makefile installs. You can specify a Go version with GO-VERSION, for example make shell GO-VERSION=1.23.4.

```bash
make shell
make bash
make zsh
make shell GO-VERSION=1.23.4
```

--------------------------------

### Usage examples for limit.New

Source: https://github.com/yaml/go-yaml/blob/main/_autodocs/api-reference/plugins.md

Shows how to create a loader with default limits, disable alias checks, and set a custom depth limit.

```go
// Default limits
loader := yaml.NewLoader(data, yaml.WithPlugin(limit.New()))
// Disable alias checks (e.g. for 11,000 programmatic aliases)
loader := yaml.NewLoader(data, yaml.WithPlugin(limit.New(limit.AliasNone())))
// Custom depth limit
loader := yaml.NewLoader(data, yaml.WithPlugin(limit.New(limit.DepthValue(50))))
```

--------------------------------

### WithLineWidth: Example Output

Source: https://github.com/yaml/go-yaml/blob/main/docs/options.md

Example YAML output for LineWidth=40 (wraps long strings) and LineWidth=-1 (no wrapping).

```yaml
# LineWidth=40
description: |
  This is a long description
  that wraps to multiple lines.

# LineWidth=-1
description: This is a long description that stays on one line
```

--------------------------------

### WithIndent: Example Output

Source: https://github.com/yaml/go-yaml/blob/main/docs/options.md

Example YAML output for different indentation levels: 2, 4, and 8 spaces.

```yaml
# WithIndent(2)
servers:
  web:
    host: localhost
    port: 8080

# WithIndent(4)
servers:
    web:
        host: localhost
        port: 8080

# WithIndent(8)
servers:
        web:
                host: localhost
                port: 8080
```

--------------------------------

### Build with JSON-comments plugin and run with -j flag

Source: https://github.com/yaml/go-yaml/blob/main/cmd/go-yaml/README.md

Builds the go-yaml binary with the JSON-comments plugin enabled via the example options file, then runs it on example data. The build resolves the newest tagged JSON-comments Go release each time.

```bash
make cli CONFIG=example/json-comments/options.yaml
./go-yaml -j example/json-comments/data.yaml
```

--------------------------------

### Dumper usage example

Source: https://github.com/yaml/go-yaml/blob/main/_autodocs/api-reference/load-dump.md

Example of using Dumper to write multiple documents to a buffer. Creates a new dumper with indentation 2, dumps two config values, closes, and prints the result.

```go
var buf bytes.Buffer
dumper, err := yaml.NewDumper(&buf, yaml.WithIndent(2))
if err != nil { log.Fatal(err) }
if err := dumper.Dump(&cfg1); err != nil { log.Fatal(err) }
if err := dumper.Dump(&cfg2); err != nil { log.Fatal(err) }
if err := dumper.Close(); err != nil { log.Fatal(err) }
fmt.Print(buf.String())
```

--------------------------------

### OptsYAML config example with WithV4Defaults

Source: https://github.com/yaml/go-yaml/blob/main/_autodocs/configuration.md

Shows how to parse a YAML config string with OptsYAML and pass it to NewDumper along with WithV4Defaults. The config file is commented out in the Go code, showing the expected YAML structure.

```go
// config.yml:
// indent: 3
// known-fields: true
// plugin:
//   limit:
//     depth: 50
opts, err := yaml.OptsYAML(configYAML)
dumper, err := yaml.NewDumper(w, yaml.Options(yaml.WithV4Defaults(), opts))
```

--------------------------------

### api-new test example

Source: https://github.com/yaml/go-yaml/blob/main/internal/libyaml/README.md

Tests constructors. The example tests NewParser with various buffer sizes and nil checks.

```yaml
- api-new:
    name: New parser
    with: NewParser
    test:
    - nil: [raw-buffer, false]
    - cap: [raw-buffer, 512]
    - nil: [buffer, false]
    - cap: [buffer, 1536]
```

--------------------------------

### WithExplicitEnd: Example Output

Source: https://github.com/yaml/go-yaml/blob/main/docs/options.md

Example YAML output showing WithExplicitEnd(true) and WithExplicitEnd(false) (default).

```yaml
# WithExplicitEnd(true)
name: test
...

# WithExplicitEnd(false) - default
name: test
```

--------------------------------

### Using the plugin with yaml.Load

Source: https://github.com/yaml/go-yaml/blob/main/_autodocs/api-reference/plugins.md

This example shows how to use the plugin directly by passing `jsoncomments.New()` to `yaml.WithPlugin`. It parses a YAML string with a JSON-style comment.

```go
var value any
err := yaml.Load([]byte("a: true // comment\n"), &value,
    yaml.WithPlugin(jsoncomments.New()))
```

--------------------------------

### Example output: unmarshal and marshal results

Source: https://github.com/yaml/go-yaml/blob/main/README.md

Output produced by the preceding Go example. Shows the unmarshaled struct, its YAML dump, the unmarshaled map, and its YAML dump.

```text
--- t:
{Easy! {2 [3 4]}}

--- t dump:
a: Easy!
b:
  c: 2
  d: [3, 4]


--- m:
map[a:Easy! b:map[c:2 d:[3 4]]]

--- m dump:
a: Easy!
b:
  c: 2
  d:
  - 3
  - 4
```

--------------------------------

### api-method test example

Source: https://github.com/yaml/go-yaml/blob/main/internal/libyaml/README.md

Tests methods and field state. The example calls SetInputString with 'key: value' and verifies the input and input-pos fields.

```yaml
- api-method:
    name: Parser set input string
    with: NewParser
    byte: true
    call: [SetInputString, 'key: value']
    test:
    - eq: [input, 'key: value']
    - eq: [input-pos, 0]
    - nil: [read-handler, false]
```

--------------------------------

### WithExplicitStart option

Source: https://github.com/yaml/go-yaml/blob/main/_autodocs/api-reference/options.md

Boolean option to print explicit `---` at document start. Default false. Variadic; enable default.

```go
func WithExplicitStart(explicit ...bool) Option
```

--------------------------------

### api-delete test example

Source: https://github.com/yaml/go-yaml/blob/main/internal/libyaml/README.md

Tests cleanup. The example initializes with SetInputString and verifies that input and buffer lengths become zero after deletion.

```yaml
- api-delete:
    name: Parser delete
    with: NewParser
    byte: true
    init: [SetInputString, test]
    test:
    - len: [input, 0]
    - len: [buffer, 0]
```

--------------------------------

### type-as-key test format example format

Source: https://github.com/yaml/go-yaml/blob/main/internal/libyaml/README.md

Shows the type-as-key format where the test type is the map key. The example, in a YAML test file, uses a test case with a name field and additional fields.

```yaml
- test-type:
    name: Test case name
    # ... other fields

```

--------------------------------

### Encoder usage example

Source: https://github.com/yaml/go-yaml/blob/main/_autodocs/api-reference/classic-apis.md

Creates an encoder, sets indentation to 4 spaces, encodes two configurations, and closes the encoder, handling errors with log.Fatal.

```go
enc := yaml.NewEncoder(&buf)
enc.SetIndent(4)
if err := enc.Encode(&cfg1); err != nil { log.Fatal(err) }
if err := enc.Encode(&cfg2); err != nil { log.Fatal(err) }
if err := enc.Close(); err != nil { log.Fatal(err) }
```

--------------------------------

### WithCompactSeqIndent: Example Output

Source: https://github.com/yaml/go-yaml/blob/main/docs/options.md

Example YAML output showing compact=true (v4 default) and compact=false (v3 style) sequence indentation.

```yaml
# compact=true (v4 default)
items:
  - name: first
    value: 1
  - name: second
    value: 2

# compact=false (v3 style)
items:
    - name: first
      value: 1
    - name: second
      value: 2
```

--------------------------------

### Go example: unmarshal and marshal YAML

Source: https://github.com/yaml/go-yaml/blob/main/README.md

Complete Go program demonstrating yaml.Unmarshal and yaml.Marshal on a struct and a map. Note that struct fields must be public for unmarshal to populate data. The example prints the unmarshaled struct, its YAML dump, the unmarshaled map, and its YAML dump.

```go
package main

import (
	"fmt"
	"log"

	"go.yaml.in/yaml/v4"
)

var data = `
a: Easy!
b:
  c: 2
  d: [3, 4]
`

// Note: struct fields must be public in order for unmarshal to
// correctly populate the data.
type T struct {
	A string
	B struct {
		RenamedC int   `yaml:"c"`
		D	[]int `yaml:",flow"`
	}
}

func main() {

	t := T{}

	err := yaml.Unmarshal([]byte(data), &t)
	if err != nil {
		log.Fatalf("error: %v", err)
	}
	fmt.Printf("--- t:\n%v\n\n", t)

	d, err := yaml.Marshal(&t)
	if err != nil {
		log.Fatalf("error: %v", err)
	}
	fmt.Printf("--- t dump:\n%s\n\n", string(d))

	m := make(map[any]any)

	err = yaml.Unmarshal([]byte(data), &m)
	if err != nil {
		log.Fatalf("error: %v", err)
	}
	fmt.Printf("--- m:\n%v\n\n", m)

	d, err = yaml.Marshal(&m)
	if err != nil {
		log.Fatalf("error: %v", err)
	}
	fmt.Printf("--- m dump:\n%s\n\n", string(d))
}
```

--------------------------------

### api-new-event test example

Source: https://github.com/yaml/go-yaml/blob/main/internal/libyaml/README.md

Tests event constructors. The example calls NewStreamStartEvent with UTF8_ENCODING and verifies the Type and encoding fields.

```yaml
- api-new-event:
    name: New stream start event
    call: [NewStreamStartEvent, UTF8_ENCODING]
    test:
    - eq: [Type, STREAM_START_EVENT]
    - eq: [encoding, UTF8_ENCODING]
```

--------------------------------

### WithExplicitStart: Emit Document Start Marker

Source: https://github.com/yaml/go-yaml/blob/main/docs/options.md

Controls whether document start markers (---) are always emitted. Use case: multi-document streams, explicit document boundaries.

```go
// Always emit --- at document start (short form)
yaml.NewDumper(w, yaml.WithExplicitStart())
```

--------------------------------

### api-panic test example

Source: https://github.com/yaml/go-yaml/blob/main/internal/libyaml/README.md

Tests methods that should panic. The example calls SetInputString twice and expects a panic with the message 'must set the input source only once'.

```yaml
- api-panic:
    name: Parser set input string twice
    with: NewParser
    byte: true
    init: [SetInputString, first]
    call: [SetInputString, second]
    want: must set the input source only once
```

--------------------------------

### Export GO_YAML_PATH to use custom Go installation

Source: https://github.com/yaml/go-yaml/blob/main/README.md

Use this shell snippet to point the makefile at your own Go installation. Export GO_YAML_PATH to the directory containing the go binary, then run any make rule. GO-YAML_PATH and GO-VERSION are mutually exclusive; when GO_YAML_PATH is set, GO-VERSION is ignored.

```shell
export GO_YAML_PATH=$(dirname "$(command -v go)")
make <rule>
# or:
make <rule> GO_YAML_PATH=$(dirname "$(command -v go)")
```

--------------------------------

### Embedded options example: YAML configuration

Source: https://github.com/yaml/go-yaml/blob/main/cmd/go-yaml/README.md

Example options file that sets indent to 4 and enables the limit and json-comments plugins. The limit plugin is configured with depth and alias settings, and json-comments is enabled with default settings.

```yaml
indent: 4
plugin:
  limit:
    depth: 50
    alias: 100
  json-comments: {}
```

--------------------------------

### Using WithPlugin with NewLoader

Source: https://github.com/yaml/go-yaml/blob/main/_autodocs/api-reference/plugins.md

Example usage of WithPlugin to register a limit plugin and an event-source plugin when creating a loader.

```go
loader := yaml.NewLoader(data,
    yaml.WithPlugin(limit.New(limit.AliasNone())),     // limit
    yaml.WithPlugin(jsoncomments.New()),               // event source
)
```

--------------------------------

### Single-document mode with Loader.Load

Source: https://github.com/yaml/go-yaml/blob/main/_autodocs/api-reference/load-dump.md

Example of using WithSingleDocument to load only the first document, subsequent calls return io.EOF.

```go
loader, _ := yaml.NewLoader(reader, yaml.WithSingleDocument())
var cfg Config
if err := loader.Load(&cfg); err != nil && !errors.Is(err, io.EOF) { ... }
_ = loader.Load(&cfg2) // always io.EOF after the first document
```

--------------------------------

### emit-config test example

Source: https://github.com/yaml/go-yaml/blob/main/internal/libyaml/README.md

Emits with a custom indent configuration. The test sets indent to 4 and expects the output to contain 'key'.

```yaml
- emit-config:
    name: Custom indent
    conf:
      indent: 4
    data:
    - STREAM_START_EVENT:
        encoding: UTF8_ENCODING
    - DOCUMENT_START_EVENT:
        implicit: true
    - MAPPING_START_EVENT:
        implicit: true
        style: BLOCK_MAPPING_STYLE
    # ... more events
    want: key
```

--------------------------------

### Run go-yaml CLI on a small YAML snippet

Source: https://github.com/yaml/go-yaml/blob/main/CONTRIBUTING.md

Use the go-yaml CLI tool to inspect the internal stages and final results of YAML processing. This example pipes a small YAML snippet to the tool using the -t flag. It is useful when reporting bugs to show the decoding process.

```bash
./go-yaml -t <<< '
foo: &a1 bar
*a1: baz

```

--------------------------------

### Example: unmarshal into a struct

Source: https://github.com/yaml/go-yaml/blob/main/_autodocs/api-reference/classic-apis.md

Shows how to unmarshal a YAML document into a struct with tagged and untagged fields. Uses `omitempty` on the `yaml` tag and demonstrates error handling with `log.Fatal`.

```go
type T struct {
    F int `yaml:"a,omitempty"`
    B int
}
var t T
if err := yaml.Unmarshal([]byte("a: 1\nb: 2"), &t); err != nil {
    log.Fatal(err)
}
```

--------------------------------

### roundtrip test example

Source: https://github.com/yaml/go-yaml/blob/main/internal/libyaml/README.md

Parses YAML and emits it, verifying the output contains expected strings. The test uses a mapping with a list and expects 'key', 'value', and 'item1'.

```yaml
- roundtrip:
    name: Roundtrip
    yaml: |
      key: value
      list:
        - item1
        - item2
    want:
    - key
    - value
    - item1
```

--------------------------------

### emit-writer test example

Source: https://github.com/yaml/go-yaml/blob/main/internal/libyaml/README.md

Emits to an io.Writer. The test uses a stream start event and expects the output to contain 'test'.

```yaml
- emit-writer:
    name: Writer
    data:
    - STREAM_START_EVENT:
        encoding: UTF8_ENCODING
    # ... more events
    want: test
```

--------------------------------

### Using OptsYAML with plugin config

Source: https://github.com/yaml/go-yaml/blob/main/_autodocs/api-reference/options.md

Shows how to parse YAML options and combine with presets.

```go
opts, err := yaml.OptsYAML(`
indent: 3
known-fields: true
plugin:
  limit:
    depth: 50
`)
if err != nil { log.Fatal(err) }
yaml.Dump(&data, yaml.Options(yaml.WithV4Defaults(), opts))
```

--------------------------------

### Using version presets

Source: https://github.com/yaml/go-yaml/blob/main/example/README.md

Create a dumper with the v4 defaults preset for standard output formatting.

```go
dumper, _ := yaml.NewDumper(writer,
    yaml.WithV4Defaults(),
)
```

--------------------------------

### Using Options with presets and WithIndent

Source: https://github.com/yaml/go-yaml/blob/main/_autodocs/api-reference/options.md

Shows how to combine presets with custom options using yaml.Options.

```go
opts := yaml.Options(yaml.WithV4Defaults(), yaml.WithIndent(3))
yaml.Dump(&data, opts)
```

--------------------------------

### WithUnicode: Example Output

Source: https://github.com/yaml/go-yaml/blob/main/docs/options.md

Example YAML output showing unicode enabled (default) and disabled (escaped).

```yaml
# WithUnicode(true) - default
name: café

# WithUnicode(false)
name: "caf\u00e9"
```

--------------------------------

### Build and run go-yaml CLI with help and node output

Source: https://github.com/yaml/go-yaml/blob/main/README.md

Builds the go-yaml binary with make, shows its help, and runs it on a sample YAML input with the -n flag to display the decoded Node structs formatted in YAML. Useful for inspecting internal processing stages when reporting issues.

```bash
make go-yaml
./go-yaml --help
./go-yaml <<< '
foo: &a1 bar
*a1: baz
' -n        # Show value on decoded Node structs (formatted in YAML)
```

--------------------------------

### Run go-yaml with -C options file

Source: https://github.com/yaml/go-yaml/blob/main/example/json-comments/README.md

Supplies the options file through -C instead of embedding it. This works because the options file's version matches the binary's linked plugin version.

```bash
./go-yaml -C example/json-comments/options.yaml \
  -j example/json-comments/data.yaml
```

--------------------------------

### WithCanonical: Example Output

Source: https://github.com/yaml/go-yaml/blob/main/docs/options.md

Example YAML output showing normal output and canonical output with explicit tags.

```yaml
# Normal output
name: John
age: 30

# Canonical output
!!map {
  ? !!str "name"
  : !!str "John",
  ? !!str "age"
  : !!int "30",
}
```

--------------------------------

### style-accessor test example

Source: https://github.com/yaml/go-yaml/blob/main/internal/libyaml/README.md

Tests style accessor methods. The example checks that the event scalar style is DOUBLE_QUOTED_SCALAR_STYLE.

```yaml
- style-accessor:
    name: Event scalar style
    test: [ScalarStyle, DOUBLE_QUOTED_SCALAR_STYLE]
```

--------------------------------

### Exercise the complete pipeline with go-yaml

Source: https://github.com/yaml/go-yaml/blob/main/cmd/go-yaml/README.md

Runs the full pipeline: tokenize, event, node, and YAML output. Demonstrates chaining of go-yaml commands.

```bash
# Exercise the complete pipeline.
go-yaml -t file.yaml | go-yaml -e | go-yaml -N | go-yaml -Y
```

--------------------------------

### enum-string test example

Source: https://github.com/yaml/go-yaml/blob/main/internal/libyaml/README.md

Tests String() methods of enums. The example checks that ScalarStyle PLAIN_SCALAR_STYLE returns 'Plain'.

```yaml
- enum-string:
    name: Scalar style plain
    enum: [ScalarStyle, PLAIN_SCALAR_STYLE]
    want: Plain
```

--------------------------------

### go run all tests in the package

Source: https://github.com/yaml/go-yaml/blob/main/internal/libyaml/README.md

Runs all tests in the internal/libyaml package using the go test command.

```bash
go test ./internal/libyaml

```

--------------------------------

### Using v4 Options with yaml.WithV4Defaults()

Source: https://github.com/yaml/go-yaml/blob/main/docs/options.md

Use this preset for modern YAML output with 2-space indent and compact sequences. This is the default, so specifying it is optional unless you want to be explicit.

```go
dumper, _ := yaml.NewDumper(writer, yaml.WithV4Defaults())
```

--------------------------------

### go-yaml basic usage

Source: https://github.com/yaml/go-yaml/blob/main/_autodocs/api-reference/cli.md

Shows the command-line syntax for go-yaml. With no file or '-', input is read from stdin. Only one file argument is supported. If stdin is a TTY and no mode flag is given, help is printed; if stdin has data and no mode flag is given, an error is raised.

```text
go-yaml [flags] [file]
```

--------------------------------

### scalar-resolution test examples

Source: https://github.com/yaml/go-yaml/blob/main/internal/libyaml/README.md

Tests scalar type resolution. The examples verify that '42' resolves to integer 42 and '-2.5' resolves to float -2.5.

```yaml
- scalar-resolution:
    name: Positive integer
    yaml: "42"
    want: 42
```

```yaml
- scalar-resolution:
    name: Negative float
    yaml: "-2.5"
    want: -2.5
```

--------------------------------

### Version preset function signatures

Source: https://github.com/yaml/go-yaml/blob/main/_autodocs/api-reference/options.md

Declarations for WithV2Defaults, WithV3Defaults, and WithV4Defaults.

```go
func WithV2Defaults() Option { ... }
func WithV3Defaults() Option { ... }
func WithV4Defaults() Option { ... }
```

--------------------------------

### Using v2 Options with yaml.WithV2Defaults()

Source: https://github.com/yaml/go-yaml/blob/main/docs/options.md

Use this preset to match go-yaml v2 output format, which uses a 2-space indent and non-compact sequences.

```go
dumper, _ := yaml.NewDumper(writer, yaml.WithV2Defaults())
```

--------------------------------

### Configure limit plugin options

Source: https://github.com/yaml/go-yaml/blob/main/docs/plugins.md

Shows how to create a loader with the limit plugin using default limits, disabling alias checking with AliasNone(), or setting a custom depth limit with DepthValue(50).

```go
import "go.yaml.in/yaml/v4/plugin/limit"

// Default limits (same as library defaults)
loader := yaml.NewLoader(data, yaml.WithPlugin(limit.New()))

// Disable alias checking (e.g. for documents with many programmatic aliases)
loader := yaml.NewLoader(data, yaml.WithPlugin(limit.New(limit.AliasNone())))

// Custom depth limit
loader := yaml.NewLoader(data, yaml.WithPlugin(limit.New(limit.DepthValue(50))))
```

--------------------------------

### Build with embedded options and run with piped input

Source: https://github.com/yaml/go-yaml/blob/main/cmd/go-yaml/README.md

Builds the binary with the embedded options file, then pipes a YAML string with a comment into the binary using the -j flag. The binary no longer needs the options file at runtime.

```bash
make cli CONFIG=example/json-comments/options.yaml
printf 'a: true // comment\n' | ./go-yaml -j
```

--------------------------------

### OptsYAML plugin schema example

Source: https://github.com/yaml/go-yaml/blob/main/_autodocs/configuration.md

Shows the YAML structure for configuring a plugin via the 'plugin' key in OptsYAML. The 'limit' plugin accepts 'depth' and 'alias' settings, with optional host fields 'disable', 'name', and 'version'. 'true' enables defaults, 'false' or '{disable: true}' disables, and null causes an error.

```yaml
plugin:
  limit:            # API name; value may be: true, false, or a mapping
    depth: 50       # int or null (null disables depth checking)
    alias: 1000     # int or null (null disables alias checking)
    disable: true   # optional host field: disable this plugin
    name: limit     # optional host field: select implementation (defaults to API key)
    version: v1.2.3 # optional host field: require exact linked release
```

--------------------------------

### Run the Go program with make shell

Source: https://github.com/yaml/go-yaml/blob/main/example/json-comments/README.md

Runs the Go program from the repository root. The program loads data.yaml with jsoncomments.New(), writes the loaded value as JSON, and checks its Go build information to confirm plugin version v0.1.8 is linked. It prints the sample data as one line of JSON.

```bash
make shell CMD='go -C example/json-comments run .'
```

--------------------------------

### Node struct

Source: https://github.com/yaml/go-yaml/blob/main/_autodocs/api-reference/node.md

Documentation for the Node struct, its fields, and usage example.

```APIDOC
## Node struct

### Description
The `Node` type represents the intermediate tree structure of a YAML document. It can be used as a field in a struct or as the target of `Unmarshal`/`Load` to access the raw YAML structure.

### Type
`Node`

### Fields
- **Kind** (`Kind`) - Document, mapping, sequence, scalar, alias, or stream node.
- **Style** (`Style`) - Formatting style (tagged, quoted, literal/folded block, flow).
- **Tag** (`string`) - YAML tag. On decode: always the resolved tag. On encode: if unset, implied from node properties; if set, serialized only with `TaggedStyle` or when it diverges from the implicit tag.
- **Value** (`string`) - Unescaped, unquoted scalar value.
- **Anchor** (`string`) - Anchor name (aliases point at it).
- **Alias** (`*Node`) - Target node; valid only when `Kind == AliasNode`.
- **Content** (`[]*Node`) - Child nodes for documents, mappings, sequences.
- **HeadComment** (`string`) - Comments in lines preceding the node (no blank-line separation).
- **LineComment** (`string`) - Comments at the end of the node's line.
- **FootComment** (`string`) - Comments following the node before empty lines.
- **Line** (`int`) - Position of the node in the decoded text (1-based; not respected when encoding).
- **Column** (`int`) - Position of the node in the decoded text (1-based; not respected when encoding).
- **Stream** (`*Stream`) - Stream metadata; non-nil only when `Kind == StreamNode`.

### Usage Example
```go
var person Node
err := yaml.Unmarshal(data, &person)
```
```

--------------------------------

### Enforce unique keys with yaml.WithUniqueKeys

Source: https://github.com/yaml/go-yaml/blob/main/docs/options.md

Controls duplicate key detection in mappings. When enabled (default), loading fails if duplicate keys are found. The example shows the short form and the explicit disable form, plus an example YAML that would fail. This prevents key override attacks.

```go
// Enforce unique keys (default - short form)
loader, _ := yaml.NewLoader(reader,
    yaml.WithUniqueKeys(),
)

// Allow duplicates (not recommended)
loader, _ := yaml.NewLoader(reader,
    yaml.WithUniqueKeys(false),
)
```

```yaml
admin: false
admin: true  # Error: duplicate key
```

--------------------------------

### WithV2Defaults() Option

Source: https://github.com/yaml/go-yaml/blob/main/_autodocs/api-reference/options.md

Returns an Option with v2 default settings, including indent 2, compact-seq-indent false, line-width 80, unicode true, unique-keys true, quote-preference QuoteLegacy, and a default limit plugin.

```APIDOC
## `WithV2Defaults`

### Description
Returns an `Option` with v2 default settings. Includes a default `limit` plugin.

### Method
N/A (Go function)

### Endpoint
N/A

### Parameters
None.

### Request Example
```go
opts := yaml.WithV2Defaults()
```

### Response
#### Success Response
- **Option** - The v2 default option.

#### Response Example
N/A

```

--------------------------------

### scan-error test example

Source: https://github.com/yaml/go-yaml/blob/main/internal/libyaml/README.md

Verifies error detection for an invalid character. The test expects an error to be raised.

```yaml
- scan-error:
    name: Invalid character
    yaml: "\x01"
```

--------------------------------

### Build selection options file for make cli

Source: https://github.com/yaml/go-yaml/blob/main/docs/plugins.md

YAML options file for `make cli CONFIG=options.yaml` that compiles the `limit` and `json-comments` plugins and embeds the file as the default configuration. The resulting `./go-yaml -j input.yaml` uses these settings automatically; the configuration file is no longer needed at runtime and edits require a rebuild.

```yaml
plugin:
  limit:
    depth: 50
    alias: 100
  json-comments: {}

```

--------------------------------

### parse-error test example

Source: https://github.com/yaml/go-yaml/blob/main/internal/libyaml/README.md

Verifies error detection for invalid YAML syntax. The test expects an error to be raised.

```yaml
- parse-error:
    name: Error state
    yaml: |
      key: : invalid
```

--------------------------------

### NewFromYAML(cfg map[string]any) (*Plugin, error)

Source: https://github.com/yaml/go-yaml/blob/main/_autodocs/api-reference/plugins.md

Creates a plugin from a configuration map. The keys 'depth' and 'alias' can be integers or null to disable the check. Unknown keys or wrong types produce errors.

```APIDOC
## NewFromYAML(cfg map[string]any) (*Plugin, error)

### Description
Creates a plugin from a configuration map. The keys 'depth' and 'alias' can be integers or null to disable the check. Unknown keys or wrong types produce errors.

### Signature
```go
func NewFromYAML(cfg map[string]any) (*Plugin, error)
```

### Parameters
- **cfg** (map[string]any) - Required - Configuration map with optional 'depth' and 'alias' keys.

### Returns
- **\*Plugin** - A new plugin instance.
- **error** - Returns an error if the configuration is invalid.

### Errors
- `limit: unknown key %q` - Returned when an unknown key is present in the config map.
- `limit: depth must be int or null, got %T` - Returned when the 'depth' key has an invalid type.
```

--------------------------------

### Streaming with options

Source: https://github.com/yaml/go-yaml/blob/main/example/README.md

Create loaders and dumpers with options for known fields, single document, and custom indentation. Demonstrates the NewLoader and NewDumper APIs. The Load and Dump calls are separate steps but part of one code block.

```go
// Load with options
loader, _ := yaml.NewLoader(reader,
    yaml.WithKnownFields(),
    yaml.WithSingleDocument(),
)
loader.Load(&config)

// Dump with options
dumper, _ := yaml.NewDumper(writer,
    yaml.WithIndent(2),
)
dumper.Dump(&config)
dumper.Close()
```

--------------------------------

### Iterate documents with Loader.Load

Source: https://github.com/yaml/go-yaml/blob/main/_autodocs/api-reference/load-dump.md

Example of using Loader.Load in a loop to read multiple documents from a stream, handling io.EOF.

```go
loader, err := yaml.NewLoader(strings.NewReader("a: 1\n---\na: 2\n"))
if err != nil { log.Fatal(err) }
for {
    var doc map[string]int
    err := loader.Load(&doc)
    if errors.Is(err, io.EOF) { break }
    if err != nil { log.Fatal(err) }
    fmt.Println(doc)
}
```

--------------------------------

### Usage with yaml.Load and WithPlugin

Source: https://github.com/yaml/go-yaml/blob/main/_autodocs/api-reference/plugins.md

Example of using the json-comments plugin with yaml.Load and yaml.WithPlugin to parse YAML with JSON-style comments.

```APIDOC
## Usage with yaml.Load and WithPlugin

### Description
Example of using the json-comments plugin with yaml.Load and yaml.WithPlugin to parse YAML with JSON-style comments.

### Method
Load

### Endpoint
N/A (Go function)

### Parameters
- **data** ([]byte) - Required - The YAML document bytes.
- **value** (any) - Required - The target variable to unmarshal into.
- **opts** (...yaml.Option) - Optional - Options such as yaml.WithPlugin.

### Request Example
```go
var value any
err := yaml.Load([]byte("a: true // comment\n"), &value,
    yaml.WithPlugin(jsoncomments.New()))
```

### Response
- **error** - An error if loading fails.

### Usage Example
```go
var value any
err := yaml.Load([]byte("a: true // comment\n"), &value,
    yaml.WithPlugin(jsoncomments.New()))
```
```
Tokens:
Raw