In some sophisticated situations, these may be expensive to calculate.
One example might be a '--branch' option accepting any single Git
branch that exists on the remote -- in such a case, the remote would
need to be queried for all possible_values. The cost is ultimately
unavoidable at runtime since this validation has to happen eventually,
but there's no need to pay it when generating help text if
`is_hide_possible_values_set`.
To keep '-h' fast, avoid collecting `possible_values` during '-h'
unless we're actually going to use the values in display.
This optimization is repeated for the manpage renderer.
This is trivially based on the short-circuiting logic at [1], which at
least supports the idea that actually consuming the iterator is not
generally-guaranteed behavior when `hide_possible_values` is set.
Note on the 'expensive' mod: This keeps all the possible_values tests
in one file but allows the entire set of tests to be controlled by the
'strings' feature (which is required to be able to use String rather
than str for each possible value).
[1]: clap_builder/src/builder/command.rs:long_help_exists_
One challenge with this is finding something that generally works.
Making this work perfectly for one setting will make it inconsistent
with other settings and take up more binary size / compile time.
So in the end, I felt like just mirroring rustc (with a bit more
brevity) seemed like a decent experiment. This will be evaluated by the
feedback on release.
This is a small part of #4638
In text communication you need to balance
- Scannability, putting the most important information upfront
- Brevity so people don't get lost in the message
- Softness to help ease people through a frustrating experience
I feel we weren't doing great on the first two points, so tried to
iterate on the messages to improve them. I hope we aren't suffering too
much on the third point as a side effect.
From
https://rustc-dev-guide.rust-lang.org/diagnostics.html#suggestion-style-guide
> Suggestions should not be a question. In particular, language like
> "did you mean" should be avoided. Sometimes, it's unclear why a
> particular suggestion is being made. In these cases, it's better to be
> upfront about what the suggestion is.
>
> The message may contain further instruction such as "to do xyz, use"
> or "to do xyz, use abc".
Inspired by #2766
This is a cheap pass at creating this to allow cutting out the cost of
rich error information / programmatic error information.
This cuts about 20 KiB off of the binary.
There is more we could cut out, like collecting of used arguments for
the usage, but I want to keep the conditionals simple.
In looking at other help output, I noticed that they use two spaces, in
place of clap's 4, and it doesn't suffer from legibility. If it
doesn't make the output worse, let's go ahead and make it as dense so we
fit more content on the screen.
This is a part of #4132
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.
When to show usage? We are currently mixed about it. For `validator`,
we didn't show it at all. Sometimes we show the used arguments and
sometimes we don't.
With `ValueParser`, I ran into the problem that we weren't showing the
used arguments like we had previously in some cases. In deciding how to
solve this, I went with the simplest route for now and removed it as the
usage likely doesn't add much context to help people solve their
problem, more so the recommendation for help. We'll see how the
feedback is on this and adjust.
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 inspired by cargo which allows you to run `cargo test --test`
and it will list the possible tests (obviously we can't support that atm
because that requires a lot of runtime processing). When we do have a
static list of possible values, we can at least show those.
Fixes#3320
This is prep for moving the derive tests. Besides organizing the test
folder for each API, this should reduce link time at the cost of
re-compiling more when a test changes.
