| app |
|
|
| args |
|
|
| completions |
|
|
| errors.rs |
|
30759 |
| fmt.rs |
|
5013 |
| lib.rs |
`clap` is a simple-to-use, efficient, and full-featured library for parsing command line
arguments and subcommands when writing console/terminal applications.
## About
`clap` is used to parse *and validate* the string of command line arguments provided by the user
at runtime. You provide the list of valid possibilities, and `clap` handles the rest. This means
you focus on your *applications* functionality, and less on the parsing and validating of
arguments.
`clap` also provides the traditional version and help switches (or flags) 'for free' meaning
automatically with no configuration. It does this by checking the list of valid possibilities you
supplied and adding only the ones you haven't already defined. If you are using subcommands,
`clap` will also auto-generate a `help` subcommand for you in addition to the traditional flags.
Once `clap` parses the user provided string of arguments, it returns the matches along with any
applicable values. If the user made an error or typo, `clap` informs them of the mistake and
exits gracefully (or returns a `Result` type and allows you to perform any clean up prior to
exit). Because of this, you can make reasonable assumptions in your code about the validity of
the arguments.
## Quick Example
The following examples show a quick example of some of the very basic functionality of `clap`.
For more advanced usage, such as requirements, conflicts, groups, multiple values and
occurrences see the [documentation](https://docs.rs/clap/), [examples/] directory of
this repository or the [video tutorials].
**NOTE:** All of these examples are functionally the same, but show different styles in which to
use `clap`
The first example shows a method that 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.
```no_run
// (Full example with detailed comments in examples/01b_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.
extern crate clap;
use clap::{Arg, App, SubCommand};
fn main() {
let matches = App::new("My Super Program")
.version("1.0")
.author("Kevin K. <kbknapp@gmail.com>")
.about("Does awesome things")
.arg(Arg::with_name("config")
.short("c")
.long("config")
.value_name("FILE")
.help("Sets a custom config file")
.takes_value(true))
.arg(Arg::with_name("INPUT")
.help("Sets the input file to use")
.required(true)
.index(1))
.arg(Arg::with_name("v")
.short("v")
.multiple(true)
.help("Sets the level of verbosity"))
.subcommand(SubCommand::with_name("test")
.about("controls testing features")
.version("1.3")
.author("Someone E. <someone_else@other.com>")
.arg(Arg::with_name("debug")
.short("d")
.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' |
24231 |
| macros.rs |
... |
38066 |
| map.rs |
|
2185 |
| osstringext.rs |
|
6769 |
| strext.rs |
|
377 |
| suggestions.rs |
|
4310 |
| usage_parser.rs |
|
48265 |