Commit graph

49 commits

Author SHA1 Message Date
Ed Page
ccf35ff70c fix!: Replace min_values (total) with number_of_values (per occurrence) 2022-07-28 17:13:41 -05:00
Ed Page
41535d5c46 feat: Extend number_of_values to support min/max per occurrence 2022-07-28 16:52:25 -05:00
Ed Page
355a8ff90c fix!: number_of_values doesn't always imply multiple_values(true)
With `number_of_values` being per-occurrence now, its doesn't make sense
for `number_of_values(0)` to set `takes_value(true)` or for
`number_of_values(1)` to set `multiple_values(true)`.

In addition, an assert is made if the user works around this
2022-07-28 14:40:58 -05:00
Ed Page
5f20fe1930 docs: Shift focus from takes_value to actions 2022-07-26 14:50:51 -05:00
Ed Page
11076a5c70 fix(help)!: Make DeriveDisplayOrder the default, removing it
Force sorting with `next_display_order(None)`

Fixes #2808
2022-07-22 15:52:03 -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
36dcb05d96 fix!: Change arg! to use ArgAction
Fixes #3795
2022-07-22 13:24:40 -05:00
Ed Page
0d459128d7 fix(error)!: Merge UnrecognizedSubcommand into InvalidSubcommand
Fixes #3676
2022-07-22 12:12:35 -05:00
Ed Page
01a3ea425f fix!: Remove unstable-v4 feature gate 2022-07-22 11:34:06 -05:00
Ed Page
9caec5a52d fix(parser): Deprecate ArgMatches::is_present 2022-06-10 14:21:25 -05:00
Ed Page
10bb9abb1a fix(assert): Reference help_expected 2022-06-08 12:06:15 -05:00
Ed Page
14a62e11fd fix(parser): Deprecate multiple_occurrences
Fixes #3772
2022-06-08 09:54:23 -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
256643f8d3 fix: Deprecate possible_values 2022-05-25 12:57:11 -05:00
Ed Page
089f96eb87 fix(help): Disallow too many value names (unstable)
I can't think of a case for this or a way to render it.

Fixes #2695
2022-05-06 13:54:07 -05:00
Ed Page
70c29e3dd8 fix(help): Use '...' when not enough value names supplied 2022-05-06 13:33:17 -05:00
Ed Page
16791ab0a7 test(help): Update for display name change 2022-05-04 20:46:49 -05:00
Ed Page
c7ff695581 fix(help): Don't wrap URLs
Confusingly, there are two similar but slightly different settings in
`textwrap`.  We need both set.

Fixes #3222
2022-05-04 16:00:08 -05:00
Ed Page
3cfea3223b fix(help): Offer a html_template variable for display name
This is a step towards #992.  When help renders the application name, it
uses the `bin` template variable which is just the `bin` name with
spaces converted to ` `.  While having `app.exe sub` makes sense,
`app.exe-sub` does not.

To get around needing this for usage, we've created a `display_name`
field that is fairly similar but
- The root name is the `name` and not `bin_name`
- We always join with `-`

This means that the derived `bin_name` will only show up in usage.

For now, the default template has not been updated as that is a minor
compatibility change and should be in a minor release, at least.  I was
worried this would be a full breaking change.  The main case I was
worried about was cargo subcommands but our tests show they should just
work.
2022-05-03 14:34:47 -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
ccf8634c19 fix(help): Provide correct context for help subcmd errors 2022-04-29 20:25:05 -05:00
Ed Page
1452c1e42b fix(help): Help subcommands usage includes requires arguments 2022-04-29 20:16:19 -05:00
Ed Page
37ebb71806 fix(help): write_help usage includes required arguments 2022-04-29 20:15:54 -05:00
Ed Page
2edc1a2bdf test(help): Verify showing of required attributes 2022-04-29 15:46:15 -05:00
Ed Page
7cdce9cabe refactor(test): Use snapbox's diffs 2022-04-29 15:32:25 -05:00
Ed Page
8f182067e3 feat(clap): Publicly expose Command::build
`Command::_build_all` started as an internal function for
`clap_complete` as a stopgap until #2911.  Overtime, we've been finding
more cases where this function needs to be called, so now we're going to
fully embrace it until #2911 so people aren't scrared off by the hidden
implementation from using it.

This was inspired by #3602

