carapace

README

carapace

Command argument completion generator for cobra. You can read more about it here: A pragmatic approach to shell completion.

Supported shells:

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

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

# nushell
example _carapace nushell | save example.nu
source example.nu

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

# powershell
Set-PSReadLineOption -Colors @{ "Selection" = "`e[7m" }
Set-PSReadlineKeyHandler -Key Tab -Function MenuComplete
$env:PATH += ":$pwd"
example _carapace powershell | out-string | Invoke-Expression

# tcsh
set autolist
eval `example _carapace tcsh`

# xonsh
$COMPLETION_QUERY_LIMIT = 500 # increase limit
$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
• knoxite A data storage & backup system
• lab cli client for GitLab

Documentation

Overview

Package carapace is a command argument completion generator for spf13/cobra

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 ActionExecute(cmd *cobra.Command) Action
  • func ActionFiles(suffix ...string) Action
  • func ActionImport(output []byte) Action
  • func ActionMessage(msg string) Action
  • func ActionMultiParts(divider string, callback func(c Context) Action) Action
  • func ActionStyleConfig() Action
  • func ActionStyledValues(values ...string) Action
  • func ActionStyledValuesDescribed(values ...string) Action
  • func ActionStyles(styles ...string) 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
  • func (a Action) Style(style string) Action
  • func (a Action) StyleF(f func(s string) string) Action
  • func (a Action) StyleR(style *string) Action
  • func (a Action) Suppress(expr ...string) Action
• type ActionMap
• type Carapace
  • func Gen(cmd *cobra.Command) *Carapace
  • func (c Carapace) DashAnyCompletion(action Action)
  • func (c Carapace) DashCompletion(action ...Action)
  • func (c Carapace) FlagCompletion(actions ActionMap)
  • func (c Carapace) PositionalAnyCompletion(action Action)
  • func (c Carapace) PositionalCompletion(action ...Action)
  • func (c Carapace) PreInvoke(f func(cmd *cobra.Command, flag *pflag.Flag, action Action) Action)
  • func (c Carapace) Snippet(shell string) (string, error)
  • func (c Carapace) Standalone()
• type CompletionCallback
• type Context
  • func (c Context) Abs(s string) (string, error)
  • func (c Context) Command(name string, arg ...string) *execabs.Cmd
  • func (c *Context) Setenv(key, value string)
• 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 ActionExecute

func ActionExecute(cmd *cobra.Command) Action

ActionExecute executes completion on an internal command TODO example

func ActionFiles

func ActionFiles(suffix ...string) Action

ActionFiles completes files with optional suffix filtering

func ActionImport

func ActionImport(output []byte) Action

ActionImport parses the json output from export as Action

carapace.Gen(rootCmd).PositionalAnyCompletion(
	carapace.ActionCallback(func(c carapace.Context) carapace.Action {
		args := []string{"_carapace", "export", ""}
		args = append(args, c.Args...)
		args = append(args, c.CallbackValue)
		return carapace.ActionExecCommand("command", args...)(func(output []byte) carapace.Action {
			return carapace.ActionImport(output)
		})
	}),
)

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 ActionStyleConfig

func ActionStyleConfig() Action

ActionStyleConfig completes style configuration

carapace.Value=blue
carapace.Description=magenta

func ActionStyledValues

func ActionStyledValues(values ...string) Action

ActionStyledValues is like ActionValues but also accepts a style

func ActionStyledValuesDescribed

func ActionStyledValuesDescribed(values ...string) Action

ActionStyledValuesDescribed is like ActionValues but also accepts a style

func ActionStyles

func ActionStyles(styles ...string) Action

Actionstyles completes styles

blue
bg-magenta

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

func (Action) Style

func (a Action) Style(style string) Action

Style sets the style

ActionValues("yes").Style(style.Green)
ActionValues("no").Style(style.Red)

func (Action) StyleF

func (a Action) StyleF(f func(s string) string) Action

Style sets the style using a function

ActionValues("dir/", "test.txt").StyleF(style.ForPathExt)
ActionValues("true", "false").StyleF(style.ForKeyword)

func (Action) StyleR

func (a Action) StyleR(style *string) Action

Style sets the style using a reference

ActionValues("value").StyleR(&style.Carapace.Value)
ActionValues("description").StyleR(&style.Carapace.Value)

func (Action) Suppress

func (a Action) Suppress(expr ...string) Action

Suppress suppresses specific error messages using regular expressions

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

func (c Carapace) DashAnyCompletion(action Action)

DashAnyCompletion defines completion for any positional arguments after dash (`--`) not already defined

func (Carapace) DashCompletion

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

DashCompletion defines completion for positional arguments after dash (`--`) using a list of Actions

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 arguments 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) PreInvoke

func (c Carapace) PreInvoke(f func(cmd *cobra.Command, flag *pflag.Flag, action Action) Action)

PreInvoke TODO experimental

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
	// Env contains environment variables for current context
	Env []string
	// Dir contains the working directory for current context
	Dir string
}

Context provides information during completion

func (Context) Abs

func (c Context) Abs(s string) (string, error)

func (Context) Command

func (c Context) Command(name string, arg ...string) *execabs.Cmd

Command returns the Cmd struct to execute the named program with the given arguments. Env and Dir are set using the Context. See exec.Command for most details.

func (*Context) Setenv

func (c *Context) Setenv(key, value string)

Setenv sets the value of the environment variable named by the key.

type InvokedAction

type InvokedAction struct {
	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
	// BridgeCompletion registers carapace completions to cobra's default completion
	BridgeCompletion bool
}

Opts contains overrides for completion behaviour