Commit graph

506 commits

Author SHA1 Message Date
Ed Page
7836beda05 chore: Release 2022-06-14 07:02:40 -05:00
Ed Page
0a529c14cc fix(derive): Switch default actions/parsers for unstable-v4 2022-06-13 18:59:58 -05:00
Ed Page
9910b1477b fix(derive): Find a better target for validator deprecation warnings
Putting it on the doc comment is weird.  We are now putting it on the
field which is a slight improvement.  This better conveys "this is
auto-generated".

No test was added because the use case that I know of for exposing this
is short lived.
2022-06-13 16:14:05 -05:00
Ed Page
0096a4e881 fix(derive): Set the span for code generation 2022-06-13 15:19:23 -05:00
Ed Page
9757e38d05 refactor(derive): Be consistent in ValueEnum term 2022-06-13 12:52:31 -05:00
Ed Page
650a29c18b chore: Release 2022-06-13 09:37:47 -05:00
Ed Page
4e56acffce chore: Release 2022-06-13 09:31:29 -05:00
Ed Page
9caec5a52d fix(parser): Deprecate ArgMatches::is_present 2022-06-10 14:21:25 -05:00
Ed Page
9e38353442 fix(derive): Clarify ArgEnum as ValueEnum
We aren't enumerating arguments but values for an argument, so the name
should reflect that.

This will be important as part of #1807 when we have more specific
attribute names.
2022-06-08 11:14:09 -05:00
Ed Page
19d8ca807f fix(derive): Transition off of multiple_occurrences
For programs opting into the clap v4 behavior (with `action` or
`value_parser` attributes), we'll no longer generate a
`multiple_occurrences(true)` call in preparation for deprecating
`multiple_occurrences`.  See #3772.
2022-06-07 15:38:14 -05:00
Ed Page
efc1520223 perf(derive): Cache positional status 2022-06-07 15:05:11 -05:00
Ed Page
647896d929 feat(derive): Expose control over Actions
This is the derive support for #3774 (see also #3775, #3777)

