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     *copperhead.URL
	FileURL *copperhead.URL
	Birdie  *ExampleNest
}

// ExampleNest is an exampe of a nested configuration struct.
type ExampleNest struct {
	Name       string
	Value      int64
	YamlIT     string `yaml:"yaml_it"`
	ComplexEnv int
}

// ExampleUsage is a testable example for Copperhead
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",
	}
	ch, err := copperhead.New(&cfg,
		copperhead.WithConfigurationFile(
			"./test-data/example.conf", copperhead.FileRequired, nil,
		),
		copperhead.WithConfigurationFile(
			"./test-data/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)

	// Load additional config file.
	err = ch.File("./test-data/file-url.json",
		copperhead.FileRequired, nil)
	if err != nil {
		println(err.Error())
		os.Exit(1)
	}
	fmt.Println("File URL (json):", cfg.FileURL.String())

	err = ch.File("./test-data/file-url.yaml",
		copperhead.FileRequired,
		copperhead.UnmarshalerFunc(yaml.Unmarshal))
	if err != nil {
		println(err.Error())
		os.Exit(1)
	}
	fmt.Println("File URL (yaml):", cfg.FileURL.String())

	// 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
	// File URL (json): http://www.example.com/json
	// File URL (yaml): http://www.example.com/yaml
}

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
  • func (c *Config) Getenv(field, env string) error
• type Duration
  • func (d *Duration) UnmarshalText(text []byte) 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 Time
  • func (t *Time) UnmarshalText(text []byte) error
• type URL
  • func (u *URL) UnmarshalText(text []byte) error
• 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.

func (*Config) Getenv

func (c *Config) Getenv(field, env string) error

Getenv reads a single environment variable.

type Duration

type Duration struct {
	time.Duration
}

Duration is an TextUnmarshaler-aware Duration

func (*Duration) UnmarshalText

func (d *Duration) UnmarshalText(text []byte) error

UnmarshalText implements encoding.TextUnmarshaler.

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 Time

type Time struct {
	time.Time
}

Time is an TextUnmarshaler-aware Time

func (*Time) UnmarshalText

func (t *Time) UnmarshalText(text []byte) error

UnmarshalText implements encoding.TextUnmarshaler.

type URL

type URL struct {
	url.URL
}

URL is an TextUnmarshaler-aware URL

func (*URL) UnmarshalText

func (u *URL) UnmarshalText(text []byte) error

UnmarshalText implements encoding.TextUnmarshaler.

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.