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
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}
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}
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}