From 6b9bd215c1cecfb2ca731ce92081806b7f02ad9d Mon Sep 17 00:00:00 2001
From: Kevin K <kbknapp@gmail.com>
Date: Sun, 18 Sep 2016 15:49:45 -0400
Subject: [PATCH] docs(Default Values): adds better examples on using default
 values

Closes #418
---
 examples/10_default_values.rs | 29 ++++++++++++++++++++++++-----
 src/args/arg.rs               | 19 +++++++++++++++++++
 2 files changed, 43 insertions(+), 5 deletions(-)

diff --git a/examples/10_default_values.rs b/examples/10_default_values.rs
index 8883a40785a..577d90b4d41 100644
--- a/examples/10_default_values.rs
+++ b/examples/10_default_values.rs
@@ -3,19 +3,38 @@ extern crate clap;
 use clap::{App, Arg};
 
 fn main() {
-    // You can get a "default value" like feature by using Option<T>'s .unwrap_or() method
+    // There are two ways in which to get a default value, one is to use claps Arg::default_value
+    // method, and the other is to use Rust's built in Option::unwrap_or method.
     //
-    // Let's assume you have -c <config> argument to allow users to specify a configuration file
-    // but you also want to support a default file, if none is specified.
+    // I'll demo both here.
+    //
+    // First, we'll use clap's Arg::default_value with an "INPUT" file.
     let matches = App::new("myapp").about("does awesome things")
+                        .arg(Arg::with_name("INPUT")
+                                .help("The input file to use") // Note, we don't need to specify
+                                                               // anything like, "Defaults to..."
+                                                               // because clap will automatically
+                                                               // generate that for us, and place
+                                                               // it in the help text
+                                .default_value("input.txt")
+                                .index(1))
+
+                        // Next we'll use the Option::unwrap_or method on this "CONFIG" option
                         .arg(Arg::with_name("CONFIG")
+                                // Note that we have to manaully include some verbage to the user
+                                // telling them what the default will be.
                                 .help("The config file to use (default is \"config.json\")")
                                 .short("c")
                                 .takes_value(true))
                         .get_matches();
 
+    // It's safe to call unwrap because the value with either be what the user input at runtime
+    // or "input.txt"
+    let input = matches.value_of("INPUT").unwrap();
+
+    // Using Option::unwrap_or we get the same affect, but without the added help text injection
     let config_file = matches.value_of("CONFIG").unwrap_or("config.json");
 
-    // If the user passed in a -c <file> we'll see that value, if not we'll see 'config.json'
+    println!("The input file is: {}", input);
     println!("The config file is: {}", config_file);
-}
\ No newline at end of file
+}
diff --git a/src/args/arg.rs b/src/args/arg.rs
index 9cf9784c0cf..3901e033522 100644
--- a/src/args/arg.rs
+++ b/src/args/arg.rs
@@ -2186,6 +2186,8 @@ impl<'a, 'b> Arg<'a, 'b> {
     ///
     /// # Examples
     ///
+    /// First we use the default value without providing any value at runtime.
+    ///
     /// ```rust
     /// # use clap::{App, Arg};
     /// let m = App::new("defvals")
@@ -2200,6 +2202,23 @@ impl<'a, 'b> Arg<'a, 'b> {
     /// assert!(m.is_present("opt"));
     /// assert_eq!(m.occurrences_of("opt"), 0);
     /// ```
+    ///
+    /// Next we provide a valu at runtime to override the default.
+    ///
+    /// ```rust
+    /// # use clap::{App, Arg};
+    /// let m = App::new("defvals")
+    ///     .arg(Arg::with_name("opt")
+    ///         .long("myopt")
+    ///         .default_value("myval"))
+    ///     .get_matches_from(vec![
+    ///         "defvals", "--myopt=non_default"
+    ///     ]);
+    ///
+    /// assert_eq!(m.value_of("opt"), Some("non_default"));
+    /// assert!(m.is_present("opt"));
+    /// assert_eq!(m.occurrences_of("opt"), 1);
+    /// ```
     /// [`ArgMatches::occurrences_of`]: /struct.ArgMatches.html#method.occurrences_of
     /// [`ArgMatches::value_of`]: ./struct.ArgMatches.html#method.value_of
     /// [`Arg::takes_value(true)`]: /struct.Arg.html#method.takes_value