Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
add basic implementation of tab completion (#663)
* add basic implementation of bash completion * update cobra to 1.0.0 because of spf13/cobra#1048 * add support for zsh and fish, improved help messages * add flag ´--no-descriptions´ to disable automatic command description (for shells that supports it) * fix fish not supporting env variables with dash in the name * fixed zsh completion not working * revert "#compdef" patch * add check on --no-description flag add comments regarding "hacks" change Replacer with ReplaceAll (for readability) * add docs * Apply suggestions from code review fix typos and corrections Co-authored-by: per1234 <accounts@perglass.com> * forgot a space * fix fish docs * add test for completion Co-authored-by: per1234 <accounts@perglass.com>
- Loading branch information
Showing
8 changed files
with
199 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,76 @@ | ||
| // This file is part of arduino-cli. | ||
| // | ||
| // Copyright 2020 ARDUINO SA (http://www.arduino.cc/) | ||
| // | ||
| // This software is released under the GNU General Public License version 3, | ||
| // which covers the main part of arduino-cli. | ||
| // The terms of this license can be found at: | ||
| // https://www.gnu.org/licenses/gpl-3.0.en.html | ||
| // | ||
| // You can be released from the requirements of the above licenses by purchasing | ||
| // a commercial license. Buying such a license is mandatory if you want to | ||
| // modify or otherwise use the software for commercial activities involving the | ||
| // Arduino software without disclosing the source code of your own applications. | ||
| // To purchase a commercial license, send an email to license@arduino.cc. | ||
|
|
||
| package completion | ||
|
|
||
| import ( | ||
| "bytes" | ||
| "os" | ||
| "strings" | ||
|
|
||
| "github.com/arduino/arduino-cli/cli/errorcodes" | ||
| "github.com/arduino/arduino-cli/cli/feedback" | ||
| "github.com/spf13/cobra" | ||
| ) | ||
|
|
||
| var ( | ||
| completionNoDesc bool //Disable completion description for shells that support it | ||
| ) | ||
|
|
||
| // NewCommand created a new `version` command | ||
| func NewCommand() *cobra.Command { | ||
| command := &cobra.Command{ | ||
| Use: "completion [bash|zsh|fish] [--no-descriptions]", | ||
| ValidArgs: []string{"bash", "zsh", "fish"}, | ||
| Args: cobra.ExactArgs(1), | ||
| Short: "Generates completion scripts", | ||
| Long: "Generates completion scripts for various shells", | ||
| Example: " " + os.Args[0] + " completion bash > completion.sh\n" + | ||
| " " + "source completion.sh", | ||
| Run: run, | ||
| } | ||
| command.Flags().BoolVar(&completionNoDesc, "no-descriptions", false, "Disable completion description for shells that support it") | ||
|
|
||
| return command | ||
| } | ||
|
|
||
| func run(cmd *cobra.Command, args []string) { | ||
| if completionNoDesc && (args[0] == "bash" || args[0] == "zsh") { | ||
| feedback.Errorf("Error: command description is not supported by %v", args[0]) | ||
| os.Exit(errorcodes.ErrGeneric) | ||
| } | ||
| switch args[0] { | ||
| case "bash": | ||
| cmd.Root().GenBashCompletion(os.Stdout) | ||
| break | ||
| case "zsh": | ||
| buf := new(bytes.Buffer) | ||
| cmd.Root().GenZshCompletion(buf) | ||
| // Next 3 lines are Hack, we'll wait new version of cobra with ZshV2Completion https://github.com/spf13/cobra/pull/1070 | ||
| //insert escaping before [ and ] | ||
| s := strings.ReplaceAll(buf.String(), "[", "\\[") | ||
| s = strings.ReplaceAll(s, "]", "\\]") | ||
| s = strings.ReplaceAll(s, "\\[1\\]", "[1]") // revert the case | ||
| os.Stdout.WriteString(s) | ||
| break | ||
| case "fish": | ||
| buf := new(bytes.Buffer) | ||
| cmd.Root().GenFishCompletion(buf, !completionNoDesc) | ||
| // Next 2 lines are Hack, fixed here https://github.com/spf13/cobra/pull/1122 | ||
| s := strings.ReplaceAll(buf.String(), "arduino-cli_comp", "arduino_cli_comp") //required because fish does not support env variables with "-" in the name | ||
| os.Stdout.WriteString(s) | ||
| break | ||
| } | ||
| } |
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,45 @@ | ||
| `arduino-cli` supports command-line completion (also known as *tab completion*) for basic commands. | ||
| Currently only `bash`, `zsh`, `fish` shells are supported | ||
|
|
||
| ### Before you start | ||
| In order to generate the file required to make the completion work you have to [install](installation.md) Arduino CLI first. | ||
|
|
||
| ### Generate the completion file | ||
| To generate the completion file you can use `arduino-cli completion [bash|zsh|fish] [--no-descriptions]`. | ||
| By default this command will print on the standard output (the shell window) the content of the completion file. To save to an actual file use the `>` redirect symbol. | ||
|
|
||
| ### Bash | ||
| Use `arduino-cli completion bash > arduino-cli.sh` to generate the completion file. | ||
| At this point you can move that file in `/etc/bash_completion.d/` (root access is required) with `sudo mv arduino-cli.sh /etc/bash_completion.d/`. | ||
|
|
||
| A not recommended alternative is to source the completion file in `.bashrc`. | ||
|
|
||
| Remember to open a new shell to test the functionality | ||
|
|
||
| ### Zsh | ||
| Use `arduino-cli completion zsh > _arduino-cli` to generate the completion file. | ||
| At this point you can place the file in a directory listed in your `fpath` if you have already created a directory to store your completion. | ||
|
|
||
| Or if you want you can create a directory, add it to your `fpath` and copy the file in it: | ||
|
|
||
| 1. `mkdir ~/completion_zsh` | ||
| 2. add `fpath=($HOME/completion_zsh $fpath)` at the beginning of your `.zshrc` file | ||
| 3. `mv _arduino-cli ~/completion_zsh/` | ||
|
|
||
| Remember to open a new shell to test the functionality | ||
|
|
||
| *N.B.* | ||
| The Zsh completion is working with [Oh-My-Zsh](https://ohmyz.sh/) but not with [Prezto](https://github.com/sorin-ionescu/prezto) (the zsh completion system is working in a different way than classic zsh). But hopefully it will be fixed in the future | ||
|
|
||
| ### Fish | ||
| Use `arduino-cli completion fish > arduino-cli.fish` to generate the completion file. | ||
| At this point you can place the file in `~/.config/fish/completions` as stated in the [official documentation](http://fishshell.com/docs/current/index.html#where-to-put-completions). | ||
| Remember to create the directory if it's not already there `mkdir -p ~/.config/fish/completions/` and then place the completion file in there with `mv arduino-cli.fish ~/.config/fish/completions/` | ||
|
|
||
| Remember to open a new shell to test the functionality | ||
|
|
||
| #### Disabling command and flag descriptions | ||
| By default fish completion has command and flag description enabled by default. If you want to disable this behaviour you can simply pass the `--no-descriptions` flag when calling `completion` command and the generated file will not have descriptions | ||
|
|
||
| *N.B.* | ||
| This flag is not compatible with bash or zsh |
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
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
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,63 @@ | ||
| # This file is part of arduino-cli. | ||
| # | ||
| # Copyright 2020 ARDUINO SA (http://www.arduino.cc/) | ||
| # | ||
| # This software is released under the GNU General Public License version 3, | ||
| # which covers the main part of arduino-cli. | ||
| # The terms of this license can be found at: | ||
| # https://www.gnu.org/licenses/gpl-3.0.en.html | ||
| # | ||
| # You can be released from the requirements of the above licenses by purchasing | ||
| # a commercial license. Buying such a license is mandatory if you want to modify or | ||
| # otherwise use the software for commercial activities involving the Arduino | ||
| # software without disclosing the source code of your own applications. To purchase | ||
| # a commercial license, send an email to license@arduino.cc. | ||
|
|
||
| import pytest | ||
|
|
||
| def test_completion_no_args(run_command): | ||
| result = run_command("completion") | ||
| assert not result.ok | ||
| assert "Error: accepts 1 arg(s), received 0" in result.stderr | ||
| assert result.stdout == "" | ||
|
|
||
| def test_completion_bash(run_command): | ||
| result = run_command("completion bash") | ||
| assert result.ok | ||
| assert result.stderr == "" | ||
| assert "_arduino-cli_root_command()" in result.stdout | ||
| assert "__start_arduino-cli()" in result.stdout | ||
|
|
||
| def test_completion_zsh(run_command): | ||
| result = run_command("completion zsh") | ||
| assert result.ok | ||
| assert result.stderr == "" | ||
| assert "#compdef _arduino-cli arduino-cli" in result.stdout | ||
| assert "function _arduino-cli" in result.stdout | ||
|
|
||
| def test_completion_fish(run_command): | ||
| result = run_command("completion fish") | ||
| assert result.ok | ||
| assert result.stderr == "" | ||
| assert "# fish completion for arduino-cli" in result.stdout | ||
| assert "function __arduino-cli_perform_completion" in result.stdout | ||
|
|
||
| def test_completion_bash_no_desc(run_command): | ||
| result = run_command("completion bash --no-descriptions") | ||
| assert not result.ok | ||
| assert result.stdout == "" | ||
| assert "Error: command description is not supported by bash" in result.stderr | ||
|
|
||
| def test_completion_zsh_no_desc(run_command): | ||
| result = run_command("completion zsh --no-descriptions") | ||
| assert not result.ok | ||
| assert result.stdout == "" | ||
| assert "Error: command description is not supported by zsh" in result.stderr | ||
|
|
||
| def test_completion_fish_no_desc(run_command): | ||
| result = run_command("completion fish --no-descriptions") | ||
| assert result.ok | ||
| assert result.stderr == "" | ||
| assert "# fish completion for arduino-cli" in result.stdout | ||
| assert "function __arduino-cli_perform_completion" in result.stdout | ||
| assert "__completeNoDesc" in result.stdout |