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

    pub struct Arg<'n, 'l, 'h, 'g, 'p, 'r> {
        pub name: &'n str,
        pub short: Option<char>,
        pub long: Option<&'l str>,
        pub help: Option<&'h str>,
        pub required: bool,
        pub takes_value: bool,
        pub index: Option<u8>,
        pub multiple: bool,
        pub blacklist: Option<Vec<&'r str>>,
        pub possible_vals: Option<Vec<&'p str>>,
        pub requires: Option<Vec<&'r str>>,
        pub group: Option<&'g str>,
        pub val_names: Option<BTreeSet<&'n str>>,
        pub num_vals: Option<u8>,
        pub max_vals: Option<u8>,
        pub min_vals: Option<u8>,
        pub empty_vals: bool,
        pub global: bool,
        pub validator: Option<Rc<Fn(String) -> Result<(), String>>>,
        pub overrides: Option<Vec<&'r str>>,
        pub hidden: bool,
    }

The abstract representation of a command line argument used by the consumer of the library. Used to set all the options and relationships that define a valid argument for the program.

This struct is used by the library consumer and describes the command line arguments for their program. Then evaluates the settings the consumer provided and determines the concret argument type to use when parsing.

There are two methods for constructing `Arg`s, using the builder pattern and setting options manually, or using a usage string which is far less verbose. You can also use a combination of the two methods to achieve the best of both worlds.

**NOTE*: Fields of this struct are not meant to be used directly unless absolutely required. 99.9% of the tasks can be performed without accessing these fields directly.

# Examples

    // Using the traditional builder pattern and setting each option manually
    Arg::with_name("config")
          .short("c")
          .long("config")
          .takes_value(true)
          .help("Provides a config file to myprog")
    // Using a usage string (setting a similar argument to the one above)
    Arg::from_usage("-i --input=[input] 'Provides an input file to the program'")

## Fields

`name` | The unique name of the argument
`short` | The short version (i.e. single character) of the argument, no preceding `-` NOTE: `short` is mutually exclusive with `index`
`long` | The long version of the flag (i.e. word) without the preceding `--` NOTE: `long` is mutually exclusive with `index`
`help` | The string of text that will displayed to the user when the application's `help` text is displayed
`required` | If this is a required by default when using the command line program, e.g. a configuration file that's required for the program to function NOTE: required by default means it is required until mutually exclusive arguments are evaluated.
`takes_value` | Determines if this argument is an option (as opposed to flag or positional) and is mutually exclusive with `index` and `multiple`
`index` | The index of the argument. `index` is mutually exclusive with `takes_value` and `multiple`
`multiple` | Determines if multiple instances of the same flag are allowed. `multiple` is mutually exclusive with `index`. e.g. `-v -v -v` or `-vvv` or `--option foo --option bar`
`blacklist` | A list of names for other arguments that may not be used with this flag
`possible_vals` | A list of possible values for an option or positional argument
`requires` | A list of names of other arguments that are required to be used when this flag is used
`group` | A name of the group the argument belongs to
`val_names` | A set of names (ordered) for the values to be displayed with the help message
`num_vals` | The exact number of values to satisfy this argument
`max_vals` | The maximum number of values possible for this argument
`min_vals` | The minimum number of values possible to satisfy this argument
`empty_vals` | Specifies whether or not this argument accepts explicit empty values such as `--option ""`
`global` | Specifies whether or not this argument is global and should be propagated through all child subcommands
`validator` | A function used to check the validity of an argument value. Failing this validation results in failed argument parsing.
`overrides` | A list of names for other arguments that mutually override this flag
`hidden` | Specifies whether the argument should show up in the help message

## Methods

### `impl<'n, 'l, 'h, 'g, 'p, 'r> Arg<'n, 'l, 'h, 'g, 'p, 'r>`

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

Creates a new instance of `Arg` using a unique string name. The name will be used by the library consumer to get information about whether or not the argument was used at runtime.

NOTE: in the case of arguments that take values (i.e. `takes_value(true)`) and positional arguments (i.e. those without a `-` or `--`) the name will also be displayed when the user prints the usage/help information of the program.

# Examples

    Arg::with_name("config")

#### `fn from_usage(u: &'n str) -> Arg<'n, 'n, 'n, 'g, 'p, 'r>`

