Commit graph

5104 commits

Author SHA1 Message Date
Ed Page
f890bfa93b docs: Focus top-level README 2021-11-30 09:53:25 -06:00
Ed Page
ea73ec521b
Merge pull request #44 from epage/examples
docs: Prefer `global_setting`
2021-11-29 16:40:20 -06:00
Ed Page
96da9cacb1
Merge pull request #43 from epage/placeholder
fix: Consistent help between Args and Subcommands
2021-11-29 16:27:58 -06:00
Ed Page
30f5872a71 fix: Consistent help between Args and Subcommands
`App::subcommand_placeholder` encompassed
- `Arg::value_name`
- `Arg::help_heading`

Split it and renamed it to make it more consistent.
2021-11-29 16:17:02 -06:00
Ed Page
54228ef7d7 docs: Prefer global_setting
I've been finding I've been setting `AppSettings` without it which is
likely leading to bugs.  This tries to raise the visibility by using it
based on the setting being used and not whether the application needs
it.
2021-11-29 16:10:54 -06:00
Ed Page
e1db873e2c
Merge pull request #41 from epage/utf8
fix: Detect when AllowInvalidUtf8 is needed
2021-11-29 15:53:26 -06:00
Ed Page
b8c34c3b57 fix: Detect when AllowInvalidUtf8 is needed
Fixes #36
2021-11-29 15:37:44 -06:00
Ed Page
c5f5c49766 refactor(parser): Use modern '?' 2021-11-29 14:20:25 -06:00
Ed Page
8a1099f921 refactor(parser): More context when creating a MatchedArg 2021-11-29 14:01:08 -06:00
Ed Page
211d36efad refactor(parser): Be consistent on terms 2021-11-29 14:01:02 -06:00
Ed Page
c7aa471deb
Merge pull request #40 from epage/derive_vec
fix(derive): Define multiple policy for Special Types
2021-11-29 13:33:05 -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
ac0f59ef73
Merge pull request #38 from epage/rename
Handle more naming issues
2021-11-29 12:10:22 -06:00
Ed Page
5911b64255
Merge pull request #39 from epage/ci
chore(ci): Verify unicode feature
2021-11-29 11:46:33 -06:00
Ed Page
e4c5d9d68d chore(ci): Verify unicode feature
In #27, we removed some default features.  When doing so, some places
weren't updated but `doc` feature covered it ... except it was only
partially updated.  This makes sure we test all the features.
2021-11-29 11:30:23 -06:00
Ed Page
44700506eb docs: Be consistent in builder args 2021-11-29 11:21:45 -06:00
Ed Page
62d7a3a928 fix: Be consistent on hide/hidden
- `PossibleValue::hidden` -> `PossibleValue::hide` (new in clap3, no
  breakin change)

