logo
pub struct ArgMatches { /* private fields */ }
Expand description

Container for parse results.

Used to get information about the arguments that were supplied to the program at runtime by the user. New instances of this struct are obtained by using the App::get_matches family of methods.

Examples

let matches = App::new("MyApp")
    .arg(Arg::new("out")
        .long("output")
        .required(true)
        .takes_value(true))
    .arg(Arg::new("debug")
        .short('d')
        .multiple_occurrences(true))
    .arg(Arg::new("cfg")
        .short('c')
        .takes_value(true))
    .get_matches(); // builds the instance of ArgMatches

// to get information about the "cfg" argument we created, such as the value supplied we use
// various ArgMatches methods, such as ArgMatches::value_of
if let Some(c) = matches.value_of("cfg") {
    println!("Value for -c: {}", c);
}

// The ArgMatches::value_of method returns an Option because the user may not have supplied
// that argument at runtime. But if we specified that the argument was "required" as we did
// with the "out" argument, we can safely unwrap because `clap` verifies that was actually
// used at runtime.
println!("Value for --output: {}", matches.value_of("out").unwrap());

// You can check the presence of an argument
if matches.is_present("out") {
    // Another way to check if an argument was present, or if it occurred multiple times is to
    // use occurrences_of() which returns 0 if an argument isn't found at runtime, or the
    // number of times that it occurred, if it was. To allow an argument to appear more than
    // once, you must use the .multiple_occurrences(true) method, otherwise it will only return 1 or 0.
    if matches.occurrences_of("debug") > 2 {
        println!("Debug mode is REALLY on, don't be crazy");
    } else {
        println!("Debug mode kind of on");
    }
}

Implementations

Gets the value of a specific option or positional argument.

i.e. an argument that takes an additional value at runtime.

Returns None if the option wasn’t present.

NOTE: Prefer ArgMatches::values_of if getting a value for an option or positional argument that allows multiples as ArgMatches::value_of will only return the first value.

NOTE: This will always return Some(value) if default_value has been set. occurrences_of can be used to check if a value is present at runtime.

Panics

If the value is invalid UTF-8. See Arg::allow_invalid_utf8.

If id is is not a valid argument or group name.

Examples
let m = App::new("myapp")
    .arg(Arg::new("output")
        .takes_value(true))
    .get_matches_from(vec!["myapp", "something"]);

assert_eq!(m.value_of("output"), Some("something"));
Examples found in repository
examples/tutorial_builder/03_03_positional.rs (line 6)
3
4
5
6
7
fn main() {
    let matches = app_from_crate!().arg(arg!([NAME])).get_matches();

    println!("NAME: {:?}", matches.value_of("NAME"));
}
More examples
examples/tutorial_builder/03_02_option.rs (line 8)
3
4
5
6
7
8
9
fn main() {
    let matches = app_from_crate!()
        .arg(arg!(-n --name <NAME>).required(false))
        .get_matches();

    println!("name: {:?}", matches.value_of("name"));
}
examples/tutorial_builder/03_05_default_values.rs (line 11)
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
fn main() {
    let matches = app_from_crate!()
        .arg(arg!([NAME]).default_value("alice"))
        .get_matches();

    println!(
        "NAME: {:?}",
        matches
            .value_of("NAME")
            .expect("default ensures there is always a value")
    );
}
examples/tutorial_builder/02_crate.rs (line 9)
3
4
5
6
7
8
9
10
11
fn main() {
    let matches = app_from_crate!()
        .arg(arg!(--two <VALUE>))
        .arg(arg!(--one <VALUE>))
        .get_matches();

    println!("two: {:?}", matches.value_of("two").expect("required"));
    println!("one: {:?}", matches.value_of("one").expect("required"));
}
examples/tutorial_builder/02_apps.rs (line 12)
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
fn main() {
    let matches = App::new("MyApp")
        .version("1.0")
        .author("Kevin K. <kbknapp@gmail.com>")
        .about("Does awesome things")
        .arg(arg!(--two <VALUE>))
        .arg(arg!(--one <VALUE>))
        .get_matches();

    println!("two: {:?}", matches.value_of("two").expect("required"));
    println!("one: {:?}", matches.value_of("one").expect("required"));
}
examples/tutorial_builder/02_app_settings.rs (line 12)
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
fn main() {
    let matches = app_from_crate!()
        .global_setting(AppSettings::AllArgsOverrideSelf)
        .global_setting(AppSettings::DeriveDisplayOrder)
        .global_setting(AppSettings::AllowNegativeNumbers)
        .arg(arg!(--two <VALUE>))
        .arg(arg!(--one <VALUE>))
        .get_matches();

    println!("two: {:?}", matches.value_of("two").expect("required"));
    println!("one: {:?}", matches.value_of("one").expect("required"));
}

Gets the lossy value of a specific option or positional argument.

i.e. an argument that takes an additional value at runtime.

A lossy value is one which contains invalid UTF-8, those invalid points will be replaced with \u{FFFD}

Returns None if the option wasn’t present.

NOTE: Recommend having set Arg::allow_invalid_utf8.

NOTE: Prefer ArgMatches::values_of_lossy if getting a value for an option or positional argument that allows multiples as ArgMatches::value_of_lossy will only return the first value.

NOTE: This will always return Some(value) if default_value has been set. occurrences_of can be used to check if a value is present at runtime.

Panics

If id is is not a valid argument or group name.

Examples
use std::ffi::OsString;
use std::os::unix::ffi::{OsStrExt,OsStringExt};

let m = App::new("utf8")
   .arg(arg!(<arg> "some arg")
       .allow_invalid_utf8(true))
   .get_matches_from(vec![OsString::from("myprog"),
                           // "Hi {0xe9}!"
                           OsString::from_vec(vec![b'H', b'i', b' ', 0xe9, b'!'])]);
assert_eq!(&*m.value_of_lossy("arg").unwrap(), "Hi \u{FFFD}!");

Get the OsStr value of a specific option or positional argument.

i.e. an argument that takes an additional value at runtime.

An OsStr on Unix-like systems is any series of bytes, regardless of whether or not they contain valid UTF-8. Since Strings in Rust are guaranteed to be valid UTF-8, a valid filename on a Unix system as an argument value may contain invalid UTF-8.

Returns None if the option wasn’t present.

NOTE: Recommend having set Arg::allow_invalid_utf8.

NOTE: Prefer ArgMatches::values_of_os if getting a value for an option or positional argument that allows multiples as ArgMatches::value_of_os will only return the first value.

NOTE: This will always return Some(value) if default_value has been set. occurrences_of can be used to check if a value is present at runtime.

Panics

If id is is not a valid argument or group name.

Examples
use std::ffi::OsString;
use std::os::unix::ffi::{OsStrExt,OsStringExt};

let m = App::new("utf8")
   .arg(arg!(<arg> "some arg")
       .allow_invalid_utf8(true))
   .get_matches_from(vec![OsString::from("myprog"),
                           // "Hi {0xe9}!"
                           OsString::from_vec(vec![b'H', b'i', b' ', 0xe9, b'!'])]);
