If a value must be reused later then it's better to pass it as a &str
instead of cloning it, that means the clone happens in a central
place (inside the method).
By never passing a &String those instances of the method are not monomorphized.
Saves only 0.5K, maybe not worth it in hindsight.
This is an initial implementation with plenty of room to grow, including
- Allowing pulling out a subset of the generated man page for greater customization
- Subcommand handling
- Extra sections
- Consolidate argument formatter after #2914Fixes#552
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>
We were only tracking the last value source (default, env, cli, etc).
This works for args because they only come from one source. Groups
however can come from multiple sources and this was making us treat a
group with a default value as being completely from defaults despite
some values maybe being from the commandline.
We now track the highest precedence value for a group.
Fixes#3330
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
We might be able to handle version/help before propagation but I didn't
want to hold up this fix for that to happen and increase the risk
associated with this fix.
Fixes#3298
This will help prevent issues from being deployed to users like in #3281
I do not consider this a breaking change because any normal operation
will assert anyways.
Cargo is an example of a user that heavily relied on using undefined
names because there is a lot of code sharing between commands. This
allows a path forward for those users that is just painful enough to
discourage overly relying on it in the future :).
`clap_generate` originally intended to be "generate anything". With
`fig`, we already broke one part out. With #3174's man support, we are
also looking at keeping it separate:
- More freedom to iterate on the API
- Uniqueness (and potential weight) of its dependencies
- man generation is normally more for distribution while completions are
a mix of being distributed with the app or the app generating the
completions (which will be exacerbated if we move most completion
parsing logic to be in Rust)
So `clap_generate` is having a lot more limited of a role than the
original name conveys. I worry the generic name will be a hindrance to
people discovering and using it (yes, documentation can help but there
are limits).
I hesitated because we are on the verge of releasing 3.0. However, doing
it even later will be even more disruptive because more people will be
using it (crates.io lists ~70 people using `clap_generate`).
To ease things, we are still releasing `clap_generate` as a wrapper
around `clap_complete`.
When we got #3193, we decided in #3196 that `--help` will give a summary
for other commands (`subcmd --help` in this case) but not show the long
version of the output for that other command.
Now with #3215, I think the case is similar for `--help` not showing the
long version but instead preferring the short version and encouraging
people to run `--version`.
Originally. clap only showed the short version or nothing. This was
changed in #2369 without fanfare to prefer the long version over short.
Now are we preferring short version over the long version always, just
like all other help.
Fixes#3215
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.
This allows two overriding args to interact with each other mid-line.
This was broken in 7673dfc / #1154. Before that, we duplicated the override
logic in several places.
Now we plug into the start of a new arg which allows us to do this
incrementally without making the logic complex or inefficient, thanks to
prior refactors.
Fixes#3217
This will have a slight performance hit as `AllArgsOverrideSelf` will
allocate a single-element `Vec` per `Arg`. This can be lessened for
positional and multiple occurrences by shifting those checks up into the
propagation check.
Long term, I'd like to see all of the `Arg`-in-`App` settings switch to
this which will make it easier for callers, like completions and man
pages, to figure out whats going on without duplicating the logic.
Short term, this is motivated by wanting to change the override logic to
accomodated interleaved overrides from #3217. Moving this logic will
make it easier to change the override logic.
This is the logical order people think in terms of (`--foo` comes before
`val` in `--foo val`). This also opens things up for using occurrence
incrementing as a place to handle occurrence transitions, like
overrides.
This makes some naming more explicit and allows us to increment
occurrences before adding values (which is the logical mental order and
allows other improvements).
We were storing data off into the struct, obscuring the direct
relationship between gathering and validating conflicts.
With this, not as much code needs to deal with mutable data
And other derive tweaks. I'm mixed on how far to go, including
- Linking to the derive reference
- Showing how to use each trait with both the derive and builder APIs
For now, this is an improvement.
Confirmed this works with [`argfile`](https://docs.rs/argfile/latest/argfile/)
And then running in clap
```
$ RUSTDOCFLAGS="--cfg docsrs" cargo +nightly doc --all-features
```
They now show up!
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
I dislike the inconsistency with only a few fields providing this (this
and `help_heading`) but this is to address a specific bug. We need to
visit this, along with iterators (#2870) and string handling (#2150).
`Arg` came along for the ride because the derive logic is applied to
both. `PossibleValue` didn't need it because we filter out `long_help`.
BREAKING CHANGE: We changed the signatures for `App::about`,
`App::long_about`, `Arg::help`, and `Arg::long_help` from accepting
anything `Into<&str>` to `&str`.
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.
Without being a breaking change.
This seems minor enough that we can break this during the release
candidates. For `ValueHint`, the completion scripts are 99% of who
should be `match`ing it. `AppSettings` as undocumented variants that
people shouldn't use.
BREAKING CHANGE: `clap::{ValueHint, ErrorKind, AppSettings,
ArgSettings}` are now `non_exhaustive`.
I'm assuming we won't have a negative performance impact by removing
`impl Copy for Id` because the compiler would inline the `clone()`s and
turn them into copies.
Addresses problems from #3164
The executable suffix is unconditionally stripped off the file path
so that the file name matches subcommands names
without having to add the EXE suffix on different platforms.
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
