feat(method): Add ClapRange and range-based value methods

migrate `number_of_value`'s internal representation

Fix clippy

simplify

fix clippy

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;
@@ -79,10 +79,11 @@ pub struct Arg<'help> {
     pub(crate) disp_ord: DisplayOrder,
     pub(crate) possible_vals: Vec<PossibleValue<'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>,
@@ -1207,7 +1208,10 @@ impl<'help> Arg<'help> {
     #[inline]
     #[must_use]
     pub fn number_of_values(mut self, qty: usize) -> Self {
-        self.num_vals = Some(qty);
+        let range = self.num_vals_range.get_or_insert_with(Default::default);
+        range.start = Some(qty);
+        range.end = Some(qty);
+        range.inclusive = true;
         self.takes_value(true).multiple_values(true)
     }
 
@@ -1271,7 +1275,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 +1344,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 num_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 num_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)
     }
 
@@ -4619,7 +4647,7 @@ impl<'help> Arg<'help> {
     /// Get the number of values for this argument.
     #[inline]
     pub fn get_num_vals(&self) -> Option<usize> {
-        self.num_vals
+        self.num_vals()
     }
 
     /// Get the delimiter between multiple values
@@ -5021,6 +5049,48 @@ 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 num_vals(&self) -> Option<usize> {
+        self.num_vals_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,8 +5107,12 @@ impl<'help> Arg<'help> {
         if val_names_len > 1 {
             self.settings.set(ArgSettings::MultipleValues);
 
-            if self.num_vals.is_none() {
-                self.num_vals = Some(val_names_len);
+            if self.num_vals_range.is_none() {
+                self.num_vals_range = Some(ClapRange {
+                    inclusive: true,
+                    start: Some(val_names_len),
+                    end: Some(val_names_len),
+                });
             }
         }
 
@@ -5147,7 +5221,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;
@@ -5199,9 +5273,6 @@ impl<'help> fmt::Debug for Arg<'help> {
             .field("disp_ord", &self.disp_ord)
             .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)"),
@@ -5259,7 +5330,7 @@ where
     .to_string();
     if !arg.val_names.is_empty() {
         // If have val_name.
-        match (arg.val_names.len(), arg.num_vals) {
+        match (arg.val_names.len(), arg.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 +5356,7 @@ where
                 }
             }
         }
-    } else if let Some(num_vals) = arg.num_vals {
+    } else if let Some(num_vals) = arg.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,7 @@ 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())
             })
             .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,21 +186,24 @@ 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();
+
+            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
+                    (num_total % num) != 0
                 } else {
-                    num != current_num
+                    num != num_total
                 };
-            } 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;
+            } else if o.has_val_num_range() {
+                debug!("ArgMatcher::needs_more_vals");
+                return o.need_more_vals(num_total, num_current);
             }
+            debug!(
+                "ArgMatcher::needs_more_vals: false, {}, {}",
+                num_total, num_current
+            );
             return o.is_multiple_values_set();
         }
         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.

src/parse/validator.rs

@@ -4,8 +4,8 @@ use crate::error::{Error, Result as ClapResult};
 use crate::output::fmt::Stream;
 use crate::output::Usage;
 use crate::parse::{ArgMatcher, MatchedArg, ParseState};
-use crate::util::ChildGraph;
 use crate::util::Id;
+use crate::util::{ChildGraph, Ord};
 use crate::{INTERNAL_ERROR_MSG, INVALID_UTF8};
 
 pub(crate) struct Validator<'help, 'cmd> {
@@ -33,7 +33,7 @@ impl<'help, 'cmd> Validator<'help, 'cmd> {
 
             let o = &self.cmd[&a];
             let should_err = if let Some(v) = matcher.args.get(&o.id) {
-                v.all_val_groups_empty() && !(o.min_vals.is_some() && o.min_vals.unwrap() == 0)
+                v.all_val_groups_empty() && !o.min_vals_zero()
             } else {
                 true
             };
@@ -385,7 +385,7 @@ impl<'help, 'cmd> Validator<'help, 'cmd> {
 
     fn validate_arg_num_vals(&self, a: &Arg, ma: &MatchedArg) -> ClapResult<()> {
         debug!("Validator::validate_arg_num_vals");
-        if let Some(num) = a.num_vals {
+        if let Some(num) = a.num_vals() {
             let total_num = ma.num_vals();
             debug!("Validator::validate_arg_num_vals: num_vals set...{}", num);
             let should_err = if a.is_multiple_occurrences_set() {
@@ -410,46 +410,44 @@ impl<'help, 'cmd> Validator<'help, 'cmd> {
                 ));
             }
         }
-        if let Some(num) = a.max_vals {
-            debug!("Validator::validate_arg_num_vals: max_vals set...{}", num);
-            if ma.num_vals() > num {
-                debug!("Validator::validate_arg_num_vals: Sending error TooManyValues");
-                return Err(Error::too_many_values(
-                    self.cmd,
-                    ma.vals_flatten()
-                        .last()
-                        .expect(INTERNAL_ERROR_MSG)
-                        .to_str()
-                        .expect(INVALID_UTF8)
-                        .to_string(),
-                    a.to_string(),
-                    Usage::new(self.cmd)
-                        .required(&self.required)
-                        .create_usage_with_title(&[]),
-                ));
+        let num_vals = ma.num_vals();
+        if let Some(range) = &a.num_vals_total_range {
+            if let Err(ord) = range.pend(num_vals) {
+                match ord {
+                    Ord::Lt(num) => {
+                        debug!("Validator::validate_arg_num_vals: Sending error TooFewValues");
+                        return Err(Error::too_few_values(
+                            self.cmd,
+                            a,
+                            num,
+                            ma.num_vals(),
+                            Usage::new(self.cmd)
+                                .required(&self.required)
+                                .create_usage_with_title(&[]),
+                        ));
+                    }
+                    Ord::Gt(_num) => {
+                        debug!("Validator::validate_arg_num_vals: Sending error TooManyValues");
+                        return Err(Error::too_many_values(
+                            self.cmd,
+                            ma.vals_flatten()
+                                .last()
+                                .expect(INTERNAL_ERROR_MSG)
+                                .to_str()
+                                .expect(INVALID_UTF8)
+                                .to_string(),
+                            a.to_string(),
+                            Usage::new(self.cmd)
+                                .required(&self.required)
+                                .create_usage_with_title(&[]),
+                        ));
+                    }
+                }
             }
         }
-        let min_vals_zero = if let Some(num) = a.min_vals {
-            debug!("Validator::validate_arg_num_vals: min_vals set: {}", num);
-            if ma.num_vals() < num && num != 0 {
-                debug!("Validator::validate_arg_num_vals: Sending error TooFewValues");
-                return Err(Error::too_few_values(
-                    self.cmd,
-                    a,
-                    num,
-                    ma.num_vals(),
-                    Usage::new(self.cmd)
-                        .required(&self.required)
-                        .create_usage_with_title(&[]),
-                ));
-            }
-            num == 0
-        } else {
-            false
-        };
         // Issue 665 (https://github.com/clap-rs/clap/issues/665)
         // Issue 1105 (https://github.com/clap-rs/clap/issues/1105)
-        if a.is_takes_value_set() && !min_vals_zero && ma.all_val_groups_empty() {
+        if a.is_takes_value_set() && !a.min_vals_zero() && ma.all_val_groups_empty() {
             return Err(Error::empty_value(
                 self.cmd,
                 &a.possible_vals