Mirrors/clap
2
0
Fork 0
mirror of https://github.com/clap-rs/clap synced 2024-11-14 00:27:13 +00:00
Code Issues Projects Releases Packages Wiki Activity

Merge pull request #243 from kbknapp/Readme_fixes

Browse source 
Quick examples fixes
This commit is contained in:
Alexander Kuvaev 2015-09-10 00:54:10 +03:00
commit 6f3f80ec33
4 changed files with 85 additions and 9 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

15
README.md
View file

@ -85,8 +85,8 @@ Below are a few of the features which `clap` supports, full descriptions and usa
- Fully compatible with other relational rules (requirements and exclusions) which allows things like requiring the use of a group, or denying the use of a group conditionally
* **Specific Value Sets**: Positional or Option Arguments can optionally define a specific set of allowed values (i.e. imagine a `--mode` option which may *only* have one of two values `fast` or `slow` such as `--mode fast` or `--mode slow`)
* **Default Values**: Although not specifically provided by `clap` you can achieve this exact functionality from Rust's `Option<&str>.unwrap_or("some default")` method (or `Result<T,String>.unwrap_or(T)` when using typed values)
* **Automatic Version from Cargo.toml**: `clap` is fully compatible with Rust's `env!()` macro for automatically setting the version of your application to the version in your Cargo.toml. See `examples/09_AutoVersion.rs` for how to do this (Thanks to [jhelwig](https://github.com/jhelwig) for pointing this out)
* **Typed Values**: You can use several convenience macros provided by `clap` to get typed values (i.e. `i32`, `u8`, etc.) from positional or option arguments so long as the type you request implements `std::str::FromStr` See the `examples/12_TypedValues.rs`. You can also use `clap`s `simple_enum!` or `arg_enum!` macro to create an enum with variants that automatically implements `std::str::FromStr`. See `examples/13a_EnumValuesAutomatic.rs` for details and performs an ascii case insensitive parse from a `string`->`enum`.
* **Automatic Version from Cargo.toml**: `clap` is fully compatible with Rust's `env!()` macro for automatically setting the version of your application to the version in your Cargo.toml. See `examples/09_auto_version.rs` for how to do this (Thanks to [jhelwig](https://github.com/jhelwig) for pointing this out)
* **Typed Values**: You can use several convenience macros provided by `clap` to get typed values (i.e. `i32`, `u8`, etc.) from positional or option arguments so long as the type you request implements `std::str::FromStr` See the `examples/12_typed_values.rs`. You can also use `clap`s `simple_enum!` or `arg_enum!` macro to create an enum with variants that automatically implements `std::str::FromStr`. See `examples/13a_enum_values_automatic.rs` for details and performs an ascii case insensitive parse from a `string`->`enum`.
* **Suggestions**: Suggests corrections when the user enter's a typo. For example, if you defined a `--myoption <value>` argument, and the user mistakenly typed `--moyption value` (notice `y` and `o` switched), they would receive a `Did you mean '--myoption' ?` error and exit gracefully. This also works for subcommands and flags. (Thanks to [Byron](https://github.com/Byron) for the implementation) (This feature can optionally be disabled, see 'Optional Dependencies / Features')
* **Colorized (Red) Errors (Non Windows OS only)**: Error message are printed in red text (this feature can optionally be disabled, see 'Optional Dependencies / Features').
* **Global Arguments**: Arguments can optionally be defined once, and be available to all child subcommands.
@ -98,10 +98,10 @@ Below are a few of the features which `clap` supports, full descriptions and usa
The following examples show a quick example of some of the very basic functionality of `clap`. For more advanced usage, such as requirements, exclusions, groups, multiple values and occurrences see the [video tutorials](https://www.youtube.com/playlist?list=PLza5oFLQGTl0Bc_EU_pBNcX-rhVqDTRxv), [documentation](http://kbknapp.github.io/clap-rs/clap/index.html), or `examples/` directory of this repository.
*NOTE:* All these examples are functionally the same, but show three different styles in which to use `clap`
**NOTE:** All these examples are functionally the same, but show three different styles in which to use `clap`
```rust
// (Full example with detailed comments in examples/01a_QuickExample.rs)
// (Full example with detailed comments in examples/01a_quick_example.rs)
//
// This example demonstrates clap's "usage strings" method of creating arguments which is less
// less verbose
@ -158,7 +158,7 @@ fn main() {
The following example is functionally the same as the one above, but this method allows more advanced configuration options (not shown in this small example), or even dynamically generating arguments when desired. Both methods can be used together to get the best of both worlds (see the documentation, examples, or video tutorials).
```rust
// (Full example with detailed comments in examples/01b_QuickExample.rs)
// (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 editting, and at times more advanced options, or the possibility
@ -227,13 +227,12 @@ fn main() {
The following combines the previous two examples by using the simplicity of the `from_usage` methods and the performance of the Builder Pattern.
```rust
// (Full example with detailed comments in examples/01c_QuickExample.rs)
// (Full example with detailed comments in examples/01c_quick_example.rs)
//
// This example demonstrates clap's "usage strings" method of creating arguments which is less
// less verbose
#[macro_use]
extern crate clap;
use clap::{Arg, App, SubCommand};
fn main() {
let matches = clap_app!(myapp =>
@ -390,7 +389,7 @@ SUBCOMMANDS:
test Controls testing features
```
*NOTE:* You could also run `myapp test --help` to see similar output and options for the `test` subcommand.
**NOTE:** You could also run `myapp test --help` to see similar output and options for the `test` subcommand.
## Try it!

2
examples/01a_quick_example.rs
View file

@ -8,6 +8,8 @@ fn main() {
// far less verbose that shown in 01b_QuickExample.rs, but is more readable. The downside is you cannot set
// the more advanced configuration options using this method (well...actually you can, you'll see ;) )
//
// The example below is functionally identical to the 01b_quick_example.rs and 01c_quick_example.rs
//
// Create an application with 5 possible arguments (2 auto generated) and 2 subcommands (1 auto generated)
// - A config file
// + Uses "-c filename" or "--config filename"

2
examples/01b_quick_example.rs
View file

@ -7,7 +7,7 @@ fn main() {
// This method shows the traditional, and slightly more configurable way to set up arguments. This method is
// more verbose, but allows setting more configuration options, and even supports easier dynamic generation.
//
// The example below is functionally identical to the one in 01a_QuickExample.rs
// The example below is functionally identical to the 01a_quick_example.rs and 01c_quick_example.rs
//
// *NOTE:* You can actually achieve the best of both worlds by using Arg::from_usage() (instead of Arg::with_name())
// and *then* setting any additional properties.

75
examples/01c_quick_example.rs Normal file
View file

@ -0,0 +1,75 @@
#[macro_use]
extern crate clap;
fn main() {
// This example shows how to create an application with several arguments using macro builder.
// It combines the simplicity of the from_usage methods and the performance of the Builder Pattern.
//
// The example below is functionally identical to the one in 01a_quick_example.rs and 01b_quick_example.rs
//
// Create an application with 5 possible arguments (2 auto generated) and 2 subcommands (1 auto generated)
// - A config file
// + Uses "-c filename" or "--config filename"
// - An output file
// + A positional argument (i.e. "$ myapp output_filename")
// - A debug flag
// + Uses "-d" or "--debug"
// + Allows multiple occurrences of such as "-dd" (for vary levels of debugging, as an example)
// - A help flag (automatically generated by clap)
// + Uses "-h" or "--help" (Only autogenerated if you do NOT specify your own "-h" or "--help")
// - A version flag (automatically generated by clap)
// + Uses "-V" or "--version" (Only autogenerated if you do NOT specify your own "-V" or "--version")
// - A subcommand "test" (subcommands behave like their own apps, with their own arguments
// + Used by "$ myapp test" with the following arguments
// > A list flag
// = Uses "-l" (usage is "$ myapp test -l"
// > A help flag (automatically generated by clap
// = Uses "-h" or "--help" (full usage "$ myapp test -h" or "$ myapp test --help")
// > A version flag (automatically generated by clap
// = Uses "-V" or "--version" (full usage "$ myapp test -V" or "$ myapp test --version")
// - A subcommand "help" (automatically generated by clap because we specified a subcommand of our own)
// + Used by "$ myapp help" (same functionality as "-h" or "--help")
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();
// 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());
// 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);
// Vary the output based on how many times the user used the "debug" flag
// (i.e. 'myapp -d -d -d' or 'myapp -ddd' vs 'myapp -d'
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"),
}
// You can 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("verbose") {
println!("Printing verbosely...");
} else {
println!("Printing normally...");
}
}
// more porgram logic goes here...
}