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?
2fn main() {
3 let mut verbose: bool = false;
4 let mut value: u32 = 0;
5 let ap = CommandLineParser::new("example");
6 let parser = ap
7 .add(Parameter::option(
8 Switch::new(&mut verbose, true),
9 "verbose",
10 Some('v'),
11 ))
12 .add(Parameter::argument(Scalar::new(&mut value), "value").meta(vec!["type: u32"]))
13 .build();
14 parser.parse();
15 println!("value: {value}, verbose: {verbose}");
16}
More examples
30fn parse_tokens(parse_fn: impl FnOnce(GeneralParser) -> Result<(), i32>) -> Params {
31 let mut params = Params::init();
32
33 let clp = CommandLineParser::new("organization");
34 let parser = clp
35 .add(Parameter::option(
36 Switch::new(&mut params.verbose, true),
37 "verbose",
38 Some('v'),
39 ))
40 .add(Parameter::argument(
41 Collection::new(&mut params.items, Nargs::AtLeastOne),
42 "item",
43 ))
44 .build();
45
46 // The parse_fn signature is a `Result`.
47 // 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.
48 parse_fn(parser).expect("test-reachable-only");
49 params
50}
53fn main() {
54 let mut _verbose: bool = false;
55 let mut operand: Operand = Operand::Add;
56 let mut initial: Option<u32> = None;
57 let mut _countries: HashSet<Country> = HashSet::default();
58 let mut items: Vec<u32> = Vec::default();
59
60 let ap = CommandLineParser::new("reducer");
61 let parser = ap
62 .add(
63 Parameter::option(Switch::new(&mut _verbose, true), "verbose", Some('v'))
64 .help("Do dee doo. We're really stretching here HAAAAAAAA HAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA!"),
65 )
66 .add(
67 Parameter::option(Scalar::new(&mut operand), "operand", Some('o'))
68 .help("moot")
69 .choice(Operand::Add, "+")
70 .choice(Operand::Multiply, "*"),
71 )
72 .add(Parameter::option(Optional::new(&mut initial), "initial", None)
73 .meta(vec!["testing a really long meta.. abcdefghijklmnopqrstuvwxyz"])
74 )
75 .add(Parameter::option(Collection::new(&mut _countries, Nargs::AtLeastOne), "country", None))
76 .add(
77 Parameter::argument(Collection::new(&mut items, Nargs::AtLeastOne), "item")
78 .help("The items."),
79 )
80 .build();
81 parser.parse();
82 println!("Items: {items:?}");
83 execute(_verbose, operand, initial, _countries, items);
84}
54fn main() {
55 let mut verbose: bool = false;
56 let mut foo_bar = FooBar::Foo;
57 let mut initial: Option<u32> = None;
58 let mut countries: HashSet<Country> = HashSet::default();
59 let mut items: Vec<u32> = Vec::default();
60
61 let ap = CommandLineParser::new("foo_bar");
62 let parser = ap
63 .add(
64 Parameter::option(Switch::new(&mut verbose, true), "verbose", Some('v'))
65 .help("Do dee doo."),
66 )
67 .branch(
68 Condition::new(Scalar::new(&mut foo_bar), "foo_bar")
69 .choice(FooBar::Foo, "123 abc let's make this one medium long.")
70 .choice(FooBar::Bar, "456 def let's make this one multiple sentences. We're really stretching here HAAAAAAAA HAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA!")
71 .help("foo'y bar'y stuff")
72 .meta(vec!["a", "b", "c"]),
73 )
74 .command(FooBar::Foo, |sub| {
75 sub.add(Parameter::option(
76 Optional::new(&mut initial),
77 "initial",
78 None,
79 ))
80 .add(
81 Parameter::argument(Collection::new(&mut items, Nargs::Any), "item")
82 .help("The items."),
83 )
84 })
85 .command(FooBar::Bar, |sub| {
86 sub.add(Parameter::option(
87 Collection::new(&mut countries, Nargs::AtLeastOne),
88 "country",
89 None,
90 ))
91 })
92 .build();
93 parser.parse();
94 println!("Items: {items:?}");
95 execute(verbose, foo_bar, initial, countries, items);
96}
3fn main() {
4 let mut sub: u32 = 0;
5 let mut arg_0: bool = false;
6 let mut opt_0: bool = false;
7 let mut arg_1: bool = false;
8
9 let clp = CommandLineParser::new("sub-command");
10 let parser = clp
11 .about("Describe the base command line parser. Let's make it a little long for fun.")
12 .branch(
13 Condition::new(Scalar::new(&mut sub), "sub")
14 // "0" is an undocumented sub-command.
15 // "1" is a regular sub-command.
16 .choice(1, "the one sub-command")
17 // "2" is a regular sub-command.
18 .choice(2, "the two sub-command")
19 // "3" is a false sub-command.
20 // It will appear in the documentation, but only those specified via `command(..)` actually affect the program structure.
21 .choice(3, "the three sub-command"),
22 )
23 .command(0, |sub_command| {
24 sub_command
25 .about("Describe the 0 sub-command parser. Let's make it a little long for fun.")
26 .add(Parameter::argument(Scalar::new(&mut arg_0), "arg"))
27 .add(Parameter::option(
28 Switch::new(&mut opt_0, true),
29 "opt",
30 None,
31 ))
32 })
33 .command(1, |sub_command| {
34 sub_command
35 .about("Describe the 1 sub-command parser.")
36 .add(Parameter::argument(Scalar::new(&mut arg_1), "arg"))
37 })
38 // Specify an argument-less & option-less sub-command by leaving the 'sub' untouched.
39 .command(2, |sub_command| sub_command)
40 // Since we never add "3", it isn't a true sub-command.
41 .build();
42
43 parser.parse();
44
45 println!("Used sub-command '{sub}'.");
46 match sub {
47 0 => {
48 println!("arg_0: {arg_0}");
49 println!("opt_0: {opt_0}");
50 assert!(!arg_1);
51 }
52 1 => {
53 assert!(!arg_0);
54 assert!(!opt_0);
55 println!("arg_1: {arg_1}");
56 }
57 2 => {
58 assert!(!arg_0);
59 assert!(!opt_0);
60 assert!(!arg_1);
61 println!("argument-less & option-less");
62 }
63 _ => {
64 panic!(
65 "impossible - the parser will reject any variants not specified via `command(..)`."
66 )
67 }
68 }
69}
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?
3fn main() {
4 let mut items: Vec<u32> = Vec::default();
5
6 let clp = CommandLineParser::new("summer");
7 let parser = clp
8 .add(
9 Parameter::argument(Collection::new(&mut items, Nargs::AtLeastOne), "item")
10 .help("The items to sum."),
11 )
12 .build();
13
14 parser.parse();
15 let sum: u32 = items.iter().sum();
16 println!("Sum: {sum}");
17}
More examples
2fn main() {
3 let mut verbose: bool = false;
4 let mut value: u32 = 0;
5 let ap = CommandLineParser::new("example");
6 let parser = ap
7 .add(Parameter::option(
8 Switch::new(&mut verbose, true),
9 "verbose",
10 Some('v'),
11 ))
12 .add(Parameter::argument(Scalar::new(&mut value), "value").meta(vec!["type: u32"]))
13 .build();
14 parser.parse();
15 println!("value: {value}, verbose: {verbose}");
16}
30fn parse_tokens(parse_fn: impl FnOnce(GeneralParser) -> Result<(), i32>) -> Params {
31 let mut params = Params::init();
32
33 let clp = CommandLineParser::new("organization");
34 let parser = clp
35 .add(Parameter::option(
36 Switch::new(&mut params.verbose, true),
37 "verbose",
38 Some('v'),
39 ))
40 .add(Parameter::argument(
41 Collection::new(&mut params.items, Nargs::AtLeastOne),
42 "item",
43 ))
44 .build();
45
46 // The parse_fn signature is a `Result`.
47 // 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.
48 parse_fn(parser).expect("test-reachable-only");
49 params
50}
53fn main() {
54 let mut _verbose: bool = false;
55 let mut operand: Operand = Operand::Add;
56 let mut initial: Option<u32> = None;
57 let mut _countries: HashSet<Country> = HashSet::default();
58 let mut items: Vec<u32> = Vec::default();
59
60 let ap = CommandLineParser::new("reducer");
61 let parser = ap
62 .add(
63 Parameter::option(Switch::new(&mut _verbose, true), "verbose", Some('v'))
64 .help("Do dee doo. We're really stretching here HAAAAAAAA HAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA!"),
65 )
66 .add(
67 Parameter::option(Scalar::new(&mut operand), "operand", Some('o'))
68 .help("moot")
69 .choice(Operand::Add, "+")
70 .choice(Operand::Multiply, "*"),
71 )
72 .add(Parameter::option(Optional::new(&mut initial), "initial", None)
73 .meta(vec!["testing a really long meta.. abcdefghijklmnopqrstuvwxyz"])
74 )
75 .add(Parameter::option(Collection::new(&mut _countries, Nargs::AtLeastOne), "country", None))
76 .add(
77 Parameter::argument(Collection::new(&mut items, Nargs::AtLeastOne), "item")
78 .help("The items."),
79 )
80 .build();
81 parser.parse();
82 println!("Items: {items:?}");
83 execute(_verbose, operand, initial, _countries, items);
84}
54fn main() {
55 let mut verbose: bool = false;
56 let mut foo_bar = FooBar::Foo;
57 let mut initial: Option<u32> = None;
58 let mut countries: HashSet<Country> = HashSet::default();
59 let mut items: Vec<u32> = Vec::default();
60
61 let ap = CommandLineParser::new("foo_bar");
62 let parser = ap
63 .add(
64 Parameter::option(Switch::new(&mut verbose, true), "verbose", Some('v'))
65 .help("Do dee doo."),
66 )
67 .branch(
68 Condition::new(Scalar::new(&mut foo_bar), "foo_bar")
69 .choice(FooBar::Foo, "123 abc let's make this one medium long.")
70 .choice(FooBar::Bar, "456 def let's make this one multiple sentences. We're really stretching here HAAAAAAAA HAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA!")
71 .help("foo'y bar'y stuff")
72 .meta(vec!["a", "b", "c"]),
73 )
74 .command(FooBar::Foo, |sub| {
75 sub.add(Parameter::option(
76 Optional::new(&mut initial),
77 "initial",
78 None,
79 ))
80 .add(
81 Parameter::argument(Collection::new(&mut items, Nargs::Any), "item")
82 .help("The items."),
83 )
84 })
85 .command(FooBar::Bar, |sub| {
86 sub.add(Parameter::option(
87 Collection::new(&mut countries, Nargs::AtLeastOne),
88 "country",
89 None,
90 ))
91 })
92 .build();
93 parser.parse();
94 println!("Items: {items:?}");
95 execute(verbose, foo_bar, initial, countries, items);
96}
4fn main() {
5 let contains_dynamic_x = env::var("DYNAMIC_X").is_ok();
6 let contains_dynamic_y = env::var("DYNAMIC_Y").is_ok();
7
8 let mut sub: u32 = 0;
9 let mut arg_0: bool = false;
10 let mut arg_1: bool = false;
11 let mut arg_2: bool = false;
12
13 let mut condition = Condition::new(Scalar::new(&mut sub), "sub")
14 // "0" is an undocumented sub-command, but will only available when environment contains `DYNAMIC_X`.
15 // "1" is a regular sub-command.
16 .choice(1, "the one sub-command");
17
18 if contains_dynamic_y {
19 // "2" is a sub-command that will only be available when the environment contains `DYNAMIC_Y`.
20 condition = condition.choice(2, "the two sub-command");
21 }
22
23 let clp = CommandLineParser::new("sub-command");
24 let mut clp = clp.branch(condition).command(1, |sub_command| {
25 sub_command.add(Parameter::argument(Scalar::new(&mut arg_1), "arg"))
26 });
27
28 if contains_dynamic_x {
29 clp = clp.command(0, |sub_command| {
30 sub_command.add(Parameter::argument(Scalar::new(&mut arg_0), "arg"))
31 });
32 }
33
34 if contains_dynamic_y {
35 clp = clp.command(2, |sub_command| {
36 sub_command.add(Parameter::argument(Scalar::new(&mut arg_2), "arg"))
37 });
38 }
39
40 let parser = clp.build();
41
42 parser.parse();
43
44 println!("Used sub-command '{sub}'.");
45 match sub {
46 0 => {
47 println!("arg_0: {arg_0}");
48 assert!(!arg_1);
49 assert!(!arg_2);
50 }
51 1 => {
52 assert!(!arg_0);
53 println!("arg_1: {arg_1}");
54 assert!(!arg_2);
55 }
56 2 => {
57 assert!(!arg_0);
58 assert!(!arg_1);
59 println!("arg_2: {arg_2}");
60 }
61 _ => {
62 panic!("impossible - the parser will reject any variants not specified via `add(..)`.")
63 }
64 }
65}
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?
3fn main() {
4 let mut items: Vec<u32> = Vec::default();
5
6 let clp = CommandLineParser::new("summer");
7 let parser = clp
8 .add(
9 Parameter::argument(Collection::new(&mut items, Nargs::AtLeastOne), "item")
10 .help("The items to sum."),
11 )
12 .build();
13
14 parser.parse();
15 let sum: u32 = items.iter().sum();
16 println!("Sum: {sum}");
17}
More examples
53fn main() {
54 let mut _verbose: bool = false;
55 let mut operand: Operand = Operand::Add;
56 let mut initial: Option<u32> = None;
57 let mut _countries: HashSet<Country> = HashSet::default();
58 let mut items: Vec<u32> = Vec::default();
59
60 let ap = CommandLineParser::new("reducer");
61 let parser = ap
62 .add(
63 Parameter::option(Switch::new(&mut _verbose, true), "verbose", Some('v'))
64 .help("Do dee doo. We're really stretching here HAAAAAAAA HAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA!"),
65 )
66 .add(
67 Parameter::option(Scalar::new(&mut operand), "operand", Some('o'))
68 .help("moot")
69 .choice(Operand::Add, "+")
70 .choice(Operand::Multiply, "*"),
71 )
72 .add(Parameter::option(Optional::new(&mut initial), "initial", None)
73 .meta(vec!["testing a really long meta.. abcdefghijklmnopqrstuvwxyz"])
74 )
75 .add(Parameter::option(Collection::new(&mut _countries, Nargs::AtLeastOne), "country", None))
76 .add(
77 Parameter::argument(Collection::new(&mut items, Nargs::AtLeastOne), "item")
78 .help("The items."),
79 )
80 .build();
81 parser.parse();
82 println!("Items: {items:?}");
83 execute(_verbose, operand, initial, _countries, items);
84}
54fn main() {
55 let mut verbose: bool = false;
56 let mut foo_bar = FooBar::Foo;
57 let mut initial: Option<u32> = None;
58 let mut countries: HashSet<Country> = HashSet::default();
59 let mut items: Vec<u32> = Vec::default();
60
61 let ap = CommandLineParser::new("foo_bar");
62 let parser = ap
63 .add(
64 Parameter::option(Switch::new(&mut verbose, true), "verbose", Some('v'))
65 .help("Do dee doo."),
66 )
67 .branch(
68 Condition::new(Scalar::new(&mut foo_bar), "foo_bar")
69 .choice(FooBar::Foo, "123 abc let's make this one medium long.")
70 .choice(FooBar::Bar, "456 def let's make this one multiple sentences. We're really stretching here HAAAAAAAA HAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA!")
71 .help("foo'y bar'y stuff")
72 .meta(vec!["a", "b", "c"]),
73 )
74 .command(FooBar::Foo, |sub| {
75 sub.add(Parameter::option(
76 Optional::new(&mut initial),
77 "initial",
78 None,
79 ))
80 .add(
81 Parameter::argument(Collection::new(&mut items, Nargs::Any), "item")
82 .help("The items."),
83 )
84 })
85 .command(FooBar::Bar, |sub| {
86 sub.add(Parameter::option(
87 Collection::new(&mut countries, Nargs::AtLeastOne),
88 "country",
89 None,
90 ))
91 })
92 .build();
93 parser.parse();
94 println!("Items: {items:?}");
95 execute(verbose, foo_bar, initial, countries, items);
96}
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?
2fn main() {
3 let mut verbose: bool = false;
4 let mut value: u32 = 0;
5 let ap = CommandLineParser::new("example");
6 let parser = ap
7 .add(Parameter::option(
8 Switch::new(&mut verbose, true),
9 "verbose",
10 Some('v'),
11 ))
12 .add(Parameter::argument(Scalar::new(&mut value), "value").meta(vec!["type: u32"]))
13 .build();
14 parser.parse();
15 println!("value: {value}, verbose: {verbose}");
16}
More examples
53fn main() {
54 let mut _verbose: bool = false;
55 let mut operand: Operand = Operand::Add;
56 let mut initial: Option<u32> = None;
57 let mut _countries: HashSet<Country> = HashSet::default();
58 let mut items: Vec<u32> = Vec::default();
59
60 let ap = CommandLineParser::new("reducer");
61 let parser = ap
62 .add(
63 Parameter::option(Switch::new(&mut _verbose, true), "verbose", Some('v'))
64 .help("Do dee doo. We're really stretching here HAAAAAAAA HAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA!"),
65 )
66 .add(
67 Parameter::option(Scalar::new(&mut operand), "operand", Some('o'))
68 .help("moot")
69 .choice(Operand::Add, "+")
70 .choice(Operand::Multiply, "*"),
71 )
72 .add(Parameter::option(Optional::new(&mut initial), "initial", None)
73 .meta(vec!["testing a really long meta.. abcdefghijklmnopqrstuvwxyz"])
74 )
75 .add(Parameter::option(Collection::new(&mut _countries, Nargs::AtLeastOne), "country", None))
76 .add(
77 Parameter::argument(Collection::new(&mut items, Nargs::AtLeastOne), "item")
78 .help("The items."),
79 )
80 .build();
81 parser.parse();
82 println!("Items: {items:?}");
83 execute(_verbose, operand, initial, _countries, items);
84}
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.");