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.
2902: Minor cosmetic: Place default/env/… on separate lines for multiline help output r=pksunkara a=jcaesar
Co-authored-by: Julius Michaelis <glitter@liftm.de>
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.
Before, when `flatten`ing, the struct you flattened in could set the
help heading for all the following arguments. Now, we scope each
`flatten` to not do that.
I had originally intended to bake this into the initial / final methods
but that would have required some re-work to allow capturing state
between them that seemed unnecessary.
Fixes#2803
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).
Our goal is to not panic inside of the macro (e.g. #2255). Currently,
we `.unwrap()` everywhere except when turning an `ArgMatches` into an
`enum`. To handle `flatten`, we walk through each `flatten`ed enum to
see if it can be instantiated. We don't want to mix this up with any of
the other eror cases (including further nested versions of this).
If we went straight to `Result<T>`, we'd have to differentiate this case
through the `ErrorKind` and `map_err` it in all other cases to prevent
it from bubbling up and confusing us.
Alternatively, we could do a more complicated type `Result<Option<T>>`
where the `Option` exists purely for this case and we can use type
checking to make sure we properly turn the `None`s into errors when
needed.
Or we can bypass all of this and just ask the `flatten`ed` subcommand if
it supports the current command.
- `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
We normally set all app attributes at the end. This can be changed but
will require some work to ensure
- Top-level item's doc cmment ins our over flattened
- We still support `Args` / `Subcommand` be used to initialize an `App` when
creating a subcommand
In the mean time, this special cases `help_heading` to happen first.
We'll need this special casing anyways to address #2803 since we'll need
to capture the old help heading before addings args and then restore it
after. I guess we could unconditionally do that but its extra work /
boilerplate for when people have to dig into their what the derives do.
Fixes#2785
When working on #2803, I noticed a disprecancy in the augment
behavior between `Arg`s and `Subcommand`s that makes it so `Arg`s can't
be flattened with the update functionality.
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>
