]>
Commit | Line | Data |
---|---|---|
04454e1e FG |
1 | # Tutorial |
2 | ||
3 | *Jump to [derive tutorial](../tutorial_derive/README.md)* | |
4 | ||
5 | 1. [Quick Start](#quick-start) | |
6 | 2. [Configuring the Parser](#configuring-the-parser) | |
7 | 3. [Adding Arguments](#adding-arguments) | |
923072b8 | 8 | 1. [Positionals](#positionals) |
04454e1e | 9 | 2. [Options](#options) |
923072b8 | 10 | 3. [Flags](#flags) |
04454e1e FG |
11 | 4. [Subcommands](#subcommands) |
12 | 5. [Defaults](#defaults) | |
13 | 4. Validation | |
14 | 1. [Enumerated values](#enumerated-values) | |
15 | 2. [Validated values](#validated-values) | |
16 | 3. [Argument Relations](#argument-relations) | |
17 | 4. [Custom Validation](#custom-validation) | |
18 | 5. [Tips](#tips) | |
19 | 6. [Contributing](#contributing) | |
20 | ||
21 | ## Quick Start | |
22 | ||
23 | You can create an application with several arguments using usage strings. | |
24 | ||
25 | [Example:](01_quick.rs) | |
26 | ```console | |
27 | $ 01_quick --help | |
28 | clap [..] | |
29 | A simple to use, efficient, and full-featured Command Line Argument Parser | |
30 | ||
31 | USAGE: | |
32 | 01_quick[EXE] [OPTIONS] [name] [SUBCOMMAND] | |
33 | ||
34 | ARGS: | |
35 | <name> Optional name to operate on | |
36 | ||
37 | OPTIONS: | |
38 | -c, --config <FILE> Sets a custom config file | |
39 | -d, --debug Turn debugging information on | |
40 | -h, --help Print help information | |
41 | -V, --version Print version information | |
42 | ||
43 | SUBCOMMANDS: | |
44 | help Print this message or the help of the given subcommand(s) | |
45 | test does testing things | |
46 | ||
47 | ``` | |
48 | ||
49 | By default, the program does nothing: | |
50 | ```console | |
51 | $ 01_quick | |
52 | Debug mode is off | |
53 | ||
54 | ``` | |
55 | ||
56 | But you can mix and match the various features | |
57 | ```console | |
58 | $ 01_quick -dd test | |
59 | Debug mode is on | |
60 | Not printing testing lists... | |
61 | ||
62 | ``` | |
63 | ||
64 | ## Configuring the Parser | |
65 | ||
66 | You use the `Command` the start building a parser. | |
67 | ||
68 | [Example:](02_apps.rs) | |
69 | ```console | |
70 | $ 02_apps --help | |
71 | MyApp 1.0 | |
72 | Kevin K. <kbknapp@gmail.com> | |
73 | Does awesome things | |
74 | ||
75 | USAGE: | |
76 | 02_apps[EXE] --two <VALUE> --one <VALUE> | |
77 | ||
78 | OPTIONS: | |
79 | -h, --help Print help information | |
80 | --one <VALUE> | |
81 | --two <VALUE> | |
82 | -V, --version Print version information | |
83 | ||
84 | $ 02_apps --version | |
85 | MyApp 1.0 | |
86 | ||
87 | ``` | |
88 | ||
89 | You can use `command!()` to fill these fields in from your `Cargo.toml` | |
90 | file. **This requires the `cargo` feature flag.** | |
91 | ||
92 | [Example:](02_crate.rs) | |
93 | ```console | |
94 | $ 02_crate --help | |
95 | clap [..] | |
96 | A simple to use, efficient, and full-featured Command Line Argument Parser | |
97 | ||
98 | USAGE: | |
99 | 02_crate[EXE] --two <VALUE> --one <VALUE> | |
100 | ||
101 | OPTIONS: | |
102 | -h, --help Print help information | |
103 | --one <VALUE> | |
104 | --two <VALUE> | |
105 | -V, --version Print version information | |
106 | ||
107 | $ 02_crate --version | |
108 | clap [..] | |
109 | ||
110 | ``` | |
111 | ||
112 | You can use `Command` methods to change the application level behavior of clap. | |
113 | ||
114 | [Example:](02_app_settings.rs) | |
115 | ```console | |
116 | $ 02_app_settings --help | |
117 | clap [..] | |
118 | A simple to use, efficient, and full-featured Command Line Argument Parser | |
119 | ||
120 | USAGE: | |
121 | 02_app_settings[EXE] --two <VALUE> --one <VALUE> | |
122 | ||
123 | OPTIONS: | |
124 | --two <VALUE> | |
125 | --one <VALUE> | |
126 | -h, --help Print help information | |
127 | -V, --version Print version information | |
128 | ||
129 | $ 02_app_settings --one -1 --one -3 --two 10 | |
130 | two: "10" | |
131 | one: "-3" | |
132 | ||
133 | ``` | |
134 | ||
135 | ## Adding Arguments | |
136 | ||
923072b8 | 137 | ### Positionals |
04454e1e | 138 | |
923072b8 | 139 | You can have users specify values by their position on the command-line: |
04454e1e | 140 | |
923072b8 | 141 | [Example:](03_03_positional.rs) |
04454e1e | 142 | ```console |
923072b8 | 143 | $ 03_03_positional --help |
04454e1e FG |
144 | clap [..] |
145 | A simple to use, efficient, and full-featured Command Line Argument Parser | |
146 | ||
147 | USAGE: | |
923072b8 | 148 | 03_03_positional[EXE] [NAME] |
04454e1e | 149 | |
923072b8 FG |
150 | ARGS: |
151 | <NAME> | |
04454e1e FG |
152 | |
153 | OPTIONS: | |
154 | -h, --help Print help information | |
04454e1e FG |
155 | -V, --version Print version information |
156 | ||
923072b8 FG |
157 | $ 03_03_positional |
158 | NAME: None | |
04454e1e | 159 | |
923072b8 FG |
160 | $ 03_03_positional bob |
161 | NAME: Some("bob") | |
04454e1e FG |
162 | |
163 | ``` | |
164 | ||
165 | ### Options | |
166 | ||
923072b8 FG |
167 | You can name your arguments with a flag: |
168 | - Order doesn't matter | |
169 | - They can be optional | |
170 | - Intent is clearer | |
04454e1e FG |
171 | |
172 | [Example:](03_02_option.rs) | |
173 | ```console | |
174 | $ 03_02_option --help | |
175 | clap [..] | |
176 | A simple to use, efficient, and full-featured Command Line Argument Parser | |
177 | ||
178 | USAGE: | |
179 | 03_02_option[EXE] [OPTIONS] | |
180 | ||
181 | OPTIONS: | |
182 | -h, --help Print help information | |
183 | -n, --name <NAME> | |
184 | -V, --version Print version information | |
185 | ||
186 | $ 03_02_option | |
187 | name: None | |
188 | ||
189 | $ 03_02_option --name bob | |
190 | name: Some("bob") | |
191 | ||
192 | $ 03_02_option --name=bob | |
193 | name: Some("bob") | |
194 | ||
195 | $ 03_02_option -n bob | |
196 | name: Some("bob") | |
197 | ||
198 | $ 03_02_option -n=bob | |
199 | name: Some("bob") | |
200 | ||
201 | $ 03_02_option -nbob | |
202 | name: Some("bob") | |
203 | ||
204 | ``` | |
205 | ||
923072b8 | 206 | ### Flags |
04454e1e | 207 | |
923072b8 | 208 | Flags can also be switches that can be on/off: |
04454e1e | 209 | |
923072b8 | 210 | [Example:](03_01_flag_bool.rs) |
04454e1e | 211 | ```console |
923072b8 | 212 | $ 03_01_flag_bool --help |
04454e1e FG |
213 | clap [..] |
214 | A simple to use, efficient, and full-featured Command Line Argument Parser | |
215 | ||
216 | USAGE: | |
923072b8 | 217 | 03_01_flag_bool[EXE] [OPTIONS] |
04454e1e | 218 | |
923072b8 FG |
219 | OPTIONS: |
220 | -h, --help Print help information | |
221 | -v, --verbose | |
222 | -V, --version Print version information | |
223 | ||
224 | $ 03_01_flag_bool | |
225 | verbose: false | |
226 | ||
227 | $ 03_01_flag_bool --verbose | |
228 | verbose: true | |
229 | ||
230 | $ 03_01_flag_bool --verbose --verbose | |
231 | verbose: true | |
232 | ||
233 | ``` | |
234 | ||
235 | Or counted. | |
236 | ||
237 | [Example:](03_01_flag_count.rs) | |
238 | ```console | |
239 | $ 03_01_flag_count --help | |
240 | clap [..] | |
241 | A simple to use, efficient, and full-featured Command Line Argument Parser | |
242 | ||
243 | USAGE: | |
244 | 03_01_flag_count[EXE] [OPTIONS] | |
04454e1e FG |
245 | |
246 | OPTIONS: | |
247 | -h, --help Print help information | |
923072b8 | 248 | -v, --verbose |
04454e1e FG |
249 | -V, --version Print version information |
250 | ||
923072b8 FG |
251 | $ 03_01_flag_count |
252 | verbose: 0 | |
04454e1e | 253 | |
923072b8 FG |
254 | $ 03_01_flag_count --verbose |
255 | verbose: 1 | |
256 | ||
257 | $ 03_01_flag_count --verbose --verbose | |
258 | verbose: 2 | |
04454e1e FG |
259 | |
260 | ``` | |
261 | ||
262 | ### Subcommands | |
263 | ||
264 | Subcommands are defined as `Command`s that get added via `Command::subcommand`. Each | |
265 | instance of a Subcommand can have its own version, author(s), Args, and even its own | |
266 | subcommands. | |
267 | ||
268 | [Example:](03_04_subcommands.rs) | |
269 | ```console | |
270 | $ 03_04_subcommands help | |
271 | clap [..] | |
272 | A simple to use, efficient, and full-featured Command Line Argument Parser | |
273 | ||
274 | USAGE: | |
275 | 03_04_subcommands[EXE] <SUBCOMMAND> | |
276 | ||
277 | OPTIONS: | |
278 | -h, --help Print help information | |
279 | -V, --version Print version information | |
280 | ||
281 | SUBCOMMANDS: | |
282 | add Adds files to myapp | |
283 | help Print this message or the help of the given subcommand(s) | |
284 | ||
285 | $ 03_04_subcommands help add | |
286 | 03_04_subcommands[EXE]-add [..] | |
287 | Adds files to myapp | |
288 | ||
289 | USAGE: | |
290 | 03_04_subcommands[EXE] add [NAME] | |
291 | ||
292 | ARGS: | |
293 | <NAME> | |
294 | ||
295 | OPTIONS: | |
296 | -h, --help Print help information | |
297 | -V, --version Print version information | |
298 | ||
299 | $ 03_04_subcommands add bob | |
300 | 'myapp add' was used, name is: Some("bob") | |
301 | ||
302 | ``` | |
303 | ||
304 | Because we set `Command::arg_required_else_help`: | |
305 | ```console | |
306 | $ 03_04_subcommands | |
307 | ? failed | |
308 | clap [..] | |
309 | A simple to use, efficient, and full-featured Command Line Argument Parser | |
310 | ||
311 | USAGE: | |
312 | 03_04_subcommands[EXE] <SUBCOMMAND> | |
313 | ||
314 | OPTIONS: | |
315 | -h, --help Print help information | |
316 | -V, --version Print version information | |
317 | ||
318 | SUBCOMMANDS: | |
319 | add Adds files to myapp | |
320 | help Print this message or the help of the given subcommand(s) | |
321 | ||
322 | ``` | |
323 | ||
324 | Because we set `Command::propagate_version`: | |
325 | ```console | |
326 | $ 03_04_subcommands --version | |
327 | clap [..] | |
328 | ||
329 | $ 03_04_subcommands add --version | |
330 | 03_04_subcommands[EXE]-add [..] | |
331 | ||
332 | ``` | |
333 | ||
334 | ### Defaults | |
335 | ||
336 | We've previously showed that arguments can be `required` or optional. When | |
337 | optional, you work with a `Option` and can `unwrap_or`. Alternatively, you can | |
338 | set `Arg::default_value`. | |
339 | ||
340 | [Example:](03_05_default_values.rs) | |
341 | ```console | |
342 | $ 03_05_default_values --help | |
343 | clap [..] | |
344 | A simple to use, efficient, and full-featured Command Line Argument Parser | |
345 | ||
346 | USAGE: | |
347 | 03_05_default_values[EXE] [NAME] | |
348 | ||
349 | ARGS: | |
350 | <NAME> [default: alice] | |
351 | ||
352 | OPTIONS: | |
353 | -h, --help Print help information | |
354 | -V, --version Print version information | |
355 | ||
356 | $ 03_05_default_values | |
357 | NAME: "alice" | |
358 | ||
359 | $ 03_05_default_values bob | |
360 | NAME: "bob" | |
361 | ||
362 | ``` | |
363 | ||
364 | ## Validation | |
365 | ||
366 | ### Enumerated values | |
367 | ||
368 | If you have arguments of specific values you want to test for, you can use the | |
923072b8 | 369 | `PossibleValuesParser` or `Arg::value_parser(["val1", ...])` for short. |
04454e1e FG |
370 | |
371 | This allows you specify the valid values for that argument. If the user does not use one of | |
372 | those specific values, they will receive a graceful exit with error message informing them | |
373 | of the mistake, and what the possible valid values are | |
374 | ||
375 | [Example:](04_01_possible.rs) | |
376 | ```console | |
377 | $ 04_01_possible --help | |
378 | clap [..] | |
379 | A simple to use, efficient, and full-featured Command Line Argument Parser | |
380 | ||
381 | USAGE: | |
382 | 04_01_possible[EXE] <MODE> | |
383 | ||
384 | ARGS: | |
385 | <MODE> What mode to run the program in [possible values: fast, slow] | |
386 | ||
387 | OPTIONS: | |
388 | -h, --help Print help information | |
389 | -V, --version Print version information | |
390 | ||
391 | $ 04_01_possible fast | |
392 | Hare | |
393 | ||
394 | $ 04_01_possible slow | |
395 | Tortoise | |
396 | ||
397 | $ 04_01_possible medium | |
398 | ? failed | |
399 | error: "medium" isn't a valid value for '<MODE>' | |
400 | [possible values: fast, slow] | |
401 | ||
04454e1e FG |
402 | For more information try --help |
403 | ||
404 | ``` | |
405 | ||
923072b8 | 406 | When enabling the `derive` feature, you can use `ValueEnum` to take care of the boiler plate for you, giving the same results. |
04454e1e FG |
407 | |
408 | [Example:](04_01_enum.rs) | |
409 | ```console | |
410 | $ 04_01_enum --help | |
411 | clap [..] | |
412 | A simple to use, efficient, and full-featured Command Line Argument Parser | |
413 | ||
414 | USAGE: | |
415 | 04_01_enum[EXE] <MODE> | |
416 | ||
417 | ARGS: | |
418 | <MODE> What mode to run the program in [possible values: fast, slow] | |
419 | ||
420 | OPTIONS: | |
421 | -h, --help Print help information | |
422 | -V, --version Print version information | |
423 | ||
424 | $ 04_01_enum fast | |
425 | Hare | |
426 | ||
427 | $ 04_01_enum slow | |
428 | Tortoise | |
429 | ||
430 | $ 04_01_enum medium | |
431 | ? failed | |
432 | error: "medium" isn't a valid value for '<MODE>' | |
433 | [possible values: fast, slow] | |
434 | ||
04454e1e FG |
435 | For more information try --help |
436 | ||
437 | ``` | |
438 | ||
439 | ### Validated values | |
440 | ||
923072b8 | 441 | More generally, you can validate and parse into any data type. |
04454e1e FG |
442 | |
443 | [Example:](04_02_parse.rs) | |
444 | ```console | |
445 | $ 04_02_parse --help | |
446 | clap [..] | |
447 | A simple to use, efficient, and full-featured Command Line Argument Parser | |
448 | ||
449 | USAGE: | |
450 | 04_02_parse[EXE] <PORT> | |
451 | ||
452 | ARGS: | |
453 | <PORT> Network port to use | |
454 | ||
455 | OPTIONS: | |
456 | -h, --help Print help information | |
457 | -V, --version Print version information | |
458 | ||
459 | $ 04_02_parse 22 | |
460 | PORT = 22 | |
461 | ||
462 | $ 04_02_parse foobar | |
463 | ? failed | |
464 | error: Invalid value "foobar" for '<PORT>': invalid digit found in string | |
465 | ||
466 | For more information try --help | |
467 | ||
923072b8 FG |
468 | $ 04_02_parse_derive 0 |
469 | ? failed | |
470 | error: Invalid value "0" for '<PORT>': 0 is not in 1..=65535 | |
471 | ||
472 | For more information try --help | |
473 | ||
04454e1e FG |
474 | ``` |
475 | ||
923072b8 | 476 | A custom parser can be used to improve the error messages or provide additional validation: |
04454e1e FG |
477 | |
478 | [Example:](04_02_validate.rs) | |
479 | ```console | |
480 | $ 04_02_validate --help | |
481 | clap [..] | |
482 | A simple to use, efficient, and full-featured Command Line Argument Parser | |
483 | ||
484 | USAGE: | |
485 | 04_02_validate[EXE] <PORT> | |
486 | ||
487 | ARGS: | |
488 | <PORT> Network port to use | |
489 | ||
490 | OPTIONS: | |
491 | -h, --help Print help information | |
492 | -V, --version Print version information | |
493 | ||
494 | $ 04_02_validate 22 | |
495 | PORT = 22 | |
496 | ||
923072b8 FG |
497 | $ 04_02_validate foobar |
498 | ? failed | |
499 | error: Invalid value "foobar" for '<PORT>': `foobar` isn't a port number | |
500 | ||
501 | For more information try --help | |
502 | ||
04454e1e FG |
503 | $ 04_02_validate 0 |
504 | ? failed | |
505 | error: Invalid value "0" for '<PORT>': Port not in range 1-65535 | |
506 | ||
507 | For more information try --help | |
508 | ||
509 | ``` | |
510 | ||
511 | ### Argument Relations | |
512 | ||
513 | You can declare dependencies or conflicts between `Arg`s or even `ArgGroup`s. | |
514 | ||
515 | `ArgGroup`s make it easier to declare relations instead of having to list each | |
516 | individually, or when you want a rule to apply "any but not all" arguments. | |
517 | ||
518 | Perhaps the most common use of `ArgGroup`s is to require one and *only* one argument to be | |
519 | present out of a given set. Imagine that you had multiple arguments, and you want one of them to | |
520 | be required, but making all of them required isn't feasible because perhaps they conflict with | |
521 | each other. | |
522 | ||
523 | [Example:](04_03_relations.rs) | |
524 | ```console | |
525 | $ 04_03_relations --help | |
526 | clap [..] | |
527 | A simple to use, efficient, and full-featured Command Line Argument Parser | |
528 | ||
529 | USAGE: | |
530 | 04_03_relations[EXE] [OPTIONS] <--set-ver <VER>|--major|--minor|--patch> [INPUT_FILE] | |
531 | ||
532 | ARGS: | |
533 | <INPUT_FILE> some regular input | |
534 | ||
535 | OPTIONS: | |
536 | -c <CONFIG> | |
537 | -h, --help Print help information | |
538 | --major auto inc major | |
539 | --minor auto inc minor | |
540 | --patch auto inc patch | |
541 | --set-ver <VER> set version manually | |
542 | --spec-in <SPEC_IN> some special input argument | |
543 | -V, --version Print version information | |
544 | ||
545 | $ 04_03_relations | |
546 | ? failed | |
547 | error: The following required arguments were not provided: | |
548 | <--set-ver <VER>|--major|--minor|--patch> | |
549 | ||
550 | USAGE: | |
551 | 04_03_relations[EXE] [OPTIONS] <--set-ver <VER>|--major|--minor|--patch> [INPUT_FILE] | |
552 | ||
553 | For more information try --help | |
554 | ||
555 | $ 04_03_relations --major | |
556 | Version: 2.2.3 | |
557 | ||
558 | $ 04_03_relations --major --minor | |
559 | ? failed | |
560 | error: The argument '--major' cannot be used with '--minor' | |
561 | ||
562 | USAGE: | |
563 | 04_03_relations[EXE] <--set-ver <VER>|--major|--minor|--patch> | |
564 | ||
565 | For more information try --help | |
566 | ||
567 | $ 04_03_relations --major -c config.toml | |
568 | ? failed | |
569 | error: The following required arguments were not provided: | |
570 | <INPUT_FILE|--spec-in <SPEC_IN>> | |
571 | ||
572 | USAGE: | |
573 | 04_03_relations[EXE] -c <CONFIG> <--set-ver <VER>|--major|--minor|--patch> <INPUT_FILE|--spec-in <SPEC_IN>> | |
574 | ||
575 | For more information try --help | |
576 | ||
577 | $ 04_03_relations --major -c config.toml --spec-in input.txt | |
578 | Version: 2.2.3 | |
579 | Doing work using input input.txt and config config.toml | |
580 | ||
581 | ``` | |
582 | ||
583 | ### Custom Validation | |
584 | ||
585 | As a last resort, you can create custom errors with the basics of clap's formatting. | |
586 | ||
587 | [Example:](04_04_custom.rs) | |
588 | ```console | |
589 | $ 04_04_custom --help | |
590 | clap [..] | |
591 | A simple to use, efficient, and full-featured Command Line Argument Parser | |
592 | ||
593 | USAGE: | |
594 | 04_04_custom[EXE] [OPTIONS] [INPUT_FILE] | |
595 | ||
596 | ARGS: | |
597 | <INPUT_FILE> some regular input | |
598 | ||
599 | OPTIONS: | |
600 | -c <CONFIG> | |
601 | -h, --help Print help information | |
602 | --major auto inc major | |
603 | --minor auto inc minor | |
604 | --patch auto inc patch | |
605 | --set-ver <VER> set version manually | |
606 | --spec-in <SPEC_IN> some special input argument | |
607 | -V, --version Print version information | |
608 | ||
609 | $ 04_04_custom | |
610 | ? failed | |
923072b8 | 611 | error: Can only modify one version field |
04454e1e FG |
612 | |
613 | USAGE: | |
614 | 04_04_custom[EXE] [OPTIONS] [INPUT_FILE] | |
615 | ||
616 | For more information try --help | |
617 | ||
618 | $ 04_04_custom --major | |
619 | Version: 2.2.3 | |
620 | ||
621 | $ 04_04_custom --major --minor | |
622 | ? failed | |
923072b8 | 623 | error: Can only modify one version field |
04454e1e FG |
624 | |
625 | USAGE: | |
626 | 04_04_custom[EXE] [OPTIONS] [INPUT_FILE] | |
627 | ||
628 | For more information try --help | |
629 | ||
630 | $ 04_04_custom --major -c config.toml | |
631 | ? failed | |
632 | Version: 2.2.3 | |
633 | error: INPUT_FILE or --spec-in is required when using --config | |
634 | ||
635 | USAGE: | |
636 | 04_04_custom[EXE] [OPTIONS] [INPUT_FILE] | |
637 | ||
638 | For more information try --help | |
639 | ||
640 | $ 04_04_custom --major -c config.toml --spec-in input.txt | |
641 | Version: 2.2.3 | |
642 | Doing work using input input.txt and config config.toml | |
643 | ||
644 | ``` | |
645 | ||
646 | ## Tips | |
647 | ||
923072b8 FG |
648 | - For more complex demonstration of features, see our [examples](../README.md). |
649 | - Proactively check for bad `Command` configurations by calling `Command::debug_assert` in a test ([example](05_01_assert.rs)) | |
04454e1e FG |
650 | |
651 | ## Contributing | |
652 | ||
653 | New example code: | |
654 | - Please update the corresponding section in the [derive tutorial](../tutorial_derive/README.md) | |
655 | - Building: They must be added to [Cargo.toml](../../Cargo.toml) with the appropriate `required-features`. | |
656 | - Testing: Ensure there is a markdown file with [trycmd](https://docs.rs/trycmd) syntax (generally they'll go in here). | |
657 | ||
658 | See also the general [CONTRIBUTING](../../CONTRIBUTING.md). |