Struct blarg::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>
impl<'a> SubCommand<'a>
sourcepub fn test_dummy() -> SubCommand<'a>
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);
sourcepub fn build_parser(self) -> Result<GeneralParser<'a>, ConfigError>
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.
sourcepub fn about(self, description: impl Into<String>) -> SubCommand<'a>
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?
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(..)`."
)
}
}
}
sourcepub fn add<T>(self, parameter: Parameter<'a, T>) -> SubCommand<'a>
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?
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
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(..)`.")
}
}
}
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(..)`."
)
}
}
}