carapace

README

carapace

Completion script generator for cobra with support for:

• Bash
• Fish
• 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 for adding 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 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 zsh '_example__condition#1' example condition --required invalid
# _message -r 'flag --required must be set to valid: invalid'

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
• Fish: fish-shell/share/functions and writing your own completions
• Zsh: zsh-completions-howto and Completion-System.

Example

An example implementation can be found in the example folder.

cd example
go build .

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

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

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

example <TAB>

Documentation

Index

• func IsCallback() bool
• type Action
  • func ActionBool() Action
  • func ActionCallback(callback CompletionCallback) Action
  • func ActionExecute(command string) Action
  • func ActionFiles(suffix string) Action
  • func ActionGroups() Action
  • func ActionHosts() Action
  • func ActionMessage(msg string) Action
  • func ActionMultiParts(separator rune, values ...string) Action
  • func ActionNetInterfaces() Action
  • func ActionUsers() Action
  • func ActionValues(values ...string) Action
  • func ActionValuesDescribed(values ...string) Action
• type ActionMap
• type Carapace
  • func Gen(cmd *cobra.Command) *Carapace
  • func (c Carapace) Bash() string
  • func (c Carapace) Fish() string
  • func (c Carapace) FlagCompletion(actions ActionMap)
  • func (c Carapace) PositionalCompletion(action ...Action)
  • func (c Carapace) Snippet(shell string) string
  • func (c Carapace) Zsh() string
• type CompletionCallback
• type Completions

Functions

func IsCallback

func IsCallback() bool

Types

type Action

type Action struct {
	Bash     string
	Fish     string
	Zsh      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 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 ActionMessage

func ActionMessage(msg string) Action

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

func ActionMultiParts

func ActionMultiParts(separator rune, values ...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 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)

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

func (c Carapace) Bash() string

func (Carapace) Fish

func (c Carapace) Fish() string

func (Carapace) FlagCompletion

func (c Carapace) FlagCompletion(actions ActionMap)

func (Carapace) PositionalCompletion

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

func (Carapace) Snippet

func (c Carapace) Snippet(shell string) string

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
}