Mirrors/clap
2
0
Fork 0
mirror of https://github.com/clap-rs/clap synced 2024-12-14 06:42:33 +00:00
Code Issues Projects Releases Packages Wiki Activity

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

Browse source 
Issue 588
This commit is contained in:
Homu 2016-09-13 11:25:56 +09:00
commit 804a60f781
8 changed files with 84 additions and 31 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

33
CHANGELOG.md
View file

@ -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)

2
Cargo.toml
View file

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

42
README.md
View file

@ -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<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

2
src/app/help.rs
View file

@ -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();

1
src/app/macros.rs
View file

@ -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);

21
src/app/parser.rs
View file

@ -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<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");

12
src/fmt.rs
View file

@ -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<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)
}
}

2
src/usage_parser.rs
View file

@ -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,