logo

Struct clap::ArgGroup[][src]

pub struct ArgGroup<'help> { /* fields omitted */ }
Expand description

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 present respectively.

Perhaps the most common use of ArgGroups 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 ArgGroups 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.

let result = App::new("app")
    .arg(arg!(--"set-ver" <ver> "set the version manually").required(false))
    .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!["app", "--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

let result = App::new("app")
    .arg(arg!(--"set-ver" <ver> "set the version manually").required(false))
    .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!["app", "--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.is_present("vers"));
// we could also alternatively check each arg individually (not shown here)

Implementations

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
ArgGroup::new("config")
Examples found in repository
examples/tutorial_builder/04_03_relations.rs (line 13)
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
fn main() {
    // Create application like normal
    let matches = app_from_crate!()
        // Add the version arguments
        .arg(arg!(--"set-ver" <VER> "set version manually").required(false))
        .arg(arg!(--major         "auto inc major"))
        .arg(arg!(--minor         "auto inc minor"))
        .arg(arg!(--patch         "auto inc patch"))
        // Create a group, make it required, and add the above arguments
        .group(
            ArgGroup::new("vers")
                .required(true)
                .args(&["set-ver", "major", "minor", "patch"]),
        )
        // Arguments can also be added to a group individually, these two arguments
        // are part of the "input" group which is not required
        .arg(arg!([INPUT_FILE] "some regular input").group("input"))
        .arg(
            arg!(--"spec-in" <SPEC_IN> "some special input argument")
                .required(false)
                .group("input"),
        )
        // Now let's assume we have a -c [config] argument which requires one of
        // (but **not** both) the "input" arguments
        .arg(arg!(config: -c <CONFIG>).required(false).requires("input"))
        .get_matches();

    // Let's assume the old version 1.2.3
    let mut major = 1;
    let mut minor = 2;
    let mut patch = 3;

    // See if --set-ver was used to set the version manually
    let version = if let Some(ver) = matches.value_of("set-ver") {
        ver.to_string()
    } else {
        // Increment the one requested (in a real program, we'd reset the lower numbers)
        let (maj, min, pat) = (
            matches.is_present("major"),
            matches.is_present("minor"),
            matches.is_present("patch"),
        );
        match (maj, min, pat) {
            (true, _, _) => major += 1,
            (_, true, _) => minor += 1,
            (_, _, true) => patch += 1,
            _ => unreachable!(),
        };
        format!("{}.{}.{}", major, minor, patch)
    };

    println!("Version: {}", version);

    // Check for usage of -c
    if matches.is_present("config") {
        let input = matches
            .value_of("INPUT_FILE")
            .unwrap_or_else(|| matches.value_of("spec-in").unwrap());
        println!(
            "Doing work using input {} and config {}",
            input,
            matches.value_of("config").unwrap()
        );
    }
}

Sets the group name.

Examples
ArgGroup::default().name("config")

Adds an argument to this group by name

Examples
let m = App::new("myprog")
    .arg(Arg::new("flag")
        .short('f'))
    .arg(Arg::new("color")
        .short('c'))
    .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.is_present("req_flags"));
// but we can also check individually if needed
assert!(m.is_present("flag"));

Adds multiple arguments to this group by name

Examples
let m = App::new("myprog")
    .arg(Arg::new("flag")
        .short('f'))
    .arg(Arg::new("color")
        .short('c'))
    .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.is_present("req_flags"));
// but we can also check individually if needed
assert!(m.is_present("flag"));
Examples found in repository
examples/tutorial_builder/04_03_relations.rs (line 15)
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
fn main() {
    // Create application like normal
    let matches = app_from_crate!()
        // Add the version arguments
        .arg(arg!(--"set-ver" <VER> "set version manually").required(false))
        .arg(arg!(--major         "auto inc major"))
        .arg(arg!(--minor         "auto inc minor"))
        .arg(arg!(--patch         "auto inc patch"))
        // Create a group, make it required, and add the above arguments
        .group(
            ArgGroup::new("vers")
                .required(true)
                .args(&["set-ver", "major", "minor", "patch"]),
        )
        // Arguments can also be added to a group individually, these two arguments
        // are part of the "input" group which is not required
        .arg(arg!([INPUT_FILE] "some regular input").group("input"))
        .arg(
            arg!(--"spec-in" <SPEC_IN> "some special input argument")
                .required(false)
                .group("input"),
        )
        // Now let's assume we have a -c [config] argument which requires one of
        // (but **not** both) the "input" arguments
        .arg(arg!(config: -c <CONFIG>).required(false).requires("input"))
        .get_matches();

    // Let's assume the old version 1.2.3
    let mut major = 1;
    let mut minor = 2;
    let mut patch = 3;

    // See if --set-ver was used to set the version manually
    let version = if let Some(ver) = matches.value_of("set-ver") {
        ver.to_string()
    } else {
        // Increment the one requested (in a real program, we'd reset the lower numbers)
        let (maj, min, pat) = (
            matches.is_present("major"),
            matches.is_present("minor"),
            matches.is_present("patch"),
        );
        match (maj, min, pat) {
            (true, _, _) => major += 1,
            (_, true, _) => minor += 1,
            (_, _, true) => patch += 1,
            _ => unreachable!(),
        };
        format!("{}.{}.{}", major, minor, patch)
    };

    println!("Version: {}", version);

    // Check for usage of -c
    if matches.is_present("config") {
        let input = matches
            .value_of("INPUT_FILE")
            .unwrap_or_else(|| matches.value_of("spec-in").unwrap());
        println!(
            "Doing work using input {} and config {}",
            input,
            matches.value_of("config").unwrap()
        );
    }
}

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

