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
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);
}