configger

README

configger

This Go package handles loading of configuration from the following sources:

• Flags
• A configuration file
• Environment variables

Underneath this uses github.com/knadh/koanf to handle this process, however this package is opinionated as follows:

• Command line flags are via github.com/spf13/pflag
• Configuration file support is YAML
• The order of loading keys is as follows with values from higher levels overriding lower ones:
  1. Defaults from command line flags
  2. Configuration file
  3. Environment variables
  4. Command line flags
• The returned configger.Config does not provide access to the underlying *koanf.Koanf type and does not implement all of its functionality.

If you require more flexibility than provided above it is recommended to use github.com/knadh/koanf directly.

Usage

Basic usage is shown below:

package main

import (
	"fmt"
	"os"

	"github.com/andrewheberle/configger"
	"github.com/spf13/pflag"
)

func main() {
	// set up a flagset and parse flags
	f := pflag.NewFlagSet("my-command", pflag.ContinueOnError)
	f.String("config", "", "path to configuration file")
	f.String("foo", "default-foo", "foo flag")
	f.String("bar", "default-bar", "bar flag")
	if err := f.Parse(os.Args[1:]); err != nil {
		panic(err)
	}

	config, err := configger.LoadConfig(f)
	if err != nil {
		panic(err)
	}

	fmt.Printf("foo: %s; bar: %s\n", config.String("foo"), config.String("bar"))
}

Documentation

Index

• Constants
• type Config
  • func LoadConfig(f *pflag.FlagSet, opts ...Option) (Config, error)
• type Option
  • func WithConfigKeyName(key string) Option
  • func WithEnvPrefix(prefix string) Option
  • func WithoutConfigurationFile() Option

Examples

• LoadConfig (WithConfig)
• LoadConfig (WithoutConfig)
• WithEnvPrefix

Constants

const (
	DefaultConfigKeyName = "config"
)

Types

type Config

type Config interface {
	Bool(key string) bool
	Bools(key string) []bool
	BoolMap(key string) map[string]bool
	Duration(key string) time.Duration
	Float64(key string) float64
	Float64s(key string) []float64
	Float64Map(key string) map[string]float64
	Int(key string) int
	Ints(key string) []int
	IntMap(key string) map[string]int
	Int64(key string) int64
	Int64s(key string) []int64
	Int64Map(key string) map[string]int64
	String(key string) string
	Strings(key string) []string
	StringMap(key string) map[string]string
}

Config represents a configuration source.

func LoadConfig

func LoadConfig(f *pflag.FlagSet, opts ...Option) (Config, error)

Returns a Config by reading a YAML based configuration file, environment variables and command line flags.

The configuration file is loaded based on the WithConfigKeyName or the default of DefaultConfigKeyName being set in the provided pflag.FlagSet. Loading of a configuration file can be disabled via WithoutConfigurationFile, via WithConfigKeyName as a blank string or loading will be skipped if the value from the config key name is blank or unset.

If WithEnvPrefix is provided then enviroment variables prefixed with "PREFIX_" will be included in the configuration.

Example (WithConfig)

package main

import (
	"fmt"

	"github.com/andrewheberle/configger"
	"github.com/spf13/pflag"
)

func main() {
	// set up a flagset and parse flags
	f := pflag.NewFlagSet("example", pflag.ContinueOnError)
	f.String("config", "", "path to configuration file")
	f.String("foo", "default-foo", "foo flag")
	f.String("bar", "default-bar", "bar flag")
	f.StringSlice("baz", []string{"default-baz"}, "baz flag")
	if err := f.Parse([]string{"--config", "testdata/config.yml"}); err != nil {
		panic(err)
	}

	config, err := configger.LoadConfig(f)
	if err != nil {
		panic(err)
	}

	baz := config.Strings("baz")
	fmt.Printf("foo: %s; bar: %s; baz: %s; len(baz): %d\n", config.String("foo"), config.String("bar"), baz, len(baz))
}

Output:
foo: file-foo; bar: file-bar; baz: [default-baz]; len(baz): 1

Example (WithoutConfig)

package main

import (
	"fmt"

	"github.com/andrewheberle/configger"
	"github.com/spf13/pflag"
)

func main() {
	// set up a flagset and parse flags
	f := pflag.NewFlagSet("example", pflag.ContinueOnError)
	f.String("config", "", "path to configuration file")
	f.String("foo", "default-foo", "foo flag")
	f.String("bar", "default-bar", "bar flag")
	f.StringSlice("baz", []string{"default-baz"}, "baz flag")
	if err := f.Parse([]string{"--foo", "flag-foo"}); err != nil {
		panic(err)
	}

	config, err := configger.LoadConfig(f)
	if err != nil {
		panic(err)
	}

	baz := config.Strings("baz")
	fmt.Printf("foo: %s; bar: %s; baz: %s; len(baz): %d\n", config.String("foo"), config.String("bar"), baz, len(baz))
}

Output:
foo: flag-foo; bar: default-bar; baz: [default-baz]; len(baz): 1

type Option

type Option func(*options)

Option is used to modify the behaviour of LoadConfig.

func WithConfigKeyName

func WithConfigKeyName(key string) Option

Sets a specific key name to lookup the configuration file name from.

func WithEnvPrefix

func WithEnvPrefix(prefix string) Option

Set the prefix for environment variable loading.

Example

package main

import (
	"fmt"
	"os"

	"github.com/andrewheberle/configger"
	"github.com/spf13/pflag"
)

func main() {
	// set up a flagset and parse flags
	f := pflag.NewFlagSet("example", pflag.ContinueOnError)
	f.String("config", "", "path to configuration file")
	f.String("foo", "default-foo", "foo flag")
	f.String("bar", "default-bar", "bar flag")
	f.StringSlice("baz", []string{"default-baz"}, "baz flag")
	if err := f.Parse([]string{"--baz", "flag-baz-a,flag-baz-b"}); err != nil {
		panic(err)
	}

	// set an env var
	if err := os.Setenv("TEST_FOO", "env-foo"); err != nil {
		panic(err)
	}
	defer func() {
		_ = os.Unsetenv("TEST_FOO")
	}()

	// load config
	config, err := configger.LoadConfig(f, configger.WithEnvPrefix("test"))
	if err != nil {
		panic(err)
	}

	baz := config.Strings("baz")
	fmt.Printf("foo: %s; bar: %s; baz: %s; len(baz): %d\n", config.String("foo"), config.String("bar"), baz, len(baz))
}

Output:
foo: env-foo; bar: default-bar; baz: [flag-baz-a flag-baz-b]; len(baz): 2

func WithoutConfigurationFile

func WithoutConfigurationFile() Option

Explicitly disable configuration file loading.