README
¶
Lamenv
Lamenv is a Go library that proposes a way to decode and encode the environment variable to/from a Golang struct.
Installation
Standard go get:
$ go get github.com/nexucis/lamenv
Purpose
There are plenty of library available to unmarshall a configuration using the environment. But, so far I didn't find one that is able to unmarshall an array of struct or a map of struct. Also, each times other library required to add new tags in the struct which bothered me.
I have written this library to be able to use it after spending times to support a yaml configuration. And then, you think it could be interesting to get the config using the environment, but you don't want to spend time again to make it work. For example, when moving to the cloud you forget a bit that you are using some password in your config, and an easy way to get it is to use a secret that you can read in an environment variable.
And here is the solution ;). lamenv. Get it, use it, forget it.
More documentation is available in the golang doc to know how to use it.
Tips
To be able to unmarshall an array, lamenv is looking to the number of the index in the environment variable.
For example, you have the following struct:
type myConfig struct{
Test []string `yaml:"test"`
}
The environment variable should look like this if you want to map it to this struct:
MY_PREFIX_TEST_0="first value"
MY_PREFIX_TEST_1="another value"
This logic is used as well for an array of struct
type SliceOfStruct struct {
A string `yaml:"a"`
}
type myConfig struct {
Sli []SliceOfStruct `yaml:"slice"`
}
The environment variable should look like this if you want to map it to this struct:
MY_PREFIX_SLICE_0_A="first value"
MY_PREFIX_SLICE_1_A="another value"
Documentation
¶
Overview ¶
Package lamenv is proposing a way to support the environment variable for Golang Using this package, you can encode or decode the environment variable with a proper Golang structure.
Source code and other details for the project are available at GitHub:
https://github.com/Nexucis/lamenv
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Marshal ¶
Marshal serializes the value provided into a series of environment variable. The series of environment variable generated will reflect the structure of the value itself Maps and pointers (to struct, string, int, etc) are accepted as the object parameter.
Struct fields are only marshalled if they are exported (have an upper case first letter), and are marshalled using the field name uppercased as the default key. Custom keys may be defined via the "json", "yaml" or "mapstructure" (by default) name in the field tag: the content preceding the first comma is used as the key, and the following comma-separated options are used to tweak the marshalling process.
The field tag format accepted is:
`(...) json|yaml|mapstructure:"[<key>][,<flag1>[,<flag2>]]" (...)`
The following flags are currently supported:
omitempty Only include the field if it's not set to the zero
value for the type or to empty slices or maps.
Zero valued structs will be omitted if all their public
fields are zero.
inline or squash Inline the field, which must be a struct,
causing all of its fields or keys to be processed as if
they were part of the outer struct.
In addition, if the key is "-", the field is ignored.
parts is the list of prefix of the future environment variable. It can be empty.
func Unmarshal ¶
Unmarshal is looking at the object to guess which environment variable is matching.
Maps and pointers (to a struct, string, int, etc) are accepted as object. If an internal pointer within a struct is not initialized, the lamenv package will initialize it if necessary for unmarshalling the provided data. The object parameter must not be nil. The parts can be used to inject a prefix of the environment variable
Struct fields are only unmarshalled if they are exported (have an upper case first letter), and are unmarshalled using the field name uppercased as the default key. Custom keys can be defined via the "json", "yaml" and "mapstructure" name in the field tag. If multiple tag name are defined, "json" is considered at first, then "yaml" and finally "mapstructure".
Note: When using a map, it's possible for the Unmarshal method to fail because it's finding multiple way to unmarshal the same environment variable for different field in the struct (that could be at different depth). It's usually because when using a map, the method has to guess which key to use to unmarshal the environment variable. And sometimes, it's possible there are several keys found.
Example of how to use it with the following environment variables available:
MY_PREFIX_A = 1
MY_PREFIX_B = 2
type T struct {
F int `json:"a,omitempty"`
B int
}
var t T
lamenv.Unmarshal(&t, []string{"MY_PREFIX"})
Types ¶
type Lamenv ¶
type Lamenv struct {
// contains filtered or unexported fields
}
Lamenv is the exported struct of the package that can be used to fine-tune the way to unmarshall the different struct.
func New ¶
func New() *Lamenv
New is the method to use to initialize the struct Lamenv. The struct can then be fine tuned using the appropriate exported method.
func (*Lamenv) AddTagSupport ¶
AddTagSupport modify the current tag list supported by adding the one passed as a parameter. If you prefer to override the default tag list supported by Lamenv, use the method OverrideTagSupport instead.
func (*Lamenv) OverrideTagSupport ¶
OverrideTagSupport overrides the current tag list supported by the one passed as a parameter. If you prefer to add new tag supported instead of overriding the current list, use the method AddTagSupport instead.
type Marshaler ¶
The Marshaler interface may be implemented by types to customize their behavior when being marshaled into a series of environment variable document.
parts is the list of prefix that would composed the final environment variables.
If an error is returned by MarshalEnv, the marshaling procedure stops and returns with the provided error.
type Unmarshaler ¶
The Unmarshaler interface may be implemented by types to customize their behavior when being unmarshaled from a series of environment varialb.
parts is the list of prefix that would composed the final environment variables. Note: for the moment, customize the way to decode a type may not work when using a map. The main reason is because the system is then not able to determinate which key it has to use when unmarshalling a map.
Source Files