README
¶
env
Credit
This repo is a heavily modified version of env by https://github.com/caarlos0 . Also major portions we adapted from github.com/joho/godotenv.
env utility functions
This repo provides some simple utilities for dealing with environment variables. There are some basic functions that are simple wrappers to the "os" package's env functions. These include:
err = env.Set("KEY", "secret_key")
err = env.Unset("KEY")
value = env.Get("OTHER_KEY")
value = env.GetOr("OTHER_KEY", "value returned if OTHER_KEY does not exist")
value = env.MustGet("KEY") // panics if KEY does not exist
Parse environment vars into a struct
A much more powerful approach is to populate an annotated struct with values from the environment.
Take the following example:
type ClientConfig struct {
Endpoint []string `env:"ENDPOINT" required:"true"`
HealthCheck bool `env:"HEALTH_CHECK" envDefault:"true"`
HealthCheckTimeout time.Duration `env:"HEALTH_CHECK_TIMEOUT" envDefault:"1s"`
}
This anotated struct can then be populated with the appropiate environment variables but using the following command:
cfg := ClientConfig{}
err := env.Parse(&cfg)
Using a prefix
If the struct you are populating is part of a library you may want to have parse the same struct but with different values. You can do this by using a prfic when parsing.
cfg := ClientConfig{}
err := env.ParseWithPrefix(&cfg, "CLIENT2_")
In this case the parser would look for the envionment variables CLIENT2_ENDPOINT, CLIENT2_HEALTH_CHECK, etc.
Supported types and defaults
The environment variables are Parsed to go into the appropiate types (or an err is thrown if it can not do so). This sames you from writing a some basic validations on envirnment varaibles.
The library has built-in support for the following types:
stringintuintint64boolfloat32float64time.Durationurl.URL[]string[]int[]bool[]float32[]float64[]time.Duration[]url.URL
Optional tags
The required tag will cause an error if the environment variable does not exist:
`env:"ENDPOINT" required:"true"`
The envDefault tag will allow you to provide a default value to use if the environment variable does not exist:
`env:"HEALTH_CHECK" envDefault:"true"`
When assigning to a slice type the "," is used to seperate fields. You can override this with the envSeparator:":" tag to use some other character.
Documentation
¶
Index ¶
- Variables
- func Get(key string) string
- func GetBool(key string) (bool, error)
- func GetDuration(key string) (time.Duration, error)
- func GetFloat32(key string) (float32, error)
- func GetFloat64(key string) (float64, error)
- func GetInt(key string) (int, error)
- func GetInt64(key string) (int64, error)
- func GetOr(key, defaultValue string) string
- func GetOrBool(key string, defaultValue bool) bool
- func GetOrDuration(key string, defaultValue string) time.Duration
- func GetOrFloat32(key string, defaultValue float32) float32
- func GetOrFloat64(key string, defaultValue float64) float64
- func GetOrInt(key string, defaultValue int) int
- func GetOrInt64(key string, defaultValue int64) int64
- func GetOrUint(key string, defaultValue uint) uint
- func GetOrUint64(key string, defaultValue uint64) uint64
- func GetOrUrl(key string, defaultValue string) *url.URL
- func GetUint(key string) (uint, error)
- func GetUint64(key string) (uint64, error)
- func GetUrl(key string) (*url.URL, error)
- func Load(filenames ...string) (err error)
- func Marshal(envMap map[string]string) (string, error)
- func MustGet(key string) string
- func MustGetBool(key string) bool
- func MustGetDuration(key string) time.Duration
- func MustGetFloat32(key string) float32
- func MustGetFloat64(key string) float64
- func MustGetInt(key string) int
- func MustGetInt64(key string) int64
- func MustGetUint(key string) uint
- func MustGetUint64(key string) uint64
- func MustGetUrl(key string) *url.URL
- func MustLoad(filenames ...string)
- func MustOverload(filenames ...string)
- func Overload(filenames ...string) (err error)
- func Parse(v interface{}) error
- func ParseIO(r io.Reader) (envMap map[string]string, err error)
- func ParseWithFuncs(v interface{}, funcMap CustomParsers) error
- func ParseWithPrefix(v interface{}, prefix string) error
- func ParseWithPrefixFuncs(v interface{}, prefix string, funcMap CustomParsers) error
- func Read(filenames ...string) (envMap map[string]string, err error)
- func Set(key, value string) error
- func Unmarshal(str string) (envMap map[string]string, err error)
- func Unset(key string) error
- func Write(envMap map[string]string, filename string) error
- type CustomParsers
- type ParserFunc
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 GetDuration ¶ added in v0.4.0
GetDuration - get an environment variable as time.Duration
func GetFloat32 ¶ added in v0.2.7
GetFloat32 - get an environment variable as float32
func GetFloat64 ¶ added in v0.4.0
GetFloat64 - get an environment variable as float64
func GetOr ¶ added in v0.2.0
GetOr - get an environment variable or return default value if does not exist
func GetOrBool ¶ added in v0.2.6
GetOrBool - get an environment variable or return default value if does not exist
func GetOrDuration ¶ added in v0.4.0
GetOrDuration - get an environment variable or return default value if does not exist
func GetOrFloat32 ¶ added in v0.2.7
GetOrFloat32 - get an environment variable or return default value if does not exist
func GetOrFloat64 ¶ added in v0.4.0
GetOrFloat64 - get an environment variable or return default value if does not exist
func GetOrInt ¶ added in v0.2.6
GetOrInt - get an environment variable or return default value if does not exist
func GetOrInt64 ¶ added in v0.4.0
GetOrInt64 - get an environment variable or return default value if does not exist
func GetOrUint ¶ added in v0.2.6
GetOrUint - get an environment variable or return default value if does not exist
func GetOrUint64 ¶ added in v0.4.0
GetOrUint64 - get an environment variable or return default value if does not exist
func GetOrUrl ¶ added in v0.4.0
GetOrUrl - get an environment variable or return default value if does not exist
func Load ¶ added in v0.2.5
Load will read your env file(s) and load them into ENV for this process.
Call this function as close as possible to the start of your program (ideally in main)
If you call Load without any args it will default to loading .env in the current path ¶
You can otherwise tell it which files to load (there can be more than one) like
err := env.Load("fileone", "filetwo")
It's important to note that it WILL NOT OVERRIDE an env variable that already exists - consider the .env file to set dev vars or sensible defaults
func Marshal ¶ added in v0.2.5
Marshal outputs the given environment as a dotenv-formatted environment file. Each line is in the format: KEY="VALUE" where VALUE is backslash-escaped.
func MustGetBool ¶ added in v0.2.6
MustGetBool - get an environment variable or panic if does not exist
func MustGetDuration ¶ added in v0.4.0
MustGetDuration - get an environment variable or panic if does not exist
func MustGetFloat32 ¶ added in v0.2.7
MustGetUFloat32 - get an environment variable or panic if does not exist
func MustGetFloat64 ¶ added in v0.4.0
MustGetUFloat64 - get an environment variable or panic if does not exist
func MustGetInt ¶ added in v0.2.6
MustGetInt - get an environment variable or panic if does not exist
func MustGetInt64 ¶ added in v0.4.0
MustGetInt64 - get an environment variable or panic if does not exist
func MustGetUint ¶ added in v0.2.6
MustGetUint - get an environment variable or panic if does not exist
func MustGetUint64 ¶ added in v0.4.0
MustGetUint64 - get an environment variable or panic if does not exist
func MustGetUrl ¶ added in v0.4.0
MustGetUrl - get an environment variable or panic if does not exist
func MustLoad ¶ added in v0.2.7
func MustLoad(filenames ...string)
MustLoad will read your env file(s) and load them into ENV for this process.
Call this function as close as possible to the start of your program (ideally in main)
If you call Load without any args it will default to loading .env in the current path. If there are any errors the function will panic.
You can otherwise tell it which files to load (there can be more than one) like
env.MustLoad("fileone", "filetwo")
It's important to note that it WILL NOT OVERRIDE an env variable that already exists - consider the .env file to set dev vars or sensible defaults
func MustOverload ¶ added in v0.2.7
func MustOverload(filenames ...string)
MustOverload will read your env file(s) and load them into ENV for this process.
Call this function as close as possible to the start of your program (ideally in main)
If you call Overload without any args it will default to loading .env in the current path ¶
You can otherwise tell it which files to load (there can be more than one) like
env.MustOverload("fileone", "filetwo")
It's important to note this WILL OVERRIDE an env variable that already exists - consider the .env file to forcefilly set all vars.
func Overload ¶ added in v0.2.5
Overload will read your env file(s) and load them into ENV for this process.
Call this function as close as possible to the start of your program (ideally in main)
If you call Overload without any args it will default to loading .env in the current path ¶
You can otherwise tell it which files to load (there can be more than one) like
err := env.Overload("fileone", "filetwo")
It's important to note this WILL OVERRIDE an env variable that already exists - consider the .env file to forcefilly set all vars.
func Parse ¶
func Parse(v interface{}) error
Parse parses a struct containing `env` tags and loads its values from environment variables.
Example ¶
type config struct {
Home string `env:"HOME"`
Port int `env:"PORT" envDefault:"3000"`
IsProduction bool `env:"PRODUCTION"`
}
os.Setenv("HOME", "/tmp/fakehome")
cfg := config{}
_ = Parse(&cfg)
fmt.Println(cfg)
Output: {/tmp/fakehome 3000 false}
func ParseIO ¶ added in v0.2.5
ParseIO reads an env file from io.Reader, returning a map of keys and values.
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.
func ParseWithPrefix ¶
ParseWithPrefix parses a struct containing `env` tags and loads its values from environment variables. The actual env vars looked up include the passed in prefix.
func ParseWithPrefixFuncs ¶
func ParseWithPrefixFuncs(v interface{}, prefix string, funcMap CustomParsers) error
ParseWithPrefixFuncs is the same as `ParseWithPrefix` except it also allows the user to pass in custom parsers.
func Read ¶ added in v0.2.5
Read all env (with same file loading semantics as Load) but return values as a map rather than automatically writing values into env
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