envconfig

README

envconfig

import "github.com/kelseyhightower/envconfig"

Documentation

See godoc

Usage

Set some environment variables:

export MYAPP_DEBUG=false
export MYAPP_PORT=8080
export MYAPP_USER=Kelsey
export MYAPP_RATE="0.5"
export MYAPP_TIMEOUT="3m"
export MYAPP_USERS="rob,ken,robert"

Write some code:

package main

import (
    "fmt"
    "log"
    "time"

    "github.com/kelseyhightower/envconfig"
)

type Specification struct {
    Debug   bool
    Port    int
    User    string
    Users   []string
    Rate    float32
    Timeout time.Duration
}

func main() {
    var s Specification
    err := envconfig.Process("myapp", &s)
    if err != nil {
        log.Fatal(err.Error())
    }
    format := "Debug: %v\nPort: %d\nUser: %s\nRate: %f\nTimeout: %s\n"
    _, err = fmt.Printf(format, s.Debug, s.Port, s.User, s.Rate)
    if err != nil {
        log.Fatal(err.Error())
    }

    fmt.Println("Users:")
    for _, u := range s.Users {
        fmt.Printf("  %s\n", u)
    }
}

Results:

Debug: false
Port: 8080
User: Kelsey
Rate: 0.500000
Timeout: 3m0s
Users:
  rob
  ken
  robert

Struct Tag Support

Envconfig supports the use of struct tags to specify alternate, default, and required environment variables.

For example, consider the following struct:

type Specification struct {
    MultiWordVar string `envconfig:"multi_word_var"`
    DefaultVar   string `default:"foobar"`
    RequiredVar  string `required:"true"`
}

Envconfig will process value for MultiWordVar by populating it with the value for MYAPP_MULTI_WORD_VAR.

export MYAPP_MULTI_WORD_VAR="this will be the value"

# export MYAPP_MULTIWORDVAR="and this will not"

If envconfig can't find an environment variable value for MYAPP_DEFAULTVAR, it will populate it with "foobar" as a default value.

If envconfig can't find an environment variable value for MYAPP_REQUIREDVAR, it will return an when asked to process the struct.

If envconfig can't find an environment variable in the form PREFIX_MYVAR, and there is a struct tag defined, it will try to populate your variable with an environment variable that directly matches the envconfig tag in your struct definition:

export SERVICE_HOST=127.0.0.1
export MYAPP_DEBUG=true

type Specification struct {
    ServiceHost string `envconfig:"SERVICE_HOST"`
    Debug       bool
}

Documentation

Overview

Package envconfig implements decoding of environment variables based on a user defined specification. A typical use is using environment variables for configuration settings.

Index

• Variables
• func MustProcess(prefix string, spec interface{})
• func Process(prefix string, spec interface{}) error
• type ParseError
  • func (e *ParseError) Error() string

Variables

var ErrInvalidSpecification = errors.New("invalid specification must be a struct")

ErrInvalidSpecification indicates that a specification is of the wrong type.

Functions

func MustProcess

func MustProcess(prefix string, spec interface{})

MustProcess is the same as Process but panics if an error occurs

func Process

func Process(prefix string, spec interface{}) error

Process populates the specified struct based on environment variables

Types

type ParseError

type ParseError struct {
	KeyName   string
	FieldName string
	TypeName  string
	Value     string
}

A ParseError occurs when an environment variable cannot be converted to the type required by a struct field during assignment.

func (*ParseError) Error

func (e *ParseError) Error() string