From dc0db358abe19481e475e10c32149b53370f1a1c Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Thu, 30 May 2024 05:57:31 +0200 Subject: Merging upstream version 1.72.1+dfsg1. Signed-off-by: Daniel Baumann --- vendor/clap_builder/src/builder/command.rs | 131 ++++++++++++++++------------- 1 file changed, 71 insertions(+), 60 deletions(-) (limited to 'vendor/clap_builder/src/builder/command.rs') diff --git a/vendor/clap_builder/src/builder/command.rs b/vendor/clap_builder/src/builder/command.rs index 799623581..2c5eb1989 100644 --- a/vendor/clap_builder/src/builder/command.rs +++ b/vendor/clap_builder/src/builder/command.rs @@ -105,6 +105,7 @@ pub struct Command { subcommand_heading: Option, external_value_parser: Option, long_help_exists: bool, + deferred: Option Command>, app_ext: Extensions, } @@ -209,8 +210,6 @@ impl Command { /// Allows one to mutate an [`Arg`] after it's been added to a [`Command`]. /// - /// This can be useful for modifying the auto-generated help or version arguments. - /// /// # Panics /// /// If the argument is undefined @@ -430,6 +429,30 @@ impl Command { self } + /// Delay initialization for parts of the `Command` + /// + /// This is useful for large applications to delay definitions of subcommands until they are + /// being invoked. + /// + /// # Examples + /// + /// ```rust + /// # use clap_builder as clap; + /// # use clap::{Command, arg}; + /// Command::new("myprog") + /// .subcommand(Command::new("config") + /// .about("Controls configuration features") + /// .defer(|cmd| { + /// cmd.arg(arg!( "Required configuration file to use")) + /// }) + /// ) + /// # ; + /// ``` + pub fn defer(mut self, deferred: fn(Command) -> Command) -> Self { + self.deferred = Some(deferred); + self + } + /// Catch problems earlier in the development cycle. /// /// Most error states are handled as asserts under the assumption they are programming mistake @@ -686,10 +709,7 @@ impl Command { if let Some(command) = argv0.file_stem().and_then(|f| f.to_str()) { // Stop borrowing command so we can get another mut ref to it. let command = command.to_owned(); - debug!( - "Command::try_get_matches_from_mut: Parsed command {} from argv", - command - ); + debug!("Command::try_get_matches_from_mut: Parsed command {command} from argv"); debug!("Command::try_get_matches_from_mut: Reinserting command into arguments so subcommand parser matches it"); raw_args.insert(&cursor, [&command]); @@ -791,7 +811,7 @@ impl Command { /// let mut cmd = Command::new("myprog"); /// let mut out = io::stdout(); /// let help = cmd.render_help(); - /// println!("{}", help); + /// println!("{help}"); /// ``` /// [`io::Write`]: std::io::Write /// [`-h` (short)]: Arg::help() @@ -818,7 +838,7 @@ impl Command { /// let mut cmd = Command::new("myprog"); /// let mut out = io::stdout(); /// let help = cmd.render_long_help(); - /// println!("{}", help); + /// println!("{help}"); /// ``` /// [`io::Write`]: std::io::Write /// [`-h` (short)]: Arg::help() @@ -986,7 +1006,7 @@ impl Command { /// /// let r = cmd.try_get_matches_from(vec!["cmd", "-c", "file", "-f", "-x"]); /// - /// assert!(r.is_ok(), "unexpected error: {:?}", r); + /// assert!(r.is_ok(), "unexpected error: {r:?}"); /// let m = r.unwrap(); /// assert_eq!(m.get_one::("config").unwrap(), "file"); /// assert!(m.get_flag("f")); @@ -1265,6 +1285,8 @@ impl Command { /// Disables the `help` [`subcommand`]. /// + /// **NOTE:** This choice is propagated to all child subcommands. + /// /// # Examples /// /// ```rust @@ -1885,21 +1907,15 @@ impl Command { #[inline] #[must_use] - pub(crate) fn setting(mut self, setting: F) -> Self - where - F: Into, - { - self.settings.insert(setting.into()); + pub(crate) fn setting(mut self, setting: AppSettings) -> Self { + self.settings.set(setting); self } #[inline] #[must_use] - pub(crate) fn unset_setting(mut self, setting: F) -> Self - where - F: Into, - { - self.settings.remove(setting.into()); + pub(crate) fn unset_setting(mut self, setting: AppSettings) -> Self { + self.settings.unset(setting); self } @@ -2576,13 +2592,13 @@ impl Command { /// Set the placement of this subcommand within the help. /// - /// Subcommands with a lower value will be displayed first in the help message. Subcommands - /// with duplicate display orders will be displayed in order they are defined. - /// - /// This is helpful when one would like to emphasize frequently used subcommands, or prioritize - /// those towards the top of the list. + /// Subcommands with a lower value will be displayed first in the help message. + /// Those with the same display order will be sorted. /// - /// **NOTE:** The default is 999 for all subcommands. + /// `Command`s are automatically assigned a display order based on the order they are added to + /// their parent [`Command`]. + /// Overriding this is helpful when the order commands are added in isn't the same as the + /// display order, whether in one-off cases or to automatically sort commands. /// /// # Examples /// @@ -2591,17 +2607,11 @@ impl Command { /// # use clap_builder as clap; /// # use clap::{Command, }; /// let m = Command::new("cust-ord") - /// .subcommand(Command::new("alpha") // typically subcommands are grouped - /// // alphabetically by name. Subcommands - /// // without a display_order have a value of - /// // 999 and are displayed alphabetically with - /// // all other 999 subcommands - /// .about("Some help and text")) /// .subcommand(Command::new("beta") - /// .display_order(1) // In order to force this subcommand to appear *first* - /// // all we have to do is give it a value lower than 999. - /// // Any other subcommands with a value of 1 will be displayed - /// // alphabetically with this one...then 2 values, then 3, etc. + /// .display_order(0) // Sort + /// .about("Some help and text")) + /// .subcommand(Command::new("alpha") + /// .display_order(0) // Sort /// .about("I should be first!")) /// .get_matches_from(vec![ /// "cust-ord", "--help" @@ -2617,8 +2627,9 @@ impl Command { /// Usage: cust-ord [OPTIONS] /// /// Commands: - /// beta I should be first! - /// alpha Some help and text + /// alpha I should be first! + /// beta Some help and text + /// help Print help for the subcommand(s) /// /// Options: /// -h, --help Print help @@ -3697,7 +3708,7 @@ impl Command { /// let cmd = clap::Command::new("raw") /// .external_subcommand_value_parser(clap::value_parser!(String)); /// let value_parser = cmd.get_external_subcommand_value_parser(); - /// println!("{:?}", value_parser); + /// println!("{value_parser:?}"); /// ``` pub fn get_external_subcommand_value_parser(&self) -> Option<&super::ValueParser> { if !self.is_allow_external_subcommands_set() { @@ -3793,8 +3804,8 @@ impl Command { // do the real parsing let mut parser = Parser::new(self); if let Err(error) = parser.get_matches_with(&mut matcher, raw_args, args_cursor) { - if self.is_set(AppSettings::IgnoreErrors) { - debug!("Command::_do_parse: ignoring error: {}", error); + if self.is_set(AppSettings::IgnoreErrors) && error.use_stderr() { + debug!("Command::_do_parse: ignoring error: {error}"); } else { return Err(error); } @@ -3827,30 +3838,30 @@ impl Command { pub(crate) fn _build_self(&mut self, expand_help_tree: bool) { debug!("Command::_build: name={:?}", self.get_name()); if !self.settings.is_set(AppSettings::Built) { + if let Some(deferred) = self.deferred.take() { + *self = (deferred)(std::mem::take(self)); + } + // Make sure all the globally set flags apply to us as well self.settings = self.settings | self.g_settings; if self.is_multicall_set() { - self.settings.insert(AppSettings::SubcommandRequired.into()); - self.settings.insert(AppSettings::DisableHelpFlag.into()); - self.settings.insert(AppSettings::DisableVersionFlag.into()); + self.settings.set(AppSettings::SubcommandRequired); + self.settings.set(AppSettings::DisableHelpFlag); + self.settings.set(AppSettings::DisableVersionFlag); } if !cfg!(feature = "help") && self.get_override_help().is_none() { - self.settings.insert(AppSettings::DisableHelpFlag.into()); - self.settings - .insert(AppSettings::DisableHelpSubcommand.into()); + self.settings.set(AppSettings::DisableHelpFlag); + self.settings.set(AppSettings::DisableHelpSubcommand); } if self.is_set(AppSettings::ArgsNegateSubcommands) { - self.settings - .insert(AppSettings::SubcommandsNegateReqs.into()); + self.settings.set(AppSettings::SubcommandsNegateReqs); } if self.external_value_parser.is_some() { - self.settings - .insert(AppSettings::AllowExternalSubcommands.into()); + self.settings.set(AppSettings::AllowExternalSubcommands); } if !self.has_subcommands() { - self.settings - .insert(AppSettings::DisableHelpSubcommand.into()); + self.settings.set(AppSettings::DisableHelpSubcommand); } self._propagate(); @@ -3903,14 +3914,13 @@ impl Command { let is_allow_negative_numbers_set = self.is_allow_negative_numbers_set(); for arg in self.args.args_mut() { if is_allow_hyphen_values_set && arg.is_takes_value_set() { - arg.settings.insert(ArgSettings::AllowHyphenValues.into()); + arg.settings.set(ArgSettings::AllowHyphenValues); } if is_allow_negative_numbers_set && arg.is_takes_value_set() { - arg.settings - .insert(ArgSettings::AllowNegativeNumbers.into()); + arg.settings.set(ArgSettings::AllowNegativeNumbers); } if is_trailing_var_arg_set && arg.get_index() == Some(highest_idx) { - arg.settings.insert(ArgSettings::TrailingVarArg.into()); + arg.settings.set(ArgSettings::TrailingVarArg); } } } @@ -4033,7 +4043,7 @@ impl Command { } .to_owned(); - for mut sc in &mut self.subcommands { + for sc in &mut self.subcommands { debug!("Command::_build_bin_names:iter: bin_name set..."); if sc.usage_name.is_none() { @@ -4438,7 +4448,7 @@ impl Command { /// Iterate through the groups this arg is member of. pub(crate) fn groups_for_arg<'a>(&'a self, arg: &Id) -> impl Iterator + 'a { - debug!("Command::groups_for_arg: id={:?}", arg); + debug!("Command::groups_for_arg: id={arg:?}"); let arg = arg.clone(); self.groups .iter() @@ -4478,7 +4488,7 @@ impl Command { } pub(crate) fn unroll_args_in_group(&self, group: &Id) -> Vec { - debug!("Command::unroll_args_in_group: group={:?}", group); + debug!("Command::unroll_args_in_group: group={group:?}"); let mut g_vec = vec![group]; let mut args = vec![]; @@ -4491,7 +4501,7 @@ impl Command { .args .iter() { - debug!("Command::unroll_args_in_group:iter: entity={:?}", n); + debug!("Command::unroll_args_in_group:iter: entity={n:?}"); if !args.contains(n) { if self.find(n).is_some() { debug!("Command::unroll_args_in_group:iter: this is an arg"); @@ -4655,6 +4665,7 @@ impl Default for Command { subcommand_heading: Default::default(), external_value_parser: Default::default(), long_help_exists: false, + deferred: None, app_ext: Default::default(), } } -- cgit v1.2.3