settings

README

settings

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

Contents

1. Installation
2. Description
3. Limitations

1. Installation

Use go get to install the package:

go get github.com/kaatinga/settings

Then, import the package into your own code:

import "github.com/kaatinga/settings"

2. Description

How to use

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

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 := Load(&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	-
~int	-
~uint	-
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
if err := Load(&settings); err != nil {
    return err
}

Nonetheless, if you want, you can do it.

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

3. Limitations

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

Empty structs are not allowed

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

Load() accepts only pointer to your configuration model

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

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

Otherwise, the function returns error.

Documentation

Overview

Package settings allows to load application setting from environment variables with validation. Full description is in the README.md

Index

• Constants
• func Load(settings interface{}) error
• 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"
	ErrNotAddressableField    cer.Error = "the value is not addressable or main struct is not indicated 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"
)

Functions

func Load

func Load(settings interface{}) error

Load loads settings to a struct.

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.