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 clap-rs#2617

src/build/app/mod.rs

@@ -383,6 +383,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.
     ///
@@ -792,6 +799,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.
     ///
@@ -832,6 +845,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
@@ -884,6 +903,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.
@@ -1020,6 +1045,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.
     ///
@@ -1133,6 +1164,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
@@ -2016,6 +2053,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.
@@ -2102,6 +2145,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`.
@@ -2151,6 +2204,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

@@ -312,6 +312,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
@@ -667,6 +686,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.
@@ -739,6 +764,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
@@ -796,6 +827,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
@@ -870,6 +907,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
@@ -946,6 +996,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.
     ///
@@ -1512,6 +1575,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`.
@@ -1598,6 +1667,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`.
@@ -4191,6 +4266,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*.
     ///
@@ -4430,6 +4511,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
@@ -4651,6 +4742,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.
@@ -4680,6 +4777,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(mut self, s: Option<&'help str>) -> 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

@@ -65,3 +65,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)
+    }
+}