package ff

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

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.

Source Files ¶

doc.go env_parser.go json_parser.go parse.go plain_parser.go

Directories ¶