README

complete

Build Status codecov golangci GoDoc goreadme

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
  1. 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:

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

Sub Packages

  • cmd: Package cmd used for command line options for the complete tool

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

  • match: Package match contains matchers that decide if to apply completion.


Created by goreadme

Expand ▾ Collapse ▴

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

Constants

This section is empty.

Variables

View Source
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

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

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

      Functions

      This section is empty.

      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.

                                                Directories

                                                Path Synopsis
                                                cmd
                                                Package cmd used for command line options for the complete tool
                                                Package cmd used for command line options for the complete tool
                                                example
                                                self
                                                Package self a program that complete itself
                                                Package self a program that complete itself
                                                Package main is complete tool for the go command line
                                                Package main is complete tool for the go command line
                                                Package match contains matchers that decide if to apply completion.
                                                Package match contains matchers that decide if to apply completion.