Struct blarg::Condition

source · 
pub struct Condition<'a, T>(/* private fields */);
Expand description

The condition argument with which to branch the parser. Used with CommandLineParser::branch.

There is an implicit (non-compile time) requirement for the type T of a Condition:

The implementations of std::str::FromStr must invert std::fmt::Display.

This sounds scary and onerous, but most types will naturally adhere to this requirement. Consider rusts implementation for bool, where this is requirement holds:

assert_eq!(bool::from_str("true").unwrap().to_string(), "true");
assert_eq!(bool::from_str("false").unwrap().to_string(), "false");

However, not all types will necessarily adhere to this requirement. Observe the following example enum:

// Implement FromStr to be case-insensitive.
// Implement Display.
enum FooBar {
    Foo,
    Bar,
}
assert_eq!(FooBar::from_str("Foo").unwrap().to_string(), "Foo");
// FromStr does not invert Display!
assert_ne!(FooBar::from_str("foo").unwrap().to_string(), "foo");

Implementations§

source§

impl<'a, T> Condition<'a, T>
where T: FromStr + Display,

source

pub fn new(value: Scalar<'a, T>, name: &'static str) -> Condition<'a, T>

Create a condition parameter.

Example
use blarg::{Condition, Scalar};
use std::str::FromStr;

// Be sure to implement `std::str::FromStr` so that it inverts `std::fmt::Display`.
enum FooBar {
    Foo,
    Bar,
}

let mut foo_bar: FooBar = FooBar::Foo;
Condition::new(Scalar::new(&mut foo_bar), "foo_bar");
// .. parse()
match foo_bar {
    FooBar::Foo => println!("Do foo'y things."),
    FooBar::Bar => println!("Do bar'y things."),
};
Examples found in repository?
examples/foo_bar.rs (line 68)
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 13)
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 13)
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 help(self, description: impl Into<String>) -> Condition<'a, T>

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

A help message describes the condition in full sentence/paragraph format. We recommend allowing blarg to format this field (ex: it is not recommended to use line breaks '\n').

See also:

Example
use blarg::{Condition, Scalar};

let mut case: u32 = 0;
Condition::new(Scalar::new(&mut case), "case")
    .help("--this will get discarded--")
    .help("Choose the 'case' to execute.  Description may include multiple sentences.");
Examples found in repository?
examples/foo_bar.rs (line 71)
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);
}
source

pub fn meta(self, description: Vec<impl Into<String>>) -> Condition<'a, T>

Document the meta message(s) for this sub-command condition. If repeated, only the final message will apply to the sub-command condition.

Meta message(s) describe short format extra details about the condition. We recommend non-sentence information for this field.

See also:

Example
use blarg::{Condition, Scalar};

let mut case: u32 = 0;
Condition::new(Scalar::new(&mut case), "case")
    .meta(vec!["--this will get discarded--"])
    .meta(vec!["final extra", "details"]);
Examples found in repository?
examples/foo_bar.rs (line 72)
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);
}

Trait Implementations§

source§

impl<'a, T> Choices<T> for Condition<'a, T>
where T: FromStr + Display,

source§

fn choice(self, variant: T, description: impl Into<String>) -> Condition<'a, T>

Document a choice’s help message for the sub-command condition. If repeated for the same variant of T, only the final message will apply to the sub-command condition. Repeat using different variants to document multiple choices. Needn’t be exhaustive.

A choice help message describes the variant in full sentence/paragraph format. We recommend allowing blarg to format this field (ex: it is not recommended to use line breaks '\n').

Notice, the documented or un-documented choices do not affect the actual command parser semantics. To actually limit the command parser semantics, be sure to use an enum.

See also:

Example
use blarg::{prelude::*, Condition, Scalar};
use std::str::FromStr;

// Be sure to implement `std::str::FromStr` so that it inverts `std::fmt::Display`.
enum FooBar {
    Foo,
    Bar,
}

let mut foo_bar: FooBar = FooBar::Foo;
Condition::new(Scalar::new(&mut foo_bar), "foo_bar")
    .choice(FooBar::Foo, "--this will get discarded--")
    .choice(FooBar::Foo, "Do foo'y things.")
    .choice(FooBar::Bar, "Do bar'y things.  Description may include multiple sentences.");

Auto Trait Implementations§

§

impl<'a, T> !RefUnwindSafe for Condition<'a, T>

§

impl<'a, T> !Send for Condition<'a, T>

§

impl<'a, T> !Sync for Condition<'a, T>

§

impl<'a, T> Unpin for Condition<'a, T>

§

impl<'a, T> !UnwindSafe for Condition<'a, T>

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