complete

README

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:

• bash
• zsh
• fish

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.

• 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.

---

Created by goreadme

Documentation

Overview

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

2. 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

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.

Index

• func CommandLine(name string)
• func Complete(name string, cmd Completer)
• func Test(t *testing.T, cmp Completer, args string, want []string)
• type Command
  • func (c *Command) ArgsGet() Predictor
  • func (c *Command) Complete(name string)
  • func (c *Command) FlagGet(flag string) Predictor
  • func (c *Command) FlagList() []string
  • func (c *Command) SubCmdGet(cmd string) Completer
  • func (c *Command) SubCmdList() []string
• type Completer
  • func FlagSet(flags *flag.FlagSet) Completer
• type PredictFunc
  • func (p PredictFunc) Predict(prefix string) []string
• type Predictor

Functions

func CommandLine

func CommandLine(name string)

Complete default command line flag set defined by the standard library.

func Complete

func Complete(name string, cmd Completer)

Complete the command line arguments for the given command in the case that the program was invoked with COMP_LINE and COMP_POINT environment variables. In that case it will also `os.Exit()`. The program name should be provided for installation purposes.

func Test

func Test(t *testing.T, cmp Completer, args string, want []string)

Test is a testing helper function for testing bash completion of a given completer.

Types

type Command

type Command struct {
	// Sub is map of sub commands of the current command. The key refer to the sub command name, and
	// the value is it's command descriptive struct.
	Sub map[string]*Command
	// Flags is a map of flags that the command accepts. The key is the flag name, and the value is
	// it's predictions. In a chain of sub commands, no duplicate flags should be defined.
	Flags map[string]Predictor
	// Args are extra arguments that the command accepts, those who are given without any flag
	// before. In any chain of sub commands, only one of them should predict positional arguments.
	Args Predictor
}

Command is an object that can be used to create complete options for a go executable that does not have a good binding to the `Completer` interface, or to use a Go program as complete binary for another executable (see ./gocomplete as an example.)

func (*Command) ArgsGet

func (c *Command) ArgsGet() Predictor

func (*Command) Complete

func (c *Command) Complete(name string)

Complete runs the completion of the described command.

func (*Command) FlagGet

func (c *Command) FlagGet(flag string) Predictor

func (*Command) FlagList

func (c *Command) FlagList() []string

func (*Command) SubCmdGet

func (c *Command) SubCmdGet(cmd string) Completer

func (*Command) SubCmdList

func (c *Command) SubCmdList() []string

type Completer

type Completer interface {
	// SubCmdList should return the list of all sub commands of the current command.
	SubCmdList() []string
	// SubCmdGet should return a sub command of the current command for the given sub command name.
	SubCmdGet(cmd string) Completer
	// FlagList should return a list of all the flag names of the current command. The flag names
	// should not have the dash prefix.
	FlagList() []string
	// FlagGet should return completion options for a given flag. It is invoked with the flag name
	// without the dash prefix. The flag is not promised to be in the command flags. In that case,
	// this method should return a nil predictor.
	FlagGet(flag string) Predictor
	// ArgsGet should return predictor for positional arguments of the command line.
	ArgsGet() Predictor
}

Completer is an interface that a command line should implement in order to get bash completion.

func FlagSet

func FlagSet(flags *flag.FlagSet) Completer

FlagSet returns a completer for a given standard library `flag.FlagSet`. It completes flag names, and additionally completes value if the `flag.Value` implements the `Predicate` interface.

type PredictFunc

type PredictFunc func(prefix string) []string

PredictFunc is a function that implements the Predictor interface.

func (PredictFunc) Predict

func (p PredictFunc) Predict(prefix string) []string

type Predictor

type Predictor interface {
	// Predict returns prediction options for a given prefix. The prefix is what currently is typed
	// as a hint for what to return, but the returned values can have any prefix. The returned
	// values will be filtered by the prefix when needed regardless. The prefix may be empty which
	// means that no value was typed.
	Predict(prefix string) []string
}

Predictor can predict completion options.