Struct clap::Arg

pub struct Arg<'help> { /* 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::new("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!(-i --input <FILE> "Provides an input file to the program");

Implementations

impl<'help> Arg<'help>

pub fn new<S: Into<&'help str>>(n: S) -> Self

Create a new Arg with a unique name.

The name is used to check 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::new("config")

pub fn name<S: Into<&'help str>>(self, n: S) -> Self

Set the identifier used for referencing this argument in the clap API.

See Arg::new for more details.

pub fn short(self, s: char) -> Self

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

By default V and h are used by 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.

Examples

When calling short, use a single valid UTF-8 character which will allow using the argument via a single hyphen (-) such as -c:

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

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

pub fn long(self, l: &'help str) -> Self

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

By default version and help are used by 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. 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).

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

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

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

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

Add an alias, which functions as a hidden long flag.

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::new("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"));

pub fn short_alias(self, name: char) -> Self

Add an alias, which functions as a hidden short flag.

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::new("test")
            .short('t')
            .short_alias('e')
            .takes_value(true))
       .get_matches_from(vec![
            "prog", "-e", "cool"
        ]);
assert!(m.is_present("test"));
assert_eq!(m.value_of("test"), Some("cool"));

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

Add aliases, which function as hidden long flags.

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::new("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"));

pub fn short_aliases(self, names: &[char]) -> Self

Add aliases, which functions as a hidden short flag.

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::new("test")
                    .short('t')
                    .short_aliases(&['e', 's'])
                    .help("the file to add")
                    .required(false))
            .get_matches_from(vec![
                "prog", "-s"
            ]);
assert!(m.is_present("test"));

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

Add an alias, which functions as a visible long flag.

Like Arg::alias, except that they are visible inside the help message.

Examples

let m = App::new("prog")
            .arg(Arg::new("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"));

pub fn visible_short_alias(self, name: char) -> Self

Add an alias, which functions as a visible short flag.

Like Arg::short_alias, except that they are visible inside the help message.

Examples

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

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

Add aliases, which function as visible long flags.

Like Arg::aliases, except that they are visible inside the help message.

Examples

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

pub fn visible_short_aliases(self, names: &[char]) -> Self

Add aliases, which function as visible short flags.

Like Arg::short_aliases, except that they are visible inside the help message.

Examples

let m = App::new("prog")
            .arg(Arg::new("test")
                .long("test")
                .visible_short_aliases(&['t', 'e']))
       .get_matches_from(vec![
            "prog", "-t"
        ]);
assert!(m.is_present("test"));

pub fn index(self, idx: usize) -> 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: 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: This is only meant to be used for positional arguments and shouldn’t to be used with Arg::short or Arg::long.

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

Panics

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::new("config")
    .index(1)

