Trait clap::Parser

pub trait Parser:
    FromArgMatches
    + CommandFactory
    + Sized {
    // Provided methods
    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 { ... }
}

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][crate::_features]

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)]
#[clap(name = "demo")]
struct Context {
   /// More verbose output
   #[clap(long)]
   verbose: bool,
   /// An optional name
   #[clap(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")
        .takes_value(true));

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

fn parse() -> Self

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

fn try_parse() -> Result<Self, Error>

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

fn parse_from<I, T>(itr: I) -> Self

where I: IntoIterator<Item = T>, T: Into<OsString> + Clone,

Parse from iterator, exit on error

fn try_parse_from<I, T>(itr: I) -> Result<Self, Error>

where I: IntoIterator<Item = T>, T: Into<OsString> + Clone,

Parse from iterator, return Err on error.

fn update_from<I, T>(&mut self, itr: I)

where I: IntoIterator<Item = T>, T: Into<OsString> + Clone,

Update from iterator, exit on error

fn try_update_from<I, T>(&mut self, itr: I) -> Result<(), Error>

where I: IntoIterator<Item = T>, T: Into<OsString> + Clone,

Update from iterator, return Err on error.

Object Safety

This trait is not object safe.

Implementations on Foreign Types

impl<T: Parser> Parser for Box<T>

fn parse() -> Self

fn try_parse() -> Result<Self, Error>

fn parse_from<I, It>(itr: I) -> Self

where I: IntoIterator<Item = It>, It: Into<OsString> + Clone,

fn try_parse_from<I, It>(itr: I) -> Result<Self, Error>

where I: IntoIterator<Item = It>, It: Into<OsString> + Clone,

Implementors