feat: Stablize ArgMatches::get_occurrences

This let's you get an arguments values, grouped by the occurrence of the
argument.

Note: this does not stablize derive support.  That requires a blocking
change and can be enabled via `unstable-v5` flag.  See #4626 for an
exploration of how we can make this easier in the future.

Fixes #2924

Cargo.toml

@@ -69,7 +69,7 @@ default = [
   "suggestions",
 ]
 debug = ["clap_derive?/debug", "dep:backtrace"] # Enables debug messages
-unstable-doc = ["derive", "cargo", "wrap_help", "env", "unicode", "string", "unstable-replace", "unstable-grouped"] # for docs.rs
+unstable-doc = ["derive", "cargo", "wrap_help", "env", "unicode", "string", "unstable-replace"] # for docs.rs
 
 # Used in default
 std = [] # support for no_std in a backwards-compatible way

Makefile

@@ -15,8 +15,8 @@ MSRV?=1.64.0
 _FEATURES = minimal default wasm full debug release
 _FEATURES_minimal = --no-default-features --features "std"
 _FEATURES_default =
-_FEATURES_wasm = --no-default-features --features "std help usage error-context suggestions" --features "deprecated derive cargo env unicode string unstable-replace unstable-grouped"
-_FEATURES_full = --features "deprecated derive cargo env unicode string unstable-replace unstable-grouped wrap_help"
+_FEATURES_wasm = --no-default-features --features "std help usage error-context suggestions" --features "deprecated derive cargo env unicode string unstable-replace"
+_FEATURES_full = --features "deprecated derive cargo env unicode string unstable-replace wrap_help"
 _FEATURES_next = ${_FEATURES_full} --features unstable-v5
 _FEATURES_debug = ${_FEATURES_full} --features debug --features clap_complete/debug
 _FEATURES_release = ${_FEATURES_full} --release

src/_features.rs

@@ -26,5 +26,4 @@
 //! **Warning:** These may contain breaking changes between minor releases.
 //!
 //! * **unstable-replace**: Enable [`Command::replace`](https://github.com/clap-rs/clap/issues/2836)
-//! * **unstable-grouped**: Enable [`ArgMatches::grouped_values_of`](https://github.com/clap-rs/clap/issues/2924)
 //! * **unstable-v5**: Preview features which will be stable on the v5.0 release

src/parser/matches/arg_matches.rs

@@ -246,7 +246,6 @@ impl ArgMatches {
     /// assert_eq!(vals, [["a", "b"], ["c", "d"]]);
     /// ```
     #[cfg_attr(debug_assertions, track_caller)]
-    #[cfg(feature = "unstable-grouped")]
     pub fn get_occurrences<T: Any + Clone + Send + Sync + 'static>(
         &self,
         id: &str,
@@ -348,7 +347,6 @@ impl ArgMatches {
     /// [`OsStr`]: std::ffi::OsStr
     /// [values]: OsValues
     /// [`String`]: std::string::String
-    #[cfg(feature = "unstable-grouped")]
     #[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))
@@ -460,7 +458,6 @@ impl ArgMatches {
     /// let vals: Vec<Vec<String>> = m.remove_occurrences("x").unwrap().map(Iterator::collect).collect();
     /// assert_eq!(vals, [["a", "b"], ["c", "d"]]);
     /// ```
-    #[cfg(feature = "unstable-grouped")]
     #[cfg_attr(debug_assertions, track_caller)]
     pub fn remove_occurrences<T: Any + Clone + Send + Sync + 'static>(
         &mut self,
@@ -1110,7 +1107,6 @@ impl ArgMatches {
     }
 
     /// Non-panicking version of [`ArgMatches::get_occurrences`]
-    #[cfg(feature = "unstable-grouped")]
     pub fn try_get_occurrences<T: Any + Clone + Send + Sync + 'static>(
         &self,
         id: &str,
@@ -1143,7 +1139,6 @@ impl ArgMatches {
     }
 
     /// Non-panicking version of [`ArgMatches::get_raw_occurrences`]
-    #[cfg(feature = "unstable-grouped")]
     pub fn try_get_raw_occurrences(
         &self,
         id: &str,
@@ -1196,7 +1191,6 @@ impl ArgMatches {
     }
 
     /// Non-panicking version of [`ArgMatches::remove_occurrences`]
-    #[cfg(feature = "unstable-grouped")]
     pub fn try_remove_occurrences<T: Any + Clone + Send + Sync + 'static>(
         &mut self,
         id: &str,
@@ -1868,9 +1862,9 @@ impl<'a> Default for Indices<'a> {
     }
 }
 
-#[cfg(feature = "unstable-grouped")]
 #[cfg_attr(debug_assertions, track_caller)]
 #[inline]
+#[cfg(feature = "unstable-grouped")]
 fn unwrap_string(value: &AnyValue) -> &str {
     match value.downcast_ref::<String>() {
         Some(value) => value,

src/parser/matches/matched_arg.rs

@@ -75,12 +75,10 @@ impl MatchedArg {
         self.indices.push(index)
     }
 
-    #[cfg(feature = "unstable-grouped")]
     pub(crate) fn vals(&self) -> Iter<Vec<AnyValue>> {
         self.vals.iter()
     }
 
-    #[cfg(feature = "unstable-grouped")]
     pub(crate) fn into_vals(self) -> Vec<Vec<AnyValue>> {
         self.vals
     }
@@ -93,7 +91,6 @@ impl MatchedArg {
         self.vals.into_iter().flatten()
     }
 
-    #[cfg(feature = "unstable-grouped")]
     pub(crate) fn raw_vals(&self) -> Iter<Vec<OsString>> {
         self.raw_vals.iter()
     }

tests/builder/occurrences.rs

@@ -1,5 +1,3 @@
-#![cfg(feature = "unstable-grouped")]
-
 use clap::{Arg, ArgAction, ArgMatches, Command};
 
 fn occurrences_as_vec_vec<'a>(m: &'a ArgMatches, name: &str) -> Vec<Vec<&'a String>> {

tests/derive/occurrences.rs

@@ -1,4 +1,4 @@
-#![cfg(all(feature = "unstable-grouped", feature = "unstable-v5"))]
+#![cfg(feature = "unstable-v5")]
 use clap::Parser;
 
 #[test]

tests/examples.rs

@@ -27,8 +27,6 @@ fn example_tests() {
         "wrap_help",
         #[cfg(feature = "unstable-replace")]
         "unstable-replace",
-        #[cfg(feature = "unstable-grouped")]
-        "unstable-grouped",
     ]
     .join(" ");
     t.register_bins(trycmd::cargo::compile_examples(["--features", &features]).unwrap());

tests/ui.rs

@@ -27,8 +27,6 @@ fn ui_tests() {
         "wrap_help",
         #[cfg(feature = "unstable-replace")]
         "unstable-replace",
-        #[cfg(feature = "unstable-grouped")]
-        "unstable-grouped",
     ]
     .join(" ");
     t.register_bins(trycmd::cargo::compile_examples(["--features", &features]).unwrap());