copperhead

README

Copperhead

Configuration loader that can load configuration from environment, files, or byte slices.

Copperhead was written to match the features that we actually used in viper (https://github.com/spf13/viper). Configuration is always loaded into a struct. Unless you pass an UnmarshalerFunc the only supported format is JSON. The predecence of configuration sources is completely controlled by the order in which you load them. URLs can be parsed as a part of the configuration loading step.

Copperhead supports the "option function"-style shown below, which has the advantage of just giving you one place to error check. You can also call func (c *Config) Environment, func (c *Config) File, and func (c *Config) Data to load configuration sources one by one.

Example usage:

// Configuration is an example configuration struct
type Configuration struct {
	Name   string
	WD     string
	URL    *url.URL
	Birdie *ExampleNest
}

type ExampleNest struct {
	Name       string
	Value      int64
	YamlIT     string `yaml:"yaml_it"`
	ComplexEnv int
}

func ExampleUsage() {
	os.Setenv("APP_NAME", "example-app")
	os.Setenv("APP_URL", "https://www.example.com")
	os.Setenv("APP_BIRD", "12")
	os.Setenv("DUMB_USAGE", `{"ComplexEnv":42}`)

	cfg := Configuration{
		WD: "with defaults",
	}
	_, err := copperhead.New(&cfg,
		copperhead.WithConfigurationFile(
			"example.conf", copperhead.FileRequired, nil,
		),
		copperhead.WithConfigurationFile(
			"example.conf.yaml",
			copperhead.FileRequired,
			copperhead.UnmarshalerFunc(yaml.Unmarshal),
		),
		copperhead.WithEnvironment(map[string]string{
			"Name":         "APP_NAME",
			"URL":          "APP_URL",
			"Birdie.Value": "APP_BIRD",
			"Birdie":       "DUMB_USAGE",
		}),
	)
	if err != nil {
		println(err.Error())
		os.Exit(1)
	}

	fmt.Println("Name:", cfg.Name)
	fmt.Println("WD:", cfg.WD)
	fmt.Println("URL:", cfg.URL.String())
	fmt.Println("URL proto:", cfg.URL.Scheme)
	fmt.Println("Birdie.Name:", cfg.Birdie.Name)
	fmt.Println("Birdie.Value:", cfg.Birdie.Value)
	fmt.Println("Birdie.YamlIT:", cfg.Birdie.YamlIT)
	fmt.Println("Birdie.ComplexEnv:", cfg.Birdie.ComplexEnv)

	// Output:
	// Name: example-app
	// WD: with defaults
	// URL: https://www.example.com
	// URL proto: https
	// Birdie.Name: Heron
	// Birdie.Value: 12
	// Birdie.YamlIT: Hello from YAML
	// Birdie.ComplexEnv: 42
}

Documentation

Overview

Package copperhead provides a configuration loader that can load configuration from environment, files, or byte slices.

Index

• type Config
  • func New(conf interface{}, opts ...Option) (*Config, error)
  • func (c *Config) Data(data []byte, unm Unmarshaler) error
  • func (c *Config) Environment(envMap map[string]string) error
  • func (c *Config) File(filename string, mode FileMode, unm Unmarshaler) error
• type FileMode
• type Option
  • func WithConfigurationData(data []byte, unm Unmarshaler) Option
  • func WithConfigurationFile(filename string, mode FileMode, unm Unmarshaler) Option
  • func WithEnvironment(envMap map[string]string) Option
• type Unmarshaler
• type UnmarshalerFunc
  • func (uf UnmarshalerFunc) Unmarshal(data []byte, v interface{}) error

Types

type Config

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

Config encapsulates configuration loading.

func New

func New(conf interface{}, opts ...Option) (*Config, error)

New creates a new configuration that populates conf.

func (*Config) Data

func (c *Config) Data(data []byte, unm Unmarshaler) error

Data reads the provided configuration data.

func (*Config) Environment

func (c *Config) Environment(envMap map[string]string) error

Environment populates our configuration with environment variables.

func (*Config) File

func (c *Config) File(filename string, mode FileMode, unm Unmarshaler) error

File reads configuration from a file.

type FileMode

type FileMode string

FileMode controls file loading behaviour.

const (
	FileRequired FileMode = "required"
	FileOptional          = "optional"
)

The file loading modes

type Option

type Option func(c *Config) error

Option configures our... inception!

func WithConfigurationData

func WithConfigurationData(data []byte, unm Unmarshaler) Option

WithConfigurationData reads the provided configuration data.

func WithConfigurationFile

func WithConfigurationFile(filename string, mode FileMode, unm Unmarshaler) Option

WithConfigurationFile reads configuration from a file.

func WithEnvironment

func WithEnvironment(envMap map[string]string) Option

WithEnvironment bootstraps our configuration with environment variables.

type Unmarshaler

type Unmarshaler interface {
	Unmarshal(data []byte, v interface{}) error
}

Unmarshaler is something that can unmarshal a configuration.

type UnmarshalerFunc

type UnmarshalerFunc func(data []byte, v interface{}) error

UnmarshalerFunc is an unmarshal function

func (UnmarshalerFunc) Unmarshal

func (uf UnmarshalerFunc) Unmarshal(
	data []byte, v interface{},
) error

Unmarshal the config data.