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-10 21:25:23 +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.4/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.4/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-10 21:25:23 +00:00
2. Tutorial: [Builder API ](https://github.com/clap-rs/clap/blob/v3.0.0-rc.4/examples/tutorial_builder/README.md ), [Derive API ](https://github.com/clap-rs/clap/blob/v3.0.0-rc.4/examples/tutorial_derive/README.md )
3. [Examples ](https://github.com/clap-rs/clap/blob/v3.0.0-rc.4/examples/README.md )
2021-11-30 18:30:19 +00:00
4. [API Reference ](https://docs.rs/clap )
2021-12-10 21:25:23 +00:00
- [Derive Reference ](https://github.com/clap-rs/clap/blob/v3.0.0-rc.4/examples/derive_ref/README.md )
2021-11-30 03:05:42 +00:00
- [Feature Flags ](#feature-flags )
2021-12-10 21:25:23 +00:00
5. [CHANGELOG ](https://github.com/clap-rs/clap/blob/v3.0.0-rc.4/CHANGELOG.md )
6. [FAQ ](https://github.com/clap-rs/clap/blob/v3.0.0-rc.4/docs/FAQ.md )
2021-11-30 18:30:19 +00:00
7. [Questions & Discussions ](https://github.com/clap-rs/clap/discussions )
2021-12-10 21:25:23 +00:00
8. [Contributing ](https://github.com/clap-rs/clap/blob/v3.0.0-rc.4/CONTRIBUTING.md )
2021-12-07 21:05:03 +00:00
8. [Sponsors ](#sponsors )
2015-06-30 02:22:13 +00:00
2015-04-06 17:39:13 +00:00
## About
2021-11-30 03:05:42 +00:00
Create your command-line parser, with all of the bells and whistles, declaratively or procedurally.
2015-05-05 23:31:41 +00:00
2021-11-30 03:05:42 +00:00
### Example
2016-01-27 21:37:09 +00:00
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
2021-11-29 22:10:52 +00:00
use clap::Parser;
2018-08-02 03:05:52 +00:00
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,
2019-10-31 00:26:41 +00:00
}
2018-08-02 03:05:52 +00:00
fn main() {
2021-12-07 21:34:23 +00:00
let args = Args::parse();
2018-08-02 03:05:52 +00:00
2021-12-07 21:34:23 +00:00
for _ in 0..args.count {
println!("Hello {}!", args.name)
}
2018-08-02 03:05:52 +00:00
}
```
2021-12-07 21:02:14 +00:00
*(note: requires feature `derive` )*
2021-11-30 03:05:42 +00:00
```bash
$ demo --help
clap [..]
2018-08-02 03:05:52 +00:00
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-05-05 23:31:41 +00:00
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]
2021-10-11 22:01:33 +00:00
-h, --help Print help information
2021-12-07 21:34:23 +00:00
-n, --name < NAME > Name of the person to greet
2021-10-11 22:01:33 +00:00
-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)*
2015-03-01 00:33:18 +00:00
2021-11-30 03:05:42 +00:00
### Aspirations
2015-04-28 02:52:50 +00:00
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)
2015-04-28 02:52:50 +00:00
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.
2015-04-28 02:52:50 +00:00
2021-11-30 03:05:42 +00:00
### Related Projects
2015-03-01 00:33:18 +00:00
2021-12-10 00:57:16 +00:00
- [wild ](https://crates.io/crates/wild ) for supporting wildcards (`*`) on Windows like you do Linux
2021-12-11 15:12:26 +00:00
- [argfile ](https://crates.io/crates/argfile ) for loading additional arguments from a file (aka response files)
2021-12-12 00:59:28 +00:00
- [clap_generate ](https://crates.io/crates/clap_generate ) for shell completion support
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 )
2021-11-30 03:05:42 +00:00
- [Command-line Apps for Rust ](https://rust-cli.github.io/book/index.html ) book
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 )
2015-05-05 23:31:41 +00:00
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
2016-10-15 02:58:36 +00:00
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.
2015-05-05 23:31:41 +00:00
2021-11-30 03:05:42 +00:00
#### Optional features
2015-05-05 23:31:41 +00:00
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.
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.
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.
2015-05-05 23:31:41 +00:00
2021-10-09 15:44:31 +00:00
#### 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
2021-10-09 15:44:31 +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 )
2021-10-23 15:01:55 +00:00
* **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)