assert_eq!(&*m.value_of_os("arg").unwrap().as_bytes(), [b'H', b'i', b' ', 0xe9, b'!']);
Examples found in repository
examples/cargo-example.rs (line 18)
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
fn main() {
    let app = clap::App::new("cargo")
        .bin_name("cargo")
        .setting(clap::AppSettings::SubcommandRequired)
        .subcommand(
            clap::app_from_crate!().name("example").arg(
                clap::arg!(--"manifest-path" <PATH>)
                    .required(false)
                    .allow_invalid_utf8(true),
            ),
        );
    let matches = app.get_matches();
    let matches = match matches.subcommand() {
        Some(("example", matches)) => matches,
        _ => unreachable!("clap should ensure we don't get here"),
    };
    let manifest_path = matches
        .value_of_os("manifest-path")
        .map(std::path::PathBuf::from);
    println!("{:?}", manifest_path);
}
More examples
examples/tutorial_builder/01_quick.rs (line 31)
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
fn main() {
    let matches = app_from_crate!()
        .arg(arg!([name] "Optional name to operate on"))
        .arg(
            arg!(
                -c --config <FILE> "Sets a custom config file"
            )
            // We don't have syntax yet for optional options, so manually calling `required`
            .required(false)
            // Support non-UTF8 paths
            .allow_invalid_utf8(true),
        )
        .arg(arg!(
            -d --debug ... "Turn debugging information on"
        ))
        .subcommand(
            App::new("test")
                .about("does testing things")
                .arg(arg!(-l --list "lists test values")),
        )
        .get_matches();

    // You can check the value provided by positional arguments, or option arguments
    if let Some(name) = matches.value_of("name") {
        println!("Value for name: {}", name);
    }

    if let Some(raw_config) = matches.value_of_os("config") {
        let config_path = Path::new(raw_config);
        println!("Value for config: {}", config_path.display());
    }

    // You can see how many times a particular flag or argument occurred
    // Note, only flags can have multiple occurrences
    match matches.occurrences_of("debug") {
        0 => println!("Debug mode is off"),
        1 => println!("Debug mode is kind of on"),
        2 => println!("Debug mode is on"),
        _ => println!("Don't be crazy"),
    }

    // You can check for the existence of subcommands, and if found use their
    // matches just as you would the top level app
    if let Some(matches) = matches.subcommand_matches("test") {
        // "$ myapp test" was run
        if matches.is_present("list") {
            // "$ myapp test -l" was run
            println!("Printing testing lists...");
        } else {
            println!("Not printing testing lists...");
        }
    }

    // Continued program logic goes here...
}

Get an Iterator over values of a specific option or positional argument.

i.e. an argument that takes multiple values at runtime.

Returns None if the option wasn’t present.

Panics

If the value is invalid UTF-8. See Arg::allow_invalid_utf8.

If id is is not a valid argument or group name.

Examples
let m = App::new("myprog")
    .arg(Arg::new("output")
        .multiple_occurrences(true)
        .short('o')
        .takes_value(true))
    .get_matches_from(vec![
        "myprog", "-o", "val1", "-o", "val2", "-o", "val3"
    ]);
let vals: Vec<&str> = m.values_of("output").unwrap().collect();
assert_eq!(vals, ["val1", "val2", "val3"]);
Examples found in repository
examples/escaped-positional.rs (line 20)
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
fn main() {
    let matches = app_from_crate!()
        .arg(arg!(eff: -f))
        .arg(arg!(pea: -p <PEAR>).required(false))
        .arg(
            arg!(slop: [SLOP]).multiple_occurrences(true).last(true), // Indicates that `slop` is only accessible after `--`.
        )
        .get_matches();

    // This is what will happen with `myprog -f -p=bob -- sloppy slop slop`...
    println!("-f used: {:?}", matches.is_present("eff")); // -f used: true
    println!("-p's value: {:?}", matches.value_of("pea")); // -p's value: Some("bob")
    println!(
        "'slops' values: {:?}",
        matches
            .values_of("slop")
            .map(|vals| vals.collect::<Vec<_>>())
            .unwrap_or_default()
    ); // 'slops' values: Some(["sloppy", "slop", "slop"])

    // Continued program logic goes here...
}
More examples
examples/pacman.rs (line 73)
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
fn main() {
    let matches = App::new("pacman")
        .about("package manager utility")
        .version("5.2.1")
        .setting(AppSettings::SubcommandRequiredElseHelp)
        .author("Pacman Development Team")
        // Query subcommand
        //
        // Only a few of its arguments are implemented below.
        .subcommand(
            App::new("query")
                .short_flag('Q')
                .long_flag("query")
                .about("Query the package database.")
                .arg(
                    Arg::new("search")
                        .short('s')
                        .long("search")
                        .help("search locally installed packages for matching strings")
                        .conflicts_with("info")
                        .takes_value(true)
                        .multiple_values(true),
                )
                .arg(
                    Arg::new("info")
                        .long("info")
                        .short('i')
                        .conflicts_with("search")
                        .help("view package information")
                        .takes_value(true)
                        .multiple_values(true),
                ),
        )
        // Sync subcommand
        //
        // Only a few of its arguments are implemented below.
        .subcommand(
            App::new("sync")
                .short_flag('S')
                .long_flag("sync")
                .about("Synchronize packages.")
                .arg(
                    Arg::new("search")
                        .short('s')
                        .long("search")
                        .conflicts_with("info")
                        .takes_value(true)
                        .multiple_values(true)
                        .help("search remote repositories for matching strings"),
                )
                .arg(
                    Arg::new("info")
                        .long("info")
                        .conflicts_with("search")
                        .short('i')
                        .help("view package information"),
                )
                .arg(
                    Arg::new("package")
                        .help("packages")
                        .required_unless_present("search")
                        .takes_value(true)
                        .multiple_values(true),
                ),
        )
        .get_matches();

    match matches.subcommand() {
        Some(("sync", sync_matches)) => {
            if sync_matches.is_present("search") {
                let packages: Vec<_> = sync_matches.values_of("search").unwrap().collect();
                let values = packages.join(", ");
                println!("Searching for {}...", values);
                return;
            }

            let packages: Vec<_> = sync_matches.values_of("package").unwrap().collect();
            let values = packages.join(", ");

            if sync_matches.is_present("info") {
                println!("Retrieving info for {}...", values);
            } else {
                println!("Installing {}...", values);
            }
        }
        Some(("query", query_matches)) => {
            if let Some(packages) = query_matches.values_of("info") {
                let comma_sep = packages.collect::<Vec<_>>().join(", ");
                println!("Retrieving info for {}...", comma_sep);
            } else if let Some(queries) = query_matches.values_of("search") {
                let comma_sep = queries.collect::<Vec<_>>().join(", ");
                println!("Searching Locally for {}...", comma_sep);
            } else {
                println!("Displaying all locally installed packages...");
            }
        }
        _ => unreachable!(), // If all subcommands are defined above, anything else is unreachable
    }
}
This is supported on crate feature unstable-grouped only.

Placeholder documentation.

Get the lossy values of a specific option or positional argument.

i.e. an argument that takes multiple values at runtime.

A lossy value is one which contains invalid UTF-8, those invalid points will be replaced with \u{FFFD}

Returns None if the option wasn’t present.

NOTE: Recommend having set Arg::allow_invalid_utf8.

Panics

If id is is not a valid argument or group name.