let m = App::new("prog")
    .arg(Arg::new("mode")
        .index(1))
    .arg(Arg::new("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

pub fn last(self, yes: bool) -> Self

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 [OPTIONS] [-- <ARG>] if ARG is marked as .last(true).

NOTE: This setting will imply crate::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 effect on OPTIONS

NOTE: Setting this requires Arg::takes_value

CAUTION: Using this setting and having child subcommands is not recommended with the exception of also using crate::AppSettings::ArgsNegateSubcommands (or crate::AppSettings::SubcommandsNegateReqs if the argument marked Last is also marked Arg::required)

Examples

Arg::new("args")
    .takes_value(true)
    .last(true)

Setting last 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::new("first"))
    .arg(Arg::new("second"))
    .arg(Arg::new("third")
        .takes_value(true)
        .last(true))
    .try_get_matches_from(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 is the only argument left to parse, failing to use the -- syntax results in an error.

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

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

pub fn required(self, yes: bool) -> Self

Specifies that the argument must be present.

Required by default means it is required, when no other conflicting rules or overrides have been evaluated. Conflicting rules take precedence over being required.

Pro tip: Flags (i.e. not positional, or arguments that take values) shouldn’t be required by default. This is because if a flag were to be required, it should simply be implied. No additional information is required from user. Flags by their very nature are simply boolean on/off switches. The only time a user should be required to use a flag is if the operation is destructive in nature, and the user is essentially proving to you, “Yes, I know what I’m doing.”

Examples

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

Setting required requires that the argument be used at runtime.

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

assert!(res.is_ok());

Setting required and then not supplying that argument at runtime is an error.

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

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

pub fn requires<T: Key>(self, arg_id: T) -> Self

Sets an argument 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

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

Examples

Arg::new("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::new("cfg")
        .takes_value(true)
        .requires("input")
        .long("config"))
    .arg(Arg::new("input")
        .index(1))
    .try_get_matches_from(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::new("cfg")
        .takes_value(true)
        .requires("input")
        .long("config"))
    .arg(Arg::new("input")
        .index(1))
    .try_get_matches_from(vec![
        "prog", "--config", "file.conf"
    ]);

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

pub fn exclusive(self, yes: bool) -> Self

This argument must be passed alone; it conflicts with all other arguments.

Examples

Arg::new("config")
    .exclusive(true)

Setting an exclusive argument and having any other arguments present at runtime is an error.

let res = App::new("prog")
    .arg(Arg::new("exclusive")
        .takes_value(true)
        .exclusive(true)
        .long("exclusive"))
    .arg(Arg::new("debug")
        .long("debug"))
    .arg(Arg::new("input")
        .index(1))
    .try_get_matches_from(vec![
        "prog", "--exclusive", "file.conf", "file.txt"
    ]);

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

pub fn global(self, yes: bool) -> Self

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

NOTE: Global arguments only propagate down, not up (to parent commands), however their values once a user uses them will be propagated back up to parents. In effect, this means one should define all global arguments at the top level, however it doesn’t matter where the user uses the global argument.

Examples

Assume an application 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::new("verb")
        .long("verbose")
        .short('v')
        .global(true))
    .subcommand(App::new("test"))
    .subcommand(App::new("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"));

pub fn multiple_occurrences(self, yes: 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 or arguments that take a value, this does not affect how many values they can accept. (i.e. only one at a time is allowed)

For example, --opt val1 --opt val2 is allowed, but --opt val1 val2 is not.

Examples

An example with flags

let m = App::new("prog")
    .arg(Arg::new("verbose")
        .multiple_occurrences(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::new("file")
        .multiple_occurrences(true)
        .takes_value(true)
        .short('F'))
    .get_matches_from(vec![
        "prog", "-F", "file1", "-F", "file2", "-F", "file3"
    ]);

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

pub fn max_occurrences(self, qty: usize) -> Self

The maximum number of occurrences for this argument.

For example, if you had a -v flag and you wanted up to 3 levels of verbosity you would set .max_occurrences(3), and this argument would be satisfied if the user provided it once or twice or thrice.

NOTE: This implicitly sets Arg::multiple_occurrences(true) if the value is greater than 1.

Examples

Arg::new("verbosity")
    .short('v')
    .max_occurrences(3);

Supplying less than the maximum number of arguments is allowed

let res = App::new("prog")
    .arg(Arg::new("verbosity")
        .max_occurrences(3)
        .short('v'))
    .try_get_matches_from(vec![
        "prog", "-vvv"
    ]);

assert!(res.is_ok());
let m = res.unwrap();
assert_eq!(m.occurrences_of("verbosity"), 3);

Supplying more than the maximum number of arguments is an error

let res = App::new("prog")
    .arg(Arg::new("verbosity")
        .max_occurrences(2)
        .short('v'))
    .try_get_matches_from(vec![
        "prog", "-vvv"
    ]);

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

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

Check if the ArgSettings variant is currently set on the argument.

pub fn setting<F>(self, setting: F) -> Self where
    F: Into<ArgFlags>, 

Apply a setting to the argument.

See ArgSettings for a full list of possibilities and examples.

Examples

Arg::new("config")
    .setting(ArgSettings::Required)
    .setting(ArgSettings::TakesValue)

Arg::new("config")
    .setting(ArgSettings::Required | ArgSettings::TakesValue)

pub fn unset_setting<F>(self, setting: F) -> Self where
    F: Into<ArgFlags>, 

Remove a setting from the argument.

See ArgSettings for a full list of possibilities and examples.

Examples

Arg::new("config")
    .unset_setting(ArgSettings::Required)
    .unset_setting(ArgSettings::TakesValue)

Arg::new("config")
    .unset_setting(ArgSettings::Required | ArgSettings::TakesValue)

impl<'help> Arg<'help>

Value handling

pub fn takes_value(self, yes: 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

let m = App::new("prog")
    .arg(Arg::new("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"));

pub fn multiple_values(self, yes: bool) -> Self

Specifies that the argument may have an unknown number of values

Without any other settings, this argument may appear only once.

For example, --opt val1 val2 is allowed, but --opt val1 val2 --opt val3 is not.

NOTE: Setting this requires Arg::takes_value.

WARNING:

Setting multiple_values for an argument that takes a value, but with no other details can be dangerous in some circumstances. Because multiple values are allowed, --option val1 val2 val3 is perfectly valid. Be careful when designing a CLI where positional arguments are also expected as clap will continue parsing values until one of the following happens:

• It reaches the maximum number of values
• It reaches a specific number of values
• It finds another flag or option (i.e. something that starts with a -)
• It reaches a value terminator is reached

Alternatively, require a delimiter between values.

WARNING:

When using args with multiple_values and subcommands, one needs to consider the possibility of an argument value being the same as a valid subcommand. By default clap will parse the argument in question as a value only if a value is possible at that moment. Otherwise it will be parsed as a subcommand. In effect, this means using multiple_values with no additional parameters and a value that coincides with a subcommand name, the subcommand cannot be called unless another argument is passed between them.

As an example, consider a CLI with an option --ui-paths=<paths>... and subcommand signer

The following would be parsed as values to --ui-paths.

$ program --ui-paths path1 path2 signer

This is because --ui-paths accepts multiple values. clap will continue parsing values until another argument is reached and it knows --ui-paths is done parsing.

By adding additional parameters to --ui-paths we can solve this issue. Consider adding Arg::number_of_values(1) or using only Arg::multiple_occurrences. The following are all valid, and signer is parsed as a subcommand in the first case, but a value in the second case.

$ program --ui-paths path1 signer
$ program --ui-paths path1 --ui-paths signer signer

Examples

An example with options

let m = App::new("prog")
    .arg(Arg::new("file")
        .takes_value(true)
        .multiple_values(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"]);

Although multiple_values has been specified, we cannot use the argument more than once.

let res = App::new("prog")
    .arg(Arg::new("file")
        .takes_value(true)
        .multiple_values(true)
        .short('F'))
    .try_get_matches_from(vec![
        "prog", "-F", "file1", "-F", "file2", "-F", "file3"
    ]);

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

A common mistake is to define an option which allows multiple values, and a positional argument.

let m = App::new("prog")
    .arg(Arg::new("file")
        .takes_value(true)
        .multiple_values(true)
        .short('F'))
    .arg(Arg::new("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 limit how many values with a maximum, or specific number, or to say Arg::multiple_occurrences is ok, but multiple values is not.

let m = App::new("prog")
    .arg(Arg::new("file")
        .takes_value(true)
        .multiple_occurrences(true)
        .short('F'))
    .arg(Arg::new("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, let’s fix the above error and get a pretty message to the user :)

let res = App::new("prog")
    .arg(Arg::new("file")
        .takes_value(true)
        .multiple_occurrences(true)
        .short('F'))
    .arg(Arg::new("word")
        .index(1))
    .try_get_matches_from(vec![
        "prog", "-F", "file1", "file2", "file3", "word"
    ]);

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

pub fn number_of_values(self, qty: usize) -> Self

The number of values allowed for 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_occurrences(true) to be set. Setting Arg::multiple_occurrences(true) would allow -f <file> <file> <file> -f <file> <file> <file> where as not setting it would only allow one occurrence of this argument.

NOTE: implicitly sets [Arg::takes_value(true)] and [Arg::multiple_values(true)].

Examples

Arg::new("file")
    .short('f')
    .number_of_values(3);

Not supplying the correct number of values is an error

let res = App::new("prog")
    .arg(Arg::new("file")
        .takes_value(true)
        .number_of_values(2)
        .short('F'))
    .try_get_matches_from(vec![
        "prog", "-F", "file1"
    ]);

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

pub fn max_values(self, qty: usize) -> Self

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_occurrences(true). This is because -o val -o val is multiple occurrences but a single value and -o val1 val2 is a single occurrence with multiple values. For positional arguments this does set Arg::multiple_occurrences(true) because there is no way to determine the difference between multiple occurrences and multiple values.

Examples

Arg::new("file")
    .short('f')
    .max_values(3);

Supplying less than the maximum number of values is allowed

let res = App::new("prog")
    .arg(Arg::new("file")
        .takes_value(true)
        .max_values(3)
        .short('F'))
    .try_get_matches_from(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::new("file")
        .takes_value(true)
        .max_values(2)
        .short('F'))
    .try_get_matches_from(vec![
        "prog", "-F", "file1", "file2", "file3"
    ]);

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

pub fn min_values(self, qty: usize) -> Self

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_occurrences(true). This is because -o val -o val is multiple occurrences but a single value and -o val1 val2 is a single occurrence with multiple values. For positional arguments this does set Arg::multiple_occurrences(true) because there is no way to determine the difference between multiple occurrences and multiple values.

Examples

Arg::new("file")
    .short('f')
    .min_values(3);

Supplying more than the minimum number of values is allowed

let res = App::new("prog")
    .arg(Arg::new("file")
        .takes_value(true)
        .min_values(2)
        .short('F'))
    .try_get_matches_from(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::new("file")
        .takes_value(true)
        .min_values(2)
        .short('F'))
    .try_get_matches_from(vec![
        "prog", "-F", "file1"
    ]);

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

pub fn value_name(self, name: &'help str) -> Self

Placeholder for the argument’s value in the help message / usage.

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::new("cfg")
    .long("config")
    .value_name("FILE")

let m = App::new("prog")
    .arg(Arg::new("config")
        .long("config")
        .value_name("FILE")
        .help("Some help text"))
    .get_matches_from(vec![
        "prog", "--help"
    ]);

Running the above program produces the following output

valnames

USAGE:
   valnames [OPTIONS]

OPTIONS:
    --config <FILE>     Some help text
    -h, --help          Print help information
    -V, --version       Print version information

pub fn value_names(self, names: &[&'help str]) -> Self

Placeholders for the argument’s values in the help message / usage.

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: implicitly sets Arg::takes_value(true) and Arg::multiple_values(true).

Examples

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

let m = App::new("prog")
    .arg(Arg::new("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 [OPTIONS]

OPTIONS:
    -h, --help                       Print help information
    --io-files <INFILE> <OUTFILE>    Some help text
    -V, --version                    Print version information

pub fn value_hint(self, value_hint: ValueHint) -> Self

Provide the shell a hint about how to complete this argument.

See ValueHint for more information.

NOTE: implicitly sets [Arg::takes_value(true)].

For example, to take a username as argument:

Arg::new("user")
    .short('u')
    .long("user")
    .value_hint(ValueHint::Username);

To take a full command line and its arguments (for example, when writing a command wrapper):

App::new("prog")
    .setting(AppSettings::TrailingVarArg)
    .arg(
        Arg::new("command")
            .takes_value(true)
            .multiple_values(true)
            .value_hint(ValueHint::CommandWithArguments)
    );

pub fn validator<F, O, E>(self, f: F) -> Self where
    F: FnMut(&str) -> Result<O, E> + Send + 'help,
    E: Into<Box<dyn Error + Send + Sync + 'static>>, 

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 Arc pointers. And the value to be checked will be allocated an extra time in order to be passed to the closure. This performance hit is extremely minimal in the grand scheme of things.

Examples

fn has_at(v: &str) -> 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::new("file")
        .index(1)
        .validator(has_at))
    .try_get_matches_from(vec![
        "prog", "some@file"
    ]);
assert!(res.is_ok());
assert_eq!(res.unwrap().value_of("file"), Some("some@file"));

pub fn validator_os<F, O, E>(self, f: F) -> Self where
    F: FnMut(&OsStr) -> Result<O, E> + Send + 'help,
    E: Into<Box<dyn Error + Send + Sync + 'static>>, 

Perform a custom validation on the argument value.

See validator.

Examples

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

pub fn possible_value<T>(self, value: T) -> Self where
    T: Into<PossibleValue<'help>>, 

Add a possible value for this argument.

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

NOTE: You can use both strings directly or use PossibleValue if you want more control over single possible values.

Examples

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

The same using PossibleValue:

Arg::new("mode").takes_value(true)
    .possible_value(PossibleValue::new("fast"))
// value with a help text
    .possible_value(PossibleValue::new("slow").help("not that fast"))
// value that is hidden from completion and help text
    .possible_value(PossibleValue::new("medium").hide(true))

let m = App::new("prog")
    .arg(Arg::new("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::new("mode")
        .long("mode")
        .takes_value(true)
        .possible_value("fast")
        .possible_value("slow")
        .possible_value("medium"))
    .try_get_matches_from(vec![
        "prog", "--mode", "wrong"
    ]);
assert!(res.is_err());
assert_eq!(res.unwrap_err().kind, ErrorKind::InvalidValue);

pub fn possible_values<I, T>(self, values: I) -> Self where
    I: IntoIterator<Item = T>,
    T: Into<PossibleValue<'help>>, 

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

NOTE: You can use both strings directly or use PossibleValue if you want more control over single possible values.

See also hide_possible_values.

Examples

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

The same using PossibleValue:

Arg::new("mode").takes_value(true).possible_values([
    PossibleValue::new("fast"),
// value with a help text
    PossibleValue::new("slow").help("not that fast"),
// value that is hidden from completion and help text
    PossibleValue::new("medium").hide(true),
])

let m = App::new("prog")
    .arg(Arg::new("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::new("mode")
        .long("mode")
        .takes_value(true)
        .possible_values(["fast", "slow", "medium"]))
    .try_get_matches_from(vec![
        "prog", "--mode", "wrong"
    ]);
assert!(res.is_err());
assert_eq!(res.unwrap_err().kind, ErrorKind::InvalidValue);

pub fn ignore_case(self, yes: bool) -> Self

Match values against Arg::possible_values without matching case.

When other arguments are conditionally required based on the value of a case-insensitive argument, the equality check done by Arg::required_if_eq, Arg::required_if_eq_any, or Arg::required_if_eq_all is case-insensitive.

NOTE: Setting this requires Arg::takes_value

NOTE: To do unicode case folding, enable the unicode feature flag.

Examples

let m = App::new("pv")
    .arg(Arg::new("option")
        .long("--option")
        .takes_value(true)
        .ignore_case(true)
        .possible_value("test123"))
    .get_matches_from(vec![
        "pv", "--option", "TeSt123",
    ]);

assert!(m.value_of("option").unwrap().eq_ignore_ascii_case("test123"));

This setting also works when multiple values can be defined:

let m = App::new("pv")
    .arg(Arg::new("option")
        .short('o')
        .long("--option")
        .takes_value(true)
        .ignore_case(true)
        .multiple_values(true)
        .possible_values(&["test123", "test321"]))
    .get_matches_from(vec![
        "pv", "--option", "TeSt123", "teST123", "tESt321"
    ]);

let matched_vals = m.values_of("option").unwrap().collect::<Vec<_>>();
assert_eq!(&*matched_vals, &["TeSt123", "teST123", "tESt321"]);

pub fn allow_hyphen_values(self, yes: bool) -> Self

Allows values which start with a leading hyphen (-)

NOTE: Setting this requires Arg::takes_value

WARNING: Take caution when using this setting combined with Arg::multiple_values, as this becomes ambiguous $ 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::multiple_occurrences which only allows a single value at a time.

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 another arg. Care 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

let m = App::new("prog")
    .arg(Arg::new("pat")
        .takes_value(true)
        .allow_hyphen_values(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::new("pat")
        .takes_value(true)
        .long("pattern"))
    .try_get_matches_from(vec![
        "prog", "--pattern", "-file"
    ]);

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

pub fn allow_invalid_utf8(self, yes: bool) -> Self

The argument’s values can be invalid UTF-8 and should not be treated as an error.

NOTE: Using argument values with invalid UTF-8 code points requires using ArgMatches::value_of_os, ArgMatches::values_of_os, ArgMatches::value_of_lossy, or ArgMatches::values_of_lossy for those particular arguments which may contain invalid UTF-8 values.

NOTE: Setting this requires Arg::takes_value

Examples

use std::ffi::OsString;
use std::os::unix::ffi::{OsStrExt,OsStringExt};
let r = App::new("myprog")
   .arg(Arg::new("arg").allow_invalid_utf8(true))
   .try_get_matches_from(vec![
       OsString::from("myprog"),
       OsString::from_vec(vec![0xe9])
   ]);

assert!(r.is_ok());
let m = r.unwrap();
assert_eq!(m.value_of_os("arg").unwrap().as_bytes(), &[0xe9]);

pub fn forbid_empty_values(self, yes: bool) -> Self

Don’t allow an argument to accept explicitly empty values.

An empty value must be specified at the command line with an explicit "", '', or --option=

NOTE: By default empty values are allowed.

NOTE: Setting this requires Arg::takes_value.

Examples

The default is allowing empty values.

let res = App::new("prog")
    .arg(Arg::new("cfg")
        .long("config")
        .short('v')
        .takes_value(true))
    .try_get_matches_from(vec![
        "prog", "--config="
    ]);

assert!(res.is_ok());
assert_eq!(res.unwrap().value_of("cfg"), Some(""));

By adding this setting, we can forbid empty values.

let res = App::new("prog")
    .arg(Arg::new("cfg")
        .long("config")
        .short('v')
        .takes_value(true)
        .forbid_empty_values(true))
    .try_get_matches_from(vec![
        "prog", "--config="
    ]);

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

pub fn require_equals(self, yes: bool) -> Self

Requires that options use the --option=val syntax

i.e. an equals between the option and associated value.

NOTE: Setting this requires Arg::takes_value

Examples

Setting require_equals requires that the option have an equals sign between it and the associated value.

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

assert!(res.is_ok());

Setting require_equals and not supplying the equals will cause an error.

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

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

pub fn use_delimiter(self, yes: bool) -> Self

Specifies that 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: When this setting is used, it will default Arg::value_delimiter to the comma ,.

NOTE: Implicitly sets Arg::takes_value

Examples

The following example shows the default behavior.

let delims = App::new("prog")
    .arg(Arg::new("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::new("option")
        .long("option")
        .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");

pub fn value_delimiter(self, d: char) -> Self

Separator between the arguments values, 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::new("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"])

pub fn require_delimiter(self, yes: bool) -> Self

Specifies that multiple values may only be set using the delimiter.

This means if an option is encountered, and no delimiter is found, it is 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 requires Arg::use_delimiter and Arg::takes_value

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::new("opt")
        .short('o')
        .takes_value(true)
        .use_delimiter(true)
        .require_delimiter(true)
        .multiple_values(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::new("opt")
        .short('o')
        .takes_value(true)
        .use_delimiter(true)
        .require_delimiter(true))
    .try_get_matches_from(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::new("opt")
        .short('o')
        .takes_value(true)
        .multiple_values(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"]);

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

Sentinel to stop parsing multiple values of a give argument.

By default when one sets multiple_values(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::new("vals")
    .takes_value(true)
    .multiple_values(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::new("cmds")
        .takes_value(true)
        .multiple_values(true)
        .allow_hyphen_values(true)
        .value_terminator(";"))
    .arg(Arg::new("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"));

pub fn raw(self, yes: bool) -> Self

Consume all following arguments.

Do not be parse them individually, but rather pass them in entirety.

It is worth noting that setting this requires all values to come after a -- to indicate they should all be captured. For example:

--foo something -- -v -v -v -b -b -b --baz -q -u -x

Will result in everything after -- to be considered one raw argument. This behavior may not be exactly what you are expecting and using crate::AppSettings::TrailingVarArg may be more appropriate.

NOTE: Implicitly sets Arg::takes_value(true) Arg::multiple_values(true), Arg::allow_hyphen_values(true), and Arg::last(true) when set to true.

pub fn default_value(self, val: &'help str) -> Self

Value for the argument when not present.

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 runtime.

NOTE: This setting is perfectly compatible with Arg::default_value_if but slightly different. Arg::default_value only takes effect when the user has not provided this arg at runtime. Arg::default_value_if however only takes effect 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 this arg at runtime, nor 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 conjunction 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::new("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::new("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);

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

Value for the argument when not present.

See Arg::default_value.

pub fn default_values(self, vals: &[&'help str]) -> Self

Value for the argument when not present.

See Arg::default_value.

pub fn default_values_os(self, vals: &[&'help OsStr]) -> Self

Value for the argument when not present.

See Arg::default_values.

pub fn default_missing_value(self, val: &'help str) -> Self

Value for the argument when the flag is present but no value is specified.

This configuration option is often used to give the user a shortcut and allow them to efficiently specify an option argument without requiring an explicitly value. The --color argument is a common example. By, supplying an default, such as default_missing_value("always"), the user can quickly just add --color to the command line to produce the desired color output.

NOTE: using this configuration option requires the use of the .min_values(0) and the .require_equals(true) configuration option. These are required in order to unambiguously determine what, if any, value was supplied for the argument.

Examples

Here is an implementation of the common POSIX style --color argument.

macro_rules! app {
    () => {{
        App::new("prog")
            .arg(Arg::new("color").long("color")
                .value_name("WHEN")
                .possible_values(["always", "auto", "never"])
                .default_value("auto")
                .overrides_with("color")
                .min_values(0)
                .require_equals(true)
                .default_missing_value("always")
                .help("Specify WHEN to colorize output.")
            )
   }};
}

let mut m;

// first, we'll provide no arguments

m  = app!().get_matches_from(vec![
        "prog"
    ]);

assert_eq!(m.value_of("color"), Some("auto"));
assert!(m.is_present("color"));
assert_eq!(m.occurrences_of("color"), 0);

// next, we'll provide a runtime value to override the default (as usually done).

m  = app!().get_matches_from(vec![
        "prog", "--color=never"
    ]);

assert_eq!(m.value_of("color"), Some("never"));
assert!(m.is_present("color"));
assert_eq!(m.occurrences_of("color"), 1);

// finally, we will use the shortcut and only provide the argument without a value.

m  = app!().get_matches_from(vec![
        "prog", "--color"
    ]);

assert_eq!(m.value_of("color"), Some("always"));
assert!(m.is_present("color"));
assert_eq!(m.occurrences_of("color"), 1);

pub fn default_missing_value_os(self, val: &'help OsStr) -> Self

Value for the argument when the flag is present but no value is specified.

See Arg::default_missing_value.

pub fn default_missing_values(self, vals: &[&'help str]) -> Self

Value for the argument when the flag is present but no value is specified.

See Arg::default_missing_value.

pub fn default_missing_values_os(self, vals: &[&'help OsStr]) -> Self

Value for the argument when the flag is present but no value is specified.

See Arg::default_missing_values.

impl<'help> Arg<'help>

Help

pub fn help(self, h: impl Into<Option<&'help str>>) -> Self

Sets the description of the argument for short help (-h).

Typically, this is a short (one line) description of the arg.

If Arg::long_help is not specified, this message will be displayed for --help.

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.

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::new("cfg")
        .long("config")
        .help("Some help text describing the --config arg"))
    .get_matches_from(vec![
        "prog", "--help"
    ]);

The above example displays

helptest

USAGE:
   helptest [OPTIONS]

OPTIONS:
    --config     Some help text describing the --config arg
-h, --help       Print help information
-V, --version    Print version information

pub fn long_help(self, h: impl Into<Option<&'help str>>) -> Self

Sets the description of the argument for long help (--help).

Typically this a more detailed (multi-line) message that describes the arg.

If Arg::help is not specified, this message will be displayed for -h.

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.

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::new("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

prog

USAGE:
    prog [OPTIONS]

OPTIONS:
        --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
            Print help information

    -V, --version
            Print version information

pub 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. 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::new("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::new("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 [OPTIONS]

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

pub fn help_heading<O>(self, heading: O) -> Self where
    O: Into<Option<&'help str>>, 

Override the current help section.

pub fn next_line_help(self, yes: bool) -> Self

Render the help on the line after the argument.

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 crate::AppSettings::NextLineHelp

Examples

let m = App::new("prog")
    .arg(Arg::new("opt")
        .long("long-option-flag")
        .short('o')
        .takes_value(true)
        .next_line_help(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"))
    .get_matches_from(vec![
        "prog", "--help"
    ]);

The above example displays the following help message

nlh

USAGE:
    nlh [OPTIONS]

OPTIONS:
    -h, --help       Print help information
    -V, --version    Print version information
    -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

pub fn hide(self, yes: bool) -> Self

Do not display the argument in help message.

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

Examples

Setting Hidden will hide the argument when displaying help text

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

The above example displays

helptest

USAGE:
   helptest [OPTIONS]

OPTIONS:
-h, --help       Print help information
-V, --version    Print version information

pub fn hide_possible_values(self, yes: bool) -> Self

Do not display the possible values in the help message.

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

NOTE: Setting this requires Arg::takes_value

To set this for all arguments, see AppSettings::HidePossibleValues.

Examples

let m = App::new("prog")
    .arg(Arg::new("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.

pub fn hide_default_value(self, yes: bool) -> Self

Do not display the default value of the argument in the help message.

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

NOTE: Setting this requires Arg::takes_value

Examples

let m = App::new("connect")
    .arg(Arg::new("host")
        .long("host")
        .default_value("localhost")
        .takes_value(true)
        .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.

pub fn hide_short_help(self, yes: bool) -> Self

Hides an argument from short help (-h).

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

NOTE: Setting this option will cause next-line-help output style to be used when long help (--help) is called.

Examples

Arg::new("debug")
    .hide_short_help(true);

Setting hide_short_help(true) will hide the argument when displaying short help text

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

The above example displays

helptest

USAGE:
   helptest [OPTIONS]

OPTIONS:
-h, --help       Print help information
-V, --version    Print version information

However, when –help is called

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

Then the following would be displayed

helptest

USAGE:
   helptest [OPTIONS]

OPTIONS:
    --config     Some help text describing the --config arg
-h, --help       Print help information
-V, --version    Print version information

pub fn hide_long_help(self, yes: bool) -> Self

Hides an argument from long help (--help).

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

NOTE: Setting this option will cause next-line-help output style to be used when long help (--help) is called.

Examples

Setting hide_long_help(true) will hide the argument when displaying long help text

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

The above example displays

helptest

USAGE:
   helptest [OPTIONS]

OPTIONS:
-h, --help       Print help information
-V, --version    Print version information

However, when -h is called

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

Then the following would be displayed

helptest

USAGE:
   helptest [OPTIONS]

OPTIONS:
    --config     Some help text describing the --config arg
-h, --help       Print help information
-V, --version    Print version information

impl<'help> Arg<'help>

Advanced argument relations

pub fn group<T: Key>(self, group_id: T) -> Self

The name of the ArgGroup the argument belongs to.

Examples

Arg::new("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::new("debug")
        .long("debug")
        .group("mode"))
    .arg(Arg::new("verbose")
        .long("verbose")
        .group("mode"))
    .get_matches_from(vec![
        "prog", "--debug"
    ]);
assert!(m.is_present("mode"));

pub fn groups<T: Key>(self, group_ids: &[T]) -> Self

The names of ArgGroup’s the argument belongs to.

Examples

Arg::new("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::new("debug")
        .long("debug")
        .groups(&["mode", "verbosity"]))
    .arg(Arg::new("verbose")
        .long("verbose")
        .groups(&["mode", "verbosity"]))
    .get_matches_from(vec![
        "prog", "--debug"
    ]);
assert!(m.is_present("mode"));
assert!(m.is_present("verbosity"));

pub fn default_value_if<T: Key>(
    self,
    arg_id: T,
    val: Option<&'help str>,
    default: Option<&'help 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.

If default is set to None, default_value will be removed.

NOTE: This setting is perfectly compatible with Arg::default_value but slightly different. Arg::default_value only takes effect when the user has not provided this arg at runtime. This setting however only takes effect 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 this arg at runtime, nor were the conditions met for Arg::default_value_if, the Arg::default_value will be applied.

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

Examples

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

let m = App::new("prog")
    .arg(Arg::new("flag")
        .long("flag"))
    .arg(Arg::new("other")
        .long("other")
        .default_value_if("flag", None, Some("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::new("flag")
        .long("flag"))
    .arg(Arg::new("other")
        .long("other")
        .default_value_if("flag", None, Some("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::new("opt")
        .takes_value(true)
        .long("opt"))
    .arg(Arg::new("other")
        .long("other")
        .default_value_if("opt", Some("special"), Some("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::new("opt")
        .takes_value(true)
        .long("opt"))
    .arg(Arg::new("other")
        .long("other")
        .default_value_if("opt", Some("special"), Some("default")))
    .get_matches_from(vec![
        "prog", "--opt", "hahaha"
    ]);

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

If we want to unset the default value for an Arg based on the presence or value of some other Arg.

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

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

pub fn default_value_if_os<T: Key>(
    self,
    arg_id: T,
    val: Option<&'help OsStr>,
    default: Option<&'help OsStr>
) -> Self

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

pub fn default_value_ifs<T: Key>(
    self,
    ifs: &[(T, Option<&'help str>, Option<&'help 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.

Examples

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

let m = App::new("prog")
    .arg(Arg::new("flag")
        .long("flag"))
    .arg(Arg::new("opt")
        .long("opt")
        .takes_value(true))
    .arg(Arg::new("other")
        .long("other")
        .default_value_ifs(&[
            ("flag", None, Some("default")),
            ("opt", Some("channal"), Some("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::new("flag")
        .long("flag"))
    .arg(Arg::new("other")
        .long("other")
        .default_value_ifs(&[
            ("flag", None, Some("default")),
            ("opt", Some("channal"), Some("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 evaluated “wins”

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

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

pub fn default_value_ifs_os<T: Key>(
    self,
    ifs: &[(T, Option<&'help OsStr>, Option<&'help OsStr>)]
) -> Self

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

pub fn required_unless_present<T: Key>(self, arg_id: T) -> Self

Set this arg as required as long as the specified argument is not present at runtime.

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

Examples

Arg::new("config")
    .required_unless_present("debug")

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::new("cfg")
        .required_unless_present("dbg")
        .takes_value(true)
        .long("config"))
    .arg(Arg::new("dbg")
        .long("debug"))
    .try_get_matches_from(vec![
        "prog", "--debug"
    ]);

assert!(res.is_ok());

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

let res = App::new("prog")
    .arg(Arg::new("cfg")
        .required_unless_present("dbg")
        .takes_value(true)
        .long("config"))
    .arg(Arg::new("dbg")
        .long("debug"))
    .try_get_matches_from(vec![
        "prog"
    ]);

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

pub fn required_unless_present_all<T, I>(self, names: I) -> Self where
    I: IntoIterator<Item = T>,
    T: Key, 

Sets this arg as required unless all of the specified arguments are present at runtime.

In other words, parsing will succeed only if user either

• supplies the self arg.
• supplies all of the names arguments.

NOTE: If you wish for this argument to only be required unless any of these args are present see Arg::required_unless_present_any

Examples

Arg::new("config")
    .required_unless_present_all(&["cfg", "dbg"])

In the following example, the required argument is not provided, but it’s not an error because all of the names args have been supplied.

let res = App::new("prog")
    .arg(Arg::new("cfg")
        .required_unless_present_all(&["dbg", "infile"])
        .takes_value(true)
        .long("config"))
    .arg(Arg::new("dbg")
        .long("debug"))
    .arg(Arg::new("infile")
        .short('i')
        .takes_value(true))
    .try_get_matches_from(vec![
        "prog", "--debug", "-i", "file"
    ]);

assert!(res.is_ok());

Setting Arg::required_unless_present_all(names) and not supplying either all of unless args or the self arg is an error.

let res = App::new("prog")
    .arg(Arg::new("cfg")
        .required_unless_present_all(&["dbg", "infile"])
        .takes_value(true)
        .long("config"))
    .arg(Arg::new("dbg")
        .long("debug"))
    .arg(Arg::new("infile")
        .short('i')
        .takes_value(true))
    .try_get_matches_from(vec![
        "prog"
    ]);

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

pub fn required_unless_present_any<T, I>(self, names: I) -> Self where
    I: IntoIterator<Item = T>,
    T: Key, 

Sets this arg as required unless any of the specified arguments are present at runtime.

In other words, parsing will succeed only if user either

• supplies the self arg.
• supplies one or more of the unless arguments.

NOTE: If you wish for this argument to be required unless all of these args are present see Arg::required_unless_present_all

Examples

Arg::new("config")
    .required_unless_present_any(&["cfg", "dbg"])

Setting Arg::required_unless_present_any(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::new("cfg")
        .required_unless_present_any(&["dbg", "infile"])
        .takes_value(true)
        .long("config"))
    .arg(Arg::new("dbg")
        .long("debug"))
    .arg(Arg::new("infile")
        .short('i')
        .takes_value(true))
    .try_get_matches_from(vec![
        "prog", "--debug"
    ]);

assert!(res.is_ok());

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

let res = App::new("prog")
    .arg(Arg::new("cfg")
        .required_unless_present_any(&["dbg", "infile"])
        .takes_value(true)
        .long("config"))
    .arg(Arg::new("dbg")
        .long("debug"))
    .arg(Arg::new("infile")
        .short('i')
        .takes_value(true))
    .try_get_matches_from(vec![
        "prog"
    ]);

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

pub fn required_if_eq<T: Key>(self, arg_id: T, val: &'help str) -> Self

This argument is required only if the specified arg is present at runtime and its value equals val.

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

Examples

Arg::new("config")
    .required_if_eq("other_arg", "value")

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

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

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

// We did use --other=special so "cfg" had become required but was missing.
assert!(res.is_err());
assert_eq!(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument);

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

// By default, the comparison is case-sensitive, so "cfg" wasn't required
assert!(res.is_ok());

let res = App::new("prog")
    .arg(Arg::new("cfg")
        .takes_value(true)
        .required_if_eq("other", "special")
        .long("config"))
    .arg(Arg::new("other")
        .long("other")
        .ignore_case(true)
        .takes_value(true))
    .try_get_matches_from(vec![
        "prog", "--other", "SPECIAL"
    ]);

// However, case-insensitive comparisons can be enabled.  This typically occurs when using Arg::possible_values().
assert!(res.is_err());
assert_eq!(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument);

pub fn required_if_eq_any<T: Key>(self, ifs: &[(T, &'help str)]) -> Self

Specify this 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 its corresponding val.

Examples

Arg::new("config")
    .required_if_eq_any(&[
        ("extra", "val"),
        ("option", "spec")
    ])

Setting Arg::required_if_eq_any(&[(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::new("cfg")
        .required_if_eq_any(&[
            ("extra", "val"),
            ("option", "spec")
        ])
        .takes_value(true)
        .long("config"))
    .arg(Arg::new("extra")
        .takes_value(true)
        .long("extra"))
    .arg(Arg::new("option")
        .takes_value(true)
        .long("option"))
    .try_get_matches_from(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_if_eq_any(&[(arg, val)]) and having any of the args used with its value of val but not using this arg is an error.

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

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

pub fn required_if_eq_all<T: Key>(self, ifs: &[(T, &'help str)]) -> Self

Specify this 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 every one of the specified arg’s value equals its corresponding val.

Examples

Arg::new("config")
    .required_if_eq_all(&[
        ("extra", "val"),
        ("option", "spec")
    ])

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

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

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

Setting Arg::required_if_eq_all(&[(arg, val)]) and having all of the args used with its value of val but not using this arg is an error.

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

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

pub fn requires_if<T: Key>(self, val: &'help str, arg_id: T) -> Self

Require another argument if this arg was present at runtime and its value equals to val.

This method takes value, another_arg pair. At runtime, clap will check if this arg (self) is present and its value equals to val. If it does, another_arg will be marked as required.

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

Examples

Arg::new("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::new("cfg")
        .takes_value(true)
        .requires_if("my.cfg", "other")
        .long("config"))
    .arg(Arg::new("other"))
    .try_get_matches_from(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::new("cfg")
        .takes_value(true)
        .requires_if("my.cfg", "input")
        .long("config"))
    .arg(Arg::new("input"))
    .try_get_matches_from(vec![
        "prog", "--config", "my.cfg"
    ]);

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

pub fn requires_ifs<T: Key>(self, ifs: &[(&'help str, T)]) -> Self

Allows multiple conditional requirements.

The requirement will only become valid if this arg’s value equals val.

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

Examples

Arg::new("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::new("cfg")
        .takes_value(true)
        .requires_ifs(&[
            ("special.conf", "opt"),
            ("other.conf", "other"),
        ])
        .long("config"))
    .arg(Arg::new("opt")
        .long("option")
        .takes_value(true))
    .arg(Arg::new("other"))
    .try_get_matches_from(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);

pub fn requires_all<T: Key>(self, names: &[T]) -> Self

Require these arguments names when this one is presen

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.

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

Examples

Arg::new("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::new("cfg")
        .takes_value(true)
        .requires("input")
        .long("config"))
    .arg(Arg::new("input")
        .index(1))
    .arg(Arg::new("output")
        .index(2))
    .try_get_matches_from(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::new("cfg")
        .takes_value(true)
        .requires_all(&["input", "output"])
        .long("config"))
    .arg(Arg::new("input")
        .index(1))
    .arg(Arg::new("output")
        .index(2))
    .try_get_matches_from(vec![
        "prog", "--config", "file.conf", "in.txt"
    ]);

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

pub fn conflicts_with<T: Key>(self, arg_id: T) -> Self

This argument is mutually exclusive with the specified 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 to also do B.conflicts_with(A))

NOTE: Arg::conflicts_with_all(names) allows specifying an argument which conflicts with more than one argument.

NOTE Arg::exclusive(true) allows specifying an argument which conflicts with every other argument.

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

Examples

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

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

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

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

pub fn conflicts_with_all(self, names: &[&str]) -> Self

This argument is mutually exclusive with the specified arguments.

See Arg::conflicts_with.

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

NOTE: Arg::exclusive(true) allows specifying an argument which conflicts with every other argument.

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

Examples

Arg::new("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::new("cfg")
        .takes_value(true)
        .conflicts_with_all(&["debug", "input"])
        .long("config"))
    .arg(Arg::new("debug")
        .long("debug"))
    .arg(Arg::new("input")
        .index(1))
    .try_get_matches_from(vec![
        "prog", "--config", "file.conf", "file.txt"
    ]);

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

pub fn overrides_with<T: Key>(self, arg_id: T) -> Self

Sets an overridable argument.

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

WARNING: Positional arguments and options which accept Arg::multiple_occurrences cannot override themselves (or we would never be able to advance to the next positional). If a positional argument or option with one of the Arg::multiple_occurrences settings lists itself as an override, it is simply ignored.

Examples

let m = App::new("prog")
    .arg(arg!(-f --flag "some flag")
        .conflicts_with("debug"))
    .arg(arg!(-d --debug "other flag"))
    .arg(arg!(-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"));

Care must be taken when using this setting, and having an arg override with itself. This is common practice when supporting things like shell aliases, config files, etc. However, when combined with multiple values, it can get dicy. Here is how clap handles such situations:

When a flag overrides itself, it’s as if the flag was only ever used once (essentially preventing a “Unexpected multiple usage” error):

let m = App::new("posix")
            .arg(arg!(--flag  "some flag").overrides_with("flag"))
            .get_matches_from(vec!["posix", "--flag", "--flag"]);
assert!(m.is_present("flag"));
assert_eq!(m.occurrences_of("flag"), 1);

Making an arg Arg::multiple_occurrences and override itself is essentially meaningless. Therefore clap ignores an override of self if it’s a flag and it already accepts multiple occurrences.

let m = App::new("posix")
            .arg(arg!(--flag ...  "some flag").overrides_with("flag"))
            .get_matches_from(vec!["", "--flag", "--flag", "--flag", "--flag"]);
assert!(m.is_present("flag"));
assert_eq!(m.occurrences_of("flag"), 4);

Now notice with options (which do not set Arg::multiple_occurrences), it’s as if only the last occurrence happened.

let m = App::new("posix")
            .arg(arg!(--opt <val> "some option").overrides_with("opt"))
            .get_matches_from(vec!["", "--opt=some", "--opt=other"]);
assert!(m.is_present("opt"));
assert_eq!(m.occurrences_of("opt"), 1);
assert_eq!(m.value_of("opt"), Some("other"));

This will also work when Arg::multiple_values is enabled:

let m = App::new("posix")
            .arg(
                Arg::new("opt")
                    .long("opt")
                    .takes_value(true)
                    .multiple_values(true)
                    .overrides_with("opt")
            )
            .get_matches_from(vec!["", "--opt", "1", "2", "--opt", "3", "4", "5"]);
assert!(m.is_present("opt"));
assert_eq!(m.occurrences_of("opt"), 1);
assert_eq!(m.values_of("opt").unwrap().collect::<Vec<_>>(), &["3", "4", "5"]);

Just like flags, options with Arg::multiple_occurrences set will ignore the “override self” setting.

let m = App::new("posix")
            .arg(arg!(--opt <val> ... "some option")
                .multiple_values(true)
                .overrides_with("opt"))
            .get_matches_from(vec!["", "--opt", "first", "over", "--opt", "other", "val"]);
assert!(m.is_present("opt"));
assert_eq!(m.occurrences_of("opt"), 2);
assert_eq!(m.values_of("opt").unwrap().collect::<Vec<_>>(), &["first", "over", "other", "val"]);

pub fn overrides_with_all<T: Key>(self, names: &[T]) -> 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!(-f --flag "some flag")
        .conflicts_with("color"))
    .arg(arg!(-d --debug "other flag"))
    .arg(arg!(-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"));

impl<'help> Arg<'help>

Reflection

pub fn get_name(&self) -> &'help str

Get the name of the argument

pub fn get_help(&self) -> Option<&'help str>

Get the help specified for this argument, if any

pub fn get_long_help(&self) -> Option<&'help str>

Get the long help specified for this argument, if any

Examples

let arg = Arg::new("foo").long_help("long help");
assert_eq!(Some("long help"), arg.get_long_help());

pub fn get_help_heading(&self) -> Option<&'help str>

Get the help heading specified for this argument, if any

pub fn get_short(&self) -> Option<char>

Get the short option name for this argument, if any

pub fn get_visible_short_aliases(&self) -> Option<Vec<char>>

Get visible short aliases for this argument, if any

pub fn get_short_and_visible_aliases(&self) -> Option<Vec<char>>

Get the short option name and its visible aliases, if any

pub fn get_long(&self) -> Option<&'help str>

Get the long option name for this argument, if any

pub fn get_visible_aliases(&self) -> Option<Vec<&'help str>>

Get visible aliases for this argument, if any

pub fn get_long_and_visible_aliases(&self) -> Option<Vec<&'help str>>

Get the long option name and its visible aliases, if any

pub fn get_possible_values(&self) -> Option<&[PossibleValue<'_>]>

Get the list of the possible values for this argument, if any

pub fn get_value_names(&self) -> Option<&[&'help str]>

Get the names of values for this argument.

pub fn get_num_vals(&self) -> Option<usize>

Get the number of values for this argument.

pub fn get_index(&self) -> Option<usize>

Get the index of this argument, if any

pub fn get_value_hint(&self) -> ValueHint

Get the value hint of this argument

pub fn get_global(&self) -> bool

Get information on if this argument is global or not

pub fn get_default_values(&self) -> &[&OsStr]

Get the default values specified for this argument, if any

Examples

let arg = Arg::new("foo").default_value("default value");
assert_eq!(&["default value"], arg.get_default_values());

pub fn is_positional(&self) -> bool

Checks whether this argument is a positional or not.

Examples

let arg = Arg::new("foo");
assert_eq!(true, arg.is_positional());

let arg = Arg::new("foo").long("foo");
assert_eq!(false, arg.is_positional());

impl<'help> Arg<'help>

Deprecated

pub fn with_name<S: Into<&'help str>>(n: S) -> Self

👎 Deprecated since 3.0.0:

Replaced with Arg::new

Deprecated, replaced with Arg::new

pub fn from_usage(u: &'help str) -> Self

👎 Deprecated since 3.0.0:

Deprecated in Issue #3086, see `clap::arg!

Deprecated in Issue #3086, see arg!.

pub fn required_unless<T: Key>(self, arg_id: T) -> Self

👎 Deprecated since 3.0.0:

Replaced with Arg::required_unless_present

Deprecated, replaced with Arg::required_unless_present

pub fn required_unless_all<T, I>(self, names: I) -> Self where
    I: IntoIterator<Item = T>,
    T: Key, 

👎 Deprecated since 3.0.0:

Replaced with Arg::required_unless_present_all

Deprecated, replaced with Arg::required_unless_present_all

pub fn required_unless_one<T, I>(self, names: I) -> Self where
    I: IntoIterator<Item = T>,
    T: Key, 

👎 Deprecated since 3.0.0:

Replaced with Arg::required_unless_present_any

Deprecated, replaced with Arg::required_unless_present_any

pub fn required_if<T: Key>(self, arg_id: T, val: &'help str) -> Self

👎 Deprecated since 3.0.0:

Replaced with Arg::required_if_eq

Deprecated, replaced with Arg::required_if_eq

pub fn required_ifs<T: Key>(self, ifs: &[(T, &'help str)]) -> Self

👎 Deprecated since 3.0.0:

Replaced with Arg::required_if_eq_any

Deprecated, replaced with Arg::required_if_eq_any

pub fn hidden(self, yes: bool) -> Self

👎 Deprecated since 3.0.0:

Replaced with Arg::hide

Deprecated, replaced with Arg::hide

pub fn case_insensitive(self, yes: bool) -> Self

👎 Deprecated since 3.0.0:

Replaced with Arg::ignore_case

Deprecated, replaced with Arg::ignore_case

pub fn empty_values(self, yes: bool) -> Self

👎 Deprecated since 3.0.0:

Replaced with Arg::forbid_empty_values

Deprecated, replaced with Arg::forbid_empty_values

pub fn multiple(self, yes: bool) -> Self

👎 Deprecated since 3.0.0:

Split into Arg::multiple_occurrences (most likely what you want) and Arg::multiple_values

Deprecated, replaced with Arg::multiple_occurrences (most likely what you want) and Arg::multiple_values

pub fn hidden_short_help(self, yes: bool) -> Self

👎 Deprecated since 3.0.0:

Replaced with Arg::hide_short_help

Deprecated, replaced with Arg::hide_short_help

pub fn hidden_long_help(self, yes: bool) -> Self

👎 Deprecated since 3.0.0:

Replaced with Arg::hide_long_help

Deprecated, replaced with Arg::hide_long_help

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

👎 Deprecated since 3.0.0:

Replaced with Arg::setting

Deprecated, replaced with Arg::setting

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

👎 Deprecated since 3.0.0:

Replaced with Arg::unset_setting

Deprecated, replaced with Arg::unset_setting

Trait Implementations

impl<'help> Clone for Arg<'help>

fn clone(&self) -> Arg<'help>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'help> Debug for Arg<'help>

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<'help> Default for Arg<'help>

fn default() -> Arg<'help>

Returns the “default value” for a type.

impl<'help> Display for Arg<'help>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'help> From<&'_ Arg<'help>> for Arg<'help>

fn from(a: &Arg<'help>) -> Self

Performs the conversion.

impl<'help> Ord for Arg<'help>

fn cmp(&self, other: &Arg<'_>) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

Restrict a value to a certain interval.

impl<'help> PartialEq<Arg<'help>> for Arg<'help>

fn eq(&self, other: &Arg<'help>) -> 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 !=.

impl<'help> PartialOrd<Arg<'help>> for Arg<'help>

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

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

This method tests less than (for self and other) and is used by the < operator.

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

This method tests less than or equal to (for self and other) and is used by the <= operator.

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

This method tests greater than (for self and other) and is used by the > operator.

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

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<'help> Eq for Arg<'help>