README
¶
Setting
setting is a simple package for the management and loading of settings. Beware setting is still in development and there WILL be breaking changes.
Installation
Installation is the same as with any other go library
go get github.com/iZettle/setting
Getting Started
The quickest way to get started is to use the FillerBuilder.
This helper allows you to attach n Fillers and iterate through them to load the
relevant Settings.
For example the below Load function looks for relevant Settings first within the environment (using OSLoad) and then in a settings file.
func LoadSettings(settingFile string) setting.Filler {
return setting.NewFillerBuilder().
WithEnvProvider().
WithFileProvider(settingFile).
Build()
}
Setting, Provider, and Filler
There are three main components of setting, Setting, Provider, and Filler.
Together these three main components make the setting package.
Setting
A setting is an interface type, a Setting is the core representation of a setting value.
type Setting interface {
Bool() (bool, error)
Int64() (int64, error)
UInt64() (uint64, error)
fmt.Stringer
}
A Setting MUST be at-least representable as a string, and MAY return
errors upon an attempt to be represented as another type, if conversion to that
type is not applicable.
setting implements the Setting interface for you on a string type, it's called
Value, it's unlikely that you'll need anything more than that, we recommend
that you return Value from your Provider implementation.
Provider
A Provider is an interface type, it takes a list of keys and provides a
Setting for each in a map[string]Setting
type Provider interface {
Load(keys ...string) (map[string]Setting, Error)
}
A provider is an interface to be implemented to give you a Setting from a
source. setting implements Provider in a few ways.
AggregateProvideraProvider, that takes many instances ofProvider, and will return Settings from the firstProviderinstance that it finds in.CachedProvideraProviderwill cacheSettinginstances retrieved from its fallbackProviderfor as long as the lifetime of theCachedProvider, or the TTL of theSettingprovided by its fallbackProviderif it has one.Fileis an implementation of aProviderthat will createValueinstances from a supplied text file.
Filler
ProviderFiler implements the Filler interface, and is an object that takes a
Provider, and will fill correctly tagged structs with the values loaded from the
supplied provider.
Tagged structs can be filled like so:
type Config struct{
Username string `setting:"CONFIG_USERNAME"`
Server string `setting:"CONFIG_SERVER"`
Port int `setting:"CONFIG_PORT"`
Production bool `setting:"CONFIG_PRODUCTION"`
}
func Load(){
cfg := Config{}
filler := setting.ProviderFiller{
Provider: &setting.File{
Filename:"settings.txt",
},
}
if err := filler.Fill(&cfg); err != nil{
panic(err)
}
}
MapFill is no longer supported as it's need has been removed by go 1.8s ability
to convert two equivalent structs between each other.
OSLoad
OSLoad loads settings from environmental variables, and implements the Provider
interface through ProviderFunc
p := ProviderFunc(OSLoad)
s, err := p.Load("foo")
File
File loads settings from a file on disk
file := setting.File{FileName: *settingsFileName}
s, err := file.Load("foo")
The loaded file should contain a single setting definition per line.
Each setting should be defined in the form setting_name=value
// This is a comment with a SETTING=foobar in it, it is ignored.
MY_FOO_SETTING=42
MY_BAR_SETTING=setting string
not a setting
Error
Error is a wrapper for generic errors.
Erroradds extra context to generic errors by allowing the user to return a list of keys that weren't successfully retrieved when used in one of the loader/provider callsErroralso contains aFatalErrorproperty that can be used to interpret if the error that has been thrown is "fatal" and thus requires a separate course of action than a generic error.
type Error interface {
error
MissingKeys() []string
FatalError() error
}
License
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AggregateProvider ¶
type AggregateProvider []Provider
AggregateProvider allows multiple settings providers to be combined so as settings can be loaded from multiple sources.
func NewAggregateProviderWithDefault ¶
func NewAggregateProviderWithDefault(provider Provider, structReceived interface{}) AggregateProvider
NewAggregateProviderWithDefault sets up a defaultProvider and makes sure this is added first into the aggregate provider method
type CachedProvider ¶
type CachedProvider struct {
Fallback Provider
Lifetime int64
// contains filtered or unexported fields
}
CachedProvider takes a settings provider, and a lifetime, CachedProvider will hold a setting for as long as its lifetime, or the lifetime of the ExpirableSetting passed to it from its fallback, if an ExpirableSetting is passed. Already expired ExpirableSettings, will be passed to the caller, but will not be cached.
func (*CachedProvider) Clear ¶
func (cp *CachedProvider) Clear()
Clear will completely empty the cache of CachedSettingsProvider
func (*CachedProvider) Load ¶
func (cp *CachedProvider) Load(keys ...string) (map[string]Setting, Error)
Load implements the settings provider interface, and will prefer to return settings from it's in memory cache, and then its fallback provider. If expired settings are provided, they will be returned to the caller, but they will not be saved.
If you wish for Settings not to be cached, simply implement ExpirableSetting interface so as that TTL always returns 0 and Expired() always returns false.
type CachedValue ¶
CachedValue is a setting that implements ExpirableSetting interface, so that CachedProvider may determine whether a setting has expired from the cache and should be reloaded from the fallback
func (CachedValue) Expired ¶
func (cv CachedValue) Expired() bool
Expired is whether the setting in question has expired in the cache
func (CachedValue) TTL ¶
func (cv CachedValue) TTL() time.Duration
TTL is the number of seconds from the expiry of the setting
type DefaultProvider ¶
type DefaultProvider struct {
// contains filtered or unexported fields
}
DefaultProvider struct where target is the struct that will be extracted within the default load function
func NewDefaultProvider ¶
func NewDefaultProvider(target interface{}) *DefaultProvider
NewDefaultProvider setups the DefaultProvider struct for use with default load the passed target interface should be a pointer to a struct
type Error ¶
Error is a generic error wrapper that can be used to list missing keys if errors occur. If a fatal error has been added to the type this should signify a type of error where execution should cease.
type ExpirableSetting ¶
ExpirableSetting combines the Setting and Expirable interface to be checked in Cached settings provider.
type File ¶
type File struct {
FileName string
// contains filtered or unexported fields
}
File implements the setting.Provider interface
type Filler ¶
type Filler interface {
Fill(interface{}) error
}
Filler fills a struct from the tags on the struct itself
type FillerBuilder ¶
type FillerBuilder struct {
Providers AggregateProvider
}
FillerBuilder is used to compose commonly used Providers together
func NewFillerBuilder ¶
func NewFillerBuilder() FillerBuilder
NewFillerBuilder is the default constructor for a FillerBuilder
func (FillerBuilder) WithEnvProvider ¶
func (fb FillerBuilder) WithEnvProvider() FillerBuilder
WithEnvProvider adds the OSLoad Provider to the Providers Slice
func (FillerBuilder) WithFileProvider ¶
func (fb FillerBuilder) WithFileProvider(settingsFile string) FillerBuilder
WithFileProvider loads the specified file using the file provider and adds it to the Providers Slice
func (FillerBuilder) WithProvider ¶
func (fb FillerBuilder) WithProvider(provider ProviderFunc) FillerBuilder
WithProvider add the specified provider to the Providers Slice
type Provider ¶
Provider is a simple interface, that can your types should accept if you want access to raw settings, or that you should implement if you want your structs to be auto-filled from a source of your choice
type ProviderError ¶
type ProviderError struct {
// contains filtered or unexported fields
}
ProviderError defines the struct to handle for a fatal error.
func NewFatalProviderError ¶
func NewFatalProviderError(err error, keys ...string) *ProviderError
NewFatalProviderError returns a fatal error and a list of keys that were supplied to the service that threw the fatal error.
func NewProviderError ¶
func NewProviderError(keys ...string) *ProviderError
NewProviderError returns a list of keys that could not be found or aren't set in the searched location.
func (*ProviderError) AppendMissingKeys ¶
func (pe *ProviderError) AppendMissingKeys(keys ...string) *ProviderError
AppendMissingKeys either adds a key to a pre-existing slice of keys or instantiates a new slice of keys
func (*ProviderError) Error ¶
func (pe *ProviderError) Error() string
Error returns the fatal with a joined list of missing keys.
func (*ProviderError) FatalError ¶
func (pe *ProviderError) FatalError() error
FatalError returns the error object that was thrown.
func (*ProviderError) MissingKeys ¶
func (pe *ProviderError) MissingKeys() []string
MissingKeys returns a list of keys that could not be found in the searched location.
type ProviderFiller ¶
ProviderFiller fills a tagged struct with the settings from the settingProvider
func NewProviderFiller ¶
func NewProviderFiller(provider Provider) *ProviderFiller
NewProviderFiller constructs an instance of ProviderFiller, with no custom tag.
func (*ProviderFiller) Fill ¶
func (pf *ProviderFiller) Fill(configPtr interface{}) error
Fill fills a struct's fields that are tagged with `setting:"SETTING_KEY"` with the value provided from the Provider, the setting must be able to be represented as the type of the field.
type ProviderFunc ¶
ProviderFunc allows functions that accept and return the same as as a Provider to implement the Provider interface
type Setting ¶
type Setting interface {
Bool() (bool, error)
Int64() (int64, error)
UInt64() (uint64, error)
fmt.Stringer
}
Setting is the core interface type of setting, it represents a setting value a Setting MUST at least be representable as a string, and as such implements the fmt.Stringer interface. A setting MAY return an error upon attempt to be used as a non applicable type.
type StringMapProvider ¶
StringMapProvider implements the setting.Provider interface to provide compatibility with other packages such as viper
type Value ¶
type Value string
Value a string type to store the raw setting, implements Setting.
Source Files