Merge pull request #3474 from epage/app_from_crate

fix: Update app_from_crate for App rename

examples/cargo-example.rs

@@ -5,7 +5,7 @@ fn main() {
         .bin_name("cargo")
         .subcommand_required(true)
         .subcommand(
-            clap::app_from_crate!().name("example").arg(
+            clap::command!("example").arg(
                 clap::arg!(--"manifest-path" <PATH>)
                     .required(false)
                     .allow_invalid_utf8(true),

examples/escaped-positional.rs

@@ -1,9 +1,9 @@
 // Note: this requires the `cargo` feature
 
-use clap::{app_from_crate, arg};
+use clap::{arg, command};
 
 fn main() {
-    let matches = app_from_crate!()
+    let matches = command!()
         .arg(arg!(eff: -f))
         .arg(arg!(pea: -p <PEAR>).required(false))
         .arg(

examples/tutorial_builder/01_quick.rs

@@ -1,8 +1,8 @@
-use clap::{app_from_crate, arg, Command};
+use clap::{arg, command, Command};
 use std::path::Path;
 
 fn main() {
-    let matches = app_from_crate!()
+    let matches = command!()
         .arg(arg!([name] "Optional name to operate on"))
         .arg(
             arg!(

examples/tutorial_builder/02_app_settings.rs

@@ -1,7 +1,7 @@
-use clap::{app_from_crate, arg, AppSettings};
+use clap::{arg, command, AppSettings};
 
 fn main() {
-    let matches = app_from_crate!()
+    let matches = command!()
         .args_override_self(true)
         .global_setting(AppSettings::DeriveDisplayOrder)
         .allow_negative_numbers(true)

examples/tutorial_builder/02_crate.rs

@@ -1,7 +1,7 @@
-use clap::{app_from_crate, arg};
+use clap::{arg, command};
 
 fn main() {
-    let matches = app_from_crate!()
+    let matches = command!()
         .arg(arg!(--two <VALUE>))
         .arg(arg!(--one <VALUE>))
         .get_matches();

examples/tutorial_builder/03_01_flag_bool.rs

@@ -1,7 +1,7 @@
-use clap::{app_from_crate, arg};
+use clap::{arg, command};
 
 fn main() {
-    let matches = app_from_crate!().arg(arg!(-v - -verbose)).get_matches();
+    let matches = command!().arg(arg!(-v - -verbose)).get_matches();
 
     println!("verbose: {:?}", matches.is_present("verbose"));
 }

examples/tutorial_builder/03_01_flag_count.rs

@@ -1,7 +1,7 @@
-use clap::{app_from_crate, arg};
+use clap::{arg, command};
 
 fn main() {
-    let matches = app_from_crate!().arg(arg!(-v --verbose ...)).get_matches();
+    let matches = command!().arg(arg!(-v --verbose ...)).get_matches();
 
     println!("verbose: {:?}", matches.occurrences_of("verbose"));
 }

examples/tutorial_builder/03_02_option.rs

@@ -1,7 +1,7 @@
-use clap::{app_from_crate, arg};
+use clap::{arg, command};
 
 fn main() {
-    let matches = app_from_crate!()
+    let matches = command!()
         .arg(arg!(-n --name <NAME>).required(false))
         .get_matches();
 

examples/tutorial_builder/03_03_positional.rs

@@ -1,7 +1,7 @@
-use clap::{app_from_crate, arg};
+use clap::{arg, command};
 
 fn main() {
-    let matches = app_from_crate!().arg(arg!([NAME])).get_matches();
+    let matches = command!().arg(arg!([NAME])).get_matches();
 
     println!("NAME: {:?}", matches.value_of("NAME"));
 }

examples/tutorial_builder/03_04_subcommands.rs

@@ -1,7 +1,7 @@
-use clap::{app_from_crate, arg, Command};
+use clap::{arg, command, Command};
 
 fn main() {
-    let matches = app_from_crate!()
+    let matches = command!()
         .propagate_version(true)
         .subcommand_required(true)
         .arg_required_else_help(true)

examples/tutorial_builder/03_05_default_values.rs

@@ -1,7 +1,7 @@
-use clap::{app_from_crate, arg};
+use clap::{arg, command};
 
 fn main() {
-    let matches = app_from_crate!()
+    let matches = command!()
         .arg(arg!([NAME]).default_value("alice"))
         .get_matches();
 

examples/tutorial_builder/04_01_enum.rs

@@ -1,4 +1,4 @@
-use clap::{app_from_crate, arg, ArgEnum, PossibleValue};
+use clap::{arg, command, ArgEnum, PossibleValue};
 
 #[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, ArgEnum)]
 enum Mode {
@@ -37,7 +37,7 @@ impl std::str::FromStr for Mode {
 }
 
 fn main() {
-    let matches = app_from_crate!()
+    let matches = command!()
         .arg(
             arg!(<MODE>)
                 .help("What mode to run the program in")

examples/tutorial_builder/04_01_possible.rs

@@ -1,7 +1,7 @@
-use clap::{app_from_crate, arg};
+use clap::{arg, command};
 
 fn main() {
-    let matches = app_from_crate!()
+    let matches = command!()
         .arg(
             arg!(<MODE>)
                 .help("What mode to run the program in")

examples/tutorial_builder/04_02_parse.rs

@@ -1,7 +1,7 @@
-use clap::{app_from_crate, arg};
+use clap::{arg, command};
 
 fn main() {
-    let matches = app_from_crate!()
+    let matches = command!()
         .arg(
             arg!(<PORT>)
                 .help("Network port to use")

examples/tutorial_builder/04_02_validate.rs

@@ -1,11 +1,11 @@
-use clap::{app_from_crate, arg};
+use clap::{arg, command};
 use std::ops::RangeInclusive;
 use std::str::FromStr;
 
 const PORT_RANGE: RangeInclusive<usize> = 1..=65535;
 
 fn main() {
-    let matches = app_from_crate!()
+    let matches = command!()
         .arg(arg!(<PORT>).help("Network port to use").validator(|s| {
             usize::from_str(s)
                 .map(|port| PORT_RANGE.contains(&port))

examples/tutorial_builder/04_03_relations.rs

@@ -1,8 +1,8 @@
-use clap::{app_from_crate, arg, ArgGroup};
+use clap::{arg, command, ArgGroup};
 
 fn main() {
     // Create application like normal
-    let matches = app_from_crate!()
+    let matches = command!()
         // Add the version arguments
         .arg(arg!(--"set-ver" <VER> "set version manually").required(false))
         .arg(arg!(--major         "auto inc major"))

examples/tutorial_builder/04_04_custom.rs

@@ -1,8 +1,8 @@
-use clap::{app_from_crate, arg, ErrorKind};
+use clap::{arg, command, ErrorKind};
 
 fn main() {
     // Create application like normal
-    let mut cmd = app_from_crate!()
+    let mut cmd = command!()
         // Add the version arguments
         .arg(arg!(--"set-ver" <VER> "set version manually").required(false))
         .arg(arg!(--major         "auto inc major"))

examples/tutorial_builder/05_01_assert.rs

@@ -1,4 +1,4 @@
-use clap::{app_from_crate, arg};
+use clap::{arg, command};
 
 fn main() {
     let matches = cmd().get_matches();
@@ -11,7 +11,7 @@ fn main() {
 }
 
 fn cmd() -> clap::Command<'static> {
-    app_from_crate!().arg(
+    command!().arg(
         arg!(<PORT>)
             .help("Network port to use")
             .validator(|s| s.parse::<usize>()),

examples/tutorial_builder/README.md

@@ -86,7 +86,7 @@ MyApp 1.0
 
 ```
 
-You can use `app_from_crate!()` to fill these fields in from your `Cargo.toml`
+You can use `command!()` to fill these fields in from your `Cargo.toml`
 file.  **This requires the `cargo` feature flag.**
 
 [Example:](02_crate.rs)

examples/tutorial_derive/README.md

@@ -89,7 +89,7 @@ MyApp 1.0
 
 ```
 
-You can use `app_from_crate!()` to fill these fields in from your `Cargo.toml` file.
+You can use `command!()` to fill these fields in from your `Cargo.toml` file.
 
 [Example:](02_crate.rs)
 ```console

src/build/command.rs

@@ -111,7 +111,7 @@ impl<'help> App<'help> {
     /// name will only be displayed to the user when they request to print
     /// version or help and usage information.
     ///
-    /// See also [`app_from_crate!`](crate::app_from_crate!) and [`crate_name!`](crate::crate_name!).
+    /// See also [`command!`](crate::command!) and [`crate_name!`](crate::crate_name!).
     ///
     /// # Examples
     ///

src/macros.rs

@@ -283,15 +283,10 @@ macro_rules! crate_name {
 
 /// Allows you to build the `Command` instance from your Cargo.toml at compile time.
 ///
-/// Equivalent to using the `crate_*!` macros with their respective fields.
-///
-/// Provided separator is for the [`crate_authors!`] macro,
-/// refer to the documentation therefor.
-///
 /// **NOTE:** Changing the values in your `Cargo.toml` does not trigger a re-build automatically,
 /// and therefore won't change the generated output until you recompile.
 ///
-/// **Pro Tip:** In some cases you can "trick" the compiler into triggering a rebuild when your
+/// In some cases you can "trick" the compiler into triggering a rebuild when your
 /// `Cargo.toml` is changed by including this in your `src/main.rs` file
 /// `include_str!("../Cargo.toml");`
 ///
@@ -301,11 +296,36 @@ macro_rules! crate_name {
 /// # #[macro_use]
 /// # extern crate clap;
 /// # fn main() {
-/// let m = app_from_crate!().get_matches();
+/// let m = command!().get_matches();
 /// # }
 /// ```
 #[cfg(feature = "cargo")]
 #[macro_export]
+macro_rules! command {
+    () => {{
+        $crate::command!($crate::crate_name!())
+    }};
+    ($name:expr) => {{
+        let mut cmd = $crate::Command::new($name).version($crate::crate_version!());
+
+        let author = $crate::crate_authors!();
+        if !author.is_empty() {
+            cmd = cmd.author(author)
+        }
+
+        let about = $crate::crate_description!();
+        if !about.is_empty() {
+            cmd = cmd.about(about)
+        }
+
+        cmd
+    }};
+}
+
+/// Deprecated, replaced with [`clap::command!`][crate::command]
+#[cfg(feature = "cargo")]
+#[deprecated(since = "3.1.0", note = "Replaced with `clap::command!")]
+#[macro_export]
 macro_rules! app_from_crate {
     () => {{
         let mut cmd = $crate::Command::new($crate::crate_name!()).version($crate::crate_version!());

tests/builder/app_from_crate.rs

@@ -1,4 +1,5 @@
 #![cfg(feature = "cargo")]
+#![allow(deprecated)]
 
 use clap::{app_from_crate, error::ErrorKind};
 

tests/builder/command.rs

@@ -0,0 +1,27 @@
+#![cfg(feature = "cargo")]
+
+use clap::{command, error::ErrorKind};
+
+static EVERYTHING: &str = "clap {{version}}
+A simple to use, efficient, and full-featured Command Line Argument Parser
+
+USAGE:
+    clap
+
+OPTIONS:
+    -h, --help       Print help information
+    -V, --version    Print version information
+";
+
+#[test]
+fn command() {
+    let res = command!().try_get_matches_from(vec!["clap", "--help"]);
+
+    assert!(res.is_err());
+    let err = res.unwrap_err();
+    assert_eq!(err.kind(), ErrorKind::DisplayHelp);
+    assert_eq!(
+        err.to_string(),
+        EVERYTHING.replace("{{version}}", env!("CARGO_PKG_VERSION"))
+    );
+}

tests/builder/main.rs

@@ -6,6 +6,7 @@ mod arg_matcher_assertions;
 mod arg_settings;
 mod borrowed;
 mod cargo;
+mod command;
 mod conflicts;
 mod default_missing_vals;
 mod default_vals;