yaml

func WithCustomUnmarshaler ¶

func WithCustomUnmarshaler[T any](fn func(*T, []byte) error) DecodeOption

WithCustomUnmarshaler registers a function that decodes YAML bytes into a value of type T, overriding the default decoding for that type.

package main

import (
	"fmt"
	"strings"

	"github.com/go-rotini/yaml"
)

func main() {
	type IP [4]byte
	var v struct {
		Addr IP `yaml:"addr"`
	}
	err := yaml.UnmarshalWithOptions([]byte("addr: 10.0.0.1\n"), &v,
		yaml.WithCustomUnmarshaler(func(ip *IP, data []byte) error {
			s := strings.TrimSpace(string(data))
			var a, b, c, d byte
			fmt.Sscanf(s, "%d.%d.%d.%d", &a, &b, &c, &d)
			*ip = IP{a, b, c, d}
			return nil
		}),
	)
	if err != nil {
		panic(err)
	}
	fmt.Println(v.Addr)
}

Output:
[10 0 0 1]

func WithDefaults ¶ added in v1.0.5

func WithDefaults() DecodeOption

WithDefaults enables applying default values from struct tags when a YAML key is absent from the input. Default values are specified with the "default=<value>" tag option (e.g. `yaml:"port,default=8080"`). Only scalar types are supported: string, bool, int/uint variants, float variants, and time.Duration. Without this option, default tags are ignored.

func WithDisallowDuplicateKey ¶

func WithDisallowDuplicateKey() DecodeOption

WithDisallowDuplicateKey causes decoding to return a DuplicateKeyError if a mapping contains the same key more than once.

package main

import (
	"errors"
	"fmt"

	"github.com/go-rotini/yaml"
)

func main() {
	var v map[string]int
	err := yaml.UnmarshalWithOptions([]byte("a: 1\na: 2\n"), &v, yaml.WithDisallowDuplicateKey())
	fmt.Println(errors.Is(err, yaml.ErrDuplicateKey))
}

Output:
true

func WithJSONUnmarshaler ¶

func WithJSONUnmarshaler() DecodeOption

WithJSONUnmarshaler causes the decoder to try a type's UnmarshalJSON method if no YAML-specific unmarshaler is found.

func WithKYAMLLintCosmetic ¶ added in v1.2.0

func WithKYAMLLintCosmetic() DecodeOption

WithKYAMLLintCosmetic additionally enforces the cosmetic rules of KYAML: indentation, bracket cuddling, trailing commas, key ordering, and key quoting. Used primarily by linters that want to assert byte-equivalence with kubectl's KYAML output.

Has no effect unless WithStrictKYAML is also set.

func WithMaxAliasExpansion ¶

func WithMaxAliasExpansion(n int) DecodeOption

WithMaxAliasExpansion limits the total number of alias expansions during decoding (default 1000). This prevents denial-of-service via exponentially expanding aliases (the "billion laughs" attack).

package main

import (
	"fmt"

	"github.com/go-rotini/yaml"
)

func main() {
	data := []byte("a: &x [1,2]\nb: &y [*x,*x]\nc: &z [*y,*y]\nd: [*z,*z]\n")
	var v any
	err := yaml.UnmarshalWithOptions(data, &v, yaml.WithMaxAliasExpansion(1))
	fmt.Println(err != nil)
}

Output:
true

func WithMaxDepth ¶

func WithMaxDepth(n int) DecodeOption

WithMaxDepth limits the nesting depth of the decoded value (default 100). Deeply nested documents are rejected with a SyntaxError.

package main

import (
	"fmt"

	"github.com/go-rotini/yaml"
)

func main() {
	type Inner struct {
		Value int `yaml:"value"`
	}
	type Outer struct {
		Inner Inner `yaml:"inner"`
	}
	var v Outer
	err := yaml.UnmarshalWithOptions([]byte("inner:\n  value: 1\n"), &v, yaml.WithMaxDepth(100))
	if err != nil {
		panic(err)
	}
	fmt.Println(v.Inner.Value)
}

Output:
1

func WithMaxDocumentSize ¶

func WithMaxDocumentSize(n int) DecodeOption

WithMaxDocumentSize rejects input that exceeds n bytes before parsing begins.

package main

