fix!: Replace multiple_values with number_of_values

This reduces ambiguity in how the different "multiple" parts of the API interact and lowrs the amount of API surface area users have to dig through to use clap. For now, this is only a matter of cleaning up the public API. Cleaning up the implementation is the next step.
clap-rs · Aug 1, 2022 · 470531b · 470531b
1 parent e2a6bbf
commit 470531b
Show file tree

Hide file tree

Showing 39 changed files with 170 additions and 354 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -25,6 +25,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 - `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)`
 - `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)
 - *(help)* Subcommand display order respects `Command::next_display_order` instead of `DeriveDisplayOrder` and using its own initial display order value (#2808)

diff --git a/clap_bench/benches/03_complex.rs b/clap_bench/benches/03_complex.rs
@@ -30,9 +30,9 @@ macro_rules! create_app {
                 arg!(--multvals <s> "Tests multiple values not mult occs").required(false).value_names(&["one", "two"]),
                 arg!(
                     --multvalsmo <s> "Tests multiple values, not mult occs"
-                ).multiple_values(true).required(false).value_names(&["one", "two"]),
-                arg!(--minvals2 <minvals> ... "Tests 2 min vals").number_of_values(2..).multiple_values(true).required(false),
-                arg!(--maxvals3 <maxvals> ... "Tests 3 max vals").number_of_values(1..=3).multiple_values(true).required(false),
+                ).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),
             ])
             .subcommand(
                 Command::new("subcmd")
@@ -57,7 +57,7 @@ pub fn build_from_builder(c: &mut Criterion) {
                         .help("tests options")
                         .short('o')
                         .long("option")
-                        .multiple_values(true)
+                        .number_of_values(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")
-                        .multiple_values(true)
+                        .number_of_values(1..)
                         .help("tests positionals with specific values")
                         .index(4)
                         .value_parser(POS3_VALS),
@@ -113,23 +113,20 @@ pub fn build_from_builder(c: &mut Criterion) {
                 .arg(
                     Arg::new("multvalsmo")
                         .long("multvalsmo")
-                        .multiple_values(true)
                         .action(ArgAction::Append)
                         .help("Tests multiple values, not mult occs")
                         .value_names(&["one", "two"]),
                 )
                 .arg(
                     Arg::new("minvals")
                         .long("minvals2")
-                        .multiple_values(true)
                         .action(ArgAction::Append)
                         .help("Tests 2 min vals")
                         .number_of_values(2..),
                 )
                 .arg(
                     Arg::new("maxvals")
                         .long("maxvals3")
-                        .multiple_values(true)
                         .action(ArgAction::Append)
                         .help("Tests 3 max vals")
                         .number_of_values(1..=3),
@@ -143,7 +140,7 @@ pub fn build_from_builder(c: &mut Criterion) {
                             Arg::new("scoption")
                                 .short('o')
                                 .long("option")
-                                .multiple_values(true)
+                                .number_of_values(1..)
                                 .action(ArgAction::Append)
                                 .help("tests options"),
                         )

diff --git a/clap_bench/benches/04_new_help.rs b/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")
-                .multiple_values(true)
+                .number_of_values(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")
-                .multiple_values(true)
+                .number_of_values(1..)
                 .action(ArgAction::Append)
                 .required(true)
                 .short('i')

diff --git a/clap_bench/benches/05_ripgrep.rs b/clap_bench/benches/05_ripgrep.rs
@@ -323,7 +323,7 @@ where
             "type-list",
             "version",
         ]))
-        .arg(arg("path").multiple_values(true))
+        .arg(arg("path").number_of_values(1..))
         .arg(
             flag("regexp")
                 .short('e')

diff --git a/clap_bench/benches/06_rustup.rs b/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).multiple_values(true)),
+                .arg(Arg::new("command").required(true).number_of_values(1..)),
         )
         .subcommand(
             Command::new("which")

diff --git a/clap_complete/examples/completion.rs b/clap_complete/examples/completion.rs
@@ -68,7 +68,7 @@ fn build_cli() -> Command<'static> {
         )
         .arg(
             Arg::new("command_with_args")
-                .multiple_values(true)
+                .number_of_values(1..)
                 .value_hint(ValueHint::CommandWithArguments),
         )
         .arg(

diff --git a/clap_complete/tests/common.rs b/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").multiple_values(true)),
+                .arg(clap::Arg::new("path").number_of_values(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)
-                .multiple_values(true)
+                .number_of_values(1..)
                 .value_hint(clap::ValueHint::CommandWithArguments),
         )
         .arg(

diff --git a/clap_complete/tests/snapshots/basic.bash b/clap_complete/tests/snapshots/basic.bash
@@ -39,7 +39,7 @@ _my-app() {
             return 0
             ;;
         my__app__help)
-            opts="-c <SUBCOMMAND>..."
+            opts="-c [<SUBCOMMAND>...]"
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 2 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0

diff --git a/clap_complete/tests/snapshots/feature_sample.bash b/clap_complete/tests/snapshots/feature_sample.bash
@@ -39,7 +39,7 @@ _my-app() {
             return 0
             ;;
         my__app__help)
-            opts="<SUBCOMMAND>..."
+            opts="[<SUBCOMMAND>...]"
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 2 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0

diff --git a/clap_complete/tests/snapshots/quoting.bash b/clap_complete/tests/snapshots/quoting.bash
@@ -138,7 +138,7 @@ _my-app() {
             return 0
             ;;
         my__app__help)
-            opts="<SUBCOMMAND>..."
+            opts="[<SUBCOMMAND>...]"
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 2 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0

diff --git a/clap_complete/tests/snapshots/special_commands.bash b/clap_complete/tests/snapshots/special_commands.bash
@@ -48,7 +48,7 @@ _my-app() {
             return 0
             ;;
         my__app__help)
-            opts="<SUBCOMMAND>..."
+            opts="[<SUBCOMMAND>...]"
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 2 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0

diff --git a/clap_complete/tests/snapshots/sub_subcommands.bash b/clap_complete/tests/snapshots/sub_subcommands.bash
@@ -45,7 +45,7 @@ _my-app() {
             return 0
             ;;
         my__app__help)
-            opts="<SUBCOMMAND>..."
+            opts="[<SUBCOMMAND>...]"
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 2 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0
@@ -73,7 +73,7 @@ _my-app() {
             return 0
             ;;
         my__app__some_cmd__help)
-            opts="<SUBCOMMAND>..."
+            opts="[<SUBCOMMAND>...]"
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 3 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0

diff --git a/clap_complete_fig/tests/common.rs b/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").multiple_values(true)),
+                .arg(clap::Arg::new("path").number_of_values(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)
-                .multiple_values(true)
+                .number_of_values(1..)
                 .value_hint(clap::ValueHint::CommandWithArguments),
         )
         .arg(

diff --git a/clap_derive/src/derives/args.rs b/clap_derive/src/derives/args.rs
@@ -267,7 +267,7 @@ pub fn gen_augment(
                         if attrs.is_positional() {
                             quote_spanned! { ty.span()=>
                                 .value_name(#value_name)
-                                .multiple_values(true)  // action won't be sufficient for getting multiple
+                                .number_of_values(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)
-                                .multiple_values(true)  // action won't be sufficient for getting multiple
+                                .number_of_values(1..)  // action won't be sufficient for getting multiple
                                 #value_parser
                                 #action
                             }

diff --git a/clap_mangen/tests/common.rs b/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)
-                .multiple_values(true)
+                .number_of_values(1..)
                 .value_hint(clap::ValueHint::CommandWithArguments),
         )
         .arg(

diff --git a/examples/escaped-positional.rs b/examples/escaped-positional.rs
@@ -11,7 +11,7 @@ fn main() {
         .arg(
             // Indicates that `slop` is only accessible after `--`.
             arg!(slop: [SLOP])
-                .multiple_values(true)
+                .number_of_values(1..)
                 .last(true)
                 .value_parser(value_parser!(String)),
         )

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