ArgSplitter - helper crate for parsing command line arguments

Helper crate for parsing command line arguments

Crates such as clap allow you to create a command-line parser with many bells and whistles. For example,

• automatically parsing the configuration into a struct,
• generating help text,
• or even starting with the help text and deriving the command-line parser from that.

The downside is that to cover all possibilities the API has to be quite large and elaborate and you have to do quite some learning, documentation reading and tinkering to get it to do what you want. Moreover, you forget and then have to relearn all that whenever you want to change an old project or start a new one.

The main aim of the argsplitter crate is that it should take only a few minutes to be productive again when coming back after not using it for a while. It tries to make it easy to process command-line flags using Rust's match statement and it tries to help correctly deal with arguments that have an invalid Unicode encoding. As such, it only provides the following services:

1. Splitting combined single-dash flags such as -xvf into separate flags -x, -v and -f.

2. Dealing with flags arguments such as -fbanana or --fruit=banana. The latter may or may not be equivalent with --fruit banana.

3. Correctly dealing with non-unicode arguments such as filenames, while still working with regular strings wherever possible. This is important because both Unix and Windows allow file names which cannot be represented as UTF-8 encoded strings.

A note about encodings: Item 3) is important because Rust strings are defined to be encoded as UTF-8 but both Unix and Windows allow file names and command-line arguments that are not Unicode. For these, Rust provides [OsString] which is less convenient to work with than [String] but can represent everything. In the argsplitter API, methods suffixed with _os have return types based on [OsString] and the others are based on [String]. You can switch back and forth between these variants as required.

Overview

We distinguish short options, long options and words. Short options start with a single dash and can be bundled, so -xvf is equivalent to -x -v -f. Long options such as --file start with two dashes and always contain a single multi-letter flag. Words are arguments that do not start with a dash. Sometimes they are standalone arguments and sometimes they are a parameter to a preceding flag. Long options can also have a parameter attached, for example --file=data.csv.

Parsers made with argsplitter crate are not declarative but purely procedural. First you construct an ArgSplitter and then you repeatedly call the methods item() or item_os(), param() or param_os(), and flag() to consume options and words from the commandline.

Example

use argsplitter::{main_support, ArgError, ArgSplitter};
use std::{error::Error, path::PathBuf, process::ExitCode};

const USAGE: &str = r###"
Usage: send_mail [OPTIONS..] RECIPIENT..
Options:
   -v   --verbose          Describe what's going on
   -a   --attach FILE      Attach this file
   -s   --subject TEXT     Subject: line
   -h   --help             Print this help
"###;

fn main() -> ExitCode {
    main_support::report_errors(USAGE, work())
}

fn work() -> Result<(), Box<dyn Error>> {
    // To be configured using arguments
    let mut verbose = false;
    let mut subject: Option<String> = None;
    let mut attachments: Vec<PathBuf> = vec![];

    let mut argsplitter = ArgSplitter::from_env();

    // .flag() skips non-flag arguments and stashes them for later use.
    while let Some(flag) = argsplitter.flag()? {
        match flag {
            "-h" | "--help" => {
                println!("{}", USAGE.trim());
                return Err(ArgError::exit_successfully())?;
            }

            "-v" | "--verbose" => verbose = true,

            // subject is a String so we use .param()
            "-s" | "--subject" => subject = Some(argsplitter.param()?),

            // attachment is a file name  so we use .param_os()
            "-a" | "--attach" => attachments.push(argsplitter.param_os()?.into()),

            flag => return Err(ArgError::unknown_flag(flag))?,
        }
    }

    // Pick up the recipients stashed by .flag().
    // The first argument states the minimum number that must be present.
    // The second argument is used in the error messages.
    let recipients: Result<Vec<_>, _> = argsplitter.stashed_args(1, "RECIPIENTS").collect();
    // Handle ArgError::ArgumentMissing and ArgError::InvalidUnicode
    let recipients = recipients?;

    println!("verbose={verbose}");
    println!("subject={subject:?}");
    println!("recipients={recipients:?}");
    println!("attachments={attachments:?}");
    Ok(())
}

Example output

With -h and --help, the Usage goes to stdout:

» send_mail -h
-- stdout --
Usage: send_mail [OPTIONS..] RECIPIENT..
Options:
   -v   --verbose          Describe what's going on
   -a   --attach FILE      Attach this file
   -s   --subject TEXT     Subject: line
   -h   --help             Print this help

Without any arguments it complains to stderr:

» send_mail
-- stderr --
Error: missing argument: RECIPIENTS
Usage: send_mail [OPTIONS..] RECIPIENT..
Options:
   -v   --verbose          Describe what's going on
   -a   --attach FILE      Attach this file
   -s   --subject TEXT     Subject: line
   -h   --help             Print this help
-- exit status 1

Non-flag arguments are recipients, there must be at least 1:

» send_mail alice bob
-- stdout --
verbose=false
subject=None
recipients=["alice", "bob"]
attachments=[]

It notices "verbose":

» send_mail alice -v bob
-- stdout --
verbose=true
subject=None
recipients=["alice", "bob"]
attachments=[]

It works correctly if we bundle multiple flags:

» send_mail alice -vshello bob
-- stdout --
verbose=true
subject=Some("Hello")
recipients=["alice", "bob"]
attachments=[]