From 390412e4446ffcda767a61e790d3cb43efa03c9f Mon Sep 17 00:00:00 2001 From: Carlos Alexandro Becker Date: Thu, 15 Jun 2023 16:24:14 +0000 Subject: [PATCH] docs: clarify custom parser funcs and required fields closes #268 --- README.md | 56 ++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 37 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 98d2f23..ed00505 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,8 @@ [![Coverage Status](https://img.shields.io/codecov/c/gh/caarlos0/env.svg?logo=codecov&style=for-the-badge)](https://codecov.io/gh/caarlos0/env) [![](http://img.shields.io/badge/godoc-reference-5272B4.svg?style=for-the-badge)](https://pkg.go.dev/github.com/caarlos0/env/v8) -A simple and zero-dependencies library to parse environment variables into structs. +A simple and zero-dependencies library to parse environment variables into +`struct`s. ## Example @@ -125,8 +126,10 @@ for more info. Env supports by default anything that implements the `TextUnmarshaler` interface. That includes things like `time.Time` for example. -The upside is that depending on the format you need, you don't need to change anything. -The downside is that if you do need time in another format, you'll need to create your own type. +The upside is that depending on the format you need, you don't need to change +anything. +The downside is that if you do need time in another format, you'll need to +create your own type. Its fairly straightforward: @@ -148,8 +151,9 @@ And then you can parse `Config` with `env.Parse`. ## Required fields -The `env` tag option `required` (e.g., `env:"tagKey,required"`) can be added to ensure that some environment variable is set. -In the example above, an error is returned if the `config` struct is changed to: +The `env` tag option `required` (e.g., `env:"tagKey,required"`) can be added to +ensure that some environment variable is set. In the example above, an error is +returned if the `config` struct is changed to: ```go type config struct { @@ -157,10 +161,18 @@ type config struct { } ``` +> **Warning** +> +> Note that being set is not the same as being empty. +> If the variable is set, but empty, the field will have its type's default +> value. +> This also means that custom parser funcs will not be invoked. + ## Not Empty fields -While `required` demands the environment variable to be set, it doesn't check its value. -If you want to make sure the environment is set and not empty, you need to use the `notEmpty` tag option instead (`env:"SOME_ENV,notEmpty"`). +While `required` demands the environment variable to be set, it doesn't check +its value. If you want to make sure the environment is set and not empty, you +need to use the `notEmpty` tag option instead (`env:"SOME_ENV,notEmpty"`). Example: @@ -186,9 +198,9 @@ type config struct { ## From file The `env` tag option `file` (e.g., `env:"tagKey,file"`) can be added -to in order to indicate that the value of the variable shall be loaded from a file. The path of that file is given -by the environment variable associated with it -Example below +in order to indicate that the value of the variable shall be loaded from a +file. +The path of that file is given by the environment variable associated with it: ```go package main @@ -269,9 +281,11 @@ func main() { ### Environment -By setting the `Options.Environment` map you can tell `Parse` to add those `keys` and `values` -as env vars before parsing is done. These envs are stored in the map and never actually set by `os.Setenv`. -This option effectively makes `env` ignore the OS environment variables: only the ones provided in the option are used. +By setting the `Options.Environment` map you can tell `Parse` to add those +`keys` and `values` as `env` vars before parsing is done. +These `envs` are stored in the map and never actually set by `os.Setenv`. +This option effectively makes `env` ignore the OS environment variables: only +the ones provided in the option are used. This can make your testing scenarios a bit more clean and easy to handle. @@ -307,8 +321,8 @@ func main() { ### Changing default tag name -You can change what tag name to use for setting the env vars by setting the `Options.TagName` -variable. +You can change what tag name to use for setting the env vars by setting the +`Options.TagName` variable. For example @@ -391,7 +405,8 @@ func main() { ### On set hooks -You might want to listen to value sets and, for example, log something or do some other kind of logic. +You might want to listen to value sets and, for example, log something or do +some other kind of logic. You can do this by passing a `OnSet` option: ```go @@ -429,7 +444,8 @@ func main() { ## Making all fields to required -You can make all fields that don't have a default value be required by setting the `RequiredIfNoDef: true` in the `Options`. +You can make all fields that don't have a default value be required by setting +the `RequiredIfNoDef: true` in the `Options`. For example @@ -464,8 +480,10 @@ func main() { ## Defaults from code -You may define default value also in code, by initialising the config data before it's filled by `env.Parse`. -Default values defined as struct tags will overwrite existing values during Parse. +You may define default value also in code, by initialising the config data +before it's filled by `env.Parse`. +Default values defined as struct tags will overwrite existing values during +Parse. ```go package main