Struct rusty_dumb_tools::arg::DumbArgParser

pub struct DumbArgParser { /* private fields */ }

A simple argument parser.

Example usage:

use rusty_dumb_tools::prelude::*;
let mut parser = DumbArgParser::new();
parser.set_description("This is a simple argument parser.");
parser.set_allow_missing_arguments();  // *** normal should not do this; this is just to make this code to run without error  ***
dap_arg!("-v", flag2="--verbose", fixed=true).add_to(&mut parser);  // argument flag "-v" / "--verbose" with fixed value (true) when the flag is present
dap_arg!("-n", flag2="--name", default="nobody").add_to(&mut parser);  // argument "-n" / "--name" requiring input value, with default "nobody"
dap_arg!("str-arg").add_to(&mut parser);  // positional argument "str-arg" (of type String)
dap_arg!("i32-arg", value=123).add_to(&mut parser);  // positional argument "i32-arg" of type i32 (inferred from the value 123)
dap_arg!("multi-arg").set_multi().add_to(&mut parser);  // positional multi-argument "multi-arg" that will accept multiple values (one + rest)
parser.parse_args();  // parse from command-line arguments
println!(". -v: {:?}", parser.get::<bool>("-v"));
println!(". --verbose: {:?}", parser.get::<bool>("--verbose"));  // will be the same parameter value as "-v"
println!(". --name: {:?}", parser.get::<String>("--name"));  // can use "-n" as well
println!(". str-arg: {:?}", parser.get::<String>("str-arg"));
println!(". i32-arg: {:?}", parser.get::<i32>("i32-arg"));
println!(". multi-arg: {:?}", parser.get_multi::<String>("multi-arg"));

Notes:

• -h and –help are reserved for showing help message; after showing the help message, the program will exit
• in case of invalid input argument, will show the error message as well as the help message, then the program will exit
• arguments are typed; the default is String; others are std::i32, std::i64, std::f32, std::f64 and bool
• also see the macro dap_arg

The above code, if run with invalid argument like -x, you will see the help screen like

| !!!
| !!! INVALID INPUT ARGUMENT: unknown input argument [-x]
| !!!
| USAGE: rusty_dumb_tools [-h] [-v] [-n name] <str-arg> <i32-arg> <multi-arg>
| : This is a simple argument parser.
| . -h, --help : HELP
| . -v, --verbose : FLAG [true]
| . -n name, --name name : OPTIONAL; default [nobody]
| . <str-arg> : REQUIRED
| . <i32-arg> : REQUIRED; e.g. 123
| . <multi-arg> ... : REQUIRED ...

• USAGE ... – the line that shows how the program should be invoked
• This is a simple argument parser – the provided description
• -h, --help : HELP – special for showing the HELP screen
• ‘-v, –verbose : FLAG true’ – a fixed FLAG argument; when such fixed FLAG is supplied, the argument is treated as the fixed value true
• -n name, --name name : OPTIONAL; default [nobody] – an optional argument that requires a string (name) following it; if not supplied, the default value is nobody
• <str-arg> : REQUIRED – a required positional argument of type String
• <i32-arg> : REQUIRED; e.g. 123 – a required positional argument of type i32; the example value 123 is provided
• <multi-arg> ... : REQUIRED ... – positional argument that can accept multiple values; at least one argument is required; notice the ...

You may want to refer to crate::demo::run_demo for a demo program that uses DumbArgParser.

Implementations

impl DumbArgParser

pub fn new() -> DumbArgParser

create and instance of DumbArgParser; program name will be extracted from env::args when DumbArgParser::parse_args is called use DumbArgParser::new_with_name if want to create an instance with a specific program name

pub fn new_with_name(program_name: &str) -> DumbArgParser

create an instance of DumbArgParser with the specific program name to be shown in the help message

pub fn set_description(&mut self, description: &str)

set the program description to be shown in the help message

pub fn set_allow_missing_arguments(&mut self)

in case of missing arguments, DumbArgParser::get will return None instead of exiting the program

pub fn compose_usage(&self) -> String

compose the “usage” part of the help message, mostly for illustration use

pub fn compose_inputs(&self) -> String

compose the equivalent argument inputs after parsing, mostly for illustration use

pub fn get<T: ArgValueTrait>(&self, arg_name: &str) -> Option<T>

get the parsed – DumbArgParser::parse_args – argument value (parameter) assigned to the given argument name

• arg_name - the argument name of which the value is to be retrieved; it can be a positional argument name, or can be a flag argument name (including flag2, which is just an alias to the flag argument)

e.g.

let param: i32 = parser.get("i32-arg").unwrap();

or

let param = parser.get::<i32>("i32-arg").unwrap();

note: except that all types can be implicitly converted to String, no other implicit type conversion; if type does not agree, will panic

pub fn get_or_default<T: ArgValueTrait>(&self, arg_name: &str, default: T) -> T

like DumbArgParser::get but returns a default value if the argument value is not supplied; note that if the argument is specified to have default (set with DumbArgBuilder::default()), that default will be used instead of the one provided here

pub fn get_string(&self, arg_name: &str) -> Option<String>

like DumbArgParser::get but returns a String

pub fn get_multi<T: ArgValueTrait>(&self, arg_name: &str) -> Option<Vec<T>>

get the parsed – DumbArgParser::parse_args – multi-argument values – see DumbArgBuilder::set_multi – associated with the given argument name

• arg_name - the argument name of which the values are to be retrieved

note: like DumbArgParser::get, except when target type is String, no implicit type conversion

pub fn get_multi_strings(&self, arg_name: &str) -> Option<Vec<String>>

like DumbArgParser::get_multi but returns a Vec of String

pub fn get_rest(&self, arg_name: &str) -> Option<Vec<String>>

get the parsed – DumbArgParser::parse_args – “rest” multi-argument values – see DumbArgBuilder::set_rest – associated with the given argument name

• arg_name - the argument name of which the values are to be retrieved

pub fn process_rest_args(&self, arg_name: &str, parser: &mut DumbArgParser)

IMPORTANT: assume DumbArgParser::get_rest is able to retrieve the “rest” multi-argument values

pub fn check_process_rest_args( &self, arg_name: &str, parser: &mut DumbArgParser, show_help_if_needed: bool, ) -> Result<bool, DumbError>

IMPORTANT: assume DumbArgParser::get_rest is able to retrieve the “rest” multi-argument values

pub fn parse_args(&mut self)

parse from the input program arguments – env::args – for argument values (parameters); after parsing, the argument values can be retrieved by DumbArgParser::get

pub fn check_parse_args( &mut self, show_help_if_needed: bool, ) -> Result<bool, DumbError>

like DumbArgParser::parse_args but returns a Result instead of exiting the program

pub fn show_help(&self, err_msg: Option<String>, and_exit: bool)

pub fn process_args(&mut self, in_args: Vec<&str>)

like DumbArgParser::parse_args but the input arguments to parse are provided explicitly

pub fn check_process_args( &mut self, in_args: Vec<&str>, show_help_if_needed: bool, ) -> Result<bool, DumbError>

like DumbArgParser::process_args but returns a Result instead of exiting the program

Trait Implementations

impl Debug for DumbArgParser

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

Formats the value using the given formatter.