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::Clap;
23
24/// A basic example
25#[derive(Clap, 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))]
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))]
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 [FLAGS] [OPTIONS] --output <output> [--] [file]...
86
87ARGS:
88    <FILE>...    Files to process
89
90FLAGS:
91    -d, --debug      Activate debug mode
92    -h, --help       Prints help information
93    -V, --version    Prints version information
94    -v, --verbose    Verbose mode (-v, -vv, -vvv, etc.)
95
96OPTIONS:
97    -l, --level <level>...     admin_level to consider
98    -c, --nb-cars <nb-cars>    Number of cars
99    -o, --output <output>      Output file
100    -s, --speed <speed>        Set speed [default: 42]
101
102ARGS:
103    <file>...    Files to process
104$ ./basic -o foo.txt
105Opt {
106    debug: false,
107    verbose: 0,
108    speed: 42.0,
109    output: "foo.txt",
110    nb_cars: None,
111    level: [],
112    files: [],
113}
114$ ./basic -o foo.txt -dvvvs 1337 -l alice -l bob --nb-cars 4 bar.txt baz.txt
115Opt {
116    debug: true,
117    verbose: 3,
118    speed: 1337.0,
119    output: "foo.txt",
120    nb_cars: Some(
121        4,
122    ),
123    level: [
124        "alice",
125        "bob",
126    ],
127    files: [
128        "bar.txt",
129        "baz.txt",
130    ],
131}
132```
133
134## clap_derive rustc version policy
135
136- 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).
137- 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).
138- Contributors can increment minimum rustc version if the library user experience is improved.
139
140## Why
141
142I'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.
143
144Today, 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.
145
146Now, there is stable custom derive. Thus I can add to clap the automatic conversion that I miss. Here is the result.
147
148## License
149
150Licensed under either of
151
152- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or <https://www.apache.org/licenses/LICENSE-2.0>)
153- MIT license ([LICENSE-MIT](LICENSE-MIT) or <https://opensource.org/licenses/MIT>)
154
155at your option.
156
157### Contribution
158
159Unless you explicitly state otherwise, any contribution intentionally submitted
160for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
161dual licensed as above, without any additional terms or conditions.
162