Expand description
A flag/switch/argument that has a short name
You can specify it multiple times, bpaf
would use items past the first of each short
and long
as
hidden aliases.
Combinatoric usage
#[derive(Debug, Clone)]
pub struct Options {
switch: bool,
arg: usize,
username: String,
}
pub fn options() -> OptionParser<Options> {
let switch = short('s') // first `short` creates a builder
.short('S') // second switch is a hidden alias
.long("switch") // visible long name
.long("also-switch") // hidden alias
.help("Switch with many names")
.switch(); // `switch` finalizes the builder
let arg = long("argument") // long is also a builder
.short('a')
.short('A')
.long("also-arg")
.help("Argument with names")
.argument::<usize>("ARG");
let username = long("user")
.short('u')
.env("USER1")
.help("Custom user name")
.argument::<String>("USER");
construct!(Options {
switch,
arg,
username
})
.to_options()
}
Derive usage
#[derive(Debug, Clone, Bpaf)]
#[bpaf(options)]
pub struct Options {
#[bpaf(short, long, short('S'), long("also-switch"))]
/// Switch with many names
switch: bool,
#[bpaf(short, long("argument"), short('A'), long("also-arg"))]
/// Argument with names
arg: usize,
#[bpaf(short, long("user"), env("USER1"), argument("USER"))]
/// Custom user name
username: String,
}
Examples
As usual switch is optional, arguments are required
% app -a 42 -u Bobert
Options { switch: false, arg: 42, username: "Bobert" }
Help displays only visible aliases (and a current value for env arguments)
% app --help
Usage: [-s] -a ARG -u USER
Available options:
-s, --switch Switch with many names
-a, --argument <ARG> Argument with names
-u, --user <USER> [env:USER1 = "pacak"]
Custom user name
-h, --help Prints help information
But you can still use hidden aliases, both short and long
% app --also-switch --also-arg 330 --user Bobert
Options { switch: true, arg: 330, username: "Bobert" }
And unless there’s many
or similar modifiers having multiple aliases doesn’t mean
you can specify them multiple times:
% app -A 42 -a 330 -u Bobert
-a is not expected in this context
Also hidden aliases are really hidden and only meant to do backward compatibility stuff, they won’t show up anywhere else in completions or error messages
% app -a 42 -A 330 -u Bobert
No such flag: `-A`, did you mean `-u`?
Examples found in repository?
examples/top_to_bottom.rs (line 34)
33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77
fn debug() -> impl Parser<bool> {
short('d')
.long("debug")
.help("Activate debug mode")
.switch()
}
// number of occurrences of the v/verbose flag capped at 3
fn verbose() -> impl Parser<usize> {
short('v')
.long("verbose")
.help("Increase the verbosity\nYou can specify it up to 3 times\neither 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
fn speed() -> impl Parser<f64> {
short('s')
.long("speed")
.help("Set speed")
.argument::<f64>("SPEED")
.fallback(42.0)
}
fn output() -> impl Parser<PathBuf> {
short('o')
.long("output")
.help("output file")
.argument::<PathBuf>("OUTPUT")
}
// no magical name transmogrifications.
fn nb_cars() -> impl Parser<u32> {
short('n').long("nb-cars").argument::<u32>("N")
}
fn files_to_process() -> impl Parser<Vec<PathBuf>> {
short('f')
.long("file")
.help("File to process")
.argument::<PathBuf>("FILE")
.many()
}
More examples
src/info.rs (line 703)
702 703 704 705 706 707 708 709 710 711 712 713 714
fn help() -> impl Parser<ExtraParams> {
short('h')
.long("help")
.help("Prints help information")
.req_flag(ExtraParams::Help)
}
#[inline(never)]
fn ver(version: &'static str) -> impl Parser<ExtraParams> {
short('V')
.long("version")
.help("Prints version information")
.req_flag(ExtraParams::Version(version))
}
examples/env_logger.rs (line 29)
28 29 30 31 32 33 34 35 36 37 38 39
fn verbose() -> impl Parser<LevelFilter> {
short('v')
.help("Verbosity level, use multiple times for more verbosity")
.req_flag(())
.many()
.map(|v| {
use LevelFilter::*;
*[Off, Error, Warn, Info, Debug, Trace]
.get(v.len())
.unwrap_or(&Trace)
})
}
examples/customize_help.rs (line 7)
6 7 8 9 10 11 12 13 14 15 16 17 18
fn main() {
let opt = short('d')
.help("Release the dragon")
.switch()
.to_options()
.descr("I am a program and I do things")
.header("Sometimes they even work.")
.footer("Beware `-d`, dragons be here")
.usage("You can call it with following flags: {usage}")
.run();
println!("{:?}", opt);
}