Merge pull request #3473 from epage/derive

fix: Change `IntoApp::into_app` to `CommandFactory::command`

clap_complete/examples/value_hints_derive.rs

@@ -12,7 +12,7 @@
 //! . ./value_hints_derive.fish
 //! ./target/debug/examples/value_hints_derive --<TAB>
 //! ```
-use clap::{Command, IntoApp, Parser, ValueHint};
+use clap::{Command, CommandFactory, Parser, ValueHint};
 use clap_complete::{generate, Generator, Shell};
 use std::ffi::OsString;
 use std::io;
@@ -65,7 +65,7 @@ fn main() {
     let opt = Opt::parse();
 
     if let Some(generator) = opt.generator {
-        let mut cmd = Opt::into_app();
+        let mut cmd = Opt::command();
         eprintln!("Generating completion file for {:?}...", generator);
         print_completions(generator, &mut cmd);
     } else {

clap_derive/src/derives/into_app.rs

@@ -56,7 +56,8 @@ pub fn gen_for_struct(
             clippy::suspicious_else_formatting,
         )]
         #[deny(clippy::correctness)]
-        impl #impl_generics clap::IntoApp for #struct_name #ty_generics #where_clause {
+        #[allow(deprecated)]
+        impl #impl_generics clap::CommandFactory for #struct_name #ty_generics #where_clause {
             fn into_app<'b>() -> clap::Command<'b> {
                 let #app_var = clap::Command::new(#name);
                 <Self as clap::Args>::augment_args(#app_var)
@@ -101,7 +102,7 @@ pub fn gen_for_enum(enum_name: &Ident, generics: &Generics, attrs: &[Attribute])
             clippy::suspicious_else_formatting,
         )]
         #[deny(clippy::correctness)]
-        impl #impl_generics clap::IntoApp for #enum_name #ty_generics #where_clause {
+        impl #impl_generics clap::CommandFactory for #enum_name #ty_generics #where_clause {
             fn into_app<'b>() -> clap::Command<'b> {
                 #[allow(deprecated)]
                 let #app_var = clap::Command::new(#name)

clap_derive/src/dummies.rs

@@ -18,7 +18,8 @@ pub fn parser_enum(name: &Ident) {
 
 pub fn into_app(name: &Ident) {
     append_dummy(quote! {
-        impl clap::IntoApp for #name {
+        #[allow(deprecated)]
+        impl clap::CommandFactory for #name {
             fn into_app<'b>() -> clap::Command<'b> {
                 unimplemented!()
             }

examples/tutorial_derive/04_04_custom.rs

@@ -1,4 +1,4 @@
-use clap::{ErrorKind, IntoApp, Parser};
+use clap::{CommandFactory, ErrorKind, Parser};
 
 #[derive(Parser)]
 #[clap(author, version, about, long_about = None)]
@@ -41,7 +41,7 @@ fn main() {
     // See if --set-ver was used to set the version manually
     let version = if let Some(ver) = cli.set_ver.as_deref() {
         if cli.major || cli.minor || cli.patch {
-            let mut cmd = Cli::into_app();
+            let mut cmd = Cli::command();
             cmd.error(
                 ErrorKind::ArgumentConflict,
                 "Can't do relative and absolute version change",
@@ -57,7 +57,7 @@ fn main() {
             (false, true, false) => minor += 1,
             (false, false, true) => patch += 1,
             _ => {
-                let mut cmd = Cli::into_app();
+                let mut cmd = Cli::command();
                 cmd.error(
                     ErrorKind::ArgumentConflict,
                     "Cam only modify one version field",
@@ -80,7 +80,7 @@ fn main() {
             // 'or' is preferred to 'or_else' here since `Option::as_deref` is 'const'
             .or(cli.spec_in.as_deref())
             .unwrap_or_else(|| {
-                let mut cmd = Cli::into_app();
+                let mut cmd = Cli::command();
                 cmd.error(
                     ErrorKind::MissingRequiredArgument,
                     "INPUT_FILE or --spec-in is required when using --config",

examples/tutorial_derive/05_01_assert.rs

@@ -16,6 +16,6 @@ fn main() {
 
 #[test]
 fn verify_app() {
-    use clap::IntoApp;
-    Cli::into_app().debug_assert()
+    use clap::CommandFactory;
+    Cli::command().debug_assert()
 }

src/build/command.rs

@@ -40,7 +40,7 @@ use crate::build::debug_asserts::assert_app;
 /// arguments (or lack thereof).
 ///
 /// When deriving a [`Parser`][crate::Parser], you can use
-/// [`IntoApp::into_app`][crate::IntoApp::into_app] to access the
+/// [`CommandFactory::into_app`][crate::CommandFactory::into_app] to access the
 /// `Command`.
 ///
 /// # Examples

src/derive.rs

@@ -12,7 +12,7 @@ use std::ffi::OsString;
 /// into concrete instance of the user struct.
 ///
 /// This trait is primarily a convenience on top of [`FromArgMatches`] +
-/// [`IntoApp`] which uses those two underlying traits to build the two
+/// [`CommandFactory`] which uses those two underlying traits to build the two
 /// fundamental functions `parse` which uses the `std::env::args_os` iterator,
 /// and `parse_from` which allows the consumer to supply the iterator (along
 /// with fallible options for each).
@@ -76,10 +76,10 @@ use std::ffi::OsString;
 /// }
 /// ```
 ///
-pub trait Parser: FromArgMatches + IntoApp + Sized {
+pub trait Parser: FromArgMatches + CommandFactory + Sized {
     /// Parse from `std::env::args_os()`, exit on error
     fn parse() -> Self {
-        let matches = <Self as IntoApp>::into_app().get_matches();
+        let matches = <Self as CommandFactory>::command().get_matches();
         let res =
             <Self as FromArgMatches>::from_arg_matches(&matches).map_err(format_error::<Self>);
         match res {
@@ -94,7 +94,7 @@ pub trait Parser: FromArgMatches + IntoApp + Sized {
 
     /// Parse from `std::env::args_os()`, return Err on error.
     fn try_parse() -> Result<Self, Error> {
-        let matches = <Self as IntoApp>::into_app().try_get_matches()?;
+        let matches = <Self as CommandFactory>::command().try_get_matches()?;
         <Self as FromArgMatches>::from_arg_matches(&matches).map_err(format_error::<Self>)
     }
 
@@ -104,7 +104,7 @@ pub trait Parser: FromArgMatches + IntoApp + Sized {
         I: IntoIterator<Item = T>,
         T: Into<OsString> + Clone,
     {
-        let matches = <Self as IntoApp>::into_app().get_matches_from(itr);
+        let matches = <Self as CommandFactory>::command().get_matches_from(itr);
         let res =
             <Self as FromArgMatches>::from_arg_matches(&matches).map_err(format_error::<Self>);
         match res {
@@ -123,7 +123,7 @@ pub trait Parser: FromArgMatches + IntoApp + Sized {
         I: IntoIterator<Item = T>,
         T: Into<OsString> + Clone,
     {
-        let matches = <Self as IntoApp>::into_app().try_get_matches_from(itr)?;
+        let matches = <Self as CommandFactory>::command().try_get_matches_from(itr)?;
         <Self as FromArgMatches>::from_arg_matches(&matches).map_err(format_error::<Self>)
     }
 
@@ -133,7 +133,7 @@ pub trait Parser: FromArgMatches + IntoApp + Sized {
         I: IntoIterator<Item = T>,
         T: Into<OsString> + Clone,
     {
-        let matches = <Self as IntoApp>::into_app_for_update().get_matches_from(itr);
+        let matches = <Self as CommandFactory>::command_for_update().get_matches_from(itr);
         let res = <Self as FromArgMatches>::update_from_arg_matches(self, &matches)
             .map_err(format_error::<Self>);
         if let Err(e) = res {
@@ -149,20 +149,20 @@ pub trait Parser: FromArgMatches + IntoApp + Sized {
         I: IntoIterator<Item = T>,
         T: Into<OsString> + Clone,
     {
-        let matches = <Self as IntoApp>::into_app_for_update().try_get_matches_from(itr)?;
+        let matches = <Self as CommandFactory>::command_for_update().try_get_matches_from(itr)?;
         <Self as FromArgMatches>::update_from_arg_matches(self, &matches)
             .map_err(format_error::<Self>)
     }
 
-    /// Deprecated, `StructOpt::clap` replaced with [`IntoCommand::into_app`] (derive as part of
+    /// Deprecated, `StructOpt::clap` replaced with [`IntoCommand::command`] (derive as part of
     /// [`Parser`])
     #[deprecated(
         since = "3.0.0",
-        note = "`StructOpt::clap` is replaced with `IntoCommand::into_app` (derived as part of `Parser`)"
+        note = "`StructOpt::clap` is replaced with `IntoCommand::command` (derived as part of `Parser`)"
     )]
     #[doc(hidden)]
     fn clap<'help>() -> Command<'help> {
-        <Self as IntoApp>::into_app()
+        <Self as CommandFactory>::command()
     }
 
     /// Deprecated, `StructOpt::from_clap` replaced with [`FromArgMatches::from_arg_matches`] (derive as part of
@@ -229,14 +229,29 @@ pub trait Parser: FromArgMatches + IntoApp + Sized {
 /// Create an [`Command`] relevant for a user-defined container.
 ///
 /// Derived as part of [`Parser`].
-pub trait IntoApp: Sized {
+pub trait CommandFactory: Sized {
     /// Build an [`Command`] that can instantiate `Self`.
     ///
     /// See [`FromArgMatches::from_arg_matches`] for instantiating `Self`.
+    fn command<'help>() -> Command<'help> {
+        #[allow(deprecated)]
+        Self::into_app()
+    }
+    /// Deprecated, replaced with `CommandFactory::command`
+    #[deprecated(since = "3.1.0", note = "Replaced with `CommandFactory::command")]
     fn into_app<'help>() -> Command<'help>;
     /// Build an [`Command`] that can update `self`.
     ///
     /// See [`FromArgMatches::update_from_arg_matches`] for updating `self`.
+    fn command_for_update<'help>() -> Command<'help> {
+        #[allow(deprecated)]
+        Self::into_app_for_update()
+    }
+    /// Deprecated, replaced with `CommandFactory::command_for_update`
+    #[deprecated(
+        since = "3.1.0",
+        note = "Replaced with `CommandFactory::command_for_update"
+    )]
     fn into_app_for_update<'help>() -> Command<'help>;
 }
 
@@ -315,13 +330,13 @@ pub trait FromArgMatches: Sized {
 pub trait Args: FromArgMatches + Sized {
     /// Append to [`Command`] so it can instantiate `Self`.
     ///
-    /// See also [`IntoApp`].
+    /// See also [`CommandFactory`].
     fn augment_args(cmd: Command<'_>) -> Command<'_>;
     /// Append to [`Command`] so it can update `self`.
     ///
     /// This is used to implement `#[clap(flatten)]`
     ///
-    /// See also [`IntoApp`].
+    /// See also [`CommandFactory`].
     fn augment_args_for_update(cmd: Command<'_>) -> Command<'_>;
 }
 
@@ -359,13 +374,13 @@ pub trait Args: FromArgMatches + Sized {
 pub trait Subcommand: FromArgMatches + Sized {
     /// Append to [`Command`] so it can instantiate `Self`.
     ///
-    /// See also [`IntoApp`].
+    /// See also [`CommandFactory`].
     fn augment_subcommands(cmd: Command<'_>) -> Command<'_>;
     /// Append to [`Command`] so it can update `self`.
     ///
     /// This is used to implement `#[clap(flatten)]`
     ///
-    /// See also [`IntoApp`].
+    /// See also [`CommandFactory`].
     fn augment_subcommands_for_update(cmd: Command<'_>) -> Command<'_>;
     /// Test whether `Self` can parse a specific subcommand
     fn has_subcommand(name: &str) -> bool;
@@ -451,12 +466,13 @@ impl<T: Parser> Parser for Box<T> {
     }
 }
 
-impl<T: IntoApp> IntoApp for Box<T> {
+#[allow(deprecated)]
+impl<T: CommandFactory> CommandFactory for Box<T> {
     fn into_app<'help>() -> Command<'help> {
-        <T as IntoApp>::into_app()
+        <T as CommandFactory>::into_app()
     }
     fn into_app_for_update<'help>() -> Command<'help> {
-        <T as IntoApp>::into_app_for_update()
+        <T as CommandFactory>::into_app_for_update()
     }
 }
 
@@ -490,7 +506,7 @@ impl<T: Subcommand> Subcommand for Box<T> {
     }
 }
 
-fn format_error<I: IntoApp>(err: crate::Error) -> crate::Error {
-    let mut cmd = I::into_app();
+fn format_error<I: CommandFactory>(err: crate::Error) -> crate::Error {
+    let mut cmd = I::command();
     err.format(&mut cmd)
 }

src/lib.rs

@@ -35,7 +35,7 @@ pub use crate::parse::{ArgMatches, Indices, OsValues, ValueSource, Values};
 #[cfg(feature = "color")]
 pub use crate::util::color::ColorChoice;
 
-pub use crate::derive::{ArgEnum, Args, FromArgMatches, IntoApp, Parser, Subcommand};
+pub use crate::derive::{ArgEnum, Args, CommandFactory, FromArgMatches, Parser, Subcommand};
 
 pub use crate::error::{ErrorKind, Result};
 
@@ -55,6 +55,10 @@ pub use yaml_rust::YamlLoader;
 #[doc(hidden)]
 pub use clap_derive::{self, *};
 
+/// Deprecated, replaced with [`CommandFactory`]
+#[deprecated(since = "3.0.0", note = "Replaced with `CommandFactory`")]
+#[doc(hidden)]
+pub use CommandFactory as IntoApp;
 /// Deprecated, replaced with [`Parser`]
 #[deprecated(since = "3.0.0", note = "Replaced with `Parser`")]
 #[doc(hidden)]

tests/derive/app_name.rs

@@ -1,4 +1,4 @@
-use clap::IntoApp;
+use clap::CommandFactory;
 use clap::Parser;
 #[test]
 fn app_name_in_short_help_from_struct() {
@@ -7,7 +7,7 @@ fn app_name_in_short_help_from_struct() {
     struct MyApp {}
 
     let mut help = Vec::new();
-    MyApp::into_app().write_help(&mut help).unwrap();
+    MyApp::command().write_help(&mut help).unwrap();
     let help = String::from_utf8(help).unwrap();
 
     assert!(help.contains("my-cmd"));
@@ -20,7 +20,7 @@ fn app_name_in_long_help_from_struct() {
     struct MyApp {}
 
     let mut help = Vec::new();
-    MyApp::into_app().write_long_help(&mut help).unwrap();
+    MyApp::command().write_long_help(&mut help).unwrap();
     let help = String::from_utf8(help).unwrap();
 
     assert!(help.contains("my-cmd"));
@@ -33,7 +33,7 @@ fn app_name_in_short_help_from_enum() {
     enum MyApp {}
 
     let mut help = Vec::new();
-    MyApp::into_app().write_help(&mut help).unwrap();
+    MyApp::command().write_help(&mut help).unwrap();
     let help = String::from_utf8(help).unwrap();
 
     assert!(help.contains("my-cmd"));
@@ -46,7 +46,7 @@ fn app_name_in_long_help_from_enum() {
     enum MyApp {}
 
     let mut help = Vec::new();
-    MyApp::into_app().write_long_help(&mut help).unwrap();
+    MyApp::command().write_long_help(&mut help).unwrap();
     let help = String::from_utf8(help).unwrap();
 
     assert!(help.contains("my-cmd"));
@@ -58,7 +58,7 @@ fn app_name_in_short_version_from_struct() {
     #[clap(name = "my-cmd")]
     struct MyApp {}
 
-    let version = MyApp::into_app().render_version();
+    let version = MyApp::command().render_version();
 
     assert!(version.contains("my-cmd"));
 }
@@ -69,7 +69,7 @@ fn app_name_in_long_version_from_struct() {
     #[clap(name = "my-cmd")]
     struct MyApp {}
 
-    let version = MyApp::into_app().render_long_version();
+    let version = MyApp::command().render_long_version();
 
     assert!(version.contains("my-cmd"));
 }
@@ -80,7 +80,7 @@ fn app_name_in_short_version_from_enum() {
     #[clap(name = "my-cmd")]
     enum MyApp {}
 
-    let version = MyApp::into_app().render_version();
+    let version = MyApp::command().render_version();
 
     assert!(version.contains("my-cmd"));
 }
@@ -91,7 +91,7 @@ fn app_name_in_long_version_from_enum() {
     #[clap(name = "my-cmd")]
     enum MyApp {}
 
-    let version = MyApp::into_app().render_long_version();
+    let version = MyApp::command().render_long_version();
 
     assert!(version.contains("my-cmd"));
 }

tests/derive/arguments.rs

@@ -12,7 +12,7 @@
 // commit#ea76fa1b1b273e65e3b0b1046643715b49bec51f which is licensed under the
 // MIT/Apache 2.0 license.
 
-use clap::IntoApp;
+use clap::CommandFactory;
 use clap::Parser;
 
 #[test]
@@ -52,7 +52,7 @@ fn auto_value_name() {
     }
 
     let mut help = Vec::new();
-    Opt::into_app().write_help(&mut help).unwrap();
+    Opt::command().write_help(&mut help).unwrap();
     let help = String::from_utf8(help).unwrap();
 
     assert!(help.contains("MY_SPECIAL_ARG"));
@@ -72,7 +72,7 @@ fn explicit_value_name() {
     }
 
     let mut help = Vec::new();
-    Opt::into_app().write_help(&mut help).unwrap();
+    Opt::command().write_help(&mut help).unwrap();
     let help = String::from_utf8(help).unwrap();
 
     assert!(help.contains("BROWNIE_POINTS"));