diff options
Diffstat (limited to 'vendor/clap_builder/src')
56 files changed, 27973 insertions, 0 deletions
diff --git a/vendor/clap_builder/src/builder/action.rs b/vendor/clap_builder/src/builder/action.rs new file mode 100644 index 0000000..2def801 --- /dev/null +++ b/vendor/clap_builder/src/builder/action.rs @@ -0,0 +1,418 @@ +#[cfg(debug_assertions)] +use crate::util::AnyValueId; + +/// Behavior of arguments when they are encountered while parsing +/// +/// # Examples +/// +/// ```rust +/// # #[cfg(feature = "help")] { +/// # use clap_builder as clap; +/// # use clap::Command; +/// # use clap::Arg; +/// let cmd = Command::new("mycmd") +/// .arg( +/// Arg::new("special-help") +/// .short('?') +/// .action(clap::ArgAction::Help) +/// ); +/// +/// // Existing help still exists +/// let err = cmd.clone().try_get_matches_from(["mycmd", "-h"]).unwrap_err(); +/// assert_eq!(err.kind(), clap::error::ErrorKind::DisplayHelp); +/// +/// // New help available +/// let err = cmd.try_get_matches_from(["mycmd", "-?"]).unwrap_err(); +/// assert_eq!(err.kind(), clap::error::ErrorKind::DisplayHelp); +/// # } +/// ``` +#[derive(Clone, Debug)] +#[non_exhaustive] +#[allow(missing_copy_implementations)] // In the future, we may accept `Box<dyn ...>` +pub enum ArgAction { + /// When encountered, store the associated value(s) in [`ArgMatches`][crate::ArgMatches] + /// + /// **NOTE:** If the argument has previously been seen, it will result in a + /// [`ArgumentConflict`][crate::error::ErrorKind::ArgumentConflict] unless + /// [`Command::args_override_self(true)`][crate::Command::args_override_self] is set. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::Command; + /// # use clap::Arg; + /// let cmd = Command::new("mycmd") + /// .arg( + /// Arg::new("flag") + /// .long("flag") + /// .action(clap::ArgAction::Set) + /// ); + /// + /// let matches = cmd.try_get_matches_from(["mycmd", "--flag", "value"]).unwrap(); + /// assert!(matches.contains_id("flag")); + /// assert_eq!( + /// matches.get_many::<String>("flag").unwrap_or_default().map(|v| v.as_str()).collect::<Vec<_>>(), + /// vec!["value"] + /// ); + /// ``` + Set, + /// When encountered, store the associated value(s) in [`ArgMatches`][crate::ArgMatches] + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::Command; + /// # use clap::Arg; + /// let cmd = Command::new("mycmd") + /// .arg( + /// Arg::new("flag") + /// .long("flag") + /// .action(clap::ArgAction::Append) + /// ); + /// + /// let matches = cmd.try_get_matches_from(["mycmd", "--flag", "value1", "--flag", "value2"]).unwrap(); + /// assert!(matches.contains_id("flag")); + /// assert_eq!( + /// matches.get_many::<String>("flag").unwrap_or_default().map(|v| v.as_str()).collect::<Vec<_>>(), + /// vec!["value1", "value2"] + /// ); + /// ``` + Append, + /// When encountered, act as if `"true"` was encountered on the command-line + /// + /// If no [`default_value`][super::Arg::default_value] is set, it will be `false`. + /// + /// No value is allowed. To optionally accept a value, see + /// [`Arg::default_missing_value`][super::Arg::default_missing_value] + /// + /// **NOTE:** If the argument has previously been seen, it will result in a + /// [`ArgumentConflict`][crate::error::ErrorKind::ArgumentConflict] unless + /// [`Command::args_override_self(true)`][crate::Command::args_override_self] is set. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::Command; + /// # use clap::Arg; + /// let cmd = Command::new("mycmd") + /// .arg( + /// Arg::new("flag") + /// .long("flag") + /// .action(clap::ArgAction::SetTrue) + /// ); + /// + /// let matches = cmd.clone().try_get_matches_from(["mycmd", "--flag"]).unwrap(); + /// assert!(matches.contains_id("flag")); + /// assert_eq!( + /// matches.get_flag("flag"), + /// true + /// ); + /// + /// let matches = cmd.try_get_matches_from(["mycmd"]).unwrap(); + /// assert!(matches.contains_id("flag")); + /// assert_eq!( + /// matches.get_flag("flag"), + /// false + /// ); + /// ``` + /// + /// You can use [`TypedValueParser::map`][crate::builder::TypedValueParser::map] to have the + /// flag control an application-specific type: + /// ```rust + /// # use clap_builder as clap; + /// # use clap::Command; + /// # use clap::Arg; + /// # use clap::builder::TypedValueParser as _; + /// # use clap::builder::BoolishValueParser; + /// let cmd = Command::new("mycmd") + /// .arg( + /// Arg::new("flag") + /// .long("flag") + /// .action(clap::ArgAction::SetTrue) + /// .value_parser( + /// BoolishValueParser::new() + /// .map(|b| -> usize { + /// if b { 10 } else { 5 } + /// }) + /// ) + /// ); + /// + /// let matches = cmd.clone().try_get_matches_from(["mycmd", "--flag"]).unwrap(); + /// assert!(matches.contains_id("flag")); + /// assert_eq!( + /// matches.get_one::<usize>("flag").copied(), + /// Some(10) + /// ); + /// + /// let matches = cmd.try_get_matches_from(["mycmd"]).unwrap(); + /// assert!(matches.contains_id("flag")); + /// assert_eq!( + /// matches.get_one::<usize>("flag").copied(), + /// Some(5) + /// ); + /// ``` + SetTrue, + /// When encountered, act as if `"false"` was encountered on the command-line + /// + /// If no [`default_value`][super::Arg::default_value] is set, it will be `true`. + /// + /// No value is allowed. To optionally accept a value, see + /// [`Arg::default_missing_value`][super::Arg::default_missing_value] + /// + /// **NOTE:** If the argument has previously been seen, it will result in a + /// [`ArgumentConflict`][crate::error::ErrorKind::ArgumentConflict] unless + /// [`Command::args_override_self(true)`][crate::Command::args_override_self] is set. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::Command; + /// # use clap::Arg; + /// let cmd = Command::new("mycmd") + /// .arg( + /// Arg::new("flag") + /// .long("flag") + /// .action(clap::ArgAction::SetFalse) + /// ); + /// + /// let matches = cmd.clone().try_get_matches_from(["mycmd", "--flag"]).unwrap(); + /// assert!(matches.contains_id("flag")); + /// assert_eq!( + /// matches.get_flag("flag"), + /// false + /// ); + /// + /// let matches = cmd.try_get_matches_from(["mycmd"]).unwrap(); + /// assert!(matches.contains_id("flag")); + /// assert_eq!( + /// matches.get_flag("flag"), + /// true + /// ); + /// ``` + SetFalse, + /// When encountered, increment a `u8` counter + /// + /// If no [`default_value`][super::Arg::default_value] is set, it will be `0`. + /// + /// No value is allowed. To optionally accept a value, see + /// [`Arg::default_missing_value`][super::Arg::default_missing_value] + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::Command; + /// # use clap::Arg; + /// let cmd = Command::new("mycmd") + /// .arg( + /// Arg::new("flag") + /// .long("flag") + /// .action(clap::ArgAction::Count) + /// ); + /// + /// let matches = cmd.clone().try_get_matches_from(["mycmd", "--flag", "--flag"]).unwrap(); + /// assert!(matches.contains_id("flag")); + /// assert_eq!( + /// matches.get_count("flag"), + /// 2 + /// ); + /// + /// let matches = cmd.try_get_matches_from(["mycmd"]).unwrap(); + /// assert!(matches.contains_id("flag")); + /// assert_eq!( + /// matches.get_count("flag"), + /// 0 + /// ); + /// ``` + Count, + /// When encountered, display [`Command::print_help`][super::Command::print_help] + /// + /// Depending on the flag, [`Command::print_long_help`][super::Command::print_long_help] may be shown + /// + /// # Examples + /// + /// ```rust + /// # #[cfg(feature = "help")] { + /// # use clap_builder as clap; + /// # use clap::Command; + /// # use clap::Arg; + /// let cmd = Command::new("mycmd") + /// .arg( + /// Arg::new("special-help") + /// .short('?') + /// .action(clap::ArgAction::Help) + /// ); + /// + /// // Existing help still exists + /// let err = cmd.clone().try_get_matches_from(["mycmd", "-h"]).unwrap_err(); + /// assert_eq!(err.kind(), clap::error::ErrorKind::DisplayHelp); + /// + /// // New help available + /// let err = cmd.try_get_matches_from(["mycmd", "-?"]).unwrap_err(); + /// assert_eq!(err.kind(), clap::error::ErrorKind::DisplayHelp); + /// # } + /// ``` + Help, + /// When encountered, display [`Command::print_help`][super::Command::print_help] + /// + /// # Examples + /// + /// ```rust + /// # #[cfg(feature = "help")] { + /// # use clap_builder as clap; + /// # use clap::Command; + /// # use clap::Arg; + /// let cmd = Command::new("mycmd") + /// .arg( + /// Arg::new("special-help") + /// .short('?') + /// .action(clap::ArgAction::HelpShort) + /// ); + /// + /// // Existing help still exists + /// let err = cmd.clone().try_get_matches_from(["mycmd", "-h"]).unwrap_err(); + /// assert_eq!(err.kind(), clap::error::ErrorKind::DisplayHelp); + /// + /// // New help available + /// let err = cmd.try_get_matches_from(["mycmd", "-?"]).unwrap_err(); + /// assert_eq!(err.kind(), clap::error::ErrorKind::DisplayHelp); + /// # } + /// ``` + HelpShort, + /// When encountered, display [`Command::print_long_help`][super::Command::print_long_help] + /// + /// # Examples + /// + /// ```rust + /// # #[cfg(feature = "help")] { + /// # use clap_builder as clap; + /// # use clap::Command; + /// # use clap::Arg; + /// let cmd = Command::new("mycmd") + /// .arg( + /// Arg::new("special-help") + /// .short('?') + /// .action(clap::ArgAction::HelpLong) + /// ); + /// + /// // Existing help still exists + /// let err = cmd.clone().try_get_matches_from(["mycmd", "-h"]).unwrap_err(); + /// assert_eq!(err.kind(), clap::error::ErrorKind::DisplayHelp); + /// + /// // New help available + /// let err = cmd.try_get_matches_from(["mycmd", "-?"]).unwrap_err(); + /// assert_eq!(err.kind(), clap::error::ErrorKind::DisplayHelp); + /// # } + /// ``` + HelpLong, + /// When encountered, display [`Command::version`][super::Command::version] + /// + /// Depending on the flag, [`Command::long_version`][super::Command::long_version] may be shown + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::Command; + /// # use clap::Arg; + /// let cmd = Command::new("mycmd") + /// .version("1.0.0") + /// .arg( + /// Arg::new("special-version") + /// .long("special-version") + /// .action(clap::ArgAction::Version) + /// ); + /// + /// // Existing help still exists + /// let err = cmd.clone().try_get_matches_from(["mycmd", "--version"]).unwrap_err(); + /// assert_eq!(err.kind(), clap::error::ErrorKind::DisplayVersion); + /// + /// // New help available + /// let err = cmd.try_get_matches_from(["mycmd", "--special-version"]).unwrap_err(); + /// assert_eq!(err.kind(), clap::error::ErrorKind::DisplayVersion); + /// ``` + Version, +} + +impl ArgAction { + /// Returns whether this action accepts values on the command-line + /// + /// [`default_values`][super::Arg::default_values] and [`env`][super::Arg::env] may still be + /// processed. + pub fn takes_values(&self) -> bool { + match self { + Self::Set => true, + Self::Append => true, + Self::SetTrue => false, + Self::SetFalse => false, + Self::Count => false, + Self::Help => false, + Self::HelpShort => false, + Self::HelpLong => false, + Self::Version => false, + } + } + + pub(crate) fn default_value(&self) -> Option<&'static std::ffi::OsStr> { + match self { + Self::Set => None, + Self::Append => None, + Self::SetTrue => Some(std::ffi::OsStr::new("false")), + Self::SetFalse => Some(std::ffi::OsStr::new("true")), + Self::Count => Some(std::ffi::OsStr::new("0")), + Self::Help => None, + Self::HelpShort => None, + Self::HelpLong => None, + Self::Version => None, + } + } + + pub(crate) fn default_missing_value(&self) -> Option<&'static std::ffi::OsStr> { + match self { + Self::Set => None, + Self::Append => None, + Self::SetTrue => Some(std::ffi::OsStr::new("true")), + Self::SetFalse => Some(std::ffi::OsStr::new("false")), + Self::Count => None, + Self::Help => None, + Self::HelpShort => None, + Self::HelpLong => None, + Self::Version => None, + } + } + + pub(crate) fn default_value_parser(&self) -> Option<super::ValueParser> { + match self { + Self::Set => None, + Self::Append => None, + Self::SetTrue => Some(super::ValueParser::bool()), + Self::SetFalse => Some(super::ValueParser::bool()), + Self::Count => Some(crate::value_parser!(u8).into()), + Self::Help => None, + Self::HelpShort => None, + Self::HelpLong => None, + Self::Version => None, + } + } + + #[cfg(debug_assertions)] + pub(crate) fn value_type_id(&self) -> Option<AnyValueId> { + match self { + Self::Set => None, + Self::Append => None, + Self::SetTrue => None, + Self::SetFalse => None, + Self::Count => Some(AnyValueId::of::<CountType>()), + Self::Help => None, + Self::HelpShort => None, + Self::HelpLong => None, + Self::Version => None, + } + } +} + +pub(crate) type CountType = u8; diff --git a/vendor/clap_builder/src/builder/app_settings.rs b/vendor/clap_builder/src/builder/app_settings.rs new file mode 100644 index 0000000..f9a87da --- /dev/null +++ b/vendor/clap_builder/src/builder/app_settings.rs @@ -0,0 +1,84 @@ +#[allow(unused)] +use crate::Arg; +#[allow(unused)] +use crate::Command; + +#[derive(Default, Copy, Clone, Debug, PartialEq, Eq)] +pub(crate) struct AppFlags(u32); + +impl AppFlags { + pub(crate) fn set(&mut self, setting: AppSettings) { + self.0 |= setting.bit(); + } + + pub(crate) fn unset(&mut self, setting: AppSettings) { + self.0 &= !setting.bit(); + } + + pub(crate) fn is_set(&self, setting: AppSettings) -> bool { + self.0 & setting.bit() != 0 + } + + pub(crate) fn insert(&mut self, other: Self) { + self.0 |= other.0; + } +} + +impl std::ops::BitOr for AppFlags { + type Output = Self; + + fn bitor(mut self, rhs: Self) -> Self::Output { + self.insert(rhs); + self + } +} + +/// Application level settings, which affect how [`Command`] operates +/// +/// **NOTE:** When these settings are used, they apply only to current command, and are *not* +/// propagated down or up through child or parent subcommands +/// +/// [`Command`]: crate::Command +#[derive(Debug, PartialEq, Copy, Clone)] +#[repr(u8)] +pub(crate) enum AppSettings { + IgnoreErrors, + AllowHyphenValues, + AllowNegativeNumbers, + AllArgsOverrideSelf, + AllowMissingPositional, + TrailingVarArg, + DontDelimitTrailingValues, + InferLongArgs, + InferSubcommands, + SubcommandRequired, + AllowExternalSubcommands, + Multicall, + SubcommandsNegateReqs, + ArgsNegateSubcommands, + SubcommandPrecedenceOverArg, + FlattenHelp, + ArgRequiredElseHelp, + NextLineHelp, + DisableColoredHelp, + DisableHelpFlag, + DisableHelpSubcommand, + DisableVersionFlag, + PropagateVersion, + Hidden, + HidePossibleValues, + HelpExpected, + NoBinaryName, + #[allow(dead_code)] + ColorAuto, + ColorAlways, + ColorNever, + Built, + BinNameBuilt, +} + +impl AppSettings { + fn bit(self) -> u32 { + 1 << (self as u8) + } +} diff --git a/vendor/clap_builder/src/builder/arg.rs b/vendor/clap_builder/src/builder/arg.rs new file mode 100644 index 0000000..f83b464 --- /dev/null +++ b/vendor/clap_builder/src/builder/arg.rs @@ -0,0 +1,4800 @@ +// Std +#[cfg(feature = "env")] +use std::env; +#[cfg(feature = "env")] +use std::ffi::OsString; +use std::{ + cmp::{Ord, Ordering}, + fmt::{self, Display, Formatter}, + str, +}; + +// Internal +use super::{ArgFlags, ArgSettings}; +use crate::builder::ArgPredicate; +use crate::builder::IntoResettable; +use crate::builder::OsStr; +use crate::builder::PossibleValue; +use crate::builder::Str; +use crate::builder::StyledStr; +use crate::builder::Styles; +use crate::builder::ValueRange; +use crate::util::AnyValueId; +use crate::ArgAction; +use crate::Id; +use crate::ValueHint; +use crate::INTERNAL_ERROR_MSG; + +/// The abstract representation of a command line argument. Used to set all the options and +/// relationships that define a valid argument for the program. +/// +/// There are two methods for constructing [`Arg`]s, using the builder pattern and setting options +/// manually, or using a usage string which is far less verbose but has fewer options. You can also +/// use a combination of the two methods to achieve the best of both worlds. +/// +/// - [Basic API][crate::Arg#basic-api] +/// - [Value Handling][crate::Arg#value-handling] +/// - [Help][crate::Arg#help-1] +/// - [Advanced Argument Relations][crate::Arg#advanced-argument-relations] +/// - [Reflection][crate::Arg#reflection] +/// +/// # Examples +/// +/// ```rust +/// # use clap_builder as clap; +/// # use clap::{Arg, arg, ArgAction}; +/// // Using the traditional builder pattern and setting each option manually +/// let cfg = Arg::new("config") +/// .short('c') +/// .long("config") +/// .action(ArgAction::Set) +/// .value_name("FILE") +/// .help("Provides a config file to myprog"); +/// // Using a usage string (setting a similar argument to the one above) +/// let input = arg!(-i --input <FILE> "Provides an input file to the program"); +/// ``` +#[derive(Default, Clone)] +pub struct Arg { + pub(crate) id: Id, + pub(crate) help: Option<StyledStr>, + pub(crate) long_help: Option<StyledStr>, + pub(crate) action: Option<ArgAction>, + pub(crate) value_parser: Option<super::ValueParser>, + pub(crate) blacklist: Vec<Id>, + pub(crate) settings: ArgFlags, + pub(crate) overrides: Vec<Id>, + pub(crate) groups: Vec<Id>, + pub(crate) requires: Vec<(ArgPredicate, Id)>, + pub(crate) r_ifs: Vec<(Id, OsStr)>, + pub(crate) r_ifs_all: Vec<(Id, OsStr)>, + pub(crate) r_unless: Vec<Id>, + pub(crate) r_unless_all: Vec<Id>, + pub(crate) short: Option<char>, + pub(crate) long: Option<Str>, + pub(crate) aliases: Vec<(Str, bool)>, // (name, visible) + pub(crate) short_aliases: Vec<(char, bool)>, // (name, visible) + pub(crate) disp_ord: Option<usize>, + pub(crate) val_names: Vec<Str>, + pub(crate) num_vals: Option<ValueRange>, + pub(crate) val_delim: Option<char>, + pub(crate) default_vals: Vec<OsStr>, + pub(crate) default_vals_ifs: Vec<(Id, ArgPredicate, Option<OsStr>)>, + pub(crate) default_missing_vals: Vec<OsStr>, + #[cfg(feature = "env")] + pub(crate) env: Option<(OsStr, Option<OsString>)>, + pub(crate) terminator: Option<Str>, + pub(crate) index: Option<usize>, + pub(crate) help_heading: Option<Option<Str>>, + pub(crate) value_hint: Option<ValueHint>, +} + +/// # Basic API +impl Arg { + /// Create a new [`Arg`] with a unique name. + /// + /// The name is used to check whether or not the argument was used at + /// runtime, get values, set relationships with other args, etc.. + /// + /// **NOTE:** In the case of arguments that take values (i.e. [`Arg::action(ArgAction::Set)`]) + /// and positional arguments (i.e. those without a preceding `-` or `--`) the name will also + /// be displayed when the user prints the usage/help information of the program. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg}; + /// Arg::new("config") + /// # ; + /// ``` + /// [`Arg::action(ArgAction::Set)`]: Arg::action() + pub fn new(id: impl Into<Id>) -> Self { + Arg::default().id(id) + } + + /// Set the identifier used for referencing this argument in the clap API. + /// + /// See [`Arg::new`] for more details. + #[must_use] + pub fn id(mut self, id: impl Into<Id>) -> Self { + self.id = id.into(); + self + } + + /// Sets the short version of the argument without the preceding `-`. + /// + /// By default `V` and `h` are used by the auto-generated `version` and `help` arguments, + /// respectively. You will need to disable the auto-generated flags + /// ([`disable_help_flag`][crate::Command::disable_help_flag], + /// [`disable_version_flag`][crate::Command::disable_version_flag]) and define your own. + /// + /// # Examples + /// + /// When calling `short`, use a single valid UTF-8 character which will allow using the + /// argument via a single hyphen (`-`) such as `-c`: + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// let m = Command::new("prog") + /// .arg(Arg::new("config") + /// .short('c') + /// .action(ArgAction::Set)) + /// .get_matches_from(vec![ + /// "prog", "-c", "file.toml" + /// ]); + /// + /// assert_eq!(m.get_one::<String>("config").map(String::as_str), Some("file.toml")); + /// ``` + /// + /// To use `-h` for your own flag and still have help: + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// let m = Command::new("prog") + /// .disable_help_flag(true) + /// .arg(Arg::new("host") + /// .short('h') + /// .long("host")) + /// .arg(Arg::new("help") + /// .long("help") + /// .global(true) + /// .action(ArgAction::Help)) + /// .get_matches_from(vec![ + /// "prog", "-h", "wikipedia.org" + /// ]); + /// + /// assert_eq!(m.get_one::<String>("host").map(String::as_str), Some("wikipedia.org")); + /// ``` + #[inline] + #[must_use] + pub fn short(mut self, s: impl IntoResettable<char>) -> Self { + if let Some(s) = s.into_resettable().into_option() { + debug_assert!(s != '-', "short option name cannot be `-`"); + self.short = Some(s); + } else { + self.short = None; + } + self + } + + /// Sets the long version of the argument without the preceding `--`. + /// + /// By default `version` and `help` are used by the auto-generated `version` and `help` + /// arguments, respectively. You may use the word `version` or `help` for the long form of your + /// own arguments, in which case `clap` simply will not assign those to the auto-generated + /// `version` or `help` arguments. + /// + /// **NOTE:** Any leading `-` characters will be stripped + /// + /// # Examples + /// + /// To set `long` use a word containing valid UTF-8. If you supply a double leading + /// `--` such as `--config` they will be stripped. Hyphens in the middle of the word, however, + /// will *not* be stripped (i.e. `config-file` is allowed). + /// + /// Setting `long` allows using the argument via a double hyphen (`--`) such as `--config` + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// let m = Command::new("prog") + /// .arg(Arg::new("cfg") + /// .long("config") + /// .action(ArgAction::Set)) + /// .get_matches_from(vec![ + /// "prog", "--config", "file.toml" + /// ]); + /// + /// assert_eq!(m.get_one::<String>("cfg").map(String::as_str), Some("file.toml")); + /// ``` + #[inline] + #[must_use] + pub fn long(mut self, l: impl IntoResettable<Str>) -> Self { + self.long = l.into_resettable().into_option(); + self + } + + /// Add an alias, which functions as a hidden long flag. + /// + /// This is more efficient, and easier than creating multiple hidden arguments as one only + /// needs to check for the existence of this command, and not all variants. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// let m = Command::new("prog") + /// .arg(Arg::new("test") + /// .long("test") + /// .alias("alias") + /// .action(ArgAction::Set)) + /// .get_matches_from(vec![ + /// "prog", "--alias", "cool" + /// ]); + /// assert_eq!(m.get_one::<String>("test").unwrap(), "cool"); + /// ``` + #[must_use] + pub fn alias(mut self, name: impl IntoResettable<Str>) -> Self { + if let Some(name) = name.into_resettable().into_option() { + self.aliases.push((name, false)); + } else { + self.aliases.clear(); + } + self + } + + /// Add an alias, which functions as a hidden short flag. + /// + /// This is more efficient, and easier than creating multiple hidden arguments as one only + /// needs to check for the existence of this command, and not all variants. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// let m = Command::new("prog") + /// .arg(Arg::new("test") + /// .short('t') + /// .short_alias('e') + /// .action(ArgAction::Set)) + /// .get_matches_from(vec![ + /// "prog", "-e", "cool" + /// ]); + /// assert_eq!(m.get_one::<String>("test").unwrap(), "cool"); + /// ``` + #[must_use] + pub fn short_alias(mut self, name: impl IntoResettable<char>) -> Self { + if let Some(name) = name.into_resettable().into_option() { + debug_assert!(name != '-', "short alias name cannot be `-`"); + self.short_aliases.push((name, false)); + } else { + self.short_aliases.clear(); + } + self + } + + /// Add aliases, which function as hidden long flags. + /// + /// This is more efficient, and easier than creating multiple hidden subcommands as one only + /// needs to check for the existence of this command, and not all variants. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// let m = Command::new("prog") + /// .arg(Arg::new("test") + /// .long("test") + /// .aliases(["do-stuff", "do-tests", "tests"]) + /// .action(ArgAction::SetTrue) + /// .help("the file to add") + /// .required(false)) + /// .get_matches_from(vec![ + /// "prog", "--do-tests" + /// ]); + /// assert_eq!(m.get_flag("test"), true); + /// ``` + #[must_use] + pub fn aliases(mut self, names: impl IntoIterator<Item = impl Into<Str>>) -> Self { + self.aliases + .extend(names.into_iter().map(|x| (x.into(), false))); + self + } + + /// Add aliases, which functions as a hidden short flag. + /// + /// This is more efficient, and easier than creating multiple hidden subcommands as one only + /// needs to check for the existence of this command, and not all variants. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// let m = Command::new("prog") + /// .arg(Arg::new("test") + /// .short('t') + /// .short_aliases(['e', 's']) + /// .action(ArgAction::SetTrue) + /// .help("the file to add") + /// .required(false)) + /// .get_matches_from(vec![ + /// "prog", "-s" + /// ]); + /// assert_eq!(m.get_flag("test"), true); + /// ``` + #[must_use] + pub fn short_aliases(mut self, names: impl IntoIterator<Item = char>) -> Self { + for s in names { + debug_assert!(s != '-', "short alias name cannot be `-`"); + self.short_aliases.push((s, false)); + } + self + } + + /// Add an alias, which functions as a visible long flag. + /// + /// Like [`Arg::alias`], except that they are visible inside the help message. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// let m = Command::new("prog") + /// .arg(Arg::new("test") + /// .visible_alias("something-awesome") + /// .long("test") + /// .action(ArgAction::Set)) + /// .get_matches_from(vec![ + /// "prog", "--something-awesome", "coffee" + /// ]); + /// assert_eq!(m.get_one::<String>("test").unwrap(), "coffee"); + /// ``` + /// [`Command::alias`]: Arg::alias() + #[must_use] + pub fn visible_alias(mut self, name: impl IntoResettable<Str>) -> Self { + if let Some(name) = name.into_resettable().into_option() { + self.aliases.push((name, true)); + } else { + self.aliases.clear(); + } + self + } + + /// Add an alias, which functions as a visible short flag. + /// + /// Like [`Arg::short_alias`], except that they are visible inside the help message. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// let m = Command::new("prog") + /// .arg(Arg::new("test") + /// .long("test") + /// .visible_short_alias('t') + /// .action(ArgAction::Set)) + /// .get_matches_from(vec![ + /// "prog", "-t", "coffee" + /// ]); + /// assert_eq!(m.get_one::<String>("test").unwrap(), "coffee"); + /// ``` + #[must_use] + pub fn visible_short_alias(mut self, name: impl IntoResettable<char>) -> Self { + if let Some(name) = name.into_resettable().into_option() { + debug_assert!(name != '-', "short alias name cannot be `-`"); + self.short_aliases.push((name, true)); + } else { + self.short_aliases.clear(); + } + self + } + + /// Add aliases, which function as visible long flags. + /// + /// Like [`Arg::aliases`], except that they are visible inside the help message. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// let m = Command::new("prog") + /// .arg(Arg::new("test") + /// .long("test") + /// .action(ArgAction::SetTrue) + /// .visible_aliases(["something", "awesome", "cool"])) + /// .get_matches_from(vec![ + /// "prog", "--awesome" + /// ]); + /// assert_eq!(m.get_flag("test"), true); + /// ``` + /// [`Command::aliases`]: Arg::aliases() + #[must_use] + pub fn visible_aliases(mut self, names: impl IntoIterator<Item = impl Into<Str>>) -> Self { + self.aliases + .extend(names.into_iter().map(|n| (n.into(), true))); + self + } + + /// Add aliases, which function as visible short flags. + /// + /// Like [`Arg::short_aliases`], except that they are visible inside the help message. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// let m = Command::new("prog") + /// .arg(Arg::new("test") + /// .long("test") + /// .action(ArgAction::SetTrue) + /// .visible_short_aliases(['t', 'e'])) + /// .get_matches_from(vec![ + /// "prog", "-t" + /// ]); + /// assert_eq!(m.get_flag("test"), true); + /// ``` + #[must_use] + pub fn visible_short_aliases(mut self, names: impl IntoIterator<Item = char>) -> Self { + for n in names { + debug_assert!(n != '-', "short alias name cannot be `-`"); + self.short_aliases.push((n, true)); + } + self + } + + /// Specifies the index of a positional argument **starting at** 1. + /// + /// **NOTE:** The index refers to position according to **other positional argument**. It does + /// not define position in the argument list as a whole. + /// + /// **NOTE:** You can optionally leave off the `index` method, and the index will be + /// assigned in order of evaluation. Utilizing the `index` method allows for setting + /// indexes out of order + /// + /// **NOTE:** This is only meant to be used for positional arguments and shouldn't to be used + /// with [`Arg::short`] or [`Arg::long`]. + /// + /// **NOTE:** When utilized with [`Arg::num_args(1..)`], only the **last** positional argument + /// may be defined as having a variable number of arguments (i.e. with the highest index) + /// + /// # Panics + /// + /// [`Command`] will [`panic!`] if indexes are skipped (such as defining `index(1)` and `index(3)` + /// but not `index(2)`, or a positional argument is defined as multiple and is not the highest + /// index (debug builds) + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg}; + /// Arg::new("config") + /// .index(1) + /// # ; + /// ``` + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// let m = Command::new("prog") + /// .arg(Arg::new("mode") + /// .index(1)) + /// .arg(Arg::new("debug") + /// .long("debug") + /// .action(ArgAction::SetTrue)) + /// .get_matches_from(vec![ + /// "prog", "--debug", "fast" + /// ]); + /// + /// assert!(m.contains_id("mode")); + /// assert_eq!(m.get_one::<String>("mode").unwrap(), "fast"); // notice index(1) means "first positional" + /// // *not* first argument + /// ``` + /// [`Arg::short`]: Arg::short() + /// [`Arg::long`]: Arg::long() + /// [`Arg::num_args(true)`]: Arg::num_args() + /// [`Command`]: crate::Command + #[inline] + #[must_use] + pub fn index(mut self, idx: impl IntoResettable<usize>) -> Self { + self.index = idx.into_resettable().into_option(); + self + } + + /// This is a "VarArg" and everything that follows should be captured by it, as if the user had + /// used a `--`. + /// + /// **NOTE:** To start the trailing "VarArg" on unknown flags (and not just a positional + /// value), set [`allow_hyphen_values`][Arg::allow_hyphen_values]. Either way, users still + /// have the option to explicitly escape ambiguous arguments with `--`. + /// + /// **NOTE:** [`Arg::value_delimiter`] still applies if set. + /// + /// **NOTE:** Setting this requires [`Arg::num_args(..)`]. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, arg}; + /// let m = Command::new("myprog") + /// .arg(arg!(<cmd> ... "commands to run").trailing_var_arg(true)) + /// .get_matches_from(vec!["myprog", "arg1", "-r", "val1"]); + /// + /// let trail: Vec<_> = m.get_many::<String>("cmd").unwrap().collect(); + /// assert_eq!(trail, ["arg1", "-r", "val1"]); + /// ``` + /// [`Arg::num_args(..)`]: crate::Arg::num_args() + pub fn trailing_var_arg(self, yes: bool) -> Self { + if yes { + self.setting(ArgSettings::TrailingVarArg) + } else { + self.unset_setting(ArgSettings::TrailingVarArg) + } + } + + /// This arg is the last, or final, positional argument (i.e. has the highest + /// index) and is *only* able to be accessed via the `--` syntax (i.e. `$ prog args -- + /// last_arg`). + /// + /// Even, if no other arguments are left to parse, if the user omits the `--` syntax + /// they will receive an [`UnknownArgument`] error. Setting an argument to `.last(true)` also + /// allows one to access this arg early using the `--` syntax. Accessing an arg early, even with + /// the `--` syntax is otherwise not possible. + /// + /// **NOTE:** This will change the usage string to look like `$ prog [OPTIONS] [-- <ARG>]` if + /// `ARG` is marked as `.last(true)`. + /// + /// **NOTE:** This setting will imply [`crate::Command::dont_collapse_args_in_usage`] because failing + /// to set this can make the usage string very confusing. + /// + /// **NOTE**: This setting only applies to positional arguments, and has no effect on OPTIONS + /// + /// **NOTE:** Setting this requires [taking values][Arg::num_args] + /// + /// **CAUTION:** Using this setting *and* having child subcommands is not + /// recommended with the exception of *also* using + /// [`crate::Command::args_conflicts_with_subcommands`] + /// (or [`crate::Command::subcommand_negates_reqs`] if the argument marked `Last` is also + /// marked [`Arg::required`]) + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Arg, ArgAction}; + /// Arg::new("args") + /// .action(ArgAction::Set) + /// .last(true) + /// # ; + /// ``` + /// + /// Setting `last` ensures the arg has the highest [index] of all positional args + /// and requires that the `--` syntax be used to access it early. + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// let res = Command::new("prog") + /// .arg(Arg::new("first")) + /// .arg(Arg::new("second")) + /// .arg(Arg::new("third") + /// .action(ArgAction::Set) + /// .last(true)) + /// .try_get_matches_from(vec![ + /// "prog", "one", "--", "three" + /// ]); + /// + /// assert!(res.is_ok()); + /// let m = res.unwrap(); + /// assert_eq!(m.get_one::<String>("third").unwrap(), "three"); + /// assert_eq!(m.get_one::<String>("second"), None); + /// ``` + /// + /// Even if the positional argument marked `Last` is the only argument left to parse, + /// failing to use the `--` syntax results in an error. + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, error::ErrorKind, ArgAction}; + /// let res = Command::new("prog") + /// .arg(Arg::new("first")) + /// .arg(Arg::new("second")) + /// .arg(Arg::new("third") + /// .action(ArgAction::Set) + /// .last(true)) + /// .try_get_matches_from(vec![ + /// "prog", "one", "two", "three" + /// ]); + /// + /// assert!(res.is_err()); + /// assert_eq!(res.unwrap_err().kind(), ErrorKind::UnknownArgument); + /// ``` + /// [index]: Arg::index() + /// [`UnknownArgument`]: crate::error::ErrorKind::UnknownArgument + #[inline] + #[must_use] + pub fn last(self, yes: bool) -> Self { + if yes { + self.setting(ArgSettings::Last) + } else { + self.unset_setting(ArgSettings::Last) + } + } + + /// Specifies that the argument must be present. + /// + /// Required by default means it is required, when no other conflicting rules or overrides have + /// been evaluated. Conflicting rules take precedence over being required. + /// + /// **Pro tip:** Flags (i.e. not positional, or arguments that take values) shouldn't be + /// required by default. This is because if a flag were to be required, it should simply be + /// implied. No additional information is required from user. Flags by their very nature are + /// simply boolean on/off switches. The only time a user *should* be required to use a flag + /// is if the operation is destructive in nature, and the user is essentially proving to you, + /// "Yes, I know what I'm doing." + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::Arg; + /// Arg::new("config") + /// .required(true) + /// # ; + /// ``` + /// + /// Setting required requires that the argument be used at runtime. + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// let res = Command::new("prog") + /// .arg(Arg::new("cfg") + /// .required(true) + /// .action(ArgAction::Set) + /// .long("config")) + /// .try_get_matches_from(vec![ + /// "prog", "--config", "file.conf", + /// ]); + /// + /// assert!(res.is_ok()); + /// ``` + /// + /// Setting required and then *not* supplying that argument at runtime is an error. + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, error::ErrorKind, ArgAction}; + /// let res = Command::new("prog") + /// .arg(Arg::new("cfg") + /// .required(true) + /// .action(ArgAction::Set) + /// .long("config")) + /// .try_get_matches_from(vec![ + /// "prog" + /// ]); + /// + /// assert!(res.is_err()); + /// assert_eq!(res.unwrap_err().kind(), ErrorKind::MissingRequiredArgument); + /// ``` + #[inline] + #[must_use] + pub fn required(self, yes: bool) -> Self { + if yes { + self.setting(ArgSettings::Required) + } else { + self.unset_setting(ArgSettings::Required) + } + } + + /// Sets an argument that is required when this one is present + /// + /// i.e. when using this argument, the following argument *must* be present. + /// + /// **NOTE:** [Conflicting] rules and [override] rules take precedence over being required + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::Arg; + /// Arg::new("config") + /// .requires("input") + /// # ; + /// ``` + /// + /// Setting [`Arg::requires(name)`] requires that the argument be used at runtime if the + /// defining argument is used. If the defining argument isn't used, the other argument isn't + /// required + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// let res = Command::new("prog") + /// .arg(Arg::new("cfg") + /// .action(ArgAction::Set) + /// .requires("input") + /// .long("config")) + /// .arg(Arg::new("input")) + /// .try_get_matches_from(vec![ + /// "prog" + /// ]); + /// + /// assert!(res.is_ok()); // We didn't use cfg, so input wasn't required + /// ``` + /// + /// Setting [`Arg::requires(name)`] and *not* supplying that argument is an error. + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, error::ErrorKind, ArgAction}; + /// let res = Command::new("prog") + /// .arg(Arg::new("cfg") + /// .action(ArgAction::Set) + /// .requires("input") + /// .long("config")) + /// .arg(Arg::new("input")) + /// .try_get_matches_from(vec![ + /// "prog", "--config", "file.conf" + /// ]); + /// + /// assert!(res.is_err()); + /// assert_eq!(res.unwrap_err().kind(), ErrorKind::MissingRequiredArgument); + /// ``` + /// [`Arg::requires(name)`]: Arg::requires() + /// [Conflicting]: Arg::conflicts_with() + /// [override]: Arg::overrides_with() + #[must_use] + pub fn requires(mut self, arg_id: impl IntoResettable<Id>) -> Self { + if let Some(arg_id) = arg_id.into_resettable().into_option() { + self.requires.push((ArgPredicate::IsPresent, arg_id)); + } else { + self.requires.clear(); + } + self + } + + /// This argument must be passed alone; it conflicts with all other arguments. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::Arg; + /// Arg::new("config") + /// .exclusive(true) + /// # ; + /// ``` + /// + /// Setting an exclusive argument and having any other arguments present at runtime + /// is an error. + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, error::ErrorKind, ArgAction}; + /// let res = Command::new("prog") + /// .arg(Arg::new("exclusive") + /// .action(ArgAction::Set) + /// .exclusive(true) + /// .long("exclusive")) + /// .arg(Arg::new("debug") + /// .long("debug")) + /// .arg(Arg::new("input")) + /// .try_get_matches_from(vec![ + /// "prog", "--exclusive", "file.conf", "file.txt" + /// ]); + /// + /// assert!(res.is_err()); + /// assert_eq!(res.unwrap_err().kind(), ErrorKind::ArgumentConflict); + /// ``` + #[inline] + #[must_use] + pub fn exclusive(self, yes: bool) -> Self { + if yes { + self.setting(ArgSettings::Exclusive) + } else { + self.unset_setting(ArgSettings::Exclusive) + } + } + + /// Specifies that an argument can be matched to all child [`Subcommand`]s. + /// + /// **NOTE:** Global arguments *only* propagate down, **not** up (to parent commands), however + /// their values once a user uses them will be propagated back up to parents. In effect, this + /// means one should *define* all global arguments at the top level, however it doesn't matter + /// where the user *uses* the global argument. + /// + /// # Examples + /// + /// Assume an application with two subcommands, and you'd like to define a + /// `--verbose` flag that can be called on any of the subcommands and parent, but you don't + /// want to clutter the source with three duplicate [`Arg`] definitions. + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// let m = Command::new("prog") + /// .arg(Arg::new("verb") + /// .long("verbose") + /// .short('v') + /// .action(ArgAction::SetTrue) + /// .global(true)) + /// .subcommand(Command::new("test")) + /// .subcommand(Command::new("do-stuff")) + /// .get_matches_from(vec![ + /// "prog", "do-stuff", "--verbose" + /// ]); + /// + /// assert_eq!(m.subcommand_name(), Some("do-stuff")); + /// let sub_m = m.subcommand_matches("do-stuff").unwrap(); + /// assert_eq!(sub_m.get_flag("verb"), true); + /// ``` + /// + /// [`Subcommand`]: crate::Subcommand + #[inline] + #[must_use] + pub fn global(self, yes: bool) -> Self { + if yes { + self.setting(ArgSettings::Global) + } else { + self.unset_setting(ArgSettings::Global) + } + } + + #[inline] + pub(crate) fn is_set(&self, s: ArgSettings) -> bool { + self.settings.is_set(s) + } + + #[inline] + #[must_use] + pub(crate) fn setting(mut self, setting: ArgSettings) -> Self { + self.settings.set(setting); + self + } + + #[inline] + #[must_use] + pub(crate) fn unset_setting(mut self, setting: ArgSettings) -> Self { + self.settings.unset(setting); + self + } +} + +/// # Value Handling +impl Arg { + /// Specify how to react to an argument when parsing it. + /// + /// [ArgAction] controls things like + /// - Overwriting previous values with new ones + /// - Appending new values to all previous ones + /// - Counting how many times a flag occurs + /// + /// The default action is `ArgAction::Set` + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::Command; + /// # use clap::Arg; + /// let cmd = Command::new("mycmd") + /// .arg( + /// Arg::new("flag") + /// .long("flag") + /// .action(clap::ArgAction::Append) + /// ); + /// + /// let matches = cmd.try_get_matches_from(["mycmd", "--flag", "value"]).unwrap(); + /// assert!(matches.contains_id("flag")); + /// assert_eq!( + /// matches.get_many::<String>("flag").unwrap_or_default().map(|v| v.as_str()).collect::<Vec<_>>(), + /// vec!["value"] + /// ); + /// ``` + #[inline] + #[must_use] + pub fn action(mut self, action: impl IntoResettable<ArgAction>) -> Self { + self.action = action.into_resettable().into_option(); + self + } + + /// Specify the typed behavior of the argument. + /// + /// This allows parsing and validating a value before storing it into + /// [`ArgMatches`][crate::ArgMatches] as the given type. + /// + /// Possible value parsers include: + /// - [`value_parser!(T)`][crate::value_parser!] for auto-selecting a value parser for a given type + /// - Or [range expressions like `0..=1`][std::ops::RangeBounds] as a shorthand for [`RangedI64ValueParser`][crate::builder::RangedI64ValueParser] + /// - `Fn(&str) -> Result<T, E>` + /// - `[&str]` and [`PossibleValuesParser`][crate::builder::PossibleValuesParser] for static enumerated values + /// - [`BoolishValueParser`][crate::builder::BoolishValueParser], and [`FalseyValueParser`][crate::builder::FalseyValueParser] for alternative `bool` implementations + /// - [`NonEmptyStringValueParser`][crate::builder::NonEmptyStringValueParser] for basic validation for strings + /// - or any other [`TypedValueParser`][crate::builder::TypedValueParser] implementation + /// + /// The default value is [`ValueParser::string`][crate::builder::ValueParser::string]. + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::ArgAction; + /// let mut cmd = clap::Command::new("raw") + /// .arg( + /// clap::Arg::new("color") + /// .long("color") + /// .value_parser(["always", "auto", "never"]) + /// .default_value("auto") + /// ) + /// .arg( + /// clap::Arg::new("hostname") + /// .long("hostname") + /// .value_parser(clap::builder::NonEmptyStringValueParser::new()) + /// .action(ArgAction::Set) + /// .required(true) + /// ) + /// .arg( + /// clap::Arg::new("port") + /// .long("port") + /// .value_parser(clap::value_parser!(u16).range(3000..)) + /// .action(ArgAction::Set) + /// .required(true) + /// ); + /// + /// let m = cmd.try_get_matches_from_mut( + /// ["cmd", "--hostname", "rust-lang.org", "--port", "3001"] + /// ).unwrap(); + /// + /// let color: &String = m.get_one("color") + /// .expect("default"); + /// assert_eq!(color, "auto"); + /// + /// let hostname: &String = m.get_one("hostname") + /// .expect("required"); + /// assert_eq!(hostname, "rust-lang.org"); + /// + /// let port: u16 = *m.get_one("port") + /// .expect("required"); + /// assert_eq!(port, 3001); + /// ``` + pub fn value_parser(mut self, parser: impl IntoResettable<super::ValueParser>) -> Self { + self.value_parser = parser.into_resettable().into_option(); + self + } + + /// Specifies the number of arguments parsed per occurrence + /// + /// For example, if you had a `-f <file>` argument where you wanted exactly 3 'files' you would + /// set `.num_args(3)`, and this argument wouldn't be satisfied unless the user + /// provided 3 and only 3 values. + /// + /// Users may specify values for arguments in any of the following methods + /// + /// - Using a space such as `-o value` or `--option value` + /// - Using an equals and no space such as `-o=value` or `--option=value` + /// - Use a short and no space such as `-ovalue` + /// + /// **WARNING:** + /// + /// Setting a variable number of values (e.g. `1..=10`) for an argument without + /// other details can be dangerous in some circumstances. Because multiple values are + /// allowed, `--option val1 val2 val3` is perfectly valid. Be careful when designing a CLI + /// where **positional arguments** or **subcommands** are *also* expected as `clap` will continue + /// parsing *values* until one of the following happens: + /// + /// - It reaches the maximum number of values + /// - It reaches a specific number of values + /// - It finds another flag or option (i.e. something that starts with a `-`) + /// - It reaches the [`Arg::value_terminator`] if set + /// + /// Alternatively, + /// - Use a delimiter between values with [Arg::value_delimiter] + /// - Require a flag occurrence per value with [`ArgAction::Append`] + /// - Require positional arguments to appear after `--` with [`Arg::last`] + /// + /// # Examples + /// + /// Option: + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg}; + /// let m = Command::new("prog") + /// .arg(Arg::new("mode") + /// .long("mode") + /// .num_args(1)) + /// .get_matches_from(vec![ + /// "prog", "--mode", "fast" + /// ]); + /// + /// assert_eq!(m.get_one::<String>("mode").unwrap(), "fast"); + /// ``` + /// + /// Flag/option hybrid (see also [default_missing_value][Arg::default_missing_value]) + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, error::ErrorKind, ArgAction}; + /// let cmd = Command::new("prog") + /// .arg(Arg::new("mode") + /// .long("mode") + /// .default_missing_value("slow") + /// .default_value("plaid") + /// .num_args(0..=1)); + /// + /// let m = cmd.clone() + /// .get_matches_from(vec![ + /// "prog", "--mode", "fast" + /// ]); + /// assert_eq!(m.get_one::<String>("mode").unwrap(), "fast"); + /// + /// let m = cmd.clone() + /// .get_matches_from(vec![ + /// "prog", "--mode", + /// ]); + /// assert_eq!(m.get_one::<String>("mode").unwrap(), "slow"); + /// + /// let m = cmd.clone() + /// .get_matches_from(vec![ + /// "prog", + /// ]); + /// assert_eq!(m.get_one::<String>("mode").unwrap(), "plaid"); + /// ``` + /// + /// Tuples + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, error::ErrorKind, ArgAction}; + /// let cmd = Command::new("prog") + /// .arg(Arg::new("file") + /// .action(ArgAction::Set) + /// .num_args(2) + /// .short('F')); + /// + /// let m = cmd.clone() + /// .get_matches_from(vec![ + /// "prog", "-F", "in-file", "out-file" + /// ]); + /// assert_eq!( + /// m.get_many::<String>("file").unwrap_or_default().map(|v| v.as_str()).collect::<Vec<_>>(), + /// vec!["in-file", "out-file"] + /// ); + /// + /// let res = cmd.clone() + /// .try_get_matches_from(vec![ + /// "prog", "-F", "file1" + /// ]); + /// assert_eq!(res.unwrap_err().kind(), ErrorKind::WrongNumberOfValues); + /// ``` + /// + /// A common mistake is to define an option which allows multiple values and a positional + /// argument. + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// let cmd = Command::new("prog") + /// .arg(Arg::new("file") + /// .action(ArgAction::Set) + /// .num_args(0..) + /// .short('F')) + /// .arg(Arg::new("word")); + /// + /// let m = cmd.clone().get_matches_from(vec![ + /// "prog", "-F", "file1", "file2", "file3", "word" + /// ]); + /// let files: Vec<_> = m.get_many::<String>("file").unwrap().collect(); + /// assert_eq!(files, ["file1", "file2", "file3", "word"]); // wait...what?! + /// assert!(!m.contains_id("word")); // but we clearly used word! + /// + /// // but this works + /// let m = cmd.clone().get_matches_from(vec![ + /// "prog", "word", "-F", "file1", "file2", "file3", + /// ]); + /// let files: Vec<_> = m.get_many::<String>("file").unwrap().collect(); + /// assert_eq!(files, ["file1", "file2", "file3"]); + /// assert_eq!(m.get_one::<String>("word").unwrap(), "word"); + /// ``` + /// The problem is `clap` doesn't know when to stop parsing values for "file". + /// + /// A solution for the example above is to limit how many values with a maximum, or specific + /// number, or to say [`ArgAction::Append`] is ok, but multiple values are not. + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// let m = Command::new("prog") + /// .arg(Arg::new("file") + /// .action(ArgAction::Append) + /// .short('F')) + /// .arg(Arg::new("word")) + /// .get_matches_from(vec![ + /// "prog", "-F", "file1", "-F", "file2", "-F", "file3", "word" + /// ]); + /// + /// let files: Vec<_> = m.get_many::<String>("file").unwrap().collect(); + /// assert_eq!(files, ["file1", "file2", "file3"]); + /// assert_eq!(m.get_one::<String>("word").unwrap(), "word"); + /// ``` + #[inline] + #[must_use] + pub fn num_args(mut self, qty: impl IntoResettable<ValueRange>) -> Self { + self.num_vals = qty.into_resettable().into_option(); + self + } + + #[doc(hidden)] + #[cfg_attr( + feature = "deprecated", + deprecated(since = "4.0.0", note = "Replaced with `Arg::num_args`") + )] + pub fn number_of_values(self, qty: usize) -> Self { + self.num_args(qty) + } + + /// Placeholder for the argument's value in the help message / usage. + /// + /// This name is cosmetic only; the name is **not** used to access arguments. + /// This setting can be very helpful when describing the type of input the user should be + /// using, such as `FILE`, `INTERFACE`, etc. Although not required, it's somewhat convention to + /// use all capital letters for the value name. + /// + /// **NOTE:** implicitly sets [`Arg::action(ArgAction::Set)`] + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg}; + /// Arg::new("cfg") + /// .long("config") + /// .value_name("FILE") + /// # ; + /// ``` + /// + /// ```rust + /// # use clap_builder as clap; + /// # #[cfg(feature = "help")] { + /// # use clap::{Command, Arg}; + /// let m = Command::new("prog") + /// .arg(Arg::new("config") + /// .long("config") + /// .value_name("FILE") + /// .help("Some help text")) + /// .get_matches_from(vec![ + /// "prog", "--help" + /// ]); + /// # } + /// ``` + /// Running the above program produces the following output + /// + /// ```text + /// valnames + /// + /// Usage: valnames [OPTIONS] + /// + /// Options: + /// --config <FILE> Some help text + /// -h, --help Print help information + /// -V, --version Print version information + /// ``` + /// [positional]: Arg::index() + /// [`Arg::action(ArgAction::Set)`]: Arg::action() + #[inline] + #[must_use] + pub fn value_name(mut self, name: impl IntoResettable<Str>) -> Self { + if let Some(name) = name.into_resettable().into_option() { + self.value_names([name]) + } else { + self.val_names.clear(); + self + } + } + + /// Placeholders for the argument's values in the help message / usage. + /// + /// These names are cosmetic only, used for help and usage strings only. The names are **not** + /// used to access arguments. The values of the arguments are accessed in numeric order (i.e. + /// if you specify two names `one` and `two` `one` will be the first matched value, `two` will + /// be the second). + /// + /// This setting can be very helpful when describing the type of input the user should be + /// using, such as `FILE`, `INTERFACE`, etc. Although not required, it's somewhat convention to + /// use all capital letters for the value name. + /// + /// **Pro Tip:** It may help to use [`Arg::next_line_help(true)`] if there are long, or + /// multiple value names in order to not throw off the help text alignment of all options. + /// + /// **NOTE:** implicitly sets [`Arg::action(ArgAction::Set)`] and [`Arg::num_args(1..)`]. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg}; + /// Arg::new("speed") + /// .short('s') + /// .value_names(["fast", "slow"]); + /// ``` + /// + /// ```rust + /// # use clap_builder as clap; + /// # #[cfg(feature = "help")] { + /// # use clap::{Command, Arg}; + /// let m = Command::new("prog") + /// .arg(Arg::new("io") + /// .long("io-files") + /// .value_names(["INFILE", "OUTFILE"])) + /// .get_matches_from(vec![ + /// "prog", "--help" + /// ]); + /// # } + /// ``` + /// + /// Running the above program produces the following output + /// + /// ```text + /// valnames + /// + /// Usage: valnames [OPTIONS] + /// + /// Options: + /// -h, --help Print help information + /// --io-files <INFILE> <OUTFILE> Some help text + /// -V, --version Print version information + /// ``` + /// [`Arg::next_line_help(true)`]: Arg::next_line_help() + /// [`Arg::num_args`]: Arg::num_args() + /// [`Arg::action(ArgAction::Set)`]: Arg::action() + /// [`Arg::num_args(1..)`]: Arg::num_args() + #[must_use] + pub fn value_names(mut self, names: impl IntoIterator<Item = impl Into<Str>>) -> Self { + self.val_names = names.into_iter().map(|s| s.into()).collect(); + self + } + + /// Provide the shell a hint about how to complete this argument. + /// + /// See [`ValueHint`] for more information. + /// + /// **NOTE:** implicitly sets [`Arg::action(ArgAction::Set)`]. + /// + /// For example, to take a username as argument: + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Arg, ValueHint}; + /// Arg::new("user") + /// .short('u') + /// .long("user") + /// .value_hint(ValueHint::Username); + /// ``` + /// + /// To take a full command line and its arguments (for example, when writing a command wrapper): + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ValueHint, ArgAction}; + /// Command::new("prog") + /// .trailing_var_arg(true) + /// .arg( + /// Arg::new("command") + /// .action(ArgAction::Set) + /// .num_args(1..) + /// .value_hint(ValueHint::CommandWithArguments) + /// ); + /// ``` + #[must_use] + pub fn value_hint(mut self, value_hint: impl IntoResettable<ValueHint>) -> Self { + self.value_hint = value_hint.into_resettable().into_option(); + self + } + + /// Match values against [`PossibleValuesParser`][crate::builder::PossibleValuesParser] without matching case. + /// + /// When other arguments are conditionally required based on the + /// value of a case-insensitive argument, the equality check done + /// by [`Arg::required_if_eq`], [`Arg::required_if_eq_any`], or + /// [`Arg::required_if_eq_all`] is case-insensitive. + /// + /// + /// **NOTE:** Setting this requires [taking values][Arg::num_args] + /// + /// **NOTE:** To do unicode case folding, enable the `unicode` feature flag. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// let m = Command::new("pv") + /// .arg(Arg::new("option") + /// .long("option") + /// .action(ArgAction::Set) + /// .ignore_case(true) + /// .value_parser(["test123"])) + /// .get_matches_from(vec![ + /// "pv", "--option", "TeSt123", + /// ]); + /// + /// assert!(m.get_one::<String>("option").unwrap().eq_ignore_ascii_case("test123")); + /// ``` + /// + /// This setting also works when multiple values can be defined: + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// let m = Command::new("pv") + /// .arg(Arg::new("option") + /// .short('o') + /// .long("option") + /// .action(ArgAction::Set) + /// .ignore_case(true) + /// .num_args(1..) + /// .value_parser(["test123", "test321"])) + /// .get_matches_from(vec![ + /// "pv", "--option", "TeSt123", "teST123", "tESt321" + /// ]); + /// + /// let matched_vals = m.get_many::<String>("option").unwrap().collect::<Vec<_>>(); + /// assert_eq!(&*matched_vals, &["TeSt123", "teST123", "tESt321"]); + /// ``` + #[inline] + #[must_use] + pub fn ignore_case(self, yes: bool) -> Self { + if yes { + self.setting(ArgSettings::IgnoreCase) + } else { + self.unset_setting(ArgSettings::IgnoreCase) + } + } + + /// Allows values which start with a leading hyphen (`-`) + /// + /// To limit values to just numbers, see + /// [`allow_negative_numbers`][Arg::allow_negative_numbers]. + /// + /// See also [`trailing_var_arg`][Arg::trailing_var_arg]. + /// + /// **NOTE:** Setting this requires [taking values][Arg::num_args] + /// + /// **WARNING:** Prior arguments with `allow_hyphen_values(true)` get precedence over known + /// flags but known flags get precedence over the next possible positional argument with + /// `allow_hyphen_values(true)`. When combined with [`Arg::num_args(..)`], + /// [`Arg::value_terminator`] is one way to ensure processing stops. + /// + /// **WARNING**: Take caution when using this setting combined with another argument using + /// [`Arg::num_args`], as this becomes ambiguous `$ prog --arg -- -- val`. All + /// three `--, --, val` will be values when the user may have thought the second `--` would + /// constitute the normal, "Only positional args follow" idiom. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// let m = Command::new("prog") + /// .arg(Arg::new("pat") + /// .action(ArgAction::Set) + /// .allow_hyphen_values(true) + /// .long("pattern")) + /// .get_matches_from(vec![ + /// "prog", "--pattern", "-file" + /// ]); + /// + /// assert_eq!(m.get_one::<String>("pat").unwrap(), "-file"); + /// ``` + /// + /// Not setting `Arg::allow_hyphen_values(true)` and supplying a value which starts with a + /// hyphen is an error. + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, error::ErrorKind, ArgAction}; + /// let res = Command::new("prog") + /// .arg(Arg::new("pat") + /// .action(ArgAction::Set) + /// .long("pattern")) + /// .try_get_matches_from(vec![ + /// "prog", "--pattern", "-file" + /// ]); + /// + /// assert!(res.is_err()); + /// assert_eq!(res.unwrap_err().kind(), ErrorKind::UnknownArgument); + /// ``` + /// [`Arg::num_args(1)`]: Arg::num_args() + #[inline] + #[must_use] + pub fn allow_hyphen_values(self, yes: bool) -> Self { + if yes { + self.setting(ArgSettings::AllowHyphenValues) + } else { + self.unset_setting(ArgSettings::AllowHyphenValues) + } + } + + /// Allows negative numbers to pass as values. + /// + /// This is similar to [`Arg::allow_hyphen_values`] except that it only allows numbers, + /// all other undefined leading hyphens will fail to parse. + /// + /// **NOTE:** Setting this requires [taking values][Arg::num_args] + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg}; + /// let res = Command::new("myprog") + /// .arg(Arg::new("num").allow_negative_numbers(true)) + /// .try_get_matches_from(vec![ + /// "myprog", "-20" + /// ]); + /// assert!(res.is_ok()); + /// let m = res.unwrap(); + /// assert_eq!(m.get_one::<String>("num").unwrap(), "-20"); + /// ``` + #[inline] + pub fn allow_negative_numbers(self, yes: bool) -> Self { + if yes { + self.setting(ArgSettings::AllowNegativeNumbers) + } else { + self.unset_setting(ArgSettings::AllowNegativeNumbers) + } + } + + /// Requires that options use the `--option=val` syntax + /// + /// i.e. an equals between the option and associated value. + /// + /// **NOTE:** Setting this requires [taking values][Arg::num_args] + /// + /// # Examples + /// + /// Setting `require_equals` requires that the option have an equals sign between + /// it and the associated value. + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// let res = Command::new("prog") + /// .arg(Arg::new("cfg") + /// .action(ArgAction::Set) + /// .require_equals(true) + /// .long("config")) + /// .try_get_matches_from(vec![ + /// "prog", "--config=file.conf" + /// ]); + /// + /// assert!(res.is_ok()); + /// ``` + /// + /// Setting `require_equals` and *not* supplying the equals will cause an + /// error. + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, error::ErrorKind, ArgAction}; + /// let res = Command::new("prog") + /// .arg(Arg::new("cfg") + /// .action(ArgAction::Set) + /// .require_equals(true) + /// .long("config")) + /// .try_get_matches_from(vec![ + /// "prog", "--config", "file.conf" + /// ]); + /// + /// assert!(res.is_err()); + /// assert_eq!(res.unwrap_err().kind(), ErrorKind::NoEquals); + /// ``` + #[inline] + #[must_use] + pub fn require_equals(self, yes: bool) -> Self { + if yes { + self.setting(ArgSettings::RequireEquals) + } else { + self.unset_setting(ArgSettings::RequireEquals) + } + } + + #[doc(hidden)] + #[cfg_attr( + feature = "deprecated", + deprecated(since = "4.0.0", note = "Replaced with `Arg::value_delimiter`") + )] + pub fn use_value_delimiter(mut self, yes: bool) -> Self { + if yes { + self.val_delim.get_or_insert(','); + } else { + self.val_delim = None; + } + self + } + + /// 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:** implicitly sets [`Arg::action(ArgAction::Set)`] + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg}; + /// let m = Command::new("prog") + /// .arg(Arg::new("config") + /// .short('c') + /// .long("config") + /// .value_delimiter(',')) + /// .get_matches_from(vec![ + /// "prog", "--config=val1,val2,val3" + /// ]); + /// + /// assert_eq!(m.get_many::<String>("config").unwrap().collect::<Vec<_>>(), ["val1", "val2", "val3"]) + /// ``` + /// [`Arg::value_delimiter(',')`]: Arg::value_delimiter() + /// [`Arg::action(ArgAction::Set)`]: Arg::action() + #[inline] + #[must_use] + pub fn value_delimiter(mut self, d: impl IntoResettable<char>) -> Self { + self.val_delim = d.into_resettable().into_option(); + self + } + + /// Sentinel to **stop** parsing multiple values of a given argument. + /// + /// By default when + /// one sets [`num_args(1..)`] on an argument, clap will continue parsing values for that + /// argument until it reaches another valid argument, or one of the other more specific settings + /// for multiple values is used (such as [`num_args`]). + /// + /// **NOTE:** This setting only applies to [options] and [positional arguments] + /// + /// **NOTE:** When the terminator is passed in on the command line, it is **not** stored as one + /// of the values + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// Arg::new("vals") + /// .action(ArgAction::Set) + /// .num_args(1..) + /// .value_terminator(";") + /// # ; + /// ``` + /// + /// The following example uses two arguments, a sequence of commands, and the location in which + /// to perform them + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// let m = Command::new("prog") + /// .arg(Arg::new("cmds") + /// .action(ArgAction::Set) + /// .num_args(1..) + /// .allow_hyphen_values(true) + /// .value_terminator(";")) + /// .arg(Arg::new("location")) + /// .get_matches_from(vec![ + /// "prog", "find", "-type", "f", "-name", "special", ";", "/home/clap" + /// ]); + /// let cmds: Vec<_> = m.get_many::<String>("cmds").unwrap().collect(); + /// assert_eq!(&cmds, &["find", "-type", "f", "-name", "special"]); + /// assert_eq!(m.get_one::<String>("location").unwrap(), "/home/clap"); + /// ``` + /// [options]: Arg::action + /// [positional arguments]: Arg::index() + /// [`num_args(1..)`]: Arg::num_args() + /// [`num_args`]: Arg::num_args() + #[inline] + #[must_use] + pub fn value_terminator(mut self, term: impl IntoResettable<Str>) -> Self { + self.terminator = term.into_resettable().into_option(); + self + } + + /// Consume all following arguments. + /// + /// Do not be parse them individually, but rather pass them in entirety. + /// + /// It is worth noting that setting this requires all values to come after a `--` to indicate + /// they should all be captured. For example: + /// + /// ```text + /// --foo something -- -v -v -v -b -b -b --baz -q -u -x + /// ``` + /// + /// Will result in everything after `--` to be considered one raw argument. This behavior + /// may not be exactly what you are expecting and using [`Arg::trailing_var_arg`] + /// may be more appropriate. + /// + /// **NOTE:** Implicitly sets [`Arg::action(ArgAction::Set)`] [`Arg::num_args(1..)`], + /// [`Arg::allow_hyphen_values(true)`], and [`Arg::last(true)`] when set to `true`. + /// + /// [`Arg::action(ArgAction::Set)`]: Arg::action() + /// [`Arg::num_args(1..)`]: Arg::num_args() + /// [`Arg::allow_hyphen_values(true)`]: Arg::allow_hyphen_values() + /// [`Arg::last(true)`]: Arg::last() + #[inline] + #[must_use] + pub fn raw(mut self, yes: bool) -> Self { + if yes { + self.num_vals.get_or_insert_with(|| (1..).into()); + } + self.allow_hyphen_values(yes).last(yes) + } + + /// Value for the argument when not present. + /// + /// **NOTE:** If the user *does not* use this argument at runtime [`ArgMatches::contains_id`] will + /// still return `true`. If you wish to determine whether the argument was used at runtime or + /// not, consider [`ArgMatches::value_source`][crate::ArgMatches::value_source]. + /// + /// **NOTE:** This setting is perfectly compatible with [`Arg::default_value_if`] but slightly + /// different. `Arg::default_value` *only* takes effect when the user has not provided this arg + /// at runtime. `Arg::default_value_if` however only takes effect when the user has not provided + /// a value at runtime **and** these other conditions are met as well. If you have set + /// `Arg::default_value` and `Arg::default_value_if`, and the user **did not** provide this arg + /// at runtime, nor were the conditions met for `Arg::default_value_if`, the `Arg::default_value` + /// will be applied. + /// + /// Like with command-line values, this will be split by [`Arg::value_delimiter`]. + /// + /// # Examples + /// + /// First we use the default value without providing any value at runtime. + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, parser::ValueSource}; + /// let m = Command::new("prog") + /// .arg(Arg::new("opt") + /// .long("myopt") + /// .default_value("myval")) + /// .get_matches_from(vec![ + /// "prog" + /// ]); + /// + /// assert_eq!(m.get_one::<String>("opt").unwrap(), "myval"); + /// assert!(m.contains_id("opt")); + /// assert_eq!(m.value_source("opt"), Some(ValueSource::DefaultValue)); + /// ``` + /// + /// Next we provide a value at runtime to override the default. + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, parser::ValueSource}; + /// let m = Command::new("prog") + /// .arg(Arg::new("opt") + /// .long("myopt") + /// .default_value("myval")) + /// .get_matches_from(vec![ + /// "prog", "--myopt=non_default" + /// ]); + /// + /// assert_eq!(m.get_one::<String>("opt").unwrap(), "non_default"); + /// assert!(m.contains_id("opt")); + /// assert_eq!(m.value_source("opt"), Some(ValueSource::CommandLine)); + /// ``` + /// [`Arg::action(ArgAction::Set)`]: Arg::action() + /// [`ArgMatches::contains_id`]: crate::ArgMatches::contains_id() + /// [`Arg::default_value_if`]: Arg::default_value_if() + #[inline] + #[must_use] + pub fn default_value(mut self, val: impl IntoResettable<OsStr>) -> Self { + if let Some(val) = val.into_resettable().into_option() { + self.default_values([val]) + } else { + self.default_vals.clear(); + self + } + } + + #[inline] + #[must_use] + #[doc(hidden)] + #[cfg_attr( + feature = "deprecated", + deprecated(since = "4.0.0", note = "Replaced with `Arg::default_value`") + )] + pub fn default_value_os(self, val: impl Into<OsStr>) -> Self { + self.default_values([val]) + } + + /// Value for the argument when not present. + /// + /// See [`Arg::default_value`]. + /// + /// [`Arg::default_value`]: Arg::default_value() + #[inline] + #[must_use] + pub fn default_values(mut self, vals: impl IntoIterator<Item = impl Into<OsStr>>) -> Self { + self.default_vals = vals.into_iter().map(|s| s.into()).collect(); + self + } + + #[inline] + #[must_use] + #[doc(hidden)] + #[cfg_attr( + feature = "deprecated", + deprecated(since = "4.0.0", note = "Replaced with `Arg::default_values`") + )] + pub fn default_values_os(self, vals: impl IntoIterator<Item = impl Into<OsStr>>) -> Self { + self.default_values(vals) + } + + /// Value for the argument when the flag is present but no value is specified. + /// + /// This configuration option is often used to give the user a shortcut and allow them to + /// efficiently specify an option argument without requiring an explicitly value. The `--color` + /// argument is a common example. By, supplying an default, such as `default_missing_value("always")`, + /// the user can quickly just add `--color` to the command line to produce the desired color output. + /// + /// **NOTE:** using this configuration option requires the use of the + /// [`.num_args(0..N)`][Arg::num_args] and the + /// [`.require_equals(true)`][Arg::require_equals] configuration option. These are required in + /// order to unambiguously determine what, if any, value was supplied for the argument. + /// + /// Like with command-line values, this will be split by [`Arg::value_delimiter`]. + /// + /// # Examples + /// + /// For POSIX style `--color`: + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, parser::ValueSource}; + /// fn cli() -> Command { + /// Command::new("prog") + /// .arg(Arg::new("color").long("color") + /// .value_name("WHEN") + /// .value_parser(["always", "auto", "never"]) + /// .default_value("auto") + /// .num_args(0..=1) + /// .require_equals(true) + /// .default_missing_value("always") + /// .help("Specify WHEN to colorize output.") + /// ) + /// } + /// + /// // first, we'll provide no arguments + /// let m = cli().get_matches_from(vec![ + /// "prog" + /// ]); + /// assert_eq!(m.get_one::<String>("color").unwrap(), "auto"); + /// assert_eq!(m.value_source("color"), Some(ValueSource::DefaultValue)); + /// + /// // next, we'll provide a runtime value to override the default (as usually done). + /// let m = cli().get_matches_from(vec![ + /// "prog", "--color=never" + /// ]); + /// assert_eq!(m.get_one::<String>("color").unwrap(), "never"); + /// assert_eq!(m.value_source("color"), Some(ValueSource::CommandLine)); + /// + /// // finally, we will use the shortcut and only provide the argument without a value. + /// let m = cli().get_matches_from(vec![ + /// "prog", "--color" + /// ]); + /// assert_eq!(m.get_one::<String>("color").unwrap(), "always"); + /// assert_eq!(m.value_source("color"), Some(ValueSource::CommandLine)); + /// ``` + /// + /// For bool literals: + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, parser::ValueSource, value_parser}; + /// fn cli() -> Command { + /// Command::new("prog") + /// .arg(Arg::new("create").long("create") + /// .value_name("BOOL") + /// .value_parser(value_parser!(bool)) + /// .num_args(0..=1) + /// .require_equals(true) + /// .default_missing_value("true") + /// ) + /// } + /// + /// // first, we'll provide no arguments + /// let m = cli().get_matches_from(vec![ + /// "prog" + /// ]); + /// assert_eq!(m.get_one::<bool>("create").copied(), None); + /// + /// // next, we'll provide a runtime value to override the default (as usually done). + /// let m = cli().get_matches_from(vec![ + /// "prog", "--create=false" + /// ]); + /// assert_eq!(m.get_one::<bool>("create").copied(), Some(false)); + /// assert_eq!(m.value_source("create"), Some(ValueSource::CommandLine)); + /// + /// // finally, we will use the shortcut and only provide the argument without a value. + /// let m = cli().get_matches_from(vec![ + /// "prog", "--create" + /// ]); + /// assert_eq!(m.get_one::<bool>("create").copied(), Some(true)); + /// assert_eq!(m.value_source("create"), Some(ValueSource::CommandLine)); + /// ``` + /// + /// [`Arg::action(ArgAction::Set)`]: Arg::action() + /// [`Arg::default_value`]: Arg::default_value() + #[inline] + #[must_use] + pub fn default_missing_value(mut self, val: impl IntoResettable<OsStr>) -> Self { + if let Some(val) = val.into_resettable().into_option() { + self.default_missing_values_os([val]) + } else { + self.default_missing_vals.clear(); + self + } + } + + /// Value for the argument when the flag is present but no value is specified. + /// + /// See [`Arg::default_missing_value`]. + /// + /// [`Arg::default_missing_value`]: Arg::default_missing_value() + /// [`OsStr`]: std::ffi::OsStr + #[inline] + #[must_use] + pub fn default_missing_value_os(self, val: impl Into<OsStr>) -> Self { + self.default_missing_values_os([val]) + } + + /// Value for the argument when the flag is present but no value is specified. + /// + /// See [`Arg::default_missing_value`]. + /// + /// [`Arg::default_missing_value`]: Arg::default_missing_value() + #[inline] + #[must_use] + pub fn default_missing_values(self, vals: impl IntoIterator<Item = impl Into<OsStr>>) -> Self { + self.default_missing_values_os(vals) + } + + /// Value for the argument when the flag is present but no value is specified. + /// + /// See [`Arg::default_missing_values`]. + /// + /// [`Arg::default_missing_values`]: Arg::default_missing_values() + /// [`OsStr`]: std::ffi::OsStr + #[inline] + #[must_use] + pub fn default_missing_values_os( + mut self, + vals: impl IntoIterator<Item = impl Into<OsStr>>, + ) -> Self { + self.default_missing_vals = vals.into_iter().map(|s| s.into()).collect(); + self + } + + /// Read from `name` environment variable when argument is not present. + /// + /// If it is not present in the environment, then default + /// rules will apply. + /// + /// If user sets the argument in the environment: + /// - When [`Arg::action(ArgAction::Set)`] is not set, the flag is considered raised. + /// - When [`Arg::action(ArgAction::Set)`] is set, + /// [`ArgMatches::get_one`][crate::ArgMatches::get_one] will + /// return value of the environment variable. + /// + /// If user doesn't set the argument in the environment: + /// - When [`Arg::action(ArgAction::Set)`] is not set, the flag is considered off. + /// - When [`Arg::action(ArgAction::Set)`] is set, + /// [`ArgMatches::get_one`][crate::ArgMatches::get_one] will + /// return the default specified. + /// + /// Like with command-line values, this will be split by [`Arg::value_delimiter`]. + /// + /// # Examples + /// + /// In this example, we show the variable coming from the environment: + /// + /// ```rust + /// # use clap_builder as clap; + /// # use std::env; + /// # use clap::{Command, Arg, ArgAction}; + /// + /// env::set_var("MY_FLAG", "env"); + /// + /// let m = Command::new("prog") + /// .arg(Arg::new("flag") + /// .long("flag") + /// .env("MY_FLAG") + /// .action(ArgAction::Set)) + /// .get_matches_from(vec![ + /// "prog" + /// ]); + /// + /// assert_eq!(m.get_one::<String>("flag").unwrap(), "env"); + /// ``` + /// + /// In this example, because `prog` is a flag that accepts an optional, case-insensitive + /// boolean literal. + /// + /// Note that the value parser controls how flags are parsed. In this case we've selected + /// [`FalseyValueParser`][crate::builder::FalseyValueParser]. A `false` literal is `n`, `no`, + /// `f`, `false`, `off` or `0`. An absent environment variable will also be considered as + /// `false`. Anything else will considered as `true`. + /// + /// ```rust + /// # use clap_builder as clap; + /// # use std::env; + /// # use clap::{Command, Arg, ArgAction}; + /// # use clap::builder::FalseyValueParser; + /// + /// env::set_var("TRUE_FLAG", "true"); + /// env::set_var("FALSE_FLAG", "0"); + /// + /// let m = Command::new("prog") + /// .arg(Arg::new("true_flag") + /// .long("true_flag") + /// .action(ArgAction::SetTrue) + /// .value_parser(FalseyValueParser::new()) + /// .env("TRUE_FLAG")) + /// .arg(Arg::new("false_flag") + /// .long("false_flag") + /// .action(ArgAction::SetTrue) + /// .value_parser(FalseyValueParser::new()) + /// .env("FALSE_FLAG")) + /// .arg(Arg::new("absent_flag") + /// .long("absent_flag") + /// .action(ArgAction::SetTrue) + /// .value_parser(FalseyValueParser::new()) + /// .env("ABSENT_FLAG")) + /// .get_matches_from(vec![ + /// "prog" + /// ]); + /// + /// assert!(m.get_flag("true_flag")); + /// assert!(!m.get_flag("false_flag")); + /// assert!(!m.get_flag("absent_flag")); + /// ``` + /// + /// In this example, we show the variable coming from an option on the CLI: + /// + /// ```rust + /// # use clap_builder as clap; + /// # use std::env; + /// # use clap::{Command, Arg, ArgAction}; + /// + /// env::set_var("MY_FLAG", "env"); + /// + /// let m = Command::new("prog") + /// .arg(Arg::new("flag") + /// .long("flag") + /// .env("MY_FLAG") + /// .action(ArgAction::Set)) + /// .get_matches_from(vec![ + /// "prog", "--flag", "opt" + /// ]); + /// + /// assert_eq!(m.get_one::<String>("flag").unwrap(), "opt"); + /// ``` + /// + /// In this example, we show the variable coming from the environment even with the + /// presence of a default: + /// + /// ```rust + /// # use clap_builder as clap; + /// # use std::env; + /// # use clap::{Command, Arg, ArgAction}; + /// + /// env::set_var("MY_FLAG", "env"); + /// + /// let m = Command::new("prog") + /// .arg(Arg::new("flag") + /// .long("flag") + /// .env("MY_FLAG") + /// .action(ArgAction::Set) + /// .default_value("default")) + /// .get_matches_from(vec![ + /// "prog" + /// ]); + /// + /// assert_eq!(m.get_one::<String>("flag").unwrap(), "env"); + /// ``` + /// + /// In this example, we show the use of multiple values in a single environment variable: + /// + /// ```rust + /// # use clap_builder as clap; + /// # use std::env; + /// # use clap::{Command, Arg, ArgAction}; + /// + /// env::set_var("MY_FLAG_MULTI", "env1,env2"); + /// + /// let m = Command::new("prog") + /// .arg(Arg::new("flag") + /// .long("flag") + /// .env("MY_FLAG_MULTI") + /// .action(ArgAction::Set) + /// .num_args(1..) + /// .value_delimiter(',')) + /// .get_matches_from(vec![ + /// "prog" + /// ]); + /// + /// assert_eq!(m.get_many::<String>("flag").unwrap().collect::<Vec<_>>(), vec!["env1", "env2"]); + /// ``` + /// [`Arg::action(ArgAction::Set)`]: Arg::action() + /// [`Arg::value_delimiter(',')`]: Arg::value_delimiter() + #[cfg(feature = "env")] + #[inline] + #[must_use] + pub fn env(mut self, name: impl IntoResettable<OsStr>) -> Self { + if let Some(name) = name.into_resettable().into_option() { + let value = env::var_os(&name); + self.env = Some((name, value)); + } else { + self.env = None; + } + self + } + + #[cfg(feature = "env")] + #[doc(hidden)] + #[cfg_attr( + feature = "deprecated", + deprecated(since = "4.0.0", note = "Replaced with `Arg::env`") + )] + pub fn env_os(self, name: impl Into<OsStr>) -> Self { + self.env(name) + } +} + +/// # Help +impl Arg { + /// Sets the description of the argument for short help (`-h`). + /// + /// Typically, this is a short (one line) description of the arg. + /// + /// If [`Arg::long_help`] is not specified, this message will be displayed for `--help`. + /// + /// **NOTE:** Only `Arg::help` is used in completion script generation in order to be concise + /// + /// # Examples + /// + /// Any valid UTF-8 is allowed in the help text. The one exception is when one wishes to + /// include a newline in the help text and have the following text be properly aligned with all + /// the other help text. + /// + /// Setting `help` displays a short message to the side of the argument when the user passes + /// `-h` or `--help` (by default). + /// + /// ```rust + /// # #[cfg(feature = "help")] { + /// # use clap_builder as clap; + /// # use clap::{Command, Arg}; + /// let m = Command::new("prog") + /// .arg(Arg::new("cfg") + /// .long("config") + /// .help("Some help text describing the --config arg")) + /// .get_matches_from(vec![ + /// "prog", "--help" + /// ]); + /// # } + /// ``` + /// + /// The above example displays + /// + /// ```notrust + /// helptest + /// + /// Usage: helptest [OPTIONS] + /// + /// Options: + /// --config Some help text describing the --config arg + /// -h, --help Print help information + /// -V, --version Print version information + /// ``` + /// [`Arg::long_help`]: Arg::long_help() + #[inline] + #[must_use] + pub fn help(mut self, h: impl IntoResettable<StyledStr>) -> Self { + self.help = h.into_resettable().into_option(); + self + } + + /// Sets the description of the argument for long help (`--help`). + /// + /// Typically this a more detailed (multi-line) message + /// that describes the arg. + /// + /// If [`Arg::help`] is not specified, this message will be displayed for `-h`. + /// + /// **NOTE:** Only [`Arg::help`] is used in completion script generation in order to be concise + /// + /// # Examples + /// + /// Any valid UTF-8 is allowed in the help text. The one exception is when one wishes to + /// include a newline in the help text and have the following text be properly aligned with all + /// the other help text. + /// + /// Setting `help` displays a short message to the side of the argument when the user passes + /// `-h` or `--help` (by default). + /// + /// ```rust + /// # #[cfg(feature = "help")] { + /// # use clap_builder as clap; + /// # use clap::{Command, Arg}; + /// let m = Command::new("prog") + /// .arg(Arg::new("cfg") + /// .long("config") + /// .long_help( + /// "The config file used by the myprog must be in JSON format + /// with only valid keys and may not contain other nonsense + /// that cannot be read by this program. Obviously I'm going on + /// and on, so I'll stop now.")) + /// .get_matches_from(vec![ + /// "prog", "--help" + /// ]); + /// # } + /// ``` + /// + /// The above example displays + /// + /// ```text + /// prog + /// + /// Usage: prog [OPTIONS] + /// + /// Options: + /// --config + /// The config file used by the myprog must be in JSON format + /// with only valid keys and may not contain other nonsense + /// that cannot be read by this program. Obviously I'm going on + /// and on, so I'll stop now. + /// + /// -h, --help + /// Print help information + /// + /// -V, --version + /// Print version information + /// ``` + /// [`Arg::help`]: Arg::help() + #[inline] + #[must_use] + pub fn long_help(mut self, h: impl IntoResettable<StyledStr>) -> Self { + self.long_help = h.into_resettable().into_option(); + self + } + + /// Allows custom ordering of args within the help message. + /// + /// `Arg`s with a lower value will be displayed first in the help message. + /// Those with the same display order will be sorted. + /// + /// `Arg`s are automatically assigned a display order based on the order they are added to the + /// [`Command`][crate::Command]. + /// Overriding this is helpful when the order arguments are added in isn't the same as the + /// display order, whether in one-off cases or to automatically sort arguments. + /// + /// To change, see [`Command::next_display_order`][crate::Command::next_display_order]. + /// + /// **NOTE:** This setting is ignored for [positional arguments] which are always displayed in + /// [index] order. + /// + /// # Examples + /// + /// ```rust + /// # #[cfg(feature = "help")] { + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// let m = Command::new("prog") + /// .arg(Arg::new("boat") + /// .short('b') + /// .long("boat") + /// .action(ArgAction::Set) + /// .display_order(0) // Sort + /// .help("Some help and text")) + /// .arg(Arg::new("airplane") + /// .short('a') + /// .long("airplane") + /// .action(ArgAction::Set) + /// .display_order(0) // Sort + /// .help("I should be first!")) + /// .arg(Arg::new("custom-help") + /// .short('?') + /// .action(ArgAction::Help) + /// .display_order(100) // Don't sort + /// .help("Alt help")) + /// .get_matches_from(vec![ + /// "prog", "--help" + /// ]); + /// # } + /// ``` + /// + /// The above example displays the following help message + /// + /// ```text + /// cust-ord + /// + /// Usage: cust-ord [OPTIONS] + /// + /// Options: + /// -a, --airplane <airplane> I should be first! + /// -b, --boat <boar> Some help and text + /// -h, --help Print help information + /// -? Alt help + /// ``` + /// [positional arguments]: Arg::index() + /// [index]: Arg::index() + #[inline] + #[must_use] + pub fn display_order(mut self, ord: impl IntoResettable<usize>) -> Self { + self.disp_ord = ord.into_resettable().into_option(); + self + } + + /// Override the [current] help section. + /// + /// [current]: crate::Command::next_help_heading + #[inline] + #[must_use] + pub fn help_heading(mut self, heading: impl IntoResettable<Str>) -> Self { + self.help_heading = Some(heading.into_resettable().into_option()); + self + } + + /// Render the [help][Arg::help] on the line after the argument. + /// + /// This can be helpful for arguments with very long or complex help messages. + /// This can also be helpful for arguments with very long flag names, or many/long value names. + /// + /// **NOTE:** To apply this setting to all arguments and subcommands, consider using + /// [`crate::Command::next_line_help`] + /// + /// # Examples + /// + /// ```rust + /// # #[cfg(feature = "help")] { + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// let m = Command::new("prog") + /// .arg(Arg::new("opt") + /// .long("long-option-flag") + /// .short('o') + /// .action(ArgAction::Set) + /// .next_line_help(true) + /// .value_names(["value1", "value2"]) + /// .help("Some really long help and complex\n\ + /// help that makes more sense to be\n\ + /// on a line after the option")) + /// .get_matches_from(vec![ + /// "prog", "--help" + /// ]); + /// # } + /// ``` + /// + /// The above example displays the following help message + /// + /// ```text + /// nlh + /// + /// Usage: nlh [OPTIONS] + /// + /// Options: + /// -h, --help Print help information + /// -V, --version Print version information + /// -o, --long-option-flag <value1> <value2> + /// Some really long help and complex + /// help that makes more sense to be + /// on a line after the option + /// ``` + #[inline] + #[must_use] + pub fn next_line_help(self, yes: bool) -> Self { + if yes { + self.setting(ArgSettings::NextLineHelp) + } else { + self.unset_setting(ArgSettings::NextLineHelp) + } + } + + /// Do not display the argument in help message. + /// + /// **NOTE:** This does **not** hide the argument from usage strings on error + /// + /// # Examples + /// + /// Setting `Hidden` will hide the argument when displaying help text + /// + /// ```rust + /// # #[cfg(feature = "help")] { + /// # use clap_builder as clap; + /// # use clap::{Command, Arg}; + /// let m = Command::new("prog") + /// .arg(Arg::new("cfg") + /// .long("config") + /// .hide(true) + /// .help("Some help text describing the --config arg")) + /// .get_matches_from(vec![ + /// "prog", "--help" + /// ]); + /// # } + /// ``` + /// + /// The above example displays + /// + /// ```text + /// helptest + /// + /// Usage: helptest [OPTIONS] + /// + /// Options: + /// -h, --help Print help information + /// -V, --version Print version information + /// ``` + #[inline] + #[must_use] + pub fn hide(self, yes: bool) -> Self { + if yes { + self.setting(ArgSettings::Hidden) + } else { + self.unset_setting(ArgSettings::Hidden) + } + } + + /// Do not display the [possible values][crate::builder::ValueParser::possible_values] in the help message. + /// + /// This is useful for args with many values, or ones which are explained elsewhere in the + /// help text. + /// + /// **NOTE:** Setting this requires [taking values][Arg::num_args] + /// + /// To set this for all arguments, see + /// [`Command::hide_possible_values`][crate::Command::hide_possible_values]. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// let m = Command::new("prog") + /// .arg(Arg::new("mode") + /// .long("mode") + /// .value_parser(["fast", "slow"]) + /// .action(ArgAction::Set) + /// .hide_possible_values(true)); + /// ``` + /// If we were to run the above program with `--help` the `[values: fast, slow]` portion of + /// the help text would be omitted. + #[inline] + #[must_use] + pub fn hide_possible_values(self, yes: bool) -> Self { + if yes { + self.setting(ArgSettings::HidePossibleValues) + } else { + self.unset_setting(ArgSettings::HidePossibleValues) + } + } + + /// Do not display the default value of the argument in the help message. + /// + /// This is useful when default behavior of an arg is explained elsewhere in the help text. + /// + /// **NOTE:** Setting this requires [taking values][Arg::num_args] + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// let m = Command::new("connect") + /// .arg(Arg::new("host") + /// .long("host") + /// .default_value("localhost") + /// .action(ArgAction::Set) + /// .hide_default_value(true)); + /// + /// ``` + /// + /// If we were to run the above program with `--help` the `[default: localhost]` portion of + /// the help text would be omitted. + #[inline] + #[must_use] + pub fn hide_default_value(self, yes: bool) -> Self { + if yes { + self.setting(ArgSettings::HideDefaultValue) + } else { + self.unset_setting(ArgSettings::HideDefaultValue) + } + } + + /// Do not display in help the environment variable name. + /// + /// This is useful when the variable option is explained elsewhere in the help text. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// let m = Command::new("prog") + /// .arg(Arg::new("mode") + /// .long("mode") + /// .env("MODE") + /// .action(ArgAction::Set) + /// .hide_env(true)); + /// ``` + /// + /// If we were to run the above program with `--help` the `[env: MODE]` portion of the help + /// text would be omitted. + #[cfg(feature = "env")] + #[inline] + #[must_use] + pub fn hide_env(self, yes: bool) -> Self { + if yes { + self.setting(ArgSettings::HideEnv) + } else { + self.unset_setting(ArgSettings::HideEnv) + } + } + + /// Do not display in help any values inside the associated ENV variables for the argument. + /// + /// This is useful when ENV vars contain sensitive values. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// let m = Command::new("connect") + /// .arg(Arg::new("host") + /// .long("host") + /// .env("CONNECT") + /// .action(ArgAction::Set) + /// .hide_env_values(true)); + /// + /// ``` + /// + /// If we were to run the above program with `$ CONNECT=super_secret connect --help` the + /// `[default: CONNECT=super_secret]` portion of the help text would be omitted. + #[cfg(feature = "env")] + #[inline] + #[must_use] + pub fn hide_env_values(self, yes: bool) -> Self { + if yes { + self.setting(ArgSettings::HideEnvValues) + } else { + self.unset_setting(ArgSettings::HideEnvValues) + } + } + + /// Hides an argument from short help (`-h`). + /// + /// **NOTE:** This does **not** hide the argument from usage strings on error + /// + /// **NOTE:** Setting this option will cause next-line-help output style to be used + /// when long help (`--help`) is called. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg}; + /// Arg::new("debug") + /// .hide_short_help(true); + /// ``` + /// + /// Setting `hide_short_help(true)` will hide the argument when displaying short help text + /// + /// ```rust + /// # #[cfg(feature = "help")] { + /// # use clap_builder as clap; + /// # use clap::{Command, Arg}; + /// let m = Command::new("prog") + /// .arg(Arg::new("cfg") + /// .long("config") + /// .hide_short_help(true) + /// .help("Some help text describing the --config arg")) + /// .get_matches_from(vec![ + /// "prog", "-h" + /// ]); + /// # } + /// ``` + /// + /// The above example displays + /// + /// ```text + /// helptest + /// + /// Usage: helptest [OPTIONS] + /// + /// Options: + /// -h, --help Print help information + /// -V, --version Print version information + /// ``` + /// + /// However, when --help is called + /// + /// ```rust + /// # #[cfg(feature = "help")] { + /// # use clap_builder as clap; + /// # use clap::{Command, Arg}; + /// let m = Command::new("prog") + /// .arg(Arg::new("cfg") + /// .long("config") + /// .hide_short_help(true) + /// .help("Some help text describing the --config arg")) + /// .get_matches_from(vec![ + /// "prog", "--help" + /// ]); + /// # } + /// ``` + /// + /// Then the following would be displayed + /// + /// ```text + /// helptest + /// + /// Usage: helptest [OPTIONS] + /// + /// Options: + /// --config Some help text describing the --config arg + /// -h, --help Print help information + /// -V, --version Print version information + /// ``` + #[inline] + #[must_use] + pub fn hide_short_help(self, yes: bool) -> Self { + if yes { + self.setting(ArgSettings::HiddenShortHelp) + } else { + self.unset_setting(ArgSettings::HiddenShortHelp) + } + } + + /// Hides an argument from long help (`--help`). + /// + /// **NOTE:** This does **not** hide the argument from usage strings on error + /// + /// **NOTE:** Setting this option will cause next-line-help output style to be used + /// when long help (`--help`) is called. + /// + /// # Examples + /// + /// Setting `hide_long_help(true)` will hide the argument when displaying long help text + /// + /// ```rust + /// # #[cfg(feature = "help")] { + /// # use clap_builder as clap; + /// # use clap::{Command, Arg}; + /// let m = Command::new("prog") + /// .arg(Arg::new("cfg") + /// .long("config") + /// .hide_long_help(true) + /// .help("Some help text describing the --config arg")) + /// .get_matches_from(vec![ + /// "prog", "--help" + /// ]); + /// # } + /// ``` + /// + /// The above example displays + /// + /// ```text + /// helptest + /// + /// Usage: helptest [OPTIONS] + /// + /// Options: + /// -h, --help Print help information + /// -V, --version Print version information + /// ``` + /// + /// However, when -h is called + /// + /// ```rust + /// # #[cfg(feature = "help")] { + /// # use clap_builder as clap; + /// # use clap::{Command, Arg}; + /// let m = Command::new("prog") + /// .arg(Arg::new("cfg") + /// .long("config") + /// .hide_long_help(true) + /// .help("Some help text describing the --config arg")) + /// .get_matches_from(vec![ + /// "prog", "-h" + /// ]); + /// # } + /// ``` + /// + /// Then the following would be displayed + /// + /// ```text + /// helptest + /// + /// Usage: helptest [OPTIONS] + /// + /// OPTIONS: + /// --config Some help text describing the --config arg + /// -h, --help Print help information + /// -V, --version Print version information + /// ``` + #[inline] + #[must_use] + pub fn hide_long_help(self, yes: bool) -> Self { + if yes { + self.setting(ArgSettings::HiddenLongHelp) + } else { + self.unset_setting(ArgSettings::HiddenLongHelp) + } + } +} + +/// # Advanced Argument Relations +impl Arg { + /// The name of the [`ArgGroup`] the argument belongs to. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// Arg::new("debug") + /// .long("debug") + /// .action(ArgAction::SetTrue) + /// .group("mode") + /// # ; + /// ``` + /// + /// Multiple arguments can be a member of a single group and then the group checked as if it + /// was one of said arguments. + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// let m = Command::new("prog") + /// .arg(Arg::new("debug") + /// .long("debug") + /// .action(ArgAction::SetTrue) + /// .group("mode")) + /// .arg(Arg::new("verbose") + /// .long("verbose") + /// .action(ArgAction::SetTrue) + /// .group("mode")) + /// .get_matches_from(vec![ + /// "prog", "--debug" + /// ]); + /// assert!(m.contains_id("mode")); + /// ``` + /// + /// [`ArgGroup`]: crate::ArgGroup + #[must_use] + pub fn group(mut self, group_id: impl IntoResettable<Id>) -> Self { + if let Some(group_id) = group_id.into_resettable().into_option() { + self.groups.push(group_id); + } else { + self.groups.clear(); + } + self + } + + /// The names of [`ArgGroup`]'s the argument belongs to. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// Arg::new("debug") + /// .long("debug") + /// .action(ArgAction::SetTrue) + /// .groups(["mode", "verbosity"]) + /// # ; + /// ``` + /// + /// Arguments can be members of multiple groups and then the group checked as if it + /// was one of said arguments. + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// let m = Command::new("prog") + /// .arg(Arg::new("debug") + /// .long("debug") + /// .action(ArgAction::SetTrue) + /// .groups(["mode", "verbosity"])) + /// .arg(Arg::new("verbose") + /// .long("verbose") + /// .action(ArgAction::SetTrue) + /// .groups(["mode", "verbosity"])) + /// .get_matches_from(vec![ + /// "prog", "--debug" + /// ]); + /// assert!(m.contains_id("mode")); + /// assert!(m.contains_id("verbosity")); + /// ``` + /// + /// [`ArgGroup`]: crate::ArgGroup + #[must_use] + pub fn groups(mut self, group_ids: impl IntoIterator<Item = impl Into<Id>>) -> Self { + self.groups.extend(group_ids.into_iter().map(Into::into)); + self + } + + /// Specifies the value of the argument if `arg` has been used at runtime. + /// + /// If `default` is set to `None`, `default_value` will be removed. + /// + /// **NOTE:** This setting is perfectly compatible with [`Arg::default_value`] but slightly + /// different. `Arg::default_value` *only* takes effect when the user has not provided this arg + /// at runtime. This setting however only takes effect when the user has not provided a value at + /// runtime **and** these other conditions are met as well. If you have set `Arg::default_value` + /// and `Arg::default_value_if`, and the user **did not** provide this arg at runtime, nor were + /// the conditions met for `Arg::default_value_if`, the `Arg::default_value` will be applied. + /// + /// Like with command-line values, this will be split by [`Arg::value_delimiter`]. + /// + /// # Examples + /// + /// First we use the default value only if another arg is present at runtime. + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// # use clap::builder::{ArgPredicate}; + /// let m = Command::new("prog") + /// .arg(Arg::new("flag") + /// .long("flag") + /// .action(ArgAction::SetTrue)) + /// .arg(Arg::new("other") + /// .long("other") + /// .default_value_if("flag", ArgPredicate::IsPresent, Some("default"))) + /// .get_matches_from(vec![ + /// "prog", "--flag" + /// ]); + /// + /// assert_eq!(m.get_one::<String>("other").unwrap(), "default"); + /// ``` + /// + /// Next we run the same test, but without providing `--flag`. + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// let m = Command::new("prog") + /// .arg(Arg::new("flag") + /// .long("flag") + /// .action(ArgAction::SetTrue)) + /// .arg(Arg::new("other") + /// .long("other") + /// .default_value_if("flag", "true", Some("default"))) + /// .get_matches_from(vec![ + /// "prog" + /// ]); + /// + /// assert_eq!(m.get_one::<String>("other"), None); + /// ``` + /// + /// Now lets only use the default value if `--opt` contains the value `special`. + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// let m = Command::new("prog") + /// .arg(Arg::new("opt") + /// .action(ArgAction::Set) + /// .long("opt")) + /// .arg(Arg::new("other") + /// .long("other") + /// .default_value_if("opt", "special", Some("default"))) + /// .get_matches_from(vec![ + /// "prog", "--opt", "special" + /// ]); + /// + /// assert_eq!(m.get_one::<String>("other").unwrap(), "default"); + /// ``` + /// + /// We can run the same test and provide any value *other than* `special` and we won't get a + /// default value. + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// let m = Command::new("prog") + /// .arg(Arg::new("opt") + /// .action(ArgAction::Set) + /// .long("opt")) + /// .arg(Arg::new("other") + /// .long("other") + /// .default_value_if("opt", "special", Some("default"))) + /// .get_matches_from(vec![ + /// "prog", "--opt", "hahaha" + /// ]); + /// + /// assert_eq!(m.get_one::<String>("other"), None); + /// ``` + /// + /// If we want to unset the default value for an Arg based on the presence or + /// value of some other Arg. + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// let m = Command::new("prog") + /// .arg(Arg::new("flag") + /// .long("flag") + /// .action(ArgAction::SetTrue)) + /// .arg(Arg::new("other") + /// .long("other") + /// .default_value("default") + /// .default_value_if("flag", "true", None)) + /// .get_matches_from(vec![ + /// "prog", "--flag" + /// ]); + /// + /// assert_eq!(m.get_one::<String>("other"), None); + /// ``` + /// [`Arg::action(ArgAction::Set)`]: Arg::action() + /// [`Arg::default_value`]: Arg::default_value() + #[must_use] + pub fn default_value_if( + mut self, + arg_id: impl Into<Id>, + predicate: impl Into<ArgPredicate>, + default: impl IntoResettable<OsStr>, + ) -> Self { + self.default_vals_ifs.push(( + arg_id.into(), + predicate.into(), + default.into_resettable().into_option(), + )); + self + } + + #[must_use] + #[doc(hidden)] + #[cfg_attr( + feature = "deprecated", + deprecated(since = "4.0.0", note = "Replaced with `Arg::default_value_if`") + )] + pub fn default_value_if_os( + self, + arg_id: impl Into<Id>, + predicate: impl Into<ArgPredicate>, + default: impl IntoResettable<OsStr>, + ) -> Self { + self.default_value_if(arg_id, predicate, default) + } + + /// Specifies multiple values and conditions in the same manner as [`Arg::default_value_if`]. + /// + /// The method takes a slice of tuples in the `(arg, predicate, default)` format. + /// + /// **NOTE**: The conditions are stored in order and evaluated in the same order. I.e. the first + /// if multiple conditions are true, the first one found will be applied and the ultimate value. + /// + /// Like with command-line values, this will be split by [`Arg::value_delimiter`]. + /// + /// # Examples + /// + /// First we use the default value only if another arg is present at runtime. + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// let m = Command::new("prog") + /// .arg(Arg::new("flag") + /// .long("flag") + /// .action(ArgAction::SetTrue)) + /// .arg(Arg::new("opt") + /// .long("opt") + /// .action(ArgAction::Set)) + /// .arg(Arg::new("other") + /// .long("other") + /// .default_value_ifs([ + /// ("flag", "true", Some("default")), + /// ("opt", "channal", Some("chan")), + /// ])) + /// .get_matches_from(vec![ + /// "prog", "--opt", "channal" + /// ]); + /// + /// assert_eq!(m.get_one::<String>("other").unwrap(), "chan"); + /// ``` + /// + /// Next we run the same test, but without providing `--flag`. + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// let m = Command::new("prog") + /// .arg(Arg::new("flag") + /// .long("flag") + /// .action(ArgAction::SetTrue)) + /// .arg(Arg::new("other") + /// .long("other") + /// .default_value_ifs([ + /// ("flag", "true", Some("default")), + /// ("opt", "channal", Some("chan")), + /// ])) + /// .get_matches_from(vec![ + /// "prog" + /// ]); + /// + /// assert_eq!(m.get_one::<String>("other"), None); + /// ``` + /// + /// We can also see that these values are applied in order, and if more than one condition is + /// true, only the first evaluated "wins" + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// # use clap::builder::ArgPredicate; + /// let m = Command::new("prog") + /// .arg(Arg::new("flag") + /// .long("flag") + /// .action(ArgAction::SetTrue)) + /// .arg(Arg::new("opt") + /// .long("opt") + /// .action(ArgAction::Set)) + /// .arg(Arg::new("other") + /// .long("other") + /// .default_value_ifs([ + /// ("flag", ArgPredicate::IsPresent, Some("default")), + /// ("opt", ArgPredicate::Equals("channal".into()), Some("chan")), + /// ])) + /// .get_matches_from(vec![ + /// "prog", "--opt", "channal", "--flag" + /// ]); + /// + /// assert_eq!(m.get_one::<String>("other").unwrap(), "default"); + /// ``` + /// [`Arg::action(ArgAction::Set)`]: Arg::action() + /// [`Arg::default_value_if`]: Arg::default_value_if() + #[must_use] + pub fn default_value_ifs( + mut self, + ifs: impl IntoIterator< + Item = ( + impl Into<Id>, + impl Into<ArgPredicate>, + impl IntoResettable<OsStr>, + ), + >, + ) -> Self { + for (arg, predicate, default) in ifs { + self = self.default_value_if(arg, predicate, default); + } + self + } + + #[must_use] + #[doc(hidden)] + #[cfg_attr( + feature = "deprecated", + deprecated(since = "4.0.0", note = "Replaced with `Arg::default_value_ifs`") + )] + pub fn default_value_ifs_os( + self, + ifs: impl IntoIterator< + Item = ( + impl Into<Id>, + impl Into<ArgPredicate>, + impl IntoResettable<OsStr>, + ), + >, + ) -> Self { + self.default_value_ifs(ifs) + } + + /// 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 + /// mandatory to also set. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::Arg; + /// Arg::new("config") + /// .required_unless_present("debug") + /// # ; + /// ``` + /// + /// In the following example, the required argument is *not* provided, + /// but it's not an error because the `unless` arg has been supplied. + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// let res = Command::new("prog") + /// .arg(Arg::new("cfg") + /// .required_unless_present("dbg") + /// .action(ArgAction::Set) + /// .long("config")) + /// .arg(Arg::new("dbg") + /// .long("debug") + /// .action(ArgAction::SetTrue)) + /// .try_get_matches_from(vec![ + /// "prog", "--debug" + /// ]); + /// + /// assert!(res.is_ok()); + /// ``` + /// + /// Setting `Arg::required_unless_present(name)` and *not* supplying `name` or this arg is an error. + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, error::ErrorKind, ArgAction}; + /// let res = Command::new("prog") + /// .arg(Arg::new("cfg") + /// .required_unless_present("dbg") + /// .action(ArgAction::Set) + /// .long("config")) + /// .arg(Arg::new("dbg") + /// .long("debug")) + /// .try_get_matches_from(vec![ + /// "prog" + /// ]); + /// + /// assert!(res.is_err()); + /// assert_eq!(res.unwrap_err().kind(), ErrorKind::MissingRequiredArgument); + /// ``` + /// [required]: Arg::required() + #[must_use] + pub fn required_unless_present(mut self, arg_id: impl IntoResettable<Id>) -> Self { + if let Some(arg_id) = arg_id.into_resettable().into_option() { + self.r_unless.push(arg_id); + } else { + self.r_unless.clear(); + } + self + } + + /// 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 + /// * supplies the `self` arg. + /// * supplies *all* of the `names` arguments. + /// + /// **NOTE:** If you wish for this argument to only be required unless *any of* these args are + /// present see [`Arg::required_unless_present_any`] + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::Arg; + /// Arg::new("config") + /// .required_unless_present_all(["cfg", "dbg"]) + /// # ; + /// ``` + /// + /// In the following example, the required argument is *not* provided, but it's not an error + /// because *all* of the `names` args have been supplied. + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// let res = Command::new("prog") + /// .arg(Arg::new("cfg") + /// .required_unless_present_all(["dbg", "infile"]) + /// .action(ArgAction::Set) + /// .long("config")) + /// .arg(Arg::new("dbg") + /// .long("debug") + /// .action(ArgAction::SetTrue)) + /// .arg(Arg::new("infile") + /// .short('i') + /// .action(ArgAction::Set)) + /// .try_get_matches_from(vec![ + /// "prog", "--debug", "-i", "file" + /// ]); + /// + /// assert!(res.is_ok()); + /// ``` + /// + /// Setting [`Arg::required_unless_present_all(names)`] and *not* supplying + /// either *all* of `unless` args or the `self` arg is an error. + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, error::ErrorKind, ArgAction}; + /// let res = Command::new("prog") + /// .arg(Arg::new("cfg") + /// .required_unless_present_all(["dbg", "infile"]) + /// .action(ArgAction::Set) + /// .long("config")) + /// .arg(Arg::new("dbg") + /// .long("debug") + /// .action(ArgAction::SetTrue)) + /// .arg(Arg::new("infile") + /// .short('i') + /// .action(ArgAction::Set)) + /// .try_get_matches_from(vec![ + /// "prog" + /// ]); + /// + /// assert!(res.is_err()); + /// assert_eq!(res.unwrap_err().kind(), ErrorKind::MissingRequiredArgument); + /// ``` + /// [required]: Arg::required() + /// [`Arg::required_unless_present_any`]: Arg::required_unless_present_any() + /// [`Arg::required_unless_present_all(names)`]: Arg::required_unless_present_all() + #[must_use] + pub fn required_unless_present_all( + mut self, + names: impl IntoIterator<Item = impl Into<Id>>, + ) -> Self { + self.r_unless_all.extend(names.into_iter().map(Into::into)); + self + } + + /// 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 + /// * supplies the `self` arg. + /// * supplies *one or more* of the `unless` arguments. + /// + /// **NOTE:** If you wish for this argument to be required unless *all of* these args are + /// present see [`Arg::required_unless_present_all`] + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::Arg; + /// Arg::new("config") + /// .required_unless_present_any(["cfg", "dbg"]) + /// # ; + /// ``` + /// + /// Setting [`Arg::required_unless_present_any(names)`] requires that the argument be used at runtime + /// *unless* *at least one of* the args in `names` are present. In the following example, the + /// required argument is *not* provided, but it's not an error because one the `unless` args + /// have been supplied. + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// let res = Command::new("prog") + /// .arg(Arg::new("cfg") + /// .required_unless_present_any(["dbg", "infile"]) + /// .action(ArgAction::Set) + /// .long("config")) + /// .arg(Arg::new("dbg") + /// .long("debug") + /// .action(ArgAction::SetTrue)) + /// .arg(Arg::new("infile") + /// .short('i') + /// .action(ArgAction::Set)) + /// .try_get_matches_from(vec![ + /// "prog", "--debug" + /// ]); + /// + /// assert!(res.is_ok()); + /// ``` + /// + /// Setting [`Arg::required_unless_present_any(names)`] and *not* supplying *at least one of* `names` + /// or this arg is an error. + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, error::ErrorKind, ArgAction}; + /// let res = Command::new("prog") + /// .arg(Arg::new("cfg") + /// .required_unless_present_any(["dbg", "infile"]) + /// .action(ArgAction::Set) + /// .long("config")) + /// .arg(Arg::new("dbg") + /// .long("debug") + /// .action(ArgAction::SetTrue)) + /// .arg(Arg::new("infile") + /// .short('i') + /// .action(ArgAction::Set)) + /// .try_get_matches_from(vec![ + /// "prog" + /// ]); + /// + /// assert!(res.is_err()); + /// assert_eq!(res.unwrap_err().kind(), ErrorKind::MissingRequiredArgument); + /// ``` + /// [required]: Arg::required() + /// [`Arg::required_unless_present_any(names)`]: Arg::required_unless_present_any() + /// [`Arg::required_unless_present_all`]: Arg::required_unless_present_all() + #[must_use] + pub fn required_unless_present_any( + mut self, + names: impl IntoIterator<Item = impl Into<Id>>, + ) -> Self { + self.r_unless.extend(names.into_iter().map(Into::into)); + self + } + + /// This argument is [required] only if the specified `arg` is present at runtime and its value + /// equals `val`. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::Arg; + /// Arg::new("config") + /// .required_if_eq("other_arg", "value") + /// # ; + /// ``` + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, error::ErrorKind, ArgAction}; + /// let res = Command::new("prog") + /// .arg(Arg::new("cfg") + /// .action(ArgAction::Set) + /// .required_if_eq("other", "special") + /// .long("config")) + /// .arg(Arg::new("other") + /// .long("other") + /// .action(ArgAction::Set)) + /// .try_get_matches_from(vec![ + /// "prog", "--other", "not-special" + /// ]); + /// + /// assert!(res.is_ok()); // We didn't use --other=special, so "cfg" wasn't required + /// + /// let res = Command::new("prog") + /// .arg(Arg::new("cfg") + /// .action(ArgAction::Set) + /// .required_if_eq("other", "special") + /// .long("config")) + /// .arg(Arg::new("other") + /// .long("other") + /// .action(ArgAction::Set)) + /// .try_get_matches_from(vec![ + /// "prog", "--other", "special" + /// ]); + /// + /// // We did use --other=special so "cfg" had become required but was missing. + /// assert!(res.is_err()); + /// assert_eq!(res.unwrap_err().kind(), ErrorKind::MissingRequiredArgument); + /// + /// let res = Command::new("prog") + /// .arg(Arg::new("cfg") + /// .action(ArgAction::Set) + /// .required_if_eq("other", "special") + /// .long("config")) + /// .arg(Arg::new("other") + /// .long("other") + /// .action(ArgAction::Set)) + /// .try_get_matches_from(vec![ + /// "prog", "--other", "SPECIAL" + /// ]); + /// + /// // By default, the comparison is case-sensitive, so "cfg" wasn't required + /// assert!(res.is_ok()); + /// + /// let res = Command::new("prog") + /// .arg(Arg::new("cfg") + /// .action(ArgAction::Set) + /// .required_if_eq("other", "special") + /// .long("config")) + /// .arg(Arg::new("other") + /// .long("other") + /// .ignore_case(true) + /// .action(ArgAction::Set)) + /// .try_get_matches_from(vec![ + /// "prog", "--other", "SPECIAL" + /// ]); + /// + /// // However, case-insensitive comparisons can be enabled. This typically occurs when using Arg::possible_values(). + /// assert!(res.is_err()); + /// assert_eq!(res.unwrap_err().kind(), ErrorKind::MissingRequiredArgument); + /// ``` + /// [`Arg::requires(name)`]: Arg::requires() + /// [Conflicting]: Arg::conflicts_with() + /// [required]: Arg::required() + #[must_use] + pub fn required_if_eq(mut self, arg_id: impl Into<Id>, val: impl Into<OsStr>) -> Self { + self.r_ifs.push((arg_id.into(), val.into())); + self + } + + /// Specify 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`. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::Arg; + /// Arg::new("config") + /// .required_if_eq_any([ + /// ("extra", "val"), + /// ("option", "spec") + /// ]) + /// # ; + /// ``` + /// + /// Setting `Arg::required_if_eq_any([(arg, val)])` makes this arg required if any of the `arg`s + /// are used at runtime and it's corresponding value is equal to `val`. If the `arg`'s value is + /// anything other than `val`, this argument isn't required. + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// let res = Command::new("prog") + /// .arg(Arg::new("cfg") + /// .required_if_eq_any([ + /// ("extra", "val"), + /// ("option", "spec") + /// ]) + /// .action(ArgAction::Set) + /// .long("config")) + /// .arg(Arg::new("extra") + /// .action(ArgAction::Set) + /// .long("extra")) + /// .arg(Arg::new("option") + /// .action(ArgAction::Set) + /// .long("option")) + /// .try_get_matches_from(vec![ + /// "prog", "--option", "other" + /// ]); + /// + /// assert!(res.is_ok()); // We didn't use --option=spec, or --extra=val so "cfg" isn't required + /// ``` + /// + /// Setting `Arg::required_if_eq_any([(arg, val)])` and having any of the `arg`s used with its + /// value of `val` but *not* using this arg is an error. + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, error::ErrorKind, ArgAction}; + /// let res = Command::new("prog") + /// .arg(Arg::new("cfg") + /// .required_if_eq_any([ + /// ("extra", "val"), + /// ("option", "spec") + /// ]) + /// .action(ArgAction::Set) + /// .long("config")) + /// .arg(Arg::new("extra") + /// .action(ArgAction::Set) + /// .long("extra")) + /// .arg(Arg::new("option") + /// .action(ArgAction::Set) + /// .long("option")) + /// .try_get_matches_from(vec![ + /// "prog", "--option", "spec" + /// ]); + /// + /// assert!(res.is_err()); + /// assert_eq!(res.unwrap_err().kind(), ErrorKind::MissingRequiredArgument); + /// ``` + /// [`Arg::requires(name)`]: Arg::requires() + /// [Conflicting]: Arg::conflicts_with() + /// [required]: Arg::required() + #[must_use] + pub fn required_if_eq_any( + mut self, + ifs: impl IntoIterator<Item = (impl Into<Id>, impl Into<OsStr>)>, + ) -> Self { + self.r_ifs + .extend(ifs.into_iter().map(|(id, val)| (id.into(), val.into()))); + self + } + + /// Specify 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`. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::Arg; + /// Arg::new("config") + /// .required_if_eq_all([ + /// ("extra", "val"), + /// ("option", "spec") + /// ]) + /// # ; + /// ``` + /// + /// Setting `Arg::required_if_eq_all([(arg, val)])` makes this arg required if all of the `arg`s + /// are used at runtime and every value is equal to its corresponding `val`. If the `arg`'s value is + /// anything other than `val`, this argument isn't required. + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// let res = Command::new("prog") + /// .arg(Arg::new("cfg") + /// .required_if_eq_all([ + /// ("extra", "val"), + /// ("option", "spec") + /// ]) + /// .action(ArgAction::Set) + /// .long("config")) + /// .arg(Arg::new("extra") + /// .action(ArgAction::Set) + /// .long("extra")) + /// .arg(Arg::new("option") + /// .action(ArgAction::Set) + /// .long("option")) + /// .try_get_matches_from(vec![ + /// "prog", "--option", "spec" + /// ]); + /// + /// assert!(res.is_ok()); // We didn't use --option=spec --extra=val so "cfg" isn't required + /// ``` + /// + /// Setting `Arg::required_if_eq_all([(arg, val)])` and having all of the `arg`s used with its + /// value of `val` but *not* using this arg is an error. + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, error::ErrorKind, ArgAction}; + /// let res = Command::new("prog") + /// .arg(Arg::new("cfg") + /// .required_if_eq_all([ + /// ("extra", "val"), + /// ("option", "spec") + /// ]) + /// .action(ArgAction::Set) + /// .long("config")) + /// .arg(Arg::new("extra") + /// .action(ArgAction::Set) + /// .long("extra")) + /// .arg(Arg::new("option") + /// .action(ArgAction::Set) + /// .long("option")) + /// .try_get_matches_from(vec![ + /// "prog", "--extra", "val", "--option", "spec" + /// ]); + /// + /// assert!(res.is_err()); + /// assert_eq!(res.unwrap_err().kind(), ErrorKind::MissingRequiredArgument); + /// ``` + /// [required]: Arg::required() + #[must_use] + pub fn required_if_eq_all( + mut self, + ifs: impl IntoIterator<Item = (impl Into<Id>, impl Into<OsStr>)>, + ) -> Self { + self.r_ifs_all + .extend(ifs.into_iter().map(|(id, val)| (id.into(), val.into()))); + self + } + + /// Require another argument if this arg matches the [`ArgPredicate`] + /// + /// This method takes `value, another_arg` pair. At runtime, clap will check + /// if this arg (`self`) matches the [`ArgPredicate`]. + /// If it does, `another_arg` will be marked as required. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::Arg; + /// Arg::new("config") + /// .requires_if("val", "arg") + /// # ; + /// ``` + /// + /// Setting `Arg::requires_if(val, arg)` requires that the `arg` be used at runtime if the + /// defining argument's value is equal to `val`. If the defining argument is anything other than + /// `val`, the other argument isn't required. + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// let res = Command::new("prog") + /// .arg(Arg::new("cfg") + /// .action(ArgAction::Set) + /// .requires_if("my.cfg", "other") + /// .long("config")) + /// .arg(Arg::new("other")) + /// .try_get_matches_from(vec![ + /// "prog", "--config", "some.cfg" + /// ]); + /// + /// assert!(res.is_ok()); // We didn't use --config=my.cfg, so other wasn't required + /// ``` + /// + /// Setting `Arg::requires_if(val, arg)` and setting the value to `val` but *not* supplying + /// `arg` is an error. + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, error::ErrorKind, ArgAction}; + /// let res = Command::new("prog") + /// .arg(Arg::new("cfg") + /// .action(ArgAction::Set) + /// .requires_if("my.cfg", "input") + /// .long("config")) + /// .arg(Arg::new("input")) + /// .try_get_matches_from(vec![ + /// "prog", "--config", "my.cfg" + /// ]); + /// + /// assert!(res.is_err()); + /// assert_eq!(res.unwrap_err().kind(), ErrorKind::MissingRequiredArgument); + /// ``` + /// [`Arg::requires(name)`]: Arg::requires() + /// [Conflicting]: Arg::conflicts_with() + /// [override]: Arg::overrides_with() + #[must_use] + pub fn requires_if(mut self, val: impl Into<ArgPredicate>, arg_id: impl Into<Id>) -> Self { + self.requires.push((val.into(), arg_id.into())); + self + } + + /// Allows multiple conditional requirements. + /// + /// The requirement will only become valid if this arg's value matches the + /// [`ArgPredicate`]. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::Arg; + /// Arg::new("config") + /// .requires_ifs([ + /// ("val", "arg"), + /// ("other_val", "arg2"), + /// ]) + /// # ; + /// ``` + /// + /// Setting `Arg::requires_ifs(["val", "arg"])` requires that the `arg` be used at runtime if the + /// defining argument's value is equal to `val`. If the defining argument's value is anything other + /// than `val`, `arg` isn't required. + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, error::ErrorKind, ArgAction}; + /// let res = Command::new("prog") + /// .arg(Arg::new("cfg") + /// .action(ArgAction::Set) + /// .requires_ifs([ + /// ("special.conf", "opt"), + /// ("other.conf", "other"), + /// ]) + /// .long("config")) + /// .arg(Arg::new("opt") + /// .long("option") + /// .action(ArgAction::Set)) + /// .arg(Arg::new("other")) + /// .try_get_matches_from(vec![ + /// "prog", "--config", "special.conf" + /// ]); + /// + /// assert!(res.is_err()); // We used --config=special.conf so --option <val> is required + /// assert_eq!(res.unwrap_err().kind(), ErrorKind::MissingRequiredArgument); + /// ``` + /// + /// Setting `Arg::requires_ifs` with [`ArgPredicate::IsPresent`] and *not* supplying all the + /// arguments is an error. + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, error::ErrorKind, ArgAction, builder::ArgPredicate}; + /// let res = Command::new("prog") + /// .arg(Arg::new("cfg") + /// .action(ArgAction::Set) + /// .requires_ifs([ + /// (ArgPredicate::IsPresent, "input"), + /// (ArgPredicate::IsPresent, "output"), + /// ]) + /// .long("config")) + /// .arg(Arg::new("input")) + /// .arg(Arg::new("output")) + /// .try_get_matches_from(vec![ + /// "prog", "--config", "file.conf", "in.txt" + /// ]); + /// + /// assert!(res.is_err()); + /// // We didn't use output + /// assert_eq!(res.unwrap_err().kind(), ErrorKind::MissingRequiredArgument); + /// ``` + /// + /// [`Arg::requires(name)`]: Arg::requires() + /// [Conflicting]: Arg::conflicts_with() + /// [override]: Arg::overrides_with() + #[must_use] + pub fn requires_ifs( + mut self, + ifs: impl IntoIterator<Item = (impl Into<ArgPredicate>, impl Into<Id>)>, + ) -> Self { + self.requires + .extend(ifs.into_iter().map(|(val, arg)| (val.into(), arg.into()))); + self + } + + #[doc(hidden)] + #[cfg_attr( + feature = "deprecated", + deprecated(since = "4.0.0", note = "Replaced with `Arg::requires_ifs`") + )] + pub fn requires_all(self, ids: impl IntoIterator<Item = impl Into<Id>>) -> Self { + self.requires_ifs(ids.into_iter().map(|id| (ArgPredicate::IsPresent, id))) + } + + /// This argument is mutually exclusive with the specified argument. + /// + /// **NOTE:** Conflicting rules take precedence over being required by default. Conflict rules + /// only need to be set for one of the two arguments, they do not need to be set for each. + /// + /// **NOTE:** Defining a conflict is two-way, but does *not* need to defined for both arguments + /// (i.e. if A conflicts with B, defining A.conflicts_with(B) is sufficient. You do not + /// need to also do B.conflicts_with(A)) + /// + /// **NOTE:** [`Arg::conflicts_with_all(names)`] allows specifying an argument which conflicts with more than one argument. + /// + /// **NOTE** [`Arg::exclusive(true)`] allows specifying an argument which conflicts with every other argument. + /// + /// **NOTE:** All arguments implicitly conflict with themselves. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::Arg; + /// Arg::new("config") + /// .conflicts_with("debug") + /// # ; + /// ``` + /// + /// Setting conflicting argument, and having both arguments present at runtime is an error. + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, error::ErrorKind, ArgAction}; + /// let res = Command::new("prog") + /// .arg(Arg::new("cfg") + /// .action(ArgAction::Set) + /// .conflicts_with("debug") + /// .long("config")) + /// .arg(Arg::new("debug") + /// .long("debug") + /// .action(ArgAction::SetTrue)) + /// .try_get_matches_from(vec![ + /// "prog", "--debug", "--config", "file.conf" + /// ]); + /// + /// assert!(res.is_err()); + /// assert_eq!(res.unwrap_err().kind(), ErrorKind::ArgumentConflict); + /// ``` + /// + /// [`Arg::conflicts_with_all(names)`]: Arg::conflicts_with_all() + /// [`Arg::exclusive(true)`]: Arg::exclusive() + #[must_use] + pub fn conflicts_with(mut self, arg_id: impl IntoResettable<Id>) -> Self { + if let Some(arg_id) = arg_id.into_resettable().into_option() { + self.blacklist.push(arg_id); + } else { + self.blacklist.clear(); + } + self + } + + /// This argument is mutually exclusive with the specified arguments. + /// + /// See [`Arg::conflicts_with`]. + /// + /// **NOTE:** Conflicting rules take precedence over being required by default. Conflict rules + /// only need to be set for one of the two arguments, they do not need to be set for each. + /// + /// **NOTE:** Defining a conflict is two-way, but does *not* need to defined for both arguments + /// (i.e. if A conflicts with B, defining A.conflicts_with(B) is sufficient. You do not need + /// need to also do B.conflicts_with(A)) + /// + /// **NOTE:** [`Arg::exclusive(true)`] allows specifying an argument which conflicts with every other argument. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::Arg; + /// Arg::new("config") + /// .conflicts_with_all(["debug", "input"]) + /// # ; + /// ``` + /// + /// Setting conflicting argument, and having any of the arguments present at runtime with a + /// conflicting argument is an error. + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, error::ErrorKind, ArgAction}; + /// let res = Command::new("prog") + /// .arg(Arg::new("cfg") + /// .action(ArgAction::Set) + /// .conflicts_with_all(["debug", "input"]) + /// .long("config")) + /// .arg(Arg::new("debug") + /// .long("debug")) + /// .arg(Arg::new("input")) + /// .try_get_matches_from(vec![ + /// "prog", "--config", "file.conf", "file.txt" + /// ]); + /// + /// assert!(res.is_err()); + /// assert_eq!(res.unwrap_err().kind(), ErrorKind::ArgumentConflict); + /// ``` + /// [`Arg::conflicts_with`]: Arg::conflicts_with() + /// [`Arg::exclusive(true)`]: Arg::exclusive() + #[must_use] + pub fn conflicts_with_all(mut self, names: impl IntoIterator<Item = impl Into<Id>>) -> Self { + self.blacklist.extend(names.into_iter().map(Into::into)); + self + } + + /// Sets an overridable argument. + /// + /// i.e. this argument and the following argument + /// will override each other in POSIX style (whichever argument was specified at runtime + /// **last** "wins") + /// + /// **NOTE:** When an argument is overridden it is essentially as if it never was used, any + /// conflicts, requirements, etc. are evaluated **after** all "overrides" have been removed + /// + /// **NOTE:** Overriding an argument implies they [conflict][Arg::conflicts_with`]. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, arg}; + /// let m = Command::new("prog") + /// .arg(arg!(-f --flag "some flag") + /// .conflicts_with("debug")) + /// .arg(arg!(-d --debug "other flag")) + /// .arg(arg!(-c --color "third flag") + /// .overrides_with("flag")) + /// .get_matches_from(vec![ + /// "prog", "-f", "-d", "-c"]); + /// // ^~~~~~~~~~~~^~~~~ flag is overridden by color + /// + /// assert!(m.get_flag("color")); + /// assert!(m.get_flag("debug")); // even though flag conflicts with debug, it's as if flag + /// // was never used because it was overridden with color + /// assert!(!m.get_flag("flag")); + /// ``` + #[must_use] + pub fn overrides_with(mut self, arg_id: impl IntoResettable<Id>) -> Self { + if let Some(arg_id) = arg_id.into_resettable().into_option() { + self.overrides.push(arg_id); + } else { + self.overrides.clear(); + } + self + } + + /// Sets multiple mutually overridable arguments by name. + /// + /// i.e. this argument and the following argument will override each other in POSIX style + /// (whichever argument was specified at runtime **last** "wins") + /// + /// **NOTE:** When an argument is overridden it is essentially as if it never was used, any + /// conflicts, requirements, etc. are evaluated **after** all "overrides" have been removed + /// + /// **NOTE:** Overriding an argument implies they [conflict][Arg::conflicts_with_all`]. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, arg}; + /// let m = Command::new("prog") + /// .arg(arg!(-f --flag "some flag") + /// .conflicts_with("color")) + /// .arg(arg!(-d --debug "other flag")) + /// .arg(arg!(-c --color "third flag") + /// .overrides_with_all(["flag", "debug"])) + /// .get_matches_from(vec![ + /// "prog", "-f", "-d", "-c"]); + /// // ^~~~~~^~~~~~~~~ flag and debug are overridden by color + /// + /// assert!(m.get_flag("color")); // even though flag conflicts with color, it's as if flag + /// // and debug were never used because they were overridden + /// // with color + /// assert!(!m.get_flag("debug")); + /// assert!(!m.get_flag("flag")); + /// ``` + #[must_use] + pub fn overrides_with_all(mut self, names: impl IntoIterator<Item = impl Into<Id>>) -> Self { + self.overrides.extend(names.into_iter().map(Into::into)); + self + } +} + +/// # Reflection +impl Arg { + /// Get the name of the argument + #[inline] + pub fn get_id(&self) -> &Id { + &self.id + } + + /// Get the help specified for this argument, if any + #[inline] + pub fn get_help(&self) -> Option<&StyledStr> { + self.help.as_ref() + } + + /// Get the long help specified for this argument, if any + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::Arg; + /// let arg = Arg::new("foo").long_help("long help"); + /// assert_eq!(Some("long help".to_owned()), arg.get_long_help().map(|s| s.to_string())); + /// ``` + /// + #[inline] + pub fn get_long_help(&self) -> Option<&StyledStr> { + self.long_help.as_ref() + } + + /// Get the help heading specified for this argument, if any + #[inline] + pub fn get_help_heading(&self) -> Option<&str> { + self.help_heading + .as_ref() + .map(|s| s.as_deref()) + .unwrap_or_default() + } + + /// Get the short option name for this argument, if any + #[inline] + pub fn get_short(&self) -> Option<char> { + self.short + } + + /// Get visible short aliases for this argument, if any + #[inline] + pub fn get_visible_short_aliases(&self) -> Option<Vec<char>> { + if self.short_aliases.is_empty() { + None + } else { + Some( + self.short_aliases + .iter() + .filter_map(|(c, v)| if *v { Some(c) } else { None }) + .copied() + .collect(), + ) + } + } + + /// Get *all* short aliases for this argument, if any, both visible and hidden. + #[inline] + pub fn get_all_short_aliases(&self) -> Option<Vec<char>> { + if self.short_aliases.is_empty() { + None + } else { + Some(self.short_aliases.iter().map(|(s, _)| s).copied().collect()) + } + } + + /// Get the short option name and its visible aliases, if any + #[inline] + pub fn get_short_and_visible_aliases(&self) -> Option<Vec<char>> { + let mut shorts = match self.short { + Some(short) => vec![short], + None => return None, + }; + if let Some(aliases) = self.get_visible_short_aliases() { + shorts.extend(aliases); + } + Some(shorts) + } + + /// Get the long option name for this argument, if any + #[inline] + pub fn get_long(&self) -> Option<&str> { + self.long.as_deref() + } + + /// Get visible aliases for this argument, if any + #[inline] + pub fn get_visible_aliases(&self) -> Option<Vec<&str>> { + if self.aliases.is_empty() { + None + } else { + Some( + self.aliases + .iter() + .filter_map(|(s, v)| if *v { Some(s.as_str()) } else { None }) + .collect(), + ) + } + } + + /// Get *all* aliases for this argument, if any, both visible and hidden. + #[inline] + pub fn get_all_aliases(&self) -> Option<Vec<&str>> { + if self.aliases.is_empty() { + None + } else { + Some(self.aliases.iter().map(|(s, _)| s.as_str()).collect()) + } + } + + /// Get the long option name and its visible aliases, if any + #[inline] + pub fn get_long_and_visible_aliases(&self) -> Option<Vec<&str>> { + let mut longs = match self.get_long() { + Some(long) => vec![long], + None => return None, + }; + if let Some(aliases) = self.get_visible_aliases() { + longs.extend(aliases); + } + Some(longs) + } + + /// Get the names of possible values for this argument. Only useful for user + /// facing applications, such as building help messages or man files + pub fn get_possible_values(&self) -> Vec<PossibleValue> { + if !self.is_takes_value_set() { + vec![] + } else { + self.get_value_parser() + .possible_values() + .map(|pvs| pvs.collect()) + .unwrap_or_default() + } + } + + /// Get the names of values for this argument. + #[inline] + pub fn get_value_names(&self) -> Option<&[Str]> { + if self.val_names.is_empty() { + None + } else { + Some(&self.val_names) + } + } + + /// Get the number of values for this argument. + #[inline] + pub fn get_num_args(&self) -> Option<ValueRange> { + self.num_vals + } + + #[inline] + pub(crate) fn get_min_vals(&self) -> usize { + self.get_num_args().expect(INTERNAL_ERROR_MSG).min_values() + } + + /// Get the delimiter between multiple values + #[inline] + pub fn get_value_delimiter(&self) -> Option<char> { + self.val_delim + } + + /// Get the value terminator for this argument. The value_terminator is a value + /// that terminates parsing of multi-valued arguments. + #[inline] + pub fn get_value_terminator(&self) -> Option<&Str> { + self.terminator.as_ref() + } + + /// Get the index of this argument, if any + #[inline] + pub fn get_index(&self) -> Option<usize> { + self.index + } + + /// Get the value hint of this argument + pub fn get_value_hint(&self) -> ValueHint { + self.value_hint.unwrap_or_else(|| { + if self.is_takes_value_set() { + let type_id = self.get_value_parser().type_id(); + if type_id == AnyValueId::of::<std::path::PathBuf>() { + ValueHint::AnyPath + } else { + ValueHint::default() + } + } else { + ValueHint::default() + } + }) + } + + /// Get the environment variable name specified for this argument, if any + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use std::ffi::OsStr; + /// # use clap::Arg; + /// let arg = Arg::new("foo").env("ENVIRONMENT"); + /// assert_eq!(arg.get_env(), Some(OsStr::new("ENVIRONMENT"))); + /// ``` + #[cfg(feature = "env")] + pub fn get_env(&self) -> Option<&std::ffi::OsStr> { + self.env.as_ref().map(|x| x.0.as_os_str()) + } + + /// Get the default values specified for this argument, if any + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::Arg; + /// let arg = Arg::new("foo").default_value("default value"); + /// assert_eq!(arg.get_default_values(), &["default value"]); + /// ``` + pub fn get_default_values(&self) -> &[OsStr] { + &self.default_vals + } + + /// Checks whether this argument is a positional or not. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::Arg; + /// let arg = Arg::new("foo"); + /// assert_eq!(arg.is_positional(), true); + /// + /// let arg = Arg::new("foo").long("foo"); + /// assert_eq!(arg.is_positional(), false); + /// ``` + pub fn is_positional(&self) -> bool { + self.get_long().is_none() && self.get_short().is_none() + } + + /// Reports whether [`Arg::required`] is set + pub fn is_required_set(&self) -> bool { + self.is_set(ArgSettings::Required) + } + + pub(crate) fn is_multiple_values_set(&self) -> bool { + self.get_num_args().unwrap_or_default().is_multiple() + } + + pub(crate) fn is_takes_value_set(&self) -> bool { + self.get_action().takes_values() + } + + /// Report whether [`Arg::allow_hyphen_values`] is set + pub fn is_allow_hyphen_values_set(&self) -> bool { + self.is_set(ArgSettings::AllowHyphenValues) + } + + /// Report whether [`Arg::allow_negative_numbers`] is set + pub fn is_allow_negative_numbers_set(&self) -> bool { + self.is_set(ArgSettings::AllowNegativeNumbers) + } + + /// Behavior when parsing the argument + pub fn get_action(&self) -> &super::ArgAction { + const DEFAULT: super::ArgAction = super::ArgAction::Set; + self.action.as_ref().unwrap_or(&DEFAULT) + } + + /// Configured parser for argument values + /// + /// # Example + /// + /// ```rust + /// # use clap_builder as clap; + /// let cmd = clap::Command::new("raw") + /// .arg( + /// clap::Arg::new("port") + /// .value_parser(clap::value_parser!(usize)) + /// ); + /// let value_parser = cmd.get_arguments() + /// .find(|a| a.get_id() == "port").unwrap() + /// .get_value_parser(); + /// println!("{value_parser:?}"); + /// ``` + pub fn get_value_parser(&self) -> &super::ValueParser { + if let Some(value_parser) = self.value_parser.as_ref() { + value_parser + } else { + static DEFAULT: super::ValueParser = super::ValueParser::string(); + &DEFAULT + } + } + + /// Report whether [`Arg::global`] is set + pub fn is_global_set(&self) -> bool { + self.is_set(ArgSettings::Global) + } + + /// Report whether [`Arg::next_line_help`] is set + pub fn is_next_line_help_set(&self) -> bool { + self.is_set(ArgSettings::NextLineHelp) + } + + /// Report whether [`Arg::hide`] is set + pub fn is_hide_set(&self) -> bool { + self.is_set(ArgSettings::Hidden) + } + + /// Report whether [`Arg::hide_default_value`] is set + pub fn is_hide_default_value_set(&self) -> bool { + self.is_set(ArgSettings::HideDefaultValue) + } + + /// Report whether [`Arg::hide_possible_values`] is set + pub fn is_hide_possible_values_set(&self) -> bool { + self.is_set(ArgSettings::HidePossibleValues) + } + + /// Report whether [`Arg::hide_env`] is set + #[cfg(feature = "env")] + pub fn is_hide_env_set(&self) -> bool { + self.is_set(ArgSettings::HideEnv) + } + + /// Report whether [`Arg::hide_env_values`] is set + #[cfg(feature = "env")] + pub fn is_hide_env_values_set(&self) -> bool { + self.is_set(ArgSettings::HideEnvValues) + } + + /// Report whether [`Arg::hide_short_help`] is set + pub fn is_hide_short_help_set(&self) -> bool { + self.is_set(ArgSettings::HiddenShortHelp) + } + + /// Report whether [`Arg::hide_long_help`] is set + pub fn is_hide_long_help_set(&self) -> bool { + self.is_set(ArgSettings::HiddenLongHelp) + } + + /// Report whether [`Arg::require_equals`] is set + pub fn is_require_equals_set(&self) -> bool { + self.is_set(ArgSettings::RequireEquals) + } + + /// Reports whether [`Arg::exclusive`] is set + pub fn is_exclusive_set(&self) -> bool { + self.is_set(ArgSettings::Exclusive) + } + + /// Report whether [`Arg::trailing_var_arg`] is set + pub fn is_trailing_var_arg_set(&self) -> bool { + self.is_set(ArgSettings::TrailingVarArg) + } + + /// Reports whether [`Arg::last`] is set + pub fn is_last_set(&self) -> bool { + self.is_set(ArgSettings::Last) + } + + /// Reports whether [`Arg::ignore_case`] is set + pub fn is_ignore_case_set(&self) -> bool { + self.is_set(ArgSettings::IgnoreCase) + } +} + +/// # Internally used only +impl Arg { + pub(crate) fn _build(&mut self) { + if self.action.is_none() { + if self.num_vals == Some(ValueRange::EMPTY) { + let action = super::ArgAction::SetTrue; + self.action = Some(action); + } else { + let action = + if self.is_positional() && self.num_vals.unwrap_or_default().is_unbounded() { + // Allow collecting arguments interleaved with flags + // + // Bounded values are probably a group and the user should explicitly opt-in to + // Append + super::ArgAction::Append + } else { + super::ArgAction::Set + }; + self.action = Some(action); + } + } + if let Some(action) = self.action.as_ref() { + if let Some(default_value) = action.default_value() { + if self.default_vals.is_empty() { + self.default_vals = vec![default_value.into()]; + } + } + if let Some(default_value) = action.default_missing_value() { + if self.default_missing_vals.is_empty() { + self.default_missing_vals = vec![default_value.into()]; + } + } + } + + if self.value_parser.is_none() { + if let Some(default) = self.action.as_ref().and_then(|a| a.default_value_parser()) { + self.value_parser = Some(default); + } else { + self.value_parser = Some(super::ValueParser::string()); + } + } + + let val_names_len = self.val_names.len(); + if val_names_len > 1 { + self.num_vals.get_or_insert(val_names_len.into()); + } else { + let nargs = if self.get_action().takes_values() { + ValueRange::SINGLE + } else { + ValueRange::EMPTY + }; + self.num_vals.get_or_insert(nargs); + } + } + + // Used for positionals when printing + pub(crate) fn name_no_brackets(&self) -> String { + debug!("Arg::name_no_brackets:{}", self.get_id()); + let delim = " "; + if !self.val_names.is_empty() { + debug!("Arg::name_no_brackets: val_names={:#?}", self.val_names); + + if self.val_names.len() > 1 { + self.val_names + .iter() + .map(|n| format!("<{n}>")) + .collect::<Vec<_>>() + .join(delim) + } else { + self.val_names + .first() + .expect(INTERNAL_ERROR_MSG) + .as_str() + .to_owned() + } + } else { + debug!("Arg::name_no_brackets: just name"); + self.get_id().as_str().to_owned() + } + } + + pub(crate) fn stylized(&self, styles: &Styles, required: Option<bool>) -> StyledStr { + use std::fmt::Write as _; + let literal = styles.get_literal(); + + let mut styled = StyledStr::new(); + // Write the name such --long or -l + if let Some(l) = self.get_long() { + let _ = write!( + styled, + "{}--{l}{}", + literal.render(), + literal.render_reset() + ); + } else if let Some(s) = self.get_short() { + let _ = write!(styled, "{}-{s}{}", literal.render(), literal.render_reset()); + } + styled.push_styled(&self.stylize_arg_suffix(styles, required)); + styled + } + + pub(crate) fn stylize_arg_suffix(&self, styles: &Styles, required: Option<bool>) -> StyledStr { + use std::fmt::Write as _; + let literal = styles.get_literal(); + let placeholder = styles.get_placeholder(); + let mut styled = StyledStr::new(); + + let mut need_closing_bracket = false; + if self.is_takes_value_set() && !self.is_positional() { + let is_optional_val = self.get_min_vals() == 0; + let (style, start) = if self.is_require_equals_set() { + if is_optional_val { + need_closing_bracket = true; + (placeholder, "[=") + } else { + (literal, "=") + } + } else if is_optional_val { + need_closing_bracket = true; + (placeholder, " [") + } else { + (placeholder, " ") + }; + let _ = write!(styled, "{}{start}{}", style.render(), style.render_reset()); + } + if self.is_takes_value_set() || self.is_positional() { + let required = required.unwrap_or_else(|| self.is_required_set()); + let arg_val = self.render_arg_val(required); + let _ = write!( + styled, + "{}{arg_val}{}", + placeholder.render(), + placeholder.render_reset() + ); + } else if matches!(*self.get_action(), ArgAction::Count) { + let _ = write!( + styled, + "{}...{}", + placeholder.render(), + placeholder.render_reset() + ); + } + if need_closing_bracket { + let _ = write!( + styled, + "{}]{}", + placeholder.render(), + placeholder.render_reset() + ); + } + + styled + } + + /// Write the values such as `<name1> <name2>` + fn render_arg_val(&self, required: bool) -> String { + let mut rendered = String::new(); + + let num_vals = self.get_num_args().unwrap_or_else(|| 1.into()); + + let mut val_names = if self.val_names.is_empty() { + vec![self.id.as_internal_str().to_owned()] + } else { + self.val_names.clone() + }; + if val_names.len() == 1 { + let min = num_vals.min_values().max(1); + let val_name = val_names.pop().unwrap(); + val_names = vec![val_name; min]; + } + + debug_assert!(self.is_takes_value_set()); + for (n, val_name) in val_names.iter().enumerate() { + let arg_name = if self.is_positional() && (num_vals.min_values() == 0 || !required) { + format!("[{val_name}]") + } else { + format!("<{val_name}>") + }; + + if n != 0 { + rendered.push(' '); + } + rendered.push_str(&arg_name); + } + + let mut extra_values = false; + extra_values |= val_names.len() < num_vals.max_values(); + if self.is_positional() && matches!(*self.get_action(), ArgAction::Append) { + extra_values = true; + } + if extra_values { + rendered.push_str("..."); + } + + rendered + } + + /// Either multiple values or occurrences + pub(crate) fn is_multiple(&self) -> bool { + self.is_multiple_values_set() || matches!(*self.get_action(), ArgAction::Append) + } + + #[cfg(feature = "help")] + pub(crate) fn get_display_order(&self) -> usize { + self.disp_ord.unwrap_or(999) + } +} + +impl From<&'_ Arg> for Arg { + fn from(a: &Arg) -> Self { + a.clone() + } +} + +impl PartialEq for Arg { + fn eq(&self, other: &Arg) -> bool { + self.get_id() == other.get_id() + } +} + +impl PartialOrd for Arg { + fn partial_cmp(&self, other: &Self) -> Option<Ordering> { + Some(self.cmp(other)) + } +} + +impl Ord for Arg { + fn cmp(&self, other: &Arg) -> Ordering { + self.get_id().cmp(other.get_id()) + } +} + +impl Eq for Arg {} + +impl Display for Arg { + fn fmt(&self, f: &mut Formatter) -> fmt::Result { + let plain = Styles::plain(); + self.stylized(&plain, None).fmt(f) + } +} + +impl fmt::Debug for Arg { + fn fmt(&self, f: &mut Formatter) -> Result<(), fmt::Error> { + let mut ds = f.debug_struct("Arg"); + + #[allow(unused_mut)] + let mut ds = ds + .field("id", &self.id) + .field("help", &self.help) + .field("long_help", &self.long_help) + .field("action", &self.action) + .field("value_parser", &self.value_parser) + .field("blacklist", &self.blacklist) + .field("settings", &self.settings) + .field("overrides", &self.overrides) + .field("groups", &self.groups) + .field("requires", &self.requires) + .field("r_ifs", &self.r_ifs) + .field("r_unless", &self.r_unless) + .field("short", &self.short) + .field("long", &self.long) + .field("aliases", &self.aliases) + .field("short_aliases", &self.short_aliases) + .field("disp_ord", &self.disp_ord) + .field("val_names", &self.val_names) + .field("num_vals", &self.num_vals) + .field("val_delim", &self.val_delim) + .field("default_vals", &self.default_vals) + .field("default_vals_ifs", &self.default_vals_ifs) + .field("terminator", &self.terminator) + .field("index", &self.index) + .field("help_heading", &self.help_heading) + .field("value_hint", &self.value_hint) + .field("default_missing_vals", &self.default_missing_vals); + + #[cfg(feature = "env")] + { + ds = ds.field("env", &self.env); + } + + ds.finish() + } +} + +// Flags +#[cfg(test)] +mod test { + use super::Arg; + use super::ArgAction; + + #[test] + fn flag_display_long() { + let mut f = Arg::new("flg").long("flag").action(ArgAction::SetTrue); + f._build(); + + assert_eq!(f.to_string(), "--flag"); + } + + #[test] + fn flag_display_short() { + let mut f2 = Arg::new("flg").short('f').action(ArgAction::SetTrue); + f2._build(); + + assert_eq!(f2.to_string(), "-f"); + } + + #[test] + fn flag_display_count() { + let mut f2 = Arg::new("flg").long("flag").action(ArgAction::Count); + f2._build(); + + assert_eq!(f2.to_string(), "--flag..."); + } + + #[test] + fn flag_display_single_alias() { + let mut f = Arg::new("flg") + .long("flag") + .visible_alias("als") + .action(ArgAction::SetTrue); + f._build(); + + assert_eq!(f.to_string(), "--flag") + } + + #[test] + fn flag_display_multiple_aliases() { + let mut f = Arg::new("flg").short('f').action(ArgAction::SetTrue); + f.aliases = vec![ + ("alias_not_visible".into(), false), + ("f2".into(), true), + ("f3".into(), true), + ("f4".into(), true), + ]; + f._build(); + + assert_eq!(f.to_string(), "-f"); + } + + #[test] + fn flag_display_single_short_alias() { + let mut f = Arg::new("flg").short('a').action(ArgAction::SetTrue); + f.short_aliases = vec![('b', true)]; + f._build(); + + assert_eq!(f.to_string(), "-a") + } + + #[test] + fn flag_display_multiple_short_aliases() { + let mut f = Arg::new("flg").short('a').action(ArgAction::SetTrue); + f.short_aliases = vec![('b', false), ('c', true), ('d', true), ('e', true)]; + f._build(); + + assert_eq!(f.to_string(), "-a"); + } + + // Options + + #[test] + fn option_display_multiple_occurrences() { + let mut o = Arg::new("opt").long("option").action(ArgAction::Append); + o._build(); + + assert_eq!(o.to_string(), "--option <opt>"); + } + + #[test] + fn option_display_multiple_values() { + let mut o = Arg::new("opt") + .long("option") + .action(ArgAction::Set) + .num_args(1..); + o._build(); + + assert_eq!(o.to_string(), "--option <opt>..."); + } + + #[test] + fn option_display_zero_or_more_values() { + let mut o = Arg::new("opt") + .long("option") + .action(ArgAction::Set) + .num_args(0..); + o._build(); + + assert_eq!(o.to_string(), "--option [<opt>...]"); + } + + #[test] + fn option_display_one_or_more_values() { + let mut o = Arg::new("opt") + .long("option") + .action(ArgAction::Set) + .num_args(1..); + o._build(); + + assert_eq!(o.to_string(), "--option <opt>..."); + } + + #[test] + fn option_display_zero_or_more_values_with_value_name() { + let mut o = Arg::new("opt") + .short('o') + .action(ArgAction::Set) + .num_args(0..) + .value_names(["file"]); + o._build(); + + assert_eq!(o.to_string(), "-o [<file>...]"); + } + + #[test] + fn option_display_one_or_more_values_with_value_name() { + let mut o = Arg::new("opt") + .short('o') + .action(ArgAction::Set) + .num_args(1..) + .value_names(["file"]); + o._build(); + + assert_eq!(o.to_string(), "-o <file>..."); + } + + #[test] + fn option_display_optional_value() { + let mut o = Arg::new("opt") + .long("option") + .action(ArgAction::Set) + .num_args(0..=1); + o._build(); + + assert_eq!(o.to_string(), "--option [<opt>]"); + } + + #[test] + fn option_display_value_names() { + let mut o = Arg::new("opt") + .short('o') + .action(ArgAction::Set) + .value_names(["file", "name"]); + o._build(); + + assert_eq!(o.to_string(), "-o <file> <name>"); + } + + #[test] + fn option_display3() { + let mut o = Arg::new("opt") + .short('o') + .num_args(1..) + .action(ArgAction::Set) + .value_names(["file", "name"]); + o._build(); + + assert_eq!(o.to_string(), "-o <file> <name>..."); + } + + #[test] + fn option_display_single_alias() { + let mut o = Arg::new("opt") + .long("option") + .action(ArgAction::Set) + .visible_alias("als"); + o._build(); + + assert_eq!(o.to_string(), "--option <opt>"); + } + + #[test] + fn option_display_multiple_aliases() { + let mut o = Arg::new("opt") + .long("option") + .action(ArgAction::Set) + .visible_aliases(["als2", "als3", "als4"]) + .alias("als_not_visible"); + o._build(); + + assert_eq!(o.to_string(), "--option <opt>"); + } + + #[test] + fn option_display_single_short_alias() { + let mut o = Arg::new("opt") + .short('a') + .action(ArgAction::Set) + .visible_short_alias('b'); + o._build(); + + assert_eq!(o.to_string(), "-a <opt>"); + } + + #[test] + fn option_display_multiple_short_aliases() { + let mut o = Arg::new("opt") + .short('a') + .action(ArgAction::Set) + .visible_short_aliases(['b', 'c', 'd']) + .short_alias('e'); + o._build(); + + assert_eq!(o.to_string(), "-a <opt>"); + } + + // Positionals + + #[test] + fn positional_display_multiple_values() { + let mut p = Arg::new("pos").index(1).num_args(1..); + p._build(); + + assert_eq!(p.to_string(), "[pos]..."); + } + + #[test] + fn positional_display_multiple_values_required() { + let mut p = Arg::new("pos").index(1).num_args(1..).required(true); + p._build(); + + assert_eq!(p.to_string(), "<pos>..."); + } + + #[test] + fn positional_display_zero_or_more_values() { + let mut p = Arg::new("pos").index(1).num_args(0..); + p._build(); + + assert_eq!(p.to_string(), "[pos]..."); + } + + #[test] + fn positional_display_one_or_more_values() { + let mut p = Arg::new("pos").index(1).num_args(1..); + p._build(); + + assert_eq!(p.to_string(), "[pos]..."); + } + + #[test] + fn positional_display_one_or_more_values_required() { + let mut p = Arg::new("pos").index(1).num_args(1..).required(true); + p._build(); + + assert_eq!(p.to_string(), "<pos>..."); + } + + #[test] + fn positional_display_optional_value() { + let mut p = Arg::new("pos") + .index(1) + .num_args(0..=1) + .action(ArgAction::Set); + p._build(); + + assert_eq!(p.to_string(), "[pos]"); + } + + #[test] + fn positional_display_multiple_occurrences() { + let mut p = Arg::new("pos").index(1).action(ArgAction::Append); + p._build(); + + assert_eq!(p.to_string(), "[pos]..."); + } + + #[test] + fn positional_display_multiple_occurrences_required() { + let mut p = Arg::new("pos") + .index(1) + .action(ArgAction::Append) + .required(true); + p._build(); + + assert_eq!(p.to_string(), "<pos>..."); + } + + #[test] + fn positional_display_required() { + let mut p = Arg::new("pos").index(1).required(true); + p._build(); + + assert_eq!(p.to_string(), "<pos>"); + } + + #[test] + fn positional_display_val_names() { + let mut p = Arg::new("pos").index(1).value_names(["file1", "file2"]); + p._build(); + + assert_eq!(p.to_string(), "[file1] [file2]"); + } + + #[test] + fn positional_display_val_names_required() { + let mut p = Arg::new("pos") + .index(1) + .value_names(["file1", "file2"]) + .required(true); + p._build(); + + assert_eq!(p.to_string(), "<file1> <file2>"); + } +} diff --git a/vendor/clap_builder/src/builder/arg_group.rs b/vendor/clap_builder/src/builder/arg_group.rs new file mode 100644 index 0000000..d3a37c1 --- /dev/null +++ b/vendor/clap_builder/src/builder/arg_group.rs @@ -0,0 +1,611 @@ +// Internal +use crate::builder::IntoResettable; +use crate::util::Id; + +/// Family of related [arguments]. +/// +/// By placing arguments in a logical group, you can create easier requirement and +/// exclusion rules instead of having to list each argument individually, or when you want a rule +/// to apply "any but not all" arguments. +/// +/// For instance, you can make an entire `ArgGroup` required. If [`ArgGroup::multiple(true)`] is +/// set, this means that at least one argument from that group must be present. If +/// [`ArgGroup::multiple(false)`] is set (the default), one and *only* one must be present. +/// +/// You can also do things such as name an entire `ArgGroup` as a [conflict] or [requirement] for +/// another argument, meaning any of the arguments that belong to that group will cause a failure +/// if present, or must be present respectively. +/// +/// Perhaps the most common use of `ArgGroup`s is to require one and *only* one argument to be +/// present out of a given set. Imagine that you had multiple arguments, and you want one of them +/// to be required, but making all of them required isn't feasible because perhaps they conflict +/// with each other. For example, lets say that you were building an application where one could +/// set a given version number by supplying a string with an option argument, i.e. +/// `--set-ver v1.2.3`, you also wanted to support automatically using a previous version number +/// and simply incrementing one of the three numbers. So you create three flags `--major`, +/// `--minor`, and `--patch`. All of these arguments shouldn't be used at one time but you want to +/// specify that *at least one* of them is used. For this, you can create a group. +/// +/// Finally, you may use `ArgGroup`s to pull a value from a group of arguments when you don't care +/// exactly which argument was actually used at runtime. +/// +/// # Examples +/// +/// The following example demonstrates using an `ArgGroup` to ensure that one, and only one, of +/// the arguments from the specified group is present at runtime. +/// +/// ```rust +/// # use clap_builder as clap; +/// # use clap::{Command, arg, ArgGroup, error::ErrorKind}; +/// let result = Command::new("cmd") +/// .arg(arg!(--"set-ver" <ver> "set the version manually")) +/// .arg(arg!(--major "auto increase major")) +/// .arg(arg!(--minor "auto increase minor")) +/// .arg(arg!(--patch "auto increase patch")) +/// .group(ArgGroup::new("vers") +/// .args(["set-ver", "major", "minor", "patch"]) +/// .required(true)) +/// .try_get_matches_from(vec!["cmd", "--major", "--patch"]); +/// // Because we used two args in the group it's an error +/// assert!(result.is_err()); +/// let err = result.unwrap_err(); +/// assert_eq!(err.kind(), ErrorKind::ArgumentConflict); +/// ``` +/// +/// This next example shows a passing parse of the same scenario +/// ```rust +/// # use clap_builder as clap; +/// # use clap::{Command, arg, ArgGroup, Id}; +/// let result = Command::new("cmd") +/// .arg(arg!(--"set-ver" <ver> "set the version manually")) +/// .arg(arg!(--major "auto increase major")) +/// .arg(arg!(--minor "auto increase minor")) +/// .arg(arg!(--patch "auto increase patch")) +/// .group(ArgGroup::new("vers") +/// .args(["set-ver", "major", "minor","patch"]) +/// .required(true)) +/// .try_get_matches_from(vec!["cmd", "--major"]); +/// assert!(result.is_ok()); +/// let matches = result.unwrap(); +/// // We may not know which of the args was used, so we can test for the group... +/// assert!(matches.contains_id("vers")); +/// // We can also ask the group which arg was used +/// assert_eq!(matches +/// .get_one::<Id>("vers") +/// .expect("`vers` is required") +/// .as_str(), +/// "major" +/// ); +/// // we could also alternatively check each arg individually (not shown here) +/// ``` +/// [`ArgGroup::multiple(true)`]: ArgGroup::multiple() +/// +/// [`ArgGroup::multiple(false)`]: ArgGroup::multiple() +/// [arguments]: crate::Arg +/// [conflict]: crate::Arg::conflicts_with() +/// [requirement]: crate::Arg::requires() +#[derive(Default, Clone, Debug, PartialEq, Eq)] +pub struct ArgGroup { + pub(crate) id: Id, + pub(crate) args: Vec<Id>, + pub(crate) required: bool, + pub(crate) requires: Vec<Id>, + pub(crate) conflicts: Vec<Id>, + pub(crate) multiple: bool, +} + +/// # Builder +impl ArgGroup { + /// Create a `ArgGroup` using a unique name. + /// + /// The name will be used to get values from the group or refer to the group inside of conflict + /// and requirement rules. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, ArgGroup}; + /// ArgGroup::new("config") + /// # ; + /// ``` + pub fn new(id: impl Into<Id>) -> Self { + ArgGroup::default().id(id) + } + + /// Sets the group name. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, ArgGroup}; + /// ArgGroup::default().id("config") + /// # ; + /// ``` + #[must_use] + pub fn id(mut self, id: impl Into<Id>) -> Self { + self.id = id.into(); + self + } + + /// Adds an [argument] to this group by name + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgGroup, ArgAction}; + /// let m = Command::new("myprog") + /// .arg(Arg::new("flag") + /// .short('f') + /// .action(ArgAction::SetTrue)) + /// .arg(Arg::new("color") + /// .short('c') + /// .action(ArgAction::SetTrue)) + /// .group(ArgGroup::new("req_flags") + /// .arg("flag") + /// .arg("color")) + /// .get_matches_from(vec!["myprog", "-f"]); + /// // maybe we don't know which of the two flags was used... + /// assert!(m.contains_id("req_flags")); + /// // but we can also check individually if needed + /// assert!(m.contains_id("flag")); + /// ``` + /// [argument]: crate::Arg + #[must_use] + pub fn arg(mut self, arg_id: impl IntoResettable<Id>) -> Self { + if let Some(arg_id) = arg_id.into_resettable().into_option() { + self.args.push(arg_id); + } else { + self.args.clear(); + } + self + } + + /// Adds multiple [arguments] to this group by name + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgGroup, ArgAction}; + /// let m = Command::new("myprog") + /// .arg(Arg::new("flag") + /// .short('f') + /// .action(ArgAction::SetTrue)) + /// .arg(Arg::new("color") + /// .short('c') + /// .action(ArgAction::SetTrue)) + /// .group(ArgGroup::new("req_flags") + /// .args(["flag", "color"])) + /// .get_matches_from(vec!["myprog", "-f"]); + /// // maybe we don't know which of the two flags was used... + /// assert!(m.contains_id("req_flags")); + /// // but we can also check individually if needed + /// assert!(m.contains_id("flag")); + /// ``` + /// [arguments]: crate::Arg + #[must_use] + pub fn args(mut self, ns: impl IntoIterator<Item = impl Into<Id>>) -> Self { + for n in ns { + self = self.arg(n); + } + self + } + + /// Getters for all args. It will return a vector of `Id` + /// + /// # Example + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{ArgGroup}; + /// let args: Vec<&str> = vec!["a1".into(), "a4".into()]; + /// let grp = ArgGroup::new("program").args(&args); + /// + /// for (pos, arg) in grp.get_args().enumerate() { + /// assert_eq!(*arg, args[pos]); + /// } + /// ``` + pub fn get_args(&self) -> impl Iterator<Item = &Id> { + self.args.iter() + } + + /// Allows more than one of the [`Arg`]s in this group to be used. (Default: `false`) + /// + /// # Examples + /// + /// Notice in this example we use *both* the `-f` and `-c` flags which are both part of the + /// group + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgGroup, ArgAction}; + /// let m = Command::new("myprog") + /// .arg(Arg::new("flag") + /// .short('f') + /// .action(ArgAction::SetTrue)) + /// .arg(Arg::new("color") + /// .short('c') + /// .action(ArgAction::SetTrue)) + /// .group(ArgGroup::new("req_flags") + /// .args(["flag", "color"]) + /// .multiple(true)) + /// .get_matches_from(vec!["myprog", "-f", "-c"]); + /// // maybe we don't know which of the two flags was used... + /// assert!(m.contains_id("req_flags")); + /// ``` + /// In this next example, we show the default behavior (i.e. `multiple(false)) which will throw + /// an error if more than one of the args in the group was used. + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgGroup, error::ErrorKind, ArgAction}; + /// let result = Command::new("myprog") + /// .arg(Arg::new("flag") + /// .short('f') + /// .action(ArgAction::SetTrue)) + /// .arg(Arg::new("color") + /// .short('c') + /// .action(ArgAction::SetTrue)) + /// .group(ArgGroup::new("req_flags") + /// .args(["flag", "color"])) + /// .try_get_matches_from(vec!["myprog", "-f", "-c"]); + /// // Because we used both args in the group it's an error + /// assert!(result.is_err()); + /// let err = result.unwrap_err(); + /// assert_eq!(err.kind(), ErrorKind::ArgumentConflict); + /// ``` + /// + /// [`Arg`]: crate::Arg + #[inline] + #[must_use] + pub fn multiple(mut self, yes: bool) -> Self { + self.multiple = yes; + self + } + + /// Return true if the group allows more than one of the arguments + /// in this group to be used. (Default: `false`) + /// + /// # Example + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{ArgGroup}; + /// let mut group = ArgGroup::new("myprog") + /// .args(["f", "c"]) + /// .multiple(true); + /// + /// assert!(group.is_multiple()); + /// ``` + pub fn is_multiple(&mut self) -> bool { + self.multiple + } + + /// Require an argument from the group to be present when parsing. + /// + /// This is unless conflicting with another argument. A required group will be displayed in + /// the usage string of the application in the format `<arg|arg2|arg3>`. + /// + /// **NOTE:** This setting only applies to the current [`Command`] / [`Subcommand`]s, and not + /// globally. + /// + /// **NOTE:** By default, [`ArgGroup::multiple`] is set to `false` which when combined with + /// `ArgGroup::required(true)` states, "One and *only one* arg must be used from this group. + /// Use of more than one arg is an error." Vice setting `ArgGroup::multiple(true)` which + /// states, '*At least* one arg from this group must be used. Using multiple is OK." + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgGroup, error::ErrorKind, ArgAction}; + /// let result = Command::new("myprog") + /// .arg(Arg::new("flag") + /// .short('f') + /// .action(ArgAction::SetTrue)) + /// .arg(Arg::new("color") + /// .short('c') + /// .action(ArgAction::SetTrue)) + /// .group(ArgGroup::new("req_flags") + /// .args(["flag", "color"]) + /// .required(true)) + /// .try_get_matches_from(vec!["myprog"]); + /// // Because we didn't use any of the args in the group, it's an error + /// assert!(result.is_err()); + /// let err = result.unwrap_err(); + /// assert_eq!(err.kind(), ErrorKind::MissingRequiredArgument); + /// ``` + /// + /// [`Subcommand`]: crate::Subcommand + /// [`ArgGroup::multiple`]: ArgGroup::multiple() + /// [`Command`]: crate::Command + #[inline] + #[must_use] + pub fn required(mut self, yes: bool) -> Self { + self.required = yes; + self + } + + /// Specify an argument or group that must be present when this group is. + /// + /// This is not to be confused with a [required group]. Requirement rules function just like + /// [argument requirement rules], you can name other arguments or groups that must be present + /// when any one of the arguments from this group is used. + /// + /// **NOTE:** The name provided may be an argument or group name + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgGroup, error::ErrorKind, ArgAction}; + /// let result = Command::new("myprog") + /// .arg(Arg::new("flag") + /// .short('f') + /// .action(ArgAction::SetTrue)) + /// .arg(Arg::new("color") + /// .short('c') + /// .action(ArgAction::SetTrue)) + /// .arg(Arg::new("debug") + /// .short('d') + /// .action(ArgAction::SetTrue)) + /// .group(ArgGroup::new("req_flags") + /// .args(["flag", "color"]) + /// .requires("debug")) + /// .try_get_matches_from(vec!["myprog", "-c"]); + /// // because we used an arg from the group, and the group requires "-d" to be used, it's an + /// // error + /// assert!(result.is_err()); + /// let err = result.unwrap_err(); + /// assert_eq!(err.kind(), ErrorKind::MissingRequiredArgument); + /// ``` + /// [required group]: ArgGroup::required() + /// [argument requirement rules]: crate::Arg::requires() + #[must_use] + pub fn requires(mut self, id: impl IntoResettable<Id>) -> Self { + if let Some(id) = id.into_resettable().into_option() { + self.requires.push(id); + } else { + self.requires.clear(); + } + self + } + + /// Specify arguments or groups that must be present when this group is. + /// + /// This is not to be confused with a [required group]. Requirement rules function just like + /// [argument requirement rules], you can name other arguments or groups that must be present + /// when one of the arguments from this group is used. + /// + /// **NOTE:** The names provided may be an argument or group name + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgGroup, error::ErrorKind, ArgAction}; + /// let result = Command::new("myprog") + /// .arg(Arg::new("flag") + /// .short('f') + /// .action(ArgAction::SetTrue)) + /// .arg(Arg::new("color") + /// .short('c') + /// .action(ArgAction::SetTrue)) + /// .arg(Arg::new("debug") + /// .short('d') + /// .action(ArgAction::SetTrue)) + /// .arg(Arg::new("verb") + /// .short('v') + /// .action(ArgAction::SetTrue)) + /// .group(ArgGroup::new("req_flags") + /// .args(["flag", "color"]) + /// .requires_all(["debug", "verb"])) + /// .try_get_matches_from(vec!["myprog", "-c", "-d"]); + /// // because we used an arg from the group, and the group requires "-d" and "-v" to be used, + /// // yet we only used "-d" it's an error + /// assert!(result.is_err()); + /// let err = result.unwrap_err(); + /// assert_eq!(err.kind(), ErrorKind::MissingRequiredArgument); + /// ``` + /// [required group]: ArgGroup::required() + /// [argument requirement rules]: crate::Arg::requires_ifs() + #[must_use] + pub fn requires_all(mut self, ns: impl IntoIterator<Item = impl Into<Id>>) -> Self { + for n in ns { + self = self.requires(n); + } + self + } + + /// Specify an argument or group that must **not** be present when this group is. + /// + /// Exclusion (aka conflict) rules function just like [argument exclusion rules], you can name + /// other arguments or groups that must *not* be present when one of the arguments from this + /// group are used. + /// + /// **NOTE:** The name provided may be an argument, or group name + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgGroup, error::ErrorKind, ArgAction}; + /// let result = Command::new("myprog") + /// .arg(Arg::new("flag") + /// .short('f') + /// .action(ArgAction::SetTrue)) + /// .arg(Arg::new("color") + /// .short('c') + /// .action(ArgAction::SetTrue)) + /// .arg(Arg::new("debug") + /// .short('d') + /// .action(ArgAction::SetTrue)) + /// .group(ArgGroup::new("req_flags") + /// .args(["flag", "color"]) + /// .conflicts_with("debug")) + /// .try_get_matches_from(vec!["myprog", "-c", "-d"]); + /// // because we used an arg from the group, and the group conflicts with "-d", it's an error + /// assert!(result.is_err()); + /// let err = result.unwrap_err(); + /// assert_eq!(err.kind(), ErrorKind::ArgumentConflict); + /// ``` + /// [argument exclusion rules]: crate::Arg::conflicts_with() + #[must_use] + pub fn conflicts_with(mut self, id: impl IntoResettable<Id>) -> Self { + if let Some(id) = id.into_resettable().into_option() { + self.conflicts.push(id); + } else { + self.conflicts.clear(); + } + self + } + + /// Specify arguments or groups that must **not** be present when this group is. + /// + /// Exclusion rules function just like [argument exclusion rules], you can name other arguments + /// or groups that must *not* be present when one of the arguments from this group are used. + /// + /// **NOTE:** The names provided may be an argument, or group name + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgGroup, error::ErrorKind, ArgAction}; + /// let result = Command::new("myprog") + /// .arg(Arg::new("flag") + /// .short('f') + /// .action(ArgAction::SetTrue)) + /// .arg(Arg::new("color") + /// .short('c') + /// .action(ArgAction::SetTrue)) + /// .arg(Arg::new("debug") + /// .short('d') + /// .action(ArgAction::SetTrue)) + /// .arg(Arg::new("verb") + /// .short('v') + /// .action(ArgAction::SetTrue)) + /// .group(ArgGroup::new("req_flags") + /// .args(["flag", "color"]) + /// .conflicts_with_all(["debug", "verb"])) + /// .try_get_matches_from(vec!["myprog", "-c", "-v"]); + /// // because we used an arg from the group, and the group conflicts with either "-v" or "-d" + /// // it's an error + /// assert!(result.is_err()); + /// let err = result.unwrap_err(); + /// assert_eq!(err.kind(), ErrorKind::ArgumentConflict); + /// ``` + /// + /// [argument exclusion rules]: crate::Arg::conflicts_with_all() + #[must_use] + pub fn conflicts_with_all(mut self, ns: impl IntoIterator<Item = impl Into<Id>>) -> Self { + for n in ns { + self = self.conflicts_with(n); + } + self + } +} + +/// # Reflection +impl ArgGroup { + /// Get the name of the group + #[inline] + pub fn get_id(&self) -> &Id { + &self.id + } + + /// Reports whether [`ArgGroup::required`] is set + #[inline] + pub fn is_required_set(&self) -> bool { + self.required + } +} + +impl From<&'_ ArgGroup> for ArgGroup { + fn from(g: &ArgGroup) -> Self { + g.clone() + } +} + +#[cfg(test)] +mod test { + use super::*; + + #[test] + fn groups() { + let g = ArgGroup::new("test") + .arg("a1") + .arg("a4") + .args(["a2", "a3"]) + .required(true) + .conflicts_with("c1") + .conflicts_with_all(["c2", "c3"]) + .conflicts_with("c4") + .requires("r1") + .requires_all(["r2", "r3"]) + .requires("r4"); + + let args: Vec<Id> = vec!["a1".into(), "a4".into(), "a2".into(), "a3".into()]; + let reqs: Vec<Id> = vec!["r1".into(), "r2".into(), "r3".into(), "r4".into()]; + let confs: Vec<Id> = vec!["c1".into(), "c2".into(), "c3".into(), "c4".into()]; + + assert_eq!(g.args, args); + assert_eq!(g.requires, reqs); + assert_eq!(g.conflicts, confs); + } + + #[test] + fn test_from() { + let g = ArgGroup::new("test") + .arg("a1") + .arg("a4") + .args(["a2", "a3"]) + .required(true) + .conflicts_with("c1") + .conflicts_with_all(["c2", "c3"]) + .conflicts_with("c4") + .requires("r1") + .requires_all(["r2", "r3"]) + .requires("r4"); + + let args: Vec<Id> = vec!["a1".into(), "a4".into(), "a2".into(), "a3".into()]; + let reqs: Vec<Id> = vec!["r1".into(), "r2".into(), "r3".into(), "r4".into()]; + let confs: Vec<Id> = vec!["c1".into(), "c2".into(), "c3".into(), "c4".into()]; + + let g2 = ArgGroup::from(&g); + assert_eq!(g2.args, args); + assert_eq!(g2.requires, reqs); + assert_eq!(g2.conflicts, confs); + } + + // This test will *fail to compile* if ArgGroup is not Send + Sync + #[test] + fn arg_group_send_sync() { + fn foo<T: Send + Sync>(_: T) {} + foo(ArgGroup::new("test")) + } + + #[test] + fn arg_group_expose_is_multiple_helper() { + let args: Vec<Id> = vec!["a1".into(), "a4".into()]; + + let mut grp_multiple = ArgGroup::new("test_multiple").args(&args).multiple(true); + assert!(grp_multiple.is_multiple()); + + let mut grp_not_multiple = ArgGroup::new("test_multiple").args(&args).multiple(false); + assert!(!grp_not_multiple.is_multiple()); + } + + #[test] + fn arg_group_expose_get_args_helper() { + let args: Vec<Id> = vec!["a1".into(), "a4".into()]; + let grp = ArgGroup::new("program").args(&args); + + for (pos, arg) in grp.get_args().enumerate() { + assert_eq!(*arg, args[pos]); + } + } +} diff --git a/vendor/clap_builder/src/builder/arg_predicate.rs b/vendor/clap_builder/src/builder/arg_predicate.rs new file mode 100644 index 0000000..bc79a11 --- /dev/null +++ b/vendor/clap_builder/src/builder/arg_predicate.rs @@ -0,0 +1,19 @@ +use crate::builder::OsStr; + +/// Operations to perform on argument values +/// +/// These do not apply to [`ValueSource::DefaultValue`][crate::parser::ValueSource::DefaultValue] +#[derive(Clone, Debug, PartialEq, Eq)] +#[cfg_attr(feature = "unstable-v5", non_exhaustive)] +pub enum ArgPredicate { + /// Is the argument present? + IsPresent, + /// Does the argument match the specified value? + Equals(OsStr), +} + +impl<S: Into<OsStr>> From<S> for ArgPredicate { + fn from(other: S) -> Self { + Self::Equals(other.into()) + } +} diff --git a/vendor/clap_builder/src/builder/arg_settings.rs b/vendor/clap_builder/src/builder/arg_settings.rs new file mode 100644 index 0000000..fd47504 --- /dev/null +++ b/vendor/clap_builder/src/builder/arg_settings.rs @@ -0,0 +1,91 @@ +#[allow(unused)] +use crate::Arg; + +#[derive(Default, Copy, Clone, Debug, PartialEq, Eq)] +pub(crate) struct ArgFlags(u32); + +impl ArgFlags { + pub(crate) fn set(&mut self, setting: ArgSettings) { + self.0 |= setting.bit(); + } + + pub(crate) fn unset(&mut self, setting: ArgSettings) { + self.0 &= !setting.bit(); + } + + pub(crate) fn is_set(&self, setting: ArgSettings) -> bool { + self.0 & setting.bit() != 0 + } + + pub(crate) fn insert(&mut self, other: Self) { + self.0 |= other.0; + } +} + +impl std::ops::BitOr for ArgFlags { + type Output = Self; + + fn bitor(mut self, rhs: Self) -> Self::Output { + self.insert(rhs); + self + } +} + +/// Various settings that apply to arguments and may be set, unset, and checked via getter/setter +/// methods [`Arg::setting`], [`Arg::unset_setting`], and [`Arg::is_set`]. This is what the +/// [`Arg`] methods which accept a `bool` use internally. +/// +/// [`Arg`]: crate::Arg +/// [`Arg::setting`]: crate::Arg::setting() +/// [`Arg::unset_setting`]: crate::Arg::unset_setting() +/// [`Arg::is_set`]: crate::Arg::is_set() +#[derive(Debug, PartialEq, Copy, Clone)] +#[repr(u8)] +pub(crate) enum ArgSettings { + Required, + Global, + Hidden, + NextLineHelp, + HidePossibleValues, + AllowHyphenValues, + AllowNegativeNumbers, + RequireEquals, + Last, + TrailingVarArg, + HideDefaultValue, + IgnoreCase, + #[cfg(feature = "env")] + HideEnv, + #[cfg(feature = "env")] + HideEnvValues, + HiddenShortHelp, + HiddenLongHelp, + Exclusive, +} + +impl ArgSettings { + fn bit(self) -> u32 { + 1 << (self as u8) + } +} + +#[cfg(test)] +mod test { + use super::*; + use crate::Arg; + + #[test] + fn setting() { + let m = Arg::new("setting").setting(ArgSettings::Required); + assert!(m.is_required_set()); + } + + #[test] + fn unset_setting() { + let m = Arg::new("unset_setting").setting(ArgSettings::Required); + assert!(m.is_required_set()); + + let m = m.unset_setting(ArgSettings::Required); + assert!(!m.is_required_set(), "{m:#?}"); + } +} diff --git a/vendor/clap_builder/src/builder/command.rs b/vendor/clap_builder/src/builder/command.rs new file mode 100644 index 0000000..6e56b18 --- /dev/null +++ b/vendor/clap_builder/src/builder/command.rs @@ -0,0 +1,4916 @@ +#![cfg_attr(not(feature = "usage"), allow(unused_mut))] + +// Std +use std::env; +use std::ffi::OsString; +use std::fmt; +use std::io; +use std::ops::Index; +use std::path::Path; + +// Internal +use crate::builder::app_settings::{AppFlags, AppSettings}; +use crate::builder::arg_settings::ArgSettings; +use crate::builder::ext::Extensions; +use crate::builder::ArgAction; +use crate::builder::IntoResettable; +use crate::builder::PossibleValue; +use crate::builder::Str; +use crate::builder::StyledStr; +use crate::builder::Styles; +use crate::builder::{Arg, ArgGroup, ArgPredicate}; +use crate::error::ErrorKind; +use crate::error::Result as ClapResult; +use crate::mkeymap::MKeyMap; +use crate::output::fmt::Stream; +use crate::output::{fmt::Colorizer, write_help, Usage}; +use crate::parser::{ArgMatcher, ArgMatches, Parser}; +use crate::util::ChildGraph; +use crate::util::{color::ColorChoice, Id}; +use crate::{Error, INTERNAL_ERROR_MSG}; + +#[cfg(debug_assertions)] +use crate::builder::debug_asserts::assert_app; + +/// Build a command-line interface. +/// +/// This includes defining arguments, subcommands, parser behavior, and help output. +/// Once all configuration is complete, +/// the [`Command::get_matches`] family of methods starts the runtime-parsing +/// process. These methods then return information about the user supplied +/// arguments (or lack thereof). +/// +/// When deriving a [`Parser`][crate::Parser], you can use +/// [`CommandFactory::command`][crate::CommandFactory::command] to access the +/// `Command`. +/// +/// - [Basic API][crate::Command#basic-api] +/// - [Application-wide Settings][crate::Command#application-wide-settings] +/// - [Command-specific Settings][crate::Command#command-specific-settings] +/// - [Subcommand-specific Settings][crate::Command#subcommand-specific-settings] +/// - [Reflection][crate::Command#reflection] +/// +/// # Examples +/// +/// ```no_run +/// # use clap_builder as clap; +/// # use clap::{Command, Arg}; +/// let m = Command::new("My Program") +/// .author("Me, me@mail.com") +/// .version("1.0.2") +/// .about("Explains in brief what the program does") +/// .arg( +/// Arg::new("in_file") +/// ) +/// .after_help("Longer explanation to appear after the options when \ +/// displaying the help information from --help or -h") +/// .get_matches(); +/// +/// // Your program logic starts here... +/// ``` +/// [`Command::get_matches`]: Command::get_matches() +#[derive(Debug, Clone)] +pub struct Command { + name: Str, + long_flag: Option<Str>, + short_flag: Option<char>, + display_name: Option<String>, + bin_name: Option<String>, + author: Option<Str>, + version: Option<Str>, + long_version: Option<Str>, + about: Option<StyledStr>, + long_about: Option<StyledStr>, + before_help: Option<StyledStr>, + before_long_help: Option<StyledStr>, + after_help: Option<StyledStr>, + after_long_help: Option<StyledStr>, + aliases: Vec<(Str, bool)>, // (name, visible) + short_flag_aliases: Vec<(char, bool)>, // (name, visible) + long_flag_aliases: Vec<(Str, bool)>, // (name, visible) + usage_str: Option<StyledStr>, + usage_name: Option<String>, + help_str: Option<StyledStr>, + disp_ord: Option<usize>, + #[cfg(feature = "help")] + template: Option<StyledStr>, + settings: AppFlags, + g_settings: AppFlags, + args: MKeyMap, + subcommands: Vec<Command>, + groups: Vec<ArgGroup>, + current_help_heading: Option<Str>, + current_disp_ord: Option<usize>, + subcommand_value_name: Option<Str>, + subcommand_heading: Option<Str>, + external_value_parser: Option<super::ValueParser>, + long_help_exists: bool, + deferred: Option<fn(Command) -> Command>, + app_ext: Extensions, +} + +/// # Basic API +impl Command { + /// Creates a new instance of an `Command`. + /// + /// It is common, but not required, to use binary name as the `name`. This + /// name will only be displayed to the user when they request to print + /// version or help and usage information. + /// + /// See also [`command!`](crate::command!) and [`crate_name!`](crate::crate_name!). + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::Command; + /// Command::new("My Program") + /// # ; + /// ``` + pub fn new(name: impl Into<Str>) -> Self { + /// The actual implementation of `new`, non-generic to save code size. + /// + /// If we don't do this rustc will unnecessarily generate multiple versions + /// of this code. + fn new_inner(name: Str) -> Command { + Command { + name, + ..Default::default() + } + } + + new_inner(name.into()) + } + + /// Adds an [argument] to the list of valid possibilities. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, arg, Arg}; + /// Command::new("myprog") + /// // Adding a single "flag" argument with a short and help text, using Arg::new() + /// .arg( + /// Arg::new("debug") + /// .short('d') + /// .help("turns on debugging mode") + /// ) + /// // Adding a single "option" argument with a short, a long, and help text using the less + /// // verbose Arg::from() + /// .arg( + /// arg!(-c --config <CONFIG> "Optionally sets a config file to use") + /// ) + /// # ; + /// ``` + /// [argument]: Arg + #[must_use] + pub fn arg(mut self, a: impl Into<Arg>) -> Self { + let arg = a.into(); + self.arg_internal(arg); + self + } + + fn arg_internal(&mut self, mut arg: Arg) { + if let Some(current_disp_ord) = self.current_disp_ord.as_mut() { + if !arg.is_positional() { + let current = *current_disp_ord; + arg.disp_ord.get_or_insert(current); + *current_disp_ord = current + 1; + } + } + + arg.help_heading + .get_or_insert_with(|| self.current_help_heading.clone()); + self.args.push(arg); + } + + /// Adds multiple [arguments] to the list of valid possibilities. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, arg, Arg}; + /// Command::new("myprog") + /// .args([ + /// arg!(-d --debug "turns on debugging info"), + /// Arg::new("input").help("the input file to use") + /// ]) + /// # ; + /// ``` + /// [arguments]: Arg + #[must_use] + pub fn args(mut self, args: impl IntoIterator<Item = impl Into<Arg>>) -> Self { + for arg in args { + self = self.arg(arg); + } + self + } + + /// Allows one to mutate an [`Arg`] after it's been added to a [`Command`]. + /// + /// # Panics + /// + /// If the argument is undefined + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// + /// let mut cmd = Command::new("foo") + /// .arg(Arg::new("bar") + /// .short('b') + /// .action(ArgAction::SetTrue)) + /// .mut_arg("bar", |a| a.short('B')); + /// + /// let res = cmd.try_get_matches_from_mut(vec!["foo", "-b"]); + /// + /// // Since we changed `bar`'s short to "B" this should err as there + /// // is no `-b` anymore, only `-B` + /// + /// assert!(res.is_err()); + /// + /// let res = cmd.try_get_matches_from_mut(vec!["foo", "-B"]); + /// assert!(res.is_ok()); + /// ``` + #[must_use] + #[cfg_attr(debug_assertions, track_caller)] + pub fn mut_arg<F>(mut self, arg_id: impl AsRef<str>, f: F) -> Self + where + F: FnOnce(Arg) -> Arg, + { + let id = arg_id.as_ref(); + let a = self + .args + .remove_by_name(id) + .unwrap_or_else(|| panic!("Argument `{id}` is undefined")); + + self.args.push(f(a)); + self + } + + /// Allows one to mutate all [`Arg`]s after they've been added to a [`Command`]. + /// + /// This does not affect the built-in `--help` or `--version` arguments. + /// + /// # Examples + /// + #[cfg_attr(feature = "string", doc = "```")] + #[cfg_attr(not(feature = "string"), doc = "```ignore")] + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// + /// let mut cmd = Command::new("foo") + /// .arg(Arg::new("bar") + /// .long("bar") + /// .action(ArgAction::SetTrue)) + /// .arg(Arg::new("baz") + /// .long("baz") + /// .action(ArgAction::SetTrue)) + /// .mut_args(|a| { + /// if let Some(l) = a.get_long().map(|l| format!("prefix-{l}")) { + /// a.long(l) + /// } else { + /// a + /// } + /// }); + /// + /// let res = cmd.try_get_matches_from_mut(vec!["foo", "--bar"]); + /// + /// // Since we changed `bar`'s long to "prefix-bar" this should err as there + /// // is no `--bar` anymore, only `--prefix-bar`. + /// + /// assert!(res.is_err()); + /// + /// let res = cmd.try_get_matches_from_mut(vec!["foo", "--prefix-bar"]); + /// assert!(res.is_ok()); + /// ``` + #[must_use] + #[cfg_attr(debug_assertions, track_caller)] + pub fn mut_args<F>(mut self, f: F) -> Self + where + F: FnMut(Arg) -> Arg, + { + self.args.mut_args(f); + self + } + + /// Allows one to mutate an [`ArgGroup`] after it's been added to a [`Command`]. + /// + /// # Panics + /// + /// If the argument is undefined + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, arg, ArgGroup}; + /// + /// Command::new("foo") + /// .arg(arg!(--"set-ver" <ver> "set the version manually").required(false)) + /// .arg(arg!(--major "auto increase major")) + /// .arg(arg!(--minor "auto increase minor")) + /// .arg(arg!(--patch "auto increase patch")) + /// .group(ArgGroup::new("vers") + /// .args(["set-ver", "major", "minor","patch"]) + /// .required(true)) + /// .mut_group("vers", |a| a.required(false)); + /// ``` + #[must_use] + #[cfg_attr(debug_assertions, track_caller)] + pub fn mut_group<F>(mut self, arg_id: impl AsRef<str>, f: F) -> Self + where + F: FnOnce(ArgGroup) -> ArgGroup, + { + let id = arg_id.as_ref(); + let index = self + .groups + .iter() + .position(|g| g.get_id() == id) + .unwrap_or_else(|| panic!("Group `{id}` is undefined")); + let a = self.groups.remove(index); + + self.groups.push(f(a)); + self + } + /// Allows one to mutate a [`Command`] after it's been added as a subcommand. + /// + /// This can be useful for modifying auto-generated arguments of nested subcommands with + /// [`Command::mut_arg`]. + /// + /// # Panics + /// + /// If the subcommand is undefined + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::Command; + /// + /// let mut cmd = Command::new("foo") + /// .subcommand(Command::new("bar")) + /// .mut_subcommand("bar", |subcmd| subcmd.disable_help_flag(true)); + /// + /// let res = cmd.try_get_matches_from_mut(vec!["foo", "bar", "--help"]); + /// + /// // Since we disabled the help flag on the "bar" subcommand, this should err. + /// + /// assert!(res.is_err()); + /// + /// let res = cmd.try_get_matches_from_mut(vec!["foo", "bar"]); + /// assert!(res.is_ok()); + /// ``` + #[must_use] + pub fn mut_subcommand<F>(mut self, name: impl AsRef<str>, f: F) -> Self + where + F: FnOnce(Self) -> Self, + { + let name = name.as_ref(); + let pos = self.subcommands.iter().position(|s| s.name == name); + + let subcmd = if let Some(idx) = pos { + self.subcommands.remove(idx) + } else { + panic!("Command `{name}` is undefined") + }; + + self.subcommands.push(f(subcmd)); + self + } + + /// Adds an [`ArgGroup`] to the application. + /// + /// [`ArgGroup`]s are a family of related arguments. + /// By placing them in a logical group, you can build easier requirement and exclusion rules. + /// + /// Example use cases: + /// - Make an entire [`ArgGroup`] required, meaning that one (and *only* + /// one) argument from that group must be present at runtime. + /// - Name an [`ArgGroup`] as a conflict to another argument. + /// Meaning any of the arguments that belong to that group will cause a failure if present with + /// the conflicting argument. + /// - Ensure exclusion between arguments. + /// - Extract a value from a group instead of determining exactly which argument was used. + /// + /// # Examples + /// + /// The following example demonstrates using an [`ArgGroup`] to ensure that one, and only one, + /// of the arguments from the specified group is present at runtime. + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, arg, ArgGroup}; + /// Command::new("cmd") + /// .arg(arg!(--"set-ver" <ver> "set the version manually").required(false)) + /// .arg(arg!(--major "auto increase major")) + /// .arg(arg!(--minor "auto increase minor")) + /// .arg(arg!(--patch "auto increase patch")) + /// .group(ArgGroup::new("vers") + /// .args(["set-ver", "major", "minor","patch"]) + /// .required(true)) + /// # ; + /// ``` + #[inline] + #[must_use] + pub fn group(mut self, group: impl Into<ArgGroup>) -> Self { + self.groups.push(group.into()); + self + } + + /// Adds multiple [`ArgGroup`]s to the [`Command`] at once. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, arg, ArgGroup}; + /// Command::new("cmd") + /// .arg(arg!(--"set-ver" <ver> "set the version manually").required(false)) + /// .arg(arg!(--major "auto increase major")) + /// .arg(arg!(--minor "auto increase minor")) + /// .arg(arg!(--patch "auto increase patch")) + /// .arg(arg!(-c <FILE> "a config file").required(false)) + /// .arg(arg!(-i <IFACE> "an interface").required(false)) + /// .groups([ + /// ArgGroup::new("vers") + /// .args(["set-ver", "major", "minor","patch"]) + /// .required(true), + /// ArgGroup::new("input") + /// .args(["c", "i"]) + /// ]) + /// # ; + /// ``` + #[must_use] + pub fn groups(mut self, groups: impl IntoIterator<Item = impl Into<ArgGroup>>) -> Self { + for g in groups.into_iter() { + self = self.group(g.into()); + } + self + } + + /// Adds a subcommand to the list of valid possibilities. + /// + /// Subcommands are effectively sub-[`Command`]s, because they can contain their own arguments, + /// subcommands, version, usage, etc. They also function just like [`Command`]s, in that they get + /// their own auto generated help, version, and usage. + /// + /// A subcommand's [`Command::name`] will be used for: + /// - The argument the user passes in + /// - Programmatically looking up the subcommand + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, arg}; + /// Command::new("myprog") + /// .subcommand(Command::new("config") + /// .about("Controls configuration features") + /// .arg(arg!(<config> "Required configuration file to use"))) + /// # ; + /// ``` + #[inline] + #[must_use] + pub fn subcommand(self, subcmd: impl Into<Command>) -> Self { + let subcmd = subcmd.into(); + self.subcommand_internal(subcmd) + } + + fn subcommand_internal(mut self, mut subcmd: Self) -> Self { + if let Some(current_disp_ord) = self.current_disp_ord.as_mut() { + let current = *current_disp_ord; + subcmd.disp_ord.get_or_insert(current); + *current_disp_ord = current + 1; + } + self.subcommands.push(subcmd); + self + } + + /// Adds multiple subcommands to the list of valid possibilities. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, }; + /// # Command::new("myprog") + /// .subcommands( [ + /// Command::new("config").about("Controls configuration functionality") + /// .arg(Arg::new("config_file")), + /// Command::new("debug").about("Controls debug functionality")]) + /// # ; + /// ``` + /// [`IntoIterator`]: std::iter::IntoIterator + #[must_use] + pub fn subcommands(mut self, subcmds: impl IntoIterator<Item = impl Into<Self>>) -> Self { + for subcmd in subcmds { + self = self.subcommand(subcmd); + } + self + } + + /// Delay initialization for parts of the `Command` + /// + /// This is useful for large applications to delay definitions of subcommands until they are + /// being invoked. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, arg}; + /// Command::new("myprog") + /// .subcommand(Command::new("config") + /// .about("Controls configuration features") + /// .defer(|cmd| { + /// cmd.arg(arg!(<config> "Required configuration file to use")) + /// }) + /// ) + /// # ; + /// ``` + pub fn defer(mut self, deferred: fn(Command) -> Command) -> Self { + self.deferred = Some(deferred); + self + } + + /// Catch problems earlier in the development cycle. + /// + /// Most error states are handled as asserts under the assumption they are programming mistake + /// and not something to handle at runtime. Rather than relying on tests (manual or automated) + /// that exhaustively test your CLI to ensure the asserts are evaluated, this will run those + /// asserts in a way convenient for running as a test. + /// + /// **Note::** This will not help with asserts in [`ArgMatches`], those will need exhaustive + /// testing of your CLI. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// fn cmd() -> Command { + /// Command::new("foo") + /// .arg( + /// Arg::new("bar").short('b').action(ArgAction::SetTrue) + /// ) + /// } + /// + /// #[test] + /// fn verify_app() { + /// cmd().debug_assert(); + /// } + /// + /// fn main() { + /// let m = cmd().get_matches_from(vec!["foo", "-b"]); + /// println!("{}", m.get_flag("bar")); + /// } + /// ``` + pub fn debug_assert(mut self) { + self.build(); + } + + /// Custom error message for post-parsing validation + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, error::ErrorKind}; + /// let mut cmd = Command::new("myprog"); + /// let err = cmd.error(ErrorKind::InvalidValue, "Some failure case"); + /// ``` + pub fn error(&mut self, kind: ErrorKind, message: impl std::fmt::Display) -> Error { + Error::raw(kind, message).format(self) + } + + /// Parse [`env::args_os`], exiting on failure. + /// + /// # Panics + /// + /// If contradictory arguments or settings exist (debug builds). + /// + /// # Examples + /// + /// ```no_run + /// # use clap_builder as clap; + /// # use clap::{Command, Arg}; + /// let matches = Command::new("myprog") + /// // Args and options go here... + /// .get_matches(); + /// ``` + /// [`env::args_os`]: std::env::args_os() + /// [`Command::try_get_matches_from_mut`]: Command::try_get_matches_from_mut() + #[inline] + pub fn get_matches(self) -> ArgMatches { + self.get_matches_from(env::args_os()) + } + + /// Parse [`env::args_os`], exiting on failure. + /// + /// Like [`Command::get_matches`] but doesn't consume the `Command`. + /// + /// # Panics + /// + /// If contradictory arguments or settings exist (debug builds). + /// + /// # Examples + /// + /// ```no_run + /// # use clap_builder as clap; + /// # use clap::{Command, Arg}; + /// let mut cmd = Command::new("myprog") + /// // Args and options go here... + /// ; + /// let matches = cmd.get_matches_mut(); + /// ``` + /// [`env::args_os`]: std::env::args_os() + /// [`Command::get_matches`]: Command::get_matches() + pub fn get_matches_mut(&mut self) -> ArgMatches { + self.try_get_matches_from_mut(&mut env::args_os()) + .unwrap_or_else(|e| e.exit()) + } + + /// Parse [`env::args_os`], returning a [`clap::Result`] on failure. + /// + /// **NOTE:** This method WILL NOT exit when `--help` or `--version` (or short versions) are + /// used. It will return a [`clap::Error`], where the [`kind`] is a + /// [`ErrorKind::DisplayHelp`] or [`ErrorKind::DisplayVersion`] respectively. You must call + /// [`Error::exit`] or perform a [`std::process::exit`]. + /// + /// # Panics + /// + /// If contradictory arguments or settings exist (debug builds). + /// + /// # Examples + /// + /// ```no_run + /// # use clap_builder as clap; + /// # use clap::{Command, Arg}; + /// let matches = Command::new("myprog") + /// // Args and options go here... + /// .try_get_matches() + /// .unwrap_or_else(|e| e.exit()); + /// ``` + /// [`env::args_os`]: std::env::args_os() + /// [`Error::exit`]: crate::Error::exit() + /// [`std::process::exit`]: std::process::exit() + /// [`clap::Result`]: Result + /// [`clap::Error`]: crate::Error + /// [`kind`]: crate::Error + /// [`ErrorKind::DisplayHelp`]: crate::error::ErrorKind::DisplayHelp + /// [`ErrorKind::DisplayVersion`]: crate::error::ErrorKind::DisplayVersion + #[inline] + pub fn try_get_matches(self) -> ClapResult<ArgMatches> { + // Start the parsing + self.try_get_matches_from(env::args_os()) + } + + /// Parse the specified arguments, exiting on failure. + /// + /// **NOTE:** The first argument will be parsed as the binary name unless + /// [`Command::no_binary_name`] is used. + /// + /// # Panics + /// + /// If contradictory arguments or settings exist (debug builds). + /// + /// # Examples + /// + /// ```no_run + /// # use clap_builder as clap; + /// # use clap::{Command, Arg}; + /// let arg_vec = vec!["my_prog", "some", "args", "to", "parse"]; + /// + /// let matches = Command::new("myprog") + /// // Args and options go here... + /// .get_matches_from(arg_vec); + /// ``` + /// [`Command::get_matches`]: Command::get_matches() + /// [`clap::Result`]: Result + /// [`Vec`]: std::vec::Vec + pub fn get_matches_from<I, T>(mut self, itr: I) -> ArgMatches + where + I: IntoIterator<Item = T>, + T: Into<OsString> + Clone, + { + self.try_get_matches_from_mut(itr).unwrap_or_else(|e| { + drop(self); + e.exit() + }) + } + + /// Parse the specified arguments, returning a [`clap::Result`] on failure. + /// + /// **NOTE:** This method WILL NOT exit when `--help` or `--version` (or short versions) are + /// used. It will return a [`clap::Error`], where the [`kind`] is a [`ErrorKind::DisplayHelp`] + /// or [`ErrorKind::DisplayVersion`] respectively. You must call [`Error::exit`] or + /// perform a [`std::process::exit`] yourself. + /// + /// **NOTE:** The first argument will be parsed as the binary name unless + /// [`Command::no_binary_name`] is used. + /// + /// # Panics + /// + /// If contradictory arguments or settings exist (debug builds). + /// + /// # Examples + /// + /// ```no_run + /// # use clap_builder as clap; + /// # use clap::{Command, Arg}; + /// let arg_vec = vec!["my_prog", "some", "args", "to", "parse"]; + /// + /// let matches = Command::new("myprog") + /// // Args and options go here... + /// .try_get_matches_from(arg_vec) + /// .unwrap_or_else(|e| e.exit()); + /// ``` + /// [`Command::get_matches_from`]: Command::get_matches_from() + /// [`Command::try_get_matches`]: Command::try_get_matches() + /// [`Error::exit`]: crate::Error::exit() + /// [`std::process::exit`]: std::process::exit() + /// [`clap::Error`]: crate::Error + /// [`Error::exit`]: crate::Error::exit() + /// [`kind`]: crate::Error + /// [`ErrorKind::DisplayHelp`]: crate::error::ErrorKind::DisplayHelp + /// [`ErrorKind::DisplayVersion`]: crate::error::ErrorKind::DisplayVersion + /// [`clap::Result`]: Result + pub fn try_get_matches_from<I, T>(mut self, itr: I) -> ClapResult<ArgMatches> + where + I: IntoIterator<Item = T>, + T: Into<OsString> + Clone, + { + self.try_get_matches_from_mut(itr) + } + + /// Parse the specified arguments, returning a [`clap::Result`] on failure. + /// + /// Like [`Command::try_get_matches_from`] but doesn't consume the `Command`. + /// + /// **NOTE:** This method WILL NOT exit when `--help` or `--version` (or short versions) are + /// used. It will return a [`clap::Error`], where the [`kind`] is a [`ErrorKind::DisplayHelp`] + /// or [`ErrorKind::DisplayVersion`] respectively. You must call [`Error::exit`] or + /// perform a [`std::process::exit`] yourself. + /// + /// **NOTE:** The first argument will be parsed as the binary name unless + /// [`Command::no_binary_name`] is used. + /// + /// # Panics + /// + /// If contradictory arguments or settings exist (debug builds). + /// + /// # Examples + /// + /// ```no_run + /// # use clap_builder as clap; + /// # use clap::{Command, Arg}; + /// let arg_vec = vec!["my_prog", "some", "args", "to", "parse"]; + /// + /// let mut cmd = Command::new("myprog"); + /// // Args and options go here... + /// let matches = cmd.try_get_matches_from_mut(arg_vec) + /// .unwrap_or_else(|e| e.exit()); + /// ``` + /// [`Command::try_get_matches_from`]: Command::try_get_matches_from() + /// [`clap::Result`]: Result + /// [`clap::Error`]: crate::Error + /// [`kind`]: crate::Error + pub fn try_get_matches_from_mut<I, T>(&mut self, itr: I) -> ClapResult<ArgMatches> + where + I: IntoIterator<Item = T>, + T: Into<OsString> + Clone, + { + let mut raw_args = clap_lex::RawArgs::new(itr); + let mut cursor = raw_args.cursor(); + + if self.settings.is_set(AppSettings::Multicall) { + if let Some(argv0) = raw_args.next_os(&mut cursor) { + let argv0 = Path::new(&argv0); + if let Some(command) = argv0.file_stem().and_then(|f| f.to_str()) { + // Stop borrowing command so we can get another mut ref to it. + let command = command.to_owned(); + debug!("Command::try_get_matches_from_mut: Parsed command {command} from argv"); + + debug!("Command::try_get_matches_from_mut: Reinserting command into arguments so subcommand parser matches it"); + raw_args.insert(&cursor, [&command]); + debug!("Command::try_get_matches_from_mut: Clearing name and bin_name so that displayed command name starts with applet name"); + self.name = "".into(); + self.bin_name = None; + return self._do_parse(&mut raw_args, cursor); + } + } + }; + + // Get the name of the program (argument 1 of env::args()) and determine the + // actual file + // that was used to execute the program. This is because a program called + // ./target/release/my_prog -a + // will have two arguments, './target/release/my_prog', '-a' but we don't want + // to display + // the full path when displaying help messages and such + if !self.settings.is_set(AppSettings::NoBinaryName) { + if let Some(name) = raw_args.next_os(&mut cursor) { + let p = Path::new(name); + + if let Some(f) = p.file_name() { + if let Some(s) = f.to_str() { + if self.bin_name.is_none() { + self.bin_name = Some(s.to_owned()); + } + } + } + } + } + + self._do_parse(&mut raw_args, cursor) + } + + /// Prints the short help message (`-h`) to [`io::stdout()`]. + /// + /// See also [`Command::print_long_help`]. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::Command; + /// let mut cmd = Command::new("myprog"); + /// cmd.print_help(); + /// ``` + /// [`io::stdout()`]: std::io::stdout() + pub fn print_help(&mut self) -> io::Result<()> { + self._build_self(false); + let color = self.color_help(); + + let mut styled = StyledStr::new(); + let usage = Usage::new(self); + write_help(&mut styled, self, &usage, false); + + let c = Colorizer::new(Stream::Stdout, color).with_content(styled); + c.print() + } + + /// Prints the long help message (`--help`) to [`io::stdout()`]. + /// + /// See also [`Command::print_help`]. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::Command; + /// let mut cmd = Command::new("myprog"); + /// cmd.print_long_help(); + /// ``` + /// [`io::stdout()`]: std::io::stdout() + /// [`BufWriter`]: std::io::BufWriter + /// [`-h` (short)]: Arg::help() + /// [`--help` (long)]: Arg::long_help() + pub fn print_long_help(&mut self) -> io::Result<()> { + self._build_self(false); + let color = self.color_help(); + + let mut styled = StyledStr::new(); + let usage = Usage::new(self); + write_help(&mut styled, self, &usage, true); + + let c = Colorizer::new(Stream::Stdout, color).with_content(styled); + c.print() + } + + /// Render the short help message (`-h`) to a [`StyledStr`] + /// + /// See also [`Command::render_long_help`]. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::Command; + /// use std::io; + /// let mut cmd = Command::new("myprog"); + /// let mut out = io::stdout(); + /// let help = cmd.render_help(); + /// println!("{help}"); + /// ``` + /// [`io::Write`]: std::io::Write + /// [`-h` (short)]: Arg::help() + /// [`--help` (long)]: Arg::long_help() + pub fn render_help(&mut self) -> StyledStr { + self._build_self(false); + + let mut styled = StyledStr::new(); + let usage = Usage::new(self); + write_help(&mut styled, self, &usage, false); + styled + } + + /// Render the long help message (`--help`) to a [`StyledStr`]. + /// + /// See also [`Command::render_help`]. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::Command; + /// use std::io; + /// let mut cmd = Command::new("myprog"); + /// let mut out = io::stdout(); + /// let help = cmd.render_long_help(); + /// println!("{help}"); + /// ``` + /// [`io::Write`]: std::io::Write + /// [`-h` (short)]: Arg::help() + /// [`--help` (long)]: Arg::long_help() + pub fn render_long_help(&mut self) -> StyledStr { + self._build_self(false); + + let mut styled = StyledStr::new(); + let usage = Usage::new(self); + write_help(&mut styled, self, &usage, true); + styled + } + + #[doc(hidden)] + #[cfg_attr( + feature = "deprecated", + deprecated(since = "4.0.0", note = "Replaced with `Command::render_help`") + )] + pub fn write_help<W: io::Write>(&mut self, w: &mut W) -> io::Result<()> { + self._build_self(false); + + let mut styled = StyledStr::new(); + let usage = Usage::new(self); + write_help(&mut styled, self, &usage, false); + ok!(write!(w, "{styled}")); + w.flush() + } + + #[doc(hidden)] + #[cfg_attr( + feature = "deprecated", + deprecated(since = "4.0.0", note = "Replaced with `Command::render_long_help`") + )] + pub fn write_long_help<W: io::Write>(&mut self, w: &mut W) -> io::Result<()> { + self._build_self(false); + + let mut styled = StyledStr::new(); + let usage = Usage::new(self); + write_help(&mut styled, self, &usage, true); + ok!(write!(w, "{styled}")); + w.flush() + } + + /// Version message rendered as if the user ran `-V`. + /// + /// See also [`Command::render_long_version`]. + /// + /// ### Coloring + /// + /// This function does not try to color the message nor it inserts any [ANSI escape codes]. + /// + /// ### Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::Command; + /// use std::io; + /// let cmd = Command::new("myprog"); + /// println!("{}", cmd.render_version()); + /// ``` + /// [`io::Write`]: std::io::Write + /// [`-V` (short)]: Command::version() + /// [`--version` (long)]: Command::long_version() + /// [ANSI escape codes]: https://en.wikipedia.org/wiki/ANSI_escape_code + pub fn render_version(&self) -> String { + self._render_version(false) + } + + /// Version message rendered as if the user ran `--version`. + /// + /// See also [`Command::render_version`]. + /// + /// ### Coloring + /// + /// This function does not try to color the message nor it inserts any [ANSI escape codes]. + /// + /// ### Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::Command; + /// use std::io; + /// let cmd = Command::new("myprog"); + /// println!("{}", cmd.render_long_version()); + /// ``` + /// [`io::Write`]: std::io::Write + /// [`-V` (short)]: Command::version() + /// [`--version` (long)]: Command::long_version() + /// [ANSI escape codes]: https://en.wikipedia.org/wiki/ANSI_escape_code + pub fn render_long_version(&self) -> String { + self._render_version(true) + } + + /// Usage statement + /// + /// ### Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::Command; + /// use std::io; + /// let mut cmd = Command::new("myprog"); + /// println!("{}", cmd.render_usage()); + /// ``` + pub fn render_usage(&mut self) -> StyledStr { + self.render_usage_().unwrap_or_default() + } + + pub(crate) fn render_usage_(&mut self) -> Option<StyledStr> { + // If there are global arguments, or settings we need to propagate them down to subcommands + // before parsing incase we run into a subcommand + self._build_self(false); + + Usage::new(self).create_usage_with_title(&[]) + } +} + +/// # Application-wide Settings +/// +/// These settings will apply to the top-level command and all subcommands, by default. Some +/// settings can be overridden in subcommands. +impl Command { + /// Specifies that the parser should not assume the first argument passed is the binary name. + /// + /// This is normally the case when using a "daemon" style mode. For shells / REPLs, see + /// [`Command::multicall`][Command::multicall]. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, arg}; + /// let m = Command::new("myprog") + /// .no_binary_name(true) + /// .arg(arg!(<cmd> ... "commands to run")) + /// .get_matches_from(vec!["command", "set"]); + /// + /// let cmds: Vec<_> = m.get_many::<String>("cmd").unwrap().collect(); + /// assert_eq!(cmds, ["command", "set"]); + /// ``` + /// [`try_get_matches_from_mut`]: crate::Command::try_get_matches_from_mut() + #[inline] + pub fn no_binary_name(self, yes: bool) -> Self { + if yes { + self.global_setting(AppSettings::NoBinaryName) + } else { + self.unset_global_setting(AppSettings::NoBinaryName) + } + } + + /// Try not to fail on parse errors, like missing option values. + /// + /// **NOTE:** This choice is propagated to all child subcommands. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, arg}; + /// let cmd = Command::new("cmd") + /// .ignore_errors(true) + /// .arg(arg!(-c --config <FILE> "Sets a custom config file")) + /// .arg(arg!(-x --stuff <FILE> "Sets a custom stuff file")) + /// .arg(arg!(f: -f "Flag")); + /// + /// let r = cmd.try_get_matches_from(vec!["cmd", "-c", "file", "-f", "-x"]); + /// + /// assert!(r.is_ok(), "unexpected error: {r:?}"); + /// let m = r.unwrap(); + /// assert_eq!(m.get_one::<String>("config").unwrap(), "file"); + /// assert!(m.get_flag("f")); + /// assert_eq!(m.get_one::<String>("stuff"), None); + /// ``` + #[inline] + pub fn ignore_errors(self, yes: bool) -> Self { + if yes { + self.global_setting(AppSettings::IgnoreErrors) + } else { + self.unset_global_setting(AppSettings::IgnoreErrors) + } + } + + /// Replace prior occurrences of arguments rather than error + /// + /// For any argument that would conflict with itself by default (e.g. + /// [`ArgAction::Set`], it will now override itself. + /// + /// This is the equivalent to saying the `foo` arg using [`Arg::overrides_with("foo")`] for all + /// defined arguments. + /// + /// **NOTE:** This choice is propagated to all child subcommands. + /// + /// [`Arg::overrides_with("foo")`]: crate::Arg::overrides_with() + #[inline] + pub fn args_override_self(self, yes: bool) -> Self { + if yes { + self.global_setting(AppSettings::AllArgsOverrideSelf) + } else { + self.unset_global_setting(AppSettings::AllArgsOverrideSelf) + } + } + + /// Disables the automatic delimiting of values after `--` or when [`Command::trailing_var_arg`] + /// was used. + /// + /// **NOTE:** The same thing can be done manually by setting the final positional argument to + /// [`Arg::value_delimiter(None)`]. Using this setting is safer, because it's easier to locate + /// when making changes. + /// + /// **NOTE:** This choice is propagated to all child subcommands. + /// + /// # Examples + /// + /// ```no_run + /// # use clap_builder as clap; + /// # use clap::{Command, Arg}; + /// Command::new("myprog") + /// .dont_delimit_trailing_values(true) + /// .get_matches(); + /// ``` + /// + /// [`Arg::value_delimiter(None)`]: crate::Arg::value_delimiter() + #[inline] + pub fn dont_delimit_trailing_values(self, yes: bool) -> Self { + if yes { + self.global_setting(AppSettings::DontDelimitTrailingValues) + } else { + self.unset_global_setting(AppSettings::DontDelimitTrailingValues) + } + } + + /// Sets when to color output. + /// + /// **NOTE:** This choice is propagated to all child subcommands. + /// + /// **NOTE:** Default behaviour is [`ColorChoice::Auto`]. + /// + /// # Examples + /// + /// ```no_run + /// # use clap_builder as clap; + /// # use clap::{Command, ColorChoice}; + /// Command::new("myprog") + /// .color(ColorChoice::Never) + /// .get_matches(); + /// ``` + /// [`ColorChoice::Auto`]: crate::ColorChoice::Auto + #[cfg(feature = "color")] + #[inline] + #[must_use] + pub fn color(self, color: ColorChoice) -> Self { + let cmd = self + .unset_global_setting(AppSettings::ColorAuto) + .unset_global_setting(AppSettings::ColorAlways) + .unset_global_setting(AppSettings::ColorNever); + match color { + ColorChoice::Auto => cmd.global_setting(AppSettings::ColorAuto), + ColorChoice::Always => cmd.global_setting(AppSettings::ColorAlways), + ColorChoice::Never => cmd.global_setting(AppSettings::ColorNever), + } + } + + /// Sets the [`Styles`] for terminal output + /// + /// **NOTE:** This choice is propagated to all child subcommands. + /// + /// **NOTE:** Default behaviour is [`Styles::default`]. + /// + /// # Examples + /// + /// ```no_run + /// # use clap_builder as clap; + /// # use clap::{Command, ColorChoice, builder::styling}; + /// let styles = styling::Styles::styled() + /// .header(styling::AnsiColor::Green.on_default() | styling::Effects::BOLD) + /// .usage(styling::AnsiColor::Green.on_default() | styling::Effects::BOLD) + /// .literal(styling::AnsiColor::Blue.on_default() | styling::Effects::BOLD) + /// .placeholder(styling::AnsiColor::Cyan.on_default()); + /// Command::new("myprog") + /// .styles(styles) + /// .get_matches(); + /// ``` + #[cfg(feature = "color")] + #[inline] + #[must_use] + pub fn styles(mut self, styles: Styles) -> Self { + self.app_ext.set(styles); + self + } + + /// Sets the terminal width at which to wrap help messages. + /// + /// Using `0` will ignore terminal widths and use source formatting. + /// + /// Defaults to current terminal width when `wrap_help` feature flag is enabled. If current + /// width cannot be determined, the default is 100. + /// + /// **`unstable-v5` feature**: Defaults to unbound, being subject to + /// [`Command::max_term_width`]. + /// + /// **NOTE:** This setting applies globally and *not* on a per-command basis. + /// + /// **NOTE:** This requires the `wrap_help` feature + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::Command; + /// Command::new("myprog") + /// .term_width(80) + /// # ; + /// ``` + #[inline] + #[must_use] + #[cfg(any(not(feature = "unstable-v5"), feature = "wrap_help"))] + pub fn term_width(mut self, width: usize) -> Self { + self.app_ext.set(TermWidth(width)); + self + } + + /// Limit the line length for wrapping help when using the current terminal's width. + /// + /// This only applies when [`term_width`][Command::term_width] is unset so that the current + /// terminal's width will be used. See [`Command::term_width`] for more details. + /// + /// Using `0` will ignore this, always respecting [`Command::term_width`] (default). + /// + /// **`unstable-v5` feature**: Defaults to 100. + /// + /// **NOTE:** This setting applies globally and *not* on a per-command basis. + /// + /// **NOTE:** This requires the `wrap_help` feature + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::Command; + /// Command::new("myprog") + /// .max_term_width(100) + /// # ; + /// ``` + #[inline] + #[must_use] + #[cfg(any(not(feature = "unstable-v5"), feature = "wrap_help"))] + pub fn max_term_width(mut self, width: usize) -> Self { + self.app_ext.set(MaxTermWidth(width)); + self + } + + /// Disables `-V` and `--version` flag. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, error::ErrorKind}; + /// let res = Command::new("myprog") + /// .version("1.0.0") + /// .disable_version_flag(true) + /// .try_get_matches_from(vec![ + /// "myprog", "--version" + /// ]); + /// assert!(res.is_err()); + /// assert_eq!(res.unwrap_err().kind(), ErrorKind::UnknownArgument); + /// ``` + /// + /// You can create a custom version flag with [`ArgAction::Version`] + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction, error::ErrorKind}; + /// let mut cmd = Command::new("myprog") + /// .version("1.0.0") + /// // Remove the `-V` short flag + /// .disable_version_flag(true) + /// .arg( + /// Arg::new("version") + /// .long("version") + /// .action(ArgAction::Version) + /// .help("Print version") + /// ); + /// + /// let res = cmd.try_get_matches_from_mut(vec![ + /// "myprog", "-V" + /// ]); + /// assert!(res.is_err()); + /// assert_eq!(res.unwrap_err().kind(), ErrorKind::UnknownArgument); + /// + /// let res = cmd.try_get_matches_from_mut(vec![ + /// "myprog", "--version" + /// ]); + /// assert!(res.is_err()); + /// assert_eq!(res.unwrap_err().kind(), ErrorKind::DisplayVersion); + /// ``` + #[inline] + pub fn disable_version_flag(self, yes: bool) -> Self { + if yes { + self.global_setting(AppSettings::DisableVersionFlag) + } else { + self.unset_global_setting(AppSettings::DisableVersionFlag) + } + } + + /// Specifies to use the version of the current command for all [`subcommands`]. + /// + /// Defaults to `false`; subcommands have independent version strings from their parents. + /// + /// **NOTE:** This choice is propagated to all child subcommands. + /// + /// # Examples + /// + /// ```no_run + /// # use clap_builder as clap; + /// # use clap::{Command, Arg}; + /// Command::new("myprog") + /// .version("v1.1") + /// .propagate_version(true) + /// .subcommand(Command::new("test")) + /// .get_matches(); + /// // running `$ myprog test --version` will display + /// // "myprog-test v1.1" + /// ``` + /// + /// [`subcommands`]: crate::Command::subcommand() + #[inline] + pub fn propagate_version(self, yes: bool) -> Self { + if yes { + self.global_setting(AppSettings::PropagateVersion) + } else { + self.unset_global_setting(AppSettings::PropagateVersion) + } + } + + /// Places the help string for all arguments and subcommands on the line after them. + /// + /// **NOTE:** This choice is propagated to all child subcommands. + /// + /// # Examples + /// + /// ```no_run + /// # use clap_builder as clap; + /// # use clap::{Command, Arg}; + /// Command::new("myprog") + /// .next_line_help(true) + /// .get_matches(); + /// ``` + #[inline] + pub fn next_line_help(self, yes: bool) -> Self { + if yes { + self.global_setting(AppSettings::NextLineHelp) + } else { + self.unset_global_setting(AppSettings::NextLineHelp) + } + } + + /// Disables `-h` and `--help` flag. + /// + /// **NOTE:** This choice is propagated to all child subcommands. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, error::ErrorKind}; + /// let res = Command::new("myprog") + /// .disable_help_flag(true) + /// .try_get_matches_from(vec![ + /// "myprog", "-h" + /// ]); + /// assert!(res.is_err()); + /// assert_eq!(res.unwrap_err().kind(), ErrorKind::UnknownArgument); + /// ``` + /// + /// You can create a custom help flag with [`ArgAction::Help`], [`ArgAction::HelpShort`], or + /// [`ArgAction::HelpLong`] + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction, error::ErrorKind}; + /// let mut cmd = Command::new("myprog") + /// // Change help short flag to `?` + /// .disable_help_flag(true) + /// .arg( + /// Arg::new("help") + /// .short('?') + /// .long("help") + /// .action(ArgAction::Help) + /// .help("Print help") + /// ); + /// + /// let res = cmd.try_get_matches_from_mut(vec![ + /// "myprog", "-h" + /// ]); + /// assert!(res.is_err()); + /// assert_eq!(res.unwrap_err().kind(), ErrorKind::UnknownArgument); + /// + /// let res = cmd.try_get_matches_from_mut(vec![ + /// "myprog", "-?" + /// ]); + /// assert!(res.is_err()); + /// assert_eq!(res.unwrap_err().kind(), ErrorKind::DisplayHelp); + /// ``` + #[inline] + pub fn disable_help_flag(self, yes: bool) -> Self { + if yes { + self.global_setting(AppSettings::DisableHelpFlag) + } else { + self.unset_global_setting(AppSettings::DisableHelpFlag) + } + } + + /// Disables the `help` [`subcommand`]. + /// + /// **NOTE:** This choice is propagated to all child subcommands. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, error::ErrorKind}; + /// let res = Command::new("myprog") + /// .disable_help_subcommand(true) + /// // Normally, creating a subcommand causes a `help` subcommand to automatically + /// // be generated as well + /// .subcommand(Command::new("test")) + /// .try_get_matches_from(vec![ + /// "myprog", "help" + /// ]); + /// assert!(res.is_err()); + /// assert_eq!(res.unwrap_err().kind(), ErrorKind::InvalidSubcommand); + /// ``` + /// + /// [`subcommand`]: crate::Command::subcommand() + #[inline] + pub fn disable_help_subcommand(self, yes: bool) -> Self { + if yes { + self.global_setting(AppSettings::DisableHelpSubcommand) + } else { + self.unset_global_setting(AppSettings::DisableHelpSubcommand) + } + } + + /// Disables colorized help messages. + /// + /// **NOTE:** This choice is propagated to all child subcommands. + /// + /// # Examples + /// + /// ```no_run + /// # use clap_builder as clap; + /// # use clap::Command; + /// Command::new("myprog") + /// .disable_colored_help(true) + /// .get_matches(); + /// ``` + #[inline] + pub fn disable_colored_help(self, yes: bool) -> Self { + if yes { + self.global_setting(AppSettings::DisableColoredHelp) + } else { + self.unset_global_setting(AppSettings::DisableColoredHelp) + } + } + + /// Panic if help descriptions are omitted. + /// + /// **NOTE:** When deriving [`Parser`][crate::Parser], you could instead check this at + /// compile-time with `#![deny(missing_docs)]` + /// + /// **NOTE:** This choice is propagated to all child subcommands. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg}; + /// Command::new("myprog") + /// .help_expected(true) + /// .arg( + /// Arg::new("foo").help("It does foo stuff") + /// // As required via `help_expected`, a help message was supplied + /// ) + /// # .get_matches(); + /// ``` + /// + /// # Panics + /// + /// On debug builds: + /// ```rust,no_run + /// # use clap_builder as clap; + /// # use clap::{Command, Arg}; + /// Command::new("myapp") + /// .help_expected(true) + /// .arg( + /// Arg::new("foo") + /// // Someone forgot to put .about("...") here + /// // Since the setting `help_expected` is activated, this will lead to + /// // a panic (if you are in debug mode) + /// ) + /// # .get_matches(); + ///``` + #[inline] + pub fn help_expected(self, yes: bool) -> Self { + if yes { + self.global_setting(AppSettings::HelpExpected) + } else { + self.unset_global_setting(AppSettings::HelpExpected) + } + } + + #[doc(hidden)] + #[cfg_attr( + feature = "deprecated", + deprecated(since = "4.0.0", note = "This is now the default") + )] + pub fn dont_collapse_args_in_usage(self, _yes: bool) -> Self { + self + } + + /// Tells `clap` *not* to print possible values when displaying help information. + /// + /// This can be useful if there are many values, or they are explained elsewhere. + /// + /// To set this per argument, see + /// [`Arg::hide_possible_values`][crate::Arg::hide_possible_values]. + /// + /// **NOTE:** This choice is propagated to all child subcommands. + #[inline] + pub fn hide_possible_values(self, yes: bool) -> Self { + if yes { + self.global_setting(AppSettings::HidePossibleValues) + } else { + self.unset_global_setting(AppSettings::HidePossibleValues) + } + } + + /// Allow partial matches of long arguments or their [aliases]. + /// + /// For example, to match an argument named `--test`, one could use `--t`, `--te`, `--tes`, and + /// `--test`. + /// + /// **NOTE:** The match *must not* be ambiguous at all in order to succeed. i.e. to match + /// `--te` to `--test` there could not also be another argument or alias `--temp` because both + /// start with `--te` + /// + /// **NOTE:** This choice is propagated to all child subcommands. + /// + /// [aliases]: crate::Command::aliases() + #[inline] + pub fn infer_long_args(self, yes: bool) -> Self { + if yes { + self.global_setting(AppSettings::InferLongArgs) + } else { + self.unset_global_setting(AppSettings::InferLongArgs) + } + } + + /// Allow partial matches of [subcommand] names and their [aliases]. + /// + /// For example, to match a subcommand named `test`, one could use `t`, `te`, `tes`, and + /// `test`. + /// + /// **NOTE:** The match *must not* be ambiguous at all in order to succeed. i.e. to match `te` + /// to `test` there could not also be a subcommand or alias `temp` because both start with `te` + /// + /// **CAUTION:** This setting can interfere with [positional/free arguments], take care when + /// designing CLIs which allow inferred subcommands and have potential positional/free + /// arguments whose values could start with the same characters as subcommands. If this is the + /// case, it's recommended to use settings such as [`Command::args_conflicts_with_subcommands`] in + /// conjunction with this setting. + /// + /// **NOTE:** This choice is propagated to all child subcommands. + /// + /// # Examples + /// + /// ```no_run + /// # use clap_builder as clap; + /// # use clap::{Command, Arg}; + /// let m = Command::new("prog") + /// .infer_subcommands(true) + /// .subcommand(Command::new("test")) + /// .get_matches_from(vec![ + /// "prog", "te" + /// ]); + /// assert_eq!(m.subcommand_name(), Some("test")); + /// ``` + /// + /// [subcommand]: crate::Command::subcommand() + /// [positional/free arguments]: crate::Arg::index() + /// [aliases]: crate::Command::aliases() + #[inline] + pub fn infer_subcommands(self, yes: bool) -> Self { + if yes { + self.global_setting(AppSettings::InferSubcommands) + } else { + self.unset_global_setting(AppSettings::InferSubcommands) + } + } +} + +/// # Command-specific Settings +/// +/// These apply only to the current command and are not inherited by subcommands. +impl Command { + /// (Re)Sets the program's name. + /// + /// See [`Command::new`] for more details. + /// + /// # Examples + /// + /// ```ignore + /// let cmd = clap::command!() + /// .name("foo"); + /// + /// // continued logic goes here, such as `cmd.get_matches()` etc. + /// ``` + #[must_use] + pub fn name(mut self, name: impl Into<Str>) -> Self { + self.name = name.into(); + self + } + + /// Overrides the runtime-determined name of the binary for help and error messages. + /// + /// This should only be used when absolutely necessary, such as when the binary name for your + /// application is misleading, or perhaps *not* how the user should invoke your program. + /// + /// **Pro-tip:** When building things such as third party `cargo` + /// subcommands, this setting **should** be used! + /// + /// **NOTE:** This *does not* change or set the name of the binary file on + /// disk. It only changes what clap thinks the name is for the purposes of + /// error or help messages. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::Command; + /// Command::new("My Program") + /// .bin_name("my_binary") + /// # ; + /// ``` + #[must_use] + pub fn bin_name(mut self, name: impl IntoResettable<String>) -> Self { + self.bin_name = name.into_resettable().into_option(); + self + } + + /// Overrides the runtime-determined display name of the program for help and error messages. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::Command; + /// Command::new("My Program") + /// .display_name("my_program") + /// # ; + /// ``` + #[must_use] + pub fn display_name(mut self, name: impl IntoResettable<String>) -> Self { + self.display_name = name.into_resettable().into_option(); + self + } + + /// Sets the author(s) for the help message. + /// + /// **Pro-tip:** Use `clap`s convenience macro [`crate_authors!`] to + /// automatically set your application's author(s) to the same thing as your + /// crate at compile time. + /// + /// **NOTE:** A custom [`help_template`][Command::help_template] is needed for author to show + /// up. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::Command; + /// Command::new("myprog") + /// .author("Me, me@mymain.com") + /// # ; + /// ``` + #[must_use] + pub fn author(mut self, author: impl IntoResettable<Str>) -> Self { + self.author = author.into_resettable().into_option(); + self + } + + /// Sets the program's description for the short help (`-h`). + /// + /// If [`Command::long_about`] is not specified, this message will be displayed for `--help`. + /// + /// **NOTE:** Only `Command::about` (short format) is used in completion + /// script generation in order to be concise. + /// + /// See also [`crate_description!`](crate::crate_description!). + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::Command; + /// Command::new("myprog") + /// .about("Does really amazing things for great people") + /// # ; + /// ``` + #[must_use] + pub fn about(mut self, about: impl IntoResettable<StyledStr>) -> Self { + self.about = about.into_resettable().into_option(); + self + } + + /// Sets the program's description for the long help (`--help`). + /// + /// If [`Command::about`] is not specified, this message will be displayed for `-h`. + /// + /// **NOTE:** Only [`Command::about`] (short format) is used in completion + /// script generation in order to be concise. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::Command; + /// Command::new("myprog") + /// .long_about( + /// "Does really amazing things to great people. Now let's talk a little + /// more in depth about how this subcommand really works. It may take about + /// a few lines of text, but that's ok!") + /// # ; + /// ``` + /// [`Command::about`]: Command::about() + #[must_use] + pub fn long_about(mut self, long_about: impl IntoResettable<StyledStr>) -> Self { + self.long_about = long_about.into_resettable().into_option(); + self + } + + /// Free-form help text for after auto-generated short help (`-h`). + /// + /// This is often used to describe how to use the arguments, caveats to be noted, or license + /// and contact information. + /// + /// If [`Command::after_long_help`] is not specified, this message will be displayed for `--help`. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::Command; + /// Command::new("myprog") + /// .after_help("Does really amazing things for great people... but be careful with -R!") + /// # ; + /// ``` + /// + #[must_use] + pub fn after_help(mut self, help: impl IntoResettable<StyledStr>) -> Self { + self.after_help = help.into_resettable().into_option(); + self + } + + /// Free-form help text for after auto-generated long help (`--help`). + /// + /// This is often used to describe how to use the arguments, caveats to be noted, or license + /// and contact information. + /// + /// If [`Command::after_help`] is not specified, this message will be displayed for `-h`. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::Command; + /// Command::new("myprog") + /// .after_long_help("Does really amazing things to great people... but be careful with -R, \ + /// like, for real, be careful with this!") + /// # ; + /// ``` + #[must_use] + pub fn after_long_help(mut self, help: impl IntoResettable<StyledStr>) -> Self { + self.after_long_help = help.into_resettable().into_option(); + self + } + + /// Free-form help text for before auto-generated short help (`-h`). + /// + /// This is often used for header, copyright, or license information. + /// + /// If [`Command::before_long_help`] is not specified, this message will be displayed for `--help`. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::Command; + /// Command::new("myprog") + /// .before_help("Some info I'd like to appear before the help info") + /// # ; + /// ``` + #[must_use] + pub fn before_help(mut self, help: impl IntoResettable<StyledStr>) -> Self { + self.before_help = help.into_resettable().into_option(); + self + } + + /// Free-form help text for before auto-generated long help (`--help`). + /// + /// This is often used for header, copyright, or license information. + /// + /// If [`Command::before_help`] is not specified, this message will be displayed for `-h`. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::Command; + /// Command::new("myprog") + /// .before_long_help("Some verbose and long info I'd like to appear before the help info") + /// # ; + /// ``` + #[must_use] + pub fn before_long_help(mut self, help: impl IntoResettable<StyledStr>) -> Self { + self.before_long_help = help.into_resettable().into_option(); + self + } + + /// Sets the version for the short version (`-V`) and help messages. + /// + /// If [`Command::long_version`] is not specified, this message will be displayed for `--version`. + /// + /// **Pro-tip:** Use `clap`s convenience macro [`crate_version!`] to + /// automatically set your application's version to the same thing as your + /// crate at compile time. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::Command; + /// Command::new("myprog") + /// .version("v0.1.24") + /// # ; + /// ``` + #[must_use] + pub fn version(mut self, ver: impl IntoResettable<Str>) -> Self { + self.version = ver.into_resettable().into_option(); + self + } + + /// Sets the version for the long version (`--version`) and help messages. + /// + /// If [`Command::version`] is not specified, this message will be displayed for `-V`. + /// + /// **Pro-tip:** Use `clap`s convenience macro [`crate_version!`] to + /// automatically set your application's version to the same thing as your + /// crate at compile time. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::Command; + /// Command::new("myprog") + /// .long_version( + /// "v0.1.24 + /// commit: abcdef89726d + /// revision: 123 + /// release: 2 + /// binary: myprog") + /// # ; + /// ``` + #[must_use] + pub fn long_version(mut self, ver: impl IntoResettable<Str>) -> Self { + self.long_version = ver.into_resettable().into_option(); + self + } + + /// Overrides the `clap` generated usage string for help and error messages. + /// + /// **NOTE:** Using this setting disables `clap`s "context-aware" usage + /// strings. After this setting is set, this will be *the only* usage string + /// displayed to the user! + /// + /// **NOTE:** Multiple usage lines may be present in the usage argument, but + /// some rules need to be followed to ensure the usage lines are formatted + /// correctly by the default help formatter: + /// + /// - Do not indent the first usage line. + /// - Indent all subsequent usage lines with seven spaces. + /// - The last line must not end with a newline. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg}; + /// Command::new("myprog") + /// .override_usage("myapp [-clDas] <some_file>") + /// # ; + /// ``` + /// + /// Or for multiple usage lines: + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg}; + /// Command::new("myprog") + /// .override_usage( + /// "myapp -X [-a] [-b] <file>\n \ + /// myapp -Y [-c] <file1> <file2>\n \ + /// myapp -Z [-d|-e]" + /// ) + /// # ; + /// ``` + /// + /// [`ArgMatches::usage`]: ArgMatches::usage() + #[must_use] + pub fn override_usage(mut self, usage: impl IntoResettable<StyledStr>) -> Self { + self.usage_str = usage.into_resettable().into_option(); + self + } + + /// Overrides the `clap` generated help message (both `-h` and `--help`). + /// + /// This should only be used when the auto-generated message does not suffice. + /// + /// **NOTE:** This **only** replaces the help message for the current + /// command, meaning if you are using subcommands, those help messages will + /// still be auto-generated unless you specify a [`Command::override_help`] for + /// them as well. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg}; + /// Command::new("myapp") + /// .override_help("myapp v1.0\n\ + /// Does awesome things\n\ + /// (C) me@mail.com\n\n\ + /// + /// Usage: myapp <opts> <command>\n\n\ + /// + /// Options:\n\ + /// -h, --help Display this message\n\ + /// -V, --version Display version info\n\ + /// -s <stuff> Do something with stuff\n\ + /// -v Be verbose\n\n\ + /// + /// Commands:\n\ + /// help Print this message\n\ + /// work Do some work") + /// # ; + /// ``` + #[must_use] + pub fn override_help(mut self, help: impl IntoResettable<StyledStr>) -> Self { + self.help_str = help.into_resettable().into_option(); + self + } + + /// Sets the help template to be used, overriding the default format. + /// + /// **NOTE:** The template system is by design very simple. Therefore, the + /// tags have to be written in the lowercase and without spacing. + /// + /// Tags are given inside curly brackets. + /// + /// Valid tags are: + /// + /// * `{name}` - Display name for the (sub-)command. + /// * `{bin}` - Binary name.(deprecated) + /// * `{version}` - Version number. + /// * `{author}` - Author information. + /// * `{author-with-newline}` - Author followed by `\n`. + /// * `{author-section}` - Author preceded and followed by `\n`. + /// * `{about}` - General description (from [`Command::about`] or + /// [`Command::long_about`]). + /// * `{about-with-newline}` - About followed by `\n`. + /// * `{about-section}` - About preceded and followed by '\n'. + /// * `{usage-heading}` - Automatically generated usage heading. + /// * `{usage}` - Automatically generated or given usage string. + /// * `{all-args}` - Help for all arguments (options, flags, positional + /// arguments, and subcommands) including titles. + /// * `{options}` - Help for options. + /// * `{positionals}` - Help for positional arguments. + /// * `{subcommands}` - Help for subcommands. + /// * `{tab}` - Standard tab sized used within clap + /// * `{after-help}` - Help from [`Command::after_help`] or [`Command::after_long_help`]. + /// * `{before-help}` - Help from [`Command::before_help`] or [`Command::before_long_help`]. + /// + /// # Examples + /// + /// For a very brief help: + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::Command; + /// Command::new("myprog") + /// .version("1.0") + /// .help_template("{name} ({version}) - {usage}") + /// # ; + /// ``` + /// + /// For showing more application context: + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::Command; + /// Command::new("myprog") + /// .version("1.0") + /// .help_template("\ + /// {before-help}{name} {version} + /// {author-with-newline}{about-with-newline} + /// {usage-heading} {usage} + /// + /// {all-args}{after-help} + /// ") + /// # ; + /// ``` + /// [`Command::about`]: Command::about() + /// [`Command::long_about`]: Command::long_about() + /// [`Command::after_help`]: Command::after_help() + /// [`Command::after_long_help`]: Command::after_long_help() + /// [`Command::before_help`]: Command::before_help() + /// [`Command::before_long_help`]: Command::before_long_help() + #[must_use] + #[cfg(feature = "help")] + pub fn help_template(mut self, s: impl IntoResettable<StyledStr>) -> Self { + self.template = s.into_resettable().into_option(); + self + } + + #[inline] + #[must_use] + pub(crate) fn setting(mut self, setting: AppSettings) -> Self { + self.settings.set(setting); + self + } + + #[inline] + #[must_use] + pub(crate) fn unset_setting(mut self, setting: AppSettings) -> Self { + self.settings.unset(setting); + self + } + + #[inline] + #[must_use] + pub(crate) fn global_setting(mut self, setting: AppSettings) -> Self { + self.settings.set(setting); + self.g_settings.set(setting); + self + } + + #[inline] + #[must_use] + pub(crate) fn unset_global_setting(mut self, setting: AppSettings) -> Self { + self.settings.unset(setting); + self.g_settings.unset(setting); + self + } + + /// Flatten subcommand help into the current command's help + /// + /// This shows a summary of subcommands within the usage and help for the current command, similar to + /// `git stash --help` showing information on `push`, `pop`, etc. + /// To see more information, a user can still pass `--help` to the individual subcommands. + #[inline] + #[must_use] + pub fn flatten_help(self, yes: bool) -> Self { + if yes { + self.setting(AppSettings::FlattenHelp) + } else { + self.unset_setting(AppSettings::FlattenHelp) + } + } + + /// 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 `Arguments` headings are + /// not specific enough for one's use case. + /// + /// For subcommands, see [`Command::subcommand_help_heading`] + /// + /// [`Command::arg`]: Command::arg() + /// [`Arg::help_heading`]: crate::Arg::help_heading() + #[inline] + #[must_use] + pub fn next_help_heading(mut self, heading: impl IntoResettable<Str>) -> Self { + self.current_help_heading = heading.into_resettable().into_option(); + self + } + + /// Change the starting value for assigning future display orders for args. + /// + /// This will be used for any arg that hasn't had [`Arg::display_order`] called. + #[inline] + #[must_use] + pub fn next_display_order(mut self, disp_ord: impl IntoResettable<usize>) -> Self { + self.current_disp_ord = disp_ord.into_resettable().into_option(); + self + } + + /// Exit gracefully if no arguments are present (e.g. `$ myprog`). + /// + /// **NOTE:** [`subcommands`] count as arguments + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command}; + /// Command::new("myprog") + /// .arg_required_else_help(true); + /// ``` + /// + /// [`subcommands`]: crate::Command::subcommand() + /// [`Arg::default_value`]: crate::Arg::default_value() + #[inline] + pub fn arg_required_else_help(self, yes: bool) -> Self { + if yes { + self.setting(AppSettings::ArgRequiredElseHelp) + } else { + self.unset_setting(AppSettings::ArgRequiredElseHelp) + } + } + + #[doc(hidden)] + #[cfg_attr( + feature = "deprecated", + deprecated(since = "4.0.0", note = "Replaced with `Arg::allow_hyphen_values`") + )] + pub fn allow_hyphen_values(self, yes: bool) -> Self { + if yes { + self.setting(AppSettings::AllowHyphenValues) + } else { + self.unset_setting(AppSettings::AllowHyphenValues) + } + } + + #[doc(hidden)] + #[cfg_attr( + feature = "deprecated", + deprecated(since = "4.0.0", note = "Replaced with `Arg::allow_negative_numbers`") + )] + pub fn allow_negative_numbers(self, yes: bool) -> Self { + if yes { + self.setting(AppSettings::AllowNegativeNumbers) + } else { + self.unset_setting(AppSettings::AllowNegativeNumbers) + } + } + + #[doc(hidden)] + #[cfg_attr( + feature = "deprecated", + deprecated(since = "4.0.0", note = "Replaced with `Arg::trailing_var_arg`") + )] + pub fn trailing_var_arg(self, yes: bool) -> Self { + if yes { + self.setting(AppSettings::TrailingVarArg) + } else { + self.unset_setting(AppSettings::TrailingVarArg) + } + } + + /// Allows one to implement two styles of CLIs where positionals can be used out of order. + /// + /// The first example is a CLI where the second to last positional argument is optional, but + /// the final positional argument is required. Such as `$ prog [optional] <required>` where one + /// of the two following usages is allowed: + /// + /// * `$ prog [optional] <required>` + /// * `$ prog <required>` + /// + /// This would otherwise not be allowed. This is useful when `[optional]` has a default value. + /// + /// **Note:** when using this style of "missing positionals" the final positional *must* be + /// [required] if `--` will not be used to skip to the final positional argument. + /// + /// **Note:** This style also only allows a single positional argument to be "skipped" without + /// the use of `--`. To skip more than one, see the second example. + /// + /// The second example is when one wants to skip multiple optional positional arguments, and use + /// of the `--` operator is OK (but not required if all arguments will be specified anyways). + /// + /// For example, imagine a CLI which has three positional arguments `[foo] [bar] [baz]...` where + /// `baz` accepts multiple values (similar to man `ARGS...` style training arguments). + /// + /// With this setting the following invocations are posisble: + /// + /// * `$ prog foo bar baz1 baz2 baz3` + /// * `$ prog foo -- baz1 baz2 baz3` + /// * `$ prog -- baz1 baz2 baz3` + /// + /// # Examples + /// + /// Style number one from above: + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg}; + /// // Assume there is an external subcommand named "subcmd" + /// let m = Command::new("myprog") + /// .allow_missing_positional(true) + /// .arg(Arg::new("arg1")) + /// .arg(Arg::new("arg2") + /// .required(true)) + /// .get_matches_from(vec![ + /// "prog", "other" + /// ]); + /// + /// assert_eq!(m.get_one::<String>("arg1"), None); + /// assert_eq!(m.get_one::<String>("arg2").unwrap(), "other"); + /// ``` + /// + /// Now the same example, but using a default value for the first optional positional argument + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg}; + /// // Assume there is an external subcommand named "subcmd" + /// let m = Command::new("myprog") + /// .allow_missing_positional(true) + /// .arg(Arg::new("arg1") + /// .default_value("something")) + /// .arg(Arg::new("arg2") + /// .required(true)) + /// .get_matches_from(vec![ + /// "prog", "other" + /// ]); + /// + /// assert_eq!(m.get_one::<String>("arg1").unwrap(), "something"); + /// assert_eq!(m.get_one::<String>("arg2").unwrap(), "other"); + /// ``` + /// + /// Style number two from above: + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// // Assume there is an external subcommand named "subcmd" + /// let m = Command::new("myprog") + /// .allow_missing_positional(true) + /// .arg(Arg::new("foo")) + /// .arg(Arg::new("bar")) + /// .arg(Arg::new("baz").action(ArgAction::Set).num_args(1..)) + /// .get_matches_from(vec![ + /// "prog", "foo", "bar", "baz1", "baz2", "baz3" + /// ]); + /// + /// assert_eq!(m.get_one::<String>("foo").unwrap(), "foo"); + /// assert_eq!(m.get_one::<String>("bar").unwrap(), "bar"); + /// assert_eq!(m.get_many::<String>("baz").unwrap().collect::<Vec<_>>(), &["baz1", "baz2", "baz3"]); + /// ``` + /// + /// Now nofice if we don't specify `foo` or `baz` but use the `--` operator. + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// // Assume there is an external subcommand named "subcmd" + /// let m = Command::new("myprog") + /// .allow_missing_positional(true) + /// .arg(Arg::new("foo")) + /// .arg(Arg::new("bar")) + /// .arg(Arg::new("baz").action(ArgAction::Set).num_args(1..)) + /// .get_matches_from(vec![ + /// "prog", "--", "baz1", "baz2", "baz3" + /// ]); + /// + /// assert_eq!(m.get_one::<String>("foo"), None); + /// assert_eq!(m.get_one::<String>("bar"), None); + /// assert_eq!(m.get_many::<String>("baz").unwrap().collect::<Vec<_>>(), &["baz1", "baz2", "baz3"]); + /// ``` + /// + /// [required]: crate::Arg::required() + #[inline] + pub fn allow_missing_positional(self, yes: bool) -> Self { + if yes { + self.setting(AppSettings::AllowMissingPositional) + } else { + self.unset_setting(AppSettings::AllowMissingPositional) + } + } +} + +/// # Subcommand-specific Settings +impl Command { + /// Sets the short version of the subcommand flag without the preceding `-`. + /// + /// Allows the subcommand to be used as if it were an [`Arg::short`]. + /// + /// # Examples + /// + /// ``` + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// let matches = Command::new("pacman") + /// .subcommand( + /// Command::new("sync").short_flag('S').arg( + /// Arg::new("search") + /// .short('s') + /// .long("search") + /// .action(ArgAction::SetTrue) + /// .help("search remote repositories for matching strings"), + /// ), + /// ) + /// .get_matches_from(vec!["pacman", "-Ss"]); + /// + /// assert_eq!(matches.subcommand_name().unwrap(), "sync"); + /// let sync_matches = matches.subcommand_matches("sync").unwrap(); + /// assert!(sync_matches.get_flag("search")); + /// ``` + /// [`Arg::short`]: Arg::short() + #[must_use] + pub fn short_flag(mut self, short: impl IntoResettable<char>) -> Self { + self.short_flag = short.into_resettable().into_option(); + self + } + + /// Sets the long version of the subcommand flag without the preceding `--`. + /// + /// Allows the subcommand to be used as if it were an [`Arg::long`]. + /// + /// **NOTE:** Any leading `-` characters will be stripped. + /// + /// # Examples + /// + /// To set `long_flag` use a word containing valid UTF-8 codepoints. If you supply a double leading + /// `--` such as `--sync` they will be stripped. Hyphens in the middle of the word; however, + /// will *not* be stripped (i.e. `sync-file` is allowed). + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// let matches = Command::new("pacman") + /// .subcommand( + /// Command::new("sync").long_flag("sync").arg( + /// Arg::new("search") + /// .short('s') + /// .long("search") + /// .action(ArgAction::SetTrue) + /// .help("search remote repositories for matching strings"), + /// ), + /// ) + /// .get_matches_from(vec!["pacman", "--sync", "--search"]); + /// + /// assert_eq!(matches.subcommand_name().unwrap(), "sync"); + /// let sync_matches = matches.subcommand_matches("sync").unwrap(); + /// assert!(sync_matches.get_flag("search")); + /// ``` + /// + /// [`Arg::long`]: Arg::long() + #[must_use] + pub fn long_flag(mut self, long: impl Into<Str>) -> Self { + self.long_flag = Some(long.into()); + self + } + + /// Sets a hidden alias to this subcommand. + /// + /// This allows the subcommand to be accessed via *either* the original name, or this given + /// alias. This is more efficient and easier than creating multiple hidden subcommands as one + /// only needs to check for the existence of this command, and not all aliased variants. + /// + /// **NOTE:** Aliases defined with this method are *hidden* from the help + /// message. If you're looking for aliases that will be displayed in the help + /// message, see [`Command::visible_alias`]. + /// + /// **NOTE:** When using aliases and checking for the existence of a + /// particular subcommand within an [`ArgMatches`] struct, one only needs to + /// search for the original name and not all aliases. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, }; + /// let m = Command::new("myprog") + /// .subcommand(Command::new("test") + /// .alias("do-stuff")) + /// .get_matches_from(vec!["myprog", "do-stuff"]); + /// assert_eq!(m.subcommand_name(), Some("test")); + /// ``` + /// [`Command::visible_alias`]: Command::visible_alias() + #[must_use] + pub fn alias(mut self, name: impl IntoResettable<Str>) -> Self { + if let Some(name) = name.into_resettable().into_option() { + self.aliases.push((name, false)); + } else { + self.aliases.clear(); + } + self + } + + /// Add an alias, which functions as "hidden" short flag subcommand + /// + /// This will automatically dispatch as if this subcommand was used. This is more efficient, + /// and easier than creating multiple hidden subcommands as one only needs to check for the + /// existence of this command, and not all variants. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, }; + /// let m = Command::new("myprog") + /// .subcommand(Command::new("test").short_flag('t') + /// .short_flag_alias('d')) + /// .get_matches_from(vec!["myprog", "-d"]); + /// assert_eq!(m.subcommand_name(), Some("test")); + /// ``` + #[must_use] + pub fn short_flag_alias(mut self, name: impl IntoResettable<char>) -> Self { + if let Some(name) = name.into_resettable().into_option() { + debug_assert!(name != '-', "short alias name cannot be `-`"); + self.short_flag_aliases.push((name, false)); + } else { + self.short_flag_aliases.clear(); + } + self + } + + /// Add an alias, which functions as a "hidden" long flag subcommand. + /// + /// This will automatically dispatch as if this subcommand was used. This is more efficient, + /// and easier than creating multiple hidden subcommands as one only needs to check for the + /// existence of this command, and not all variants. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, }; + /// let m = Command::new("myprog") + /// .subcommand(Command::new("test").long_flag("test") + /// .long_flag_alias("testing")) + /// .get_matches_from(vec!["myprog", "--testing"]); + /// assert_eq!(m.subcommand_name(), Some("test")); + /// ``` + #[must_use] + pub fn long_flag_alias(mut self, name: impl IntoResettable<Str>) -> Self { + if let Some(name) = name.into_resettable().into_option() { + self.long_flag_aliases.push((name, false)); + } else { + self.long_flag_aliases.clear(); + } + self + } + + /// Sets multiple hidden aliases to this subcommand. + /// + /// This allows the subcommand to be accessed via *either* the original name or any of the + /// given aliases. This is more efficient, and easier than creating multiple hidden subcommands + /// as one only needs to check for the existence of this command and not all aliased variants. + /// + /// **NOTE:** Aliases defined with this method are *hidden* from the help + /// message. If looking for aliases that will be displayed in the help + /// message, see [`Command::visible_aliases`]. + /// + /// **NOTE:** When using aliases and checking for the existence of a + /// particular subcommand within an [`ArgMatches`] struct, one only needs to + /// search for the original name and not all aliases. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg}; + /// let m = Command::new("myprog") + /// .subcommand(Command::new("test") + /// .aliases(["do-stuff", "do-tests", "tests"])) + /// .arg(Arg::new("input") + /// .help("the file to add") + /// .required(false)) + /// .get_matches_from(vec!["myprog", "do-tests"]); + /// assert_eq!(m.subcommand_name(), Some("test")); + /// ``` + /// [`Command::visible_aliases`]: Command::visible_aliases() + #[must_use] + pub fn aliases(mut self, names: impl IntoIterator<Item = impl Into<Str>>) -> Self { + self.aliases + .extend(names.into_iter().map(|n| (n.into(), false))); + self + } + + /// Add aliases, which function as "hidden" short flag subcommands. + /// + /// These will automatically dispatch as if this subcommand was used. This is more efficient, + /// and easier than creating multiple hidden subcommands as one only needs to check for the + /// existence of this command, and not all variants. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, }; + /// let m = Command::new("myprog") + /// .subcommand(Command::new("test").short_flag('t') + /// .short_flag_aliases(['a', 'b', 'c'])) + /// .arg(Arg::new("input") + /// .help("the file to add") + /// .required(false)) + /// .get_matches_from(vec!["myprog", "-a"]); + /// assert_eq!(m.subcommand_name(), Some("test")); + /// ``` + #[must_use] + pub fn short_flag_aliases(mut self, names: impl IntoIterator<Item = char>) -> Self { + for s in names { + debug_assert!(s != '-', "short alias name cannot be `-`"); + self.short_flag_aliases.push((s, false)); + } + self + } + + /// Add aliases, which function as "hidden" long flag subcommands. + /// + /// These will automatically dispatch as if this subcommand was used. This is more efficient, + /// and easier than creating multiple hidden subcommands as one only needs to check for the + /// existence of this command, and not all variants. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, }; + /// let m = Command::new("myprog") + /// .subcommand(Command::new("test").long_flag("test") + /// .long_flag_aliases(["testing", "testall", "test_all"])) + /// .arg(Arg::new("input") + /// .help("the file to add") + /// .required(false)) + /// .get_matches_from(vec!["myprog", "--testing"]); + /// assert_eq!(m.subcommand_name(), Some("test")); + /// ``` + #[must_use] + pub fn long_flag_aliases(mut self, names: impl IntoIterator<Item = impl Into<Str>>) -> Self { + for s in names { + self = self.long_flag_alias(s) + } + self + } + + /// Sets a visible alias to this subcommand. + /// + /// This allows the subcommand to be accessed via *either* the + /// original name or the given alias. This is more efficient and easier + /// than creating hidden subcommands as one only needs to check for + /// the existence of this command and not all aliased variants. + /// + /// **NOTE:** The alias defined with this method is *visible* from the help + /// message and displayed as if it were just another regular subcommand. If + /// looking for an alias that will not be displayed in the help message, see + /// [`Command::alias`]. + /// + /// **NOTE:** When using aliases and checking for the existence of a + /// particular subcommand within an [`ArgMatches`] struct, one only needs to + /// search for the original name and not all aliases. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg}; + /// let m = Command::new("myprog") + /// .subcommand(Command::new("test") + /// .visible_alias("do-stuff")) + /// .get_matches_from(vec!["myprog", "do-stuff"]); + /// assert_eq!(m.subcommand_name(), Some("test")); + /// ``` + /// [`Command::alias`]: Command::alias() + #[must_use] + pub fn visible_alias(mut self, name: impl IntoResettable<Str>) -> Self { + if let Some(name) = name.into_resettable().into_option() { + self.aliases.push((name, true)); + } else { + self.aliases.clear(); + } + self + } + + /// Add an alias, which functions as "visible" short flag subcommand + /// + /// This will automatically dispatch as if this subcommand was used. This is more efficient, + /// and easier than creating multiple hidden subcommands as one only needs to check for the + /// existence of this command, and not all variants. + /// + /// See also [`Command::short_flag_alias`]. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, }; + /// let m = Command::new("myprog") + /// .subcommand(Command::new("test").short_flag('t') + /// .visible_short_flag_alias('d')) + /// .get_matches_from(vec!["myprog", "-d"]); + /// assert_eq!(m.subcommand_name(), Some("test")); + /// ``` + /// [`Command::short_flag_alias`]: Command::short_flag_alias() + #[must_use] + pub fn visible_short_flag_alias(mut self, name: impl IntoResettable<char>) -> Self { + if let Some(name) = name.into_resettable().into_option() { + debug_assert!(name != '-', "short alias name cannot be `-`"); + self.short_flag_aliases.push((name, true)); + } else { + self.short_flag_aliases.clear(); + } + self + } + + /// Add an alias, which functions as a "visible" long flag subcommand. + /// + /// This will automatically dispatch as if this subcommand was used. This is more efficient, + /// and easier than creating multiple hidden subcommands as one only needs to check for the + /// existence of this command, and not all variants. + /// + /// See also [`Command::long_flag_alias`]. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, }; + /// let m = Command::new("myprog") + /// .subcommand(Command::new("test").long_flag("test") + /// .visible_long_flag_alias("testing")) + /// .get_matches_from(vec!["myprog", "--testing"]); + /// assert_eq!(m.subcommand_name(), Some("test")); + /// ``` + /// [`Command::long_flag_alias`]: Command::long_flag_alias() + #[must_use] + pub fn visible_long_flag_alias(mut self, name: impl IntoResettable<Str>) -> Self { + if let Some(name) = name.into_resettable().into_option() { + self.long_flag_aliases.push((name, true)); + } else { + self.long_flag_aliases.clear(); + } + self + } + + /// Sets multiple visible aliases to this subcommand. + /// + /// This allows the subcommand to be accessed via *either* the + /// original name or any of the given aliases. This is more efficient and easier + /// than creating multiple hidden subcommands as one only needs to check for + /// the existence of this command and not all aliased variants. + /// + /// **NOTE:** The alias defined with this method is *visible* from the help + /// message and displayed as if it were just another regular subcommand. If + /// looking for an alias that will not be displayed in the help message, see + /// [`Command::alias`]. + /// + /// **NOTE:** When using aliases, and checking for the existence of a + /// particular subcommand within an [`ArgMatches`] struct, one only needs to + /// search for the original name and not all aliases. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, }; + /// let m = Command::new("myprog") + /// .subcommand(Command::new("test") + /// .visible_aliases(["do-stuff", "tests"])) + /// .get_matches_from(vec!["myprog", "do-stuff"]); + /// assert_eq!(m.subcommand_name(), Some("test")); + /// ``` + /// [`Command::alias`]: Command::alias() + #[must_use] + pub fn visible_aliases(mut self, names: impl IntoIterator<Item = impl Into<Str>>) -> Self { + self.aliases + .extend(names.into_iter().map(|n| (n.into(), true))); + self + } + + /// Add aliases, which function as *visible* short flag subcommands. + /// + /// See [`Command::short_flag_aliases`]. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, }; + /// let m = Command::new("myprog") + /// .subcommand(Command::new("test").short_flag('b') + /// .visible_short_flag_aliases(['t'])) + /// .get_matches_from(vec!["myprog", "-t"]); + /// assert_eq!(m.subcommand_name(), Some("test")); + /// ``` + /// [`Command::short_flag_aliases`]: Command::short_flag_aliases() + #[must_use] + pub fn visible_short_flag_aliases(mut self, names: impl IntoIterator<Item = char>) -> Self { + for s in names { + debug_assert!(s != '-', "short alias name cannot be `-`"); + self.short_flag_aliases.push((s, true)); + } + self + } + + /// Add aliases, which function as *visible* long flag subcommands. + /// + /// See [`Command::long_flag_aliases`]. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, }; + /// let m = Command::new("myprog") + /// .subcommand(Command::new("test").long_flag("test") + /// .visible_long_flag_aliases(["testing", "testall", "test_all"])) + /// .get_matches_from(vec!["myprog", "--testing"]); + /// assert_eq!(m.subcommand_name(), Some("test")); + /// ``` + /// [`Command::long_flag_aliases`]: Command::long_flag_aliases() + #[must_use] + pub fn visible_long_flag_aliases( + mut self, + names: impl IntoIterator<Item = impl Into<Str>>, + ) -> Self { + for s in names { + self = self.visible_long_flag_alias(s); + } + self + } + + /// Set the placement of this subcommand within the help. + /// + /// Subcommands with a lower value will be displayed first in the help message. + /// Those with the same display order will be sorted. + /// + /// `Command`s are automatically assigned a display order based on the order they are added to + /// their parent [`Command`]. + /// Overriding this is helpful when the order commands are added in isn't the same as the + /// display order, whether in one-off cases or to automatically sort commands. + /// + /// # Examples + /// + /// ```rust + /// # #[cfg(feature = "help")] { + /// # use clap_builder as clap; + /// # use clap::{Command, }; + /// let m = Command::new("cust-ord") + /// .subcommand(Command::new("beta") + /// .display_order(0) // Sort + /// .about("Some help and text")) + /// .subcommand(Command::new("alpha") + /// .display_order(0) // Sort + /// .about("I should be first!")) + /// .get_matches_from(vec![ + /// "cust-ord", "--help" + /// ]); + /// # } + /// ``` + /// + /// The above example displays the following help message + /// + /// ```text + /// cust-ord + /// + /// Usage: cust-ord [OPTIONS] + /// + /// Commands: + /// alpha I should be first! + /// beta Some help and text + /// help Print help for the subcommand(s) + /// + /// Options: + /// -h, --help Print help + /// -V, --version Print version + /// ``` + #[inline] + #[must_use] + pub fn display_order(mut self, ord: impl IntoResettable<usize>) -> Self { + self.disp_ord = ord.into_resettable().into_option(); + self + } + + /// Specifies that this [`subcommand`] should be hidden from help messages + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg}; + /// Command::new("myprog") + /// .subcommand( + /// Command::new("test").hide(true) + /// ) + /// # ; + /// ``` + /// + /// [`subcommand`]: crate::Command::subcommand() + #[inline] + pub fn hide(self, yes: bool) -> Self { + if yes { + self.setting(AppSettings::Hidden) + } else { + self.unset_setting(AppSettings::Hidden) + } + } + + /// If no [`subcommand`] is present at runtime, error and exit gracefully. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, error::ErrorKind}; + /// let err = Command::new("myprog") + /// .subcommand_required(true) + /// .subcommand(Command::new("test")) + /// .try_get_matches_from(vec![ + /// "myprog", + /// ]); + /// assert!(err.is_err()); + /// assert_eq!(err.unwrap_err().kind(), ErrorKind::MissingSubcommand); + /// # ; + /// ``` + /// + /// [`subcommand`]: crate::Command::subcommand() + pub fn subcommand_required(self, yes: bool) -> Self { + if yes { + self.setting(AppSettings::SubcommandRequired) + } else { + self.unset_setting(AppSettings::SubcommandRequired) + } + } + + /// Assume unexpected positional arguments are a [`subcommand`]. + /// + /// Arguments will be stored in the `""` argument in the [`ArgMatches`] + /// + /// **NOTE:** Use this setting with caution, + /// as a truly unexpected argument (i.e. one that is *NOT* an external subcommand) + /// will **not** cause an error and instead be treated as a potential subcommand. + /// One should check for such cases manually and inform the user appropriately. + /// + /// **NOTE:** A built-in subcommand will be parsed as an external subcommand when escaped with + /// `--`. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use std::ffi::OsString; + /// # use clap::Command; + /// // Assume there is an external subcommand named "subcmd" + /// let m = Command::new("myprog") + /// .allow_external_subcommands(true) + /// .get_matches_from(vec![ + /// "myprog", "subcmd", "--option", "value", "-fff", "--flag" + /// ]); + /// + /// // All trailing arguments will be stored under the subcommand's sub-matches using an empty + /// // string argument name + /// match m.subcommand() { + /// Some((external, ext_m)) => { + /// let ext_args: Vec<_> = ext_m.get_many::<OsString>("").unwrap().collect(); + /// assert_eq!(external, "subcmd"); + /// assert_eq!(ext_args, ["--option", "value", "-fff", "--flag"]); + /// }, + /// _ => {}, + /// } + /// ``` + /// + /// [`subcommand`]: crate::Command::subcommand() + /// [`ArgMatches`]: crate::ArgMatches + /// [`ErrorKind::UnknownArgument`]: crate::error::ErrorKind::UnknownArgument + pub fn allow_external_subcommands(self, yes: bool) -> Self { + if yes { + self.setting(AppSettings::AllowExternalSubcommands) + } else { + self.unset_setting(AppSettings::AllowExternalSubcommands) + } + } + + /// Specifies how to parse external subcommand arguments. + /// + /// The default parser is for `OsString`. This can be used to switch it to `String` or another + /// type. + /// + /// **NOTE:** Setting this requires [`Command::allow_external_subcommands`] + /// + /// # Examples + /// + /// ```rust + /// # #[cfg(unix)] { + /// # use clap_builder as clap; + /// # use std::ffi::OsString; + /// # use clap::Command; + /// # use clap::value_parser; + /// // Assume there is an external subcommand named "subcmd" + /// let m = Command::new("myprog") + /// .allow_external_subcommands(true) + /// .get_matches_from(vec![ + /// "myprog", "subcmd", "--option", "value", "-fff", "--flag" + /// ]); + /// + /// // All trailing arguments will be stored under the subcommand's sub-matches using an empty + /// // string argument name + /// match m.subcommand() { + /// Some((external, ext_m)) => { + /// let ext_args: Vec<_> = ext_m.get_many::<OsString>("").unwrap().collect(); + /// assert_eq!(external, "subcmd"); + /// assert_eq!(ext_args, ["--option", "value", "-fff", "--flag"]); + /// }, + /// _ => {}, + /// } + /// # } + /// ``` + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::Command; + /// # use clap::value_parser; + /// // Assume there is an external subcommand named "subcmd" + /// let m = Command::new("myprog") + /// .external_subcommand_value_parser(value_parser!(String)) + /// .get_matches_from(vec![ + /// "myprog", "subcmd", "--option", "value", "-fff", "--flag" + /// ]); + /// + /// // All trailing arguments will be stored under the subcommand's sub-matches using an empty + /// // string argument name + /// match m.subcommand() { + /// Some((external, ext_m)) => { + /// let ext_args: Vec<_> = ext_m.get_many::<String>("").unwrap().collect(); + /// assert_eq!(external, "subcmd"); + /// assert_eq!(ext_args, ["--option", "value", "-fff", "--flag"]); + /// }, + /// _ => {}, + /// } + /// ``` + /// + /// [`subcommands`]: crate::Command::subcommand() + pub fn external_subcommand_value_parser( + mut self, + parser: impl IntoResettable<super::ValueParser>, + ) -> Self { + self.external_value_parser = parser.into_resettable().into_option(); + self + } + + /// Specifies that use of an argument prevents the use of [`subcommands`]. + /// + /// By default `clap` allows arguments between subcommands such + /// as `<cmd> [cmd_args] <subcmd> [subcmd_args] <subsubcmd> [subsubcmd_args]`. + /// + /// This setting disables that functionality and says that arguments can + /// only follow the *final* subcommand. For instance using this setting + /// makes only the following invocations possible: + /// + /// * `<cmd> <subcmd> <subsubcmd> [subsubcmd_args]` + /// * `<cmd> <subcmd> [subcmd_args]` + /// * `<cmd> [cmd_args]` + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::Command; + /// Command::new("myprog") + /// .args_conflicts_with_subcommands(true); + /// ``` + /// + /// [`subcommands`]: crate::Command::subcommand() + pub fn args_conflicts_with_subcommands(self, yes: bool) -> Self { + if yes { + self.setting(AppSettings::ArgsNegateSubcommands) + } else { + self.unset_setting(AppSettings::ArgsNegateSubcommands) + } + } + + /// Prevent subcommands from being consumed as an arguments value. + /// + /// By default, if an option taking multiple values is followed by a subcommand, the + /// subcommand will be parsed as another value. + /// + /// ```text + /// cmd --foo val1 val2 subcommand + /// --------- ---------- + /// values another value + /// ``` + /// + /// This setting instructs the parser to stop when encountering a subcommand instead of + /// greedily consuming arguments. + /// + /// ```text + /// cmd --foo val1 val2 subcommand + /// --------- ---------- + /// values subcommand + /// ``` + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// let cmd = Command::new("cmd").subcommand(Command::new("sub")).arg( + /// Arg::new("arg") + /// .long("arg") + /// .num_args(1..) + /// .action(ArgAction::Set), + /// ); + /// + /// let matches = cmd + /// .clone() + /// .try_get_matches_from(&["cmd", "--arg", "1", "2", "3", "sub"]) + /// .unwrap(); + /// assert_eq!( + /// matches.get_many::<String>("arg").unwrap().collect::<Vec<_>>(), + /// &["1", "2", "3", "sub"] + /// ); + /// assert!(matches.subcommand_matches("sub").is_none()); + /// + /// let matches = cmd + /// .subcommand_precedence_over_arg(true) + /// .try_get_matches_from(&["cmd", "--arg", "1", "2", "3", "sub"]) + /// .unwrap(); + /// assert_eq!( + /// matches.get_many::<String>("arg").unwrap().collect::<Vec<_>>(), + /// &["1", "2", "3"] + /// ); + /// assert!(matches.subcommand_matches("sub").is_some()); + /// ``` + pub fn subcommand_precedence_over_arg(self, yes: bool) -> Self { + if yes { + self.setting(AppSettings::SubcommandPrecedenceOverArg) + } else { + self.unset_setting(AppSettings::SubcommandPrecedenceOverArg) + } + } + + /// Allows [`subcommands`] to override all requirements of the parent command. + /// + /// For example, if you had a subcommand or top level application with a required argument + /// that is only required as long as there is no subcommand present, + /// using this setting would allow you to set those arguments to [`Arg::required(true)`] + /// and yet receive no error so long as the user uses a valid subcommand instead. + /// + /// **NOTE:** This defaults to false (using subcommand does *not* negate requirements) + /// + /// # Examples + /// + /// This first example shows that it is an error to not use a required argument + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, error::ErrorKind}; + /// let err = Command::new("myprog") + /// .subcommand_negates_reqs(true) + /// .arg(Arg::new("opt").required(true)) + /// .subcommand(Command::new("test")) + /// .try_get_matches_from(vec![ + /// "myprog" + /// ]); + /// assert!(err.is_err()); + /// assert_eq!(err.unwrap_err().kind(), ErrorKind::MissingRequiredArgument); + /// # ; + /// ``` + /// + /// This next example shows that it is no longer error to not use a required argument if a + /// valid subcommand is used. + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, error::ErrorKind}; + /// let noerr = Command::new("myprog") + /// .subcommand_negates_reqs(true) + /// .arg(Arg::new("opt").required(true)) + /// .subcommand(Command::new("test")) + /// .try_get_matches_from(vec![ + /// "myprog", "test" + /// ]); + /// assert!(noerr.is_ok()); + /// # ; + /// ``` + /// + /// [`Arg::required(true)`]: crate::Arg::required() + /// [`subcommands`]: crate::Command::subcommand() + pub fn subcommand_negates_reqs(self, yes: bool) -> Self { + if yes { + self.setting(AppSettings::SubcommandsNegateReqs) + } else { + self.unset_setting(AppSettings::SubcommandsNegateReqs) + } + } + + /// Multiple-personality program dispatched on the binary name (`argv[0]`) + /// + /// A "multicall" executable is a single executable + /// that contains a variety of applets, + /// and decides which applet to run based on the name of the file. + /// The executable can be called from different names by creating hard links + /// or symbolic links to it. + /// + /// This is desirable for: + /// - Easy distribution, a single binary that can install hardlinks to access the different + /// personalities. + /// - Minimal binary size by sharing common code (e.g. standard library, clap) + /// - Custom shells or REPLs where there isn't a single top-level command + /// + /// Setting `multicall` will cause + /// - `argv[0]` to be stripped to the base name and parsed as the first argument, as if + /// [`Command::no_binary_name`][Command::no_binary_name] was set. + /// - Help and errors to report subcommands as if they were the top-level command + /// + /// When the subcommand is not present, there are several strategies you may employ, depending + /// on your needs: + /// - Let the error percolate up normally + /// - Print a specialized error message using the + /// [`Error::context`][crate::Error::context] + /// - Print the [help][Command::write_help] but this might be ambiguous + /// - Disable `multicall` and re-parse it + /// - Disable `multicall` and re-parse it with a specific subcommand + /// + /// When detecting the error condition, the [`ErrorKind`] isn't sufficient as a sub-subcommand + /// might report the same error. Enable + /// [`allow_external_subcommands`][Command::allow_external_subcommands] if you want to specifically + /// get the unrecognized binary name. + /// + /// **NOTE:** Multicall can't be used with [`no_binary_name`] since they interpret + /// the command name in incompatible ways. + /// + /// **NOTE:** The multicall command cannot have arguments. + /// + /// **NOTE:** Applets are slightly semantically different from subcommands, + /// so it's recommended to use [`Command::subcommand_help_heading`] and + /// [`Command::subcommand_value_name`] to change the descriptive text as above. + /// + /// # Examples + /// + /// `hostname` is an example of a multicall executable. + /// Both `hostname` and `dnsdomainname` are provided by the same executable + /// and which behaviour to use is based on the executable file name. + /// + /// This is desirable when the executable has a primary purpose + /// but there is related functionality that would be convenient to provide + /// and implement it to be in the same executable. + /// + /// The name of the cmd is essentially unused + /// and may be the same as the name of a subcommand. + /// + /// The names of the immediate subcommands of the Command + /// are matched against the basename of the first argument, + /// which is conventionally the path of the executable. + /// + /// This does not allow the subcommand to be passed as the first non-path argument. + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, error::ErrorKind}; + /// let mut cmd = Command::new("hostname") + /// .multicall(true) + /// .subcommand(Command::new("hostname")) + /// .subcommand(Command::new("dnsdomainname")); + /// let m = cmd.try_get_matches_from_mut(&["/usr/bin/hostname", "dnsdomainname"]); + /// assert!(m.is_err()); + /// assert_eq!(m.unwrap_err().kind(), ErrorKind::UnknownArgument); + /// let m = cmd.get_matches_from(&["/usr/bin/dnsdomainname"]); + /// assert_eq!(m.subcommand_name(), Some("dnsdomainname")); + /// ``` + /// + /// Busybox is another common example of a multicall executable + /// with a subcommmand for each applet that can be run directly, + /// e.g. with the `cat` applet being run by running `busybox cat`, + /// or with `cat` as a link to the `busybox` binary. + /// + /// This is desirable when the launcher program has additional options + /// or it is useful to run the applet without installing a symlink + /// e.g. to test the applet without installing it + /// or there may already be a command of that name installed. + /// + /// To make an applet usable as both a multicall link and a subcommand + /// the subcommands must be defined both in the top-level Command + /// and as subcommands of the "main" applet. + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::Command; + /// fn applet_commands() -> [Command; 2] { + /// [Command::new("true"), Command::new("false")] + /// } + /// let mut cmd = Command::new("busybox") + /// .multicall(true) + /// .subcommand( + /// Command::new("busybox") + /// .subcommand_value_name("APPLET") + /// .subcommand_help_heading("APPLETS") + /// .subcommands(applet_commands()), + /// ) + /// .subcommands(applet_commands()); + /// // When called from the executable's canonical name + /// // its applets can be matched as subcommands. + /// let m = cmd.try_get_matches_from_mut(&["/usr/bin/busybox", "true"]).unwrap(); + /// assert_eq!(m.subcommand_name(), Some("busybox")); + /// assert_eq!(m.subcommand().unwrap().1.subcommand_name(), Some("true")); + /// // When called from a link named after an applet that applet is matched. + /// let m = cmd.get_matches_from(&["/usr/bin/true"]); + /// assert_eq!(m.subcommand_name(), Some("true")); + /// ``` + /// + /// [`no_binary_name`]: crate::Command::no_binary_name + /// [`Command::subcommand_value_name`]: crate::Command::subcommand_value_name + /// [`Command::subcommand_help_heading`]: crate::Command::subcommand_help_heading + #[inline] + pub fn multicall(self, yes: bool) -> Self { + if yes { + self.setting(AppSettings::Multicall) + } else { + self.unset_setting(AppSettings::Multicall) + } + } + + /// Sets the value name used for subcommands when printing usage and help. + /// + /// By default, this is "COMMAND". + /// + /// See also [`Command::subcommand_help_heading`] + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg}; + /// Command::new("myprog") + /// .subcommand(Command::new("sub1")) + /// .print_help() + /// # ; + /// ``` + /// + /// will produce + /// + /// ```text + /// myprog + /// + /// Usage: myprog [COMMAND] + /// + /// Commands: + /// help Print this message or the help of the given subcommand(s) + /// sub1 + /// + /// Options: + /// -h, --help Print help + /// -V, --version Print version + /// ``` + /// + /// but usage of `subcommand_value_name` + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg}; + /// Command::new("myprog") + /// .subcommand(Command::new("sub1")) + /// .subcommand_value_name("THING") + /// .print_help() + /// # ; + /// ``` + /// + /// will produce + /// + /// ```text + /// myprog + /// + /// Usage: myprog [THING] + /// + /// Commands: + /// help Print this message or the help of the given subcommand(s) + /// sub1 + /// + /// Options: + /// -h, --help Print help + /// -V, --version Print version + /// ``` + #[must_use] + pub fn subcommand_value_name(mut self, value_name: impl IntoResettable<Str>) -> Self { + self.subcommand_value_name = value_name.into_resettable().into_option(); + self + } + + /// Sets the help heading used for subcommands when printing usage and help. + /// + /// By default, this is "Commands". + /// + /// See also [`Command::subcommand_value_name`] + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg}; + /// Command::new("myprog") + /// .subcommand(Command::new("sub1")) + /// .print_help() + /// # ; + /// ``` + /// + /// will produce + /// + /// ```text + /// myprog + /// + /// Usage: myprog [COMMAND] + /// + /// Commands: + /// help Print this message or the help of the given subcommand(s) + /// sub1 + /// + /// Options: + /// -h, --help Print help + /// -V, --version Print version + /// ``` + /// + /// but usage of `subcommand_help_heading` + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg}; + /// Command::new("myprog") + /// .subcommand(Command::new("sub1")) + /// .subcommand_help_heading("Things") + /// .print_help() + /// # ; + /// ``` + /// + /// will produce + /// + /// ```text + /// myprog + /// + /// Usage: myprog [COMMAND] + /// + /// Things: + /// help Print this message or the help of the given subcommand(s) + /// sub1 + /// + /// Options: + /// -h, --help Print help + /// -V, --version Print version + /// ``` + #[must_use] + pub fn subcommand_help_heading(mut self, heading: impl IntoResettable<Str>) -> Self { + self.subcommand_heading = heading.into_resettable().into_option(); + self + } +} + +/// # Reflection +impl Command { + #[inline] + #[cfg(feature = "usage")] + pub(crate) fn get_usage_name(&self) -> Option<&str> { + self.usage_name.as_deref() + } + + #[inline] + #[cfg(feature = "usage")] + pub(crate) fn get_usage_name_fallback(&self) -> &str { + self.get_usage_name() + .unwrap_or_else(|| self.get_bin_name_fallback()) + } + + #[inline] + #[cfg(not(feature = "usage"))] + #[allow(dead_code)] + pub(crate) fn get_usage_name_fallback(&self) -> &str { + self.get_bin_name_fallback() + } + + /// Get the name of the binary. + #[inline] + pub fn get_display_name(&self) -> Option<&str> { + self.display_name.as_deref() + } + + /// Get the name of the binary. + #[inline] + pub fn get_bin_name(&self) -> Option<&str> { + self.bin_name.as_deref() + } + + /// Get the name of the binary. + #[inline] + pub(crate) fn get_bin_name_fallback(&self) -> &str { + self.bin_name.as_deref().unwrap_or_else(|| self.get_name()) + } + + /// Set binary name. Uses `&mut self` instead of `self`. + pub fn set_bin_name(&mut self, name: impl Into<String>) { + self.bin_name = Some(name.into()); + } + + /// Get the name of the cmd. + #[inline] + pub fn get_name(&self) -> &str { + self.name.as_str() + } + + #[inline] + #[cfg(debug_assertions)] + pub(crate) fn get_name_str(&self) -> &Str { + &self.name + } + + /// Get the version of the cmd. + #[inline] + pub fn get_version(&self) -> Option<&str> { + self.version.as_deref() + } + + /// Get the long version of the cmd. + #[inline] + pub fn get_long_version(&self) -> Option<&str> { + self.long_version.as_deref() + } + + /// Get the authors of the cmd. + #[inline] + pub fn get_author(&self) -> Option<&str> { + self.author.as_deref() + } + + /// Get the short flag of the subcommand. + #[inline] + pub fn get_short_flag(&self) -> Option<char> { + self.short_flag + } + + /// Get the long flag of the subcommand. + #[inline] + pub fn get_long_flag(&self) -> Option<&str> { + self.long_flag.as_deref() + } + + /// Get the help message specified via [`Command::about`]. + /// + /// [`Command::about`]: Command::about() + #[inline] + pub fn get_about(&self) -> Option<&StyledStr> { + self.about.as_ref() + } + + /// Get the help message specified via [`Command::long_about`]. + /// + /// [`Command::long_about`]: Command::long_about() + #[inline] + pub fn get_long_about(&self) -> Option<&StyledStr> { + self.long_about.as_ref() + } + + /// Get the custom section heading specified via [`Command::flatten_help`]. + #[inline] + pub fn is_flatten_help_set(&self) -> bool { + self.is_set(AppSettings::FlattenHelp) + } + + /// Get the custom section heading specified via [`Command::next_help_heading`]. + /// + /// [`Command::help_heading`]: Command::help_heading() + #[inline] + pub fn get_next_help_heading(&self) -> Option<&str> { + self.current_help_heading.as_deref() + } + + /// Iterate through the *visible* aliases for this subcommand. + #[inline] + pub fn get_visible_aliases(&self) -> impl Iterator<Item = &str> + '_ { + self.aliases + .iter() + .filter(|(_, vis)| *vis) + .map(|a| a.0.as_str()) + } + + /// Iterate through the *visible* short aliases for this subcommand. + #[inline] + pub fn get_visible_short_flag_aliases(&self) -> impl Iterator<Item = char> + '_ { + self.short_flag_aliases + .iter() + .filter(|(_, vis)| *vis) + .map(|a| a.0) + } + + /// Iterate through the *visible* long aliases for this subcommand. + #[inline] + pub fn get_visible_long_flag_aliases(&self) -> impl Iterator<Item = &str> + '_ { + self.long_flag_aliases + .iter() + .filter(|(_, vis)| *vis) + .map(|a| a.0.as_str()) + } + + /// Iterate through the set of *all* the aliases for this subcommand, both visible and hidden. + #[inline] + pub fn get_all_aliases(&self) -> impl Iterator<Item = &str> + '_ { + self.aliases.iter().map(|a| a.0.as_str()) + } + + /// Iterate through the set of *all* the short aliases for this subcommand, both visible and hidden. + #[inline] + pub fn get_all_short_flag_aliases(&self) -> impl Iterator<Item = char> + '_ { + self.short_flag_aliases.iter().map(|a| a.0) + } + + /// Iterate through the set of *all* the long aliases for this subcommand, both visible and hidden. + #[inline] + pub fn get_all_long_flag_aliases(&self) -> impl Iterator<Item = &str> + '_ { + self.long_flag_aliases.iter().map(|a| a.0.as_str()) + } + + #[inline] + pub(crate) fn is_set(&self, s: AppSettings) -> bool { + self.settings.is_set(s) || self.g_settings.is_set(s) + } + + /// Should we color the output? + pub fn get_color(&self) -> ColorChoice { + debug!("Command::color: Color setting..."); + + if cfg!(feature = "color") { + if self.is_set(AppSettings::ColorNever) { + debug!("Never"); + ColorChoice::Never + } else if self.is_set(AppSettings::ColorAlways) { + debug!("Always"); + ColorChoice::Always + } else { + debug!("Auto"); + ColorChoice::Auto + } + } else { + ColorChoice::Never + } + } + + /// Return the current `Styles` for the `Command` + #[inline] + pub fn get_styles(&self) -> &Styles { + self.app_ext.get().unwrap_or_default() + } + + /// Iterate through the set of subcommands, getting a reference to each. + #[inline] + pub fn get_subcommands(&self) -> impl Iterator<Item = &Command> { + self.subcommands.iter() + } + + /// Iterate through the set of subcommands, getting a mutable reference to each. + #[inline] + pub fn get_subcommands_mut(&mut self) -> impl Iterator<Item = &mut Command> { + self.subcommands.iter_mut() + } + + /// Returns `true` if this `Command` has subcommands. + #[inline] + pub fn has_subcommands(&self) -> bool { + !self.subcommands.is_empty() + } + + /// Returns the help heading for listing subcommands. + #[inline] + pub fn get_subcommand_help_heading(&self) -> Option<&str> { + self.subcommand_heading.as_deref() + } + + /// Returns the subcommand value name. + #[inline] + pub fn get_subcommand_value_name(&self) -> Option<&str> { + self.subcommand_value_name.as_deref() + } + + /// Returns the help heading for listing subcommands. + #[inline] + pub fn get_before_help(&self) -> Option<&StyledStr> { + self.before_help.as_ref() + } + + /// Returns the help heading for listing subcommands. + #[inline] + pub fn get_before_long_help(&self) -> Option<&StyledStr> { + self.before_long_help.as_ref() + } + + /// Returns the help heading for listing subcommands. + #[inline] + pub fn get_after_help(&self) -> Option<&StyledStr> { + self.after_help.as_ref() + } + + /// Returns the help heading for listing subcommands. + #[inline] + pub fn get_after_long_help(&self) -> Option<&StyledStr> { + self.after_long_help.as_ref() + } + + /// Find subcommand such that its name or one of aliases equals `name`. + /// + /// This does not recurse through subcommands of subcommands. + #[inline] + pub fn find_subcommand(&self, name: impl AsRef<std::ffi::OsStr>) -> Option<&Command> { + let name = name.as_ref(); + self.get_subcommands().find(|s| s.aliases_to(name)) + } + + /// Find subcommand such that its name or one of aliases equals `name`, returning + /// a mutable reference to the subcommand. + /// + /// This does not recurse through subcommands of subcommands. + #[inline] + pub fn find_subcommand_mut( + &mut self, + name: impl AsRef<std::ffi::OsStr>, + ) -> Option<&mut Command> { + let name = name.as_ref(); + self.get_subcommands_mut().find(|s| s.aliases_to(name)) + } + + /// Iterate through the set of groups. + #[inline] + pub fn get_groups(&self) -> impl Iterator<Item = &ArgGroup> { + self.groups.iter() + } + + /// Iterate through the set of arguments. + #[inline] + pub fn get_arguments(&self) -> impl Iterator<Item = &Arg> { + self.args.args() + } + + /// Iterate through the *positionals* arguments. + #[inline] + pub fn get_positionals(&self) -> impl Iterator<Item = &Arg> { + self.get_arguments().filter(|a| a.is_positional()) + } + + /// Iterate through the *options*. + pub fn get_opts(&self) -> impl Iterator<Item = &Arg> { + self.get_arguments() + .filter(|a| a.is_takes_value_set() && !a.is_positional()) + } + + /// Get a list of all arguments the given argument conflicts with. + /// + /// If the provided argument is declared as global, the conflicts will be determined + /// based on the propagation rules of global arguments. + /// + /// ### Panics + /// + /// If the given arg contains a conflict with an argument that is unknown to + /// this `Command`. + pub fn get_arg_conflicts_with(&self, arg: &Arg) -> Vec<&Arg> // FIXME: This could probably have been an iterator + { + if arg.is_global_set() { + self.get_global_arg_conflicts_with(arg) + } else { + let mut result = Vec::new(); + for id in arg.blacklist.iter() { + if let Some(arg) = self.find(id) { + result.push(arg); + } else if let Some(group) = self.find_group(id) { + result.extend( + self.unroll_args_in_group(&group.id) + .iter() + .map(|id| self.find(id).expect(INTERNAL_ERROR_MSG)), + ); + } else { + panic!("Command::get_arg_conflicts_with: The passed arg conflicts with an arg unknown to the cmd"); + } + } + result + } + } + + // Get a unique list of all arguments of all commands and continuous subcommands the given argument conflicts with. + // + // This behavior follows the propagation rules of global arguments. + // It is useful for finding conflicts for arguments declared as global. + // + // ### Panics + // + // If the given arg contains a conflict with an argument that is unknown to + // this `Command`. + fn get_global_arg_conflicts_with(&self, arg: &Arg) -> Vec<&Arg> // FIXME: This could probably have been an iterator + { + arg.blacklist + .iter() + .map(|id| { + self.args + .args() + .chain( + self.get_subcommands_containing(arg) + .iter() + .flat_map(|x| x.args.args()), + ) + .find(|arg| arg.get_id() == id) + .expect( + "Command::get_arg_conflicts_with: \ + The passed arg conflicts with an arg unknown to the cmd", + ) + }) + .collect() + } + + // Get a list of subcommands which contain the provided Argument + // + // This command will only include subcommands in its list for which the subcommands + // parent also contains the Argument. + // + // This search follows the propagation rules of global arguments. + // It is useful to finding subcommands, that have inherited a global argument. + // + // **NOTE:** In this case only Sucommand_1 will be included + // Subcommand_1 (contains Arg) + // Subcommand_1.1 (doesn't contain Arg) + // Subcommand_1.1.1 (contains Arg) + // + fn get_subcommands_containing(&self, arg: &Arg) -> Vec<&Self> { + let mut vec = std::vec::Vec::new(); + for idx in 0..self.subcommands.len() { + if self.subcommands[idx] + .args + .args() + .any(|ar| ar.get_id() == arg.get_id()) + { + vec.push(&self.subcommands[idx]); + vec.append(&mut self.subcommands[idx].get_subcommands_containing(arg)); + } + } + vec + } + + /// Report whether [`Command::no_binary_name`] is set + pub fn is_no_binary_name_set(&self) -> bool { + self.is_set(AppSettings::NoBinaryName) + } + + /// Report whether [`Command::ignore_errors`] is set + pub(crate) fn is_ignore_errors_set(&self) -> bool { + self.is_set(AppSettings::IgnoreErrors) + } + + /// Report whether [`Command::dont_delimit_trailing_values`] is set + pub fn is_dont_delimit_trailing_values_set(&self) -> bool { + self.is_set(AppSettings::DontDelimitTrailingValues) + } + + /// Report whether [`Command::disable_version_flag`] is set + pub fn is_disable_version_flag_set(&self) -> bool { + self.is_set(AppSettings::DisableVersionFlag) + || (self.version.is_none() && self.long_version.is_none()) + } + + /// Report whether [`Command::propagate_version`] is set + pub fn is_propagate_version_set(&self) -> bool { + self.is_set(AppSettings::PropagateVersion) + } + + /// Report whether [`Command::next_line_help`] is set + pub fn is_next_line_help_set(&self) -> bool { + self.is_set(AppSettings::NextLineHelp) + } + + /// Report whether [`Command::disable_help_flag`] is set + pub fn is_disable_help_flag_set(&self) -> bool { + self.is_set(AppSettings::DisableHelpFlag) + } + + /// Report whether [`Command::disable_help_subcommand`] is set + pub fn is_disable_help_subcommand_set(&self) -> bool { + self.is_set(AppSettings::DisableHelpSubcommand) + } + + /// Report whether [`Command::disable_colored_help`] is set + pub fn is_disable_colored_help_set(&self) -> bool { + self.is_set(AppSettings::DisableColoredHelp) + } + + /// Report whether [`Command::help_expected`] is set + #[cfg(debug_assertions)] + pub(crate) fn is_help_expected_set(&self) -> bool { + self.is_set(AppSettings::HelpExpected) + } + + #[doc(hidden)] + #[cfg_attr( + feature = "deprecated", + deprecated(since = "4.0.0", note = "This is now the default") + )] + pub fn is_dont_collapse_args_in_usage_set(&self) -> bool { + true + } + + /// Report whether [`Command::infer_long_args`] is set + pub(crate) fn is_infer_long_args_set(&self) -> bool { + self.is_set(AppSettings::InferLongArgs) + } + + /// Report whether [`Command::infer_subcommands`] is set + pub(crate) fn is_infer_subcommands_set(&self) -> bool { + self.is_set(AppSettings::InferSubcommands) + } + + /// Report whether [`Command::arg_required_else_help`] is set + pub fn is_arg_required_else_help_set(&self) -> bool { + self.is_set(AppSettings::ArgRequiredElseHelp) + } + + #[doc(hidden)] + #[cfg_attr( + feature = "deprecated", + deprecated( + since = "4.0.0", + note = "Replaced with `Arg::is_allow_hyphen_values_set`" + ) + )] + pub(crate) fn is_allow_hyphen_values_set(&self) -> bool { + self.is_set(AppSettings::AllowHyphenValues) + } + + #[doc(hidden)] + #[cfg_attr( + feature = "deprecated", + deprecated( + since = "4.0.0", + note = "Replaced with `Arg::is_allow_negative_numbers_set`" + ) + )] + pub fn is_allow_negative_numbers_set(&self) -> bool { + self.is_set(AppSettings::AllowNegativeNumbers) + } + + #[doc(hidden)] + #[cfg_attr( + feature = "deprecated", + deprecated(since = "4.0.0", note = "Replaced with `Arg::is_trailing_var_arg_set`") + )] + pub fn is_trailing_var_arg_set(&self) -> bool { + self.is_set(AppSettings::TrailingVarArg) + } + + /// Report whether [`Command::allow_missing_positional`] is set + pub fn is_allow_missing_positional_set(&self) -> bool { + self.is_set(AppSettings::AllowMissingPositional) + } + + /// Report whether [`Command::hide`] is set + pub fn is_hide_set(&self) -> bool { + self.is_set(AppSettings::Hidden) + } + + /// Report whether [`Command::subcommand_required`] is set + pub fn is_subcommand_required_set(&self) -> bool { + self.is_set(AppSettings::SubcommandRequired) + } + + /// Report whether [`Command::allow_external_subcommands`] is set + pub fn is_allow_external_subcommands_set(&self) -> bool { + self.is_set(AppSettings::AllowExternalSubcommands) + } + + /// Configured parser for values passed to an external subcommand + /// + /// # Example + /// + /// ```rust + /// # use clap_builder as clap; + /// let cmd = clap::Command::new("raw") + /// .external_subcommand_value_parser(clap::value_parser!(String)); + /// let value_parser = cmd.get_external_subcommand_value_parser(); + /// println!("{value_parser:?}"); + /// ``` + pub fn get_external_subcommand_value_parser(&self) -> Option<&super::ValueParser> { + if !self.is_allow_external_subcommands_set() { + None + } else { + static DEFAULT: super::ValueParser = super::ValueParser::os_string(); + Some(self.external_value_parser.as_ref().unwrap_or(&DEFAULT)) + } + } + + /// Report whether [`Command::args_conflicts_with_subcommands`] is set + pub fn is_args_conflicts_with_subcommands_set(&self) -> bool { + self.is_set(AppSettings::ArgsNegateSubcommands) + } + + #[doc(hidden)] + pub fn is_args_override_self(&self) -> bool { + self.is_set(AppSettings::AllArgsOverrideSelf) + } + + /// Report whether [`Command::subcommand_precedence_over_arg`] is set + pub fn is_subcommand_precedence_over_arg_set(&self) -> bool { + self.is_set(AppSettings::SubcommandPrecedenceOverArg) + } + + /// Report whether [`Command::subcommand_negates_reqs`] is set + pub fn is_subcommand_negates_reqs_set(&self) -> bool { + self.is_set(AppSettings::SubcommandsNegateReqs) + } + + /// Report whether [`Command::multicall`] is set + pub fn is_multicall_set(&self) -> bool { + self.is_set(AppSettings::Multicall) + } +} + +// Internally used only +impl Command { + pub(crate) fn get_override_usage(&self) -> Option<&StyledStr> { + self.usage_str.as_ref() + } + + pub(crate) fn get_override_help(&self) -> Option<&StyledStr> { + self.help_str.as_ref() + } + + #[cfg(feature = "help")] + pub(crate) fn get_help_template(&self) -> Option<&StyledStr> { + self.template.as_ref() + } + + #[cfg(feature = "help")] + pub(crate) fn get_term_width(&self) -> Option<usize> { + self.app_ext.get::<TermWidth>().map(|e| e.0) + } + + #[cfg(feature = "help")] + pub(crate) fn get_max_term_width(&self) -> Option<usize> { + self.app_ext.get::<MaxTermWidth>().map(|e| e.0) + } + + pub(crate) fn get_keymap(&self) -> &MKeyMap { + &self.args + } + + fn get_used_global_args(&self, matches: &ArgMatches, global_arg_vec: &mut Vec<Id>) { + global_arg_vec.extend( + self.args + .args() + .filter(|a| a.is_global_set()) + .map(|ga| ga.id.clone()), + ); + if let Some((id, matches)) = matches.subcommand() { + if let Some(used_sub) = self.find_subcommand(id) { + used_sub.get_used_global_args(matches, global_arg_vec); + } + } + } + + fn _do_parse( + &mut self, + raw_args: &mut clap_lex::RawArgs, + args_cursor: clap_lex::ArgCursor, + ) -> ClapResult<ArgMatches> { + debug!("Command::_do_parse"); + + // If there are global arguments, or settings we need to propagate them down to subcommands + // before parsing in case we run into a subcommand + self._build_self(false); + + let mut matcher = ArgMatcher::new(self); + + // do the real parsing + let mut parser = Parser::new(self); + if let Err(error) = parser.get_matches_with(&mut matcher, raw_args, args_cursor) { + if self.is_set(AppSettings::IgnoreErrors) && error.use_stderr() { + debug!("Command::_do_parse: ignoring error: {error}"); + } else { + return Err(error); + } + } + + let mut global_arg_vec = Default::default(); + self.get_used_global_args(&matcher, &mut global_arg_vec); + + matcher.propagate_globals(&global_arg_vec); + + Ok(matcher.into_inner()) + } + + /// Prepare for introspecting on all included [`Command`]s + /// + /// Call this on the top-level [`Command`] when done building and before reading state for + /// cases like completions, custom help output, etc. + pub fn build(&mut self) { + self._build_recursive(true); + self._build_bin_names_internal(); + } + + pub(crate) fn _build_recursive(&mut self, expand_help_tree: bool) { + self._build_self(expand_help_tree); + for subcmd in self.get_subcommands_mut() { + subcmd._build_recursive(expand_help_tree); + } + } + + pub(crate) fn _build_self(&mut self, expand_help_tree: bool) { + debug!("Command::_build: name={:?}", self.get_name()); + if !self.settings.is_set(AppSettings::Built) { + if let Some(deferred) = self.deferred.take() { + *self = (deferred)(std::mem::take(self)); + } + + // Make sure all the globally set flags apply to us as well + self.settings = self.settings | self.g_settings; + + if self.is_multicall_set() { + self.settings.set(AppSettings::SubcommandRequired); + self.settings.set(AppSettings::DisableHelpFlag); + self.settings.set(AppSettings::DisableVersionFlag); + } + if !cfg!(feature = "help") && self.get_override_help().is_none() { + self.settings.set(AppSettings::DisableHelpFlag); + self.settings.set(AppSettings::DisableHelpSubcommand); + } + if self.is_set(AppSettings::ArgsNegateSubcommands) { + self.settings.set(AppSettings::SubcommandsNegateReqs); + } + if self.external_value_parser.is_some() { + self.settings.set(AppSettings::AllowExternalSubcommands); + } + if !self.has_subcommands() { + self.settings.set(AppSettings::DisableHelpSubcommand); + } + + self._propagate(); + self._check_help_and_version(expand_help_tree); + self._propagate_global_args(); + + let mut pos_counter = 1; + let hide_pv = self.is_set(AppSettings::HidePossibleValues); + for a in self.args.args_mut() { + // Fill in the groups + for g in &a.groups { + if let Some(ag) = self.groups.iter_mut().find(|grp| grp.id == *g) { + ag.args.push(a.get_id().clone()); + } else { + let mut ag = ArgGroup::new(g); + ag.args.push(a.get_id().clone()); + self.groups.push(ag); + } + } + + // Figure out implied settings + a._build(); + if hide_pv && a.is_takes_value_set() { + a.settings.set(ArgSettings::HidePossibleValues); + } + if a.is_positional() && a.index.is_none() { + a.index = Some(pos_counter); + pos_counter += 1; + } + } + + self.args._build(); + + #[allow(deprecated)] + { + let highest_idx = self + .get_keymap() + .keys() + .filter_map(|x| { + if let crate::mkeymap::KeyType::Position(n) = x { + Some(*n) + } else { + None + } + }) + .max() + .unwrap_or(0); + let is_trailing_var_arg_set = self.is_trailing_var_arg_set(); + let is_allow_hyphen_values_set = self.is_allow_hyphen_values_set(); + let is_allow_negative_numbers_set = self.is_allow_negative_numbers_set(); + for arg in self.args.args_mut() { + if is_allow_hyphen_values_set && arg.is_takes_value_set() { + arg.settings.set(ArgSettings::AllowHyphenValues); + } + if is_allow_negative_numbers_set && arg.is_takes_value_set() { + arg.settings.set(ArgSettings::AllowNegativeNumbers); + } + if is_trailing_var_arg_set && arg.get_index() == Some(highest_idx) { + arg.settings.set(ArgSettings::TrailingVarArg); + } + } + } + + #[cfg(debug_assertions)] + assert_app(self); + self.settings.set(AppSettings::Built); + } else { + debug!("Command::_build: already built"); + } + } + + pub(crate) fn _build_subcommand(&mut self, name: &str) -> Option<&mut Self> { + use std::fmt::Write; + + let mut mid_string = String::from(" "); + #[cfg(feature = "usage")] + if !self.is_subcommand_negates_reqs_set() && !self.is_args_conflicts_with_subcommands_set() + { + let reqs = Usage::new(self).get_required_usage_from(&[], None, true); // maybe Some(m) + + for s in &reqs { + mid_string.push_str(&s.to_string()); + mid_string.push(' '); + } + } + let is_multicall_set = self.is_multicall_set(); + + let sc = some!(self.subcommands.iter_mut().find(|s| s.name == name)); + + // Display subcommand name, short and long in usage + let mut sc_names = String::new(); + sc_names.push_str(sc.name.as_str()); + let mut flag_subcmd = false; + if let Some(l) = sc.get_long_flag() { + write!(sc_names, "|--{l}").unwrap(); + flag_subcmd = true; + } + if let Some(s) = sc.get_short_flag() { + write!(sc_names, "|-{s}").unwrap(); + flag_subcmd = true; + } + + if flag_subcmd { + sc_names = format!("{{{sc_names}}}"); + } + + let usage_name = self + .bin_name + .as_ref() + .map(|bin_name| format!("{bin_name}{mid_string}{sc_names}")) + .unwrap_or(sc_names); + sc.usage_name = Some(usage_name); + + // bin_name should be parent's bin_name + [<reqs>] + the sc's name separated by + // a space + let bin_name = format!( + "{}{}{}", + self.bin_name.as_deref().unwrap_or_default(), + if self.bin_name.is_some() { " " } else { "" }, + &*sc.name + ); + debug!( + "Command::_build_subcommand Setting bin_name of {} to {:?}", + sc.name, bin_name + ); + sc.bin_name = Some(bin_name); + + if sc.display_name.is_none() { + let self_display_name = if is_multicall_set { + self.display_name.as_deref().unwrap_or("") + } else { + self.display_name.as_deref().unwrap_or(&self.name) + }; + let display_name = format!( + "{}{}{}", + self_display_name, + if !self_display_name.is_empty() { + "-" + } else { + "" + }, + &*sc.name + ); + debug!( + "Command::_build_subcommand Setting display_name of {} to {:?}", + sc.name, display_name + ); + sc.display_name = Some(display_name); + } + + // Ensure all args are built and ready to parse + sc._build_self(false); + + Some(sc) + } + + fn _build_bin_names_internal(&mut self) { + debug!("Command::_build_bin_names"); + + if !self.is_set(AppSettings::BinNameBuilt) { + let mut mid_string = String::from(" "); + #[cfg(feature = "usage")] + if !self.is_subcommand_negates_reqs_set() + && !self.is_args_conflicts_with_subcommands_set() + { + let reqs = Usage::new(self).get_required_usage_from(&[], None, true); // maybe Some(m) + + for s in &reqs { + mid_string.push_str(&s.to_string()); + mid_string.push(' '); + } + } + let is_multicall_set = self.is_multicall_set(); + + let self_bin_name = if is_multicall_set { + self.bin_name.as_deref().unwrap_or("") + } else { + self.bin_name.as_deref().unwrap_or(&self.name) + } + .to_owned(); + + for sc in &mut self.subcommands { + debug!("Command::_build_bin_names:iter: bin_name set..."); + + if sc.usage_name.is_none() { + use std::fmt::Write; + // Display subcommand name, short and long in usage + let mut sc_names = String::new(); + sc_names.push_str(sc.name.as_str()); + let mut flag_subcmd = false; + if let Some(l) = sc.get_long_flag() { + write!(sc_names, "|--{l}").unwrap(); + flag_subcmd = true; + } + if let Some(s) = sc.get_short_flag() { + write!(sc_names, "|-{s}").unwrap(); + flag_subcmd = true; + } + + if flag_subcmd { + sc_names = format!("{{{sc_names}}}"); + } + + let usage_name = format!("{self_bin_name}{mid_string}{sc_names}"); + debug!( + "Command::_build_bin_names:iter: Setting usage_name of {} to {:?}", + sc.name, usage_name + ); + sc.usage_name = Some(usage_name); + } else { + debug!( + "Command::_build_bin_names::iter: Using existing usage_name of {} ({:?})", + sc.name, sc.usage_name + ); + } + + if sc.bin_name.is_none() { + let bin_name = format!( + "{}{}{}", + self_bin_name, + if !self_bin_name.is_empty() { " " } else { "" }, + &*sc.name + ); + debug!( + "Command::_build_bin_names:iter: Setting bin_name of {} to {:?}", + sc.name, bin_name + ); + sc.bin_name = Some(bin_name); + } else { + debug!( + "Command::_build_bin_names::iter: Using existing bin_name of {} ({:?})", + sc.name, sc.bin_name + ); + } + + if sc.display_name.is_none() { + let self_display_name = if is_multicall_set { + self.display_name.as_deref().unwrap_or("") + } else { + self.display_name.as_deref().unwrap_or(&self.name) + }; + let display_name = format!( + "{}{}{}", + self_display_name, + if !self_display_name.is_empty() { + "-" + } else { + "" + }, + &*sc.name + ); + debug!( + "Command::_build_bin_names:iter: Setting display_name of {} to {:?}", + sc.name, display_name + ); + sc.display_name = Some(display_name); + } else { + debug!( + "Command::_build_bin_names::iter: Using existing display_name of {} ({:?})", + sc.name, sc.display_name + ); + } + + sc._build_bin_names_internal(); + } + self.set(AppSettings::BinNameBuilt); + } else { + debug!("Command::_build_bin_names: already built"); + } + } + + pub(crate) fn _panic_on_missing_help(&self, help_required_globally: bool) { + if self.is_set(AppSettings::HelpExpected) || help_required_globally { + let args_missing_help: Vec<Id> = self + .args + .args() + .filter(|arg| arg.get_help().is_none() && arg.get_long_help().is_none()) + .map(|arg| arg.get_id().clone()) + .collect(); + + debug_assert!(args_missing_help.is_empty(), + "Command::help_expected is enabled for the Command {}, but at least one of its arguments does not have either `help` or `long_help` set. List of such arguments: {}", + self.name, + args_missing_help.join(", ") + ); + } + + for sub_app in &self.subcommands { + sub_app._panic_on_missing_help(help_required_globally); + } + } + + #[cfg(debug_assertions)] + pub(crate) fn two_args_of<F>(&self, condition: F) -> Option<(&Arg, &Arg)> + where + F: Fn(&Arg) -> bool, + { + two_elements_of(self.args.args().filter(|a: &&Arg| condition(a))) + } + + // just in case + #[allow(unused)] + fn two_groups_of<F>(&self, condition: F) -> Option<(&ArgGroup, &ArgGroup)> + where + F: Fn(&ArgGroup) -> bool, + { + two_elements_of(self.groups.iter().filter(|a| condition(a))) + } + + /// Propagate global args + pub(crate) fn _propagate_global_args(&mut self) { + debug!("Command::_propagate_global_args:{}", self.name); + + let autogenerated_help_subcommand = !self.is_disable_help_subcommand_set(); + + for sc in &mut self.subcommands { + if sc.get_name() == "help" && autogenerated_help_subcommand { + // Avoid propagating args to the autogenerated help subtrees used in completion. + // This prevents args from showing up during help completions like + // `myapp help subcmd <TAB>`, which should only suggest subcommands and not args, + // while still allowing args to show up properly on the generated help message. + continue; + } + + for a in self.args.args().filter(|a| a.is_global_set()) { + if sc.find(&a.id).is_some() { + debug!( + "Command::_propagate skipping {:?} to {}, already exists", + a.id, + sc.get_name(), + ); + continue; + } + + debug!( + "Command::_propagate pushing {:?} to {}", + a.id, + sc.get_name(), + ); + sc.args.push(a.clone()); + } + } + } + + /// Propagate settings + pub(crate) fn _propagate(&mut self) { + debug!("Command::_propagate:{}", self.name); + let mut subcommands = std::mem::take(&mut self.subcommands); + for sc in &mut subcommands { + self._propagate_subcommand(sc); + } + self.subcommands = subcommands; + } + + fn _propagate_subcommand(&self, sc: &mut Self) { + // We have to create a new scope in order to tell rustc the borrow of `sc` is + // done and to recursively call this method + { + if self.settings.is_set(AppSettings::PropagateVersion) { + if let Some(version) = self.version.as_ref() { + sc.version.get_or_insert_with(|| version.clone()); + } + if let Some(long_version) = self.long_version.as_ref() { + sc.long_version.get_or_insert_with(|| long_version.clone()); + } + } + + sc.settings = sc.settings | self.g_settings; + sc.g_settings = sc.g_settings | self.g_settings; + sc.app_ext.update(&self.app_ext); + } + } + + pub(crate) fn _check_help_and_version(&mut self, expand_help_tree: bool) { + debug!( + "Command::_check_help_and_version:{} expand_help_tree={}", + self.name, expand_help_tree + ); + + self.long_help_exists = self.long_help_exists_(); + + if !self.is_disable_help_flag_set() { + debug!("Command::_check_help_and_version: Building default --help"); + let mut arg = Arg::new(Id::HELP) + .short('h') + .long("help") + .action(ArgAction::Help); + if self.long_help_exists { + arg = arg + .help("Print help (see more with '--help')") + .long_help("Print help (see a summary with '-h')"); + } else { + arg = arg.help("Print help"); + } + // Avoiding `arg_internal` to not be sensitive to `next_help_heading` / + // `next_display_order` + self.args.push(arg); + } + if !self.is_disable_version_flag_set() { + debug!("Command::_check_help_and_version: Building default --version"); + let arg = Arg::new(Id::VERSION) + .short('V') + .long("version") + .action(ArgAction::Version) + .help("Print version"); + // Avoiding `arg_internal` to not be sensitive to `next_help_heading` / + // `next_display_order` + self.args.push(arg); + } + + if !self.is_set(AppSettings::DisableHelpSubcommand) { + debug!("Command::_check_help_and_version: Building help subcommand"); + let help_about = "Print this message or the help of the given subcommand(s)"; + + let mut help_subcmd = if expand_help_tree { + // Slow code path to recursively clone all other subcommand subtrees under help + let help_subcmd = Command::new("help") + .about(help_about) + .global_setting(AppSettings::DisableHelpSubcommand) + .subcommands(self.get_subcommands().map(Command::_copy_subtree_for_help)); + + let mut help_help_subcmd = Command::new("help").about(help_about); + help_help_subcmd.version = None; + help_help_subcmd.long_version = None; + help_help_subcmd = help_help_subcmd + .setting(AppSettings::DisableHelpFlag) + .setting(AppSettings::DisableVersionFlag); + + help_subcmd.subcommand(help_help_subcmd) + } else { + Command::new("help").about(help_about).arg( + Arg::new("subcommand") + .action(ArgAction::Append) + .num_args(..) + .value_name("COMMAND") + .help("Print help for the subcommand(s)"), + ) + }; + self._propagate_subcommand(&mut help_subcmd); + + // The parser acts like this is set, so let's set it so we don't falsely + // advertise it to the user + help_subcmd.version = None; + help_subcmd.long_version = None; + help_subcmd = help_subcmd + .setting(AppSettings::DisableHelpFlag) + .setting(AppSettings::DisableVersionFlag) + .unset_global_setting(AppSettings::PropagateVersion); + + self.subcommands.push(help_subcmd); + } + } + + fn _copy_subtree_for_help(&self) -> Command { + let mut cmd = Command::new(self.name.clone()) + .hide(self.is_hide_set()) + .global_setting(AppSettings::DisableHelpFlag) + .global_setting(AppSettings::DisableVersionFlag) + .subcommands(self.get_subcommands().map(Command::_copy_subtree_for_help)); + if self.get_about().is_some() { + cmd = cmd.about(self.get_about().unwrap().clone()); + } + cmd + } + + pub(crate) fn _render_version(&self, use_long: bool) -> String { + debug!("Command::_render_version"); + + let ver = if use_long { + self.long_version + .as_deref() + .or(self.version.as_deref()) + .unwrap_or_default() + } else { + self.version + .as_deref() + .or(self.long_version.as_deref()) + .unwrap_or_default() + }; + let display_name = self.get_display_name().unwrap_or_else(|| self.get_name()); + format!("{display_name} {ver}\n") + } + + pub(crate) fn format_group(&self, g: &Id) -> StyledStr { + let g_string = self + .unroll_args_in_group(g) + .iter() + .filter_map(|x| self.find(x)) + .map(|x| { + if x.is_positional() { + // Print val_name for positional arguments. e.g. <file_name> + x.name_no_brackets() + } else { + // Print usage string for flags arguments, e.g. <--help> + x.to_string() + } + }) + .collect::<Vec<_>>() + .join("|"); + let mut styled = StyledStr::new(); + styled.push_str("<"); + styled.push_string(g_string); + styled.push_str(">"); + styled + } +} + +/// A workaround: +/// <https://github.com/rust-lang/rust/issues/34511#issuecomment-373423999> +pub(crate) trait Captures<'a> {} +impl<'a, T> Captures<'a> for T {} + +// Internal Query Methods +impl Command { + /// Iterate through the *flags* & *options* arguments. + #[cfg(any(feature = "usage", feature = "help"))] + pub(crate) fn get_non_positionals(&self) -> impl Iterator<Item = &Arg> { + self.get_arguments().filter(|a| !a.is_positional()) + } + + pub(crate) fn find(&self, arg_id: &Id) -> Option<&Arg> { + self.args.args().find(|a| a.get_id() == arg_id) + } + + #[inline] + pub(crate) fn contains_short(&self, s: char) -> bool { + debug_assert!( + self.is_set(AppSettings::Built), + "If Command::_build hasn't been called, manually search through Arg shorts" + ); + + self.args.contains(s) + } + + #[inline] + pub(crate) fn set(&mut self, s: AppSettings) { + self.settings.set(s) + } + + #[inline] + pub(crate) fn has_positionals(&self) -> bool { + self.get_positionals().next().is_some() + } + + #[cfg(any(feature = "usage", feature = "help"))] + pub(crate) fn has_visible_subcommands(&self) -> bool { + self.subcommands + .iter() + .any(|sc| sc.name != "help" && !sc.is_set(AppSettings::Hidden)) + } + + /// Check if this subcommand can be referred to as `name`. In other words, + /// check if `name` is the name of this subcommand or is one of its aliases. + #[inline] + pub(crate) fn aliases_to(&self, name: impl AsRef<std::ffi::OsStr>) -> bool { + let name = name.as_ref(); + self.get_name() == name || self.get_all_aliases().any(|alias| alias == name) + } + + /// Check if this subcommand can be referred to as `name`. In other words, + /// check if `name` is the name of this short flag subcommand or is one of its short flag aliases. + #[inline] + pub(crate) fn short_flag_aliases_to(&self, flag: char) -> bool { + Some(flag) == self.short_flag + || self.get_all_short_flag_aliases().any(|alias| flag == alias) + } + + /// Check if this subcommand can be referred to as `name`. In other words, + /// check if `name` is the name of this long flag subcommand or is one of its long flag aliases. + #[inline] + pub(crate) fn long_flag_aliases_to(&self, flag: &str) -> bool { + match self.long_flag.as_ref() { + Some(long_flag) => { + long_flag == flag || self.get_all_long_flag_aliases().any(|alias| alias == flag) + } + None => self.get_all_long_flag_aliases().any(|alias| alias == flag), + } + } + + #[cfg(debug_assertions)] + pub(crate) fn id_exists(&self, id: &Id) -> bool { + self.args.args().any(|x| x.get_id() == id) || self.groups.iter().any(|x| x.id == *id) + } + + /// Iterate through the groups this arg is member of. + pub(crate) fn groups_for_arg<'a>(&'a self, arg: &Id) -> impl Iterator<Item = Id> + 'a { + debug!("Command::groups_for_arg: id={arg:?}"); + let arg = arg.clone(); + self.groups + .iter() + .filter(move |grp| grp.args.iter().any(|a| a == &arg)) + .map(|grp| grp.id.clone()) + } + + pub(crate) fn find_group(&self, group_id: &Id) -> Option<&ArgGroup> { + self.groups.iter().find(|g| g.id == *group_id) + } + + /// Iterate through all the names of all subcommands (not recursively), including aliases. + /// Used for suggestions. + pub(crate) fn all_subcommand_names(&self) -> impl Iterator<Item = &str> + Captures { + self.get_subcommands().flat_map(|sc| { + let name = sc.get_name(); + let aliases = sc.get_all_aliases(); + std::iter::once(name).chain(aliases) + }) + } + + pub(crate) fn required_graph(&self) -> ChildGraph<Id> { + let mut reqs = ChildGraph::with_capacity(5); + for a in self.args.args().filter(|a| a.is_required_set()) { + reqs.insert(a.get_id().clone()); + } + for group in &self.groups { + if group.required { + let idx = reqs.insert(group.id.clone()); + for a in &group.requires { + reqs.insert_child(idx, a.clone()); + } + } + } + + reqs + } + + pub(crate) fn unroll_args_in_group(&self, group: &Id) -> Vec<Id> { + debug!("Command::unroll_args_in_group: group={group:?}"); + let mut g_vec = vec![group]; + let mut args = vec![]; + + while let Some(g) = g_vec.pop() { + for n in self + .groups + .iter() + .find(|grp| grp.id == *g) + .expect(INTERNAL_ERROR_MSG) + .args + .iter() + { + debug!("Command::unroll_args_in_group:iter: entity={n:?}"); + if !args.contains(n) { + if self.find(n).is_some() { + debug!("Command::unroll_args_in_group:iter: this is an arg"); + args.push(n.clone()) + } else { + debug!("Command::unroll_args_in_group:iter: this is a group"); + g_vec.push(n); + } + } + } + } + + args + } + + pub(crate) fn unroll_arg_requires<F>(&self, func: F, arg: &Id) -> Vec<Id> + where + F: Fn(&(ArgPredicate, Id)) -> Option<Id>, + { + let mut processed = vec![]; + let mut r_vec = vec![arg]; + let mut args = vec![]; + + while let Some(a) = r_vec.pop() { + if processed.contains(&a) { + continue; + } + + processed.push(a); + + if let Some(arg) = self.find(a) { + for r in arg.requires.iter().filter_map(&func) { + if let Some(req) = self.find(&r) { + if !req.requires.is_empty() { + r_vec.push(req.get_id()) + } + } + args.push(r); + } + } + } + + args + } + + /// Find a flag subcommand name by short flag or an alias + pub(crate) fn find_short_subcmd(&self, c: char) -> Option<&str> { + self.get_subcommands() + .find(|sc| sc.short_flag_aliases_to(c)) + .map(|sc| sc.get_name()) + } + + /// Find a flag subcommand name by long flag or an alias + pub(crate) fn find_long_subcmd(&self, long: &str) -> Option<&str> { + self.get_subcommands() + .find(|sc| sc.long_flag_aliases_to(long)) + .map(|sc| sc.get_name()) + } + + #[cfg(feature = "help")] + pub(crate) fn get_display_order(&self) -> usize { + self.disp_ord.unwrap_or(999) + } + + pub(crate) fn write_help_err(&self, mut use_long: bool) -> StyledStr { + debug!( + "Command::write_help_err: {}, use_long={:?}", + self.get_display_name().unwrap_or_else(|| self.get_name()), + use_long && self.long_help_exists(), + ); + + use_long = use_long && self.long_help_exists(); + let usage = Usage::new(self); + + let mut styled = StyledStr::new(); + write_help(&mut styled, self, &usage, use_long); + + styled + } + + pub(crate) fn write_version_err(&self, use_long: bool) -> StyledStr { + let msg = self._render_version(use_long); + StyledStr::from(msg) + } + + pub(crate) fn long_help_exists(&self) -> bool { + debug!("Command::long_help_exists: {}", self.long_help_exists); + self.long_help_exists + } + + fn long_help_exists_(&self) -> bool { + debug!("Command::long_help_exists"); + // In this case, both must be checked. This allows the retention of + // original formatting, but also ensures that the actual -h or --help + // specified by the user is sent through. If hide_short_help is not included, + // then items specified with hidden_short_help will also be hidden. + let should_long = |v: &Arg| { + !v.is_hide_set() + && (v.get_long_help().is_some() + || v.is_hide_long_help_set() + || v.is_hide_short_help_set() + || (!v.is_hide_possible_values_set() + && v.get_possible_values() + .iter() + .any(PossibleValue::should_show_help))) + }; + + // Subcommands aren't checked because we prefer short help for them, deferring to + // `cmd subcmd --help` for more. + self.get_long_about().is_some() + || self.get_before_long_help().is_some() + || self.get_after_long_help().is_some() + || self.get_arguments().any(should_long) + } + + // Should we color the help? + pub(crate) fn color_help(&self) -> ColorChoice { + #[cfg(feature = "color")] + if self.is_disable_colored_help_set() { + return ColorChoice::Never; + } + + self.get_color() + } +} + +impl Default for Command { + fn default() -> Self { + Self { + name: Default::default(), + long_flag: Default::default(), + short_flag: Default::default(), + display_name: Default::default(), + bin_name: Default::default(), + author: Default::default(), + version: Default::default(), + long_version: Default::default(), + about: Default::default(), + long_about: Default::default(), + before_help: Default::default(), + before_long_help: Default::default(), + after_help: Default::default(), + after_long_help: Default::default(), + aliases: Default::default(), + short_flag_aliases: Default::default(), + long_flag_aliases: Default::default(), + usage_str: Default::default(), + usage_name: Default::default(), + help_str: Default::default(), + disp_ord: Default::default(), + #[cfg(feature = "help")] + template: Default::default(), + settings: Default::default(), + g_settings: Default::default(), + args: Default::default(), + subcommands: Default::default(), + groups: Default::default(), + current_help_heading: Default::default(), + current_disp_ord: Some(0), + subcommand_value_name: Default::default(), + subcommand_heading: Default::default(), + external_value_parser: Default::default(), + long_help_exists: false, + deferred: None, + app_ext: Default::default(), + } + } +} + +impl Index<&'_ Id> for Command { + type Output = Arg; + + fn index(&self, key: &Id) -> &Self::Output { + self.find(key).expect(INTERNAL_ERROR_MSG) + } +} + +impl From<&'_ Command> for Command { + fn from(cmd: &'_ Command) -> Self { + cmd.clone() + } +} + +impl fmt::Display for Command { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + write!(f, "{}", self.name) + } +} + +pub(crate) trait AppTag: crate::builder::ext::Extension {} + +#[derive(Default, Copy, Clone, Debug)] +struct TermWidth(usize); + +impl AppTag for TermWidth {} + +#[derive(Default, Copy, Clone, Debug)] +struct MaxTermWidth(usize); + +impl AppTag for MaxTermWidth {} + +fn two_elements_of<I, T>(mut iter: I) -> Option<(T, T)> +where + I: Iterator<Item = T>, +{ + let first = iter.next(); + let second = iter.next(); + + match (first, second) { + (Some(first), Some(second)) => Some((first, second)), + _ => None, + } +} + +#[test] +fn check_auto_traits() { + static_assertions::assert_impl_all!(Command: Send, Sync, Unpin); +} diff --git a/vendor/clap_builder/src/builder/debug_asserts.rs b/vendor/clap_builder/src/builder/debug_asserts.rs new file mode 100644 index 0000000..2b63384 --- /dev/null +++ b/vendor/clap_builder/src/builder/debug_asserts.rs @@ -0,0 +1,840 @@ +use std::cmp::Ordering; + +use crate::builder::ValueRange; +use crate::mkeymap::KeyType; +use crate::util::FlatSet; +use crate::util::Id; +use crate::ArgAction; +use crate::INTERNAL_ERROR_MSG; +use crate::{Arg, Command, ValueHint}; + +pub(crate) fn assert_app(cmd: &Command) { + debug!("Command::_debug_asserts"); + + let mut short_flags = vec![]; + let mut long_flags = vec![]; + + // Invalid version flag settings + if cmd.get_version().is_none() && cmd.get_long_version().is_none() { + // PropagateVersion is meaningless if there is no version + assert!( + !cmd.is_propagate_version_set(), + "Command {}: No version information via Command::version or Command::long_version to propagate", + cmd.get_name(), + ); + + // Used `Command::mut_arg("version", ..) but did not provide any version information to display + let version_needed = cmd + .get_arguments() + .filter(|x| matches!(x.get_action(), ArgAction::Version)) + .map(|x| x.get_id()) + .collect::<Vec<_>>(); + + assert_eq!(version_needed, Vec::<&str>::new(), "Command {}: `ArgAction::Version` used without providing Command::version or Command::long_version" + ,cmd.get_name() + ); + } + + for sc in cmd.get_subcommands() { + if let Some(s) = sc.get_short_flag().as_ref() { + short_flags.push(Flag::Command(format!("-{s}"), sc.get_name())); + } + + for short_alias in sc.get_all_short_flag_aliases() { + short_flags.push(Flag::Command(format!("-{short_alias}"), sc.get_name())); + } + + if let Some(l) = sc.get_long_flag().as_ref() { + assert!(!l.starts_with('-'), "Command {}: long_flag {:?} must not start with a `-`, that will be handled by the parser", sc.get_name(), l); + long_flags.push(Flag::Command(format!("--{l}"), sc.get_name())); + } + + for long_alias in sc.get_all_long_flag_aliases() { + long_flags.push(Flag::Command(format!("--{long_alias}"), sc.get_name())); + } + } + + for arg in cmd.get_arguments() { + assert_arg(arg); + + assert!( + !cmd.is_multicall_set(), + "Command {}: Arguments like {} cannot be set on a multicall command", + cmd.get_name(), + arg.get_id() + ); + + if let Some(s) = arg.get_short() { + short_flags.push(Flag::Arg(format!("-{s}"), arg.get_id().as_str())); + } + + for (short_alias, _) in &arg.short_aliases { + short_flags.push(Flag::Arg(format!("-{short_alias}"), arg.get_id().as_str())); + } + + if let Some(l) = arg.get_long() { + assert!(!l.starts_with('-'), "Argument {}: long {:?} must not start with a `-`, that will be handled by the parser", arg.get_id(), l); + long_flags.push(Flag::Arg(format!("--{l}"), arg.get_id().as_str())); + } + + for (long_alias, _) in &arg.aliases { + long_flags.push(Flag::Arg(format!("--{long_alias}"), arg.get_id().as_str())); + } + + // Name conflicts + if let Some((first, second)) = cmd.two_args_of(|x| x.get_id() == arg.get_id()) { + panic!( + "Command {}: Argument names must be unique, but '{}' is in use by more than one argument or group{}", + cmd.get_name(), + arg.get_id(), + duplicate_tip(cmd, first, second), + ); + } + + // Long conflicts + if let Some(l) = arg.get_long() { + if let Some((first, second)) = cmd.two_args_of(|x| x.get_long() == Some(l)) { + panic!( + "Command {}: Long option names must be unique for each argument, \ + but '--{}' is in use by both '{}' and '{}'{}", + cmd.get_name(), + l, + first.get_id(), + second.get_id(), + duplicate_tip(cmd, first, second) + ) + } + } + + // Short conflicts + if let Some(s) = arg.get_short() { + if let Some((first, second)) = cmd.two_args_of(|x| x.get_short() == Some(s)) { + panic!( + "Command {}: Short option names must be unique for each argument, \ + but '-{}' is in use by both '{}' and '{}'{}", + cmd.get_name(), + s, + first.get_id(), + second.get_id(), + duplicate_tip(cmd, first, second), + ) + } + } + + // Index conflicts + if let Some(idx) = arg.index { + if let Some((first, second)) = + cmd.two_args_of(|x| x.is_positional() && x.get_index() == Some(idx)) + { + panic!( + "Command {}: Argument '{}' has the same index as '{}' \ + and they are both positional arguments\n\n\t \ + Use `Arg::num_args(1..)` to allow one \ + positional argument to take multiple values", + cmd.get_name(), + first.get_id(), + second.get_id() + ) + } + } + + // requires, r_if, r_unless + for req in &arg.requires { + assert!( + cmd.id_exists(&req.1), + "Command {}: Argument or group '{}' specified in 'requires*' for '{}' does not exist", + cmd.get_name(), + req.1, + arg.get_id(), + ); + } + + for req in &arg.r_ifs { + assert!( + !arg.is_required_set(), + "Argument {}: `required` conflicts with `required_if_eq*`", + arg.get_id() + ); + assert!( + cmd.id_exists(&req.0), + "Command {}: Argument or group '{}' specified in 'required_if_eq*' for '{}' does not exist", + cmd.get_name(), + req.0, + arg.get_id() + ); + } + + for req in &arg.r_ifs_all { + assert!( + !arg.is_required_set(), + "Argument {}: `required` conflicts with `required_if_eq_all`", + arg.get_id() + ); + assert!( + cmd.id_exists(&req.0), + "Command {}: Argument or group '{}' specified in 'required_if_eq_all' for '{}' does not exist", + cmd.get_name(), + req.0, + arg.get_id() + ); + } + + for req in &arg.r_unless { + assert!( + !arg.is_required_set(), + "Argument {}: `required` conflicts with `required_unless*`", + arg.get_id() + ); + assert!( + cmd.id_exists(req), + "Command {}: Argument or group '{}' specified in 'required_unless*' for '{}' does not exist", + cmd.get_name(), + req, + arg.get_id(), + ); + } + + for req in &arg.r_unless_all { + assert!( + !arg.is_required_set(), + "Argument {}: `required` conflicts with `required_unless*`", + arg.get_id() + ); + assert!( + cmd.id_exists(req), + "Command {}: Argument or group '{}' specified in 'required_unless*' for '{}' does not exist", + cmd.get_name(), + req, + arg.get_id(), + ); + } + + // blacklist + for req in &arg.blacklist { + assert!( + cmd.id_exists(req), + "Command {}: Argument or group '{}' specified in 'conflicts_with*' for '{}' does not exist", + cmd.get_name(), + req, + arg.get_id(), + ); + } + + // overrides + for req in &arg.overrides { + assert!( + cmd.id_exists(req), + "Command {}: Argument or group '{}' specified in 'overrides_with*' for '{}' does not exist", + cmd.get_name(), + req, + arg.get_id(), + ); + } + + if arg.is_last_set() { + assert!( + arg.get_long().is_none(), + "Command {}: Flags or Options cannot have last(true) set. '{}' has both a long and last(true) set.", + cmd.get_name(), + arg.get_id() + ); + assert!( + arg.get_short().is_none(), + "Command {}: Flags or Options cannot have last(true) set. '{}' has both a short and last(true) set.", + cmd.get_name(), + arg.get_id() + ); + } + + assert!( + !(arg.is_required_set() && arg.is_global_set()), + "Command {}: Global arguments cannot be required.\n\n\t'{}' is marked as both global and required", + cmd.get_name(), + arg.get_id() + ); + + if arg.get_value_hint() == ValueHint::CommandWithArguments { + assert!( + arg.is_positional(), + "Command {}: Argument '{}' has hint CommandWithArguments and must be positional.", + cmd.get_name(), + arg.get_id() + ); + + assert!( + arg.is_trailing_var_arg_set() || arg.is_last_set(), + "Command {}: Positional argument '{}' has hint CommandWithArguments, so Command must have `trailing_var_arg(true)` or `last(true)` set.", + cmd.get_name(), + arg.get_id() + ); + } + } + + for group in cmd.get_groups() { + // Name conflicts + assert!( + cmd.get_groups().filter(|x| x.id == group.id).count() < 2, + "Command {}: Argument group name must be unique\n\n\t'{}' is already in use", + cmd.get_name(), + group.get_id(), + ); + + // Groups should not have naming conflicts with Args + assert!( + !cmd.get_arguments().any(|x| x.get_id() == group.get_id()), + "Command {}: Argument group name '{}' must not conflict with argument name", + cmd.get_name(), + group.get_id(), + ); + + for arg in &group.args { + // Args listed inside groups should exist + assert!( + cmd.get_arguments().any(|x| x.get_id() == arg), + "Command {}: Argument group '{}' contains non-existent argument '{}'", + cmd.get_name(), + group.get_id(), + arg + ); + } + + for arg in &group.requires { + // Args listed inside groups should exist + assert!( + cmd.id_exists(arg), + "Command {}: Argument group '{}' requires non-existent '{}' id", + cmd.get_name(), + group.get_id(), + arg + ); + } + + for arg in &group.conflicts { + // Args listed inside groups should exist + assert!( + cmd.id_exists(arg), + "Command {}: Argument group '{}' conflicts with non-existent '{}' id", + cmd.get_name(), + group.get_id(), + arg + ); + } + } + + // Conflicts between flags and subcommands + + long_flags.sort_unstable(); + short_flags.sort_unstable(); + + detect_duplicate_flags(&long_flags, "long"); + detect_duplicate_flags(&short_flags, "short"); + + let mut subs = FlatSet::new(); + for sc in cmd.get_subcommands() { + assert!( + subs.insert(sc.get_name()), + "Command {}: command name `{}` is duplicated", + cmd.get_name(), + sc.get_name() + ); + for alias in sc.get_all_aliases() { + assert!( + subs.insert(alias), + "Command {}: command `{}` alias `{}` is duplicated", + cmd.get_name(), + sc.get_name(), + alias + ); + } + } + + _verify_positionals(cmd); + + #[cfg(feature = "help")] + if let Some(help_template) = cmd.get_help_template() { + assert!( + !help_template.to_string().contains("{flags}"), + "Command {}: {}", + cmd.get_name(), + "`{flags}` template variable was removed in clap3, they are now included in `{options}`", + ); + assert!( + !help_template.to_string().contains("{unified}"), + "Command {}: {}", + cmd.get_name(), + "`{unified}` template variable was removed in clap3, use `{options}` instead" + ); + #[cfg(feature = "unstable-v5")] + assert!( + !help_template.to_string().contains("{bin}"), + "Command {}: {}", + cmd.get_name(), + "`{bin}` template variable was removed in clap5, use `{name}` instead" + ) + } + + cmd._panic_on_missing_help(cmd.is_help_expected_set()); + assert_app_flags(cmd); +} + +fn duplicate_tip(cmd: &Command, first: &Arg, second: &Arg) -> &'static str { + if !cmd.is_disable_help_flag_set() + && (first.get_id() == Id::HELP || second.get_id() == Id::HELP) + { + " (call `cmd.disable_help_flag(true)` to remove the auto-generated `--help`)" + } else if !cmd.is_disable_version_flag_set() + && (first.get_id() == Id::VERSION || second.get_id() == Id::VERSION) + { + " (call `cmd.disable_version_flag(true)` to remove the auto-generated `--version`)" + } else { + "" + } +} + +#[derive(Eq)] +enum Flag<'a> { + Command(String, &'a str), + Arg(String, &'a str), +} + +impl PartialEq for Flag<'_> { + fn eq(&self, other: &Flag) -> bool { + self.cmp(other) == Ordering::Equal + } +} + +impl PartialOrd for Flag<'_> { + fn partial_cmp(&self, other: &Flag) -> Option<Ordering> { + Some(self.cmp(other)) + } +} + +impl Ord for Flag<'_> { + fn cmp(&self, other: &Self) -> Ordering { + use Flag::*; + + match (self, other) { + (Command(s1, _), Command(s2, _)) + | (Arg(s1, _), Arg(s2, _)) + | (Command(s1, _), Arg(s2, _)) + | (Arg(s1, _), Command(s2, _)) => { + if s1 == s2 { + Ordering::Equal + } else { + s1.cmp(s2) + } + } + } + } +} + +fn detect_duplicate_flags(flags: &[Flag], short_or_long: &str) { + use Flag::*; + + for (one, two) in find_duplicates(flags) { + match (one, two) { + (Command(flag, one), Command(_, another)) if one != another => panic!( + "the '{flag}' {short_or_long} flag is specified for both '{one}' and '{another}' subcommands" + ), + + (Arg(flag, one), Arg(_, another)) if one != another => panic!( + "{short_or_long} option names must be unique, but '{flag}' is in use by both '{one}' and '{another}'" + ), + + (Arg(flag, arg), Command(_, sub)) | (Command(flag, sub), Arg(_, arg)) => panic!( + "the '{flag}' {short_or_long} flag for the '{arg}' argument conflicts with the short flag \ + for '{sub}' subcommand" + ), + + _ => {} + } + } +} + +/// Find duplicates in a sorted array. +/// +/// The algorithm is simple: the array is sorted, duplicates +/// must be placed next to each other, we can check only adjacent elements. +fn find_duplicates<T: PartialEq>(slice: &[T]) -> impl Iterator<Item = (&T, &T)> { + slice.windows(2).filter_map(|w| { + if w[0] == w[1] { + Some((&w[0], &w[1])) + } else { + None + } + }) +} + +fn assert_app_flags(cmd: &Command) { + macro_rules! checker { + ($a:ident requires $($b:ident)|+) => { + if cmd.$a() { + let mut s = String::new(); + + $( + if !cmd.$b() { + use std::fmt::Write; + write!(&mut s, " AppSettings::{} is required when AppSettings::{} is set.\n", std::stringify!($b), std::stringify!($a)).unwrap(); + } + )+ + + if !s.is_empty() { + panic!("{s}") + } + } + }; + ($a:ident conflicts $($b:ident)|+) => { + if cmd.$a() { + let mut s = String::new(); + + $( + if cmd.$b() { + use std::fmt::Write; + write!(&mut s, " AppSettings::{} conflicts with AppSettings::{}.\n", std::stringify!($b), std::stringify!($a)).unwrap(); + } + )+ + + if !s.is_empty() { + panic!("{}\n{}", cmd.get_name(), s) + } + } + }; + } + + checker!(is_multicall_set conflicts is_no_binary_name_set); +} + +#[cfg(debug_assertions)] +fn _verify_positionals(cmd: &Command) -> bool { + debug!("Command::_verify_positionals"); + // Because you must wait until all arguments have been supplied, this is the first chance + // to make assertions on positional argument indexes + // + // First we verify that the index highest supplied index, is equal to the number of + // positional arguments to verify there are no gaps (i.e. supplying an index of 1 and 3 + // but no 2) + + let highest_idx = cmd + .get_keymap() + .keys() + .filter_map(|x| { + if let KeyType::Position(n) = x { + Some(*n) + } else { + None + } + }) + .max() + .unwrap_or(0); + + let num_p = cmd.get_keymap().keys().filter(|x| x.is_position()).count(); + + assert!( + highest_idx == num_p, + "Found positional argument whose index is {highest_idx} but there \ + are only {num_p} positional arguments defined", + ); + + for arg in cmd.get_arguments() { + if arg.index.unwrap_or(0) == highest_idx { + assert!( + !arg.is_trailing_var_arg_set() || !arg.is_last_set(), + "{}:{}: `Arg::trailing_var_arg` and `Arg::last` cannot be used together", + cmd.get_name(), + arg.get_id() + ); + + if arg.is_trailing_var_arg_set() { + assert!( + arg.is_multiple(), + "{}:{}: `Arg::trailing_var_arg` must accept multiple values", + cmd.get_name(), + arg.get_id() + ); + } + } else { + assert!( + !arg.is_trailing_var_arg_set(), + "{}:{}: `Arg::trailing_var_arg` can only apply to last positional", + cmd.get_name(), + arg.get_id() + ); + } + } + + // Next we verify that only the highest index has takes multiple arguments (if any) + let only_highest = |a: &Arg| a.is_multiple() && (a.get_index().unwrap_or(0) != highest_idx); + if cmd.get_positionals().any(only_highest) { + // First we make sure if there is a positional that allows multiple values + // the one before it (second to last) has one of these: + // * a value terminator + // * ArgSettings::Last + // * The last arg is Required + + // We can't pass the closure (it.next()) to the macro directly because each call to + // find() (iterator, not macro) gets called repeatedly. + let last = &cmd.get_keymap()[&KeyType::Position(highest_idx)]; + let second_to_last = &cmd.get_keymap()[&KeyType::Position(highest_idx - 1)]; + + // Either the final positional is required + // Or the second to last has a terminator or .last(true) set + let ok = last.is_required_set() + || (second_to_last.terminator.is_some() || second_to_last.is_last_set()) + || last.is_last_set(); + assert!( + ok, + "Positional argument `{last}` *must* have `required(true)` or `last(true)` set \ + because a prior positional argument (`{second_to_last}`) has `num_args(1..)`" + ); + + // We make sure if the second to last is Multiple the last is ArgSettings::Last + let ok = second_to_last.is_multiple() || last.is_last_set(); + assert!( + ok, + "Only the last positional argument, or second to last positional \ + argument may be set to `.num_args(1..)`" + ); + + // Next we check how many have both Multiple and not a specific number of values set + let count = cmd + .get_positionals() + .filter(|p| { + p.is_multiple_values_set() + && p.get_value_terminator().is_none() + && !p.get_num_args().expect(INTERNAL_ERROR_MSG).is_fixed() + }) + .count(); + let ok = count <= 1 + || (last.is_last_set() + && last.is_multiple() + && second_to_last.is_multiple() + && count == 2); + assert!( + ok, + "Only one positional argument with `.num_args(1..)` set is allowed per \ + command, unless the second one also has .last(true) set" + ); + } + + let mut found = false; + + if cmd.is_allow_missing_positional_set() { + // Check that if a required positional argument is found, all positions with a lower + // index are also required. + let mut foundx2 = false; + + for p in cmd.get_positionals() { + if foundx2 && !p.is_required_set() { + assert!( + p.is_required_set(), + "Found non-required positional argument with a lower \ + index than a required positional argument by two or more: {:?} \ + index {:?}", + p.get_id(), + p.get_index() + ); + } else if p.is_required_set() && !p.is_last_set() { + // Args that .last(true) don't count since they can be required and have + // positionals with a lower index that aren't required + // Imagine: prog <req1> [opt1] -- <req2> + // Both of these are valid invocations: + // $ prog r1 -- r2 + // $ prog r1 o1 -- r2 + if found { + foundx2 = true; + continue; + } + found = true; + continue; + } else { + found = false; + } + } + } else { + // Check that if a required positional argument is found, all positions with a lower + // index are also required + for p in (1..=num_p).rev().filter_map(|n| cmd.get_keymap().get(&n)) { + if found { + assert!( + p.is_required_set(), + "Found non-required positional argument with a lower \ + index than a required positional argument: {:?} index {:?}", + p.get_id(), + p.get_index() + ); + } else if p.is_required_set() && !p.is_last_set() { + // Args that .last(true) don't count since they can be required and have + // positionals with a lower index that aren't required + // Imagine: prog <req1> [opt1] -- <req2> + // Both of these are valid invocations: + // $ prog r1 -- r2 + // $ prog r1 o1 -- r2 + found = true; + continue; + } + } + } + assert!( + cmd.get_positionals().filter(|p| p.is_last_set()).count() < 2, + "Only one positional argument may have last(true) set. Found two." + ); + if cmd + .get_positionals() + .any(|p| p.is_last_set() && p.is_required_set()) + && cmd.has_subcommands() + && !cmd.is_subcommand_negates_reqs_set() + { + panic!( + "Having a required positional argument with .last(true) set *and* child \ + subcommands without setting SubcommandsNegateReqs isn't compatible." + ); + } + + true +} + +fn assert_arg(arg: &Arg) { + debug!("Arg::_debug_asserts:{}", arg.get_id()); + + // Self conflict + // TODO: this check should be recursive + assert!( + !arg.blacklist.iter().any(|x| x == arg.get_id()), + "Argument '{}' cannot conflict with itself", + arg.get_id(), + ); + + assert_eq!( + arg.get_action().takes_values(), + arg.is_takes_value_set(), + "Argument `{}`'s selected action {:?} contradicts `takes_value`", + arg.get_id(), + arg.get_action() + ); + if let Some(action_type_id) = arg.get_action().value_type_id() { + assert_eq!( + action_type_id, + arg.get_value_parser().type_id(), + "Argument `{}`'s selected action {:?} contradicts `value_parser` ({:?})", + arg.get_id(), + arg.get_action(), + arg.get_value_parser() + ); + } + + if arg.get_value_hint() != ValueHint::Unknown { + assert!( + arg.is_takes_value_set(), + "Argument '{}' has value hint but takes no value", + arg.get_id() + ); + + if arg.get_value_hint() == ValueHint::CommandWithArguments { + assert!( + arg.is_multiple_values_set(), + "Argument '{}' uses hint CommandWithArguments and must accept multiple values", + arg.get_id() + ) + } + } + + if arg.index.is_some() { + assert!( + arg.is_positional(), + "Argument '{}' is a positional argument and can't have short or long name versions", + arg.get_id() + ); + assert!( + arg.is_takes_value_set(), + "Argument '{}` is positional and it must take a value but action is {:?}{}", + arg.get_id(), + arg.get_action(), + if arg.get_id() == Id::HELP { + " (`mut_arg` no longer works with implicit `--help`)" + } else if arg.get_id() == Id::VERSION { + " (`mut_arg` no longer works with implicit `--version`)" + } else { + "" + } + ); + } + + let num_vals = arg.get_num_args().expect(INTERNAL_ERROR_MSG); + // This can be the cause of later asserts, so put this first + if num_vals != ValueRange::EMPTY { + // HACK: Don't check for flags to make the derive easier + let num_val_names = arg.get_value_names().unwrap_or(&[]).len(); + if num_vals.max_values() < num_val_names { + panic!( + "Argument {}: Too many value names ({}) compared to `num_args` ({})", + arg.get_id(), + num_val_names, + num_vals + ); + } + } + + assert_eq!( + num_vals.takes_values(), + arg.is_takes_value_set(), + "Argument {}: mismatch between `num_args` ({}) and `takes_value`", + arg.get_id(), + num_vals, + ); + assert_eq!( + num_vals.is_multiple(), + arg.is_multiple_values_set(), + "Argument {}: mismatch between `num_args` ({}) and `multiple_values`", + arg.get_id(), + num_vals, + ); + + if 1 < num_vals.min_values() { + assert!( + !arg.is_require_equals_set(), + "Argument {}: cannot accept more than 1 arg (num_args={}) with require_equals", + arg.get_id(), + num_vals + ); + } + + if num_vals == ValueRange::SINGLE { + assert!( + !arg.is_multiple_values_set(), + "Argument {}: mismatch between `num_args` and `multiple_values`", + arg.get_id() + ); + } + + assert_arg_flags(arg); +} + +fn assert_arg_flags(arg: &Arg) { + macro_rules! checker { + ($a:ident requires $($b:ident)|+) => { + if arg.$a() { + let mut s = String::new(); + + $( + if !arg.$b() { + use std::fmt::Write; + write!(&mut s, " Arg::{} is required when Arg::{} is set.\n", std::stringify!($b), std::stringify!($a)).unwrap(); + } + )+ + + if !s.is_empty() { + panic!("Argument {:?}\n{}", arg.get_id(), s) + } + } + } + } + + checker!(is_hide_possible_values_set requires is_takes_value_set); + checker!(is_allow_hyphen_values_set requires is_takes_value_set); + checker!(is_allow_negative_numbers_set requires is_takes_value_set); + checker!(is_require_equals_set requires is_takes_value_set); + checker!(is_last_set requires is_takes_value_set); + checker!(is_hide_default_value_set requires is_takes_value_set); + checker!(is_multiple_values_set requires is_takes_value_set); + checker!(is_ignore_case_set requires is_takes_value_set); +} diff --git a/vendor/clap_builder/src/builder/ext.rs b/vendor/clap_builder/src/builder/ext.rs new file mode 100644 index 0000000..2fb0d96 --- /dev/null +++ b/vendor/clap_builder/src/builder/ext.rs @@ -0,0 +1,216 @@ +use crate::util::AnyValueId; +use crate::util::FlatMap; + +#[derive(Default, Clone, Debug)] +pub(crate) struct Extensions { + extensions: FlatMap<AnyValueId, BoxedExtension>, +} + +impl Extensions { + #[allow(dead_code)] + pub(crate) fn get<T: Extension>(&self) -> Option<&T> { + let id = AnyValueId::of::<T>(); + self.extensions.get(&id).map(|e| e.as_ref::<T>()) + } + + #[allow(dead_code)] + pub(crate) fn get_mut<T: Extension>(&mut self) -> Option<&mut T> { + let id = AnyValueId::of::<T>(); + self.extensions.get_mut(&id).map(|e| e.as_mut::<T>()) + } + + #[allow(dead_code)] + pub(crate) fn get_or_insert_default<T: Extension + Default>(&mut self) -> &mut T { + let id = AnyValueId::of::<T>(); + self.extensions + .entry(id) + .or_insert_with(|| BoxedExtension::new(T::default())) + .as_mut::<T>() + } + + #[allow(dead_code)] + pub(crate) fn set<T: Extension + Into<BoxedEntry>>(&mut self, tagged: T) -> bool { + let BoxedEntry { id, value } = tagged.into(); + self.extensions.insert(id, value).is_some() + } + + #[allow(dead_code)] + pub(crate) fn remove<T: Extension>(&mut self) -> Option<Box<dyn Extension>> { + let id = AnyValueId::of::<T>(); + self.extensions.remove(&id).map(BoxedExtension::into_inner) + } + + pub(crate) fn update(&mut self, other: &Self) { + for (key, value) in other.extensions.iter() { + self.extensions.insert(*key, value.clone()); + } + } +} + +/// Supports conversion to `Any`. Traits to be extended by `impl_downcast!` must extend `Extension`. +pub(crate) trait Extension: std::fmt::Debug + Send + Sync + 'static { + /// Convert `Box<dyn Trait>` (where `Trait: Extension`) to `Box<dyn Any>`. + /// + /// `Box<dyn Any>` can /// then be further `downcast` into + /// `Box<ConcreteType>` where `ConcreteType` implements `Trait`. + fn into_any(self: Box<Self>) -> Box<dyn std::any::Any>; + /// Clone `&Box<dyn Trait>` (where `Trait: Extension`) to `Box<dyn Extension>`. + /// + /// `Box<dyn Any>` can /// then be further `downcast` into + // `Box<ConcreteType>` where `ConcreteType` implements `Trait`. + fn clone_extension(&self) -> Box<dyn Extension>; + /// Convert `&Trait` (where `Trait: Extension`) to `&Any`. + /// + /// This is needed since Rust cannot /// generate `&Any`'s vtable from + /// `&Trait`'s. + fn as_any(&self) -> &dyn std::any::Any; + /// Convert `&mut Trait` (where `Trait: Extension`) to `&Any`. + /// + /// This is needed since Rust cannot /// generate `&mut Any`'s vtable from + /// `&mut Trait`'s. + fn as_any_mut(&mut self) -> &mut dyn std::any::Any; +} + +impl<T> Extension for T +where + T: Clone + std::fmt::Debug + Send + Sync + 'static, +{ + fn into_any(self: Box<Self>) -> Box<dyn std::any::Any> { + self + } + fn clone_extension(&self) -> Box<dyn Extension> { + Box::new(self.clone()) + } + fn as_any(&self) -> &dyn std::any::Any { + self + } + fn as_any_mut(&mut self) -> &mut dyn std::any::Any { + self + } +} + +impl Clone for Box<dyn Extension> { + fn clone(&self) -> Self { + self.as_ref().clone_extension() + } +} + +#[derive(Clone)] +#[repr(transparent)] +struct BoxedExtension(Box<dyn Extension>); + +impl BoxedExtension { + fn new<T: Extension>(inner: T) -> Self { + Self(Box::new(inner)) + } + + fn into_inner(self) -> Box<dyn Extension> { + self.0 + } + + fn as_ref<T: Extension>(&self) -> &T { + self.0.as_ref().as_any().downcast_ref::<T>().unwrap() + } + + fn as_mut<T: Extension>(&mut self) -> &mut T { + self.0.as_mut().as_any_mut().downcast_mut::<T>().unwrap() + } +} + +impl std::fmt::Debug for BoxedExtension { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> Result<(), std::fmt::Error> { + self.0.fmt(f) + } +} + +#[derive(Clone)] +pub(crate) struct BoxedEntry { + id: AnyValueId, + value: BoxedExtension, +} + +impl BoxedEntry { + pub(crate) fn new(r: impl Extension) -> Self { + let id = AnyValueId::from(&r); + let value = BoxedExtension::new(r); + BoxedEntry { id, value } + } +} + +impl<R: Extension> From<R> for BoxedEntry { + fn from(inner: R) -> Self { + BoxedEntry::new(inner) + } +} + +#[cfg(test)] +mod test { + use super::*; + + #[derive(Default, Copy, Clone, Debug, PartialEq, Eq)] + struct Number(usize); + + #[test] + fn get() { + let mut ext = Extensions::default(); + ext.set(Number(10)); + assert_eq!(ext.get::<Number>(), Some(&Number(10))); + } + + #[test] + fn get_mut() { + let mut ext = Extensions::default(); + ext.set(Number(10)); + *ext.get_mut::<Number>().unwrap() = Number(20); + assert_eq!(ext.get::<Number>(), Some(&Number(20))); + } + + #[test] + fn get_or_insert_default_empty() { + let mut ext = Extensions::default(); + assert_eq!(ext.get_or_insert_default::<Number>(), &Number(0)); + } + + #[test] + fn get_or_insert_default_full() { + let mut ext = Extensions::default(); + ext.set(Number(10)); + assert_eq!(ext.get_or_insert_default::<Number>(), &Number(10)); + } + + #[test] + fn set() { + let mut ext = Extensions::default(); + assert!(!ext.set(Number(10))); + assert_eq!(ext.get::<Number>(), Some(&Number(10))); + assert!(ext.set(Number(20))); + assert_eq!(ext.get::<Number>(), Some(&Number(20))); + } + + #[test] + fn reset() { + let mut ext = Extensions::default(); + assert_eq!(ext.get::<Number>(), None); + + assert!(ext.remove::<Number>().is_none()); + assert_eq!(ext.get::<Number>(), None); + + assert!(!ext.set(Number(10))); + assert_eq!(ext.get::<Number>(), Some(&Number(10))); + + assert!(ext.remove::<Number>().is_some()); + assert_eq!(ext.get::<Number>(), None); + } + + #[test] + fn update() { + let mut ext = Extensions::default(); + assert_eq!(ext.get::<Number>(), None); + + let mut new = Extensions::default(); + assert!(!new.set(Number(10))); + + ext.update(&new); + assert_eq!(ext.get::<Number>(), Some(&Number(10))); + } +} diff --git a/vendor/clap_builder/src/builder/mod.rs b/vendor/clap_builder/src/builder/mod.rs new file mode 100644 index 0000000..320a453 --- /dev/null +++ b/vendor/clap_builder/src/builder/mod.rs @@ -0,0 +1,67 @@ +//! Define [`Command`] line [arguments][`Arg`] + +mod action; +mod app_settings; +mod arg; +mod arg_group; +mod arg_predicate; +mod arg_settings; +mod command; +mod ext; +mod os_str; +mod possible_value; +mod range; +mod resettable; +mod str; +mod styled_str; +mod value_hint; +mod value_parser; + +#[cfg(debug_assertions)] +mod debug_asserts; + +#[cfg(test)] +mod tests; + +pub mod styling; + +pub use self::str::Str; +pub use action::ArgAction; +pub use arg::Arg; +pub use arg_group::ArgGroup; +pub use arg_predicate::ArgPredicate; +pub use command::Command; +pub use os_str::OsStr; +pub use possible_value::PossibleValue; +pub use range::ValueRange; +pub use resettable::IntoResettable; +pub use resettable::Resettable; +pub use styled_str::StyledStr; +pub use styling::Styles; +pub use value_hint::ValueHint; +pub use value_parser::_AutoValueParser; +pub use value_parser::via_prelude; +pub use value_parser::BoolValueParser; +pub use value_parser::BoolishValueParser; +pub use value_parser::EnumValueParser; +pub use value_parser::FalseyValueParser; +pub use value_parser::MapValueParser; +pub use value_parser::NonEmptyStringValueParser; +pub use value_parser::OsStringValueParser; +pub use value_parser::PathBufValueParser; +pub use value_parser::PossibleValuesParser; +pub use value_parser::RangedI64ValueParser; +pub use value_parser::RangedU64ValueParser; +pub use value_parser::StringValueParser; +pub use value_parser::TryMapValueParser; +pub use value_parser::TypedValueParser; +pub use value_parser::UnknownArgumentValueParser; +pub use value_parser::ValueParser; +pub use value_parser::ValueParserFactory; +pub use value_parser::_AnonymousValueParser; + +#[allow(unused_imports)] +pub(crate) use self::str::Inner as StrInner; +pub(crate) use action::CountType; +pub(crate) use arg_settings::{ArgFlags, ArgSettings}; +pub(crate) use command::AppTag; diff --git a/vendor/clap_builder/src/builder/os_str.rs b/vendor/clap_builder/src/builder/os_str.rs new file mode 100644 index 0000000..fe8928e --- /dev/null +++ b/vendor/clap_builder/src/builder/os_str.rs @@ -0,0 +1,336 @@ +use crate::builder::Str; + +/// A UTF-8-encoded fixed string +/// +/// **NOTE:** To support dynamic values (i.e. `OsString`), enable the `string` +/// feature +#[derive(Default, Clone, Eq, PartialEq, PartialOrd, Ord, Hash)] +pub struct OsStr { + name: Inner, +} + +impl OsStr { + #[cfg(feature = "string")] + pub(crate) fn from_string(name: std::ffi::OsString) -> Self { + Self { + name: Inner::from_string(name), + } + } + + #[cfg(feature = "string")] + pub(crate) fn from_ref(name: &std::ffi::OsStr) -> Self { + Self { + name: Inner::from_ref(name), + } + } + + pub(crate) fn from_static_ref(name: &'static std::ffi::OsStr) -> Self { + Self { + name: Inner::from_static_ref(name), + } + } + + /// Get the raw string as an `std::ffi::OsStr` + pub fn as_os_str(&self) -> &std::ffi::OsStr { + self.name.as_os_str() + } + + /// Get the raw string as an `OsString` + pub fn to_os_string(&self) -> std::ffi::OsString { + self.as_os_str().to_owned() + } +} + +impl From<&'_ OsStr> for OsStr { + fn from(id: &'_ OsStr) -> Self { + id.clone() + } +} + +#[cfg(feature = "string")] +impl From<Str> for OsStr { + fn from(id: Str) -> Self { + match id.into_inner() { + crate::builder::StrInner::Static(s) => Self::from_static_ref(std::ffi::OsStr::new(s)), + crate::builder::StrInner::Owned(s) => Self::from_ref(std::ffi::OsStr::new(s.as_ref())), + } + } +} + +#[cfg(not(feature = "string"))] +impl From<Str> for OsStr { + fn from(id: Str) -> Self { + Self::from_static_ref(std::ffi::OsStr::new(id.into_inner().0)) + } +} + +#[cfg(feature = "perf")] +impl From<&'_ Str> for OsStr { + fn from(id: &'_ Str) -> Self { + match id.clone().into_inner() { + crate::builder::StrInner::Static(s) => Self::from_static_ref(std::ffi::OsStr::new(s)), + crate::builder::StrInner::Owned(s) => Self::from_ref(std::ffi::OsStr::new(s.as_ref())), + } + } +} + +impl From<&'_ Str> for OsStr { + fn from(id: &'_ Str) -> Self { + id.clone().into() + } +} + +#[cfg(feature = "string")] +impl From<std::ffi::OsString> for OsStr { + fn from(name: std::ffi::OsString) -> Self { + Self::from_string(name) + } +} + +#[cfg(feature = "string")] +impl From<&'_ std::ffi::OsString> for OsStr { + fn from(name: &'_ std::ffi::OsString) -> Self { + Self::from_ref(name.as_os_str()) + } +} + +#[cfg(feature = "string")] +impl From<std::string::String> for OsStr { + fn from(name: std::string::String) -> Self { + Self::from_string(name.into()) + } +} + +#[cfg(feature = "string")] +impl From<&'_ std::string::String> for OsStr { + fn from(name: &'_ std::string::String) -> Self { + Self::from_ref(name.as_str().as_ref()) + } +} + +impl From<&'static std::ffi::OsStr> for OsStr { + fn from(name: &'static std::ffi::OsStr) -> Self { + Self::from_static_ref(name) + } +} + +impl From<&'_ &'static std::ffi::OsStr> for OsStr { + fn from(name: &'_ &'static std::ffi::OsStr) -> Self { + Self::from_static_ref(name) + } +} + +impl From<&'static str> for OsStr { + fn from(name: &'static str) -> Self { + Self::from_static_ref(name.as_ref()) + } +} + +impl From<&'_ &'static str> for OsStr { + fn from(name: &'_ &'static str) -> Self { + Self::from_static_ref((*name).as_ref()) + } +} + +impl From<OsStr> for std::ffi::OsString { + fn from(name: OsStr) -> Self { + name.name.into_os_string() + } +} + +impl From<OsStr> for std::path::PathBuf { + fn from(name: OsStr) -> Self { + std::ffi::OsString::from(name).into() + } +} + +impl std::fmt::Debug for OsStr { + #[inline] + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + std::fmt::Debug::fmt(self.as_os_str(), f) + } +} + +impl std::ops::Deref for OsStr { + type Target = std::ffi::OsStr; + + #[inline] + fn deref(&self) -> &std::ffi::OsStr { + self.as_os_str() + } +} + +impl AsRef<std::ffi::OsStr> for OsStr { + #[inline] + fn as_ref(&self) -> &std::ffi::OsStr { + self.as_os_str() + } +} + +impl AsRef<std::path::Path> for OsStr { + #[inline] + fn as_ref(&self) -> &std::path::Path { + std::path::Path::new(self) + } +} + +impl std::borrow::Borrow<std::ffi::OsStr> for OsStr { + #[inline] + fn borrow(&self) -> &std::ffi::OsStr { + self.as_os_str() + } +} + +impl PartialEq<str> for OsStr { + #[inline] + fn eq(&self, other: &str) -> bool { + PartialEq::eq(self.as_os_str(), other) + } +} +impl PartialEq<OsStr> for str { + #[inline] + fn eq(&self, other: &OsStr) -> bool { + PartialEq::eq(self, other.as_os_str()) + } +} + +impl PartialEq<&'_ str> for OsStr { + #[inline] + fn eq(&self, other: &&str) -> bool { + PartialEq::eq(self.as_os_str(), *other) + } +} +impl PartialEq<OsStr> for &'_ str { + #[inline] + fn eq(&self, other: &OsStr) -> bool { + PartialEq::eq(*self, other.as_os_str()) + } +} + +impl PartialEq<&'_ std::ffi::OsStr> for OsStr { + #[inline] + fn eq(&self, other: &&std::ffi::OsStr) -> bool { + PartialEq::eq(self.as_os_str(), *other) + } +} +impl PartialEq<OsStr> for &'_ std::ffi::OsStr { + #[inline] + fn eq(&self, other: &OsStr) -> bool { + PartialEq::eq(*self, other.as_os_str()) + } +} + +impl PartialEq<std::string::String> for OsStr { + #[inline] + fn eq(&self, other: &std::string::String) -> bool { + PartialEq::eq(self.as_os_str(), other.as_str()) + } +} +impl PartialEq<OsStr> for std::string::String { + #[inline] + fn eq(&self, other: &OsStr) -> bool { + PartialEq::eq(self.as_str(), other.as_os_str()) + } +} + +impl PartialEq<std::ffi::OsString> for OsStr { + #[inline] + fn eq(&self, other: &std::ffi::OsString) -> bool { + PartialEq::eq(self.as_os_str(), other.as_os_str()) + } +} +impl PartialEq<OsStr> for std::ffi::OsString { + #[inline] + fn eq(&self, other: &OsStr) -> bool { + PartialEq::eq(self.as_os_str(), other.as_os_str()) + } +} + +#[cfg(feature = "string")] +pub(crate) mod inner { + #[derive(Clone)] + pub(crate) enum Inner { + Static(&'static std::ffi::OsStr), + Owned(Box<std::ffi::OsStr>), + } + + impl Inner { + pub(crate) fn from_string(name: std::ffi::OsString) -> Self { + Self::Owned(name.into_boxed_os_str()) + } + + pub(crate) fn from_ref(name: &std::ffi::OsStr) -> Self { + Self::Owned(Box::from(name)) + } + + pub(crate) fn from_static_ref(name: &'static std::ffi::OsStr) -> Self { + Self::Static(name) + } + + pub(crate) fn as_os_str(&self) -> &std::ffi::OsStr { + match self { + Self::Static(s) => s, + Self::Owned(s) => s.as_ref(), + } + } + + pub(crate) fn into_os_string(self) -> std::ffi::OsString { + self.as_os_str().to_owned() + } + } +} + +#[cfg(not(feature = "string"))] +pub(crate) mod inner { + #[derive(Clone)] + pub(crate) struct Inner(&'static std::ffi::OsStr); + + impl Inner { + pub(crate) fn from_static_ref(name: &'static std::ffi::OsStr) -> Self { + Self(name) + } + + pub(crate) fn as_os_str(&self) -> &std::ffi::OsStr { + self.0 + } + + pub(crate) fn into_os_string(self) -> std::ffi::OsString { + self.as_os_str().to_owned() + } + } +} + +pub(crate) use inner::Inner; + +impl Default for Inner { + fn default() -> Self { + Self::from_static_ref(std::ffi::OsStr::new("")) + } +} + +impl PartialEq for Inner { + fn eq(&self, other: &Inner) -> bool { + self.as_os_str() == other.as_os_str() + } +} + +impl PartialOrd for Inner { + fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> { + Some(self.cmp(other)) + } +} + +impl Ord for Inner { + fn cmp(&self, other: &Inner) -> std::cmp::Ordering { + self.as_os_str().cmp(other.as_os_str()) + } +} + +impl Eq for Inner {} + +impl std::hash::Hash for Inner { + #[inline] + fn hash<H: std::hash::Hasher>(&self, state: &mut H) { + self.as_os_str().hash(state); + } +} diff --git a/vendor/clap_builder/src/builder/possible_value.rs b/vendor/clap_builder/src/builder/possible_value.rs new file mode 100644 index 0000000..de7e543 --- /dev/null +++ b/vendor/clap_builder/src/builder/possible_value.rs @@ -0,0 +1,229 @@ +use crate::builder::IntoResettable; +use crate::builder::Str; +use crate::builder::StyledStr; +use crate::util::eq_ignore_case; + +/// A possible value of an argument. +/// +/// This is used for specifying [possible values] of [Args]. +/// +/// See also [`PossibleValuesParser`][crate::builder::PossibleValuesParser] +/// +/// **NOTE:** Most likely you can use strings, rather than `PossibleValue` as it is only required +/// to [hide] single values from help messages and shell completions or to attach [help] to +/// possible values. +/// +/// # Examples +/// +/// ```rust +/// # use clap_builder as clap; +/// # use clap::{Arg, builder::PossibleValue, ArgAction}; +/// let cfg = Arg::new("config") +/// .action(ArgAction::Set) +/// .value_name("FILE") +/// .value_parser([ +/// PossibleValue::new("fast"), +/// PossibleValue::new("slow").help("slower than fast"), +/// PossibleValue::new("secret speed").hide(true) +/// ]); +/// ``` +/// +/// [Args]: crate::Arg +/// [possible values]: crate::builder::ValueParser::possible_values +/// [hide]: PossibleValue::hide() +/// [help]: PossibleValue::help() +#[derive(Debug, Default, Clone, PartialEq, Eq)] +pub struct PossibleValue { + name: Str, + help: Option<StyledStr>, + aliases: Vec<Str>, // (name, visible) + hide: bool, +} + +impl PossibleValue { + /// Create a [`PossibleValue`] with its name. + /// + /// The name will be used to decide whether this value was provided by the user to an argument. + /// + /// **NOTE:** In case it is not [hidden] it will also be shown in help messages for arguments + /// that use it as a [possible value] and have not hidden them through [`Arg::hide_possible_values(true)`]. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::builder::PossibleValue; + /// PossibleValue::new("fast") + /// # ; + /// ``` + /// [hidden]: PossibleValue::hide + /// [possible value]: crate::builder::PossibleValuesParser + /// [`Arg::hide_possible_values(true)`]: crate::Arg::hide_possible_values() + pub fn new(name: impl Into<Str>) -> Self { + PossibleValue { + name: name.into(), + ..Default::default() + } + } + + /// Sets the help description of the value. + /// + /// This is typically displayed in completions (where supported) and should be a short, one-line + /// description. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::builder::PossibleValue; + /// PossibleValue::new("slow") + /// .help("not fast") + /// # ; + /// ``` + #[inline] + #[must_use] + pub fn help(mut self, help: impl IntoResettable<StyledStr>) -> Self { + self.help = help.into_resettable().into_option(); + self + } + + /// Hides this value from help and shell completions. + /// + /// This is an alternative to hiding through [`Arg::hide_possible_values(true)`], if you only + /// want to hide some values. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::builder::PossibleValue; + /// PossibleValue::new("secret") + /// .hide(true) + /// # ; + /// ``` + /// [`Arg::hide_possible_values(true)`]: crate::Arg::hide_possible_values() + #[inline] + #[must_use] + pub fn hide(mut self, yes: bool) -> Self { + self.hide = yes; + self + } + + /// Sets a *hidden* alias for this argument value. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::builder::PossibleValue; + /// PossibleValue::new("slow") + /// .alias("not-fast") + /// # ; + /// ``` + #[must_use] + pub fn alias(mut self, name: impl IntoResettable<Str>) -> Self { + if let Some(name) = name.into_resettable().into_option() { + self.aliases.push(name); + } else { + self.aliases.clear(); + } + self + } + + /// Sets multiple *hidden* aliases for this argument value. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::builder::PossibleValue; + /// PossibleValue::new("slow") + /// .aliases(["not-fast", "snake-like"]) + /// # ; + /// ``` + #[must_use] + pub fn aliases(mut self, names: impl IntoIterator<Item = impl Into<Str>>) -> Self { + self.aliases.extend(names.into_iter().map(|a| a.into())); + self + } +} + +/// Reflection +impl PossibleValue { + /// Get the name of the argument value + #[inline] + pub fn get_name(&self) -> &str { + self.name.as_str() + } + + /// Get the help specified for this argument, if any + #[inline] + pub fn get_help(&self) -> Option<&StyledStr> { + self.help.as_ref() + } + + /// Report if [`PossibleValue::hide`] is set + #[inline] + pub fn is_hide_set(&self) -> bool { + self.hide + } + + /// Report if PossibleValue is not hidden and has a help message + pub(crate) fn should_show_help(&self) -> bool { + !self.hide && self.help.is_some() + } + + /// Get the name if argument value is not hidden, `None` otherwise, + /// but wrapped in quotes if it contains whitespace + #[cfg(feature = "help")] + pub(crate) fn get_visible_quoted_name(&self) -> Option<std::borrow::Cow<'_, str>> { + if !self.hide { + Some(if self.name.contains(char::is_whitespace) { + format!("{:?}", self.name).into() + } else { + self.name.as_str().into() + }) + } else { + None + } + } + + /// Returns all valid values of the argument value. + /// + /// Namely the name and all aliases. + pub fn get_name_and_aliases(&self) -> impl Iterator<Item = &str> + '_ { + std::iter::once(self.get_name()).chain(self.aliases.iter().map(|s| s.as_str())) + } + + /// Tests if the value is valid for this argument value + /// + /// The value is valid if it is either the name or one of the aliases. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::builder::PossibleValue; + /// let arg_value = PossibleValue::new("fast").alias("not-slow"); + /// + /// assert!(arg_value.matches("fast", false)); + /// assert!(arg_value.matches("not-slow", false)); + /// + /// assert!(arg_value.matches("FAST", true)); + /// assert!(!arg_value.matches("FAST", false)); + /// ``` + pub fn matches(&self, value: &str, ignore_case: bool) -> bool { + if ignore_case { + self.get_name_and_aliases() + .any(|name| eq_ignore_case(name, value)) + } else { + self.get_name_and_aliases().any(|name| name == value) + } + } +} + +impl<S: Into<Str>> From<S> for PossibleValue { + fn from(s: S) -> Self { + Self::new(s) + } +} diff --git a/vendor/clap_builder/src/builder/range.rs b/vendor/clap_builder/src/builder/range.rs new file mode 100644 index 0000000..158d02c --- /dev/null +++ b/vendor/clap_builder/src/builder/range.rs @@ -0,0 +1,286 @@ +/// Values per occurrence for an argument +#[derive(Copy, Clone, PartialEq, Eq, Hash)] +pub struct ValueRange { + start_inclusive: usize, + end_inclusive: usize, +} + +impl ValueRange { + /// Nor argument values, or a flag + pub const EMPTY: Self = Self { + start_inclusive: 0, + end_inclusive: 0, + }; + + /// A single argument value, the most common case for options + pub const SINGLE: Self = Self { + start_inclusive: 1, + end_inclusive: 1, + }; + + /// Create a range + /// + /// # Panics + /// + /// If the end is less than the start (debug builds) + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::builder::ValueRange; + /// let range = ValueRange::new(5); + /// let range = ValueRange::new(5..10); + /// let range = ValueRange::new(5..=10); + /// let range = ValueRange::new(5..); + /// let range = ValueRange::new(..10); + /// let range = ValueRange::new(..=10); + /// ``` + /// + /// While this will panic: + /// ```should_panic + /// # use clap_builder as clap; + /// # use clap::builder::ValueRange; + /// let range = ValueRange::new(10..5); // Panics! + /// ``` + pub fn new(range: impl Into<Self>) -> Self { + range.into() + } + + pub(crate) fn raw(start_inclusive: usize, end_inclusive: usize) -> Self { + debug_assert!(start_inclusive <= end_inclusive); + Self { + start_inclusive, + end_inclusive, + } + } + + /// Fewest number of values the argument accepts + pub fn min_values(&self) -> usize { + self.start_inclusive + } + + /// Most number of values the argument accepts + pub fn max_values(&self) -> usize { + self.end_inclusive + } + + /// Report whether the argument takes any values (ie is a flag) + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::builder::ValueRange; + /// let range = ValueRange::new(5); + /// assert!(range.takes_values()); + /// + /// let range = ValueRange::new(0); + /// assert!(!range.takes_values()); + /// ``` + pub fn takes_values(&self) -> bool { + self.end_inclusive != 0 + } + + pub(crate) fn is_unbounded(&self) -> bool { + self.end_inclusive == usize::MAX + } + + pub(crate) fn is_fixed(&self) -> bool { + self.start_inclusive == self.end_inclusive + } + + pub(crate) fn is_multiple(&self) -> bool { + self.start_inclusive != self.end_inclusive || 1 < self.start_inclusive + } + + pub(crate) fn num_values(&self) -> Option<usize> { + self.is_fixed().then_some(self.start_inclusive) + } + + pub(crate) fn accepts_more(&self, current: usize) -> bool { + current < self.end_inclusive + } +} + +impl std::ops::RangeBounds<usize> for ValueRange { + fn start_bound(&self) -> std::ops::Bound<&usize> { + std::ops::Bound::Included(&self.start_inclusive) + } + + fn end_bound(&self) -> std::ops::Bound<&usize> { + std::ops::Bound::Included(&self.end_inclusive) + } +} + +impl Default for ValueRange { + fn default() -> Self { + Self::SINGLE + } +} + +impl From<usize> for ValueRange { + fn from(fixed: usize) -> Self { + (fixed..=fixed).into() + } +} + +impl From<std::ops::Range<usize>> for ValueRange { + fn from(range: std::ops::Range<usize>) -> Self { + let start_inclusive = range.start; + let end_inclusive = range.end.saturating_sub(1); + Self::raw(start_inclusive, end_inclusive) + } +} + +impl From<std::ops::RangeFull> for ValueRange { + fn from(_: std::ops::RangeFull) -> Self { + let start_inclusive = 0; + let end_inclusive = usize::MAX; + Self::raw(start_inclusive, end_inclusive) + } +} + +impl From<std::ops::RangeFrom<usize>> for ValueRange { + fn from(range: std::ops::RangeFrom<usize>) -> Self { + let start_inclusive = range.start; + let end_inclusive = usize::MAX; + Self::raw(start_inclusive, end_inclusive) + } +} + +impl From<std::ops::RangeTo<usize>> for ValueRange { + fn from(range: std::ops::RangeTo<usize>) -> Self { + let start_inclusive = 0; + let end_inclusive = range.end.saturating_sub(1); + Self::raw(start_inclusive, end_inclusive) + } +} + +impl From<std::ops::RangeInclusive<usize>> for ValueRange { + fn from(range: std::ops::RangeInclusive<usize>) -> Self { + let start_inclusive = *range.start(); + let end_inclusive = *range.end(); + Self::raw(start_inclusive, end_inclusive) + } +} + +impl From<std::ops::RangeToInclusive<usize>> for ValueRange { + fn from(range: std::ops::RangeToInclusive<usize>) -> Self { + let start_inclusive = 0; + let end_inclusive = range.end; + Self::raw(start_inclusive, end_inclusive) + } +} + +impl std::fmt::Display for ValueRange { + fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result { + ok!(self.start_inclusive.fmt(f)); + if !self.is_fixed() { + ok!("..=".fmt(f)); + ok!(self.end_inclusive.fmt(f)); + } + Ok(()) + } +} + +impl std::fmt::Debug for ValueRange { + fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result { + write!(f, "{self}") + } +} + +#[cfg(test)] +mod test { + use super::*; + + use std::ops::RangeBounds; + + #[test] + fn from_fixed() { + let range: ValueRange = 5.into(); + assert_eq!(range.start_bound(), std::ops::Bound::Included(&5)); + assert_eq!(range.end_bound(), std::ops::Bound::Included(&5)); + assert!(range.is_fixed()); + assert!(range.is_multiple()); + assert_eq!(range.num_values(), Some(5)); + assert!(range.takes_values()); + } + + #[test] + fn from_fixed_empty() { + let range: ValueRange = 0.into(); + assert_eq!(range.start_bound(), std::ops::Bound::Included(&0)); + assert_eq!(range.end_bound(), std::ops::Bound::Included(&0)); + assert!(range.is_fixed()); + assert!(!range.is_multiple()); + assert_eq!(range.num_values(), Some(0)); + assert!(!range.takes_values()); + } + + #[test] + fn from_range() { + let range: ValueRange = (5..10).into(); + assert_eq!(range.start_bound(), std::ops::Bound::Included(&5)); + assert_eq!(range.end_bound(), std::ops::Bound::Included(&9)); + assert!(!range.is_fixed()); + assert!(range.is_multiple()); + assert_eq!(range.num_values(), None); + assert!(range.takes_values()); + } + + #[test] + fn from_range_inclusive() { + let range: ValueRange = (5..=10).into(); + assert_eq!(range.start_bound(), std::ops::Bound::Included(&5)); + assert_eq!(range.end_bound(), std::ops::Bound::Included(&10)); + assert!(!range.is_fixed()); + assert!(range.is_multiple()); + assert_eq!(range.num_values(), None); + assert!(range.takes_values()); + } + + #[test] + fn from_range_full() { + let range: ValueRange = (..).into(); + assert_eq!(range.start_bound(), std::ops::Bound::Included(&0)); + assert_eq!(range.end_bound(), std::ops::Bound::Included(&usize::MAX)); + assert!(!range.is_fixed()); + assert!(range.is_multiple()); + assert_eq!(range.num_values(), None); + assert!(range.takes_values()); + } + + #[test] + fn from_range_from() { + let range: ValueRange = (5..).into(); + assert_eq!(range.start_bound(), std::ops::Bound::Included(&5)); + assert_eq!(range.end_bound(), std::ops::Bound::Included(&usize::MAX)); + assert!(!range.is_fixed()); + assert!(range.is_multiple()); + assert_eq!(range.num_values(), None); + assert!(range.takes_values()); + } + + #[test] + fn from_range_to() { + let range: ValueRange = (..10).into(); + assert_eq!(range.start_bound(), std::ops::Bound::Included(&0)); + assert_eq!(range.end_bound(), std::ops::Bound::Included(&9)); + assert!(!range.is_fixed()); + assert!(range.is_multiple()); + assert_eq!(range.num_values(), None); + assert!(range.takes_values()); + } + + #[test] + fn from_range_to_inclusive() { + let range: ValueRange = (..=10).into(); + assert_eq!(range.start_bound(), std::ops::Bound::Included(&0)); + assert_eq!(range.end_bound(), std::ops::Bound::Included(&10)); + assert!(!range.is_fixed()); + assert!(range.is_multiple()); + assert_eq!(range.num_values(), None); + assert!(range.takes_values()); + } +} diff --git a/vendor/clap_builder/src/builder/resettable.rs b/vendor/clap_builder/src/builder/resettable.rs new file mode 100644 index 0000000..0572740 --- /dev/null +++ b/vendor/clap_builder/src/builder/resettable.rs @@ -0,0 +1,212 @@ +// Unlike `impl Into<Option<T>>` or `Option<impl Into<T>>`, this isn't ambiguous for the `None` +// case. + +use crate::builder::ArgAction; +use crate::builder::OsStr; +use crate::builder::Str; +use crate::builder::StyledStr; +use crate::builder::ValueHint; +use crate::builder::ValueParser; +use crate::builder::ValueRange; + +/// Clearable builder value +/// +/// This allows a builder function to both accept any value that can [`Into::into`] `T` (like +/// `&str` into `OsStr`) as well as `None` to reset it to the default. This is needed to +/// workaround a limitation where you can't have a function argument that is `impl Into<Option<T>>` +/// where `T` is `impl Into<S>` accept `None` as its type is ambiguous. +/// +/// # Example +/// +/// ```rust +/// # use clap_builder as clap; +/// # use clap::Command; +/// # use clap::Arg; +/// fn common() -> Command { +/// Command::new("cli") +/// .arg(Arg::new("input").short('i').long("input")) +/// } +/// let mut command = common(); +/// command.mut_arg("input", |arg| arg.short(None)); +/// ``` +#[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)] +pub enum Resettable<T> { + /// Overwrite builder value + Value(T), + /// Reset builder value + Reset, +} + +impl<T> Resettable<T> { + pub(crate) fn into_option(self) -> Option<T> { + match self { + Self::Value(t) => Some(t), + Self::Reset => None, + } + } +} + +impl<T> From<T> for Resettable<T> { + fn from(other: T) -> Self { + Self::Value(other) + } +} + +impl<T> From<Option<T>> for Resettable<T> { + fn from(other: Option<T>) -> Self { + match other { + Some(inner) => Self::Value(inner), + None => Self::Reset, + } + } +} + +/// Convert to the intended resettable type +pub trait IntoResettable<T> { + /// Convert to the intended resettable type + fn into_resettable(self) -> Resettable<T>; +} + +impl IntoResettable<char> for Option<char> { + fn into_resettable(self) -> Resettable<char> { + match self { + Some(s) => Resettable::Value(s), + None => Resettable::Reset, + } + } +} + +impl IntoResettable<usize> for Option<usize> { + fn into_resettable(self) -> Resettable<usize> { + match self { + Some(s) => Resettable::Value(s), + None => Resettable::Reset, + } + } +} + +impl IntoResettable<ArgAction> for Option<ArgAction> { + fn into_resettable(self) -> Resettable<ArgAction> { + match self { + Some(s) => Resettable::Value(s), + None => Resettable::Reset, + } + } +} + +impl IntoResettable<ValueHint> for Option<ValueHint> { + fn into_resettable(self) -> Resettable<ValueHint> { + match self { + Some(s) => Resettable::Value(s), + None => Resettable::Reset, + } + } +} + +impl IntoResettable<ValueParser> for Option<ValueParser> { + fn into_resettable(self) -> Resettable<ValueParser> { + match self { + Some(s) => Resettable::Value(s), + None => Resettable::Reset, + } + } +} + +impl IntoResettable<StyledStr> for Option<&'static str> { + fn into_resettable(self) -> Resettable<StyledStr> { + match self { + Some(s) => Resettable::Value(s.into()), + None => Resettable::Reset, + } + } +} + +impl IntoResettable<OsStr> for Option<&'static str> { + fn into_resettable(self) -> Resettable<OsStr> { + match self { + Some(s) => Resettable::Value(s.into()), + None => Resettable::Reset, + } + } +} + +impl IntoResettable<Str> for Option<&'static str> { + fn into_resettable(self) -> Resettable<Str> { + match self { + Some(s) => Resettable::Value(s.into()), + None => Resettable::Reset, + } + } +} + +impl<T> IntoResettable<T> for Resettable<T> { + fn into_resettable(self) -> Resettable<T> { + self + } +} + +impl IntoResettable<char> for char { + fn into_resettable(self) -> Resettable<char> { + Resettable::Value(self) + } +} + +impl IntoResettable<usize> for usize { + fn into_resettable(self) -> Resettable<usize> { + Resettable::Value(self) + } +} + +impl IntoResettable<ArgAction> for ArgAction { + fn into_resettable(self) -> Resettable<ArgAction> { + Resettable::Value(self) + } +} + +impl IntoResettable<ValueHint> for ValueHint { + fn into_resettable(self) -> Resettable<ValueHint> { + Resettable::Value(self) + } +} + +impl<I: Into<ValueRange>> IntoResettable<ValueRange> for I { + fn into_resettable(self) -> Resettable<ValueRange> { + Resettable::Value(self.into()) + } +} + +impl<I: Into<ValueParser>> IntoResettable<ValueParser> for I { + fn into_resettable(self) -> Resettable<ValueParser> { + Resettable::Value(self.into()) + } +} + +impl<I: Into<String>> IntoResettable<String> for I { + fn into_resettable(self) -> Resettable<String> { + Resettable::Value(self.into()) + } +} + +impl<I: Into<StyledStr>> IntoResettable<StyledStr> for I { + fn into_resettable(self) -> Resettable<StyledStr> { + Resettable::Value(self.into()) + } +} + +impl<I: Into<OsStr>> IntoResettable<OsStr> for I { + fn into_resettable(self) -> Resettable<OsStr> { + Resettable::Value(self.into()) + } +} + +impl<I: Into<Str>> IntoResettable<Str> for I { + fn into_resettable(self) -> Resettable<Str> { + Resettable::Value(self.into()) + } +} + +impl<I: Into<crate::Id>> IntoResettable<crate::Id> for I { + fn into_resettable(self) -> Resettable<crate::Id> { + Resettable::Value(self.into()) + } +} diff --git a/vendor/clap_builder/src/builder/str.rs b/vendor/clap_builder/src/builder/str.rs new file mode 100644 index 0000000..cf87691 --- /dev/null +++ b/vendor/clap_builder/src/builder/str.rs @@ -0,0 +1,310 @@ +/// A UTF-8-encoded fixed string +/// +/// **NOTE:** To support dynamic values (i.e. `String`), enable the `string` +/// feature +#[derive(Default, Clone, Eq, PartialEq, PartialOrd, Ord, Hash)] +pub struct Str { + name: Inner, +} + +impl Str { + #[cfg(feature = "string")] + pub(crate) fn from_string(name: std::string::String) -> Self { + Self { + name: Inner::from_string(name), + } + } + + #[cfg(feature = "string")] + pub(crate) fn from_ref(name: &str) -> Self { + Self { + name: Inner::from_ref(name), + } + } + + pub(crate) fn from_static_ref(name: &'static str) -> Self { + Self { + name: Inner::from_static_ref(name), + } + } + + pub(crate) fn into_inner(self) -> Inner { + self.name + } + + /// Get the raw string of the `Str` + pub fn as_str(&self) -> &str { + self.name.as_str() + } +} + +impl From<&'_ Str> for Str { + fn from(id: &'_ Str) -> Self { + id.clone() + } +} + +#[cfg(feature = "string")] +impl From<std::string::String> for Str { + fn from(name: std::string::String) -> Self { + Self::from_string(name) + } +} + +#[cfg(feature = "string")] +impl From<&'_ std::string::String> for Str { + fn from(name: &'_ std::string::String) -> Self { + Self::from_ref(name.as_str()) + } +} + +impl From<&'static str> for Str { + fn from(name: &'static str) -> Self { + Self::from_static_ref(name) + } +} + +impl From<&'_ &'static str> for Str { + fn from(name: &'_ &'static str) -> Self { + Self::from_static_ref(name) + } +} + +impl From<Str> for String { + fn from(name: Str) -> Self { + name.name.into_string() + } +} + +impl From<Str> for Vec<u8> { + fn from(name: Str) -> Self { + String::from(name).into() + } +} + +impl From<Str> for std::ffi::OsString { + fn from(name: Str) -> Self { + String::from(name).into() + } +} + +impl From<Str> for std::path::PathBuf { + fn from(name: Str) -> Self { + String::from(name).into() + } +} + +impl std::fmt::Display for Str { + #[inline] + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + std::fmt::Display::fmt(self.as_str(), f) + } +} + +impl std::fmt::Debug for Str { + #[inline] + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + std::fmt::Debug::fmt(self.as_str(), f) + } +} + +impl std::ops::Deref for Str { + type Target = str; + + #[inline] + fn deref(&self) -> &str { + self.as_str() + } +} + +impl AsRef<str> for Str { + #[inline] + fn as_ref(&self) -> &str { + self.as_str() + } +} + +impl AsRef<[u8]> for Str { + #[inline] + fn as_ref(&self) -> &[u8] { + self.as_bytes() + } +} + +impl AsRef<std::ffi::OsStr> for Str { + #[inline] + fn as_ref(&self) -> &std::ffi::OsStr { + (**self).as_ref() + } +} + +impl AsRef<std::path::Path> for Str { + #[inline] + fn as_ref(&self) -> &std::path::Path { + std::path::Path::new(self) + } +} + +impl std::borrow::Borrow<str> for Str { + #[inline] + fn borrow(&self) -> &str { + self.as_str() + } +} + +impl PartialEq<str> for Str { + #[inline] + fn eq(&self, other: &str) -> bool { + PartialEq::eq(self.as_str(), other) + } +} +impl PartialEq<Str> for str { + #[inline] + fn eq(&self, other: &Str) -> bool { + PartialEq::eq(self, other.as_str()) + } +} + +impl PartialEq<&'_ str> for Str { + #[inline] + fn eq(&self, other: &&str) -> bool { + PartialEq::eq(self.as_str(), *other) + } +} +impl PartialEq<Str> for &'_ str { + #[inline] + fn eq(&self, other: &Str) -> bool { + PartialEq::eq(*self, other.as_str()) + } +} + +impl PartialEq<std::ffi::OsStr> for Str { + #[inline] + fn eq(&self, other: &std::ffi::OsStr) -> bool { + PartialEq::eq(self.as_str(), other) + } +} +impl PartialEq<Str> for std::ffi::OsStr { + #[inline] + fn eq(&self, other: &Str) -> bool { + PartialEq::eq(self, other.as_str()) + } +} + +impl PartialEq<&'_ std::ffi::OsStr> for Str { + #[inline] + fn eq(&self, other: &&std::ffi::OsStr) -> bool { + PartialEq::eq(self.as_str(), *other) + } +} +impl PartialEq<Str> for &'_ std::ffi::OsStr { + #[inline] + fn eq(&self, other: &Str) -> bool { + PartialEq::eq(*self, other.as_str()) + } +} + +impl PartialEq<std::string::String> for Str { + #[inline] + fn eq(&self, other: &std::string::String) -> bool { + PartialEq::eq(self.as_str(), other.as_str()) + } +} +impl PartialEq<Str> for std::string::String { + #[inline] + fn eq(&self, other: &Str) -> bool { + PartialEq::eq(self.as_str(), other.as_str()) + } +} + +#[cfg(feature = "string")] +pub(crate) mod inner { + #[derive(Clone)] + pub(crate) enum Inner { + Static(&'static str), + Owned(Box<str>), + } + + impl Inner { + pub(crate) fn from_string(name: std::string::String) -> Self { + Self::Owned(name.into_boxed_str()) + } + + pub(crate) fn from_ref(name: &str) -> Self { + Self::Owned(Box::from(name)) + } + + pub(crate) fn from_static_ref(name: &'static str) -> Self { + Self::Static(name) + } + + pub(crate) fn as_str(&self) -> &str { + match self { + Self::Static(s) => s, + Self::Owned(s) => s.as_ref(), + } + } + + pub(crate) fn into_string(self) -> String { + match self { + Self::Static(s) => s.to_owned(), + Self::Owned(s) => s.into(), + } + } + } +} + +#[cfg(not(feature = "string"))] +pub(crate) mod inner { + #[derive(Clone)] + pub(crate) struct Inner(pub(crate) &'static str); + + impl Inner { + pub(crate) fn from_static_ref(name: &'static str) -> Self { + Self(name) + } + + pub(crate) fn as_str(&self) -> &str { + self.0 + } + + pub(crate) fn into_string(self) -> String { + self.as_str().to_owned() + } + } +} + +pub(crate) use inner::Inner; + +impl Default for Inner { + fn default() -> Self { + Self::from_static_ref("") + } +} + +impl PartialEq for Inner { + fn eq(&self, other: &Inner) -> bool { + self.as_str() == other.as_str() + } +} + +impl PartialOrd for Inner { + fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> { + Some(self.cmp(other)) + } +} + +impl Ord for Inner { + fn cmp(&self, other: &Inner) -> std::cmp::Ordering { + self.as_str().cmp(other.as_str()) + } +} + +impl Eq for Inner {} + +impl std::hash::Hash for Inner { + #[inline] + fn hash<H: std::hash::Hasher>(&self, state: &mut H) { + self.as_str().hash(state); + } +} diff --git a/vendor/clap_builder/src/builder/styled_str.rs b/vendor/clap_builder/src/builder/styled_str.rs new file mode 100644 index 0000000..e06ddbc --- /dev/null +++ b/vendor/clap_builder/src/builder/styled_str.rs @@ -0,0 +1,210 @@ +#![cfg_attr(not(feature = "usage"), allow(dead_code))] + +/// Terminal-styling container +/// +/// Styling may be encoded as [ANSI Escape Code](https://en.wikipedia.org/wiki/ANSI_escape_code) +/// +/// # Examples +/// +/// ```rust +/// # use clap_builder as clap; +/// // `cstr!` converts tags to ANSI codes +/// let after_help: &'static str = color_print::cstr!( +/// r#"<bold><underline>Examples</underline></bold> +/// +/// <dim>$</dim> <bold>mybin --input file.toml</bold> +/// "#); +/// +/// let cmd = clap::Command::new("mybin") +/// .after_help(after_help) // The `&str` gets converted into a `StyledStr` +/// // ... +/// # ; +/// ``` +#[derive(Clone, Default, Debug, PartialEq, Eq, PartialOrd, Ord)] +pub struct StyledStr(String); + +impl StyledStr { + /// Create an empty buffer + pub const fn new() -> Self { + Self(String::new()) + } + + /// Display using [ANSI Escape Code](https://en.wikipedia.org/wiki/ANSI_escape_code) styling + #[cfg(feature = "color")] + pub fn ansi(&self) -> impl std::fmt::Display + '_ { + self.0.as_str() + } + + /// May allow the compiler to consolidate the `Drop`s for `msg`, reducing code size compared to + /// `styled.push_str(&msg)` + pub(crate) fn push_string(&mut self, msg: String) { + self.0.push_str(&msg); + } + + pub(crate) fn push_str(&mut self, msg: &str) { + self.0.push_str(msg); + } + + pub(crate) fn trim_start_lines(&mut self) { + if let Some(pos) = self.0.find('\n') { + let (leading, help) = self.0.split_at(pos + 1); + if leading.trim().is_empty() { + self.0 = help.to_owned() + } + } + } + + pub(crate) fn trim_end(&mut self) { + self.0 = self.0.trim_end().to_owned() + } + + #[cfg(feature = "help")] + pub(crate) fn replace_newline_var(&mut self) { + self.0 = self.0.replace("{n}", "\n"); + } + + #[cfg(feature = "help")] + pub(crate) fn indent(&mut self, initial: &str, trailing: &str) { + self.0.insert_str(0, initial); + + let mut line_sep = "\n".to_owned(); + line_sep.push_str(trailing); + self.0 = self.0.replace('\n', &line_sep); + } + + #[cfg(all(not(feature = "wrap_help"), feature = "help"))] + pub(crate) fn wrap(&mut self, _hard_width: usize) {} + + #[cfg(feature = "wrap_help")] + pub(crate) fn wrap(&mut self, hard_width: usize) { + let mut new = String::with_capacity(self.0.len()); + + let mut last = 0; + let mut wrapper = crate::output::textwrap::wrap_algorithms::LineWrapper::new(hard_width); + for content in self.iter_text() { + // Preserve styling + let current = content.as_ptr() as usize - self.0.as_str().as_ptr() as usize; + if last != current { + new.push_str(&self.0.as_str()[last..current]); + } + last = current + content.len(); + + for (i, line) in content.split_inclusive('\n').enumerate() { + if 0 < i { + // reset char count on newline, skipping the start as we might have carried + // over from a prior block of styled text + wrapper.reset(); + } + let line = crate::output::textwrap::word_separators::find_words_ascii_space(line) + .collect::<Vec<_>>(); + new.extend(wrapper.wrap(line)); + } + } + if last != self.0.len() { + new.push_str(&self.0.as_str()[last..]); + } + new = new.trim_end().to_owned(); + + self.0 = new; + } + + #[inline(never)] + #[cfg(feature = "help")] + pub(crate) fn display_width(&self) -> usize { + let mut width = 0; + for c in self.iter_text() { + width += crate::output::display_width(c); + } + width + } + + #[cfg(feature = "help")] + pub(crate) fn is_empty(&self) -> bool { + self.0.is_empty() + } + + #[cfg(feature = "help")] + pub(crate) fn as_styled_str(&self) -> &str { + &self.0 + } + + #[cfg(feature = "color")] + pub(crate) fn iter_text(&self) -> impl Iterator<Item = &str> { + anstream::adapter::strip_str(&self.0) + } + + #[cfg(not(feature = "color"))] + pub(crate) fn iter_text(&self) -> impl Iterator<Item = &str> { + [self.0.as_str()].into_iter() + } + + pub(crate) fn push_styled(&mut self, other: &Self) { + self.0.push_str(&other.0); + } + + pub(crate) fn write_to(&self, buffer: &mut dyn std::io::Write) -> std::io::Result<()> { + ok!(buffer.write_all(self.0.as_bytes())); + + Ok(()) + } +} + +impl Default for &'_ StyledStr { + fn default() -> Self { + static DEFAULT: StyledStr = StyledStr::new(); + &DEFAULT + } +} + +impl From<std::string::String> for StyledStr { + fn from(name: std::string::String) -> Self { + StyledStr(name) + } +} + +impl From<&'_ std::string::String> for StyledStr { + fn from(name: &'_ std::string::String) -> Self { + let mut styled = StyledStr::new(); + styled.push_str(name); + styled + } +} + +impl From<&'static str> for StyledStr { + fn from(name: &'static str) -> Self { + let mut styled = StyledStr::new(); + styled.push_str(name); + styled + } +} + +impl From<&'_ &'static str> for StyledStr { + fn from(name: &'_ &'static str) -> Self { + StyledStr::from(*name) + } +} + +impl std::fmt::Write for StyledStr { + #[inline] + fn write_str(&mut self, s: &str) -> Result<(), std::fmt::Error> { + self.0.push_str(s); + Ok(()) + } + + #[inline] + fn write_char(&mut self, c: char) -> Result<(), std::fmt::Error> { + self.0.push(c); + Ok(()) + } +} + +/// Color-unaware printing. Never uses coloring. +impl std::fmt::Display for StyledStr { + fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result { + for part in self.iter_text() { + part.fmt(f)?; + } + + Ok(()) + } +} diff --git a/vendor/clap_builder/src/builder/styling.rs b/vendor/clap_builder/src/builder/styling.rs new file mode 100644 index 0000000..3a03448 --- /dev/null +++ b/vendor/clap_builder/src/builder/styling.rs @@ -0,0 +1,179 @@ +//! Terminal [`Styles`] for help and error output + +pub use anstyle::*; + +/// Terminal styling definitions +/// +/// See also [`Command::styles`][crate::Command::styles]. +/// +/// # Example +/// +/// clap v3 styling +/// ```rust +/// # use clap_builder as clap; +/// # use clap::builder::styling::*; +/// let styles = Styles::styled() +/// .header(AnsiColor::Yellow.on_default()) +/// .usage(AnsiColor::Green.on_default()) +/// .literal(AnsiColor::Green.on_default()) +/// .placeholder(AnsiColor::Green.on_default()); +/// ``` +#[derive(Clone, Debug)] +#[allow(missing_copy_implementations)] // Large enough type that I want an explicit `clone()` for now +pub struct Styles { + header: anstyle::Style, + error: anstyle::Style, + usage: anstyle::Style, + literal: anstyle::Style, + placeholder: anstyle::Style, + valid: anstyle::Style, + invalid: anstyle::Style, +} + +impl Styles { + /// No terminal styling + pub const fn plain() -> Self { + Self { + header: anstyle::Style::new(), + error: anstyle::Style::new(), + usage: anstyle::Style::new(), + literal: anstyle::Style::new(), + placeholder: anstyle::Style::new(), + valid: anstyle::Style::new(), + invalid: anstyle::Style::new(), + } + } + + /// Default terminal styling + pub const fn styled() -> Self { + #[cfg(feature = "color")] + { + Self { + header: anstyle::Style::new().bold().underline(), + error: anstyle::Style::new() + .fg_color(Some(anstyle::Color::Ansi(anstyle::AnsiColor::Red))) + .bold(), + usage: anstyle::Style::new().bold().underline(), + literal: anstyle::Style::new().bold(), + placeholder: anstyle::Style::new(), + valid: anstyle::Style::new() + .fg_color(Some(anstyle::Color::Ansi(anstyle::AnsiColor::Green))), + invalid: anstyle::Style::new() + .fg_color(Some(anstyle::Color::Ansi(anstyle::AnsiColor::Yellow))), + } + } + #[cfg(not(feature = "color"))] + { + Self::plain() + } + } + + /// General Heading style, e.g. [`help_heading`][crate::Arg::help_heading] + #[inline] + pub const fn header(mut self, style: anstyle::Style) -> Self { + self.header = style; + self + } + + /// Error heading + #[inline] + pub const fn error(mut self, style: anstyle::Style) -> Self { + self.error = style; + self + } + + /// Usage heading + #[inline] + pub const fn usage(mut self, style: anstyle::Style) -> Self { + self.usage = style; + self + } + + /// Literal command-line syntax, e.g. `--help` + #[inline] + pub const fn literal(mut self, style: anstyle::Style) -> Self { + self.literal = style; + self + } + + /// Descriptions within command-line syntax, e.g. [`value_name`][crate::Arg::value_name] + #[inline] + pub const fn placeholder(mut self, style: anstyle::Style) -> Self { + self.placeholder = style; + self + } + + /// Highlight suggested usage + #[inline] + pub const fn valid(mut self, style: anstyle::Style) -> Self { + self.valid = style; + self + } + + /// Highlight invalid usage + #[inline] + pub const fn invalid(mut self, style: anstyle::Style) -> Self { + self.invalid = style; + self + } +} + +/// Reflection +impl Styles { + /// General Heading style, e.g. [`help_heading`][crate::Arg::help_heading] + #[inline(always)] + pub const fn get_header(&self) -> &anstyle::Style { + &self.header + } + + /// Error heading + #[inline(always)] + pub const fn get_error(&self) -> &anstyle::Style { + &self.error + } + + /// Usage heading + #[inline(always)] + pub const fn get_usage(&self) -> &anstyle::Style { + &self.usage + } + + /// Literal command-line syntax, e.g. `--help` + #[inline(always)] + pub const fn get_literal(&self) -> &anstyle::Style { + &self.literal + } + + /// Descriptions within command-line syntax, e.g. [`value_name`][crate::Arg::value_name] + #[inline(always)] + pub const fn get_placeholder(&self) -> &anstyle::Style { + &self.placeholder + } + + /// Highlight suggested usage + #[inline(always)] + pub const fn get_valid(&self) -> &anstyle::Style { + &self.valid + } + + /// Highlight invalid usage + #[inline(always)] + pub const fn get_invalid(&self) -> &anstyle::Style { + &self.invalid + } +} + +impl super::AppTag for Styles {} + +impl Default for Styles { + fn default() -> Self { + Self::styled() + } +} + +impl Default for &'_ Styles { + fn default() -> Self { + const STYLES: Styles = Styles::styled(); + &STYLES + } +} diff --git a/vendor/clap_builder/src/builder/tests.rs b/vendor/clap_builder/src/builder/tests.rs new file mode 100644 index 0000000..15cb8c4 --- /dev/null +++ b/vendor/clap_builder/src/builder/tests.rs @@ -0,0 +1,56 @@ +use crate::Arg; +use crate::Command; + +#[test] +fn propagate_version() { + let mut cmd = Command::new("test") + .propagate_version(true) + .version("1.1") + .subcommand(Command::new("sub1")); + cmd._propagate(); + assert_eq!( + cmd.get_subcommands().next().unwrap().get_version(), + Some("1.1") + ); +} + +#[test] +fn global_setting() { + let mut cmd = Command::new("test") + .disable_version_flag(true) + .subcommand(Command::new("subcmd")); + cmd._propagate(); + assert!(cmd + .get_subcommands() + .find(|s| s.get_name() == "subcmd") + .unwrap() + .is_disable_version_flag_set()); +} + +// This test will *fail to compile* if Command is not Send + Sync +#[test] +fn app_send_sync() { + fn foo<T: Send + Sync>(_: T) {} + foo(Command::new("test")) +} + +#[test] +fn issue_2090() { + let mut cmd = Command::new("cmd") + .disable_version_flag(true) + .subcommand(Command::new("sub")); + cmd._build_self(false); + + assert!(cmd + .get_subcommands() + .next() + .unwrap() + .is_disable_version_flag_set()); +} + +// This test will *fail to compile* if Arg is not Send + Sync +#[test] +fn arg_send_sync() { + fn foo<T: Send + Sync>(_: T) {} + foo(Arg::new("test")) +} diff --git a/vendor/clap_builder/src/builder/value_hint.rs b/vendor/clap_builder/src/builder/value_hint.rs new file mode 100644 index 0000000..38fa862 --- /dev/null +++ b/vendor/clap_builder/src/builder/value_hint.rs @@ -0,0 +1,90 @@ +use std::str::FromStr; + +/// Provide shell with hint on how to complete an argument. +/// +/// See [Arg::value_hint][crate::Arg::value_hint] to set this on an argument. +/// +/// See the `clap_complete` crate for completion script generation. +/// +/// Overview of which hints are supported by which shell: +/// +/// | Hint | zsh | fish[^1]| +/// | ---------------------- | --- | ------- | +/// | `AnyPath` | Yes | Yes | +/// | `FilePath` | Yes | Yes | +/// | `DirPath` | Yes | Yes | +/// | `ExecutablePath` | Yes | Partial | +/// | `CommandName` | Yes | Yes | +/// | `CommandString` | Yes | Partial | +/// | `CommandWithArguments` | Yes | | +/// | `Username` | Yes | Yes | +/// | `Hostname` | Yes | Yes | +/// | `Url` | Yes | | +/// | `EmailAddress` | Yes | | +/// +/// [^1]: fish completions currently only support named arguments (e.g. -o or --opt), not +/// positional arguments. +#[derive(Debug, Default, PartialEq, Eq, Hash, Copy, Clone)] +#[non_exhaustive] +pub enum ValueHint { + /// Default value if hint is not specified. Follows shell default behavior, which is usually + /// auto-completing filenames. + #[default] + Unknown, + /// None of the hints below apply. Disables shell completion for this argument. + Other, + /// Any existing path. + AnyPath, + /// Path to a file. + FilePath, + /// Path to a directory. + DirPath, + /// Path to an executable file. + ExecutablePath, + /// Name of a command, without arguments. May be relative to PATH, or full path to executable. + CommandName, + /// A single string containing a command and its arguments. + CommandString, + /// Capture the remaining arguments as a command name and arguments for that command. This is + /// common when writing shell wrappers that execute anther command, for example `sudo` or `env`. + /// + /// This hint is special, the argument must be a positional argument and have + /// [`.num_args(1..)`] and Command must use [`Command::trailing_var_arg(true)`]. The result is that the + /// command line `my_app ls -la /` will be parsed as `["ls", "-la", "/"]` and clap won't try to + /// parse the `-la` argument itself. + /// + /// [`Command::trailing_var_arg(true)`]: crate::Command::trailing_var_arg + /// [`.num_args(1..)`]: crate::Arg::num_args() + CommandWithArguments, + /// Name of a local operating system user. + Username, + /// Host name of a computer. + /// Shells usually parse `/etc/hosts` and `.ssh/known_hosts` to complete hostnames. + Hostname, + /// Complete web address. + Url, + /// Email address. + EmailAddress, +} + +impl FromStr for ValueHint { + type Err = String; + fn from_str(s: &str) -> Result<Self, <Self as FromStr>::Err> { + Ok(match &*s.to_ascii_lowercase() { + "unknown" => ValueHint::Unknown, + "other" => ValueHint::Other, + "anypath" => ValueHint::AnyPath, + "filepath" => ValueHint::FilePath, + "dirpath" => ValueHint::DirPath, + "executablepath" => ValueHint::ExecutablePath, + "commandname" => ValueHint::CommandName, + "commandstring" => ValueHint::CommandString, + "commandwitharguments" => ValueHint::CommandWithArguments, + "username" => ValueHint::Username, + "hostname" => ValueHint::Hostname, + "url" => ValueHint::Url, + "emailaddress" => ValueHint::EmailAddress, + _ => return Err(format!("unknown ValueHint: `{s}`")), + }) + } +} diff --git a/vendor/clap_builder/src/builder/value_parser.rs b/vendor/clap_builder/src/builder/value_parser.rs new file mode 100644 index 0000000..1f0ef92 --- /dev/null +++ b/vendor/clap_builder/src/builder/value_parser.rs @@ -0,0 +1,2712 @@ +use std::convert::TryInto; +use std::ops::RangeBounds; + +use crate::builder::Str; +use crate::builder::StyledStr; +use crate::parser::ValueSource; +use crate::util::AnyValue; +use crate::util::AnyValueId; + +/// Parse/validate argument values +/// +/// Specified with [`Arg::value_parser`][crate::Arg::value_parser]. +/// +/// `ValueParser` defines how to convert a raw argument value into a validated and typed value for +/// use within an application. +/// +/// See +/// - [`value_parser!`][crate::value_parser] for automatically selecting an implementation for a given type +/// - [`ValueParser::new`] for additional [`TypedValueParser`] that can be used +/// +/// # Example +/// +/// ```rust +/// # use clap_builder as clap; +/// let mut cmd = clap::Command::new("raw") +/// .arg( +/// clap::Arg::new("color") +/// .long("color") +/// .value_parser(["always", "auto", "never"]) +/// .default_value("auto") +/// ) +/// .arg( +/// clap::Arg::new("hostname") +/// .long("hostname") +/// .value_parser(clap::builder::NonEmptyStringValueParser::new()) +/// .action(clap::ArgAction::Set) +/// .required(true) +/// ) +/// .arg( +/// clap::Arg::new("port") +/// .long("port") +/// .value_parser(clap::value_parser!(u16).range(3000..)) +/// .action(clap::ArgAction::Set) +/// .required(true) +/// ); +/// +/// let m = cmd.try_get_matches_from_mut( +/// ["cmd", "--hostname", "rust-lang.org", "--port", "3001"] +/// ).unwrap(); +/// +/// let color: &String = m.get_one("color") +/// .expect("default"); +/// assert_eq!(color, "auto"); +/// +/// let hostname: &String = m.get_one("hostname") +/// .expect("required"); +/// assert_eq!(hostname, "rust-lang.org"); +/// +/// let port: u16 = *m.get_one("port") +/// .expect("required"); +/// assert_eq!(port, 3001); +/// ``` +pub struct ValueParser(ValueParserInner); + +enum ValueParserInner { + // Common enough to optimize and for possible values + Bool, + // Common enough to optimize + String, + // Common enough to optimize + OsString, + // Common enough to optimize + PathBuf, + Other(Box<dyn AnyValueParser>), +} + +impl ValueParser { + /// Custom parser for argument values + /// + /// Pre-existing [`TypedValueParser`] implementations include: + /// - `Fn(&str) -> Result<T, E>` + /// - [`EnumValueParser`] and [`PossibleValuesParser`] for static enumerated values + /// - [`BoolishValueParser`] and [`FalseyValueParser`] for alternative `bool` implementations + /// - [`RangedI64ValueParser`] and [`RangedU64ValueParser`] + /// - [`NonEmptyStringValueParser`] + /// + /// # Example + /// + /// ```rust + /// # use clap_builder as clap; + /// type EnvVar = (String, Option<String>); + /// fn parse_env_var(env: &str) -> Result<EnvVar, std::io::Error> { + /// if let Some((var, value)) = env.split_once('=') { + /// Ok((var.to_owned(), Some(value.to_owned()))) + /// } else { + /// Ok((env.to_owned(), None)) + /// } + /// } + /// + /// let mut cmd = clap::Command::new("raw") + /// .arg( + /// clap::Arg::new("env") + /// .value_parser(clap::builder::ValueParser::new(parse_env_var)) + /// .required(true) + /// ); + /// + /// let m = cmd.try_get_matches_from_mut(["cmd", "key=value"]).unwrap(); + /// let port: &EnvVar = m.get_one("env") + /// .expect("required"); + /// assert_eq!(*port, ("key".into(), Some("value".into()))); + /// ``` + pub fn new<P>(other: P) -> Self + where + P: TypedValueParser, + { + Self(ValueParserInner::Other(Box::new(other))) + } + + /// [`bool`] parser for argument values + /// + /// See also: + /// - [`BoolishValueParser`] for different human readable bool representations + /// - [`FalseyValueParser`] for assuming non-false is true + /// + /// # Example + /// + /// ```rust + /// # use clap_builder as clap; + /// let mut cmd = clap::Command::new("raw") + /// .arg( + /// clap::Arg::new("download") + /// .value_parser(clap::value_parser!(bool)) + /// .required(true) + /// ); + /// + /// let m = cmd.try_get_matches_from_mut(["cmd", "true"]).unwrap(); + /// let port: bool = *m.get_one("download") + /// .expect("required"); + /// assert_eq!(port, true); + /// + /// assert!(cmd.try_get_matches_from_mut(["cmd", "forever"]).is_err()); + /// ``` + pub const fn bool() -> Self { + Self(ValueParserInner::Bool) + } + + /// [`String`] parser for argument values + /// + /// See also: + /// - [`NonEmptyStringValueParser`] + /// + /// # Example + /// + /// ```rust + /// # use clap_builder as clap; + /// let mut cmd = clap::Command::new("raw") + /// .arg( + /// clap::Arg::new("port") + /// .value_parser(clap::value_parser!(String)) + /// .required(true) + /// ); + /// + /// let m = cmd.try_get_matches_from_mut(["cmd", "80"]).unwrap(); + /// let port: &String = m.get_one("port") + /// .expect("required"); + /// assert_eq!(port, "80"); + /// ``` + pub const fn string() -> Self { + Self(ValueParserInner::String) + } + + /// [`OsString`][std::ffi::OsString] parser for argument values + /// + /// # Example + /// + /// ```rust + /// # #[cfg(unix)] { + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, builder::ValueParser}; + /// use std::ffi::OsString; + /// use std::os::unix::ffi::{OsStrExt,OsStringExt}; + /// let r = Command::new("myprog") + /// .arg( + /// Arg::new("arg") + /// .required(true) + /// .value_parser(ValueParser::os_string()) + /// ) + /// .try_get_matches_from(vec![ + /// OsString::from("myprog"), + /// OsString::from_vec(vec![0xe9]) + /// ]); + /// + /// assert!(r.is_ok()); + /// let m = r.unwrap(); + /// let arg: &OsString = m.get_one("arg") + /// .expect("required"); + /// assert_eq!(arg.as_bytes(), &[0xe9]); + /// # } + /// ``` + pub const fn os_string() -> Self { + Self(ValueParserInner::OsString) + } + + /// [`PathBuf`][std::path::PathBuf] parser for argument values + /// + /// # Example + /// + /// ```rust + /// # use clap_builder as clap; + /// # use std::path::PathBuf; + /// # use std::path::Path; + /// let mut cmd = clap::Command::new("raw") + /// .arg( + /// clap::Arg::new("output") + /// .value_parser(clap::value_parser!(PathBuf)) + /// .required(true) + /// ); + /// + /// let m = cmd.try_get_matches_from_mut(["cmd", "hello.txt"]).unwrap(); + /// let port: &PathBuf = m.get_one("output") + /// .expect("required"); + /// assert_eq!(port, Path::new("hello.txt")); + /// + /// assert!(cmd.try_get_matches_from_mut(["cmd", ""]).is_err()); + /// ``` + pub const fn path_buf() -> Self { + Self(ValueParserInner::PathBuf) + } +} + +impl ValueParser { + /// Parse into a `AnyValue` + /// + /// When `arg` is `None`, an external subcommand value is being parsed. + pub(crate) fn parse_ref( + &self, + cmd: &crate::Command, + arg: Option<&crate::Arg>, + value: &std::ffi::OsStr, + source: ValueSource, + ) -> Result<AnyValue, crate::Error> { + self.any_value_parser().parse_ref_(cmd, arg, value, source) + } + + /// Describes the content of `AnyValue` + pub fn type_id(&self) -> AnyValueId { + self.any_value_parser().type_id() + } + + /// Reflect on enumerated value properties + /// + /// Error checking should not be done with this; it is mostly targeted at user-facing + /// applications like errors and completion. + pub fn possible_values( + &self, + ) -> Option<Box<dyn Iterator<Item = crate::builder::PossibleValue> + '_>> { + self.any_value_parser().possible_values() + } + + fn any_value_parser(&self) -> &dyn AnyValueParser { + match &self.0 { + ValueParserInner::Bool => &BoolValueParser {}, + ValueParserInner::String => &StringValueParser {}, + ValueParserInner::OsString => &OsStringValueParser {}, + ValueParserInner::PathBuf => &PathBufValueParser {}, + ValueParserInner::Other(o) => o.as_ref(), + } + } +} + +/// Convert a [`TypedValueParser`] to [`ValueParser`] +/// +/// # Example +/// +/// ```rust +/// # use clap_builder as clap; +/// let mut cmd = clap::Command::new("raw") +/// .arg( +/// clap::Arg::new("hostname") +/// .long("hostname") +/// .value_parser(clap::builder::NonEmptyStringValueParser::new()) +/// .action(clap::ArgAction::Set) +/// .required(true) +/// ); +/// +/// let m = cmd.try_get_matches_from_mut( +/// ["cmd", "--hostname", "rust-lang.org"] +/// ).unwrap(); +/// +/// let hostname: &String = m.get_one("hostname") +/// .expect("required"); +/// assert_eq!(hostname, "rust-lang.org"); +/// ``` +impl<P> From<P> for ValueParser +where + P: TypedValueParser + Send + Sync + 'static, +{ + fn from(p: P) -> Self { + Self::new(p) + } +} + +impl From<_AnonymousValueParser> for ValueParser { + fn from(p: _AnonymousValueParser) -> Self { + p.0 + } +} + +/// Create an `i64` [`ValueParser`] from a `N..M` range +/// +/// See [`RangedI64ValueParser`] for more control over the output type. +/// +/// See also [`RangedU64ValueParser`] +/// +/// # Examples +/// +/// ```rust +/// # use clap_builder as clap; +/// let mut cmd = clap::Command::new("raw") +/// .arg( +/// clap::Arg::new("port") +/// .long("port") +/// .value_parser(3000..4000) +/// .action(clap::ArgAction::Set) +/// .required(true) +/// ); +/// +/// let m = cmd.try_get_matches_from_mut(["cmd", "--port", "3001"]).unwrap(); +/// let port: i64 = *m.get_one("port") +/// .expect("required"); +/// assert_eq!(port, 3001); +/// ``` +impl From<std::ops::Range<i64>> for ValueParser { + fn from(value: std::ops::Range<i64>) -> Self { + let inner = RangedI64ValueParser::<i64>::new().range(value.start..value.end); + Self::from(inner) + } +} + +/// Create an `i64` [`ValueParser`] from a `N..=M` range +/// +/// See [`RangedI64ValueParser`] for more control over the output type. +/// +/// See also [`RangedU64ValueParser`] +/// +/// # Examples +/// +/// ```rust +/// # use clap_builder as clap; +/// let mut cmd = clap::Command::new("raw") +/// .arg( +/// clap::Arg::new("port") +/// .long("port") +/// .value_parser(3000..=4000) +/// .action(clap::ArgAction::Set) +/// .required(true) +/// ); +/// +/// let m = cmd.try_get_matches_from_mut(["cmd", "--port", "3001"]).unwrap(); +/// let port: i64 = *m.get_one("port") +/// .expect("required"); +/// assert_eq!(port, 3001); +/// ``` +impl From<std::ops::RangeInclusive<i64>> for ValueParser { + fn from(value: std::ops::RangeInclusive<i64>) -> Self { + let inner = RangedI64ValueParser::<i64>::new().range(value.start()..=value.end()); + Self::from(inner) + } +} + +/// Create an `i64` [`ValueParser`] from a `N..` range +/// +/// See [`RangedI64ValueParser`] for more control over the output type. +/// +/// See also [`RangedU64ValueParser`] +/// +/// # Examples +/// +/// ```rust +/// # use clap_builder as clap; +/// let mut cmd = clap::Command::new("raw") +/// .arg( +/// clap::Arg::new("port") +/// .long("port") +/// .value_parser(3000..) +/// .action(clap::ArgAction::Set) +/// .required(true) +/// ); +/// +/// let m = cmd.try_get_matches_from_mut(["cmd", "--port", "3001"]).unwrap(); +/// let port: i64 = *m.get_one("port") +/// .expect("required"); +/// assert_eq!(port, 3001); +/// ``` +impl From<std::ops::RangeFrom<i64>> for ValueParser { + fn from(value: std::ops::RangeFrom<i64>) -> Self { + let inner = RangedI64ValueParser::<i64>::new().range(value.start..); + Self::from(inner) + } +} + +/// Create an `i64` [`ValueParser`] from a `..M` range +/// +/// See [`RangedI64ValueParser`] for more control over the output type. +/// +/// See also [`RangedU64ValueParser`] +/// +/// # Examples +/// +/// ```rust +/// # use clap_builder as clap; +/// let mut cmd = clap::Command::new("raw") +/// .arg( +/// clap::Arg::new("port") +/// .long("port") +/// .value_parser(..3000) +/// .action(clap::ArgAction::Set) +/// .required(true) +/// ); +/// +/// let m = cmd.try_get_matches_from_mut(["cmd", "--port", "80"]).unwrap(); +/// let port: i64 = *m.get_one("port") +/// .expect("required"); +/// assert_eq!(port, 80); +/// ``` +impl From<std::ops::RangeTo<i64>> for ValueParser { + fn from(value: std::ops::RangeTo<i64>) -> Self { + let inner = RangedI64ValueParser::<i64>::new().range(..value.end); + Self::from(inner) + } +} + +/// Create an `i64` [`ValueParser`] from a `..=M` range +/// +/// See [`RangedI64ValueParser`] for more control over the output type. +/// +/// See also [`RangedU64ValueParser`] +/// +/// # Examples +/// +/// ```rust +/// # use clap_builder as clap; +/// let mut cmd = clap::Command::new("raw") +/// .arg( +/// clap::Arg::new("port") +/// .long("port") +/// .value_parser(..=3000) +/// .action(clap::ArgAction::Set) +/// .required(true) +/// ); +/// +/// let m = cmd.try_get_matches_from_mut(["cmd", "--port", "80"]).unwrap(); +/// let port: i64 = *m.get_one("port") +/// .expect("required"); +/// assert_eq!(port, 80); +/// ``` +impl From<std::ops::RangeToInclusive<i64>> for ValueParser { + fn from(value: std::ops::RangeToInclusive<i64>) -> Self { + let inner = RangedI64ValueParser::<i64>::new().range(..=value.end); + Self::from(inner) + } +} + +/// Create an `i64` [`ValueParser`] from a `..` range +/// +/// See [`RangedI64ValueParser`] for more control over the output type. +/// +/// See also [`RangedU64ValueParser`] +/// +/// # Examples +/// +/// ```rust +/// # use clap_builder as clap; +/// let mut cmd = clap::Command::new("raw") +/// .arg( +/// clap::Arg::new("port") +/// .long("port") +/// .value_parser(..) +/// .action(clap::ArgAction::Set) +/// .required(true) +/// ); +/// +/// let m = cmd.try_get_matches_from_mut(["cmd", "--port", "3001"]).unwrap(); +/// let port: i64 = *m.get_one("port") +/// .expect("required"); +/// assert_eq!(port, 3001); +/// ``` +impl From<std::ops::RangeFull> for ValueParser { + fn from(value: std::ops::RangeFull) -> Self { + let inner = RangedI64ValueParser::<i64>::new().range(value); + Self::from(inner) + } +} + +/// Create a [`ValueParser`] with [`PossibleValuesParser`] +/// +/// See [`PossibleValuesParser`] for more flexibility in creating the +/// [`PossibleValue`][crate::builder::PossibleValue]s. +/// +/// # Examples +/// +/// ```rust +/// # use clap_builder as clap; +/// let mut cmd = clap::Command::new("raw") +/// .arg( +/// clap::Arg::new("color") +/// .long("color") +/// .value_parser(["always", "auto", "never"]) +/// .default_value("auto") +/// ); +/// +/// let m = cmd.try_get_matches_from_mut( +/// ["cmd", "--color", "never"] +/// ).unwrap(); +/// +/// let color: &String = m.get_one("color") +/// .expect("default"); +/// assert_eq!(color, "never"); +/// ``` +impl<P, const C: usize> From<[P; C]> for ValueParser +where + P: Into<super::PossibleValue>, +{ + fn from(values: [P; C]) -> Self { + let inner = PossibleValuesParser::from(values); + Self::from(inner) + } +} + +/// Create a [`ValueParser`] with [`PossibleValuesParser`] +/// +/// See [`PossibleValuesParser`] for more flexibility in creating the +/// [`PossibleValue`][crate::builder::PossibleValue]s. +/// +/// # Examples +/// +/// ```rust +/// # use clap_builder as clap; +/// let possible = vec!["always", "auto", "never"]; +/// let mut cmd = clap::Command::new("raw") +/// .arg( +/// clap::Arg::new("color") +/// .long("color") +/// .value_parser(possible) +/// .default_value("auto") +/// ); +/// +/// let m = cmd.try_get_matches_from_mut( +/// ["cmd", "--color", "never"] +/// ).unwrap(); +/// +/// let color: &String = m.get_one("color") +/// .expect("default"); +/// assert_eq!(color, "never"); +/// ``` +impl<P> From<Vec<P>> for ValueParser +where + P: Into<super::PossibleValue>, +{ + fn from(values: Vec<P>) -> Self { + let inner = PossibleValuesParser::from(values); + Self::from(inner) + } +} + +impl std::fmt::Debug for ValueParser { + fn fmt(&self, f: &mut std::fmt::Formatter) -> Result<(), std::fmt::Error> { + match &self.0 { + ValueParserInner::Bool => f.debug_struct("ValueParser::bool").finish(), + ValueParserInner::String => f.debug_struct("ValueParser::string").finish(), + ValueParserInner::OsString => f.debug_struct("ValueParser::os_string").finish(), + ValueParserInner::PathBuf => f.debug_struct("ValueParser::path_buf").finish(), + ValueParserInner::Other(o) => write!(f, "ValueParser::other({:?})", o.type_id()), + } + } +} + +impl Clone for ValueParser { + fn clone(&self) -> Self { + Self(match &self.0 { + ValueParserInner::Bool => ValueParserInner::Bool, + ValueParserInner::String => ValueParserInner::String, + ValueParserInner::OsString => ValueParserInner::OsString, + ValueParserInner::PathBuf => ValueParserInner::PathBuf, + ValueParserInner::Other(o) => ValueParserInner::Other(o.clone_any()), + }) + } +} + +/// A type-erased wrapper for [`TypedValueParser`]. +trait AnyValueParser: Send + Sync + 'static { + fn parse_ref( + &self, + cmd: &crate::Command, + arg: Option<&crate::Arg>, + value: &std::ffi::OsStr, + ) -> Result<AnyValue, crate::Error>; + + fn parse_ref_( + &self, + cmd: &crate::Command, + arg: Option<&crate::Arg>, + value: &std::ffi::OsStr, + _source: ValueSource, + ) -> Result<AnyValue, crate::Error> { + self.parse_ref(cmd, arg, value) + } + + fn parse( + &self, + cmd: &crate::Command, + arg: Option<&crate::Arg>, + value: std::ffi::OsString, + ) -> Result<AnyValue, crate::Error>; + + fn parse_( + &self, + cmd: &crate::Command, + arg: Option<&crate::Arg>, + value: std::ffi::OsString, + _source: ValueSource, + ) -> Result<AnyValue, crate::Error> { + self.parse(cmd, arg, value) + } + + /// Describes the content of `AnyValue` + fn type_id(&self) -> AnyValueId; + + fn possible_values( + &self, + ) -> Option<Box<dyn Iterator<Item = crate::builder::PossibleValue> + '_>>; + + fn clone_any(&self) -> Box<dyn AnyValueParser>; +} + +impl<T, P> AnyValueParser for P +where + T: std::any::Any + Clone + Send + Sync + 'static, + P: TypedValueParser<Value = T>, +{ + fn parse_ref( + &self, + cmd: &crate::Command, + arg: Option<&crate::Arg>, + value: &std::ffi::OsStr, + ) -> Result<AnyValue, crate::Error> { + let value = ok!(TypedValueParser::parse_ref(self, cmd, arg, value)); + Ok(AnyValue::new(value)) + } + + fn parse_ref_( + &self, + cmd: &crate::Command, + arg: Option<&crate::Arg>, + value: &std::ffi::OsStr, + source: ValueSource, + ) -> Result<AnyValue, crate::Error> { + let value = ok!(TypedValueParser::parse_ref_(self, cmd, arg, value, source)); + Ok(AnyValue::new(value)) + } + + fn parse( + &self, + cmd: &crate::Command, + arg: Option<&crate::Arg>, + value: std::ffi::OsString, + ) -> Result<AnyValue, crate::Error> { + let value = ok!(TypedValueParser::parse(self, cmd, arg, value)); + Ok(AnyValue::new(value)) + } + + fn parse_( + &self, + cmd: &crate::Command, + arg: Option<&crate::Arg>, + value: std::ffi::OsString, + source: ValueSource, + ) -> Result<AnyValue, crate::Error> { + let value = ok!(TypedValueParser::parse_(self, cmd, arg, value, source)); + Ok(AnyValue::new(value)) + } + + fn type_id(&self) -> AnyValueId { + AnyValueId::of::<T>() + } + + fn possible_values( + &self, + ) -> Option<Box<dyn Iterator<Item = crate::builder::PossibleValue> + '_>> { + P::possible_values(self) + } + + fn clone_any(&self) -> Box<dyn AnyValueParser> { + Box::new(self.clone()) + } +} + +/// Parse/validate argument values +/// +/// As alternatives to implementing `TypedValueParser`, +/// - Use `Fn(&str) -> Result<T, E>` which implements `TypedValueParser` +/// - [`TypedValueParser::map`] or [`TypedValueParser::try_map`] to adapt an existing `TypedValueParser` +/// +/// See `ValueParserFactory` to register `TypedValueParser::Value` with +/// [`value_parser!`][crate::value_parser]. +/// +/// # Example +/// +/// ```rust +/// # #[cfg(feature = "error-context")] { +/// # use clap_builder as clap; +/// # use clap::error::ErrorKind; +/// # use clap::error::ContextKind; +/// # use clap::error::ContextValue; +/// #[derive(Clone)] +/// struct Custom(u32); +/// +/// #[derive(Clone)] +/// struct CustomValueParser; +/// +/// impl clap::builder::TypedValueParser for CustomValueParser { +/// type Value = Custom; +/// +/// fn parse_ref( +/// &self, +/// cmd: &clap::Command, +/// arg: Option<&clap::Arg>, +/// value: &std::ffi::OsStr, +/// ) -> Result<Self::Value, clap::Error> { +/// let inner = clap::value_parser!(u32); +/// let val = inner.parse_ref(cmd, arg, value)?; +/// +/// const INVALID_VALUE: u32 = 10; +/// if val == INVALID_VALUE { +/// let mut err = clap::Error::new(ErrorKind::ValueValidation) +/// .with_cmd(cmd); +/// if let Some(arg) = arg { +/// err.insert(ContextKind::InvalidArg, ContextValue::String(arg.to_string())); +/// } +/// err.insert(ContextKind::InvalidValue, ContextValue::String(INVALID_VALUE.to_string())); +/// return Err(err); +/// } +/// +/// Ok(Custom(val)) +/// } +/// } +/// # } +/// ``` +pub trait TypedValueParser: Clone + Send + Sync + 'static { + /// Argument's value type + type Value: Send + Sync + Clone; + + /// Parse the argument value + /// + /// When `arg` is `None`, an external subcommand value is being parsed. + fn parse_ref( + &self, + cmd: &crate::Command, + arg: Option<&crate::Arg>, + value: &std::ffi::OsStr, + ) -> Result<Self::Value, crate::Error>; + + /// Parse the argument value + /// + /// When `arg` is `None`, an external subcommand value is being parsed. + fn parse_ref_( + &self, + cmd: &crate::Command, + arg: Option<&crate::Arg>, + value: &std::ffi::OsStr, + _source: ValueSource, + ) -> Result<Self::Value, crate::Error> { + self.parse_ref(cmd, arg, value) + } + + /// Parse the argument value + /// + /// When `arg` is `None`, an external subcommand value is being parsed. + fn parse( + &self, + cmd: &crate::Command, + arg: Option<&crate::Arg>, + value: std::ffi::OsString, + ) -> Result<Self::Value, crate::Error> { + self.parse_ref(cmd, arg, &value) + } + + /// Parse the argument value + /// + /// When `arg` is `None`, an external subcommand value is being parsed. + fn parse_( + &self, + cmd: &crate::Command, + arg: Option<&crate::Arg>, + value: std::ffi::OsString, + _source: ValueSource, + ) -> Result<Self::Value, crate::Error> { + self.parse(cmd, arg, value) + } + + /// Reflect on enumerated value properties + /// + /// Error checking should not be done with this; it is mostly targeted at user-facing + /// applications like errors and completion. + fn possible_values( + &self, + ) -> Option<Box<dyn Iterator<Item = crate::builder::PossibleValue> + '_>> { + None + } + + /// Adapt a `TypedValueParser` from one value to another + /// + /// # Example + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::Command; + /// # use clap::Arg; + /// # use clap::builder::TypedValueParser as _; + /// # use clap::builder::BoolishValueParser; + /// let cmd = Command::new("mycmd") + /// .arg( + /// Arg::new("flag") + /// .long("flag") + /// .action(clap::ArgAction::SetTrue) + /// .value_parser( + /// BoolishValueParser::new() + /// .map(|b| -> usize { + /// if b { 10 } else { 5 } + /// }) + /// ) + /// ); + /// + /// let matches = cmd.clone().try_get_matches_from(["mycmd", "--flag"]).unwrap(); + /// assert!(matches.contains_id("flag")); + /// assert_eq!( + /// matches.get_one::<usize>("flag").copied(), + /// Some(10) + /// ); + /// + /// let matches = cmd.try_get_matches_from(["mycmd"]).unwrap(); + /// assert!(matches.contains_id("flag")); + /// assert_eq!( + /// matches.get_one::<usize>("flag").copied(), + /// Some(5) + /// ); + /// ``` + fn map<T, F>(self, func: F) -> MapValueParser<Self, F> + where + T: Send + Sync + Clone, + F: Fn(Self::Value) -> T + Clone, + { + MapValueParser::new(self, func) + } + + /// Adapt a `TypedValueParser` from one value to another + /// + /// # Example + /// + /// ```rust + /// # use clap_builder as clap; + /// # use std::ffi::OsString; + /// # use std::ffi::OsStr; + /// # use std::path::PathBuf; + /// # use std::path::Path; + /// # use clap::Command; + /// # use clap::Arg; + /// # use clap::builder::TypedValueParser as _; + /// # use clap::builder::OsStringValueParser; + /// let cmd = Command::new("mycmd") + /// .arg( + /// Arg::new("flag") + /// .long("flag") + /// .value_parser( + /// OsStringValueParser::new() + /// .try_map(verify_ext) + /// ) + /// ); + /// + /// fn verify_ext(os: OsString) -> Result<PathBuf, &'static str> { + /// let path = PathBuf::from(os); + /// if path.extension() != Some(OsStr::new("rs")) { + /// return Err("only Rust files are supported"); + /// } + /// Ok(path) + /// } + /// + /// let error = cmd.clone().try_get_matches_from(["mycmd", "--flag", "foo.txt"]).unwrap_err(); + /// error.print(); + /// + /// let matches = cmd.try_get_matches_from(["mycmd", "--flag", "foo.rs"]).unwrap(); + /// assert!(matches.contains_id("flag")); + /// assert_eq!( + /// matches.get_one::<PathBuf>("flag").map(|s| s.as_path()), + /// Some(Path::new("foo.rs")) + /// ); + /// ``` + fn try_map<T, E, F>(self, func: F) -> TryMapValueParser<Self, F> + where + F: Fn(Self::Value) -> Result<T, E> + Clone + Send + Sync + 'static, + T: Send + Sync + Clone, + E: Into<Box<dyn std::error::Error + Send + Sync + 'static>>, + { + TryMapValueParser::new(self, func) + } +} + +impl<F, T, E> TypedValueParser for F +where + F: Fn(&str) -> Result<T, E> + Clone + Send + Sync + 'static, + E: Into<Box<dyn std::error::Error + Send + Sync + 'static>>, + T: Send + Sync + Clone, +{ + type Value = T; + + fn parse_ref( + &self, + cmd: &crate::Command, + arg: Option<&crate::Arg>, + value: &std::ffi::OsStr, + ) -> Result<Self::Value, crate::Error> { + let value = ok!(value.to_str().ok_or_else(|| { + crate::Error::invalid_utf8( + cmd, + crate::output::Usage::new(cmd).create_usage_with_title(&[]), + ) + })); + let value = ok!((self)(value).map_err(|e| { + let arg = arg + .map(|a| a.to_string()) + .unwrap_or_else(|| "...".to_owned()); + crate::Error::value_validation(arg, value.to_owned(), e.into()).with_cmd(cmd) + })); + Ok(value) + } +} + +/// Implementation for [`ValueParser::string`] +/// +/// Useful for composing new [`TypedValueParser`]s +#[derive(Copy, Clone, Debug)] +#[non_exhaustive] +pub struct StringValueParser {} + +impl StringValueParser { + /// Implementation for [`ValueParser::string`] + pub fn new() -> Self { + Self {} + } +} + +impl TypedValueParser for StringValueParser { + type Value = String; + + fn parse_ref( + &self, + cmd: &crate::Command, + arg: Option<&crate::Arg>, + value: &std::ffi::OsStr, + ) -> Result<Self::Value, crate::Error> { + TypedValueParser::parse(self, cmd, arg, value.to_owned()) + } + + fn parse( + &self, + cmd: &crate::Command, + _arg: Option<&crate::Arg>, + value: std::ffi::OsString, + ) -> Result<Self::Value, crate::Error> { + let value = ok!(value.into_string().map_err(|_| { + crate::Error::invalid_utf8( + cmd, + crate::output::Usage::new(cmd).create_usage_with_title(&[]), + ) + })); + Ok(value) + } +} + +impl Default for StringValueParser { + fn default() -> Self { + Self::new() + } +} + +/// Implementation for [`ValueParser::os_string`] +/// +/// Useful for composing new [`TypedValueParser`]s +#[derive(Copy, Clone, Debug)] +#[non_exhaustive] +pub struct OsStringValueParser {} + +impl OsStringValueParser { + /// Implementation for [`ValueParser::os_string`] + pub fn new() -> Self { + Self {} + } +} + +impl TypedValueParser for OsStringValueParser { + type Value = std::ffi::OsString; + + fn parse_ref( + &self, + cmd: &crate::Command, + arg: Option<&crate::Arg>, + value: &std::ffi::OsStr, + ) -> Result<Self::Value, crate::Error> { + TypedValueParser::parse(self, cmd, arg, value.to_owned()) + } + + fn parse( + &self, + _cmd: &crate::Command, + _arg: Option<&crate::Arg>, + value: std::ffi::OsString, + ) -> Result<Self::Value, crate::Error> { + Ok(value) + } +} + +impl Default for OsStringValueParser { + fn default() -> Self { + Self::new() + } +} + +/// Implementation for [`ValueParser::path_buf`] +/// +/// Useful for composing new [`TypedValueParser`]s +#[derive(Copy, Clone, Debug)] +#[non_exhaustive] +pub struct PathBufValueParser {} + +impl PathBufValueParser { + /// Implementation for [`ValueParser::path_buf`] + pub fn new() -> Self { + Self {} + } +} + +impl TypedValueParser for PathBufValueParser { + type Value = std::path::PathBuf; + + fn parse_ref( + &self, + cmd: &crate::Command, + arg: Option<&crate::Arg>, + value: &std::ffi::OsStr, + ) -> Result<Self::Value, crate::Error> { + TypedValueParser::parse(self, cmd, arg, value.to_owned()) + } + + fn parse( + &self, + cmd: &crate::Command, + arg: Option<&crate::Arg>, + value: std::ffi::OsString, + ) -> Result<Self::Value, crate::Error> { + if value.is_empty() { + return Err(crate::Error::empty_value( + cmd, + &[], + arg.map(ToString::to_string) + .unwrap_or_else(|| "...".to_owned()), + )); + } + Ok(Self::Value::from(value)) + } +} + +impl Default for PathBufValueParser { + fn default() -> Self { + Self::new() + } +} + +/// Parse an [`ValueEnum`][crate::ValueEnum] value. +/// +/// See also: +/// - [`PossibleValuesParser`] +/// +/// # Example +/// +/// ```rust +/// # use clap_builder as clap; +/// # use std::ffi::OsStr; +/// # use clap::ColorChoice; +/// # use clap::builder::TypedValueParser; +/// # let cmd = clap::Command::new("test"); +/// # let arg = None; +/// +/// // Usage +/// let mut cmd = clap::Command::new("raw") +/// .arg( +/// clap::Arg::new("color") +/// .value_parser(clap::builder::EnumValueParser::<ColorChoice>::new()) +/// .required(true) +/// ); +/// +/// let m = cmd.try_get_matches_from_mut(["cmd", "always"]).unwrap(); +/// let port: ColorChoice = *m.get_one("color") +/// .expect("required"); +/// assert_eq!(port, ColorChoice::Always); +/// +/// // Semantics +/// let value_parser = clap::builder::EnumValueParser::<ColorChoice>::new(); +/// // or +/// let value_parser = clap::value_parser!(ColorChoice); +/// assert!(value_parser.parse_ref(&cmd, arg, OsStr::new("random")).is_err()); +/// assert!(value_parser.parse_ref(&cmd, arg, OsStr::new("")).is_err()); +/// assert_eq!(value_parser.parse_ref(&cmd, arg, OsStr::new("always")).unwrap(), ColorChoice::Always); +/// assert_eq!(value_parser.parse_ref(&cmd, arg, OsStr::new("auto")).unwrap(), ColorChoice::Auto); +/// assert_eq!(value_parser.parse_ref(&cmd, arg, OsStr::new("never")).unwrap(), ColorChoice::Never); +/// ``` +#[derive(Clone, Debug)] +pub struct EnumValueParser<E: crate::ValueEnum + Clone + Send + Sync + 'static>( + std::marker::PhantomData<E>, +); + +impl<E: crate::ValueEnum + Clone + Send + Sync + 'static> EnumValueParser<E> { + /// Parse an [`ValueEnum`][crate::ValueEnum] + pub fn new() -> Self { + let phantom: std::marker::PhantomData<E> = Default::default(); + Self(phantom) + } +} + +impl<E: crate::ValueEnum + Clone + Send + Sync + 'static> TypedValueParser for EnumValueParser<E> { + type Value = E; + + fn parse_ref( + &self, + cmd: &crate::Command, + arg: Option<&crate::Arg>, + value: &std::ffi::OsStr, + ) -> Result<Self::Value, crate::Error> { + let ignore_case = arg.map(|a| a.is_ignore_case_set()).unwrap_or(false); + let possible_vals = || { + E::value_variants() + .iter() + .filter_map(|v| v.to_possible_value()) + .filter(|v| !v.is_hide_set()) + .map(|v| v.get_name().to_owned()) + .collect::<Vec<_>>() + }; + + let value = ok!(value.to_str().ok_or_else(|| { + crate::Error::invalid_value( + cmd, + value.to_string_lossy().into_owned(), + &possible_vals(), + arg.map(ToString::to_string) + .unwrap_or_else(|| "...".to_owned()), + ) + })); + let value = ok!(E::value_variants() + .iter() + .find(|v| { + v.to_possible_value() + .expect("ValueEnum::value_variants contains only values with a corresponding ValueEnum::to_possible_value") + .matches(value, ignore_case) + }) + .ok_or_else(|| { + crate::Error::invalid_value( + cmd, + value.to_owned(), + &possible_vals(), + arg.map(ToString::to_string) + .unwrap_or_else(|| "...".to_owned()), + ) + })) + .clone(); + Ok(value) + } + + fn possible_values( + &self, + ) -> Option<Box<dyn Iterator<Item = crate::builder::PossibleValue> + '_>> { + Some(Box::new( + E::value_variants() + .iter() + .filter_map(|v| v.to_possible_value()), + )) + } +} + +impl<E: crate::ValueEnum + Clone + Send + Sync + 'static> Default for EnumValueParser<E> { + fn default() -> Self { + Self::new() + } +} + +/// Verify the value is from an enumerated set of [`PossibleValue`][crate::builder::PossibleValue]. +/// +/// See also: +/// - [`EnumValueParser`] for directly supporting [`ValueEnum`][crate::ValueEnum] types +/// - [`TypedValueParser::map`] for adapting values to a more specialized type, like an external +/// enums that can't implement [`ValueEnum`][crate::ValueEnum] +/// +/// # Example +/// +/// Usage: +/// ```rust +/// # use clap_builder as clap; +/// let mut cmd = clap::Command::new("raw") +/// .arg( +/// clap::Arg::new("color") +/// .value_parser(clap::builder::PossibleValuesParser::new(["always", "auto", "never"])) +/// .required(true) +/// ); +/// +/// let m = cmd.try_get_matches_from_mut(["cmd", "always"]).unwrap(); +/// let port: &String = m.get_one("color") +/// .expect("required"); +/// assert_eq!(port, "always"); +/// ``` +/// +/// Semantics: +/// ```rust +/// # use clap_builder as clap; +/// # use std::ffi::OsStr; +/// # use clap::builder::TypedValueParser; +/// # let cmd = clap::Command::new("test"); +/// # let arg = None; +/// let value_parser = clap::builder::PossibleValuesParser::new(["always", "auto", "never"]); +/// assert!(value_parser.parse_ref(&cmd, arg, OsStr::new("random")).is_err()); +/// assert!(value_parser.parse_ref(&cmd, arg, OsStr::new("")).is_err()); +/// assert_eq!(value_parser.parse_ref(&cmd, arg, OsStr::new("always")).unwrap(), "always"); +/// assert_eq!(value_parser.parse_ref(&cmd, arg, OsStr::new("auto")).unwrap(), "auto"); +/// assert_eq!(value_parser.parse_ref(&cmd, arg, OsStr::new("never")).unwrap(), "never"); +/// ``` +#[derive(Clone, Debug)] +pub struct PossibleValuesParser(Vec<super::PossibleValue>); + +impl PossibleValuesParser { + /// Verify the value is from an enumerated set of [`PossibleValue`][crate::builder::PossibleValue]. + pub fn new(values: impl Into<PossibleValuesParser>) -> Self { + values.into() + } +} + +impl TypedValueParser for PossibleValuesParser { + type Value = String; + + fn parse_ref( + &self, + cmd: &crate::Command, + arg: Option<&crate::Arg>, + value: &std::ffi::OsStr, + ) -> Result<Self::Value, crate::Error> { + TypedValueParser::parse(self, cmd, arg, value.to_owned()) + } + + fn parse( + &self, + cmd: &crate::Command, + arg: Option<&crate::Arg>, + value: std::ffi::OsString, + ) -> Result<String, crate::Error> { + let value = ok!(value.into_string().map_err(|_| { + crate::Error::invalid_utf8( + cmd, + crate::output::Usage::new(cmd).create_usage_with_title(&[]), + ) + })); + + let ignore_case = arg.map(|a| a.is_ignore_case_set()).unwrap_or(false); + if self.0.iter().any(|v| v.matches(&value, ignore_case)) { + Ok(value) + } else { + let possible_vals = self + .0 + .iter() + .filter(|v| !v.is_hide_set()) + .map(|v| v.get_name().to_owned()) + .collect::<Vec<_>>(); + + Err(crate::Error::invalid_value( + cmd, + value, + &possible_vals, + arg.map(ToString::to_string) + .unwrap_or_else(|| "...".to_owned()), + )) + } + } + + fn possible_values( + &self, + ) -> Option<Box<dyn Iterator<Item = crate::builder::PossibleValue> + '_>> { + Some(Box::new(self.0.iter().cloned())) + } +} + +impl<I, T> From<I> for PossibleValuesParser +where + I: IntoIterator<Item = T>, + T: Into<super::PossibleValue>, +{ + fn from(values: I) -> Self { + Self(values.into_iter().map(|t| t.into()).collect()) + } +} + +/// Parse number that fall within a range of values +/// +/// **NOTE:** To capture negative values, you will also need to set +/// [`Arg::allow_negative_numbers`][crate::Arg::allow_negative_numbers] or +/// [`Arg::allow_hyphen_values`][crate::Arg::allow_hyphen_values]. +/// +/// # Example +/// +/// Usage: +/// ```rust +/// # use clap_builder as clap; +/// let mut cmd = clap::Command::new("raw") +/// .arg( +/// clap::Arg::new("port") +/// .long("port") +/// .value_parser(clap::value_parser!(u16).range(3000..)) +/// .action(clap::ArgAction::Set) +/// .required(true) +/// ); +/// +/// let m = cmd.try_get_matches_from_mut(["cmd", "--port", "3001"]).unwrap(); +/// let port: u16 = *m.get_one("port") +/// .expect("required"); +/// assert_eq!(port, 3001); +/// ``` +/// +/// Semantics: +/// ```rust +/// # use clap_builder as clap; +/// # use std::ffi::OsStr; +/// # use clap::builder::TypedValueParser; +/// # let cmd = clap::Command::new("test"); +/// # let arg = None; +/// let value_parser = clap::builder::RangedI64ValueParser::<i32>::new().range(-1..200); +/// assert!(value_parser.parse_ref(&cmd, arg, OsStr::new("random")).is_err()); +/// assert!(value_parser.parse_ref(&cmd, arg, OsStr::new("")).is_err()); +/// assert!(value_parser.parse_ref(&cmd, arg, OsStr::new("-200")).is_err()); +/// assert!(value_parser.parse_ref(&cmd, arg, OsStr::new("300")).is_err()); +/// assert_eq!(value_parser.parse_ref(&cmd, arg, OsStr::new("-1")).unwrap(), -1); +/// assert_eq!(value_parser.parse_ref(&cmd, arg, OsStr::new("0")).unwrap(), 0); +/// assert_eq!(value_parser.parse_ref(&cmd, arg, OsStr::new("50")).unwrap(), 50); +/// ``` +#[derive(Copy, Clone, Debug)] +pub struct RangedI64ValueParser<T: std::convert::TryFrom<i64> + Clone + Send + Sync = i64> { + bounds: (std::ops::Bound<i64>, std::ops::Bound<i64>), + target: std::marker::PhantomData<T>, +} + +impl<T: std::convert::TryFrom<i64> + Clone + Send + Sync> RangedI64ValueParser<T> { + /// Select full range of `i64` + pub fn new() -> Self { + Self::from(..) + } + + /// Narrow the supported range + pub fn range<B: RangeBounds<i64>>(mut self, range: B) -> Self { + // Consideration: when the user does `value_parser!(u8).range()` + // - Avoid programming mistakes by accidentally expanding the range + // - Make it convenient to limit the range like with `..10` + let start = match range.start_bound() { + l @ std::ops::Bound::Included(i) => { + debug_assert!( + self.bounds.contains(i), + "{} must be in {:?}", + i, + self.bounds + ); + l.cloned() + } + l @ std::ops::Bound::Excluded(i) => { + debug_assert!( + self.bounds.contains(&i.saturating_add(1)), + "{} must be in {:?}", + i, + self.bounds + ); + l.cloned() + } + std::ops::Bound::Unbounded => self.bounds.start_bound().cloned(), + }; + let end = match range.end_bound() { + l @ std::ops::Bound::Included(i) => { + debug_assert!( + self.bounds.contains(i), + "{} must be in {:?}", + i, + self.bounds + ); + l.cloned() + } + l @ std::ops::Bound::Excluded(i) => { + debug_assert!( + self.bounds.contains(&i.saturating_sub(1)), + "{} must be in {:?}", + i, + self.bounds + ); + l.cloned() + } + std::ops::Bound::Unbounded => self.bounds.end_bound().cloned(), + }; + self.bounds = (start, end); + self + } + + fn format_bounds(&self) -> String { + let mut result = match self.bounds.0 { + std::ops::Bound::Included(i) => i.to_string(), + std::ops::Bound::Excluded(i) => i.saturating_add(1).to_string(), + std::ops::Bound::Unbounded => i64::MIN.to_string(), + }; + result.push_str(".."); + match self.bounds.1 { + std::ops::Bound::Included(i) => { + result.push('='); + result.push_str(&i.to_string()); + } + std::ops::Bound::Excluded(i) => { + result.push_str(&i.to_string()); + } + std::ops::Bound::Unbounded => { + result.push_str(&i64::MAX.to_string()); + } + } + result + } +} + +impl<T: std::convert::TryFrom<i64> + Clone + Send + Sync + 'static> TypedValueParser + for RangedI64ValueParser<T> +where + <T as std::convert::TryFrom<i64>>::Error: Send + Sync + 'static + std::error::Error + ToString, +{ + type Value = T; + + fn parse_ref( + &self, + cmd: &crate::Command, + arg: Option<&crate::Arg>, + raw_value: &std::ffi::OsStr, + ) -> Result<Self::Value, crate::Error> { + let value = ok!(raw_value.to_str().ok_or_else(|| { + crate::Error::invalid_utf8( + cmd, + crate::output::Usage::new(cmd).create_usage_with_title(&[]), + ) + })); + let value = ok!(value.parse::<i64>().map_err(|err| { + let arg = arg + .map(|a| a.to_string()) + .unwrap_or_else(|| "...".to_owned()); + crate::Error::value_validation( + arg, + raw_value.to_string_lossy().into_owned(), + err.into(), + ) + .with_cmd(cmd) + })); + if !self.bounds.contains(&value) { + let arg = arg + .map(|a| a.to_string()) + .unwrap_or_else(|| "...".to_owned()); + return Err(crate::Error::value_validation( + arg, + raw_value.to_string_lossy().into_owned(), + format!("{} is not in {}", value, self.format_bounds()).into(), + ) + .with_cmd(cmd)); + } + + let value: Result<Self::Value, _> = value.try_into(); + let value = ok!(value.map_err(|err| { + let arg = arg + .map(|a| a.to_string()) + .unwrap_or_else(|| "...".to_owned()); + crate::Error::value_validation( + arg, + raw_value.to_string_lossy().into_owned(), + err.into(), + ) + .with_cmd(cmd) + })); + + Ok(value) + } +} + +impl<T: std::convert::TryFrom<i64> + Clone + Send + Sync, B: RangeBounds<i64>> From<B> + for RangedI64ValueParser<T> +{ + fn from(range: B) -> Self { + Self { + bounds: (range.start_bound().cloned(), range.end_bound().cloned()), + target: Default::default(), + } + } +} + +impl<T: std::convert::TryFrom<i64> + Clone + Send + Sync> Default for RangedI64ValueParser<T> { + fn default() -> Self { + Self::new() + } +} + +/// Parse number that fall within a range of values +/// +/// # Example +/// +/// Usage: +/// ```rust +/// # use clap_builder as clap; +/// let mut cmd = clap::Command::new("raw") +/// .arg( +/// clap::Arg::new("port") +/// .long("port") +/// .value_parser(clap::value_parser!(u64).range(3000..)) +/// .action(clap::ArgAction::Set) +/// .required(true) +/// ); +/// +/// let m = cmd.try_get_matches_from_mut(["cmd", "--port", "3001"]).unwrap(); +/// let port: u64 = *m.get_one("port") +/// .expect("required"); +/// assert_eq!(port, 3001); +/// ``` +/// +/// Semantics: +/// ```rust +/// # use clap_builder as clap; +/// # use std::ffi::OsStr; +/// # use clap::builder::TypedValueParser; +/// # let cmd = clap::Command::new("test"); +/// # let arg = None; +/// let value_parser = clap::builder::RangedU64ValueParser::<u32>::new().range(0..200); +/// assert!(value_parser.parse_ref(&cmd, arg, OsStr::new("random")).is_err()); +/// assert!(value_parser.parse_ref(&cmd, arg, OsStr::new("")).is_err()); +/// assert!(value_parser.parse_ref(&cmd, arg, OsStr::new("-200")).is_err()); +/// assert!(value_parser.parse_ref(&cmd, arg, OsStr::new("300")).is_err()); +/// assert!(value_parser.parse_ref(&cmd, arg, OsStr::new("-1")).is_err()); +/// assert_eq!(value_parser.parse_ref(&cmd, arg, OsStr::new("0")).unwrap(), 0); +/// assert_eq!(value_parser.parse_ref(&cmd, arg, OsStr::new("50")).unwrap(), 50); +/// ``` +#[derive(Copy, Clone, Debug)] +pub struct RangedU64ValueParser<T: std::convert::TryFrom<u64> = u64> { + bounds: (std::ops::Bound<u64>, std::ops::Bound<u64>), + target: std::marker::PhantomData<T>, +} + +impl<T: std::convert::TryFrom<u64>> RangedU64ValueParser<T> { + /// Select full range of `u64` + pub fn new() -> Self { + Self::from(..) + } + + /// Narrow the supported range + pub fn range<B: RangeBounds<u64>>(mut self, range: B) -> Self { + // Consideration: when the user does `value_parser!(u8).range()` + // - Avoid programming mistakes by accidentally expanding the range + // - Make it convenient to limit the range like with `..10` + let start = match range.start_bound() { + l @ std::ops::Bound::Included(i) => { + debug_assert!( + self.bounds.contains(i), + "{} must be in {:?}", + i, + self.bounds + ); + l.cloned() + } + l @ std::ops::Bound::Excluded(i) => { + debug_assert!( + self.bounds.contains(&i.saturating_add(1)), + "{} must be in {:?}", + i, + self.bounds + ); + l.cloned() + } + std::ops::Bound::Unbounded => self.bounds.start_bound().cloned(), + }; + let end = match range.end_bound() { + l @ std::ops::Bound::Included(i) => { + debug_assert!( + self.bounds.contains(i), + "{} must be in {:?}", + i, + self.bounds + ); + l.cloned() + } + l @ std::ops::Bound::Excluded(i) => { + debug_assert!( + self.bounds.contains(&i.saturating_sub(1)), + "{} must be in {:?}", + i, + self.bounds + ); + l.cloned() + } + std::ops::Bound::Unbounded => self.bounds.end_bound().cloned(), + }; + self.bounds = (start, end); + self + } + + fn format_bounds(&self) -> String { + let mut result = match self.bounds.0 { + std::ops::Bound::Included(i) => i.to_string(), + std::ops::Bound::Excluded(i) => i.saturating_add(1).to_string(), + std::ops::Bound::Unbounded => u64::MIN.to_string(), + }; + result.push_str(".."); + match self.bounds.1 { + std::ops::Bound::Included(i) => { + result.push('='); + result.push_str(&i.to_string()); + } + std::ops::Bound::Excluded(i) => { + result.push_str(&i.to_string()); + } + std::ops::Bound::Unbounded => { + result.push_str(&u64::MAX.to_string()); + } + } + result + } +} + +impl<T: std::convert::TryFrom<u64> + Clone + Send + Sync + 'static> TypedValueParser + for RangedU64ValueParser<T> +where + <T as std::convert::TryFrom<u64>>::Error: Send + Sync + 'static + std::error::Error + ToString, +{ + type Value = T; + + fn parse_ref( + &self, + cmd: &crate::Command, + arg: Option<&crate::Arg>, + raw_value: &std::ffi::OsStr, + ) -> Result<Self::Value, crate::Error> { + let value = ok!(raw_value.to_str().ok_or_else(|| { + crate::Error::invalid_utf8( + cmd, + crate::output::Usage::new(cmd).create_usage_with_title(&[]), + ) + })); + let value = ok!(value.parse::<u64>().map_err(|err| { + let arg = arg + .map(|a| a.to_string()) + .unwrap_or_else(|| "...".to_owned()); + crate::Error::value_validation( + arg, + raw_value.to_string_lossy().into_owned(), + err.into(), + ) + .with_cmd(cmd) + })); + if !self.bounds.contains(&value) { + let arg = arg + .map(|a| a.to_string()) + .unwrap_or_else(|| "...".to_owned()); + return Err(crate::Error::value_validation( + arg, + raw_value.to_string_lossy().into_owned(), + format!("{} is not in {}", value, self.format_bounds()).into(), + ) + .with_cmd(cmd)); + } + + let value: Result<Self::Value, _> = value.try_into(); + let value = ok!(value.map_err(|err| { + let arg = arg + .map(|a| a.to_string()) + .unwrap_or_else(|| "...".to_owned()); + crate::Error::value_validation( + arg, + raw_value.to_string_lossy().into_owned(), + err.into(), + ) + .with_cmd(cmd) + })); + + Ok(value) + } +} + +impl<T: std::convert::TryFrom<u64>, B: RangeBounds<u64>> From<B> for RangedU64ValueParser<T> { + fn from(range: B) -> Self { + Self { + bounds: (range.start_bound().cloned(), range.end_bound().cloned()), + target: Default::default(), + } + } +} + +impl<T: std::convert::TryFrom<u64>> Default for RangedU64ValueParser<T> { + fn default() -> Self { + Self::new() + } +} + +/// Implementation for [`ValueParser::bool`] +/// +/// Useful for composing new [`TypedValueParser`]s +#[derive(Copy, Clone, Debug)] +#[non_exhaustive] +pub struct BoolValueParser {} + +impl BoolValueParser { + /// Implementation for [`ValueParser::bool`] + pub fn new() -> Self { + Self {} + } + + fn possible_values() -> impl Iterator<Item = crate::builder::PossibleValue> { + ["true", "false"] + .iter() + .copied() + .map(crate::builder::PossibleValue::new) + } +} + +impl TypedValueParser for BoolValueParser { + type Value = bool; + + fn parse_ref( + &self, + cmd: &crate::Command, + arg: Option<&crate::Arg>, + value: &std::ffi::OsStr, + ) -> Result<Self::Value, crate::Error> { + let value = if value == std::ffi::OsStr::new("true") { + true + } else if value == std::ffi::OsStr::new("false") { + false + } else { + // Intentionally showing hidden as we hide all of them + let possible_vals = Self::possible_values() + .map(|v| v.get_name().to_owned()) + .collect::<Vec<_>>(); + + return Err(crate::Error::invalid_value( + cmd, + value.to_string_lossy().into_owned(), + &possible_vals, + arg.map(ToString::to_string) + .unwrap_or_else(|| "...".to_owned()), + )); + }; + Ok(value) + } + + fn possible_values( + &self, + ) -> Option<Box<dyn Iterator<Item = crate::builder::PossibleValue> + '_>> { + Some(Box::new(Self::possible_values())) + } +} + +impl Default for BoolValueParser { + fn default() -> Self { + Self::new() + } +} + +/// Parse false-like string values, everything else is `true` +/// +/// See also: +/// - [`ValueParser::bool`] for assuming non-false is true +/// - [`BoolishValueParser`] for different human readable bool representations +/// +/// # Example +/// +/// Usage: +/// ```rust +/// # use clap_builder as clap; +/// let mut cmd = clap::Command::new("raw") +/// .arg( +/// clap::Arg::new("append") +/// .value_parser(clap::builder::FalseyValueParser::new()) +/// .required(true) +/// ); +/// +/// let m = cmd.try_get_matches_from_mut(["cmd", "true"]).unwrap(); +/// let port: bool = *m.get_one("append") +/// .expect("required"); +/// assert_eq!(port, true); +/// ``` +/// +/// Semantics: +/// ```rust +/// # use clap_builder as clap; +/// # use std::ffi::OsStr; +/// # use clap::builder::TypedValueParser; +/// # let cmd = clap::Command::new("test"); +/// # let arg = None; +/// let value_parser = clap::builder::FalseyValueParser::new(); +/// assert_eq!(value_parser.parse_ref(&cmd, arg, OsStr::new("random")).unwrap(), true); +/// assert_eq!(value_parser.parse_ref(&cmd, arg, OsStr::new("100")).unwrap(), true); +/// assert_eq!(value_parser.parse_ref(&cmd, arg, OsStr::new("")).unwrap(), false); +/// assert_eq!(value_parser.parse_ref(&cmd, arg, OsStr::new("false")).unwrap(), false); +/// assert_eq!(value_parser.parse_ref(&cmd, arg, OsStr::new("No")).unwrap(), false); +/// assert_eq!(value_parser.parse_ref(&cmd, arg, OsStr::new("oFF")).unwrap(), false); +/// assert_eq!(value_parser.parse_ref(&cmd, arg, OsStr::new("0")).unwrap(), false); +/// ``` +#[derive(Copy, Clone, Debug)] +#[non_exhaustive] +pub struct FalseyValueParser {} + +impl FalseyValueParser { + /// Parse false-like string values, everything else is `true` + pub fn new() -> Self { + Self {} + } + + fn possible_values() -> impl Iterator<Item = crate::builder::PossibleValue> { + crate::util::TRUE_LITERALS + .iter() + .chain(crate::util::FALSE_LITERALS.iter()) + .copied() + .map(|l| crate::builder::PossibleValue::new(l).hide(l != "true" && l != "false")) + } +} + +impl TypedValueParser for FalseyValueParser { + type Value = bool; + + fn parse_ref( + &self, + cmd: &crate::Command, + _arg: Option<&crate::Arg>, + value: &std::ffi::OsStr, + ) -> Result<Self::Value, crate::Error> { + let value = ok!(value.to_str().ok_or_else(|| { + crate::Error::invalid_utf8( + cmd, + crate::output::Usage::new(cmd).create_usage_with_title(&[]), + ) + })); + let value = if value.is_empty() { + false + } else { + crate::util::str_to_bool(value).unwrap_or(true) + }; + Ok(value) + } + + fn possible_values( + &self, + ) -> Option<Box<dyn Iterator<Item = crate::builder::PossibleValue> + '_>> { + Some(Box::new(Self::possible_values())) + } +} + +impl Default for FalseyValueParser { + fn default() -> Self { + Self::new() + } +} + +/// Parse bool-like string values, everything else is `true` +/// +/// See also: +/// - [`ValueParser::bool`] for different human readable bool representations +/// - [`FalseyValueParser`] for assuming non-false is true +/// +/// # Example +/// +/// Usage: +/// ```rust +/// # use clap_builder as clap; +/// let mut cmd = clap::Command::new("raw") +/// .arg( +/// clap::Arg::new("append") +/// .value_parser(clap::builder::BoolishValueParser::new()) +/// .required(true) +/// ); +/// +/// let m = cmd.try_get_matches_from_mut(["cmd", "true"]).unwrap(); +/// let port: bool = *m.get_one("append") +/// .expect("required"); +/// assert_eq!(port, true); +/// ``` +/// +/// Semantics: +/// ```rust +/// # use clap_builder as clap; +/// # use std::ffi::OsStr; +/// # use clap::builder::TypedValueParser; +/// # let cmd = clap::Command::new("test"); +/// # let arg = None; +/// let value_parser = clap::builder::BoolishValueParser::new(); +/// assert!(value_parser.parse_ref(&cmd, arg, OsStr::new("random")).is_err()); +/// assert!(value_parser.parse_ref(&cmd, arg, OsStr::new("")).is_err()); +/// assert!(value_parser.parse_ref(&cmd, arg, OsStr::new("100")).is_err()); +/// assert_eq!(value_parser.parse_ref(&cmd, arg, OsStr::new("true")).unwrap(), true); +/// assert_eq!(value_parser.parse_ref(&cmd, arg, OsStr::new("Yes")).unwrap(), true); +/// assert_eq!(value_parser.parse_ref(&cmd, arg, OsStr::new("oN")).unwrap(), true); +/// assert_eq!(value_parser.parse_ref(&cmd, arg, OsStr::new("1")).unwrap(), true); +/// assert_eq!(value_parser.parse_ref(&cmd, arg, OsStr::new("false")).unwrap(), false); +/// assert_eq!(value_parser.parse_ref(&cmd, arg, OsStr::new("No")).unwrap(), false); +/// assert_eq!(value_parser.parse_ref(&cmd, arg, OsStr::new("oFF")).unwrap(), false); +/// assert_eq!(value_parser.parse_ref(&cmd, arg, OsStr::new("0")).unwrap(), false); +/// ``` +#[derive(Copy, Clone, Debug)] +#[non_exhaustive] +pub struct BoolishValueParser {} + +impl BoolishValueParser { + /// Parse bool-like string values, everything else is `true` + pub fn new() -> Self { + Self {} + } + + fn possible_values() -> impl Iterator<Item = crate::builder::PossibleValue> { + crate::util::TRUE_LITERALS + .iter() + .chain(crate::util::FALSE_LITERALS.iter()) + .copied() + .map(|l| crate::builder::PossibleValue::new(l).hide(l != "true" && l != "false")) + } +} + +impl TypedValueParser for BoolishValueParser { + type Value = bool; + + fn parse_ref( + &self, + cmd: &crate::Command, + arg: Option<&crate::Arg>, + value: &std::ffi::OsStr, + ) -> Result<Self::Value, crate::Error> { + let value = ok!(value.to_str().ok_or_else(|| { + crate::Error::invalid_utf8( + cmd, + crate::output::Usage::new(cmd).create_usage_with_title(&[]), + ) + })); + let value = ok!(crate::util::str_to_bool(value).ok_or_else(|| { + let arg = arg + .map(|a| a.to_string()) + .unwrap_or_else(|| "...".to_owned()); + crate::Error::value_validation(arg, value.to_owned(), "value was not a boolean".into()) + .with_cmd(cmd) + })); + Ok(value) + } + + fn possible_values( + &self, + ) -> Option<Box<dyn Iterator<Item = crate::builder::PossibleValue> + '_>> { + Some(Box::new(Self::possible_values())) + } +} + +impl Default for BoolishValueParser { + fn default() -> Self { + Self::new() + } +} + +/// Parse non-empty string values +/// +/// See also: +/// - [`ValueParser::string`] +/// +/// # Example +/// +/// Usage: +/// ```rust +/// # use clap_builder as clap; +/// let mut cmd = clap::Command::new("raw") +/// .arg( +/// clap::Arg::new("append") +/// .value_parser(clap::builder::NonEmptyStringValueParser::new()) +/// .required(true) +/// ); +/// +/// let m = cmd.try_get_matches_from_mut(["cmd", "true"]).unwrap(); +/// let port: &String = m.get_one("append") +/// .expect("required"); +/// assert_eq!(port, "true"); +/// ``` +/// +/// Semantics: +/// ```rust +/// # use clap_builder as clap; +/// # use std::ffi::OsStr; +/// # use clap::builder::TypedValueParser; +/// # let cmd = clap::Command::new("test"); +/// # let arg = None; +/// let value_parser = clap::builder::NonEmptyStringValueParser::new(); +/// assert_eq!(value_parser.parse_ref(&cmd, arg, OsStr::new("random")).unwrap(), "random"); +/// assert!(value_parser.parse_ref(&cmd, arg, OsStr::new("")).is_err()); +/// ``` +#[derive(Copy, Clone, Debug)] +#[non_exhaustive] +pub struct NonEmptyStringValueParser {} + +impl NonEmptyStringValueParser { + /// Parse non-empty string values + pub fn new() -> Self { + Self {} + } +} + +impl TypedValueParser for NonEmptyStringValueParser { + type Value = String; + + fn parse_ref( + &self, + cmd: &crate::Command, + arg: Option<&crate::Arg>, + value: &std::ffi::OsStr, + ) -> Result<Self::Value, crate::Error> { + if value.is_empty() { + return Err(crate::Error::empty_value( + cmd, + &[], + arg.map(ToString::to_string) + .unwrap_or_else(|| "...".to_owned()), + )); + } + let value = ok!(value.to_str().ok_or_else(|| { + crate::Error::invalid_utf8( + cmd, + crate::output::Usage::new(cmd).create_usage_with_title(&[]), + ) + })); + Ok(value.to_owned()) + } +} + +impl Default for NonEmptyStringValueParser { + fn default() -> Self { + Self::new() + } +} + +/// Adapt a `TypedValueParser` from one value to another +/// +/// See [`TypedValueParser::map`] +#[derive(Clone, Debug)] +pub struct MapValueParser<P, F> { + parser: P, + func: F, +} + +impl<P, F, T> MapValueParser<P, F> +where + P: TypedValueParser, + P::Value: Send + Sync + Clone, + F: Fn(P::Value) -> T + Clone, + T: Send + Sync + Clone, +{ + fn new(parser: P, func: F) -> Self { + Self { parser, func } + } +} + +impl<P, F, T> TypedValueParser for MapValueParser<P, F> +where + P: TypedValueParser, + P::Value: Send + Sync + Clone, + F: Fn(P::Value) -> T + Clone + Send + Sync + 'static, + T: Send + Sync + Clone, +{ + type Value = T; + + fn parse_ref( + &self, + cmd: &crate::Command, + arg: Option<&crate::Arg>, + value: &std::ffi::OsStr, + ) -> Result<Self::Value, crate::Error> { + let value = ok!(self.parser.parse_ref(cmd, arg, value)); + let value = (self.func)(value); + Ok(value) + } + + fn parse( + &self, + cmd: &crate::Command, + arg: Option<&crate::Arg>, + value: std::ffi::OsString, + ) -> Result<Self::Value, crate::Error> { + let value = ok!(self.parser.parse(cmd, arg, value)); + let value = (self.func)(value); + Ok(value) + } + + fn possible_values( + &self, + ) -> Option<Box<dyn Iterator<Item = crate::builder::PossibleValue> + '_>> { + self.parser.possible_values() + } +} + +/// Adapt a `TypedValueParser` from one value to another +/// +/// See [`TypedValueParser::try_map`] +#[derive(Clone, Debug)] +pub struct TryMapValueParser<P, F> { + parser: P, + func: F, +} + +impl<P, F, T, E> TryMapValueParser<P, F> +where + P: TypedValueParser, + P::Value: Send + Sync + Clone, + F: Fn(P::Value) -> Result<T, E> + Clone + Send + Sync + 'static, + T: Send + Sync + Clone, + E: Into<Box<dyn std::error::Error + Send + Sync + 'static>>, +{ + fn new(parser: P, func: F) -> Self { + Self { parser, func } + } +} + +impl<P, F, T, E> TypedValueParser for TryMapValueParser<P, F> +where + P: TypedValueParser, + P::Value: Send + Sync + Clone, + F: Fn(P::Value) -> Result<T, E> + Clone + Send + Sync + 'static, + T: Send + Sync + Clone, + E: Into<Box<dyn std::error::Error + Send + Sync + 'static>>, +{ + type Value = T; + + fn parse_ref( + &self, + cmd: &crate::Command, + arg: Option<&crate::Arg>, + value: &std::ffi::OsStr, + ) -> Result<Self::Value, crate::Error> { + let mid_value = ok!(self.parser.parse_ref(cmd, arg, value)); + let value = ok!((self.func)(mid_value).map_err(|e| { + let arg = arg + .map(|a| a.to_string()) + .unwrap_or_else(|| "...".to_owned()); + crate::Error::value_validation(arg, value.to_string_lossy().into_owned(), e.into()) + .with_cmd(cmd) + })); + Ok(value) + } + + fn possible_values( + &self, + ) -> Option<Box<dyn Iterator<Item = crate::builder::PossibleValue> + '_>> { + self.parser.possible_values() + } +} + +/// When encountered, report [ErrorKind::UnknownArgument][crate::error::ErrorKind::UnknownArgument] +/// +/// Useful to help users migrate, either from old versions or similar tools. +/// +/// # Examples +/// +/// ```rust +/// # use clap_builder as clap; +/// # use clap::Command; +/// # use clap::Arg; +/// let cmd = Command::new("mycmd") +/// .args([ +/// Arg::new("current-dir") +/// .short('C'), +/// Arg::new("current-dir-unknown") +/// .long("cwd") +/// .aliases(["current-dir", "directory", "working-directory", "root"]) +/// .value_parser(clap::builder::UnknownArgumentValueParser::suggest_arg("-C")) +/// .hide(true), +/// ]); +/// +/// // Use a supported version of the argument +/// let matches = cmd.clone().try_get_matches_from(["mycmd", "-C", ".."]).unwrap(); +/// assert!(matches.contains_id("current-dir")); +/// assert_eq!( +/// matches.get_many::<String>("current-dir").unwrap_or_default().map(|v| v.as_str()).collect::<Vec<_>>(), +/// vec![".."] +/// ); +/// +/// // Use one of the invalid versions +/// let err = cmd.try_get_matches_from(["mycmd", "--cwd", ".."]).unwrap_err(); +/// assert_eq!(err.kind(), clap::error::ErrorKind::UnknownArgument); +/// ``` +#[derive(Clone, Debug)] +pub struct UnknownArgumentValueParser { + arg: Option<Str>, + suggestions: Vec<StyledStr>, +} + +impl UnknownArgumentValueParser { + /// Suggest an alternative argument + pub fn suggest_arg(arg: impl Into<Str>) -> Self { + Self { + arg: Some(arg.into()), + suggestions: Default::default(), + } + } + + /// Provide a general suggestion + pub fn suggest(text: impl Into<StyledStr>) -> Self { + Self { + arg: Default::default(), + suggestions: vec![text.into()], + } + } + + /// Extend the suggestions + pub fn and_suggest(mut self, text: impl Into<StyledStr>) -> Self { + self.suggestions.push(text.into()); + self + } +} + +impl TypedValueParser for UnknownArgumentValueParser { + type Value = String; + + fn parse_ref( + &self, + cmd: &crate::Command, + arg: Option<&crate::Arg>, + value: &std::ffi::OsStr, + ) -> Result<Self::Value, crate::Error> { + TypedValueParser::parse_ref_(self, cmd, arg, value, ValueSource::CommandLine) + } + + fn parse_ref_( + &self, + cmd: &crate::Command, + arg: Option<&crate::Arg>, + _value: &std::ffi::OsStr, + source: ValueSource, + ) -> Result<Self::Value, crate::Error> { + match source { + ValueSource::DefaultValue => { + TypedValueParser::parse_ref_(&StringValueParser::new(), cmd, arg, _value, source) + } + ValueSource::EnvVariable | ValueSource::CommandLine => { + let arg = match arg { + Some(arg) => arg.to_string(), + None => "..".to_owned(), + }; + let err = crate::Error::unknown_argument( + cmd, + arg, + self.arg.as_ref().map(|s| (s.as_str().to_owned(), None)), + false, + crate::output::Usage::new(cmd).create_usage_with_title(&[]), + ); + #[cfg(feature = "error-context")] + let err = { + debug_assert_eq!( + err.get(crate::error::ContextKind::Suggested), + None, + "Assuming `Error::unknown_argument` doesn't apply any `Suggested` so we can without caution" + ); + err.insert_context_unchecked( + crate::error::ContextKind::Suggested, + crate::error::ContextValue::StyledStrs(self.suggestions.clone()), + ) + }; + Err(err) + } + } + } +} + +/// Register a type with [value_parser!][crate::value_parser!] +/// +/// # Example +/// +/// ```rust +/// # use clap_builder as clap; +/// #[derive(Copy, Clone, Debug)] +/// pub struct Custom(u32); +/// +/// impl clap::builder::ValueParserFactory for Custom { +/// type Parser = CustomValueParser; +/// fn value_parser() -> Self::Parser { +/// CustomValueParser +/// } +/// } +/// +/// #[derive(Clone, Debug)] +/// pub struct CustomValueParser; +/// impl clap::builder::TypedValueParser for CustomValueParser { +/// type Value = Custom; +/// +/// fn parse_ref( +/// &self, +/// cmd: &clap::Command, +/// arg: Option<&clap::Arg>, +/// value: &std::ffi::OsStr, +/// ) -> Result<Self::Value, clap::Error> { +/// let inner = clap::value_parser!(u32); +/// let val = inner.parse_ref(cmd, arg, value)?; +/// Ok(Custom(val)) +/// } +/// } +/// +/// let parser: CustomValueParser = clap::value_parser!(Custom); +/// ``` +pub trait ValueParserFactory { + /// Generated parser, usually [`ValueParser`]. + /// + /// It should at least be a type that supports `Into<ValueParser>`. A non-`ValueParser` type + /// allows the caller to do further initialization on the parser. + type Parser; + + /// Create the specified [`Self::Parser`] + fn value_parser() -> Self::Parser; +} +impl ValueParserFactory for String { + type Parser = ValueParser; + fn value_parser() -> Self::Parser { + ValueParser::string() // Default `clap_derive` to optimized implementation + } +} +impl ValueParserFactory for Box<str> { + type Parser = MapValueParser<StringValueParser, fn(String) -> Box<str>>; + fn value_parser() -> Self::Parser { + StringValueParser::new().map(String::into_boxed_str) + } +} +impl ValueParserFactory for std::ffi::OsString { + type Parser = ValueParser; + fn value_parser() -> Self::Parser { + ValueParser::os_string() // Default `clap_derive` to optimized implementation + } +} +impl ValueParserFactory for Box<std::ffi::OsStr> { + type Parser = + MapValueParser<OsStringValueParser, fn(std::ffi::OsString) -> Box<std::ffi::OsStr>>; + fn value_parser() -> Self::Parser { + OsStringValueParser::new().map(std::ffi::OsString::into_boxed_os_str) + } +} +impl ValueParserFactory for std::path::PathBuf { + type Parser = ValueParser; + fn value_parser() -> Self::Parser { + ValueParser::path_buf() // Default `clap_derive` to optimized implementation + } +} +impl ValueParserFactory for Box<std::path::Path> { + type Parser = + MapValueParser<PathBufValueParser, fn(std::path::PathBuf) -> Box<std::path::Path>>; + fn value_parser() -> Self::Parser { + PathBufValueParser::new().map(std::path::PathBuf::into_boxed_path) + } +} +impl ValueParserFactory for bool { + type Parser = ValueParser; + fn value_parser() -> Self::Parser { + ValueParser::bool() // Default `clap_derive` to optimized implementation + } +} +impl ValueParserFactory for u8 { + type Parser = RangedI64ValueParser<u8>; + fn value_parser() -> Self::Parser { + let start: i64 = u8::MIN.into(); + let end: i64 = u8::MAX.into(); + RangedI64ValueParser::new().range(start..=end) + } +} +impl ValueParserFactory for i8 { + type Parser = RangedI64ValueParser<i8>; + fn value_parser() -> Self::Parser { + let start: i64 = i8::MIN.into(); + let end: i64 = i8::MAX.into(); + RangedI64ValueParser::new().range(start..=end) + } +} +impl ValueParserFactory for u16 { + type Parser = RangedI64ValueParser<u16>; + fn value_parser() -> Self::Parser { + let start: i64 = u16::MIN.into(); + let end: i64 = u16::MAX.into(); + RangedI64ValueParser::new().range(start..=end) + } +} +impl ValueParserFactory for i16 { + type Parser = RangedI64ValueParser<i16>; + fn value_parser() -> Self::Parser { + let start: i64 = i16::MIN.into(); + let end: i64 = i16::MAX.into(); + RangedI64ValueParser::new().range(start..=end) + } +} +impl ValueParserFactory for u32 { + type Parser = RangedI64ValueParser<u32>; + fn value_parser() -> Self::Parser { + let start: i64 = u32::MIN.into(); + let end: i64 = u32::MAX.into(); + RangedI64ValueParser::new().range(start..=end) + } +} +impl ValueParserFactory for i32 { + type Parser = RangedI64ValueParser<i32>; + fn value_parser() -> Self::Parser { + let start: i64 = i32::MIN.into(); + let end: i64 = i32::MAX.into(); + RangedI64ValueParser::new().range(start..=end) + } +} +impl ValueParserFactory for u64 { + type Parser = RangedU64ValueParser<u64>; + fn value_parser() -> Self::Parser { + RangedU64ValueParser::new() + } +} +impl ValueParserFactory for i64 { + type Parser = RangedI64ValueParser<i64>; + fn value_parser() -> Self::Parser { + RangedI64ValueParser::new() + } +} +impl<T> ValueParserFactory for std::num::Wrapping<T> +where + T: ValueParserFactory, + <T as ValueParserFactory>::Parser: TypedValueParser<Value = T>, + T: Send + Sync + Clone, +{ + type Parser = MapValueParser<<T as ValueParserFactory>::Parser, fn(T) -> std::num::Wrapping<T>>; + fn value_parser() -> Self::Parser { + T::value_parser().map(std::num::Wrapping) + } +} +impl<T> ValueParserFactory for Box<T> +where + T: ValueParserFactory, + <T as ValueParserFactory>::Parser: TypedValueParser<Value = T>, + T: Send + Sync + Clone, +{ + type Parser = MapValueParser<<T as ValueParserFactory>::Parser, fn(T) -> Box<T>>; + fn value_parser() -> Self::Parser { + T::value_parser().map(Box::new) + } +} +impl<T> ValueParserFactory for std::sync::Arc<T> +where + T: ValueParserFactory, + <T as ValueParserFactory>::Parser: TypedValueParser<Value = T>, + T: Send + Sync + Clone, +{ + type Parser = MapValueParser<<T as ValueParserFactory>::Parser, fn(T) -> std::sync::Arc<T>>; + fn value_parser() -> Self::Parser { + T::value_parser().map(std::sync::Arc::new) + } +} + +#[doc(hidden)] +#[derive(Debug)] +pub struct _AutoValueParser<T>(std::marker::PhantomData<T>); + +impl<T> _AutoValueParser<T> { + #[doc(hidden)] + #[allow(clippy::new_without_default)] + pub fn new() -> Self { + Self(Default::default()) + } +} + +/// Unstable [`ValueParser`] +/// +/// Implementation may change to more specific instance in the future +#[doc(hidden)] +#[derive(Debug)] +pub struct _AnonymousValueParser(ValueParser); + +#[doc(hidden)] +pub mod via_prelude { + use super::*; + + #[doc(hidden)] + pub trait _ValueParserViaFactory: private::_ValueParserViaFactorySealed { + type Parser; + fn value_parser(&self) -> Self::Parser; + } + impl<P: ValueParserFactory> _ValueParserViaFactory for &&&&&&_AutoValueParser<P> { + type Parser = P::Parser; + fn value_parser(&self) -> Self::Parser { + P::value_parser() + } + } + + #[doc(hidden)] + pub trait _ValueParserViaValueEnum: private::_ValueParserViaValueEnumSealed { + type Output; + + fn value_parser(&self) -> Self::Output; + } + impl<E: crate::ValueEnum + Clone + Send + Sync + 'static> _ValueParserViaValueEnum + for &&&&&_AutoValueParser<E> + { + type Output = EnumValueParser<E>; + + fn value_parser(&self) -> Self::Output { + EnumValueParser::<E>::new() + } + } + + #[doc(hidden)] + pub trait _ValueParserViaFromOsString: private::_ValueParserViaFromOsStringSealed { + fn value_parser(&self) -> _AnonymousValueParser; + } + impl<FromOsString> _ValueParserViaFromOsString for &&&&_AutoValueParser<FromOsString> + where + FromOsString: From<std::ffi::OsString> + std::any::Any + Clone + Send + Sync + 'static, + { + fn value_parser(&self) -> _AnonymousValueParser { + _AnonymousValueParser( + OsStringValueParser::new() + .map(|s| FromOsString::from(s)) + .into(), + ) + } + } + + #[doc(hidden)] + pub trait _ValueParserViaFromOsStr: private::_ValueParserViaFromOsStrSealed { + fn value_parser(&self) -> _AnonymousValueParser; + } + impl<FromOsStr> _ValueParserViaFromOsStr for &&&_AutoValueParser<FromOsStr> + where + FromOsStr: + for<'s> From<&'s std::ffi::OsStr> + std::any::Any + Clone + Send + Sync + 'static, + { + fn value_parser(&self) -> _AnonymousValueParser { + _AnonymousValueParser( + OsStringValueParser::new() + .map(|s| FromOsStr::from(&s)) + .into(), + ) + } + } + + #[doc(hidden)] + pub trait _ValueParserViaFromString: private::_ValueParserViaFromStringSealed { + fn value_parser(&self) -> _AnonymousValueParser; + } + impl<FromString> _ValueParserViaFromString for &&_AutoValueParser<FromString> + where + FromString: From<String> + std::any::Any + Clone + Send + Sync + 'static, + { + fn value_parser(&self) -> _AnonymousValueParser { + _AnonymousValueParser(StringValueParser::new().map(|s| FromString::from(s)).into()) + } + } + + #[doc(hidden)] + pub trait _ValueParserViaFromStr: private::_ValueParserViaFromStrSealed { + fn value_parser(&self) -> _AnonymousValueParser; + } + impl<FromStr> _ValueParserViaFromStr for &_AutoValueParser<FromStr> + where + FromStr: for<'s> From<&'s str> + std::any::Any + Clone + Send + Sync + 'static, + { + fn value_parser(&self) -> _AnonymousValueParser { + _AnonymousValueParser(StringValueParser::new().map(|s| FromStr::from(&s)).into()) + } + } + + #[doc(hidden)] + pub trait _ValueParserViaParse: private::_ValueParserViaParseSealed { + fn value_parser(&self) -> _AnonymousValueParser; + } + impl<Parse> _ValueParserViaParse for _AutoValueParser<Parse> + where + Parse: std::str::FromStr + std::any::Any + Clone + Send + Sync + 'static, + <Parse as std::str::FromStr>::Err: Into<Box<dyn std::error::Error + Send + Sync + 'static>>, + { + fn value_parser(&self) -> _AnonymousValueParser { + let func: fn(&str) -> Result<Parse, <Parse as std::str::FromStr>::Err> = + Parse::from_str; + _AnonymousValueParser(ValueParser::new(func)) + } + } +} + +/// Select a [`ValueParser`] implementation from the intended type +/// +/// Supported types +/// - [`ValueParserFactory` types][ValueParserFactory], including +/// - [Native types][ValueParser]: `bool`, `String`, `OsString`, `PathBuf` +/// - [Ranged numeric types][RangedI64ValueParser]: `u8`, `i8`, `u16`, `i16`, `u32`, `i32`, `u64`, `i64` +/// - [`ValueEnum` types][crate::ValueEnum] +/// - [`From<OsString>` types][std::convert::From] and [`From<&OsStr>` types][std::convert::From] +/// - [`From<String>` types][std::convert::From] and [`From<&str>` types][std::convert::From] +/// - [`FromStr` types][std::str::FromStr], including usize, isize +/// +/// # Example +/// +/// Usage: +/// ```rust +/// # use clap_builder as clap; +/// # use std::path::PathBuf; +/// # use std::path::Path; +/// let mut cmd = clap::Command::new("raw") +/// .arg( +/// clap::Arg::new("output") +/// .value_parser(clap::value_parser!(PathBuf)) +/// .required(true) +/// ); +/// +/// let m = cmd.try_get_matches_from_mut(["cmd", "file.txt"]).unwrap(); +/// let port: &PathBuf = m.get_one("output") +/// .expect("required"); +/// assert_eq!(port, Path::new("file.txt")); +/// ``` +/// +/// Example mappings: +/// ```rust +/// # use clap_builder as clap; +/// # use clap::ColorChoice; +/// // Built-in types +/// let parser = clap::value_parser!(String); +/// assert_eq!(format!("{parser:?}"), "ValueParser::string"); +/// let parser = clap::value_parser!(std::ffi::OsString); +/// assert_eq!(format!("{parser:?}"), "ValueParser::os_string"); +/// let parser = clap::value_parser!(std::path::PathBuf); +/// assert_eq!(format!("{parser:?}"), "ValueParser::path_buf"); +/// clap::value_parser!(u16).range(3000..); +/// clap::value_parser!(u64).range(3000..); +/// +/// // FromStr types +/// let parser = clap::value_parser!(usize); +/// assert_eq!(format!("{parser:?}"), "_AnonymousValueParser(ValueParser::other(usize))"); +/// +/// // ValueEnum types +/// clap::value_parser!(ColorChoice); +/// ``` +#[macro_export] +macro_rules! value_parser { + ($name:ty) => {{ + use $crate::builder::via_prelude::*; + let auto = $crate::builder::_AutoValueParser::<$name>::new(); + (&&&&&&auto).value_parser() + }}; +} + +mod private { + use super::*; + + // Prefer these so `clap_derive` defaults to optimized implementations + pub trait _ValueParserViaSelfSealed {} + impl<P: Into<ValueParser>> _ValueParserViaSelfSealed for &&&&&&&_AutoValueParser<P> {} + + pub trait _ValueParserViaFactorySealed {} + impl<P: ValueParserFactory> _ValueParserViaFactorySealed for &&&&&&_AutoValueParser<P> {} + + pub trait _ValueParserViaValueEnumSealed {} + impl<E: crate::ValueEnum> _ValueParserViaValueEnumSealed for &&&&&_AutoValueParser<E> {} + + pub trait _ValueParserViaFromOsStringSealed {} + impl<FromOsString> _ValueParserViaFromOsStringSealed for &&&&_AutoValueParser<FromOsString> where + FromOsString: From<std::ffi::OsString> + std::any::Any + Send + Sync + 'static + { + } + + pub trait _ValueParserViaFromOsStrSealed {} + impl<FromOsStr> _ValueParserViaFromOsStrSealed for &&&_AutoValueParser<FromOsStr> where + FromOsStr: for<'s> From<&'s std::ffi::OsStr> + std::any::Any + Send + Sync + 'static + { + } + + pub trait _ValueParserViaFromStringSealed {} + impl<FromString> _ValueParserViaFromStringSealed for &&_AutoValueParser<FromString> where + FromString: From<String> + std::any::Any + Send + Sync + 'static + { + } + + pub trait _ValueParserViaFromStrSealed {} + impl<FromStr> _ValueParserViaFromStrSealed for &_AutoValueParser<FromStr> where + FromStr: for<'s> From<&'s str> + std::any::Any + Send + Sync + 'static + { + } + + pub trait _ValueParserViaParseSealed {} + impl<Parse> _ValueParserViaParseSealed for _AutoValueParser<Parse> + where + Parse: std::str::FromStr + std::any::Any + Send + Sync + 'static, + <Parse as std::str::FromStr>::Err: Into<Box<dyn std::error::Error + Send + Sync + 'static>>, + { + } +} + +#[cfg(test)] +mod test { + use super::*; + + #[test] + fn ensure_typed_applies_to_parse() { + fn parse(_: &str) -> Result<usize, std::io::Error> { + Ok(10) + } + let cmd = crate::Command::new("cmd"); + let arg = None; + assert_eq!( + TypedValueParser::parse_ref(&parse, &cmd, arg, std::ffi::OsStr::new("foo")).unwrap(), + 10 + ); + } +} diff --git a/vendor/clap_builder/src/derive.rs b/vendor/clap_builder/src/derive.rs new file mode 100644 index 0000000..7494e84 --- /dev/null +++ b/vendor/clap_builder/src/derive.rs @@ -0,0 +1,361 @@ +//! This module contains traits that are usable with the `#[derive(...)]` +//! macros in `clap_derive`. + +use crate::builder::PossibleValue; +use crate::{ArgMatches, Command, Error}; + +use std::ffi::OsString; + +/// Parse command-line arguments into `Self`. +/// +/// The primary one-stop-shop trait used to create an instance of a `clap` +/// [`Command`], conduct the parsing, and turn the resulting [`ArgMatches`] back +/// into concrete instance of the user struct. +/// +/// This trait is primarily a convenience on top of [`FromArgMatches`] + +/// [`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). +/// +/// See also [`Subcommand`] and [`Args`]. +/// +/// **NOTE:** Deriving requires the `derive` feature flag +pub trait Parser: FromArgMatches + CommandFactory + Sized { + /// Parse from `std::env::args_os()`, exit on error + fn parse() -> Self { + let mut matches = <Self as CommandFactory>::command().get_matches(); + let res = <Self as FromArgMatches>::from_arg_matches_mut(&mut matches) + .map_err(format_error::<Self>); + match res { + Ok(s) => s, + Err(e) => { + // Since this is more of a development-time error, we aren't doing as fancy of a quit + // as `get_matches` + e.exit() + } + } + } + + /// Parse from `std::env::args_os()`, return Err on error. + fn try_parse() -> Result<Self, Error> { + let mut matches = ok!(<Self as CommandFactory>::command().try_get_matches()); + <Self as FromArgMatches>::from_arg_matches_mut(&mut matches).map_err(format_error::<Self>) + } + + /// Parse from iterator, exit on error + fn parse_from<I, T>(itr: I) -> Self + where + I: IntoIterator<Item = T>, + T: Into<OsString> + Clone, + { + let mut matches = <Self as CommandFactory>::command().get_matches_from(itr); + let res = <Self as FromArgMatches>::from_arg_matches_mut(&mut matches) + .map_err(format_error::<Self>); + match res { + Ok(s) => s, + Err(e) => { + // Since this is more of a development-time error, we aren't doing as fancy of a quit + // as `get_matches_from` + e.exit() + } + } + } + + /// Parse from iterator, return Err on error. + fn try_parse_from<I, T>(itr: I) -> Result<Self, Error> + where + I: IntoIterator<Item = T>, + T: Into<OsString> + Clone, + { + let mut matches = ok!(<Self as CommandFactory>::command().try_get_matches_from(itr)); + <Self as FromArgMatches>::from_arg_matches_mut(&mut matches).map_err(format_error::<Self>) + } + + /// Update from iterator, exit on error + fn update_from<I, T>(&mut self, itr: I) + where + I: IntoIterator<Item = T>, + T: Into<OsString> + Clone, + { + let mut matches = <Self as CommandFactory>::command_for_update().get_matches_from(itr); + let res = <Self as FromArgMatches>::update_from_arg_matches_mut(self, &mut matches) + .map_err(format_error::<Self>); + if let Err(e) = res { + // Since this is more of a development-time error, we aren't doing as fancy of a quit + // as `get_matches_from` + e.exit() + } + } + + /// Update from iterator, return Err on error. + fn try_update_from<I, T>(&mut self, itr: I) -> Result<(), Error> + where + I: IntoIterator<Item = T>, + T: Into<OsString> + Clone, + { + let mut matches = + ok!(<Self as CommandFactory>::command_for_update().try_get_matches_from(itr)); + <Self as FromArgMatches>::update_from_arg_matches_mut(self, &mut matches) + .map_err(format_error::<Self>) + } +} + +/// Create a [`Command`] relevant for a user-defined container. +/// +/// Derived as part of [`Parser`]. +pub trait CommandFactory: Sized { + /// Build a [`Command`] that can instantiate `Self`. + /// + /// See [`FromArgMatches::from_arg_matches_mut`] for instantiating `Self`. + fn command() -> Command; + /// Build a [`Command`] that can update `self`. + /// + /// See [`FromArgMatches::update_from_arg_matches_mut`] for updating `self`. + fn command_for_update() -> Command; +} + +/// Converts an instance of [`ArgMatches`] to a user-defined container. +/// +/// Derived as part of [`Parser`], [`Args`], and [`Subcommand`]. +pub trait FromArgMatches: Sized { + /// Instantiate `Self` from [`ArgMatches`], parsing the arguments as needed. + /// + /// Motivation: If our application had two CLI options, `--name + /// <STRING>` and the flag `--debug`, we may create a struct as follows: + /// + /// ```rust + /// # #[cfg(feature = "derive")] { + /// struct Context { + /// name: String, + /// debug: bool + /// } + /// # } + /// ``` + /// + /// We then need to convert the `ArgMatches` that `clap` generated into our struct. + /// `from_arg_matches` serves as the equivalent of: + /// + /// ```rust + /// # #[cfg(feature = "derive")] { + /// # use clap::ArgMatches; + /// # struct Context { + /// # name: String, + /// # debug: bool + /// # } + /// impl From<ArgMatches> for Context { + /// fn from(m: ArgMatches) -> Self { + /// Context { + /// name: m.get_one::<String>("name").unwrap().clone(), + /// debug: m.get_flag("debug"), + /// } + /// } + /// } + /// # } + /// ``` + fn from_arg_matches(matches: &ArgMatches) -> Result<Self, Error>; + + /// Instantiate `Self` from [`ArgMatches`], parsing the arguments as needed. + /// + /// Motivation: If our application had two CLI options, `--name + /// <STRING>` and the flag `--debug`, we may create a struct as follows: + /// + /// ```rust + /// # #[cfg(feature = "derive")] { + /// struct Context { + /// name: String, + /// debug: bool + /// } + /// # } + /// ``` + /// + /// We then need to convert the `ArgMatches` that `clap` generated into our struct. + /// `from_arg_matches_mut` serves as the equivalent of: + /// + /// ```rust + /// # #[cfg(feature = "derive")] { + /// # use clap::ArgMatches; + /// # struct Context { + /// # name: String, + /// # debug: bool + /// # } + /// impl From<ArgMatches> for Context { + /// fn from(m: ArgMatches) -> Self { + /// Context { + /// name: m.get_one::<String>("name").unwrap().to_string(), + /// debug: m.get_flag("debug"), + /// } + /// } + /// } + /// # } + /// ``` + fn from_arg_matches_mut(matches: &mut ArgMatches) -> Result<Self, Error> { + Self::from_arg_matches(matches) + } + + /// Assign values from `ArgMatches` to `self`. + fn update_from_arg_matches(&mut self, matches: &ArgMatches) -> Result<(), Error>; + + /// Assign values from `ArgMatches` to `self`. + fn update_from_arg_matches_mut(&mut self, matches: &mut ArgMatches) -> Result<(), Error> { + self.update_from_arg_matches(matches) + } +} + +/// Parse a set of arguments into a user-defined container. +/// +/// Implementing this trait lets a parent container delegate argument parsing behavior to `Self`. +/// with: +/// - `#[command(flatten)] args: ChildArgs`: Attribute can only be used with struct fields that impl +/// `Args`. +/// - `Variant(ChildArgs)`: No attribute is used with enum variants that impl `Args`. +/// +/// **NOTE:** Deriving requires the `derive` feature flag +pub trait Args: FromArgMatches + Sized { + /// Report the [`ArgGroup::id`][crate::ArgGroup::id] for this set of arguments + fn group_id() -> Option<crate::Id> { + None + } + /// Append to [`Command`] so it can instantiate `Self`. + /// + /// See also [`CommandFactory`]. + fn augment_args(cmd: Command) -> Command; + /// Append to [`Command`] so it can update `self`. + /// + /// This is used to implement `#[command(flatten)]` + /// + /// See also [`CommandFactory`]. + fn augment_args_for_update(cmd: Command) -> Command; +} + +/// Parse a sub-command into a user-defined enum. +/// +/// Implementing this trait lets a parent container delegate subcommand behavior to `Self`. +/// with: +/// - `#[command(subcommand)] field: SubCmd`: Attribute can be used with either struct fields or enum +/// variants that impl `Subcommand`. +/// - `#[command(flatten)] Variant(SubCmd)`: Attribute can only be used with enum variants that impl +/// `Subcommand`. +/// +/// **NOTE:** Deriving requires the `derive` feature flag +pub trait Subcommand: FromArgMatches + Sized { + /// Append to [`Command`] so it can instantiate `Self`. + /// + /// See also [`CommandFactory`]. + fn augment_subcommands(cmd: Command) -> Command; + /// Append to [`Command`] so it can update `self`. + /// + /// This is used to implement `#[command(flatten)]` + /// + /// 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; +} + +/// Parse arguments into enums. +/// +/// When deriving [`Parser`], a field whose type implements `ValueEnum` can have the attribute +/// `#[arg(value_enum)]` which will +/// - Call [`EnumValueParser`][crate::builder::EnumValueParser] +/// - Allowing using the `#[arg(default_value_t)]` attribute without implementing `Display`. +/// +/// **NOTE:** Deriving requires the `derive` feature flag +pub trait ValueEnum: Sized + Clone { + /// All possible argument values, in display order. + fn value_variants<'a>() -> &'a [Self]; + + /// Parse an argument into `Self`. + fn from_str(input: &str, ignore_case: bool) -> Result<Self, String> { + Self::value_variants() + .iter() + .find(|v| { + v.to_possible_value() + .expect("ValueEnum::value_variants contains only values with a corresponding ValueEnum::to_possible_value") + .matches(input, ignore_case) + }) + .cloned() + .ok_or_else(|| format!("invalid variant: {input}")) + } + + /// The canonical argument value. + /// + /// The value is `None` for skipped variants. + fn to_possible_value(&self) -> Option<PossibleValue>; +} + +impl<T: Parser> Parser for Box<T> { + fn parse() -> Self { + Box::new(<T as Parser>::parse()) + } + + fn try_parse() -> Result<Self, Error> { + <T as Parser>::try_parse().map(Box::new) + } + + fn parse_from<I, It>(itr: I) -> Self + where + I: IntoIterator<Item = It>, + It: Into<OsString> + Clone, + { + Box::new(<T as Parser>::parse_from(itr)) + } + + fn try_parse_from<I, It>(itr: I) -> Result<Self, Error> + where + I: IntoIterator<Item = It>, + It: Into<OsString> + Clone, + { + <T as Parser>::try_parse_from(itr).map(Box::new) + } +} + +impl<T: CommandFactory> CommandFactory for Box<T> { + fn command<'help>() -> Command { + <T as CommandFactory>::command() + } + fn command_for_update<'help>() -> Command { + <T as CommandFactory>::command_for_update() + } +} + +impl<T: FromArgMatches> FromArgMatches for Box<T> { + fn from_arg_matches(matches: &ArgMatches) -> Result<Self, Error> { + <T as FromArgMatches>::from_arg_matches(matches).map(Box::new) + } + fn from_arg_matches_mut(matches: &mut ArgMatches) -> Result<Self, Error> { + <T as FromArgMatches>::from_arg_matches_mut(matches).map(Box::new) + } + fn update_from_arg_matches(&mut self, matches: &ArgMatches) -> Result<(), Error> { + <T as FromArgMatches>::update_from_arg_matches(self, matches) + } + fn update_from_arg_matches_mut(&mut self, matches: &mut ArgMatches) -> Result<(), Error> { + <T as FromArgMatches>::update_from_arg_matches_mut(self, matches) + } +} + +impl<T: Args> Args for Box<T> { + fn augment_args(cmd: Command) -> Command { + <T as Args>::augment_args(cmd) + } + fn augment_args_for_update(cmd: Command) -> Command { + <T as Args>::augment_args_for_update(cmd) + } +} + +impl<T: Subcommand> Subcommand for Box<T> { + fn augment_subcommands(cmd: Command) -> Command { + <T as Subcommand>::augment_subcommands(cmd) + } + fn augment_subcommands_for_update(cmd: Command) -> Command { + <T as Subcommand>::augment_subcommands_for_update(cmd) + } + fn has_subcommand(name: &str) -> bool { + <T as Subcommand>::has_subcommand(name) + } +} + +fn format_error<I: CommandFactory>(err: crate::Error) -> crate::Error { + let mut cmd = I::command(); + err.format(&mut cmd) +} diff --git a/vendor/clap_builder/src/error/context.rs b/vendor/clap_builder/src/error/context.rs new file mode 100644 index 0000000..045923c --- /dev/null +++ b/vendor/clap_builder/src/error/context.rs @@ -0,0 +1,114 @@ +/// Semantics for a piece of error information +#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)] +#[non_exhaustive] +#[cfg(feature = "error-context")] +pub enum ContextKind { + /// The cause of the error + InvalidSubcommand, + /// The cause of the error + InvalidArg, + /// Existing arguments + PriorArg, + /// Accepted subcommands + ValidSubcommand, + /// Accepted values + ValidValue, + /// Rejected values + InvalidValue, + /// Number of values present + ActualNumValues, + /// Number of allowed values + ExpectedNumValues, + /// Minimum number of allowed values + MinValues, + /// Potential fix for the user + SuggestedCommand, + /// Potential fix for the user + SuggestedSubcommand, + /// Potential fix for the user + SuggestedArg, + /// Potential fix for the user + SuggestedValue, + /// Trailing argument + TrailingArg, + /// Potential fix for the user + Suggested, + /// A usage string + Usage, + /// An opaque message to the user + Custom, +} + +impl ContextKind { + /// End-user description of the error case, where relevant + pub fn as_str(self) -> Option<&'static str> { + match self { + Self::InvalidSubcommand => Some("Invalid Subcommand"), + Self::InvalidArg => Some("Invalid Argument"), + Self::PriorArg => Some("Prior Argument"), + Self::ValidSubcommand => Some("Valid Subcommand"), + Self::ValidValue => Some("Valid Value"), + Self::InvalidValue => Some("Invalid Value"), + Self::ActualNumValues => Some("Actual Number of Values"), + Self::ExpectedNumValues => Some("Expected Number of Values"), + Self::MinValues => Some("Minimum Number of Values"), + Self::SuggestedCommand => Some("Suggested Command"), + Self::SuggestedSubcommand => Some("Suggested Subcommand"), + Self::SuggestedArg => Some("Suggested Argument"), + Self::SuggestedValue => Some("Suggested Value"), + Self::TrailingArg => Some("Trailing Argument"), + Self::Suggested => Some("Suggested"), + Self::Usage => None, + Self::Custom => None, + } + } +} + +impl std::fmt::Display for ContextKind { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + self.as_str().unwrap_or_default().fmt(f) + } +} + +/// A piece of error information +#[derive(Clone, Debug, PartialEq, Eq)] +#[non_exhaustive] +#[cfg(feature = "error-context")] +pub enum ContextValue { + /// [`ContextKind`] is self-sufficient, no additional information needed + None, + /// A single value + Bool(bool), + /// A single value + String(String), + /// Many values + Strings(Vec<String>), + /// A single value + StyledStr(crate::builder::StyledStr), + /// many value + StyledStrs(Vec<crate::builder::StyledStr>), + /// A single value + Number(isize), +} + +impl std::fmt::Display for ContextValue { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + match self { + Self::None => "".fmt(f), + Self::Bool(v) => v.fmt(f), + Self::String(v) => v.fmt(f), + Self::Strings(v) => v.join(", ").fmt(f), + Self::StyledStr(v) => v.fmt(f), + Self::StyledStrs(v) => { + for (i, v) in v.iter().enumerate() { + if i != 0 { + ", ".fmt(f)?; + } + v.fmt(f)?; + } + Ok(()) + } + Self::Number(v) => v.fmt(f), + } + } +} diff --git a/vendor/clap_builder/src/error/format.rs b/vendor/clap_builder/src/error/format.rs new file mode 100644 index 0000000..49e617d --- /dev/null +++ b/vendor/clap_builder/src/error/format.rs @@ -0,0 +1,545 @@ +#![allow(missing_copy_implementations)] +#![allow(missing_debug_implementations)] +#![cfg_attr(not(feature = "error-context"), allow(dead_code))] +#![cfg_attr(not(feature = "error-context"), allow(unused_imports))] + +use crate::builder::Command; +use crate::builder::StyledStr; +use crate::builder::Styles; +#[cfg(feature = "error-context")] +use crate::error::ContextKind; +#[cfg(feature = "error-context")] +use crate::error::ContextValue; +use crate::error::ErrorKind; +use crate::output::TAB; + +/// Defines how to format an error for displaying to the user +pub trait ErrorFormatter: Sized { + /// Stylize the error for the terminal + fn format_error(error: &crate::error::Error<Self>) -> StyledStr; +} + +/// Report [`ErrorKind`] +/// +/// No context is included. +/// +/// **NOTE:** Consider removing the `error-context` default feature if using this to remove all +/// overhead for [`RichFormatter`]. +#[non_exhaustive] +pub struct KindFormatter; + +impl ErrorFormatter for KindFormatter { + fn format_error(error: &crate::error::Error<Self>) -> StyledStr { + use std::fmt::Write as _; + let styles = &error.inner.styles; + + let mut styled = StyledStr::new(); + start_error(&mut styled, styles); + if let Some(msg) = error.kind().as_str() { + styled.push_str(msg); + } else if let Some(source) = error.inner.source.as_ref() { + let _ = write!(styled, "{source}"); + } else { + styled.push_str("unknown cause"); + } + styled.push_str("\n"); + styled + } +} + +/// Richly formatted error context +/// +/// This follows the [rustc diagnostic style guide](https://rustc-dev-guide.rust-lang.org/diagnostics.html#suggestion-style-guide). +#[non_exhaustive] +#[cfg(feature = "error-context")] +pub struct RichFormatter; + +#[cfg(feature = "error-context")] +impl ErrorFormatter for RichFormatter { + fn format_error(error: &crate::error::Error<Self>) -> StyledStr { + use std::fmt::Write as _; + let styles = &error.inner.styles; + let valid = &styles.get_valid(); + + let mut styled = StyledStr::new(); + start_error(&mut styled, styles); + + if !write_dynamic_context(error, &mut styled, styles) { + if let Some(msg) = error.kind().as_str() { + styled.push_str(msg); + } else if let Some(source) = error.inner.source.as_ref() { + let _ = write!(styled, "{source}"); + } else { + styled.push_str("unknown cause"); + } + } + + let mut suggested = false; + if let Some(valid) = error.get(ContextKind::SuggestedSubcommand) { + styled.push_str("\n"); + if !suggested { + styled.push_str("\n"); + suggested = true; + } + did_you_mean(&mut styled, styles, "subcommand", valid); + } + if let Some(valid) = error.get(ContextKind::SuggestedArg) { + styled.push_str("\n"); + if !suggested { + styled.push_str("\n"); + suggested = true; + } + did_you_mean(&mut styled, styles, "argument", valid); + } + if let Some(valid) = error.get(ContextKind::SuggestedValue) { + styled.push_str("\n"); + if !suggested { + styled.push_str("\n"); + suggested = true; + } + did_you_mean(&mut styled, styles, "value", valid); + } + let suggestions = error.get(ContextKind::Suggested); + if let Some(ContextValue::StyledStrs(suggestions)) = suggestions { + if !suggested { + styled.push_str("\n"); + } + for suggestion in suggestions { + let _ = write!( + styled, + "\n{TAB}{}tip:{} ", + valid.render(), + valid.render_reset() + ); + styled.push_styled(suggestion); + } + } + + let usage = error.get(ContextKind::Usage); + if let Some(ContextValue::StyledStr(usage)) = usage { + put_usage(&mut styled, usage); + } + + try_help(&mut styled, styles, error.inner.help_flag); + + styled + } +} + +fn start_error(styled: &mut StyledStr, styles: &Styles) { + use std::fmt::Write as _; + let error = &styles.get_error(); + let _ = write!(styled, "{}error:{} ", error.render(), error.render_reset()); +} + +#[must_use] +#[cfg(feature = "error-context")] +fn write_dynamic_context( + error: &crate::error::Error, + styled: &mut StyledStr, + styles: &Styles, +) -> bool { + use std::fmt::Write as _; + let valid = styles.get_valid(); + let invalid = styles.get_invalid(); + let literal = styles.get_literal(); + + match error.kind() { + ErrorKind::ArgumentConflict => { + let invalid_arg = error.get(ContextKind::InvalidArg); + let prior_arg = error.get(ContextKind::PriorArg); + if let (Some(ContextValue::String(invalid_arg)), Some(prior_arg)) = + (invalid_arg, prior_arg) + { + if ContextValue::String(invalid_arg.clone()) == *prior_arg { + let _ = write!( + styled, + "the argument '{}{invalid_arg}{}' cannot be used multiple times", + invalid.render(), + invalid.render_reset() + ); + } else { + let _ = write!( + styled, + "the argument '{}{invalid_arg}{}' cannot be used with", + invalid.render(), + invalid.render_reset() + ); + + match prior_arg { + ContextValue::Strings(values) => { + styled.push_str(":"); + for v in values { + let _ = write!( + styled, + "\n{TAB}{}{v}{}", + invalid.render(), + invalid.render_reset() + ); + } + } + ContextValue::String(value) => { + let _ = write!( + styled, + " '{}{value}{}'", + invalid.render(), + invalid.render_reset() + ); + } + _ => { + styled.push_str(" one or more of the other specified arguments"); + } + } + } + true + } else { + false + } + } + ErrorKind::NoEquals => { + let invalid_arg = error.get(ContextKind::InvalidArg); + if let Some(ContextValue::String(invalid_arg)) = invalid_arg { + let _ = write!( + styled, + "equal sign is needed when assigning values to '{}{invalid_arg}{}'", + invalid.render(), + invalid.render_reset() + ); + true + } else { + false + } + } + ErrorKind::InvalidValue => { + let invalid_arg = error.get(ContextKind::InvalidArg); + let invalid_value = error.get(ContextKind::InvalidValue); + if let ( + Some(ContextValue::String(invalid_arg)), + Some(ContextValue::String(invalid_value)), + ) = (invalid_arg, invalid_value) + { + if invalid_value.is_empty() { + let _ = write!( + styled, + "a value is required for '{}{invalid_arg}{}' but none was supplied", + invalid.render(), + invalid.render_reset() + ); + } else { + let _ = write!( + styled, + "invalid value '{}{invalid_value}{}' for '{}{invalid_arg}{}'", + invalid.render(), + invalid.render_reset(), + literal.render(), + literal.render_reset() + ); + } + + let values = error.get(ContextKind::ValidValue); + write_values_list("possible values", styled, valid, values); + + true + } else { + false + } + } + ErrorKind::InvalidSubcommand => { + let invalid_sub = error.get(ContextKind::InvalidSubcommand); + if let Some(ContextValue::String(invalid_sub)) = invalid_sub { + let _ = write!( + styled, + "unrecognized subcommand '{}{invalid_sub}{}'", + invalid.render(), + invalid.render_reset() + ); + true + } else { + false + } + } + ErrorKind::MissingRequiredArgument => { + let invalid_arg = error.get(ContextKind::InvalidArg); + if let Some(ContextValue::Strings(invalid_arg)) = invalid_arg { + styled.push_str("the following required arguments were not provided:"); + for v in invalid_arg { + let _ = write!( + styled, + "\n{TAB}{}{v}{}", + valid.render(), + valid.render_reset() + ); + } + true + } else { + false + } + } + ErrorKind::MissingSubcommand => { + let invalid_sub = error.get(ContextKind::InvalidSubcommand); + if let Some(ContextValue::String(invalid_sub)) = invalid_sub { + let _ = write!( + styled, + "'{}{invalid_sub}{}' requires a subcommand but one was not provided", + invalid.render(), + invalid.render_reset() + ); + let values = error.get(ContextKind::ValidSubcommand); + write_values_list("subcommands", styled, valid, values); + + true + } else { + false + } + } + ErrorKind::InvalidUtf8 => false, + ErrorKind::TooManyValues => { + let invalid_arg = error.get(ContextKind::InvalidArg); + let invalid_value = error.get(ContextKind::InvalidValue); + if let ( + Some(ContextValue::String(invalid_arg)), + Some(ContextValue::String(invalid_value)), + ) = (invalid_arg, invalid_value) + { + let _ = write!( + styled, + "unexpected value '{}{invalid_value}{}' for '{}{invalid_arg}{}' found; no more were expected", + invalid.render(), + invalid.render_reset(), + literal.render(), + literal.render_reset(), + ); + true + } else { + false + } + } + ErrorKind::TooFewValues => { + let invalid_arg = error.get(ContextKind::InvalidArg); + let actual_num_values = error.get(ContextKind::ActualNumValues); + let min_values = error.get(ContextKind::MinValues); + if let ( + Some(ContextValue::String(invalid_arg)), + Some(ContextValue::Number(actual_num_values)), + Some(ContextValue::Number(min_values)), + ) = (invalid_arg, actual_num_values, min_values) + { + let were_provided = singular_or_plural(*actual_num_values as usize); + let _ = write!( + styled, + "{}{min_values}{} more values required by '{}{invalid_arg}{}'; only {}{actual_num_values}{}{were_provided}", + valid.render(), + valid.render_reset(), + literal.render(), + literal.render_reset(), + invalid.render(), + invalid.render_reset(), + ); + true + } else { + false + } + } + ErrorKind::ValueValidation => { + let invalid_arg = error.get(ContextKind::InvalidArg); + let invalid_value = error.get(ContextKind::InvalidValue); + if let ( + Some(ContextValue::String(invalid_arg)), + Some(ContextValue::String(invalid_value)), + ) = (invalid_arg, invalid_value) + { + let _ = write!( + styled, + "invalid value '{}{invalid_value}{}' for '{}{invalid_arg}{}'", + invalid.render(), + invalid.render_reset(), + literal.render(), + literal.render_reset(), + ); + if let Some(source) = error.inner.source.as_deref() { + let _ = write!(styled, ": {source}"); + } + true + } else { + false + } + } + ErrorKind::WrongNumberOfValues => { + let invalid_arg = error.get(ContextKind::InvalidArg); + let actual_num_values = error.get(ContextKind::ActualNumValues); + let num_values = error.get(ContextKind::ExpectedNumValues); + if let ( + Some(ContextValue::String(invalid_arg)), + Some(ContextValue::Number(actual_num_values)), + Some(ContextValue::Number(num_values)), + ) = (invalid_arg, actual_num_values, num_values) + { + let were_provided = singular_or_plural(*actual_num_values as usize); + let _ = write!( + styled, + "{}{num_values}{} values required for '{}{invalid_arg}{}' but {}{actual_num_values}{}{were_provided}", + valid.render(), + valid.render_reset(), + literal.render(), + literal.render_reset(), + invalid.render(), + invalid.render_reset(), + ); + true + } else { + false + } + } + ErrorKind::UnknownArgument => { + let invalid_arg = error.get(ContextKind::InvalidArg); + if let Some(ContextValue::String(invalid_arg)) = invalid_arg { + let _ = write!( + styled, + "unexpected argument '{}{invalid_arg}{}' found", + invalid.render(), + invalid.render_reset(), + ); + true + } else { + false + } + } + ErrorKind::DisplayHelp + | ErrorKind::DisplayHelpOnMissingArgumentOrSubcommand + | ErrorKind::DisplayVersion + | ErrorKind::Io + | ErrorKind::Format => false, + } +} + +#[cfg(feature = "error-context")] +fn write_values_list( + list_name: &'static str, + styled: &mut StyledStr, + valid: &anstyle::Style, + possible_values: Option<&ContextValue>, +) { + use std::fmt::Write as _; + if let Some(ContextValue::Strings(possible_values)) = possible_values { + if !possible_values.is_empty() { + let _ = write!(styled, "\n{TAB}[{list_name}: "); + + let style = valid.render(); + let reset = valid.render_reset(); + for (idx, val) in possible_values.iter().enumerate() { + if idx > 0 { + styled.push_str(", "); + } + let _ = write!(styled, "{style}{}{reset}", Escape(val)); + } + + styled.push_str("]"); + } + } +} + +pub(crate) fn format_error_message( + message: &str, + styles: &Styles, + cmd: Option<&Command>, + usage: Option<&StyledStr>, +) -> StyledStr { + let mut styled = StyledStr::new(); + start_error(&mut styled, styles); + styled.push_str(message); + if let Some(usage) = usage { + put_usage(&mut styled, usage); + } + if let Some(cmd) = cmd { + try_help(&mut styled, styles, get_help_flag(cmd)); + } + styled +} + +/// Returns the singular or plural form on the verb to be based on the argument's value. +fn singular_or_plural(n: usize) -> &'static str { + if n > 1 { + " were provided" + } else { + " was provided" + } +} + +fn put_usage(styled: &mut StyledStr, usage: &StyledStr) { + styled.push_str("\n\n"); + styled.push_styled(usage); +} + +pub(crate) fn get_help_flag(cmd: &Command) -> Option<&'static str> { + if !cmd.is_disable_help_flag_set() { + Some("--help") + } else if cmd.has_subcommands() && !cmd.is_disable_help_subcommand_set() { + Some("help") + } else { + None + } +} + +fn try_help(styled: &mut StyledStr, styles: &Styles, help: Option<&str>) { + if let Some(help) = help { + use std::fmt::Write as _; + let literal = &styles.get_literal(); + let _ = write!( + styled, + "\n\nFor more information, try '{}{help}{}'.\n", + literal.render(), + literal.render_reset() + ); + } else { + styled.push_str("\n"); + } +} + +#[cfg(feature = "error-context")] +fn did_you_mean(styled: &mut StyledStr, styles: &Styles, context: &str, valid: &ContextValue) { + use std::fmt::Write as _; + + let _ = write!( + styled, + "{TAB}{}tip:{}", + styles.get_valid().render(), + styles.get_valid().render_reset() + ); + if let ContextValue::String(valid) = valid { + let _ = write!( + styled, + " a similar {context} exists: '{}{valid}{}'", + styles.get_valid().render(), + styles.get_valid().render_reset() + ); + } else if let ContextValue::Strings(valid) = valid { + if valid.len() == 1 { + let _ = write!(styled, " a similar {context} exists: ",); + } else { + let _ = write!(styled, " some similar {context}s exist: ",); + } + for (i, valid) in valid.iter().enumerate() { + if i != 0 { + styled.push_str(", "); + } + let _ = write!( + styled, + "'{}{valid}{}'", + styles.get_valid().render(), + styles.get_valid().render_reset() + ); + } + } +} + +struct Escape<'s>(&'s str); + +impl<'s> std::fmt::Display for Escape<'s> { + fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result { + if self.0.contains(char::is_whitespace) { + std::fmt::Debug::fmt(self.0, f) + } else { + self.0.fmt(f) + } + } +} diff --git a/vendor/clap_builder/src/error/kind.rs b/vendor/clap_builder/src/error/kind.rs new file mode 100644 index 0000000..a9d576c --- /dev/null +++ b/vendor/clap_builder/src/error/kind.rs @@ -0,0 +1,366 @@ +/// Command line argument parser kind of error +#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)] +#[non_exhaustive] +pub enum ErrorKind { + /// Occurs when an [`Arg`][crate::Arg] has a set of possible values, + /// and the user provides a value which isn't in that set. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, error::ErrorKind}; + /// let result = Command::new("prog") + /// .arg(Arg::new("speed") + /// .value_parser(["fast", "slow"])) + /// .try_get_matches_from(vec!["prog", "other"]); + /// assert!(result.is_err()); + /// assert_eq!(result.unwrap_err().kind(), ErrorKind::InvalidValue); + /// ``` + InvalidValue, + + /// Occurs when a user provides a flag, option, argument or subcommand which isn't defined. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, arg, error::ErrorKind}; + /// let result = Command::new("prog") + /// .arg(arg!(--flag "some flag")) + /// .try_get_matches_from(vec!["prog", "--other"]); + /// assert!(result.is_err()); + /// assert_eq!(result.unwrap_err().kind(), ErrorKind::UnknownArgument); + /// ``` + UnknownArgument, + + /// Occurs when the user provides an unrecognized [`Subcommand`] which meets the threshold for + /// being similar enough to an existing subcommand. + /// If it doesn't meet the threshold, or the 'suggestions' feature is disabled, + /// the more general [`UnknownArgument`] error is returned. + /// + /// # Examples + /// + /// ```rust + /// # #[cfg(feature = "suggestions")] { + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, error::ErrorKind, }; + /// let result = Command::new("prog") + /// .subcommand(Command::new("config") + /// .about("Used for configuration") + /// .arg(Arg::new("config_file") + /// .help("The configuration file to use"))) + /// .try_get_matches_from(vec!["prog", "confi"]); + /// assert!(result.is_err()); + /// assert_eq!(result.unwrap_err().kind(), ErrorKind::InvalidSubcommand); + /// # } + /// ``` + /// + /// [`Subcommand`]: crate::Subcommand + /// [`UnknownArgument`]: ErrorKind::UnknownArgument + InvalidSubcommand, + + /// Occurs when the user doesn't use equals for an option that requires equal + /// sign to provide values. + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, error::ErrorKind, ArgAction}; + /// let res = Command::new("prog") + /// .arg(Arg::new("color") + /// .action(ArgAction::Set) + /// .require_equals(true) + /// .long("color")) + /// .try_get_matches_from(vec!["prog", "--color", "red"]); + /// assert!(res.is_err()); + /// assert_eq!(res.unwrap_err().kind(), ErrorKind::NoEquals); + /// ``` + NoEquals, + + /// Occurs when the user provides a value for an argument with a custom validation and the + /// value fails that validation. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, error::ErrorKind, value_parser}; + /// fn is_numeric(val: &str) -> Result<(), String> { + /// match val.parse::<i64>() { + /// Ok(..) => Ok(()), + /// Err(..) => Err(String::from("value wasn't a number!")), + /// } + /// } + /// + /// let result = Command::new("prog") + /// .arg(Arg::new("num") + /// .value_parser(value_parser!(u8))) + /// .try_get_matches_from(vec!["prog", "NotANumber"]); + /// assert!(result.is_err()); + /// assert_eq!(result.unwrap_err().kind(), ErrorKind::ValueValidation); + /// ``` + ValueValidation, + + /// Occurs when a user provides more values for an argument than were defined by setting + /// [`Arg::num_args`]. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, error::ErrorKind}; + /// let result = Command::new("prog") + /// .arg(Arg::new("arg") + /// .num_args(1..=2)) + /// .try_get_matches_from(vec!["prog", "too", "many", "values"]); + /// assert!(result.is_err()); + /// assert_eq!(result.unwrap_err().kind(), ErrorKind::TooManyValues); + /// ``` + /// [`Arg::num_args`]: crate::Arg::num_args() + TooManyValues, + + /// Occurs when the user provides fewer values for an argument than were defined by setting + /// [`Arg::num_args`]. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, error::ErrorKind}; + /// let result = Command::new("prog") + /// .arg(Arg::new("some_opt") + /// .long("opt") + /// .num_args(3..)) + /// .try_get_matches_from(vec!["prog", "--opt", "too", "few"]); + /// assert!(result.is_err()); + /// assert_eq!(result.unwrap_err().kind(), ErrorKind::TooFewValues); + /// ``` + /// [`Arg::num_args`]: crate::Arg::num_args() + TooFewValues, + + /// Occurs when the user provides a different number of values for an argument than what's + /// been defined by setting [`Arg::num_args`] or than was implicitly set by + /// [`Arg::value_names`]. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, error::ErrorKind, ArgAction}; + /// let result = Command::new("prog") + /// .arg(Arg::new("some_opt") + /// .long("opt") + /// .action(ArgAction::Set) + /// .num_args(2)) + /// .try_get_matches_from(vec!["prog", "--opt", "wrong"]); + /// assert!(result.is_err()); + /// assert_eq!(result.unwrap_err().kind(), ErrorKind::WrongNumberOfValues); + /// ``` + /// + /// [`Arg::num_args`]: crate::Arg::num_args() + /// [`Arg::value_names`]: crate::Arg::value_names() + WrongNumberOfValues, + + /// Occurs when the user provides two values which conflict with each other and can't be used + /// together. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, error::ErrorKind, ArgAction}; + /// let result = Command::new("prog") + /// .arg(Arg::new("debug") + /// .long("debug") + /// .action(ArgAction::SetTrue) + /// .conflicts_with("color")) + /// .arg(Arg::new("color") + /// .long("color") + /// .action(ArgAction::SetTrue)) + /// .try_get_matches_from(vec!["prog", "--debug", "--color"]); + /// assert!(result.is_err()); + /// assert_eq!(result.unwrap_err().kind(), ErrorKind::ArgumentConflict); + /// ``` + ArgumentConflict, + + /// Occurs when the user does not provide one or more required arguments. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, error::ErrorKind}; + /// let result = Command::new("prog") + /// .arg(Arg::new("debug") + /// .required(true)) + /// .try_get_matches_from(vec!["prog"]); + /// assert!(result.is_err()); + /// assert_eq!(result.unwrap_err().kind(), ErrorKind::MissingRequiredArgument); + /// ``` + MissingRequiredArgument, + + /// Occurs when a subcommand is required (as defined by [`Command::subcommand_required`]), + /// but the user does not provide one. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, error::ErrorKind}; + /// let err = Command::new("prog") + /// .subcommand_required(true) + /// .subcommand(Command::new("test")) + /// .try_get_matches_from(vec![ + /// "myprog", + /// ]); + /// assert!(err.is_err()); + /// assert_eq!(err.unwrap_err().kind(), ErrorKind::MissingSubcommand); + /// # ; + /// ``` + /// + /// [`Command::subcommand_required`]: crate::Command::subcommand_required + MissingSubcommand, + + /// Occurs when the user provides a value containing invalid UTF-8. + /// + /// To allow arbitrary data + /// - Set [`Arg::value_parser(value_parser!(OsString))`] for argument values + /// - Set [`Command::external_subcommand_value_parser`] for external-subcommand + /// values + /// + /// # Platform Specific + /// + /// Non-Windows platforms only (such as Linux, Unix, OSX, etc.) + /// + /// # Examples + /// + /// ```rust + /// # #[cfg(unix)] { + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, error::ErrorKind, ArgAction}; + /// # use std::os::unix::ffi::OsStringExt; + /// # use std::ffi::OsString; + /// let result = Command::new("prog") + /// .arg(Arg::new("utf8") + /// .short('u') + /// .action(ArgAction::Set)) + /// .try_get_matches_from(vec![OsString::from("myprog"), + /// OsString::from("-u"), + /// OsString::from_vec(vec![0xE9])]); + /// assert!(result.is_err()); + /// assert_eq!(result.unwrap_err().kind(), ErrorKind::InvalidUtf8); + /// # } + /// ``` + /// + /// [`Arg::allow_invalid_utf8`]: crate::Arg::allow_invalid_utf8 + /// [`Command::external_subcommand_value_parser`]: crate::Command::external_subcommand_value_parser + InvalidUtf8, + + /// Not a true "error" as it means `--help` or similar was used. + /// The help message will be sent to `stdout`. + /// + /// **Note**: If the help is displayed due to an error (such as missing subcommands) it will + /// be sent to `stderr` instead of `stdout`. + /// + /// # Examples + /// + /// ```rust + /// # #[cfg(feature = "help")] { + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, error::ErrorKind}; + /// let result = Command::new("prog") + /// .try_get_matches_from(vec!["prog", "--help"]); + /// assert!(result.is_err()); + /// assert_eq!(result.unwrap_err().kind(), ErrorKind::DisplayHelp); + /// # } + /// ``` + DisplayHelp, + + /// Occurs when either an argument or a [`Subcommand`] is required, as defined by + /// [`Command::arg_required_else_help`] , but the user did not provide + /// one. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, error::ErrorKind, }; + /// let result = Command::new("prog") + /// .arg_required_else_help(true) + /// .subcommand(Command::new("config") + /// .about("Used for configuration") + /// .arg(Arg::new("config_file") + /// .help("The configuration file to use"))) + /// .try_get_matches_from(vec!["prog"]); + /// assert!(result.is_err()); + /// assert_eq!(result.unwrap_err().kind(), ErrorKind::DisplayHelpOnMissingArgumentOrSubcommand); + /// ``` + /// + /// [`Subcommand`]: crate::Subcommand + /// [`Command::arg_required_else_help`]: crate::Command::arg_required_else_help + DisplayHelpOnMissingArgumentOrSubcommand, + + /// Not a true "error" as it means `--version` or similar was used. + /// The message will be sent to `stdout`. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, error::ErrorKind}; + /// let result = Command::new("prog") + /// .version("3.0") + /// .try_get_matches_from(vec!["prog", "--version"]); + /// assert!(result.is_err()); + /// assert_eq!(result.unwrap_err().kind(), ErrorKind::DisplayVersion); + /// ``` + DisplayVersion, + + /// Represents an [I/O error]. + /// Can occur when writing to `stderr` or `stdout` or reading a configuration file. + /// + /// [I/O error]: std::io::Error + Io, + + /// Represents a [Format error] (which is a part of [`Display`]). + /// Typically caused by writing to `stderr` or `stdout`. + /// + /// [`Display`]: std::fmt::Display + /// [Format error]: std::fmt::Error + Format, +} + +impl ErrorKind { + /// End-user description of the error case, where relevant + pub fn as_str(self) -> Option<&'static str> { + match self { + Self::InvalidValue => Some("one of the values isn't valid for an argument"), + Self::UnknownArgument => Some("unexpected argument found"), + Self::InvalidSubcommand => Some("unrecognized subcommand"), + Self::NoEquals => Some("equal is needed when assigning values to one of the arguments"), + Self::ValueValidation => Some("invalid value for one of the arguments"), + Self::TooManyValues => Some("unexpected value for an argument found"), + Self::TooFewValues => Some("more values required for an argument"), + Self::WrongNumberOfValues => Some("too many or too few values for an argument"), + Self::ArgumentConflict => { + Some("an argument cannot be used with one or more of the other specified arguments") + } + Self::MissingRequiredArgument => { + Some("one or more required arguments were not provided") + } + Self::MissingSubcommand => Some("a subcommand is required but one was not provided"), + Self::InvalidUtf8 => Some("invalid UTF-8 was detected in one or more arguments"), + Self::DisplayHelp => None, + Self::DisplayHelpOnMissingArgumentOrSubcommand => None, + Self::DisplayVersion => None, + Self::Io => None, + Self::Format => None, + } + } +} + +impl std::fmt::Display for ErrorKind { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + self.as_str().unwrap_or_default().fmt(f) + } +} diff --git a/vendor/clap_builder/src/error/mod.rs b/vendor/clap_builder/src/error/mod.rs new file mode 100644 index 0000000..af90e27 --- /dev/null +++ b/vendor/clap_builder/src/error/mod.rs @@ -0,0 +1,923 @@ +//! Error reporting + +#![cfg_attr(not(feature = "error-context"), allow(dead_code))] +#![cfg_attr(not(feature = "error-context"), allow(unused_imports))] +#![cfg_attr(not(feature = "error-context"), allow(unused_variables))] +#![cfg_attr(not(feature = "error-context"), allow(unused_mut))] +#![cfg_attr(not(feature = "error-context"), allow(clippy::let_and_return))] + +// Std +use std::{ + borrow::Cow, + convert::From, + error, + fmt::{self, Debug, Display, Formatter}, + io::{self}, + result::Result as StdResult, +}; + +// Internal +use crate::builder::StyledStr; +use crate::builder::Styles; +use crate::output::fmt::Colorizer; +use crate::output::fmt::Stream; +use crate::parser::features::suggestions; +use crate::util::FlatMap; +use crate::util::{color::ColorChoice, safe_exit, SUCCESS_CODE, USAGE_CODE}; +use crate::Command; + +#[cfg(feature = "error-context")] +mod context; +mod format; +mod kind; + +pub use format::ErrorFormatter; +pub use format::KindFormatter; +pub use kind::ErrorKind; + +#[cfg(feature = "error-context")] +pub use context::ContextKind; +#[cfg(feature = "error-context")] +pub use context::ContextValue; +#[cfg(feature = "error-context")] +pub use format::RichFormatter; + +#[cfg(not(feature = "error-context"))] +pub use KindFormatter as DefaultFormatter; +#[cfg(feature = "error-context")] +pub use RichFormatter as DefaultFormatter; + +/// Short hand for [`Result`] type +/// +/// [`Result`]: std::result::Result +pub type Result<T, E = Error> = StdResult<T, E>; + +/// Command Line Argument Parser Error +/// +/// See [`Command::error`] to create an error. +/// +/// [`Command::error`]: crate::Command::error +pub struct Error<F: ErrorFormatter = DefaultFormatter> { + inner: Box<ErrorInner>, + phantom: std::marker::PhantomData<F>, +} + +#[derive(Debug)] +struct ErrorInner { + kind: ErrorKind, + #[cfg(feature = "error-context")] + context: FlatMap<ContextKind, ContextValue>, + message: Option<Message>, + source: Option<Box<dyn error::Error + Send + Sync>>, + help_flag: Option<&'static str>, + styles: Styles, + color_when: ColorChoice, + color_help_when: ColorChoice, + backtrace: Option<Backtrace>, +} + +impl<F: ErrorFormatter> Error<F> { + /// Create an unformatted error + /// + /// This is for you need to pass the error up to + /// a place that has access to the `Command` at which point you can call [`Error::format`]. + /// + /// Prefer [`Command::error`] for generating errors. + /// + /// [`Command::error`]: crate::Command::error + pub fn raw(kind: ErrorKind, message: impl std::fmt::Display) -> Self { + Self::new(kind).set_message(message.to_string()) + } + + /// Format the existing message with the Command's context + #[must_use] + pub fn format(mut self, cmd: &mut Command) -> Self { + cmd._build_self(false); + let usage = cmd.render_usage_(); + if let Some(message) = self.inner.message.as_mut() { + message.format(cmd, usage); + } + self.with_cmd(cmd) + } + + /// Create an error with a pre-defined message + /// + /// See also + /// - [`Error::insert`] + /// - [`Error::with_cmd`] + /// + /// # Example + /// + /// ```rust + /// # #[cfg(feature = "error-context")] { + /// # use clap_builder as clap; + /// # use clap::error::ErrorKind; + /// # use clap::error::ContextKind; + /// # use clap::error::ContextValue; + /// + /// let cmd = clap::Command::new("prog"); + /// + /// let mut err = clap::Error::new(ErrorKind::ValueValidation) + /// .with_cmd(&cmd); + /// err.insert(ContextKind::InvalidArg, ContextValue::String("--foo".to_owned())); + /// err.insert(ContextKind::InvalidValue, ContextValue::String("bar".to_owned())); + /// + /// err.print(); + /// # } + /// ``` + pub fn new(kind: ErrorKind) -> Self { + Self { + inner: Box::new(ErrorInner { + kind, + #[cfg(feature = "error-context")] + context: FlatMap::new(), + message: None, + source: None, + help_flag: None, + styles: Styles::plain(), + color_when: ColorChoice::Never, + color_help_when: ColorChoice::Never, + backtrace: Backtrace::new(), + }), + phantom: Default::default(), + } + } + + /// Apply [`Command`]'s formatting to the error + /// + /// Generally, this is used with [`Error::new`] + pub fn with_cmd(self, cmd: &Command) -> Self { + self.set_styles(cmd.get_styles().clone()) + .set_color(cmd.get_color()) + .set_colored_help(cmd.color_help()) + .set_help_flag(format::get_help_flag(cmd)) + } + + /// Apply an alternative formatter to the error + /// + /// # Example + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::Command; + /// # use clap::Arg; + /// # use clap::error::KindFormatter; + /// let cmd = Command::new("foo") + /// .arg(Arg::new("input").required(true)); + /// let matches = cmd + /// .try_get_matches_from(["foo", "input.txt"]) + /// .map_err(|e| e.apply::<KindFormatter>()) + /// .unwrap_or_else(|e| e.exit()); + /// ``` + pub fn apply<EF: ErrorFormatter>(self) -> Error<EF> { + Error { + inner: self.inner, + phantom: Default::default(), + } + } + + /// Type of error for programmatic processing + pub fn kind(&self) -> ErrorKind { + self.inner.kind + } + + /// Additional information to further qualify the error + #[cfg(feature = "error-context")] + pub fn context(&self) -> impl Iterator<Item = (ContextKind, &ContextValue)> { + self.inner.context.iter().map(|(k, v)| (*k, v)) + } + + /// Lookup a piece of context + #[inline(never)] + #[cfg(feature = "error-context")] + pub fn get(&self, kind: ContextKind) -> Option<&ContextValue> { + self.inner.context.get(&kind) + } + + /// Insert a piece of context + #[inline(never)] + #[cfg(feature = "error-context")] + pub fn insert(&mut self, kind: ContextKind, value: ContextValue) -> Option<ContextValue> { + self.inner.context.insert(kind, value) + } + + /// Should the message be written to `stdout` or not? + #[inline] + pub fn use_stderr(&self) -> bool { + self.stream() == Stream::Stderr + } + + pub(crate) fn stream(&self) -> Stream { + match self.kind() { + ErrorKind::DisplayHelp | ErrorKind::DisplayVersion => Stream::Stdout, + _ => Stream::Stderr, + } + } + + /// Returns the exit code that `.exit` will exit the process with. + /// + /// When the error's kind would print to `stderr` this returns `2`, + /// else it returns `0`. + pub fn exit_code(&self) -> i32 { + if self.use_stderr() { + USAGE_CODE + } else { + SUCCESS_CODE + } + } + + /// Prints the error and exits. + /// + /// Depending on the error kind, this either prints to `stderr` and exits with a status of `2` + /// or prints to `stdout` and exits with a status of `0`. + pub fn exit(&self) -> ! { + // Swallow broken pipe errors + let _ = self.print(); + safe_exit(self.exit_code()) + } + + /// Prints formatted and colored error to `stdout` or `stderr` according to its error kind + /// + /// # Example + /// ```no_run + /// # use clap_builder as clap; + /// use clap::Command; + /// + /// match Command::new("Command").try_get_matches() { + /// Ok(matches) => { + /// // do_something + /// }, + /// Err(err) => { + /// err.print().expect("Error writing Error"); + /// // do_something + /// }, + /// }; + /// ``` + pub fn print(&self) -> io::Result<()> { + let style = self.formatted(); + let color_when = if matches!( + self.kind(), + ErrorKind::DisplayHelp | ErrorKind::DisplayHelpOnMissingArgumentOrSubcommand, + ) { + self.inner.color_help_when + } else { + self.inner.color_when + }; + let c = Colorizer::new(self.stream(), color_when).with_content(style.into_owned()); + c.print() + } + + /// Render the error message to a [`StyledStr`]. + /// + /// # Example + /// ```no_run + /// # use clap_builder as clap; + /// use clap::Command; + /// + /// match Command::new("Command").try_get_matches() { + /// Ok(matches) => { + /// // do_something + /// }, + /// Err(err) => { + /// let err = err.render(); + /// println!("{err}"); + /// // do_something + /// }, + /// }; + /// ``` + pub fn render(&self) -> StyledStr { + self.formatted().into_owned() + } + + #[inline(never)] + fn for_app(kind: ErrorKind, cmd: &Command, styled: StyledStr) -> Self { + Self::new(kind).set_message(styled).with_cmd(cmd) + } + + pub(crate) fn set_message(mut self, message: impl Into<Message>) -> Self { + self.inner.message = Some(message.into()); + self + } + + pub(crate) fn set_source(mut self, source: Box<dyn error::Error + Send + Sync>) -> Self { + self.inner.source = Some(source); + self + } + + pub(crate) fn set_styles(mut self, styles: Styles) -> Self { + self.inner.styles = styles; + self + } + + pub(crate) fn set_color(mut self, color_when: ColorChoice) -> Self { + self.inner.color_when = color_when; + self + } + + pub(crate) fn set_colored_help(mut self, color_help_when: ColorChoice) -> Self { + self.inner.color_help_when = color_help_when; + self + } + + pub(crate) fn set_help_flag(mut self, help_flag: Option<&'static str>) -> Self { + self.inner.help_flag = help_flag; + self + } + + /// Does not verify if `ContextKind` is already present + #[inline(never)] + #[cfg(feature = "error-context")] + pub(crate) fn insert_context_unchecked( + mut self, + kind: ContextKind, + value: ContextValue, + ) -> Self { + self.inner.context.insert_unchecked(kind, value); + self + } + + /// Does not verify if `ContextKind` is already present + #[inline(never)] + #[cfg(feature = "error-context")] + pub(crate) fn extend_context_unchecked<const N: usize>( + mut self, + context: [(ContextKind, ContextValue); N], + ) -> Self { + self.inner.context.extend_unchecked(context); + self + } + + pub(crate) fn display_help(cmd: &Command, styled: StyledStr) -> Self { + Self::for_app(ErrorKind::DisplayHelp, cmd, styled) + } + + pub(crate) fn display_help_error(cmd: &Command, styled: StyledStr) -> Self { + Self::for_app( + ErrorKind::DisplayHelpOnMissingArgumentOrSubcommand, + cmd, + styled, + ) + } + + pub(crate) fn display_version(cmd: &Command, styled: StyledStr) -> Self { + Self::for_app(ErrorKind::DisplayVersion, cmd, styled) + } + + pub(crate) fn argument_conflict( + cmd: &Command, + arg: String, + mut others: Vec<String>, + usage: Option<StyledStr>, + ) -> Self { + let mut err = Self::new(ErrorKind::ArgumentConflict).with_cmd(cmd); + + #[cfg(feature = "error-context")] + { + let others = match others.len() { + 0 => ContextValue::None, + 1 => ContextValue::String(others.pop().unwrap()), + _ => ContextValue::Strings(others), + }; + err = err.extend_context_unchecked([ + (ContextKind::InvalidArg, ContextValue::String(arg)), + (ContextKind::PriorArg, others), + ]); + if let Some(usage) = usage { + err = err + .insert_context_unchecked(ContextKind::Usage, ContextValue::StyledStr(usage)); + } + } + + err + } + + pub(crate) fn empty_value(cmd: &Command, good_vals: &[String], arg: String) -> Self { + Self::invalid_value(cmd, "".to_owned(), good_vals, arg) + } + + pub(crate) fn no_equals(cmd: &Command, arg: String, usage: Option<StyledStr>) -> Self { + let mut err = Self::new(ErrorKind::NoEquals).with_cmd(cmd); + + #[cfg(feature = "error-context")] + { + err = err + .extend_context_unchecked([(ContextKind::InvalidArg, ContextValue::String(arg))]); + if let Some(usage) = usage { + err = err + .insert_context_unchecked(ContextKind::Usage, ContextValue::StyledStr(usage)); + } + } + + err + } + + pub(crate) fn invalid_value( + cmd: &Command, + bad_val: String, + good_vals: &[String], + arg: String, + ) -> Self { + let suggestion = suggestions::did_you_mean(&bad_val, good_vals.iter()).pop(); + let mut err = Self::new(ErrorKind::InvalidValue).with_cmd(cmd); + + #[cfg(feature = "error-context")] + { + err = err.extend_context_unchecked([ + (ContextKind::InvalidArg, ContextValue::String(arg)), + (ContextKind::InvalidValue, ContextValue::String(bad_val)), + ( + ContextKind::ValidValue, + ContextValue::Strings(good_vals.iter().map(|s| (*s).to_owned()).collect()), + ), + ]); + if let Some(suggestion) = suggestion { + err = err.insert_context_unchecked( + ContextKind::SuggestedValue, + ContextValue::String(suggestion), + ); + } + } + + err + } + + pub(crate) fn invalid_subcommand( + cmd: &Command, + subcmd: String, + did_you_mean: Vec<String>, + name: String, + suggested_trailing_arg: bool, + usage: Option<StyledStr>, + ) -> Self { + use std::fmt::Write as _; + let styles = cmd.get_styles(); + let invalid = &styles.get_invalid(); + let valid = &styles.get_valid(); + let mut err = Self::new(ErrorKind::InvalidSubcommand).with_cmd(cmd); + + #[cfg(feature = "error-context")] + { + let mut suggestions = vec![]; + if suggested_trailing_arg { + let mut styled_suggestion = StyledStr::new(); + let _ = write!( + styled_suggestion, + "to pass '{}{subcmd}{}' as a value, use '{}{name} -- {subcmd}{}'", + invalid.render(), + invalid.render_reset(), + valid.render(), + valid.render_reset() + ); + suggestions.push(styled_suggestion); + } + + err = err.extend_context_unchecked([ + (ContextKind::InvalidSubcommand, ContextValue::String(subcmd)), + ( + ContextKind::SuggestedSubcommand, + ContextValue::Strings(did_you_mean), + ), + ( + ContextKind::Suggested, + ContextValue::StyledStrs(suggestions), + ), + ]); + if let Some(usage) = usage { + err = err + .insert_context_unchecked(ContextKind::Usage, ContextValue::StyledStr(usage)); + } + } + + err + } + + pub(crate) fn unrecognized_subcommand( + cmd: &Command, + subcmd: String, + usage: Option<StyledStr>, + ) -> Self { + let mut err = Self::new(ErrorKind::InvalidSubcommand).with_cmd(cmd); + + #[cfg(feature = "error-context")] + { + err = err.extend_context_unchecked([( + ContextKind::InvalidSubcommand, + ContextValue::String(subcmd), + )]); + if let Some(usage) = usage { + err = err + .insert_context_unchecked(ContextKind::Usage, ContextValue::StyledStr(usage)); + } + } + + err + } + + pub(crate) fn missing_required_argument( + cmd: &Command, + required: Vec<String>, + usage: Option<StyledStr>, + ) -> Self { + let mut err = Self::new(ErrorKind::MissingRequiredArgument).with_cmd(cmd); + + #[cfg(feature = "error-context")] + { + err = err.extend_context_unchecked([( + ContextKind::InvalidArg, + ContextValue::Strings(required), + )]); + if let Some(usage) = usage { + err = err + .insert_context_unchecked(ContextKind::Usage, ContextValue::StyledStr(usage)); + } + } + + err + } + + pub(crate) fn missing_subcommand( + cmd: &Command, + parent: String, + available: Vec<String>, + usage: Option<StyledStr>, + ) -> Self { + let mut err = Self::new(ErrorKind::MissingSubcommand).with_cmd(cmd); + + #[cfg(feature = "error-context")] + { + err = err.extend_context_unchecked([ + (ContextKind::InvalidSubcommand, ContextValue::String(parent)), + ( + ContextKind::ValidSubcommand, + ContextValue::Strings(available), + ), + ]); + if let Some(usage) = usage { + err = err + .insert_context_unchecked(ContextKind::Usage, ContextValue::StyledStr(usage)); + } + } + + err + } + + pub(crate) fn invalid_utf8(cmd: &Command, usage: Option<StyledStr>) -> Self { + let mut err = Self::new(ErrorKind::InvalidUtf8).with_cmd(cmd); + + #[cfg(feature = "error-context")] + { + if let Some(usage) = usage { + err = err + .insert_context_unchecked(ContextKind::Usage, ContextValue::StyledStr(usage)); + } + } + + err + } + + pub(crate) fn too_many_values( + cmd: &Command, + val: String, + arg: String, + usage: Option<StyledStr>, + ) -> Self { + let mut err = Self::new(ErrorKind::TooManyValues).with_cmd(cmd); + + #[cfg(feature = "error-context")] + { + err = err.extend_context_unchecked([ + (ContextKind::InvalidArg, ContextValue::String(arg)), + (ContextKind::InvalidValue, ContextValue::String(val)), + ]); + if let Some(usage) = usage { + err = err + .insert_context_unchecked(ContextKind::Usage, ContextValue::StyledStr(usage)); + } + } + + err + } + + pub(crate) fn too_few_values( + cmd: &Command, + arg: String, + min_vals: usize, + curr_vals: usize, + usage: Option<StyledStr>, + ) -> Self { + let mut err = Self::new(ErrorKind::TooFewValues).with_cmd(cmd); + + #[cfg(feature = "error-context")] + { + err = err.extend_context_unchecked([ + (ContextKind::InvalidArg, ContextValue::String(arg)), + ( + ContextKind::MinValues, + ContextValue::Number(min_vals as isize), + ), + ( + ContextKind::ActualNumValues, + ContextValue::Number(curr_vals as isize), + ), + ]); + if let Some(usage) = usage { + err = err + .insert_context_unchecked(ContextKind::Usage, ContextValue::StyledStr(usage)); + } + } + + err + } + + pub(crate) fn value_validation( + arg: String, + val: String, + err: Box<dyn error::Error + Send + Sync>, + ) -> Self { + let mut err = Self::new(ErrorKind::ValueValidation).set_source(err); + + #[cfg(feature = "error-context")] + { + err = err.extend_context_unchecked([ + (ContextKind::InvalidArg, ContextValue::String(arg)), + (ContextKind::InvalidValue, ContextValue::String(val)), + ]); + } + + err + } + + pub(crate) fn wrong_number_of_values( + cmd: &Command, + arg: String, + num_vals: usize, + curr_vals: usize, + usage: Option<StyledStr>, + ) -> Self { + let mut err = Self::new(ErrorKind::WrongNumberOfValues).with_cmd(cmd); + + #[cfg(feature = "error-context")] + { + err = err.extend_context_unchecked([ + (ContextKind::InvalidArg, ContextValue::String(arg)), + ( + ContextKind::ExpectedNumValues, + ContextValue::Number(num_vals as isize), + ), + ( + ContextKind::ActualNumValues, + ContextValue::Number(curr_vals as isize), + ), + ]); + if let Some(usage) = usage { + err = err + .insert_context_unchecked(ContextKind::Usage, ContextValue::StyledStr(usage)); + } + } + + err + } + + pub(crate) fn unknown_argument( + cmd: &Command, + arg: String, + did_you_mean: Option<(String, Option<String>)>, + suggested_trailing_arg: bool, + usage: Option<StyledStr>, + ) -> Self { + use std::fmt::Write as _; + let styles = cmd.get_styles(); + let invalid = &styles.get_invalid(); + let valid = &styles.get_valid(); + let mut err = Self::new(ErrorKind::UnknownArgument).with_cmd(cmd); + + #[cfg(feature = "error-context")] + { + let mut suggestions = vec![]; + if suggested_trailing_arg { + let mut styled_suggestion = StyledStr::new(); + let _ = write!( + styled_suggestion, + "to pass '{}{arg}{}' as a value, use '{}-- {arg}{}'", + invalid.render(), + invalid.render_reset(), + valid.render(), + valid.render_reset() + ); + suggestions.push(styled_suggestion); + } + + err = err + .extend_context_unchecked([(ContextKind::InvalidArg, ContextValue::String(arg))]); + if let Some(usage) = usage { + err = err + .insert_context_unchecked(ContextKind::Usage, ContextValue::StyledStr(usage)); + } + match did_you_mean { + Some((flag, Some(sub))) => { + let mut styled_suggestion = StyledStr::new(); + let _ = write!( + styled_suggestion, + "'{}{sub} {flag}{}' exists", + valid.render(), + valid.render_reset() + ); + suggestions.push(styled_suggestion); + } + Some((flag, None)) => { + err = err.insert_context_unchecked( + ContextKind::SuggestedArg, + ContextValue::String(flag), + ); + } + None => {} + } + if !suggestions.is_empty() { + err = err.insert_context_unchecked( + ContextKind::Suggested, + ContextValue::StyledStrs(suggestions), + ); + } + } + + err + } + + pub(crate) fn unnecessary_double_dash( + cmd: &Command, + arg: String, + usage: Option<StyledStr>, + ) -> Self { + use std::fmt::Write as _; + let styles = cmd.get_styles(); + let invalid = &styles.get_invalid(); + let valid = &styles.get_valid(); + let mut err = Self::new(ErrorKind::UnknownArgument).with_cmd(cmd); + + #[cfg(feature = "error-context")] + { + let mut styled_suggestion = StyledStr::new(); + let _ = write!( + styled_suggestion, + "subcommand '{}{arg}{}' exists; to use it, remove the '{}--{}' before it", + valid.render(), + valid.render_reset(), + invalid.render(), + invalid.render_reset() + ); + + err = err.extend_context_unchecked([ + (ContextKind::InvalidArg, ContextValue::String(arg)), + ( + ContextKind::Suggested, + ContextValue::StyledStrs(vec![styled_suggestion]), + ), + ]); + if let Some(usage) = usage { + err = err + .insert_context_unchecked(ContextKind::Usage, ContextValue::StyledStr(usage)); + } + } + + err + } + + fn formatted(&self) -> Cow<'_, StyledStr> { + if let Some(message) = self.inner.message.as_ref() { + message.formatted(&self.inner.styles) + } else { + let styled = F::format_error(self); + Cow::Owned(styled) + } + } +} + +impl<F: ErrorFormatter> From<io::Error> for Error<F> { + fn from(e: io::Error) -> Self { + Error::raw(ErrorKind::Io, e) + } +} + +impl<F: ErrorFormatter> From<fmt::Error> for Error<F> { + fn from(e: fmt::Error) -> Self { + Error::raw(ErrorKind::Format, e) + } +} + +impl<F: ErrorFormatter> std::fmt::Debug for Error<F> { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> Result<(), std::fmt::Error> { + self.inner.fmt(f) + } +} + +impl<F: ErrorFormatter> error::Error for Error<F> { + #[allow(trivial_casts)] + fn source(&self) -> Option<&(dyn error::Error + 'static)> { + self.inner.source.as_ref().map(|e| e.as_ref() as _) + } +} + +impl<F: ErrorFormatter> Display for Error<F> { + fn fmt(&self, f: &mut Formatter) -> fmt::Result { + // Assuming `self.message` already has a trailing newline, from `try_help` or similar + ok!(write!(f, "{}", self.formatted())); + if let Some(backtrace) = self.inner.backtrace.as_ref() { + ok!(writeln!(f)); + ok!(writeln!(f, "Backtrace:")); + ok!(writeln!(f, "{backtrace}")); + } + Ok(()) + } +} + +#[derive(Clone, Debug)] +pub(crate) enum Message { + Raw(String), + Formatted(StyledStr), +} + +impl Message { + fn format(&mut self, cmd: &Command, usage: Option<StyledStr>) { + match self { + Message::Raw(s) => { + let mut message = String::new(); + std::mem::swap(s, &mut message); + + let styled = format::format_error_message( + &message, + cmd.get_styles(), + Some(cmd), + usage.as_ref(), + ); + + *self = Self::Formatted(styled); + } + Message::Formatted(_) => {} + } + } + + fn formatted(&self, styles: &Styles) -> Cow<StyledStr> { + match self { + Message::Raw(s) => { + let styled = format::format_error_message(s, styles, None, None); + + Cow::Owned(styled) + } + Message::Formatted(s) => Cow::Borrowed(s), + } + } +} + +impl From<String> for Message { + fn from(inner: String) -> Self { + Self::Raw(inner) + } +} + +impl From<StyledStr> for Message { + fn from(inner: StyledStr) -> Self { + Self::Formatted(inner) + } +} + +#[cfg(feature = "debug")] +#[derive(Debug)] +struct Backtrace(backtrace::Backtrace); + +#[cfg(feature = "debug")] +impl Backtrace { + fn new() -> Option<Self> { + Some(Self(backtrace::Backtrace::new())) + } +} + +#[cfg(feature = "debug")] +impl Display for Backtrace { + fn fmt(&self, f: &mut Formatter) -> fmt::Result { + // `backtrace::Backtrace` uses `Debug` instead of `Display` + write!(f, "{:?}", self.0) + } +} + +#[cfg(not(feature = "debug"))] +#[derive(Debug)] +struct Backtrace; + +#[cfg(not(feature = "debug"))] +impl Backtrace { + fn new() -> Option<Self> { + None + } +} + +#[cfg(not(feature = "debug"))] +impl Display for Backtrace { + fn fmt(&self, _: &mut Formatter) -> fmt::Result { + Ok(()) + } +} + +#[test] +fn check_auto_traits() { + static_assertions::assert_impl_all!(Error: Send, Sync, Unpin); +} diff --git a/vendor/clap_builder/src/lib.rs b/vendor/clap_builder/src/lib.rs new file mode 100644 index 0000000..7d49d41 --- /dev/null +++ b/vendor/clap_builder/src/lib.rs @@ -0,0 +1,66 @@ +// Copyright ⓒ 2015-2016 Kevin B. Knapp and [`clap-rs` contributors](https://github.com/clap-rs/clap/graphs/contributors). +// Licensed under the MIT license +// (see LICENSE or <http://opensource.org/licenses/MIT>) All files in the project carrying such +// notice may not be copied, modified, or distributed except according to those terms. + +#![cfg_attr(docsrs, feature(doc_auto_cfg))] +#![doc = include_str!("../README.md")] +#![doc(html_logo_url = "https://raw.githubusercontent.com/clap-rs/clap/master/assets/clap.png")] +#![warn( + missing_docs, + missing_debug_implementations, + missing_copy_implementations, + trivial_casts, + unused_allocation, + trivial_numeric_casts, + clippy::single_char_pattern +)] +#![forbid(unsafe_code)] +// Wanting consistency in our calls +#![allow(clippy::write_with_newline)] +// Gets in the way of logging +#![allow(clippy::let_and_return)] +// HACK https://github.com/rust-lang/rust-clippy/issues/7290 +#![allow(clippy::single_component_path_imports)] +#![allow(clippy::branches_sharing_code)] +// Doesn't allow for debug statements, etc to be unique +#![allow(clippy::if_same_then_else)] +// Breaks up parallelism that clarifies intent +#![allow(clippy::collapsible_else_if)] + +#[cfg(not(feature = "std"))] +compile_error!("`std` feature is currently required to build `clap`"); + +pub use crate::builder::ArgAction; +pub use crate::builder::Command; +pub use crate::builder::ValueHint; +pub use crate::builder::{Arg, ArgGroup}; +pub use crate::parser::ArgMatches; +pub use crate::util::color::ColorChoice; +pub use crate::util::Id; + +/// Command Line Argument Parser Error +/// +/// See [`Command::error`] to create an error. +/// +/// [`Command::error`]: crate::Command::error +pub type Error = crate::error::Error<crate::error::DefaultFormatter>; + +pub use crate::derive::{Args, CommandFactory, FromArgMatches, Parser, Subcommand, ValueEnum}; + +#[macro_use] +#[allow(missing_docs)] +mod macros; + +mod derive; + +pub mod builder; +pub mod error; +pub mod parser; + +mod mkeymap; +mod output; +mod util; + +const INTERNAL_ERROR_MSG: &str = "Fatal internal error. Please consider filing a bug \ + report at https://github.com/clap-rs/clap/issues"; diff --git a/vendor/clap_builder/src/macros.rs b/vendor/clap_builder/src/macros.rs new file mode 100644 index 0000000..767ea94 --- /dev/null +++ b/vendor/clap_builder/src/macros.rs @@ -0,0 +1,574 @@ +/// Allows you to pull the version from your Cargo.toml at compile time as +/// `MAJOR.MINOR.PATCH_PKGVERSION_PRE` +/// +/// # Examples +/// +/// ```no_run +/// # use clap_builder as clap; +/// # use clap::crate_version; +/// # use clap::Command; +/// let m = Command::new("cmd") +/// .version(crate_version!()) +/// .get_matches(); +/// ``` +#[cfg(feature = "cargo")] +#[macro_export] +macro_rules! crate_version { + () => { + env!("CARGO_PKG_VERSION") + }; +} + +/// Allows you to pull the authors for the command from your Cargo.toml at +/// compile time in the form: +/// `"author1 lastname <author1@example.com>:author2 lastname <author2@example.com>"` +/// +/// You can replace the colons with a custom separator by supplying a +/// replacement string, so, for example, +/// `crate_authors!(",\n")` would become +/// `"author1 lastname <author1@example.com>,\nauthor2 lastname <author2@example.com>,\nauthor3 lastname <author3@example.com>"` +/// +/// # Examples +/// +/// ```no_run +/// # use clap_builder as clap; +/// # use clap::crate_authors; +/// # use clap::Command; +/// let m = Command::new("cmd") +/// .author(crate_authors!("\n")) +/// .get_matches(); +/// ``` +#[cfg(feature = "cargo")] +#[macro_export] +macro_rules! crate_authors { + ($sep:expr) => {{ + static authors: &str = env!("CARGO_PKG_AUTHORS"); + if authors.contains(':') { + static CACHED: std::sync::OnceLock<String> = std::sync::OnceLock::new(); + let s = CACHED.get_or_init(|| authors.replace(':', $sep)); + let s: &'static str = &*s; + s + } else { + authors + } + }}; + () => { + env!("CARGO_PKG_AUTHORS") + }; +} + +/// Allows you to pull the description from your Cargo.toml at compile time. +/// +/// # Examples +/// +/// ```no_run +/// # use clap_builder as clap; +/// # use clap::crate_description; +/// # use clap::Command; +/// let m = Command::new("cmd") +/// .about(crate_description!()) +/// .get_matches(); +/// ``` +#[cfg(feature = "cargo")] +#[macro_export] +macro_rules! crate_description { + () => { + env!("CARGO_PKG_DESCRIPTION") + }; +} + +/// Allows you to pull the name from your Cargo.toml at compile time. +/// +/// **NOTE:** This macro extracts the name from an environment variable `CARGO_PKG_NAME`. +/// When the crate name is set to something different from the package name, +/// use environment variables `CARGO_CRATE_NAME` or `CARGO_BIN_NAME`. +/// See [the Cargo Book](https://doc.rust-lang.org/cargo/reference/environment-variables.html) +/// for more information. +/// +/// # Examples +/// +/// ```no_run +/// # use clap_builder as clap; +/// # use clap::crate_name; +/// # use clap::Command; +/// let m = Command::new(crate_name!()) +/// .get_matches(); +/// ``` +#[cfg(feature = "cargo")] +#[macro_export] +macro_rules! crate_name { + () => { + env!("CARGO_PKG_NAME") + }; +} + +/// Allows you to build the `Command` instance from your Cargo.toml at compile time. +/// +/// **NOTE:** Changing the values in your `Cargo.toml` does not trigger a re-build automatically, +/// and therefore won't change the generated output until you recompile. +/// +/// In some cases you can "trick" the compiler into triggering a rebuild when your +/// `Cargo.toml` is changed by including this in your `src/main.rs` file +/// `include_str!("../Cargo.toml");` +/// +/// # Examples +/// +/// ```no_run +/// # use clap_builder as clap; +/// # use clap::command; +/// let m = command!().get_matches(); +/// ``` +#[cfg(feature = "cargo")] +#[macro_export] +macro_rules! command { + () => {{ + $crate::command!($crate::crate_name!()) + }}; + ($name:expr) => {{ + let mut cmd = $crate::Command::new($name).version($crate::crate_version!()); + + let author = $crate::crate_authors!(); + if !author.is_empty() { + cmd = cmd.author(author) + } + + let about = $crate::crate_description!(); + if !about.is_empty() { + cmd = cmd.about(about) + } + + cmd + }}; +} + +/// Requires `cargo` feature flag to be enabled. +#[cfg(not(feature = "cargo"))] +#[macro_export] +macro_rules! command { + () => {{ + compile_error!("`cargo` feature flag is required"); + }}; + ($name:expr) => {{ + compile_error!("`cargo` feature flag is required"); + }}; +} + +#[doc(hidden)] +#[macro_export] +macro_rules! arg_impl { + ( @string $val:ident ) => { + stringify!($val) + }; + ( @string $val:literal ) => {{ + let ident_or_string_literal: &str = $val; + ident_or_string_literal + }}; + ( @string $val:tt ) => { + ::std::compile_error!("Only identifiers or string literals supported"); + }; + ( @string ) => { + None + }; + + ( @char $val:ident ) => {{ + let ident_or_char_literal = stringify!($val); + debug_assert_eq!( + ident_or_char_literal.len(), + 1, + "Single-letter identifier expected, got {ident_or_char_literal}", + ); + ident_or_char_literal.chars().next().unwrap() + }}; + ( @char $val:literal ) => {{ + let ident_or_char_literal: char = $val; + ident_or_char_literal + }}; + ( @char ) => {{ + None + }}; + + ( + @arg + ($arg:expr) + --$long:ident + $($tail:tt)* + ) => {{ + debug_assert_eq!($arg.get_value_names(), None, "Flags should precede values"); + debug_assert!(!matches!($arg.get_action(), $crate::ArgAction::Append), "Flags should precede `...`"); + + let mut arg = $arg; + let long = $crate::arg_impl! { @string $long }; + if arg.get_id() == "" { + arg = arg.id(long); + } + let action = $crate::ArgAction::SetTrue; + let arg = arg + .long(long) + .action(action); + let arg = $crate::arg_impl! { + @arg (arg) $($tail)* + }; + arg + }}; + ( + @arg + ($arg:expr) + --$long:literal + $($tail:tt)* + ) => {{ + debug_assert_eq!($arg.get_value_names(), None, "Flags should precede values"); + debug_assert!(!matches!($arg.get_action(), $crate::ArgAction::Append), "Flags should precede `...`"); + + let mut arg = $arg; + let long = $crate::arg_impl! { @string $long }; + if arg.get_id() == "" { + arg = arg.id(long); + } + let action = $crate::ArgAction::SetTrue; + let arg = arg + .long(long) + .action(action); + let arg = $crate::arg_impl! { + @arg (arg) $($tail)* + }; + arg + }}; + ( + @arg + ($arg:expr) + -$short:ident + $($tail:tt)* + ) => {{ + debug_assert_eq!($arg.get_long(), None, "Short flags should precede long flags"); + debug_assert_eq!($arg.get_value_names(), None, "Flags should precede values"); + debug_assert!(!matches!($arg.get_action(), $crate::ArgAction::Append), "Flags should precede `...`"); + + let action = $crate::ArgAction::SetTrue; + let arg = $arg + .short($crate::arg_impl! { @char $short }) + .action(action); + let arg = $crate::arg_impl! { + @arg (arg) $($tail)* + }; + arg + }}; + ( + @arg + ($arg:expr) + -$short:literal + $($tail:tt)* + ) => {{ + debug_assert_eq!($arg.get_long(), None, "Short flags should precede long flags"); + debug_assert_eq!($arg.get_value_names(), None, "Flags should precede values"); + debug_assert!(!matches!($arg.get_action(), $crate::ArgAction::Append), "Flags should precede `...`"); + + let action = $crate::ArgAction::SetTrue; + let arg = $arg + .short($crate::arg_impl! { @char $short }) + .action(action); + let arg = $crate::arg_impl! { + @arg (arg) $($tail)* + }; + arg + }}; + ( + @arg + ($arg:expr) + <$value_name:ident> + $($tail:tt)* + ) => {{ + debug_assert!(!matches!($arg.get_action(), $crate::ArgAction::Append), "Flags should precede `...`"); + debug_assert_eq!($arg.get_value_names(), None, "Multiple values not yet supported"); + + let mut arg = $arg; + + if arg.get_long().is_none() && arg.get_short().is_none() { + arg = arg.required(true); + } + + let value_name = $crate::arg_impl! { @string $value_name }; + if arg.get_id() == "" { + arg = arg.id(value_name); + } + let arg = arg + .value_name(value_name) + .action($crate::ArgAction::Set); + let arg = $crate::arg_impl! { + @arg (arg) $($tail)* + }; + arg + }}; + ( + @arg + ($arg:expr) + <$value_name:literal> + $($tail:tt)* + ) => {{ + debug_assert!(!matches!($arg.get_action(), $crate::ArgAction::Append), "Flags should precede `...`"); + debug_assert_eq!($arg.get_value_names(), None, "Multiple values not yet supported"); + + let mut arg = $arg; + + if arg.get_long().is_none() && arg.get_short().is_none() { + arg = arg.required(true); + } + + let value_name = $crate::arg_impl! { @string $value_name }; + if arg.get_id() == "" { + arg = arg.id(value_name); + } + let arg = arg + .value_name(value_name) + .action($crate::ArgAction::Set); + let arg = $crate::arg_impl! { + @arg (arg) $($tail)* + }; + arg + }}; + ( + @arg + ($arg:expr) + [$value_name:ident] + $($tail:tt)* + ) => {{ + debug_assert!(!matches!($arg.get_action(), $crate::ArgAction::Append), "Flags should precede `...`"); + debug_assert_eq!($arg.get_value_names(), None, "Multiple values not yet supported"); + + let mut arg = $arg; + + if arg.get_long().is_none() && arg.get_short().is_none() { + arg = arg.required(false); + } else { + arg = arg.num_args(0..=1); + } + + let value_name = $crate::arg_impl! { @string $value_name }; + if arg.get_id() == "" { + arg = arg.id(value_name); + } + let arg = arg + .value_name(value_name) + .action($crate::ArgAction::Set); + let arg = $crate::arg_impl! { + @arg (arg) $($tail)* + }; + arg + }}; + ( + @arg + ($arg:expr) + [$value_name:literal] + $($tail:tt)* + ) => {{ + debug_assert!(!matches!($arg.get_action(), $crate::ArgAction::Append), "Flags should precede `...`"); + debug_assert_eq!($arg.get_value_names(), None, "Multiple values not yet supported"); + + let mut arg = $arg; + + if arg.get_long().is_none() && arg.get_short().is_none() { + arg = arg.required(false); + } else { + arg = arg.num_args(0..=1); + } + + let value_name = $crate::arg_impl! { @string $value_name }; + if arg.get_id() == "" { + arg = arg.id(value_name); + } + let arg = arg + .value_name(value_name) + .action($crate::ArgAction::Set); + let arg = $crate::arg_impl! { + @arg (arg) $($tail)* + }; + arg + }}; + ( + @arg + ($arg:expr) + ... + $($tail:tt)* + ) => {{ + let arg = match $arg.get_action() { + $crate::ArgAction::Set => { + if $arg.get_long().is_none() && $arg.get_short().is_none() { + $arg.num_args(1..) + // Allow collecting arguments interleaved with flags + .action($crate::ArgAction::Append) + } else { + $arg.action($crate::ArgAction::Append) + } + }, + $crate::ArgAction::SetTrue | $crate::ArgAction::Help | $crate::ArgAction::Version => { + $arg.action($crate::ArgAction::Count) + } + action => { + panic!("Unexpected action {action:?}") + } + }; + let arg = $crate::arg_impl! { + @arg (arg) $($tail)* + }; + arg + }}; + ( + @arg + ($arg:expr) + $help:literal + ) => {{ + $arg.help($help) + }}; + ( + @arg + ($arg:expr) + ) => {{ + $arg + }}; +} + +/// Create an [`Arg`] from a usage string. +/// +/// Allows creation of basic settings for the [`Arg`]. +/// +/// **NOTE**: Not all settings may be set using the usage string method. Some properties are +/// only available via the builder pattern. +/// +/// # Syntax +/// +/// Usage strings typically following the form: +/// +/// ```notrust +/// [explicit name] [short] [long] [value names] [...] [help string] +/// ``` +/// +/// ### Explicit Name +/// +/// The name may be either a bare-word or a string, followed by a `:`, like `name:` or +/// `"name":`. +/// +/// *Note:* This is an optional field, if it's omitted the argument will use one of the additional +/// fields as the name using the following priority order: +/// +/// 1. Explicit Name +/// 2. Long +/// 3. Value Name +/// +/// See [`Arg::id`][crate::Arg::id]. +/// +/// ### Short +/// +/// A short flag is a `-` followed by either a bare-character or quoted character, like `-f` or +/// `-'f'`. +/// +/// See [`Arg::short`][crate::Arg::short]. +/// +/// ### Long +/// +/// A long flag is a `--` followed by either a bare-word or a string, like `--foo` or +/// `--"foo"`. +/// +/// **NOTE:** Dashes in the long name (e.g. `--foo-bar`) is not supported and quoting is required +/// (e.g. `--"foo-bar"`). +/// +/// See [`Arg::long`][crate::Arg::long]. +/// +/// ### Values (Value Notation) +/// +/// This is set by placing bare-word between: +/// - `[]` like `[FOO]` +/// - Positional argument: optional +/// - Named argument: optional value +/// - `<>` like `<FOO>`: required +/// +/// See [`Arg::value_name`][crate::Arg::value_name]. +/// +/// ### `...` +/// +/// `...` (three consecutive dots/periods) specifies that this argument may occur multiple +/// times (not to be confused with multiple values per occurrence). +/// +/// See [`ArgAction::Count`][crate::ArgAction::Count] and [`ArgAction::Append`][crate::ArgAction::Append]. +/// +/// ### Help String +/// +/// The help string is denoted between a pair of double quotes `""` and may contain any +/// characters. +/// +/// # Examples +/// +/// ```rust +/// # use clap_builder as clap; +/// # use clap::{Command, Arg, arg}; +/// let cmd = Command::new("prog") +/// .args(&[ +/// arg!(--config <FILE> "a required file for the configuration and no short"), +/// arg!(-d --debug ... "turns on debugging information and allows multiples"), +/// arg!([input] "an optional input file to use") +/// ]); +/// +/// let m = cmd.try_get_matches_from(["prog", "--config", "file.toml"]).unwrap(); +/// assert_eq!(m.get_one::<String>("config").unwrap(), "file.toml"); +/// assert_eq!(*m.get_one::<u8>("debug").unwrap(), 0); +/// assert_eq!(m.get_one::<String>("input"), None); +/// ``` +/// [`Arg`]: crate::Arg +#[macro_export] +macro_rules! arg { + ( $name:ident: $($tail:tt)+ ) => {{ + let arg = $crate::Arg::new($crate::arg_impl! { @string $name }); + let arg = $crate::arg_impl! { + @arg (arg) $($tail)+ + }; + arg + }}; + ( $($tail:tt)+ ) => {{ + let arg = $crate::Arg::default(); + let arg = $crate::arg_impl! { + @arg (arg) $($tail)+ + }; + debug_assert_ne!(arg.get_id(), "", "Without a value or long flag, the `name:` prefix is required"); + arg + }}; +} + +#[cfg(feature = "debug")] +macro_rules! debug { + ($($arg:tt)*) => ({ + use std::fmt::Write as _; + let hint = anstyle::Style::new().dimmed(); + + let module_path = module_path!(); + let body = format!($($arg)*); + let mut styled = $crate::builder::StyledStr::new(); + let _ = write!(styled, "{}[{module_path:>28}]{body}{}\n", hint.render(), hint.render_reset()); + let color = $crate::output::fmt::Colorizer::new($crate::output::fmt::Stream::Stderr, $crate::ColorChoice::Auto).with_content(styled); + let _ = color.print(); + }) +} + +#[cfg(not(feature = "debug"))] +macro_rules! debug { + ($($arg:tt)*) => {}; +} + +macro_rules! ok { + ($expr:expr) => { + match $expr { + Ok(val) => val, + Err(err) => { + return Err(err); + } + } + }; +} + +macro_rules! some { + ($expr:expr) => { + match $expr { + Some(val) => val, + None => { + return None; + } + } + }; +} diff --git a/vendor/clap_builder/src/mkeymap.rs b/vendor/clap_builder/src/mkeymap.rs new file mode 100644 index 0000000..301c7bc --- /dev/null +++ b/vendor/clap_builder/src/mkeymap.rs @@ -0,0 +1,188 @@ +use std::iter::Iterator; +use std::ops::Index; + +use crate::builder::OsStr; +use crate::Arg; +use crate::INTERNAL_ERROR_MSG; + +#[derive(PartialEq, Eq, Debug, Clone)] +pub(crate) struct Key { + key: KeyType, + index: usize, +} + +#[derive(Default, PartialEq, Eq, Debug, Clone)] +pub(crate) struct MKeyMap { + /// All of the arguments. + args: Vec<Arg>, + + // Cache part: + /// Will be set after `_build()`. + keys: Vec<Key>, +} + +#[derive(Debug, PartialEq, Eq, Hash, Clone)] +pub(crate) enum KeyType { + Short(char), + Long(OsStr), + Position(usize), +} + +impl KeyType { + pub(crate) fn is_position(&self) -> bool { + matches!(self, KeyType::Position(_)) + } +} + +impl PartialEq<usize> for KeyType { + fn eq(&self, rhs: &usize) -> bool { + match self { + KeyType::Position(x) => x == rhs, + _ => false, + } + } +} + +impl PartialEq<&str> for KeyType { + fn eq(&self, rhs: &&str) -> bool { + match self { + KeyType::Long(l) => l == rhs, + _ => false, + } + } +} + +impl PartialEq<str> for KeyType { + fn eq(&self, rhs: &str) -> bool { + match self { + KeyType::Long(l) => l == rhs, + _ => false, + } + } +} + +impl PartialEq<OsStr> for KeyType { + fn eq(&self, rhs: &OsStr) -> bool { + match self { + KeyType::Long(l) => l == rhs, + _ => false, + } + } +} + +impl PartialEq<char> for KeyType { + fn eq(&self, rhs: &char) -> bool { + match self { + KeyType::Short(c) => c == rhs, + _ => false, + } + } +} + +impl MKeyMap { + /// If any arg has corresponding key in this map, we can search the key with + /// u64(for positional argument), char(for short flag), &str and OsString + /// (for long flag) + pub(crate) fn contains<K>(&self, key: K) -> bool + where + KeyType: PartialEq<K>, + { + self.keys.iter().any(|x| x.key == key) + } + + /// Push an argument in the map. + pub(crate) fn push(&mut self, new_arg: Arg) { + self.args.push(new_arg); + } + + /// Find the arg have corresponding key in this map, we can search the key + /// with u64(for positional argument), char(for short flag), &str and + /// OsString (for long flag) + pub(crate) fn get<K: ?Sized>(&self, key: &K) -> Option<&Arg> + where + KeyType: PartialEq<K>, + { + self.keys + .iter() + .find(|k| &k.key == key) + .map(|k| &self.args[k.index]) + } + + /// Return iterators of all keys. + pub(crate) fn keys(&self) -> impl Iterator<Item = &KeyType> { + self.keys.iter().map(|x| &x.key) + } + + /// Return iterators of all args. + pub(crate) fn args(&self) -> impl Iterator<Item = &Arg> { + self.args.iter() + } + + /// Return mutable iterators of all args. + pub(crate) fn args_mut(&mut self) -> impl Iterator<Item = &mut Arg> { + self.args.iter_mut() + } + + /// Mutate every argument. + pub(crate) fn mut_args<F>(&mut self, f: F) + where + F: FnMut(Arg) -> Arg, + { + let mut args = std::mem::take(&mut self.args); + self.args.extend(args.drain(..).map(f)); + } + + /// We need a lazy build here since some we may change args after creating + /// the map, you can checkout who uses `args_mut`. + pub(crate) fn _build(&mut self) { + // There will be at least as many keys as args, so that is a good starting point + self.keys.reserve(self.args.len()); + for (i, arg) in self.args.iter().enumerate() { + append_keys(&mut self.keys, arg, i); + } + } + + /// Remove an arg in the graph by Id, usually used by `mut_arg`. Return + /// `Some(arg)` if removed. + pub(crate) fn remove_by_name(&mut self, name: &str) -> Option<Arg> { + self.args + .iter() + .position(|arg| arg.id == name) + // since it's a cold function, using this wouldn't hurt much + .map(|i| self.args.remove(i)) + } +} + +impl Index<&'_ KeyType> for MKeyMap { + type Output = Arg; + + fn index(&self, key: &KeyType) -> &Self::Output { + self.get(key).expect(INTERNAL_ERROR_MSG) + } +} + +/// Generate key types for an specific Arg. +fn append_keys(keys: &mut Vec<Key>, arg: &Arg, index: usize) { + if let Some(pos_index) = arg.index { + let key = KeyType::Position(pos_index); + keys.push(Key { key, index }); + } else { + if let Some(short) = arg.short { + let key = KeyType::Short(short); + keys.push(Key { key, index }); + } + if let Some(long) = arg.long.clone() { + let key = KeyType::Long(long.into()); + keys.push(Key { key, index }); + } + + for (short, _) in arg.short_aliases.iter() { + let key = KeyType::Short(*short); + keys.push(Key { key, index }); + } + for (long, _) in arg.aliases.iter() { + let key = KeyType::Long(long.into()); + keys.push(Key { key, index }); + } + } +} diff --git a/vendor/clap_builder/src/output/fmt.rs b/vendor/clap_builder/src/output/fmt.rs new file mode 100644 index 0000000..0c9a24f --- /dev/null +++ b/vendor/clap_builder/src/output/fmt.rs @@ -0,0 +1,83 @@ +use crate::builder::StyledStr; +use crate::util::color::ColorChoice; + +#[derive(Copy, Clone, Debug, PartialEq, Eq)] +pub(crate) enum Stream { + Stdout, + Stderr, +} + +#[derive(Clone, Debug)] +pub(crate) struct Colorizer { + stream: Stream, + #[allow(unused)] + color_when: ColorChoice, + content: StyledStr, +} + +impl Colorizer { + pub(crate) fn new(stream: Stream, color_when: ColorChoice) -> Self { + Colorizer { + stream, + color_when, + content: Default::default(), + } + } + + pub(crate) fn with_content(mut self, content: StyledStr) -> Self { + self.content = content; + self + } +} + +/// Printing methods. +impl Colorizer { + #[cfg(feature = "color")] + pub(crate) fn print(&self) -> std::io::Result<()> { + let color_when = match self.color_when { + ColorChoice::Always => anstream::ColorChoice::Always, + ColorChoice::Auto => anstream::ColorChoice::Auto, + ColorChoice::Never => anstream::ColorChoice::Never, + }; + + let mut stdout; + let mut stderr; + let writer: &mut dyn std::io::Write = match self.stream { + Stream::Stderr => { + stderr = anstream::AutoStream::new(std::io::stderr().lock(), color_when); + &mut stderr + } + Stream::Stdout => { + stdout = anstream::AutoStream::new(std::io::stdout().lock(), color_when); + &mut stdout + } + }; + + self.content.write_to(writer) + } + + #[cfg(not(feature = "color"))] + pub(crate) fn print(&self) -> std::io::Result<()> { + // [e]println can't be used here because it panics + // if something went wrong. We don't want that. + match self.stream { + Stream::Stdout => { + let stdout = std::io::stdout(); + let mut stdout = stdout.lock(); + self.content.write_to(&mut stdout) + } + Stream::Stderr => { + let stderr = std::io::stderr(); + let mut stderr = stderr.lock(); + self.content.write_to(&mut stderr) + } + } + } +} + +/// Color-unaware printing. Never uses coloring. +impl std::fmt::Display for Colorizer { + fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result { + self.content.fmt(f) + } +} diff --git a/vendor/clap_builder/src/output/help.rs b/vendor/clap_builder/src/output/help.rs new file mode 100644 index 0000000..a5073a9 --- /dev/null +++ b/vendor/clap_builder/src/output/help.rs @@ -0,0 +1,39 @@ +#![cfg_attr(not(feature = "help"), allow(unused_variables))] + +// Internal +use crate::builder::Command; +use crate::builder::StyledStr; +use crate::output::Usage; + +/// Writes the parser help to the wrapped stream. +pub(crate) fn write_help(writer: &mut StyledStr, cmd: &Command, usage: &Usage<'_>, use_long: bool) { + debug!("write_help"); + + if let Some(h) = cmd.get_override_help() { + writer.push_styled(h); + } else { + #[cfg(feature = "help")] + { + use super::AutoHelp; + use super::HelpTemplate; + if let Some(tmpl) = cmd.get_help_template() { + HelpTemplate::new(writer, cmd, usage, use_long) + .write_templated_help(tmpl.as_styled_str()); + } else { + AutoHelp::new(writer, cmd, usage, use_long).write_help(); + } + } + + #[cfg(not(feature = "help"))] + { + debug!("write_help: no help, `Command::override_help` and `help` is missing"); + } + } + + // Remove any lines from unused sections + writer.trim_start_lines(); + // Remove any whitespace caused by book keeping + writer.trim_end(); + // Ensure there is still a trailing newline + writer.push_str("\n"); +} diff --git a/vendor/clap_builder/src/output/help_template.rs b/vendor/clap_builder/src/output/help_template.rs new file mode 100644 index 0000000..dff15ff --- /dev/null +++ b/vendor/clap_builder/src/output/help_template.rs @@ -0,0 +1,1198 @@ +// HACK: for rust 1.64 (1.68 doesn't need this since this is in lib.rs) +// +// Wanting consistency in our calls +#![allow(clippy::write_with_newline)] + +// Std +use std::borrow::Cow; +use std::cmp; +use std::usize; + +// Internal +use crate::builder::PossibleValue; +use crate::builder::Str; +use crate::builder::StyledStr; +use crate::builder::Styles; +use crate::builder::{Arg, Command}; +use crate::output::display_width; +use crate::output::wrap; +use crate::output::Usage; +use crate::output::TAB; +use crate::output::TAB_WIDTH; +use crate::util::FlatSet; + +/// `clap` auto-generated help writer +pub(crate) struct AutoHelp<'cmd, 'writer> { + template: HelpTemplate<'cmd, 'writer>, +} + +// Public Functions +impl<'cmd, 'writer> AutoHelp<'cmd, 'writer> { + /// Create a new `HelpTemplate` instance. + pub(crate) fn new( + writer: &'writer mut StyledStr, + cmd: &'cmd Command, + usage: &'cmd Usage<'cmd>, + use_long: bool, + ) -> Self { + Self { + template: HelpTemplate::new(writer, cmd, usage, use_long), + } + } + + pub(crate) fn write_help(&mut self) { + let pos = self + .template + .cmd + .get_positionals() + .any(|arg| should_show_arg(self.template.use_long, arg)); + let non_pos = self + .template + .cmd + .get_non_positionals() + .any(|arg| should_show_arg(self.template.use_long, arg)); + let subcmds = self.template.cmd.has_visible_subcommands(); + + let template = if non_pos || pos || subcmds { + DEFAULT_TEMPLATE + } else { + DEFAULT_NO_ARGS_TEMPLATE + }; + self.template.write_templated_help(template); + } +} + +const DEFAULT_TEMPLATE: &str = "\ +{before-help}{about-with-newline} +{usage-heading} {usage} + +{all-args}{after-help}\ + "; + +const DEFAULT_NO_ARGS_TEMPLATE: &str = "\ +{before-help}{about-with-newline} +{usage-heading} {usage}{after-help}\ + "; + +/// `clap` HelpTemplate Writer. +/// +/// Wraps a writer stream providing different methods to generate help for `clap` objects. +pub(crate) struct HelpTemplate<'cmd, 'writer> { + writer: &'writer mut StyledStr, + cmd: &'cmd Command, + styles: &'cmd Styles, + usage: &'cmd Usage<'cmd>, + next_line_help: bool, + term_w: usize, + use_long: bool, +} + +// Public Functions +impl<'cmd, 'writer> HelpTemplate<'cmd, 'writer> { + /// Create a new `HelpTemplate` instance. + pub(crate) fn new( + writer: &'writer mut StyledStr, + cmd: &'cmd Command, + usage: &'cmd Usage<'cmd>, + use_long: bool, + ) -> Self { + debug!( + "HelpTemplate::new cmd={}, use_long={}", + cmd.get_name(), + use_long + ); + let term_w = Self::term_w(cmd); + let next_line_help = cmd.is_next_line_help_set(); + + HelpTemplate { + writer, + cmd, + styles: cmd.get_styles(), + usage, + next_line_help, + term_w, + use_long, + } + } + + #[cfg(not(feature = "unstable-v5"))] + fn term_w(cmd: &'cmd Command) -> usize { + match cmd.get_term_width() { + Some(0) => usize::MAX, + Some(w) => w, + None => { + let (current_width, _h) = dimensions(); + let current_width = current_width.unwrap_or(100); + let max_width = match cmd.get_max_term_width() { + None | Some(0) => usize::MAX, + Some(mw) => mw, + }; + cmp::min(current_width, max_width) + } + } + } + + #[cfg(feature = "unstable-v5")] + fn term_w(cmd: &'cmd Command) -> usize { + let term_w = match cmd.get_term_width() { + Some(0) => usize::MAX, + Some(w) => w, + None => { + let (current_width, _h) = dimensions(); + current_width.unwrap_or(usize::MAX) + } + }; + + let max_term_w = match cmd.get_max_term_width() { + Some(0) => usize::MAX, + Some(mw) => mw, + None => 100, + }; + + cmp::min(term_w, max_term_w) + } + + /// Write help to stream for the parser in the format defined by the template. + /// + /// For details about the template language see [`Command::help_template`]. + /// + /// [`Command::help_template`]: Command::help_template() + pub(crate) fn write_templated_help(&mut self, template: &str) { + debug!("HelpTemplate::write_templated_help"); + use std::fmt::Write as _; + + let mut parts = template.split('{'); + if let Some(first) = parts.next() { + self.writer.push_str(first); + } + for part in parts { + if let Some((tag, rest)) = part.split_once('}') { + match tag { + "name" => { + self.write_display_name(); + } + #[cfg(not(feature = "unstable-v5"))] + "bin" => { + self.write_bin_name(); + } + "version" => { + self.write_version(); + } + "author" => { + self.write_author(false, false); + } + "author-with-newline" => { + self.write_author(false, true); + } + "author-section" => { + self.write_author(true, true); + } + "about" => { + self.write_about(false, false); + } + "about-with-newline" => { + self.write_about(false, true); + } + "about-section" => { + self.write_about(true, true); + } + "usage-heading" => { + let _ = write!( + self.writer, + "{}Usage:{}", + self.styles.get_usage().render(), + self.styles.get_usage().render_reset() + ); + } + "usage" => { + self.writer.push_styled( + &self.usage.create_usage_no_title(&[]).unwrap_or_default(), + ); + } + "all-args" => { + self.write_all_args(); + } + "options" => { + // Include even those with a heading as we don't have a good way of + // handling help_heading in the template. + self.write_args( + &self.cmd.get_non_positionals().collect::<Vec<_>>(), + "options", + option_sort_key, + ); + } + "positionals" => { + self.write_args( + &self.cmd.get_positionals().collect::<Vec<_>>(), + "positionals", + positional_sort_key, + ); + } + "subcommands" => { + self.write_subcommands(self.cmd); + } + "tab" => { + self.writer.push_str(TAB); + } + "after-help" => { + self.write_after_help(); + } + "before-help" => { + self.write_before_help(); + } + _ => { + let _ = write!(self.writer, "{{{tag}}}"); + } + } + self.writer.push_str(rest); + } + } + } +} + +/// Basic template methods +impl<'cmd, 'writer> HelpTemplate<'cmd, 'writer> { + /// Writes binary name of a Parser Object to the wrapped stream. + fn write_display_name(&mut self) { + debug!("HelpTemplate::write_display_name"); + + let display_name = wrap( + &self + .cmd + .get_display_name() + .unwrap_or_else(|| self.cmd.get_name()) + .replace("{n}", "\n"), + self.term_w, + ); + self.writer.push_string(display_name); + } + + /// Writes binary name of a Parser Object to the wrapped stream. + #[cfg(not(feature = "unstable-v5"))] + fn write_bin_name(&mut self) { + debug!("HelpTemplate::write_bin_name"); + + let bin_name = if let Some(bn) = self.cmd.get_bin_name() { + if bn.contains(' ') { + // In case we're dealing with subcommands i.e. git mv is translated to git-mv + bn.replace(' ', "-") + } else { + wrap(&self.cmd.get_name().replace("{n}", "\n"), self.term_w) + } + } else { + wrap(&self.cmd.get_name().replace("{n}", "\n"), self.term_w) + }; + self.writer.push_string(bin_name); + } + + fn write_version(&mut self) { + let version = self + .cmd + .get_version() + .or_else(|| self.cmd.get_long_version()); + if let Some(output) = version { + self.writer.push_string(wrap(output, self.term_w)); + } + } + + fn write_author(&mut self, before_new_line: bool, after_new_line: bool) { + if let Some(author) = self.cmd.get_author() { + if before_new_line { + self.writer.push_str("\n"); + } + self.writer.push_string(wrap(author, self.term_w)); + if after_new_line { + self.writer.push_str("\n"); + } + } + } + + fn write_about(&mut self, before_new_line: bool, after_new_line: bool) { + let about = if self.use_long { + self.cmd.get_long_about().or_else(|| self.cmd.get_about()) + } else { + self.cmd.get_about() + }; + if let Some(output) = about { + if before_new_line { + self.writer.push_str("\n"); + } + let mut output = output.clone(); + output.replace_newline_var(); + output.wrap(self.term_w); + self.writer.push_styled(&output); + if after_new_line { + self.writer.push_str("\n"); + } + } + } + + fn write_before_help(&mut self) { + debug!("HelpTemplate::write_before_help"); + let before_help = if self.use_long { + self.cmd + .get_before_long_help() + .or_else(|| self.cmd.get_before_help()) + } else { + self.cmd.get_before_help() + }; + if let Some(output) = before_help { + let mut output = output.clone(); + output.replace_newline_var(); + output.wrap(self.term_w); + self.writer.push_styled(&output); + self.writer.push_str("\n\n"); + } + } + + fn write_after_help(&mut self) { + debug!("HelpTemplate::write_after_help"); + let after_help = if self.use_long { + self.cmd + .get_after_long_help() + .or_else(|| self.cmd.get_after_help()) + } else { + self.cmd.get_after_help() + }; + if let Some(output) = after_help { + self.writer.push_str("\n\n"); + let mut output = output.clone(); + output.replace_newline_var(); + output.wrap(self.term_w); + self.writer.push_styled(&output); + } + } +} + +/// Arg handling +impl<'cmd, 'writer> HelpTemplate<'cmd, 'writer> { + /// Writes help for all arguments (options, flags, args, subcommands) + /// including titles of a Parser Object to the wrapped stream. + pub(crate) fn write_all_args(&mut self) { + debug!("HelpTemplate::write_all_args"); + use std::fmt::Write as _; + let header = &self.styles.get_header(); + + let pos = self + .cmd + .get_positionals() + .filter(|a| a.get_help_heading().is_none()) + .filter(|arg| should_show_arg(self.use_long, arg)) + .collect::<Vec<_>>(); + let non_pos = self + .cmd + .get_non_positionals() + .filter(|a| a.get_help_heading().is_none()) + .filter(|arg| should_show_arg(self.use_long, arg)) + .collect::<Vec<_>>(); + let subcmds = self.cmd.has_visible_subcommands(); + + let custom_headings = self + .cmd + .get_arguments() + .filter_map(|arg| arg.get_help_heading()) + .collect::<FlatSet<_>>(); + + let flatten = self.cmd.is_flatten_help_set(); + + let mut first = true; + + if subcmds && !flatten { + if !first { + self.writer.push_str("\n\n"); + } + first = false; + let default_help_heading = Str::from("Commands"); + let help_heading = self + .cmd + .get_subcommand_help_heading() + .unwrap_or(&default_help_heading); + let _ = write!( + self.writer, + "{}{help_heading}:{}\n", + header.render(), + header.render_reset() + ); + + self.write_subcommands(self.cmd); + } + + if !pos.is_empty() { + if !first { + self.writer.push_str("\n\n"); + } + first = false; + // Write positional args if any + let help_heading = "Arguments"; + let _ = write!( + self.writer, + "{}{help_heading}:{}\n", + header.render(), + header.render_reset() + ); + self.write_args(&pos, "Arguments", positional_sort_key); + } + + if !non_pos.is_empty() { + if !first { + self.writer.push_str("\n\n"); + } + first = false; + let help_heading = "Options"; + let _ = write!( + self.writer, + "{}{help_heading}:{}\n", + header.render(), + header.render_reset() + ); + self.write_args(&non_pos, "Options", option_sort_key); + } + if !custom_headings.is_empty() { + for heading in custom_headings { + let args = self + .cmd + .get_arguments() + .filter(|a| { + if let Some(help_heading) = a.get_help_heading() { + return help_heading == heading; + } + false + }) + .filter(|arg| should_show_arg(self.use_long, arg)) + .collect::<Vec<_>>(); + + if !args.is_empty() { + if !first { + self.writer.push_str("\n\n"); + } + first = false; + let _ = write!( + self.writer, + "{}{heading}:{}\n", + header.render(), + header.render_reset() + ); + self.write_args(&args, heading, option_sort_key); + } + } + } + if subcmds && flatten { + let mut cmd = self.cmd.clone(); + cmd.build(); + self.write_flat_subcommands(&cmd, &mut first); + } + } + + /// Sorts arguments by length and display order and write their help to the wrapped stream. + fn write_args(&mut self, args: &[&Arg], _category: &str, sort_key: ArgSortKey) { + debug!("HelpTemplate::write_args {_category}"); + // The shortest an arg can legally be is 2 (i.e. '-x') + let mut longest = 2; + let mut ord_v = Vec::new(); + + // Determine the longest + for &arg in args.iter().filter(|arg| { + // If it's NextLineHelp we don't care to compute how long it is because it may be + // NextLineHelp on purpose simply *because* it's so long and would throw off all other + // args alignment + should_show_arg(self.use_long, arg) + }) { + if longest_filter(arg) { + longest = longest.max(display_width(&arg.to_string())); + debug!( + "HelpTemplate::write_args: arg={:?} longest={}", + arg.get_id(), + longest + ); + } + + let key = (sort_key)(arg); + ord_v.push((key, arg)); + } + ord_v.sort_by(|a, b| a.0.cmp(&b.0)); + + let next_line_help = self.will_args_wrap(args, longest); + + for (i, (_, arg)) in ord_v.iter().enumerate() { + if i != 0 { + self.writer.push_str("\n"); + if next_line_help && self.use_long { + self.writer.push_str("\n"); + } + } + self.write_arg(arg, next_line_help, longest); + } + } + + /// Writes help for an argument to the wrapped stream. + fn write_arg(&mut self, arg: &Arg, next_line_help: bool, longest: usize) { + let spec_vals = &self.spec_vals(arg); + + self.writer.push_str(TAB); + self.short(arg); + self.long(arg); + self.writer + .push_styled(&arg.stylize_arg_suffix(self.styles, None)); + self.align_to_about(arg, next_line_help, longest); + + let about = if self.use_long { + arg.get_long_help() + .or_else(|| arg.get_help()) + .unwrap_or_default() + } else { + arg.get_help() + .or_else(|| arg.get_long_help()) + .unwrap_or_default() + }; + + self.help(Some(arg), about, spec_vals, next_line_help, longest); + } + + /// Writes argument's short command to the wrapped stream. + fn short(&mut self, arg: &Arg) { + debug!("HelpTemplate::short"); + use std::fmt::Write as _; + let literal = &self.styles.get_literal(); + + if let Some(s) = arg.get_short() { + let _ = write!( + self.writer, + "{}-{s}{}", + literal.render(), + literal.render_reset() + ); + } else if arg.get_long().is_some() { + self.writer.push_str(" "); + } + } + + /// Writes argument's long command to the wrapped stream. + fn long(&mut self, arg: &Arg) { + debug!("HelpTemplate::long"); + use std::fmt::Write as _; + let literal = &self.styles.get_literal(); + + if let Some(long) = arg.get_long() { + if arg.get_short().is_some() { + self.writer.push_str(", "); + } + let _ = write!( + self.writer, + "{}--{long}{}", + literal.render(), + literal.render_reset() + ); + } + } + + /// Write alignment padding between arg's switches/values and its about message. + fn align_to_about(&mut self, arg: &Arg, next_line_help: bool, longest: usize) { + debug!( + "HelpTemplate::align_to_about: arg={}, next_line_help={}, longest={}", + arg.get_id(), + next_line_help, + longest + ); + let padding = if self.use_long || next_line_help { + // long help prints messages on the next line so it doesn't need to align text + debug!("HelpTemplate::align_to_about: printing long help so skip alignment"); + 0 + } else if !arg.is_positional() { + let self_len = display_width(&arg.to_string()); + // Since we're writing spaces from the tab point we first need to know if we + // had a long and short, or just short + let padding = if arg.get_long().is_some() { + // Only account 4 after the val + TAB_WIDTH + } else { + // Only account for ', --' + 4 after the val + TAB_WIDTH + 4 + }; + let spcs = longest + padding - self_len; + debug!( + "HelpTemplate::align_to_about: positional=false arg_len={self_len}, spaces={spcs}" + ); + + spcs + } else { + let self_len = display_width(&arg.to_string()); + let padding = TAB_WIDTH; + let spcs = longest + padding - self_len; + debug!( + "HelpTemplate::align_to_about: positional=true arg_len={self_len}, spaces={spcs}", + ); + + spcs + }; + + self.write_padding(padding); + } + + /// Writes argument's help to the wrapped stream. + fn help( + &mut self, + arg: Option<&Arg>, + about: &StyledStr, + spec_vals: &str, + next_line_help: bool, + longest: usize, + ) { + debug!("HelpTemplate::help"); + use std::fmt::Write as _; + let literal = &self.styles.get_literal(); + + // Is help on next line, if so then indent + if next_line_help { + debug!("HelpTemplate::help: Next Line...{next_line_help:?}"); + self.writer.push_str("\n"); + self.writer.push_str(TAB); + self.writer.push_str(NEXT_LINE_INDENT); + } + + let spaces = if next_line_help { + TAB.len() + NEXT_LINE_INDENT.len() + } else if let Some(true) = arg.map(|a| a.is_positional()) { + longest + TAB_WIDTH * 2 + } else { + longest + TAB_WIDTH * 2 + 4 // See `fn short` for the 4 + }; + let trailing_indent = spaces; // Don't indent any further than the first line is indented + let trailing_indent = self.get_spaces(trailing_indent); + + let mut help = about.clone(); + help.replace_newline_var(); + if !spec_vals.is_empty() { + if !help.is_empty() { + let sep = if self.use_long && arg.is_some() { + "\n\n" + } else { + " " + }; + help.push_str(sep); + } + help.push_str(spec_vals); + } + let avail_chars = self.term_w.saturating_sub(spaces); + debug!( + "HelpTemplate::help: help_width={}, spaces={}, avail={}", + spaces, + help.display_width(), + avail_chars + ); + help.wrap(avail_chars); + help.indent("", &trailing_indent); + let help_is_empty = help.is_empty(); + self.writer.push_styled(&help); + if let Some(arg) = arg { + if !arg.is_hide_possible_values_set() && self.use_long_pv(arg) { + const DASH_SPACE: usize = "- ".len(); + let possible_vals = arg.get_possible_values(); + if !possible_vals.is_empty() { + debug!("HelpTemplate::help: Found possible vals...{possible_vals:?}"); + let longest = possible_vals + .iter() + .filter(|f| !f.is_hide_set()) + .map(|f| display_width(f.get_name())) + .max() + .expect("Only called with possible value"); + + let spaces = spaces + TAB_WIDTH - DASH_SPACE; + let trailing_indent = spaces + DASH_SPACE; + let trailing_indent = self.get_spaces(trailing_indent); + + if !help_is_empty { + let _ = write!(self.writer, "\n\n{:spaces$}", ""); + } + self.writer.push_str("Possible values:"); + for pv in possible_vals.iter().filter(|pv| !pv.is_hide_set()) { + let name = pv.get_name(); + + let mut descr = StyledStr::new(); + let _ = write!( + &mut descr, + "{}{name}{}", + literal.render(), + literal.render_reset() + ); + if let Some(help) = pv.get_help() { + debug!("HelpTemplate::help: Possible Value help"); + // To align help messages + let padding = longest - display_width(name); + let _ = write!(&mut descr, ": {:padding$}", ""); + descr.push_styled(help); + } + + let avail_chars = if self.term_w > trailing_indent.len() { + self.term_w - trailing_indent.len() + } else { + usize::MAX + }; + descr.replace_newline_var(); + descr.wrap(avail_chars); + descr.indent("", &trailing_indent); + + let _ = write!(self.writer, "\n{:spaces$}- ", "",); + self.writer.push_styled(&descr); + } + } + } + } + } + + /// Will use next line help on writing args. + fn will_args_wrap(&self, args: &[&Arg], longest: usize) -> bool { + args.iter() + .filter(|arg| should_show_arg(self.use_long, arg)) + .any(|arg| { + let spec_vals = &self.spec_vals(arg); + self.arg_next_line_help(arg, spec_vals, longest) + }) + } + + fn arg_next_line_help(&self, arg: &Arg, spec_vals: &str, longest: usize) -> bool { + if self.next_line_help || arg.is_next_line_help_set() || self.use_long { + // setting_next_line + true + } else { + // force_next_line + let h = arg.get_help().unwrap_or_default(); + let h_w = h.display_width() + display_width(spec_vals); + let taken = if arg.is_positional() { + longest + TAB_WIDTH * 2 + } else { + longest + TAB_WIDTH * 2 + 4 // See `fn short` for the 4 + }; + self.term_w >= taken + && (taken as f32 / self.term_w as f32) > 0.40 + && h_w > (self.term_w - taken) + } + } + + fn spec_vals(&self, a: &Arg) -> String { + debug!("HelpTemplate::spec_vals: a={a}"); + let mut spec_vals = Vec::new(); + #[cfg(feature = "env")] + if let Some(ref env) = a.env { + if !a.is_hide_env_set() { + debug!( + "HelpTemplate::spec_vals: Found environment variable...[{:?}:{:?}]", + env.0, env.1 + ); + let env_val = if !a.is_hide_env_values_set() { + format!( + "={}", + env.1 + .as_ref() + .map(|s| s.to_string_lossy()) + .unwrap_or_default() + ) + } else { + Default::default() + }; + let env_info = format!("[env: {}{}]", env.0.to_string_lossy(), env_val); + spec_vals.push(env_info); + } + } + if a.is_takes_value_set() && !a.is_hide_default_value_set() && !a.default_vals.is_empty() { + debug!( + "HelpTemplate::spec_vals: Found default value...[{:?}]", + a.default_vals + ); + + let pvs = a + .default_vals + .iter() + .map(|pvs| pvs.to_string_lossy()) + .map(|pvs| { + if pvs.contains(char::is_whitespace) { + Cow::from(format!("{pvs:?}")) + } else { + pvs + } + }) + .collect::<Vec<_>>() + .join(" "); + + spec_vals.push(format!("[default: {pvs}]")); + } + + let als = a + .aliases + .iter() + .filter(|&als| als.1) // visible + .map(|als| als.0.as_str()) // name + .collect::<Vec<_>>() + .join(", "); + if !als.is_empty() { + debug!("HelpTemplate::spec_vals: Found aliases...{:?}", a.aliases); + spec_vals.push(format!("[aliases: {als}]")); + } + + let als = a + .short_aliases + .iter() + .filter(|&als| als.1) // visible + .map(|&als| als.0.to_string()) // name + .collect::<Vec<_>>() + .join(", "); + if !als.is_empty() { + debug!( + "HelpTemplate::spec_vals: Found short aliases...{:?}", + a.short_aliases + ); + spec_vals.push(format!("[short aliases: {als}]")); + } + + if !a.is_hide_possible_values_set() && !self.use_long_pv(a) { + let possible_vals = a.get_possible_values(); + if !possible_vals.is_empty() { + debug!("HelpTemplate::spec_vals: Found possible vals...{possible_vals:?}"); + + let pvs = possible_vals + .iter() + .filter_map(PossibleValue::get_visible_quoted_name) + .collect::<Vec<_>>() + .join(", "); + + spec_vals.push(format!("[possible values: {pvs}]")); + } + } + let connector = if self.use_long { "\n" } else { " " }; + spec_vals.join(connector) + } + + fn get_spaces(&self, n: usize) -> String { + " ".repeat(n) + } + + fn write_padding(&mut self, amount: usize) { + use std::fmt::Write as _; + let _ = write!(self.writer, "{:amount$}", ""); + } + + fn use_long_pv(&self, arg: &Arg) -> bool { + self.use_long + && arg + .get_possible_values() + .iter() + .any(PossibleValue::should_show_help) + } +} + +/// Subcommand handling +impl<'cmd, 'writer> HelpTemplate<'cmd, 'writer> { + /// Writes help for subcommands of a Parser Object to the wrapped stream. + fn write_flat_subcommands(&mut self, cmd: &Command, first: &mut bool) { + debug!( + "HelpTemplate::write_flat_subcommands, cmd={}, first={}", + cmd.get_name(), + *first + ); + use std::fmt::Write as _; + let header = &self.styles.get_header(); + + let mut ord_v = Vec::new(); + for subcommand in cmd + .get_subcommands() + .filter(|subcommand| should_show_subcommand(subcommand)) + { + ord_v.push(( + subcommand.get_display_order(), + subcommand.get_name(), + subcommand, + )); + } + ord_v.sort_by(|a, b| (a.0, &a.1).cmp(&(b.0, &b.1))); + for (_, _, subcommand) in ord_v { + if !*first { + self.writer.push_str("\n\n"); + } + *first = false; + + let heading = subcommand.get_usage_name_fallback(); + let about = subcommand + .get_about() + .or_else(|| subcommand.get_long_about()) + .unwrap_or_default(); + + let _ = write!( + self.writer, + "{}{heading}:{}\n", + header.render(), + header.render_reset() + ); + if !about.is_empty() { + let _ = write!(self.writer, "{about}\n",); + } + + let mut sub_help = HelpTemplate { + writer: self.writer, + cmd: subcommand, + styles: self.styles, + usage: self.usage, + next_line_help: self.next_line_help, + term_w: self.term_w, + use_long: self.use_long, + }; + let args = subcommand + .get_arguments() + .filter(|arg| should_show_arg(self.use_long, arg) && !arg.is_global_set()) + .collect::<Vec<_>>(); + sub_help.write_args(&args, heading, option_sort_key); + if subcommand.is_flatten_help_set() { + sub_help.write_flat_subcommands(subcommand, first); + } + } + } + + /// Writes help for subcommands of a Parser Object to the wrapped stream. + fn write_subcommands(&mut self, cmd: &Command) { + debug!("HelpTemplate::write_subcommands"); + use std::fmt::Write as _; + let literal = &self.styles.get_literal(); + + // The shortest an arg can legally be is 2 (i.e. '-x') + let mut longest = 2; + let mut ord_v = Vec::new(); + for subcommand in cmd + .get_subcommands() + .filter(|subcommand| should_show_subcommand(subcommand)) + { + let mut styled = StyledStr::new(); + let name = subcommand.get_name(); + let _ = write!( + styled, + "{}{name}{}", + literal.render(), + literal.render_reset() + ); + if let Some(short) = subcommand.get_short_flag() { + let _ = write!( + styled, + ", {}-{short}{}", + literal.render(), + literal.render_reset() + ); + } + if let Some(long) = subcommand.get_long_flag() { + let _ = write!( + styled, + ", {}--{long}{}", + literal.render(), + literal.render_reset() + ); + } + longest = longest.max(styled.display_width()); + ord_v.push((subcommand.get_display_order(), styled, subcommand)); + } + ord_v.sort_by(|a, b| (a.0, &a.1).cmp(&(b.0, &b.1))); + + debug!("HelpTemplate::write_subcommands longest = {longest}"); + + let next_line_help = self.will_subcommands_wrap(cmd.get_subcommands(), longest); + + for (i, (_, sc_str, sc)) in ord_v.into_iter().enumerate() { + if 0 < i { + self.writer.push_str("\n"); + } + self.write_subcommand(sc_str, sc, next_line_help, longest); + } + } + + /// Will use next line help on writing subcommands. + fn will_subcommands_wrap<'a>( + &self, + subcommands: impl IntoIterator<Item = &'a Command>, + longest: usize, + ) -> bool { + subcommands + .into_iter() + .filter(|&subcommand| should_show_subcommand(subcommand)) + .any(|subcommand| { + let spec_vals = &self.sc_spec_vals(subcommand); + self.subcommand_next_line_help(subcommand, spec_vals, longest) + }) + } + + fn write_subcommand( + &mut self, + sc_str: StyledStr, + cmd: &Command, + next_line_help: bool, + longest: usize, + ) { + debug!("HelpTemplate::write_subcommand"); + + let spec_vals = &self.sc_spec_vals(cmd); + + let about = cmd + .get_about() + .or_else(|| cmd.get_long_about()) + .unwrap_or_default(); + + self.subcmd(sc_str, next_line_help, longest); + self.help(None, about, spec_vals, next_line_help, longest) + } + + fn sc_spec_vals(&self, a: &Command) -> String { + debug!("HelpTemplate::sc_spec_vals: a={}", a.get_name()); + let mut spec_vals = vec![]; + + let mut short_als = a + .get_visible_short_flag_aliases() + .map(|a| format!("-{a}")) + .collect::<Vec<_>>(); + let als = a.get_visible_aliases().map(|s| s.to_string()); + short_als.extend(als); + let all_als = short_als.join(", "); + if !all_als.is_empty() { + debug!( + "HelpTemplate::spec_vals: Found aliases...{:?}", + a.get_all_aliases().collect::<Vec<_>>() + ); + debug!( + "HelpTemplate::spec_vals: Found short flag aliases...{:?}", + a.get_all_short_flag_aliases().collect::<Vec<_>>() + ); + spec_vals.push(format!("[aliases: {all_als}]")); + } + + spec_vals.join(" ") + } + + fn subcommand_next_line_help(&self, cmd: &Command, spec_vals: &str, longest: usize) -> bool { + // Ignore `self.use_long` since subcommands are only shown as short help + if self.next_line_help { + // setting_next_line + true + } else { + // force_next_line + let h = cmd.get_about().unwrap_or_default(); + let h_w = h.display_width() + display_width(spec_vals); + let taken = longest + TAB_WIDTH * 2; + self.term_w >= taken + && (taken as f32 / self.term_w as f32) > 0.40 + && h_w > (self.term_w - taken) + } + } + + /// Writes subcommand to the wrapped stream. + fn subcmd(&mut self, sc_str: StyledStr, next_line_help: bool, longest: usize) { + self.writer.push_str(TAB); + self.writer.push_styled(&sc_str); + if !next_line_help { + let width = sc_str.display_width(); + let padding = longest + TAB_WIDTH - width; + self.write_padding(padding); + } + } +} + +const NEXT_LINE_INDENT: &str = " "; + +type ArgSortKey = fn(arg: &Arg) -> (usize, String); + +fn positional_sort_key(arg: &Arg) -> (usize, String) { + (arg.get_index().unwrap_or(0), String::new()) +} + +fn option_sort_key(arg: &Arg) -> (usize, String) { + // Formatting key like this to ensure that: + // 1. Argument has long flags are printed just after short flags. + // 2. For two args both have short flags like `-c` and `-C`, the + // `-C` arg is printed just after the `-c` arg + // 3. For args without short or long flag, print them at last(sorted + // by arg name). + // Example order: -a, -b, -B, -s, --select-file, --select-folder, -x + + let key = if let Some(x) = arg.get_short() { + let mut s = x.to_ascii_lowercase().to_string(); + s.push(if x.is_ascii_lowercase() { '0' } else { '1' }); + s + } else if let Some(x) = arg.get_long() { + x.to_string() + } else { + let mut s = '{'.to_string(); + s.push_str(arg.get_id().as_str()); + s + }; + (arg.get_display_order(), key) +} + +pub(crate) fn dimensions() -> (Option<usize>, Option<usize>) { + #[cfg(not(feature = "wrap_help"))] + return (None, None); + + #[cfg(feature = "wrap_help")] + terminal_size::terminal_size() + .map(|(w, h)| (Some(w.0.into()), Some(h.0.into()))) + .unwrap_or_else(|| (parse_env("COLUMNS"), parse_env("LINES"))) +} + +#[cfg(feature = "wrap_help")] +fn parse_env(var: &str) -> Option<usize> { + some!(some!(std::env::var_os(var)).to_str()) + .parse::<usize>() + .ok() +} + +fn should_show_arg(use_long: bool, arg: &Arg) -> bool { + debug!( + "should_show_arg: use_long={:?}, arg={}", + use_long, + arg.get_id() + ); + if arg.is_hide_set() { + return false; + } + (!arg.is_hide_long_help_set() && use_long) + || (!arg.is_hide_short_help_set() && !use_long) + || arg.is_next_line_help_set() +} + +fn should_show_subcommand(subcommand: &Command) -> bool { + !subcommand.is_hide_set() +} + +fn longest_filter(arg: &Arg) -> bool { + arg.is_takes_value_set() || arg.get_long().is_some() || arg.get_short().is_none() +} + +#[cfg(test)] +mod test { + #[test] + #[cfg(feature = "wrap_help")] + fn wrap_help_last_word() { + use super::*; + + let help = String::from("foo bar baz"); + assert_eq!(wrap(&help, 5), "foo\nbar\nbaz"); + } + + #[test] + #[cfg(feature = "unicode")] + fn display_width_handles_non_ascii() { + use super::*; + + // Popular Danish tongue-twister, the name of a fruit dessert. + let text = "rødgrød med fløde"; + assert_eq!(display_width(text), 17); + // Note that the string width is smaller than the string + // length. This is due to the precomposed non-ASCII letters: + assert_eq!(text.len(), 20); + } + + #[test] + #[cfg(feature = "unicode")] + fn display_width_handles_emojis() { + use super::*; + + let text = "😂"; + // There is a single `char`... + assert_eq!(text.chars().count(), 1); + // but it is double-width: + assert_eq!(display_width(text), 2); + // This is much less than the byte length: + assert_eq!(text.len(), 4); + } +} diff --git a/vendor/clap_builder/src/output/mod.rs b/vendor/clap_builder/src/output/mod.rs new file mode 100644 index 0000000..b358711 --- /dev/null +++ b/vendor/clap_builder/src/output/mod.rs @@ -0,0 +1,23 @@ +mod help; +#[cfg(feature = "help")] +mod help_template; +mod usage; + +pub(crate) mod fmt; +#[cfg(feature = "help")] +pub(crate) mod textwrap; + +pub(crate) use self::help::write_help; +#[cfg(feature = "help")] +pub(crate) use self::help_template::AutoHelp; +#[cfg(feature = "help")] +pub(crate) use self::help_template::HelpTemplate; +#[cfg(feature = "help")] +pub(crate) use self::textwrap::core::display_width; +#[cfg(feature = "help")] +pub(crate) use self::textwrap::wrap; +pub(crate) use self::usage::Usage; + +pub(crate) const TAB: &str = " "; +#[cfg(feature = "help")] +pub(crate) const TAB_WIDTH: usize = TAB.len(); diff --git a/vendor/clap_builder/src/output/textwrap/core.rs b/vendor/clap_builder/src/output/textwrap/core.rs new file mode 100644 index 0000000..2f6004c --- /dev/null +++ b/vendor/clap_builder/src/output/textwrap/core.rs @@ -0,0 +1,158 @@ +/// Compute the display width of `text` +/// +/// # Examples +/// +/// **Note:** When the `unicode` Cargo feature is disabled, all characters are presumed to take up +/// 1 width. With the feature enabled, function will correctly deal with [combining characters] in +/// their decomposed form (see [Unicode equivalence]). +/// +/// An example of a decomposed character is “é”, which can be decomposed into: “e” followed by a +/// combining acute accent: “◌́”. Without the `unicode` Cargo feature, every `char` has a width of +/// 1. This includes the combining accent: +/// +/// ## Emojis and CJK Characters +/// +/// Characters such as emojis and [CJK characters] used in the +/// Chinese, Japanese, and Korean languages are seen as double-width, +/// even if the `unicode-width` feature is disabled: +/// +/// # Limitations +/// +/// The displayed width of a string cannot always be computed from the +/// string alone. This is because the width depends on the rendering +/// engine used. This is particularly visible with [emoji modifier +/// sequences] where a base emoji is modified with, e.g., skin tone or +/// hair color modifiers. It is up to the rendering engine to detect +/// this and to produce a suitable emoji. +/// +/// A simple example is “❤️”, which consists of “❤” (U+2764: Black +/// Heart Symbol) followed by U+FE0F (Variation Selector-16). By +/// itself, “❤” is a black heart, but if you follow it with the +/// variant selector, you may get a wider red heart. +/// +/// A more complex example would be “👨🦰” which should depict a man +/// with red hair. Here the computed width is too large — and the +/// width differs depending on the use of the `unicode-width` feature: +/// +/// This happens because the grapheme consists of three code points: +/// “👨” (U+1F468: Man), Zero Width Joiner (U+200D), and “🦰” +/// (U+1F9B0: Red Hair). You can see them above in the test. With +/// `unicode-width` enabled, the ZWJ is correctly seen as having zero +/// width, without it is counted as a double-width character. +/// +/// ## Terminal Support +/// +/// Modern browsers typically do a great job at combining characters +/// as shown above, but terminals often struggle more. As an example, +/// Gnome Terminal version 3.38.1, shows “❤️” as a big red heart, but +/// shows "👨🦰" as “👨🦰”. +/// +/// [combining characters]: https://en.wikipedia.org/wiki/Combining_character +/// [Unicode equivalence]: https://en.wikipedia.org/wiki/Unicode_equivalence +/// [CJK characters]: https://en.wikipedia.org/wiki/CJK_characters +/// [emoji modifier sequences]: https://unicode.org/emoji/charts/full-emoji-modifiers.html +#[inline(never)] +pub(crate) fn display_width(text: &str) -> usize { + let mut width = 0; + + let mut control_sequence = false; + let control_terminate: char = 'm'; + + for ch in text.chars() { + if ch.is_ascii_control() { + control_sequence = true; + } else if control_sequence && ch == control_terminate { + control_sequence = false; + continue; + } + + if !control_sequence { + width += ch_width(ch); + } + } + width +} + +#[cfg(feature = "unicode")] +fn ch_width(ch: char) -> usize { + unicode_width::UnicodeWidthChar::width(ch).unwrap_or(0) +} + +#[cfg(not(feature = "unicode"))] +fn ch_width(_: char) -> usize { + 1 +} + +#[cfg(test)] +mod tests { + use super::*; + + #[cfg(feature = "unicode")] + use unicode_width::UnicodeWidthChar; + + #[test] + fn emojis_have_correct_width() { + use unic_emoji_char::is_emoji; + + // Emojis in the Basic Latin (ASCII) and Latin-1 Supplement + // blocks all have a width of 1 column. This includes + // characters such as '#' and '©'. + for ch in '\u{1}'..'\u{FF}' { + if is_emoji(ch) { + let desc = format!("{:?} U+{:04X}", ch, ch as u32); + + #[cfg(feature = "unicode")] + assert_eq!(ch.width().unwrap(), 1, "char: {desc}"); + + #[cfg(not(feature = "unicode"))] + assert_eq!(ch_width(ch), 1, "char: {desc}"); + } + } + + // Emojis in the remaining blocks of the Basic Multilingual + // Plane (BMP), in the Supplementary Multilingual Plane (SMP), + // and in the Supplementary Ideographic Plane (SIP), are all 1 + // or 2 columns wide when unicode-width is used, and always 2 + // columns wide otherwise. This includes all of our favorite + // emojis such as 😊. + for ch in '\u{FF}'..'\u{2FFFF}' { + if is_emoji(ch) { + let desc = format!("{:?} U+{:04X}", ch, ch as u32); + + #[cfg(feature = "unicode")] + assert!(ch.width().unwrap() <= 2, "char: {desc}"); + + #[cfg(not(feature = "unicode"))] + assert_eq!(ch_width(ch), 1, "char: {desc}"); + } + } + + // The remaining planes contain almost no assigned code points + // and thus also no emojis. + } + + #[test] + #[cfg(feature = "unicode")] + fn display_width_works() { + assert_eq!("Café Plain".len(), 11); // “é” is two bytes + assert_eq!(display_width("Café Plain"), 10); + } + + #[test] + #[cfg(feature = "unicode")] + fn display_width_narrow_emojis() { + assert_eq!(display_width("⁉"), 1); + } + + #[test] + #[cfg(feature = "unicode")] + fn display_width_narrow_emojis_variant_selector() { + assert_eq!(display_width("⁉\u{fe0f}"), 1); + } + + #[test] + #[cfg(feature = "unicode")] + fn display_width_emojis() { + assert_eq!(display_width("😂😭🥺🤣✨😍🙏🥰😊🔥"), 20); + } +} diff --git a/vendor/clap_builder/src/output/textwrap/mod.rs b/vendor/clap_builder/src/output/textwrap/mod.rs new file mode 100644 index 0000000..fe8139f --- /dev/null +++ b/vendor/clap_builder/src/output/textwrap/mod.rs @@ -0,0 +1,122 @@ +//! Fork of `textwrap` crate +//! +//! Benefits of forking: +//! - Pull in only what we need rather than relying on the compiler to remove what we don't need +//! - `LineWrapper` is able to incrementally wrap which will help with `StyledStr + +pub(crate) mod core; +#[cfg(feature = "wrap_help")] +pub(crate) mod word_separators; +#[cfg(feature = "wrap_help")] +pub(crate) mod wrap_algorithms; + +#[cfg(feature = "wrap_help")] +pub(crate) fn wrap(content: &str, hard_width: usize) -> String { + let mut wrapper = wrap_algorithms::LineWrapper::new(hard_width); + let mut total = Vec::new(); + for line in content.split_inclusive('\n') { + wrapper.reset(); + let line = word_separators::find_words_ascii_space(line).collect::<Vec<_>>(); + total.extend(wrapper.wrap(line)); + } + total.join("") +} + +#[cfg(not(feature = "wrap_help"))] +pub(crate) fn wrap(content: &str, _hard_width: usize) -> String { + content.to_owned() +} + +#[cfg(test)] +#[cfg(feature = "wrap_help")] +mod test { + /// Compatibility shim to keep textwrap's tests + fn wrap(content: &str, hard_width: usize) -> Vec<String> { + super::wrap(content, hard_width) + .trim_end() + .split('\n') + .map(|s| s.to_owned()) + .collect::<Vec<_>>() + } + + #[test] + fn no_wrap() { + assert_eq!(wrap("foo", 10), vec!["foo"]); + } + + #[test] + fn wrap_simple() { + assert_eq!(wrap("foo bar baz", 5), vec!["foo", "bar", "baz"]); + } + + #[test] + fn to_be_or_not() { + assert_eq!( + wrap("To be, or not to be, that is the question.", 10), + vec!["To be, or", "not to be,", "that is", "the", "question."] + ); + } + + #[test] + fn multiple_words_on_first_line() { + assert_eq!(wrap("foo bar baz", 10), vec!["foo bar", "baz"]); + } + + #[test] + fn long_word() { + assert_eq!(wrap("foo", 0), vec!["foo"]); + } + + #[test] + fn long_words() { + assert_eq!(wrap("foo bar", 0), vec!["foo", "bar"]); + } + + #[test] + fn max_width() { + assert_eq!(wrap("foo bar", usize::MAX), vec!["foo bar"]); + + let text = "Hello there! This is some English text. \ + It should not be wrapped given the extents below."; + assert_eq!(wrap(text, usize::MAX), vec![text]); + } + + #[test] + fn leading_whitespace() { + assert_eq!(wrap(" foo bar", 6), vec![" foo", " bar"]); + } + + #[test] + fn leading_whitespace_empty_first_line() { + // If there is no space for the first word, the first line + // will be empty. This is because the string is split into + // words like [" ", "foobar ", "baz"], which puts "foobar " on + // the second line. We never output trailing whitespace + assert_eq!(wrap(" foobar baz", 6), vec!["", " foobar", " baz"]); + } + + #[test] + fn trailing_whitespace() { + // Whitespace is only significant inside a line. After a line + // gets too long and is broken, the first word starts in + // column zero and is not indented. + assert_eq!(wrap("foo bar baz ", 5), vec!["foo", "bar", "baz"]); + } + + #[test] + fn issue_99() { + // We did not reset the in_whitespace flag correctly and did + // not handle single-character words after a line break. + assert_eq!( + wrap("aaabbbccc x yyyzzzwww", 9), + vec!["aaabbbccc", "x", "yyyzzzwww"] + ); + } + + #[test] + fn issue_129() { + // The dash is an em-dash which takes up four bytes. We used + // to panic since we tried to index into the character. + assert_eq!(wrap("x – x", 1), vec!["x", "–", "x"]); + } +} diff --git a/vendor/clap_builder/src/output/textwrap/word_separators.rs b/vendor/clap_builder/src/output/textwrap/word_separators.rs new file mode 100644 index 0000000..cb8250b --- /dev/null +++ b/vendor/clap_builder/src/output/textwrap/word_separators.rs @@ -0,0 +1,92 @@ +pub(crate) fn find_words_ascii_space(line: &str) -> impl Iterator<Item = &'_ str> + '_ { + let mut start = 0; + let mut in_whitespace = false; + let mut char_indices = line.char_indices(); + + std::iter::from_fn(move || { + for (idx, ch) in char_indices.by_ref() { + let next_whitespace = ch == ' '; + if in_whitespace && !next_whitespace { + let word = &line[start..idx]; + start = idx; + in_whitespace = next_whitespace; + return Some(word); + } + + in_whitespace = next_whitespace; + } + + if start < line.len() { + let word = &line[start..]; + start = line.len(); + return Some(word); + } + + None + }) +} + +#[cfg(test)] +mod tests { + use super::*; + + macro_rules! test_find_words { + ($ascii_name:ident, + $([ $line:expr, $ascii_words:expr ]),+) => { + #[test] + fn $ascii_name() { + $( + let expected_words: Vec<&str> = $ascii_words.to_vec(); + let actual_words = find_words_ascii_space($line) + .collect::<Vec<_>>(); + assert_eq!(actual_words, expected_words, "Line: {:?}", $line); + )+ + } + }; + } + + test_find_words!(ascii_space_empty, ["", []]); + + test_find_words!(ascii_single_word, ["foo", ["foo"]]); + + test_find_words!(ascii_two_words, ["foo bar", ["foo ", "bar"]]); + + test_find_words!( + ascii_multiple_words, + ["foo bar", ["foo ", "bar"]], + ["x y z", ["x ", "y ", "z"]] + ); + + test_find_words!(ascii_only_whitespace, [" ", [" "]], [" ", [" "]]); + + test_find_words!( + ascii_inter_word_whitespace, + ["foo bar", ["foo ", "bar"]] + ); + + test_find_words!(ascii_trailing_whitespace, ["foo ", ["foo "]]); + + test_find_words!(ascii_leading_whitespace, [" foo", [" ", "foo"]]); + + test_find_words!( + ascii_multi_column_char, + ["\u{1f920}", ["\u{1f920}"]] // cowboy emoji 🤠 + ); + + test_find_words!( + ascii_hyphens, + ["foo-bar", ["foo-bar"]], + ["foo- bar", ["foo- ", "bar"]], + ["foo - bar", ["foo ", "- ", "bar"]], + ["foo -bar", ["foo ", "-bar"]] + ); + + test_find_words!(ascii_newline, ["foo\nbar", ["foo\nbar"]]); + + test_find_words!(ascii_tab, ["foo\tbar", ["foo\tbar"]]); + + test_find_words!( + ascii_non_breaking_space, + ["foo\u{00A0}bar", ["foo\u{00A0}bar"]] + ); +} diff --git a/vendor/clap_builder/src/output/textwrap/wrap_algorithms.rs b/vendor/clap_builder/src/output/textwrap/wrap_algorithms.rs new file mode 100644 index 0000000..34b4fd2 --- /dev/null +++ b/vendor/clap_builder/src/output/textwrap/wrap_algorithms.rs @@ -0,0 +1,63 @@ +use super::core::display_width; + +#[derive(Debug)] +pub(crate) struct LineWrapper<'w> { + hard_width: usize, + line_width: usize, + carryover: Option<&'w str>, +} + +impl<'w> LineWrapper<'w> { + pub(crate) fn new(hard_width: usize) -> Self { + Self { + hard_width, + line_width: 0, + carryover: None, + } + } + + pub(crate) fn reset(&mut self) { + self.line_width = 0; + self.carryover = None; + } + + pub(crate) fn wrap(&mut self, mut words: Vec<&'w str>) -> Vec<&'w str> { + if self.carryover.is_none() { + if let Some(word) = words.first() { + if word.trim().is_empty() { + self.carryover = Some(*word); + } else { + self.carryover = Some(""); + } + } + } + + let mut i = 0; + while i < words.len() { + let word = &words[i]; + let trimmed = word.trim_end(); + let word_width = display_width(trimmed); + let trimmed_delta = word.len() - trimmed.len(); + if i != 0 && self.hard_width < self.line_width + word_width { + if 0 < i { + let last = i - 1; + let trimmed = words[last].trim_end(); + words[last] = trimmed; + } + + self.line_width = 0; + words.insert(i, "\n"); + i += 1; + if let Some(carryover) = self.carryover { + words.insert(i, carryover); + self.line_width += carryover.len(); + i += 1; + } + } + self.line_width += word_width + trimmed_delta; + + i += 1; + } + words + } +} diff --git a/vendor/clap_builder/src/output/usage.rs b/vendor/clap_builder/src/output/usage.rs new file mode 100644 index 0000000..d75b704 --- /dev/null +++ b/vendor/clap_builder/src/output/usage.rs @@ -0,0 +1,529 @@ +#![cfg_attr(not(feature = "usage"), allow(unused_imports))] +#![cfg_attr(not(feature = "usage"), allow(unused_variables))] +#![cfg_attr(not(feature = "usage"), allow(clippy::manual_map))] +#![cfg_attr(not(feature = "usage"), allow(dead_code))] + +// Internal +use crate::builder::ArgAction; +use crate::builder::StyledStr; +use crate::builder::Styles; +use crate::builder::{ArgPredicate, Command}; +use crate::parser::ArgMatcher; +use crate::util::ChildGraph; +use crate::util::FlatSet; +use crate::util::Id; + +static DEFAULT_SUB_VALUE_NAME: &str = "COMMAND"; +const USAGE_SEP: &str = "\n "; + +pub(crate) struct Usage<'cmd> { + cmd: &'cmd Command, + styles: &'cmd Styles, + required: Option<&'cmd ChildGraph<Id>>, +} + +impl<'cmd> Usage<'cmd> { + pub(crate) fn new(cmd: &'cmd Command) -> Self { + Usage { + cmd, + styles: cmd.get_styles(), + required: None, + } + } + + pub(crate) fn required(mut self, required: &'cmd ChildGraph<Id>) -> Self { + self.required = Some(required); + self + } + + // Creates a usage string for display. This happens just after all arguments were parsed, but before + // any subcommands have been parsed (so as to give subcommands their own usage recursively) + pub(crate) fn create_usage_with_title(&self, used: &[Id]) -> Option<StyledStr> { + debug!("Usage::create_usage_with_title"); + use std::fmt::Write as _; + let mut styled = StyledStr::new(); + let _ = write!( + styled, + "{}Usage:{} ", + self.styles.get_usage().render(), + self.styles.get_usage().render_reset() + ); + if self.write_usage_no_title(&mut styled, used) { + styled.trim_end(); + } else { + return None; + } + debug!("Usage::create_usage_with_title: usage={styled}"); + Some(styled) + } + + // Creates a usage string (*without title*) if one was not provided by the user manually. + pub(crate) fn create_usage_no_title(&self, used: &[Id]) -> Option<StyledStr> { + debug!("Usage::create_usage_no_title"); + + let mut styled = StyledStr::new(); + if self.write_usage_no_title(&mut styled, used) { + styled.trim_end(); + debug!("Usage::create_usage_no_title: usage={styled}"); + Some(styled) + } else { + None + } + } + + // Creates a usage string (*without title*) if one was not provided by the user manually. + fn write_usage_no_title(&self, styled: &mut StyledStr, used: &[Id]) -> bool { + debug!("Usage::create_usage_no_title"); + if let Some(u) = self.cmd.get_override_usage() { + styled.push_styled(u); + true + } else { + #[cfg(feature = "usage")] + { + if used.is_empty() { + self.write_help_usage(styled); + } else { + self.write_smart_usage(styled, used); + } + true + } + + #[cfg(not(feature = "usage"))] + { + false + } + } + } +} + +#[cfg(feature = "usage")] +impl<'cmd> Usage<'cmd> { + // Creates a usage string for display in help messages (i.e. not for errors) + fn write_help_usage(&self, styled: &mut StyledStr) { + debug!("Usage::write_help_usage"); + use std::fmt::Write; + + if self.cmd.has_visible_subcommands() && self.cmd.is_flatten_help_set() { + if !self.cmd.is_subcommand_required_set() + || self.cmd.is_args_conflicts_with_subcommands_set() + { + self.write_arg_usage(styled, &[], true); + styled.trim_end(); + let _ = write!(styled, "{}", USAGE_SEP); + } + let mut cmd = self.cmd.clone(); + cmd.build(); + for (i, sub) in cmd + .get_subcommands() + .filter(|c| !c.is_hide_set()) + .enumerate() + { + if i != 0 { + styled.trim_end(); + let _ = write!(styled, "{}", USAGE_SEP); + } + Usage::new(sub).write_usage_no_title(styled, &[]); + } + } else { + self.write_arg_usage(styled, &[], true); + self.write_subcommand_usage(styled); + } + } + + // Creates a context aware usage string, or "smart usage" from currently used + // args, and requirements + fn write_smart_usage(&self, styled: &mut StyledStr, used: &[Id]) { + debug!("Usage::create_smart_usage"); + use std::fmt::Write; + let placeholder = &self.styles.get_placeholder(); + + self.write_arg_usage(styled, used, true); + + if self.cmd.is_subcommand_required_set() { + let value_name = self + .cmd + .get_subcommand_value_name() + .unwrap_or(DEFAULT_SUB_VALUE_NAME); + let _ = write!( + styled, + "{}<{value_name}>{}", + placeholder.render(), + placeholder.render_reset() + ); + } + } + + fn write_arg_usage(&self, styled: &mut StyledStr, used: &[Id], incl_reqs: bool) { + debug!("Usage::write_arg_usage; incl_reqs={incl_reqs:?}"); + use std::fmt::Write as _; + let literal = &self.styles.get_literal(); + let placeholder = &self.styles.get_placeholder(); + + let bin_name = self.cmd.get_usage_name_fallback(); + if !bin_name.is_empty() { + // the trim won't properly remove a leading space due to the formatting + let _ = write!( + styled, + "{}{bin_name}{} ", + literal.render(), + literal.render_reset() + ); + } + + if used.is_empty() && self.needs_options_tag() { + let _ = write!( + styled, + "{}[OPTIONS]{} ", + placeholder.render(), + placeholder.render_reset() + ); + } + + self.write_args(styled, used, !incl_reqs); + } + + fn write_subcommand_usage(&self, styled: &mut StyledStr) { + debug!("Usage::write_subcommand_usage"); + use std::fmt::Write as _; + + // incl_reqs is only false when this function is called recursively + if self.cmd.has_visible_subcommands() || self.cmd.is_allow_external_subcommands_set() { + let literal = &self.styles.get_literal(); + let placeholder = &self.styles.get_placeholder(); + let value_name = self + .cmd + .get_subcommand_value_name() + .unwrap_or(DEFAULT_SUB_VALUE_NAME); + if self.cmd.is_subcommand_negates_reqs_set() + || self.cmd.is_args_conflicts_with_subcommands_set() + { + styled.trim_end(); + let _ = write!(styled, "{}", USAGE_SEP); + if self.cmd.is_args_conflicts_with_subcommands_set() { + let bin_name = self.cmd.get_usage_name_fallback(); + // Short-circuit full usage creation since no args will be relevant + let _ = write!( + styled, + "{}{bin_name}{} ", + literal.render(), + literal.render_reset() + ); + } else { + self.write_arg_usage(styled, &[], false); + } + let _ = write!( + styled, + "{}<{value_name}>{}", + placeholder.render(), + placeholder.render_reset() + ); + } else if self.cmd.is_subcommand_required_set() { + let _ = write!( + styled, + "{}<{value_name}>{}", + placeholder.render(), + placeholder.render_reset() + ); + } else { + let _ = write!( + styled, + "{}[{value_name}]{}", + placeholder.render(), + placeholder.render_reset() + ); + } + } + } + + // Determines if we need the `[OPTIONS]` tag in the usage string + fn needs_options_tag(&self) -> bool { + debug!("Usage::needs_options_tag"); + 'outer: for f in self.cmd.get_non_positionals() { + debug!("Usage::needs_options_tag:iter: f={}", f.get_id()); + + // Don't print `[OPTIONS]` just for help or version + if f.get_long() == Some("help") || f.get_long() == Some("version") { + debug!("Usage::needs_options_tag:iter Option is built-in"); + continue; + } + match f.get_action() { + ArgAction::Set + | ArgAction::Append + | ArgAction::SetTrue + | ArgAction::SetFalse + | ArgAction::Count => {} + ArgAction::Help + | ArgAction::HelpShort + | ArgAction::HelpLong + | ArgAction::Version => { + debug!("Usage::needs_options_tag:iter Option is built-in"); + continue; + } + } + + if f.is_hide_set() { + debug!("Usage::needs_options_tag:iter Option is hidden"); + continue; + } + if f.is_required_set() { + debug!("Usage::needs_options_tag:iter Option is required"); + continue; + } + for grp_s in self.cmd.groups_for_arg(f.get_id()) { + debug!("Usage::needs_options_tag:iter:iter: grp_s={grp_s:?}"); + if self.cmd.get_groups().any(|g| g.id == grp_s && g.required) { + debug!("Usage::needs_options_tag:iter:iter: Group is required"); + continue 'outer; + } + } + + debug!("Usage::needs_options_tag:iter: [OPTIONS] required"); + return true; + } + + debug!("Usage::needs_options_tag: [OPTIONS] not required"); + false + } + + // Returns the required args in usage string form by fully unrolling all groups + pub(crate) fn write_args(&self, styled: &mut StyledStr, incls: &[Id], force_optional: bool) { + debug!("Usage::write_args: incls={incls:?}",); + use std::fmt::Write as _; + let literal = &self.styles.get_literal(); + + let required_owned; + let required = if let Some(required) = self.required { + required + } else { + required_owned = self.cmd.required_graph(); + &required_owned + }; + + let mut unrolled_reqs = Vec::new(); + for a in required.iter() { + let is_relevant = |(val, req_arg): &(ArgPredicate, Id)| -> Option<Id> { + let required = match val { + ArgPredicate::Equals(_) => false, + ArgPredicate::IsPresent => true, + }; + required.then(|| req_arg.clone()) + }; + + for aa in self.cmd.unroll_arg_requires(is_relevant, a) { + // if we don't check for duplicates here this causes duplicate error messages + // see https://github.com/clap-rs/clap/issues/2770 + unrolled_reqs.push(aa); + } + // always include the required arg itself. it will not be enumerated + // by unroll_requirements_for_arg. + unrolled_reqs.push(a.clone()); + } + debug!("Usage::get_args: unrolled_reqs={unrolled_reqs:?}"); + + let mut required_groups_members = FlatSet::new(); + let mut required_groups = FlatSet::new(); + for req in unrolled_reqs.iter().chain(incls.iter()) { + if self.cmd.find_group(req).is_some() { + let group_members = self.cmd.unroll_args_in_group(req); + let elem = self.cmd.format_group(req); + required_groups.insert(elem); + required_groups_members.extend(group_members); + } else { + debug_assert!(self.cmd.find(req).is_some()); + } + } + + let mut required_opts = FlatSet::new(); + let mut required_positionals = Vec::new(); + for req in unrolled_reqs.iter().chain(incls.iter()) { + if let Some(arg) = self.cmd.find(req) { + if required_groups_members.contains(arg.get_id()) { + continue; + } + + let stylized = arg.stylized(self.styles, Some(!force_optional)); + if let Some(index) = arg.get_index() { + let new_len = index + 1; + if required_positionals.len() < new_len { + required_positionals.resize(new_len, None); + } + required_positionals[index] = Some(stylized); + } else { + required_opts.insert(stylized); + } + } else { + debug_assert!(self.cmd.find_group(req).is_some()); + } + } + + for pos in self.cmd.get_positionals() { + if pos.is_hide_set() { + continue; + } + if required_groups_members.contains(pos.get_id()) { + continue; + } + + let index = pos.get_index().unwrap(); + let new_len = index + 1; + if required_positionals.len() < new_len { + required_positionals.resize(new_len, None); + } + if required_positionals[index].is_some() { + if pos.is_last_set() { + let styled = required_positionals[index].take().unwrap(); + let mut new = StyledStr::new(); + let _ = write!(new, "{}--{} ", literal.render(), literal.render_reset()); + new.push_styled(&styled); + required_positionals[index] = Some(new); + } + } else { + let mut styled; + if pos.is_last_set() { + styled = StyledStr::new(); + let _ = write!(styled, "{}[--{} ", literal.render(), literal.render_reset()); + styled.push_styled(&pos.stylized(self.styles, Some(true))); + let _ = write!(styled, "{}]{}", literal.render(), literal.render_reset()); + } else { + styled = pos.stylized(self.styles, Some(false)); + } + required_positionals[index] = Some(styled); + } + if pos.is_last_set() && force_optional { + required_positionals[index] = None; + } + } + + if !force_optional { + for arg in required_opts { + styled.push_styled(&arg); + styled.push_str(" "); + } + for arg in required_groups { + styled.push_styled(&arg); + styled.push_str(" "); + } + } + for arg in required_positionals.into_iter().flatten() { + styled.push_styled(&arg); + styled.push_str(" "); + } + } + + pub(crate) fn get_required_usage_from( + &self, + incls: &[Id], + matcher: Option<&ArgMatcher>, + incl_last: bool, + ) -> Vec<StyledStr> { + debug!( + "Usage::get_required_usage_from: incls={:?}, matcher={:?}, incl_last={:?}", + incls, + matcher.is_some(), + incl_last + ); + + let required_owned; + let required = if let Some(required) = self.required { + required + } else { + required_owned = self.cmd.required_graph(); + &required_owned + }; + + let mut unrolled_reqs = Vec::new(); + for a in required.iter() { + let is_relevant = |(val, req_arg): &(ArgPredicate, Id)| -> Option<Id> { + let required = match val { + ArgPredicate::Equals(_) => { + if let Some(matcher) = matcher { + matcher.check_explicit(a, val) + } else { + false + } + } + ArgPredicate::IsPresent => true, + }; + required.then(|| req_arg.clone()) + }; + + for aa in self.cmd.unroll_arg_requires(is_relevant, a) { + // if we don't check for duplicates here this causes duplicate error messages + // see https://github.com/clap-rs/clap/issues/2770 + unrolled_reqs.push(aa); + } + // always include the required arg itself. it will not be enumerated + // by unroll_requirements_for_arg. + unrolled_reqs.push(a.clone()); + } + debug!("Usage::get_required_usage_from: unrolled_reqs={unrolled_reqs:?}"); + + let mut required_groups_members = FlatSet::new(); + let mut required_groups = FlatSet::new(); + for req in unrolled_reqs.iter().chain(incls.iter()) { + if self.cmd.find_group(req).is_some() { + let group_members = self.cmd.unroll_args_in_group(req); + let is_present = matcher + .map(|m| { + group_members + .iter() + .any(|arg| m.check_explicit(arg, &ArgPredicate::IsPresent)) + }) + .unwrap_or(false); + debug!("Usage::get_required_usage_from:iter:{req:?} group is_present={is_present}"); + if is_present { + continue; + } + + let elem = self.cmd.format_group(req); + required_groups.insert(elem); + required_groups_members.extend(group_members); + } else { + debug_assert!(self.cmd.find(req).is_some(), "`{req}` must exist"); + } + } + + let mut required_opts = FlatSet::new(); + let mut required_positionals = Vec::new(); + for req in unrolled_reqs.iter().chain(incls.iter()) { + if let Some(arg) = self.cmd.find(req) { + if required_groups_members.contains(arg.get_id()) { + continue; + } + + let is_present = matcher + .map(|m| m.check_explicit(req, &ArgPredicate::IsPresent)) + .unwrap_or(false); + debug!("Usage::get_required_usage_from:iter:{req:?} arg is_present={is_present}"); + if is_present { + continue; + } + + let stylized = arg.stylized(self.styles, Some(true)); + if let Some(index) = arg.get_index() { + if !arg.is_last_set() || incl_last { + let new_len = index + 1; + if required_positionals.len() < new_len { + required_positionals.resize(new_len, None); + } + required_positionals[index] = Some(stylized); + } + } else { + required_opts.insert(stylized); + } + } else { + debug_assert!(self.cmd.find_group(req).is_some()); + } + } + + let mut ret_val = Vec::new(); + ret_val.extend(required_opts); + ret_val.extend(required_groups); + for pos in required_positionals.into_iter().flatten() { + ret_val.push(pos); + } + + debug!("Usage::get_required_usage_from: ret_val={ret_val:?}"); + ret_val + } +} diff --git a/vendor/clap_builder/src/parser/arg_matcher.rs b/vendor/clap_builder/src/parser/arg_matcher.rs new file mode 100644 index 0000000..b8d827a --- /dev/null +++ b/vendor/clap_builder/src/parser/arg_matcher.rs @@ -0,0 +1,238 @@ +// Std +use std::ffi::OsString; +use std::mem; +use std::ops::Deref; + +// Internal +use crate::builder::{Arg, ArgPredicate, Command}; +use crate::parser::Identifier; +use crate::parser::PendingArg; +use crate::parser::{ArgMatches, MatchedArg, SubCommand, ValueSource}; +use crate::util::AnyValue; +use crate::util::FlatMap; +use crate::util::Id; +use crate::INTERNAL_ERROR_MSG; + +#[derive(Debug, Default)] +pub(crate) struct ArgMatcher { + matches: ArgMatches, + pending: Option<PendingArg>, +} + +impl ArgMatcher { + pub(crate) fn new(_cmd: &Command) -> Self { + ArgMatcher { + matches: ArgMatches { + #[cfg(debug_assertions)] + valid_args: { + let args = _cmd.get_arguments().map(|a| a.get_id().clone()); + let groups = _cmd.get_groups().map(|g| g.get_id().clone()); + args.chain(groups).collect() + }, + #[cfg(debug_assertions)] + valid_subcommands: _cmd + .get_subcommands() + .map(|sc| sc.get_name_str().clone()) + .collect(), + ..Default::default() + }, + pending: None, + } + } + + pub(crate) fn into_inner(self) -> ArgMatches { + self.matches + } + + pub(crate) fn propagate_globals(&mut self, global_arg_vec: &[Id]) { + debug!("ArgMatcher::get_global_values: global_arg_vec={global_arg_vec:?}"); + let mut vals_map = FlatMap::new(); + self.fill_in_global_values(global_arg_vec, &mut vals_map); + } + + fn fill_in_global_values( + &mut self, + global_arg_vec: &[Id], + vals_map: &mut FlatMap<Id, MatchedArg>, + ) { + for global_arg in global_arg_vec { + if let Some(ma) = self.get(global_arg) { + // We have to check if the parent's global arg wasn't used but still exists + // such as from a default value. + // + // For example, `myprog subcommand --global-arg=value` where `--global-arg` defines + // a default value of `other` myprog would have an existing MatchedArg for + // `--global-arg` where the value is `other` + let to_update = if let Some(parent_ma) = vals_map.get(global_arg) { + if parent_ma.source() > ma.source() { + parent_ma + } else { + ma + } + } else { + ma + } + .clone(); + vals_map.insert(global_arg.clone(), to_update); + } + } + if let Some(ref mut sc) = self.matches.subcommand { + let mut am = ArgMatcher { + matches: mem::take(&mut sc.matches), + pending: None, + }; + am.fill_in_global_values(global_arg_vec, vals_map); + mem::swap(&mut am.matches, &mut sc.matches); + } + + for (name, matched_arg) in vals_map.iter_mut() { + self.matches.args.insert(name.clone(), matched_arg.clone()); + } + } + + pub(crate) fn get(&self, arg: &Id) -> Option<&MatchedArg> { + self.matches.args.get(arg) + } + + pub(crate) fn get_mut(&mut self, arg: &Id) -> Option<&mut MatchedArg> { + self.matches.args.get_mut(arg) + } + + pub(crate) fn remove(&mut self, arg: &Id) -> bool { + self.matches.args.remove(arg).is_some() + } + + pub(crate) fn contains(&self, arg: &Id) -> bool { + self.matches.args.contains_key(arg) + } + + pub(crate) fn arg_ids(&self) -> std::slice::Iter<'_, Id> { + self.matches.args.keys() + } + + pub(crate) fn args(&self) -> crate::util::flat_map::Iter<'_, Id, MatchedArg> { + self.matches.args.iter() + } + + pub(crate) fn entry(&mut self, arg: Id) -> crate::util::Entry<Id, MatchedArg> { + self.matches.args.entry(arg) + } + + pub(crate) fn subcommand(&mut self, sc: SubCommand) { + self.matches.subcommand = Some(Box::new(sc)); + } + + pub(crate) fn subcommand_name(&self) -> Option<&str> { + self.matches.subcommand_name() + } + + pub(crate) fn check_explicit(&self, arg: &Id, predicate: &ArgPredicate) -> bool { + self.get(arg) + .map(|a| a.check_explicit(predicate)) + .unwrap_or_default() + } + + pub(crate) fn start_custom_arg(&mut self, arg: &Arg, source: ValueSource) { + let id = arg.get_id().clone(); + debug!("ArgMatcher::start_custom_arg: id={id:?}, source={source:?}"); + let ma = self.entry(id).or_insert(MatchedArg::new_arg(arg)); + debug_assert_eq!(ma.type_id(), Some(arg.get_value_parser().type_id())); + ma.set_source(source); + ma.new_val_group(); + } + + pub(crate) fn start_custom_group(&mut self, id: Id, source: ValueSource) { + debug!("ArgMatcher::start_custom_arg: id={id:?}, source={source:?}"); + let ma = self.entry(id).or_insert(MatchedArg::new_group()); + debug_assert_eq!(ma.type_id(), None); + ma.set_source(source); + ma.new_val_group(); + } + + pub(crate) fn start_occurrence_of_external(&mut self, cmd: &crate::Command) { + let id = Id::from_static_ref(Id::EXTERNAL); + debug!("ArgMatcher::start_occurrence_of_external: id={id:?}"); + let ma = self.entry(id).or_insert(MatchedArg::new_external(cmd)); + debug_assert_eq!( + ma.type_id(), + Some( + cmd.get_external_subcommand_value_parser() + .expect(INTERNAL_ERROR_MSG) + .type_id() + ) + ); + ma.set_source(ValueSource::CommandLine); + ma.new_val_group(); + } + + pub(crate) fn add_val_to(&mut self, arg: &Id, val: AnyValue, raw_val: OsString) { + let ma = self.get_mut(arg).expect(INTERNAL_ERROR_MSG); + ma.append_val(val, raw_val); + } + + pub(crate) fn add_index_to(&mut self, arg: &Id, idx: usize) { + let ma = self.get_mut(arg).expect(INTERNAL_ERROR_MSG); + ma.push_index(idx); + } + + pub(crate) fn needs_more_vals(&self, o: &Arg) -> bool { + let num_pending = self + .pending + .as_ref() + .and_then(|p| (p.id == *o.get_id()).then_some(p.raw_vals.len())) + .unwrap_or(0); + debug!( + "ArgMatcher::needs_more_vals: o={}, pending={}", + o.get_id(), + num_pending + ); + let expected = o.get_num_args().expect(INTERNAL_ERROR_MSG); + debug!("ArgMatcher::needs_more_vals: expected={expected}, actual={num_pending}"); + expected.accepts_more(num_pending) + } + + pub(crate) fn pending_arg_id(&self) -> Option<&Id> { + self.pending.as_ref().map(|p| &p.id) + } + + pub(crate) fn pending_values_mut( + &mut self, + id: &Id, + ident: Option<Identifier>, + trailing_values: bool, + ) -> &mut Vec<OsString> { + let pending = self.pending.get_or_insert_with(|| PendingArg { + id: id.clone(), + ident, + raw_vals: Default::default(), + trailing_idx: None, + }); + debug_assert_eq!(pending.id, *id, "{INTERNAL_ERROR_MSG}"); + if ident.is_some() { + debug_assert_eq!(pending.ident, ident, "{INTERNAL_ERROR_MSG}"); + } + if trailing_values { + pending.trailing_idx.get_or_insert(pending.raw_vals.len()); + } + &mut pending.raw_vals + } + + pub(crate) fn start_trailing(&mut self) { + if let Some(pending) = &mut self.pending { + // Allow asserting its started on subsequent calls + pending.trailing_idx.get_or_insert(pending.raw_vals.len()); + } + } + + pub(crate) fn take_pending(&mut self) -> Option<PendingArg> { + self.pending.take() + } +} + +impl Deref for ArgMatcher { + type Target = ArgMatches; + + fn deref(&self) -> &Self::Target { + &self.matches + } +} diff --git a/vendor/clap_builder/src/parser/error.rs b/vendor/clap_builder/src/parser/error.rs new file mode 100644 index 0000000..77b0bb0 --- /dev/null +++ b/vendor/clap_builder/src/parser/error.rs @@ -0,0 +1,63 @@ +use crate::util::AnyValueId; + +/// Violation of [`ArgMatches`][crate::ArgMatches] assumptions +#[derive(Clone, Debug)] +#[allow(missing_copy_implementations)] // We might add non-Copy types in the future +#[non_exhaustive] +pub enum MatchesError { + /// Failed to downcast `AnyValue` to the specified type + #[non_exhaustive] + Downcast { + /// Type for value stored in [`ArgMatches`][crate::ArgMatches] + actual: AnyValueId, + /// The target type to downcast to + expected: AnyValueId, + }, + /// Argument not defined in [`Command`][crate::Command] + #[non_exhaustive] + UnknownArgument { + // Missing `id` but blocked on a public id type which will hopefully come with `unstable-v4` + }, +} + +impl MatchesError { + #[cfg_attr(debug_assertions, track_caller)] + pub(crate) fn unwrap<T>(id: &str, r: Result<T, MatchesError>) -> T { + let err = match r { + Ok(t) => { + return t; + } + Err(err) => err, + }; + panic!("Mismatch between definition and access of `{id}`. {err}",) + } +} + +impl std::error::Error for MatchesError {} + +impl std::fmt::Display for MatchesError { + fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result { + match self { + Self::Downcast { actual, expected } => { + writeln!( + f, + "Could not downcast to {expected:?}, need to downcast to {actual:?}" + ) + } + Self::UnknownArgument {} => { + writeln!(f, "Unknown argument or group id. Make sure you are using the argument id and not the short or long flags") + } + } + } +} + +#[test] +fn check_auto_traits() { + static_assertions::assert_impl_all!( + MatchesError: Send, + Sync, + std::panic::RefUnwindSafe, + std::panic::UnwindSafe, + Unpin + ); +} diff --git a/vendor/clap_builder/src/parser/features/mod.rs b/vendor/clap_builder/src/parser/features/mod.rs new file mode 100644 index 0000000..bdeb766 --- /dev/null +++ b/vendor/clap_builder/src/parser/features/mod.rs @@ -0,0 +1 @@ +pub(crate) mod suggestions; diff --git a/vendor/clap_builder/src/parser/features/suggestions.rs b/vendor/clap_builder/src/parser/features/suggestions.rs new file mode 100644 index 0000000..b8bb7ad --- /dev/null +++ b/vendor/clap_builder/src/parser/features/suggestions.rs @@ -0,0 +1,167 @@ +#[cfg(feature = "suggestions")] +use std::cmp::Ordering; + +// Internal +use crate::builder::Command; + +/// Find strings from an iterable of `possible_values` similar to a given value `v` +/// Returns a Vec of all possible values that exceed a similarity threshold +/// sorted by ascending similarity, most similar comes last +#[cfg(feature = "suggestions")] +pub(crate) fn did_you_mean<T, I>(v: &str, possible_values: I) -> Vec<String> +where + T: AsRef<str>, + I: IntoIterator<Item = T>, +{ + let mut candidates: Vec<(f64, String)> = possible_values + .into_iter() + // GH #4660: using `jaro` because `jaro_winkler` implementation in `strsim-rs` is wrong + // causing strings with common prefix >=10 to be considered perfectly similar + .map(|pv| (strsim::jaro(v, pv.as_ref()), pv.as_ref().to_owned())) + // Confidence of 0.7 so that bar -> baz is suggested + .filter(|(confidence, _)| *confidence > 0.7) + .collect(); + candidates.sort_by(|a, b| a.0.partial_cmp(&b.0).unwrap_or(Ordering::Equal)); + candidates.into_iter().map(|(_, pv)| pv).collect() +} + +#[cfg(not(feature = "suggestions"))] +pub(crate) fn did_you_mean<T, I>(_: &str, _: I) -> Vec<String> +where + T: AsRef<str>, + I: IntoIterator<Item = T>, +{ + Vec::new() +} + +/// Returns a suffix that can be empty, or is the standard 'did you mean' phrase +pub(crate) fn did_you_mean_flag<'a, 'help, I, T>( + arg: &str, + remaining_args: &[&std::ffi::OsStr], + longs: I, + subcommands: impl IntoIterator<Item = &'a mut Command>, +) -> Option<(String, Option<String>)> +where + 'help: 'a, + T: AsRef<str>, + I: IntoIterator<Item = T>, +{ + use crate::mkeymap::KeyType; + + match did_you_mean(arg, longs).pop() { + Some(candidate) => Some((candidate, None)), + None => subcommands + .into_iter() + .filter_map(|subcommand| { + subcommand._build_self(false); + + let longs = subcommand.get_keymap().keys().filter_map(|a| { + if let KeyType::Long(v) = a { + Some(v.to_string_lossy().into_owned()) + } else { + None + } + }); + + let subcommand_name = subcommand.get_name(); + + let candidate = some!(did_you_mean(arg, longs).pop()); + let score = some!(remaining_args.iter().position(|x| subcommand_name == *x)); + Some((score, (candidate, Some(subcommand_name.to_string())))) + }) + .min_by_key(|(x, _)| *x) + .map(|(_, suggestion)| suggestion), + } +} + +#[cfg(all(test, feature = "suggestions"))] +mod test { + use super::*; + + #[test] + fn missing_letter() { + let p_vals = ["test", "possible", "values"]; + assert_eq!(did_you_mean("tst", p_vals.iter()), vec!["test"]); + } + + #[test] + fn ambiguous() { + let p_vals = ["test", "temp", "possible", "values"]; + assert_eq!(did_you_mean("te", p_vals.iter()), vec!["test", "temp"]); + } + + #[test] + fn unrelated() { + let p_vals = ["test", "possible", "values"]; + assert_eq!( + did_you_mean("hahaahahah", p_vals.iter()), + Vec::<String>::new() + ); + } + + #[test] + fn best_fit() { + let p_vals = [ + "test", + "possible", + "values", + "alignmentStart", + "alignmentScore", + ]; + assert_eq!( + did_you_mean("alignmentScorr", p_vals.iter()), + vec!["alignmentStart", "alignmentScore"] + ); + } + + #[test] + fn best_fit_long_common_prefix_issue_4660() { + let p_vals = ["alignmentScore", "alignmentStart"]; + assert_eq!( + did_you_mean("alignmentScorr", p_vals.iter()), + vec!["alignmentStart", "alignmentScore"] + ); + } + + #[test] + fn flag_missing_letter() { + let p_vals = ["test", "possible", "values"]; + assert_eq!( + did_you_mean_flag("tst", &[], p_vals.iter(), []), + Some(("test".to_owned(), None)) + ); + } + + #[test] + fn flag_ambiguous() { + let p_vals = ["test", "temp", "possible", "values"]; + assert_eq!( + did_you_mean_flag("te", &[], p_vals.iter(), []), + Some(("temp".to_owned(), None)) + ); + } + + #[test] + fn flag_unrelated() { + let p_vals = ["test", "possible", "values"]; + assert_eq!( + did_you_mean_flag("hahaahahah", &[], p_vals.iter(), []), + None + ); + } + + #[test] + fn flag_best_fit() { + let p_vals = [ + "test", + "possible", + "values", + "alignmentStart", + "alignmentScore", + ]; + assert_eq!( + did_you_mean_flag("alignmentScorr", &[], p_vals.iter(), []), + Some(("alignmentScore".to_owned(), None)) + ); + } +} diff --git a/vendor/clap_builder/src/parser/matches/arg_matches.rs b/vendor/clap_builder/src/parser/matches/arg_matches.rs new file mode 100644 index 0000000..e80c39b --- /dev/null +++ b/vendor/clap_builder/src/parser/matches/arg_matches.rs @@ -0,0 +1,2030 @@ +// Std +use std::any::Any; +use std::ffi::{OsStr, OsString}; +use std::fmt::Debug; +use std::iter::{Cloned, Flatten, Map}; +use std::slice::Iter; + +// Internal +#[cfg(debug_assertions)] +use crate::builder::Str; +use crate::parser::MatchedArg; +use crate::parser::MatchesError; +use crate::parser::ValueSource; +use crate::util::AnyValue; +use crate::util::AnyValueId; +use crate::util::FlatMap; +use crate::util::Id; +use crate::INTERNAL_ERROR_MSG; + +/// Container for parse results. +/// +/// Used to get information about the arguments that were supplied to the program at runtime by +/// the user. New instances of this struct are obtained by using the [`Command::get_matches`] family of +/// methods. +/// +/// # Examples +/// +/// ```no_run +/// # use clap_builder as clap; +/// # use clap::{Command, Arg, ArgAction}; +/// # use clap::parser::ValueSource; +/// let matches = Command::new("MyApp") +/// .arg(Arg::new("out") +/// .long("output") +/// .required(true) +/// .action(ArgAction::Set) +/// .default_value("-")) +/// .arg(Arg::new("cfg") +/// .short('c') +/// .action(ArgAction::Set)) +/// .get_matches(); // builds the instance of ArgMatches +/// +/// // to get information about the "cfg" argument we created, such as the value supplied we use +/// // various ArgMatches methods, such as [ArgMatches::get_one] +/// if let Some(c) = matches.get_one::<String>("cfg") { +/// println!("Value for -c: {c}"); +/// } +/// +/// // The ArgMatches::get_one method returns an Option because the user may not have supplied +/// // that argument at runtime. But if we specified that the argument was "required" as we did +/// // with the "out" argument, we can safely unwrap because `clap` verifies that was actually +/// // used at runtime. +/// println!("Value for --output: {}", matches.get_one::<String>("out").unwrap()); +/// +/// // You can check the presence of an argument's values +/// if matches.contains_id("out") { +/// // However, if you want to know where the value came from +/// if matches.value_source("out").expect("checked contains_id") == ValueSource::CommandLine { +/// println!("`out` set by user"); +/// } else { +/// println!("`out` is defaulted"); +/// } +/// } +/// ``` +/// [`Command::get_matches`]: crate::Command::get_matches() +#[derive(Debug, Clone, Default, PartialEq, Eq)] +pub struct ArgMatches { + #[cfg(debug_assertions)] + pub(crate) valid_args: Vec<Id>, + #[cfg(debug_assertions)] + pub(crate) valid_subcommands: Vec<Str>, + pub(crate) args: FlatMap<Id, MatchedArg>, + pub(crate) subcommand: Option<Box<SubCommand>>, +} + +/// # Arguments +impl ArgMatches { + /// Gets the value of a specific option or positional argument. + /// + /// i.e. an argument that [takes an additional value][crate::Arg::num_args] at runtime. + /// + /// Returns an error if the wrong type was used. + /// + /// Returns `None` if the option wasn't present. + /// + /// *NOTE:* This will always return `Some(value)` if [`default_value`] has been set. + /// [`ArgMatches::value_source`] can be used to check if a value is present at runtime. + /// + /// # Panic + /// + /// If the argument definition and access mismatch. To handle this case programmatically, see + /// [`ArgMatches::try_get_one`]. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, value_parser, ArgAction}; + /// let m = Command::new("myapp") + /// .arg(Arg::new("port") + /// .value_parser(value_parser!(usize)) + /// .action(ArgAction::Set) + /// .required(true)) + /// .get_matches_from(vec!["myapp", "2020"]); + /// + /// let port: usize = *m + /// .get_one("port") + /// .expect("`port`is required"); + /// assert_eq!(port, 2020); + /// ``` + /// [positional]: crate::Arg::index() + /// [`default_value`]: crate::Arg::default_value() + #[cfg_attr(debug_assertions, track_caller)] + pub fn get_one<T: Any + Clone + Send + Sync + 'static>(&self, id: &str) -> Option<&T> { + MatchesError::unwrap(id, self.try_get_one(id)) + } + + /// Gets the value of a specific [`ArgAction::Count`][crate::ArgAction::Count] flag + /// + /// # Panic + /// + /// If the argument's action is not [`ArgAction::Count`][crate::ArgAction::Count] + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::Command; + /// # use clap::Arg; + /// let cmd = Command::new("mycmd") + /// .arg( + /// Arg::new("flag") + /// .long("flag") + /// .action(clap::ArgAction::Count) + /// ); + /// + /// let matches = cmd.clone().try_get_matches_from(["mycmd", "--flag", "--flag"]).unwrap(); + /// assert_eq!( + /// matches.get_count("flag"), + /// 2 + /// ); + /// ``` + #[cfg_attr(debug_assertions, track_caller)] + pub fn get_count(&self, id: &str) -> u8 { + *self.get_one::<u8>(id).unwrap_or_else(|| { + panic!("arg `{id}`'s `ArgAction` should be `Count` which should provide a default") + }) + } + + /// Gets the value of a specific [`ArgAction::SetTrue`][crate::ArgAction::SetTrue] or [`ArgAction::SetFalse`][crate::ArgAction::SetFalse] flag + /// + /// # Panic + /// + /// If the argument's action is not [`ArgAction::SetTrue`][crate::ArgAction::SetTrue] or [`ArgAction::SetFalse`][crate::ArgAction::SetFalse] + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::Command; + /// # use clap::Arg; + /// let cmd = Command::new("mycmd") + /// .arg( + /// Arg::new("flag") + /// .long("flag") + /// .action(clap::ArgAction::SetTrue) + /// ); + /// + /// let matches = cmd.clone().try_get_matches_from(["mycmd", "--flag"]).unwrap(); + /// assert!(matches.contains_id("flag")); + /// assert_eq!( + /// matches.get_flag("flag"), + /// true + /// ); + /// ``` + #[cfg_attr(debug_assertions, track_caller)] + pub fn get_flag(&self, id: &str) -> bool { + *self + .get_one::<bool>(id) + .unwrap_or_else(|| { + panic!( + "arg `{id}`'s `ArgAction` should be one of `SetTrue`, `SetFalse` which should provide a default" + ) + }) + } + + /// Iterate over values of a specific option or positional argument. + /// + /// i.e. an argument that takes multiple values at runtime. + /// + /// Returns an error if the wrong type was used. + /// + /// Returns `None` if the option wasn't present. + /// + /// # Panic + /// + /// If the argument definition and access mismatch. To handle this case programmatically, see + /// [`ArgMatches::try_get_many`]. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, value_parser, ArgAction}; + /// let m = Command::new("myprog") + /// .arg(Arg::new("ports") + /// .action(ArgAction::Append) + /// .value_parser(value_parser!(usize)) + /// .short('p') + /// .required(true)) + /// .get_matches_from(vec![ + /// "myprog", "-p", "22", "-p", "80", "-p", "2020" + /// ]); + /// let vals: Vec<usize> = m.get_many("ports") + /// .expect("`port`is required") + /// .copied() + /// .collect(); + /// assert_eq!(vals, [22, 80, 2020]); + /// ``` + #[cfg_attr(debug_assertions, track_caller)] + pub fn get_many<T: Any + Clone + Send + Sync + 'static>( + &self, + id: &str, + ) -> Option<ValuesRef<T>> { + MatchesError::unwrap(id, self.try_get_many(id)) + } + + /// Iterate over the values passed to each occurrence of an option. + /// + /// Each item is itself an iterator containing the arguments passed to a single occurrence + /// of the option. + /// + /// If the option doesn't support multiple occurrences, or there was only a single occurrence, + /// the iterator will only contain a single item. + /// + /// Returns `None` if the option wasn't present. + /// + /// # Panics + /// + /// If the argument definition and access mismatch (debug builds). To handle this case programmatically, see + /// [`ArgMatches::try_get_occurrences`]. + /// + /// # Examples + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command,Arg, ArgAction, value_parser}; + /// let m = Command::new("myprog") + /// .arg(Arg::new("x") + /// .short('x') + /// .num_args(2) + /// .action(ArgAction::Append) + /// .value_parser(value_parser!(String))) + /// .get_matches_from(vec![ + /// "myprog", "-x", "a", "b", "-x", "c", "d"]); + /// let vals: Vec<Vec<&String>> = m.get_occurrences("x").unwrap().map(Iterator::collect).collect(); + /// assert_eq!(vals, [["a", "b"], ["c", "d"]]); + /// ``` + #[cfg_attr(debug_assertions, track_caller)] + pub fn get_occurrences<T: Any + Clone + Send + Sync + 'static>( + &self, + id: &str, + ) -> Option<OccurrencesRef<T>> { + MatchesError::unwrap(id, self.try_get_occurrences(id)) + } + + /// Iterate over the original argument values. + /// + /// An `OsStr` on Unix-like systems is any series of bytes, regardless of whether or not they + /// contain valid UTF-8. Since [`String`]s in Rust are guaranteed to be valid UTF-8, a valid + /// filename on a Unix system as an argument value may contain invalid UTF-8. + /// + /// Returns `None` if the option wasn't present. + /// + /// # Panic + /// + /// If the argument definition and access mismatch. To handle this case programmatically, see + /// [`ArgMatches::try_get_raw`]. + /// + /// # Examples + /// + /// ```rust + /// # #[cfg(unix)] { + /// # use clap_builder as clap; + /// # use clap::{Command, arg, value_parser}; + /// # use std::ffi::{OsStr,OsString}; + /// # use std::os::unix::ffi::{OsStrExt,OsStringExt}; + /// use std::path::PathBuf; + /// + /// let m = Command::new("utf8") + /// .arg(arg!(<arg> ... "some arg").value_parser(value_parser!(PathBuf))) + /// .get_matches_from(vec![OsString::from("myprog"), + /// // "Hi" + /// OsString::from_vec(vec![b'H', b'i']), + /// // "{0xe9}!" + /// OsString::from_vec(vec![0xe9, b'!'])]); + /// + /// let mut itr = m.get_raw("arg") + /// .expect("`port`is required") + /// .into_iter(); + /// assert_eq!(itr.next(), Some(OsStr::new("Hi"))); + /// assert_eq!(itr.next(), Some(OsStr::from_bytes(&[0xe9, b'!']))); + /// assert_eq!(itr.next(), None); + /// # } + /// ``` + /// [`Iterator`]: std::iter::Iterator + /// [`OsSt`]: std::ffi::OsStr + /// [values]: OsValues + /// [`String`]: std::string::String + #[cfg_attr(debug_assertions, track_caller)] + pub fn get_raw(&self, id: &str) -> Option<RawValues<'_>> { + MatchesError::unwrap(id, self.try_get_raw(id)) + } + + /// Iterate over the original values for each occurrence of an option. + /// + /// Similar to [`ArgMatches::get_occurrences`] but returns raw values. + /// + /// An `OsStr` on Unix-like systems is any series of bytes, regardless of whether or not they + /// contain valid UTF-8. Since [`String`]s in Rust are guaranteed to be valid UTF-8, a valid + /// filename on a Unix system as an argument value may contain invalid UTF-8. + /// + /// Returns `None` if the option wasn't present. + /// + /// # Panic + /// + /// If the argument definition and access mismatch. To handle this case programmatically, see + /// [`ArgMatches::try_get_raw_occurrences`]. + /// + /// # Examples + /// + /// ```rust + /// # #[cfg(unix)] { + /// # use clap_builder as clap; + /// # use clap::{Command, arg, value_parser, ArgAction, Arg}; + /// # use std::ffi::{OsStr,OsString}; + /// # use std::os::unix::ffi::{OsStrExt,OsStringExt}; + /// use std::path::PathBuf; + /// + /// let m = Command::new("myprog") + /// .arg(Arg::new("x") + /// .short('x') + /// .num_args(2) + /// .action(ArgAction::Append) + /// .value_parser(value_parser!(PathBuf))) + /// .get_matches_from(vec![OsString::from("myprog"), + /// OsString::from("-x"), + /// OsString::from("a"), OsString::from("b"), + /// OsString::from("-x"), + /// OsString::from("c"), + /// // "{0xe9}!" + /// OsString::from_vec(vec![0xe9, b'!'])]); + /// let mut itr = m.get_raw_occurrences("x") + /// .expect("`-x`is required") + /// .map(Iterator::collect::<Vec<_>>); + /// assert_eq!(itr.next(), Some(vec![OsStr::new("a"), OsStr::new("b")])); + /// assert_eq!(itr.next(), Some(vec![OsStr::new("c"), OsStr::from_bytes(&[0xe9, b'!'])])); + /// assert_eq!(itr.next(), None); + /// # } + /// ``` + /// [`Iterator`]: std::iter::Iterator + /// [`OsStr`]: std::ffi::OsStr + /// [values]: OsValues + /// [`String`]: std::string::String + #[cfg_attr(debug_assertions, track_caller)] + pub fn get_raw_occurrences(&self, id: &str) -> Option<RawOccurrences<'_>> { + MatchesError::unwrap(id, self.try_get_raw_occurrences(id)) + } + + /// Returns the value of a specific option or positional argument. + /// + /// i.e. an argument that [takes an additional value][crate::Arg::num_args] at runtime. + /// + /// Returns an error if the wrong type was used. No item will have been removed. + /// + /// Returns `None` if the option wasn't present. + /// + /// *NOTE:* This will always return `Some(value)` if [`default_value`] has been set. + /// [`ArgMatches::value_source`] can be used to check if a value is present at runtime. + /// + /// # Panic + /// + /// If the argument definition and access mismatch. To handle this case programmatically, see + /// [`ArgMatches::try_remove_one`]. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, value_parser, ArgAction}; + /// let mut m = Command::new("myprog") + /// .arg(Arg::new("file") + /// .required(true) + /// .action(ArgAction::Set)) + /// .get_matches_from(vec![ + /// "myprog", "file.txt", + /// ]); + /// let vals: String = m.remove_one("file") + /// .expect("`file`is required"); + /// assert_eq!(vals, "file.txt"); + /// ``` + /// [positional]: crate::Arg::index() + /// [`default_value`]: crate::Arg::default_value() + #[cfg_attr(debug_assertions, track_caller)] + pub fn remove_one<T: Any + Clone + Send + Sync + 'static>(&mut self, id: &str) -> Option<T> { + MatchesError::unwrap(id, self.try_remove_one(id)) + } + + /// Return values of a specific option or positional argument. + /// + /// i.e. an argument that takes multiple values at runtime. + /// + /// Returns an error if the wrong type was used. No item will have been removed. + /// + /// Returns `None` if the option wasn't present. + /// + /// # Panic + /// + /// If the argument definition and access mismatch. To handle this case programmatically, see + /// [`ArgMatches::try_remove_many`]. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, value_parser, ArgAction}; + /// let mut m = Command::new("myprog") + /// .arg(Arg::new("file") + /// .action(ArgAction::Append) + /// .num_args(1..) + /// .required(true)) + /// .get_matches_from(vec![ + /// "myprog", "file1.txt", "file2.txt", "file3.txt", "file4.txt", + /// ]); + /// let vals: Vec<String> = m.remove_many("file") + /// .expect("`file`is required") + /// .collect(); + /// assert_eq!(vals, ["file1.txt", "file2.txt", "file3.txt", "file4.txt"]); + /// ``` + #[cfg_attr(debug_assertions, track_caller)] + pub fn remove_many<T: Any + Clone + Send + Sync + 'static>( + &mut self, + id: &str, + ) -> Option<Values<T>> { + MatchesError::unwrap(id, self.try_remove_many(id)) + } + + /// Return values for each occurrence of an option. + /// + /// Each item is itself an iterator containing the arguments passed to a single occurrence of + /// the option. + /// + /// If the option doesn't support multiple occurrences, or there was only a single occurrence, + /// the iterator will only contain a single item. + /// + /// Returns `None` if the option wasn't present. + /// + /// # Panic + /// + /// If the argument definition and access mismatch. To handle this case programmatically, see + /// [`ArgMatches::try_remove_occurrences`]. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, value_parser, ArgAction}; + /// let mut m = Command::new("myprog") + /// .arg(Arg::new("x") + /// .short('x') + /// .num_args(2) + /// .action(ArgAction::Append) + /// .value_parser(value_parser!(String))) + /// .get_matches_from(vec![ + /// "myprog", "-x", "a", "b", "-x", "c", "d"]); + /// let vals: Vec<Vec<String>> = m.remove_occurrences("x").unwrap().map(Iterator::collect).collect(); + /// assert_eq!(vals, [["a", "b"], ["c", "d"]]); + /// ``` + #[cfg_attr(debug_assertions, track_caller)] + pub fn remove_occurrences<T: Any + Clone + Send + Sync + 'static>( + &mut self, + id: &str, + ) -> Option<Occurrences<T>> { + MatchesError::unwrap(id, self.try_remove_occurrences(id)) + } + + /// Check if values are present for the argument or group id + /// + /// *NOTE:* This will always return `true` if [`default_value`] has been set. + /// [`ArgMatches::value_source`] can be used to check if a value is present at runtime. + /// + /// # Panics + /// + /// If `id` is not a valid argument or group name (debug builds). To handle this case programmatically, see + /// [`ArgMatches::try_contains_id`]. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// let m = Command::new("myprog") + /// .arg(Arg::new("debug") + /// .short('d') + /// .action(ArgAction::SetTrue)) + /// .get_matches_from(vec![ + /// "myprog", "-d" + /// ]); + /// + /// assert!(m.contains_id("debug")); + /// ``` + /// + /// [`default_value`]: crate::Arg::default_value() + pub fn contains_id(&self, id: &str) -> bool { + MatchesError::unwrap(id, self.try_contains_id(id)) + } + + /// Iterate over [`Arg`][crate::Arg] and [`ArgGroup`][crate::ArgGroup] [`Id`]s via [`ArgMatches::ids`]. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, arg, value_parser}; + /// + /// let m = Command::new("myprog") + /// .arg(arg!(--color <when>) + /// .value_parser(["auto", "always", "never"])) + /// .arg(arg!(--config <path>) + /// .value_parser(value_parser!(std::path::PathBuf))) + /// .get_matches_from(["myprog", "--config=config.toml", "--color=auto"]); + /// assert_eq!(m.ids().len(), 2); + /// assert_eq!( + /// m.ids() + /// .map(|id| id.as_str()) + /// .collect::<Vec<_>>(), + /// ["config", "color"] + /// ); + /// ``` + pub fn ids(&self) -> IdsRef<'_> { + IdsRef { + iter: self.args.keys(), + } + } + + /// Check if any args were present on the command line + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// let mut cmd = Command::new("myapp") + /// .arg(Arg::new("output") + /// .action(ArgAction::Set)); + /// + /// let m = cmd + /// .try_get_matches_from_mut(vec!["myapp", "something"]) + /// .unwrap(); + /// assert!(m.args_present()); + /// + /// let m = cmd + /// .try_get_matches_from_mut(vec!["myapp"]) + /// .unwrap(); + /// assert!(! m.args_present()); + pub fn args_present(&self) -> bool { + !self.args.is_empty() + } + + /// Report where argument value came from + /// + /// # Panics + /// + /// If `id` is not a valid argument or group id (debug builds). + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// # use clap::parser::ValueSource; + /// let m = Command::new("myprog") + /// .arg(Arg::new("debug") + /// .short('d') + /// .action(ArgAction::SetTrue)) + /// .get_matches_from(vec![ + /// "myprog", "-d" + /// ]); + /// + /// assert_eq!(m.value_source("debug"), Some(ValueSource::CommandLine)); + /// ``` + /// + /// [`default_value`]: crate::Arg::default_value() + #[cfg_attr(debug_assertions, track_caller)] + pub fn value_source(&self, id: &str) -> Option<ValueSource> { + let value = self.get_arg(id); + + value.and_then(MatchedArg::source) + } + + /// The first index of that an argument showed up. + /// + /// Indices are similar to argv indices, but are not exactly 1:1. + /// + /// For flags (i.e. those arguments which don't have an associated value), indices refer + /// to occurrence of the switch, such as `-f`, or `--flag`. However, for options the indices + /// refer to the *values* `-o val` would therefore not represent two distinct indices, only the + /// index for `val` would be recorded. This is by design. + /// + /// Besides the flag/option discrepancy, the primary difference between an argv index and clap + /// index, is that clap continues counting once all arguments have properly separated, whereas + /// an argv index does not. + /// + /// The examples should clear this up. + /// + /// *NOTE:* If an argument is allowed multiple times, this method will only give the *first* + /// index. See [`ArgMatches::indices_of`]. + /// + /// # Panics + /// + /// If `id` is not a valid argument or group id (debug builds). + /// + /// # Examples + /// + /// The argv indices are listed in the comments below. See how they correspond to the clap + /// indices. Note that if it's not listed in a clap index, this is because it's not saved in + /// in an `ArgMatches` struct for querying. + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// let m = Command::new("myapp") + /// .arg(Arg::new("flag") + /// .short('f') + /// .action(ArgAction::SetTrue)) + /// .arg(Arg::new("option") + /// .short('o') + /// .action(ArgAction::Set)) + /// .get_matches_from(vec!["myapp", "-f", "-o", "val"]); + /// // ARGV indices: ^0 ^1 ^2 ^3 + /// // clap indices: ^1 ^3 + /// + /// assert_eq!(m.index_of("flag"), Some(1)); + /// assert_eq!(m.index_of("option"), Some(3)); + /// ``` + /// + /// Now notice, if we use one of the other styles of options: + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// let m = Command::new("myapp") + /// .arg(Arg::new("flag") + /// .short('f') + /// .action(ArgAction::SetTrue)) + /// .arg(Arg::new("option") + /// .short('o') + /// .action(ArgAction::Set)) + /// .get_matches_from(vec!["myapp", "-f", "-o=val"]); + /// // ARGV indices: ^0 ^1 ^2 + /// // clap indices: ^1 ^3 + /// + /// assert_eq!(m.index_of("flag"), Some(1)); + /// assert_eq!(m.index_of("option"), Some(3)); + /// ``` + /// + /// Things become much more complicated, or clear if we look at a more complex combination of + /// flags. Let's also throw in the final option style for good measure. + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// let m = Command::new("myapp") + /// .arg(Arg::new("flag") + /// .short('f') + /// .action(ArgAction::SetTrue)) + /// .arg(Arg::new("flag2") + /// .short('F') + /// .action(ArgAction::SetTrue)) + /// .arg(Arg::new("flag3") + /// .short('z') + /// .action(ArgAction::SetTrue)) + /// .arg(Arg::new("option") + /// .short('o') + /// .action(ArgAction::Set)) + /// .get_matches_from(vec!["myapp", "-fzF", "-oval"]); + /// // ARGV indices: ^0 ^1 ^2 + /// // clap indices: ^1,2,3 ^5 + /// // + /// // clap sees the above as 'myapp -f -z -F -o val' + /// // ^0 ^1 ^2 ^3 ^4 ^5 + /// assert_eq!(m.index_of("flag"), Some(1)); + /// assert_eq!(m.index_of("flag2"), Some(3)); + /// assert_eq!(m.index_of("flag3"), Some(2)); + /// assert_eq!(m.index_of("option"), Some(5)); + /// ``` + /// + /// One final combination of flags/options to see how they combine: + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// let m = Command::new("myapp") + /// .arg(Arg::new("flag") + /// .short('f') + /// .action(ArgAction::SetTrue)) + /// .arg(Arg::new("flag2") + /// .short('F') + /// .action(ArgAction::SetTrue)) + /// .arg(Arg::new("flag3") + /// .short('z') + /// .action(ArgAction::SetTrue)) + /// .arg(Arg::new("option") + /// .short('o') + /// .action(ArgAction::Set)) + /// .get_matches_from(vec!["myapp", "-fzFoval"]); + /// // ARGV indices: ^0 ^1 + /// // clap indices: ^1,2,3^5 + /// // + /// // clap sees the above as 'myapp -f -z -F -o val' + /// // ^0 ^1 ^2 ^3 ^4 ^5 + /// assert_eq!(m.index_of("flag"), Some(1)); + /// assert_eq!(m.index_of("flag2"), Some(3)); + /// assert_eq!(m.index_of("flag3"), Some(2)); + /// assert_eq!(m.index_of("option"), Some(5)); + /// ``` + /// + /// The last part to mention is when values are sent in multiple groups with a [delimiter]. + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg}; + /// let m = Command::new("myapp") + /// .arg(Arg::new("option") + /// .short('o') + /// .value_delimiter(',') + /// .num_args(1..)) + /// .get_matches_from(vec!["myapp", "-o=val1,val2,val3"]); + /// // ARGV indices: ^0 ^1 + /// // clap indices: ^2 ^3 ^4 + /// // + /// // clap sees the above as 'myapp -o val1 val2 val3' + /// // ^0 ^1 ^2 ^3 ^4 + /// assert_eq!(m.index_of("option"), Some(2)); + /// assert_eq!(m.indices_of("option").unwrap().collect::<Vec<_>>(), &[2, 3, 4]); + /// ``` + /// [delimiter]: crate::Arg::value_delimiter() + #[cfg_attr(debug_assertions, track_caller)] + pub fn index_of(&self, id: &str) -> Option<usize> { + let arg = some!(self.get_arg(id)); + let i = some!(arg.get_index(0)); + Some(i) + } + + /// All indices an argument appeared at when parsing. + /// + /// Indices are similar to argv indices, but are not exactly 1:1. + /// + /// For flags (i.e. those arguments which don't have an associated value), indices refer + /// to occurrence of the switch, such as `-f`, or `--flag`. However, for options the indices + /// refer to the *values* `-o val` would therefore not represent two distinct indices, only the + /// index for `val` would be recorded. This is by design. + /// + /// *NOTE:* For more information about how clap indices compared to argv indices, see + /// [`ArgMatches::index_of`] + /// + /// # Panics + /// + /// If `id` is not a valid argument or group id (debug builds). + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg}; + /// let m = Command::new("myapp") + /// .arg(Arg::new("option") + /// .short('o') + /// .value_delimiter(',')) + /// .get_matches_from(vec!["myapp", "-o=val1,val2,val3"]); + /// // ARGV indices: ^0 ^1 + /// // clap indices: ^2 ^3 ^4 + /// // + /// // clap sees the above as 'myapp -o val1 val2 val3' + /// // ^0 ^1 ^2 ^3 ^4 + /// assert_eq!(m.indices_of("option").unwrap().collect::<Vec<_>>(), &[2, 3, 4]); + /// ``` + /// + /// Another quick example is when flags and options are used together + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// let m = Command::new("myapp") + /// .arg(Arg::new("option") + /// .short('o') + /// .action(ArgAction::Set) + /// .action(ArgAction::Append)) + /// .arg(Arg::new("flag") + /// .short('f') + /// .action(ArgAction::Count)) + /// .get_matches_from(vec!["myapp", "-o", "val1", "-f", "-o", "val2", "-f"]); + /// // ARGV indices: ^0 ^1 ^2 ^3 ^4 ^5 ^6 + /// // clap indices: ^2 ^3 ^5 ^6 + /// + /// assert_eq!(m.indices_of("option").unwrap().collect::<Vec<_>>(), &[2, 5]); + /// assert_eq!(m.indices_of("flag").unwrap().collect::<Vec<_>>(), &[6]); + /// ``` + /// + /// One final example, which is an odd case; if we *don't* use value delimiter as we did with + /// the first example above instead of `val1`, `val2` and `val3` all being distinc values, they + /// would all be a single value of `val1,val2,val3`, in which case they'd only receive a single + /// index. + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// let m = Command::new("myapp") + /// .arg(Arg::new("option") + /// .short('o') + /// .action(ArgAction::Set) + /// .num_args(1..)) + /// .get_matches_from(vec!["myapp", "-o=val1,val2,val3"]); + /// // ARGV indices: ^0 ^1 + /// // clap indices: ^2 + /// // + /// // clap sees the above as 'myapp -o "val1,val2,val3"' + /// // ^0 ^1 ^2 + /// assert_eq!(m.indices_of("option").unwrap().collect::<Vec<_>>(), &[2]); + /// ``` + /// [`ArgMatches::index_of`]: ArgMatches::index_of() + /// [delimiter]: Arg::value_delimiter() + #[cfg_attr(debug_assertions, track_caller)] + pub fn indices_of(&self, id: &str) -> Option<Indices<'_>> { + let arg = some!(self.get_arg(id)); + let i = Indices { + iter: arg.indices(), + len: arg.num_vals(), + }; + Some(i) + } +} + +/// # Subcommands +impl ArgMatches { + /// The name and `ArgMatches` of the current [subcommand]. + /// + /// Subcommand values are put in a child [`ArgMatches`] + /// + /// Returns `None` if the subcommand wasn't present at runtime, + /// + /// # Examples + /// + /// ```no_run + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, }; + /// let app_m = Command::new("git") + /// .subcommand(Command::new("clone")) + /// .subcommand(Command::new("push")) + /// .subcommand(Command::new("commit")) + /// .get_matches(); + /// + /// match app_m.subcommand() { + /// Some(("clone", sub_m)) => {}, // clone was used + /// Some(("push", sub_m)) => {}, // push was used + /// Some(("commit", sub_m)) => {}, // commit was used + /// _ => {}, // Either no subcommand or one not tested for... + /// } + /// ``` + /// + /// Another useful scenario is when you want to support third party, or external, subcommands. + /// In these cases you can't know the subcommand name ahead of time, so use a variable instead + /// with pattern matching! + /// + /// ```rust + /// # use clap_builder as clap; + /// # use std::ffi::OsString; + /// # use std::ffi::OsStr; + /// # use clap::Command; + /// // Assume there is an external subcommand named "subcmd" + /// let app_m = Command::new("myprog") + /// .allow_external_subcommands(true) + /// .get_matches_from(vec![ + /// "myprog", "subcmd", "--option", "value", "-fff", "--flag" + /// ]); + /// + /// // All trailing arguments will be stored under the subcommand's sub-matches using an empty + /// // string argument name + /// match app_m.subcommand() { + /// Some((external, sub_m)) => { + /// let ext_args: Vec<&OsStr> = sub_m.get_many::<OsString>("") + /// .unwrap().map(|s| s.as_os_str()).collect(); + /// assert_eq!(external, "subcmd"); + /// assert_eq!(ext_args, ["--option", "value", "-fff", "--flag"]); + /// }, + /// _ => {}, + /// } + /// ``` + /// [subcommand]: crate::Command::subcommand + #[inline] + pub fn subcommand(&self) -> Option<(&str, &ArgMatches)> { + self.subcommand.as_ref().map(|sc| (&*sc.name, &sc.matches)) + } + + /// Return the name and `ArgMatches` of the current [subcommand]. + /// + /// Subcommand values are put in a child [`ArgMatches`] + /// + /// Returns `None` if the subcommand wasn't present at runtime, + /// + /// # Examples + /// + /// ```no_run + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, }; + /// let mut app_m = Command::new("git") + /// .subcommand(Command::new("clone")) + /// .subcommand(Command::new("push")) + /// .subcommand(Command::new("commit")) + /// .subcommand_required(true) + /// .get_matches(); + /// + /// let (name, sub_m) = app_m.remove_subcommand().expect("required"); + /// match (name.as_str(), sub_m) { + /// ("clone", sub_m) => {}, // clone was used + /// ("push", sub_m) => {}, // push was used + /// ("commit", sub_m) => {}, // commit was used + /// (name, _) => unimplemented!("{name}"), + /// } + /// ``` + /// + /// Another useful scenario is when you want to support third party, or external, subcommands. + /// In these cases you can't know the subcommand name ahead of time, so use a variable instead + /// with pattern matching! + /// + /// ```rust + /// # use clap_builder as clap; + /// # use std::ffi::OsString; + /// # use clap::Command; + /// // Assume there is an external subcommand named "subcmd" + /// let mut app_m = Command::new("myprog") + /// .allow_external_subcommands(true) + /// .get_matches_from(vec![ + /// "myprog", "subcmd", "--option", "value", "-fff", "--flag" + /// ]); + /// + /// // All trailing arguments will be stored under the subcommand's sub-matches using an empty + /// // string argument name + /// match app_m.remove_subcommand() { + /// Some((external, mut sub_m)) => { + /// let ext_args: Vec<OsString> = sub_m.remove_many("") + /// .expect("`file`is required") + /// .collect(); + /// assert_eq!(external, "subcmd"); + /// assert_eq!(ext_args, ["--option", "value", "-fff", "--flag"]); + /// }, + /// _ => {}, + /// } + /// ``` + /// [subcommand]: crate::Command::subcommand + pub fn remove_subcommand(&mut self) -> Option<(String, ArgMatches)> { + self.subcommand.take().map(|sc| (sc.name, sc.matches)) + } + + /// The `ArgMatches` for the current [subcommand]. + /// + /// Subcommand values are put in a child [`ArgMatches`] + /// + /// Returns `None` if the subcommand wasn't present at runtime, + /// + /// # Panics + /// + /// If `id` is not a valid subcommand (debug builds). + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, ArgAction}; + /// let app_m = Command::new("myprog") + /// .arg(Arg::new("debug") + /// .short('d') + /// .action(ArgAction::SetTrue) + /// ) + /// .subcommand(Command::new("test") + /// .arg(Arg::new("opt") + /// .long("option") + /// .action(ArgAction::Set))) + /// .get_matches_from(vec![ + /// "myprog", "-d", "test", "--option", "val" + /// ]); + /// + /// // Both parent commands, and child subcommands can have arguments present at the same times + /// assert!(app_m.get_flag("debug")); + /// + /// // Get the subcommand's ArgMatches instance + /// if let Some(sub_m) = app_m.subcommand_matches("test") { + /// // Use the struct like normal + /// assert_eq!(sub_m.get_one::<String>("opt").map(|s| s.as_str()), Some("val")); + /// } + /// ``` + /// + /// [subcommand]: crate::Command::subcommand + /// [`Command`]: crate::Command + pub fn subcommand_matches(&self, name: &str) -> Option<&ArgMatches> { + self.get_subcommand(name).map(|sc| &sc.matches) + } + + /// The name of the current [subcommand]. + /// + /// Returns `None` if the subcommand wasn't present at runtime, + /// + /// # Examples + /// + /// ```no_run + /// # use clap_builder as clap; + /// # use clap::{Command, Arg, }; + /// let app_m = Command::new("git") + /// .subcommand(Command::new("clone")) + /// .subcommand(Command::new("push")) + /// .subcommand(Command::new("commit")) + /// .get_matches(); + /// + /// match app_m.subcommand_name() { + /// Some("clone") => {}, // clone was used + /// Some("push") => {}, // push was used + /// Some("commit") => {}, // commit was used + /// _ => {}, // Either no subcommand or one not tested for... + /// } + /// ``` + /// [subcommand]: crate::Command::subcommand + /// [`Command`]: crate::Command + #[inline] + pub fn subcommand_name(&self) -> Option<&str> { + self.subcommand.as_ref().map(|sc| &*sc.name) + } + + /// Check if a subcommand can be queried + /// + /// By default, `ArgMatches` functions assert on undefined `Id`s to help catch programmer + /// mistakes. In some context, this doesn't work, so users can use this function to check + /// before they do a query on `ArgMatches`. + #[inline] + #[doc(hidden)] + pub fn is_valid_subcommand(&self, _name: &str) -> bool { + #[cfg(debug_assertions)] + { + _name.is_empty() || self.valid_subcommands.iter().any(|s| *s == _name) + } + #[cfg(not(debug_assertions))] + { + true + } + } +} + +/// # Advanced +impl ArgMatches { + /// Non-panicking version of [`ArgMatches::get_one`] + pub fn try_get_one<T: Any + Clone + Send + Sync + 'static>( + &self, + id: &str, + ) -> Result<Option<&T>, MatchesError> { + let arg = ok!(self.try_get_arg_t::<T>(id)); + let value = match arg.and_then(|a| a.first()) { + Some(value) => value, + None => { + return Ok(None); + } + }; + Ok(value + .downcast_ref::<T>() + .map(Some) + .expect(INTERNAL_ERROR_MSG)) // enforced by `try_get_arg_t` + } + + /// Non-panicking version of [`ArgMatches::get_many`] + pub fn try_get_many<T: Any + Clone + Send + Sync + 'static>( + &self, + id: &str, + ) -> Result<Option<ValuesRef<T>>, MatchesError> { + let arg = match ok!(self.try_get_arg_t::<T>(id)) { + Some(arg) => arg, + None => return Ok(None), + }; + let len = arg.num_vals(); + let values = arg.vals_flatten(); + let values = ValuesRef { + // enforced by `try_get_arg_t` + iter: values.map(unwrap_downcast_ref), + len, + }; + Ok(Some(values)) + } + + /// Non-panicking version of [`ArgMatches::get_occurrences`] + pub fn try_get_occurrences<T: Any + Clone + Send + Sync + 'static>( + &self, + id: &str, + ) -> Result<Option<OccurrencesRef<T>>, MatchesError> { + let arg = match ok!(self.try_get_arg_t::<T>(id)) { + Some(arg) => arg, + None => return Ok(None), + }; + let values = arg.vals(); + Ok(Some(OccurrencesRef { + iter: values.map(|g| OccurrenceValuesRef { + iter: g.iter().map(unwrap_downcast_ref), + }), + })) + } + + /// Non-panicking version of [`ArgMatches::get_raw`] + pub fn try_get_raw(&self, id: &str) -> Result<Option<RawValues<'_>>, MatchesError> { + let arg = match ok!(self.try_get_arg(id)) { + Some(arg) => arg, + None => return Ok(None), + }; + let len = arg.num_vals(); + let values = arg.raw_vals_flatten(); + let values = RawValues { + iter: values.map(OsString::as_os_str), + len, + }; + Ok(Some(values)) + } + + /// Non-panicking version of [`ArgMatches::get_raw_occurrences`] + pub fn try_get_raw_occurrences( + &self, + id: &str, + ) -> Result<Option<RawOccurrences<'_>>, MatchesError> { + let arg = match ok!(self.try_get_arg(id)) { + Some(arg) => arg, + None => return Ok(None), + }; + let values = arg.raw_vals(); + let occurrences = RawOccurrences { + iter: values.map(|g| RawOccurrenceValues { + iter: g.iter().map(OsString::as_os_str), + }), + }; + Ok(Some(occurrences)) + } + + /// Non-panicking version of [`ArgMatches::remove_one`] + pub fn try_remove_one<T: Any + Clone + Send + Sync + 'static>( + &mut self, + id: &str, + ) -> Result<Option<T>, MatchesError> { + match ok!(self.try_remove_arg_t::<T>(id)) { + Some(values) => Ok(values + .into_vals_flatten() + // enforced by `try_get_arg_t` + .map(unwrap_downcast_into) + .next()), + None => Ok(None), + } + } + + /// Non-panicking version of [`ArgMatches::remove_many`] + pub fn try_remove_many<T: Any + Clone + Send + Sync + 'static>( + &mut self, + id: &str, + ) -> Result<Option<Values<T>>, MatchesError> { + let arg = match ok!(self.try_remove_arg_t::<T>(id)) { + Some(arg) => arg, + None => return Ok(None), + }; + let len = arg.num_vals(); + let values = arg.into_vals_flatten(); + let values = Values { + // enforced by `try_get_arg_t` + iter: values.map(unwrap_downcast_into), + len, + }; + Ok(Some(values)) + } + + /// Non-panicking version of [`ArgMatches::remove_occurrences`] + pub fn try_remove_occurrences<T: Any + Clone + Send + Sync + 'static>( + &mut self, + id: &str, + ) -> Result<Option<Occurrences<T>>, MatchesError> { + let arg = match ok!(self.try_remove_arg_t::<T>(id)) { + Some(arg) => arg, + None => return Ok(None), + }; + let values = arg.into_vals(); + let occurrences = Occurrences { + iter: values.into_iter().map(|g| OccurrenceValues { + iter: g.into_iter().map(unwrap_downcast_into), + }), + }; + Ok(Some(occurrences)) + } + + /// Non-panicking version of [`ArgMatches::contains_id`] + pub fn try_contains_id(&self, id: &str) -> Result<bool, MatchesError> { + ok!(self.verify_arg(id)); + + let presence = self.args.contains_key(id); + Ok(presence) + } +} + +// Private methods +impl ArgMatches { + #[inline] + fn try_get_arg(&self, arg: &str) -> Result<Option<&MatchedArg>, MatchesError> { + ok!(self.verify_arg(arg)); + Ok(self.args.get(arg)) + } + + #[inline] + fn try_get_arg_t<T: Any + Send + Sync + 'static>( + &self, + arg: &str, + ) -> Result<Option<&MatchedArg>, MatchesError> { + let arg = match ok!(self.try_get_arg(arg)) { + Some(arg) => arg, + None => { + return Ok(None); + } + }; + ok!(self.verify_arg_t::<T>(arg)); + Ok(Some(arg)) + } + + #[inline] + fn try_remove_arg_t<T: Any + Send + Sync + 'static>( + &mut self, + arg: &str, + ) -> Result<Option<MatchedArg>, MatchesError> { + ok!(self.verify_arg(arg)); + let (id, matched) = match self.args.remove_entry(arg) { + Some((id, matched)) => (id, matched), + None => { + return Ok(None); + } + }; + + let expected = AnyValueId::of::<T>(); + let actual = matched.infer_type_id(expected); + if actual == expected { + Ok(Some(matched)) + } else { + self.args.insert(id, matched); + Err(MatchesError::Downcast { actual, expected }) + } + } + + fn verify_arg_t<T: Any + Send + Sync + 'static>( + &self, + arg: &MatchedArg, + ) -> Result<(), MatchesError> { + let expected = AnyValueId::of::<T>(); + let actual = arg.infer_type_id(expected); + if expected == actual { + Ok(()) + } else { + Err(MatchesError::Downcast { actual, expected }) + } + } + + #[inline] + fn verify_arg(&self, _arg: &str) -> Result<(), MatchesError> { + #[cfg(debug_assertions)] + { + if _arg == Id::EXTERNAL || self.valid_args.iter().any(|s| *s == _arg) { + } else { + debug!( + "`{:?}` is not an id of an argument or a group.\n\ + Make sure you're using the name of the argument itself \ + and not the name of short or long flags.", + _arg + ); + return Err(MatchesError::UnknownArgument {}); + } + } + Ok(()) + } + + #[inline] + #[cfg_attr(debug_assertions, track_caller)] + fn get_arg<'s>(&'s self, arg: &str) -> Option<&'s MatchedArg> { + #[cfg(debug_assertions)] + { + if arg == Id::EXTERNAL || self.valid_args.iter().any(|s| *s == arg) { + } else { + panic!( + "`{arg:?}` is not an id of an argument or a group.\n\ + Make sure you're using the name of the argument itself \ + and not the name of short or long flags." + ); + } + } + + self.args.get(arg) + } + + #[inline] + #[cfg_attr(debug_assertions, track_caller)] + fn get_subcommand(&self, name: &str) -> Option<&SubCommand> { + #[cfg(debug_assertions)] + { + if name.is_empty() || self.valid_subcommands.iter().any(|s| *s == name) { + } else { + panic!("`{name}` is not a name of a subcommand."); + } + } + + if let Some(ref sc) = self.subcommand { + if sc.name == name { + return Some(sc); + } + } + + None + } +} + +#[derive(Debug, Clone, PartialEq, Eq)] +pub(crate) struct SubCommand { + pub(crate) name: String, + pub(crate) matches: ArgMatches, +} + +/// Iterate over [`Arg`][crate::Arg] and [`ArgGroup`][crate::ArgGroup] [`Id`]s via [`ArgMatches::ids`]. +/// +/// # Examples +/// +/// ```rust +/// # use clap_builder as clap; +/// # use clap::{Command, arg, value_parser}; +/// +/// let m = Command::new("myprog") +/// .arg(arg!(--color <when>) +/// .value_parser(["auto", "always", "never"])) +/// .arg(arg!(--config <path>) +/// .value_parser(value_parser!(std::path::PathBuf))) +/// .get_matches_from(["myprog", "--config=config.toml", "--color=auto"]); +/// assert_eq!( +/// m.ids() +/// .map(|id| id.as_str()) +/// .collect::<Vec<_>>(), +/// ["config", "color"] +/// ); +/// ``` +#[derive(Clone, Debug)] +pub struct IdsRef<'a> { + iter: std::slice::Iter<'a, Id>, +} + +impl<'a> Iterator for IdsRef<'a> { + type Item = &'a Id; + + fn next(&mut self) -> Option<&'a Id> { + self.iter.next() + } + fn size_hint(&self) -> (usize, Option<usize>) { + self.iter.size_hint() + } +} + +impl<'a> DoubleEndedIterator for IdsRef<'a> { + fn next_back(&mut self) -> Option<&'a Id> { + self.iter.next_back() + } +} + +impl<'a> ExactSizeIterator for IdsRef<'a> {} + +/// Iterate over multiple values for an argument via [`ArgMatches::remove_many`]. +/// +/// # Examples +/// +/// ```rust +/// # use clap_builder as clap; +/// # use clap::{Command, Arg, ArgAction}; +/// let mut m = Command::new("myapp") +/// .arg(Arg::new("output") +/// .short('o') +/// .action(ArgAction::Append)) +/// .get_matches_from(vec!["myapp", "-o", "val1", "-o", "val2"]); +/// +/// let mut values = m.remove_many::<String>("output") +/// .unwrap(); +/// +/// assert_eq!(values.next(), Some(String::from("val1"))); +/// assert_eq!(values.next(), Some(String::from("val2"))); +/// assert_eq!(values.next(), None); +/// ``` +#[derive(Clone, Debug)] +pub struct Values<T> { + #[allow(clippy::type_complexity)] + iter: Map<Flatten<std::vec::IntoIter<Vec<AnyValue>>>, fn(AnyValue) -> T>, + len: usize, +} + +impl<T> Iterator for Values<T> { + type Item = T; + + fn next(&mut self) -> Option<Self::Item> { + if let Some(next) = self.iter.next() { + self.len -= 1; + Some(next) + } else { + None + } + } + fn size_hint(&self) -> (usize, Option<usize>) { + (self.len, Some(self.len)) + } +} + +impl<T> DoubleEndedIterator for Values<T> { + fn next_back(&mut self) -> Option<Self::Item> { + if let Some(next) = self.iter.next_back() { + self.len -= 1; + Some(next) + } else { + None + } + } +} + +impl<T> ExactSizeIterator for Values<T> {} + +/// Creates an empty iterator. +impl<T> Default for Values<T> { + fn default() -> Self { + let empty: Vec<Vec<AnyValue>> = Default::default(); + Values { + iter: empty.into_iter().flatten().map(|_| unreachable!()), + len: 0, + } + } +} + +/// Iterate over multiple values for an argument via [`ArgMatches::get_many`]. +/// +/// # Examples +/// +/// ```rust +/// # use clap_builder as clap; +/// # use clap::{Command, Arg, ArgAction}; +/// let m = Command::new("myapp") +/// .arg(Arg::new("output") +/// .short('o') +/// .action(ArgAction::Append)) +/// .get_matches_from(vec!["myapp", "-o", "val1", "-o", "val2"]); +/// +/// let mut values = m.get_many::<String>("output") +/// .unwrap() +/// .map(|s| s.as_str()); +/// +/// assert_eq!(values.next(), Some("val1")); +/// assert_eq!(values.next(), Some("val2")); +/// assert_eq!(values.next(), None); +/// ``` +#[derive(Clone, Debug)] +pub struct ValuesRef<'a, T> { + #[allow(clippy::type_complexity)] + iter: Map<Flatten<Iter<'a, Vec<AnyValue>>>, fn(&AnyValue) -> &T>, + len: usize, +} + +impl<'a, T: 'a> Iterator for ValuesRef<'a, T> { + type Item = &'a T; + + fn next(&mut self) -> Option<Self::Item> { + if let Some(next) = self.iter.next() { + self.len -= 1; + Some(next) + } else { + None + } + } + fn size_hint(&self) -> (usize, Option<usize>) { + (self.len, Some(self.len)) + } +} + +impl<'a, T: 'a> DoubleEndedIterator for ValuesRef<'a, T> { + fn next_back(&mut self) -> Option<Self::Item> { + if let Some(next) = self.iter.next_back() { + self.len -= 1; + Some(next) + } else { + None + } + } +} + +impl<'a, T: 'a> ExactSizeIterator for ValuesRef<'a, T> {} + +/// Creates an empty iterator. +impl<'a, T: 'a> Default for ValuesRef<'a, T> { + fn default() -> Self { + static EMPTY: [Vec<AnyValue>; 0] = []; + ValuesRef { + iter: EMPTY[..].iter().flatten().map(|_| unreachable!()), + len: 0, + } + } +} + +/// Iterate over raw argument values via [`ArgMatches::get_raw`]. +/// +/// # Examples +/// +/// ```rust +/// # #[cfg(unix)] { +/// # use clap_builder as clap; +/// # use clap::{Command, arg, value_parser}; +/// use std::ffi::OsString; +/// use std::os::unix::ffi::{OsStrExt,OsStringExt}; +/// +/// let m = Command::new("utf8") +/// .arg(arg!(<arg> "some arg") +/// .value_parser(value_parser!(OsString))) +/// .get_matches_from(vec![OsString::from("myprog"), +/// // "Hi {0xe9}!" +/// OsString::from_vec(vec![b'H', b'i', b' ', 0xe9, b'!'])]); +/// assert_eq!( +/// &*m.get_raw("arg") +/// .unwrap() +/// .next().unwrap() +/// .as_bytes(), +/// [b'H', b'i', b' ', 0xe9, b'!'] +/// ); +/// # } +/// ``` +#[derive(Clone, Debug)] +pub struct RawValues<'a> { + #[allow(clippy::type_complexity)] + iter: Map<Flatten<Iter<'a, Vec<OsString>>>, fn(&OsString) -> &OsStr>, + len: usize, +} + +impl<'a> Iterator for RawValues<'a> { + type Item = &'a OsStr; + + fn next(&mut self) -> Option<&'a OsStr> { + if let Some(next) = self.iter.next() { + self.len -= 1; + Some(next) + } else { + None + } + } + fn size_hint(&self) -> (usize, Option<usize>) { + (self.len, Some(self.len)) + } +} + +impl<'a> DoubleEndedIterator for RawValues<'a> { + fn next_back(&mut self) -> Option<&'a OsStr> { + if let Some(next) = self.iter.next_back() { + self.len -= 1; + Some(next) + } else { + None + } + } +} + +impl<'a> ExactSizeIterator for RawValues<'a> {} + +/// Creates an empty iterator. +impl Default for RawValues<'_> { + fn default() -> Self { + static EMPTY: [Vec<OsString>; 0] = []; + RawValues { + iter: EMPTY[..].iter().flatten().map(|_| unreachable!()), + len: 0, + } + } +} + +// The following were taken and adapted from vec_map source +// repo: https://github.com/contain-rs/vec-map +// commit: be5e1fa3c26e351761b33010ddbdaf5f05dbcc33 +// license: MIT - Copyright (c) 2015 The Rust Project Developers + +#[derive(Clone, Debug)] +#[deprecated(since = "4.1.0", note = "Use Occurrences instead")] +pub struct GroupedValues<'a> { + #[allow(clippy::type_complexity)] + iter: Map<Iter<'a, Vec<AnyValue>>, fn(&Vec<AnyValue>) -> Vec<&str>>, + len: usize, +} + +#[allow(deprecated)] +impl<'a> Iterator for GroupedValues<'a> { + type Item = Vec<&'a str>; + + fn next(&mut self) -> Option<Self::Item> { + if let Some(next) = self.iter.next() { + self.len -= 1; + Some(next) + } else { + None + } + } + fn size_hint(&self) -> (usize, Option<usize>) { + (self.len, Some(self.len)) + } +} + +#[allow(deprecated)] +impl<'a> DoubleEndedIterator for GroupedValues<'a> { + fn next_back(&mut self) -> Option<Self::Item> { + if let Some(next) = self.iter.next_back() { + self.len -= 1; + Some(next) + } else { + None + } + } +} + +#[allow(deprecated)] +impl<'a> ExactSizeIterator for GroupedValues<'a> {} + +/// Creates an empty iterator. Used for `unwrap_or_default()`. +#[allow(deprecated)] +impl<'a> Default for GroupedValues<'a> { + fn default() -> Self { + static EMPTY: [Vec<AnyValue>; 0] = []; + GroupedValues { + iter: EMPTY[..].iter().map(|_| unreachable!()), + len: 0, + } + } +} + +#[derive(Clone, Debug)] +pub struct Occurrences<T> { + #[allow(clippy::type_complexity)] + iter: Map<std::vec::IntoIter<Vec<AnyValue>>, fn(Vec<AnyValue>) -> OccurrenceValues<T>>, +} + +impl<T> Iterator for Occurrences<T> { + type Item = OccurrenceValues<T>; + + fn next(&mut self) -> Option<Self::Item> { + self.iter.next() + } + + fn size_hint(&self) -> (usize, Option<usize>) { + self.iter.size_hint() + } +} + +impl<T> DoubleEndedIterator for Occurrences<T> { + fn next_back(&mut self) -> Option<Self::Item> { + self.iter.next_back() + } +} + +impl<T> ExactSizeIterator for Occurrences<T> {} + +impl<T> Default for Occurrences<T> { + fn default() -> Self { + let empty: Vec<Vec<AnyValue>> = Default::default(); + Occurrences { + iter: empty.into_iter().map(|_| unreachable!()), + } + } +} + +#[derive(Clone, Debug)] +pub struct OccurrenceValues<T> { + #[allow(clippy::type_complexity)] + iter: Map<std::vec::IntoIter<AnyValue>, fn(AnyValue) -> T>, +} + +impl<T> Iterator for OccurrenceValues<T> { + type Item = T; + + fn next(&mut self) -> Option<Self::Item> { + self.iter.next() + } + + fn size_hint(&self) -> (usize, Option<usize>) { + self.iter.size_hint() + } +} + +impl<T> DoubleEndedIterator for OccurrenceValues<T> { + fn next_back(&mut self) -> Option<Self::Item> { + self.iter.next_back() + } +} + +impl<T> ExactSizeIterator for OccurrenceValues<T> {} + +#[derive(Clone, Debug)] +pub struct OccurrencesRef<'a, T> { + #[allow(clippy::type_complexity)] + iter: Map<Iter<'a, Vec<AnyValue>>, fn(&Vec<AnyValue>) -> OccurrenceValuesRef<'_, T>>, +} + +impl<'a, T> Iterator for OccurrencesRef<'a, T> +where + Self: 'a, +{ + type Item = OccurrenceValuesRef<'a, T>; + + fn next(&mut self) -> Option<Self::Item> { + self.iter.next() + } + + fn size_hint(&self) -> (usize, Option<usize>) { + self.iter.size_hint() + } +} + +impl<'a, T> DoubleEndedIterator for OccurrencesRef<'a, T> +where + Self: 'a, +{ + fn next_back(&mut self) -> Option<Self::Item> { + self.iter.next_back() + } +} + +impl<'a, T> ExactSizeIterator for OccurrencesRef<'a, T> where Self: 'a {} +impl<'a, T> Default for OccurrencesRef<'a, T> { + fn default() -> Self { + static EMPTY: [Vec<AnyValue>; 0] = []; + OccurrencesRef { + iter: EMPTY[..].iter().map(|_| unreachable!()), + } + } +} + +#[derive(Clone, Debug)] +pub struct OccurrenceValuesRef<'a, T> { + #[allow(clippy::type_complexity)] + iter: Map<Iter<'a, AnyValue>, fn(&AnyValue) -> &T>, +} + +impl<'a, T> Iterator for OccurrenceValuesRef<'a, T> +where + Self: 'a, +{ + type Item = &'a T; + + fn next(&mut self) -> Option<Self::Item> { + self.iter.next() + } + + fn size_hint(&self) -> (usize, Option<usize>) { + self.iter.size_hint() + } +} + +impl<'a, T> DoubleEndedIterator for OccurrenceValuesRef<'a, T> +where + Self: 'a, +{ + fn next_back(&mut self) -> Option<Self::Item> { + self.iter.next_back() + } +} + +impl<'a, T> ExactSizeIterator for OccurrenceValuesRef<'a, T> where Self: 'a {} + +#[derive(Clone, Debug)] +pub struct RawOccurrences<'a> { + #[allow(clippy::type_complexity)] + iter: Map<Iter<'a, Vec<OsString>>, fn(&Vec<OsString>) -> RawOccurrenceValues<'_>>, +} + +impl<'a> Iterator for RawOccurrences<'a> { + type Item = RawOccurrenceValues<'a>; + + fn next(&mut self) -> Option<Self::Item> { + self.iter.next() + } + + fn size_hint(&self) -> (usize, Option<usize>) { + self.iter.size_hint() + } +} + +impl<'a> DoubleEndedIterator for RawOccurrences<'a> { + fn next_back(&mut self) -> Option<Self::Item> { + self.iter.next_back() + } +} + +impl<'a> ExactSizeIterator for RawOccurrences<'a> {} + +impl<'a> Default for RawOccurrences<'a> { + fn default() -> Self { + static EMPTY: [Vec<OsString>; 0] = []; + RawOccurrences { + iter: EMPTY[..].iter().map(|_| unreachable!()), + } + } +} + +#[derive(Clone, Debug)] +pub struct RawOccurrenceValues<'a> { + #[allow(clippy::type_complexity)] + iter: Map<Iter<'a, OsString>, fn(&OsString) -> &OsStr>, +} + +impl<'a> Iterator for RawOccurrenceValues<'a> +where + Self: 'a, +{ + type Item = &'a OsStr; + + fn next(&mut self) -> Option<Self::Item> { + self.iter.next() + } + + fn size_hint(&self) -> (usize, Option<usize>) { + self.iter.size_hint() + } +} + +impl<'a> DoubleEndedIterator for RawOccurrenceValues<'a> +where + Self: 'a, +{ + fn next_back(&mut self) -> Option<Self::Item> { + self.iter.next_back() + } +} + +impl<'a> ExactSizeIterator for RawOccurrenceValues<'a> {} + +/// Iterate over indices for where an argument appeared when parsing, via [`ArgMatches::indices_of`] +/// +/// # Examples +/// +/// ```rust +/// # use clap_builder as clap; +/// # use clap::{Command, Arg, ArgAction}; +/// let m = Command::new("myapp") +/// .arg(Arg::new("output") +/// .short('o') +/// .num_args(1..) +/// .action(ArgAction::Set)) +/// .get_matches_from(vec!["myapp", "-o", "val1", "val2"]); +/// +/// let mut indices = m.indices_of("output").unwrap(); +/// +/// assert_eq!(indices.next(), Some(2)); +/// assert_eq!(indices.next(), Some(3)); +/// assert_eq!(indices.next(), None); +/// ``` +/// [`ArgMatches::indices_of`]: ArgMatches::indices_of() +#[derive(Clone, Debug)] +pub struct Indices<'a> { + iter: Cloned<Iter<'a, usize>>, + len: usize, +} + +impl<'a> Iterator for Indices<'a> { + type Item = usize; + + fn next(&mut self) -> Option<usize> { + if let Some(next) = self.iter.next() { + self.len -= 1; + Some(next) + } else { + None + } + } + fn size_hint(&self) -> (usize, Option<usize>) { + (self.len, Some(self.len)) + } +} + +impl<'a> DoubleEndedIterator for Indices<'a> { + fn next_back(&mut self) -> Option<usize> { + if let Some(next) = self.iter.next_back() { + self.len -= 1; + Some(next) + } else { + None + } + } +} + +impl<'a> ExactSizeIterator for Indices<'a> {} + +/// Creates an empty iterator. +impl<'a> Default for Indices<'a> { + fn default() -> Self { + static EMPTY: [usize; 0] = []; + // This is never called because the iterator is empty: + Indices { + iter: EMPTY[..].iter().cloned(), + len: 0, + } + } +} + +#[track_caller] +fn unwrap_downcast_ref<T: Any + Clone + Send + Sync + 'static>(value: &AnyValue) -> &T { + value.downcast_ref().expect(INTERNAL_ERROR_MSG) +} + +#[track_caller] +fn unwrap_downcast_into<T: Any + Clone + Send + Sync + 'static>(value: AnyValue) -> T { + value.downcast_into().expect(INTERNAL_ERROR_MSG) +} + +#[cfg(test)] +mod tests { + use super::*; + + use crate::ArgAction; + + #[test] + fn check_auto_traits() { + static_assertions::assert_impl_all!(ArgMatches: Send, Sync, Unpin); + } + + #[test] + fn test_default_raw_values() { + let mut values: RawValues = Default::default(); + assert_eq!(values.next(), None); + } + + #[test] + fn test_default_indices() { + let mut indices: Indices = Indices::default(); + assert_eq!(indices.next(), None); + } + + #[test] + fn test_default_indices_with_shorter_lifetime() { + let matches = ArgMatches::default(); + let mut indices = matches.indices_of("").unwrap_or_default(); + assert_eq!(indices.next(), None); + } + + #[test] + fn values_exact_size() { + let l = crate::Command::new("test") + .arg( + crate::Arg::new("POTATO") + .action(ArgAction::Set) + .num_args(1..) + .required(true), + ) + .try_get_matches_from(["test", "one"]) + .unwrap() + .get_many::<String>("POTATO") + .expect("present") + .count(); + assert_eq!(l, 1); + } + + #[test] + fn os_values_exact_size() { + let l = crate::Command::new("test") + .arg( + crate::Arg::new("POTATO") + .action(ArgAction::Set) + .num_args(1..) + .value_parser(crate::builder::ValueParser::os_string()) + .required(true), + ) + .try_get_matches_from(["test", "one"]) + .unwrap() + .get_many::<std::ffi::OsString>("POTATO") + .expect("present") + .count(); + assert_eq!(l, 1); + } + + #[test] + fn indices_exact_size() { + let l = crate::Command::new("test") + .arg( + crate::Arg::new("POTATO") + .action(ArgAction::Set) + .num_args(1..) + .required(true), + ) + .try_get_matches_from(["test", "one"]) + .unwrap() + .indices_of("POTATO") + .expect("present") + .len(); + assert_eq!(l, 1); + } + + #[test] + fn rev_iter() { + let mut matches = crate::Command::new("myprog") + .arg(crate::Arg::new("a").short('a').action(ArgAction::Append)) + .arg(crate::Arg::new("b").short('b').action(ArgAction::Append)) + .try_get_matches_from(vec!["myprog", "-a1", "-b1", "-b3"]) + .unwrap(); + + let a_index = matches + .indices_of("a") + .expect("missing aopt indices") + .collect::<Vec<_>>(); + dbg!(&a_index); + let a_value = matches + .remove_many::<String>("a") + .expect("missing aopt values"); + dbg!(&a_value); + let a = a_index.into_iter().zip(a_value).rev().collect::<Vec<_>>(); + dbg!(a); + + let b_index = matches + .indices_of("b") + .expect("missing aopt indices") + .collect::<Vec<_>>(); + dbg!(&b_index); + let b_value = matches + .remove_many::<String>("b") + .expect("missing aopt values"); + dbg!(&b_value); + let b = b_index.into_iter().zip(b_value).rev().collect::<Vec<_>>(); + dbg!(b); + } +} diff --git a/vendor/clap_builder/src/parser/matches/matched_arg.rs b/vendor/clap_builder/src/parser/matches/matched_arg.rs new file mode 100644 index 0000000..24df8b1 --- /dev/null +++ b/vendor/clap_builder/src/parser/matches/matched_arg.rs @@ -0,0 +1,225 @@ +// Std +use std::{ + ffi::{OsStr, OsString}, + iter::{Cloned, Flatten}, + slice::Iter, +}; + +use crate::builder::ArgPredicate; +use crate::parser::ValueSource; +use crate::util::eq_ignore_case; +use crate::util::AnyValue; +use crate::util::AnyValueId; +use crate::INTERNAL_ERROR_MSG; + +#[derive(Debug, Clone)] +pub(crate) struct MatchedArg { + source: Option<ValueSource>, + indices: Vec<usize>, + type_id: Option<AnyValueId>, + vals: Vec<Vec<AnyValue>>, + raw_vals: Vec<Vec<OsString>>, + ignore_case: bool, +} + +impl MatchedArg { + pub(crate) fn new_arg(arg: &crate::Arg) -> Self { + let ignore_case = arg.is_ignore_case_set(); + Self { + source: None, + indices: Vec::new(), + type_id: Some(arg.get_value_parser().type_id()), + vals: Vec::new(), + raw_vals: Vec::new(), + ignore_case, + } + } + + pub(crate) fn new_group() -> Self { + let ignore_case = false; + Self { + source: None, + indices: Vec::new(), + type_id: None, + vals: Vec::new(), + raw_vals: Vec::new(), + ignore_case, + } + } + + pub(crate) fn new_external(cmd: &crate::Command) -> Self { + let ignore_case = false; + Self { + source: None, + indices: Vec::new(), + type_id: Some( + cmd.get_external_subcommand_value_parser() + .expect(INTERNAL_ERROR_MSG) + .type_id(), + ), + vals: Vec::new(), + raw_vals: Vec::new(), + ignore_case, + } + } + + pub(crate) fn indices(&self) -> Cloned<Iter<'_, usize>> { + self.indices.iter().cloned() + } + + pub(crate) fn get_index(&self, index: usize) -> Option<usize> { + self.indices.get(index).cloned() + } + + pub(crate) fn push_index(&mut self, index: usize) { + self.indices.push(index) + } + + pub(crate) fn vals(&self) -> Iter<Vec<AnyValue>> { + self.vals.iter() + } + + pub(crate) fn into_vals(self) -> Vec<Vec<AnyValue>> { + self.vals + } + + pub(crate) fn vals_flatten(&self) -> Flatten<Iter<Vec<AnyValue>>> { + self.vals.iter().flatten() + } + + pub(crate) fn into_vals_flatten(self) -> Flatten<std::vec::IntoIter<Vec<AnyValue>>> { + self.vals.into_iter().flatten() + } + + pub(crate) fn raw_vals(&self) -> Iter<Vec<OsString>> { + self.raw_vals.iter() + } + + pub(crate) fn raw_vals_flatten(&self) -> Flatten<Iter<Vec<OsString>>> { + self.raw_vals.iter().flatten() + } + + pub(crate) fn first(&self) -> Option<&AnyValue> { + self.vals_flatten().next() + } + + #[cfg(test)] + pub(crate) fn first_raw(&self) -> Option<&OsString> { + self.raw_vals_flatten().next() + } + + pub(crate) fn new_val_group(&mut self) { + self.vals.push(vec![]); + self.raw_vals.push(vec![]); + } + + pub(crate) fn append_val(&mut self, val: AnyValue, raw_val: OsString) { + // We assume there is always a group created before. + self.vals.last_mut().expect(INTERNAL_ERROR_MSG).push(val); + self.raw_vals + .last_mut() + .expect(INTERNAL_ERROR_MSG) + .push(raw_val); + } + + pub(crate) fn num_vals(&self) -> usize { + self.vals.iter().map(|v| v.len()).sum() + } + + // Will be used later + #[allow(dead_code)] + pub(crate) fn num_vals_last_group(&self) -> usize { + self.vals.last().map(|x| x.len()).unwrap_or(0) + } + + pub(crate) fn all_val_groups_empty(&self) -> bool { + self.vals.iter().flatten().count() == 0 + } + + pub(crate) fn check_explicit(&self, predicate: &ArgPredicate) -> bool { + if self.source.map(|s| !s.is_explicit()).unwrap_or(false) { + return false; + } + + match predicate { + ArgPredicate::Equals(val) => self.raw_vals_flatten().any(|v| { + if self.ignore_case { + // If `v` isn't utf8, it can't match `val`, so `OsStr::to_str` should be fine + eq_ignore_case(&v.to_string_lossy(), &val.to_string_lossy()) + } else { + OsString::as_os_str(v) == OsStr::new(val) + } + }), + ArgPredicate::IsPresent => true, + } + } + + pub(crate) fn source(&self) -> Option<ValueSource> { + self.source + } + + pub(crate) fn set_source(&mut self, source: ValueSource) { + if let Some(existing) = self.source { + self.source = Some(existing.max(source)); + } else { + self.source = Some(source) + } + } + + pub(crate) fn type_id(&self) -> Option<AnyValueId> { + self.type_id + } + + pub(crate) fn infer_type_id(&self, expected: AnyValueId) -> AnyValueId { + self.type_id() + .or_else(|| { + self.vals_flatten() + .map(|v| v.type_id()) + .find(|actual| *actual != expected) + }) + .unwrap_or(expected) + } +} + +impl PartialEq for MatchedArg { + fn eq(&self, other: &MatchedArg) -> bool { + let MatchedArg { + source: self_source, + indices: self_indices, + type_id: self_type_id, + vals: _, + raw_vals: self_raw_vals, + ignore_case: self_ignore_case, + } = self; + let MatchedArg { + source: other_source, + indices: other_indices, + type_id: other_type_id, + vals: _, + raw_vals: other_raw_vals, + ignore_case: other_ignore_case, + } = other; + self_source == other_source + && self_indices == other_indices + && self_type_id == other_type_id + && self_raw_vals == other_raw_vals + && self_ignore_case == other_ignore_case + } +} + +impl Eq for MatchedArg {} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn test_grouped_vals_first() { + let mut m = MatchedArg::new_group(); + m.new_val_group(); + m.new_val_group(); + m.append_val(AnyValue::new(String::from("bbb")), "bbb".into()); + m.append_val(AnyValue::new(String::from("ccc")), "ccc".into()); + assert_eq!(m.first_raw(), Some(&OsString::from("bbb"))); + } +} diff --git a/vendor/clap_builder/src/parser/matches/mod.rs b/vendor/clap_builder/src/parser/matches/mod.rs new file mode 100644 index 0000000..eb86585 --- /dev/null +++ b/vendor/clap_builder/src/parser/matches/mod.rs @@ -0,0 +1,13 @@ +mod arg_matches; +mod matched_arg; +mod value_source; + +pub use arg_matches::IdsRef; +pub use arg_matches::RawValues; +pub use arg_matches::Values; +pub use arg_matches::ValuesRef; +pub use arg_matches::{ArgMatches, Indices}; +pub use value_source::ValueSource; + +pub(crate) use arg_matches::SubCommand; +pub(crate) use matched_arg::MatchedArg; diff --git a/vendor/clap_builder/src/parser/matches/value_source.rs b/vendor/clap_builder/src/parser/matches/value_source.rs new file mode 100644 index 0000000..db45d9c --- /dev/null +++ b/vendor/clap_builder/src/parser/matches/value_source.rs @@ -0,0 +1,17 @@ +/// Origin of the argument's value +#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)] +#[non_exhaustive] +pub enum ValueSource { + /// Value came [`Arg::default_value`][crate::Arg::default_value] + DefaultValue, + /// Value came [`Arg::env`][crate::Arg::env] + EnvVariable, + /// Value was passed in on the command-line + CommandLine, +} + +impl ValueSource { + pub(crate) fn is_explicit(self) -> bool { + self != Self::DefaultValue + } +} diff --git a/vendor/clap_builder/src/parser/mod.rs b/vendor/clap_builder/src/parser/mod.rs new file mode 100644 index 0000000..3e73544 --- /dev/null +++ b/vendor/clap_builder/src/parser/mod.rs @@ -0,0 +1,25 @@ +//! [`Command`][crate::Command] line argument parser + +mod arg_matcher; +mod error; +mod matches; +#[allow(clippy::module_inception)] +mod parser; +mod validator; + +pub(crate) mod features; + +pub(crate) use self::arg_matcher::ArgMatcher; +pub(crate) use self::matches::{MatchedArg, SubCommand}; +pub(crate) use self::parser::Identifier; +pub(crate) use self::parser::PendingArg; +pub(crate) use self::parser::{ParseState, Parser}; +pub(crate) use self::validator::get_possible_values_cli; +pub(crate) use self::validator::Validator; + +pub use self::matches::IdsRef; +pub use self::matches::RawValues; +pub use self::matches::Values; +pub use self::matches::ValuesRef; +pub use self::matches::{ArgMatches, Indices, ValueSource}; +pub use error::MatchesError; diff --git a/vendor/clap_builder/src/parser/parser.rs b/vendor/clap_builder/src/parser/parser.rs new file mode 100644 index 0000000..93616d6 --- /dev/null +++ b/vendor/clap_builder/src/parser/parser.rs @@ -0,0 +1,1622 @@ +// Std +use std::{ + cell::Cell, + ffi::{OsStr, OsString}, +}; + +use clap_lex::OsStrExt as _; + +// Internal +use crate::builder::{Arg, Command}; +use crate::error::Error as ClapError; +use crate::error::Result as ClapResult; +use crate::mkeymap::KeyType; +use crate::output::Usage; +use crate::parser::features::suggestions; +use crate::parser::{ArgMatcher, SubCommand}; +use crate::parser::{Validator, ValueSource}; +use crate::util::AnyValue; +use crate::util::Id; +use crate::ArgAction; +use crate::INTERNAL_ERROR_MSG; + +pub(crate) struct Parser<'cmd> { + cmd: &'cmd mut Command, + cur_idx: Cell<usize>, + /// Index of the previous flag subcommand in a group of flags. + flag_subcmd_at: Option<usize>, + /// Counter indicating the number of items to skip + /// when revisiting the group of flags which includes the flag subcommand. + flag_subcmd_skip: usize, +} + +// Initializing Methods +impl<'cmd> Parser<'cmd> { + pub(crate) fn new(cmd: &'cmd mut Command) -> Self { + Parser { + cmd, + cur_idx: Cell::new(0), + flag_subcmd_at: None, + flag_subcmd_skip: 0, + } + } +} + +// Parsing Methods +impl<'cmd> Parser<'cmd> { + // The actual parsing function + #[allow(clippy::cognitive_complexity)] + pub(crate) fn get_matches_with( + &mut self, + matcher: &mut ArgMatcher, + raw_args: &mut clap_lex::RawArgs, + mut args_cursor: clap_lex::ArgCursor, + ) -> ClapResult<()> { + debug!("Parser::get_matches_with"); + // Verify all positional assertions pass + + let mut subcmd_name: Option<String> = None; + let mut keep_state = false; + let mut parse_state = ParseState::ValuesDone; + let mut pos_counter = 1; + + // Already met any valid arg(then we shouldn't expect subcommands after it). + let mut valid_arg_found = false; + // If the user already passed '--'. Meaning only positional args follow. + let mut trailing_values = false; + + // Count of positional args + let positional_count = self + .cmd + .get_keymap() + .keys() + .filter(|x| x.is_position()) + .count(); + // If any arg sets .last(true) + let contains_last = self.cmd.get_arguments().any(|x| x.is_last_set()); + + while let Some(arg_os) = raw_args.next(&mut args_cursor) { + debug!( + "Parser::get_matches_with: Begin parsing '{:?}'", + arg_os.to_value_os(), + ); + + // Has the user already passed '--'? Meaning only positional args follow + if !trailing_values { + if self.cmd.is_subcommand_precedence_over_arg_set() + || !matches!(parse_state, ParseState::Opt(_) | ParseState::Pos(_)) + { + // Does the arg match a subcommand name, or any of its aliases (if defined) + let sc_name = self.possible_subcommand(arg_os.to_value(), valid_arg_found); + debug!("Parser::get_matches_with: sc={sc_name:?}"); + if let Some(sc_name) = sc_name { + if sc_name == "help" && !self.cmd.is_disable_help_subcommand_set() { + ok!(self.parse_help_subcommand(raw_args.remaining(&mut args_cursor))); + unreachable!("`parse_help_subcommand` always errors"); + } else { + subcmd_name = Some(sc_name.to_owned()); + } + break; + } + } + + if arg_os.is_escape() { + if matches!(&parse_state, ParseState::Opt(opt) | ParseState::Pos(opt) if + self.cmd[opt].is_allow_hyphen_values_set()) + { + // ParseResult::MaybeHyphenValue, do nothing + } else { + debug!("Parser::get_matches_with: setting TrailingVals=true"); + trailing_values = true; + matcher.start_trailing(); + continue; + } + } else if let Some((long_arg, long_value)) = arg_os.to_long() { + let parse_result = ok!(self.parse_long_arg( + matcher, + long_arg, + long_value, + &parse_state, + pos_counter, + &mut valid_arg_found, + )); + debug!("Parser::get_matches_with: After parse_long_arg {parse_result:?}"); + match parse_result { + ParseResult::NoArg => { + unreachable!("`to_long` always has the flag specified") + } + ParseResult::ValuesDone => { + parse_state = ParseState::ValuesDone; + continue; + } + ParseResult::Opt(id) => { + parse_state = ParseState::Opt(id); + continue; + } + ParseResult::FlagSubCommand(name) => { + debug!( + "Parser::get_matches_with: FlagSubCommand found in long arg {:?}", + &name + ); + subcmd_name = Some(name); + break; + } + ParseResult::EqualsNotProvided { arg } => { + let _ = self.resolve_pending(matcher); + return Err(ClapError::no_equals( + self.cmd, + arg, + Usage::new(self.cmd).create_usage_with_title(&[]), + )); + } + ParseResult::NoMatchingArg { arg } => { + let _ = self.resolve_pending(matcher); + let remaining_args: Vec<_> = + raw_args.remaining(&mut args_cursor).collect(); + return Err(self.did_you_mean_error( + &arg, + matcher, + &remaining_args, + trailing_values, + )); + } + ParseResult::UnneededAttachedValue { rest, used, arg } => { + let _ = self.resolve_pending(matcher); + return Err(ClapError::too_many_values( + self.cmd, + rest, + arg, + Usage::new(self.cmd).create_usage_with_title(&used), + )); + } + ParseResult::MaybeHyphenValue => { + // Maybe a hyphen value, do nothing. + } + ParseResult::AttachedValueNotConsumed => { + unreachable!() + } + } + } else if let Some(short_arg) = arg_os.to_short() { + // Arg looks like a short flag, and not a possible number + + // Try to parse short args like normal, if allow_hyphen_values or + // AllowNegativeNumbers is set, parse_short_arg will *not* throw + // an error, and instead return Ok(None) + let parse_result = ok!(self.parse_short_arg( + matcher, + short_arg, + &parse_state, + pos_counter, + &mut valid_arg_found, + )); + // If it's None, we then check if one of those two AppSettings was set + debug!("Parser::get_matches_with: After parse_short_arg {parse_result:?}"); + match parse_result { + ParseResult::NoArg => { + // Is a single dash `-`, try positional. + } + ParseResult::ValuesDone => { + parse_state = ParseState::ValuesDone; + continue; + } + ParseResult::Opt(id) => { + parse_state = ParseState::Opt(id); + continue; + } + ParseResult::FlagSubCommand(name) => { + // If there are more short flags to be processed, we should keep the state, and later + // revisit the current group of short flags skipping the subcommand. + keep_state = self + .flag_subcmd_at + .map(|at| { + raw_args + .seek(&mut args_cursor, clap_lex::SeekFrom::Current(-1)); + // Since we are now saving the current state, the number of flags to skip during state recovery should + // be the current index (`cur_idx`) minus ONE UNIT TO THE LEFT of the starting position. + self.flag_subcmd_skip = self.cur_idx.get() - at + 1; + }) + .is_some(); + + debug!( + "Parser::get_matches_with:FlagSubCommandShort: subcmd_name={}, keep_state={}, flag_subcmd_skip={}", + name, + keep_state, + self.flag_subcmd_skip + ); + + subcmd_name = Some(name); + break; + } + ParseResult::EqualsNotProvided { arg } => { + let _ = self.resolve_pending(matcher); + return Err(ClapError::no_equals( + self.cmd, + arg, + Usage::new(self.cmd).create_usage_with_title(&[]), + )); + } + ParseResult::NoMatchingArg { arg } => { + let _ = self.resolve_pending(matcher); + // We already know it looks like a flag + let suggested_trailing_arg = + !trailing_values && self.cmd.has_positionals(); + return Err(ClapError::unknown_argument( + self.cmd, + arg, + None, + suggested_trailing_arg, + Usage::new(self.cmd).create_usage_with_title(&[]), + )); + } + ParseResult::MaybeHyphenValue => { + // Maybe a hyphen value, do nothing. + } + ParseResult::UnneededAttachedValue { .. } + | ParseResult::AttachedValueNotConsumed => unreachable!(), + } + } + + if let ParseState::Opt(id) = &parse_state { + // Assume this is a value of a previous arg. + + // get the option so we can check the settings + let arg = &self.cmd[id]; + let parse_result = if let Some(parse_result) = + self.check_terminator(arg, arg_os.to_value_os()) + { + parse_result + } else { + let trailing_values = false; + let arg_values = matcher.pending_values_mut(id, None, trailing_values); + arg_values.push(arg_os.to_value_os().to_owned()); + if matcher.needs_more_vals(arg) { + ParseResult::Opt(arg.get_id().clone()) + } else { + ParseResult::ValuesDone + } + }; + parse_state = match parse_result { + ParseResult::Opt(id) => ParseState::Opt(id), + ParseResult::ValuesDone => ParseState::ValuesDone, + _ => unreachable!(), + }; + // get the next value from the iterator + continue; + } + } + + // Correct pos_counter. + pos_counter = { + let is_second_to_last = pos_counter + 1 == positional_count; + + // The last positional argument, or second to last positional + // argument may be set to .multiple_values(true) or `.multiple_occurrences(true)` + let low_index_mults = is_second_to_last + && self.cmd.get_positionals().any(|a| { + a.is_multiple() && (positional_count != a.get_index().unwrap_or(0)) + }) + && self + .cmd + .get_positionals() + .last() + .map(|p_name| !p_name.is_last_set()) + .unwrap_or_default(); + + let is_terminated = self + .cmd + .get_keymap() + .get(&pos_counter) + .map(|a| a.get_value_terminator().is_some()) + .unwrap_or_default(); + + let missing_pos = self.cmd.is_allow_missing_positional_set() + && is_second_to_last + && !trailing_values; + + debug!("Parser::get_matches_with: Positional counter...{pos_counter}"); + debug!("Parser::get_matches_with: Low index multiples...{low_index_mults:?}"); + + if (low_index_mults || missing_pos) && !is_terminated { + let skip_current = if let Some(n) = raw_args.peek(&args_cursor) { + if let Some(arg) = self + .cmd + .get_positionals() + .find(|a| a.get_index() == Some(pos_counter)) + { + // If next value looks like a new_arg or it's a + // subcommand, skip positional argument under current + // pos_counter(which means current value cannot be a + // positional argument with a value next to it), assume + // current value matches the next arg. + self.is_new_arg(&n, arg) + || self + .possible_subcommand(n.to_value(), valid_arg_found) + .is_some() + } else { + true + } + } else { + true + }; + + if skip_current { + debug!("Parser::get_matches_with: Bumping the positional counter..."); + pos_counter + 1 + } else { + pos_counter + } + } else if trailing_values + && (self.cmd.is_allow_missing_positional_set() || contains_last) + { + // Came to -- and one positional has .last(true) set, so we go immediately + // to the last (highest index) positional + debug!("Parser::get_matches_with: .last(true) and --, setting last pos"); + positional_count + } else { + pos_counter + } + }; + + if let Some(arg) = self.cmd.get_keymap().get(&pos_counter) { + if arg.is_last_set() && !trailing_values { + let _ = self.resolve_pending(matcher); + // Its already considered a positional, we don't need to suggest turning it + // into one + let suggested_trailing_arg = false; + return Err(ClapError::unknown_argument( + self.cmd, + arg_os.display().to_string(), + None, + suggested_trailing_arg, + Usage::new(self.cmd).create_usage_with_title(&[]), + )); + } + + if arg.is_trailing_var_arg_set() { + trailing_values = true; + } + + if matcher.pending_arg_id() != Some(arg.get_id()) || !arg.is_multiple_values_set() { + ok!(self.resolve_pending(matcher)); + } + parse_state = + if let Some(parse_result) = self.check_terminator(arg, arg_os.to_value_os()) { + debug_assert_eq!(parse_result, ParseResult::ValuesDone); + pos_counter += 1; + ParseState::ValuesDone + } else { + let arg_values = matcher.pending_values_mut( + arg.get_id(), + Some(Identifier::Index), + trailing_values, + ); + arg_values.push(arg_os.to_value_os().to_owned()); + + // Only increment the positional counter if it doesn't allow multiples + if !arg.is_multiple() { + pos_counter += 1; + ParseState::ValuesDone + } else { + ParseState::Pos(arg.get_id().clone()) + } + }; + valid_arg_found = true; + } else if let Some(external_parser) = + self.cmd.get_external_subcommand_value_parser().cloned() + { + // Get external subcommand name + let sc_name = match arg_os.to_value() { + Ok(s) => s.to_owned(), + Err(_) => { + let _ = self.resolve_pending(matcher); + return Err(ClapError::invalid_utf8( + self.cmd, + Usage::new(self.cmd).create_usage_with_title(&[]), + )); + } + }; + + // Collect the external subcommand args + let mut sc_m = ArgMatcher::new(self.cmd); + sc_m.start_occurrence_of_external(self.cmd); + + for raw_val in raw_args.remaining(&mut args_cursor) { + let val = ok!(external_parser.parse_ref( + self.cmd, + None, + raw_val, + ValueSource::CommandLine + )); + let external_id = Id::from_static_ref(Id::EXTERNAL); + sc_m.add_val_to(&external_id, val, raw_val.to_os_string()); + } + + matcher.subcommand(SubCommand { + name: sc_name, + matches: sc_m.into_inner(), + }); + + ok!(self.resolve_pending(matcher)); + #[cfg(feature = "env")] + ok!(self.add_env(matcher)); + ok!(self.add_defaults(matcher)); + return Validator::new(self.cmd).validate(parse_state, matcher); + } else { + // Start error processing + let _ = self.resolve_pending(matcher); + return Err(self.match_arg_error(&arg_os, valid_arg_found, trailing_values)); + } + } + + if let Some(ref pos_sc_name) = subcmd_name { + let sc_name = self + .cmd + .find_subcommand(pos_sc_name) + .expect(INTERNAL_ERROR_MSG) + .get_name() + .to_owned(); + ok!(self.parse_subcommand(&sc_name, matcher, raw_args, args_cursor, keep_state)); + } + + ok!(self.resolve_pending(matcher)); + #[cfg(feature = "env")] + ok!(self.add_env(matcher)); + ok!(self.add_defaults(matcher)); + Validator::new(self.cmd).validate(parse_state, matcher) + } + + fn match_arg_error( + &self, + arg_os: &clap_lex::ParsedArg<'_>, + valid_arg_found: bool, + trailing_values: bool, + ) -> ClapError { + // If argument follows a `--` + if trailing_values { + // If the arg matches a subcommand name, or any of its aliases (if defined) + if self + .possible_subcommand(arg_os.to_value(), valid_arg_found) + .is_some() + { + return ClapError::unnecessary_double_dash( + self.cmd, + arg_os.display().to_string(), + Usage::new(self.cmd).create_usage_with_title(&[]), + ); + } + } + + let suggested_trailing_arg = !trailing_values + && self.cmd.has_positionals() + && (arg_os.is_long() || arg_os.is_short()); + + if !(self.cmd.is_args_conflicts_with_subcommands_set() && valid_arg_found) { + let candidates = suggestions::did_you_mean( + &arg_os.display().to_string(), + self.cmd.all_subcommand_names(), + ); + // If the argument looks like a subcommand. + if !candidates.is_empty() { + return ClapError::invalid_subcommand( + self.cmd, + arg_os.display().to_string(), + candidates, + self.cmd.get_bin_name_fallback().to_owned(), + suggested_trailing_arg, + Usage::new(self.cmd).create_usage_with_title(&[]), + ); + } + + // If the argument must be a subcommand. + if self.cmd.has_subcommands() + && (!self.cmd.has_positionals() || self.cmd.is_infer_subcommands_set()) + { + return ClapError::unrecognized_subcommand( + self.cmd, + arg_os.display().to_string(), + Usage::new(self.cmd).create_usage_with_title(&[]), + ); + } + } + + ClapError::unknown_argument( + self.cmd, + arg_os.display().to_string(), + None, + suggested_trailing_arg, + Usage::new(self.cmd).create_usage_with_title(&[]), + ) + } + + // Checks if the arg matches a subcommand name, or any of its aliases (if defined) + fn possible_subcommand( + &self, + arg: Result<&str, &OsStr>, + valid_arg_found: bool, + ) -> Option<&str> { + debug!("Parser::possible_subcommand: arg={arg:?}"); + let arg = some!(arg.ok()); + + if !(self.cmd.is_args_conflicts_with_subcommands_set() && valid_arg_found) { + if self.cmd.is_infer_subcommands_set() { + // For subcommand `test`, we accepts it's prefix: `t`, `te`, + // `tes` and `test`. + let mut iter = self.cmd.get_subcommands().filter_map(|s| { + if s.get_name().starts_with(arg) { + return Some(s.get_name()); + } + + // Use find here instead of chaining the iterator because we want to accept + // conflicts in aliases. + s.get_all_aliases().find(|s| s.starts_with(arg)) + }); + + if let name @ Some(_) = iter.next() { + if iter.next().is_none() { + return name; + } + } + } + // Don't use an else here because we want inference to support exact matching even if + // there are conflicts. + if let Some(sc) = self.cmd.find_subcommand(arg) { + return Some(sc.get_name()); + } + } + None + } + + // Checks if the arg matches a long flag subcommand name, or any of its aliases (if defined) + fn possible_long_flag_subcommand(&self, arg: &str) -> Option<&str> { + debug!("Parser::possible_long_flag_subcommand: arg={arg:?}"); + if self.cmd.is_infer_subcommands_set() { + let mut iter = self.cmd.get_subcommands().filter_map(|sc| { + sc.get_long_flag().and_then(|long| { + if long.starts_with(arg) { + Some(sc.get_name()) + } else { + sc.get_all_long_flag_aliases().find_map(|alias| { + if alias.starts_with(arg) { + Some(sc.get_name()) + } else { + None + } + }) + } + }) + }); + + if let name @ Some(_) = iter.next() { + if iter.next().is_none() { + return name; + } + } + } + if let Some(sc_name) = self.cmd.find_long_subcmd(arg) { + return Some(sc_name); + } + None + } + + fn parse_help_subcommand( + &self, + cmds: impl Iterator<Item = &'cmd OsStr>, + ) -> ClapResult<std::convert::Infallible> { + debug!("Parser::parse_help_subcommand"); + + let mut cmd = self.cmd.clone(); + let sc = { + let mut sc = &mut cmd; + + for cmd in cmds { + sc = if let Some(sc_name) = + sc.find_subcommand(cmd).map(|sc| sc.get_name().to_owned()) + { + sc._build_subcommand(&sc_name).unwrap() + } else { + return Err(ClapError::unrecognized_subcommand( + sc, + cmd.to_string_lossy().into_owned(), + Usage::new(sc).create_usage_with_title(&[]), + )); + }; + } + + sc + }; + let parser = Parser::new(sc); + + Err(parser.help_err(true)) + } + + fn is_new_arg(&self, next: &clap_lex::ParsedArg<'_>, current_positional: &Arg) -> bool { + #![allow(clippy::needless_bool)] // Prefer consistent if/else-if ladder + + debug!( + "Parser::is_new_arg: {:?}:{}", + next.to_value_os(), + current_positional.get_id() + ); + + if self.cmd[current_positional.get_id()].is_allow_hyphen_values_set() + || (self.cmd[current_positional.get_id()].is_allow_negative_numbers_set() + && next.is_negative_number()) + { + // If allow hyphen, this isn't a new arg. + debug!("Parser::is_new_arg: Allow hyphen"); + false + } else if next.is_long() { + // If this is a long flag, this is a new arg. + debug!("Parser::is_new_arg: --<something> found"); + true + } else if next.is_short() { + // If this is a short flag, this is a new arg. But a singe '-' by + // itself is a value and typically means "stdin" on unix systems. + debug!("Parser::is_new_arg: -<something> found"); + true + } else { + // Nothing special, this is a value. + debug!("Parser::is_new_arg: value"); + false + } + } + + fn parse_subcommand( + &mut self, + sc_name: &str, + matcher: &mut ArgMatcher, + raw_args: &mut clap_lex::RawArgs, + args_cursor: clap_lex::ArgCursor, + keep_state: bool, + ) -> ClapResult<()> { + debug!("Parser::parse_subcommand"); + + let partial_parsing_enabled = self.cmd.is_ignore_errors_set(); + + if let Some(sc) = self.cmd._build_subcommand(sc_name) { + let mut sc_matcher = ArgMatcher::new(sc); + + debug!( + "Parser::parse_subcommand: About to parse sc={}", + sc.get_name() + ); + + { + let mut p = Parser::new(sc); + // HACK: maintain indexes between parsers + // FlagSubCommand short arg needs to revisit the current short args, but skip the subcommand itself + if keep_state { + p.cur_idx.set(self.cur_idx.get()); + p.flag_subcmd_at = self.flag_subcmd_at; + p.flag_subcmd_skip = self.flag_subcmd_skip; + } + if let Err(error) = p.get_matches_with(&mut sc_matcher, raw_args, args_cursor) { + if partial_parsing_enabled { + debug!("Parser::parse_subcommand: ignored error in subcommand {sc_name}: {error:?}"); + } else { + return Err(error); + } + } + } + matcher.subcommand(SubCommand { + name: sc.get_name().to_owned(), + matches: sc_matcher.into_inner(), + }); + } + Ok(()) + } + + fn parse_long_arg( + &mut self, + matcher: &mut ArgMatcher, + long_arg: Result<&str, &OsStr>, + long_value: Option<&OsStr>, + parse_state: &ParseState, + pos_counter: usize, + valid_arg_found: &mut bool, + ) -> ClapResult<ParseResult> { + // maybe here lifetime should be 'a + debug!("Parser::parse_long_arg"); + + #[allow(clippy::blocks_in_if_conditions)] + if matches!(parse_state, ParseState::Opt(opt) | ParseState::Pos(opt) if + self.cmd[opt].is_allow_hyphen_values_set()) + { + debug!("Parser::parse_long_arg: prior arg accepts hyphenated values",); + return Ok(ParseResult::MaybeHyphenValue); + } + + debug!("Parser::parse_long_arg: Does it contain '='..."); + let long_arg = match long_arg { + Ok(long_arg) => long_arg, + Err(long_arg_os) => { + return Ok(ParseResult::NoMatchingArg { + arg: long_arg_os.to_string_lossy().into_owned(), + }) + } + }; + if long_arg.is_empty() { + debug_assert!( + long_value.is_some(), + "`--` should be filtered out before this point" + ); + } + + let arg = if let Some(arg) = self.cmd.get_keymap().get(long_arg) { + debug!("Parser::parse_long_arg: Found valid arg or flag '{arg}'"); + Some((long_arg, arg)) + } else if self.cmd.is_infer_long_args_set() { + let mut iter = self.cmd.get_arguments().filter_map(|a| { + if let Some(long) = a.get_long() { + if long.starts_with(long_arg) { + return Some((long, a)); + } + } + a.aliases + .iter() + .find_map(|(alias, _)| alias.starts_with(long_arg).then(|| (alias.as_str(), a))) + }); + + iter.next().filter(|_| iter.next().is_none()) + } else { + None + }; + + if let Some((_long_arg, arg)) = arg { + let ident = Identifier::Long; + *valid_arg_found = true; + if arg.is_takes_value_set() { + debug!( + "Parser::parse_long_arg({:?}): Found an arg with value '{:?}'", + long_arg, &long_value + ); + let has_eq = long_value.is_some(); + self.parse_opt_value(ident, long_value, arg, matcher, has_eq) + } else if let Some(rest) = long_value { + let required = self.cmd.required_graph(); + debug!("Parser::parse_long_arg({long_arg:?}): Got invalid literal `{rest:?}`"); + let mut used: Vec<Id> = matcher + .arg_ids() + .filter(|arg_id| { + matcher.check_explicit(arg_id, &crate::builder::ArgPredicate::IsPresent) + }) + .filter(|&n| { + self.cmd + .find(n) + .map(|a| !(a.is_hide_set() || required.contains(a.get_id()))) + .unwrap_or(true) + }) + .cloned() + .collect(); + used.push(arg.get_id().clone()); + + Ok(ParseResult::UnneededAttachedValue { + rest: rest.to_string_lossy().into_owned(), + used, + arg: arg.to_string(), + }) + } else { + debug!("Parser::parse_long_arg({long_arg:?}): Presence validated"); + let trailing_idx = None; + self.react( + Some(ident), + ValueSource::CommandLine, + arg, + vec![], + trailing_idx, + matcher, + ) + } + } else if let Some(sc_name) = self.possible_long_flag_subcommand(long_arg) { + Ok(ParseResult::FlagSubCommand(sc_name.to_string())) + } else if self + .cmd + .get_keymap() + .get(&pos_counter) + .map(|arg| arg.is_allow_hyphen_values_set() && !arg.is_last_set()) + .unwrap_or_default() + { + debug!("Parser::parse_long_args: positional at {pos_counter} allows hyphens"); + Ok(ParseResult::MaybeHyphenValue) + } else { + Ok(ParseResult::NoMatchingArg { + arg: long_arg.to_owned(), + }) + } + } + + fn parse_short_arg( + &mut self, + matcher: &mut ArgMatcher, + mut short_arg: clap_lex::ShortFlags<'_>, + parse_state: &ParseState, + // change this to possible pos_arg when removing the usage of &mut Parser. + pos_counter: usize, + valid_arg_found: &mut bool, + ) -> ClapResult<ParseResult> { + debug!("Parser::parse_short_arg: short_arg={short_arg:?}"); + + #[allow(clippy::blocks_in_if_conditions)] + if matches!(parse_state, ParseState::Opt(opt) | ParseState::Pos(opt) + if self.cmd[opt].is_allow_hyphen_values_set() || (self.cmd[opt].is_allow_negative_numbers_set() && short_arg.is_negative_number())) + { + debug!("Parser::parse_short_args: prior arg accepts hyphenated values",); + return Ok(ParseResult::MaybeHyphenValue); + } else if self + .cmd + .get_keymap() + .get(&pos_counter) + .map(|arg| arg.is_allow_negative_numbers_set()) + .unwrap_or_default() + && short_arg.is_negative_number() + { + debug!("Parser::parse_short_arg: negative number"); + return Ok(ParseResult::MaybeHyphenValue); + } else if self + .cmd + .get_keymap() + .get(&pos_counter) + .map(|arg| arg.is_allow_hyphen_values_set() && !arg.is_last_set()) + .unwrap_or_default() + && short_arg + .clone() + .any(|c| !c.map(|c| self.cmd.contains_short(c)).unwrap_or_default()) + { + debug!("Parser::parse_short_args: positional at {pos_counter} allows hyphens"); + return Ok(ParseResult::MaybeHyphenValue); + } + + let mut ret = ParseResult::NoArg; + + let skip = self.flag_subcmd_skip; + self.flag_subcmd_skip = 0; + let res = short_arg.advance_by(skip); + debug_assert_eq!( + res, + Ok(()), + "tracking of `flag_subcmd_skip` is off for `{short_arg:?}`" + ); + while let Some(c) = short_arg.next_flag() { + let c = match c { + Ok(c) => c, + Err(rest) => { + return Ok(ParseResult::NoMatchingArg { + arg: format!("-{}", rest.to_string_lossy()), + }); + } + }; + debug!("Parser::parse_short_arg:iter:{c}"); + + // Check for matching short options, and return the name if there is no trailing + // concatenated value: -oval + // Option: -o + // Value: val + if let Some(arg) = self.cmd.get_keymap().get(&c) { + let ident = Identifier::Short; + debug!("Parser::parse_short_arg:iter:{c}: Found valid opt or flag"); + *valid_arg_found = true; + if !arg.is_takes_value_set() { + let arg_values = Vec::new(); + let trailing_idx = None; + ret = ok!(self.react( + Some(ident), + ValueSource::CommandLine, + arg, + arg_values, + trailing_idx, + matcher, + )); + continue; + } + + // Check for trailing concatenated value + // + // Cloning the iterator, so we rollback if it isn't there. + let val = short_arg.clone().next_value_os().unwrap_or_default(); + debug!("Parser::parse_short_arg:iter:{c}: val={val:?}, short_arg={short_arg:?}"); + let val = Some(val).filter(|v| !v.is_empty()); + + // Default to "we're expecting a value later". + // + // If attached value is not consumed, we may have more short + // flags to parse, continue. + // + // e.g. `-xvf`, when require_equals && x.min_vals == 0, we don't + // consume the `vf`, even if it's provided as value. + let (val, has_eq) = if let Some(val) = val.and_then(|v| v.strip_prefix("=")) { + (Some(val), true) + } else { + (val, false) + }; + match ok!(self.parse_opt_value(ident, val, arg, matcher, has_eq)) { + ParseResult::AttachedValueNotConsumed => continue, + x => return Ok(x), + } + } + + return if let Some(sc_name) = self.cmd.find_short_subcmd(c) { + debug!("Parser::parse_short_arg:iter:{c}: subcommand={sc_name}"); + // Make sure indices get updated before reading `self.cur_idx` + ok!(self.resolve_pending(matcher)); + self.cur_idx.set(self.cur_idx.get() + 1); + debug!("Parser::parse_short_arg: cur_idx:={}", self.cur_idx.get()); + + let name = sc_name.to_string(); + // Get the index of the previously saved flag subcommand in the group of flags (if exists). + // If it is a new flag subcommand, then the formentioned index should be the current one + // (ie. `cur_idx`), and should be registered. + let cur_idx = self.cur_idx.get(); + self.flag_subcmd_at.get_or_insert(cur_idx); + let done_short_args = short_arg.is_empty(); + if done_short_args { + self.flag_subcmd_at = None; + } + Ok(ParseResult::FlagSubCommand(name)) + } else { + Ok(ParseResult::NoMatchingArg { + arg: format!("-{c}"), + }) + }; + } + Ok(ret) + } + + fn parse_opt_value( + &self, + ident: Identifier, + attached_value: Option<&OsStr>, + arg: &Arg, + matcher: &mut ArgMatcher, + has_eq: bool, + ) -> ClapResult<ParseResult> { + debug!( + "Parser::parse_opt_value; arg={}, val={:?}, has_eq={:?}", + arg.get_id(), + attached_value, + has_eq + ); + debug!("Parser::parse_opt_value; arg.settings={:?}", arg.settings); + + debug!("Parser::parse_opt_value; Checking for val..."); + // require_equals is set, but no '=' is provided, try throwing error. + if arg.is_require_equals_set() && !has_eq { + if arg.get_min_vals() == 0 { + debug!("Requires equals, but min_vals == 0"); + let arg_values = Vec::new(); + let trailing_idx = None; + let react_result = ok!(self.react( + Some(ident), + ValueSource::CommandLine, + arg, + arg_values, + trailing_idx, + matcher, + )); + debug_assert_eq!(react_result, ParseResult::ValuesDone); + if attached_value.is_some() { + Ok(ParseResult::AttachedValueNotConsumed) + } else { + Ok(ParseResult::ValuesDone) + } + } else { + debug!("Requires equals but not provided. Error."); + Ok(ParseResult::EqualsNotProvided { + arg: arg.to_string(), + }) + } + } else if let Some(v) = attached_value { + let arg_values = vec![v.to_owned()]; + let trailing_idx = None; + let react_result = ok!(self.react( + Some(ident), + ValueSource::CommandLine, + arg, + arg_values, + trailing_idx, + matcher, + )); + debug_assert_eq!(react_result, ParseResult::ValuesDone); + // Attached are always done + Ok(ParseResult::ValuesDone) + } else { + debug!("Parser::parse_opt_value: More arg vals required..."); + ok!(self.resolve_pending(matcher)); + let trailing_values = false; + matcher.pending_values_mut(arg.get_id(), Some(ident), trailing_values); + Ok(ParseResult::Opt(arg.get_id().clone())) + } + } + + fn check_terminator(&self, arg: &Arg, val: &OsStr) -> Option<ParseResult> { + if Some(val) == arg.terminator.as_ref().map(|s| OsStr::new(s.as_str())) { + debug!("Parser::check_terminator: terminator={:?}", arg.terminator); + Some(ParseResult::ValuesDone) + } else { + None + } + } + + fn push_arg_values( + &self, + arg: &Arg, + raw_vals: Vec<OsString>, + source: ValueSource, + matcher: &mut ArgMatcher, + ) -> ClapResult<()> { + debug!("Parser::push_arg_values: {raw_vals:?}"); + + for raw_val in raw_vals { + // update the current index because each value is a distinct index to clap + self.cur_idx.set(self.cur_idx.get() + 1); + debug!( + "Parser::add_single_val_to_arg: cur_idx:={}", + self.cur_idx.get() + ); + let value_parser = arg.get_value_parser(); + let val = ok!(value_parser.parse_ref(self.cmd, Some(arg), &raw_val, source)); + + matcher.add_val_to(arg.get_id(), val, raw_val); + matcher.add_index_to(arg.get_id(), self.cur_idx.get()); + } + + Ok(()) + } + + fn resolve_pending(&self, matcher: &mut ArgMatcher) -> ClapResult<()> { + let pending = match matcher.take_pending() { + Some(pending) => pending, + None => { + return Ok(()); + } + }; + + debug!("Parser::resolve_pending: id={:?}", pending.id); + let arg = self.cmd.find(&pending.id).expect(INTERNAL_ERROR_MSG); + let _ = ok!(self.react( + pending.ident, + ValueSource::CommandLine, + arg, + pending.raw_vals, + pending.trailing_idx, + matcher, + )); + + Ok(()) + } + + fn react( + &self, + ident: Option<Identifier>, + source: ValueSource, + arg: &Arg, + mut raw_vals: Vec<OsString>, + mut trailing_idx: Option<usize>, + matcher: &mut ArgMatcher, + ) -> ClapResult<ParseResult> { + ok!(self.resolve_pending(matcher)); + + debug!( + "Parser::react action={:?}, identifier={:?}, source={:?}", + arg.get_action(), + ident, + source + ); + + // Process before `default_missing_values` to avoid it counting as values from the command + // line + if source == ValueSource::CommandLine { + ok!(self.verify_num_args(arg, &raw_vals)); + } + + if raw_vals.is_empty() { + // We assume this case is valid: require equals, but min_vals == 0. + if !arg.default_missing_vals.is_empty() { + debug!("Parser::react: has default_missing_vals"); + trailing_idx = None; + raw_vals.extend( + arg.default_missing_vals + .iter() + .map(|s| s.as_os_str().to_owned()), + ); + } + } + + if let Some(val_delim) = arg.get_value_delimiter() { + if self.cmd.is_dont_delimit_trailing_values_set() && trailing_idx == Some(0) { + // Nothing to do + } else { + let mut val_delim_buffer = [0; 4]; + let val_delim = val_delim.encode_utf8(&mut val_delim_buffer); + let mut split_raw_vals = Vec::with_capacity(raw_vals.len()); + for (i, raw_val) in raw_vals.into_iter().enumerate() { + if !raw_val.contains(val_delim) + || (self.cmd.is_dont_delimit_trailing_values_set() + && trailing_idx == Some(i)) + { + split_raw_vals.push(raw_val); + } else { + split_raw_vals.extend(raw_val.split(val_delim).map(|x| x.to_owned())); + } + } + raw_vals = split_raw_vals + } + } + + match arg.get_action() { + ArgAction::Set => { + if source == ValueSource::CommandLine + && matches!(ident, Some(Identifier::Short) | Some(Identifier::Long)) + { + // Record flag's index + self.cur_idx.set(self.cur_idx.get() + 1); + debug!("Parser::react: cur_idx:={}", self.cur_idx.get()); + } + if matcher.remove(arg.get_id()) + && !(self.cmd.is_args_override_self() || arg.overrides.contains(arg.get_id())) + { + return Err(ClapError::argument_conflict( + self.cmd, + arg.to_string(), + vec![arg.to_string()], + Usage::new(self.cmd).create_usage_with_title(&[]), + )); + } + self.start_custom_arg(matcher, arg, source); + ok!(self.push_arg_values(arg, raw_vals, source, matcher)); + if cfg!(debug_assertions) && matcher.needs_more_vals(arg) { + debug!( + "Parser::react not enough values passed in, leaving it to the validator to complain", + ); + } + Ok(ParseResult::ValuesDone) + } + ArgAction::Append => { + if source == ValueSource::CommandLine + && matches!(ident, Some(Identifier::Short) | Some(Identifier::Long)) + { + // Record flag's index + self.cur_idx.set(self.cur_idx.get() + 1); + debug!("Parser::react: cur_idx:={}", self.cur_idx.get()); + } + self.start_custom_arg(matcher, arg, source); + ok!(self.push_arg_values(arg, raw_vals, source, matcher)); + if cfg!(debug_assertions) && matcher.needs_more_vals(arg) { + debug!( + "Parser::react not enough values passed in, leaving it to the validator to complain", + ); + } + Ok(ParseResult::ValuesDone) + } + ArgAction::SetTrue => { + let raw_vals = if raw_vals.is_empty() { + vec![OsString::from("true")] + } else { + raw_vals + }; + + if matcher.remove(arg.get_id()) + && !(self.cmd.is_args_override_self() || arg.overrides.contains(arg.get_id())) + { + return Err(ClapError::argument_conflict( + self.cmd, + arg.to_string(), + vec![arg.to_string()], + Usage::new(self.cmd).create_usage_with_title(&[]), + )); + } + self.start_custom_arg(matcher, arg, source); + ok!(self.push_arg_values(arg, raw_vals, source, matcher)); + Ok(ParseResult::ValuesDone) + } + ArgAction::SetFalse => { + let raw_vals = if raw_vals.is_empty() { + vec![OsString::from("false")] + } else { + raw_vals + }; + + if matcher.remove(arg.get_id()) + && !(self.cmd.is_args_override_self() || arg.overrides.contains(arg.get_id())) + { + return Err(ClapError::argument_conflict( + self.cmd, + arg.to_string(), + vec![arg.to_string()], + Usage::new(self.cmd).create_usage_with_title(&[]), + )); + } + self.start_custom_arg(matcher, arg, source); + ok!(self.push_arg_values(arg, raw_vals, source, matcher)); + Ok(ParseResult::ValuesDone) + } + ArgAction::Count => { + let raw_vals = if raw_vals.is_empty() { + let existing_value = *matcher + .get_one::<crate::builder::CountType>(arg.get_id().as_str()) + .unwrap_or(&0); + let next_value = existing_value.saturating_add(1); + vec![OsString::from(next_value.to_string())] + } else { + raw_vals + }; + + matcher.remove(arg.get_id()); + self.start_custom_arg(matcher, arg, source); + ok!(self.push_arg_values(arg, raw_vals, source, matcher)); + Ok(ParseResult::ValuesDone) + } + ArgAction::Help => { + let use_long = match ident { + Some(Identifier::Long) => true, + Some(Identifier::Short) => false, + Some(Identifier::Index) => true, + None => true, + }; + debug!("Help: use_long={use_long}"); + Err(self.help_err(use_long)) + } + ArgAction::HelpShort => { + let use_long = false; + debug!("Help: use_long={use_long}"); + Err(self.help_err(use_long)) + } + ArgAction::HelpLong => { + let use_long = true; + debug!("Help: use_long={use_long}"); + Err(self.help_err(use_long)) + } + ArgAction::Version => { + let use_long = match ident { + Some(Identifier::Long) => true, + Some(Identifier::Short) => false, + Some(Identifier::Index) => true, + None => true, + }; + debug!("Version: use_long={use_long}"); + Err(self.version_err(use_long)) + } + } + } + + fn verify_num_args(&self, arg: &Arg, raw_vals: &[OsString]) -> ClapResult<()> { + if self.cmd.is_ignore_errors_set() { + return Ok(()); + } + + let actual = raw_vals.len(); + let expected = arg.get_num_args().expect(INTERNAL_ERROR_MSG); + + if 0 < expected.min_values() && actual == 0 { + // Issue 665 (https://github.com/clap-rs/clap/issues/665) + // Issue 1105 (https://github.com/clap-rs/clap/issues/1105) + return Err(ClapError::empty_value( + self.cmd, + &super::get_possible_values_cli(arg) + .iter() + .filter(|pv| !pv.is_hide_set()) + .map(|n| n.get_name().to_owned()) + .collect::<Vec<_>>(), + arg.to_string(), + )); + } else if let Some(expected) = expected.num_values() { + if expected != actual { + debug!("Validator::validate_arg_num_vals: Sending error WrongNumberOfValues"); + return Err(ClapError::wrong_number_of_values( + self.cmd, + arg.to_string(), + expected, + actual, + Usage::new(self.cmd).create_usage_with_title(&[]), + )); + } + } else if actual < expected.min_values() { + return Err(ClapError::too_few_values( + self.cmd, + arg.to_string(), + expected.min_values(), + actual, + Usage::new(self.cmd).create_usage_with_title(&[]), + )); + } else if expected.max_values() < actual { + debug!("Validator::validate_arg_num_vals: Sending error TooManyValues"); + return Err(ClapError::too_many_values( + self.cmd, + raw_vals + .last() + .expect(INTERNAL_ERROR_MSG) + .to_string_lossy() + .into_owned(), + arg.to_string(), + Usage::new(self.cmd).create_usage_with_title(&[]), + )); + } + + Ok(()) + } + + fn remove_overrides(&self, arg: &Arg, matcher: &mut ArgMatcher) { + debug!("Parser::remove_overrides: id={:?}", arg.id); + for override_id in &arg.overrides { + debug!("Parser::remove_overrides:iter:{override_id:?}: removing"); + matcher.remove(override_id); + } + + // Override anything that can override us + let mut transitive = Vec::new(); + for arg_id in matcher.arg_ids() { + if let Some(overrider) = self.cmd.find(arg_id) { + if overrider.overrides.contains(arg.get_id()) { + transitive.push(overrider.get_id()); + } + } + } + for overrider_id in transitive { + debug!("Parser::remove_overrides:iter:{overrider_id:?}: removing"); + matcher.remove(overrider_id); + } + } + + #[cfg(feature = "env")] + fn add_env(&mut self, matcher: &mut ArgMatcher) -> ClapResult<()> { + debug!("Parser::add_env"); + + for arg in self.cmd.get_arguments() { + // Use env only if the arg was absent among command line args, + // early return if this is not the case. + if matcher.contains(&arg.id) { + debug!("Parser::add_env: Skipping existing arg `{arg}`"); + continue; + } + + debug!("Parser::add_env: Checking arg `{arg}`"); + if let Some((_, Some(ref val))) = arg.env { + debug!("Parser::add_env: Found an opt with value={val:?}"); + let arg_values = vec![val.to_owned()]; + let trailing_idx = None; + let _ = ok!(self.react( + None, + ValueSource::EnvVariable, + arg, + arg_values, + trailing_idx, + matcher, + )); + } + } + + Ok(()) + } + + fn add_defaults(&self, matcher: &mut ArgMatcher) -> ClapResult<()> { + debug!("Parser::add_defaults"); + + for arg in self.cmd.get_arguments() { + debug!("Parser::add_defaults:iter:{}:", arg.get_id()); + ok!(self.add_default_value(arg, matcher)); + } + + Ok(()) + } + + fn add_default_value(&self, arg: &Arg, matcher: &mut ArgMatcher) -> ClapResult<()> { + if !arg.default_vals_ifs.is_empty() { + debug!("Parser::add_default_value: has conditional defaults"); + if !matcher.contains(arg.get_id()) { + for (id, val, default) in arg.default_vals_ifs.iter() { + let add = if let Some(a) = matcher.get(id) { + match val { + crate::builder::ArgPredicate::Equals(v) => { + a.raw_vals_flatten().any(|value| v == value) + } + crate::builder::ArgPredicate::IsPresent => true, + } + } else { + false + }; + + if add { + if let Some(default) = default { + let arg_values = vec![default.to_os_string()]; + let trailing_idx = None; + let _ = ok!(self.react( + None, + ValueSource::DefaultValue, + arg, + arg_values, + trailing_idx, + matcher, + )); + } + return Ok(()); + } + } + } + } else { + debug!("Parser::add_default_value: doesn't have conditional defaults"); + } + + if !arg.default_vals.is_empty() { + debug!( + "Parser::add_default_value:iter:{}: has default vals", + arg.get_id() + ); + if matcher.contains(arg.get_id()) { + debug!("Parser::add_default_value:iter:{}: was used", arg.get_id()); + // do nothing + } else { + debug!( + "Parser::add_default_value:iter:{}: wasn't used", + arg.get_id() + ); + let arg_values: Vec<_> = arg + .default_vals + .iter() + .map(crate::builder::OsStr::to_os_string) + .collect(); + let trailing_idx = None; + let _ = ok!(self.react( + None, + ValueSource::DefaultValue, + arg, + arg_values, + trailing_idx, + matcher, + )); + } + } else { + debug!( + "Parser::add_default_value:iter:{}: doesn't have default vals", + arg.get_id() + ); + + // do nothing + } + + Ok(()) + } + + fn start_custom_arg(&self, matcher: &mut ArgMatcher, arg: &Arg, source: ValueSource) { + if source == ValueSource::CommandLine { + // With each new occurrence, remove overrides from prior occurrences + self.remove_overrides(arg, matcher); + } + matcher.start_custom_arg(arg, source); + if source.is_explicit() { + for group in self.cmd.groups_for_arg(arg.get_id()) { + matcher.start_custom_group(group.clone(), source); + matcher.add_val_to( + &group, + AnyValue::new(arg.get_id().clone()), + OsString::from(arg.get_id().as_str()), + ); + } + } + } +} + +// Error, Help, and Version Methods +impl<'cmd> Parser<'cmd> { + /// Is only used for the long flag(which is the only one needs fuzzy searching) + fn did_you_mean_error( + &mut self, + arg: &str, + matcher: &mut ArgMatcher, + remaining_args: &[&OsStr], + trailing_values: bool, + ) -> ClapError { + debug!("Parser::did_you_mean_error: arg={arg}"); + // Didn't match a flag or option + let longs = self + .cmd + .get_keymap() + .keys() + .filter_map(|x| match x { + KeyType::Long(l) => Some(l.to_string_lossy().into_owned()), + _ => None, + }) + .collect::<Vec<_>>(); + debug!("Parser::did_you_mean_error: longs={longs:?}"); + + let did_you_mean = suggestions::did_you_mean_flag( + arg, + remaining_args, + longs.iter().map(|x| &x[..]), + self.cmd.get_subcommands_mut(), + ); + + // Add the arg to the matches to build a proper usage string + if let Some((name, _)) = did_you_mean.as_ref() { + if let Some(arg) = self.cmd.get_keymap().get(&name.as_ref()) { + self.start_custom_arg(matcher, arg, ValueSource::CommandLine); + } + } + let did_you_mean = did_you_mean.map(|(arg, cmd)| (format!("--{arg}"), cmd)); + + let required = self.cmd.required_graph(); + let used: Vec<Id> = matcher + .arg_ids() + .filter(|arg_id| { + matcher.check_explicit(arg_id, &crate::builder::ArgPredicate::IsPresent) + }) + .filter(|n| self.cmd.find(n).map(|a| !a.is_hide_set()).unwrap_or(true)) + .cloned() + .collect(); + + // `did_you_mean` is a lot more likely and should cause us to skip the `--` suggestion + // + // In theory, this is only called for `--long`s, so we don't need to check + let suggested_trailing_arg = + did_you_mean.is_none() && !trailing_values && self.cmd.has_positionals(); + ClapError::unknown_argument( + self.cmd, + format!("--{arg}"), + did_you_mean, + suggested_trailing_arg, + Usage::new(self.cmd) + .required(&required) + .create_usage_with_title(&used), + ) + } + + fn help_err(&self, use_long: bool) -> ClapError { + let styled = self.cmd.write_help_err(use_long); + ClapError::display_help(self.cmd, styled) + } + + fn version_err(&self, use_long: bool) -> ClapError { + let styled = self.cmd.write_version_err(use_long); + ClapError::display_version(self.cmd, styled) + } +} + +#[derive(Debug, PartialEq, Eq)] +pub(crate) enum ParseState { + ValuesDone, + Opt(Id), + Pos(Id), +} + +/// Recoverable Parsing results. +#[derive(Debug, PartialEq, Clone)] +#[must_use] +enum ParseResult { + FlagSubCommand(String), + Opt(Id), + ValuesDone, + /// Value attached to the short flag is not consumed(e.g. 'u' for `-cu` is + /// not consumed). + AttachedValueNotConsumed, + /// This long flag doesn't need a value but is provided one. + UnneededAttachedValue { + rest: String, + used: Vec<Id>, + arg: String, + }, + /// This flag might be an hyphen Value. + MaybeHyphenValue, + /// Equals required but not provided. + EqualsNotProvided { + arg: String, + }, + /// Failed to match a Arg. + NoMatchingArg { + arg: String, + }, + /// No argument found e.g. parser is given `-` when parsing a flag. + NoArg, +} + +#[derive(Clone, Debug, PartialEq, Eq)] +pub(crate) struct PendingArg { + pub(crate) id: Id, + pub(crate) ident: Option<Identifier>, + pub(crate) raw_vals: Vec<OsString>, + pub(crate) trailing_idx: Option<usize>, +} + +#[derive(Copy, Clone, Debug, PartialEq, Eq)] +pub(crate) enum Identifier { + Short, + Long, + Index, +} diff --git a/vendor/clap_builder/src/parser/validator.rs b/vendor/clap_builder/src/parser/validator.rs new file mode 100644 index 0000000..55f4633 --- /dev/null +++ b/vendor/clap_builder/src/parser/validator.rs @@ -0,0 +1,561 @@ +// Internal +use crate::builder::StyledStr; +use crate::builder::{Arg, ArgGroup, ArgPredicate, Command, PossibleValue}; +use crate::error::{Error, Result as ClapResult}; +use crate::output::Usage; +use crate::parser::{ArgMatcher, ParseState}; +use crate::util::ChildGraph; +use crate::util::FlatMap; +use crate::util::FlatSet; +use crate::util::Id; +use crate::INTERNAL_ERROR_MSG; + +pub(crate) struct Validator<'cmd> { + cmd: &'cmd Command, + required: ChildGraph<Id>, +} + +impl<'cmd> Validator<'cmd> { + pub(crate) fn new(cmd: &'cmd Command) -> Self { + let required = cmd.required_graph(); + Validator { cmd, required } + } + + pub(crate) fn validate( + &mut self, + parse_state: ParseState, + matcher: &mut ArgMatcher, + ) -> ClapResult<()> { + debug!("Validator::validate"); + let conflicts = Conflicts::with_args(self.cmd, matcher); + let has_subcmd = matcher.subcommand_name().is_some(); + + if let ParseState::Opt(a) = parse_state { + debug!("Validator::validate: needs_val_of={a:?}"); + + let o = &self.cmd[&a]; + let should_err = if let Some(v) = matcher.args.get(o.get_id()) { + v.all_val_groups_empty() && o.get_min_vals() != 0 + } else { + true + }; + if should_err { + return Err(Error::empty_value( + self.cmd, + &get_possible_values_cli(o) + .iter() + .filter(|pv| !pv.is_hide_set()) + .map(|n| n.get_name().to_owned()) + .collect::<Vec<_>>(), + o.to_string(), + )); + } + } + + if !has_subcmd && self.cmd.is_arg_required_else_help_set() { + let num_user_values = matcher + .args() + .filter(|(_, matched)| matched.check_explicit(&ArgPredicate::IsPresent)) + .count(); + if num_user_values == 0 { + let message = self.cmd.write_help_err(false); + return Err(Error::display_help_error(self.cmd, message)); + } + } + if !has_subcmd && self.cmd.is_subcommand_required_set() { + let bn = self.cmd.get_bin_name_fallback(); + return Err(Error::missing_subcommand( + self.cmd, + bn.to_string(), + self.cmd + .all_subcommand_names() + .map(|s| s.to_owned()) + .collect::<Vec<_>>(), + Usage::new(self.cmd) + .required(&self.required) + .create_usage_with_title(&[]), + )); + } + + ok!(self.validate_conflicts(matcher, &conflicts)); + if !(self.cmd.is_subcommand_negates_reqs_set() && has_subcmd) { + ok!(self.validate_required(matcher, &conflicts)); + } + + Ok(()) + } + + fn validate_conflicts( + &mut self, + matcher: &ArgMatcher, + conflicts: &Conflicts, + ) -> ClapResult<()> { + debug!("Validator::validate_conflicts"); + + ok!(self.validate_exclusive(matcher)); + + for (arg_id, _) in matcher + .args() + .filter(|(_, matched)| matched.check_explicit(&ArgPredicate::IsPresent)) + .filter(|(arg_id, _)| self.cmd.find(arg_id).is_some()) + { + debug!("Validator::validate_conflicts::iter: id={arg_id:?}"); + let conflicts = conflicts.gather_conflicts(self.cmd, arg_id); + ok!(self.build_conflict_err(arg_id, &conflicts, matcher)); + } + + Ok(()) + } + + fn validate_exclusive(&self, matcher: &ArgMatcher) -> ClapResult<()> { + debug!("Validator::validate_exclusive"); + let args_count = matcher + .args() + .filter(|(arg_id, matched)| { + matched.check_explicit(&crate::builder::ArgPredicate::IsPresent) + // Avoid including our own groups by checking none of them. If a group is present, the + // args for the group will be. + && self.cmd.find(arg_id).is_some() + }) + .count(); + if args_count <= 1 { + // Nothing present to conflict with + return Ok(()); + } + + matcher + .args() + .filter(|(_, matched)| matched.check_explicit(&crate::builder::ArgPredicate::IsPresent)) + .filter_map(|(id, _)| { + debug!("Validator::validate_exclusive:iter:{id:?}"); + self.cmd + .find(id) + // Find `arg`s which are exclusive but also appear with other args. + .filter(|&arg| arg.is_exclusive_set() && args_count > 1) + }) + .next() + .map(|arg| { + // Throw an error for the first conflict found. + Err(Error::argument_conflict( + self.cmd, + arg.to_string(), + Vec::new(), + Usage::new(self.cmd) + .required(&self.required) + .create_usage_with_title(&[]), + )) + }) + .unwrap_or(Ok(())) + } + + fn build_conflict_err( + &self, + name: &Id, + conflict_ids: &[Id], + matcher: &ArgMatcher, + ) -> ClapResult<()> { + if conflict_ids.is_empty() { + return Ok(()); + } + + debug!("Validator::build_conflict_err: name={name:?}"); + let mut seen = FlatSet::new(); + let conflicts = conflict_ids + .iter() + .flat_map(|c_id| { + if self.cmd.find_group(c_id).is_some() { + self.cmd.unroll_args_in_group(c_id) + } else { + vec![c_id.clone()] + } + }) + .filter_map(|c_id| { + seen.insert(c_id.clone()).then(|| { + let c_arg = self.cmd.find(&c_id).expect(INTERNAL_ERROR_MSG); + c_arg.to_string() + }) + }) + .collect(); + + let former_arg = self.cmd.find(name).expect(INTERNAL_ERROR_MSG); + let usg = self.build_conflict_err_usage(matcher, conflict_ids); + Err(Error::argument_conflict( + self.cmd, + former_arg.to_string(), + conflicts, + usg, + )) + } + + fn build_conflict_err_usage( + &self, + matcher: &ArgMatcher, + conflicting_keys: &[Id], + ) -> Option<StyledStr> { + let used_filtered: Vec<Id> = matcher + .args() + .filter(|(_, matched)| matched.check_explicit(&ArgPredicate::IsPresent)) + .map(|(n, _)| n) + .filter(|n| { + // Filter out the args we don't want to specify. + self.cmd + .find(n) + .map(|a| !a.is_hide_set()) + .unwrap_or_default() + }) + .filter(|key| !conflicting_keys.contains(key)) + .cloned() + .collect(); + let required: Vec<Id> = used_filtered + .iter() + .filter_map(|key| self.cmd.find(key)) + .flat_map(|arg| arg.requires.iter().map(|item| &item.1)) + .filter(|key| !used_filtered.contains(key) && !conflicting_keys.contains(key)) + .chain(used_filtered.iter()) + .cloned() + .collect(); + Usage::new(self.cmd) + .required(&self.required) + .create_usage_with_title(&required) + } + + fn gather_requires(&mut self, matcher: &ArgMatcher) { + debug!("Validator::gather_requires"); + for (name, matched) in matcher + .args() + .filter(|(_, matched)| matched.check_explicit(&ArgPredicate::IsPresent)) + { + debug!("Validator::gather_requires:iter:{name:?}"); + if let Some(arg) = self.cmd.find(name) { + let is_relevant = |(val, req_arg): &(ArgPredicate, Id)| -> Option<Id> { + let required = matched.check_explicit(val); + required.then(|| req_arg.clone()) + }; + + for req in self.cmd.unroll_arg_requires(is_relevant, arg.get_id()) { + self.required.insert(req); + } + } else if let Some(g) = self.cmd.find_group(name) { + debug!("Validator::gather_requires:iter:{name:?}:group"); + for r in &g.requires { + self.required.insert(r.clone()); + } + } + } + } + + fn validate_required(&mut self, matcher: &ArgMatcher, conflicts: &Conflicts) -> ClapResult<()> { + debug!("Validator::validate_required: required={:?}", self.required); + self.gather_requires(matcher); + + let mut missing_required = Vec::new(); + let mut highest_index = 0; + + let is_exclusive_present = matcher + .args() + .filter(|(_, matched)| matched.check_explicit(&ArgPredicate::IsPresent)) + .any(|(id, _)| { + self.cmd + .find(id) + .map(|arg| arg.is_exclusive_set()) + .unwrap_or_default() + }); + debug!("Validator::validate_required: is_exclusive_present={is_exclusive_present}"); + + for arg_or_group in self + .required + .iter() + .filter(|r| !matcher.check_explicit(r, &ArgPredicate::IsPresent)) + { + debug!("Validator::validate_required:iter:aog={arg_or_group:?}"); + if let Some(arg) = self.cmd.find(arg_or_group) { + debug!("Validator::validate_required:iter: This is an arg"); + if !is_exclusive_present && !self.is_missing_required_ok(arg, conflicts) { + debug!( + "Validator::validate_required:iter: Missing {:?}", + arg.get_id() + ); + missing_required.push(arg.get_id().clone()); + if !arg.is_last_set() { + highest_index = highest_index.max(arg.get_index().unwrap_or(0)); + } + } + } else if let Some(group) = self.cmd.find_group(arg_or_group) { + debug!("Validator::validate_required:iter: This is a group"); + if !self + .cmd + .unroll_args_in_group(&group.id) + .iter() + .any(|a| matcher.check_explicit(a, &ArgPredicate::IsPresent)) + { + debug!( + "Validator::validate_required:iter: Missing {:?}", + group.get_id() + ); + missing_required.push(group.get_id().clone()); + } + } + } + + // Validate the conditionally required args + for a in self + .cmd + .get_arguments() + .filter(|a| !matcher.check_explicit(a.get_id(), &ArgPredicate::IsPresent)) + { + let mut required = false; + + for (other, val) in &a.r_ifs { + if matcher.check_explicit(other, &ArgPredicate::Equals(val.into())) { + debug!( + "Validator::validate_required:iter: Missing {:?}", + a.get_id() + ); + required = true; + } + } + + let match_all = a.r_ifs_all.iter().all(|(other, val)| { + matcher.check_explicit(other, &ArgPredicate::Equals(val.into())) + }); + if match_all && !a.r_ifs_all.is_empty() { + debug!( + "Validator::validate_required:iter: Missing {:?}", + a.get_id() + ); + required = true; + } + + if (!a.r_unless.is_empty() || !a.r_unless_all.is_empty()) + && self.fails_arg_required_unless(a, matcher) + { + debug!( + "Validator::validate_required:iter: Missing {:?}", + a.get_id() + ); + required = true; + } + + if required { + missing_required.push(a.get_id().clone()); + if !a.is_last_set() { + highest_index = highest_index.max(a.get_index().unwrap_or(0)); + } + } + } + + // For display purposes, include all of the preceding positional arguments + if !self.cmd.is_allow_missing_positional_set() { + for pos in self + .cmd + .get_positionals() + .filter(|a| !matcher.check_explicit(a.get_id(), &ArgPredicate::IsPresent)) + { + if pos.get_index() < Some(highest_index) { + debug!( + "Validator::validate_required:iter: Missing {:?}", + pos.get_id() + ); + missing_required.push(pos.get_id().clone()); + } + } + } + + if !missing_required.is_empty() { + ok!(self.missing_required_error(matcher, missing_required)); + } + + Ok(()) + } + + fn is_missing_required_ok(&self, a: &Arg, conflicts: &Conflicts) -> bool { + debug!("Validator::is_missing_required_ok: {}", a.get_id()); + if !conflicts.gather_conflicts(self.cmd, a.get_id()).is_empty() { + debug!("Validator::is_missing_required_ok: true (self)"); + return true; + } + for group_id in self.cmd.groups_for_arg(a.get_id()) { + if !conflicts.gather_conflicts(self.cmd, &group_id).is_empty() { + debug!("Validator::is_missing_required_ok: true ({group_id})"); + return true; + } + } + false + } + + // Failing a required unless means, the arg's "unless" wasn't present, and neither were they + fn fails_arg_required_unless(&self, a: &Arg, matcher: &ArgMatcher) -> bool { + debug!("Validator::fails_arg_required_unless: a={:?}", a.get_id()); + let exists = |id| matcher.check_explicit(id, &ArgPredicate::IsPresent); + + (a.r_unless_all.is_empty() || !a.r_unless_all.iter().all(exists)) + && !a.r_unless.iter().any(exists) + } + + // `req_args`: an arg to include in the error even if not used + fn missing_required_error( + &self, + matcher: &ArgMatcher, + raw_req_args: Vec<Id>, + ) -> ClapResult<()> { + debug!("Validator::missing_required_error; incl={raw_req_args:?}"); + debug!( + "Validator::missing_required_error: reqs={:?}", + self.required + ); + + let usg = Usage::new(self.cmd).required(&self.required); + + let req_args = { + #[cfg(feature = "usage")] + { + usg.get_required_usage_from(&raw_req_args, Some(matcher), true) + .into_iter() + .map(|s| s.to_string()) + .collect::<Vec<_>>() + } + + #[cfg(not(feature = "usage"))] + { + raw_req_args + .iter() + .map(|id| { + if let Some(arg) = self.cmd.find(id) { + arg.to_string() + } else if let Some(_group) = self.cmd.find_group(id) { + self.cmd.format_group(id).to_string() + } else { + debug_assert!(false, "id={id:?} is unknown"); + "".to_owned() + } + }) + .collect::<Vec<_>>() + } + }; + + debug!("Validator::missing_required_error: req_args={req_args:#?}"); + + let used: Vec<Id> = matcher + .args() + .filter(|(_, matched)| matched.check_explicit(&ArgPredicate::IsPresent)) + .map(|(n, _)| n) + .filter(|n| { + // Filter out the args we don't want to specify. + self.cmd + .find(n) + .map(|a| !a.is_hide_set()) + .unwrap_or_default() + }) + .cloned() + .chain(raw_req_args) + .collect(); + + Err(Error::missing_required_argument( + self.cmd, + req_args, + usg.create_usage_with_title(&used), + )) + } +} + +#[derive(Default, Clone, Debug)] +struct Conflicts { + potential: FlatMap<Id, Vec<Id>>, +} + +impl Conflicts { + fn with_args(cmd: &Command, matcher: &ArgMatcher) -> Self { + let mut potential = FlatMap::new(); + potential.extend_unchecked( + matcher + .args() + .filter(|(_, matched)| matched.check_explicit(&ArgPredicate::IsPresent)) + .map(|(id, _)| { + let conf = gather_direct_conflicts(cmd, id); + (id.clone(), conf) + }), + ); + Self { potential } + } + + fn gather_conflicts(&self, cmd: &Command, arg_id: &Id) -> Vec<Id> { + debug!("Conflicts::gather_conflicts: arg={arg_id:?}"); + let mut conflicts = Vec::new(); + + let arg_id_conflicts_storage; + let arg_id_conflicts = if let Some(arg_id_conflicts) = self.get_direct_conflicts(arg_id) { + arg_id_conflicts + } else { + // `is_missing_required_ok` is a case where we check not-present args for conflicts + arg_id_conflicts_storage = gather_direct_conflicts(cmd, arg_id); + &arg_id_conflicts_storage + }; + for (other_arg_id, other_arg_id_conflicts) in self.potential.iter() { + if arg_id == other_arg_id { + continue; + } + + if arg_id_conflicts.contains(other_arg_id) { + conflicts.push(other_arg_id.clone()); + } + if other_arg_id_conflicts.contains(arg_id) { + conflicts.push(other_arg_id.clone()); + } + } + + debug!("Conflicts::gather_conflicts: conflicts={conflicts:?}"); + conflicts + } + + fn get_direct_conflicts(&self, arg_id: &Id) -> Option<&[Id]> { + self.potential.get(arg_id).map(Vec::as_slice) + } +} + +fn gather_direct_conflicts(cmd: &Command, id: &Id) -> Vec<Id> { + let conf = if let Some(arg) = cmd.find(id) { + gather_arg_direct_conflicts(cmd, arg) + } else if let Some(group) = cmd.find_group(id) { + gather_group_direct_conflicts(group) + } else { + debug_assert!(false, "id={id:?} is unknown"); + Vec::new() + }; + debug!("Conflicts::gather_direct_conflicts id={id:?}, conflicts={conf:?}",); + conf +} + +fn gather_arg_direct_conflicts(cmd: &Command, arg: &Arg) -> Vec<Id> { + let mut conf = arg.blacklist.clone(); + for group_id in cmd.groups_for_arg(arg.get_id()) { + let group = cmd.find_group(&group_id).expect(INTERNAL_ERROR_MSG); + conf.extend(group.conflicts.iter().cloned()); + if !group.multiple { + for member_id in &group.args { + if member_id != arg.get_id() { + conf.push(member_id.clone()); + } + } + } + } + + // Overrides are implicitly conflicts + conf.extend(arg.overrides.iter().cloned()); + + conf +} + +fn gather_group_direct_conflicts(group: &ArgGroup) -> Vec<Id> { + group.conflicts.clone() +} + +pub(crate) fn get_possible_values_cli(a: &Arg) -> Vec<PossibleValue> { + if !a.is_takes_value_set() { + vec![] + } else { + a.get_value_parser() + .possible_values() + .map(|pvs| pvs.collect()) + .unwrap_or_default() + } +} diff --git a/vendor/clap_builder/src/util/any_value.rs b/vendor/clap_builder/src/util/any_value.rs new file mode 100644 index 0000000..19aa82b --- /dev/null +++ b/vendor/clap_builder/src/util/any_value.rs @@ -0,0 +1,127 @@ +#[derive(Clone)] +pub(crate) struct AnyValue { + inner: std::sync::Arc<dyn std::any::Any + Send + Sync + 'static>, + // While we can extract `TypeId` from `inner`, the debug repr is of a number, so let's track + // the type_name in debug builds. + id: AnyValueId, +} + +impl AnyValue { + pub(crate) fn new<V: std::any::Any + Clone + Send + Sync + 'static>(inner: V) -> Self { + let id = AnyValueId::of::<V>(); + let inner = std::sync::Arc::new(inner); + Self { inner, id } + } + + pub(crate) fn downcast_ref<T: std::any::Any + Clone + Send + Sync + 'static>( + &self, + ) -> Option<&T> { + self.inner.downcast_ref::<T>() + } + + pub(crate) fn downcast_into<T: std::any::Any + Clone + Send + Sync>(self) -> Result<T, Self> { + let id = self.id; + let value = + ok!(std::sync::Arc::downcast::<T>(self.inner).map_err(|inner| Self { inner, id })); + let value = std::sync::Arc::try_unwrap(value).unwrap_or_else(|arc| (*arc).clone()); + Ok(value) + } + + pub(crate) fn type_id(&self) -> AnyValueId { + self.id + } +} + +impl std::fmt::Debug for AnyValue { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> Result<(), std::fmt::Error> { + f.debug_struct("AnyValue").field("inner", &self.id).finish() + } +} + +#[derive(Copy, Clone)] +pub struct AnyValueId { + type_id: std::any::TypeId, + #[cfg(debug_assertions)] + type_name: &'static str, +} + +impl AnyValueId { + pub(crate) fn of<A: ?Sized + 'static>() -> Self { + Self { + type_id: std::any::TypeId::of::<A>(), + #[cfg(debug_assertions)] + type_name: std::any::type_name::<A>(), + } + } +} + +impl PartialEq for AnyValueId { + fn eq(&self, other: &Self) -> bool { + self.type_id == other.type_id + } +} + +impl Eq for AnyValueId {} + +impl PartialOrd for AnyValueId { + fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> { + Some(self.cmp(other)) + } +} + +impl PartialEq<std::any::TypeId> for AnyValueId { + fn eq(&self, other: &std::any::TypeId) -> bool { + self.type_id == *other + } +} + +impl Ord for AnyValueId { + fn cmp(&self, other: &Self) -> std::cmp::Ordering { + self.type_id.cmp(&other.type_id) + } +} + +impl std::hash::Hash for AnyValueId { + fn hash<H: std::hash::Hasher>(&self, state: &mut H) { + self.type_id.hash(state); + } +} + +impl std::fmt::Debug for AnyValueId { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> Result<(), std::fmt::Error> { + #[cfg(not(debug_assertions))] + { + self.type_id.fmt(f) + } + #[cfg(debug_assertions)] + { + f.debug_struct(self.type_name).finish() + } + } +} + +impl<'a, A: ?Sized + 'static> From<&'a A> for AnyValueId { + fn from(_: &'a A) -> Self { + Self::of::<A>() + } +} + +#[cfg(test)] +mod test { + #[test] + #[cfg(debug_assertions)] + fn debug_impl() { + use super::*; + + assert_eq!(format!("{:?}", AnyValue::new(5)), "AnyValue { inner: i32 }"); + } + + #[test] + fn eq_to_type_id() { + use super::*; + + let any_value_id = AnyValueId::of::<i32>(); + let type_id = std::any::TypeId::of::<i32>(); + assert_eq!(any_value_id, type_id); + } +} diff --git a/vendor/clap_builder/src/util/color.rs b/vendor/clap_builder/src/util/color.rs new file mode 100644 index 0000000..d13a6df --- /dev/null +++ b/vendor/clap_builder/src/util/color.rs @@ -0,0 +1,116 @@ +use crate::builder::PossibleValue; +use crate::derive::ValueEnum; + +/// Represents the color preferences for program output +#[derive(Debug, Copy, Clone, Eq, PartialEq)] +pub enum ColorChoice { + /// Enables colored output only when the output is going to a terminal or TTY. + /// + /// **NOTE:** This is the default behavior of `clap`. + /// + /// # Platform Specific + /// + /// This setting only applies to Unix, Linux, and macOS (i.e. non-Windows platforms). + /// + /// # Examples + /// + /// ```rust + /// # #[cfg(feature = "color")] { + /// # use clap_builder as clap; + /// # use clap::{Command, ColorChoice}; + /// Command::new("myprog") + /// .color(ColorChoice::Auto) + /// .get_matches(); + /// # } + /// ``` + Auto, + + /// Enables colored output regardless of whether or not the output is going to a terminal/TTY. + /// + /// # Platform Specific + /// + /// This setting only applies to Unix, Linux, and macOS (i.e. non-Windows platforms). + /// + /// # Examples + /// + /// ```rust + /// # #[cfg(feature = "color")] { + /// # use clap_builder as clap; + /// # use clap::{Command, ColorChoice}; + /// Command::new("myprog") + /// .color(ColorChoice::Always) + /// .get_matches(); + /// # } + /// ``` + Always, + + /// Disables colored output no matter if the output is going to a terminal/TTY, or not. + /// + /// # Platform Specific + /// + /// This setting only applies to Unix, Linux, and macOS (i.e. non-Windows platforms) + /// + /// # Examples + /// + /// ```rust + /// # #[cfg(feature = "color")] { + /// # use clap_builder as clap; + /// # use clap::{Command, ColorChoice}; + /// Command::new("myprog") + /// .color(ColorChoice::Never) + /// .get_matches(); + /// # } + /// ``` + Never, +} + +impl ColorChoice { + /// Report all `possible_values` + pub fn possible_values() -> impl Iterator<Item = PossibleValue> { + Self::value_variants() + .iter() + .filter_map(ValueEnum::to_possible_value) + } +} + +impl Default for ColorChoice { + fn default() -> Self { + Self::Auto + } +} + +impl std::fmt::Display for ColorChoice { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + self.to_possible_value() + .expect("no values are skipped") + .get_name() + .fmt(f) + } +} + +impl std::str::FromStr for ColorChoice { + type Err = String; + + fn from_str(s: &str) -> Result<Self, Self::Err> { + for variant in Self::value_variants() { + if variant.to_possible_value().unwrap().matches(s, false) { + return Ok(*variant); + } + } + Err(format!("invalid variant: {s}")) + } +} + +impl ValueEnum for ColorChoice { + fn value_variants<'a>() -> &'a [Self] { + &[Self::Auto, Self::Always, Self::Never] + } + + fn to_possible_value(&self) -> Option<PossibleValue> { + Some(match self { + Self::Auto => PossibleValue::new("auto"), + Self::Always => PossibleValue::new("always"), + Self::Never => PossibleValue::new("never"), + }) + } +} diff --git a/vendor/clap_builder/src/util/flat_map.rs b/vendor/clap_builder/src/util/flat_map.rs new file mode 100644 index 0000000..468f0a9 --- /dev/null +++ b/vendor/clap_builder/src/util/flat_map.rs @@ -0,0 +1,254 @@ +#![allow(dead_code)] + +use std::borrow::Borrow; + +/// Flat (Vec) backed map +/// +/// This preserves insertion order +#[derive(Clone, Debug, PartialEq, Eq)] +pub(crate) struct FlatMap<K, V> { + keys: Vec<K>, + values: Vec<V>, +} + +impl<K: PartialEq + Eq, V> FlatMap<K, V> { + pub(crate) fn new() -> Self { + Default::default() + } + + pub(crate) fn insert(&mut self, key: K, mut value: V) -> Option<V> { + for (index, existing) in self.keys.iter().enumerate() { + if *existing == key { + std::mem::swap(&mut self.values[index], &mut value); + return Some(value); + } + } + + self.insert_unchecked(key, value); + None + } + + pub(crate) fn insert_unchecked(&mut self, key: K, value: V) { + self.keys.push(key); + self.values.push(value); + } + + pub(crate) fn extend_unchecked(&mut self, iter: impl IntoIterator<Item = (K, V)>) { + for (key, value) in iter { + self.insert_unchecked(key, value); + } + } + + pub fn contains_key<Q: ?Sized>(&self, key: &Q) -> bool + where + K: Borrow<Q>, + Q: Eq, + { + for existing in &self.keys { + if existing.borrow() == key { + return true; + } + } + false + } + + pub fn remove<Q: ?Sized>(&mut self, key: &Q) -> Option<V> + where + K: Borrow<Q>, + Q: std::hash::Hash + Eq, + { + self.remove_entry(key).map(|(_, v)| v) + } + + pub fn remove_entry<Q: ?Sized>(&mut self, key: &Q) -> Option<(K, V)> + where + K: Borrow<Q>, + Q: std::hash::Hash + Eq, + { + let index = some!(self + .keys + .iter() + .enumerate() + .find_map(|(i, k)| (k.borrow() == key).then_some(i))); + let key = self.keys.remove(index); + let value = self.values.remove(index); + Some((key, value)) + } + + pub(crate) fn is_empty(&self) -> bool { + self.keys.is_empty() + } + + pub fn entry(&mut self, key: K) -> Entry<K, V> { + for (index, existing) in self.keys.iter().enumerate() { + if *existing == key { + return Entry::Occupied(OccupiedEntry { v: self, index }); + } + } + Entry::Vacant(VacantEntry { v: self, key }) + } + + pub fn get<Q: ?Sized>(&self, k: &Q) -> Option<&V> + where + K: Borrow<Q>, + Q: Eq, + { + for (index, existing) in self.keys.iter().enumerate() { + if existing.borrow() == k { + return Some(&self.values[index]); + } + } + None + } + + pub fn get_mut<Q: ?Sized>(&mut self, k: &Q) -> Option<&mut V> + where + K: Borrow<Q>, + Q: Eq, + { + for (index, existing) in self.keys.iter().enumerate() { + if existing.borrow() == k { + return Some(&mut self.values[index]); + } + } + None + } + + pub fn keys(&self) -> std::slice::Iter<'_, K> { + self.keys.iter() + } + + pub fn iter(&self) -> Iter<K, V> { + Iter { + keys: self.keys.iter(), + values: self.values.iter(), + } + } + + pub fn iter_mut(&mut self) -> IterMut<K, V> { + IterMut { + keys: self.keys.iter_mut(), + values: self.values.iter_mut(), + } + } +} + +impl<K: PartialEq + Eq, V> Default for FlatMap<K, V> { + fn default() -> Self { + Self { + keys: Default::default(), + values: Default::default(), + } + } +} + +pub enum Entry<'a, K: 'a, V: 'a> { + Vacant(VacantEntry<'a, K, V>), + Occupied(OccupiedEntry<'a, K, V>), +} + +impl<'a, K: 'a, V: 'a> Entry<'a, K, V> { + pub fn or_insert(self, default: V) -> &'a mut V { + match self { + Entry::Occupied(entry) => &mut entry.v.values[entry.index], + Entry::Vacant(entry) => { + entry.v.keys.push(entry.key); + entry.v.values.push(default); + entry.v.values.last_mut().unwrap() + } + } + } + + pub fn or_insert_with<F: FnOnce() -> V>(self, default: F) -> &'a mut V { + match self { + Entry::Occupied(entry) => &mut entry.v.values[entry.index], + Entry::Vacant(entry) => { + entry.v.keys.push(entry.key); + entry.v.values.push(default()); + entry.v.values.last_mut().unwrap() + } + } + } +} + +pub struct VacantEntry<'a, K: 'a, V: 'a> { + v: &'a mut FlatMap<K, V>, + key: K, +} + +pub struct OccupiedEntry<'a, K: 'a, V: 'a> { + v: &'a mut FlatMap<K, V>, + index: usize, +} + +pub struct Iter<'a, K: 'a, V: 'a> { + keys: std::slice::Iter<'a, K>, + values: std::slice::Iter<'a, V>, +} + +impl<'a, K, V> Iterator for Iter<'a, K, V> { + type Item = (&'a K, &'a V); + + fn next(&mut self) -> Option<(&'a K, &'a V)> { + match self.keys.next() { + Some(k) => { + let v = self.values.next().unwrap(); + Some((k, v)) + } + None => None, + } + } + fn size_hint(&self) -> (usize, Option<usize>) { + self.keys.size_hint() + } +} + +impl<'a, K, V> DoubleEndedIterator for Iter<'a, K, V> { + fn next_back(&mut self) -> Option<(&'a K, &'a V)> { + match self.keys.next_back() { + Some(k) => { + let v = self.values.next_back().unwrap(); + Some((k, v)) + } + None => None, + } + } +} + +impl<'a, K, V> ExactSizeIterator for Iter<'a, K, V> {} + +pub struct IterMut<'a, K: 'a, V: 'a> { + keys: std::slice::IterMut<'a, K>, + values: std::slice::IterMut<'a, V>, +} + +impl<'a, K, V> Iterator for IterMut<'a, K, V> { + type Item = (&'a K, &'a mut V); + + fn next(&mut self) -> Option<(&'a K, &'a mut V)> { + match self.keys.next() { + Some(k) => { + let v = self.values.next().unwrap(); + Some((k, v)) + } + None => None, + } + } + fn size_hint(&self) -> (usize, Option<usize>) { + self.keys.size_hint() + } +} + +impl<'a, K, V> DoubleEndedIterator for IterMut<'a, K, V> { + fn next_back(&mut self) -> Option<(&'a K, &'a mut V)> { + match self.keys.next_back() { + Some(k) => { + let v = self.values.next_back().unwrap(); + Some((k, v)) + } + None => None, + } + } +} + +impl<'a, K, V> ExactSizeIterator for IterMut<'a, K, V> {} diff --git a/vendor/clap_builder/src/util/flat_set.rs b/vendor/clap_builder/src/util/flat_set.rs new file mode 100644 index 0000000..3e0b23d --- /dev/null +++ b/vendor/clap_builder/src/util/flat_set.rs @@ -0,0 +1,107 @@ +#![allow(dead_code)] + +use std::borrow::Borrow; + +/// Flat (Vec) backed set +/// +/// This preserves insertion order +#[derive(Clone, Debug, PartialEq, Eq)] +pub(crate) struct FlatSet<T> { + inner: Vec<T>, +} + +impl<T: PartialEq + Eq> FlatSet<T> { + pub(crate) fn new() -> Self { + Default::default() + } + + pub(crate) fn insert(&mut self, value: T) -> bool { + for existing in &self.inner { + if *existing == value { + return false; + } + } + self.inner.push(value); + true + } + + pub fn contains<Q: ?Sized>(&self, value: &Q) -> bool + where + T: Borrow<Q>, + Q: Eq, + { + for existing in &self.inner { + if existing.borrow() == value { + return true; + } + } + false + } + + pub fn retain<F>(&mut self, f: F) + where + F: FnMut(&T) -> bool, + { + self.inner.retain(f); + } + + pub(crate) fn is_empty(&self) -> bool { + self.inner.is_empty() + } + + pub(crate) fn iter(&self) -> std::slice::Iter<'_, T> { + self.inner.iter() + } + + pub fn sort_by_key<K, F>(&mut self, f: F) + where + F: FnMut(&T) -> K, + K: Ord, + { + self.inner.sort_by_key(f); + } +} + +impl<T: PartialEq + Eq> Default for FlatSet<T> { + fn default() -> Self { + Self { + inner: Default::default(), + } + } +} + +impl<T: PartialEq + Eq> IntoIterator for FlatSet<T> { + type Item = T; + type IntoIter = std::vec::IntoIter<T>; + + fn into_iter(self) -> Self::IntoIter { + self.inner.into_iter() + } +} + +impl<'s, T: PartialEq + Eq> IntoIterator for &'s FlatSet<T> { + type Item = &'s T; + type IntoIter = std::slice::Iter<'s, T>; + + fn into_iter(self) -> Self::IntoIter { + self.inner.iter() + } +} + +impl<T: PartialEq + Eq> Extend<T> for FlatSet<T> { + fn extend<I: IntoIterator<Item = T>>(&mut self, iter: I) { + for value in iter { + self.insert(value); + } + } +} + +impl<T: PartialEq + Eq> FromIterator<T> for FlatSet<T> { + fn from_iter<I: IntoIterator<Item = T>>(iter: I) -> Self { + let mut set = Self::new(); + for value in iter { + set.insert(value); + } + set + } +} diff --git a/vendor/clap_builder/src/util/graph.rs b/vendor/clap_builder/src/util/graph.rs new file mode 100644 index 0000000..d646400 --- /dev/null +++ b/vendor/clap_builder/src/util/graph.rs @@ -0,0 +1,49 @@ +#[derive(Debug)] +struct Child<T> { + id: T, + children: Vec<usize>, +} + +impl<T> Child<T> { + fn new(id: T) -> Self { + Child { + id, + children: vec![], + } + } +} + +#[derive(Debug)] +pub(crate) struct ChildGraph<T>(Vec<Child<T>>); + +impl<T> ChildGraph<T> +where + T: Sized + PartialEq + Clone, +{ + pub(crate) fn with_capacity(s: usize) -> Self { + ChildGraph(Vec::with_capacity(s)) + } + + pub(crate) fn insert(&mut self, req: T) -> usize { + self.0.iter().position(|e| e.id == req).unwrap_or_else(|| { + let idx = self.0.len(); + self.0.push(Child::new(req)); + idx + }) + } + + pub(crate) fn insert_child(&mut self, parent: usize, child: T) -> usize { + let c_idx = self.0.len(); + self.0.push(Child::new(child)); + self.0[parent].children.push(c_idx); + c_idx + } + + pub(crate) fn iter(&self) -> impl Iterator<Item = &T> { + self.0.iter().map(|r| &r.id) + } + + pub(crate) fn contains(&self, req: &T) -> bool { + self.0.iter().any(|r| r.id == *req) + } +} diff --git a/vendor/clap_builder/src/util/id.rs b/vendor/clap_builder/src/util/id.rs new file mode 100644 index 0000000..710d2ea --- /dev/null +++ b/vendor/clap_builder/src/util/id.rs @@ -0,0 +1,164 @@ +use crate::builder::Str; + +/// [`Arg`][crate::Arg] or [`ArgGroup`][crate::ArgGroup] identifier +/// +/// This is used for accessing the value in [`ArgMatches`][crate::ArgMatches] or defining +/// relationships between `Arg`s and `ArgGroup`s with functions like +/// [`Arg::conflicts_with`][crate::Arg::conflicts_with]. +#[derive(Default, Clone, Eq, PartialEq, PartialOrd, Ord, Hash)] +pub struct Id(Str); + +impl Id { + pub(crate) const HELP: &'static str = "help"; + pub(crate) const VERSION: &'static str = "version"; + pub(crate) const EXTERNAL: &'static str = ""; + + pub(crate) fn from_static_ref(name: &'static str) -> Self { + Self(Str::from_static_ref(name)) + } + + /// Get the raw string of the `Id` + pub fn as_str(&self) -> &str { + self.0.as_str() + } + + pub(crate) fn as_internal_str(&self) -> &Str { + &self.0 + } +} + +impl From<&'_ Id> for Id { + fn from(id: &'_ Id) -> Self { + id.clone() + } +} + +impl From<Str> for Id { + fn from(name: Str) -> Self { + Self(name) + } +} + +impl From<&'_ Str> for Id { + fn from(name: &'_ Str) -> Self { + Self(name.into()) + } +} + +#[cfg(feature = "string")] +impl From<std::string::String> for Id { + fn from(name: std::string::String) -> Self { + Self(name.into()) + } +} + +#[cfg(feature = "string")] +impl From<&'_ std::string::String> for Id { + fn from(name: &'_ std::string::String) -> Self { + Self(name.into()) + } +} + +impl From<&'static str> for Id { + fn from(name: &'static str) -> Self { + Self(name.into()) + } +} + +impl From<&'_ &'static str> for Id { + fn from(name: &'_ &'static str) -> Self { + Self(name.into()) + } +} + +impl From<Id> for Str { + fn from(name: Id) -> Self { + name.0 + } +} + +impl From<Id> for String { + fn from(name: Id) -> Self { + Str::from(name).into() + } +} + +impl std::fmt::Display for Id { + #[inline] + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + std::fmt::Display::fmt(self.as_str(), f) + } +} + +impl std::fmt::Debug for Id { + #[inline] + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + std::fmt::Debug::fmt(self.as_str(), f) + } +} + +impl AsRef<str> for Id { + #[inline] + fn as_ref(&self) -> &str { + self.as_str() + } +} + +impl std::borrow::Borrow<str> for Id { + #[inline] + fn borrow(&self) -> &str { + self.as_str() + } +} + +impl PartialEq<str> for Id { + #[inline] + fn eq(&self, other: &str) -> bool { + PartialEq::eq(self.as_str(), other) + } +} +impl PartialEq<Id> for str { + #[inline] + fn eq(&self, other: &Id) -> bool { + PartialEq::eq(self, other.as_str()) + } +} + +impl PartialEq<&'_ str> for Id { + #[inline] + fn eq(&self, other: &&str) -> bool { + PartialEq::eq(self.as_str(), *other) + } +} +impl PartialEq<Id> for &'_ str { + #[inline] + fn eq(&self, other: &Id) -> bool { + PartialEq::eq(*self, other.as_str()) + } +} + +impl PartialEq<Str> for Id { + #[inline] + fn eq(&self, other: &Str) -> bool { + PartialEq::eq(self.as_str(), other.as_str()) + } +} +impl PartialEq<Id> for Str { + #[inline] + fn eq(&self, other: &Id) -> bool { + PartialEq::eq(self.as_str(), other.as_str()) + } +} + +impl PartialEq<std::string::String> for Id { + #[inline] + fn eq(&self, other: &std::string::String) -> bool { + PartialEq::eq(self.as_str(), other.as_str()) + } +} +impl PartialEq<Id> for std::string::String { + #[inline] + fn eq(&self, other: &Id) -> bool { + PartialEq::eq(other, self) + } +} diff --git a/vendor/clap_builder/src/util/mod.rs b/vendor/clap_builder/src/util/mod.rs new file mode 100644 index 0000000..a92aef8 --- /dev/null +++ b/vendor/clap_builder/src/util/mod.rs @@ -0,0 +1,47 @@ +#![allow(clippy::single_component_path_imports)] + +mod any_value; +pub(crate) mod flat_map; +pub(crate) mod flat_set; +mod graph; +mod id; +mod str_to_bool; + +pub use self::id::Id; + +pub(crate) use self::any_value::AnyValue; +pub(crate) use self::any_value::AnyValueId; +pub(crate) use self::flat_map::Entry; +pub(crate) use self::flat_map::FlatMap; +pub(crate) use self::flat_set::FlatSet; +pub(crate) use self::graph::ChildGraph; +pub(crate) use self::str_to_bool::str_to_bool; +pub(crate) use self::str_to_bool::FALSE_LITERALS; +pub(crate) use self::str_to_bool::TRUE_LITERALS; + +pub(crate) mod color; + +pub(crate) const SUCCESS_CODE: i32 = 0; +// While sysexists.h defines EX_USAGE as 64, this doesn't seem to be used much in practice but +// instead 2 seems to be frequently used. +// Examples +// - GNU `ls` returns 2 +// - Python's `argparse` returns 2 +pub(crate) const USAGE_CODE: i32 = 2; + +pub(crate) fn safe_exit(code: i32) -> ! { + use std::io::Write; + + let _ = std::io::stdout().lock().flush(); + let _ = std::io::stderr().lock().flush(); + + std::process::exit(code) +} + +#[cfg(not(feature = "unicode"))] +pub(crate) fn eq_ignore_case(left: &str, right: &str) -> bool { + left.eq_ignore_ascii_case(right) +} + +#[cfg(feature = "unicode")] +pub(crate) use unicase::eq as eq_ignore_case; diff --git a/vendor/clap_builder/src/util/str_to_bool.rs b/vendor/clap_builder/src/util/str_to_bool.rs new file mode 100644 index 0000000..1fbdc75 --- /dev/null +++ b/vendor/clap_builder/src/util/str_to_bool.rs @@ -0,0 +1,21 @@ +/// True values are `y`, `yes`, `t`, `true`, `on`, and `1`. +pub(crate) const TRUE_LITERALS: [&str; 6] = ["y", "yes", "t", "true", "on", "1"]; + +/// False values are `n`, `no`, `f`, `false`, `off`, and `0`. +pub(crate) const FALSE_LITERALS: [&str; 6] = ["n", "no", "f", "false", "off", "0"]; + +/// Converts a string literal representation of truth to true or false. +/// +/// `false` values are `n`, `no`, `f`, `false`, `off`, and `0` (case insensitive). +/// +/// Any other value will be considered as `true`. +pub(crate) fn str_to_bool(val: impl AsRef<str>) -> Option<bool> { + let pat: &str = &val.as_ref().to_lowercase(); + if TRUE_LITERALS.contains(&pat) { + Some(true) + } else if FALSE_LITERALS.contains(&pat) { + Some(false) + } else { + None + } +} |