fix: Ease clap2->clap3 migration with deprecations

- `App::with_defaults` was not included since that has been deprecated
  since 2.14
- `App::args_from_usage` does not have a close enough parallel in the
  new API, as far as I could tell
- `ArgMatches::usage` cannot have a thin wrapper around
  `App::generate_usage`.
- `App::write_*`: getting lazy, didn't seem like high value functions
- Any `Settings` (some things need to be figured out here)

This is a part of #2617

src/build/app/mod.rs

@@ -378,6 +378,13 @@ impl<'help> App<'help> {
         )
     }
 
+    /// Deprecated, see [`App::from`]
+    #[cfg(feature = "yaml")]
+    #[deprecated(since = "3.0.0", note = "Replaced with `App::from`")]
+    pub fn from_yaml(yaml: &'help Yaml) -> Self {
+        Self::from(yaml)
+    }
+
     /// Sets a string of author(s) that will be displayed to the user when they
     /// request the help message.
     ///
@@ -787,6 +794,12 @@ impl<'help> App<'help> {
         self
     }
 
+    /// Deprecated, see [`App::override_usage`]
+    #[deprecated(since = "3.0.0", note = "Replaced with `App::override_usage`")]
+    pub fn usage<S: Into<&'help str>>(self, usage: S) -> Self {
+        self.override_usage(usage)
+    }
+
     /// Overrides the `clap` generated help message. This should only be used
     /// when the auto-generated message does not suffice.
     ///
@@ -827,6 +840,12 @@ impl<'help> App<'help> {
         self
     }
 
+    /// Deprecated, see [`App::override_help`]
+    #[deprecated(since = "3.0.0", note = "Replaced with `App::override_help`")]
+    pub fn help<S: Into<&'help str>>(self, help: S) -> Self {
+        self.override_help(help)
+    }
+
     /// Sets the help template to be used, overriding the default format.
     ///
     /// **NOTE:** The template system is by design very simple. Therefore, the
@@ -875,6 +894,12 @@ impl<'help> App<'help> {
         self
     }
 
+    /// Deprecated, see [`App::help_template`]
+    #[deprecated(since = "3.0.0", note = "Replaced with `App::help_template`")]
+    pub fn template<S: Into<&'help str>>(self, s: S) -> Self {
+        self.help_template(s)
+    }
+
     /// Enables a single settings for the current (this `App` instance) command or subcommand.
     ///
     /// See [`AppSettings`] for a full list of possibilities and examples.
@@ -1033,6 +1058,12 @@ impl<'help> App<'help> {
         self
     }
 
+    /// Deprecated, see [`App::term_width`]
+    #[deprecated(since = "3.0.0", note = "Replaced with `App::term_width`")]
+    pub fn set_term_width(self, width: usize) -> Self {
+        self.term_width(width)
+    }
+
     /// Sets the maximum terminal width at which to wrap help messages. Using `0`
     /// will ignore terminal widths and use source formatting.
     ///
@@ -1136,6 +1167,12 @@ impl<'help> App<'help> {
         self
     }
 
+    /// Deprecated, see [`App::arg`]
+    #[deprecated(since = "3.0.0", note = "Replaced with `App::arg`")]
+    pub fn arg_from_usage(self, usage: &'help str) -> Self {
+        self.arg(usage)
+    }
+
     /// If this `App` instance is a subcommand, this method adds an alias, which
     /// allows this subcommand to be accessed via *either* the original name, or
     /// this given alias. This is more efficient and easier than creating
@@ -2025,6 +2062,12 @@ impl<'help> App<'help> {
         self.try_get_matches_from(&mut env::args_os())
     }
 
+    /// Deprecated, see [`App::try_get_matches`]
+    #[deprecated(since = "3.0.0", note = "Replaced with `App::try_get_matches`")]
+    pub fn get_matches_safe(self) -> ClapResult<ArgMatches> {
+        self.try_get_matches()
+    }
+
     /// Starts the parsing process. Like [`App::get_matches`] this method does not return a [`clap::Result`]
     /// and will automatically exit with an error message. This method, however, lets you specify
     /// what iterator to use when performing matches, such as a [`Vec`] of your making.
@@ -2111,6 +2154,16 @@ impl<'help> App<'help> {
         self.try_get_matches_from_mut(itr)
     }
 
