Commit graph

58 commits

Author SHA1 Message Date
Ed Page
56fe5e0ec0 fix!: Remove unstable-replace feature flag
This has been implemented for 3 years without much traction for
finishing it up.

The subcommand use case can be worked around by creating `Command`s that
just include the relevant logic, very similar to the default subcommand
examples in `git` / `git-derive`.

Using this for flags is covered by #4793.

Without `unstable-replace` being enabled, this still cut 5 KiB from
`cargo bloat --release --example git`.

Closes #2836
Closes #2011
2023-03-28 00:26:45 -05:00
Ed Page
fa60e723fc fix(error): Give more idea why we are suggesting an arg
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
2023-03-27 20:45:27 -05:00
Ed Page
234d5f91d1 fix(error): Change from neutral 'note' to helpful 'tip'
This also has the advantage of aligning with `error:`

This is a small part of #4638
2023-03-27 20:45:11 -05:00
Cornelius Roemer
5dcc5c9509 fix: Add plural s in suggestions
Old: `note: subcommand 'test', 'temp' exist`
New: `note: subcommands 'test', 'temp' exist`
Fixes #4666
2023-01-23 22:16:50 +01:00
Ed Page
162a556dba fix(error): Try to soften unexpected argument/value errors
Adding "found" might seem minor but I feel it has a slight softening on the message.  It also maintains scanability as it is at the end and short.

As this is a one-off message change and not a styling issue to be consistent with, I think this is safe to put in a patch release.
2023-01-13 21:29:49 -06:00
Ed Page
762b06fba4 fix(error): Try to polish/clarify messages
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.
2023-01-06 17:01:36 -06:00
Ed Page
68a7740fdc fix(error): Match rustc for giving more information 2023-01-03 13:22:35 -06:00
Ed Page
c2efb60a5f fix(error): Lowercase the start of error messages
This matches the rustc error style
2023-01-03 13:17:46 -06:00
Ed Page
e7d58b3daf
Merge pull request #4385 from epage/errors
fix(error): Be consistent with rustc diagnostic guidelines
2023-01-03 12:54:16 -06:00
Ed Page
36bc641648 fix(help): Remove extraneous text from built-ins
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
2023-01-03 11:02:26 -06:00
Ed Page
623ccbc152 style: Make clippy happy 2022-11-24 08:05:21 -06:00
Ed Page
f1ffc63a79 fix(error): Be consistent with rustc diagnostic guidelines
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
2022-10-13 14:01:49 -05:00
Ed Page
a4bcba6840 fix(error): Consistently indent suggestions 2022-10-13 12:10:13 -05:00
Ed Page
a964f45b1b fix(error): Properly quote, color subcommand suggestions 2022-10-13 10:51:17 -05:00
Ed Page
f8053fcedb fix(error): Don't suggest '--' when it doesn't help 2022-10-13 10:17:11 -05:00
Ed Page
5399f49572 fix(error): Quote literals consistently 2022-09-29 08:54:03 -05:00
Ed Page
4280fdfcbd fix(help): Replace help writers with renderers
The writer is less convenient and isn't offering any performance
benefits of avoidign the extra allocations, so let's render instead.

This supersedes #3874

Fixes #3873
2022-09-22 09:54:19 -05:00
Ed Page
652e71d616 fix(help)!: Provide styled usage to user
This will open us up to providing the user with access to the styled
version in the future.
2022-09-22 09:54:19 -05:00
Ed Page
2d83a7b12e feat(error): Break out error-context feature flag
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.
2022-09-19 10:23:55 -05:00
Ed Page
0184cf008a fix(parser): Quote the suggested help
We do it elsewhere but here it is only distinguished coloring.

Inspired by #4218
2022-09-15 16:24:59 -05:00
Ed Page
c9eef44213 fix: Make arg!(--flag <value>) optional by default
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
2022-09-12 17:10:01 -05:00
Ed Page
c90a4eabae fix(help): Make output more dense
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
2022-09-07 17:13:55 -05:00
Ed Page
9a645d2d19 fix(help): Collapse usage to one line
After looking at more examples, I've become more attached to this
briefer format.

Part of #4132
2022-09-07 11:03:57 -05:00
Ed Page
671914b590 fix(error): Make whitespace consistent with self/help
Sometimes errors would use a tab, sometimes four spaces.  This makes it
always four spaces and shares a definition with help.
2022-08-31 16:02:14 -05:00
Ed Page
65b5b5f7bf fix(help): Remove name/version/author from help
This is to help shorten it and polish it by removing redundant
information.

