asserchiu/env

A KISS way to deal with environment variables in Go.

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"`
}

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:

• string
• int
• uint
• int64
• bool
• float32
• float64
• time.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.

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"`
}