import (
	"bytes"
	"errors"
	"fmt"

	"github.com/go-rotini/yaml"
)

func main() {
	big := bytes.Repeat([]byte("a"), 1000)
	var v any
	err := yaml.UnmarshalWithOptions(big, &v, yaml.WithMaxDocumentSize(100))
	fmt.Println(errors.Is(err, yaml.ErrDocumentSize))
}

Output:
true

func WithMaxNodes ¶

func WithMaxNodes(n int) DecodeOption

WithMaxNodes limits the total number of AST nodes the parser may create. Zero means no limit.

func WithOrderedMap ¶

func WithOrderedMap() DecodeOption

WithOrderedMap causes decoding into any (interface{}) to produce MapSlice values for mappings instead of map[string]any, preserving key order.

package main

import (
	"fmt"

	"github.com/go-rotini/yaml"
)

func main() {
	var v any
	if err := yaml.UnmarshalWithOptions([]byte("b: 2\na: 1\n"), &v, yaml.WithOrderedMap()); err != nil {
		panic(err)
	}
	ms := v.(yaml.MapSlice)
	for _, item := range ms {
		fmt.Printf("%s=%v\n", item.Key, item.Value)
	}
}

Output:
b=2
a=1

func WithRecursiveDir ¶

func WithRecursiveDir(b bool) DecodeOption

WithRecursiveDir controls whether WithReferenceDirs walks subdirectories recursively. Symlinks that escape the directory root are rejected.

func WithReferenceDirs ¶

func WithReferenceDirs(dirs ...string) DecodeOption

WithReferenceDirs loads all .yaml and .yml files in the given directories and makes their anchors available for alias resolution. By default only the top level of each directory is scanned; use WithRecursiveDir to walk subdirectories.

func WithReferenceFiles ¶

func WithReferenceFiles(files ...string) DecodeOption

WithReferenceFiles loads the given YAML files and makes their anchors available for alias resolution in the primary document.

func WithSchema ¶

func WithSchema(s Schema) DecodeOption

WithSchema selects the YAML tag resolution schema. The default is CoreSchema. Use JSONSchema for JSON-compatible resolution or FailsafeSchema to treat all plain scalars as strings.

package main

import (
	"fmt"

	"github.com/go-rotini/yaml"
)

func main() {
	var v any
	if err := yaml.UnmarshalWithOptions([]byte("val: true\n"), &v, yaml.WithSchema(yaml.FailsafeSchema)); err != nil {
		panic(err)
	}
	m := v.(map[string]any)
	fmt.Printf("%T: %v\n", m["val"], m["val"])
}

Output:
string: true

func WithStrict ¶

func WithStrict() DecodeOption

WithStrict causes decoding to return an UnknownFieldError if a YAML key does not correspond to any field in the target struct.

package main

import (
	"errors"
	"fmt"

	"github.com/go-rotini/yaml"
)

func main() {
	type Config struct {
		Name string `yaml:"name"`
	}
	var cfg Config
	err := yaml.UnmarshalWithOptions([]byte("name: ok\nextra: bad\n"), &cfg, yaml.WithStrict())
	fmt.Println(errors.Is(err, yaml.ErrUnknownField))
}

Output:
true

func WithStrictKYAML ¶ added in v1.2.0

func WithStrictKYAML() DecodeOption

WithStrictKYAML rejects YAML constructs that fall outside the KYAML subset: anchors, aliases, tags, merge keys, block-style scalars/mappings/sequences, plain string scalars (except keys), single-quoted scalars, non-string keys, hex/octal/binary numeric literals, YAML 1.1 boolean aliases, .nan/.inf floats, the ? complex-key indicator, and YAML directives. Documents must begin with the "---" header.

Errors are returned as *KYAMLError carrying every violation with source positions. Use errors.Is(err, ErrKYAML) to test generically.

See KEP-5295 for the full KYAML format definition.

func WithTagResolver ¶

func WithTagResolver(resolver *TagResolver) DecodeOption

WithTagResolver registers a TagResolver that handles a custom YAML tag (e.g. "!mytype") during decoding.

package main

import (
	"fmt"
	"reflect"
	"strings"

	"github.com/go-rotini/yaml"
)

