carapace

README

carapace

Command-line completion generator for cobra with support for:

• Bash
• Elvish
• Fish
• Ion (experimental)
• Nushell (experimental)
• Oil
• Powershell
• 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

# 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|xonsh|zsh]

example <TAB>

Projects

• carapace-bin multi-shell multi-command argument completer
• gh github cli with added completions (fork)
• lab cli client for GitLab
• pulumi pulumi cli with added completions (fork)

Documentation

Index

• func ActionExecCommand(name string, arg ...string) func(f func(output []byte) Action) Action
• func IsCallback() bool
• 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) Invoke(c Context) InvokedAction
• 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

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 IsCallback

func IsCallback() bool

IsCallback returns true if current program invocation is a callback

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) Invoke

func (a Action) Invoke(c Context) InvokedAction

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

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"])