This is a part of #4132
2022-08-31 15:06:15 -05:00
Ed Page
42c943844c fix(help): Use Command in place of Subcommand
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
2022-08-31 08:53:10 -05:00
Ed Page
02db3043e2 fix(help): Consistently use [] for positionals
In the usaeg we use `[]` but in the arg list we use `<>`.
2022-08-29 15:34:30 -05:00
Ed Page
83d6add9aa fix(help): Shift focus to subcommands, when present
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.
2022-08-26 10:59:40 -05:00
Ed Page
9b23a09f7a fix(help): Don't rely on ALL CAPS for headers
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.
2022-08-26 10:21:18 -05:00
Ed Page
85f541d789 fix: Switch to owned types
Impact:
- Binary size: 556.6 KiB to 578.4 KiB
- build time: 6.4950 us (7% slower)
- parse time: 7.7256 us
- parse sc time: 8.1580 us (5% faster)

Fixes #1041
Fixes #2150
2022-08-22 14:55:55 -05:00
Ed Page
2de59195aa fix!: Prefer IntoIterator over &[]
The main breakinge change cases:
- `&[char]`: now requires removing `&`
- All other non-ID `&[_]`: hopefully #1041 will make these non-breaking

Fixes #2870
2022-08-15 13:26:17 -05:00
Ed Page
ba15b5f430 fix!: Rename Arg::number_of_values to Arg::num_args 2022-08-03 14:45:47 -05:00
Ed Page
470531b515 fix!: Replace multiple_values with number_of_values
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.
2022-08-01 15:50:23 -05:00
Ed Page
5f20fe1930 docs: Shift focus from takes_value to actions 2022-07-26 14:50:51 -05:00
Ed Page
13e672fb90 fix(assert)!: Prevent repeated subcommand names
Fixes #3888
2022-07-25 13:46:18 -05:00
Ed Page
389ff4ff21 fix(help): Subcommand display order respects Command::next_display_order
Previous behavior:
- They'd be sorted by default
- They'd derive display order if `DeriveDisplayOrder` was set
  - This could be set recursively
- The initial display order value for subcommands was 0

New behavior:
- Sorted order is derived by default
- Sorting is turned on by `cmd.next_display_order(None)`
  - This is not recursive, it must be set on each level
- The display order incrementing is mixed with arguments
  - This does make it slightly more difficult to predict
2022-07-22 15:03:16 -05:00
Ed Page
0d459128d7 fix(error)!: Merge UnrecognizedSubcommand into InvalidSubcommand
Fixes #3676
2022-07-22 12:12:35 -05:00
Ed Page
9caec5a52d fix(parser): Deprecate ArgMatches::is_present 2022-06-10 14:21:25 -05:00
Ed Page
4a9c4dee64 refactor(test): Make it easier to fork tests 2022-06-07 16:21:12 -05:00
Ed Page
a712adefcd fix(parser): Deprecate value_of and friends 2022-05-25 12:57:11 -05:00
Ed Page
686b0379ce feat(multicall): Stablize multicall
`multicall` allows you to have one binary expose itself as multiple
programs, like busybox does.  This also works well for user clap for
parsing REPLs.

Fixes #2861
2022-05-20 12:20:40 -05:00
Ed Page
1a2b7acd60 test(multicall): Conditionalize suggestion-related case
This impacts the error code (#3676) and the error body and without
suggestions, its redundant.
2022-05-20 12:20:40 -05:00
Ed Page
af3b789e4c fix(multicall): Consistently skip multicall bin in help 2022-05-02 11:50:30 -05:00
Ed Page
8cd59fa4e5 fix(multicall): More consistent whitespace in errors 2022-05-02 11:01:14 -05:00
Ed Page
f9fdb99ee8 fix(multicall): Disallow args on multicall binary
Set expectations for how this can be used and to make sure the right
errors are given.
2022-05-02 09:33:09 -05:00
Ed Page
ce727f1951 fix(error): Render actual usage for unrecognized subcommands
For some reason this code path diverged and manually constructed a
usage, not following any of our patterns for doing so.
2022-05-02 09:25:44 -05:00
Ed Page
5cd1a4070b fix(multicall): Show subcommands are required 2022-05-02 09:13:44 -05:00
Ed Page
414ae57a2a fix(multicall): Improve bad multicall binary error
By removing all arguments, we've switched from an "unrecognized
argument" error to a "unrecognized subcommand" error.  While the wording
has room for improvement, its at least progress on #2862.
2022-05-02 09:12:12 -05:00
Ed Page
7cdce9cabe refactor(test): Use snapbox's diffs 2022-04-29 15:32:25 -05:00
Ed Page
e8010e79a9 refactor: Update app variables to cmd 2022-02-14 15:55:56 -06:00