env

README

Package env

This package facilitates loading environment variables into Go structures.

Key Features

• Load environment variables into configuration structure based on its env tags.
• typesafe environment variable Lookup
• Support for default values using default or env-default tags.
• configurable list separator using separator or env-separator tags.
• Support for required fields using required/require or env-required/env-require tags.
• Custom parsers for specific types can be registered using the RegisterParser function.
• Built-in support for loading string, int, float, boolean and time.Duration types.
• Nested structs are also visited and loaded with environment variables.
• integrates with enum package

Examples

Lookup[T any]: typesafe environment variable Lookup.

package main

func main() {
	val, ok, err := env.Lookup[string]("FOO", env.DefaultValue("foo"))
	_, _, _ = val, ok, err
}

Load[T any](ptr *T) error: Loads environment variables into the struct fields based on the field tags.

package main

type ExampleAppConfig struct {
	Foo  string        `env:"FOO"`
	Bar  time.Duration `env:"BAR" default:"1h5m"`
	Baz  int           `env:"BAZ" enum:"1;2;3;""`
	Qux  float64       `env:"QUX" required:"true"`
	Quux MyCustomInt   `env:"QUUX"`
}

func main() {
	var c ExampleAppConfig
	if err := env.Load(&c); err != nil {
		logger.Fatal(nil, "failed to load application config", logger.ErrField(err))
		os.Exit(1)
	}
}

RegisterParser[T any]: Registers custom parsers for specific types.

package main

type MyCustomInt int

var _ = env.RegisterParser(func(envValue string) (MyCustomInt, error) {
	// try parse hex
	v, err := strconv.ParseInt(envValue, 16, 64)
	if err == nil {
		return MyCustomInt(v), nil
	}

	// then let's try parse it as base 10 int
	v, err = strconv.ParseInt(envValue, 10, 64)
	if err == nil {
		return MyCustomInt(v), nil
	}
	return 0, err
})

TODO

• time.Time parsing support with configurable layout
• url.URL parsing support

Documentation

Index

• Constants
• func Load[T any](ptr *T) error
• func Lookup[T any](key string, opts ...LookupOption) (T, bool, error)
• func RegisterParser[T any](parser func(envValue string) (T, error)) struct{}
• type LookupOption
  • func DefaultValue(val string) LookupOption
  • func ListSeparator[SEP rune | string](sep SEP) LookupOption
  • func Required() LookupOption

Examples

• Load
• Load (Enum)
• Lookup
• RegisterParser

Constants

const ErrLoadInvalidData errorkit.Error = "ErrLoadInvalidData"

Functions

func Load

func Load[T any](ptr *T) error

Example

package main

import (
	"github.com/adamluzsi/frameless/pkg/env"
	"github.com/adamluzsi/frameless/pkg/logger"
	"os"
	"time"
)

func main() {
	type ExampleAppConfig struct {
		Foo string        `env:"FOO"`
		Bar time.Duration `env:"BAR" default:"1h5m"`
		Baz int           `env:"BAZ" required:"true"`
	}

	var c ExampleAppConfig
	if err := env.Load(&c); err != nil {
		logger.Fatal(nil, "failed to load application config", logger.ErrField(err))
		os.Exit(1)
	}
}

Example (Enum)

package main

import (
	"github.com/adamluzsi/frameless/pkg/env"
	"github.com/adamluzsi/frameless/pkg/logger"
	"os"
)

func main() {
	type ExampleAppConfig struct {
		Foo string `env:"FOO" enum:"foo;bar;baz;" default:"foo"`
	}

	var c ExampleAppConfig
	if err := env.Load(&c); err != nil {
		logger.Fatal(nil, "failed to load application config", logger.ErrField(err))
		os.Exit(1)
	}
}

func Lookup

func Lookup[T any](key string, opts ...LookupOption) (T, bool, error)

Example

package main

import (
	"github.com/adamluzsi/frameless/pkg/env"
)

func main() {
	val, ok, err := env.Lookup[string]("FOO", env.DefaultValue("foo"))
	_, _, _ = val, ok, err
}

func RegisterParser

func RegisterParser[T any](parser func(envValue string) (T, error)) struct{}

Example

package main

import (
	"github.com/adamluzsi/frameless/pkg/env"
	"strconv"
)

func main() {
	type MyCustomInt int

	var _ = env.RegisterParser(func(envValue string) (MyCustomInt, error) {
		// try parse hex
		v, err := strconv.ParseInt(envValue, 16, 64)
		if err == nil {
			return MyCustomInt(v), nil
		}

		// then let's try parse it as base 10 int
		v, err = strconv.ParseInt(envValue, 10, 64)
		if err == nil {
			return MyCustomInt(v), nil
		}
		return 0, err
	})

	type ExampleAppConfig struct {
		Foo MyCustomInt `env:"FOO" required:"true"`
	}

	var c ExampleAppConfig
	_ = env.Load(&c) // handle error
}

Types

type LookupOption

type LookupOption interface {
	// contains filtered or unexported methods
}

func DefaultValue

func DefaultValue(val string) LookupOption

func ListSeparator

func ListSeparator[SEP rune | string](sep SEP) LookupOption

func Required

func Required() LookupOption