revparse

Usage

First you have to create a mutable variable, we'll call it parser

let mut parser = revparse::Parser::new("executable_name"); // for grep "executable_name" would be "grep"

There are two types of arguments the user can give

One that takes a value, and one that doesn't:

grep --version      // takes no value
grep --file=FILE    // takes a value

In this example we will add an argument of the first type, that takes no value

parser.add_argument(
    "--version",
    Some("-V"),     // Short name (optional)
    "display version information and exit", // help message
    None,           // Take no value
);

How the argument will be shown in the help message:

  -V, --version             display version information and exit

In this example we will add an argument of the second type, that takes a value

parser.add_argument(
    "--file",
    Some("-f"),     // Short name (optional)
    "take PATTERNS from FILE",  // help message
    Some("FILE"),   // Take a value called FILE to help the user understand what it is for
);

How the argument will be shown in the help message:

  -f, --file=FILE           take PATTERNS from FILE

Before getting ANY argument at all, you have to call

parser.run();

ONCE in the entire program, not for every argument!

Find out if the user gave us an Option of the first type (That takes no value), or not

(Using the 'get_noval' function)

let version: bool = parser.get_noval("--version");

Get the value the user entered for the second type (That takes a value)

(Using the 'get_val' function)

let file: Option<String> = parser.get_val("--file"); // DIFFERENT FUNCTION THAN ABOVE !!!

// The 'file' variable will be None, if the user didn't enter this flag, and Some(String) if he did

Examples

Since we want to simulate the user giving us flags (often called Options), we will use the run_custom_args() function instead of run()

let mut parser = revparse::Parser::new("grep");
parser.add_argument("--test", Some("-t"), "this is a test flag, that takes a value", Some("TEST_VALUE"));
parser.run_custom_args(&["program_name", "-t", "some_value"]); // --test will work just the same
let test: Option<String> = parser.get_val("--test");
assert_eq!(test.unwrap(), "some_value");

let mut parser = revparse::Parser::new("grep");
parser.add_argument("--test", Some("-t"), "this is a test flag, that takes a value", Some("TEST_VALUE"));
// This time the user doesn't give us an argument
parser.run_custom_args(&["program_name"]);
let test: Option<String> = parser.get_val("--test");
assert_eq!(test, None);     // Which is why the 'test' variable is None, and not Some(String)

let mut parser = revparse::Parser::new("grep");
parser.add_argument("--test", Some("-t"), "this is a test flag, that takes no value", None);
parser.run_custom_args(&["program_name", "-t"]);    // again, --test will work the same
let test: bool = parser.get_noval("--test");        // you can't use "-t" for this function
assert_eq!(test, true);

let mut parser = revparse::Parser::new("grep");
parser.add_argument("--test", Some("-t"), "this is a test flag, that takes no value", None);
parser.run_custom_args(&["program_name"]);      // this time the user gave us no arguments
let test: bool = parser.get_noval("--test");     
assert_eq!(test, false);                        // which is why the 'test' variable is false

Positional Arguments

revparse supports the use of positional arguments, which are values passed without flags.

Like this:

program some_value

Instead of

program --value=some_value

Usage

parser.add_pos_arg("ARGUMENT");

Help message

With a positional argument:

Usage: executable_name [OPTION]... ARGUMENT

Options:
  -h, --help                display this help text and exit

Without a positional argument:

Usage: executable_name [OPTION]...

Options:
  -h, --help                display this help text and exit

As you can see, the ARGUMENT after [OPTION]... vanished

Here's how to force the user to enter at least 1 out of 2 positional arguments

parser.add_pos_arg("ARGUMENT1");    // This argument will be forced
parser.add_pos_arg("[ARGUMENT2]");  // This argument won't be forced
// Since we want the user to enter the first one, but don't care
// about whether he enters a second positional argument, we will pass 1 to this function
parser.min_pos_args(1);
// If you were to give 2 to that function, the user would have to enter 2 positional arguments

Getting the value of positional arguments

// Example from above
parser.add_pos_arg("ARGUMENT1");
parser.add_pos_arg("[ARGUMENT2]");
parser.min_pos_args(1);
parser.run_custom_args(&["executable_name", "first_positional_argument", "--", "---second positional argument"]);
// The second positional argument starts with --- to demonstrate, that the user will have to type -- before such an argument
let pos_args: Vec<String> = parser.get_pos_args();
// parser.get_pos_args() returns a Vector with ALL positional arguments given
assert_eq!(pos_args.len(), 2); // The user entered both positional arguments, so the length is 2
assert_eq!(pos_args[0], "first_positional_argument");
assert_eq!(pos_args[1], "---second positional argument");

Help message for positional arguments

Sometimes positional arguments need an explanation, like with grep:

Usage: grep [OPTION]... PATTERNS [FILE]...
Search for PATTERNS in each FILE.
Example: grep -i 'hello world' menu.h main.c
PATTERNS can contain multiple patterns separated by newlines.

To implement the above help message with this library you can use the 'pos_arg_help' function:

parser.pos_arg_help("Search for PATTERNS in each FILE.
Example: grep -i 'hello world' menu.h main.c
PATTERNS can contain multiple patterns separated by newlines.");

Allow an infinite amount of positional arguments

Usage

// We'll add one positional argument, so the user knows the meaning of all of the positional arguments.
parser.add_pos_arg("[FILE]...");
parser.allow_infinite_pos_args();
parser.run();
// Then get the positional arguments
let pos_args: Vec<String> = parser.get_pos_args();
// do something with them
for file in pos_args {
    println!("File given: '{file}'");
}

If you don't call the function allow_infinite_pos_args(), then the amount of positional arguments the user can enter is limited to the amount of times the add_pos_arg() function was called