This is meant to lower the chance of confusion with cases like #2714 and #1586.
This is not meant to be exhaustive, looked at the mentioned cases in
that issue and pattern matched on other ones mentioning "is present".
When I'm making changes, I frequently have to touch every error
function. This creates a more standard builder API so we can more
easily add or modify fields without having to update every case.
While in some cases "branches-sharing-code" might catch bugs, it overall encourages a form
of DRY that leads to bad code. In this specific case, it is relying on
the implementation detail of the formatting of each branch being the
same. If the `'` wasn't part of it, I could see it being about a shared
`?` to go with the shared start of the question.
In considering potential work for #2683, I realized we might need a type to carry data for
each of the `multiple_values`. `ArgValue` works both for that and for
possible values, so we need to come up with a better name for one or
both. Changing `ArgValue`s name now would be ideal since its new in
clap3 and by renaming it, we can reduce churn for users.
While thinking about this, I realized I regularly get these mixed
up, so renaming `ArgValue` to `PossibleValue` I think will help clear
things up, regardless of #2683.
This gives users the basic error template for quick and dirty messages.
In addition to the lack of customization, they are not given anything to help
them with coloring or for programmayic use (info, source).
This is something I've wanted many times for one-off validation that
can't be expressed with clap's validation or it just wasn't worth
the hoops. The more pressing need is for #2255, I need `clap_derive`
to be able to create error messages and `Error::with_description` seemed
too disjoint from the rest of the clap experience that it seemed like
users would immediately create issues about it showing up.
With this available, I've gone ahead and deprecated
`Error::with_description` (added in 58512f2fc), assuming this will be
sufficient for users needs (or they can use IO Errors as a back door).
I did so according to the pattern in #2718 despite us not being fully
resolved on that approach yet.
2817: Add support for Multicall executables as subcommands with a Multicall setting r=pksunkara a=fishface60
Co-authored-by: Richard Maw <richard.maw@gmail.com>
Who knew people need to ask `help` for how to use `help`?
While auditing `MultpleValues`, I saw commented out code. Looks
its commit (f230cfedc) was part of a large refactor and updating that
part fell through the cracks. Just simply updating it didn't quite get
it to work. The advantage of this approach is it gets us closer to how
clap works on its own.
In clap 2.33.3, `cmd help help` looks like
```
myapp-help
Prints this message or the help of the given subcommand(s)
USAGE:
test-clap help [subcommand]...
ARGS:
<subcommand>... The subcommand whose help message to display
```
But clap3 master looks like:
```
myapp
USAGE:
myapp [SUBCOMMAND]
OPTIONS:
-h, --help Print custom help about text
SUBCOMMANDS:
help Print this message or the help of the given subcommand(s)
subcmd
```
This change improves it to:
```
myapp-help
Print this message or the help of the given subcommand(s)
USAGE:
myapp help [SUBCOMMAND]...
ARGS:
<SUBCOMMAND>... The subcommand whose help message to display
OPTIONS:
-h, --help Print custom help about text
```
We still have global arguments showing up (like `-h`) that will error but its
an improvement! In general, I'd like to find a way to leverage clap's stanard
behavior for implementing this so we don't have to worry about any of these
corner cases in the future.
Note: compared to clap2, I changed `<subcommand>` to `<SUBCOMMAND>` because I
believe the standard convention is for value names to be all caps (e.g.
`clap_derive` has been updated to default to that).
- `App::with_defaults` was not included since that has been deprecated
since 2.14
- `App::args_from_usage` does not have a close enough parallel in the
new API, as far as I could tell
- `ArgMatches::usage` cannot have a thin wrapper around
`App::generate_usage`.
- `App::write_*`: getting lazy, didn't seem like high value functions
- Any `Settings` (some things need to be figured out here)
This is a part of #2617
There were fewer occasions than I expected where the use of
`multiple_values` was superfluous and we could instead use the more
predictable `multiple_occurrences`.
In terms of the remaining `multiple` split work, #1772 will take care of the derive
behavior and #2692 will resolve any remaining issues with values vs
occurrences in positional arguments.
Fixes#2816
This is inline with all of our other help-related functions that return
strings.
This is a part of #2164
BREAKING CHANEG: `App::generate_usage` (added in v3) ->
`App::render_usage`.
PR #1211 originally added `help_heading` with the current priority
(`App::help_heading` wins).
In #1958, the author had proposed to change this
> Note that I made the existing arg's heading a priority over the one in App::help_heading
This was reverted on reviewer request because
> Thanks for the priority explanation. Yes, please make the app's help
> heading a priority. I can see how it would be useful when people might
> want to reuse args.
Re-using args is an important use case but this makes life difficult
for anyone using `help_heading` with `clap_derive` because the user
can only call `App::help_heading` once per struct. Derive users can't get
per-field granularity with `App::help_heading` like the builder API.
As a bonus, I think this will be the least surpising to users. Users
generally expect the more generic specification (App) to be overridden by the
more specific specification (Arg). Honestly, I had thought this PR is
how `help_heading` worked until I dug into the code with #2872.
In the argument re-use cases, a workaround is for the reusable arguments
to **not** set their help_heading and require the caller to set it as
needed.
Fixes#2873
2871: Better positional checks r=epage a=pksunkara
2872: Iterate on help_heading to prepare for derive support r=pksunkara a=epage
2876: Generate/bash: add possible_values to completion when available r=pksunkara a=nstinus
Co-authored-by: Pavan Kumar Sunkara <pavan.sss1991@gmail.com>
Co-authored-by: Ed Page <eopage@gmail.com>
Co-authored-by: Nicolas Stinus <nstinus@latourtrading.com>
Now that `help_heading`'s API is loosened with an `Into<Option>`, we can
more easily allow the existing yaml functionality to work. This still
misses the ability to set the help heading to nothing.
This reverts commit 9031deb806.
This makes `Some()` optional. This change was made with the derive API
in mind where you are unlikely to clear directly but we still need the
ability to clear.
In part, this is just fixing a papercut where someone will try to use
the API in the same way between the two but it fails and they'll have to
consult the docs / rust-analyzer.
The bigger reason is that this is more derive-friendly for dealing with #2803
since we will be able to just ask for the current help heading
before running the app and then restore it back, rather than having to
conditionalize the revert logic.
Problems with this
- It is incompatible with the new signature planned for
`App::help_heading`
- It is missing from `Arg` which is where this is more needed
- All this can do is set a global help heading because you can duplicate
keys (`clap_derive` has a similar problem but it at least has `flatten`)
For those that want the original behavior, you can usxe
`arg.help_heading(Some("FLAGS"))` on your flags. Limitations:
- This will not give you a special sort order
- This will not get a `[FLAGS]` added to usage
For templates, we removed `{unified}` and `{flags}`. To help people
catch these, a debug_assert was added.
I'm unsure but I think there might be a change in behavior in calcuating
when to show `[OPTION]` in usage. The old code only looked at
`required` while flags looked only at arg groups. We now look at both.
Ideally we'd add these in `_build` and remove special casing for
no-groups except in the sort order of groups. I feel like thats best
left for later.
This also reduced the scope of `App`s public API.
`get_*_with_no_heading` seemed a bit specialized to be in the public
API. #2853 looks at splitting it out into its own PR.
BREAKING CHANGE: Multiple
- `UnifiedHelpMessage` removed
- `{flags}` and `{unified}` are removed and will assert when present.
- `get_*_with_no_heading` removed
Fixes#2807
`App::get_matches` lazily post-processes `App`s and `Arg`s so we don't
do it to subcommands that are never run (downside being people have to
exercise their full app to get debug_asserts).
`clap_generate` was only post-processing the top-level `App` and `Arg`s,
ignoring the sub-commands. In #2858, we noticed that `--version` was
being left in the completions instead of being removed during the
`_build` step. We would also have an incorrect `num_vals` and a host of
other problems.
This change adds a `App::_build_all` function for `clap_generate` to use
to eagerly build everything. By having it there, we make sure
everywhere that needs eager building, gets it (like some tests).
In `clap_generate::utils`, we add a unit test to ensure the subcommand's
`--version` was removed.
For some other tests specifying `.version()`, I added
`AppSettings::PropagateVersion` to make it behave more consistently.
The places I didn't were generally where the version was conditionally
set.
For `clap_generate/tests/generate_completions.rs`, I had to adjust the
`conflicts_with` because the subcommand was inheriting the argument with
it defined *but* the subcommand did not have the argument, tripping up a
debug assert.
Fixes#2860
This partially reverts commit 7f627fc.
This reverts the error code change but not the `ErrorKind` change. I
was mixed on whether we should do that or not. The benefit is it makes
it so people can check the Kind for cases like #2021. On the other
hand, it doesn't seem that hard to re-implement the feature.
Fixes#2767