This combined with `value_parser` replaces `parser`.  The main
frustration with this is that `ArgAction::Count` (the replacement for
`parse(from_occurrences)` must be a `u64`.  We could come up with a
magic attribute that is meant to be the value parser's parsed type.  We
could then use `TryFrom` to convert the parsed type to the user's type
to allow more.  That is an exercise for the future.  Alternatively, we
have #3792.

Prep for this included
- #3782
- #3783
- #3786
- #3789
- #3793
2022-06-06 11:35:07 -05:00
Ed Page
552e6feb3f fix(derive): Adjust precedence for flag/occurrence logic 2022-06-02 16:56:12 -05:00
Ed Page
f4004b653b refactor(derive): Give new-style highest precedence
This exposed a potential bug but I figure it isn't worth fixing without
actions.
2022-06-02 16:46:50 -05:00
Ed Page
ebf9c16a23 refactor(derive): Clarify functions role 2022-06-02 16:46:50 -05:00
Ed Page
cccc88bcc2 fix(derive): Fix typo in error messages 2022-06-02 16:46:50 -05:00
Ed Page
e5f2911603 fix(derive): Reference correct path 2022-06-02 16:46:50 -05:00
Ed Page
773ba94c4e refactor(derive): Merge handling of bool/from_flag
This will make it easier to divide off parser logic for adding in
actions.

This does mean we can't provide error reporting on bad values with
`bool` but
- We should have also been doing that for `from_flag`
- We'll be dropping this soon in clap4 anyways
2022-06-02 13:01:59 -05:00
Ed Page
e5ead4ce49 refactor(derive): Default parser based on type 2022-06-02 11:50:45 -05:00
Ed Page
f61aad4b34 refactor(derive): Resolve value parsers earlier 2022-06-02 11:14:25 -05:00
Ed Page
96ac83e260 refactor(derive): Simplify needs for finding the inner type 2022-06-02 11:07:43 -05:00
Ed Page
bbab148289 fix(derive): Align value parser's type with occurrences_of 2022-06-01 11:21:34 -05:00
Ed Page
eda0ca54c1 fix(parser): Simplify the common getter API
Clap has focused on reporting development errors through assertions
rather than mixing user errors with development errors.  Sometimes,
developers need to handle things more flexibly so included in #3732 was
the reporting of value accessor failures as internal errors with a
distinct type.  I've been going back and forth on whether the extra
error pessimises the usability in the common case vs dealing with the
proliferation of different function combinations.  In working on
deprecating the `value_of` functions, I decided that it was going to be
worth duplicating so long as we can keep the documentation focused.
2022-05-25 10:50:42 -05:00
Ed Page
ed45de2f03 fix(parser): Clean up remove types
The remove functions no longer return `Arc` but the core type, at the
cost of requiring `Clone`.  I originally held off on this
in #3732 in the hope of gracefully transition the derive and requiring
`Clone` would have been a breaking change but when it came to #3734, I didn't
find a way to make it work without a breaking change, so I made it
opt-in.  This means I can force the `Clone` requirement now.

I added the requirement for `Clone` everywhere else in the hopes that in
the future, we can drop the `Arc` without a breaking change.
2022-05-24 16:25:07 -05:00
Ed Page
a997ee7e10 fix(derive): Improve where errors point 2022-05-24 14:53:08 -05:00
Ed Page
2fba6155ec refactor(derive): Separate concerns when removing 2022-05-20 19:27:52 -05:00
Ed Page
a35df14caf feat(derive): Opt-in to inferred value_parser 2022-05-20 19:25:20 -05:00
Ed Page
7845e604e7 perf(derive): Reuse allocations where possible
Only bothered to implement this for `value_parser` cases as `parse`
cases are going to be considered deprecated.
2022-05-20 15:44:19 -05:00
Ed Page
b52c7f115e feat(derive): Allow users to opt-in to ValueParser
For clap 3, its opt-in as a precaution against breaking
compatibility in some weird cases.

This does require the types to implement `Clone`.

Fixes #3734
Fixes #3496
Fixes #3589
2022-05-20 15:38:44 -05:00
Ed Page
0628d04174 perf(derive): Reuse allocations for external subcommands
In case the `ArgMatches` is cloned, this forces a constraint that the
underlying type impls `Clone` but that should be safe as we only support
`String` and `OsString`.
2022-05-20 12:02:31 -05:00
Ed Page
d61552a8b8 refactor(derive): Deconstruct arg matches into enums 2022-05-20 11:56:47 -05:00
Ed Page
18f295029f refactor(derive): Consistently handle sub matches 2022-05-20 11:10:26 -05:00
Ed Page
b817c2d2a9 refactor(derive): Separate sub flattening to avoid aliasing 2022-05-20 11:08:05 -05:00
Ed Page
5806e16dd4 refactor(derive): Don't alias arg matches
Right now, the aliasing is safe (the compiler says so!) but we're going
to be switching to a `&mut` and need to ensure we don't alias.
2022-05-18 09:38:38 -05:00
Ed Page
2abb6804d3 fix: Switch to 2021 edition 2022-05-18 10:35:30 -05:00
Ed Page
d827364ea9 style: Normalize manifests 2022-05-18 10:33:37 -05:00
Ed Page
272334b26a fix: List rust-version for all crates 2022-05-18 10:08:10 -05:00
Ed Page
d826ab9445 fix(derive): Move args to new 'get_one'/'get_many' API 2022-05-16 15:16:51 -05:00
Ed Page
72c44a32e5 fix(derive): Move subcommands to new 'get_many' API 2022-05-16 15:16:51 -05:00
Ed Page
524e36cf1a chore: Release 2022-05-10 15:29:16 -05:00
Ed Page
2e3540355a fix(derive): Don't change case of Arg id's (unstable)
This will make it easier to reference arguments with different
attributes.

Fixes #3282
2022-05-09 10:36:03 -05:00
Ed Page
65538e21a8 fix(derive): Detect escaped ambiguous subcommands (unstable) 2022-05-06 15:46:34 -05:00
Liu Dingming
1b63fbd6df feat(derive): Start unstable-v4 feature flag
This is split out of #3661 as several changes I'm working on need it.
2022-05-06 14:56:55 -05:00
Ed Page
c75d2642ef chore: Release 2022-03-31 12:22:40 -05:00
shir0kamii
fb4755d1c3 feat(derive): Don't abort when non-unit variant is skipped 2022-03-31 18:49:21 +02:00
shir0kamii
ee3d12ec56 fix(derive): Abort on non-unit variant 2022-03-30 03:49:14 +02:00
Ed Page
1e286f3dc2 chore: Release 2022-03-02 09:20:00 -06:00
Ed Page
bfeb751d0d chore: Ensure clap always uses latest clap_derive 2022-02-23 12:50:32 -06:00
Ed Page
20dc6673bc chore: Release 2022-02-23 09:39:40 -06:00
Ed Page
cb937641fa fix(derive): Allow other attributes with subcommand that has subcommands
This was overlooked when we added support for `#[clap(subcommand)]` to
variants.

Fixes #3504
2022-02-23 09:23:33 -06:00
Ed Page
e6729f96c3 chore: Release 2022-02-16 11:59:45 -06:00
Ed Page
ddac492302 fix: Rename IntoApp to CommandFactory
This is part of the `App` rename.

Previously, I was concerned about not being able to deprecate

For backwards compatibility, we still expose the `IntoApp` name.
2022-02-15 08:24:00 -06:00
Ed Page
c3fec1fa75 fix: Update derive->Command function name
No good solution for transitioning the trate name, unfortnately, since
we can't mark `use`s as deprecated (we can, it just does nothing).

I got rid of the `into` prefix because that implies a `self` parameter
that doesn't exist.
2022-02-14 16:04:10 -06:00
Ed Page
e8010e79a9 refactor: Update app variables to cmd 2022-02-14 15:55:56 -06:00
Ed Page
c4144d7d6c docs: Update App references to Command 2022-02-14 15:33:49 -06:00
Ed Page
4895a32e81 fix: Deprecate SubcommandRequiredElseHelp
Now that we can use `SubcommandRequired |
ArgRequiredElseHelp`, this setting offers little value but requires we
track required subcommands with two different settings.  Deprecating as
the cost is not worth the benefit anymore.

Issue #3280 will see the derive updated
2022-02-11 15:31:25 -06:00
Ed Page
85908ce039 refactor(derive): Remove redundant code paths
I'm assuming this is from when structopt always set author, version, and
about and you had to apply other attributes to remove them.
2022-02-11 13:19:14 -06:00
Ed Page
272f840178 feat: Replace core set of AppSettings with functions
This is a part of #2717

Some settings didn't get getters because
- They are transient parse settings (e.g. ignore errors)
- They get propagated to args and should be checked there

`is_allow_hyphen_values_set` is a curious case.  In some cases, we only
check the app and not an arg.  This seems suspicious.
2022-02-11 12:35:09 -06:00
Ed Page
5290f82133 feat: Override DeriveDisplayOrder behavior with App::next_display_order
For the derive API, you can only call `next_display_order` when dealing
with a flatten.  Until we offer app attributes on arguments, the user can workaround with
this no-op flattens.

This is a part of #1807
2022-02-07 19:19:11 -06:00
Ed Page
c00f71ec4a feat: Add App::next_help_heading
This clarifies the intent and prepares for other functions doing the
same, like `next_display_order`.  This will then open us to name
`subcommand_help_heading` and `display_order` similar.

The deprecation is waiting on 3.1.

This is part of #1807 and #1553.
2022-02-07 19:19:01 -06:00
Ed Page
dc035de409 chore: Release 2022-02-01 16:11:53 -06:00
Rob Donnelly
a19bca8a10 docs(error): Update link to explicit bool parser example 2022-01-31 21:58:54 -08:00
Ed Page
ea7699c11f chore: Release 2022-01-24 15:34:27 -06:00
omjadas
86c83d296f
feat: Add default_value_os_t (#3333)
The order of suffixes allows us to preserve the original builder function name.

This is a part of #2813
2022-01-24 15:32:21 -06:00
Ed Page
e5b06c3061 chore: Release 2022-01-24 10:54:50 -06:00
Ed Page
4c2d65e290 docs(derive): Have crate link out to specific docs 2022-01-18 19:41:29 -06:00
Ed Page
811fd6a04a chore: Release 2022-01-10 16:16:18 -06:00
Ed Page
c494da93ce chore: Share a tag between clap / clap_derive 2022-01-10 16:16:04 -06:00
Ed Page
3326a11be0 fix(derive): Don't assume use clap::ArgEnum
The error was when doing `#[clap(arg_enum, default_value_t = ...)]`.

Good example of why we should minimize `use`, at least in tests
(besides reducing merge conflicts, code churn, etc).
2022-01-10 15:41:58 -06:00
Ed Page
ef823bbeaf chore: Release 2022-01-05 16:28:24 -06:00
Noa
ffd991f0ae
chore: Fix clap_derive license headers 2022-01-04 14:25:48 -06:00
Ed Page
d9906eb150 chore: Release 2022-01-04 09:49:41 -06:00
Daniel Eades
2986a9eee0 style: remove unnecessary lazy evaluations 2022-01-04 09:20:17 -06:00
Daniel Eades
7f71d642cd style: prefer 'char' to 'str' for single character patterns 2022-01-04 09:20:08 -06:00
Ed Page
bcbe126b4d chore: Release 2022-01-03 18:53:28 -06:00
Ed Page
6b9ae5404c fix(derive): Don't enit warnings
We missed covering `Args` warnings when using struct variants.

Fixes #3245
2022-01-03 11:35:34 -06:00
Ed Page
42f6c72caa chore: Upgrade heck 2022-01-01 20:31:53 -06:00
Ed Page
c01ebbac17 chore: Release 2021-12-31 14:35:02 -06:00
Ed Page
bc951e4e53 chore: Release 2021-12-31 13:37:28 -06:00
Ed Page
8d73a0e80f chore: Release 2021-12-31 12:23:47 -06:00
Ed Page
2d7dc1ff8f chore: Release 2021-12-30 15:00:19 -06:00
Ed Page
ea02f6125d chore: Release 2021-12-30 14:28:32 -06:00
Ed Page
ff713d5ae5 chore: Release 2021-12-27 15:57:27 -06:00
Ed Page
8d94739de4 chore: Release 2021-12-23 14:28:46 -06:00
Ed Page
27893cfd9a chore: Release 2021-12-16 12:19:58 -06:00
Ed Page
c212402466 chore: Release 2021-12-16 09:33:06 -06:00
Ed Page
8924dd7a1e feat(derive): Don't require Display for default ArgEnum
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
2021-12-16 09:11:32 -06:00
Ed Page
1100f04b56 chore: Release 2021-12-15 11:02:40 -06:00
Ed Page
d55f040bbd fix(derive): Set both about/long_about with doc comments
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
2021-12-14 11:07:57 -06:00
Ed Page
7c10b5a9b4 fix(derive): Treat default_value_os like default_value
The test went from panicing to not-panicing

Fixes #3031
2021-12-13 16:25:49 -06:00
Ed Page
c3f8c8938f chore: Release 2021-12-10 15:25:23 -06:00
Ed Page
43d3ac37a6 fix(derive): Allow aliased Option with ArgEnum 2021-12-10 10:41:55 -06:00
Frankie Foston
1285c0f885 fix: unqualified result types causing compilation failures with derive implementations 2021-12-10 14:13:26 +00:00
Ed Page
ada95d6f3d chore: Release 2021-12-09 19:39:08 -06:00
Ed Page
3dec7df14f chore: Release 2021-12-09 07:00:33 -06:00
Ed Page
febf7c637e docs(derive): Note using fully-qualified path 2021-12-08 19:58:41 -06:00
Janik Rabe
7b1ea308a0 fix(derive): Use fully qualified types
This fixes `#[derive(Parser)]` when a custom `Result` type is in scope.
2021-12-08 21:07:49 +00:00
Ed Page
d444f46f92 chore: Release 2021-12-08 12:41:59 -06:00
Ed Page
cf623d9e53 fix(derive): Update structopt links
Fixes #1671
2021-12-08 11:28:25 -06:00
Ed Page
c807f892b1 chore: Configure release process
Experimenting with treating clap-derive and clap one and the same from
the release process perspective.  The completion generators are a bit
more independent.
2021-12-07 21:36:00 -06:00
Ed Page
093de2b83b docs: Add back in logo 2021-12-07 17:45:57 -06:00
Ed Page
98b899f978 docs: Expand child crate docs 2021-12-07 17:45:57 -06:00
Ed Page
ad797e70af docs: Remove reference to clap.rs 2021-12-06 20:56:47 -06:00
Ed Page
b2836c07a7 fix: Gracefully handle empty authors 2021-12-06 11:30:26 -06:00
Ed Page
f517c0ede1 docs: Remove author fields 2021-12-06 11:24:23 -06:00
Ed Page
f3268b0a4c chore: Remove clap dependency 2021-12-06 11:07:11 -06:00
Ed Page
1acc95ff55 docs: Make clap_derive reflect it not being user-facing 2021-12-06 11:06:34 -06:00
Ed Page
c23f9230d1 chore: Remove stale boiletplate 2021-12-06 11:04:41 -06:00
Ed Page
b46abb7236 docs: Re-order items in docs
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
2021-12-04 19:18:28 -06:00
Ed Page
500def4904 fix(derive): Smooth out transition for structopt
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.
2021-12-02 20:18:33 -06:00
Ed Page
64d052f8b8 fix: Remove untested IntoApp derive 2021-12-02 20:01:00 -06:00
Ed Page
befee6667b docs: Re-work examples
This creates distinct tutorial examples from complex feature examples
(more how-tos).  Both sets are getting builder / derive versions (at
least the critical ones).
2021-11-30 21:33:52 -06:00
Ed Page
b190a6a817 test: Consolidate clap tests
This reduces the need for us to have `clap` as a dependency in
`clap_derive`, preparing the way to fix #15.
2021-11-30 10:07:08 -06:00
Ed Page
54228ef7d7 docs: Prefer global_setting
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.
2021-11-29 16:10:54 -06:00
Ed Page
1cdb2250e8 fix(derive): Define multiple policy for Special Types
Before:
- `bool`: a flag
- `Option<_>`: not required
- `Option<Option<_>>` is not required and when it is present, the value
  is not required
- `Vec<_>`: multiple values, optional
- `Option<Vec<_>>`: multiple values, min values of 0, optional

After:
- `bool`: a flag
- `Option<_>`: not required
- `Option<Option<_>>` is not required and when it is present, the value
  is not required
- `Vec<_>`: multiple occurrences, optional
  - optional: `Vec` implies 0 or more, so should not imply required
- `Option<Vec<_>>`: multiple occurrences, optional
  - optional: Use over `Vec` to detect when no option being present when
    using multiple values

Motivations:

My priorities were:
1. Are we getting in the users way?
2. Does the API make sense?
3. Does the API encourage best practices?

I was originally concerned about the lack of composability with
`Option<Option<_>>` and `Option<Vec<_>>` (and eventually `Vec<Vec<_>>`).
It prescribes special meaning to each type depending on where it shows
up, rather than providing a single meaning for a type generally.  You
then can't do things like have `Option<_>` mean "required argument with
optional value" without hand constructing it.  However, in practice the
outer type correlates with the argument occurrence and the inner type
with the value.   It is rare to want the value behavior without also the
occurrence behavior.  So I figure it is probably fine as long as people
can set the flags to manually get the behavior they want.

`Vec<_>` implies multiple occurrences, rather than multiple values.
Anecdotally, whenever I've used the old `Arg::multiple`, I thought I was
getting `Arg::multiple_occurrences` only.  `Arg::multiple_values`,
without any bounds or delimiter requirement, can lead to a confusing
user experience and isn't a good default for these.  On top of that, if
someone does have an unbounded or a delimiter multiple values, they are
probably also using multiple occurrences.

`Vec<_>` is optional because a `Vec` implies 0 or more, so we stick to
the meaning of the rust type.  At least for me, I also rarely need a
required with multiple occurrences argument but more often need optional
with multiple occurrences.

`Option<Vec<_>>` ends up matching `Vec<_>` which can raise the question
of why have it.  Some users might prefer the type.  Otherwise, this is
so users can detect whether the argument is present or not when using
`min_values(0)`.  Rather than defining an entire policy around this and
having users customize it, or setting `min_values(0)` without the rest
of a default policy, this gives people a blank slate to work from.

Another design option would have been to not infer any special-type
settings if someone sets a handful of settings manually, which would
have avoided the confusion in Issue clap-rs/clap 2599 but I see that
being confusing (for someone who knows the default, they will be
expecting it to be additive; which flags disable inferred settings?) and
brittle (as flags are added or changed, how do we ensure we keep this
up?).

Tests were added to ensure we support people customizing the behavior to
match their needs.

This is not solving:
- `Vec<Vec<_>>`, see clap-rs/clap 2924
- `(T1, T2)`, `Vec<(T1, T2)>`, etc, see clap-rs/clap 1717
- `Vec<Option<_>>` and many other potential combinations

Fixes clap-rs/clap 1772
Fixes clap-rs/clap 2599
See also clap-rs/clap 2195
2021-11-29 13:16:12 -06:00
Ed Page
62d7a3a928 fix: Be consistent on hide/hidden
- `PossibleValue::hidden` -> `PossibleValue::hide` (new in clap3, no
  breakin change)

Fixes #33
2021-11-29 10:58:00 -06:00
Ed Page
57e5fc2b07 fix: Rename to Arg::ignore_case like ArgSettings
Fixes #32
2021-11-29 10:34:42 -06:00
Ed Page
eae3ffb599 docs: Emphasize Arg over ArgSettings 2021-11-29 09:54:04 -06:00
Ed Page
c15a0bf5b3 fix: Rename App's AllowLeadingHyphen to AllowHyphenValues
This aligns us with `Arg::allow_hyphen_values` in clap2.
2021-11-24 11:25:48 -06:00
Ed Page
7e899cd340 Revert "Deprecate Arg::help in favour of Arg::about"
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.
2021-11-18 12:25:49 -06:00
kuviman
aa6594b334 feat(derive): Generic support
This is a port of clap-rs/clap#3023
2021-11-17 15:33:59 -06:00
Ed Page
4479282b11 style: Address warnings 2021-11-17 14:23:32 -06:00
Ed Page
9167fdebf3 fix(derive): Don't emit warnings
Looks like this is coming from `update_from_arg_matches` where we do a
ladder of `if __clap_arg_matches.is_present(...)` that clippy wants to
be `else if`s.  While for human edited code, that does clarify intent,
for machine generated code that is rarely read, its a pain to do, so
silencing it.

Unfortunately, it isn't in a group we can overall silence.

Fixes #3017
2021-11-12 12:52:18 -06:00
Ed Page
78e4c90326 refactor(tests): Prepare for Special Type experiments
In experimenting on #1772, I want to write test cases for various
combinations of required or not, values vs occurrences, etc.  There
wasn't really a clear place to put these.

On top of that, I wanted there to be a clear place in the tests for
describing the behavior of special types, to make it easier to audit and
easier to see how a PR for #1772 changes things.

As part of this effort in organizing these tests, I reduced the number
of tests that use special types.  This better focuses these tests on the
cases they are intending to cover, rather than pulling in unrelated
features.  This makes it easier to audit special types and makes it so
failures give more focused results, making it easier to see what broke.
2021-11-04 13:12:01 -05:00
Ed Page
844251c478 test: Easier to test with minimal features
PR #2979 reduced what dependencies we push on users and made us one step
closer to being able to test more with fewer features.  Looks like I
also need to update `clap_derive`.  I verified locally that #2976 fails
with this.

`clap_derive` still needs `env` because of examples / tests that use it.
I feel like moving `clap_derive`s tests out to `clap` would be the way
to fix this.
2021-11-02 16:40:31 -05:00
Ed Page
a9c6a5b531 refactor(tests): Remove unnecessary color disabling
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.
2021-11-02 16:40:31 -05:00
Ed Page
4b7ed54d7e test(derive): Provide better error info
`Parser::parse_from` will call `exit` on failure and we don't just lose
backtrace information but we don't even know which of the tests running
in parallel panicked.  I ran into this when experimenting with
`clap_derive` and I couldn't tell what actually failed.

So let's switch to `Parse::try_parse_from`.

Errors went from:
```
test option_option ... ok
error: Found argument 'bar' which wasn't expected, or isn't valid in this context

USAGE:
    clap_derive [OPTIONS]

For more information try --help
error: test failed, to rerun pass '--test arg_enum'
```
To:
```
test option_option ... ok
test variant_with_defined_casing ... ok
test skip_variant ... ok
test default_value ... ok
test vector ... FAILED
test option_vector ... ok

failures:

---- vector stdout ----
thread 'vector' panicked at 'called `Result::unwrap()` on an `Err` value: Error { message: Formatted(Colorizer { use_stderr: true, color_when: Auto
, pieces: [("error:", Some(Red)), (" ", None), ("Found argument '", None), ("bar", Some(Yellow)), ("' which wasn't expected, or isn't valid in this
 context", None), ("\n\n", None), ("USAGE:\n    clap_derive [OPTIONS]", None), ("\n\nFor more information try ", None), ("--help", Some(Green)), ("
\n", None)] }), kind: UnknownArgument, info: ["bar"], source: None, backtrace: Backtrace }', clap_derive/tests/arg_enum.rs:388:56
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

failures:
    vector

test result: FAILED. 15 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

error: test failed, to rerun pass '--test arg_enum'
```
2021-10-30 10:00:34 -05:00
Ed Page
93c26dd420 test(derive): Verify derive-genned errors are formatted
This is to help verify behavior added in #2943.  We separated the error
raising site from the error formatting site and this verifies that the
formatting actually happens.
2021-10-29 16:09:07 -05:00
bors[bot]
a802662341
Merge #2952 #2953
2952: fix(derive): Don't duplicate subcommand aliases r=pksunkara a=epage



2953: docs(app): Correlate help_heading and subcommand_placeholder r=pksunkara a=epage



Co-authored-by: Ed Page <eopage@gmail.com>
2021-10-26 21:56:54 +00:00
Ed Page
d05622d015 fix(derive): Don't duplicate subcommand aliases
When an anonymous struct is inside of an enum, we end up applying the
App methods twice, once for the `augment_args` and once for variant.

This consolidates those calls.

Fixes #2898
2021-10-26 16:01:05 -05:00
bors[bot]
f9e074e554
Merge #2926 #2948
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>
2021-10-26 20:56:20 +00:00
Ed Page
a065702205 docs(generate): Move derive example to generate
From a users perspective, `clap_derive` is baked into `clap`.
`clap_generate is an add on to `clap`.  So it seems best to have all
`clap_generate` examples in `clap_generate` where a user will look for
them.

Fixes #2939
2021-10-26 14:26:50 -05:00
Ed Page
53e10b41e3 fix(derive)!: Error, don't panic!
The derive is generating `Error::raw` (from scratch or by converting
existing erors) and then the inherent `Parser` methods format them.

Fixes #2255
2021-10-26 14:26:50 -05:00
Ed Page
69a7b7133a fix(derive): Use variants help_heading
Due to a copy/paste bug, we were reading the `help_heading` for
Subcommands from the enum's attribute and not the variant's attribute.

It doesn't make sense for the outer command's help_heading to control
the subcommands help_heading.

This does raise an interesting question on inheriting / propagating help_heading,
which I originally wrote the tests for.  We'd first need to answer
whether it should be built-in to the builder or derive-specific.
2021-10-26 12:49:43 -05:00
Ed Page
5d036d4d34 fix(derive): Support arg_enum everywhere
In working on converting unwraps to errors, I noticed that we did not
spport `arg_enum` for  `Option<Option<_>>` and `Option<Vec<_>>`, so this
addresses that.

My main motivation was to consolidate and make the logic more
consistent, the bug fix just fell out of that work.
2021-10-25 14:12:08 -05:00
bors[bot]
d6462884ed
Merge #2941
2941: Fix a path incompatible with re-exports r=pksunkara a=epage



Co-authored-by: Ed Page <eopage@gmail.com>
2021-10-25 15:40:33 +00:00
Ed Page
345694fea8 fix(derive): Allow subcommands with re-exporting
Our approach to re-exporting is to not fully qualify symbols in `clap`.
This is a place where a leading `::` got introduced, so its being
removed.
2021-10-25 09:44:38 -05:00
Ed Page
92fea91dfe doc(derive): Note derive policies 2021-10-25 09:44:05 -05:00
Ed Page
ed987933cf test: Verify clap_derive README
Fixes #2920
2021-10-25 09:21:45 -05:00
Ed Page
e5f10c81bc feat(derive): Allow help_heading on flattening fields
Fixes #2928
2021-10-23 16:05:08 -05:00
Ed Page
3a697af253 fix(derive): Avoid name collisions with users
PR #2751 highlighted a problem we have where the variable names we use
could collide with users.  Rather than parse out when or not to use
special names, and worry about people keeping that up to date through
refactors, I globally renamed all variables by adding a `__clap_`
prefix, which looks like what serde does to solve this problem.

I audited the result with `cargo expand`.  I didn't add any tests
because any tests would be reactionary and would give us a false sense
of protection since any new code could hit this with anything we do.
Our best route for naming is consistency so people are likely to notice
and copy.

Fixes #2934
2021-10-23 12:55:30 -05:00
Jake Shadle
db2a25473a Fix packaging of LICENSE-* files 2021-10-21 14:57:49 +02:00
bors[bot]
c4dfb1aede
Merge #2916
2916: fix ArgEnum multiline doc comment r=epage a=marjakm



Co-authored-by: Mattis Marjak <mattis.marjak@gmail.com>
2021-10-19 17:06:14 +00:00
Mattis Marjak
cba7ba5369 fix ArgEnum multiline doc comment 2021-10-19 18:34:54 +03:00
Ed Page
9f12bfec47 fix!: Rename ArgValue to PossibleValue
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.
2021-10-19 10:10:37 -05:00
rhysd
012f318c97 feat(doc): Fix many typos in docs, comments and codes found by typos-cli 2021-10-19 10:38:22 +09:00
Pavan Kumar Sunkara
585e995811 Release 3.0.0-beta.5 2021-10-17 17:01:18 +01:00
Julius Michaelis
16af4f230a cosmetic: spec_vals on separate lines for long help 2021-10-17 22:43:06 +09:00
Ed Page
65e4bf232d fix(derive): Don't leak help headings
Before, when `flatten`ing, the struct you flattened in could set the
help heading for all the following arguments.  Now, we scope each
`flatten` to not do that.

I had originally intended to bake this into the initial / final methods
but that would have required some re-work to allow capturing state
between them that seemed unnecessary.

Fixes #2803
2021-10-16 11:21:16 -05:00
bors[bot]
6eacd8a747
Merge #2882
2882: fix(derive): Ensure App help_heading is applied r=epage a=epage



Co-authored-by: Ed Page <eopage@gmail.com>
2021-10-16 02:47:34 +00:00
Ed Page
7b56184175 refactor(derive): Simplify 'error' handling
Our goal is to not panic inside of the macro (e.g. #2255).  Currently,
we `.unwrap()` everywhere except when turning an `ArgMatches` into an
`enum`.  To handle `flatten`, we walk through each `flatten`ed enum to
see if it can be instantiated.  We don't want to mix this up with any of
the other eror cases (including further nested versions of this).

If we went straight to `Result<T>`, we'd have to differentiate this case
through the `ErrorKind` and `map_err` it in all other cases to prevent
it from bubbling up and confusing us.

Alternatively, we could do a more complicated type `Result<Option<T>>`
where the `Option` exists purely for this case and we can use type
checking to make sure we properly turn the `None`s into errors when
needed.

Or we can bypass all of this and just ask the `flatten`ed` subcommand if
it supports the current command.
2021-10-15 15:43:02 -05:00
Ed Page
22edac66d9 fix(derive): Ensure App help_heading is applied
We normally set all app attributes at the end.  This can be changed but
will require some work to ensure
- Top-level item's doc cmment ins our over flattened
- We still support `Args` / `Subcommand` be used to initialize an `App` when
  creating a subcommand

In the mean time, this special cases `help_heading` to happen first.
We'll need this special casing anyways to address #2803 since we'll need
to capture the old help heading before addings args and then restore it
after.  I guess we could unconditionally do that but its extra work /
boilerplate for when people have to dig into their what the derives do.

Fixes #2785
2021-10-15 14:19:16 -05:00
Ed Page
7b3d3401c0 fix(derive): Support 'update' with 'flatten'
When working on #2803, I noticed a disprecancy in the augment
behavior between `Arg`s and `Subcommand`s that makes it so `Arg`s can't
be flattened with the update functionality.
2021-10-15 14:19:16 -05:00
Ed Page
61c9e6265b fix(help)!: Merge OPTIONS / FLAGS default groups
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
2021-10-13 11:42:10 -05:00
Pavan Kumar Sunkara
efeb02cd34 fix!: Make color settings an enum 2021-10-13 13:54:44 +01:00
Ed Page
60c9c2e59a docs(derive): Use more-specific traits
This helps to raise visibility of the new derive traits.

I didn't touch ui tests because there were a lot and they didn't seem to
be as high value.
2021-10-12 07:51:11 -05:00
bors[bot]
74cbe0bf09
Merge #2721
2721: feat(generate): Give `Shell` superpowers to simplify getting started r=pksunkara a=epage



Co-authored-by: Ed Page <eopage@gmail.com>
2021-10-11 23:48:17 +00:00
Pavan Kumar Sunkara
685601e002 fix: Add test for flattening struct in enum 2021-10-11 21:54:44 +01:00
Ed Page
96f2343e1b feat(generate): 'impl Generator for Shell'
This includes updating the example but does not include improving the
jumping-off documentation.
2021-10-11 10:46:44 -05:00
Ed Page
1bbfd956aa test: Harden tests against trailing whitespace
In a follow up commit, my editor stripped trailing whitespace.  Rather
than have everyone fight this, let's not make a deal over the small
stuff.
2021-10-11 10:44:48 -05:00
Ed Page
35d53d9dcf feat(generate): 'impl ArgEnum for Shell'
These keeps `FromStr` for ease of use with `value_of_t`.

This includes adding test to make sure everything works as expected.
2021-10-11 10:44:48 -05:00
Ed Page
6dd9d467ce fix(help)!: Consoldiate color settings
A lot of users expected `color` feature flag and `ColorAuto` etc to
control all colors.  Having this extra flag around is easy to miss and
adds to our overall settings bloat, making it harder to find settings
people want.

This completely removes it, rather than make it deprecated like
functions in #2617, because there is extra work to mark things
deprecated as Settings and we should decide on our strategy first before
investing time in addressing that issue.

Fixes #2806
2021-10-11 09:01:13 -05:00
Ed Page
d840d5650e fix(derive)!: Rename Clap to Parser.
Before #2005, `Clap` was a special trait that derived all clap traits it
detected were relevant (including an enum getting both `ArgEnum`,
`Clap`, and `Subcommand`).  Now, we have elevated `Clap`, `Args`,
`Subcommand`, and `ArgEnum` to be user facing but the name `Clap` isn't
very descriptive.

This also helps further clarify the relationships so a crate providing
an item to be `#[clap(flatten)]` or `#[clap(subcommand)]` is more likely
to choose the needed trait to derive.

Also, my proposed fix fo #2785 includes making `App` attributes almost
exclusively for `Clap`.  Clarifying the names/roles will help
communicate this.

For prior discussion, see #2583
2021-10-09 20:12:03 -05:00
Kevin K
0eba8015e3
chore: silence warning in example code 2021-10-09 11:12:50 -04:00
Kevin K
0addd938a6
tests(Examples): fixes examples for no-auto generated version 2021-10-09 11:06:48 -04:00
bors[bot]
e3b23929b3
Merge #2823 #2824 #2827
2823: fix(derive): Subcommands not working within macro_rules r=epage a=epage



2824: docs(derive): Fix explanation on optional string list argument r=epage a=epage



2827: feat: Add backtraces to errors r=epage a=epage



Co-authored-by: Ed Page <eopage@gmail.com>
2021-10-07 18:49:59 +00:00
bors[bot]
6c2daef7a1
Merge #2821 #2822
2821: test(derive): Port structopt flatten coverage r=epage a=epage



2822: feat(derive): Add support for lower/upper in rename_all r=epage a=epage



Co-authored-by: Ed Page <eopage@gmail.com>
2021-10-07 16:02:20 +00:00
Ed Page
e42487f6e8 fix(derive): Subcommands not working within macro_rules
This carries over a test case from
https://github.com/TeXitoi/structopt/pull/448, and re-fixes it according
to the changes we've made since we forked.  I also tried to  identify
other cases and quote them to avoid playing whack-a-mole with this.

This is a part of #2809
2021-10-07 10:05:30 -05:00
Ed Page
7761cf00d7 docs(derive): Fix explanation on optional string list argument
This is a port of https://github.com/TeXitoi/structopt/pull/450

This is a part of #2809
2021-10-07 10:02:34 -05:00
Ed Page
f681e46414 test(derive): Port structopt flatten coverage
https://github.com/TeXitoi/structopt/pull/414 was ported in
a95195874 but the test was less exhaustive.  This updates our test to
match structopt's latest version of the test.

This is a part of #2809
2021-10-07 10:02:34 -05:00
Ed Page
e10b5281d6 feat(derive): Add support for lower/upper in rename_all
Some programs do not use anything to separate word boundaries.

For example a struct may contain the field `build_dir` while the flag is
`--builddir`.

This is a port of https://github.com/TeXitoi/structopt/pull/412

This is part of #2809
2021-10-07 10:02:34 -05:00
Ed Page
74799ea916 Revert structopt #325
https://github.com/TeXitoi/structopt/pull/325 special cased `version`
because a default method would be added if the user did nothing, which
caused problems when nesting subcommands.  We no longer apply that
default method and the highest item in the chain always has precedence,
so this can be simplified / clarified.
2021-10-06 19:20:15 -05:00
Ed Page
412071a134 refactor: Be consistent in adding methods last
This will unblock us from removing the `version` hack because we'll
always get the right precedence.

Later we can explore ways of moving the app methods to being done first.
The big problem is with `#[clap(subcommand)]` because we need to call
those app methods on the subcommands `App` *and* override them with app
methods on the variant, requiring the app methods to be last to get
precedence.
2021-10-06 19:19:31 -05:00
Ed Page
6594e28776
Merge pull request #2826 from epage/skip
feat(derive): Add skip attribute support for enum variants
2021-10-06 19:16:42 -05:00
Ed Page
16023cf157 feat(derive): Add skip attribute support for enum variants
> Resolves #493

This is a port of https://github.com/TeXitoi/structopt/pull/494

This is part of #2809
2021-10-06 13:52:02 -05:00
Ed Page
51c723a84f fix(derive): Fix the problem where the build fails due to the ambiguous type of map
> This PR closes #490. Please refer to #490 for the detail of the problem. Let me know if you want to make `convert_type` a function.

This is a port of https://github.com/TeXitoi/structopt/pull/491

This is part of #2809
2021-10-06 13:22:56 -05:00
Ed Page
e62a92f260
Merge pull request #2810 from epage/license
docs: Ensure all crates have license files
2021-10-06 08:55:25 -05:00
Ed Page
6f95650a91
Merge pull request #2805 from epage/validate_default
fix(derive): Type check `default_value_t`
2021-10-06 08:54:59 -05:00
Ed Page
9afa08ff50 fix(derive): Support SubcommandsNegateReqs
Before there was no way to make `SubcommandsNegateReqs` with
`clap_derive` because it required a required field with a sentinel value
for when the required part was negated.  We blocked that.

This turned out simpler than I expected.

This came out of the discussion for #2255 but that issue is more
specifically about the panic, so not closing it.
2021-10-05 16:02:02 -05:00
Ed Page
6c6b97daa8 docs: Ensure all crates have license files
In #2270, its brought up to solve this at the `cargo workspace publish`
level.  However, copying the files is a 5s fix without any design work,
it doesn't seem like support within an external tool should block us
from getting this fix into users hands.  Once `cargo workspace publish`
supports this and if we are still using it, we can re-evaluate.

Fixes #2270
2021-10-04 14:45:31 -05:00
Ed Page
d0b22b53ff fix(derive): Type check default_value_t
Fixes #2064
2021-10-04 13:02:47 -05:00
ModProg
08e8c53862 refactor(ArgEnum): replace unwrap with except, arg_value -> to_arg_value 2021-10-01 16:14:10 +02:00
ModProg
d53778ed5d fix ui 2021-09-29 19:31:05 +02:00
ModProg
15fcf814c2 fix dummies 2021-09-29 19:05:16 +02:00
ModProg
480035ac9c ArgEnum: Slice instead of array, from_str in ArgEnum implemented 2021-09-29 18:33:43 +02:00
ModProg
ac1a9d6d13 address epage's remarks 2021-09-27 22:06:17 +02:00
ModProg
76f7211d8b small changes 2021-09-27 01:29:10 +02:00
ModProg
f002cdcc99 move alias implementation to ArgValue for derive 2021-09-27 01:18:47 +02:00
Roland Fredenhagen
88d7d02555 Working Implementation 2021-09-26 16:32:46 +02:00
ModProg
b589a6ce06 feat(derive:arg_enum): use ArgValue in ArgEnum trait 2021-09-26 16:32:46 +02:00
Roland Fredenhagen
5580e8c465
ArgValue builder (#2758)
* feat(arg_value): ArgValue can be used for possible_values

Through the ArgValue it is possible:

* `hide` possible_values from showing in completion, help and validation
* add `about` to possible_values in completion

* Resolved a few change-requests by epage

* make clippy happy

* add ArgValue::get_visible_value

* remove verbose destructering

* rename ArgValue::get_hidden to ArgValue::is_hidden

* add test for help output of hidden ArgValues

* Documentation for ArgValue

There is an issue that required to implement From<&ArgValue> for
ArgValue. We should probably find a solution without that.

* fix requested changes by epage

* fix formatting

* add deref in possible_values call to remove From<&&str>

* make clippy happy

* use copied() instad of map(|v|*v)

* Finishing up for merge, hopefully

* changes requested by pksunkara
2021-09-19 10:29:09 +00:00
corentin.regal
8df90fbd0e Allow subcmd name to be something else than a literal in clap derive 2021-09-06 09:13:20 +02:00
Sven-Hendrik Haase
2f8f55e64b
Fix keyvalue example
This was broken earlier due to 3f94d17c71 not
taking into account this example.

Fixes #2746.
2021-08-30 04:52:35 +02:00
Ed Page
aeaf01e3e7 fix: Provide path to avoid UTF-8 panics
Before, validating UTF-8 was all-or-nothing and would cause a `panic` if
someone used the right API with non-UTF-8 input.

Now, all arguments are validated for UTF-8, unless opted-out.  This
ensures a non-panicing path forward at the cost of people using the
builder API that previously did `value_of_os` need to now set this flag.

Fixes #751
2021-08-18 14:15:18 -05:00
Ed Page
502dd78828 fix(derive): Don't produce warnings
I did some digging to root cause this but gave up and suppressed it,
like others.  Warnings like this also come with a cost of code-gen
complexity.

Fixes #2712
2021-08-17 20:53:12 -05:00
Pavan Kumar Sunkara
52be134949 Release 3.0.0-beta.4
clap@3.0.0-beta.4
clap_derive@3.0.0-beta.4
clap_generate@3.0.0-beta.4

Generated by cargo-workspaces
2021-08-14 23:40:49 +01:00
Pavan Kumar Sunkara
73b28fb104 Release 3.0.0-beta.3
clap@3.0.0-beta.3
clap_derive@3.0.0-beta.3
clap_generate@3.0.0-beta.3

Generated by cargo-workspaces
2021-08-14 23:01:13 +01:00
Ed Page
2eb22e2b36 fix!: value_name/value_names should not append
Instead they should behave like `default_value`/`default_values`.

In implementingt this, I didn't see any reason to be using a `VecMap`.
In fact, this helped simplify the code / make intent clearer.

With this, we are also able to simplify the derive macro work from #2633.

Fixes #2634

BREAKING CHANGE: `value_name`/`value_names` always overwrite, rather
than append.  We expect the impact to be minimal.
2021-08-13 15:37:03 -05:00
Pavan Kumar Sunkara
badcb3ac7b
Merge pull request #2684 from epage/update_ext
test: Cover external subcommand updates
2021-08-13 20:51:21 +01:00
Ed Page
2458d3934a test: Cover external subcommand updates
We don't know enough to do partial updates, so we are only doing full
updates.

Closes #2212
2021-08-13 12:33:12 -05:00