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.
This is inspired by cargo which allows you to run `cargo test --test`
and it will list the possible tests (obviously we can't support that atm
because that requires a lot of runtime processing). When we do have a
static list of possible values, we can at least show those.
Fixes#3320
For some errors, we use the unroll logic to get the list of required
arguments. The usage then does the same, but without a matcher. This
was causing the lists to not match.
As a side effect, this fixed an ordering issue where we were putting the
present arg after the not-present arg. I assume its because we ended up
reporting the items twice but the first time is correctly ordered and
gets precedence.
This was split out of #3020
In clap2, `ArgMatches.args` was public but hidden. We made it private
in clap3, giving us more implementation flexibility but many people
relied on it, like to short-circuit defaulting, providing their own
`ArgRequiredElseHelp`, etc.
The main problem was how to expose this
- If we think of `ArgMatches` as a container (a DAG), should we have an
`is_empty` and what all is included in that, like subcommands?
- If we focus on only args, what term how do we refer to this to convey
the right intent?
In the end, I realized that this aligns most with our existing
`is_present` check and reporting if args are present fits the best
within the existing API.
I looked into also exposing iterating over the args (`present_arg_ids`)
but we have no way to expose the Id. The Id is currently private and if
we made it public, it can't be used to access any arg because it can't
implement `Key`.
This supersedes #3265
If a value must be reused later then it's better to pass it as a &str
instead of cloning it, that means the clone happens in a central
place (inside the method).
By never passing a &String those instances of the method are not monomorphized.
Saves only 0.5K, maybe not worth it in hindsight.
This is an initial implementation with plenty of room to grow, including
- Allowing pulling out a subset of the generated man page for greater customization
- Subcommand handling
- Extra sections
- Consolidate argument formatter after #2914Fixes#552
