carapace

README

carapace

Completion script generator for cobra with support for:

• Bash
• Elvish
• Fish
• Powershell
• 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 enough to enable completion script generation using the hidden command.

Invocations to carapace.Gen must be after the command was added to the parent command so that the uids are correct.

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

carapace.Gen(myCmd)

FlagCompletions

Completion for flags can be configured with FlagCompletion and a map consisting of name and action.

carapace.Gen(myCmd).FlagCompletion(carapace.ActionMap{
    "flagName": carapace.ActionValues("a", "b", "c"),
    ...
})

PositionalCompletions

Completion for positional arguments can be configured with PositionalCompletion and a list of actions.

carapace.Gen(callbackCmd).PositionalCompletion(
    carapace.ActionValues("a", "b", "c"),
    ...
)

Hidden Command

When carapace.Gen(myCmd) is invoked a hidden command (_carapace) is added to the root command unless it already exists. This handles completion script generation and callbacks.

Uid

Uids are generated to identify corresponding completions:

• _{rootCmd}__{subCommand1}__{subCommand2}#{position} for positional arguments
• _{rootCmd}__{subCommand1}__{subCommand2}##{flagName} for flags

Action

An action indicates how to complete a flag or a positional argument. See action.go and the examples below for current implementations.

ActionMessage

carapace.ActionMessage("message example")

// #./example action --message <TAB>
// message example

ActionValuesDescribed

carapace.ActionValuesDescribed(
  "values", "valueDescription",
  "example", "exampleDescription"),

// #./example action --values_described <TAB>
// example  -- exampleDescription
// values   -- valueDescription

ActionCallback

ActionCallback is a special action where the program itself provides the completion dynamically. For this the hidden command is called with a uid and the current command line content which then lets cobra parse existing flags and invokes the callback function after that.

carapace.ActionCallback(func(args []string) carapace.Action {
  if conditionCmd.Flag("required").Value.String() == "valid" {
    return carapace.ActionValues("condition fulfilled")
  } else {
    return carapace.ActionMessage("flag --required must be set to valid: " + conditionCmd.Flag("required").Value.String())
  }
})

// #./example condition --required invalid <TAB>
// flag --required must be set to valid: invalid

Since callbacks are simply invocations of the program they can be tested directly.

./example _carapace bash '_example__condition#1' example condition --required invalid
#compgen -W "ERR flag_--required_must_be_set_to_valid:_invalid" -- $last

./example _carapace elvish '_example__condition#1' example condition --required invalid
#edit:complex-candidate ERR &display-suffix=' (flag --required must be set to valid: invalid)'
#edit:complex-candidate _ &display-suffix=' ()'

./example _carapace fish '_example__condition#1' example condition --required invalid
#echo -e ERR\tflag --required must be set to valid: invalid\n_\t\n\n

./example _carapace powershell '_example__condition#1' example condition --required invalid
#[CompletionResult]::new('ERR', 'ERR', [CompletionResultType]::ParameterValue, ' ')
#[CompletionResult]::new('flag --required must be set to valid: invalid', 'flag --required must be set to valid: invalid', [CompletionResultType]::ParameterValue, ' ')

./example _carapace zsh '_example__condition#1' example condition --required invalid
# _message -r 'flag --required must be set to valid: invalid'

ActionMultiParts

This is an initial version which still got some quirks, expect some changes here (in the long term this shall return Action as well)

ActionMultiParts is a callback action where parts of an argument can be completed separately (e.g. user:group from chown). Divider can be empty as well, but note that bash and fish will add the space suffix for anything other than /=@:., (it still works, but after each selection backspace is needed to continue the completion).

carapace.ActionMultiParts(":", func(args []string, parts []string) []string {
	switch len(parts) {
	case 0:
		return []{"user1:", "user2:", "user3:"}
	case 1:
		return []{"groupA", "groupB", "groupC"}
	default:
		return []string{}
	}
})

Custom Action

For actions that aren't implemented or missing required options, a custom action can be defined.

carapace.Action{Zsh: "_most_recent_file 2"}

// #./example action --custom <TAB>

Additional information can be found at:

