`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.
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.
Originally, clap carried a lifetime parameter. When moving away from
that, we took the approach that dynamically generated strings are always
supported and `&'static str` was just an optimization.
The problem is the code size increase from this is dramatic. So we're
taking the opposite approach and making dynamic formatting opt-in under
the `string` feature flag. When deciding on an implementation, I
favored the faster one rather than the one with smaller code size since
small code size can be gotten through other means.
Before: 567.2 KiB, 15.975 µs
After: 541.1 KiB, 9.7855 µs
With `string`: 576.6 KiB, 13.016 µs
This makes us accept `str` and not do any allocations at the cost of
panicing if unsupported which I think fits our overall story in trying
to catch development-time errors.
Originally, I saw the ideal as the parent command being isolated from
`#[clap(flatte)]` especially after all of the doc comment
leakage issues. We scaled that back to just `next_help_heading` because
of the issues with settling on a policy and maintenance to cover
everything. When doing `next_display_order`, we decided it would mess
things up too much to isolate it.
With #1807, we instead have been moving towards setting
`#[command(next_help_heading)]` anywhere, we just need to finish working
out how it should work.
Just having `--help` or `--version` can make us get invalid args instead
of invalid subcommands. It doesn't make sense to do this unless
positionals are used. Even then it might not make sense but this is at
least a step in the right direction.
Unsure how I feel about this being backported to clap 3. It most likely
would be fine?
This was noticed while looking into #4218
Since the `name` is changed to be the package name, we can't use it as
(1) its not as predictable and (2) it can lead to conflicts if a
`Parser` is flattened into a `Parser`
This was ported over from the usage parser which modeled after docopt.
We just never got around to implementing the rest of the syntax.
However, when considering this as a standalone feature, an
`arg!(--flag <value>)`, outside of other context, should be optional.
This is how the help would display it.
Fixes#4206
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
If short help is too long for the terminal, clap will automatically
switch to next line help. As part of next line help for longs, we add a
blank line between args. This helps make the args clearer when dealing
with multiple paragraphs. However, its not as much needed for short and
subcommands (always short), so now short matches subcommands.
This was inspired by #3300 and a part of #4132
This makes it match up with `Command::allow_hyphen_values` which was the
guiding factor for what the behavior should be.
This supersedes #4039Fixes#3880Fixes#1538
This has been a bit out of place being on the command. Now its clearer
what the user intends to be the trailing var arg and it is more likely
to be discovered.
The builder function was deprecated in v3 and removed in v4 but the
derive masked that, so we're still adapting things but now with a path
towards removal.
In reviewing CLIs for #4132, I found some were providing helps on `-h`
vs `--help` and figured that could be built directly into clap. I had
considered not making this hint automatic but I figured the overhead of
checking if long exists wouldn't be too bad. The code exists (no binary
size increase) and just a simple iteration is probably not too slow
compared to everything else.
Fixes#1015
This ensures we don't end up with accidental leading or trailing
newlines due to help template variables not being used when a section is
empty.
This is prep for removing name/version from the default template and is
part of #4132
In switching to title case for help headings (#4123), it caused me to
look at "subcommand" in a fresh light. I can't quite put my finger on
it but "Subcommand" looks a bit sloppy. I also have recently been
surveying other CLIs and they just use "command" as well.
All of them are commands anyways, just some are children of others
(subcommands) while others are not (root or top-level commands, or just
command). Context is good enough for clarifying subcommands from root
commands.
This is part of #4132
The setting was added to resolve#769. The reason it was optional is out
of concern for applications with a lot of positional arguments. I think
those cases are rare enough that we should just push people to override
the usage. Positional arguments are generally important enough, even if
optional, to show.
As a side effect, this fixed some bugs with
`dont_collapse_args_in_usage` where it would repeat an argument in a
smart usage.
As a side effect, smart usage now shows `--` when it should
