/gosettings

Go package providing helper functions for working with settings

Primary LanguageGoMIT LicenseMIT

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:

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 🚧