env

README

env

Go support library to aide and enhance using environment variables for configuration.

Please see the examples directory for inspiration. API Documentation is available here.

Getting started

Example

package main

import (
  "github.com/danryan/env"
  "fmt"
  "os"
)

// An imaginary config for a chat bot
type Config struct {
  Name    string `env:"key=NAME required=true"`
  Port    int    `env:"key=PORT default=9000"`
  Adapter string `env:"key=ADAPTER default=shell in=shell,slack,hipchat"`
  Enabled bool   `env:"key=IS_ENABLED default=true"`
}

func main() {
  os.Setenv("NAME", "hal")
  c := &Config{}
  if err := env.Process(c); err != nil {
    fmt.Println(err)
  }
  fmt.Printf("name: %s, port: %d, adapter: %s, enabled: %v\n", c.Name, c.Port, c.Adapter, c.Enabled)
}
// Will print out
// name: foo, port: 9001, adapter: shell, enabled: true

This library uses runtime reflection just like encoding/json. Most programs won't have more than a handful of config objects, so the slowness typically associated with reflection is negligible here.

Supported types

Four types are currently supported:

• string - defaults to ""
• int - defaults to 0
• bool - defaults to false
• float64 - defaults to 0.0

Support for custom types via interfaces will likely make an an appearance at a later date.

Struct tags

Env uses struct tags to set up rules for parsing environment variables and setting fields on your config struct. Tag syntax must be either key=value or key (boolean), using spaces to separate. Spaces in keys or values are not allowed. This is very likely to change in the future, as it's a rather limiting restriction.

key

The key is used to look up an environment variable. Keys are automatically UPPER_CASED. If this tag is not specified, the name of the struct field will be used.

// Look for a variable `MY_NAME`, or return an empty string
type Config struct {
  Name string `env:"key=MY_NAME"`
}

// Look for a variable `MY_PORT`. Note that uppercase conversion is automatic.
type Config struct {
  Port string `env:"key=my_port"`
}

required

Including required validates that the requested environment variable is present, or returns an error if not.

// Look for a variable `NAME`, or return an error if not found.
type Config struct {
  Name string `env:"required"`
}

default

If specified, the default will be used if no environment variable is found matching the key. Default values must be castable to the associated struct field type, otherwise an error is returned.

// Look for a variable `ENABLED` or otherwise default to true
type Config struct {
  Enabled bool `env:"default=true"`
}
config := &Config{}
if config.Enabled {
  fmt.Println("Enabled!") // prints "Enabled!"
}

// ...

// Look for a variable `NAME` or default to "Inigo"
type Config struct {
  Name string `env:"default=Inigo"`
}

config := &Config{}
fmt.Println(config.Name) // prints "Inigo"

options

Options ensure that an environment variable is in a set of possible valid values. If it is not, an error is returned.

// Look for a variable `ADAPTER` and return an error if the variable is not
// included in the options
type Config struct {
  Adapter string `env:"options=shell,slack,hipchat"`
}

Is it any good?

Probably not.

Bugs, features, rants, etc.

Please use (the issue tracker)[https://github.com/danryan/env/issues) for development progress tracking, feature requests, or bug reports. Thank you! ❤

Documentation

Index

• func MustProcess(v interface{})
• func Process(v interface{}) error
• type Env
  • func New(v interface{}) (*Env, error)
  • func NewEnv(v interface{}) (*Env, error)
  • func (e *Env) FieldNames() []string
  • func (e *Env) Parse() error
  • func (e *Env) SetPrefix(prefix string)
  • func (e *Env) SetValue(v interface{})
  • func (e *Env) Type() reflect.Type
• type Var
  • func NewVar(field reflect.StructField) (*Var, error)
  • func (v *Var) Parse(field reflect.StructField) error
  • func (v *Var) SetDefault(value reflect.Value)
  • func (v *Var) SetKey(value string)
  • func (v *Var) SetName(value string)
  • func (v *Var) SetOptions(values []reflect.Value)
  • func (v *Var) SetRequired(value bool)
  • func (v *Var) SetType(value reflect.Type)
  • func (v *Var) SetValue(value reflect.Value)

Functions

func MustProcess

func MustProcess(v interface{})

MustProcess maps environment variables to the fields of struct v. If any errors are returned, this function will panic.

func Process

func Process(v interface{}) error

Process takes a struct, and maps environment variables to its fields. Errors returned from underlying functions will bubble up to the surface.

Types

type Env

type Env struct {
	Value  reflect.Value // Value is the value of an interface or pointer
	Prefix string
	Vars   []*Var
}

Env struct

func New

func New(v interface{}) (*Env, error)

New is a shortcut wrapper around NewEnv

func NewEnv

func NewEnv(v interface{}) (*Env, error)

NewEnv returns a new Env

func (*Env) FieldNames

func (e *Env) FieldNames() []string

FieldNames returns the name of all struct fields as aa slice of strings

func (*Env) Parse

func (e *Env) Parse() error

Parse parses the config struct into valid Vars

func (*Env) SetPrefix

func (e *Env) SetPrefix(prefix string)

SetPrefix sets prefix of Env e

func (*Env) SetValue

func (e *Env) SetValue(v interface{})

SetValue sets Value of Env e

func (*Env) Type

func (e *Env) Type() reflect.Type

Type returns the type of e.Value

type Var

type Var struct {
	Name     string
	Key      string
	Type     reflect.Type
	Value    reflect.Value
	Required bool
	Default  reflect.Value
	Options  []reflect.Value
}

Var struct

func NewVar

func NewVar(field reflect.StructField) (*Var, error)

NewVar returns a new Var

func (*Var) Parse

func (v *Var) Parse(field reflect.StructField) error

Parse parses the struct tags of each field

func (*Var) SetDefault

func (v *Var) SetDefault(value reflect.Value)

SetDefault sets Var.Default

func (*Var) SetKey

func (v *Var) SetKey(value string)

SetKey sets Var.Key

func (*Var) SetName

func (v *Var) SetName(value string)

SetName sets Var.Name

func (*Var) SetOptions

func (v *Var) SetOptions(values []reflect.Value)

SetOptions sets Var.Options

func (*Var) SetRequired

func (v *Var) SetRequired(value bool)

SetRequired sets Var.Required

func (*Var) SetType

func (v *Var) SetType(value reflect.Type)

SetType sets Var.Type

func (*Var) SetValue

func (v *Var) SetValue(value reflect.Value)

SetValue sets Var.Value