mirror of
https://github.com/clap-rs/clap
synced 2024-09-20 14:31:58 +00:00
Update README.md
This commit is contained in:
Kevin K.
parent
bb973008a8
commit
09f1234d3e
1 changed files with 67 additions and 63 deletions
80
README.md
80
README.md
|
|
@ -1,27 +1,25 @@
|
|||
# clap 
|
||||
Command Line Argument Parser written in Rust
|
||||
|
||||
A simply library for parsing command line arguments when writing
|
||||
command line and console applications.
|
||||
A simply library for parsing command line arguments and subcommands when writing command line and console applications.
|
||||
|
||||
You can use `clap` to lay out a list of possible valid command line arguments and subcommands, then let `clap` parse the string given by the user at runtime.
|
||||
|
||||
You can use `clap` to lay out a list of possible valid command line arguments and let `clap` parse the string given by the user at runtime.
|
||||
When using `clap` you define a set of parameters and rules for your arguments and at runtime `clap` will determine their validity.
|
||||
Also, `clap` provides the traditional version and help switches 'for free' by parsing the list of possible valid arguments lazily at runtime.
|
||||
i.e. only when it's been determined that the user wants or needs to see the help and version information.
|
||||
When using `clap` you define a set of parameters and rules for your arguments and subcommands, then at runtime `clap` will determine their validity.
|
||||
|
||||
After defining a list of possible valid arguments you get a list of matches that the user supplied at runtime. You can then use this list to
|
||||
determine the functioning of your program.
|
||||
`clap` also provides the traditional version and help switches 'for free' by parsing the list of possible valid arguments lazily at runtime, and if not already defined by the developer `clap` will autogenerate all applicable "help" and "version" switches (as well as a "help" subcommand if other subcommands are defined as well).
|
||||
|
||||
Example:
|
||||
After defining a list of possible valid arguments and subcommands, `clap` gives you a list of valid matches that the user supplied at runtime, or informs the user of their error and exits gracefully. You can use this list to determine the functioning of your program.
|
||||
|
||||
```rust
|
||||
extern crate clap;
|
||||
use clap::{Arg, App, SubCommand};
|
||||
# Example (Full example with comments in examples/myapp.rs)
|
||||
|
||||
// ...
|
||||
```rust
|
||||
extern crate clap;
|
||||
use clap::{Arg, App, SubCommand};
|
||||
|
||||
let matches = App::new("MyApp")
|
||||
// ...
|
||||
|
||||
let matches = App::new("MyApp")
|
||||
.version("1.0")
|
||||
.author("Kevin K. <kbknapp@gmail.com>")
|
||||
.about("Does awesome things")
|
||||
|
|
@ -44,73 +42,79 @@ Command Line Argument Parser written in Rust
|
|||
.help("print test information verbosely")))
|
||||
.get_matches();
|
||||
|
||||
if let Some(o) = matches.value_of("output") {
|
||||
if let Some(o) = matches.value_of("output") {
|
||||
println!("Value for output: {}", o);
|
||||
}
|
||||
}
|
||||
|
||||
if let Some(c) = matches.value_of("config") {
|
||||
if let Some(c) = matches.value_of("config") {
|
||||
println!("Value for config: {}", c);
|
||||
}
|
||||
}
|
||||
|
||||
match matches.occurrences_of("debug") {
|
||||
match matches.occurrences_of("debug") {
|
||||
0 => println!("Debug mode is off"),
|
||||
1 => println!("Debug mode is kind of on"),
|
||||
2 => println!("Debug mode is on"),
|
||||
3 | _ => println!("Don't be crazy"),
|
||||
}
|
||||
}
|
||||
|
||||
if let Some(ref matches) = matches.subcommand_matches("test") {
|
||||
if let Some(ref matches) = matches.subcommand_matches("test") {
|
||||
if matches.is_present("list") {
|
||||
println!("Printing testing lists...");
|
||||
} else {
|
||||
println!("Not printing testing lists...");
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// more porgram logic goes here...
|
||||
```
|
||||
// more porgram logic goes here...
|
||||
```
|
||||
|
||||
If you were to compile the above program and run it with the flag `--help` or `-h` the following output woud be presented
|
||||
If you were to compile the above program and run it with the flag `--help` or `-h` (or `help` subcommand, since we defined `test` as a subcommand) the following output woud be presented
|
||||
|
||||
```sh
|
||||
$ myprog --help
|
||||
MyApp 1.0
|
||||
Kevin K. <kbknapp@gmail.com>
|
||||
Does awesome things
|
||||
```sh
|
||||
$ myprog --help
|
||||
MyApp 1.0
|
||||
Kevin K. <kbknapp@gmail.com>
|
||||
Does awesome things
|
||||
|
||||
USAGE:
|
||||
USAGE:
|
||||
MyApp [FLAGS] [OPTIONS] [POSITIONAL] [SUBCOMMANDS]
|
||||
|
||||
FLAGS:
|
||||
FLAGS:
|
||||
-d Turn debugging information on
|
||||
-h,--help Prints this message
|
||||
-v,--version Prints version information
|
||||
|
||||
OPTIONS:
|
||||
OPTIONS:
|
||||
-c,--config <config> Sets a custom config file
|
||||
|
||||
POSITIONAL ARGUMENTS:
|
||||
POSITIONAL ARGUMENTS:
|
||||
output Sets an optional output file
|
||||
|
||||
SUBCOMMANDS:
|
||||
SUBCOMMANDS:
|
||||
help Prints this message
|
||||
test Controls testing features
|
||||
```
|
||||
```
|
||||
|
||||
## Installation
|
||||
Simply add `clap` as a dependecy in your `Cargo.toml` file to use from crates.io:
|
||||
Add `clap` as a dependecy in your `Cargo.toml` file to use from crates.io:
|
||||
|
||||
```
|
||||
[dependencies]
|
||||
clap = "*"
|
||||
```
|
||||
Or to simply track the latest on the master branch at github:
|
||||
Or track the latest on the master branch at github:
|
||||
|
||||
```
|
||||
[dependencies.clap]
|
||||
git = "https://github.com/kbknapp/clap-rs.git"
|
||||
```
|
||||
|
||||
Then run `cargo build` or `cargo update` for your project.
|
||||
|
||||
## Usage
|
||||
|
||||
Add `extern crate clap;` to your crate root.
|
||||
|
||||
## More Information
|
||||
|
||||
You can find complete documentation on the [github-pages site](http://kbknapp.github.io/clap-rs/docs/clap/index.html) for this project.
|
||||
|
|
|
|||
Loading…
Reference in a new issue