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
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 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.
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
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
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.
`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 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.
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.
When an Arg uses .min_values(0), that arg's value(s) are effectively
optional. This is conventionaly denoted in help messages by wrapping the
arg's values in square brackets. For example:
--foo[=value]
--bar [value]
This kind of argument can be seen in the wild in many git commands; e.g.
git-status(1).
Signed-off-by: Peter Grayson <pete@jpgrayson.net>
I thought I was adding a test in #3305. Maybe I considered the
clap_complete changes sufficient for this. Doing more `debug_assert`s
would be good also.
Unsetting `PropagateVersion` helps in some cases but we need to unset it
globally to override the global propagation.
Fixes#3310
This reverts commit 333b993481.
PR #1810's motivation was effectively "this is redundant with `\n`".
That is a fine motivation. Unfortunately, we don't have a way to force
a hard break in `clap_derive`. #2389 should help with this eventually
but we shouldn't hold up 3.0 to get that ready. So in the mean time, we
are restoring `{n}`.
We have #3230 for tracking the re-removal of it.
The extra whitespace was targeted at machine processing for a subset of
users for a subset of runs of CLIs. On the other hand, there is a lot
of concern over the extra verbose output.
A user can set the help template for man, if desired. They can even do
something (env? feature flag?) to make it only run when doing man
generation. We also have #3174 in the works.
So let's focus on the end-user reading `--help`. People wanting to use
`help2man` have workarounds to do what they need.
Fixes#3096
We have two ways of fixing this
- Making `--help` work
- Don't put `--help` in the help output
For now, I went with the latter. I tried to make it clear what the
actual requirement is so we can pivot if needed.
Fixes#2892
This happens to also fix the interaction of `DisableHelpFlag` with the
help subcommand and complcations. I've added a test to help catch if we
break this by changing how we fixed the original issue.
Fixes#2724
These issues were reported against clap3. I've not tried to reproduce
these in clap2 to see if they should show up in the release notes.
This is prep for moving the derive tests. Besides organizing the test
folder for each API, this should reduce link time at the cost of
re-compiling more when a test changes.