func main() {
	resolver := &yaml.TagResolver{
		Tag:    "!upper",
		GoType: reflect.TypeOf(""),
		Resolve: func(value string) (any, error) {
			return strings.ToUpper(value), nil
		},
	}
	var v map[string]string
	err := yaml.UnmarshalWithOptions([]byte("name: !upper hello\n"), &v, yaml.WithTagResolver(resolver))
	if err != nil {
		panic(err)
	}
	fmt.Println(v["name"])
}

Output:
HELLO

func WithValidator ¶

func WithValidator(v StructValidator) DecodeOption

WithValidator registers a StructValidator that is called after each struct is fully decoded.

package main

import (
	"fmt"

	"github.com/go-rotini/yaml"
)

func main() {
	type Config struct {
		Port int `yaml:"port"`
	}
	validator := validatorFunc(func(v any) error {
		if c, ok := v.(*Config); ok && c.Port < 1 {
			return fmt.Errorf("port must be positive")
		}
		return nil
	})
	var cfg Config
	err := yaml.UnmarshalWithOptions([]byte("port: 0\n"), &cfg, yaml.WithValidator(validator))
	fmt.Println(err != nil)
}

type validatorFunc func(any) error

func (f validatorFunc) Struct(v any) error { return f(v) }

Output:
true

func NewDecoder ¶

func NewDecoder(r io.Reader, opts ...DecodeOption) *Decoder

NewDecoder returns a new Decoder that reads from r.

package main

import (
	"bytes"
	"fmt"
	"io"

	"github.com/go-rotini/yaml"
)

func main() {
	data := "---\nhello: world\n---\nfoo: bar\n"
	dec := yaml.NewDecoder(bytes.NewReader([]byte(data)))
	for {
		var v map[string]string
		err := dec.Decode(&v)
		if err == io.EOF {
			break
		}
		if err != nil {
			panic(err)
		}
		fmt.Println(v)
	}
}

Output:
map[hello:world]
map[foo:bar]

func WithAutoInt ¶

func WithAutoInt(b bool) EncodeOption

WithAutoInt encodes float64 values that have no fractional part as integers (e.g. 42 instead of 42.0).

package main

import (
	"fmt"

	"github.com/go-rotini/yaml"
)

func main() {
	v := map[string]float64{"count": 42.0}
	data, _ := yaml.MarshalWithOptions(v, yaml.WithAutoInt(true))
	fmt.Print(string(data))
}

Output:
count: 42

func WithComment ¶

func WithComment(comments map[string][]Comment) EncodeOption

WithComment attaches comments to nodes by dot-path key (e.g. "server.port"). Each key maps to a slice of Comment values specifying position and text.

package main

import (
	"fmt"

	"github.com/go-rotini/yaml"
)

func main() {
	v := map[string]int{"port": 8080}
	comments := map[string][]yaml.Comment{
		"port": {{Position: yaml.LineCommentPos, Text: "server port"}},
	}
	data, _ := yaml.MarshalWithOptions(v, yaml.WithComment(comments))
	fmt.Print(string(data))
}

Output:
port: 8080 # server port

func WithCustomMarshaler ¶

func WithCustomMarshaler[T any](fn func(T) ([]byte, error)) EncodeOption

WithCustomMarshaler registers a function that encodes values of type T to YAML bytes, overriding the default encoding for that type.

package main

import (
	"fmt"

	"github.com/go-rotini/yaml"
)

func main() {
	type Hex int
	data, _ := yaml.MarshalWithOptions(
		map[string]Hex{"code": 255},
		yaml.WithCustomMarshaler(func(h Hex) ([]byte, error) {
			return fmt.Appendf(nil, "0x%X", int(h)), nil
		}),
	)
	fmt.Print(string(data))
}

Output:
code: 0xFF

func WithDurationAsString ¶ added in v1.2.0

func WithDurationAsString(b bool) EncodeOption

WithDurationAsString controls how time.Duration values are encoded. When false (the default), durations encode as int64 nanoseconds, matching encoding/json. When true, durations encode using their human-readable String() form (e.g. "1h30m") wrapped as a quoted string under KYAML mode.

The string form is more readable for config files; the int64 form is stable for machine-to-machine interchange and matches stdlib behavior.

func WithFlow ¶

func WithFlow(b bool) EncodeOption

WithFlow encodes all values in flow style (JSON-like inline notation) when set to true.

