From 8e48841063f4c5f444bf6b2fa3cf5f6e25fb0e30 Mon Sep 17 00:00:00 2001 From: Tronje Krop Date: Fri, 20 Sep 2024 02:05:06 +0200 Subject: [PATCH] feat: improve docs and update deps (#7) Signed-off-by: Tronje Krop --- .gitignore | 2 ++ Makefile | 2 +- README.md | 79 ++++++++++++++++++++++++++++++++++-------------------- 3 files changed, 53 insertions(+), 30 deletions(-) diff --git a/.gitignore b/.gitignore index fed87aa..ce3e562 100644 --- a/.gitignore +++ b/.gitignore @@ -6,3 +6,5 @@ build run mock_*_test.go + +__debug_bin* diff --git a/Makefile b/Makefile index 046a987..58d421b 100644 --- a/Makefile +++ b/Makefile @@ -12,7 +12,7 @@ export GOPATH ?= $(shell $(GO) env GOPATH) export GOBIN ?= $(GOPATH)/bin # Setup go-make version to use desired build and config scripts. -GOMAKE_DEP ?= github.com/tkrop/go-make@v0.0.96 +GOMAKE_DEP ?= github.com/tkrop/go-make@v0.0.97 INSTALL_FLAGS ?= -mod=readonly -buildvcs=auto # Request targets from go-make targets target. TARGETS := $(shell command -v $(GOBIN)/go-make >/dev/null || \ diff --git a/README.md b/README.md index 21912e6..a40ba76 100644 --- a/README.md +++ b/README.md @@ -47,35 +47,45 @@ ## Introduction -Goal of `go-config` is to provide an easy and extensible config framework with -fluent interface based on [Viper][viper] supporting simple default tags for -standard services, jobs, and commands. +Goal of [`go-config`][go-config] is to provide an easy to use and extensible +config framework with fluent interface based on [Viper][viper] for services, +jobs, and commands. It is supporting simple `default`-tags and prototype +config to set up and change the reader defaults quickly. -[viper]: https://github.com/spf13/viper +[viper]: +[go-config]: ## How to start -To start with `go-config` you simply create your config as an extension of the -config provided in this package as follows: +In [`go-config`][go-config] you simply create your config as an extension of +the config provided in this package as a base line as follows: ```go // Config root element for configuration. type Config struct { config.Config `mapstructure:",squash"` - String string `default:"my-value"` Int int `default:"31"` - Dur Duration `default:"1m"` + String string `default:"my-value"` + Dur Duration `default:"1m"` + + Service *my.ServiceConfig } ``` -As usual in [Viper][viper], you can now create your config using the reader -that allows creating multiple configuration while applying the default setup -mechanisms using the following convenience functions: +**Note:** [`go-config`][go-config] makes it very simple to reuse the simple +config `struct`s provided by other libraries and components, since you can +easily create any hierarchy of `struct`s, `slice`s, and even `map[string]`s +containing native types, based on `int`, `float`, `byte`, `rune`, `complex`, +and `string`. You can also use `time.Time` and `time.Duration`. + +As usual in [Viper][viper], you can create your config using the reader that +allows creating multiple configs while applying the setup mechanisms for +defaults using the following convenience functions: ```go - reader := config.New("", "", &Config{}). + reader := config.New("", "", &Config{}). SetDefaults(func(c *config.ConfigReader[config.Config]{ c.SetDefault("int", 32) }).ReadConfig("main") @@ -83,14 +93,18 @@ mechanisms using the following convenience functions: config := reader.GetConfig("main") ``` -The defaults provided have via different options are overwriting each other in +This creates a standard config reader with defaults from the given config +prototype reading in additional defaults from the `[-env].yaml`-file +and environment variables. + +The defaults provided by the different options are overwriting each other in the following order: 1. First, the values provided via the `default`-tags are applied. 2. Second the values provided by the config prototype instance are applied. 3. Third the values provided by [Viper][viper] custom setup calls are applied. This also includes the convenient methods provided in this package. -4. Forth the values provided in the `[-env].yaml`-file are applied. +4. Forth the values provided in the `[-env].yaml`-file are applied. 5. And finally the values provided via environment variables are applied taking the highest precedence. @@ -99,13 +113,13 @@ still possible to customize the reader arbitrarily, e.g. with flag support, and setup any other config structure by using the original [Viper][viper] interface functions. -A special feature provided by `go-config` is to set up the defaults using a -partial or complete prototype config. You can provide a complete prototype in -the `New` constructor as well as any sub-prototype in the `SetSubDefaults` -method as follows: +A special feature provided by [`go-config`][go-config] is to set up the +defaults using a partial or complete config prototype. While you must provide a +complete prototype in the `New` constructor, you can provide any sub-prototype +in the `SetSubDefaults` method as follows: ```go - reader := config.New("", "", &config.Config{ + reader := config.New("", "", &config.Config{ Env: "prod", }).SetSubDefaults("", &log.Config{ Level: "debug", @@ -115,11 +129,11 @@ method as follows: ## Logger setup -The `go-config` framework als supports to set up a [logrus][logrus] Logger -out-of-the-box using configured defaults as follows: +The [`go-config`][go-config] framework supports to set up a [logrus][logrus] +`Logger`_out-of-the-box as follows: ```go - config := config.New("", "", &Config{}). + config := config.New("", "", &Config{}). LoadConfig("main") logger := config.Log.Setup(log.New()) @@ -132,10 +146,11 @@ If no logger is provided, the standard logger is configured and returned. ## Build info -Finally, the `go-config` framework also supports in conjunction with -`go-make` a build information to track and access the origin of a command, -service or job. However, the build information must be manually enabled -by adding the following variable set to the `main.go` file. +Finally, [`go-config`][go-config] in conjunction with [`go-make`][go-make] +supports a build information to track and access the origin of a command, +service or job. While the build information is also auto-discovered, a full +[`go-make`][go-make] integration provides the following variables in the +`main.go`-file. ```go // Build information variables set by `go-make`. @@ -155,12 +170,18 @@ var ( ) ``` -In addition, you have to set up the build information in config reader by -utilizing the variables as follows: +You can now use this information to set up the default build information in +the config reader by using `SetInfo` during creation as follows: ```go func main() { - reader := config.New("", "", &Config{}). + reader := config.New("", "", &Config{}). SetInfo(info.New(Path, Version, Build, Revision, Commit, Dirty)). } ``` + +If you don't want to use [`go-make`][go-make], you can provide the variable +defaults in the `-ldflags="-X main.Path=... -X main.Version=... ...` manually +during your build. + +[go-make]: