This is an intermediate solution for #4408. As there were no agreeed
upon goals, I went with what I felt read well and that I saw commonly
used on non-clap commands.
- "information" isn't really a necessary word.
- I originally favored `Print this help` but realied that doesn't read
correctly in completions.
- Besides being shorter, the reason for the flipped short/long hint is
it gives people the context they need for scanning, emphasizing
"summary" and "more".
Fixes#4409
This prevents global args from showing in help completions,
since help completions should only suggest subcommands.
Adds tests to ensure the args still show in the generated
help messages of subcommands.
* Copy hide flag
* Revert global args special handling. Another commit will
address the issue of whether global args should be included in
help subtrees.
Adds parser flags to toggle whether to run the
expensive clone logic for completions case.
Help completion will only suggest subcommands, not args.
clap_complete generator sets the flag.
Before we introduced actions, it required specific setups to engage with
claps version and help printing. With actions making that more
explicit, we don't get as much benefit from our multiple, obscure, ways
of users customizing help
Before
- Modify existing help or version with `mut_arg` which would
automatically be pushed down the command tree like `global(true)`
- Create an new help or version and have it treated as if it was the
built-in on (I think)
- Use the same flags as built-in and have the built-in flags
automatically disabled
- Users could explicitly disable the built-in functionality and do what
they want
Now
- `mut_arg` no longer works as we define help and version flags at the
end
- If someone defines a flag that overlaps with the built-ins by id,
long, or short, a debug assert will tell them to explicitly disable
the built-in
- Any customization has to be done by a user providing their own. To
propagate through the command tree, they need to set `global(true)`.
Benefits
- Hopefully, this makes it less confusing on how to override help
behavior. Someone creates an arg and we then tell them how to disable
the built-in
- This greatly simplifies the arg handling by pushing more
responsibility onto the developer in what are hopefully just corner
cases
- This removes about 1Kb from .text
Fixes#3405Fixes#4033
This reduces ambiguity in how the different "multiple" parts of the API
interact and lowrs the amount of API surface area users have to dig
through to use clap.
For now, this is only a matter of cleaning up the public API. Cleaning
up the implementation is the next step.
This is a step towards #3309. We want to make longs and long aliases
more consistent in how they handle leading dashes. There is more
flexibility offered in not stripping and it matches the v3 short
behavior of only taking the non-dash form. This starts the process by
disallowing it completely so people will catch problems with it and
remove their existing leading dashes. In a subsequent breaking release
we can remove the debug assert and allow triple-leading dashes.
This is a part of #2717
Some settings didn't get getters because
- They are transient parse settings (e.g. ignore errors)
- They get propagated to args and should be checked there
`is_allow_hyphen_values_set` is a curious case. In some cases, we only
check the app and not an arg. This seems suspicious.
`clap_generate` originally intended to be "generate anything". With
`fig`, we already broke one part out. With #3174's man support, we are
also looking at keeping it separate:
- More freedom to iterate on the API
- Uniqueness (and potential weight) of its dependencies
- man generation is normally more for distribution while completions are
a mix of being distributed with the app or the app generating the
completions (which will be exacerbated if we move most completion
parsing logic to be in Rust)
So `clap_generate` is having a lot more limited of a role than the
original name conveys. I worry the generic name will be a hindrance to
people discovering and using it (yes, documentation can help but there
are limits).
I hesitated because we are on the verge of releasing 3.0. However, doing
it even later will be even more disruptive because more people will be
using it (crates.io lists ~70 people using `clap_generate`).
To ease things, we are still releasing `clap_generate` as a wrapper
around `clap_complete`.
