Though this is changing an API item we export, we do not consider this a
breaking change because
- This was an implementation detail of the macros and people shouldn't be using it directly
- The `macro_rules` macro is coupled to `clap` because they are in the
same crate
- The derive macro is coupled to `clap` because `clap` declares a
`=x.y.z` dependency on `clap_derive
Fixes#3828
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.
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.
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.
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
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
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.
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.
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#3734Fixes#3496Fixes#3589
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`.
