Repository files navigation

A simple, zero-dependencies library to parse environment variables into structs.

go get github.com/caarlos0/env/v11

typeconfigstruct {Homestring`env:"HOME"`}// parsevarcfgconfigerr:=env.Parse(&cfg)// parse with genericscfg,err:=env.ParseAs[config]()

You can see the full documentation and list of examples atpkg.go.dev.

Encore – the platform for building Go-based cloud backends.

• Parse: parse the current environment into a type
• ParseAs: parse the current environment into a type using generics
• ParseWithOptions: parse the current environment into a type with custom options
• ParseAsWithOptions: parse the current environment into a type with custom options and using generics
• Must: can be used to wrapParse.* calls to panic on error
• GetFieldParams: get theenv parsed options for a type
• GetFieldParamsWithOptions: get theenv parsed options for a type with custom options

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.

The following tags are provided:

• env: sets the environment variable name and optionally takes the tag options described below
• envDefault: sets the default value for the field
• envPrefix: can be used in a field that is a complex type to set a prefix to all environment variables used in it
• envSeparator: 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::)

Here are all the options available for theenv 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

There are a few options available in the functions that end withWithOptions:

• Environment: keys and values to be used instead ofos.Environ()
• TagName: specifies another tag name to use rather than the defaultenv
• PrefixTagName: specifies another prefix tag name to use rather than the defaultenvPrefix
• DefaultValueTagName: specifies another default tag name to use rather than the defaultenvDefault
• 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 set
• Prefix: prefix to be used in all environment variables
• UseFieldNameByDefault: defines whether or notenv should use the field name by default if theenv key is missing
• FuncMap: custom parse functions for custom types

Examples are live inpkg.go.dev,and also in theexample test file.

env is considered feature-complete.

I do not intent to add any new features unless they really make sense, and arerequested by many people.

Eventual bug fixes will keep being merged.

• envdoc - generate documentation for environment variables fromenv tags