README
¶
envs - Reads configuration from various environments
Copyright (c) 2022, 2023, Geert JM Vanderkelen
The Go envs package offers functionality to read environment variables from the OS or dot-env files.
Overview
Environment Variables can be used, among other things, to configure
applications. This package offers functionality to read such environment
into a Go struct with special field tags.
Quick Start
For example, you want to read variables from the environment where the Go
application runs to identify the user and her home directory. This can be
easily achieved using Go's os.Getenv, but using this package, it would
be like this:
package main
import (
"fmt"
"github.com/golistic/envs"
)
type UserEnv struct {
Username string `envVar:"USER"`
HomeDir string `envVar:"HOME"`
Avatar string `envVar:"AVATAR" default:"🐣"`
}
func main() {
userEnv := &UserEnv{}
if err := envs.OSEnviron(userEnv); err != nil {
fmt.Println("Error:", err)
} else {
fmt.Printf("Username: %s\n", userEnv.Username)
fmt.Printf("HomeDir : %s\n", userEnv.HomeDir)
}
}
The above would output something similar too:
Username: alice
HomeDir : /Users/alice
Avatar : 🐣
The AVATAR environment variables was not available, so the default was used.
Supported Go Types
We currently support the following types (also pointer values):
- string
- numeric
int,int8,int16,int32,int64- empty mean 0 (zero)
- bool
true,t,1,on,enabledfalse,f,0,off,disabled- empty means
false
- time.Duration
- a Go duration as string, for example,
2d5m - empty means
0s
- a Go duration as string, for example,
Naked Variables
Naked variables are those without value and equal sign, for example:
# naked!
TCP_PORT
When the destination struct has the field reading TCP_PORT as pointer value,
for example, *int16, it will be nil. However, if type would be int16, a
syntax error is shown.
Supported Environments
We support the following environments:
- Operating System (OS) environment using Go's
os.Environ .envfiles using rules from- the dotenv project, for NodeJS projects
- the djanto-dotenv project, for Django projects
Operating System (OS) environment
Reading the Operating System (OS) environment is the most common way of getting the application's configuration.
See Quick Start for an example.
NodeJS projects
Reading an .env (dotenv) file from a NodeJS project is done using the rules
defined by the dotenv package.
Note: variable expansion not yet supported.
Example:
package main
import (
"fmt"
"github.com/golistic/envs"
)
type UserEnv struct {
Username string `envVar:"USER"`
HomeDir string `envVar:"HOME"`
Avatar string `envVar:"AVATAR" default:"🐣"`
}
func main() {
userEnv := &UserEnv{}
if err := envs.NodeJSDotEnvFromFile(userEnv, ".env"); err != nil {
fmt.Println("Error:", err)
} else {
fmt.Printf("Username: %s\n", userEnv.Username)
fmt.Printf("HomeDir : %s\n", userEnv.HomeDir)
fmt.Printf("Avatar : %s\n", userEnv.Avatar)
}
}
Django projects
Reading an .env (dotenv) file from a Django project is done using the rules
defined by the django-dotenv module.
Note: variable expansion not yet supported.
Example code is very similar to the NodeJS one, but using
the function envs.DjangoDotEnvFromFile instead.
License
Distributed under the MIT license. See LICENSE.txt for more information.
Documentation
¶
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DjangoDotEnv ¶
DjangoDotEnv reads environment variables from r and stores them in struct dest according to the rules defined by the django-dotenv project https://github.com/jpadilla/django-dotenv/blob/master/dotenv.py. The variables are stored and available within the dest struct.
func DjangoDotEnvFromFile ¶
DjangoDotEnvFromFile reads environment variables from a file with path and stores them in struct dest. See DjangoDotEnv() for further details.
func NodeJSDotEnv ¶
NodeJSDotEnv reads environment variables from a file typically called `.env` according to the rules defined by the NPM package https://www.npmjs.com/package/dotenv.
func NodeJSDotEnvFromFile ¶
NodeJSDotEnvFromFile reads environment variables from a file with path and stores them in struct dest. See NodeJSDotEnv() for further details.
Example ¶
package main
import (
"fmt"
"path"
"github.com/golistic/envs"
)
type UserEnv struct {
Username string `envVar:"USER"`
HomeDir string `envVar:"HOME"`
Avatar string `envVar:"AVATAR" default:"🐣"`
}
func main() {
userEnv := &UserEnv{}
p := path.Join(".", "_test_data", "js.example.env")
if err := envs.NodeJSDotEnvFromFile(userEnv, p); err != nil {
fmt.Println("Error:", err)
} else {
fmt.Printf("Username: %s\n", userEnv.Username)
fmt.Printf("HomeDir : %s\n", userEnv.HomeDir)
fmt.Printf("Avatar : %s\n", userEnv.Avatar)
}
}
Output: Username: alice HomeDir : /home/alice Avatar : 🙂️
func OSEnviron ¶
OSEnviron gets variables from the operating system's environment and stores the values in the struct dest.
This function uses Go's os.Environ.
Panics when dest is non-pointer, nil, or not a struct.
Example ¶
package main
import (
"fmt"
"os"
"github.com/golistic/envs"
)
type UserEnv struct {
Username string `envVar:"USER"`
HomeDir string `envVar:"HOME"`
Avatar string `envVar:"AVATAR" default:"🐣"`
}
func main() {
userEnv := &UserEnv{}
// we have to set the following so test is deterministic
_ = os.Setenv("USER", "alice")
_ = os.Setenv("HOME", "/Users/alice")
if err := envs.OSEnviron(userEnv); err != nil {
fmt.Println("Error:", err)
} else {
fmt.Printf("Username: %s\n", userEnv.Username)
fmt.Printf("HomeDir : %s\n", userEnv.HomeDir)
fmt.Printf("Avatar : %s\n", userEnv.Avatar)
}
}
Output: Username: alice HomeDir : /Users/alice Avatar : 🐣
Types ¶
type ErrReadingFile ¶
func (*ErrReadingFile) Error ¶
func (err *ErrReadingFile) Error() string
Source Files