lflag

README

lflag

lflag is a replacement for the stdlib's flag package. It handles --help and delaying code execution across multiple packages/functions until flags are evaluated.

Documentation

Overview

Package lflag handles defining configuration providers as well as coordinating initialization code.

Configuration

Parameters are defined much like they are in the standard flag package. A pointer is returned from a method like String, which will then be filled once lflag.Parse is called. All parameters must be defined before lflag.Parse is called.

addr := lflag.String("db-addr", ":666", "Address the database is listening on")
poolSize := lflag.Int("db-pool-size", 10, "Number of connections to the database to make")
lflag.Parse(lflag.NewSourceCLI())
db, err := NewDB(*addr, *poolSize)

Sources

lflag supports multiple Sources, which are places from which configuration information is obtained. For example, NewSourceCLI returns a Source which will read configuration from command-line parameters, NewSourceEnv read configuration from environment parameters, and so on. Sources can be combined together using the Sources type, which handles merging the different Sources into a single one.

Initialization

In addition to handling configuration parameters lflag also manages initialization based on their values, via the Do function. When lflag.Parse is called, after all parameters have been filled in, all functions passed into Do are called, in the order in which they were passed in.

Miscellaneous

lflag handles a couple of other behaviors which are related to initialization and runtime.

Build information can be compiled into binaries using lflag using the build variables like BuildCommit. See their doc string for how exactly to do that.

Index

• Constants
• Variables
• func Bool(name string, value bool, usage string) *bool
• func Configure()
• func Custom(paramType, name string, value interface{}, usage string) interface{}
• func CustomParamType(name string, examplePtr interface{}, p ParseFunc, jp JSONStringFunc)
• func Do(fn func())
• func Duration(name string, value time.Duration, usage string) *time.Duration
• func Int(name string, value int, usage string) *int
• func JSON(rcv interface{}, name string, value interface{}, usage string)
• func JSONStringAsIs(j json.RawMessage) (string, error)
• func JSONStringUnmarshal(j json.RawMessage) (string, error)
• func Parse(s Source)
• func Prefixed(strs ...string) string
• func RequiredBool(name, usage string) *bool
• func RequiredCustom(paramType, name, usage string) interface{}
• func RequiredDuration(name, usage string) *time.Duration
• func RequiredInt(name, usage string) *int
• func RequiredJSON(rcv interface{}, name string, usage string)
• func RequiredString(name, usage string) *string
• func Reset()
• func String(name, value, usage string) *string
• func Version() string
• type JSONStringFunc
• type Param
• type ParseFunc
• type Source
  • func NewSourceCLI() Source
  • func NewSourceEnv() Source
  • func NewSourceJSON(inner Source) Source
• type SourceStub
  • func (ss SourceStub) Parse([]Param) (map[string]string, error)
• type Sources
  • func (ss Sources) Parse(pp []Param) (map[string]string, error)

Constants

const (
	ParamTypeString   = "string"
	ParamTypeInt      = "int"
	ParamTypeInt64    = "int64"
	ParamTypeBool     = "bool"
	ParamTypeDuration = "duration"
	ParamTypeJSON     = "json"
)

All the built-int ParamTypes

Variables

var (
	BuildCommit    string
	BuildDate      string
	BuildNumber    string // TeamCity (or other build system) build number
	BuildGoVersion string
)

Build variables which can be set during the go build command. E.g.: -ldflags "-X 'gerrit.levenlabs.com/llib/lflag.BuildCommit commitHash'" These fields will be used to construct the string printed out when the --version flag is used.

var HelpPrefix string

HelpPrefix may be set as a prefix to be printed out by sources which can print out help strings (e.g. NewSourceCLI). If the string doesn't end in a newline one will be added

Functions

func Bool

func Bool(name string, value bool, usage string) *bool

Bool takes in the name of a config param, a default value, and a string describing the usage for the param, and returns a pointer which will be filled when Parse is called

func Configure

func Configure()

Configure is a shortcut around Parse which uses our default sources (in order of least-to-most precedent: json-file, environment, cli).

Additionally, lflag.NotifyReadyAfter is called and closed after Parse is called letting any service manager know that we are now ready.

func Custom

func Custom(paramType, name string, value interface{}, usage string) interface{}

Custom takes in a paramType, the name of a config param, a default value, a string describing the usage for the param, and returns a pointer which will be filled when Parse is called.

The value must be the underlying type that your custom Parser expects as a pointer and we'll use fmt.Sprint() to convert it to a string.

You can use type-assertion on the return value to get the pointer type that you expect. For instance, if your custom ParamType is for time.Time, this would return a *time.Time.

func CustomParamType

func CustomParamType(name string, examplePtr interface{}, p ParseFunc, jp JSONStringFunc)

CustomParamType defines a new ParamType that can be used by calling Custom or RequiredCustom. The examplePtr should be an example value that your ParseFunc expects. For instance, if you expect *time.Time then you'd send a new(time.Time) as the examplePtr.

func Do

func Do(fn func())

Do registers the given function to be performed after Parse is called an all param pointers have been filled in. Multiple functions may be registered using Do, though the order they are called is guaranteed to be in calling order. Once Parse has been called and ALL queued Do functions have returned, sent function is immediately invoked. If Do is called within another Do, then the sent function is added to the queue at the end and will be envoked once all queued up Do's are called.

