config

Documentation

Overview

Package config provides configuration loading and optionally validation. Config files are expected to be in TOML format.

Index

• Constants
• Variables
• func C(c any, opts ...Option) error
• func ToEnv(opts ...Option) error
• type Option
  • func DisableEnvOverwrite() Option
  • func From(filename string) Option
  • func FromDir(dir string) Option
  • func Validate(v *validator.Validate) Option
  • func WithFileExt(ext string) Option
• type Options

Constants

const Dir = "config"

Dir is the default directory for config files.

const Pkg = "sys.config"

Variables

var (
	UnexpectedErrTryingEnvOverwrite = errors.New("unexpected error trying to overwrite config with env variables")
)

Functions

func C

func C(c any, opts ...Option) error

C reads a config file of type TOML and unmarshalls it into the given config struct. C will override the config struct with a local config file if it exists. After overriding with .local.toml the config will be overwritten by environment variables as well. The C function expects parameters through Option functions, default values are provided.

If the Validate() Option is passed a validator.Validate the config struct will be validated.

Using default options the config file is expected to be located in the config/ directory. Default example: config/config.toml

The config file will be overwritten by a local config file if it exists. For the local config a "local" will be inserted between filename and file extension. Default example: config/config.local.toml

Then the config will be overwritten by environment variables. For overwriting through environment variables the struct must be annotated with the "env" tag and define the environment variables name like: `env:"ENV_VAR_NAME"`. Overwriting is done recursively, meaning that nested structs will be overwritten as well. Bools will be set to true if the env value is "true" (case-insensitive) otherwise the value will be false. Int/Float values will not be overwritten. Strings will be overwritten with the env value. Example:

type Config struct {
	Foo string `env:"FOO"`
	Bar bool   `env:"BAR"`
	Baz struct {
		Qux string `env:"QUX"`
	}
}
// env: FOO=foo BAR=true QUX=qux
// config: { Foo: "foo", Bar: true, Baz: { Qux: "qux" } }

Overwriting can be disabled by passing the DisableEnvOverwrite Option.

Errors are returned if they occur on validating the options/config, reading or unmarshalling the config file.

func ToEnv

func ToEnv(opts ...Option) error

ToEnv reads a TOML config file and loads it into the environment. As with C, the options are passed through Option functions.

The config file will be loaded recursively, meaning that nested maps will be flattened and joined with underscores. The values will be converted to strings and may be accessed through os.Getenv(<CONFIG_NAME>_<KEY>).

The Validate() has no effect on this function. As of right now there is no validation implemented for env variables loaded from config files.

Types

type Option

type Option func(*Options)

func DisableEnvOverwrite

func DisableEnvOverwrite() Option

DisableEnvOverwrite disables overwriting the config struct with environment variables.

func From

func From(filename string) Option

From sets the filename to read the config from. This Option is required.

func FromDir

func FromDir(dir string) Option

FromDir sets the directory to read the config file from.

func Validate

func Validate(v *validator.Validate) Option

Validate sets a validator.Validate to validate the config struct. Without passing a non-nil validator.Validate the config will not be validated.

func WithFileExt

func WithFileExt(ext string) Option

WithFileExt sets the file extension of the config file. (default is "toml")

type Options

type Options struct {
	// contains filtered or unexported fields
}