ff configuration library

An ff.FlagSet can have a parent flag set using the .SetParent(parentfs) method. This allows a "child" flag set to inherit and parse all flags defined in the parent set, in addition to its own. This is useful for defining global flags (like --log or --config) that should be available to all subcommands.

parentfs := ff.NewFlagSet("parentcommand")
var (
	loglevel = parentfs.StringEnum('l', "log", "log level: debug, info, error", "info", "debug", "error")
	_        = parentfs.StringLong("config", "", "config file (optional)")
)

childfs := ff.NewFlagSet("childcommand").SetParent(parentfs)
var (
	compress  = childfs.Bool('c', "compress", "enable compression")
	transform = childfs.Bool('t', "transform", "enable transformation")
	refresh   = childfs.DurationLong('r', "refresh", 15*time.Second, "refresh interval")
)

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

For a more feature-rich experience, use ff.NewFlagSet. It is inspired by getopts(3) and provides:

• Short (-f) and long (--foo) flag names.
• Useful flag types like StringSet, StringEnum, and DurationLong.
• Improved parsing ergonomics.

Example of defining various flag types with ff.FlagSet:

fs := ff.NewFlagSet("myprogram")
var (
	addrs     = fs.StringSet('a', "addr", "remote address (repeatable)")
	compress  = fs.Bool('c', "compress", "enable compression")
	transform = fs.Bool('t', "transform", "enable transformation")
	loglevel  = fs.StringEnum('l', "log", "log level: debug, info, error", "info", "debug", "error")
	_         = fs.StringLong("config", "", "config file (optional)")
)

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

fmt.Printf("addrs=%v compress=%v transform=%v loglevel=%v\n", *addrs, *compress, *transform, *loglevel)

You can use ff.Parse to extend the standard library's flag.FlagSet with support for environment variables and configuration files. This allows you to maintain compatibility with standard Go flag definitions while adding multi-source configuration capabilities.

Use ff.WithEnvVarPrefix to define the prefix for environment variables and ff.WithConfigFileFlag to specify which flag identifies the configuration file. Use ff.WithConfigFileParser to choose a parser (e.g., ff.PlainParser).

fs := flag.NewFlagSet("myprogram", flag.ContinueOnError)
var (
	listenAddr = fs.String("listen", "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)")
)

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

fmt.Printf("listen=%s refresh=%s debug=%v\n", *listen, *refresh, *debug)

The ff.Command type provides a declarative way to build complex CLI applications with subcommands (similar to docker or kubectl).

To build a command tree:

1. Define a root ff.Command with its own ff.FlagSet.
2. Define subcommands as ff.Command instances.
3. Use .SetParent(parentFlagSet) on subcommand flag sets to inherit global flags.
4. Append subcommands to the Subcommands slice of the parent command.
5. Call cmd.ParseAndRun(ctx, args) to execute the tree.

// textctl -- root command
textctlFlags := ff.NewFlagSet("textctl")
verbose := textctlFlags.Bool('v', "verbose", "increase log verbosity")
textctlCmd := &ff.Command{
	Name:  "textctl",
	Usage: "textctl [FLAGS] SUBCOMMAND ...",
	Flags: textctlFlags,
}

// textctl repeat -- subcommand
repeatFlags := ff.NewFlagSet("repeat").SetParent(textctlFlags)
n := repeatFlags.IntShort('n', 3, "how many times to repeat")
repeatCmd := &ff.Command{
	Name:      "repeat",
	Usage:     "textctl repeat [-n TIMES] ARG",
	ShortHelp: "repeatedly print the first argument to stdout",
	Flags:     repeatFlags,
	Exec:      func(ctx context.Context, args []string) error { /* ... */ },
}
textctlCmd.Subcommands = append(textctlCmd.Subcommands, repeatCmd)

if err := textctlCmd.ParseAndRun(context.Background(), os.Args[1:]); err != nil {
	fmt.Fprintf(os.Stderr, "%s\n", ffhelp.Command(textctlCmd))
	fmt.Fprintf(os.Stderr, "error: %v\n", err)
	os.Exit(1)
}

The ff package implements a layered configuration model. When Parse is called, it processes sources in a specific order of precedence. This allows users to provide defaults in a config file, override them with environment variables for containerized environments, and finally override everything with explicit command-line flags.

Priority Order

1. Command-line Arguments: The most specific source. If a flag is provided here, it is marked as provided and cannot be changed by other sources.
2. Environment Variables: If enabled via options, ff looks for environment variables matching the flag's name (transformed to uppercase and using underscores for separators). If a flag was already set by the command line, environment variables are ignored for that flag.
3. Config Files: If enabled, ff reads the file using a provided configParseFunc. If a flag was already set by the command line or environment, the config file value is ignored (unless the config file specifies the same flag multiple times, in which case it may append to slices).

Environment Variable Mapping

By default, ff transforms flag names into environment variable keys:

• Hyphens - and dots . are replaced with underscores _.
• The name is converted to uppercase.
• An optional prefix can be added.

Example: A flag --database-url becomes DATABASE_URL (or APP_DATABASE_URL if the APP prefix is used).