From a990de90fe41456a23e58bd087d2f107d321f3a1 Mon Sep 17 00:00:00 2001 From: Valentin Popov Date: Fri, 19 Jul 2024 16:37:58 +0400 Subject: Deleted vendor folder --- .../clap_builder/src/parser/matches/arg_matches.rs | 2030 -------------------- 1 file changed, 2030 deletions(-) delete mode 100644 vendor/clap_builder/src/parser/matches/arg_matches.rs (limited to 'vendor/clap_builder/src/parser/matches/arg_matches.rs') diff --git a/vendor/clap_builder/src/parser/matches/arg_matches.rs b/vendor/clap_builder/src/parser/matches/arg_matches.rs deleted file mode 100644 index e80c39b..0000000 --- a/vendor/clap_builder/src/parser/matches/arg_matches.rs +++ /dev/null @@ -1,2030 +0,0 @@ -// 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::("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, - pub(crate) args: FlatMap, - 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::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(&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::(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::(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 = 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( - &self, - id: &str, - ) -> Option> { - 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> = 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( - &self, - id: &str, - ) -> Option> { - 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!( ... "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> { - 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::>); - /// 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> { - 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(&mut self, id: &str) -> Option { - 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 = 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( - &mut self, - id: &str, - ) -> Option> { - 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> = 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( - &mut self, - id: &str, - ) -> Option> { - 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 ) - /// .value_parser(["auto", "always", "never"])) - /// .arg(arg!(--config ) - /// .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::>(), - /// ["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 { - 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::>(), &[2, 3, 4]); - /// ``` - /// [delimiter]: crate::Arg::value_delimiter() - #[cfg_attr(debug_assertions, track_caller)] - pub fn index_of(&self, id: &str) -> Option { - 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::>(), &[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::>(), &[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_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::>(), &[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> { - 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::("") - /// .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 = 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::("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( - &self, - id: &str, - ) -> Result, MatchesError> { - let arg = ok!(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 arg = match ok!(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(unwrap_downcast_ref), - len, - }; - Ok(Some(values)) - } - - /// Non-panicking version of [`ArgMatches::get_occurrences`] - pub fn try_get_occurrences( - &self, - id: &str, - ) -> Result>, MatchesError> { - let arg = match ok!(self.try_get_arg_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>, 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>, 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( - &mut self, - id: &str, - ) -> Result, MatchesError> { - match ok!(self.try_remove_arg_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( - &mut self, - id: &str, - ) -> Result>, MatchesError> { - let arg = match ok!(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 = 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( - &mut self, - id: &str, - ) -> Result>, MatchesError> { - let arg = match ok!(self.try_remove_arg_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 { - 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, MatchesError> { - ok!(self.verify_arg(arg)); - Ok(self.args.get(arg)) - } - - #[inline] - fn try_get_arg_t( - &self, - arg: &str, - ) -> Result, MatchesError> { - let arg = match ok!(self.try_get_arg(arg)) { - Some(arg) => arg, - None => { - return Ok(None); - } - }; - ok!(self.verify_arg_t::(arg)); - Ok(Some(arg)) - } - - #[inline] - fn try_remove_arg_t( - &mut self, - arg: &str, - ) -> Result, 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::(); - 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( - &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: &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 ) -/// .value_parser(["auto", "always", "never"])) -/// .arg(arg!(--config ) -/// .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::>(), -/// ["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) { - 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::("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 { - #[allow(clippy::type_complexity)] - iter: Map>>, fn(AnyValue) -> T>, - len: usize, -} - -impl Iterator for Values { - type Item = T; - - fn next(&mut self) -> Option { - if let Some(next) = self.iter.next() { - self.len -= 1; - Some(next) - } else { - None - } - } - fn size_hint(&self) -> (usize, Option) { - (self.len, Some(self.len)) - } -} - -impl DoubleEndedIterator for Values { - fn next_back(&mut self) -> Option { - if let Some(next) = self.iter.next_back() { - self.len -= 1; - Some(next) - } else { - None - } - } -} - -impl ExactSizeIterator for Values {} - -/// Creates an empty iterator. -impl Default for Values { - fn default() -> Self { - let empty: Vec> = 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::("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 { - if let Some(next) = self.iter.next() { - self.len -= 1; - Some(next) - } else { - None - } - } - 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 { - 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; 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!( "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> { - if let Some(next) = self.iter.next() { - self.len -= 1; - Some(next) - } else { - None - } - } - 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> { - 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; 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>, fn(&Vec) -> Vec<&str>>, - len: usize, -} - -#[allow(deprecated)] -impl<'a> Iterator for GroupedValues<'a> { - type Item = Vec<&'a str>; - - fn next(&mut self) -> Option { - if let Some(next) = self.iter.next() { - self.len -= 1; - Some(next) - } else { - None - } - } - fn size_hint(&self) -> (usize, Option) { - (self.len, Some(self.len)) - } -} - -#[allow(deprecated)] -impl<'a> DoubleEndedIterator for GroupedValues<'a> { - fn next_back(&mut self) -> Option { - 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; 0] = []; - GroupedValues { - iter: EMPTY[..].iter().map(|_| unreachable!()), - len: 0, - } - } -} - -#[derive(Clone, Debug)] -pub struct Occurrences { - #[allow(clippy::type_complexity)] - iter: Map>, fn(Vec) -> OccurrenceValues>, -} - -impl Iterator for Occurrences { - type Item = OccurrenceValues; - - fn next(&mut self) -> Option { - self.iter.next() - } - - fn size_hint(&self) -> (usize, Option) { - self.iter.size_hint() - } -} - -impl DoubleEndedIterator for Occurrences { - fn next_back(&mut self) -> Option { - self.iter.next_back() - } -} - -impl ExactSizeIterator for Occurrences {} - -impl Default for Occurrences { - fn default() -> Self { - let empty: Vec> = Default::default(); - Occurrences { - iter: empty.into_iter().map(|_| unreachable!()), - } - } -} - -#[derive(Clone, Debug)] -pub struct OccurrenceValues { - #[allow(clippy::type_complexity)] - iter: Map, fn(AnyValue) -> T>, -} - -impl Iterator for OccurrenceValues { - type Item = T; - - fn next(&mut self) -> Option { - self.iter.next() - } - - fn size_hint(&self) -> (usize, Option) { - self.iter.size_hint() - } -} - -impl DoubleEndedIterator for OccurrenceValues { - fn next_back(&mut self) -> Option { - self.iter.next_back() - } -} - -impl ExactSizeIterator for OccurrenceValues {} - -#[derive(Clone, Debug)] -pub struct OccurrencesRef<'a, T> { - #[allow(clippy::type_complexity)] - iter: Map>, fn(&Vec) -> OccurrenceValuesRef<'_, T>>, -} - -impl<'a, T> Iterator for OccurrencesRef<'a, T> -where - Self: 'a, -{ - type Item = OccurrenceValuesRef<'a, T>; - - fn next(&mut self) -> Option { - self.iter.next() - } - - fn size_hint(&self) -> (usize, Option) { - self.iter.size_hint() - } -} - -impl<'a, T> DoubleEndedIterator for OccurrencesRef<'a, T> -where - Self: 'a, -{ - fn next_back(&mut self) -> Option { - 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; 0] = []; - OccurrencesRef { - iter: EMPTY[..].iter().map(|_| unreachable!()), - } - } -} - -#[derive(Clone, Debug)] -pub struct OccurrenceValuesRef<'a, T> { - #[allow(clippy::type_complexity)] - iter: Map, fn(&AnyValue) -> &T>, -} - -impl<'a, T> Iterator for OccurrenceValuesRef<'a, T> -where - Self: 'a, -{ - type Item = &'a T; - - fn next(&mut self) -> Option { - self.iter.next() - } - - fn size_hint(&self) -> (usize, Option) { - self.iter.size_hint() - } -} - -impl<'a, T> DoubleEndedIterator for OccurrenceValuesRef<'a, T> -where - Self: 'a, -{ - fn next_back(&mut self) -> Option { - 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>, fn(&Vec) -> RawOccurrenceValues<'_>>, -} - -impl<'a> Iterator for RawOccurrences<'a> { - type Item = RawOccurrenceValues<'a>; - - fn next(&mut self) -> Option { - self.iter.next() - } - - fn size_hint(&self) -> (usize, Option) { - self.iter.size_hint() - } -} - -impl<'a> DoubleEndedIterator for RawOccurrences<'a> { - fn next_back(&mut self) -> Option { - self.iter.next_back() - } -} - -impl<'a> ExactSizeIterator for RawOccurrences<'a> {} - -impl<'a> Default for RawOccurrences<'a> { - fn default() -> Self { - static EMPTY: [Vec; 0] = []; - RawOccurrences { - iter: EMPTY[..].iter().map(|_| unreachable!()), - } - } -} - -#[derive(Clone, Debug)] -pub struct RawOccurrenceValues<'a> { - #[allow(clippy::type_complexity)] - iter: Map, fn(&OsString) -> &OsStr>, -} - -impl<'a> Iterator for RawOccurrenceValues<'a> -where - Self: 'a, -{ - type Item = &'a OsStr; - - fn next(&mut self) -> Option { - self.iter.next() - } - - fn size_hint(&self) -> (usize, Option) { - self.iter.size_hint() - } -} - -impl<'a> DoubleEndedIterator for RawOccurrenceValues<'a> -where - Self: 'a, -{ - fn next_back(&mut self) -> Option { - 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>, - len: usize, -} - -impl<'a> Iterator for Indices<'a> { - type Item = usize; - - fn next(&mut self) -> Option { - if let Some(next) = self.iter.next() { - self.len -= 1; - Some(next) - } else { - None - } - } - fn size_hint(&self) -> (usize, Option) { - (self.len, Some(self.len)) - } -} - -impl<'a> DoubleEndedIterator for Indices<'a> { - fn next_back(&mut self) -> Option { - 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(value: &AnyValue) -> &T { - value.downcast_ref().expect(INTERNAL_ERROR_MSG) -} - -#[track_caller] -fn unwrap_downcast_into(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::("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::("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::>(); - dbg!(&a_index); - let a_value = matches - .remove_many::("a") - .expect("missing aopt values"); - dbg!(&a_value); - let a = a_index.into_iter().zip(a_value).rev().collect::>(); - dbg!(a); - - let b_index = matches - .indices_of("b") - .expect("missing aopt indices") - .collect::>(); - dbg!(&b_index); - let b_value = matches - .remove_many::("b") - .expect("missing aopt values"); - dbg!(&b_value); - let b = b_index.into_iter().zip(b_value).rev().collect::>(); - dbg!(b); - } -} -- cgit v1.2.3