fix(derive)!: Rename Clap to Parser.

Before clap-rs#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 clap-rs#2785 includes making `App` attributes almost
exclusively for `Clap`.  Clarifying the names/roles will help
communicate this.

For prior discussion, see clap-rs#2583

FAQ.md

@@ -20,7 +20,7 @@ Simple! `clap` *is* `structopt`. With the 3.0 release, `clap` imported the `stru
 
 If you were using `structopt` before, you have to change the attributes from `#[structopt(...)]` to `#[clap(...)]`.
 
-Also the derive statements changed from `#[derive(Structopt)]` to `#[derive(Clap)]`. There is also some additional functionality and breaking changes that's been added to the `clap_derive` crate. See the documentation for that crate, for more details.
+Also the derive statements changed from `#[derive(Structopt)]` to `#[derive(Parser)]`. There is also some additional functionality and breaking changes that's been added to the `clap_derive` crate. See the documentation for that crate, for more details.
 
 #### How does `clap` compare to [getopts](https://github.com/rust-lang-nursery/getopts)?
 

README.md

@@ -137,11 +137,11 @@ The first example shows the simplest way to use `clap`, by defining a struct. If
 //
 // This example demonstrates clap's full 'custom derive' style of creating arguments which is the
 // simplest method of use, but sacrifices some flexibility.
-use clap::{AppSettings, Clap};
+use clap::{AppSettings, Parser};
 
 /// This doc string acts as a help message when the user runs '--help'
 /// as do all doc strings on fields
