Touch up the clap example

src/app.md

@@ -11,80 +11,92 @@
 [![clap-badge]][clap]
 
 ```rust
-// Argument parsing
 extern crate clap;
+
 use clap::{Arg, App};
 
 fn main() {
-
-    // Set command line arguments
+    // Define command line arguments.
     let matches = App::new("My Test Program")
-                           .version("0.0.1")
+        .version("0.1.0")
         .author("Hackerman Jones <hckrmnjones@hack.gov>")
         .about("Teaches argument parsing")
         .arg(Arg::with_name("file")
                  .short("f")
                  .long("file")
-                                .value_name("FILE")
-                                .help("A cool file")
-                                .takes_value(true))
-                           .arg(Arg::with_name("input_string")
-                                .short("i")
-                                .help("Your favorite phrase")
-                                .multiple(true)
                  .takes_value(true)
-                                .index(1))
-                           .arg(Arg::with_name("count")
-                                .short("c")
-                                .long("count")
+                 .help("A cool file"))
+        .arg(Arg::with_name("num")
+                 .short("n")
+                 .long("number")
                  .takes_value(true)
-                                .help("5 less than your favorite number"))
+                 .help("Five less than your favorite number"))
         .get_matches();
 
-    // Gets value for file, or defaults to 'input.txt'
+    // Get value for file, or default to 'input.txt'.
     let myfile = matches.value_of("file").unwrap_or("input.txt");
     println!("The file passed is: {}", myfile);
 
-    // Gets value for input string, simple unwrap is safe,
-    // as this arg was required
-    let mystring = matches.value_of("input_string").unwrap_or("");
-    println!("The string passed is: {}", mystring);
-
-    // Gets value for count, default to 0, then convert to int
-    let count_string = matches.value_of("count").unwrap_or("0");
-    let mut count = count_string.parse::<i32>().unwrap_or(0);
-
-    count += 5;
-
-    println!("The value of the number passed plus 5 is: {}", count);
+    // Get value for num if present, and try parsing it as i32.
+    let num_str = matches.value_of("num");
+    match num_str {
+        None => println!("No idea what your favorite number is."),
+        Some(s) => {
+            match s.parse::<i32>() {
+                Ok(n) => println!("Your favorite number must be {}.", n + 5),
+                Err(_) => println!("That's not a number! {}", s),
+            }
+        }
+    }
 }
 ```
 
-The purpose of this is to display the raw power of the clap library, an
-extensive command line argument parser for Rust. First, the user writes a
-description for their App, given a version, author, and about string.
+The `clap` crate is a simple-to-use, efficient, and full-featured library for
+parsing command line arguments and subcommands when writing console/terminal
+applications.
 
-The next step involves describing the args that clap can expect. 'with_name' is
-the option or argument descriptor that 'value_of' uses to get the value passed.
-'short' and 'long' sets the version to be passed with characters '-' and '--',
-respectively, through the command line. 'value_name' is simply cosmetic, and is
-NOT used in getting any actual values. 'help' allows the user to describe what
-the argument is used for or what the argument expects. If 'takes_value' is set
-to true, it will expect the argument to take a value, such as a string,
-filename, or number, as in the example above. For more examples of usage and a
-description of what clap is capable of, please visit their
-[wiki](https://kbknapp.github.io/clap-rs/clap/struct.App.html).
+The application can describe the structure of its command-line interface using
+`clap`'s builder style. The [documentation] gives two other possible ways to
+instantiate an application.
 
-We can test this program by running command similar to the following:
+[documentation]: https://docs.rs/clap/
+
+In the builder style, `with_name` is the unique identifier that `value_of` will
+use to retrieve the value passed. 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`.
+
+Usage information is generated by `clap`. The usage for the example application
+looks like this.
 
 ```
-cargo run -- -f myfile.txt -i "I <3 Rust!!!" --count 6
+My Test Program 0.1.0
+Hackerman Jones <hckrmnjones@hack.gov>
+Teaches argument parsing
+
+USAGE:
+    testing [OPTIONS]
+
+FLAGS:
+    -h, --help       Prints help information
+    -V, --version    Prints version information
+
+OPTIONS:
+    -f, --file <file>     A cool file
+    -n, --number <num>    Five less than your favorite number
 ```
 
+We can test the application by running a command like the following.
+
 ```
-> The file passed is: myfile.txt
-> The string passed is: I <3 Rust!!!
-> The value of the number passed plus 5 is: 11
+$ cargo run -- -f myfile.txt -n 251
+```
+
+The output is:
+
+```
+The file passed is: myfile.txt
+Your favorite number must be 256.
 ```
 
 <!-- Crates -->