Crate clappers

Clappers - Command Line Argument Parsing Particularly Easy, Relatively Straightforward!

Clappers aims to be the most user-friendly command line argument parser this side of the Milky Way. You configure a Clappers parser with the command line arguments you care about via chaining, with the last link in the chain being a call to build(). Command line argument values are then retrieved via getters on the Clappers parser.

Example 1 - A Minimal Directory Listing

use clappers::Clappers;

fn main() {
    let clappers = Clappers::new()
        .set_flags(vec![
            "h|help",
            "l",
            "R|recursive",
        ])
        .build();

    if clappers.get_flag("help") {
        println!("
            usage: ls [arguments] [FILE1]...

            Arguments:
                -h|--help        Print this help
                -l               Use a long listing format
                -R|--recursive   List subdirectories recursively
        ");
    }

    if clappers.get_flag("l") {
        // Show more details than usual
    }

    if clappers.get_flag("R") {
        // Recurse into subdirectories
    }

    if clappers.get_flag("recursive") {
        // This will also recurse
    }

    let filenames: Vec<String> = clappers.get_leftovers();

    // ...
}

Example 2 - A Minimal Compiler

use clappers::Clappers;

fn main() {
    let clappers = Clappers::new()
        .set_flags(vec![
            "h|help",
            "v|verbose",
        ])
        .set_singles(vec![
            "o|output",
        ])
        .set_multiples(vec![
            "i|input",
            "I",
            "L",
        ])
        .build();

    if clappers.get_flag("help") {
        println!("
            usage: compile [arguments]

            Arguments:
                -h|--help                        Print this help
                -v|--verbose                     Enable verbose mode
                -I <dir1> ... <dirN>             Include directories
                -L <dir1> ... <dirN>             Library directories
                -i|--input <file1> ... <fileN>   Input filenames
                -o|--output filename             Output filename
        ");
    }

    let output_filename = clappers.get_single("output");
    let input_filenames: Vec<String> = clappers.get_multiple("input");

    // ...
}

Argument Types

There are four types of arguments:

1. Flags
2. Single value
3. Multiple value
4. Leftovers

1. Flag Arguments

Flag arguments are true if they were supplied on the command line, and false otherwise e.g:

 -h
 --help
 -v
 --verbose

Note: flag arguments do not take values

2. Single Value Arguments

Single value arguments contain a single String value if they were supplied on the command line, and empty String otherwise e.g:

 -o filename.txt
 --output filename.txt
 -u Zelensky
 --username Zelensky

3. Multiple Value Arguments

Multiple value arguments contain at least a single String value if they were supplied on the command line, and empty String otherwise e.g:

 -i file1.txt
 --input file1.txt
 --host host1

They can also contain multiple values, by repetition on the command line e.g:

 -i file1.txt -i file2.txt ... -i fileN.txt
 --host host1 --host host2 ... --host hostN

The following format also works, reading from the first value until either the next argument is reached, or until the end of the entire command line arguments e.g:

 -i file1.txt file2.txt ... fileN.txt -n next_argument
 --host host1 host2 hostN

4. Leftover Arguments

Leftover argument values are values supplied on the command line that are not associated with any configuration. These includes:

• any values when no other argument types have been supplied e.g:

 ls file1 file2... fileN

• any values after the double-dash argument e.g:

 ls -l -R  -- file1 file2... fileN`

• any value supplied to flags, because flags do not accept values

• any remaining values supplied to singles value arguments, because these only take a one value

Caveats

• Combining flags is currently unsupported i.e the following does not work:

 tar -zcf filename.tar.gz *

• Equals-Value is currently unsupported i.e the following does not work:

 tar -zc --file=filename.tar.gz

• Commands with their own separate Clappers parser is currently unsupported i.e the following does not work:

 apt-get -y install -f cargo
 apt-get update -f

• Command line argument values are always String types. This was by design, and no convenience functions are planned. To convert a String to something else, use String’s built-in parse() function instead:

 use clappers::Clappers;

 fn main() {
     let clappers = Clappers::new()
         .set_singles(vec!["number"])
         .build();

     let number: i32 = clappers.get_single("number").parse().unwrap_or(0);

     println!("Double {number} is {}", number * 2);
 }

Structs

• Clappers