1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
/// The abstract representation of a command line argument used by the consumer of the library.
///
///
/// This struct is used by the library consumer and describes the command line arguments for
/// their program.
/// and then evaluates the settings the consumer provided and determines the concret
/// argument struct to use when parsing.
///
/// # Example
///
/// ```no_run
/// # use clap::{App, Arg};
/// # let matches = App::new("myprog")
/// # .arg(
/// Arg::new("conifg")
/// .short("c")
/// .long("config")
/// .takes_value(true)
/// .help("Provides a config file to myprog")
/// # ).get_matches();
pub struct Arg<'n, 'l, 'h, 'b, 'p, 'r> {
/// The unique name of the argument, required
pub name: &'n str,
/// The short version (i.e. single character) of the argument, no preceding `-`
/// **NOTE:** `short` is mutually exclusive with `index`
pub short: Option<char>,
/// The long version of the flag (i.e. word) without the preceding `--`
/// **NOTE:** `long` is mutually exclusive with `index`
pub long: Option<&'l str>,
/// The string of text that will displayed to the user when the application's
/// `help` text is displayed
pub help: Option<&'h str>,
/// If this is a required by default when using the command line program
/// i.e. a configuration file that's required for the program to function
/// **NOTE:** required by default means, it is required *until* mutually
/// exclusive arguments are evaluated.
pub required: bool,
/// Determines if this argument is an option, vice a flag or positional and
/// is mutually exclusive with `index` and `multiple`
pub takes_value: bool,
/// The index of the argument. `index` is mutually exclusive with `takes_value`
/// and `multiple`
pub index: Option<u8>,
/// Determines if multiple instances of the same flag are allowed. `multiple`
/// is mutually exclusive with `index` and `takes_value`.
/// I.e. `-v -v -v` or `-vvv`
pub multiple: bool,
/// A list of names for other arguments that *may not* be used with this flag
pub blacklist: Option<Vec<&'b str>>,
/// A list of possible values for an option or positional argument
pub possible_vals: Option<Vec<&'p str>>,
/// A list of names of other arguments that are *required* to be used when
/// this flag is used
pub requires: Option<Vec<&'r str>>
}
impl<'n, 'l, 'h, 'b, 'p, 'r> Arg<'n, 'l, 'h, 'b, 'p, 'r> {
/// Creates a new instace of `Arg` using a unique string name.
/// The name will be used by the library consumer to get information about
/// whether or not the argument was used at runtime.
///
/// **NOTE:** in the case of arguments that take values (i.e. `takes_value(true)`)
/// and positional arguments (i.e. those without a `-` or `--`) the name will also
/// be displayed when the user prints the usage/help information of the program.
///
/// Example:
///
/// ```no_run
/// # use clap::{App, Arg};
/// # let matches = App::new("myprog")
/// # .arg(
/// Arg::new("conifg")
/// # .short("c")
/// # ).get_matches();
pub fn new(n: &'n str) -> Arg<'n, 'l, 'h, 'b, 'p, 'r> {
Arg {
name: n,
short: None,
long: None,
help: None,
required: false,
takes_value: false,
multiple: false,
index: None,
possible_vals: None,
blacklist: None,
requires: None,
}
}
/// Sets the short version of the argument without the preceding `-`.
///
///
/// By default `clap` automatically assigns `v` and `h` to display version and help information
/// respectivly. You may use `v` or `h` for your own purposes, in which case `clap` simply
/// will not asign those to the displaying of version or help.
///
/// **NOTE:** Any leading `-` characters will be stripped, and only the first
/// non `-` chacter will be used as the `short` version, i.e. for when the user
/// mistakenly sets the short to `-o` or the like.
/// Example:
///
/// ```no_run
/// # use clap::{App, Arg};
/// # let matches = App::new("myprog")
/// # .arg(
/// # Arg::new("conifg")
/// .short("c")
/// # ).get_matches();
pub fn short(mut self, s: &str) -> Arg<'n, 'l, 'h, 'b, 'p, 'r> {
self.short = s.trim_left_matches(|c| c == '-').chars().nth(0);
self
}
/// Sets the long version of the argument without the preceding `--`.
///
/// By default `clap` automatically assigns `version` and `help` to display version and help information
/// respectivly. You may use `version` or `help` for your own purposes, in which case `clap` simply
/// will not asign those to the displaying of version or help automatically, and you will have to do
/// so manually.
///
/// **NOTE:** Any leading `-` characters will be stripped i.e. for
/// when the user mistakenly sets the short to `--out` or the like.
///
/// Example:
///
/// ```no_run
/// # use clap::{App, Arg};
/// # let matches = App::new("myprog")
/// # .arg(
/// # Arg::new("conifg")
/// .long("config")
/// # ).get_matches();
pub fn long(mut self, l: &'l str) -> Arg<'n, 'l, 'h, 'b, 'p, 'r> {
self.long = Some(l.trim_left_matches(|c| c == '-'));
self
}
/// Sets the help text of the argument that will be displayed to the user
/// when they print the usage/help information.
///
/// Example:
///
/// ```no_run
/// # use clap::{App, Arg};
/// # let matches = App::new("myprog")
/// # .arg(
/// # Arg::new("conifg")
/// .help("The config file used by the myprog")
/// # ).get_matches();
pub fn help(mut self, h: &'h str) -> Arg<'n, 'l, 'h, 'b, 'p, 'r> {
self.help = Some(h);
self
}
/// Sets whether or not the argument is required by default. Required by
/// default means it is required, when no other mutually exlusive rules have
/// been evaluated. Mutually exclusive rules take precedence over being required
/// by default.
///
/// **NOTE:** Flags (i.e. not positional, or arguments that take values)
/// cannot be required by default.
/// when they print the usage/help information.
///
/// Example:
///
/// ```no_run
/// # use clap::{App, Arg};
/// # let matches = App::new("myprog")
/// # .arg(
/// # Arg::new("conifg")
/// .required(true)
/// # ).get_matches();
pub fn required(mut self, r: bool) -> Arg<'n, 'l, 'h, 'b, 'p, 'r> {
self.required = r;
self
}
/// Sets a mutually exclusive argument by name. I.e. when using this argument,
/// the following argument can't be present.
///
/// **NOTE:** Mutually exclusive rules take precedence over being required
/// by default. Mutually exclusive rules only need to be set for one of the two
/// arguments, they do not need to be set for each.
///
/// Example:
///
/// ```no_run
/// # use clap::{App, Arg};
/// # let myprog = App::new("myprog").arg(Arg::new("conifg")
/// .mutually_excludes("debug")
/// # ).get_matches();
pub fn mutually_excludes(mut self, name: &'b str) -> Arg<'n, 'l, 'h, 'b, 'p, 'r> {
if let Some(ref mut vec) = self.blacklist {
vec.push(name);
} else {
self.blacklist = Some(vec![name]);
}
self
}
/// Sets a mutually exclusive arguments by names. I.e. when using this argument,
/// the following argument can't be present.
///
/// **NOTE:** Mutually exclusive rules take precedence over being required
/// by default. Mutually exclusive rules only need to be set for one of the two
/// arguments, they do not need to be set for each.
///
/// Example:
///
/// ```no_run
/// # use clap::{App, Arg};
/// # let myprog = App::new("myprog").arg(Arg::new("conifg")
/// .mutually_excludes_all(
/// vec!["debug", "input"])
/// # ).get_matches();
pub fn mutually_excludes_all(mut self, names: Vec<&'b str>) -> Arg<'n, 'l, 'h, 'b, 'p, 'r> {
if let Some(ref mut vec) = self.blacklist {
for n in names {
vec.push(n);
}
} else {
self.blacklist = Some(names);
}
self
}
/// Sets an argument by name that is required when this one is presnet I.e. when
/// using this argument, the following argument *must* be present.
///
/// **NOTE:** Mutually exclusive rules take precedence over being required
///
/// Example:
///
/// ```no_run
/// # use clap::{App, Arg};
/// # let myprog = App::new("myprog").arg(Arg::new("conifg")
/// .requires("debug")
/// # ).get_matches();
pub fn requires(mut self, name: &'r str) -> Arg<'n, 'l, 'h, 'b, 'p, 'r> {
if let Some(ref mut vec) = self.requires {
vec.push(name);
} else {
self.requires = Some(vec![name]);
}
self
}
/// Sets arguments by names that are required when this one is presnet I.e. when
/// using this argument, the following arguments *must* be present.
///
/// **NOTE:** Mutually exclusive rules take precedence over being required
/// by default.
///
/// Example:
///
/// ```no_run
/// # use clap::{App, Arg};
/// # let myprog = App::new("myprog").arg(Arg::new("conifg")
/// .requires_all(
/// vec!["debug", "input"])
/// # ).get_matches();
pub fn requires_all(mut self, names: Vec<&'r str>) -> Arg<'n, 'l, 'h, 'b, 'p, 'r> {
if let Some(ref mut vec) = self.requires {
for n in names {
vec.push(n);
}
} else {
self.requires = Some(names);
}
self
}
/// Specifies that the argument takes an additional value at run time.
///
/// **NOTE:** When setting this to `true` the `name` of the argument
/// will be used when printing the help/usage information to the user.
///
/// Example:
///
/// ```no_run
/// # use clap::{App, Arg};
/// # let matches = App::new("myprog")
/// # .arg(
/// # Arg::new("conifg")
/// .takes_value(true)
/// # ).get_matches();
pub fn takes_value(mut self, tv: bool) -> Arg<'n, 'l, 'h, 'b, 'p, 'r> {
self.takes_value = tv;
self
}
/// Specifies the index of a positional argument starting at 1.
///
/// **NOTE:** When setting this, any `short` or `long` values you set
/// are ignored as positional arguments cannot have a `short` or `long`.
/// Also, the name will be used when printing the help/usage information
/// to the user.
///
/// Example:
///
/// ```no_run
/// # use clap::{App, Arg};
/// # let matches = App::new("myprog")
/// # .arg(
/// # Arg::new("conifg")
/// .index(1)
/// # ).get_matches();
pub fn index(mut self, idx: u8) -> Arg<'n, 'l, 'h, 'b, 'p, 'r> {
self.index = Some(idx);
self
}
/// Specifies if the flag may appear more than once such as for multiple debugging
/// levels (as an example). `-ddd` for three levels of debugging, or `-d -d -d`.
/// When this is set to `true` you recieve the number of occurances the user supplied
/// of a particular flag at runtime.
///
/// **NOTE:** When setting this, any `takes_value` or `index` values you set
/// are ignored as flags cannot have a values or an `index`.
///
/// Example:
///
/// ```no_run
/// # use clap::{App, Arg};
/// # let matches = App::new("myprog")
/// # .arg(
/// # Arg::new("debug")
/// .multiple(true)
/// # ).get_matches();
pub fn multiple(mut self, multi: bool) -> Arg<'n, 'l, 'h, 'b, 'p, 'r> {
self.multiple = multi;
self
}
/// Specifies a list of possible values for this argument. At runtime, clap verifies that only
/// one of the specified values was used, or fails with a usage string.
///
/// **NOTE:** This setting only applies to options and positional arguments
///
/// Example:
///
/// ```no_run
/// # use clap::{App, Arg};
/// # let matches = App::new("myprog")
/// # .arg(
/// # Arg::new("debug").index(1)
/// .possible_values(vec!["fast", "slow"])
/// # ).get_matches();
pub fn possible_values(mut self, names: Vec<&'p str>) -> Arg<'n, 'l, 'h, 'b, 'p, 'r> {
if let Some(ref mut vec) = self.possible_vals {
for n in names {
vec.push(n);
}
} else {
self.possible_vals = Some(names);
}
self
}
}