Skip to content

Commit

Permalink
fix: Deprecate various APIs
Browse files Browse the repository at this point in the history 
- ArgSettings are part of clap-rs#2717
- Errors are part of clap-rs#2628
- `help_heading` is part of clap-rs#1807 and clap-rs#1553
- Some misc parts are for API consistency
  • Loading branch information
@epage
epage committed Feb 11, 2022
1 parent 4868680 commit 9bd7060
Show file tree
Hide file tree
Showing 12 changed files with 158 additions and 203 deletions.
2 changes: 1 addition & 1 deletion clap_complete/src/shells/fish.rs
View file
Expand Up @@ -153,7 +153,7 @@ fn value_completion(option: &Arg) -> String {
format!(
" -r -f -a \"{{{}}}\"",
data.iter()
.filter_map(|value| if value.is_hidden() {
.filter_map(|value| if value.is_hide_set() {
None
} else {
Some(format!(
Expand Down
2 changes: 1 addition & 1 deletion clap_complete/src/shells/zsh.rs
View file
Expand Up @@ -515,7 +515,7 @@ fn arg_conflicts(app: &App, arg: &Arg, app_global: Option<&App>) -> String {
}

let mut res = vec![];
match (app_global, arg.get_global()) {
match (app_global, arg.is_global_set()) {
(Some(x), true) => {
let conflicts = x.get_arg_conflicts_with(arg);

Expand Down
20 changes: 4 additions & 16 deletions src/build/app.rs
View file
Expand Up @@ -1325,20 +1325,10 @@ impl<'help> App<'help> {
}
}

/// Set the default section heading for future args.
///
/// This will be used for any arg that hasn't had [`Arg::help_heading`] called.
///
/// This is useful if the default `OPTIONS` or `ARGS` headings are
/// not specific enough for one's use case.
///
/// For subcommands, see [`App::subcommand_help_heading`]
///
/// [`App::arg`]: App::arg()
/// [`Arg::help_heading`]: crate::Arg::help_heading()
/// Deprecated, replaced with [`App::next_help_heading`]
#[inline]
#[must_use]
// TODO: Deprecate
#[deprecated(since = "3.1.0", note = "Replaced with `App::next_help_heading`")]
pub fn help_heading<O>(self, heading: O) -> Self
where
O: Into<Option<&'help str>>,
Expand Down Expand Up @@ -2197,11 +2187,9 @@ impl<'help> App<'help> {
self.long_about
}

/// Get the custom section heading specified via [`App::help_heading`].
///
/// [`App::help_heading`]: App::help_heading()
/// Deprecated, replaced with [`App::get_next_help_heading`]
#[inline]
// TODO: Deprecate
#[deprecated(since = "3.1.0", note = "Replaced with `App::get_next_help_heading`")]
pub fn get_help_heading(&self) -> Option<&'help str> {
self.get_next_help_heading()
}
Expand Down
140 changes: 8 additions & 132 deletions src/build/arg.rs
View file
@@ -1,3 +1,5 @@
#![allow(deprecated)]

// Std
use std::{
borrow::Cow,
Expand Down Expand Up @@ -872,7 +874,6 @@ impl<'help> Arg<'help> {
///
/// [`ArgSettings`]: crate::ArgSettings
#[inline]
// TODO: Deprecate
pub fn is_set(&self, s: ArgSettings) -> bool {
self.settings.is_set(s)
}
Expand All @@ -899,7 +900,6 @@ impl<'help> Arg<'help> {
/// ```
#[inline]
#[must_use]
// TODO: Deprecate
pub fn setting<F>(mut self, setting: F) -> Self
where
F: Into<ArgFlags>,
Expand Down Expand Up @@ -930,7 +930,6 @@ impl<'help> Arg<'help> {
/// ```
#[inline]
#[must_use]
// TODO: Deprecate
pub fn unset_setting<F>(mut self, setting: F) -> Self
where
F: Into<ArgFlags>,
Expand Down Expand Up @@ -2128,58 +2127,10 @@ impl<'help> Arg<'help> {
}
}

/// Specifies that an argument should allow grouping of multiple values via a
/// delimiter.
///
/// i.e. should `--option=val1,val2,val3` be parsed as three values (`val1`, `val2`,
/// and `val3`) or as a single value (`val1,val2,val3`). Defaults to using `,` (comma) as the
/// value delimiter for all arguments that accept values (options and positional arguments)
///
/// **NOTE:** When this setting is used, it will default [`Arg::value_delimiter`]
/// to the comma `,`.
///
/// **NOTE:** Implicitly sets [`Arg::takes_value`]
///
/// # Examples
///
/// The following example shows the default behavior.
///
/// ```rust
/// # use clap::{App, Arg};
/// let delims = App::new("prog")
/// .arg(Arg::new("option")
/// .long("option")
/// .use_delimiter(true)
/// .takes_value(true))
/// .get_matches_from(vec![
/// "prog", "--option=val1,val2,val3",
/// ]);
///
/// assert!(delims.is_present("option"));
/// assert_eq!(delims.occurrences_of("option"), 1);
/// assert_eq!(delims.values_of("option").unwrap().collect::<Vec<_>>(), ["val1", "val2", "val3"]);
/// ```
/// The next example shows the difference when turning delimiters off. This is the default
/// behavior
///
/// ```rust
/// # use clap::{App, Arg};
/// let nodelims = App::new("prog")
/// .arg(Arg::new("option")
/// .long("option")
/// .takes_value(true))
/// .get_matches_from(vec![
/// "prog", "--option=val1,val2,val3",
/// ]);
///
/// assert!(nodelims.is_present("option"));
/// assert_eq!(nodelims.occurrences_of("option"), 1);
/// assert_eq!(nodelims.value_of("option").unwrap(), "val1,val2,val3");
/// ```
/// [`Arg::value_delimiter`]: Arg::value_delimiter()
/// Deprecated, replaced with [`Arg::use_value_delimiter`]
#[inline]
#[must_use]
// TODO: Deprecate
#[deprecated(since = "3.1.0", note = "Replaced with `Arg::use_value_delimiter`")]
pub fn use_delimiter(self, yes: bool) -> Self {
self.use_value_delimiter(yes)
}
Expand Down Expand Up @@ -2300,85 +2251,10 @@ impl<'help> Arg<'help> {
}
}

/// Specifies that *multiple values* may only be set using the delimiter.
///
/// This means if an option is encountered, and no delimiter is found, it is assumed that no
/// additional values for that option follow. This is unlike the default, where it is generally
/// assumed that more values will follow regardless of whether or not a delimiter is used.
///
/// **NOTE:** The default is `false`.
///
/// **NOTE:** Setting this requires [`Arg::use_value_delimiter`] and
/// [`Arg::takes_value`]
///
/// **NOTE:** It's a good idea to inform the user that use of a delimiter is required, either
/// through help text or other means.
///
/// # Examples
///
/// These examples demonstrate what happens when `require_delimiter(true)` is used. Notice
/// everything works in this first example, as we use a delimiter, as expected.
///
/// ```rust
/// # use clap::{App, Arg};
/// let delims = App::new("prog")
/// .arg(Arg::new("opt")
/// .short('o')
/// .takes_value(true)
/// .use_value_delimiter(true)
/// .require_delimiter(true)
/// .multiple_values(true))
/// .get_matches_from(vec![
/// "prog", "-o", "val1,val2,val3",
/// ]);
///
/// assert!(delims.is_present("opt"));
/// assert_eq!(delims.values_of("opt").unwrap().collect::<Vec<_>>(), ["val1", "val2", "val3"]);
/// ```
///
/// In this next example, we will *not* use a delimiter. Notice it's now an error.
///
/// ```rust
/// # use clap::{App, Arg, ErrorKind};
/// let res = App::new("prog")
/// .arg(Arg::new("opt")
/// .short('o')
/// .takes_value(true)
/// .use_value_delimiter(true)
/// .require_delimiter(true))
/// .try_get_matches_from(vec![
/// "prog", "-o", "val1", "val2", "val3",
/// ]);
///
/// assert!(res.is_err());
/// let err = res.unwrap_err();
/// assert_eq!(err.kind(), ErrorKind::UnknownArgument);
/// ```
///
/// What's happening is `-o` is getting `val1`, and because delimiters are required yet none
/// were present, it stops parsing `-o`. At this point it reaches `val2` and because no
/// positional arguments have been defined, it's an error of an unexpected argument.
///
/// In this final example, we contrast the above with `clap`'s default behavior where the above
/// is *not* an error.
///
/// ```rust
/// # use clap::{App, Arg};
/// let delims = App::new("prog")
/// .arg(Arg::new("opt")
/// .short('o')
/// .takes_value(true)
/// .multiple_values(true))
/// .get_matches_from(vec![
/// "prog", "-o", "val1", "val2", "val3",
/// ]);
///
/// assert!(delims.is_present("opt"));
/// assert_eq!(delims.values_of("opt").unwrap().collect::<Vec<_>>(), ["val1", "val2", "val3"]);
/// ```
/// Deprecated, replaced with [`Arg::require_value_delimiter`]
#[inline]
#[must_use]
// TODO: Deprecate
#[deprecated(since = "3.1.0", note = "Replaced with `Arg::require_value_delimiter`")]
pub fn require_delimiter(self, yes: bool) -> Self {
self.require_value_delimiter(yes)
}
Expand Down Expand Up @@ -4751,8 +4627,8 @@ impl<'help> Arg<'help> {
self.value_hint
}

/// Get information on if this argument is global or not
// TODO: Deprecate
/// Deprecated, replaced with [`Arg::is_global_set`]
#[deprecated(since = "3.1.0", note = "Replaced with `Arg::is_global_set`")]
pub fn get_global(&self) -> bool {
self.is_global_set()
}
Expand Down

0 comments on commit 9bd7060

Please sign in to comment.