go-flags

The go-flags library uses Go structs and reflection to define command line options. You specify options by adding struct fields with specific tags. Supported tags include:

• short: Single character short name (e.g., short:"v" for -v).
• long: Long name (e.g., long:"verbose" for --verbose).
• description: Help text for the option.
• required: Set to "true" to make the flag mandatory.
• choice: Restricts the input to a pre-defined set of strings (e.g., choice:"cat" choice:"dog").
• value-name: The name used for the argument in the help message (e.g., value-name:"FILE").
• default: The default value for the option.
• env: The environment variable name to use if the flag is not provided.
• env-delim: The delimiter used for environment variable values (e.g., env-delim:",").

Supported types include all primitive Go types, slices (for multiple occurrences), maps, pointers, and function callbacks.

type Options struct {
	Verbose []bool `short:"v" long:"verbose" description:"Show verbose debug information"` 
	Name    string `short:"n" long:"name" description:"A name" required:"true"` 
	Animal  string `long:"animal" choice:"cat" choice:"dog"` 
}

go-flags provides built-in support for bash completion. To enable it, your application must be invoked with the environment variable GO_FLAGS_COMPLETION=1.

Usage: GO_FLAGS_COMPLETION=1 ./your-app arg1 arg2 arg3 (where arg3 is the argument currently being completed).

Bash Integration Example:

_completion_example() {
    # All arguments except the first one
    args=("${COMP_WORDS[@]:1:$COMP_CWORD})"

    # Only split on newlines
    local IFS=$'\n'

    # Call completion
    COMPREPLY=($(GO_FLAGS_COMPLETION=1 ${COMP_WORDS[0]} "${args[@]}"))
    return 0
}

complete -F _completion_example completion-example

Notes:

• Completion requires the parser option PassDoubleDash.
• Setting GO_FLAGS_COMPLETION=verbose will show descriptions of possible completion items if there are more than one.
• You can customize completion for argument values by implementing the flags.Completer interface.

This example demonstrates various features: boolean slices for repeated flags, automatic type marshalling, function callbacks, required flags, choice restrictions, pointers, slices, maps, and environment variable integration.

var opts struct {
	Verbose []bool `short:"v" long:"verbose" description:"Show verbose debug information"`
	Offset uint `long:"offset" description:"Offset"`
	Call func(string) `short:"c" description:"Call phone number"`
	Name string `short:"n" long:"name" description:"A name" required:"true"`
	Animal string `long:"animal" choice:"cat" choice:"dog"`
	File string `short:"f" long:"file" description:"A file" value-name:"FILE"`
	Ptr *int `short:"p" description:"A pointer to an integer"`
	StringSlice []string `short:"s" description:"A slice of strings"`
	PtrSlice []*string `long:"ptrslice" description:"A slice of pointers to string"`
	IntMap map[string]int `long:"intmap" description:"A map from string to int"`
	Thresholds  []int     `long:"thresholds" default:"1" default:"2" env:"THRESHOLD_VALUES"  env-delim:"\","`
}

opts.Call = func(num string) {
	cmd := exec.Command("open", "callto:"+num)
	cmd.Start()
	cmd.Process.Release()
}

args := []string{
	"-vv",
	"--offset=5",
	"-n", "Me",
	"--animal", "dog",
	"-p", "3",
	"-s", "hello",
	"-s", "world",
	"--ptrslice", "hello",
	"--ptrslice", "world",
	"--intmap", "a:1",
	"--intmap", "b:5",
	"arg1",
	"arg2",
	"arg3",
}

args, err := flags.ParseArgs(&opts, args)
if err != nil {
	panic(err)
}

fmt.Printf("Verbosity: %v\n", opts.Verbose)
fmt.Printf("Offset: %d\n", opts.Offset)
fmt.Printf("Name: %s\n", opts.Name)
fmt.Printf("Animal: %s\n", opts.Animal)
fmt.Printf("Ptr: %d\n", *opts.Ptr)
fmt.Printf("StringSlice: %v\n", opts.StringSlice)
fmt.Printf("PtrSlice: [%v %v]\n", *opts.PtrSlice[0], *opts.PtrSlice[1])
fmt.Printf("IntMap: [a:%v b:%v]\n", opts.IntMap["a"], opts.IntMap["b"])
fmt.Printf("Remaining args: %s\n", strings.Join(args, " "))