This adds a new `Cargo.toml` feature named `deprecated` that opts
controls whether deprecation warnings show up. This is starting off as
non-default though that may change (see below).
Benefits
- Allows a staged rollout so a smaller subset of users see new
deprecations and can report their experience with them before everyone
sees them. For example, this reduces the number of people who have to
deal with #3822.
- This allows people to defer responding to each new batch of
deprecations and instead do it at once. This means we should
reconsider #3616.
The one risk is people who don't follow blog posts and guides having a
harder time upgrading to the next breaking release without the warnings
on by default. For these users, we reserve the right to make the
`deprecated` feature `default`. This is most likely to happen in a
minor release that is released in conjunction with the next major
release (e.g. when releasing 4.0.0, we release a 3.3.0 that enables
deprecations by default). By using a feature, users can still disable
this if they want.
Thanks @joshtriplett for the idea
Though this is changing an API item we export, we do not consider this a
breaking change because
- This was an implementation detail of the macros and people shouldn't be using it directly
- The `macro_rules` macro is coupled to `clap` because they are in the
same crate
- The derive macro is coupled to `clap` because `clap` declares a
`=x.y.z` dependency on `clap_derive
Fixes#3828
This is mostly about avoiding criterion's build times when just
developing clap itself.
I'm assuming the derive test changed because criterion's clap v2 isn't
in the dependency tree anymore.
`multicall` allows you to have one binary expose itself as multiple
programs, like busybox does. This also works well for user clap for
parsing REPLs.
Fixes#2861
While `clap` depends on `clap_derive`, `clap_derive` inherently has a
dependency on `clap` because it generates code assuming at least a
specific clap version. If a new `clap_derive` is used with an old
`clap`, it'll generate code that won't compile.
We've kept things loose because of
- Bad experiences with overly constrained version reqs
- To not force new `clap` versions to release `clap_derive`.
- People should have a lock file anyways
The downsides:
- `cargo install` does not use `Cargo.lock` by default, required
`--locked`
- If we want people to not skip non-patch releases when upgrading, we
need it to not be a pain
`-h` (short help) still shows the same.
This gates it behind an `unstable-v4` feature flag to avoid disrupting users who set the help without knowing where all it shows up (particularly derive users where `ArgEnum` is automatically extracting the help).
Fixes#3312
I have access to the `clap-man` name but we use `clap_*`. Rather than
people getting mixed up on which is supposed to use, we went with a
different name.
This is an initial implementation with plenty of room to grow, including
- Allowing pulling out a subset of the generated man page for greater customization
- Subcommand handling
- Extra sections
- Consolidate argument formatter after #2914Fixes#552
This just affects how it's rendered; rather than attempting to highlight
these blocks as a shell script, they'll get highlighted as console
output.
See the rendered versions for a better comparison.
`clap_generate` originally intended to be "generate anything". With
`fig`, we already broke one part out. With #3174's man support, we are
also looking at keeping it separate:
- More freedom to iterate on the API
- Uniqueness (and potential weight) of its dependencies
- man generation is normally more for distribution while completions are
a mix of being distributed with the app or the app generating the
completions (which will be exacerbated if we move most completion
parsing logic to be in Rust)
So `clap_generate` is having a lot more limited of a role than the
original name conveys. I worry the generic name will be a hindrance to
people discovering and using it (yes, documentation can help but there
are limits).
I hesitated because we are on the verge of releasing 3.0. However, doing
it even later will be even more disruptive because more people will be
using it (crates.io lists ~70 people using `clap_generate`).
To ease things, we are still releasing `clap_generate` as a wrapper
around `clap_complete`.
Confirmed this works with [`argfile`](https://docs.rs/argfile/latest/argfile/)
And then running in clap
```
$ RUSTDOCFLAGS="--cfg docsrs" cargo +nightly doc --all-features
```
They now show up!
Experimenting with treating clap-derive and clap one and the same from
the release process perspective. The completion generators are a bit
more independent.
This is carried over from the clap_derive examples. Looking over the
other examples, I feel like they are covered by other examples or by the
derive reference. We should call out deny missing docs though.
This creates distinct tutorial examples from complex feature examples
(more how-tos). Both sets are getting builder / derive versions (at
least the critical ones).
In #27, we removed some default features. When doing so, some places
weren't updated but `doc` feature covered it ... except it was only
partially updated. This makes sure we test all the features.
Too many times people have to disable default features. Let's try to
have a more minimal out of box experience.
- `derive`: people are already used to adding this feature for serde
- `cargo`: not needed for derive
- `env`: most probably don't use this
- `unicode`: most CLIs are probably ASCII. We should do a debug warn
about this though
BREAKING CHANGE: `derive`, `cargo`, `env`, and `unicode` are no longer
on by default.
This ports our example testing over to [trycmd](https://docs.rs/) so
we can:
- More thoroughly test our examples
- Provide always-up-to-date example usage
The old way of testing automatically picked up examples. This new way
requires we have a `.md` file that uses the example in some way.
Notes:
- Moved overall example description to the `.md` file
- I added cross-linking between related examples
- `14_groups` had a redundant paragraph (twice talked about "one and
only one"
2817: Add support for Multicall executables as subcommands with a Multicall setting r=pksunkara a=fishface60
Co-authored-by: Richard Maw <richard.maw@gmail.com>
This is gated behind the `debug` feature flag so only explicit debugging
cases pay the build time and runtime costs.
The builder API's stack traces are generally not too interesting. Where
this really helps is with `clap_derive`. We currently panic on
unexpected conditions which at least gives us a backtrace. We'd like to
turn these into errors but to do so would lose those debuggin
backtraces, which is where this comes in.
This is a part of #2255
This removes the direct dependency on unicode-width and delegates the
complexity of computing the displayed width of text to the Textwrap
crate.
The `display_width` function handles characters like “æøå” (Danish),
“äöü” (German), and “😂✨😍” (emojis) – even if the unicode-width
Cargo feature is disabled.
This is an improvement of the former `str_width` function which would
over-estimate the width of emojis and non-ASCII characters (since they
are several bytes wide).
This commit introduces a new feature called `"regex"`. It adds a new
function `validator_regex` to `Arg` and was inspired by the discussion
in #1968. The name `validator_regex` was chosen instead of
`regex_validator` to make sure that the developer keeps in mind that
there may only be a single `Validator` on an `Arg`.
The feature can be used with YAML files, however there is no proper
pattern in `clap_app!` (yet).
1664: Import structopt r=pksunkara a=CreepySkeleton
OK, here is about 50% of what's left to import.
`impl StructOpt for Box<impl StructOpt>` is not imported because layouts of `StructOpt` and `Clap` are too different. I'll work it out after the import is done.
<!-- Reviewable:start -->
---
This change is [<img src="https://reviewable.io/review_button.svg" height="34" align="absmiddle" alt="Reviewable"/>](https://reviewable.io/reviews/clap-rs/clap/1664)
<!-- Reviewable:end -->
Co-authored-by: CreepySkeleton <creepy-skeleton@yandex.ru>
Co-authored-by: Cecile Tonglet <cecile.tonglet@cecton.com>
Co-authored-by: David McNeil <mcneil.david2@gmail.com>
Before this commit, ansi_term was compiled anytime the `color` feature
was used. However, on Windows the `color` feature is ignored. Even so
ansi_term was compiled, and just not used. This commit fixes that by
only compiling ansi_term on non-Windows targets. Thanks to @retep998 for
the gudiance.
Closes#1155
This commit primarily changes to a lazy handling of POSIX overrides by
relying on github.com/bluss/ordermap instead of the old HashMap impl.
The ordermap allows us to keep track of which arguments arrived first,
and therefore determine which ones should be removed when an override
conflict is found.
This has the added benefit of we no longer have to do the bookkeeping to
keep track and override args as they come in, we can do it once at the
end.
Finally, ordermap allows fast Vec like iteration of the keys, which we
end up doing several times. Benching is still TBD once the v3 prep is
done, but this change should have a meaningful impact.
This version of textwrap uses a new wrapping algorithm that allocates
fewer strings on the heap.
The 05_ripgrep benchmarks shows a performance improvement of 3-15%.
The build_help_long benchmark benefits the most since it uses longer
help texts.
All the other features are either irrelevant, for nightly or already included by default so this should build with all features.
https://github.com/onur/docs.rs/pull/73Fixes#911
* chore: disables mention-bots finding reviewers and pinging tons of people
* docs(README.md): added a warning about using ~ deps
* chore: increase version
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.
The newly released version 1.2.0 of unicode-segmentation adds code
that use the "?" operator, which in turn requires Rust 1.13.0.
However, clap currently still works with Rust 1.11.0 and this caused
build failures:
https://travis-ci.org/kbknapp/clap-rs/jobs/235010822
The changes since 1.1.0 seem to be related cursors/iterators and I
think clap can work fine without them.
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
