carapace

README

carapace

Command-line completion generator for cobra with support for:

• Bash
• Elvish
• Fish
• Ion (experimental)
• Nushell (experimental)
• Oil
• Powershell
• Tcsh (experimental)
• Xonsh
• Zsh

Status

WIP: works, but expect some api changes and small hiccups like a special character not yet escaped

Usage

Calling carapace.Gen on the root command is sufficient to enable completion script generation using the hidden command.

import (
    "github.com/rsteube/carapace"
)

carapace.Gen(rootCmd)

Standalone Mode

Carapace can also be used to provide completion for arbitrary commands as well (similar to aws_completer). See rsteube/carapace-bin for examples. There is also a binary to parse flags from gnu help pages at caraparse.

Example

An example implementation can be found in the example folder.

cd example
go build .

# bash
PATH=$PATH:$(pwd)
source <(example _carapace bash)

# elvish
paths=[$@paths (pwd)]
eval (example _carapace elvish | slurp)

# fish
set PATH $PATH (pwd) 
example _carapace fish | source

# oil
PATH=$PATH:$(pwd)
source <(example _carapace oil)

# powershell
Set-PSReadlineKeyHandler -Key Tab -Function MenuComplete
$env:PATH += ":$pwd"
example _carapace powershell | out-string | Invoke-Expression

# tcsh
set autolist
eval `example _carapace tcsh`

# xonsh
$PATH.append($(pwd))
exec($(example _carapace xonsh))

# zsh
PATH=$PATH:$(pwd)
source <(example _carapace zsh)

example <TAB>

or use docker-compose:

docker-compose pull
docker-compose run --rm build
docker-compose run --rm [bash|elvish|fish|ion|nushell|oil|powershell|tcsh|xonsh|zsh]

example <TAB>

Projects

• carapace-bin multi-shell multi-command argument completer
• go-jira-cli simple jira command line client
• lab cli client for GitLab

Documentation

Index

• func ActionExecCommand(name string, arg ...string) func(f func(output []byte) Action) Action
• func Batch(actions ...Action) batch
• func IsCallback() bool
• func Override(o Opts)
• func Test(t testingT)
• type Action
  • func ActionCallback(callback CompletionCallback) Action
  • func ActionDirectories() Action
  • func ActionFiles(suffix ...string) Action
  • func ActionMessage(msg string) Action
  • func ActionMultiParts(divider string, callback func(c Context) Action) Action
  • func ActionValues(values ...string) Action
  • func ActionValuesDescribed(values ...string) Action
  • func (a Action) Cache(timeout time.Duration, keys ...pkgcache.Key) Action
  • func (a Action) Chdir(dir string) Action
  • func (a Action) Invoke(c Context) InvokedAction
  • func (a Action) NoSpace() Action
• type ActionMap
• type Carapace
  • func Gen(cmd *cobra.Command) *Carapace
  • func (c Carapace) FlagCompletion(actions ActionMap)
  • func (c Carapace) PositionalAnyCompletion(action Action)
  • func (c Carapace) PositionalCompletion(action ...Action)
  • func (c Carapace) Snippet(shell string) (string, error)
  • func (c Carapace) Standalone()
• type CompletionCallback
• type Context
• type InvokedAction
  • func (a InvokedAction) Filter(values []string) InvokedAction
  • func (a InvokedAction) Merge(others ...InvokedAction) InvokedAction
  • func (a InvokedAction) Prefix(prefix string) InvokedAction
  • func (a InvokedAction) Suffix(suffix string) InvokedAction
  • func (a InvokedAction) ToA() Action
  • func (a InvokedAction) ToMultiPartsA(divider string) Action
• type Opts

Functions

func ActionExecCommand

func ActionExecCommand(name string, arg ...string) func(f func(output []byte) Action) Action

ActionExecCommand invokes given command and transforms its output using given function on success or returns ActionMessage with the first line of stderr if available.

carapace.ActionExecCommand("git", "remote")(func(output []byte) carapace.Action {
  lines := strings.Split(string(output), "\n")
  return carapace.ActionValues(lines[:len(lines)-1]...)
})

func Batch

func Batch(actions ...Action) batch

Batch creates a batch of Actions that can be invoked in parallel

func IsCallback

func IsCallback() bool

IsCallback returns true if current program invocation is a callback

func Override

func Override(o Opts)

Override changes completion behaviour for non-posix style flags in standalone mode. Mostly done by patching `os.Args` before command execution and thus must be called before it. These are considered hacks and might undergo changes in future (or replaced by a custom pflag fork).

func Execute() error {
    carapace.Override(carapace.Opts{
        LongShorthand: true,
        OptArgDelimiter: ":",
    })
	return rootCmd.Execute()
}

func Test

func Test(t testingT)

Test verifies the configuration (e.g. flag name exists)

func TestCarapace(t *testing.T) {
    carapace.Test(t)
}

Types

type Action

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

Action indicates how to complete a flag or positional argument

func ActionCallback

func ActionCallback(callback CompletionCallback) Action

ActionCallback invokes a go function during completion

func ActionDirectories

func ActionDirectories() Action

ActionDirectories completes directories

func ActionFiles

func ActionFiles(suffix ...string) Action

ActionFiles completes files with optional suffix filtering

