If one is using a nightly Rust compiler they should compile clap
with the `nightly` feature.
```toml
[dependencies]
clap = { version = "2.27", features = ["nightly"] }
```
This isn't required for compilation to succeed, only to take
advantage of any nightly features used by clap.
If one is compiling with `#[deny(warnings)]` this commit will cause
compilation to fail if one *does not* compile with the `nightly`
since `std::ascii::AsciiExt` is no longer required in in multiple
files as of the latest Rust nightly (Nov 6th, 2017).
Closes#1095
Prior to this commit, using `AppSettings::AllowHyphenValues` would allow
ANY argument to pass, even if there was no way it could be valid.
Imagine a CLI with only a single flag (i.e. *no value*) `--flag`, but this setting
is set. The following was valid:
```
$ prog hello
```
This commit fixes that by creating an UnknownArgument error unless the
unknown argument/value in question could legally be parsed as a value
to a valid argument.
Closes#1066
**This commit contains a breaking change in order to fix a bug.**
The only users affected are those relying on the "bug." The bug is only in code that uses
subcommands, and parent commands with arguments accepting multiple values (positionals or options)
unrestrained *and* where a value may coincide with a subcommand's name.
Imagine a CLI with a positional argument `files` that accepts multiple values but no other conditions
or parameters (just `Arg::multiple(true)`), and a subcommand `log`
Prior to this commit, the following was valid:
```
$ prog file1 file2 file3 log
```
which would be parsed as:
* files = file1, file2, file3
* subcommand = log
However, if there was a file named `log` the subcommand isn't callable.
The CLI should be designed in a way that either limits number of values so that clap knows
when `files` is done and can then look for subcommands, or other AppSettings which change
the behavior.
Possible fixes are `Arg::number_of_values`, `Arg::max_values`,
`AppSettings::ArgsNegateSubcommands`, `Arg::require_equals`,
`AppSettings::SubcommandsNegateArgs`, and more.
This *does not* affect CLIs which contain other arguments between the unrestrained multiple
value args, and the any subcommands. Such as if our example above also had a flag `-f`
The following would be parsed the same before and after this commit.
```
$ prog file1 file2 file3 -f log
```
This is because upon reaching the flag `-f`, clap stops parsing `files`.
No other breaking changes were made.
---
When using args with `multiple(true)` on options or positionals (i.e. those args that
accept values) and subcommands, one needs to consider the posibility of an argument value
being the same as a valid subcommand. By default `clap` will parse the argument in question
as a value *only if* a value is possible at that moment. Otherwise it will be parsed as a
subcommand. In effect, this means using `multiple(true)` with no additional parameters and
a possible value that coincides with a subcommand name, the subcommand cannot be called
unless another argument is passed first.
As an example, consider a CLI with an option `--ui-paths=<paths>...` and subcommand `signer`
The following would be parsed as values to `--ui-paths`.
```
$ program --ui-paths path1 path2 signer
```
This is because `--ui-paths` accepts multiple values. `clap` will continue parsing values
until another argument is reached and it knows `--ui-paths` is done.
By adding additional parameters to `--ui-paths` we can solve this issue. Consider adding
`Arg::number_of_values(1)` as discussed above. The following are all valid, and `signer`
is parsed as both a subcommand and a value in the second case.
```
$ program --ui-paths path1 signer
$ program --ui-paths path1 --ui-paths signer signer
```
Closes#1031
This doc attribute is used by rustdoc when generating documentation
for other crates that depend on this crate. With the html_root_url,
rustdoc will be able to generate correct links into this crate.
See C-HTML-ROOT in the Rust API Guidelines for more information:
https://rust-lang-nursery.github.io/api-guidelines/documentation.html#crate-sets-html_root_url-attribute-c-html-root
A version-sync check was added to ensure that the URL is kept up to
date when the crate version changes.
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.