Creates a new instance of `Arg` from a usage string. Allows creation of basic settings for Arg (i.e. everything except relational rules). The syntax is flexible, but there are some rules to follow.

NOTE: only properties which you wish to set must be present

1. Name (arguments with a `long` or that take a value can omit this if desired), use `[]` for non-required arguments, or `<>` for required arguments.
2. Short preceded by a `-`
3. Long preceded by a `--` (this may be used as the name, if the name is omitted. If the name is not omitted, the name takes precedence over the `long`)
4. Value (this can be used as the name if the name is not manually specified. If the name is manually specified, it takes precedence. If this value is used as the name, it uses the same `[]` and `<>` requirement specification rules. If it is not used as the name, it still needs to be surrounded by either `[]` or `<>` but there is no requirement effect, as the requirement rule is determined by the real name. This value may follow the `short` or `long`, it doesn't matter. If it follows the `long`, it may follow either a `=` or `` there is no difference, just personal preference. If this follows a `short` it can only be after a ``) i.e. `-c [name]`, `--config [name]`, `--config=[name]`, etc.
5. Multiple specifier `...` (the `...` may follow the name, `short`, `long`, or value without a `` space) i.e. `<name>... -c`, `--config <name>...`, `[name] -c...`, etc.
6. The help info surrounded by `'`s (single quotes)
7. The index of a positional argument will be the next available index (you don't need to specify one) i.e. all arguments without a `short` or `long` will be treated as positional
8. If the value names are all the same, and their multiple ones (i.e `-o <val> <val>`) they are counted and used as the number of values. If they are different, they are used as the value names (i.e. `--opt <file> <mode>`). In this case, if no name was specified prior to the value names, the long is used as the name by which to access the argument.

# Examples

                     .args(vec![

    // A option argument with a long, named "conf" (note: because the name was specified
    // the portion after the long can be called anything, only the first name will be displayed
    // to the user. Also, requirement is set with the *name*, so the portion after the long
    // could be either <> or [] and it wouldn't matter, so long as it's one of them. Had the
    // name been omitted, the name would have been derived from the portion after the long and
    // those rules would have mattered)
    Arg::from_usage("[conf] --config=[c] 'a required file for the configuration'"),

    // A flag with a short, a long, named "debug", and accepts multiple values
    Arg::from_usage("-d --debug... 'turns on debugging information"),

    // A required positional argument named "input"
    Arg::from_usage("<input> 'the input file to use'")
    ])

#### `fn short(self, s: &str) -> Self`

Sets the short version of the argument without the preceding `-`.

By default `clap` automatically assigns `V` and `h` to display version and help information respectively. You may use `V` or `h` for your own purposes, in which case `clap` simply will not assign those to the displaying of version or help.

NOTE: Any leading `-` characters will be stripped, and only the first non `-` character will be used as the `short` version

# Examples

    .short("c")

#### `fn long(self, l: &'l str) -> Self`

Sets the long version of the argument without the preceding `--`.

By default `clap` automatically assigns `version` and `help` to display version and help information respectively. You may use `version` or `help` for your own purposes, in which case `clap` simply will not assign those to the displaying of version or help automatically, and you will have to do so manually.

NOTE: Any leading `-` characters will be stripped

# Examples

    .long("config")

#### `fn help(self, h: &'h str) -> Self`

Sets the help text of the argument that will be displayed to the user when they print the usage/help information.

# Examples

    .help("The config file used by the myprog")

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

Sets whether or not the argument is required by default. Required by default means it is required, when no other mutually exclusive rules have been evaluated. Mutually exclusive rules take precedence over being required by default.

NOTE: Flags (i.e. not positional, or arguments that take values) cannot be required by default. when they print the usage/help information.

# Example

    .required(true)

#### `fn conflicts_with(self, name: &'r str) -> Self`

Sets a mutually exclusive argument by name. I.e. when using this argument, the following argument can't be present.

NOTE: Mutually exclusive rules take precedence over being required by default. Mutually exclusive rules only need to be set for one of the two arguments, they do not need to be set for each.

# Examples

    .conflicts_with("debug")

#### `fn conflicts_with_all<T, I>(self, names: I) -> Self where T: AsRef<str> + 'r, I: IntoIterator<Item=&'r T>`

Sets mutually exclusive arguments by names. I.e. when using this argument, the following argument can't be present.

NOTE: Mutually exclusive rules take precedence over being required by default. Mutually exclusive rules only need to be set for one of the two arguments, they do not need to be set for each.

# Examples

    let config_conflicts = ["debug", "input"];
    .conflicts_with_all(&config_conflicts)

#### `fn mutually_overrides_with(self, name: &'r str) -> Self`

Sets a mutually overridable argument by name. I.e. this argument and the following argument will override each other in POSIX style

# Examples

    .mutually_overrides_with("debug")

#### `fn mutually_overrides_with_all<T, I>(self, names: I) -> Self where T: AsRef<str> + 'r, I: IntoIterator<Item=&'r T>`

Sets a mutually overridable arguments by name. I.e. this argument and the following argument will override each other in POSIX style

# Examples

    let config_overrides = ["debug", "input"];
    .mutually_overrides_with_all(&config_overrides)

#### `fn requires(self, name: &'r str) -> Self`

Sets an argument by name that is required when this one is present I.e. when using this argument, the following argument must be present.

NOTE: Mutually exclusive and override rules take precedence over being required

# Examples

    .requires("debug")

#### `fn requires_all<T, I>(self, names: I) -> Self where T: AsRef<str> + 'r, I: IntoIterator<Item=&'r T>`

Sets arguments by names that are required when this one is present I.e. when using this argument, the following arguments must be present.

NOTE: Mutually exclusive and override rules take precedence over being required by default.

# Examples

    let config_reqs = ["debug", "input"];
    .requires_all(&config_reqs)

#### `fn takes_value(self, tv: bool) -> Self`

Specifies that the argument takes an additional value at run time.

NOTE: When setting this to `true` the `name` of the argument will be used when printing the help/usage information to the user.

# Examples

    .takes_value(true)

#### `fn index(self, idx: u8) -> Self`

Specifies the index of a positional argument starting at 1.

NOTE: When setting this, any `short` or `long` values you set are ignored as positional arguments cannot have a `short` or `long`. Also, the name will be used when printing the help/usage information to the user.

# Examples

    .index(1)

#### `fn multiple(self, multi: bool) -> Self`

Specifies that the flag or option may appear more than once. For flags, this results in the number of occurrences of the flag being recorded. For example `-ddd` would count as three occurrences. The form `-d -d -d` would also be recognized as three occurrences. For options, more than one value may be provided. The forms `--optional foo --optional bar`, `--optional foo bar` and `-ofoo -obar` are all recognized, assuming the relevant `short` and `long` option names have been set.

NOTE: When setting this, `index` is ignored as it only makes sense for positional arguments.

# Examples

    .multiple(true)

#### `fn global(self, g: bool) -> Self`

Specifies that an argument can be matched to all child subcommands.

NOTE: Global arguments only propagate down, not up (to parent commands)

NOTE: Global arguments cannot be required.

NOTE: Global arguments, when matched, only exist in the command's matches that they were matched to. For example, if you defined a `--flag` global argument in the top most parent command, but the user supplied the arguments `top cmd1 cmd2 --flag` only `cmd2`'s `ArgMatches` would return `true` if tested for `.is_present("flag")`.

# Examples

    .global(true)

#### `fn empty_values(self, ev: bool) -> Self`

Allows an argument to accept explicit empty values. An empty value must be specified at the command line with an explicit `""`, or `''`

NOTE: Defaults to `true` (Explicit empty values are allowed)

# Examples

    .empty_values(true)

#### `fn hidden(self, h: bool) -> Self`

Hides an argument from help message output.

NOTE: This does not hide the argument from usage strings on error

# Examples

    .hidden(true)

#### `fn possible_values<T, I>(self, names: I) -> Self where T: AsRef<str> + 'p, I: IntoIterator<Item=&'p T>`

Specifies a list of possible values for this argument. At runtime, clap verifies that only one of the specified values was used, or fails with a usage string.

NOTE: This setting only applies to options and positional arguments

# Examples

    let mode_vals = ["fast", "slow"];
    .possible_values(&mode_vals)

#### `fn possible_value(self, name: &'p str) -> Self`

Specifies a possible value for this argument. At runtime, clap verifies that only one of the specified values was used, or fails with a usage string.

NOTE: This setting only applies to options and positional arguments

# Examples

    .possible_value("fast")
    .possible_value("slow")

#### `fn group(self, name: &'g str) -> Self`

Specifies the name of the group the argument belongs to.

# Examples

    .group("mode")

#### `fn number_of_values(self, qty: u8) -> Self`

Specifies how many values are required to satisfy this argument. For example, if you had a `-f <file>` argument where you wanted exactly 3 'files' you would set `.number_of_values(3)`, and this argument wouldn't be satisfied unless the user provided 3 and only 3 values.

NOTE: Does not require `.multiple(true)` to be set. Setting `.multiple(true)` would allow `-f <file> <file> <file> -f <file> <file> <file>` where as not setting `.multiple(true)` would only allow one occurrence of this argument.

# Examples

    .number_of_values(3)

#### `fn validator<F>(self, f: F) -> Self where F: Fn(String) -> Result<(), String> + 'static`

Allows one to perform a validation on the argument value. You provide a closure which accepts a `String` value, a `Result` where the `Err(String)` is a message displayed to the user.

NOTE: The error message does not need to contain the `error:` portion, only the message.

NOTE: There is a small performance hit for using validators, as they are implemented with `Rc` pointers. And the value to be checked will be allocated an extra time in order to to be passed to the closure.

# Examples

    .validator(|val| {
        if val.contains("@") {
            Ok(())
        } else {
            Err(String::from("the value must contain at least one '@' character"))
        }
    })

#### `fn max_values(self, qty: u8) -> Self`

Specifies the maximum number of values are for this argument. For example, if you had a `-f <file>` argument where you wanted up to 3 'files' you would set `.max_values(3)`, and this argument would be satisfied if the user provided, 1, 2, or 3 values.

NOTE: `qty` must be > 1

NOTE: This implicitly sets `.multiple(true)`

# Examples

    .max_values(3)

#### `fn min_values(self, qty: u8) -> Self`

Specifies the minimum number of values are for this argument. For example, if you had a `-f <file>` argument where you wanted at least 2 'files' you would set `.min_values(2)`, and this argument would be satisfied if the user provided, 2 or more values.

NOTE: This implicitly sets `.multiple(true)`

NOTE: `qty` must be > 0

NOTE: `qty` must be > 0. If you wish to have an argument with 0 or more values prefer two separate arguments (a flag, and an option with multiple values).

# Examples

    .min_values(2)

#### `fn value_names<T, I>(self, names: I) -> Self where T: AsRef<str> + 'n, I: IntoIterator<Item=&'n T>`

Specifies names for values of option arguments. These names are cosmetic only, used for help and usage strings only. The names are not used to access arguments. The values of the arguments are accessed in numeric order (i.e. if you specify two names `one` and `two` `one` will be the first matched value, `two` will be the second).

NOTE: This implicitly sets `.number_of_values()` so there is no need to set that, but be aware that the number of "names" you set for the values, will be the exact number of values required to satisfy this argument

NOTE: Does not require `.multiple(true)` to be set. Setting `.multiple(true)` would allow `-f <file> <file> <file> -f <file> <file> <file>` where as not setting `.multiple(true)` would only allow one occurrence of this argument.

# Examples

    let val_names = ["one", "two"];
    // ...
    .value_names(&val_names)

#### `fn value_name(self, name: &'n str) -> Self`

Specifies the name for value of option or positional arguments. This name is cosmetic only, used for help and usage strings. The name is not used to access arguments.

# Examples

    Arg::with_name("debug")
        .index(1)
        .value_name("file")

## Trait Implementations

### `impl<'n, 'l, 'h, 'g, 'p, 'r, 'z> From<&'z Arg<'n, 'l, 'h, 'g, 'p, 'r>> for Arg<'n, 'l, 'h, 'g, 'p, 'r>`

#### `fn from(a: &'z Arg<'n, 'l, 'h, 'g, 'p, 'r>) -> Self`

### Derived Implementations

### `impl<'n, 'l, 'h, 'g, 'p, 'r> Default for Arg<'n, 'l, 'h, 'g, 'p, 'r>`

#### `fn default() -> Arg<'n, 'l, 'h, 'g, 'p, 'r>`

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