mirror of
https://github.com/clap-rs/clap
synced 2024-11-10 06:44:16 +00:00
docs(README.md): stars the v3 update of the docs
This commit is contained in:
Kevin K
parent
9d2d9f7a6c
commit
1ffc9556b7
1 changed files with 105 additions and 118 deletions
223
README.md
223
README.md
|
|
@ -1,10 +1,10 @@
|
|||
clap
|
||||
====
|
||||
|
||||
[](https://crates.io/crates/clap) [](https://crates.io/crates/clap) [](https://github.com/kbknapp/clap-rs/blob/master/LICENSE-APACHE) [](https://github.com/kbknapp/clap-rs/blob/master/LICENSE-MIT) [](https://coveralls.io/github/kbknapp/clap-rs?branch=master) [](https://gitter.im/kbknapp/clap-rs?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
|
||||
[](https://crates.io/crates/clap) [](https://crates.io/crates/clap) [](https://github.com/clap-rs/clap/blob/master/LICENSE-APACHE) [](https://github.com/clap-rs/clap/blob/master/LICENSE-MIT) [](https://coveralls.io/github/clap-rs/clap?branch=master) [](https://gitter.im/clap-rs/clap?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
|
||||
|
||||
Linux: [](https://travis-ci.org/kbknapp/clap-rs)
|
||||
Windows: [](https://ci.appveyor.com/project/kbknapp/clap-rs/branch/master)
|
||||
Linux: [](https://travis-ci.org/clap-rs/clap)
|
||||
Windows: [](https://ci.appveyor.com/project/clap-rs/clap/branch/master)
|
||||
|
||||
Command Line Argument Parser for Rust
|
||||
|
||||
|
|
@ -42,47 +42,9 @@ Created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc)
|
|||
|
||||
## What's New
|
||||
|
||||
Here's whats new in 2.29.2:
|
||||
Here's whats new in 3.0.0-alpha.1:
|
||||
|
||||
* **Many ZSH Completions Improvements** (Thanks to @segevfiner)
|
||||
* Positional arguments will default to file completion when not using specific values!
|
||||
* Implement postional argument possible values completion
|
||||
* Removes redundant code from output
|
||||
* Don't pass `-S` to `_arguments` if Zsh is too old
|
||||
* Fix completions with mixed positionals and subcommands
|
||||
* String escape possible values for options
|
||||
|
||||
|
||||
Here's whats new in 2.29.1:
|
||||
|
||||
* Debloats clap by deduplicating logic and refactors for a ~57% decrease in code size! This is with zero functinoality lost, and a slight perf increase!
|
||||
* Change the bash completion script code generation to support hyphens.
|
||||
* Fix completion of long option values in ZSH completions
|
||||
* Fixes broken links in docs
|
||||
* Updates contributors list
|
||||
* Fixes the ripgrep benchmark by adding a value to a flag that expects it
|
||||
|
||||
Here's whats new in 2.29.0:
|
||||
|
||||
* **Arg:** adds Arg::hide_env_values(bool) which allows one to hide any current env values and display only the key in help messages
|
||||
|
||||
Here's whats new in 2.28.0:
|
||||
|
||||
The minimum required Rust is now 1.20. This was done to start using bitflags 1.0 and having >1.0 deps is a *very good* thing!
|
||||
|
||||
* Updates `bitflags` to 1.0
|
||||
* Adds the traits to be used with the `clap-derive` crate to be able to use Custom Derive (for now must be accessed with `unstable` feature flag)
|
||||
* Adds Arg::case_insensitive(bool) which allows matching Arg::possible_values without worrying about ASCII case
|
||||
* Fixes a regression where --help couldn't be overridden
|
||||
* adds '[SUBCOMMAND]' to usage strings with only AppSettings::AllowExternalSubcommands is used with no other subcommands
|
||||
* uses `.bash` for Bash completion scripts now instead of `.bash-completion` due to convention and `.bash-completion` not being supported by completion projects
|
||||
* Fix URL path to github hosted files
|
||||
* fix typos in docs
|
||||
* **README.md:** updates the readme and pulls out some redundant sections
|
||||
* fixes a bug that allowed options to pass parsing when no value was provided
|
||||
* ignore PropagateGlobalValuesDown deprecation warning
|
||||
|
||||
For full details, see [CHANGELOG.md](https://github.com/kbknapp/clap-rs/blob/master/CHANGELOG.md)
|
||||
For full details, see [CHANGELOG.md](https://github.com/clap-rs/clap/blob/master/CHANGELOG.md)
|
||||
|
||||
## About
|
||||
|
||||
|
|
@ -94,12 +56,20 @@ Once `clap` parses the user provided string of arguments, it returns the matches
|
|||
|
||||
## FAQ
|
||||
|
||||
For a full FAQ and more in depth details, see [the wiki page](https://github.com/kbknapp/clap-rs/wiki/FAQ)
|
||||
For a full FAQ and more in depth details, see [the wiki page](https://github.com/clap-rs/clap/wiki/FAQ)
|
||||
|
||||
### Comparisons
|
||||
|
||||
First, let me say that these comparisons are highly subjective, and not meant in a critical or harsh manner. All the argument parsing libraries out there (to include `clap`) have their own strengths and weaknesses. Sometimes it just comes down to personal taste when all other factors are equal. When in doubt, try them all and pick one that you enjoy :) There's plenty of room in the Rust community for multiple implementations!
|
||||
|
||||
#### How does `clap` compare to [structopt](https://github.com/TeXitoi/structopt)?
|
||||
|
||||
Simple! `clap` *is* `stuctopt`. With the 3.0 release, `clap` imported the `structopt` code into it's own codebase as the [`clap_derive`](https://github.com/clap-rs/clap_derive) crate. Since `structopt` already used `clap` under the hood, the transition was nearly painless, and is 100% feature compatible.
|
||||
|
||||
If you were using `structopt` before, the only thing you should have to do is change the attributes from `#[structopt(...)]` to `#[clap(...)]`.
|
||||
|
||||
Also the derive statements changed from `#[derive(Structopt)]` to `#[derive(Clap)]`. There is also some additional functionality that's been added to the `clap_derive` crate. See the documentation for that crate, for more details.
|
||||
|
||||
#### How does `clap` compare to [getopts](https://github.com/rust-lang-nursery/getopts)?
|
||||
|
||||
`getopts` is a very basic, fairly minimalist argument parsing library. This isn't a bad thing, sometimes you don't need tons of features, you just want to parse some simple arguments, and have some help text generated for you based on valid arguments you specify. The downside to this approach is that you must manually implement most of the common features (such as checking to display help messages, usage strings, etc.). If you want a highly custom argument parser, and don't mind writing the majority of the functionality yourself, `getopts` is an excellent base.
|
||||
|
|
@ -128,9 +98,11 @@ Depending on the style in which you choose to define the valid arguments, `clap`
|
|||
|
||||
Below are a few of the features which `clap` supports, full descriptions and usage can be found in the [documentation](https://docs.rs/clap/) and [examples/](examples) directory
|
||||
|
||||
* Generate a CLI simply by defining a struct!
|
||||
* **Auto-generated Help, Version, and Usage information**
|
||||
- Can optionally be fully, or partially overridden if you want a custom help, version, or usage statements
|
||||
* **Auto-generated completion scripts at compile time (Bash, Zsh, Fish, and PowerShell)**
|
||||
* **Auto-generated completion scripts (Bash, Zsh, Fish, Elvish and PowerShell)**
|
||||
- Using [`clap_generate`](https://github.com/clap-rs/clap_generate)
|
||||
- Even works through many multiple levels of subcommands
|
||||
- Works with options which only accept certain values
|
||||
- Works with subcommand aliases
|
||||
|
|
@ -183,14 +155,82 @@ The following examples show a quick example of some of the very basic functional
|
|||
|
||||
**NOTE:** All of these examples are functionally the same, but show different styles in which to use `clap`. These different styles are purely a matter of personal preference.
|
||||
|
||||
The first example shows a method using the 'Builder Pattern' which allows more advanced configuration options (not shown in this small example), or even dynamically generating arguments when desired. The downside is it's more verbose.
|
||||
The first example shows the simplest way to use `clap`, by defining a struct. If you're familiar with the `structopt` crate you're in luck, it's the same! (In fact it's the exact same code running under the covers!)
|
||||
|
||||
```rust
|
||||
// (Full example with detailed comments in examples/01b_quick_example.rs)
|
||||
// (Full example with detailed comments in examples/01d_quick_example.rs)
|
||||
//
|
||||
// This example demonstrates clap's full 'builder pattern' style of creating arguments which is
|
||||
// more verbose, but allows easier editing, and at times more advanced options, or the possibility
|
||||
// to generate arguments dynamically.
|
||||
// This example demonstrates clap's full 'custom derive' style of creating arguments which is the
|
||||
// simplest method of use, but sacrifices some flexibility.
|
||||
#[macro_use]
|
||||
extern crate clap;
|
||||
|
||||
/// This doc string acts as a help message when the user runs '--help'
|
||||
/// as do all doc strings on fields
|
||||
#[derive(Clap)]
|
||||
#[clap(version = "1.0", author = "Kevin K.")]
|
||||
struct Opts {
|
||||
/// Sets a custom config file. Could have been an Option<T> with no default too
|
||||
#[clap(short = "c", long = "config", default_value = "default.conf")]
|
||||
file: String,
|
||||
/// Some input. Because this isn't an Option<T> it's required to be used
|
||||
input: String,
|
||||
/// A level of verbosity, and can be used multiple times
|
||||
#[clap(short = "v", long = "verbose", parse_from_occurrences)]
|
||||
verbose: Option<i32>,
|
||||
#[clap(subcommand)]
|
||||
subcmd: SubCommand,
|
||||
}
|
||||
|
||||
#[derive(Clap)]
|
||||
enum SubCommand {
|
||||
/// A subcommand for controlling testing
|
||||
#[clap(name = "test", version = "1.3", author = "Someone Else")]
|
||||
Test {
|
||||
/// Print debug info
|
||||
#[clap(short = "d")]
|
||||
debug: bool
|
||||
}
|
||||
}
|
||||
fn main() {
|
||||
let opts: Opts = Opts::parse();
|
||||
|
||||
// Gets a value for config if supplied by user, or defaults to "default.conf"
|
||||
println!("Value for config: {}", opts.config);
|
||||
println!("Using input file: {}", opts.input);
|
||||
|
||||
// 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'
|
||||
match opts.verbose.unwrap_or(0) {
|
||||
0 => println!("No verbose info"),
|
||||
1 => println!("Some verbose info"),
|
||||
2 => println!("Tons of verbose info"),
|
||||
3 | _ => println!("Don't be crazy"),
|
||||
}
|
||||
|
||||
// You can handle information about subcommands by requesting their matches by name
|
||||
// (as below), requesting just the name used, or both at the same time
|
||||
match matches.subcmd {
|
||||
SubCommand::Test @ t => {
|
||||
if t.debug {
|
||||
println!("Printing debug info...");
|
||||
} else {
|
||||
println!("Printing normally...");
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// more program logic goes here...
|
||||
}
|
||||
```
|
||||
|
||||
This second method shows a method using the 'Builder Pattern' which allows more advanced configuration options (not shown in this small example), or even dynamically generating arguments when desired. The downside is it's more verbose.
|
||||
|
||||
```rust
|
||||
// (Full example with detailed comments in examples/01a_quick_example.rs)
|
||||
//
|
||||
// This example demonstrates clap's "builder pattern" method of creating arguments
|
||||
// which the most flexible, but also most verbose.
|
||||
extern crate clap;
|
||||
use clap::{Arg, App, SubCommand};
|
||||
|
||||
|
|
@ -222,34 +262,7 @@ fn main() {
|
|||
.help("print debug information verbosely")))
|
||||
.get_matches();
|
||||
|
||||
// Gets a value for config if supplied by user, or defaults to "default.conf"
|
||||
let config = matches.value_of("config").unwrap_or("default.conf");
|
||||
println!("Value for config: {}", config);
|
||||
|
||||
// Calling .unwrap() is safe here because "INPUT" is required (if "INPUT" wasn't
|
||||
// required we could have used an 'if let' to conditionally get the value)
|
||||
println!("Using input file: {}", matches.value_of("INPUT").unwrap());
|
||||
|
||||
// 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'
|
||||
match matches.occurrences_of("v") {
|
||||
0 => println!("No verbose info"),
|
||||
1 => println!("Some verbose info"),
|
||||
2 => println!("Tons of verbose info"),
|
||||
3 | _ => println!("Don't be crazy"),
|
||||
}
|
||||
|
||||
// You can handle information about subcommands by requesting their matches by name
|
||||
// (as below), requesting just the name used, or both at the same time
|
||||
if let Some(matches) = matches.subcommand_matches("test") {
|
||||
if matches.is_present("debug") {
|
||||
println!("Printing debug info...");
|
||||
} else {
|
||||
println!("Printing normally...");
|
||||
}
|
||||
}
|
||||
|
||||
// more program logic goes here...
|
||||
// Same as above examples...
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -343,33 +356,7 @@ fn main() {
|
|||
}
|
||||
```
|
||||
|
||||
Last but not least there is a macro version, which is like a hybrid approach offering the runtime speed of the builder pattern (the first example), but without all the verbosity.
|
||||
|
||||
```rust
|
||||
#[macro_use]
|
||||
extern crate clap;
|
||||
|
||||
fn main() {
|
||||
let matches = clap_app!(myapp =>
|
||||
(version: "1.0")
|
||||
(author: "Kevin K. <kbknapp@gmail.com>")
|
||||
(about: "Does awesome things")
|
||||
(@arg CONFIG: -c --config +takes_value "Sets a custom config file")
|
||||
(@arg INPUT: +required "Sets the input file to use")
|
||||
(@arg debug: -d ... "Sets the level of debugging information")
|
||||
(@subcommand test =>
|
||||
(about: "controls testing features")
|
||||
(version: "1.3")
|
||||
(author: "Someone E. <someone_else@other.com>")
|
||||
(@arg verbose: -v --verbose "Print test information verbosely")
|
||||
)
|
||||
).get_matches();
|
||||
|
||||
// Same as before...
|
||||
}
|
||||
```
|
||||
|
||||
If you were to compile any of the above programs and run them with the flag `--help` or `-h` (or `help` subcommand, since we defined `test` as a subcommand) the following would be output
|
||||
If you were to compile any of the above programs and run them with the flag `--help` or `-h` (or `help` subcommand, since we defined `test` as a subcommand) the following would be output (except the first example where the help message sort of explains the Rust code).
|
||||
|
||||
```sh
|
||||
$ myprog --help
|
||||
|
|
@ -377,6 +364,9 @@ My Super Program 1.0
|
|||
Kevin K. <kbknapp@gmail.com>
|
||||
Does awesome things
|
||||
|
||||
ARGS:
|
||||
INPUT The input file to use
|
||||
|
||||
USAGE:
|
||||
MyApp [FLAGS] [OPTIONS] <INPUT> [SUBCOMMAND]
|
||||
|
||||
|
|
@ -388,9 +378,6 @@ FLAGS:
|
|||
OPTIONS:
|
||||
-c, --config <FILE> Sets a custom config file
|
||||
|
||||
ARGS:
|
||||
INPUT The input file to use
|
||||
|
||||
SUBCOMMANDS:
|
||||
help Prints this message or the help of the given subcommand(s)
|
||||
test Controls testing features
|
||||
|
|
@ -404,7 +391,7 @@ SUBCOMMANDS:
|
|||
|
||||
To try out the pre-built examples, use the following steps:
|
||||
|
||||
* Clone the repository `$ git clone https://github.com/kbknapp/clap-rs && cd clap-rs/`
|
||||
* Clone the repository `$ git clone https://github.com/clap-rs/clap && cd clap/`
|
||||
* Compile the example `$ cargo build --example <EXAMPLE>`
|
||||
* Run the help info `$ ./target/debug/examples/<EXAMPLE> --help`
|
||||
* Play with the arguments!
|
||||
|
|
@ -424,11 +411,17 @@ clap = "3.0.0-alpha.1"
|
|||
* Add the following to your `src/main.rs`
|
||||
|
||||
```rust
|
||||
#[macro_use]
|
||||
extern crate clap;
|
||||
use clap::App;
|
||||
|
||||
#[derive(Clap)]
|
||||
#[clap(version = "v1.0-beta")]
|
||||
/// My First clap CLI!
|
||||
struct Opts;
|
||||
|
||||
fn main() {
|
||||
App::new("fake").version("v1.0-beta").get_matches();
|
||||
Opts::parse();
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -456,6 +449,7 @@ Then run `cargo build` or `cargo update && cargo build` for your project.
|
|||
|
||||
#### Features enabled by default
|
||||
|
||||
* **derive**: Enables the custom derive (i.e. `#[derive(Clap)]`). Without this you must use one of the other methods of creating a `clap` CLI listed above
|
||||
* **"suggestions"**: Turns on the `Did you mean '--myoption'?` feature for when users make typos. (builds dependency `strsim`)
|
||||
* **"color"**: Turns on colored error messages. This feature only works on non-Windows OSs. (builds dependency `ansi-term`)
|
||||
* **"vec_map"**: Use [`VecMap`](https://crates.io/crates/vec_map) internally instead of a [`BTreeMap`](https://doc.rust-lang.org/stable/std/collections/struct.BTreeMap.html). This feature provides a _slight_ performance improvement. (builds dependency `vec_map`)
|
||||
|
|
@ -487,13 +481,7 @@ features = [ "suggestions", "color" ]
|
|||
|
||||
### Dependencies Tree
|
||||
|
||||
The following graphic depicts `clap`s dependency graph (generated using [cargo-graph](https://github.com/kbknapp/cargo-graph)).
|
||||
|
||||
* **Dashed** Line: Optional dependency
|
||||
* **Red** Color: **NOT** included by default (must use cargo `features` to enable)
|
||||
* **Blue** Color: Dev dependency, only used while developing.
|
||||
|
||||
|
||||
@TODO-v3-beta: update
|
||||
|
||||
### More Information
|
||||
|
||||
|
|
@ -573,7 +561,6 @@ See the [LICENSE-APACHE](LICENSE-APACHE) and [LICENSE-MIT](LICENSE-MIT) files in
|
|||
|
||||
There are several excellent crates which can be used with `clap`, I recommend checking them all out! If you've got a crate that would be a good fit to be used with `clap` open an issue and let me know, I'd love to add it!
|
||||
|
||||
* [`structopt`](https://github.com/TeXitoi/structopt) - This crate allows you to define a struct, and build a CLI from it! No more "stringly typed" and it uses `clap` behind the scenes! (*Note*: There is work underway to pull this crate into mainline `clap`).
|
||||
* [`assert_cli`](https://github.com/assert-rs/assert_cli) - This crate allows you test your CLIs in a very intuitive and functional way!
|
||||
|
||||
## Recent Breaking Changes
|
||||
|
|
|
|||
Loading…
Reference in a new issue