Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/deanishe/go-env
Access environment variables & populate structs from them
https://github.com/deanishe/go-env
configuration environment-variables envvars mapping settings struct
Last synced: about 2 months ago
JSON representation
Access environment variables & populate structs from them
- Host: GitHub
- URL: https://github.com/deanishe/go-env
- Owner: deanishe
- License: mit
- Created: 2018-01-28T18:55:42.000Z (almost 7 years ago)
- Default Branch: master
- Last Pushed: 2020-07-31T18:23:48.000Z (over 4 years ago)
- Last Synced: 2024-10-02T14:07:54.156Z (3 months ago)
- Topics: configuration, environment-variables, envvars, mapping, settings, struct
- Language: Go
- Size: 66.4 KB
- Stars: 11
- Watchers: 3
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
go-env
======
![Build Status][github-status-icon]
[![Go Report Card][goreport-icon]][goreport-link]
[![Codacy coverage][coverage-icon]][codacy-link]
[![GitHub licence][licence-icon]][licence-link]
[![GoDoc][godoc-icon]][godoc-link]
Access environment variables from Go, and populate structs from them.
- [Usage](#usage)
- [Access environment variables](#access-environment-variables)
- [Binding](#binding)
- [Customisation](#customisation)
- [Dumping](#dumping)
- [Installation](#installation)
- [Documentation](#documentation)
- [Licence](#licence)
Import path is `go.deanishe.net/env`.
You can directly access environment variables, or populate your structs from them using struct tags and `env.Bind()`.
### Access environment variables ###
Read `int`, `float64`, `duration` and `string` values from environment variables, with optional fallback values for unset variables.
```go
import "go.deanishe.net/env"
// Get value for key or return empty string
s := env.Get("SHELL")
// Get value for key or return a specified default
s := env.Get("DOES_NOT_EXIST", "fallback value")
// Get an int (or 0 if SOME_NUMBER is unset or empty)
i := env.GetInt("SOME_NUMBER")
// Int with a fallback
i := env.GetInt("SOME_UNSET_NUMBER", 10)
```
You can also populate a struct directly from the environment by appropriately tagging it and calling `env.Bind()`:
```go
// Simple configuration struct
type config struct {
HostName string `env:"HOSTNAME"` // default would be HOST_NAME
Port int // leave as default (PORT)
SSL bool `env:"USE_SSL"` // default would be SSL
Online bool `env:"-"` // ignore this field
}
// Set some values in the environment for test purposes
os.Setenv("HOSTNAME", "api.example.com")
os.Setenv("PORT", "443")
os.Setenv("USE_SSL", "1")
os.Setenv("ONLINE", "1") // will be ignored
// Create a config and bind it to the environment
c := &config{}
if err := Bind(c); err != nil {
// handle error...
}
// config struct now populated from the environment
fmt.Println(c.HostName)
fmt.Printf("%d\n", c.Port)
fmt.Printf("%v\n", c.SSL)
fmt.Printf("%v\n", c.Online)
// Output:
// api.example.com
// 443
// true
// false
```
Variables are retrieved via implementors of the `env.Env` interface (which `env.Bind()` accepts as a second, optional parameter):
```go
type Env interface {
// Lookup retrieves the value of the variable named by key.
//
// It follows the same semantics as os.LookupEnv(). If a variable
// is unset, the boolean will be false. If a variable is set, the
// boolean will be true, but the variable may still be an empty
// string.
Lookup(key string) (string, bool)
}
```
So you can pass a custom `Env` implementation to `Bind()` in order to populate structs from a source other than environment variables.
See [_examples/docopt][docopt] to see how to implement a custom `Env` that populates a struct from `docopt` command-line options.
Dump a struct to a map[string]string by passing it to Dump():
```go
type options struct {
Hostname string
Port int
}
o := options{
Hostname: "www.example.com",
Port: 22,
}
vars, err := Dump(o)
if err != nil {
// handler err
}
fmt.Println(vars["HOSTNAME"]) // -> www.example.com
fmt.Println(vars["PORT"]) // -> 22
```
```bash
go get go.deanishe.net/env
```
Read the documentation on [GoDoc][godoc-link].
This library is released under the [MIT Licence][mit].
[mit]: ./LICENCE.txt
[docopt]: _examples/docopt/docopt_example.go
[godoc-icon]: https://godoc.org/go.deanishe.net/env?status.svg
[godoc-link]: https://godoc.org/go.deanishe.net/env
[goreport-link]: https://goreportcard.com/report/github.com/deanishe/go-env
[goreport-icon]: https://goreportcard.com/badge/github.com/deanishe/go-env
[coverage-icon]: https://img.shields.io/codacy/coverage/a0ebe54382ad43bf8604b6d6aac02400?color=brightgreen
[codacy-link]: https://www.codacy.com/app/deanishe/go-env
[azure-status-icon]: https://img.shields.io/azure-devops/build/deanishe/3b09feef-08fa-42bc-830e-57ce1de63779/2
[azure-link]: https://dev.azure.com/deanishe/go-env/_build
[licence-icon]: https://img.shields.io/github/license/deanishe/go-env
[licence-link]: https://github.com/deanishe/go-env/blob/master/LICENCE.txt
[github-status-link]: https://github.com/deanishe/go-env/actions?query=workflow%3ACI
[github-status-icon]: https://github.com/deanishe/go-env/workflows/CI/badge.svg