Ability to apply a setting to all args

[epage]

Issue by epage
Monday Nov 08, 2021 at 14:14 GMT
Originally opened as clap-rs/clap#3002

---

Use Cases

• "in our application tests [we need] to set an argument setting on all arguments programmatically just in the test context, and we had a lot of arguments so safest, cleanest, and easiest, to be able to set it with this new function. Essentially: app.mut_args(|arg| Some(arg.setting(ArgSettings::HideEnvValues)))". See #2966
• AppSettings::AllArgsOverrideSelf is arg configuration that we want to apply everywhere. Rather than creating specialized arguments, is there a different way?
• One option for sorting arguments in help after Builder and clap_derive should be WYSIWYG clap-rs/clap#2808 is to set the same display order on all arguments
• App::help_heading allows applying Arg:help_heading to all future arguments to take advantage of the natural grouping of arguments when adding them.

Note: in some cases, users will want this to apply globally (ie to all subcommand args)

Solution Options

Note: this isn't a "pick one" but we can use a mixture

• Specialize Arg settings in App (ie do nothing), like
  • AppSettings::AllArgsOverrideSelf
  • App::help_heading
  • A App::next_display_order for #2808
  • Con:: design / implementation is needed for each solution
  • Con: each solution ends up different than the others
• Direct users to use reflection + mut_arg to manually apply a setting (ie do nothing, see #2976)
  • This ended up being what we used instead of #2966 which led to it being reverted in #2994
  • Con: Not ergonomic for clap_derive users (instead of calling Parser, they have to call IntoApp and FromArgMarches)
• Provide a App:args_mut(&mut self) -> impl Iterator<Item = &mut Arg>.
  • Con: Not ergonomic for clap_derive users (instead of calling Parser, they have to call IntoApp and FromArgMarches)
• Provide a App::arg_setting
  • Con: Only works with ArgSettings, so doesn't help with AppSettings::AllArgsOverrideSelf or display_order
• mut_args, modeled after mut_arg (see #2966, #2994)
  • Con: The return type is confusing (should it be just bool?)
  • Con: Policy of when to return what is unclear
• Like mut_args above but Fn doesn't have a return type
  • mut_arg assumes you are calling it on an arg you intend to keep, so an implicit --version becomes explicit, making it show up when you might have disabled it
  • #2966 carried this policy forward but provided a return value to avoid adding disabled args
  • This solution assumes that mass-setting an argument is argument-agnostic and it does not imply the intention of using that argument, so it keeps --version implicit
• App::default_arg(arg: Arg) or App::mut_default_arg is layered underneath each arg
  • We'd have to implement support for tracking what arguments are explicitly set or not to know what is set in the "default arg" and what not to override in each arg
  • Not all settings should be layered (like alias or long)
• App::override_arg(arg: Arg) or App::mut_override_arg is layered on top of each arg
  • We'd have to implement support for tracking what arguments are explicitly set or not to know what is set in the "override arg"
  • Not all settings should be layered (like alias or long)

For when to apply these to subcommands, we could

• Have a global_ variant of any function, like today's ``global_settings`
• Accept a global: bool or scope: enum Scope { Local, Inherit } argument in any function
• Layer Subcommands on top of their immediate parent App
  • Like with default and override args, this will require tracking what configuration is explicitly set
  • Not all settings should be layered, like alias (used for subcommands)

[epage]

Comment by epage
Monday Nov 08, 2021 at 14:15 GMT

---

@repi in case you have any further thoughts on this topic