Struct bpaf::params::ParsePositional

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

Parse a positional item, created with positional

You can add extra information to positional parsers with help and strict on this struct.

Implementations

impl<T> ParsePositional<T>

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

Add a help message to a positional parser

Combinatoric usage

fn parse_name() -> impl Parser<String> {
    positional::<String>("NAME")
        .help("a flag that does a thing")
}

Derive usage

bpaf_derive converts doc comments into option help by following those rules:

1. It skips blank lines, if present.
2. It stops parsing after a double blank line.

#[derive(Debug, Clone, Bpaf)]
struct Options (
    /// This line is part of help message
    ///
    /// So is this one
    ///
    ///
    /// But this one isn't
    String,
);

See also NamedArg::help

Examples found in repository

examples/numeric_prefix.rs (line 12)

pub fn options() -> OptionParser<Options> {
    let prefix = positional::<usize>("PREFIX")
        .help("Optional numeric command prefix")
        .optional()
        .catch();
    let command = positional::<String>("COMMAND").help("Required command name");

    construct!(Options { prefix, command }).to_options()
}

examples/cat.rs (line 17)

fn main() {
    let file = positional::<OsString>("FILE")
        .help("File name to concatenate, with no FILE or when FILE is -, read standard input")
        .optional()
        .parse::<_, Box<dyn Read>, std::io::Error>(|path| {
            Ok(if let Some(path) = path {
                if path == "-" {
                    Box::new(stdin())
                } else {
                    Box::new(File::open(path)?)
                }
            } else {
                Box::new(stdin())
            })
        })
        .to_options()
        .descr("Concatenate a file to standard output")
        .run();

    let reader = BufReader::new(file);

    for line in reader.lines() {
        println!("{}", line.unwrap());
    }
}

pub fn strict(self) -> Self

Changes positional parser to be “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. If your app requires several different strict positional elements - it’s better to place this annotation only to the first one.

Example

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

$ app --help
Usage: [-p SPEC] [[--bin NAME] | [--example NAME]] [--release] [<BIN>] -- <CHILD_ARG>...
<skip>

Combinatoric usage

fn options() -> impl Parser<Vec<std::ffi::OsString>> {
    positional::<std::ffi::OsString>("OPTS")
        .strict()
        .many()
}

Derive usage

Not available at the moment

Trait Implementations

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

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

Returns a copy 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 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 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 hide_usage(self) -> ParseHideUsage<Self>where
    Self: Sized + Parser<T>,

Ignore this parser when generating usage line

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

Attach help message to a complex parser

fn complete<M, F>(self, op: F) -> ParseComp<Self, F>where
    M: Into<String>,
    F: Fn(&T) -> Vec<(M, Option<M>)>,
    Self: Sized + Parser<T>,

Dynamic shell completion

fn complete_shell(self, op: ShellComp) -> ParseCompShell<Self>where
    Self: Sized + Parser<T>,

Static shell completion

fn complete_style(self, style: CompleteDecor) -> ParseCompStyle<Self>where
    Self: Sized + Parser<T>,

Add extra annotations to completion information

fn adjacent(self) -> ParseAdjacent<Self>where
    Self: Sized + Parser<T>,

Automagically restrict the inner parser scope to accept adjacent values only

fn anywhere(self) -> ParseAnywhere<Self>where
    Self: Sized + Parser<T>,

Parse anywhere

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

Transform Parser into OptionParser to attach metadata and run