README
¶
Settings and configurations for golang application
- Easy to learn and easy to use settings for golang libraries and applications.
- Settings object is represented as
map[string]interface{}object. - Settings can be marshalled to JSON or un-marshalled from JSON.
- Possible to add more formats for marshalling and un-marshalling settings.
- All methods exported on settings object are immutable, except
Mixin. - Stable APIs, existing APIs are not going to change.
Settings as Key value pairs
Golang map is the chosen structure for passing around settings, holding them within components and interpret them when ever needed. To create new settings object:
setts := make(Settings)
Subsequently setts can be populated with {key,value} pairs, where each
{key,value} pair correspond to a single configuration parameter. To make
most out of Settings it is better to avoid nested values, as in:
// not recommended
setts["llrb"] = Settings{
"maxkeylen": 1024,
"maxvallen": 1024,
}
Instead compose settings as:
// recommended
setts := make(Settings)
setts["llrb.maxkeylen"] = 1024
setts["llrb.maxvallen"] = 1024
Although the former style is quite natural to manage a tree of settings at
component and sub-component level, it can quickly become complex when
we start passing settings object around the application. While the later
style encourages flat map of {key,value} pairs, we can still preserve the
topology of settings by using the dot-separated namespaces. There are three
APIs available to filter out component level settings and merge it with
container namespace, Section, Trim, and AddPrefix:
setts := make(Settings)
setts["numvbuckets"] = 8
setts["memalloc"] = 1000000
setts["llrb.maxkeylen"] = 1024
setts["llrb.maxvallen"] = 1024
llrbsetts := setts.Section("llrb.") // Section
setts.Section API will filter out setting keys that are prefixed by llrb.,
it will look-like:
llrbsetts <==> Settings{"llrb.maxkeylen": 1024, "llrb.maxvallen": 1024}
While passing llrbsettings to the llrb component, it may not expect the
llrb. prefixed to its settings key-name. To trim them away:
llrbsettings := setts.Section("llrb.").Trim("llrb.") // Trim away "llrb."
Now, llrbsettings will just be:
llrbsetts <==> Settings{"maxkeylen": 1024, "maxvallen": 1024}
In case, the llrb component is going to provide default set of configuration parameters, and we want to merge them with our application-level settings object, then, use AddPrefix:
appsetts := llrbsetts.AddPrefix("llrb.")
appsetts will look like:
appsetts <==> Settings{"llrb.maxkeylen": 1024, "llrb.maxvallen": 1024}
Settings from json
Most often, settings are obtained from JSON text. One of the reason for
using map[string]interface{} as the underlying data-structure is to keep
it friendly for JSON. To initialize Settings from JSON:
var setts Settings
json.Unmarshal(data, &setts)
Can't get simpler than that !
Accessors
With map[string]interface{}, settings value are resolved only during run
time. There are several helper functions that type check and extract the
settings value.
- Bool(key string), return the boolean value for key.
- Float64(key string), return the float64 value for key.
- Int64(key string) return the int64 value for key.
- Uint64(key string) return the uint64 value for key.
- String(key string) return the string value for key.
- Strings(key string) shall parse value as comma separated string items.
NOTE: To encode large numbers that can fit within int64 and uint64,
settings value can be encoded as decimal strings
Eg: {"epoch": "1125899906842624"}.
Panic and Recovery
Settings API don't return error, instead it creates panic. This is because settings are mostly part of bootstrapping process and are expected to be clean and suggested by developers. If panics become un-avoidable please use panic/recover. We are listing some of the cases when panic can happened.
- When accessing a settings key which is not present in the map.
- When using one of the typed accessors, if underlying value does not match the accessor type.
How to contribute
- Pick an issue, or create an new issue. Provide adequate documentation for the issue.
- Assign the issue or get it assigned.
- Work on the code, once finished, raise a pull request.
- Gosettings is written in golang, hence expected to follow the global guidelines for writing go programs.
- As of now, branch
masteris the development branch.
Documentation
¶
Index ¶
- type Settings
- func (setts Settings) AddPrefix(prefix string) Settings
- func (setts Settings) Bool(key string) bool
- func (setts Settings) Filter(subs string) Settings
- func (setts Settings) Float64(key string) float64
- func (setts Settings) Int64(key string) int64
- func (setts Settings) Mixin(settings ...interface{}) Settings
- func (setts Settings) PPrint() string
- func (setts Settings) Section(prefix string) Settings
- func (setts Settings) String(key string) string
- func (setts Settings) Strings(key string) []string
- func (setts Settings) Trim(prefix string) Settings
- func (setts Settings) Uint64(key string) uint64
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Settings ¶
type Settings map[string]interface{}
Settings {key,value} map of configuration parameters.
func (Settings) Mixin ¶
Mixin settings to override `setts` with a list of `settings`. Typical usage:
Make(Settings).Mixin(setts1, setts2, setts3)
Mixin mutates the receiving map, and applies settings from left to right.
func (Settings) Section ¶
Section will create a new settings object with parameters starting with `prefix`.
Source Files
Directories