Skip to content

Latest commit

 

History

History
252 lines (182 loc) · 5.96 KB

README.md

File metadata and controls

252 lines (182 loc) · 5.96 KB
Raw

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 argument. 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();

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

Support

Please report any bugs or feature requests at:

Feel free to fork the repository and submit pull requests :)

Слава Україні!

Author

Alfie John <alfie@alfie.wtf>

Warranty

IT COMES WITHOUT WARRANTY OF ANY KIND.

Copyright and License

Copyright (C) 2022 by Alfie John

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License and GNU Free Documentation License as published by the Free Software Foundation, either version 3 of the GPL or 1.3 of the GFDL, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.