env

README

env

Package env reads and parses environment variables from various sources. It supports unmarshaling into any type and (over)loading the variables into the system's environment.

Included features are:

• Reading environment variables from various sources;
• Decoding environment variables into any type;
• Encoding environment variables from any type;
• Loading and overloading into the system's environment variables.

---

go get github.com/go-pogo/env

import "github.com/go-pogo/env"

Usage

Below example demonstrates how to decode system environment variables into a struct.

package main

import (
    "github.com/davecgh/go-spew/spew"
    "github.com/go-pogo/env"
    "time"
)

func main() {
    type Config struct {
        Foo     string
        Timeout time.Duration `default:"10s"`
    }

    var conf Config
    if err := env.NewDecoder(env.System()).Decode(&conf); err != nil {
        panic(err)
    }

    spew.Dump(conf)
    // Output:
    // (env.Config) {
    //  Foo: (string) "",
    //  Timeout: (time.Duration) 10s
    // }
}

Usage with dotenv

This example reads .env files from the example directory and decodes the found variables into a struct.

package main

import (
    "github.com/davecgh/go-spew/spew"
    "github.com/go-pogo/env"
    "github.com/go-pogo/env/dotenv"
    "time"
)

func main() {
    type Config struct {
        Foo     string
        Timeout time.Duration `default:"10s"`
    }

    var conf Config
    if err := env.NewDecoder(dotenv.Read("example", dotenv.None)).Decode(&conf); err != nil {
        panic(err)
    }

    spew.Dump(conf)
    // Output:
    // (dotenv.Config) {
    //  Foo: (string) (len=3) "bar",
    //  Timeout: (time.Duration) 2s
    // }
}

Documentation

Additional detailed documentation is available at pkg.go.dev

Created with

License

Copyright © 2020-2024 Roel Schut. All rights reserved.

This project is governed by a BSD-style license that can be found in the LICENSE file.

Documentation

Overview

Package env implements encoding and decoding of environment variables from files, the OS or other io.Reader compatible data sources. It supports unmarshalling to structs and maps, and marshaling from various types to files and io.Writer. It can also be used to load/overload environment variables into the system.

The mapping between environment variables and Go values is described in the documentation for the Marshal and Unmarshal functions.

Supported types

This package uses the rawconv package to parse/unmarshal any string value to its Go type equivalent. Additionally, custom types may implement the Unmarshaler interface to implement its own unmarshalling rules, or register an unmarshaler function using rawconv.Register.

Load and overload

Additional os.Environ entries can be loaded using the ReadAndLoad, OpenAndLoad, ReadAndOverload and OpenAndOverload functions. The source is read any bash style variables are replaced before being set to the system using Setenv.

Dotenv

The dotenv package supports reading and loading environment variables from .env files based on active environment (e.g. prod, dev etc.). See its documentation for more information.

Writing

This package can also write environment variables to an io.Writer.

Index

• Constants
• func IsNotFound(err error) bool
• func Load(envs Environment) error
• func Marshal(v any) ([]byte, error)
• func Overload(envs Environment) error
• func ScanLines(data []byte, atEOF bool) (advance int, token []byte, err error)
• func Setenv(key string, val Value) error
• func Unmarshal(data []byte, v any) error
• type DecodeOptions
• type Decoder
  • func NewDecoder(src ...Lookupper) *Decoder
  • func NewReaderDecoder(r io.Reader) *Decoder
  • func (d *Decoder) Decode(v any) error
  • func (d *Decoder) Strict() *Decoder
  • func (d *Decoder) WithLookupper(l Lookupper) *Decoder
  • func (d *Decoder) WithOptions(opts DecodeOptions) *Decoder
  • func (d *Decoder) WithTagOptions(opts TagOptions) *Decoder
• type EncodeOptions
• type Encoder
  • func NewEncoder(w io.Writer) *Encoder
  • func (e *Encoder) Encode(v any) error
  • func (e *Encoder) WithOptions(opts EncodeOptions) *Encoder
  • func (e *Encoder) WithTagOptions(opts TagOptions) *Encoder
  • func (e *Encoder) WithWriter(w io.Writer) *Encoder
• type Environment
• type EnvironmentLookupper
  • func System() EnvironmentLookupper
• type Lookupper
  • func Chain(l ...Lookupper) Lookupper
• type LookupperFunc
  • func (f LookupperFunc) Lookup(key string) (Value, error)
