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