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.
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
A couple of things happened when preparing to release 3.0
- We needed derive documentation
- I had liked how serde handled theres
- I had bad experiences finding things in structopt's documentation
- The examples were broken and we needed tests
- The examples seemed to follow a pattern of having tutorial content and
cookbook content
- We had been getting bug reports from people looking at master and
thinking they were looking at what is currently released
- We had gotten feedback to keep down the number of places that
documentation was located
From this, we went with a mix of docs.rs and github
- We kept the number of content locations at 2 rather than 3 by not
having an external site like serde
- We rewrote the examples into explicit tutorials and cookbooks to align
with the 4 styles of documentation
- We could test our examples by running `console` code blocks with
trycmd
- Documentation was versioned and the README pointed to the last release
This had downsides
- The tutorials didn't have the code inlined
- Users still had a hard time finding and navigating between the
different forms of documentation
- In practice, we were less likely to cross-link between the different
types of documentation
Moving to docs.rs would offer a lot of benefits, even if it is only
designed for Rust-reference documentation and isn't good for Rust derive
reference documentation, tutorials, cookbooks, etc. The big problem was
keeping the examples tested to keep maintenance costs down. Maybe its
just me but its easy to overlook
- You can pull documentation from a file using `#[doc = "path"]`
- Repeated doc attributes get concatenated rather than first or last
writer winning
Remember these when specifically thinking about Rust documentation made
me realize that we could get everything into docs.rs.
When doing this
- Tutorial code got brought in as was one of the aims
- We needed to split the lib documentation and the README to have all of
the linking work. This allowed us to specialize them according to
their rule (user vs contributor)
- We needed to avoid users getting caught up in making a decision
between Derive and Builder APIs so we put the focus on the derive API
with links to the FAQ to help users decide when to use one or the
other.
- Improved cross-referencing between different parts of the
documentation
- Limited inline comments were added to example code
- Introductory example code intentionally does not have teaching
comments in it as its meant to give a flavor or sense of things and
not meant to teach on its own.
This is a first attempt. There will be a lot of room for further
improvement. Current know downsides:
- Content source is more split up for the tutorials
This hopefully addresses #3189
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.
Before, I was mixed on doing this as ideally people would upgrade
through the minor releases, going through the release notes. This also
saves us havin to audit deprecations to make sure they are all pointing
to the latest.
First, this isn't practical for users. Its annoying to pin your version (at least
its easier now that we pin `clap_derive` for users) and a lot of work to
go through them one step at a time.
On top of that, we've changed our deprecation policy to put the timing
of responding to deprecations into the user's hands with, with us
putting them behind the `deprecated` feature flag. This means someone
might respond to deprecations every once in a while or might not do it
until right before the 4.0 release. Our deprecation messages should be
updated to respond to that.
This supersedes #3616
This broke when we introduced clap_lex and then did a refactor on top.
We put in guards to say that escapes shouldn't happen but missed `--=`
which isn't quite an escape.
Not fully set on what error should be returned in this case (we are
returning roughly what we used to) but at least
we aren't panicing.
Fixes#3858
Between
- `ArgAction::SetTrue` storing actual values
- `ArgAction::Set` making it easier for derive users to override bool
behavior
- `Arg::default_missing_value` allowing hybrid-flags
- This commit documenting hybrid-flags even further
There shouldn't be anything left for #1649Fixes#1649
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
Though this is changing an API item we export, we do not consider this a
breaking change because
- This was an implementation detail of the macros and people shouldn't be using it directly
- The `macro_rules` macro is coupled to `clap` because they are in the
same crate
- The derive macro is coupled to `clap` because `clap` declares a
`=x.y.z` dependency on `clap_derive
Fixes#3828
- This matches the more container-like naming we are aiming for
- This provides an opportunity to warn people about moving away from
`ArgAction::IncOcccurrences` for flags, like the deprecation for
`ArgMatches::occurrences_of` to help people migrate in preparation for
clap 4 (rather than having the behavior change subtly in a way only
caught by thorough tests)
In addition, I feel `contains_id` has less ambiguous meaning than
`is_present`.
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
With `AnyValueParser` now private, we can also make `AnyValue` private.
Most users should not need to call `ValueParser::parse_ref` and doing
this gives us more implementation freedom for the future.
I'm a bit disappointed we don't have a way to control the action for the
help subcommand. Instead, people will need to provide their own and
disable ours. Long term, I want to design actions for subcommands but I
don't think its worth keeping `NoAutoHelp` around for it.
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 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.
Originally I hid all, assuming the flag-only use case but we had to
prevent that from showing up anyways. For the takes_value case, we
should be showing something since we know what it accepts. I decided to
only show the most basic values and hide the rest so as to not overwhelm
the user with redundant options and hope the user recognizes they are
redundant.
Now that flags can have meaningful defaults and with defaults being
implicitly set for certain actions, they appear in help but don't quite
make sense.
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 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.
This is the minimum set of actions for the derive to move off of
`parse`. These are inspired by Python's native actions.
These new actions have a "unified" behavior with defaults/envs. This
mostly means that occurrences aren't tracked. Occurrences were used as
a substitute for `ValueSource` or for counting values. Both cases
shouldn't be needed anymore but we can re-evaluate this later if needed.
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.
When creating `PendingValues`, I can't have the lifetime. I could make
it a `Cow` but decided to hold off instead since we don't need this
right now. Maybe by the time we do need it, we'll have another way of
doing this.
There is a default_missing_vals case which is slightly different because
its not actually a default but closing out the remaining argument that
was started in last iteration.
Before, if we were in trailing values that aren't delimite, we wouldn't
respect this flag and end processing of the value, now we do.
This also has a slight perf benefit of us only splitting the value if
the delimiter is present. We checked for the delimiter anyways, so
doing it first removes a slight bit of work.
I also feel this helps clarify the intended behavior and ooches us
towards a unified code path for actions.
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.
Inferred flags can make it hard for a future action to trigger behavior
off of the selected alias, like we might want to do for negations, so we
are now translating to the intended arg.
This will also help for debugging.
For most users, this won't be worth doing, they can just specify the
parser if needed. Where this has value is crates that integrate custom
types into clap, like creating click-like file integration. See
https://click.palletsprojects.com/en/8.0.x/arguments/#file-arguments
Clap has focused on reporting development errors through assertions
rather than mixing user errors with development errors. Sometimes,
developers need to handle things more flexibly so included in #3732 was
the reporting of value accessor failures as internal errors with a
distinct type. I've been going back and forth on whether the extra
error pessimises the usability in the common case vs dealing with the
proliferation of different function combinations. In working on
deprecating the `value_of` functions, I decided that it was going to be
worth duplicating so long as we can keep the documentation focused.
The remove functions no longer return `Arc` but the core type, at the
cost of requiring `Clone`. I originally held off on this
in #3732 in the hope of gracefully transition the derive and requiring
`Clone` would have been a breaking change but when it came to #3734, I didn't
find a way to make it work without a breaking change, so I made it
opt-in. This means I can force the `Clone` requirement now.
I added the requirement for `Clone` everywhere else in the hopes that in
the future, we can drop the `Arc` without a breaking change.
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.
`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
There are several approaches with this
- `value_parser(N..M)`: creates an i64 range
- `value_parser(value_parser!(u16).range(10..))`: creates an u16 range
that starts at 10
- `RangeI64ValueParser`: create whatever range you want
I was hoping to generalize `RangeI64ValueParser` for any source type,
not just i64, but ran into issues and decided to punt. I chose `i64` as
the source type as it seemed the most general and didn't run into
portability issues like `isize`.
This is a step towards #3199. All that is left is for the derive to use
this.
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.
