Struct ParseFallback

pub struct ParseFallback<P, T> { /* private fields */ }

Parser that substitutes missing value but not parse failure, created with fallback.

Implementations

impl<P, T: Display> ParseFallback<P, T>

pub fn display_fallback(self) -> Self

Show fallback value in --help using Display representation

Combinatoric example

#[derive(Debug, Clone)]
pub struct Options {
    jobs: usize,
}

pub fn options() -> OptionParser<Options> {
    let jobs = long("jobs")
        .help("Number of jobs")
        .argument("JOBS")
        .fallback(42)
        .display_fallback();
    construct!(Options { jobs }).to_options()
}

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

Derive example

#[derive(Debug, Clone, Bpaf)]
#[bpaf(options)]
#[allow(dead_code)]
pub struct Options {
    /// Number of jobs
    #[bpaf(argument("JOBS"), fallback(42), display_fallback)]
    jobs: usize,
}

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

Output

fallback changes parser to fallback to a default value used when argument is not specified

$ app
Options { jobs: 42 }

If value is present - fallback value is ignored

$ app --jobs 10
Options { jobs: 10 }

Parsing errors are preserved and presented to the user

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

With display_fallback, debug_fallback, and format_fallback, you can make it so the default value is visible in the --help output.

$ app --help

Usage: app [--jobs=JOBS]

Available options:

--jobs=JOBS

Number of jobs

[default: 42]

-h, --help

Prints help information

Examples found in repository

examples/dd.rs (line 34)

fn in_file() -> impl Parser<String> {
    tag::<String>("if=", "FILE", "read from FILE")
        .fallback(String::from("-"))
        .display_fallback()
}

fn out_file() -> impl Parser<String> {
    tag::<String>("of=", "FILE", "write to FILE")
        .fallback(String::from("-"))
        .display_fallback()
}

fn block_size() -> impl Parser<usize> {
    // it is possible to parse notation used by dd itself as well,
    // using usuze only for simplicity
    tag::<usize>("bs=", "SIZE", "read/write SIZE blocks at once")
        .fallback(512)
        .display_fallback()
}

examples/basic.rs (line 41)

fn opts() -> OptionParser<Out> {
    // A flag, true if used in the command line. Can be required, this one is optional

    let debug = short('d') // start with a short name
        .long("debug") // also add a long name
        .help("Activate debug mode") // and a help message to use
        .switch(); // turn this into a switch

    // number of occurrences of the v/verbose flag capped at 3 with an error here but you can also
    // use `max` inside `map`
    let verbose = short('v')
        .long("verbose")
        .help("Increase the verbosity\n You can specify it up to 3 times\n either as -v -v -v or as -vvv")
        .req_flag(())
        .many()
        .map(|xs| xs.len())
        .guard(|&x| x <= 3, "It doesn't get any more verbose than this");

    // an argument, parsed and with default value
    let speed = short('s')
        .long("speed")
        .help("Set speed")
        .argument::<f64>("SPEED") // you can specify a type to parse
        .fallback(42.0)
        .display_fallback();

    let output = short('o')
        .long("output")
        .help("output file")
        .argument::<PathBuf>("OUTPUT") // but it's optional when rustc can derive it
        .complete_shell(ShellComp::File { mask: None });

    // no magical name transmogrifications in combinatoric API,
    let nb_cars = short('n')
        .long("nb-cars")
        .help("Number of items to process")
        .argument::<u32>("N")
        .fallback(1)
        .display_fallback();

    // a parser that consumes one argument
    // you can build the inner parser in one go or as multiple steps giving each step a name
    // you can also add some static shell completion functionality
    let file_to_proces = short('f')
        .long("file")
        .help("File to process")
        .argument::<PathBuf>("FILE")
        .complete_shell(ShellComp::File { mask: Some("*.rs") });

    let files_to_process = file_to_proces.many();

    // packing things in a struct assumes parser for each field is in scope.
    construct!(Out {
        debug,
        verbose,
        speed,
        output,
        nb_cars,
        files_to_process
    })
    .to_options()
    .descr("This is a description")
}

