Struct bpaf::Command

pub struct Command<T> { /* private fields */ }

Builder structure for the command

Created with command, implements parser for the inner structure, gives access to help.

Implementations

impl<P> Command<P>

pub fn help<M>(self, help: M) -> Self where
    M: Into<String>, 

Add a brief description to a command

bpaf uses this description along with the command name in help output so it shouldn’t exceed one or two lines. If help isn’t specified bpaf falls back to descr from the inner parser.

Combinatoric usage

fn inner() -> OptionParser<bool> {
    short('i')
        .help("Mysterious inner switch")
        .switch()
        .to_options()
        .descr("performs an operation")
}

fn mysterious_parser() -> impl Parser<bool> {
    command("mystery", inner())
        .help("This command performs a mystery operation")
}

Derive usage

bpaf_derive uses doc comments for inner parser, no specific options are available. See descr for more details

/// This command performs a mystery operation
#[derive(Debug, Clone, Bpaf)]
#[bpaf(command)]
struct Mystery {
    #[bpaf(short)]
    /// Mysterious inner switch
    inner: bool,
}

Example

$ app --help
    <skip>
Available commands:
    mystery  This command performs a mystery operation

Examples found in repository

examples/enum_tuple.rs (line 27)

↕

fn main() {
    let bar = short('b')
        .long("bar")
        .help("some bar command")
        .argument("BAR")
        .optional();

    let bar_cmd = construct!(Foo { bar })
        .to_options()
        .descr("This command will try to do foo given a bar argument");

    let opt = command("foo", bar_cmd)
        .help("command for doing foo")
        .map(Command::Foo)
        .to_options()
        .run();

    println!("{:#?}", opt);
}

examples/git.rs (line 49)

↕

fn main() {
    let dry_run = long("dry_run").switch();
    let all = long("all").switch();
    let repository = positional("SRC").fallback("origin".to_string());
    let fetch = construct!(Opt::Fetch {
        dry_run,
        all,
        repository
    })
    .to_options()
    .descr("fetches branches from remote repository");

    let fetch_cmd = command("fetch", fetch);

    let interactive = short('i').switch();
    let all = long("all").switch();
    let files = positional("FILE").many();
    let add = construct!(Opt::Add {
        interactive,
        all,
        files
    })
    .to_options()
    .descr("add files to the staging area");

    let add_cmd = command("add", add).help("add files to the staging area");

    let opt = construct!([fetch_cmd, add_cmd])
        .to_options()
        .descr("The stupid content tracker")
        .run();

    println!("{:?}", opt);
}

pub fn short(self, short: char) -> Self

Add a custom short alias for a command

Behavior is similar to short, only first short name is visible.

pub fn long(self, long: &'static str) -> Self

Add a custom hidden long alias for a command

Behavior is similar to long, but since you had to specify the first long name when making the command - this one becomes a hidden alias.

Trait Implementations

impl<T> Parser<T> for Command<T>

fn many(self) -> ParseMany<Self> where
    Self: Sized, 

Consume zero or more items from a command line and collect them into Vec

fn some(self, message: &'static str) -> ParseSome<Self> where
    Self: Sized + Parser<T>, 

Consume one or more items from a command line

fn optional(self) -> ParseOptional<Self> where
    Self: Sized + Parser<T>, 

Turn a required argument into optional one

fn parse<F, R, E>(self, f: F) -> ParseWith<T, Self, F, E, R> where
    Self: Sized + Parser<T>,
    F: Fn(T) -> Result<R, E>,
    E: ToString, 

Apply a failing transformation to a contained value

fn map<F, R>(self, map: F) -> ParseMap<T, Self, F, R> where
    Self: Sized + Parser<T>,
    F: Fn(T) -> R + 'static, 

Apply a pure transformation to a contained value

fn from_str<R>(self) -> ParseFromStr<Self, R> where
    Self: Sized + Parser<T>, 

Parse stored String using FromStr instance

fn guard<F>(self, check: F, message: &'static str) -> ParseGuard<Self, F> where
    Self: Sized + Parser<T>,
    F: Fn(&T) -> bool, 

Validate or fail with a message

fn fallback(self, value: T) -> ParseFallback<Self, T> where
    Self: Sized + Parser<T>, 

Use this value as default if value isn’t present on a command line

fn fallback_with<F, E>(self, fallback: F) -> ParseFallbackWith<T, Self, F, E> where
    Self: Sized + Parser<T>,
    F: Fn() -> Result<T, E>,
    E: ToString, 

Use value produced by this function as default if value isn’t present

fn hide(self) -> ParseHide<Self> where
    Self: Sized + Parser<T>, 

Ignore this parser during any sort of help generation

fn group_help(self, message: &'static str) -> ParseGroupHelp<Self> where
    Self: Sized + Parser<T>, 

Attach help message to a complex parser

fn to_options(self) -> OptionParser<T> where
    Self: Sized + Parser<T> + 'static, 

Transform Parser into OptionParser to attach metadata and run