This is inspired by cargo which allows you to run `cargo test --test`
and it will list the possible tests (obviously we can't support that atm
because that requires a lot of runtime processing). When we do have a
static list of possible values, we can at least show those.
Fixes#3320
For some errors, we use the unroll logic to get the list of required
arguments. The usage then does the same, but without a matcher. This
was causing the lists to not match.
As a side effect, this fixed an ordering issue where we were putting the
present arg after the not-present arg. I assume its because we ended up
reporting the items twice but the first time is correctly ordered and
gets precedence.
This was split out of #3020
In clap2, `ArgMatches.args` was public but hidden. We made it private
in clap3, giving us more implementation flexibility but many people
relied on it, like to short-circuit defaulting, providing their own
`ArgRequiredElseHelp`, etc.
The main problem was how to expose this
- If we think of `ArgMatches` as a container (a DAG), should we have an
`is_empty` and what all is included in that, like subcommands?
- If we focus on only args, what term how do we refer to this to convey
the right intent?
In the end, I realized that this aligns most with our existing
`is_present` check and reporting if args are present fits the best
within the existing API.
I looked into also exposing iterating over the args (`present_arg_ids`)
but we have no way to expose the Id. The Id is currently private and if
we made it public, it can't be used to access any arg because it can't
implement `Key`.
This supersedes #3265
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).
