env

package module
v1.0.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 14, 2024 License: MIT Imports: 9 Imported by: 0

README

env

Build Status Coverage Status

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

Fork-note: The only difference with the original library is that env tag names are returned and has more priority than field names in every error derivated from ParseError. Also, unit tests has been updated to take that into account.

Used and supported by

encore icon

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

Example

Get the module with:

go get github.com/0xc000022070/env/v11

The usage looks like this:

package main

import (
 "fmt"
 "time"

 "github.com/0xc000022070/env/v11"
)

type config struct {
 Home         string         `env:"HOME"`
 Port         int            `env:"PORT" envDefault:"3000"`
 Password     string         `env:"PASSWORD,unset"`
 IsProduction bool           `env:"PRODUCTION"`
 Duration     time.Duration  `env:"DURATION"`
 Hosts        []string       `env:"HOSTS" envSeparator:":"`
 TempFolder   string         `env:"TEMP_FOLDER,expand" envDefault:"${HOME}/tmp"`
 StringInts   map[string]int `env:"MAP_STRING_INT"`
}

func main() {
 cfg := config{}
 if err := env.Parse(&cfg); err != nil {
  fmt.Printf("%+v\n", err)
 }

  // or you can use generics
  cfg, err := env.ParseAs[config]()
  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 MAP_STRING_INT=k1:1,k2:2 go run main.go
{Home:/your/home Port:3000 IsProduction:true Hosts:[host1 host2 host3] Duration:1s StringInts:map[k1:1 k2:2]}

Caveats

[!CAUTION]

Unexported fields will be ignored by env. This is by design and will not change.

Supported types and defaults

Out of the box all built-in types are supported, plus a few others that are commonly used.

Complete list:

  • string
  • bool
  • int
  • int8
  • int16
  • int32
  • int64
  • uint
  • uint8
  • uint16
  • uint32
  • uint64
  • float32
  • float64
  • time.Duration
  • encoding.TextUnmarshaler
  • url.URL

Pointers, slices and slices of pointers, and maps of those types are also supported.

You can also use/define a custom parser func for any other type you want.

You can also use custom keys and values in your maps, as long as you provide a parser function for them.

If you set the envDefault tag for something, this value will be used in the case of absence of it in the environment.

By default, slice types will split the environment value on ,; you can change this behavior by setting the envSeparator tag. For map types, the default separator between key and value is : and , for key-value pairs. The behavior can be changed by setting the envKeyValSeparator and envSeparator tags accordingly.

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.ParseWithOptions() function.

In addition to accepting a struct pointer (same as Parse()), this function also accepts a Options{}, and you can set your custom parsers in the FuncMap field.

If you add a custom parser for, say Foo, it will also be used to parse *Foo and []Foo types.

Check the examples in the go doc for more info.

A note about TextUnmarshaler and time.Time

Env supports by default anything that implements the TextUnmarshaler interface. That includes things like time.Time for example. The upside is that depending on the format you need, you don't need to change anything. The downside is that if you do need time in another format, you'll need to create your own type.

Its fairly straightforward:

type MyTime time.Time

func (t *MyTime) UnmarshalText(text []byte) error {
 tt, err := time.Parse("2006-01-02", string(text))
 *t = MyTime(tt)
 return err
}

type Config struct {
 SomeTime MyTime `env:"SOME_TIME"`
}

And then you can parse Config with env.Parse.

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 {
 SecretKey string `env:"SECRET_KEY,required"`
}

[!NOTE]

Note that being set is not the same as being empty. If the variable is set, but empty, the field will have its type's default value. This also means that custom parser funcs will not be invoked.

Expand vars

If you set the expand option, environment variables (either in ${var} or $var format) in the string will be replaced according with the actual value of the variable. For example:

type config struct {
 SecretKey string `env:"SECRET_KEY,expand"`
}

This also works with envDefault:

import (
 "fmt"
 "github.com/0xc000022070/env/v11"
)

type config struct {
 Host     string `env:"HOST" envDefault:"localhost"`
 Port     int    `env:"PORT" envDefault:"3000"`
 Address  string `env:"ADDRESS,expand" envDefault:"$HOST:${PORT}"`
}

func main() {
 cfg := config{}
 if err := env.Parse(&cfg); err != nil {
  fmt.Printf("%+v\n", err)
 }
 fmt.Printf("%+v\n", cfg)
}

results in this:

$ PORT=8080 go run main.go
{Host:localhost Port:8080 Address:localhost:8080}

Not Empty fields

While required demands the environment variable to be set, it doesn't check its value. If you want to make sure the environment is set and not empty, you need to use the notEmpty tag option instead (env:"SOME_ENV,notEmpty").

Example:

type config struct {
 SecretKey string `env:"SECRET_KEY,notEmpty"`
}

Unset environment variable after reading it

The env tag option unset (e.g., env:"tagKey,unset") can be added to ensure that some environment variable is unset after reading it.

Example:

type config struct {
 SecretKey string `env:"SECRET_KEY,unset"`
}

From file

The env tag option file (e.g., env:"tagKey,file") can be added in order to indicate that the value of the variable shall be loaded from a file. The path of that file is given by the environment variable associated with it:

package main

import (
 "fmt"
 "time"

 "github.com/0xc000022070/env/v11"
)

type config struct {
 Secret      string `env:"SECRET,file"`
 Password    string `env:"PASSWORD,file"           envDefault:"/tmp/password"`
 Certificate string `env:"CERTIFICATE,file,expand" envDefault:"${CERTIFICATE_FILE}"`
}

func main() {
 cfg := config{}
 if err := env.Parse(&cfg); err != nil {
  fmt.Printf("%+v\n", err)
 }

 fmt.Printf("%+v\n", cfg)
}

$ echo qwerty > /tmp/secret
$ echo dvorak > /tmp/password
$ echo coleman > /tmp/certificate

$ SECRET=/tmp/secret  \
 CERTIFICATE_FILE=/tmp/certificate \
 go run main.go
{Secret:qwerty Password:dvorak Certificate:coleman}

Options

Use field names as environment variables by default

If you don't want to set the env tag on every field, you can use the UseFieldNameByDefault option.

It will use the field name to define the environment variable name. So, Foo becomes FOO, FooBar becomes FOO_BAR, and so on.

Here's an example:

package main

import (
 "fmt"
 "log"

 "github.com/0xc000022070/env/v11"
)

type Config struct {
 Username     string // will use $USERNAME
 Password     string // will use $PASSWORD
 UserFullName string // will use $USER_FULL_NAME
}

func main() {
 cfg := &Config{}
 opts := env.Options{UseFieldNameByDefault: true}

 // Load env vars.
 if err := env.ParseWithOptions(cfg, opts); err != nil {
  log.Fatal(err)
 }

 // Print the loaded data.
 fmt.Printf("%+v\n", cfg)
}
Environment

By setting the Options.Environment map you can tell Parse to add those keys and values as env vars before parsing is done. These envs are stored in the map and never actually set by os.Setenv. This option effectively makes env ignore the OS environment variables: only the ones provided in the option are used.

This can make your testing scenarios a bit more clean and easy to handle.

package main

import (
 "fmt"
 "log"

 "github.com/0xc000022070/env/v11"
)

type Config struct {
 Password string `env:"PASSWORD"`
}

func main() {
 cfg := &Config{}
 opts := env.Options{Environment: map[string]string{
  "PASSWORD": "MY_PASSWORD",
 }}

 // Load env vars.
 if err := env.ParseWithOptions(cfg, opts); err != nil {
  log.Fatal(err)
 }

 // Print the loaded data.
 fmt.Printf("%+v\n", cfg)
}
Changing default tag name

You can change what tag name to use for setting the env vars by setting the Options.TagName variable.

For example

package main

import (
 "fmt"
 "log"

 "github.com/0xc000022070/env/v11"
)

type Config struct {
 Password string `json:"PASSWORD"`
}

func main() {
 cfg := &Config{}
 opts := env.Options{TagName: "json"}

 // Load env vars.
 if err := env.ParseWithOptions(cfg, opts); err != nil {
  log.Fatal(err)
 }

 // Print the loaded data.
 fmt.Printf("%+v\n", cfg)
}
Prefixes

You can prefix sub-structs env tags, as well as a whole env.Parse call.

Here's an example flexing it a bit:

package main

import (
 "fmt"
 "log"

 "github.com/0xc000022070/env/v11"
)

type Config struct {
 Home string `env:"HOME"`
}

type ComplexConfig struct {
 Foo   Config `envPrefix:"FOO_"`
 Clean Config
 Bar   Config `envPrefix:"BAR_"`
 Blah  string `env:"BLAH"`
}

func main() {
 cfg := &ComplexConfig{}
 opts := env.Options{
  Prefix: "T_",
  Environment: map[string]string{
   "T_FOO_HOME": "/foo",
   "T_BAR_HOME": "/bar",
   "T_BLAH":     "blahhh",
   "T_HOME":     "/clean",
  },
 }

 // Load env vars.
 if err := env.ParseWithOptions(cfg, opts); err != nil {
  log.Fatal(err)
 }

 // Print the loaded data.
 fmt.Printf("%+v\n", cfg)
}
On set hooks

You might want to listen to value sets and, for example, log something or do some other kind of logic. You can do this by passing a OnSet option:

package main

import (
 "fmt"
 "log"

 "github.com/0xc000022070/env/v11"
)

type Config struct {
 Username string `env:"USERNAME" envDefault:"admin"`
 Password string `env:"PASSWORD"`
}

func main() {
 cfg := &Config{}
 opts := env.Options{
  OnSet: func(tag string, value interface{}, isDefault bool) {
   fmt.Printf("Set %s to %v (default? %v)\n", tag, value, isDefault)
  },
 }

 // Load env vars.
 if err := env.ParseWithOptions(cfg, opts); err != nil {
  log.Fatal(err)
 }

 // Print the loaded data.
 fmt.Printf("%+v\n", cfg)
}

Making all fields to required

You can make all fields that don't have a default value be required by setting the RequiredIfNoDef: true in the Options.

For example

package main

import (
 "fmt"
 "log"

 "github.com/0xc000022070/env/v11"
)

type Config struct {
 Username string `env:"USERNAME" envDefault:"admin"`
 Password string `env:"PASSWORD"`
}

func main() {
 cfg := &Config{}
 opts := env.Options{RequiredIfNoDef: true}

 // Load env vars.
 if err := env.ParseWithOptions(cfg, opts); err != nil {
  log.Fatal(err)
 }

 // Print the loaded data.
 fmt.Printf("%+v\n", cfg)
}

Defaults from code

You may define default value also in code, by initialising the config data before it's filled by env.Parse. Default values defined as struct tags will overwrite existing values during Parse.

package main

import (
 "fmt"
 "log"

 "github.com/0xc000022070/env/v11"
)

type Config struct {
 Username string `env:"USERNAME" envDefault:"admin"`
 Password string `env:"PASSWORD"`
}

func main() {
 cfg := Config{
  Username: "test",
  Password: "123456",
 }

 if err := env.Parse(&cfg); err != nil {
  fmt.Println("failed:", err)
 }

 fmt.Printf("%+v", cfg) // {Username:admin Password:123456}
}

Error handling

You can handle the errors the library throws like so:

package main

import (
 "fmt"
 "log"

 "github.com/0xc000022070/env/v11"
)

type Config struct {
 Username string `env:"USERNAME" envDefault:"admin"`
 Password string `env:"PASSWORD"`
}

func main() {
 var cfg Config
 err := env.Parse(&cfg)
 if e, ok := err.(*env.AggregateError); ok {
  for _, er := range e.Errors {
   switch v := er.(type) {
   case env.ParseError:
    // handle it
   case env.NotStructPtrError:
    // handle it
   case env.NoParserError:
    // handle it
   case env.NoSupportedTagOptionError:
    // handle it
   default:
    fmt.Printf("Unknown error type %v", v)
   }
  }
 }

 fmt.Printf("%+v", cfg) // {Username:admin Password:123456}
}

Info

If you want to check if an specific error is in the chain, you can also use errors.Is().

  • envdoc - generate documentation for environment variables from env tags

Stargazers over time

Stargazers over time

Documentation

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func Must 

func Must[T any](t T, err error) T

Must panic is if err is not nil, and returns t otherwise.

func Parse 

func Parse(v interface{}) error

Parse parses a struct containing `env` tags and loads its values from environment variables.

Example 
type inner struct {
	Foo string `env:"FOO" envDefault:"foobar"`
}
type config struct {
	Home         string         `env:"HOME,required"`
	Port         int            `env:"PORT" envDefault:"3000"`
	IsProduction bool           `env:"PRODUCTION"`
	TempFolder   string         `env:"TEMP_FOLDER,expand" envDefault:"${HOME}/.tmp"`
	StringInts   map[string]int `env:"MAP_STRING_INT" envDefault:"k1:1,k2:2"`
	Inner        inner
}
os.Setenv("HOME", "/tmp/fakehome")
var cfg config
if err := Parse(&cfg); err != nil {
	fmt.Println("failed:", err)
}
fmt.Printf("%+v", cfg)

Output:

{Home:/tmp/fakehome Port:3000 IsProduction:false TempFolder:/tmp/fakehome/.tmp StringInts:map[k1:1 k2:2] Inner:{Foo:foobar}}
Example (Defaults) 
type config struct {
	A string `env:"FOO" envDefault:"foo"`
	B string `env:"FOO"`
}

// env FOO is not set

cfg := config{
	A: "A",
	B: "B",
}
if err := Parse(&cfg); err != nil {
	fmt.Println("failed:", err)
}
fmt.Printf("%+v", cfg)

Output:

{A:foo B:B}
Example (OnSet) 
type config struct {
	Home         string `env:"HOME,required"`
	Port         int    `env:"PORT" envDefault:"3000"`
	IsProduction bool   `env:"PRODUCTION"`
	NoEnvTag     bool
	Inner        struct{} `envPrefix:"INNER_"`
}
os.Setenv("HOME", "/tmp/fakehome")
var cfg config
if err := ParseWithOptions(&cfg, Options{
	OnSet: func(tag string, value interface{}, isDefault bool) {
		fmt.Printf("Set %s to %v (default? %v)\n", tag, value, isDefault)
	},
}); err != nil {
	fmt.Println("failed:", err)
}
fmt.Printf("%+v", cfg)

Output:

Set HOME to /tmp/fakehome (default? false)
Set PORT to 3000 (default? true)
Set PRODUCTION to  (default? false)
{Home:/tmp/fakehome Port:3000 IsProduction:false NoEnvTag:false Inner:{}}

func ParseAs 

func ParseAs[T any]() (T, error)

ParseAs parses the given struct type containing `env` tags and loads its values from environment variables.

func ParseAsWithOptions 

func ParseAsWithOptions[T any](opts Options) (T, error)

ParseWithOptions parses the given struct type containing `env` tags and loads its values from environment variables.

func ParseWithOptions 

func ParseWithOptions(v interface{}, opts Options) error

ParseWithOptions parses a struct containing `env` tags and loads its values from environment variables.

Example 
type thing struct {
	desc string
}

type conf struct {
	Thing thing `env:"THING"`
}

os.Setenv("THING", "my thing")

c := conf{}

err := ParseWithOptions(&c, Options{FuncMap: map[reflect.Type]ParserFunc{
	reflect.TypeOf(thing{}): func(v string) (interface{}, error) {
		return thing{desc: v}, nil
	},
}})
if err != nil {
	fmt.Println(err)
}
fmt.Println(c.Thing.desc)

Output:

my thing

func ToMap 

func ToMap(env []string) map[string]string

ToMap Converts list of env vars as provided by os.Environ() to map you can use as Options.Environment field

Types

type AggregateError 

type AggregateError struct {
	Errors []error
}

An aggregated error wrapper to combine gathered errors. This allows either to display all errors or convert them individually List of the available errors ParseError NotStructPtrError NoParserError NoSupportedTagOptionError EnvVarIsNotSetError EmptyEnvVarError LoadFileContentError ParseValueError

func (AggregateError) Error 

func (e AggregateError) Error() string

func (AggregateError) Is 

func (e AggregateError) Is(err error) bool

Is conforms with errors.Is.

type EmptyEnvVarError 

type EmptyEnvVarError struct {
	Key string
}

This error occurs when the variable which must be not empty is existing but has an empty value Read about not empty fields: https://github.com/0xc000022070/env#not-empty-fields

func (EmptyEnvVarError) Error 

func (e EmptyEnvVarError) Error() string

type EnvVarIsNotSetError 

type EnvVarIsNotSetError struct {
	Key string
}

This error occurs when the required variable is not set Read about required fields: https://github.com/0xc000022070/env#required-fields

func (EnvVarIsNotSetError) Error 

func (e EnvVarIsNotSetError) Error() string

type FieldParams 

type FieldParams struct {
	OwnKey          string
	Key             string
	DefaultValue    string
	HasDefaultValue bool
	Required        bool
	LoadFile        bool
	Unset           bool
	NotEmpty        bool
	Expand          bool
}

FieldParams contains information about parsed field tags.

func GetFieldParams 

func GetFieldParams(v interface{}) ([]FieldParams, error)

GetFieldParams parses a struct containing `env` tags and returns information about tags it found.

func GetFieldParamsWithOptions 

func GetFieldParamsWithOptions(v interface{}, opts Options) ([]FieldParams, error)

GetFieldParamsWithOptions parses a struct containing `env` tags and returns information about tags it found.

type LoadFileContentError 

type LoadFileContentError struct {
	Filename string
	Key      string
	Err      error
}

This error occurs when it's impossible to load the value from the file Read about From file feature: https://github.com/0xc000022070/env#from-file

func (LoadFileContentError) Error 

func (e LoadFileContentError) Error() string

type NoParserError 

type NoParserError struct {
	Name string
	Type reflect.Type
}

This error occurs when there is no parser provided for given type Supported types and defaults: https://github.com/0xc000022070/env#supported-types-and-defaults How to create a custom parser: https://github.com/0xc000022070/env#custom-parser-funcs

func (NoParserError) Error 

func (e NoParserError) Error() string

type NoSupportedTagOptionError 

type NoSupportedTagOptionError struct {
	Tag string
}

This error occurs when the given tag is not supported In-built supported tags: "", "file", "required", "unset", "notEmpty", "expand", "envDefault", "envSeparator" How to create a custom tag: https://github.com/0xc000022070/env#changing-default-tag-name

func (NoSupportedTagOptionError) Error 

func (e NoSupportedTagOptionError) Error() string

type NotStructPtrError 

type NotStructPtrError struct{}

The error occurs when pass something that is not a pointer to a Struct to Parse

func (NotStructPtrError) Error 

func (e NotStructPtrError) Error() string

type OnSetFn 

type OnSetFn func(tag string, value interface{}, isDefault bool)

OnSetFn is a hook that can be run when a value is set.

type Options 

type Options struct {
	// Environment keys and values that will be accessible for the service.
	Environment map[string]string

	// TagName specifies another tagname to use rather than the default env.
	TagName string

	// RequiredIfNoDef automatically sets all env as required if they do not
	// declare 'envDefault'.
	RequiredIfNoDef bool

	// OnSet allows to run a function when a value is set.
	OnSet OnSetFn

	// Prefix define a prefix for each key.
	Prefix string

	// UseFieldNameByDefault defines whether or not env should use the field
	// name by default if the `env` key is missing.
	// Note that the field name will be "converted" to conform with environment
	// variable names conventions.
	UseFieldNameByDefault bool

	// Custom parse functions for different types.
	FuncMap map[reflect.Type]ParserFunc
	// contains filtered or unexported fields
}

Options for the parser.

type ParseError 

type ParseError struct {
	Name string
	Type reflect.Type
	Err  error
}

The error occurs when it's impossible to convert the value for given type.

func (ParseError) Error 

func (e ParseError) Error() string

type ParseValueError 

type ParseValueError struct {
	Msg string
	Err error
}

This error occurs when it's impossible to convert value using given parser Supported types and defaults: https://github.com/0xc000022070/env#supported-types-and-defaults How to create a custom parser: https://github.com/0xc000022070/env#custom-parser-funcs

func (ParseValueError) Error 

func (e ParseValueError) Error() string

type ParserFunc 

type ParserFunc func(v string) (interface{}, error)

ParserFunc defines the signature of a function that can be used within `CustomParsers`.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.