impl<P, T: Debug> ParseFallback<P, T>

pub fn debug_fallback(self) -> Self

Show fallback value in --help using Debug representation

Combinatoric example

fn try_to_get_version() -> Result<usize, &'static str> {
    Ok(42)
}

#[derive(Debug, Clone)]
pub struct Options {
    version: usize,
}

pub fn options() -> OptionParser<Options> {
    let version = long("version")
        .help("Specify protocol version")
        .argument("VERS")
        .fallback_with(try_to_get_version)
        .debug_fallback();
    construct!(Options { version }).to_options()
}

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

Derive example

fn try_to_get_version() -> Result<usize, &'static str> {
    Ok(42)
}

#[derive(Debug, Clone, Bpaf)]
#[bpaf(options)]
pub struct Options {
    #[bpaf(argument("VERS"), fallback_with(try_to_get_version), debug_fallback)]
    /// Specify protocol version
    version: usize,
}

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

Output

fallback_with changes parser to fallback to a value that comes from a potentially failing computation when argument is not specified

$ app
Options { version: 42 }

If value is present - fallback value is ignored

$ app --version 10
Options { version: 10 }

Parsing errors are preserved and presented to the user

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

bpaf encases parsers with fallback value of some sort in usage with []

$ app --help

Usage: app [--version=VERS]

Available options:

--version=VERS

Specify protocol version

[default: 42]

-h, --help

Prints help information

Examples found in repository

examples/coreutils.rs (line 74)

    pub fn parse_binary() -> impl Parser<bool> {
        #[derive(Debug, Clone, Copy, Bpaf, Eq, PartialEq)]
        enum Mode {
            /// Use binary mode
            #[bpaf(short, long)]
            Binary,
            /// Use text mode
            #[bpaf(short, long)]
            Text,
        }
        mode()
            .last()
            .fallback(Mode::Text)
            .debug_fallback()
            .map(|mode| mode == Mode::Binary)
    }

impl<P, T> ParseFallback<P, T>

pub fn format_fallback( self, format: impl Fn(&T, &mut Formatter<'_>) -> Result, ) -> Self

Show fallback value in --help using the provided formatting function.

Combinatoric example

use std::{fmt::Display as _, path::PathBuf};
#[derive(Debug, Clone)]
pub struct Options {
    log_file: PathBuf,
}

pub fn options() -> OptionParser<Options> {
    let log_file = long("log-file")
        .help("Path to log file")
        .argument::<PathBuf>("FILE")
        .guard(
            |log_file| !log_file.is_dir(),
            "The log file can't be a directory",
        )
        .fallback(PathBuf::from("logfile.txt"))
        .format_fallback(|path, f| path.display().fmt(f));
    construct!(Options { log_file }).to_options()
}

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

Derive example

use std::{fmt::Display as _, path::PathBuf};
#[derive(Debug, Clone, Bpaf)]
#[bpaf(options)]
#[allow(dead_code)]
pub struct Options {
    /// Path to log file
    #[bpaf(
        argument("FILE"),
        guard(|log_file| !log_file.is_dir(), "The log file can't be a directory"),
        fallback(PathBuf::from("logfile.txt")),
        format_fallback(|path, f| path.display().fmt(f)),
    )]
    log_file: PathBuf,
}

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

Output

fallback changes parser to fallback to a default value used when argument is not specified

$ app
Options { log_file: "logfile.txt" }

If value is present - fallback value is ignored

$ app --log-file output.txt
Options { log_file: "output.txt" }

Parsing errors are preserved and presented to the user

$ app --log-file /
Error: /: The log file can't be a directory

With display_fallback, debug_fallback, and format_fallback, you can make it so the default value is visible in the --help output.

$ app --help

Usage: app [--log-file=FILE]

Available options:

--log-file=FILE

Path to log file

[default: logfile.txt]

-h, --help

Prints help information

Trait Implementations

impl<P, T> Parser<T> for ParseFallback<P, T>

where P: Parser<T>, T: Clone,

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