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

    pub struct Arg<'a, 'b> where 'a: 'b {
        // some fields omitted
    }

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

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 but has fewer options. You can also use a combination of the two methods to achieve the best of both worlds.

# Examples

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

## Methods

### `impl<'a, 'b> Arg<'a, 'b>`

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

Creates a new instance of `Arg` using a unique string name. The name will be used to get information about whether or not the argument was used at runtime, get values, set relationships with other args, etc..

NOTE: In the case of arguments that take values (i.e. `takes_value(true)`) and positional arguments (i.e. those without a preceding `-` 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: &'a str) -> Self`

Creates a new instance of `Arg` from a usage string. Allows creation of basic settings for the `Arg`. The syntax is flexible, but there are some rules to follow.

NOTE: Not all settings may be set using the usage string method. Some properties are only available via the builder pattern.

NOTE: Only ASCII values in `from_usage` strings are officially supported. Some UTF-8 codepoints may work just fine, but this is not guaranteed.

# Syntax

Usage strings typically following the form:

    [explicit name] [short] [long] [value names] [help string]

This is not a hard rule as the attributes can appear in other orders. There are also several additional sigils which denote additional settings. Below are the details of each portion of the string.

### Explicit Name

This is an optional field, if it's omitted the argumenet will use one of the additioinal fields as the name using the following priority order:

- Explicit Name (This always takes precedence when present)
- Long
- Short
- Value Name

`clap` determines explicit names as the first string of characters between either `[]` or `<>` where `[]` has the dual notation of meaning the argument is optional, and `<>` meaning the argument is required.

Explicit names may be followed by: * The multiple denotation `...`

Example explicit names as follows (`ename` for an optional argument, and `rname` for a required argument):

    [ename] -s, --long 'some flag'
    <rname> -r, --longer 'some other flag'

### Short

This is set by placing a single character after a leading `-`.

Shorts may be followed by * The multiple denotation `...` * An optional comma `,` which is cosmetic only * Value notation

Example shorts are as follows (`-s`, and `-r`):

    -s, --long 'some flag'
    <rname> -r [val], --longer 'some option'

### Long

This is set by placing a word (no spaces) after a leading `--`.

Shorts may be followed by * The multiple denotation `...` * Value notation

Example longs are as follows (`--some`, and `--rapid`):

    -s, --some 'some flag'
    --rapid=[FILE] 'some option'

### Values (Value Notation)

This is set by placing a word(s) between `[]` or `<>` optionally after `=` (although this is cosmetic only and does not affect functionality). If an explicit name has not been set, using `<>` will denote a required argument, and `[]` will denote an optional argument

Values may be followed by * The multiple denotation `...` * More Value notation

More than one value will also implicitly set the arguments number of values, i.e. having two values, `--option [val1] [val2]` specifies that in order for option to be satisified it must receive exactly two values

Example values are as follows (`FILE`, and `SPEED`):

    -s, --some [FILE] 'some option'
    --rapid=<SPEED>... 'some required multiple option'

### Help String

The help string is denoted between a pair of single quotes `''` and may contain any characters.

Example help strings are as follows:

    -s, --some [FILE] 'some option'
    --rapid=<SPEED>... 'some required multiple option'

### Additional Sigils

Multiple notation `...` (three consecutive dots/periods) specifies that this argument may be used multiple times. Do not confuse multiple occurrences (`...`) with multiple values. `--option val1 val2` is a single occurrence with multiple values. `--flag --flag` is multiple occurrences (and then you can obviously have instances of both as well)

# Examples

    App::new("myprog")
        .args(&[
            Arg::from_usage("--config <FILE> 'a required file for the configuration and no short'"),
            Arg::from_usage("-d, --debug... 'turns on debugging information and allows multiples'"),
            Arg::from_usage("[input] 'an optional input file to use'")
    ])

#### `fn short<S: AsRef<str>>(self, s: S) -> 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

To set `short` use a single valid UTF-8 codepoint. If you supply a leading `-` such as `-c` it will be stripped.

    Arg::with_name("config")
        .short("c")

Setting `short` allows using the argument via a single hyphen (`-`) such as `-c`

    let m = App::new("shorttest")
        .arg(Arg::with_name("config")
            .short("c"))
        .get_matches_from(vec![
            "shorttest", "-c"
        ]);

    assert!(m.is_present("config"));

#### `fn long(self, l: &'b 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

To set `long` use a word containing valid UTF-8 codepoints. If you supply a dobule leading `--` such as `--config` they will be stripped. Hyphens in the middle of the word, however, will not be stripped (i.e. `config-file` is allowed)

    Arg::with_name("cfg")
        .long("config")

Setting `long` allows using the argument via a double hyphen (`--`) such as `--config`

    let m = App::new("longtest")
        .arg(Arg::with_name("cfg")
            .long("config"))
        .get_matches_from(vec![
            "shorttest", "--config"
        ]);

    assert!(m.is_present("cfg"));

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

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

# Examples

Any valid `String` slice is allowed as help (i.e. only valid UTF-8). The one exception is one wishes to include a newline in the help text. To include a newline and be properly aligned with all other arguments help text, it must be specified via `{n}` instead of `\n`.

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

Setting `help` displays a short message to the side of the argument when the user passes `-h` or `--help` (by default).

    let m = App::new("helptest")
        .arg(Arg::with_name("cfg")
            .long("config")
            .help("Some help text describing the --config arg"))
        .get_matches_from(vec![
            "shorttest", "--help"
        ]);

    // ...

The above example displays

    helptest

    USAGE:
       helptest [FLAGS]

    FLAGS:
        --config     Some help text describing the --config arg
    -h, --help       Prints help information
    -V, --version    Prints version information

#### `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 conflicting rules have been evaluated. Conflicting rules take precedence over being required. Default: `false`

NOTE: Flags (i.e. not positional, or arguments that take values) cannot be required.

# Examples

    Arg::with_name("config")
        .required(true)

Setting `required(true)` requires that the argument be used at runtime.

    let res = App::new("longtest")
        .arg(Arg::with_name("cfg")
            .required(true)
            .takes_value(true)
            .long("config"))
        .get_matches_from_safe(vec![
            "shorttest", "--config", "file.conf"
        ]);

    assert!(res.is_ok());

Setting `required(true)` and not supplying that argument is an error.

    let res = App::new("longtest")
        .arg(Arg::with_name("cfg")
            .required(true)
            .takes_value(true)
            .long("config"))
        .get_matches_from_safe(vec![
            "shorttest"
        ]);

    assert!(res.is_err());
    assert_eq!(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument);

#### `fn required_unless(self, name: &'a str) -> Self`

Sets an arg that override this arg's required setting. (i.e. this arg will be required unless this other argument is present).

Pro Tip: Using `Arg::required_unless` implies `Arg::required` and is therefore not mandatory to also set.

# Examples

    Arg::with_name("config")
        .required_unless("debug")

Setting `required_unless(name)` requires that the argument be used at runtime unless `name` is present. In the following example, the required argument is not provided, but it's not an error because the `unless` arg has been supplied.

    let res = App::new("unlesstest")
        .arg(Arg::with_name("cfg")
            .required_unless("dbg")
            .takes_value(true)
            .long("config"))
        .arg(Arg::with_name("dbg")
            .long("debug"))
        .get_matches_from_safe(vec![
            "unlesstest", "--debug"
        ]);

    assert!(res.is_ok());

Setting `required_unless(name)` and not supplying `name` or this arg is an error.

    let res = App::new("unlesstest")
        .arg(Arg::with_name("cfg")
            .required_unless("dbg")
            .takes_value(true)
            .long("config"))
        .arg(Arg::with_name("dbg")
            .long("debug"))
        .get_matches_from_safe(vec![
            "unlesstest"
        ]);

    assert!(res.is_err());
    assert_eq!(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument);

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

Sets args that override this arg's required setting. (i.e. this arg will be required unless all these other argument are present).

NOTE: If you wish for the this argument to only be required if one of these args are present see `Arg::required_unless_one`

# Examples

    Arg::with_name("config")
        .required_unless_all(&["cfg", "dbg"])

Setting `required_unless_all(names)` requires that the argument be used at runtime unless all the args in `names` are present. In the following example, the required argument is not provided, but it's not an error because all the `unless` args have been supplied.

    let res = App::new("unlessall")
        .arg(Arg::with_name("cfg")
            .required_unless_all(&["dbg", "infile"])
            .takes_value(true)
            .long("config"))
        .arg(Arg::with_name("dbg")
            .long("debug"))
        .arg(Arg::with_name("infile")
            .short("i")
            .takes_value(true))
        .get_matches_from_safe(vec![
            "unlessall", "--debug", "-i", "file"
        ]);

    assert!(res.is_ok());

Setting `required_unless_all(names)` and not supplying all of `names` or this arg is an error.

    let res = App::new("unlessall")
        .arg(Arg::with_name("cfg")
            .required_unless_all(&["dbg", "infile"])
            .takes_value(true)
            .long("config"))
        .arg(Arg::with_name("dbg")
            .long("debug"))
        .arg(Arg::with_name("infile")
            .short("i")
            .takes_value(true))
        .get_matches_from_safe(vec![
            "unlessall"
        ]);

    assert!(res.is_err());
    assert_eq!(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument);

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

Sets args that override this arg's required setting. (i.e. this arg will be required unless at least one of these other argument are present).

NOTE: If you wish for the this argument to only be required if all of these args are present see `Arg::required_unless_all`

# Examples

    Arg::with_name("config")
        .required_unless_all(&["cfg", "dbg"])

Setting `required_unless_one(names)` requires that the argument be used at runtime unless at least one of the args in `names` are present. In the following example, the required argument is not provided, but it's not an error because one the `unless` args have been supplied.

    let res = App::new("unlessone")
        .arg(Arg::with_name("cfg")
            .required_unless_one(&["dbg", "infile"])
            .takes_value(true)
            .long("config"))
        .arg(Arg::with_name("dbg")
            .long("debug"))
        .arg(Arg::with_name("infile")
            .short("i")
            .takes_value(true))
        .get_matches_from_safe(vec![
            "unlessone", "--debug"
        ]);

    assert!(res.is_ok());

Setting `required_unless_one(names)` and not supplying at least one of `names` or this arg is an error.

    let res = App::new("unlessone")
        .arg(Arg::with_name("cfg")
            .required_unless_one(&["dbg", "infile"])
            .takes_value(true)
            .long("config"))
        .arg(Arg::with_name("dbg")
            .long("debug"))
        .arg(Arg::with_name("infile")
            .short("i")
            .takes_value(true))
        .get_matches_from_safe(vec![
            "unlessone"
        ]);

    assert!(res.is_err());
    assert_eq!(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument);

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

Sets a conflicting argument by name. I.e. when using this argument, the following argument can't be present and vice versa.

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

NOTE: Defining a conflict is two-way, but does not need to defined for both arguments (i.e. if A conflicts with B, defining A.conflicts_with(B) is sufficient. You do not need need to also do B.conflicts_with(A))

# Examples

    Arg::with_name("config")
        .conflicts_with("debug")

Setting conflicting argument, and having both arguments present at runtime is an error.

    let res = App::new("conflictions")
        .arg(Arg::with_name("cfg")
            .takes_value(true)
            .conflicts_with("debug")
            .long("config"))
        .arg(Arg::with_name("debug")
            .long("debug"))
        .get_matches_from_safe(vec![
            "conflictions", "--debug", "--config", "file.conf"
        ]);

    assert!(res.is_err());
    assert_eq!(res.unwrap_err().kind, ErrorKind::ArgumentConflict);

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

The same as `Arg::conflicts_with` but allows specifying multiple two-way conlicts per argument.

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

NOTE: Defining a conflict is two-way, but does not need to defined for both arguments (i.e. if A conflicts with B, defining A.conflicts_with(B) is sufficient. You do not need need to also do B.conflicts_with(A))

# Examples

    Arg::with_name("config")
        .conflicts_with_all(&["debug", "input"])

Setting conflicting argument, and having any of the arguments present at runtime with a conflicting argument is an error.

    let res = App::new("conflictions")
        .arg(Arg::with_name("cfg")
            .takes_value(true)
            .conflicts_with_all(&["debug", "input"])
            .long("config"))
        .arg(Arg::with_name("debug")
            .long("debug"))
        .arg(Arg::with_name("input")
            .index(1))
        .get_matches_from_safe(vec![
            "conflictions", "--config", "file.conf", "file.txt"
        ]);

    assert!(res.is_err());
    assert_eq!(res.unwrap_err().kind, ErrorKind::ArgumentConflict);

#### `fn overrides_with(self, name: &'a str) -> Self`

Sets a overridable argument by name. I.e. this argument and the following argument will override each other in POSIX style (whichever argument was specified at runtime last "wins")

NOTE: When an argument is overriden it is essentially as if it never was used, any conflicts, requirements, etc. are evaluated after all "overrides" have been removed

# Examples

    let m = App::new("posix")
        .arg(Arg::from_usage("-f, --flag 'some flag'")
            .conflicts_with("debug"))
        .arg(Arg::from_usage("-d, --debug 'other flag'"))
        .arg(Arg::from_usage("-c, --color 'third flag'")
            .overrides_with("flag"))
        .get_matches_from(vec!["posix", "-f", "-d", "-c"]);
                                    //    ^~~~~~~~~~~~^~~~~ flag is overriden by color

    assert!(m.is_present("color"));
    assert!(m.is_present("debug")); // even though flag conflicts with debug, it's as if flag
                                    // was never used because it was overriden with color
    assert!(!m.is_present("flag"));

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

Sets multiple mutually overridable arguments by name. I.e. this argument and the following argument will override each other in POSIX style (whichever argument was specified at runtime last "wins")

NOTE: When an argument is overriden it is essentially as if it never was used, any conflicts, requirements, etc. are evaluated after all "overrides" have been removed

# Examples

    let m = App::new("posix")
        .arg(Arg::from_usage("-f, --flag 'some flag'")
            .conflicts_with("color"))
        .arg(Arg::from_usage("-d, --debug 'other flag'"))
        .arg(Arg::from_usage("-c, --color 'third flag'")
            .overrides_with_all(&["flag", "debug"]))
        .get_matches_from(vec!["posix", "-f", "-d", "-c"]);
                                    //    ^~~~~~^~~~~~~~~ flag and debug are overriden by color

    assert!(m.is_present("color")); // even though flag conflicts with color, it's as if flag
                                    // and debug were never used because they were overriden
                                    // with color
    assert!(!m.is_present("debug"));
    assert!(!m.is_present("flag"));

#### `fn requires(self, name: &'a 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: Conflicting rules and override rules take precedence over being required

# Examples

    Arg::with_name("config")
        .requires("input")

Setting `requires("arg")` requires that the argument be used at runtime if the defining argument is used. If the defining argument isn't used, the other arguemnt isn't required

    let res = App::new("reqtest")
        .arg(Arg::with_name("cfg")
            .takes_value(true)
            .requires("input")
            .long("config"))
        .arg(Arg::with_name("input")
            .index(1))
        .get_matches_from_safe(vec![
            "reqtest"
        ]);

    assert!(res.is_ok()); // We didn't use cfg, so input wasn't required

Setting `requires("arg")` and not supplying that argument is an error.

    let res = App::new("reqtest")
        .arg(Arg::with_name("cfg")
            .takes_value(true)
            .requires("input")
            .long("config"))
        .arg(Arg::with_name("input")
            .index(1))
        .get_matches_from_safe(vec![
            "reqtest", "--config", "file.conf"
        ]);

    assert!(res.is_err());
    assert_eq!(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument);

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

Sets multiple 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

    Arg::with_name("config")
        .requires_all(&["input", "output"])

Setting `requires_all(&["arg", "arg2"])` requires that all the arguments be used at runtime if the defining argument is used. If the defining argument isn't used, the other arguemnt isn't required

    let res = App::new("reqtest")
        .arg(Arg::with_name("cfg")
            .takes_value(true)
            .requires("input")
            .long("config"))
        .arg(Arg::with_name("input")
            .index(1))
        .arg(Arg::with_name("output")
            .index(2))
        .get_matches_from_safe(vec![
            "reqtest"
        ]);

    assert!(res.is_ok()); // We didn't use cfg, so input and output weren't required

Setting `requires_all(&["arg", "arg2"])` and not supplying all the arguments is an error.

    let res = App::new("reqtest")
        .arg(Arg::with_name("cfg")
            .takes_value(true)
            .requires_all(&["input", "output"])
            .long("config"))
        .arg(Arg::with_name("input")
            .index(1))
        .arg(Arg::with_name("output")
            .index(2))
        .get_matches_from_safe(vec![
            "reqtest", "--config", "file.conf", "in.txt"
        ]);

    assert!(res.is_err());
    // We didn't use output
    assert_eq!(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument);

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

Specifies that the argument takes a value at run time.

NOTE: values for arguments may be specified in any of the following methods

- Using a space such as `-o value` or `--option value`
- Using an equals and no space such as `-o=value` or `--option=value`
- Use a short and no space such as `-ovalue`

NOTE: By default, values are delimted by commas, meaning `--option=val1,val2,val3` is is three values for the `--option` argument. If you wish to change the delimiter to another character you can use `Arg::value_delimiter(char)`, alternatively you can delimiting values OFF by using `Arg::use_delimiter(false)`

# Examples

    Arg::with_name("config")
        .takes_value(true)

    let m = App::new("posvals")
        .arg(Arg::with_name("mode")
            .long("mode")
            .takes_value(true))
        .get_matches_from(vec!["posvals", "--mode", "fast"]);

    assert!(m.is_present("mode"));
    assert_eq!(m.value_of("mode"), Some("fast"));

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

Specifies the index of a positional argument starting at 1.

NOTE: The index refers to position according to other positional argument. It does not define position in the argument list as a whole.

NOTE: If no `short`, or `long` have been defined, you can optionally leave off the `index` method, and the index will be assigned in order of evaluation. Utilizing the `index` method allows for setting indexes out of order

NOTE: When utilized with `multiple(true)`, only the last psoitional argument may be defined as multiple (i.e. with the highest index)

# Panics

Although not in this method directly, `App` will `panic!` if indexes are skipped (such as defining `index(1)` and `index(3)` but not `index(2)`, or a positional argument is defined as multiple and is not the highest index

# Examples

    Arg::with_name("config")
        .index(1)

    let m = App::new("posvals")
        .arg(Arg::with_name("mode")
            .index(1))
        .arg(Arg::with_name("debug")
            .long("debug"))
        .get_matches_from(vec!["posvals", "--debug", "fast"]);

    assert!(m.is_present("mode"));
    assert_eq!(m.value_of("mode"), Some("fast")); // notice index(1) means "first positional"
                                                  // *not* first argument

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

Specifies that the argument may appear more than once. For flags, this results in the number of occurrences of the flag being recorded. For example `-ddd` or `-d -d -d` would count as three occurrences. For options there is a distinct difference in multiple occurrences vs multiple values.

For example, `--opt val1 val2` is one occurrence, but two values. Whereas `--opt val1 --opt val2` is two occurrences.

WARNING:

Setting `multipe(true)` for an option allows multiple values and multiple occurrences because it isn't possible to more occurrences than values for options. Because multiple values are allowed, `--option val1 val2 val3` is perfectly valid, be careful when designing a CLI where positional arguments are expectd after a option which accepts multiple values, as `clap` will continue parsing values until it reaches the max or specific number of values defined, or another flag or option.

Pro Tip:

It's possible to define an option which allows multiple occurrences, but only one value per occurrence. To do this use `Arg::number_of_values(1)` in coordination with `Arg::multiple(true)`.

# Examples

    Arg::with_name("debug")
        .short("d")
        .multiple(true)

An example with flags

    let m = App::new("mults")
        .arg(Arg::with_name("verbose")
            .multiple(true)
            .short("v"))
        .get_matches_from(vec!["mults", "-v", "-v", "-v"]); // note, -vvv would have same result

    assert!(m.is_present("verbose"));
    assert_eq!(m.occurrences_of("verbose"), 3);

An example with options

    let m = App::new("mults")
        .arg(Arg::with_name("file")
            .multiple(true)
            .takes_value(true)
            .short("F"))
        .get_matches_from(vec!["mults", "-F", "file1", "file2", "file3"]);

    assert!(m.is_present("file"));
    assert_eq!(m.occurrences_of("file"), 1); // notice only one occurrence
    let files: Vec<_> = m.values_of("file").unwrap().collect();
    assert_eq!(files, ["file1", "file2", "file3"]);

This is functionally equivilant to the example above

    let m = App::new("mults")
        .arg(Arg::with_name("file")
            .multiple(true)
            .takes_value(true)
            .short("F"))
        .get_matches_from(vec!["mults", "-F", "file1", "-F", "file2", "-F", "file3"]);
    let files: Vec<_> = m.values_of("file").unwrap().collect();
    assert_eq!(files, ["file1", "file2", "file3"]);

    assert!(m.is_present("file"));
    assert_eq!(m.occurrences_of("file"), 3); // Notice 3 occurrences
    let files: Vec<_> = m.values_of("file").unwrap().collect();
    assert_eq!(files, ["file1", "file2", "file3"]);

A common mistake is to define an option which allows multiples, and a positional argument

    let m = App::new("mults")
        .arg(Arg::with_name("file")
            .multiple(true)
            .takes_value(true)
            .short("F"))
        .arg(Arg::with_name("word")
            .index(1))
        .get_matches_from(vec!["mults", "-F", "file1", "file2", "file3", "word"]);

    assert!(m.is_present("file"));
    let files: Vec<_> = m.values_of("file").unwrap().collect();
    assert_eq!(files, ["file1", "file2", "file3", "word"]); // wait...what?!
    assert!(!m.is_present("word")); // but we clearly used word!

The problem is clap doesn't know when to stop parsing values for "files". This is further compounded by if we'd said `word -F file1 file2` it would have worked fine, so it would appear to only fail sometimes...not good!

A solution for the example above is to specify that `-F` only accepts one value, but is allowed to appear multiple times

    let m = App::new("mults")
        .arg(Arg::with_name("file")
            .multiple(true)
            .takes_value(true)
            .number_of_values(1)
            .short("F"))
        .arg(Arg::with_name("word")
            .index(1))
        .get_matches_from(vec!["mults", "-F", "file1", "-F", "file2", "-F", "file3", "word"]);

    assert!(m.is_present("file"));
    let files: Vec<_> = m.values_of("file").unwrap().collect();
    assert_eq!(files, ["file1", "file2", "file3"]);
    assert!(m.is_present("word"));
    assert_eq!(m.value_of("word"), Some("word"));

As a final example, notice if we define `number_of_values(1)` and try to run the problem example above, it would have been a runtime error with a pretty message to the user :)

    let res = App::new("mults")
        .arg(Arg::with_name("file")
            .multiple(true)
            .takes_value(true)
            .number_of_values(1)
            .short("F"))
        .arg(Arg::with_name("word")
            .index(1))
        .get_matches_from_safe(vec!["mults", "-F", "file1", "file2", "file3", "word"]);

    assert!(res.is_err());
    assert_eq!(res.unwrap_err().kind, ErrorKind::UnknownArgument);

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

    Arg::with_name("debug")
        .short("d")
        .global(true)

For example, assume an appliction with two subcommands, and you'd like to define a `--verbose` flag that can be called on any of the subcommands and parent, but you don't want to clutter the source with three duplicate `Arg` definitions.

    let m = App::new("mults")
        .arg(Arg::with_name("verb")
            .long("verbose")
            .short("v")
            .global(true))
        .subcommand(SubCommand::with_name("test"))
        .subcommand(SubCommand::with_name("do-stuff"))
        .get_matches_from(vec!["mults", "do-stuff", "--verbose"]);

    assert_eq!(m.subcommand_name(), Some("do-stuff"));
    let sub_m = m.subcommand_matches("do-stuff").unwrap();
    assert!(sub_m.is_present("verb"));

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

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

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

NOTE: Implicitly sets `takes_value(true)` when set to `false`

# Examples

    Arg::with_name("file")
        .long("file")
        .empty_values(false)

The default is to allow empty values, such as `--option ""` would be an empty value. But we can change to make empty values become an error.

    let res = App::new("evals")
        .arg(Arg::with_name("cfg")
            .long("config")
            .short("v")
            .empty_values(false))
        .get_matches_from_safe(vec!["evals", "--config="]);

    assert!(res.is_err());
    assert_eq!(res.unwrap_err().kind, ErrorKind::EmptyValue);

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

    Arg::with_name("debug")
        .hidden(true)

Setting `hidden(true)` will hide the argument when displaying help text

    let m = App::new("helptest")
        .arg(Arg::with_name("cfg")
            .long("config")
            .hidden(true)
            .help("Some help text describing the --config arg"))
        .get_matches_from(vec![
            "shorttest", "--help"
        ]);

    // ...

The above example displays

    helptest

    USAGE:
       helptest [FLAGS]

    FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

#### `fn possible_values(self, names: &[&'b str]) -> Self`

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 an error message.

NOTE: This setting only applies to options and positional arguments

# Examples

    Arg::with_name("mode")
        .takes_value(true)
        .possible_values(&["fast", "slow", "medium"])

    let m = App::new("posvals")
        .arg(Arg::with_name("mode")
            .long("mode")
            .takes_value(true)
            .possible_values(&["fast", "slow", "medium"]))
        .get_matches_from(vec!["posvals", "--mode", "fast"]);
    assert!(m.is_present("mode"));
    assert_eq!(m.value_of("mode"), Some("fast"));

The next example shows a failed parse from using a value which wasn't defined as one of the possible values.

    let res = App::new("posvals")
        .arg(Arg::with_name("mode")
            .long("mode")
            .takes_value(true)
            .possible_values(&["fast", "slow", "medium"]))
        .get_matches_from_safe(vec!["myprog", "--mode", "wrong"]);
    assert!(res.is_err());
    assert_eq!(res.unwrap_err().kind, ErrorKind::InvalidValue);

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

Specifies a possible value for this argument, one at a time. At runtime, `clap` verifies that only one of the specified values was used, or fails with error message.

# Examples

    Arg::with_name("mode")
        .takes_value(true)
        .possible_value("fast")
        .possible_value("slow")
        .possible_value("medium")

    let m = App::new("posvals")
        .arg(Arg::with_name("mode")
            .long("mode")
            .takes_value(true)
            .possible_value("fast")
            .possible_value("slow")
            .possible_value("medium"))
        .get_matches_from(vec!["posvals", "--mode", "fast"]);
    assert!(m.is_present("mode"));
    assert_eq!(m.value_of("mode"), Some("fast"));

The next example shows a failed parse from using a value which wasn't defined as one of the possible values.

    let res = App::new("posvals")
        .arg(Arg::with_name("mode")
            .long("mode")
            .takes_value(true)
            .possible_value("fast")
            .possible_value("slow")
            .possible_value("medium"))
        .get_matches_from_safe(vec!["myprog", "--mode", "wrong"]);
    assert!(res.is_err());
    assert_eq!(res.unwrap_err().kind, ErrorKind::InvalidValue);

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

Specifies the name of the group the argument belongs to.

# Examples

    Arg::with_name("debug")
        .long("debug")
        .group("mode")

Multiple arguments can be a member of a single group and then the group checked as if it was one of said arguments.

    let m = App::new("groups")
        .arg(Arg::with_name("debug")
            .long("debug")
            .group("mode"))
        .arg(Arg::with_name("verbose")
            .long("verbose")
            .group("mode"))
        .get_matches_from(vec!["posvals", "--debug"]);
    assert!(m.is_present("mode"));

#### `fn number_of_values(self, qty: u64) -> 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

    Arg::with_name("file")
        .short("f")
        .number_of_values(3)

Not supplying the correct number of values is an error

    let res = App::new("numvals")
        .arg(Arg::with_name("file")
            .takes_value(true)
            .number_of_values(2)
            .short("F"))
        .get_matches_from_safe(vec!["mults", "-F", "file1"]);

    assert!(res.is_err());
    assert_eq!(res.unwrap_err().kind, ErrorKind::WrongNumberOfValues);

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

Allows one to perform a custom 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. This performance hit is extremely minimal in the grand scheme of things.

# Examples

    fn has_at(v: String) -> Result<(), String> {
        if v.contains("@") { return Ok(()); }
        Err(String::from("The value did not contain the required @ sigil"))
    }
    let res = App::new("validators")
        .arg(Arg::with_name("file")
            .index(1)
            .validator(has_at))
        .get_matches_from_safe(vec![
            "validators", "some@file"
        ]);
    assert!(res.is_ok());
    assert_eq!(res.unwrap().value_of("file"), Some("some@file"));

#### `fn max_values(self, qty: u64) -> 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: This does not implicitly set `mulitple(true)`. This is because `-o val -o val` is multiples occurrences but a single value and `-o val1 val2` is a single occurence with multple values. For positional arguments this does set `multiple(true)` because there is no way to determine the diffrence between multiple occureces and multiple values.

# Examples

    Arg::with_name("file")
        .short("f")
        .max_values(3)

Supplying less than the maximum number of values is allowed

    let res = App::new("numvals")
        .arg(Arg::with_name("file")
            .takes_value(true)
            .max_values(3)
            .short("F"))
        .get_matches_from_safe(vec!["mults", "-F", "file1", "file2"]);

    assert!(res.is_ok());
    let m = res.unwrap();
    let files: Vec<_> = m.values_of("file").unwrap().collect();
    assert_eq!(files, ["file1", "file2"]);

Supplying more than the maximum number of values is an error

    let res = App::new("numvals")
        .arg(Arg::with_name("file")
            .takes_value(true)
            .max_values(2)
            .short("F"))
        .get_matches_from_safe(vec!["mults", "-F", "file1", "file2", "file3"]);

    assert!(res.is_err());
    assert_eq!(res.unwrap_err().kind, ErrorKind::TooManyValues);

#### `fn min_values(self, qty: u64) -> 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 does not implicitly set `mulitple(true)`. This is because `-o val -o val` is multiples occurrences but a single value and `-o val1 val2` is a single occurence with multple values. For positional arguments this does set `multiple(true)` because there is no way to determine the diffrence between multiple occureces and multiple values.

# Examples

    Arg::with_name("file")
        .short("f")
        .min_values(3)

Supplying more than the minimum number of values is allowed

    let res = App::new("numvals")
        .arg(Arg::with_name("file")
            .takes_value(true)
            .min_values(2)
            .short("F"))
        .get_matches_from_safe(vec!["mults", "-F", "file1", "file2", "file3"]);

    assert!(res.is_ok());
    let m = res.unwrap();
    let files: Vec<_> = m.values_of("file").unwrap().collect();
    assert_eq!(files, ["file1", "file2", "file3"]);

Supplying less than the mainimum number of values is an error

    let res = App::new("numvals")
        .arg(Arg::with_name("file")
            .takes_value(true)
            .min_values(2)
            .short("F"))
        .get_matches_from_safe(vec!["mults", "-F", "file1"]);

    assert!(res.is_err());
    assert_eq!(res.unwrap_err().kind, ErrorKind::TooFewValues);

#### `fn use_delimiter(self, d: bool) -> Self`

Specifies whether or not an arugment should allow grouping of multiple values via a delimter. I.e. shoulde `--option=val1,val2,val3` be parsed as three values (`val1`, `val2`, and `val3`) or as a single value (`val1,val2,val3`). Defaults to using `,` (comma) as the value delimiter for all arguments that accept values (options and positional arguments)

NOTE: The defalt is `true`. Setting the value to `true` will reset any previous use of `Arg::value_delimiter` back to the default of `,` (comma).

# Examples

The following example shows the default behavior.

    let delims = App::new("delims")
        .arg(Arg::with_name("option")
            .long("option")
            .takes_value(true))
        .get_matches_from(vec![
            "delims",
            "--option=val1,val2,val3",
        ]);

    assert!(delims.is_present("option"));
    assert_eq!(delims.occurrences_of("option"), 1);
    assert_eq!(delims.values_of("option").unwrap().collect::<Vec<_>>(), ["val1", "val2", "val3"]);

The next example shows the difference when turning delimiters off.

    let nodelims = App::new("nodelims")
        .arg(Arg::with_name("option")
            .long("option")
            .use_delimiter(false)
            .takes_value(true))
        .get_matches_from(vec![
            "nodelims",
            "--option=val1,val2,val3",
        ]);

    assert!(nodelims.is_present("option"));
    assert_eq!(nodelims.occurrences_of("option"), 1);
    assert_eq!(nodelims.value_of("option").unwrap(), "val1,val2,val3");

#### `fn value_delimiter(self, d: &str) -> Self`

Specifies the separator to use when values are clumped together, defaults to `,` (comma).

NOTE: implicitly sets `Arg::use_delimiter(true)`

NOTE: implicitly sets `Arg::takes_value(true)`

# Examples

    let app = App::new("fake")
        .arg(Arg::with_name("config")
            .short("c")
            .long("config")
            .value_delimiter(";"));

    let m = app.get_matches_from(vec![
        "fake", "--config=val1;val2;val3"
    ]);

    assert_eq!(m.values_of("config").unwrap().collect::<Vec<_>>(), ["val1", "val2", "val3"])

#### `fn value_names(self, names: &[&'b str]) -> Self`

Specify multiple 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).

