envconfig

// This example demonstrates the basic usage for envconfig.

type MyStruct struct {
	Port     int    `env:"PORT"`
	Username string `env:"USERNAME"`
}

// Set some environment variables in the process:
//
//     export PORT=5555
//     export USERNAME=yoyo
//

var s MyStruct
if err := envconfig.Process(ctx, &s); err != nil {
	panic(err) // TODO: handle error
}

// c.Port = 5555
// c.Username = "yoyo"

Output:

// This example demonstrates how to set global configuration options that
// apply to all decoding (unless overridden at the field level).

type HTTPConfig struct {
	AllowedHeaders  map[string]string `env:"ALLOWED_HEADERS"`
	RejectedHeaders map[string]string `env:"REJECTED_HEADERS, delimiter=|"`
}

var httpConfig HTTPConfig
if err := envconfig.ProcessWith(ctx, &envconfig.Config{
	Target: &httpConfig,

	// All fields will use a ";" delimiter and "@" separator, unless locally
	// overridden.
	DefaultDelimiter: ";",
	DefaultSeparator: "@",

	Lookuper: envconfig.MapLookuper(map[string]string{
		"ALLOWED_HEADERS":  "header1@value1;header2@value2",
		"REJECTED_HEADERS": "header3@value3|header4@value4",
	}),
}); err != nil {
	panic(err)
}

fmt.Printf("allowed: %v\n", httpConfig.AllowedHeaders)
fmt.Printf("rejected: %v\n", httpConfig.RejectedHeaders)

Output:

allowed: map[header1:value1 header2:value2]
rejected: map[header3:value3 header4:value4]

package main

import (
	"encoding/json"
	"fmt"

	"github.com/diegosz/go-envconfig"
)

type CustomStruct struct {
	Port string `json:"port"`
	User string `json:"user"`
	Max  int    `json:"max"`
}

func (s *CustomStruct) EnvDecode(val string) error {
	return json.Unmarshal([]byte(val), s)
}

func main() {
	// This example demonstrates defining a custom decoder function.

	type MyStruct struct {
		Config CustomStruct `env:"CONFIG"`
	}

	var s MyStruct
	if err := envconfig.ProcessWith(ctx, &envconfig.Config{
		Target: &s,
		Lookuper: envconfig.MapLookuper(map[string]string{
			"CONFIG": `{
				"port": "8080",
				"user": "yoyo",
				"max": 51
			}`,
		}),
	}); err != nil {
		panic(err) // TODO: handle error
	}

	fmt.Printf("port: %v\n", s.Config.Port)
	fmt.Printf("user: %v\n", s.Config.User)
	fmt.Printf("max: %v\n", s.Config.Max)

}

Output:

port: 8080
user: yoyo
max: 51

// This example demonstrates forcing envconfig to run decoders, even on unset
// environment variables.

type MyStruct struct {
	UrlA *url.URL `env:"URL_A"`
	UrlB *url.URL `env:"URL_B, decodeunset"`
}

var s MyStruct
if err := envconfig.Process(ctx, &s); err != nil {
	panic(err)
}

fmt.Printf("urlA: %s\n", s.UrlA)
fmt.Printf("urlB: %s\n", s.UrlB)

Output:

urlA: //@
urlB:

// This example demonstrates how to set default values for fields. Fields will
// use their default value if no value is provided for that key in the
// environment.

type MyStruct struct {
	Port     int    `env:"PORT, default=8080"`
	Username string `env:"USERNAME, default=$OTHER_ENV"`
}

var s MyStruct
if err := envconfig.Process(ctx, &s); err != nil {
	panic(err) // TODO: handle error
}

fmt.Printf("port: %d\n", s.Port)

Output:

port: 8080

// This example demonstrates how struct-level configuration options are
// propagated to child fields and structs.

type Credentials struct {
	Username string `env:"USERNAME"`
	Password string `env:"PASSWORD"`
}

type Metadata struct {
	Headers map[string]string  `env:"HEADERS"`
	Footers []string           `env:"FOOTERS"`
	Margins map[string]float64 `env:"MARGINS, delimiter=\\,, separator=:"`
}