• Bash: bash-programmable-completion-tutorial and Programmable-Completion-Builtins
• Elvish: using-and-writing-completions-in-elvish and argument-completer
• Fish: fish-shell/share/functions and writing your own completions
• Powershell: Dynamic Tab Completion and Register-ArgumentCompleter
• Zsh: zsh-completions-howto and Completion-System.

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)]
example _carapace elvish > example.elv
-source example.elv

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

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

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

example <TAB>

or use docker-compose:

docker-compose run --rm build
docker-compose run --rm [bash|elvish|fish|powershell|zsh]

example <TAB>

Projects

• carapace-bin multi-shell multi-command argument completer
• lab cli client for GitLab

Documentation

Index

• Variables
• func IsCallback() bool
• type Action
  • func ActionBool() Action
  • func ActionCallback(callback CompletionCallback) Action
  • func ActionDirectories() Action
  • func ActionExecute(command string) Action
  • func ActionFiles(suffix string) Action
  • func ActionGroups() Action
  • func ActionHosts() Action
  • func ActionKillSignals() Action
  • func ActionMessage(msg string) Action
  • func ActionMultiParts(divider string, callback func(args []string, parts []string) []string) Action
  • func ActionNetInterfaces() Action
  • func ActionPrefixValues(prefix string, values ...string) Action
  • func ActionUserGroup() Action
  • func ActionUsers() Action
  • func ActionValues(values ...string) Action
  • func ActionValuesDescribed(values ...string) Action
  • func (a Action) NestedValue(args []string, shell string, maxDepth int) string
  • func (a Action) Value(shell string) string
• type ActionMap
  • func (m *ActionMap) Shell(shell string) map[string]string
• type Carapace
  • func Gen(cmd *cobra.Command) *Carapace
  • func (c Carapace) Bash() string
  • func (c Carapace) Elvish() string
  • func (c Carapace) Fish() string
  • func (c Carapace) FlagCompletion(actions ActionMap)
  • func (c Carapace) PositionalAnyCompletion(action Action)
  • func (c Carapace) PositionalCompletion(action ...Action)
  • func (c Carapace) Powershell() string
  • func (c Carapace) Snippet(shell string) string
  • func (c Carapace) Standalone()
  • func (c Carapace) Zsh() string
• type CompletionCallback
• type Completions

Variables

var CallbackValue string

TODO find a better solution for this

Functions

func IsCallback

func IsCallback() bool

Types

type Action

type Action struct {
	Bash       string
	Elvish     string
	Fish       string
	Zsh        string
	Powershell string
	Callback   CompletionCallback
}

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

func ActionExecute

func ActionExecute(command string) Action

ActionExecute uses command substitution to invoke a command and evalues it's result as Action

func ActionFiles

func ActionFiles(suffix string) Action

func ActionGroups

func ActionGroups() Action

ActionGroups completes group names

func ActionHosts

func ActionHosts() Action

ActionHosts completes host names

func ActionKillSignals

func ActionKillSignals() Action

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(args []string, parts []string) []string) Action

ActionMultiParts completes multiple parts of words separately where each part is separated by some char

func ActionNetInterfaces

func ActionNetInterfaces() Action

ActionNetInterfaces completes network interface names

func ActionPrefixValues

func ActionPrefixValues(prefix string, values ...string) Action

func ActionUserGroup

func ActionUserGroup() Action

ActionUserGroup completes user:group separately

func ActionUsers

func ActionUsers() Action

ActionUsers completes user names

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

func (a Action) NestedValue(args []string, shell string, maxDepth int) string

func (Action) Value

func (a Action) Value(shell string) string

type ActionMap

type ActionMap map[string]Action

func (*ActionMap) Shell

func (m *ActionMap) Shell(shell string) map[string]string

type Carapace

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

func Gen

func Gen(cmd *cobra.Command) *Carapace

func (Carapace) Bash

func (c Carapace) Bash() string

func (Carapace) Elvish

func (c Carapace) Elvish() string

func (Carapace) Fish

func (c Carapace) Fish() string

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

func (c Carapace) Powershell() string

func (Carapace) Snippet

func (c Carapace) Snippet(shell string) string

func (Carapace) Standalone

func (c Carapace) Standalone()

func (Carapace) Zsh

func (c Carapace) Zsh() string

type CompletionCallback

type CompletionCallback func(args []string) Action

type Completions

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