feat: ValueEnum fallback

Cargo.toml

@@ -144,6 +144,7 @@ default = [
   "usage",
   "error-context",
   "suggestions",
+"unstable-derive-ui-tests"
 ]
 debug = ["clap_builder/debug", "clap_derive?/debug"] # Enables debug messages
 unstable-doc = ["clap_builder/unstable-doc", "derive"] # for docs.rs

clap_derive/Cargo.toml

@@ -29,7 +29,7 @@ proc-macro = true
 bench = false
 
 [dependencies]
-syn = { version = "2.0.8", features = ["full"] }
+syn = { version = "2.0.73", features = ["full"] }
 quote = "1.0.9"
 proc-macro2 = "1.0.69"
 heck = "0.5.0"

clap_derive/src/attr.rs

@@ -102,6 +102,7 @@ impl Parse for ClapAttr {
             "long_help" => Some(MagicAttrName::LongHelp),
             "author" => Some(MagicAttrName::Author),
             "version" => Some(MagicAttrName::Version),
+            "fallback" => Some(MagicAttrName::Fallback),
             _ => None,
         };
 
@@ -168,6 +169,7 @@ pub(crate) enum MagicAttrName {
     DefaultValuesOsT,
     NextDisplayOrder,
     NextHelpHeading,
+    Fallback,
 }
 
 #[derive(Clone)]

clap_derive/src/derives/value_enum.rs

@@ -49,6 +49,7 @@ pub(crate) fn gen_for_enum(
     let lits = lits(variants)?;
     let value_variants = gen_value_variants(&lits);
     let to_possible_value = gen_to_possible_value(item, &lits);
+    let from_str_for_fallback = gen_from_str_for_fallback(variants)?;
 
     Ok(quote! {
         #[allow(
@@ -75,6 +76,7 @@ pub(crate) fn gen_for_enum(
         impl clap::ValueEnum for #item_name {
             #value_variants
             #to_possible_value
+            #from_str_for_fallback
         }
     })
 }
@@ -85,6 +87,9 @@ fn lits(variants: &[(&Variant, Item)]) -> Result<Vec<(TokenStream, Ident)>, syn:
         if let Kind::Skip(_, _) = &*item.kind() {
             continue;
         }
+        if item.is_fallback() {
+            continue;
+        }
         if !matches!(variant.fields, Fields::Unit) {
             abort!(variant.span(), "`#[derive(ValueEnum)]` only supports unit variants. Non-unit variants must be skipped");
         }
@@ -128,3 +133,62 @@ fn gen_to_possible_value(item: &Item, lits: &[(TokenStream, Ident)]) -> TokenStr
         }
     }
 }
