ff

README

ff

ff stands for flags-first, and provides an opinionated way to populate a flag.FlagSet with configuration data from the environment. By default, it parses only from the command line, but you can enable parsing from environment variables (lower priority) and/or a configuration file (lowest priority).

Building a commandline application in the style of kubectl or docker? Consider package ffcli, a natural companion to, and extension of, package ff.

Usage

Define a flag.FlagSet in your func main.

import (
	"flag"
	"os"
	"time"

	"github.com/peterbourgon/ff/v3"
)

func main() {
	fs := flag.NewFlagSet("my-program", flag.ContinueOnError)
	var (
		listenAddr = fs.String("listen-addr", "localhost:8080", "listen address")
		refresh    = fs.Duration("refresh", 15*time.Second, "refresh interval")
		debug      = fs.Bool("debug", false, "log debug information")
		_          = fs.String("config", "", "config file (optional)")
	)

Then, call ff.Parse instead of fs.Parse. Options are available to control parse behavior.

	err := ff.Parse(fs, os.Args[1:],
		ff.WithEnvVarPrefix("MY_PROGRAM"),
		ff.WithConfigFileFlag("config"),
		ff.WithConfigFileParser(ff.PlainParser),
	)

This example will parse flags from the commandline args, just like regular package flag, with the highest priority. (The flag's default value will be used only if the flag remains unset after parsing all provided sources of configuration.)

Additionally, the example will look in the environment for variables with a MY_PROGRAM prefix. Flag names are capitalized, and separator characters are converted to underscores. In this case, for example, MY_PROGRAM_LISTEN_ADDR would match to listen-addr.

Finally, if a -config file is specified, the example will try to parse it using the PlainParser, which expects files in this format.

listen-addr localhost:8080
refresh 30s
debug true

You could also use the JSONParser, which expects a JSON object.

{
	"listen-addr": "localhost:8080",
	"refresh": "30s",
	"debug": true
}

Or, you could write your own config file parser.

// ConfigFileParser interprets the config file represented by the reader
// and calls the set function for each parsed flag pair.
type ConfigFileParser func(r io.Reader, set func(name, value string) error) error

Flags and env vars

One common use case is to allow configuration from both flags and env vars.

package main

import (
	"flag"
	"fmt"
	"os"

	"github.com/peterbourgon/ff/v3"
)

func main() {
	fs := flag.NewFlagSet("myservice", flag.ContinueOnError)
	var (
		port  = fs.Int("port", 8080, "listen port for server (also via PORT)")
		debug = fs.Bool("debug", false, "log debug information (also via DEBUG)")
	)
	if err := ff.Parse(fs, os.Args[1:], ff.WithEnvVars()); err != nil {
		fmt.Fprintf(os.Stderr, "error: %v\n", err)
		os.Exit(1)
	}

	fmt.Printf("port %d, debug %v\n", *port, *debug)
}

$ env PORT=9090 myservice
port 9090, debug false
$ env PORT=9090 DEBUG=1 myservice -port=1234
port 1234, debug true

Error handling

In general, you should call flag.NewFlagSet with the flag.ContinueOnError error handling strategy, which, somewhat confusingly, is the only way that ff.Parse can return errors. (The other strategies terminate the program on error. Rude!) This is the only way to detect certain types of parse failures, in addition to being good practice in general.

Documentation

Overview

Package ff is a flags-first helper package for configuring programs.

Runtime configuration must always be specified as commandline flags, so that the configuration surface area of a program is self-describing. Package ff provides an easy way to populate those flags from environment variables and config files.

See the README at https://github.com/peterbourgon/ff for more information.

Index

• Variables
• func EnvParser(r io.Reader, set func(name, value string) error) error
• func JSONParser(r io.Reader, set func(name, value string) error) error
• func Parse(fs *flag.FlagSet, args []string, options ...Option) error
• func PlainParser(r io.Reader, set func(name, value string) error) error
• type ConfigFileParser
• type Context
• type JSONParseConfig
  • func (pc *JSONParseConfig) Parse(r io.Reader, set func(name, value string) error) error
• type JSONParseError
  • func (e JSONParseError) Error() string
  • func (e JSONParseError) Unwrap() error
• type Option
  • func WithAllowMissingConfigFile(allow bool) Option
  • func WithConfigFile(filename string) Option
  • func WithConfigFileFlag(flagname string) Option
  • func WithConfigFileParser(p ConfigFileParser) Option
  • func WithConfigFileVia(filename *string) Option
  • func WithEnvVarPrefix(prefix string) Option
  • func WithEnvVarSplit(delimiter string) Option
  • func WithEnvVars() Option
  • func WithFilesystem(fs embed.FS) Option
  • func WithIgnoreUndefined(ignore bool) Option
• type StringConversionError
  • func (e StringConversionError) Error() string

Variables

var WithEnvVarNoPrefix = WithEnvVars

WithEnvVarNoPrefix is an alias for WithEnvVars.

DEPRECATED: prefer WithEnvVars.

Functions

func EnvParser

func EnvParser(r io.Reader, set func(name, value string) error) error

EnvParser is a parser for .env files. Each line is tokenized on the first `=` character. The first token is interpreted as the flag name, and the second token is interpreted as the value. Both tokens are trimmed of leading and trailing whitespace. If the value is "double quoted", control characters like `\n` are expanded. Lines beginning with `#` are interpreted as comments.

EnvParser respects WithEnvVarPrefix, e.g. an .env file containing `A_B=c` will set a flag named "b" if Parse is called with WithEnvVarPrefix("A").

func JSONParser

func JSONParser(r io.Reader, set func(name, value string) error) error

JSONParser is a helper function that uses a default JSONParseConfig.

func Parse

func Parse(fs *flag.FlagSet, args []string, options ...Option) error

Parse the flags in the flag set from the provided (presumably commandline) args. Additional options may be provided to have Parse also read from a config file, and/or environment variables, in that priority order.

func PlainParser

func PlainParser(r io.Reader, set func(name, value string) error) error

PlainParser is a parser for config files in an extremely simple format. Each line is tokenized as a single key/value pair. The first whitespace-delimited token in the line is interpreted as the flag name, and all remaining tokens are interpreted as the value. Any leading hyphens on the flag name are ignored.

Types

type ConfigFileParser

type ConfigFileParser func(r io.Reader, set func(name, value string) error) error

ConfigFileParser interprets the config file represented by the reader and calls the set function for each parsed flag pair.

type Context

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

Context contains private fields used during parsing.

type JSONParseConfig

type JSONParseConfig struct {
	// Delimiter is used when concatenating nested node keys into a flag name.
	// The default delimiter is ".".
	Delimiter string
}

JSONParseConfig collects parameters for the JSON config file parser.

func (*JSONParseConfig) Parse

func (pc *JSONParseConfig) Parse(r io.Reader, set func(name, value string) error) error

Parse a JSON document from the provided io.Reader, using the provided set function to set flag values. Flag names are derived from the node names and their key/value pairs.

type JSONParseError

type JSONParseError struct {
	Inner error
}

JSONParseError wraps all errors originating from the JSONParser.

func (JSONParseError) Error

func (e JSONParseError) Error() string

Error implenents the error interface.

func (JSONParseError) Unwrap

func (e JSONParseError) Unwrap() error

Unwrap implements the errors.Wrapper interface, allowing errors.Is and errors.As to work with JSONParseErrors.

type Option

type Option func(*Context)

Option controls some aspect of Parse behavior.

func WithAllowMissingConfigFile

func WithAllowMissingConfigFile(allow bool) Option

WithAllowMissingConfigFile tells Parse to permit the case where a config file is specified but doesn't exist.

By default, missing config files cause Parse to fail.

func WithConfigFile

func WithConfigFile(filename string) Option

WithConfigFile tells Parse to read the provided filename as a config file. Requires WithConfigFileParser, and overrides WithConfigFileFlag. Because config files should generally be user-specifiable, this option should rarely be used; prefer WithConfigFileFlag.

func WithConfigFileFlag

func WithConfigFileFlag(flagname string) Option

WithConfigFileFlag tells Parse to treat the flag with the given name as a config file. Requires WithConfigFileParser, and is overridden by WithConfigFile.

To specify a default config file, provide it as the default value of the corresponding flag. See also: WithAllowMissingConfigFile.

func WithConfigFileParser

func WithConfigFileParser(p ConfigFileParser) Option

WithConfigFileParser tells Parse how to interpret the config file provided via WithConfigFile or WithConfigFileFlag.

func WithConfigFileVia

func WithConfigFileVia(filename *string) Option

WithConfigFileVia tells Parse to read the provided filename as a config file. Requires WithConfigFileParser, and overrides WithConfigFileFlag. This is useful for sharing a single root level flag for config files among multiple ffcli subcommands.

func WithEnvVarPrefix

func WithEnvVarPrefix(prefix string) Option

WithEnvVarPrefix is like WithEnvVars, but only considers environment variables beginning with the given prefix followed by an underscore. That prefix (and underscore) are removed before matching to flag names. This option is also respected by the EnvParser config file parser.

By default, flags are not set from environment variables at all.

func WithEnvVarSplit

func WithEnvVarSplit(delimiter string) Option

WithEnvVarSplit tells Parse to split environment variables on the given delimiter, and to make a call to Set on the corresponding flag with each split token.

func WithEnvVars

func WithEnvVars() Option

WithEnvVars tells Parse to set flags from environment variables. Flag names are matched to environment variables by capitalizing the flag name, and replacing separator characters like periods or hyphens with underscores.

By default, flags are not set from environment variables at all.

func WithFilesystem

func WithFilesystem(fs embed.FS) Option

WithFilesystem tells Parse to use the provided filesystem when accessing files on disk, for example when reading a config file. By default, the host filesystem is used, via os.Open.

func WithIgnoreUndefined

func WithIgnoreUndefined(ignore bool) Option

WithIgnoreUndefined tells Parse to ignore undefined flags that it encounters in config files. By default, if Parse encounters an undefined flag in a config file, it will return an error. Note that this setting does not apply to undefined flags passed as arguments.

type StringConversionError

type StringConversionError struct {
	Value interface{}
}

StringConversionError was returned by config file parsers in certain cases.

DEPRECATED: this error is no longer returned by anything.

func (StringConversionError) Error

func (e StringConversionError) Error() string

Error implements the error interface.