This setting can be very helpful when describing the type of input the user should be using, such as `FILE`, `INTERFACE`, etc. Although not required, it's somewhat convention to use all capital letters for the value name.

Pro Tip: It may help to use `Arg::next_line_help(true)` if there are long, or multiple value names in order to not throw off the help text alignment of all options.

NOTE: This implicitly sets `.number_of_values()` if the number of value names is greater than one. I.e. 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: implicitly sets `Arg::takes_value(true)`

NOTE: Does not require or imply `.multiple(true)`.

# Examples

    Arg::with_name("speed")
        .short("s")
        .value_names(&["fast", "slow"])

    let app = App::new("valnames")
        .arg(Arg::with_name("io")
            .long("io-files")
            .value_names(&["INFILE", "OUTFILE"]))
        .get_matches_from(vec![
            "valnames", "--help"
        ]);

Running the above program produces the following output

    valnames

    USAGE:
       valnames [FLAGS] [OPTIONS]

    FLAGS:
        -h, --help       Prints help information
        -V, --version    Prints version information

    OPTIONS:
        --io-files <INFILE> <OUTFILE>    Some help text

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

Specifies the name for value of option or positional arguments inside of help documenation. This name is cosmetic only, the name is not used to access arguments. This setting can be very helpful when describing the type of input the user should be using, such as `FILE`, `INTERFACE`, etc. Although not required, it's somewhat convention to use all capital letters for the value name.

