From 9d2d384b3ad001a4720f060dbac86f2b145a8edf Mon Sep 17 00:00:00 2001
From: Kevin K <kbknapp@gmail.com>
Date: Thu, 19 Mar 2015 17:55:13 -0400
Subject: [PATCH] Initial commit for better examples

---
 examples/{myapp.rs => 01_QuickExample.rs} |  0
 examples/02_Apps.rs                       | 23 ++++++++++
 examples/03_Args.rs                       | 53 +++++++++++++++++++++++
 3 files changed, 76 insertions(+)
 rename examples/{myapp.rs => 01_QuickExample.rs} (100%)
 create mode 100644 examples/02_Apps.rs
 create mode 100644 examples/03_Args.rs

diff --git a/examples/myapp.rs b/examples/01_QuickExample.rs
similarity index 100%
rename from examples/myapp.rs
rename to examples/01_QuickExample.rs
diff --git a/examples/02_Apps.rs b/examples/02_Apps.rs
new file mode 100644
index 00000000..2438f787
--- /dev/null
+++ b/examples/02_Apps.rs
@@ -0,0 +1,23 @@
+extern crate clap;
+
+use clap::{App};
+
+fn main() {
+
+    // Apps describe the top level application
+    //
+    // call .get_matches() last in order to 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.
+    //
+    // The options (version(), author(), about()) aren't mandatory, but recommended. There is another 
+    // option, usage(), which is an exception to the rule. This should only be used when the default
+    // usage string generated by clap doesn't suffice.
+    let matches = App::new("MyApp")
+                        .version("1.0")
+                        .author("Kevin K. <kbknapp@gmail.com>")
+                        .about("Does awesome things")
+                        .get_matches();
+     
+    // Continued program logic goes here...
+}
diff --git a/examples/03_Args.rs b/examples/03_Args.rs
new file mode 100644
index 00000000..4af8ce0d
--- /dev/null
+++ b/examples/03_Args.rs
@@ -0,0 +1,53 @@
+extern crate clap;
+
+use clap::{App, Arg};
+
+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
+    // special type of arguement, called SubCommands (which will be discussed seperately).
+    //
+    // Args are described in the same manner as Apps using the "builder pattern" with multiple
+    // methods describing various options for the individual arguments. 
+    //
+    // Arguments can be added to applications in two manners, one at a time with the arg() method,
+    // or multiple arguments at once via a Vec<Arg> inside the args() method.
+    //
+    // There are various options which can be set for a given argument, some apply to any of the
+    // three types of arguments, some only apply one or two of the types. *NOTE* if you set 
+    // incompatible options on a single argument, it will panic! at runtime. This is by design, so
+    // that you know right away an error was made. You only need to set the options you care about
+    // for each argument. 
+    //
+    // # Help and Version
+    // clap automatically generates a help and version flag for you, unless you specificy your
+    // own. By default help uses "-h" and "--help", and version uses "-v" and "--version". You can
+    // safely overide "-v" and "-h" to your own arguments, and "--help" and "--version" will stil
+    // be automatically generated for you.
+    let matches = App::new("MyApp")
+                        // All application settings go here...
+                        // A simple "Flag" argument (i.e. "-a")
+                        .arg(Arg::new("debug"))
+                        // A complex "Option" argument (i.e. one that takes a value) such as "-c some"
+                        .arg(Arg::new("config")                 // This name will be displayed with the help message
+                                                                // and is used to get runtime details of this argument
+                                    .help("sets a config file") // A short message displayed with the help message
+                                    .short("c")                 // Sets an argument trigger to "-c"
+                                    .long("config")             // Sets an argument trigger to "--config"
+                                    .takes_value(true)          // Specifies a value *MUST* accompany this argument
+                                                                // such as "-c some" (if you provided a short()) or 
+                                                                // "--config some" or "--config=some" (if you provided
+                                                                // a long())
+                                    .multiple(true)             // Allows multiple instances of this argument such as
+                                                                // "-c some -c other -c string"
+                                    .required(true)             // By default the user *MUST* use this argument
+                                    .requires("")
+                                    .requires_all()
+                                    .mutually_excludes()
+                                    .mutually_excludes_all()
+                            )
+                        .get_matches();
+     
+    // Continued program logic goes here...
+}