Examples
use std::ffi::OsString;
use std::os::unix::ffi::OsStringExt;

let m = App::new("utf8")
   .arg(arg!(<arg> ... "some arg")
       .allow_invalid_utf8(true))
   .get_matches_from(vec![OsString::from("myprog"),
                           // "Hi"
                           OsString::from_vec(vec![b'H', b'i']),
                           // "{0xe9}!"
                           OsString::from_vec(vec![0xe9, b'!'])]);
let mut itr = m.values_of_lossy("arg").unwrap().into_iter();
assert_eq!(&itr.next().unwrap()[..], "Hi");
assert_eq!(&itr.next().unwrap()[..], "\u{FFFD}!");
assert_eq!(itr.next(), None);

Get an Iterator over OsStr values of a specific option or positional argument.

i.e. an argument that takes multiple values at runtime.

An OsStr on Unix-like systems is any series of bytes, regardless of whether or not they contain valid UTF-8. Since Strings in Rust are guaranteed to be valid UTF-8, a valid filename on a Unix system as an argument value may contain invalid UTF-8.

Returns None if the option wasn’t present.

NOTE: Recommend having set Arg::allow_invalid_utf8.

Panics

If id is is not a valid argument or group name.

Examples
use std::ffi::{OsStr,OsString};
use std::os::unix::ffi::{OsStrExt,OsStringExt};

let m = App::new("utf8")
   .arg(arg!(<arg> ... "some arg")
       .allow_invalid_utf8(true))
   .get_matches_from(vec![OsString::from("myprog"),
                               // "Hi"
                               OsString::from_vec(vec![b'H', b'i']),
                               // "{0xe9}!"
                               OsString::from_vec(vec![0xe9, b'!'])]);

let mut itr = m.values_of_os("arg").unwrap().into_iter();
assert_eq!(itr.next(), Some(OsStr::new("Hi")));
assert_eq!(itr.next(), Some(OsStr::from_bytes(&[0xe9, b'!'])));
assert_eq!(itr.next(), None);
Examples found in repository
examples/git.rs (line 46)
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
fn main() {
    let matches = App::new("git")
        .about("A fictional versioning CLI")
        .setting(AppSettings::SubcommandRequiredElseHelp)
        .setting(AppSettings::AllowExternalSubcommands)
        .setting(AppSettings::AllowInvalidUtf8ForExternalSubcommands)
        .subcommand(
            App::new("clone")
                .about("Clones repos")
                .arg(arg!(<REMOTE> "The remote to clone"))
                .setting(AppSettings::ArgRequiredElseHelp),
        )
        .subcommand(
            App::new("push")
                .about("pushes things")
                .arg(arg!(<REMOTE> "The remote to target"))
                .setting(AppSettings::ArgRequiredElseHelp),
        )
        .subcommand(
            App::new("add")
                .about("adds things")
                .setting(AppSettings::ArgRequiredElseHelp)
                .arg(arg!(<PATH> ... "Stuff to add").allow_invalid_utf8(true)),
        )
        .get_matches();

    match matches.subcommand() {
        Some(("clone", sub_matches)) => {
            println!(
                "Cloning {}",
                sub_matches.value_of("REMOTE").expect("required")
            );
        }
        Some(("push", sub_matches)) => {
            println!(
                "Pushing to {}",
                sub_matches.value_of("REMOTE").expect("required")
            );
        }
        Some(("add", sub_matches)) => {
            let paths = sub_matches
                .values_of_os("PATH")
                .unwrap_or_default()
                .map(PathBuf::from)
                .collect::<Vec<_>>();
            println!("Adding {:?}", paths);
        }
        Some((ext, sub_matches)) => {
            let args = sub_matches
                .values_of_os("")
                .unwrap_or_default()
                .collect::<Vec<_>>();
            println!("Calling out to {:?} with {:?}", ext, args);
        }
        _ => unreachable!(), // If all subcommands are defined above, anything else is unreachabe!()
    }

    // Continued program logic goes here...
}

Parse the value (with FromStr) of a specific option or positional argument.

There are two types of errors, parse failures and those where the argument wasn’t present (such as a non-required argument). Check ErrorKind to distinguish them.

NOTE: If getting a value for an option or positional argument that allows multiples, prefer ArgMatches::values_of_t as this method will only return the first value.

Panics

If the value is invalid UTF-8. See Arg::allow_invalid_utf8.

If id is is not a valid argument or group name.

Examples
let matches = App::new("myapp")
              .arg(arg!([length] "Set the length to use as a pos whole num i.e. 20"))
              .get_matches_from(&["test", "12"]);

// Specify the type explicitly (or use turbofish)
let len: u32 = matches.value_of_t("length").unwrap_or_else(|e| e.exit());
assert_eq!(len, 12);

// You can often leave the type for rustc to figure out
let also_len = matches.value_of_t("length").unwrap_or_else(|e| e.exit());
// Something that expects u32
let _: u32 = also_len;
Examples found in repository
examples/tutorial_builder/05_01_assert.rs (line 8)
3
4
5
6
7
8
9
10
11
fn main() {
    let matches = app().get_matches();

    // Note, it's safe to call unwrap() because the arg is required
    let port: usize = matches
        .value_of_t("PORT")
        .expect("'PORT' is required and parsing will fail if its missing");
    println!("PORT = {}", port);
}
More examples
examples/tutorial_builder/04_02_validate.rs (line 14)
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
fn main() {
    let matches = app_from_crate!()
        .arg(
            arg!(<PORT>)
                .help("Network port to use")
                .validator(|s| s.parse::<usize>()),
        )
        .get_matches();

    // Note, it's safe to call unwrap() because the arg is required
    let port: usize = matches
        .value_of_t("PORT")
        .expect("'PORT' is required and parsing will fail if its missing");
    println!("PORT = {}", port);
}
examples/tutorial_builder/04_01_enum.rs (line 50)
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
fn main() {
    let matches = app_from_crate!()
        .arg(
            arg!(<MODE>)
                .help("What mode to run the program in")
                .possible_values(Mode::possible_values()),
        )
        .get_matches();

    // Note, it's safe to call unwrap() because the arg is required
    match matches
        .value_of_t("MODE")
        .expect("'MODE' is required and parsing will fail if its missing")
    {
        Mode::Fast => {
            println!("Hare");
        }
        Mode::Slow => {
            println!("Tortoise");
        }
    }
}

Parse the value (with FromStr) of a specific option or positional argument.

If either the value is not present or parsing failed, exits the program.

Panics

If the value is invalid UTF-8. See Arg::allow_invalid_utf8.

If id is is not a valid argument or group name.

Examples
let matches = App::new("myapp")
              .arg(arg!([length] "Set the length to use as a pos whole num i.e. 20"))
              .get_matches_from(&["test", "12"]);

// Specify the type explicitly (or use turbofish)
let len: u32 = matches.value_of_t_or_exit("length");
assert_eq!(len, 12);

// You can often leave the type for rustc to figure out
let also_len = matches.value_of_t_or_exit("length");
// Something that expects u32
let _: u32 = also_len;

