vendor/clap/src/build/possible_value.rs

   1 use std::iter;
   2
   3 use crate::util::eq_ignore_case;
   4
   5 /// A possible value of an argument.
   6 ///
   7 /// This is used for specifying [possible values] of [Args].
   8 ///
   9 /// **NOTE:** This struct is likely not needed for most usecases as it is only required to
  10 /// [hide] single values from help messages and shell completions or to attach [help] to possible values.
  11 ///
  12 /// # Examples
  13 ///
  14 /// ```rust
  15 /// # use clap::{Arg, PossibleValue};
  16 /// let cfg = Arg::new("config")
  17 ///       .takes_value(true)
  18 ///       .value_name("FILE")
  19 ///       .possible_value(PossibleValue::new("fast"))
  20 ///       .possible_value(PossibleValue::new("slow").help("slower than fast"))
  21 ///       .possible_value(PossibleValue::new("secret speed").hide(true));
  22 /// ```
  23 /// [Args]: crate::Arg
  24 /// [possible values]: crate::Arg::possible_value()
  25 /// [hide]: PossibleValue::hide()
  26 /// [help]: PossibleValue::help()
  27 #[derive(Debug, Default, Clone, PartialEq, Eq)]
  28 pub struct PossibleValue<'help> {
  29     name: &'help str,
  30     help: Option<&'help str>,
  31     aliases: Vec<&'help str>, // (name, visible)
  32     hide: bool,
  33 }
  34
  35 impl<'help> PossibleValue<'help> {
  36     /// Create a [`PossibleValue`] with its name.
  37     ///
  38     /// The name will be used to decide whether this value was provided by the user to an argument.
  39     ///
  40     /// **NOTE:** In case it is not [hidden] it will also be shown in help messages for arguments
  41     /// that use it as a [possible value] and have not hidden them through [`Arg::hide_possible_values(true)`].
  42     ///
  43     /// # Examples
  44     ///
  45     /// ```rust
  46     /// # use clap::PossibleValue;
  47     /// PossibleValue::new("fast")
  48     /// # ;
  49     /// ```
  50     /// [hidden]: PossibleValue::hide
  51     /// [possible value]: crate::Arg::possible_values
  52     /// [`Arg::hide_possible_values(true)`]: crate::Arg::hide_possible_values()
  53     pub fn new(name: &'help str) -> Self {
  54         PossibleValue {
  55             name,
  56             ..Default::default()
  57         }
  58     }
  59
  60     /// Sets the help description of the value.
  61     ///
  62     /// This is typically displayed in completions (where supported) and should be a short, one-line
  63     /// description.
  64     ///
  65     /// # Examples
  66     ///
  67     /// ```rust
  68     /// # use clap::PossibleValue;
  69     /// PossibleValue::new("slow")
  70     ///     .help("not fast")
  71     /// # ;
  72     /// ```
  73     #[inline]
  74     #[must_use]
  75     pub fn help(mut self, help: &'help str) -> Self {
  76         self.help = Some(help);
  77         self
  78     }
  79
  80     /// Hides this value from help and shell completions.
  81     ///
  82     /// This is an alternative to hiding through [`Arg::hide_possible_values(true)`], if you only
  83     /// want to hide some values.
  84     ///
  85     /// # Examples
  86     ///
  87     /// ```rust
  88     /// # use clap::PossibleValue;
  89     /// PossibleValue::new("secret")
  90     ///     .hide(true)
  91     /// # ;
  92     /// ```
  93     /// [`Arg::hide_possible_values(true)`]: crate::Arg::hide_possible_values()
  94     #[inline]
  95     #[must_use]
  96     pub fn hide(mut self, yes: bool) -> Self {
  97         self.hide = yes;
  98         self
  99     }
 100
 101     /// Sets a *hidden* alias for this argument value.
 102     ///
 103     /// # Examples
 104     ///
 105     /// ```rust
 106     /// # use clap::PossibleValue;
 107     /// PossibleValue::new("slow")
 108     ///     .alias("not-fast")
 109     /// # ;
 110     /// ```
 111     #[must_use]
 112     pub fn alias(mut self, name: &'help str) -> Self {
 113         self.aliases.push(name);
 114         self
 115     }
 116
 117     /// Sets multiple *hidden* aliases for this argument value.
 118     ///
 119     /// # Examples
 120     ///
 121     /// ```rust
 122     /// # use clap::PossibleValue;
 123     /// PossibleValue::new("slow")
 124     ///     .aliases(["not-fast", "snake-like"])
 125     /// # ;
 126     /// ```
 127     #[must_use]
 128     pub fn aliases<I>(mut self, names: I) -> Self
 129     where
 130         I: IntoIterator<Item = &'help str>,
 131     {
 132         self.aliases.extend(names.into_iter());
 133         self
 134     }
 135 }
 136
 137 /// Reflection
 138 impl<'help> PossibleValue<'help> {
 139     /// Get the name of the argument value
 140     #[inline]
 141     pub fn get_name(&self) -> &'help str {
 142         self.name
 143     }
 144
 145     /// Get the help specified for this argument, if any
 146     #[inline]
 147     pub fn get_help(&self) -> Option<&'help str> {
 148         self.help
 149     }
 150
 151     /// Deprecated, replaced with [`PossibleValue::is_hide_set`]
 152     #[inline]
 153     #[deprecated(since = "3.1.0", note = "Replaced with `PossibleValue::is_hide_set`")]
 154     pub fn is_hidden(&self) -> bool {
 155         self.is_hide_set()
 156     }
 157
 158     /// Report if [`PossibleValue::hide`] is set
 159     #[inline]
 160     pub fn is_hide_set(&self) -> bool {
 161         self.hide
 162     }
 163
 164     /// Get the name if argument value is not hidden, `None` otherwise
 165     pub fn get_visible_name(&self) -> Option<&'help str> {
 166         if self.hide {
 167             None
 168         } else {
 169             Some(self.name)
 170         }
 171     }
 172
 173     /// Returns all valid values of the argument value.
 174     ///
 175     /// Namely the name and all aliases.
 176     pub fn get_name_and_aliases(&self) -> impl Iterator<Item = &'help str> + '_ {
 177         iter::once(&self.name).chain(&self.aliases).copied()
 178     }
 179
 180     /// Tests if the value is valid for this argument value
 181     ///
 182     /// The value is valid if it is either the name or one of the aliases.
 183     ///
 184     /// # Examples
 185     ///
 186     /// ```rust
 187     /// # use clap::PossibleValue;
 188     /// let arg_value = PossibleValue::new("fast").alias("not-slow");
 189     ///
 190     /// assert!(arg_value.matches("fast", false));
 191     /// assert!(arg_value.matches("not-slow", false));
 192     ///
 193     /// assert!(arg_value.matches("FAST", true));
 194     /// assert!(!arg_value.matches("FAST", false));
 195     /// ```
 196     pub fn matches(&self, value: &str, ignore_case: bool) -> bool {
 197         if ignore_case {
 198             self.get_name_and_aliases()
 199                 .any(|name| eq_ignore_case(name, value))
 200         } else {
 201             self.get_name_and_aliases().any(|name| name == value)
 202         }
 203     }
 204 }
 205
 206 impl<'help> From<&'help str> for PossibleValue<'help> {
 207     fn from(s: &'help str) -> Self {
 208         Self::new(s)
 209     }
 210 }
 211
 212 impl<'help> From<&'help &'help str> for PossibleValue<'help> {
 213     fn from(s: &'help &'help str) -> Self {
 214         Self::new(s)
 215     }
 216 }