I'm a bit disappointed we don't have a way to control the action for the
help subcommand. Instead, people will need to provide their own and
disable ours. Long term, I want to design actions for subcommands but I
don't think its worth keeping `NoAutoHelp` around for it.
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.
This mostly exist for
- Knowing of the value came from the command-line but we now have
`ArgMatches::source`
- Counting the number of flags but we now have `ArgAction::Count`
This shouldn't be needed anymore now that this is effectively the new
behavior for the non-deprecated actions.
This was briefly talked about in
https://github.com/clap-rs/clap/discussions/2627 but I wasn't familiar
enough with the implementation to know how safe it is. Now, maintainrs
and users can be more confident because they are explicitly opting into
it.
See also #3795
Dropping these will help simplify a lot, including removing of
occurrences.
These come at the cost of the derive not yet supporting types that impl
`From`.
This is a follow up to #3420. Its easy to overlook this because it is only
useful for the conditionals (we actually prevent applying unconditional
defaults to unconditional requireds). This became apparent with the
increased use of defaults with `SetTrue`.
As always, there is the question of when is a bug fix a breaking change.
I'm going to consider this safe since we prevent some instances of this
from even happening and we already did #3420 and this is in line with
those.
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)
Before, if two arguments were required *and* overrode each other, then
`cmd --opt=1 --other=2` succeded but `cmd --other=2` failed despite
ignoring `--opt=1`. Requiring `--opt=1` to be present but unavailable
doesn't help anyone and makes the behavior less predictable.
Now both commands will have the same behavior.
We had two different implementations of conflicts
- Validating conflicts
- Allowing conflicts to override `required`
- Missing members of a group conflicting with each other
- Missing symmetric conflicts (A conflicts with B so B conflicts with
A)
This consolidates their implementations which should fix overriding of
`required`.
`Command::_build_all` started as an internal function for
`clap_complete` as a stopgap until #2911. Overtime, we've been finding
more cases where this function needs to be called, so now we're going to
fully embrace it until #2911 so people aren't scrared off by the hidden
implementation from using it.
This was inspired by #3602
Comptibility: Though this adds a deprecation which we general reserve
for minor or major versions, this is enough of a corner case that I'm
fine doing this in a patch release.
In considering the design for this, we want:
- Ability to modify the argment list while maintaining the `Cursor` for
replacements
- Allow picking up subcommand parsing in the middle of short flags
- Ability to peek at the next item to determine if we want to treat it
as a flag or as a value
- Ability to detect started short and long arguments for completions
Longer term, we also want to consider:
- Allowing users to customize the lexer to support different syntaxes
Since we'll need `skip`, it made me wonder how to name `skip` and
`previous` to fit together, so I decided to play with `seek`. Its
probably over kill but wondering if its better.
Before, we had a generic `next` that provided the next item and peeked
at all remaining items. This was to work around the borrow checker for
modifying the position while accessing args.
We've now split `Input` into `RawArgs` and `ArgsCursor` so we don't have
overlapping borrows. This made it so we can split `next` into `next`,
`peek`, and `remaining`.
`-h` (short help) still shows the same.
This gates it behind an `unstable-v4` feature flag to avoid disrupting users who set the help without knowing where all it shows up (particularly derive users where `ArgEnum` is automatically extracting the help).
Fixes#3312
Instead of just renaming it, I reconsidered what the API should look
like. A custom separator for author does not make sense positionally
but accepting a name, and defaulting it, does fit with what someone
would expect.
I removed the `_from_crate` suffix because it doesn't seem necessary.
We don't have this kind of naming for the derive. I feel it cleans
things up this way.
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.
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.
The long term goals are
- Easier refactoring
- Identify needs for reflection API
Shorter term, if I want to rename `App` to `Command` and deprecate
`App`, it will mark all member access as deprecated. This works around
that.
I gave up in exploring abstractions when it came to `MKeyMap` access.
This can be refined in the future.
The main goal is to allow centralizing some building logic currently
split between the parser and `App`. It depends on this logic.
As a side benefit, this allowed us to decouple some operations from `Parser` in `App`.
The main impact I can see is that we'll calculate the required once for
parsing a subcommand and once for validation.
We left them in the docs for a period of time to help people find docs
for code that was still in use. Balancing that with the need for clean
docs, it seems like 3.1 is an appropriate time to mark them hidden in
the docs.
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
Like was said in #2435, this is what people would expect.
While we should note this in a compatibility section in the changelog, I
do not consider this a breaking change since we should be free to adjust
the help output as needed. We are cautious when people might build up
their own content around it (like #3312) but apps should already handle
this with `--help` so this shouldn't be a major change.
We aren't offering a way for people to disable this, assuming people
won't need to. Longer term, we are looking at support "Actions" (#3405)
and expect those to help customize the flags. We'll need something
similar for the `help` subcommand.
Fixes#3440
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.
Unrolling serves two distinct purposes but we muddied them together
- Is `requires` satisfied for validation
- Report what arguments are currently considered required for usage
This was split out of #3020
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
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.
