clap/README.md

152 lines
6.5 KiB
Markdown
Raw Normal View History

2020-03-02 08:52:15 +00:00
<!-- omit in TOC -->
# clap
2015-03-18 23:43:33 +00:00
2021-11-30 03:05:42 +00:00
> **Command Line Argument Parser for Rust**
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)
2021-12-09 13:00:33 +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.0-rc.1/LICENSE-APACHE)
[![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](https://github.com/clap-rs/clap/blob/v3.0.0-rc.1/LICENSE-MIT)
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)
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)
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)
2015-03-18 23:43:33 +00:00
2021-11-30 03:05:42 +00:00
Dual-licensed under [Apache 2.0](LICENSE-APACHE) or [MIT](LICENSE-MIT).
2020-03-02 08:52:15 +00:00
1. [About](#about)
2021-12-09 13:00:33 +00:00
2. Tutorial: [Builder API](https://github.com/clap-rs/clap/blob/v3.0.0-rc.1/examples/tutorial_builder/README.md), [Derive API](https://github.com/clap-rs/clap/blob/v3.0.0-rc.1/examples/tutorial_derive/README.md)
3. [Examples](https://github.com/clap-rs/clap/blob/v3.0.0-rc.1/examples/README.md)
4. [API Reference](https://docs.rs/clap)
2021-12-09 13:00:33 +00:00
- [Derive Reference](https://github.com/clap-rs/clap/blob/v3.0.0-rc.1/examples/derive_ref/README.md)
2021-11-30 03:05:42 +00:00
- [Feature Flags](#feature-flags)
2021-12-09 13:00:33 +00:00
5. [CHANGELOG](https://github.com/clap-rs/clap/blob/v3.0.0-rc.1/docs/CHANGELOG.md)
6. [FAQ](https://github.com/clap-rs/clap/blob/v3.0.0-rc.1/docs/FAQ.md)
7. [Questions & Discussions](https://github.com/clap-rs/clap/discussions)
2021-12-09 13:00:33 +00:00
8. [Contributing](https://github.com/clap-rs/clap/blob/v3.0.0-rc.1/CONTRIBUTING.md)
2021-12-07 21:05:03 +00:00
8. [Sponsors](#sponsors)
## About
2021-11-30 03:05:42 +00:00
Create your command-line parser, with all of the bells and whistles, declaratively or procedurally.
2021-11-30 03:05:42 +00:00
### Example
2021-11-30 03:05:42 +00:00
<!-- Copied from examples/demo.{rs,md} -->
2021-10-23 15:46:26 +00:00
```rust,no_run
use clap::Parser;
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,
}
fn main() {
2021-12-07 21:34:23 +00:00
let args = Args::parse();
2021-12-07 21:34:23 +00:00
for _ in 0..args.count {
println!("Hello {}!", args.name)
}
}
```
2021-12-07 21:02:14 +00:00
*(note: requires feature `derive`)*
2021-11-30 03:05:42 +00:00
```bash
$ demo --help
clap [..]
2021-11-30 03:05:42 +00:00
A simple to use, efficient, and full-featured Command Line Argument Parser
2015-03-01 00:22:23 +00:00
2021-11-30 03:05:42 +00:00
USAGE:
2021-12-07 21:34:23 +00:00
demo[EXE] [OPTIONS] --name <NAME>
2015-03-16 14:38:43 +00:00
OPTIONS:
2021-12-07 21:34:23 +00:00
-c, --count <COUNT> Number of times to greet [default: 1]
-h, --help Print help information
2021-12-07 21:34:23 +00:00
-n, --name <NAME> Name of the person to greet
-V, --version Print version information
2015-03-16 14:38:43 +00:00
```
2021-11-30 03:05:42 +00:00
*(version number and `.exe` extension on windows replaced by placeholders)*
2021-11-30 03:05:42 +00:00
### Aspirations
2021-11-30 03:05:42 +00:00
- Out of the box, users get a polished CLI experience
- Including common argument behavior, help generation, suggested fixes for users, colored output, [shell completions](https://github.com/clap-rs/clap/tree/master/clap_generate), etc
- Flexible enough to port your existing CLI interface
- However, we won't necessarily streamline support for each use case
- Reasonable parse performance
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
2021-12-07 21:03:34 +00:00
- We follow semver and will wait about 6-9 months between major breaking changes
2021-12-07 21:03:12 +00:00
- We will support the last two minor Rust releases (MSRV, currently 1.54.0)
2021-11-30 03:05:42 +00:00
While these aspirations can be at odds with fast build times and low binary
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
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.
2021-11-30 03:05:42 +00:00
### Related Projects
2021-12-01 13:15:51 +00:00
- [clap-verbosity-flag](https://github.com/rust-cli/clap-verbosity-flag)
- [clap-cargo](https://github.com/crate-ci/clap-cargo)
- [concolor-clap](https://github.com/rust-cli/concolor/tree/main/crates/clap)
2021-11-30 03:05:42 +00:00
- [Command-line Apps for Rust](https://rust-cli.github.io/book/index.html) book
- [`trycmd`](https://github.com/epage/trycmd): Snapshot testing
- Or for more control, [`assert_cmd`](https://github.com/assert-rs/assert_cmd) and [`assert_fs`](https://github.com/assert-rs/assert_fs)
2021-11-30 03:05:42 +00:00
## Feature Flags
2021-08-14 00:04:49 +00:00
2021-11-30 03:05:42 +00:00
### Default Features
2021-08-14 00:04:49 +00:00
* **std**: _Not Currently Used._ Placeholder for supporting `no_std` environments in a backwards compatible manner.
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.
2021-11-30 03:05:42 +00:00
#### Optional features
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.
* **cargo**: Turns on macros that read values from `CARGO_*` environment variables.
* **env**: Turns on the usage of environment variables during parsing.
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.
#### Experimental features
2021-11-30 03:05:42 +00:00
**Warning:** These may contain breaking changes between minor releases.
2021-10-09 18:50:16 +00:00
* **unstable-replace**: Enable [`App::replace`](https://github.com/clap-rs/clap/issues/2836)
2021-10-12 19:51:26 +00:00
* **unstable-multicall**: Enable [`AppSettings::Multicall`](https://github.com/clap-rs/clap/issues/2861)
* **unstable-grouped**: Enable [`ArgMatches::grouped_values_of`](https://github.com/clap-rs/clap/issues/2924)
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)