Adding in a `StructOpt` derive with `structopt` attributes, with
deprecation notices. Unofrtunately, not as many deprecation warnings as
I would like. Apparently, you can't do them for a `use` of a derive? I
also wanted to inject code that would trigger a deprecation notice for
attributes but that would require enough of a refactor that I didn't
consider it worth it. We are at least providing a transition window
even if it means we'll have to remvoe it next major release without a
deprecation warning.
This creates distinct tutorial examples from complex feature examples
(more how-tos). Both sets are getting builder / derive versions (at
least the critical ones).
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.
This both distances itself from our 'require' terminology and aligns
itself with `Option::expect`, making it more likely for people to guess
the intended behavior.
This ports our example testing over to [trycmd](https://docs.rs/) so
we can:
- More thoroughly test our examples
- Provide always-up-to-date example usage
The old way of testing automatically picked up examples. This new way
requires we have a `.md` file that uses the example in some way.
Notes:
- Moved overall example description to the `.md` file
- I added cross-linking between related examples
- `14_groups` had a redundant paragraph (twice talked about "one and
only one"
This is intended to replace the runtime usage parser and is not meant to
be a complete API in of itself, like `clap_app!`. What is in scope is
everything that visually makes sense as in a usage string (see
[docopt](http://docopt.org/) for inspiration). General setting of
attributes is out of scope.
This deviates from both `clap_app` and the runtime usage parser
- `clap_app` supported multiple values but has a bug because we made
`Arg::value_name` non-appending, so we aren't supporting this yet
- We do not yet support optional flags that take a value
- In both, `...` is multiple occurrences and values while its only
multiple occurrences for us
- We explicitly support optional values for flags
- Unlike `clap_app`, our name is optional
- Unlike runtime usage parser, our name syntax is simpler
- Unlike runtime usage parser, our name syntax does not allow modifiers
Its more limited than I would like. Hopefully some people better with
macros can expand the feature set and turn more runtime errors into
compile-time errors.
This is to prepare for deprecating the runtime usage parser (#8).
Since usage parser and yaml are on the way to being deprecated (#8, #9),
doing a rename also seems excessive, so rolling it back.
Past relevant PRs:
- clap-rs/clap#1157
- clap-rs/clap#1257
This reverts commits 24cb8b1..d0abb37 from clap-rs/clap#1840
This is part of #16. clap-rs/clap#1840 wasn't the right call but we
don't have time to make the decision now, so instead of having one
option and changing it in 4.0, this reverts back to clap2 behavior.
This feature is too immature at this stage in the release. See
clap-rs/clap Issue 3020 when bringing this feature back.
This reverts commit 301c6f765a.
This reverts commit 43a4c90c86.
This reverts commit 4e29777b21.
This reverts commit 69957c4ddd.
This reverts commit bdb1d324a5.
This reverts commit b102da0cd2.
This reverts commit 72429be14e.
This reverts commit 0b7def675b.
This reverts commit b86aa631be.
This reverts commit 6b458c602d.
In #2851, we moved color from an AppSetting to function (with some
tweaks in #2907). When doing this, we documented `App::color` to be
equivalent of `App::global_settings(Color...)` but never actually
propagated it.
We are now propagating it. A test is added to ensure that no matter
how we store the color choice, we continue to propagate it. This
required exposing `App::get_color`.
The tests are using `to_string` which maps to `Display::fmt` and the
`Colorizer` version is colorless. To get color, it is only supported
with `print()` which has to go to stdout / stderr and can't be directed
to an arbitrary stream.
Though we store a lot of values as `&'help str`, we return them as
`&'self str`, making it so they can not be used programmatically as part
of a `App::mut_arg` call.
This loosens the lifetimes so they can be used with `App::mut_arg`.
This also includes a test simulating the desired workflow described in #2966
I skipped `get_all_aliases`. I ran into problems with lifetimes with
`all_subcommand_names` and didn't quickly resolve it. Rather than hold
this up, I punted on it for now.
We'll have to tighten these back up with #1041 but that will also enable
turning them into owned strings, so this will still be possible after
that issue is resolved, just the calls will be slightly different.
When supporting multiple occurrences for positional arguments in #2804,
I added some tests to cover this but apparently simpler cases fail
despite those more complicated cases being tested.
This adds more multiple-occurrences tests for positional arguments,
fixes them, and in general equates multiple values with occurrences for
positional arguments as part of #2692. There are a couple more points
for consideration for #2692 for us to decide on once this unblocks them
(usage special case in #2977 and how subcommand help should be handled).
I fully admit I have not fully quantified the impact of all of these
changes and am heavily relying on the quality of our tests to carry this
forward.
In looking at multiple occurrences and values for issues like #2692, I
noticed that `...` can mean both multiple values and multiple
occurrences, like before we split them.
Pros
- No syntax change with clap3
Cons
- All the reasons we split `multiple` into two
Uncertain
- I originally started this as part of another branch but I lost track
if something depended on this. I'll have to do more digging
BREAKING CHANGE: If `--opt [val]...` was meant for
- only multiple occurrences, see `[opt]... --opt [val]`
- both multiple occurrences and values, see `[opt]... --opt [val]...`
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).
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>
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.
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