let m = App::new("myprog")
    .arg(Arg::new("flag")
        .short('f'))
    .arg(Arg::new("color")
        .short('c'))
    .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.is_present("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.

let result = App::new("myprog")
    .arg(Arg::new("flag")
        .short('f'))
    .arg(Arg::new("color")
        .short('c'))
    .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);

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 App / 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.“

NOTE: An argument is considered present when there is a Arg::default_value

Examples
let result = App::new("myprog")
    .arg(Arg::new("flag")
        .short('f'))
    .arg(Arg::new("color")
        .short('c'))
    .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);
Examples found in repository
examples/tutorial_builder/04_03_relations.rs (line 14)
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
fn main() {
    // Create application like normal
    let matches = app_from_crate!()
        // Add the version arguments
        .arg(arg!(--"set-ver" <VER> "set version manually").required(false))
        .arg(arg!(--major         "auto inc major"))
        .arg(arg!(--minor         "auto inc minor"))
        .arg(arg!(--patch         "auto inc patch"))
        // Create a group, make it required, and add the above arguments
        .group(
            ArgGroup::new("vers")
                .required(true)
                .args(&["set-ver", "major", "minor", "patch"]),
        )
        // Arguments can also be added to a group individually, these two arguments
        // are part of the "input" group which is not required
        .arg(arg!([INPUT_FILE] "some regular input").group("input"))
        .arg(
            arg!(--"spec-in" <SPEC_IN> "some special input argument")
                .required(false)
                .group("input"),
        )
        // Now let's assume we have a -c [config] argument which requires one of
        // (but **not** both) the "input" arguments
        .arg(arg!(config: -c <CONFIG>).required(false).requires("input"))
        .get_matches();

    // Let's assume the old version 1.2.3
    let mut major = 1;
    let mut minor = 2;
    let mut patch = 3;

    // See if --set-ver was used to set the version manually
    let version = if let Some(ver) = matches.value_of("set-ver") {
        ver.to_string()
    } else {
        // Increment the one requested (in a real program, we'd reset the lower numbers)
        let (maj, min, pat) = (
            matches.is_present("major"),
            matches.is_present("minor"),
            matches.is_present("patch"),
        );
        match (maj, min, pat) {
            (true, _, _) => major += 1,
            (_, true, _) => minor += 1,
            (_, _, true) => patch += 1,
            _ => unreachable!(),
        };
        format!("{}.{}.{}", major, minor, patch)
    };

    println!("Version: {}", version);

    // Check for usage of -c
    if matches.is_present("config") {
        let input = matches
            .value_of("INPUT_FILE")
            .unwrap_or_else(|| matches.value_of("spec-in").unwrap());
        println!(
            "Doing work using input {} and config {}",
            input,
            matches.value_of("config").unwrap()
        );
    }
}

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: An argument is considered present when there is a Arg::default_value

NOTE: The name provided may be an argument or group name

Examples
let result = App::new("myprog")
    .arg(Arg::new("flag")
        .short('f'))
    .arg(Arg::new("color")
        .short('c'))
    .arg(Arg::new("debug")
        .short('d'))
    .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);

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

NOTE: An argument is considered present when there is a Arg::default_value

Examples
let result = App::new("myprog")
    .arg(Arg::new("flag")
        .short('f'))
    .arg(Arg::new("color")
        .short('c'))
    .arg(Arg::new("debug")
        .short('d'))
    .arg(Arg::new("verb")
        .short('v'))
    .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);

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

NOTE: An argument is considered present when there is a Arg::default_value

Examples
let result = App::new("myprog")
    .arg(Arg::new("flag")
        .short('f'))
    .arg(Arg::new("color")
        .short('c'))
    .arg(Arg::new("debug")
        .short('d'))
    .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);

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

NOTE: An argument is considered present when there is a Arg::default_value

Examples
let result = App::new("myprog")
    .arg(Arg::new("flag")
        .short('f'))
    .arg(Arg::new("color")
        .short('c'))
    .arg(Arg::new("debug")
        .short('d'))
    .arg(Arg::new("verb")
        .short('v'))
    .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);
👎 Deprecated since 3.0.0:

Replaced with ArgGroup::new

Deprecated, replaced with ArgGroup::new

👎 Deprecated since 3.0.0:

Maybe clap::Parser would fit your use case? (Issue #3087)

This is supported on crate feature yaml only.

Deprecated in Issue #3087, maybe clap::Parser would fit your use case?

Trait Implementations

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

Formats the value using the given formatter. Read more

Returns the “default value” for a type. Read more

Performs the conversion.

Deprecated in Issue #3087, maybe clap::Parser would fit your use case?

Deprecated in Issue #3087, maybe clap::Parser would fit your use case?

This method tests for self and other values to be equal, and is used by ==. Read more

This method tests for !=.

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Compare self to key and return true if they are equal.

Performs the conversion.

Performs the conversion.

The resulting type after obtaining ownership.

Creates owned data from borrowed data, usually by cloning. Read more

🔬 This is a nightly-only experimental API. (toowned_clone_into)

Uses borrowed data to replace owned data, usually by cloning. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.