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