README
¶
envi
Installation
go get github.com/Clarilab/envi/v3
Importing
import "github.com/Clarilab/envi/v3"
Usage
Config struct
To use envi, you have to create a struct which resembles your config structure that you want to parse.
type Config struct {
YamlFile YAMLFile `env:"my-path-to.yaml" watch:"true"`
JsonFile JSONFile `env:"my-path-to.json" default:"./my-default-path.json" type:"json"`
TextFile TextFile `env:"my-path-to.txt" type:"text"`
Environment string `default:"prod"`
}
type TextFile struct {
Value string `default:"foobar"`
}
type YAMLFile struct {
StringField string `yaml:"STRING_FIELD"`
IntField int `yaml:"INT_FIELD" default:"1337"`
Int64Field int64 `yaml:"INT_64_FIELD" required:"true" default:"1337"`
BoolField bool `yaml:"BOOL_FIELD"`
FloatField float32 `yaml:"FLOAT_FIELD" required:"true"`
Float64Field float64 `yaml:"FLOAT_64_FIELD" default:"3.1415926"`
}
// necessary func to enable file watching
func (y YAMLFile) OnChange() {
// do something when the config file changes
}
// necessary func to enable file watching
func (y YAMLFile) OnError(err error) {
// do something when loading a config update fails
}
type JSONFile struct {
Foo string `json:"FOO"`
Bar int64 `json:"BAR"`
}
Available Tags
- default: default value (supports file paths for files and standard data types bool, float32, float64, int32, int64, string)
- env: environment variable name
- type: describes the file type (json, yaml, text), defaults to yaml if omitted
- required: indicates that the field is required, "envi.Load()" will return an error in this case
- watch: indicates that the file should be watched for changes
File watcher
To watch for changes in config files, for example while using a vault, the underlying struct has to implement the envi.FileWatcher interface:
type FileWatcher interface {
OnChange()
OnError(error)
}
Load config
To load environment variables into your config:
e := envi.New()
defer e.Close()
var myConfig Config
err := e.Load(&myConfig)
// some error handling as a good developer should do
Load loads all config files and environment variables into the input struct. Supported types are JSON, YAML and text files, as well as strings on the struct root level.
If you want to watch a file for changes, the "watch" tag has to be set to true and the underlying struct has to implement the envi.FileWatcher interface.
While using the "default" tag, the "env" tag can be omitted. If not omitted, the value from the environment variable will be used.
When using the text file type, envi will try to load the file content into the first string field of that struct.
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type CloseError ¶
type CloseError struct {
Errors []error
}
CloseError is returned when one or multiple errors occured while closing the file watchers.
func (*CloseError) Error ¶
func (e *CloseError) Error() string
type Envi ¶
type Envi struct {
// contains filtered or unexported fields
}
Envi holds references to all active file watchers.
func (*Envi) Errors ¶ added in v3.0.3
Errors returns an error channel where filewatcher errors are sent to.
func (*Envi) Load ¶
Load loads all config files and environment variables into the input struct. Supported types are JSON, YAML and text files, as well as strings.
If you want to watch a file for changes, the "watch" tag has to be set to true and the underlying struct has to implement the envi.FileWatcher interface.
While using the "default" tag, the "env" tag can be omitted. If not omitted, the value from the environment variable will be used.
When using the text file type, envi will try to load the file content into the first string field of that struct.
Example config:
type Config struct {
Environment string `env:"ENVIRONMENT" required:"true"`
YAMLConfig YAMLFile `type:"yaml" watch:"true" default:"./config.yaml"`
TextConfig TextFile `env:"MY_TEXT_CONFIG_FILE" type:"text"`
}
type YAMLFile struct {
Key1 string `yaml:"key1" required:"true"`
Key2 string `yaml:"key2"`
}
func (y *YAMLFile) OnChange() {
fmt.Println("YAML file changed")
}
func (y *YAMLFile) OnError(err error) {
fmt.Println("error while reloading YAML file:", err)
}
type TextFile struct {
Value string `default:"bar"`
}
Available tags are:
- default: default value (supports file paths for files and standard data types bool, float32, float64, int32, int64, string)
- env: environment variable name
- type: describes the file type (json, yaml, text), defaults to yaml if omitted
- required: indicates that the field is required, "Load()" will return an error in this case
- watch: indicates that the file should be watched for changes
type FieldRequiredError ¶
type FieldRequiredError struct {
FieldName string
}
FieldRequiredError is returned when a required field is not set.
func (*FieldRequiredError) Error ¶
func (e *FieldRequiredError) Error() string
type FileWatcher ¶
type FileWatcher interface {
OnChange()
OnError(error)
}
FileWatcher is an interface for watching file changes.
type InvalidKindError ¶
InvalidKindError is returned when a field is not of the expected kind.
func (*InvalidKindError) Error ¶
func (e *InvalidKindError) Error() string
type InvalidTagError ¶
type InvalidTagError struct {
Tag string
}
func (*InvalidTagError) Error ¶
func (e *InvalidTagError) Error() string
type MissingTagError ¶
type MissingTagError struct {
Tag string
}
MissingTagError is returned when a required tag is not set.
func (*MissingTagError) Error ¶
func (e *MissingTagError) Error() string
type ParsingError ¶
ParsingError is returned when an error occurs while parsing a value into a specific datatype.
func (*ParsingError) Error ¶
func (e *ParsingError) Error() string
type UnmarshalError ¶
UnmarshalError is returned when an error occurs while unmarshalling.
func (*UnmarshalError) Error ¶
func (e *UnmarshalError) Error() string
type ValidationError ¶
type ValidationError struct {
Errors []error
}
ValidationError is returned when one or multiple errors occured while validating the config.
func (*ValidationError) Error ¶
func (e *ValidationError) Error() string
Source Files