-
-
Notifications
You must be signed in to change notification settings - Fork 11
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
partly updated README content
- Loading branch information
Showing
2 changed files
with
135 additions
and
2 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,132 @@ | ||
# carapace | ||
|
||
[![CircleCI](https://circleci.com/gh/rsteube/carapace.svg?style=svg)](https://circleci.com/gh/rsteube/carapace) | ||
|
||
[ZSH completion](https://github.com/zsh-users/zsh-completions/blob/master/zsh-completions-howto.org) and [Fish completion](https://fishshell.com/docs/current/#writing-your-own-completions) script generator for [cobra] (based on [spf13/cobra#646](https://github.com/spf13/cobra/pull/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](#hidden-command). | ||
|
||
> Invocations to `carapace.Gen` must be **after** the command was to the parent command so that the [uids](#uid) are correct. | ||
```go | ||
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](#action). | ||
|
||
```go | ||
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](#action). | ||
|
||
```go | ||
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](#actioncallback). | ||
|
||
|
||
### Uid | ||
|
||
Uids are generated to identify corresponding completions: | ||
- `_{rootCmd}__{subCommand1}__{subCommand2}#{position}` for positional arguments | ||
- `_{rootCmd}__{subCommand1}__{subCommand2}##{flagName}` for flags | ||
|
||
|
||
## Action | ||
An [action](#action) indicates how to complete a flag or a positional argument. See [action.go](./action.go) and the examples below for current implementations. | ||
|
||
Additional information can be found at [zsh-completions-howto](https://github.com/zsh-users/zsh-completions/blob/master/zsh-completions-howto.org#functions-for-performing-complex-completions-of-single-words) and the [official documentation](http://zsh.sourceforge.net/Doc/Release/Completion-System.html#Completion-System). | ||
|
||
### ActionMessage | ||
|
||
```go | ||
carapace.ActionMessage("message example") | ||
|
||
// #./example action --message <TAB> | ||
// message example | ||
``` | ||
|
||
### ActionValuesDescribed | ||
|
||
```go | ||
carapace.ActionValuesDescribed( | ||
"values", "valueDescription", | ||
"example", "exampleDescription"), | ||
|
||
// #./example action --values_described <TAB> | ||
// example -- exampleDescription | ||
// values -- valueDescription | ||
``` | ||
|
||
### ActionCallback | ||
|
||
ActionCallback is a special [action](#action) where the program itself provides the completion dynamically. For this the [hidden command](#hidden-command) is called with a [uid](#uid) and the current command line content which then lets [cobra] parse existing flags and invokes the callback function after that. | ||
|
||
```go | ||
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. | ||
|
||
```sh | ||
./example _carapace zsh '_example__condition#1' condition --required invalid | ||
|
||
# _message -r 'flag --required must be set to valid: invalid' | ||
``` | ||
|
||
### Custom Action | ||
|
||
For [actions](#action) that aren't implemented or missing required options, a custom action can be defined. | ||
|
||
```go | ||
carapace.Action{Value: "_most_recent_file 2"} | ||
|
||
// #./example action --custom <TAB> | ||
``` | ||
|
||
## Example | ||
|
||
An example implementation can be found in the [example](./example/) folder. | ||
|
||
```sh | ||
cd example | ||
go build . | ||
source <(./example _carapace zsh) | ||
./example <TAB> | ||
``` | ||
|
||
[cobra]:https://github.com/spf13/cobra |