carapace

README

carapace

ZSH completion and Fish completion script generator for cobra (based on spf13/cobra#646).

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 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 (when invoked with arg zsh or fish) 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.

Additional information can be found at zsh-completions-howto and the official documentation.

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 zsh '_example__condition#1' 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{Value: "_most_recent_file 2"}

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

Example

An example implementation can be found in the example folder.

cd example
go build .
source <(./example _carapace zsh)
./example <TAB>

Documentation

Index

• 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 ActionOptions() Action
  • func ActionPathFiles(suffix string) 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 (zsh Carapace) FlagCompletion(actions ActionMap)
  • func (zsh Carapace) PositionalCompletion(action ...Action)
• type CompletionCallback
• type Completions
  • func (c Completions) GenerateFish(cmd *cobra.Command) string
  • func (c Completions) GenerateFishFunctions(cmd *cobra.Command) string
  • func (c Completions) GenerateZsh(cmd *cobra.Command) string
  • func (c Completions) GenerateZshFunctions(cmd *cobra.Command) string

Types

type Action

type Action struct {
	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 ActionOptions

func ActionOptions() Action

ActionOptions completes the names of shell options

func ActionPathFiles

func ActionPathFiles(suffix string) Action

ActionPathFiles completes filepaths

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

func (zsh Carapace) FlagCompletion(actions ActionMap)

func (Carapace) PositionalCompletion

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

type CompletionCallback

type CompletionCallback func(args []string) Action

type Completions

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

func (Completions) GenerateFish

func (c Completions) GenerateFish(cmd *cobra.Command) string

fish

func (Completions) GenerateFishFunctions

func (c Completions) GenerateFishFunctions(cmd *cobra.Command) string

func (Completions) GenerateZsh

func (c Completions) GenerateZsh(cmd *cobra.Command) string

func (Completions) GenerateZshFunctions

func (c Completions) GenerateZshFunctions(cmd *cobra.Command) string