Mirrors/clap
2
0
Fork 0
mirror of https://github.com/clap-rs/clap synced 2024-09-21 06:41:54 +00:00
Code Issues Projects Releases Packages Wiki Activity
clap/README.md

159 lines
6.7 KiB
Markdown
Raw Normal View History

Update README for beta release
2020-03-02 08:52:15 +00:00
<!-- omit in TOC -->
# clap
This breaks for rustdoc
2015-03-18 23:43:33 +00:00
docs: Focus top-level README
2021-11-30 03:05:42 +00:00
> **Command Line Argument Parser for Rust**
Update README for beta release
2020-03-02 08:52:15 +00:00
[![Crates.io](https://img.shields.io/crates/v/clap?style=flat-square)](https://crates.io/crates/clap)
[![Crates.io](https://img.shields.io/crates/d/clap?style=flat-square)](https://crates.io/crates/clap)
chore: Release
2022-01-04 17:42:50 +00:00
[![License](https://img.shields.io/badge/license-Apache%202.0-blue?style=flat-square)](https://github.com/clap-rs/clap/blob/v3.0.3/LICENSE-APACHE)
[![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](https://github.com/clap-rs/clap/blob/v3.0.3/LICENSE-MIT)
chore: CI improvements
2021-10-09 18:50:16 +00:00
[![Build Status](https://img.shields.io/github/workflow/status/clap-rs/clap/CI/staging?style=flat-square)](https://github.com/clap-rs/clap/actions/workflows/ci.yml?query=branch%3Astaging)
Update README for beta release
2020-03-02 08:52:15 +00:00
[![Coverage Status](https://img.shields.io/coveralls/github/clap-rs/clap/master?style=flat-square)](https://coveralls.io/github/clap-rs/clap?branch=master)
Update badges
2021-05-25 22:19:32 +00:00
[![Contributors](https://img.shields.io/github/contributors/clap-rs/clap?style=flat-square)](https://github.com/clap-rs/clap/graphs/contributors)
This breaks for rustdoc
2015-03-18 23:43:33 +00:00
docs: Focus top-level README
2021-11-30 03:05:42 +00:00
Dual-licensed under [Apache 2.0](LICENSE-APACHE) or [MIT](LICENSE-MIT).
Update README for beta release
2020-03-02 08:52:15 +00:00
1. [About](#about)
chore: Release
2022-01-04 17:42:50 +00:00
2. Tutorial: [Builder API](https://github.com/clap-rs/clap/blob/v3.0.3/examples/tutorial_builder/README.md), [Derive API](https://github.com/clap-rs/clap/blob/v3.0.3/examples/tutorial_derive/README.md)
3. [Examples](https://github.com/clap-rs/clap/blob/v3.0.3/examples/README.md)
docs: Re-work examples This creates distinct tutorial examples from complex feature examples (more how-tos). Both sets are getting builder / derive versions (at least the critical ones).
2021-11-30 18:30:19 +00:00
4. [API Reference](https://docs.rs/clap)
chore: Release
2022-01-04 17:42:50 +00:00
- [Derive Reference](https://github.com/clap-rs/clap/blob/v3.0.3/examples/derive_ref/README.md)
docs: Focus top-level README
2021-11-30 03:05:42 +00:00
- [Feature Flags](#feature-flags)
chore: Release
2022-01-04 17:42:50 +00:00
5. [CHANGELOG](https://github.com/clap-rs/clap/blob/v3.0.3/CHANGELOG.md)
6. [FAQ](https://github.com/clap-rs/clap/blob/v3.0.3/docs/FAQ.md)
docs: Re-work examples This creates distinct tutorial examples from complex feature examples (more how-tos). Both sets are getting builder / derive versions (at least the critical ones).
2021-11-30 18:30:19 +00:00
7. [Questions & Discussions](https://github.com/clap-rs/clap/discussions)
chore: Release
2022-01-04 17:42:50 +00:00
8. [Contributing](https://github.com/clap-rs/clap/blob/v3.0.3/CONTRIBUTING.md)
docs: Add back sponsors
2021-12-07 21:05:03 +00:00
8. [Sponsors](#sponsors)
docs: adds "whats new" section to readme
2015-06-30 02:22:13 +00:00
docs(README.md): add video tutorial section
2015-04-06 17:39:13 +00:00
## About
docs: Focus top-level README
2021-11-30 03:05:42 +00:00
Create your command-line parser, with all of the bells and whistles, declaratively or procedurally.
docs(README): adds details about optional and new features
2015-05-05 23:31:41 +00:00
docs: Focus top-level README
2021-11-30 03:05:42 +00:00
### Example
docs(README.md): updates readme for v2 release Closes #393
2016-01-27 21:37:09 +00:00
docs: Focus top-level README
2021-11-30 03:05:42 +00:00
<!-- Copied from examples/demo.{rs,md} -->
test: Compile example in README
2021-10-23 15:46:26 +00:00
```rust,no_run
docs: Prefer `global_setting` I've been finding I've been setting `AppSettings` without it which is likely leading to bugs. This tries to raise the visibility by using it based on the setting being used and not whether the application needs it.
2021-11-29 22:10:52 +00:00
use clap::Parser;
docs(README.md): stars the v3 update of the docs
2018-08-02 03:05:52 +00:00
docs: Simplify demo
2021-12-07 21:34:23 +00:00
/// Simple program to greet a person
#[derive(Parser, Debug)]
#[clap(about, version, author)]
struct Args {
/// Name of the person to greet
#[clap(short, long)]
name: String,
/// Number of times to greet
#[clap(short, long, default_value_t = 1)]
count: u8,
docs(README.md): fixes the custom derive example in the readme Closes #1589
2019-10-31 00:26:41 +00:00
}
docs(README.md): stars the v3 update of the docs
2018-08-02 03:05:52 +00:00
fn main() {
docs: Simplify demo
2021-12-07 21:34:23 +00:00
let args = Args::parse();
docs(README.md): stars the v3 update of the docs
2018-08-02 03:05:52 +00:00
docs: Simplify demo
2021-12-07 21:34:23 +00:00
for _ in 0..args.count {
println!("Hello {}!", args.name)
}
docs(README.md): stars the v3 update of the docs
2018-08-02 03:05:52 +00:00
}
```
docs: More explicit "derive" feature
2021-12-17 15:23:02 +00:00
Add this to `Cargo.toml`:
```toml
[dependencies]
chore: Release
2022-01-04 17:42:50 +00:00
clap = { version = "3.0.3", features = ["derive"] }
docs: More explicit "derive" feature
2021-12-17 15:23:02 +00:00
```
docs: Focus top-level README
2021-11-30 03:05:42 +00:00
```bash
$ demo --help
clap [..]
docs(README.md): stars the v3 update of the docs
2018-08-02 03:05:52 +00:00
docs: Focus top-level README
2021-11-30 03:05:42 +00:00
A simple to use, efficient, and full-featured Command Line Argument Parser
Updated readme
2015-03-01 00:22:23 +00:00
docs: Focus top-level README
2021-11-30 03:05:42 +00:00
USAGE:
docs: Simplify demo
2021-12-07 21:34:23 +00:00
demo[EXE] [OPTIONS] --name <NAME>
docs(README): adds details about optional and new features
2015-05-05 23:31:41 +00:00
Update README.md
2015-03-16 14:38:43 +00:00
OPTIONS:
docs: Simplify demo
2021-12-07 21:34:23 +00:00
-c, --count <COUNT> Number of times to greet [default: 1]
fix(help)!: Merge OPTIONS / FLAGS default groups For those that want the original behavior, you can usxe `arg.help_heading(Some("FLAGS"))` on your flags. Limitations: - This will not give you a special sort order - This will not get a `[FLAGS]` added to usage For templates, we removed `{unified}` and `{flags}`. To help people catch these, a debug_assert was added. I'm unsure but I think there might be a change in behavior in calcuating when to show `[OPTION]` in usage. The old code only looked at `required` while flags looked only at arg groups. We now look at both. Ideally we'd add these in `_build` and remove special casing for no-groups except in the sort order of groups. I feel like thats best left for later. This also reduced the scope of `App`s public API. `get_*_with_no_heading` seemed a bit specialized to be in the public API. #2853 looks at splitting it out into its own PR. BREAKING CHANGE: Multiple - `UnifiedHelpMessage` removed - `{flags}` and `{unified}` are removed and will assert when present. - `get_*_with_no_heading` removed Fixes #2807
2021-10-11 22:01:33 +00:00
-h, --help Print help information
docs: Simplify demo
2021-12-07 21:34:23 +00:00
-n, --name <NAME> Name of the person to greet
fix(help)!: Merge OPTIONS / FLAGS default groups For those that want the original behavior, you can usxe `arg.help_heading(Some("FLAGS"))` on your flags. Limitations: - This will not give you a special sort order - This will not get a `[FLAGS]` added to usage For templates, we removed `{unified}` and `{flags}`. To help people catch these, a debug_assert was added. I'm unsure but I think there might be a change in behavior in calcuating when to show `[OPTION]` in usage. The old code only looked at `required` while flags looked only at arg groups. We now look at both. Ideally we'd add these in `_build` and remove special casing for no-groups except in the sort order of groups. I feel like thats best left for later. This also reduced the scope of `App`s public API. `get_*_with_no_heading` seemed a bit specialized to be in the public API. #2853 looks at splitting it out into its own PR. BREAKING CHANGE: Multiple - `UnifiedHelpMessage` removed - `{flags}` and `{unified}` are removed and will assert when present. - `get_*_with_no_heading` removed Fixes #2807
2021-10-11 22:01:33 +00:00
-V, --version Print version information
Update README.md
2015-03-16 14:38:43 +00:00
```
docs: Focus top-level README
2021-11-30 03:05:42 +00:00
*(version number and `.exe` extension on windows replaced by placeholders)*
Updated readme and removed Cargo.lock from git
2015-03-01 00:33:18 +00:00
docs: Focus top-level README
2021-11-30 03:05:42 +00:00
### Aspirations
docs(groups): adds documentation for ArgGroups
2015-04-28 02:52:50 +00:00
docs: Focus top-level README
2021-11-30 03:05:42 +00:00
- Out of the box, users get a polished CLI experience
fix(complete): Give crates more specific names `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`.
2021-12-31 17:59:15 +00:00
- Including common argument behavior, help generation, suggested fixes for users, colored output, [shell completions](https://github.com/clap-rs/clap/tree/master/clap_complete), etc
docs: Focus top-level README
2021-11-30 03:05:42 +00:00
- Flexible enough to port your existing CLI interface
- However, we won't necessarily streamline support for each use case
- Reasonable parse performance
docs: Expand on aspirations
2021-12-06 20:54:33 +00:00
- Resilient maintainership, including
- Willing to break compatibility rather than batching up breaking changes in large releases
- Leverage feature flags to keep to one active branch
- Being under [WG-CLI](https://github.com/rust-cli/team/) to increase the bus factor
docs: Expand breaking change window
2021-12-07 21:03:34 +00:00
- We follow semver and will wait about 6-9 months between major breaking changes
docs: Be explicit about current MSRV
2021-12-07 21:03:12 +00:00
- We will support the last two minor Rust releases (MSRV, currently 1.54.0)
docs(groups): adds documentation for ArgGroups
2015-04-28 02:52:50 +00:00
docs: Focus top-level README
2021-11-30 03:05:42 +00:00
While these aspirations can be at odds with fast build times and low binary
docs: Expand on aspirations
2021-12-06 20:54:33 +00:00
size, we will still strive to keep these reasonable for the flexibility you
get. Check out the
docs: Focus top-level README
2021-11-30 03:05:42 +00:00
[argparse-benchmarks](https://github.com/rust-cli/argparse-benchmarks-rs) for
CLI parsers optimized for other use cases.
docs(groups): adds documentation for ArgGroups
2015-04-28 02:52:50 +00:00
docs: Focus top-level README
2021-11-30 03:05:42 +00:00
### Related Projects
Updated readme and removed Cargo.lock from git
2015-03-01 00:33:18 +00:00
docs(readme): Raise visibility of wild
2021-12-10 00:57:16 +00:00
- [wild](https://crates.io/crates/wild) for supporting wildcards (`*`) on Windows like you do Linux
docs(readme): Consistently use crates.io links
2021-12-11 15:12:26 +00:00
- [argfile](https://crates.io/crates/argfile) for loading additional arguments from a file (aka response files)
fix(complete): Give crates more specific names `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`.
2021-12-31 17:59:15 +00:00
- [clap_complete](https://crates.io/crates/clap_complete) for shell completion support
docs(readme): Consistently use crates.io links
2021-12-11 15:12:26 +00:00
- [clap-verbosity-flag](https://crates.io/crates/clap-verbosity-flag)
- [clap-cargo](https://crates.io/crates/clap-cargo)
- [concolor-clap](https://crates.io/crates/concolor-clap)
docs: Focus top-level README
2021-11-30 03:05:42 +00:00
- [Command-line Apps for Rust](https://rust-cli.github.io/book/index.html) book
docs(readme): Consistently use crates.io links
2021-12-11 15:12:26 +00:00
- [`trycmd`](https://crates.io/crates/trycmd): Snapshot testing
- Or for more control, [`assert_cmd`](https://crates.io/crates/assert_cmd) and [`assert_fs`](https://crates.io/crates/assert_fs)
docs(README): adds details about optional and new features
2015-05-05 23:31:41 +00:00
docs: Focus top-level README
2021-11-30 03:05:42 +00:00
## Feature Flags
Add env feature gate
2021-08-14 00:04:49 +00:00
docs: Focus top-level README
2021-11-30 03:05:42 +00:00
### Default Features
docs: Improve documentation around features * 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.
2016-10-15 02:58:36 +00:00
Add env feature gate
2021-08-14 00:04:49 +00:00
* **std**: _Not Currently Used._ Placeholder for supporting `no_std` environments in a backwards compatible manner.
docs: Focus top-level README
2021-11-30 03:05:42 +00:00
* **color**: Turns on colored error messages.
* **suggestions**: Turns on the `Did you mean '--myoption'?` feature for when users make typos.
docs(README): adds details about optional and new features
2015-05-05 23:31:41 +00:00
docs: Focus top-level README
2021-11-30 03:05:42 +00:00
#### Optional features
docs(README): adds details about optional and new features
2015-05-05 23:31:41 +00:00
docs: Focus top-level README
2021-11-30 03:05:42 +00:00
* **derive**: Enables the custom derive (i.e. `#[derive(Parser)]`). Without this you must use one of the other methods of creating a `clap` CLI listed above.
fix!: Lighten clap's default feature set 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.
2021-11-24 16:35:29 +00:00
* **cargo**: Turns on macros that read values from `CARGO_*` environment variables.
* **env**: Turns on the usage of environment variables during parsing.
docs: Focus top-level README
2021-11-30 03:05:42 +00:00
* **regex**: Enables regex validators.
* **unicode**: Turns on support for unicode characters (including emoji) in arguments and help messages.
* **wrap_help**: Turns on the help text wrapping feature, based on the terminal size.
docs(README): adds details about optional and new features
2015-05-05 23:31:41 +00:00
fix: Gate App::replace We are concerned about the level of polish of this feature and are unsure enough about its future, we've decided to gate it to unblock the v3 release.
2021-10-09 15:44:31 +00:00
#### Experimental features
docs: Focus top-level README
2021-11-30 03:05:42 +00:00
**Warning:** These may contain breaking changes between minor releases.
chore: CI improvements
2021-10-09 18:50:16 +00:00
fix: Gate App::replace We are concerned about the level of polish of this feature and are unsure enough about its future, we've decided to gate it to unblock the v3 release.
2021-10-09 15:44:31 +00:00
* **unstable-replace**: Enable [`App::replace`](https://github.com/clap-rs/clap/issues/2836)
fixup! Fill in tracking issue number
2021-10-12 19:51:26 +00:00
* **unstable-multicall**: Enable [`AppSettings::Multicall`](https://github.com/clap-rs/clap/issues/2861)
Put `grouped_values_of` behind a feature gate There is enough open work on this, we should probably not have it public yet, so putting it behind a gate. See https://github.com/clap-rs/clap/issues/2924
2021-10-23 15:01:55 +00:00
* **unstable-grouped**: Enable [`ArgMatches::grouped_values_of`](https://github.com/clap-rs/clap/issues/2924)
docs: Add back sponsors
2021-12-07 21:05:03 +00:00
## Sponsors
<!-- omit in TOC -->
### Gold
[![](https://opencollective.com/clap/tiers/gold.svg?avatarHeight=36&width=600)](https://opencollective.com/clap)
<!-- omit in TOC -->
### Silver
[![](https://opencollective.com/clap/tiers/silver.svg?avatarHeight=36&width=600)](https://opencollective.com/clap)
<!-- omit in TOC -->
### Bronze
[![](https://opencollective.com/clap/tiers/bronze.svg?avatarHeight=36&width=600)](https://opencollective.com/clap)
<!-- omit in TOC -->
### Backer
[![](https://opencollective.com/clap/tiers/backer.svg?avatarHeight=36&width=600)](https://opencollective.com/clap)
Reference in a new issue Copy permalink