package main

import (
	"fmt"

	"github.com/go-rotini/yaml"
)

func main() {
	v := map[string][]string{"tags": {"go", "yaml"}}
	data, _ := yaml.MarshalWithOptions(v, yaml.WithFlow(true))
	fmt.Print(string(data))
}

Output:
{tags: [go, yaml]}

func WithIndent ¶

func WithIndent(n int) EncodeOption

WithIndent sets the number of spaces per indentation level (default 2).

package main

import (
	"fmt"

	"github.com/go-rotini/yaml"
)

func main() {
	v := []string{"a", "b", "c"}
	data, _ := yaml.MarshalWithOptions(v, yaml.WithIndent(4))
	fmt.Print(string(data))
}

Output:
- a
- b
- c

func WithIndentSequence ¶

func WithIndentSequence(b bool) EncodeOption

WithIndentSequence controls whether sequence items are indented relative to their parent key. When false (the default), the "- " prefix aligns with the parent's indentation level.

func WithJSON ¶

func WithJSON(b bool) EncodeOption

WithJSON enables JSON-compatible output: all strings are double-quoted, keys are quoted, and null is used instead of YAML's tilde notation.

package main

import (
	"fmt"

	"github.com/go-rotini/yaml"
)

func main() {
	v := map[string]any{"name": "test", "active": true}
	data, _ := yaml.MarshalWithOptions(v, yaml.WithJSON(true))
	fmt.Print(string(data))
}

Output:
"active": true
"name": "test"

func WithKYAML ¶ added in v1.2.0

func WithKYAML() EncodeOption

WithKYAML enables KYAML output mode, a strict subset of YAML defined by Kubernetes KEP-5295. KYAML output:

• always begins with a "---" document header
• uses flow style ({} for mappings, [] for sequences) exclusively
• double-quotes every string value with full escape handling
• quotes keys only when they are type-ambiguous (the "Norway problem")
• emits trailing commas (suppressed where brackets are cuddled)
• sorts native map keys lexicographically
• prefers the json struct tag and json.Marshaler over their yaml equivalents
• never emits anchors, aliases, tags, merge keys, or block-style scalars

KYAML is a subset of YAML 1.2.2, so output is always valid YAML.

func WithKYAMLAlwaysQuoteKeys ¶ added in v1.2.0

func WithKYAMLAlwaysQuoteKeys() EncodeOption

WithKYAMLAlwaysQuoteKeys forces double-quoting of every map and struct key under KYAML mode. Default is to quote only type-ambiguous keys.

Has no effect unless WithKYAML is also set.

func WithLineWidth ¶

func WithLineWidth(n int) EncodeOption

WithLineWidth sets the preferred line width for scalar wrapping (default 80). The encoder may exceed this width when a single word is longer than the limit.

func WithLiteralStyle ¶

func WithLiteralStyle(b bool) EncodeOption

WithLiteralStyle encodes multi-line strings as YAML literal block scalars (|) instead of quoted scalars when set to true.

package main

import (
	"fmt"

	"github.com/go-rotini/yaml"
)

func main() {
	type Msg struct {
		Text string `yaml:"text"`
	}
	v := Msg{Text: "line1\nline2\n"}
	data, _ := yaml.MarshalWithOptions(v, yaml.WithLiteralStyle(true))
	fmt.Print(string(data))
}

Output:
text: |
    line1
    line2

func WithOmitEmpty ¶

func WithOmitEmpty(b bool) EncodeOption

WithOmitEmpty omits struct fields and map entries whose values are zero/empty, equivalent to adding ",omitempty" to every field tag.

package main

import (
	"fmt"

	"github.com/go-rotini/yaml"
)

func main() {
	type Config struct {
		Name  string   `yaml:"name"`
		Tags  []string `yaml:"tags,omitempty"`
		Debug bool     `yaml:"debug,omitempty"`
	}
	data, _ := yaml.MarshalWithOptions(Config{Name: "app"}, yaml.WithOmitEmpty(true))
	fmt.Print(string(data))
}

Output:
name: app

func WithQuoteAllStrings ¶

func WithQuoteAllStrings(b bool) EncodeOption

WithQuoteAllStrings forces all string scalar values to be quoted when set to true. Mapping keys remain unquoted unless they require quoting for syntactic reasons.

