docs(tutorial): Further expand on actions

Cargo.toml

@@ -183,11 +183,21 @@ name = "03_02_option"
 path = "examples/tutorial_builder/03_02_option.rs"
 required-features = ["cargo"]
 
+[[example]]
+name = "03_02_option_mult"
+path = "examples/tutorial_builder/03_02_option_mult.rs"
+required-features = ["cargo"]
+
 [[example]]
 name = "03_03_positional"
 path = "examples/tutorial_builder/03_03_positional.rs"
 required-features = ["cargo"]
 
+[[example]]
+name = "03_03_positional_mult"
+path = "examples/tutorial_builder/03_03_positional_mult.rs"
+required-features = ["cargo"]
+
 [[example]]
 name = "03_04_subcommands"
 path = "examples/tutorial_builder/03_04_subcommands.rs"
@@ -269,11 +279,21 @@ name = "03_02_option_derive"
 path = "examples/tutorial_derive/03_02_option.rs"
 required-features = ["derive"]
 
+[[example]]
+name = "03_02_option_mult_derive"
+path = "examples/tutorial_derive/03_02_option_mult.rs"
+required-features = ["derive"]
+
 [[example]]
 name = "03_03_positional_derive"
 path = "examples/tutorial_derive/03_03_positional.rs"
 required-features = ["derive"]
 
+[[example]]
+name = "03_03_positional_mult_derive"
+path = "examples/tutorial_derive/03_03_positional_mult.rs"
+required-features = ["derive"]
+
 [[example]]
 name = "03_04_subcommands_derive"
 path = "examples/tutorial_derive/03_04_subcommands.rs"

examples/tutorial_builder/03_02_option_mult.md

@@ -0,0 +1,32 @@
+```console
+$ 03_02_option_mult --help
+clap [..]
+A simple to use, efficient, and full-featured Command Line Argument Parser
+
+USAGE:
+    03_02_option_mult[EXE] [OPTIONS]
+
+OPTIONS:
+    -n, --name <name>    
+    -h, --help           Print help information
+    -V, --version        Print version information
+
+$ 03_02_option_mult
+name: None
+
+$ 03_02_option_mult --name bob
+name: Some("bob")
+
+$ 03_02_option_mult --name=bob
+name: Some("bob")
+
+$ 03_02_option_mult -n bob
+name: Some("bob")
+
+$ 03_02_option_mult -n=bob
+name: Some("bob")
+
+$ 03_02_option_mult -nbob
+name: Some("bob")
+
+```

examples/tutorial_builder/03_02_option_mult.rs

@@ -0,0 +1,14 @@
+use clap::{command, Arg, ArgAction};
+
+fn main() {
+    let matches = command!() // requires `cargo` feature
+        .arg(
+            Arg::new("name")
+                .short('n')
+                .long("name")
+                .action(ArgAction::Append),
+        )
+        .get_matches();
+
+    println!("name: {:?}", matches.get_one::<String>("name"));
+}

examples/tutorial_builder/03_03_positional_mult.md

@@ -0,0 +1,22 @@
+```console
+$ 03_03_positional_mult --help
+clap [..]
+A simple to use, efficient, and full-featured Command Line Argument Parser
+
+USAGE:
+    03_03_positional_mult[EXE] [name]...
+
+ARGS:
+    <name>...    
+
+OPTIONS:
+    -h, --help       Print help information
+    -V, --version    Print version information
+
+$ 03_03_positional_mult
+name: None
+
+$ 03_03_positional_mult bob
+name: Some("bob")
+
+```

examples/tutorial_builder/03_03_positional_mult.rs

@@ -0,0 +1,9 @@
+use clap::{command, Arg, ArgAction};
+
+fn main() {
+    let matches = command!() // requires `cargo` feature
+        .arg(Arg::new("name").action(ArgAction::Append))
+        .get_matches();
+
+    println!("name: {:?}", matches.get_one::<String>("name"));
+}

examples/tutorial_derive/03_02_option_mult.md

@@ -0,0 +1,32 @@
+```console
+$ 03_02_option_mult_derive --help
+clap [..]
+A simple to use, efficient, and full-featured Command Line Argument Parser
+
+USAGE:
+    03_02_option_mult_derive[EXE] [OPTIONS]
+
+OPTIONS:
+    -n, --name <NAME>    
+    -h, --help           Print help information
+    -V, --version        Print version information
+
+$ 03_02_option_mult_derive
+name: []
+
+$ 03_02_option_mult_derive --name bob
+name: ["bob"]
+
+$ 03_02_option_mult_derive --name=bob
+name: ["bob"]
+
+$ 03_02_option_mult_derive -n bob
+name: ["bob"]
+
+$ 03_02_option_mult_derive -n=bob
+name: ["bob"]
+
+$ 03_02_option_mult_derive -nbob
+name: ["bob"]
+
+```