NOTE: implicitly sets `Arg::takes_value(true)`

# Examples

    Arg::with_name("cfg")
        .long("config")
        .value_name("FILE")

    let app = App::new("valnames")
        .arg(Arg::with_name("config")
            .long("config")
            .value_name("FILE"))
        .get_matches_from(vec![
            "valnames", "--help"
        ]);

Running the above program produces the following output

    valnames

    USAGE:
       valnames [FLAGS] [OPTIONS]

    FLAGS:
        -h, --help       Prints help information
        -V, --version    Prints version information

    OPTIONS:
        --config <FILE>     Some help text

#### `fn default_value(self, val: &'a str) -> Self`

Specifies the value of the argument when not specified at runtime.

NOTE: If the user does not use this argument at runtime, `ArgMatches::occurrences_of` will return `0` even though the `value_of` will return the default specified.

NOTE: If the user does not use this argument at runtime `ArgMatches::is_present` will still return `true`. If you wish to determine whether the argument was used at runtime or not, consider `ArgMatches::occurrences_of` which will return `0` if the argument was not used at runtmie.

NOTE: This implicitly sets `Arg::takes_value(true)`.

# Examples

    let m = App::new("defvals")
        .arg(Arg::with_name("opt")
            .long("myopt")
            .default_value("myval"))
        .get_matches_from(vec![
            "defvals"
        ]);

    assert_eq!(m.value_of("opt"), Some("myval"));
    assert!(m.is_present("opt"));
    assert_eq!(m.occurrences_of("opt"), 0);

