Gosettings
gosettings
is a Go package providing helper functions for working with settings.
Go.dev documentation:
Add it to your Go project with:
go get github.com/qdm12/gosettings
💁 Only compatible with Go 1.18+ since it now uses generics.
Features:
- Define settings struct methods:
Copy
: usegosettings.CopyPointer
andgosettings.CopySlice
SetDefaults
:gosettings.Default*
functions (see pkg.go.dev/github.com/qdm12/gosettings)MergeWith
:gosettings.MergeWith*
functions (see pkg.go.dev/github.com/qdm12/gosettings)OverrideWith
:gosettings.OverrideWith*
functions (see pkg.go.dev/github.com/qdm12/gosettings)Validate
:validate.*
functions fromgithub.com/qdm12/gosettings/validate
- Reading settings from sources:
- Environment variables: use
env.New(os.Environ())
with its methods, fromgithub.com/qdm12/gosettings/sources/env
- Environment variables: use
- Minor feature notes:
- No use of
reflect
for performance - Near zero dependency
- No use of
Philosophy
After having worked with Go and settings from different sources for years, I have come with a design I am happy with.
Settings struct
Each component has a settings struct, where the zero value of a field should be meaningless.
For example, if the value 0
is allowed for a field, then it must be an *int
field.
On the contrary, you could have an int
field if the zero value 0
is meaningless.
The reasoning behind this is that you want the zero Go value to be considered as 'unset field' so that the field value can be defaulted, merged with or overridden by another settings struct. See the below interface comments for more details on what this allows.
Next, each of your settings struct should ideally implement the following interface:
type Settings interface {
// SetDefaults sets default values for all unset fields.
// All pointer fields must be defaulted to a non nil value.
// Usage:
// - Once on the base settings at the start of the program.
// - If the user requests a reset of the settings, on an empty settings struct.
SetDefaults()
// Validate validates all the settings and return an error if any field value is invalid.
// It should only be called after `SetDefaults()` is called, and therefore should assume
// all pointer fields are set and NOT nil.
// Usage:
// - Validate settings early at program start
// - Validate new settings given, after calling .Copy() + .OverrideWith(newSettings)
Validate() (err error)
// Copy deep copies all the settings to a new Settings object.
// Usage:
// - Copy settings before modifying them with OverrideWith(), to validate them with Validate() before actually using them.
Copy() Settings
// MergeWith copies the receiver settings as `merged`, and sets all the unset fields
// of `merged` to the values of the `other` settings. The receiver should be a VALUE
// receiver so that it can be used with the generics-based merger settings source:
// https://github.com/qdm12/gosettings/blob/main/sources/merger
// Usage:
// - Read from different settings sources with an order of precedence
MergeWith(other Settings) (merged Settings)
// OverrideWith sets all the set values of the other settings to the fields of the receiver settings.
// Usage:
// - Update settings at runtime
OverrideWith(other Settings)
// ToLinesNode returns a (tree) node with the settings as lines, for displaying settings
// in a formatted tree, where you can nest settings node to display a full settings tree.
ToLinesNode() *gotree.Node
// String returns the string representation of the settings.
// It should simply return `s.ToLinesNode().String()` to show a tree of settings.
String() string
}
💁 This is my recommendation, and obviously you don't need to:
- define this interface
- have all these methods exported
- define
ToLinesNode
with gotree if you don't want to
➡️ Example settings implementation
More concrete settings implementation examples using this library are notably:
Settings methods usage
In the following Go examples, we use the example settings implementation.
Read settings from multiple sources
A quick glimpse on how this works:
package main
import (
"github.com/qdm12/gosettings/sources/merger"
)
type Settings struct {
// ...
}
// ... and Settings methods
func main() {
env := NewEnv()
flags := NewFlags()
merger := merger.New[Settings](flags, env)
settings, err := merger.Read()
if err != nil {
panic(err)
}
settings.SetDefaults()
// ...
}
See the runnable example which uses the example settings implementation.
Updating settings at runtime
🚧 To be completed 🚧