Struct Condition

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

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

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

where T: FromStr + Display,

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)

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

examples/dynamic_sub_command.rs (line 13)

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)

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(..)`."
            )
        }
    }
}

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:

• Condition::meta
• Condition::choice

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)

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

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:

• Condition::help
• Condition::choice

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)

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

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

where T: FromStr + Display,

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:

• Condition::help
• Condition::meta

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.");