env_loader

README

env_loader

The package looks up necessary environment variables and use them to specify settings for your application. In addition, the package validates the final struct using standard validate tags.

Contents

1. Installation
2. Example
3. Limitations

1. Installation

Use go get.

go get github.com/kaatinga/env_loader

Then import the validator package into your own code.

import "github.com/kaatinga/env_loader"

2. Description

How to use

Create a settings model where you can use tags env, default and validate. Announce a variable and call LoadUsingReflect():

type Settings struct {
    Port       string `env:"PORT" validate:"numeric"`
    Database   string `env:"DATABASE"`
    CacheSize  byte `env:"CACHE_SIZE" default:"50"`
    LaunchMode string `env:"LAUNCH_MODE"`
}

var settings Settings
err := LoadUsingReflect(&settings)
if err != nil {
    return err
}

The env tag must contain the name of the related environment variable. The default tag contains a default value that is used in case the environment variable was not found. The validate tag may contain an optional validation rule fallowing the documentation of the validator package.

Supported types

Type	Real type
string	-
boolean	-
any uint	-
int, int64	-
logrus.Level	uint32
syslog.Priority	int
time.Duration	int64

Nested structs

Nested structs can be added via pointer or without pointer. Example:

type Model2 struct {
    CacheSize   byte `env:"CACHE_SIZE"`
}

type Model3 struct {
    Port        string `env:"PORT validate:"numeric"`
}

type Model1 struct {
    Database    string `env:"DATABASE"`
    Model2      *Model2
    Model3      Model3
}

The nested structs that added via pointer must not be necessarily initialized:

var settings Model1
err := LoadUsingReflect(&settings)
if err != nil {
    return err
}

Nonetheless, if you want, you can do it.

var settings = Model1{Model2: new(Model2)}
err := LoadUsingReflect(&settings)
if err != nil {
    return err
}

3. Limitations

The configuration model has some limitations in the way how it is arranged and used.

Empty structs are not allowed

If you add an empty struct to your configuration model, LoadUsingReflect() returns error.

LoadUsingReflect() accepts only pointer to your configuration model

The root model must be initialized and added to the LoadUsingReflect() signature via pointer:

err := LoadUsingReflect(&EnvironmentSettings)
if err != nil {
    return err
}

Otherwise, the function returns error.

Documentation

Index

• Constants
• func LoadSettings(settings interface{}) error
• func ParseSyslogPriority(lvl string) (syslog.Priority, error)
• func PriorityDescription(priority syslog.Priority) string
• type Engine
• type Loop

Constants

const (
	ErrUnsupportedField       cer.Error = "unsupported field type"
	ErrTheModelHasEmptyStruct cer.Error = "an input struct has no fields"
	ErrNotAStruct             cer.Error = "the configuration must be a struct"
	ErrNotAddressable         cer.Error = "the main struct must be pointed out via pointer"

	ErrInternalFailure     cer.Error = "an internal package error"
	ErrIncorrectFieldValue cer.Error = "variable has been found but has incorrect value"
	ErrValidationFailed    cer.Error = "field validation failed"
	ErrIncorrectPriority   cer.Error = "incorrect syslog priority"
)

Functions

func LoadSettings

func LoadSettings(settings interface{}) error

LoadSettings loads settings to a struct.

func ParseSyslogPriority

func ParseSyslogPriority(lvl string) (syslog.Priority, error)

ParseSyslogPriority converts string to syslog.Priority.

func PriorityDescription

func PriorityDescription(priority syslog.Priority) string

PriorityDescription returns description for syslog.Priority.

Types

type Engine

type Engine struct {
	Value          reflect.Value
	Type           reflect.Type
	NumberOfFields int
	Validate       *validator.Validate
	Field          Loop
}

Engine — data model to process settings.

type Loop

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

Loop — variables that used during field processing.