Function bpaf::short

source · 
pub fn short(short: char) -> NamedArg
Expand description

Parse a flag/switch/argument that has a short name

You can chain multiple short, long and env for multiple names. You can specify multiple names of the same type, bpaf would use items past the first one as hidden aliases.

Combinatoric example 
#[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()
}

fn main() {
    println!("{:?}", options().run())
}
Derive example 
#[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,
}

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

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: app [-s] -a=ARG -u=USER

Available options:
-s, --switch
Switch with many names
-a, --argument=ARG
Argument with names
-u, --user=USER
Custom user name
[env:USER1: N/A]
-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
Error: -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
Error: -A is not expected in this context
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
Hide additional examples
examples/at_least_two.rs (line 8)
7
8
9
10
11
12
13
14
15
16

fn main() {
    let opt = short('f')
        .req_flag(())
        .many()
        .guard(|x| x.len() >= 2, "at least two arguments are required")
        .to_options()
        .run();

    println!("{:?}", opt);
}
examples/dd.rs (line 52)
51
52
53
54
55
56
57
58
59
60
61
62
63

pub fn options() -> OptionParser<Options> {
    let magic = short('m')
        .long("magic")
        .help("a usual switch still works")
        .switch();
    construct!(Options {
        magic,
        in_file(),
        out_file(),
        block_size(),
    })
    .to_options()
}
examples/env_logger.rs (line 29)
28
29
30
31
32
33
34
35
36
37

fn verbose() -> impl Parser<LevelFilter> {
    short('v')
        .help("Verbosity level, use multiple times for more verbosity")
        .req_flag(())
        .count()
        .map(|l| {
            use LevelFilter::*;
            [Off, Error, Warn, Info, Debug, Trace][l.max(5)]
        })
}
examples/derive.rs (line 29)
27
28
29
30
31
32
33
34
35
36

fn verbose() -> impl Parser<usize> {
    // number of occurrences of the v/verbose flag capped at 3
    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")
}
examples/flatten.rs (line 25)
24
25
26
27
28
29
30
31
32
33
34
35
36

fn main() {
    let verbose = short('v').help("switch verbosity on").switch();
    let user = short('u').help("daemon user").argument::<String>("USER");
    let group = short('g').help("daemon group").argument::<String>("GROUP");
    let daemon_opts = construct!(DaemonOpts { user, group });
    let opt = construct!(Cmdline {
        verbose,
        daemon_opts
    })
    .to_options()
    .run();
    println!("{:?}", opt);
}
Additional examples can be found in: