confr

Documentation

Overview

Package confr provides a simple but yet powerful configuration loader.

Features:

1. Load from command line flags defined by field tag `flag`;

2. Load by custom loader function for fields which have a `custom` tag, this is useful where you may have configuration values stored in a centric repository or a remote config center;

3. Load from environment variables by explicitly defined `env` tag or auto-generated names implicitly;

4. Load from multiple configuration fields with priority and overriding;

5. Set default values by field tag `default` if a configuration field is not given by any of the higher priority source;

6. Minimal dependency;

You may check Config and Loader for more details.

Index

• Constants
• func Load(dst any, files ...string) error
• type Config
• type Loader
  • func New(config *Config) *Loader
  • func (p *Loader) Load(dst any, files ...string) error

Constants

const (
	ConfrTag        = "confr"
	CustomTag       = "custom"
	DefaultValueTag = "default"
	EnvTag          = "env"
	FlagTag         = "flag"
)

const DefaultEnvPrefix = "Confr"

Functions

func Load

func Load(dst any, files ...string) error

Load creates a Loader with nil config and loads configuration to dst, it is a shortcut for New(nil).Load(dst, files...).

Types

type Config

type Config struct {

	// LogFunc specifies a log function to use instead of [log.Printf].
	LogFunc func(format string, v ...any)

	// Verbose tells the loader to output verbose logging messages.
	Verbose bool

	// DisallowUnknownFields causes the loader to return an error when
	// the configuration files contain object keys which do not match
	// the given destination struct.
	DisallowUnknownFields bool

	// EnableImplicitEnv enables the loader checking auto-generated names
	// to find environment variables.
	// The default is false, which means the loader will only check `env`
	// tag, won't check auto-generated names.
	EnableImplicitEnv bool

	// EnvPrefix is used to prefix the auto-generated names to find
	// environment variables. The default value is "Confr".
	EnvPrefix string

	// CustomLoader optionally loads fields which have a `custom` tag,
	// the field's type and the tag value will be passed to the custom loader.
	CustomLoader func(typ reflect.Type, tag string) (any, error)

	// UnmarshalFunc optionally specifies an unmarshal function
	// to use instead of the default function.
	UnmarshalFunc func(data []byte, v any, disallowUnknownFields bool) error

	// FlagSet optionally specifies a flag set to lookup flag value
	// for fields which have a `flag` tag. The tag value should be the
	// flag name to lookup for.
	FlagSet *flag.FlagSet
}

Config provides options to configure the behavior of Loader.

type Loader

type Loader struct {
	*Config
}

Loader is used to load configuration from files (JSON/TOML/YAML), environment variables, command line flags, or by custom loader function.

The priority in descending order is:

1. command line flag defined by field tag `flag`;

2. custom loader function defined by field tag `custom`;

3. environment variables;

4. config files, if multiple files are given to Load, files appeared first takes higher priority, if a config field appears in more than one files, only the first has effect.

5. default values defined by field tag `default`;

func New

func New(config *Config) *Loader

New creates a new Loader.

func (*Loader) Load

func (p *Loader) Load(dst any, files ...string) error

Load loads configuration to dst using the Loader's Config and the given configuration files.

See Loader and Config for detailed document.