zconf

Documentation

Overview

Simple struct-based configuration library Supports config from environment variables, .env files, command line flags, config files (yaml, json, toml, etc) and default tags.

Example

type Config struct {
	Port int    `default:"8080" env:"PORT" flag:",specify the port to listen on"`
	Host string `default:"localhost"`
	DB   struct {
		DSN string `default:"sqlite://:memory:"`
	}
}

var config Config
// Sets the struct values using flags, environment variables and finally the default values defined on the struct
if err := Load(&config, Auto()); err != nil {
	panic(err)
}

flag.Usage()
// flag.Usage will output the following:
// Usage of test:
//   -db-dsn string
//     	set db-dsn
//   -host string
//     	set host
//   -port int
//     	specify the port to listen on

Example (Auto)

type Config struct {
	Port int    `default:"8080" env:"PORT"`
	Host string `default:"localhost"`
	DB   struct {
		DSN string `default:"sqlite://:memory:"`
	}
}
var c Config

// This will use any flags if they are provided, then environment variables and finally default values
if err := Load(&c, Auto()); err != nil {
	panic(err)
}

Example (Manual)

type Config struct {
	Port int    `default:"8080" env:"PORT"`
	Host string `default:"localhost"`
	DB   struct {
		DSN string `default:"sqlite://:memory:"`
	}
}
var c Config
// This will use any flags if they are provided, then environment variables and finally default values
if err := Load(&c, Flag(), Env(), Defaults()); err != nil {
	panic(err)
}

Index

• func Auto() configOption
• func Defaults() configOption
• func Env(paths ...string) configOption
• func EnvFiles(paths ...string) configOption
• func Flag(opts ...flagOpt) configOption
• func Load(val interface{}, opts ...configOption) (err error)
• func New(opts ...configOption) *zconfig
• func Prefix(prefix string) configOption
• func SkipParse() flagOpt
• func UseFlagSet(fs *flag.FlagSet) flagOpt
• type ConfigPrefixable
• type ConfigSettable
• type Configurer
• type FlagConfigurer
  • func (f *FlagConfigurer) Apply(val interface{}, args ...string) (err error)
  • func (f *FlagConfigurer) Init(val interface{}) (err error)
  • func (f *FlagConfigurer) SetFlagSet(flagSet *flag.FlagSet)
  • func (f *FlagConfigurer) SetPrefix(prefix string)

Examples

• Package
• Package (Auto)
• Package (Manual)
• Env
• EnvFiles
• Flag
• Flag (Customization)

Functions

func Auto

func Auto() configOption

Configure a struct using any command line flags, environment variables, variables in .env and finally, values set using default tags

func Defaults

func Defaults() configOption

func Env

func Env(paths ...string) configOption

This will load configuration values from both environment variables and any .env files provided. By default, if a provided path does not exist it will be skipped. Keys are set using the struct field name, but can be overridden using the `env` struct tag. If the `env` struct tag is not set, the key is the struct field name converted to uppercase with words separated by underscores. Additional underscores are added for nested structs.

Example

type Config struct {
	Port int    `env:"PORT"`
	Host string `env:"HOST"`
	DB   struct {
		DSN string `env:"DB_DSN"`
	}
}

// The following environment variables will set the values on the struct
os.Setenv("PORT", "8080")
os.Setenv("HOST", "localhost")
os.Setenv("DB_DSN", "sqlite://:memory:")
var config Config
if err := Load(&config, Env()); err != nil {
	panic(err)
}

func EnvFiles

func EnvFiles(paths ...string) configOption

Load configuration values from any .env files provided. By default, if a provided path does not exist it will be skipped. The keys use the same format and struct tag as the Env configurer.

Example

type Config struct {
	Port int    `env:"PORT"`
	Host string `env:"HOST"`
	DB   struct {
		DSN string `env:"DB_DSN"`
	}
}

var config Config
// This will load the values from the .env file and ignores anything in os.Environ
if err := Load(&config, EnvFiles(".env")); err != nil {
	panic(err)
}

func Flag

func Flag(opts ...flagOpt) configOption

Load configuration values from command line flags. The flag name can be overridden using the `flag` struct tag. The default flag name is the struct field name converted to kebab-case. Additional dashes are added for nested structs.

Example

The default usage of the flag configurer

type Config struct {
	Port int    `flag:"port"`
	Host string `flag:"host"`
	DB   struct {
		DSN string `flag:"db-dsn"`
	}
}
// The following command line arguments will set the values on the struct:
// -port 8080 -host localhost -db-dsn sqlite://:memory:
var config Config
if err := Load(&config, Flag()); err != nil {
	panic(err)
}

Example (Customization)

This is how we can customize how the flag configurer works.

type Config struct {
	Port int    `flag:"port"`
	Host string `flag:"host"`
	DB   struct {
		DSN string `flag:"db-dsn"`
	}
}
// The following command line arguments will set the values on the struct:
// -port 8080 -host localhost -db-dsn sqlite://:memory:
var config Config
set := flag.NewFlagSet("test", flag.ContinueOnError)
// This will set the flag names on the 'test' flag set
if err := Load(&config, Flag(UseFlagSet(set))); err != nil {
	panic(err)
}

// This will not call flag.Parse()
// if err := Load(&config, Flag(SkipParse())); err != nil {
// 	panic(err)
// }

func Load

func Load(val interface{}, opts ...configOption) (err error)

Helper function to quickly load a struct using the configurers provided

func New

func New(opts ...configOption) *zconfig

Create a configurer. Configurer precedence is the order in which they are provided.

func Prefix

func Prefix(prefix string) configOption

func SkipParse

func SkipParse() flagOpt

Tell the Flag configurer not to parse the flag set. This is useful if you want to parse the flags yourself or are using an external library.

func UseFlagSet

func UseFlagSet(fs *flag.FlagSet) flagOpt

Provide a custom flag set. This is useful if you want to parse the flags yourself or are using an external library.

Types

type ConfigPrefixable

type ConfigPrefixable interface {
	SetPrefix(prefix string)
}

type ConfigSettable

type ConfigSettable interface {
	SetConfig(val interface{}) error
}

type Configurer

type Configurer interface {
	Init(val interface{}) error
	Apply(val interface{}, args ...string) error
}

type FlagConfigurer

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

func (*FlagConfigurer) Apply

func (f *FlagConfigurer) Apply(val interface{}, args ...string) (err error)

func (*FlagConfigurer) Init

func (f *FlagConfigurer) Init(val interface{}) (err error)

func (*FlagConfigurer) SetFlagSet

func (f *FlagConfigurer) SetFlagSet(flagSet *flag.FlagSet)

func (*FlagConfigurer) SetPrefix

func (f *FlagConfigurer) SetPrefix(prefix string)