1 // Contributing 2 // 3 // New example code: 4 // - Please update the corresponding section in the derive tutorial 5 // - Building: They must be added to `Cargo.toml` with the appropriate `required-features`. 6 // - Testing: Ensure there is a markdown file with [trycmd](https://docs.rs/trycmd) syntax 7 // 8 // See also the general CONTRIBUTING 9 10 //! # Documentation: Derive Tutorial 11 //! 12 //! 1. [Quick Start](#quick-start) 13 //! 2. [Configuring the Parser](#configuring-the-parser) 14 //! 3. [Adding Arguments](#adding-arguments) 15 //! 1. [Positionals](#positionals) 16 //! 2. [Options](#options) 17 //! 3. [Flags](#flags) 18 //! 4. [Subcommands](#subcommands) 19 //! 5. [Defaults](#defaults) 20 //! 4. Validation 21 //! 1. [Enumerated values](#enumerated-values) 22 //! 2. [Validated values](#validated-values) 23 //! 3. [Argument Relations](#argument-relations) 24 //! 4. [Custom Validation](#custom-validation) 25 //! 5. [Testing](#testing) 26 //! 27 //! See also 28 //! - [FAQ: When should I use the builder vs derive APIs?][crate::_faq#when-should-i-use-the-builder-vs-derive-apis] 29 //! - The [cookbook][crate::_cookbook] for more application-focused examples 30 //! 31 //! ## Quick Start 32 //! 33 //! You can create an application declaratively with a `struct` and some 34 //! attributes. **This requires enabling the [`derive` feature flag][crate::_features].** 35 //! 36 //! ```rust 37 #![doc = include_str!("../../examples/tutorial_derive/01_quick.rs")] 38 //! ``` 39 //! 40 #![doc = include_str!("../../examples/tutorial_derive/01_quick.md")] 41 //! 42 //! ## Configuring the Parser 43 //! 44 //! You use derive [`Parser`][crate::Parser] to start building a parser. 45 //! 46 //! ```rust 47 #![doc = include_str!("../../examples/tutorial_derive/02_apps.rs")] 48 //! ``` 49 //! 50 #![doc = include_str!("../../examples/tutorial_derive/02_apps.md")] 51 //! 52 //! You can use `#[command(author, version, about)]` attribute defaults to fill these fields in from your `Cargo.toml` file. 53 //! 54 //! ```rust 55 #![doc = include_str!("../../examples/tutorial_derive/02_crate.rs")] 56 //! ``` 57 #![doc = include_str!("../../examples/tutorial_derive/02_crate.md")] 58 //! 59 //! You can use attributes to change the application level behavior of clap. Any [`Command`][crate::Command] builder function can be used as an attribute. 60 //! 61 //! ```rust 62 #![doc = include_str!("../../examples/tutorial_derive/02_app_settings.rs")] 63 //! ``` 64 #![doc = include_str!("../../examples/tutorial_derive/02_app_settings.md")] 65 //! 66 //! ## Adding Arguments 67 //! 68 //! ### Positionals 69 //! 70 //! You can have users specify values by their position on the command-line: 71 //! 72 //! ```rust 73 #![doc = include_str!("../../examples/tutorial_derive/03_03_positional.rs")] 74 //! ``` 75 #![doc = include_str!("../../examples/tutorial_derive/03_03_positional.md")] 76 //! 77 //! Note that the default [`ArgAction`][crate::ArgAction] is [`Set`][crate::ArgAction::Set]. To 78 //! accept multiple values, use [`Append`][crate::ArgAction::Append]: 79 //! ```rust 80 #![doc = include_str!("../../examples/tutorial_derive/03_03_positional_mult.rs")] 81 //! ``` 82 #![doc = include_str!("../../examples/tutorial_derive/03_03_positional_mult.md")] 83 //! 84 //! ### Options 85 //! 86 //! You can name your arguments with a flag: 87 //! - Order doesn't matter 88 //! - They can be optional 89 //! - Intent is clearer 90 //! 91 //! The `#[arg(short = 'n')]` and `#[arg(long = "name")]` attributes that define 92 //! the flags are [`Arg`][crate::Args] methods that are derived from the field name when no value 93 //! is specified (`#[arg(short)]` and `#[arg(long)]`). 94 //! 95 //! ```rust 96 #![doc = include_str!("../../examples/tutorial_derive/03_02_option.rs")] 97 //! ``` 98 #![doc = include_str!("../../examples/tutorial_derive/03_02_option.md")] 99 //! 100 //! Note that the default [`ArgAction`][crate::ArgAction] is [`Set`][crate::ArgAction::Set]. To 101 //! accept multiple occurrences, use [`Append`][crate::ArgAction::Append]: 102 //! ```rust 103 #![doc = include_str!("../../examples/tutorial_derive/03_02_option_mult.rs")] 104 //! ``` 105 #![doc = include_str!("../../examples/tutorial_derive/03_02_option_mult.md")] 106 //! 107 //! ### Flags 108 //! 109 //! Flags can also be switches that can be on/off. This is enabled via the 110 //! `#[arg(action = ArgAction::SetTrue)]` attribute though this is implied when the field is a 111 //! `bool`. 112 //! 113 //! ```rust 114 #![doc = include_str!("../../examples/tutorial_derive/03_01_flag_bool.rs")] 115 //! ``` 116 #![doc = include_str!("../../examples/tutorial_derive/03_01_flag_bool.md")] 117 //! 118 //! Note that the default [`ArgAction`][crate::ArgAction] for a `bool` field is 119 //! [`SetTrue`][crate::ArgAction::SetTrue]. To accept multiple flags, use 120 //! [`Count`][crate::ArgAction::Count]: 121 //! 122 //! ```rust 123 #![doc = include_str!("../../examples/tutorial_derive/03_01_flag_count.rs")] 124 //! ``` 125 #![doc = include_str!("../../examples/tutorial_derive/03_01_flag_count.md")] 126 //! 127 //! ### Subcommands 128 //! 129 //! Subcommands are derived with `#[derive(Subcommand)]` and be added via `#[command(subcommand)]` attribute. Each 130 //! instance of a [Subcommand][crate::Subcommand] can have its own version, author(s), Args, and even its own 131 //! subcommands. 132 //! 133 //! ```rust 134 #![doc = include_str!("../../examples/tutorial_derive/03_04_subcommands.rs")] 135 //! ``` 136 //! We used a struct-variant to define the `add` subcommand. 137 //! Alternatively, you can use a struct for your subcommand's arguments: 138 //! ```rust 139 #![doc = include_str!("../../examples/tutorial_derive/03_04_subcommands_alt.rs")] 140 //! ``` 141 //! 142 #![doc = include_str!("../../examples/tutorial_derive/03_04_subcommands.md")] 143 //! 144 //! ### Defaults 145 //! 146 //! We've previously showed that arguments can be [`required`][crate::Arg::required] or optional. 147 //! When optional, you work with a `Option` and can `unwrap_or`. Alternatively, you can 148 //! set `#[arg(default_value_t)]`. 149 //! 150 //! ```rust 151 #![doc = include_str!("../../examples/tutorial_derive/03_05_default_values.rs")] 152 //! ``` 153 #![doc = include_str!("../../examples/tutorial_derive/03_05_default_values.md")] 154 //! 155 //! ## Validation 156 //! 157 //! An appropriate default parser/validator will be selected for the field's type. See 158 //! [`value_parser!`][crate::value_parser!] for more details. 159 //! 160 //! ### Enumerated values 161 //! 162 //! For example, if you have arguments of specific values you want to test for, you can derive 163 //! [`ValueEnum`][crate::ValueEnum]. 164 //! 165 //! This allows you specify the valid values for that argument. If the user does not use one of 166 //! those specific values, they will receive a graceful exit with error message informing them 167 //! of the mistake, and what the possible valid values are 168 //! 169 //! ```rust 170 #![doc = include_str!("../../examples/tutorial_derive/04_01_enum.rs")] 171 //! ``` 172 #![doc = include_str!("../../examples/tutorial_derive/04_01_enum.md")] 173 //! 174 //! ### Validated values 175 //! 176 //! More generally, you can validate and parse into any data type. 177 //! 178 //! ```rust 179 #![doc = include_str!("../../examples/tutorial_derive/04_02_parse.rs")] 180 //! ``` 181 #![doc = include_str!("../../examples/tutorial_derive/04_02_parse.md")] 182 //! 183 //! A custom parser can be used to improve the error messages or provide additional validation: 184 //! 185 //! ```rust 186 #![doc = include_str!("../../examples/tutorial_derive/04_02_validate.rs")] 187 //! ``` 188 #![doc = include_str!("../../examples/tutorial_derive/04_02_validate.md")] 189 //! 190 //! See [`Arg::value_parser`][crate::Arg::value_parser] for more details. 191 //! 192 //! ### Argument Relations 193 //! 194 //! You can declare dependencies or conflicts between [`Arg`][crate::Arg]s or even 195 //! [`ArgGroup`][crate::ArgGroup]s. 196 //! 197 //! [`ArgGroup`][crate::ArgGroup]s make it easier to declare relations instead of having to list 198 //! each individually, or when you want a rule to apply "any but not all" arguments. 199 //! 200 //! Perhaps the most common use of [`ArgGroup`][crate::ArgGroup]s is to require one and *only* one 201 //! argument to be present out of a given set. Imagine that you had multiple arguments, and you 202 //! want one of them to be required, but making all of them required isn't feasible because perhaps 203 //! they conflict with each other. 204 //! 205 //! ```rust 206 #![doc = include_str!("../../examples/tutorial_derive/04_03_relations.rs")] 207 //! ``` 208 #![doc = include_str!("../../examples/tutorial_derive/04_03_relations.md")] 209 //! 210 //! ### Custom Validation 211 //! 212 //! As a last resort, you can create custom errors with the basics of clap's formatting. 213 //! 214 //! ```rust 215 #![doc = include_str!("../../examples/tutorial_derive/04_04_custom.rs")] 216 //! ``` 217 #![doc = include_str!("../../examples/tutorial_derive/04_04_custom.md")] 218 //! 219 //! ## Testing 220 //! 221 //! clap reports most development errors as `debug_assert!`s. Rather than checking every 222 //! subcommand, you should have a test that calls 223 //! [`Command::debug_assert`][crate::Command::debug_assert]: 224 //! ```rust,no_run 225 #![doc = include_str!("../../examples/tutorial_derive/05_01_assert.rs")] 226 //! ``` 227