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