Struct blarg::GeneralParser
source · pub struct GeneralParser<'a> { /* private fields */ }
Expand description
The configured command line parser.
Built via CommandLineParser::build
or SubCommandParser::build
.
Implementations§
source§impl<'a> GeneralParser<'a>
impl<'a> GeneralParser<'a>
sourcepub fn parse_tokens(self, tokens: &[&str]) -> Result<(), i32>
pub fn parse_tokens(self, tokens: &[&str]) -> Result<(), i32>
Run the command line parser against the input tokens.
Help messages are printed on stdout
, while error messages are printed on stderr
.
The parser will process the input tokens based off the CommandLineParser
/SubCommandParser
configuration.
Parsing happens in two phases:
- Token matching aligns the tokens to arguments and options. All tokens must be matched successfully in order to proceed to the next phase.
- Token capturing parses the tokens by their respective types
T
. This phase will actually mutate your program variables.
If at any point the parser encounters an error (ex: un-matched token, un-capturable token, etc), it will return with Err(1)
.
If the help switch (-h
or --help
) is encountered, the parser will display the help message and return with Err(0)
.
This skips the phase #2 capturing.
In the case of a sub-command based parser, a third phase is introduced where the parser is branched into the sub-command.
After branching, the token matching and token capturing phases are repeated for the sub-command.
In effect, the input tokens are partitioned based off the branching Condition
.
sourcepub fn parse(self)
pub fn parse(self)
Run the command line parser against the Cli env::args
.
Help messages are printed on stdout
, while error messages are printed on stderr
.
The parser will process the input tokens based off the CommandLineParser
/SubCommandParser
configuration.
Parsing happens in two phases:
- Token matching aligns the tokens to arguments and options. All tokens must be matched successfully in order to proceed to the next phase.
- Token capturing parses the tokens by their respective types
T
. This phase will actually mutate your program variables.
If at any point the parser encounters an error (ex: un-matched token, un-capturable token, etc), it will exit with error code 1
(via std::process::exit
).
If the help switch (-h
or --help
) is encountered, the parser will display the help message and exit with error code 0
.
This skips the phase #2 capturing.
In the case of a sub-command based parser, a third phase is introduced where the parser is branched into the sub-command.
After branching, the token matching and token capturing phases are repeated for the sub-command.
In effect, the input tokens are partitioned based off the branching Condition
.
Examples found in repository?
More examples
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}");
}
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}");
}
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);
}