goconfigure

README

Configuration Package for Go

goconfigure allows configuration of an application via flags, environment variables, or a configuration file.

Installation

go get github.com/domdavis/goconfigure

Usage

The following comes from example/cli.go which can be used to see how the various methods of setting options works:

package main

import (
	"fmt"
	"github.com/domdavis/goconfigure"
)

func main() {
	var opt goconfigure.Option
	var options struct {
		config string
		message string
		count int
	}

	opts := goconfigure.NewOptions()

	opt = goconfigure.NewOption(&options.message, "The message to display")
	opt.ShortFlag('m')
	opt.ConfigKey("message")
	opt.Default("This space intentionally left blank")
	opts.Add(opt)

	opt = goconfigure.NewOption(&options.count,
		"The number of times to display the message")
	opt.LongFlag("count")
	opt.ConfigKey("count")
	opt.EnvVar("GOCONFIGURE_COUNT")
	opt.Default(1)
	opts.Add(opt)

	opt = goconfigure.NewOption(&options.config,
		"The path to the configuration file")
	opt.ShortFlag('o')
	opts.Add(opt)

	if err := opts.ParseUsing(opt); err != nil {
		opts.Usage()
	}

	for i := 0; i < options.count; i++ {
		fmt.Println(options.message)
	}
}

By default this produces the output:

$ go run ./cli.go 
This space intentionally left blank

Using an options file gives:

$ go run ./cli.go -o ./options.json
Hello, world!
Hello, world!
Hello, world!

And this can be overridden, with command line arguments always taking precedence:

$ GOCONFIGURE_COUNT=2 go run cli.go -o ./options.json 
Hello, world!
Hello, world!

$ GOCONFIGURE_COUNT=2 go run cli.go -o ./options.json --count 3
Hello, world!
Hello, world!
Hello, world!

Documentation

Index

• type Option
  • func NewOption(i interface{}, description string) Option
• type Options
  • func NewOptions() Options
  • func NewOptionsWithArgs(args []string) Options

Examples

• NewOptions
• NewOptionsWithArgs

Types

type Option

type Option interface {

	// Flags defines both a short and long flag for setting the option from the
	// command line. For example:
	//
	//     option.Flags('f', "flag")
	//
	// allows the flags:
	//
	//     myApp -f value
	//     myApp --flag value
	//
	// An Option can only have one short and long flag definition so any
	// previously defined values will be overwritten. This function does nothing
	// if Parse has already been called.
	Flags(short rune, longFlag string)

	// ShortFlag defines a short flag for setting the option from the command
	// line. For example:
	//
	//     option.ShortFlag('f')
	//
	// allows the flag:
	//
	//     myApp -f value
	//
	// An Option can only have one short flag defined so any previously defined
	// value will be overwritten. This function does nothing if Parse has
	// already been called.
	ShortFlag(name rune)

	// LongFlag defines a long flag for setting the option from the command
	// line. For example:
	//
	//     option.LongFlag("flag")
	//
	// allows the flag:
	//
	//     myApp --flag value
	//
	// An Option can only have one long flag defined so any previously defined
	// value will be overwritten. This function does nothing if Parse has
	// already been called.
	LongFlag(name string)

	// EnvVar defines the name of an environment variable that can be used to
	// set this option. The string value of the environment variable must be
	// convertible to the type of the option.
	EnvVar(name string)

	// ConfigKey defines the key this option can use to set itself from a JSON
	// configuration file. The value stored under this key must be convertible
	// to the Option Type.
	ConfigKey(name string)

	// Default defines a value that will be used by the option if no flags,
	// environment variables, or configuration file values are set or found. The
	// value must be the same type as the Option.
	Default(value interface{})

	// Value returns the encapsulated value held by this Option. Value should
	// not be called until Parse has been called. In general Value only needs to
	// be called by a parent Options type.
	Value() value.Data

	// RegisterFlags causes the flags defined on this option to be registered
	// with the provided FlagSet. In general RegisterFlags only needs to be
	// called by a parent Options type.
	RegisterFlags(flags *flag.FlagSet) error

	// Parse this option with the provided config. In general Parse only needs
	// to be called by a parent Options type.
	Parse(config map[string]interface{}) error

	// Output the option as a human readable and formatted string.
	String() string
}

Option represents a configuration option that can be set either by flag, configuration file, environment variable, or a default value with the value to use being chosen in that order. Options must be one of bool, int, int64, uint, unit64, float64, string, or time.Duration.

func NewOption

func NewOption(i interface{}, description string) Option

NewOption returns an option with i being a pointer to a variable of the type of this option (*bool, *int, *int64, *uint, *uint64, *float64, *string, *time.Duration). The description is used when producing usage information. Providing an invalid type for i will not error here, but will generate an error when the Option is parsed.

type Options

type Options interface {
	// Add an option to this set of Options.
	Add(option Option)

	// Parse the Options using the provided map for configuration options.
	Parse(config map[string]interface{}) error

	// ParseUsing uses the given Option to locate and load the configuration
	// from a file.
	ParseUsing(option Option) error

	// NArg is the number of arguments remaining after flags have been
	// processed. Calling NArg before Parse will simply return 0.
	NArg() int

	// Args returns the non-flag command-line arguments. Calling Args before
	// calling Parse will simply return an empty slice.
	Args() []string

	// Usage displays the usage information for this set of options to STDERR.
	Usage()

	// UsageString building of custom usage output by providing just the usage
	// details for the defined options.
	UsageString() string
}

Options holds a set of configuration options which can be provided by the command line, environment variables, configuration files, or default values.

func NewOptions

func NewOptions() Options

NewOptions returns a new Options type that takes its flags from the arguments provided to the process.

Example

package main

import (
	"fmt"
	"github.com/domdavis/goconfigure"
)

func main() {
	var r string
	opts := goconfigure.NewOptions()

	// We need to replace opts so arguments sent be testing harnesses are not
	// included. Ordinarily this line can be omitted.
	opts = goconfigure.NewOptionsWithArgs(nil)

	opt := goconfigure.NewOption(&r, "option")
	opt.LongFlag("config")
	opts.Add(opt)
	err := opts.ParseUsing(opt)

	fmt.Println(err)
}

Output:
<nil>

func NewOptionsWithArgs

func NewOptionsWithArgs(args []string) Options

NewOptionsWithArgs returns a new Options type that uses the given slice of strings as its argument set.

Example

package main

import (
	"fmt"
	"github.com/domdavis/goconfigure"
)

func main() {
	var options struct {
		test string
	}

	opts := goconfigure.NewOptionsWithArgs([]string{"-flag", "test"})
	opt := goconfigure.NewOption(&options.test, "test option")
	opt.ShortFlag('f')
	opt.LongFlag("flag")
	opts.Add(opt)
	err := opts.ParseUsing(nil)

	if err == nil {
		fmt.Println(options)
	} else {
		fmt.Println(err)
	}

}

Output:
{test}