From 36d22d82aa202bb199967e9512281e9a53db42c9 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 21:33:14 +0200 Subject: Adding upstream version 115.7.0esr. Signed-off-by: Daniel Baumann --- third_party/rust/clap/README.md | 179 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 179 insertions(+) create mode 100644 third_party/rust/clap/README.md (limited to 'third_party/rust/clap/README.md') diff --git a/third_party/rust/clap/README.md b/third_party/rust/clap/README.md new file mode 100644 index 0000000000..ee6d9f3d8c --- /dev/null +++ b/third_party/rust/clap/README.md @@ -0,0 +1,179 @@ + +# clap + +> **Command Line Argument Parser for Rust** + +[![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) +[![License](https://img.shields.io/badge/license-Apache%202.0-blue?style=flat-square)](https://github.com/clap-rs/clap/blob/v3.1.18/LICENSE-APACHE) +[![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](https://github.com/clap-rs/clap/blob/v3.1.18/LICENSE-MIT) +[![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) +[![Coverage Status](https://img.shields.io/coveralls/github/clap-rs/clap/master?style=flat-square)](https://coveralls.io/github/clap-rs/clap?branch=master) +[![Contributors](https://img.shields.io/github/contributors/clap-rs/clap?style=flat-square)](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.18/examples/tutorial_builder/README.md), [Derive API](https://github.com/clap-rs/clap/blob/v3.1.18/examples/tutorial_derive/README.md) +3. [Examples](https://github.com/clap-rs/clap/blob/v3.1.18/examples/README.md) +4. [API Reference](https://docs.rs/clap) + - [Derive Reference](https://github.com/clap-rs/clap/blob/v3.1.18/examples/derive_ref/README.md) + - [Feature Flags](#feature-flags) +5. [CHANGELOG](https://github.com/clap-rs/clap/blob/v3.1.18/CHANGELOG.md) +6. [FAQ](https://github.com/clap-rs/clap/blob/v3.1.18/docs/FAQ.md) +7. [Questions & Discussions](https://github.com/clap-rs/clap/discussions) +8. [Contributing](https://github.com/clap-rs/clap/blob/v3.1.18/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.18/examples/tutorial_derive/README.md) +which provides access to the [Builder API](https://github.com/clap-rs/clap/blob/v3.1.18/examples/tutorial_builder/README.md) as attributes on a `struct`: + + +```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.18", features = ["derive"] } +``` +```bash +$ demo --help +clap [..] +Simple program to greet a person + +USAGE: + demo[EXE] [OPTIONS] --name + +OPTIONS: + -c, --count Number of times to greet [default: 1] + -h, --help Print help information + -n, --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.18/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.18/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 + +* **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 + + +### Gold + +[![](https://opencollective.com/clap/tiers/gold.svg?avatarHeight=36&width=600)](https://opencollective.com/clap) + + +### Silver + +[![](https://opencollective.com/clap/tiers/silver.svg?avatarHeight=36&width=600)](https://opencollective.com/clap) + + +### Bronze + +[![](https://opencollective.com/clap/tiers/bronze.svg?avatarHeight=36&width=600)](https://opencollective.com/clap) + + +### Backer + +[![](https://opencollective.com/clap/tiers/backer.svg?avatarHeight=36&width=600)](https://opencollective.com/clap) -- cgit v1.2.3