Struct ParsePositional 

pub struct ParsePositional<T> {
    metavar: &'static str,
    help: Option<Doc>,
    position: Position,
    ty: PhantomData<T>,
}

Parse a positional item, created with positional

You can add extra information to positional parsers with help, strict, or non_strict on this struct.

Fields

metavar: &'static str

help: Option<Doc>

position: Position

ty: PhantomData<T>

Implementations

impl<T> ParsePositional<T>

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

where M: Into<Doc>,

Add a help message to a positional parser

bpaf converts doc comments and string into help by following those rules:

1. Everything up to the first blank line is included into a “short” help message
2. Everything is included into a “long” help message
3. bpaf preserves linebreaks followed by a line that starts with a space
4. Linebreaks are removed otherwise

You can pass anything that can be converted into Doc, if you are not using documentation generation functionality (doc) this can be &str.

Combinatoric example

#[derive(Debug, Clone)]
pub struct Options {
    verbose: bool,
    crate_name: String,
    feature_name: Option<String>,
}

pub fn options() -> OptionParser<Options> {
    let verbose = short('v')
        .long("verbose")
        .help("Display detailed information")
        .switch();

    let crate_name = positional("CRATE").help("Crate name to use");

    let feature_name = positional("FEATURE")
        .help("Display information about this feature")
        .optional();

    construct!(Options {
        verbose,
        // You must place positional items and commands after
        // all other parsers
        crate_name,
        feature_name
    })
    .to_options()
}

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

Derive example

#[derive(Debug, Clone, Bpaf)]
#[bpaf(options)]
pub struct Options {
    /// Display detailed information
    #[bpaf(short, long)]
    verbose: bool,

    // You must place positional items and commands after
    // all other parsers
    #[bpaf(positional("CRATE"))]
    /// Crate name to use
    crate_name: String,

    #[bpaf(positional("FEATURE"))]
    /// Display information about this feature
    feature_name: Option<String>,
}

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

Output

Positional items show up in a separate group of arguments if they contain a help message, otherwise they will show up only in Usage part.

$ app --help

Usage: app [-v] CRATE [FEATURE]

Available positional items:

CRATE

Crate name to use

FEATURE

Display information about this feature

Available options:

-v, --verbose

Display detailed information

-h, --help

Prints help information

You can mix positional items with regular items

$ app --verbose bpaf
Options { verbose: true, crate_name: "bpaf", feature_name: None }

And since bpaf API expects to have non positional items consumed before positional ones - you can use them in a different order. In this example bpaf corresponds to a crate_name field and --verbose – to verbose.

$ app bpaf --verbose
Options { verbose: true, crate_name: "bpaf", feature_name: None }

In previous examples optional field feature was missing, this one contains it.

$ app bpaf autocomplete
Options { verbose: false, crate_name: "bpaf", feature_name: Some("autocomplete") }

Users can use -- to tell bpaf to treat remaining items as positionals - this might be required to handle unusual items.

$ app bpaf -- --verbose
Options { verbose: false, crate_name: "bpaf", feature_name: Some("--verbose") }

$ app -- bpaf --verbose
Options { verbose: false, crate_name: "bpaf", feature_name: Some("--verbose") }

Without using -- bpaf would only accept items that don’t start with - as positional.

$ app --detailed
Error: expected CRATE, got --detailed. Pass --help for usage information

$ app --verbose
Error: expected CRATE, pass --help for usage information

You can use any to work around this restriction.

pub fn strict(self) -> ParsePositional<T>

Changes positional parser to be a “strict” positional

Usually positional items can appear anywhere on a command line:

$ ls -d bpaf
$ ls bpaf -d

here ls takes a positional item bpaf and a flag -d

But in some cases it might be useful to have a stricter separation between positonal items and flags, such as passing arguments to a subprocess:

$ cargo run --example basic -- --help

here cargo takes a --help as a positional item and passes it to the example

bpaf allows to require user to pass -- for positional items with strict annotation. bpaf would display such positional elements differently in usage line as well.

Combinatoric example

#[derive(Debug, Clone)]
pub struct Options {
    verbose: bool,
    binary: String,
    args: Vec<String>,
}

