Merge pull request #241 from kbknapp/incver

chore: increase version

CHANGELOG.md

@@ -1,3 +1,16 @@
+<a name="v1.4.0"></a>
+## v1.4.0 (2015-09-09)
+
+
+#### Features
+
+*   allows printing help message by library consumers ([56b95f32](https://github.com/kbknapp/clap-rs/commit/56b95f320875c62dda82cb91b29059671e120ed1))
+*   allows defining hidden args and subcmds ([2cab4d03](https://github.com/kbknapp/clap-rs/commit/2cab4d0334ea3c2439a1d4bfca5bf9905c7ea9ac), closes [#231](https://github.com/kbknapp/clap-rs/issues/231))
+*   Builder macro to assist with App/Arg/Group/SubCommand building ([443841b0](https://github.com/kbknapp/clap-rs/commit/443841b012a8d795cd5c2bd69ae6e23ef9b16477))
+* **Errors:**  allows consumers to write to stderr and exit on error ([1e6403b6](https://github.com/kbknapp/clap-rs/commit/1e6403b6a863574fa3cb6946b1fb58f034e8664c))
+
+
+
 <a name="v1.3.2"></a>
 ### v1.3.2 (2015-09-08)
 

Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 
 name = "clap"
-version = "1.3.2"
+version = "1.4.0"
 authors = ["Kevin K. <kbknapp@gmail.com>"]
 exclude = ["examples/*", "clap-tests/*", "tests/*", "benches/*", "clap.png"]
 description = "A simple to use, efficient, and full featured  Command Line Argument Parser"

README.md

@@ -8,13 +8,12 @@ It is a simple to use, efficient, and full featured library for parsing command
 
 ## What's New
 
-If you're already familiar with `clap` but just want to see some new highlights as of **1.3.2**
+If you're already familiar with `clap` but just want to see some new highlights as of **1.4.0**
 
-* Code Coverage has now been added, and is slowly going up (See the badge at the top of this page)! Thanks to [Vinatorul](https://github.com/vinatorul) for the leg work!
-* You can now call `get_matches_*` to *not* consume the `App` struct (See those ending in `_borrow`)
-* You can now handle get a `Result` from the `get_matches_*` methods in order to handle errors if you so choose (see those ending in `_safe`)
-* You can now **build a CLI from YAML** - This keeps your Rust source nice and tidy :) Full details can be found in [examples/17_yaml.rs](https://github.com/kbknapp/clap-rs/blob/master/examples/17_yaml.rs)
-* A very minor "breaking" change which should affect very, very few people. If you're using `ArgGroup::*_all`, they no longer take a `Vec<&str>`, but now takes a far more versatile `&[&str]`. If you were using code such as `.add_all(vec!["arg1", "arg2"])` you only need to change the `vec!`->`&` and it should work again. This also has the added benefit of not needlessly allocating the `Vec`!
+* A new macro has been designed by [james-darkfox](https://github.com/james-darkfox) to give the simplicity of `from_usage` methods, but the performance of the Builder Pattern. Huge thanks to him! Fair warning this is very new, and may still have some kinks and tweaks left as we experiment ;)
+* Users can now print the help message programatically using `App::write_help(io::Write)` and `App::print_help()`.
+* Users can now simply print the error message to `stderr` and exit gracefully programmatically using `ClapError::exit()`
+* You can now get argument matches **without** consuming your `App` struct using `App::get_matches_from_safe_borrow()`
 * Some other minor bug fixes and improvements
 
 For full details see the [changelog](https://github.com/kbknapp/clap-rs/blob/master/CHANGELOG.md)
@@ -73,7 +72,7 @@ Below are a few of the features which `clap` supports, full descriptions and usa
 
 ## Quick Example
 
-The following two examples show a quick example of some of the very basic functionality of `clap`. For more advanced usage, such as requirements, exclusions, groups, multiple values and occurrences see the [video tutorials](https://www.youtube.com/playlist?list=PLza5oFLQGTl0Bc_EU_pBNcX-rhVqDTRxv), [documentation](http://kbknapp.github.io/clap-rs/clap/index.html), or `examples/` directory of this repository.
+The following examples show a quick example of some of the very basic functionality of `clap`. For more advanced usage, such as requirements, exclusions, groups, multiple values and occurrences see the [video tutorials](https://www.youtube.com/playlist?list=PLza5oFLQGTl0Bc_EU_pBNcX-rhVqDTRxv), [documentation](http://kbknapp.github.io/clap-rs/clap/index.html), or `examples/` directory of this repository.
 
  *NOTE:* All these examples are functionally the same, but show three different styles in which to use `clap`
 
@@ -201,6 +200,64 @@ fn main() {
 }
 ```
 
+The following combines the previous two examples by using the simplicity of the `from_usage` methods and the performance of the Builder Pattern.
+
+```rust
+// (Full example with detailed comments in examples/01c_QuickExample.rs)
+//
+// This example demonstrates clap's "usage strings" method of creating arguments which is less
+// less verbose
+#[macro_use]
+extern crate clap;
+use clap::{Arg, App, SubCommand};
+
+fn main() {
+    let matches = clap_app!(myapp =>
+        (version: "1.0")
+        (author: "Kevin K. <kbknapp@gmail.com>")
+        (about: "Does awesome things")
+        (@arg CONFIG: -c --config +takes_value "Sets a custom config file")
+        (@arg INPUT: +required "Sets the input file to use")
+        (@arg debug: -d ... "Sets the level of debugging information")
+        (@subcommand test =>
+            (about: "controls testing features")
+            (version: "1.3")
+            (author: "Someone E. <someone_else@other.com>")
+            (@arg verbose: -v --verbose "Print test information verbosely")
+        )
+    ).get_matches();
+
+    // Calling .unwrap() is safe here because "INPUT" is required (if "INPUT" wasn't
+    // required we could have used an 'if let' to conditionally get the value)
+    println!("Using input file: {}", matches.value_of("INPUT").unwrap());
+
+    // Gets a value for config if supplied by user, or defaults to "default.conf"
+    let config = matches.value_of("CONFIG").unwrap_or("default.conf");
+    println!("Value for config: {}", config);
+
+    // Vary the output based on how many times the user used the "debug" flag
+    // (i.e. 'myapp -d -d -d' or 'myapp -ddd' vs 'myapp -d'
+    match matches.occurrences_of("debug") {
+        0 => println!("Debug mode is off"),
+        1 => println!("Debug mode is kind of on"),
+        2 => println!("Debug mode is on"),
+        3 | _ => println!("Don't be crazy"),
+    }
+
+    // You can information about subcommands by requesting their matches by name
+    // (as below), requesting just the name used, or both at the same time
+    if let Some(matches) = matches.subcommand_matches("test") {
+        if matches.is_present("verbose") {
+            println!("Printing verbosely...");
+        } else {
+            println!("Printing normally...");
+        }
+    }
+
+    // more porgram logic goes here...
+}
+```
+
 This final method shows how you can use a YAML file to build your CLI and keep your Rust source tidy. First, create the `cli.yml` file to hold your CLI options, but it could be called anything we like (we'll use the same both examples above to keep it functionally equivilant):
 
 ```yaml

src/macros.rs

@@ -777,7 +777,11 @@ macro_rules! clap_app {
     };
     // Yaml like function calls - used for setting varous meta directly against the app
     (@app ($builder:expr) ($ident:ident: $($v:expr),*) $($tt:tt)*) => {
-        clap_app!{ @app ($builder.$ident($($v),*)) $($tt)* }
+        // clap_app!{ @app ($builder.$ident($($v),*)) $($tt)* }
+        clap_app!{ @app
+            ($builder.$ident($($v),*))
+            $($tt)*
+        }
     };
 
     // Add members to group and continue argument handling with the parent builder