• type Map
  • func Environ() Map
  • func ReplaceAll(m Map) (Map, error)
  • func (m Map) Environ() (Map, error)
  • func (m Map) Lookup(key string) (Value, error)
  • func (m Map) Merge(src map[string]string)
  • func (m Map) MergeValues(src map[string]Value)
• type Marshaler
• type NamedValue
  • func Parse(str string) (NamedValue, error)
  • func (nv NamedValue) GoString() string
• type ParseError
  • func (e *ParseError) Error() string
  • func (e *ParseError) Unwrap() error
• type Reader
  • func NewReader(r io.Reader) *Reader
  • func (r *Reader) Environ() (Map, error)
  • func (r *Reader) Lookup(key string) (Value, error)
• type Replacer
  • func NewReplacer(l Lookupper) *Replacer
  • func (r *Replacer) Lookup(k string) (Value, error)
  • func (r *Replacer) Replace(v Value) (Value, error)
  • func (r *Replacer) Unwrap() Lookupper
• type Scanner
  • func NewScanner(r io.Reader) *Scanner
  • func (s *Scanner) Bytes() []byte
  • func (s *Scanner) Err() error
  • func (s *Scanner) NamedValue() (NamedValue, error)
  • func (s *Scanner) Scan() bool
  • func (s *Scanner) Text() string
• type TagOptions
• type Unmarshaler
• type Value
  • func Getenv(key string) Value
  • func Lookup(key string, from ...Lookupper) (Value, error)
  • func LookupEnv(key string) (Value, bool)

Examples

• Decoder.Decode
• Marshal
• Unmarshal

Constants

const (
	ErrInvalidFormat   errors.Msg = "invalid format"
	ErrMissingEndQuote errors.Msg = "missing end quote"
	ErrEmptyKey        errors.Msg = "empty key"
)

const ErrCircularDependency errors.Msg = "circular dependency"

const ErrNotFound errors.Msg = "not found"

ErrNotFound is returned when a Lookup call cannot find a matching key.

const ErrStructExpected errors.Msg = "expected a struct type"

const ErrStructPointerExpected errors.Msg = "expected a non-nil pointer to a struct"

Functions

func IsNotFound

func IsNotFound(err error) bool

IsNotFound tests whether the provided error is ErrNotFound.

func Load

func Load(envs Environment) error

Load sets the system's environment variables with those from the Map when they do not exist.

func Marshal

func Marshal(v any) ([]byte, error)

Marshal returns v encoded in env format.

Example

type Envs struct {
	Foo string
	Bar struct {
		Url url.URL `default:"https://example.com"`
	} `env:",inline"`
	Timeout time.Duration `default:"10s"`
	Ip      net.IP
}

b, err := Marshal(Envs{})
if err != nil {
	panic(err)
}

fmt.Println(string(b))

Output:

FOO=
URL=https://example.com
TIMEOUT=10s
IP=

func Overload

func Overload(envs Environment) error

Overload sets and overwrites the system's environment variables with those from the Map.

func ScanLines

func ScanLines(data []byte, atEOF bool) (advance int, token []byte, err error)

ScanLines is a bufio.SplitFunc that returns each line of text using bufio.ScanLines. Additionally, any leading or trailing whitespace is stripped from the token result. Lines that start with a #, after all leading whitespace is stripped, are treated as comments and result in an empty token result.

func Setenv

func Setenv(key string, val Value) error

Setenv sets the Value of the environment variable named by the key using // os.Setenv.

func Unmarshal

func Unmarshal(data []byte, v any) error

Unmarshal parses the env formatted data and stores the result in the value pointed to by v. If v is nil or not a pointer, Unmarshal returns an ErrStructPointerExpected error.

Example

type Envs struct {
	Foo string
	Bar struct {
		Url url.URL
	} `env:",inline"`
	Timeout time.Duration `default:"10s"`
	Ip      net.IP
}

var data = `
FOO=bar
# ignore me
URL=http://example.com
IP=192.168.1.1`

var envs Envs
if err := Unmarshal([]byte(data), &envs); err != nil {
	panic(err)
}

spew.Dump(envs)

Output:

(env.Envs) {
 Foo: (string) (len=3) "bar",
 Bar: (struct { Url url.URL }) {
  Url: (url.URL) http://example.com
 },
 Timeout: (time.Duration) 10s,
 Ip: (net.IP) (len=16 cap=16) 192.168.1.1
}

Types

type DecodeOptions

type DecodeOptions struct {
	// ReplaceVars
	ReplaceVars bool
}

type Decoder

