README
¶
flagconf
Package flagconf combines the standard library's flag package with Andrew Gallant's excellent TOML parsing library.
This package sets program options from a TOML configuration file while allowing the settings to be overridden with command-line flags as well.
Installation
$ go get -u github.com/cespare/flagconf
Usage
Documentation is on godoc.org.
Here is a small example:
import (
"github.com/cespare/flagconf"
)
type Config struct {
MaxProcs int `desc:"maximum OS threads"`
Addr string `desc:"listen address (with port)"`
}
func main() {
// Set the defaults.
config := Config{
MaxProcs: 4,
}
flagconf.Parse("config.toml", &config)
}
Now if the TOML file looks like this:
# config.toml
maxprocs = 8
addr = "localhost:7755"
and the program is run like this:
$ ./prog -addr ":8888"
then conf will be:
MaxProcs: 8
Addr: ":8888"
(That is, TOML settings override the defaults and flags given override those.)
License
MIT
Documentation
¶
Overview ¶
Package flagconf combines the standard library's flag package with Andrew Gallant's excellent TOML parsing library: https://github.com/BurntSushi/toml.
This package sets program options from a TOML configuration file while allowing the settings to be overridden with command-line flags as well.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func IsHelp ¶
IsHelp checks whether err was caused by user requesting help output (setting -h or --help flags).
func MustParse ¶
func MustParse(path string, config interface{})
MustParse is like Parse except if parsing fails it prints the error and exits the program.
func Parse ¶
Parse reads a TOML configuration file at path as well as user-supplied options from os.Args and sets matching options in config, which must be a non-nil pointer to a struct.
Typical usage is that the user represents configuration options with a struct type and then populates a value of that type with the default configuration values.
Then the user calls flagconf.Parse, passing in the path to the configuration file and a pointer to the configuration value. This function will read settings from the TOML file and then read the user-supplied arguments from os.Args.
Example ¶
Here is a small example:
import (
"github.com/cespare/flagconf"
)
type Config struct {
MaxProcs int `desc:"maximum OS threads"`
Addr string `desc:"listen address (with port)"`
}
func main() {
// Set the defaults
config := Config{
MaxProcs: 4,
}
flagconf.Parse("config.toml", &config)
}
Now if the TOML file looks like this:
# config.toml
maxprocs = 8
addr = "localhost:7755"
and the user runs the program with
./prog -addr ":8888"
then conf will be:
MaxProcs: 8 Addr: ":8888"
(That is, TOML settings override the defaults and flags given override those.)
Descriptions for the flags are taken from the "desc" struct tag. A default description is created based on the field type if a tag is not provided.
TOML matches are attempted for every exported field in the configuration struct. Flag names are constructed for every exported field. Unexported fields, as well as exported fields tagged with `flag:"-"`, are ignored by flagconf. (If a field is ignored by using this tag, it is typically best to also use `toml:"-"` so that the field is not picked up by the TOML parser.)
Parse returns an error if no file can be found at path.
Types ¶
The basic types flagconf supports are those which are directly supported by both package flag and TOML:
bool string int int64 uint uint64 float64
Flagconf also supports any type implementing flag.Value, as long as TOML also supports it.
Finally, flagconf supports nesting by recursively inspecting structs and creating them as necessary when the config value contains a nil struct pointer. In TOML, a struct corresponds to a nested section; in flags the name will be dot-separated:
type Conf {
S *struct {
N int
}
}
// corresponds to this TOML
[s]
n = 3
// and this flag
-s.n=3
Embedded structs are handled like in encoding/json: their exported fields are treated as if they were fields of the outer struct.
Naming ¶
Matching names from TOML values to struct field names is much like encoding/json: exact matches are preferred and then case-insensitive matching will be accepted. (TOML names are typically lowercase, but the struct fields must be exported.) The struct tag "toml" can be used to set a different name.
The flag names are constructed by lowercasing the struct field name. The "flag" struct tag controls the flag name.
type Conf struct {
Foo string `toml:"bar" flag:"baz"`
}
func ParseStrings ¶
ParseStrings reads a TOML configuration file at path as well as command-line arguments in args and sets matching options in config, which must be a non-nil pointer to a struct.
ParseStrings is similar to Parse except that it provides the caller with more fine-grained control.
The argument array is passed into ParseStrings the args parameter; note that this is treated like os.Args in that args[0] is interpreted as the executable name and args[1:] are flags.
The allowNoConfig parameter controls whether ParseStrings returns an error if no file is found at path.
Types ¶
type Ints ¶
type Ints []int
Ints is a convenience wrapper around an int slice that implements flag.Value and handles the value as comma-separated list.
For example flag -cpu=1,2,4 will result in a slice {1, 2, 4}.
Source Files