Struct Arg 

pub struct Arg { /* private fields */ }

Available on crate feature std only.

A single argument a command accepts.

Build one with Arg::flag, Arg::option, or Arg::positional, then attach it with Command::arg. The name is the key used to read the parsed result back out of a Matches.

Examples

use cli_forge::Arg;

let verbose = Arg::count("verbose").short('v').help("increase verbosity");
let define = Arg::option("define").short('D').multiple(true);
let files = Arg::positional("files").multiple(true).required(true);

Implementations

impl Arg

pub fn flag(name: impl Into<String>) -> Arg

Define a boolean flag, e.g. --verbose. The long form defaults to the name; add a short for a one-letter alias.

Examples

use cli_forge::Arg;
let force = Arg::flag("force").short('f');

pub fn count(name: impl Into<String>) -> Arg

Define a counting flag: a switch that may be repeated, whose occurrences are tallied. -v, -vv, -vvv (or -v -v -v, or --verbose --verbose) count 1, 2, 3. Read the count with Matches::count.

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 m = app.try_parse_from(["run", "-vvv"]).unwrap();
assert_eq!(m.subcommand().unwrap().1.count("verbose"), 3);

pub fn option(name: impl Into<String>) -> Arg

Define a value-taking option, e.g. --output file. Accepts --name v, --name=v, -x v, and -xv at parse time. Mark it multiple to accept it more than once.

Examples

use cli_forge::Arg;
let out = Arg::option("output").short('o').required(true);

pub fn positional(name: impl Into<String>) -> Arg

Define a positional argument, filled by bare values in order.

Examples

use cli_forge::Arg;
let path = Arg::positional("path").default(".");

pub fn short(self, short: char) -> Arg

Set a one-letter short form (-x). Ignored for positionals.

pub fn long(self, long: impl Into<String>) -> Arg

Override the long form (--name). Defaults to the argument’s name. Ignored for positionals.

pub fn help(self, help: impl Into<String>) -> Arg

Attach help text, shown in generated help.

pub fn required(self, required: bool) -> Arg

Require the argument. Parsing fails with ParseError::MissingRequired if it is absent and has no default. Has no effect on flags or counts (they are simply present or not).

pub fn multiple(self, multiple: bool) -> Arg

Collect every occurrence into a list instead of keeping a single value.

For an option, each --name v appends a value: -D A -D B yields ["A", "B"]. For a positional, it becomes variadic and absorbs every remaining bare value: a b c yields ["a", "b", "c"] (put it last). Read the values with Matches::values. Ignored for flags and counts.

Examples

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

let mut app = App::new("cc");
app.register(
    Command::new("build")
        .arg(Arg::option("include").short('I').multiple(true))
        .arg(Arg::positional("sources").multiple(true)),
);

let m = app.try_parse_from(["build", "-I", "a", "-I", "b", "x.c", "y.c"]).unwrap();
let (_, build) = m.subcommand().unwrap();
assert_eq!(build.values("include").collect::<Vec<_>>(), ["a", "b"]);
assert_eq!(build.values("sources").collect::<Vec<_>>(), ["x.c", "y.c"]);

pub fn default(self, value: impl Into<String>) -> Arg

Provide a default value used when an option or positional is omitted. A default makes the argument effectively optional even if required was set.

Trait Implementations

impl Clone for Arg

fn clone(&self) -> Arg

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Arg

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.