1# clap_derive 2 3Parse command line argument by defining a struct. It combines [structopt](https://github.com/TeXitoi/structopt) and [clap](https://crates.io/crates/clap) into a single experience. This crate is used by clap, and not meant to be used directly by 4consumers. 5 6## Documentation 7 8Find it on [Docs.rs](https://docs.rs/clap_derive). You can also check the [examples](https://github.com/clap-rs/clap/tree/master/clap_derive/examples) and the [changelog](https://github.com/clap-rs/clap/blob/master/CHANGELOG.md). 9 10## Example 11 12Add `clap` to your dependencies of your `Cargo.toml`: 13 14```toml 15[dependencies] 16clap = "3" 17``` 18 19And then, in your rust file: 20```rust 21use std::path::PathBuf; 22use clap::Parser; 23 24/// A basic example 25#[derive(Parser, Debug)] 26#[clap(name = "basic")] 27struct Opt { 28 // A flag, true if used in the command line. Note doc comment will 29 // be used for the help message of the flag. The name of the 30 // argument will be, by default, based on the name of the field. 31 /// Activate debug mode 32 #[clap(short, long)] 33 debug: bool, 34 35 // The number of occurrences of the `v/verbose` flag 36 /// Verbose mode (-v, -vv, -vvv, etc.) 37 #[clap(short, long, parse(from_occurrences))] 38 verbose: u8, 39 40 /// Set speed 41 #[clap(short, long, default_value = "42")] 42 speed: f64, 43 44 /// Output file 45 #[clap(short, long, parse(from_os_str), value_hint = ValueHint::FilePath)] 46 output: PathBuf, 47 48 // the long option will be translated by default to kebab case, 49 // i.e. `--nb-cars`. 50 /// Number of cars 51 #[clap(short = "c", long)] 52 nb_cars: Option<i32>, 53 54 /// admin_level to consider 55 #[clap(short, long)] 56 level: Vec<String>, 57 58 /// Files to process 59 #[clap(name = "FILE", parse(from_os_str), value_hint = ValueHint::AnyPath)] 60 files: Vec<PathBuf>, 61} 62 63fn main() { 64 let opt = Opt::parse(); 65 println!("{:#?}", opt); 66} 67``` 68 69Using this example: 70``` 71$ ./basic 72error: The following required arguments were not provided: 73 --output <output> 74 75USAGE: 76 basic --output <output> --speed <speed> 77 78For more information try --help 79$ ./basic --help 80basic 0.3.0 81Guillaume Pinot <texitoi@texitoi.eu>, others 82A basic example 83 84USAGE: 85 basic [OPTIONS] --output <output> [--] [file]... 86 87ARGS: 88 <FILE>... Files to process 89 90OPTIONS: 91 -c, --nb-cars <nb-cars> Number of cars 92 -d, --debug Activate debug mode 93 -h, --help Print help information 94 -l, --level <level>... admin_level to consider 95 -o, --output <output> Output file 96 -s, --speed <speed> Set speed [default: 42] 97 -V, --version Print version information 98 -v, --verbose Verbose mode (-v, -vv, -vvv, etc.) 99 100ARGS: 101 <file>... Files to process 102$ ./basic -o foo.txt 103Opt { 104 debug: false, 105 verbose: 0, 106 speed: 42.0, 107 output: "foo.txt", 108 nb_cars: None, 109 level: [], 110 files: [], 111} 112$ ./basic -o foo.txt -dvvvs 1337 -l alice -l bob --nb-cars 4 bar.txt baz.txt 113Opt { 114 debug: true, 115 verbose: 3, 116 speed: 1337.0, 117 output: "foo.txt", 118 nb_cars: Some( 119 4, 120 ), 121 level: [ 122 "alice", 123 "bob", 124 ], 125 files: [ 126 "bar.txt", 127 "baz.txt", 128 ], 129} 130``` 131 132## clap_derive rustc version policy 133 134- Minimum rustc version modification must be specified in the [changelog](https://github.com/clap-rs/clap_derive/blob/master/CHANGELOG.md) and in the [travis configuration](https://github.com/clap-rs/clap_derive/blob/master/.travis.yaml). 135- Contributors can increment minimum rustc version without any justification if the new version is required by the latest version of one of clap_derive's depedencies (`cargo update` will not fail on clap_derive). 136- Contributors can increment minimum rustc version if the library user experience is improved. 137 138## Why 139 140I've (@TeXitoi) used [docopt](https://crates.io/crates/docopt) for a long time (pre rust 1.0). I really like the fact that you have a structure with the parsed argument: no need to convert `String` to `f64`, no useless `unwrap`. But on the other hand, I don't like to write by hand the usage string. That's like going back to the golden age of WYSIWYG editors. Field naming is also a bit artificial. 141 142Today, the new standard to read command line arguments in Rust is [clap](https://crates.io/crates/clap). This library is so feature full! But I think there is one downside: even if you can validate argument and expressing that an argument is required, you still need to transform something looking like a hashmap of string vectors to something useful for your application. 143 144Now, there is stable custom derive. Thus I can add to clap the automatic conversion that I miss. Here is the result. 145 146## License 147 148Licensed under either of 149 150- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or <https://www.apache.org/licenses/LICENSE-2.0>) 151- MIT license ([LICENSE-MIT](LICENSE-MIT) or <https://opensource.org/licenses/MIT>) 152 153at your option. 154 155### Contribution 156 157Unless you explicitly state otherwise, any contribution intentionally submitted 158for inclusion in the work by you, as defined in the Apache-2.0 license, shall be 159dual licensed as above, without any additional terms or conditions. 160