Merge pull request #5929 from epage/required

docs(tutorial): Explicitly cover required vs optional

Cargo.toml

@@ -323,6 +323,12 @@ path = "examples/tutorial_builder/03_05_default_values.rs"
 required-features = ["cargo"]
 doc-scrape-examples = true
 
+[[example]]
+name = "03_06_required"
+path = "examples/tutorial_builder/03_06_required.rs"
+required-features = ["cargo"]
+doc-scrape-examples = true
+
 [[example]]
 name = "04_01_possible"
 path = "examples/tutorial_builder/04_01_possible.rs"
@@ -444,6 +450,12 @@ path = "examples/tutorial_derive/03_05_default_values.rs"
 required-features = ["derive"]
 doc-scrape-examples = true
 
+[[example]]
+name = "03_06_optional_derive"
+path = "examples/tutorial_derive/03_06_optional.rs"
+required-features = ["derive"]
+doc-scrape-examples = true
+
 [[example]]
 name = "04_01_enum_derive"
 path = "examples/tutorial_derive/04_01_enum.rs"

examples/tutorial_builder/03_06_required.md

@@ -0,0 +1,26 @@
+```console
+$ 03_06_required --help
+A simple to use, efficient, and full-featured Command Line Argument Parser
+
+Usage: 03_06_required[EXE] <name>
+
+Arguments:
+  <name>  
+
+Options:
+  -h, --help     Print help
+  -V, --version  Print version
+
+$ 03_06_required
+? 2
+error: the following required arguments were not provided:
+  <name>
+
+Usage: 03_06_required[EXE] <name>
+
+For more information, try '--help'.
+
+$ 03_06_required bob
+name: "bob"
+
+```

examples/tutorial_builder/03_06_required.rs

@@ -0,0 +1,14 @@
+use clap::{command, Arg};
+
+fn main() {
+    let matches = command!() // requires `cargo` feature
+        .arg(Arg::new("name").required(true))
+        .get_matches();
+
+    println!(
+        "name: {:?}",
+        matches
+            .get_one::<String>("name")
+            .expect("clap `required` ensures its present")
+    );
+}

examples/tutorial_derive/03_02_option.md

@@ -2,29 +2,35 @@
 $ 03_02_option_derive --help
 A simple to use, efficient, and full-featured Command Line Argument Parser
 
-Usage: 03_02_option_derive[EXE] [OPTIONS]
+Usage: 03_02_option_derive[EXE] --name <NAME>
 
 Options:
   -n, --name <NAME>  
   -h, --help         Print help
   -V, --version      Print version
 
 $ 03_02_option_derive
-name: None
+? 2
+error: the following required arguments were not provided:
+  --name <NAME>
+
+Usage: 03_02_option_derive[EXE] --name <NAME>
+
+For more information, try '--help'.
 
 $ 03_02_option_derive --name bob
-name: Some("bob")
+name: "bob"
 
 $ 03_02_option_derive --name=bob
-name: Some("bob")
+name: "bob"
 
 $ 03_02_option_derive -n bob
-name: Some("bob")
+name: "bob"
 
 $ 03_02_option_derive -n=bob
-name: Some("bob")
+name: "bob"
 
 $ 03_02_option_derive -nbob
-name: Some("bob")
+name: "bob"
 
 ```

examples/tutorial_derive/03_02_option.rs

@@ -4,11 +4,11 @@ use clap::Parser;
 #[command(version, about, long_about = None)]
 struct Cli {
     #[arg(short, long)]
-    name: Option<String>,
+    name: String,
 }
 
 fn main() {
     let cli = Cli::parse();
 
-    println!("name: {:?}", cli.name.as_deref());
+    println!("name: {:?}", cli.name);
 }

examples/tutorial_derive/03_03_positional.md

@@ -2,19 +2,25 @@
 $ 03_03_positional_derive --help
 A simple to use, efficient, and full-featured Command Line Argument Parser
 
-Usage: 03_03_positional_derive[EXE] [NAME]
+Usage: 03_03_positional_derive[EXE] <NAME>
 
 Arguments:
-  [NAME]  
+  <NAME>  
 
 Options:
   -h, --help     Print help
   -V, --version  Print version
 
 $ 03_03_positional_derive
-name: None
+? 2
+error: the following required arguments were not provided:
+  <NAME>
+
+Usage: 03_03_positional_derive[EXE] <NAME>
+
+For more information, try '--help'.
 
 $ 03_03_positional_derive bob
-name: Some("bob")
+name: "bob"
 
 ```

examples/tutorial_derive/03_03_positional.rs

@@ -3,11 +3,11 @@ use clap::Parser;
 #[derive(Parser)]
 #[command(version, about, long_about = None)]
 struct Cli {
-    name: Option<String>,
+    name: String,
 }
 
 fn main() {
     let cli = Cli::parse();
 
-    println!("name: {:?}", cli.name.as_deref());
+    println!("name: {:?}", cli.name);
 }

examples/tutorial_derive/03_06_optional.md

@@ -0,0 +1,20 @@
+```console
+$ 03_06_optional_derive --help
+A simple to use, efficient, and full-featured Command Line Argument Parser
+
+Usage: 03_06_optional_derive[EXE] [NAME]
+
+Arguments:
+  [NAME]  
+
+Options:
+  -h, --help     Print help
+  -V, --version  Print version
+
+$ 03_06_optional_derive
+name: None
+
+$ 03_06_optional_derive bob
+name: Some("bob")
+
+```

examples/tutorial_derive/03_06_optional.rs

