Struct blarg::SubCommandParser

source · 
pub struct SubCommandParser<'a, B>
where
    B: Display,
{ /* private fields */ }
Expand description

The sub-command parser.

Implementations§

source§

impl<'a, B> SubCommandParser<'a, B>
where B: FromStr + Display + PartialEq,

source

pub fn command( self, variant: B, setup_fn: impl FnOnce(SubCommand<'a>) -> SubCommand<'a> ) -> SubCommandParser<'a, B>

Setup a sub-command.

Sub-commands may be added arbitrarily, as long as the correspond to the branching type B. If repeated for the same variant of B, only the final version will be created on the parser. The order of sub-commands does not affect the command parser semantics.

Example
use blarg::{CommandLineParser, Condition, Parameter, Scalar};

let mut value_a: u32 = 0;
let mut value_b: u32 = 0;
let mut sub_command: String = "".to_string();
let parser = CommandLineParser::new("program")
    .branch(Condition::new(Scalar::new(&mut sub_command), "sub_command"))
    .command("a".to_string(), |sub| sub.add(Parameter::argument(Scalar::new(&mut value_a), "value_a")))
    .command("b".to_string(), |sub| {
        sub.about("Description for the sub-command 'b'.")
            .add(Parameter::argument(Scalar::new(&mut value_b), "value_b"))
    })
    .build();

parser.parse_tokens(vec!["a", "1"].as_slice()).unwrap();

assert_eq!(&sub_command, "a");
assert_eq!(value_a, 1);
assert_eq!(value_b, 0);
Examples found in repository?
examples/foo_bar.rs (lines 74-84)
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96

fn main() {
    let mut verbose: bool = false;
    let mut foo_bar = FooBar::Foo;
    let mut initial: Option<u32> = None;
    let mut countries: HashSet<Country> = HashSet::default();
    let mut items: Vec<u32> = Vec::default();

    let ap = CommandLineParser::new("foo_bar");
    let parser = ap
        .add(
            Parameter::option(Switch::new(&mut verbose, true), "verbose", Some('v'))
                .help("Do dee doo."),
        )
        .branch(
            Condition::new(Scalar::new(&mut foo_bar), "foo_bar")
                .choice(FooBar::Foo, "123 abc let's make this one medium long.")
                .choice(FooBar::Bar, "456 def let's make this one multiple sentences.  We're really stretching here HAAAAAAAA HAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA!")
                .help("foo'y bar'y stuff")
                .meta(vec!["a", "b", "c"]),
        )
        .command(FooBar::Foo, |sub| {
            sub.add(Parameter::option(
                Optional::new(&mut initial),
                "initial",
                None,
            ))
            .add(
                Parameter::argument(Collection::new(&mut items, Nargs::Any), "item")
                    .help("The items."),
            )
        })
        .command(FooBar::Bar, |sub| {
            sub.add(Parameter::option(
                Collection::new(&mut countries, Nargs::AtLeastOne),
                "country",
                None,
            ))
        })
        .build();
    parser.parse();
    println!("Items: {items:?}");
    execute(verbose, foo_bar, initial, countries, items);
}
More examples
Hide additional examples
examples/dynamic_sub_command.rs (lines 24-26)
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
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

fn main() {
    let contains_dynamic_x = env::var("DYNAMIC_X").is_ok();
    let contains_dynamic_y = env::var("DYNAMIC_Y").is_ok();

    let mut sub: u32 = 0;
    let mut arg_0: bool = false;
    let mut arg_1: bool = false;
    let mut arg_2: bool = false;

    let mut condition = Condition::new(Scalar::new(&mut sub), "sub")
        // "0" is an undocumented sub-command, but will only available when environment contains `DYNAMIC_X`.
        // "1" is a regular sub-command.
        .choice(1, "the one sub-command");

    if contains_dynamic_y {
        // "2" is a sub-command that will only be available when the environment contains `DYNAMIC_Y`.
        condition = condition.choice(2, "the two sub-command");
    }

    let clp = CommandLineParser::new("sub-command");
    let mut clp = clp.branch(condition).command(1, |sub_command| {
        sub_command.add(Parameter::argument(Scalar::new(&mut arg_1), "arg"))
    });

    if contains_dynamic_x {
        clp = clp.command(0, |sub_command| {
            sub_command.add(Parameter::argument(Scalar::new(&mut arg_0), "arg"))
        });
    }

    if contains_dynamic_y {
        clp = clp.command(2, |sub_command| {
            sub_command.add(Parameter::argument(Scalar::new(&mut arg_2), "arg"))
        });
    }

    let parser = clp.build();

    parser.parse();

    println!("Used sub-command '{sub}'.");
    match sub {
        0 => {
            println!("arg_0: {arg_0}");
            assert!(!arg_1);
            assert!(!arg_2);
        }
        1 => {
            assert!(!arg_0);
            println!("arg_1: {arg_1}");
            assert!(!arg_2);
        }
        2 => {
            assert!(!arg_0);
            assert!(!arg_1);
            println!("arg_2: {arg_2}");
        }
        _ => {
            panic!("impossible - the parser will reject any variants not specified via `add(..)`.")
        }
    }
}
examples/demo_sub_command.rs (lines 23-32)
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
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

fn main() {
    let mut sub: u32 = 0;
    let mut arg_0: bool = false;
    let mut opt_0: bool = false;
    let mut arg_1: bool = false;

    let clp = CommandLineParser::new("sub-command");
    let parser = clp
        .about("Describe the base command line parser.  Let's make it a little long for fun.")
        .branch(
            Condition::new(Scalar::new(&mut sub), "sub")
                // "0" is an undocumented sub-command.
                // "1" is a regular sub-command.
                .choice(1, "the one sub-command")
                // "2" is a regular sub-command.
                .choice(2, "the two sub-command")
                // "3" is a false sub-command.
                // It will appear in the documentation, but only those specified via `command(..)` actually affect the program structure.
                .choice(3, "the three sub-command"),
        )
        .command(0, |sub_command| {
            sub_command
                .about("Describe the 0 sub-command parser.  Let's make it a little long for fun.")
                .add(Parameter::argument(Scalar::new(&mut arg_0), "arg"))
                .add(Parameter::option(
                    Switch::new(&mut opt_0, true),
                    "opt",
                    None,
                ))
        })
        .command(1, |sub_command| {
            sub_command
                .about("Describe the 1 sub-command parser.")
                .add(Parameter::argument(Scalar::new(&mut arg_1), "arg"))
        })
        // Specify an argument-less & option-less sub-command by leaving the 'sub' untouched.
        .command(2, |sub_command| sub_command)
        // Since we never add "3", it isn't a true sub-command.
        .build();

    parser.parse();

    println!("Used sub-command '{sub}'.");
    match sub {
        0 => {
            println!("arg_0: {arg_0}");
            println!("opt_0: {opt_0}");
            assert!(!arg_1);
        }
        1 => {
            assert!(!arg_0);
            assert!(!opt_0);
            println!("arg_1: {arg_1}");
        }
        2 => {
            assert!(!arg_0);
            assert!(!opt_0);
            assert!(!arg_1);
            println!("argument-less & option-less");
        }
        _ => {
            panic!(
                "impossible - the parser will reject any variants not specified via `command(..)`."
            )
        }
    }
}
source

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

Build the sub-command based command line parser as a Result. This finalizes the configuration and checks for errors (ex: a repeated parameter name).

source

pub fn build(self) -> GeneralParser<'a>

Build the sub-command based command line parser. This finalizes the configuration and checks for errors (ex: a repeated parameter name). If an error is encountered, exits with error code 1 (via std::process::exit).

Examples found in repository?
examples/foo_bar.rs (line 92)
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96

fn main() {
    let mut verbose: bool = false;
    let mut foo_bar = FooBar::Foo;
    let mut initial: Option<u32> = None;
    let mut countries: HashSet<Country> = HashSet::default();
    let mut items: Vec<u32> = Vec::default();

    let ap = CommandLineParser::new("foo_bar");
    let parser = ap
        .add(
            Parameter::option(Switch::new(&mut verbose, true), "verbose", Some('v'))
                .help("Do dee doo."),
        )
        .branch(
            Condition::new(Scalar::new(&mut foo_bar), "foo_bar")
                .choice(FooBar::Foo, "123 abc let's make this one medium long.")
                .choice(FooBar::Bar, "456 def let's make this one multiple sentences.  We're really stretching here HAAAAAAAA HAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA!")
                .help("foo'y bar'y stuff")
                .meta(vec!["a", "b", "c"]),
        )
        .command(FooBar::Foo, |sub| {
            sub.add(Parameter::option(
                Optional::new(&mut initial),
                "initial",
                None,
            ))
            .add(
                Parameter::argument(Collection::new(&mut items, Nargs::Any), "item")
                    .help("The items."),
            )
        })
        .command(FooBar::Bar, |sub| {
            sub.add(Parameter::option(
                Collection::new(&mut countries, Nargs::AtLeastOne),
                "country",
                None,
            ))
        })
        .build();
    parser.parse();
    println!("Items: {items:?}");
    execute(verbose, foo_bar, initial, countries, items);
}
More examples
Hide additional examples
examples/dynamic_sub_command.rs (line 40)
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
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

fn main() {
    let contains_dynamic_x = env::var("DYNAMIC_X").is_ok();
    let contains_dynamic_y = env::var("DYNAMIC_Y").is_ok();

    let mut sub: u32 = 0;
    let mut arg_0: bool = false;
    let mut arg_1: bool = false;
    let mut arg_2: bool = false;

    let mut condition = Condition::new(Scalar::new(&mut sub), "sub")
        // "0" is an undocumented sub-command, but will only available when environment contains `DYNAMIC_X`.
        // "1" is a regular sub-command.
        .choice(1, "the one sub-command");

    if contains_dynamic_y {
        // "2" is a sub-command that will only be available when the environment contains `DYNAMIC_Y`.
        condition = condition.choice(2, "the two sub-command");
    }

    let clp = CommandLineParser::new("sub-command");
    let mut clp = clp.branch(condition).command(1, |sub_command| {
        sub_command.add(Parameter::argument(Scalar::new(&mut arg_1), "arg"))
    });

    if contains_dynamic_x {
        clp = clp.command(0, |sub_command| {
            sub_command.add(Parameter::argument(Scalar::new(&mut arg_0), "arg"))
        });
    }

    if contains_dynamic_y {
        clp = clp.command(2, |sub_command| {
            sub_command.add(Parameter::argument(Scalar::new(&mut arg_2), "arg"))
        });
    }

    let parser = clp.build();

    parser.parse();

    println!("Used sub-command '{sub}'.");
    match sub {
        0 => {
            println!("arg_0: {arg_0}");
            assert!(!arg_1);
            assert!(!arg_2);
        }
        1 => {
            assert!(!arg_0);
            println!("arg_1: {arg_1}");
            assert!(!arg_2);
        }
        2 => {
            assert!(!arg_0);
            assert!(!arg_1);
            println!("arg_2: {arg_2}");
        }
        _ => {
            panic!("impossible - the parser will reject any variants not specified via `add(..)`.")
        }
    }
}
examples/demo_sub_command.rs (line 41)
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
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

fn main() {
    let mut sub: u32 = 0;
    let mut arg_0: bool = false;
    let mut opt_0: bool = false;
    let mut arg_1: bool = false;

    let clp = CommandLineParser::new("sub-command");
    let parser = clp
        .about("Describe the base command line parser.  Let's make it a little long for fun.")
        .branch(
            Condition::new(Scalar::new(&mut sub), "sub")
                // "0" is an undocumented sub-command.
                // "1" is a regular sub-command.
                .choice(1, "the one sub-command")
                // "2" is a regular sub-command.
                .choice(2, "the two sub-command")
                // "3" is a false sub-command.
                // It will appear in the documentation, but only those specified via `command(..)` actually affect the program structure.
                .choice(3, "the three sub-command"),
        )
        .command(0, |sub_command| {
            sub_command
                .about("Describe the 0 sub-command parser.  Let's make it a little long for fun.")
                .add(Parameter::argument(Scalar::new(&mut arg_0), "arg"))
                .add(Parameter::option(
                    Switch::new(&mut opt_0, true),
                    "opt",
                    None,
                ))
        })
        .command(1, |sub_command| {
            sub_command
                .about("Describe the 1 sub-command parser.")
                .add(Parameter::argument(Scalar::new(&mut arg_1), "arg"))
        })
        // Specify an argument-less & option-less sub-command by leaving the 'sub' untouched.
        .command(2, |sub_command| sub_command)
        // Since we never add "3", it isn't a true sub-command.
        .build();

    parser.parse();

    println!("Used sub-command '{sub}'.");
    match sub {
        0 => {
            println!("arg_0: {arg_0}");
            println!("opt_0: {opt_0}");
            assert!(!arg_1);
        }
        1 => {
            assert!(!arg_0);
            assert!(!opt_0);
            println!("arg_1: {arg_1}");
        }
        2 => {
            assert!(!arg_0);
            assert!(!opt_0);
            assert!(!arg_1);
            println!("argument-less & option-less");
        }
        _ => {
            panic!(
                "impossible - the parser will reject any variants not specified via `command(..)`."
            )
        }
    }
}

Auto Trait Implementations§

§

impl<'a, B> !RefUnwindSafe for SubCommandParser<'a, B>

§

impl<'a, B> !Send for SubCommandParser<'a, B>

§

impl<'a, B> !Sync for SubCommandParser<'a, B>

§

impl<'a, B> Unpin for SubCommandParser<'a, B>
where B: Unpin,

§

impl<'a, B> !UnwindSafe for SubCommandParser<'a, B>

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

§

impl<T> Instrument for T

§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided [Span], returning an Instrumented wrapper. Read more
§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

impl<T> WithSubscriber for T

§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a [WithDispatch] wrapper. Read more
§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a [WithDispatch] wrapper. Read more