lever

README

lever

A simple interface to configuration parameters for an app, accessed through either command line, environment variables, or configuration file.

Usage

To install

go get github.com/mediocregopher/lever

To use

import "github.com/mediocregopher/lever"

See the api docs for more detailed usage and examples

Documentation

Overview

Package lever provides a simple interface to access configuration parameters, accessed through either command line, environment variables, or configuration file.

Initializing

An instance is initialized like so:

f := lever.New("myapp", nil)

// -- or - can be used, or really anything, or nothing! Check the Name field
// doc for more specific rules
f.Add(lever.Param{Name: "--foo"})
f.Add(lever.Param{Name: "--bar", Default: "something"})
f.Add(lever.Param{Name: "--foo-bar", Flag: true})
f.Parse()

"myapp" is the name of the application using lever, and nil could be a set of Opts if you want, but nil uses the default values which is probably fine.

In addition to the given Params, lever automatically adds in "--help" (to print out a help page and exit), "--example" (to print out an example config file and exit) and "--config" (to read in a config file and use values from it). Exact behaviour can be tweaked through both Param and Opt fields.

Values for the set params can be passed in through either the command line, environment variables, a config file, or all three. The order of precedence goes:

- command line (highest)

- environment variables

- config file

- default value

Using command line

For the above app, command line options could be set like (Note that both the "--key val" and "--key=val" forms are valid):

./myapp --foo foo --bar=bar --foo-bar

Using environment variables

