diff --git a/Cargo.toml b/Cargo.toml index 62528a7b1f4..93047d7f2dc 100644 --- a/Cargo.toml +++ b/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" diff --git a/examples/tutorial_builder/03_06_required.md b/examples/tutorial_builder/03_06_required.md new file mode 100644 index 00000000000..a12f198f8b0 --- /dev/null +++ b/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] + +Arguments: + + +Options: + -h, --help Print help + -V, --version Print version + +$ 03_06_required +? 2 +error: the following required arguments were not provided: + + +Usage: 03_06_required[EXE] + +For more information, try '--help'. + +$ 03_06_required bob +name: "bob" + +``` diff --git a/examples/tutorial_builder/03_06_required.rs b/examples/tutorial_builder/03_06_required.rs new file mode 100644 index 00000000000..31df3155507 --- /dev/null +++ b/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::("name") + .expect("clap `required` ensures its present") + ); +} diff --git a/examples/tutorial_derive/03_02_option.md b/examples/tutorial_derive/03_02_option.md index 24e272aa81b..5f71847edd6 100644 --- a/examples/tutorial_derive/03_02_option.md +++ b/examples/tutorial_derive/03_02_option.md @@ -2,7 +2,7 @@ $ 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 Options: -n, --name @@ -10,21 +10,27 @@ Options: -V, --version Print version $ 03_02_option_derive -name: None +? 2 +error: the following required arguments were not provided: + --name + +Usage: 03_02_option_derive[EXE] --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" ``` diff --git a/examples/tutorial_derive/03_02_option.rs b/examples/tutorial_derive/03_02_option.rs index 5fad3950ef4..4646e320a07 100644 --- a/examples/tutorial_derive/03_02_option.rs +++ b/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, + name: String, } fn main() { let cli = Cli::parse(); - println!("name: {:?}", cli.name.as_deref()); + println!("name: {:?}", cli.name); } diff --git a/examples/tutorial_derive/03_03_positional.md b/examples/tutorial_derive/03_03_positional.md index 9437c246f2e..8a4cfd58ce1 100644 --- a/examples/tutorial_derive/03_03_positional.md +++ b/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] Arguments: - [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: + + +Usage: 03_03_positional_derive[EXE] + +For more information, try '--help'. $ 03_03_positional_derive bob -name: Some("bob") +name: "bob" ``` diff --git a/examples/tutorial_derive/03_03_positional.rs b/examples/tutorial_derive/03_03_positional.rs index 5a8f73ebe9d..b69c07782ad 100644 --- a/examples/tutorial_derive/03_03_positional.rs +++ b/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, + name: String, } fn main() { let cli = Cli::parse(); - println!("name: {:?}", cli.name.as_deref()); + println!("name: {:?}", cli.name); } diff --git a/examples/tutorial_derive/03_06_optional.md b/examples/tutorial_derive/03_06_optional.md new file mode 100644 index 00000000000..eda036c21e5 --- /dev/null +++ b/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") + +``` diff --git a/examples/tutorial_derive/03_06_optional.rs b/examples/tutorial_derive/03_06_optional.rs new file mode 100644 index 00000000000..3187af5239d --- /dev/null +++ b/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, +} + +fn main() { + let cli = Cli::parse(); + + println!("name: {:?}", cli.name); +} diff --git a/src/_derive/_tutorial.rs b/src/_derive/_tutorial.rs index d47ca30bda3..51f3dcd2550 100644 --- a/src/_derive/_tutorial.rs +++ b/src/_derive/_tutorial.rs @@ -61,8 +61,9 @@ //! 1. [Positionals](#positionals) //! 2. [Options](#options) //! 3. [Flags](#flags) -//! 4. [Defaults](#defaults) -//! 5. [Subcommands](#subcommands) +//! 4. [Optional](#optional) +//! 5. [Defaults](#defaults) +//! 6. [Subcommands](#subcommands) //! //! Arguments are inferred from the fields of your struct. //! @@ -124,6 +125,15 @@ //! //! 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. diff --git a/src/_tutorial.rs b/src/_tutorial.rs index 44f773fa06e..0606279d372 100644 --- a/src/_tutorial.rs +++ b/src/_tutorial.rs @@ -62,8 +62,9 @@ //! 1. [Positionals](#positionals) //! 2. [Options](#options) //! 3. [Flags](#flags) -//! 4. [Defaults](#defaults) -//! 5. [Subcommands](#subcommands) +//! 4. [Required](#required) +//! 5. [Defaults](#defaults) +//! 6. [Subcommands](#subcommands) //! //! //! ### Positionals @@ -116,6 +117,15 @@ //! ``` #![doc = include_str!("../examples/tutorial_builder/03_01_flag_count.md")] //! +//! ### Required +//! +//! By default, an [`Arg`] is optional which can be changed with +//! [`required`][crate::Arg::required]. +//! ```rust +#![doc = include_str!("../examples/tutorial_builder/03_06_required.rs")] +//! ``` +#![doc = include_str!("../examples/tutorial_builder/03_06_required.md")] +//! //! ### Defaults //! //! We've previously showed that arguments can be [`required`][crate::Arg::required] or optional.