The highest tagged major version is
README
¶
env 
A KISS way to deal with environment variables in Go.
Why
At first, it was boring for me to write down an entire function just to
get some var from the environment and default to another in case it's missing.
For that manner, I wrote a GetOr function in the
go-idioms project.
Then, I got pissed about writing os.Getenv, os.Setenv, os.Unsetenv...
it kind of make more sense to me write it as env.Get, env.Set, env.Unset.
So I did.
Then I got a better idea: to use struct tags to do all that work for me.
Example
A very basic example (check the examples folder):
package main
import (
"fmt"
"time"
"github.com/caarlos0/env"
)
type config struct {
Home string `env:"HOME"`
Port int `env:"PORT" envDefault:"3000"`
IsProduction bool `env:"PRODUCTION"`
Hosts []string `env:"HOSTS" envSeparator:":"`
Duration time.Duration `env:"DURATION"`
TempFolder string `env:"TEMP_FOLDER" envDefault:"${HOME}/tmp" envExpand:"true"`
}
func main() {
cfg := config{}
err := env.Parse(&cfg)
if err != nil {
fmt.Printf("%+v\n", err)
}
fmt.Printf("%+v\n", cfg)
}
You can run it like this:
$ PRODUCTION=true HOSTS="host1:host2:host3" DURATION=1s go run examples/first.go
{Home:/your/home Port:3000 IsProduction:true Hosts:[host1 host2 host3] Duration:1s}
Supported types and defaults
The library has built-in support for the following types:
stringintuintint64boolfloat32float64time.Duration[]string[]int[]bool[]float32[]float64[]time.Duration- .. or use/define a custom parser func for any other type
If you set the envDefault tag for something, this value will be used in the
case of absence of it in the environment. If you don't do that AND the
environment variable is also not set, the zero-value
of the type will be used: empty for strings, false for bools
and 0 for ints.
By default, slice types will split the environment value on ,; you can change this behavior by setting the envSeparator tag.
If you set the envExpand tag, environment variables (either in ${var} or $var format)
in the string will be replaced according with the actual value of the variable.
Custom Parser Funcs
If you have a type that is not supported out of the box by the lib, you are able
to use (or define) and pass custom parsers (and their associated reflect.Type) to the
env.ParseWithFuncs() function.
In addition to accepting a struct pointer (same as Parse()), this function also
accepts a env.CustomParsers arg that under the covers is a map[reflect.Type]env.ParserFunc.
To see what this looks like in practice, take a look at the commented block in the example.
env also ships with some pre-built custom parser funcs for common types. You
can check them out here.
Required fields
The env tag option required (e.g., env:"tagKey,required") can be added
to ensure that some environment variable is set. In the example above,
an error is returned if the config struct is changed to:
type config struct {
Home string `env:"HOME"`
Port int `env:"PORT" envDefault:"3000"`
IsProduction bool `env:"PRODUCTION"`
Hosts []string `env:"HOSTS" envSeparator:":"`
SecretKey string `env:"SECRET_KEY,required"`
}
Documentation
¶
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrNotAStructPtr is returned if you pass something that is not a pointer to a // Struct to Parse ErrNotAStructPtr = errors.New("Expected a pointer to a Struct") // ErrUnsupportedType if the struct field type is not supported by env ErrUnsupportedType = errors.New("Type is not supported") // ErrUnsupportedSliceType if the slice element type is not supported by env ErrUnsupportedSliceType = errors.New("Unsupported slice type") // OnEnvVarSet is an optional convenience callback, such as for logging purposes. // If not nil, it's called after successfully setting the given field from the given value. OnEnvVarSet func(reflect.StructField, string) )
Functions ¶
func Parse ¶
func Parse(v interface{}) error
Parse parses a struct containing `env` tags and loads its values from environment variables.
Example ¶
package main
import (
"fmt"
"os"
"github.com/caarlos0/env"
)
func main() {
type config struct {
Home string `env:"HOME"`
Port int `env:"PORT" envDefault:"3000"`
IsProduction bool `env:"PRODUCTION"`
}
os.Setenv("HOME", "/tmp/fakehome")
cfg := config{}
env.Parse(&cfg)
fmt.Println(cfg)
}
Output: {/tmp/fakehome 3000 false}
func ParseWithFuncs ¶
func ParseWithFuncs(v interface{}, funcMap CustomParsers) error
ParseWithFuncs is the same as `Parse` except it also allows the user to pass in custom parsers.
Types ¶
type CustomParsers ¶
type CustomParsers map[reflect.Type]ParserFunc
CustomParsers is a friendly name for the type that `ParseWithFuncs()` accepts
type ParserFunc ¶
ParserFunc defines the signature of a function that can be used within `CustomParsers`
Source Files
Directories