For the above app, environment variables could be set like (Note the prepending of the app's name):

export MYAPP_FOO=foo
export MYAPP_FOO_BAR=true
./myapp

Using a config file

To see an example configuration file for your app, use the "--example" command line flag. It will print and example config file with all default values already filled in to stdout.

./myapp --example > myapp.conf
./myapp --config myapp.conf

Retrieving values

Any of the Param* methods can be used to retrieve values from within your app. For the app above you could values with something like:

foo, ok := f.ParamInt("--foo")
bar, ok := f.ParamStr("--bar")
foobar, ok := f.ParamFlag("--foo-bar")

You use these methods regardless of the source of the values (command line, environment, etc...). The names will be automatically translated from their source naming to match what was used for the Name field in the original Param.

Multi params

Multi params are those which can be specified more than once. You don't have to specify a Param in a special way, only retrieve it in a special way:

f := lever.New("myapp2", nil)
f.Add(lever.Param{Name: "--multi"})
f.Parse

// ./myapp2 --multi foo --multi bar

m, ok := f.ParamStrs("--multi")
// m == []string{"foo", "bar"}

You can set the default value for multi params as well, using the DefaultMulti field. If one source sets *any* values for the multi param all values from sources of lower priority are thrown away, for example:

export MYAPP2_MULTI=foo
./myapp2 --multi bar --multi baz
# multi == []string{"bar", "baz"}

Index

• type Lever
  • func New(appName string, o *Opts) *Lever
  • func (f *Lever) Add(p Param)
  • func (f *Lever) Example() string
  • func (f *Lever) Help() string
  • func (f *Lever) ParamFlag(name string) bool
  • func (f *Lever) ParamInt(name string) (int, bool)
  • func (f *Lever) ParamInts(name string) ([]int, bool)
  • func (f *Lever) ParamRest() []string
  • func (f *Lever) ParamStr(name string) (string, bool)
  • func (f *Lever) ParamStrs(name string) ([]string, bool)
  • func (f *Lever) Parse()
• type Opts
• type Param

Types

type Lever

type Lever struct {
	// contains filtered or unexported fields
}

Lever is an instance of the paramater parser, which can have expected parameters assigned to it and their values retrieved from it

func New

func New(appName string, o *Opts) *Lever

New instantiates a new Lever with the given appName and Opts (or nil to just use the default Opts). appName is used as the name of the application using lever, both in the example configuration file and as a prefix to environment variables

func (*Lever) Add

func (f *Lever) Add(p Param)

Add the given parameter as an expected parameter for the process

func (*Lever) Example

func (f *Lever) Example() string

Example returns a string representing exactly what would be written to stdout if --example is set

func (*Lever) Help

func (f *Lever) Help() string

Help returns a string representing exactly what would be written to stdout if --help is set

func (*Lever) ParamFlag

func (f *Lever) ParamFlag(name string) bool

ParamFlag returns the value of the param of the given name as a boolean. The param need only be set with no value to take on the opposite value of its Default. This almost always means that if the flag is set true is returned.

func (*Lever) ParamInt

func (f *Lever) ParamInt(name string) (int, bool)

ParamInt returns the value of the param of the given name as an int. True is returned if the value was set by either the user or a default value

func (*Lever) ParamInts

func (f *Lever) ParamInts(name string) ([]int, bool)

ParamInts returns all the values of the param (if it was set multiple times) of the given name as ints. True is returned if the values were set by either the user or the default values

func (*Lever) ParamRest

func (f *Lever) ParamRest() []string

ParamRest returns any command line parameters which were passed in by the user but not expected. In addition, any paramaters following a "--" parameter on the command line will automatically be appended to this list regardless of their value

func (*Lever) ParamStr

func (f *Lever) ParamStr(name string) (string, bool)

ParamStr returns the value of the param of the given name as a string. True is returned if the value is set by either the user or a default value

func (*Lever) ParamStrs

func (f *Lever) ParamStrs(name string) ([]string, bool)

ParamStrs returns all the values of the param (if it was set multiple times) of the given name as strings. True is returned if the values were set by either the user or the default values

func (*Lever) Parse

func (f *Lever) Parse()

Parse looks at all available sources of param values (command line, environment variables, configuration file) and puts together all the discovered values. Once this returns it is possible to retrieve values for specific params. If the --help or --example flags are set on the command line their associated output is dumped to stdout os.Exit(0) will be called.

type Opts

type Opts struct {

	// If set lever will look in the given file (if it exists) for
	DefaultConfigFile string

	// Extra text which will be shown above the output of Help() when --help is
	// set. A newline is not required
	HelpHeader string

	// Extra text which will be shown below the output of Help() when --help is
	// set. A newline is not required
	HelpFooter string

	// Don't allow there to be a configuration file imported. the --config and
	// --example cli options won't be present in the output of Help()
	DisallowConfigFile bool

	// If the config file is missing even though it is specified (either through
	// default value or on the command line) do not error
	AllowMissingConfigFile bool
}

Opts are options which can be used when instantiating a new instance of a Lever to change its behavior. None of them are required to be set

type Param

type Param struct {

	// Required. This the long form of the flag name. It should include any
	// delimiters which wish to be used, for example "--long-form" or
	// "-long-form". Name cannot contain :, =, or whitespace
	Name string

	// Other names for the same parameter which will be accepted on the command
	// line, generally used for short form flags. Like Name these should include
	// any delimiters which wish to be used, for example "-alias" or "-s"
	Aliases []string

	// A short description of the paramater, shown in command-line help and as a
	// comment in the default configuration file
	Description string

	// The default value this param should take, as a string. If this param is
	// going to be parsed as something else, like an int, the default string
	// should also be parsable as an int.
	//
	// If this param is a flag this can be "", "false" (equivalent), or "true"
	Default string

	// If the param is going to be used as a type which is specified multiple
	// times (for example, using ParamStrs()), this is the default value field
	// which should be used. nil means to refer to Default, empty slice means
	// the default is no entries
	DefaultMulti []string

	// If the param is a flag (boolean switch, it doesn't expect a value), this
	// must be set to true
	Flag bool

	// If set to true this parameter will not appear in the example
	// configuration file and will not be allowed to be set in it
	DisallowInConfigFile bool
}

Param is a single configuration option which is specified by the user running the application