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

Expand ▾ Collapse ▴

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

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

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

                              Source Files