type Decoder struct {
	DecodeOptions
	TagOptions
	// contains filtered or unexported fields
}

A Decoder looks up environment variables while decoding them into a struct.

func NewDecoder

func NewDecoder(src ...Lookupper) *Decoder

NewDecoder returns a new Decoder which looks up environment variables from the provided Lookupper(s). When a Chain is provided it must not be empty.

func NewReaderDecoder

func NewReaderDecoder(r io.Reader) *Decoder

NewReaderDecoder returns a new Decoder similar to calling NewDecoder with NewReader as argument.

func (*Decoder) Decode

func (d *Decoder) Decode(v any) error

Example

Below example demonstrates how to decode system environment variables into a struct.

type Config struct {
	Foo     string
	Timeout time.Duration `default:"10s"`
}

var conf Config
if err := NewDecoder(System()).Decode(&conf); err != nil {
	panic(err)
}

spew.Dump(conf)

Output:

(env.Config) {
 Foo: (string) "",
 Timeout: (time.Duration) 10s
}

func (*Decoder) Strict

func (d *Decoder) Strict() *Decoder

Strict sets the StrictTags option to true.

func (*Decoder) WithLookupper

func (d *Decoder) WithLookupper(l Lookupper) *Decoder

WithLookupper changes the internal Lookupper to l.

func (*Decoder) WithOptions

func (d *Decoder) WithOptions(opts DecodeOptions) *Decoder

WithOptions changes the internal DecodeOptions to opts.

func (*Decoder) WithTagOptions

func (d *Decoder) WithTagOptions(opts TagOptions) *Decoder

WithTagOptions changes the internal TagOptions to opts.

type EncodeOptions

type EncodeOptions struct {
	// TakeValues takes the values from the struct field.
	TakeValues bool
	// ExportPrefix adds an export prefix to each relevant line.
	ExportPrefix bool
}

type Encoder

type Encoder struct {
	EncodeOptions
	TagOptions
	// contains filtered or unexported fields
}

An Encoder writes env values to an output stream.

func NewEncoder

func NewEncoder(w io.Writer) *Encoder

NewEncoder returns a new Encoder which writes to w.

func (*Encoder) Encode

func (e *Encoder) Encode(v any) error

Encode writes the env format encoding of v to the underlying io.Writer. Supported types of v are:

• Map
• map[string]Value
• map[fmt.Stringer]Value
• []NamedValue
• []envtag.Tag
• any struct type the rawconv package can handle

func (*Encoder) WithOptions

func (e *Encoder) WithOptions(opts EncodeOptions) *Encoder

WithOptions changes the internal EncodeOptions to opts.

func (*Encoder) WithTagOptions

func (e *Encoder) WithTagOptions(opts TagOptions) *Encoder

WithTagOptions changes the internal TagOptions to opts.

func (*Encoder) WithWriter

func (e *Encoder) WithWriter(w io.Writer) *Encoder

WithWriter changes the internal io.Writer to w.

type Environment

type Environment interface {
	Environ() (Map, error)
}

Environment provides a Map of keys and values representing the environment.

type EnvironmentLookupper

type EnvironmentLookupper interface {
	Lookupper
	Environment
}

func System

func System() EnvironmentLookupper

System returns an EnvironmentLookupper which wraps the operating system's env related functions.

dec := NewDecoder(System())

type Lookupper

type Lookupper interface {
	// Lookup retrieves the Value of the environment variable named by the key.
	// It must return an ErrNotFound error if the key is not present.
	Lookup(key string) (val Value, err error)
}

func Chain

func Chain(l ...Lookupper) Lookupper

Chain multiple Lookupper(s) to lookup keys from.

type LookupperFunc

type LookupperFunc func(key string) (Value, error)

func (LookupperFunc) Lookup

func (f LookupperFunc) Lookup(key string) (Value, error)

type Map

type Map map[string]Value

Map represents a map of key value pairs.

func Environ

func Environ() Map

Environ returns a Map with the environment variables using os.Environ.

func ReplaceAll

func ReplaceAll(m Map) (Map, error)

func (Map) Environ

func (m Map) Environ() (Map, error)

Environ returns a copy of the Map.

func (Map) Lookup

func (m Map) Lookup(key string) (Value, error)

Lookup retrieves the Value of the environment variable named by the key. If the key is present in Map, the value (which may be empty) is returned and the boolean is true. Otherwise, the returned value will be empty and the boolean is false.

func (Map) Merge

func (m Map) Merge(src map[string]string)

