Mirrors/clap
2
0
Fork 0
mirror of https://github.com/clap-rs/clap synced 2024-11-10 06:44:16 +00:00
Code Issues Projects Releases Packages Wiki Activity
clap/README.md

168 lines
7.3 KiB
Markdown
Raw Normal View History

Update README for beta release
2020-03-02 08:52:15 +00:00
<!-- omit in TOC -->
# clap
This breaks for rustdoc
2015-03-18 23:43:33 +00:00
docs: Focus top-level README
2021-11-30 03:05:42 +00:00
> **Command Line Argument Parser for Rust**
Update README for beta release
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)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue?style=flat-square)](https://github.com/clap-rs/clap/blob/master/LICENSE-APACHE)
[![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](https://github.com/clap-rs/clap/blob/master/LICENSE-MIT)
chore: CI improvements
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)
Update README for beta release
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)
Update badges
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)
This breaks for rustdoc
2015-03-18 23:43:33 +00:00
docs: Focus top-level README
2021-11-30 03:05:42 +00:00
Dual-licensed under [Apache 2.0](LICENSE-APACHE) or [MIT](LICENSE-MIT).
Update README for beta release
2020-03-02 08:52:15 +00:00
1. [About](#about)
docs: Re-work examples This creates distinct tutorial examples from complex feature examples (more how-tos). Both sets are getting builder / derive versions (at least the critical ones).
2021-11-30 18:30:19 +00:00
2. Tutorial: [Builder API](https://github.com/clap-rs/clap/blob/master/examples/tutorial_builder/README.md), [Derive API](https://github.com/clap-rs/clap/blob/master/examples/tutorial_derive/README.md)
3. [Examples](https://github.com/clap-rs/clap/blob/master/examples/README.md)
4. [API Reference](https://docs.rs/clap)
docs: Add Derive API reference I took more inspiration for organization from `serde.rs` than `docs.rs/structopt`.
2021-12-01 20:31:06 +00:00
- [Derive Reference](https://github.com/clap-rs/clap/blob/master/examples/derive_ref/README.md)
docs: Focus top-level README
2021-11-30 03:05:42 +00:00
- [Feature Flags](#feature-flags)
docs: Re-work examples This creates distinct tutorial examples from complex feature examples (more how-tos). Both sets are getting builder / derive versions (at least the critical ones).
2021-11-30 18:30:19 +00:00
5. [CHANGELOG](https://github.com/clap-rs/clap/blob/master/docs/CHANGELOG.md)
6. [FAQ](https://github.com/clap-rs/clap/blob/master/docs/FAQ.md)
7. [Questions & Discussions](https://github.com/clap-rs/clap/discussions)
docs: Focus top-level README
2021-11-30 03:05:42 +00:00
8. [Contributing](https://github.com/clap-rs/clap/blob/master/CONTRIBUTING.md)
docs: Add back sponsors
2021-12-07 21:05:03 +00:00
8. [Sponsors](#sponsors)
docs: adds "whats new" section to readme
2015-06-30 02:22:13 +00:00
docs(README.md): add video tutorial section
2015-04-06 17:39:13 +00:00
## About
docs: Focus top-level README
2021-11-30 03:05:42 +00:00
Create your command-line parser, with all of the bells and whistles, declaratively or procedurally.
docs(README): adds details about optional and new features
2015-05-05 23:31:41 +00:00
docs: Focus top-level README
2021-11-30 03:05:42 +00:00
### Example
docs(README.md): updates readme for v2 release Closes #393
2016-01-27 21:37:09 +00:00
docs: Focus top-level README
2021-11-30 03:05:42 +00:00
<!-- Copied from examples/demo.{rs,md} -->
test: Compile example in README
2021-10-23 15:46:26 +00:00
```rust,no_run
docs: Prefer `global_setting` I've been finding I've been setting `AppSettings` without it which is likely leading to bugs. This tries to raise the visibility by using it based on the setting being used and not whether the application needs it.
2021-11-29 22:10:52 +00:00
use clap::Parser;
docs(README.md): stars the v3 update of the docs
2018-08-02 03:05:52 +00:00
fix(derive)!: Rename `Clap` to `Parser`. Before #2005, `Clap` was a special trait that derived all clap traits it detected were relevant (including an enum getting both `ArgEnum`, `Clap`, and `Subcommand`). Now, we have elevated `Clap`, `Args`, `Subcommand`, and `ArgEnum` to be user facing but the name `Clap` isn't very descriptive. This also helps further clarify the relationships so a crate providing an item to be `#[clap(flatten)]` or `#[clap(subcommand)]` is more likely to choose the needed trait to derive. Also, my proposed fix fo #2785 includes making `App` attributes almost exclusively for `Clap`. Clarifying the names/roles will help communicate this. For prior discussion, see #2583
2021-07-13 17:50:55 +00:00
#[derive(Parser)]
docs: Focus top-level README
2021-11-30 03:05:42 +00:00
#[clap(about, version, author)] // Pull these from `Cargo.toml`
struct Cli {
docs(README.md): stars the v3 update of the docs
2018-08-02 03:05:52 +00:00
/// Sets a custom config file. Could have been an Option<T> with no default too
docs: Focus top-level README
2021-11-30 03:05:42 +00:00
#[clap(short, long, default_value = "default.toml", value_name = "PATH")]
config: std::path::PathBuf,
docs(README.md): stars the v3 update of the docs
2018-08-02 03:05:52 +00:00
/// Some input. Because this isn't an Option<T> it's required to be used
Fix yaml docs
2019-10-25 17:53:17 +00:00
input: String,
docs(README.md): stars the v3 update of the docs
2018-08-02 03:05:52 +00:00
/// A level of verbosity, and can be used multiple times
Update README for beta release
2020-03-02 08:52:15 +00:00
#[clap(short, long, parse(from_occurrences))]
docs(README.md): fixes the custom derive example in the readme Closes #1589
2019-10-31 00:26:41 +00:00
verbose: i32,
}
docs(README.md): stars the v3 update of the docs
2018-08-02 03:05:52 +00:00
fn main() {
docs: Focus top-level README
2021-11-30 03:05:42 +00:00
let args = Cli::parse();
docs(README.md): stars the v3 update of the docs
2018-08-02 03:05:52 +00:00
docs: Focus top-level README
2021-11-30 03:05:42 +00:00
println!("Value for config: {}", args.config.display());
println!("Using input file: {}", args.input);
docs(README.md): stars the v3 update of the docs
2018-08-02 03:05:52 +00:00
// Vary the output based on how many times the user used the "verbose" flag
// (i.e. 'myprog -v -v -v' or 'myprog -vvv' vs 'myprog -v'
docs: Focus top-level README
2021-11-30 03:05:42 +00:00
match args.verbose {
docs(README.md): stars the v3 update of the docs
2018-08-02 03:05:52 +00:00
0 => println!("No verbose info"),
1 => println!("Some verbose info"),
2 => println!("Tons of verbose info"),
Change some wording to be more inclusive
2021-07-15 21:03:25 +00:00
_ => println!("Don't be ridiculous"),
docs(README.md): stars the v3 update of the docs
2018-08-02 03:05:52 +00:00
}
// more program logic goes here...
}
```
docs: Note feature needed in demo
2021-12-07 21:02:14 +00:00
*(note: requires feature `derive`)*
docs: Focus top-level README
2021-11-30 03:05:42 +00:00
```bash
$ demo --help
clap [..]
docs(README.md): stars the v3 update of the docs
2018-08-02 03:05:52 +00:00
docs: Remove author fields
2021-12-06 17:11:56 +00:00
Update README for beta release
2020-03-02 08:52:15 +00:00
docs: Focus top-level README
2021-11-30 03:05:42 +00:00
A simple to use, efficient, and full-featured Command Line Argument Parser
Updated readme
2015-03-01 00:22:23 +00:00
docs: Focus top-level README
2021-11-30 03:05:42 +00:00
USAGE:
demo[EXE] [OPTIONS] <INPUT>
Update README.md
2015-03-16 14:38:43 +00:00
docs(README.md): stars the v3 update of the docs
2018-08-02 03:05:52 +00:00
ARGS:
docs: Focus top-level README
2021-11-30 03:05:42 +00:00
<INPUT> Some input. Because this isn't an Option<T> it's required to be used
docs(README): adds details about optional and new features
2015-05-05 23:31:41 +00:00
Update README.md
2015-03-16 14:38:43 +00:00
OPTIONS:
docs: Focus top-level README
2021-11-30 03:05:42 +00:00
-c, --config <PATH> Sets a custom config file. Could have been an Option<T> with no default
too [default: default.toml]
fix(help)!: Merge OPTIONS / FLAGS default groups For those that want the original behavior, you can usxe `arg.help_heading(Some("FLAGS"))` on your flags. Limitations: - This will not give you a special sort order - This will not get a `[FLAGS]` added to usage For templates, we removed `{unified}` and `{flags}`. To help people catch these, a debug_assert was added. I'm unsure but I think there might be a change in behavior in calcuating when to show `[OPTION]` in usage. The old code only looked at `required` while flags looked only at arg groups. We now look at both. Ideally we'd add these in `_build` and remove special casing for no-groups except in the sort order of groups. I feel like thats best left for later. This also reduced the scope of `App`s public API. `get_*_with_no_heading` seemed a bit specialized to be in the public API. #2853 looks at splitting it out into its own PR. BREAKING CHANGE: Multiple - `UnifiedHelpMessage` removed - `{flags}` and `{unified}` are removed and will assert when present. - `get_*_with_no_heading` removed Fixes #2807
2021-10-11 22:01:33 +00:00
-h, --help Print help information
docs: Focus top-level README
2021-11-30 03:05:42 +00:00
-v, --verbose A level of verbosity, and can be used multiple times
fix(help)!: Merge OPTIONS / FLAGS default groups For those that want the original behavior, you can usxe `arg.help_heading(Some("FLAGS"))` on your flags. Limitations: - This will not give you a special sort order - This will not get a `[FLAGS]` added to usage For templates, we removed `{unified}` and `{flags}`. To help people catch these, a debug_assert was added. I'm unsure but I think there might be a change in behavior in calcuating when to show `[OPTION]` in usage. The old code only looked at `required` while flags looked only at arg groups. We now look at both. Ideally we'd add these in `_build` and remove special casing for no-groups except in the sort order of groups. I feel like thats best left for later. This also reduced the scope of `App`s public API. `get_*_with_no_heading` seemed a bit specialized to be in the public API. #2853 looks at splitting it out into its own PR. BREAKING CHANGE: Multiple - `UnifiedHelpMessage` removed - `{flags}` and `{unified}` are removed and will assert when present. - `get_*_with_no_heading` removed Fixes #2807
2021-10-11 22:01:33 +00:00
-V, --version Print version information
Update README.md
2015-03-16 14:38:43 +00:00
```
docs: Focus top-level README
2021-11-30 03:05:42 +00:00
*(version number and `.exe` extension on windows replaced by placeholders)*
Updated readme and removed Cargo.lock from git
2015-03-01 00:33:18 +00:00
docs: Focus top-level README
2021-11-30 03:05:42 +00:00
### Aspirations
docs(groups): adds documentation for ArgGroups
2015-04-28 02:52:50 +00:00
docs: Focus top-level README
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
docs: Expand on aspirations
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
docs: Expand breaking change window
2021-12-07 21:03:34 +00:00
- We follow semver and will wait about 6-9 months between major breaking changes
docs: Be explicit about current MSRV
2021-12-07 21:03:12 +00:00
- We will support the last two minor Rust releases (MSRV, currently 1.54.0)
docs(groups): adds documentation for ArgGroups
2015-04-28 02:52:50 +00:00
docs: Focus top-level README
2021-11-30 03:05:42 +00:00
While these aspirations can be at odds with fast build times and low binary
docs: Expand on aspirations
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
docs: Focus top-level README
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.
docs(groups): adds documentation for ArgGroups
2015-04-28 02:52:50 +00:00
docs: Focus top-level README
2021-11-30 03:05:42 +00:00
### Related Projects
Updated readme and removed Cargo.lock from git
2015-03-01 00:33:18 +00:00
docs: Add more crates
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)
docs: Focus top-level README
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)
docs(README): adds details about optional and new features
2015-05-05 23:31:41 +00:00
docs: Focus top-level README
2021-11-30 03:05:42 +00:00
## Feature Flags
Add env feature gate
2021-08-14 00:04:49 +00:00
docs: Focus top-level README
2021-11-30 03:05:42 +00:00
### Default Features
docs: Improve documentation around features * Clap has dependencies even with all features disabled. * The "nightly" feature does nothing, so don't mention it. * Explain the difference between "unstable" and "nightly" better. * Split features into groups (default, opt-in, clap-development). * For contributors: update what tests should be run, and remove make command. * Removes a repeated word and splits up some long markdown lines. Also groups features by category and dependencies by feature in Cargo.toml.
2016-10-15 02:58:36 +00:00
Add env feature gate
2021-08-14 00:04:49 +00:00
* **std**: _Not Currently Used._ Placeholder for supporting `no_std` environments in a backwards compatible manner.
docs: Focus top-level README
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.
docs(README): adds details about optional and new features
2015-05-05 23:31:41 +00:00
docs: Focus top-level README
2021-11-30 03:05:42 +00:00
#### Optional features
docs(README): adds details about optional and new features
2015-05-05 23:31:41 +00:00
docs: Focus top-level README
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.
fix!: Lighten clap's default feature set Too many times people have to disable default features. Let's try to have a more minimal out of box experience. - `derive`: people are already used to adding this feature for serde - `cargo`: not needed for derive - `env`: most probably don't use this - `unicode`: most CLIs are probably ASCII. We should do a debug warn about this though BREAKING CHANGE: `derive`, `cargo`, `env`, and `unicode` are no longer on by default.
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.
docs: Focus top-level README
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.
docs(README): adds details about optional and new features
2015-05-05 23:31:41 +00:00
fix: Gate App::replace We are concerned about the level of polish of this feature and are unsure enough about its future, we've decided to gate it to unblock the v3 release.
2021-10-09 15:44:31 +00:00
#### Experimental features
docs: Focus top-level README
2021-11-30 03:05:42 +00:00
**Warning:** These may contain breaking changes between minor releases.
chore: CI improvements
2021-10-09 18:50:16 +00:00
fix: Gate App::replace We are concerned about the level of polish of this feature and are unsure enough about its future, we've decided to gate it to unblock the v3 release.
2021-10-09 15:44:31 +00:00
* **unstable-replace**: Enable [`App::replace`](https://github.com/clap-rs/clap/issues/2836)
fixup! Fill in tracking issue number
2021-10-12 19:51:26 +00:00
* **unstable-multicall**: Enable [`AppSettings::Multicall`](https://github.com/clap-rs/clap/issues/2861)
Put `grouped_values_of` behind a feature gate There is enough open work on this, we should probably not have it public yet, so putting it behind a gate. See https://github.com/clap-rs/clap/issues/2924
2021-10-23 15:01:55 +00:00
* **unstable-grouped**: Enable [`ArgMatches::grouped_values_of`](https://github.com/clap-rs/clap/issues/2924)
docs: Add back sponsors
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)
Reference in a new issue Copy permalink