pub struct Parameter<'a, T>(/* private fields */);
Expand description
An argument/option for the command parser.
Used with CommandLineParser::add
and SubCommand::add
.
Implementations§
source§impl<'a, T> Parameter<'a, T>
impl<'a, T> Parameter<'a, T>
sourcepub fn option(
field: impl GenericCapturable<'a, T> + CliOption + 'a,
name: impl Into<String>,
short: Option<char>
) -> Parameter<'a, T>
pub fn option( field: impl GenericCapturable<'a, T> + CliOption + 'a, name: impl Into<String>, short: Option<char> ) -> Parameter<'a, T>
Create an option parameter.
Example
use blarg::{Parameter, Switch};
let mut verbose: bool = false;
Parameter::option(Switch::new(&mut verbose, true), "verbose", Some('v'));
Examples found in repository?
2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
fn main() {
let mut verbose: bool = false;
let mut value: u32 = 0;
let ap = CommandLineParser::new("example");
let parser = ap
.add(Parameter::option(
Switch::new(&mut verbose, true),
"verbose",
Some('v'),
))
.add(Parameter::argument(Scalar::new(&mut value), "value").meta(vec!["type: u32"]))
.build();
parser.parse();
println!("value: {value}, verbose: {verbose}");
}
More examples
30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50
fn parse_tokens(parse_fn: impl FnOnce(GeneralParser) -> Result<(), i32>) -> Params {
let mut params = Params::init();
let clp = CommandLineParser::new("organization");
let parser = clp
.add(Parameter::option(
Switch::new(&mut params.verbose, true),
"verbose",
Some('v'),
))
.add(Parameter::argument(
Collection::new(&mut params.items, Nargs::AtLeastOne),
"item",
))
.build();
// The parse_fn signature is a `Result`.
// However, since `GeneralParser::parse` does not return an error (it uses `std::process::exit` under the hood), the `Err` case is only reached via test.
parse_fn(parser).expect("test-reachable-only");
params
}
53 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
fn main() {
let mut _verbose: bool = false;
let mut operand: Operand = Operand::Add;
let mut initial: Option<u32> = None;
let mut _countries: HashSet<Country> = HashSet::default();
let mut items: Vec<u32> = Vec::default();
let ap = CommandLineParser::new("reducer");
let parser = ap
.add(
Parameter::option(Switch::new(&mut _verbose, true), "verbose", Some('v'))
.help("Do dee doo. We're really stretching here HAAAAAAAA HAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA!"),
)
.add(
Parameter::option(Scalar::new(&mut operand), "operand", Some('o'))
.help("moot")
.choice(Operand::Add, "+")
.choice(Operand::Multiply, "*"),
)
.add(Parameter::option(Optional::new(&mut initial), "initial", None)
.meta(vec!["testing a really long meta.. abcdefghijklmnopqrstuvwxyz"])
)
.add(Parameter::option(Collection::new(&mut _countries, Nargs::AtLeastOne), "country", None))
.add(
Parameter::argument(Collection::new(&mut items, Nargs::AtLeastOne), "item")
.help("The items."),
)
.build();
parser.parse();
println!("Items: {items:?}");
execute(_verbose, operand, initial, _countries, items);
}
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);
}
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 argument(
field: impl GenericCapturable<'a, T> + CliArgument + 'a,
name: impl Into<String>
) -> Parameter<'a, T>
pub fn argument( field: impl GenericCapturable<'a, T> + CliArgument + 'a, name: impl Into<String> ) -> Parameter<'a, T>
Create an argument parameter.
Example
use blarg::{Parameter, Scalar};
let mut verbose: bool = false;
Parameter::argument(Scalar::new(&mut verbose), "verbose");
Examples found in repository?
3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
fn main() {
let mut items: Vec<u32> = Vec::default();
let clp = CommandLineParser::new("summer");
let parser = clp
.add(
Parameter::argument(Collection::new(&mut items, Nargs::AtLeastOne), "item")
.help("The items to sum."),
)
.build();
parser.parse();
let sum: u32 = items.iter().sum();
println!("Sum: {sum}");
}
More examples
2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
fn main() {
let mut verbose: bool = false;
let mut value: u32 = 0;
let ap = CommandLineParser::new("example");
let parser = ap
.add(Parameter::option(
Switch::new(&mut verbose, true),
"verbose",
Some('v'),
))
.add(Parameter::argument(Scalar::new(&mut value), "value").meta(vec!["type: u32"]))
.build();
parser.parse();
println!("value: {value}, verbose: {verbose}");
}
30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50
fn parse_tokens(parse_fn: impl FnOnce(GeneralParser) -> Result<(), i32>) -> Params {
let mut params = Params::init();
let clp = CommandLineParser::new("organization");
let parser = clp
.add(Parameter::option(
Switch::new(&mut params.verbose, true),
"verbose",
Some('v'),
))
.add(Parameter::argument(
Collection::new(&mut params.items, Nargs::AtLeastOne),
"item",
))
.build();
// The parse_fn signature is a `Result`.
// However, since `GeneralParser::parse` does not return an error (it uses `std::process::exit` under the hood), the `Err` case is only reached via test.
parse_fn(parser).expect("test-reachable-only");
params
}
53 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
fn main() {
let mut _verbose: bool = false;
let mut operand: Operand = Operand::Add;
let mut initial: Option<u32> = None;
let mut _countries: HashSet<Country> = HashSet::default();
let mut items: Vec<u32> = Vec::default();
let ap = CommandLineParser::new("reducer");
let parser = ap
.add(
Parameter::option(Switch::new(&mut _verbose, true), "verbose", Some('v'))
.help("Do dee doo. We're really stretching here HAAAAAAAA HAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA!"),
)
.add(
Parameter::option(Scalar::new(&mut operand), "operand", Some('o'))
.help("moot")
.choice(Operand::Add, "+")
.choice(Operand::Multiply, "*"),
)
.add(Parameter::option(Optional::new(&mut initial), "initial", None)
.meta(vec!["testing a really long meta.. abcdefghijklmnopqrstuvwxyz"])
)
.add(Parameter::option(Collection::new(&mut _countries, Nargs::AtLeastOne), "country", None))
.add(
Parameter::argument(Collection::new(&mut items, Nargs::AtLeastOne), "item")
.help("The items."),
)
.build();
parser.parse();
println!("Items: {items:?}");
execute(_verbose, operand, initial, _countries, items);
}
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);
}
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(..)`.")
}
}
}
sourcepub fn help(self, description: impl Into<String>) -> Parameter<'a, T>
pub fn help(self, description: impl Into<String>) -> Parameter<'a, T>
Document the help message for this parameter. If repeated, only the final message will apply to the parameter.
A help message describes the parameter 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::{Parameter, Scalar};
let mut verbose: bool = false;
Parameter::argument(Scalar::new(&mut verbose), "verbose")
.help("--this will get discarded--")
.help("Make the program output verbose. Description may include multiple sentences.");
Examples found in repository?
3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
fn main() {
let mut items: Vec<u32> = Vec::default();
let clp = CommandLineParser::new("summer");
let parser = clp
.add(
Parameter::argument(Collection::new(&mut items, Nargs::AtLeastOne), "item")
.help("The items to sum."),
)
.build();
parser.parse();
let sum: u32 = items.iter().sum();
println!("Sum: {sum}");
}
More examples
53 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
fn main() {
let mut _verbose: bool = false;
let mut operand: Operand = Operand::Add;
let mut initial: Option<u32> = None;
let mut _countries: HashSet<Country> = HashSet::default();
let mut items: Vec<u32> = Vec::default();
let ap = CommandLineParser::new("reducer");
let parser = ap
.add(
Parameter::option(Switch::new(&mut _verbose, true), "verbose", Some('v'))
.help("Do dee doo. We're really stretching here HAAAAAAAA HAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA!"),
)
.add(
Parameter::option(Scalar::new(&mut operand), "operand", Some('o'))
.help("moot")
.choice(Operand::Add, "+")
.choice(Operand::Multiply, "*"),
)
.add(Parameter::option(Optional::new(&mut initial), "initial", None)
.meta(vec!["testing a really long meta.. abcdefghijklmnopqrstuvwxyz"])
)
.add(Parameter::option(Collection::new(&mut _countries, Nargs::AtLeastOne), "country", None))
.add(
Parameter::argument(Collection::new(&mut items, Nargs::AtLeastOne), "item")
.help("The items."),
)
.build();
parser.parse();
println!("Items: {items:?}");
execute(_verbose, operand, initial, _countries, items);
}
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);
}
sourcepub fn meta(self, descriptions: Vec<impl Into<String>>) -> Parameter<'a, T>
pub fn meta(self, descriptions: Vec<impl Into<String>>) -> Parameter<'a, T>
Document the meta message(s) for this parameter. If repeated, only the final message will apply to the parameter.
Meta message(s) describe short format extra details about the parameter. We recommend non-sentence information for this field.
See also:
Example
use blarg::{Parameter, Scalar};
let mut verbose: bool = false;
Parameter::argument(Scalar::new(&mut verbose), "verbose")
.meta(vec!["--this will be discarded--"])
.meta(vec!["final extra", "details"]);
Examples found in repository?
2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
fn main() {
let mut verbose: bool = false;
let mut value: u32 = 0;
let ap = CommandLineParser::new("example");
let parser = ap
.add(Parameter::option(
Switch::new(&mut verbose, true),
"verbose",
Some('v'),
))
.add(Parameter::argument(Scalar::new(&mut value), "value").meta(vec!["type: u32"]))
.build();
parser.parse();
println!("value: {value}, verbose: {verbose}");
}
More examples
53 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
fn main() {
let mut _verbose: bool = false;
let mut operand: Operand = Operand::Add;
let mut initial: Option<u32> = None;
let mut _countries: HashSet<Country> = HashSet::default();
let mut items: Vec<u32> = Vec::default();
let ap = CommandLineParser::new("reducer");
let parser = ap
.add(
Parameter::option(Switch::new(&mut _verbose, true), "verbose", Some('v'))
.help("Do dee doo. We're really stretching here HAAAAAAAA HAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA!"),
)
.add(
Parameter::option(Scalar::new(&mut operand), "operand", Some('o'))
.help("moot")
.choice(Operand::Add, "+")
.choice(Operand::Multiply, "*"),
)
.add(Parameter::option(Optional::new(&mut initial), "initial", None)
.meta(vec!["testing a really long meta.. abcdefghijklmnopqrstuvwxyz"])
)
.add(Parameter::option(Collection::new(&mut _countries, Nargs::AtLeastOne), "country", None))
.add(
Parameter::argument(Collection::new(&mut items, Nargs::AtLeastOne), "item")
.help("The items."),
)
.build();
parser.parse();
println!("Items: {items:?}");
execute(_verbose, operand, initial, _countries, items);
}
Trait Implementations§
source§impl<'a, T> Choices<T> for Parameter<'a, T>where
T: Display,
impl<'a, T> Choices<T> for Parameter<'a, T>where
T: Display,
source§fn choice(self, variant: T, description: impl Into<String>) -> Parameter<'a, T>
fn choice(self, variant: T, description: impl Into<String>) -> Parameter<'a, T>
Document a choice’s help message for this parameter.
If repeated for the same variant
of T
, only the final message will apply to the parameter.
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::*, Parameter, Scalar};
use std::str::FromStr;
let mut door: u32 = 0;
Parameter::argument(Scalar::new(&mut door), "door")
.choice(1, "--this will get discarded--")
.choice(1, "Enter door #1.")
.choice(2, "Enter door #2. Description may include multiple sentences.");