+    /// Deprecated, see [`App::try_get_matches_from`]
+    #[deprecated(since = "3.0.0", note = "Replaced with `App::try_get_matches_from`")]
+    pub fn get_matches_from_safe<I, T>(self, itr: I) -> ClapResult<ArgMatches>
+    where
+        I: IntoIterator<Item = T>,
+        T: Into<OsString> + Clone,
+    {
+        self.try_get_matches_from(itr)
+    }
+
     /// Starts the parsing process without consuming the [`App`] struct `self`. This is normally not
     /// the desired functionality, instead prefer [`App::try_get_matches_from`] which *does*
     /// consume `self`.
@@ -2160,6 +2213,19 @@ impl<'help> App<'help> {
         self._do_parse(&mut it)
     }
 
+    /// Deprecated, see [`App::try_get_matches_from_mut`]
+    #[deprecated(
+        since = "3.0.0",
+        note = "Replaced with `App::try_get_matches_from_mut`"
+    )]
+    pub fn get_matches_from_safe_borrow<I, T>(&mut self, itr: I) -> ClapResult<ArgMatches>
+    where
+        I: IntoIterator<Item = T>,
+        T: Into<OsString> + Clone,
+    {
+        self.try_get_matches_from_mut(itr)
+    }
+
     /// Sets the placeholder text used for subcommands when printing usage and help.
     /// By default, this is "SUBCOMMAND" with a header of "SUBCOMMANDS".
     ///

src/build/arg/mod.rs

@@ -344,6 +344,25 @@ impl<'help> Arg<'help> {
         }
     }
 
+    /// Deprecated, see [`Arg::new`]
+    #[deprecated(since = "3.0.0", note = "Replaced with `Arg::new`")]
+    pub fn with_name<S: Into<&'help str>>(n: S) -> Self {
+        Self::new(n)
+    }
+
+    /// Deprecated, see [`Arg::from`]
+    #[cfg(feature = "yaml")]
+    #[deprecated(since = "3.0.0", note = "Replaced with `Arg::from`")]
+    pub fn from_yaml(y: &'help Yaml) -> Self {
+        Self::from(y)
+    }
+
+    /// Deprecated, see [`Arg::from`]
+    #[deprecated(since = "3.0.0", note = "Replaced with `Arg::from`")]
+    pub fn from_usage(u: &'help str) -> Self {
+        Self::from(u)
+    }
+
     pub(crate) fn generated(mut self) -> Self {
         self.provider = ArgProvider::Generated;
         self
@@ -689,6 +708,12 @@ impl<'help> Arg<'help> {
         self
     }
 
+    /// Deprecated, see [`Arg::about`]
+    #[deprecated(since = "3.0.0", note = "Replaced with `Arg::about`")]
+    pub fn help(self, h: &'help str) -> Self {
+        self.about(h)
+    }
+
     /// Sets the long help text of the argument that will be displayed to the user when they print
     /// the help information with `--help`. Typically this a more detailed (multi-line) message
     /// that describes the arg.
@@ -761,6 +786,12 @@ impl<'help> Arg<'help> {
         self
     }
 
+    /// Deprecated, see [`Arg::long_about`]
+    #[deprecated(since = "3.0.0", note = "Replaced with `Arg::long_about`")]
+    pub fn long_help(self, h: &'help str) -> Self {
+        self.long_about(h)
+    }
+
     /// Set this arg as [required] as long as the specified argument is not present at runtime.
     ///
     /// **Pro Tip:** Using `Arg::required_unless_present` implies [`Arg::required`] and is therefore not
@@ -818,6 +849,12 @@ impl<'help> Arg<'help> {
         self
     }
 
+    /// Deprecated, see [`Arg::required_unless_present`]
+    #[deprecated(since = "3.0.0", note = "Replaced with `Arg::required_unless_present`")]
+    pub fn required_unless<T: Key>(self, arg_id: T) -> Self {
+        self.required_unless_present(arg_id)
+    }
+
     /// Sets this arg as [required] unless *all* of the specified arguments are present at runtime.
     ///
     /// In other words, parsing will succeed only if user either
@@ -892,6 +929,19 @@ impl<'help> Arg<'help> {
         self.setting(ArgSettings::RequiredUnlessAll)
     }
 
+    /// Deprecated, see [`Arg::required_unless_present_all`]
+    #[deprecated(
+        since = "3.0.0",
+        note = "Replaced with `Arg::required_unless_present_all`"
+    )]
+    pub fn required_unless_all<T, I>(self, names: I) -> Self
+    where
+        I: IntoIterator<Item = T>,
+        T: Key,
+    {
+        self.required_unless_present_all(names)
+    }
+
     /// Sets this arg as [required] unless *any* of the specified arguments are present at runtime.
     ///
     /// In other words, parsing will succeed only if user either
