If short help is too long for the terminal, clap will automatically
switch to next line help. As part of next line help for longs, we add a
blank line between args. This helps make the args clearer when dealing
with multiple paragraphs. However, its not as much needed for short and
subcommands (always short), so now short matches subcommands.
This was inspired by #3300 and a part of #4132
This makes it match up with `Command::allow_hyphen_values` which was the
guiding factor for what the behavior should be.
This supersedes #4039Fixes#3880Fixes#1538
This has been a bit out of place being on the command. Now its clearer
what the user intends to be the trailing var arg and it is more likely
to be discovered.
The builder function was deprecated in v3 and removed in v4 but the
derive masked that, so we're still adapting things but now with a path
towards removal.
In reviewing CLIs for #4132, I found some were providing helps on `-h`
vs `--help` and figured that could be built directly into clap. I had
considered not making this hint automatic but I figured the overhead of
checking if long exists wouldn't be too bad. The code exists (no binary
size increase) and just a simple iteration is probably not too slow
compared to everything else.
Fixes#1015
This ensures we don't end up with accidental leading or trailing
newlines due to help template variables not being used when a section is
empty.
This is prep for removing name/version from the default template and is
part of #4132
In switching to title case for help headings (#4123), it caused me to
look at "subcommand" in a fresh light. I can't quite put my finger on
it but "Subcommand" looks a bit sloppy. I also have recently been
surveying other CLIs and they just use "command" as well.
All of them are commands anyways, just some are children of others
(subcommands) while others are not (root or top-level commands, or just
command). Context is good enough for clarifying subcommands from root
commands.
This is part of #4132
The setting was added to resolve#769. The reason it was optional is out
of concern for applications with a lot of positional arguments. I think
those cases are rare enough that we should just push people to override
the usage. Positional arguments are generally important enough, even if
optional, to show.
As a side effect, this fixed some bugs with
`dont_collapse_args_in_usage` where it would repeat an argument in a
smart usage.
As a side effect, smart usage now shows `--` when it should
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.
In surveying various tools and CLI parsers, I noticed they list the
subcommands first. This puts an emphasis on them which makes sense
because that is most likely what an end user is supposed to pass in
next.
Listing them last aligns with the usage order but it probably doesn't
outweigh the value of getting a user moving forward.
I see them fulfilling two roles
- A form of bolding
- As a callback to their placeholder in usage
However, it is a bit of an unpolished look and no other CLI seems to do
it. This looks a bit more proefessional. We have colored help for
formatting and I think the sections relation to usage will be clear
enough.
For now, there isn't much a custom implementation can do.
Going from `Rich` to `Null` drops about 6 KiB from the binary
This is a part of #1365 and #1384
While `TypedValueParser` will generally make it easier to reuse value
parsers, this was particularly written for flags. Besides having a
concrete API to document, an advantage over `fn(&str) -> Result<bool, E>`
value parsers is you get all of the benefits of the existing value
parsers for environment variable parsing.
The main breakinge change cases:
- `&[char]`: now requires removing `&`
- All other non-ID `&[_]`: hopefully #1041 will make these non-breaking
Fixes#2870
For now, we are focusing only on iterating over the argument ids and not
the values.
This provides a building block for more obscure use cases like iterating
over argument values, in order. We are not providing it out of the box
at the moment both to not overly incentize a less common case, because
it would abstract away a performance hit, and because we want to let
people experiment with this and if a common path emerges we can consider
it then if there is enough users.
Fixes#1206
Now that `Id` is public, we can have `ArgMatches` report them. If we
have to choose one behavior, this is more universal. The user can still
look up the values, this works with groups whose args have different
types, and this allows people to make decisions off of it when otherwise
there isn't enogh information.
Fixes#2317Fixes#3748
This is a step towards #1041
- `ArgGroup` no longer takes a lifetime
- One less field type needs a lifetime
For now, we are using a more brute force type (`String`) so we can
establish performance base lines. I was torn on whether to use `&str`
everywhere or make an `IdRef`. The latter would add a lot of noise that
I'm concerned about, so i left it simple for now. `IdRef` would help to
communicate the types involved though.
Speaking of communicating types, I'm also torn on whether we should use
`Id` for all strings or if we should have `Id`, `Name`, etc types to
avoid people mixing and matching.
This added 18.7 KB.
Compared to `HEAD~` on `06_rustup`:
- build: 6.23us -> 7.41us
- parse: 8.17us -> 9.36us
- parse_sc: 7.65us -> 9.29us
This is a part of #2870 and is prep for #1041
Oddly enough, this dropped the binary size by 200 Bytes
Compared to `HEAD~` on `06_rustup`:
- build: 6.21us -> 6.23us
- parse: 7.55us -> 8.17us
- parse_sc: 7.95us -> 7.65us
Documenting the existing behavior is challenging which suggests it can
cause user confusion. So long as its not too hard to explicitly
specify actions, we should just do it.
Fixes#4057
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
Previously the Arg id was set with the "name" attribute. This allows use
of an "id" attribute to match the underlying struct.
A side effect of this is that the "id" attribute may also be used on
Commands. This isn't desired, but given the current architecture of the
attribute parser, it's hard to avoid.
Fixes: #3785
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.
In clap v3, `require_value_delimiter` activated an alternative parse
mode where
- `multiple_values` meant "multiple values within a single arg"
- `number_of_values` having no parse impact, only validation impact
- `value_names` being delimited values
For unbounded `number_of_values`, this is exactly what `value_delimiter`
provides. The only value is if someone wanted `value_name` to be
`<file1>,<file2>,...` which can be useful and we might look into adding
back in.
Alternatively, this could be used for cases like key-value pairs but
that has issues like not allowing the delimiter in the value which might
be ok in some cases but not others. We already instead document that
people should instead use `ValueParser` for this case.
In removing this, we remove points of confusion at how the different
multiple values and delimited value calls interact with each other. I
know I would set `require_value_delimiter(true).multiple_values(true)`
when it turns out all I needed was `value_delimiter(',')`.
This also reduces the API surface area which makes it easier to discover
what features we do provide.
While this isn't big, this is also yet another small step towards
reducing binary size and compile times.
This will allow `num_args(0..=1).value_delimiter(',')` to work properly.
This hacks in support for `require_value_delimiter` until we can remove
it.
This no longer recognzes value terminators in delimited lists.
It looks like there is a bug with recognizing value terminators in
positionals arguments. We'll need to dig into that more.
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.
When suggesting required arguments, we wanted to avoid an argument
showing up in both a group and by itself but we didn't correctly
calculate that, causing no required arguments to show up at times.
Now, we all use the same pool of information for doing the calculations.
This was the type of cleanup that I expected it to drop our binary size
but this added 1k to our .text. Strange.
Fixes#4004
With `number_of_values` being per-occurrence now, its doesn't make sense
for `number_of_values(0)` to set `takes_value(true)` or for
`number_of_values(1)` to set `multiple_values(true)`.
In addition, an assert is made if the user works around this
This both simplifies the code and the model we present to the user,
making more sense.
There is room for further exploration of tying flag actions into this.
This changes the default type as well to encourage preserving the full
information for shelling out. If people need UTF-8, then they can
change the value parser.
Fixes#3733
Previous behavior:
- They'd be sorted by default
- They'd derive display order if `DeriveDisplayOrder` was set
- This could be set recursively
- The initial display order value for subcommands was 0
New behavior:
- Sorted order is derived by default
- Sorting is turned on by `cmd.next_display_order(None)`
- This is not recursive, it must be set on each level
- The display order incrementing is mixed with arguments
- This does make it slightly more difficult to predict
We had some tests for this but not sufficient obviously. The problem is
we were tweaking the positional argument counter when processing flags
and not just positional arguments. Delaying it until after flags seems
to fix this.
Fixes#3959
This fixes a bug introduced in 4a694f3592
when we were trying to move away from presence checks via occurrences.
I switched it to the common type of presence check but really what we
want is a highest-precedence check.
Fixes#3872
When upgrading our company projects from clap 3.1 to clap 3.2 I had
to fix several references to `clap::lazy_init`. People are not
supposed to do that, but that's hard to enforce.
Hope placing `once_cell` reexport into `__macro_refs` prevent at
least some of the such issues in the future.
This adds a new `Cargo.toml` feature named `deprecated` that opts
controls whether deprecation warnings show up. This is starting off as
non-default though that may change (see below).
Benefits
- Allows a staged rollout so a smaller subset of users see new
deprecations and can report their experience with them before everyone
sees them. For example, this reduces the number of people who have to
deal with #3822.
- This allows people to defer responding to each new batch of
deprecations and instead do it at once. This means we should
reconsider #3616.
The one risk is people who don't follow blog posts and guides having a
harder time upgrading to the next breaking release without the warnings
on by default. For these users, we reserve the right to make the
`deprecated` feature `default`. This is most likely to happen in a
minor release that is released in conjunction with the next major
release (e.g. when releasing 4.0.0, we release a 3.3.0 that enables
deprecations by default). By using a feature, users can still disable
this if they want.
Thanks @joshtriplett for the idea
With the new `ArgMatches`, we need to know what the inner type is.
Unfortunately, #3142 didn't list use cases for this. We dropped the
`Option` alias changing `T` but we still have a `Result` in there that
is aliased.
One potential workaround if people need it is if we add an attribute to
specify the `get_many::<T>` type. This would also help with
`ArgAction::Count` to support more data types.
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.
Someone should not reasonably expect a coun flag to go up to billions,
millions, or even thousands. 255 should be sufficient for anyone,
right?
The original type was selected to be consistent with
`ArgMatches::occurrences_of` but that is also used for tracking how
many values appear which can be large with `xargs`.
I'm still conflicted on what the "right type" is an wish we could
support any numeric type. When I did a search on github though, every
case was for debug/quiet flags and only supported 2-3 occurrences,
making a `u8` overkill.
This came out of a discussion on #3792
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 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 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.
This is mostly about avoiding criterion's build times when just
developing clap itself.
I'm assuming the derive test changed because criterion's clap v2 isn't
in the dependency tree anymore.
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 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
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.
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.
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.
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.
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
`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
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.
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 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.
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.
`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
