A friendlier viper.

go get snai.pe/boa

Boa aims to be a simple, human-focused, no-dependency configuration management library.

It supports JSON5 and TOML.

Configurations are expressed as Go types, using struct field tags to map configuration files to type-safe data types.

For instance, the following TOML configuration file:

[person]
first-name = "John"
last-name = "Doe"
dob = 1953-02-25T00:00:42-08:00

Can be loaded into this Go type:

type Config struct {
  Person struct {
    FirstName string
    LastName  string
    Birth     time.Time `name:"dob"`
  } `naming:"kebab-case"`
}

At the time of writing, none of the other configuration parsers are actually designed for configuration. Most of the standard parsers under the encoding package are designed for robots. Non-standard parsers either do not follow the same semantics as the standard packages, or suffer the same flaws as standard parsers. Comments and formatting are usually not parsed nor preserved. Encoders interact poorly with other encoders, usually necessitating multiple struct tags per configuration language, or do not provide a good interface for accessing and discovering configuration values.

Boa aims to be an overall better configuration management library. It has no dependencies outside of the standard Go library, and provides a unified way to load, manipulate, and save configurations.

The following languages are supported:

• JSON5
• TOML

In addition, all configuration parsers have the following properties:

• Error messages contain the filename when available as well as the line and column number where the error occured.
• Parsers support the same set of base struct tags for consistency and conciseness.
• Comments and whitespace are preserved by the parsers in the configuration AST, which makes it possible to edit configuration while still preserving the style of the original file.

Any type that implements encoding.TextMarshaler can be saved as a string. Any type that implements encoding.TextUnmarshaler can be loaded from a string.

In addition, the following standard library types are marshaled and unmarshaled as the appropriate type:

Some packages also define or support some specialized types for specific configuration objects:

package main

import (
	"fmt"
	"log"

	"snai.pe/boa"
)

func main() {

	var config struct {
		Answer   int               `help:"This is an important field that needs to be 42"`
		Primes   []int             `help:"Some prime numbers"`
		Contacts map[string]string `help:"Some people in my contact list"`
	}

	// Will load any matching "appname.toml" config file from the system config path,
	// then the user config path. The TOML decoder is inferred from the .toml extension.
	//
	// For instance, on Linux, this will load in order:
	//     - /etc/<appname>.toml
	//     - /etc/xdg/<appname>.toml
	//     - ~/.config/<appname>.toml
	//
	if err := boa.Load("appname", &config); err != nil {
		log.Fatalln(err)
	}

}

Configuration defaults are not, by design, set via struct tags or other field-specific mechanisms.

Instead, write a default configuration file in your package, and embed it. Multiple configs defaults can be embedded into the same embed.FS declaration -- see the documentation of the embed package.

package main

import (
	"embed"
	"fmt"
	"log"

	"snai.pe/boa"
)

//go:embed appname.toml
var defaults embed.FS

func main() {

	// Register defaults
	boa.SetDefaults(defaults)

	var config struct {
		Answer   int               `help:"This is an important field that needs to be 42"`
		Primes   []int             `help:"Some prime numbers"`
		Contacts map[string]string `help:"Some people in my contact list"`
	}

	if err := boa.Load("appname", &config); err != nil {
		log.Fatalln(err)
	}

}

Good configuration defaults should be consistent and self-explanatory. Consider making the default for fields their respective type's zero value.

Configuration fields can be explicitly bound to environment variables via the env struct tag:

type Config struct {
	Shell string   `env:"SHELL"`
	Path  []string `env:"PATH"`
}

Environment values are generally parsed according to the strconv Parse functions, or using UnmarshalText if the field's type implements encoding.TextUnmarshaler.

Slices and arrays are parsed as a path-list-separated list of strings. The delimiter is os.PathListSeparator: with the above example, on Unix derivatives, PATH=a:b:c would get unmarshaled as [a, b, c], while on Windows the value would need to be PATH=a;b;c.

Fields with no env tag are not populated from the environment, unless the AutomaticEnv option is provided:

type Config struct {
	ImplicitVariable string
}

boa.SetOptions(
	boa.AutomaticEnv("PREFIX"),
)

In this example, PREFIX_IMPLICIT_VARIABLE=value would set Config.ImplicitVariable.

Logo made by Irina Mir