emp
emp copied to clipboard
A golang library for parsing environment variables in an easier way.
emp
What is emp?
emp is a Go library for parsing environment variable to structures, while providing helpful error handling.
Why emp?
Directly read environment variables in Go will case a lot of repeat code like this:
package main
import "os"
func main() {
envStringValue := os.Getenv("SOME_ENV")
if envStringValue == "" {
panic("missing SOME_ENV")
// OR: envStringValue = "default"
}
// convert string to the type you want
envValue := sthConvert(envStringValue)
}
It's a bit complicated and unclear, isn't it?
Let's try emp!
package main
import "github.com/XMLHexagram/emp"
func main() {
type EnvModel struct {
SOME_ENV int
SOME_ENV_1 string
SOME_ENV_2 []string
// whatever type you want, but not map
}
envModel := new(EnvModel)
err := Parse(envModel)
if err != nil {
panic(err)
}
}
Now, SOME_ENV
is parsed to envModel
.
It is simpler and easier to understand than the previous one, right?
What, no? Then you need to see Usage below.
Installation
Standard go get
:
$ go get github.com/XMLHexagram/emp
Usage
For full usage and examples see the Godoc.
Or you can see Real Project Example, Test Case and Example Test Case
Here is a short introduction of emp:
Parse Environment variables to struct
The easiest way to use emp is to use Parse
function.
First, define an empty struct:
type EnvModel struct {
JWT_SECERT string
JWT_EXPIRE int
REDIS_URL string
SERVER_ struct {
PORT string
HTTP_TIMEOUT int
}
// whatever type you want, but not map
}
Then, Let's use emp.Marshal
to see the environment variables emp will looking for.
res, err := emp.Marshal(&EnvModel{})
fmt.Println(res)
/*
JWT_SECERT=
JWT_EXPIRE=0
REDIS_URL=
// you want SERVER_PORT and SERVER_HTTP_TIMEOUT, right?
PORT=
HTTP_TIMEOUT=0
*/
Good, but not good enough. Maybe you want SERVER_PORT
and SERVER_HTTP_TIMEOUT
.
Let's try AutoPrefix
:
parser, _ := emp.NewParser(&Config{
AutoPrefix: true,
})
res, _ = parser.Marshal(&EnvModel{})
fmt.Println(res)
/*
JWT_SECERT=
JWT_EXPIRE=0
REDIS_URL=
// the prefix is `SERVER_` now!
SERVER_PORT=
SERVER_HTTP_TIMEOUT=0
*/
Much better, but can emp do something more?
Of course can, let's try field tag
to customize the prefix
and environment variable
emp looking for:
type EnvModel struct {
JwtSecret string `emp:"JWT_SECRET"`
JwtExpire int `emp:"JWT_EXPIRE"`
RedisUrl string `emp:"REDIS_URL"`
Server struct {
Port string `emp:"SERVER_PORT"`
HttpTimeout int `emp:"SERVER_HTTP_TIMEOUT"`
} `emp:"prefix:SERVER_"`
// whatever type you want, but not map
}
res, _ := emp.Marshal(&EnvModel1{})
fmt.Println(res)
/*
JWT_SECRET=
JWT_EXPIRE=0
REDIS_URL=
SERVER_SERVER_PORT=
SERVER_SERVER_HTTP_TIMEOUT=0
*/
COOL! This struct defines looks perfect. Now, we only need one more step.
Finally, call Parse
function:
envModel := new(EnvModel)
_ := emp.Parse(envModel)
envModel is now filled with environment variables you need. 🎉
That's All?
No, emp also provides more features to customize your environment variables parsing.
See emp doc for more details.
Q & A
Why is it called "emp"?
A: emp => EnvironMent variable Parser
Does emp support case sensitive keys?
Yes, but maybe not in the future.
As we all know, environment variables in most time are ALL CAPS. So if someone need this feature, I will add it as a configurable option.
How to set environment variables?
There is an easy way to set environment variables by use godotenv
Support for map type?
No, the only not supported native type of Go is map. Sincerely, I have no idea on how to support it. If you have any idea, please open an issue.
Thanks
Thanks to mitchellh/mapstructure and spf13/viper, Your repos have inspired me, and I used some code from your repo.
More Feature or Bug Report
Feel free to open an issue when you want to report a bug, feature or ask for help. ✨