CSCI 241 Systems Programming Labs

Let’s look at an example.

extern crate clap;
use std::path::PathBuf;

use clap::Parser;

#[derive(Parser, Debug)]
#[command(author, version, about = "Example command line parsing", long_about = None)]
struct Config {
    /// Use colored output
    #[arg(short, long)]
    color: bool,

    /// Use at most COUNT values
    #[arg(short = 'C', long)]
    count: Option<i32>,

    /// Specify optional log file
    #[arg(short = 'f', long, conflicts_with = "count")]
    log_file: Option<PathBuf>,

    /// Input files
    #[arg(default_value = "-")]
    files: Vec<PathBuf>,
}

fn main() {
    let config = Config::parse();
    println!("{config:#?}");
}

There’s a lot going on here! At the top of the code, there are two use statements which inform the compiler about PathBuf from the standard library and Parser from clap.

Next we have a struct named Config. This structure defines the supported command line arguments of this example program. The main function calls the function Config::parse() which parses all of the command line arguments and crucially, returns an instance of Config with the structure’s members. We can access the members as config.color, config.count, config.log_file, and config.files.

The println!("{config:#?}") line will pretty-print the debug representation of config. The format specifier {config:?} (with the colon followed by a question mark) means to print the debug representation and the # in {config:#?} means to pretty-print it with new lines.

All good command line utilities have a --help option or similar. Before we look at this code in detail, here’s the output of running this program with the --help option which just prints out the help message and then exits the program.

$ cargo run -- --help
Example command line parsing

Usage: ex [OPTIONS] [FILES]...

Arguments:
  [FILES]...  Input files [default: -]

Options:
  -c, --color                Use colored output
  -C, --count <COUNT>        Use at most COUNT values
  -f, --log-file <LOG_FILE>  Specify optional log file
  -h, --help                 Print help
  -V, --version              Print version

This code defines three options, each of which has a short and a long form. Two of the options take arguments and two of the options conflict with one another meaning at most one of those options can be specified at a time. It also takes a list of file paths. Each file path is represented by a PathBuf in Rust.

Because the final line of code prints out the Config instance that was returned from Config::parse(), we can run the program a few times with different options to see the results. Note that in what follows I’m passing the --quiet option to cargo run because I don’t want cargo to print out any output like “Created binary …” As usual, the argument before the -- go to cargo run, the arguments after the -- go to the program itself.

$ cargo run --quiet --
Config {
    color: false,
    count: None,
    log_file: None,
    files: [
        "-",
    ],
}

$ cargo run --quiet -- --color -f log.txt input1.txt input2.txt
Config {
    color: true,
    count: None,
    log_file: Some(
        "log.txt",
    ),
    files: [
        "input1.txt",
        "input2.txt",
    ],
}

$ cargo run --quiet -- --version  
ex 0.1.0

$  cargo run --quiet -- -f log.txt -C 10
error: the argument '--log-file <LOG_FILE>' cannot be used with '--count <COUNT>'

Usage: ex --log-file <LOG_FILE> [FILES]...

For more information, try '--help'.

The definition of Config starts by deriving the clap::Parser and Debug traits. The Parser trait is what provides the parse() function which reads the command-line arguments and returns an instance of Config.

The next line

#[command(author, version, about = "Example command line parsing", long_about = None)]

is new. It is attaching metadata to the Config struct that the clap library will use to do all of the argument parsing and producing usage and error messages. The about = "..." lets us specify a short about message to appear in the --help message.

Each of the arguments consists of three parts.

    /// Use colored output
    #[arg(short, long)]
    color: bool,

The comment with three slashes is a doc comment. Normally, such a comment is used to write documentation. (Running cargo doc produces HTML documentation of your code. The doc comments are where the documentation comes from.) Clap is repurposing that doc comment to construct a --help message.

The next line, #[arg(short, long)], is attaching some more metadata for Clap. It says this should have a short option -c and a long option --color. It took both option names from the name of the variable color itself. Note that we can be explict about what the option names are. There are a variety of other things we can do including making options conflict. If we try to pass both -f and -C, we’ll get an error from Clap.

The third line is the variable and its type, of course. Because the type of color is bool, this acts as an on/off flag. For other types, using an Option<...> indicates that the argument is optional. If you want to allow 0 or more, you use a Vec rather than an Option as I did for files.