#### `fn next_line_help(self, nlh: bool) -> Self`

When set to `true` the help string will be displayed on the line after the argument and indented once. This can be helpful for arguments with very long or complex help messages. This can also be helpful for arguments with very long flag names, or many/long value names.

NOTE: To apply this setting to all arguments consider using `AppSettings::NextLineHelp`

# Examples

    let m = App::new("nlh")
        .arg(Arg::with_name("opt")
            .long("long-option-flag")
            .short("o")
            .takes_value(true)
            .value_names(&["value1", "value2"])
            .help("Some really long help and complex{n}\
                   help that makes more sense to be{n}\
                   on a line after the option")
            .next_line_help(true))
        .get_matches_from(vec![
            "nlh", "--help"
        ]);

The above example displays the following help message

    nlh

    USAGE:
        nlh [FLAGS] [OPTIONS]

    FLAGS:
        -h, --help       Prints help information
        -V, --version    Prints version information

    OPTIONS:
        -o, --long-option-flag <value1> <value2>
            Some really long help and complex
            help that makes more sense to be
            on a line after the option

#### `fn display_order(self, ord: usize) -> Self`

Allows custom ordering of args within the help message. Args with a lower value will be displayed first in the help message. This is helpful when one would like to emphasise frequently used args, or prioritize those towards the top of the list. Duplicate values are allowed. Args with duplicate display orders will be displayed in alphabetical order.

