Commit graph

2635 commits

Author SHA1 Message Date
Ed Page
ff0796b014 fix(derive)!: Remove old derive names 2022-07-21 12:57:12 -05:00
Ed Page
da5d5b8b53 fix!: Remove SubCommand 2022-07-21 12:48:52 -05:00
Ed Page
99d92c916c fix!: Remove yaml support 2022-07-21 12:46:47 -05:00
Ed Page
765af4198c fix!: Remove regex validation 2022-07-21 12:42:09 -05:00
Ed Page
48f087d090 fix(parser): low index multiples work with flags
We had some tests for this but not sufficient obviously.  The problem is
we were tweaking the positional argument counter when processing flags
and not just positional arguments.  Delaying it until after flags seems
to fix this.

Fixes #3959
2022-07-20 17:44:49 -05:00
Ed Page
5e02445ce5 docs: Small tweak to lib docs 2022-07-19 15:54:01 -05:00
Tshepang Mbambo
01d7e7ac04
docs: reduce the need to guess 2022-07-19 22:32:42 +02:00
Ed Page
d43f1dbf6f docs: Move everything to docs.rs
A couple of things happened when preparing to release 3.0
- We needed derive documentation
  - I had liked how serde handled theres
  - I had bad experiences finding things in structopt's documentation
- The examples were broken and we needed tests
- The examples seemed to follow a pattern of having tutorial content and
  cookbook content
- We had been getting bug reports from people looking at master and
  thinking they were looking at what is currently released
- We had gotten feedback to keep down the number of places that
  documentation was located

From this, we went with a mix of docs.rs and github
- We kept the number of content locations at 2 rather than 3 by not
  having an external site like serde
- We rewrote the examples into explicit tutorials and cookbooks to align
  with the 4 styles of documentation
- We could test our examples by running `console` code blocks with
  trycmd
- Documentation was versioned and the README pointed to the last release

This had downsides
- The tutorials didn't have the code inlined
- Users still had a hard time finding and navigating between the
  different forms of documentation
- In practice, we were less likely to cross-link between the different
  types of documentation

Moving to docs.rs would offer a lot of benefits, even if it is only
designed for Rust-reference documentation and isn't good for Rust derive
reference documentation, tutorials, cookbooks, etc.  The big problem was
keeping the examples tested to keep maintenance costs down.  Maybe its
just me but its easy to overlook
- You can pull documentation from a file using `#[doc = "path"]`
- Repeated doc attributes get concatenated rather than first or last
  writer winning

Remember these when specifically thinking about Rust documentation made
me realize that we could get everything into docs.rs.

When doing this
- Tutorial code got brought in as was one of the aims
- We needed to split the lib documentation and the README to have all of
  the linking work.  This allowed us to specialize them according to
  their rule (user vs contributor)
- We needed to avoid users getting caught up in making a decision
  between Derive and Builder APIs so we put the focus on the derive API
  with links to the FAQ to help users decide when to use one or the
  other.
- Improved cross-referencing between different parts of the
  documentation
- Limited inline comments were added to example code
  - Introductory example code intentionally does not have teaching
    comments in it as its meant to give a flavor or sense of things and
    not meant to teach on its own.

This is a first attempt.  There will be a lot of room for further
improvement.  Current know downsides:
- Content source is more split up for the tutorials

This hopefully addresses #3189
2022-07-19 13:30:38 -05:00
Ed Page
a8a7a61f56 chore: Release 2022-07-14 09:38:54 -05:00
Ed Page
afc540153b
Merge pull request #3902 from tmccombs/get-conflicts-with-group
Include groups in `get_arg_conflicts_with`
2022-07-14 09:37:45 -05:00
Thayne McCombs
f27f1f57ea fix: Include groups in get_arg_conflicts_with
So that it doesn't panic if trying to get the conflicts for an Arg that
conflicts with a group.

