babyenv

README

Babyenv

Package babyenv collects environment variables and places them in corresponding struct fields. It aims to reduce the boilerplate in reading data from the environment.

The struct should contain env tags indicating the names of corresponding environment variables. The values of those environment variables will be then collected and placed into the struct. If nothing is found, struct fields will be given their default values (for example, bools will be false).

type config struct {
    Name string `env:"NAME"`
}

Default values can also be provided in the default tag.

    type config struct {
        Name string `env:"NAME" default:"Jane"`
    }

A 'required' flag can also be set in the following format:

    type config struct {
        Name string `env:"NAME,required"`
    }

If a required flag is set the 'default' tag will be ignored.

Example

package main

import (
    "fmt"
    "os"
    "github.com/magicnumbers/babyenv"
)

type config struct {
    Debug   bool   `env:"DEBUG"`
    Port    string `env:"PORT" default:"8000"`
    Workers int    `env:"WORKERS" default:"16"`
    Name    string `env:"NAME,required"`
}

func main() {
    os.Setenv("DEBUG", "true")
    os.Setenv("WORKERS", "4")
    os.Setenv("NAME", "Jane")

    var cfg config
    if err := babyenv.Parse(&cfg); err != nil {
        log.Fatalf("could not get environment vars: %v", err)
    }

    fmt.Printf("%b\n%s\n%d\n%s", cfg.Debug, cfg.Port, cfg.Workers, cfg.Name)

    // Output:
    // true
    // 8000
    // 4
    // Jane
}

Supported Types

Currently, only the following types are supported:

• string
• bool
• int
• []byte
• *string
• *bool
• *int
• *[]byte

Pull requests are welcome, especially for new types.

Credit

This is entirely based on the caarlos0’s env package. This one simply has a slightly different interface, and less functionality.

LICENSE

MIT

Documentation

Overview

Package babyenv collects environment variables and places them in corresponding struct fields. It aims to reduce the boilerplate in reading data from the environment.

The struct should contain `env` tags indicating the names of corresponding environment variables. The values of those environment variables will be then collected and placed into the struct. If nothing is found, struct fields will be given their default values (for example, `bool`s will be `false`).

type config struct {
    Name string `env:"NAME"`
}

Default values can also be provided in the `default` tag.

`env:"NAME" default:"Jane"`

A 'required' flag can also be set in the following format:

`env:"NAME,required"`

If a required flag is set the 'default' tag will be ignored.

Only a few types are supported: string, bool, int, []byte, *string, *bool, *int, *[]byte. An error will be returned if other types are attempted to be processed.

Example:

package main

import (
    "fmt"
    "os"
    "github.com/magicnumbers/babyenv"
)

type config struct {
    Debug   bool   `env:"DEBUG"`
    Port    string `env:"PORT" default:"8000"`
    Workers int    `env:"WORKERS" default:"16"`
    Name    string `env:"NAME,required"`
}

func main() {
    os.Setenv("DEBUG", "true")
    os.Setenv("WORKERS", "4")
    os.Setenv("NAME", "Jane")

    var cfg config
    if err := babyenv.Parse(&cfg); err != nil {
        log.Fatalf("could not get environment vars: %v", err)
    }

    fmt.Printf("%b\n%s\n%d\n%s", cfg.Debug, cfg.Port, cfg.Workers, cfg.Name)

    // Output:
    // true
    // 8000
    // 4
    // Jane
}

Index

• Variables
• func Parse(cfg interface{}) error
• type ErrorEnvVarRequired
  • func (e *ErrorEnvVarRequired) Error() string
• type ErrorUnsettable
  • func (e *ErrorUnsettable) Error() string
• type ErrorUnsupportedType
  • func (e *ErrorUnsupportedType) Error() string

Variables

var (
	// ErrorNotAStructPointer indicates that we were expecting a pointer to a
	// struct but we didn't get it. This is returned when parsing a passed
	// struct.
	ErrorNotAStructPointer = errors.New("expected a pointer to a struct")
)

Functions

func Parse

func Parse(cfg interface{}) error

Parse parses a struct for environment variables, placing found values in the struct, altering it. We look at the 'env' tag for the environment variable names, and the 'default' for the default value to the corresponding environment variable.

Types

type ErrorEnvVarRequired

type ErrorEnvVarRequired struct {
	Name string
}

ErrorEnvVarRequired is used when a `required` flag is used and the value of the corresponding environment variable is empty

func (*ErrorEnvVarRequired) Error

func (e *ErrorEnvVarRequired) Error() string

Error implements the error interface

type ErrorUnsettable

type ErrorUnsettable struct {
	FieldName string
}

ErrorUnsettable is used when a field cannot be set

func (*ErrorUnsettable) Error

func (e *ErrorUnsettable) Error() string

Error implements the error interface

type ErrorUnsupportedType

type ErrorUnsupportedType struct {
	Type reflect.Type
}

ErrorUnsupportedType is used when we attempt to parse a struct field of an unsupported type

func (*ErrorUnsupportedType) Error

func (e *ErrorUnsupportedType) Error() string

Error implements the error interface