Struct ParseSome

pub struct ParseSome<P> { /* private fields */ }

Apply inner parser several times and collect results into Vec, created with some, requires for at least one item to be available to succeed. Implements catch

Implementations

impl<P> ParseSome<P>

pub fn catch(self) -> Self

Handle parse failures

Can be useful to decide to skip parsing of some items on a command line When parser succeeds - catch version would return a value as usual if it fails - catch would restore all the consumed values and return None.

There’s several structures that implement this attribute: ParseOptional, ParseMany and ParseSome, behavior should be identical for all of them.

Combinatoric example

#[derive(Debug, Clone)]
pub struct Options {
    height: Vec<usize>,
    height_str: Vec<String>,
    width: Vec<usize>,
    width_str: Vec<String>,
}

pub fn options() -> OptionParser<Options> {
    // contains catch
    let height = long("height")
        .help("Height of a rectangle")
        .argument::<usize>("PX")
        .some("You must specify some heights")
        .catch();

    let height_str = long("height").argument::<String>("PX").many().hide();

    // contains no catch
    let width = long("width")
        .help("Width of a rectangle")
        .argument::<usize>("PX")
        .some("You must specify some widths");

    let width_str = long("width").argument::<String>("PX").many().hide();

    construct!(Options {
        height,
        height_str,
        width,
        width_str
    })
    .to_options()
}

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

Derive example

#[derive(Debug, Clone, Bpaf)]
#[bpaf(options)]
pub struct Options {
    #[bpaf(long, argument("PX"), some("You must specify some heights"), catch)]
    /// Height of a rectangle
    height: Vec<usize>,

    #[bpaf(long("height"), argument("PX"), many, hide)]
    height_str: Vec<String>,

    #[bpaf(long, argument("PX"), some("You must specify some widths"))]
    /// Width of a rectangle
    width: Vec<usize>,

    #[bpaf(long("width"), argument("PX"), many, hide)]
    width_str: Vec<String>,
}

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

Output

Despite parser producing a funky value - help looks like you would expect from a parser that takes two values

$ app --help

Usage: app --height=PX... --width=PX...

Available options:

--height=PX

Height of a rectangle

--width=PX

Width of a rectangle

-h, --help

Prints help information

When executed with no parameters parser fails because some requires you to specify at least one matching parameter

$ app
Error: You must specify some heights

When executed with expected parameters fields with usize get their values

$ app --height 100 --width 100 --height 12 --width 44
Options { height: [100, 12], height_str: [], width: [100, 44], width_str: [] }

With incorrect value for --height parameter inner part of height parser fails, some combined with catch handles this failure and produces [] without consuming value from the command line. Parser height_str runs next and consumes the value as a string

$ app --height 10 --height twenty --width 33
Options { height: [10], height_str: ["twenty"], width: [33], width_str: [] }

In case of wrong --width - parser width fails, parser for some sees this as a “value is present but not correct” and propagates the error outside, execution never reaches width_str parser

$ app --height 10 --width 33 --width ten
Error: couldn't parse ten: invalid digit found in string

Trait Implementations

impl<T, P> Parser<Vec<T>> for ParseSome<P>

where P: Parser<T>,

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 complete<M, F>(self, op: F) -> ParseComp<Self, F>

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

Available on crate feature autocomplete only.

Dynamic shell completion

fn complete_shell(self, op: ShellComp) -> ParseCompShell<Self>

where Self: Sized + Parser<T>,

Available on crate feature autocomplete only.

Static shell completion

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