Struct GeneralParser

pub struct GeneralParser<'a> { /* private fields */ }

The configured command line parser. Built via CommandLineParser::build or SubCommandParser::build.

Implementations

impl<'a> GeneralParser<'a>

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:

1. Token matching aligns the tokens to arguments and options. All tokens must be matched successfully in order to proceed to the next phase.
2. 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.

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:

1. Token matching aligns the tokens to arguments and options. All tokens must be matched successfully in order to proceed to the next phase.
2. 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

examples/demo_organization.rs (line 26)

fn parse() -> Params {
    parse_tokens(|parser: GeneralParser| Ok(parser.parse()))
}

examples/empty.rs (line 6)

fn main() {
    let ap = CommandLineParser::new("empty");
    let parser = ap.build();
    parser.parse();
    println!("empty parser");
}

examples/demo_summer_b.rs (line 14)

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}");
}

examples/example.rs (line 14)

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}");
}

examples/reducer.rs (line 81)

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

examples/foo_bar.rs (line 93)

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

Additional examples can be found in:

• examples/dynamic_sub_command.rs
• examples/demo_sub_command.rs

Trait Implementations

impl<'a> Debug for GeneralParser<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.