toml

Documentation

Overview

Package toml provides TOML binding support for the binding package.

This package extends rivaas.dev/binding with TOML serialization support, using github.com/BurntSushi/toml for parsing.

Example:

type Config struct {
    Title   string `toml:"title"`
    Port    int    `toml:"port"`
    Debug   bool   `toml:"debug"`
}

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

Index

• func FromTOML(body []byte, opts ...Option) binding.Option
• func FromTOMLReader(r io.Reader, opts ...Option) binding.Option
• func TOML[T any](body []byte, opts ...Option) (T, error)
• func TOMLReader[T any](r io.Reader, opts ...Option) (T, error)
• func TOMLReaderTo(r io.Reader, out any, opts ...Option) error
• func TOMLTo(body []byte, out any, opts ...Option) error
• type Metadata
  • func TOMLWithMetadata[T any](body []byte, opts ...Option) (T, Metadata, error)
• type Option

Examples

• TOML
• TOML (ArrayOfTables)
• TOML (Arrays)
• TOML (InlineTable)
• TOML (NestedTables)
• TOMLReader
• TOMLTo
• TOMLWithMetadata

Functions

func FromTOML

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

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

Example:

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

func FromTOMLReader

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

FromTOMLReader returns a binding.Option that specifies TOML from io.Reader as a binding source.

Example:

req, err := binding.Bind[Request](
    toml.FromTOMLReader(r.Body),
)

func TOML

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

TOML binds TOML bytes to type T.

Example:

config, err := toml.TOML[Config](body)

Example

ExampleTOML demonstrates basic TOML binding.

package main

import (
	"fmt"

	"rivaas.dev/binding/toml"
)

func main() {
	type Config struct {
		Title   string `toml:"title"`
		Version string `toml:"version"`
		Debug   bool   `toml:"debug"`
	}

	body := []byte(`
title = "My App"
version = "1.0.0"
debug = true
`)

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

	_, _ = fmt.Printf("Title: %s, Version: %s, Debug: %v\n", config.Title, config.Version, config.Debug)
}

Output:
Title: My App, Version: 1.0.0, Debug: true

Example (ArrayOfTables)

ExampleTOML_arrayOfTables demonstrates binding TOML array of tables.

package main

import (
	"fmt"

	"rivaas.dev/binding/toml"
)

func main() {
	type Product struct {
		Name  string `toml:"name"`
		Price int    `toml:"price"`
	}

	type Catalog struct {
		Products []Product `toml:"products"`
	}

	body := []byte(`
[[products]]
name = "Widget"
price = 100

[[products]]
name = "Gadget"
price = 200
`)

	catalog, err := toml.TOML[Catalog](body)
	if err != nil {
		_, _ = fmt.Printf("Error: %v\n", err)
		return
	}

	_, _ = fmt.Printf("Products: %d items\n", len(catalog.Products))
	_, _ = fmt.Printf("First: %s ($%d)\n", catalog.Products[0].Name, catalog.Products[0].Price)
}

Output:
Products: 2 items
First: Widget ($100)

Example (Arrays)

ExampleTOML_arrays demonstrates binding TOML arrays.

package main

import (
	"fmt"

	"rivaas.dev/binding/toml"
)

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

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

	config, err := toml.TOML[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 8082]

Example (InlineTable)

ExampleTOML_inlineTable demonstrates binding TOML inline tables.

package main

import (
	"fmt"

	"rivaas.dev/binding/toml"
)

func main() {
	type Point struct {
		X int `toml:"x"`
		Y int `toml:"y"`
	}

	type Config struct {
		Origin Point `toml:"origin"`
	}

	body := []byte(`
origin = { x = 10, y = 20 }
`)

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

	_, _ = fmt.Printf("Origin: (%d, %d)\n", config.Origin.X, config.Origin.Y)
}

Output:
Origin: (10, 20)

Example (NestedTables)

ExampleTOML_nestedTables demonstrates binding nested TOML tables.

package main

import (
	"fmt"

	"rivaas.dev/binding/toml"
)

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

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

	type Config struct {
		Title    string   `toml:"title"`
		Server   Server   `toml:"server"`
		Database Database `toml:"database"`
	}

	body := []byte(`
title = "My Service"

[server]
host = "0.0.0.0"
port = 8080

[database]
host = "localhost"
port = 5432
`)

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

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

Output:
Title: My Service, Server: 0.0.0.0:8080, DB: localhost:5432

func TOMLReader

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

TOMLReader binds TOML from an io.Reader to type T.

Example:

config, err := toml.TOMLReader[Config](r.Body)

Example

ExampleTOMLReader demonstrates binding from an io.Reader.

package main

import (
	"bytes"
	"fmt"

	"rivaas.dev/binding/toml"
)

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

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

	db, err := toml.TOMLReader[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 TOMLReaderTo

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

TOMLReaderTo binds TOML from an io.Reader to out.

Example:

var config Config
err := toml.TOMLReaderTo(r.Body, &config)

func TOMLTo

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

TOMLTo binds TOML bytes to out.

Example:

var config Config
err := toml.TOMLTo(body, &config)

Example

ExampleTOMLTo demonstrates non-generic TOML binding.

package main

import (
	"fmt"

	"rivaas.dev/binding/toml"
)

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

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

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

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

Output:
Server: localhost:8080

Types

type Metadata

type Metadata = toml.MetaData

Metadata holds information about undecoded keys.

func TOMLWithMetadata

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

TOMLWithMetadata binds TOML bytes to type T and returns metadata. The metadata contains information about which keys were decoded.

Example:

config, meta, err := toml.TOMLWithMetadata[Config](body)
if len(meta.Undecoded()) > 0 {
    log.Printf("Unknown keys: %v", meta.Undecoded())
}

Example

ExampleTOMLWithMetadata demonstrates accessing TOML metadata.

package main

import (
	"fmt"

	"rivaas.dev/binding/toml"
)

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

	body := []byte(`
name = "myapp"
unknown = "ignored"
`)

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

	_, _ = fmt.Printf("Name: %s\n", config.Name)
	_, _ = fmt.Printf("Undecoded keys: %v\n", meta.Undecoded())
}

Output:
Name: myapp
Undecoded keys: [unknown]

type Option

type Option func(*config)

Option configures TOML binding behavior.