complete

Documentation

Overview

Package complete provides a tool for bash writing bash completion in go, and bash completion for the go command line.

Writing bash completion scripts is a hard work. This package provides an easy way to create bash completion scripts for any command, and also an easy way to install/uninstall the completion of the command.

Go Command Bash Completion

In ./cmd/gocomplete there is an example 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/gocomplete
gocomplete -install

2. Restart your shell

Uninstall by `gocomplete -uninstall`

Features

- Complete `go` command, including sub commands and all 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

Assuming you have program called `run` and you want to have bash completion for it, meaning, if you type `run` then space, then press the `Tab` key, the shell will suggest relevant complete options.

In that case, we will create a program called `runcomplete`, a go program, with a `func main()` and so, that will make the completion of the `run` program. Once the `runcomplete` will be in a binary form, we could `runcomplete -install` and that will add to our shell all the bash completion options for `run`.

So here it is:

import "github.com/posener/complete"

func main() {

	// create a Command object, that represents the command we want
	// to complete.
	run := complete.Command{

		// Sub defines a list of sub commands of the program,
		// this is recursive, since every command is of type command also.
		Sub: complete.Commands{

			// add a build sub command
			"build": complete.Command {

				// define flags of the build sub command
				Flags: complete.Flags{
					// build sub command has a flag '-cpus', which
					// expects number of cpus after it. in that case
					// anything could complete this flag.
					"-cpus": complete.PredictAnything,
				},
			},
		},

		// define flags of the 'run' main command
		Flags: complete.Flags{
			// a flag -o, which expects a file ending with .out after
			// it, the tab completion will auto complete for files matching
			// the given pattern.
			"-o": complete.PredictFiles("*.out"),
		},

		// define global flags of the 'run' main command
		// those will show up also when a sub command was entered in the
		// command line
		GlobalFlags: complete.Flags{

			// a flag '-h' which does not expects anything after it
			"-h": complete.PredictNothing,
		},
	}

	// run the command completion, as part of the main() function.
	// this triggers the autocompletion when needed.
	// name must be exactly as the binary that we want to complete.
	complete.New("run", run).Run()
}

Self completing program

In case that the program that we want to complete is written in go we can make it self completing. Here is an example: ./example/self/main.go .

Index

• Variables
• type Args
  • func (a Args) Directory() string
• type Command
  • func (c *Command) Predict(a Args) []string
• type Commands
  • func (c Commands) Predict(a Args) (prediction []string)
• type Complete
  • func New(name string, command Command) *Complete
  • func (c *Complete) Complete() bool
  • func (c *Complete) Run() bool
• type Flags
  • func (f Flags) Predict(a Args) (prediction []string)
• type PredictFunc
  • func PredictFilesSet(files []string) PredictFunc
  • func (p PredictFunc) Predict(a Args) []string
• type Predictor
  • func PredictDirs(pattern string) Predictor
  • func PredictFiles(pattern string) Predictor
  • func PredictOr(predictors ...Predictor) Predictor
  • func PredictSet(options ...string) Predictor

Variables

var Log = getLogger()

Log is used for debugging purposes since complete is running on tab completion, it is nice to have logs to the stderr (when writing your own completer) to write logs, set the COMP_DEBUG environment variable and use complete.Log in the complete program

var PredictAnything = PredictFunc(func(Args) []string { return nil })

PredictAnything expects something, but nothing particular, such as a number or arbitrary name.

Types

type Args

type Args struct {
	// All lists of all arguments in command line (not including the command itself)
	All []string
	// Completed lists of all completed arguments in command line,
	// If the last one is still being typed - no space after it,
	// it won't appear in this list of arguments.
	Completed []string
	// Last argument in command line, the one being typed, if the last
	// character in the command line is a space, this argument will be empty,
	// otherwise this would be the last word.
	Last string
	// LastCompleted is the last argument that was fully typed.
	// If the last character in the command line is space, this would be the
	// last word, otherwise, it would be the word before that.
	LastCompleted string
}

Args describes command line arguments

func (Args) Directory

func (a Args) Directory() string

Directory gives the directory of the current written last argument if it represents a file name being written. in case that it is not, we fall back to the current directory.

Deprecated.

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 Commands

	// Flags is a map of flags that the command accepts.
	// The key is the flag name, and the value is it's predictions.
	Flags Flags

	// GlobalFlags is a map of flags that the command accepts.
	// Global flags that can appear also after a sub command.
	GlobalFlags Flags

	// Args are extra arguments that the command accepts, those who are
	// given without any flag before.
	Args Predictor
}

Command represents a command line It holds the data that enables auto completion of command line Command can also be a sub command.

func (*Command) Predict

func (c *Command) Predict(a Args) []string

Predict returns all possible predictions for args according to the command struct

type Commands

type Commands map[string]Command

Commands is the type of Sub member, it maps a command name to a command struct

func (Commands) Predict

func (c Commands) Predict(a Args) (prediction []string)

Predict completion of sub command names names according to command line arguments

type Complete

type Complete struct {
	Command Command
	cmd.CLI
	Out io.Writer
}

Complete structs define completion for a command with CLI options

func New

func New(name string, command Command) *Complete

New creates a new complete command. name is the name of command we want to auto complete. IMPORTANT: it must be the same name - if the auto complete completes the 'go' command, name must be equal to "go". command is the struct of the command completion.

func (*Complete) Complete

func (c *Complete) Complete() bool

Complete a command from completion line in environment variable, and print out the complete options. returns success if the completion ran or if the cli matched any of the given flags, false otherwise For installation: it assumes that flags were added and parsed before it was called.

func (*Complete) Run

func (c *Complete) Run() bool

Run runs the completion and add installation flags beforehand. The flags are added to the main flag CommandLine variable.

type Flags

type Flags map[string]Predictor

Flags is the type Flags of the Flags member, it maps a flag name to the flag predictions.

func (Flags) Predict

func (f Flags) Predict(a Args) (prediction []string)

Predict completion of flags names according to command line arguments

type PredictFunc

type PredictFunc func(Args) []string

PredictFunc determines what terms can follow a command or a flag It is used for auto completion, given last - the last word in the already in the command line, what words can complete it.

func PredictFilesSet

func PredictFilesSet(files []string) PredictFunc

PredictFilesSet predict according to file rules to a given set of file names

func (PredictFunc) Predict

func (p PredictFunc) Predict(a Args) []string

Predict invokes the predict function and implements the Predictor interface

type Predictor

type Predictor interface {
	Predict(Args) []string
}

Predictor implements a predict method, in which given command line arguments returns a list of options it predicts.

var PredictNothing Predictor

PredictNothing does not expect anything after.

func PredictDirs

func PredictDirs(pattern string) Predictor

PredictDirs will search for directories in the given started to be typed path, if no path was started to be typed, it will complete to directories in the current working directory.

func PredictFiles

func PredictFiles(pattern string) Predictor

PredictFiles will search for files matching the given pattern in the started to be typed path, if no path was started to be typed, it will complete to files that match the pattern in the current working directory. To match any file, use "*" as pattern. To match go files use "*.go", and so on.

func PredictOr

func PredictOr(predictors ...Predictor) Predictor

PredictOr unions two predicate functions, so that the result predicate returns the union of their predication

func PredictSet

func PredictSet(options ...string) Predictor

PredictSet expects specific set of terms, given in the options argument.