While I'm unsure how much type specialization we should do, we
intentionally have the `arg_enum` attribute for doing special behavior
based on it, so let's take advantage of it.
Fixes#3185
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
The main care about is that when we override a `flatten` / `subcommand`
doc comment in a parent container, that we make sure we take nothing
from the child container, rather than implicitly taking one `about` ut
not `long_about`.
To do this, and to play the most safe with long help detection, we reset
`long_about` to default when there is no doc comment body to use for
`long_about`.
Fixes#2983
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.
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
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.