pub fn options() -> OptionParser<Options> {
    let verbose = short('v')
        .long("verbose")
        .help("Produce detailed report")
        .switch();
    let binary = long("bin").help("Binary to execute").argument("BIN");
    let args = positional("ARG")
        .help("Arguments for the binary")
        .strict()
        .many();
    construct!(Options {
        verbose,
        binary,
        args
    })
    .to_options()
}

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

Derive example

#[derive(Debug, Clone, Bpaf)]
#[bpaf(options)]
pub struct Options {
    #[bpaf(short, long)]
    /// Produce detailed report
    verbose: bool,
    #[bpaf(long("bin"), argument("BIN"))]
    /// Binary to execute
    binary: String,
    #[bpaf(positional("ARG"), strict, many)]
    /// Arguments for the binary
    args: Vec<String>,
}

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

Output

Usage line for a cargo-run like app that takes an app name and possibly many strictly positional child arguments can look like this:

$ app --help

Usage: app [-v] --bin=BIN -- [ARG]...

Available positional items:

ARG

Arguments for the binary

Available options:

-v, --verbose

Produce detailed report

--bin=BIN

Binary to execute

-h, --help

Prints help information

Here any argument passed before double dash goes to the parser itself

$ app --bin dd --verbose
Options { verbose: true, binary: "dd", args: [] }

Anything after it - collected into strict arguments

$ app --bin dd -- --verbose
Options { verbose: false, binary: "dd", args: ["--verbose"] }

pub fn non_strict(self) -> Self

Changes positional parser to be a “not strict” positional

Ensures the parser always rejects “strict” positions to the right of the separator, --. Essentially the inverse operation to ParsePositional::strict, which can be used to ensure adjacent strict and nonstrict args never conflict with eachother.

fn meta(&self) -> Meta

Trait Implementations

impl<T: Clone> Clone for ParsePositional<T>

fn clone(&self) -> ParsePositional<T>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T> Parser<T> for ParsePositional<T>

where T: FromStr + 'static, <T as FromStr>::Err: Display,

fn many(self) -> ParseMany<Self>

where Self: Sized,

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

fn collect<C>(self) -> ParseCollect<Self, C, T>

where C: FromIterator<T>, Self: Sized,

Transform parser into a collection parser

fn some(self, message: &'static str) -> ParseSome<Self>

where Self: Sized + Parser<T>,

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

fn optional(self) -> ParseOptional<Self>

where Self: Sized + Parser<T>,

Turn a required argument into an optional one

fn count(self) -> ParseCount<Self, T>

where Self: Sized + Parser<T>,

Count how many times the inner parser succeeds, and return that number.

fn last(self) -> ParseLast<Self>

where Self: Sized + Parser<T>,

Apply the inner parser as many times as it succeeds, return the last value

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 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 the 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 the value isn’t present

fn hide(self) -> ParseHide<Self>

where Self: Sized + Parser<T>,

Ignore this parser during any sort of help generation

fn hide_usage(self) -> ParseUsage<Self>

where Self: Sized + Parser<T>,

Ignore this parser when generating a usage line

fn custom_usage<M>(self, usage: M) -> ParseUsage<Self>

where M: Into<Doc>, Self: Sized + Parser<T>,

Customize how this parser looks like in the usage line

fn group_help<M: Into<Doc>>(self, message: M) -> ParseGroupHelp<Self>

where Self: Sized + Parser<T>,

Attach a help message to a complex parser

fn with_group_help<F>(self, f: F) -> ParseWithGroupHelp<Self, F>

where Self: Sized + Parser<T>, F: Fn(MetaInfo<'_>) -> Doc,

Make a help message for a complex parser from its MetaInfo

fn to_options(self) -> OptionParser<T>

where Self: Sized + Parser<T> + 'static,

Transform Parser into OptionParser to get ready to run it

fn run(self) -> T

where Self: Sized + Parser<T> + 'static,

Finalize and run the parser

fn boxed(self) -> Box<dyn Parser<T>>

where Self: Sized + Parser<T> + 'static,

Create a boxed representation for a parser