shellcomp

README

shellcomp

A commandline tool can provide completions by responding to the --complete flag and making suggestions based on any arguments that follow the flag. The tool should write a list of suggestions to standard output (separated by newlines) and a directive

Imaging that typing git che<tab> causes the shell to complete the word checkout and then typing git checkout <tab> causes the shell to list local branches.

If git implemented its completion scripts using this API, it would be expected to interact like this:

$ git --complete che
checkout
:4

$ git --complete checkout ""
<list of local branches>
:4

The directive :4 tells the completion script not to suggest files from the working directory.

Directives

The directive is a bit flag that can combine the following options:

Directive	Name	Use for
0	DirectiveDefault	The shell should perform its default behavior after providing the returned completions
1	DirectiveError	The shell should ignore completions: an error occurred
2	DirectiveNoSpace	The shell should not add a space after completing a word (useful for completing arguments to flags that end with =)
4	DirectiveNoFileComp	The shell should not suggest files from the working directory
8	DirectiveFilterFileExt	The shell should suggest files from the working directory and use the returned completions as file extension filters instead of suggestions
16	DirectiveFilterDirs	The shell should suggest directories and use the returned completions to identify the directory in which to search

Go

Go projects may import the package "github.com/square/exoskeleton/pkg/shellcomp" and call os.Stdout.Write(shellcomp.Marshal(completions, directive, false))

Documentation

Overview

The constants in this file are taken from https://github.com/spf13/cobra/blob/v1.5.0/completions.go

Cobra defines a completion API so that generic completion logic can be written once for Bash and Zsh that invokes a CLI with `--complete --` and passes the inputs to be completed.

The CLI is expected to write suggestions to Standard Output as well as a Shell Completion Directive, which is an integer that stacks one or more bit flags.

Index

• func Marshal(completions []string, directive Directive, noDescriptions bool) (result []byte)
• type Directive
  • func Unmarshal(bytes []byte) ([]string, Directive, error)
  • func (d Directive) String() string

Functions

func Marshal

func Marshal(completions []string, directive Directive, noDescriptions bool) (result []byte)

Types

type Directive

type Directive int

Directive is a bit map representing the different behaviors the shell can be instructed to have once completions have been provided.

const (
	// DirectiveError indicates an error occurred and completions should be ignored.
	DirectiveError Directive = 1 << iota

	// DirectiveNoSpace indicates that the shell should not add a space
	// after the completion even if there is a single completion provided.
	// Used when a flag ends with '='.
	DirectiveNoSpace

	// DirectiveNoFileComp indicates that the shell should not provide
	// file completion even when no completion is provided.
	DirectiveNoFileComp

	// DirectiveFilterFileExt indicates that the provided completions
	// should be used as file extension filters.
	// For flags, using Command.MarkFlagFilename() and Command.MarkPersistentFlagFilename()
	// is a shortcut to using this directive explicitly. The BashCompFilenameExt
	// annotation can also be used to obtain the same behavior for flags.
	DirectiveFilterFileExt

	// DirectiveFilterDirs indicates that only directory names should
	// be provided in file completion. To request directory names within another
	// directory, the returned completions should specify the directory within
	// which to search. The BashCompSubdirsInDir annotation can be used to
	// obtain the same behavior but only for flags.
	DirectiveFilterDirs

	// DirectiveDefault indicates to let the shell perform its default
	// behavior after completions have been provided.
	// This one must be last to avoid messing up the iota count.
	DirectiveDefault Directive = 0
)

func Unmarshal

func Unmarshal(bytes []byte) ([]string, Directive, error)

func (Directive) String

func (d Directive) String() string

Returns a string listing the different directive enabled in the specified parameter