Struct clap::ArgMatches

source ·

pub struct ArgMatches<'n, 'a> { /* private fields */ }

Expand description

Used to get information about the arguments that where supplied to the program at runtime by the user. To get a new instance of this struct you use .get_matches() of the App struct.

§Example

let matches = App::new("MyApp")
// adding of arguments and configuration goes here...
                    .get_matches();
// if you had an argument named "output" that takes a value
if let Some(o) = matches.value_of("output") {
    println!("Value for output: {}", o);
}

// If you have a required argument you can call .unwrap() because the program will exit long
// before this point if the user didn't specify it at runtime.
println!("Config file: {}", matches.value_of("config").unwrap());

// You can check the presence of an argument
if matches.is_present("debug") {
    // 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(true) method, otherwise it will only return 1 or 0.
    if matches.occurrences_of("debug") > 2 {
        println!("Debug mode is REALLY on");
    } else {
        println!("Debug mode kind of on");
    }
}

// You can get the sub-matches of a particular subcommand (in this case "test")
// If "test" had it's own "-l" flag you could check for it's presence accordingly
if let Some(ref matches) = matches.subcommand_matches("test") {
    if matches.is_present("list") {
        println!("Printing testing lists...");
    } else {
        println!("Not printing testing lists...");
    }
}

Implementations§

source §

impl<'n, 'a> ArgMatches<'n, 'a>

source

pub fn value_of<'na>(&self, name: &'na str) -> Option<&str>

Gets the value of a specific option or positional argument (i.e. an argument that takes an additional value at runtime). If the option wasn’t present at runtime it returns None.

NOTE: If getting a value for an option or positional argument that allows multiples, prefer values_of() as value_of() will only return the first value.

§Example

if let Some(o) = matches.value_of("output") {
       println!("Value for output: {}", o);
}

source

pub fn values_of<'na>(&'a self, name: &'na str) -> Option<Vec<&'a str>>

Gets the values of a specific option or positional argument in a vector (i.e. an argument that takes multiple values at runtime). If the option wasn’t present at runtime it returns None

§Example

// If the program had option "-c" that took a value and was run
// via "myapp -o some -o other -o file"
// values_of() would return a [&str; 3] ("some", "other", "file")
if let Some(os) = matches.values_of("output") {
       for o in os {
           println!("A value for output: {}", o);
       }
}

source

pub fn is_present<'na>(&self, name: &'na str) -> bool

Returns if an argument was present at runtime.

§Example

if matches.is_present("output") {
       println!("The output argument was used!");
}

source

pub fn occurrences_of<'na>(&self, name: &'na str) -> u8

Returns the number of occurrences of an option, flag, or positional argument at runtime. If an argument isn’t present it will return 0. Can be used on arguments which don’t allow multiple occurrences, but will obviously only return 0 or 1.

§Example

if matches.occurrences_of("debug") > 1 {
    println!("Debug mode is REALLY on");
} else {
    println!("Debug mode kind of on");
}

source

pub fn subcommand_matches<'na>( &self, name: &'na str, ) -> Option<&ArgMatches<'_, '_>>

Returns the ArgMatches for a particular subcommand or None if the subcommand wasn’t present at runtime.

§Example

if let Some(matches) = app_matches.subcommand_matches("test") {
    // Use matches as normal
}

source

pub fn subcommand_name(&self) -> Option<&str>

Returns the name of the subcommand used of the parent App, or None if one wasn’t found

NOTE: Only a single subcommand may be present per App at runtime, does NOT check for the name of sub-subcommand’s names

§Example

match app_matches.subcommand_name() {
    Some("test")   => {}, // test was used
    Some("config") => {}, // config was used
    _              => {}, // Either no subcommand or one not tested for...
}

source

pub fn subcommand(&self) -> (&str, Option<&ArgMatches<'_, '_>>)

Returns the name and ArgMatches of the subcommand used at runtime or (“”, None) if one wasn’t found.

§Example

match app_matches.subcommand() {
    ("test", Some(matches))   => {}, // test was used
    ("config", Some(matches)) => {}, // config was used
    _                         => {}, // Either no subcommand or one not tested for...
}

source