Struct bpaf::parsers::ParseOptional

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

Apply inner parser, return a value in Some if items requested by it are all present, restore and return None if any are missing. Created with optional. Implements catch

Implementations

impl<P> ParseOptional<P>

pub fn catch(self) -> Self

Handle parse failures for optional parsers

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.

Those examples are very artificial and designed to show what difference catch makes, to actually parse arguments like in examples you should parse or construct enum with alternative branches

Combinatoric example

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

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

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

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

    let width_str = long("width").argument::<String>("PX").optional().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"), optional, catch)]
    /// Height of a rectangle
    height: Option<usize>,

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

    #[bpaf(long, argument("PX"), optional)]
    /// Width of a rectangle
    width: Option<usize>,

    #[bpaf(long("width"), argument("PX"), optional, hide)]
    width_str: Option<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 it produces four None values - all parsers succeed by the nature of them being optional

$ app
Options { height: None, height_str: None, width: None, width_str: None }

When executed with expected parameters fields with usize get their values

$ app --height 100 --width 100
Options { height: Some(100), height_str: None, width: Some(100), width_str: None }

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

$ app --height ten
Options { height: None, height_str: Some("ten"), width: None, width_str: None }

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

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

Examples found in repository

examples/numeric_prefix.rs (line 25)

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/derive_commands.rs (line 43)

fn feature_if() -> impl Parser<Option<String>> {
    // here feature starts as any string on a command line that does not start with a dash
    positional::<String>("FEATURE")
        // guard restricts it such that it can't be a valid version
        .guard(move |s| !is_version(s), "")
        // last two steps describe what to do with strings in this position but are actually
        // versions.
        // optional allows parser to represent an ignored value with None
        .optional()
        // and catch lets optional to handle parse failures coming from guard
        .catch()
}

fn version_if() -> impl Parser<Option<String>> {
    positional::<String>("VERSION")
        .guard(move |s| is_version(s), "")
        .optional()
        .catch()
}

Trait Implementations

impl<T, P> Parser<Option<T>> for ParseOptional<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