Skip to main content

## Module escaped_positional_derive

Source
Available on crate feature `unstable-doc` only.
Expand description

## §Example (Derive API)

    use clap::Parser;

    #[derive(Parser)] // requires `derive` feature
    #[command(version, about, long_about = None)]
    struct Cli {
        #[arg(short = 'f')]
        eff: bool,

        #[arg(short = 'p', value_name = "PEAR")]
        pea: Option<String>,

        #[arg(last = true)]
        slop: Vec<String>,
    }

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

        // This is what will happen with `myprog -f -p=bob -- sloppy slop slop`...
        println!("-f used: {:?}", args.eff); // -f used: true
        println!("-p's value: {:?}", args.pea); // -p's value: Some("bob")
        println!("'slops' values: {:?}", args.slop); // 'slops' values: Some(["sloppy", "slop", "slop"])

        // Continued program logic goes here...
    }

This requires enabling the `derive` feature flag.

You can use `--` to escape further arguments.

Let’s see what this looks like in the help:

    $ escaped-positional-derive --help
    A simple to use, efficient, and full-featured Command Line Argument Parser

    Usage: escaped-positional-derive[EXE] [OPTIONS] [-- <SLOP>...]

    Arguments:
      [SLOP]...

    Options:
      -f
      -p <PEAR>
      -h, --help     Print help
      -V, --version  Print version

Here is a baseline without any arguments:

    $ escaped-positional-derive
    -f used: false
    -p's value: None
    'slops' values: []

Notice that we can’t pass positional arguments before `--`:

    $ escaped-positional-derive foo bar
    ? failed
    error: unexpected argument 'foo' found

    Usage: escaped-positional-derive[EXE] [OPTIONS] [-- <SLOP>...]

    For more information, try '--help'.

But you can after:

    $ escaped-positional-derive -f -p=bob -- sloppy slop slop
    -f used: true
    -p's value: Some("bob")
    'slops' values: ["sloppy", "slop", "slop"]

As mentioned, the parser will directly pass everything through:

    $ escaped-positional-derive -- -f -p=bob sloppy slop slop
    -f used: false
    -p's value: None
    'slops' values: ["-f", "-p=bob", "sloppy", "slop", "slop"]