mirror of
https://github.com/clap-rs/clap
synced 2024-11-14 00:27:13 +00:00
178 lines
8 KiB
Markdown
178 lines
8 KiB
Markdown
<!-- 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.1.7/LICENSE-APACHE)
|
|
[](https://github.com/clap-rs/clap/blob/v3.1.7/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.1.7/examples/tutorial_builder/README.md), [Derive API](https://github.com/clap-rs/clap/blob/v3.1.7/examples/tutorial_derive/README.md)
|
|
3. [Examples](https://github.com/clap-rs/clap/blob/v3.1.7/examples/README.md)
|
|
4. [API Reference](https://docs.rs/clap)
|
|
- [Derive Reference](https://github.com/clap-rs/clap/blob/v3.1.7/examples/derive_ref/README.md)
|
|
- [Feature Flags](#feature-flags)
|
|
5. [CHANGELOG](https://github.com/clap-rs/clap/blob/v3.1.7/CHANGELOG.md)
|
|
6. [FAQ](https://github.com/clap-rs/clap/blob/v3.1.7/docs/FAQ.md)
|
|
7. [Questions & Discussions](https://github.com/clap-rs/clap/discussions)
|
|
8. [Contributing](https://github.com/clap-rs/clap/blob/v3.1.7/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.1.7/examples/tutorial_derive/README.md)
|
|
which provides access to the [Builder API](https://github.com/clap-rs/clap/blob/v3.1.7/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)]
|
|
name: String,
|
|
|
|
/// Number of times to greet
|
|
#[clap(short, long, 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.1.7", 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.54.0)
|
|
|
|
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.1.7/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.1.7/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_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
|
|
|
|
* **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-multicall**: Enable [`Command::multicall`](https://github.com/clap-rs/clap/issues/2861)
|
|
* **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)
|