env

Documentation

Overview

Package env is a simple, zero-dependencies library to parse environment variables into structs.

Example:

type config struct {
	Home string `env:"HOME"`
}
// parse
var cfg config
err := env.Parse(&cfg)
// or parse with generics
cfg, err := env.ParseAs[config]()

Check the examples and README for more detailed usage.

Index

• func Must[T any](t T, err error) T
• func Parse(v interface{}) error
• func ParseAs[T any]() (T, error)
• func ParseAsWithOptions[T any](opts Options) (T, error)
• func ParseWithOptions(v interface{}, opts Options) error
• func ToMap(env []string) map[string]string
• type AggregateError
  • func (e AggregateError) Error() string
  • func (e AggregateError) Is(err error) bool
  • func (e AggregateError) Unwrap() []error
• type EmptyEnvVarError
• type EmptyVarError
  • func (e EmptyVarError) Error() string
• type EnvVarIsNotSetError
• type FieldParams
  • func GetFieldParams(v interface{}) ([]FieldParams, error)
  • func GetFieldParamsWithOptions(v interface{}, opts Options) ([]FieldParams, error)
• type LoadFileContentError
  • func (e LoadFileContentError) Error() string
• type NoParserError
  • func (e NoParserError) Error() string
• type NoSupportedTagOptionError
  • func (e NoSupportedTagOptionError) Error() string
• type NotStructPtrError
  • func (e NotStructPtrError) Error() string
• type OnSetFn
• type Options
• type ParseError
  • func (e ParseError) Error() string
• type ParseValueError
  • func (e ParseValueError) Error() string
• type ParserFunc
• type VarIsNotSetError
  • func (e VarIsNotSetError) Error() string

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.

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)

ParseAsWithOptions 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.

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
}

AggregateError is 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 VarIsNotSetError EmptyVarError 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.

func (AggregateError) Unwrap

func (e AggregateError) Unwrap() []error

Unwrap implements std errors.Join go1.20 compatibility

type EmptyEnvVarError

type EmptyEnvVarError = EmptyVarError

EmptyEnvVarError occurs when the variable which must be not empty is existing but has an empty value

Deprecated: use EmptyVarError.

type EmptyVarError

type EmptyVarError struct {
	Key string
}

EmptyVarError occurs when the variable which must be not empty is existing but has an empty value

func (EmptyVarError) Error

func (e EmptyVarError) Error() string

type EnvVarIsNotSetError

type EnvVarIsNotSetError = VarIsNotSetError

EnvVarIsNotSetError occurs when the required variable is not set.

Deprecated: use VarIsNotSetError.

type FieldParams

type FieldParams struct {
	OwnKey          string
	Key             string
	DefaultValue    string
	HasDefaultValue bool
	Required        bool
	LoadFile        bool
	Unset           bool
	NotEmpty        bool
	Expand          bool
	Init            bool
	Ignored         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
}

LoadFileContentError occurs when it's impossible to load the value from the file.

func (LoadFileContentError) Error

func (e LoadFileContentError) Error() string

type NoParserError

type NoParserError struct {
	Name string
	Type reflect.Type
}

NoParserError occurs when there is no parser provided for given type.

func (NoParserError) Error

func (e NoParserError) Error() string

type NoSupportedTagOptionError

type NoSupportedTagOptionError struct {
	Tag string
}

NoSupportedTagOptionError occurs when the given tag is not supported. Built-in supported tags: "", "file", "required", "unset", "notEmpty", "expand", "envDefault", and "envSeparator".

func (NoSupportedTagOptionError) Error

func (e NoSupportedTagOptionError) Error() string

type NotStructPtrError

type NotStructPtrError struct{}

NotStructPtrError 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 tag name to use rather than the default 'env'.
	TagName string

	// PrefixTagName specifies another prefix tag name to use rather than the default 'envPrefix'.
	PrefixTagName string

	// DefaultValueTagName specifies another default tag name to use rather than the default 'envDefault'.
	DefaultValueTagName string

	// RequiredIfNoDef automatically sets all fields 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 every 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

	// SetDefaultsForZeroValuesOnly defines whether to set defaults for zero values
	// If the `env` variable for the value is not set
	// and `envDefault` is set
	// and the value is not a zero value for the the type
	// and SetDefaultsForZeroValuesOnly=true
	// the value from `envDefault` will be ignored
	// Useful for mixing default values from `envDefault` and struct initialization
	SetDefaultsForZeroValuesOnly 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
}

ParseError 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
}

ParseValueError occurs when it's impossible to convert value using given parser.

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 `Options`' `FuncMap`.

type VarIsNotSetError

type VarIsNotSetError struct {
	Key string
}

VarIsNotSetError occurs when the required variable is not set.

func (VarIsNotSetError) Error

func (e VarIsNotSetError) Error() string