Document how to source completions

clap-rs / clap

A full featured, fast Command Line Argument Parser for Rust

docs.rs/clap

Apache License 2.0

13.72k stars 1.02k forks source link

Document how to source completions #2488

Open ajeetdsouza opened 3 years ago

ajeetdsouza commented 3 years ago

Please complete the following tasks

[X] I have searched the discussions
[X] I have searched the existing issues

Clap Version

3.0.0-beta.2

Where?

clap_generate

What's wrong?

Currently, clap generates completions without providing any insight into how to actually get them running in the shell.

How to fix?

It would be nice if we could specify (for each shell):

How to source the generated completions as a file
How to source the generated completions when printed to stdout
How to add the above to your shell configuration file

kidonng commented 3 years ago

I'd like to give a simple and general description:

Bash: install bash-completion (some distros have this by default), then the completions can be sourced
Zsh: the optimal way is to use $fpath, but if one would really like to go the manual way:
```
autoload -U compinit
compinit
source <(program completions zsh | sed '$d') # can also be `head -n -1` or whatever as long as the last line is removed
compdef _program program
```
FWIW, it is said that completions generated by cobra (clap counterpart in Go) can be directly sourced (i.e. no need to strip the last line), may worth looking into
Fish: directly source-able 🎉

I don't have much experience with other shells so additions welcome.

nicholastmosher commented 3 years ago

Hmm, that makes me wonder if there wouldn't be any reason not to update the output of program completions zsh to just include the autoload and compdef commands. It'd be nice to just be able to do

source <(program completions zsh)

Where program completions zsh would just look like

autoload -U compinit
compinit
<old content of 'program completions zsh'>
compdef _program program

One could certainly do that at the app-level, but is there no reason to build that directly into the completions output of clap?

kidonng commented 3 years ago

@nicholastmosher I can't say for sure, but I think generally clap completions are generated at packaging time. That is to say, when you install a program from the package manager, it comes with the completions placed at the suitable location so shells will pick them up automatically. Manually sourcing the completions is not the usual way people use it.

nicholastmosher commented 3 years ago

Ah I see. I was taking inspiration from the oh-my-zsh kubectl completions plugin: https://github.com/ohmyzsh/ohmyzsh/blob/master/plugins/kubectl/kubectl.plugin.zsh#L1-L11, though it seems like that is more geared towards dynamic completions like described in https://github.com/clap-rs/clap/issues/1232

gakonst commented 2 years ago

For me I had to do 2 things to get it working with ZSH 5.8 (program is your command's name):

Remove the last line (program "$@")
Replace the first line from #compdef program to #compdef _program program

Unsure why this is not happening by default, is this a bug?

Also, if there's any backticks in any help message, the shell tries to interpret it due to shell expansion, suspect it's related to https://github.com/clap-rs/clap/issues/1596