@@ -968,6 +1018,19 @@ impl<'help> Arg<'help> {
         self
     }
 
+    /// Deprecated, see [`Arg::required_unless_present_any`]
+    #[deprecated(
+        since = "3.0.0",
+        note = "Replaced with `Arg::required_unless_present_any`"
+    )]
+    pub fn required_unless_any<T, I>(self, names: I) -> Self
+    where
+        I: IntoIterator<Item = T>,
+        T: Key,
+    {
+        self.required_unless_present_any(names)
+    }
+
     /// Sets a conflicting argument by name. I.e. when using this argument,
     /// the following argument can't be present and vice versa.
     ///
@@ -1534,6 +1597,12 @@ impl<'help> Arg<'help> {
         self
     }
 
+    /// Deprecated, see [`Arg::required_if_eq`]
+    #[deprecated(since = "3.0.0", note = "Replaced with `Arg::required_if_eq`")]
+    pub fn required_if<T: Key>(self, arg_id: T, val: &'help str) -> Self {
+        self.required_if_eq(arg_id, val)
+    }
+
     /// Allows specifying that this argument is [required] based on multiple conditions. The
     /// conditions are set up in a `(arg, val)` style tuple. The requirement will only become valid
     /// if one of the specified `arg`'s value equals its corresponding `val`.
@@ -1620,6 +1689,12 @@ impl<'help> Arg<'help> {
         self
     }
 
+    /// Deprecated, see [`Arg::required_if_eq_any`]
+    #[deprecated(since = "3.0.0", note = "Replaced with `Arg::required_if_eq_any`")]
+    pub fn required_ifs<T: Key>(self, ifs: &[(T, &'help str)]) -> Self {
+        self.required_if_eq_any(ifs)
+    }
+
     /// Allows specifying that this argument is [required] based on multiple conditions. The
     /// conditions are set up in a `(arg, val)` style tuple. The requirement will only become valid
     /// if every one of the specified `arg`'s value equals its corresponding `val`.
@@ -4204,6 +4279,12 @@ impl<'help> Arg<'help> {
         }
     }
 
+    /// Deprecated, see [`Arg::forbid_empty_values`]
+    #[deprecated(since = "3.0.0", note = "Replaced with `Arg::forbid_empty_values`")]
+    pub fn empty_values(self, empty: bool) -> Self {
+        self.forbid_empty_values(!empty)
+    }
+
     /// Specifies that the argument may have an unknown number of multiple values. Without any other
     /// settings, this argument may appear only *once*.
     ///
@@ -4443,6 +4524,16 @@ impl<'help> Arg<'help> {
         }
     }
 
+    /// Deprecated, see [`Arg::multiple_occurrences`] (most likely what you want) and
+    /// [`Arg::multiple_values`]
+    #[deprecated(
+        since = "3.0.0",
+        note = "Split into `Arg::multiple_occurrences` (most likely what you want)  and `Arg::multiple_values`"
+    )]
+    pub fn multiple(self, multi: bool) -> Self {
+        self.multiple_occurrences(multi).multiple_values(multi)
+    }
+
     /// Indicates that all parameters passed after this should not be parsed
     /// individually, but rather passed in their entirety. It is worth noting
     /// that setting this requires all values to come after a `--` to indicate they
@@ -4664,6 +4755,12 @@ impl<'help> Arg<'help> {
         self
     }
 
+    /// Deprecated, see [`Arg::setting`]
+    #[deprecated(since = "3.0.0", note = "Replaced with `Arg::setting`")]
+    pub fn set(self, s: ArgSettings) -> Self {
+        self.setting(s)
+    }
+
     /// Disables a single setting for the current (this `Arg` instance) argument.
     ///
     /// See [`ArgSettings`] for a full list of possibilities and examples.
@@ -4693,6 +4790,12 @@ impl<'help> Arg<'help> {
         self
     }
 
