yaml

Documentation

Overview

Package yaml provides YAML binding support for the binding package.

This package extends rivaas.dev/binding with YAML serialization support, using gopkg.in/yaml.v3 for parsing.

Example:

type Config struct {
    Name    string `yaml:"name"`
    Port    int    `yaml:"port"`
    Debug   bool   `yaml:"debug"`
}

config, err := yaml.YAML[Config](body)
if err != nil {
    // handle error
}

Index

• func FromYAML(body []byte, opts ...Option) binding.Option
• func FromYAMLReader(r io.Reader, opts ...Option) binding.Option
• func YAML[T any](body []byte, opts ...Option) (T, error)
• func YAMLReader[T any](r io.Reader, opts ...Option) (T, error)
• func YAMLReaderTo(r io.Reader, out any, opts ...Option) error
• func YAMLTo(body []byte, out any, opts ...Option) error
• type Option
  • func WithStrict() Option
  • func WithValidator(v binding.Validator) Option

Examples

• YAML
• YAML (Arrays)
• YAML (Maps)
• YAML (NestedStructs)
• YAML (WithStrict)
• YAML (WithValidator)
• YAMLReader
• YAMLTo

Functions

func FromYAML

func FromYAML(body []byte, opts ...Option) binding.Option

FromYAML returns a binding.Option that specifies YAML body as a binding source. This can be used with binding.Bind for multi-source binding.

Note: When using FromYAML, the YAML binding is handled specially in the multi-source binding flow. See binding.Bind documentation.

Example:

req, err := binding.Bind[Request](
    binding.FromQuery(r.URL.Query()),
    yaml.FromYAML(body),
)

func FromYAMLReader

func FromYAMLReader(r io.Reader, opts ...Option) binding.Option

FromYAMLReader returns a binding.Option that specifies YAML from io.Reader as a binding source.

Example:

req, err := binding.Bind[Request](
    yaml.FromYAMLReader(r.Body),
)

func YAML

func YAML[T any](body []byte, opts ...Option) (T, error)

YAML binds YAML bytes to type T.

Example:

config, err := yaml.YAML[Config](body)

// With options
config, err := yaml.YAML[Config](body, yaml.WithStrict())

Example

ExampleYAML demonstrates basic YAML binding.

package main

import (
	"fmt"

	"rivaas.dev/binding/yaml"
)

func main() {
	type Config struct {
		Name  string `yaml:"name"`
		Port  int    `yaml:"port"`
		Debug bool   `yaml:"debug"`
	}

	body := []byte(`
name: myapp
port: 8080
debug: true
`)

	config, err := yaml.YAML[Config](body)
	if err != nil {
		fmt.Printf("Error: %v\n", err)
		return
	}

	fmt.Printf("Name: %s, Port: %d, Debug: %v\n", config.Name, config.Port, config.Debug)
}

Output:
Name: myapp, Port: 8080, Debug: true

Example (Arrays)

ExampleYAML_arrays demonstrates binding YAML arrays.

package main

import (
	"fmt"

	"rivaas.dev/binding/yaml"
)

func main() {
	type Config struct {
		Hosts []string `yaml:"hosts"`
		Ports []int    `yaml:"ports"`
	}

	body := []byte(`
hosts:
  - host1.example.com
  - host2.example.com
ports:
  - 8080
  - 8081
`)

	config, err := yaml.YAML[Config](body)
	if err != nil {
		fmt.Printf("Error: %v\n", err)
		return
	}

	fmt.Printf("Hosts: %v, Ports: %v\n", config.Hosts, config.Ports)
}

Output:
Hosts: [host1.example.com host2.example.com], Ports: [8080 8081]

Example (Maps)

ExampleYAML_maps demonstrates binding YAML maps.

package main

import (
	"fmt"

	"rivaas.dev/binding/yaml"
)

func main() {
	type Config struct {
		Settings map[string]string `yaml:"settings"`
	}

	body := []byte(`
settings:
  log_level: debug
  environment: production
  region: us-east-1
`)

	config, err := yaml.YAML[Config](body)
	if err != nil {
		fmt.Printf("Error: %v\n", err)
		return
	}

	fmt.Printf("Log Level: %s\n", config.Settings["log_level"])
}

Output:
Log Level: debug

Example (NestedStructs)

ExampleYAML_nestedStructs demonstrates binding nested YAML structures.

package main

import (
	"fmt"

	"rivaas.dev/binding/yaml"
)