@@ -0,0 +1,13 @@
+use clap::Parser;
+
+#[derive(Parser)]
+#[command(version, about, long_about = None)]
+struct Cli {
+    name: Option<String>,
+}
+
+fn main() {
+    let cli = Cli::parse();
+
+    println!("name: {:?}", cli.name);
+}

src/_derive/_tutorial.rs

@@ -61,8 +61,9 @@
 //! 1. [Positionals](#positionals)
 //! 2. [Options](#options)
 //! 3. [Flags](#flags)
-//! 4. [Subcommands](#subcommands)
+//! 4. [Optional](#optional)
 //! 5. [Defaults](#defaults)
+//! 6. [Subcommands](#subcommands)
 //!
 //! Arguments are inferred from the fields of your struct.
 //!
@@ -85,9 +86,8 @@
 //! ### Options
 //!
 //! You can name your arguments with a flag:
+//! - Intent of the value is clearer
 //! - Order doesn't matter
-//! - They can be optional
-//! - Intent is clearer
 //!
 //! To specify the flags for an argument, you can use [`#[arg(short = 'n')]`][Arg::short] and/or
 //! [`#[arg(long = "name")]`][Arg::long] attributes on a field.  When no value is given (e.g.
@@ -125,6 +125,26 @@
 //!
 //! This also shows that any[`Arg`][crate::Args] method may be used as an attribute.
 //!
+//! ### Optional
+//!
+//! By default, arguments are assumed to be [`required`][crate::Arg::required].
+//! To make an argument optional, wrap the field's type in `Option`:
+//! ```rust
+#![doc = include_str!("../../examples/tutorial_derive/03_06_optional.rs")]
+//! ```
+#![doc = include_str!("../../examples/tutorial_derive/03_06_optional.md")]
+//!
+//! ### Defaults
+//!
+//! We've previously showed that arguments can be [`required`][crate::Arg::required] or optional.
+//! When optional, you work with a `Option` and can `unwrap_or`.  Alternatively, you can
+//! set [`#[arg(default_value_t)]`][super#arg-attributes].
+//!
+//! ```rust
+#![doc = include_str!("../../examples/tutorial_derive/03_05_default_values.rs")]
+//! ```
+#![doc = include_str!("../../examples/tutorial_derive/03_05_default_values.md")]
+//!
 //! ### Subcommands
 //!
 //! Subcommands are derived with `#[derive(Subcommand)]` and be added via
@@ -143,17 +163,6 @@
 //!
 #![doc = include_str!("../../examples/tutorial_derive/03_04_subcommands.md")]
 //!
-//! ### Defaults
-//!
-//! We've previously showed that arguments can be [`required`][crate::Arg::required] or optional.
-//! When optional, you work with a `Option` and can `unwrap_or`.  Alternatively, you can
-//! set [`#[arg(default_value_t)]`][super#arg-attributes].
-//!
-//! ```rust
-#![doc = include_str!("../../examples/tutorial_derive/03_05_default_values.rs")]
-//! ```
-#![doc = include_str!("../../examples/tutorial_derive/03_05_default_values.md")]
-//!
 //! ## Validation
 //!
 //! 1. [Enumerated values](#enumerated-values)

src/_tutorial.rs

@@ -62,8 +62,9 @@
 //! 1. [Positionals](#positionals)
 //! 2. [Options](#options)
 //! 3. [Flags](#flags)
-//! 4. [Subcommands](#subcommands)
+//! 4. [Required](#required)
 //! 5. [Defaults](#defaults)
+//! 6. [Subcommands](#subcommands)
 //!
 //!
 //! ### Positionals
@@ -85,9 +86,8 @@
 //! ### Options
 //!
 //! You can name your arguments with a flag:
+//! - Intent of the value is clearer
 //! - Order doesn't matter
-//! - They can be optional
-//! - Intent is clearer
 //!
 //! ```rust
 #![doc = include_str!("../examples/tutorial_builder/03_02_option.rs")]
@@ -117,16 +117,14 @@
 //! ```
 #![doc = include_str!("../examples/tutorial_builder/03_01_flag_count.md")]
 //!
-//! ### Subcommands
-//!
-//! Subcommands are defined as [`Command`][crate::Command]s that get added via
-//! [`Command::subcommand`][crate::Command::subcommand]. Each instance of a Subcommand can have its
-//! own version, author(s), Args, and even its own subcommands.
+//! ### Required
 //!
+//! By default, an [`Arg`] is optional which can be changed with
+//! [`required`][crate::Arg::required].
 //! ```rust
-#![doc = include_str!("../examples/tutorial_builder/03_04_subcommands.rs")]
+#![doc = include_str!("../examples/tutorial_builder/03_06_required.rs")]
 //! ```
-#![doc = include_str!("../examples/tutorial_builder/03_04_subcommands.md")]
+#![doc = include_str!("../examples/tutorial_builder/03_06_required.md")]
 //!
 //! ### Defaults
 //!
@@ -139,6 +137,17 @@
 //! ```
 #![doc = include_str!("../examples/tutorial_builder/03_05_default_values.md")]
 //!
+//! ### Subcommands
+//!
+//! Subcommands are defined as [`Command`][crate::Command]s that get added via
+//! [`Command::subcommand`][crate::Command::subcommand]. Each instance of a Subcommand can have its
+//! own version, author(s), Args, and even its own subcommands.
+//!
+//! ```rust
+#![doc = include_str!("../examples/tutorial_builder/03_04_subcommands.rs")]
+//! ```
+#![doc = include_str!("../examples/tutorial_builder/03_04_subcommands.md")]
+//!
 //! ## Validation
 //!
 //! 1. [Enumerated values](#enumerated-values)