+    /// Deprecated, see [`Arg::unset_setting`]
+    #[deprecated(since = "3.0.0", note = "Replaced with `Arg::unset_setting`")]
+    pub fn unset(self, s: ArgSettings) -> Self {
+        self.unset_setting(s)
+    }
+
     /// Set a custom heading for this arg to be printed under
     #[inline]
     pub fn help_heading<O>(mut self, heading: O) -> Self

src/build/arg_group.rs

@@ -108,6 +108,19 @@ impl<'help> ArgGroup<'help> {
         ArgGroup::default().name(n)
     }
 
+    /// Deprecated, see [`ArgGroup::new`]
+    #[deprecated(since = "3.0.0", note = "Replaced with `ArgGroup::new`")]
+    pub fn with_name<S: Into<&'help str>>(n: S) -> Self {
+        Self::new(n)
+    }
+
+    /// Deprecated, see [`ArgGroup::from`]
+    #[cfg(feature = "yaml")]
+    #[deprecated(since = "3.0.0", note = "Replaced with `ArgGroup::from`")]
+    pub fn from_yaml(yaml: &'help Yaml) -> Self {
+        Self::from(yaml)
+    }
+
     /// Sets the group name.
     ///
     /// # Examples

src/lib.rs

@@ -64,3 +64,22 @@ mod util;
 const INTERNAL_ERROR_MSG: &str = "Fatal internal error. Please consider filing a bug \
                                   report at https://github.com/clap-rs/clap/issues";
 const INVALID_UTF8: &str = "unexpected invalid UTF-8 code point";
+
+/// Deprecated, see [`App`]
+#[derive(Debug, Copy, Clone)]
+pub struct SubCommand {}
+
+impl SubCommand {
+    /// Deprecated, see [`App::new`]
+    #[deprecated(since = "3.0.0", note = "Replaced with `App::new`)")]
+    pub fn with_name<'help>(name: &str) -> App<'help> {
+        App::new(name)
+    }
+
+    /// Deprecated, see [`App::from`]
+    #[cfg(feature = "yaml")]
+    #[deprecated(since = "3.0.0", note = "Replaced with `App::from`)")]
+    pub fn from_yaml(yaml: &yaml_rust::Yaml) -> App {
+        App::from(yaml)
+    }
+}

src/macros.rs

@@ -650,3 +650,57 @@ macro_rules! debug {
 macro_rules! debug {
     ($($arg:tt)*) => {};
 }
+
+/// Deprecated, see [`ArgMatches::value_of_t`]
+#[macro_export]
+#[deprecated(since = "3.0.0", note = "Replaced with `ArgMatches::value_of_t`")]
+macro_rules! value_t {
+    ($m:ident, $v:expr, $t:ty) => {
+        clap::value_t!($m.value_of($v), $t)
+    };
+    ($m:ident.value_of($v:expr), $t:ty) => {
+        $m.value_of_t::<$t>($v)
+    };
+}
+
+/// Deprecated, see [`ArgMatches::value_of_t_or_exit`]
+#[macro_export]
+#[deprecated(
+    since = "3.0.0",
+    note = "Replaced with `ArgMatches::value_of_t_or_exit`"
+)]
+macro_rules! value_t_or_exit {
+    ($m:ident, $v:expr, $t:ty) => {
+        value_t_or_exit!($m.value_of($v), $t)
+    };
+    ($m:ident.value_of($v:expr), $t:ty) => {
+        $m.value_of_t_or_exit::<$t>($v)
+    };
+}
+
+/// Deprecated, see [`ArgMatches::values_of_t`]
+#[macro_export]
+#[deprecated(since = "3.0.0", note = "Replaced with `ArgMatches::values_of_t`")]
+macro_rules! values_t {
+    ($m:ident, $v:expr, $t:ty) => {
+        values_t!($m.values_of($v), $t)
+    };
+    ($m:ident.values_of($v:expr), $t:ty) => {
+        $m.values_of_t::<$t>($v)
+    };
+}
+
+/// Deprecated, see [`ArgMatches::values_of_t_or_exit`]
+#[macro_export]
+#[deprecated(
+    since = "3.0.0",
+    note = "Replaced with `ArgMatches::values_of_t_or_exit`"
+)]
+macro_rules! values_t_or_exit {
+    ($m:ident, $v:expr, $t:ty) => {
+        values_t_or_exit!($m.values_of($v), $t)
+    };
+    ($m:ident.values_of($v:expr), $t:ty) => {
+        $m.values_of_t_or_exit::<$t>($v)
+    };
+}