The styling of usage has changed in #4188 such that the usage string is on
the same line as the "Usage:" title. Previously, the usage went on the line
below the title. As such, the rules have changed for how to make a
multiline usage format correctly.
These updated rules achieve the following output for the documented
example:
Usage: myapp -X [-a] [-b] <file>
myapp -Y [-c] <file1> <file2>
myapp -Z [-d|-e]
Relates-to: #4132
If users don't want `wrap_help` feature, they can put newlines in where
needed. Seems odd to support wrapping when the wrap size is fixed. For
those hard coding the lines, this will save them a decent amount of
size.
This gives users the control over where clap outputs while still getting
colors. For users who want to support old windows versions, check out
`fwdansi` crate.
The writer is less convenient and isn't offering any performance
benefits of avoidign the extra allocations, so let's render instead.
This supersedes #3874Fixes#3873
Things that tripped up a user
- Derive reference was misunderstood to say that the only alternative to
the built-in value parser behavior was to implement
`ValueParserFactory`
- We now delegate to `value_parser!`s docs any talk of integrating
into it (it should have been a subbullet of "not present" anyways)
- `value_parser!` relies too much on the example to demonstrate behavior
when the user will likely make the determination of whether its
relevant before then
- We are now more upfront what type mappings are supported
- Too many steps to find all information
- For example, a user needs to look at `TypedValueParser`
implementations, `ValueParserFactory` implementations, and `From<T>
for ValueParser` implementations to understand what all can be used
- We are now more upfront with a lot of this information at the entry
points the user is most likely to look at
In addition, I did an audit of the docs to make sure they were updated
for us only supporting the new behavior and all of the new APIs.
See https://www.reddit.com/r/rust/comments/xjlie4/preannouncing_clap_40_a_rust_cli_argument_parser/ip9kzf1/
`clap::Error::raw` was producing ambiguity errors with a default generic
parameter on `clap::error::Error` (which `clap::Error` is a re-export
of).
I tried making `clap::Error` a type alias with a default generic
parameter but that ran into an ambiguity error with `map_err`.
So I'm going ahead and hard coding `clap::Error`. We don't expect
people to change this all that often.