`FromStr

Parse the values (with FromStr) of a specific option or positional argument.

There are two types of errors, parse failures and those where the argument wasn’t present (such as a non-required argument). Check ErrorKind to distinguish them.

NOTE: If getting a value for an option or positional argument that allows multiples, prefer ArgMatches::values_of_t as this method will only return the first value.

Panics

If the value is invalid UTF-8. See Arg::allow_invalid_utf8.

If id is is not a valid argument or group name.

Examples
let matches = App::new("myapp")
              .arg(arg!([length] ... "A sequence of integers because integers are neat!"))
              .get_matches_from(&["test", "12", "77", "40"]);

// Specify the type explicitly (or use turbofish)
let len: Vec<u32> = matches.values_of_t("length").unwrap_or_else(|e| e.exit());
assert_eq!(len, vec![12, 77, 40]);

// You can often leave the type for rustc to figure out
let also_len = matches.values_of_t("length").unwrap_or_else(|e| e.exit());
// Something that expects Vec<u32>
let _: Vec<u32> = also_len;

Parse the values (with FromStr) of a specific option or positional argument.

If parsing (of any value) has failed, exits the program.

Panics

If the value is invalid UTF-8. See Arg::allow_invalid_utf8.

If id is is not a valid argument or group name.

Examples
let matches = App::new("myapp")
              .arg(arg!([length] ... "A sequence of integers because integers are neat!"))
              .get_matches_from(&["test", "12", "77", "40"]);

// Specify the type explicitly (or use turbofish)
let len: Vec<u32> = matches.values_of_t_or_exit("length");
assert_eq!(len, vec![12, 77, 40]);

// You can often leave the type for rustc to figure out
let also_len = matches.values_of_t_or_exit("length");
// Something that expects Vec<u32>
let _: Vec<u32> = also_len;

Check if an argument was present at runtime.

NOTE: This will always return true if default_value has been set. occurrences_of can be used to check if a value is present at runtime.

Panics

If id is is not a valid argument or group name.

Examples
let m = App::new("myprog")
    .arg(Arg::new("debug")
        .short('d'))
    .get_matches_from(vec![
        "myprog", "-d"
    ]);

assert!(m.is_present("debug"));
Examples found in repository
examples/tutorial_builder/03_01_flag_bool.rs (line 6)
3
4
5
6
7
fn main() {
    let matches = app_from_crate!().arg(arg!(-v - -verbose)).get_matches();

    println!("verbose: {:?}", matches.is_present("verbose"));
}
More examples
examples/escaped-positional.rs (line 15)
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
fn main() {
    let matches = app_from_crate!()
        .arg(arg!(eff: -f))
        .arg(arg!(pea: -p <PEAR>).required(false))
        .arg(
            arg!(slop: [SLOP]).multiple_occurrences(true).last(true), // Indicates that `slop` is only accessible after `--`.
        )
        .get_matches();

    // This is what will happen with `myprog -f -p=bob -- sloppy slop slop`...
    println!("-f used: {:?}", matches.is_present("eff")); // -f used: true
    println!("-p's value: {:?}", matches.value_of("pea")); // -p's value: Some("bob")
    println!(
        "'slops' values: {:?}",
        matches
            .values_of("slop")
            .map(|vals| vals.collect::<Vec<_>>())
            .unwrap_or_default()
    ); // 'slops' values: Some(["sloppy", "slop", "slop"])

    // Continued program logic goes here...
}
examples/tutorial_builder/01_quick.rs (line 49)
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
fn main() {
    let matches = app_from_crate!()
        .arg(arg!([name] "Optional name to operate on"))
        .arg(
            arg!(
                -c --config <FILE> "Sets a custom config file"
            )
            // We don't have syntax yet for optional options, so manually calling `required`
            .required(false)
            // Support non-UTF8 paths
            .allow_invalid_utf8(true),
        )
        .arg(arg!(
            -d --debug ... "Turn debugging information on"
        ))
        .subcommand(
            App::new("test")
                .about("does testing things")
                .arg(arg!(-l --list "lists test values")),
        )
        .get_matches();

    // You can check the value provided by positional arguments, or option arguments
    if let Some(name) = matches.value_of("name") {
        println!("Value for name: {}", name);
    }

    if let Some(raw_config) = matches.value_of_os("config") {
        let config_path = Path::new(raw_config);
        println!("Value for config: {}", config_path.display());
    }

    // You can see how many times a particular flag or argument occurred
    // Note, only flags can have multiple occurrences
    match matches.occurrences_of("debug") {
        0 => println!("Debug mode is off"),
        1 => println!("Debug mode is kind of on"),
        2 => println!("Debug mode is on"),
        _ => println!("Don't be crazy"),
    }

    // You can check for the existence of subcommands, and if found use their
    // matches just as you would the top level app
    if let Some(matches) = matches.subcommand_matches("test") {
        // "$ myapp test" was run
        if matches.is_present("list") {
            // "$ myapp test -l" was run
            println!("Printing testing lists...");
        } else {
            println!("Not printing testing lists...");
        }
    }

    // Continued program logic goes here...
}
examples/tutorial_builder/04_03_relations.rs (line 41)
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
fn main() {
    // Create application like normal
    let matches = app_from_crate!()
        // Add the version arguments
        .arg(arg!(--"set-ver" <VER> "set version manually").required(false))
        .arg(arg!(--major         "auto inc major"))
        .arg(arg!(--minor         "auto inc minor"))
        .arg(arg!(--patch         "auto inc patch"))
        // Create a group, make it required, and add the above arguments
        .group(
            ArgGroup::new("vers")
                .required(true)
                .args(&["set-ver", "major", "minor", "patch"]),
        )
        // Arguments can also be added to a group individually, these two arguments
        // are part of the "input" group which is not required
        .arg(arg!([INPUT_FILE] "some regular input").group("input"))
        .arg(
            arg!(--"spec-in" <SPEC_IN> "some special input argument")
                .required(false)
                .group("input"),
        )
        // Now let's assume we have a -c [config] argument which requires one of
        // (but **not** both) the "input" arguments
        .arg(arg!(config: -c <CONFIG>).required(false).requires("input"))
        .get_matches();

    // Let's assume the old version 1.2.3
    let mut major = 1;
    let mut minor = 2;
    let mut patch = 3;

    // See if --set-ver was used to set the version manually
    let version = if let Some(ver) = matches.value_of("set-ver") {
        ver.to_string()
    } else {
        // Increment the one requested (in a real program, we'd reset the lower numbers)
        let (maj, min, pat) = (
            matches.is_present("major"),
            matches.is_present("minor"),
            matches.is_present("patch"),
        );
        match (maj, min, pat) {
            (true, _, _) => major += 1,
            (_, true, _) => minor += 1,
            (_, _, true) => patch += 1,
            _ => unreachable!(),
        };
        format!("{}.{}.{}", major, minor, patch)
    };

    println!("Version: {}", version);

    // Check for usage of -c
    if matches.is_present("config") {
        let input = matches
            .value_of("INPUT_FILE")
            .unwrap_or_else(|| matches.value_of("spec-in").unwrap());
        println!(
            "Doing work using input {} and config {}",
            input,
            matches.value_of("config").unwrap()
        );
    }
}
examples/tutorial_builder/04_04_custom.rs (line 27)
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
fn main() {
    // Create application like normal
    let mut app = app_from_crate!()
        // Add the version arguments
        .arg(arg!(--"set-ver" <VER> "set version manually").required(false))
        .arg(arg!(--major         "auto inc major"))
        .arg(arg!(--minor         "auto inc minor"))
        .arg(arg!(--patch         "auto inc patch"))
        // Arguments can also be added to a group individually, these two arguments
        // are part of the "input" group which is not required
        .arg(arg!([INPUT_FILE] "some regular input"))
        .arg(arg!(--"spec-in" <SPEC_IN> "some special input argument").required(false))
        // Now let's assume we have a -c [config] argument which requires one of
        // (but **not** both) the "input" arguments
        .arg(arg!(config: -c <CONFIG>).required(false));
    let matches = app.get_matches_mut();

    // Let's assume the old version 1.2.3
    let mut major = 1;
    let mut minor = 2;
    let mut patch = 3;

    // See if --set-ver was used to set the version manually
    let version = if let Some(ver) = matches.value_of("set-ver") {
        if matches.is_present("major") || matches.is_present("minor") || matches.is_present("patch")
        {
            app.error(
                ErrorKind::ArgumentConflict,
                "Can't do relative and absolute version change",
            )
            .exit();
        }
        ver.to_string()
    } else {
        // Increment the one requested (in a real program, we'd reset the lower numbers)
        let (maj, min, pat) = (
            matches.is_present("major"),
            matches.is_present("minor"),
            matches.is_present("patch"),
        );
        match (maj, min, pat) {
            (true, false, false) => major += 1,
            (false, true, false) => minor += 1,
            (false, false, true) => patch += 1,
            _ => {
                app.error(
                    ErrorKind::ArgumentConflict,
                    "Cam only modify one version field",
                )
                .exit();
            }
        };
        format!("{}.{}.{}", major, minor, patch)
    };

    println!("Version: {}", version);

    // Check for usage of -c
    if matches.is_present("config") {
        let input = matches
            .value_of("INPUT_FILE")
            .or_else(|| matches.value_of("spec-in"))
            .unwrap_or_else(|| {
                app.error(
                    ErrorKind::MissingRequiredArgument,
                    "INPUT_FILE or --spec-in is required when using --config",
                )
                .exit()
            });
        println!(
            "Doing work using input {} and config {}",
            input,
            matches.value_of("config").unwrap()
        );
    }
}
examples/pacman.rs (line 72)
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
fn main() {
    let matches = App::new("pacman")
        .about("package manager utility")
        .version("5.2.1")
        .setting(AppSettings::SubcommandRequiredElseHelp)
        .author("Pacman Development Team")
        // Query subcommand
        //
        // Only a few of its arguments are implemented below.
        .subcommand(
            App::new("query")
                .short_flag('Q')
                .long_flag("query")
                .about("Query the package database.")
                .arg(
                    Arg::new("search")
                        .short('s')
                        .long("search")
                        .help("search locally installed packages for matching strings")
                        .conflicts_with("info")
                        .takes_value(true)
                        .multiple_values(true),
                )
                .arg(
                    Arg::new("info")
                        .long("info")
                        .short('i')
                        .conflicts_with("search")
                        .help("view package information")
                        .takes_value(true)
                        .multiple_values(true),
                ),
        )
        // Sync subcommand
        //
        // Only a few of its arguments are implemented below.
        .subcommand(
            App::new("sync")
                .short_flag('S')
                .long_flag("sync")
                .about("Synchronize packages.")
                .arg(
                    Arg::new("search")
                        .short('s')
                        .long("search")
                        .conflicts_with("info")
                        .takes_value(true)
                        .multiple_values(true)
                        .help("search remote repositories for matching strings"),
                )
                .arg(
                    Arg::new("info")
                        .long("info")
                        .conflicts_with("search")
                        .short('i')
                        .help("view package information"),
                )
                .arg(
                    Arg::new("package")
                        .help("packages")
                        .required_unless_present("search")
                        .takes_value(true)
                        .multiple_values(true),
                ),
        )
        .get_matches();

    match matches.subcommand() {
        Some(("sync", sync_matches)) => {
            if sync_matches.is_present("search") {
                let packages: Vec<_> = sync_matches.values_of("search").unwrap().collect();
                let values = packages.join(", ");
                println!("Searching for {}...", values);
                return;
            }

            let packages: Vec<_> = sync_matches.values_of("package").unwrap().collect();
            let values = packages.join(", ");

            if sync_matches.is_present("info") {
                println!("Retrieving info for {}...", values);
            } else {
                println!("Installing {}...", values);
            }
        }
        Some(("query", query_matches)) => {
            if let Some(packages) = query_matches.values_of("info") {
                let comma_sep = packages.collect::<Vec<_>>().join(", ");
                println!("Retrieving info for {}...", comma_sep);
            } else if let Some(queries) = query_matches.values_of("search") {
                let comma_sep = queries.collect::<Vec<_>>().join(", ");
                println!("Searching Locally for {}...", comma_sep);
            } else {
                println!("Displaying all locally installed packages...");
            }
        }
        _ => unreachable!(), // If all subcommands are defined above, anything else is unreachable
    }
}

The number of times an argument was used at runtime.

If an argument isn’t present it will return 0.

NOTE: This returns the number of times the argument was used, not the number of values. For example, -o val1 val2 val3 -o val4 would return 2 (2 occurrences, but 4 values). See Arg::multiple_occurrences.

Panics

If id is is not a valid argument or group name.

Examples
let m = App::new("myprog")
    .arg(Arg::new("debug")
        .short('d')
        .multiple_occurrences(true))
    .get_matches_from(vec![
        "myprog", "-d", "-d", "-d"
    ]);

assert_eq!(m.occurrences_of("debug"), 3);

This next example shows that counts actual uses of the argument, not just -’s

let m = App::new("myprog")
    .arg(Arg::new("debug")
        .short('d')
        .multiple_occurrences(true))
    .arg(Arg::new("flag")
        .short('f'))
    .get_matches_from(vec![
        "myprog", "-ddfd"
    ]);

assert_eq!(m.occurrences_of("debug"), 3);
assert_eq!(m.occurrences_of("flag"), 1);
Examples found in repository
examples/tutorial_builder/03_01_flag_count.rs (line 6)
3
4
5
6
7
fn main() {
    let matches = app_from_crate!().arg(arg!(-v --verbose ...)).get_matches();

    println!("verbose: {:?}", matches.occurrences_of("verbose"));
}
More examples
examples/multicall-busybox.rs (line 36)
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
fn main() {
    let app = App::new(env!("CARGO_CRATE_NAME"))
        .setting(AppSettings::Multicall)
        .subcommand(
            App::new("busybox")
                .setting(AppSettings::ArgRequiredElseHelp)
                .subcommand_value_name("APPLET")
                .subcommand_help_heading("APPLETS")
                .arg(
                    Arg::new("install")
                        .long("install")
                        .help("Install hardlinks for all subcommands in path")
                        .exclusive(true)
                        .takes_value(true)
                        .default_missing_value("/usr/local/bin")
                        .use_delimiter(false),
                )
                .subcommands(applet_commands()),
        )
        .subcommands(applet_commands());

    let matches = app.get_matches();
    let mut subcommand = matches.subcommand();
    if let Some(("busybox", cmd)) = subcommand {
        if cmd.occurrences_of("install") > 0 {
            unimplemented!("Make hardlinks to the executable here");
        }
        subcommand = cmd.subcommand();
    }
    match subcommand {
        Some(("false", _)) => exit(1),
        Some(("true", _)) => exit(0),
        _ => unreachable!("parser should ensure only valid subcommand names are used"),
    }
}
examples/tutorial_builder/01_quick.rs (line 38)
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
fn main() {
    let matches = app_from_crate!()
        .arg(arg!([name] "Optional name to operate on"))
        .arg(
            arg!(
                -c --config <FILE> "Sets a custom config file"
            )
            // We don't have syntax yet for optional options, so manually calling `required`
            .required(false)
            // Support non-UTF8 paths
            .allow_invalid_utf8(true),
        )
        .arg(arg!(
            -d --debug ... "Turn debugging information on"
        ))
        .subcommand(
            App::new("test")
                .about("does testing things")
                .arg(arg!(-l --list "lists test values")),
        )
        .get_matches();

    // You can check the value provided by positional arguments, or option arguments
    if let Some(name) = matches.value_of("name") {
        println!("Value for name: {}", name);
    }

    if let Some(raw_config) = matches.value_of_os("config") {
        let config_path = Path::new(raw_config);
        println!("Value for config: {}", config_path.display());
    }

    // You can see how many times a particular flag or argument occurred
    // Note, only flags can have multiple occurrences
    match matches.occurrences_of("debug") {
        0 => println!("Debug mode is off"),
        1 => println!("Debug mode is kind of on"),
        2 => println!("Debug mode is on"),
        _ => println!("Don't be crazy"),
    }

    // You can check for the existence of subcommands, and if found use their
    // matches just as you would the top level app
    if let Some(matches) = matches.subcommand_matches("test") {
        // "$ myapp test" was run
        if matches.is_present("list") {
            // "$ myapp test -l" was run
            println!("Printing testing lists...");
        } else {
            println!("Not printing testing lists...");
        }
    }

    // Continued program logic goes here...
}

The first index of that an argument showed up.

Indices are similar to argv indices, but are not exactly 1:1.

For flags (i.e. those arguments which don’t have an associated value), indices refer to occurrence of the switch, such as -f, or --flag. However, for options the indices refer to the values -o val would therefore not represent two distinct indices, only the index for val would be recorded. This is by design.

Besides the flag/option discrepancy, the primary difference between an argv index and clap index, is that clap continues counting once all arguments have properly separated, whereas an argv index does not.

The examples should clear this up.

NOTE: If an argument is allowed multiple times, this method will only give the first index. See ArgMatches::indices_of.

Panics

If id is is not a valid argument or group name.

Examples

The argv indices are listed in the comments below. See how they correspond to the clap indices. Note that if it’s not listed in a clap index, this is because it’s not saved in in an ArgMatches struct for querying.

let m = App::new("myapp")
    .arg(Arg::new("flag")
        .short('f'))
    .arg(Arg::new("option")
        .short('o')
        .takes_value(true))
    .get_matches_from(vec!["myapp", "-f", "-o", "val"]);
           // ARGV indices: ^0       ^1    ^2    ^3
           // clap indices:          ^1          ^3

assert_eq!(m.index_of("flag"), Some(1));
assert_eq!(m.index_of("option"), Some(3));

Now notice, if we use one of the other styles of options:

let m = App::new("myapp")
    .arg(Arg::new("flag")
        .short('f'))
    .arg(Arg::new("option")
        .short('o')
        .takes_value(true))
    .get_matches_from(vec!["myapp", "-f", "-o=val"]);
           // ARGV indices: ^0       ^1    ^2
           // clap indices:          ^1       ^3

assert_eq!(m.index_of("flag"), Some(1));
assert_eq!(m.index_of("option"), Some(3));

Things become much more complicated, or clear if we look at a more complex combination of flags. Let’s also throw in the final option style for good measure.

let m = App::new("myapp")
    .arg(Arg::new("flag")
        .short('f'))
    .arg(Arg::new("flag2")
        .short('F'))
    .arg(Arg::new("flag3")
        .short('z'))
    .arg(Arg::new("option")
        .short('o')
        .takes_value(true))
    .get_matches_from(vec!["myapp", "-fzF", "-oval"]);
           // ARGV indices: ^0      ^1       ^2
           // clap indices:         ^1,2,3    ^5
           //
           // clap sees the above as 'myapp -f -z -F -o val'
           //                         ^0    ^1 ^2 ^3 ^4 ^5
assert_eq!(m.index_of("flag"), Some(1));
assert_eq!(m.index_of("flag2"), Some(3));
assert_eq!(m.index_of("flag3"), Some(2));
assert_eq!(m.index_of("option"), Some(5));

One final combination of flags/options to see how they combine:

let m = App::new("myapp")
    .arg(Arg::new("flag")
        .short('f'))
    .arg(Arg::new("flag2")
        .short('F'))
    .arg(Arg::new("flag3")
        .short('z'))
    .arg(Arg::new("option")
        .short('o')
        .takes_value(true))
    .get_matches_from(vec!["myapp", "-fzFoval"]);
           // ARGV indices: ^0       ^1
           // clap indices:          ^1,2,3^5
           //
           // clap sees the above as 'myapp -f -z -F -o val'
           //                         ^0    ^1 ^2 ^3 ^4 ^5
assert_eq!(m.index_of("flag"), Some(1));
assert_eq!(m.index_of("flag2"), Some(3));
assert_eq!(m.index_of("flag3"), Some(2));
assert_eq!(m.index_of("option"), Some(5));

The last part to mention is when values are sent in multiple groups with a delimiter.

let m = App::new("myapp")
    .arg(Arg::new("option")
        .short('o')
        .use_delimiter(true)
        .multiple_values(true))
    .get_matches_from(vec!["myapp", "-o=val1,val2,val3"]);
           // ARGV indices: ^0       ^1
           // clap indices:             ^2   ^3   ^4
           //
           // clap sees the above as 'myapp -o val1 val2 val3'
           //                         ^0    ^1 ^2   ^3   ^4
assert_eq!(m.index_of("option"), Some(2));
assert_eq!(m.indices_of("option").unwrap().collect::<Vec<_>>(), &[2, 3, 4]);

All indices an argument appeared at when parsing.

Indices are similar to argv indices, but are not exactly 1:1.

For flags (i.e. those arguments which don’t have an associated value), indices refer to occurrence of the switch, such as -f, or --flag. However, for options the indices refer to the values -o val would therefore not represent two distinct indices, only the index for val would be recorded. This is by design.

NOTE: For more information about how clap indices compared to argv indices, see ArgMatches::index_of

Panics

If id is is not a valid argument or group name.

Examples
let m = App::new("myapp")
    .arg(Arg::new("option")
        .short('o')
        .use_delimiter(true)
        .multiple_values(true))
    .get_matches_from(vec!["myapp", "-o=val1,val2,val3"]);
           // ARGV indices: ^0       ^1
           // clap indices:             ^2   ^3   ^4
           //
           // clap sees the above as 'myapp -o val1 val2 val3'
           //                         ^0    ^1 ^2   ^3   ^4
assert_eq!(m.indices_of("option").unwrap().collect::<Vec<_>>(), &[2, 3, 4]);

Another quick example is when flags and options are used together

let m = App::new("myapp")
    .arg(Arg::new("option")
        .short('o')
        .takes_value(true)
        .multiple_occurrences(true))
    .arg(Arg::new("flag")
        .short('f')
        .multiple_occurrences(true))
    .get_matches_from(vec!["myapp", "-o", "val1", "-f", "-o", "val2", "-f"]);
           // ARGV indices: ^0       ^1    ^2      ^3    ^4    ^5      ^6
           // clap indices:                ^2      ^3          ^5      ^6

assert_eq!(m.indices_of("option").unwrap().collect::<Vec<_>>(), &[2, 5]);
assert_eq!(m.indices_of("flag").unwrap().collect::<Vec<_>>(), &[3, 6]);

One final example, which is an odd case; if we don’t use value delimiter as we did with the first example above instead of val1, val2 and val3 all being distinc values, they would all be a single value of val1,val2,val3, in which case they’d only receive a single index.

let m = App::new("myapp")
    .arg(Arg::new("option")
        .short('o')
        .takes_value(true)
        .multiple_values(true))
    .get_matches_from(vec!["myapp", "-o=val1,val2,val3"]);
           // ARGV indices: ^0       ^1
           // clap indices:             ^2
           //
           // clap sees the above as 'myapp -o "val1,val2,val3"'
           //                         ^0    ^1  ^2
assert_eq!(m.indices_of("option").unwrap().collect::<Vec<_>>(), &[2]);

The name and ArgMatches of the current subcommand.

Subcommand values are put in a child ArgMatches

Returns None if the subcommand wasn’t present at runtime,

Examples
 let app_m = App::new("git")
     .subcommand(App::new("clone"))
     .subcommand(App::new("push"))
     .subcommand(App::new("commit"))
     .get_matches();

match app_m.subcommand() {
    Some(("clone",  sub_m)) => {}, // clone was used
    Some(("push",   sub_m)) => {}, // push was used
    Some(("commit", sub_m)) => {}, // commit was used
    _                       => {}, // Either no subcommand or one not tested for...
}

Another useful scenario is when you want to support third party, or external, subcommands. In these cases you can’t know the subcommand name ahead of time, so use a variable instead with pattern matching!

// Assume there is an external subcommand named "subcmd"
let app_m = App::new("myprog")
    .setting(AppSettings::AllowExternalSubcommands)
    .get_matches_from(vec![
        "myprog", "subcmd", "--option", "value", "-fff", "--flag"
    ]);

// All trailing arguments will be stored under the subcommand's sub-matches using an empty
// string argument name
match app_m.subcommand() {
    Some((external, sub_m)) => {
         let ext_args: Vec<&str> = sub_m.values_of("").unwrap().collect();
         assert_eq!(external, "subcmd");
         assert_eq!(ext_args, ["--option", "value", "-fff", "--flag"]);
    },
    _ => {},
}
Examples found in repository
examples/tutorial_builder/03_04_subcommands.rs (line 15)
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
fn main() {
    let matches = app_from_crate!()
        .global_setting(AppSettings::PropagateVersion)
        .global_setting(AppSettings::UseLongFormatForHelpSubcommand)
        .setting(AppSettings::SubcommandRequiredElseHelp)
        .subcommand(
            App::new("add")
                .about("Adds files to myapp")
                .arg(arg!([NAME])),
        )
        .get_matches();

    match matches.subcommand() {
        Some(("add", sub_matches)) => println!(
            "'myapp add' was used, name is: {:?}",
            sub_matches.value_of("NAME")
        ),
        _ => unreachable!(),
    }
}
More examples
examples/cargo-example.rs (line 13)
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
fn main() {
    let app = clap::App::new("cargo")
        .bin_name("cargo")
        .setting(clap::AppSettings::SubcommandRequired)
        .subcommand(
            clap::app_from_crate!().name("example").arg(
                clap::arg!(--"manifest-path" <PATH>)
                    .required(false)
                    .allow_invalid_utf8(true),
            ),
        );
    let matches = app.get_matches();
    let matches = match matches.subcommand() {
        Some(("example", matches)) => matches,
        _ => unreachable!("clap should ensure we don't get here"),
    };
    let manifest_path = matches
        .value_of_os("manifest-path")
        .map(std::path::PathBuf::from);
    println!("{:?}", manifest_path);
}
examples/multicall-busybox.rs (line 34)
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
fn main() {
    let app = App::new(env!("CARGO_CRATE_NAME"))
        .setting(AppSettings::Multicall)
        .subcommand(
            App::new("busybox")
                .setting(AppSettings::ArgRequiredElseHelp)
                .subcommand_value_name("APPLET")
                .subcommand_help_heading("APPLETS")
                .arg(
                    Arg::new("install")
                        .long("install")
                        .help("Install hardlinks for all subcommands in path")
                        .exclusive(true)
                        .takes_value(true)
                        .default_missing_value("/usr/local/bin")
                        .use_delimiter(false),
                )
                .subcommands(applet_commands()),
        )
        .subcommands(applet_commands());

    let matches = app.get_matches();
    let mut subcommand = matches.subcommand();
    if let Some(("busybox", cmd)) = subcommand {
        if cmd.occurrences_of("install") > 0 {
            unimplemented!("Make hardlinks to the executable here");
        }
        subcommand = cmd.subcommand();
    }
    match subcommand {
        Some(("false", _)) => exit(1),
        Some(("true", _)) => exit(0),
        _ => unreachable!("parser should ensure only valid subcommand names are used"),
    }
}
examples/git.rs (line 31)
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
fn main() {
    let matches = App::new("git")
        .about("A fictional versioning CLI")
        .setting(AppSettings::SubcommandRequiredElseHelp)
        .setting(AppSettings::AllowExternalSubcommands)
        .setting(AppSettings::AllowInvalidUtf8ForExternalSubcommands)
        .subcommand(
            App::new("clone")
                .about("Clones repos")
                .arg(arg!(<REMOTE> "The remote to clone"))
                .setting(AppSettings::ArgRequiredElseHelp),
        )
        .subcommand(
            App::new("push")
                .about("pushes things")
                .arg(arg!(<REMOTE> "The remote to target"))
                .setting(AppSettings::ArgRequiredElseHelp),
        )
        .subcommand(
            App::new("add")
                .about("adds things")
                .setting(AppSettings::ArgRequiredElseHelp)
                .arg(arg!(<PATH> ... "Stuff to add").allow_invalid_utf8(true)),
        )
        .get_matches();

    match matches.subcommand() {
        Some(("clone", sub_matches)) => {
            println!(
                "Cloning {}",
                sub_matches.value_of("REMOTE").expect("required")
            );
        }
        Some(("push", sub_matches)) => {
            println!(
                "Pushing to {}",
                sub_matches.value_of("REMOTE").expect("required")
            );
        }
        Some(("add", sub_matches)) => {
            let paths = sub_matches
                .values_of_os("PATH")
                .unwrap_or_default()
                .map(PathBuf::from)
                .collect::<Vec<_>>();
            println!("Adding {:?}", paths);
        }
        Some((ext, sub_matches)) => {
            let args = sub_matches
                .values_of_os("")
                .unwrap_or_default()
                .collect::<Vec<_>>();
            println!("Calling out to {:?} with {:?}", ext, args);
        }
        _ => unreachable!(), // If all subcommands are defined above, anything else is unreachabe!()
    }

    // Continued program logic goes here...
}
examples/pacman.rs (line 70)
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
fn main() {
    let matches = App::new("pacman")
        .about("package manager utility")
        .version("5.2.1")
        .setting(AppSettings::SubcommandRequiredElseHelp)
        .author("Pacman Development Team")
        // Query subcommand
        //
        // Only a few of its arguments are implemented below.
        .subcommand(
            App::new("query")
                .short_flag('Q')
                .long_flag("query")
                .about("Query the package database.")
                .arg(
                    Arg::new("search")
                        .short('s')
                        .long("search")
                        .help("search locally installed packages for matching strings")
                        .conflicts_with("info")
                        .takes_value(true)
                        .multiple_values(true),
                )
                .arg(
                    Arg::new("info")
                        .long("info")
                        .short('i')
                        .conflicts_with("search")
                        .help("view package information")
                        .takes_value(true)
                        .multiple_values(true),
                ),
        )
        // Sync subcommand
        //
        // Only a few of its arguments are implemented below.
        .subcommand(
            App::new("sync")
                .short_flag('S')
                .long_flag("sync")
                .about("Synchronize packages.")
                .arg(
                    Arg::new("search")
                        .short('s')
                        .long("search")
                        .conflicts_with("info")
                        .takes_value(true)
                        .multiple_values(true)
                        .help("search remote repositories for matching strings"),
                )
                .arg(
                    Arg::new("info")
                        .long("info")
                        .conflicts_with("search")
                        .short('i')
                        .help("view package information"),
                )
                .arg(
                    Arg::new("package")
                        .help("packages")
                        .required_unless_present("search")
                        .takes_value(true)
                        .multiple_values(true),
                ),
        )
        .get_matches();

    match matches.subcommand() {
        Some(("sync", sync_matches)) => {
            if sync_matches.is_present("search") {
                let packages: Vec<_> = sync_matches.values_of("search").unwrap().collect();
                let values = packages.join(", ");
                println!("Searching for {}...", values);
                return;
            }

            let packages: Vec<_> = sync_matches.values_of("package").unwrap().collect();
            let values = packages.join(", ");

            if sync_matches.is_present("info") {
                println!("Retrieving info for {}...", values);
            } else {
                println!("Installing {}...", values);
            }
        }
        Some(("query", query_matches)) => {
            if let Some(packages) = query_matches.values_of("info") {
                let comma_sep = packages.collect::<Vec<_>>().join(", ");
                println!("Retrieving info for {}...", comma_sep);
            } else if let Some(queries) = query_matches.values_of("search") {
                let comma_sep = queries.collect::<Vec<_>>().join(", ");
                println!("Searching Locally for {}...", comma_sep);
            } else {
                println!("Displaying all locally installed packages...");
            }
        }
        _ => unreachable!(), // If all subcommands are defined above, anything else is unreachable
    }
}

The ArgMatches for the current subcommand.

Subcommand values are put in a child ArgMatches

Returns None if the subcommand wasn’t present at runtime,

Panics

If id is is not a valid subcommand.

Examples
let app_m = App::new("myprog")
    .arg(Arg::new("debug")
        .short('d'))
    .subcommand(App::new("test")
        .arg(Arg::new("opt")
            .long("option")
            .takes_value(true)))
    .get_matches_from(vec![
        "myprog", "-d", "test", "--option", "val"
    ]);

// Both parent commands, and child subcommands can have arguments present at the same times
assert!(app_m.is_present("debug"));

// Get the subcommand's ArgMatches instance
if let Some(sub_m) = app_m.subcommand_matches("test") {
    // Use the struct like normal
    assert_eq!(sub_m.value_of("opt"), Some("val"));
}
Examples found in repository
examples/tutorial_builder/01_quick.rs (line 47)
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
fn main() {
    let matches = app_from_crate!()
        .arg(arg!([name] "Optional name to operate on"))
        .arg(
            arg!(
                -c --config <FILE> "Sets a custom config file"
            )
            // We don't have syntax yet for optional options, so manually calling `required`
            .required(false)
            // Support non-UTF8 paths
            .allow_invalid_utf8(true),
        )
        .arg(arg!(
            -d --debug ... "Turn debugging information on"
        ))
        .subcommand(
            App::new("test")
                .about("does testing things")
                .arg(arg!(-l --list "lists test values")),
        )
        .get_matches();

    // You can check the value provided by positional arguments, or option arguments
    if let Some(name) = matches.value_of("name") {
        println!("Value for name: {}", name);
    }

    if let Some(raw_config) = matches.value_of_os("config") {
        let config_path = Path::new(raw_config);
        println!("Value for config: {}", config_path.display());
    }

    // You can see how many times a particular flag or argument occurred
    // Note, only flags can have multiple occurrences
    match matches.occurrences_of("debug") {
        0 => println!("Debug mode is off"),
        1 => println!("Debug mode is kind of on"),
        2 => println!("Debug mode is on"),
        _ => println!("Don't be crazy"),
    }

    // You can check for the existence of subcommands, and if found use their
    // matches just as you would the top level app
    if let Some(matches) = matches.subcommand_matches("test") {
        // "$ myapp test" was run
        if matches.is_present("list") {
            // "$ myapp test -l" was run
            println!("Printing testing lists...");
        } else {
            println!("Not printing testing lists...");
        }
    }

    // Continued program logic goes here...
}

The name of the current subcommand.

Returns None if the subcommand wasn’t present at runtime,

Examples
 let app_m = App::new("git")
     .subcommand(App::new("clone"))
     .subcommand(App::new("push"))
     .subcommand(App::new("commit"))
     .get_matches();

match app_m.subcommand_name() {
    Some("clone")  => {}, // clone was used
    Some("push")   => {}, // push was used
    Some("commit") => {}, // commit was used
    _              => {}, // Either no subcommand or one not tested for...
}
Examples found in repository
examples/multicall-hostname.rs (line 13)
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
fn main() {
    let app = App::new(env!("CARGO_CRATE_NAME"))
        .setting(AppSettings::ArgRequiredElseHelp)
        .subcommand_value_name("APPLET")
        .subcommand_help_heading("APPLETS")
        .subcommand(App::new("hostname").about("show hostname part of FQDN"))
        .subcommand(App::new("dnsdomainname").about("show domain name part of FQDN"));

    let app = app.setting(AppSettings::Multicall);

    match app.get_matches().subcommand_name() {
        Some("hostname") => println!("www"),
        Some("dnsdomainname") => println!("example.com"),
        _ => unreachable!("parser should ensure only valid subcommand names are used"),
    }
}

Trait Implementations

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

Formats the value using the given formatter. Read more

Returns the “default value” for a type. Read more

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

This method tests for !=.

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Compare self to key and return true if they are equal.

Performs the conversion.

Performs the conversion.

The resulting type after obtaining ownership.

Creates owned data from borrowed data, usually by cloning. Read more

🔬 This is a nightly-only experimental API. (toowned_clone_into)

Uses borrowed data to replace owned data, usually by cloning. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.