Auto merge of #660 - kbknapp:issue-588, r=kbknapp

Issue 588

CHANGELOG.md

@@ -1,3 +1,36 @@
+<a name="v2.12.0"></a>
+## v2.12.0 (2016-09-13)
+
+
+#### Features
+
+* **Help:**  adds ability to hide the possible values on a per argument basis ([9151ef73](https://github.com/kbknapp/clap-rs/commit/9151ef739871f2e74910c342299c0de196b95dec), closes [#640](https://github.com/kbknapp/clap-rs/issues/640))
+* **help:**  allow for limiting detected terminal width ([a43e28af](https://github.com/kbknapp/clap-rs/commit/a43e28af85c9a9deaedd5ef735f4f13008daab29), closes [#653](https://github.com/kbknapp/clap-rs/issues/653))
+
+#### Documentation
+
+* **Help Wrapping:**  removes the verbage about using `'{n}'` to insert newlines in help text ([c5a2b352](https://github.com/kbknapp/clap-rs/commit/c5a2b352ca600f5b802290ad945731066cd53611))
+* **Value Delimiters:**  updates the docs for the Arg::multiple method WRT value delimiters and default settings ([f9d17a06](https://github.com/kbknapp/clap-rs/commit/f9d17a060aa53f10d0a6e1a7eed5d989d1a59533))
+* **appsettings:**  Document AppSetting::DisableVersion ([94501965](https://github.com/kbknapp/clap-rs/commit/945019654d2ca67eb2b1d6014fdf80b84d528d30), closes [#589](https://github.com/kbknapp/clap-rs/issues/589))
+
+#### Bug Fixes
+
+* **AllowLeadingHyphen:**  fixes a bug where valid args aren't recognized with this setting ([a9699e4d](https://github.com/kbknapp/clap-rs/commit/a9699e4d7cdc9a06e73b845933ff1fe6d76f016a), closes [#588](https://github.com/kbknapp/clap-rs/issues/588))
+
+#### Improvements
+
+* **Help Wrapping:**
+  *  clap now ignores hard newlines in help messages and properly re-aligns text, but still wraps if the term width is too small ([c7678523](https://github.com/kbknapp/clap-rs/commit/c76785239fd42adc8ca04f9202b6fec615aa9f14), closes [#617](https://github.com/kbknapp/clap-rs/issues/617))
+  *  makes some minor changes to when next line help is automatically used ([01cae799](https://github.com/kbknapp/clap-rs/commit/01cae7990a33167ac35103fb36c811b4fe6eb98f))
+* **Value Delimiters:**  changes the default value delimiter rules ([f9e69254](https://github.com/kbknapp/clap-rs/commit/f9e692548e8c94de15f909432de301407d6bb834), closes [#655](https://github.com/kbknapp/clap-rs/issues/655))
+* **YAML:**  supports setting Arg::require_delimiter from YAML ([b9b55a39](https://github.com/kbknapp/clap-rs/commit/b9b55a39dfebcdbdc05dca2692927e503db50816))
+
+#### Performance
+
+* **help:**  fix redundant contains() checks ([a8afed74](https://github.com/kbknapp/clap-rs/commit/a8afed7428bf0733f8e93bb11ad6c00d9e970fcc))
+
+
+
 <a name="v2.11.3"></a>
 ### v2.11.3 (2016-09-07)
 

Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 
 name = "clap"
-version = "2.11.3"
+version = "2.12.0"
 authors = ["Kevin K. <[email protected]>"]
 exclude = ["examples/*", "clap-test/*", "tests/*", "benches/*", "*.png", "clap-perf/*", "*.dot"]
 repository = "https://github.com/kbknapp/clap-rs.git"

README.md

@@ -39,38 +39,53 @@ Created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc)
 
 ## What's New
 
+Here's the highlights for v2.12.0
+
+* Changes the default value delimiter rules (i.e. the default is `use_delimiter(false)` *unless* a setting/method that implies multiple values was used) **[Bugfix that *may* "break" code]**
+ * If code breaks, simply add `Arg::use_delimiter(true)` to the affected args
+* Updates the docs for the `Arg::multiple` method WRT value delimiters and default settings
+* Adds ability to hide the possible values from the help text on a per argument basis, instead of command wide
+* Allows for limiting detected terminal width (i.e. wrap at `x` length, unless the terminal width is *smaller*)
+* Removes some redundant `contains()` checks for minor performance improvements
+* Fixes a bug where valid args aren't recognized with the `AppSettings::AllowLeadingHyphen` setting
+* `clap` now ignores hard newlines in help messages and properly re-aligns text, but still wraps if the term width is too small
+* Makes some minor changes to when next line help is automatically used
+* Adds support for the setting `Arg::require_delimiter` from YAML
+* Removes the verbage about using `'{n}'` to insert newlines in help text from the docs (the normal `\n` can now be used)
+* Documents `AppSetting::DisableVersion`
+
 Here's the highlights for v2.11.3
 
 * `clap` no longer requires one to use `{n}` inside help text to insert a newline that is properly aligned. One can now use the normal `\n`.
-* `clap` now ignores hard newlines in help messages and properly re-aligns text, but still wraps if the term width is too small 
-* Supports setting `Arg::require_delimiter` from YAML 
+* `clap` now ignores hard newlines in help messages and properly re-aligns text, but still wraps if the term width is too small
+* Supports setting `Arg::require_delimiter` from YAML
 
 Here's the highlights for v2.11.2
 
 * Makes some minor changes to when next line help is automatically used for improved wrapping
 
 Here's the highlights for v2.11.1
 
-* Fixes an issue where settings weren't propogated down through grand-child subcommands 
-* Errors can now have custom description 
+* Fixes an issue where settings weren't propogated down through grand-child subcommands
+* Errors can now have custom description
 * Uses `term_size` instead of home-grown solution on Windows
 * Updates deps with some minor bug fixes
 
 
 Here's the highlights for v2.11.0
 
 * Adds the ability to wrap help text intelligently on Windows!
-* Moves docs to [docs.rs!](https://docs.rs/clap/) 
-* Fixes some usage strings that contain both args in groups and ones that conflict with each other 
-* Uses standard conventions for bash completion files, namely `{bin}.bash-completion` 
-* Automatically moves help text to the next line and wraps when term width is determined to be too small, or help text is too long 
-* Vastly improves *development* error messages when using YAML 
-* Adds `App::with_defaults` to automatically use `crate_authors!` and `crate_version!` macros 
+* Moves docs to [docs.rs!](https://docs.rs/clap/)
+* Fixes some usage strings that contain both args in groups and ones that conflict with each other
+* Uses standard conventions for bash completion files, namely `{bin}.bash-completion`
+* Automatically moves help text to the next line and wraps when term width is determined to be too small, or help text is too long
+* Vastly improves *development* error messages when using YAML
+* Adds `App::with_defaults` to automatically use `crate_authors!` and `crate_version!` macros
 * Other minor improvements and bug fixes
 
 Here's the highlights for v2.10.4
 
-* Fixes a bug where help is wrapped incorrectly and causing a panic with some non-English characters 
+* Fixes a bug where help is wrapped incorrectly and causing a panic with some non-English characters
 
 Here's the highlights for v2.10.3
 
@@ -301,18 +316,17 @@ Below are a few of the features which `clap` supports, full descriptions and usa
 * **Confliction Rules**: Arguments can optionally define the following types of exclusion rules
   - Can be disallowed when certain arguments are present
   - Can disallow use of other arguments when present
-* **POSIX Override Rules**: Arguments can define rules to support POSIX overriding
 * **Groups**: Arguments can be made part of a group
   - Fully compatible with other relational rules (requirements, conflicts, and overrides) which allows things like requiring the use of any arg in a group, or denying the use of an entire group conditionally
 * **Specific Value Sets**: Positional or Option Arguments can define a specific set of allowed values (i.e. imagine a `--mode` option which may *only* have one of two values `fast` or `slow` such as `--mode fast` or `--mode slow`)
-* **Default Values**: Although not specifically provided by `clap` you can achieve this exact functionality from Rust's `Option<&str>.unwrap_or("some default")` method (or `Result<T,String>.unwrap_or(T)` when using typed values)
+* **Default Values**
 * **Automatic Version from Cargo.toml**: `clap` is fully compatible with Rust's `env!()` macro for automatically setting the version of your application to the version in your Cargo.toml. See [09_auto_version example](examples/09_auto_version.rs) for how to do this (Thanks to [jhelwig](https://github.com/jhelwig) for pointing this out)
 * **Typed Values**: You can use several convenience macros provided by `clap` to get typed values (i.e. `i32`, `u8`, etc.) from positional or option arguments so long as the type you request implements `std::str::FromStr` See the [12_typed_values example](examples/12_typed_values.rs). You can also use `clap`s `arg_enum!` macro to create an enum with variants that automatically implement `std::str::FromStr`. See [13a_enum_values_automatic example](examples/13a_enum_values_automatic.rs) for details
 * **Suggestions**: Suggests corrections when the user enters a typo. For example, if you defined a `--myoption` argument, and the user mistakenly typed `--moyption` (notice `y` and `o` transposed), they would receive a `Did you mean '--myoption'?` error and exit gracefully. This also works for subcommands and flags. (Thanks to [Byron](https://github.com/Byron) for the implementation) (This feature can optionally be disabled, see 'Optional Dependencies / Features')
 * **Colorized Errors (Non Windows OS only)**: Error message are printed in in colored text (this feature can optionally be disabled, see 'Optional Dependencies / Features').
 * **Global Arguments**: Arguments can optionally be defined once, and be available to all child subcommands.
 * **Custom Validations**: You can define a function to use as a validator of argument values. Imagine defining a function to validate IP addresses, or fail parsing upon error. This means your application logic can be solely focused on *using* values.
-* **POSIX Compatible Conflicts** - In POSIX args can be conflicting, but not fail parsing because whichever arg comes *last* "wins" so to speak. This allows things such as aliases (i.e. `alias ls='ls -l'` but then using `ls -C` in your terminal which ends up passing `ls -l -C` as the final arguments. Since `-l` and `-C` aren't compatible, this effectively runs `ls -C` in `clap` if you choose...`clap` also supports hard conflicts that fail parsing). (Thanks to [Vinatorul](https://github.com/Vinatorul)!)
+* **POSIX Compatible Conflicts/Overrides** - In POSIX args can be conflicting, but not fail parsing because whichever arg comes *last* "wins" so to speak. This allows things such as aliases (i.e. `alias ls='ls -l'` but then using `ls -C` in your terminal which ends up passing `ls -l -C` as the final arguments. Since `-l` and `-C` aren't compatible, this effectively runs `ls -C` in `clap` if you choose...`clap` also supports hard conflicts that fail parsing). (Thanks to [Vinatorul](https://github.com/Vinatorul)!)
 * Supports the Unix `--` meaning, only positional arguments follow
 
 ## Quick Example

src/app/help.rs

@@ -605,7 +605,7 @@ impl<'a> Help<'a> {
 
     /// Writes help for subcommands of a Parser Object to the wrapped stream.
     fn write_subcommands(&mut self, parser: &Parser) -> io::Result<()> {
-        debugln!("exec=write_subcommands;");
+        debugln!("fn=write_subcommands;");
         let mut longest = 0;
 
         let mut ord_m = VecMap::new();

src/app/macros.rs

@@ -88,6 +88,7 @@ macro_rules! _handle_group_reqs{
             } else {
                 false
             };
+            debugln!("iter;grp={};found={:?}", grp.name, found);
             if found {
                 vec_remove_all!($me.required, &grp.args);
                 debugln!("Adding args from group to blacklist...{:?}", grp.args);

src/app/parser.rs

@@ -439,7 +439,7 @@ impl<'a, 'b> Parser<'a, 'b>
     }
 
     pub fn needs_flags_tag(&self) -> bool {
-        debugln!("exec=needs_flags_tag;");
+        debugln!("fn=needs_flags_tag;");
         'outer: for f in &self.flags {
             debugln!("iter;f={};", f.name);
             if let Some(l) = f.long {
@@ -753,7 +753,7 @@ impl<'a, 'b> Parser<'a, 'b>
                     name: sc_name,
                     matches: sc_m.into(),
                 });
-            } else {
+            } else if !self.settings.is_set(AppSettings::AllowLeadingHyphen) {
                 return Err(Error::unknown_argument(&*arg_os.to_string_lossy(),
                                                    "",
                                                    &*self.create_current_usage(matcher),
@@ -763,7 +763,10 @@ impl<'a, 'b> Parser<'a, 'b>
 
         let mut reqs_validated = false;
         if let Some(a) = needs_val_of {
+            debugln!("needs_val_of={}", a);
+            debug!("Is this an opt...");
             if let Some(o) = self.opts.iter().find(|o| &o.name == &a) {
+                sdebugln!("Yes");
                 try!(self.validate_required(matcher));
                 reqs_validated = true;
                 let should_err = if let Some(v) = matcher.0.args.get(&*o.name) {
@@ -777,6 +780,8 @@ impl<'a, 'b> Parser<'a, 'b>
                                                   self.color()));
                 }
             } else {
+                sdebugln!("No");
+                debugln!("Returning Error::empty_value");
                 return Err(Error::empty_value(self.positionals
                                                   .values()
                                                   .find(|p| &p.name == &a)
@@ -846,15 +851,15 @@ impl<'a, 'b> Parser<'a, 'b>
     }
 
     fn propogate_help_version(&mut self) {
-        debugln!("exec=propogate_help_version;");
+        debugln!("fn=propogate_help_version;");
         self.create_help_and_version();
         for sc in &mut self.subcommands {
             sc.p.propogate_help_version();
         }
     }
 
     fn build_bin_names(&mut self) {
-        debugln!("exec=build_bin_names;");
+        debugln!("fn=build_bin_names;");
         for sc in &mut self.subcommands {
             debug!("bin_name set...");
             if sc.p.meta.bin_name.is_none() {
@@ -992,7 +997,7 @@ impl<'a, 'b> Parser<'a, 'b>
     }
 
     fn groups_for_arg(&self, name: &str) -> Option<Vec<&'a str>> {
-        debugln!("fn=groups_for_arg;");
+        debugln!("fn=groups_for_arg; name={}", name);
 
         if self.groups.is_empty() {
             debugln!("No groups defined");
@@ -1149,14 +1154,14 @@ impl<'a, 'b> Parser<'a, 'b>
     fn check_for_help_and_version_char(&self, arg: char) -> ClapResult<()> {
         debug!("Checking if -{} is help or version...", arg);
         if let Some(h) = self.help_short {
-            sdebugln!("Help");
             if arg == h && self.settings.is_set(AppSettings::NeedsLongHelp) {
+                sdebugln!("Help");
                 try!(self._help());
             }
         }
         if let Some(v) = self.version_short {
-            sdebugln!("Help");
             if arg == v && self.settings.is_set(AppSettings::NeedsLongVersion) {
+                sdebugln!("Version");
                 try!(self._version());
             }
         }
@@ -1862,7 +1867,7 @@ impl<'a, 'b> Parser<'a, 'b>
     // Should we color the output? None=determined by output location, true=yes, false=no
     #[doc(hidden)]
     pub fn color(&self) -> ColorWhen {
-        debugln!("exec=color;");
+        debugln!("fn=color;");
         debug!("Color setting...");
         if self.is_set(AppSettings::ColorNever) {
             sdebugln!("Never");

src/fmt.rs

@@ -28,15 +28,15 @@ pub enum ColorWhen {
 
 #[cfg(feature = "color")]
 pub fn is_a_tty(stderr: bool) -> bool {
-    debugln!("exec=is_a_tty;");
+    debugln!("fn=is_a_tty;");
     debugln!("Use stderr...{:?}", stderr);
     let fd = if stderr { STDERR } else { STDOUT };
     unsafe { libc::isatty(fd) != 0 }
 }
 
 #[cfg(not(feature = "color"))]
 pub fn is_a_tty(_: bool) -> bool {
-    debugln!("exec=is_a_tty;");
+    debugln!("fn=is_a_tty;");
     false
 }
 
@@ -64,28 +64,28 @@ impl Colorizer {
     pub fn good<T>(&self, msg: T) -> Format<T>
         where T: fmt::Display + AsRef<str>
     {
-        debugln!("exec=good;");
+        debugln!("fn=good;");
         color!(self, Good, msg)
     }
 
     pub fn warning<T>(&self, msg: T) -> Format<T>
         where T: fmt::Display + AsRef<str>
     {
-        debugln!("exec=warning;");
+        debugln!("fn=warning;");
         color!(self, Warning, msg)
     }
 
     pub fn error<T>(&self, msg: T) -> Format<T>
         where T: fmt::Display + AsRef<str>
     {
-        debugln!("exec=error;");
+        debugln!("fn=error;");
         color!(self, Error, msg)
     }
 
     pub fn none<T>(&self, msg: T) -> Format<T>
         where T: fmt::Display + AsRef<str>
     {
-        debugln!("exec=none;");
+        debugln!("fn=none;");
         Format::None(msg)
     }
 }

src/usage_parser.rs

@@ -31,7 +31,7 @@ pub struct UsageParser<'a> {
 
 impl<'a> UsageParser<'a> {
     fn new(usage: &'a str) -> Self {
-        debugln!("exec=new; usage={:?}", usage);
+        debugln!("fn=new; usage={:?}", usage);
         UsageParser {
             usage: usage,
             pos: 0,