Earlier, wrap_help was doing in-place modification on the help text.
With the user of the textwrap crate, this is no longer the case and we
can return the string directly.
The textwrap crate uses a simpler linear-time algorithm for wrapping
the text. The current algorithm in wrap_help uses several O(n) calls
to String::insert and String::remove, which makes it potentially
quadratic in complexity.
Comparing the 05_ripgrep benchmark at commits textwrap~2 and textwrap
gives this result on my machine:
name before ns/iter after ns/iter diff ns/iter diff %
build_app_long 22,101 21,099 -1,002 -4.53%
build_app_short 22,138 21,205 -933 -4.21%
build_help_long 514,265 284,467 -229,798 -44.68%
build_help_short 85,720 85,693 -27 -0.03%
parse_clean 23,471 22,859 -612 -2.61%
parse_complex 29,535 28,919 -616 -2.09%
parse_lots 422,815 414,577 -8,238 -1.95%
As part of this commit, the wrapping_newline_chars test was updated.
The old algorithm had a subtle bug where it would break lines too
early. That is, it wrapped the text like
ARGS:
<mode> x, max, maximum 20 characters, contains
symbols.
l, long Copy-friendly,
14 characters, contains symbols.
m, med, medium Copy-friendly, 8
characters, contains symbols.";
when it should really have wrapped it like
ARGS:
<mode> x, max, maximum 20 characters, contains
symbols.
l, long Copy-friendly, 14
characters, contains symbols.
m, med, medium Copy-friendly, 8
characters, contains symbols.";
Notice how the word "14" was incorrectly moved to the next line. There
is clearly room for the word on the line with the "l, long" option
since there is room for "contains" just above it.
I'm not sure why this is, but the algorithm in textwrap handles this
case correctly.
One can now use `App::long_version` to dsiplay a different (presumably
longer) message when `--version` is called. This commit also adds the
corresponding print/write long version methods of `App`
One can now use `App::print_long_help` or `App::write_long_help`
Note that `App::write_long_help` is **NOT** affected by kbknapp/clap-rs#808 in the manner
that `App::write_help` help is and thus should be preferred if at all possible.
One can now use `Arg::long_help` which will be displayed when the user
runs `--help`. This is typically longer form content and will be
displayed using the NextLineHelp methodology.
If one specifies the standard `Arg::help` it will be displayed when the
user runs `-h` (by default, unless the help short has been overridden).
The help text will be displayed in the typical clap fashion.
The help format requested (-h/short or --help/long) will be the
*default* displayed. Meaning, if one runs `--help` (long) but only an
`Arg::help` has been provided, the message from `Arg::help` will be
used. Likewise, if one requests `-h` (short) but only
`Arg::long_help` was provided, `Arg::long_help` will be displayed appropriately
wrapped and aligned.
Completion script generation *only* uses `Arg::help` in order to be
concise.
cc @BurntSushi thanks for the idea!
One should be able to override the auto generated help and version flags
by simply providing an arg with a long of `help` or `version`
respectively. This bug was preventing that from happening.
However, now that it's fixed if one was relying on adding an arg with a
long of `help` or `version` and using `get_matches_safe` to produce the
`ErrorKind::HelpDisplayed` or `ErrorKind::VersionDisplayed` errors they
**WILL NOT** happen anymore.
This is because the bug was causing those "errors" to occur (i.e. the
help or version message to be displayed). The "fix" to get that
functionality back is to either:
* Remove the arg with the long of `help` or `version`
* Use `ArgMatches::is_present` instead of `App::get_matches_safe` to check for the presence of your custom help or version flag
Option 1 is the easiest provided one wasn't using said arg to *also*
override other aspects of the flags as well (short, help message, etc.)
Even though this may break some code, as per the compatibility policy
listed in the readme; code that breaks due to relying on a bug does
*not* constitute a major version bump. I will however be bumping the
minor version instead of just the patch version. I will also be
searching for, contacting, and attempting to submit PRs to any affected
projects prior to releasing the next version to crates.io
Closes#922
Adds a new method, `Arg::hide_default_value`, which allows for
specifying whether the default value of the argument should be hidden
from the help string.
Closes#902
Marking a positional argument `.last(true)` will allow accessing this argument earlier if the `--` syntax is used (i.e. skipping other positional args)
and also change the usage string to one of the following:
* `$ prog [arg1] [-- <last_arg>]`
* `$ prog [arg1] -- <last_arg>` (if the arg marked `.last(true)` is also marked `.required(true)`)
Closes#888
This makes a very big difference for CLIs that parse a large number of
values (think ripgrep over a large directory).
This commit improved the ripgrep parsing of ~2,000 values, simulating
giving ripgrep a bunch of files. Parsing when from ~1,200,000 ns to
~400,000 ns! This was conducted a i7-5600U 2.6GHz
One can now define default values that contain invalid UTF-8.
The underlying implementation has also been changed to use OsStrs in order to avoid duplication
of code and provide the new APIs basically for free.
Closes#849
Not only does this remove some unsafe code from clap itself, `atty` does the
right thing on Windows too. This isn't relevant now since we don't currently
support colorized output on Windows, but will come in handy if/when we
implement that feature (#836).
* tests: adds tests for default values triggering conditional requirements
* fix: fixes a bug where default values should have triggered a conditional requirement but didnt
Closes#831
* tests: adds tests for missing conditional requirements in usage string of errors
* fix: fixes a bug where conditionally required args werent appearing in errors
* tests: adds tests for completion generators
* tests: adds tests for completions with binaries names that have underscores
* fix: fixes a bug where ZSH completions would panic if the binary name had an underscore in it
Closes#581
* fix: fixes bash completions for commands that have an underscore in the name
Closes#581
* chore: fix the category for crates.io
* docs(Macros): adds a warning about changing values in Cargo.toml not triggering a rebuild automatically
Closes#838
* fix(Completions): fixes a bug where global args weren't included in the generated completion scripts
Closes#841
* fix: fixes a println->debugln typo
* chore: increase version
* fix: fixes a critical bug where subcommand settings were being propogated too far
Closes#832
* imp: adds ArgGroup::multiple to the supported YAML fields for building ArgGroups from YAML
Closes#840
* chore: increase version
Before, inserting a newline did not move the prev_space index forward.
This meant that the next word was measured incorrectly since the
length was measured back to the word before the newly inserted
linebreak.
Fixes#828.
Before, wrapping the help text at, say, 80 characters really meant
that every line could be at most 79 characters wide.
Lines can now be up to and including avail_chars columns wide.
If needed, a desired margin or padding can be subtracted from the
avail_chars argument at a later point.
This fixes#827. The problem was that the check `grp.args.contains(&grp.args[i])` was a) trivially fulfilled (of course `grp.args[i]` is contained in `grp.args`) and b) causing an out-of-bounds error, since the indices were taken from `.required.len()`.
With this change the argument in the group will be removed from the list of required arguments, as intended.
When calling the executable without arguments one expects a help message. However, if even one argument has a default value, the validation step of the parser will always see at least one argument, and therefore report success. This effectively disables the settings.
Specifies that use of a valid [argument] negates [subcomands] being used after. By default
`clap` allows arguments between subcommands such as
`<cmd> [cmd_args] <cmd2> [cmd2_args] <cmd3> [cmd3_args]`. This setting disables that
functionality and says that arguments can only follow the *final* subcommand. For instance
using this setting makes only the following invocations possible:
* `<cmd> <cmd2> <cmd3> [cmd3_args]`
* `<cmd> <cmd2> [cmd2_args]`
* `<cmd> [cmd_args]`
Closes#793
An arg can now be conditionally required (i.e. it's only required if arg
A is used with a value of V).
For example:
```rust
let res = App::new("ri")
.arg(Arg::with_name("cfg")
.required_if("extra", "val")
.takes_value(true)
.long("config"))
.arg(Arg::with_name("extra")
.takes_value(true)
.long("extra"))
.get_matches_from_safe(vec![
"ri", "--extra", "val"
]);
assert!(res.is_err());
assert_eq!(res.unwrap_err().kind, ErrorKind::MissingRequiredArgument);
```
Relates to #764
An arg can now conditionally require additional arguments if it's value matches a specific value.
For example, arg A can state that it only requires arg B if the value X was used with arg A. If any
other value is used with A, arg B isn't required.
Relates to #764
One can now implement conditional default values. I.e. a default value that is only applied in
certain conditions, such as another arg being present, or another arg being present *and*
containing a specific value.
Now it's possible to say, "Only apply this default value if arg X is present" or "Only apply this
value if arg X is present, but also only if arg X's value is equal to Y"
This new method is fully compatible with the current `Arg::default_value`, which gets set only if
the arg wasn't used at runtime *and* none of the specified conditions were met.
Releates to #764
Instead of using Format::Error directly, we need to use a Colorizer to
make sure that the message only gets colorized when it is appropriate
to do so.
Fixes#775
The implementation is basically manually expanded lazy_static! macro
(with some hand-crafted simplifications and inlining), since you can't
use extern crates (and therefore import macros therefrom) in macros.
This ensures that you get this:
p:\Rust\http>target\debug\http -h
http 0.1.0
thecoshman <thecoshman@gmail.com>
nabijaczleweli <nabijaczleweli@gmail.com>
Host These Things Please - a basic HTTP server for hosting a folder fast and simply
Instead of this:
p:\Rust\http>target\debug\http -h
http 0.1.0
thecoshman <thecoshman@gmail.com>:nabijaczleweli <nabijaczleweli@gmail.com>
Host These Things Please - a basic HTTP server for hosting a folder fast and simply
Closes#779
Since ZSH completions use `[ and ]` for descriptions, but clap args use `[ and ]` for possible
values and other auxillary arg information, this was creating a conflict. clap now escapes any
square brackets before writing the help, i.e. `\\[ and \\]` which removes conflicts.
Alternatives would be to switch `[ and ]` for `( and )` but this would create a slight difference
in help messages and completions.
Closes#771
With these options, in case the completion function cannot provide
suggestions, Bash will perform its default completions, based on e.g.
files, directories, and variable names. This is particularly useful for
argument values.
Prior to this commit setting `number_of_values(1)` and `multiple(true)` would cause the help
message alignment to be off. This commit fixes that.
Closes#760
One can now use `Arg::allow_hyphen_values(true)` which will enable `--opt -val` style values only
for the specific arg and not command wide.
Closes#742
Flags, Opts, and Positionals now store their internals using compartmented Base, Valued, and
Switched structs to keep the code duplication down and make it easier to maintain.
Iniside the src/app/parser.rs there have been several changes to make reasoning about the code
easier. Primarily moving related sections out of the large get_matches_with into their own
functions.
Now one can build CLIs that support things like `mv <files>... <target>`
There are a few requirements and caveats;
* The final positional argument (and all positional arguments prior) *must* be required
* Only one positional argument may be `multiple(true)`
* Only the second to last, or last positional argument may be `multiple(true)`
Closes#725
Prior to this commit, conflicting error messages and the suggeseted usage would depend on whether
you defined the conflict on both arguments, or just one, and the order in which you specified the
conflicting arguments at runtime.
Now they are symetrical, meaning the suggestions from the error message are consistent, and it no
longer matters if you specify the conflict in one, or both arguments.
Closes#718
Don't attempt to change the display order of flags/options until any app
settings have been propagated down from a parent App in case DeriveDisplayOrder
and/or UnifiedHelpMessage are propagated.
Fixes#706
One can now use `AppSettings::AllowNegativeNumbers` which functions similar to `AllowLeadingHyphen`
with the exception that only unknown numbers are allowed have a preceding hyphen character.
See the documentation for details and examples.
Closes#696
* Clap has dependencies even with all features disabled.
* The "nightly" feature does nothing, so don't mention it.
* Explain the difference between "unstable" and "nightly" better.
* Split features into groups (default, opt-in, clap-development).
* For contributors: update what tests should be run, and remove make command.
* Removes a repeated word and splits up some long markdown lines.
Also groups features by category and dependencies by feature in Cargo.toml.
The new version of rustc 1.14.0-nightly (144af3e97 2016-10-02) has new
linting warnings/errors. This commit fixes them.
Signed-off-by: Salim Afiune <afiune@chef.io>
Added same alias funtionality for flags, now you can do:
```
Arg::with_name("flg")
.long("flag")
.short("f")
.alias("not_visible_flag")
.visible_alias("awesome_v_flag")
```
Signed-off-by: Salim Afiune <afiune@chef.io>
There are some cases where you need to have an argument to have an
alias, an example could be when you depricate one option in favor of
another one.
Now you are going to be able to alias arguments as follows:
```
Arg::with_name("opt")
.long("opt")
.short("o")
.takes_value(true)
.alias("invisible")
.visible_alias("visible")
```
Closes#669
