From 20431706a863f92cb37dc512fef6e48d192aaf2c Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Wed, 17 Apr 2024 14:11:38 +0200 Subject: Merging upstream version 1.66.0+dfsg1. Signed-off-by: Daniel Baumann --- vendor/clap-3.2.20/src/parser/matches/any_value.rs | 112 ++ .../clap-3.2.20/src/parser/matches/arg_matches.rs | 1896 ++++++++++++++++++++ .../clap-3.2.20/src/parser/matches/matched_arg.rs | 240 +++ vendor/clap-3.2.20/src/parser/matches/mod.rs | 17 + .../clap-3.2.20/src/parser/matches/value_source.rs | 11 + 5 files changed, 2276 insertions(+) create mode 100644 vendor/clap-3.2.20/src/parser/matches/any_value.rs create mode 100644 vendor/clap-3.2.20/src/parser/matches/arg_matches.rs create mode 100644 vendor/clap-3.2.20/src/parser/matches/matched_arg.rs create mode 100644 vendor/clap-3.2.20/src/parser/matches/mod.rs create mode 100644 vendor/clap-3.2.20/src/parser/matches/value_source.rs (limited to 'vendor/clap-3.2.20/src/parser/matches') diff --git a/vendor/clap-3.2.20/src/parser/matches/any_value.rs b/vendor/clap-3.2.20/src/parser/matches/any_value.rs new file mode 100644 index 000000000..a9277e75f --- /dev/null +++ b/vendor/clap-3.2.20/src/parser/matches/any_value.rs @@ -0,0 +1,112 @@ +#[derive(Clone)] +pub(crate) struct AnyValue { + inner: std::sync::Arc, + // 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(inner: V) -> Self { + let id = AnyValueId::of::(); + let inner = std::sync::Arc::new(inner); + Self { inner, id } + } + + pub(crate) fn downcast_ref( + &self, + ) -> Option<&T> { + self.inner.downcast_ref::() + } + + pub(crate) fn downcast_into(self) -> Result { + let id = self.id; + let value = + std::sync::Arc::downcast::(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() -> Self { + Self { + type_id: std::any::TypeId::of::(), + #[cfg(debug_assertions)] + type_name: std::any::type_name::(), + } + } +} + +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 { + self.type_id.partial_cmp(&other.type_id) + } +} + +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(&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::() + } +} + +#[cfg(test)] +mod test { + #[test] + #[cfg(debug_assertions)] + fn debug_impl() { + use super::*; + + assert_eq!(format!("{:?}", AnyValue::new(5)), "AnyValue { inner: i32 }"); + } +} diff --git a/vendor/clap-3.2.20/src/parser/matches/arg_matches.rs b/vendor/clap-3.2.20/src/parser/matches/arg_matches.rs new file mode 100644 index 000000000..2585c0219 --- /dev/null +++ b/vendor/clap-3.2.20/src/parser/matches/arg_matches.rs @@ -0,0 +1,1896 @@ +// Std +use std::any::Any; +use std::borrow::Cow; +use std::ffi::{OsStr, OsString}; +use std::fmt::{Debug, Display}; +use std::iter::{Cloned, Flatten, Map}; +use std::slice::Iter; +use std::str::FromStr; + +// Third Party +use indexmap::IndexMap; + +// Internal +use crate::parser::AnyValue; +use crate::parser::AnyValueId; +use crate::parser::MatchedArg; +use crate::parser::MatchesError; +use crate::parser::ValueSource; +use crate::util::{Id, Key}; +use crate::Error; +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::{Command, Arg, ValueSource}; +/// let matches = Command::new("MyApp") +/// .arg(Arg::new("out") +/// .long("output") +/// .required(true) +/// .takes_value(true) +/// .default_value("-")) +/// .arg(Arg::new("cfg") +/// .short('c') +/// .takes_value(true)) +/// .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::("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::("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, + #[cfg(debug_assertions)] + pub(crate) valid_subcommands: Vec, + #[cfg(debug_assertions)] + pub(crate) disable_asserts: bool, + pub(crate) args: IndexMap, + pub(crate) subcommand: Option>, +} + +/// # Arguments +impl ArgMatches { + /// Gets the value of a specific option or positional argument. + /// + /// i.e. an argument that [takes an additional value][crate::Arg::takes_value] 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::{Command, Arg, value_parser}; + /// let m = Command::new("myapp") + /// .arg(Arg::new("port") + /// .value_parser(value_parser!(usize)) + /// .takes_value(true) + /// .required(true)) + /// .get_matches_from(vec!["myapp", "2020"]); + /// + /// let port: usize = *m + /// .get_one("port") + /// .expect("`port`is required"); + /// assert_eq!(port, 2020); + /// ``` + /// [option]: crate::Arg::takes_value() + /// [positional]: crate::Arg::index() + /// [`default_value`]: crate::Arg::default_value() + #[track_caller] + pub fn get_one(&self, id: &str) -> Option<&T> { + let internal_id = Id::from(id); + MatchesError::unwrap(&internal_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::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 + /// ); + /// ``` + #[track_caller] + pub fn get_count(&self, id: &str) -> u8 { + *self + .get_one::(id) + .expect("ArgAction::Count is defaulted") + } + + /// 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::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", "--flag"]).unwrap(); + /// assert!(matches.contains_id("flag")); + /// assert_eq!( + /// matches.get_flag("flag"), + /// true + /// ); + /// ``` + #[track_caller] + pub fn get_flag(&self, id: &str) -> bool { + *self + .get_one::(id) + .expect("ArgAction::SetTrue / ArgAction::SetFalse is defaulted") + } + + /// 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::{Command, Arg, value_parser, ArgAction}; + /// let m = Command::new("myprog") + /// .arg(Arg::new("ports") + /// .action(ArgAction::Append) + /// .value_parser(value_parser!(usize)) + /// .short('p') + /// .takes_value(true) + /// .required(true)) + /// .get_matches_from(vec![ + /// "myprog", "-p", "22", "-p", "80", "-p", "2020" + /// ]); + /// let vals: Vec = m.get_many("ports") + /// .expect("`port`is required") + /// .copied() + /// .collect(); + /// assert_eq!(vals, [22, 80, 2020]); + /// ``` + #[track_caller] + pub fn get_many( + &self, + id: &str, + ) -> Option> { + let internal_id = Id::from(id); + MatchesError::unwrap(&internal_id, self.try_get_many(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 + /// + #[cfg_attr(not(unix), doc = " ```ignore")] + #[cfg_attr(unix, doc = " ```")] + /// # 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!( ... "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 + #[track_caller] + pub fn get_raw(&self, id: &str) -> Option> { + let internal_id = Id::from(id); + MatchesError::unwrap(&internal_id, self.try_get_raw(id)) + } + + /// Returns the value of a specific option or positional argument. + /// + /// i.e. an argument that [takes an additional value][crate::Arg::takes_value] 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::{Command, Arg, value_parser}; + /// let mut m = Command::new("myprog") + /// .arg(Arg::new("file") + /// .required(true) + /// .takes_value(true)) + /// .get_matches_from(vec![ + /// "myprog", "file.txt", + /// ]); + /// let vals: String = m.remove_one("file") + /// .expect("`file`is required"); + /// assert_eq!(vals, "file.txt"); + /// ``` + /// [option]: crate::Arg::takes_value() + /// [positional]: crate::Arg::index() + /// [`default_value`]: crate::Arg::default_value() + #[track_caller] + pub fn remove_one(&mut self, id: &str) -> Option { + let internal_id = Id::from(id); + MatchesError::unwrap(&internal_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::{Command, Arg, value_parser, ArgAction}; + /// let mut m = Command::new("myprog") + /// .arg(Arg::new("file") + /// .action(ArgAction::Append) + /// .multiple_values(true) + /// .required(true) + /// .takes_value(true)) + /// .get_matches_from(vec![ + /// "myprog", "file1.txt", "file2.txt", "file3.txt", "file4.txt", + /// ]); + /// let vals: Vec = m.remove_many("file") + /// .expect("`file`is required") + /// .collect(); + /// assert_eq!(vals, ["file1.txt", "file2.txt", "file3.txt", "file4.txt"]); + /// ``` + #[track_caller] + pub fn remove_many( + &mut self, + id: &str, + ) -> Option> { + let internal_id = Id::from(id); + MatchesError::unwrap(&internal_id, self.try_remove_many(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 is not a valid argument or group name. To handle this case programmatically, see + /// [`ArgMatches::try_contains_id`]. + /// + /// # Examples + /// + /// ```rust + /// # use clap::{Command, Arg}; + /// let m = Command::new("myprog") + /// .arg(Arg::new("debug") + /// .short('d')) + /// .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 { + let internal_id = Id::from(id); + MatchesError::unwrap(&internal_id, self.try_contains_id(id)) + } + + /// Check if any args were present on the command line + /// + /// # Examples + /// + /// ```rust + /// # use clap::{Command, Arg}; + /// let mut cmd = Command::new("myapp") + /// .arg(Arg::new("output") + /// .takes_value(true)); + /// + /// 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() + } + + /// Deprecated, replaced with [`ArgMatches::get_one()`] + #[cfg_attr( + feature = "deprecated", + deprecated(since = "3.2.0", note = "Replaced with `ArgMatches::get_one()`") + )] + #[cfg_attr(debug_assertions, track_caller)] + pub fn value_of(&self, id: T) -> Option<&str> { + let id = Id::from(id); + let arg = self.get_arg(&id)?; + let v = unwrap_string_arg(&id, arg.first()?); + Some(v) + } + + /// Deprecated, replaced with [`ArgMatches::get_one()`] + #[cfg_attr( + feature = "deprecated", + deprecated(since = "3.2.0", note = "Replaced with `ArgMatches::get_one()`") + )] + #[cfg_attr(debug_assertions, track_caller)] + pub fn value_of_lossy(&self, id: T) -> Option> { + let id = Id::from(id); + let arg = self.get_arg(&id)?; + let v = unwrap_os_string_arg(&id, arg.first()?); + Some(v.to_string_lossy()) + } + + /// Deprecated, replaced with [`ArgMatches::get_one()`] + #[cfg_attr( + feature = "deprecated", + deprecated(since = "3.2.0", note = "Replaced with `ArgMatches::get_one()`") + )] + #[cfg_attr(debug_assertions, track_caller)] + pub fn value_of_os(&self, id: T) -> Option<&OsStr> { + let id = Id::from(id); + let arg = self.get_arg(&id)?; + let v = unwrap_os_string_arg(&id, arg.first()?); + Some(v) + } + + /// Deprecated, replaced with [`ArgMatches::get_many()`] + #[cfg_attr( + feature = "deprecated", + deprecated(since = "3.2.0", note = "Replaced with `ArgMatches::get_many()`") + )] + #[cfg_attr(debug_assertions, track_caller)] + pub fn values_of(&self, id: T) -> Option { + #![allow(deprecated)] + let id = Id::from(id); + let arg = self.get_arg(&id)?; + let v = Values { + iter: arg.vals_flatten().map(unwrap_string), + len: arg.num_vals(), + }; + Some(v) + } + + /// Get an [`Iterator`] over groups of values of a specific option. + /// + /// specifically grouped by the occurrences of the options. + /// + /// Each group is a `Vec<&str>` 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 value is invalid UTF-8. + /// + /// If `id` is not a valid argument or group id. + /// + /// # Examples + /// ```rust + /// # use clap::{Command,Arg, ArgAction}; + /// let m = Command::new("myprog") + /// .arg(Arg::new("exec") + /// .short('x') + /// .min_values(1) + /// .action(ArgAction::Append) + /// .value_terminator(";")) + /// .get_matches_from(vec![ + /// "myprog", "-x", "echo", "hi", ";", "-x", "echo", "bye"]); + /// let vals: Vec> = m.grouped_values_of("exec").unwrap().collect(); + /// assert_eq!(vals, [["echo", "hi"], ["echo", "bye"]]); + /// ``` + /// [`Iterator`]: std::iter::Iterator + #[cfg(feature = "unstable-grouped")] + #[cfg_attr(debug_assertions, track_caller)] + pub fn grouped_values_of(&self, id: T) -> Option { + let id = Id::from(id); + let arg = self.get_arg(&id)?; + let v = GroupedValues { + iter: arg.vals().map(|g| g.iter().map(unwrap_string).collect()), + len: arg.vals().len(), + }; + Some(v) + } + + /// Deprecated, replaced with [`ArgMatches::get_many()`] + #[cfg_attr( + feature = "deprecated", + deprecated(since = "3.2.0", note = "Replaced with `ArgMatches::get_many()`") + )] + #[cfg_attr(debug_assertions, track_caller)] + pub fn values_of_lossy(&self, id: T) -> Option> { + let id = Id::from(id); + let arg = self.get_arg(&id)?; + let v = arg + .vals_flatten() + .map(|v| unwrap_os_string_arg(&id, v).to_string_lossy().into_owned()) + .collect(); + Some(v) + } + + /// Deprecated, replaced with [`ArgMatches::get_many()`] + #[cfg_attr( + feature = "deprecated", + deprecated(since = "3.2.0", note = "Replaced with `ArgMatches::get_many()`") + )] + #[cfg_attr(debug_assertions, track_caller)] + pub fn values_of_os(&self, id: T) -> Option { + #![allow(deprecated)] + let id = Id::from(id); + let arg = self.get_arg(&id)?; + let v = OsValues { + iter: arg.vals_flatten().map(unwrap_os_string), + len: arg.num_vals(), + }; + Some(v) + } + + /// Deprecated, replaced with [`ArgMatches::get_one()`] + #[cfg_attr( + feature = "deprecated", + deprecated(since = "3.2.0", note = "Replaced with `ArgMatches::get_one()`") + )] + #[cfg_attr(debug_assertions, track_caller)] + pub fn value_of_t(&self, name: &str) -> Result + where + R: FromStr, + ::Err: Display, + { + #![allow(deprecated)] + let v = self + .value_of(name) + .ok_or_else(|| Error::argument_not_found_auto(name.to_string()))?; + v.parse::().map_err(|e| { + let message = format!( + "The argument '{}' isn't a valid value for '{}': {}", + v, name, e + ); + + Error::value_validation(name.to_string(), v.to_string(), message.into()) + }) + } + + /// Deprecated, replaced with [`ArgMatches::get_one()`] + #[cfg_attr( + feature = "deprecated", + deprecated(since = "3.2.0", note = "Replaced with `ArgMatches::get_one()`") + )] + #[cfg_attr(debug_assertions, track_caller)] + pub fn value_of_t_or_exit(&self, name: &str) -> R + where + R: FromStr, + ::Err: Display, + { + #![allow(deprecated)] + self.value_of_t(name).unwrap_or_else(|e| e.exit()) + } + + /// Deprecated, replaced with [`ArgMatches::get_many()`] + #[cfg_attr( + feature = "deprecated", + deprecated(since = "3.2.0", note = "Replaced with `ArgMatches::get_many()`") + )] + #[cfg_attr(debug_assertions, track_caller)] + pub fn values_of_t(&self, name: &str) -> Result, Error> + where + R: FromStr, + ::Err: Display, + { + #![allow(deprecated)] + let v = self + .values_of(name) + .ok_or_else(|| Error::argument_not_found_auto(name.to_string()))?; + v.map(|v| { + v.parse::().map_err(|e| { + let message = format!("The argument '{}' isn't a valid value: {}", v, e); + + Error::value_validation(name.to_string(), v.to_string(), message.into()) + }) + }) + .collect() + } + + /// Deprecated, replaced with [`ArgMatches::get_many()`] + #[cfg_attr( + feature = "deprecated", + deprecated(since = "3.2.0", note = "Replaced with `ArgMatches::get_many()`") + )] + #[cfg_attr(debug_assertions, track_caller)] + pub fn values_of_t_or_exit(&self, name: &str) -> Vec + where + R: FromStr, + ::Err: Display, + { + #![allow(deprecated)] + self.values_of_t(name).unwrap_or_else(|e| e.exit()) + } + + /// Deprecated, replaced with [`ArgAction::SetTrue`][crate::ArgAction] or + /// [`ArgMatches::contains_id`]. + #[cfg_attr( + feature = "deprecated", + deprecated( + since = "3.2.0", + note = "Replaced with either `ArgAction::SetTrue` or `ArgMatches::contains_id(...)`" + ) + )] + #[cfg_attr(debug_assertions, track_caller)] + pub fn is_present(&self, id: T) -> bool { + let id = Id::from(id); + + #[cfg(debug_assertions)] + self.get_arg(&id); + + self.args.contains_key(&id) + } + + /// Report where argument value came from + /// + /// # Panics + /// + /// If `id` is is not a valid argument or group id. + /// + /// # Examples + /// + /// ```rust + /// # use clap::{Command, Arg, ValueSource}; + /// let m = Command::new("myprog") + /// .arg(Arg::new("debug") + /// .short('d')) + /// .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: T) -> Option { + let id = Id::from(id); + + let value = self.get_arg(&id); + + value.and_then(MatchedArg::source) + } + + /// Deprecated, replaced with [`ArgAction::Count`][crate::ArgAction], + /// [`ArgMatches::get_many`]`.len()`, or [`ArgMatches::value_source`]. + #[cfg_attr( + feature = "deprecated", + deprecated( + since = "3.2.0", + note = "Replaced with either `ArgAction::Count`, `ArgMatches::get_many(...).len()`, or `ArgMatches::value_source`" + ) + )] + #[cfg_attr(debug_assertions, track_caller)] + pub fn occurrences_of(&self, id: T) -> u64 { + #![allow(deprecated)] + self.get_arg(&Id::from(id)) + .map_or(0, |a| a.get_occurrences()) + } + + /// 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 is not a valid argument or group id. + /// + /// # 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::{Command, Arg}; + /// let m = Command::new("myapp") + /// .arg(Arg::new("flag") + /// .short('f')) + /// .arg(Arg::new("option") + /// .short('o') + /// .takes_value(true)) + /// .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::{Command, Arg}; + /// let m = Command::new("myapp") + /// .arg(Arg::new("flag") + /// .short('f')) + /// .arg(Arg::new("option") + /// .short('o') + /// .takes_value(true)) + /// .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::{Command, Arg}; + /// let m = Command::new("myapp") + /// .arg(Arg::new("flag") + /// .short('f')) + /// .arg(Arg::new("flag2") + /// .short('F')) + /// .arg(Arg::new("flag3") + /// .short('z')) + /// .arg(Arg::new("option") + /// .short('o') + /// .takes_value(true)) + /// .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::{Command, Arg}; + /// let m = Command::new("myapp") + /// .arg(Arg::new("flag") + /// .short('f')) + /// .arg(Arg::new("flag2") + /// .short('F')) + /// .arg(Arg::new("flag3") + /// .short('z')) + /// .arg(Arg::new("option") + /// .short('o') + /// .takes_value(true)) + /// .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::{Command, Arg}; + /// let m = Command::new("myapp") + /// .arg(Arg::new("option") + /// .short('o') + /// .use_value_delimiter(true) + /// .multiple_values(true)) + /// .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::>(), &[2, 3, 4]); + /// ``` + /// [delimiter]: crate::Arg::value_delimiter() + #[cfg_attr(debug_assertions, track_caller)] + pub fn index_of(&self, id: T) -> Option { + let arg = self.get_arg(&Id::from(id))?; + let i = 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 is not a valid argument or group id. + /// + /// # Examples + /// + /// ```rust + /// # use clap::{Command, Arg}; + /// let m = Command::new("myapp") + /// .arg(Arg::new("option") + /// .short('o') + /// .use_value_delimiter(true) + /// .multiple_values(true)) + /// .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::>(), &[2, 3, 4]); + /// ``` + /// + /// Another quick example is when flags and options are used together + /// + /// ```rust + /// # use clap::{Command, Arg, ArgAction}; + /// let m = Command::new("myapp") + /// .arg(Arg::new("option") + /// .short('o') + /// .takes_value(true) + /// .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::>(), &[2, 5]); + /// assert_eq!(m.indices_of("flag").unwrap().collect::>(), &[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::{Command, Arg}; + /// let m = Command::new("myapp") + /// .arg(Arg::new("option") + /// .short('o') + /// .takes_value(true) + /// .multiple_values(true)) + /// .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::>(), &[2]); + /// ``` + /// [`ArgMatches::index_of`]: ArgMatches::index_of() + /// [delimiter]: Arg::value_delimiter() + #[cfg_attr(debug_assertions, track_caller)] + pub fn indices_of(&self, id: T) -> Option> { + let arg = self.get_arg(&Id::from(id))?; + let i = Indices { + iter: arg.indices(), + len: arg.num_vals(), + }; + Some(i) + } + + #[inline] + #[doc(hidden)] + #[cfg_attr( + feature = "deprecated", + deprecated(since = "3.2.0", note = "Replaced with `ArgMatches::try_get_one()`") + )] + pub fn is_valid_arg(&self, _id: impl Key) -> bool { + #[cfg(debug_assertions)] + { + let id = Id::from(_id); + self.disable_asserts || id == Id::empty_hash() || self.valid_args.contains(&id) + } + #[cfg(not(debug_assertions))] + { + true + } + } +} + +/// # 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::{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::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<&str> = sub_m.get_many::("") + /// .unwrap().map(|s| s.as_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::{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::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 = 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 is not a valid subcommand. + /// + /// # Examples + /// + /// ```rust + /// # 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") + /// .takes_value(true))) + /// .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_one::("debug").expect("defaulted by clap")); + /// + /// // 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::("opt").map(|s| s.as_str()), Some("val")); + /// } + /// ``` + /// + /// [subcommand]: crate::Command::subcommand + /// [`Command`]: crate::Command + pub fn subcommand_matches(&self, id: T) -> Option<&ArgMatches> { + self.get_subcommand(&id.into()).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::{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, _id: impl Key) -> bool { + #[cfg(debug_assertions)] + { + let id = Id::from(_id); + self.disable_asserts || id == Id::empty_hash() || self.valid_subcommands.contains(&id) + } + #[cfg(not(debug_assertions))] + { + true + } + } +} + +/// # Advanced +impl ArgMatches { + /// Non-panicking version of [`ArgMatches::get_one`] + pub fn try_get_one( + &self, + id: &str, + ) -> Result, MatchesError> { + let id = Id::from(id); + let arg = self.try_get_arg_t::(&id)?; + let value = match arg.and_then(|a| a.first()) { + Some(value) => value, + None => { + return Ok(None); + } + }; + Ok(value + .downcast_ref::() + .map(Some) + .expect(INTERNAL_ERROR_MSG)) // enforced by `try_get_arg_t` + } + + /// Non-panicking version of [`ArgMatches::get_many`] + pub fn try_get_many( + &self, + id: &str, + ) -> Result>, MatchesError> { + let id = Id::from(id); + let arg = match self.try_get_arg_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(|v| v.downcast_ref::().expect(INTERNAL_ERROR_MSG)), + len, + }; + Ok(Some(values)) + } + + /// Non-panicking version of [`ArgMatches::get_raw`] + pub fn try_get_raw(&self, id: &str) -> Result>, MatchesError> { + let id = Id::from(id); + let arg = match 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::remove_one`] + pub fn try_remove_one( + &mut self, + id: &str, + ) -> Result, MatchesError> { + let id = Id::from(id); + match self.try_remove_arg_t::(&id)? { + Some(values) => Ok(values + .into_vals_flatten() + // enforced by `try_get_arg_t` + .map(|v| v.downcast_into::().expect(INTERNAL_ERROR_MSG)) + .next()), + None => Ok(None), + } + } + + /// Non-panicking version of [`ArgMatches::remove_many`] + pub fn try_remove_many( + &mut self, + id: &str, + ) -> Result>, MatchesError> { + let id = Id::from(id); + let arg = match self.try_remove_arg_t::(&id)? { + Some(arg) => arg, + None => return Ok(None), + }; + let len = arg.num_vals(); + let values = arg.into_vals_flatten(); + let values = Values2 { + // enforced by `try_get_arg_t` + iter: values.map(|v| v.downcast_into::().expect(INTERNAL_ERROR_MSG)), + len, + }; + Ok(Some(values)) + } + + /// Non-panicking version of [`ArgMatches::contains_id`] + pub fn try_contains_id(&self, id: &str) -> Result { + let id = Id::from(id); + + self.verify_arg(&id)?; + + let presence = self.args.contains_key(&id); + Ok(presence) + } +} + +// Private methods +impl ArgMatches { + #[inline] + fn try_get_arg(&self, arg: &Id) -> Result, MatchesError> { + self.verify_arg(arg)?; + Ok(self.args.get(arg)) + } + + #[inline] + fn try_get_arg_t( + &self, + arg: &Id, + ) -> Result, MatchesError> { + let arg = match self.try_get_arg(arg)? { + Some(arg) => arg, + None => { + return Ok(None); + } + }; + self.verify_arg_t::(arg)?; + Ok(Some(arg)) + } + + #[inline] + fn try_remove_arg_t( + &mut self, + arg: &Id, + ) -> Result, MatchesError> { + self.verify_arg(arg)?; + let matched = match self.args.remove(arg) { + Some(matched) => matched, + None => { + return Ok(None); + } + }; + + let expected = AnyValueId::of::(); + let actual = matched.infer_type_id(expected); + if actual == expected { + Ok(Some(matched)) + } else { + self.args.insert(arg.clone(), matched); + Err(MatchesError::Downcast { actual, expected }) + } + } + + fn verify_arg_t( + &self, + arg: &MatchedArg, + ) -> Result<(), MatchesError> { + let expected = AnyValueId::of::(); + let actual = arg.infer_type_id(expected); + if expected == actual { + Ok(()) + } else { + Err(MatchesError::Downcast { actual, expected }) + } + } + + #[inline] + fn verify_arg(&self, _arg: &Id) -> Result<(), MatchesError> { + #[cfg(debug_assertions)] + { + if self.disable_asserts || *_arg == Id::empty_hash() || self.valid_args.contains(_arg) { + } else if self.valid_subcommands.contains(_arg) { + debug!( + "Subcommand `{:?}` used where an argument or group name was expected.", + _arg + ); + return Err(MatchesError::UnknownArgument {}); + } 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(&self, arg: &Id) -> Option<&MatchedArg> { + #[cfg(debug_assertions)] + { + if self.disable_asserts || *arg == Id::empty_hash() || self.valid_args.contains(arg) { + } else if self.valid_subcommands.contains(arg) { + panic!( + "Subcommand `{:?}` used where an argument or group name was expected.", + arg + ); + } else { + panic!( + "`{:?}` 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 + ); + } + } + + self.args.get(arg) + } + + #[inline] + #[cfg_attr(debug_assertions, track_caller)] + fn get_subcommand(&self, id: &Id) -> Option<&SubCommand> { + #[cfg(debug_assertions)] + { + if self.disable_asserts + || *id == Id::empty_hash() + || self.valid_subcommands.contains(id) + { + } else if self.valid_args.contains(id) { + panic!( + "Argument or group `{:?}` used where a subcommand name was expected.", + id + ); + } else { + panic!("`{:?}` is not a name of a subcommand.", id); + } + } + + if let Some(ref sc) = self.subcommand { + if sc.id == *id { + return Some(sc); + } + } + + None + } +} + +#[derive(Debug, Clone, PartialEq, Eq)] +pub(crate) struct SubCommand { + pub(crate) id: Id, + pub(crate) name: String, + pub(crate) matches: ArgMatches, +} + +/// Iterate over multiple values for an argument via [`ArgMatches::remove_many`]. +/// +/// # Examples +/// +/// ```rust +/// # use clap::{Command, Arg, ArgAction}; +/// let mut m = Command::new("myapp") +/// .arg(Arg::new("output") +/// .short('o') +/// .action(ArgAction::Append) +/// .takes_value(true)) +/// .get_matches_from(vec!["myapp", "-o", "val1", "-o", "val2"]); +/// +/// let mut values = m.remove_many::("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 Values2 { + #[allow(clippy::type_complexity)] + iter: Map>>, fn(AnyValue) -> T>, + len: usize, +} + +impl Iterator for Values2 { + type Item = T; + + fn next(&mut self) -> Option { + self.iter.next() + } + fn size_hint(&self) -> (usize, Option) { + (self.len, Some(self.len)) + } +} + +impl DoubleEndedIterator for Values2 { + fn next_back(&mut self) -> Option { + self.iter.next_back() + } +} + +impl ExactSizeIterator for Values2 {} + +/// Creates an empty iterator. +impl Default for Values2 { + fn default() -> Self { + let empty: Vec> = Default::default(); + Values2 { + iter: empty.into_iter().flatten().map(|_| unreachable!()), + len: 0, + } + } +} + +/// Iterate over multiple values for an argument via [`ArgMatches::get_many`]. +/// +/// # Examples +/// +/// ```rust +/// # use clap::{Command, Arg, ArgAction}; +/// let m = Command::new("myapp") +/// .arg(Arg::new("output") +/// .short('o') +/// .action(ArgAction::Append) +/// .takes_value(true)) +/// .get_matches_from(vec!["myapp", "-o", "val1", "-o", "val2"]); +/// +/// let mut values = m.get_many::("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>>, fn(&AnyValue) -> &T>, + len: usize, +} + +impl<'a, T: 'a> Iterator for ValuesRef<'a, T> { + type Item = &'a T; + + fn next(&mut self) -> Option { + self.iter.next() + } + fn size_hint(&self) -> (usize, Option) { + (self.len, Some(self.len)) + } +} + +impl<'a, T: 'a> DoubleEndedIterator for ValuesRef<'a, T> { + fn next_back(&mut self) -> Option { + self.iter.next_back() + } +} + +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; 0] = []; + ValuesRef { + iter: EMPTY[..].iter().flatten().map(|_| unreachable!()), + len: 0, + } + } +} + +/// Iterate over raw argument values via [`ArgMatches::get_raw`]. +/// +/// # Examples +/// +#[cfg_attr(not(unix), doc = " ```ignore")] +#[cfg_attr(unix, doc = " ```")] +/// # use clap::{Command, arg, value_parser}; +/// use std::ffi::OsString; +/// use std::os::unix::ffi::{OsStrExt,OsStringExt}; +/// +/// let m = Command::new("utf8") +/// .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>>, fn(&OsString) -> &OsStr>, + len: usize, +} + +impl<'a> Iterator for RawValues<'a> { + type Item = &'a OsStr; + + fn next(&mut self) -> Option<&'a OsStr> { + self.iter.next() + } + fn size_hint(&self) -> (usize, Option) { + (self.len, Some(self.len)) + } +} + +impl<'a> DoubleEndedIterator for RawValues<'a> { + fn next_back(&mut self) -> Option<&'a OsStr> { + self.iter.next_back() + } +} + +impl<'a> ExactSizeIterator for RawValues<'a> {} + +/// Creates an empty iterator. +impl Default for RawValues<'_> { + fn default() -> Self { + static EMPTY: [Vec; 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 + +/// Deprecated, replaced with [`ArgMatches::get_many()`] +#[cfg_attr( + feature = "deprecated", + deprecated(since = "3.2.0", note = "Replaced with `ArgMatches::get_many()`") +)] +#[derive(Clone, Debug)] +pub struct Values<'a> { + #[allow(clippy::type_complexity)] + iter: Map>>, for<'r> fn(&'r AnyValue) -> &'r str>, + len: usize, +} + +#[allow(deprecated)] +impl<'a> Iterator for Values<'a> { + type Item = &'a str; + + fn next(&mut self) -> Option<&'a str> { + self.iter.next() + } + fn size_hint(&self) -> (usize, Option) { + (self.len, Some(self.len)) + } +} + +#[allow(deprecated)] +impl<'a> DoubleEndedIterator for Values<'a> { + fn next_back(&mut self) -> Option<&'a str> { + self.iter.next_back() + } +} + +#[allow(deprecated)] +impl<'a> ExactSizeIterator for Values<'a> {} + +/// Creates an empty iterator. +#[allow(deprecated)] +impl<'a> Default for Values<'a> { + fn default() -> Self { + static EMPTY: [Vec; 0] = []; + Values { + iter: EMPTY[..].iter().flatten().map(|_| unreachable!()), + len: 0, + } + } +} + +#[derive(Clone)] +#[allow(missing_debug_implementations)] +pub struct GroupedValues<'a> { + #[allow(clippy::type_complexity)] + iter: Map>, fn(&Vec) -> Vec<&str>>, + len: usize, +} + +impl<'a> Iterator for GroupedValues<'a> { + type Item = Vec<&'a str>; + + fn next(&mut self) -> Option { + self.iter.next() + } + fn size_hint(&self) -> (usize, Option) { + (self.len, Some(self.len)) + } +} + +impl<'a> DoubleEndedIterator for GroupedValues<'a> { + fn next_back(&mut self) -> Option { + self.iter.next_back() + } +} + +impl<'a> ExactSizeIterator for GroupedValues<'a> {} + +/// Creates an empty iterator. Used for `unwrap_or_default()`. +impl<'a> Default for GroupedValues<'a> { + fn default() -> Self { + #![allow(deprecated)] + static EMPTY: [Vec; 0] = []; + GroupedValues { + iter: EMPTY[..].iter().map(|_| unreachable!()), + len: 0, + } + } +} + +/// Deprecated, replaced with [`ArgMatches::get_many()`] +#[cfg_attr( + feature = "deprecated", + deprecated(since = "3.2.0", note = "Replaced with `ArgMatches::get_many()`") +)] +#[derive(Clone, Debug)] +pub struct OsValues<'a> { + #[allow(clippy::type_complexity)] + iter: Map>>, fn(&AnyValue) -> &OsStr>, + len: usize, +} + +#[allow(deprecated)] +impl<'a> Iterator for OsValues<'a> { + type Item = &'a OsStr; + + fn next(&mut self) -> Option<&'a OsStr> { + self.iter.next() + } + fn size_hint(&self) -> (usize, Option) { + (self.len, Some(self.len)) + } +} + +#[allow(deprecated)] +impl<'a> DoubleEndedIterator for OsValues<'a> { + fn next_back(&mut self) -> Option<&'a OsStr> { + self.iter.next_back() + } +} + +#[allow(deprecated)] +impl<'a> ExactSizeIterator for OsValues<'a> {} + +/// Creates an empty iterator. +#[allow(deprecated)] +impl Default for OsValues<'_> { + fn default() -> Self { + static EMPTY: [Vec; 0] = []; + OsValues { + iter: EMPTY[..].iter().flatten().map(|_| unreachable!()), + len: 0, + } + } +} + +/// Iterate over indices for where an argument appeared when parsing, via [`ArgMatches::indices_of`] +/// +/// # Examples +/// +/// ```rust +/// # use clap::{Command, Arg}; +/// let m = Command::new("myapp") +/// .arg(Arg::new("output") +/// .short('o') +/// .multiple_values(true) +/// .takes_value(true)) +/// .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>, + len: usize, +} + +impl<'a> Iterator for Indices<'a> { + type Item = usize; + + fn next(&mut self) -> Option { + self.iter.next() + } + fn size_hint(&self) -> (usize, Option) { + (self.len, Some(self.len)) + } +} + +impl<'a> DoubleEndedIterator for Indices<'a> { + fn next_back(&mut self) -> Option { + self.iter.next_back() + } +} + +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, + } + } +} + +#[cfg_attr(debug_assertions, track_caller)] +#[inline] +fn unwrap_string(value: &AnyValue) -> &str { + match value.downcast_ref::() { + Some(value) => value, + None => { + panic!("Must use `_os` lookups with `Arg::allow_invalid_utf8`",) + } + } +} + +#[cfg_attr(debug_assertions, track_caller)] +#[inline] +fn unwrap_string_arg<'v>(id: &Id, value: &'v AnyValue) -> &'v str { + match value.downcast_ref::() { + Some(value) => value, + None => { + panic!( + "Must use `_os` lookups with `Arg::allow_invalid_utf8` at `{:?}`", + id + ) + } + } +} + +#[cfg_attr(debug_assertions, track_caller)] +#[inline] +fn unwrap_os_string(value: &AnyValue) -> &OsStr { + match value.downcast_ref::() { + Some(value) => value, + None => { + panic!("Must use `Arg::allow_invalid_utf8` with `_os` lookups",) + } + } +} + +#[cfg_attr(debug_assertions, track_caller)] +#[inline] +fn unwrap_os_string_arg<'v>(id: &Id, value: &'v AnyValue) -> &'v OsStr { + match value.downcast_ref::() { + Some(value) => value, + None => { + panic!( + "Must use `Arg::allow_invalid_utf8` with `_os` lookups at `{:?}`", + id + ) + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn check_auto_traits() { + static_assertions::assert_impl_all!(ArgMatches: Send, Sync, Unpin); + } + + #[test] + fn test_default_values() { + #![allow(deprecated)] + let mut values: Values = Values::default(); + assert_eq!(values.next(), None); + } + + #[test] + fn test_default_osvalues() { + #![allow(deprecated)] + let mut values: OsValues = OsValues::default(); + assert_eq!(values.next(), None); + } + + #[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") + .takes_value(true) + .multiple_values(true) + .required(true), + ) + .try_get_matches_from(["test", "one"]) + .unwrap() + .get_many::("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") + .takes_value(true) + .multiple_values(true) + .value_parser(crate::builder::ValueParser::os_string()) + .required(true), + ) + .try_get_matches_from(["test", "one"]) + .unwrap() + .get_many::("POTATO") + .expect("present") + .count(); + assert_eq!(l, 1); + } + + #[test] + fn indices_exact_size() { + let l = crate::Command::new("test") + .arg( + crate::Arg::new("POTATO") + .takes_value(true) + .multiple_values(true) + .required(true), + ) + .try_get_matches_from(["test", "one"]) + .unwrap() + .indices_of("POTATO") + .expect("present") + .len(); + assert_eq!(l, 1); + } +} diff --git a/vendor/clap-3.2.20/src/parser/matches/matched_arg.rs b/vendor/clap-3.2.20/src/parser/matches/matched_arg.rs new file mode 100644 index 000000000..fde6d37f3 --- /dev/null +++ b/vendor/clap-3.2.20/src/parser/matches/matched_arg.rs @@ -0,0 +1,240 @@ +// Std +use std::{ + ffi::{OsStr, OsString}, + iter::{Cloned, Flatten}, + slice::Iter, +}; + +use crate::builder::ArgPredicate; +use crate::parser::AnyValue; +use crate::parser::AnyValueId; +use crate::parser::ValueSource; +use crate::util::eq_ignore_case; +use crate::INTERNAL_ERROR_MSG; + +#[derive(Debug, Clone)] +pub(crate) struct MatchedArg { + occurs: u64, + source: Option, + indices: Vec, + type_id: Option, + vals: Vec>, + raw_vals: Vec>, + ignore_case: bool, +} + +impl MatchedArg { + pub(crate) fn new_arg(arg: &crate::Arg) -> Self { + let ignore_case = arg.is_ignore_case_set(); + Self { + occurs: 0, + 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 { + occurs: 0, + 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 { + occurs: 0, + 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, + } + } + + #[cfg_attr(feature = "deprecated", deprecated(since = "3.2.0"))] + pub(crate) fn inc_occurrences(&mut self) { + self.occurs += 1; + } + + #[cfg_attr(feature = "deprecated", deprecated(since = "3.2.0"))] + pub(crate) fn set_occurrences(&mut self, occurs: u64) { + self.occurs = occurs + } + + #[cfg_attr(feature = "deprecated", deprecated(since = "3.2.0"))] + pub(crate) fn get_occurrences(&self) -> u64 { + self.occurs + } + + pub(crate) fn indices(&self) -> Cloned> { + self.indices.iter().cloned() + } + + pub(crate) fn get_index(&self, index: usize) -> Option { + self.indices.get(index).cloned() + } + + pub(crate) fn push_index(&mut self, index: usize) { + self.indices.push(index) + } + + #[cfg(feature = "unstable-grouped")] + pub(crate) fn vals(&self) -> Iter> { + self.vals.iter() + } + + pub(crate) fn vals_flatten(&self) -> Flatten>> { + self.vals.iter().flatten() + } + + pub(crate) fn into_vals_flatten(self) -> Flatten>> { + self.vals.into_iter().flatten() + } + + pub(crate) fn raw_vals_flatten(&self) -> Flatten>> { + 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 == Some(ValueSource::DefaultValue) { + 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 { + 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 { + 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 { + occurs: self_occurs, + 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 { + occurs: other_occurs, + source: other_source, + indices: other_indices, + type_id: other_type_id, + vals: _, + raw_vals: other_raw_vals, + ignore_case: other_ignore_case, + } = other; + self_occurs == other_occurs + && 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-3.2.20/src/parser/matches/mod.rs b/vendor/clap-3.2.20/src/parser/matches/mod.rs new file mode 100644 index 000000000..7b88eeca7 --- /dev/null +++ b/vendor/clap-3.2.20/src/parser/matches/mod.rs @@ -0,0 +1,17 @@ +mod any_value; +mod arg_matches; +mod matched_arg; +mod value_source; + +pub use any_value::AnyValueId; +pub use arg_matches::RawValues; +pub use arg_matches::ValuesRef; +pub use arg_matches::{ArgMatches, Indices}; +pub use value_source::ValueSource; + +pub(crate) use any_value::AnyValue; +pub(crate) use arg_matches::SubCommand; +pub(crate) use matched_arg::MatchedArg; + +#[allow(deprecated)] +pub use arg_matches::{OsValues, Values}; diff --git a/vendor/clap-3.2.20/src/parser/matches/value_source.rs b/vendor/clap-3.2.20/src/parser/matches/value_source.rs new file mode 100644 index 000000000..fb762d2af --- /dev/null +++ b/vendor/clap-3.2.20/src/parser/matches/value_source.rs @@ -0,0 +1,11 @@ +/// 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, +} -- cgit v1.2.3