Provide an attribute that implements a common --completions <SHELL>
convention without boilerplate
#5504
Closed
2 tasks done
Labels
Please complete the following tasks
Clap Version
N/A
Describe your use case
A lot of programs now implement one of the following:
program --completions <SHELL>
program completions <SHELL>
I loooove
clap
andclap_complete
, and would love for this to be so simple to configure that I can configure it for a project (or contribute it to another project usingclap
) in minimal code.While it would be nice to support both the flag and command version, I think command version is more fraught1, so I will focus on a proposal for the flag version.
Describe the solution you'd like
I'd love to get full completions functionality with syntax like this:
clap_complete
supports acompletions
attribute.completions
at the top level of the program. (Or I think this should at least generate warning unless explicitly silenced.)Option<Shell>
.clap_complete
automatically generates default documentation for the flag, something like this:clap_complete
ignores any other arguments/input, prints completions, and exits with code0
(example).stdout
orstderr
that can begrep
ped with low false positives?default_completions_behaviour
attribute that automatically injects the flag?Alternatives, if applicable
The main alternative is to leave this for each program to implement individually.
However, I think this is not ideal in the long term:
clap
to do some research and manually figure out how to integrate this into their code. By contrast, a singleclap_complete
directive is trivial to try out, and will work perfectly the first time in a lot of cases. Now there's a value proposition!clap_complete
will automatically stay up to date over time with upgrades toclap_complete
. No need to keep the flag's documentation up to date manually for each program if there are feature changes (such as newly supported shells).source <(folderify --completions bash)
inbash
on my computer, because of an issue with piping. If I find a fix, I'd love to contribute that toclap_complete
and upgrade dependencies instead of fixing a copy of the code in each of my programs. Since most shells are still actively getting new features and shell syntax/semantics can be really subtle, I'd bet there will be more such issues over time, and it would be much more powerful to have all the compatibility handled in one place.I'd also love for this to serve as the basis for a standard convention for discoverable completions that can be used by package managers and shells. Hence my emphasis on consistent behaviour with consistent invocation syntax.
For example, Homebrew makes it a one-liner to support completions for a given program, but you don't get them for a given program if someone didn't add that line manually.2 I can imagine a package manager that automatically invokes
--completions
and loads them automatically, or at least introduces a linter for package definitions that highlights when completions seem to be available (but are not explicitly marked as supported/unsupported). This kind of functionality could also integrate with something likecargo install
or shells directly.Additional Context
I know I'm probably not thinking of some details (e.g. how to avoid pulling in the standard library, how to have a program signal support for this convention without complications for legacy programs), but I think at an implementation level this should be a fairly moderate amount of code? But I know I'm asking for kind of bold stance on paving the path for a kind of hardcoded convention, when
clap
andclap_complete
are all about versatility and flexibility in general.I'd be glad to contribute a PR if maintainers are on board and can give me a few pointers.
Footnotes
If you want to figure out whether a program supports something, I think a flag is generally much safer to try than a command. For example,
rm --completions fish
is basically safe to run, whilerm completions fish
is a recipe for a bad time. ↩In fact, I was motivated to file this issue after I found that Homebrew was missing completions for
tailscale
. They were super quick to accept my PR to add support. But that means everyone is only getting these completions going forward, when they were actually already available! ↩The text was updated successfully, but these errors were encountered: