logo

Trait clap::Parser[−][src]

pub trait Parser: FromArgMatches + IntoApp + 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,
    { ... }

    fn clap<'help>() -> App<'help> { ... }

    fn from_clap(matches: &ArgMatches) -> Self { ... }

    fn from_args() -> Self { ... }

    fn from_args_safe() -> Result<Self, Error> { ... }

    fn from_iter<I, T>(itr: I) -> Self
    where
        I: IntoIterator<Item = T>,
        T: Into<OsString> + Clone,
    { ... }

    fn from_iter_safe<I, T>(itr: I) -> Result<Self, 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 App, 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 + IntoApp 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)]
#[clap(name = "demo")]
struct Context {
   /// More verbose output
   #[clap(long)]
   verbose: bool,
   /// An optional name
   #[clap(short, long)]
   name: Option<String>,
}

The equivalent App struct + From implementation:

App::new("demo")
    .about("My super CLI")
    .arg(Arg::new("verbose")
        .long("verbose")
        .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.is_present("verbose"),
            name: m.value_of("name").map(|n| n.to_owned()),
        }
    }
}

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
examples/keyvalue-derive.rs (line 27)
26
27
28
29

fn main() {
    let args = Args::parse();
    println!("{:?}", args);
}
examples/tutorial_derive/04_02_validate.rs (line 12)
11
12
13
14
15

fn main() {
    let cli = Cli::parse();

    println!("PORT = {}", cli.port);
}
examples/tutorial_derive/05_01_assert.rs (line 12)
11
12
13
14
15

fn main() {
    let cli = Cli::parse();

    println!("PORT = {}", cli.port);
}
examples/tutorial_derive/03_05_default_values.rs (line 11)
10
11
12
13
14

fn main() {
    let cli = Cli::parse();

    println!("name: {:?}", cli.name);
}
examples/tutorial_derive/03_01_flag_count.rs (line 11)
10
11
12
13
14

fn main() {
    let cli = Cli::parse();

    println!("verbose: {:?}", cli.verbose);
}
Additional examples can be found in:

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.

👎 Deprecated since 3.0.0:

StructOpt::clap is replaced with IntoApp::into_app (derived as part of Parser)

Deprecated, StructOpt::clap replaced with IntoApp::into_app (derive as part of Parser)

👎 Deprecated since 3.0.0:

StructOpt::from_clap is replaced with FromArgMatches::from_arg_matches (derived as part of Parser)

Deprecated, StructOpt::from_clap replaced with FromArgMatches::from_arg_matches (derive as part of Parser)

👎 Deprecated since 3.0.0:

StructOpt::from_args is replaced with Parser::parse (note the change in derives)

Deprecated, StructOpt::from_args replaced with Parser::parse (note the change in derives)

👎 Deprecated since 3.0.0:

StructOpt::from_args_safe is replaced with Parser::try_parse (note the change in derives)

Deprecated, StructOpt::from_args_safe replaced with Parser::try_parse (note the change in derives)

👎 Deprecated since 3.0.0:

StructOpt::from_iter is replaced with Parser::parse_from (note the change in derives)

Deprecated, StructOpt::from_iter replaced with Parser::parse_from (note the change in derives)

👎 Deprecated since 3.0.0:

StructOpt::from_iter_safe is replaced with Parser::try_parse_from (note the change in derives)

Deprecated, StructOpt::from_iter_safe replaced with Parser::try_parse_from (note the change in derives)

Implementations on Foreign Types

Implementors