env

package module
v0.5.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 1, 2025 License: BSD-3-Clause Imports: 13 Imported by: 6

README

env

Latest release Build status Go Report Card Documentation

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-2025 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

Examples

Constants

View Source 
const (
	ErrInvalidFormat   errors.Msg = "invalid format"
	ErrMissingEndQuote errors.Msg = "missing end quote"
	ErrEmptyKey        errors.Msg = "empty key"
)
View Source 
const ErrCircularDependency errors.Msg = "circular dependency"
View Source 
const ErrNotFound errors.Msg = "not found"

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

View Source 
const ErrStructExpected errors.Msg = "expected a struct type"
View Source 
const ErrStructPointerExpected errors.Msg = "expected a non-nil pointer to a struct"

Variables

This section is empty.

Functions

func Extract added in v0.5.0 

func Extract(v any) (map[string]any, error)

Extract environment variables names and values from the provided struct v.

func Format added in v0.5.0 

func Format(name string, val any) (string, error)

Format the name and val using a standard env format and return the resulting line as a string.

func FormatShellExport added in v0.5.0 

func FormatShellExport(name string, val any) (string, error)

FormatShellExport the name and val using a shell compatible env format and return the resulting line as a string.

func GetMarshalFunc added in v0.5.0 

func GetMarshalFunc(typ reflect.Type) rawconv.MarshalFunc

GetMarshalFunc returns the globally registered rawconv.MarshalFunc for reflect.Type typ or nil if there is none registered.

func GetUnmarshalFunc added in v0.5.0 

func GetUnmarshalFunc(typ reflect.Type) rawconv.UnmarshalFunc

GetUnmarshalFunc returns the globally registered rawconv.UnmarshalFunc for reflect.Type typ or nil if there is none registered.

func IsNotFound 

func IsNotFound(err error) bool

IsNotFound tests whether the provided error is ErrNotFound.

func Load added in v0.4.0 

func Load(envs Mapper) error

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

func Marshal added in v0.4.0 

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 added in v0.4.0 

func Overload(envs Mapper) error

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

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 added in v0.4.0 

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 added in v0.4.0 

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 added in v0.4.0 

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 added in v0.4.0 

func (d *Decoder) Strict() *Decoder

Strict sets the StrictTags option to true.

func (*Decoder) WithLookupper added in v0.4.0 

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

WithLookupper sets the internal Lookupper to l.

func (*Decoder) WithOptions added in v0.4.0 

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

WithOptions sets DecodeOptions to the provided DecodeOptions opts.

func (*Decoder) WithTagOptions added in v0.4.0 

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

WithTagOptions sets TagOptions to the provided TagOptions opts.

type EncodeOptions added in v0.4.0 

type EncodeOptions struct {
	// TakeValues takes the values from the struct field.
	TakeValues bool
	// ExportPrefix adds an "export" prefix to each relevant line.
	// Deprecated: Use [FormatShellExport] [Formatter] instead.
	ExportPrefix bool

	Formatter Formatter
}

type Encoder added in v0.4.0 

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

An Encoder writes env values to an output stream.

func NewEncoder added in v0.4.0 

func NewEncoder(w io.Writer) *Encoder

NewEncoder returns a new Encoder which writes to w.

func (*Encoder) Encode added in v0.4.0 

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

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

func (*Encoder) WithFormatter added in v0.5.0 

func (e *Encoder) WithFormatter(p Formatter) *Encoder

WithFormatter sets Formatter to the provided Formatter p.

func (*Encoder) WithOptions added in v0.4.0 

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

WithOptions sets EncodeOptions to the provided EncodeOptions opts.

func (*Encoder) WithTagOptions added in v0.4.0 

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

WithTagOptions sets TagOptions to the provided TagOptions opts.

func (*Encoder) WithWriter added in v0.4.0 

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

WithWriter changes the internal io.Writer to w.

type Extractor added in v0.5.0 

type Extractor struct {
	TagOptions
}

An Extractor extracts environment variables names and values from a struct value.

func NewExtractor added in v0.5.0 

func NewExtractor() *Extractor

NewExtractor returns a new Extractor.

func (*Extractor) Extract added in v0.5.0 

func (ex *Extractor) Extract(v any) (map[string]any, error)

Extract environment variables names and values from the provided struct v.

func (*Extractor) WithTagOptions added in v0.5.0 

func (ex *Extractor) WithTagOptions(opts TagOptions) *Extractor

WithTagOptions sets TagOptions to the provided TagOptions opts.

type Formatter added in v0.5.0 

type Formatter func(name string, val any) (string, error)

type LookupMapper 

type LookupMapper interface {
	Lookupper
	Mapper
}

func System added in v0.4.0 

func System() LookupMapper

System returns a LookupMapper 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 added in v0.4.0 

func ReplaceAll(m Map) (Map, error)

func (Map) Environ added in v0.4.0 

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 the 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 the Map are overwritten with the value of the key in src.

type Mapper added in v0.5.0 

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

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

type Marshaler added in v0.4.0 

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

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

type NamedValue added in v0.4.0 

type NamedValue struct {
	Name  string
	Value Value
}

func Parse 

func Parse(str string) (NamedValue, error)

Parse parses a string containing a possible name/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 added in v0.4.0 

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 added in v0.4.0 

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 added in v0.4.0 

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

func NewReplacer added in v0.4.0 

func NewReplacer(l Lookupper) *Replacer

func (*Replacer) Lookup added in v0.4.0 

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

func (*Replacer) Replace added in v0.4.0 

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

func (*Replacer) Unwrap added in v0.4.0 

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 added in v0.4.0 

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 added in v0.4.0 

type TagOptions = envtag.Options

TagOptions is an alias of 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.

Source Files

View all Source files

Directories

Path Synopsis
Package dotenv supports reading and loading environment variables from .env files based on active environment (e.g.
 Package dotenv supports reading and loading environment variables from .env files based on active environment (e.g.
Package envfile provides tools to read and load environment variables from files.
 Package envfile provides tools to read and load environment variables from files.
Package envtag provides tools to parse tags from strings or struct fields.
 Package envtag provides tools to parse tags from strings or struct fields.
internal
osfs

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.