Initial vendor packages

Signed-off-by: Valentin Popov <valentin@popov.link>

4 files changed, 2285 insertions, 0 deletions

diff --git a/vendor/clap_builder/src/parser/matches/arg_matches.rs b/vendor/clap_builder/src/parser/matches/arg_matches.rs
new file mode 100644
index 0000000..e80c39b
--- /dev/null
+++ b/vendor/clap_builder/src/parser/matches/arg_matches.rs
@@ -0,0 +1,2030 @@
+// Std
+use std::any::Any;
+use std::ffi::{OsStr, OsString};
+use std::fmt::Debug;
+use std::iter::{Cloned, Flatten, Map};
+use std::slice::Iter;
+
+// Internal
+#[cfg(debug_assertions)]
+use crate::builder::Str;
+use crate::parser::MatchedArg;
+use crate::parser::MatchesError;
+use crate::parser::ValueSource;
+use crate::util::AnyValue;
+use crate::util::AnyValueId;
+use crate::util::FlatMap;
+use crate::util::Id;
+use crate::INTERNAL_ERROR_MSG;
+
+/// Container for parse results.
+///
+/// Used to get information about the arguments that were supplied to the program at runtime by
+/// the user. New instances of this struct are obtained by using the [`Command::get_matches`] family of
+/// methods.
+///
+/// # Examples
+///
+/// ```no_run
+/// # use clap_builder as clap;
+/// # use clap::{Command, Arg, ArgAction};
+/// # use clap::parser::ValueSource;
+/// let matches = Command::new("MyApp")
+///     .arg(Arg::new("out")
+///         .long("output")
+///         .required(true)
+///         .action(ArgAction::Set)
+///         .default_value("-"))
+///     .arg(Arg::new("cfg")
+///         .short('c')
+///         .action(ArgAction::Set))
+///     .get_matches(); // builds the instance of ArgMatches
+///
+/// // to get information about the "cfg" argument we created, such as the value supplied we use
+/// // various ArgMatches methods, such as [ArgMatches::get_one]
+/// if let Some(c) = matches.get_one::<String>("cfg") {
+///     println!("Value for -c: {c}");
+/// }
+///
+/// // The ArgMatches::get_one method returns an Option because the user may not have supplied
+/// // that argument at runtime. But if we specified that the argument was "required" as we did
+/// // with the "out" argument, we can safely unwrap because `clap` verifies that was actually
+/// // used at runtime.
+/// println!("Value for --output: {}", matches.get_one::<String>("out").unwrap());
+///
+/// // You can check the presence of an argument's values
+/// if matches.contains_id("out") {
+///     // However, if you want to know where the value came from
+///     if matches.value_source("out").expect("checked contains_id") == ValueSource::CommandLine {
+///         println!("`out` set by user");
+///     } else {
+///         println!("`out` is defaulted");
+///     }
+/// }
+/// ```
+/// [`Command::get_matches`]: crate::Command::get_matches()
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct ArgMatches {
+    #[cfg(debug_assertions)]
+    pub(crate) valid_args: Vec<Id>,
+    #[cfg(debug_assertions)]
+    pub(crate) valid_subcommands: Vec<Str>,
+    pub(crate) args: FlatMap<Id, MatchedArg>,
+    pub(crate) subcommand: Option<Box<SubCommand>>,
+}
+
+/// # Arguments
+impl ArgMatches {
+    /// Gets the value of a specific option or positional argument.
+    ///
+    /// i.e. an argument that [takes an additional value][crate::Arg::num_args] at runtime.
+    ///
+    /// Returns an error if the wrong type was used.
+    ///
+    /// Returns `None` if the option wasn't present.
+    ///
+    /// *NOTE:* This will always return `Some(value)` if [`default_value`] has been set.
+    /// [`ArgMatches::value_source`] can be used to check if a value is present at runtime.
+    ///
+    /// # Panic
+    ///
+    /// If the argument definition and access mismatch.  To handle this case programmatically, see
+    /// [`ArgMatches::try_get_one`].
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// # use clap_builder as clap;
+    /// # use clap::{Command, Arg, value_parser, ArgAction};
+    /// let m = Command::new("myapp")
+    ///     .arg(Arg::new("port")
+    ///         .value_parser(value_parser!(usize))
+    ///         .action(ArgAction::Set)
+    ///         .required(true))
+    ///     .get_matches_from(vec!["myapp", "2020"]);
+    ///
+    /// let port: usize = *m
+    ///     .get_one("port")
+    ///     .expect("`port`is required");
+    /// assert_eq!(port, 2020);
+    /// ```
+    /// [positional]: crate::Arg::index()
+    /// [`default_value`]: crate::Arg::default_value()
+    #[cfg_attr(debug_assertions, track_caller)]
+    pub fn get_one<T: Any + Clone + Send + Sync + 'static>(&self, id: &str) -> Option<&T> {
+        MatchesError::unwrap(id, self.try_get_one(id))
+    }
+
+    /// Gets the value of a specific [`ArgAction::Count`][crate::ArgAction::Count] flag
+    ///
+    /// # Panic
+    ///
+    /// If the argument's action is not [`ArgAction::Count`][crate::ArgAction::Count]
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// # use clap_builder as clap;
+    /// # use clap::Command;
+    /// # use clap::Arg;
+    /// let cmd = Command::new("mycmd")
+    ///     .arg(
+    ///         Arg::new("flag")
+    ///             .long("flag")
+    ///             .action(clap::ArgAction::Count)
+    ///     );
+    ///
+    /// let matches = cmd.clone().try_get_matches_from(["mycmd", "--flag", "--flag"]).unwrap();
+    /// assert_eq!(
+    ///     matches.get_count("flag"),
+    ///     2
+    /// );
+    /// ```
+    #[cfg_attr(debug_assertions, track_caller)]
+    pub fn get_count(&self, id: &str) -> u8 {
+        *self.get_one::<u8>(id).unwrap_or_else(|| {
+            panic!("arg `{id}`'s `ArgAction` should be `Count` which should provide a default")
+        })
+    }
+
+    /// Gets the value of a specific [`ArgAction::SetTrue`][crate::ArgAction::SetTrue] or [`ArgAction::SetFalse`][crate::ArgAction::SetFalse] flag
+    ///
+    /// # Panic
+    ///
+    /// If the argument's action is not [`ArgAction::SetTrue`][crate::ArgAction::SetTrue] or [`ArgAction::SetFalse`][crate::ArgAction::SetFalse]
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// # use clap_builder as clap;
+    /// # use clap::Command;
+    /// # use clap::Arg;
+    /// let cmd = Command::new("mycmd")
+    ///     .arg(
+    ///         Arg::new("flag")
+    ///             .long("flag")
+    ///             .action(clap::ArgAction::SetTrue)
+    ///     );
+    ///
+    /// let matches = cmd.clone().try_get_matches_from(["mycmd", "--flag"]).unwrap();
+    /// assert!(matches.contains_id("flag"));
+    /// assert_eq!(
+    ///     matches.get_flag("flag"),
+    ///     true
+    /// );
+    /// ```
+    #[cfg_attr(debug_assertions, track_caller)]
+    pub fn get_flag(&self, id: &str) -> bool {
+        *self
+            .get_one::<bool>(id)
+            .unwrap_or_else(|| {
+                panic!(
+                    "arg `{id}`'s `ArgAction` should be one of `SetTrue`, `SetFalse` which should provide a default"
+                )
+            })
+    }
+
+    /// Iterate over values of a specific option or positional argument.
+    ///
+    /// i.e. an argument that takes multiple values at runtime.
+    ///
+    /// Returns an error if the wrong type was used.
+    ///
+    /// Returns `None` if the option wasn't present.
+    ///
+    /// # Panic
+    ///
+    /// If the argument definition and access mismatch.  To handle this case programmatically, see
+    /// [`ArgMatches::try_get_many`].
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// # use clap_builder as clap;
+    /// # use clap::{Command, Arg, value_parser, ArgAction};
+    /// let m = Command::new("myprog")
+    ///     .arg(Arg::new("ports")
+    ///         .action(ArgAction::Append)
+    ///         .value_parser(value_parser!(usize))
+    ///         .short('p')
+    ///         .required(true))
+    ///     .get_matches_from(vec![
+    ///         "myprog", "-p", "22", "-p", "80", "-p", "2020"
+    ///     ]);
+    /// let vals: Vec<usize> = m.get_many("ports")
+    ///     .expect("`port`is required")
+    ///     .copied()
+    ///     .collect();
+    /// assert_eq!(vals, [22, 80, 2020]);
+    /// ```
+    #[cfg_attr(debug_assertions, track_caller)]
+    pub fn get_many<T: Any + Clone + Send + Sync + 'static>(
+        &self,
+        id: &str,
+    ) -> Option<ValuesRef<T>> {
+        MatchesError::unwrap(id, self.try_get_many(id))
+    }
+
+    /// Iterate over the values passed to each occurrence of an option.
+    ///
+    /// Each item is itself an iterator containing the arguments passed to a single occurrence
+    /// of the option.
+    ///
+    /// If the option doesn't support multiple occurrences, or there was only a single occurrence,
+    /// the iterator will only contain a single item.
+    ///
+    /// Returns `None` if the option wasn't present.
+    ///
+    /// # Panics
+    ///
+    /// If the argument definition and access mismatch (debug builds). To handle this case programmatically, see
+    /// [`ArgMatches::try_get_occurrences`].
+    ///
+    /// # Examples
+    /// ```rust
+    /// # use clap_builder as clap;
+    /// # use clap::{Command,Arg, ArgAction, value_parser};
+    /// let m = Command::new("myprog")
+    ///     .arg(Arg::new("x")
+    ///         .short('x')
+    ///         .num_args(2)
+    ///         .action(ArgAction::Append)
+    ///         .value_parser(value_parser!(String)))
+    ///     .get_matches_from(vec![
+    ///         "myprog", "-x", "a", "b", "-x", "c", "d"]);
+    /// let vals: Vec<Vec<&String>> = m.get_occurrences("x").unwrap().map(Iterator::collect).collect();
+    /// assert_eq!(vals, [["a", "b"], ["c", "d"]]);
+    /// ```
+    #[cfg_attr(debug_assertions, track_caller)]
+    pub fn get_occurrences<T: Any + Clone + Send + Sync + 'static>(
+        &self,
+        id: &str,
+    ) -> Option<OccurrencesRef<T>> {
+        MatchesError::unwrap(id, self.try_get_occurrences(id))
+    }
+
+    /// Iterate over the original argument values.
+    ///
+    /// An `OsStr` on Unix-like systems is any series of bytes, regardless of whether or not they
+    /// contain valid UTF-8. Since [`String`]s in Rust are guaranteed to be valid UTF-8, a valid
+    /// filename on a Unix system as an argument value may contain invalid UTF-8.
+    ///
+    /// Returns `None` if the option wasn't present.
+    ///
+    /// # Panic
+    ///
+    /// If the argument definition and access mismatch.  To handle this case programmatically, see
+    /// [`ArgMatches::try_get_raw`].
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// # #[cfg(unix)] {
+    /// # use clap_builder as clap;
+    /// # use clap::{Command, arg, value_parser};
+    /// # use std::ffi::{OsStr,OsString};
+    /// # use std::os::unix::ffi::{OsStrExt,OsStringExt};
+    /// use std::path::PathBuf;
+    ///
+    /// let m = Command::new("utf8")
+    ///     .arg(arg!(<arg> ... "some arg").value_parser(value_parser!(PathBuf)))
+    ///     .get_matches_from(vec![OsString::from("myprog"),
+    ///                                 // "Hi"
+    ///                                 OsString::from_vec(vec![b'H', b'i']),
+    ///                                 // "{0xe9}!"
+    ///                                 OsString::from_vec(vec![0xe9, b'!'])]);
+    ///
+    /// let mut itr = m.get_raw("arg")
+    ///     .expect("`port`is required")
+    ///     .into_iter();
+    /// assert_eq!(itr.next(), Some(OsStr::new("Hi")));
+    /// assert_eq!(itr.next(), Some(OsStr::from_bytes(&[0xe9, b'!'])));
+    /// assert_eq!(itr.next(), None);
+    /// # }
+    /// ```
+    /// [`Iterator`]: std::iter::Iterator
+    /// [`OsSt`]: std::ffi::OsStr
+    /// [values]: OsValues
+    /// [`String`]: std::string::String
+    #[cfg_attr(debug_assertions, track_caller)]
+    pub fn get_raw(&self, id: &str) -> Option<RawValues<'_>> {
+        MatchesError::unwrap(id, self.try_get_raw(id))
+    }
+
+    /// Iterate over the original values for each occurrence of an option.
+    ///
+    /// Similar to [`ArgMatches::get_occurrences`] but returns raw values.
+    ///
+    /// An `OsStr` on Unix-like systems is any series of bytes, regardless of whether or not they
+    /// contain valid UTF-8. Since [`String`]s in Rust are guaranteed to be valid UTF-8, a valid
+    /// filename on a Unix system as an argument value may contain invalid UTF-8.
+    ///
+    /// Returns `None` if the option wasn't present.
+    ///
+    /// # Panic
+    ///
+    /// If the argument definition and access mismatch.  To handle this case programmatically, see
+    /// [`ArgMatches::try_get_raw_occurrences`].
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// # #[cfg(unix)] {
+    /// # use clap_builder as clap;
+    /// # use clap::{Command, arg, value_parser, ArgAction, Arg};
+    /// # use std::ffi::{OsStr,OsString};
+    /// # use std::os::unix::ffi::{OsStrExt,OsStringExt};
+    /// use std::path::PathBuf;
+    ///
+    /// let m = Command::new("myprog")
+    ///     .arg(Arg::new("x")
+    ///         .short('x')
+    ///         .num_args(2)
+    ///         .action(ArgAction::Append)
+    ///         .value_parser(value_parser!(PathBuf)))
+    ///     .get_matches_from(vec![OsString::from("myprog"),
+    ///                             OsString::from("-x"),
+    ///                             OsString::from("a"), OsString::from("b"),
+    ///                             OsString::from("-x"),
+    ///                             OsString::from("c"),
+    ///                             // "{0xe9}!"
+    ///                             OsString::from_vec(vec![0xe9, b'!'])]);
+    /// let mut itr = m.get_raw_occurrences("x")
+    ///     .expect("`-x`is required")
+    ///     .map(Iterator::collect::<Vec<_>>);
+    /// assert_eq!(itr.next(), Some(vec![OsStr::new("a"), OsStr::new("b")]));
+    /// assert_eq!(itr.next(), Some(vec![OsStr::new("c"), OsStr::from_bytes(&[0xe9, b'!'])]));
+    /// assert_eq!(itr.next(), None);
+    /// # }
+    /// ```
+    /// [`Iterator`]: std::iter::Iterator
+    /// [`OsStr`]: std::ffi::OsStr
+    /// [values]: OsValues
+    /// [`String`]: std::string::String
+    #[cfg_attr(debug_assertions, track_caller)]
+    pub fn get_raw_occurrences(&self, id: &str) -> Option<RawOccurrences<'_>> {
+        MatchesError::unwrap(id, self.try_get_raw_occurrences(id))
+    }
+
+    /// Returns the value of a specific option or positional argument.
+    ///
+    /// i.e. an argument that [takes an additional value][crate::Arg::num_args] at runtime.
+    ///
+    /// Returns an error if the wrong type was used.  No item will have been removed.
+    ///
+    /// Returns `None` if the option wasn't present.
+    ///
+    /// *NOTE:* This will always return `Some(value)` if [`default_value`] has been set.
+    /// [`ArgMatches::value_source`] can be used to check if a value is present at runtime.
+    ///
+    /// # Panic
+    ///
+    /// If the argument definition and access mismatch.  To handle this case programmatically, see
+    /// [`ArgMatches::try_remove_one`].
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// # use clap_builder as clap;
+    /// # use clap::{Command, Arg, value_parser, ArgAction};
+    /// let mut m = Command::new("myprog")
+    ///     .arg(Arg::new("file")
+    ///         .required(true)
+    ///         .action(ArgAction::Set))
+    ///     .get_matches_from(vec![
+    ///         "myprog", "file.txt",
+    ///     ]);
+    /// let vals: String = m.remove_one("file")
+    ///     .expect("`file`is required");
+    /// assert_eq!(vals, "file.txt");
+    /// ```
+    /// [positional]: crate::Arg::index()
+    /// [`default_value`]: crate::Arg::default_value()
+    #[cfg_attr(debug_assertions, track_caller)]
+    pub fn remove_one<T: Any + Clone + Send + Sync + 'static>(&mut self, id: &str) -> Option<T> {
+        MatchesError::unwrap(id, self.try_remove_one(id))
+    }
+
+    /// Return values of a specific option or positional argument.
+    ///
+    /// i.e. an argument that takes multiple values at runtime.
+    ///
+    /// Returns an error if the wrong type was used.  No item will have been removed.
+    ///
+    /// Returns `None` if the option wasn't present.
+    ///
+    /// # Panic
+    ///
+    /// If the argument definition and access mismatch.  To handle this case programmatically, see
+    /// [`ArgMatches::try_remove_many`].
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// # use clap_builder as clap;
+    /// # use clap::{Command, Arg, value_parser, ArgAction};
+    /// let mut m = Command::new("myprog")
+    ///     .arg(Arg::new("file")
+    ///         .action(ArgAction::Append)
+    ///         .num_args(1..)
+    ///         .required(true))
+    ///     .get_matches_from(vec![
+    ///         "myprog", "file1.txt", "file2.txt", "file3.txt", "file4.txt",
+    ///     ]);
+    /// let vals: Vec<String> = m.remove_many("file")
+    ///     .expect("`file`is required")
+    ///     .collect();
+    /// assert_eq!(vals, ["file1.txt", "file2.txt", "file3.txt", "file4.txt"]);
+    /// ```
+    #[cfg_attr(debug_assertions, track_caller)]
+    pub fn remove_many<T: Any + Clone + Send + Sync + 'static>(
+        &mut self,
+        id: &str,
+    ) -> Option<Values<T>> {
+        MatchesError::unwrap(id, self.try_remove_many(id))
+    }
+
+    /// Return values for each occurrence of an option.
+    ///
+    /// Each item is itself an iterator containing the arguments passed to a single occurrence of
+    /// the option.
+    ///
+    /// If the option doesn't support multiple occurrences, or there was only a single occurrence,
+    /// the iterator will only contain a single item.
+    ///
+    /// Returns `None` if the option wasn't present.
+    ///
+    /// # Panic
+    ///
+    /// If the argument definition and access mismatch.  To handle this case programmatically, see
+    /// [`ArgMatches::try_remove_occurrences`].
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// # use clap_builder as clap;
+    /// # use clap::{Command, Arg, value_parser, ArgAction};
+    /// let mut m = Command::new("myprog")
+    ///     .arg(Arg::new("x")
+    ///         .short('x')
+    ///         .num_args(2)
+    ///         .action(ArgAction::Append)
+    ///         .value_parser(value_parser!(String)))
+    ///     .get_matches_from(vec![
+    ///         "myprog", "-x", "a", "b", "-x", "c", "d"]);
+    /// let vals: Vec<Vec<String>> = m.remove_occurrences("x").unwrap().map(Iterator::collect).collect();
+    /// assert_eq!(vals, [["a", "b"], ["c", "d"]]);
+    /// ```
+    #[cfg_attr(debug_assertions, track_caller)]
+    pub fn remove_occurrences<T: Any + Clone + Send + Sync + 'static>(
+        &mut self,
+        id: &str,
+    ) -> Option<Occurrences<T>> {
+        MatchesError::unwrap(id, self.try_remove_occurrences(id))
+    }
+
+    /// Check if values are present for the argument or group id
+    ///
+    /// *NOTE:* This will always return `true` if [`default_value`] has been set.
+    /// [`ArgMatches::value_source`] can be used to check if a value is present at runtime.
+    ///
+    /// # Panics
+    ///
+    /// If `id` is not a valid argument or group name (debug builds).  To handle this case programmatically, see
+    /// [`ArgMatches::try_contains_id`].
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// # use clap_builder as clap;
+    /// # use clap::{Command, Arg, ArgAction};
+    /// let m = Command::new("myprog")
+    ///     .arg(Arg::new("debug")
+    ///         .short('d')
+    ///         .action(ArgAction::SetTrue))
+    ///     .get_matches_from(vec![
+    ///         "myprog", "-d"
+    ///     ]);
+    ///
+    /// assert!(m.contains_id("debug"));
+    /// ```
+    ///
+    /// [`default_value`]: crate::Arg::default_value()
+    pub fn contains_id(&self, id: &str) -> bool {
+        MatchesError::unwrap(id, self.try_contains_id(id))
+    }
+
+    /// Iterate over [`Arg`][crate::Arg] and [`ArgGroup`][crate::ArgGroup] [`Id`]s via [`ArgMatches::ids`].
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// # use clap_builder as clap;
+    /// # use clap::{Command, arg, value_parser};
+    ///
+    /// let m = Command::new("myprog")
+    ///     .arg(arg!(--color <when>)
+    ///         .value_parser(["auto", "always", "never"]))
+    ///     .arg(arg!(--config <path>)
+    ///         .value_parser(value_parser!(std::path::PathBuf)))
+    ///     .get_matches_from(["myprog", "--config=config.toml", "--color=auto"]);
+    /// assert_eq!(m.ids().len(), 2);
+    /// assert_eq!(
+    ///     m.ids()
+    ///         .map(|id| id.as_str())
+    ///         .collect::<Vec<_>>(),
+    ///     ["config", "color"]
+    /// );
+    /// ```
+    pub fn ids(&self) -> IdsRef<'_> {
+        IdsRef {
+            iter: self.args.keys(),
+        }
+    }
+
+    /// Check if any args were present on the command line
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// # use clap_builder as clap;
+    /// # use clap::{Command, Arg, ArgAction};
+    /// let mut cmd = Command::new("myapp")
+    ///     .arg(Arg::new("output")
+    ///         .action(ArgAction::Set));
+    ///
+    /// let m = cmd
+    ///     .try_get_matches_from_mut(vec!["myapp", "something"])
+    ///     .unwrap();
+    /// assert!(m.args_present());
+    ///
+    /// let m = cmd
+    ///     .try_get_matches_from_mut(vec!["myapp"])
+    ///     .unwrap();
+    /// assert!(! m.args_present());
+    pub fn args_present(&self) -> bool {
+        !self.args.is_empty()
+    }
+
+    /// Report where argument value came from
+    ///
+    /// # Panics
+    ///
+    /// If `id` is not a valid argument or group id (debug builds).
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// # use clap_builder as clap;
+    /// # use clap::{Command, Arg, ArgAction};
+    /// # use clap::parser::ValueSource;
+    /// let m = Command::new("myprog")
+    ///     .arg(Arg::new("debug")
+    ///         .short('d')
+    ///         .action(ArgAction::SetTrue))
+    ///     .get_matches_from(vec![
+    ///         "myprog", "-d"
+    ///     ]);
+    ///
+    /// assert_eq!(m.value_source("debug"), Some(ValueSource::CommandLine));
+    /// ```
+    ///
+    /// [`default_value`]: crate::Arg::default_value()
+    #[cfg_attr(debug_assertions, track_caller)]
+    pub fn value_source(&self, id: &str) -> Option<ValueSource> {
+        let value = self.get_arg(id);
+
+        value.and_then(MatchedArg::source)
+    }
+
+    /// The first index of that an argument showed up.
+    ///
+    /// Indices are similar to argv indices, but are not exactly 1:1.
+    ///
+    /// For flags (i.e. those arguments which don't have an associated value), indices refer
+    /// to occurrence of the switch, such as `-f`, or `--flag`. However, for options the indices
+    /// refer to the *values* `-o val` would therefore not represent two distinct indices, only the
+    /// index for `val` would be recorded. This is by design.
+    ///
+    /// Besides the flag/option discrepancy, the primary difference between an argv index and clap
+    /// index, is that clap continues counting once all arguments have properly separated, whereas
+    /// an argv index does not.
+    ///
+    /// The examples should clear this up.
+    ///
+    /// *NOTE:* If an argument is allowed multiple times, this method will only give the *first*
+    /// index.  See [`ArgMatches::indices_of`].
+    ///
+    /// # Panics
+    ///
+    /// If `id` is not a valid argument or group id (debug builds).
+    ///
+    /// # Examples
+    ///
+    /// The argv indices are listed in the comments below. See how they correspond to the clap
+    /// indices. Note that if it's not listed in a clap index, this is because it's not saved in
+    /// in an `ArgMatches` struct for querying.
+    ///
+    /// ```rust
+    /// # use clap_builder as clap;
+    /// # use clap::{Command, Arg, ArgAction};
+    /// let m = Command::new("myapp")
+    ///     .arg(Arg::new("flag")
+    ///         .short('f')
+    ///         .action(ArgAction::SetTrue))
+    ///     .arg(Arg::new("option")
+    ///         .short('o')
+    ///         .action(ArgAction::Set))
+    ///     .get_matches_from(vec!["myapp", "-f", "-o", "val"]);
+    ///            // ARGV indices: ^0       ^1    ^2    ^3
+    ///            // clap indices:          ^1          ^3
+    ///
+    /// assert_eq!(m.index_of("flag"), Some(1));
+    /// assert_eq!(m.index_of("option"), Some(3));
+    /// ```
+    ///
+    /// Now notice, if we use one of the other styles of options:
+    ///
+    /// ```rust
+    /// # use clap_builder as clap;
+    /// # use clap::{Command, Arg, ArgAction};
+    /// let m = Command::new("myapp")
+    ///     .arg(Arg::new("flag")
+    ///         .short('f')
+    ///         .action(ArgAction::SetTrue))
+    ///     .arg(Arg::new("option")
+    ///         .short('o')
+    ///         .action(ArgAction::Set))
+    ///     .get_matches_from(vec!["myapp", "-f", "-o=val"]);
+    ///            // ARGV indices: ^0       ^1    ^2
+    ///            // clap indices:          ^1       ^3
+    ///
+    /// assert_eq!(m.index_of("flag"), Some(1));
+    /// assert_eq!(m.index_of("option"), Some(3));
+    /// ```
+    ///
+    /// Things become much more complicated, or clear if we look at a more complex combination of
+    /// flags. Let's also throw in the final option style for good measure.
+    ///
+    /// ```rust
+    /// # use clap_builder as clap;
+    /// # use clap::{Command, Arg, ArgAction};
+    /// let m = Command::new("myapp")
+    ///     .arg(Arg::new("flag")
+    ///         .short('f')
+    ///         .action(ArgAction::SetTrue))
+    ///     .arg(Arg::new("flag2")
+    ///         .short('F')
+    ///         .action(ArgAction::SetTrue))
+    ///     .arg(Arg::new("flag3")
+    ///         .short('z')
+    ///         .action(ArgAction::SetTrue))
+    ///     .arg(Arg::new("option")
+    ///         .short('o')
+    ///         .action(ArgAction::Set))
+    ///     .get_matches_from(vec!["myapp", "-fzF", "-oval"]);
+    ///            // ARGV indices: ^0      ^1       ^2
+    ///            // clap indices:         ^1,2,3    ^5
+    ///            //
+    ///            // clap sees the above as 'myapp -f -z -F -o val'
+    ///            //                         ^0    ^1 ^2 ^3 ^4 ^5
+    /// assert_eq!(m.index_of("flag"), Some(1));
+    /// assert_eq!(m.index_of("flag2"), Some(3));
+    /// assert_eq!(m.index_of("flag3"), Some(2));
+    /// assert_eq!(m.index_of("option"), Some(5));
+    /// ```
+    ///
+    /// One final combination of flags/options to see how they combine:
+    ///
+    /// ```rust
+    /// # use clap_builder as clap;
+    /// # use clap::{Command, Arg, ArgAction};
+    /// let m = Command::new("myapp")
+    ///     .arg(Arg::new("flag")
+    ///         .short('f')
+    ///         .action(ArgAction::SetTrue))
+    ///     .arg(Arg::new("flag2")
+    ///         .short('F')
+    ///         .action(ArgAction::SetTrue))
+    ///     .arg(Arg::new("flag3")
+    ///         .short('z')
+    ///         .action(ArgAction::SetTrue))
+    ///     .arg(Arg::new("option")
+    ///         .short('o')
+    ///         .action(ArgAction::Set))
+    ///     .get_matches_from(vec!["myapp", "-fzFoval"]);
+    ///            // ARGV indices: ^0       ^1
+    ///            // clap indices:          ^1,2,3^5
+    ///            //
+    ///            // clap sees the above as 'myapp -f -z -F -o val'
+    ///            //                         ^0    ^1 ^2 ^3 ^4 ^5
+    /// assert_eq!(m.index_of("flag"), Some(1));
+    /// assert_eq!(m.index_of("flag2"), Some(3));
+    /// assert_eq!(m.index_of("flag3"), Some(2));
+    /// assert_eq!(m.index_of("option"), Some(5));
+    /// ```
+    ///
+    /// The last part to mention is when values are sent in multiple groups with a [delimiter].
+    ///
+    /// ```rust
+    /// # use clap_builder as clap;
+    /// # use clap::{Command, Arg};
+    /// let m = Command::new("myapp")
+    ///     .arg(Arg::new("option")
+    ///         .short('o')
+    ///         .value_delimiter(',')
+    ///         .num_args(1..))
+    ///     .get_matches_from(vec!["myapp", "-o=val1,val2,val3"]);
+    ///            // ARGV indices: ^0       ^1
+    ///            // clap indices:             ^2   ^3   ^4
+    ///            //
+    ///            // clap sees the above as 'myapp -o val1 val2 val3'
+    ///            //                         ^0    ^1 ^2   ^3   ^4
+    /// assert_eq!(m.index_of("option"), Some(2));
+    /// assert_eq!(m.indices_of("option").unwrap().collect::<Vec<_>>(), &[2, 3, 4]);
+    /// ```
+    /// [delimiter]: crate::Arg::value_delimiter()
+    #[cfg_attr(debug_assertions, track_caller)]
+    pub fn index_of(&self, id: &str) -> Option<usize> {
+        let arg = some!(self.get_arg(id));
+        let i = some!(arg.get_index(0));
+        Some(i)
+    }
+
+    /// All indices an argument appeared at when parsing.
+    ///
+    /// Indices are similar to argv indices, but are not exactly 1:1.
+    ///
+    /// For flags (i.e. those arguments which don't have an associated value), indices refer
+    /// to occurrence of the switch, such as `-f`, or `--flag`. However, for options the indices
+    /// refer to the *values* `-o val` would therefore not represent two distinct indices, only the
+    /// index for `val` would be recorded. This is by design.
+    ///
+    /// *NOTE:* For more information about how clap indices compared to argv indices, see
+    /// [`ArgMatches::index_of`]
+    ///
+    /// # Panics
+    ///
+    /// If `id` is not a valid argument or group id (debug builds).
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// # use clap_builder as clap;
+    /// # use clap::{Command, Arg};
+    /// let m = Command::new("myapp")
+    ///     .arg(Arg::new("option")
+    ///         .short('o')
+    ///         .value_delimiter(','))
+    ///     .get_matches_from(vec!["myapp", "-o=val1,val2,val3"]);
+    ///            // ARGV indices: ^0       ^1
+    ///            // clap indices:             ^2   ^3   ^4
+    ///            //
+    ///            // clap sees the above as 'myapp -o val1 val2 val3'
+    ///            //                         ^0    ^1 ^2   ^3   ^4
+    /// assert_eq!(m.indices_of("option").unwrap().collect::<Vec<_>>(), &[2, 3, 4]);
+    /// ```
+    ///
+    /// Another quick example is when flags and options are used together
+    ///
+    /// ```rust
+    /// # use clap_builder as clap;
+    /// # use clap::{Command, Arg, ArgAction};
+    /// let m = Command::new("myapp")
+    ///     .arg(Arg::new("option")
+    ///         .short('o')
+    ///         .action(ArgAction::Set)
+    ///         .action(ArgAction::Append))
+    ///     .arg(Arg::new("flag")
+    ///         .short('f')
+    ///         .action(ArgAction::Count))
+    ///     .get_matches_from(vec!["myapp", "-o", "val1", "-f", "-o", "val2", "-f"]);
+    ///            // ARGV indices: ^0       ^1    ^2      ^3    ^4    ^5      ^6
+    ///            // clap indices:                ^2      ^3          ^5      ^6
+    ///
+    /// assert_eq!(m.indices_of("option").unwrap().collect::<Vec<_>>(), &[2, 5]);
+    /// assert_eq!(m.indices_of("flag").unwrap().collect::<Vec<_>>(), &[6]);
+    /// ```
+    ///
+    /// One final example, which is an odd case; if we *don't* use  value delimiter as we did with
+    /// the first example above instead of `val1`, `val2` and `val3` all being distinc values, they
+    /// would all be a single value of `val1,val2,val3`, in which case they'd only receive a single
+    /// index.
+    ///
+    /// ```rust
+    /// # use clap_builder as clap;
+    /// # use clap::{Command, Arg, ArgAction};
+    /// let m = Command::new("myapp")
+    ///     .arg(Arg::new("option")
+    ///         .short('o')
+    ///         .action(ArgAction::Set)
+    ///         .num_args(1..))
+    ///     .get_matches_from(vec!["myapp", "-o=val1,val2,val3"]);
+    ///            // ARGV indices: ^0       ^1
+    ///            // clap indices:             ^2
+    ///            //
+    ///            // clap sees the above as 'myapp -o "val1,val2,val3"'
+    ///            //                         ^0    ^1  ^2
+    /// assert_eq!(m.indices_of("option").unwrap().collect::<Vec<_>>(), &[2]);
+    /// ```
+    /// [`ArgMatches::index_of`]: ArgMatches::index_of()
+    /// [delimiter]: Arg::value_delimiter()
+    #[cfg_attr(debug_assertions, track_caller)]
+    pub fn indices_of(&self, id: &str) -> Option<Indices<'_>> {
+        let arg = some!(self.get_arg(id));
+        let i = Indices {
+            iter: arg.indices(),
+            len: arg.num_vals(),
+        };
+        Some(i)
+    }
+}
+
+/// # Subcommands
+impl ArgMatches {
+    /// The name and `ArgMatches` of the current [subcommand].
+    ///
+    /// Subcommand values are put in a child [`ArgMatches`]
+    ///
+    /// Returns `None` if the subcommand wasn't present at runtime,
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// # use clap_builder as clap;
+    /// # use clap::{Command, Arg, };
+    ///  let app_m = Command::new("git")
+    ///      .subcommand(Command::new("clone"))
+    ///      .subcommand(Command::new("push"))
+    ///      .subcommand(Command::new("commit"))
+    ///      .get_matches();
+    ///
+    /// match app_m.subcommand() {
+    ///     Some(("clone",  sub_m)) => {}, // clone was used
+    ///     Some(("push",   sub_m)) => {}, // push was used
+    ///     Some(("commit", sub_m)) => {}, // commit was used
+    ///     _                       => {}, // Either no subcommand or one not tested for...
+    /// }
+    /// ```
+    ///
+    /// Another useful scenario is when you want to support third party, or external, subcommands.
+    /// In these cases you can't know the subcommand name ahead of time, so use a variable instead
+    /// with pattern matching!
+    ///
+    /// ```rust
+    /// # use clap_builder as clap;
+    /// # use std::ffi::OsString;
+    /// # use std::ffi::OsStr;
+    /// # use clap::Command;
+    /// // Assume there is an external subcommand named "subcmd"
+    /// let app_m = Command::new("myprog")
+    ///     .allow_external_subcommands(true)
+    ///     .get_matches_from(vec![
+    ///         "myprog", "subcmd", "--option", "value", "-fff", "--flag"
+    ///     ]);
+    ///
+    /// // All trailing arguments will be stored under the subcommand's sub-matches using an empty
+    /// // string argument name
+    /// match app_m.subcommand() {
+    ///     Some((external, sub_m)) => {
+    ///          let ext_args: Vec<&OsStr> = sub_m.get_many::<OsString>("")
+    ///             .unwrap().map(|s| s.as_os_str()).collect();
+    ///          assert_eq!(external, "subcmd");
+    ///          assert_eq!(ext_args, ["--option", "value", "-fff", "--flag"]);
+    ///     },
+    ///     _ => {},
+    /// }
+    /// ```
+    /// [subcommand]: crate::Command::subcommand
+    #[inline]
+    pub fn subcommand(&self) -> Option<(&str, &ArgMatches)> {
+        self.subcommand.as_ref().map(|sc| (&*sc.name, &sc.matches))
+    }
+
+    /// Return the name and `ArgMatches` of the current [subcommand].
+    ///
+    /// Subcommand values are put in a child [`ArgMatches`]
+    ///
+    /// Returns `None` if the subcommand wasn't present at runtime,
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// # use clap_builder as clap;
+    /// # use clap::{Command, Arg, };
+    ///  let mut app_m = Command::new("git")
+    ///      .subcommand(Command::new("clone"))
+    ///      .subcommand(Command::new("push"))
+    ///      .subcommand(Command::new("commit"))
+    ///      .subcommand_required(true)
+    ///      .get_matches();
+    ///
+    /// let (name, sub_m) = app_m.remove_subcommand().expect("required");
+    /// match (name.as_str(), sub_m) {
+    ///     ("clone",  sub_m) => {}, // clone was used
+    ///     ("push",   sub_m) => {}, // push was used
+    ///     ("commit", sub_m) => {}, // commit was used
+    ///     (name, _)         => unimplemented!("{name}"),
+    /// }
+    /// ```
+    ///
+    /// Another useful scenario is when you want to support third party, or external, subcommands.
+    /// In these cases you can't know the subcommand name ahead of time, so use a variable instead
+    /// with pattern matching!
+    ///
+    /// ```rust
+    /// # use clap_builder as clap;
+    /// # use std::ffi::OsString;
+    /// # use clap::Command;
+    /// // Assume there is an external subcommand named "subcmd"
+    /// let mut app_m = Command::new("myprog")
+    ///     .allow_external_subcommands(true)
+    ///     .get_matches_from(vec![
+    ///         "myprog", "subcmd", "--option", "value", "-fff", "--flag"
+    ///     ]);
+    ///
+    /// // All trailing arguments will be stored under the subcommand's sub-matches using an empty
+    /// // string argument name
+    /// match app_m.remove_subcommand() {
+    ///     Some((external, mut sub_m)) => {
+    ///          let ext_args: Vec<OsString> = sub_m.remove_many("")
+    ///             .expect("`file`is required")
+    ///             .collect();
+    ///          assert_eq!(external, "subcmd");
+    ///          assert_eq!(ext_args, ["--option", "value", "-fff", "--flag"]);
+    ///     },
+    ///     _ => {},
+    /// }
+    /// ```
+    /// [subcommand]: crate::Command::subcommand
+    pub fn remove_subcommand(&mut self) -> Option<(String, ArgMatches)> {
+        self.subcommand.take().map(|sc| (sc.name, sc.matches))
+    }
+
+    /// The `ArgMatches` for the current [subcommand].
+    ///
+    /// Subcommand values are put in a child [`ArgMatches`]
+    ///
+    /// Returns `None` if the subcommand wasn't present at runtime,
+    ///
+    /// # Panics
+    ///
+    /// If `id` is not a valid subcommand (debug builds).
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// # use clap_builder as clap;
+    /// # use clap::{Command, Arg, ArgAction};
+    /// let app_m = Command::new("myprog")
+    ///     .arg(Arg::new("debug")
+    ///         .short('d')
+    ///         .action(ArgAction::SetTrue)
+    ///     )
+    ///     .subcommand(Command::new("test")
+    ///         .arg(Arg::new("opt")
+    ///             .long("option")
+    ///             .action(ArgAction::Set)))
+    ///     .get_matches_from(vec![
+    ///         "myprog", "-d", "test", "--option", "val"
+    ///     ]);
+    ///
+    /// // Both parent commands, and child subcommands can have arguments present at the same times
+    /// assert!(app_m.get_flag("debug"));
+    ///
+    /// // Get the subcommand's ArgMatches instance
+    /// if let Some(sub_m) = app_m.subcommand_matches("test") {
+    ///     // Use the struct like normal
+    ///     assert_eq!(sub_m.get_one::<String>("opt").map(|s| s.as_str()), Some("val"));
+    /// }
+    /// ```
+    ///
+    /// [subcommand]: crate::Command::subcommand
+    /// [`Command`]: crate::Command
+    pub fn subcommand_matches(&self, name: &str) -> Option<&ArgMatches> {
+        self.get_subcommand(name).map(|sc| &sc.matches)
+    }
+
+    /// The name of the current [subcommand].
+    ///
+    /// Returns `None` if the subcommand wasn't present at runtime,
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// # use clap_builder as clap;
+    /// # use clap::{Command, Arg, };
+    ///  let app_m = Command::new("git")
+    ///      .subcommand(Command::new("clone"))
+    ///      .subcommand(Command::new("push"))
+    ///      .subcommand(Command::new("commit"))
+    ///      .get_matches();
+    ///
+    /// match app_m.subcommand_name() {
+    ///     Some("clone")  => {}, // clone was used
+    ///     Some("push")   => {}, // push was used
+    ///     Some("commit") => {}, // commit was used
+    ///     _              => {}, // Either no subcommand or one not tested for...
+    /// }
+    /// ```
+    /// [subcommand]: crate::Command::subcommand
+    /// [`Command`]: crate::Command
+    #[inline]
+    pub fn subcommand_name(&self) -> Option<&str> {
+        self.subcommand.as_ref().map(|sc| &*sc.name)
+    }
+
+    /// Check if a subcommand can be queried
+    ///
+    /// By default, `ArgMatches` functions assert on undefined `Id`s to help catch programmer
+    /// mistakes.  In some context, this doesn't work, so users can use this function to check
+    /// before they do a query on `ArgMatches`.
+    #[inline]
+    #[doc(hidden)]
+    pub fn is_valid_subcommand(&self, _name: &str) -> bool {
+        #[cfg(debug_assertions)]
+        {
+            _name.is_empty() || self.valid_subcommands.iter().any(|s| *s == _name)
+        }
+        #[cfg(not(debug_assertions))]
+        {
+            true
+        }
+    }
+}
+
+/// # Advanced
+impl ArgMatches {
+    /// Non-panicking version of [`ArgMatches::get_one`]
+    pub fn try_get_one<T: Any + Clone + Send + Sync + 'static>(
+        &self,
+        id: &str,
+    ) -> Result<Option<&T>, MatchesError> {
+        let arg = ok!(self.try_get_arg_t::<T>(id));
+        let value = match arg.and_then(|a| a.first()) {
+            Some(value) => value,
+            None => {
+                return Ok(None);
+            }
+        };
+        Ok(value
+            .downcast_ref::<T>()
+            .map(Some)
+            .expect(INTERNAL_ERROR_MSG)) // enforced by `try_get_arg_t`
+    }
+
+    /// Non-panicking version of [`ArgMatches::get_many`]
+    pub fn try_get_many<T: Any + Clone + Send + Sync + 'static>(
+        &self,
+        id: &str,
+    ) -> Result<Option<ValuesRef<T>>, MatchesError> {
+        let arg = match ok!(self.try_get_arg_t::<T>(id)) {
+            Some(arg) => arg,
+            None => return Ok(None),
+        };
+        let len = arg.num_vals();
+        let values = arg.vals_flatten();
+        let values = ValuesRef {
+            // enforced by `try_get_arg_t`
+            iter: values.map(unwrap_downcast_ref),
+            len,
+        };
+        Ok(Some(values))
+    }
+
+    /// Non-panicking version of [`ArgMatches::get_occurrences`]
+    pub fn try_get_occurrences<T: Any + Clone + Send + Sync + 'static>(
+        &self,
+        id: &str,
+    ) -> Result<Option<OccurrencesRef<T>>, MatchesError> {
+        let arg = match ok!(self.try_get_arg_t::<T>(id)) {
+            Some(arg) => arg,
+            None => return Ok(None),
+        };
+        let values = arg.vals();
+        Ok(Some(OccurrencesRef {
+            iter: values.map(|g| OccurrenceValuesRef {
+                iter: g.iter().map(unwrap_downcast_ref),
+            }),
+        }))
+    }
+
+    /// Non-panicking version of [`ArgMatches::get_raw`]
+    pub fn try_get_raw(&self, id: &str) -> Result<Option<RawValues<'_>>, MatchesError> {
+        let arg = match ok!(self.try_get_arg(id)) {
+            Some(arg) => arg,
+            None => return Ok(None),
+        };
+        let len = arg.num_vals();
+        let values = arg.raw_vals_flatten();
+        let values = RawValues {
+            iter: values.map(OsString::as_os_str),
+            len,
+        };
+        Ok(Some(values))
+    }
+
+    /// Non-panicking version of [`ArgMatches::get_raw_occurrences`]
+    pub fn try_get_raw_occurrences(
+        &self,
+        id: &str,
+    ) -> Result<Option<RawOccurrences<'_>>, MatchesError> {
+        let arg = match ok!(self.try_get_arg(id)) {
+            Some(arg) => arg,
+            None => return Ok(None),
+        };
+        let values = arg.raw_vals();
+        let occurrences = RawOccurrences {
+            iter: values.map(|g| RawOccurrenceValues {
+                iter: g.iter().map(OsString::as_os_str),
+            }),
+        };
+        Ok(Some(occurrences))
+    }
+
+    /// Non-panicking version of [`ArgMatches::remove_one`]
+    pub fn try_remove_one<T: Any + Clone + Send + Sync + 'static>(
+        &mut self,
+        id: &str,
+    ) -> Result<Option<T>, MatchesError> {
+        match ok!(self.try_remove_arg_t::<T>(id)) {
+            Some(values) => Ok(values
+                .into_vals_flatten()
+                // enforced by `try_get_arg_t`
+                .map(unwrap_downcast_into)
+                .next()),
+            None => Ok(None),
+        }
+    }
+
+    /// Non-panicking version of [`ArgMatches::remove_many`]
+    pub fn try_remove_many<T: Any + Clone + Send + Sync + 'static>(
+        &mut self,
+        id: &str,
+    ) -> Result<Option<Values<T>>, MatchesError> {
+        let arg = match ok!(self.try_remove_arg_t::<T>(id)) {
+            Some(arg) => arg,
+            None => return Ok(None),
+        };
+        let len = arg.num_vals();
+        let values = arg.into_vals_flatten();
+        let values = Values {
+            // enforced by `try_get_arg_t`
+            iter: values.map(unwrap_downcast_into),
+            len,
+        };
+        Ok(Some(values))
+    }
+
+    /// Non-panicking version of [`ArgMatches::remove_occurrences`]
+    pub fn try_remove_occurrences<T: Any + Clone + Send + Sync + 'static>(
+        &mut self,
+        id: &str,
+    ) -> Result<Option<Occurrences<T>>, MatchesError> {
+        let arg = match ok!(self.try_remove_arg_t::<T>(id)) {
+            Some(arg) => arg,
+            None => return Ok(None),
+        };
+        let values = arg.into_vals();
+        let occurrences = Occurrences {
+            iter: values.into_iter().map(|g| OccurrenceValues {
+                iter: g.into_iter().map(unwrap_downcast_into),
+            }),
+        };
+        Ok(Some(occurrences))
+    }
+
+    /// Non-panicking version of [`ArgMatches::contains_id`]
+    pub fn try_contains_id(&self, id: &str) -> Result<bool, MatchesError> {
+        ok!(self.verify_arg(id));
+
+        let presence = self.args.contains_key(id);
+        Ok(presence)
+    }
+}
+
+// Private methods
+impl ArgMatches {
+    #[inline]
+    fn try_get_arg(&self, arg: &str) -> Result<Option<&MatchedArg>, MatchesError> {
+        ok!(self.verify_arg(arg));
+        Ok(self.args.get(arg))
+    }
+
+    #[inline]
+    fn try_get_arg_t<T: Any + Send + Sync + 'static>(
+        &self,
+        arg: &str,
+    ) -> Result<Option<&MatchedArg>, MatchesError> {
+        let arg = match ok!(self.try_get_arg(arg)) {
+            Some(arg) => arg,
+            None => {
+                return Ok(None);
+            }
+        };
+        ok!(self.verify_arg_t::<T>(arg));
+        Ok(Some(arg))
+    }
+
+    #[inline]
+    fn try_remove_arg_t<T: Any + Send + Sync + 'static>(
+        &mut self,
+        arg: &str,
+    ) -> Result<Option<MatchedArg>, MatchesError> {
+        ok!(self.verify_arg(arg));
+        let (id, matched) = match self.args.remove_entry(arg) {
+            Some((id, matched)) => (id, matched),
+            None => {
+                return Ok(None);
+            }
+        };
+
+        let expected = AnyValueId::of::<T>();
+        let actual = matched.infer_type_id(expected);
+        if actual == expected {
+            Ok(Some(matched))
+        } else {
+            self.args.insert(id, matched);
+            Err(MatchesError::Downcast { actual, expected })
+        }
+    }
+
+    fn verify_arg_t<T: Any + Send + Sync + 'static>(
+        &self,
+        arg: &MatchedArg,
+    ) -> Result<(), MatchesError> {
+        let expected = AnyValueId::of::<T>();
+        let actual = arg.infer_type_id(expected);
+        if expected == actual {
+            Ok(())
+        } else {
+            Err(MatchesError::Downcast { actual, expected })
+        }
+    }
+
+    #[inline]
+    fn verify_arg(&self, _arg: &str) -> Result<(), MatchesError> {
+        #[cfg(debug_assertions)]
+        {
+            if _arg == Id::EXTERNAL || self.valid_args.iter().any(|s| *s == _arg) {
+            } else {
+                debug!(
+                    "`{:?}` is not an id of an argument or a group.\n\
+                     Make sure you're using the name of the argument itself \
+                     and not the name of short or long flags.",
+                    _arg
+                );
+                return Err(MatchesError::UnknownArgument {});
+            }
+        }
+        Ok(())
+    }
+
+    #[inline]
+    #[cfg_attr(debug_assertions, track_caller)]
+    fn get_arg<'s>(&'s self, arg: &str) -> Option<&'s MatchedArg> {
+        #[cfg(debug_assertions)]
+        {
+            if arg == Id::EXTERNAL || self.valid_args.iter().any(|s| *s == arg) {
+            } else {
+                panic!(
+                    "`{arg:?}` is not an id of an argument or a group.\n\
+                     Make sure you're using the name of the argument itself \
+                     and not the name of short or long flags."
+                );
+            }
+        }
+
+        self.args.get(arg)
+    }
+
+    #[inline]
+    #[cfg_attr(debug_assertions, track_caller)]
+    fn get_subcommand(&self, name: &str) -> Option<&SubCommand> {
+        #[cfg(debug_assertions)]
+        {
+            if name.is_empty() || self.valid_subcommands.iter().any(|s| *s == name) {
+            } else {
+                panic!("`{name}` is not a name of a subcommand.");
+            }
+        }
+
+        if let Some(ref sc) = self.subcommand {
+            if sc.name == name {
+                return Some(sc);
+            }
+        }
+
+        None
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) struct SubCommand {
+    pub(crate) name: String,
+    pub(crate) matches: ArgMatches,
+}
+
+/// Iterate over [`Arg`][crate::Arg] and [`ArgGroup`][crate::ArgGroup] [`Id`]s via [`ArgMatches::ids`].
+///
+/// # Examples
+///
+/// ```rust
+/// # use clap_builder as clap;
+/// # use clap::{Command, arg, value_parser};
+///
+/// let m = Command::new("myprog")
+///     .arg(arg!(--color <when>)
+///         .value_parser(["auto", "always", "never"]))
+///     .arg(arg!(--config <path>)
+///         .value_parser(value_parser!(std::path::PathBuf)))
+///     .get_matches_from(["myprog", "--config=config.toml", "--color=auto"]);
+/// assert_eq!(
+///     m.ids()
+///         .map(|id| id.as_str())
+///         .collect::<Vec<_>>(),
+///     ["config", "color"]
+/// );
+/// ```
+#[derive(Clone, Debug)]
+pub struct IdsRef<'a> {
+    iter: std::slice::Iter<'a, Id>,
+}
+
+impl<'a> Iterator for IdsRef<'a> {
+    type Item = &'a Id;
+
+    fn next(&mut self) -> Option<&'a Id> {
+        self.iter.next()
+    }
+    fn size_hint(&self) -> (usize, Option<usize>) {
+        self.iter.size_hint()
+    }
+}
+
+impl<'a> DoubleEndedIterator for IdsRef<'a> {
+    fn next_back(&mut self) -> Option<&'a Id> {
+        self.iter.next_back()
+    }
+}
+
+impl<'a> ExactSizeIterator for IdsRef<'a> {}
+
+/// Iterate over multiple values for an argument via [`ArgMatches::remove_many`].
+///
+/// # Examples
+///
+/// ```rust
+/// # use clap_builder as clap;
+/// # use clap::{Command, Arg, ArgAction};
+/// let mut m = Command::new("myapp")
+///     .arg(Arg::new("output")
+///         .short('o')
+///         .action(ArgAction::Append))
+///     .get_matches_from(vec!["myapp", "-o", "val1", "-o", "val2"]);
+///
+/// let mut values = m.remove_many::<String>("output")
+///     .unwrap();
+///
+/// assert_eq!(values.next(), Some(String::from("val1")));
+/// assert_eq!(values.next(), Some(String::from("val2")));
+/// assert_eq!(values.next(), None);
+/// ```
+#[derive(Clone, Debug)]
+pub struct Values<T> {
+    #[allow(clippy::type_complexity)]
+    iter: Map<Flatten<std::vec::IntoIter<Vec<AnyValue>>>, fn(AnyValue) -> T>,
+    len: usize,
+}
+
+impl<T> Iterator for Values<T> {
+    type Item = T;
+
+    fn next(&mut self) -> Option<Self::Item> {
+        if let Some(next) = self.iter.next() {
+            self.len -= 1;
+            Some(next)
+        } else {
+            None
+        }
+    }
+    fn size_hint(&self) -> (usize, Option<usize>) {
+        (self.len, Some(self.len))
+    }
+}
+
+impl<T> DoubleEndedIterator for Values<T> {
+    fn next_back(&mut self) -> Option<Self::Item> {
+        if let Some(next) = self.iter.next_back() {
+            self.len -= 1;
+            Some(next)
+        } else {
+            None
+        }
+    }
+}
+
+impl<T> ExactSizeIterator for Values<T> {}
+
+/// Creates an empty iterator.
+impl<T> Default for Values<T> {
+    fn default() -> Self {
+        let empty: Vec<Vec<AnyValue>> = Default::default();
+        Values {
+            iter: empty.into_iter().flatten().map(|_| unreachable!()),
+            len: 0,
+        }
+    }
+}
+
+/// Iterate over multiple values for an argument via [`ArgMatches::get_many`].
+///
+/// # Examples
+///
+/// ```rust
+/// # use clap_builder as clap;
+/// # use clap::{Command, Arg, ArgAction};
+/// let m = Command::new("myapp")
+///     .arg(Arg::new("output")
+///         .short('o')
+///         .action(ArgAction::Append))
+///     .get_matches_from(vec!["myapp", "-o", "val1", "-o", "val2"]);
+///
+/// let mut values = m.get_many::<String>("output")
+///     .unwrap()
+///     .map(|s| s.as_str());
+///
+/// assert_eq!(values.next(), Some("val1"));
+/// assert_eq!(values.next(), Some("val2"));
+/// assert_eq!(values.next(), None);
+/// ```
+#[derive(Clone, Debug)]
+pub struct ValuesRef<'a, T> {
+    #[allow(clippy::type_complexity)]
+    iter: Map<Flatten<Iter<'a, Vec<AnyValue>>>, fn(&AnyValue) -> &T>,
+    len: usize,
+}
+
+impl<'a, T: 'a> Iterator for ValuesRef<'a, T> {
+    type Item = &'a T;
+
+    fn next(&mut self) -> Option<Self::Item> {
+        if let Some(next) = self.iter.next() {
+            self.len -= 1;
+            Some(next)
+        } else {
+            None
+        }
+    }
+    fn size_hint(&self) -> (usize, Option<usize>) {
+        (self.len, Some(self.len))
+    }
+}
+
+impl<'a, T: 'a> DoubleEndedIterator for ValuesRef<'a, T> {
+    fn next_back(&mut self) -> Option<Self::Item> {
+        if let Some(next) = self.iter.next_back() {
+            self.len -= 1;
+            Some(next)
+        } else {
+            None
+        }
+    }
+}
+
+impl<'a, T: 'a> ExactSizeIterator for ValuesRef<'a, T> {}
+
+/// Creates an empty iterator.
+impl<'a, T: 'a> Default for ValuesRef<'a, T> {
+    fn default() -> Self {
+        static EMPTY: [Vec<AnyValue>; 0] = [];
+        ValuesRef {
+            iter: EMPTY[..].iter().flatten().map(|_| unreachable!()),
+            len: 0,
+        }
+    }
+}
+
+/// Iterate over raw argument values via [`ArgMatches::get_raw`].
+///
+/// # Examples
+///
+/// ```rust
+/// # #[cfg(unix)] {
+/// # use clap_builder as clap;
+/// # use clap::{Command, arg, value_parser};
+/// use std::ffi::OsString;
+/// use std::os::unix::ffi::{OsStrExt,OsStringExt};
+///
+/// let m = Command::new("utf8")
+///     .arg(arg!(<arg> "some arg")
+///         .value_parser(value_parser!(OsString)))
+///     .get_matches_from(vec![OsString::from("myprog"),
+///                             // "Hi {0xe9}!"
+///                             OsString::from_vec(vec![b'H', b'i', b' ', 0xe9, b'!'])]);
+/// assert_eq!(
+///     &*m.get_raw("arg")
+///         .unwrap()
+///         .next().unwrap()
+///         .as_bytes(),
+///     [b'H', b'i', b' ', 0xe9, b'!']
+/// );
+/// # }
+/// ```
+#[derive(Clone, Debug)]
+pub struct RawValues<'a> {
+    #[allow(clippy::type_complexity)]
+    iter: Map<Flatten<Iter<'a, Vec<OsString>>>, fn(&OsString) -> &OsStr>,
+    len: usize,
+}
+
+impl<'a> Iterator for RawValues<'a> {
+    type Item = &'a OsStr;
+
+    fn next(&mut self) -> Option<&'a OsStr> {
+        if let Some(next) = self.iter.next() {
+            self.len -= 1;
+            Some(next)
+        } else {
+            None
+        }
+    }
+    fn size_hint(&self) -> (usize, Option<usize>) {
+        (self.len, Some(self.len))
+    }
+}
+
+impl<'a> DoubleEndedIterator for RawValues<'a> {
+    fn next_back(&mut self) -> Option<&'a OsStr> {
+        if let Some(next) = self.iter.next_back() {
+            self.len -= 1;
+            Some(next)
+        } else {
+            None
+        }
+    }
+}
+
+impl<'a> ExactSizeIterator for RawValues<'a> {}
+
+/// Creates an empty iterator.
+impl Default for RawValues<'_> {
+    fn default() -> Self {
+        static EMPTY: [Vec<OsString>; 0] = [];
+        RawValues {
+            iter: EMPTY[..].iter().flatten().map(|_| unreachable!()),
+            len: 0,
+        }
+    }
+}
+
+// The following were taken and adapted from vec_map source
+// repo: https://github.com/contain-rs/vec-map
+// commit: be5e1fa3c26e351761b33010ddbdaf5f05dbcc33
+// license: MIT - Copyright (c) 2015 The Rust Project Developers
+
+#[derive(Clone, Debug)]
+#[deprecated(since = "4.1.0", note = "Use Occurrences instead")]
+pub struct GroupedValues<'a> {
+    #[allow(clippy::type_complexity)]
+    iter: Map<Iter<'a, Vec<AnyValue>>, fn(&Vec<AnyValue>) -> Vec<&str>>,
+    len: usize,
+}
+
+#[allow(deprecated)]
+impl<'a> Iterator for GroupedValues<'a> {
+    type Item = Vec<&'a str>;
+
+    fn next(&mut self) -> Option<Self::Item> {
+        if let Some(next) = self.iter.next() {
+            self.len -= 1;
+            Some(next)
+        } else {
+            None
+        }
+    }
+    fn size_hint(&self) -> (usize, Option<usize>) {
+        (self.len, Some(self.len))
+    }
+}
+
+#[allow(deprecated)]
+impl<'a> DoubleEndedIterator for GroupedValues<'a> {
+    fn next_back(&mut self) -> Option<Self::Item> {
+        if let Some(next) = self.iter.next_back() {
+            self.len -= 1;
+            Some(next)
+        } else {
+            None
+        }
+    }
+}
+
+#[allow(deprecated)]
+impl<'a> ExactSizeIterator for GroupedValues<'a> {}
+
+/// Creates an empty iterator. Used for `unwrap_or_default()`.
+#[allow(deprecated)]
+impl<'a> Default for GroupedValues<'a> {
+    fn default() -> Self {
+        static EMPTY: [Vec<AnyValue>; 0] = [];
+        GroupedValues {
+            iter: EMPTY[..].iter().map(|_| unreachable!()),
+            len: 0,
+        }
+    }
+}
+
+#[derive(Clone, Debug)]
+pub struct Occurrences<T> {
+    #[allow(clippy::type_complexity)]
+    iter: Map<std::vec::IntoIter<Vec<AnyValue>>, fn(Vec<AnyValue>) -> OccurrenceValues<T>>,
+}
+
+impl<T> Iterator for Occurrences<T> {
+    type Item = OccurrenceValues<T>;
+
+    fn next(&mut self) -> Option<Self::Item> {
+        self.iter.next()
+    }
+
+    fn size_hint(&self) -> (usize, Option<usize>) {
+        self.iter.size_hint()
+    }
+}
+
+impl<T> DoubleEndedIterator for Occurrences<T> {
+    fn next_back(&mut self) -> Option<Self::Item> {
+        self.iter.next_back()
+    }
+}
+
+impl<T> ExactSizeIterator for Occurrences<T> {}
+
+impl<T> Default for Occurrences<T> {
+    fn default() -> Self {
+        let empty: Vec<Vec<AnyValue>> = Default::default();
+        Occurrences {
+            iter: empty.into_iter().map(|_| unreachable!()),
+        }
+    }
+}
+
+#[derive(Clone, Debug)]
+pub struct OccurrenceValues<T> {
+    #[allow(clippy::type_complexity)]
+    iter: Map<std::vec::IntoIter<AnyValue>, fn(AnyValue) -> T>,
+}
+
+impl<T> Iterator for OccurrenceValues<T> {
+    type Item = T;
+
+    fn next(&mut self) -> Option<Self::Item> {
+        self.iter.next()
+    }
+
+    fn size_hint(&self) -> (usize, Option<usize>) {
+        self.iter.size_hint()
+    }
+}
+
+impl<T> DoubleEndedIterator for OccurrenceValues<T> {
+    fn next_back(&mut self) -> Option<Self::Item> {
+        self.iter.next_back()
+    }
+}
+
+impl<T> ExactSizeIterator for OccurrenceValues<T> {}
+
+#[derive(Clone, Debug)]
+pub struct OccurrencesRef<'a, T> {
+    #[allow(clippy::type_complexity)]
+    iter: Map<Iter<'a, Vec<AnyValue>>, fn(&Vec<AnyValue>) -> OccurrenceValuesRef<'_, T>>,
+}
+
+impl<'a, T> Iterator for OccurrencesRef<'a, T>
+where
+    Self: 'a,
+{
+    type Item = OccurrenceValuesRef<'a, T>;
+
+    fn next(&mut self) -> Option<Self::Item> {
+        self.iter.next()
+    }
+
+    fn size_hint(&self) -> (usize, Option<usize>) {
+        self.iter.size_hint()
+    }
+}
+
+impl<'a, T> DoubleEndedIterator for OccurrencesRef<'a, T>
+where
+    Self: 'a,
+{
+    fn next_back(&mut self) -> Option<Self::Item> {
+        self.iter.next_back()
+    }
+}
+
+impl<'a, T> ExactSizeIterator for OccurrencesRef<'a, T> where Self: 'a {}
+impl<'a, T> Default for OccurrencesRef<'a, T> {
+    fn default() -> Self {
+        static EMPTY: [Vec<AnyValue>; 0] = [];
+        OccurrencesRef {
+            iter: EMPTY[..].iter().map(|_| unreachable!()),
+        }
+    }
+}
+
+#[derive(Clone, Debug)]
+pub struct OccurrenceValuesRef<'a, T> {
+    #[allow(clippy::type_complexity)]
+    iter: Map<Iter<'a, AnyValue>, fn(&AnyValue) -> &T>,
+}
+
+impl<'a, T> Iterator for OccurrenceValuesRef<'a, T>
+where
+    Self: 'a,
+{
+    type Item = &'a T;
+
+    fn next(&mut self) -> Option<Self::Item> {
+        self.iter.next()
+    }
+
+    fn size_hint(&self) -> (usize, Option<usize>) {
+        self.iter.size_hint()
+    }
+}
+
+impl<'a, T> DoubleEndedIterator for OccurrenceValuesRef<'a, T>
+where
+    Self: 'a,
+{
+    fn next_back(&mut self) -> Option<Self::Item> {
+        self.iter.next_back()
+    }
+}
+
+impl<'a, T> ExactSizeIterator for OccurrenceValuesRef<'a, T> where Self: 'a {}
+
+#[derive(Clone, Debug)]
+pub struct RawOccurrences<'a> {
+    #[allow(clippy::type_complexity)]
+    iter: Map<Iter<'a, Vec<OsString>>, fn(&Vec<OsString>) -> RawOccurrenceValues<'_>>,
+}
+
+impl<'a> Iterator for RawOccurrences<'a> {
+    type Item = RawOccurrenceValues<'a>;
+
+    fn next(&mut self) -> Option<Self::Item> {
+        self.iter.next()
+    }
+
+    fn size_hint(&self) -> (usize, Option<usize>) {
+        self.iter.size_hint()
+    }
+}
+
+impl<'a> DoubleEndedIterator for RawOccurrences<'a> {
+    fn next_back(&mut self) -> Option<Self::Item> {
+        self.iter.next_back()
+    }
+}
+
+impl<'a> ExactSizeIterator for RawOccurrences<'a> {}
+
+impl<'a> Default for RawOccurrences<'a> {
+    fn default() -> Self {
+        static EMPTY: [Vec<OsString>; 0] = [];
+        RawOccurrences {
+            iter: EMPTY[..].iter().map(|_| unreachable!()),
+        }
+    }
+}
+
+#[derive(Clone, Debug)]
+pub struct RawOccurrenceValues<'a> {
+    #[allow(clippy::type_complexity)]
+    iter: Map<Iter<'a, OsString>, fn(&OsString) -> &OsStr>,
+}
+
+impl<'a> Iterator for RawOccurrenceValues<'a>
+where
+    Self: 'a,
+{
+    type Item = &'a OsStr;
+
+    fn next(&mut self) -> Option<Self::Item> {
+        self.iter.next()
+    }
+
+    fn size_hint(&self) -> (usize, Option<usize>) {
+        self.iter.size_hint()
+    }
+}
+
+impl<'a> DoubleEndedIterator for RawOccurrenceValues<'a>
+where
+    Self: 'a,
+{
+    fn next_back(&mut self) -> Option<Self::Item> {
+        self.iter.next_back()
+    }
+}
+
+impl<'a> ExactSizeIterator for RawOccurrenceValues<'a> {}
+
+/// Iterate over indices for where an argument appeared when parsing, via [`ArgMatches::indices_of`]
+///
+/// # Examples
+///
+/// ```rust
+/// # use clap_builder as clap;
+/// # use clap::{Command, Arg, ArgAction};
+/// let m = Command::new("myapp")
+///     .arg(Arg::new("output")
+///         .short('o')
+///         .num_args(1..)
+///         .action(ArgAction::Set))
+///     .get_matches_from(vec!["myapp", "-o", "val1", "val2"]);
+///
+/// let mut indices = m.indices_of("output").unwrap();
+///
+/// assert_eq!(indices.next(), Some(2));
+/// assert_eq!(indices.next(), Some(3));
+/// assert_eq!(indices.next(), None);
+/// ```
+/// [`ArgMatches::indices_of`]: ArgMatches::indices_of()
+#[derive(Clone, Debug)]
+pub struct Indices<'a> {
+    iter: Cloned<Iter<'a, usize>>,
+    len: usize,
+}
+
+impl<'a> Iterator for Indices<'a> {
+    type Item = usize;
+
+    fn next(&mut self) -> Option<usize> {
+        if let Some(next) = self.iter.next() {
+            self.len -= 1;
+            Some(next)
+        } else {
+            None
+        }
+    }
+    fn size_hint(&self) -> (usize, Option<usize>) {
+        (self.len, Some(self.len))
+    }
+}
+
+impl<'a> DoubleEndedIterator for Indices<'a> {
+    fn next_back(&mut self) -> Option<usize> {
+        if let Some(next) = self.iter.next_back() {
+            self.len -= 1;
+            Some(next)
+        } else {
+            None
+        }
+    }
+}
+
+impl<'a> ExactSizeIterator for Indices<'a> {}
+
+/// Creates an empty iterator.
+impl<'a> Default for Indices<'a> {
+    fn default() -> Self {
+        static EMPTY: [usize; 0] = [];
+        // This is never called because the iterator is empty:
+        Indices {
+            iter: EMPTY[..].iter().cloned(),
+            len: 0,
+        }
+    }
+}
+
+#[track_caller]
+fn unwrap_downcast_ref<T: Any + Clone + Send + Sync + 'static>(value: &AnyValue) -> &T {
+    value.downcast_ref().expect(INTERNAL_ERROR_MSG)
+}
+
+#[track_caller]
+fn unwrap_downcast_into<T: Any + Clone + Send + Sync + 'static>(value: AnyValue) -> T {
+    value.downcast_into().expect(INTERNAL_ERROR_MSG)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    use crate::ArgAction;
+
+    #[test]
+    fn check_auto_traits() {
+        static_assertions::assert_impl_all!(ArgMatches: Send, Sync, Unpin);
+    }
+
+    #[test]
+    fn test_default_raw_values() {
+        let mut values: RawValues = Default::default();
+        assert_eq!(values.next(), None);
+    }
+
+    #[test]
+    fn test_default_indices() {
+        let mut indices: Indices = Indices::default();
+        assert_eq!(indices.next(), None);
+    }
+
+    #[test]
+    fn test_default_indices_with_shorter_lifetime() {
+        let matches = ArgMatches::default();
+        let mut indices = matches.indices_of("").unwrap_or_default();
+        assert_eq!(indices.next(), None);
+    }
+
+    #[test]
+    fn values_exact_size() {
+        let l = crate::Command::new("test")
+            .arg(
+                crate::Arg::new("POTATO")
+                    .action(ArgAction::Set)
+                    .num_args(1..)
+                    .required(true),
+            )
+            .try_get_matches_from(["test", "one"])
+            .unwrap()
+            .get_many::<String>("POTATO")
+            .expect("present")
+            .count();
+        assert_eq!(l, 1);
+    }
+
+    #[test]
+    fn os_values_exact_size() {
+        let l = crate::Command::new("test")
+            .arg(
+                crate::Arg::new("POTATO")
+                    .action(ArgAction::Set)
+                    .num_args(1..)
+                    .value_parser(crate::builder::ValueParser::os_string())
+                    .required(true),
+            )
+            .try_get_matches_from(["test", "one"])
+            .unwrap()
+            .get_many::<std::ffi::OsString>("POTATO")
+            .expect("present")
+            .count();
+        assert_eq!(l, 1);
+    }
+
+    #[test]
+    fn indices_exact_size() {
+        let l = crate::Command::new("test")
+            .arg(
+                crate::Arg::new("POTATO")
+                    .action(ArgAction::Set)
+                    .num_args(1..)
+                    .required(true),
+            )
+            .try_get_matches_from(["test", "one"])
+            .unwrap()
+            .indices_of("POTATO")
+            .expect("present")
+            .len();
+        assert_eq!(l, 1);
+    }
+
+    #[test]
+    fn rev_iter() {
+        let mut matches = crate::Command::new("myprog")
+            .arg(crate::Arg::new("a").short('a').action(ArgAction::Append))
+            .arg(crate::Arg::new("b").short('b').action(ArgAction::Append))
+            .try_get_matches_from(vec!["myprog", "-a1", "-b1", "-b3"])
+            .unwrap();
+
+        let a_index = matches
+            .indices_of("a")
+            .expect("missing aopt indices")
+            .collect::<Vec<_>>();
+        dbg!(&a_index);
+        let a_value = matches
+            .remove_many::<String>("a")
+            .expect("missing aopt values");
+        dbg!(&a_value);
+        let a = a_index.into_iter().zip(a_value).rev().collect::<Vec<_>>();
+        dbg!(a);
+
+        let b_index = matches
+            .indices_of("b")
+            .expect("missing aopt indices")
+            .collect::<Vec<_>>();
+        dbg!(&b_index);
+        let b_value = matches
+            .remove_many::<String>("b")
+            .expect("missing aopt values");
+        dbg!(&b_value);
+        let b = b_index.into_iter().zip(b_value).rev().collect::<Vec<_>>();
+        dbg!(b);
+    }
+}
diff --git a/vendor/clap_builder/src/parser/matches/matched_arg.rs b/vendor/clap_builder/src/parser/matches/matched_arg.rs
new file mode 100644
index 0000000..24df8b1
--- /dev/null
+++ b/vendor/clap_builder/src/parser/matches/matched_arg.rs
@@ -0,0 +1,225 @@
+// Std
+use std::{
+    ffi::{OsStr, OsString},
+    iter::{Cloned, Flatten},
+    slice::Iter,
+};
+
+use crate::builder::ArgPredicate;
+use crate::parser::ValueSource;
+use crate::util::eq_ignore_case;
+use crate::util::AnyValue;
+use crate::util::AnyValueId;
+use crate::INTERNAL_ERROR_MSG;
+
+#[derive(Debug, Clone)]
+pub(crate) struct MatchedArg {
+    source: Option<ValueSource>,
+    indices: Vec<usize>,
+    type_id: Option<AnyValueId>,
+    vals: Vec<Vec<AnyValue>>,
+    raw_vals: Vec<Vec<OsString>>,
+    ignore_case: bool,
+}
+
+impl MatchedArg {
+    pub(crate) fn new_arg(arg: &crate::Arg) -> Self {
+        let ignore_case = arg.is_ignore_case_set();
+        Self {
+            source: None,
+            indices: Vec::new(),
+            type_id: Some(arg.get_value_parser().type_id()),
+            vals: Vec::new(),
+            raw_vals: Vec::new(),
+            ignore_case,
+        }
+    }
+
+    pub(crate) fn new_group() -> Self {
+        let ignore_case = false;
+        Self {
+            source: None,
+            indices: Vec::new(),
+            type_id: None,
+            vals: Vec::new(),
+            raw_vals: Vec::new(),
+            ignore_case,
+        }
+    }
+
+    pub(crate) fn new_external(cmd: &crate::Command) -> Self {
+        let ignore_case = false;
+        Self {
+            source: None,
+            indices: Vec::new(),
+            type_id: Some(
+                cmd.get_external_subcommand_value_parser()
+                    .expect(INTERNAL_ERROR_MSG)
+                    .type_id(),
+            ),
+            vals: Vec::new(),
+            raw_vals: Vec::new(),
+            ignore_case,
+        }
+    }
+
+    pub(crate) fn indices(&self) -> Cloned<Iter<'_, usize>> {
+        self.indices.iter().cloned()
+    }
+
+    pub(crate) fn get_index(&self, index: usize) -> Option<usize> {
+        self.indices.get(index).cloned()
+    }
+
+    pub(crate) fn push_index(&mut self, index: usize) {
+        self.indices.push(index)
+    }
+
+    pub(crate) fn vals(&self) -> Iter<Vec<AnyValue>> {
+        self.vals.iter()
+    }
+
+    pub(crate) fn into_vals(self) -> Vec<Vec<AnyValue>> {
+        self.vals
+    }
+
+    pub(crate) fn vals_flatten(&self) -> Flatten<Iter<Vec<AnyValue>>> {
+        self.vals.iter().flatten()
+    }
+
+    pub(crate) fn into_vals_flatten(self) -> Flatten<std::vec::IntoIter<Vec<AnyValue>>> {
+        self.vals.into_iter().flatten()
+    }
+
+    pub(crate) fn raw_vals(&self) -> Iter<Vec<OsString>> {
+        self.raw_vals.iter()
+    }
+
+    pub(crate) fn raw_vals_flatten(&self) -> Flatten<Iter<Vec<OsString>>> {
+        self.raw_vals.iter().flatten()
+    }
+
+    pub(crate) fn first(&self) -> Option<&AnyValue> {
+        self.vals_flatten().next()
+    }
+
+    #[cfg(test)]
+    pub(crate) fn first_raw(&self) -> Option<&OsString> {
+        self.raw_vals_flatten().next()
+    }
+
+    pub(crate) fn new_val_group(&mut self) {
+        self.vals.push(vec![]);
+        self.raw_vals.push(vec![]);
+    }
+
+    pub(crate) fn append_val(&mut self, val: AnyValue, raw_val: OsString) {
+        // We assume there is always a group created before.
+        self.vals.last_mut().expect(INTERNAL_ERROR_MSG).push(val);
+        self.raw_vals
+            .last_mut()
+            .expect(INTERNAL_ERROR_MSG)
+            .push(raw_val);
+    }
+
+    pub(crate) fn num_vals(&self) -> usize {
+        self.vals.iter().map(|v| v.len()).sum()
+    }
+
+    // Will be used later
+    #[allow(dead_code)]
+    pub(crate) fn num_vals_last_group(&self) -> usize {
+        self.vals.last().map(|x| x.len()).unwrap_or(0)
+    }
+
+    pub(crate) fn all_val_groups_empty(&self) -> bool {
+        self.vals.iter().flatten().count() == 0
+    }
+
+    pub(crate) fn check_explicit(&self, predicate: &ArgPredicate) -> bool {
+        if self.source.map(|s| !s.is_explicit()).unwrap_or(false) {
+            return false;
+        }
+
+        match predicate {
+            ArgPredicate::Equals(val) => self.raw_vals_flatten().any(|v| {
+                if self.ignore_case {
+                    // If `v` isn't utf8, it can't match `val`, so `OsStr::to_str` should be fine
+                    eq_ignore_case(&v.to_string_lossy(), &val.to_string_lossy())
+                } else {
+                    OsString::as_os_str(v) == OsStr::new(val)
+                }
+            }),
+            ArgPredicate::IsPresent => true,
+        }
+    }
+
+    pub(crate) fn source(&self) -> Option<ValueSource> {
+        self.source
+    }
+
+    pub(crate) fn set_source(&mut self, source: ValueSource) {
+        if let Some(existing) = self.source {
+            self.source = Some(existing.max(source));
+        } else {
+            self.source = Some(source)
+        }
+    }
+
+    pub(crate) fn type_id(&self) -> Option<AnyValueId> {
+        self.type_id
+    }
+
+    pub(crate) fn infer_type_id(&self, expected: AnyValueId) -> AnyValueId {
+        self.type_id()
+            .or_else(|| {
+                self.vals_flatten()
+                    .map(|v| v.type_id())
+                    .find(|actual| *actual != expected)
+            })
+            .unwrap_or(expected)
+    }
+}
+
+impl PartialEq for MatchedArg {
+    fn eq(&self, other: &MatchedArg) -> bool {
+        let MatchedArg {
+            source: self_source,
+            indices: self_indices,
+            type_id: self_type_id,
+            vals: _,
+            raw_vals: self_raw_vals,
+            ignore_case: self_ignore_case,
+        } = self;
+        let MatchedArg {
+            source: other_source,
+            indices: other_indices,
+            type_id: other_type_id,
+            vals: _,
+            raw_vals: other_raw_vals,
+            ignore_case: other_ignore_case,
+        } = other;
+        self_source == other_source
+            && self_indices == other_indices
+            && self_type_id == other_type_id
+            && self_raw_vals == other_raw_vals
+            && self_ignore_case == other_ignore_case
+    }
+}
+
+impl Eq for MatchedArg {}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_grouped_vals_first() {
+        let mut m = MatchedArg::new_group();
+        m.new_val_group();
+        m.new_val_group();
+        m.append_val(AnyValue::new(String::from("bbb")), "bbb".into());
+        m.append_val(AnyValue::new(String::from("ccc")), "ccc".into());
+        assert_eq!(m.first_raw(), Some(&OsString::from("bbb")));
+    }
+}
diff --git a/vendor/clap_builder/src/parser/matches/mod.rs b/vendor/clap_builder/src/parser/matches/mod.rs
new file mode 100644
index 0000000..eb86585
--- /dev/null
+++ b/vendor/clap_builder/src/parser/matches/mod.rs
@@ -0,0 +1,13 @@
+mod arg_matches;
+mod matched_arg;
+mod value_source;
+
+pub use arg_matches::IdsRef;
+pub use arg_matches::RawValues;
+pub use arg_matches::Values;
+pub use arg_matches::ValuesRef;
+pub use arg_matches::{ArgMatches, Indices};
+pub use value_source::ValueSource;
+
+pub(crate) use arg_matches::SubCommand;
+pub(crate) use matched_arg::MatchedArg;
diff --git a/vendor/clap_builder/src/parser/matches/value_source.rs b/vendor/clap_builder/src/parser/matches/value_source.rs
new file mode 100644
index 0000000..db45d9c
--- /dev/null
+++ b/vendor/clap_builder/src/parser/matches/value_source.rs
@@ -0,0 +1,17 @@
+/// Origin of the argument's value
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+#[non_exhaustive]
+pub enum ValueSource {
+    /// Value came [`Arg::default_value`][crate::Arg::default_value]
+    DefaultValue,
+    /// Value came [`Arg::env`][crate::Arg::env]
+    EnvVariable,
+    /// Value was passed in on the command-line
+    CommandLine,
+}
+
+impl ValueSource {
+    pub(crate) fn is_explicit(self) -> bool {
+        self != Self::DefaultValue
+    }
+}