Fixes: #3900
2022-07-14 01:08:06 -06:00
Ed Page
2df0732df4 chore: Release 2022-07-13 09:08:35 -05:00
Emerson Ford
e39156e0b9 feat: Add method to get non-visible arg aliases 2022-07-12 11:23:22 -07:00
Ed Page
9b6321a1f0 chore: Release 2022-07-11 21:48:07 -05:00
Emerson Ford
8e1411b3b2 fix: Loosen lifetime constraint on mut_subcommand 2022-07-11 19:12:36 -07:00
Ed Page
7009ae63c8 doc: Explain why examples are missing
Fixes #3865
2022-06-30 08:29:16 -05:00
Ed Page
6614ffa6c8 chore: Release 2022-06-30 08:25:54 -05:00
Emerson Ford
619f209138 feat: Add mut_subcommand method to Command
this allows us modify existing subcommands on an existing/already built
Command struct
2022-06-29 20:42:58 -07:00
Ed Page
b4a1362486 chore: Release 2022-06-28 08:04:18 -05:00
Ed Page
72d206e4d9 fix(parser): Ensure globals override env vars
This fixes a bug introduced in 4a694f3592
when we were trying to move away from presence checks via occurrences.
I switched it to the common type of presence check but really what we
want is a highest-precedence check.

Fixes #3872
2022-06-27 22:40:40 -05:00
Ed Page
3c4e684c8b test: Verify auto-traits for core types
By checking these types, we'll get some other types for free, like
`Command` verifying `Arg`.

This was inspired by #3876
2022-06-27 20:50:29 -05:00
Stiopa Koltsov
464ef3920b refactor: Put once_cell reexport into __macro_refs
When upgrading our company projects from clap 3.1 to clap 3.2 I had
to fix several references to `clap::lazy_init`. People are not
supposed to do that, but that's hard to enforce.

Hope placing `once_cell` reexport into `__macro_refs` prevent at
least some of the such issues in the future.
2022-06-26 04:13:03 +01:00
Ed Page
f9e51952b8 fix(docs): Update deprecations to latest target
Before, I was mixed on doing this as ideally people would upgrade
through the minor releases, going through the release notes.  This also
saves us havin to audit deprecations to make sure they are all pointing
to the latest.

First, this isn't practical for users.  Its annoying to pin your version (at least
its easier now that we pin `clap_derive` for users) and a lot of work to
go through them one step at a time.

On top of that, we've changed our deprecation policy to put the timing
of responding to deprecations into the user's hands with, with us
putting them behind the `deprecated` feature flag.  This means someone
might respond to deprecations every once in a while or might not do it
until right before the 4.0 release.  Our deprecation messages should be
updated to respond to that.

This supersedes #3616
2022-06-22 14:31:15 -05:00
Ed Page
3823df9bbe chore: Release 2022-06-21 09:32:04 -05:00
Ed Page
01da890145 fix(parser): Don't panic on --=
This broke when we introduced clap_lex and then did a refactor on top.
We put in guards to say that escapes shouldn't happen but missed `--=`
which isn't quite an escape.

Not fully set on what error should be returned in this case (we are
returning roughly what we used to) but at least
we aren't panicing.

Fixes #3858
2022-06-21 08:53:04 -05:00
David Tolnay
690530a191
Fix typo in ErrorKind::ValueValidation message 2022-06-17 13:07:09 -07:00
Ed Page
f131d46b99 fix(parser): Add value_source as a replacement for occurrences_of
This was an oversight when listing out the options as identified when
looking at oxidecomputer/humility#161.
2022-06-16 13:29:31 -05:00
Ed Page
a7698e9a1d chore: Release 2022-06-15 11:50:16 -05:00
Ed Page
40daa70b89 docs: Provide a hybrid-flag example
Between
- `ArgAction::SetTrue` storing actual values
- `ArgAction::Set` making it easier for derive users to override bool
  behavior
- `Arg::default_missing_value` allowing hybrid-flags
- This commit documenting hybrid-flags even further

There shouldn't be anything left for #1649

