env

Documentation

Overview

Package env loads dotenv files and process environment variables into nested maps and Go structs. Multiple sources merge with later scalars overriding earlier ones; maps merge recursively.

Example:

c := env.New(
    env.WithFile(".default.env"),
    env.WithFile(".env"),
    env.WithCurrentEnvironment(),
)
var cfg MyConfig
if err := c.Unmarshal(&cfg); err != nil { ... }

Index

• type Codec
  • func New(opts ...Option) *Codec
  • func (c *Codec) Map(ctx context.Context) (map[string]any, error)
  • func (c *Codec) Marshal(src any) ([]byte, error)
  • func (c *Codec) Unmarshal(dst any) error
  • func (c *Codec) UnmarshalContext(ctx context.Context, dst any) error
  • func (c *Codec) WriteTo(w io.Writer, src any) (int64, error)
• type Option
  • func WithBytes(b []byte) Option
  • func WithCurrentEnvironment() Option
  • func WithDecodeHook(h mapstructure.DecodeHookFunc) Option
  • func WithFile(path string) Option
  • func WithHTTPClient(client *http.Client) Option
  • func WithHTTPHeader(k, v string) Option
  • func WithKeyNormalizer(n keymap.Normalizer) Option
  • func WithPrefix(prefix string) Option
  • func WithReader(r io.Reader) Option
  • func WithSliceMerge(s merge.SliceStrategy) Option
  • func WithTagName(name string) Option
  • func WithTrim(enable bool) Option
  • func WithURL(raw string) Option
  • func WithWeaklyTyped(enable bool) Option

Types

type Codec

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

Codec loads environment-style key/value data from multiple sources.

func New

func New(opts ...Option) *Codec

New builds a Codec from options. Sources are merged left-to-right; later sources override earlier scalar leaves (see package merge).

func (*Codec) Map

func (c *Codec) Map(ctx context.Context) (map[string]any, error)

Map returns the merged nested map after all sources are loaded and keys normalized.

func (*Codec) Marshal

func (c *Codec) Marshal(src any) ([]byte, error)

Marshal encodes src into dotenv-style bytes (KEY=value lines, sorted keys). src may be a struct or map[string]any.

func (*Codec) Unmarshal

func (c *Codec) Unmarshal(dst any) error

Unmarshal decodes using context.Background.

func (*Codec) UnmarshalContext

func (c *Codec) UnmarshalContext(ctx context.Context, dst any) error

UnmarshalContext decodes the merged map into dst using mapstructure.

func (*Codec) WriteTo

func (c *Codec) WriteTo(w io.Writer, src any) (int64, error)

WriteTo writes dotenv-style output to w.

type Option

type Option func(*Codec)

Option configures a Codec.

func WithBytes

func WithBytes(b []byte) Option

WithBytes appends raw dotenv bytes as a source.

func WithCurrentEnvironment

func WithCurrentEnvironment() Option

WithCurrentEnvironment appends the process environment as a source (read at Map time).

func WithDecodeHook

func WithDecodeHook(h mapstructure.DecodeHookFunc) Option

WithDecodeHook appends a decode hook.

func WithFile

func WithFile(path string) Option

WithFile appends a dotenv file path as a source.

func WithHTTPClient

func WithHTTPClient(client *http.Client) Option

WithHTTPClient sets the HTTP client used by subsequent WithURL sources.

func WithHTTPHeader

func WithHTTPHeader(k, v string) Option

WithHTTPHeader adds a header for subsequent WithURL sources.

func WithKeyNormalizer

func WithKeyNormalizer(n keymap.Normalizer) Option

WithKeyNormalizer sets key normalizer after merge (nil disables).

func WithPrefix

func WithPrefix(prefix string) Option

WithPrefix strips prefix from variable names before path splitting.

func WithReader

func WithReader(r io.Reader) Option

WithReader appends dotenv content from r (read fully on each Map call).

func WithSliceMerge

func WithSliceMerge(s merge.SliceStrategy) Option

WithSliceMerge sets slice merge strategy when merging sources.

func WithTagName

func WithTagName(name string) Option

WithTagName sets the struct tag name for mapstructure.

func WithTrim

func WithTrim(enable bool) Option

WithTrim toggles struct string trim via mapstructure hook.

func WithURL

func WithURL(raw string) Option

WithURL appends an HTTP(S) URL returning dotenv content. Use WithHTTPHeader / WithHTTPClient before WithURL so they apply to this request.

func WithWeaklyTyped

func WithWeaklyTyped(enable bool) Option

WithWeaklyTyped toggles weak typing for struct decode.