type ConnectionInfo struct {
	Address string `env:"ADDRESS"`

	// All child fields will be required.
	Credentials *Credentials `env:",required"`

	// All child fields will use a ";" delimiter and "@" separator, unless
	// locally overridden.
	Metadata *Metadata `env:",delimiter=;, separator=@"`
}

var conn ConnectionInfo
if err := envconfig.ProcessWith(ctx, &envconfig.Config{
	Target: &conn,
	Lookuper: envconfig.MapLookuper(map[string]string{
		"ADDRESS":  "127.0.0.1",
		"USERNAME": "user",
		"PASSWORD": "pass",
		"HEADERS":  "header1@value1;header2@value2",
		"FOOTERS":  "footer1; footer2",
		"MARGINS":  "top:0.5, bottom:1.5",
	}),
}); err != nil {
	panic(err)
}

fmt.Printf("address: %q\n", conn.Address)
fmt.Printf("username: %q\n", conn.Credentials.Username)
fmt.Printf("password: %q\n", conn.Credentials.Password)
fmt.Printf("headers: %v\n", conn.Metadata.Headers)
fmt.Printf("footers: %q\n", conn.Metadata.Footers)
fmt.Printf("margins: %v\n", conn.Metadata.Margins)

Output:

address: "127.0.0.1"
username: "user"
password: "pass"
headers: map[header1:value1 header2:value2]
footers: ["footer1" "footer2"]
margins: map[bottom:1.5 top:0.5]

// This example demonstrates using a [MapLookuper] to source environment
// variables from a map instead of the environment. The map will always be of
// type string=string, because environment variables are always string types.

type MyStruct struct {
	Port     int    `env:"PORT"`
	Username string `env:"USERNAME"`
}

var s MyStruct
if err := envconfig.ProcessWith(ctx, &envconfig.Config{
	Target: &s,
	Lookuper: envconfig.MapLookuper(map[string]string{
		"PORT":     "5555",
		"USERNAME": "yoyo",
	}),
}); err != nil {
	panic(err) // TODO: handle error
}

fmt.Printf("port: %d\n", s.Port)
fmt.Printf("username: %q\n", s.Username)

Output:

port: 5555
username: "yoyo"

package main

import (
	"context"
	"fmt"

	"github.com/diegosz/go-envconfig"
)

// MyMutator is a mutator that keeps a count of all mutated values, appending
// the current count to each environment variable that is processed.
type MyMutator struct {
	counter int
}

func (m *MyMutator) EnvMutate(ctx context.Context, originalKey, resolvedKey, originalValue, currentValue string) (newValue string, stop bool, err error) {
	m.counter++
	return fmt.Sprintf("%s-%d", currentValue, m.counter), false, nil
}

func main() {
	// This exmaple demonstrates authoring a complex mutator that modifies
	// environment variable values before processing.

	type MyStruct struct {
		FieldA string `env:"FIELD_A"`
		FieldB string `env:"FIELD_B"`
		FieldC string `env:"FIELD_C"`
		FieldD string `env:"FIELD_D"`
	}

	var s MyStruct
	if err := envconfig.ProcessWith(ctx, &envconfig.Config{
		Target: &s,
		Lookuper: envconfig.MapLookuper(map[string]string{
			"FIELD_A": "a",
			"FIELD_B": "b",
			"FIELD_C": "c",
		}),
		Mutators: []envconfig.Mutator{&MyMutator{}},
	}); err != nil {
		panic(err) // TODO: handle error
	}

	fmt.Printf("field a: %q\n", s.FieldA)
	fmt.Printf("field b: %q\n", s.FieldB)
	fmt.Printf("field c: %q\n", s.FieldC)
	fmt.Printf("field d: %q\n", s.FieldD)

}

Output:

field a: "a-1"
field b: "b-2"
field c: "c-3"
field d: ""

// This example demonstrates authoring mutator functions to modify environment
// variable values before processing.

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

resolveSecretFunc := envconfig.MutatorFunc(func(ctx context.Context, originalKey, resolvedKey, originalValue, resolvedValue string) (newValue string, stop bool, err error) {
	if strings.HasPrefix(resolvedValue, "secret://") {
		v, err := secretmanager.Resolve(ctx, resolvedValue)
		if err != nil {
			return resolvedValue, true, fmt.Errorf("failed to access secret: %w", err)
		}
		return v, false, nil
	}
	return resolvedValue, false, nil
})