Merge any map of strings into this Map. Existing keys in Map are overwritten with the value of the key in src.

func (Map) MergeValues

func (m Map) MergeValues(src map[string]Value)

MergeValues merges a map of Value into this Map. Existing keys in Map m are overwritten with the value of the key in src.

type Marshaler

type Marshaler interface {
	MarshalEnv() ([]byte, error)
}

Marshaler is the interface implemented by types that can marshal themselves into valid env values.

type NamedValue

type NamedValue struct {
	Name  string
	Value Value
}

func Parse

func Parse(str string) (NamedValue, error)

Parse parses a string containing a possible key value pair. Any whitespace at the start and/or end of str is trimmed. It returns an empty NamedValue when the provided str, after trimming, begins with #.

func (NamedValue) GoString

func (nv NamedValue) GoString() string

type ParseError

type ParseError struct {
	Err error
	Str string
}

func (*ParseError) Error

func (e *ParseError) Error() string

func (*ParseError) Unwrap

func (e *ParseError) Unwrap() error

type Reader

type Reader struct {
	// contains filtered or unexported fields
}

func NewReader

func NewReader(r io.Reader) *Reader

NewReader returns a Reader which looks up environment variables from the provided io.Reader r.

dec := NewDecoder(NewReader(r))

func (*Reader) Environ

func (r *Reader) Environ() (Map, error)

Environ continues reading and scanning the internal io.Reader and returns a Map of all found environment variables when either EOF is reached or an error has occurred.

func (*Reader) Lookup

func (r *Reader) Lookup(key string) (Value, error)

Lookup continues reading and scanning the internal io.Reader until either EOF is reached or key is found. It will return the found value, ErrNotFound if not found, or an error if any has occurred while scanning.

type Replacer

type Replacer struct {
	// contains filtered or unexported fields
}

func NewReplacer

func NewReplacer(l Lookupper) *Replacer

func (*Replacer) Lookup

func (r *Replacer) Lookup(k string) (Value, error)

func (*Replacer) Replace

func (r *Replacer) Replace(v Value) (Value, error)

func (*Replacer) Unwrap

func (r *Replacer) Unwrap() Lookupper

Unwrap returns the original Lookupper that was wrapped by the Replacer.

type Scanner

type Scanner struct {
	// contains filtered or unexported fields
}

func NewScanner

func NewScanner(r io.Reader) *Scanner

NewScanner returns a new Scanner which wraps a bufio.Scanner that reads from io.Reader r. The split function defaults to ScanLines. Successive calls to the Scan method will (just like bufio.Scanner) step through the 'tokens' of the read bytes, skipping the bytes between the tokens.

func (*Scanner) Bytes

func (s *Scanner) Bytes() []byte

Bytes returns the most recent token generated by a call to Scan. The underlying array may point to data that will be overwritten by a subsequent call to Scan. It does no allocation.

func (*Scanner) Err

func (s *Scanner) Err() error

Err returns the first non-EOF error that was encountered by the Scanner.

func (*Scanner) NamedValue

func (s *Scanner) NamedValue() (NamedValue, error)

NamedValue returns the parsed NamedValue from the most recent token generated by a call to Scan.

func (*Scanner) Scan

func (s *Scanner) Scan() bool

Scan advances the scanner to the next token, which will then be available through the Bytes or Text method. The token is guaranteed to not be empty. See bufio.Scanner for additional details.

func (*Scanner) Text

func (s *Scanner) Text() string

Text returns the most recent token generated by a call to Scan as a newly allocated string holding its bytes.

type TagOptions

type TagOptions = envtag.Options

type Unmarshaler

type Unmarshaler interface {
	UnmarshalEnv([]byte) error
}

Unmarshaler is the interface implemented by types that can unmarshal a textual representation of themselves. It is similar to encoding.TextUnmarshaler.

type Value

type Value = rawconv.Value

Value is an alias of rawconv.Value.

func Getenv

func Getenv(key string) Value

Getenv retrieves the Value of the environment variable named by the key using os.Getenv.

func Lookup

func Lookup(key string, from ...Lookupper) (Value, error)

Lookup retrieves the Value of the environment variable named by the key from any of the provided Lookupper(s). If the key is present the value (which may be empty) is returned and the error is nil. Otherwise, the returned value will be empty and the error ErrNotFound.

func LookupEnv

func LookupEnv(key string) (Value, bool)

LookupEnv retrieves the Value of the environment variable named by the key using os.LookupEnv.