This adds feature parity for mangen with the standard help output. Users
will now see the list of possible values for value arguments.
One change that was made to make this possible was adding the method
`get_possible_values` to the public API for an arg. I tried to think of
a way to get around this, but because this is the interface that the
help generation uses, and it is part of the crate public interface
I thing adding it as a part of the public API might be for the best.
fixes: #3861
The performance gains of writing directly to the writer are not worth
the complexity. Output is not in our performance hot path.
Binary size went from 565.7 KiB to 562.2 KiB
Extend Command::override_usage() doc string to describe how to format
multiple usage lines to be compatible with clap's default help formatter.
Relates-to: #3413
The binary size and performance difference is enough to make it
configurable.
Code size:
- default: 565.7 KiB
- perf: 578.5 KiB
Build time:
- default: 9.1706 us
- perf: 7.0479 us
Parse time:
- default: 12.673 us
- perf: 8.1708 us
Parse with subcommand time:
- default: 12.112 us
- perf: 7.9874 us
Another step towards #1041
This isn't the long term type for `PossibleValue::help`, I just wanted
to get the lifetime out of the way first before figuring out how help
will work.
While `TypedValueParser` will generally make it easier to reuse value
parsers, this was particularly written for flags. Besides having a
concrete API to document, an advantage over `fn(&str) -> Result<bool, E>`
value parsers is you get all of the benefits of the existing value
parsers for environment variable parsing.
The main breakinge change cases:
- `&[char]`: now requires removing `&`
- All other non-ID `&[_]`: hopefully #1041 will make these non-breaking
Fixes#2870
For now, we are focusing only on iterating over the argument ids and not
the values.
This provides a building block for more obscure use cases like iterating
over argument values, in order. We are not providing it out of the box
at the moment both to not overly incentize a less common case, because
it would abstract away a performance hit, and because we want to let
people experiment with this and if a common path emerges we can consider
it then if there is enough users.
Fixes#1206
