This will make it faster for someone to figure out what is going on
without dropping down to `RUST_BACKTRRACE=1` by giving them the arg
*and* telling them which function *they* called was involved.
Now that we use options, we can rely on that, instead of sentinels, for
detecting a default and overriding only a default.
Noticed this as part of looking at #1807.
These exist pretty much just for YAML (#3087). If anyone else is
building on these, it has a limited shelf-life anyways because of #2717.
BREAKING CHANGE: `FromStr` for settings requires the `yaml` feature.
- Some still referenced the clapng issue number
- Some YAML ones were missed in the formatting clean up
- I never updated the usage ones with the formatting clean up
Before, we limited it to the `doc` feature because of how extensive the
README was. It has since scaled back, so we can be more selective with
what features enable it.
This contains two types of re-ordering:
- Internal, putting the focus of each file first.
- Public, re-arranging items and grouping impl blocks to try to better
organize the documentation and find related items.
The main weakness of the docs work is in `Args`. Its just a mess. In
particular, we should probably link the simple casesm like `required` to
the advanced impl block.
Fixes#55
Until we have a modular help generator that can be configured and/or
authored by the users themselves as part of #2914, we will provide the
flexibility of turning off colored help messages but still wanting
colored error messages.
This flexibility was available before #2845 and @dbrgn immediately
noticed it and requested it back to which I agree. This was also
suggested by Josh in
[here](https://github.com/clap-rs/clap/issues/2806#issuecomment-933877438)
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.
The intention had been to that people setting this would now set
nothing. Unfortunately, clap2 had `EmptyValues` as the default, so
people were more likely to unset it, making this not work out.
These were broken in #17 and #38 when renaming `hidden` to `hide`. These
weren't caught because we test with `--all-targets` which is mutually
exclusive with `--doc`.
I've been finding I've been setting `AppSettings` without it which is
likely leading to bugs. This tries to raise the visibility by using it
based on the setting being used and not whether the application needs
it.
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 makes it easier for us to compose. Before, we had to infer things
like "bold" based on the color. Now we just say "error" and get all of
the formatting specific to that.
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.
This reverts commit 6898fbde33.
PR #2144 added the `license` field but no consumer has been added since
the (like Issue #1768). Since this is not ready yet, I am pulling it
from the 3.0 release.
So far, our main route for pulling a feature from the release has
been to put it behind a `unstable-*` feature flag and to create a
stablization tracking issue. I chose to instead remove the feature
because a write-only field with no effect does not provide values for
people to use in as an early access and so doesn't outweight the cost of
the extra documentation noise and code noise it creates. Additionally,
keeping an `unstable-` feature around when it has such an unknown path
(and time table) to stalbization feels like it violates YAGNI. I'm
uncertain how much of this feature we can implement and not create a
legal trap for users because the crate's license is insufficient for the
final artifact's license. I feel our stabliazation process sshould be
about iteration and collecting user feedback which this doesn't line up
with.
When someone is ready to tackle #1768, it will be easy to revert this
commit and pick up the work again.
Fixes#3001
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`.
In #2985, I noticed #2834 was incomplete, there were case-insensitive
comparisons we were doing without being unicode aware (when compile
options are set).
The downside is that each comparison will require a UTF-8 validation.
These seem to be in more of corners of the API, rather than in common
calls in common usages, so hopefully that isn't too much of a problem.
Similar to #2977, this changes positional argument `<subcmd>` in
`help <subcmd>` to be multiple occurrences, from being multiple values.
This is what identified the usage generation bug fixed in #2978 and was
isolated into the test case `positional_multiple_occurrences_is_dotted`.
This is part of #2692 where we re-evaluate the usage of multiple values
for positionals now that we accept multiple occurrences.
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.
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.
I noticed this while investigating #2692. Since we are making
multiple-occurrences a thing for positional arguments, this allows us to
remove a special case.
Another way to look at this is that we should make the default whatever
we do for dervies (#1772). I'm going to propose we make the derive
always turn `Vec<i32>` into multiple occurences and not multiple values
(with users being able to change it through attributes), but that is an
in-work proposal and not decided yet.
BREAKING CHANGE: `Arg::from(...)` will now use `multiple_occurrences`
for a positional `...`, rather than `multiple_values`.
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]...`
Besides being more explicit / clear, this makes it easier to experiment
with tweaking the logic and keeping the test updates minimal, so the
change of behavior stands out more.
Wow, I'm having a hard time summarizing this for the summary.
When we code-gen Settings using `impl_settings`, we have no control over
whether one instance of a Settings will use some or all functions. I
have a fix that removes the one `ArgSettings::unset`, causing warnings
for `ArgSettings` despite needing it for `AppSettings`.
So I'm making it less dependent on how each instantiation uses it.
Technically, this also fixes a bug with an extra newline when building
with `debug` but that is a pretty minor cosmetic issue. It is unclear
if `backtrace` has a trailing newline or not, so I left that as-is.
Before, `Error::exit` didn't provide `WaitOnError`, requiring each call
site to duplicate half of `Error::exit`s behavior to get it. This
hadn't been done for errors raised by derive-generated code. Ideally,
these errors never happen but all the same, having this consistent would
be good.
This moves knowledge of `WaitOnError` to `Error` (including through
`Error::format`) so `Error::exit` can wait. Now all of the callers to
`.exit` get a consistent experience without duplication.
While #2938 made a lot of `Error` fields optional for less churn-heavy
modifications, I made this new field required to minimize the risk of an
raise site forgetting to set it.
If the user prints a raw error, it may include color even if the user
turned it off at runtime. Now we'll be more conservative and never show
color for raw errors.
This is a follow up to #2943; apparently I had missed some cases.
We prefer Settings to always be off by default, so when we change a
default, we have to rename.
This adds back in the now-default settings with deprecation messages to
help the user know how things now work.
Unfortunately, there is no way to notify the user that the default they
relied on has changed. This also doesn't help us when the change in
behavior is more than just an inverting, like `InvalidUtf8` or when a
setting mapped to multiple bits.
This partiall reverts commit efeb02cd34,
bringing back the `AppSettins::Color*` and making them the backing store
for `App::color`, to help ease the transition from clap2->3.
Once we remove these deprecated settings, we might want to keep this
backing store to save on memory.
This is a part of #2617
This brings back the old name of settings, just deprecated. Since they
all map to the same bits in the bit field, this should work for
`setting` and `is_set`. The only thing this lacks is being able to do
equality across variants, whcih seems like a minority case.
Removed settings have some extra care abouts that we'll need to look
into separately.
This is a part of #2617
2926: Put `grouped_values_of` behind a feature gate r=pksunkara a=epage
2948: docs(generate): Move derive example to generate r=pksunkara a=epage
Co-authored-by: Ed Page <eopage@gmail.com>
If the user prints a raw error, it may include color even if the user
turned it off at runtime. Now we'll be more conservative and never show
color for raw errors.
While `App::error` is what most people will need, `clap_derive` needs to
handle when the site raising the error doesn't have access to the `App`
and needs to defer that to later.
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