func ActionMessage

func ActionMessage(msg string) Action

ActionMessage displays a help messages in places where no completions can be generated

func ActionMultiParts

func ActionMultiParts(divider string, callback func(c Context) Action) Action

ActionMultiParts completes multiple parts of words separately where each part is separated by some char (CallbackValue is set to the currently completed part during invocation)

func ActionValues

func ActionValues(values ...string) Action

ActionValues completes arbitrary keywords (values)

func ActionValuesDescribed

func ActionValuesDescribed(values ...string) Action

ActionValuesDescribed completes arbitrary key (values) with an additional description (value, description pairs)

func (Action) Cache

func (a Action) Cache(timeout time.Duration, keys ...pkgcache.Key) Action

Cache cashes values of a CompletionCallback for given duration and keys

func (Action) Chdir

func (a Action) Chdir(dir string) Action

Chdir changes the current working directory to the named directory during invocation.

func (Action) Invoke

func (a Action) Invoke(c Context) InvokedAction

Invoke executes the callback of an action if it exists (supports nesting)

func (Action) NoSpace

func (a Action) NoSpace() Action

NoSpace disables space suffix

type ActionMap

type ActionMap map[string]Action

ActionMap maps Actions to an identifier

type Carapace

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

Carapace wraps cobra.Command to define completions

func Gen

func Gen(cmd *cobra.Command) *Carapace

Gen initialized Carapace for given command

func (Carapace) FlagCompletion

func (c Carapace) FlagCompletion(actions ActionMap)

FlagCompletion defines completion for flags using a map consisting of name and Action

func (Carapace) PositionalAnyCompletion

func (c Carapace) PositionalAnyCompletion(action Action)

PositionalAnyCompletion defines completion for any positional argument not already defined

func (Carapace) PositionalCompletion

func (c Carapace) PositionalCompletion(action ...Action)

PositionalCompletion defines completion for positional arguments using a list of Actions

func (Carapace) Snippet

func (c Carapace) Snippet(shell string) (string, error)

Snippet creates completion script for given shell

func (Carapace) Standalone

func (c Carapace) Standalone()

Standalone prevents cobra defaults interfering with standalone mode (e.g. implicit help command)

type CompletionCallback

type CompletionCallback func(c Context) Action

CompletionCallback is executed during completion of associated flag or positional argument

type Context

type Context struct {
	// CallbackValue contains the (partial) value (or part of it during an ActionMultiParts) currently being completed
	CallbackValue string
	// Args contains the positional arguments of current (sub)command (exclusive the one currently being completed)
	Args []string
	// Parts contains the splitted CallbackValue during an ActionMultiParts (exclusive the part currently being completed)
	Parts []string
}

Context provides information during completion

type InvokedAction

type InvokedAction Action

InvokedAction is a logical alias for an Action whose (nested) callback was invoked

func (InvokedAction) Filter

func (a InvokedAction) Filter(values []string) InvokedAction

Filter filters given values (this should be done before any call to Prefix/Suffix as those alter the values being filtered)

a := carapace.ActionValues("A", "B", "C").Invoke(c)
b := a.Filter([]string{"B"}) // ["A", "C"]

func (InvokedAction) Merge

func (a InvokedAction) Merge(others ...InvokedAction) InvokedAction

Merge merges InvokedActions (existing values are overwritten)

a := carapace.ActionValues("A", "B").Invoke(c)
b := carapace.ActionValues("B", "C").Invoke(c)
c := a.Merge(b) // ["A", "B", "C"]

func (InvokedAction) Prefix

func (a InvokedAction) Prefix(prefix string) InvokedAction

Prefix adds a prefix to values (only the ones inserted, not the display values)

a := carapace.ActionValues("melon", "drop", "fall").Invoke(c)
b := a.Prefix("water") // ["watermelon", "waterdrop", "waterfall"] but display still ["melon", "drop", "fall"]

func (InvokedAction) Suffix

func (a InvokedAction) Suffix(suffix string) InvokedAction

Suffix adds a suffx to values (only the ones inserted, not the display values)

a := carapace.ActionValues("apple", "melon", "orange").Invoke(c)
b := a.Suffix("juice") // ["applejuice", "melonjuice", "orangejuice"] but display still ["apple", "melon", "orange"]

func (InvokedAction) ToA

func (a InvokedAction) ToA() Action

ToA casts an InvokedAction to Action

func (InvokedAction) ToMultiPartsA

func (a InvokedAction) ToMultiPartsA(divider string) Action

ToMultiPartsA create an ActionMultiParts from values with given divider

a := carapace.ActionValues("A/B/C", "A/C", "B/C", "C").Invoke(c)
b := a.ToMultiPartsA("/") // completes segments separately (first one is ["A/", "B/", "C"])

type Opts

type Opts struct {
	// LongShorthand forces flag names to use non-posix single `-` style
	// No shorthand flags should be used in this mode (thus no shorthand chaining).
	//   false // chown --verbose (default)
	//   true  // java -classpath
	LongShorthand bool
	// OptArgDelimiter changes the delimiter for optional flag arguments
	//   "=" // tail --verbose=descriptor (default)
	//   ":" // java -verbose:class
	OptArgDelimiter string
}

Opts contains overrides for completion behaviour