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.
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
Making this plural can go either way as
- Clarify it is plural
- This is all really to simulate actually doing subcommands and you only
do one at a time
For now, I lean towards clarifying it is plural
I also tweaked the message to be more consistent with how `--help` and
`-h` describe themselves.
Fixes#4342
In clap v4, we changed the padding from 4 to 2 but we didn't update our
calculation for when to switch to next-line-help as it was a magic
number (we tried to catch all of these).
When updating the tests, we also missed that a test was being wrapped
too narrowly
This was found while discussing #3300
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.
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
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.
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 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.
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
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.
In surveying various tools and CLI parsers, I noticed they list the
subcommands first. This puts an emphasis on them which makes sense
because that is most likely what an end user is supposed to pass in
next.
Listing them last aligns with the usage order but it probably doesn't
outweigh the value of getting a user moving forward.
I see them fulfilling two roles
- A form of bolding
- As a callback to their placeholder in usage
However, it is a bit of an unpolished look and no other CLI seems to do
it. This looks a bit more proefessional. We have colored help for
formatting and I think the sections relation to usage will be clear
enough.
The main breakinge change cases:
- `&[char]`: now requires removing `&`
- All other non-ID `&[_]`: hopefully #1041 will make these non-breaking
Fixes#2870
This is a step towards #1041
- `ArgGroup` no longer takes a lifetime
- One less field type needs a lifetime
For now, we are using a more brute force type (`String`) so we can
establish performance base lines. I was torn on whether to use `&str`
everywhere or make an `IdRef`. The latter would add a lot of noise that
I'm concerned about, so i left it simple for now. `IdRef` would help to
communicate the types involved though.
Speaking of communicating types, I'm also torn on whether we should use
`Id` for all strings or if we should have `Id`, `Name`, etc types to
avoid people mixing and matching.
This added 18.7 KB.
Compared to `HEAD~` on `06_rustup`:
- build: 6.23us -> 7.41us
- parse: 8.17us -> 9.36us
- parse_sc: 7.65us -> 9.29us
This is a part of #2870 and is prep for #1041
Oddly enough, this dropped the binary size by 200 Bytes
Compared to `HEAD~` on `06_rustup`:
- build: 6.21us -> 6.23us
- parse: 7.55us -> 8.17us
- parse_sc: 7.95us -> 7.65us
Documenting the existing behavior is challenging which suggests it can
cause user confusion. So long as its not too hard to explicitly
specify actions, we should just do it.
Fixes#4057
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
In clap v3, `require_value_delimiter` activated an alternative parse
mode where
- `multiple_values` meant "multiple values within a single arg"
- `number_of_values` having no parse impact, only validation impact
- `value_names` being delimited values
For unbounded `number_of_values`, this is exactly what `value_delimiter`
provides. The only value is if someone wanted `value_name` to be
`<file1>,<file2>,...` which can be useful and we might look into adding
back in.
Alternatively, this could be used for cases like key-value pairs but
that has issues like not allowing the delimiter in the value which might
be ok in some cases but not others. We already instead document that
people should instead use `ValueParser` for this case.
In removing this, we remove points of confusion at how the different
multiple values and delimited value calls interact with each other. I
know I would set `require_value_delimiter(true).multiple_values(true)`
when it turns out all I needed was `value_delimiter(',')`.
This also reduces the API surface area which makes it easier to discover
what features we do provide.
While this isn't big, this is also yet another small step towards
reducing binary size and compile times.
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.