+
+fn gen_from_str_for_fallback(variants: &[(&Variant, Item)]) -> syn::Result<TokenStream> {
+    let fallbacks: Vec<_> = variants
+        .iter()
+        .filter(|(_, item)| item.is_fallback())
+        .collect();
+
+    match fallbacks.as_slice() {
+        [] => Ok(quote!()),
+        [(variant, _)] => {
+            let ident = &variant.ident;
+            let variant_initialization = match variant.fields.len() {
+                _ if matches!(variant.fields, Fields::Unit) => quote! {#ident},
+                0 => quote! {#ident{}},
+                1 => {
+                    let member = variant
+                        .fields
+                        .members()
+                        .next()
+                        .expect("there should be exactly one field");
+                    quote! {#ident{
+                        #member: {
+                            use std::convert::Into;
+                            __input.into()
+                        },
+                    }}
+                }
+                _ => abort!(
+                    variant,
+                    "`fallback` only supports Unit variants, or variants with a single field"
+                ),
+            };
+            Ok(quote! {
+                fn from_str(__input: &::std::primitive::str, __ignore_case: ::std::primitive::bool) -> ::std::result::Result<Self, ::std::string::String> {
+                    Ok(Self::value_variants()
+                        .iter()
+                        .find(|v| {
+                            v.to_possible_value()
+                                .expect("ValueEnum::value_variants contains only values with a corresponding ValueEnum::to_possible_value")
+                                .matches(__input, __ignore_case)
+                        })
+                        .cloned()
+                        .unwrap_or_else(|| Self::#variant_initialization))
+                }
+            })
+        }
+        [first, second, ..] => {
+            let mut error = syn::Error::new_spanned(
+                first.0,
+                "`#[derive(ValueEnum)]` only supports one `fallback`.",
+            );
+            error.combine(syn::Error::new_spanned(
+                second.0,
+                "second fallback defined here",
+            ));
+            Err(error)
+        }
+    }
+}

clap_derive/src/item.rs

@@ -49,6 +49,8 @@ pub(crate) struct Item {
     skip_group: bool,
     group_id: Name,
     group_methods: Vec<Method>,
+    /// Used as fallback value `ValueEnum`.
+    is_fallback: bool,
     kind: Sp<Kind>,
 }
 
@@ -279,6 +281,7 @@ impl Item {
             group_id,
             group_methods: vec![],
             kind,
+            is_fallback: false,
         }
     }
 
@@ -835,6 +838,12 @@ impl Item {
                     self.skip_group = true;
                 }
 
+                Some(MagicAttrName::Fallback) => {
+                    assert_attr_kind(attr, &[AttrKind::Value])?;
+
+                    self.is_fallback = true;
+                }
+
                 None
                 // Magic only for the default, otherwise just forward to the builder
                 | Some(MagicAttrName::Short)
@@ -1077,6 +1086,10 @@ impl Item {
     pub(crate) fn skip_group(&self) -> bool {
         self.skip_group
     }
+
+    pub(crate) fn is_fallback(&self) -> bool {
+        self.is_fallback
+    }
 }
 
 #[derive(Clone)]

tests/derive/value_enum.rs

@@ -626,3 +626,152 @@ fn vec_type_default_value() {
         Opt::try_parse_from(["", "-a", "foo,baz"]).unwrap()
     );
 }
+
+#[test]
+fn unit_fallback() {
+    #[derive(clap::ValueEnum, PartialEq, Debug, Clone)]
+    enum ArgChoice {
+        Foo,
+        #[clap(fallback)]
+        Fallback,
+    }
+
+    #[derive(Parser, PartialEq, Debug)]
+    struct Opt {
+        #[arg(value_enum)]
+        arg: ArgChoice,
+    }
+
+    assert_eq!(
+        Opt {
+            arg: ArgChoice::Foo
+        },
+        Opt::try_parse_from(["", "foo"]).unwrap()
+    );
+    assert_eq!(
+        Opt {
+            arg: ArgChoice::Fallback
+        },
+        Opt::try_parse_from(["", "not-foo"]).unwrap()
+    );
+}
+
+#[test]
+fn empty_tuple_fallback() {
+    #[derive(clap::ValueEnum, PartialEq, Debug, Clone)]
+    enum ArgChoice {
+        Foo,
+        #[clap(fallback)]
+        Fallback(),
+    }
+
+    #[derive(Parser, PartialEq, Debug)]
+    struct Opt {
+        #[arg(value_enum)]
+        arg: ArgChoice,
+    }
+
+    assert_eq!(
+        Opt {
+            arg: ArgChoice::Foo
+        },
+        Opt::try_parse_from(["", "foo"]).unwrap()
+    );
+    assert_eq!(
+        Opt {
+            arg: ArgChoice::Fallback()
+        },
+        Opt::try_parse_from(["", "not-foo"]).unwrap()
+    );
+}
+
+#[test]
+fn empty_struct_fallback() {
+    #[derive(clap::ValueEnum, PartialEq, Debug, Clone)]
+    enum ArgChoice {
+        Foo,
+        #[clap(fallback)]
+        Fallback {},
+    }
+
+    #[derive(Parser, PartialEq, Debug)]
+    struct Opt {
+        #[arg(value_enum)]
+        arg: ArgChoice,
+    }
+
+    assert_eq!(
+        Opt {
+            arg: ArgChoice::Foo
+        },
+        Opt::try_parse_from(["", "foo"]).unwrap()
+    );
+    assert_eq!(
+        Opt {
+            arg: ArgChoice::Fallback {}
+        },
+        Opt::try_parse_from(["", "not-foo"]).unwrap()
+    );
+}
+
+#[test]
+fn non_empty_struct_fallback() {
+    #[derive(clap::ValueEnum, PartialEq, Debug, Clone)]
+    enum ArgChoice {
+        Foo,
+        #[clap(fallback)]
+        Fallback {
+            value: String,
+        },
+    }
+
+    #[derive(Parser, PartialEq, Debug)]
+    struct Opt {
+        #[arg(value_enum)]
+        arg: ArgChoice,
+    }
+
+    assert_eq!(
+        Opt {
+            arg: ArgChoice::Foo
+        },
+        Opt::try_parse_from(["", "foo"]).unwrap()
+    );
+    assert_eq!(
+        Opt {
+            arg: ArgChoice::Fallback {
+                value: String::from("not-foo")
+            }
+        },
+        Opt::try_parse_from(["", "not-foo"]).unwrap()
+    );
+}
+
+#[test]
+fn non_empty_tuple_fallback() {
+    #[derive(clap::ValueEnum, PartialEq, Debug, Clone)]
+    enum ArgChoice {
+        Foo,
+        #[clap(fallback)]
+        Fallback(String),
+    }
+
+    #[derive(Parser, PartialEq, Debug)]
+    struct Opt {
+        #[arg(value_enum)]
+        arg: ArgChoice,
+    }
+
+    assert_eq!(
+        Opt {
+            arg: ArgChoice::Foo
+        },
+        Opt::try_parse_from(["", "foo"]).unwrap()
+    );
+    assert_eq!(
+        Opt {
+            arg: ArgChoice::Fallback(String::from("not-foo"))
+        },
+        Opt::try_parse_from(["", "not-foo"]).unwrap()
+    );
+}