-#[derive(Clap)]
+#[derive(Parser)]
 #[clap(version = "1.0", author = "Kevin K. <[email protected]>")]
 #[clap(setting = AppSettings::ColoredHelp)]
 struct Opts {
@@ -157,14 +157,14 @@ struct Opts {
     subcmd: SubCommand,
 }
 
-#[derive(Clap)]
+#[derive(Parser)]
 enum SubCommand {
     #[clap(version = "1.3", author = "Someone E. <[email protected]>")]
     Test(Test),
 }
 
 /// A subcommand for controlling testing
-#[derive(Clap)]
+#[derive(Parser)]
 struct Test {
     /// Print debug info
     #[clap(short)]
@@ -470,7 +470,7 @@ Disabling optional features can decrease the binary size of `clap` and decrease
 #### Features enabled by default
 
 * **std**: _Not Currently Used._ Placeholder for supporting `no_std` environments in a backwards compatible manner.
-* **derive**: Enables the custom derive (i.e. `#[derive(Clap)]`). Without this you must use one of the other methods of creating a `clap` CLI listed above. (builds dependency `clap_derive`)
+* **derive**: Enables the custom derive (i.e. `#[derive(Parser)]`). Without this you must use one of the other methods of creating a `clap` CLI listed above. (builds dependency `clap_derive`)
 * **cargo**: Turns on macros that read values from `CARGO_*` environment variables.
 * **color**: Turns on colored error messages. You still have to turn on colored help by setting `AppSettings::ColoredHelp`. (builds dependency `termcolor`)
 * **env**: Turns on the usage of environment variables during parsing.

clap_derive/README.md

@@ -19,10 +19,10 @@ clap = "3"
 And then, in your rust file:
 ```rust
 use std::path::PathBuf;
-use clap::Clap;
+use clap::Parser;
 
 /// A basic example
-#[derive(Clap, Debug)]
+#[derive(Parser, Debug)]
 #[clap(name = "basic")]
 struct Opt {
     // A flag, true if used in the command line. Note doc comment will

clap_derive/examples/after_help.rs

@@ -1,11 +1,11 @@
 //! How to append a postscript to the help message generated.
 
-use clap::Clap;
+use clap::Parser;
 
 /// I am a program and I do things.
 ///
 /// Sometimes they even work.
-#[derive(Clap, Debug)]
+#[derive(Parser, Debug)]
 #[clap(after_help = "Beware `-d`, dragons be here")]
 struct Opt {
     /// Release the dragon.

clap_derive/examples/arg_enum.rs

@@ -2,7 +2,7 @@
 //!
 //! All the variants of the enum and the enum itself support `rename_all`
 
-use clap::{ArgEnum, Clap};
+use clap::{ArgEnum, Parser};
 
 #[derive(ArgEnum, Debug, PartialEq, Clone)]
 enum ArgChoice {
@@ -19,7 +19,7 @@ enum ArgChoice {
     Hidden,
 }
 
-#[derive(Clap, PartialEq, Debug)]
+#[derive(Parser, PartialEq, Debug)]
 struct Opt {
     #[clap(arg_enum)]
     arg: ArgChoice,

clap_derive/examples/at_least_two.rs

@@ -1,9 +1,9 @@
 //! How to require presence of at least N values,
 //! like `val1 val2 ... valN ... valM`.
 
-use clap::Clap;
+use clap::Parser;
 
-#[derive(Clap, Debug)]
+#[derive(Parser, Debug)]
 struct Opt {
     #[clap(required = true, min_values = 2)]
     foos: Vec<String>,

clap_derive/examples/basic.rs

@@ -1,10 +1,10 @@
 //! A somewhat comprehensive example of a typical `clap_derive` usage.
 
-use clap::{Clap, ValueHint};
+use clap::{Parser, ValueHint};
 use std::path::PathBuf;
 
 /// A basic example
-#[derive(Clap, Debug)]
+#[derive(Parser, Debug)]
 #[clap(name = "basic")]
 struct Opt {
     // A flag, true if used in the command line. Note doc comment will

clap_derive/examples/deny_missing_docs.rs

@@ -16,10 +16,10 @@
 
 #![deny(missing_docs)]
 
-use clap::Clap;
+use clap::Parser;
 
 /// The options
-#[derive(Clap, Debug, PartialEq)]
+#[derive(Parser, Debug, PartialEq)]
 pub struct Opt {
     #[clap(short)]
     verbose: bool,
@@ -28,7 +28,7 @@ pub struct Opt {
 }
 
 /// Some subcommands
-#[derive(Clap, Debug, PartialEq)]
+#[derive(Parser, Debug, PartialEq)]
 pub enum Cmd {
     /// command A
     A,
@@ -43,7 +43,7 @@ pub enum Cmd {
 }
 
 /// The options for C
-#[derive(Clap, Debug, PartialEq)]
+#[derive(Parser, Debug, PartialEq)]
 pub struct COpt {
     #[clap(short)]
     bob: bool,

clap_derive/examples/doc_comments.rs

@@ -1,10 +1,10 @@
 //! How to use doc comments in place of `help/long_help`.
 
-use clap::Clap;
+use clap::Parser;
 
 /// A basic example for the usage of doc comments as replacement
 /// of the arguments `help`, `long_help`, `about` and `long_about`.
-#[derive(Clap, Debug)]
+#[derive(Parser, Debug)]
 #[clap(name = "basic")]
 struct Opt {
     /// Just use doc comments to replace `help`, `long_help`,
@@ -52,7 +52,7 @@ code) in the description:
     sub_command: SubCommand,
 }
 
-#[derive(Clap, Debug)]
+#[derive(Parser, Debug)]
 #[clap()]
 enum SubCommand {
     /// The same rules described previously for flags. Are

clap_derive/examples/enum_tuple.rs

@@ -1,19 +1,19 @@
 //! How to extract subcommands' args into external structs.
 
-use clap::Clap;
+use clap::Parser;
 
-#[derive(Debug, Clap)]
+#[derive(Debug, Parser)]
 pub struct Foo {
     pub bar: Option<String>,
 }
 
-#[derive(Debug, Clap)]
+#[derive(Debug, Parser)]
 pub enum Command {
     #[clap(name = "foo")]
     Foo(Foo),
 }
 
-#[derive(Debug, Clap)]
+#[derive(Debug, Parser)]
 #[clap(name = "classify")]
 pub struct ApplicationArguments {
     #[clap(subcommand)]

clap_derive/examples/env.rs

@@ -1,10 +1,10 @@
 //! How to use environment variable fallback an how it
 //! interacts with `default_value`.
 
-use clap::{ArgSettings, Clap};
+use clap::{ArgSettings, Parser};
 
 /// Example for allowing to specify options via environment variables.
-#[derive(Clap, Debug)]
+#[derive(Parser, Debug)]
 #[clap(name = "env")]
 struct Opt {
     // Use `env` to enable specifying the option with an environment

clap_derive/examples/example.rs

@@ -1,8 +1,8 @@
-//! Somewhat complex example of usage of #[derive(Clap)].
+//! Somewhat complex example of usage of #[derive(Parser)].
 
-use clap::Clap;
+use clap::Parser;
 
-#[derive(Clap, Debug)]
+#[derive(Parser, Debug)]
 #[clap(name = "example")]
 /// An example of clap_derive usage.
 struct Opt {

clap_derive/examples/flatten.rs

@@ -1,8 +1,8 @@
 //! How to use flattening.
 
-use clap::Clap;
+use clap::Parser;
 
-#[derive(Clap, Debug)]
+#[derive(Parser, Debug)]
 struct Cmdline {
     /// switch verbosity on
     #[clap(short)]
@@ -12,7 +12,7 @@ struct Cmdline {
     daemon_opts: DaemonOpts,
 }
 
-#[derive(Clap, Debug)]
+#[derive(Parser, Debug)]
 struct DaemonOpts {
     /// daemon user
     #[clap(short)]

clap_derive/examples/from_crate.rs

@@ -1,8 +1,8 @@
 //! How to derive the author, description, and version from Cargo.toml
 
-use clap::Clap;
+use clap::Parser;
 
-#[derive(Clap, Debug)]
+#[derive(Parser, Debug)]
 #[clap(author, about, version)]
 //     ^^^^^^                   <- derive author from Cargo.toml
 //             ^^^^^            <- derive description from Cargo.toml

clap_derive/examples/git.rs

@@ -3,9 +3,9 @@
 //! Documentation can be added either through doc comments or
 //! `help`/`about` attributes.
 
-use clap::Clap;
+use clap::Parser;
 
-#[derive(Clap, Debug)]
+#[derive(Parser, Debug)]
 #[clap(name = "git")]
 /// the stupid content tracker
 enum Opt {

clap_derive/examples/group.rs

@@ -1,8 +1,8 @@
 //! How to use `clap::Arg::group`
 
-use clap::{ArgGroup, Clap};
+use clap::{ArgGroup, Parser};
 
-#[derive(Clap, Debug)]
+#[derive(Parser, Debug)]
 #[clap(group = ArgGroup::new("verb").required(true))]
 struct Opt {
     /// Set a custom HTTP verb

clap_derive/examples/keyvalue.rs

@@ -1,6 +1,6 @@
-//! How to parse "key=value" pairs with #[derive(Clap)].
+//! How to parse "key=value" pairs with #[derive(Parser)].
 
-use clap::Clap;
+use clap::Parser;
 use std::error::Error;
 
 /// Parse a single key-value pair
@@ -17,7 +17,7 @@ where
     Ok((s[..pos].parse()?, s[pos + 1..].parse()?))
 }
 
-#[derive(Clap, Debug)]
+#[derive(Parser, Debug)]
 struct Opt {
     // number_of_values = 1 forces the user to repeat the -D option for each key-value pair:
     // my_program -D a=1 -D b=2

clap_derive/examples/negative_flag.rs

@@ -1,9 +1,9 @@
 //! How to add `no-thing` flag which is `true` by default and
 //! `false` if passed.
 
-use clap::Clap;
+use clap::Parser;
 
-#[derive(Debug, Clap)]
+#[derive(Debug, Parser)]
 struct Opt {
     #[clap(long = "no-verbose", parse(from_flag = std::ops::Not::not))]
     verbose: bool,

clap_derive/examples/rename_all.rs

@@ -18,9 +18,9 @@
 //!                   with underscores.
 //! - **Verbatim**: Use the original attribute name defined in the code.
 
-use clap::Clap;
+use clap::Parser;
 
-#[derive(Clap, Debug)]
+#[derive(Parser, Debug)]
 #[clap(name = "rename_all", rename_all = "screaming_snake_case")]
 enum Opt {
     // This subcommand will be named `FIRST_COMMAND`. As the command doesn't
@@ -55,13 +55,13 @@ enum Opt {
     },
 }
 
-#[derive(Clap, Debug)]
+#[derive(Parser, Debug)]
 enum Subcommands {
     // This one will be available as `first-subcommand`.
     FirstSubcommand,
 }
 
-#[derive(Clap, Debug)]
+#[derive(Parser, Debug)]
 struct BonusOptions {
     // And this one will be available as `baz-option`.
     #[clap(long)]

clap_derive/examples/skip.rs

@@ -1,8 +1,8 @@
 //! How to use `#[clap(skip)]`
 
-use clap::Clap;
+use clap::Parser;
 
-#[derive(Clap, Debug, PartialEq)]
+#[derive(Parser, Debug, PartialEq)]
 pub struct Opt {
     #[clap(long, short)]
     number: u32,

clap_derive/examples/subcommand_aliases.rs

@@ -1,8 +1,8 @@
 //! How to assign some aliases to subcommands
 
-use clap::{AppSettings, Clap};
+use clap::{AppSettings, Parser};
 
-#[derive(Clap, Debug)]
+#[derive(Parser, Debug)]
 // https://docs.rs/clap/2/clap/enum.AppSettings.html#variant.InferSubcommands
 #[clap(setting = AppSettings::InferSubcommands)]
 enum Opt {

clap_derive/examples/true_or_false.rs

@@ -1,6 +1,6 @@
 //! How to parse `--foo=true --bar=false` and turn them into bool.
 
-use clap::Clap;
+use clap::Parser;
 
 fn true_or_false(s: &str) -> Result<bool, &'static str> {
     match s {
@@ -10,7 +10,7 @@ fn true_or_false(s: &str) -> Result<bool, &'static str> {
     }
 }
 
-#[derive(Clap, Debug, PartialEq)]
+#[derive(Parser, Debug, PartialEq)]
 struct Opt {
     // Default parser for `try_from_str` is FromStr::from_str.
     // `impl FromStr for bool` parses `true` or `false` so this

clap_derive/examples/value_hints_derive.rs

@@ -12,7 +12,7 @@
 //! . ./value_hints_derive.fish
 //! ./target/debug/examples/value_hints_derive --<TAB>
 //! ```
-use clap::{App, AppSettings, ArgEnum, Clap, IntoApp, ValueHint};
+use clap::{App, AppSettings, ArgEnum, IntoApp, Parser, ValueHint};
 use clap_generate::generators::{Bash, Elvish, Fish, PowerShell, Zsh};
 use clap_generate::{generate, Generator};
 use std::ffi::OsString;
@@ -29,7 +29,7 @@ enum GeneratorChoice {
     Zsh,
 }
 
-#[derive(Clap, Debug, PartialEq)]
+#[derive(Parser, Debug, PartialEq)]
 #[clap(
     name = "value_hints_derive",
     // AppSettings::TrailingVarArg is required to use ValueHint::CommandWithArguments