Commit graph

12 commits

Author SHA1 Message Date
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
Ed Page
1cdb2250e8 fix(derive): Define multiple policy for Special Types
Before:
- `bool`: a flag
- `Option<_>`: not required
- `Option<Option<_>>` is not required and when it is present, the value
  is not required
- `Vec<_>`: multiple values, optional
- `Option<Vec<_>>`: multiple values, min values of 0, optional

After:
- `bool`: a flag
- `Option<_>`: not required
- `Option<Option<_>>` is not required and when it is present, the value
  is not required
- `Vec<_>`: multiple occurrences, optional
  - optional: `Vec` implies 0 or more, so should not imply required
- `Option<Vec<_>>`: multiple occurrences, optional
  - optional: Use over `Vec` to detect when no option being present when
    using multiple values

Motivations:

My priorities were:
1. Are we getting in the users way?
2. Does the API make sense?
3. Does the API encourage best practices?

I was originally concerned about the lack of composability with
`Option<Option<_>>` and `Option<Vec<_>>` (and eventually `Vec<Vec<_>>`).
It prescribes special meaning to each type depending on where it shows
up, rather than providing a single meaning for a type generally.  You
then can't do things like have `Option<_>` mean "required argument with
optional value" without hand constructing it.  However, in practice the
outer type correlates with the argument occurrence and the inner type
with the value.   It is rare to want the value behavior without also the
occurrence behavior.  So I figure it is probably fine as long as people
can set the flags to manually get the behavior they want.

`Vec<_>` implies multiple occurrences, rather than multiple values.
Anecdotally, whenever I've used the old `Arg::multiple`, I thought I was
getting `Arg::multiple_occurrences` only.  `Arg::multiple_values`,
without any bounds or delimiter requirement, can lead to a confusing
user experience and isn't a good default for these.  On top of that, if
someone does have an unbounded or a delimiter multiple values, they are
probably also using multiple occurrences.

`Vec<_>` is optional because a `Vec` implies 0 or more, so we stick to
the meaning of the rust type.  At least for me, I also rarely need a
required with multiple occurrences argument but more often need optional
with multiple occurrences.

`Option<Vec<_>>` ends up matching `Vec<_>` which can raise the question
of why have it.  Some users might prefer the type.  Otherwise, this is
so users can detect whether the argument is present or not when using
`min_values(0)`.  Rather than defining an entire policy around this and
having users customize it, or setting `min_values(0)` without the rest
of a default policy, this gives people a blank slate to work from.

Another design option would have been to not infer any special-type
settings if someone sets a handful of settings manually, which would
have avoided the confusion in Issue clap-rs/clap 2599 but I see that
being confusing (for someone who knows the default, they will be
expecting it to be additive; which flags disable inferred settings?) and
brittle (as flags are added or changed, how do we ensure we keep this
up?).

Tests were added to ensure we support people customizing the behavior to
match their needs.

This is not solving:
- `Vec<Vec<_>>`, see clap-rs/clap 2924
- `(T1, T2)`, `Vec<(T1, T2)>`, etc, see clap-rs/clap 1717
- `Vec<Option<_>>` and many other potential combinations

Fixes clap-rs/clap 1772
Fixes clap-rs/clap 2599
See also clap-rs/clap 2195
2021-11-29 13:16:12 -06:00
Ed Page
78e4c90326 refactor(tests): Prepare for Special Type experiments
In experimenting on #1772, I want to write test cases for various
combinations of required or not, values vs occurrences, etc.  There
wasn't really a clear place to put these.

On top of that, I wanted there to be a clear place in the tests for
describing the behavior of special types, to make it easier to audit and
easier to see how a PR for #1772 changes things.

As part of this effort in organizing these tests, I reduced the number
of tests that use special types.  This better focuses these tests on the
cases they are intending to cover, rather than pulling in unrelated
features.  This makes it easier to audit special types and makes it so
failures give more focused results, making it easier to see what broke.
2021-11-04 13:12:01 -05:00
Ed Page
4b7ed54d7e test(derive): Provide better error info
`Parser::parse_from` will call `exit` on failure and we don't just lose
backtrace information but we don't even know which of the tests running
in parallel panicked.  I ran into this when experimenting with
`clap_derive` and I couldn't tell what actually failed.

So let's switch to `Parse::try_parse_from`.

Errors went from:
```
test option_option ... ok
error: Found argument 'bar' which wasn't expected, or isn't valid in this context

USAGE:
    clap_derive [OPTIONS]

For more information try --help
error: test failed, to rerun pass '--test arg_enum'
```
To:
```
test option_option ... ok
test variant_with_defined_casing ... ok
test skip_variant ... ok
test default_value ... ok
test vector ... FAILED
test option_vector ... ok

failures:

---- vector stdout ----
thread 'vector' panicked at 'called `Result::unwrap()` on an `Err` value: Error { message: Formatted(Colorizer { use_stderr: true, color_when: Auto
, pieces: [("error:", Some(Red)), (" ", None), ("Found argument '", None), ("bar", Some(Yellow)), ("' which wasn't expected, or isn't valid in this
 context", None), ("\n\n", None), ("USAGE:\n    clap_derive [OPTIONS]", None), ("\n\nFor more information try ", None), ("--help", Some(Green)), ("
\n", None)] }), kind: UnknownArgument, info: ["bar"], source: None, backtrace: Backtrace }', clap_derive/tests/arg_enum.rs:388:56
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

failures:
    vector

test result: FAILED. 15 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

error: test failed, to rerun pass '--test arg_enum'
```
2021-10-30 10:00:34 -05:00
Ed Page
60c9c2e59a docs(derive): Use more-specific traits
This helps to raise visibility of the new derive traits.

I didn't touch ui tests because there were a lot and they didn't seem to
be as high value.
2021-10-12 07:51:11 -05:00
Ed Page
d840d5650e fix(derive)!: Rename Clap to Parser.
Before #2005, `Clap` was a special trait that derived all clap traits it
detected were relevant (including an enum getting both `ArgEnum`,
`Clap`, and `Subcommand`).  Now, we have elevated `Clap`, `Args`,
`Subcommand`, and `ArgEnum` to be user facing but the name `Clap` isn't
very descriptive.

This also helps further clarify the relationships so a crate providing
an item to be `#[clap(flatten)]` or `#[clap(subcommand)]` is more likely
to choose the needed trait to derive.

Also, my proposed fix fo #2785 includes making `App` attributes almost
exclusively for `Clap`.  Clarifying the names/roles will help
communicate this.

For prior discussion, see #2583
2021-10-09 20:12:03 -05:00
Ed Page
9afa08ff50 fix(derive): Support SubcommandsNegateReqs
Before there was no way to make `SubcommandsNegateReqs` with
`clap_derive` because it required a required field with a sentinel value
for when the required part was negated.  We blocked that.

This turned out simpler than I expected.

This came out of the discussion for #2255 but that issue is more
specifically about the panic, so not closing it.
2021-10-05 16:02:02 -05:00
patrick-gu
eca8ba6098 Make multiple_values false with Option<Option<...>> 2021-08-01 14:50:31 -07:00
Pavan Kumar Sunkara
3f94d17c71 Removed Arg::multiple 2021-06-16 07:17:11 +01:00
CreepySkeleton
5d9ef1527f Fix warnings in tests & examples 2020-03-05 13:40:25 +03:00
Pavan Kumar Sunkara
dd75cee72c fix: Clippy should pass 2020-02-01 06:48:50 +01:00
Pavan Kumar Sunkara
5e8f424dfe Merged clap_derive using git-subtree 2020-01-18 17:40:07 +05:30