docs: updates examples for 2x release

Closes #394

examples/01a_quick_example.rs

@@ -36,12 +36,12 @@ fn main() {
                         .version("1.0")
                         .author("Kevin K. <[email protected]>")
                         .about("Does awesome things")
-                        .args_from_usage("-c --config=[conf] 'Sets a custom config file'
-                                         [output] 'Sets an optional output file'
-                                         [debug]... -d 'Turn debugging information on'")
+                        .args_from_usage("-c, --config=[FILE] 'Sets a custom config file'
+                                         <output> 'Sets an optional output file'
+                                         -d... 'Turn debugging information on'")
                         .subcommand(SubCommand::with_name("test")
                                                 .about("does testing things")
-                                                .arg_from_usage("[list] -l 'lists test values'"))
+                                                .arg_from_usage("-l, --list 'lists test values'"))
                         .get_matches();
 
     // You can check the value provided by positional arguments, or option arguments
@@ -55,7 +55,7 @@ fn main() {
 
     // You can see how many times a particular flag or argument occurred
     // Note, only flags can have multiple occurrences
-    match matches.occurrences_of("debug") {
+    match matches.occurrences_of("d") {
         0 => println!("Debug mode is off"),
         1 => println!("Debug mode is kind of on"),
         2 => println!("Debug mode is on"),

examples/01b_quick_example.rs

@@ -41,6 +41,7 @@ fn main() {
                         .arg(Arg::with_name("config")
                                     .short("c")
                                     .long("config")
+                                    .value_name("FILE")
                                     .help("Sets a custom config file")
                                     .takes_value(true))
                         .arg(Arg::with_name("output")

examples/02_apps.rs

@@ -15,9 +15,9 @@ fn main() {
     // and args_from_usage() (as well as subcommands via the subcommand() and subcommands() methods) which
     // will be covered later.
     //
-    // 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.
+    // Once all options have been set, call one of the .get_matches* family of methods 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.
     App::new("MyApp")
         .version("1.0")
         .author("Kevin K. <[email protected]>")

examples/03_args.rs

@@ -58,7 +58,7 @@ fn main() {
 
                         // Two args, one "Positional", and one "Option" using a usage string
                         .args_from_usage("[output] 'Supply an output file to use'
-                                          -i --int=[interface] 'Set an interface to use'")
+                                          -i, --int=[IFACE] 'Set an interface to use'")
                         .get_matches();
 
     // Here are some examples of using the arguments defined above. Keep in mind that this is only

examples/09_auto_version.rs

@@ -21,7 +21,7 @@ fn main() {
     App::new("myapp")
         .about("does awesome things")
        // use crate_version! to pull the version number
-       .version(&crate_version!()[..])
+       .version(crate_version!())
        .get_matches();
 
     // running the this app with the -V or --version will display whatever version is in your

examples/11_only_specific_values.rs

@@ -12,12 +12,11 @@ fn main() {
     //
     // For this example, assume you want one positional argument of either "fast" or "slow"
     // i.e. the only possible ways to run the program are "myprog fast" or "myprog slow"
-    let mode_vals = ["fast", "slow"];
     let matches = App::new("myapp").about("does awesome things")
                         .arg(Arg::with_name("MODE")
                                 .help("What mode to run the program in")
                                 .index(1)
-                                .possible_values(&mode_vals)
+                                .possible_values(&["fast", "slow"])
                                 .required(true))
                         .get_matches();
 
@@ -31,4 +30,4 @@ fn main() {
         },
         _      => unreachable!()
     }
-}
+}

examples/13b_enum_values_manual.rs

@@ -35,12 +35,11 @@ impl FromStr for Vals {
 
 fn main() {
     // Create the application like normal
-    let enum_vals = ["Foo", "Bar", "Baz", "Qux"];
     let m = App::new("myapp")
                     // Use a single positional argument that is required
                     .arg(Arg::from_usage("<type> 'The type to use'")
                             // Define the list of possible values
-                            .possible_values(&enum_vals))
+                            .possible_values(&["Foo", "Bar", "Baz", "Qux"]))
                     .get_matches();
 
     let t = value_t!(m, "type", Vals).unwrap_or_else(|e| e.exit());

examples/14_groups.rs

@@ -39,11 +39,16 @@ fn main() {
                                           .args(&["ver", "major", "minor", "patch"]))
                       // Arguments can also be added to a group individually, these two arguments
                       // are part of the "input" group which is not required
-                      .arg(Arg::from_usage("[INPUT_FILE] 'some regular input'").group("input"))
-                      .arg(Arg::from_usage("--spec-in [SPEC_IN] 'some special input argument'").group("input"))
+                      .arg(Arg::from_usage("[INPUT_FILE] 'some regular input'")
+                        .group("input"))
+                      .arg(Arg::from_usage("--spec-in [SPEC_IN] 'some special input argument'")
+                        .group("input"))
                       // Now let's assume we have a -c [config] argument which requires one of
                       // (but **not** both) the "input" arguments
-                      .arg(Arg::with_name("config").short("c").takes_value(true).requires("input"))
+                      .arg(Arg::with_name("config")
+                        .short("c")
+                        .takes_value(true)
+                        .requires("input"))
                       .get_matches();
 
     // Let's assume the old version 1.2.3
@@ -79,4 +84,4 @@ fn main() {
     }
 
 
-}
+}

examples/15_custom_validator.rs

@@ -13,25 +13,25 @@ fn main() {
                                      .help("the input file to use")
                                      .index(1)
                                      .required(true)
-
-                                     .validator(|val| {
-                                         // val is the argument value passed in by the user
-                                         // val has type of String.
-
-                                         if val.ends_with(".png") {
-                                             Ok(())
-                                         } else {
-                                             // clap automatically adds "error: " to the beginning
-                                             // of the message.
-                                             Err(String::from("the file format must be png."))
-                                         }
-
-                                         // Of course, you can do more complicated validation as
-                                         // well, but for the simplicity, this example only checks
-                                         // if the value passed in ends with ".png" or not.
-                                     }))
+                                     // You can pass in a closure, or a function
+                                     .validator(is_png))
                         .get_matches();
 
     // Here we can call .unwrap() because the argument is required.
     println!("The .PNG file is: {}", matches.value_of("input").unwrap());
 }
+
+fn is_png(val: String) -> Result<(), String> {
+    // val is the argument value passed in by the user
+    // val has type of String.
+    if val.ends_with(".png") {
+        Ok(())
+    } else {
+        // clap automatically adds "error: " to the beginning
+        // of the message.
+        Err(String::from("the file format must be png."))
+    }
+    // Of course, you can do more complicated validation as
+    // well, but for the simplicity, this example only checks
+    // if the value passed in ends with ".png" or not.
+}