| <!-- omit in TOC --> |
| # clap |
| |
| > **Command Line Argument Parser for Rust** |
| |
| [](https://crates.io/crates/clap) |
| [](https://crates.io/crates/clap) |
| [](https://github.com/clap-rs/clap/blob/v3.2.6/LICENSE-APACHE) |
| [](https://github.com/clap-rs/clap/blob/v3.2.6/LICENSE-MIT) |
| [](https://github.com/clap-rs/clap/actions/workflows/ci.yml?query=branch%3Astaging) |
| [](https://coveralls.io/github/clap-rs/clap?branch=master) |
| [](https://github.com/clap-rs/clap/graphs/contributors) |
| |
| Dual-licensed under [Apache 2.0](LICENSE-APACHE) or [MIT](LICENSE-MIT). |
| |
| 1. [About](#about) |
| 2. Tutorial: [Builder API](https://github.com/clap-rs/clap/blob/v3.2.6/examples/tutorial_builder/README.md), [Derive API](https://github.com/clap-rs/clap/blob/v3.2.6/examples/tutorial_derive/README.md) |
| 3. [Examples](https://github.com/clap-rs/clap/blob/v3.2.6/examples/README.md) |
| 4. [API Reference](https://docs.rs/clap) |
| - [Derive Reference](https://github.com/clap-rs/clap/blob/v3.2.6/examples/derive_ref/README.md) |
| - [Feature Flags](#feature-flags) |
| 5. [CHANGELOG](https://github.com/clap-rs/clap/blob/v3.2.6/CHANGELOG.md) |
| 6. [FAQ](https://github.com/clap-rs/clap/blob/v3.2.6/docs/FAQ.md) |
| 7. [Questions & Discussions](https://github.com/clap-rs/clap/discussions) |
| 8. [Contributing](https://github.com/clap-rs/clap/blob/v3.2.6/CONTRIBUTING.md) |
| 8. [Sponsors](#sponsors) |
| |
| ## About |
| |
| Create your command-line parser, with all of the bells and whistles, declaratively or procedurally. |
| |
| ### Example |
| |
| This uses our |
| [Derive API](https://github.com/clap-rs/clap/blob/v3.2.6/examples/tutorial_derive/README.md) |
| which provides access to the [Builder API](https://github.com/clap-rs/clap/blob/v3.2.6/examples/tutorial_builder/README.md) as attributes on a `struct`: |
| |
| <!-- Copied from examples/demo.{rs,md} --> |
| ```rust,no_run |
| use clap::Parser; |
| |
| /// Simple program to greet a person |
| #[derive(Parser, Debug)] |
| #[clap(author, version, about, long_about = None)] |
| struct Args { |
| /// Name of the person to greet |
| #[clap(short, long, value_parser)] |
| name: String, |
| |
| /// Number of times to greet |
| #[clap(short, long, value_parser, default_value_t = 1)] |
| count: u8, |
| } |
| |
| fn main() { |
| let args = Args::parse(); |
| |
| for _ in 0..args.count { |
| println!("Hello {}!", args.name) |
| } |
| } |
| ``` |
| Add this to `Cargo.toml`: |
| ```toml |
| [dependencies] |
| clap = { version = "3.2.6", features = ["derive"] } |
| ``` |
| ```bash |
| $ demo --help |
| clap [..] |
| Simple program to greet a person |
| |
| USAGE: |
| demo[EXE] [OPTIONS] --name <NAME> |
| |
| OPTIONS: |
| -c, --count <COUNT> Number of times to greet [default: 1] |
| -h, --help Print help information |
| -n, --name <NAME> Name of the person to greet |
| -V, --version Print version information |
| ``` |
| *(version number and `.exe` extension on windows replaced by placeholders)* |
| |
| ### Aspirations |
| |
| - 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_complete), etc |
| - Flexible enough to port your existing CLI interface |
| - However, we won't necessarily streamline support for each use case |
| - Reasonable parse performance |
| - 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 |
| - We follow semver and will wait about 6-9 months between major breaking changes |
| - We will support the last two minor Rust releases (MSRV, currently 1.56.1) |
| |
| While these aspirations can be at odds with fast build times and low binary |
| size, we will still strive to keep these reasonable for the flexibility you |
| get. Check out the |
| [argparse-benchmarks](https://github.com/rust-cli/argparse-benchmarks-rs) for |
| CLI parsers optimized for other use cases. |
| |
| ### Selecting an API |
| |
| Why use the declarative [Derive API](https://github.com/clap-rs/clap/blob/v3.2.6/examples/tutorial_derive/README.md): |
| - Easier to read, write, and modify |
| - Easier to keep the argument declaration and reading of argument in sync |
| - Easier to reuse, e.g. [clap-verbosity-flag](https://crates.io/crates/clap-verbosity-flag) |
| |
| Why use the procedural [Builder API](https://github.com/clap-rs/clap/blob/v3.2.6/examples/tutorial_builder/README.md): |
| - Faster compile times if you aren't already using other procedural macros |
| - More flexible, e.g. you can look up how many times an argument showed up, |
| what its values were, and what were the indexes of those values. The Derive |
| API can only report presence, number of occurrences, or values but no indices |
| or combinations of data. |
| |
| ### Related Projects |
| |
| - [wild](https://crates.io/crates/wild) for supporting wildcards (`*`) on Windows like you do Linux |
| - [argfile](https://crates.io/crates/argfile) for loading additional arguments from a file (aka response files) |
| - [shadow-rs](https://crates.io/crates/shadow-rs) for generating `Command::long_version` |
| - [clap_lex](https://crates.io/crates/clap_lex) for a lighter-weight, battle-tested CLI parser |
| - [clap_mangen](https://crates.io/crates/clap_mangen) for generating man page source (roff) |
| - [clap_complete](https://crates.io/crates/clap_complete) for shell completion support |
| - [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) |
| - [Command-line Apps for Rust](https://rust-cli.github.io/book/index.html) book |
| - [`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) |
| |
| ## Feature Flags |
| |
| ### Default Features |
| |
| * **std**: _Not Currently Used._ Placeholder for supporting `no_std` environments in a backwards compatible manner. |
| * **color**: Turns on colored error messages. |
| * **suggestions**: Turns on the `Did you mean '--myoption'?` feature for when users make typos. |
| |
| #### Optional features |
| |
| * **deprecated**: Guided experience to prepare for next breaking release (at different stages of development, this may become default) |
| * **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. |
| * **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 |
| |
| **Warning:** These may contain breaking changes between minor releases. |
| |
| * **unstable-replace**: Enable [`Command::replace`](https://github.com/clap-rs/clap/issues/2836) |
| * **unstable-grouped**: Enable [`ArgMatches::grouped_values_of`](https://github.com/clap-rs/clap/issues/2924) |
| * **unstable-v4**: Preview features which will be stable on the v4.0 release |
| |
| ## Sponsors |
| |
| <!-- omit in TOC --> |
| ### Gold |
| |
| [](https://opencollective.com/clap) |
| |
| <!-- omit in TOC --> |
| ### Silver |
| |
| [](https://opencollective.com/clap) |
| |
| <!-- omit in TOC --> |
| ### Bronze |
| |
| [](https://opencollective.com/clap) |
| |
| <!-- omit in TOC --> |
| ### Backer |
| |
| [](https://opencollective.com/clap) |
