or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

basic-operations.mdcustom-serialization.mdindex.mdnode-manipulation.mdstreaming-operations.md
tile.json

tessl/golang-gopkg-in--yaml-v3

YAML support for the Go language

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
golangpkg:golang/gopkg.in/yaml.v3@3.0.x

To install, run

npx @tessl/cli install tessl/golang-gopkg-in--yaml-v3@3.0.0

index.mddocs/

gopkg.in/yaml.v3

YAML support for the Go language, providing comprehensive encoding and decoding capabilities for YAML documents with support for most of YAML 1.2 specification while maintaining backwards compatibility with YAML 1.1.

Package Information

  • Package Name: gopkg.in/yaml.v3
  • Package Type: Go module
  • Language: Go
  • Installation: go get gopkg.in/yaml.v3
  • Import Path: gopkg.in/yaml.v3

Core Imports

import "gopkg.in/yaml.v3"

For type-specific imports:

import (
    "gopkg.in/yaml.v3"
)

// Use qualified names:
// yaml.Marshal()
// yaml.Unmarshal()
// yaml.Node{}

Basic Usage

Simple marshaling and unmarshaling:

package main

import (
    "fmt"
    "log"
    "gopkg.in/yaml.v3"
)

type Config struct {
    Name    string
    Version int
    Options struct {
        Debug   bool
        Timeout int `yaml:"timeout"`
    }
}

func main() {
    // Unmarshal YAML data
    data := []byte(`
name: MyApp
version: 2
options:
  debug: true
  timeout: 30
`)

    var config Config
    err := yaml.Unmarshal(data, &config)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Config: %+v\n", config)

    // Marshal to YAML
    output, err := yaml.Marshal(&config)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("YAML output:\n%s", output)
}

Capabilities

Basic YAML Operations

Core functionality for encoding and decoding YAML documents with simple function calls.

func Marshal(in interface{}) (out []byte, err error)
func Unmarshal(in []byte, out interface{}) (err error)

Basic YAML Operations

Streaming YAML Operations

Stream-based encoding and decoding for processing multiple YAML documents or working with io.Reader/io.Writer interfaces.

func NewDecoder(r io.Reader) *Decoder

type Decoder struct {
    // Has unexported fields
}

func (dec *Decoder) Decode(v interface{}) (err error)
func (dec *Decoder) KnownFields(enable bool)
func NewEncoder(w io.Writer) *Encoder

type Encoder struct {
    // Has unexported fields
}

func (e *Encoder) Encode(v interface{}) (err error)
func (e *Encoder) SetIndent(spaces int)
func (e *Encoder) Close() (err error)

Streaming YAML Operations

Node Manipulation

Low-level AST manipulation for fine-grained control over YAML document structure, comments, and formatting.

type Node struct {
    Kind        Kind
    Style       Style
    Tag         string
    Value       string
    Anchor      string
    Alias       *Node
    Content     []*Node
    HeadComment string
    LineComment string
    FootComment string
    Line        int
    Column      int
}

func (n *Node) Decode(v interface{}) (err error)
func (n *Node) Encode(v interface{}) (err error)
func (n *Node) IsZero() bool
func (n *Node) LongTag() string
func (n *Node) ShortTag() string
func (n *Node) SetString(s string)

Node Manipulation

Custom Type Serialization

Interfaces for implementing custom marshaling and unmarshaling behavior for user-defined types.

type Marshaler interface {
    MarshalYAML() (interface{}, error)
}

type Unmarshaler interface {
    UnmarshalYAML(value *Node) error
}

type IsZeroer interface {
    IsZero() bool
}

Custom Type Serialization

Error Handling

TypeError

Returned when one or more fields cannot be properly decoded. Unmarshaling continues partially and returns all errors.

type TypeError struct {
    Errors []string
}

func (e *TypeError) Error() string

Common Types

Kind

Defines the type of YAML node.

type Kind uint32

const (
    DocumentNode Kind = 1 << iota
    SequenceNode
    MappingNode
    ScalarNode
    AliasNode
)

Style

Controls the rendering style of YAML nodes.

type Style uint32

const (
    TaggedStyle Style = 1 << iota
    DoubleQuotedStyle
    SingleQuotedStyle
    LiteralStyle
    FoldedStyle
    FlowStyle
)

YAML 1.1 vs 1.2 Compatibility

This package supports most of YAML 1.2 while preserving some YAML 1.1 behavior:

  • Booleans: YAML 1.1 bools (yes/no, on/off) are supported when decoding into typed bool values, otherwise treated as strings. YAML 1.2 uses true/false only.
  • Octals: Encode and decode as 0777 (YAML 1.1 format) rather than 0o777 (YAML 1.2). The 0o777 format is also supported for reading.
  • Base-60 floats: Not supported (removed in YAML 1.2).

Struct Field Tags

Control marshaling and unmarshaling behavior with struct tags:

type Example struct {
    Field1 string `yaml:"custom_name"`           // Custom YAML key
    Field2 int    `yaml:"field2,omitempty"`      // Omit if zero value
    Field3 []int  `yaml:"field3,flow"`           // Use flow style
    Field4 Data   `yaml:",inline"`               // Inline struct fields
    Field5 string `yaml:"-"`                     // Ignore field
}

Supported Flags

  • omitempty - Omit field if zero value (respects IsZeroer interface)
  • flow - Use flow style (inline) for sequences and maps
  • inline - Inline struct or map fields into parent
  • - - Ignore field completely