From 9c17ee16d0d550c8a972ae659c821940e93c623d Mon Sep 17 00:00:00 2001 From: slashformotion Date: Tue, 6 Sep 2022 10:55:53 +0200 Subject: [PATCH] add docs --- README.md | 211 +++++++++++++++++++- docs/normalization/normalization.md | 21 ++ docs/using_it_for_real/conf/verdeterapp.yml | 1 + docs/using_it_for_real/main.go | 39 ++++ docs/using_it_for_real/using_it_for_real.md | 147 ++++++++++++++ 5 files changed, 418 insertions(+), 1 deletion(-) create mode 100644 docs/normalization/normalization.md create mode 100644 docs/using_it_for_real/conf/verdeterapp.yml create mode 100644 docs/using_it_for_real/main.go create mode 100644 docs/using_it_for_real/using_it_for_real.md diff --git a/README.md b/README.md index 9443f93..1b22bc6 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,212 @@ # Verdeter -Verdeter project is a tool to write configuration easily with cobra and viper. Verdeter +Verdeter is a library to write configuration easily with cobra and viper for distributed applications. Verdeter bring the power of cobra and viper in a single library. + +It should be consider as a wrapper for cobra and viper that allow developers to code faster. + +> The api is susceptible to change at any point in time until the v1 is released. + +Verdeter allow developers to bind a posix complient flag, an environment variable and a variable in a config file to a viper key with a single line of code. +Verdeter also comes with extra features such as: +- support for [normalize function](https://github.com/ditrit/verdeter/blob/main/docs/normalization/normalization.md), ex: `LowerString` (lower the input string) +- support for [key specific checks](https://github.com/ditrit/verdeter/blob/main/docs/using_it_for_real/using_it_for_real.md), ex: `StringNotEmpty`(check if the input string is empty), `CheckIsHighPort`(check is the input integer is a high tcp port)) +- support for constraints, ex: check for specific arch +- support for dynamic default values (named *Computed values*), ex: set `time.Now().Unix()` as a default for a "time" key + + +## How Verdeter differ from viper in handling configuration value + +Verdeter uses the following precedence order. Each item takes precedence over the item below it: + +1. Explicit call to `viper.Set`: + + `viper.Set(key)` set the key to a fixed value + + *Example: `viper.Set("age", 25)` will set the key "**age**" to `25`* + +2. POSIX flags + + Cli flags are handled by cobra using [pflag](https://github.com/spf13/pflag) + + *Example: appending the flag `--age 25` will set the key "**age**" to `25`* + +3. Environment variables + + Environment Variable are handled by viper (read more [here](https://github.com/spf13/viper#working-with-environment-variables)) + + *Example: running `export _age` will export an environment variable (the `` is set by verdeter). Verdeter will bind automatically the environment variable name to a viper key when the developer will define the key he needs. Then, when the developer retreive a value for the "**age**" key with a call to `viper.Get("age)`, viper get all the environment variable and find the value of `_age`.* + + +4. Value in a config file + + Viper support reading from [JSON, TOML, YAML, HCL, envfile and Java properties config files](https://github.com/spf13/viper#what-is-viper). The developer need to set a key named "**config_path**" to set the path to the config file or the path to the config directory. + + *Example:* + Let's say the "**config_path**" is set to `./conf.yml` and the file looks like below + ```yml + # conf.yml + author: + name: bob + age: 25 + ``` + Then you would use `viper.Get("author.name")` to access the value `bob` and `viper.Get("age")` to access the value `25`. + +5. Dynamic default values (*computed values*) + + Verdeter allow the user of "*computed values*" as dynamic default values. It means that the developer can values returned by functions as default values. + + *Example:* + The function `defaultTime` will provide a unix time integer. + + ```go + var defaultTime verdeter.models.DefaultValueFunction := func () interface{} { + return time.Now().Unix() + } + ``` + + We bind this function to the key time using verdeter. + + ```go + (*VerdeterCommand).SetComputedValue("time", defaultTime) + ``` + + Then the value can be retreived easily using `viper.Get("time")` as usual + + +6. static default + + Static defaults can be set using verdeter + ```go + // of course here the value is static + (*VerdeterCommand).SetDefault("time", 1661957668) + ``` + Alternatively you can use viper directly to do exactly the same thing (please note that we will use `(*VerdeterCommand).SetDefault` in the rest of the documentation). + ```go + viper.SetDefault("time", 1661957668) + ``` + + +7. type default (0 for an integer) + + If a key is *not set* and *not marked as required (using `(*VerdeterCommand).SetRequired()`)*, then a call to `viper.Get()` will return the default value for this ``. + + *Example:* let's say thay we **did not** call `(*VerdeterCommand).SetRequired("time")` to set the key "time" as required. + Then a call to `viper.GetInt("time")` will return `0`. (please note that a call to `viper.Get()` returns an `interface{}` wich has no "defaut value"). + + +## Basic Example + +Let's create a rootCommand named "myApp" +```go + +var rootCommand = verdeter.NewConfigCmd( + // Name of the app + "myApp", + + // A short description + "myApp is an amazing piece of software", + + // A longer description + `myApp is an amazing piece of software, +that everyone can use thanks to verdeter`, + + // Callback + func(cfg *verdeter.VerdeterCommand, args []string) { + key := "author.name" + fmt.Printf("value for %q is %q\n", key, viper.GetString(key)) + }) +``` + +You might to receive args on the command line, set the number of args you want. +If more are provided, Cobra will throw an error. + +```go +// only 2 args please +rootCommand.SetNbArgs(2) +``` + +Then I want to add configuration to this command, for example to bind an address and a port to myApp. + +```go +// Adding a local key. +// if you want sub command to inherit this flag, use (*verdeter.VerdeterCommand).GKey instead +rootCommand.LKey("addr", verdeter.IsStr, "a", "bind to IPV4 addr") +rootCommand.LKey("port", verdeter.IsInt, "p", "bind to TCP port") +``` + +A default value can be set for each config key + +```go +rootCommand.SetDefault("addr", "127.0.0.1") +rootCommand.SetDefault("port", 7070) +``` + +A validator can be bound to a config key. + +```go +// creating a validator from scratch +addrValidator := models.Validator{ + // the name of the validator + Name: "IPV4 validator", + + // the actual validation function + Func: func (input interface{}) error { + valueStr, ok := input.(string) + if !ok { + return fmt.Error("wrong input type") + } + parts := strings.Split(".") + if len(parts)!=4 { + return fmt.Errorf("An IPv4 is composed of four 8bit integers, fount %d", len(parts)) + } + for _,p := parts { + intVal, err := strconv.Atoi(p) + if err != nil { + return err + } + if intVal<0 || intVal >255 { + return fmt.Error("one of the part in the string is not a byte") + } + + } + }, +} + +// using the validator we just created +rootCommand.SetValidator("addr", addrValidator) + +// verdeter comes with some predefined validators +rootCommand.SetValidator("port", verdeter.validators.CheckTCPHighPort) +``` + +Config key can be marked as required. The cobra function [(* cobra.Command).PreRunE](https://pkg.go.dev/github.com/spf13/cobra#Command) will fail if the designated config key is not provided, preventing the callback to run. +```go +rootCommand.SetRequired("addr") +``` + +To actually run the command, use this code in your main.go + +```go +func init(){ + // Initialize the command + rootCommand.Initialize() + // setup keys + // rootCommand.LKey("port", ve...... + +} +func main() { + + + /* + YOUR CODE HERE + */ + + // Launch the command + rootCommand.Execute() + +} +``` + +## Contributing Guidelines + +See [CONTRIBUTING](CONTRIBUTING.md) \ No newline at end of file diff --git a/docs/normalization/normalization.md b/docs/normalization/normalization.md new file mode 100644 index 0000000..c3087e1 --- /dev/null +++ b/docs/normalization/normalization.md @@ -0,0 +1,21 @@ +# Normalization + +Verdeter support normalization functions. + +Let's say you are building an app that take strings as config values. Instead of asking you user to use only lowercase strings you could set a normalizer with verdeter that will ensure that the string value you will retrieve is actually a lowercase value. + +```go +var LowerString models.NormalizationFunction = func(val interface{}) interface{} { + strVal, ok := val.(string) + if !ok { + return val + } + return strings.ToLower(strVal) +} + +verdeterCommand.SetNormalize("keyname", LowerString) +``` + +--- + +*The `LowerString` normalization function is actually available at `verdeter.normalization.LowerString`* \ No newline at end of file diff --git a/docs/using_it_for_real/conf/verdeterapp.yml b/docs/using_it_for_real/conf/verdeterapp.yml new file mode 100644 index 0000000..35ad839 --- /dev/null +++ b/docs/using_it_for_real/conf/verdeterapp.yml @@ -0,0 +1 @@ +time: 1661865582 \ No newline at end of file diff --git a/docs/using_it_for_real/main.go b/docs/using_it_for_real/main.go new file mode 100644 index 0000000..ee7c93a --- /dev/null +++ b/docs/using_it_for_real/main.go @@ -0,0 +1,39 @@ +package main + +import ( + "fmt" + "time" + + "github.com/ditrit/verdeter" + "github.com/spf13/viper" +) + +var verdeterRootCmd = verdeter.NewVerdeterCommand( + "verdeterapp", + "verdeterapp print formated time to the terminal", + "/* Insert a longer description here*/", + func(cfg *verdeter.VerdeterCommand, args []string) error { + timeStamp := viper.GetInt("time") + t := time.Unix(int64(timeStamp), 0) + fmt.Println(t) + + // no error to return + return nil + }) + +func main() { + // Initialize the command + verdeterRootCmd.Initialize() + + viper.Set("config_path", "./conf/") + + // Set a new key named "time" with a shortcut named "t" + verdeterRootCmd.GKey("time", verdeter.IsInt, "t", "the time") + + // If the value of time is not set, run this function and set "time" to it's output + verdeterRootCmd.SetComputedValue("time", func() interface{} { + return time.Now().Unix() + }) + + verdeterRootCmd.Execute() +} diff --git a/docs/using_it_for_real/using_it_for_real.md b/docs/using_it_for_real/using_it_for_real.md new file mode 100644 index 0000000..590e9d9 --- /dev/null +++ b/docs/using_it_for_real/using_it_for_real.md @@ -0,0 +1,147 @@ +# Using Verdeter, for real + +We will create an app that will take a unix timestamp as an input for a config key and print a formated version to the standard output. + +Let's define our root command with the callback +```go +var verdeterRootCmd = verdeter.NewVerdeterCommand( + "verdeterapp", + "verdeterapp print formated time to the terminal", + "/* Insert a longer description here*/", + func(cfg *verdeter.VerdeterCommand, args []string) error { + timeStamp := viper.GetInt("time") + t := time.Unix(int64(timeStamp), 0) + fmt.Println(t) + + // no error to return + return nil +}) +``` + +Then set the config_path to `./conf/vertederapp.yml` +```go +verdeterRootCmd.SetDefault("config_path", "./conf/") +``` + +Then add a consig key + +```go +// Set a new key named "time" with a shortcut named "t" +verdeterRootCmd.GKey("time", verdeter.IsInt, "t", "the input unix time") +``` + +The we set a dynamic default value to `time.Now().Unix()`. That way if the config key 'time" is not present in the flag, in the environment variables or in the config file, "time" will take the value of the current time. + + +```go +// If the value of time is not set, run this function and set "time" to it's output +verdeterRootCmd.SetComputedValue("time", func() interface{} { + return time.Now().Unix() +}) +``` + +The we set a dynamic default value to `time.Now().Unix()`. That way if the config key 'time" is not present in the flag, in the environment variables or in the config file, "time" will take the value of the current time. + + +```go +// If the value of time is not set, run this function and set "time" to it's output +verdeterRootCmd.SetComputedValue("time", func() interface{} { + return time.Now().Unix() +}) +``` +Let's write a config file + +```yml +# ./conf/verdeterapp.yml +time: 1661865582 +``` +***The code in full:*** +```go +package main + +import ( + "fmt" + "time" + + "github.com/ditrit/verdeter" + "github.com/spf13/viper" +) + +var verdeterRootCmd = verdeter.NewVerdeterCommand( + "verdeterapp", + "verdeterapp print formated time to the terminal", + "/* Insert a longer description here*/", + func(cfg *verdeter.VerdeterCommand, args []string) error { + timeStamp := viper.GetInt("time") + t := time.Unix(int64(timeStamp), 0) + fmt.Println(t) + + // no error to return + return nil + }) + +func main() { + // Initialize the command + verdeterRootCmd.Initialize() + + viper.Set("config_path", "./conf/") + + // Set a new key named "time" with a shortcut named "t" + verdeterRootCmd.GKey("time", verdeter.IsInt, "t", "the time") + + // If the value of time is not set, run this function and set "time" to it's output + verdeterRootCmd.SetComputedValue("time", func() interface{} { + return time.Now().Unix() + }) + + verdeterRootCmd.Execute() +} + +``` + + +## Executing the program + +> the "help" command is available + ``` +$ verdeterapp help +Usage: + verdeterapp [flags] + +Flags: + -h, --help help for verdeterapp + -t, --time int the time + ``` + +**`time` can now be set:** +- with an environment variable `VERDETERAPP_TIME` +- with a flag `--time` (or `-t`) +- with a value set in a config + + + +"time" is set from the flag + +```bash +> go build -o verdeterapp +> ./verdeterapp --time 1661865571 +Tue Aug 30 2022 13:19:31 GMT+0000 +``` + +"time" is set from the ENV variable + +```bash +> go build -o verdeterapp +> VERDETERAPP_TIME=1661865555 ./verdeterapp +Tue Aug 30 2022 13:19:15 GMT+0000 +``` + +"time" is set from the config file + +```bash +> go build -o verdeterapp +> ./verdeterapp +Tue Aug 30 2022 13:19:42 GMT+0000 +``` + +In this example, verdeter allowed us to build an app that can use configuration from 3 main sources (*flags, environment variables and config file*) easily. \ No newline at end of file