# Struct clap::ArgGroup [−] [src]

    pub struct ArgGroup<'a> {
        // some fields omitted
    }

`ArgGroup`s are a family of related arguments and way for you to express, "Any of these 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, this means that one (and only one) argument from that group must be present. Using more than one argument from an `ArgGroup` causes a parsing failure.

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 `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 exaclty 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.

    App::new("app")
        .args_from_usage(
            "--set-ver [ver] 'set the version manually'
             --major         'auto increase major'
             --minor         'auto increase minor'
             --patch         'auto increase patch'")
        .group(ArgGroup::with_name("vers")
             .args(&["set-ver", "major", "minor","patch"])
             .required(true))

## Methods

### `impl<'a> ArgGroup<'a>`

#### `fn with_name(n: &'a str) -> Self`

Creates a new instance of `ArgGroup` using a unique string 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::with_name("config")

#### `fn arg(self, n: &'a str) -> Self`

Adds an argument to this group by name

# Examples

    let cfg_arg = Arg::with_name("config");
    // ...
    ArgGroup::with_name("files")
        .arg("config")

#### `fn args(self, ns: &[&'a str]) -> Self`

Adds multiple arguments to this group by name

# Examples

    let cfg_arg = Arg::with_name("config");
    let in_arg = Arg::with_name("input");
    // ...
    ArgGroup::with_name("files")
        .args(&["config", "input"])

#### `fn required(self, r: bool) -> Self`

Sets the group as required or not. A required group will be displayed in the usage string of the application in the format `[arg|arg2|arg3]`. A required `ArgGroup` simply states that one, and only one argument from this group must be present at runtime (unless conflicting with another argument).

NOTE: This setting only applies to the current `App` / `SubCommand`, and not globally.

# Examples

    let cfg_arg = Arg::with_name("config");
    let in_arg = Arg::with_name("input");
    // ...
    ArgGroup::with_name("cfg")
        .args(&["config", "input"])
        .required(true)

#### `fn requires(self, n: &'a str) -> Self`

Sets the requirement rules of this group. 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 name provided may be an argument, or group name

# Examples

    let cfg_arg = Arg::with_name("config");
    let in_arg = Arg::with_name("input");
    // ...
    ArgGroup::with_name("files")
        .args(&["config", "input"])
    // ...
    ArgGroup::with_name("other_group")
        .requires("files")

#### `fn requires_all(self, ns: &[&'a str]) -> Self`

Sets the requirement rules of this group. 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

    let cfg_arg = Arg::with_name("config");
    let in_arg = Arg::with_name("input");
    // ...
    ArgGroup::with_name("files")
        .args(&["config", "input"])
    // ...
    ArgGroup::with_name("other_group")
        .requires_all(&["config", "input"]) // No different than saying, .requires("files")

#### `fn conflicts_with(self, n: &'a str) -> Self`

Sets the exclusion rules of this group. 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

    let cfg_arg = Arg::with_name("config");
    let in_arg = Arg::with_name("input");
    // ...
    ArgGroup::with_name("files")
        .args(&["config", "input"])
    // ...
    ArgGroup::with_name("other_group")
        .conflicts_with("files")

#### `fn conflicts_with_all(self, ns: &[&'a str]) -> Self`

Sets the exclusion rules of this group. 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

    let cfg_arg = Arg::with_name("config");
    let in_arg = Arg::with_name("input");
    // ...
    ArgGroup::with_name("files")
        .args(&["config", "input"])
    // ...
    ArgGroup::with_name("other_group")
        .conflicts_with_all(&["files", "input"]) // same as saying, conflicts_with("files")

## Trait Implementations

### `impl<'a> Debug for ArgGroup<'a>`

#### `fn fmt(&self, f: &mut Formatter) -> Result`

### `impl<'a, 'z> From<&'z ArgGroup<'a>> for ArgGroup<'a>`

#### `fn from(g: &'z ArgGroup<'a>) -> Self`

### `impl<'a> Clone for ArgGroup<'a>`

#### `fn clone(&self) -> Self`

#### `fn clone_from(&mut self, source: &Self)`1.0.0

### Derived Implementations

### `impl<'a> Default for ArgGroup<'a>`

#### `fn default() -> ArgGroup<'a>`

# Help

## Keyboard Shortcuts

?
  Show this help dialog
S
  Focus the search field
⇤
  Move up in search results
⇥
  Move down in search results
⏎
  Go to active search result

## Search Tricks

Prefix searches with a type followed by a colon (e.g. `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g. `vec -> usize` or `* -> vec`)