This makes us accept `str` and not do any allocations at the cost of
panicing if unsupported which I think fits our overall story in trying
to catch development-time errors.
Just having `--help` or `--version` can make us get invalid args instead
of invalid subcommands. It doesn't make sense to do this unless
positionals are used. Even then it might not make sense but this is at
least a step in the right direction.
Unsure how I feel about this being backported to clap 3. It most likely
would be fine?
This was noticed while looking into #4218
This was ported over from the usage parser which modeled after docopt.
We just never got around to implementing the rest of the syntax.
However, when considering this as a standalone feature, an
`arg!(--flag <value>)`, outside of other context, should be optional.
This is how the help would display it.
Fixes#4206
In looking at other help output, I noticed that they use two spaces, in
place of clap's 4, and it doesn't suffer from legibility. If it
doesn't make the output worse, let's go ahead and make it as dense so we
fit more content on the screen.
This is a part of #4132
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.
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.
* Copy hide flag
* Revert global args special handling. Another commit will
address the issue of whether global args should be included in
help subtrees.
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.
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.
The immediate benefit is binary size but this also makes us more
flexible on the implementation, like allowing wrapping of `StyledStr`.
This removed 12 KiB from `.text`
This helps towards #1365 and probably #2037
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
This adds feature parity for mangen with the standard help output. Users
will now see the list of possible values for value arguments.
One change that was made to make this possible was adding the method
`get_possible_values` to the public API for an arg. I tried to think of
a way to get around this, but because this is the interface that the
help generation uses, and it is part of the crate public interface
I thing adding it as a part of the public API might be for the best.
fixes: #3861
The performance gains of writing directly to the writer are not worth
the complexity. Output is not in our performance hot path.
Binary size went from 565.7 KiB to 562.2 KiB
Extend Command::override_usage() doc string to describe how to format
multiple usage lines to be compatible with clap's default help formatter.
Relates-to: #3413
The binary size and performance difference is enough to make it
configurable.
Code size:
- default: 565.7 KiB
- perf: 578.5 KiB
Build time:
- default: 9.1706 us
- perf: 7.0479 us
Parse time:
- default: 12.673 us
- perf: 8.1708 us
Parse with subcommand time:
- default: 12.112 us
- perf: 7.9874 us
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.
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
This dropped 17KB
Again, performance shouldn't be too bad as the total number of argument
id's passed in by the user shouldn't be huge, with the upper end being
5-15 except for in extreme cases like rustc accepting arguments from
cargo via a file.
This dropped `.text` by 14KB
Anything in debug asserts or help/usage output doesn't matter for
performance but I wouldn't be surprised if this was comparable since the
container sizes we are talking about are relatively small.
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
Naming is hard. I found I was writing new code without the `s` so that
suggests the name was wrong. But we renamed `number_of_values` to
`num_args`, so should this be `ArgRange`?
TakesValue helps because it provides a way for a lot of settings to say
a value is needed without specifying how many. Multiple values didn't
have enough call sites to make this worthwhile.
This is a part of #2688
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.
As we move people off takes_value/multiple_values, this will provide
something to check.
This was previously blocked on other issues related to flag handling
(#4023)
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
In the short term, this just provides a back door to custom actions.
Longer term, we can explore a `SetConst` action that relies on this
behavior. Really, `SetTrue` and `SetFalse` are shortcuts for such an
action but shortcuts can be helpful for usability.
Apparently, this also reduced `.text` size by 1k
Rendering of usage is not in a critical path, so should be more worried
about binary size than performance. That only leaves avoiding coloring
spaces. That shouldn't be a problem, so let's make the binary smaller.
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
When checking into binary size, I noticed that the `git` example is a
lot larger than v3. `git bisect` narrowed it down to
11076a5c70 which doesn't make sense. I
did noticed we could remove some bloat from monomorphization.
Overall for `cargo-example, we've dropped about 47 KiB.
