config

README

config is a flexible application configuration package. It is modeled on the go library net/http package. config was inspired by https://github.com/inconshreveable/log15.

For more information please run 'make docs'. This package will eventually be made available on godoc.org.

Documentation

Overview

Package config is a flexible tool kit that simplifies application configuration. It is modeled after the standard library's io and net/http packages, and inspired by the inconshreveables' log15 package. It allows you to easily set up logging the way you want for your application. It provides implementations of other standard configuration methods, such as the approach espoused for 12 factor apps (http://12factor.net/config), or the multi-level configuration scheme in viper (https://github.com/spf13/viper).

Like the standard library net/http package, config relies heavily on standard interfaces, in particular the Handler and Loader interfaces. These interfaces act like lego blocks allowing you to combine them in customized ways.

Getting Started

To get started you will need to import the library:

import "github.com/materials-commons/config"

You can now start to use the config package. The easiest way is to use the standard config object. Unless you need to create multiple configuration entries, its easiest to just use the standard, this is a package global that you can access, for example config.Get(...).

Before you start using config you need to tell it how it will find its configuration information. For example, lets say all your configuration information is kept in environment variables. You can do:

import (

"github.com/materials-commons/config"
"github.com/materials-commons/config/handler"

func main() {
    config.Init(handler.Env())
}

Index

• Variables
• func Get(key string, args ...interface{}) (interface{}, error)
• func GetBool(key string, args ...interface{}) bool
• func GetBoolErr(key string, args ...interface{}) (bool, error)
• func GetInt(key string, args ...interface{}) int
• func GetIntErr(key string, args ...interface{}) (int, error)
• func GetLastError() error
• func GetString(key string, args ...interface{}) string
• func GetStringErr(key string, args ...interface{}) (string, error)
• func GetTime(key string, args ...interface{}) time.Time
• func GetTimeErr(key string, args ...interface{}) (time.Time, error)
• func Init(handler cfg.Handler) error
• func Set(key string, value interface{}, args ...interface{}) error
• func SetErrorHandler(f cfg.ErrorFunc)
• type Configer
  • func New(handler cfg.Handler) Configer
• type Event
  • func ToEvent(str string) Event
  • func (e Event) String() string
• type LoggerFunc

Variables

var TwelveFactor = handler.Env()

Store configuration in environment as specified for 12 Factor Applications: http://12factor.net/config. The handler is thread safe and can safely be used across multiple go routines.

var TwelveFactorWithOverride = handler.Multi(handler.Sync(handler.Map()), handler.Env())

Store configuration in environment, but allow overrides, either by the application setting them internally as defaults, or setting them from the command line. See http://12factor.net/config. Overrides are an extension to the specification. This handler is thread safe and can safely be used across multiple go routines.

Functions

func Get

func Get(key string, args ...interface{}) (interface{}, error)

Get gets a key from the standard Configer.

func GetBool

func GetBool(key string, args ...interface{}) bool

GetBool gets an integer key. It returns the default value of false if there is an error. GetLastError can be called to see the error. if a function is set with SetErrorHandler then the function will be called when an error occurs.

func GetBoolErr

func GetBoolErr(key string, args ...interface{}) (bool, error)

GetBoolErr gets an bool key from the standard Configer.

func GetInt

func GetInt(key string, args ...interface{}) int

GetInt gets an integer key. It returns the default value of 0 if there is an error. GetLastError can be called to see the error. If a function is set with SetErrorHandler then the function will be called when an error occurs.

func GetIntErr

func GetIntErr(key string, args ...interface{}) (int, error)

GetIntErr gets an integer key from the standard Configer.

func GetLastError

func GetLastError() error

GetLastError returns any error that occured when GetInt, GetString, GetBool, or GetTime are called. It will return nil if there was no error.

func GetString

func GetString(key string, args ...interface{}) string

GetString gets an integer key. It returns the default value of "" if there is an error. GetLastError can be called to see the error. If a function is set with SetErrorHandler then the function will be called when an error occurs.

func GetStringErr

func GetStringErr(key string, args ...interface{}) (string, error)

GetStringErr gets an string key from the standard Configer.

func GetTime

func GetTime(key string, args ...interface{}) time.Time

GetTime gets an integer key. It returns the default value of an empty time.Time if there is an error. GetLastError can be called to see the error. If a function is set with SetErrorHandler then the function will be called when an error occurs.

func GetTimeErr

func GetTimeErr(key string, args ...interface{}) (time.Time, error)

GetTimeErr gets an time key from the standard Configer.

func Init

func Init(handler cfg.Handler) error

Init initializes the standard Configer using the specified handler. The standard configer is a global config that can be conveniently accessed from the config package.

func Set

func Set(key string, value interface{}, args ...interface{}) error

Set sets key to value in the standard Configer.

func SetErrorHandler

func SetErrorHandler(f cfg.ErrorFunc)

SetErrorHandler sets a function to call when GetInt, GetString, GetBool, or GetTime return an error. You can use this function to handle error in an application specific way. For example if an error is fatal you can have this function call os.Exit() or panic. Alternatively you can easily log errors with this.

Types

type Configer

type Configer interface {
	cfg.Initer
	cfg.Getter
	cfg.TypeGetterErr
	cfg.TypeGetterDefault
	cfg.Setter
	SetHandler(handler cfg.Handler)
	SetHandlerInit(handler cfg.Handler) error
	SetLogger(l LoggerFunc)
}

A Configer is a configuration object that can store and retrieve key/value pairs.

func New

func New(handler cfg.Handler) Configer

New creates a new Configer instance that uses the specified Handler for key/value retrieval and storage.

type Event

type Event int

Event is a configuration event.

const (
	// GET Get key event
	GET Event = iota

	// SET Set key event
	SET

	// TOINT Convert to int event
	TOINT

	// TOSTRING Convert to string event
	TOSTRING

	// TOBOOL Convert to bool event
	TOBOOL

	// TOTIME Convert to time event
	TOTIME

	// SWAP Swap handler event
	SWAP

	// INIT Initialize handler event
	INIT

	// UNKNOWN Unknown event
	UNKNOWN
)

func ToEvent

func ToEvent(str string) Event

ToEvent maps a string to an event. The match on string is not case sensitive.

func (Event) String

func (e Event) String() string

String turns an event into a string.

type LoggerFunc

type LoggerFunc func(event Event, err error, args ...interface{})

LoggerFunc is the function to call to log config events.