Awesome
<p align="center"> <img alt="GoReleaser Logo" src="https://becker.software/env.png" height="140" /> <p align="center">A simple, zero-dependencies library to parse environment variables into structs.</p> </p>Installation
go get github.com/caarlos0/env/v11
Getting started
type config struct {
Home string `env:"HOME"`
}
// parse
var cfg config
err := env.Parse(&cfg)
// parse with generics
cfg, err := env.ParseAs[config]()
You can see the full documentation and list of examples at pkg.go.dev.
Used and supported by
<p> <a href="https://encore.dev"> <img src="https://user-images.githubusercontent.com/78424526/214602214-52e0483a-b5fc-4d4c-b03e-0b7b23e012df.svg" width="120px" alt="encore icon" /> </a> <br/> <br/> <b>Encore – the platform for building Go-based cloud backends.</b> <br/> </p>Usage
Caveats
[!CAUTION]
Unexported fields will be ignored by
env
. This is by design and will not change.
Functions
Parse
: parse the current environment into a typeParseAs
: parse the current environment into a type using genericsParseWithOptions
: parse the current environment into a type with custom optionsParseAsithOptions
: parse the current environment into a type with custom options and using genericsMust
: can be used to wrapParse.*
calls to panic on errorGetFieldParams
: get theenv
parsed options for a typeGetFieldParamsWithOptions
: get theenv
parsed options for a type with custom options
Supported types
Out of the box all built-in types are supported, plus a few others that are commonly used.
Complete list:
bool
float32
float64
int16
int32
int64
int8
int
string
uint16
uint32
uint64
uint8
uint
time.Duration
time.Location
encoding.TextUnmarshaler
url.URL
Pointers, slices and slices of pointers, and maps of those types are also supported.
You may also add custom parsers for your types.
Tags
The following tags are provided:
env
: sets the environment variable name and optionally takes the tag options described belowenvDefault
: sets the default value for the fieldenvPrefix
: can be used in a field that is a complex type to set a prefix to all environment variables used in itenvSeparator
: sets the character to be used to separate items in slices and maps (default:,
)envKeyValSeparator
: sets the character to be used to separate keys and their values in maps (default::
)
env
tag options
Here are all the options available for the env
tag:
,expand
: expands environment variables, e.g.FOO_${BAR}
,file
: instructs that the content of the variable is a path to a file that should be read,init
: initialize nil pointers,notEmpty
: make the field errors if the environment variable is empty,required
: make the field errors if the environment variable is not set,unset
: unset the environment variable after use
Parse Options
There are a few options available in the functions that end with WithOptions
:
Environment
: keys and values to be used instead ofos.Environ()
TagName
: specifies another tag name to use rather than the defaultenv
RequiredIfNoDef
: set allenv
fields as required if they do not declareenvDefault
OnSet
: allows to hook into theenv
parsing and do something when a value is setPrefix
: prefix to be used in all environment variablesUseFieldNameByDefault
: defines whether or notenv
should use the field name by default if theenv
key is missingFuncMap
: custom parse functions for custom types
Documentation and examples
Examples are live in pkg.go.dev, and also in the example test file.
Current state
env
is considered feature-complete.
I do not intent to add any new features unless they really make sense, and are requested by many people.
Eventual bug fixes will keep being merged.
Badges
Related projects
- envdoc - generate documentation for environment variables from
env
tags