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: FromStr + Display> Condition<'a, T>

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

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

pub fn help(self, description: impl Into<String>) -> Self

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

pub fn meta(self, description: Vec<impl Into<String>>) -> Self

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

Trait Implementations

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

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

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