vendor/clap-3.2.20/src/_tutorial.rs

   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 //! ```