diff --git a/CHANGELOG.md b/CHANGELOG.md index 41a61a213d5..37e0a452a47 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,36 @@ + +## 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)) + + + ### v2.11.3 (2016-09-07) diff --git a/Cargo.toml b/Cargo.toml index 74605488c3c..7835bc89c1a 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,7 +1,7 @@ [package] name = "clap" -version = "2.11.3" +version = "2.12.0" authors = ["Kevin K. "] exclude = ["examples/*", "clap-test/*", "tests/*", "benches/*", "*.png", "clap-perf/*", "*.dot"] repository = "https://github.com/kbknapp/clap-rs.git" diff --git a/README.md b/README.md index 952936b708a..2dd8fac2373 100644 --- a/README.md +++ b/README.md @@ -39,11 +39,26 @@ 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 @@ -51,8 +66,8 @@ Here's the highlights for v2.11.2 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 @@ -60,17 +75,17 @@ Here's the highlights for v2.11.1 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.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 diff --git a/src/app/help.rs b/src/app/help.rs index f804a0cf4eb..16312bf0b04 100644 --- a/src/app/help.rs +++ b/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(); diff --git a/src/app/macros.rs b/src/app/macros.rs index 59f7a4dfc64..d3006b89c27 100644 --- a/src/app/macros.rs +++ b/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); diff --git a/src/app/parser.rs b/src/app/parser.rs index 660385b69b4..7c896203f74 100644 --- a/src/app/parser.rs +++ b/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,7 +851,7 @@ 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(); @@ -854,7 +859,7 @@ impl<'a, 'b> Parser<'a, 'b> } 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> { - 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"); diff --git a/src/fmt.rs b/src/fmt.rs index c23cfaa4573..8b1ccf19180 100644 --- a/src/fmt.rs +++ b/src/fmt.rs @@ -28,7 +28,7 @@ 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 } @@ -36,7 +36,7 @@ pub fn is_a_tty(stderr: bool) -> bool { #[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(&self, msg: T) -> Format where T: fmt::Display + AsRef { - debugln!("exec=good;"); + debugln!("fn=good;"); color!(self, Good, msg) } pub fn warning(&self, msg: T) -> Format where T: fmt::Display + AsRef { - debugln!("exec=warning;"); + debugln!("fn=warning;"); color!(self, Warning, msg) } pub fn error(&self, msg: T) -> Format where T: fmt::Display + AsRef { - debugln!("exec=error;"); + debugln!("fn=error;"); color!(self, Error, msg) } pub fn none(&self, msg: T) -> Format where T: fmt::Display + AsRef { - debugln!("exec=none;"); + debugln!("fn=none;"); Format::None(msg) } } diff --git a/src/usage_parser.rs b/src/usage_parser.rs index d2d17a7e00f..b8344265e90 100644 --- a/src/usage_parser.rs +++ b/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,