envloader

README

Go: Load config from the environment

WIP in terms of API and docs.

Why?

TODO

Usage

Install:

go get github.com/andreyvit/envloader

Use:

TODO

Contributing

This library is a work in progress.

We recommend modd (go install github.com/cortesi/modd/cmd/modd@latest) for continuous testing during development.

MIT license

Copyright (c) 2023 Andrey Tarantsov. Published under the terms of the MIT license.

Documentation

Overview

Package envloader assists in writing executables that load their config from the environment.

Index

• func Optional() bool
• func PrintError(e *Error, w io.Writer)
• func Required() bool
• func WhenFalse(boolVar *bool) func() bool
• func WhenTrue(boolVar *bool) func() bool
• type Bool
  • func BoolVar(v *bool) *Bool
  • func NewBool(v bool) *Bool
  • func (v Bool) Get() interface{}
  • func (v *Bool) Set(raw string) error
  • func (v Bool) String() string
• type Duration
  • func DurationVar(v *time.Duration) *Duration
  • func NewDuration(v time.Duration) *Duration
  • func (v Duration) Get() interface{}
  • func (v *Duration) Set(raw string) error
  • func (v Duration) String() string
• type Error
• type Int
  • func IntVar(v *int) *Int
  • func NewInt(v int) *Int
  • func (v Int) Get() interface{}
  • func (v *Int) Set(raw string) error
  • func (v Int) String() string
• type Int64
  • func Int64Var(v *int64) *Int64
  • func NewInt64(v int64) *Int64
  • func (v Int64) Get() interface{}
  • func (v *Int64) Ptr() *int64
  • func (v *Int64) Set(raw string) error
  • func (v Int64) String() string
• type InvalidValue
  • func (e *InvalidValue) Error() string
  • func (e *InvalidValue) Unwrap() error
• type String
  • func NewString(v string) *String
  • func StringVar(v *string) *String
  • func (v String) Get() interface{}
  • func (v *String) Set(raw string) error
  • func (v String) String() string
• type Value
• type Var
• type VarSet
  • func (vars VarSet) Parse()
  • func (vars VarSet) Print()
  • func (vars VarSet) PrintAction() flag.Value
  • func (vars VarSet) PrintTo(out io.Writer)
  • func (vars VarSet) String() string
  • func (vars VarSet) TryParse() *Error
  • func (vars VarSet) TryParseFrom(getenv func(string) string) *Error
  • func (vars *VarSet) Var(envKey string, required func() bool, value flag.Value, desc string) *Var

Functions

func Optional

func Optional() bool

Optional is a convenient value to pass to VarSet.Add for variables that are always optional.

func PrintError

func PrintError(e *Error, w io.Writer)

PrintError performs default printing of the given error returned by TryParse.

func Required

func Required() bool

Required is a convenient value to pass to VarSet.Add for variables that are always required.

func WhenFalse

func WhenFalse(boolVar *bool) func() bool

WhenFalse returns a value to pass to VarSet.Add for variables that are required when the given variable is false.

func WhenTrue

func WhenTrue(boolVar *bool) func() bool

WhenTrue returns a value to pass to VarSet.Add for variables that are required when the given variable is true.

Types

type Bool

type Bool bool

func BoolVar

func BoolVar(v *bool) *Bool

func NewBool

func NewBool(v bool) *Bool

func (Bool) Get

func (v Bool) Get() interface{}

func (*Bool) Set

func (v *Bool) Set(raw string) error

func (Bool) String

func (v Bool) String() string

type Duration

type Duration time.Duration

func DurationVar

func DurationVar(v *time.Duration) *Duration

func NewDuration

func NewDuration(v time.Duration) *Duration

func (Duration) Get

func (v Duration) Get() interface{}

func (*Duration) Set

func (v *Duration) Set(raw string) error

func (Duration) String

func (v Duration) String() string

type Error

type Error struct {
	InvalidValues []*InvalidValue
	MissingVars   VarSet
}

Error describes environment variable problems encountered by TryParse.

type Int

type Int int

func IntVar

func IntVar(v *int) *Int

func NewInt

func NewInt(v int) *Int

func (Int) Get

func (v Int) Get() interface{}

func (*Int) Set

func (v *Int) Set(raw string) error

func (Int) String

func (v Int) String() string

type Int64

type Int64 int64

func Int64Var

func Int64Var(v *int64) *Int64

func NewInt64

func NewInt64(v int64) *Int64

func (Int64) Get

func (v Int64) Get() interface{}

func (*Int64) Ptr

func (v *Int64) Ptr() *int64

func (*Int64) Set

func (v *Int64) Set(raw string) error

func (Int64) String

func (v Int64) String() string

type InvalidValue

type InvalidValue struct {
	EnvKey string
	Cause  error
}

InvalidValue is an error returned as part of Error struct for environment variable values that failed to parse.

func (*InvalidValue) Error

func (e *InvalidValue) Error() string

func (*InvalidValue) Unwrap

func (e *InvalidValue) Unwrap() error

type String

type String string

func NewString

func NewString(v string) *String

func StringVar

func StringVar(v *string) *String

func (String) Get

func (v String) Get() interface{}

func (*String) Set

func (v *String) Set(raw string) error

func (String) String

func (v String) String() string

type Value

type Value interface {
	flag.Value
	flag.Getter
}

type Var

type Var struct {
	EnvKey   string
	Required func() bool
	Value    flag.Value
	Desc     string

	IsSpecified bool
}

Var defines a single environment variable.

type VarSet

type VarSet []*Var

VarSet is a slice of environment variable definitions. The ordering matters, both when printing the values (obviously), and also when parsing, because later variables can refer to the values of prior ones.

func (VarSet) Parse

func (vars VarSet) Parse()

Parse parses the current environment variable values. If parsing fails, prints an error message and exits the program with error code 2.

func (VarSet) Print

func (vars VarSet) Print()

Print prints a shell script that defines all variables in the set to os.Stdout. Variable descriptions are added as comments.

func (VarSet) PrintAction

func (vars VarSet) PrintAction() flag.Value

PrintAction returns flag.Value that can be used with flag.Var to print all environment variables in shell format.

Use like this:

flag.Var(vars.PrintAction(), "print-env", "print all supported environment variables in shell format")

func (VarSet) PrintTo

func (vars VarSet) PrintTo(out io.Writer)

PrintTo prints a shell script that defines all variables in the set. Variable descriptions are added as comments.

func (VarSet) String

func (vars VarSet) String() string

String returns a shell script that defines all variables in the set. Variable descriptions are added as comments.

func (VarSet) TryParse

func (vars VarSet) TryParse() *Error

TryParse parses the current environment variable values. Returns nil when successful, a pointer to Error when not.

func (VarSet) TryParseFrom

func (vars VarSet) TryParseFrom(getenv func(string) string) *Error

TryParseFrom parses environment variable values returned by the given function. Returns nil when successful, a pointer to Error when not.

func (*VarSet) Var

func (vars *VarSet) Var(envKey string, required func() bool, value flag.Value, desc string) *Var

Var adds a given value to the set of environment variable definitions.

Required func specifies the conditions when the value is required. Very often, a feature is enabled by a master on/off variable, and a bunch of configuration parameters are only required when it is on. Use Required, Optional, WhenTrue and WhenFalse helpers, or define your own custom function. These functions can refer to the values of the previously defined variables.

Use StringVar, BoolVar, IntVar & similar helpers defined in this package to make flag.Value for your variables.