carapace

README

carapace

Completion script 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 any command is sufficient to enable completion script generation using the hidden command.

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

carapace.Gen(myCmd)

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

Documentation

Index

• func IsCallback() bool
• func Test(t testing)
• type Action
  • func ActionBool() 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.CacheKey) 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 IsCallback

func IsCallback() bool

func Test

func Test(t testing)

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 ActionBool

func ActionBool() Action

ActionBool completes true/false

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.CacheKey) Action

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

type Carapace

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

func Gen

func Gen(cmd *cobra.Command) *Carapace

func (Carapace) FlagCompletion

func (c Carapace) FlagCompletion(actions ActionMap)

func (Carapace) PositionalAnyCompletion

func (c Carapace) PositionalAnyCompletion(action Action)

func (Carapace) PositionalCompletion

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

func (Carapace) Snippet

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

func (Carapace) Standalone

func (c Carapace) Standalone()

type CompletionCallback

type CompletionCallback func(c Context) Action

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
}

type InvokedAction

type InvokedAction Action

func (InvokedAction) Filter

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

func (InvokedAction) Merge

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

func (InvokedAction) Prefix

func (a InvokedAction) Prefix(prefix string) InvokedAction

func (InvokedAction) Suffix

func (a InvokedAction) Suffix(suffix string) InvokedAction

func (InvokedAction) ToA

func (a InvokedAction) ToA() Action

func (InvokedAction) ToMultiPartsA

func (a InvokedAction) ToMultiPartsA(divider string) Action