fromenv

README

fromenv

import "github.com/alfred-landrum/fromenv"

Overview

Package fromenv can set tagged struct fields with values from the environment. See the godoc for full documentation and examples.

Documentation

Overview

Package fromenv can set tagged struct fields with values from the environment.

Example

var c struct {
	Field1 string `env:"KEY1"`
}
os.Setenv("KEY1", "foo")
_ = Unmarshal(&c)
fmt.Println(c.Field1)
// Ouput: foo

Example (Default)

var c struct {
	Field1 string `env:"KEY1=key1default"`
}

os.Unsetenv("KEY1")

_ = Unmarshal(&c)
fmt.Println(c.Field1)

Output:

key1default

Example (Inner)

var c struct {
	Inner struct {
		Field2 string `env:"KEY2"`
	}
}

os.Setenv("KEY2", "inner too")

_ = Unmarshal(&c)
fmt.Println(c.Inner.Field2)

Output:

inner too

Index

• func Unmarshal(in interface{}, options ...Option) error
• type LookupEnvFunc
• type Option
  • func DefaultsOnly() Option
  • func Looker(f LookupEnvFunc) Option
  • func Map(m map[string]string) Option
  • func SetFunc(fn interface{}) Option

Examples

• Package
• Package (Default)
• Package (Inner)
• SetFunc

Functions

func Unmarshal

func Unmarshal(in interface{}, options ...Option) error

Unmarshal takes a pointer to a struct, recursively looks for struct fields with a "env" tag, and, by default, uses the os.LookupEnv function to determine the desired value from the environment.

An env tag may optionally specify a default desired value; if no entry exists in the environment for the field's key, then the desired value of the field will be this default value.

Unmarshal will set the struct field (of type T) to the desired value by whichever method matches first:

* Using a function of type "func(*T, string) error" configured via SetFunc.

* If T satisfies an interface of `func Set(string) error`, then its Set function.

* If T is a boolean, numeric, or string type, then the appropriate strconv function will be used.

Unmarshal will return an error if the env tag is used on a struct field that can't be set with any of the above, or if the value's setting function fails.

Types

type LookupEnvFunc

type LookupEnvFunc func(key string) (value *string, err error)

A LookupEnvFunc retrieves the value of the environment variable named by the key. If the variable isn't present, a nil pointer is returned.

type Option

type Option func(*config)

An Option is a functional option for Unmarshal.

func DefaultsOnly

func DefaultsOnly() Option

DefaultsOnly configures Unmarshal to only set fields with a tag-defined default to that default, ignoring other fields and the environment.

func Looker

func Looker(f LookupEnvFunc) Option

Looker configures the environment lookup function used during an Unmarshal call.

func Map

func Map(m map[string]string) Option

Map configures Unmarshal to use the given map for environment lookups.

func SetFunc

func SetFunc(fn interface{}) Option

SetFunc takes a function of form "func(*T, string) error", and configures Unmarshal to use that function to set the value of any type T's.

Example

durSetter := func(t *time.Duration, s string) error {
	x, err := time.ParseDuration(s)
	*t = x
	return err
}

urlSetter := func(u *url.URL, s string) error {
	x, err := url.Parse(s)
	*u = *x
	return err
}

type config struct {
	Timeout time.Duration `env:"GAP=1000ms"`
	Server  *url.URL      `env:"PLACE=http://www.github.com"`
}

var c config
_ = Unmarshal(&c, SetFunc(durSetter), SetFunc(urlSetter))
fmt.Println(c.Timeout, c.Server.Hostname())

Output:

1s www.github.com