clap
clap copied to clipboard
Document external subcommands
Discussed in https://github.com/clap-rs/clap/discussions/3863
Originally posted by cd-work June 22, 2022 I'd like to write an external subcommand that accepts any parameter and forwards it, however it should also still be documented as subcommand.
I think this is probably a pretty common scenario, since you usually have some way to know which external subcommands are available even if you do not know their exact parameters. I do not want to allow just any subcommand, I have a list which I want to accept with generic parameters, everything else should still cause a failure.
I've tried using ignore_errors(true)
, but that only seems to work globally and not on the subcommands themselves. Otherwise it could be used to just accept parameters.
I've also used various combinations of allowing hyphen values and multiple values, but none of them seem to allow for the first argument to have two hyphens.
I only care about the subcommands documentation and description on the toplevel, since bin subcommand --help
should already be forwarded to the subcommand and not handled by clap. This is also a scenario where built-in subcommands and flags exist already, so it's not only external subcommands I'm worried about.
I only care about the subcommands documentation and description on the toplevel, since
bin subcommand --help
should already be forwarded to the subcommand and not handled by clap.
Unless you are disabling it, this still leaves bin help subcommand
just two cents from someone who's been working on something similar w/ external subcommands, I think a more reasonable approach API might be something like treat_flags_as_positional_args
or something of that nature, which could essentially just make the bin subcommand -- this --flag is not treated as a flag
behavior the default.
specifically, allow_external_subcommands
has the side effect of also handling unrecognized positional args (not just subcommands). if we could tell Clap to treat flags just as positional args, allow_external_subcommand
would gracefully handle this situation for free.
would also make it clear that bin help subcommand
isn't treated as an external subcommand and I feel like it's a bit clearer than ignore_error
edit: this approach would also solve #3880
The ignore_errors
approach just seems like the simplest way to get an acceptable solution without introducing a dedicated API, though I agree that it is not ideal.
If I had to consider an ideal API for my usecase, I think it would be a way to specify a list of named external subcommands with a description of what they do, which is used as documentation on the toplevel, but then also informs clap that these are not going to want their own subcommand docs.
The concrete effect this would have on bin help subcommand
still isn't straightforward though. While you could transform it to bin subcommand --help
, that's pretty hacky so far from ideal. But just erroring out for external subcommands would probably work just fine, I personally think bin subcommand help
makes much more sense to use anyway.
I believe with #4187 it should now work to define subcommands and then capture all their values with arg.trailing_var_arg(true).allow_hyphen_values(true)
. You will also need to disable help and version flags on these semi-external subcommands as well.