tests/derive_ui/value_enum_fallback_two_fields.rs

@@ -0,0 +1,10 @@
+use clap::ValueEnum;
+
+#[derive(ValueEnum, Clone, Debug)]
+enum Opt {
+    #[clap(fallback)]
+    First(String, String),
+}
+
+fn main() {}
+

tests/derive_ui/value_enum_fallback_two_fields.stderr

@@ -0,0 +1,6 @@
+error: `fallback` only supports Unit variants, or variants with a single field
+ --> tests/derive_ui/value_enum_fallback_two_fields.rs:5:5
+  |
+5 | /     #[clap(fallback)]
+6 | |     First(String, String),
+  | |_________________________^

tests/derive_ui/value_enum_two_fallback.rs

@@ -0,0 +1,11 @@
+use clap::ValueEnum;
+
+#[derive(ValueEnum, Clone, Debug)]
+enum Opt {
+    #[clap(fallback)]
+    First(String),
+    #[clap(fallback)]
+    Second(String),
+}
+
+fn main() {}

tests/derive_ui/value_enum_two_fallback.stderr

@@ -0,0 +1,13 @@
+error: `#[derive(ValueEnum)]` only supports one `fallback`.
+ --> tests/derive_ui/value_enum_two_fallback.rs:5:5
+  |
+5 | /     #[clap(fallback)]
+6 | |     First(String),
+  | |_________________^
+
+error: second fallback defined here
+ --> tests/derive_ui/value_enum_two_fallback.rs:7:5
+  |
+7 | /     #[clap(fallback)]
+8 | |     Second(String),
+  | |__________________^

tests/derive_ui/value_parser_unsupported.stderr

@@ -37,6 +37,14 @@ note: the traits `From`, `FromStr`, `ValueEnum`,  and `ValueParserFactory` must
   |
   | pub trait ValueEnum: Sized + Clone {
   | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- --> $RUST/core/src/convert/mod.rs
- --> $RUST/core/src/str/traits.rs
+  |
+ ::: $RUST/core/src/convert/mod.rs
+  |
+  | pub trait From<T>: Sized {
+  | ^^^^^^^^^^^^^^^^^^^^^^^^
+  |
+ ::: $RUST/core/src/str/traits.rs
+  |
+  | pub trait FromStr: Sized {
+  | ^^^^^^^^^^^^^^^^^^^^^^^^
   = note: this error originates in the macro `clap::value_parser` (in Nightly builds, run with -Z macro-backtrace for more info)