feat(method): Add range-based value methods

use range_num_vals(_total) test pass

Add tests

src/build/arg.rs

@@ -19,7 +19,7 @@ use yaml_rust::Yaml;
 // Internal
 use crate::build::usage_parser::UsageParser;
 use crate::build::ArgPredicate;
-use crate::util::{Id, Key};
+use crate::util::{ClapRange, Id, Key};
 use crate::PossibleValue;
 use crate::ValueHint;
 use crate::INTERNAL_ERROR_MSG;
@@ -81,8 +81,10 @@ pub struct Arg<'help> {
     pub(crate) val_names: Vec<&'help str>,
     pub(crate) num_vals: Option<usize>,
     pub(crate) max_occurs: Option<usize>,
-    pub(crate) max_vals: Option<usize>,
-    pub(crate) min_vals: Option<usize>,
+    /// Range of number of values per occurrence
+    pub(crate) num_vals_range: Option<ClapRange<usize>>,
+    /// Total number of values range
+    pub(crate) num_vals_total_range: Option<ClapRange<usize>>,
     pub(crate) validator: Option<Arc<Mutex<Validator<'help>>>>,
     pub(crate) validator_os: Option<Arc<Mutex<ValidatorOs<'help>>>>,
     pub(crate) val_delim: Option<char>,
