fix!: num_args controls user args rather than parsed values

CHANGELOG.md

@@ -20,12 +20,14 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 - `arg!` now sets `ArgAction::SetTrue`, `ArgAction::Count`, `ArgAction::Set`, or `ArgAction::Append` as appropriate (#3795)
 - Default actions are now `Set` and `SetTrue`
 - Removed `PartialEq` and `Eq` from `Command`
-- `Arg::number_of_values` now applies per occurrence rather than the average across all occurrences
-- `number_of_values(0)` no longer implies `takes_value(true).multiple_values(true)`
-- `number_of_values(1)` no longer implies `multiple_values(true)`
-- Remove `Arg::min_values` (across all occurrences) with `Arg::number_of_values(N..)` (per occurrence)
-- Remove `Arg::max_values` (across all occurrences) with `Arg::number_of_values(1..=M)` (per occurrence)
-- Remove `Arg::multiple_values(true)` with `Arg::number_of_values(1..)` and `Arg::multiple_values(false)` with `Arg::number_of_values(0)`
+- Replace `Arg::number_of_values` (average across occurrences) with `Arg::num_args` (per occurrence, raw CLI args, not parsed values)
+  - `num_args(0)` no longer implies `takes_value(true).multiple_values(true)`
+  - `num_args(1)` no longer implies `multiple_values(true)`
+  - Does not check default values, only what the user explicitly passes in
+- Sometimes `Arg::default_missing_value` didn't require `num_args(0..=1)`, now it does
+- Replace `Arg::min_values` (across all occurrences) with `Arg::num_args(N..)` (per occurrence)
+- Replace `Arg::max_values` (across all occurrences) with `Arg::num_args(1..=M)` (per occurrence)
+- Replace `Arg::multiple_values(true)` with `Arg::num_args(1..)` and `Arg::multiple_values(false)` with `Arg::num_args(0)`
 - Remove `Arg::use_value_delimiter` in favor of `Arg::value_delimiter`
 - `ArgAction::SetTrue` and `ArgAction::SetFalse` now prioritize `Arg::default_missing_value` over their standard behavior
 - *(help)* Make `DeriveDisplayOrder` the default and removed the setting.  To sort help, set `next_display_order(None)` (#2808)
@@ -36,14 +38,14 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ### Features
 
-- `Arg::number_of_values` now accepts ranges, allowing setting both the minimum and maximum number of values per occurrence
+- `Arg::num_args` now accepts ranges, allowing setting both the minimum and maximum number of values per occurrence
 - *(help)* Show `PossibleValue::help` in long help (`--help`) (#3312)
 
 ### Fixes
 
 - Leading dashes in `Arg::long` are no longer allowed (#3691)
 - Verify `required` is not used with conditional required settings (#3660)
-- Disallow more `value_names` than `number_of_values` (#2695)
+- Disallow more `value_names` than `num_args` (#2695)
 - Replaced `cmd.allow_invalid_for_utf8_external_subcommands` with `cmd.external_subcommand_value_parser` (#3733)
 - Changed the default type of `allow_external_subcommands` from `String` to `OsString`
 - `Arg::default_missing_value` now applies per occurrence rather than if a value is missing across all occurrences

clap_bench/benches/03_complex.rs

@@ -31,8 +31,8 @@ macro_rules! create_app {
                 arg!(
                     --multvalsmo <s> "Tests multiple values, not mult occs"
                 ).required(false).value_names(&["one", "two"]),
-                arg!(--minvals2 <minvals> ... "Tests 2 min vals").number_of_values(2..).required(false),
-                arg!(--maxvals3 <maxvals> ... "Tests 3 max vals").number_of_values(1..=3).required(false),
+                arg!(--minvals2 <minvals> ... "Tests 2 min vals").num_args(2..).required(false),
+                arg!(--maxvals3 <maxvals> ... "Tests 3 max vals").num_args(1..=3).required(false),
             ])
             .subcommand(
                 Command::new("subcmd")
@@ -57,7 +57,7 @@ pub fn build_from_builder(c: &mut Criterion) {
                         .help("tests options")
                         .short('o')
                         .long("option")
-                        .number_of_values(1..)
+                        .num_args(1..)
                         .action(ArgAction::Append),
                 )
                 .arg(Arg::new("positional").help("tests positionals").index(1))
@@ -99,7 +99,7 @@ pub fn build_from_builder(c: &mut Criterion) {
                 )
                 .arg(
                     Arg::new("positional3")
-                        .number_of_values(1..)
+                        .num_args(1..)
                         .help("tests positionals with specific values")
                         .index(4)
                         .value_parser(POS3_VALS),
@@ -122,14 +122,14 @@ pub fn build_from_builder(c: &mut Criterion) {
                         .long("minvals2")
                         .action(ArgAction::Append)
                         .help("Tests 2 min vals")
-                        .number_of_values(2..),
+                        .num_args(2..),
                 )
                 .arg(
                     Arg::new("maxvals")
                         .long("maxvals3")
                         .action(ArgAction::Append)
                         .help("Tests 3 max vals")
-                        .number_of_values(1..=3),
+                        .num_args(1..=3),
                 )
                 .subcommand(
                     Command::new("subcmd")
@@ -140,7 +140,7 @@ pub fn build_from_builder(c: &mut Criterion) {
                             Arg::new("scoption")
                                 .short('o')
                                 .long("option")
-                                .number_of_values(1..)
+                                .num_args(1..)
                                 .action(ArgAction::Append)
                                 .help("tests options"),
                         )

clap_bench/benches/04_new_help.rs

@@ -118,7 +118,7 @@ fn app_example7<'c>() -> Command<'c> {
         .arg(
             Arg::new("input")
                 .help("the input file to use")
-                .number_of_values(1..)
+                .num_args(1..)
                 .action(ArgAction::Append)
                 .required(true)
                 .short('i')
@@ -135,7 +135,7 @@ fn app_example8<'c>() -> Command<'c> {
         .arg(
             Arg::new("input")
                 .help("the input file to use")
-                .number_of_values(1..)
+                .num_args(1..)
                 .action(ArgAction::Append)
                 .required(true)
                 .short('i')

clap_bench/benches/05_ripgrep.rs

@@ -323,7 +323,7 @@ where
             "type-list",
             "version",
         ]))
-        .arg(arg("path").number_of_values(1..))
+        .arg(arg("path").num_args(1..))
         .arg(
             flag("regexp")
                 .short('e')

clap_bench/benches/06_rustup.rs

@@ -236,7 +236,7 @@ fn build_cli() -> Command<'static> {
                 .after_help(RUN_HELP)
                 .trailing_var_arg(true)
                 .arg(Arg::new("toolchain").required(true))
-                .arg(Arg::new("command").required(true).number_of_values(1..)),
+                .arg(Arg::new("command").required(true).num_args(1..)),
         )
         .subcommand(
             Command::new("which")

clap_complete/examples/completion.rs

@@ -68,7 +68,7 @@ fn build_cli() -> Command<'static> {
         )
         .arg(
             Arg::new("command_with_args")
-                .number_of_values(1..)
+                .num_args(1..)
                 .value_hint(ValueHint::CommandWithArguments),
         )
         .arg(

clap_complete/src/shells/zsh.rs

@@ -462,7 +462,7 @@ fn write_opts_of(p: &Command, p_global: Option<&Command>) -> String {
             Some(val) => format!(":{}:{}", vn, val),
             None => format!(":{}: ", vn),
         };
-        let vc = match o.get_num_vals() {
+        let vc = match o.get_num_args() {
             Some(num_vals) => vc.repeat(num_vals.min_values()),
             None => vc,
         };

clap_complete/tests/common.rs

@@ -64,7 +64,7 @@ pub fn special_commands_command(name: &'static str) -> clap::Command<'static> {
                         .require_equals(true)
                         .help("the other case to test"),
                 )
-                .arg(clap::Arg::new("path").number_of_values(1..)),
+                .arg(clap::Arg::new("path").num_args(1..)),
         )
         .subcommand(clap::Command::new("some-cmd-with-hyphens").alias("hyphen"))
         .subcommand(clap::Command::new("some-hidden-cmd").hide(true))
@@ -220,7 +220,7 @@ pub fn value_hint_command(name: &'static str) -> clap::Command<'static> {
         .arg(
             clap::Arg::new("command_with_args")
                 .action(clap::ArgAction::Set)
-                .number_of_values(1..)
+                .num_args(1..)
                 .value_hint(clap::ValueHint::CommandWithArguments),
         )
         .arg(

clap_complete_fig/tests/common.rs

@@ -64,7 +64,7 @@ pub fn special_commands_command(name: &'static str) -> clap::Command<'static> {
                         .require_equals(true)
                         .help("the other case to test"),
                 )
-                .arg(clap::Arg::new("path").number_of_values(1..)),
+                .arg(clap::Arg::new("path").num_args(1..)),
         )
         .subcommand(clap::Command::new("some-cmd-with-hyphens").alias("hyphen"))
         .subcommand(clap::Command::new("some-hidden-cmd").hide(true))
@@ -220,7 +220,7 @@ pub fn value_hint_command(name: &'static str) -> clap::Command<'static> {
         .arg(
             clap::Arg::new("command_with_args")
                 .action(clap::ArgAction::Set)
-                .number_of_values(1..)
+                .num_args(1..)
                 .value_hint(clap::ValueHint::CommandWithArguments),
         )
         .arg(

clap_derive/src/derives/args.rs

@@ -258,7 +258,7 @@ pub fn gen_augment(
 
                     Ty::OptionOption => quote_spanned! { ty.span()=>
                         .value_name(#value_name)
-                        .number_of_values(0..=1)
+                        .num_args(0..=1)
                         #value_parser
                         #action
                     },
@@ -267,7 +267,7 @@ pub fn gen_augment(
                         if attrs.is_positional() {
                             quote_spanned! { ty.span()=>
                                 .value_name(#value_name)
-                                .number_of_values(1..)  // action won't be sufficient for getting multiple
+                                .num_args(1..)  // action won't be sufficient for getting multiple
                                 #value_parser
                                 #action
                             }
@@ -284,7 +284,7 @@ pub fn gen_augment(
                         if attrs.is_positional() {
                             quote_spanned! { ty.span()=>
                                 .value_name(#value_name)
-                                .number_of_values(1..)  // action won't be sufficient for getting multiple
+                                .num_args(1..)  // action won't be sufficient for getting multiple
                                 #value_parser
                                 #action
                             }

clap_mangen/tests/common.rs

@@ -216,7 +216,7 @@ pub fn value_hint_command(name: &'static str) -> clap::Command<'static> {
         .arg(
             clap::Arg::new("command_with_args")
                 .action(clap::ArgAction::Set)
-                .number_of_values(1..)
+                .num_args(1..)
                 .value_hint(clap::ValueHint::CommandWithArguments),
         )
         .arg(

examples/escaped-positional.rs

@@ -11,7 +11,7 @@ fn main() {
         .arg(
             // Indicates that `slop` is only accessible after `--`.
             arg!(slop: [SLOP])
-                .number_of_values(1..)
+                .num_args(1..)
                 .last(true)
                 .value_parser(value_parser!(String)),
         )

examples/pacman.rs

@@ -22,7 +22,7 @@ fn main() {
                         .help("search locally installed packages for matching strings")
                         .conflicts_with("info")
                         .action(ArgAction::Set)
-                        .number_of_values(1..),
+                        .num_args(1..),
                 )
                 .arg(
                     Arg::new("info")
@@ -31,7 +31,7 @@ fn main() {
                         .conflicts_with("search")
                         .help("view package information")
                         .action(ArgAction::Set)
-                        .number_of_values(1..),
+                        .num_args(1..),
                 ),
         )
         // Sync subcommand
@@ -48,7 +48,7 @@ fn main() {
                         .long("search")
                         .conflicts_with("info")
                         .action(ArgAction::Set)
-                        .number_of_values(1..)
+                        .num_args(1..)
                         .help("search remote repositories for matching strings"),
                 )
                 .arg(
@@ -64,7 +64,7 @@ fn main() {
                         .help("packages")
                         .required_unless_present("search")
                         .action(ArgAction::Set)
-                        .number_of_values(1..),
+                        .num_args(1..),
                 ),
         )
         .get_matches();