Function cargo_helper

pub fn cargo_helper<P, T>(cmd: &'static str, parser: P) -> impl Parser<T>
where
    P: Parser<T>,

Available on crate feature batteries only.

Strip a command name if present at the front when used as a cargo command

When implementing a cargo subcommand parser needs to be able to skip the first argument which is always the same as the executable name without cargo- prefix. For example if executable name is cargo-cmd so first argument would be cmd. cargo_helper helps to support both invocations: with name present when used via cargo and without it when used locally.

You can read the code of this function as this approximate sequence of statements:

1. Try to parse a string literal that corresponds to a command name
2. It’s okay if it’s missing
3. And don’t show anything to the user in --help or completion
4. Parse this word and then everything else as a tuple, return that second item.

Combinatoric example

#[derive(Debug, Clone)]
pub struct Options {
    argument: usize,
    switch: bool,
}

pub fn options() -> OptionParser<Options> {
    let argument = long("argument")
        .help("An argument")
        .argument::<usize>("ARG");
    let switch = short('s').help("A switch").switch();
    let options = construct!(Options { argument, switch });

    // Given the cargo command is `cargo pretty`.
    cargo_helper("pretty", options).to_options()
}

fn main() {
    println!("{:?}", options().run())
}

Derive example

#[derive(Debug, Clone, Bpaf)]
#[bpaf(options("pretty"))] // Given the cargo command is `cargo pretty`.
pub struct Options {
    /// An argument
    argument: usize,
    /// A switch
    #[bpaf(short)]
    switch: bool,
}

fn main() {
    println!("{:?}", options().run())
}

Output

Let’s say the goal is to parse an argument and a switch:

$ app --argument 15
Options { argument: 15, switch: false }

But when used as a cargo subcommand, cargo will also pass the command name. For example you can invoke an app with binary name cargo-asm

$ cargo asm --lib --everything
...

cargo will then spawn the executable and pass it following parameters:

$ cargo-asm asm --lib --everything
...

If you are not using cargo_helper - parser won’t know what to do with asm part. cargo-helper allows the parser to strip it from the front and everything works as expected.

And it doesn’t show up in --help so not to confuse users

$ app --help

Usage: app --argument=ARG [-s]

Available options:

--argument=ARG

An argument

-s

A switch

-h, --help

Prints help information