README
¶
carapace
Command argument completion generator for cobra. You can read more about it here: A pragmatic approach to shell completion.
Supported shells:
Usage
Calling carapace.Gen on the root command is sufficient to enable completion using the hidden command.
import (
"github.com/carapace-sh/carapace"
)
carapace.Gen(rootCmd)
Example
An example implementation can be found in the example folder.
Standalone Mode
Carapace can also be used to provide completion for arbitrary commands. See carapace-bin for examples.
Related Projects
- carapace-bin multi-shell multi-command argument completer
- carapace-bridge completion bridge
- carapace-pflag Drop-in replacement for spf13/pflag with support for non-posix variants
- carapace-shlex simple shell lexer
- carapace-spec define simple completions using a spec file
- carapace-spec-clap spec generation for clap-rs/clap
- carapace-spec-kingpin spec generation for alecthomas/kingpin
- carapace-spec-kong spec generation for alecthomas/kong
- carapace-spec-man spec generation for manpages
- carapace-spec-urfavecli spec generation for urfave/cli
Documentation
¶
Overview ¶
Package carapace is a command argument completion generator for spf13/cobra
Index ¶
- Variables
- func ActionExecCommand(name string, arg ...string) func(f func(output []byte) Action) Action
- func ActionExecCommandE(name string, arg ...string) func(f func(output []byte, err error) Action) Action
- func Batch(actions ...Action) batch
- func IsCallback() bool
- func Test(t interface{ ... })
- type Action
- func ActionCallback(callback CompletionCallback) Action
- func ActionCobra(...) Action
- func ActionCommands(cmd *cobra.Command) Action
- func ActionDirectories() Action
- func ActionExecutables() Action
- func ActionExecute(cmd *cobra.Command) Action
- func ActionFiles(suffix ...string) Action
- func ActionImport(output []byte) Action
- func ActionMessage(msg string, args ...interface{}) Action
- func ActionMultiParts(sep string, callback func(c Context) Action) Action
- func ActionMultiPartsN(sep string, n int, callback func(c Context) Action) Action
- func ActionPositional(cmd *cobra.Command) 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 Diff(original, new Action) Action
- func (a Action) Cache(timeout time.Duration, keys ...key.Key) Action
- func (a Action) Chdir(dir string) Action
- func (a Action) ChdirF(f func(tc pkgtraverse.Context) (string, error)) Action
- func (a Action) Filter(values ...string) Action
- func (a Action) FilterArgs() Action
- func (a Action) FilterParts() Action
- func (a Action) Invoke(c Context) InvokedAction
- func (a Action) List(divider string) Action
- func (a Action) MultiParts(dividers ...string) Action
- func (a Action) MultiPartsP(delimiter string, pattern string, ...) Action
- func (a Action) NoSpace(suffixes ...rune) Action
- func (a Action) Prefix(prefix string) Action
- func (a Action) Retain(values ...string) Action
- func (a Action) Shift(n int) Action
- func (a Action) Split() Action
- func (a Action) SplitP() Action
- func (a Action) Style(s string) Action
- func (a Action) StyleF(f func(s string, sc style.Context) string) Action
- func (a Action) StyleR(s *string) Action
- func (a Action) Suffix(suffix string) Action
- func (a Action) Suppress(expr ...string) Action
- func (a Action) Tag(tag string) Action
- func (a Action) TagF(f func(s string) string) Action
- func (a Action) Timeout(d time.Duration, alternative Action) Action
- func (a Action) UniqueList(divider string) Action
- func (a Action) UniqueListF(divider string, f func(s string) string) Action
- func (a Action) Unless(condition func(c Context) bool) Action
- func (a Action) Usage(usage string, args ...interface{}) Action
- func (a Action) UsageF(f func() string) Action
- type ActionMap
- type 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) PreRun(f func(cmd *cobra.Command, args []string))
- func (c Carapace) Snippet(name string) (string, error)
- func (c Carapace) Standalone()
- type CompletionCallback
- type Context
- func (c Context) Abs(path string) (string, error)
- func (c Context) Command(name string, arg ...string) *execlog.Cmd
- func (c Context) Envsubst(s string) (string, error)
- func (c Context) Getenv(key string) string
- func (c Context) LookupEnv(key string) (string, bool)
- func (c *Context) Setenv(key, value string)
- type InvokedAction
- func (ia InvokedAction) Filter(values ...string) InvokedAction
- func (ia InvokedAction) Merge(others ...InvokedAction) InvokedAction
- func (ia InvokedAction) Prefix(prefix string) InvokedAction
- func (ia InvokedAction) Retain(values ...string) InvokedAction
- func (ia InvokedAction) Suffix(suffix string) InvokedAction
- func (ia InvokedAction) ToA() Action
- func (ia InvokedAction) ToMultiPartsA(dividers ...string) Action
Constants ¶
This section is empty.
Variables ¶
var LOG = log.LOG
Functions ¶
func ActionExecCommand ¶
ActionExecCommand executes an external command.
carapace.ActionExecCommand("git", "remote")(func(output []byte) carapace.Action {
lines := strings.Split(string(output), "\n")
return carapace.ActionValues(lines[:len(lines)-1]...)
})
func ActionExecCommandE ¶
func ActionExecCommandE(name string, arg ...string) func(f func(output []byte, err error) Action) Action
ActionExecCommandE is like ActionExecCommand but with custom error handling.
carapace.ActionExecCommandE("supervisorctl", "--configuration", path, "status")(func(output []byte, err error) carapace.Action {
if err != nil {
const NOT_RUNNING = 3
if exitErr, ok := err.(*exec.ExitError); !ok || exitErr.ExitCode() != NOT_RUNNING {
return carapace.ActionMessage(err.Error())
}
}
return carapace.ActionValues("success")
})
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.
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 ActionCobra ¶
func ActionCobra(f func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective)) Action
ActionCora bridges given cobra completion function.
func ActionCommands ¶
ActionCommands completes (sub)commands of given command. `Context.Args` is used to traverse the command tree further down. Use `Action.Shift` to avoid this.
carapace.Gen(helpCmd).PositionalAnyCompletion( carapace.ActionCommands(rootCmd), )
func ActionExecutables ¶
func ActionExecutables() Action
ActionExecutables completes PATH executables
nvim chmod
func ActionExecute ¶
ActionExecute executes completion on an internal command TODO example.
func ActionFiles ¶
ActionFiles completes files with optional suffix filtering.
func ActionImport ¶
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.Value)
return carapace.ActionExecCommand("command", args...)(func(output []byte) carapace.Action {
return carapace.ActionImport(output)
})
}),
)
func ActionMessage ¶
ActionMessage displays a help messages in places where no completions can be generated.
func ActionMultiParts ¶
ActionMultiParts completes parts of an argument separated by sep.
func ActionMultiPartsN ¶
ActionMultiPartsN is like ActionMultiParts but limits the number of parts to `n`.
func ActionPositional ¶
ActionPositional completes positional arguments for given command ignoring `--` (dash). TODO: experimental - likely gives issues with preinvoke (does not have the full args)
carapace.Gen(cmd).DashAnyCompletion( carapace.ActionPositional(cmd), )
func ActionStyleConfig ¶
func ActionStyleConfig() Action
ActionStyleConfig completes style configuration
carapace.Value=blue carapace.Description=magenta
func ActionStyledValues ¶
ActionStyledValues is like ActionValues but also accepts a style.
func ActionStyledValuesDescribed ¶
ActionStyledValuesDescribed is like ActionValues but also accepts a style.
func ActionValues ¶
ActionValues completes arbitrary keywords (values).
func ActionValuesDescribed ¶
ActionValuesDescribed completes arbitrary key (values) with an additional description (value, description pairs).
func Diff ¶
Diff compares values of two actions. It overrides the style to hightlight changes.
red: only present in original dim: present in both green: only present in new
func (Action) Chdir ¶
Chdir changes the current working directory to the named directory for the duration of invocation.
func (Action) Filter ¶
Filter filters given values.
carapace.ActionValues("A", "B", "C").Filter("B") // ["A", "C"]
func (Action) Invoke ¶
func (a Action) Invoke(c Context) InvokedAction
Invoke executes the callback of an action if it exists (supports nesting).
func (Action) MultiParts ¶
MultiParts splits values of an Action by given dividers and completes each segment separately.
func (Action) MultiPartsP ¶
func (a Action) MultiPartsP(delimiter string, pattern string, f func(placeholder string, matches map[string]string) Action) Action
MultiPartsP is like MultiParts but with placeholders.
func (Action) NoSpace ¶
NoSpace disables space suffix for given characters (or all if none are given).
func (Action) Prefix ¶
Prefix adds a prefix to values (only the ones inserted, not the display values).
carapace.ActionValues("melon", "drop", "fall").Prefix("water")
func (Action) Retain ¶
Retain retains given values.
carapace.ActionValues("A", "B", "C").Retain("A", "C") // ["A", "C"]
func (Action) Split ¶
Split splits `Context.Value` lexicographically and replaces `Context.Args` with the tokens.
func (Action) Style ¶
Style sets the style.
ActionValues("yes").Style(style.Green)
ActionValues("no").Style(style.Red)
func (Action) StyleF ¶
Style sets the style using a function.
ActionValues("dir/", "test.txt").StyleF(style.ForPathExt)
ActionValues("true", "false").StyleF(style.ForKeyword)
func (Action) StyleR ¶
Style sets the style using a reference.
ActionValues("value").StyleR(&style.Carapace.Value)
ActionValues("description").StyleR(&style.Carapace.Value)
func (Action) Suffix ¶
Suffix adds a suffx to values (only the ones inserted, not the display values).
carapace.ActionValues("apple", "melon", "orange").Suffix("juice")
func (Action) TagF ¶
Tag sets the tag using a function.
ActionValues("192.168.1.1", "127.0.0.1").TagF(func(value string) string {
return "interfaces"
})
func (Action) Timeout ¶
Timeout sets the maximum duration an Action may take to invoke.
carapace.ActionCallback(func(c carapace.Context) carapace.Action {
time.Sleep(2*time.Second)
return carapace.ActionValues("done")
}).Timeout(1*time.Second, carapace.ActionMessage("timeout exceeded"))
func (Action) UniqueList ¶
UniqueList wraps the Action in an ActionMultiParts with given divider.
func (Action) UniqueListF ¶
UniqueListF is like UniqueList but uses a function to transform values before filtering.
type Carapace ¶
type Carapace struct {
// contains filtered or unexported fields
}
Carapace wraps cobra.Command to define completions.
func (Carapace) DashAnyCompletion ¶
DashAnyCompletion defines completion for any positional arguments after dash (`--`) not already defined.
func (Carapace) DashCompletion ¶
DashCompletion defines completion for positional arguments after dash (`--`) using a list of Actions.
func (Carapace) FlagCompletion ¶
FlagCompletion defines completion for flags using a map consisting of name and Action.
func (Carapace) PositionalAnyCompletion ¶
PositionalAnyCompletion defines completion for any positional arguments not already defined.
func (Carapace) PositionalCompletion ¶
PositionalCompletion defines completion for positional arguments using a list of Actions.
func (Carapace) Standalone ¶
func (c Carapace) Standalone()
Standalone prevents cobra defaults interfering with standalone mode (e.g. implicit help command).
type CompletionCallback ¶
CompletionCallback is executed during completion of associated flag or positional argument.
type Context ¶
type Context struct {
// Value contains the value currently being completed (or part of it during an ActionMultiParts).
Value string
// Args contains the positional arguments of current (sub)command (exclusive the one currently being completed).
Args []string
// Parts contains the splitted Value 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
// contains filtered or unexported fields
}
Context provides information during completion.
func NewContext ¶
NewContext creates a new context for given arguments.
func (Context) Command ¶
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) Envsubst ¶
Envsubst replaces ${var} in the string based on environment variables in current context.
type InvokedAction ¶
type InvokedAction struct {
// contains filtered or unexported fields
}
InvokedAction is a logical alias for an Action whose (nested) callback was invoked.
func (InvokedAction) Filter ¶
func (ia InvokedAction) Filter(values ...string) InvokedAction
Filter filters given values.
a := carapace.ActionValues("A", "B", "C").Invoke(c)
b := a.Filter([]string{"B"}) // ["A", "C"]
func (InvokedAction) Merge ¶
func (ia 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 (ia InvokedAction) Prefix(prefix string) InvokedAction
Prefix adds a prefix to values (only the ones inserted, not the display values)
carapace.ActionValues("melon", "drop", "fall").Invoke(c).Prefix("water")
func (InvokedAction) Retain ¶
func (ia InvokedAction) Retain(values ...string) InvokedAction
Retain retains given values.
a := carapace.ActionValues("A", "B", "C").Invoke(c)
b := a.Retain([]string{"A", "C"}) // ["A", "C"]
func (InvokedAction) Suffix ¶
func (ia InvokedAction) Suffix(suffix string) InvokedAction
Suffix adds a suffx to values (only the ones inserted, not the display values)
carapace.ActionValues("apple", "melon", "orange").Invoke(c).Suffix("juice")
func (InvokedAction) ToA ¶
func (ia InvokedAction) ToA() Action
ToA casts an InvokedAction to Action.
func (InvokedAction) ToMultiPartsA ¶
func (ia InvokedAction) ToMultiPartsA(dividers ...string) Action
ToMultiPartsA create an ActionMultiParts from values with given dividers
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"])
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
example-nonposix
module
|
|
|
internal
|
|
|
assert
Package assert provides test helpers
|
Package assert provides test helpers |
|
cache
Package cache provides disk cache for Actions
|
Package cache provides disk cache for Actions |
|
common
Package common code
|
Package common code |
|
shell/bash
Package bash provides bash completion
|
Package bash provides bash completion |
|
shell/bash_ble
Package bash_ble provides bash-ble completion
|
Package bash_ble provides bash-ble completion |
|
shell/elvish
Package elvish provides elvish completion
|
Package elvish provides elvish completion |
|
shell/export
Package export provides command structure export
|
Package export provides command structure export |
|
shell/fish
Package fish provides fish completion
|
Package fish provides fish completion |
|
shell/ion
Package ion provides Ion completion
|
Package ion provides Ion completion |
|
shell/nushell
Package nushell provides Nushell completion
|
Package nushell provides Nushell completion |
|
shell/oil
Package oil provides Oil completion
|
Package oil provides Oil completion |
|
shell/powershell
Package powershell provides powershell completion
|
Package powershell provides powershell completion |
|
shell/tcsh
Package tcsh provides tcsh completion
|
Package tcsh provides tcsh completion |
|
shell/xonsh
Package xonsh provides Xonsh completion
|
Package xonsh provides Xonsh completion |
|
shell/zsh
Package zsh provides zsh completion
|
Package zsh provides zsh completion |
|
spec
Package spec provides spec file generation for use with carapace-bin
|
Package spec provides spec file generation for use with carapace-bin |
|
uid
Package uid provides unique identifiers
|
Package uid provides unique identifiers |
|
pkg
|
|
|
cache/key
Package cache provides cache keys
|
Package cache provides cache keys |
|
ps
Package ps provides shell determination by process name
|
Package ps provides shell determination by process name |
|
style
Package style provide display coloring
|
Package style provide display coloring |
|
x
Package x contains experimental functions
|
Package x contains experimental functions |
|
third_party
|
|
|
github.com/elves/elvish/pkg/cli/lscolors
Package lscolors provides styling of filenames based on file features.
|
Package lscolors provides styling of filenames based on file features. |
|
github.com/hexops/gotextdiff
package gotextdiff supports a pluggable diff algorithm.
|
package gotextdiff supports a pluggable diff algorithm. |
|
github.com/hexops/gotextdiff/myers
Package myers implements the Myers diff algorithm.
|
Package myers implements the Myers diff algorithm. |
|
github.com/hexops/gotextdiff/span
Package span contains support for representing with positions and ranges in text files.
|
Package span contains support for representing with positions and ranges in text files. |
|
github.com/mitchellh/go-ps
ps provides an API for finding and listing processes in a platform-agnostic way.
|
ps provides an API for finding and listing processes in a platform-agnostic way. |
|
golang.org/x/sys/execabs
Package execabs is a drop-in replacement for os/exec that requires PATH lookups to find absolute paths.
|
Package execabs is a drop-in replacement for os/exec that requires PATH lookups to find absolute paths. |