From 9f12bfec47b526ba86597c106f29579357208997 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Mon, 18 Oct 2021 08:35:52 -0500 Subject: [PATCH] fix!: Rename ArgValue to PossibleValue In considering potential work for #2683, I realized we might need a type to carry data for each of the `multiple_values`. `ArgValue` works both for that and for possible values, so we need to come up with a better name for one or both. Changing `ArgValue`s name now would be ideal since its new in clap3 and by renaming it, we can reduce churn for users. While thinking about this, I realized I regularly get these mixed up, so renaming `ArgValue` to `PossibleValue` I think will help clear things up, regardless of #2683. --- clap_derive/src/derives/arg_enum.rs | 16 +++--- clap_derive/src/derives/args.rs | 2 +- clap_derive/src/dummies.rs | 2 +- clap_derive/tests/arg_enum.rs | 8 +-- clap_generate/examples/value_hints.rs | 2 +- clap_generate/src/generators/shells/bash.rs | 2 +- clap_generate/src/generators/shells/zsh.rs | 2 +- clap_generate/src/lib.rs | 2 +- clap_generate/src/shell.rs | 22 ++++---- src/build/arg/mod.rs | 36 ++++++------- .../arg/{arg_value.rs => possible_value.rs} | 52 +++++++++---------- src/build/mod.rs | 2 +- src/derive.rs | 8 +-- src/lib.rs | 2 +- src/parse/validator.rs | 4 +- tests/help.rs | 4 +- tests/possible_values.rs | 16 +++--- 17 files changed, 91 insertions(+), 91 deletions(-) rename src/build/arg/{arg_value.rs => possible_value.rs} (80%) diff --git a/clap_derive/src/derives/arg_enum.rs b/clap_derive/src/derives/arg_enum.rs index ee36d59964b..544fa213deb 100644 --- a/clap_derive/src/derives/arg_enum.rs +++ b/clap_derive/src/derives/arg_enum.rs @@ -47,8 +47,8 @@ pub fn gen_for_enum(name: &Ident, attrs: &[Attribute], e: &DataEnum) -> TokenStr ); let lits = lits(&e.variants, &attrs); - let arg_values = gen_arg_values(&lits); - let to_arg_value = gen_to_arg_value(&lits); + let value_variants = gen_value_variants(&lits); + let to_possible_value = gen_to_possible_value(&lits); quote! { #[allow(dead_code, unreachable_code, unused_variables)] @@ -64,8 +64,8 @@ pub fn gen_for_enum(name: &Ident, attrs: &[Attribute], e: &DataEnum) -> TokenStr )] #[deny(clippy::correctness)] impl clap::ArgEnum for #name { - #arg_values - #to_arg_value + #value_variants + #to_possible_value } } } @@ -89,7 +89,7 @@ fn lits( let name = attrs.cased_name(); Some(( quote! { - clap::ArgValue::new(#name) + clap::PossibleValue::new(#name) #fields }, variant.ident.clone(), @@ -99,7 +99,7 @@ fn lits( .collect::>() } -fn gen_arg_values(lits: &[(TokenStream, Ident)]) -> TokenStream { +fn gen_value_variants(lits: &[(TokenStream, Ident)]) -> TokenStream { let lit = lits.iter().map(|l| &l.1).collect::>(); quote! { @@ -109,11 +109,11 @@ fn gen_arg_values(lits: &[(TokenStream, Ident)]) -> TokenStream { } } -fn gen_to_arg_value(lits: &[(TokenStream, Ident)]) -> TokenStream { +fn gen_to_possible_value(lits: &[(TokenStream, Ident)]) -> TokenStream { let (lit, variant): (Vec, Vec) = lits.iter().cloned().unzip(); quote! { - fn to_arg_value<'a>(&self) -> Option> { + fn to_possible_value<'a>(&self) -> Option> { match self { #(Self::#variant => Some(#lit),)* _ => None diff --git a/clap_derive/src/derives/args.rs b/clap_derive/src/derives/args.rs index 1fb0de2b4c6..d819ffe3c9b 100644 --- a/clap_derive/src/derives/args.rs +++ b/clap_derive/src/derives/args.rs @@ -372,7 +372,7 @@ pub fn gen_augment( fn gen_arg_enum_possible_values(ty: &Type) -> TokenStream { quote_spanned! { ty.span()=> - .possible_values(<#ty as clap::ArgEnum>::value_variants().iter().filter_map(clap::ArgEnum::to_arg_value)) + .possible_values(<#ty as clap::ArgEnum>::value_variants().iter().filter_map(clap::ArgEnum::to_possible_value)) } } diff --git a/clap_derive/src/dummies.rs b/clap_derive/src/dummies.rs index 358cba17456..40250eaa8ae 100644 --- a/clap_derive/src/dummies.rs +++ b/clap_derive/src/dummies.rs @@ -82,7 +82,7 @@ pub fn arg_enum(name: &Ident) { fn from_str(_input: &str, _case_insensitive: bool) -> Result { unimplemented!() } - fn to_arg_value<'a>(&self) -> Option>{ + fn to_possible_value<'a>(&self) -> Option>{ unimplemented!() } } diff --git a/clap_derive/tests/arg_enum.rs b/clap_derive/tests/arg_enum.rs index dd77ccc62e8..c28dcb2506c 100644 --- a/clap_derive/tests/arg_enum.rs +++ b/clap_derive/tests/arg_enum.rs @@ -7,7 +7,7 @@ // , at your // option. This file may not be copied, modified, or distributed // except according to those terms. -use clap::{ArgEnum, ArgValue, Parser}; +use clap::{ArgEnum, Parser, PossibleValue}; #[test] fn basic() { @@ -54,7 +54,7 @@ fn default_value() { impl std::fmt::Display for ArgChoice { fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> Result<(), std::fmt::Error> { - std::fmt::Display::fmt(self.to_arg_value().unwrap().get_name(), f) + std::fmt::Display::fmt(self.to_possible_value().unwrap().get_name(), f) } } @@ -370,10 +370,10 @@ fn skip_variant() { assert_eq!( ArgChoice::value_variants() .iter() - .map(ArgEnum::to_arg_value) + .map(ArgEnum::to_possible_value) .map(Option::unwrap) .collect::>(), - vec![ArgValue::new("foo"), ArgValue::new("bar")] + vec![PossibleValue::new("foo"), PossibleValue::new("bar")] ); assert!(ArgChoice::from_str("foo", true).is_ok()); assert!(ArgChoice::from_str("bar", true).is_ok()); diff --git a/clap_generate/examples/value_hints.rs b/clap_generate/examples/value_hints.rs index 52c6cf31d52..917a69d9d82 100644 --- a/clap_generate/examples/value_hints.rs +++ b/clap_generate/examples/value_hints.rs @@ -23,7 +23,7 @@ fn build_cli() -> App<'static> { .arg( Arg::new("generator") .long("generate") - .possible_values(Shell::arg_values()), + .possible_values(Shell::possible_values()), ) .arg( Arg::new("unknown") diff --git a/clap_generate/src/generators/shells/bash.rs b/clap_generate/src/generators/shells/bash.rs index 2d74bfc74fd..426a44c0409 100644 --- a/clap_generate/src/generators/shells/bash.rs +++ b/clap_generate/src/generators/shells/bash.rs @@ -179,7 +179,7 @@ fn vals_for(o: &Arg) -> String { format!( "$(compgen -W \"{}\" -- \"${{cur}}\")", vals.iter() - .filter_map(ArgValue::get_visible_name) + .filter_map(PossibleValue::get_visible_name) .collect::>() .join(" ") ) diff --git a/clap_generate/src/generators/shells/zsh.rs b/clap_generate/src/generators/shells/zsh.rs index 3e23fa9791a..25af74e1948 100644 --- a/clap_generate/src/generators/shells/zsh.rs +++ b/clap_generate/src/generators/shells/zsh.rs @@ -372,7 +372,7 @@ fn value_completion(arg: &Arg) -> Option { "({})", values .iter() - .filter_map(ArgValue::get_visible_name) + .filter_map(PossibleValue::get_visible_name) .collect::>() .join(" ") )) diff --git a/clap_generate/src/lib.rs b/clap_generate/src/lib.rs index 49ca286a6d2..502dfdc7c0d 100644 --- a/clap_generate/src/lib.rs +++ b/clap_generate/src/lib.rs @@ -36,7 +36,7 @@ //! .arg( //! Arg::new("generator") //! .long("generate") -//! .possible_values(Shell::arg_values()), +//! .possible_values(Shell::possible_values()), //! ) //! } //! diff --git a/clap_generate/src/shell.rs b/clap_generate/src/shell.rs index 059469798a8..042b33b8bbe 100644 --- a/clap_generate/src/shell.rs +++ b/clap_generate/src/shell.rs @@ -1,7 +1,7 @@ use std::fmt::Display; use std::str::FromStr; -use clap::{ArgEnum, ArgValue}; +use clap::{ArgEnum, PossibleValue}; use crate::{generators, Generator}; @@ -23,16 +23,16 @@ pub enum Shell { impl Shell { /// Report all `possible_values` - pub fn arg_values() -> impl Iterator> { + pub fn possible_values() -> impl Iterator> { Shell::value_variants() .iter() - .filter_map(ArgEnum::to_arg_value) + .filter_map(ArgEnum::to_possible_value) } } impl Display for Shell { fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { - self.to_arg_value() + self.to_possible_value() .expect("no values are skipped") .get_name() .fmt(f) @@ -44,7 +44,7 @@ impl FromStr for Shell { fn from_str(s: &str) -> Result { for variant in Self::value_variants() { - if variant.to_arg_value().unwrap().matches(s, false) { + if variant.to_possible_value().unwrap().matches(s, false) { return Ok(*variant); } } @@ -64,13 +64,13 @@ impl ArgEnum for Shell { ] } - fn to_arg_value<'a>(&self) -> Option> { + fn to_possible_value<'a>(&self) -> Option> { Some(match self { - Shell::Bash => ArgValue::new("bash"), - Shell::Elvish => ArgValue::new("elvish"), - Shell::Fish => ArgValue::new("fish"), - Shell::PowerShell => ArgValue::new("powershell"), - Shell::Zsh => ArgValue::new("zsh"), + Shell::Bash => PossibleValue::new("bash"), + Shell::Elvish => PossibleValue::new("elvish"), + Shell::Fish => PossibleValue::new("fish"), + Shell::PowerShell => PossibleValue::new("powershell"), + Shell::Zsh => PossibleValue::new("zsh"), }) } } diff --git a/src/build/arg/mod.rs b/src/build/arg/mod.rs index 01766d331e8..66dc4226627 100644 --- a/src/build/arg/mod.rs +++ b/src/build/arg/mod.rs @@ -1,12 +1,12 @@ -mod arg_value; #[cfg(debug_assertions)] pub mod debug_asserts; +mod possible_value; mod settings; #[cfg(test)] mod tests; mod value_hint; -pub use self::arg_value::ArgValue; +pub use self::possible_value::PossibleValue; pub use self::settings::{ArgFlags, ArgSettings}; pub use self::value_hint::ValueHint; @@ -102,7 +102,7 @@ pub struct Arg<'help> { pub(crate) short_aliases: Vec<(char, bool)>, // (name, visible) pub(crate) disp_ord: usize, pub(crate) unified_ord: usize, - pub(crate) possible_vals: Vec>, + pub(crate) possible_vals: Vec>, pub(crate) val_names: Vec<&'help str>, pub(crate) num_vals: Option, pub(crate) max_occurs: Option, @@ -231,7 +231,7 @@ impl<'help> Arg<'help> { /// Get the list of the possible values for this argument, if any #[inline] - pub fn get_possible_values(&self) -> Option<&[ArgValue]> { + pub fn get_possible_values(&self) -> Option<&[PossibleValue]> { if self.possible_vals.is_empty() { None } else { @@ -1959,7 +1959,7 @@ impl<'help> Arg<'help> { /// /// **NOTE:** This setting only applies to [options] and [positional arguments] /// - /// **NOTE:** You can use both strings directly or use [`ArgValue`] if you want more control + /// **NOTE:** You can use both strings directly or use [`PossibleValue`] if you want more control /// over single possible values. /// /// # Examples @@ -1971,16 +1971,16 @@ impl<'help> Arg<'help> { /// .possible_values(["fast", "slow", "medium"]) /// # ; /// ``` - /// The same using [`ArgValue`]: + /// The same using [`PossibleValue`]: /// /// ```rust - /// # use clap::{App, Arg, ArgValue}; + /// # use clap::{App, Arg, PossibleValue}; /// Arg::new("mode").takes_value(true).possible_values([ - /// ArgValue::new("fast"), + /// PossibleValue::new("fast"), /// // value with a help text - /// ArgValue::new("slow").about("not that fast"), + /// PossibleValue::new("slow").about("not that fast"), /// // value that is hidden from completion and help text - /// ArgValue::new("medium").hidden(true), + /// PossibleValue::new("medium").hidden(true), /// ]) /// # ; /// ``` @@ -2020,7 +2020,7 @@ impl<'help> Arg<'help> { pub fn possible_values(mut self, values: I) -> Self where I: IntoIterator, - T: Into>, + T: Into>, { self.possible_vals .extend(values.into_iter().map(|value| value.into())); @@ -2032,7 +2032,7 @@ impl<'help> Arg<'help> { /// /// **NOTE:** This setting only applies to [options] and [positional arguments] /// - /// **NOTE:** You can use both strings directly or use [`ArgValue`] if you want more control + /// **NOTE:** You can use both strings directly or use [`PossibleValue`] if you want more control /// over single possible values. /// /// # Examples @@ -2046,16 +2046,16 @@ impl<'help> Arg<'help> { /// .possible_value("medium") /// # ; /// ``` - /// The same using [`ArgValue`]: + /// The same using [`PossibleValue`]: /// /// ```rust - /// # use clap::{App, Arg, ArgValue}; + /// # use clap::{App, Arg, PossibleValue}; /// Arg::new("mode").takes_value(true) - /// .possible_value(ArgValue::new("fast")) + /// .possible_value(PossibleValue::new("fast")) /// // value with a help text - /// .possible_value(ArgValue::new("slow").about("not that fast")) + /// .possible_value(PossibleValue::new("slow").about("not that fast")) /// // value that is hidden from completion and help text - /// .possible_value(ArgValue::new("medium").hidden(true)) + /// .possible_value(PossibleValue::new("medium").hidden(true)) /// # ; /// ``` /// @@ -2097,7 +2097,7 @@ impl<'help> Arg<'help> { /// [positional arguments]: Arg::index() pub fn possible_value(mut self, value: T) -> Self where - T: Into>, + T: Into>, { self.possible_vals.push(value.into()); self.takes_value(true) diff --git a/src/build/arg/arg_value.rs b/src/build/arg/possible_value.rs similarity index 80% rename from src/build/arg/arg_value.rs rename to src/build/arg/possible_value.rs index 88757716aaa..34420e0c7bf 100644 --- a/src/build/arg/arg_value.rs +++ b/src/build/arg/possible_value.rs @@ -12,40 +12,40 @@ use crate::util::eq_ignore_case; /// # Examples /// /// ```rust -/// # use clap::{Arg, ArgValue}; +/// # use clap::{Arg, PossibleValue}; /// let cfg = Arg::new("config") /// .takes_value(true) /// .value_name("FILE") -/// .possible_value(ArgValue::new("fast")) -/// .possible_value(ArgValue::new("slow").about("slower than fast")) -/// .possible_value(ArgValue::new("secret speed").hidden(true)); +/// .possible_value(PossibleValue::new("fast")) +/// .possible_value(PossibleValue::new("slow").about("slower than fast")) +/// .possible_value(PossibleValue::new("secret speed").hidden(true)); /// ``` /// [Args]: crate::Arg /// [possible values]: crate::Arg::possible_value() -/// [hide]: ArgValue::hidden() -/// [about]: ArgValue::about() +/// [hide]: PossibleValue::hidden() +/// [about]: PossibleValue::about() #[derive(Debug, Default, Clone, PartialEq, Eq)] -pub struct ArgValue<'help> { +pub struct PossibleValue<'help> { pub(crate) name: &'help str, pub(crate) about: Option<&'help str>, pub(crate) aliases: Vec<&'help str>, // (name, visible) pub(crate) hidden: bool, } -impl<'help> From<&'help str> for ArgValue<'help> { +impl<'help> From<&'help str> for PossibleValue<'help> { fn from(s: &'help str) -> Self { Self::new(s) } } -impl<'help> From<&'help &'help str> for ArgValue<'help> { +impl<'help> From<&'help &'help str> for PossibleValue<'help> { fn from(s: &'help &'help str) -> Self { Self::new(s) } } /// Getters -impl<'help> ArgValue<'help> { +impl<'help> PossibleValue<'help> { /// Get the name of the argument value #[inline] pub fn get_name(&self) -> &str { @@ -86,8 +86,8 @@ impl<'help> ArgValue<'help> { /// # Examples /// /// ```rust - /// # use clap::ArgValue; - /// let arg_value = ArgValue::new("fast").alias("not-slow"); + /// # use clap::PossibleValue; + /// let arg_value = PossibleValue::new("fast").alias("not-slow"); /// /// assert!(arg_value.matches("fast", false)); /// assert!(arg_value.matches("not-slow", false)); @@ -105,8 +105,8 @@ impl<'help> ArgValue<'help> { } } -impl<'help> ArgValue<'help> { - /// Creates a new instance of [`ArgValue`] using a string name. The name will be used to +impl<'help> PossibleValue<'help> { + /// Creates a new instance of [`PossibleValue`] using a string name. The name will be used to /// decide wether this value was provided by the user to an argument. /// /// **NOTE:** In case it is not [hidden] it will also be shown in help messages for arguments @@ -115,15 +115,15 @@ impl<'help> ArgValue<'help> { /// # Examples /// /// ```rust - /// # use clap::ArgValue; - /// ArgValue::new("fast") + /// # use clap::PossibleValue; + /// PossibleValue::new("fast") /// # ; /// ``` - /// [hidden]: ArgValue::hidden + /// [hidden]: PossibleValue::hidden /// [possible value]: crate::Arg::possible_values /// [`Arg::hide_possible_values(true)`]: crate::Arg::hide_possible_values() pub fn new(name: &'help str) -> Self { - ArgValue { + PossibleValue { name, ..Default::default() } @@ -135,8 +135,8 @@ impl<'help> ArgValue<'help> { /// # Examples /// /// ```rust - /// # use clap::ArgValue; - /// ArgValue::new("slow") + /// # use clap::PossibleValue; + /// PossibleValue::new("slow") /// .about("not fast") /// # ; /// ``` @@ -154,8 +154,8 @@ impl<'help> ArgValue<'help> { /// # Examples /// /// ```rust - /// # use clap::ArgValue; - /// ArgValue::new("secret") + /// # use clap::PossibleValue; + /// PossibleValue::new("secret") /// .hidden(true) /// # ; /// ``` @@ -173,8 +173,8 @@ impl<'help> ArgValue<'help> { /// # Examples /// /// ```rust - /// # use clap::ArgValue; - /// ArgValue::new("slow") + /// # use clap::PossibleValue; + /// PossibleValue::new("slow") /// .alias("not-fast") /// # ; /// ``` @@ -190,8 +190,8 @@ impl<'help> ArgValue<'help> { /// # Examples /// /// ```rust - /// # use clap::ArgValue; - /// ArgValue::new("slow") + /// # use clap::PossibleValue; + /// PossibleValue::new("slow") /// .aliases(["not-fast", "snake-like"]) /// # ; /// ``` diff --git a/src/build/mod.rs b/src/build/mod.rs index 46096d46929..d23694dd1ca 100644 --- a/src/build/mod.rs +++ b/src/build/mod.rs @@ -9,6 +9,6 @@ mod usage_parser; pub use self::{ app::{App, AppFlags, AppSettings}, - arg::{Arg, ArgFlags, ArgSettings, ArgValue, ValueHint}, + arg::{Arg, ArgFlags, ArgSettings, PossibleValue, ValueHint}, arg_group::ArgGroup, }; diff --git a/src/derive.rs b/src/derive.rs index d51c00c6587..e73ff4f06e6 100644 --- a/src/derive.rs +++ b/src/derive.rs @@ -1,7 +1,7 @@ //! This module contains traits that are usable with the `#[derive(...)].` //! macros in [`clap_derive`]. -use crate::{App, ArgMatches, ArgValue, Error}; +use crate::{App, ArgMatches, Error, PossibleValue}; use std::ffi::OsString; @@ -295,8 +295,8 @@ pub trait ArgEnum: Sized + Clone { Self::value_variants() .iter() .find(|v| { - v.to_arg_value() - .expect("ArgEnum::value_variants contains only values with a corresponding ArgEnum::to_arg_value") + v.to_possible_value() + .expect("ArgEnum::value_variants contains only values with a corresponding ArgEnum::to_possible_value") .matches(input, case_insensitive) }) .cloned() @@ -306,7 +306,7 @@ pub trait ArgEnum: Sized + Clone { /// The canonical argument value. /// /// The value is `None` for skipped variants. - fn to_arg_value<'a>(&self) -> Option>; + fn to_possible_value<'a>(&self) -> Option>; } impl Parser for Box { diff --git a/src/lib.rs b/src/lib.rs index 5f19ec0b7d6..d6dc023b52e 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -25,7 +25,7 @@ compile_error!("`std` feature is currently required to build `clap`"); pub use crate::{ build::{ - App, AppFlags, AppSettings, Arg, ArgFlags, ArgGroup, ArgSettings, ArgValue, ValueHint, + App, AppFlags, AppSettings, Arg, ArgFlags, ArgGroup, ArgSettings, PossibleValue, ValueHint, }, parse::errors::{Error, ErrorKind, Result}, parse::{ArgMatches, Indices, OsValues, Values}, diff --git a/src/parse/validator.rs b/src/parse/validator.rs index 9fc8be067ab..8cbb83d3a28 100644 --- a/src/parse/validator.rs +++ b/src/parse/validator.rs @@ -1,6 +1,6 @@ // Internal use crate::{ - build::{arg::ArgValue, AppSettings as AS, Arg, ArgSettings}, + build::{arg::PossibleValue, AppSettings as AS, Arg, ArgSettings}, output::Usage, parse::{ errors::{Error, ErrorKind, Result as ClapResult}, @@ -121,7 +121,7 @@ impl<'help, 'app, 'parser> Validator<'help, 'app, 'parser> { val_str.into_owned(), &arg.possible_vals .iter() - .filter_map(ArgValue::get_visible_name) + .filter_map(PossibleValue::get_visible_name) .collect::>(), arg, Usage::new(self.p).create_usage_with_title(&used), diff --git a/tests/help.rs b/tests/help.rs index fee7af246c7..9233514b550 100644 --- a/tests/help.rs +++ b/tests/help.rs @@ -1,6 +1,6 @@ mod utils; -use clap::{App, AppSettings, Arg, ArgGroup, ArgSettings, ArgValue, ErrorKind}; +use clap::{App, AppSettings, Arg, ArgGroup, ArgSettings, ErrorKind, PossibleValue}; static REQUIRE_DELIM_HELP: &str = "test 1.3 @@ -1049,7 +1049,7 @@ fn hide_single_possible_val() { .long("pos") .value_name("VAL") .possible_values(["fast", "slow"]) - .possible_value(ArgValue::new("secret speed").hidden(true)) + .possible_value(PossibleValue::new("secret speed").hidden(true)) .about("Some vals") .takes_value(true), ) diff --git a/tests/possible_values.rs b/tests/possible_values.rs index 5f8638af454..469f35fe098 100644 --- a/tests/possible_values.rs +++ b/tests/possible_values.rs @@ -1,6 +1,6 @@ mod utils; -use clap::{App, Arg, ArgValue, ErrorKind}; +use clap::{App, Arg, ErrorKind, PossibleValue}; #[cfg(feature = "suggestions")] static PV_ERROR: &str = "error: \"slo\" isn't a valid value for '-O