README
¶
Yet another envflag library
This is a simple library that allows that enables reading the value of flags from environment variables.
Why?
The Go flags package is well-thought-out, battle-tested, and extensively used, but modern deployment practices tend to favour storing configuration in environment variables rather than passing them in on the command-line.
envflag and its predecessors bridge this gap by mapping environment variables onto flags.
How?
Import this package, and use envflag.Parse instead of flag.Parse:
package main
import (
"flag"
"github.com/csmith/envflag"
)
var (
myFlag = flag.String("my-flag", "woohoo", "Something or other")
)
func main() {
envflag.Parse()
println(*myFlag)
}
What?
In its default configuration, envflag will:
- Map all flag names to appropriate environment variable names (
my-flag->MY_FLAG) - Update the usage information of flags to include the environment variable name
- Show usage and exit with an appropriate status code on error
- Use the default set of flags provided by
flag.CommandLine - Call
flag.Parseto also parse any command-line flags
You can customise the behaviour of envflag by passing in options:
Prefix all environment variables
envflag.Parse(envflag.WithPrefix("MYAPP_"))
Changes the mapping of environment variables to always include the given prefix
(e.g. my-flag -> MYAPP_MY_FLAG).
Use a different flag set
envflag.Parse(envflag.WithFlagSet(someFlagSet))
Use the given flag.FlagSet instead of flag.CommandLine.
Don't show environment variable names in usage
envflag.Parse(envflag.WithShowInUsage(false))
Suppresses the default behaviour of updating flag usage to include the environment variable names.
Use a different set of arguments
envflag.Parse(envflag.WithArguments([]string{"-option1", "-option2"}))
When parsing the command-line arguments, use the given slice instead of os.Args[1:].
Licence/credits/contributions etc
Released under the MIT licence. See LICENCE for full details.
Heavily inspired by kouhin/envflag which does mostly the same job but can't easily add prefixes and is a bit harder to configure.
Contributions are welcome! Please feel free to open issues or send pull requests.
Documentation
¶
Overview ¶
Package envflag facilitates setting standard Go flags using environment variables.
Basic usage ¶
Simply replace the typical call to flag.Parse() with envflag.Parse(). Flag names are mapped to environment variables by converting them to uppercase, and replacing dashes with underscores (e.g. `my-flag` => `MY_FLAG`). Command-line arguments will take precedence over environment variables where both are specified.
Advanced usage ¶
You can customise the behaviour of envflag by passing in options to the Parse() method. For example, to add a prefix to all environment variables:
envflag.Parse(envflag.WithPrefix("MYAPP_"))
This will map a flag named `my-flag` to the environment variable `MYAPP_MY_FLAG`.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Parse ¶
func Parse(opts ...Option)
Parse parses flag values from the environment and the arguments list. Must be called after all flags are defined and before flags are accessed by the program.
The parsing behaviour can be customised by passing one or more options, but will use sensible defaults if no options are passed.
If an error occurs trying to set a flag, error and usage information will be printed to the flag.FlagSet's Output and os.Exit(2) will be called. This is the same behaviour as flag.ExitOnError, which is the default behaviour for the flag.CommandLine set.
NOTE: This method will call flag.Parse(). Callers do not need to call it directly.
Types ¶
type Option ¶
type Option func(*config)
Option defines a configuration option for the envflag package.
func WithArguments ¶
WithArguments specifies the arguments that should be parsed into flags. If a flag is specified in both an environment variable and in the given arguments, the one in the arguments will be used. Defaults to the command-line arguments (os.Args[1:]).
func WithFlagSet ¶
WithFlagSet specifies which FlagSet envflag should operate on. If not specified, defaults to flag.CommandLine.
func WithPrefix ¶
WithPrefix alters the mapping of flag names to environment variables so that they are prefixed with the given string. If not specified, no prefix is used.
func WithShowInUsage ¶
WithShowInUsage specifies whether the name of environment variables should be prepended to the usage text of each flag. If not specified, defaults to true.
Source Files