Fixes #33
2021-11-29 10:58:00 -06:00
Ed Page
57e5fc2b07 fix: Rename to Arg::ignore_case like ArgSettings
Fixes #32
2021-11-29 10:34:42 -06:00
Ed Page
8fc12586bb fix: Make AppSettings::HidePossibleValues mirror ArgSettings
Fixes #31
2021-11-29 10:28:31 -06:00
Ed Page
6316e8a7fe
Merge pull request #37 from epage/unset
docs: Emphasize `Arg` over `ArgSettings`
2021-11-29 10:12:05 -06:00
Ed Page
eae3ffb599 docs: Emphasize Arg over ArgSettings 2021-11-29 09:54:04 -06:00
Kurt Wolf
a9f4d759c0 Allow bash completions to work with an alias (clap-rs/clap#2054) 2021-11-29 09:02:52 -06:00
bors[bot]
39374acb90
Merge #3054
3054: Allow bash completions to work with an alias r=pksunkara a=kurtbuilds



Co-authored-by: Kurt Wolf <kurtwolfbuilds@gmail.com>
2021-11-28 22:04:36 +00:00
Kurt Wolf
36a6360055 Allow bash completions to work with an alias 2021-11-28 12:15:42 -05:00
Ed Page
bc4c29056f
Merge pull request #35 from epage/docs
doc: Polish reference API
2021-11-24 20:00:32 -06:00
Ed Page
d1eec17d03 docs: Remove references to YAML 2021-11-24 16:09:56 -06:00
Ed Page
a2f0863a30 docs: Polish reference API 2021-11-24 16:09:53 -06:00
Ed Page
7bb729fe25
Merge pull request #30 from epage/doc
docs: Include more features in rustdoc
2021-11-24 14:28:20 -06:00
Ed Page
6a56a98a12 docs: Include more features in rustdoc 2021-11-24 14:07:57 -06:00
Ed Page
cdff449d19
Merge pull request #29 from epage/expected
fix: Rename HelpRequired to HelpExpected
2021-11-24 11:57:49 -06:00
Ed Page
314a6a36bb fix: Rename HelpRequired to HelpExpected
This both distances itself from our 'require' terminology and aligns
itself with `Option::expect`, making it more likely for people to guess
the intended behavior.
2021-11-24 11:38:57 -06:00
Ed Page
5210744d3a
Merge pull request #26 from epage/hyphen
fix: Rename App's AllowLeadingHyphen to AllowHyphenValues
2021-11-24 11:38:26 -06:00
Ed Page
af76c215b7
Merge pull request #28 from epage/debug
Color debug output
2021-11-24 11:36:31 -06:00
Ed Page
e6fca5446b
Merge pull request #27 from epage/features
fix!: Lighten clap's default feature set
2021-11-24 11:36:25 -06:00
Ed Page
c15a0bf5b3 fix: Rename App's AllowLeadingHyphen to AllowHyphenValues
This aligns us with `Arg::allow_hyphen_values` in clap2.
2021-11-24 11:25:48 -06:00
Ed Page
4b72d3cc7f feat: Color debug output 2021-11-24 11:21:40 -06:00
Ed Page
463d75474e refactor(color): Track style, rather than details
This makes it easier for us to compose.  Before, we had to infer things
like "bold" based on the color.  Now we just say "error" and get all of
the formatting specific to that.
2021-11-24 11:21:40 -06:00
Ed Page
c0f0713248 fix!: Lighten clap's default feature set
Too many times people have to disable default features.  Let's try to
have a more minimal out of box experience.

- `derive`: people are already used to adding this feature for serde
- `cargo`: not needed for derive
- `env`: most probably don't use this
- `unicode`: most CLIs are probably ASCII.  We should do a debug warn
  about this though

BREAKING CHANGE: `derive`, `cargo`, `env`, and `unicode` are no longer
on by default.
2021-11-24 10:35:29 -06:00
Ed Page
6a580d4de2 fix: Deprecate, rather than remove, AllowLeadingHyphen 2021-11-24 10:24:18 -06:00
Pavan Kumar Sunkara
afa7346f74 Remove extern crate in doc tests to fix coverage (clap-rs/clap#3047) 2021-11-24 09:17:20 -06:00
Ed Page
c2c9f0acb1
Merge pull request #23 from epage/examples
test: Verify examples based on feature flags
2021-11-24 09:08:43 -06:00
bors[bot]
6fae3f1a07
Merge #3047
3047: Remove extern crate in doc tests to fix coverage r=ldm0 a=pksunkara



Co-authored-by: Pavan Kumar Sunkara <pavan.sss1991@gmail.com>
2021-11-24 09:03:52 +00:00
Ed Page
9c4194a5a1 test: Verify examples based on feature flags 2021-11-23 17:10:01 -06:00
Ed Page
020d55e832
Merge pull request #22 from epage/ci
Fix CI bugs
2021-11-23 16:40:24 -06:00
Ed Page
da03c2706c chore(ci): Run build/test all crates 2021-11-23 16:10:32 -06:00
Ed Page
6b5e7e28df chore(ci): Test benchmarks 2021-11-23 16:09:31 -06:00
Mooneyhan
8bc8967498 corrected minor grammar mistakes in README.md (clap-rs/clap#3033) 2021-11-23 13:25:47 -06:00
Ed Page
0fccd07001
Merge pull request #21 from epage/trycmd
test: More thoroughly test examples
2021-11-23 13:24:22 -06:00
Ed Page
bfa02fd418 test: More thoroughly test examples
This ports our example testing over to [trycmd](https://docs.rs/) so
we can:
- More thoroughly test our examples
- Provide always-up-to-date example usage

The old way of testing automatically picked up examples.  This new way
requires we have a `.md` file that uses the example in some way.

Notes:
- Moved overall example description to the `.md` file
- I added cross-linking between related examples
- `14_groups` had a redundant paragraph (twice talked about "one and
  only one"
2021-11-23 13:13:41 -06:00
Ed Page
d8b12a6bb5
Merge pull request #20 from epage/macro
Deprecate YAML and Usage Parser
2021-11-23 12:09:51 -06:00