summaryrefslogtreecommitdiffstats
path: root/vendor/clap/examples/derive_ref
diff options
context:
space:
mode:
Diffstat (limited to 'vendor/clap/examples/derive_ref')
-rw-r--r--vendor/clap/examples/derive_ref/augment_args.rs27
-rw-r--r--vendor/clap/examples/derive_ref/augment_subcommands.rs21
-rw-r--r--vendor/clap/examples/derive_ref/flatten_hand_args.rs91
-rw-r--r--vendor/clap/examples/derive_ref/hand_subcommand.rs79
-rw-r--r--vendor/clap/examples/derive_ref/interop_tests.md248
5 files changed, 466 insertions, 0 deletions
diff --git a/vendor/clap/examples/derive_ref/augment_args.rs b/vendor/clap/examples/derive_ref/augment_args.rs
new file mode 100644
index 000000000..458beb44c
--- /dev/null
+++ b/vendor/clap/examples/derive_ref/augment_args.rs
@@ -0,0 +1,27 @@
+use clap::{arg, Args, Command, FromArgMatches as _};
+
+#[derive(Args, Debug)]
+struct DerivedArgs {
+ #[arg(short, long)]
+ derived: bool,
+}
+
+fn main() {
+ let cli = Command::new("CLI").arg(arg!(-b - -built).action(clap::ArgAction::SetTrue));
+ // Augment built args with derived args
+ let cli = DerivedArgs::augment_args(cli);
+
+ let matches = cli.get_matches();
+ println!("Value of built: {:?}", matches.get_flag("built"));
+ println!(
+ "Value of derived via ArgMatches: {:?}",
+ matches.get_flag("derived")
+ );
+
+ // Since DerivedArgs implements FromArgMatches, we can extract it from the unstructured ArgMatches.
+ // This is the main benefit of using derived arguments.
+ let derived_matches = DerivedArgs::from_arg_matches(&matches)
+ .map_err(|err| err.exit())
+ .unwrap();
+ println!("Value of derived: {:#?}", derived_matches);
+}
diff --git a/vendor/clap/examples/derive_ref/augment_subcommands.rs b/vendor/clap/examples/derive_ref/augment_subcommands.rs
new file mode 100644
index 000000000..577527500
--- /dev/null
+++ b/vendor/clap/examples/derive_ref/augment_subcommands.rs
@@ -0,0 +1,21 @@
+use clap::{Command, FromArgMatches as _, Parser, Subcommand as _};
+
+#[derive(Parser, Debug)]
+enum Subcommands {
+ Derived {
+ #[arg(short, long)]
+ derived_flag: bool,
+ },
+}
+
+fn main() {
+ let cli = Command::new("Built CLI");
+ // Augment with derived subcommands
+ let cli = Subcommands::augment_subcommands(cli);
+
+ let matches = cli.get_matches();
+ let derived_subcommands = Subcommands::from_arg_matches(&matches)
+ .map_err(|err| err.exit())
+ .unwrap();
+ println!("Derived subcommands: {:#?}", derived_subcommands);
+}
diff --git a/vendor/clap/examples/derive_ref/flatten_hand_args.rs b/vendor/clap/examples/derive_ref/flatten_hand_args.rs
new file mode 100644
index 000000000..2ceeb7c0f
--- /dev/null
+++ b/vendor/clap/examples/derive_ref/flatten_hand_args.rs
@@ -0,0 +1,91 @@
+use clap::error::Error;
+use clap::{Arg, ArgAction, ArgMatches, Args, Command, FromArgMatches, Parser};
+
+#[derive(Debug)]
+struct CliArgs {
+ foo: bool,
+ bar: bool,
+ quuz: Option<String>,
+}
+
+impl FromArgMatches for CliArgs {
+ fn from_arg_matches(matches: &ArgMatches) -> Result<Self, Error> {
+ let mut matches = matches.clone();
+ Self::from_arg_matches_mut(&mut matches)
+ }
+ fn from_arg_matches_mut(matches: &mut ArgMatches) -> Result<Self, Error> {
+ Ok(Self {
+ foo: matches.get_flag("foo"),
+ bar: matches.get_flag("bar"),
+ quuz: matches.remove_one::<String>("quuz"),
+ })
+ }
+ fn update_from_arg_matches(&mut self, matches: &ArgMatches) -> Result<(), Error> {
+ let mut matches = matches.clone();
+ self.update_from_arg_matches_mut(&mut matches)
+ }
+ fn update_from_arg_matches_mut(&mut self, matches: &mut ArgMatches) -> Result<(), Error> {
+ self.foo |= matches.get_flag("foo");
+ self.bar |= matches.get_flag("bar");
+ if let Some(quuz) = matches.remove_one::<String>("quuz") {
+ self.quuz = Some(quuz);
+ }
+ Ok(())
+ }
+}
+
+impl Args for CliArgs {
+ fn augment_args(cmd: Command) -> Command {
+ cmd.arg(
+ Arg::new("foo")
+ .short('f')
+ .long("foo")
+ .action(ArgAction::SetTrue),
+ )
+ .arg(
+ Arg::new("bar")
+ .short('b')
+ .long("bar")
+ .action(ArgAction::SetTrue),
+ )
+ .arg(
+ Arg::new("quuz")
+ .short('q')
+ .long("quuz")
+ .action(ArgAction::Set),
+ )
+ }
+ fn augment_args_for_update(cmd: Command) -> Command {
+ cmd.arg(
+ Arg::new("foo")
+ .short('f')
+ .long("foo")
+ .action(ArgAction::SetTrue),
+ )
+ .arg(
+ Arg::new("bar")
+ .short('b')
+ .long("bar")
+ .action(ArgAction::SetTrue),
+ )
+ .arg(
+ Arg::new("quuz")
+ .short('q')
+ .long("quuz")
+ .action(ArgAction::Set),
+ )
+ }
+}
+
+#[derive(Parser, Debug)]
+struct Cli {
+ #[arg(short, long)]
+ top_level: bool,
+ #[command(flatten)]
+ more_args: CliArgs,
+}
+
+fn main() {
+ let args = Cli::parse();
+ println!("{:#?}", args);
+}
diff --git a/vendor/clap/examples/derive_ref/hand_subcommand.rs b/vendor/clap/examples/derive_ref/hand_subcommand.rs
new file mode 100644
index 000000000..5ea169cd1
--- /dev/null
+++ b/vendor/clap/examples/derive_ref/hand_subcommand.rs
@@ -0,0 +1,79 @@
+use clap::error::{Error, ErrorKind};
+use clap::{ArgMatches, Args as _, Command, FromArgMatches, Parser, Subcommand};
+
+#[derive(Parser, Debug)]
+struct AddArgs {
+ name: Vec<String>,
+}
+#[derive(Parser, Debug)]
+struct RemoveArgs {
+ #[arg(short, long)]
+ force: bool,
+ name: Vec<String>,
+}
+
+#[derive(Debug)]
+enum CliSub {
+ Add(AddArgs),
+ Remove(RemoveArgs),
+}
+
+impl FromArgMatches for CliSub {
+ fn from_arg_matches(matches: &ArgMatches) -> Result<Self, Error> {
+ match matches.subcommand() {
+ Some(("add", args)) => Ok(Self::Add(AddArgs::from_arg_matches(args)?)),
+ Some(("remove", args)) => Ok(Self::Remove(RemoveArgs::from_arg_matches(args)?)),
+ Some((_, _)) => Err(Error::raw(
+ ErrorKind::InvalidSubcommand,
+ "Valid subcommands are `add` and `remove`",
+ )),
+ None => Err(Error::raw(
+ ErrorKind::MissingSubcommand,
+ "Valid subcommands are `add` and `remove`",
+ )),
+ }
+ }
+ fn update_from_arg_matches(&mut self, matches: &ArgMatches) -> Result<(), Error> {
+ match matches.subcommand() {
+ Some(("add", args)) => *self = Self::Add(AddArgs::from_arg_matches(args)?),
+ Some(("remove", args)) => *self = Self::Remove(RemoveArgs::from_arg_matches(args)?),
+ Some((_, _)) => {
+ return Err(Error::raw(
+ ErrorKind::InvalidSubcommand,
+ "Valid subcommands are `add` and `remove`",
+ ))
+ }
+ None => (),
+ };
+ Ok(())
+ }
+}
+
+impl Subcommand for CliSub {
+ fn augment_subcommands(cmd: Command) -> Command {
+ cmd.subcommand(AddArgs::augment_args(Command::new("add")))
+ .subcommand(RemoveArgs::augment_args(Command::new("remove")))
+ .subcommand_required(true)
+ }
+ fn augment_subcommands_for_update(cmd: Command) -> Command {
+ cmd.subcommand(AddArgs::augment_args(Command::new("add")))
+ .subcommand(RemoveArgs::augment_args(Command::new("remove")))
+ .subcommand_required(true)
+ }
+ fn has_subcommand(name: &str) -> bool {
+ matches!(name, "add" | "remove")
+ }
+}
+
+#[derive(Parser, Debug)]
+struct Cli {
+ #[arg(short, long)]
+ top_level: bool,
+ #[clap(subcommand)]
+ subcommand: CliSub,
+}
+
+fn main() {
+ let args = Cli::parse();
+ println!("{:#?}", args);
+}
diff --git a/vendor/clap/examples/derive_ref/interop_tests.md b/vendor/clap/examples/derive_ref/interop_tests.md
new file mode 100644
index 000000000..a7bcc7e7d
--- /dev/null
+++ b/vendor/clap/examples/derive_ref/interop_tests.md
@@ -0,0 +1,248 @@
+Following are tests for the interop examples in this directory.
+
+## Augment Args
+
+```console
+$ interop_augment_args
+Value of built: false
+Value of derived via ArgMatches: false
+Value of derived: DerivedArgs {
+ derived: false,
+}
+
+```
+
+```console
+$ interop_augment_args -b --derived
+Value of built: true
+Value of derived via ArgMatches: true
+Value of derived: DerivedArgs {
+ derived: true,
+}
+
+```
+
+```console
+$ interop_augment_args -d --built
+Value of built: true
+Value of derived via ArgMatches: true
+Value of derived: DerivedArgs {
+ derived: true,
+}
+
+```
+
+```console
+$ interop_augment_args --unknown
+? failed
+error: unexpected argument '--unknown' found
+
+Usage: interop_augment_args[EXE] [OPTIONS]
+
+For more information, try '--help'.
+
+```
+
+## Augment Subcommands
+
+```console
+$ interop_augment_subcommands
+? failed
+error: A subcommand is required but one was not provided.
+```
+
+```console
+$ interop_augment_subcommands derived
+Derived subcommands: Derived {
+ derived_flag: false,
+}
+
+```
+
+```console
+$ interop_augment_subcommands derived --derived-flag
+Derived subcommands: Derived {
+ derived_flag: true,
+}
+
+```
+
+```console
+$ interop_augment_subcommands derived --unknown
+? failed
+error: unexpected argument '--unknown' found
+
+Usage: interop_augment_subcommands[EXE] derived [OPTIONS]
+
+For more information, try '--help'.
+
+```
+
+```console
+$ interop_augment_subcommands unknown
+? failed
+error: unrecognized subcommand 'unknown'
+
+Usage: interop_augment_subcommands[EXE] [COMMAND]
+
+For more information, try '--help'.
+
+```
+
+## Hand-Implemented Subcommand
+
+```console
+$ interop_hand_subcommand
+? failed
+Usage: interop_hand_subcommand[EXE] [OPTIONS] <COMMAND>
+
+Commands:
+ add
+ remove
+ help Print this message or the help of the given subcommand(s)
+
+Options:
+ -t, --top-level
+ -h, --help Print help
+
+```
+
+```console
+$ interop_hand_subcommand add
+Cli {
+ top_level: false,
+ subcommand: Add(
+ AddArgs {
+ name: [],
+ },
+ ),
+}
+
+```
+
+```console
+$ interop_hand_subcommand add a b c
+Cli {
+ top_level: false,
+ subcommand: Add(
+ AddArgs {
+ name: [
+ "a",
+ "b",
+ "c",
+ ],
+ },
+ ),
+}
+
+```
+
+```console
+$ interop_hand_subcommand add --unknown
+? failed
+error: unexpected argument '--unknown' found
+
+ note: to pass '--unknown' as a value, use '-- --unknown'
+
+Usage: interop_hand_subcommand[EXE] add [NAME]...
+
+For more information, try '--help'.
+
+```
+
+```console
+$ interop_hand_subcommand remove
+Cli {
+ top_level: false,
+ subcommand: Remove(
+ RemoveArgs {
+ force: false,
+ name: [],
+ },
+ ),
+}
+
+```
+
+```console
+$ interop_hand_subcommand remove --force a b c
+Cli {
+ top_level: false,
+ subcommand: Remove(
+ RemoveArgs {
+ force: true,
+ name: [
+ "a",
+ "b",
+ "c",
+ ],
+ },
+ ),
+}
+
+```
+
+```console
+$ interop_hand_subcommand unknown
+? failed
+error: unrecognized subcommand 'unknown'
+
+Usage: interop_hand_subcommand[EXE] [OPTIONS] <COMMAND>
+
+For more information, try '--help'.
+
+```
+
+## Flatten Hand-Implemented Args
+
+```console
+$ interop_flatten_hand_args
+Cli {
+ top_level: false,
+ more_args: CliArgs {
+ foo: false,
+ bar: false,
+ quuz: None,
+ },
+}
+
+```
+
+```console
+$ interop_flatten_hand_args -f --bar
+Cli {
+ top_level: false,
+ more_args: CliArgs {
+ foo: true,
+ bar: true,
+ quuz: None,
+ },
+}
+
+```
+
+```console
+$ interop_flatten_hand_args --quuz abc
+Cli {
+ top_level: false,
+ more_args: CliArgs {
+ foo: false,
+ bar: false,
+ quuz: Some(
+ "abc",
+ ),
+ },
+}
+
+```
+
+```console
+$ interop_flatten_hand_args --unknown
+? failed
+error: unexpected argument '--unknown' found
+
+Usage: interop_flatten_hand_args[EXE] [OPTIONS]
+
+For more information, try '--help'.
+
+```
generated by cgit v1.2.3 (git 2.39.1) at 2024-07-23 20:46:01 +0000