README
¶
enve v1.1.0
Parsing and configuration via environment variables.
- Handy logs & error messages so you can easily discover your configuration by just running the program.
- Lets you know by default what knobs are required or missing... at most once per environment variable.
- As simple an API as I could make.
the big idea
Mandatory Environment Variables
If you have a required configuration value, use the Must family of functions:
Or specify custom parsing functions with Must itself.
Optional Environment Variables
If you have an optional configuration value, use the Or family of functions:
Or specify custom parsing functions with Or itself.
Customizing Enve's Logging Output
Enve outputs logs using the log package by default, using it's default (global) logger. You can customize this behavior using environment variables:
- Use
ENVE_LOG_SLOG=1to use thelog/slogpackage instead: it will use the default (global) logger at INFO level. Enve tries to provide the 'right amount' of logging, but you can tweak it a bit using the envvars described in the consts section of the documentation.
See more examples in the .
Documentation
¶
Overview ¶
Package enve retrieves & parses environment variables with optional logging.
- Handy logs & error messages so you can easily discover your configuration by just running the program.
- Lets you know by default what knobs are required or missing... at most once per environment variable.
- As simple an API as I could make.
Example (Must) ¶
Use the Must family of functions for required environment variables.
package main
import (
"fmt"
"os"
"gitlab.com/efronlicht/enve"
)
func main() {
os.Setenv("THE_ANSWER", "42")
fmt.Println(enve.MustInt("THE_ANSWER"))
}
Output: 42
Example (MustPanicOnMissing) ¶
package main
import (
"fmt"
"log"
"os"
"gitlab.com/efronlicht/enve"
)
func main() {
defer replaceStderr()()
defer func() { recover() }()
fmt.Println(enve.MustString("THE_QUESTION"))
// enve: enve/example_test.go:48 enve_test.Example_mustPanicOnMissing FATAL ERR: missing required envvar THE_QUESTION
}
func replaceStderr() func() {
log.SetFlags(0)
oldstderr := *os.Stderr
*os.Stderr = *os.Stdout
return func() { *os.Stderr = oldstderr }
}
Output:
Example (Or) ¶
Use the Or family of functions for optional environment variables.
package main
import (
"fmt"
"gitlab.com/efronlicht/enve"
)
func main() {
port := fmt.Sprintf(":%d", enve.IntOr("PORT", 8080)) // default to 8080 if not set
fmt.Printf("server listening at %s\n", port)
}
Output: server listening at :8080
Example (OrCustom) ¶
You can use your own parser functions with Or or Must for custom types.
package main
import (
"fmt"
"net"
"os"
"gitlab.com/efronlicht/enve"
)
func main() {
parseIP := func(s string) (net.IP, error) {
if ip := net.ParseIP(s); ip != nil {
return ip, nil
}
return nil, fmt.Errorf("invalid IP address %q", s)
}
os.Setenv("DNS", "8.8.8.8") // google's public DNS
fmt.Println(enve.Or(parseIP, "DNS", net.IPv4(1, 1, 1, 1))) // default to Cloudflare's public DNS if not set
}
Output: 8.8.8.8
Index ¶
- Constants
- func BoolOr(key string, backup bool) bool
- func DurationOr(key string, backup time.Duration) time.Duration
- func FloatOr(key string, backup float64) float64
- func FromTextOr[T any, PT interface{ ... }](key string, backup T) T
- func IntOr(key string, backup int) int
- func Lookup[T any](parse func(s string) (T, error), key string) (T, error)
- func Must[T any](parse func(string) (T, error), key string) T
- func MustBool(key string) bool
- func MustDuration(key string) time.Duration
- func MustFloat(key string) float64
- func MustInt(key string) int
- func MustString(key string) string
- func MustTimeRFC3339(key string) time.Time
- func MustUint64(key string) uint64
- func Or[T any](parse func(string) (T, error), key string, backup T) T
- func StringOr(key, backup string) string
- func TimeRFC3339Or(key string, backup time.Time) time.Time
- func Uint64Or(key string, backup uint64) uint64
Examples ¶
Constants ¶
const ( // environment variables to control logging behavior. ENVE_LOG_SUCCESS = "ENVE_LOG_SUCCESS" // if false, don't log successes (found/parsed key for the first time) ENVE_LOG_ERROR = "ENVE_LOG_ERROR" // if false, don't log errors (missing keys, bad values) ENVE_LOG_SLOG = "ENVE_LOG_SLOG" // environment variable to enable "log/slog" logging mode; if false, use "log" instead. ENVE_LOG_DISABLED = "ENVE_LOG_DISABLED" // environment variable to disable logging entirely; overrides all other logging settings. )
Variables ¶
This section is empty.
Functions ¶
func BoolOr ¶
BoolOr returns the boolean value represented by the environment variable. It accepts 1, t, T, TRUE, true, True, 0, f, F, FALSE, false, False. Any other value will return backup.
func DurationOr ¶
DurationOr looks up and parses the envvar as a duration.
func FromTextOr ¶
func FromTextOr[T any, PT interface { *T encoding.TextUnmarshaler }](key string, backup T, ) T
FromTextOr looks up and parses the envvar as a TextUnmarshaler.
func Lookup ¶
Lookup and parse the specified environment variable key, returning ErrorMissingKey if it's missing, and the result of parse(os.Getenv(key)) otherwise. The error message will include the key.
func Must ¶
Must looks up & parses the specified environment variable key, panicking on a missing value or parse error. Successful output will be logged exactly once if ENVE_LOG_SUCCESS is true.
func MustDuration ¶
MustDuration wraps Must(time.ParseDuration, key)
func MustString ¶
MustString looks up the envvar, panicking on a missing value. Unlike "Or", the empty string is OK.
func MustTimeRFC3339 ¶
MustTimeRFC3339 wraps Must(parse.TimeRFC3339, key)
func MustUint64 ¶
MustUint64 wraps Must(strconv.ParseUint(key, 0, 64), key)
func Or ¶
Or looks up & parses the specified environment variable key. A missing or unparsable value will return the backup value, logging the error (if any) and the fallback valuue. Successful output will be logged exactly once if ENVE_LOG_SUCCESS is true.
func TimeRFC3339Or ¶
TimeRFC3339Or wraps Or(parse.TimeRFC3339, key, backup)
Types ¶
This section is empty.
Source Files
Directories