vendor/clap-3.2.20/src/_derive/_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: 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 `#[clap(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 //! ### Options
  78 //!
  79 //! You can name your arguments with a flag:
  80 //! - Order doesn't matter
  81 //! - They can be optional
  82 //! - Intent is clearer
  83 //!
  84 //! The `#[clap(short = 'n')]` and `#[clap(long = "name")]` attributes that define
  85 //! the flags are [`Arg`][crate::Args] methods that are derived from the field name when no value
  86 //! is specified (`#[clap(short)]` and `#[clap(long)]`).
  87 //!
  88 //! ```rust
  89 #![doc = include_str!("../../examples/tutorial_derive/03_02_option.rs")]
  90 //! ```
  91 #![doc = include_str!("../../examples/tutorial_derive/03_02_option.md")]
  92 //!
  93 //! ### Flags
  94 //!
  95 //! Flags can also be switches that can be on/off.  This is enabled via the
  96 //! `#[clap(action = ArgAction::SetTrue)]` attribute though this is implied when the field is a
  97 //! `bool`.
  98 //!
  99 //! ```rust
 100 #![doc = include_str!("../../examples/tutorial_derive/03_01_flag_bool.rs")]
 101 //! ```
 102 #![doc = include_str!("../../examples/tutorial_derive/03_01_flag_bool.md")]
 103 //!
 104 //! Or counted with `#[clap(action = clap::ArgAction::Count)]`:
 105 //!
 106 //! ```rust
 107 #![doc = include_str!("../../examples/tutorial_derive/03_01_flag_count.rs")]
 108 //! ```
 109 #![doc = include_str!("../../examples/tutorial_derive/03_01_flag_count.md")]
 110 //!
 111 //! ### Subcommands
 112 //!
 113 //! Subcommands are derived with `#[derive(Subcommand)]` and be added via `#[clap(subcommand)]` attribute. Each
 114 //! instance of a [Subcommand][crate::Subcommand] can have its own version, author(s), Args, and even its own
 115 //! subcommands.
 116 //!
 117 //! ```rust
 118 #![doc = include_str!("../../examples/tutorial_derive/03_04_subcommands.rs")]
 119 //! ```
 120 //! We used a struct-variant to define the `add` subcommand.
 121 //! Alternatively, you can use a struct for your subcommand's arguments:
 122 //! ```rust
 123 #![doc = include_str!("../../examples/tutorial_derive/03_04_subcommands_alt.rs")]
 124 //! ```
 125 //!
 126 #![doc = include_str!("../../examples/tutorial_derive/03_04_subcommands.md")]
 127 //!
 128 //! ### Defaults
 129 //!
 130 //! We've previously showed that arguments can be [`required`][crate::Arg::required] or optional.
 131 //! When optional, you work with a `Option` and can `unwrap_or`.  Alternatively, you can
 132 //! set `#[clap(default_value_t)]`.
 133 //!
 134 //! ```rust
 135 #![doc = include_str!("../../examples/tutorial_derive/03_05_default_values.rs")]
 136 //! ```
 137 #![doc = include_str!("../../examples/tutorial_derive/03_05_default_values.md")]
 138 //!
 139 //! ## Validation
 140 //!
 141 //! ### Enumerated values
 142 //!
 143 //! If you have arguments of specific values you want to test for, you can derive
 144 //! [`ValueEnum`][crate::ValueEnum].
 145 //!
 146 //! This allows you specify the valid values for that argument. If the user does not use one of
 147 //! those specific values, they will receive a graceful exit with error message informing them
 148 //! of the mistake, and what the possible valid values are
 149 //!
 150 //! ```rust
 151 #![doc = include_str!("../../examples/tutorial_derive/04_01_enum.rs")]
 152 //! ```
 153 #![doc = include_str!("../../examples/tutorial_derive/04_01_enum.md")]
 154 //!
 155 //! ### Validated values
 156 //!
 157 //! More generally, you can validate and parse into any data type.
 158 //!
 159 //! ```rust
 160 #![doc = include_str!("../../examples/tutorial_derive/04_02_parse.rs")]
 161 //! ```
 162 #![doc = include_str!("../../examples/tutorial_derive/04_02_parse.md")]
 163 //!
 164 //! A custom parser can be used to improve the error messages or provide additional validation:
 165 //!
 166 //! ```rust
 167 #![doc = include_str!("../../examples/tutorial_derive/04_02_validate.rs")]
 168 //! ```
 169 #![doc = include_str!("../../examples/tutorial_derive/04_02_validate.md")]
 170 //!
 171 //! ### Argument Relations
 172 //!
 173 //! You can declare dependencies or conflicts between [`Arg`][crate::Arg]s or even
 174 //! [`ArgGroup`][crate::ArgGroup]s.
 175 //!
 176 //! [`ArgGroup`][crate::ArgGroup]s  make it easier to declare relations instead of having to list
 177 //! each individually, or when you want a rule to apply "any but not all" arguments.
 178 //!
 179 //! Perhaps the most common use of [`ArgGroup`][crate::ArgGroup]s is to require one and *only* one
 180 //! argument to be present out of a given set. Imagine that you had multiple arguments, and you
 181 //! want one of them to be required, but making all of them required isn't feasible because perhaps
 182 //! they conflict with each other.
 183 //!
 184 //! ```rust
 185 #![doc = include_str!("../../examples/tutorial_derive/04_03_relations.rs")]
 186 //! ```
 187 #![doc = include_str!("../../examples/tutorial_derive/04_03_relations.md")]
 188 //!
 189 //! ### Custom Validation
 190 //!
 191 //! As a last resort, you can create custom errors with the basics of clap's formatting.
 192 //!
 193 //! ```rust
 194 #![doc = include_str!("../../examples/tutorial_derive/04_04_custom.rs")]
 195 //! ```
 196 #![doc = include_str!("../../examples/tutorial_derive/04_04_custom.md")]
 197 //!
 198 //! ## Testing
 199 //!
 200 //! clap reports most development errors as `debug_assert!`s.  Rather than checking every
 201 //! subcommand, you should have a test that calls
 202 //! [`Command::debug_assert`][crate::App::debug_assert]:
 203 //! ```rust,no_run
 204 #![doc = include_str!("../../examples/tutorial_derive/05_01_assert.rs")]
 205 //! ```