config

README

Config

Loads configuration settings into a struct from the following sources in this order.

1. default specified in struct tag
2. config.yml YAML file
3. environment variables
4. command line parameters

Each source successively overrides the previous ones.

Nested structs are supported as each setting specifies its full path to the associated struct field.

How to Use

See the examples folder and the unit tests for how to define and consume your configuration.

Config Struct

The following config struct will contain our settings. Note the default values defined in the struct tags.

var cfg struct {
	Address string        `yaml:"address" default:"localhost"`
	Timeout time.Duration `yaml:"timeout" default:"5m"`
}

YAML File

config.yml file overrides any struct defaults.

---
address: http://example.com/
timeout: 1m

Environment Variables

Environment variables override any matching config.yml file values.

export ADDRESS=http://example.com/funapp
export TIMEOUT=1m30s

Command Line Arguments

Command line arguments override any matching environment variables.

./myapp address=http://example.com/home timeout=2m

Documentation

Index

• Variables
• func FromArguments(args []string, v interface{}) error
• func FromEnvironment(v interface{}) error
• func FromStructDefaults(v interface{}) error
• func FromYaml(yml []byte, v interface{}) error
• func FromYamlFile(path string, v interface{}) error
• func Load(file string, v interface{})
• func ToYaml(v interface{}) (string, error)
• func Unmarshal(s string, v interface{}) error
• func UnmarshalValue(s string, rv reflect.Value) error

Variables

var (
	// ErrNilPointer indicates the v parameter is a nil pointer
	ErrNilPointer = errors.New("destination parameter cannot be nil")
	// ErrCannotSetValue indicates the v parameter is not writable
	ErrCannotSetValue = errors.New("destination parameter must be writable")
	// ErrInvalidType indicates that the v parameter is not a pointer
	ErrInvalidType = errors.New("must be a pointer type")
	// ErrBadMap indicates the s parameter is not a comma separated list of key:value pairs
	ErrBadMap = errors.New("string for a map must be comma separated list of key:value")
	// ErrUnsupportedType indicates that Unmarshal doesn't support that type
	ErrUnsupportedType = errors.New("cannot unmarshal unsupported type")
)

Functions

func FromArguments

func FromArguments(args []string, v interface{}) error

FromArguments extracts settings from a list of arguments such as those supplied on the command line. All args strings must be in the form key.path=value, where key.path is a period '.' or underscore '_' separated path to the struct member.

server.address=http://example.com

func FromEnvironment

func FromEnvironment(v interface{}) error

FromEnvironment extracts settings from environment variables. We expect them to be named upper case and underscore separated.

SERVER_ADDRESS=http://example.com

func FromStructDefaults

func FromStructDefaults(v interface{}) error

FromStructDefaults initializes struct members from "default:" struc tags

func FromYaml

func FromYaml(yml []byte, v interface{}) error

FromYaml extracts settings from a YAML string.

func FromYamlFile

func FromYamlFile(path string, v interface{}) error

FromYamlFile extracts settings from a YAML file.

func Load

func Load(file string, v interface{})

Load fills in the specified struct with configuration loaded from YAML, env vars, and command line arguments. It purposely ignores any errors from attempting to load from a specific source.

func ToYaml

func ToYaml(v interface{}) (string, error)

ToYaml marshals the struc into a YAML string.

func Unmarshal

func Unmarshal(s string, v interface{}) error

Unmarshal attempts to convert string 's' into a value of type 'v'. It infers the type from v itself, and uses the appropriate conversion routine. This only supports the common basic types, slices, and maps, but not structs.

Type                                    Examples
-----------------------------------     ---------------------------------------------
string                                  "", "some string"
bool                                    "0", "false", "F", "1", "true", "T"
time.Duration                           "1h22m33s", "6h"
int, int8, int16, int32, int64          "12", "-77"
uint, uint8, uint16, uint32, uint64     "42", "0xDEADBEEF"
float32, float64                        "345.71, "-3.14159"
slice                                   "super, duper", "12, 20, 36"
map                                     "good:26, bad:37, ugly:55", "1:true, 7:false"

func UnmarshalValue

func UnmarshalValue(s string, rv reflect.Value) error

UnmarshalValue converts a string representation of a value of the type wrapped by rv, and writes it into rv. The type is inferred from the type of rv. This has the same functionality as Unmarshal() except that it takes a reflect.Value instead of an interface.