Commit graph

135 commits

Author SHA1 Message Date
Ed Page
439c9e7a91 feat(help): Expose clap's indentation to help_template
This will make it easier for help templates to be consistent with clap
2022-08-31 15:42:59 -05:00
Ed Page
65b5b5f7bf fix(help): Remove name/version/author from help
This is to help shorten it and polish it by removing redundant
information.

This is a part of #4132
2022-08-31 15:06:15 -05:00
Ed Page
c1c269b427 fix(help): Clarify short vs long help
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
2022-08-31 14:25:46 -05:00
Ed Page
42c943844c fix(help): Use Command in place of Subcommand
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
2022-08-31 08:53:10 -05:00
Ed Page
36460aed08 fix: Deprecate _os variants
PR #4096 made them redundant
2022-08-29 12:42:30 -05:00
Ed Page
9b23a09f7a fix(help): Don't rely on ALL CAPS for headers
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.
2022-08-26 10:21:18 -05:00
Ed Page
c6155f62d5 feat: Open the door for user styling in the future
This added about 10 KiB to the `.text` which I cannot explain why
2022-08-24 18:17:42 -05:00
Ed Page
91e55c6b9c fix: Switch OsStr's in builder to owned/borrowed type
This is a part of #1041

Because `Option<Into<T>>` is ambiguous for `None`, we had to create
`Resettable` to workaround it.
2022-08-16 14:53:36 -05:00
Ed Page
9074b60194 feat(parser): Make customizeing flags easier
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.
2022-08-19 08:21:55 -05:00
Ed Page
09354dec21 fix: Allow non-bool value_parsers for SetTrue
Not sure if we could have originally made this work but it definitely
does now that we use `default_missing_value` for this (#4000)
2022-08-18 21:35:29 -05:00
Ed Page
2de59195aa fix!: Prefer IntoIterator over &[]
The main breakinge change cases:
- `&[char]`: now requires removing `&`
- All other non-ID `&[_]`: hopefully #1041 will make these non-breaking

Fixes #2870
2022-08-15 13:26:17 -05:00
Ed Page
43e961d24f style: Address clippy 2022-08-11 16:07:58 -05:00
Ed Page
07b6e66eb7 fix: No implicit version/help actions
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
2022-08-10 21:21:53 -05:00
Daniel Parks
1a2ae76738
fix(derive): Add "id" attribute
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
2022-08-09 12:15:02 -07:00
Ed Page
69ad5cfd84 test(derive): Highlight current behavior for version/help 2022-08-05 14:22:09 -05:00
Ed Page
ba15b5f430 fix!: Rename Arg::number_of_values to Arg::num_args 2022-08-03 14:45:47 -05:00
Ed Page
470531b515 fix!: Replace multiple_values with number_of_values
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.
2022-08-01 15:50:23 -05:00
Ed Page
76bff6f34e fix!: Remove rest of deprecated APIs
Fixes #4009
2022-08-01 15:21:33 -05:00
Ed Page
ac32c831fc fix(help): Remove '...' for optional values 2022-07-29 09:44:29 -05:00
Ed Page
ccf35ff70c fix!: Replace min_values (total) with number_of_values (per occurrence) 2022-07-28 17:13:41 -05:00
Ed Page
4f756c483f fix(derive): Make consistent with arg!
This has the downside of a regression in `--help`.  We expect to fix
that soon-ish.
2022-07-28 16:52:06 -05:00
Ed Page
6f03b4f948 fix!: Remove multiple occurrences in favor of Append/Count
For num_vals and friends, this only implements hacks until #2688

Fixes #3021
2022-07-25 13:23:43 -05:00
Emerson Ford
04e0ed7474 feat(clap_derive): Add default_values_t and default_values_os_t 2022-07-25 10:14:04 -07:00
Ed Page
11076a5c70 fix(help)!: Make DeriveDisplayOrder the default, removing it
Force sorting with `next_display_order(None)`

Fixes #2808
2022-07-22 15:52:03 -05:00
Ed Page
7068586246 fix(derive)!: Remove deprecated parse attribute 2022-07-22 12:14:29 -05:00
Ed Page
01a3ea425f fix!: Remove unstable-v4 feature gate 2022-07-22 11:34:06 -05:00
Ed Page
09c6405d5c fix!: Remove validator 2022-07-21 16:05:39 -05:00
Ed Page
7d403fad78 test: Remove legacy cases 2022-07-21 13:38:24 -05:00
Ed Page
ff0796b014 fix(derive)!: Remove old derive names 2022-07-21 12:57:12 -05:00
omjadas
4d521429be test: Add test for default_value_os_t 2022-06-15 13:46:59 +10:00
Ed Page
0a529c14cc fix(derive): Switch default actions/parsers for unstable-v4 2022-06-13 18:59:58 -05:00
Ed Page
cc76d2881c test(derive): Allow specializing tests for unstable-v4 2022-06-13 17:00:39 -05:00
Ed Page
3686244264 test(derive): No longer supporting some wrapped types
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.
2022-06-13 16:56:34 -05:00
Ed Page
b7668e84f5 test: Don't run legacy tests with v4 behavior 2022-06-13 16:47:25 -05:00
Ed Page
483b64ee8e test(derive): Update another case to new approach 2022-06-13 16:45:09 -05:00
Ed Page
9caec5a52d fix(parser): Deprecate ArgMatches::is_present 2022-06-10 14:21:25 -05:00
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
14a62e11fd fix(parser): Deprecate multiple_occurrences
Fixes #3772
2022-06-08 09:54:23 -05:00
Ed Page
1879826b21 fix(parser): Deprecate StoreValue / IncOccurrences Actions
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`.
2022-06-06 13:41:27 -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
b09def1ad0 test(derive): Verify doc comments on ArgEnum 2022-06-04 12:58:53 -05:00
Ed Page
11fbe7e54b test(derive): Improve help output assertions 2022-06-04 12:58:53 -05:00
Ed Page
5db611384e test(derive): Ensure we don't break compatibility 2022-06-02 16:56:14 -05:00
Ed Page
773ba94c4e refactor(derive): Merge handling of bool/from_flag
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
2022-06-02 13:01:59 -05:00
Ed Page
256643f8d3 fix: Deprecate possible_values 2022-05-25 12:57:11 -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
a35df14caf feat(derive): Opt-in to inferred value_parser 2022-05-20 19:25:20 -05:00
Ed Page
b52c7f115e feat(derive): Allow users to opt-in to ValueParser
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 #3734
Fixes #3496
Fixes #3589
2022-05-20 15:38:44 -05:00
Ed Page
d826ab9445 fix(derive): Move args to new 'get_one'/'get_many' API 2022-05-16 15:16:51 -05:00
Ed Page
2e3540355a fix(derive): Don't change case of Arg id's (unstable)
This will make it easier to reference arguments with different
attributes.

Fixes #3282
2022-05-09 10:36:03 -05:00
Ed Page
f7e4dd23d6 refactor(derive): Divide rename_all assertions 2022-05-06 16:47:52 -05:00
Ed Page
ddc9d54f41 refactor(derive): Generalize test name 2022-05-06 16:45:03 -05:00
Ed Page
fe4888d668 refactor(derive): Group subcommand rename tests 2022-05-06 16:43:23 -05:00
Ed Page
65538e21a8 fix(derive): Detect escaped ambiguous subcommands (unstable) 2022-05-06 15:46:34 -05:00
shir0kamii
fb4755d1c3 feat(derive): Don't abort when non-unit variant is skipped 2022-03-31 18:49:21 +02:00
plaflamme
154c0d0c65
test: Add test to demonstrate regression 2022-03-06 23:09:55 -05:00
Ed Page
cb937641fa fix(derive): Allow other attributes with subcommand that has subcommands
This was overlooked when we added support for `#[clap(subcommand)]` to
variants.

Fixes #3504
2022-02-23 09:23:33 -06:00
Ed Page
ddac492302 fix: Rename IntoApp to CommandFactory
This is part of the `App` rename.

Previously, I was concerned about not being able to deprecate

For backwards compatibility, we still expose the `IntoApp` name.
2022-02-15 08:24:00 -06:00
Ed Page
c3fec1fa75 fix: Update derive->Command function name
No good solution for transitioning the trate name, unfortnately, since
we can't mark `use`s as deprecated (we can, it just does nothing).

I got rid of the `into` prefix because that implies a `self` parameter
that doesn't exist.
2022-02-14 16:04:10 -06:00
Ed Page
e8010e79a9 refactor: Update app variables to cmd 2022-02-14 15:55:56 -06:00
Ed Page
c4144d7d6c docs: Update App references to Command 2022-02-14 15:33:49 -06:00
Ed Page
d3f5d7ce34 fix: Clarify Arg/ArgGroup id's role
This adjusts names.  Adjusting the derive naming (and re-naming) is left
to #2475.

Fixes #3335
2022-02-11 14:11:50 -06:00
Ed Page
06d43a02da fix(help): Subcommand help looks like --help
Like was said in #2435, this is what people would expect.

While we should note this in a compatibility section in the changelog, I
do not consider this a breaking change since we should be free to adjust
the help output as needed.  We are cautious when people might build up
their own content around it (like #3312) but apps should already handle
this with `--help` so this shouldn't be a major change.

We aren't offering a way for people to disable this, assuming people
won't need to.  Longer term, we are looking at support "Actions" (#3405)
and expect those to help customize the flags.  We'll need something
similar for the `help` subcommand.

Fixes #3440
2022-02-11 12:47:34 -06:00
Ed Page
272f840178 feat: Replace core set of AppSettings with functions
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.
2022-02-11 12:35:09 -06:00
Ed Page
6ad52f41b3 feat: Allow disabling derive display order
In clap 4.0, we will make `DeriveDisplayOrder` the default and this is
how you'll disable it.

This is part of #2808
2022-02-07 19:19:11 -06:00
Ed Page
5290f82133 feat: Override DeriveDisplayOrder behavior with App::next_display_order
For the derive API, you can only call `next_display_order` when dealing
with a flatten.  Until we offer app attributes on arguments, the user can workaround with
this no-op flattens.

This is a part of #1807
2022-02-07 19:19:11 -06:00
Ed Page
c00f71ec4a feat: Add App::next_help_heading
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.
2022-02-07 19:19:01 -06:00
Ed Page
4538d618a7 refactor: Migrate off of .kind 2022-02-01 11:27:08 -06:00
Peter Grayson
7eea7d27ad
fix(help): Optional arg values in brackets
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>
2022-01-26 12:03:23 -05:00
Ed Page
3326a11be0 fix(derive): Don't assume use clap::ArgEnum
The error was when doing `#[clap(arg_enum, default_value_t = ...)]`.

Good example of why we should minimize `use`, at least in tests
(besides reducing merge conflicts, code churn, etc).
2022-01-10 15:41:58 -06:00
Noa
ffd991f0ae
chore: Fix clap_derive license headers 2022-01-04 14:25:48 -06:00
Ed Page
6b9ae5404c fix(derive): Don't enit warnings
We missed covering `Args` warnings when using struct variants.

Fixes #3245
2022-01-03 11:35:34 -06:00
Ed Page
8924dd7a1e feat(derive): Don't require Display for default ArgEnum
While I'm unsure how much type specialization we should do, we
intentionally have the `arg_enum` attribute for doing special behavior
based on it, so let's take advantage of it.

Fixes #3185
2021-12-16 09:11:32 -06:00
Ed Page
9e64387ef0 revert(help): Partial revert of 3c049b4
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
2021-12-15 10:36:59 -06:00
Ed Page
d55f040bbd fix(derive): Set both about/long_about with doc comments
The main care about is that when we override a `flatten` / `subcommand`
doc comment in a parent container, that we make sure we take nothing
from the child container, rather than implicitly taking one `about` ut
not `long_about`.

To do this, and to play the most safe with long help detection, we reset
`long_about` to default when there is no doc comment body to use for
`long_about`.

Fixes #2983
2021-12-14 11:07:57 -06:00
Ed Page
1811f5e7af test(derive): Show current doc comment behavior
Based on #2983
2021-12-14 11:07:54 -06:00
Ed Page
7c10b5a9b4 fix(derive): Treat default_value_os like default_value
The test went from panicing to not-panicing

Fixes #3031
2021-12-13 16:25:49 -06:00
Ed Page
703238f155 test(derive): Check all derives
There will always be some kind of corner case not covered as code
evolves but this expands the test to all of the basics.
2021-12-10 10:52:30 -06:00
Ed Page
71a564de88 test(derive): Don't parse the actual command line 2021-12-10 10:36:45 -06:00
Frankie Foston
1285c0f885 fix: unqualified result types causing compilation failures with derive implementations 2021-12-10 14:13:26 +00:00
Ed Page
f517c0ede1 docs: Remove author fields 2021-12-06 11:24:23 -06:00
Ed Page
888c27048d docs: Update changelog 2021-12-02 20:26:21 -06:00
Ed Page
500def4904 fix(derive): Smooth out transition for structopt
Adding in a `StructOpt` derive with `structopt` attributes, with
deprecation notices.  Unofrtunately, not as many deprecation warnings as
I would like.  Apparently, you can't do them for a `use` of a derive?  I
also wanted to inject code that would trigger a deprecation notice for
attributes but that would require enough of a refactor that I didn't
consider it worth it.  We are at least providing a transition window
even if it means we'll have to remvoe it next major release without a
deprecation warning.
2021-12-02 20:18:33 -06:00
Ed Page
b190a6a817 test: Consolidate clap tests
This reduces the need for us to have `clap` as a dependency in
`clap_derive`, preparing the way to fix #15.
2021-11-30 10:07:08 -06:00