Comptibility: Though this adds a deprecation which we general reserve
for minor or major versions, this is enough of a corner case that I'm
fine doing this in a patch release.
2022-04-19 10:13:43 -05:00
Roland Fredenhagen
33949ce4de
feat(help): Show PossibleValue help in --help (#3503)
`-h` (short help) still shows the same.

This gates it behind an `unstable-v4` feature flag to avoid disrupting users who set the help without knowing where all it shows up (particularly derive users where `ArgEnum` is automatically extracting the help).

Fixes #3312
2022-03-02 09:15:28 -06:00
Ed Page
e8010e79a9 refactor: Update app variables to cmd 2022-02-14 15:55:56 -06:00
Ed Page
c4144d7d6c docs: Update App references to Command 2022-02-14 15:33:49 -06:00
Ed Page
d3f5d7ce34 fix: Clarify Arg/ArgGroup id's role
This adjusts names.  Adjusting the derive naming (and re-naming) is left
to #2475.

Fixes #3335
2022-02-11 14:11:50 -06:00
Ed Page
272f840178 feat: Replace core set of AppSettings with functions
This is a part of #2717

Some settings didn't get getters because
- They are transient parse settings (e.g. ignore errors)
- They get propagated to args and should be checked there

`is_allow_hyphen_values_set` is a curious case.  In some cases, we only
check the app and not an arg.  This seems suspicious.
2022-02-11 12:35:09 -06:00
Ed Page
9bd7060089 fix: Deprecate various APIs
- ArgSettings are part of #2717
- Errors are part of #2628
- `help_heading` is part of #1807 and #1553
- Some misc parts are for API consistency
2022-02-10 19:37:47 -06:00
Ed Page
47d76742eb feat: Add Arg getters for all settings
This is prep for #2717
2022-02-10 10:18:41 -06:00
Ed Page
6c60b79d21 fix(assert): Provide next steps for '-h' conflicts
For now, we are going to provide a better debug assert in this case.
Resolving #3405 is the better long term route.

Fixes #3403
2022-02-08 18:56:14 -06:00
Ed Page
0aabcd70c1 test: Ensure we can avoid a short on help 2022-02-08 18:51:51 -06:00
Ed Page
c00f71ec4a feat: Add App::next_help_heading
This clarifies the intent and prepares for other functions doing the
same, like `next_display_order`.  This will then open us to name
`subcommand_help_heading` and `display_order` similar.

The deprecation is waiting on 3.1.

This is part of #1807 and #1553.
2022-02-07 19:19:01 -06:00
Ed Page
b538a43961 refactor(error): Switch to error::ErrorKind 2022-02-02 15:41:24 -06:00
Ed Page
4538d618a7 refactor: Migrate off of .kind 2022-02-01 11:27:08 -06:00
Peter Grayson
7eea7d27ad
fix(help): Optional arg values in brackets
When an Arg uses .min_values(0), that arg's value(s) are effectively
optional. This is conventionaly denoted in help messages by wrapping the
arg's values in square brackets. For example:

    --foo[=value]
    --bar [value]

This kind of argument can be seen in the wild in many git commands; e.g.
git-status(1).

Signed-off-by: Peter Grayson <pete@jpgrayson.net>
2022-01-26 12:03:23 -05:00
Ed Page
38e6952d46 fix: Don't panic when propagating
I thought I was adding a test in #3305.  Maybe I considered the
clap_complete changes sufficient for this.  Doing more `debug_assert`s
would be good also.

Unsetting `PropagateVersion` helps in some cases but we need to unset it
globally to override the global propagation.

Fixes #3310
2022-01-18 14:38:58 -06:00
Ed Page
e5fbdc9b95 Revert "Remove {n} support"
This reverts commit 333b993481.

PR #1810's motivation was effectively "this is redundant with `\n`".
That is a fine motivation.  Unfortunately, we don't have a way to force
a hard break in `clap_derive`.  #2389 should help with this eventually
but we shouldn't hold up 3.0 to get that ready.  So in the mean time, we
are restoring `{n}`.

We have #3230 for tracking the re-removal of it.
2021-12-30 11:44:45 -06:00
Ed Page
9c6c0174d2 test: Show more detailed failures 2021-12-27 13:57:38 -06:00
Ed Page
bfc486501a test: Panic, rather than exit, on error
Working on a fix for #3217 and can't see what is failing because the
test process exits.
2021-12-27 12:56:15 -06:00
Ed Page
318b7859dc fix(help): Don't infer long help from subcommands
Fixes #3193
2021-12-17 09:25:00 -06:00
Ed Page
9e64387ef0 revert(help): Partial revert of 3c049b4
The extra whitespace was targeted at machine processing for a subset of
users for a subset of runs of CLIs.  On the other hand, there is a lot
of concern over the extra verbose output.

A user can set the help template for man, if desired.  They can even do
something (env? feature flag?) to make it only run when doing man
generation.  We also have #3174 in the works.

So let's focus on the end-user reading `--help`.  People wanting to use
`help2man` have workarounds to do what they need.

Fixes #3096
2021-12-15 10:36:59 -06:00
Ed Page
19ed78c64f fix(help): Don't commit to '--help' that doesn't work
We have two ways of fixing this
- Making `--help` work
- Don't put `--help` in the help output

For now, I went with the latter.  I tried to make it clear what the
actual requirement is so we can pivot if needed.

Fixes #2892

This happens to also fix the interaction of `DisableHelpFlag` with the
help subcommand and complcations.  I've added a test to help catch if we
break this by changing how we fixed the original issue.

Fixes #2724

These issues were reported against clap3.  I've not tried to reproduce
these in clap2 to see if they should show up in the release notes.
2021-12-13 15:59:14 -06:00
Ed Page
2eb69def4e fix(error): Ensure trailing newline without help
Fixes #2787
2021-12-13 13:09:48 -06:00
Ed Page
045bf99ae0 test: Consolidate builder tests
This is prep for moving the derive tests.  Besides organizing the test
folder for each API, this should reduce link time at the cost of
re-compiling more when a test changes.
2021-11-30 10:07:05 -06:00
Renamed from tests/help.rs (Browse further)