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: Builder 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 with several arguments using usage strings. 34 //! 35 //! ```rust 36 #![doc = include_str!("../examples/tutorial_builder/01_quick.rs")] 37 //! ``` 38 //! 39 #![doc = include_str!("../examples/tutorial_builder/01_quick.md")] 40 //! 41 //! ## Configuring the Parser 42 //! 43 //! You use [`Command`][crate::Command] to start building a parser. 44 //! 45 //! ```rust 46 #![doc = include_str!("../examples/tutorial_builder/02_apps.rs")] 47 //! ``` 48 //! 49 #![doc = include_str!("../examples/tutorial_builder/02_apps.md")] 50 //! 51 //! You can use [`command!()`][crate::command!] to fill these fields in from your `Cargo.toml` 52 //! file. **This requires the [`cargo` feature flag][crate::_features].** 53 //! 54 //! ```rust 55 #![doc = include_str!("../examples/tutorial_builder/02_crate.rs")] 56 //! ``` 57 #![doc = include_str!("../examples/tutorial_builder/02_crate.md")] 58 //! 59 //! You can use [`Command`][crate::Command] methods to change the application level behavior of 60 //! clap. 61 //! 62 //! ```rust 63 #![doc = include_str!("../examples/tutorial_builder/02_app_settings.rs")] 64 //! ``` 65 #![doc = include_str!("../examples/tutorial_builder/02_app_settings.md")] 66 //! 67 //! ## Adding Arguments 68 //! 69 //! ### Positionals 70 //! 71 //! You can have users specify values by their position on the command-line: 72 //! 73 //! ```rust 74 #![doc = include_str!("../examples/tutorial_builder/03_03_positional.rs")] 75 //! ``` 76 #![doc = include_str!("../examples/tutorial_builder/03_03_positional.md")] 77 //! 78 //! ### Options 79 //! 80 //! You can name your arguments with a flag: 81 //! - Order doesn't matter 82 //! - They can be optional 83 //! - Intent is clearer 84 //! 85 //! ```rust 86 #![doc = include_str!("../examples/tutorial_builder/03_02_option.rs")] 87 //! ``` 88 #![doc = include_str!("../examples/tutorial_builder/03_02_option.md")] 89 //! 90 //! ### Flags 91 //! 92 //! Flags can also be switches that can be on/off: 93 //! 94 //! ```rust 95 #![doc = include_str!("../examples/tutorial_builder/03_01_flag_bool.rs")] 96 //! ``` 97 #![doc = include_str!("../examples/tutorial_builder/03_01_flag_bool.md")] 98 //! 99 //! Or counted. 100 //! 101 //! ```rust 102 #![doc = include_str!("../examples/tutorial_builder/03_01_flag_count.rs")] 103 //! ``` 104 #![doc = include_str!("../examples/tutorial_builder/03_01_flag_count.md")] 105 //! 106 //! ### Subcommands 107 //! 108 //! Subcommands are defined as [`Command`][crate::Command]s that get added via 109 //! [`Command::subcommand`][crate::Command::subcommand]. Each instance of a Subcommand can have its 110 //! own version, author(s), Args, and even its own subcommands. 111 //! 112 //! ```rust 113 #![doc = include_str!("../examples/tutorial_builder/03_04_subcommands.rs")] 114 //! ``` 115 #![doc = include_str!("../examples/tutorial_builder/03_04_subcommands.md")] 116 //! 117 //! ### Defaults 118 //! 119 //! We've previously showed that arguments can be [`required`][crate::Arg::required] or optional. 120 //! When optional, you work with a `Option` and can `unwrap_or`. Alternatively, you can set 121 //! [`Arg::default_value`][crate::Arg::default_value]. 122 //! 123 //! ```rust 124 #![doc = include_str!("../examples/tutorial_builder/03_05_default_values.rs")] 125 //! ``` 126 #![doc = include_str!("../examples/tutorial_builder/03_05_default_values.md")] 127 //! 128 //! ## Validation 129 //! 130 //! ### Enumerated values 131 //! 132 //! If you have arguments of specific values you want to test for, you can use the 133 //! [`PossibleValuesParser`][crate::builder::PossibleValuesParser] or [`Arg::value_parser(["val1", 134 //! ...])`][crate::Arg::value_parser] for short. 135 //! 136 //! This allows you specify the valid values for that argument. If the user does not use one of 137 //! those specific values, they will receive a graceful exit with error message informing them 138 //! of the mistake, and what the possible valid values are 139 //! 140 //! ```rust 141 #![doc = include_str!("../examples/tutorial_builder/04_01_possible.rs")] 142 //! ``` 143 #![doc = include_str!("../examples/tutorial_builder/04_01_possible.md")] 144 //! 145 //! When enabling the [`derive` feature][crate::_features], you can use 146 //! [`ValueEnum`][crate::ValueEnum] to take care of the boiler plate for you, giving the same 147 //! results. 148 //! 149 //! ```rust 150 #![doc = include_str!("../examples/tutorial_builder/04_01_enum.rs")] 151 //! ``` 152 #![doc = include_str!("../examples/tutorial_builder/04_01_enum.md")] 153 //! 154 //! ### Validated values 155 //! 156 //! More generally, you can validate and parse into any data type. 157 //! 158 //! ```rust 159 #![doc = include_str!("../examples/tutorial_builder/04_02_parse.rs")] 160 //! ``` 161 #![doc = include_str!("../examples/tutorial_builder/04_02_parse.md")] 162 //! 163 //! A custom parser can be used to improve the error messages or provide additional validation: 164 //! 165 //! ```rust 166 #![doc = include_str!("../examples/tutorial_builder/04_02_validate.rs")] 167 //! ``` 168 #![doc = include_str!("../examples/tutorial_builder/04_02_validate.md")] 169 //! 170 //! ### Argument Relations 171 //! 172 //! You can declare dependencies or conflicts between [`Arg`][crate::Arg]s or even 173 //! [`ArgGroup`][crate::ArgGroup]s. 174 //! 175 //! [`ArgGroup`][crate::ArgGroup]s make it easier to declare relations instead of having to list 176 //! each individually, or when you want a rule to apply "any but not all" arguments. 177 //! 178 //! Perhaps the most common use of [`ArgGroup`][crate::ArgGroup]s is to require one and *only* one 179 //! argument to be present out of a given set. Imagine that you had multiple arguments, and you 180 //! want one of them to be required, but making all of them required isn't feasible because perhaps 181 //! they conflict with each other. 182 //! 183 //! ```rust 184 #![doc = include_str!("../examples/tutorial_builder/04_03_relations.rs")] 185 //! ``` 186 #![doc = include_str!("../examples/tutorial_builder/04_03_relations.md")] 187 //! 188 //! ### Custom Validation 189 //! 190 //! As a last resort, you can create custom errors with the basics of clap's formatting. 191 //! 192 //! ```rust 193 #![doc = include_str!("../examples/tutorial_builder/04_04_custom.rs")] 194 //! ``` 195 #![doc = include_str!("../examples/tutorial_builder/04_04_custom.md")] 196 //! 197 //! ## Testing 198 //! 199 //! clap reports most development errors as `debug_assert!`s. Rather than checking every 200 //! subcommand, you should have a test that calls 201 //! [`Command::debug_assert`][crate::App::debug_assert]: 202 //! ```rust,no_run 203 #![doc = include_str!("../examples/tutorial_builder/05_01_assert.rs")] 204 //! ``` 205