var s MyStruct
if err := envconfig.ProcessWith(ctx, &envconfig.Config{
	Target:   &s,
	Lookuper: envconfig.OsLookuper(),
	Mutators: []envconfig.Mutator{resolveSecretFunc},
}); err != nil {
	panic(err) // TODO: handle error
}

Output:

// This example demonstrates setting the "noinit" tag to bypass
// initialization.

type MyStruct struct {
	SecureA *bool `env:"SECURE_A"`
	SecureB *bool `env:"SECURE_B, noinit"`
}

var s MyStruct
if err := envconfig.Process(ctx, &s); err != nil {
	panic(err)
}

printVal := func(v *bool) string {
	if v != nil {
		return strconv.FormatBool(*v)
	}
	return "<nil>"
}

fmt.Printf("secureA: %s\n", printVal(s.SecureA))
fmt.Printf("secureB: %s\n", printVal(s.SecureB))

Output:

secureA: false
secureB: <nil>

// This example demonstrates how to tell envconfig to overwrite existing
// struct values.

type MyStruct struct {
	Port int `env:"PORT, overwrite"`
}

s := &MyStruct{
	Port: 1234,
}
if err := envconfig.ProcessWith(ctx, &envconfig.Config{
	Target: s,
	Lookuper: envconfig.MapLookuper(map[string]string{
		"PORT": "8080",
	}),
}); err != nil {
	panic(err) // TODO: handle error
}

fmt.Printf("port: %d\n", s.Port)

Output:

port: 8080

// This example demonstrates using prefixes to share structures.

type RedisConfig struct {
	Host string `env:"REDIS_HOST"`
	User string `env:"REDIS_USER"`
}

type ServerConfig struct {
	// CacheConfig will process values from $CACHE_REDIS_HOST and
	// $CACHE_REDIS_USER respectively.
	CacheConfig *RedisConfig `env:", prefix=CACHE_"`

	// RateLimitConfig will process values from $RATE_LIMIT_REDIS_HOST and
	// $RATE_LIMIT_REDIS_USER respectively.
	RateLimitConfig *RedisConfig `env:", prefix=RATE_LIMIT_"`
}

var s ServerConfig
if err := envconfig.ProcessWith(ctx, &envconfig.Config{
	Target: &s,
	Lookuper: envconfig.MapLookuper(map[string]string{
		"CACHE_REDIS_HOST":      "https://cache.host.internal",
		"CACHE_REDIS_USER":      "cacher",
		"RATE_LIMIT_REDIS_HOST": "https://limiter.host.internal",
		"RATE_LIMIT_REDIS_USER": "limiter",
	}),
}); err != nil {
	panic(err) // TODO: handle error
}

fmt.Printf("cache redis host: %s\n", s.CacheConfig.Host)
fmt.Printf("cache redis user: %s\n", s.CacheConfig.User)
fmt.Printf("rate limit redis host: %s\n", s.RateLimitConfig.Host)
fmt.Printf("rate limit redis user: %s\n", s.RateLimitConfig.User)

Output:

cache redis host: https://cache.host.internal
cache redis user: cacher
rate limit redis host: https://limiter.host.internal
rate limit redis user: limiter

// This example demonstrates using a [PrefixLookuper] to programatically alter
// environment variable keys to include the given prefix.

type MyStruct struct {
	Port int `env:"PORT"`
}

var s MyStruct
if err := envconfig.ProcessWith(ctx, &envconfig.Config{
	Target: &s,
	Lookuper: envconfig.PrefixLookuper("APP_", envconfig.MapLookuper(map[string]string{
		"APP_PORT": "1234",
	})),
}); err != nil {
	panic(err)
}

fmt.Printf("port: %d\n", s.Port)

Output:

port: 1234

// This example demonstrates how to set fields as required. Required fields
// will error if unset.

type MyStruct struct {
	Port int `env:"PORT, required"`
}

var s MyStruct
if err := envconfig.Process(ctx, &s); err != nil {
	fmt.Printf("error: %s\n", err)
}

Output:

error: Port: missing required value: PORT