Struct clap::Arg

pub struct Arg<'a, 'b> where
    'a: 'b,  { /* 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 Args, 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. Arg::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 are officially supported in Arg::from_usage strings. 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 argument will use one of the additional 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("prog")
    .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 the auto-generated version and help arguments respectively. You may use the uppercase V or lowercase h for your own arguments, in which case clap simply will not assign those to the auto-generated version or help arguments.

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 code point. If you supply a leading - such as -c, the - 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("prog")
    .arg(Arg::with_name("config")
        .short("c"))
    .get_matches_from(vec![
        "prog", "-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 the auto-generated version and help arguments respectively. You may use the word version or help for the long form of your own arguments, in which case clap simply will not assign those to the auto-generated version or help arguments.

NOTE: Any leading - characters will be stripped

Examples

To set long use a word containing valid UTF-8 codepoints. If you supply a double 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("prog")
    .arg(Arg::with_name("cfg")
        .long("config"))
    .get_matches_from(vec![
        "prog", "--config"
    ]);

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

fn alias<S: Into<&'b str>>(self, name: S) -> Self

Allows adding a Arg alias, which function as "hidden" arguments that automatically dispatch as if this argument was used. This is more efficient, and easier than creating multiple hidden arguments as one only needs to check for the existence of this command, and not all variants.

Examples

let m = App::new("prog")
            .arg(Arg::with_name("test")
            .long("test")
            .alias("alias")
            .takes_value(true))
       .get_matches_from(vec![
            "prog", "--alias", "cool"
        ]);
assert!(m.is_present("test"));
assert_eq!(m.value_of("test"), Some("cool"));

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

Allows adding Arg aliases, which function as "hidden" arguments that automatically dispatch as if this argument was used. This is more efficient, and easier than creating multiple hidden subcommands as one only needs to check for the existence of this command, and not all variants.

Examples

let m = App::new("prog")
            .arg(Arg::with_name("test")
                    .long("test")
                    .aliases(&["do-stuff", "do-tests", "tests"])
                    .help("the file to add")
                    .required(false))
            .get_matches_from(vec![
                "prog", "--do-tests"
            ]);
assert!(m.is_present("test"));

fn visible_alias<S: Into<&'b str>>(self, name: S) -> Self

Allows adding a Arg alias that functions exactly like those defined with [Arg::alias], except that they are visible inside the help message.

Examples

let m = App::new("prog")
            .arg(Arg::with_name("test")
                .visible_alias("something-awesome")
                .long("test")
                .takes_value(true))
       .get_matches_from(vec![
            "prog", "--something-awesome", "coffee"
        ]);
assert!(m.is_present("test"));
assert_eq!(m.value_of("test"), Some("coffee"));

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

Allows adding multiple Arg aliases that functions exactly like those defined with [Arg::aliases], except that they are visible inside the help message.

Examples

let m = App::new("prog")
            .arg(Arg::with_name("test")
                .long("test")
                .visible_aliases(&["something", "awesome", "cool"]))
       .get_matches_from(vec![
            "prog", "--awesome"
        ]);
assert!(m.is_present("test"));

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

Sets the short help text of the argument that will be displayed to the user when they print the help information with -h. Typically, this is a short (one line) description of the arg.

NOTE: If only Arg::help is provided, and not Arg::long_help but the user requests --help clap will still display the contents of help appropriately

NOTE: Only Arg::help is used in completion script generation in order to be concise

Examples

Any valid UTF-8 is allowed in the help text. The one exception is when one wishes to include a newline in the help text and have the following text be properly aligned with all the other help text.

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("prog")
    .arg(Arg::with_name("cfg")
        .long("config")
        .help("Some help text describing the --config arg"))
    .get_matches_from(vec![
        "prog", "--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 long_help(self, h: &'b str) -> Self

Sets the long help text of the argument that will be displayed to the user when they print the help information with --help. Typically this a more detailed (multi-line) message that describes the arg.

NOTE: If only long_help is provided, and not Arg::help but the user requests -h clap will still display the contents of long_help appropriately

NOTE: Only Arg::help is used in completion script generation in order to be concise

Examples

Any valid UTF-8 is allowed in the help text. The one exception is when one wishes to include a newline in the help text and have the following text be properly aligned with all the other help text.

Arg::with_name("config")
    .long_help(
"The config file used by the myprog must be in JSON format
with only valid keys and may not contain other nonsense
that cannot be read by this program. Obviously I'm going on
and on, so I'll stop now.")

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("prog")
    .arg(Arg::with_name("cfg")
        .long("config")
        .long_help(
"The config file used by the myprog must be in JSON format
with only valid keys and may not contain other nonsense
that cannot be read by this program. Obviously I'm going on
and on, so I'll stop now."))
    .get_matches_from(vec![
        "prog", "--help"
    ]);

The above example displays

helptest

USAGE:
   helptest [FLAGS]

FLAGS:
   --config
        The config file used by the myprog must be in JSON format
        with only valid keys and may not contain other nonsense
        that cannot be read by this program. Obviously I'm going on
        and on, so I'll stop now.

-h, --help       
        Prints help information

-V, --version    
        Prints version information

fn last(self, l: bool) -> Self

Specifies that this arg is the last, or final, positional argument (i.e. has the highest index) and is only able to be accessed via the -- syntax (i.e. $ prog args -- last_arg). Even, if no other arguments are left to parse, if the user omits the -- syntax they will receive an UnknownArgument error. Setting an argument to .last(true) also allows one to access this arg early using the -- syntax. Accessing an arg early, even with the -- syntax is otherwise not possible.

NOTE: This will change the usage string to look like $ prog [FLAGS] [-- <ARG>] if ARG is marked as .last(true).

NOTE: This setting will imply AppSettings::DontCollapseArgsInUsage because failing to set this can make the usage string very confusing.

NOTE: This setting only applies to positional arguments, and has no affect on FLAGS / OPTIONS

CAUTION: Setting an argument to .last(true) and having child subcommands is not recommended with the exception of also using AppSettings::ArgsNegateSubcommands

Examples

Arg::with_name("args")
    .last(true)

Setting Arg::last(true) ensures the arg has the highest index of all positional args and requires that the -- syntax be used to access it early.

let res = App::new("prog")
    .arg(Arg::with_name("first"))
    .arg(Arg::with_name("second"))
    .arg(Arg::with_name("third").last(true))
    .get_matches_from_safe(vec![
        "prog", "one", "--", "three"
    ]);

assert!(res.is_ok());
let m = res.unwrap();
assert_eq!(m.value_of("third"), Some("three"));
assert!(m.value_of("second").is_none());

Even if the positional argument marked .last(true) is the only argument left to parse, failing to use the -- syntax results in an error.

let res = App::new("prog")
    .arg(Arg::with_name("first"))
    .arg(Arg::with_name("second"))
    .arg(Arg::with_name("third").last(true))
    .get_matches_from_safe(vec![
        "prog", "one", "two", "three"
    ]);

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

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 by default. This is simply because if a flag should be required, it should simply be implied as no additional information is required from user. Flags by their very nature are simply yes/no, or true/false.

Examples

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

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

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

assert!(res.is_ok());

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

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

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

fn require_equals(self, r: bool) -> Self

Requires that options use the --option=val syntax (i.e. an equals between the option and associated value) Default: false

NOTE: This setting also removes the default of allowing empty values and implies Arg::empty_values(false).

Examples

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

Setting Arg::require_equals(true) requires that the option have an equals sign between it and the associated value.

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

assert!(res.is_ok());

Setting Arg::require_equals(true) and not supplying the equals will cause an error unless Arg::empty_values(true) is set.

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

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

fn allow_hyphen_values(self, a: bool) -> Self

Allows values which start with a leading hyphen (-)

WARNING: Take caution when using this setting, combined with Arg::multiple(true) as it this becomes ambigous $ prog --arg -- -- val. All three --, --, val will be values when the user may have thought the second -- would constitute the normal, "Only positional args follow" idiom. To fix this, consider using Arg::number_of_values(1)

WARNING: When building your CLIs, consider the effects of allowing leading hyphens and the user passing in a value that matches a valid short. For example prog -opt -F where -F is supposed to be a value, yet -F is also a valid short for anther arg. Care should should be taken when designing these args. This is compounded by the ability to "stack" short args. I.e. if -val is supposed to be a value, but -v, -a, and -l are all valid shorts.

Examples

Arg::with_name("pattern")
    .allow_hyphen_values(true)

let m = App::new("prog")
    .arg(Arg::with_name("pat")
        .allow_hyphen_values(true)
        .takes_value(true)
        .long("pattern"))
    .get_matches_from(vec![
        "prog", "--pattern", "-file"
    ]);

assert_eq!(m.value_of("pat"), Some("-file"));

Not setting Arg::allow_hyphen_values(true) and supplying a value which starts with a hyphen is an error.

let res = App::new("prog")
    .arg(Arg::with_name("pat")
        .takes_value(true)
        .long("pattern"))
    .get_matches_from_safe(vec![
        "prog", "--pattern", "-file"
    ]);

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

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 Arg::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("prog")
    .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![
        "prog", "--debug"
    ]);

assert!(res.is_ok());

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

let res = App::new("prog")
    .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![
        "prog"
    ]);

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 arguments are present).

NOTE: If you wish for 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 Arg::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("prog")
    .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![
        "prog", "--debug", "-i", "file"
    ]);

assert!(res.is_ok());

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

let res = App::new("prog")
    .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![
        "prog"
    ]);

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 arguments are present).

NOTE: If you wish for 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 Arg::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("prog")
    .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![
        "prog", "--debug"
    ]);

assert!(res.is_ok());

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

let res = App::new("prog")
    .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![
        "prog"
    ]);

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("prog")
    .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![
        "prog", "--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("prog")
    .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![
        "prog", "--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 overridden 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("prog")
    .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![
        "prog", "-f", "-d", "-c"]);
            //    ^~~~~~~~~~~~^~~~~ flag is overridden 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 overridden 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 overridden 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("prog")
    .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![
        "prog", "-f", "-d", "-c"]);
            //    ^~~~~~^~~~~~~~~ flag and debug are overridden 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 overridden
                                // 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 Arg::requires(name) requires that the argument be used at runtime if the defining argument is used. If the defining argument isn't used, the other argument isn't required

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

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

Setting Arg::requires(name) and not supplying that argument is an error.

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

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

fn requires_if(self, val: &'b str, arg: &'a str) -> Self

Allows a conditional requirement. The requirement will only become valid if this arg's value equals val.

NOTE: If using YAML the values should be laid out as follows

requires_if:
    - [val, arg]

Examples

Arg::with_name("config")
    .requires_if("val", "arg")

Setting [Arg::requires_if(val, arg)] requires that the arg be used at runtime if the defining argument's value is equal to val. If the defining argument is anything other than val, the other argument isn't required.

let res = App::new("prog")
    .arg(Arg::with_name("cfg")
        .takes_value(true)
        .requires_if("my.cfg", "other")
        .long("config"))
    .arg(Arg::with_name("other"))
    .get_matches_from_safe(vec![
        "prog", "--config", "some.cfg"
    ]);

assert!(res.is_ok()); // We didn't use --config=my.cfg, so other wasn't required

Setting [Arg::requires_if(val, arg)] and setting the value to val but not supplying arg is an error.

let res = App::new("prog")
    .arg(Arg::with_name("cfg")
        .takes_value(true)
        .requires_if("my.cfg", "input")
        .long("config"))
    .arg(Arg::with_name("input"))
    .get_matches_from_safe(vec![
        "prog", "--config", "my.cfg"
    ]);

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

fn requires_ifs(self, ifs: &[(&'b str, &'a str)]) -> Self

Allows multiple conditional requirements. The requirement will only become valid if this arg's value equals val.

NOTE: If using YAML the values should be laid out as follows

requires_if:
    - [val, arg]
    - [val2, arg2]

Examples

Arg::with_name("config")
    .requires_ifs(&[
        ("val", "arg"),
        ("other_val", "arg2"),
    ])

Setting [Arg::requires_ifs(&["val", "arg"])] requires that the arg be used at runtime if the defining argument's value is equal to val. If the defining argument's value is anything other than val, arg isn't required.

let res = App::new("prog")
    .arg(Arg::with_name("cfg")
        .takes_value(true)
        .requires_ifs(&[
            ("special.conf", "opt"),
            ("other.conf", "other"),
        ])
        .long("config"))
    .arg(Arg::with_name("opt")
        .long("option")
        .takes_value(true))
    .arg(Arg::with_name("other"))
    .get_matches_from_safe(vec![
        "prog", "--config", "special.conf"
    ]);

assert!(res.is_err()); // We  used --config=special.conf so --option <val> is required
assert_eq!(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument);

fn required_if(self, arg: &'a str, val: &'b str) -> Self

Allows specifying that an argument is required conditionally. The requirement will only become valid if the specified arg's value equals val.

NOTE: If using YAML the values should be laid out as follows

required_if:
    - [arg, val]

Examples

Arg::with_name("config")
    .required_if("other_arg", "value")

Setting [Arg::required_if(arg, val)] makes this arg required if the arg is used at runtime and it's value is equal to val. If the arg's value is anything other than val, this argument isn't required.

let res = App::new("prog")
    .arg(Arg::with_name("cfg")
        .takes_value(true)
        .required_if("other", "special")
        .long("config"))
    .arg(Arg::with_name("other")
        .long("other")
        .takes_value(true))
    .get_matches_from_safe(vec![
        "prog", "--other", "not-special"
    ]);

assert!(res.is_ok()); // We didn't use --other=special, so "cfg" wasn't required

Setting [Arg::required_if(arg, val)] and having arg used with a value of val but not using this arg is an error.

let res = App::new("prog")
    .arg(Arg::with_name("cfg")
        .takes_value(true)
        .required_if("other", "special")
        .long("config"))
    .arg(Arg::with_name("other")
        .long("other")
        .takes_value(true))
    .get_matches_from_safe(vec![
        "prog", "--other", "special"
    ]);

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

fn required_ifs(self, ifs: &[(&'a str, &'b str)]) -> Self

Allows specifying that an argument is required based on multiple conditions. The conditions are set up in a (arg, val) style tuple. The requirement will only become valid if one of the specified arg's value equals it's corresponding val.

NOTE: If using YAML the values should be laid out as follows

required_if:
    - [arg, val]
    - [arg2, val2]

Examples

Arg::with_name("config")
    .required_ifs(&[
        ("extra", "val"),
        ("option", "spec")
    ])

Setting [Arg::required_ifs(&[(arg, val)])] makes this arg required if any of the args are used at runtime and it's corresponding value is equal to val. If the arg's value is anything other than val, this argument isn't required.

let res = App::new("prog")
    .arg(Arg::with_name("cfg")
        .required_ifs(&[
            ("extra", "val"),
            ("option", "spec")
        ])
        .takes_value(true)
        .long("config"))
    .arg(Arg::with_name("extra")
        .takes_value(true)
        .long("extra"))
    .arg(Arg::with_name("option")
        .takes_value(true)
        .long("option"))
    .get_matches_from_safe(vec![
        "prog", "--option", "other"
    ]);

assert!(res.is_ok()); // We didn't use --option=spec, or --extra=val so "cfg" isn't required

Setting [Arg::required_ifs(&[(arg, val)])] and having any of the args used with it's value of val but not using this arg is an error.

let res = App::new("prog")
    .arg(Arg::with_name("cfg")
        .required_ifs(&[
            ("extra", "val"),
            ("option", "spec")
        ])
        .takes_value(true)
        .long("config"))
    .arg(Arg::with_name("extra")
        .takes_value(true)
        .long("extra"))
    .arg(Arg::with_name("option")
        .takes_value(true)
        .long("option"))
    .get_matches_from_safe(vec![
        "prog", "--option", "spec"
    ]);

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: Conflicting rules and override rules take precedence over being required by default.

Examples

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

Setting [Arg::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 argument isn't required

let res = App::new("prog")
    .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![
        "prog"
    ]);

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

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

let res = App::new("prog")
    .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![
        "prog", "--config", "file.conf", "in.txt"
    ]);

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

[Arg::requires_all(&[arg, arg2])]: ./struct.Arg.html#method.requires_all

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, args which allow multiple values are delimited by commas, meaning --option=val1,val2,val3 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 turn delimiting values OFF by using Arg::use_delimiter(false)

Examples

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

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

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

fn hide_possible_values(self, hide: bool) -> Self

Specifies if the possible values of an argument should be displayed in the help text or not. Defaults to false (i.e. show possible values)

This is useful for args with many values, or ones which are explained elsewhere in the help text.

Examples

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

let m = App::new("prog")
    .arg(Arg::with_name("mode")
        .long("mode")
        .possible_values(&["fast", "slow"])
        .takes_value(true)
        .hide_possible_values(true));

If we were to run the above program with --help the [values: fast, slow] portion of the help text would be omitted.

fn hide_default_value(self, hide: bool) -> Self

Specifies if the default value of an argument should be displayed in the help text or not. Defaults to false (i.e. show default value)

This is useful when default behavior of an arg is explained elsewhere in the help text.

Examples

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

let m = App::new("connect")
    .arg(Arg::with_name("host")
        .long("host")
        .default_value("localhost")
        .hide_default_value(true));

If we were to run the above program with --help the [default: localhost] portion of the help text would be omitted.

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 Arg::short, or Arg::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 Arg::multiple(true), only the last positional 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("prog")
    .arg(Arg::with_name("mode")
        .index(1))
    .arg(Arg::with_name("debug")
        .long("debug"))
    .get_matches_from(vec![
        "prog", "--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 multiple(true) for an option with no other details, allows multiple values and multiple occurrences because it isn't possible to have 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 expected 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("prog")
    .arg(Arg::with_name("verbose")
        .multiple(true)
        .short("v"))
    .get_matches_from(vec![
        "prog", "-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("prog")
    .arg(Arg::with_name("file")
        .multiple(true)
        .takes_value(true)
        .short("F"))
    .get_matches_from(vec![
        "prog", "-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("prog")
    .arg(Arg::with_name("file")
        .multiple(true)
        .takes_value(true)
        .short("F"))
    .get_matches_from(vec![
        "prog", "-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("prog")
    .arg(Arg::with_name("file")
        .multiple(true)
        .takes_value(true)
        .short("F"))
    .arg(Arg::with_name("word")
        .index(1))
    .get_matches_from(vec![
        "prog", "-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("prog")
    .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![
        "prog", "-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 Arg::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("prog")
    .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![
        "prog", "-F", "file1", "file2", "file3", "word"
    ]);

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

fn value_terminator(self, term: &'b str) -> Self

Specifies a value that stops parsing multiple values of a give argument. By default when one sets multiple(true) on an argument, clap will continue parsing values for that argument until it reaches another valid argument, or one of the other more specific settings for multiple values is used (such as min_values, max_values or number_of_values).

NOTE: This setting only applies to options and positional arguments

NOTE: When the terminator is passed in on the command line, it is not stored as one of the values

Examples

Arg::with_name("vals")
    .takes_value(true)
    .multiple(true)
    .value_terminator(";")

The following example uses two arguments, a sequence of commands, and the location in which to perform them

let m = App::new("prog")
    .arg(Arg::with_name("cmds")
        .multiple(true)
        .allow_hyphen_values(true)
        .value_terminator(";"))
    .arg(Arg::with_name("location"))
    .get_matches_from(vec![
        "prog", "find", "-type", "f", "-name", "special", ";", "/home/clap"
    ]);
let cmds: Vec<_> = m.values_of("cmds").unwrap().collect();
assert_eq!(&cmds, &["find", "-type", "f", "-name", "special"]);
assert_eq!(m.value_of("location"), Some("/home/clap"));

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 ArgMatches::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("prog")
    .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![
        "prog", "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 Arg::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("prog")
    .arg(Arg::with_name("cfg")
        .long("config")
        .short("v")
        .empty_values(false))
    .get_matches_from_safe(vec![
        "prog", "--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("prog")
    .arg(Arg::with_name("cfg")
        .long("config")
        .hidden(true)
        .help("Some help text describing the --config arg"))
    .get_matches_from(vec![
        "prog", "--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("prog")
    .arg(Arg::with_name("mode")
        .long("mode")
        .takes_value(true)
        .possible_values(&["fast", "slow", "medium"]))
    .get_matches_from(vec![
        "prog", "--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("prog")
    .arg(Arg::with_name("mode")
        .long("mode")
        .takes_value(true)
        .possible_values(&["fast", "slow", "medium"]))
    .get_matches_from_safe(vec![
        "prog", "--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.

NOTE: This setting only applies to options and positional arguments

Examples

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

let m = App::new("prog")
    .arg(Arg::with_name("mode")
        .long("mode")
        .takes_value(true)
        .possible_value("fast")
        .possible_value("slow")
        .possible_value("medium"))
    .get_matches_from(vec![
        "prog", "--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("prog")
    .arg(Arg::with_name("mode")
        .long("mode")
        .takes_value(true)
        .possible_value("fast")
        .possible_value("slow")
        .possible_value("medium"))
    .get_matches_from_safe(vec![
        "prog", "--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 ArgGroup 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("prog")
    .arg(Arg::with_name("debug")
        .long("debug")
        .group("mode"))
    .arg(Arg::with_name("verbose")
        .long("verbose")
        .group("mode"))
    .get_matches_from(vec![
        "prog", "--debug"
    ]);
assert!(m.is_present("mode"));

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

Specifies the names of multiple ArgGroup's the argument belongs to.

Examples

Arg::with_name("debug")
    .long("debug")
    .groups(&["mode", "verbosity"])

Arguments can be members of multiple groups and then the group checked as if it was one of said arguments.

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

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 Arg::multiple(true) to be set. Setting Arg::multiple(true) would allow -f <file> <file> <file> -f <file> <file> <file> where as not setting Arg::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("prog")
    .arg(Arg::with_name("file")
        .takes_value(true)
        .number_of_values(2)
        .short("F"))
    .get_matches_from_safe(vec![
        "prog", "-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, and return 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 as all errors will appear as error: Invalid value for '<arg>': <YOUR MESSAGE> where <arg> is replaced by the actual arg, and <YOUR MESSAGE> is the String you return as the error.

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("prog")
    .arg(Arg::with_name("file")
        .index(1)
        .validator(has_at))
    .get_matches_from_safe(vec![
        "prog", "some@file"
    ]);
assert!(res.is_ok());
assert_eq!(res.unwrap().value_of("file"), Some("some@file"));

fn validator_os<F>(self, f: F) -> Self where
    F: Fn(&OsStr) -> Result<(), OsString> + 'static, 

Works identically to Validator but is intended to be used with values that could contain non UTF-8 formatted strings.

Examples

fn has_ampersand(v: &OsStr) -> Result<(), OsString> {
    if v.as_bytes().iter().any(|b| *b == b'&') { return Ok(()); }
    Err(OsString::from("The value did not contain the required & sigil"))
}
let res = App::new("prog")
    .arg(Arg::with_name("file")
        .index(1)
        .validator_os(has_ampersand))
    .get_matches_from_safe(vec![
        "prog", "Fish & chips"
    ]);
assert!(res.is_ok());
assert_eq!(res.unwrap().value_of("file"), Some("Fish & chips"));

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 Arg::multiple(true). This is because -o val -o val is multiple occurrences but a single value and -o val1 val2 is a single occurence with multiple values. For positional arguments this does set Arg::multiple(true) because there is no way to determine the difference between multiple occurences 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("prog")
    .arg(Arg::with_name("file")
        .takes_value(true)
        .max_values(3)
        .short("F"))
    .get_matches_from_safe(vec![
        "prog", "-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("prog")
    .arg(Arg::with_name("file")
        .takes_value(true)
        .max_values(2)
        .short("F"))
    .get_matches_from_safe(vec![
        "prog", "-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 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 Arg::multiple(true). This is because -o val -o val is multiple occurrences but a single value and -o val1 val2 is a single occurence with multiple values. For positional arguments this does set Arg::multiple(true) because there is no way to determine the difference between multiple occurences 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("prog")
    .arg(Arg::with_name("file")
        .takes_value(true)
        .min_values(2)
        .short("F"))
    .get_matches_from_safe(vec![
        "prog", "-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 minimum number of values is an error

let res = App::new("prog")
    .arg(Arg::with_name("file")
        .takes_value(true)
        .min_values(2)
        .short("F"))
    .get_matches_from_safe(vec![
        "prog", "-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 argument should allow grouping of multiple values via a delimiter. I.e. should --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 default is false. When set to true the default Arg::value_delimiter is the comma ,.

Examples

The following example shows the default behavior.

let delims = App::new("prog")
    .arg(Arg::with_name("option")
        .long("option")
        .use_delimiter(true)
        .takes_value(true))
    .get_matches_from(vec![
        "prog", "--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. This is the default behavior

let nodelims = App::new("prog")
    .arg(Arg::with_name("option")
        .long("option")
        .use_delimiter(false)
        .takes_value(true))
    .get_matches_from(vec![
        "prog", "--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 require_delimiter(self, d: bool) -> Self

Specifies that multiple values may only be set using the delimiter. This means if an if an option is encountered, and no delimiter is found, it automatically assumed that no additional values for that option follow. This is unlike the default, where it is generally assumed that more values will follow regardless of whether or not a delimiter is used.

NOTE: The default is false.

NOTE: Setting this to true implies Arg::use_delimiter(true)

NOTE: It's a good idea to inform the user that use of a delimiter is required, either through help text or other means.

Examples

These examples demonstrate what happens when require_delimiter(true) is used. Notice everything works in this first example, as we use a delimiter, as expected.

let delims = App::new("prog")
    .arg(Arg::with_name("opt")
        .short("o")
        .takes_value(true)
        .multiple(true)
        .require_delimiter(true))
    .get_matches_from(vec![
        "prog", "-o", "val1,val2,val3",
    ]);

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

In this next example, we will not use a delimiter. Notice it's now an error.

let res = App::new("prog")
    .arg(Arg::with_name("opt")
        .short("o")
        .takes_value(true)
        .multiple(true)
        .require_delimiter(true))
    .get_matches_from_safe(vec![
        "prog", "-o", "val1", "val2", "val3",
    ]);

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

What's happening is -o is getting val1, and because delimiters are required yet none were present, it stops parsing -o. At this point it reaches val2 and because no positional arguments have been defined, it's an error of an unexpected argument.

In this final example, we contrast the above with clap's default behavior where the above is not an error.

let delims = App::new("prog")
    .arg(Arg::with_name("opt")
        .short("o")
        .takes_value(true)
        .multiple(true))
    .get_matches_from(vec![
        "prog", "-o", "val1", "val2", "val3",
    ]);

assert!(delims.is_present("opt"));
assert_eq!(delims.values_of("opt").unwrap().collect::<Vec<_>>(), ["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 m = App::new("prog")
    .arg(Arg::with_name("config")
        .short("c")
        .long("config")
        .value_delimiter(";"))
    .get_matches_from(vec![
        "prog", "--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 Arg::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 Arg::multiple(true).

Examples

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

let m = App::new("prog")
    .arg(Arg::with_name("io")
        .long("io-files")
        .value_names(&["INFILE", "OUTFILE"]))
    .get_matches_from(vec![
        "prog", "--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 documentation. 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 m = App::new("prog")
    .arg(Arg::with_name("config")
        .long("config")
        .value_name("FILE"))
    .get_matches_from(vec![
        "prog", "--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 ArgMatches::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 setting is perfectly compatible with Arg::default_value_if but slightly different. Arg::default_value only takes affect when the user has not provided this arg at runtime. Arg::default_value_if however only takes affect when the user has not provided a value at runtime and these other conditions are met as well. If you have set Arg::default_value and Arg::default_value_if, and the user did not provide a this arg at runtime, nor did were the conditions met for Arg::default_value_if, the Arg::default_value will be applied.

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

NOTE: This setting effectively disables AppSettings::ArgRequiredElseHelp if used in conjuction as it ensures that some argument will always be present.

Examples

First we use the default value without providing any value at runtime.

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

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

Next we provide a value at runtime to override the default.

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

assert_eq!(m.value_of("opt"), Some("non_default"));
assert!(m.is_present("opt"));
assert_eq!(m.occurrences_of("opt"), 1);

fn default_value_os(self, val: &'a OsStr) -> Self

Provides a default value in the exact same manner as Arg::default_value only using OsStrs instead.

fn default_value_if(
    self,
    arg: &'a str,
    val: Option<&'b str>,
    default: &'b str
) -> Self

Specifies the value of the argument if arg has been used at runtime. If val is set to None, arg only needs to be present. If val is set to "some-val" then arg must be present at runtime and have the value val.

NOTE: This setting is perfectly compatible with Arg::default_value but slightly different. Arg::default_value only takes affect when the user has not provided this arg at runtime. This setting however only takes affect when the user has not provided a value at runtime and these other conditions are met as well. If you have set Arg::default_value and Arg::default_value_if, and the user did not provide a this arg at runtime, nor did were the conditions met for Arg::default_value_if, the Arg::default_value will be applied.

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

NOTE: If using YAML the values should be laid out as follows (None can be represented as null in YAML)

default_value_if:
    - [arg, val, default]

Examples

First we use the default value only if another arg is present at runtime.

let m = App::new("prog")
    .arg(Arg::with_name("flag")
        .long("flag"))
    .arg(Arg::with_name("other")
        .long("other")
        .default_value_if("flag", None, "default"))
    .get_matches_from(vec![
        "prog", "--flag"
    ]);

assert_eq!(m.value_of("other"), Some("default"));

Next we run the same test, but without providing --flag.

let m = App::new("prog")
    .arg(Arg::with_name("flag")
        .long("flag"))
    .arg(Arg::with_name("other")
        .long("other")
        .default_value_if("flag", None, "default"))
    .get_matches_from(vec![
        "prog"
    ]);

assert_eq!(m.value_of("other"), None);

Now lets only use the default value if --opt contains the value special.

let m = App::new("prog")
    .arg(Arg::with_name("opt")
        .takes_value(true)
        .long("opt"))
    .arg(Arg::with_name("other")
        .long("other")
        .default_value_if("opt", Some("special"), "default"))
    .get_matches_from(vec![
        "prog", "--opt", "special"
    ]);

assert_eq!(m.value_of("other"), Some("default"));

We can run the same test and provide any value other than special and we won't get a default value.

let m = App::new("prog")
    .arg(Arg::with_name("opt")
        .takes_value(true)
        .long("opt"))
    .arg(Arg::with_name("other")
        .long("other")
        .default_value_if("opt", Some("special"), "default"))
    .get_matches_from(vec![
        "prog", "--opt", "hahaha"
    ]);

assert_eq!(m.value_of("other"), None);

fn default_value_if_os(
    self,
    arg: &'a str,
    val: Option<&'b OsStr>,
    default: &'b OsStr
) -> Self

Provides a conditional default value in the exact same manner as Arg::default_value_if only using OsStrs instead.

fn default_value_ifs(self, ifs: &[(&'a str, Option<&'b str>, &'b str)]) -> Self

Specifies multiple values and conditions in the same manner as [Arg::default_value_if]. The method takes a slice of tuples in the (arg, Option<val>, default) format.

NOTE: The conditions are stored in order and evaluated in the same order. I.e. the first if multiple conditions are true, the first one found will be applied and the ultimate value.

NOTE: If using YAML the values should be laid out as follows

default_value_if:
    - [arg, val, default]
    - [arg2, null, default2]

Examples

First we use the default value only if another arg is present at runtime.

let m = App::new("prog")
    .arg(Arg::with_name("flag")
        .long("flag"))
    .arg(Arg::with_name("opt")
        .long("opt")
        .takes_value(true))
    .arg(Arg::with_name("other")
        .long("other")
        .default_value_ifs(&[
            ("flag", None, "default"),
            ("opt", Some("channal"), "chan"),
        ]))
    .get_matches_from(vec![
        "prog", "--opt", "channal"
    ]);

assert_eq!(m.value_of("other"), Some("chan"));

Next we run the same test, but without providing --flag.

let m = App::new("prog")
    .arg(Arg::with_name("flag")
        .long("flag"))
    .arg(Arg::with_name("other")
        .long("other")
        .default_value_ifs(&[
            ("flag", None, "default"),
            ("opt", Some("channal"), "chan"),
        ]))
    .get_matches_from(vec![
        "prog"
    ]);

assert_eq!(m.value_of("other"), None);

We can also see that these values are applied in order, and if more than one condition is true, only the first evaluatd "wins"

let m = App::new("prog")
    .arg(Arg::with_name("flag")
        .long("flag"))
    .arg(Arg::with_name("opt")
        .long("opt")
        .takes_value(true))
    .arg(Arg::with_name("other")
        .long("other")
        .default_value_ifs(&[
            ("flag", None, "default"),
            ("opt", Some("channal"), "chan"),
        ]))
    .get_matches_from(vec![
        "prog", "--opt", "channal", "--flag"
    ]);

assert_eq!(m.value_of("other"), Some("default"));

fn default_value_ifs_os(
    self,
    ifs: &[(&'a str, Option<&'b OsStr>, &'b OsStr)]
) -> Self

Provides multiple conditional default values in the exact same manner as Arg::default_value_ifs only using OsStrs instead.

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("prog")
    .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![
        "prog", "--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("prog")
    .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![
        "prog", "--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> where
    'a: 'b, 

fn default() -> Arg<'a, 'b>

Returns the "default value" for a type.

impl<'a, 'b> Clone for Arg<'a, 'b> where
    'a: 'b, 

fn clone(&self) -> Arg<'a, 'b>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

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

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

Performs the conversion.

impl<'n, 'e> PartialEq for Arg<'n, 'e>

fn eq(&self, other: &Arg<'n, 'e>) -> bool

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

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.