diff --git a/src/app.md b/src/app.md index d383d0b..5179548 100644 --- a/src/app.md +++ b/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") - .author("Hackerman Jones ") - .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") - .takes_value(true) - .help("5 less than your favorite number")) - .get_matches(); + .version("0.1.0") + .author("Hackerman Jones ") + .about("Teaches argument parsing") + .arg(Arg::with_name("file") + .short("f") + .long("file") + .takes_value(true) + .help("A cool file")) + .arg(Arg::with_name("num") + .short("n") + .long("number") + .takes_value(true) + .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::().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::() { + 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 +Teaches argument parsing + +USAGE: + testing [OPTIONS] + +FLAGS: + -h, --help Prints help information + -V, --version Prints version information + +OPTIONS: + -f, --file A cool file + -n, --number 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. ```