Commit graph

2991 commits

Author SHA1 Message Date
Dominik Nakamura
232d91b96e
docs: Describe the skip attribute for ValueEnums (#4328)
Documenting the `skip` attribute for the `ValueEnum` derive macro promptly, as it's not mentioned anywhere else.

Fixes #4327
2022-10-05 08:22:18 -05:00
Tony Gorez
7f98947c04
feat: expose is_multiple & get_args API for ArgGroup (#4336)
Fixes #4228
2022-10-03 15:21:53 -05:00
Ed Page
dd8e242773 fix(parser): Allow defaults for Help/Version
These didn't make sense for the builder but are helpful for the derive.
The assert was assuming people wouldn't do this and to catch internal
problems.

Fixes #4326
2022-10-01 13:37:24 -05:00
Ed Page
46e238febb docs: Fix outdated short comment
Noticed as part of #4311
2022-09-30 14:49:38 -05:00
Ed Page
16e5599b71 docs: Note that author doesn't show up by default 2022-09-30 13:27:46 -05:00
Ed Page
4eb3da20f7 docs(help): Include example with old template 2022-09-30 13:21:13 -05:00
Ed Page
db31881be5 docs: Remove references to global settings
These were copied over from the original `AppSettings` and never updated
despite never being relevant in this context.
2022-09-30 13:17:46 -05:00
Ed Page
973f30fb22 refactor(docs): Use intra-doc links to avoid breakages 2022-09-30 13:16:13 -05:00
Ed Page
e53447835c docs: Fix link to crate_authors macro 2022-09-30 13:15:58 -05:00
Ed Page
1065d6c36b feat(assert): Help people know about implicit ArgGroups 2022-09-30 12:56:43 -05:00
Ed Page
c16fdbedc1 docs: Clarify term_width requires wrap_help 2022-09-30 12:30:14 -05:00
Ed Page
5017f0d720 fxi(error): Don't report unrelated groups in requries errors 2022-09-30 11:18:47 -05:00
Ed Page
cb04c71105 fix(error): Don't report unrelated groups in conflict errors
Ideally, a conflict caused by a group itself would show the relevant
group but that is less important than showing a valid, non-garbage,
usage
2022-09-30 10:38:27 -05:00
Ed Page
2498147138 feat(derive): Allow skipping the implicit ArgGroup
This was prioritized to allow users to workaround problems when the
implicit `ArgGroup` is getting in the way.

Fixes #4279
2022-09-30 09:15:38 -05:00
Ed Page
b814c785ef docs(derive): Correct reference 2022-09-30 08:15:48 -05:00
Ed Page
8fc8b5f273 feat: Add ArgGroup::is_required_set
This is a part of #4228

I thought I needed this for another change but it turned out I didn't.
2022-09-29 16:29:08 -05:00
Ed Page
4634812e3d refactor: Use getters internally
This originally stemmed from wrapping `Arg` in a `Box`, but we had to
smash it with a hammer as it didn't improve things enough.

- This dropped binary size by 3-7 KiB
- Parsing slowed by 20%.
- Incremental rebuilds slowed down by 1%
2022-09-29 15:26:24 -05:00
Ed Page
84055f41e4 docs: Provide more nuance on allow_hyphen_values
This matches what we hope is the right behavior, see #4283
2022-09-29 14:41:39 -05:00
Ed Page
4e9f3cca2c fix(error): Specialize the self-conflicts error
Inspired by rust-lang/cargo#11159
2022-09-29 09:54:20 -05:00
Ed Page
5399f49572 fix(error): Quote literals consistently 2022-09-29 08:54:03 -05:00
Ed Page
2d86f96d64 fix(error): Stylize escape suggestions 2022-09-29 08:47:56 -05:00
Ed Page
549911a84a fix(error): Format help suggestion as literal 2022-09-29 08:43:05 -05:00
Ed Page
3683e2c791 fix(parser): Allow one-off self-overrides
bat needed this.

See also #4261
2022-09-28 16:45:35 -05:00
Ed Page
2d7874948f fix(parser): SetFalse should also not allow self-override 2022-09-28 16:26:36 -05:00
Wolf Thomsen
0f45ac7235
Fix inline code snippet typos
There are a couple of typos where a backtick is missing / too much which results in slightly broken formatting. This PR should hopefully fix them.
2022-09-28 21:26:56 +02:00
Ed Page
9cd1939535
Merge pull request #4269 from epage/usage
fix(error): Polish `--flag=bad-value` error
2022-09-27 09:42:11 -05:00
Ed Page
cb1cd67009 fix(error): Include failed arg in usage in --flag=bad-value error 2022-09-27 09:25:24 -05:00
Ed Page
12d76d649a fix(error): Include 'Usage:' title in --flag=bad-value error 2022-09-27 09:20:42 -05:00
Peter Grayson
7dd216b1e6
docs: Update multiline usage override rules
The styling of usage has changed in #4188 such that the usage string is on
the same line as the "Usage:" title. Previously, the usage went on the line
below the title. As such, the rules have changed for how to make a
multiline usage format correctly.

These updated rules achieve the following output for the documented
example:

    Usage: myapp -X [-a] [-b] <file>
           myapp -Y [-c] <file1> <file2>
           myapp -Z [-d|-e]

Relates-to: #4132
2022-09-26 21:57:09 -04:00
Ed Page
a5ce7a0187
Merge pull request #4262 from epage/conflict
fix(parser): Conflict-with-self is back on by default
2022-09-26 13:41:45 -05:00
Ed Page
9bccded7ed fix(parser): Conflict-with-self is back on by default
See #4261 for more details
2022-09-26 13:29:48 -05:00
Ed Page
4a1552cc0e perf: Drop use of Into::into for '?'
For binary size, this only dropped 0.2 KiB

For performance, before:
- parse_rustup_with_sc    time:   [7.9866 µs 8.0138 µs 8.0470 µs]
After:
- parse_rustup_with_sc    time:   [7.5387 µs 7.5722 µs 7.6157 µs]

For build-time, before
```console
$ hyperfine --warmup=1 --min-runs=5 "--prepare=cargo clean" "cargo build -F cargo --example cargo-example"
Benchmark 1: cargo build -F cargo --example cargo-example
  Time (mean ± σ):     16.988 s ±  1.190 s    [User: 68.178 s, System: 6.637 s]
  Range (min … max):   15.550 s … 18.277 s    5 runs
```
After:
```console
$ hyperfine --warmup=1 --min-runs=5 "--prepare=cargo clean" "cargo build -F cargo --example cargo-example"
Benchmark 1: cargo build -F cargo --example cargo-example
  Time (mean ± σ):     15.674 s ±  0.222 s    [User: 62.287 s, System: 4.608 s]
  Range (min … max):   15.426 s … 15.993 s    5 runs
```
2022-09-26 12:31:39 -05:00
Ed Page
c4b3a4f491 refactor: Remove use of '?' 2022-09-26 12:19:30 -05:00
Ed Page
3c9bca5ead fix(help)!: Wrapping is behind wrap_help
If users don't want `wrap_help` feature, they can put newlines in where
needed.  Seems odd to support wrapping when the wrap size is fixed.  For
those hard coding the lines, this will save them a decent amount of
size.
2022-09-26 11:45:44 -05:00
Ed Page
bac3eb3280 docs: Raise visibility of 'string' feature 2022-09-26 11:14:06 -05:00
Ed Page
bd6b67c605 style: Make clippy happy 2022-09-26 09:55:02 -05:00
Ed Page
31f9234cc7 feat(parser): Add From<str> and From<String> 2022-09-26 09:51:44 -05:00
Ed Page
931b6338f1 refactor(parser): Clarify FromStr from future FromStr 2022-09-26 09:51:03 -05:00
Ed Page
76ec238b45 docs: Clarify value_parser implementation 2022-09-26 09:50:51 -05:00
Ed Page
9f49c0c630 feat(parser): Support From<OsString> for value_parser 2022-09-26 09:50:49 -05:00
Ed Page
e64ed91a4e feat(parser): Support From<&OsStr> types for value_parser!
Last time I tried this, I wasn't able to resolve the lifetime issues.  I
seemed to have gotten it working this time.

This came up in #4254.
2022-09-26 09:50:12 -05:00
Ed Page
037b07577c feat: Expose ANSI styling to the user
This gives users the control over where clap outputs while still getting
colors.  For users who want to support old windows versions, check out
`fwdansi` crate.
2022-09-22 09:59:42 -05:00
Ed Page
a2272a2c50 feat(error): Add a 'render' method 2022-09-22 09:55:11 -05:00
Ed Page
4280fdfcbd fix(help): Replace help writers with renderers
The writer is less convenient and isn't offering any performance
benefits of avoidign the extra allocations, so let's render instead.

This supersedes #3874

Fixes #3873
2022-09-22 09:54:19 -05:00
Ed Page
652e71d616 fix(help)!: Provide styled usage to user
This will open us up to providing the user with access to the styled
version in the future.
2022-09-22 09:54:19 -05:00
Ed Page
a76f622d17 docs: Clarify when quoting is required for arg 2022-09-21 11:49:18 -05:00
Ed Page
2bbb81f311 docs: Clarify value parser
Things that tripped up a user
- Derive reference was misunderstood to say that the only alternative to
  the built-in value parser behavior was to implement
  `ValueParserFactory`
  - We now delegate to `value_parser!`s docs any talk of integrating
    into it (it should have been a subbullet of "not present" anyways)
- `value_parser!` relies too much on the example to demonstrate behavior
  when the user will likely make the determination of whether its
  relevant before then
  - We are now more upfront what type mappings are supported
- Too many steps to find all information
  - For example, a user needs to look at `TypedValueParser`
    implementations, `ValueParserFactory` implementations, and `From<T>
    for ValueParser` implementations to understand what all can be used
  - We are now more upfront with a lot of this information at the entry
    points the user is most likely to look at

In addition, I did an audit of the docs to make sure they were updated
for us only supporting the new behavior and all of the new APIs.

See https://www.reddit.com/r/rust/comments/xjlie4/preannouncing_clap_40_a_rust_cli_argument_parser/ip9kzf1/
2022-09-21 11:11:21 -05:00
Ed Page
99dfe7404a docs(ref): Remove dead example
This was missed in the migration to the reference being on docs.rs.  Not
feeling its worth finding a way to integrate it into the new structure.
2022-09-21 11:02:08 -05:00
Ed Page
4674e43493 fix(error): Remove RawFormatter
The likelihood of using this is a lot lower now with `KindFormatter` and
`error-context` feature flag.

People can implement it themselves.
2022-09-20 13:40:18 -05:00
Ed Page
90bcb7f75e fix(error): Use a non-generic Error alias
`clap::Error::raw` was producing ambiguity errors with a default generic
parameter on `clap::error::Error` (which `clap::Error` is a re-export
of).

I tried making `clap::Error` a type alias with a default generic
parameter but that ran into an ambiguity error with `map_err`.

So I'm going ahead and hard coding `clap::Error`.  We don't expect
people to change this all that often.
2022-09-20 13:37:02 -05:00