env

README

env

A Zero Dependency - No Nonsense Environment Variable Parser / Unmarshaler

import "github.com/halorium/env"

Usage

There are two ways to use env

• Unmarshal into a struct using struct tags
• Get values as specified type for use how you want (no struct needed)

Example

Set some environment variables:

export TEST_STRING="some value"
export TEST_BOOL=true
export TEST_INT=1
export TEST_FLOAT=1.2
export TEST_DURATION="5s"
export TEST_LIST="one,two,three"
export TEST_MAP="one:1,two:2,three:3"

Write some code:

package main

import (
    "fmt"
    "log"
    "time"

    "github.com/halorium/env"
)

type Config struct {
	StringField   string         `env:"TEST_STRING"`
	BoolField     bool           `env:"TEST_BOOL"`
	IntField      int            `env:"TEST_INT"`
	FloatField    float64        `env:"TEST_FLOAT"`
	DurationField time.Duration  `env:"TEST_DURATION"`
	ListField     []string       `env:"TEST_LIST"`
	MapField      map[string]int `env:"TEST_MAP"`
}

func main() {
	var cfg Config
	err := env.Unmarshal(&cfg)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(cfg)
}

Other Ways to Use 'env'

Access environment variables as specified types directly.

s, err := env.AsString("TEST_STRING") // returns (string, error)

b, err := env.AsBool("TEST_BOOL") // returns (bool, error)

i, err := env.AsInt("TEST_INT", 64) // returns (int64, error)

i, err := env.AsUint("TEST_UINT", 64) // returns (uint64, error)

f, err := env.AsFloat("TEST_FLOAT", 64) // returns (float64, error)

d, err := env.AsDuration("TEST_DURATION") // returns (time.Duration, error)

Options (Struct Tags, Validation, etc.)

The default tag is 'env' however this can be changed in the options.

Example:

type Config struct {
	StringField   string         `custom:"TEST_STRING"`
	BoolField     bool           `custom:"TEST_BOOL"`
	IntField      int            `custom:"TEST_INT"`
	FloatField    float64        `custom:"TEST_FLOAT"`
	DurationField time.Duration  `custom:"TEST_DURATION"`
	ListField     []string       `custom:"TEST_LIST"`
	MapField      map[string]int `custom:"TEST_MAP"`
}

var cfg Config
options := env.Options{Tag: "custom"}
err := env.Unmarshal(&cfg, options)
if err != nil {
	log.Fatal(err)
}
fmt.Println(cfg)

Validation

env doesn't assume any validation, if an environment variable is not found then it is skipped.

The 'Required' option can be set to have an error returned if any environment variables are not set. Example:

var cfg Config
options := env.Options{Required: true}
err := env.Unmarshal(&cfg, options)
if err != nil {
	log.Fatal(err)
}
fmt.Println(cfg)

Ignored Fields

env will ignore the field if the tag is set to either an empty string '' or a hyphen '-'. Example:

type Config struct {
	StringField   string `env:"TEST_STRING"`
	BoolField     bool   `env:""`  // ignored
	IntField      int    `env:"-"` // ignored
}

Supported Field Types

• string
• bool
• int, int8, int16, int32, int64
• uint, uint8, uint16, uint32, uint64
• float32, float64
• slices of any supported type
• maps (keys and values of any supported type)
• time.Duration
• any field that implements the Unmarshaler interface (UnmarshalENV)

Note: Embedded structs using these fields are also supported.

Custom Unmarshaler

Any field whose type (or pointer-to-type) implements env.UnmarshalENV can control its own deserialization:

export URL="http://github.com/halorium/env"

type CustomURL url.URL

func (c *CustomURL) UnmarshalENV(v string) error {
	url, err := url.Parse(v)
	if err != nil {
		return err
	}
	*c = CustomURL(*url)
	return nil
}

type Config struct {
    URL CustomURL `env:"URL"`
}

Documentation

Index

• Variables
• func AsBool(s string) (v bool, e error)
• func AsDuration(s string) (v time.Duration, e error)
• func AsFloat(s string, bitSize int) (v float64, e error)
• func AsInt(s string, bitSize int) (v int64, e error)
• func AsString(s string) (string, error)
• func AsUint(s string, bitSize int) (v uint64, e error)
• func Unmarshal(obj interface{}, options ...Options) error
• type Options
• type Unmarshaler

Variables

var ErrInvalidType = errors.New("must be a pointer to a non-nil struct")

Functions

func AsBool

func AsBool(s string) (v bool, e error)

func AsDuration

func AsDuration(s string) (v time.Duration, e error)

func AsFloat

func AsFloat(s string, bitSize int) (v float64, e error)

func AsInt

func AsInt(s string, bitSize int) (v int64, e error)

func AsString

func AsString(s string) (string, error)

func AsUint

func AsUint(s string, bitSize int) (v uint64, e error)

func Unmarshal

func Unmarshal(obj interface{}, options ...Options) error

Types

type Options

type Options struct {
	Tag      string // default "env"
	Required bool   // default false
}

type Unmarshaler

type Unmarshaler interface {
	UnmarshalENV(value string) error
}