Struct clap::ArgMatches

pub struct ArgMatches<'a> {
    pub flags: HashMap<&'a str, FlagArg>,
    pub opts: HashMap<&'a str, OptArg>,
    pub positionals: HashMap<&'a str, PosArg>,
    pub subcommand: Option<Box<SubCommand<'a>>>,
}

Used to get information about the arguments that where supplied to the program at runtime.

Fields of ArgMatches aren't designed to be used directly, only the methods in order to query information.

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

// Although not advised, if you have a required argument
// you can call .unwrap() because the program will exit long before
// here at noticing the user didn't supply a required argument...
// use at your own risk ;)
println!("Config file: {}", matches.value_of("config").unwrap());

// You can check the present of an argument
if matches.is_present("debug") {
    // Checking if "debug" was present was necessary,
    // as occurrences returns 0 if a flag isn't found
    // but we can check how many times "debug" was found
    // if we allow multiple (if multiple isn't allowed it always be 1 or 0)
    if matches.occurrences_of("debug") > 1 {
        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...");
    }
}

Fields

flags: HashMap<&'a str, FlagArg>

opts: HashMap<&'a str, OptArg>

positionals: HashMap<&'a str, PosArg>

subcommand: Option<Box<SubCommand<'a>>>

Methods

impl<'a> ArgMatches<'a>

fn new() -> ArgMatches<'a>

Creates a new instance of ArgMatches. This ins't called directly, but through the .get_matches() method of App

Example

let matches = App::new("myprog").get_matches();

fn value_of<'n>(&self, name: &'n 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);
}

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

Gets the values of a specific option or positional argument in a vector (i.e. an argument that takes an additional value 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);
       }
}

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

Checks if a flag was argument was supplied at runtime. DOES NOT work for option or positional arguments (use .value_of() instead)

Example

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

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

Checks the number of occurrences of an option, flag, or positional argument at runtime. If an option or flag isn't present it will return 0, if the option or flag doesn't allow multiple occurrences, it will return 1 no matter how many times it occurred (unless it wasn't prsent) at all.

Example

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

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

If a subcommand was found, returns the ArgMatches struct associated with it's matches

Example

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

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

If a subcommand was found, returns the name associated with it

Example

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