Commit graph

295 commits

Author SHA1 Message Date
Ed Page
31b22d1a51 perf(parser): Take up less memory with ArgAction::Count
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
2022-06-09 11:09:38 -05:00
Ed Page
9e38353442 fix(derive): Clarify ArgEnum as ValueEnum
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.
2022-06-08 11:14:09 -05:00
Ed Page
8dde489e3a docs(tutorial): Update for new API 2022-06-08 10:35:06 -05:00
Ed Page
14a62e11fd fix(parser): Deprecate multiple_occurrences
Fixes #3772
2022-06-08 09:54:23 -05:00
Ed Page
86a162d1bb fix(parser): Deprecate occurrences_of
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`
2022-06-07 13:30:32 -05:00
Ed Page
1428785677 fix(parser): Deprecate args_override_self
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
2022-06-06 14:57:24 -05:00
Ed Page
647896d929 feat(derive): Expose control over Actions
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
2022-06-06 11:35:07 -05:00
Ed Page
f4004b653b refactor(derive): Give new-style highest precedence
This exposed a potential bug but I figure it isn't worth fixing without
actions.
2022-06-02 16:46:50 -05:00
Ed Page
b39d3d4f2b docs(derive): Make raw attribute more discoverable
Based on feedback in #3189
2022-05-30 18:41:10 -05:00
Yuri Astrakhan
3fd5e4bc33
fix cargo.toml link 2022-05-27 07:43:09 -04:00
Ed Page
fcdd31781b feat(parser): Allow people to plug into 'value_parser' macro
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
2022-05-25 14:12:27 -05:00
Ed Page
177511dab1 fix: Deprecate validator / validator_os
`validator_regex` is being ignored for now as I await on a comment
period for #3743
2022-05-25 12:57:11 -05:00
Ed Page
eda0ca54c1 fix(parser): Simplify the common getter API
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.
2022-05-25 10:50:42 -05:00
Ed Page
ed45de2f03 fix(parser): Clean up remove types
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.
2022-05-24 16:25:07 -05:00
Ed Page
b3847d12f0 docs(ref): Update for _ref derive 2022-05-24 14:53:08 -05:00
Ed Page
33e94df212 docs(example): Update for value_parser 2022-05-24 14:53:08 -05:00
Ed Page
15616bbd13 fix(error): Remove usage from value validation
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.
2022-05-23 20:56:04 -05:00
Ed Page
e23800e10e doc(derive): Update for value_parser 2022-05-20 20:02:23 -05:00
Ed Page
a35df14caf feat(derive): Opt-in to inferred value_parser 2022-05-20 19:25:20 -05:00
Ed Page
686b0379ce feat(multicall): Stablize multicall
`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
2022-05-20 12:20:40 -05:00
Ed Page
8824ad0df0 docs(tutorial): Link derive to builder API 2022-05-03 15:44:54 -05:00
Ed Page
253e579781 docs(tutorial): Gradually add concepts for args 2022-05-03 15:40:11 -05:00
Ed Page
97a5c27d74 docs(tutorial): Clarify subcommand wording 2022-05-03 15:40:08 -05:00
Ed Page
396ea15a41 docs(tutorial): Link Parser attributes with Command functions 2022-05-03 15:40:04 -05:00
Ed Page
414ae57a2a fix(multicall): Improve bad multicall binary error
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.
2022-05-02 09:12:12 -05:00
Ed Page
ec4735a44e docs: Add REPL example
This is to help in cases like #3668 and #3673
2022-05-02 06:27:57 -05:00
Ed Page
d411e7a2fa docs(ref): Be more explicit with ArgEnums 2022-04-29 19:32:10 -05:00
Ed Page
5be61a199c docs(examples); Call out optional subcommands 2022-04-01 09:27:29 -05:00
shir0kamii
fb4755d1c3 feat(derive): Don't abort when non-unit variant is skipped 2022-03-31 18:49:21 +02:00
shir0kamii
ee3d12ec56 fix(derive): Abort on non-unit variant 2022-03-30 03:49:14 +02:00
Ed Page
731d18f300 docs(examples): Fix help output 2022-03-25 07:20:46 -05:00
Ed Page
429e1d3f31 docs: Fix examples
CI didn't run for #3570, so we missed that some things were off on
Windows.
2022-03-23 12:31:13 -05:00
Ed Page
db863de6c1 docs(examples): Show how to do default subcommands
While we don't have a built-in mechanism, its relatively easy to support
with the APIs we provide.

Inspired by #3566
2022-03-23 11:08:07 -05:00
Ed Page
bdd5cf17f8 docs(examples): Show IP Address 2022-03-14 09:53:31 -05:00
Ed Page
4842f07045 docs(examples): Show duration parsing 2022-03-14 09:49:46 -05:00
Ed Page
c230c72120 docs(examples): Allow any path 2022-03-14 09:46:33 -05:00
Ed Page
ce9e2cba8f docs(examples): Show implicit parser 2022-03-14 09:43:17 -05:00
Ed Page
a8ffebbab9 docs(examples): Generalize key-value example 2022-03-14 09:38:04 -05:00
Ed Page
dbe8c0c957 docs(tutorial): Prefer custom parsing to validation 2022-03-14 09:31:40 -05:00
Matt Fellenz
17193bd074
docs(derive): Builder/Derive interop reference (#3515)
Fixes #3500
2022-03-07 14:43:51 -06:00
Jörg Wunderlich-Pfeiffer
92e1666868 docs: Fix link to example 2022-03-06 11:05:23 +01:00
Pavan Kumar Sunkara
8a9403a1df Fixes #3464 2022-03-05 14:25:12 +00:00
Ed Page
14ea156218 docs: Annotate more places with required features 2022-03-03 12:32:29 -06:00
Ed Page
d2863a228c
Merge pull request #3529 from epage/attrib
docs(derive): Shift structure around lang->builder
2022-03-02 18:18:34 -06:00
Lucas Kent
0fe8ca7d3c docs(derive): Shift structure around lang->builder
Before, we had the focus on attributes and how they were impacted by
various features.  Now we separate out language items and put both magic
and raw attributes under the type of attribute (command, arg, etc)
2022-03-02 16:14:51 -06:00
Steve Klabnik
f89c8f4da2 Fix a typo in an example 2022-03-02 08:41:08 -06:00
Moritz Mœller
22efb36983
Fixed broken Command Attributes link 2022-02-24 13:39:53 +01:00
Nils Homer
c13cd89ceb
Fix link to contributing 2022-02-22 20:36:54 -08:00
Ed Page
a7b7d43582 docs(derive): Call out 'Command' relationship 2022-02-22 18:09:47 -06:00
Ed Page
cb9cb251a9 style: Clean up 2022-02-22 17:47:46 -06:00