@@ -1271,7 +1273,11 @@ impl<'help> Arg<'help> {
     #[inline]
     #[must_use]
     pub fn max_values(mut self, qty: usize) -> Self {
-        self.max_vals = Some(qty);
+        let range = self
+            .num_vals_total_range
+            .get_or_insert_with(Default::default);
+        range.end = Some(qty);
+        range.inclusive = true;
         self.takes_value(true).multiple_values(true)
     }
 
@@ -1336,7 +1342,27 @@ impl<'help> Arg<'help> {
     #[inline]
     #[must_use]
     pub fn min_values(mut self, qty: usize) -> Self {
-        self.min_vals = Some(qty);
+        self.num_vals_total_range
+            .get_or_insert_with(Default::default)
+            .start = Some(qty);
+        self.takes_value(true).multiple_values(true)
+    }
+
+    /// emm
+    pub fn takes_values<R>(mut self, range: R) -> Self
+    where
+        R: Into<ClapRange<usize>>,
+    {
+        self.num_vals_range = Some(range.into());
+        self.takes_value(true).multiple_values(true)
+    }
+
+    /// emm
+    pub fn takes_values_total<R>(mut self, range: R) -> Self
+    where
+        R: Into<ClapRange<usize>>,
+    {
+        self.num_vals_total_range = Some(range.into());
         self.takes_value(true).multiple_values(true)
     }
 
@@ -5021,6 +5047,54 @@ impl<'help> Arg<'help> {
 
 /// # Internally used only
 impl<'help> Arg<'help> {
+    pub(crate) fn has_val_num_range(&self) -> bool {
+        self.num_vals_range.is_some() || self.num_vals_total_range.is_some()
+    }
+
+    /// If has_val_num_range() == false, return false.
+    /// Or else should we accept more values.
+    pub(crate) fn need_more_vals(&self, total: usize, current: usize) -> bool {
+        if let Some(range) = &self.num_vals_total_range {
+            if !range.need_more(total) {
+                return false;
+            }
+        }
+        if let Some(range) = &self.num_vals_range {
+            if !range.need_more(current) {
+                return false;
+            }
+        }
+
+        self.has_val_num_range()
+    }
+
+    /// If has_val_num_range() == false, return false.
+    /// Or else is num_vals == 0 accepted ?
+    pub(crate) fn min_vals_zero(&self) -> bool {
+        if let Some(range) = &self.num_vals_total_range {
+            if !range.is_valid(0) {
+                return false;
+            }
+        }
+        if let Some(range) = &self.num_vals_range {
+            if !range.is_valid(0) {
+                return false;
+            }
+        }
+
+        self.has_val_num_range()
+    }
+
+    pub(crate) fn range_num_vals(&self) -> Option<usize> {
+        self.num_vals_range.as_ref().and_then(|x| x.num_vals())
+    }
+
+    pub(crate) fn range_num_vals_total(&self) -> Option<usize> {
+        self.num_vals_total_range
+            .as_ref()
+            .and_then(|x| x.num_vals())
+    }
+
     pub(crate) fn _build(&mut self) {
         if self.is_positional() {
             self.settings.set(ArgSettings::TakesValue);
@@ -5037,7 +5111,11 @@ impl<'help> Arg<'help> {
         if val_names_len > 1 {
             self.settings.set(ArgSettings::MultipleValues);
 
-            if self.num_vals.is_none() {
+            if self.num_vals.is_none()
+                && self.range_num_vals().is_none()
+                && self.range_num_vals_total().is_none()
+            {
+                // TODO(ldm0) Migrate this to `num_vals_range_total` in clap 4 since it's a breaking change.
                 self.num_vals = Some(val_names_len);
             }
         }
@@ -5147,7 +5225,7 @@ impl<'help> Display for Arg<'help> {
         }
         let mut need_closing_bracket = false;
         if !self.is_positional() && self.is_takes_value_set() {
-            let is_optional_val = self.min_vals == Some(0);
+            let is_optional_val = self.min_vals_zero();
             let sep = if self.is_require_equals_set() {
                 if is_optional_val {
                     need_closing_bracket = true;
@@ -5200,8 +5278,6 @@ impl<'help> fmt::Debug for Arg<'help> {
             .field("possible_vals", &self.possible_vals)
             .field("val_names", &self.val_names)
             .field("num_vals", &self.num_vals)
-            .field("max_vals", &self.max_vals)
-            .field("min_vals", &self.min_vals)
             .field(
                 "validator",
                 &self.validator.as_ref().map_or("None", |_| "Some(FnMut)"),
@@ -5257,9 +5333,15 @@ where
         ' '
     }
     .to_string();
+
+    let num_vals = arg
+        .num_vals
+        .or_else(|| arg.range_num_vals())
+        .or_else(|| arg.range_num_vals_total());
+
     if !arg.val_names.is_empty() {
         // If have val_name.
-        match (arg.val_names.len(), arg.num_vals) {
+        match (arg.val_names.len(), num_vals) {
             (1, Some(num_vals)) => {
                 // If single value name with multiple num_of_vals, display all
                 // the values with the single value name.
@@ -5285,7 +5367,7 @@ where
                 }
             }
         }
-    } else if let Some(num_vals) = arg.num_vals {
+    } else if let Some(num_vals) = num_vals {
         // If number_of_values is specified, display the value multiple times.
         let arg_name = format!("<{}>", arg.name);
         for n in 1..=num_vals {

src/build/debug_asserts.rs

@@ -493,7 +493,10 @@ fn _verify_positionals(cmd: &Command) -> bool {
             .get_positionals()
             .filter(|p| {
                 p.is_multiple_occurrences_set()
-                    || (p.is_multiple_values_set() && p.num_vals.is_none())
+                    || (p.is_multiple_values_set()
+                        && p.num_vals.is_none()
+                        && p.range_num_vals().is_none()
+                        && p.range_num_vals_total().is_none())
             })
             .count();
         let ok = count <= 1

src/output/help.rs

@@ -281,7 +281,7 @@ impl<'help, 'cmd, 'writer> Help<'help, 'cmd, 'writer> {
         debug!("Help::val: arg={}", arg.name);
         let mut need_closing_bracket = false;
         if arg.is_takes_value_set() && !arg.is_positional() {
-            let is_optional_val = arg.min_vals == Some(0);
+            let is_optional_val = arg.min_vals_zero();
             let sep = if arg.is_require_equals_set() {
                 if is_optional_val {
                     need_closing_bracket = true;

src/parse/arg_matcher.rs

@@ -186,22 +186,27 @@ impl ArgMatcher {
     pub(crate) fn needs_more_vals(&self, o: &Arg) -> bool {
         debug!("ArgMatcher::needs_more_vals: o={}", o.name);
         if let Some(ma) = self.get(&o.id) {
-            let current_num = ma.num_vals();
-            if let Some(num) = o.num_vals {
+            let num_total = ma.num_vals();
+            let num_current = ma.num_vals_last_group();
+            let needs_more_vals = if let Some(num) = o.num_vals {
                 debug!("ArgMatcher::needs_more_vals: num_vals...{}", num);
-                return if o.is_multiple_occurrences_set() {
-                    (current_num % num) != 0
+                if o.is_multiple_occurrences_set() {
+                    (num_total % num) != 0
                 } else {
-                    num != current_num
-                };
-            } else if let Some(num) = o.max_vals {
-                debug!("ArgMatcher::needs_more_vals: max_vals...{}", num);
-                return current_num < num;
-            } else if o.min_vals.is_some() {
-                debug!("ArgMatcher::needs_more_vals: min_vals...true");
-                return true;
-            }
-            return o.is_multiple_values_set();
+                    num != num_total
+                }
+            } else if o.has_val_num_range() {
+                debug!("ArgMatcher::has_val_num_range");
+                o.need_more_vals(num_total, num_current)
+            } else {
+                debug!("ArgMatcher::check is_multiple_values_set");
+                o.is_multiple_values_set()
+            };
+            debug!(
+                "ArgMatcher::needs_more_vals: {}, {}, {}",
+                needs_more_vals, num_total, num_current
+            );
+            return needs_more_vals;
         }
         true
     }

src/parse/matches/matched_arg.rs

@@ -81,8 +81,6 @@ impl MatchedArg {
         self.vals.iter().flatten().count()
     }
 
-    // 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)
     }

src/parse/parser.rs

@@ -1043,7 +1043,7 @@ impl<'help, 'cmd> Parser<'help, 'cmd> {
         debug!("Parser::parse_opt; Checking for val...");
         // require_equals is set, but no '=' is provided, try throwing error.
         if opt.is_require_equals_set() && !has_eq {
-            if opt.min_vals == Some(0) {
+            if opt.min_vals_zero() {
                 debug!("Requires equals, but min_vals == 0");
                 self.inc_occurrence_of_arg(matcher, opt);
                 // We assume this case is valid: require equals, but min_vals == 0.