envs

README

envs

a mapper of ENVironment variables to Structure for Go.

This library maps the environment variables to the struct according to the fields' types and tags.
Currently, it supports the following field types: string, int64, float64, bool, and the pointer for them.

Synopsis

Basic usage:

import (
	"fmt"
	"os"

	"github.com/moznion/envs"
)

type StructuredEnv struct {
	Foo     string  `envs:"FOO"`
	Bar     int64   `envs:"BAR"`
	Buz     float64 `envs:"BUZ"`
	Qux     bool    `envs:"QUX"`
	FooBar  string  `envs:"FOOBAR,allowempty"`
	Nothing string
}

func main() {
	_ = os.Setenv("FOO", "string-value")
	_ = os.Setenv("BAR", "65535")
	_ = os.Setenv("BUZ", "123.456")
	_ = os.Setenv("QUX", "true")

	var e StructuredEnv
	err := envs.Unmarshal(&e)
	if err != nil {
		panic(err)
	}
	fmt.Printf("structured envvar:\n")
	fmt.Printf("    Foo     => \"%s\"\n", e.Foo)
	fmt.Printf("    Bar     => %d\n", e.Bar)
	fmt.Printf("    Buz     => %f\n", e.Buz)
	fmt.Printf("    Qux     => %v\n", e.Qux)
	fmt.Printf("    FooBar  => \"%s\"\n", e.FooBar)
	fmt.Printf("    Nothing => \"%s\"\n", e.Nothing)

	// Output:
	// structured envvar:
	//     Foo     => "string-value"
	//     Bar     => 65535
	//     Buz     => 123.456000
	//     Qux     => true
	//     FooBar  => ""
	//     Nothing => ""
}

Pointer based usage:

import (
	"fmt"
	"os"

	"github.com/moznion/envs"
)

type PtrStructuredEnv struct {
	Foo     *string  `envs:"FOO"`
	Bar     *int64   `envs:"BAR"`
	Buz     *float64 `envs:"BUZ"`
	Qux     *bool    `envs:"QUX"`
	FooBar  *string  `envs:"FOOBAR,allowempty"`
	Nothing *string
}

func main() {
	_ = os.Setenv("FOO", "string-value")
	_ = os.Setenv("BAR", "65535")
	_ = os.Setenv("BUZ", "123.456")
	_ = os.Setenv("QUX", "true")

	var pe PtrStructuredEnv
	err = envs.Unmarshal(&pe)
	if err != nil {
		panic(err)
	}
	fmt.Printf("pointer based structured envvar:\n")
	fmt.Printf("    Foo     => \"%s\"\n", *pe.Foo)
	fmt.Printf("    Bar     => %d\n", *pe.Bar)
	fmt.Printf("    Buz     => %f\n", *pe.Buz)
	fmt.Printf("    Qux     => %v\n", *pe.Qux)
	fmt.Printf("    FooBar  => %v\n", pe.FooBar)
	fmt.Printf("    Nothing => %v\n", pe.Nothing)

	// Output:
	// pointer based structured envvar:
	//     Foo     => "string-value"
	//     Bar     => 65535
	//     Buz     => 123.456000
	//     Qux     => true
	//     FooBar  => <nil>
	//     Nothing => <nil>
}

and examples are here

Documentations

Author

moznion (moznion@mail.moznion.net)

Documentation

Index

• Variables
• func Unmarshal(vessel interface{}) error

Examples

• Unmarshal

Variables

var (
	ErrNonPointerVesselType            = errors.New("non-pointer vessel type is not allowed")
	ErrNilVessel                       = errors.New("nil vessel is not allowed")
	ErrEnvironmentVariableNameIsEmpty  = errors.New("given tag value for environment variable's name is empty")
	ErrEmptyEnvironmentVariable        = errors.New("environment variable is empty; if it would like to allow the empty value, please consider using `allowempty` option")
	ErrEnvironmentVariableParseInt64   = errors.New("failed to parse an environment variable to int64")
	ErrEnvironmentVariableParseFloat64 = errors.New("failed to parse an environment variable to float64")
	ErrUnsupportedFieldName            = errors.New("unsupported field type; supported types are string, int64, float64, bool, and the pointer for them")
)

Functions

func Unmarshal

func Unmarshal(vessel interface{}) error

Unmarshal maps the environment variables to the given structure following the definition. A parameter of this function must be non-nil pointer type.

For example, if the following structure has given to this function,

type StructuredEnv struct {
		Foo string `envs:"FOO"`
}

The environment variable of `FOO` is mapped into `StructuredEnv#Foo` field according to the field type. Currently, it supports the following field types: string, int64, float64, bool, and the pointer for them.

A tag of `envs` is a specifier which environment variable to map to the field. As default, if the environment variable is empty it raises an error but if `allowempty` is put in a tag (e.g. `envs:"FOO,allowempty"`), it accepts empty (i.e. default) value.

Example

_ = os.Setenv("FOO", "string-value")
_ = os.Setenv("BAR", "65535")
_ = os.Setenv("BUZ", "123.456")
_ = os.Setenv("QUX", "true")

type StructuredEnv struct {
	Foo     string  `envs:"FOO"`
	Bar     int64   `envs:"BAR"`
	Buz     float64 `envs:"BUZ"`
	Qux     bool    `envs:"QUX"`
	FooBar  string  `envs:"FOOBAR,allowempty"`
	Nothing string
}

var e StructuredEnv
err := Unmarshal(&e)
if err != nil {
	panic(err)
}
fmt.Printf("structured envvar:\n")
fmt.Printf("    Foo     => \"%s\"\n", e.Foo)
fmt.Printf("    Bar     => %d\n", e.Bar)
fmt.Printf("    Buz     => %f\n", e.Buz)
fmt.Printf("    Qux     => %v\n", e.Qux)
fmt.Printf("    FooBar  => \"%s\"\n", e.FooBar)
fmt.Printf("    Nothing => \"%s\"\n", e.Nothing)

type PtrStructuredEnv struct {
	Foo     *string  `envs:"FOO"`
	Bar     *int64   `envs:"BAR"`
	Buz     *float64 `envs:"BUZ"`
	Qux     *bool    `envs:"QUX"`
	FooBar  *string  `envs:"FOOBAR,allowempty"`
	Nothing *string
}
var pe PtrStructuredEnv
err = Unmarshal(&pe)
if err != nil {
	panic(err)
}
fmt.Printf("pointer based structured envvar:\n")
fmt.Printf("    Foo     => \"%s\"\n", *pe.Foo)
fmt.Printf("    Bar     => %d\n", *pe.Bar)
fmt.Printf("    Buz     => %f\n", *pe.Buz)
fmt.Printf("    Qux     => %v\n", *pe.Qux)
fmt.Printf("    FooBar  => %v\n", pe.FooBar)
fmt.Printf("    Nothing => %v\n", pe.Nothing)

Output:
structured envvar:
    Foo     => "string-value"
    Bar     => 65535
    Buz     => 123.456000
    Qux     => true
    FooBar  => ""
    Nothing => ""
pointer based structured envvar:
    Foo     => "string-value"
    Bar     => 65535
    Buz     => 123.456000
    Qux     => true
    FooBar  => <nil>
    Nothing => <nil>