README
¶
env
env provides a way to parse environment variables using a schema
Getting Started
The env package can be added to a project by running:
go get cattlecloud.net/go/env@latest
import "cattlecloud.net/go/env"
Examples
Use env.ParseOS and env.Schema for conveniently extracting values from the
operating system environment variables.
var (
home string
gomaxprocs int
)
err := env.ParseOS(env.Schema{
"HOME": env.String(&home, true),
"GOMAXPROCS": env.Int(&gomaxprocs, true),
})
the StringOr and IntOr variants can be used to provide fallback values in
case the environment variables are not set.
err := env.ParseOS(env.Schema{
"HOME": env.StringOr(&home, "/doesnotexist"),
"GOMAXPROCS": env.IntOr(&gomaxprocs, 8),
})
The Schema parsing is compatible with generic types, so if you have custom types
like UUID backed by string or ID backed by integers, they can still be used as
targets for extraction.
type (
uuid string
timestamp int64
)
var (
id uuid
creation timestamp
)
err := env.ParseOS(env.Schema{
"ID": env.String(&id, true),
"CREATED": env.Int(&creation, true),
})
In addition to ParseOS, other parsers include
ParseFile- for parsing a file containing environment variable key-value pairsParseMap- for parsing a Go map containing string key-value pairsParse[Environment]for parsing arbitrary implementations of theEnvironmenttype
License
The cattlecloud.net/go/env module is open source under the BSD license.
Documentation
¶
Index ¶
- func Parse(environment Environment, schema Schema) error
- func ParseFile(path string, schema Schema) error
- func ParseMap(m map[string]string, schema Schema) error
- func ParseOS(schema Schema) error
- type Environment
- type IntType
- type Parser
- func Bool(b *bool, required bool) Parser
- func BoolOr(b *bool, alt bool) Parser
- func Float(f *float64, required bool) Parser
- func FloatOr(f *float64, alt float64) Parser
- func Int[T IntType](i *T, required bool) Parser
- func IntOr[T IntType](i *T, alt T) Parser
- func Secret(s **conceal.Text, required bool) Parser
- func String[T StringType](s *T, required bool) Parser
- func StringOr[T StringType](s *T, alt T) Parser
- type Schema
- type StringType
- type Variable
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Parse ¶
func Parse(environment Environment, schema Schema) error
Parse uses the given Schema to parse the environment variables in the given Environment. If the values of environment variables in Environment do not match the schema, or required variables are missing, an error is returned.
func ParseFile ¶
ParseFile is a convenience function for parsing the given Schema of environment variables using the given .env file path. The contents of the file are read and interpreted as key=value pairs, one per line. If the environment variable contents of the file do not match the schema, or required variables are missing, an error is returned.
func ParseMap ¶
ParseMap is a convenience function for parsing the given Schema of environment variables using the given map. The contents of the map are inferred as key=value pairs. If the contents of the map do not match the schema, or required variables are missing, an error is returned.
func ParseOS ¶
ParseOS is a convenience function for parsing the given Schema of environment variables using the environment variables accessed by the standard libraray os package. If the values of environment variables do not match the schema, or required variables are missing, an error is returned.
Types ¶
type Environment ¶
Environment is something that implements Getenv().
Most use cases can simply make use of the OS implementation which is backed by the standard library os package.
var OS Environment = new(osEnv)
OS is an implementation of Environment that uses the standard library os package to retrieve actual environment variables.
func File ¶
func File(filename string) Environment
File is an implementation of Environment that reads environment variables from a file.
e.g. /etc/os-release
func Map ¶
func Map(m map[string]string) Environment
Map is an implementation of Environment that uses a given map[string]string to emulate a set of environment variables. Useful for testing.
m := Map(map[string]string {...})
func f(e env.Environment) {
e.Getenv("FOOBAR")
}
type IntType ¶
type IntType interface {
~int | ~int8 | ~int16 | ~int32 | ~int64 |
~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64
}
IntType represents any type compatible with the Go integer built-in types, to be used as a destination for writing the value of an environment variable.
type Parser ¶
The Parser interface is what must be implemented to support decoding an environment variable into a custom type.
func Bool ¶
Bool is used to extract an environment variable into a Go bool. If required is true, then an error is returned if the environment variable is not set or is empty.
func BoolOr ¶
BoolOr is used to extract an environment variable into a Go bool. If the environment variable is not set or is empty, then the alt value is used instead.
func Float ¶
Float is used to extract an environment variable into a Go float64. If required is true, then an error is returned if the environment variable is not set or is empty.
func FloatOr ¶
FloatOr is used to extract an environment variable into a Go float64. If the environment variable is not set or is emty, then the alt value is used instead.
func Int ¶
Int is used to extract an environment variable into a Go int. If required is true, then an error is returned if the environment variable is not set or is empty.
func IntOr ¶
IntOr is used to extract an environment variable into a Go int. If the environment variable is not set or is empty, then the alt value is used instead.
func Secret ¶
Secret is used to extract an environment variable into a Go concel.Text object. If required is true, then an error is returned if the environment variable is not set or is empty.
func String ¶
func String[T StringType](s *T, required bool) Parser
String is used to extract an environment variable into a Go string. If required is true, then an error is returned if the environment variable is not set or is empty.
func StringOr ¶
func StringOr[T StringType](s *T, alt T) Parser
StringOr is used to extract an environment variable into a Go string. If the environment variable is not set or is empty, then the alt value is used instead.
type StringType ¶
type StringType interface {
~string
}
StringType represents any type compatible with the Go string built-in type, to be used as a destination for writing the value of an environment variable.
Source Files