Skip to main content

## Parser

# Trait Parser

Source

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

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`.

NOTE: Deriving requires the `derive` feature flag

## Provided Methods§

Source

#### fn parse() -> Self

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

##### Examples found in repository?

examples/typed-derive/main.rs (line 20)

    19fn main() {
    20    let cli = Cli::parse();
    21    println!("{cli:?}");
    22}

More examples
Hide additional examples
examples/derive_ref/flatten_hand_args.rs (line 89)

    88fn main() {
    89    let args = Cli::parse();
    90    println!("{args:#?}");
    91}

examples/derive_ref/hand_subcommand.rs (line 78)

    77fn main() {
    78    let args = Cli::parse();
    79    println!("{args:#?}");
    80}

examples/tutorial_derive/04_02_parse.rs (line 12)

    11fn main() {
    12    let cli = Cli::parse();
    13
    14    println!("PORT = {}", cli.port);
    15}

examples/tutorial_derive/04_02_validate.rs (line 14)

    13fn main() {
    14    let cli = Cli::parse();
    15
    16    println!("PORT = {}", cli.port);
    17}

examples/tutorial_derive/05_01_assert.rs (line 11)

    10fn main() {
    11    let cli = Cli::parse();
    12
    13    println!("PORT = {}", cli.port);
    14}

Additional examples can be found in:

- examples/tutorial_derive/03_02_option.rs
- examples/tutorial_derive/03_02_option_mult.rs
- examples/tutorial_derive/03_03_positional.rs
- examples/tutorial_derive/03_03_positional_mult.rs
- examples/tutorial_derive/03_05_default_values.rs
- examples/tutorial_derive/03_06_optional.rs
- examples/tutorial_derive/03_01_flag_bool.rs
- examples/tutorial_derive/03_01_flag_count.rs
- examples/cargo-example-derive.rs
- examples/tutorial_derive/02_app_settings.rs
- examples/tutorial_derive/02_apps.rs
- examples/tutorial_derive/02_crate.rs
- examples/demo.rs
- examples/tutorial_derive/04_01_enum.rs
- examples/tutorial_derive/03_04_subcommands.rs
- examples/tutorial_derive/03_04_subcommands_alt.rs
- examples/escaped-positional-derive.rs
- examples/tutorial_derive/04_03_relations.rs
- examples/tutorial_derive/01_quick.rs
- examples/tutorial_derive/04_04_custom.rs
- examples/git-derive.rs

Source

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

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

Source

#### fn parse_from<I, T>(itr: I) -> Self
where I: IntoIterator<Item = T>, T: Into<OsString> + Clone,

Parse from iterator, exit on error.

Source

#### 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.

##### Examples found in repository?

examples/repl-derive.rs (line 31)

    29fn respond(line: &str) -> Result<bool, String> {
    30    let args = shlex::split(line).ok_or("error: Invalid quoting")?;
    31    let cli = Cli::try_parse_from(args).map_err(|e| e.to_string())?;
    32    match cli.command {
    33        Commands::Ping => {
    34            write!(std::io::stdout(), "Pong").map_err(|e| e.to_string())?;
    35            std::io::stdout().flush().map_err(|e| e.to_string())?;
    36        }
    37        Commands::Exit => {
    38            write!(std::io::stdout(), "Exiting ...").map_err(|e| e.to_string())?;
    39            std::io::stdout().flush().map_err(|e| e.to_string())?;
    40            return Ok(true);
    41        }
    42    }
    43    Ok(false)
    44}

Source

#### fn update_from<I, T>(&mut self, itr: I)
where I: IntoIterator<Item = T>, T: Into<OsString> + Clone,

Update from iterator, exit on error.

Unlike `Parser::parse`, this works with an existing instance of `self`. The assumption is that all required fields are already provided and any `Args` or `Subcommand`s provided by the user will modify only what is specified.

Source

#### 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.

## Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

## Implementations on Foreign Types§

Source§

### impl<T> Parser for Box<T>
where T: Parser,

Source§

#### fn parse() -> Box<T>

Source§

#### fn try_parse() -> Result<Box<T>, Error>

Source§

#### fn parse_from<I, It>(itr: I) -> Box<T>
where I: IntoIterator<Item = It>, It: Into<OsString> + Clone,

Source§

#### fn try_parse_from<I, It>(itr: I) -> Result<Box<T>, Error>
where I: IntoIterator<Item = It>, It: Into<OsString> + Clone,

## Implementors§