README
¶
go-env
Access environment variables from Go, and populate structs from them.
Usage
Import path is go.deanishe.net/env.
You can directly access environment variables, or populate your structs from them using struct tags and env.Bind().
Access environment variables
Read int, float64, duration and string values from environment variables, with optional fallback values for unset variables.
import "go.deanishe.net/env"
// Get value for key or return empty string
s := env.Get("SHELL")
// Get value for key or return a specified default
s := env.Get("DOES_NOT_EXIST", "fallback value")
// Get an int (or 0 if SOME_NUMBER is unset or empty)
i := env.GetInt("SOME_NUMBER")
// Int with a fallback
i := env.GetInt("SOME_UNSET_NUMBER", 10)
Binding
You can also populate a struct directly from the environment by appropriately tagging it and calling env.Bind():
// Simple configuration struct
type config struct {
HostName string `env:"HOSTNAME"` // default would be HOST_NAME
Port int // leave as default (PORT)
SSL bool `env:"USE_SSL"` // default would be SSL
Online bool `env:"-"` // ignore this field
}
// Set some values in the environment for test purposes
os.Setenv("HOSTNAME", "api.example.com")
os.Setenv("PORT", "443")
os.Setenv("USE_SSL", "1")
os.Setenv("ONLINE", "1") // will be ignored
// Create a config and bind it to the environment
c := &config{}
if err := Bind(c); err != nil {
// handle error...
}
// config struct now populated from the environment
fmt.Println(c.HostName)
fmt.Printf("%d\n", c.Port)
fmt.Printf("%v\n", c.SSL)
fmt.Printf("%v\n", c.Online)
// Output:
// api.example.com
// 443
// true
// false
Customisation
Variables are retrieved via implementors of the env.Env interface (which env.Bind() accepts as a second, optional parameter):
type Env interface {
// Lookup retrieves the value of the variable named by key.
//
// It follows the same semantics as os.LookupEnv(). If a variable
// is unset, the boolean will be false. If a variable is set, the
// boolean will be true, but the variable may still be an empty
// string.
Lookup(key string) (string, bool)
}
So you can pass a custom Env implementation to Bind() in order to populate structs from a source other than environment variables.
See _examples/docopt to see how to implement a custom Env that populates a struct from docopt command-line options.
Dumping
Dump a struct to a map[string]string by passing it to Dump():
type options struct {
Hostname string
Port int
}
o := options{
Hostname: "www.example.com",
Port: 22,
}
vars, err := Dump(o)
if err != nil {
// handler err
}
fmt.Println(vars["HOSTNAME"]) // -> www.example.com
fmt.Println(vars["PORT"]) // -> 22
Installation
go get go.deanishe.net/env
Documentation
Read the documentation on GoDoc.
Licence
This library is released under the MIT Licence.
Documentation
¶
Overview ¶
Package env maps environment variables to struct fields and vice versa.
It is heavily based on github.com/caarlos0/env, but has different semantics, and also allows the dumping of a struct to environment variables, not just populating a struct from environment variables.
Reading variables ¶
Read environment variables with the Get* functions:
// String
s := env.Get("HOME")
// String with fallback
s = env.Get("NON_EXISTENT_VAR", "default") // -> default
// Int
i := env.GetInt("SOME_COUNT")
// Int with fallback
i = env.GetInt("NON_EXISTENT_VAR", 10) // -> 10
// Duration (e.g. "1m", "2h30m", "5.3s")
d := env.GetDuration("SOME_TIME")
// Duration with fallback
d = env.GetDuration("NON_EXISTENT_VAR", time.Minute * 120) // -> 2h0m
Populating structs ¶
Populate a struct from the environment by passing it to Bind():
type options struct {
Hostname string
Port int
}
o := &options{}
if err := env.Bind(o); err != nil {
// handle error...
}
fmt.Println(o.Hostname) // -> value of HOSTNAME environment variable
fmt.Println(o.Port) // -> value of PORT environment variable
Use tags to specify a variable name or ignore a field:
type options {
HostName string `env:"HOSTNAME"` // default would be HOST_NAME
Port int
Online bool `env:"-"` // ignored
}
Dumping structs ¶
Dump a struct to a map[string]string by passing it to Dump():
type options struct {
Hostname string
Port int
}
o := options{
Hostname: "www.example.com",
Port: 22,
}
vars, err := Dump(o)
if err != nil {
// handler err
}
fmt.Println(vars["HOSTNAME"]) // -> www.example.com
fmt.Println(vars["PORT"]) // -> 22
Tags ¶
Add `env:"..."` tags to your struct fields to bind them to specific environment variables or ignore them. `env:"-"` tells Bind() to ignore the field:
type options {
UserName string
LastUpdatedAt string `env:"-"` // Not loaded from environment
}
Add `env:"VARNAME"` to bind a field to the variable VARNAME:
type options {
UserName string `env:"USERNAME"` // default = USER_NAME
APIKey string `env:"APP_SECRET"` // default = API_KEY
}
Customisation ¶
Variables are retrieved via implementors of the Env interface, which Bind() accepts as a second, optional parameter.
So you can pass a custom Env implementation to Bind() to populate structs from a source other than environment variables.
See _examples/docopt to see a custom Env implementation used to populate a struct from docopt command-line options.
You can also customise the map keys used when dumping a struct by passing VarNameFunc to Dump().
Licence ¶
This library is released under the MIT Licence.
Index ¶
- Variables
- func Bind(v interface{}, env ...Env) error
- func Dump(v interface{}, opt ...DumpOption) (map[string]string, error)
- func Export(v interface{}, opt ...DumpOption) error
- func Get(key string, fallback ...string) string
- func GetBool(key string, fallback ...bool) bool
- func GetDuration(key string, fallback ...time.Duration) time.Duration
- func GetFloat(key string, fallback ...float64) float64
- func GetInt(key string, fallback ...int) int
- func GetString(key string, fallback ...string) string
- func GetUint(key string, fallback ...uint) uint
- func VarName(name string) string
- type DumpOption
- type Env
- type ErrUnsupported
- type MapEnv
- type Reader
- func (r Reader) Get(key string, fallback ...string) string
- func (r Reader) GetBool(key string, fallback ...bool) bool
- func (r Reader) GetDuration(key string, fallback ...time.Duration) time.Duration
- func (r Reader) GetFloat(key string, fallback ...float64) float64
- func (r Reader) GetInt(key string, fallback ...int) int
- func (r Reader) GetString(key string, fallback ...string) string
- func (r Reader) GetUint(key string, fallback ...uint) uint
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ( ErrNotStruct = errors.New("not a struct") ErrNotStructPtr = errors.New("not a pointer to a struct") )
Errors returned by Dump and Bind if they are called with inappropriate values. Bind() requires a pointer to a struct, while Dump requires either a struct or a pointer to a struct.
Functions ¶
func Bind ¶
Bind populates the fields of a struct from environment variables.
Variables are mapped to fields using `env:"..."` tags, and the struct is populated by passing it to Bind(). Unset or empty environment variables are ignored.
Untagged fields have a default environment variable assigned to them. See VarName() for details of how names are generated.
Bind accepts an optional Env argument. If provided, values will be looked up via that Env instead of the program's environment.
Example ¶
Populate a struct from environment variables.
// Simple configuration struct
type config struct {
HostName string `env:"HOSTNAME"` // default: HOST_NAME
UserName string `env:"USERNAME"` // default: USER_NAME
SSL bool `env:"USE_SSL"` // default: SSL
Port int // leave as default (PORT)
PingInterval time.Duration `env:"PING"` // default: PING_INTERVAL
Online bool `env:"-"` // ignore this field
}
// Set some values in the environment for test purposes
_ = os.Setenv("HOSTNAME", "api.example.com")
_ = os.Setenv("USERNAME", "") // empty
_ = os.Setenv("PORT", "443")
_ = os.Setenv("USE_SSL", "1")
_ = os.Setenv("PING", "5m")
_ = os.Setenv("ONLINE", "1") // will be ignored
// Create a config and bind it to the environment
c := &config{}
if err := Bind(c); err != nil {
// handle error...
}
// config struct now populated from the environment
fmt.Println(c.HostName)
fmt.Println(c.UserName)
fmt.Printf("%d\n", c.Port)
fmt.Printf("%v\n", c.SSL)
fmt.Printf("%v\n", c.Online)
fmt.Printf("%v\n", c.PingInterval*4) // it's not a string!
Output: api.example.com 443 true false 20m0s
Example (EmptyVars) ¶
In contrast to the Get* functions, Bind treats empty variables the same as unset ones and ignores them.
type config struct {
Username string
Email string
}
// Defaults
c := &config{
Username: "bob",
Email: "[email protected]",
}
_ = os.Setenv("USERNAME", "dave") // different value
_ = os.Setenv("EMAIL", "") // empty value, ignored by Bind()
// Bind config to environment
if err := Bind(c); err != nil {
panic(err)
}
fmt.Println(c.Username)
fmt.Println(c.Email)
Output: dave [email protected]
func Dump ¶
func Dump(v interface{}, opt ...DumpOption) (map[string]string, error)
Dump extracts a struct's fields to a map of variables. By default, the names (map keys) of the variables are generated using VarName. Pass the VarNameFunc option to generate custom keys.
func Export ¶
func Export(v interface{}, opt ...DumpOption) error
Export extracts a struct's fields' values (via Dump) and exports them to the environment (via os.Setenv). It accepts the same options as Dump.
func Get ¶
Get returns the value for envvar "key". It accepts one optional "fallback" argument. If no envvar is set, returns fallback or an empty string.
If a variable is set, but empty, its value is used.
Example ¶
Basic usage of Get. Returns an empty string if variable is unset.
// Set some test variables
_ = os.Setenv("TEST_NAME", "Bob Smith")
_ = os.Setenv("TEST_ADDRESS", "7, Dreary Lane")
fmt.Println(Get("TEST_NAME"))
fmt.Println(Get("TEST_ADDRESS"))
fmt.Println(Get("TEST_NONEXISTENT")) // unset variable
// GetString is a synonym
fmt.Println(GetString("TEST_NAME"))
Output: Bob Smith 7, Dreary Lane Bob Smith
Example (Fallback) ¶
The fallback value is returned if the variable is unset.
// Set some test variables
_ = os.Setenv("TEST_NAME", "Bob Smith")
_ = os.Setenv("TEST_ADDRESS", "7, Dreary Lane")
_ = os.Setenv("TEST_EMAIL", "")
fmt.Println(Get("TEST_NAME", "default name")) // fallback ignored
fmt.Println(Get("TEST_ADDRESS", "default address")) // fallback ignored
fmt.Println(Get("TEST_EMAIL", "[email protected]")) // fallback ignored (var is empty, not unset)
fmt.Println(Get("TEST_NONEXISTENT", "hi there!")) // unset variable
Output: Bob Smith 7, Dreary Lane hi there!
func GetBool ¶
GetBool returns the value for envvar "key" as a boolean. It accepts one optional "fallback" argument. If no envvar is set, returns fallback or false.
Values are parsed with strconv.ParseBool().
Example ¶
Strings are parsed using strconv.ParseBool().
// Set some test variables
_ = os.Setenv("LIKE_PEAS", "t")
_ = os.Setenv("LIKE_CARROTS", "true")
_ = os.Setenv("LIKE_BEANS", "1")
_ = os.Setenv("LIKE_LIVER", "f")
_ = os.Setenv("LIKE_TOMATOES", "0")
_ = os.Setenv("LIKE_BVB", "false")
_ = os.Setenv("LIKE_BAYERN", "FALSE")
// strconv.ParseBool() supports many formats
fmt.Println(GetBool("LIKE_PEAS"))
fmt.Println(GetBool("LIKE_CARROTS"))
fmt.Println(GetBool("LIKE_BEANS"))
fmt.Println(GetBool("LIKE_LIVER"))
fmt.Println(GetBool("LIKE_TOMATOES"))
fmt.Println(GetBool("LIKE_BVB"))
fmt.Println(GetBool("LIKE_BAYERN"))
// Fallback
fmt.Println(GetBool("LIKE_BEER", true))
Output: true true true false false false false true
func GetDuration ¶
GetDuration returns the value for envvar "key" as a time.Duration. It accepts one optional "fallback" argument. If no envvar is set, returns fallback or 0.
Values are parsed with time.ParseDuration().
Example ¶
Durations are parsed using time.ParseDuration.
// Set some test variables
_ = os.Setenv("DURATION_NAP", "20m")
_ = os.Setenv("DURATION_EGG", "5m")
_ = os.Setenv("DURATION_BIG_EGG", "")
_ = os.Setenv("DURATION_MATCH", "1.5h")
// returns time.Duration
fmt.Println(GetDuration("DURATION_NAP"))
fmt.Println(GetDuration("DURATION_EGG") * 2)
// fallback with unset variable
fmt.Println(GetDuration("DURATION_POWERNAP", time.Minute*45))
// or an empty one
fmt.Println(GetDuration("DURATION_BIG_EGG", time.Minute*10))
fmt.Println(GetDuration("DURATION_MATCH").Minutes())
Output: 20m0s 10m0s 45m0s 10m0s 90
func GetFloat ¶
GetFloat returns the value for envvar "key" as a float. It accepts one optional "fallback" argument. If no envvar is set, returns fallback or 0.0.
Values are parsed with strconv.ParseFloat().
Example ¶
Strings are parsed to floats using strconv.ParseFloat().
// Set some test variables
_ = os.Setenv("TOTAL_SCORE", "172.3")
_ = os.Setenv("AVERAGE_SCORE", "7.54")
fmt.Printf("%0.2f\n", GetFloat("TOTAL_SCORE"))
fmt.Printf("%0.1f\n", GetFloat("AVERAGE_SCORE"))
fmt.Println(GetFloat("NON_EXISTENT_SCORE", 120.5))
Output: 172.30 7.5 120.5
func GetInt ¶
GetInt returns the value for envvar "key" as an int. It accepts one optional "fallback" argument. If no envvar is set, returns fallback or 0.
Values are parsed with strconv.ParseInt(). If strconv.ParseInt() fails, tries to parse the number with strconv.ParseFloat() and truncate it to an int.
Example ¶
Getting int values with and without fallbacks.
// Set some test variables
_ = os.Setenv("PORT", "3000")
_ = os.Setenv("PING_INTERVAL", "")
fmt.Println(GetInt("PORT"))
fmt.Println(GetInt("PORT", 5000)) // fallback is ignored
fmt.Println(GetInt("PING_INTERVAL")) // returns zero value
fmt.Println(GetInt("PING_INTERVAL", 60)) // returns fallback
Output: 3000 3000 0 60
func GetUint ¶
GetUint returns the value for envvar "key" as an int. It accepts one optional "fallback" argument. If no envvar is set, returns fallback or 0.
Values are parsed with strconv.ParseUint(). If strconv.ParseUint() fails, tries to parse the number with strconv.ParseFloat() and truncate it to a uint.
Example ¶
Getting int values with and without fallbacks.
// Set some test variables
_ = os.Setenv("PORT", "3000")
_ = os.Setenv("PING_INTERVAL", "")
fmt.Println(GetUint("PORT"))
fmt.Println(GetUint("PORT", 5000)) // fallback is ignored
fmt.Println(GetUint("PING_INTERVAL")) // returns zero value
fmt.Println(GetUint("PING_INTERVAL", 60)) // returns fallback
Output: 3000 3000 0 60
func VarName ¶
VarName generates an environment variable name from a field name. This is documented to show how the automatic names are generated.
Example ¶
Example output of VarName.
// single-case words are upper-cased
fmt.Println(VarName("URL"))
fmt.Println(VarName("name"))
// words that start with fewer than 3 uppercase chars are
// upper-cased
fmt.Println(VarName("Folder"))
fmt.Println(VarName("MTime"))
// but with 3+ uppercase chars, the last is treated as the first
// char of the next word
fmt.Println(VarName("VIPath"))
fmt.Println(VarName("URLEncoding"))
fmt.Println(VarName("SSLPort"))
// camel-case words are split on the case changes
fmt.Println(VarName("LastName"))
fmt.Println(VarName("LongHorse"))
fmt.Println(VarName("loginURL"))
fmt.Println(VarName("newHomeAddress"))
fmt.Println(VarName("PointA"))
// digits are considered as the end of a word, not the start
fmt.Println(VarName("b2B"))
Output: URL NAME FOLDER MTIME VI_PATH URL_ENCODING SSL_PORT LAST_NAME LONG_HORSE LOGIN_URL NEW_HOME_ADDRESS POINT_A B2_B
Types ¶
type DumpOption ¶
type DumpOption func(d *dumper)
DumpOption is a configuration option to Dump.
var ( // IgnoreZeroValues excludes zero values from the returned map of variables. // Non-nil slices are unaffected by the setting: an empty string is returned // for empty slices regardless. IgnoreZeroValues DumpOption = func(d *dumper) { d.noZero = true } )
func VarNameFunc ¶
func VarNameFunc(fun func(string) string) DumpOption
VarNameFunc specifies a different function to generate the names of the variables returned by Dump.
type Env ¶
type Env interface {
// Lookup retrieves the value of the variable named by key.
//
// It follows the same semantics as os.LookupEnv(). If a variable
// is unset, the boolean will be false. If a variable is set, the
// boolean will be true, but the variable may still be an empty
// string.
Lookup(key string) (string, bool)
}
Env is the data source for bindings and lookup. It is an optional parameter to Bind(). By specifying a custom Env, it's possible to populate a struct from an alternative source.
The demo program in _examples/docopt implements a custom Env to populate a struct from docopt options via Bind().
var ( // System retrieves values from the system environment. System Env = systemEnv{} )
type ErrUnsupported ¶
type ErrUnsupported string
ErrUnsupported is returned by Bind if a field of an unsupported type is tagged for binding. Unsupported fields that are not tagged are ignored.
type Reader ¶
type Reader struct {
// contains filtered or unexported fields
}
Reader converts values from Env into other types.
func (Reader) Get ¶
Get returns the value for envvar "key". It accepts one optional "fallback" argument. If no envvar is set, returns fallback or an empty string.
If a variable is set, but empty, its value is used.
func (Reader) GetBool ¶
GetBool returns the value for envvar "key" as a boolean. It accepts one optional "fallback" argument. If no envvar is set, returns fallback or false.
Values are parsed with strconv.ParseBool().
func (Reader) GetDuration ¶
GetDuration returns the value for envvar "key" as a time.Duration. It accepts one optional "fallback" argument. If no envvar is set, returns fallback or 0.
Values are parsed with time.ParseDuration().
func (Reader) GetFloat ¶
GetFloat returns the value for envvar "key" as a float. It accepts one optional "fallback" argument. If no envvar is set, returns fallback or 0.0.
Values are parsed with strconv.ParseFloat().
func (Reader) GetInt ¶
GetInt returns the value for envvar "key" as an int. It accepts one optional "fallback" argument. If no envvar is set, returns fallback or 0.
Values are parsed with strconv.ParseInt(). If strconv.ParseInt() fails, tries to parse the number with strconv.ParseFloat() and truncate it to an int.
func (Reader) GetUint ¶
GetUint returns the value for envvar "key" as an int. It accepts one optional "fallback" argument. If no envvar is set, returns fallback or 0.
Values are parsed with strconv.ParseUint(). If strconv.ParseUint() fails, tries to parse the number with strconv.ParseFloat() and truncate it to a uint.
Source Files
Directories