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. Before you start using config you need to tell it how it how to find configuration information. For example, if your configuration information is kept in environment variables you would setup the config as follows:
import ( "github.com/materials-commons/config" "github.com/materials-commons/config/handler" ) func main() { config.Init(handler.Env()) }
This will setup config to look for configuration entries by accessing environment variables.
While you can setup your own config variable, for most projects you can use the standard configuration. The standard configuration is accessible as package global methods. When you load config, it will initialize a standard configuration for you. It's default configuration is the TwelveFactor handler. You can easily change the default handler. Lets take a look at how using this:
import ( "github.com/materials-commons/config" "github.com/materials-commons/config/handler" ) func main() { config.Init(config.TwelveFactorWithOverride) port := config.GetInt("MYAPP_PORT") }
Handlers ¶
The Handler interface allows you to define new handlers for your specific use case. A Handler defines how config sets and gets configuration keys. Config comes with a large array of Handlers. Some Handlers allow you to combine handlers together. This is useful if you have a series of fallbacks to look for configuration keys.
For example, by default you might want your app to look for its configuration in environment variables. If they can't be found there, you want it to look in a YAML file. You could set this up by using the Multi Handler, and passing it the Env Handler, and the YAML Handler. For good measure you want access to be safe across multiple go routines. Here is what that looks like:
import ( "io/ioutil" "bytes" "github.com/materials-commons/config" "github.com/materials-commons/config/handler" "github.com/materials-commons/config/loader" ) func main() { b, _ := ioutil.ReadFile("/etc/myapp/app.yaml") l := loader.YAML(bytes.NewReader(b)) myAppHandler := handler.Sync(handler.Multi(handler.Env(), handler.Loader(l))) config.Init(myAppHandler) port := config.GetInt("MYAPP_PORT") }
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
- type Event
- type LoggerFunc
Constants ¶
This section is empty.
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 GetBool ¶
GetBool gets an boolean 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 ¶
GetBoolErr gets an bool key from the standard Configer.
func GetInt ¶
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 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 ¶
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 ¶
GetStringErr gets an string key from the standard Configer.
func GetTime ¶
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 ¶
GetTimeErr gets an time key from the standard Configer.
func Init ¶
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 SetErrorHandler ¶
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.
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 )
type LoggerFunc ¶
LoggerFunc is the function to call to log config events.