NOTE: The default is 999 for all arguments.

NOTE: This setting is ignored for positional arguments which are always displayed in index order.

# Examples

    let m = App::new("cust-ord")
        .arg(Arg::with_name("a") // Typically args are grouped alphabetically by name.
                                 // Args without a display_order have a value of 999 and are
                                 // displayed alphabetically with all other 999 valued args.
            .long("long-option")
            .short("o")
            .takes_value(true)
            .help("Some help and text"))
        .arg(Arg::with_name("b")
            .long("other-option")
            .short("O")
            .takes_value(true)
            .display_order(1)   // In order to force this arg to appear *first*
                                // all we have to do is give it a value lower than 999.
                                // Any other args with a value of 1 will be displayed
                                // alphabetically with this one...then 2 values, then 3, etc.
            .help("I should be first!"))
        .get_matches_from(vec![
            "cust-ord", "--help"
        ]);

The above example displays the following help message

    cust-ord

    USAGE:
        cust-ord [FLAGS] [OPTIONS]

    FLAGS:
        -h, --help       Prints help information
        -V, --version    Prints version information

    OPTIONS:
        -O, --other-option <b>    I should be first!
        -o, --long-option <a>     Some help and text

#### `fn is_set(&self, s: ArgSettings) -> bool`

Checks if one of the `ArgSettings` settings is set for the argument

#### `fn set(self, s: ArgSettings) -> Self`

Sets one of the `ArgSettings` settings for the argument

#### `fn unset(self, s: ArgSettings) -> Self`

Unsets one of the `ArgSettings` settings for the argument

## Trait Implementations

### `impl<'a, 'b> Default for Arg<'a, 'b>`

#### `fn default() -> Self`

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

#### `fn from(a: &'z Arg<'a, 'b>) -> Self`

### `impl<'a, 'b> Clone for Arg<'a, 'b>`

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

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

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