feat(derive): a default a collecting field can hold

benches/mise.usage.kdl

@@ -5386,14 +5386,21 @@ This can also be used via the $WATCHEXEC_IGNORE_FILES environment variable.
 """#
         arg <PATH>
     }
-    flag --fs-events help="Filesystem events to filter to" var=#true default=create,remove,rename,modify,metadata {
+    flag --fs-events help="Filesystem events to filter to" var=#true {
         long_help #"""
 Filesystem events to filter to
 
 This is a quick filter to only emit events for the given types of filesystem changes. Choose from 'access', 'create', 'remove', 'rename', 'modify', 'metadata'. Multiple types can be given by repeating the option or by separating them with commas. By default, this is all types except for 'access'.
 
 This may apply filtering at the kernel level when possible, which can be more efficient, but may be more confusing when reading the logs.
 """#
+        default {
+            create
+            remove
+            rename
+            modify
+            metadata
+        }
         arg <EVENTS> {
             choices access create remove rename modify metadata
         }

benches/shadows/mise-clap/src/lib.rs

@@ -5356,7 +5356,7 @@ pub struct WatchArgs {
     /// This is a quick filter to only emit events for the given types of filesystem changes. Choose from 'access', 'create', 'remove', 'rename', 'modify', 'metadata'. Multiple types can be given by repeating the option or by separating them with commas. By default, this is all types except for 'access'.
     ///
     /// This may apply filtering at the kernel level when possible, which can be more efficient, but may be more confusing when reading the logs.
-    #[arg(long = "fs-events", value_name = "EVENTS", value_parser = ::clap::builder::PossibleValuesParser::new(["access", "create", "remove", "rename", "modify", "metadata"]), default_value = "create,remove,rename,modify,metadata")]
+    #[arg(long = "fs-events", value_name = "EVENTS", value_parser = ::clap::builder::PossibleValuesParser::new(["access", "create", "remove", "rename", "modify", "metadata"]), default_value = "create")]
     pub fs_events: Vec<String>,
     /// Don't emit fs events for metadata changes
     ///

benches/shadows/mise/src/lib.rs

@@ -5945,6 +5945,11 @@ pub struct WatchArgs {
         long = "fs-events",
         value_name = "EVENTS",
         choices("access", "create", "remove", "rename", "modify", "metadata"),
+        default = "create",
+        default = "remove",
+        default = "rename",
+        default = "modify",
+        default = "metadata",
         var
     )]
     pub fs_events: ::std::vec::Vec<::std::string::String>,

conformance/tests/post_binding.rs

@@ -430,3 +430,125 @@ fn each_occurrence_of_a_bounded_flag_counts_for_itself() {
     assert_eq!(bounded.include, ["a", "b"]);
     assert_eq!(bounded.out.as_deref(), Some("c"));
 }
+
+/// A watcher whose filter starts out set
+///
+/// mise's `mise watch --fs-events`, which is where this came from: a `Vec` flag that already
+/// holds something when nobody gives it one. Its spec said so and the derive could not, so it
+/// was the last thing mise's 211-command spec could express that the derive could not.
+#[derive(Cli)]
+#[usage(bin = "ex")]
+struct Defaulted {
+    /// Filesystem events to filter to
+    #[usage(long, var, default = "create", default = "remove", default = "modify")]
+    fs_events: Vec<String>,
+    /// Watch everything again
+    #[usage(long, overrides = "--fs-events")]
+    all_events: bool,
+    /// One value, and it may be given once
+    #[usage(long, default = "4")]
+    jobs: Option<String>,
+    /// Read from the environment when nobody says otherwise
+    #[usage(long, var, default = "one", default = "two", env = "EX_FROM_ENV")]
+    from_env: Vec<String>,
+    /// Never `None`, because it always has something
+    #[usage(long, var, default = "x", default = "y")]
+    maybe: Option<Vec<String>>,
+    /// `None` until it is given, because it declares nothing
+    #[usage(long, var)]
+    plain: Option<Vec<String>>,
+}
+
+#[test]
+fn a_collecting_flag_starts_out_holding_its_defaults() {
+    // Absent: all of them, in the order written. A `Vec` is the one shape that can hold
+    // several, so it is the one shape that may be given several.
+    let a = argv([]);
+    let d = Defaulted::parse_from(&a).expect("should parse");
+    assert_eq!(d.fs_events, ["create", "remove", "modify"]);
+    assert_eq!(d.jobs.as_deref(), Some("4"));
+
+    // Given: *replaced*, not added to. A default says what the flag means when nobody said
+    // anything, so appending would make `--fs-events access` mean four events, three of which
+    // the user asked to filter out.
+    let a = argv(["--fs-events", "access"]);
+    let d = Defaulted::parse_from(&a).expect("should parse");
+    assert_eq!(d.fs_events, ["access"]);
+}
+
+#[test]
+fn the_defaults_reach_the_spec_in_order() {
+    // The spec is the interface: a default the parser applies and the spec omits is a CLI whose
+    // help, completions and manpage describe different behaviour from the binary.
+    let spec: usage::Spec = Defaulted::to_kdl().parse().expect("valid spec");
+    let flag = spec
+        .cmd
+        .flags
+        .iter()
+        .find(|f| f.name == "fs-events")
+        .expect("the flag");
+    let defaults = if flag.default.is_empty() {
+        &flag.arg.as_ref().expect("takes a value").default
+    } else {
+        &flag.default
+    };
+    assert_eq!(defaults, &["create", "remove", "modify"]);
+}
+
+#[test]
+fn a_displaced_collecting_flag_goes_back_to_its_defaults() {
+    // The other half of "replaced, not added to", and the half the guard on `__given_*` hides:
+    // when the flag *was* given, the defaults are never reached — except here. `--all-events`
+    // displaces `--fs-events`, and what a displaced flag reads as is its declared default, so
+    // the values the user gave have to go. Appending would leave `access` standing beside the
+    // three it was meant to replace, in a flag the user asked to be overridden.
+    let a = argv(["--fs-events", "access", "--all-events"]);
+    let d = Defaulted::parse_from(&a).expect("should parse");
+    assert!(d.all_events);
+    assert_eq!(
+        d.fs_events,
+        ["create", "remove", "modify"],
+        "back to its declared defaults, and only those"
+    );
+}
+
+#[test]
+fn the_environment_replaces_a_collections_defaults() {
+    // Every other shape assigns, so the environment overrides a default. A collection pushed,
+    // so it ended up holding both — three events when the variable named one, and the extra two
+    // are the ones the user's variable was chosen instead of.
+    //
+    // Serialized against the other environment test by reading a variable of its own.
+    unsafe { std::env::set_var("EX_FROM_ENV", "three") };
+    let a = argv([]);
+    let d = Defaulted::parse_from(&a).expect("should parse");
+    assert_eq!(d.from_env, ["three"]);
+    unsafe { std::env::remove_var("EX_FROM_ENV") };
+
+    // And with the variable unset the defaults stand, which is the other half of "replaces".
+    let a = argv([]);
+    let d = Defaulted::parse_from(&a).expect("should parse");
+    assert_eq!(d.from_env, ["one", "two"]);
+}
+
+#[test]
+fn an_optional_collection_with_defaults_is_never_none() {
+    // `Option<Vec<T>>` says `None` for "never given", and a default is a value — so a field that
+    // declares one always has something to hold. Seeding it left `__given_*` alone (the
+    // environment still has to be able to replace it), so `None` came back and every declared
+    // default was discarded on the way out of the partial.
+    let a = argv([]);
+    let d = Defaulted::parse_from(&a).expect("should parse");
+    assert_eq!(
+        d.maybe.as_deref(),
+        Some(&["x".to_string(), "y".to_string()][..])
+    );
+
+    // Given, it is what was given.
+    let a = argv(["--maybe", "z"]);
+    let d = Defaulted::parse_from(&a).expect("should parse");
+    assert_eq!(d.maybe.as_deref(), Some(&["z".to_string()][..]));
+
+    // And one that declares no default still tells "never given" from "given nothing".
+    assert_eq!(d.plain, None);
+}

derive/src/codegen.rs

@@ -697,10 +697,8 @@ fn flag_meta(i: usize, field: &Field, owner: &syn::Ident) -> TokenStream {
     let env = option_str(field.env.as_deref());
     let help_heading = option_str(field.help_heading.as_deref());
     let value_name = option_str(field.value_name.as_deref());
-    let default = match field.default.as_deref() {
-        Some(d) => quote!(&[#d]),
-        None => quote!(&[]),
-    };
+    let defaults = &field.default;
+    let default = quote!(&[#(#defaults),*]);
     let hide = field.hide;
     let count = field.shape == Shape::Count;
     let repeatable = field.repeatable;
@@ -755,10 +753,8 @@ fn arg_meta(i: usize, field: &Field, owner: &syn::Ident) -> TokenStream {
     let long_help = option_str(field.long_help.as_deref());
     let env = option_str(field.env.as_deref());
     let help_heading = option_str(field.help_heading.as_deref());
-    let default = match field.default.as_deref() {
-        Some(d) => quote!(&[#d]),
-        None => quote!(&[]),
-    };
+    let defaults = &field.default;
+    let default = quote!(&[#(#defaults),*]);
     let hide = field.hide;
     // `String` must be filled; `Option` and `Vec` need not be.
     // A collecting field's type cannot say whether one value is needed, so `required` may
@@ -1707,10 +1703,11 @@ fn field_final(field: &Field) -> TokenStream {
                 }};
                 if field.optional_collection {
                     let given = format_ident!("__given_{}", ident);
+                    let defaulted = !field.default.is_empty();
                     // Same as below: whether anything arrived is what tells "never given"
                     // from "given nothing", which the `Vec` itself cannot.
                     quote! {
-                        #ident: if partial.#given {
+                        #ident: if partial.#given || #defaulted {
                             ::std::option::Option::Some(#collected)
                         } else {
                             ::std::option::Option::None
@@ -1800,10 +1797,14 @@ fn field_final(field: &Field) -> TokenStream {
             }};
             if field.optional_collection {
                 let given = format_ident!("__given_{}", ident);
+                // A declared default is a value, so a field that has one is never `None`. It
+                // does not set `__given_*` — the environment still has to be able to replace it
+                // — so the answer has to come from the declaration rather than from the partial.
+                let defaulted = !field.default.is_empty();
                 // `Option<Vec<T>>` distinguishes "never given" from "given nothing", which
                 // no `Vec` can — so the answer comes from whether anything arrived.
                 quote! {
-                    #ident: if partial.#given {
+                    #ident: if partial.#given || #defaulted {
                         ::std::option::Option::Some(#collected)
                     } else {
                         ::std::option::Option::None
@@ -1824,27 +1825,36 @@ fn field_final(field: &Field) -> TokenStream {
 /// not as absent.
 fn reset_to_default(field: &Field) -> TokenStream {
     let ident = &field.ident;
-    let Some(default) = field.default.as_deref() else {
-        return match field.shape {
-            // A collection is cleared rather than replaced, so the field keeps whatever
-            // capacity it already allocated.
-            Shape::Many => quote!(partial.#ident.clear();),
-            _ => quote!(partial.#ident = ::std::default::Default::default();),
-        };
+    // A collection is cleared rather than replaced, so the field keeps whatever capacity it
+    // already allocated — and clearing is also the first half of seeding it, since a default
+    // means *these values and no others* however many were bound before.
+    let cleared = match field.shape {
+        Shape::Many => quote!(partial.#ident.clear();),
+        _ => quote!(partial.#ident = ::std::default::Default::default();),
     };
+    if field.default.is_empty() {
+        return cleared;
+    }
+    // Every shape but a collection was checked in the model to have at most one.
+    let first = &field.default[0];
     match field.shape {
         Shape::Bool => {
-            let on = default == "true";
+            let on = first == "true";
             quote!(partial.#ident = #on;)
         }
         Shape::Optional => quote! {
-            partial.#ident = ::std::option::Option::Some(#default.as_bytes().to_vec());
+            partial.#ident = ::std::option::Option::Some(#first.as_bytes().to_vec());
         },
-        Shape::Required => quote!(partial.#ident = #default.as_bytes().to_vec();),
-        // Rejected in the model: a count starts at zero, and a default for a collecting
-        // field is not applied yet.
-        Shape::Count => quote!(partial.#ident = ::std::default::Default::default();),
-        Shape::Many => quote!(partial.#ident.clear();),
+        Shape::Required => quote!(partial.#ident = #first.as_bytes().to_vec();),
+        // Rejected in the model: a count starts at zero, so a default has nothing to say.
+        Shape::Count => cleared,
+        Shape::Many => {
+            let defaults = &field.default;
+            quote! {
+                #cleared
+                #(partial.#ident.push(#defaults.as_bytes().to_vec());)*
+            }
+        }
     }
 }
 
@@ -2540,7 +2550,7 @@ fn post_binding(cli: &Cli) -> TokenStream {
     // Guarded on `__given_*`, which is what makes this safe to move: a negation that set a
     // defaulted `bool` to false during the parse must not be undone here.
     let declared_defaults = cli.fields.iter().filter_map(|f| {
-        if f.default.is_none() || matches!(f.kind, Kind::Subcommand { .. }) {
+        if f.default.is_empty() || matches!(f.kind, Kind::Subcommand { .. }) {
             return None;
         }
         let given = format_ident!("__given_{}", f.ident);
@@ -2563,7 +2573,15 @@ fn post_binding(cli: &Cli) -> TokenStream {
                 partial.#ident = ::std::option::Option::Some(value.into_bytes());
             },
             Shape::Required => quote!(partial.#ident = value.into_bytes();),
-            Shape::Many => quote!(partial.#ident.push(value.into_bytes());),
+            // Cleared first, so the environment *replaces* a declared default instead of
+            // adding to it — which is what every other shape does by assigning, and what the
+            // order here means: a default says what the value is when nobody said anything,
+            // and the environment is somebody saying something. Nothing else can be in the
+            // collection at this point: argv sets `__given_*`, which this is guarded on.
+            Shape::Many => quote! {
+                partial.#ident.clear();
+                partial.#ident.push(value.into_bytes());
+            },
             // A switch reads as on for anything but the spellings of "off", which is
             // what every tool that takes a boolean from the environment settles on.
             Shape::Bool => quote! {
@@ -2609,7 +2627,7 @@ fn post_binding(cli: &Cli) -> TokenStream {
         // meant a `Vec` marked `required` was reported as one-or-more by the spec, the help, the
         // manpage and the completions, and accepted zero values from the CLI that actually ran.
         // One expression cannot disagree with itself.
-        if !(f.shape == Shape::Required || f.required_collection) || f.default.is_some() {
+        if !(f.shape == Shape::Required || f.required_collection) || !f.default.is_empty() {
             return None;
         }
         let given = format_ident!("__given_{}", f.ident);
@@ -2770,7 +2788,7 @@ fn post_binding(cli: &Cli) -> TokenStream {
         }
         // A field with a default is already filled, so no condition can make it
         // missing. Plain required-ness skips these too, and so does usage-lib.
-        if f.default.is_some() {
+        if !f.default.is_empty() {
             return None;
         }
         let given = format_ident!("__given_{}", f.ident);

derive/src/lib.rs

@@ -171,7 +171,7 @@
 //! | `var_max = n` | how many values a variadic takes before the next field gets the rest |
 //! | `global` | subcommands inherit the flag |
 //! | `env = "X"` | an environment variable that can supply the value |
-//! | `default = "x"` | the value when the command line does not supply one |
+//! | `default = "x"` | the value when the command line does not supply one; a `Vec` may be given several, and starts out holding all of them |
 //! | `help_heading = "x"` | the section to list this under in help output |
 //! | `hide` | keep it out of help and completions |
 //! | `double_dash = "…"` | how a positional relates to `--`: `optional` (the default), `required` (fillable only after one), `preserve` (the `--` is a value), `automatic` (filling it ends flag parsing, so a wrapper forwards) |