cfg

README

See https://godoc.org/github.com/apokalyptik/cfg

Documentation

Overview

Package cfgflag is an easy way to provide configuration file and environmental defaults to the flag package from the standard library.

The reason for the creation of this package was to make a simple, easy, and standard library based way to configure applications and libs. There exist many very very good configuration libraries out there for Go, but the ones that I have found are very heavy and usually geared towards a very specific kind of use case. They rely a lot on reflection, and configuring entire structs at once.

This is meant to be a drop in replacement for the most common use cases of the flag package (indeed it uses the flag package to do most of the work) where you would like to be able to confugure an application via files or environment variables. An example of why one might want to do this is when you're using flags during development but in production you do not wish to have sensitive data like api keys and passwords listed in the process list.

Since it also presents you with a namespace. It's very easy to adopt in libraries where specific configuration would be useful. An example of which might be a library which requires an API key but that might be shared between many processed or commands, but it is undesireable to configure the library manually each time you wish to use it. In this case dropping a json or yaml configuration into your home dir, or users environment would configure the library for all processes and commands at once.

c := cfgflag.New("test")
myvar := c.Int("myint", 100, "my integer flag")
cfgflag.Parse

Given the preceeding code you can expect, in order from lowest priority to highest:

Standard library flag defaults for -test-myint (prefix + flag)

  -test-myint int
		my integer flag (default 100)

At this point *myvar would be 100 if no further configuration is found or specified.

Environment variable based defaults via

TEST_MYINT=98

You'll notice that it's {prefix}_{flag} all uppercased. At this point *myvar would be 98 if no further configuration is found or specified.

JSON config file support for

{ "myint": 97 }

You'll notice that there is no prefix inside the file since the filename counts as the variables namespace. JSON is read from exactly one the following files in order from lowest priority to highest:

/etc/test.json unless we find
~/.test.json unless we find
~/test.json unless we find
./.test.json unless we find
./test.json

At this point *myvar would be 97 if no further configuration is found or specified.

YAML config file support for

---
myint: 96

You'll notice that there is no prefix inside the file since the filename counts as the variables namespace. YAML is read from exactly one the following files in order from lowest priority to highest:

/etc/test.yml unless we find
~/.test.yml unless we find
~/test.yml unless we find
./.test.yml unless we find
./test.yml

At this point *myvar would be 96 if no further configuration is found or specified.

Command line speficied flags take precedence over YAML, JSON, ENV, and flag defaults

-test-myint=95

At this point *myvar would be 95.

Index

• Variables
• func Parse()
• type Options
  • func New(prefix string) *Options
  • func (o *Options) Bool(name string, value bool, usage string) *bool
  • func (o *Options) BoolVar(p *bool, name string, value bool, usage string)
  • func (o *Options) Duration(name string, value time.Duration, usage string) *time.Duration
  • func (o *Options) DurationVar(p *time.Duration, name string, value time.Duration, usage string)
  • func (o *Options) Float64(name string, value float64, usage string) *float64
  • func (o *Options) Float64Var(p *float64, name string, value float64, usage string)
  • func (o *Options) Int(name string, value int, usage string) *int
  • func (o *Options) Int64(name string, value int64, usage string) *int64
  • func (o *Options) Int64Var(p *int64, name string, value int64, usage string)
  • func (o *Options) IntVar(p *int, name string, value int, usage string)
  • func (o *Options) String(name string, value string, usage string) *string
  • func (o *Options) StringVar(p *string, name string, value string, usage string)
  • func (o *Options) Uint(name string, value uint, usage string) *uint
  • func (o *Options) Uint64(name string, value uint64, usage string) *uint64
  • func (o *Options) Uint64Var(p *uint64, name string, value uint64, usage string)
  • func (o *Options) UintVar(p *uint, name string, value uint, usage string)

Variables

var (
	// Debug tells us whether to log debugging messages
	Debug = false
	// DoYAML tells us whether to look for YAML configuration files
	DoYAML = true
	// DoJSON tells us whether to look for JSON configuration files
	DoJSON = true
)

Functions

func Parse

func Parse()

Parse is a convenience wrapper for flag.Parse

Types

type Options

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

Options is your entry point for the necessary functions for configuring your application. There is some initialization required. Please use New() to obtain your very own *Options

func New

func New(prefix string) *Options

New returns a new *Options initialized with environment, json, and yaml default configuration data for use in accepting command line arguments exactly mirroring a useful subset of the flag API for compatibility.

func (*Options) Bool

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

Bool works mostly like the flag package equivalent except that it will pull in defaults from the environment, and configuratin files

func (*Options) BoolVar

func (o *Options) BoolVar(p *bool, name string, value bool, usage string)

BoolVar works mostly like the flag package equivalent except that it will pull in defaults from the environment, and configuratin files

func (*Options) Duration

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

Duration works mostly like the flag package equivalent except that it will pull in defaults from the environment, and configuratin files

func (*Options) DurationVar

func (o *Options) DurationVar(p *time.Duration, name string, value time.Duration, usage string)

DurationVar works mostly like the flag package equivalent except that it will pull in defaults from the environment, and configuratin files

func (*Options) Float64

func (o *Options) Float64(name string, value float64, usage string) *float64

Float64 works mostly like the flag package equivalent except that it will pull in defaults from the environment, and configuratin files

func (*Options) Float64Var

func (o *Options) Float64Var(p *float64, name string, value float64, usage string)

Float64Var works mostly like the flag package equivalent except that it will pull in defaults from the environment, and configuratin files

func (*Options) Int

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

Int works mostly like the flag package equivalent except that it will pull in defaults from the environment, and configuratin files

func (*Options) Int64

func (o *Options) Int64(name string, value int64, usage string) *int64

Int64 works mostly like the flag package equivalent except that it will pull in defaults from the environment, and configuratin files

func (*Options) Int64Var

func (o *Options) Int64Var(p *int64, name string, value int64, usage string)

Int64Var works mostly like the flag package equivalent except that it will pull in defaults from the environment, and configuratin files

func (*Options) IntVar

func (o *Options) IntVar(p *int, name string, value int, usage string)

IntVar works mostly like the flag package equivalent except that it will pull in defaults from the environment, and configuratin files

func (*Options) String

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

String works mostly like the flag package equivalent except that it will pull in defaults from the environment, and configuratin files

func (*Options) StringVar

func (o *Options) StringVar(p *string, name string, value string, usage string)

StringVar works mostly like the flag package equivalent except that it will pull in defaults from the environment, and configuratin files

func (*Options) Uint

func (o *Options) Uint(name string, value uint, usage string) *uint

Uint works mostly like the flag package equivalent except that it will pull in defaults from the environment, and configuratin files

func (*Options) Uint64

func (o *Options) Uint64(name string, value uint64, usage string) *uint64

Uint64 works mostly like the flag package equivalent except that it will pull in defaults from the environment, and configuratin files

func (*Options) Uint64Var

func (o *Options) Uint64Var(p *uint64, name string, value uint64, usage string)

Uint64Var works mostly like the flag package equivalent except that it will pull in defaults from the environment, and configuratin files

func (*Options) UintVar

func (o *Options) UintVar(p *uint, name string, value uint, usage string)

UintVar works mostly like the flag package equivalent except that it will pull in defaults from the environment, and configuratin files