func Duration

func Duration(name string, value time.Duration, usage string) *time.Duration

Duration takes in the name of a config param, a default value, a string describing the usage for the param, and returns a pointer which will be filled when Parse is called.

The value given by a config for a Duration must be parsable by time.ParseDuration.

func Int

func Int(name string, value int, usage string) *int

Int takes in the name of a config param, a default value, and a string describing the usage for the param, and returns a pointer which will be filled when Parse is called

func JSON

func JSON(rcv interface{}, name string, value interface{}, usage string)

JSON reads in the config param as a string and json.Unmarshals it into the given receiver pointer. value is a default value for the parameter, and usage describes the parameter.

If value cannot be json.Marshaled (for help string purposes) this will panic

func JSONStringAsIs

func JSONStringAsIs(j json.RawMessage) (string, error)

JSONStringAsIs is a JSONStringFunc that just casts the json.RawMessage as a string. It's used for non-quoted values in JSON like numbers and booleans.

func JSONStringUnmarshal

func JSONStringUnmarshal(j json.RawMessage) (string, error)

JSONStringUnmarshal is a JSONStringFunc that unmarshal's the json.RawMessage into a string. It's used for string values in JSON.

func Parse

func Parse(s Source)

Parse goes through each Source and compiles a set of values for registered params (later Sources overwrite previous ones), fills in param pointers, then calls all functions registered using Do.

At the end of Parse all of the lflag package's params are reset. Any calls to Do will immediately invoke the sent function after Parse is called.

func Prefixed

func Prefixed(strs ...string) string

Prefixed is basically strings.Join except it ignores empty strings

func RequiredBool

func RequiredBool(name, usage string) *bool

RequiredBool is like Bool, but it has no default value and must be set

func RequiredCustom

func RequiredCustom(paramType, name, usage string) interface{}

RequiredCustom is like Custom, but it has no default and must be set

func RequiredDuration

func RequiredDuration(name, usage string) *time.Duration

RequiredDuration is like Duration, but it has no default value and must be set

func RequiredInt

func RequiredInt(name, usage string) *int

RequiredInt is like Int, but it has no default value and must e set

func RequiredJSON

func RequiredJSON(rcv interface{}, name string, usage string)

RequiredJSON is like JSON, but it has no default and must be set

func RequiredString

func RequiredString(name, usage string) *string

RequiredString is like String, but it has no default value and must e set

func Reset

func Reset()

Reset removes any configured flags and resets everything back to before Parse was called. This should ONLY be used in tests

func String

func String(name, value, usage string) *string

String takes in the name of a config param, a default value, and a string describing the usage for the param, and returns a pointer which will be filled when Parse is called

func Version

func Version() string

Version compiles the build strings into a string which will be printed out when --version or -V is used, but is exposed so it may be used other places too.

Types

type JSONStringFunc

type JSONStringFunc func(json.RawMessage) (string, error)

JSONStringFunc takes a JSON value and converts it into an appropriate string that will be eventually sent to ParseFunc. JSONStringAsIs and JSONStringUnmarshal are both JSONStringFunc's.

type Param

type Param struct {
	//  is the
	ParamType string

	// Name is the name of the parameter, e.g. "listen-addr" or "img-file".
	Name string

	// Default is the default value of the param, 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 ParamTypeBool this will be "true" or "false"
	Default string

	// Usage is a short description of the paramater's usage
	Usage string

	// Required should be true if the parameter must be provided by the caller
	Required bool
}

Param describes everything a Source needs to know about a single configuration option which has been defined

type ParseFunc

type ParseFunc func(string, interface{}) error

ParseFunc is a function that takes a string from the Source and converts it into a value necessary to store in the sent pointer.

type Source

type Source interface {

	// Parse returns all the configured keys/values. The passed in slice should
	// not be modified.
	//
	// NOTE the only valid true value for a ParamTypeBool is "true". All other
	// values will be considered false
	Parse([]Param) (map[string]string, error)
}

Source describes an entity which actually provides the values for configuration, e.g. command line or environment variables.

func NewSourceCLI

func NewSourceCLI() Source

NewSourceCLI initializes and returns a new Source which will pull from the command line arguments at runtime. It also handles --help and --version options

func NewSourceEnv

func NewSourceEnv() Source

NewSourceEnv initializes and returns a new Source which will pull from the environment variables at runtime. All param names are completely uppercased and have '-' replaced with '_', e.g "listen-addr" becomes "LISTEN_ADDR"

func NewSourceJSON

func NewSourceJSON(inner Source) Source

NewSourceJSON wraps an existing Source and adds support for reading a json file to source parameter values. The values coming from the inner Source will overwrite any which are found in the json file

type SourceStub

type SourceStub map[string]string

SourceStub can be used for testing with configuration options

func (SourceStub) Parse

func (ss SourceStub) Parse([]Param) (map[string]string, error)

Parse implements the Source interface by returning the SourceStub as-is

type Sources

type Sources []Source

Sources encompasses multiple Source instances. When Parse is called the returned map from each will be combined together, with right-most Source values taking precedence over their lefthand neighbor

func (Sources) Parse

func (ss Sources) Parse(pp []Param) (map[string]string, error)

Parse implements the Source interface. See Sources' doc