func WithSingleQuote ¶

func WithSingleQuote(b bool) EncodeOption

WithSingleQuote prefers single-quoted scalars over double-quoted when the value contains no characters requiring escape sequences.

package main

import (
	"fmt"

	"github.com/go-rotini/yaml"
)

func main() {
	v := map[string]string{"name": "true"}
	data, _ := yaml.MarshalWithOptions(v, yaml.WithSingleQuote(true))
	fmt.Print(string(data))
}

Output:
name: 'true'

func NewEncoder ¶

func NewEncoder(w io.Writer, opts ...EncodeOption) *Encoder

NewEncoder returns a new Encoder that writes to w.

package main

import (
	"bytes"
	"fmt"

	"github.com/go-rotini/yaml"
)

func main() {
	var buf bytes.Buffer
	enc := yaml.NewEncoder(&buf)
	if err := enc.Encode(map[string]string{"a": "1"}); err != nil {
		panic(err)
	}
	if err := enc.Encode(map[string]string{"b": "2"}); err != nil {
		panic(err)
	}
	if err := enc.Close(); err != nil {
		panic(err)
	}
	fmt.Print(buf.String())
}

Output:
a: "1"
---
b: "2"

func Parse ¶

func Parse(data []byte) (*File, error)

Parse tokenizes and parses data into an AST. The returned File provides direct access to the document tree without decoding into Go values.

package main

import (
	"fmt"

	"github.com/go-rotini/yaml"
)

func main() {
	data := []byte("name: hello\nitems:\n  - a\n  - b\n")
	file, err := yaml.Parse(data)
	if err != nil {
		panic(err)
	}
	for _, doc := range file.Docs {
		yaml.Walk(doc, func(n *yaml.Node) bool {
			if n.Kind == yaml.ScalarNode {
				fmt.Println(n.Value)
			}
			return true
		})
	}
}

Output:
name
hello
items
a
b

func Lint ¶ added in v1.2.0

func Lint(data []byte, opts ...DecodeOption) ([]LintIssue, error)

Lint parses data as YAML and returns a slice of LintIssue values describing every KYAML deviation. Unlike ValidateKYAML, Lint always returns the full list of issues. With WithKYAMLLintCosmetic in opts, Lint additionally reports cosmetic deviations.

func Filter ¶

func Filter(n *Node, fn func(*Node) bool) []*Node

Filter walks the AST rooted at n and returns all nodes for which fn returns true.

package main

import (
	"fmt"

	"github.com/go-rotini/yaml"
)

func main() {
	file, _ := yaml.Parse([]byte("a: 1\nb: hello\nc: 3\n"))
	scalars := yaml.Filter(file.Docs[0], func(n *yaml.Node) bool {
		return n.Kind == yaml.ScalarNode
	})
	for _, s := range scalars {
		fmt.Println(s.Value)
	}
}

Output:
a
1
b
hello
c
3

func PathPointer ¶ added in v1.2.1

func PathPointer(ptr string) (*Path, error)

PathPointer compiles an RFC 6901 JSON Pointer into a Path. The empty string selects the document root; any other pointer must begin with "/". Reference tokens are unescaped per RFC 6901 ("~1" → "/", then "~0" → "~").

A JSON Pointer token can address either a mapping key or a sequence index — the document decides which — so each token compiles to a segment that resolves as a child key on a MappingNode and, when the token is a non-negative integer, as an index on a SequenceNode.

Returns ErrPointerSyntax (wrapped) when a non-empty pointer does not begin with "/".

func PathString ¶

func PathString(expr string) (*Path, error)

PathString compiles a JSONPath-like expression into a Path.

Supported syntax:

• $ root node
• .key child mapping key
• [n] sequence index (negative indexes count from the end)
• .*, [*] wildcard (all children)
• .. recursive descent

Example: "$.servers[0].host" selects the host field of the first server.

package main

import (
	"fmt"

	"github.com/go-rotini/yaml"
)

func main() {
	path, err := yaml.PathString("$.name")
	if err != nil {
		panic(err)
	}
	data := []byte("name: world\nport: 80\n")
	result, err := path.ReadString(data)
	if err != nil {
		panic(err)
	}
	fmt.Println(result)
}

Output:
world