docs(Examples): adds better usage examples instead of having unused v…

…ariables

examples/02_apps.rs

@@ -2,7 +2,6 @@ extern crate clap;
 
 use clap::{App};
 
-#[allow(unused_variables)]
 fn main() {
     // Apps describe the top level application
     //
@@ -19,11 +18,11 @@ fn main() {
     // Once all options have been set, call .get_matches() in order to start the parsing and find all valid
     // command line arguments that supplied by the user at runtime. The name given to new() will be displayed
     // when the version or help flags are used.
-    let matches = App::new("MyApp")
-                        .version("1.0")
-                        .author("Kevin K. <kbknapp@gmail.com>")
-                        .about("Does awesome things")
-                        .get_matches();
+    App::new("MyApp")
+        .version("1.0")
+       .author("Kevin K. <kbknapp@gmail.com>")
+       .about("Does awesome things")
+       .get_matches();
 
     // This example doesn't do much, but it *does* give automatic -h, --help, -V, and --version functionality ;)
 

examples/03_args.rs

@@ -2,7 +2,6 @@ extern crate clap;
 
 use clap::{App, Arg};
 
-#[allow(unused_variables)]
 fn main() {
     // Args describe a possible valid argument which may be supplied by the user at runtime. There
     // are three different types of arguments (flags, options, and positional) as well as a fourth
@@ -39,6 +38,7 @@ fn main() {
                         .args( vec![
                             Arg::with_name("config")
                                     .help("sets the config file to use")
+                                    .takes_value(true)
                                     .short("c")
                                     .long("config"),
                             Arg::with_name("input")
@@ -61,5 +61,24 @@ fn main() {
                                           -i --int=[interface] 'Set an interface to use'")
                         .get_matches();
 
-    // Continued program logic goes here...
+    // Here are some examples of using the arguments defined above. Keep in mind that this is only
+    // an example, and may be somewhat contrived
+    //
+    // First we check if debugging should be on or not
+    println!("Debugging mode is: {}", if matches.is_present("debug") { "ON" } else { "OFF" });
+
+    // Next we print the config file we're using, if any was defined with either -c <file> or 
+    // --config <file>
+    if let Some(config) = matches.value_of("config") {
+        println!("A config file was passed in: {}", config);
+    }
+
+    // Let's print the <INPUT> file the user passed in. We can use .unwrap() here becase the arg is
+    // required, and parsing would have failed if the user forgot it
+    println!("Using input file: {}", matches.value_of("input").unwrap());
+
+    // We could continue checking for and using arguments in this manner, such as "license",
+    // "output", and "interface". Keep in mind that "output" and "interface" are optional, so you
+    // shouldn't call .unwrap(), instead prefer using an 'if let' expression as we did with 
+    // "config"
 }

examples/09_auto_version.rs

@@ -3,7 +3,6 @@ extern crate clap;
 
 use clap::App;
 
-#[allow(unused_variables)]
 fn main() {
     // You can have clap pull the application version directly from your Cargo.toml starting with
     // clap v0.4.14 on crates.io (or master#a81f915 on github). Using Rust's env! macro like this:
@@ -19,11 +18,11 @@ fn main() {
     // the version.
     //
     // Thanks to https://github.com/jhelwig for pointing this out
-    let matches = App::new("myapp")
-                      .about("does awesome things")
-                      // use crate_version! to pull the version number
-                      .version(&crate_version!()[..])
-                      .get_matches();
+    App::new("myapp")
+        .about("does awesome things")
+       // use crate_version! to pull the version number
+       .version(&crate_version!()[..])
+       .get_matches();
 
     // running the this app with the -V or --version will display whatever version is in your
     // Cargo.toml, the default being: myapp 0.0.1

examples/10_default_values.rs

@@ -2,7 +2,6 @@ extern crate clap;
 
 use clap::{App, Arg};
 
-#[allow(unused_variables)]
 fn main() {
     // You can get a "default value" like feature by using Option<T>'s .unwrap_or() method
     //
@@ -17,5 +16,6 @@ fn main() {
 
     let config_file = matches.value_of("CONFIG").unwrap_or("config.json");
 
-    // use config_file here...
+    // If the user passed in a -c <file> we'll see that value, if not we'll see 'config.json'
+    println!("The config file is: {}", config_file);
 }

examples/15_custom_validator.rs

@@ -2,7 +2,6 @@ extern crate clap;
 
 use clap::{App, Arg};
 
-#[allow(unused_variables)]
 fn main() {
     // You can define a function (or a closure) to use as a validator to argument values. The
     // function must accept a String and return Result<(), String> where Err(String) is the message
@@ -33,5 +32,6 @@ fn main() {
                                      }))
                         .get_matches();
 
-    // Continued program logic here...
+    // Here we can call .unwrap() because the argument is required.
+    println!("The .PNG file is: {}", matches.value_of("input").unwrap());
 }

examples/16_app_settings.rs

@@ -2,7 +2,6 @@ extern crate clap;
 
 use clap::{App, AppSettings, SubCommand};
 
-#[allow(unused_variables)]
 fn main() {
     // You can use AppSettings to change the application level behavior of clap. .setting() function
     // of App struct takes AppSettings enum as argument. There is also .settings() function which
@@ -20,13 +19,23 @@ fn main() {
                                             // Required positional argument called input.  This
                                             // will be only required if subcommand is not present.
 
-                        .subcommand(SubCommand::with_name("help")
-                                                .about("shows help message"))
+                        .subcommand(SubCommand::with_name("test")
+                                                .about("does some testing"))
                                             // if program is invoked with subcommand, you do not
                                             // need to specify the <input> argument anymore due to
                                             // the AppSettings::SubcommandsNegateReqs setting.
 
                         .get_matches();
 
-    // Contiued program logic goes here...
+    // Calling unwrap() on "input" would not be advised here, because although it's required,
+    // if the user uses a subcommand, those requirements are no longer required. Hence, we should
+    // use some sort of 'if let' construct
+    if let Some(inp) = matches.value_of("input") {
+        println!("The input file is: {}", inp);
+    }
+
+    match matches.subcommand() {
+        ("test", _) => println!("The 'test' subcommand was used"),
+        _           => unreachable!()
+    }
 }