Struct clap::Arg

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

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

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

Examples

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

Methods

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

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

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

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

Examples

Arg::with_name("config")

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

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

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

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

Syntax

Usage strings typically following the form:

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

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

Explicit Name

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

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

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

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

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

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

Short

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

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

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

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

Long

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

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

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

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

Values (Value Notation)

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

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

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

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

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

Help String

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

Example help strings are as follows:

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

Additional Sigils

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

Examples

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

fn short<S: AsRef<str>>(self, s: S) -> Self

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

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

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

Examples

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

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

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

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

NOTE: Any leading - characters will be stripped

Examples

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

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

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

Examples

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

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

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

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

Example

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

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

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

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

Examples

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

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

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

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.

Examples

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

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

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

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

Examples

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

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

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

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

Examples

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

fn requires(self, name: &'a str) -> Self

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

NOTE: Conflicting rules and override rules take precedence over being required

Examples

let m = App::new("group_required")
    .arg(Arg::from_usage("-f, --flag 'some flag'"))
    .group(ArgGroup::with_name("gr")
        .required(true)
        .arg("some")
        .arg("other"))
    .arg(Arg::from_usage("--some 'some arg'"))
    .arg(Arg::from_usage("--other 'other arg'"))
    .get_matches_from(vec!["", "-f", "--some"]);
assert!(m.is_present("some"));
assert!(!m.is_present("other"));
assert!(m.is_present("flag"));

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

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

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

Examples

let result = App::new("flag_required")
    .arg(Arg::from_usage("-d 'debugging mode'"))
    .arg(Arg::from_usage("-f, --flag 'some flag'")
        .requires_all(&["color", "d"]))
    .arg(Arg::from_usage("-c, --color 'third flag'"))
    .get_matches_from_safe(vec!["flag_required", "-f"]);
assert!(result.is_err());
let err = result.err().unwrap();
assert_eq!(err.kind, ErrorKind::MissingRequiredArgument);

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

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

Examples

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

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

Specifies the index of a positional argument starting at 1.

Examples

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

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

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

For example, --opt val1 val2 is one occurrence, but multiple values. --opt val1 --opt val2 is multiple occurrences. This setting applies to occurrences and not values.

To specify that an option may receive multiple values, use Arg::min_values, Arg::max_values, or Arg::number_of_values depending on your use case. Note also, that Arg::value_names implicitly sets multiple values, but not multiple occurrences.

Examples

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

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

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

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

NOTE: Global arguments cannot be required.

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

Examples

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

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

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

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

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

Examples

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

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

Hides an argument from help message output.

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

Examples

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

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

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

NOTE: This setting only applies to options and positional arguments

Examples

let res = App::new("possible_values")
    .arg(Arg::with_name("option")
        .short("-o")
        .long("--option")
        .takes_value(true)
        .possible_values(&["fast", "slow"]))
    .get_matches_from_safe(vec!["myprog", "--option", "fast"]);
assert!(res.is_ok());
let m = res.unwrap();
assert!(m.is_present("option"));
assert_eq!(m.value_of("option"), Some("fast"));

The next example shows a failed parse

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

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

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

Examples

let res = App::new("possible_values")
    .arg(Arg::with_name("option")
        .short("-o")
        .long("--option")
        .takes_value(true)
        .possible_value("slow")
        .possible_value("fast"))
    .get_matches_from_safe(vec!["myprog", "--option", "fast"]);
assert!(res.is_ok());
let m = res.unwrap();
assert!(m.is_present("option"));
assert_eq!(m.value_of("option"), Some("fast"));

The next example shows a failed parse

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

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

Specifies the name of the group the argument belongs to.

Examples

Arg::with_name("debug")
    .index(1)
    .group("mode")

fn number_of_values(self, qty: u64) -> Self

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

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

Examples

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

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

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

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

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

Examples

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

fn max_values(self, qty: u64) -> Self

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

NOTE: This does not implicitly set mulitple(true). This is because -o val -o val is multiples occurrences but a single value and -o val1 val2 is a single occurence with multple values. For positional arguments this does set multiple(true) because there is no way to determine the diffrence between multiple occureces and multiple values.

Examples

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

fn min_values(self, qty: u64) -> Self

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

NOTE: This does not implicitly set mulitple(true). This is because -o val -o val is multiples occurrences but a single value and -o val1 val2 is a single occurence with multple values. For positional arguments this does set multiple(true) because there is no way to determine the diffrence between multiple occureces and multiple values.

Examples

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

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

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

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

Examples

The following example shows the default behavior.

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

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

The next example shows the difference when turning delimiters off.

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

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

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

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

NOTE: implicitly sets Arg::use_delimiter(true)

NOTE: implicitly sets Arg::takes_value(true)

Examples

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

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

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

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

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

NOTE: This implicitly sets .number_of_values() if the number of value names is greater than one. I.e. be aware that the number of "names" you set for the values, will be the exact number of values required to satisfy this argument

NOTE: implicitly sets Arg::takes_value(true)

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

Examples

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

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

Specifies the name for value of option or positional arguments inside of help documenation. This name is cosmetic only, the name is not used to access arguments.

NOTE: implicitly sets Arg::takes_value(true)

Examples

Arg::with_name("input")
    .index(1)
    .value_name("FILE")

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

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

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

Sets one of the ArgSettings settings for the argument

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

Unsets one of the ArgSettings settings for the argument

Trait Implementations

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

fn default() -> Self

Returns the "default value" for a type.

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

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

Performs the conversion.