examples/tutorial_derive/03_02_option_mult.rs

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

examples/tutorial_derive/03_03_positional_mult.md

@@ -0,0 +1,22 @@
+```console
+$ 03_03_positional_mult_derive --help
+clap [..]
+A simple to use, efficient, and full-featured Command Line Argument Parser
+
+USAGE:
+    03_03_positional_mult_derive[EXE] [NAME]...
+
+ARGS:
+    <NAME>...    
+
+OPTIONS:
+    -h, --help       Print help information
+    -V, --version    Print version information
+
+$ 03_03_positional_mult_derive
+name: []
+
+$ 03_03_positional_mult_derive bob
+name: ["bob"]
+
+```

examples/tutorial_derive/03_03_positional_mult.rs

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

src/_derive/_tutorial.rs

@@ -74,6 +74,13 @@
 //! ```
 #![doc = include_str!("../../examples/tutorial_derive/03_03_positional.md")]
 //!
+//! Note that the default [`ArgAction`][crate::ArgAction]` is [`Set`][crate::ArgAction::Set].  To
+//! accept multiple values, use [`Append`][crate::ArgAction::Append]:
+//! ```rust
+#![doc = include_str!("../../examples/tutorial_derive/03_03_positional_mult.rs")]
+//! ```
+#![doc = include_str!("../../examples/tutorial_derive/03_03_positional_mult.md")]
+//!
 //! ### Options
 //!
 //! You can name your arguments with a flag:
@@ -90,6 +97,13 @@
 //! ```
 #![doc = include_str!("../../examples/tutorial_derive/03_02_option.md")]
 //!
+//! Note that the default [`ArgAction`][crate::ArgAction]` is [`Set`][crate::ArgAction::Set].  To
+//! accept multiple occurrences, use [`Append`][crate::ArgAction::Append]:
+//! ```rust
+#![doc = include_str!("../../examples/tutorial_derive/03_02_option_mult.rs")]
+//! ```
+#![doc = include_str!("../../examples/tutorial_derive/03_02_option_mult.md")]
+//!
 //! ### Flags
 //!
 //! Flags can also be switches that can be on/off.  This is enabled via the
@@ -101,7 +115,9 @@
 //! ```
 #![doc = include_str!("../../examples/tutorial_derive/03_01_flag_bool.md")]
 //!
-//! Or counted with `#[clap(action = clap::ArgAction::Count)]`:
+//! Note that the default [`ArgAction`][crate::ArgAction]` for a `bool` field is
+//! [`SetTrue`][crate::ArgAction::SetTrue].  To accept multiple values, use
+//! [`Append`][crate::ArgAction::Append]:
 //!
 //! ```rust
 #![doc = include_str!("../../examples/tutorial_derive/03_01_flag_count.rs")]

src/_tutorial.rs

@@ -75,6 +75,13 @@
 //! ```
 #![doc = include_str!("../examples/tutorial_builder/03_03_positional.md")]
 //!
+//! Note that the default [`ArgAction`][crate::ArgAction]` is [`Set`][crate::ArgAction::Set].  To
+//! accept multiple values, use [`Append`][crate::ArgAction::Append]:
+//! ```rust
+#![doc = include_str!("../examples/tutorial_builder/03_03_positional_mult.rs")]
+//! ```
+#![doc = include_str!("../examples/tutorial_builder/03_03_positional_mult.md")]
+//!
 //! ### Options
 //!
 //! You can name your arguments with a flag:
@@ -87,6 +94,13 @@
 //! ```
 #![doc = include_str!("../examples/tutorial_builder/03_02_option.md")]
 //!
+//! Note that the default [`ArgAction`][crate::ArgAction]` is [`Set`][crate::ArgAction::Set].  To
+//! accept multiple occurrences, use [`Append`][crate::ArgAction::Append]:
+//! ```rust
+#![doc = include_str!("../examples/tutorial_builder/03_02_option_mult.rs")]
+//! ```
+#![doc = include_str!("../examples/tutorial_builder/03_02_option_mult.md")]
+//!
 //! ### Flags
 //!
 //! Flags can also be switches that can be on/off:
@@ -96,7 +110,9 @@
 //! ```
 #![doc = include_str!("../examples/tutorial_builder/03_01_flag_bool.md")]
 //!
-//! Or counted.
+//! Note that the default [`ArgAction`][crate::ArgAction]` for a `bool` field is
+//! [`SetTrue`][crate::ArgAction::SetTrue].  To accept multiple values, use
+//! [`Append`][crate::ArgAction::Append]:
 //!
 //! ```rust
 #![doc = include_str!("../examples/tutorial_builder/03_01_flag_count.rs")]