complete

README

complete

Writing bash completion scripts is a hard work, usually done in the bash scripting language. This package can help produce a binary which will serve as the auto-completion input/output facility: your shell will run your binary everytime completion is required with the input being the user's current command line, and the binary's output being the suggested completions.

Installation

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.

Example

import (
 	"flag"
 	"github.com/ipinfo/cli/lib/complete"
 	"github.com/ipinfo/cli/lib/complete/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...
}

Documentation

Index

• func Complete(name string, cmd Completer)
• func Test(t *testing.T, cmp Completer, args string, want []string)
• type Arg
  • func Parse(line string) []Arg
• 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
• type Parsed
• type PredictFunc
  • func (p PredictFunc) Predict(prefix string) []string
• type Predictor
• type Tokener
  • func (t *Tokener) Closed() string
  • func (t *Tokener) Escaped() bool
  • func (t *Tokener) Fixed() string
  • func (t *Tokener) LastSpace() bool
  • func (t *Tokener) Quoted() bool
  • func (t *Tokener) Visit(b byte)

Functions

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 Arg

type Arg struct {
	Text      string
	Completed bool
	Parsed
}

Arg is typed a command line argument.

func Parse

func Parse(line string) []Arg

Parse parses a typed command line argument list, and returns a list of arguments.

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.

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.

type Parsed

type Parsed struct {
	Flag     string
	HasFlag  bool
	Value    string
	HasValue bool
}

Parsed contains information about the argument.

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 Tokener

type Tokener struct {
	// contains filtered or unexported fields
}

func (*Tokener) Closed

func (t *Tokener) Closed() string

func (*Tokener) Escaped

func (t *Tokener) Escaped() bool

func (*Tokener) Fixed

func (t *Tokener) Fixed() string

func (*Tokener) LastSpace

func (t *Tokener) LastSpace() bool

func (*Tokener) Quoted

func (t *Tokener) Quoted() bool

func (*Tokener) Visit

func (t *Tokener) Visit(b byte)

Visit visit a byte and update the state of the quotes. It returns true if the byte was quotes or escape character.