logo
pub trait Parser: FromArgMatches + CommandFactory + Sized {
    fn parse() -> Self { ... }
    fn try_parse() -> Result<Self, Error> { ... }
    fn parse_from<I, T>(itr: I) -> Self
   where
        I: IntoIterator<Item = T>,
        T: Into<OsString> + Clone
, { ... } fn try_parse_from<I, T>(itr: I) -> Result<Self, Error>
   where
        I: IntoIterator<Item = T>,
        T: Into<OsString> + Clone
, { ... } fn update_from<I, T>(&mut self, itr: I)
   where
        I: IntoIterator<Item = T>,
        T: Into<OsString> + Clone
, { ... } fn try_update_from<I, T>(&mut self, itr: I) -> Result<(), Error>
   where
        I: IntoIterator<Item = T>,
        T: Into<OsString> + Clone
, { ... } }
Expand description

Parse command-line arguments into Self.

The primary one-stop-shop trait used to create an instance of a clap Command, conduct the parsing, and turn the resulting ArgMatches back into concrete instance of the user struct.

This trait is primarily a convenience on top of FromArgMatches + CommandFactory which uses those two underlying traits to build the two fundamental functions parse which uses the std::env::args_os iterator, and parse_from which allows the consumer to supply the iterator (along with fallible options for each).

See also Subcommand and Args.

See the derive reference for attributes and best practices.

NOTE: Deriving requires the derive feature flag

Examples

The following example creates a Context struct that would be used throughout the application representing the normalized values coming from the CLI.

/// My super CLI
#[derive(clap::Parser)]
#[command(name = "demo")]
struct Context {
   /// More verbose output
   #[arg(long)]
   verbose: bool,
   /// An optional name
   #[arg(short, long)]
   name: Option<String>,
}

The equivalent Command struct + From implementation:

Command::new("demo")
    .about("My super CLI")
    .arg(Arg::new("verbose")
        .long("verbose")
        .action(ArgAction::SetTrue)
        .help("More verbose output"))
    .arg(Arg::new("name")
        .long("name")
        .short('n')
        .help("An optional name")
        .action(ArgAction::Set));

struct Context {
    verbose: bool,
    name: Option<String>,
}

impl From<ArgMatches> for Context {
    fn from(m: ArgMatches) -> Self {
        Context {
            verbose: *m.get_one::<bool>("verbose").expect("defaulted_by_clap"),
            name: m.get_one::<String>("name").cloned(),
        }
    }
}

Provided Methods

Parse from std::env::args_os(), exit on error

Examples found in repository?
examples/derive_ref/custom-bool.rs (line 30)
29
30
31
32
fn main() {
    let opt = Opt::parse();
    dbg!(opt);
}
More examples
Hide additional examples
examples/derive_ref/flatten_hand_args.rs (line 89)
88
89
90
91
fn main() {
    let args = Cli::parse();
    println!("{:#?}", args);
}
examples/typed-derive.rs (line 42)
41
42
43
44
fn main() {
    let args = Args::parse();
    println!("{:?}", args);
}
examples/derive_ref/hand_subcommand.rs (line 77)
76
77
78
79
fn main() {
    let args = Cli::parse();
    println!("{:#?}", args);
}
examples/tutorial_derive/04_02_validate.rs (line 14)
13
14
15
16
17
fn main() {
    let cli = Cli::parse();

    println!("PORT = {}", cli.port);
}
examples/tutorial_derive/05_01_assert.rs (line 11)
10
11
12
13
14
fn main() {
    let cli = Cli::parse();

    println!("PORT = {}", cli.port);
}

Parse from std::env::args_os(), return Err on error.

Parse from iterator, exit on error

Parse from iterator, return Err on error.

Update from iterator, exit on error

Update from iterator, return Err on error.

Implementations on Foreign Types

Implementors