Originally I hid all, assuming the flag-only use case but we had to
prevent that from showing up anyways. For the takes_value case, we
should be showing something since we know what it accepts. I decided to
only show the most basic values and hide the rest so as to not overwhelm
the user with redundant options and hope the user recognizes they are
redundant.
Now that flags can have meaningful defaults and with defaults being
implicitly set for certain actions, they appear in help but don't quite
make sense.
Actions were inspired by Python and Python does not implicitly default
any field when an action is given. From a Builder API perspective, this
seemed fine because we tend to focus the Builder API on giving the user
all information so they can make their own decisions. When working on
the Derive API, this became a problem because users were going to have
to migrate from an implied default to an explicit default when a common
default is good enough most of the time. This shouldn't interfere with
Builder users getting more details when needed.
This also highlighted two problems
- We set the index for defaults
- We don't debug_assert when applying conditional requirements with a
default present
This round out the new style actions and allow us to start deprecating
occurrences.
As part of an effort to unify code paths, this does change flag parsing
to do splits. This will only be a problem if the user enables splits
but we'll at least not crash. Once we also address #3776, we'll be able
to have envs all work the same.
This is the minimum set of actions for the derive to move off of
`parse`. These are inspired by Python's native actions.
These new actions have a "unified" behavior with defaults/envs. This
mostly means that occurrences aren't tracked. Occurrences were used as
a substitute for `ValueSource` or for counting values. Both cases
shouldn't be needed anymore but we can re-evaluate this later if needed.
If we felt this was important long-term, we should fix this outside of
the Action. Since we might be changing up occurrences (#3772), we can
probably get away with a hack.
This changes how occurrences and values are grouped for multiple values.
Today, it appears as a bug. If we move forward with #3772, then this
can make sense.
When creating `PendingValues`, I can't have the lifetime. I could make
it a `Cow` but decided to hold off instead since we don't need this
right now. Maybe by the time we do need it, we'll have another way of
doing this.
There is a default_missing_vals case which is slightly different because
its not actually a default but closing out the remaining argument that
was started in last iteration.
Before, if we were in trailing values that aren't delimite, we wouldn't
respect this flag and end processing of the value, now we do.
This also has a slight perf benefit of us only splitting the value if
the delimiter is present. We checked for the delimiter anyways, so
doing it first removes a slight bit of work.
I also feel this helps clarify the intended behavior and ooches us
towards a unified code path for actions.
I wrote these tests expecting to highlight a bug but it turns out things
were structured just right to not exhibit it. The fact that the code
looks like its broken is a problem, so I restructured it (put it first,
changed the source) so it doesn't look suspicious anymore.
We were independently starting occurrences and starting value groups.
Now we do them at the same time.
COMPATIBILITY: This changes us from counting occurrences per positional
when using `multiple_values` to one occurrence. This is user visible
and tests were written against it but it goes against the documentation
and doesn't quite make sense.
Inferred flags can make it hard for a future action to trigger behavior
off of the selected alias, like we might want to do for negations, so we
are now translating to the intended arg.
This will also help for debugging.
For most users, this won't be worth doing, they can just specify the
parser if needed. Where this has value is crates that integrate custom
types into clap, like creating click-like file integration. See
https://click.palletsprojects.com/en/8.0.x/arguments/#file-arguments
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.
When to show usage? We are currently mixed about it. For `validator`,
we didn't show it at all. Sometimes we show the used arguments and
sometimes we don't.
With `ValueParser`, I ran into the problem that we weren't showing the
used arguments like we had previously in some cases. In deciding how to
solve this, I went with the simplest route for now and removed it as the
usage likely doesn't add much context to help people solve their
problem, more so the recommendation for help. We'll see how the
feedback is on this and adjust.
`multicall` allows you to have one binary expose itself as multiple
programs, like busybox does. This also works well for user clap for
parsing REPLs.
Fixes#2861
There are several approaches with this
- `value_parser(N..M)`: creates an i64 range
- `value_parser(value_parser!(u16).range(10..))`: creates an u16 range
that starts at 10
- `RangeI64ValueParser`: create whatever range you want
I was hoping to generalize `RangeI64ValueParser` for any source type,
not just i64, but ran into issues and decided to punt. I chose `i64` as
the source type as it seemed the most general and didn't run into
portability issues like `isize`.
This is a step towards #3199. All that is left is for the derive to use
this.
This identified a problem with the blanket implementations for
`TypedValueParser`: it only worked on function pointer types and not unnamed
function tupes. The user has to explicitly decay the function type to a
function pointer to opt-in, so I changed the blanket impl. The loss of
the `OsStr` impl shouldn't be too bad.
To set the type, we offer
- `ValueParser::<type>` short cuts for natively supported types
- `TypedValueParser` for fn pointers and custom implementations
- `value_parser!(T)` for specialized lookup of an implementation
(inspired by #2298)
The main motivation for `value_parser!` is to help with `clap_derive`s
implementation but it can also be convinient for end-users.
When reading, this replaces nearly all of our current `ArgMatches` getters with:
- `get_one`: like `value_of_t`
- `get_many`: like `values_of_t`
It also adds a `get_raw` that allows accessing the `OsStr`s without
panicing.
The naming is to invoke the idea of a more general container which I
want to move this to.
The return type is a bit complicated so that
- Users choose whether to panic on invalid types so they can do their
own querying, like `get_raw`
- Users can choose how to handle not present easily (#2505)
We had to defer setting the `value_parser` on external subcommands,
for consistency sake, because `Command` requires `PartialEq` and
`ValueParser` does not impl that trait. It'll have to wait until a
breaking change.
Fixes#2505
Unfortunately, we can't track using a `ValueParser` inside of `Command`
because its `PartialEq`. We'll have to wait until a breaking change to
relax that.
Compatibility:
- We now assert on using the wrong method to look up defaults. This
shouldn't be a breaking change as it'll assert when getting a real
value.
- `values_of`, et al delay panicing on the wrong lookup until the
iterator is being processed.
The top-level API for clap is getting a bit bloated. By exposing these
modules, we'll be able to continue to add new, less commonly used types
while keeping the main API focused.
In #3711, we had a confusing assert about no non-default members of a
required group when there were no defaults involved. This is because
there were no valid args in the group but that check happens after.
With us moving the required de-duplication up a level, it made this
check redundant. By removing this check, we're more likely to have an
item in the `incls` which forces a smart usage and reduces the chance of
an `[ARGS]` or `[OPTIONS]`, so a couple of tests changed.
Gave up trying to decipher the existing logic for safe ways to
de-duplicate manually and switched to an `IndexSet` to enforce only one
of each argument exists.
Fixes#3556
This will mean we won't have an awkard `.exe` in the middle on Windows
This means users can have a display name for their application rather
than it being dependent on the binary name it was run as
This means users can manually set it to use spaces instead of dashes for
separating things out.
Fixes#992Fixes#1474Fixes#1431
This is a step towards #3309. We want to make longs and long aliases
more consistent in how they handle leading dashes. There is more
flexibility offered in not stripping and it matches the v3 short
behavior of only taking the non-dash form. This starts the process by
disallowing it completely so people will catch problems with it and
remove their existing leading dashes. In a subsequent breaking release
we can remove the debug assert and allow triple-leading dashes.
`Arg::exclusive` is just another way of defining conflicts, so a
present-exclusive arg should override required like other conflicts.
Instead of going through the message of enumerating all other arguments
as exclusive, I shortcutted it and special case exclusive in the
required check like we do with conflicts. The big downside is the
implicit coupling between the code paths rather than having a consistent
abstraction for covering conflicts.
This isn't a breaking change because if someone defined an exclusive arg
as a sibling to a required arg, the exclusive arg could never be used,
it always errored, and so no valid application can be written with it.
Fixes#3595
This is a step towards #992. When help renders the application name, it
uses the `bin` template variable which is just the `bin` name with
spaces converted to ` `. While having `app.exe sub` makes sense,
`app.exe-sub` does not.
To get around needing this for usage, we've created a `display_name`
field that is fairly similar but
- The root name is the `name` and not `bin_name`
- We always join with `-`
This means that the derived `bin_name` will only show up in usage.
For now, the default template has not been updated as that is a minor
compatibility change and should be in a minor release, at least. I was
worried this would be a full breaking change. The main case I was
worried about was cargo subcommands but our tests show they should just
work.
By removing all arguments, we've switched from an "unrecognized
argument" error to a "unrecognized subcommand" error. While the wording
has room for improvement, its at least progress on #2862.
Inspired by argcomplete, this provides Rust-implemented completions
- Only bash for now
- No subcommand support
- No flag value support
- No special settings support
- No handling of positions within positionals
- No prioritizing of required or removing of conflicts (including
self-conflicts)
