From 07f6d63e173b0e0a6819e3554f5c335cda382a1e Mon Sep 17 00:00:00 2001 From: Kevin K Date: Wed, 9 Sep 2015 00:00:17 -0400 Subject: [PATCH] chore: increase version --- CHANGELOG.md | 13 ++++++++++ Cargo.toml | 2 +- README.md | 71 ++++++++++++++++++++++++++++++++++++++++++++++----- src/macros.rs | 6 ++++- 4 files changed, 83 insertions(+), 9 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a73677c1b7d..65bd29f1eea 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,16 @@ + +## 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)) + + + ### v1.3.2 (2015-09-08) diff --git a/Cargo.toml b/Cargo.toml index 6e1d8cd320d..7fff8d19686 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,7 +1,7 @@ [package] name = "clap" -version = "1.3.2" +version = "1.4.0" authors = ["Kevin K. "] exclude = ["examples/*", "clap-tests/*", "tests/*", "benches/*", "clap.png"] description = "A simple to use, efficient, and full featured Command Line Argument Parser" diff --git a/README.md b/README.md index e2c8cee3ab8..eb408dda497 100644 --- a/README.md +++ b/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. ") + (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. ") + (@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 diff --git a/src/macros.rs b/src/macros.rs index 50d4d0f6a06..65def20fa3e 100644 --- a/src/macros.rs +++ b/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