Skip to main content

## Module escaped_positional

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

## §Example (Builder API)

    use clap::{ArgAction, arg, command, value_parser};

    fn main() {
        let matches = command!() // requires `cargo` feature
            .arg(arg!(eff: -f).action(ArgAction::SetTrue))
            .arg(arg!(pea: -p <PEAR>).value_parser(value_parser!(String)))
            .arg(
                // Indicates that `slop` is only accessible after `--`.
                arg!(slop: [SLOP])
                    .num_args(1..)
                    .last(true)
                    .value_parser(value_parser!(String)),
            )
            .get_matches();

        // This is what will happen with `myprog -f -p=bob -- sloppy slop slop`...

        // -f used: true
        println!("-f used: {:?}", matches.get_flag("eff"));
        // -p's value: Some("bob")
        println!("-p's value: {:?}", matches.get_one::<String>("pea"));
        // 'slops' values: Some(["sloppy", "slop", "slop"])
        println!(
            "'slops' values: {:?}",
            matches
                .get_many::<String>("slop")
                .map(|vals| vals.collect::<Vec<_>>())
                .unwrap_or_default()
        );

        // Continued program logic goes here...
    }

This requires enabling the `cargo` feature flag.

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

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

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

    Usage: escaped-positional[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
    -f used: false
    -p's value: None
    'slops' values: []

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

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

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

    For more information, try '--help'.

But you can after:

    $ escaped-positional -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 -- -f -p=bob sloppy slop slop
    -f used: false
    -p's value: None
    'slops' values: ["-f", "-p=bob", "sloppy", "slop", "slop"]