Struct Matches

Source

pub struct Matches { /* private fields */ }

Available on crate feature std only.

Expand description

Parsed arguments for one command level.

Read flags with flag, counting flags with count, single values with value, repeated/variadic values with values, and descend into an invoked subcommand with subcommand.

§Examples

use cli_forge::{App, Arg, Command};

let mut app = App::new("demo");
app.register(
    Command::new("build")
        .arg(Arg::flag("release").short('r'))
        .arg(Arg::count("verbose").short('v'))
        .arg(Arg::option("jobs").short('j').default("1")),
);

let matches = app.try_parse_from(["build", "-r", "-vv", "--jobs", "8"]).unwrap();
let (name, build) = matches.subcommand().unwrap();
assert_eq!(name, "build");
assert!(build.flag("release"));
assert_eq!(build.count("verbose"), 2);
assert_eq!(build.value("jobs"), Some("8"));

Implementations§

Source §

impl Matches

Source

pub fn flag(&self, name: &str) -> bool

Whether the flag named name was set.

Returns false for an unset flag or an unknown name. A counting flag reports true once its count reaches one, so flag works for either kind.

§Examples

use cli_forge::{App, Arg, Command};

let mut app = App::new("demo");
app.register(Command::new("run").arg(Arg::flag("verbose").short('v')));

let m = app.try_parse_from(["run", "-v"]).unwrap();
assert!(m.subcommand().unwrap().1.flag("verbose"));

Source

pub fn count(&self, name: &str) -> usize

How many times the counting flag named name was given.

Returns 0 for a flag that was not given or an unknown name.

§Examples

use cli_forge::{App, Arg, Command};

let mut app = App::new("demo");
app.register(Command::new("run").arg(Arg::count("verbose").short('v')));

let quiet = app.try_parse_from(["run"]).unwrap();
assert_eq!(quiet.subcommand().unwrap().1.count("verbose"), 0);

let loud = app.try_parse_from(["run", "-vvv"]).unwrap();
assert_eq!(loud.subcommand().unwrap().1.count("verbose"), 3);

Source

pub fn value(&self, name: &str) -> Option<&str>

The value given for an option or positional named name, or its default.

Returns None if the argument was not provided and has no default, or if the name is unknown. For a multiple argument this is the first value; use values for all of them.

§Examples

use cli_forge::{App, Arg, Command};

let mut app = App::new("demo");
app.register(Command::new("greet").arg(Arg::positional("name").default("world")));

let provided = app.try_parse_from(["greet", "Ada"]).unwrap();
assert_eq!(provided.subcommand().unwrap().1.value("name"), Some("Ada"));

let defaulted = app.try_parse_from(["greet"]).unwrap();
assert_eq!(defaulted.subcommand().unwrap().1.value("name"), Some("world"));

Source

pub fn values(&self, name: &str) -> impl Iterator<Item = &str>

Every value collected for name, in the order given.

Yields all values of a multiple option or variadic positional; for a single-valued argument it yields its one value (or its default). The iterator is empty for an argument that was not provided or an unknown name.

§Examples

use cli_forge::{App, Arg, Command};

let mut app = App::new("cc");
app.register(Command::new("build").arg(Arg::option("define").short('D').multiple(true)));

let m = app.try_parse_from(["build", "-D", "A=1", "-D", "B=2"]).unwrap();
let defines: Vec<&str> = m.subcommand().unwrap().1.values("define").collect();
assert_eq!(defines, ["A=1", "B=2"]);

Iterate directly without collecting:

let mut count = 0;
for file in build.values("files") {
    let _ = file;
    count += 1;
}
assert_eq!(count, 2);

Source

pub fn subcommand(&self) -> Option<(&str, &Matches)>

The invoked subcommand’s name and its own Matches, if one was given.

§Examples

use cli_forge::{App, Command};

let mut app = App::new("demo");
app.register(Command::new("status"));

let m = app.try_parse_from(["status"]).unwrap();
assert_eq!(m.subcommand().map(|(name, _)| name), Some("status"));