With the previous fixes for #4273 and #4280 in place, it's now easy to
add support for subcommand aliases, which this commit does. This
addresses #4265 for Bash.
This continues the work started with the fix for #4273. There was
another bug caused by using the subcommand names without considering
their position in the argument list. If the user enters `git diff log
<TAB>`, we build up a string that identifies the subcommand. We ended
up making the string `git__diff__log` in this case because we appended
`__log` without considering the current state. Since `git__diff__log`
does not correspond to an actual command, we wouldn't provide any
suggestions.
This commit restructures the code so we walk subcommands and
subsubcommands in `bash.rs`. While walking those, we build up a list
containing triples of the parent `$cmd` name (e.g. `git__diff`), the
current command's name (e.g. `log`), and the `$cmd` for the current
command. We then build the shell script's case arms based on that
information.
We could instead have fixed#4280 by using the second element in the
pair returned from `utils::all_subcommands()` (a stringified list of
the subcommand path) instead of the first one. However, that would not
have helped us solve #4265.
Closes#4280
Early in the Bash-completion script, we build up a string that
identifies the command or subcommand. When we see the top-level
command's name (e.g. `git`) we set the command so far to that
value. We do that regardless of where in the argument list it
appears. For example, if the argument list is `git diff git`, we set
the current command to `git` when run into it the second time. We
therefore suggest arguments to the top-level command afterwards, which
is not correct.
This patch fixes that by also considering the string that identifies
the command so far, so we only set the overall command to `git` if the
command so far is the empty string.
This is actually just a step on the way to getting completion to work
for aliases of subcommands.
Closes#4273
There seems to be little reason to return early with an empty list
when there are no subcommands, instead of going through the loop 0
times and then returning the empty list.
The derive-based example has a `///` comment on one argument, which
ends up as a description for the argument in the generated completion
scripts. Let's switch to `//` so the two scripts produce the same
output (except for the binary name), so they're easy to compare.
The example binaries were renamed in 89c2b3bb0d, but the commands in
them were not, making the generated completion scripts not work
(because we use the command name as binary name in the examples).
Originally, clap carried a lifetime parameter. When moving away from
that, we took the approach that dynamically generated strings are always
supported and `&'static str` was just an optimization.
The problem is the code size increase from this is dramatic. So we're
taking the opposite approach and making dynamic formatting opt-in under
the `string` feature flag. When deciding on an implementation, I
favored the faster one rather than the one with smaller code size since
small code size can be gotten through other means.
Before: 567.2 KiB, 15.975 µs
After: 541.1 KiB, 9.7855 µs
With `string`: 576.6 KiB, 13.016 µs
This prevents global args from showing in help completions,
since help completions should only suggest subcommands.
Adds tests to ensure the args still show in the generated
help messages of subcommands.
* Copy hide flag
* Revert global args special handling. Another commit will
address the issue of whether global args should be included in
help subtrees.
Adds parser flags to toggle whether to run the
expensive clone logic for completions case.
Help completion will only suggest subcommands, not args.
clap_complete generator sets the flag.
Another step towards #1041
This isn't the long term type for `PossibleValue::help`, I just wanted
to get the lifetime out of the way first before figuring out how help
will work.
Before we introduced actions, it required specific setups to engage with
claps version and help printing. With actions making that more
explicit, we don't get as much benefit from our multiple, obscure, ways
of users customizing help
Before
- Modify existing help or version with `mut_arg` which would
automatically be pushed down the command tree like `global(true)`
- Create an new help or version and have it treated as if it was the
built-in on (I think)
- Use the same flags as built-in and have the built-in flags
automatically disabled
- Users could explicitly disable the built-in functionality and do what
they want
Now
- `mut_arg` no longer works as we define help and version flags at the
end
- If someone defines a flag that overlaps with the built-ins by id,
long, or short, a debug assert will tell them to explicitly disable
the built-in
- Any customization has to be done by a user providing their own. To
propagate through the command tree, they need to set `global(true)`.
Benefits
- Hopefully, this makes it less confusing on how to override help
behavior. Someone creates an arg and we then tell them how to disable
the built-in
- This greatly simplifies the arg handling by pushing more
responsibility onto the developer in what are hopefully just corner
cases
- This removes about 1Kb from .text
Fixes#3405Fixes#4033
multiple_values is now just book keeping for the builder, instead people
should look to actions and `num_args`.
The meaning for it was a little weird anyways.
The only time it won't be initialized is before `_build`. This is possible because
of #4027
I wish I could just put the `expect` inside the call but I'm worried
about allowing people to build stuff on top of clap.
This reduces ambiguity in how the different "multiple" parts of the API
interact and lowrs the amount of API surface area users have to dig
through to use clap.
For now, this is only a matter of cleaning up the public API. Cleaning
up the implementation is the next step.
The main goal is to reduce the risk of people developing on the wrong
release, assuming they are using something like starship to raise the
visibility of the crate version.
Looks like I forgot to add a test case for this.
I put this in `clap_complete` because I expect `ValueHint` to move here
as we move towards a plugin system.
Fixes#3840
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 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.
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)
`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.
`-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
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.
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.
`clap_generate` originally intended to be "generate anything". With
`fig`, we already broke one part out. With #3174's man support, we are
also looking at keeping it separate:
- More freedom to iterate on the API
- Uniqueness (and potential weight) of its dependencies
- man generation is normally more for distribution while completions are
a mix of being distributed with the app or the app generating the
completions (which will be exacerbated if we move most completion
parsing logic to be in Rust)
So `clap_generate` is having a lot more limited of a role than the
original name conveys. I worry the generic name will be a hindrance to
people discovering and using it (yes, documentation can help but there
are limits).
I hesitated because we are on the verge of releasing 3.0. However, doing
it even later will be even more disruptive because more people will be
using it (crates.io lists ~70 people using `clap_generate`).
To ease things, we are still releasing `clap_generate` as a wrapper
around `clap_complete`.
