Struct ArgGroup

pub struct ArgGroup { /* private fields */ }

Specifies a logical group of arguments

You can use this for

For visually grouping arguments in help, see instead [Arg::help_heading][crate::Arg::help_heading].

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.

# 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

# 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)

Implementations

impl ArgGroup

fn new(id: impl Into<Id>) -> Self

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

# use clap_builder as clap;
# use clap::{Command, ArgGroup};
ArgGroup::new("config")
# ;

fn id(self, id: impl Into<Id>) -> Self

Sets the group name.

Examples

# use clap_builder as clap;
# use clap::{Command, ArgGroup};
ArgGroup::default().id("config")
# ;

fn arg(self, arg_id: impl IntoResettable<Id>) -> Self

Adds an argument to this group by name

Examples

# 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"));

fn args(self, ns: impl IntoIterator<Item = impl Into<Id>>) -> Self

Adds multiple arguments to this group by name

Examples

# 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"));

fn get_args(&self) -> impl Iterator<Item = &Id>

Getters for all args. It will return a vector of Id

Example

# 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]);
}

fn multiple(self, yes: bool) -> Self

Allows more than one of the Args 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

# 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.

# 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);

fn is_multiple(&mut self) -> bool

Return true if the group allows more than one of the arguments in this group to be used. (Default: false)

Example

# use clap_builder as clap;
# use clap::{ArgGroup};
let mut group = ArgGroup::new("myprog")
    .args(["f", "c"])
    .multiple(true);

assert!(group.is_multiple());

fn required(self, yes: bool) -> Self

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 / Subcommands, 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

# 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);

fn requires(self, id: impl IntoResettable<Id>) -> 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

# 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);

fn requires_all(self, ns: impl IntoIterator<Item = impl Into<Id>>) -> 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

# 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);

fn conflicts_with(self, id: impl IntoResettable<Id>) -> 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

# 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);

fn conflicts_with_all(self, ns: impl IntoIterator<Item = impl Into<Id>>) -> 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

# 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);

impl ArgGroup

fn get_id(&self) -> &Id

Get the name of the group

fn is_required_set(&self) -> bool

Reports whether ArgGroup::required is set

Trait Implementations

impl Clone for ArgGroup

fn clone(&self) -> ArgGroup

impl Debug for ArgGroup

fn fmt(&self, f: &mut Formatter<'_>) -> Result

impl Default for ArgGroup

fn default() -> ArgGroup

impl Eq for ArgGroup

impl From<&ArgGroup> for ArgGroup

fn from(g: &ArgGroup) -> Self

impl PartialEq for ArgGroup

fn eq(&self, other: &ArgGroup) -> bool

impl StructuralPartialEq for ArgGroup

Auto Trait Implementations

impl Freeze for ArgGroup

impl RefUnwindSafe for ArgGroup

impl Send for ArgGroup

impl Sync for ArgGroup

impl Unpin for ArgGroup

impl UnsafeUnpin for ArgGroup

impl UnwindSafe for ArgGroup

Blanket Implementations

impl<T> Any for ArgGroup where T: 'static + ?Sized,

fn type_id(&self) -> TypeId

impl<T> Borrow<T> for ArgGroup where T: ?Sized,

fn borrow(&self) -> &T

impl<T> BorrowMut<T> for ArgGroup where T: ?Sized,

fn borrow_mut(&mut self) -> &mut T

impl<T> CloneToUninit for ArgGroup where T: Clone,

unsafe fn clone_to_uninit(&self, dest: *mut u8)

impl<T> From<T> for ArgGroup

fn from(t: T) -> T

Returns the argument unchanged.

impl<T> ToOwned for ArgGroup where T: Clone,

type Owned = T;
fn to_owned(&self) -> T
fn clone_into(&self, target: &mut T)

impl<T, U> Into<U> for ArgGroup where U: From<T>,

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of [From]<T> for U chooses to do.

impl<T, U> TryFrom<U> for ArgGroup where U: Into<T>,

type Error = Infallible;
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

impl<T, U> TryInto<U> for ArgGroup where U: TryFrom<T>,

type Error = <U as TryFrom<T>>::Error;
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>