Document external subcommands

[epage]

Discussed in #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.

[epage]

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

[emersonford]

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

[cd-work]

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.

[epage]

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.