complete

Package complete is everything for bash completion and Go.

Writing bash completion scripts is a hard work, usually done in the bash scripting language. This package provides:

• A library for bash completion for Go programs.

• A tool for writing bash completion script in the Go language. For any Go or non Go program.

• Bash completion for the go command line (See ./gocomplete).

• Library for bash-completion enabled flags (See ./compflag).

• Enables an easy way to install/uninstall the completion of the command.

The library and tools are extensible such that any program can add its one logic, completion types or methologies.

Go Command Bash Completion

./gocomplete is the script for bash completion for the go command line. This is an example that uses the complete package on the go command - the complete package can also be used to implement any completions, see #usage.

Install:

1. Type in your shell:

go get -u github.com/posener/complete/v2/gocomplete
COMP_INSTALL=1 gocomplete

1. Restart your shell

Uninstall by COMP_UNINSTALL=1 gocomplete

Features:

• Complete go command, including sub commands and flags.
• Complete packages names or .go files when necessary.
• Complete test names after -run flag.

Complete Package

Supported shells:

• [x] bash
• [x] zsh
• [x] fish

The installation of completion for a command line tool is done automatically by this library by running the command line tool with the COMP_INSTALL environment variable set. Uninstalling the completion is similarly done by the COMP_UNINSTALL environment variable. For example, if a tool called my-cli uses this library, the completion can install by running COMP_INSTALL=1 my-cli.

Usage

Add bash completion capabilities to any Go program. See ./example/command.

 import (
    "flag"
    "github.com/posener/complete/v2"
    "github.com/posener/complete/v2/predict"
 )
 var (
    // Add variables to the program.
    name      = flag.String("name", "", "")
    something = flag.String("something", "", "")
    nothing   = flag.String("nothing", "", "")
 )
 func main() {
    // Create the complete command.
    // Here we define completion values for each flag.
    cmd := &complete.Command{
        Flags: map[string]complete.Predictor{
            "name":      predict.Set{"foo", "bar", "foo bar"},
            "something": predict.Something,
            "nothing":   predict.Nothing,
        },
    }
    // Run the completion - provide it with the binary name.
    cmd.Complete("my-program")
    // Parse the flags.
    flag.Parse()
    // Program logic...
 }

This package also enables to complete flags defined by the standard library flag package. To use this feature, simply call complete.CommandLine before flag.Parse. (See ./example/stdlib).

 import (
    "flag"
+   "github.com/posener/complete/v2"
 )
 var (
    // Define flags here...
    foo = flag.Bool("foo", false, "")
 )
 func main() {
    // Call command line completion before parsing the flags - provide it with the binary name.
+   complete.CommandLine("my-program")
    flag.Parse()
 }

If flag value completion is desired, it can be done by providing the standard library flag.Var function a flag.Value that also implements the complete.Predictor interface. For standard flag with values, it is possible to use the github.com/posener/complete/v2/compflag package. (See ./example/compflag).

 import (
    "flag"
+   "github.com/posener/complete/v2"
+   "github.com/posener/complete/v2/compflag"
 )
 var (
    // Define flags here...
-   foo = flag.Bool("foo", false, "")
+   foo = compflag.Bool("foo", false, "")
 )
 func main() {
    // Call command line completion before parsing the flags.
+   complete.CommandLine("my-program")
    flag.Parse()
 }

Instead of calling both complete.CommandLine and flag.Parse, one can call just compflag.Parse which does them both.

Testing

For command line bash completion testing use the complete.Test function.

Sub Packages

• compflag: Package compflag provides a handful of standard library-compatible flags with bash complition capabilities.

• compflag/gen: Generates flags.go.

• example/command: command shows how to have bash completion to an arbitrary Go program using the complete.Command struct.

• example/compflag: compflag shows how to use the github.com/posener/complete/v2/compflag package to have auto bash completion for a defined set of flags.

• example/stdlib: stdlib shows how to have flags bash completion to an arbitrary Go program that uses the standard library flag package.

• gocomplete: Package main is complete tool for the go command line

• install: Package install provide installation functions of command completion.

• predict: Package predict provides helper functions for completion predictors.

Examples

OutputCapturing

ExampleComplete_outputCapturing demonstrates the ability to capture the output of Complete() invocations, crucial for integration tests.

defer func(f func(int)) { exit = f }(exit)
defer func(f getEnvFn) { getEnv = f }(getEnv)
exit = func(int) {}

// This is where the actual example starts:

cmd := &Command{Sub: map[string]*Command{"bar": {}}}
getEnv = promptEnv("foo b")

Complete("foo", cmd)

Output:

bar

Readme created from Go doc with goreadme