Fixes #1649
2022-06-15 11:09:53 -05:00
Ed Page
c9988db97f docs(builder): Clean up default_missing_value's docs 2022-06-15 10:59:34 -05:00
Ed Page
eba753f162 fix(help): Further debug clean up 2022-06-15 10:03:52 -05:00
Ed Page
c443aa0b5d refactor(help): Collapse useless function 2022-06-15 09:31:19 -05:00
Ed Page
17d975743a fix(help): Improve debug output 2022-06-15 09:25:18 -05:00
Ed Page
20358ff295 chore: Release 2022-06-14 15:01:42 -05:00
Ed Page
63a17a40ad chore: Release 2022-06-14 11:19:59 -05:00
Ed Page
7515bfeb51 fix: Allow people to opt-in to deprecations
This adds a new `Cargo.toml` feature named `deprecated` that opts
controls whether deprecation warnings show up.  This is starting off as
non-default though that may change (see below).

Benefits
- Allows a staged rollout so a smaller subset of users see new
  deprecations and can report their experience with them before everyone
  sees them.  For example, this reduces the number of people who have to
  deal with #3822.
- This allows people to defer responding to each new batch of
  deprecations and instead do it at once.  This means we should
  reconsider #3616.

The one risk is people who don't follow blog posts and guides having a
harder time upgrading to the next breaking release without the warnings
on by default.  For these users, we reserve the right to make the
`deprecated` feature `default`.  This is most likely to happen in a
minor release that is released in conjunction with the next major
release (e.g. when releasing 4.0.0, we release a 3.3.0 that enables
deprecations by default).  By using a feature, users can still disable
this if they want.

Thanks @joshtriplett for the idea
2022-06-14 10:50:05 -05:00
Ed Page
cb42df61e4 refactor: Switch to once_cell
Though this is changing an API item we export, we do not consider this a
breaking change because
- This was an implementation detail of the macros and people shouldn't be using it directly
- The `macro_rules` macro is coupled to `clap` because they are in the
  same crate
- The derive macro is coupled to `clap` because `clap` declares a
  `=x.y.z` dependency on `clap_derive

Fixes #3828
2022-06-14 09:10:50 -05:00
Ed Page
7836beda05 chore: Release 2022-06-14 07:02:40 -05:00
Ed Page
650a29c18b chore: Release 2022-06-13 09:37:47 -05:00
Ed Page
4e56acffce chore: Release 2022-06-13 09:31:29 -05:00
Ed Page
c8b45f75b8
Merge pull request #3820 from epage/panic
fix(assert): Tweak bad arg panics
2022-06-13 07:40:05 -05:00
梦想实现家
3eacf5b8b0
fix(builder): Don't double-has arg id in default_value_ifs_os (#3815) 2022-06-13 07:39:50 -05:00
Ed Page
a1320754f9 fix(assert): Be consistent in ID language for args 2022-06-13 07:08:38 -05:00
Ed Page
97f8041229 fix(assert): Add missing track_caller attributes 2022-06-13 07:04:59 -05:00
Ed Page
ca2846615c docs(parser): Encourage people to read the whole deprecation message 2022-06-10 19:41:50 -05:00
Ed Page
9caec5a52d fix(parser): Deprecate ArgMatches::is_present 2022-06-10 14:21:25 -05:00
Ed Page
9b7813558c feat(parser): Provide updated version if 'is_present'
- This matches the more container-like naming we are aiming for
- This provides an opportunity to warn people about moving away from
  `ArgAction::IncOcccurrences` for flags, like the deprecation for
  `ArgMatches::occurrences_of` to help people migrate in preparation for
  clap 4 (rather than having the behavior change subtly in a way only
  caught by thorough tests)

In addition, I feel `contains_id` has less ambiguous meaning than
`is_present`.
2022-06-10 10:16:44 -05:00
Ed Page
fce1125ba9 fix(assert): Allow required flags
Newstyle flags have defaults which prevents them from being required
until now.
2022-06-10 10:16:44 -05:00
Ed Page
54125aca55 docs(parser): Clarify we want arg ids
This was missed in #3453
2022-06-09 17:00:07 -05:00
Ed Page
f87fd0325c fix: Open the door for adding value_parser! specializations
I wanted to make the contract more clear that we might add more specific
value parsers in the future.
2022-06-10 10:52:38 -05:00