func main() {
	type Database struct {
		Host string `yaml:"host"`
		Port int    `yaml:"port"`
	}

	type Server struct {
		Host string `yaml:"host"`
		Port int    `yaml:"port"`
	}

	type Config struct {
		App      string   `yaml:"app"`
		Server   Server   `yaml:"server"`
		Database Database `yaml:"database"`
	}

	body := []byte(`
app: myservice
server:
  host: 0.0.0.0
  port: 8080
database:
  host: localhost
  port: 5432
`)

	config, err := yaml.YAML[Config](body)
	if err != nil {
		fmt.Printf("Error: %v\n", err)
		return
	}

	fmt.Printf("App: %s, Server: %s:%d, DB: %s:%d\n",
		config.App,
		config.Server.Host, config.Server.Port,
		config.Database.Host, config.Database.Port)
}

Output:
App: myservice, Server: 0.0.0.0:8080, DB: localhost:5432

Example (WithStrict)

ExampleYAML_withStrict demonstrates strict YAML parsing.

package main

import (
	"fmt"

	"rivaas.dev/binding/yaml"
)

func main() {
	type Config struct {
		Name string `yaml:"name"`
	}

	// YAML with only known fields
	body := []byte(`name: myapp`)

	config, err := yaml.YAML[Config](body, yaml.WithStrict())
	if err != nil {
		fmt.Printf("Error: %v\n", err)
		return
	}

	fmt.Printf("Name: %s\n", config.Name)
}

Output:
Name: myapp

Example (WithValidator)

ExampleYAML_withValidator demonstrates YAML binding with validation.

package main

import (
	"fmt"

	"rivaas.dev/binding/yaml"
)

func main() {
	type Config struct {
		Name string `yaml:"name"`
		Port int    `yaml:"port"`
	}

	body := []byte(`
name: myapp
port: 8080
`)

	// Create a simple validator
	validator := &simpleValidator{}

	config, err := yaml.YAML[Config](body, yaml.WithValidator(validator))
	if err != nil {
		fmt.Printf("Error: %v\n", err)
		return
	}

	fmt.Printf("Name: %s, Port: %d\n", config.Name, config.Port)
}

// simpleValidator is a test validator for examples.
type simpleValidator struct{}

func (v *simpleValidator) Validate(data any) error {
	return nil
}

Output:
Name: myapp, Port: 8080

func YAMLReader

func YAMLReader[T any](r io.Reader, opts ...Option) (T, error)

YAMLReader binds YAML from an io.Reader to type T.

Example:

config, err := yaml.YAMLReader[Config](r.Body)

Example

ExampleYAMLReader demonstrates binding from an io.Reader.

package main

import (
	"bytes"
	"fmt"

	"rivaas.dev/binding/yaml"
)

func main() {
	type Database struct {
		Host     string `yaml:"host"`
		Port     int    `yaml:"port"`
		Database string `yaml:"database"`
	}

	body := bytes.NewReader([]byte(`
host: db.example.com
port: 5432
database: mydb
`))

	db, err := yaml.YAMLReader[Database](body)
	if err != nil {
		fmt.Printf("Error: %v\n", err)
		return
	}

	fmt.Printf("Database: %s@%s:%d\n", db.Database, db.Host, db.Port)
}

Output:
Database: mydb@db.example.com:5432

func YAMLReaderTo

func YAMLReaderTo(r io.Reader, out any, opts ...Option) error

YAMLReaderTo binds YAML from an io.Reader to out.

Example:

var config Config
err := yaml.YAMLReaderTo(r.Body, &config)

func YAMLTo

func YAMLTo(body []byte, out any, opts ...Option) error

YAMLTo binds YAML bytes to out.

Example:

var config Config
err := yaml.YAMLTo(body, &config)

Example

ExampleYAMLTo demonstrates non-generic YAML binding.

package main

import (
	"fmt"

	"rivaas.dev/binding/yaml"
)

func main() {
	type Server struct {
		Host string `yaml:"host"`
		Port int    `yaml:"port"`
	}

	body := []byte(`
host: localhost
port: 3000
`)

	var server Server
	err := yaml.YAMLTo(body, &server)
	if err != nil {
		fmt.Printf("Error: %v\n", err)
		return
	}

	fmt.Printf("Host: %s, Port: %d\n", server.Host, server.Port)
}

Output:
Host: localhost, Port: 3000

Types

type Option

type Option func(*config)

Option configures YAML binding behavior.

func WithStrict

func WithStrict() Option

WithStrict enables strict YAML parsing. When enabled, unknown fields will cause an error.

func WithValidator

func WithValidator(v binding.Validator) Option

WithValidator integrates external validation. The validator is called after successful binding.