| // Internal |
| use crate::builder::IntoResettable; |
| use crate::util::Id; |
| |
| /// Family of related [arguments]. |
| /// |
| /// By placing arguments in a logical group, you can create easier requirement and |
| /// exclusion rules instead of having to list each argument individually, or when you want a rule |
| /// to apply "any but not all" arguments. |
| /// |
| /// For instance, you can make an entire `ArgGroup` required. If [`ArgGroup::multiple(true)`] is |
| /// set, this means that at least one argument from that group must be present. If |
| /// [`ArgGroup::multiple(false)`] is set (the default), one and *only* one must be present. |
| /// |
| /// You can also do things such as name an entire `ArgGroup` as a [conflict] or [requirement] for |
| /// another argument, meaning any of the arguments that belong to that group will cause a failure |
| /// if present, or must be present respectively. |
| /// |
| /// Perhaps the most common use of `ArgGroup`s is to require one and *only* one argument to be |
| /// present out of a given set. Imagine that you had multiple arguments, and you want one of them |
| /// to be required, but making all of them required isn't feasible because perhaps they conflict |
| /// with each other. For example, lets say that you were building an application where one could |
| /// set a given version number by supplying a string with an option argument, i.e. |
| /// `--set-ver v1.2.3`, you also wanted to support automatically using a previous version number |
| /// and simply incrementing one of the three numbers. So you create three flags `--major`, |
| /// `--minor`, and `--patch`. All of these arguments shouldn't be used at one time but you want to |
| /// specify that *at least one* of them is used. For this, you can create a group. |
| /// |
| /// Finally, you may use `ArgGroup`s to pull a value from a group of arguments when you don't care |
| /// exactly which argument was actually used at runtime. |
| /// |
| /// # Examples |
| /// |
| /// The following example demonstrates using an `ArgGroup` to ensure that one, and only one, of |
| /// the arguments from the specified group is present at runtime. |
| /// |
| /// ```rust |
| /// # use clap_builder as clap; |
| /// # use clap::{Command, arg, ArgGroup, error::ErrorKind}; |
| /// let result = Command::new("cmd") |
| /// .arg(arg!(--"set-ver" <ver> "set the version manually")) |
| /// .arg(arg!(--major "auto increase major")) |
| /// .arg(arg!(--minor "auto increase minor")) |
| /// .arg(arg!(--patch "auto increase patch")) |
| /// .group(ArgGroup::new("vers") |
| /// .args(["set-ver", "major", "minor", "patch"]) |
| /// .required(true)) |
| /// .try_get_matches_from(vec!["cmd", "--major", "--patch"]); |
| /// // Because we used two args in the group it's an error |
| /// assert!(result.is_err()); |
| /// let err = result.unwrap_err(); |
| /// assert_eq!(err.kind(), ErrorKind::ArgumentConflict); |
| /// ``` |
| /// |
| /// This next example shows a passing parse of the same scenario |
| /// ```rust |
| /// # use clap_builder as clap; |
| /// # use clap::{Command, arg, ArgGroup, Id}; |
| /// let result = Command::new("cmd") |
| /// .arg(arg!(--"set-ver" <ver> "set the version manually")) |
| /// .arg(arg!(--major "auto increase major")) |
| /// .arg(arg!(--minor "auto increase minor")) |
| /// .arg(arg!(--patch "auto increase patch")) |
| /// .group(ArgGroup::new("vers") |
| /// .args(["set-ver", "major", "minor","patch"]) |
| /// .required(true)) |
| /// .try_get_matches_from(vec!["cmd", "--major"]); |
| /// assert!(result.is_ok()); |
| /// let matches = result.unwrap(); |
| /// // We may not know which of the args was used, so we can test for the group... |
| /// assert!(matches.contains_id("vers")); |
| /// // We can also ask the group which arg was used |
| /// assert_eq!(matches |
| /// .get_one::<Id>("vers") |
| /// .expect("`vers` is required") |
| /// .as_str(), |
| /// "major" |
| /// ); |
| /// // we could also alternatively check each arg individually (not shown here) |
| /// ``` |
| /// [`ArgGroup::multiple(true)`]: ArgGroup::multiple() |
| /// |
| /// [`ArgGroup::multiple(false)`]: ArgGroup::multiple() |
| /// [arguments]: crate::Arg |
| /// [conflict]: crate::Arg::conflicts_with() |
| /// [requirement]: crate::Arg::requires() |
| #[derive(Default, Clone, Debug, PartialEq, Eq)] |
| pub struct ArgGroup { |
| pub(crate) id: Id, |
| pub(crate) args: Vec<Id>, |
| pub(crate) required: bool, |
| pub(crate) requires: Vec<Id>, |
| pub(crate) conflicts: Vec<Id>, |
| pub(crate) multiple: bool, |
| } |
| |
| /// # Builder |
| impl ArgGroup { |
| /// Create a `ArgGroup` using a unique name. |
| /// |
| /// The name will be used to get values from the group or refer to the group inside of conflict |
| /// and requirement rules. |
| /// |
| /// # Examples |
| /// |
| /// ```rust |
| /// # use clap_builder as clap; |
| /// # use clap::{Command, ArgGroup}; |
| /// ArgGroup::new("config") |
| /// # ; |
| /// ``` |
| pub fn new(id: impl Into<Id>) -> Self { |
| ArgGroup::default().id(id) |
| } |
| |
| /// Sets the group name. |
| /// |
| /// # Examples |
| /// |
| /// ```rust |
| /// # use clap_builder as clap; |
| /// # use clap::{Command, ArgGroup}; |
| /// ArgGroup::default().id("config") |
| /// # ; |
| /// ``` |
| #[must_use] |
| pub fn id(mut self, id: impl Into<Id>) -> Self { |
| self.id = id.into(); |
| self |
| } |
| |
| /// Adds an [argument] to this group by name |
| /// |
| /// # Examples |
| /// |
| /// ```rust |
| /// # use clap_builder as clap; |
| /// # use clap::{Command, Arg, ArgGroup, ArgAction}; |
| /// let m = Command::new("myprog") |
| /// .arg(Arg::new("flag") |
| /// .short('f') |
| /// .action(ArgAction::SetTrue)) |
| /// .arg(Arg::new("color") |
| /// .short('c') |
| /// .action(ArgAction::SetTrue)) |
| /// .group(ArgGroup::new("req_flags") |
| /// .arg("flag") |
| /// .arg("color")) |
| /// .get_matches_from(vec!["myprog", "-f"]); |
| /// // maybe we don't know which of the two flags was used... |
| /// assert!(m.contains_id("req_flags")); |
| /// // but we can also check individually if needed |
| /// assert!(m.contains_id("flag")); |
| /// ``` |
| /// [argument]: crate::Arg |
| #[must_use] |
| pub fn arg(mut self, arg_id: impl IntoResettable<Id>) -> Self { |
| if let Some(arg_id) = arg_id.into_resettable().into_option() { |
| self.args.push(arg_id); |
| } else { |
| self.args.clear(); |
| } |
| self |
| } |
| |
| /// Adds multiple [arguments] to this group by name |
| /// |
| /// # Examples |
| /// |
| /// ```rust |
| /// # use clap_builder as clap; |
| /// # use clap::{Command, Arg, ArgGroup, ArgAction}; |
| /// let m = Command::new("myprog") |
| /// .arg(Arg::new("flag") |
| /// .short('f') |
| /// .action(ArgAction::SetTrue)) |
| /// .arg(Arg::new("color") |
| /// .short('c') |
| /// .action(ArgAction::SetTrue)) |
| /// .group(ArgGroup::new("req_flags") |
| /// .args(["flag", "color"])) |
| /// .get_matches_from(vec!["myprog", "-f"]); |
| /// // maybe we don't know which of the two flags was used... |
| /// assert!(m.contains_id("req_flags")); |
| /// // but we can also check individually if needed |
| /// assert!(m.contains_id("flag")); |
| /// ``` |
| /// [arguments]: crate::Arg |
| #[must_use] |
| pub fn args(mut self, ns: impl IntoIterator<Item = impl Into<Id>>) -> Self { |
| for n in ns { |
| self = self.arg(n); |
| } |
| self |
| } |
| |
| /// Getters for all args. It will return a vector of `Id` |
| /// |
| /// # Example |
| /// |
| /// ```rust |
| /// # use clap_builder as clap; |
| /// # use clap::{ArgGroup}; |
| /// let args: Vec<&str> = vec!["a1".into(), "a4".into()]; |
| /// let grp = ArgGroup::new("program").args(&args); |
| /// |
| /// for (pos, arg) in grp.get_args().enumerate() { |
| /// assert_eq!(*arg, args[pos]); |
| /// } |
| /// ``` |
| pub fn get_args(&self) -> impl Iterator<Item = &Id> { |
| self.args.iter() |
| } |
| |
| /// Allows more than one of the [`Arg`]s in this group to be used. (Default: `false`) |
| /// |
| /// # Examples |
| /// |
| /// Notice in this example we use *both* the `-f` and `-c` flags which are both part of the |
| /// group |
| /// |
| /// ```rust |
| /// # use clap_builder as clap; |
| /// # use clap::{Command, Arg, ArgGroup, ArgAction}; |
| /// let m = Command::new("myprog") |
| /// .arg(Arg::new("flag") |
| /// .short('f') |
| /// .action(ArgAction::SetTrue)) |
| /// .arg(Arg::new("color") |
| /// .short('c') |
| /// .action(ArgAction::SetTrue)) |
| /// .group(ArgGroup::new("req_flags") |
| /// .args(["flag", "color"]) |
| /// .multiple(true)) |
| /// .get_matches_from(vec!["myprog", "-f", "-c"]); |
| /// // maybe we don't know which of the two flags was used... |
| /// assert!(m.contains_id("req_flags")); |
| /// ``` |
| /// In this next example, we show the default behavior (i.e. `multiple(false)) which will throw |
| /// an error if more than one of the args in the group was used. |
| /// |
| /// ```rust |
| /// # use clap_builder as clap; |
| /// # use clap::{Command, Arg, ArgGroup, error::ErrorKind, ArgAction}; |
| /// let result = Command::new("myprog") |
| /// .arg(Arg::new("flag") |
| /// .short('f') |
| /// .action(ArgAction::SetTrue)) |
| /// .arg(Arg::new("color") |
| /// .short('c') |
| /// .action(ArgAction::SetTrue)) |
| /// .group(ArgGroup::new("req_flags") |
| /// .args(["flag", "color"])) |
| /// .try_get_matches_from(vec!["myprog", "-f", "-c"]); |
| /// // Because we used both args in the group it's an error |
| /// assert!(result.is_err()); |
| /// let err = result.unwrap_err(); |
| /// assert_eq!(err.kind(), ErrorKind::ArgumentConflict); |
| /// ``` |
| /// |
| /// [`Arg`]: crate::Arg |
| #[inline] |
| #[must_use] |
| pub fn multiple(mut self, yes: bool) -> Self { |
| self.multiple = yes; |
| self |
| } |
| |
| /// Return true if the group allows more than one of the arguments |
| /// in this group to be used. (Default: `false`) |
| /// |
| /// # Example |
| /// |
| /// ```rust |
| /// # use clap_builder as clap; |
| /// # use clap::{ArgGroup}; |
| /// let mut group = ArgGroup::new("myprog") |
| /// .args(["f", "c"]) |
| /// .multiple(true); |
| /// |
| /// assert!(group.is_multiple()); |
| /// ``` |
| pub fn is_multiple(&mut self) -> bool { |
| self.multiple |
| } |
| |
| /// Require an argument from the group to be present when parsing. |
| /// |
| /// This is unless conflicting with another argument. A required group will be displayed in |
| /// the usage string of the application in the format `<arg|arg2|arg3>`. |
| /// |
| /// **NOTE:** This setting only applies to the current [`Command`] / [`Subcommand`]s, and not |
| /// globally. |
| /// |
| /// **NOTE:** By default, [`ArgGroup::multiple`] is set to `false` which when combined with |
| /// `ArgGroup::required(true)` states, "One and *only one* arg must be used from this group. |
| /// Use of more than one arg is an error." Vice setting `ArgGroup::multiple(true)` which |
| /// states, '*At least* one arg from this group must be used. Using multiple is OK." |
| /// |
| /// # Examples |
| /// |
| /// ```rust |
| /// # use clap_builder as clap; |
| /// # use clap::{Command, Arg, ArgGroup, error::ErrorKind, ArgAction}; |
| /// let result = Command::new("myprog") |
| /// .arg(Arg::new("flag") |
| /// .short('f') |
| /// .action(ArgAction::SetTrue)) |
| /// .arg(Arg::new("color") |
| /// .short('c') |
| /// .action(ArgAction::SetTrue)) |
| /// .group(ArgGroup::new("req_flags") |
| /// .args(["flag", "color"]) |
| /// .required(true)) |
| /// .try_get_matches_from(vec!["myprog"]); |
| /// // Because we didn't use any of the args in the group, it's an error |
| /// assert!(result.is_err()); |
| /// let err = result.unwrap_err(); |
| /// assert_eq!(err.kind(), ErrorKind::MissingRequiredArgument); |
| /// ``` |
| /// |
| /// [`Subcommand`]: crate::Subcommand |
| /// [`ArgGroup::multiple`]: ArgGroup::multiple() |
| /// [`Command`]: crate::Command |
| #[inline] |
| #[must_use] |
| pub fn required(mut self, yes: bool) -> Self { |
| self.required = yes; |
| self |
| } |
| |
| /// Specify an argument or group that must be present when this group is. |
| /// |
| /// This is not to be confused with a [required group]. Requirement rules function just like |
| /// [argument requirement rules], you can name other arguments or groups that must be present |
| /// when any one of the arguments from this group is used. |
| /// |
| /// **NOTE:** The name provided may be an argument or group name |
| /// |
| /// # Examples |
| /// |
| /// ```rust |
| /// # use clap_builder as clap; |
| /// # use clap::{Command, Arg, ArgGroup, error::ErrorKind, ArgAction}; |
| /// let result = Command::new("myprog") |
| /// .arg(Arg::new("flag") |
| /// .short('f') |
| /// .action(ArgAction::SetTrue)) |
| /// .arg(Arg::new("color") |
| /// .short('c') |
| /// .action(ArgAction::SetTrue)) |
| /// .arg(Arg::new("debug") |
| /// .short('d') |
| /// .action(ArgAction::SetTrue)) |
| /// .group(ArgGroup::new("req_flags") |
| /// .args(["flag", "color"]) |
| /// .requires("debug")) |
| /// .try_get_matches_from(vec!["myprog", "-c"]); |
| /// // because we used an arg from the group, and the group requires "-d" to be used, it's an |
| /// // error |
| /// assert!(result.is_err()); |
| /// let err = result.unwrap_err(); |
| /// assert_eq!(err.kind(), ErrorKind::MissingRequiredArgument); |
| /// ``` |
| /// [required group]: ArgGroup::required() |
| /// [argument requirement rules]: crate::Arg::requires() |
| #[must_use] |
| pub fn requires(mut self, id: impl IntoResettable<Id>) -> Self { |
| if let Some(id) = id.into_resettable().into_option() { |
| self.requires.push(id); |
| } else { |
| self.requires.clear(); |
| } |
| self |
| } |
| |
| /// Specify arguments or groups that must be present when this group is. |
| /// |
| /// This is not to be confused with a [required group]. Requirement rules function just like |
| /// [argument requirement rules], you can name other arguments or groups that must be present |
| /// when one of the arguments from this group is used. |
| /// |
| /// **NOTE:** The names provided may be an argument or group name |
| /// |
| /// # Examples |
| /// |
| /// ```rust |
| /// # use clap_builder as clap; |
| /// # use clap::{Command, Arg, ArgGroup, error::ErrorKind, ArgAction}; |
| /// let result = Command::new("myprog") |
| /// .arg(Arg::new("flag") |
| /// .short('f') |
| /// .action(ArgAction::SetTrue)) |
| /// .arg(Arg::new("color") |
| /// .short('c') |
| /// .action(ArgAction::SetTrue)) |
| /// .arg(Arg::new("debug") |
| /// .short('d') |
| /// .action(ArgAction::SetTrue)) |
| /// .arg(Arg::new("verb") |
| /// .short('v') |
| /// .action(ArgAction::SetTrue)) |
| /// .group(ArgGroup::new("req_flags") |
| /// .args(["flag", "color"]) |
| /// .requires_all(["debug", "verb"])) |
| /// .try_get_matches_from(vec!["myprog", "-c", "-d"]); |
| /// // because we used an arg from the group, and the group requires "-d" and "-v" to be used, |
| /// // yet we only used "-d" it's an error |
| /// assert!(result.is_err()); |
| /// let err = result.unwrap_err(); |
| /// assert_eq!(err.kind(), ErrorKind::MissingRequiredArgument); |
| /// ``` |
| /// [required group]: ArgGroup::required() |
| /// [argument requirement rules]: crate::Arg::requires_ifs() |
| #[must_use] |
| pub fn requires_all(mut self, ns: impl IntoIterator<Item = impl Into<Id>>) -> Self { |
| for n in ns { |
| self = self.requires(n); |
| } |
| self |
| } |
| |
| /// Specify an argument or group that must **not** be present when this group is. |
| /// |
| /// Exclusion (aka conflict) rules function just like [argument exclusion rules], you can name |
| /// other arguments or groups that must *not* be present when one of the arguments from this |
| /// group are used. |
| /// |
| /// **NOTE:** The name provided may be an argument, or group name |
| /// |
| /// # Examples |
| /// |
| /// ```rust |
| /// # use clap_builder as clap; |
| /// # use clap::{Command, Arg, ArgGroup, error::ErrorKind, ArgAction}; |
| /// let result = Command::new("myprog") |
| /// .arg(Arg::new("flag") |
| /// .short('f') |
| /// .action(ArgAction::SetTrue)) |
| /// .arg(Arg::new("color") |
| /// .short('c') |
| /// .action(ArgAction::SetTrue)) |
| /// .arg(Arg::new("debug") |
| /// .short('d') |
| /// .action(ArgAction::SetTrue)) |
| /// .group(ArgGroup::new("req_flags") |
| /// .args(["flag", "color"]) |
| /// .conflicts_with("debug")) |
| /// .try_get_matches_from(vec!["myprog", "-c", "-d"]); |
| /// // because we used an arg from the group, and the group conflicts with "-d", it's an error |
| /// assert!(result.is_err()); |
| /// let err = result.unwrap_err(); |
| /// assert_eq!(err.kind(), ErrorKind::ArgumentConflict); |
| /// ``` |
| /// [argument exclusion rules]: crate::Arg::conflicts_with() |
| #[must_use] |
| pub fn conflicts_with(mut self, id: impl IntoResettable<Id>) -> Self { |
| if let Some(id) = id.into_resettable().into_option() { |
| self.conflicts.push(id); |
| } else { |
| self.conflicts.clear(); |
| } |
| self |
| } |
| |
| /// Specify arguments or groups that must **not** be present when this group is. |
| /// |
| /// Exclusion rules function just like [argument exclusion rules], you can name other arguments |
| /// or groups that must *not* be present when one of the arguments from this group are used. |
| /// |
| /// **NOTE:** The names provided may be an argument, or group name |
| /// |
| /// # Examples |
| /// |
| /// ```rust |
| /// # use clap_builder as clap; |
| /// # use clap::{Command, Arg, ArgGroup, error::ErrorKind, ArgAction}; |
| /// let result = Command::new("myprog") |
| /// .arg(Arg::new("flag") |
| /// .short('f') |
| /// .action(ArgAction::SetTrue)) |
| /// .arg(Arg::new("color") |
| /// .short('c') |
| /// .action(ArgAction::SetTrue)) |
| /// .arg(Arg::new("debug") |
| /// .short('d') |
| /// .action(ArgAction::SetTrue)) |
| /// .arg(Arg::new("verb") |
| /// .short('v') |
| /// .action(ArgAction::SetTrue)) |
| /// .group(ArgGroup::new("req_flags") |
| /// .args(["flag", "color"]) |
| /// .conflicts_with_all(["debug", "verb"])) |
| /// .try_get_matches_from(vec!["myprog", "-c", "-v"]); |
| /// // because we used an arg from the group, and the group conflicts with either "-v" or "-d" |
| /// // it's an error |
| /// assert!(result.is_err()); |
| /// let err = result.unwrap_err(); |
| /// assert_eq!(err.kind(), ErrorKind::ArgumentConflict); |
| /// ``` |
| /// |
| /// [argument exclusion rules]: crate::Arg::conflicts_with_all() |
| #[must_use] |
| pub fn conflicts_with_all(mut self, ns: impl IntoIterator<Item = impl Into<Id>>) -> Self { |
| for n in ns { |
| self = self.conflicts_with(n); |
| } |
| self |
| } |
| } |
| |
| /// # Reflection |
| impl ArgGroup { |
| /// Get the name of the group |
| #[inline] |
| pub fn get_id(&self) -> &Id { |
| &self.id |
| } |
| |
| /// Reports whether [`ArgGroup::required`] is set |
| #[inline] |
| pub fn is_required_set(&self) -> bool { |
| self.required |
| } |
| } |
| |
| impl From<&'_ ArgGroup> for ArgGroup { |
| fn from(g: &ArgGroup) -> Self { |
| g.clone() |
| } |
| } |
| |
| #[cfg(test)] |
| mod test { |
| use super::*; |
| |
| #[test] |
| fn groups() { |
| let g = ArgGroup::new("test") |
| .arg("a1") |
| .arg("a4") |
| .args(["a2", "a3"]) |
| .required(true) |
| .conflicts_with("c1") |
| .conflicts_with_all(["c2", "c3"]) |
| .conflicts_with("c4") |
| .requires("r1") |
| .requires_all(["r2", "r3"]) |
| .requires("r4"); |
| |
| let args: Vec<Id> = vec!["a1".into(), "a4".into(), "a2".into(), "a3".into()]; |
| let reqs: Vec<Id> = vec!["r1".into(), "r2".into(), "r3".into(), "r4".into()]; |
| let confs: Vec<Id> = vec!["c1".into(), "c2".into(), "c3".into(), "c4".into()]; |
| |
| assert_eq!(g.args, args); |
| assert_eq!(g.requires, reqs); |
| assert_eq!(g.conflicts, confs); |
| } |
| |
| #[test] |
| fn test_from() { |
| let g = ArgGroup::new("test") |
| .arg("a1") |
| .arg("a4") |
| .args(["a2", "a3"]) |
| .required(true) |
| .conflicts_with("c1") |
| .conflicts_with_all(["c2", "c3"]) |
| .conflicts_with("c4") |
| .requires("r1") |
| .requires_all(["r2", "r3"]) |
| .requires("r4"); |
| |
| let args: Vec<Id> = vec!["a1".into(), "a4".into(), "a2".into(), "a3".into()]; |
| let reqs: Vec<Id> = vec!["r1".into(), "r2".into(), "r3".into(), "r4".into()]; |
| let confs: Vec<Id> = vec!["c1".into(), "c2".into(), "c3".into(), "c4".into()]; |
| |
| let g2 = ArgGroup::from(&g); |
| assert_eq!(g2.args, args); |
| assert_eq!(g2.requires, reqs); |
| assert_eq!(g2.conflicts, confs); |
| } |
| |
| // This test will *fail to compile* if ArgGroup is not Send + Sync |
| #[test] |
| fn arg_group_send_sync() { |
| fn foo<T: Send + Sync>(_: T) {} |
| foo(ArgGroup::new("test")) |
| } |
| |
| #[test] |
| fn arg_group_expose_is_multiple_helper() { |
| let args: Vec<Id> = vec!["a1".into(), "a4".into()]; |
| |
| let mut grp_multiple = ArgGroup::new("test_multiple").args(&args).multiple(true); |
| assert!(grp_multiple.is_multiple()); |
| |
| let mut grp_not_multiple = ArgGroup::new("test_multiple").args(&args).multiple(false); |
| assert!(!grp_not_multiple.is_multiple()); |
| } |
| |
| #[test] |
| fn arg_group_expose_get_args_helper() { |
| let args: Vec<Id> = vec!["a1".into(), "a4".into()]; |
| let grp = ArgGroup::new("program").args(&args); |
| |
| for (pos, arg) in grp.get_args().enumerate() { |
| assert_eq!(*arg, args[pos]); |
| } |
| } |
| } |
