Small correction to add a link to the source in the documentation, previously
it was a placeholder.
`rustdoc` does not appear to package assets with the docs, therefore
relative links looking for static files do not work. The links are
consistent enough on github that the static files can be directly linked
to on the master branch.
Currently to use these traits clap must be built with the `unstable` feature. This does not
require a nightly compiler. These traits and APIs may change without warning (hence the `unstable`
feature flag). Once they have been stablelized and the `clap-derive` crate is released the
`unstable` feature flag will no longer be required.
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.
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.
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).
* 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 following completion would happen (using example 17_yaml.rs):
```
$ prog <tab>
help subcmd
```
```
$ prog -<tab><tab>
--help -h (Prints help information)
--max-vals (you can only supply a max of 3 values for me!)
--min-vals (you must supply at least two values to satisfy me)
--mode (shows an option with specific values)
--mult-vals (demos an option which has two named values)
--option -o (example option argument from yaml)
--version -V (Prints version information)
-F (demo flag argument)
```
```
$ prog --<tab><tab>
--help -h (Prints help information)
--max-vals (you can only supply a max of 3 values for me!)
--min-vals (you must supply at least two values to satisfy me)
--mode (shows an option with specific values)
--mult-vals (demos an option which has two named values)
--option -o (example option argument from yaml)
--version -V (Prints version information)
```
```
$ prog --mode <tab>
emacs (shows an option with specific values) vi (shows an option with specific values)
```
```
$ prog subcmd -<tab>
--help -h (Prints help information) -B (example subcommand option)
--version -V (Prints version information)
```
```
$ prog subcmd --<tab>
--help (Prints help information) --version (Prints version information)
```
Close#578
By using a build.rs "build script" one can now generate a bash completions script which allows tab
completions for the entire program, to include, subcommands, options, everything!
See the documentation for full examples and details.
Closes#376
