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/go-pa/ff for more information.
Index ¶
- 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 JSONParseError
- 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 WithEnvVarNoPrefix() Option
- func WithEnvVarPrefix(prefix string) Option
- func WithEnvVarSplit(delimiter string) Option
- func WithIgnoreUndefined(ignore bool) Option
- type StringConversionError
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func JSONParser ¶
JSONParser is a parser for config files in JSON format. Input should be an object. The object's keys are treated as flag names, and the object's values as flag values. If the value is an array, the flag will be set multiple times.
func Parse ¶
Parse the flags in the flag set from the provided (presumably commandline) args. Additional options may be provided to parse from a config file and/or environment variables in that priority order.
func PlainParser ¶
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 ¶
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 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 ¶
WithAllowMissingConfigFile tells Parse to permit the case where a config file is specified but doesn't exist. By default, missing config files result in an error.
func WithConfigFile ¶
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 be rarely used. Prefer WithConfigFileFlag.
func WithConfigFileFlag ¶
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 -- and consider also using the WithAllowMissingConfigFile option.
func WithConfigFileParser ¶
func WithConfigFileParser(p ConfigFileParser) Option
WithConfigFileParser tells Parse how to interpret the config file provided via WithConfigFile or WithConfigFileFlag.
func WithConfigFileVia ¶
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 WithEnvVarNoPrefix ¶
func WithEnvVarNoPrefix() Option
WithEnvVarNoPrefix tells Parse to try to set flags from environment variables without any specific prefix. 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 WithEnvVarPrefix ¶
WithEnvVarPrefix tells Parse to try to set flags from environment variables with the given prefix. Flag names are matched to environment variables with the given prefix, followed by an underscore, followed by the capitalized flag names, with separator characters like periods or hyphens replaced with underscores. By default, flags are not set from environment variables at all.
func WithEnvVarSplit ¶
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 WithIgnoreUndefined ¶
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 is returned when a value in a config file can't be converted to a string, to be provided to a flag.
func (StringConversionError) Error ¶
func (e StringConversionError) Error() string
Error implements the error interface.
Directories ¶
Path | Synopsis |
---|---|
Package ffcli is for building declarative commandline applications.
|
Package ffcli is for building declarative commandline applications. |
Package fftest provides unit test helpers.
|
Package fftest provides unit test helpers. |
Package fftoml provides a TOML config file paser.
|
Package fftoml provides a TOML config file paser. |
Package ffyaml provides a YAML config file parser.
|
Package ffyaml provides a YAML config file parser. |