Struct SubCommand

Source

pub struct SubCommand<'a> { /* private fields */ }

Expand description

A sub-command line parser.

Used with SubCommandParser::command.

Implementations§

Source §

impl<'a> SubCommand<'a>

Source

pub fn test_dummy() -> SubCommand<'a>

Available using ‘unit_test’ crate feature only.

Build a SubCommand for use in testing.

§Example

use blarg::{Parameter, Scalar, SubCommand};

// Function under test.
// We want to make sure the setup_fn is wired up correctly.
pub fn setup_fn<'a>(value: &'a mut u32) -> impl FnOnce(SubCommand<'a>) -> SubCommand<'a> {
    |sub| sub.add(Parameter::argument(Scalar::new(value), "value"))
}

let mut x: u32 = 1;
let parser = setup_fn(&mut x)(SubCommand::test_dummy()).build_parser().unwrap();
parser.parse_tokens(vec!["2"].as_slice()).unwrap();
assert_eq!(x, 2);

Source

pub fn build_parser(self) -> Result<GeneralParser<'a>, ConfigError>

Available using ‘unit_test’ crate feature only.

Build a GeneralParser for testing. See SubCommand::test_dummy for an example.

Source

pub fn about(self, description: impl Into<String>) -> SubCommand<'a>

Document the about message for this sub-command. If repeated, only the final help message will apply.

An about message documents the sub-command in full sentence/paragraph format. We recommend allowing blarg to format this field (ex: it is not recommended to use line breaks '\n').

See SubCommandParser::command for usage.

Examples found in repository ?

examples/demo_sub_command.rs (line 25)

3fn main() {
4    let mut sub: u32 = 0;
5    let mut arg_0: bool = false;
6    let mut opt_0: bool = false;
7    let mut arg_1: bool = false;
8
9    let clp = CommandLineParser::new("sub-command");
10    let parser = clp
11        .about("Describe the base command line parser.  Let's make it a little long for fun.")
12        .branch(
13            Condition::new(Scalar::new(&mut sub), "sub")
14                // "0" is an undocumented sub-command.
15                // "1" is a regular sub-command.
16                .choice(1, "the one sub-command")
17                // "2" is a regular sub-command.
18                .choice(2, "the two sub-command")
19                // "3" is a false sub-command.
20                // It will appear in the documentation, but only those specified via `command(..)` actually affect the program structure.
21                .choice(3, "the three sub-command"),
22        )
23        .command(0, |sub_command| {
24            sub_command
25                .about("Describe the 0 sub-command parser.  Let's make it a little long for fun.")
26                .add(Parameter::argument(Scalar::new(&mut arg_0), "arg"))
27                .add(Parameter::option(
28                    Switch::new(&mut opt_0, true),
29                    "opt",
30                    None,
31                ))
32        })
33        .command(1, |sub_command| {
34            sub_command
35                .about("Describe the 1 sub-command parser.")
36                .add(Parameter::argument(Scalar::new(&mut arg_1), "arg"))
37        })
38        // Specify an argument-less & option-less sub-command by leaving the 'sub' untouched.
39        .command(2, |sub_command| sub_command)
40        // Since we never add "3", it isn't a true sub-command.
41        .build();
42
43    parser.parse();
44
45    println!("Used sub-command '{sub}'.");
46    match sub {
47        0 => {
48            println!("arg_0: {arg_0}");
49            println!("opt_0: {opt_0}");
50            assert!(!arg_1);
51        }
52        1 => {
53            assert!(!arg_0);
54            assert!(!opt_0);
55            println!("arg_1: {arg_1}");
56        }
57        2 => {
58            assert!(!arg_0);
59            assert!(!opt_0);
60            assert!(!arg_1);
61            println!("argument-less & option-less");
62        }
63        _ => {
64            panic!(
65                "impossible - the parser will reject any variants not specified via `command(..)`."
66            )
67        }
68    }
69}

Source

pub fn add<T>(self, parameter: Parameter<'a, T>) -> SubCommand<'a>

Add an argument/option to the sub-command.

The order of argument parameters corresponds to their positional order during parsing. The order of option parameters does not affect the sub-command parser semantics.

See SubCommandParser::command for usage.

Examples found in repository ?

examples/foo_bar.rs (lines 75-79)

54fn main() {
55    let mut verbose: bool = false;
56    let mut foo_bar = FooBar::Foo;
57    let mut initial: Option<u32> = None;
58    let mut countries: HashSet<Country> = HashSet::default();
59    let mut items: Vec<u32> = Vec::default();
60
61    let ap = CommandLineParser::new("foo_bar");
62    let parser = ap
63        .add(
64            Parameter::option(Switch::new(&mut verbose, true), "verbose", Some('v'))
65                .help("Do dee doo."),
66        )
67        .branch(
68            Condition::new(Scalar::new(&mut foo_bar), "foo_bar")
69                .choice(FooBar::Foo, "123 abc let's make this one medium long.")
70                .choice(FooBar::Bar, "456 def let's make this one multiple sentences.  We're really stretching here HAAAAAAAA HAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA!")
71                .help("foo'y bar'y stuff")
72                .meta(vec!["a", "b", "c"]),
73        )
74        .command(FooBar::Foo, |sub| {
75            sub.add(Parameter::option(
76                Optional::new(&mut initial),
77                "initial",
78                None,
79            ))
80            .add(
81                Parameter::argument(Collection::new(&mut items, Nargs::Any), "item")
82                    .help("The items."),
83            )
84        })
85        .command(FooBar::Bar, |sub| {
86            sub.add(Parameter::option(
87                Collection::new(&mut countries, Nargs::AtLeastOne),
88                "country",
89                None,
90            ))
91        })
92        .build();
93    parser.parse();
94    println!("Items: {items:?}");
95    execute(verbose, foo_bar, initial, countries, items);
96}

More examples

Hide additional examples

examples/dynamic_sub_command.rs (line 25)

4fn main() {
5    let contains_dynamic_x = env::var("DYNAMIC_X").is_ok();
6    let contains_dynamic_y = env::var("DYNAMIC_Y").is_ok();
7
8    let mut sub: u32 = 0;
9    let mut arg_0: bool = false;
10    let mut arg_1: bool = false;
11    let mut arg_2: bool = false;
12
13    let mut condition = Condition::new(Scalar::new(&mut sub), "sub")
14        // "0" is an undocumented sub-command, but will only available when environment contains `DYNAMIC_X`.
15        // "1" is a regular sub-command.
16        .choice(1, "the one sub-command");
17
18    if contains_dynamic_y {
19        // "2" is a sub-command that will only be available when the environment contains `DYNAMIC_Y`.
20        condition = condition.choice(2, "the two sub-command");
21    }
22
23    let clp = CommandLineParser::new("sub-command");
24    let mut clp = clp.branch(condition).command(1, |sub_command| {
25        sub_command.add(Parameter::argument(Scalar::new(&mut arg_1), "arg"))
26    });
27
28    if contains_dynamic_x {
29        clp = clp.command(0, |sub_command| {
30            sub_command.add(Parameter::argument(Scalar::new(&mut arg_0), "arg"))
31        });
32    }
33
34    if contains_dynamic_y {
35        clp = clp.command(2, |sub_command| {
36            sub_command.add(Parameter::argument(Scalar::new(&mut arg_2), "arg"))
37        });
38    }
39
40    let parser = clp.build();
41
42    parser.parse();
43
44    println!("Used sub-command '{sub}'.");
45    match sub {
46        0 => {
47            println!("arg_0: {arg_0}");
48            assert!(!arg_1);
49            assert!(!arg_2);
50        }
51        1 => {
52            assert!(!arg_0);
53            println!("arg_1: {arg_1}");
54            assert!(!arg_2);
55        }
56        2 => {
57            assert!(!arg_0);
58            assert!(!arg_1);
59            println!("arg_2: {arg_2}");
60        }
61        _ => {
62            panic!("impossible - the parser will reject any variants not specified via `add(..)`.")
63        }
64    }
65}

examples/demo_sub_command.rs (line 26)

3fn main() {
4    let mut sub: u32 = 0;
5    let mut arg_0: bool = false;
6    let mut opt_0: bool = false;
7    let mut arg_1: bool = false;
8
9    let clp = CommandLineParser::new("sub-command");
10    let parser = clp
11        .about("Describe the base command line parser.  Let's make it a little long for fun.")
12        .branch(
13            Condition::new(Scalar::new(&mut sub), "sub")
14                // "0" is an undocumented sub-command.
15                // "1" is a regular sub-command.
16                .choice(1, "the one sub-command")
17                // "2" is a regular sub-command.
18                .choice(2, "the two sub-command")
19                // "3" is a false sub-command.
20                // It will appear in the documentation, but only those specified via `command(..)` actually affect the program structure.
21                .choice(3, "the three sub-command"),
22        )
23        .command(0, |sub_command| {
24            sub_command
25                .about("Describe the 0 sub-command parser.  Let's make it a little long for fun.")
26                .add(Parameter::argument(Scalar::new(&mut arg_0), "arg"))
27                .add(Parameter::option(
28                    Switch::new(&mut opt_0, true),
29                    "opt",
30                    None,
31                ))
32        })
33        .command(1, |sub_command| {
34            sub_command
35                .about("Describe the 1 sub-command parser.")
36                .add(Parameter::argument(Scalar::new(&mut arg_1), "arg"))
37        })
38        // Specify an argument-less & option-less sub-command by leaving the 'sub' untouched.
39        .command(2, |sub_command| sub_command)
40        // Since we never add "3", it isn't a true sub-command.
41        .build();
42
43    parser.parse();
44
45    println!("Used sub-command '{sub}'.");
46    match sub {
47        0 => {
48            println!("arg_0: {arg_0}");
49            println!("opt_0: {opt_0}");
50            assert!(!arg_1);
51        }
52        1 => {
53            assert!(!arg_0);
54            assert!(!opt_0);
55            println!("arg_1: {arg_1}");
56        }
57        2 => {
58            assert!(!arg_0);
59            assert!(!opt_0);
60            assert!(!arg_1);
61            println!("argument-less & option-less");
62        }
63        _ => {
64            panic!(
65                "impossible - the parser will reject any variants not specified via `command(..)`."
66            )
67        }
68    }
69}