README.md
1Configurable: The useless Go configuration package that doesn't do anything
2===========================================================================
3
4[](https://godoc.org/gopkg.in/hlandau/configurable.v1)
5
6Configurable is a Go library for managing program configuration information, no
7matter whether it comes from command line arguments, configuration files,
8environment variables, or anywhere else.
9
10The most noteworthy feature of configurable is that it doesn't do anything. It
11contains no functionality for examining or parsing command line arguments. It
12doesn't do anything with environment variables. And it certainly can't read
13configuration files.
14
15The purpose of configurable is to act as an [integration
16nexus](http://www.devever.net/~hl/nexuses), essentially a matchmaker between
17application configuration and specific configuration interfaces. This creates
18the important feature that your application's configuration can be expressed
19completely independently of *how* that configuration is loaded.
20
21Configurable doesn't implement any configuration loading logic because it
22strives to be a neutral intermediary, which abstracts the interface between
23configurable items and configurators.
24
25In order to demonstrate the configurable way of doing things, a simple flag
26parsing package is included. Use of this package is completely optional. If it
27doesn't meet your needs, you can throw it out and use your own — but still
28consume and configure all registered Configurables.
29
30Included example packages demonstrate how an application or library might
31register various configurable items, and then expose them for configuration via
32the command line, configuration files or other means.
33
34**Import as:** `gopkg.in/hlandau/configurable.v1`
35
36Configurable
37------------
38
39A Configurable is an object that represents some configurable thing. It is
40obliged only to implement the following interface:
41
42```go
43type Configurable interface{}
44```
45
46Configurable is designed around interface upgrades. If you want to actually do
47anything with a Configurable, you must attempt to cast it to an interface with
48the methods you need. A Configurable is not obliged to implement any interface
49besides Configurable, but almost always will.
50
51Here are some common interfaces implemented by Configurables, in descending
52order of importance:
53
54 - `CfSetValue(interface{}) error` — attempt to set the Configurable to a value.
55
56 - `CfName() string` — get the Configurable's name.
57
58 - `CfDefaultValue() interface{}` — get the Configurable's default value.
59
60 - `CfGetValue() interface{}` — get the Configurable's value.
61
62 - `CfChildren() []Configurable` — return the children of this Configurable, if any.
63
64 - `CfUsageSummaryLine() string` — get a one-line usage summary suitable for
65 use as command line usage information.
66
67 - `String() string` — the standard Go `String()` interface.
68
69 - `CfGetPriority() Priority` — retrieves the priority of the value, used to
70 determine whether it should be overridden.
71
72 - `CfSetPriority(priority Priority)` — sets the priority of the value.
73
74 - `CfEnvVarName() string` — if a non-empty string, an environment variable
75 that maps to this Configurable.
76
77Configurable-specific methods should always be prefixed with `Cf` so that it is clear
78that they are intended for consumption by Configurable consumers.
79
80A command line parsing adapter should typically be able to make do with a Configurable
81which implements just `CfSetValue` and `CfName`.
82
83The Standard Bindings
84---------------------
85
86For a package which makes it easy to register and consume configurables, see
87the [easyconfig](https://github.com/hlandau/easyconfig) package.
88
89Of course, nothing requires you to use the easyconfig package. You are free to
90eschew it and make your own.
91
92Background Reading
93------------------
94
95 - [On Nexuses](http://www.devever.net/~hl/nexuses)
96 - See also: [Measurable](https://github.com/hlandau/measurable)
97
98Licence
99-------
100
101 © 2015 Hugo Landau <hlandau@devever.net> MIT License
102
103
){kind=link}