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/monk-io/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

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/monk-io/complete/v2"
 	"github.com/monk-io/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/monk-io/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/monk-io/complete/v2/compflag package. (See ./example/compflag).

 import (
 	"flag"
+	"github.com/monk-io/complete/v2"
+	"github.com/monk-io/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/monk-io/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.

---

Readme created from Go doc with 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/monk-io/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

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/monk-io/complete/v2"
 	"github.com/monk-io/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/monk-io/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/monk-io/complete/v2/compflag` package. (See ./example/compflag).

 import (
 	"flag"
+	"github.com/monk-io/complete/v2"
+	"github.com/monk-io/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

• Variables
• func CommandLine()
• func Complete(name string, cmdCompletionTree *CompTree)
• func GetFlagValue(name string) string
• func ParseArgs() []arg.Arg
• 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 CompTree
• type Completer
  • func FlagSet(flags *flag.FlagSet) Completer
• type PredictFunc
  • func (p PredictFunc) Predict(prefix string) []string
• type Predictor
• type SearchMethod
• type Suggestion
  • func AutoComplete(text string, completionTree *CompTree, queryFunc SearchMethod) ([]Suggestion, error)
  • func CompleteLine(line string, cmdCompletionTree *CompTree, searchMethod SearchMethod) ([]Suggestion, error)

Variables

var (
	SuggestSomething = []Suggestion{{Name: ""}}
	SuggestNothing   []Suggestion
	SuggestFlag      = []Suggestion{{Name: "--"}}
)

Functions

func CommandLine

func CommandLine()

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

func Complete

func Complete(name string, cmdCompletionTree *CompTree)

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 GetFlagValue

func GetFlagValue(name string) string

func ParseArgs

func ParseArgs() []arg.Arg

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 {
	Description string
	// 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
	Name string
}

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 CompTree

type CompTree struct {
	Flags map[string]*CompTree
	// FIXME: Args & Sub may be able to be combined since thus far there doesn't seem to necessitate a difference
	Args       map[string]*CompTree
	Sub        map[string]*CompTree
	Dynamic    func(prefix string) []Suggestion
	Desc       string
	Name       string
	TakesValue bool
}

a tree representation of CLI commands & sub commands

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.

type SearchMethod

type SearchMethod func(s, query string) bool

type Suggestion

type Suggestion struct {
	Name string
	Desc string
}

func AutoComplete

func AutoComplete(text string, completionTree *CompTree, queryFunc SearchMethod) ([]Suggestion, error)

func CompleteLine

func CompleteLine(line string, cmdCompletionTree *CompTree, searchMethod SearchMethod) ([]Suggestion, error)