summaryrefslogtreecommitdiffstats
path: root/vendor/clap/src/builder
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-17 12:11:38 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-17 12:13:23 +0000
commit20431706a863f92cb37dc512fef6e48d192aaf2c (patch)
tree2867f13f5fd5437ba628c67d7f87309ccadcd286 /vendor/clap/src/builder
parentReleasing progress-linux version 1.65.0+dfsg1-2~progress7.99u1. (diff)
downloadrustc-20431706a863f92cb37dc512fef6e48d192aaf2c.tar.xz
rustc-20431706a863f92cb37dc512fef6e48d192aaf2c.zip
Merging upstream version 1.66.0+dfsg1.
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'vendor/clap/src/builder')
-rw-r--r--vendor/clap/src/builder/action.rs325
-rw-r--r--vendor/clap/src/builder/app_settings.rs864
-rw-r--r--vendor/clap/src/builder/arg.rs5494
-rw-r--r--vendor/clap/src/builder/arg_group.rs633
-rw-r--r--vendor/clap/src/builder/arg_predicate.rs14
-rw-r--r--vendor/clap/src/builder/arg_settings.rs456
-rw-r--r--vendor/clap/src/builder/command.rs5189
-rw-r--r--vendor/clap/src/builder/debug_asserts.rs851
-rw-r--r--vendor/clap/src/builder/macros.rs180
-rw-r--r--vendor/clap/src/builder/mod.rs61
-rw-r--r--vendor/clap/src/builder/possible_value.rs259
-rw-r--r--vendor/clap/src/builder/regex.rs88
-rw-r--r--vendor/clap/src/builder/tests.rs56
-rw-r--r--vendor/clap/src/builder/usage_parser.rs1277
-rw-r--r--vendor/clap/src/builder/value_hint.rs95
-rw-r--r--vendor/clap/src/builder/value_parser.rs2089
16 files changed, 0 insertions, 17931 deletions
diff --git a/vendor/clap/src/builder/action.rs b/vendor/clap/src/builder/action.rs
deleted file mode 100644
index 71a91a8b1..000000000
--- a/vendor/clap/src/builder/action.rs
+++ /dev/null
@@ -1,325 +0,0 @@
-/// Behavior of arguments when they are encountered while parsing
-///
-/// # Examples
-///
-/// ```rust
-/// # use clap::Command;
-/// # use clap::Arg;
-/// let cmd = Command::new("mycmd")
-/// .arg(
-/// Arg::new("special-help")
-/// .short('?')
-/// .action(clap::ArgAction::Help)
-/// );
-///
-/// // Existing help still exists
-/// let err = cmd.clone().try_get_matches_from(["mycmd", "-h"]).unwrap_err();
-/// assert_eq!(err.kind(), clap::error::ErrorKind::DisplayHelp);
-///
-/// // New help available
-/// let err = cmd.try_get_matches_from(["mycmd", "-?"]).unwrap_err();
-/// assert_eq!(err.kind(), clap::error::ErrorKind::DisplayHelp);
-/// ```
-#[derive(Clone, Debug)]
-#[non_exhaustive]
-#[allow(missing_copy_implementations)] // In the future, we may accept `Box<dyn ...>`
-pub enum ArgAction {
- /// When encountered, store the associated value(s) in [`ArgMatches`][crate::ArgMatches]
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::Command;
- /// # use clap::Arg;
- /// let cmd = Command::new("mycmd")
- /// .arg(
- /// Arg::new("flag")
- /// .long("flag")
- /// .action(clap::ArgAction::Set)
- /// );
- ///
- /// let matches = cmd.try_get_matches_from(["mycmd", "--flag", "value"]).unwrap();
- /// assert!(matches.contains_id("flag"));
- /// assert_eq!(matches.occurrences_of("flag"), 0);
- /// assert_eq!(
- /// matches.get_many::<String>("flag").unwrap_or_default().map(|v| v.as_str()).collect::<Vec<_>>(),
- /// vec!["value"]
- /// );
- /// ```
- Set,
- /// When encountered, store the associated value(s) in [`ArgMatches`][crate::ArgMatches]
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::Command;
- /// # use clap::Arg;
- /// let cmd = Command::new("mycmd")
- /// .arg(
- /// Arg::new("flag")
- /// .long("flag")
- /// .action(clap::ArgAction::Append)
- /// );
- ///
- /// let matches = cmd.try_get_matches_from(["mycmd", "--flag", "value1", "--flag", "value2"]).unwrap();
- /// assert!(matches.contains_id("flag"));
- /// assert_eq!(matches.occurrences_of("flag"), 0);
- /// assert_eq!(
- /// matches.get_many::<String>("flag").unwrap_or_default().map(|v| v.as_str()).collect::<Vec<_>>(),
- /// vec!["value1", "value2"]
- /// );
- /// ```
- Append,
- /// Deprecated, replaced with [`ArgAction::Set`] or [`ArgAction::Append`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.2.0",
- note = "Replaced with `ArgAction::Set` or `ArgAction::Append`"
- )
- )]
- StoreValue,
- /// Deprecated, replaced with [`ArgAction::SetTrue`] or [`ArgAction::Count`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.2.0",
- note = "Replaced with `ArgAction::SetTrue` or `ArgAction::Count`"
- )
- )]
- IncOccurrence,
- /// When encountered, act as if `"true"` was encountered on the command-line
- ///
- /// If no [`default_value`][super::Arg::default_value] is set, it will be `false`.
- ///
- /// No value is allowed. To optionally accept a value, see
- /// [`Arg::default_missing_value`][super::Arg::default_missing_value]
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::Command;
- /// # use clap::Arg;
- /// let cmd = Command::new("mycmd")
- /// .arg(
- /// Arg::new("flag")
- /// .long("flag")
- /// .action(clap::ArgAction::SetTrue)
- /// );
- ///
- /// let matches = cmd.clone().try_get_matches_from(["mycmd", "--flag", "--flag"]).unwrap();
- /// assert!(matches.contains_id("flag"));
- /// assert_eq!(matches.occurrences_of("flag"), 0);
- /// assert_eq!(
- /// matches.get_one::<bool>("flag").copied(),
- /// Some(true)
- /// );
- ///
- /// let matches = cmd.try_get_matches_from(["mycmd"]).unwrap();
- /// assert!(matches.contains_id("flag"));
- /// assert_eq!(matches.occurrences_of("flag"), 0);
- /// assert_eq!(
- /// matches.get_one::<bool>("flag").copied(),
- /// Some(false)
- /// );
- /// ```
- SetTrue,
- /// When encountered, act as if `"false"` was encountered on the command-line
- ///
- /// If no [`default_value`][super::Arg::default_value] is set, it will be `true`.
- ///
- /// No value is allowed. To optionally accept a value, see
- /// [`Arg::default_missing_value`][super::Arg::default_missing_value]
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::Command;
- /// # use clap::Arg;
- /// let cmd = Command::new("mycmd")
- /// .arg(
- /// Arg::new("flag")
- /// .long("flag")
- /// .action(clap::ArgAction::SetFalse)
- /// );
- ///
- /// let matches = cmd.clone().try_get_matches_from(["mycmd", "--flag", "--flag"]).unwrap();
- /// assert!(matches.contains_id("flag"));
- /// assert_eq!(matches.occurrences_of("flag"), 0);
- /// assert_eq!(
- /// matches.get_one::<bool>("flag").copied(),
- /// Some(false)
- /// );
- ///
- /// let matches = cmd.try_get_matches_from(["mycmd"]).unwrap();
- /// assert!(matches.contains_id("flag"));
- /// assert_eq!(matches.occurrences_of("flag"), 0);
- /// assert_eq!(
- /// matches.get_one::<bool>("flag").copied(),
- /// Some(true)
- /// );
- /// ```
- SetFalse,
- /// When encountered, increment a `u8` counter
- ///
- /// If no [`default_value`][super::Arg::default_value] is set, it will be `0`.
- ///
- /// No value is allowed. To optionally accept a value, see
- /// [`Arg::default_missing_value`][super::Arg::default_missing_value]
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::Command;
- /// # use clap::Arg;
- /// let cmd = Command::new("mycmd")
- /// .arg(
- /// Arg::new("flag")
- /// .long("flag")
- /// .action(clap::ArgAction::Count)
- /// );
- ///
- /// let matches = cmd.clone().try_get_matches_from(["mycmd", "--flag", "--flag"]).unwrap();
- /// assert!(matches.contains_id("flag"));
- /// assert_eq!(matches.occurrences_of("flag"), 0);
- /// assert_eq!(
- /// matches.get_count("flag"),
- /// 2
- /// );
- ///
- /// let matches = cmd.try_get_matches_from(["mycmd"]).unwrap();
- /// assert!(matches.contains_id("flag"));
- /// assert_eq!(matches.occurrences_of("flag"), 0);
- /// assert_eq!(
- /// matches.get_count("flag"),
- /// 0
- /// );
- /// ```
- Count,
- /// When encountered, display [`Command::print_help`][super::App::print_help]
- ///
- /// Depending on the flag, [`Command::print_long_help`][super::App::print_long_help] may be shown
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::Command;
- /// # use clap::Arg;
- /// let cmd = Command::new("mycmd")
- /// .arg(
- /// Arg::new("special-help")
- /// .short('?')
- /// .action(clap::ArgAction::Help)
- /// );
- ///
- /// // Existing help still exists
- /// let err = cmd.clone().try_get_matches_from(["mycmd", "-h"]).unwrap_err();
- /// assert_eq!(err.kind(), clap::error::ErrorKind::DisplayHelp);
- ///
- /// // New help available
- /// let err = cmd.try_get_matches_from(["mycmd", "-?"]).unwrap_err();
- /// assert_eq!(err.kind(), clap::error::ErrorKind::DisplayHelp);
- /// ```
- Help,
- /// When encountered, display [`Command::version`][super::App::version]
- ///
- /// Depending on the flag, [`Command::long_version`][super::App::long_version] may be shown
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::Command;
- /// # use clap::Arg;
- /// let cmd = Command::new("mycmd")
- /// .version("1.0.0")
- /// .arg(
- /// Arg::new("special-version")
- /// .long("special-version")
- /// .action(clap::ArgAction::Version)
- /// );
- ///
- /// // Existing help still exists
- /// let err = cmd.clone().try_get_matches_from(["mycmd", "--version"]).unwrap_err();
- /// assert_eq!(err.kind(), clap::error::ErrorKind::DisplayVersion);
- ///
- /// // New help available
- /// let err = cmd.try_get_matches_from(["mycmd", "--special-version"]).unwrap_err();
- /// assert_eq!(err.kind(), clap::error::ErrorKind::DisplayVersion);
- /// ```
- Version,
-}
-
-impl ArgAction {
- /// Returns whether this action accepts values on the command-line
- ///
- /// [`default_values`][super::Arg::default_values] and [`env`][super::Arg::env] may still be
- /// processed.
- pub fn takes_values(&self) -> bool {
- match self {
- Self::Set => true,
- Self::Append => true,
- #[allow(deprecated)]
- Self::StoreValue => true,
- #[allow(deprecated)]
- Self::IncOccurrence => false,
- Self::SetTrue => false,
- Self::SetFalse => false,
- Self::Count => false,
- Self::Help => false,
- Self::Version => false,
- }
- }
-
- pub(crate) fn default_value(&self) -> Option<&'static std::ffi::OsStr> {
- match self {
- Self::Set => None,
- Self::Append => None,
- #[allow(deprecated)]
- Self::StoreValue => None,
- #[allow(deprecated)]
- Self::IncOccurrence => None,
- Self::SetTrue => Some(std::ffi::OsStr::new("false")),
- Self::SetFalse => Some(std::ffi::OsStr::new("true")),
- Self::Count => Some(std::ffi::OsStr::new("0")),
- Self::Help => None,
- Self::Version => None,
- }
- }
-
- pub(crate) fn default_value_parser(&self) -> Option<super::ValueParser> {
- match self {
- Self::Set => None,
- Self::Append => None,
- #[allow(deprecated)]
- Self::StoreValue => None,
- #[allow(deprecated)]
- Self::IncOccurrence => None,
- Self::SetTrue => Some(super::ValueParser::bool()),
- Self::SetFalse => Some(super::ValueParser::bool()),
- Self::Count => Some(crate::value_parser!(u8).into()),
- Self::Help => None,
- Self::Version => None,
- }
- }
-
- #[cfg(debug_assertions)]
- pub(crate) fn value_type_id(&self) -> Option<crate::parser::AnyValueId> {
- use crate::parser::AnyValueId;
-
- match self {
- Self::Set => None,
- Self::Append => None,
- #[allow(deprecated)]
- Self::StoreValue => None,
- #[allow(deprecated)]
- Self::IncOccurrence => None,
- Self::SetTrue => Some(AnyValueId::of::<bool>()),
- Self::SetFalse => Some(AnyValueId::of::<bool>()),
- Self::Count => Some(AnyValueId::of::<CountType>()),
- Self::Help => None,
- Self::Version => None,
- }
- }
-}
-
-pub(crate) type CountType = u8;
diff --git a/vendor/clap/src/builder/app_settings.rs b/vendor/clap/src/builder/app_settings.rs
deleted file mode 100644
index 88bc243c4..000000000
--- a/vendor/clap/src/builder/app_settings.rs
+++ /dev/null
@@ -1,864 +0,0 @@
-#![allow(deprecated)]
-
-// Std
-use std::ops::BitOr;
-#[cfg(feature = "yaml")]
-use std::str::FromStr;
-
-#[allow(unused)]
-use crate::Arg;
-#[allow(unused)]
-use crate::Command;
-
-// Third party
-use bitflags::bitflags;
-
-#[doc(hidden)]
-#[derive(Debug, Copy, Clone, PartialEq, Eq)]
-pub struct AppFlags(Flags);
-
-impl Default for AppFlags {
- fn default() -> Self {
- AppFlags(Flags::COLOR_AUTO)
- }
-}
-
-/// Application level settings, which affect how [`Command`] operates
-///
-/// **NOTE:** When these settings are used, they apply only to current command, and are *not*
-/// propagated down or up through child or parent subcommands
-///
-/// [`Command`]: crate::Command
-#[derive(Debug, PartialEq, Copy, Clone)]
-#[non_exhaustive]
-pub enum AppSettings {
- /// Deprecated, replaced with [`Command::ignore_errors`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.1.0", note = "Replaced with `Command::ignore_errors`")
- )]
- IgnoreErrors,
-
- /// Deprecated, replace
- /// ```rust,no_run
- /// let cmd = clap::Command::new("cmd")
- /// .global_setting(clap::AppSettings::WaitOnError)
- /// .arg(clap::arg!(--flag));
- /// let m = cmd.get_matches();
- /// ```
- /// with
- /// ```rust
- /// let cmd = clap::Command::new("cmd")
- /// .arg(clap::arg!(--flag));
- /// let m = match cmd.try_get_matches() {
- /// Ok(m) => m,
- /// Err(err) => {
- /// if err.use_stderr() {
- /// let _ = err.print();
- ///
- /// eprintln!("\nPress [ENTER] / [RETURN] to continue...");
- /// use std::io::BufRead;
- /// let mut s = String::new();
- /// let i = std::io::stdin();
- /// i.lock().read_line(&mut s).unwrap();
- ///
- /// std::process::exit(2);
- /// } else {
- /// let _ = err.print();
- /// std::process::exit(0);
- /// }
- /// }
- /// };
- /// ```
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.1.0",
- note = "See documentation for how to hand-implement this"
- )
- )]
- WaitOnError,
-
- /// Deprecated, replaced with [`Command::allow_hyphen_values`] and
- /// [`Arg::is_allow_hyphen_values_set`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.1.0",
- note = "Replaced with `Command::allow_hyphen_values` and `Arg::is_allow_hyphen_values_set`"
- )
- )]
- AllowHyphenValues,
-
- /// Deprecated, replaced with [`Command::allow_negative_numbers`] and
- /// [`Command::is_allow_negative_numbers_set`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.1.0",
- note = "Replaced with `Command::allow_negative_numbers` and `Command::is_allow_negative_numbers_set`"
- )
- )]
- AllowNegativeNumbers,
-
- /// Deprecated, replaced with [`Command::args_override_self`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.1.0", note = "Replaced with `Command::args_override_self`")
- )]
- AllArgsOverrideSelf,
-
- /// Deprecated, replaced with [`Command::allow_missing_positional`] and
- /// [`Command::is_allow_missing_positional_set`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.1.0",
- note = "Replaced with `Command::allow_missing_positional` and `Command::is_allow_missing_positional_set`"
- )
- )]
- AllowMissingPositional,
-
- /// Deprecated, replaced with [`Command::trailing_var_arg`] and [`Command::is_trailing_var_arg_set`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.1.0",
- note = "Replaced with `Command::trailing_var_arg` and `Command::is_trailing_var_arg_set`"
- )
- )]
- TrailingVarArg,
-
- /// Deprecated, replaced with [`Command::dont_delimit_trailing_values`] and
- /// [`Command::is_dont_delimit_trailing_values_set`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.1.0",
- note = "Replaced with `Command::dont_delimit_trailing_values` and `Command::is_dont_delimit_trailing_values_set`"
- )
- )]
- DontDelimitTrailingValues,
-
- /// Deprecated, replaced with [`Command::infer_long_args`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.1.0", note = "Replaced with `Command::infer_long_args`")
- )]
- InferLongArgs,
-
- /// Deprecated, replaced with [`Command::infer_subcommands`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.1.0", note = "Replaced with `Command::infer_subcommands`")
- )]
- InferSubcommands,
-
- /// Deprecated, replaced with [`Command::subcommand_required`] and
- /// [`Command::is_subcommand_required_set`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.1.0",
- note = "Replaced with `Command::subcommand_required` and `Command::is_subcommand_required_set`"
- )
- )]
- SubcommandRequired,
-
- /// Deprecated, replaced with [`Command::subcommand_required`] combined with
- /// [`Command::arg_required_else_help`].
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.1.0",
- note = "Replaced with `Command::subcommand_required` combined with `Command::arg_required_else_help`"
- )
- )]
- SubcommandRequiredElseHelp,
-
- /// Deprecated, replaced with [`Command::allow_external_subcommands`] and
- /// [`Command::is_allow_external_subcommands_set`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.1.0",
- note = "Replaced with `Command::allow_external_subcommands` and `Command::is_allow_external_subcommands_set`"
- )
- )]
- AllowExternalSubcommands,
-
- /// Deprecated, replaced with [`Command::multicall`] and [`Command::is_multicall_set`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.1.0",
- note = "Replaced with `Command::multicall` and `Command::is_multicall_set`"
- )
- )]
- Multicall,
-
- /// Deprecated, replaced with [`Command::allow_invalid_utf8_for_external_subcommands`] and [`Command::is_allow_invalid_utf8_for_external_subcommands_set`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.1.0",
- note = "Replaced with `Command::allow_invalid_utf8_for_external_subcommands` and `Command::is_allow_invalid_utf8_for_external_subcommands_set`"
- )
- )]
- AllowInvalidUtf8ForExternalSubcommands,
-
- /// Deprecated, this is now the default
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.1.0", note = "This is now the default")
- )]
- UseLongFormatForHelpSubcommand,
-
- /// Deprecated, replaced with [`Command::subcommand_negates_reqs`] and
- /// [`Command::is_subcommand_negates_reqs_set`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.1.0",
- note = "Replaced with `Command::subcommand_negates_reqs` and `Command::is_subcommand_negates_reqs_set`"
- )
- )]
- SubcommandsNegateReqs,
-
- /// Deprecated, replaced with [`Command::args_conflicts_with_subcommands`] and
- /// [`Command::is_args_conflicts_with_subcommands_set`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.1.0",
- note = "Replaced with `Command::args_conflicts_with_subcommands` and `Command::is_args_conflicts_with_subcommands_set`"
- )
- )]
- ArgsNegateSubcommands,
-
- /// Deprecated, replaced with [`Command::subcommand_precedence_over_arg`] and
- /// [`Command::is_subcommand_precedence_over_arg_set`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.1.0",
- note = "Replaced with `Command::subcommand_precedence_over_arg` and `Command::is_subcommand_precedence_over_arg_set`"
- )
- )]
- SubcommandPrecedenceOverArg,
-
- /// Deprecated, replaced with [`Command::arg_required_else_help`] and
- /// [`Command::is_arg_required_else_help_set`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.1.0",
- note = "Replaced with `Command::arg_required_else_help` and `Command::is_arg_required_else_help_set`"
- )
- )]
- ArgRequiredElseHelp,
-
- /// Displays the arguments and [`subcommands`] in the help message in the order that they were
- /// declared in, and not alphabetically which is the default.
- ///
- /// To override the declaration order, see [`Arg::display_order`] and [`Command::display_order`].
- ///
- /// # Examples
- ///
- /// ```no_run
- /// # use clap::{Command, Arg, AppSettings};
- /// Command::new("myprog")
- /// .global_setting(AppSettings::DeriveDisplayOrder)
- /// .get_matches();
- /// ```
- ///
- /// [`subcommands`]: crate::Command::subcommand()
- /// [`Arg::display_order`]: crate::Arg::display_order
- /// [`Command::display_order`]: crate::Command::display_order
- DeriveDisplayOrder,
-
- /// Deprecated, replaced with [`Command::dont_collapse_args_in_usage`] and
- /// [`Command::is_dont_collapse_args_in_usage_set`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.1.0",
- note = "Replaced with `Command::dont_collapse_args_in_usage` and `Command::is_dont_collapse_args_in_usage_set`"
- )
- )]
- DontCollapseArgsInUsage,
-
- /// Deprecated, replaced with [`Command::next_line_help`] and [`Command::is_next_line_help_set`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.1.0",
- note = "Replaced with `Command::next_line_help` and `Command::is_next_line_help_set`"
- )
- )]
- NextLineHelp,
-
- /// Deprecated, replaced with [`Command::disable_colored_help`] and
- /// [`Command::is_disable_colored_help_set`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.1.0",
- note = "Replaced with `Command::disable_colored_help` and `Command::is_disable_colored_help_set`"
- )
- )]
- DisableColoredHelp,
-
- /// Deprecated, replaced with [`Command::disable_help_flag`] and [`Command::is_disable_help_flag_set`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.1.0",
- note = "Replaced with `Command::disable_help_flag` and `Command::is_disable_help_flag_set`"
- )
- )]
- DisableHelpFlag,
-
- /// Deprecated, replaced with [`Command::disable_help_subcommand`] and
- /// [`Command::is_disable_help_subcommand_set`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.1.0",
- note = "Replaced with `Command::disable_help_subcommand` and `Command::is_disable_help_subcommand_set`"
- )
- )]
- DisableHelpSubcommand,
-
- /// Deprecated, replaced with [`Command::disable_version_flag`] and
- /// [`Command::is_disable_version_flag_set`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.1.0",
- note = "Replaced with `Command::disable_version_flag` and `Command::is_disable_version_flag_set`"
- )
- )]
- DisableVersionFlag,
-
- /// Deprecated, replaced with [`Command::propagate_version`] and [`Command::is_propagate_version_set`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.1.0",
- note = "Replaced with `Command::propagate_version` and `Command::is_propagate_version_set`"
- )
- )]
- PropagateVersion,
-
- /// Deprecated, replaced with [`Command::hide`] and [`Command::is_hide_set`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.1.0",
- note = "Replaced with `Command::hide` and `Command::is_hide_set`"
- )
- )]
- Hidden,
-
- /// Deprecated, replaced with [`Command::hide_possible_values`] and
- /// [`Arg::is_hide_possible_values_set`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.1.0",
- note = "Replaced with `Command::hide_possible_values` and `Arg::is_hide_possible_values_set`"
- )
- )]
- HidePossibleValues,
-
- /// Deprecated, replaced with [`Command::help_expected`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.1.0", note = "Replaced with `Command::help_expected`")
- )]
- HelpExpected,
-
- /// Deprecated, replaced with [`Command::no_binary_name`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.1.0", note = "Replaced with `Command::no_binary_name`")
- )]
- NoBinaryName,
-
- /// Deprecated, replaced with [`Arg::action`][super::Arg::action]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.2.0", note = "Replaced with `Arg::action`")
- )]
- NoAutoHelp,
-
- /// Deprecated, replaced with [`Arg::action`][super::Arg::action]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.2.0", note = "Replaced with `Arg::action`")
- )]
- NoAutoVersion,
-
- /// Deprecated, replaced with [`Command::allow_hyphen_values`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.0.0", note = "Replaced with `Command::allow_hyphen_values`")
- )]
- #[doc(hidden)]
- AllowLeadingHyphen,
-
- /// Deprecated, replaced with [`Command::allow_invalid_utf8_for_external_subcommands`] and [`Command::is_allow_invalid_utf8_for_external_subcommands_set`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.0.0",
- note = "Replaced with `Command::allow_invalid_utf8_for_external_subcommands` and `Command::is_allow_invalid_utf8_for_external_subcommands_set`"
- )
- )]
- #[doc(hidden)]
- StrictUtf8,
-
- /// Deprecated, this is now the default
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.0.0", note = "This is now the default")
- )]
- #[doc(hidden)]
- UnifiedHelpMessage,
-
- /// Deprecated, this is now the default
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.0.0", note = "This is now the default")
- )]
- #[doc(hidden)]
- ColoredHelp,
-
- /// Deprecated, see [`Command::color`][crate::Command::color]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.0.0", note = "Replaced with `Command::color`")
- )]
- #[doc(hidden)]
- ColorAuto,
-
- /// Deprecated, replaced with [`Command::color`][crate::Command::color]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.0.0", note = "Replaced with `Command::color`")
- )]
- #[doc(hidden)]
- ColorAlways,
-
- /// Deprecated, replaced with [`Command::color`][crate::Command::color]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.0.0", note = "Replaced with `Command::color`")
- )]
- #[doc(hidden)]
- ColorNever,
-
- /// Deprecated, replaced with [`Command::disable_help_flag`] and [`Command::is_disable_help_flag_set`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.0.0",
- note = "Replaced with `Command::disable_help_flag` and `Command::is_disable_help_flag_set`"
- )
- )]
- #[doc(hidden)]
- DisableHelpFlags,
-
- /// Deprecated, replaced with [`Command::disable_version_flag`] and
- /// [`Command::is_disable_version_flag_set`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.0.0",
- note = "Replaced with `Command::disable_version_flag` and `Command::is_disable_version_flag_set`"
- )
- )]
- #[doc(hidden)]
- DisableVersion,
-
- /// Deprecated, replaced with [`Command::propagate_version`] and [`Command::is_propagate_version_set`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.0.0",
- note = "Replaced with `Command::propagate_version` and `Command::is_propagate_version_set`"
- )
- )]
- #[doc(hidden)]
- GlobalVersion,
-
- /// Deprecated, replaced with [`Command::hide_possible_values`] and
- /// [`Arg::is_hide_possible_values_set`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.0.0",
- note = "Replaced with `Command::hide_possible_values` and `Arg::is_hide_possible_values_set`"
- )
- )]
- #[doc(hidden)]
- HidePossibleValuesInHelp,
-
- /// Deprecated, this is now the default
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.0.0", note = "This is now the default")
- )]
- #[doc(hidden)]
- UnifiedHelp,
-
- /// If the cmd is already built, used for caching.
- #[doc(hidden)]
- Built,
-
- /// If the cmd's bin name is already built, used for caching.
- #[doc(hidden)]
- BinNameBuilt,
-}
-
-bitflags! {
- struct Flags: u64 {
- const SC_NEGATE_REQS = 1;
- const SC_REQUIRED = 1 << 1;
- const ARG_REQUIRED_ELSE_HELP = 1 << 2;
- const PROPAGATE_VERSION = 1 << 3;
- const DISABLE_VERSION_FOR_SC = 1 << 4;
- const WAIT_ON_ERROR = 1 << 6;
- const SC_REQUIRED_ELSE_HELP = 1 << 7;
- const NO_AUTO_HELP = 1 << 8;
- const NO_AUTO_VERSION = 1 << 9;
- const DISABLE_VERSION_FLAG = 1 << 10;
- const HIDDEN = 1 << 11;
- const TRAILING_VARARG = 1 << 12;
- const NO_BIN_NAME = 1 << 13;
- const ALLOW_UNK_SC = 1 << 14;
- const SC_UTF8_NONE = 1 << 15;
- const LEADING_HYPHEN = 1 << 16;
- const NO_POS_VALUES = 1 << 17;
- const NEXT_LINE_HELP = 1 << 18;
- const DERIVE_DISP_ORDER = 1 << 19;
- const DISABLE_COLORED_HELP = 1 << 20;
- const COLOR_ALWAYS = 1 << 21;
- const COLOR_AUTO = 1 << 22;
- const COLOR_NEVER = 1 << 23;
- const DONT_DELIM_TRAIL = 1 << 24;
- const ALLOW_NEG_NUMS = 1 << 25;
- const DISABLE_HELP_SC = 1 << 27;
- const DONT_COLLAPSE_ARGS = 1 << 28;
- const ARGS_NEGATE_SCS = 1 << 29;
- const PROPAGATE_VALS_DOWN = 1 << 30;
- const ALLOW_MISSING_POS = 1 << 31;
- const TRAILING_VALUES = 1 << 32;
- const BUILT = 1 << 33;
- const BIN_NAME_BUILT = 1 << 34;
- const VALID_ARG_FOUND = 1 << 35;
- const INFER_SUBCOMMANDS = 1 << 36;
- const CONTAINS_LAST = 1 << 37;
- const ARGS_OVERRIDE_SELF = 1 << 38;
- const HELP_REQUIRED = 1 << 39;
- const SUBCOMMAND_PRECEDENCE_OVER_ARG = 1 << 40;
- const DISABLE_HELP_FLAG = 1 << 41;
- const USE_LONG_FORMAT_FOR_HELP_SC = 1 << 42;
- const INFER_LONG_ARGS = 1 << 43;
- const IGNORE_ERRORS = 1 << 44;
- const MULTICALL = 1 << 45;
- const NO_OP = 0;
- }
-}
-
-impl_settings! { AppSettings, AppFlags,
- ArgRequiredElseHelp
- => Flags::ARG_REQUIRED_ELSE_HELP,
- SubcommandPrecedenceOverArg
- => Flags::SUBCOMMAND_PRECEDENCE_OVER_ARG,
- ArgsNegateSubcommands
- => Flags::ARGS_NEGATE_SCS,
- AllowExternalSubcommands
- => Flags::ALLOW_UNK_SC,
- StrictUtf8
- => Flags::NO_OP,
- AllowInvalidUtf8ForExternalSubcommands
- => Flags::SC_UTF8_NONE,
- AllowHyphenValues
- => Flags::LEADING_HYPHEN,
- AllowLeadingHyphen
- => Flags::LEADING_HYPHEN,
- AllowNegativeNumbers
- => Flags::ALLOW_NEG_NUMS,
- AllowMissingPositional
- => Flags::ALLOW_MISSING_POS,
- UnifiedHelpMessage
- => Flags::NO_OP,
- ColoredHelp
- => Flags::NO_OP,
- ColorAlways
- => Flags::COLOR_ALWAYS,
- ColorAuto
- => Flags::COLOR_AUTO,
- ColorNever
- => Flags::COLOR_NEVER,
- DontDelimitTrailingValues
- => Flags::DONT_DELIM_TRAIL,
- DontCollapseArgsInUsage
- => Flags::DONT_COLLAPSE_ARGS,
- DeriveDisplayOrder
- => Flags::DERIVE_DISP_ORDER,
- DisableColoredHelp
- => Flags::DISABLE_COLORED_HELP,
- DisableHelpSubcommand
- => Flags::DISABLE_HELP_SC,
- DisableHelpFlag
- => Flags::DISABLE_HELP_FLAG,
- DisableHelpFlags
- => Flags::DISABLE_HELP_FLAG,
- DisableVersionFlag
- => Flags::DISABLE_VERSION_FLAG,
- DisableVersion
- => Flags::DISABLE_VERSION_FLAG,
- PropagateVersion
- => Flags::PROPAGATE_VERSION,
- GlobalVersion
- => Flags::PROPAGATE_VERSION,
- HidePossibleValues
- => Flags::NO_POS_VALUES,
- HidePossibleValuesInHelp
- => Flags::NO_POS_VALUES,
- HelpExpected
- => Flags::HELP_REQUIRED,
- Hidden
- => Flags::HIDDEN,
- Multicall
- => Flags::MULTICALL,
- NoAutoHelp
- => Flags::NO_AUTO_HELP,
- NoAutoVersion
- => Flags::NO_AUTO_VERSION,
- NoBinaryName
- => Flags::NO_BIN_NAME,
- SubcommandsNegateReqs
- => Flags::SC_NEGATE_REQS,
- SubcommandRequired
- => Flags::SC_REQUIRED,
- SubcommandRequiredElseHelp
- => Flags::SC_REQUIRED_ELSE_HELP,
- UseLongFormatForHelpSubcommand
- => Flags::USE_LONG_FORMAT_FOR_HELP_SC,
- TrailingVarArg
- => Flags::TRAILING_VARARG,
- UnifiedHelp => Flags::NO_OP,
- NextLineHelp
- => Flags::NEXT_LINE_HELP,
- IgnoreErrors
- => Flags::IGNORE_ERRORS,
- WaitOnError
- => Flags::WAIT_ON_ERROR,
- Built
- => Flags::BUILT,
- BinNameBuilt
- => Flags::BIN_NAME_BUILT,
- InferSubcommands
- => Flags::INFER_SUBCOMMANDS,
- AllArgsOverrideSelf
- => Flags::ARGS_OVERRIDE_SELF,
- InferLongArgs
- => Flags::INFER_LONG_ARGS
-}
-
-/// Deprecated in [Issue #3087](https://github.com/clap-rs/clap/issues/3087), maybe [`clap::Parser`][crate::Parser] would fit your use case?
-#[cfg(feature = "yaml")]
-impl FromStr for AppSettings {
- type Err = String;
- fn from_str(s: &str) -> Result<Self, <Self as FromStr>::Err> {
- #[allow(deprecated)]
- #[allow(unreachable_patterns)]
- match &*s.to_ascii_lowercase() {
- "argrequiredelsehelp" => Ok(AppSettings::ArgRequiredElseHelp),
- "subcommandprecedenceoverarg" => Ok(AppSettings::SubcommandPrecedenceOverArg),
- "argsnegatesubcommands" => Ok(AppSettings::ArgsNegateSubcommands),
- "allowexternalsubcommands" => Ok(AppSettings::AllowExternalSubcommands),
- "strictutf8" => Ok(AppSettings::StrictUtf8),
- "allowinvalidutf8forexternalsubcommands" => {
- Ok(AppSettings::AllowInvalidUtf8ForExternalSubcommands)
- }
- "allowhyphenvalues" => Ok(AppSettings::AllowHyphenValues),
- "allowleadinghyphen" => Ok(AppSettings::AllowLeadingHyphen),
- "allownegativenumbers" => Ok(AppSettings::AllowNegativeNumbers),
- "allowmissingpositional" => Ok(AppSettings::AllowMissingPositional),
- "unifiedhelpmessage" => Ok(AppSettings::UnifiedHelpMessage),
- "coloredhelp" => Ok(AppSettings::ColoredHelp),
- "coloralways" => Ok(AppSettings::ColorAlways),
- "colorauto" => Ok(AppSettings::ColorAuto),
- "colornever" => Ok(AppSettings::ColorNever),
- "dontdelimittrailingvalues" => Ok(AppSettings::DontDelimitTrailingValues),
- "dontcollapseargsinusage" => Ok(AppSettings::DontCollapseArgsInUsage),
- "derivedisplayorder" => Ok(AppSettings::DeriveDisplayOrder),
- "disablecoloredhelp" => Ok(AppSettings::DisableColoredHelp),
- "disablehelpsubcommand" => Ok(AppSettings::DisableHelpSubcommand),
- "disablehelpflag" => Ok(AppSettings::DisableHelpFlag),
- "disablehelpflags" => Ok(AppSettings::DisableHelpFlags),
- "disableversionflag" => Ok(AppSettings::DisableVersionFlag),
- "disableversion" => Ok(AppSettings::DisableVersion),
- "propagateversion" => Ok(AppSettings::PropagateVersion),
- "propagateversion" => Ok(AppSettings::GlobalVersion),
- "hidepossiblevalues" => Ok(AppSettings::HidePossibleValues),
- "hidepossiblevaluesinhelp" => Ok(AppSettings::HidePossibleValuesInHelp),
- "helpexpected" => Ok(AppSettings::HelpExpected),
- "hidden" => Ok(AppSettings::Hidden),
- "noautohelp" => Ok(AppSettings::NoAutoHelp),
- "noautoversion" => Ok(AppSettings::NoAutoVersion),
- "nobinaryname" => Ok(AppSettings::NoBinaryName),
- "subcommandsnegatereqs" => Ok(AppSettings::SubcommandsNegateReqs),
- "subcommandrequired" => Ok(AppSettings::SubcommandRequired),
- "subcommandrequiredelsehelp" => Ok(AppSettings::SubcommandRequiredElseHelp),
- "uselongformatforhelpsubcommand" => Ok(AppSettings::UseLongFormatForHelpSubcommand),
- "trailingvararg" => Ok(AppSettings::TrailingVarArg),
- "unifiedhelp" => Ok(AppSettings::UnifiedHelp),
- "nextlinehelp" => Ok(AppSettings::NextLineHelp),
- "ignoreerrors" => Ok(AppSettings::IgnoreErrors),
- "waitonerror" => Ok(AppSettings::WaitOnError),
- "built" => Ok(AppSettings::Built),
- "binnamebuilt" => Ok(AppSettings::BinNameBuilt),
- "infersubcommands" => Ok(AppSettings::InferSubcommands),
- "allargsoverrideself" => Ok(AppSettings::AllArgsOverrideSelf),
- "inferlongargs" => Ok(AppSettings::InferLongArgs),
- _ => Err(format!("unknown AppSetting: `{}`", s)),
- }
- }
-}
-
-#[cfg(test)]
-mod test {
- #[allow(clippy::cognitive_complexity)]
- #[test]
- #[cfg(feature = "yaml")]
- fn app_settings_fromstr() {
- use super::AppSettings;
-
- assert_eq!(
- "disablehelpflag".parse::<AppSettings>().unwrap(),
- AppSettings::DisableHelpFlag
- );
- assert_eq!(
- "argsnegatesubcommands".parse::<AppSettings>().unwrap(),
- AppSettings::ArgsNegateSubcommands
- );
- assert_eq!(
- "argrequiredelsehelp".parse::<AppSettings>().unwrap(),
- AppSettings::ArgRequiredElseHelp
- );
- assert_eq!(
- "subcommandprecedenceoverarg"
- .parse::<AppSettings>()
- .unwrap(),
- AppSettings::SubcommandPrecedenceOverArg
- );
- assert_eq!(
- "allowexternalsubcommands".parse::<AppSettings>().unwrap(),
- AppSettings::AllowExternalSubcommands
- );
- assert_eq!(
- "allowinvalidutf8forexternalsubcommands"
- .parse::<AppSettings>()
- .unwrap(),
- AppSettings::AllowInvalidUtf8ForExternalSubcommands
- );
- assert_eq!(
- "allowhyphenvalues".parse::<AppSettings>().unwrap(),
- AppSettings::AllowHyphenValues
- );
- assert_eq!(
- "allownegativenumbers".parse::<AppSettings>().unwrap(),
- AppSettings::AllowNegativeNumbers
- );
- assert_eq!(
- "disablehelpsubcommand".parse::<AppSettings>().unwrap(),
- AppSettings::DisableHelpSubcommand
- );
- assert_eq!(
- "disableversionflag".parse::<AppSettings>().unwrap(),
- AppSettings::DisableVersionFlag
- );
- assert_eq!(
- "dontcollapseargsinusage".parse::<AppSettings>().unwrap(),
- AppSettings::DontCollapseArgsInUsage
- );
- assert_eq!(
- "dontdelimittrailingvalues".parse::<AppSettings>().unwrap(),
- AppSettings::DontDelimitTrailingValues
- );
- assert_eq!(
- "derivedisplayorder".parse::<AppSettings>().unwrap(),
- AppSettings::DeriveDisplayOrder
- );
- assert_eq!(
- "disablecoloredhelp".parse::<AppSettings>().unwrap(),
- AppSettings::DisableColoredHelp
- );
- assert_eq!(
- "propagateversion".parse::<AppSettings>().unwrap(),
- AppSettings::PropagateVersion
- );
- assert_eq!(
- "hidden".parse::<AppSettings>().unwrap(),
- AppSettings::Hidden
- );
- assert_eq!(
- "hidepossiblevalues".parse::<AppSettings>().unwrap(),
- AppSettings::HidePossibleValues
- );
- assert_eq!(
- "helpexpected".parse::<AppSettings>().unwrap(),
- AppSettings::HelpExpected
- );
- assert_eq!(
- "nobinaryname".parse::<AppSettings>().unwrap(),
- AppSettings::NoBinaryName
- );
- assert_eq!(
- "nextlinehelp".parse::<AppSettings>().unwrap(),
- AppSettings::NextLineHelp
- );
- assert_eq!(
- "subcommandsnegatereqs".parse::<AppSettings>().unwrap(),
- AppSettings::SubcommandsNegateReqs
- );
- assert_eq!(
- "subcommandrequired".parse::<AppSettings>().unwrap(),
- AppSettings::SubcommandRequired
- );
- assert_eq!(
- "subcommandrequiredelsehelp".parse::<AppSettings>().unwrap(),
- AppSettings::SubcommandRequiredElseHelp
- );
- assert_eq!(
- "uselongformatforhelpsubcommand"
- .parse::<AppSettings>()
- .unwrap(),
- AppSettings::UseLongFormatForHelpSubcommand
- );
- assert_eq!(
- "trailingvararg".parse::<AppSettings>().unwrap(),
- AppSettings::TrailingVarArg
- );
- assert_eq!(
- "waitonerror".parse::<AppSettings>().unwrap(),
- AppSettings::WaitOnError
- );
- assert_eq!("built".parse::<AppSettings>().unwrap(), AppSettings::Built);
- assert_eq!(
- "binnamebuilt".parse::<AppSettings>().unwrap(),
- AppSettings::BinNameBuilt
- );
- assert_eq!(
- "infersubcommands".parse::<AppSettings>().unwrap(),
- AppSettings::InferSubcommands
- );
- assert!("hahahaha".parse::<AppSettings>().is_err());
- }
-}
diff --git a/vendor/clap/src/builder/arg.rs b/vendor/clap/src/builder/arg.rs
deleted file mode 100644
index e9403d0b7..000000000
--- a/vendor/clap/src/builder/arg.rs
+++ /dev/null
@@ -1,5494 +0,0 @@
-#![allow(deprecated)]
-
-// Std
-use std::{
- borrow::Cow,
- cmp::{Ord, Ordering},
- error::Error,
- ffi::OsStr,
- fmt::{self, Display, Formatter},
- str,
- sync::{Arc, Mutex},
-};
-#[cfg(feature = "env")]
-use std::{env, ffi::OsString};
-
-#[cfg(feature = "yaml")]
-use yaml_rust::Yaml;
-
-// Internal
-use crate::builder::usage_parser::UsageParser;
-use crate::builder::ArgPredicate;
-use crate::util::{Id, Key};
-use crate::ArgAction;
-use crate::PossibleValue;
-use crate::ValueHint;
-use crate::INTERNAL_ERROR_MSG;
-use crate::{ArgFlags, ArgSettings};
-
-#[cfg(feature = "regex")]
-use crate::builder::RegexRef;
-
-/// The abstract representation of a command line argument. Used to set all the options and
-/// relationships that define a valid argument for the program.
-///
-/// There are two methods for constructing [`Arg`]s, using the builder pattern and setting options
-/// manually, or using a usage string which is far less verbose but has fewer options. You can also
-/// use a combination of the two methods to achieve the best of both worlds.
-///
-/// - [Basic API][crate::Arg#basic-api]
-/// - [Value Handling][crate::Arg#value-handling]
-/// - [Help][crate::Arg#help-1]
-/// - [Advanced Argument Relations][crate::Arg#advanced-argument-relations]
-/// - [Reflection][crate::Arg#reflection]
-///
-/// # Examples
-///
-/// ```rust
-/// # use clap::{Arg, arg};
-/// // Using the traditional builder pattern and setting each option manually
-/// let cfg = Arg::new("config")
-/// .short('c')
-/// .long("config")
-/// .takes_value(true)
-/// .value_name("FILE")
-/// .help("Provides a config file to myprog");
-/// // Using a usage string (setting a similar argument to the one above)
-/// let input = arg!(-i --input <FILE> "Provides an input file to the program");
-/// ```
-#[allow(missing_debug_implementations)]
-#[derive(Default, Clone)]
-pub struct Arg<'help> {
- pub(crate) id: Id,
- pub(crate) provider: ArgProvider,
- pub(crate) name: &'help str,
- pub(crate) help: Option<&'help str>,
- pub(crate) long_help: Option<&'help str>,
- pub(crate) action: Option<ArgAction>,
- pub(crate) value_parser: Option<super::ValueParser>,
- pub(crate) blacklist: Vec<Id>,
- pub(crate) settings: ArgFlags,
- pub(crate) overrides: Vec<Id>,
- pub(crate) groups: Vec<Id>,
- pub(crate) requires: Vec<(ArgPredicate<'help>, Id)>,
- pub(crate) r_ifs: Vec<(Id, &'help str)>,
- pub(crate) r_ifs_all: Vec<(Id, &'help str)>,
- pub(crate) r_unless: Vec<Id>,
- pub(crate) r_unless_all: Vec<Id>,
- pub(crate) short: Option<char>,
- pub(crate) long: Option<&'help str>,
- pub(crate) aliases: Vec<(&'help str, bool)>, // (name, visible)
- pub(crate) short_aliases: Vec<(char, bool)>, // (name, visible)
- pub(crate) disp_ord: DisplayOrder,
- pub(crate) possible_vals: Vec<PossibleValue<'help>>,
- pub(crate) val_names: Vec<&'help str>,
- pub(crate) num_vals: Option<usize>,
- pub(crate) max_occurs: Option<usize>,
- pub(crate) max_vals: Option<usize>,
- pub(crate) min_vals: Option<usize>,
- pub(crate) validator: Option<Arc<Mutex<Validator<'help>>>>,
- pub(crate) validator_os: Option<Arc<Mutex<ValidatorOs<'help>>>>,
- pub(crate) val_delim: Option<char>,
- pub(crate) default_vals: Vec<&'help OsStr>,
- pub(crate) default_vals_ifs: Vec<(Id, ArgPredicate<'help>, Option<&'help OsStr>)>,
- pub(crate) default_missing_vals: Vec<&'help OsStr>,
- #[cfg(feature = "env")]
- pub(crate) env: Option<(&'help OsStr, Option<OsString>)>,
- pub(crate) terminator: Option<&'help str>,
- pub(crate) index: Option<usize>,
- pub(crate) help_heading: Option<Option<&'help str>>,
- pub(crate) value_hint: Option<ValueHint>,
-}
-
-/// # Basic API
-impl<'help> Arg<'help> {
- /// Create a new [`Arg`] with a unique name.
- ///
- /// The name is used to check whether or not the argument was used at
- /// runtime, get values, set relationships with other args, etc..
- ///
- /// **NOTE:** In the case of arguments that take values (i.e. [`Arg::takes_value(true)`])
- /// and positional arguments (i.e. those without a preceding `-` or `--`) the name will also
- /// be displayed when the user prints the usage/help information of the program.
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// Arg::new("config")
- /// # ;
- /// ```
- /// [`Arg::takes_value(true)`]: Arg::takes_value()
- pub fn new<S: Into<&'help str>>(n: S) -> Self {
- Arg::default().name(n)
- }
-
- /// Set the identifier used for referencing this argument in the clap API.
- ///
- /// See [`Arg::new`] for more details.
- #[must_use]
- pub fn id<S: Into<&'help str>>(mut self, n: S) -> Self {
- let name = n.into();
- self.id = Id::from(&*name);
- self.name = name;
- self
- }
-
- /// Deprecated, replaced with [`Arg::id`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.1.0", note = "Replaced with `Arg::id`")
- )]
- pub fn name<S: Into<&'help str>>(self, n: S) -> Self {
- self.id(n)
- }
-
- /// Sets the short version of the argument without the preceding `-`.
- ///
- /// By default `V` and `h` are used by the auto-generated `version` and `help` arguments,
- /// respectively. You may use the uppercase `V` or lowercase `h` for your own arguments, in
- /// which case `clap` simply will not assign those to the auto-generated
- /// `version` or `help` arguments.
- ///
- /// # Examples
- ///
- /// When calling `short`, use a single valid UTF-8 character which will allow using the
- /// argument via a single hyphen (`-`) such as `-c`:
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// let m = Command::new("prog")
- /// .arg(Arg::new("config")
- /// .short('c')
- /// .takes_value(true))
- /// .get_matches_from(vec![
- /// "prog", "-c", "file.toml"
- /// ]);
- ///
- /// assert_eq!(m.get_one::<String>("config").map(String::as_str), Some("file.toml"));
- /// ```
- #[inline]
- #[must_use]
- pub fn short(mut self, s: char) -> Self {
- assert!(s != '-', "short option name cannot be `-`");
-
- self.short = Some(s);
- self
- }
-
- /// Sets the long version of the argument without the preceding `--`.
- ///
- /// By default `version` and `help` are used by the auto-generated `version` and `help`
- /// arguments, respectively. You may use the word `version` or `help` for the long form of your
- /// own arguments, in which case `clap` simply will not assign those to the auto-generated
- /// `version` or `help` arguments.
- ///
- /// **NOTE:** Any leading `-` characters will be stripped
- ///
- /// # Examples
- ///
- /// To set `long` use a word containing valid UTF-8. If you supply a double leading
- /// `--` such as `--config` they will be stripped. Hyphens in the middle of the word, however,
- /// will *not* be stripped (i.e. `config-file` is allowed).
- ///
- /// Setting `long` allows using the argument via a double hyphen (`--`) such as `--config`
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// let m = Command::new("prog")
- /// .arg(Arg::new("cfg")
- /// .long("config")
- /// .takes_value(true))
- /// .get_matches_from(vec![
- /// "prog", "--config", "file.toml"
- /// ]);
- ///
- /// assert_eq!(m.get_one::<String>("cfg").map(String::as_str), Some("file.toml"));
- /// ```
- #[inline]
- #[must_use]
- pub fn long(mut self, l: &'help str) -> Self {
- #[cfg(feature = "unstable-v4")]
- {
- self.long = Some(l);
- }
- #[cfg(not(feature = "unstable-v4"))]
- {
- self.long = Some(l.trim_start_matches(|c| c == '-'));
- }
- self
- }
-
- /// Add an alias, which functions as a hidden long flag.
- ///
- /// This is more efficient, and easier than creating multiple hidden arguments as one only
- /// needs to check for the existence of this command, and not all variants.
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// let m = Command::new("prog")
- /// .arg(Arg::new("test")
- /// .long("test")
- /// .alias("alias")
- /// .takes_value(true))
- /// .get_matches_from(vec![
- /// "prog", "--alias", "cool"
- /// ]);
- /// assert!(m.contains_id("test"));
- /// assert_eq!(m.value_of("test"), Some("cool"));
- /// ```
- #[must_use]
- pub fn alias<S: Into<&'help str>>(mut self, name: S) -> Self {
- self.aliases.push((name.into(), false));
- self
- }
-
- /// Add an alias, which functions as a hidden short flag.
- ///
- /// This is more efficient, and easier than creating multiple hidden arguments as one only
- /// needs to check for the existence of this command, and not all variants.
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// let m = Command::new("prog")
- /// .arg(Arg::new("test")
- /// .short('t')
- /// .short_alias('e')
- /// .takes_value(true))
- /// .get_matches_from(vec![
- /// "prog", "-e", "cool"
- /// ]);
- /// assert!(m.contains_id("test"));
- /// assert_eq!(m.value_of("test"), Some("cool"));
- /// ```
- #[must_use]
- pub fn short_alias(mut self, name: char) -> Self {
- assert!(name != '-', "short alias name cannot be `-`");
-
- self.short_aliases.push((name, false));
- self
- }
-
- /// Add aliases, which function as hidden long flags.
- ///
- /// This is more efficient, and easier than creating multiple hidden subcommands as one only
- /// needs to check for the existence of this command, and not all variants.
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Command, Arg, ArgAction};
- /// let m = Command::new("prog")
- /// .arg(Arg::new("test")
- /// .long("test")
- /// .aliases(&["do-stuff", "do-tests", "tests"])
- /// .action(ArgAction::SetTrue)
- /// .help("the file to add")
- /// .required(false))
- /// .get_matches_from(vec![
- /// "prog", "--do-tests"
- /// ]);
- /// assert_eq!(*m.get_one::<bool>("test").expect("defaulted by clap"), true);
- /// ```
- #[must_use]
- pub fn aliases(mut self, names: &[&'help str]) -> Self {
- self.aliases.extend(names.iter().map(|&x| (x, false)));
- self
- }
-
- /// Add aliases, which functions as a hidden short flag.
- ///
- /// This is more efficient, and easier than creating multiple hidden subcommands as one only
- /// needs to check for the existence of this command, and not all variants.
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Command, Arg, ArgAction};
- /// let m = Command::new("prog")
- /// .arg(Arg::new("test")
- /// .short('t')
- /// .short_aliases(&['e', 's'])
- /// .action(ArgAction::SetTrue)
- /// .help("the file to add")
- /// .required(false))
- /// .get_matches_from(vec![
- /// "prog", "-s"
- /// ]);
- /// assert_eq!(*m.get_one::<bool>("test").expect("defaulted by clap"), true);
- /// ```
- #[must_use]
- pub fn short_aliases(mut self, names: &[char]) -> Self {
- for s in names {
- assert!(s != &'-', "short alias name cannot be `-`");
- self.short_aliases.push((*s, false));
- }
- self
- }
-
- /// Add an alias, which functions as a visible long flag.
- ///
- /// Like [`Arg::alias`], except that they are visible inside the help message.
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// let m = Command::new("prog")
- /// .arg(Arg::new("test")
- /// .visible_alias("something-awesome")
- /// .long("test")
- /// .takes_value(true))
- /// .get_matches_from(vec![
- /// "prog", "--something-awesome", "coffee"
- /// ]);
- /// assert!(m.contains_id("test"));
- /// assert_eq!(m.value_of("test"), Some("coffee"));
- /// ```
- /// [`Command::alias`]: Arg::alias()
- #[must_use]
- pub fn visible_alias<S: Into<&'help str>>(mut self, name: S) -> Self {
- self.aliases.push((name.into(), true));
- self
- }
-
- /// Add an alias, which functions as a visible short flag.
- ///
- /// Like [`Arg::short_alias`], except that they are visible inside the help message.
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// let m = Command::new("prog")
- /// .arg(Arg::new("test")
- /// .long("test")
- /// .visible_short_alias('t')
- /// .takes_value(true))
- /// .get_matches_from(vec![
- /// "prog", "-t", "coffee"
- /// ]);
- /// assert!(m.contains_id("test"));
- /// assert_eq!(m.value_of("test"), Some("coffee"));
- /// ```
- #[must_use]
- pub fn visible_short_alias(mut self, name: char) -> Self {
- assert!(name != '-', "short alias name cannot be `-`");
-
- self.short_aliases.push((name, true));
- self
- }
-
- /// Add aliases, which function as visible long flags.
- ///
- /// Like [`Arg::aliases`], except that they are visible inside the help message.
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Command, Arg, ArgAction};
- /// let m = Command::new("prog")
- /// .arg(Arg::new("test")
- /// .long("test")
- /// .action(ArgAction::SetTrue)
- /// .visible_aliases(&["something", "awesome", "cool"]))
- /// .get_matches_from(vec![
- /// "prog", "--awesome"
- /// ]);
- /// assert_eq!(*m.get_one::<bool>("test").expect("defaulted by clap"), true);
- /// ```
- /// [`Command::aliases`]: Arg::aliases()
- #[must_use]
- pub fn visible_aliases(mut self, names: &[&'help str]) -> Self {
- self.aliases.extend(names.iter().map(|n| (*n, true)));
- self
- }
-
- /// Add aliases, which function as visible short flags.
- ///
- /// Like [`Arg::short_aliases`], except that they are visible inside the help message.
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Command, Arg, ArgAction};
- /// let m = Command::new("prog")
- /// .arg(Arg::new("test")
- /// .long("test")
- /// .action(ArgAction::SetTrue)
- /// .visible_short_aliases(&['t', 'e']))
- /// .get_matches_from(vec![
- /// "prog", "-t"
- /// ]);
- /// assert_eq!(*m.get_one::<bool>("test").expect("defaulted by clap"), true);
- /// ```
- #[must_use]
- pub fn visible_short_aliases(mut self, names: &[char]) -> Self {
- for n in names {
- assert!(n != &'-', "short alias name cannot be `-`");
- self.short_aliases.push((*n, true));
- }
- self
- }
-
- /// Specifies the index of a positional argument **starting at** 1.
- ///
- /// **NOTE:** The index refers to position according to **other positional argument**. It does
- /// not define position in the argument list as a whole.
- ///
- /// **NOTE:** You can optionally leave off the `index` method, and the index will be
- /// assigned in order of evaluation. Utilizing the `index` method allows for setting
- /// indexes out of order
- ///
- /// **NOTE:** This is only meant to be used for positional arguments and shouldn't to be used
- /// with [`Arg::short`] or [`Arg::long`].
- ///
- /// **NOTE:** When utilized with [`Arg::multiple_values(true)`], only the **last** positional argument
- /// may be defined as multiple (i.e. with the highest index)
- ///
- /// # Panics
- ///
- /// [`Command`] will [`panic!`] if indexes are skipped (such as defining `index(1)` and `index(3)`
- /// but not `index(2)`, or a positional argument is defined as multiple and is not the highest
- /// index
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// Arg::new("config")
- /// .index(1)
- /// # ;
- /// ```
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// let m = Command::new("prog")
- /// .arg(Arg::new("mode")
- /// .index(1))
- /// .arg(Arg::new("debug")
- /// .long("debug"))
- /// .get_matches_from(vec![
- /// "prog", "--debug", "fast"
- /// ]);
- ///
- /// assert!(m.contains_id("mode"));
- /// assert_eq!(m.value_of("mode"), Some("fast")); // notice index(1) means "first positional"
- /// // *not* first argument
- /// ```
- /// [`Arg::short`]: Arg::short()
- /// [`Arg::long`]: Arg::long()
- /// [`Arg::multiple_values(true)`]: Arg::multiple_values()
- /// [`panic!`]: https://doc.rust-lang.org/std/macro.panic!.html
- /// [`Command`]: crate::Command
- #[inline]
- #[must_use]
- pub fn index(mut self, idx: usize) -> Self {
- self.index = Some(idx);
- self
- }
-
- /// This arg is the last, or final, positional argument (i.e. has the highest
- /// index) and is *only* able to be accessed via the `--` syntax (i.e. `$ prog args --
- /// last_arg`).
- ///
- /// Even, if no other arguments are left to parse, if the user omits the `--` syntax
- /// they will receive an [`UnknownArgument`] error. Setting an argument to `.last(true)` also
- /// allows one to access this arg early using the `--` syntax. Accessing an arg early, even with
- /// the `--` syntax is otherwise not possible.
- ///
- /// **NOTE:** This will change the usage string to look like `$ prog [OPTIONS] [-- <ARG>]` if
- /// `ARG` is marked as `.last(true)`.
- ///
- /// **NOTE:** This setting will imply [`crate::Command::dont_collapse_args_in_usage`] because failing
- /// to set this can make the usage string very confusing.
- ///
- /// **NOTE**: This setting only applies to positional arguments, and has no effect on OPTIONS
- ///
- /// **NOTE:** Setting this requires [`Arg::takes_value`]
- ///
- /// **CAUTION:** Using this setting *and* having child subcommands is not
- /// recommended with the exception of *also* using
- /// [`crate::Command::args_conflicts_with_subcommands`]
- /// (or [`crate::Command::subcommand_negates_reqs`] if the argument marked `Last` is also
- /// marked [`Arg::required`])
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::Arg;
- /// Arg::new("args")
- /// .takes_value(true)
- /// .last(true)
- /// # ;
- /// ```
- ///
- /// Setting `last` ensures the arg has the highest [index] of all positional args
- /// and requires that the `--` syntax be used to access it early.
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// let res = Command::new("prog")
- /// .arg(Arg::new("first"))
- /// .arg(Arg::new("second"))
- /// .arg(Arg::new("third")
- /// .takes_value(true)
- /// .last(true))
- /// .try_get_matches_from(vec![
- /// "prog", "one", "--", "three"
- /// ]);
- ///
- /// assert!(res.is_ok());
- /// let m = res.unwrap();
- /// assert_eq!(m.value_of("third"), Some("three"));
- /// assert!(m.value_of("second").is_none());
- /// ```
- ///
- /// Even if the positional argument marked `Last` is the only argument left to parse,
- /// failing to use the `--` syntax results in an error.
- ///
- /// ```rust
- /// # use clap::{Command, Arg, ErrorKind};
- /// let res = Command::new("prog")
- /// .arg(Arg::new("first"))
- /// .arg(Arg::new("second"))
- /// .arg(Arg::new("third")
- /// .takes_value(true)
- /// .last(true))
- /// .try_get_matches_from(vec![
- /// "prog", "one", "two", "three"
- /// ]);
- ///
- /// assert!(res.is_err());
- /// assert_eq!(res.unwrap_err().kind(), ErrorKind::UnknownArgument);
- /// ```
- /// [index]: Arg::index()
- /// [`UnknownArgument`]: crate::ErrorKind::UnknownArgument
- #[inline]
- #[must_use]
- pub fn last(self, yes: bool) -> Self {
- if yes {
- self.setting(ArgSettings::Last)
- } else {
- self.unset_setting(ArgSettings::Last)
- }
- }
-
- /// Specifies that the argument must be present.
- ///
- /// Required by default means it is required, when no other conflicting rules or overrides have
- /// been evaluated. Conflicting rules take precedence over being required.
- ///
- /// **Pro tip:** Flags (i.e. not positional, or arguments that take values) shouldn't be
- /// required by default. This is because if a flag were to be required, it should simply be
- /// implied. No additional information is required from user. Flags by their very nature are
- /// simply boolean on/off switches. The only time a user *should* be required to use a flag
- /// is if the operation is destructive in nature, and the user is essentially proving to you,
- /// "Yes, I know what I'm doing."
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::Arg;
- /// Arg::new("config")
- /// .required(true)
- /// # ;
- /// ```
- ///
- /// Setting required requires that the argument be used at runtime.
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// let res = Command::new("prog")
- /// .arg(Arg::new("cfg")
- /// .required(true)
- /// .takes_value(true)
- /// .long("config"))
- /// .try_get_matches_from(vec![
- /// "prog", "--config", "file.conf",
- /// ]);
- ///
- /// assert!(res.is_ok());
- /// ```
- ///
- /// Setting required and then *not* supplying that argument at runtime is an error.
- ///
- /// ```rust
- /// # use clap::{Command, Arg, ErrorKind};
- /// let res = Command::new("prog")
- /// .arg(Arg::new("cfg")
- /// .required(true)
- /// .takes_value(true)
- /// .long("config"))
- /// .try_get_matches_from(vec![
- /// "prog"
- /// ]);
- ///
- /// assert!(res.is_err());
- /// assert_eq!(res.unwrap_err().kind(), ErrorKind::MissingRequiredArgument);
- /// ```
- #[inline]
- #[must_use]
- pub fn required(self, yes: bool) -> Self {
- if yes {
- self.setting(ArgSettings::Required)
- } else {
- self.unset_setting(ArgSettings::Required)
- }
- }
-
- /// Sets an argument that is required when this one is present
- ///
- /// i.e. when using this argument, the following argument *must* be present.
- ///
- /// **NOTE:** [Conflicting] rules and [override] rules take precedence over being required
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::Arg;
- /// Arg::new("config")
- /// .requires("input")
- /// # ;
- /// ```
- ///
- /// Setting [`Arg::requires(name)`] requires that the argument be used at runtime if the
- /// defining argument is used. If the defining argument isn't used, the other argument isn't
- /// required
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// let res = Command::new("prog")
- /// .arg(Arg::new("cfg")
- /// .takes_value(true)
- /// .requires("input")
- /// .long("config"))
- /// .arg(Arg::new("input"))
- /// .try_get_matches_from(vec![
- /// "prog"
- /// ]);
- ///
- /// assert!(res.is_ok()); // We didn't use cfg, so input wasn't required
- /// ```
- ///
- /// Setting [`Arg::requires(name)`] and *not* supplying that argument is an error.
- ///
- /// ```rust
- /// # use clap::{Command, Arg, ErrorKind};
- /// let res = Command::new("prog")
- /// .arg(Arg::new("cfg")
- /// .takes_value(true)
- /// .requires("input")
- /// .long("config"))
- /// .arg(Arg::new("input"))
- /// .try_get_matches_from(vec![
- /// "prog", "--config", "file.conf"
- /// ]);
- ///
- /// assert!(res.is_err());
- /// assert_eq!(res.unwrap_err().kind(), ErrorKind::MissingRequiredArgument);
- /// ```
- /// [`Arg::requires(name)`]: Arg::requires()
- /// [Conflicting]: Arg::conflicts_with()
- /// [override]: Arg::overrides_with()
- #[must_use]
- pub fn requires<T: Key>(mut self, arg_id: T) -> Self {
- self.requires.push((ArgPredicate::IsPresent, arg_id.into()));
- self
- }
-
- /// This argument must be passed alone; it conflicts with all other arguments.
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::Arg;
- /// Arg::new("config")
- /// .exclusive(true)
- /// # ;
- /// ```
- ///
- /// Setting an exclusive argument and having any other arguments present at runtime
- /// is an error.
- ///
- /// ```rust
- /// # use clap::{Command, Arg, ErrorKind};
- /// let res = Command::new("prog")
- /// .arg(Arg::new("exclusive")
- /// .takes_value(true)
- /// .exclusive(true)
- /// .long("exclusive"))
- /// .arg(Arg::new("debug")
- /// .long("debug"))
- /// .arg(Arg::new("input"))
- /// .try_get_matches_from(vec![
- /// "prog", "--exclusive", "file.conf", "file.txt"
- /// ]);
- ///
- /// assert!(res.is_err());
- /// assert_eq!(res.unwrap_err().kind(), ErrorKind::ArgumentConflict);
- /// ```
- #[inline]
- #[must_use]
- pub fn exclusive(self, yes: bool) -> Self {
- if yes {
- self.setting(ArgSettings::Exclusive)
- } else {
- self.unset_setting(ArgSettings::Exclusive)
- }
- }
-
- /// Specifies that an argument can be matched to all child [`Subcommand`]s.
- ///
- /// **NOTE:** Global arguments *only* propagate down, **not** up (to parent commands), however
- /// their values once a user uses them will be propagated back up to parents. In effect, this
- /// means one should *define* all global arguments at the top level, however it doesn't matter
- /// where the user *uses* the global argument.
- ///
- /// # Examples
- ///
- /// Assume an application with two subcommands, and you'd like to define a
- /// `--verbose` flag that can be called on any of the subcommands and parent, but you don't
- /// want to clutter the source with three duplicate [`Arg`] definitions.
- ///
- /// ```rust
- /// # use clap::{Command, Arg, ArgAction};
- /// let m = Command::new("prog")
- /// .arg(Arg::new("verb")
- /// .long("verbose")
- /// .short('v')
- /// .action(ArgAction::SetTrue)
- /// .global(true))
- /// .subcommand(Command::new("test"))
- /// .subcommand(Command::new("do-stuff"))
- /// .get_matches_from(vec![
- /// "prog", "do-stuff", "--verbose"
- /// ]);
- ///
- /// assert_eq!(m.subcommand_name(), Some("do-stuff"));
- /// let sub_m = m.subcommand_matches("do-stuff").unwrap();
- /// assert_eq!(*sub_m.get_one::<bool>("verb").expect("defaulted by clap"), true);
- /// ```
- ///
- /// [`Subcommand`]: crate::Subcommand
- #[inline]
- #[must_use]
- pub fn global(self, yes: bool) -> Self {
- if yes {
- self.setting(ArgSettings::Global)
- } else {
- self.unset_setting(ArgSettings::Global)
- }
- }
-
- /// Deprecated, replaced with [`Arg::action`] ([Issue #3772](https://github.com/clap-rs/clap/issues/3772))
- #[inline]
- #[must_use]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.2.0", note = "Replaced with `Arg::action` (Issue #3772)")
- )]
- pub fn multiple_occurrences(self, yes: bool) -> Self {
- if yes {
- self.setting(ArgSettings::MultipleOccurrences)
- } else {
- self.unset_setting(ArgSettings::MultipleOccurrences)
- }
- }
-
- /// Deprecated, for flags this is replaced with `action(ArgAction::Count).value_parser(value_parser!(u8).range(..max))`
- #[inline]
- #[must_use]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.2.0",
- note = "For flags, replaced with `action(ArgAction::Count).value_parser(value_parser!(u8).range(..max))`"
- )
- )]
- pub fn max_occurrences(mut self, qty: usize) -> Self {
- self.max_occurs = Some(qty);
- if qty > 1 {
- self.multiple_occurrences(true)
- } else {
- self
- }
- }
-
- /// Check if the [`ArgSettings`] variant is currently set on the argument.
- ///
- /// [`ArgSettings`]: crate::ArgSettings
- #[inline]
- pub fn is_set(&self, s: ArgSettings) -> bool {
- self.settings.is_set(s)
- }
-
- /// Apply a setting to the argument.
- ///
- /// See [`ArgSettings`] for a full list of possibilities and examples.
- ///
- /// # Examples
- ///
- /// ```no_run
- /// # use clap::{Arg, ArgSettings};
- /// Arg::new("config")
- /// .setting(ArgSettings::Required)
- /// .setting(ArgSettings::TakesValue)
- /// # ;
- /// ```
- ///
- /// ```no_run
- /// # use clap::{Arg, ArgSettings};
- /// Arg::new("config")
- /// .setting(ArgSettings::Required | ArgSettings::TakesValue)
- /// # ;
- /// ```
- #[inline]
- #[must_use]
- pub fn setting<F>(mut self, setting: F) -> Self
- where
- F: Into<ArgFlags>,
- {
- self.settings.insert(setting.into());
- self
- }
-
- /// Remove a setting from the argument.
- ///
- /// See [`ArgSettings`] for a full list of possibilities and examples.
- ///
- /// # Examples
- ///
- /// ```no_run
- /// # use clap::{Arg, ArgSettings};
- /// Arg::new("config")
- /// .unset_setting(ArgSettings::Required)
- /// .unset_setting(ArgSettings::TakesValue)
- /// # ;
- /// ```
- ///
- /// ```no_run
- /// # use clap::{Arg, ArgSettings};
- /// Arg::new("config")
- /// .unset_setting(ArgSettings::Required | ArgSettings::TakesValue)
- /// # ;
- /// ```
- #[inline]
- #[must_use]
- pub fn unset_setting<F>(mut self, setting: F) -> Self
- where
- F: Into<ArgFlags>,
- {
- self.settings.remove(setting.into());
- self
- }
-}
-
-/// # Value Handling
-impl<'help> Arg<'help> {
- /// Specifies that the argument takes a value at run time.
- ///
- /// **NOTE:** values for arguments may be specified in any of the following methods
- ///
- /// - Using a space such as `-o value` or `--option value`
- /// - Using an equals and no space such as `-o=value` or `--option=value`
- /// - Use a short and no space such as `-ovalue`
- ///
- /// **NOTE:** By default, args which allow [multiple values] are delimited by commas, meaning
- /// `--option=val1,val2,val3` is three values for the `--option` argument. If you wish to
- /// change the delimiter to another character you can use [`Arg::value_delimiter(char)`],
- /// alternatively you can turn delimiting values **OFF** by using
- /// [`Arg::use_value_delimiter(false)`][Arg::use_value_delimiter]
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// let m = Command::new("prog")
- /// .arg(Arg::new("mode")
- /// .long("mode")
- /// .takes_value(true))
- /// .get_matches_from(vec![
- /// "prog", "--mode", "fast"
- /// ]);
- ///
- /// assert!(m.contains_id("mode"));
- /// assert_eq!(m.value_of("mode"), Some("fast"));
- /// ```
- /// [`Arg::value_delimiter(char)`]: Arg::value_delimiter()
- /// [multiple values]: Arg::multiple_values
- #[inline]
- #[must_use]
- pub fn takes_value(self, yes: bool) -> Self {
- if yes {
- self.setting(ArgSettings::TakesValue)
- } else {
- self.unset_setting(ArgSettings::TakesValue)
- }
- }
-
- /// Specify the behavior when parsing an argument
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::Command;
- /// # use clap::Arg;
- /// let cmd = Command::new("mycmd")
- /// .arg(
- /// Arg::new("flag")
- /// .long("flag")
- /// .action(clap::ArgAction::Set)
- /// );
- ///
- /// let matches = cmd.try_get_matches_from(["mycmd", "--flag", "value"]).unwrap();
- /// assert!(matches.contains_id("flag"));
- /// assert_eq!(matches.occurrences_of("flag"), 0);
- /// assert_eq!(
- /// matches.get_many::<String>("flag").unwrap_or_default().map(|v| v.as_str()).collect::<Vec<_>>(),
- /// vec!["value"]
- /// );
- /// ```
- #[inline]
- #[must_use]
- pub fn action(mut self, action: ArgAction) -> Self {
- self.action = Some(action);
- self
- }
-
- /// Specify the type of the argument.
- ///
- /// This allows parsing and validating a value before storing it into
- /// [`ArgMatches`][crate::ArgMatches].
- ///
- /// See also
- /// - [`value_parser!`][crate::value_parser!] for auto-selecting a value parser for a given type
- /// - [`BoolishValueParser`][crate::builder::BoolishValueParser], and [`FalseyValueParser`][crate::builder::FalseyValueParser] for alternative `bool` implementations
- /// - [`NonEmptyStringValueParser`][crate::builder::NonEmptyStringValueParser] for basic validation for strings
- /// - [`RangedI64ValueParser`][crate::builder::RangedI64ValueParser] and [`RangedU64ValueParser`][crate::builder::RangedU64ValueParser] for numeric ranges
- /// - [`EnumValueParser`][crate::builder::EnumValueParser] and [`PossibleValuesParser`][crate::builder::PossibleValuesParser] for static enumerated values
- /// - or any other [`TypedValueParser`][crate::builder::TypedValueParser] implementation
- ///
- /// ```rust
- /// let mut cmd = clap::Command::new("raw")
- /// .arg(
- /// clap::Arg::new("color")
- /// .long("color")
- /// .value_parser(["always", "auto", "never"])
- /// .default_value("auto")
- /// )
- /// .arg(
- /// clap::Arg::new("hostname")
- /// .long("hostname")
- /// .value_parser(clap::builder::NonEmptyStringValueParser::new())
- /// .takes_value(true)
- /// .required(true)
- /// )
- /// .arg(
- /// clap::Arg::new("port")
- /// .long("port")
- /// .value_parser(clap::value_parser!(u16).range(3000..))
- /// .takes_value(true)
- /// .required(true)
- /// );
- ///
- /// let m = cmd.try_get_matches_from_mut(
- /// ["cmd", "--hostname", "rust-lang.org", "--port", "3001"]
- /// ).unwrap();
- ///
- /// let color: &String = m.get_one("color")
- /// .expect("default");
- /// assert_eq!(color, "auto");
- ///
- /// let hostname: &String = m.get_one("hostname")
- /// .expect("required");
- /// assert_eq!(hostname, "rust-lang.org");
- ///
- /// let port: u16 = *m.get_one("port")
- /// .expect("required");
- /// assert_eq!(port, 3001);
- /// ```
- pub fn value_parser(mut self, parser: impl Into<super::ValueParser>) -> Self {
- self.value_parser = Some(parser.into());
- self
- }
-
- /// Specifies that the argument may have an unknown number of values
- ///
- /// Without any other settings, this argument may appear only *once*.
- ///
- /// For example, `--opt val1 val2` is allowed, but `--opt val1 val2 --opt val3` is not.
- ///
- /// **NOTE:** Setting this requires [`Arg::takes_value`].
- ///
- /// **WARNING:**
- ///
- /// Setting `multiple_values` for an argument that takes a value, but with no other details can
- /// be dangerous in some circumstances. Because multiple values are allowed,
- /// `--option val1 val2 val3` is perfectly valid. Be careful when designing a CLI where
- /// positional arguments are *also* expected as `clap` will continue parsing *values* until one
- /// of the following happens:
- ///
- /// - It reaches the [maximum number of values]
- /// - It reaches a [specific number of values]
- /// - It finds another flag or option (i.e. something that starts with a `-`)
- /// - It reaches a [value terminator][Arg::value_terminator] is reached
- ///
- /// Alternatively, [require a delimiter between values][Arg::require_delimiter].
- ///
- /// **WARNING:**
- ///
- /// When using args with `multiple_values` and [`subcommands`], one needs to consider the
- /// possibility of an argument value being the same as a valid subcommand. By default `clap` will
- /// parse the argument in question as a value *only if* a value is possible at that moment.
- /// Otherwise it will be parsed as a subcommand. In effect, this means using `multiple_values` with no
- /// additional parameters and a value that coincides with a subcommand name, the subcommand
- /// cannot be called unless another argument is passed between them.
- ///
- /// As an example, consider a CLI with an option `--ui-paths=<paths>...` and subcommand `signer`
- ///
- /// The following would be parsed as values to `--ui-paths`.
- ///
- /// ```text
- /// $ program --ui-paths path1 path2 signer
- /// ```
- ///
- /// This is because `--ui-paths` accepts multiple values. `clap` will continue parsing values
- /// until another argument is reached and it knows `--ui-paths` is done parsing.
- ///
- /// By adding additional parameters to `--ui-paths` we can solve this issue. Consider adding
- /// [`Arg::number_of_values(1)`] or using *only* [`ArgAction::Append`]. The following are all
- /// valid, and `signer` is parsed as a subcommand in the first case, but a value in the second
- /// case.
- ///
- /// ```text
- /// $ program --ui-paths path1 signer
- /// $ program --ui-paths path1 --ui-paths signer signer
- /// ```
- ///
- /// # Examples
- ///
- /// An example with options
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// let m = Command::new("prog")
- /// .arg(Arg::new("file")
- /// .takes_value(true)
- /// .multiple_values(true)
- /// .short('F'))
- /// .get_matches_from(vec![
- /// "prog", "-F", "file1", "file2", "file3"
- /// ]);
- ///
- /// assert!(m.contains_id("file"));
- /// let files: Vec<_> = m.values_of("file").unwrap().collect();
- /// assert_eq!(files, ["file1", "file2", "file3"]);
- /// ```
- ///
- /// Although `multiple_values` has been specified, we cannot use the argument more than once.
- ///
- /// ```rust
- /// # use clap::{Command, Arg, ErrorKind};
- /// let res = Command::new("prog")
- /// .arg(Arg::new("file")
- /// .takes_value(true)
- /// .multiple_values(true)
- /// .short('F'))
- /// .try_get_matches_from(vec![
- /// "prog", "-F", "file1", "-F", "file2", "-F", "file3"
- /// ]);
- ///
- /// assert!(res.is_err());
- /// assert_eq!(res.unwrap_err().kind(), ErrorKind::UnexpectedMultipleUsage)
- /// ```
- ///
- /// A common mistake is to define an option which allows multiple values, and a positional
- /// argument.
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// let m = Command::new("prog")
- /// .arg(Arg::new("file")
- /// .takes_value(true)
- /// .multiple_values(true)
- /// .short('F'))
- /// .arg(Arg::new("word"))
- /// .get_matches_from(vec![
- /// "prog", "-F", "file1", "file2", "file3", "word"
- /// ]);
- ///
- /// assert!(m.contains_id("file"));
- /// let files: Vec<_> = m.values_of("file").unwrap().collect();
- /// assert_eq!(files, ["file1", "file2", "file3", "word"]); // wait...what?!
- /// assert!(!m.contains_id("word")); // but we clearly used word!
- /// ```
- ///
- /// The problem is `clap` doesn't know when to stop parsing values for "files". This is further
- /// compounded by if we'd said `word -F file1 file2` it would have worked fine, so it would
- /// appear to only fail sometimes...not good!
- ///
- /// A solution for the example above is to limit how many values with a [maximum], or [specific]
- /// number, or to say [`ArgAction::Append`] is ok, but multiple values is not.
- ///
- /// ```rust
- /// # use clap::{Command, Arg, ArgAction};
- /// let m = Command::new("prog")
- /// .arg(Arg::new("file")
- /// .takes_value(true)
- /// .action(ArgAction::Append)
- /// .short('F'))
- /// .arg(Arg::new("word"))
- /// .get_matches_from(vec![
- /// "prog", "-F", "file1", "-F", "file2", "-F", "file3", "word"
- /// ]);
- ///
- /// assert!(m.contains_id("file"));
- /// let files: Vec<_> = m.values_of("file").unwrap().collect();
- /// assert_eq!(files, ["file1", "file2", "file3"]);
- /// assert!(m.contains_id("word"));
- /// assert_eq!(m.value_of("word"), Some("word"));
- /// ```
- ///
- /// As a final example, let's fix the above error and get a pretty message to the user :)
- ///
- /// ```rust
- /// # use clap::{Command, Arg, ErrorKind, ArgAction};
- /// let res = Command::new("prog")
- /// .arg(Arg::new("file")
- /// .takes_value(true)
- /// .action(ArgAction::Append)
- /// .short('F'))
- /// .arg(Arg::new("word"))
- /// .try_get_matches_from(vec![
- /// "prog", "-F", "file1", "file2", "file3", "word"
- /// ]);
- ///
- /// assert!(res.is_err());
- /// assert_eq!(res.unwrap_err().kind(), ErrorKind::UnknownArgument);
- /// ```
- ///
- /// [`subcommands`]: crate::Command::subcommand()
- /// [`Arg::number_of_values(1)`]: Arg::number_of_values()
- /// [maximum number of values]: Arg::max_values()
- /// [specific number of values]: Arg::number_of_values()
- /// [maximum]: Arg::max_values()
- /// [specific]: Arg::number_of_values()
- #[inline]
- #[must_use]
- pub fn multiple_values(self, yes: bool) -> Self {
- if yes {
- self.setting(ArgSettings::MultipleValues)
- } else {
- self.unset_setting(ArgSettings::MultipleValues)
- }
- }
-
- /// The number of values allowed for this argument.
- ///
- /// For example, if you had a
- /// `-f <file>` argument where you wanted exactly 3 'files' you would set
- /// `.number_of_values(3)`, and this argument wouldn't be satisfied unless the user provided
- /// 3 and only 3 values.
- ///
- /// **NOTE:** Does *not* require [`Arg::multiple_occurrences(true)`] to be set. Setting
- /// [`Arg::multiple_occurrences(true)`] would allow `-f <file> <file> <file> -f <file> <file> <file>` where
- /// as *not* setting it would only allow one occurrence of this argument.
- ///
- /// **NOTE:** implicitly sets [`Arg::takes_value(true)`] and [`Arg::multiple_values(true)`].
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// Arg::new("file")
- /// .short('f')
- /// .number_of_values(3);
- /// ```
- ///
- /// Not supplying the correct number of values is an error
- ///
- /// ```rust
- /// # use clap::{Command, Arg, ErrorKind};
- /// let res = Command::new("prog")
- /// .arg(Arg::new("file")
- /// .takes_value(true)
- /// .number_of_values(2)
- /// .short('F'))
- /// .try_get_matches_from(vec![
- /// "prog", "-F", "file1"
- /// ]);
- ///
- /// assert!(res.is_err());
- /// assert_eq!(res.unwrap_err().kind(), ErrorKind::WrongNumberOfValues);
- /// ```
- /// [`Arg::multiple_occurrences(true)`]: Arg::multiple_occurrences()
- #[inline]
- #[must_use]
- pub fn number_of_values(mut self, qty: usize) -> Self {
- self.num_vals = Some(qty);
- self.takes_value(true).multiple_values(true)
- }
-
- /// The *maximum* number of values are for this argument.
- ///
- /// For example, if you had a
- /// `-f <file>` argument where you wanted up to 3 'files' you would set `.max_values(3)`, and
- /// this argument would be satisfied if the user provided, 1, 2, or 3 values.
- ///
- /// **NOTE:** This does *not* implicitly set [`Arg::multiple_occurrences(true)`]. This is because
- /// `-o val -o val` is multiple occurrences but a single value and `-o val1 val2` is a single
- /// occurrence with multiple values. For positional arguments this **does** set
- /// [`Arg::multiple_occurrences(true)`] because there is no way to determine the difference between multiple
- /// occurrences and multiple values.
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// Arg::new("file")
- /// .short('f')
- /// .max_values(3);
- /// ```
- ///
- /// Supplying less than the maximum number of values is allowed
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// let res = Command::new("prog")
- /// .arg(Arg::new("file")
- /// .takes_value(true)
- /// .max_values(3)
- /// .short('F'))
- /// .try_get_matches_from(vec![
- /// "prog", "-F", "file1", "file2"
- /// ]);
- ///
- /// assert!(res.is_ok());
- /// let m = res.unwrap();
- /// let files: Vec<_> = m.values_of("file").unwrap().collect();
- /// assert_eq!(files, ["file1", "file2"]);
- /// ```
- ///
- /// Supplying more than the maximum number of values is an error
- ///
- /// ```rust
- /// # use clap::{Command, Arg, ErrorKind};
- /// let res = Command::new("prog")
- /// .arg(Arg::new("file")
- /// .takes_value(true)
- /// .max_values(2)
- /// .short('F'))
- /// .try_get_matches_from(vec![
- /// "prog", "-F", "file1", "file2", "file3"
- /// ]);
- ///
- /// assert!(res.is_err());
- /// assert_eq!(res.unwrap_err().kind(), ErrorKind::UnknownArgument);
- /// ```
- /// [`Arg::multiple_occurrences(true)`]: Arg::multiple_occurrences()
- #[inline]
- #[must_use]
- pub fn max_values(mut self, qty: usize) -> Self {
- self.max_vals = Some(qty);
- self.takes_value(true).multiple_values(true)
- }
-
- /// The *minimum* number of values for this argument.
- ///
- /// For example, if you had a
- /// `-f <file>` argument where you wanted at least 2 'files' you would set
- /// `.min_values(2)`, and this argument would be satisfied if the user provided, 2 or more
- /// values.
- ///
- /// **NOTE:** This does not implicitly set [`Arg::multiple_occurrences(true)`]. This is because
- /// `-o val -o val` is multiple occurrences but a single value and `-o val1 val2` is a single
- /// occurrence with multiple values. For positional arguments this **does** set
- /// [`Arg::multiple_occurrences(true)`] because there is no way to determine the difference between multiple
- /// occurrences and multiple values.
- ///
- /// **NOTE:** Passing a non-zero value is not the same as specifying [`Arg::required(true)`].
- /// This is due to min and max validation only being performed for present arguments,
- /// marking them as required will thus perform validation and a min value of 1
- /// is unnecessary, ignored if not required.
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// Arg::new("file")
- /// .short('f')
- /// .min_values(3);
- /// ```
- ///
- /// Supplying more than the minimum number of values is allowed
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// let res = Command::new("prog")
- /// .arg(Arg::new("file")
- /// .takes_value(true)
- /// .min_values(2)
- /// .short('F'))
- /// .try_get_matches_from(vec![
- /// "prog", "-F", "file1", "file2", "file3"
- /// ]);
- ///
- /// assert!(res.is_ok());
- /// let m = res.unwrap();
- /// let files: Vec<_> = m.values_of("file").unwrap().collect();
- /// assert_eq!(files, ["file1", "file2", "file3"]);
- /// ```
- ///
- /// Supplying less than the minimum number of values is an error
- ///
- /// ```rust
- /// # use clap::{Command, Arg, ErrorKind};
- /// let res = Command::new("prog")
- /// .arg(Arg::new("file")
- /// .takes_value(true)
- /// .min_values(2)
- /// .short('F'))
- /// .try_get_matches_from(vec![
- /// "prog", "-F", "file1"
- /// ]);
- ///
- /// assert!(res.is_err());
- /// assert_eq!(res.unwrap_err().kind(), ErrorKind::TooFewValues);
- /// ```
- /// [`Arg::multiple_occurrences(true)`]: Arg::multiple_occurrences()
- /// [`Arg::required(true)`]: Arg::required()
- #[inline]
- #[must_use]
- pub fn min_values(mut self, qty: usize) -> Self {
- self.min_vals = Some(qty);
- self.takes_value(true).multiple_values(true)
- }
-
- /// Placeholder for the argument's value in the help message / usage.
- ///
- /// This name is cosmetic only; the name is **not** used to access arguments.
- /// This setting can be very helpful when describing the type of input the user should be
- /// using, such as `FILE`, `INTERFACE`, etc. Although not required, it's somewhat convention to
- /// use all capital letters for the value name.
- ///
- /// **NOTE:** implicitly sets [`Arg::takes_value(true)`]
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// Arg::new("cfg")
- /// .long("config")
- /// .value_name("FILE")
- /// # ;
- /// ```
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// let m = Command::new("prog")
- /// .arg(Arg::new("config")
- /// .long("config")
- /// .value_name("FILE")
- /// .help("Some help text"))
- /// .get_matches_from(vec![
- /// "prog", "--help"
- /// ]);
- /// ```
- /// Running the above program produces the following output
- ///
- /// ```text
- /// valnames
- ///
- /// USAGE:
- /// valnames [OPTIONS]
- ///
- /// OPTIONS:
- /// --config <FILE> Some help text
- /// -h, --help Print help information
- /// -V, --version Print version information
- /// ```
- /// [option]: Arg::takes_value()
- /// [positional]: Arg::index()
- /// [`Arg::takes_value(true)`]: Arg::takes_value()
- #[inline]
- #[must_use]
- pub fn value_name(self, name: &'help str) -> Self {
- self.value_names(&[name])
- }
-
- /// Placeholders for the argument's values in the help message / usage.
- ///
- /// These names are cosmetic only, used for help and usage strings only. The names are **not**
- /// used to access arguments. The values of the arguments are accessed in numeric order (i.e.
- /// if you specify two names `one` and `two` `one` will be the first matched value, `two` will
- /// be the second).
- ///
- /// This setting can be very helpful when describing the type of input the user should be
- /// using, such as `FILE`, `INTERFACE`, etc. Although not required, it's somewhat convention to
- /// use all capital letters for the value name.
- ///
- /// **Pro Tip:** It may help to use [`Arg::next_line_help(true)`] if there are long, or
- /// multiple value names in order to not throw off the help text alignment of all options.
- ///
- /// **NOTE:** implicitly sets [`Arg::takes_value(true)`] and [`Arg::multiple_values(true)`].
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// Arg::new("speed")
- /// .short('s')
- /// .value_names(&["fast", "slow"]);
- /// ```
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// let m = Command::new("prog")
- /// .arg(Arg::new("io")
- /// .long("io-files")
- /// .value_names(&["INFILE", "OUTFILE"]))
- /// .get_matches_from(vec![
- /// "prog", "--help"
- /// ]);
- /// ```
- ///
- /// Running the above program produces the following output
- ///
- /// ```text
- /// valnames
- ///
- /// USAGE:
- /// valnames [OPTIONS]
- ///
- /// OPTIONS:
- /// -h, --help Print help information
- /// --io-files <INFILE> <OUTFILE> Some help text
- /// -V, --version Print version information
- /// ```
- /// [`Arg::next_line_help(true)`]: Arg::next_line_help()
- /// [`Arg::number_of_values`]: Arg::number_of_values()
- /// [`Arg::takes_value(true)`]: Arg::takes_value()
- /// [`Arg::multiple_values(true)`]: Arg::multiple_values()
- #[must_use]
- pub fn value_names(mut self, names: &[&'help str]) -> Self {
- self.val_names = names.to_vec();
- self.takes_value(true)
- }
-
- /// Provide the shell a hint about how to complete this argument.
- ///
- /// See [`ValueHint`][crate::ValueHint] for more information.
- ///
- /// **NOTE:** implicitly sets [`Arg::takes_value(true)`].
- ///
- /// For example, to take a username as argument:
- ///
- /// ```
- /// # use clap::{Arg, ValueHint};
- /// Arg::new("user")
- /// .short('u')
- /// .long("user")
- /// .value_hint(ValueHint::Username);
- /// ```
- ///
- /// To take a full command line and its arguments (for example, when writing a command wrapper):
- ///
- /// ```
- /// # use clap::{Command, Arg, ValueHint};
- /// Command::new("prog")
- /// .trailing_var_arg(true)
- /// .arg(
- /// Arg::new("command")
- /// .takes_value(true)
- /// .multiple_values(true)
- /// .value_hint(ValueHint::CommandWithArguments)
- /// );
- /// ```
- #[must_use]
- pub fn value_hint(mut self, value_hint: ValueHint) -> Self {
- self.value_hint = Some(value_hint);
- self.takes_value(true)
- }
-
- /// Deprecated, replaced with [`Arg::value_parser(...)`]
- #[inline]
- #[must_use]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.2.0", note = "Replaced with `Arg::value_parser(...)`")
- )]
- pub fn validator<F, O, E>(mut self, mut f: F) -> Self
- where
- F: FnMut(&str) -> Result<O, E> + Send + 'help,
- E: Into<Box<dyn Error + Send + Sync + 'static>>,
- {
- self.validator = Some(Arc::new(Mutex::new(move |s: &str| {
- f(s).map(|_| ()).map_err(|e| e.into())
- })));
- self
- }
-
- /// Deprecated, replaced with [`Arg::value_parser(...)`]
- #[must_use]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.2.0", note = "Replaced with `Arg::value_parser(...)`")
- )]
- pub fn validator_os<F, O, E>(mut self, mut f: F) -> Self
- where
- F: FnMut(&OsStr) -> Result<O, E> + Send + 'help,
- E: Into<Box<dyn Error + Send + Sync + 'static>>,
- {
- self.validator_os = Some(Arc::new(Mutex::new(move |s: &OsStr| {
- f(s).map(|_| ()).map_err(|e| e.into())
- })));
- self
- }
-
- /// Deprecated in [Issue #3743](https://github.com/clap-rs/clap/issues/3743), replaced with [`Arg::value_parser(...)`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.2.0",
- note = "Deprecated in Issue #3743; eplaced with `Arg::value_parser(...)`"
- )
- )]
- #[cfg(feature = "regex")]
- #[must_use]
- pub fn validator_regex(
- self,
- regex: impl Into<RegexRef<'help>>,
- err_message: &'help str,
- ) -> Self {
- let regex = regex.into();
- self.validator(move |s: &str| {
- if regex.is_match(s) {
- Ok(())
- } else {
- Err(err_message)
- }
- })
- }
-
- /// Deprecated, replaced with [`Arg::value_parser(PossibleValuesParser::new(...))`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.2.0",
- note = "Replaced with `Arg::value_parser(PossibleValuesParser::new(...)).takes_value(true)`"
- )
- )]
- #[must_use]
- pub fn possible_value<T>(mut self, value: T) -> Self
- where
- T: Into<PossibleValue<'help>>,
- {
- self.possible_vals.push(value.into());
- self.takes_value(true)
- }
-
- /// Deprecated, replaced with [`Arg::value_parser(PossibleValuesParser::new(...))`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.2.0",
- note = "Replaced with `Arg::value_parser(PossibleValuesParser::new(...)).takes_value(true)`"
- )
- )]
- #[must_use]
- pub fn possible_values<I, T>(mut self, values: I) -> Self
- where
- I: IntoIterator<Item = T>,
- T: Into<PossibleValue<'help>>,
- {
- self.possible_vals
- .extend(values.into_iter().map(|value| value.into()));
- self.takes_value(true)
- }
-
- /// Match values against [`Arg::possible_values`] without matching case.
- ///
- /// When other arguments are conditionally required based on the
- /// value of a case-insensitive argument, the equality check done
- /// by [`Arg::required_if_eq`], [`Arg::required_if_eq_any`], or
- /// [`Arg::required_if_eq_all`] is case-insensitive.
- ///
- ///
- /// **NOTE:** Setting this requires [`Arg::takes_value`]
- ///
- /// **NOTE:** To do unicode case folding, enable the `unicode` feature flag.
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// let m = Command::new("pv")
- /// .arg(Arg::new("option")
- /// .long("option")
- /// .takes_value(true)
- /// .ignore_case(true)
- /// .value_parser(["test123"]))
- /// .get_matches_from(vec![
- /// "pv", "--option", "TeSt123",
- /// ]);
- ///
- /// assert!(m.value_of("option").unwrap().eq_ignore_ascii_case("test123"));
- /// ```
- ///
- /// This setting also works when multiple values can be defined:
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// let m = Command::new("pv")
- /// .arg(Arg::new("option")
- /// .short('o')
- /// .long("option")
- /// .takes_value(true)
- /// .ignore_case(true)
- /// .multiple_values(true)
- /// .value_parser(["test123", "test321"]))
- /// .get_matches_from(vec![
- /// "pv", "--option", "TeSt123", "teST123", "tESt321"
- /// ]);
- ///
- /// let matched_vals = m.values_of("option").unwrap().collect::<Vec<_>>();
- /// assert_eq!(&*matched_vals, &["TeSt123", "teST123", "tESt321"]);
- /// ```
- #[inline]
- #[must_use]
- pub fn ignore_case(self, yes: bool) -> Self {
- if yes {
- self.setting(ArgSettings::IgnoreCase)
- } else {
- self.unset_setting(ArgSettings::IgnoreCase)
- }
- }
-
- /// Allows values which start with a leading hyphen (`-`)
- ///
- /// **NOTE:** Setting this requires [`Arg::takes_value`]
- ///
- /// **WARNING**: Take caution when using this setting combined with
- /// [`Arg::multiple_values`], as this becomes ambiguous `$ prog --arg -- -- val`. All
- /// three `--, --, val` will be values when the user may have thought the second `--` would
- /// constitute the normal, "Only positional args follow" idiom. To fix this, consider using
- /// [`Arg::multiple_occurrences`] which only allows a single value at a time.
- ///
- /// **WARNING**: When building your CLIs, consider the effects of allowing leading hyphens and
- /// the user passing in a value that matches a valid short. For example, `prog -opt -F` where
- /// `-F` is supposed to be a value, yet `-F` is *also* a valid short for another arg.
- /// Care should be taken when designing these args. This is compounded by the ability to "stack"
- /// short args. I.e. if `-val` is supposed to be a value, but `-v`, `-a`, and `-l` are all valid
- /// shorts.
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// let m = Command::new("prog")
- /// .arg(Arg::new("pat")
- /// .takes_value(true)
- /// .allow_hyphen_values(true)
- /// .long("pattern"))
- /// .get_matches_from(vec![
- /// "prog", "--pattern", "-file"
- /// ]);
- ///
- /// assert_eq!(m.value_of("pat"), Some("-file"));
- /// ```
- ///
- /// Not setting `Arg::allow_hyphen_values(true)` and supplying a value which starts with a
- /// hyphen is an error.
- ///
- /// ```rust
- /// # use clap::{Command, Arg, ErrorKind};
- /// let res = Command::new("prog")
- /// .arg(Arg::new("pat")
- /// .takes_value(true)
- /// .long("pattern"))
- /// .try_get_matches_from(vec![
- /// "prog", "--pattern", "-file"
- /// ]);
- ///
- /// assert!(res.is_err());
- /// assert_eq!(res.unwrap_err().kind(), ErrorKind::UnknownArgument);
- /// ```
- /// [`Arg::number_of_values(1)`]: Arg::number_of_values()
- #[inline]
- #[must_use]
- pub fn allow_hyphen_values(self, yes: bool) -> Self {
- if yes {
- self.setting(ArgSettings::AllowHyphenValues)
- } else {
- self.unset_setting(ArgSettings::AllowHyphenValues)
- }
- }
-
- /// Deprecated, replaced with [`Arg::value_parser(...)`] with either [`ValueParser::os_string()`][crate::builder::ValueParser::os_string]
- /// or [`ValueParser::path_buf()`][crate::builder::ValueParser::path_buf]
- #[inline]
- #[must_use]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.2.0",
- note = "Replaced with `Arg::value_parser(...)` with either `ValueParser::os_string()` or `ValueParser::path_buf()`"
- )
- )]
- pub fn allow_invalid_utf8(self, yes: bool) -> Self {
- if yes {
- self.setting(ArgSettings::AllowInvalidUtf8)
- } else {
- self.unset_setting(ArgSettings::AllowInvalidUtf8)
- }
- }
-
- /// Deprecated, replaced with [`Arg::value_parser(NonEmptyStringValueParser::new())`]
- #[inline]
- #[must_use]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.2.0",
- note = "Replaced with `Arg::value_parser(NonEmptyStringValueParser::new())`"
- )
- )]
- pub fn forbid_empty_values(self, yes: bool) -> Self {
- if yes {
- self.setting(ArgSettings::ForbidEmptyValues)
- } else {
- self.unset_setting(ArgSettings::ForbidEmptyValues)
- }
- }
-
- /// Requires that options use the `--option=val` syntax
- ///
- /// i.e. an equals between the option and associated value.
- ///
- /// **NOTE:** Setting this requires [`Arg::takes_value`]
- ///
- /// # Examples
- ///
- /// Setting `require_equals` requires that the option have an equals sign between
- /// it and the associated value.
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// let res = Command::new("prog")
- /// .arg(Arg::new("cfg")
- /// .takes_value(true)
- /// .require_equals(true)
- /// .long("config"))
- /// .try_get_matches_from(vec![
- /// "prog", "--config=file.conf"
- /// ]);
- ///
- /// assert!(res.is_ok());
- /// ```
- ///
- /// Setting `require_equals` and *not* supplying the equals will cause an
- /// error.
- ///
- /// ```rust
- /// # use clap::{Command, Arg, ErrorKind};
- /// let res = Command::new("prog")
- /// .arg(Arg::new("cfg")
- /// .takes_value(true)
- /// .require_equals(true)
- /// .long("config"))
- /// .try_get_matches_from(vec![
- /// "prog", "--config", "file.conf"
- /// ]);
- ///
- /// assert!(res.is_err());
- /// assert_eq!(res.unwrap_err().kind(), ErrorKind::NoEquals);
- /// ```
- #[inline]
- #[must_use]
- pub fn require_equals(self, yes: bool) -> Self {
- if yes {
- self.setting(ArgSettings::RequireEquals)
- } else {
- self.unset_setting(ArgSettings::RequireEquals)
- }
- }
-
- /// Specifies that an argument should allow grouping of multiple values via a
- /// delimiter.
- ///
- /// i.e. should `--option=val1,val2,val3` be parsed as three values (`val1`, `val2`,
- /// and `val3`) or as a single value (`val1,val2,val3`). Defaults to using `,` (comma) as the
- /// value delimiter for all arguments that accept values (options and positional arguments)
- ///
- /// **NOTE:** When this setting is used, it will default [`Arg::value_delimiter`]
- /// to the comma `,`.
- ///
- /// **NOTE:** Implicitly sets [`Arg::takes_value`]
- ///
- /// # Examples
- ///
- /// The following example shows the default behavior.
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// let delims = Command::new("prog")
- /// .arg(Arg::new("option")
- /// .long("option")
- /// .use_value_delimiter(true)
- /// .takes_value(true))
- /// .get_matches_from(vec![
- /// "prog", "--option=val1,val2,val3",
- /// ]);
- ///
- /// assert!(delims.contains_id("option"));
- /// assert_eq!(delims.values_of("option").unwrap().collect::<Vec<_>>(), ["val1", "val2", "val3"]);
- /// ```
- /// The next example shows the difference when turning delimiters off. This is the default
- /// behavior
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// let nodelims = Command::new("prog")
- /// .arg(Arg::new("option")
- /// .long("option")
- /// .takes_value(true))
- /// .get_matches_from(vec![
- /// "prog", "--option=val1,val2,val3",
- /// ]);
- ///
- /// assert!(nodelims.contains_id("option"));
- /// assert_eq!(nodelims.value_of("option").unwrap(), "val1,val2,val3");
- /// ```
- /// [`Arg::value_delimiter`]: Arg::value_delimiter()
- #[inline]
- #[must_use]
- pub fn use_value_delimiter(mut self, yes: bool) -> Self {
- if yes {
- if self.val_delim.is_none() {
- self.val_delim = Some(',');
- }
- self.takes_value(true)
- .setting(ArgSettings::UseValueDelimiter)
- } else {
- self.val_delim = None;
- self.unset_setting(ArgSettings::UseValueDelimiter)
- }
- }
-
- /// Deprecated, replaced with [`Arg::use_value_delimiter`]
- #[inline]
- #[must_use]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.1.0", note = "Replaced with `Arg::use_value_delimiter`")
- )]
- pub fn use_delimiter(self, yes: bool) -> Self {
- self.use_value_delimiter(yes)
- }
-
- /// Separator between the arguments values, defaults to `,` (comma).
- ///
- /// **NOTE:** implicitly sets [`Arg::use_value_delimiter(true)`]
- ///
- /// **NOTE:** implicitly sets [`Arg::takes_value(true)`]
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// let m = Command::new("prog")
- /// .arg(Arg::new("config")
- /// .short('c')
- /// .long("config")
- /// .value_delimiter(';'))
- /// .get_matches_from(vec![
- /// "prog", "--config=val1;val2;val3"
- /// ]);
- ///
- /// assert_eq!(m.values_of("config").unwrap().collect::<Vec<_>>(), ["val1", "val2", "val3"])
- /// ```
- /// [`Arg::use_value_delimiter(true)`]: Arg::use_value_delimiter()
- /// [`Arg::takes_value(true)`]: Arg::takes_value()
- #[inline]
- #[must_use]
- pub fn value_delimiter(mut self, d: char) -> Self {
- self.val_delim = Some(d);
- self.takes_value(true).use_value_delimiter(true)
- }
-
- /// Specifies that *multiple values* may only be set using the delimiter.
- ///
- /// This means if an option is encountered, and no delimiter is found, it is assumed that no
- /// additional values for that option follow. This is unlike the default, where it is generally
- /// assumed that more values will follow regardless of whether or not a delimiter is used.
- ///
- /// **NOTE:** The default is `false`.
- ///
- /// **NOTE:** Setting this requires [`Arg::use_value_delimiter`] and
- /// [`Arg::takes_value`]
- ///
- /// **NOTE:** It's a good idea to inform the user that use of a delimiter is required, either
- /// through help text or other means.
- ///
- /// # Examples
- ///
- /// These examples demonstrate what happens when `require_delimiter(true)` is used. Notice
- /// everything works in this first example, as we use a delimiter, as expected.
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// let delims = Command::new("prog")
- /// .arg(Arg::new("opt")
- /// .short('o')
- /// .takes_value(true)
- /// .use_value_delimiter(true)
- /// .require_delimiter(true)
- /// .multiple_values(true))
- /// .get_matches_from(vec![
- /// "prog", "-o", "val1,val2,val3",
- /// ]);
- ///
- /// assert!(delims.contains_id("opt"));
- /// assert_eq!(delims.values_of("opt").unwrap().collect::<Vec<_>>(), ["val1", "val2", "val3"]);
- /// ```
- ///
- /// In this next example, we will *not* use a delimiter. Notice it's now an error.
- ///
- /// ```rust
- /// # use clap::{Command, Arg, ErrorKind};
- /// let res = Command::new("prog")
- /// .arg(Arg::new("opt")
- /// .short('o')
- /// .takes_value(true)
- /// .use_value_delimiter(true)
- /// .require_delimiter(true))
- /// .try_get_matches_from(vec![
- /// "prog", "-o", "val1", "val2", "val3",
- /// ]);
- ///
- /// assert!(res.is_err());
- /// let err = res.unwrap_err();
- /// assert_eq!(err.kind(), ErrorKind::UnknownArgument);
- /// ```
- ///
- /// What's happening is `-o` is getting `val1`, and because delimiters are required yet none
- /// were present, it stops parsing `-o`. At this point it reaches `val2` and because no
- /// positional arguments have been defined, it's an error of an unexpected argument.
- ///
- /// In this final example, we contrast the above with `clap`'s default behavior where the above
- /// is *not* an error.
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// let delims = Command::new("prog")
- /// .arg(Arg::new("opt")
- /// .short('o')
- /// .takes_value(true)
- /// .multiple_values(true))
- /// .get_matches_from(vec![
- /// "prog", "-o", "val1", "val2", "val3",
- /// ]);
- ///
- /// assert!(delims.contains_id("opt"));
- /// assert_eq!(delims.values_of("opt").unwrap().collect::<Vec<_>>(), ["val1", "val2", "val3"]);
- /// ```
- #[inline]
- #[must_use]
- pub fn require_value_delimiter(self, yes: bool) -> Self {
- if yes {
- self.setting(ArgSettings::RequireDelimiter)
- } else {
- self.unset_setting(ArgSettings::RequireDelimiter)
- }
- }
-
- /// Deprecated, replaced with [`Arg::require_value_delimiter`]
- #[inline]
- #[must_use]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.1.0", note = "Replaced with `Arg::require_value_delimiter`")
- )]
- pub fn require_delimiter(self, yes: bool) -> Self {
- self.require_value_delimiter(yes)
- }
-
- /// Sentinel to **stop** parsing multiple values of a give argument.
- ///
- /// By default when
- /// one sets [`multiple_values(true)`] on an argument, clap will continue parsing values for that
- /// argument until it reaches another valid argument, or one of the other more specific settings
- /// for multiple values is used (such as [`min_values`], [`max_values`] or
- /// [`number_of_values`]).
- ///
- /// **NOTE:** This setting only applies to [options] and [positional arguments]
- ///
- /// **NOTE:** When the terminator is passed in on the command line, it is **not** stored as one
- /// of the values
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// Arg::new("vals")
- /// .takes_value(true)
- /// .multiple_values(true)
- /// .value_terminator(";")
- /// # ;
- /// ```
- ///
- /// The following example uses two arguments, a sequence of commands, and the location in which
- /// to perform them
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// let m = Command::new("prog")
- /// .arg(Arg::new("cmds")
- /// .takes_value(true)
- /// .multiple_values(true)
- /// .allow_hyphen_values(true)
- /// .value_terminator(";"))
- /// .arg(Arg::new("location"))
- /// .get_matches_from(vec![
- /// "prog", "find", "-type", "f", "-name", "special", ";", "/home/clap"
- /// ]);
- /// let cmds: Vec<_> = m.values_of("cmds").unwrap().collect();
- /// assert_eq!(&cmds, &["find", "-type", "f", "-name", "special"]);
- /// assert_eq!(m.value_of("location"), Some("/home/clap"));
- /// ```
- /// [options]: Arg::takes_value()
- /// [positional arguments]: Arg::index()
- /// [`multiple_values(true)`]: Arg::multiple_values()
- /// [`min_values`]: Arg::min_values()
- /// [`number_of_values`]: Arg::number_of_values()
- /// [`max_values`]: Arg::max_values()
- #[inline]
- #[must_use]
- pub fn value_terminator(mut self, term: &'help str) -> Self {
- self.terminator = Some(term);
- self.takes_value(true)
- }
-
- /// Consume all following arguments.
- ///
- /// Do not be parse them individually, but rather pass them in entirety.
- ///
- /// It is worth noting that setting this requires all values to come after a `--` to indicate
- /// they should all be captured. For example:
- ///
- /// ```text
- /// --foo something -- -v -v -v -b -b -b --baz -q -u -x
- /// ```
- ///
- /// Will result in everything after `--` to be considered one raw argument. This behavior
- /// may not be exactly what you are expecting and using [`crate::Command::trailing_var_arg`]
- /// may be more appropriate.
- ///
- /// **NOTE:** Implicitly sets [`Arg::takes_value(true)`] [`Arg::multiple_values(true)`],
- /// [`Arg::allow_hyphen_values(true)`], and [`Arg::last(true)`] when set to `true`.
- ///
- /// [`Arg::takes_value(true)`]: Arg::takes_value()
- /// [`Arg::multiple_values(true)`]: Arg::multiple_values()
- /// [`Arg::allow_hyphen_values(true)`]: Arg::allow_hyphen_values()
- /// [`Arg::last(true)`]: Arg::last()
- #[inline]
- #[must_use]
- pub fn raw(self, yes: bool) -> Self {
- self.takes_value(yes)
- .multiple_values(yes)
- .allow_hyphen_values(yes)
- .last(yes)
- }
-
- /// Value for the argument when not present.
- ///
- /// **NOTE:** If the user *does not* use this argument at runtime, [`ArgMatches::occurrences_of`]
- /// will return `0` even though the [`ArgMatches::value_of`] will return the default specified.
- ///
- /// **NOTE:** If the user *does not* use this argument at runtime [`ArgMatches::contains_id`] will
- /// still return `true`. If you wish to determine whether the argument was used at runtime or
- /// not, consider [`ArgMatches::value_source`][crate::ArgMatches::value_source].
- ///
- /// **NOTE:** This setting is perfectly compatible with [`Arg::default_value_if`] but slightly
- /// different. `Arg::default_value` *only* takes effect when the user has not provided this arg
- /// at runtime. `Arg::default_value_if` however only takes effect when the user has not provided
- /// a value at runtime **and** these other conditions are met as well. If you have set
- /// `Arg::default_value` and `Arg::default_value_if`, and the user **did not** provide this arg
- /// at runtime, nor were the conditions met for `Arg::default_value_if`, the `Arg::default_value`
- /// will be applied.
- ///
- /// **NOTE:** This implicitly sets [`Arg::takes_value(true)`].
- ///
- /// # Examples
- ///
- /// First we use the default value without providing any value at runtime.
- ///
- /// ```rust
- /// # use clap::{Command, Arg, ValueSource};
- /// let m = Command::new("prog")
- /// .arg(Arg::new("opt")
- /// .long("myopt")
- /// .default_value("myval"))
- /// .get_matches_from(vec![
- /// "prog"
- /// ]);
- ///
- /// assert_eq!(m.value_of("opt"), Some("myval"));
- /// assert!(m.contains_id("opt"));
- /// assert_eq!(m.value_source("opt"), Some(ValueSource::DefaultValue));
- /// ```
- ///
- /// Next we provide a value at runtime to override the default.
- ///
- /// ```rust
- /// # use clap::{Command, Arg, ValueSource};
- /// let m = Command::new("prog")
- /// .arg(Arg::new("opt")
- /// .long("myopt")
- /// .default_value("myval"))
- /// .get_matches_from(vec![
- /// "prog", "--myopt=non_default"
- /// ]);
- ///
- /// assert_eq!(m.value_of("opt"), Some("non_default"));
- /// assert!(m.contains_id("opt"));
- /// assert_eq!(m.value_source("opt"), Some(ValueSource::CommandLine));
- /// ```
- /// [`ArgMatches::occurrences_of`]: crate::ArgMatches::occurrences_of()
- /// [`ArgMatches::value_of`]: crate::ArgMatches::value_of()
- /// [`Arg::takes_value(true)`]: Arg::takes_value()
- /// [`ArgMatches::contains_id`]: crate::ArgMatches::contains_id()
- /// [`Arg::default_value_if`]: Arg::default_value_if()
- #[inline]
- #[must_use]
- pub fn default_value(self, val: &'help str) -> Self {
- self.default_values_os(&[OsStr::new(val)])
- }
-
- /// Value for the argument when not present.
- ///
- /// See [`Arg::default_value`].
- ///
- /// [`Arg::default_value`]: Arg::default_value()
- /// [`OsStr`]: std::ffi::OsStr
- #[inline]
- #[must_use]
- pub fn default_value_os(self, val: &'help OsStr) -> Self {
- self.default_values_os(&[val])
- }
-
- /// Value for the argument when not present.
- ///
- /// See [`Arg::default_value`].
- ///
- /// [`Arg::default_value`]: Arg::default_value()
- #[inline]
- #[must_use]
- pub fn default_values(self, vals: &[&'help str]) -> Self {
- let vals_vec: Vec<_> = vals.iter().map(|val| OsStr::new(*val)).collect();
- self.default_values_os(&vals_vec[..])
- }
-
- /// Value for the argument when not present.
- ///
- /// See [`Arg::default_values`].
- ///
- /// [`Arg::default_values`]: Arg::default_values()
- /// [`OsStr`]: std::ffi::OsStr
- #[inline]
- #[must_use]
- pub fn default_values_os(mut self, vals: &[&'help OsStr]) -> Self {
- self.default_vals = vals.to_vec();
- self.takes_value(true)
- }
-
- /// Value for the argument when the flag is present but no value is specified.
- ///
- /// This configuration option is often used to give the user a shortcut and allow them to
- /// efficiently specify an option argument without requiring an explicitly value. The `--color`
- /// argument is a common example. By, supplying an default, such as `default_missing_value("always")`,
- /// the user can quickly just add `--color` to the command line to produce the desired color output.
- ///
- /// **NOTE:** using this configuration option requires the use of the `.min_values(0)` and the
- /// `.require_equals(true)` configuration option. These are required in order to unambiguously
- /// determine what, if any, value was supplied for the argument.
- ///
- /// # Examples
- ///
- /// For POSIX style `--color`:
- /// ```rust
- /// # use clap::{Command, Arg, ValueSource};
- /// fn cli() -> Command<'static> {
- /// Command::new("prog")
- /// .arg(Arg::new("color").long("color")
- /// .value_name("WHEN")
- /// .value_parser(["always", "auto", "never"])
- /// .default_value("auto")
- /// .min_values(0)
- /// .require_equals(true)
- /// .default_missing_value("always")
- /// .help("Specify WHEN to colorize output.")
- /// )
- /// }
- ///
- /// // first, we'll provide no arguments
- /// let m = cli().get_matches_from(vec![
- /// "prog"
- /// ]);
- /// assert_eq!(m.value_of("color"), Some("auto"));
- /// assert_eq!(m.value_source("color"), Some(ValueSource::DefaultValue));
- ///
- /// // next, we'll provide a runtime value to override the default (as usually done).
- /// let m = cli().get_matches_from(vec![
- /// "prog", "--color=never"
- /// ]);
- /// assert_eq!(m.value_of("color"), Some("never"));
- /// assert_eq!(m.value_source("color"), Some(ValueSource::CommandLine));
- ///
- /// // finally, we will use the shortcut and only provide the argument without a value.
- /// let m = cli().get_matches_from(vec![
- /// "prog", "--color"
- /// ]);
- /// assert_eq!(m.value_of("color"), Some("always"));
- /// assert_eq!(m.value_source("color"), Some(ValueSource::CommandLine));
- /// ```
- ///
- /// For bool literals:
- /// ```rust
- /// # use clap::{Command, Arg, ValueSource, value_parser};
- /// fn cli() -> Command<'static> {
- /// Command::new("prog")
- /// .arg(Arg::new("create").long("create")
- /// .value_name("BOOL")
- /// .value_parser(value_parser!(bool))
- /// .min_values(0)
- /// .require_equals(true)
- /// .default_missing_value("true")
- /// )
- /// }
- ///
- /// // first, we'll provide no arguments
- /// let m = cli().get_matches_from(vec![
- /// "prog"
- /// ]);
- /// assert_eq!(m.get_one::<bool>("create").copied(), None);
- ///
- /// // next, we'll provide a runtime value to override the default (as usually done).
- /// let m = cli().get_matches_from(vec![
- /// "prog", "--create=false"
- /// ]);
- /// assert_eq!(m.get_one::<bool>("create").copied(), Some(false));
- /// assert_eq!(m.value_source("create"), Some(ValueSource::CommandLine));
- ///
- /// // finally, we will use the shortcut and only provide the argument without a value.
- /// let m = cli().get_matches_from(vec![
- /// "prog", "--create"
- /// ]);
- /// assert_eq!(m.get_one::<bool>("create").copied(), Some(true));
- /// assert_eq!(m.value_source("create"), Some(ValueSource::CommandLine));
- /// ```
- ///
- /// [`ArgMatches::value_of`]: ArgMatches::value_of()
- /// [`Arg::takes_value(true)`]: Arg::takes_value()
- /// [`Arg::default_value`]: Arg::default_value()
- #[inline]
- #[must_use]
- pub fn default_missing_value(self, val: &'help str) -> Self {
- self.default_missing_values_os(&[OsStr::new(val)])
- }
-
- /// Value for the argument when the flag is present but no value is specified.
- ///
- /// See [`Arg::default_missing_value`].
- ///
- /// [`Arg::default_missing_value`]: Arg::default_missing_value()
- /// [`OsStr`]: std::ffi::OsStr
- #[inline]
- #[must_use]
- pub fn default_missing_value_os(self, val: &'help OsStr) -> Self {
- self.default_missing_values_os(&[val])
- }
-
- /// Value for the argument when the flag is present but no value is specified.
- ///
- /// See [`Arg::default_missing_value`].
- ///
- /// [`Arg::default_missing_value`]: Arg::default_missing_value()
- #[inline]
- #[must_use]
- pub fn default_missing_values(self, vals: &[&'help str]) -> Self {
- let vals_vec: Vec<_> = vals.iter().map(|val| OsStr::new(*val)).collect();
- self.default_missing_values_os(&vals_vec[..])
- }
-
- /// Value for the argument when the flag is present but no value is specified.
- ///
- /// See [`Arg::default_missing_values`].
- ///
- /// [`Arg::default_missing_values`]: Arg::default_missing_values()
- /// [`OsStr`]: std::ffi::OsStr
- #[inline]
- #[must_use]
- pub fn default_missing_values_os(mut self, vals: &[&'help OsStr]) -> Self {
- self.default_missing_vals = vals.to_vec();
- self.takes_value(true)
- }
-
- /// Read from `name` environment variable when argument is not present.
- ///
- /// If it is not present in the environment, then default
- /// rules will apply.
- ///
- /// If user sets the argument in the environment:
- /// - When [`Arg::takes_value(true)`] is not set, the flag is considered raised.
- /// - When [`Arg::takes_value(true)`] is set, [`ArgMatches::value_of`] will
- /// return value of the environment variable.
- ///
- /// If user doesn't set the argument in the environment:
- /// - When [`Arg::takes_value(true)`] is not set, the flag is considered off.
- /// - When [`Arg::takes_value(true)`] is set, [`ArgMatches::value_of`] will
- /// return the default specified.
- ///
- /// # Examples
- ///
- /// In this example, we show the variable coming from the environment:
- ///
- /// ```rust
- /// # use std::env;
- /// # use clap::{Command, Arg};
- ///
- /// env::set_var("MY_FLAG", "env");
- ///
- /// let m = Command::new("prog")
- /// .arg(Arg::new("flag")
- /// .long("flag")
- /// .env("MY_FLAG")
- /// .takes_value(true))
- /// .get_matches_from(vec![
- /// "prog"
- /// ]);
- ///
- /// assert_eq!(m.value_of("flag"), Some("env"));
- /// ```
- ///
- /// In this example, because [`Arg::takes_value(false)`] (by default),
- /// `prog` is a flag that accepts an optional, case-insensitive boolean literal.
- /// A `false` literal is `n`, `no`, `f`, `false`, `off` or `0`.
- /// An absent environment variable will also be considered as `false`.
- /// Anything else will considered as `true`.
- ///
- /// ```rust
- /// # use std::env;
- /// # use clap::{Command, Arg};
- ///
- /// env::set_var("TRUE_FLAG", "true");
- /// env::set_var("FALSE_FLAG", "0");
- ///
- /// let m = Command::new("prog")
- /// .arg(Arg::new("true_flag")
- /// .long("true_flag")
- /// .env("TRUE_FLAG"))
- /// .arg(Arg::new("false_flag")
- /// .long("false_flag")
- /// .env("FALSE_FLAG"))
- /// .arg(Arg::new("absent_flag")
- /// .long("absent_flag")
- /// .env("ABSENT_FLAG"))
- /// .get_matches_from(vec![
- /// "prog"
- /// ]);
- ///
- /// assert!(m.is_present("true_flag"));
- /// assert_eq!(m.value_of("true_flag"), None);
- /// assert!(!m.is_present("false_flag"));
- /// assert!(!m.is_present("absent_flag"));
- /// ```
- ///
- /// In this example, we show the variable coming from an option on the CLI:
- ///
- /// ```rust
- /// # use std::env;
- /// # use clap::{Command, Arg};
- ///
- /// env::set_var("MY_FLAG", "env");
- ///
- /// let m = Command::new("prog")
- /// .arg(Arg::new("flag")
- /// .long("flag")
- /// .env("MY_FLAG")
- /// .takes_value(true))
- /// .get_matches_from(vec![
- /// "prog", "--flag", "opt"
- /// ]);
- ///
- /// assert_eq!(m.value_of("flag"), Some("opt"));
- /// ```
- ///
- /// In this example, we show the variable coming from the environment even with the
- /// presence of a default:
- ///
- /// ```rust
- /// # use std::env;
- /// # use clap::{Command, Arg};
- ///
- /// env::set_var("MY_FLAG", "env");
- ///
- /// let m = Command::new("prog")
- /// .arg(Arg::new("flag")
- /// .long("flag")
- /// .env("MY_FLAG")
- /// .takes_value(true)
- /// .default_value("default"))
- /// .get_matches_from(vec![
- /// "prog"
- /// ]);
- ///
- /// assert_eq!(m.value_of("flag"), Some("env"));
- /// ```
- ///
- /// In this example, we show the use of multiple values in a single environment variable:
- ///
- /// ```rust
- /// # use std::env;
- /// # use clap::{Command, Arg};
- ///
- /// env::set_var("MY_FLAG_MULTI", "env1,env2");
- ///
- /// let m = Command::new("prog")
- /// .arg(Arg::new("flag")
- /// .long("flag")
- /// .env("MY_FLAG_MULTI")
- /// .takes_value(true)
- /// .multiple_values(true)
- /// .use_value_delimiter(true))
- /// .get_matches_from(vec![
- /// "prog"
- /// ]);
- ///
- /// assert_eq!(m.values_of("flag").unwrap().collect::<Vec<_>>(), vec!["env1", "env2"]);
- /// ```
- /// [`ArgMatches::value_of`]: crate::ArgMatches::value_of()
- /// [`Arg::takes_value(true)`]: Arg::takes_value()
- /// [`Arg::use_value_delimiter(true)`]: Arg::use_value_delimiter()
- #[cfg(feature = "env")]
- #[inline]
- #[must_use]
- pub fn env(self, name: &'help str) -> Self {
- self.env_os(OsStr::new(name))
- }
-
- /// Read from `name` environment variable when argument is not present.
- ///
- /// See [`Arg::env`].
- #[cfg(feature = "env")]
- #[inline]
- #[must_use]
- pub fn env_os(mut self, name: &'help OsStr) -> Self {
- self.env = Some((name, env::var_os(name)));
- self
- }
-}
-
-/// # Help
-impl<'help> Arg<'help> {
- /// Sets the description of the argument for short help (`-h`).
- ///
- /// Typically, this is a short (one line) description of the arg.
- ///
- /// If [`Arg::long_help`] is not specified, this message will be displayed for `--help`.
- ///
- /// **NOTE:** Only `Arg::help` is used in completion script generation in order to be concise
- ///
- /// # Examples
- ///
- /// Any valid UTF-8 is allowed in the help text. The one exception is when one wishes to
- /// include a newline in the help text and have the following text be properly aligned with all
- /// the other help text.
- ///
- /// Setting `help` displays a short message to the side of the argument when the user passes
- /// `-h` or `--help` (by default).
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// let m = Command::new("prog")
- /// .arg(Arg::new("cfg")
- /// .long("config")
- /// .help("Some help text describing the --config arg"))
- /// .get_matches_from(vec![
- /// "prog", "--help"
- /// ]);
- /// ```
- ///
- /// The above example displays
- ///
- /// ```notrust
- /// helptest
- ///
- /// USAGE:
- /// helptest [OPTIONS]
- ///
- /// OPTIONS:
- /// --config Some help text describing the --config arg
- /// -h, --help Print help information
- /// -V, --version Print version information
- /// ```
- /// [`Arg::long_help`]: Arg::long_help()
- #[inline]
- #[must_use]
- pub fn help(mut self, h: impl Into<Option<&'help str>>) -> Self {
- self.help = h.into();
- self
- }
-
- /// Sets the description of the argument for long help (`--help`).
- ///
- /// Typically this a more detailed (multi-line) message
- /// that describes the arg.
- ///
- /// If [`Arg::help`] is not specified, this message will be displayed for `-h`.
- ///
- /// **NOTE:** Only [`Arg::help`] is used in completion script generation in order to be concise
- ///
- /// # Examples
- ///
- /// Any valid UTF-8 is allowed in the help text. The one exception is when one wishes to
- /// include a newline in the help text and have the following text be properly aligned with all
- /// the other help text.
- ///
- /// Setting `help` displays a short message to the side of the argument when the user passes
- /// `-h` or `--help` (by default).
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// let m = Command::new("prog")
- /// .arg(Arg::new("cfg")
- /// .long("config")
- /// .long_help(
- /// "The config file used by the myprog must be in JSON format
- /// with only valid keys and may not contain other nonsense
- /// that cannot be read by this program. Obviously I'm going on
- /// and on, so I'll stop now."))
- /// .get_matches_from(vec![
- /// "prog", "--help"
- /// ]);
- /// ```
- ///
- /// The above example displays
- ///
- /// ```text
- /// prog
- ///
- /// USAGE:
- /// prog [OPTIONS]
- ///
- /// OPTIONS:
- /// --config
- /// The config file used by the myprog must be in JSON format
- /// with only valid keys and may not contain other nonsense
- /// that cannot be read by this program. Obviously I'm going on
- /// and on, so I'll stop now.
- ///
- /// -h, --help
- /// Print help information
- ///
- /// -V, --version
- /// Print version information
- /// ```
- /// [`Arg::help`]: Arg::help()
- #[inline]
- #[must_use]
- pub fn long_help(mut self, h: impl Into<Option<&'help str>>) -> Self {
- self.long_help = h.into();
- self
- }
-
- /// Allows custom ordering of args within the help message.
- ///
- /// Args with a lower value will be displayed first in the help message. This is helpful when
- /// one would like to emphasise frequently used args, or prioritize those towards the top of
- /// the list. Args with duplicate display orders will be displayed in alphabetical order.
- ///
- /// **NOTE:** The default is 999 for all arguments.
- ///
- /// **NOTE:** This setting is ignored for [positional arguments] which are always displayed in
- /// [index] order.
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// let m = Command::new("prog")
- /// .arg(Arg::new("a") // Typically args are grouped alphabetically by name.
- /// // Args without a display_order have a value of 999 and are
- /// // displayed alphabetically with all other 999 valued args.
- /// .long("long-option")
- /// .short('o')
- /// .takes_value(true)
- /// .help("Some help and text"))
- /// .arg(Arg::new("b")
- /// .long("other-option")
- /// .short('O')
- /// .takes_value(true)
- /// .display_order(1) // In order to force this arg to appear *first*
- /// // all we have to do is give it a value lower than 999.
- /// // Any other args with a value of 1 will be displayed
- /// // alphabetically with this one...then 2 values, then 3, etc.
- /// .help("I should be first!"))
- /// .get_matches_from(vec![
- /// "prog", "--help"
- /// ]);
- /// ```
- ///
- /// The above example displays the following help message
- ///
- /// ```text
- /// cust-ord
- ///
- /// USAGE:
- /// cust-ord [OPTIONS]
- ///
- /// OPTIONS:
- /// -h, --help Print help information
- /// -V, --version Print version information
- /// -O, --other-option <b> I should be first!
- /// -o, --long-option <a> Some help and text
- /// ```
- /// [positional arguments]: Arg::index()
- /// [index]: Arg::index()
- #[inline]
- #[must_use]
- pub fn display_order(mut self, ord: usize) -> Self {
- self.disp_ord.set_explicit(ord);
- self
- }
-
- /// Override the [current] help section.
- ///
- /// [current]: crate::Command::help_heading
- #[inline]
- #[must_use]
- pub fn help_heading<O>(mut self, heading: O) -> Self
- where
- O: Into<Option<&'help str>>,
- {
- self.help_heading = Some(heading.into());
- self
- }
-
- /// Render the [help][Arg::help] on the line after the argument.
- ///
- /// This can be helpful for arguments with very long or complex help messages.
- /// This can also be helpful for arguments with very long flag names, or many/long value names.
- ///
- /// **NOTE:** To apply this setting to all arguments and subcommands, consider using
- /// [`crate::Command::next_line_help`]
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// let m = Command::new("prog")
- /// .arg(Arg::new("opt")
- /// .long("long-option-flag")
- /// .short('o')
- /// .takes_value(true)
- /// .next_line_help(true)
- /// .value_names(&["value1", "value2"])
- /// .help("Some really long help and complex\n\
- /// help that makes more sense to be\n\
- /// on a line after the option"))
- /// .get_matches_from(vec![
- /// "prog", "--help"
- /// ]);
- /// ```
- ///
- /// The above example displays the following help message
- ///
- /// ```text
- /// nlh
- ///
- /// USAGE:
- /// nlh [OPTIONS]
- ///
- /// OPTIONS:
- /// -h, --help Print help information
- /// -V, --version Print version information
- /// -o, --long-option-flag <value1> <value2>
- /// Some really long help and complex
- /// help that makes more sense to be
- /// on a line after the option
- /// ```
- #[inline]
- #[must_use]
- pub fn next_line_help(self, yes: bool) -> Self {
- if yes {
- self.setting(ArgSettings::NextLineHelp)
- } else {
- self.unset_setting(ArgSettings::NextLineHelp)
- }
- }
-
- /// Do not display the argument in help message.
- ///
- /// **NOTE:** This does **not** hide the argument from usage strings on error
- ///
- /// # Examples
- ///
- /// Setting `Hidden` will hide the argument when displaying help text
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// let m = Command::new("prog")
- /// .arg(Arg::new("cfg")
- /// .long("config")
- /// .hide(true)
- /// .help("Some help text describing the --config arg"))
- /// .get_matches_from(vec![
- /// "prog", "--help"
- /// ]);
- /// ```
- ///
- /// The above example displays
- ///
- /// ```text
- /// helptest
- ///
- /// USAGE:
- /// helptest [OPTIONS]
- ///
- /// OPTIONS:
- /// -h, --help Print help information
- /// -V, --version Print version information
- /// ```
- #[inline]
- #[must_use]
- pub fn hide(self, yes: bool) -> Self {
- if yes {
- self.setting(ArgSettings::Hidden)
- } else {
- self.unset_setting(ArgSettings::Hidden)
- }
- }
-
- /// Do not display the [possible values][crate::builder::ValueParser::possible_values] in the help message.
- ///
- /// This is useful for args with many values, or ones which are explained elsewhere in the
- /// help text.
- ///
- /// **NOTE:** Setting this requires [`Arg::takes_value`]
- ///
- /// To set this for all arguments, see
- /// [`Command::hide_possible_values`][crate::Command::hide_possible_values].
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// let m = Command::new("prog")
- /// .arg(Arg::new("mode")
- /// .long("mode")
- /// .value_parser(["fast", "slow"])
- /// .takes_value(true)
- /// .hide_possible_values(true));
- /// ```
- /// If we were to run the above program with `--help` the `[values: fast, slow]` portion of
- /// the help text would be omitted.
- #[inline]
- #[must_use]
- pub fn hide_possible_values(self, yes: bool) -> Self {
- if yes {
- self.setting(ArgSettings::HidePossibleValues)
- } else {
- self.unset_setting(ArgSettings::HidePossibleValues)
- }
- }
-
- /// Do not display the default value of the argument in the help message.
- ///
- /// This is useful when default behavior of an arg is explained elsewhere in the help text.
- ///
- /// **NOTE:** Setting this requires [`Arg::takes_value`]
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// let m = Command::new("connect")
- /// .arg(Arg::new("host")
- /// .long("host")
- /// .default_value("localhost")
- /// .takes_value(true)
- /// .hide_default_value(true));
- ///
- /// ```
- ///
- /// If we were to run the above program with `--help` the `[default: localhost]` portion of
- /// the help text would be omitted.
- #[inline]
- #[must_use]
- pub fn hide_default_value(self, yes: bool) -> Self {
- if yes {
- self.setting(ArgSettings::HideDefaultValue)
- } else {
- self.unset_setting(ArgSettings::HideDefaultValue)
- }
- }
-
- /// Do not display in help the environment variable name.
- ///
- /// This is useful when the variable option is explained elsewhere in the help text.
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// let m = Command::new("prog")
- /// .arg(Arg::new("mode")
- /// .long("mode")
- /// .env("MODE")
- /// .takes_value(true)
- /// .hide_env(true));
- /// ```
- ///
- /// If we were to run the above program with `--help` the `[env: MODE]` portion of the help
- /// text would be omitted.
- #[cfg(feature = "env")]
- #[inline]
- #[must_use]
- pub fn hide_env(self, yes: bool) -> Self {
- if yes {
- self.setting(ArgSettings::HideEnv)
- } else {
- self.unset_setting(ArgSettings::HideEnv)
- }
- }
-
- /// Do not display in help any values inside the associated ENV variables for the argument.
- ///
- /// This is useful when ENV vars contain sensitive values.
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// let m = Command::new("connect")
- /// .arg(Arg::new("host")
- /// .long("host")
- /// .env("CONNECT")
- /// .takes_value(true)
- /// .hide_env_values(true));
- ///
- /// ```
- ///
- /// If we were to run the above program with `$ CONNECT=super_secret connect --help` the
- /// `[default: CONNECT=super_secret]` portion of the help text would be omitted.
- #[cfg(feature = "env")]
- #[inline]
- #[must_use]
- pub fn hide_env_values(self, yes: bool) -> Self {
- if yes {
- self.setting(ArgSettings::HideEnvValues)
- } else {
- self.unset_setting(ArgSettings::HideEnvValues)
- }
- }
-
- /// Hides an argument from short help (`-h`).
- ///
- /// **NOTE:** This does **not** hide the argument from usage strings on error
- ///
- /// **NOTE:** Setting this option will cause next-line-help output style to be used
- /// when long help (`--help`) is called.
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// Arg::new("debug")
- /// .hide_short_help(true);
- /// ```
- ///
- /// Setting `hide_short_help(true)` will hide the argument when displaying short help text
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// let m = Command::new("prog")
- /// .arg(Arg::new("cfg")
- /// .long("config")
- /// .hide_short_help(true)
- /// .help("Some help text describing the --config arg"))
- /// .get_matches_from(vec![
- /// "prog", "-h"
- /// ]);
- /// ```
- ///
- /// The above example displays
- ///
- /// ```text
- /// helptest
- ///
- /// USAGE:
- /// helptest [OPTIONS]
- ///
- /// OPTIONS:
- /// -h, --help Print help information
- /// -V, --version Print version information
- /// ```
- ///
- /// However, when --help is called
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// let m = Command::new("prog")
- /// .arg(Arg::new("cfg")
- /// .long("config")
- /// .hide_short_help(true)
- /// .help("Some help text describing the --config arg"))
- /// .get_matches_from(vec![
- /// "prog", "--help"
- /// ]);
- /// ```
- ///
- /// Then the following would be displayed
- ///
- /// ```text
- /// helptest
- ///
- /// USAGE:
- /// helptest [OPTIONS]
- ///
- /// OPTIONS:
- /// --config Some help text describing the --config arg
- /// -h, --help Print help information
- /// -V, --version Print version information
- /// ```
- #[inline]
- #[must_use]
- pub fn hide_short_help(self, yes: bool) -> Self {
- if yes {
- self.setting(ArgSettings::HiddenShortHelp)
- } else {
- self.unset_setting(ArgSettings::HiddenShortHelp)
- }
- }
-
- /// Hides an argument from long help (`--help`).
- ///
- /// **NOTE:** This does **not** hide the argument from usage strings on error
- ///
- /// **NOTE:** Setting this option will cause next-line-help output style to be used
- /// when long help (`--help`) is called.
- ///
- /// # Examples
- ///
- /// Setting `hide_long_help(true)` will hide the argument when displaying long help text
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// let m = Command::new("prog")
- /// .arg(Arg::new("cfg")
- /// .long("config")
- /// .hide_long_help(true)
- /// .help("Some help text describing the --config arg"))
- /// .get_matches_from(vec![
- /// "prog", "--help"
- /// ]);
- /// ```
- ///
- /// The above example displays
- ///
- /// ```text
- /// helptest
- ///
- /// USAGE:
- /// helptest [OPTIONS]
- ///
- /// OPTIONS:
- /// -h, --help Print help information
- /// -V, --version Print version information
- /// ```
- ///
- /// However, when -h is called
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// let m = Command::new("prog")
- /// .arg(Arg::new("cfg")
- /// .long("config")
- /// .hide_long_help(true)
- /// .help("Some help text describing the --config arg"))
- /// .get_matches_from(vec![
- /// "prog", "-h"
- /// ]);
- /// ```
- ///
- /// Then the following would be displayed
- ///
- /// ```text
- /// helptest
- ///
- /// USAGE:
- /// helptest [OPTIONS]
- ///
- /// OPTIONS:
- /// --config Some help text describing the --config arg
- /// -h, --help Print help information
- /// -V, --version Print version information
- /// ```
- #[inline]
- #[must_use]
- pub fn hide_long_help(self, yes: bool) -> Self {
- if yes {
- self.setting(ArgSettings::HiddenLongHelp)
- } else {
- self.unset_setting(ArgSettings::HiddenLongHelp)
- }
- }
-}
-
-/// # Advanced Argument Relations
-impl<'help> Arg<'help> {
- /// The name of the [`ArgGroup`] the argument belongs to.
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// Arg::new("debug")
- /// .long("debug")
- /// .group("mode")
- /// # ;
- /// ```
- ///
- /// Multiple arguments can be a member of a single group and then the group checked as if it
- /// was one of said arguments.
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// let m = Command::new("prog")
- /// .arg(Arg::new("debug")
- /// .long("debug")
- /// .group("mode"))
- /// .arg(Arg::new("verbose")
- /// .long("verbose")
- /// .group("mode"))
- /// .get_matches_from(vec![
- /// "prog", "--debug"
- /// ]);
- /// assert!(m.contains_id("mode"));
- /// ```
- ///
- /// [`ArgGroup`]: crate::ArgGroup
- #[must_use]
- pub fn group<T: Key>(mut self, group_id: T) -> Self {
- self.groups.push(group_id.into());
- self
- }
-
- /// The names of [`ArgGroup`]'s the argument belongs to.
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// Arg::new("debug")
- /// .long("debug")
- /// .groups(&["mode", "verbosity"])
- /// # ;
- /// ```
- ///
- /// Arguments can be members of multiple groups and then the group checked as if it
- /// was one of said arguments.
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// let m = Command::new("prog")
- /// .arg(Arg::new("debug")
- /// .long("debug")
- /// .groups(&["mode", "verbosity"]))
- /// .arg(Arg::new("verbose")
- /// .long("verbose")
- /// .groups(&["mode", "verbosity"]))
- /// .get_matches_from(vec![
- /// "prog", "--debug"
- /// ]);
- /// assert!(m.contains_id("mode"));
- /// assert!(m.contains_id("verbosity"));
- /// ```
- ///
- /// [`ArgGroup`]: crate::ArgGroup
- #[must_use]
- pub fn groups<T: Key>(mut self, group_ids: &[T]) -> Self {
- self.groups.extend(group_ids.iter().map(Id::from));
- self
- }
-
- /// Specifies the value of the argument if `arg` has been used at runtime.
- ///
- /// If `val` is set to `None`, `arg` only needs to be present. If `val` is set to `"some-val"`
- /// then `arg` must be present at runtime **and** have the value `val`.
- ///
- /// If `default` is set to `None`, `default_value` will be removed.
- ///
- /// **NOTE:** This setting is perfectly compatible with [`Arg::default_value`] but slightly
- /// different. `Arg::default_value` *only* takes effect when the user has not provided this arg
- /// at runtime. This setting however only takes effect when the user has not provided a value at
- /// runtime **and** these other conditions are met as well. If you have set `Arg::default_value`
- /// and `Arg::default_value_if`, and the user **did not** provide this arg at runtime, nor were
- /// the conditions met for `Arg::default_value_if`, the `Arg::default_value` will be applied.
- ///
- /// **NOTE:** This implicitly sets [`Arg::takes_value(true)`].
- ///
- /// # Examples
- ///
- /// First we use the default value only if another arg is present at runtime.
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// let m = Command::new("prog")
- /// .arg(Arg::new("flag")
- /// .long("flag"))
- /// .arg(Arg::new("other")
- /// .long("other")
- /// .default_value_if("flag", None, Some("default")))
- /// .get_matches_from(vec![
- /// "prog", "--flag"
- /// ]);
- ///
- /// assert_eq!(m.value_of("other"), Some("default"));
- /// ```
- ///
- /// Next we run the same test, but without providing `--flag`.
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// let m = Command::new("prog")
- /// .arg(Arg::new("flag")
- /// .long("flag"))
- /// .arg(Arg::new("other")
- /// .long("other")
- /// .default_value_if("flag", None, Some("default")))
- /// .get_matches_from(vec![
- /// "prog"
- /// ]);
- ///
- /// assert_eq!(m.value_of("other"), None);
- /// ```
- ///
- /// Now lets only use the default value if `--opt` contains the value `special`.
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// let m = Command::new("prog")
- /// .arg(Arg::new("opt")
- /// .takes_value(true)
- /// .long("opt"))
- /// .arg(Arg::new("other")
- /// .long("other")
- /// .default_value_if("opt", Some("special"), Some("default")))
- /// .get_matches_from(vec![
- /// "prog", "--opt", "special"
- /// ]);
- ///
- /// assert_eq!(m.value_of("other"), Some("default"));
- /// ```
- ///
- /// We can run the same test and provide any value *other than* `special` and we won't get a
- /// default value.
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// let m = Command::new("prog")
- /// .arg(Arg::new("opt")
- /// .takes_value(true)
- /// .long("opt"))
- /// .arg(Arg::new("other")
- /// .long("other")
- /// .default_value_if("opt", Some("special"), Some("default")))
- /// .get_matches_from(vec![
- /// "prog", "--opt", "hahaha"
- /// ]);
- ///
- /// assert_eq!(m.value_of("other"), None);
- /// ```
- ///
- /// If we want to unset the default value for an Arg based on the presence or
- /// value of some other Arg.
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// let m = Command::new("prog")
- /// .arg(Arg::new("flag")
- /// .long("flag"))
- /// .arg(Arg::new("other")
- /// .long("other")
- /// .default_value("default")
- /// .default_value_if("flag", None, None))
- /// .get_matches_from(vec![
- /// "prog", "--flag"
- /// ]);
- ///
- /// assert_eq!(m.value_of("other"), None);
- /// ```
- /// [`Arg::takes_value(true)`]: Arg::takes_value()
- /// [`Arg::default_value`]: Arg::default_value()
- #[must_use]
- pub fn default_value_if<T: Key>(
- self,
- arg_id: T,
- val: Option<&'help str>,
- default: Option<&'help str>,
- ) -> Self {
- self.default_value_if_os(arg_id, val.map(OsStr::new), default.map(OsStr::new))
- }
-
- /// Provides a conditional default value in the exact same manner as [`Arg::default_value_if`]
- /// only using [`OsStr`]s instead.
- ///
- /// [`Arg::default_value_if`]: Arg::default_value_if()
- /// [`OsStr`]: std::ffi::OsStr
- #[must_use]
- pub fn default_value_if_os<T: Key>(
- mut self,
- arg_id: T,
- val: Option<&'help OsStr>,
- default: Option<&'help OsStr>,
- ) -> Self {
- self.default_vals_ifs
- .push((arg_id.into(), val.into(), default));
- self.takes_value(true)
- }
-
- /// Specifies multiple values and conditions in the same manner as [`Arg::default_value_if`].
- ///
- /// The method takes a slice of tuples in the `(arg, Option<val>, default)` format.
- ///
- /// **NOTE**: The conditions are stored in order and evaluated in the same order. I.e. the first
- /// if multiple conditions are true, the first one found will be applied and the ultimate value.
- ///
- /// # Examples
- ///
- /// First we use the default value only if another arg is present at runtime.
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// let m = Command::new("prog")
- /// .arg(Arg::new("flag")
- /// .long("flag"))
- /// .arg(Arg::new("opt")
- /// .long("opt")
- /// .takes_value(true))
- /// .arg(Arg::new("other")
- /// .long("other")
- /// .default_value_ifs(&[
- /// ("flag", None, Some("default")),
- /// ("opt", Some("channal"), Some("chan")),
- /// ]))
- /// .get_matches_from(vec![
- /// "prog", "--opt", "channal"
- /// ]);
- ///
- /// assert_eq!(m.value_of("other"), Some("chan"));
- /// ```
- ///
- /// Next we run the same test, but without providing `--flag`.
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// let m = Command::new("prog")
- /// .arg(Arg::new("flag")
- /// .long("flag"))
- /// .arg(Arg::new("other")
- /// .long("other")
- /// .default_value_ifs(&[
- /// ("flag", None, Some("default")),
- /// ("opt", Some("channal"), Some("chan")),
- /// ]))
- /// .get_matches_from(vec![
- /// "prog"
- /// ]);
- ///
- /// assert_eq!(m.value_of("other"), None);
- /// ```
- ///
- /// We can also see that these values are applied in order, and if more than one condition is
- /// true, only the first evaluated "wins"
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// let m = Command::new("prog")
- /// .arg(Arg::new("flag")
- /// .long("flag"))
- /// .arg(Arg::new("opt")
- /// .long("opt")
- /// .takes_value(true))
- /// .arg(Arg::new("other")
- /// .long("other")
- /// .default_value_ifs(&[
- /// ("flag", None, Some("default")),
- /// ("opt", Some("channal"), Some("chan")),
- /// ]))
- /// .get_matches_from(vec![
- /// "prog", "--opt", "channal", "--flag"
- /// ]);
- ///
- /// assert_eq!(m.value_of("other"), Some("default"));
- /// ```
- /// [`Arg::takes_value(true)`]: Arg::takes_value()
- /// [`Arg::default_value_if`]: Arg::default_value_if()
- #[must_use]
- pub fn default_value_ifs<T: Key>(
- mut self,
- ifs: &[(T, Option<&'help str>, Option<&'help str>)],
- ) -> Self {
- for (arg, val, default) in ifs {
- self = self.default_value_if_os(arg, val.map(OsStr::new), default.map(OsStr::new));
- }
- self
- }
-
- /// Provides multiple conditional default values in the exact same manner as
- /// [`Arg::default_value_ifs`] only using [`OsStr`]s instead.
- ///
- /// [`Arg::default_value_ifs`]: Arg::default_value_ifs()
- /// [`OsStr`]: std::ffi::OsStr
- #[must_use]
- pub fn default_value_ifs_os<T: Key>(
- mut self,
- ifs: &[(T, Option<&'help OsStr>, Option<&'help OsStr>)],
- ) -> Self {
- for (arg, val, default) in ifs {
- self = self.default_value_if_os(arg, *val, *default);
- }
- self
- }
-
- /// Set this arg as [required] as long as the specified argument is not present at runtime.
- ///
- /// **Pro Tip:** Using `Arg::required_unless_present` implies [`Arg::required`] and is therefore not
- /// mandatory to also set.
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::Arg;
- /// Arg::new("config")
- /// .required_unless_present("debug")
- /// # ;
- /// ```
- ///
- /// In the following example, the required argument is *not* provided,
- /// but it's not an error because the `unless` arg has been supplied.
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// let res = Command::new("prog")
- /// .arg(Arg::new("cfg")
- /// .required_unless_present("dbg")
- /// .takes_value(true)
- /// .long("config"))
- /// .arg(Arg::new("dbg")
- /// .long("debug"))
- /// .try_get_matches_from(vec![
- /// "prog", "--debug"
- /// ]);
- ///
- /// assert!(res.is_ok());
- /// ```
- ///
- /// Setting `Arg::required_unless_present(name)` and *not* supplying `name` or this arg is an error.
- ///
- /// ```rust
- /// # use clap::{Command, Arg, ErrorKind};
- /// let res = Command::new("prog")
- /// .arg(Arg::new("cfg")
- /// .required_unless_present("dbg")
- /// .takes_value(true)
- /// .long("config"))
- /// .arg(Arg::new("dbg")
- /// .long("debug"))
- /// .try_get_matches_from(vec![
- /// "prog"
- /// ]);
- ///
- /// assert!(res.is_err());
- /// assert_eq!(res.unwrap_err().kind(), ErrorKind::MissingRequiredArgument);
- /// ```
- /// [required]: Arg::required()
- #[must_use]
- pub fn required_unless_present<T: Key>(mut self, arg_id: T) -> Self {
- self.r_unless.push(arg_id.into());
- self
- }
-
- /// Sets this arg as [required] unless *all* of the specified arguments are present at runtime.
- ///
- /// In other words, parsing will succeed only if user either
- /// * supplies the `self` arg.
- /// * supplies *all* of the `names` arguments.
- ///
- /// **NOTE:** If you wish for this argument to only be required unless *any of* these args are
- /// present see [`Arg::required_unless_present_any`]
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::Arg;
- /// Arg::new("config")
- /// .required_unless_present_all(&["cfg", "dbg"])
- /// # ;
- /// ```
- ///
- /// In the following example, the required argument is *not* provided, but it's not an error
- /// because *all* of the `names` args have been supplied.
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// let res = Command::new("prog")
- /// .arg(Arg::new("cfg")
- /// .required_unless_present_all(&["dbg", "infile"])
- /// .takes_value(true)
- /// .long("config"))
- /// .arg(Arg::new("dbg")
- /// .long("debug"))
- /// .arg(Arg::new("infile")
- /// .short('i')
- /// .takes_value(true))
- /// .try_get_matches_from(vec![
- /// "prog", "--debug", "-i", "file"
- /// ]);
- ///
- /// assert!(res.is_ok());
- /// ```
- ///
- /// Setting [`Arg::required_unless_present_all(names)`] and *not* supplying
- /// either *all* of `unless` args or the `self` arg is an error.
- ///
- /// ```rust
- /// # use clap::{Command, Arg, ErrorKind};
- /// let res = Command::new("prog")
- /// .arg(Arg::new("cfg")
- /// .required_unless_present_all(&["dbg", "infile"])
- /// .takes_value(true)
- /// .long("config"))
- /// .arg(Arg::new("dbg")
- /// .long("debug"))
- /// .arg(Arg::new("infile")
- /// .short('i')
- /// .takes_value(true))
- /// .try_get_matches_from(vec![
- /// "prog"
- /// ]);
- ///
- /// assert!(res.is_err());
- /// assert_eq!(res.unwrap_err().kind(), ErrorKind::MissingRequiredArgument);
- /// ```
- /// [required]: Arg::required()
- /// [`Arg::required_unless_present_any`]: Arg::required_unless_present_any()
- /// [`Arg::required_unless_present_all(names)`]: Arg::required_unless_present_all()
- #[must_use]
- pub fn required_unless_present_all<T, I>(mut self, names: I) -> Self
- where
- I: IntoIterator<Item = T>,
- T: Key,
- {
- self.r_unless_all.extend(names.into_iter().map(Id::from));
- self
- }
-
- /// Sets this arg as [required] unless *any* of the specified arguments are present at runtime.
- ///
- /// In other words, parsing will succeed only if user either
- /// * supplies the `self` arg.
- /// * supplies *one or more* of the `unless` arguments.
- ///
- /// **NOTE:** If you wish for this argument to be required unless *all of* these args are
- /// present see [`Arg::required_unless_present_all`]
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::Arg;
- /// Arg::new("config")
- /// .required_unless_present_any(&["cfg", "dbg"])
- /// # ;
- /// ```
- ///
- /// Setting [`Arg::required_unless_present_any(names)`] requires that the argument be used at runtime
- /// *unless* *at least one of* the args in `names` are present. In the following example, the
- /// required argument is *not* provided, but it's not an error because one the `unless` args
- /// have been supplied.
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// let res = Command::new("prog")
- /// .arg(Arg::new("cfg")
- /// .required_unless_present_any(&["dbg", "infile"])
- /// .takes_value(true)
- /// .long("config"))
- /// .arg(Arg::new("dbg")
- /// .long("debug"))
- /// .arg(Arg::new("infile")
- /// .short('i')
- /// .takes_value(true))
- /// .try_get_matches_from(vec![
- /// "prog", "--debug"
- /// ]);
- ///
- /// assert!(res.is_ok());
- /// ```
- ///
- /// Setting [`Arg::required_unless_present_any(names)`] and *not* supplying *at least one of* `names`
- /// or this arg is an error.
- ///
- /// ```rust
- /// # use clap::{Command, Arg, ErrorKind};
- /// let res = Command::new("prog")
- /// .arg(Arg::new("cfg")
- /// .required_unless_present_any(&["dbg", "infile"])
- /// .takes_value(true)
- /// .long("config"))
- /// .arg(Arg::new("dbg")
- /// .long("debug"))
- /// .arg(Arg::new("infile")
- /// .short('i')
- /// .takes_value(true))
- /// .try_get_matches_from(vec![
- /// "prog"
- /// ]);
- ///
- /// assert!(res.is_err());
- /// assert_eq!(res.unwrap_err().kind(), ErrorKind::MissingRequiredArgument);
- /// ```
- /// [required]: Arg::required()
- /// [`Arg::required_unless_present_any(names)`]: Arg::required_unless_present_any()
- /// [`Arg::required_unless_present_all`]: Arg::required_unless_present_all()
- #[must_use]
- pub fn required_unless_present_any<T, I>(mut self, names: I) -> Self
- where
- I: IntoIterator<Item = T>,
- T: Key,
- {
- self.r_unless.extend(names.into_iter().map(Id::from));
- self
- }
-
- /// This argument is [required] only if the specified `arg` is present at runtime and its value
- /// equals `val`.
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::Arg;
- /// Arg::new("config")
- /// .required_if_eq("other_arg", "value")
- /// # ;
- /// ```
- ///
- /// ```rust
- /// # use clap::{Command, Arg, ErrorKind};
- /// let res = Command::new("prog")
- /// .arg(Arg::new("cfg")
- /// .takes_value(true)
- /// .required_if_eq("other", "special")
- /// .long("config"))
- /// .arg(Arg::new("other")
- /// .long("other")
- /// .takes_value(true))
- /// .try_get_matches_from(vec![
- /// "prog", "--other", "not-special"
- /// ]);
- ///
- /// assert!(res.is_ok()); // We didn't use --other=special, so "cfg" wasn't required
- ///
- /// let res = Command::new("prog")
- /// .arg(Arg::new("cfg")
- /// .takes_value(true)
- /// .required_if_eq("other", "special")
- /// .long("config"))
- /// .arg(Arg::new("other")
- /// .long("other")
- /// .takes_value(true))
- /// .try_get_matches_from(vec![
- /// "prog", "--other", "special"
- /// ]);
- ///
- /// // We did use --other=special so "cfg" had become required but was missing.
- /// assert!(res.is_err());
- /// assert_eq!(res.unwrap_err().kind(), ErrorKind::MissingRequiredArgument);
- ///
- /// let res = Command::new("prog")
- /// .arg(Arg::new("cfg")
- /// .takes_value(true)
- /// .required_if_eq("other", "special")
- /// .long("config"))
- /// .arg(Arg::new("other")
- /// .long("other")
- /// .takes_value(true))
- /// .try_get_matches_from(vec![
- /// "prog", "--other", "SPECIAL"
- /// ]);
- ///
- /// // By default, the comparison is case-sensitive, so "cfg" wasn't required
- /// assert!(res.is_ok());
- ///
- /// let res = Command::new("prog")
- /// .arg(Arg::new("cfg")
- /// .takes_value(true)
- /// .required_if_eq("other", "special")
- /// .long("config"))
- /// .arg(Arg::new("other")
- /// .long("other")
- /// .ignore_case(true)
- /// .takes_value(true))
- /// .try_get_matches_from(vec![
- /// "prog", "--other", "SPECIAL"
- /// ]);
- ///
- /// // However, case-insensitive comparisons can be enabled. This typically occurs when using Arg::possible_values().
- /// assert!(res.is_err());
- /// assert_eq!(res.unwrap_err().kind(), ErrorKind::MissingRequiredArgument);
- /// ```
- /// [`Arg::requires(name)`]: Arg::requires()
- /// [Conflicting]: Arg::conflicts_with()
- /// [required]: Arg::required()
- #[must_use]
- pub fn required_if_eq<T: Key>(mut self, arg_id: T, val: &'help str) -> Self {
- self.r_ifs.push((arg_id.into(), val));
- self
- }
-
- /// Specify this argument is [required] based on multiple conditions.
- ///
- /// The conditions are set up in a `(arg, val)` style tuple. The requirement will only become
- /// valid if one of the specified `arg`'s value equals its corresponding `val`.
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::Arg;
- /// Arg::new("config")
- /// .required_if_eq_any(&[
- /// ("extra", "val"),
- /// ("option", "spec")
- /// ])
- /// # ;
- /// ```
- ///
- /// Setting `Arg::required_if_eq_any(&[(arg, val)])` makes this arg required if any of the `arg`s
- /// are used at runtime and it's corresponding value is equal to `val`. If the `arg`'s value is
- /// anything other than `val`, this argument isn't required.
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// let res = Command::new("prog")
- /// .arg(Arg::new("cfg")
- /// .required_if_eq_any(&[
- /// ("extra", "val"),
- /// ("option", "spec")
- /// ])
- /// .takes_value(true)
- /// .long("config"))
- /// .arg(Arg::new("extra")
- /// .takes_value(true)
- /// .long("extra"))
- /// .arg(Arg::new("option")
- /// .takes_value(true)
- /// .long("option"))
- /// .try_get_matches_from(vec![
- /// "prog", "--option", "other"
- /// ]);
- ///
- /// assert!(res.is_ok()); // We didn't use --option=spec, or --extra=val so "cfg" isn't required
- /// ```
- ///
- /// Setting `Arg::required_if_eq_any(&[(arg, val)])` and having any of the `arg`s used with its
- /// value of `val` but *not* using this arg is an error.
- ///
- /// ```rust
- /// # use clap::{Command, Arg, ErrorKind};
- /// let res = Command::new("prog")
- /// .arg(Arg::new("cfg")
- /// .required_if_eq_any(&[
- /// ("extra", "val"),
- /// ("option", "spec")
- /// ])
- /// .takes_value(true)
- /// .long("config"))
- /// .arg(Arg::new("extra")
- /// .takes_value(true)
- /// .long("extra"))
- /// .arg(Arg::new("option")
- /// .takes_value(true)
- /// .long("option"))
- /// .try_get_matches_from(vec![
- /// "prog", "--option", "spec"
- /// ]);
- ///
- /// assert!(res.is_err());
- /// assert_eq!(res.unwrap_err().kind(), ErrorKind::MissingRequiredArgument);
- /// ```
- /// [`Arg::requires(name)`]: Arg::requires()
- /// [Conflicting]: Arg::conflicts_with()
- /// [required]: Arg::required()
- #[must_use]
- pub fn required_if_eq_any<T: Key>(mut self, ifs: &[(T, &'help str)]) -> Self {
- self.r_ifs
- .extend(ifs.iter().map(|(id, val)| (Id::from_ref(id), *val)));
- self
- }
-
- /// Specify this argument is [required] based on multiple conditions.
- ///
- /// The conditions are set up in a `(arg, val)` style tuple. The requirement will only become
- /// valid if every one of the specified `arg`'s value equals its corresponding `val`.
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::Arg;
- /// Arg::new("config")
- /// .required_if_eq_all(&[
- /// ("extra", "val"),
- /// ("option", "spec")
- /// ])
- /// # ;
- /// ```
- ///
- /// Setting `Arg::required_if_eq_all(&[(arg, val)])` makes this arg required if all of the `arg`s
- /// are used at runtime and every value is equal to its corresponding `val`. If the `arg`'s value is
- /// anything other than `val`, this argument isn't required.
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// let res = Command::new("prog")
- /// .arg(Arg::new("cfg")
- /// .required_if_eq_all(&[
- /// ("extra", "val"),
- /// ("option", "spec")
- /// ])
- /// .takes_value(true)
- /// .long("config"))
- /// .arg(Arg::new("extra")
- /// .takes_value(true)
- /// .long("extra"))
- /// .arg(Arg::new("option")
- /// .takes_value(true)
- /// .long("option"))
- /// .try_get_matches_from(vec![
- /// "prog", "--option", "spec"
- /// ]);
- ///
- /// assert!(res.is_ok()); // We didn't use --option=spec --extra=val so "cfg" isn't required
- /// ```
- ///
- /// Setting `Arg::required_if_eq_all(&[(arg, val)])` and having all of the `arg`s used with its
- /// value of `val` but *not* using this arg is an error.
- ///
- /// ```rust
- /// # use clap::{Command, Arg, ErrorKind};
- /// let res = Command::new("prog")
- /// .arg(Arg::new("cfg")
- /// .required_if_eq_all(&[
- /// ("extra", "val"),
- /// ("option", "spec")
- /// ])
- /// .takes_value(true)
- /// .long("config"))
- /// .arg(Arg::new("extra")
- /// .takes_value(true)
- /// .long("extra"))
- /// .arg(Arg::new("option")
- /// .takes_value(true)
- /// .long("option"))
- /// .try_get_matches_from(vec![
- /// "prog", "--extra", "val", "--option", "spec"
- /// ]);
- ///
- /// assert!(res.is_err());
- /// assert_eq!(res.unwrap_err().kind(), ErrorKind::MissingRequiredArgument);
- /// ```
- /// [required]: Arg::required()
- #[must_use]
- pub fn required_if_eq_all<T: Key>(mut self, ifs: &[(T, &'help str)]) -> Self {
- self.r_ifs_all
- .extend(ifs.iter().map(|(id, val)| (Id::from_ref(id), *val)));
- self
- }
-
- /// Require another argument if this arg was present at runtime and its value equals to `val`.
- ///
- /// This method takes `value, another_arg` pair. At runtime, clap will check
- /// if this arg (`self`) is present and its value equals to `val`.
- /// If it does, `another_arg` will be marked as required.
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::Arg;
- /// Arg::new("config")
- /// .requires_if("val", "arg")
- /// # ;
- /// ```
- ///
- /// Setting `Arg::requires_if(val, arg)` requires that the `arg` be used at runtime if the
- /// defining argument's value is equal to `val`. If the defining argument is anything other than
- /// `val`, the other argument isn't required.
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// let res = Command::new("prog")
- /// .arg(Arg::new("cfg")
- /// .takes_value(true)
- /// .requires_if("my.cfg", "other")
- /// .long("config"))
- /// .arg(Arg::new("other"))
- /// .try_get_matches_from(vec![
- /// "prog", "--config", "some.cfg"
- /// ]);
- ///
- /// assert!(res.is_ok()); // We didn't use --config=my.cfg, so other wasn't required
- /// ```
- ///
- /// Setting `Arg::requires_if(val, arg)` and setting the value to `val` but *not* supplying
- /// `arg` is an error.
- ///
- /// ```rust
- /// # use clap::{Command, Arg, ErrorKind};
- /// let res = Command::new("prog")
- /// .arg(Arg::new("cfg")
- /// .takes_value(true)
- /// .requires_if("my.cfg", "input")
- /// .long("config"))
- /// .arg(Arg::new("input"))
- /// .try_get_matches_from(vec![
- /// "prog", "--config", "my.cfg"
- /// ]);
- ///
- /// assert!(res.is_err());
- /// assert_eq!(res.unwrap_err().kind(), ErrorKind::MissingRequiredArgument);
- /// ```
- /// [`Arg::requires(name)`]: Arg::requires()
- /// [Conflicting]: Arg::conflicts_with()
- /// [override]: Arg::overrides_with()
- #[must_use]
- pub fn requires_if<T: Key>(mut self, val: &'help str, arg_id: T) -> Self {
- self.requires
- .push((ArgPredicate::Equals(OsStr::new(val)), arg_id.into()));
- self
- }
-
- /// Allows multiple conditional requirements.
- ///
- /// The requirement will only become valid if this arg's value equals `val`.
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::Arg;
- /// Arg::new("config")
- /// .requires_ifs(&[
- /// ("val", "arg"),
- /// ("other_val", "arg2"),
- /// ])
- /// # ;
- /// ```
- ///
- /// Setting `Arg::requires_ifs(&["val", "arg"])` requires that the `arg` be used at runtime if the
- /// defining argument's value is equal to `val`. If the defining argument's value is anything other
- /// than `val`, `arg` isn't required.
- ///
- /// ```rust
- /// # use clap::{Command, Arg, ErrorKind};
- /// let res = Command::new("prog")
- /// .arg(Arg::new("cfg")
- /// .takes_value(true)
- /// .requires_ifs(&[
- /// ("special.conf", "opt"),
- /// ("other.conf", "other"),
- /// ])
- /// .long("config"))
- /// .arg(Arg::new("opt")
- /// .long("option")
- /// .takes_value(true))
- /// .arg(Arg::new("other"))
- /// .try_get_matches_from(vec![
- /// "prog", "--config", "special.conf"
- /// ]);
- ///
- /// assert!(res.is_err()); // We used --config=special.conf so --option <val> is required
- /// assert_eq!(res.unwrap_err().kind(), ErrorKind::MissingRequiredArgument);
- /// ```
- /// [`Arg::requires(name)`]: Arg::requires()
- /// [Conflicting]: Arg::conflicts_with()
- /// [override]: Arg::overrides_with()
- #[must_use]
- pub fn requires_ifs<T: Key>(mut self, ifs: &[(&'help str, T)]) -> Self {
- self.requires.extend(
- ifs.iter()
- .map(|(val, arg)| (ArgPredicate::Equals(OsStr::new(*val)), Id::from(arg))),
- );
- self
- }
-
- /// Require these arguments names when this one is presen
- ///
- /// i.e. when using this argument, the following arguments *must* be present.
- ///
- /// **NOTE:** [Conflicting] rules and [override] rules take precedence over being required
- /// by default.
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::Arg;
- /// Arg::new("config")
- /// .requires_all(&["input", "output"])
- /// # ;
- /// ```
- ///
- /// Setting `Arg::requires_all(&[arg, arg2])` requires that all the arguments be used at
- /// runtime if the defining argument is used. If the defining argument isn't used, the other
- /// argument isn't required
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// let res = Command::new("prog")
- /// .arg(Arg::new("cfg")
- /// .takes_value(true)
- /// .requires("input")
- /// .long("config"))
- /// .arg(Arg::new("input"))
- /// .arg(Arg::new("output"))
- /// .try_get_matches_from(vec![
- /// "prog"
- /// ]);
- ///
- /// assert!(res.is_ok()); // We didn't use cfg, so input and output weren't required
- /// ```
- ///
- /// Setting `Arg::requires_all(&[arg, arg2])` and *not* supplying all the arguments is an
- /// error.
- ///
- /// ```rust
- /// # use clap::{Command, Arg, ErrorKind};
- /// let res = Command::new("prog")
- /// .arg(Arg::new("cfg")
- /// .takes_value(true)
- /// .requires_all(&["input", "output"])
- /// .long("config"))
- /// .arg(Arg::new("input"))
- /// .arg(Arg::new("output"))
- /// .try_get_matches_from(vec![
- /// "prog", "--config", "file.conf", "in.txt"
- /// ]);
- ///
- /// assert!(res.is_err());
- /// // We didn't use output
- /// assert_eq!(res.unwrap_err().kind(), ErrorKind::MissingRequiredArgument);
- /// ```
- /// [Conflicting]: Arg::conflicts_with()
- /// [override]: Arg::overrides_with()
- #[must_use]
- pub fn requires_all<T: Key>(mut self, names: &[T]) -> Self {
- self.requires
- .extend(names.iter().map(|s| (ArgPredicate::IsPresent, s.into())));
- self
- }
-
- /// This argument is mutually exclusive with the specified argument.
- ///
- /// **NOTE:** Conflicting rules take precedence over being required by default. Conflict rules
- /// only need to be set for one of the two arguments, they do not need to be set for each.
- ///
- /// **NOTE:** Defining a conflict is two-way, but does *not* need to defined for both arguments
- /// (i.e. if A conflicts with B, defining A.conflicts_with(B) is sufficient. You do not
- /// need to also do B.conflicts_with(A))
- ///
- /// **NOTE:** [`Arg::conflicts_with_all(names)`] allows specifying an argument which conflicts with more than one argument.
- ///
- /// **NOTE** [`Arg::exclusive(true)`] allows specifying an argument which conflicts with every other argument.
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::Arg;
- /// Arg::new("config")
- /// .conflicts_with("debug")
- /// # ;
- /// ```
- ///
- /// Setting conflicting argument, and having both arguments present at runtime is an error.
- ///
- /// ```rust
- /// # use clap::{Command, Arg, ErrorKind};
- /// let res = Command::new("prog")
- /// .arg(Arg::new("cfg")
- /// .takes_value(true)
- /// .conflicts_with("debug")
- /// .long("config"))
- /// .arg(Arg::new("debug")
- /// .long("debug"))
- /// .try_get_matches_from(vec![
- /// "prog", "--debug", "--config", "file.conf"
- /// ]);
- ///
- /// assert!(res.is_err());
- /// assert_eq!(res.unwrap_err().kind(), ErrorKind::ArgumentConflict);
- /// ```
- ///
- /// [`Arg::conflicts_with_all(names)`]: Arg::conflicts_with_all()
- /// [`Arg::exclusive(true)`]: Arg::exclusive()
- #[must_use]
- pub fn conflicts_with<T: Key>(mut self, arg_id: T) -> Self {
- self.blacklist.push(arg_id.into());
- self
- }
-
- /// This argument is mutually exclusive with the specified arguments.
- ///
- /// See [`Arg::conflicts_with`].
- ///
- /// **NOTE:** Conflicting rules take precedence over being required by default. Conflict rules
- /// only need to be set for one of the two arguments, they do not need to be set for each.
- ///
- /// **NOTE:** Defining a conflict is two-way, but does *not* need to defined for both arguments
- /// (i.e. if A conflicts with B, defining A.conflicts_with(B) is sufficient. You do not need
- /// need to also do B.conflicts_with(A))
- ///
- /// **NOTE:** [`Arg::exclusive(true)`] allows specifying an argument which conflicts with every other argument.
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::Arg;
- /// Arg::new("config")
- /// .conflicts_with_all(&["debug", "input"])
- /// # ;
- /// ```
- ///
- /// Setting conflicting argument, and having any of the arguments present at runtime with a
- /// conflicting argument is an error.
- ///
- /// ```rust
- /// # use clap::{Command, Arg, ErrorKind};
- /// let res = Command::new("prog")
- /// .arg(Arg::new("cfg")
- /// .takes_value(true)
- /// .conflicts_with_all(&["debug", "input"])
- /// .long("config"))
- /// .arg(Arg::new("debug")
- /// .long("debug"))
- /// .arg(Arg::new("input"))
- /// .try_get_matches_from(vec![
- /// "prog", "--config", "file.conf", "file.txt"
- /// ]);
- ///
- /// assert!(res.is_err());
- /// assert_eq!(res.unwrap_err().kind(), ErrorKind::ArgumentConflict);
- /// ```
- /// [`Arg::conflicts_with`]: Arg::conflicts_with()
- /// [`Arg::exclusive(true)`]: Arg::exclusive()
- #[must_use]
- pub fn conflicts_with_all(mut self, names: &[&str]) -> Self {
- self.blacklist.extend(names.iter().copied().map(Id::from));
- self
- }
-
- /// Sets an overridable argument.
- ///
- /// i.e. this argument and the following argument
- /// will override each other in POSIX style (whichever argument was specified at runtime
- /// **last** "wins")
- ///
- /// **NOTE:** When an argument is overridden it is essentially as if it never was used, any
- /// conflicts, requirements, etc. are evaluated **after** all "overrides" have been removed
- ///
- /// **NOTE:** Overriding an argument implies they [conflict][Arg::conflicts_with`].
- ///
- /// **WARNING:** Positional arguments and options which accept
- /// [`Arg::multiple_occurrences`] cannot override themselves (or we
- /// would never be able to advance to the next positional). If a positional
- /// argument or option with one of the [`Arg::multiple_occurrences`]
- /// settings lists itself as an override, it is simply ignored.
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Command, arg};
- /// let m = Command::new("prog")
- /// .arg(arg!(-f --flag "some flag")
- /// .conflicts_with("debug"))
- /// .arg(arg!(-d --debug "other flag"))
- /// .arg(arg!(-c --color "third flag")
- /// .overrides_with("flag"))
- /// .get_matches_from(vec![
- /// "prog", "-f", "-d", "-c"]);
- /// // ^~~~~~~~~~~~^~~~~ flag is overridden by color
- ///
- /// assert!(m.is_present("color"));
- /// assert!(m.is_present("debug")); // even though flag conflicts with debug, it's as if flag
- /// // was never used because it was overridden with color
- /// assert!(!m.is_present("flag"));
- /// ```
- /// Care must be taken when using this setting, and having an arg override with itself. This
- /// is common practice when supporting things like shell aliases, config files, etc.
- /// However, when combined with multiple values, it can get dicy.
- /// Here is how clap handles such situations:
- ///
- /// When a flag overrides itself, it's as if the flag was only ever used once (essentially
- /// preventing a "Unexpected multiple usage" error):
- ///
- /// ```rust
- /// # use clap::{Command, arg};
- /// let m = Command::new("posix")
- /// .arg(arg!(--flag "some flag").overrides_with("flag"))
- /// .get_matches_from(vec!["posix", "--flag", "--flag"]);
- /// assert!(m.is_present("flag"));
- /// ```
- ///
- /// Making an arg [`Arg::multiple_occurrences`] and override itself
- /// is essentially meaningless. Therefore clap ignores an override of self
- /// if it's a flag and it already accepts multiple occurrences.
- ///
- /// ```
- /// # use clap::{Command, arg};
- /// let m = Command::new("posix")
- /// .arg(arg!(--flag ... "some flag").overrides_with("flag"))
- /// .get_matches_from(vec!["", "--flag", "--flag", "--flag", "--flag"]);
- /// assert!(m.is_present("flag"));
- /// ```
- ///
- /// Now notice with options (which *do not* set
- /// [`Arg::multiple_occurrences`]), it's as if only the last
- /// occurrence happened.
- ///
- /// ```
- /// # use clap::{Command, arg};
- /// let m = Command::new("posix")
- /// .arg(arg!(--opt <val> "some option").overrides_with("opt"))
- /// .get_matches_from(vec!["", "--opt=some", "--opt=other"]);
- /// assert!(m.is_present("opt"));
- /// assert_eq!(m.value_of("opt"), Some("other"));
- /// ```
- ///
- /// This will also work when [`Arg::multiple_values`] is enabled:
- ///
- /// ```
- /// # use clap::{Command, Arg};
- /// let m = Command::new("posix")
- /// .arg(
- /// Arg::new("opt")
- /// .long("opt")
- /// .takes_value(true)
- /// .multiple_values(true)
- /// .overrides_with("opt")
- /// )
- /// .get_matches_from(vec!["", "--opt", "1", "2", "--opt", "3", "4", "5"]);
- /// assert!(m.is_present("opt"));
- /// assert_eq!(m.values_of("opt").unwrap().collect::<Vec<_>>(), &["3", "4", "5"]);
- /// ```
- ///
- /// Just like flags, options with [`Arg::multiple_occurrences`] set
- /// will ignore the "override self" setting.
- ///
- /// ```
- /// # use clap::{Command, arg};
- /// let m = Command::new("posix")
- /// .arg(arg!(--opt <val> ... "some option")
- /// .multiple_values(true)
- /// .overrides_with("opt"))
- /// .get_matches_from(vec!["", "--opt", "first", "over", "--opt", "other", "val"]);
- /// assert!(m.is_present("opt"));
- /// assert_eq!(m.values_of("opt").unwrap().collect::<Vec<_>>(), &["first", "over", "other", "val"]);
- /// ```
- #[must_use]
- pub fn overrides_with<T: Key>(mut self, arg_id: T) -> Self {
- self.overrides.push(arg_id.into());
- self
- }
-
- /// Sets multiple mutually overridable arguments by name.
- ///
- /// i.e. this argument and the following argument will override each other in POSIX style
- /// (whichever argument was specified at runtime **last** "wins")
- ///
- /// **NOTE:** When an argument is overridden it is essentially as if it never was used, any
- /// conflicts, requirements, etc. are evaluated **after** all "overrides" have been removed
- ///
- /// **NOTE:** Overriding an argument implies they [conflict][Arg::conflicts_with_all`].
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Command, arg};
- /// let m = Command::new("prog")
- /// .arg(arg!(-f --flag "some flag")
- /// .conflicts_with("color"))
- /// .arg(arg!(-d --debug "other flag"))
- /// .arg(arg!(-c --color "third flag")
- /// .overrides_with_all(&["flag", "debug"]))
- /// .get_matches_from(vec![
- /// "prog", "-f", "-d", "-c"]);
- /// // ^~~~~~^~~~~~~~~ flag and debug are overridden by color
- ///
- /// assert!(m.is_present("color")); // even though flag conflicts with color, it's as if flag
- /// // and debug were never used because they were overridden
- /// // with color
- /// assert!(!m.is_present("debug"));
- /// assert!(!m.is_present("flag"));
- /// ```
- #[must_use]
- pub fn overrides_with_all<T: Key>(mut self, names: &[T]) -> Self {
- self.overrides.extend(names.iter().map(Id::from));
- self
- }
-}
-
-/// # Reflection
-impl<'help> Arg<'help> {
- /// Get the name of the argument
- #[inline]
- pub fn get_id(&self) -> &'help str {
- self.name
- }
-
- /// Deprecated, replaced with [`Arg::get_id`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.1.0", note = "Replaced with `Arg::get_id`")
- )]
- pub fn get_name(&self) -> &'help str {
- self.get_id()
- }
-
- /// Get the help specified for this argument, if any
- #[inline]
- pub fn get_help(&self) -> Option<&'help str> {
- self.help
- }
-
- /// Get the long help specified for this argument, if any
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::Arg;
- /// let arg = Arg::new("foo").long_help("long help");
- /// assert_eq!(Some("long help"), arg.get_long_help());
- /// ```
- ///
- #[inline]
- pub fn get_long_help(&self) -> Option<&'help str> {
- self.long_help
- }
-
- /// Get the help heading specified for this argument, if any
- #[inline]
- pub fn get_help_heading(&self) -> Option<&'help str> {
- self.help_heading.unwrap_or_default()
- }
-
- /// Get the short option name for this argument, if any
- #[inline]
- pub fn get_short(&self) -> Option<char> {
- self.short
- }
-
- /// Get visible short aliases for this argument, if any
- #[inline]
- pub fn get_visible_short_aliases(&self) -> Option<Vec<char>> {
- if self.short_aliases.is_empty() {
- None
- } else {
- Some(
- self.short_aliases
- .iter()
- .filter_map(|(c, v)| if *v { Some(c) } else { None })
- .copied()
- .collect(),
- )
- }
- }
-
- /// Get *all* short aliases for this argument, if any, both visible and hidden.
- #[inline]
- pub fn get_all_short_aliases(&self) -> Option<Vec<char>> {
- if self.short_aliases.is_empty() {
- None
- } else {
- Some(self.short_aliases.iter().map(|(s, _)| s).copied().collect())
- }
- }
-
- /// Get the short option name and its visible aliases, if any
- #[inline]
- pub fn get_short_and_visible_aliases(&self) -> Option<Vec<char>> {
- let mut shorts = match self.short {
- Some(short) => vec![short],
- None => return None,
- };
- if let Some(aliases) = self.get_visible_short_aliases() {
- shorts.extend(aliases);
- }
- Some(shorts)
- }
-
- /// Get the long option name for this argument, if any
- #[inline]
- pub fn get_long(&self) -> Option<&'help str> {
- self.long
- }
-
- /// Get visible aliases for this argument, if any
- #[inline]
- pub fn get_visible_aliases(&self) -> Option<Vec<&'help str>> {
- if self.aliases.is_empty() {
- None
- } else {
- Some(
- self.aliases
- .iter()
- .filter_map(|(s, v)| if *v { Some(s) } else { None })
- .copied()
- .collect(),
- )
- }
- }
-
- /// Get *all* aliases for this argument, if any, both visible and hidden.
- #[inline]
- pub fn get_all_aliases(&self) -> Option<Vec<&'help str>> {
- if self.aliases.is_empty() {
- None
- } else {
- Some(self.aliases.iter().map(|(s, _)| s).copied().collect())
- }
- }
-
- /// Get the long option name and its visible aliases, if any
- #[inline]
- pub fn get_long_and_visible_aliases(&self) -> Option<Vec<&'help str>> {
- let mut longs = match self.long {
- Some(long) => vec![long],
- None => return None,
- };
- if let Some(aliases) = self.get_visible_aliases() {
- longs.extend(aliases);
- }
- Some(longs)
- }
-
- /// Deprecated, replaced with [`Arg::get_value_parser().possible_values()`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.2.0",
- note = "Replaced with `Arg::get_value_parser().possible_values()`"
- )
- )]
- pub fn get_possible_values(&self) -> Option<&[PossibleValue<'help>]> {
- if self.possible_vals.is_empty() {
- None
- } else {
- Some(&self.possible_vals)
- }
- }
-
- pub(crate) fn get_possible_values2(&self) -> Vec<PossibleValue<'help>> {
- #![allow(deprecated)]
- if !self.is_takes_value_set() {
- vec![]
- } else if let Some(pvs) = self.get_possible_values() {
- // Check old first in case the user explicitly set possible values and the derive inferred
- // a `ValueParser` with some.
- pvs.to_vec()
- } else {
- self.get_value_parser()
- .possible_values()
- .map(|pvs| pvs.collect())
- .unwrap_or_default()
- }
- }
-
- /// Get the names of values for this argument.
- #[inline]
- pub fn get_value_names(&self) -> Option<&[&'help str]> {
- if self.val_names.is_empty() {
- None
- } else {
- Some(&self.val_names)
- }
- }
-
- /// Get the number of values for this argument.
- #[inline]
- pub fn get_num_vals(&self) -> Option<usize> {
- self.num_vals
- }
-
- /// Get the delimiter between multiple values
- #[inline]
- pub fn get_value_delimiter(&self) -> Option<char> {
- self.val_delim
- }
-
- /// Get the index of this argument, if any
- #[inline]
- pub fn get_index(&self) -> Option<usize> {
- self.index
- }
-
- /// Get the value hint of this argument
- pub fn get_value_hint(&self) -> ValueHint {
- self.value_hint.unwrap_or_else(|| {
- if self.is_takes_value_set() {
- let type_id = self.get_value_parser().type_id();
- if type_id == crate::parser::AnyValueId::of::<std::path::PathBuf>() {
- ValueHint::AnyPath
- } else {
- ValueHint::default()
- }
- } else {
- ValueHint::default()
- }
- })
- }
-
- /// Deprecated, replaced with [`Arg::is_global_set`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.1.0", note = "Replaced with `Arg::is_global_set`")
- )]
- pub fn get_global(&self) -> bool {
- self.is_global_set()
- }
-
- /// Get the environment variable name specified for this argument, if any
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use std::ffi::OsStr;
- /// # use clap::Arg;
- /// let arg = Arg::new("foo").env("ENVIRONMENT");
- /// assert_eq!(Some(OsStr::new("ENVIRONMENT")), arg.get_env());
- /// ```
- #[cfg(feature = "env")]
- pub fn get_env(&self) -> Option<&OsStr> {
- self.env.as_ref().map(|x| x.0)
- }
-
- /// Get the default values specified for this argument, if any
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::Arg;
- /// let arg = Arg::new("foo").default_value("default value");
- /// assert_eq!(&["default value"], arg.get_default_values());
- /// ```
- pub fn get_default_values(&self) -> &[&OsStr] {
- &self.default_vals
- }
-
- /// Checks whether this argument is a positional or not.
- ///
- /// # Examples
- ///
- /// ```
- /// # use clap::Arg;
- /// let arg = Arg::new("foo");
- /// assert_eq!(true, arg.is_positional());
- ///
- /// let arg = Arg::new("foo").long("foo");
- /// assert_eq!(false, arg.is_positional());
- /// ```
- pub fn is_positional(&self) -> bool {
- self.long.is_none() && self.short.is_none()
- }
-
- /// Reports whether [`Arg::required`] is set
- pub fn is_required_set(&self) -> bool {
- self.is_set(ArgSettings::Required)
- }
-
- /// Report whether [`Arg::multiple_values`] is set
- pub fn is_multiple_values_set(&self) -> bool {
- self.is_set(ArgSettings::MultipleValues)
- }
-
- /// [`Arg::multiple_occurrences`] is going away ([Issue #3772](https://github.com/clap-rs/clap/issues/3772))
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.2.0", note = "`multiple_occurrences` away (Issue #3772)")
- )]
- pub fn is_multiple_occurrences_set(&self) -> bool {
- self.is_set(ArgSettings::MultipleOccurrences)
- }
-
- /// Report whether [`Arg::is_takes_value_set`] is set
- pub fn is_takes_value_set(&self) -> bool {
- self.is_set(ArgSettings::TakesValue)
- }
-
- /// Report whether [`Arg::allow_hyphen_values`] is set
- pub fn is_allow_hyphen_values_set(&self) -> bool {
- self.is_set(ArgSettings::AllowHyphenValues)
- }
-
- /// Deprecated, replaced with [`Arg::get_value_parser()`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.2.0", note = "Replaced with `Arg::get_value_parser()`")
- )]
- pub fn is_forbid_empty_values_set(&self) -> bool {
- self.is_set(ArgSettings::ForbidEmptyValues)
- }
-
- /// Deprecated, replaced with [`Arg::get_value_parser()`
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.2.0", note = "Replaced with `Arg::get_value_parser()`")
- )]
- pub fn is_allow_invalid_utf8_set(&self) -> bool {
- self.is_set(ArgSettings::AllowInvalidUtf8)
- }
-
- /// Behavior when parsing the argument
- pub fn get_action(&self) -> &super::ArgAction {
- const DEFAULT: super::ArgAction = super::ArgAction::StoreValue;
- self.action.as_ref().unwrap_or(&DEFAULT)
- }
-
- /// Configured parser for argument values
- ///
- /// # Example
- ///
- /// ```rust
- /// let cmd = clap::Command::new("raw")
- /// .arg(
- /// clap::Arg::new("port")
- /// .value_parser(clap::value_parser!(usize))
- /// );
- /// let value_parser = cmd.get_arguments()
- /// .find(|a| a.get_id() == "port").unwrap()
- /// .get_value_parser();
- /// println!("{:?}", value_parser);
- /// ```
- pub fn get_value_parser(&self) -> &super::ValueParser {
- if let Some(value_parser) = self.value_parser.as_ref() {
- value_parser
- } else if self.is_allow_invalid_utf8_set() {
- static DEFAULT: super::ValueParser = super::ValueParser::os_string();
- &DEFAULT
- } else {
- static DEFAULT: super::ValueParser = super::ValueParser::string();
- &DEFAULT
- }
- }
-
- /// Report whether [`Arg::global`] is set
- pub fn is_global_set(&self) -> bool {
- self.is_set(ArgSettings::Global)
- }
-
- /// Report whether [`Arg::next_line_help`] is set
- pub fn is_next_line_help_set(&self) -> bool {
- self.is_set(ArgSettings::NextLineHelp)
- }
-
- /// Report whether [`Arg::hide`] is set
- pub fn is_hide_set(&self) -> bool {
- self.is_set(ArgSettings::Hidden)
- }
-
- /// Report whether [`Arg::hide_default_value`] is set
- pub fn is_hide_default_value_set(&self) -> bool {
- self.is_set(ArgSettings::HideDefaultValue)
- }
-
- /// Report whether [`Arg::hide_possible_values`] is set
- pub fn is_hide_possible_values_set(&self) -> bool {
- self.is_set(ArgSettings::HidePossibleValues)
- }
-
- /// Report whether [`Arg::hide_env`] is set
- #[cfg(feature = "env")]
- pub fn is_hide_env_set(&self) -> bool {
- self.is_set(ArgSettings::HideEnv)
- }
-
- /// Report whether [`Arg::hide_env_values`] is set
- #[cfg(feature = "env")]
- pub fn is_hide_env_values_set(&self) -> bool {
- self.is_set(ArgSettings::HideEnvValues)
- }
-
- /// Report whether [`Arg::hide_short_help`] is set
- pub fn is_hide_short_help_set(&self) -> bool {
- self.is_set(ArgSettings::HiddenShortHelp)
- }
-
- /// Report whether [`Arg::hide_long_help`] is set
- pub fn is_hide_long_help_set(&self) -> bool {
- self.is_set(ArgSettings::HiddenLongHelp)
- }
-
- /// Report whether [`Arg::use_value_delimiter`] is set
- pub fn is_use_value_delimiter_set(&self) -> bool {
- self.is_set(ArgSettings::UseValueDelimiter)
- }
-
- /// Report whether [`Arg::require_value_delimiter`] is set
- pub fn is_require_value_delimiter_set(&self) -> bool {
- self.is_set(ArgSettings::RequireDelimiter)
- }
-
- /// Report whether [`Arg::require_equals`] is set
- pub fn is_require_equals_set(&self) -> bool {
- self.is_set(ArgSettings::RequireEquals)
- }
-
- /// Reports whether [`Arg::exclusive`] is set
- pub fn is_exclusive_set(&self) -> bool {
- self.is_set(ArgSettings::Exclusive)
- }
-
- /// Reports whether [`Arg::last`] is set
- pub fn is_last_set(&self) -> bool {
- self.is_set(ArgSettings::Last)
- }
-
- /// Reports whether [`Arg::ignore_case`] is set
- pub fn is_ignore_case_set(&self) -> bool {
- self.is_set(ArgSettings::IgnoreCase)
- }
-}
-
-/// # Deprecated
-impl<'help> Arg<'help> {
- /// Deprecated, replaced with [`Arg::new`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.0.0", note = "Replaced with `Arg::new`")
- )]
- #[doc(hidden)]
- pub fn with_name<S: Into<&'help str>>(n: S) -> Self {
- Self::new(n)
- }
-
- /// Deprecated in [Issue #3087](https://github.com/clap-rs/clap/issues/3087), maybe [`clap::Parser`][crate::Parser] would fit your use case?
- #[cfg(feature = "yaml")]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.0.0",
- note = "Deprecated in Issue #3087, maybe clap::Parser would fit your use case?"
- )
- )]
- #[doc(hidden)]
- pub fn from_yaml(y: &'help Yaml) -> Self {
- #![allow(deprecated)]
- let yaml_file_hash = y.as_hash().expect("YAML file must be a hash");
- // We WANT this to panic on error...so expect() is good.
- let (name_yaml, yaml) = yaml_file_hash
- .iter()
- .next()
- .expect("There must be one arg in the YAML file");
- let name_str = name_yaml.as_str().expect("Arg name must be a string");
- let mut a = Arg::new(name_str);
-
- for (k, v) in yaml.as_hash().expect("Arg must be a hash") {
- a = match k.as_str().expect("Arg fields must be strings") {
- "short" => yaml_to_char!(a, v, short),
- "long" => yaml_to_str!(a, v, long),
- "aliases" => yaml_vec_or_str!(a, v, alias),
- "help" => yaml_to_str!(a, v, help),
- "long_help" => yaml_to_str!(a, v, long_help),
- "required" => yaml_to_bool!(a, v, required),
- "required_if" => yaml_tuple2!(a, v, required_if_eq),
- "required_ifs" => yaml_tuple2!(a, v, required_if_eq),
- "takes_value" => yaml_to_bool!(a, v, takes_value),
- "index" => yaml_to_usize!(a, v, index),
- "global" => yaml_to_bool!(a, v, global),
- "multiple" => yaml_to_bool!(a, v, multiple),
- "hidden" => yaml_to_bool!(a, v, hide),
- "next_line_help" => yaml_to_bool!(a, v, next_line_help),
- "group" => yaml_to_str!(a, v, group),
- "number_of_values" => yaml_to_usize!(a, v, number_of_values),
- "max_values" => yaml_to_usize!(a, v, max_values),
- "min_values" => yaml_to_usize!(a, v, min_values),
- "value_name" => yaml_to_str!(a, v, value_name),
- "use_delimiter" => yaml_to_bool!(a, v, use_delimiter),
- "allow_hyphen_values" => yaml_to_bool!(a, v, allow_hyphen_values),
- "last" => yaml_to_bool!(a, v, last),
- "require_delimiter" => yaml_to_bool!(a, v, require_delimiter),
- "value_delimiter" => yaml_to_char!(a, v, value_delimiter),
- "required_unless" => yaml_to_str!(a, v, required_unless_present),
- "display_order" => yaml_to_usize!(a, v, display_order),
- "default_value" => yaml_to_str!(a, v, default_value),
- "default_value_if" => yaml_tuple3!(a, v, default_value_if),
- "default_value_ifs" => yaml_tuple3!(a, v, default_value_if),
- #[cfg(feature = "env")]
- "env" => yaml_to_str!(a, v, env),
- "value_names" => yaml_vec_or_str!(a, v, value_name),
- "groups" => yaml_vec_or_str!(a, v, group),
- "requires" => yaml_vec_or_str!(a, v, requires),
- "requires_if" => yaml_tuple2!(a, v, requires_if),
- "requires_ifs" => yaml_tuple2!(a, v, requires_if),
- "conflicts_with" => yaml_vec_or_str!(a, v, conflicts_with),
- "overrides_with" => yaml_to_str!(a, v, overrides_with),
- "possible_values" => yaml_vec_or_str!(a, v, possible_value),
- "case_insensitive" => yaml_to_bool!(a, v, ignore_case),
- "required_unless_one" => yaml_vec!(a, v, required_unless_present_any),
- "required_unless_all" => yaml_vec!(a, v, required_unless_present_all),
- s => {
- panic!(
- "Unknown setting '{}' in YAML file for arg '{}'",
- s, name_str
- )
- }
- }
- }
-
- a
- }
-
- /// Deprecated in [Issue #3086](https://github.com/clap-rs/clap/issues/3086), see [`arg!`][crate::arg!].
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.0.0", note = "Deprecated in Issue #3086, see `clap::arg!")
- )]
- #[doc(hidden)]
- pub fn from_usage(u: &'help str) -> Self {
- UsageParser::from_usage(u).parse()
- }
-
- /// Deprecated, replaced with [`Arg::required_unless_present`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.0.0", note = "Replaced with `Arg::required_unless_present`")
- )]
- #[doc(hidden)]
- #[must_use]
- pub fn required_unless<T: Key>(self, arg_id: T) -> Self {
- self.required_unless_present(arg_id)
- }
-
- /// Deprecated, replaced with [`Arg::required_unless_present_all`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.0.0",
- note = "Replaced with `Arg::required_unless_present_all`"
- )
- )]
- #[doc(hidden)]
- #[must_use]
- pub fn required_unless_all<T, I>(self, names: I) -> Self
- where
- I: IntoIterator<Item = T>,
- T: Key,
- {
- self.required_unless_present_all(names)
- }
-
- /// Deprecated, replaced with [`Arg::required_unless_present_any`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.0.0",
- note = "Replaced with `Arg::required_unless_present_any`"
- )
- )]
- #[doc(hidden)]
- #[must_use]
- pub fn required_unless_one<T, I>(self, names: I) -> Self
- where
- I: IntoIterator<Item = T>,
- T: Key,
- {
- self.required_unless_present_any(names)
- }
-
- /// Deprecated, replaced with [`Arg::required_if_eq`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.0.0", note = "Replaced with `Arg::required_if_eq`")
- )]
- #[doc(hidden)]
- #[must_use]
- pub fn required_if<T: Key>(self, arg_id: T, val: &'help str) -> Self {
- self.required_if_eq(arg_id, val)
- }
-
- /// Deprecated, replaced with [`Arg::required_if_eq_any`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.0.0", note = "Replaced with `Arg::required_if_eq_any`")
- )]
- #[doc(hidden)]
- #[must_use]
- pub fn required_ifs<T: Key>(self, ifs: &[(T, &'help str)]) -> Self {
- self.required_if_eq_any(ifs)
- }
-
- /// Deprecated, replaced with [`Arg::hide`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.0.0", note = "Replaced with `Arg::hide`")
- )]
- #[doc(hidden)]
- #[inline]
- #[must_use]
- pub fn hidden(self, yes: bool) -> Self {
- self.hide(yes)
- }
-
- /// Deprecated, replaced with [`Arg::ignore_case`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.0.0", note = "Replaced with `Arg::ignore_case`")
- )]
- #[doc(hidden)]
- #[inline]
- #[must_use]
- pub fn case_insensitive(self, yes: bool) -> Self {
- self.ignore_case(yes)
- }
-
- /// Deprecated, replaced with [`Arg::forbid_empty_values`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.0.0", note = "Replaced with `Arg::forbid_empty_values`")
- )]
- #[doc(hidden)]
- #[must_use]
- pub fn empty_values(self, yes: bool) -> Self {
- self.forbid_empty_values(!yes)
- }
-
- /// Deprecated, replaced with [`Arg::multiple_occurrences`] (most likely what you want) and
- /// [`Arg::multiple_values`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.0.0",
- note = "Split into `Arg::multiple_occurrences` (most likely what you want) and `Arg::multiple_values`"
- )
- )]
- #[doc(hidden)]
- #[must_use]
- pub fn multiple(self, yes: bool) -> Self {
- self.multiple_occurrences(yes).multiple_values(yes)
- }
-
- /// Deprecated, replaced with [`Arg::hide_short_help`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.0.0", note = "Replaced with `Arg::hide_short_help`")
- )]
- #[doc(hidden)]
- #[inline]
- #[must_use]
- pub fn hidden_short_help(self, yes: bool) -> Self {
- self.hide_short_help(yes)
- }
-
- /// Deprecated, replaced with [`Arg::hide_long_help`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.0.0", note = "Replaced with `Arg::hide_long_help`")
- )]
- #[doc(hidden)]
- #[inline]
- #[must_use]
- pub fn hidden_long_help(self, yes: bool) -> Self {
- self.hide_long_help(yes)
- }
-
- /// Deprecated, replaced with [`Arg::setting`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.0.0", note = "Replaced with `Arg::setting`")
- )]
- #[doc(hidden)]
- #[must_use]
- pub fn set(self, s: ArgSettings) -> Self {
- self.setting(s)
- }
-
- /// Deprecated, replaced with [`Arg::unset_setting`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.0.0", note = "Replaced with `Arg::unset_setting`")
- )]
- #[doc(hidden)]
- #[must_use]
- pub fn unset(self, s: ArgSettings) -> Self {
- self.unset_setting(s)
- }
-}
-
-/// # Internally used only
-impl<'help> Arg<'help> {
- pub(crate) fn _build(&mut self) {
- if self.is_positional() {
- self.settings.set(ArgSettings::TakesValue);
- }
- if let Some(action) = self.action.as_ref() {
- if let Some(default_value) = action.default_value() {
- if self.default_vals.is_empty() {
- self.default_vals = vec![default_value];
- }
- }
- if action.takes_values() {
- self.settings.set(ArgSettings::TakesValue);
- } else {
- self.settings.unset(ArgSettings::TakesValue);
- }
- match action {
- ArgAction::StoreValue
- | ArgAction::IncOccurrence
- | ArgAction::Help
- | ArgAction::Version => {}
- ArgAction::Set
- | ArgAction::Append
- | ArgAction::SetTrue
- | ArgAction::SetFalse
- | ArgAction::Count => {
- if !self.is_positional() {
- self.settings.set(ArgSettings::MultipleOccurrences);
- }
- }
- }
- }
-
- if self.value_parser.is_none() {
- if let Some(default) = self.action.as_ref().and_then(|a| a.default_value_parser()) {
- self.value_parser = Some(default);
- } else if self.is_allow_invalid_utf8_set() {
- self.value_parser = Some(super::ValueParser::os_string());
- } else {
- self.value_parser = Some(super::ValueParser::string());
- }
- }
-
- if (self.is_use_value_delimiter_set() || self.is_require_value_delimiter_set())
- && self.val_delim.is_none()
- {
- self.val_delim = Some(',');
- }
-
- let val_names_len = self.val_names.len();
-
- if val_names_len > 1 {
- self.settings.set(ArgSettings::MultipleValues);
-
- if self.num_vals.is_none() {
- self.num_vals = Some(val_names_len);
- }
- }
-
- let self_id = self.id.clone();
- if self.is_positional() || self.is_multiple_occurrences_set() {
- // Remove self-overrides where they don't make sense.
- //
- // We can evaluate switching this to a debug assert at a later time (though it will
- // require changing propagation of `AllArgsOverrideSelf`). Being conservative for now
- // due to where we are at in the release.
- self.overrides.retain(|e| *e != self_id);
- }
- }
-
- pub(crate) fn generated(mut self) -> Self {
- self.provider = ArgProvider::Generated;
- self
- }
-
- pub(crate) fn longest_filter(&self) -> bool {
- self.is_takes_value_set() || self.long.is_some() || self.short.is_none()
- }
-
- // Used for positionals when printing
- pub(crate) fn multiple_str(&self) -> &str {
- let mult_vals = self.val_names.len() > 1;
- if (self.is_multiple_values_set() || self.is_multiple_occurrences_set()) && !mult_vals {
- "..."
- } else {
- ""
- }
- }
-
- // Used for positionals when printing
- pub(crate) fn name_no_brackets(&self) -> Cow<str> {
- debug!("Arg::name_no_brackets:{}", self.name);
- let delim = if self.is_require_value_delimiter_set() {
- self.val_delim.expect(INTERNAL_ERROR_MSG)
- } else {
- ' '
- }
- .to_string();
- if !self.val_names.is_empty() {
- debug!("Arg::name_no_brackets: val_names={:#?}", self.val_names);
-
- if self.val_names.len() > 1 {
- Cow::Owned(
- self.val_names
- .iter()
- .map(|n| format!("<{}>", n))
- .collect::<Vec<_>>()
- .join(&*delim),
- )
- } else {
- Cow::Borrowed(self.val_names.get(0).expect(INTERNAL_ERROR_MSG))
- }
- } else {
- debug!("Arg::name_no_brackets: just name");
- Cow::Borrowed(self.name)
- }
- }
-
- /// Either multiple values or occurrences
- pub(crate) fn is_multiple(&self) -> bool {
- self.is_multiple_values_set() | self.is_multiple_occurrences_set()
- }
-
- pub(crate) fn get_display_order(&self) -> usize {
- self.disp_ord.get_explicit()
- }
-}
-
-impl<'help> From<&'_ Arg<'help>> for Arg<'help> {
- fn from(a: &Arg<'help>) -> Self {
- a.clone()
- }
-}
-
-impl<'help> PartialEq for Arg<'help> {
- fn eq(&self, other: &Arg<'help>) -> bool {
- self.name == other.name
- }
-}
-
-impl<'help> PartialOrd for Arg<'help> {
- fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
- Some(self.cmp(other))
- }
-}
-
-impl<'help> Ord for Arg<'help> {
- fn cmp(&self, other: &Arg) -> Ordering {
- self.name.cmp(other.name)
- }
-}
-
-impl<'help> Eq for Arg<'help> {}
-
-impl<'help> Display for Arg<'help> {
- fn fmt(&self, f: &mut Formatter) -> fmt::Result {
- // Write the name such --long or -l
- if let Some(l) = self.long {
- write!(f, "--{}", l)?;
- } else if let Some(s) = self.short {
- write!(f, "-{}", s)?;
- }
- let mut need_closing_bracket = false;
- if !self.is_positional() && self.is_takes_value_set() {
- let is_optional_val = self.min_vals == Some(0);
- let sep = if self.is_require_equals_set() {
- if is_optional_val {
- need_closing_bracket = true;
- "[="
- } else {
- "="
- }
- } else if is_optional_val {
- need_closing_bracket = true;
- " ["
- } else {
- " "
- };
- f.write_str(sep)?;
- }
- if self.is_takes_value_set() || self.is_positional() {
- display_arg_val(self, |s, _| f.write_str(s))?;
- }
- if need_closing_bracket {
- f.write_str("]")?;
- }
-
- Ok(())
- }
-}
-
-impl<'help> fmt::Debug for Arg<'help> {
- fn fmt(&self, f: &mut Formatter) -> Result<(), fmt::Error> {
- let mut ds = f.debug_struct("Arg");
-
- #[allow(unused_mut)]
- let mut ds = ds
- .field("id", &self.id)
- .field("provider", &self.provider)
- .field("name", &self.name)
- .field("help", &self.help)
- .field("long_help", &self.long_help)
- .field("action", &self.action)
- .field("value_parser", &self.value_parser)
- .field("blacklist", &self.blacklist)
- .field("settings", &self.settings)
- .field("overrides", &self.overrides)
- .field("groups", &self.groups)
- .field("requires", &self.requires)
- .field("r_ifs", &self.r_ifs)
- .field("r_unless", &self.r_unless)
- .field("short", &self.short)
- .field("long", &self.long)
- .field("aliases", &self.aliases)
- .field("short_aliases", &self.short_aliases)
- .field("disp_ord", &self.disp_ord)
- .field("possible_vals", &self.possible_vals)
- .field("val_names", &self.val_names)
- .field("num_vals", &self.num_vals)
- .field("max_vals", &self.max_vals)
- .field("min_vals", &self.min_vals)
- .field(
- "validator",
- &self.validator.as_ref().map_or("None", |_| "Some(FnMut)"),
- )
- .field(
- "validator_os",
- &self.validator_os.as_ref().map_or("None", |_| "Some(FnMut)"),
- )
- .field("val_delim", &self.val_delim)
- .field("default_vals", &self.default_vals)
- .field("default_vals_ifs", &self.default_vals_ifs)
- .field("terminator", &self.terminator)
- .field("index", &self.index)
- .field("help_heading", &self.help_heading)
- .field("value_hint", &self.value_hint)
- .field("default_missing_vals", &self.default_missing_vals);
-
- #[cfg(feature = "env")]
- {
- ds = ds.field("env", &self.env);
- }
-
- ds.finish()
- }
-}
-
-type Validator<'a> = dyn FnMut(&str) -> Result<(), Box<dyn Error + Send + Sync>> + Send + 'a;
-type ValidatorOs<'a> = dyn FnMut(&OsStr) -> Result<(), Box<dyn Error + Send + Sync>> + Send + 'a;
-
-#[derive(Debug, Clone, Eq, PartialEq)]
-pub(crate) enum ArgProvider {
- Generated,
- GeneratedMutated,
- User,
-}
-
-impl Default for ArgProvider {
- fn default() -> Self {
- ArgProvider::User
- }
-}
-
-/// Write the values such as <name1> <name2>
-pub(crate) fn display_arg_val<F, T, E>(arg: &Arg, mut write: F) -> Result<(), E>
-where
- F: FnMut(&str, bool) -> Result<T, E>,
-{
- let mult_val = arg.is_multiple_values_set();
- let mult_occ = arg.is_multiple_occurrences_set();
- let delim = if arg.is_require_value_delimiter_set() {
- arg.val_delim.expect(INTERNAL_ERROR_MSG)
- } else {
- ' '
- }
- .to_string();
- if !arg.val_names.is_empty() {
- // If have val_name.
- match (arg.val_names.len(), arg.num_vals) {
- (1, Some(num_vals)) => {
- // If single value name with multiple num_of_vals, display all
- // the values with the single value name.
- let arg_name = format!("<{}>", arg.val_names.get(0).unwrap());
- for n in 1..=num_vals {
- write(&arg_name, true)?;
- if n != num_vals {
- write(&delim, false)?;
- }
- }
- }
- (num_val_names, _) => {
- // If multiple value names, display them sequentially(ignore num of vals).
- let mut it = arg.val_names.iter().peekable();
- while let Some(val) = it.next() {
- write(&format!("<{}>", val), true)?;
- if it.peek().is_some() {
- write(&delim, false)?;
- }
- }
- if (num_val_names == 1 && mult_val)
- || (arg.is_positional() && mult_occ)
- || num_val_names < arg.num_vals.unwrap_or(0)
- {
- write("...", true)?;
- }
- }
- }
- } else if let Some(num_vals) = arg.num_vals {
- // If number_of_values is specified, display the value multiple times.
- let arg_name = format!("<{}>", arg.name);
- for n in 1..=num_vals {
- write(&arg_name, true)?;
- if n != num_vals {
- write(&delim, false)?;
- }
- }
- } else if arg.is_positional() {
- // Value of positional argument with no num_vals and val_names.
- write(&format!("<{}>", arg.name), true)?;
-
- if mult_val || mult_occ {
- write("...", true)?;
- }
- } else {
- // value of flag argument with no num_vals and val_names.
- write(&format!("<{}>", arg.name), true)?;
- if mult_val {
- write("...", true)?;
- }
- }
- Ok(())
-}
-
-#[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord)]
-pub(crate) enum DisplayOrder {
- None,
- Implicit(usize),
- Explicit(usize),
-}
-
-impl DisplayOrder {
- pub(crate) fn set_explicit(&mut self, explicit: usize) {
- *self = Self::Explicit(explicit)
- }
-
- pub(crate) fn set_implicit(&mut self, implicit: usize) {
- *self = (*self).max(Self::Implicit(implicit))
- }
-
- pub(crate) fn make_explicit(&mut self) {
- match *self {
- Self::None | Self::Explicit(_) => {}
- Self::Implicit(disp) => self.set_explicit(disp),
- }
- }
-
- pub(crate) fn get_explicit(self) -> usize {
- match self {
- Self::None | Self::Implicit(_) => 999,
- Self::Explicit(disp) => disp,
- }
- }
-}
-
-impl Default for DisplayOrder {
- fn default() -> Self {
- Self::None
- }
-}
-
-// Flags
-#[cfg(test)]
-mod test {
- use super::Arg;
-
- #[test]
- fn flag_display() {
- let mut f = Arg::new("flg").multiple_occurrences(true);
- f.long = Some("flag");
-
- assert_eq!(f.to_string(), "--flag");
-
- let mut f2 = Arg::new("flg");
- f2.short = Some('f');
-
- assert_eq!(f2.to_string(), "-f");
- }
-
- #[test]
- fn flag_display_single_alias() {
- let mut f = Arg::new("flg");
- f.long = Some("flag");
- f.aliases = vec![("als", true)];
-
- assert_eq!(f.to_string(), "--flag")
- }
-
- #[test]
- fn flag_display_multiple_aliases() {
- let mut f = Arg::new("flg");
- f.short = Some('f');
- f.aliases = vec![
- ("alias_not_visible", false),
- ("f2", true),
- ("f3", true),
- ("f4", true),
- ];
- assert_eq!(f.to_string(), "-f");
- }
-
- #[test]
- fn flag_display_single_short_alias() {
- let mut f = Arg::new("flg");
- f.short = Some('a');
- f.short_aliases = vec![('b', true)];
-
- assert_eq!(f.to_string(), "-a")
- }
-
- #[test]
- fn flag_display_multiple_short_aliases() {
- let mut f = Arg::new("flg");
- f.short = Some('a');
- f.short_aliases = vec![('b', false), ('c', true), ('d', true), ('e', true)];
- assert_eq!(f.to_string(), "-a");
- }
-
- // Options
-
- #[test]
- fn option_display_multiple_occurrences() {
- let o = Arg::new("opt")
- .long("option")
- .takes_value(true)
- .multiple_occurrences(true);
-
- assert_eq!(o.to_string(), "--option <opt>");
- }
-
- #[test]
- fn option_display_multiple_values() {
- let o = Arg::new("opt")
- .long("option")
- .takes_value(true)
- .multiple_values(true);
-
- assert_eq!(o.to_string(), "--option <opt>...");
- }
-
- #[test]
- fn option_display2() {
- let o2 = Arg::new("opt").short('o').value_names(&["file", "name"]);
-
- assert_eq!(o2.to_string(), "-o <file> <name>");
- }
-
- #[test]
- fn option_display3() {
- let o2 = Arg::new("opt")
- .short('o')
- .takes_value(true)
- .multiple_values(true)
- .value_names(&["file", "name"]);
-
- assert_eq!(o2.to_string(), "-o <file> <name>");
- }
-
- #[test]
- fn option_display_single_alias() {
- let o = Arg::new("opt")
- .takes_value(true)
- .long("option")
- .visible_alias("als");
-
- assert_eq!(o.to_string(), "--option <opt>");
- }
-
- #[test]
- fn option_display_multiple_aliases() {
- let o = Arg::new("opt")
- .long("option")
- .takes_value(true)
- .visible_aliases(&["als2", "als3", "als4"])
- .alias("als_not_visible");
-
- assert_eq!(o.to_string(), "--option <opt>");
- }
-
- #[test]
- fn option_display_single_short_alias() {
- let o = Arg::new("opt")
- .takes_value(true)
- .short('a')
- .visible_short_alias('b');
-
- assert_eq!(o.to_string(), "-a <opt>");
- }
-
- #[test]
- fn option_display_multiple_short_aliases() {
- let o = Arg::new("opt")
- .short('a')
- .takes_value(true)
- .visible_short_aliases(&['b', 'c', 'd'])
- .short_alias('e');
-
- assert_eq!(o.to_string(), "-a <opt>");
- }
-
- // Positionals
-
- #[test]
- fn positional_display_multiple_values() {
- let p = Arg::new("pos")
- .index(1)
- .takes_value(true)
- .multiple_values(true);
-
- assert_eq!(p.to_string(), "<pos>...");
- }
-
- #[test]
- fn positional_display_multiple_occurrences() {
- let p = Arg::new("pos")
- .index(1)
- .takes_value(true)
- .multiple_occurrences(true);
-
- assert_eq!(p.to_string(), "<pos>...");
- }
-
- #[test]
- fn positional_display_required() {
- let p2 = Arg::new("pos").index(1).required(true);
-
- assert_eq!(p2.to_string(), "<pos>");
- }
-
- #[test]
- fn positional_display_val_names() {
- let p2 = Arg::new("pos").index(1).value_names(&["file1", "file2"]);
-
- assert_eq!(p2.to_string(), "<file1> <file2>");
- }
-
- #[test]
- fn positional_display_val_names_req() {
- let p2 = Arg::new("pos")
- .index(1)
- .required(true)
- .value_names(&["file1", "file2"]);
-
- assert_eq!(p2.to_string(), "<file1> <file2>");
- }
-}
diff --git a/vendor/clap/src/builder/arg_group.rs b/vendor/clap/src/builder/arg_group.rs
deleted file mode 100644
index 0fe317109..000000000
--- a/vendor/clap/src/builder/arg_group.rs
+++ /dev/null
@@ -1,633 +0,0 @@
-// Internal
-use crate::util::{Id, Key};
-
-#[cfg(feature = "yaml")]
-use yaml_rust::Yaml;
-
-/// Family of related [arguments].
-///
-/// By placing arguments in a logical group, you can create easier requirement and
-/// exclusion rules instead of having to list each argument individually, or when you want a rule
-/// to apply "any but not all" arguments.
-///
-/// For instance, you can make an entire `ArgGroup` required. If [`ArgGroup::multiple(true)`] is
-/// set, this means that at least one argument from that group must be present. If
-/// [`ArgGroup::multiple(false)`] is set (the default), one and *only* one must be present.
-///
-/// You can also do things such as name an entire `ArgGroup` as a [conflict] or [requirement] for
-/// another argument, meaning any of the arguments that belong to that group will cause a failure
-/// if present, or must be present respectively.
-///
-/// Perhaps the most common use of `ArgGroup`s is to require one and *only* one argument to be
-/// present out of a given set. Imagine that you had multiple arguments, and you want one of them
-/// to be required, but making all of them required isn't feasible because perhaps they conflict
-/// with each other. For example, lets say that you were building an application where one could
-/// set a given version number by supplying a string with an option argument, i.e.
-/// `--set-ver v1.2.3`, you also wanted to support automatically using a previous version number
-/// and simply incrementing one of the three numbers. So you create three flags `--major`,
-/// `--minor`, and `--patch`. All of these arguments shouldn't be used at one time but you want to
-/// specify that *at least one* of them is used. For this, you can create a group.
-///
-/// Finally, you may use `ArgGroup`s to pull a value from a group of arguments when you don't care
-/// exactly which argument was actually used at runtime.
-///
-/// # Examples
-///
-/// The following example demonstrates using an `ArgGroup` to ensure that one, and only one, of
-/// the arguments from the specified group is present at runtime.
-///
-/// ```rust
-/// # use clap::{Command, arg, ArgGroup, ErrorKind};
-/// let result = Command::new("cmd")
-/// .arg(arg!(--"set-ver" <ver> "set the version manually").required(false))
-/// .arg(arg!(--major "auto increase major"))
-/// .arg(arg!(--minor "auto increase minor"))
-/// .arg(arg!(--patch "auto increase patch"))
-/// .group(ArgGroup::new("vers")
-/// .args(&["set-ver", "major", "minor", "patch"])
-/// .required(true))
-/// .try_get_matches_from(vec!["cmd", "--major", "--patch"]);
-/// // Because we used two args in the group it's an error
-/// assert!(result.is_err());
-/// let err = result.unwrap_err();
-/// assert_eq!(err.kind(), ErrorKind::ArgumentConflict);
-/// ```
-/// This next example shows a passing parse of the same scenario
-///
-/// ```rust
-/// # use clap::{Command, arg, ArgGroup};
-/// let result = Command::new("cmd")
-/// .arg(arg!(--"set-ver" <ver> "set the version manually").required(false))
-/// .arg(arg!(--major "auto increase major"))
-/// .arg(arg!(--minor "auto increase minor"))
-/// .arg(arg!(--patch "auto increase patch"))
-/// .group(ArgGroup::new("vers")
-/// .args(&["set-ver", "major", "minor","patch"])
-/// .required(true))
-/// .try_get_matches_from(vec!["cmd", "--major"]);
-/// assert!(result.is_ok());
-/// let matches = result.unwrap();
-/// // We may not know which of the args was used, so we can test for the group...
-/// assert!(matches.contains_id("vers"));
-/// // we could also alternatively check each arg individually (not shown here)
-/// ```
-/// [`ArgGroup::multiple(true)`]: ArgGroup::multiple()
-///
-/// [`ArgGroup::multiple(false)`]: ArgGroup::multiple()
-/// [arguments]: crate::Arg
-/// [conflict]: crate::Arg::conflicts_with()
-/// [requirement]: crate::Arg::requires()
-#[derive(Default, Debug, PartialEq, Eq)]
-pub struct ArgGroup<'help> {
- pub(crate) id: Id,
- pub(crate) name: &'help str,
- pub(crate) args: Vec<Id>,
- pub(crate) required: bool,
- pub(crate) requires: Vec<Id>,
- pub(crate) conflicts: Vec<Id>,
- pub(crate) multiple: bool,
-}
-
-impl<'help> ArgGroup<'help> {
- pub(crate) fn with_id(id: Id) -> Self {
- ArgGroup {
- id,
- ..ArgGroup::default()
- }
- }
-
- /// Create a `ArgGroup` using a unique name.
- ///
- /// The name will be used to get values from the group or refer to the group inside of conflict
- /// and requirement rules.
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Command, ArgGroup};
- /// ArgGroup::new("config")
- /// # ;
- /// ```
- pub fn new<S: Into<&'help str>>(n: S) -> Self {
- ArgGroup::default().id(n)
- }
-
- /// Sets the group name.
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Command, ArgGroup};
- /// ArgGroup::default().name("config")
- /// # ;
- /// ```
- #[must_use]
- pub fn id<S: Into<&'help str>>(mut self, n: S) -> Self {
- self.name = n.into();
- self.id = Id::from(self.name);
- self
- }
-
- /// Deprecated, replaced with [`ArgGroup::id`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.1.0", note = "Replaced with `ArgGroup::id`")
- )]
- pub fn name<S: Into<&'help str>>(self, n: S) -> Self {
- self.id(n)
- }
-
- /// Adds an [argument] to this group by name
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Command, Arg, ArgGroup};
- /// let m = Command::new("myprog")
- /// .arg(Arg::new("flag")
- /// .short('f'))
- /// .arg(Arg::new("color")
- /// .short('c'))
- /// .group(ArgGroup::new("req_flags")
- /// .arg("flag")
- /// .arg("color"))
- /// .get_matches_from(vec!["myprog", "-f"]);
- /// // maybe we don't know which of the two flags was used...
- /// assert!(m.contains_id("req_flags"));
- /// // but we can also check individually if needed
- /// assert!(m.contains_id("flag"));
- /// ```
- /// [argument]: crate::Arg
- #[must_use]
- pub fn arg<T: Key>(mut self, arg_id: T) -> Self {
- self.args.push(arg_id.into());
- self
- }
-
- /// Adds multiple [arguments] to this group by name
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Command, Arg, ArgGroup};
- /// let m = Command::new("myprog")
- /// .arg(Arg::new("flag")
- /// .short('f'))
- /// .arg(Arg::new("color")
- /// .short('c'))
- /// .group(ArgGroup::new("req_flags")
- /// .args(&["flag", "color"]))
- /// .get_matches_from(vec!["myprog", "-f"]);
- /// // maybe we don't know which of the two flags was used...
- /// assert!(m.contains_id("req_flags"));
- /// // but we can also check individually if needed
- /// assert!(m.contains_id("flag"));
- /// ```
- /// [arguments]: crate::Arg
- #[must_use]
- pub fn args<T: Key>(mut self, ns: &[T]) -> Self {
- for n in ns {
- self = self.arg(n);
- }
- self
- }
-
- /// Allows more than one of the [`Arg`]s in this group to be used. (Default: `false`)
- ///
- /// # Examples
- ///
- /// Notice in this example we use *both* the `-f` and `-c` flags which are both part of the
- /// group
- ///
- /// ```rust
- /// # use clap::{Command, Arg, ArgGroup};
- /// let m = Command::new("myprog")
- /// .arg(Arg::new("flag")
- /// .short('f'))
- /// .arg(Arg::new("color")
- /// .short('c'))
- /// .group(ArgGroup::new("req_flags")
- /// .args(&["flag", "color"])
- /// .multiple(true))
- /// .get_matches_from(vec!["myprog", "-f", "-c"]);
- /// // maybe we don't know which of the two flags was used...
- /// assert!(m.contains_id("req_flags"));
- /// ```
- /// In this next example, we show the default behavior (i.e. `multiple(false)) which will throw
- /// an error if more than one of the args in the group was used.
- ///
- /// ```rust
- /// # use clap::{Command, Arg, ArgGroup, ErrorKind};
- /// let result = Command::new("myprog")
- /// .arg(Arg::new("flag")
- /// .short('f'))
- /// .arg(Arg::new("color")
- /// .short('c'))
- /// .group(ArgGroup::new("req_flags")
- /// .args(&["flag", "color"]))
- /// .try_get_matches_from(vec!["myprog", "-f", "-c"]);
- /// // Because we used both args in the group it's an error
- /// assert!(result.is_err());
- /// let err = result.unwrap_err();
- /// assert_eq!(err.kind(), ErrorKind::ArgumentConflict);
- /// ```
- ///
- /// [`Arg`]: crate::Arg
- #[inline]
- #[must_use]
- pub fn multiple(mut self, yes: bool) -> Self {
- self.multiple = yes;
- self
- }
-
- /// Require an argument from the group to be present when parsing.
- ///
- /// This is unless conflicting with another argument. A required group will be displayed in
- /// the usage string of the application in the format `<arg|arg2|arg3>`.
- ///
- /// **NOTE:** This setting only applies to the current [`Command`] / [`Subcommand`]s, and not
- /// globally.
- ///
- /// **NOTE:** By default, [`ArgGroup::multiple`] is set to `false` which when combined with
- /// `ArgGroup::required(true)` states, "One and *only one* arg must be used from this group.
- /// Use of more than one arg is an error." Vice setting `ArgGroup::multiple(true)` which
- /// states, '*At least* one arg from this group must be used. Using multiple is OK."
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Command, Arg, ArgGroup, ErrorKind};
- /// let result = Command::new("myprog")
- /// .arg(Arg::new("flag")
- /// .short('f'))
- /// .arg(Arg::new("color")
- /// .short('c'))
- /// .group(ArgGroup::new("req_flags")
- /// .args(&["flag", "color"])
- /// .required(true))
- /// .try_get_matches_from(vec!["myprog"]);
- /// // Because we didn't use any of the args in the group, it's an error
- /// assert!(result.is_err());
- /// let err = result.unwrap_err();
- /// assert_eq!(err.kind(), ErrorKind::MissingRequiredArgument);
- /// ```
- ///
- /// [`Subcommand`]: crate::Subcommand
- /// [`ArgGroup::multiple`]: ArgGroup::multiple()
- /// [`Command`]: crate::Command
- #[inline]
- #[must_use]
- pub fn required(mut self, yes: bool) -> Self {
- self.required = yes;
- self
- }
-
- /// Specify an argument or group that must be present when this group is.
- ///
- /// This is not to be confused with a [required group]. Requirement rules function just like
- /// [argument requirement rules], you can name other arguments or groups that must be present
- /// when any one of the arguments from this group is used.
- ///
- /// **NOTE:** The name provided may be an argument or group name
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Command, Arg, ArgGroup, ErrorKind};
- /// let result = Command::new("myprog")
- /// .arg(Arg::new("flag")
- /// .short('f'))
- /// .arg(Arg::new("color")
- /// .short('c'))
- /// .arg(Arg::new("debug")
- /// .short('d'))
- /// .group(ArgGroup::new("req_flags")
- /// .args(&["flag", "color"])
- /// .requires("debug"))
- /// .try_get_matches_from(vec!["myprog", "-c"]);
- /// // because we used an arg from the group, and the group requires "-d" to be used, it's an
- /// // error
- /// assert!(result.is_err());
- /// let err = result.unwrap_err();
- /// assert_eq!(err.kind(), ErrorKind::MissingRequiredArgument);
- /// ```
- /// [required group]: ArgGroup::required()
- /// [argument requirement rules]: crate::Arg::requires()
- #[must_use]
- pub fn requires<T: Key>(mut self, id: T) -> Self {
- self.requires.push(id.into());
- self
- }
-
- /// Specify arguments or groups that must be present when this group is.
- ///
- /// This is not to be confused with a [required group]. Requirement rules function just like
- /// [argument requirement rules], you can name other arguments or groups that must be present
- /// when one of the arguments from this group is used.
- ///
- /// **NOTE:** The names provided may be an argument or group name
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Command, Arg, ArgGroup, ErrorKind};
- /// let result = Command::new("myprog")
- /// .arg(Arg::new("flag")
- /// .short('f'))
- /// .arg(Arg::new("color")
- /// .short('c'))
- /// .arg(Arg::new("debug")
- /// .short('d'))
- /// .arg(Arg::new("verb")
- /// .short('v'))
- /// .group(ArgGroup::new("req_flags")
- /// .args(&["flag", "color"])
- /// .requires_all(&["debug", "verb"]))
- /// .try_get_matches_from(vec!["myprog", "-c", "-d"]);
- /// // because we used an arg from the group, and the group requires "-d" and "-v" to be used,
- /// // yet we only used "-d" it's an error
- /// assert!(result.is_err());
- /// let err = result.unwrap_err();
- /// assert_eq!(err.kind(), ErrorKind::MissingRequiredArgument);
- /// ```
- /// [required group]: ArgGroup::required()
- /// [argument requirement rules]: crate::Arg::requires_all()
- #[must_use]
- pub fn requires_all(mut self, ns: &[&'help str]) -> Self {
- for n in ns {
- self = self.requires(n);
- }
- self
- }
-
- /// Specify an argument or group that must **not** be present when this group is.
- ///
- /// Exclusion (aka conflict) rules function just like [argument exclusion rules], you can name
- /// other arguments or groups that must *not* be present when one of the arguments from this
- /// group are used.
- ///
- /// **NOTE:** The name provided may be an argument, or group name
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Command, Arg, ArgGroup, ErrorKind};
- /// let result = Command::new("myprog")
- /// .arg(Arg::new("flag")
- /// .short('f'))
- /// .arg(Arg::new("color")
- /// .short('c'))
- /// .arg(Arg::new("debug")
- /// .short('d'))
- /// .group(ArgGroup::new("req_flags")
- /// .args(&["flag", "color"])
- /// .conflicts_with("debug"))
- /// .try_get_matches_from(vec!["myprog", "-c", "-d"]);
- /// // because we used an arg from the group, and the group conflicts with "-d", it's an error
- /// assert!(result.is_err());
- /// let err = result.unwrap_err();
- /// assert_eq!(err.kind(), ErrorKind::ArgumentConflict);
- /// ```
- /// [argument exclusion rules]: crate::Arg::conflicts_with()
- #[must_use]
- pub fn conflicts_with<T: Key>(mut self, id: T) -> Self {
- self.conflicts.push(id.into());
- self
- }
-
- /// Specify arguments or groups that must **not** be present when this group is.
- ///
- /// Exclusion rules function just like [argument exclusion rules], you can name other arguments
- /// or groups that must *not* be present when one of the arguments from this group are used.
- ///
- /// **NOTE:** The names provided may be an argument, or group name
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Command, Arg, ArgGroup, ErrorKind};
- /// let result = Command::new("myprog")
- /// .arg(Arg::new("flag")
- /// .short('f'))
- /// .arg(Arg::new("color")
- /// .short('c'))
- /// .arg(Arg::new("debug")
- /// .short('d'))
- /// .arg(Arg::new("verb")
- /// .short('v'))
- /// .group(ArgGroup::new("req_flags")
- /// .args(&["flag", "color"])
- /// .conflicts_with_all(&["debug", "verb"]))
- /// .try_get_matches_from(vec!["myprog", "-c", "-v"]);
- /// // because we used an arg from the group, and the group conflicts with either "-v" or "-d"
- /// // it's an error
- /// assert!(result.is_err());
- /// let err = result.unwrap_err();
- /// assert_eq!(err.kind(), ErrorKind::ArgumentConflict);
- /// ```
- ///
- /// [argument exclusion rules]: crate::Arg::conflicts_with_all()
- #[must_use]
- pub fn conflicts_with_all(mut self, ns: &[&'help str]) -> Self {
- for n in ns {
- self = self.conflicts_with(n);
- }
- self
- }
-
- /// Deprecated, replaced with [`ArgGroup::new`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.0.0", note = "Replaced with `ArgGroup::new`")
- )]
- #[doc(hidden)]
- pub fn with_name<S: Into<&'help str>>(n: S) -> Self {
- Self::new(n)
- }
-
- /// Deprecated in [Issue #3087](https://github.com/clap-rs/clap/issues/3087), maybe [`clap::Parser`][crate::Parser] would fit your use case?
- #[cfg(feature = "yaml")]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.0.0",
- note = "Maybe clap::Parser would fit your use case? (Issue #3087)"
- )
- )]
- #[doc(hidden)]
- pub fn from_yaml(yaml: &'help Yaml) -> Self {
- Self::from(yaml)
- }
-}
-
-impl<'help> From<&'_ ArgGroup<'help>> for ArgGroup<'help> {
- fn from(g: &ArgGroup<'help>) -> Self {
- ArgGroup {
- id: g.id.clone(),
- name: g.name,
- required: g.required,
- args: g.args.clone(),
- requires: g.requires.clone(),
- conflicts: g.conflicts.clone(),
- multiple: g.multiple,
- }
- }
-}
-
-/// Deprecated in [Issue #3087](https://github.com/clap-rs/clap/issues/3087), maybe [`clap::Parser`][crate::Parser] would fit your use case?
-#[cfg(feature = "yaml")]
-impl<'help> From<&'help Yaml> for ArgGroup<'help> {
- /// Deprecated in [Issue #3087](https://github.com/clap-rs/clap/issues/3087), maybe [`clap::Parser`][crate::Parser] would fit your use case?
- fn from(y: &'help Yaml) -> Self {
- let b = y.as_hash().expect("ArgGroup::from::<Yaml> expects a table");
- // We WANT this to panic on error...so expect() is good.
- let mut a = ArgGroup::default();
- let group_settings = if b.len() == 1 {
- let name_yaml = b.keys().next().expect("failed to get name");
- let name_str = name_yaml
- .as_str()
- .expect("failed to convert arg YAML name to str");
- a.name = name_str;
- a.id = Id::from(&a.name);
- b.get(name_yaml)
- .expect("failed to get name_str")
- .as_hash()
- .expect("failed to convert to a hash")
- } else {
- b
- };
-
- for (k, v) in group_settings {
- a = match k.as_str().unwrap() {
- "required" => a.required(v.as_bool().unwrap()),
- "multiple" => a.multiple(v.as_bool().unwrap()),
- "args" => yaml_vec_or_str!(a, v, arg),
- "arg" => {
- if let Some(ys) = v.as_str() {
- a = a.arg(ys);
- }
- a
- }
- "requires" => yaml_vec_or_str!(a, v, requires),
- "conflicts_with" => yaml_vec_or_str!(a, v, conflicts_with),
- "name" => {
- if let Some(ys) = v.as_str() {
- a = a.id(ys);
- }
- a
- }
- s => panic!(
- "Unknown ArgGroup setting '{}' in YAML file for \
- ArgGroup '{}'",
- s, a.name
- ),
- }
- }
-
- a
- }
-}
-
-#[cfg(test)]
-mod test {
- use super::ArgGroup;
- #[cfg(feature = "yaml")]
- use yaml_rust::YamlLoader;
-
- #[test]
- fn groups() {
- let g = ArgGroup::new("test")
- .arg("a1")
- .arg("a4")
- .args(&["a2", "a3"])
- .required(true)
- .conflicts_with("c1")
- .conflicts_with_all(&["c2", "c3"])
- .conflicts_with("c4")
- .requires("r1")
- .requires_all(&["r2", "r3"])
- .requires("r4");
-
- let args = vec!["a1".into(), "a4".into(), "a2".into(), "a3".into()];
- let reqs = vec!["r1".into(), "r2".into(), "r3".into(), "r4".into()];
- let confs = vec!["c1".into(), "c2".into(), "c3".into(), "c4".into()];
-
- assert_eq!(g.args, args);
- assert_eq!(g.requires, reqs);
- assert_eq!(g.conflicts, confs);
- }
-
- #[test]
- fn test_from() {
- let g = ArgGroup::new("test")
- .arg("a1")
- .arg("a4")
- .args(&["a2", "a3"])
- .required(true)
- .conflicts_with("c1")
- .conflicts_with_all(&["c2", "c3"])
- .conflicts_with("c4")
- .requires("r1")
- .requires_all(&["r2", "r3"])
- .requires("r4");
-
- let args = vec!["a1".into(), "a4".into(), "a2".into(), "a3".into()];
- let reqs = vec!["r1".into(), "r2".into(), "r3".into(), "r4".into()];
- let confs = vec!["c1".into(), "c2".into(), "c3".into(), "c4".into()];
-
- let g2 = ArgGroup::from(&g);
- assert_eq!(g2.args, args);
- assert_eq!(g2.requires, reqs);
- assert_eq!(g2.conflicts, confs);
- }
-
- #[cfg(feature = "yaml")]
- #[test]
- fn test_yaml() {
- let g_yaml = "name: test
-args:
-- a1
-- a4
-- a2
-- a3
-conflicts_with:
-- c1
-- c2
-- c3
-- c4
-requires:
-- r1
-- r2
-- r3
-- r4";
- let yaml = &YamlLoader::load_from_str(g_yaml).expect("failed to load YAML file")[0];
- let g = ArgGroup::from(yaml);
- let args = vec!["a1".into(), "a4".into(), "a2".into(), "a3".into()];
- let reqs = vec!["r1".into(), "r2".into(), "r3".into(), "r4".into()];
- let confs = vec!["c1".into(), "c2".into(), "c3".into(), "c4".into()];
- assert_eq!(g.args, args);
- assert_eq!(g.requires, reqs);
- assert_eq!(g.conflicts, confs);
- }
-
- // This test will *fail to compile* if ArgGroup is not Send + Sync
- #[test]
- fn arg_group_send_sync() {
- fn foo<T: Send + Sync>(_: T) {}
- foo(ArgGroup::new("test"))
- }
-}
-
-impl Clone for ArgGroup<'_> {
- fn clone(&self) -> Self {
- ArgGroup {
- id: self.id.clone(),
- name: self.name,
- required: self.required,
- args: self.args.clone(),
- requires: self.requires.clone(),
- conflicts: self.conflicts.clone(),
- multiple: self.multiple,
- }
- }
-}
diff --git a/vendor/clap/src/builder/arg_predicate.rs b/vendor/clap/src/builder/arg_predicate.rs
deleted file mode 100644
index 58eb5494c..000000000
--- a/vendor/clap/src/builder/arg_predicate.rs
+++ /dev/null
@@ -1,14 +0,0 @@
-#[derive(Copy, Clone, Debug, PartialEq, Eq)]
-pub(crate) enum ArgPredicate<'help> {
- IsPresent,
- Equals(&'help std::ffi::OsStr),
-}
-
-impl<'help> From<Option<&'help std::ffi::OsStr>> for ArgPredicate<'help> {
- fn from(other: Option<&'help std::ffi::OsStr>) -> Self {
- match other {
- Some(other) => Self::Equals(other),
- None => Self::IsPresent,
- }
- }
-}
diff --git a/vendor/clap/src/builder/arg_settings.rs b/vendor/clap/src/builder/arg_settings.rs
deleted file mode 100644
index ecc064caa..000000000
--- a/vendor/clap/src/builder/arg_settings.rs
+++ /dev/null
@@ -1,456 +0,0 @@
-#![allow(deprecated)]
-
-// Std
-use std::ops::BitOr;
-#[cfg(feature = "yaml")]
-use std::str::FromStr;
-
-// Third party
-use bitflags::bitflags;
-
-#[allow(unused)]
-use crate::Arg;
-
-#[doc(hidden)]
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub struct ArgFlags(Flags);
-
-impl Default for ArgFlags {
- fn default() -> Self {
- Self::empty()
- }
-}
-
-/// Various settings that apply to arguments and may be set, unset, and checked via getter/setter
-/// methods [`Arg::setting`], [`Arg::unset_setting`], and [`Arg::is_set`]. This is what the
-/// [`Arg`] methods which accept a `bool` use internally.
-///
-/// [`Arg`]: crate::Arg
-/// [`Arg::setting`]: crate::Arg::setting()
-/// [`Arg::unset_setting`]: crate::Arg::unset_setting()
-/// [`Arg::is_set`]: crate::Arg::is_set()
-#[derive(Debug, PartialEq, Copy, Clone)]
-#[non_exhaustive]
-pub enum ArgSettings {
- /// Deprecated, replaced with [`Arg::required`] and [`Arg::is_required_set`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.1.0",
- note = "Replaced with `Arg::required` and `Arg::is_required_set`"
- )
- )]
- Required,
- /// Deprecated, replaced with [`Arg::multiple_values`] and [`Arg::is_multiple_values_set`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.1.0",
- note = "Replaced with `Arg::multiple_values` and `Arg::`is_multiple_values_set`"
- )
- )]
- MultipleValues,
- /// Deprecated, replaced with [`Arg::action`] ([Issue #3772](https://github.com/clap-rs/clap/issues/3772))
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.1.0", note = "Replaced with `Arg::action` (Issue #3772)")
- )]
- MultipleOccurrences,
- /// Deprecated, see [`ArgSettings::MultipleOccurrences`] (most likely what you want) and
- /// [`ArgSettings::MultipleValues`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.0.0",
- note = "Split into `Arg::multiple_occurrences` (most likely what you want) and `Arg::multiple_values`"
- )
- )]
- #[doc(hidden)]
- Multiple,
- /// Deprecated, replaced with [`Arg::value_parser(NonEmptyStringValueParser::new())`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.1.0",
- note = "Replaced with `Arg::value_parser(NonEmptyStringValueParser::new())`"
- )
- )]
- ForbidEmptyValues,
- /// Deprecated, replaced with [`Arg::global`] and [`Arg::is_global_set`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.1.0",
- note = "Replaced with `Arg::global` and `Arg::is_global_set`"
- )
- )]
- Global,
- /// Deprecated, replaced with [`Arg::hide`] and [`Arg::is_hide_set`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.1.0",
- note = "Replaced with `Arg::hide` and `Arg::is_hide_set`"
- )
- )]
- Hidden,
- /// Deprecated, replaced with [`Arg::takes_value`] and [`Arg::is_takes_value_set`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.1.0",
- note = "Replaced with `Arg::takes_value` and `Arg::is_takes_value_set`"
- )
- )]
- TakesValue,
- /// Deprecated, replaced with [`Arg::use_value_delimiter`] and
- /// [`Arg::is_use_value_delimiter_set`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.1.0",
- note = "Replaced with `Arg::use_value_delimiter` and `Arg::is_use_value_delimiter_set`"
- )
- )]
- UseValueDelimiter,
- /// Deprecated, replaced with [`Arg::next_line_help`] and [`Arg::is_next_line_help_set`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.1.0",
- note = "Replaced with `Arg::next_line_help` and `Arg::is_next_line_help_set`"
- )
- )]
- NextLineHelp,
- /// Deprecated, replaced with [`Arg::require_value_delimiter`] and
- /// [`Arg::is_require_value_delimiter_set`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.1.0",
- note = "Replaced with `Arg::require_value_delimiter` and `Arg::is_require_value_delimiter_set`"
- )
- )]
- RequireDelimiter,
- /// Deprecated, replaced with [`Arg::hide_possible_values`] and
- /// [`Arg::is_hide_possible_values_set`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.1.0",
- note = "Replaced with `Arg::hide_possible_values` and `Arg::is_hide_possible_values_set`"
- )
- )]
- HidePossibleValues,
- /// Deprecated, replaced with [`Arg::allow_hyphen_values`] and
- /// [`Arg::is_allow_hyphen_values_set`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.1.0",
- note = "Replaced with `Arg::allow_hyphen_values` and `Arg::is_allow_hyphen_values_set`"
- )
- )]
- AllowHyphenValues,
- /// Deprecated, replaced with [`Arg::allow_hyphen_values`] and
- /// [`Arg::is_allow_hyphen_values_set`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.0.0",
- note = "Replaced with `Arg::allow_hyphen_values` and `Arg::is_allow_hyphen_values_set`"
- )
- )]
- #[doc(hidden)]
- AllowLeadingHyphen,
- /// Deprecated, replaced with [`Arg::require_equals`] and [`Arg::is_require_equals_set`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.1.0",
- note = "Replaced with `Arg::require_equals` and `Arg::is_require_equals_set`"
- )
- )]
- RequireEquals,
- /// Deprecated, replaced with [`Arg::last`] and [`Arg::is_last_set`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.1.0",
- note = "Replaced with `Arg::last` and `Arg::is_last_set`"
- )
- )]
- Last,
- /// Deprecated, replaced with [`Arg::hide_default_value`] and [`Arg::is_hide_default_value_set`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.1.0",
- note = "Replaced with `Arg::hide_default_value` and `Arg::is_hide_default_value_set`"
- )
- )]
- HideDefaultValue,
- /// Deprecated, replaced with [`Arg::ignore_case`] and [`Arg::is_ignore_case_set`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.1.0",
- note = "Replaced with `Arg::ignore_case` and `Arg::is_ignore_case_set`"
- )
- )]
- IgnoreCase,
- /// Deprecated, replaced with [`Arg::ignore_case`] and [`Arg::is_ignore_case_set`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.0.0",
- note = "Replaced with `Arg::ignore_case` and `Arg::is_ignore_case_set`"
- )
- )]
- #[doc(hidden)]
- CaseInsensitive,
- /// Deprecated, replaced with [`Arg::hide_env`] and [`Arg::is_hide_env_set`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.1.0",
- note = "Replaced with `Arg::hide_env` and `Arg::is_hide_env_set`"
- )
- )]
- #[cfg(feature = "env")]
- HideEnv,
- /// Deprecated, replaced with [`Arg::hide_env_values`] and [`Arg::is_hide_env_values_set`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.1.0",
- note = "Replaced with `Arg::hide_env_values` and `Arg::is_hide_env_values_set`"
- )
- )]
- #[cfg(feature = "env")]
- HideEnvValues,
- /// Deprecated, replaced with [`Arg::hide_short_help`] and [`Arg::is_hide_short_help_set`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.1.0",
- note = "Replaced with `Arg::hide_short_help` and `Arg::is_hide_short_help_set`"
- )
- )]
- HiddenShortHelp,
- /// Deprecated, replaced with [`Arg::hide_long_help`] and [`Arg::is_hide_long_help_set`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.1.0",
- note = "Replaced with `Arg::hide_long_help` and `Arg::is_hide_long_help_set`"
- )
- )]
- HiddenLongHelp,
- /// Deprecated, replaced with [`Arg::allow_invalid_utf8`] and [`Arg::is_allow_invalid_utf8_set`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.1.0",
- note = "Replaced with `Arg::allow_invalid_utf8` and `Arg::is_allow_invalid_utf8_set`"
- )
- )]
- AllowInvalidUtf8,
- /// Deprecated, replaced with [`Arg::exclusive`] and [`Arg::is_exclusive_set`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.1.0",
- note = "Replaced with `Arg::exclusive` and `Arg::is_exclusive_set`"
- )
- )]
- Exclusive,
-}
-
-bitflags! {
- struct Flags: u32 {
- const REQUIRED = 1;
- const MULTIPLE_OCC = 1 << 1;
- const NO_EMPTY_VALS = 1 << 2;
- const GLOBAL = 1 << 3;
- const HIDDEN = 1 << 4;
- const TAKES_VAL = 1 << 5;
- const USE_DELIM = 1 << 6;
- const NEXT_LINE_HELP = 1 << 7;
- const REQ_DELIM = 1 << 9;
- const DELIM_NOT_SET = 1 << 10;
- const HIDE_POS_VALS = 1 << 11;
- const ALLOW_TAC_VALS = 1 << 12;
- const REQUIRE_EQUALS = 1 << 13;
- const LAST = 1 << 14;
- const HIDE_DEFAULT_VAL = 1 << 15;
- const CASE_INSENSITIVE = 1 << 16;
- #[cfg(feature = "env")]
- const HIDE_ENV_VALS = 1 << 17;
- const HIDDEN_SHORT_H = 1 << 18;
- const HIDDEN_LONG_H = 1 << 19;
- const MULTIPLE_VALS = 1 << 20;
- const MULTIPLE = Self::MULTIPLE_OCC.bits | Self::MULTIPLE_VALS.bits;
- #[cfg(feature = "env")]
- const HIDE_ENV = 1 << 21;
- const UTF8_NONE = 1 << 22;
- const EXCLUSIVE = 1 << 23;
- const NO_OP = 0;
- }
-}
-
-impl_settings! { ArgSettings, ArgFlags,
- Required => Flags::REQUIRED,
- MultipleOccurrences => Flags::MULTIPLE_OCC,
- MultipleValues => Flags::MULTIPLE_VALS,
- Multiple => Flags::MULTIPLE,
- ForbidEmptyValues => Flags::NO_EMPTY_VALS,
- Global => Flags::GLOBAL,
- Hidden => Flags::HIDDEN,
- TakesValue => Flags::TAKES_VAL,
- UseValueDelimiter => Flags::USE_DELIM,
- NextLineHelp => Flags::NEXT_LINE_HELP,
- RequireDelimiter => Flags::REQ_DELIM,
- HidePossibleValues => Flags::HIDE_POS_VALS,
- AllowHyphenValues => Flags::ALLOW_TAC_VALS,
- AllowLeadingHyphen => Flags::ALLOW_TAC_VALS,
- RequireEquals => Flags::REQUIRE_EQUALS,
- Last => Flags::LAST,
- IgnoreCase => Flags::CASE_INSENSITIVE,
- CaseInsensitive => Flags::CASE_INSENSITIVE,
- #[cfg(feature = "env")]
- HideEnv => Flags::HIDE_ENV,
- #[cfg(feature = "env")]
- HideEnvValues => Flags::HIDE_ENV_VALS,
- HideDefaultValue => Flags::HIDE_DEFAULT_VAL,
- HiddenShortHelp => Flags::HIDDEN_SHORT_H,
- HiddenLongHelp => Flags::HIDDEN_LONG_H,
- AllowInvalidUtf8 => Flags::UTF8_NONE,
- Exclusive => Flags::EXCLUSIVE
-}
-
-/// Deprecated in [Issue #3087](https://github.com/clap-rs/clap/issues/3087), maybe [`clap::Parser`][crate::Parser] would fit your use case?
-#[cfg(feature = "yaml")]
-impl FromStr for ArgSettings {
- type Err = String;
- fn from_str(s: &str) -> Result<Self, <Self as FromStr>::Err> {
- #[allow(deprecated)]
- #[allow(unreachable_patterns)]
- match &*s.to_ascii_lowercase() {
- "required" => Ok(ArgSettings::Required),
- "multipleoccurrences" => Ok(ArgSettings::MultipleOccurrences),
- "multiplevalues" => Ok(ArgSettings::MultipleValues),
- "multiple" => Ok(ArgSettings::Multiple),
- "forbidemptyvalues" => Ok(ArgSettings::ForbidEmptyValues),
- "global" => Ok(ArgSettings::Global),
- "hidden" => Ok(ArgSettings::Hidden),
- "takesvalue" => Ok(ArgSettings::TakesValue),
- "usevaluedelimiter" => Ok(ArgSettings::UseValueDelimiter),
- "nextlinehelp" => Ok(ArgSettings::NextLineHelp),
- "requiredelimiter" => Ok(ArgSettings::RequireDelimiter),
- "hidepossiblevalues" => Ok(ArgSettings::HidePossibleValues),
- "allowhyphenvalues" => Ok(ArgSettings::AllowHyphenValues),
- "allowleadinghypyhen" => Ok(ArgSettings::AllowLeadingHyphen),
- "requireequals" => Ok(ArgSettings::RequireEquals),
- "last" => Ok(ArgSettings::Last),
- "ignorecase" => Ok(ArgSettings::IgnoreCase),
- "caseinsensitive" => Ok(ArgSettings::CaseInsensitive),
- #[cfg(feature = "env")]
- "hideenv" => Ok(ArgSettings::HideEnv),
- #[cfg(feature = "env")]
- "hideenvvalues" => Ok(ArgSettings::HideEnvValues),
- "hidedefaultvalue" => Ok(ArgSettings::HideDefaultValue),
- "hiddenshorthelp" => Ok(ArgSettings::HiddenShortHelp),
- "hiddenlonghelp" => Ok(ArgSettings::HiddenLongHelp),
- "allowinvalidutf8" => Ok(ArgSettings::AllowInvalidUtf8),
- "exclusive" => Ok(ArgSettings::Exclusive),
- _ => Err(format!("unknown AppSetting: `{}`", s)),
- }
- }
-}
-
-#[cfg(test)]
-mod test {
- #[test]
- #[cfg(feature = "yaml")]
- fn arg_settings_fromstr() {
- use super::ArgSettings;
-
- assert_eq!(
- "allowhyphenvalues".parse::<ArgSettings>().unwrap(),
- ArgSettings::AllowHyphenValues
- );
- assert_eq!(
- "forbidemptyvalues".parse::<ArgSettings>().unwrap(),
- ArgSettings::ForbidEmptyValues
- );
- assert_eq!(
- "hidepossiblevalues".parse::<ArgSettings>().unwrap(),
- ArgSettings::HidePossibleValues
- );
- assert_eq!(
- "hidden".parse::<ArgSettings>().unwrap(),
- ArgSettings::Hidden
- );
- assert_eq!(
- "nextlinehelp".parse::<ArgSettings>().unwrap(),
- ArgSettings::NextLineHelp
- );
- assert_eq!(
- "requiredelimiter".parse::<ArgSettings>().unwrap(),
- ArgSettings::RequireDelimiter
- );
- assert_eq!(
- "required".parse::<ArgSettings>().unwrap(),
- ArgSettings::Required
- );
- assert_eq!(
- "takesvalue".parse::<ArgSettings>().unwrap(),
- ArgSettings::TakesValue
- );
- assert_eq!(
- "usevaluedelimiter".parse::<ArgSettings>().unwrap(),
- ArgSettings::UseValueDelimiter
- );
- assert_eq!(
- "requireequals".parse::<ArgSettings>().unwrap(),
- ArgSettings::RequireEquals
- );
- assert_eq!("last".parse::<ArgSettings>().unwrap(), ArgSettings::Last);
- assert_eq!(
- "hidedefaultvalue".parse::<ArgSettings>().unwrap(),
- ArgSettings::HideDefaultValue
- );
- assert_eq!(
- "ignorecase".parse::<ArgSettings>().unwrap(),
- ArgSettings::IgnoreCase
- );
- #[cfg(feature = "env")]
- assert_eq!(
- "hideenv".parse::<ArgSettings>().unwrap(),
- ArgSettings::HideEnv
- );
- #[cfg(feature = "env")]
- assert_eq!(
- "hideenvvalues".parse::<ArgSettings>().unwrap(),
- ArgSettings::HideEnvValues
- );
- assert_eq!(
- "hiddenshorthelp".parse::<ArgSettings>().unwrap(),
- ArgSettings::HiddenShortHelp
- );
- assert_eq!(
- "hiddenlonghelp".parse::<ArgSettings>().unwrap(),
- ArgSettings::HiddenLongHelp
- );
- assert_eq!(
- "allowinvalidutf8".parse::<ArgSettings>().unwrap(),
- ArgSettings::AllowInvalidUtf8
- );
- assert_eq!(
- "exclusive".parse::<ArgSettings>().unwrap(),
- ArgSettings::Exclusive
- );
- assert!("hahahaha".parse::<ArgSettings>().is_err());
- }
-}
diff --git a/vendor/clap/src/builder/command.rs b/vendor/clap/src/builder/command.rs
deleted file mode 100644
index de59ad8cd..000000000
--- a/vendor/clap/src/builder/command.rs
+++ /dev/null
@@ -1,5189 +0,0 @@
-#![allow(deprecated)]
-
-// Std
-use std::collections::HashMap;
-use std::env;
-use std::ffi::OsString;
-use std::fmt;
-use std::io;
-use std::ops::Index;
-use std::path::Path;
-
-// Third Party
-#[cfg(feature = "yaml")]
-use yaml_rust::Yaml;
-
-// Internal
-use crate::builder::app_settings::{AppFlags, AppSettings};
-use crate::builder::arg_settings::ArgSettings;
-use crate::builder::{arg::ArgProvider, Arg, ArgGroup, ArgPredicate};
-use crate::error::ErrorKind;
-use crate::error::Result as ClapResult;
-use crate::mkeymap::MKeyMap;
-use crate::output::fmt::Stream;
-use crate::output::{fmt::Colorizer, Help, HelpWriter, Usage};
-use crate::parser::{ArgMatcher, ArgMatches, Parser};
-use crate::util::ChildGraph;
-use crate::util::{color::ColorChoice, Id, Key};
-use crate::PossibleValue;
-use crate::{Error, INTERNAL_ERROR_MSG};
-
-#[cfg(debug_assertions)]
-use crate::builder::debug_asserts::assert_app;
-
-/// Build a command-line interface.
-///
-/// This includes defining arguments, subcommands, parser behavior, and help output.
-/// Once all configuration is complete,
-/// the [`Command::get_matches`] family of methods starts the runtime-parsing
-/// process. These methods then return information about the user supplied
-/// arguments (or lack thereof).
-///
-/// When deriving a [`Parser`][crate::Parser], you can use
-/// [`CommandFactory::command`][crate::CommandFactory::command] to access the
-/// `Command`.
-///
-/// - [Basic API][crate::App#basic-api]
-/// - [Application-wide Settings][crate::App#application-wide-settings]
-/// - [Command-specific Settings][crate::App#command-specific-settings]
-/// - [Subcommand-specific Settings][crate::App#subcommand-specific-settings]
-/// - [Reflection][crate::App#reflection]
-///
-/// # Examples
-///
-/// ```no_run
-/// # use clap::{Command, Arg};
-/// let m = Command::new("My Program")
-/// .author("Me, me@mail.com")
-/// .version("1.0.2")
-/// .about("Explains in brief what the program does")
-/// .arg(
-/// Arg::new("in_file")
-/// )
-/// .after_help("Longer explanation to appear after the options when \
-/// displaying the help information from --help or -h")
-/// .get_matches();
-///
-/// // Your program logic starts here...
-/// ```
-/// [`App::get_matches`]: Command::get_matches()
-pub type Command<'help> = App<'help>;
-
-/// Deprecated, replaced with [`Command`]
-#[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.1.0", note = "Replaced with `Command`")
-)]
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct App<'help> {
- id: Id,
- name: String,
- long_flag: Option<&'help str>,
- short_flag: Option<char>,
- display_name: Option<String>,
- bin_name: Option<String>,
- author: Option<&'help str>,
- version: Option<&'help str>,
- long_version: Option<&'help str>,
- about: Option<&'help str>,
- long_about: Option<&'help str>,
- before_help: Option<&'help str>,
- before_long_help: Option<&'help str>,
- after_help: Option<&'help str>,
- after_long_help: Option<&'help str>,
- aliases: Vec<(&'help str, bool)>, // (name, visible)
- short_flag_aliases: Vec<(char, bool)>, // (name, visible)
- long_flag_aliases: Vec<(&'help str, bool)>, // (name, visible)
- usage_str: Option<&'help str>,
- usage_name: Option<String>,
- help_str: Option<&'help str>,
- disp_ord: Option<usize>,
- term_w: Option<usize>,
- max_w: Option<usize>,
- template: Option<&'help str>,
- settings: AppFlags,
- g_settings: AppFlags,
- args: MKeyMap<'help>,
- subcommands: Vec<App<'help>>,
- replacers: HashMap<&'help str, &'help [&'help str]>,
- groups: Vec<ArgGroup<'help>>,
- current_help_heading: Option<&'help str>,
- current_disp_ord: Option<usize>,
- subcommand_value_name: Option<&'help str>,
- subcommand_heading: Option<&'help str>,
-}
-
-/// # Basic API
-impl<'help> App<'help> {
- /// Creates a new instance of an `Command`.
- ///
- /// It is common, but not required, to use binary name as the `name`. This
- /// name will only be displayed to the user when they request to print
- /// version or help and usage information.
- ///
- /// See also [`command!`](crate::command!) and [`crate_name!`](crate::crate_name!).
- ///
- /// # Examples
- ///
- /// ```no_run
- /// # use clap::Command;
- /// Command::new("My Program")
- /// # ;
- /// ```
- pub fn new<S: Into<String>>(name: S) -> Self {
- /// The actual implementation of `new`, non-generic to save code size.
- ///
- /// If we don't do this rustc will unnecessarily generate multiple versions
- /// of this code.
- fn new_inner<'help>(name: String) -> App<'help> {
- App {
- id: Id::from(&*name),
- name,
- ..Default::default()
- }
- .arg(
- Arg::new("help")
- .long("help")
- .help("Print help information")
- .global(true)
- .generated(),
- )
- .arg(
- Arg::new("version")
- .long("version")
- .help("Print version information")
- .global(true)
- .generated(),
- )
- }
-
- new_inner(name.into())
- }
-
- /// Adds an [argument] to the list of valid possibilities.
- ///
- /// # Examples
- ///
- /// ```no_run
- /// # use clap::{Command, arg, Arg};
- /// Command::new("myprog")
- /// // Adding a single "flag" argument with a short and help text, using Arg::new()
- /// .arg(
- /// Arg::new("debug")
- /// .short('d')
- /// .help("turns on debugging mode")
- /// )
- /// // Adding a single "option" argument with a short, a long, and help text using the less
- /// // verbose Arg::from()
- /// .arg(
- /// arg!(-c --config <CONFIG> "Optionally sets a config file to use")
- /// )
- /// # ;
- /// ```
- /// [argument]: Arg
- #[must_use]
- pub fn arg<A: Into<Arg<'help>>>(mut self, a: A) -> Self {
- let mut arg = a.into();
- if let Some(current_disp_ord) = self.current_disp_ord.as_mut() {
- if !arg.is_positional() && arg.provider != ArgProvider::Generated {
- let current = *current_disp_ord;
- arg.disp_ord.set_implicit(current);
- *current_disp_ord = current + 1;
- }
- }
-
- arg.help_heading.get_or_insert(self.current_help_heading);
- self.args.push(arg);
- self
- }
-
- /// Adds multiple [arguments] to the list of valid possibilities.
- ///
- /// # Examples
- ///
- /// ```no_run
- /// # use clap::{Command, arg, Arg};
- /// Command::new("myprog")
- /// .args(&[
- /// arg!("[debug] -d 'turns on debugging info'"),
- /// Arg::new("input").help("the input file to use")
- /// ])
- /// # ;
- /// ```
- /// [arguments]: Arg
- #[must_use]
- pub fn args<I, T>(mut self, args: I) -> Self
- where
- I: IntoIterator<Item = T>,
- T: Into<Arg<'help>>,
- {
- let args = args.into_iter();
- let (lower, _) = args.size_hint();
- self.args.reserve(lower);
-
- for arg in args {
- self = self.arg(arg);
- }
- self
- }
-
- /// Allows one to mutate an [`Arg`] after it's been added to a [`Command`].
- ///
- /// This can be useful for modifying the auto-generated help or version arguments.
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- ///
- /// let mut cmd = Command::new("foo")
- /// .arg(Arg::new("bar")
- /// .short('b'))
- /// .mut_arg("bar", |a| a.short('B'));
- ///
- /// let res = cmd.try_get_matches_from_mut(vec!["foo", "-b"]);
- ///
- /// // Since we changed `bar`'s short to "B" this should err as there
- /// // is no `-b` anymore, only `-B`
- ///
- /// assert!(res.is_err());
- ///
- /// let res = cmd.try_get_matches_from_mut(vec!["foo", "-B"]);
- /// assert!(res.is_ok());
- /// ```
- #[must_use]
- pub fn mut_arg<T, F>(mut self, arg_id: T, f: F) -> Self
- where
- F: FnOnce(Arg<'help>) -> Arg<'help>,
- T: Key + Into<&'help str>,
- {
- let arg_id: &str = arg_id.into();
- let id = Id::from(arg_id);
-
- let mut a = self.args.remove_by_name(&id).unwrap_or_else(|| Arg {
- id,
- name: arg_id,
- ..Arg::default()
- });
-
- if a.provider == ArgProvider::Generated {
- a.provider = ArgProvider::GeneratedMutated;
- }
-
- self.args.push(f(a));
- self
- }
-
- /// Allows one to mutate a [`Command`] after it's been added as a subcommand.
- ///
- /// This can be useful for modifying auto-generated arguments of nested subcommands with
- /// [`Command::mut_arg`].
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::Command;
- ///
- /// let mut cmd = Command::new("foo")
- /// .subcommand(Command::new("bar"))
- /// .mut_subcommand("bar", |subcmd| subcmd.disable_help_flag(true));
- ///
- /// let res = cmd.try_get_matches_from_mut(vec!["foo", "bar", "--help"]);
- ///
- /// // Since we disabled the help flag on the "bar" subcommand, this should err.
- ///
- /// assert!(res.is_err());
- ///
- /// let res = cmd.try_get_matches_from_mut(vec!["foo", "bar"]);
- /// assert!(res.is_ok());
- /// ```
- #[must_use]
- pub fn mut_subcommand<'a, T, F>(mut self, subcmd_id: T, f: F) -> Self
- where
- F: FnOnce(App<'help>) -> App<'help>,
- T: Into<&'a str>,
- {
- let subcmd_id: &str = subcmd_id.into();
- let id = Id::from(subcmd_id);
-
- let pos = self.subcommands.iter().position(|s| s.id == id);
-
- let subcmd = if let Some(idx) = pos {
- self.subcommands.remove(idx)
- } else {
- App::new(subcmd_id)
- };
-
- self.subcommands.push(f(subcmd));
- self
- }
-
- /// Adds an [`ArgGroup`] to the application.
- ///
- /// [`ArgGroup`]s are a family of related arguments.
- /// By placing them in a logical group, you can build easier requirement and exclusion rules.
- ///
- /// Example use cases:
- /// - Make an entire [`ArgGroup`] required, meaning that one (and *only*
- /// one) argument from that group must be present at runtime.
- /// - Name an [`ArgGroup`] as a conflict to another argument.
- /// Meaning any of the arguments that belong to that group will cause a failure if present with
- /// the conflicting argument.
- /// - Ensure exclusion between arguments.
- /// - Extract a value from a group instead of determining exactly which argument was used.
- ///
- /// # Examples
- ///
- /// The following example demonstrates using an [`ArgGroup`] to ensure that one, and only one,
- /// of the arguments from the specified group is present at runtime.
- ///
- /// ```no_run
- /// # use clap::{Command, arg, ArgGroup};
- /// Command::new("cmd")
- /// .arg(arg!("--set-ver [ver] 'set the version manually'"))
- /// .arg(arg!("--major 'auto increase major'"))
- /// .arg(arg!("--minor 'auto increase minor'"))
- /// .arg(arg!("--patch 'auto increase patch'"))
- /// .group(ArgGroup::new("vers")
- /// .args(&["set-ver", "major", "minor","patch"])
- /// .required(true))
- /// # ;
- /// ```
- #[inline]
- #[must_use]
- pub fn group<G: Into<ArgGroup<'help>>>(mut self, group: G) -> Self {
- self.groups.push(group.into());
- self
- }
-
- /// Adds multiple [`ArgGroup`]s to the [`Command`] at once.
- ///
- /// # Examples
- ///
- /// ```no_run
- /// # use clap::{Command, arg, ArgGroup};
- /// Command::new("cmd")
- /// .arg(arg!("--set-ver [ver] 'set the version manually'"))
- /// .arg(arg!("--major 'auto increase major'"))
- /// .arg(arg!("--minor 'auto increase minor'"))
- /// .arg(arg!("--patch 'auto increase patch'"))
- /// .arg(arg!("-c [FILE] 'a config file'"))
- /// .arg(arg!("-i [IFACE] 'an interface'"))
- /// .groups(&[
- /// ArgGroup::new("vers")
- /// .args(&["set-ver", "major", "minor","patch"])
- /// .required(true),
- /// ArgGroup::new("input")
- /// .args(&["c", "i"])
- /// ])
- /// # ;
- /// ```
- #[must_use]
- pub fn groups<I, T>(mut self, groups: I) -> Self
- where
- I: IntoIterator<Item = T>,
- T: Into<ArgGroup<'help>>,
- {
- for g in groups.into_iter() {
- self = self.group(g.into());
- }
- self
- }
-
- /// Adds a subcommand to the list of valid possibilities.
- ///
- /// Subcommands are effectively sub-[`Command`]s, because they can contain their own arguments,
- /// subcommands, version, usage, etc. They also function just like [`Command`]s, in that they get
- /// their own auto generated help, version, and usage.
- ///
- /// A subcommand's [`Command::name`] will be used for:
- /// - The argument the user passes in
- /// - Programmatically looking up the subcommand
- ///
- /// # Examples
- ///
- /// ```no_run
- /// # use clap::{Command, arg};
- /// Command::new("myprog")
- /// .subcommand(Command::new("config")
- /// .about("Controls configuration features")
- /// .arg(arg!("<config> 'Required configuration file to use'")))
- /// # ;
- /// ```
- #[inline]
- #[must_use]
- pub fn subcommand<S: Into<App<'help>>>(mut self, subcmd: S) -> Self {
- self.subcommands.push(subcmd.into());
- self
- }
-
- /// Adds multiple subcommands to the list of valid possibilities.
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Command, Arg, };
- /// # Command::new("myprog")
- /// .subcommands( vec![
- /// Command::new("config").about("Controls configuration functionality")
- /// .arg(Arg::new("config_file")),
- /// Command::new("debug").about("Controls debug functionality")])
- /// # ;
- /// ```
- /// [`IntoIterator`]: std::iter::IntoIterator
- #[must_use]
- pub fn subcommands<I, T>(mut self, subcmds: I) -> Self
- where
- I: IntoIterator<Item = T>,
- T: Into<App<'help>>,
- {
- for subcmd in subcmds.into_iter() {
- self.subcommands.push(subcmd.into());
- }
- self
- }
-
- /// Catch problems earlier in the development cycle.
- ///
- /// Most error states are handled as asserts under the assumption they are programming mistake
- /// and not something to handle at runtime. Rather than relying on tests (manual or automated)
- /// that exhaustively test your CLI to ensure the asserts are evaluated, this will run those
- /// asserts in a way convenient for running as a test.
- ///
- /// **Note::** This will not help with asserts in [`ArgMatches`], those will need exhaustive
- /// testing of your CLI.
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Command, Arg, ArgAction};
- /// fn cmd() -> Command<'static> {
- /// Command::new("foo")
- /// .arg(
- /// Arg::new("bar").short('b').action(ArgAction::SetTrue)
- /// )
- /// }
- ///
- /// #[test]
- /// fn verify_app() {
- /// cmd().debug_assert();
- /// }
- ///
- /// fn main() {
- /// let m = cmd().get_matches_from(vec!["foo", "-b"]);
- /// println!("{}", *m.get_one::<bool>("bar").expect("defaulted by clap"));
- /// }
- /// ```
- pub fn debug_assert(mut self) {
- self._build_all();
- }
-
- /// Custom error message for post-parsing validation
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Command, ErrorKind};
- /// let mut cmd = Command::new("myprog");
- /// let err = cmd.error(ErrorKind::InvalidValue, "Some failure case");
- /// ```
- pub fn error(&mut self, kind: ErrorKind, message: impl std::fmt::Display) -> Error {
- Error::raw(kind, message).format(self)
- }
-
- /// Parse [`env::args_os`], exiting on failure.
- ///
- /// # Panics
- ///
- /// If contradictory arguments or settings exist.
- ///
- /// # Examples
- ///
- /// ```no_run
- /// # use clap::{Command, Arg};
- /// let matches = Command::new("myprog")
- /// // Args and options go here...
- /// .get_matches();
- /// ```
- /// [`env::args_os`]: std::env::args_os()
- /// [`App::try_get_matches_from_mut`]: Command::try_get_matches_from_mut()
- #[inline]
- pub fn get_matches(self) -> ArgMatches {
- self.get_matches_from(&mut env::args_os())
- }
-
- /// Parse [`env::args_os`], exiting on failure.
- ///
- /// Like [`App::get_matches`] but doesn't consume the `Command`.
- ///
- /// # Panics
- ///
- /// If contradictory arguments or settings exist.
- ///
- /// # Examples
- ///
- /// ```no_run
- /// # use clap::{Command, Arg};
- /// let mut cmd = Command::new("myprog")
- /// // Args and options go here...
- /// ;
- /// let matches = cmd.get_matches_mut();
- /// ```
- /// [`env::args_os`]: std::env::args_os()
- /// [`App::get_matches`]: Command::get_matches()
- pub fn get_matches_mut(&mut self) -> ArgMatches {
- self.try_get_matches_from_mut(&mut env::args_os())
- .unwrap_or_else(|e| e.exit())
- }
-
- /// Parse [`env::args_os`], returning a [`clap::Result`] on failure.
- ///
- /// **NOTE:** This method WILL NOT exit when `--help` or `--version` (or short versions) are
- /// used. It will return a [`clap::Error`], where the [`kind`] is a
- /// [`ErrorKind::DisplayHelp`] or [`ErrorKind::DisplayVersion`] respectively. You must call
- /// [`Error::exit`] or perform a [`std::process::exit`].
- ///
- /// # Panics
- ///
- /// If contradictory arguments or settings exist.
- ///
- /// # Examples
- ///
- /// ```no_run
- /// # use clap::{Command, Arg};
- /// let matches = Command::new("myprog")
- /// // Args and options go here...
- /// .try_get_matches()
- /// .unwrap_or_else(|e| e.exit());
- /// ```
- /// [`env::args_os`]: std::env::args_os()
- /// [`Error::exit`]: crate::Error::exit()
- /// [`std::process::exit`]: std::process::exit()
- /// [`clap::Result`]: Result
- /// [`clap::Error`]: crate::Error
- /// [`kind`]: crate::Error
- /// [`ErrorKind::DisplayHelp`]: crate::ErrorKind::DisplayHelp
- /// [`ErrorKind::DisplayVersion`]: crate::ErrorKind::DisplayVersion
- #[inline]
- pub fn try_get_matches(self) -> ClapResult<ArgMatches> {
- // Start the parsing
- self.try_get_matches_from(&mut env::args_os())
- }
-
- /// Parse the specified arguments, exiting on failure.
- ///
- /// **NOTE:** The first argument will be parsed as the binary name unless
- /// [`Command::no_binary_name`] is used.
- ///
- /// # Panics
- ///
- /// If contradictory arguments or settings exist.
- ///
- /// # Examples
- ///
- /// ```no_run
- /// # use clap::{Command, Arg};
- /// let arg_vec = vec!["my_prog", "some", "args", "to", "parse"];
- ///
- /// let matches = Command::new("myprog")
- /// // Args and options go here...
- /// .get_matches_from(arg_vec);
- /// ```
- /// [`App::get_matches`]: Command::get_matches()
- /// [`clap::Result`]: Result
- /// [`Vec`]: std::vec::Vec
- pub fn get_matches_from<I, T>(mut self, itr: I) -> ArgMatches
- where
- I: IntoIterator<Item = T>,
- T: Into<OsString> + Clone,
- {
- self.try_get_matches_from_mut(itr).unwrap_or_else(|e| {
- drop(self);
- e.exit()
- })
- }
-
- /// Parse the specified arguments, returning a [`clap::Result`] on failure.
- ///
- /// **NOTE:** This method WILL NOT exit when `--help` or `--version` (or short versions) are
- /// used. It will return a [`clap::Error`], where the [`kind`] is a [`ErrorKind::DisplayHelp`]
- /// or [`ErrorKind::DisplayVersion`] respectively. You must call [`Error::exit`] or
- /// perform a [`std::process::exit`] yourself.
- ///
- /// **NOTE:** The first argument will be parsed as the binary name unless
- /// [`Command::no_binary_name`] is used.
- ///
- /// # Panics
- ///
- /// If contradictory arguments or settings exist.
- ///
- /// # Examples
- ///
- /// ```no_run
- /// # use clap::{Command, Arg};
- /// let arg_vec = vec!["my_prog", "some", "args", "to", "parse"];
- ///
- /// let matches = Command::new("myprog")
- /// // Args and options go here...
- /// .try_get_matches_from(arg_vec)
- /// .unwrap_or_else(|e| e.exit());
- /// ```
- /// [`App::get_matches_from`]: Command::get_matches_from()
- /// [`App::try_get_matches`]: Command::try_get_matches()
- /// [`Error::exit`]: crate::Error::exit()
- /// [`std::process::exit`]: std::process::exit()
- /// [`clap::Error`]: crate::Error
- /// [`Error::exit`]: crate::Error::exit()
- /// [`kind`]: crate::Error
- /// [`ErrorKind::DisplayHelp`]: crate::ErrorKind::DisplayHelp
- /// [`ErrorKind::DisplayVersion`]: crate::ErrorKind::DisplayVersion
- /// [`clap::Result`]: Result
- pub fn try_get_matches_from<I, T>(mut self, itr: I) -> ClapResult<ArgMatches>
- where
- I: IntoIterator<Item = T>,
- T: Into<OsString> + Clone,
- {
- self.try_get_matches_from_mut(itr)
- }
-
- /// Parse the specified arguments, returning a [`clap::Result`] on failure.
- ///
- /// Like [`App::try_get_matches_from`] but doesn't consume the `Command`.
- ///
- /// **NOTE:** This method WILL NOT exit when `--help` or `--version` (or short versions) are
- /// used. It will return a [`clap::Error`], where the [`kind`] is a [`ErrorKind::DisplayHelp`]
- /// or [`ErrorKind::DisplayVersion`] respectively. You must call [`Error::exit`] or
- /// perform a [`std::process::exit`] yourself.
- ///
- /// **NOTE:** The first argument will be parsed as the binary name unless
- /// [`Command::no_binary_name`] is used.
- ///
- /// # Panics
- ///
- /// If contradictory arguments or settings exist.
- ///
- /// # Examples
- ///
- /// ```no_run
- /// # use clap::{Command, Arg};
- /// let arg_vec = vec!["my_prog", "some", "args", "to", "parse"];
- ///
- /// let mut cmd = Command::new("myprog");
- /// // Args and options go here...
- /// let matches = cmd.try_get_matches_from_mut(arg_vec)
- /// .unwrap_or_else(|e| e.exit());
- /// ```
- /// [`App::try_get_matches_from`]: Command::try_get_matches_from()
- /// [`clap::Result`]: Result
- /// [`clap::Error`]: crate::Error
- /// [`kind`]: crate::Error
- pub fn try_get_matches_from_mut<I, T>(&mut self, itr: I) -> ClapResult<ArgMatches>
- where
- I: IntoIterator<Item = T>,
- T: Into<OsString> + Clone,
- {
- let mut raw_args = clap_lex::RawArgs::new(itr.into_iter());
- let mut cursor = raw_args.cursor();
-
- if self.settings.is_set(AppSettings::Multicall) {
- if let Some(argv0) = raw_args.next_os(&mut cursor) {
- let argv0 = Path::new(&argv0);
- if let Some(command) = argv0.file_stem().and_then(|f| f.to_str()) {
- // Stop borrowing command so we can get another mut ref to it.
- let command = command.to_owned();
- debug!(
- "Command::try_get_matches_from_mut: Parsed command {} from argv",
- command
- );
-
- debug!("Command::try_get_matches_from_mut: Reinserting command into arguments so subcommand parser matches it");
- raw_args.insert(&cursor, &[&command]);
- debug!("Command::try_get_matches_from_mut: Clearing name and bin_name so that displayed command name starts with applet name");
- self.name.clear();
- self.bin_name = None;
- return self._do_parse(&mut raw_args, cursor);
- }
- }
- };
-
- // Get the name of the program (argument 1 of env::args()) and determine the
- // actual file
- // that was used to execute the program. This is because a program called
- // ./target/release/my_prog -a
- // will have two arguments, './target/release/my_prog', '-a' but we don't want
- // to display
- // the full path when displaying help messages and such
- if !self.settings.is_set(AppSettings::NoBinaryName) {
- if let Some(name) = raw_args.next_os(&mut cursor) {
- let p = Path::new(name);
-
- if let Some(f) = p.file_name() {
- if let Some(s) = f.to_str() {
- if self.bin_name.is_none() {
- self.bin_name = Some(s.to_owned());
- }
- }
- }
- }
- }
-
- self._do_parse(&mut raw_args, cursor)
- }
-
- /// Prints the short help message (`-h`) to [`io::stdout()`].
- ///
- /// See also [`Command::print_long_help`].
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::Command;
- /// let mut cmd = Command::new("myprog");
- /// cmd.print_help();
- /// ```
- /// [`io::stdout()`]: std::io::stdout()
- pub fn print_help(&mut self) -> io::Result<()> {
- self._build_self();
- let color = self.color_help();
-
- let mut c = Colorizer::new(Stream::Stdout, color);
- let usage = Usage::new(self);
- Help::new(HelpWriter::Buffer(&mut c), self, &usage, false).write_help()?;
- c.print()
- }
-
- /// Prints the long help message (`--help`) to [`io::stdout()`].
- ///
- /// See also [`Command::print_help`].
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::Command;
- /// let mut cmd = Command::new("myprog");
- /// cmd.print_long_help();
- /// ```
- /// [`io::stdout()`]: std::io::stdout()
- /// [`BufWriter`]: std::io::BufWriter
- /// [`-h` (short)]: Arg::help()
- /// [`--help` (long)]: Arg::long_help()
- pub fn print_long_help(&mut self) -> io::Result<()> {
- self._build_self();
- let color = self.color_help();
-
- let mut c = Colorizer::new(Stream::Stdout, color);
- let usage = Usage::new(self);
- Help::new(HelpWriter::Buffer(&mut c), self, &usage, true).write_help()?;
- c.print()
- }
-
- /// Writes the short help message (`-h`) to a [`io::Write`] object.
- ///
- /// See also [`Command::write_long_help`].
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::Command;
- /// use std::io;
- /// let mut cmd = Command::new("myprog");
- /// let mut out = io::stdout();
- /// cmd.write_help(&mut out).expect("failed to write to stdout");
- /// ```
- /// [`io::Write`]: std::io::Write
- /// [`-h` (short)]: Arg::help()
- /// [`--help` (long)]: Arg::long_help()
- pub fn write_help<W: io::Write>(&mut self, w: &mut W) -> io::Result<()> {
- self._build_self();
-
- let usage = Usage::new(self);
- Help::new(HelpWriter::Normal(w), self, &usage, false).write_help()?;
- w.flush()
- }
-
- /// Writes the long help message (`--help`) to a [`io::Write`] object.
- ///
- /// See also [`Command::write_help`].
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::Command;
- /// use std::io;
- /// let mut cmd = Command::new("myprog");
- /// let mut out = io::stdout();
- /// cmd.write_long_help(&mut out).expect("failed to write to stdout");
- /// ```
- /// [`io::Write`]: std::io::Write
- /// [`-h` (short)]: Arg::help()
- /// [`--help` (long)]: Arg::long_help()
- pub fn write_long_help<W: io::Write>(&mut self, w: &mut W) -> io::Result<()> {
- self._build_self();
-
- let usage = Usage::new(self);
- Help::new(HelpWriter::Normal(w), self, &usage, true).write_help()?;
- w.flush()
- }
-
- /// Version message rendered as if the user ran `-V`.
- ///
- /// See also [`Command::render_long_version`].
- ///
- /// ### Coloring
- ///
- /// This function does not try to color the message nor it inserts any [ANSI escape codes].
- ///
- /// ### Examples
- ///
- /// ```rust
- /// # use clap::Command;
- /// use std::io;
- /// let cmd = Command::new("myprog");
- /// println!("{}", cmd.render_version());
- /// ```
- /// [`io::Write`]: std::io::Write
- /// [`-V` (short)]: Command::version()
- /// [`--version` (long)]: Command::long_version()
- /// [ANSI escape codes]: https://en.wikipedia.org/wiki/ANSI_escape_code
- pub fn render_version(&self) -> String {
- self._render_version(false)
- }
-
- /// Version message rendered as if the user ran `--version`.
- ///
- /// See also [`Command::render_version`].
- ///
- /// ### Coloring
- ///
- /// This function does not try to color the message nor it inserts any [ANSI escape codes].
- ///
- /// ### Examples
- ///
- /// ```rust
- /// # use clap::Command;
- /// use std::io;
- /// let cmd = Command::new("myprog");
- /// println!("{}", cmd.render_long_version());
- /// ```
- /// [`io::Write`]: std::io::Write
- /// [`-V` (short)]: Command::version()
- /// [`--version` (long)]: Command::long_version()
- /// [ANSI escape codes]: https://en.wikipedia.org/wiki/ANSI_escape_code
- pub fn render_long_version(&self) -> String {
- self._render_version(true)
- }
-
- /// Usage statement
- ///
- /// ### Examples
- ///
- /// ```rust
- /// # use clap::Command;
- /// use std::io;
- /// let mut cmd = Command::new("myprog");
- /// println!("{}", cmd.render_usage());
- /// ```
- pub fn render_usage(&mut self) -> String {
- // If there are global arguments, or settings we need to propagate them down to subcommands
- // before parsing incase we run into a subcommand
- self._build_self();
-
- Usage::new(self).create_usage_with_title(&[])
- }
-}
-
-/// # Application-wide Settings
-///
-/// These settings will apply to the top-level command and all subcommands, by default. Some
-/// settings can be overridden in subcommands.
-impl<'help> App<'help> {
- /// Specifies that the parser should not assume the first argument passed is the binary name.
- ///
- /// This is normally the case when using a "daemon" style mode. For shells / REPLs, see
- /// [`Command::multicall`][App::multicall].
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Command, arg};
- /// let m = Command::new("myprog")
- /// .no_binary_name(true)
- /// .arg(arg!(<cmd> ... "commands to run"))
- /// .get_matches_from(vec!["command", "set"]);
- ///
- /// let cmds: Vec<&str> = m.values_of("cmd").unwrap().collect();
- /// assert_eq!(cmds, ["command", "set"]);
- /// ```
- /// [`try_get_matches_from_mut`]: crate::Command::try_get_matches_from_mut()
- #[inline]
- pub fn no_binary_name(self, yes: bool) -> Self {
- if yes {
- self.global_setting(AppSettings::NoBinaryName)
- } else {
- self.unset_global_setting(AppSettings::NoBinaryName)
- }
- }
-
- /// Try not to fail on parse errors, like missing option values.
- ///
- /// **Note:** Make sure you apply it as `global_setting` if you want this setting
- /// to be propagated to subcommands and sub-subcommands!
- ///
- /// **NOTE:** This choice is propagated to all child subcommands.
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Command, arg};
- /// let cmd = Command::new("cmd")
- /// .ignore_errors(true)
- /// .arg(arg!(-c --config <FILE> "Sets a custom config file").required(false))
- /// .arg(arg!(-x --stuff <FILE> "Sets a custom stuff file").required(false))
- /// .arg(arg!(f: -f "Flag"));
- ///
- /// let r = cmd.try_get_matches_from(vec!["cmd", "-c", "file", "-f", "-x"]);
- ///
- /// assert!(r.is_ok(), "unexpected error: {:?}", r);
- /// let m = r.unwrap();
- /// assert_eq!(m.value_of("config"), Some("file"));
- /// assert!(m.is_present("f"));
- /// assert_eq!(m.value_of("stuff"), None);
- /// ```
- #[inline]
- pub fn ignore_errors(self, yes: bool) -> Self {
- if yes {
- self.global_setting(AppSettings::IgnoreErrors)
- } else {
- self.unset_global_setting(AppSettings::IgnoreErrors)
- }
- }
-
- /// Deprecated, replaced with [`ArgAction::Set`][super::ArgAction::Set]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.2.0", note = "Replaced with `Arg::action(ArgAction::Set)`")
- )]
- pub fn args_override_self(self, yes: bool) -> Self {
- if yes {
- self.global_setting(AppSettings::AllArgsOverrideSelf)
- } else {
- self.unset_global_setting(AppSettings::AllArgsOverrideSelf)
- }
- }
-
- /// Disables the automatic delimiting of values after `--` or when [`Command::trailing_var_arg`]
- /// was used.
- ///
- /// **NOTE:** The same thing can be done manually by setting the final positional argument to
- /// [`Arg::use_value_delimiter(false)`]. Using this setting is safer, because it's easier to locate
- /// when making changes.
- ///
- /// **NOTE:** This choice is propagated to all child subcommands.
- ///
- /// # Examples
- ///
- /// ```no_run
- /// # use clap::{Command, Arg};
- /// Command::new("myprog")
- /// .dont_delimit_trailing_values(true)
- /// .get_matches();
- /// ```
- ///
- /// [`Arg::use_value_delimiter(false)`]: crate::Arg::use_value_delimiter()
- #[inline]
- pub fn dont_delimit_trailing_values(self, yes: bool) -> Self {
- if yes {
- self.global_setting(AppSettings::DontDelimitTrailingValues)
- } else {
- self.unset_global_setting(AppSettings::DontDelimitTrailingValues)
- }
- }
-
- /// Sets when to color output.
- ///
- /// **NOTE:** This choice is propagated to all child subcommands.
- ///
- /// **NOTE:** Default behaviour is [`ColorChoice::Auto`].
- ///
- /// # Examples
- ///
- /// ```no_run
- /// # use clap::{Command, ColorChoice};
- /// Command::new("myprog")
- /// .color(ColorChoice::Never)
- /// .get_matches();
- /// ```
- /// [`ColorChoice::Auto`]: crate::ColorChoice::Auto
- #[cfg(feature = "color")]
- #[inline]
- #[must_use]
- pub fn color(self, color: ColorChoice) -> Self {
- #![allow(deprecated)]
- let cmd = self
- .unset_global_setting(AppSettings::ColorAuto)
- .unset_global_setting(AppSettings::ColorAlways)
- .unset_global_setting(AppSettings::ColorNever);
- match color {
- ColorChoice::Auto => cmd.global_setting(AppSettings::ColorAuto),
- ColorChoice::Always => cmd.global_setting(AppSettings::ColorAlways),
- ColorChoice::Never => cmd.global_setting(AppSettings::ColorNever),
- }
- }
-
- /// Sets the terminal width at which to wrap help messages.
- ///
- /// Using `0` will ignore terminal widths and use source formatting.
- ///
- /// Defaults to current terminal width when `wrap_help` feature flag is enabled. If the flag
- /// is disabled or it cannot be determined, the default is 100.
- ///
- /// **NOTE:** This setting applies globally and *not* on a per-command basis.
- ///
- /// # Examples
- ///
- /// ```no_run
- /// # use clap::Command;
- /// Command::new("myprog")
- /// .term_width(80)
- /// # ;
- /// ```
- #[inline]
- #[must_use]
- pub fn term_width(mut self, width: usize) -> Self {
- self.term_w = Some(width);
- self
- }
-
- /// Sets the maximum terminal width at which to wrap help messages.
- ///
- /// This only applies when setting the current terminal width. See [`Command::term_width`] for
- /// more details.
- ///
- /// Using `0` will ignore terminal widths and use source formatting.
- ///
- /// **NOTE:** This setting applies globally and *not* on a per-command basis.
- ///
- /// # Examples
- ///
- /// ```no_run
- /// # use clap::Command;
- /// Command::new("myprog")
- /// .max_term_width(100)
- /// # ;
- /// ```
- #[inline]
- #[must_use]
- pub fn max_term_width(mut self, w: usize) -> Self {
- self.max_w = Some(w);
- self
- }
-
- /// Disables `-V` and `--version` flag.
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Command, ErrorKind};
- /// let res = Command::new("myprog")
- /// .disable_version_flag(true)
- /// .try_get_matches_from(vec![
- /// "myprog", "-V"
- /// ]);
- /// assert!(res.is_err());
- /// assert_eq!(res.unwrap_err().kind(), ErrorKind::UnknownArgument);
- /// ```
- #[inline]
- pub fn disable_version_flag(self, yes: bool) -> Self {
- if yes {
- self.global_setting(AppSettings::DisableVersionFlag)
- } else {
- self.unset_global_setting(AppSettings::DisableVersionFlag)
- }
- }
-
- /// Specifies to use the version of the current command for all [`subcommands`].
- ///
- /// Defaults to `false`; subcommands have independent version strings from their parents.
- ///
- /// **Note:** Make sure you apply it as `global_setting` if you want this setting
- /// to be propagated to subcommands and sub-subcommands!
- ///
- /// **NOTE:** This choice is propagated to all child subcommands.
- ///
- /// # Examples
- ///
- /// ```no_run
- /// # use clap::{Command, Arg};
- /// Command::new("myprog")
- /// .version("v1.1")
- /// .propagate_version(true)
- /// .subcommand(Command::new("test"))
- /// .get_matches();
- /// // running `$ myprog test --version` will display
- /// // "myprog-test v1.1"
- /// ```
- ///
- /// [`subcommands`]: crate::Command::subcommand()
- #[inline]
- pub fn propagate_version(self, yes: bool) -> Self {
- if yes {
- self.global_setting(AppSettings::PropagateVersion)
- } else {
- self.unset_global_setting(AppSettings::PropagateVersion)
- }
- }
-
- /// Places the help string for all arguments and subcommands on the line after them.
- ///
- /// **NOTE:** This choice is propagated to all child subcommands.
- ///
- /// # Examples
- ///
- /// ```no_run
- /// # use clap::{Command, Arg};
- /// Command::new("myprog")
- /// .next_line_help(true)
- /// .get_matches();
- /// ```
- #[inline]
- pub fn next_line_help(self, yes: bool) -> Self {
- if yes {
- self.global_setting(AppSettings::NextLineHelp)
- } else {
- self.unset_global_setting(AppSettings::NextLineHelp)
- }
- }
-
- /// Disables `-h` and `--help` flag.
- ///
- /// **NOTE:** This choice is propagated to all child subcommands.
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Command, ErrorKind};
- /// let res = Command::new("myprog")
- /// .disable_help_flag(true)
- /// .try_get_matches_from(vec![
- /// "myprog", "-h"
- /// ]);
- /// assert!(res.is_err());
- /// assert_eq!(res.unwrap_err().kind(), ErrorKind::UnknownArgument);
- /// ```
- #[inline]
- pub fn disable_help_flag(self, yes: bool) -> Self {
- if yes {
- self.global_setting(AppSettings::DisableHelpFlag)
- } else {
- self.unset_global_setting(AppSettings::DisableHelpFlag)
- }
- }
-
- /// Disables the `help` [`subcommand`].
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Command, ErrorKind};
- /// let res = Command::new("myprog")
- /// .disable_help_subcommand(true)
- /// // Normally, creating a subcommand causes a `help` subcommand to automatically
- /// // be generated as well
- /// .subcommand(Command::new("test"))
- /// .try_get_matches_from(vec![
- /// "myprog", "help"
- /// ]);
- /// assert!(res.is_err());
- /// assert_eq!(res.unwrap_err().kind(), ErrorKind::UnknownArgument);
- /// ```
- ///
- /// [`subcommand`]: crate::Command::subcommand()
- #[inline]
- pub fn disable_help_subcommand(self, yes: bool) -> Self {
- if yes {
- self.global_setting(AppSettings::DisableHelpSubcommand)
- } else {
- self.unset_global_setting(AppSettings::DisableHelpSubcommand)
- }
- }
-
- /// Disables colorized help messages.
- ///
- /// **NOTE:** This choice is propagated to all child subcommands.
- ///
- /// # Examples
- ///
- /// ```no_run
- /// # use clap::Command;
- /// Command::new("myprog")
- /// .disable_colored_help(true)
- /// .get_matches();
- /// ```
- #[inline]
- pub fn disable_colored_help(self, yes: bool) -> Self {
- if yes {
- self.global_setting(AppSettings::DisableColoredHelp)
- } else {
- self.unset_global_setting(AppSettings::DisableColoredHelp)
- }
- }
-
- /// Panic if help descriptions are omitted.
- ///
- /// **NOTE:** When deriving [`Parser`][crate::Parser], you could instead check this at
- /// compile-time with `#![deny(missing_docs)]`
- ///
- /// **NOTE:** This choice is propagated to all child subcommands.
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// Command::new("myprog")
- /// .help_expected(true)
- /// .arg(
- /// Arg::new("foo").help("It does foo stuff")
- /// // As required via `help_expected`, a help message was supplied
- /// )
- /// # .get_matches();
- /// ```
- ///
- /// # Panics
- ///
- /// ```rust,no_run
- /// # use clap::{Command, Arg};
- /// Command::new("myapp")
- /// .help_expected(true)
- /// .arg(
- /// Arg::new("foo")
- /// // Someone forgot to put .about("...") here
- /// // Since the setting `help_expected` is activated, this will lead to
- /// // a panic (if you are in debug mode)
- /// )
- /// # .get_matches();
- ///```
- #[inline]
- pub fn help_expected(self, yes: bool) -> Self {
- if yes {
- self.global_setting(AppSettings::HelpExpected)
- } else {
- self.unset_global_setting(AppSettings::HelpExpected)
- }
- }
-
- /// Disables the automatic collapsing of positional args into `[ARGS]` inside the usage string.
- ///
- /// **NOTE:** This choice is propagated to all child subcommands.
- ///
- /// # Examples
- ///
- /// ```no_run
- /// # use clap::{Command, Arg};
- /// Command::new("myprog")
- /// .dont_collapse_args_in_usage(true)
- /// .get_matches();
- /// ```
- #[inline]
- pub fn dont_collapse_args_in_usage(self, yes: bool) -> Self {
- if yes {
- self.global_setting(AppSettings::DontCollapseArgsInUsage)
- } else {
- self.unset_global_setting(AppSettings::DontCollapseArgsInUsage)
- }
- }
-
- /// Tells `clap` *not* to print possible values when displaying help information.
- ///
- /// This can be useful if there are many values, or they are explained elsewhere.
- ///
- /// To set this per argument, see
- /// [`Arg::hide_possible_values`][crate::Arg::hide_possible_values].
- ///
- /// **NOTE:** This choice is propagated to all child subcommands.
- #[inline]
- pub fn hide_possible_values(self, yes: bool) -> Self {
- if yes {
- self.global_setting(AppSettings::HidePossibleValues)
- } else {
- self.unset_global_setting(AppSettings::HidePossibleValues)
- }
- }
-
- /// Allow partial matches of long arguments or their [aliases].
- ///
- /// For example, to match an argument named `--test`, one could use `--t`, `--te`, `--tes`, and
- /// `--test`.
- ///
- /// **NOTE:** The match *must not* be ambiguous at all in order to succeed. i.e. to match
- /// `--te` to `--test` there could not also be another argument or alias `--temp` because both
- /// start with `--te`
- ///
- /// **NOTE:** This choice is propagated to all child subcommands.
- ///
- /// [aliases]: crate::Command::aliases()
- #[inline]
- pub fn infer_long_args(self, yes: bool) -> Self {
- if yes {
- self.global_setting(AppSettings::InferLongArgs)
- } else {
- self.unset_global_setting(AppSettings::InferLongArgs)
- }
- }
-
- /// Allow partial matches of [subcommand] names and their [aliases].
- ///
- /// For example, to match a subcommand named `test`, one could use `t`, `te`, `tes`, and
- /// `test`.
- ///
- /// **NOTE:** The match *must not* be ambiguous at all in order to succeed. i.e. to match `te`
- /// to `test` there could not also be a subcommand or alias `temp` because both start with `te`
- ///
- /// **CAUTION:** This setting can interfere with [positional/free arguments], take care when
- /// designing CLIs which allow inferred subcommands and have potential positional/free
- /// arguments whose values could start with the same characters as subcommands. If this is the
- /// case, it's recommended to use settings such as [`Command::args_conflicts_with_subcommands`] in
- /// conjunction with this setting.
- ///
- /// **NOTE:** This choice is propagated to all child subcommands.
- ///
- /// # Examples
- ///
- /// ```no_run
- /// # use clap::{Command, Arg};
- /// let m = Command::new("prog")
- /// .infer_subcommands(true)
- /// .subcommand(Command::new("test"))
- /// .get_matches_from(vec![
- /// "prog", "te"
- /// ]);
- /// assert_eq!(m.subcommand_name(), Some("test"));
- /// ```
- ///
- /// [subcommand]: crate::Command::subcommand()
- /// [positional/free arguments]: crate::Arg::index()
- /// [aliases]: crate::Command::aliases()
- #[inline]
- pub fn infer_subcommands(self, yes: bool) -> Self {
- if yes {
- self.global_setting(AppSettings::InferSubcommands)
- } else {
- self.unset_global_setting(AppSettings::InferSubcommands)
- }
- }
-}
-
-/// # Command-specific Settings
-///
-/// These apply only to the current command and are not inherited by subcommands.
-impl<'help> App<'help> {
- /// (Re)Sets the program's name.
- ///
- /// See [`Command::new`] for more details.
- ///
- /// # Examples
- ///
- /// ```ignore
- /// # use clap::{Command, load_yaml};
- /// let yaml = load_yaml!("cmd.yaml");
- /// let cmd = Command::from(yaml)
- /// .name(crate_name!());
- ///
- /// // continued logic goes here, such as `cmd.get_matches()` etc.
- /// ```
- #[must_use]
- pub fn name<S: Into<String>>(mut self, name: S) -> Self {
- self.name = name.into();
- self
- }
-
- /// Overrides the runtime-determined name of the binary for help and error messages.
- ///
- /// This should only be used when absolutely necessary, such as when the binary name for your
- /// application is misleading, or perhaps *not* how the user should invoke your program.
- ///
- /// **Pro-tip:** When building things such as third party `cargo`
- /// subcommands, this setting **should** be used!
- ///
- /// **NOTE:** This *does not* change or set the name of the binary file on
- /// disk. It only changes what clap thinks the name is for the purposes of
- /// error or help messages.
- ///
- /// # Examples
- ///
- /// ```no_run
- /// # use clap::Command;
- /// Command::new("My Program")
- /// .bin_name("my_binary")
- /// # ;
- /// ```
- #[must_use]
- pub fn bin_name<S: Into<String>>(mut self, name: S) -> Self {
- self.bin_name = Some(name.into());
- self
- }
-
- /// Overrides the runtime-determined display name of the program for help and error messages.
- ///
- /// # Examples
- ///
- /// ```no_run
- /// # use clap::Command;
- /// Command::new("My Program")
- /// .display_name("my_program")
- /// # ;
- /// ```
- #[must_use]
- pub fn display_name<S: Into<String>>(mut self, name: S) -> Self {
- self.display_name = Some(name.into());
- self
- }
-
- /// Sets the author(s) for the help message.
- ///
- /// **Pro-tip:** Use `clap`s convenience macro [`crate_authors!`] to
- /// automatically set your application's author(s) to the same thing as your
- /// crate at compile time.
- ///
- /// # Examples
- ///
- /// ```no_run
- /// # use clap::Command;
- /// Command::new("myprog")
- /// .author("Me, me@mymain.com")
- /// # ;
- /// ```
- /// [`crate_authors!`]: ./macro.crate_authors!.html
- #[must_use]
- pub fn author<S: Into<&'help str>>(mut self, author: S) -> Self {
- self.author = Some(author.into());
- self
- }
-
- /// Sets the program's description for the short help (`-h`).
- ///
- /// If [`Command::long_about`] is not specified, this message will be displayed for `--help`.
- ///
- /// **NOTE:** Only `Command::about` (short format) is used in completion
- /// script generation in order to be concise.
- ///
- /// See also [`crate_description!`](crate::crate_description!).
- ///
- /// # Examples
- ///
- /// ```no_run
- /// # use clap::Command;
- /// Command::new("myprog")
- /// .about("Does really amazing things for great people")
- /// # ;
- /// ```
- #[must_use]
- pub fn about<O: Into<Option<&'help str>>>(mut self, about: O) -> Self {
- self.about = about.into();
- self
- }
-
- /// Sets the program's description for the long help (`--help`).
- ///
- /// If [`Command::about`] is not specified, this message will be displayed for `-h`.
- ///
- /// **NOTE:** Only [`Command::about`] (short format) is used in completion
- /// script generation in order to be concise.
- ///
- /// # Examples
- ///
- /// ```no_run
- /// # use clap::Command;
- /// Command::new("myprog")
- /// .long_about(
- /// "Does really amazing things to great people. Now let's talk a little
- /// more in depth about how this subcommand really works. It may take about
- /// a few lines of text, but that's ok!")
- /// # ;
- /// ```
- /// [`App::about`]: Command::about()
- #[must_use]
- pub fn long_about<O: Into<Option<&'help str>>>(mut self, long_about: O) -> Self {
- self.long_about = long_about.into();
- self
- }
-
- /// Free-form help text for after auto-generated short help (`-h`).
- ///
- /// This is often used to describe how to use the arguments, caveats to be noted, or license
- /// and contact information.
- ///
- /// If [`Command::after_long_help`] is not specified, this message will be displayed for `--help`.
- ///
- /// # Examples
- ///
- /// ```no_run
- /// # use clap::Command;
- /// Command::new("myprog")
- /// .after_help("Does really amazing things for great people... but be careful with -R!")
- /// # ;
- /// ```
- ///
- #[must_use]
- pub fn after_help<S: Into<&'help str>>(mut self, help: S) -> Self {
- self.after_help = Some(help.into());
- self
- }
-
- /// Free-form help text for after auto-generated long help (`--help`).
- ///
- /// This is often used to describe how to use the arguments, caveats to be noted, or license
- /// and contact information.
- ///
- /// If [`Command::after_help`] is not specified, this message will be displayed for `-h`.
- ///
- /// # Examples
- ///
- /// ```no_run
- /// # use clap::Command;
- /// Command::new("myprog")
- /// .after_long_help("Does really amazing things to great people... but be careful with -R, \
- /// like, for real, be careful with this!")
- /// # ;
- /// ```
- #[must_use]
- pub fn after_long_help<S: Into<&'help str>>(mut self, help: S) -> Self {
- self.after_long_help = Some(help.into());
- self
- }
-
- /// Free-form help text for before auto-generated short help (`-h`).
- ///
- /// This is often used for header, copyright, or license information.
- ///
- /// If [`Command::before_long_help`] is not specified, this message will be displayed for `--help`.
- ///
- /// # Examples
- ///
- /// ```no_run
- /// # use clap::Command;
- /// Command::new("myprog")
- /// .before_help("Some info I'd like to appear before the help info")
- /// # ;
- /// ```
- #[must_use]
- pub fn before_help<S: Into<&'help str>>(mut self, help: S) -> Self {
- self.before_help = Some(help.into());
- self
- }
-
- /// Free-form help text for before auto-generated long help (`--help`).
- ///
- /// This is often used for header, copyright, or license information.
- ///
- /// If [`Command::before_help`] is not specified, this message will be displayed for `-h`.
- ///
- /// # Examples
- ///
- /// ```no_run
- /// # use clap::Command;
- /// Command::new("myprog")
- /// .before_long_help("Some verbose and long info I'd like to appear before the help info")
- /// # ;
- /// ```
- #[must_use]
- pub fn before_long_help<S: Into<&'help str>>(mut self, help: S) -> Self {
- self.before_long_help = Some(help.into());
- self
- }
-
- /// Sets the version for the short version (`-V`) and help messages.
- ///
- /// If [`Command::long_version`] is not specified, this message will be displayed for `--version`.
- ///
- /// **Pro-tip:** Use `clap`s convenience macro [`crate_version!`] to
- /// automatically set your application's version to the same thing as your
- /// crate at compile time.
- ///
- /// # Examples
- ///
- /// ```no_run
- /// # use clap::Command;
- /// Command::new("myprog")
- /// .version("v0.1.24")
- /// # ;
- /// ```
- /// [`crate_version!`]: ./macro.crate_version!.html
- #[must_use]
- pub fn version<S: Into<&'help str>>(mut self, ver: S) -> Self {
- self.version = Some(ver.into());
- self
- }
-
- /// Sets the version for the long version (`--version`) and help messages.
- ///
- /// If [`Command::version`] is not specified, this message will be displayed for `-V`.
- ///
- /// **Pro-tip:** Use `clap`s convenience macro [`crate_version!`] to
- /// automatically set your application's version to the same thing as your
- /// crate at compile time.
- ///
- /// # Examples
- ///
- /// ```no_run
- /// # use clap::Command;
- /// Command::new("myprog")
- /// .long_version(
- /// "v0.1.24
- /// commit: abcdef89726d
- /// revision: 123
- /// release: 2
- /// binary: myprog")
- /// # ;
- /// ```
- /// [`crate_version!`]: ./macro.crate_version!.html
- #[must_use]
- pub fn long_version<S: Into<&'help str>>(mut self, ver: S) -> Self {
- self.long_version = Some(ver.into());
- self
- }
-
- /// Overrides the `clap` generated usage string for help and error messages.
- ///
- /// **NOTE:** Using this setting disables `clap`s "context-aware" usage
- /// strings. After this setting is set, this will be *the only* usage string
- /// displayed to the user!
- ///
- /// **NOTE:** Multiple usage lines may be present in the usage argument, but
- /// some rules need to be followed to ensure the usage lines are formatted
- /// correctly by the default help formatter:
- ///
- /// - Do not indent the first usage line.
- /// - Indent all subsequent usage lines with four spaces.
- /// - The last line must not end with a newline.
- ///
- /// # Examples
- ///
- /// ```no_run
- /// # use clap::{Command, Arg};
- /// Command::new("myprog")
- /// .override_usage("myapp [-clDas] <some_file>")
- /// # ;
- /// ```
- ///
- /// Or for multiple usage lines:
- ///
- /// ```no_run
- /// # use clap::{Command, Arg};
- /// Command::new("myprog")
- /// .override_usage(
- /// "myapp -X [-a] [-b] <file>\n \
- /// myapp -Y [-c] <file1> <file2>\n \
- /// myapp -Z [-d|-e]"
- /// )
- /// # ;
- /// ```
- ///
- /// [`ArgMatches::usage`]: ArgMatches::usage()
- #[must_use]
- pub fn override_usage<S: Into<&'help str>>(mut self, usage: S) -> Self {
- self.usage_str = Some(usage.into());
- self
- }
-
- /// Overrides the `clap` generated help message (both `-h` and `--help`).
- ///
- /// This should only be used when the auto-generated message does not suffice.
- ///
- /// **NOTE:** This **only** replaces the help message for the current
- /// command, meaning if you are using subcommands, those help messages will
- /// still be auto-generated unless you specify a [`Command::override_help`] for
- /// them as well.
- ///
- /// # Examples
- ///
- /// ```no_run
- /// # use clap::{Command, Arg};
- /// Command::new("myapp")
- /// .override_help("myapp v1.0\n\
- /// Does awesome things\n\
- /// (C) me@mail.com\n\n\
- ///
- /// USAGE: myapp <opts> <command>\n\n\
- ///
- /// Options:\n\
- /// -h, --help Display this message\n\
- /// -V, --version Display version info\n\
- /// -s <stuff> Do something with stuff\n\
- /// -v Be verbose\n\n\
- ///
- /// Commands:\n\
- /// help Print this message\n\
- /// work Do some work")
- /// # ;
- /// ```
- #[must_use]
- pub fn override_help<S: Into<&'help str>>(mut self, help: S) -> Self {
- self.help_str = Some(help.into());
- self
- }
-
- /// Sets the help template to be used, overriding the default format.
- ///
- /// **NOTE:** The template system is by design very simple. Therefore, the
- /// tags have to be written in the lowercase and without spacing.
- ///
- /// Tags are given inside curly brackets.
- ///
- /// Valid tags are:
- ///
- /// * `{name}` - Display name for the (sub-)command.
- /// * `{bin}` - Binary name.
- /// * `{version}` - Version number.
- /// * `{author}` - Author information.
- /// * `{author-with-newline}` - Author followed by `\n`.
- /// * `{author-section}` - Author preceded and followed by `\n`.
- /// * `{about}` - General description (from [`Command::about`] or
- /// [`Command::long_about`]).
- /// * `{about-with-newline}` - About followed by `\n`.
- /// * `{about-section}` - About preceded and followed by '\n'.
- /// * `{usage-heading}` - Automatically generated usage heading.
- /// * `{usage}` - Automatically generated or given usage string.
- /// * `{all-args}` - Help for all arguments (options, flags, positional
- /// arguments, and subcommands) including titles.
- /// * `{options}` - Help for options.
- /// * `{positionals}` - Help for positional arguments.
- /// * `{subcommands}` - Help for subcommands.
- /// * `{after-help}` - Help from [`App::after_help`] or [`Command::after_long_help`].
- /// * `{before-help}` - Help from [`App::before_help`] or [`Command::before_long_help`].
- ///
- /// # Examples
- ///
- /// ```no_run
- /// # use clap::Command;
- /// Command::new("myprog")
- /// .version("1.0")
- /// .help_template("{bin} ({version}) - {usage}")
- /// # ;
- /// ```
- /// [`App::about`]: Command::about()
- /// [`App::long_about`]: Command::long_about()
- /// [`App::after_help`]: Command::after_help()
- /// [`App::after_long_help`]: Command::after_long_help()
- /// [`App::before_help`]: Command::before_help()
- /// [`App::before_long_help`]: Command::before_long_help()
- #[must_use]
- pub fn help_template<S: Into<&'help str>>(mut self, s: S) -> Self {
- self.template = Some(s.into());
- self
- }
-
- /// Apply a setting for the current command or subcommand.
- ///
- /// See [`Command::global_setting`] to apply a setting to this command and all subcommands.
- ///
- /// See [`AppSettings`] for a full list of possibilities and examples.
- ///
- /// # Examples
- ///
- /// ```no_run
- /// # use clap::{Command, AppSettings};
- /// Command::new("myprog")
- /// .setting(AppSettings::SubcommandRequired)
- /// .setting(AppSettings::AllowLeadingHyphen)
- /// # ;
- /// ```
- /// or
- /// ```no_run
- /// # use clap::{Command, AppSettings};
- /// Command::new("myprog")
- /// .setting(AppSettings::SubcommandRequired | AppSettings::AllowLeadingHyphen)
- /// # ;
- /// ```
- #[inline]
- #[must_use]
- pub fn setting<F>(mut self, setting: F) -> Self
- where
- F: Into<AppFlags>,
- {
- self.settings.insert(setting.into());
- self
- }
-
- /// Remove a setting for the current command or subcommand.
- ///
- /// See [`AppSettings`] for a full list of possibilities and examples.
- ///
- /// # Examples
- ///
- /// ```no_run
- /// # use clap::{Command, AppSettings};
- /// Command::new("myprog")
- /// .unset_setting(AppSettings::SubcommandRequired)
- /// .setting(AppSettings::AllowLeadingHyphen)
- /// # ;
- /// ```
- /// or
- /// ```no_run
- /// # use clap::{Command, AppSettings};
- /// Command::new("myprog")
- /// .unset_setting(AppSettings::SubcommandRequired | AppSettings::AllowLeadingHyphen)
- /// # ;
- /// ```
- #[inline]
- #[must_use]
- pub fn unset_setting<F>(mut self, setting: F) -> Self
- where
- F: Into<AppFlags>,
- {
- self.settings.remove(setting.into());
- self
- }
-
- /// Apply a setting for the current command and all subcommands.
- ///
- /// See [`Command::setting`] to apply a setting only to this command.
- ///
- /// See [`AppSettings`] for a full list of possibilities and examples.
- ///
- /// # Examples
- ///
- /// ```no_run
- /// # use clap::{Command, AppSettings};
- /// Command::new("myprog")
- /// .global_setting(AppSettings::AllowNegativeNumbers)
- /// # ;
- /// ```
- #[inline]
- #[must_use]
- pub fn global_setting(mut self, setting: AppSettings) -> Self {
- self.settings.set(setting);
- self.g_settings.set(setting);
- self
- }
-
- /// Remove a setting and stop propagating down to subcommands.
- ///
- /// See [`AppSettings`] for a full list of possibilities and examples.
- ///
- /// # Examples
- ///
- /// ```no_run
- /// # use clap::{Command, AppSettings};
- /// Command::new("myprog")
- /// .unset_global_setting(AppSettings::AllowNegativeNumbers)
- /// # ;
- /// ```
- /// [global]: Command::global_setting()
- #[inline]
- #[must_use]
- pub fn unset_global_setting(mut self, setting: AppSettings) -> Self {
- self.settings.unset(setting);
- self.g_settings.unset(setting);
- self
- }
-
- /// Deprecated, replaced with [`Command::next_help_heading`]
- #[inline]
- #[must_use]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.1.0", note = "Replaced with `App::next_help_heading`")
- )]
- pub fn help_heading<O>(self, heading: O) -> Self
- where
- O: Into<Option<&'help str>>,
- {
- self.next_help_heading(heading)
- }
-
- /// Set the default section heading for future args.
- ///
- /// This will be used for any arg that hasn't had [`Arg::help_heading`] called.
- ///
- /// This is useful if the default `OPTIONS` or `ARGS` headings are
- /// not specific enough for one's use case.
- ///
- /// For subcommands, see [`Command::subcommand_help_heading`]
- ///
- /// [`App::arg`]: Command::arg()
- /// [`Arg::help_heading`]: crate::Arg::help_heading()
- #[inline]
- #[must_use]
- pub fn next_help_heading<O>(mut self, heading: O) -> Self
- where
- O: Into<Option<&'help str>>,
- {
- self.current_help_heading = heading.into();
- self
- }
-
- /// Change the starting value for assigning future display orders for ags.
- ///
- /// This will be used for any arg that hasn't had [`Arg::display_order`] called.
- #[inline]
- #[must_use]
- pub fn next_display_order(mut self, disp_ord: impl Into<Option<usize>>) -> Self {
- self.current_disp_ord = disp_ord.into();
- self
- }
-
- /// Replaces an argument or subcommand used on the CLI at runtime with other arguments or subcommands.
- ///
- /// **Note:** This is gated behind [`unstable-replace`](https://github.com/clap-rs/clap/issues/2836)
- ///
- /// When this method is used, `name` is removed from the CLI, and `target`
- /// is inserted in its place. Parsing continues as if the user typed
- /// `target` instead of `name`.
- ///
- /// This can be used to create "shortcuts" for subcommands, or if a
- /// particular argument has the semantic meaning of several other specific
- /// arguments and values.
- ///
- /// # Examples
- ///
- /// We'll start with the "subcommand short" example. In this example, let's
- /// assume we have a program with a subcommand `module` which can be invoked
- /// via `cmd module`. Now let's also assume `module` also has a subcommand
- /// called `install` which can be invoked `cmd module install`. If for some
- /// reason users needed to be able to reach `cmd module install` via the
- /// short-hand `cmd install`, we'd have several options.
- ///
- /// We *could* create another sibling subcommand to `module` called
- /// `install`, but then we would need to manage another subcommand and manually
- /// dispatch to `cmd module install` handling code. This is error prone and
- /// tedious.
- ///
- /// We could instead use [`Command::replace`] so that, when the user types `cmd
- /// install`, `clap` will replace `install` with `module install` which will
- /// end up getting parsed as if the user typed the entire incantation.
- ///
- /// ```rust
- /// # use clap::Command;
- /// let m = Command::new("cmd")
- /// .subcommand(Command::new("module")
- /// .subcommand(Command::new("install")))
- /// .replace("install", &["module", "install"])
- /// .get_matches_from(vec!["cmd", "install"]);
- ///
- /// assert!(m.subcommand_matches("module").is_some());
- /// assert!(m.subcommand_matches("module").unwrap().subcommand_matches("install").is_some());
- /// ```
- ///
- /// Now let's show an argument example!
- ///
- /// Let's assume we have an application with two flags `--save-context` and
- /// `--save-runtime`. But often users end up needing to do *both* at the
- /// same time. We can add a third flag `--save-all` which semantically means
- /// the same thing as `cmd --save-context --save-runtime`. To implement that,
- /// we have several options.
- ///
- /// We could create this third argument and manually check if that argument
- /// and in our own consumer code handle the fact that both `--save-context`
- /// and `--save-runtime` *should* have been used. But again this is error
- /// prone and tedious. If we had code relying on checking `--save-context`
- /// and we forgot to update that code to *also* check `--save-all` it'd mean
- /// an error!
- ///
- /// Luckily we can use [`Command::replace`] so that when the user types
- /// `--save-all`, `clap` will replace that argument with `--save-context
- /// --save-runtime`, and parsing will continue like normal. Now all our code
- /// that was originally checking for things like `--save-context` doesn't
- /// need to change!
- ///
- /// ```rust
- /// # use clap::{Command, Arg, ArgAction};
- /// let m = Command::new("cmd")
- /// .arg(Arg::new("save-context")
- /// .long("save-context")
- /// .action(ArgAction::SetTrue))
- /// .arg(Arg::new("save-runtime")
- /// .long("save-runtime")
- /// .action(ArgAction::SetTrue))
- /// .replace("--save-all", &["--save-context", "--save-runtime"])
- /// .get_matches_from(vec!["cmd", "--save-all"]);
- ///
- /// assert!(*m.get_one::<bool>("save-context").expect("defaulted by clap"));
- /// assert!(*m.get_one::<bool>("save-runtime").expect("defaulted by clap"));
- /// ```
- ///
- /// This can also be used with options, for example if our application with
- /// `--save-*` above also had a `--format=TYPE` option. Let's say it
- /// accepted `txt` or `json` values. However, when `--save-all` is used,
- /// only `--format=json` is allowed, or valid. We could change the example
- /// above to enforce this:
- ///
- /// ```rust
- /// # use clap::{Command, Arg, ArgAction};
- /// let m = Command::new("cmd")
- /// .arg(Arg::new("save-context")
- /// .long("save-context")
- /// .action(ArgAction::SetTrue))
- /// .arg(Arg::new("save-runtime")
- /// .long("save-runtime")
- /// .action(ArgAction::SetTrue))
- /// .arg(Arg::new("format")
- /// .long("format")
- /// .takes_value(true)
- /// .value_parser(["txt", "json"]))
- /// .replace("--save-all", &["--save-context", "--save-runtime", "--format=json"])
- /// .get_matches_from(vec!["cmd", "--save-all"]);
- ///
- /// assert!(*m.get_one::<bool>("save-context").expect("defaulted by clap"));
- /// assert!(*m.get_one::<bool>("save-runtime").expect("defaulted by clap"));
- /// assert_eq!(m.value_of("format"), Some("json"));
- /// ```
- ///
- /// [`App::replace`]: Command::replace()
- #[inline]
- #[cfg(feature = "unstable-replace")]
- #[must_use]
- pub fn replace(mut self, name: &'help str, target: &'help [&'help str]) -> Self {
- self.replacers.insert(name, target);
- self
- }
-
- /// Exit gracefully if no arguments are present (e.g. `$ myprog`).
- ///
- /// **NOTE:** [`subcommands`] count as arguments
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Command};
- /// Command::new("myprog")
- /// .arg_required_else_help(true);
- /// ```
- ///
- /// [`subcommands`]: crate::Command::subcommand()
- /// [`Arg::default_value`]: crate::Arg::default_value()
- #[inline]
- pub fn arg_required_else_help(self, yes: bool) -> Self {
- if yes {
- self.setting(AppSettings::ArgRequiredElseHelp)
- } else {
- self.unset_setting(AppSettings::ArgRequiredElseHelp)
- }
- }
-
- /// Specifies that leading hyphens are allowed in all argument *values* (e.g. `-10`).
- ///
- /// Otherwise they will be parsed as another flag or option. See also
- /// [`Command::allow_negative_numbers`].
- ///
- /// **NOTE:** Use this setting with caution as it silences certain circumstances which would
- /// otherwise be an error (such as accidentally forgetting to specify a value for leading
- /// option). It is preferred to set this on a per argument basis, via [`Arg::allow_hyphen_values`].
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Arg, Command};
- /// // Imagine you needed to represent negative numbers as well, such as -10
- /// let m = Command::new("nums")
- /// .allow_hyphen_values(true)
- /// .arg(Arg::new("neg"))
- /// .get_matches_from(vec![
- /// "nums", "-20"
- /// ]);
- ///
- /// assert_eq!(m.value_of("neg"), Some("-20"));
- /// # ;
- /// ```
- /// [`Arg::allow_hyphen_values`]: crate::Arg::allow_hyphen_values()
- #[inline]
- pub fn allow_hyphen_values(self, yes: bool) -> Self {
- if yes {
- self.setting(AppSettings::AllowHyphenValues)
- } else {
- self.unset_setting(AppSettings::AllowHyphenValues)
- }
- }
-
- /// Allows negative numbers to pass as values.
- ///
- /// This is similar to [`Command::allow_hyphen_values`] except that it only allows numbers,
- /// all other undefined leading hyphens will fail to parse.
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// let res = Command::new("myprog")
- /// .allow_negative_numbers(true)
- /// .arg(Arg::new("num"))
- /// .try_get_matches_from(vec![
- /// "myprog", "-20"
- /// ]);
- /// assert!(res.is_ok());
- /// let m = res.unwrap();
- /// assert_eq!(m.value_of("num").unwrap(), "-20");
- /// ```
- #[inline]
- pub fn allow_negative_numbers(self, yes: bool) -> Self {
- if yes {
- self.setting(AppSettings::AllowNegativeNumbers)
- } else {
- self.unset_setting(AppSettings::AllowNegativeNumbers)
- }
- }
-
- /// Specifies that the final positional argument is a "VarArg" and that `clap` should not
- /// attempt to parse any further args.
- ///
- /// The values of the trailing positional argument will contain all args from itself on.
- ///
- /// **NOTE:** The final positional argument **must** have [`Arg::multiple_values(true)`] or the usage
- /// string equivalent.
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Command, arg};
- /// let m = Command::new("myprog")
- /// .trailing_var_arg(true)
- /// .arg(arg!(<cmd> ... "commands to run"))
- /// .get_matches_from(vec!["myprog", "arg1", "-r", "val1"]);
- ///
- /// let trail: Vec<&str> = m.values_of("cmd").unwrap().collect();
- /// assert_eq!(trail, ["arg1", "-r", "val1"]);
- /// ```
- /// [`Arg::multiple_values(true)`]: crate::Arg::multiple_values()
- pub fn trailing_var_arg(self, yes: bool) -> Self {
- if yes {
- self.setting(AppSettings::TrailingVarArg)
- } else {
- self.unset_setting(AppSettings::TrailingVarArg)
- }
- }
-
- /// Allows one to implement two styles of CLIs where positionals can be used out of order.
- ///
- /// The first example is a CLI where the second to last positional argument is optional, but
- /// the final positional argument is required. Such as `$ prog [optional] <required>` where one
- /// of the two following usages is allowed:
- ///
- /// * `$ prog [optional] <required>`
- /// * `$ prog <required>`
- ///
- /// This would otherwise not be allowed. This is useful when `[optional]` has a default value.
- ///
- /// **Note:** when using this style of "missing positionals" the final positional *must* be
- /// [required] if `--` will not be used to skip to the final positional argument.
- ///
- /// **Note:** This style also only allows a single positional argument to be "skipped" without
- /// the use of `--`. To skip more than one, see the second example.
- ///
- /// The second example is when one wants to skip multiple optional positional arguments, and use
- /// of the `--` operator is OK (but not required if all arguments will be specified anyways).
- ///
- /// For example, imagine a CLI which has three positional arguments `[foo] [bar] [baz]...` where
- /// `baz` accepts multiple values (similar to man `ARGS...` style training arguments).
- ///
- /// With this setting the following invocations are posisble:
- ///
- /// * `$ prog foo bar baz1 baz2 baz3`
- /// * `$ prog foo -- baz1 baz2 baz3`
- /// * `$ prog -- baz1 baz2 baz3`
- ///
- /// # Examples
- ///
- /// Style number one from above:
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// // Assume there is an external subcommand named "subcmd"
- /// let m = Command::new("myprog")
- /// .allow_missing_positional(true)
- /// .arg(Arg::new("arg1"))
- /// .arg(Arg::new("arg2")
- /// .required(true))
- /// .get_matches_from(vec![
- /// "prog", "other"
- /// ]);
- ///
- /// assert_eq!(m.value_of("arg1"), None);
- /// assert_eq!(m.value_of("arg2"), Some("other"));
- /// ```
- ///
- /// Now the same example, but using a default value for the first optional positional argument
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// // Assume there is an external subcommand named "subcmd"
- /// let m = Command::new("myprog")
- /// .allow_missing_positional(true)
- /// .arg(Arg::new("arg1")
- /// .default_value("something"))
- /// .arg(Arg::new("arg2")
- /// .required(true))
- /// .get_matches_from(vec![
- /// "prog", "other"
- /// ]);
- ///
- /// assert_eq!(m.value_of("arg1"), Some("something"));
- /// assert_eq!(m.value_of("arg2"), Some("other"));
- /// ```
- ///
- /// Style number two from above:
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// // Assume there is an external subcommand named "subcmd"
- /// let m = Command::new("myprog")
- /// .allow_missing_positional(true)
- /// .arg(Arg::new("foo"))
- /// .arg(Arg::new("bar"))
- /// .arg(Arg::new("baz").takes_value(true).multiple_values(true))
- /// .get_matches_from(vec![
- /// "prog", "foo", "bar", "baz1", "baz2", "baz3"
- /// ]);
- ///
- /// assert_eq!(m.value_of("foo"), Some("foo"));
- /// assert_eq!(m.value_of("bar"), Some("bar"));
- /// assert_eq!(m.values_of("baz").unwrap().collect::<Vec<_>>(), &["baz1", "baz2", "baz3"]);
- /// ```
- ///
- /// Now nofice if we don't specify `foo` or `baz` but use the `--` operator.
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// // Assume there is an external subcommand named "subcmd"
- /// let m = Command::new("myprog")
- /// .allow_missing_positional(true)
- /// .arg(Arg::new("foo"))
- /// .arg(Arg::new("bar"))
- /// .arg(Arg::new("baz").takes_value(true).multiple_values(true))
- /// .get_matches_from(vec![
- /// "prog", "--", "baz1", "baz2", "baz3"
- /// ]);
- ///
- /// assert_eq!(m.value_of("foo"), None);
- /// assert_eq!(m.value_of("bar"), None);
- /// assert_eq!(m.values_of("baz").unwrap().collect::<Vec<_>>(), &["baz1", "baz2", "baz3"]);
- /// ```
- ///
- /// [required]: crate::Arg::required()
- #[inline]
- pub fn allow_missing_positional(self, yes: bool) -> Self {
- if yes {
- self.setting(AppSettings::AllowMissingPositional)
- } else {
- self.unset_setting(AppSettings::AllowMissingPositional)
- }
- }
-}
-
-/// # Subcommand-specific Settings
-impl<'help> App<'help> {
- /// Sets the short version of the subcommand flag without the preceding `-`.
- ///
- /// Allows the subcommand to be used as if it were an [`Arg::short`].
- ///
- /// # Examples
- ///
- /// ```
- /// # use clap::{Command, Arg, ArgAction};
- /// let matches = Command::new("pacman")
- /// .subcommand(
- /// Command::new("sync").short_flag('S').arg(
- /// Arg::new("search")
- /// .short('s')
- /// .long("search")
- /// .action(ArgAction::SetTrue)
- /// .help("search remote repositories for matching strings"),
- /// ),
- /// )
- /// .get_matches_from(vec!["pacman", "-Ss"]);
- ///
- /// assert_eq!(matches.subcommand_name().unwrap(), "sync");
- /// let sync_matches = matches.subcommand_matches("sync").unwrap();
- /// assert!(*sync_matches.get_one::<bool>("search").expect("defaulted by clap"));
- /// ```
- /// [`Arg::short`]: Arg::short()
- #[must_use]
- pub fn short_flag(mut self, short: char) -> Self {
- self.short_flag = Some(short);
- self
- }
-
- /// Sets the long version of the subcommand flag without the preceding `--`.
- ///
- /// Allows the subcommand to be used as if it were an [`Arg::long`].
- ///
- /// **NOTE:** Any leading `-` characters will be stripped.
- ///
- /// # Examples
- ///
- /// To set `long_flag` use a word containing valid UTF-8 codepoints. If you supply a double leading
- /// `--` such as `--sync` they will be stripped. Hyphens in the middle of the word; however,
- /// will *not* be stripped (i.e. `sync-file` is allowed).
- ///
- /// ```
- /// # use clap::{Command, Arg, ArgAction};
- /// let matches = Command::new("pacman")
- /// .subcommand(
- /// Command::new("sync").long_flag("sync").arg(
- /// Arg::new("search")
- /// .short('s')
- /// .long("search")
- /// .action(ArgAction::SetTrue)
- /// .help("search remote repositories for matching strings"),
- /// ),
- /// )
- /// .get_matches_from(vec!["pacman", "--sync", "--search"]);
- ///
- /// assert_eq!(matches.subcommand_name().unwrap(), "sync");
- /// let sync_matches = matches.subcommand_matches("sync").unwrap();
- /// assert!(*sync_matches.get_one::<bool>("search").expect("defaulted by clap"));
- /// ```
- ///
- /// [`Arg::long`]: Arg::long()
- #[must_use]
- pub fn long_flag(mut self, long: &'help str) -> Self {
- #[cfg(feature = "unstable-v4")]
- {
- self.long_flag = Some(long);
- }
- #[cfg(not(feature = "unstable-v4"))]
- {
- self.long_flag = Some(long.trim_start_matches(|c| c == '-'));
- }
- self
- }
-
- /// Sets a hidden alias to this subcommand.
- ///
- /// This allows the subcommand to be accessed via *either* the original name, or this given
- /// alias. This is more efficient and easier than creating multiple hidden subcommands as one
- /// only needs to check for the existence of this command, and not all aliased variants.
- ///
- /// **NOTE:** Aliases defined with this method are *hidden* from the help
- /// message. If you're looking for aliases that will be displayed in the help
- /// message, see [`Command::visible_alias`].
- ///
- /// **NOTE:** When using aliases and checking for the existence of a
- /// particular subcommand within an [`ArgMatches`] struct, one only needs to
- /// search for the original name and not all aliases.
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Command, Arg, };
- /// let m = Command::new("myprog")
- /// .subcommand(Command::new("test")
- /// .alias("do-stuff"))
- /// .get_matches_from(vec!["myprog", "do-stuff"]);
- /// assert_eq!(m.subcommand_name(), Some("test"));
- /// ```
- /// [`App::visible_alias`]: Command::visible_alias()
- #[must_use]
- pub fn alias<S: Into<&'help str>>(mut self, name: S) -> Self {
- self.aliases.push((name.into(), false));
- self
- }
-
- /// Add an alias, which functions as "hidden" short flag subcommand
- ///
- /// This will automatically dispatch as if this subcommand was used. This is more efficient,
- /// and easier than creating multiple hidden subcommands as one only needs to check for the
- /// existence of this command, and not all variants.
- ///
- /// # Examples
- ///
- /// ```no_run
- /// # use clap::{Command, Arg, };
- /// let m = Command::new("myprog")
- /// .subcommand(Command::new("test").short_flag('t')
- /// .short_flag_alias('d'))
- /// .get_matches_from(vec!["myprog", "-d"]);
- /// assert_eq!(m.subcommand_name(), Some("test"));
- /// ```
- #[must_use]
- pub fn short_flag_alias(mut self, name: char) -> Self {
- assert!(name != '-', "short alias name cannot be `-`");
- self.short_flag_aliases.push((name, false));
- self
- }
-
- /// Add an alias, which functions as a "hidden" long flag subcommand.
- ///
- /// This will automatically dispatch as if this subcommand was used. This is more efficient,
- /// and easier than creating multiple hidden subcommands as one only needs to check for the
- /// existence of this command, and not all variants.
- ///
- /// # Examples
- ///
- /// ```no_run
- /// # use clap::{Command, Arg, };
- /// let m = Command::new("myprog")
- /// .subcommand(Command::new("test").long_flag("test")
- /// .long_flag_alias("testing"))
- /// .get_matches_from(vec!["myprog", "--testing"]);
- /// assert_eq!(m.subcommand_name(), Some("test"));
- /// ```
- #[must_use]
- pub fn long_flag_alias(mut self, name: &'help str) -> Self {
- self.long_flag_aliases.push((name, false));
- self
- }
-
- /// Sets multiple hidden aliases to this subcommand.
- ///
- /// This allows the subcommand to be accessed via *either* the original name or any of the
- /// given aliases. This is more efficient, and easier than creating multiple hidden subcommands
- /// as one only needs to check for the existence of this command and not all aliased variants.
- ///
- /// **NOTE:** Aliases defined with this method are *hidden* from the help
- /// message. If looking for aliases that will be displayed in the help
- /// message, see [`Command::visible_aliases`].
- ///
- /// **NOTE:** When using aliases and checking for the existence of a
- /// particular subcommand within an [`ArgMatches`] struct, one only needs to
- /// search for the original name and not all aliases.
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// let m = Command::new("myprog")
- /// .subcommand(Command::new("test")
- /// .aliases(&["do-stuff", "do-tests", "tests"]))
- /// .arg(Arg::new("input")
- /// .help("the file to add")
- /// .required(false))
- /// .get_matches_from(vec!["myprog", "do-tests"]);
- /// assert_eq!(m.subcommand_name(), Some("test"));
- /// ```
- /// [`App::visible_aliases`]: Command::visible_aliases()
- #[must_use]
- pub fn aliases(mut self, names: &[&'help str]) -> Self {
- self.aliases.extend(names.iter().map(|n| (*n, false)));
- self
- }
-
- /// Add aliases, which function as "hidden" short flag subcommands.
- ///
- /// These will automatically dispatch as if this subcommand was used. This is more efficient,
- /// and easier than creating multiple hidden subcommands as one only needs to check for the
- /// existence of this command, and not all variants.
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Command, Arg, };
- /// let m = Command::new("myprog")
- /// .subcommand(Command::new("test").short_flag('t')
- /// .short_flag_aliases(&['a', 'b', 'c']))
- /// .arg(Arg::new("input")
- /// .help("the file to add")
- /// .required(false))
- /// .get_matches_from(vec!["myprog", "-a"]);
- /// assert_eq!(m.subcommand_name(), Some("test"));
- /// ```
- #[must_use]
- pub fn short_flag_aliases(mut self, names: &[char]) -> Self {
- for s in names {
- assert!(s != &'-', "short alias name cannot be `-`");
- self.short_flag_aliases.push((*s, false));
- }
- self
- }
-
- /// Add aliases, which function as "hidden" long flag subcommands.
- ///
- /// These will automatically dispatch as if this subcommand was used. This is more efficient,
- /// and easier than creating multiple hidden subcommands as one only needs to check for the
- /// existence of this command, and not all variants.
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Command, Arg, };
- /// let m = Command::new("myprog")
- /// .subcommand(Command::new("test").long_flag("test")
- /// .long_flag_aliases(&["testing", "testall", "test_all"]))
- /// .arg(Arg::new("input")
- /// .help("the file to add")
- /// .required(false))
- /// .get_matches_from(vec!["myprog", "--testing"]);
- /// assert_eq!(m.subcommand_name(), Some("test"));
- /// ```
- #[must_use]
- pub fn long_flag_aliases(mut self, names: &[&'help str]) -> Self {
- for s in names {
- self.long_flag_aliases.push((s, false));
- }
- self
- }
-
- /// Sets a visible alias to this subcommand.
- ///
- /// This allows the subcommand to be accessed via *either* the
- /// original name or the given alias. This is more efficient and easier
- /// than creating hidden subcommands as one only needs to check for
- /// the existence of this command and not all aliased variants.
- ///
- /// **NOTE:** The alias defined with this method is *visible* from the help
- /// message and displayed as if it were just another regular subcommand. If
- /// looking for an alias that will not be displayed in the help message, see
- /// [`Command::alias`].
- ///
- /// **NOTE:** When using aliases and checking for the existence of a
- /// particular subcommand within an [`ArgMatches`] struct, one only needs to
- /// search for the original name and not all aliases.
- ///
- /// # Examples
- ///
- /// ```no_run
- /// # use clap::{Command, Arg};
- /// let m = Command::new("myprog")
- /// .subcommand(Command::new("test")
- /// .visible_alias("do-stuff"))
- /// .get_matches_from(vec!["myprog", "do-stuff"]);
- /// assert_eq!(m.subcommand_name(), Some("test"));
- /// ```
- /// [`App::alias`]: Command::alias()
- #[must_use]
- pub fn visible_alias<S: Into<&'help str>>(mut self, name: S) -> Self {
- self.aliases.push((name.into(), true));
- self
- }
-
- /// Add an alias, which functions as "visible" short flag subcommand
- ///
- /// This will automatically dispatch as if this subcommand was used. This is more efficient,
- /// and easier than creating multiple hidden subcommands as one only needs to check for the
- /// existence of this command, and not all variants.
- ///
- /// See also [`Command::short_flag_alias`].
- ///
- /// # Examples
- ///
- /// ```no_run
- /// # use clap::{Command, Arg, };
- /// let m = Command::new("myprog")
- /// .subcommand(Command::new("test").short_flag('t')
- /// .visible_short_flag_alias('d'))
- /// .get_matches_from(vec!["myprog", "-d"]);
- /// assert_eq!(m.subcommand_name(), Some("test"));
- /// ```
- /// [`App::short_flag_alias`]: Command::short_flag_alias()
- #[must_use]
- pub fn visible_short_flag_alias(mut self, name: char) -> Self {
- assert!(name != '-', "short alias name cannot be `-`");
- self.short_flag_aliases.push((name, true));
- self
- }
-
- /// Add an alias, which functions as a "visible" long flag subcommand.
- ///
- /// This will automatically dispatch as if this subcommand was used. This is more efficient,
- /// and easier than creating multiple hidden subcommands as one only needs to check for the
- /// existence of this command, and not all variants.
- ///
- /// See also [`Command::long_flag_alias`].
- ///
- /// # Examples
- ///
- /// ```no_run
- /// # use clap::{Command, Arg, };
- /// let m = Command::new("myprog")
- /// .subcommand(Command::new("test").long_flag("test")
- /// .visible_long_flag_alias("testing"))
- /// .get_matches_from(vec!["myprog", "--testing"]);
- /// assert_eq!(m.subcommand_name(), Some("test"));
- /// ```
- /// [`App::long_flag_alias`]: Command::long_flag_alias()
- #[must_use]
- pub fn visible_long_flag_alias(mut self, name: &'help str) -> Self {
- self.long_flag_aliases.push((name, true));
- self
- }
-
- /// Sets multiple visible aliases to this subcommand.
- ///
- /// This allows the subcommand to be accessed via *either* the
- /// original name or any of the given aliases. This is more efficient and easier
- /// than creating multiple hidden subcommands as one only needs to check for
- /// the existence of this command and not all aliased variants.
- ///
- /// **NOTE:** The alias defined with this method is *visible* from the help
- /// message and displayed as if it were just another regular subcommand. If
- /// looking for an alias that will not be displayed in the help message, see
- /// [`Command::alias`].
- ///
- /// **NOTE:** When using aliases, and checking for the existence of a
- /// particular subcommand within an [`ArgMatches`] struct, one only needs to
- /// search for the original name and not all aliases.
- ///
- /// # Examples
- ///
- /// ```no_run
- /// # use clap::{Command, Arg, };
- /// let m = Command::new("myprog")
- /// .subcommand(Command::new("test")
- /// .visible_aliases(&["do-stuff", "tests"]))
- /// .get_matches_from(vec!["myprog", "do-stuff"]);
- /// assert_eq!(m.subcommand_name(), Some("test"));
- /// ```
- /// [`App::alias`]: Command::alias()
- #[must_use]
- pub fn visible_aliases(mut self, names: &[&'help str]) -> Self {
- self.aliases.extend(names.iter().map(|n| (*n, true)));
- self
- }
-
- /// Add aliases, which function as *visible* short flag subcommands.
- ///
- /// See [`Command::short_flag_aliases`].
- ///
- /// # Examples
- ///
- /// ```no_run
- /// # use clap::{Command, Arg, };
- /// let m = Command::new("myprog")
- /// .subcommand(Command::new("test").short_flag('b')
- /// .visible_short_flag_aliases(&['t']))
- /// .get_matches_from(vec!["myprog", "-t"]);
- /// assert_eq!(m.subcommand_name(), Some("test"));
- /// ```
- /// [`App::short_flag_aliases`]: Command::short_flag_aliases()
- #[must_use]
- pub fn visible_short_flag_aliases(mut self, names: &[char]) -> Self {
- for s in names {
- assert!(s != &'-', "short alias name cannot be `-`");
- self.short_flag_aliases.push((*s, true));
- }
- self
- }
-
- /// Add aliases, which function as *visible* long flag subcommands.
- ///
- /// See [`Command::long_flag_aliases`].
- ///
- /// # Examples
- ///
- /// ```no_run
- /// # use clap::{Command, Arg, };
- /// let m = Command::new("myprog")
- /// .subcommand(Command::new("test").long_flag("test")
- /// .visible_long_flag_aliases(&["testing", "testall", "test_all"]))
- /// .get_matches_from(vec!["myprog", "--testing"]);
- /// assert_eq!(m.subcommand_name(), Some("test"));
- /// ```
- /// [`App::long_flag_aliases`]: Command::long_flag_aliases()
- #[must_use]
- pub fn visible_long_flag_aliases(mut self, names: &[&'help str]) -> Self {
- for s in names {
- self.long_flag_aliases.push((s, true));
- }
- self
- }
-
- /// Set the placement of this subcommand within the help.
- ///
- /// Subcommands with a lower value will be displayed first in the help message. Subcommands
- /// with duplicate display orders will be displayed in alphabetical order.
- ///
- /// This is helpful when one would like to emphasize frequently used subcommands, or prioritize
- /// those towards the top of the list.
- ///
- /// **NOTE:** The default is 999 for all subcommands.
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Command, };
- /// let m = Command::new("cust-ord")
- /// .subcommand(Command::new("alpha") // typically subcommands are grouped
- /// // alphabetically by name. Subcommands
- /// // without a display_order have a value of
- /// // 999 and are displayed alphabetically with
- /// // all other 999 subcommands
- /// .about("Some help and text"))
- /// .subcommand(Command::new("beta")
- /// .display_order(1) // In order to force this subcommand to appear *first*
- /// // all we have to do is give it a value lower than 999.
- /// // Any other subcommands with a value of 1 will be displayed
- /// // alphabetically with this one...then 2 values, then 3, etc.
- /// .about("I should be first!"))
- /// .get_matches_from(vec![
- /// "cust-ord", "--help"
- /// ]);
- /// ```
- ///
- /// The above example displays the following help message
- ///
- /// ```text
- /// cust-ord
- ///
- /// USAGE:
- /// cust-ord [OPTIONS]
- ///
- /// OPTIONS:
- /// -h, --help Print help information
- /// -V, --version Print version information
- ///
- /// SUBCOMMANDS:
- /// beta I should be first!
- /// alpha Some help and text
- /// ```
- #[inline]
- #[must_use]
- pub fn display_order(mut self, ord: usize) -> Self {
- self.disp_ord = Some(ord);
- self
- }
-
- /// Specifies that this [`subcommand`] should be hidden from help messages
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// Command::new("myprog")
- /// .subcommand(
- /// Command::new("test").hide(true)
- /// )
- /// # ;
- /// ```
- ///
- /// [`subcommand`]: crate::Command::subcommand()
- #[inline]
- pub fn hide(self, yes: bool) -> Self {
- if yes {
- self.setting(AppSettings::Hidden)
- } else {
- self.unset_setting(AppSettings::Hidden)
- }
- }
-
- /// If no [`subcommand`] is present at runtime, error and exit gracefully.
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Command, ErrorKind};
- /// let err = Command::new("myprog")
- /// .subcommand_required(true)
- /// .subcommand(Command::new("test"))
- /// .try_get_matches_from(vec![
- /// "myprog",
- /// ]);
- /// assert!(err.is_err());
- /// assert_eq!(err.unwrap_err().kind(), ErrorKind::MissingSubcommand);
- /// # ;
- /// ```
- ///
- /// [`subcommand`]: crate::Command::subcommand()
- pub fn subcommand_required(self, yes: bool) -> Self {
- if yes {
- self.setting(AppSettings::SubcommandRequired)
- } else {
- self.unset_setting(AppSettings::SubcommandRequired)
- }
- }
-
- /// Assume unexpected positional arguments are a [`subcommand`].
- ///
- /// Arguments will be stored in the `""` argument in the [`ArgMatches`]
- ///
- /// **NOTE:** Use this setting with caution,
- /// as a truly unexpected argument (i.e. one that is *NOT* an external subcommand)
- /// will **not** cause an error and instead be treated as a potential subcommand.
- /// One should check for such cases manually and inform the user appropriately.
- ///
- /// **NOTE:** A built-in subcommand will be parsed as an external subcommand when escaped with
- /// `--`.
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::Command;
- /// // Assume there is an external subcommand named "subcmd"
- /// let m = Command::new("myprog")
- /// .allow_external_subcommands(true)
- /// .get_matches_from(vec![
- /// "myprog", "subcmd", "--option", "value", "-fff", "--flag"
- /// ]);
- ///
- /// // All trailing arguments will be stored under the subcommand's sub-matches using an empty
- /// // string argument name
- /// match m.subcommand() {
- /// Some((external, ext_m)) => {
- /// let ext_args: Vec<&str> = ext_m.values_of("").unwrap().collect();
- /// assert_eq!(external, "subcmd");
- /// assert_eq!(ext_args, ["--option", "value", "-fff", "--flag"]);
- /// },
- /// _ => {},
- /// }
- /// ```
- ///
- /// [`subcommand`]: crate::Command::subcommand()
- /// [`ArgMatches`]: crate::ArgMatches
- /// [`ErrorKind::UnknownArgument`]: crate::ErrorKind::UnknownArgument
- pub fn allow_external_subcommands(self, yes: bool) -> Self {
- if yes {
- self.setting(AppSettings::AllowExternalSubcommands)
- } else {
- self.unset_setting(AppSettings::AllowExternalSubcommands)
- }
- }
-
- /// Specifies that external subcommands that are invalid UTF-8 should *not* be treated as an error.
- ///
- /// **NOTE:** Using external subcommand argument values with invalid UTF-8 requires using
- /// [`ArgMatches::values_of_os`] or [`ArgMatches::values_of_lossy`] for those particular
- /// arguments which may contain invalid UTF-8 values
- ///
- /// **NOTE:** Setting this requires [`Command::allow_external_subcommands`]
- ///
- /// # Platform Specific
- ///
- /// Non Windows systems only
- ///
- /// # Examples
- ///
- #[cfg_attr(not(unix), doc = " ```ignore")]
- #[cfg_attr(unix, doc = " ```")]
- /// # use clap::Command;
- /// // Assume there is an external subcommand named "subcmd"
- /// let m = Command::new("myprog")
- /// .allow_invalid_utf8_for_external_subcommands(true)
- /// .allow_external_subcommands(true)
- /// .get_matches_from(vec![
- /// "myprog", "subcmd", "--option", "value", "-fff", "--flag"
- /// ]);
- ///
- /// // All trailing arguments will be stored under the subcommand's sub-matches using an empty
- /// // string argument name
- /// match m.subcommand() {
- /// Some((external, ext_m)) => {
- /// let ext_args: Vec<&std::ffi::OsStr> = ext_m.values_of_os("").unwrap().collect();
- /// assert_eq!(external, "subcmd");
- /// assert_eq!(ext_args, ["--option", "value", "-fff", "--flag"]);
- /// },
- /// _ => {},
- /// }
- /// ```
- ///
- /// [`ArgMatches::values_of_os`]: crate::ArgMatches::values_of_os()
- /// [`ArgMatches::values_of_lossy`]: crate::ArgMatches::values_of_lossy()
- /// [`subcommands`]: crate::Command::subcommand()
- pub fn allow_invalid_utf8_for_external_subcommands(self, yes: bool) -> Self {
- if yes {
- self.setting(AppSettings::AllowInvalidUtf8ForExternalSubcommands)
- } else {
- self.unset_setting(AppSettings::AllowInvalidUtf8ForExternalSubcommands)
- }
- }
-
- /// Specifies that use of an argument prevents the use of [`subcommands`].
- ///
- /// By default `clap` allows arguments between subcommands such
- /// as `<cmd> [cmd_args] <subcmd> [subcmd_args] <subsubcmd> [subsubcmd_args]`.
- ///
- /// This setting disables that functionality and says that arguments can
- /// only follow the *final* subcommand. For instance using this setting
- /// makes only the following invocations possible:
- ///
- /// * `<cmd> <subcmd> <subsubcmd> [subsubcmd_args]`
- /// * `<cmd> <subcmd> [subcmd_args]`
- /// * `<cmd> [cmd_args]`
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::Command;
- /// Command::new("myprog")
- /// .args_conflicts_with_subcommands(true);
- /// ```
- ///
- /// [`subcommands`]: crate::Command::subcommand()
- pub fn args_conflicts_with_subcommands(self, yes: bool) -> Self {
- if yes {
- self.setting(AppSettings::ArgsNegateSubcommands)
- } else {
- self.unset_setting(AppSettings::ArgsNegateSubcommands)
- }
- }
-
- /// Prevent subcommands from being consumed as an arguments value.
- ///
- /// By default, if an option taking multiple values is followed by a subcommand, the
- /// subcommand will be parsed as another value.
- ///
- /// ```text
- /// cmd --foo val1 val2 subcommand
- /// --------- ----------
- /// values another value
- /// ```
- ///
- /// This setting instructs the parser to stop when encountering a subcommand instead of
- /// greedily consuming arguments.
- ///
- /// ```text
- /// cmd --foo val1 val2 subcommand
- /// --------- ----------
- /// values subcommand
- /// ```
- ///
- /// **Note:** Make sure you apply it as `global_setting` if you want this setting
- /// to be propagated to subcommands and sub-subcommands!
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::{Command, Arg};
- /// let cmd = Command::new("cmd").subcommand(Command::new("sub")).arg(
- /// Arg::new("arg")
- /// .long("arg")
- /// .multiple_values(true)
- /// .takes_value(true),
- /// );
- ///
- /// let matches = cmd
- /// .clone()
- /// .try_get_matches_from(&["cmd", "--arg", "1", "2", "3", "sub"])
- /// .unwrap();
- /// assert_eq!(
- /// matches.values_of("arg").unwrap().collect::<Vec<_>>(),
- /// &["1", "2", "3", "sub"]
- /// );
- /// assert!(matches.subcommand_matches("sub").is_none());
- ///
- /// let matches = cmd
- /// .subcommand_precedence_over_arg(true)
- /// .try_get_matches_from(&["cmd", "--arg", "1", "2", "3", "sub"])
- /// .unwrap();
- /// assert_eq!(
- /// matches.values_of("arg").unwrap().collect::<Vec<_>>(),
- /// &["1", "2", "3"]
- /// );
- /// assert!(matches.subcommand_matches("sub").is_some());
- /// ```
- pub fn subcommand_precedence_over_arg(self, yes: bool) -> Self {
- if yes {
- self.setting(AppSettings::SubcommandPrecedenceOverArg)
- } else {
- self.unset_setting(AppSettings::SubcommandPrecedenceOverArg)
- }
- }
-
- /// Allows [`subcommands`] to override all requirements of the parent command.
- ///
- /// For example, if you had a subcommand or top level application with a required argument
- /// that is only required as long as there is no subcommand present,
- /// using this setting would allow you to set those arguments to [`Arg::required(true)`]
- /// and yet receive no error so long as the user uses a valid subcommand instead.
- ///
- /// **NOTE:** This defaults to false (using subcommand does *not* negate requirements)
- ///
- /// # Examples
- ///
- /// This first example shows that it is an error to not use a required argument
- ///
- /// ```rust
- /// # use clap::{Command, Arg, ErrorKind};
- /// let err = Command::new("myprog")
- /// .subcommand_negates_reqs(true)
- /// .arg(Arg::new("opt").required(true))
- /// .subcommand(Command::new("test"))
- /// .try_get_matches_from(vec![
- /// "myprog"
- /// ]);
- /// assert!(err.is_err());
- /// assert_eq!(err.unwrap_err().kind(), ErrorKind::MissingRequiredArgument);
- /// # ;
- /// ```
- ///
- /// This next example shows that it is no longer error to not use a required argument if a
- /// valid subcommand is used.
- ///
- /// ```rust
- /// # use clap::{Command, Arg, ErrorKind};
- /// let noerr = Command::new("myprog")
- /// .subcommand_negates_reqs(true)
- /// .arg(Arg::new("opt").required(true))
- /// .subcommand(Command::new("test"))
- /// .try_get_matches_from(vec![
- /// "myprog", "test"
- /// ]);
- /// assert!(noerr.is_ok());
- /// # ;
- /// ```
- ///
- /// [`Arg::required(true)`]: crate::Arg::required()
- /// [`subcommands`]: crate::Command::subcommand()
- pub fn subcommand_negates_reqs(self, yes: bool) -> Self {
- if yes {
- self.setting(AppSettings::SubcommandsNegateReqs)
- } else {
- self.unset_setting(AppSettings::SubcommandsNegateReqs)
- }
- }
-
- /// Multiple-personality program dispatched on the binary name (`argv[0]`)
- ///
- /// A "multicall" executable is a single executable
- /// that contains a variety of applets,
- /// and decides which applet to run based on the name of the file.
- /// The executable can be called from different names by creating hard links
- /// or symbolic links to it.
- ///
- /// This is desirable for:
- /// - Easy distribution, a single binary that can install hardlinks to access the different
- /// personalities.
- /// - Minimal binary size by sharing common code (e.g. standard library, clap)
- /// - Custom shells or REPLs where there isn't a single top-level command
- ///
- /// Setting `multicall` will cause
- /// - `argv[0]` to be stripped to the base name and parsed as the first argument, as if
- /// [`Command::no_binary_name`][App::no_binary_name] was set.
- /// - Help and errors to report subcommands as if they were the top-level command
- ///
- /// When the subcommand is not present, there are several strategies you may employ, depending
- /// on your needs:
- /// - Let the error percolate up normally
- /// - Print a specialized error message using the
- /// [`Error::context`][crate::Error::context]
- /// - Print the [help][App::write_help] but this might be ambiguous
- /// - Disable `multicall` and re-parse it
- /// - Disable `multicall` and re-parse it with a specific subcommand
- ///
- /// When detecting the error condition, the [`ErrorKind`] isn't sufficient as a sub-subcommand
- /// might report the same error. Enable
- /// [`allow_external_subcommands`][App::allow_external_subcommands] if you want to specifically
- /// get the unrecognized binary name.
- ///
- /// **NOTE:** Multicall can't be used with [`no_binary_name`] since they interpret
- /// the command name in incompatible ways.
- ///
- /// **NOTE:** The multicall command cannot have arguments.
- ///
- /// **NOTE:** Applets are slightly semantically different from subcommands,
- /// so it's recommended to use [`Command::subcommand_help_heading`] and
- /// [`Command::subcommand_value_name`] to change the descriptive text as above.
- ///
- /// # Examples
- ///
- /// `hostname` is an example of a multicall executable.
- /// Both `hostname` and `dnsdomainname` are provided by the same executable
- /// and which behaviour to use is based on the executable file name.
- ///
- /// This is desirable when the executable has a primary purpose
- /// but there is related functionality that would be convenient to provide
- /// and implement it to be in the same executable.
- ///
- /// The name of the cmd is essentially unused
- /// and may be the same as the name of a subcommand.
- ///
- /// The names of the immediate subcommands of the Command
- /// are matched against the basename of the first argument,
- /// which is conventionally the path of the executable.
- ///
- /// This does not allow the subcommand to be passed as the first non-path argument.
- ///
- /// ```rust
- /// # use clap::{Command, ErrorKind};
- /// let mut cmd = Command::new("hostname")
- /// .multicall(true)
- /// .subcommand(Command::new("hostname"))
- /// .subcommand(Command::new("dnsdomainname"));
- /// let m = cmd.try_get_matches_from_mut(&["/usr/bin/hostname", "dnsdomainname"]);
- /// assert!(m.is_err());
- /// assert_eq!(m.unwrap_err().kind(), ErrorKind::UnknownArgument);
- /// let m = cmd.get_matches_from(&["/usr/bin/dnsdomainname"]);
- /// assert_eq!(m.subcommand_name(), Some("dnsdomainname"));
- /// ```
- ///
- /// Busybox is another common example of a multicall executable
- /// with a subcommmand for each applet that can be run directly,
- /// e.g. with the `cat` applet being run by running `busybox cat`,
- /// or with `cat` as a link to the `busybox` binary.
- ///
- /// This is desirable when the launcher program has additional options
- /// or it is useful to run the applet without installing a symlink
- /// e.g. to test the applet without installing it
- /// or there may already be a command of that name installed.
- ///
- /// To make an applet usable as both a multicall link and a subcommand
- /// the subcommands must be defined both in the top-level Command
- /// and as subcommands of the "main" applet.
- ///
- /// ```rust
- /// # use clap::Command;
- /// fn applet_commands() -> [Command<'static>; 2] {
- /// [Command::new("true"), Command::new("false")]
- /// }
- /// let mut cmd = Command::new("busybox")
- /// .multicall(true)
- /// .subcommand(
- /// Command::new("busybox")
- /// .subcommand_value_name("APPLET")
- /// .subcommand_help_heading("APPLETS")
- /// .subcommands(applet_commands()),
- /// )
- /// .subcommands(applet_commands());
- /// // When called from the executable's canonical name
- /// // its applets can be matched as subcommands.
- /// let m = cmd.try_get_matches_from_mut(&["/usr/bin/busybox", "true"]).unwrap();
- /// assert_eq!(m.subcommand_name(), Some("busybox"));
- /// assert_eq!(m.subcommand().unwrap().1.subcommand_name(), Some("true"));
- /// // When called from a link named after an applet that applet is matched.
- /// let m = cmd.get_matches_from(&["/usr/bin/true"]);
- /// assert_eq!(m.subcommand_name(), Some("true"));
- /// ```
- ///
- /// [`no_binary_name`]: crate::Command::no_binary_name
- /// [`App::subcommand_value_name`]: crate::Command::subcommand_value_name
- /// [`App::subcommand_help_heading`]: crate::Command::subcommand_help_heading
- #[inline]
- pub fn multicall(self, yes: bool) -> Self {
- if yes {
- self.setting(AppSettings::Multicall)
- } else {
- self.unset_setting(AppSettings::Multicall)
- }
- }
-
- /// Sets the value name used for subcommands when printing usage and help.
- ///
- /// By default, this is "SUBCOMMAND".
- ///
- /// See also [`Command::subcommand_help_heading`]
- ///
- /// # Examples
- ///
- /// ```no_run
- /// # use clap::{Command, Arg};
- /// Command::new("myprog")
- /// .subcommand(Command::new("sub1"))
- /// .print_help()
- /// # ;
- /// ```
- ///
- /// will produce
- ///
- /// ```text
- /// myprog
- ///
- /// USAGE:
- /// myprog [SUBCOMMAND]
- ///
- /// OPTIONS:
- /// -h, --help Print help information
- /// -V, --version Print version information
- ///
- /// SUBCOMMANDS:
- /// help Print this message or the help of the given subcommand(s)
- /// sub1
- /// ```
- ///
- /// but usage of `subcommand_value_name`
- ///
- /// ```no_run
- /// # use clap::{Command, Arg};
- /// Command::new("myprog")
- /// .subcommand(Command::new("sub1"))
- /// .subcommand_value_name("THING")
- /// .print_help()
- /// # ;
- /// ```
- ///
- /// will produce
- ///
- /// ```text
- /// myprog
- ///
- /// USAGE:
- /// myprog [THING]
- ///
- /// OPTIONS:
- /// -h, --help Print help information
- /// -V, --version Print version information
- ///
- /// SUBCOMMANDS:
- /// help Print this message or the help of the given subcommand(s)
- /// sub1
- /// ```
- #[must_use]
- pub fn subcommand_value_name<S>(mut self, value_name: S) -> Self
- where
- S: Into<&'help str>,
- {
- self.subcommand_value_name = Some(value_name.into());
- self
- }
-
- /// Sets the help heading used for subcommands when printing usage and help.
- ///
- /// By default, this is "SUBCOMMANDS".
- ///
- /// See also [`Command::subcommand_value_name`]
- ///
- /// # Examples
- ///
- /// ```no_run
- /// # use clap::{Command, Arg};
- /// Command::new("myprog")
- /// .subcommand(Command::new("sub1"))
- /// .print_help()
- /// # ;
- /// ```
- ///
- /// will produce
- ///
- /// ```text
- /// myprog
- ///
- /// USAGE:
- /// myprog [SUBCOMMAND]
- ///
- /// OPTIONS:
- /// -h, --help Print help information
- /// -V, --version Print version information
- ///
- /// SUBCOMMANDS:
- /// help Print this message or the help of the given subcommand(s)
- /// sub1
- /// ```
- ///
- /// but usage of `subcommand_help_heading`
- ///
- /// ```no_run
- /// # use clap::{Command, Arg};
- /// Command::new("myprog")
- /// .subcommand(Command::new("sub1"))
- /// .subcommand_help_heading("THINGS")
- /// .print_help()
- /// # ;
- /// ```
- ///
- /// will produce
- ///
- /// ```text
- /// myprog
- ///
- /// USAGE:
- /// myprog [SUBCOMMAND]
- ///
- /// OPTIONS:
- /// -h, --help Print help information
- /// -V, --version Print version information
- ///
- /// THINGS:
- /// help Print this message or the help of the given subcommand(s)
- /// sub1
- /// ```
- #[must_use]
- pub fn subcommand_help_heading<T>(mut self, heading: T) -> Self
- where
- T: Into<&'help str>,
- {
- self.subcommand_heading = Some(heading.into());
- self
- }
-}
-
-/// # Reflection
-impl<'help> App<'help> {
- #[inline]
- pub(crate) fn get_usage_name(&self) -> Option<&str> {
- self.usage_name.as_deref()
- }
-
- /// Get the name of the binary.
- #[inline]
- pub fn get_display_name(&self) -> Option<&str> {
- self.display_name.as_deref()
- }
-
- /// Get the name of the binary.
- #[inline]
- pub fn get_bin_name(&self) -> Option<&str> {
- self.bin_name.as_deref()
- }
-
- /// Set binary name. Uses `&mut self` instead of `self`.
- pub fn set_bin_name<S: Into<String>>(&mut self, name: S) {
- self.bin_name = Some(name.into());
- }
-
- /// Get the name of the cmd.
- #[inline]
- pub fn get_name(&self) -> &str {
- &self.name
- }
-
- /// Get the version of the cmd.
- #[inline]
- pub fn get_version(&self) -> Option<&'help str> {
- self.version
- }
-
- /// Get the long version of the cmd.
- #[inline]
- pub fn get_long_version(&self) -> Option<&'help str> {
- self.long_version
- }
-
- /// Get the authors of the cmd.
- #[inline]
- pub fn get_author(&self) -> Option<&'help str> {
- self.author
- }
-
- /// Get the short flag of the subcommand.
- #[inline]
- pub fn get_short_flag(&self) -> Option<char> {
- self.short_flag
- }
-
- /// Get the long flag of the subcommand.
- #[inline]
- pub fn get_long_flag(&self) -> Option<&'help str> {
- self.long_flag
- }
-
- /// Get the help message specified via [`Command::about`].
- ///
- /// [`App::about`]: Command::about()
- #[inline]
- pub fn get_about(&self) -> Option<&'help str> {
- self.about
- }
-
- /// Get the help message specified via [`Command::long_about`].
- ///
- /// [`App::long_about`]: Command::long_about()
- #[inline]
- pub fn get_long_about(&self) -> Option<&'help str> {
- self.long_about
- }
-
- /// Deprecated, replaced with [`Command::get_next_help_heading`]
- #[inline]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.1.0", note = "Replaced with `App::get_next_help_heading`")
- )]
- pub fn get_help_heading(&self) -> Option<&'help str> {
- self.get_next_help_heading()
- }
-
- /// Get the custom section heading specified via [`Command::help_heading`].
- ///
- /// [`App::help_heading`]: Command::help_heading()
- #[inline]
- pub fn get_next_help_heading(&self) -> Option<&'help str> {
- self.current_help_heading
- }
-
- /// Iterate through the *visible* aliases for this subcommand.
- #[inline]
- pub fn get_visible_aliases(&self) -> impl Iterator<Item = &'help str> + '_ {
- self.aliases.iter().filter(|(_, vis)| *vis).map(|a| a.0)
- }
-
- /// Iterate through the *visible* short aliases for this subcommand.
- #[inline]
- pub fn get_visible_short_flag_aliases(&self) -> impl Iterator<Item = char> + '_ {
- self.short_flag_aliases
- .iter()
- .filter(|(_, vis)| *vis)
- .map(|a| a.0)
- }
-
- /// Iterate through the *visible* long aliases for this subcommand.
- #[inline]
- pub fn get_visible_long_flag_aliases(&self) -> impl Iterator<Item = &'help str> + '_ {
- self.long_flag_aliases
- .iter()
- .filter(|(_, vis)| *vis)
- .map(|a| a.0)
- }
-
- /// Iterate through the set of *all* the aliases for this subcommand, both visible and hidden.
- #[inline]
- pub fn get_all_aliases(&self) -> impl Iterator<Item = &str> + '_ {
- self.aliases.iter().map(|a| a.0)
- }
-
- /// Iterate through the set of *all* the short aliases for this subcommand, both visible and hidden.
- #[inline]
- pub fn get_all_short_flag_aliases(&self) -> impl Iterator<Item = char> + '_ {
- self.short_flag_aliases.iter().map(|a| a.0)
- }
-
- /// Iterate through the set of *all* the long aliases for this subcommand, both visible and hidden.
- #[inline]
- pub fn get_all_long_flag_aliases(&self) -> impl Iterator<Item = &'help str> + '_ {
- self.long_flag_aliases.iter().map(|a| a.0)
- }
-
- /// Check if the given [`AppSettings`] variant is currently set on the `Command`.
- ///
- /// This checks both [local] and [global settings].
- ///
- /// [local]: Command::setting()
- /// [global settings]: Command::global_setting()
- #[inline]
- pub fn is_set(&self, s: AppSettings) -> bool {
- self.settings.is_set(s) || self.g_settings.is_set(s)
- }
-
- /// Should we color the output?
- #[inline(never)]
- pub fn get_color(&self) -> ColorChoice {
- debug!("Command::color: Color setting...");
-
- if cfg!(feature = "color") {
- #[allow(deprecated)]
- if self.is_set(AppSettings::ColorNever) {
- debug!("Never");
- ColorChoice::Never
- } else if self.is_set(AppSettings::ColorAlways) {
- debug!("Always");
- ColorChoice::Always
- } else {
- debug!("Auto");
- ColorChoice::Auto
- }
- } else {
- ColorChoice::Never
- }
- }
-
- /// Iterate through the set of subcommands, getting a reference to each.
- #[inline]
- pub fn get_subcommands(&self) -> impl Iterator<Item = &App<'help>> {
- self.subcommands.iter()
- }
-
- /// Iterate through the set of subcommands, getting a mutable reference to each.
- #[inline]
- pub fn get_subcommands_mut(&mut self) -> impl Iterator<Item = &mut App<'help>> {
- self.subcommands.iter_mut()
- }
-
- /// Returns `true` if this `Command` has subcommands.
- #[inline]
- pub fn has_subcommands(&self) -> bool {
- !self.subcommands.is_empty()
- }
-
- /// Returns the help heading for listing subcommands.
- #[inline]
- pub fn get_subcommand_help_heading(&self) -> Option<&str> {
- self.subcommand_heading
- }
-
- /// Deprecated, replaced with [`App::get_subcommand_help_heading`]
- #[inline]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.1.0",
- note = "Replaced with `App::get_subcommand_help_heading`"
- )
- )]
- pub fn get_subommand_help_heading(&self) -> Option<&str> {
- self.get_subcommand_help_heading()
- }
-
- /// Returns the subcommand value name.
- #[inline]
- pub fn get_subcommand_value_name(&self) -> Option<&str> {
- self.subcommand_value_name
- }
-
- /// Returns the help heading for listing subcommands.
- #[inline]
- pub fn get_before_help(&self) -> Option<&str> {
- self.before_help
- }
-
- /// Returns the help heading for listing subcommands.
- #[inline]
- pub fn get_before_long_help(&self) -> Option<&str> {
- self.before_long_help
- }
-
- /// Returns the help heading for listing subcommands.
- #[inline]
- pub fn get_after_help(&self) -> Option<&str> {
- self.after_help
- }
-
- /// Returns the help heading for listing subcommands.
- #[inline]
- pub fn get_after_long_help(&self) -> Option<&str> {
- self.after_long_help
- }
-
- /// Find subcommand such that its name or one of aliases equals `name`.
- ///
- /// This does not recurse through subcommands of subcommands.
- #[inline]
- pub fn find_subcommand<T>(&self, name: &T) -> Option<&App<'help>>
- where
- T: PartialEq<str> + ?Sized,
- {
- self.get_subcommands().find(|s| s.aliases_to(name))
- }
-
- /// Find subcommand such that its name or one of aliases equals `name`, returning
- /// a mutable reference to the subcommand.
- ///
- /// This does not recurse through subcommands of subcommands.
- #[inline]
- pub fn find_subcommand_mut<T>(&mut self, name: &T) -> Option<&mut App<'help>>
- where
- T: PartialEq<str> + ?Sized,
- {
- self.get_subcommands_mut().find(|s| s.aliases_to(name))
- }
-
- /// Iterate through the set of groups.
- #[inline]
- pub fn get_groups(&self) -> impl Iterator<Item = &ArgGroup<'help>> {
- self.groups.iter()
- }
-
- /// Iterate through the set of arguments.
- #[inline]
- pub fn get_arguments(&self) -> impl Iterator<Item = &Arg<'help>> {
- self.args.args()
- }
-
- /// Iterate through the *positionals* arguments.
- #[inline]
- pub fn get_positionals(&self) -> impl Iterator<Item = &Arg<'help>> {
- self.get_arguments().filter(|a| a.is_positional())
- }
-
- /// Iterate through the *options*.
- pub fn get_opts(&self) -> impl Iterator<Item = &Arg<'help>> {
- self.get_arguments()
- .filter(|a| a.is_takes_value_set() && !a.is_positional())
- }
-
- /// Get a list of all arguments the given argument conflicts with.
- ///
- /// If the provided argument is declared as global, the conflicts will be determined
- /// based on the propagation rules of global arguments.
- ///
- /// ### Panics
- ///
- /// If the given arg contains a conflict with an argument that is unknown to
- /// this `Command`.
- pub fn get_arg_conflicts_with(&self, arg: &Arg) -> Vec<&Arg<'help>> // FIXME: This could probably have been an iterator
- {
- if arg.is_global_set() {
- self.get_global_arg_conflicts_with(arg)
- } else {
- let mut result = Vec::new();
- for id in arg.blacklist.iter() {
- if let Some(arg) = self.find(id) {
- result.push(arg);
- } else if let Some(group) = self.find_group(id) {
- result.extend(
- self.unroll_args_in_group(&group.id)
- .iter()
- .map(|id| self.find(id).expect(INTERNAL_ERROR_MSG)),
- );
- } else {
- panic!("Command::get_arg_conflicts_with: The passed arg conflicts with an arg unknown to the cmd");
- }
- }
- result
- }
- }
-
- // Get a unique list of all arguments of all commands and continuous subcommands the given argument conflicts with.
- //
- // This behavior follows the propagation rules of global arguments.
- // It is useful for finding conflicts for arguments declared as global.
- //
- // ### Panics
- //
- // If the given arg contains a conflict with an argument that is unknown to
- // this `App`.
- fn get_global_arg_conflicts_with(&self, arg: &Arg) -> Vec<&Arg<'help>> // FIXME: This could probably have been an iterator
- {
- arg.blacklist
- .iter()
- .map(|id| {
- self.args
- .args()
- .chain(
- self.get_subcommands_containing(arg)
- .iter()
- .flat_map(|x| x.args.args()),
- )
- .find(|arg| arg.id == *id)
- .expect(
- "Command::get_arg_conflicts_with: \
- The passed arg conflicts with an arg unknown to the cmd",
- )
- })
- .collect()
- }
-
- // Get a list of subcommands which contain the provided Argument
- //
- // This command will only include subcommands in its list for which the subcommands
- // parent also contains the Argument.
- //
- // This search follows the propagation rules of global arguments.
- // It is useful to finding subcommands, that have inherited a global argument.
- //
- // **NOTE:** In this case only Sucommand_1 will be included
- // Subcommand_1 (contains Arg)
- // Subcommand_1.1 (doesn't contain Arg)
- // Subcommand_1.1.1 (contains Arg)
- //
- fn get_subcommands_containing(&self, arg: &Arg) -> Vec<&App<'help>> {
- let mut vec = std::vec::Vec::new();
- for idx in 0..self.subcommands.len() {
- if self.subcommands[idx].args.args().any(|ar| ar.id == arg.id) {
- vec.push(&self.subcommands[idx]);
- vec.append(&mut self.subcommands[idx].get_subcommands_containing(arg));
- }
- }
- vec
- }
-
- /// Report whether [`Command::no_binary_name`] is set
- pub fn is_no_binary_name_set(&self) -> bool {
- self.is_set(AppSettings::NoBinaryName)
- }
-
- /// Report whether [`Command::ignore_errors`] is set
- pub(crate) fn is_ignore_errors_set(&self) -> bool {
- self.is_set(AppSettings::IgnoreErrors)
- }
-
- /// Report whether [`Command::dont_delimit_trailing_values`] is set
- pub fn is_dont_delimit_trailing_values_set(&self) -> bool {
- self.is_set(AppSettings::DontDelimitTrailingValues)
- }
-
- /// Report whether [`Command::disable_version_flag`] is set
- pub fn is_disable_version_flag_set(&self) -> bool {
- self.is_set(AppSettings::DisableVersionFlag)
- }
-
- /// Report whether [`Command::propagate_version`] is set
- pub fn is_propagate_version_set(&self) -> bool {
- self.is_set(AppSettings::PropagateVersion)
- }
-
- /// Report whether [`Command::next_line_help`] is set
- pub fn is_next_line_help_set(&self) -> bool {
- self.is_set(AppSettings::NextLineHelp)
- }
-
- /// Report whether [`Command::disable_help_flag`] is set
- pub fn is_disable_help_flag_set(&self) -> bool {
- self.is_set(AppSettings::DisableHelpFlag)
- }
-
- /// Report whether [`Command::disable_help_subcommand`] is set
- pub fn is_disable_help_subcommand_set(&self) -> bool {
- self.is_set(AppSettings::DisableHelpSubcommand)
- }
-
- /// Report whether [`Command::disable_colored_help`] is set
- pub fn is_disable_colored_help_set(&self) -> bool {
- self.is_set(AppSettings::DisableColoredHelp)
- }
-
- /// Report whether [`Command::help_expected`] is set
- #[cfg(debug_assertions)]
- pub(crate) fn is_help_expected_set(&self) -> bool {
- self.is_set(AppSettings::HelpExpected)
- }
-
- /// Report whether [`Command::dont_collapse_args_in_usage`] is set
- pub fn is_dont_collapse_args_in_usage_set(&self) -> bool {
- self.is_set(AppSettings::DontCollapseArgsInUsage)
- }
-
- /// Report whether [`Command::infer_long_args`] is set
- pub(crate) fn is_infer_long_args_set(&self) -> bool {
- self.is_set(AppSettings::InferLongArgs)
- }
-
- /// Report whether [`Command::infer_subcommands`] is set
- pub(crate) fn is_infer_subcommands_set(&self) -> bool {
- self.is_set(AppSettings::InferSubcommands)
- }
-
- /// Report whether [`Command::arg_required_else_help`] is set
- pub fn is_arg_required_else_help_set(&self) -> bool {
- self.is_set(AppSettings::ArgRequiredElseHelp)
- }
-
- /// Report whether [`Command::allow_hyphen_values`] is set
- pub(crate) fn is_allow_hyphen_values_set(&self) -> bool {
- self.is_set(AppSettings::AllowHyphenValues)
- }
-
- /// Report whether [`Command::allow_negative_numbers`] is set
- pub fn is_allow_negative_numbers_set(&self) -> bool {
- self.is_set(AppSettings::AllowNegativeNumbers)
- }
-
- /// Report whether [`Command::trailing_var_arg`] is set
- pub fn is_trailing_var_arg_set(&self) -> bool {
- self.is_set(AppSettings::TrailingVarArg)
- }
-
- /// Report whether [`Command::allow_missing_positional`] is set
- pub fn is_allow_missing_positional_set(&self) -> bool {
- self.is_set(AppSettings::AllowMissingPositional)
- }
-
- /// Report whether [`Command::hide`] is set
- pub fn is_hide_set(&self) -> bool {
- self.is_set(AppSettings::Hidden)
- }
-
- /// Report whether [`Command::subcommand_required`] is set
- pub fn is_subcommand_required_set(&self) -> bool {
- self.is_set(AppSettings::SubcommandRequired)
- }
-
- /// Report whether [`Command::allow_external_subcommands`] is set
- pub fn is_allow_external_subcommands_set(&self) -> bool {
- self.is_set(AppSettings::AllowExternalSubcommands)
- }
-
- /// Report whether [`Command::allow_invalid_utf8_for_external_subcommands`] is set
- pub fn is_allow_invalid_utf8_for_external_subcommands_set(&self) -> bool {
- self.is_set(AppSettings::AllowInvalidUtf8ForExternalSubcommands)
- }
-
- /// Configured parser for values passed to an external subcommand
- ///
- /// # Example
- ///
- /// ```rust
- /// let cmd = clap::Command::new("raw")
- /// .allow_external_subcommands(true)
- /// .allow_invalid_utf8_for_external_subcommands(true);
- /// let value_parser = cmd.get_external_subcommand_value_parser();
- /// println!("{:?}", value_parser);
- /// ```
- pub fn get_external_subcommand_value_parser(&self) -> Option<&super::ValueParser> {
- if !self.is_allow_external_subcommands_set() {
- None
- } else if self.is_allow_invalid_utf8_for_external_subcommands_set() {
- static DEFAULT: super::ValueParser = super::ValueParser::os_string();
- Some(&DEFAULT)
- } else {
- static DEFAULT: super::ValueParser = super::ValueParser::string();
- Some(&DEFAULT)
- }
- }
-
- /// Report whether [`Command::args_conflicts_with_subcommands`] is set
- pub fn is_args_conflicts_with_subcommands_set(&self) -> bool {
- self.is_set(AppSettings::ArgsNegateSubcommands)
- }
-
- /// Report whether [`Command::subcommand_precedence_over_arg`] is set
- pub fn is_subcommand_precedence_over_arg_set(&self) -> bool {
- self.is_set(AppSettings::SubcommandPrecedenceOverArg)
- }
-
- /// Report whether [`Command::subcommand_negates_reqs`] is set
- pub fn is_subcommand_negates_reqs_set(&self) -> bool {
- self.is_set(AppSettings::SubcommandsNegateReqs)
- }
-
- /// Report whether [`Command::multicall`] is set
- pub fn is_multicall_set(&self) -> bool {
- self.is_set(AppSettings::Multicall)
- }
-}
-
-/// Deprecated
-impl<'help> App<'help> {
- /// Deprecated in [Issue #3087](https://github.com/clap-rs/clap/issues/3087), maybe [`clap::Parser`][crate::Parser] would fit your use case?
- #[cfg(feature = "yaml")]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.0.0",
- note = "Deprecated in Issue #3087, maybe clap::Parser would fit your use case?"
- )
- )]
- #[doc(hidden)]
- pub fn from_yaml(y: &'help Yaml) -> Self {
- #![allow(deprecated)]
- let yaml_file_hash = y.as_hash().expect("YAML file must be a hash");
- // We WANT this to panic on error...so expect() is good.
- let (mut a, yaml, err) = if let Some(name) = y["name"].as_str() {
- (App::new(name), yaml_file_hash, "cmd".into())
- } else {
- let (name_yaml, value_yaml) = yaml_file_hash
- .iter()
- .next()
- .expect("There must be one subcommand in the YAML file");
- let name_str = name_yaml
- .as_str()
- .expect("Subcommand name must be a string");
-
- (
- App::new(name_str),
- value_yaml.as_hash().expect("Subcommand must be a hash"),
- format!("subcommand '{}'", name_str),
- )
- };
-
- for (k, v) in yaml {
- a = match k.as_str().expect("App fields must be strings") {
- "version" => yaml_to_str!(a, v, version),
- "long_version" => yaml_to_str!(a, v, long_version),
- "author" => yaml_to_str!(a, v, author),
- "bin_name" => yaml_to_str!(a, v, bin_name),
- "about" => yaml_to_str!(a, v, about),
- "long_about" => yaml_to_str!(a, v, long_about),
- "before_help" => yaml_to_str!(a, v, before_help),
- "after_help" => yaml_to_str!(a, v, after_help),
- "template" => yaml_to_str!(a, v, help_template),
- "usage" => yaml_to_str!(a, v, override_usage),
- "help" => yaml_to_str!(a, v, override_help),
- "help_message" => yaml_to_str!(a, v, help_message),
- "version_message" => yaml_to_str!(a, v, version_message),
- "alias" => yaml_to_str!(a, v, alias),
- "aliases" => yaml_vec_or_str!(a, v, alias),
- "visible_alias" => yaml_to_str!(a, v, visible_alias),
- "visible_aliases" => yaml_vec_or_str!(a, v, visible_alias),
- "display_order" => yaml_to_usize!(a, v, display_order),
- "args" => {
- if let Some(vec) = v.as_vec() {
- for arg_yaml in vec {
- a = a.arg(Arg::from_yaml(arg_yaml));
- }
- } else {
- panic!("Failed to convert YAML value {:?} to a vec", v);
- }
- a
- }
- "subcommands" => {
- if let Some(vec) = v.as_vec() {
- for sc_yaml in vec {
- a = a.subcommand(App::from_yaml(sc_yaml));
- }
- } else {
- panic!("Failed to convert YAML value {:?} to a vec", v);
- }
- a
- }
- "groups" => {
- if let Some(vec) = v.as_vec() {
- for ag_yaml in vec {
- a = a.group(ArgGroup::from(ag_yaml));
- }
- } else {
- panic!("Failed to convert YAML value {:?} to a vec", v);
- }
- a
- }
- "setting" | "settings" => {
- yaml_to_setting!(a, v, setting, AppSettings, "AppSetting", err)
- }
- "global_setting" | "global_settings" => {
- yaml_to_setting!(a, v, global_setting, AppSettings, "AppSetting", err)
- }
- _ => a,
- }
- }
-
- a
- }
-
- /// Deprecated, replaced with [`Command::override_usage`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.0.0", note = "Replaced with `App::override_usage`")
- )]
- #[doc(hidden)]
- #[must_use]
- pub fn usage<S: Into<&'help str>>(self, usage: S) -> Self {
- self.override_usage(usage)
- }
-
- /// Deprecated, replaced with [`Command::override_help`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.0.0", note = "Replaced with `App::override_help`")
- )]
- #[doc(hidden)]
- #[must_use]
- pub fn help<S: Into<&'help str>>(self, help: S) -> Self {
- self.override_help(help)
- }
-
- /// Deprecated, replaced with [`Command::mut_arg`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.0.0", note = "Replaced with `App::mut_arg`")
- )]
- #[doc(hidden)]
- #[must_use]
- pub fn help_short(self, c: char) -> Self {
- self.mut_arg("help", |a| a.short(c))
- }
-
- /// Deprecated, replaced with [`Command::mut_arg`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.0.0", note = "Replaced with `App::mut_arg`")
- )]
- #[doc(hidden)]
- #[must_use]
- pub fn version_short(self, c: char) -> Self {
- self.mut_arg("version", |a| a.short(c))
- }
-
- /// Deprecated, replaced with [`Command::mut_arg`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.0.0", note = "Replaced with `App::mut_arg`")
- )]
- #[doc(hidden)]
- #[must_use]
- pub fn help_message(self, s: impl Into<&'help str>) -> Self {
- self.mut_arg("help", |a| a.help(s.into()))
- }
-
- /// Deprecated, replaced with [`Command::mut_arg`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.0.0", note = "Replaced with `App::mut_arg`")
- )]
- #[doc(hidden)]
- #[must_use]
- pub fn version_message(self, s: impl Into<&'help str>) -> Self {
- self.mut_arg("version", |a| a.help(s.into()))
- }
-
- /// Deprecated, replaced with [`Command::help_template`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.0.0", note = "Replaced with `App::help_template`")
- )]
- #[doc(hidden)]
- #[must_use]
- pub fn template<S: Into<&'help str>>(self, s: S) -> Self {
- self.help_template(s)
- }
-
- /// Deprecated, replaced with [`Command::setting(a| b)`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.0.0", note = "Replaced with `App::setting(a | b)`")
- )]
- #[doc(hidden)]
- #[must_use]
- pub fn settings(mut self, settings: &[AppSettings]) -> Self {
- for s in settings {
- self.settings.insert((*s).into());
- }
- self
- }
-
- /// Deprecated, replaced with [`Command::unset_setting(a| b)`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.0.0", note = "Replaced with `App::unset_setting(a | b)`")
- )]
- #[doc(hidden)]
- #[must_use]
- pub fn unset_settings(mut self, settings: &[AppSettings]) -> Self {
- for s in settings {
- self.settings.remove((*s).into());
- }
- self
- }
-
- /// Deprecated, replaced with [`Command::global_setting(a| b)`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.0.0", note = "Replaced with `App::global_setting(a | b)`")
- )]
- #[doc(hidden)]
- #[must_use]
- pub fn global_settings(mut self, settings: &[AppSettings]) -> Self {
- for s in settings {
- self.settings.insert((*s).into());
- self.g_settings.insert((*s).into());
- }
- self
- }
-
- /// Deprecated, replaced with [`Command::term_width`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.0.0", note = "Replaced with `App::term_width`")
- )]
- #[doc(hidden)]
- #[must_use]
- pub fn set_term_width(self, width: usize) -> Self {
- self.term_width(width)
- }
-
- /// Deprecated in [Issue #3086](https://github.com/clap-rs/clap/issues/3086), see [`arg!`][crate::arg!].
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.0.0", note = "Deprecated in Issue #3086, see `clap::arg!")
- )]
- #[doc(hidden)]
- #[must_use]
- pub fn arg_from_usage(self, usage: &'help str) -> Self {
- #![allow(deprecated)]
- self.arg(Arg::from_usage(usage))
- }
-
- /// Deprecated in [Issue #3086](https://github.com/clap-rs/clap/issues/3086), see [`arg!`][crate::arg!].
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.0.0", note = "Deprecated in Issue #3086, see `clap::arg!")
- )]
- #[doc(hidden)]
- #[must_use]
- pub fn args_from_usage(mut self, usage: &'help str) -> Self {
- #![allow(deprecated)]
- for line in usage.lines() {
- let l = line.trim();
- if l.is_empty() {
- continue;
- }
- self = self.arg(Arg::from_usage(l));
- }
- self
- }
-
- /// Deprecated, replaced with [`Command::render_version`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.0.0", note = "Replaced with `App::render_version`")
- )]
- #[doc(hidden)]
- pub fn write_version<W: io::Write>(&self, w: &mut W) -> ClapResult<()> {
- write!(w, "{}", self.render_version()).map_err(From::from)
- }
-
- /// Deprecated, replaced with [`Command::render_long_version`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.0.0", note = "Replaced with `App::render_long_version`")
- )]
- #[doc(hidden)]
- pub fn write_long_version<W: io::Write>(&self, w: &mut W) -> ClapResult<()> {
- write!(w, "{}", self.render_long_version()).map_err(From::from)
- }
-
- /// Deprecated, replaced with [`Command::try_get_matches`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.0.0", note = "Replaced with `App::try_get_matches`")
- )]
- #[doc(hidden)]
- pub fn get_matches_safe(self) -> ClapResult<ArgMatches> {
- self.try_get_matches()
- }
-
- /// Deprecated, replaced with [`Command::try_get_matches_from`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.0.0", note = "Replaced with `App::try_get_matches_from`")
- )]
- #[doc(hidden)]
- pub fn get_matches_from_safe<I, T>(self, itr: I) -> ClapResult<ArgMatches>
- where
- I: IntoIterator<Item = T>,
- T: Into<OsString> + Clone,
- {
- self.try_get_matches_from(itr)
- }
-
- /// Deprecated, replaced with [`Command::try_get_matches_from_mut`]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.0.0",
- note = "Replaced with `App::try_get_matches_from_mut`"
- )
- )]
- #[doc(hidden)]
- pub fn get_matches_from_safe_borrow<I, T>(&mut self, itr: I) -> ClapResult<ArgMatches>
- where
- I: IntoIterator<Item = T>,
- T: Into<OsString> + Clone,
- {
- self.try_get_matches_from_mut(itr)
- }
-}
-
-// Internally used only
-impl<'help> App<'help> {
- pub(crate) fn get_id(&self) -> Id {
- self.id.clone()
- }
-
- pub(crate) fn get_override_usage(&self) -> Option<&str> {
- self.usage_str
- }
-
- pub(crate) fn get_override_help(&self) -> Option<&str> {
- self.help_str
- }
-
- pub(crate) fn get_help_template(&self) -> Option<&str> {
- self.template
- }
-
- pub(crate) fn get_term_width(&self) -> Option<usize> {
- self.term_w
- }
-
- pub(crate) fn get_max_term_width(&self) -> Option<usize> {
- self.max_w
- }
-
- pub(crate) fn get_replacement(&self, key: &str) -> Option<&[&str]> {
- self.replacers.get(key).copied()
- }
-
- pub(crate) fn get_keymap(&self) -> &MKeyMap<'help> {
- &self.args
- }
-
- fn get_used_global_args(&self, matches: &ArgMatches, global_arg_vec: &mut Vec<Id>) {
- global_arg_vec.extend(
- self.args
- .args()
- .filter(|a| a.is_global_set())
- .map(|ga| ga.id.clone()),
- );
- if let Some((id, matches)) = matches.subcommand() {
- if let Some(used_sub) = self.find_subcommand(id) {
- used_sub.get_used_global_args(matches, global_arg_vec);
- }
- }
- }
-
- fn _do_parse(
- &mut self,
- raw_args: &mut clap_lex::RawArgs,
- args_cursor: clap_lex::ArgCursor,
- ) -> ClapResult<ArgMatches> {
- debug!("Command::_do_parse");
-
- // If there are global arguments, or settings we need to propagate them down to subcommands
- // before parsing in case we run into a subcommand
- self._build_self();
-
- let mut matcher = ArgMatcher::new(self);
-
- // do the real parsing
- let mut parser = Parser::new(self);
- if let Err(error) = parser.get_matches_with(&mut matcher, raw_args, args_cursor) {
- if self.is_set(AppSettings::IgnoreErrors) {
- debug!("Command::_do_parse: ignoring error: {}", error);
- } else {
- return Err(error);
- }
- }
-
- let mut global_arg_vec = Default::default();
- self.get_used_global_args(&matcher, &mut global_arg_vec);
-
- matcher.propagate_globals(&global_arg_vec);
-
- Ok(matcher.into_inner())
- }
-
- #[doc(hidden)]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.1.10", note = "Replaced with `Command::build`")
- )]
- pub fn _build_all(&mut self) {
- self.build();
- }
-
- #[doc(hidden)]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.1.10", note = "Replaced with `Command::build`")
- )]
- pub fn _build(&mut self) {
- self._build_self()
- }
-
- #[doc(hidden)]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.1.13", note = "Replaced with `Command::build`")
- )]
- pub fn _build_bin_names(&mut self) {
- self._build_bin_names_internal();
- }
-
- /// Prepare for introspecting on all included [`Command`]s
- ///
- /// Call this on the top-level [`Command`] when done building and before reading state for
- /// cases like completions, custom help output, etc.
- pub fn build(&mut self) {
- self._build_recursive();
- self._build_bin_names_internal();
- }
-
- pub(crate) fn _build_recursive(&mut self) {
- self._build_self();
- for subcmd in self.get_subcommands_mut() {
- subcmd._build_recursive();
- }
- }
-
- pub(crate) fn _build_self(&mut self) {
- debug!("Command::_build: name={:?}", self.get_name());
- if !self.settings.is_set(AppSettings::Built) {
- // Make sure all the globally set flags apply to us as well
- self.settings = self.settings | self.g_settings;
-
- if self.is_multicall_set() {
- self.settings.insert(AppSettings::SubcommandRequired.into());
- self.settings.insert(AppSettings::DisableHelpFlag.into());
- self.settings.insert(AppSettings::DisableVersionFlag.into());
- }
-
- self._propagate();
- self._check_help_and_version();
- self._propagate_global_args();
- self._derive_display_order();
-
- let mut pos_counter = 1;
- let self_override = self.is_set(AppSettings::AllArgsOverrideSelf);
- let hide_pv = self.is_set(AppSettings::HidePossibleValues);
- let auto_help =
- !self.is_set(AppSettings::NoAutoHelp) && !self.is_disable_help_flag_set();
- let auto_version =
- !self.is_set(AppSettings::NoAutoVersion) && !self.is_disable_version_flag_set();
- for a in self.args.args_mut() {
- // Fill in the groups
- for g in &a.groups {
- if let Some(ag) = self.groups.iter_mut().find(|grp| grp.id == *g) {
- ag.args.push(a.id.clone());
- } else {
- let mut ag = ArgGroup::with_id(g.clone());
- ag.args.push(a.id.clone());
- self.groups.push(ag);
- }
- }
-
- // Figure out implied settings
- if a.is_last_set() {
- // if an arg has `Last` set, we need to imply DontCollapseArgsInUsage so that args
- // in the usage string don't get confused or left out.
- self.settings.set(AppSettings::DontCollapseArgsInUsage);
- }
- if hide_pv && a.is_takes_value_set() {
- a.settings.set(ArgSettings::HidePossibleValues);
- }
- if self_override {
- let self_id = a.id.clone();
- a.overrides.push(self_id);
- }
- a._build();
- // HACK: Setting up action at this level while auto-help / disable help flag is
- // required. Otherwise, most of this won't be needed because when we can break
- // compat, actions will reign supreme (default to `Store`)
- if a.action.is_none() {
- if a.get_id() == "help" && auto_help && !a.is_takes_value_set() {
- let action = super::ArgAction::Help;
- a.action = Some(action);
- } else if a.get_id() == "version" && auto_version && !a.is_takes_value_set() {
- let action = super::ArgAction::Version;
- a.action = Some(action);
- } else if a.is_takes_value_set() {
- let action = super::ArgAction::StoreValue;
- a.action = Some(action);
- } else {
- let action = super::ArgAction::IncOccurrence;
- a.action = Some(action);
- }
- }
- if a.is_positional() && a.index.is_none() {
- a.index = Some(pos_counter);
- pos_counter += 1;
- }
- }
-
- self.args._build();
-
- #[cfg(debug_assertions)]
- assert_app(self);
- self.settings.set(AppSettings::Built);
- } else {
- debug!("Command::_build: already built");
- }
- }
-
- pub(crate) fn _build_subcommand(&mut self, name: &str) -> Option<&mut Self> {
- use std::fmt::Write;
-
- let mut mid_string = String::from(" ");
- if !self.is_subcommand_negates_reqs_set() && !self.is_args_conflicts_with_subcommands_set()
- {
- let reqs = Usage::new(self).get_required_usage_from(&[], None, true); // maybe Some(m)
-
- for s in &reqs {
- mid_string.push_str(s);
- mid_string.push(' ');
- }
- }
- let is_multicall_set = self.is_multicall_set();
-
- let sc = self.subcommands.iter_mut().find(|s| s.name == name)?;
-
- // Display subcommand name, short and long in usage
- let mut sc_names = sc.name.clone();
- let mut flag_subcmd = false;
- if let Some(l) = sc.long_flag {
- write!(sc_names, "|--{}", l).unwrap();
- flag_subcmd = true;
- }
- if let Some(s) = sc.short_flag {
- write!(sc_names, "|-{}", s).unwrap();
- flag_subcmd = true;
- }
-
- if flag_subcmd {
- sc_names = format!("{{{}}}", sc_names);
- }
-
- let usage_name = self
- .bin_name
- .as_ref()
- .map(|bin_name| format!("{}{}{}", bin_name, mid_string, sc_names))
- .unwrap_or(sc_names);
- sc.usage_name = Some(usage_name);
-
- // bin_name should be parent's bin_name + [<reqs>] + the sc's name separated by
- // a space
- let bin_name = format!(
- "{}{}{}",
- self.bin_name.as_ref().unwrap_or(&String::new()),
- if self.bin_name.is_some() { " " } else { "" },
- &*sc.name
- );
- debug!(
- "Command::_build_subcommand Setting bin_name of {} to {:?}",
- sc.name, bin_name
- );
- sc.bin_name = Some(bin_name);
-
- if sc.display_name.is_none() {
- let self_display_name = if is_multicall_set {
- self.display_name.as_deref().unwrap_or("")
- } else {
- self.display_name.as_deref().unwrap_or(&self.name)
- };
- let display_name = format!(
- "{}{}{}",
- self_display_name,
- if !self_display_name.is_empty() {
- "-"
- } else {
- ""
- },
- &*sc.name
- );
- debug!(
- "Command::_build_subcommand Setting display_name of {} to {:?}",
- sc.name, display_name
- );
- sc.display_name = Some(display_name);
- }
-
- // Ensure all args are built and ready to parse
- sc._build_self();
-
- Some(sc)
- }
-
- fn _build_bin_names_internal(&mut self) {
- debug!("Command::_build_bin_names");
-
- if !self.is_set(AppSettings::BinNameBuilt) {
- let mut mid_string = String::from(" ");
- if !self.is_subcommand_negates_reqs_set()
- && !self.is_args_conflicts_with_subcommands_set()
- {
- let reqs = Usage::new(self).get_required_usage_from(&[], None, true); // maybe Some(m)
-
- for s in &reqs {
- mid_string.push_str(s);
- mid_string.push(' ');
- }
- }
- let is_multicall_set = self.is_multicall_set();
-
- let self_bin_name = if is_multicall_set {
- self.bin_name.as_deref().unwrap_or("")
- } else {
- self.bin_name.as_deref().unwrap_or(&self.name)
- }
- .to_owned();
-
- for mut sc in &mut self.subcommands {
- debug!("Command::_build_bin_names:iter: bin_name set...");
-
- if sc.usage_name.is_none() {
- use std::fmt::Write;
- // Display subcommand name, short and long in usage
- let mut sc_names = sc.name.clone();
- let mut flag_subcmd = false;
- if let Some(l) = sc.long_flag {
- write!(sc_names, "|--{}", l).unwrap();
- flag_subcmd = true;
- }
- if let Some(s) = sc.short_flag {
- write!(sc_names, "|-{}", s).unwrap();
- flag_subcmd = true;
- }
-
- if flag_subcmd {
- sc_names = format!("{{{}}}", sc_names);
- }
-
- let usage_name = format!("{}{}{}", self_bin_name, mid_string, sc_names);
- debug!(
- "Command::_build_bin_names:iter: Setting usage_name of {} to {:?}",
- sc.name, usage_name
- );
- sc.usage_name = Some(usage_name);
- } else {
- debug!(
- "Command::_build_bin_names::iter: Using existing usage_name of {} ({:?})",
- sc.name, sc.usage_name
- );
- }
-
- if sc.bin_name.is_none() {
- let bin_name = format!(
- "{}{}{}",
- self_bin_name,
- if !self_bin_name.is_empty() { " " } else { "" },
- &*sc.name
- );
- debug!(
- "Command::_build_bin_names:iter: Setting bin_name of {} to {:?}",
- sc.name, bin_name
- );
- sc.bin_name = Some(bin_name);
- } else {
- debug!(
- "Command::_build_bin_names::iter: Using existing bin_name of {} ({:?})",
- sc.name, sc.bin_name
- );
- }
-
- if sc.display_name.is_none() {
- let self_display_name = if is_multicall_set {
- self.display_name.as_deref().unwrap_or("")
- } else {
- self.display_name.as_deref().unwrap_or(&self.name)
- };
- let display_name = format!(
- "{}{}{}",
- self_display_name,
- if !self_display_name.is_empty() {
- "-"
- } else {
- ""
- },
- &*sc.name
- );
- debug!(
- "Command::_build_bin_names:iter: Setting display_name of {} to {:?}",
- sc.name, display_name
- );
- sc.display_name = Some(display_name);
- } else {
- debug!(
- "Command::_build_bin_names::iter: Using existing display_name of {} ({:?})",
- sc.name, sc.display_name
- );
- }
-
- sc._build_bin_names_internal();
- }
- self.set(AppSettings::BinNameBuilt);
- } else {
- debug!("Command::_build_bin_names: already built");
- }
- }
-
- pub(crate) fn _panic_on_missing_help(&self, help_required_globally: bool) {
- if self.is_set(AppSettings::HelpExpected) || help_required_globally {
- let args_missing_help: Vec<String> = self
- .args
- .args()
- .filter(|arg| arg.help.is_none() && arg.long_help.is_none())
- .map(|arg| String::from(arg.name))
- .collect();
-
- assert!(args_missing_help.is_empty(),
- "Command::help_expected is enabled for the Command {}, but at least one of its arguments does not have either `help` or `long_help` set. List of such arguments: {}",
- self.name,
- args_missing_help.join(", ")
- );
- }
-
- for sub_app in &self.subcommands {
- sub_app._panic_on_missing_help(help_required_globally);
- }
- }
-
- #[cfg(debug_assertions)]
- pub(crate) fn two_args_of<F>(&self, condition: F) -> Option<(&Arg<'help>, &Arg<'help>)>
- where
- F: Fn(&Arg) -> bool,
- {
- two_elements_of(self.args.args().filter(|a: &&Arg| condition(a)))
- }
-
- // just in case
- #[allow(unused)]
- fn two_groups_of<F>(&self, condition: F) -> Option<(&ArgGroup, &ArgGroup)>
- where
- F: Fn(&ArgGroup) -> bool,
- {
- two_elements_of(self.groups.iter().filter(|a| condition(a)))
- }
-
- /// Propagate global args
- pub(crate) fn _propagate_global_args(&mut self) {
- debug!("Command::_propagate_global_args:{}", self.name);
-
- for sc in &mut self.subcommands {
- for a in self.args.args().filter(|a| a.is_global_set()) {
- let mut propagate = false;
- let is_generated = matches!(
- a.provider,
- ArgProvider::Generated | ArgProvider::GeneratedMutated
- );
-
- // Remove generated help and version args in the subcommand
- //
- // Don't remove if those args are further mutated
- if is_generated {
- let generated_pos = sc
- .args
- .args()
- .position(|x| x.id == a.id && x.provider == ArgProvider::Generated);
-
- if let Some(index) = generated_pos {
- debug!(
- "Command::_propagate removing {}'s {:?}",
- sc.get_name(),
- a.id
- );
- sc.args.remove(index);
- propagate = true;
- }
- }
-
- if propagate || sc.find(&a.id).is_none() {
- debug!(
- "Command::_propagate pushing {:?} to {}",
- a.id,
- sc.get_name(),
- );
- sc.args.push(a.clone());
- }
- }
- }
- }
-
- /// Propagate settings
- pub(crate) fn _propagate(&mut self) {
- debug!("Command::_propagate:{}", self.name);
- let mut subcommands = std::mem::take(&mut self.subcommands);
- for sc in &mut subcommands {
- self._propagate_subcommand(sc);
- }
- self.subcommands = subcommands;
- }
-
- fn _propagate_subcommand(&self, sc: &mut Self) {
- // We have to create a new scope in order to tell rustc the borrow of `sc` is
- // done and to recursively call this method
- {
- if self.settings.is_set(AppSettings::PropagateVersion) {
- if sc.version.is_none() && self.version.is_some() {
- sc.version = Some(self.version.unwrap());
- }
- if sc.long_version.is_none() && self.long_version.is_some() {
- sc.long_version = Some(self.long_version.unwrap());
- }
- }
-
- sc.settings = sc.settings | self.g_settings;
- sc.g_settings = sc.g_settings | self.g_settings;
- sc.term_w = self.term_w;
- sc.max_w = self.max_w;
- }
- }
-
- #[allow(clippy::blocks_in_if_conditions)]
- pub(crate) fn _check_help_and_version(&mut self) {
- debug!("Command::_check_help_and_version: {}", self.name);
-
- if self.is_set(AppSettings::DisableHelpFlag)
- || self.args.args().any(|x| {
- x.provider == ArgProvider::User
- && (x.long == Some("help") || x.id == Id::help_hash())
- })
- || self
- .subcommands
- .iter()
- .any(|sc| sc.long_flag == Some("help"))
- {
- debug!("Command::_check_help_and_version: Removing generated help");
-
- let generated_help_pos = self
- .args
- .args()
- .position(|x| x.id == Id::help_hash() && x.provider == ArgProvider::Generated);
-
- if let Some(index) = generated_help_pos {
- self.args.remove(index);
- }
- } else {
- let help = self
- .args
- .args()
- .find(|x| x.id == Id::help_hash())
- .expect(INTERNAL_ERROR_MSG);
- assert_ne!(help.provider, ArgProvider::User);
-
- if help.short.is_some() {
- if help.short == Some('h') {
- if let Some(other_arg) = self
- .args
- .args()
- .find(|x| x.id != Id::help_hash() && x.short == Some('h'))
- {
- panic!(
- "`help`s `-h` conflicts with `{}`.
-
-To change `help`s short, call `cmd.arg(Arg::new(\"help\")...)`.",
- other_arg.name
- );
- }
- }
- } else if !(self.args.args().any(|x| x.short == Some('h'))
- || self.subcommands.iter().any(|sc| sc.short_flag == Some('h')))
- {
- let help = self
- .args
- .args_mut()
- .find(|x| x.id == Id::help_hash())
- .expect(INTERNAL_ERROR_MSG);
- help.short = Some('h');
- } else {
- debug!("Command::_check_help_and_version: Removing `-h` from help");
- }
- }
-
- // Determine if we should remove the generated --version flag
- //
- // Note that if only mut_arg() was used, the first expression will evaluate to `true`
- // however inside the condition block, we only check for Generated args, not
- // GeneratedMutated args, so the `mut_arg("version", ..) will be skipped and fall through
- // to the following condition below (Adding the short `-V`)
- if self.settings.is_set(AppSettings::DisableVersionFlag)
- || (self.version.is_none() && self.long_version.is_none())
- || self.args.args().any(|x| {
- x.provider == ArgProvider::User
- && (x.long == Some("version") || x.id == Id::version_hash())
- })
- || self
- .subcommands
- .iter()
- .any(|sc| sc.long_flag == Some("version"))
- {
- debug!("Command::_check_help_and_version: Removing generated version");
-
- // This is the check mentioned above that only checks for Generated, not
- // GeneratedMutated args by design.
- let generated_version_pos = self
- .args
- .args()
- .position(|x| x.id == Id::version_hash() && x.provider == ArgProvider::Generated);
-
- if let Some(index) = generated_version_pos {
- self.args.remove(index);
- }
- }
-
- // If we still have a generated --version flag, determine if we can apply the short `-V`
- if self.args.args().any(|x| {
- x.id == Id::version_hash()
- && matches!(
- x.provider,
- ArgProvider::Generated | ArgProvider::GeneratedMutated
- )
- }) {
- let other_arg_has_short = self.args.args().any(|x| x.short == Some('V'));
- let version = self
- .args
- .args_mut()
- .find(|x| x.id == Id::version_hash())
- .expect(INTERNAL_ERROR_MSG);
-
- if !(version.short.is_some()
- || other_arg_has_short
- || self.subcommands.iter().any(|sc| sc.short_flag == Some('V')))
- {
- version.short = Some('V');
- }
- }
-
- if !self.is_set(AppSettings::DisableHelpSubcommand)
- && self.has_subcommands()
- && !self.subcommands.iter().any(|s| s.id == Id::help_hash())
- {
- debug!("Command::_check_help_and_version: Building help subcommand");
- let mut help_subcmd = App::new("help")
- .about("Print this message or the help of the given subcommand(s)")
- .arg(
- Arg::new("subcommand")
- .index(1)
- .takes_value(true)
- .multiple_occurrences(true)
- .value_name("SUBCOMMAND")
- .help("The subcommand whose help message to display"),
- );
- self._propagate_subcommand(&mut help_subcmd);
-
- // The parser acts like this is set, so let's set it so we don't falsely
- // advertise it to the user
- help_subcmd.version = None;
- help_subcmd.long_version = None;
- help_subcmd = help_subcmd
- .setting(AppSettings::DisableHelpFlag)
- .unset_global_setting(AppSettings::PropagateVersion);
-
- self.subcommands.push(help_subcmd);
- }
- }
-
- pub(crate) fn _derive_display_order(&mut self) {
- debug!("Command::_derive_display_order:{}", self.name);
-
- if self.settings.is_set(AppSettings::DeriveDisplayOrder) {
- for a in self
- .args
- .args_mut()
- .filter(|a| !a.is_positional())
- .filter(|a| a.provider != ArgProvider::Generated)
- {
- a.disp_ord.make_explicit();
- }
- for (i, sc) in &mut self.subcommands.iter_mut().enumerate() {
- sc.disp_ord.get_or_insert(i);
- }
- }
- for sc in &mut self.subcommands {
- sc._derive_display_order();
- }
- }
-
- pub(crate) fn _render_version(&self, use_long: bool) -> String {
- debug!("Command::_render_version");
-
- let ver = if use_long {
- self.long_version.or(self.version).unwrap_or("")
- } else {
- self.version.or(self.long_version).unwrap_or("")
- };
- if let Some(bn) = self.bin_name.as_ref() {
- if bn.contains(' ') {
- // In case we're dealing with subcommands i.e. git mv is translated to git-mv
- format!("{} {}\n", bn.replace(' ', "-"), ver)
- } else {
- format!("{} {}\n", &self.name[..], ver)
- }
- } else {
- format!("{} {}\n", &self.name[..], ver)
- }
- }
-
- pub(crate) fn format_group(&self, g: &Id) -> String {
- let g_string = self
- .unroll_args_in_group(g)
- .iter()
- .filter_map(|x| self.find(x))
- .map(|x| {
- if x.is_positional() {
- // Print val_name for positional arguments. e.g. <file_name>
- x.name_no_brackets().to_string()
- } else {
- // Print usage string for flags arguments, e.g. <--help>
- x.to_string()
- }
- })
- .collect::<Vec<_>>()
- .join("|");
- format!("<{}>", &*g_string)
- }
-}
-
-/// A workaround:
-/// <https://github.com/rust-lang/rust/issues/34511#issuecomment-373423999>
-pub(crate) trait Captures<'a> {}
-impl<'a, T> Captures<'a> for T {}
-
-// Internal Query Methods
-impl<'help> App<'help> {
- /// Iterate through the *flags* & *options* arguments.
- pub(crate) fn get_non_positionals(&self) -> impl Iterator<Item = &Arg<'help>> {
- self.get_arguments().filter(|a| !a.is_positional())
- }
-
- /// Iterate through the *positionals* that don't have custom heading.
- pub(crate) fn get_positionals_with_no_heading(&self) -> impl Iterator<Item = &Arg<'help>> {
- self.get_positionals()
- .filter(|a| a.get_help_heading().is_none())
- }
-
- /// Iterate through the *flags* & *options* that don't have custom heading.
- pub(crate) fn get_non_positionals_with_no_heading(&self) -> impl Iterator<Item = &Arg<'help>> {
- self.get_non_positionals()
- .filter(|a| a.get_help_heading().is_none())
- }
-
- pub(crate) fn find(&self, arg_id: &Id) -> Option<&Arg<'help>> {
- self.args.args().find(|a| a.id == *arg_id)
- }
-
- #[inline]
- pub(crate) fn contains_short(&self, s: char) -> bool {
- assert!(
- self.is_set(AppSettings::Built),
- "If App::_build hasn't been called, manually search through Arg shorts"
- );
-
- self.args.contains(s)
- }
-
- #[inline]
- pub(crate) fn set(&mut self, s: AppSettings) {
- self.settings.set(s)
- }
-
- #[inline]
- pub(crate) fn has_args(&self) -> bool {
- !self.args.is_empty()
- }
-
- pub(crate) fn has_positionals(&self) -> bool {
- self.args.keys().any(|x| x.is_position())
- }
-
- pub(crate) fn has_visible_subcommands(&self) -> bool {
- self.subcommands
- .iter()
- .any(|sc| sc.name != "help" && !sc.is_set(AppSettings::Hidden))
- }
-
- /// Check if this subcommand can be referred to as `name`. In other words,
- /// check if `name` is the name of this subcommand or is one of its aliases.
- #[inline]
- pub(crate) fn aliases_to<T>(&self, name: &T) -> bool
- where
- T: PartialEq<str> + ?Sized,
- {
- *name == *self.get_name() || self.get_all_aliases().any(|alias| *name == *alias)
- }
-
- /// Check if this subcommand can be referred to as `name`. In other words,
- /// check if `name` is the name of this short flag subcommand or is one of its short flag aliases.
- #[inline]
- pub(crate) fn short_flag_aliases_to(&self, flag: char) -> bool {
- Some(flag) == self.short_flag
- || self.get_all_short_flag_aliases().any(|alias| flag == alias)
- }
-
- /// Check if this subcommand can be referred to as `name`. In other words,
- /// check if `name` is the name of this long flag subcommand or is one of its long flag aliases.
- #[inline]
- pub(crate) fn long_flag_aliases_to<T>(&self, flag: &T) -> bool
- where
- T: PartialEq<str> + ?Sized,
- {
- match self.long_flag {
- Some(long_flag) => {
- flag == long_flag || self.get_all_long_flag_aliases().any(|alias| flag == alias)
- }
- None => self.get_all_long_flag_aliases().any(|alias| flag == alias),
- }
- }
-
- #[cfg(debug_assertions)]
- pub(crate) fn id_exists(&self, id: &Id) -> bool {
- self.args.args().any(|x| x.id == *id) || self.groups.iter().any(|x| x.id == *id)
- }
-
- /// Iterate through the groups this arg is member of.
- pub(crate) fn groups_for_arg<'a>(&'a self, arg: &Id) -> impl Iterator<Item = Id> + 'a {
- debug!("Command::groups_for_arg: id={:?}", arg);
- let arg = arg.clone();
- self.groups
- .iter()
- .filter(move |grp| grp.args.iter().any(|a| a == &arg))
- .map(|grp| grp.id.clone())
- }
-
- pub(crate) fn find_group(&self, group_id: &Id) -> Option<&ArgGroup<'help>> {
- self.groups.iter().find(|g| g.id == *group_id)
- }
-
- /// Iterate through all the names of all subcommands (not recursively), including aliases.
- /// Used for suggestions.
- pub(crate) fn all_subcommand_names(&self) -> impl Iterator<Item = &str> + Captures<'help> {
- self.get_subcommands().flat_map(|sc| {
- let name = sc.get_name();
- let aliases = sc.get_all_aliases();
- std::iter::once(name).chain(aliases)
- })
- }
-
- pub(crate) fn required_graph(&self) -> ChildGraph<Id> {
- let mut reqs = ChildGraph::with_capacity(5);
- for a in self.args.args().filter(|a| a.is_required_set()) {
- reqs.insert(a.id.clone());
- }
- for group in &self.groups {
- if group.required {
- let idx = reqs.insert(group.id.clone());
- for a in &group.requires {
- reqs.insert_child(idx, a.clone());
- }
- }
- }
-
- reqs
- }
-
- pub(crate) fn unroll_args_in_group(&self, group: &Id) -> Vec<Id> {
- debug!("Command::unroll_args_in_group: group={:?}", group);
- let mut g_vec = vec![group];
- let mut args = vec![];
-
- while let Some(g) = g_vec.pop() {
- for n in self
- .groups
- .iter()
- .find(|grp| grp.id == *g)
- .expect(INTERNAL_ERROR_MSG)
- .args
- .iter()
- {
- debug!("Command::unroll_args_in_group:iter: entity={:?}", n);
- if !args.contains(n) {
- if self.find(n).is_some() {
- debug!("Command::unroll_args_in_group:iter: this is an arg");
- args.push(n.clone())
- } else {
- debug!("Command::unroll_args_in_group:iter: this is a group");
- g_vec.push(n);
- }
- }
- }
- }
-
- args
- }
-
- pub(crate) fn unroll_arg_requires<F>(&self, func: F, arg: &Id) -> Vec<Id>
- where
- F: Fn(&(ArgPredicate<'_>, Id)) -> Option<Id>,
- {
- let mut processed = vec![];
- let mut r_vec = vec![arg];
- let mut args = vec![];
-
- while let Some(a) = r_vec.pop() {
- if processed.contains(&a) {
- continue;
- }
-
- processed.push(a);
-
- if let Some(arg) = self.find(a) {
- for r in arg.requires.iter().filter_map(&func) {
- if let Some(req) = self.find(&r) {
- if !req.requires.is_empty() {
- r_vec.push(&req.id)
- }
- }
- args.push(r);
- }
- }
- }
-
- args
- }
-
- /// Find a flag subcommand name by short flag or an alias
- pub(crate) fn find_short_subcmd(&self, c: char) -> Option<&str> {
- self.get_subcommands()
- .find(|sc| sc.short_flag_aliases_to(c))
- .map(|sc| sc.get_name())
- }
-
- /// Find a flag subcommand name by long flag or an alias
- pub(crate) fn find_long_subcmd(&self, long: &str) -> Option<&str> {
- self.get_subcommands()
- .find(|sc| sc.long_flag_aliases_to(long))
- .map(|sc| sc.get_name())
- }
-
- pub(crate) fn get_display_order(&self) -> usize {
- self.disp_ord.unwrap_or(999)
- }
-
- pub(crate) fn write_help_err(
- &self,
- mut use_long: bool,
- stream: Stream,
- ) -> ClapResult<Colorizer> {
- debug!(
- "Parser::write_help_err: use_long={:?}, stream={:?}",
- use_long && self.use_long_help(),
- stream
- );
-
- use_long = use_long && self.use_long_help();
- let usage = Usage::new(self);
-
- let mut c = Colorizer::new(stream, self.color_help());
- Help::new(HelpWriter::Buffer(&mut c), self, &usage, use_long).write_help()?;
- Ok(c)
- }
-
- pub(crate) fn use_long_help(&self) -> bool {
- debug!("Command::use_long_help");
- // In this case, both must be checked. This allows the retention of
- // original formatting, but also ensures that the actual -h or --help
- // specified by the user is sent through. If hide_short_help is not included,
- // then items specified with hidden_short_help will also be hidden.
- let should_long = |v: &Arg| {
- v.long_help.is_some()
- || v.is_hide_long_help_set()
- || v.is_hide_short_help_set()
- || cfg!(feature = "unstable-v4")
- && v.get_possible_values2()
- .iter()
- .any(PossibleValue::should_show_help)
- };
-
- // Subcommands aren't checked because we prefer short help for them, deferring to
- // `cmd subcmd --help` for more.
- self.get_long_about().is_some()
- || self.get_before_long_help().is_some()
- || self.get_after_long_help().is_some()
- || self.get_arguments().any(should_long)
- }
-
- // Should we color the help?
- pub(crate) fn color_help(&self) -> ColorChoice {
- #[cfg(feature = "color")]
- if self.is_disable_colored_help_set() {
- return ColorChoice::Never;
- }
-
- self.get_color()
- }
-}
-
-impl<'help> Default for App<'help> {
- fn default() -> Self {
- Self {
- id: Default::default(),
- name: Default::default(),
- long_flag: Default::default(),
- short_flag: Default::default(),
- display_name: Default::default(),
- bin_name: Default::default(),
- author: Default::default(),
- version: Default::default(),
- long_version: Default::default(),
- about: Default::default(),
- long_about: Default::default(),
- before_help: Default::default(),
- before_long_help: Default::default(),
- after_help: Default::default(),
- after_long_help: Default::default(),
- aliases: Default::default(),
- short_flag_aliases: Default::default(),
- long_flag_aliases: Default::default(),
- usage_str: Default::default(),
- usage_name: Default::default(),
- help_str: Default::default(),
- disp_ord: Default::default(),
- term_w: Default::default(),
- max_w: Default::default(),
- template: Default::default(),
- settings: Default::default(),
- g_settings: Default::default(),
- args: Default::default(),
- subcommands: Default::default(),
- replacers: Default::default(),
- groups: Default::default(),
- current_help_heading: Default::default(),
- current_disp_ord: Some(0),
- subcommand_value_name: Default::default(),
- subcommand_heading: Default::default(),
- }
- }
-}
-
-impl<'help> Index<&'_ Id> for App<'help> {
- type Output = Arg<'help>;
-
- fn index(&self, key: &Id) -> &Self::Output {
- self.find(key).expect(INTERNAL_ERROR_MSG)
- }
-}
-
-impl fmt::Display for App<'_> {
- fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
- write!(f, "{}", self.name)
- }
-}
-
-fn two_elements_of<I, T>(mut iter: I) -> Option<(T, T)>
-where
- I: Iterator<Item = T>,
-{
- let first = iter.next();
- let second = iter.next();
-
- match (first, second) {
- (Some(first), Some(second)) => Some((first, second)),
- _ => None,
- }
-}
-
-#[test]
-fn check_auto_traits() {
- static_assertions::assert_impl_all!(Command: Send, Sync, Unpin);
-}
diff --git a/vendor/clap/src/builder/debug_asserts.rs b/vendor/clap/src/builder/debug_asserts.rs
deleted file mode 100644
index 864b8b479..000000000
--- a/vendor/clap/src/builder/debug_asserts.rs
+++ /dev/null
@@ -1,851 +0,0 @@
-use std::cmp::Ordering;
-
-use clap_lex::RawOsStr;
-
-use crate::builder::arg::ArgProvider;
-use crate::mkeymap::KeyType;
-use crate::ArgAction;
-use crate::{Arg, Command, ValueHint};
-
-pub(crate) fn assert_app(cmd: &Command) {
- debug!("Command::_debug_asserts");
-
- let mut short_flags = vec![];
- let mut long_flags = vec![];
-
- // Invalid version flag settings
- if cmd.get_version().is_none() && cmd.get_long_version().is_none() {
- // PropagateVersion is meaningless if there is no version
- assert!(
- !cmd.is_propagate_version_set(),
- "Command {}: No version information via Command::version or Command::long_version to propagate",
- cmd.get_name(),
- );
-
- // Used `Command::mut_arg("version", ..) but did not provide any version information to display
- let version_needed = cmd
- .get_arguments()
- .filter(|x| {
- let action_set = matches!(x.get_action(), ArgAction::Version);
- #[cfg(not(feature = "unstable-v4"))]
- let provider_set = matches!(x.provider, ArgProvider::GeneratedMutated);
- #[cfg(feature = "unstable-v4")]
- let provider_set = matches!(
- x.provider,
- ArgProvider::User | ArgProvider::GeneratedMutated
- );
- action_set && provider_set
- })
- .map(|x| x.get_id())
- .collect::<Vec<_>>();
-
- assert_eq!(version_needed, Vec::<&str>::new(), "Command {}: `ArgAction::Version` used without providing Command::version or Command::long_version"
- ,cmd.get_name()
- );
- }
-
- for sc in cmd.get_subcommands() {
- if let Some(s) = sc.get_short_flag().as_ref() {
- short_flags.push(Flag::Command(format!("-{}", s), sc.get_name()));
- }
-
- for short_alias in sc.get_all_short_flag_aliases() {
- short_flags.push(Flag::Command(format!("-{}", short_alias), sc.get_name()));
- }
-
- if let Some(l) = sc.get_long_flag().as_ref() {
- #[cfg(feature = "unstable-v4")]
- {
- assert!(!l.starts_with('-'), "Command {}: long_flag {:?} must not start with a `-`, that will be handled by the parser", sc.get_name(), l);
- }
- long_flags.push(Flag::Command(format!("--{}", l), sc.get_name()));
- }
-
- for long_alias in sc.get_all_long_flag_aliases() {
- long_flags.push(Flag::Command(format!("--{}", long_alias), sc.get_name()));
- }
- }
-
- for arg in cmd.get_arguments() {
- assert_arg(arg);
-
- assert!(
- !cmd.is_multicall_set(),
- "Command {}: Arguments like {} cannot be set on a multicall command",
- cmd.get_name(),
- arg.name
- );
-
- if let Some(s) = arg.short.as_ref() {
- short_flags.push(Flag::Arg(format!("-{}", s), &*arg.name));
- }
-
- for (short_alias, _) in &arg.short_aliases {
- short_flags.push(Flag::Arg(format!("-{}", short_alias), arg.name));
- }
-
- if let Some(l) = arg.long.as_ref() {
- #[cfg(feature = "unstable-v4")]
- {
- assert!(!l.starts_with('-'), "Argument {}: long {:?} must not start with a `-`, that will be handled by the parser", arg.name, l);
- }
- long_flags.push(Flag::Arg(format!("--{}", l), &*arg.name));
- }
-
- for (long_alias, _) in &arg.aliases {
- long_flags.push(Flag::Arg(format!("--{}", long_alias), arg.name));
- }
-
- // Name conflicts
- assert!(
- cmd.two_args_of(|x| x.id == arg.id).is_none(),
- "Command {}: Argument names must be unique, but '{}' is in use by more than one argument or group",
- cmd.get_name(),
- arg.name,
- );
-
- // Long conflicts
- if let Some(l) = arg.long {
- if let Some((first, second)) = cmd.two_args_of(|x| x.long == Some(l)) {
- panic!(
- "Command {}: Long option names must be unique for each argument, \
- but '--{}' is in use by both '{}' and '{}'",
- cmd.get_name(),
- l,
- first.name,
- second.name
- )
- }
- }
-
- // Short conflicts
- if let Some(s) = arg.short {
- if let Some((first, second)) = cmd.two_args_of(|x| x.short == Some(s)) {
- panic!(
- "Command {}: Short option names must be unique for each argument, \
- but '-{}' is in use by both '{}' and '{}'",
- cmd.get_name(),
- s,
- first.name,
- second.name
- )
- }
- }
-
- // Index conflicts
- if let Some(idx) = arg.index {
- if let Some((first, second)) =
- cmd.two_args_of(|x| x.is_positional() && x.index == Some(idx))
- {
- panic!(
- "Command {}: Argument '{}' has the same index as '{}' \
- and they are both positional arguments\n\n\t \
- Use Arg::multiple_values(true) to allow one \
- positional argument to take multiple values",
- cmd.get_name(),
- first.name,
- second.name
- )
- }
- }
-
- // requires, r_if, r_unless
- for req in &arg.requires {
- assert!(
- cmd.id_exists(&req.1),
- "Command {}: Argument or group '{:?}' specified in 'requires*' for '{}' does not exist",
- cmd.get_name(),
- req.1,
- arg.name,
- );
- }
-
- for req in &arg.r_ifs {
- #[cfg(feature = "unstable-v4")]
- {
- assert!(
- !arg.is_required_set(),
- "Argument {}: `required` conflicts with `required_if_eq*`",
- arg.name
- );
- }
- assert!(
- cmd.id_exists(&req.0),
- "Command {}: Argument or group '{:?}' specified in 'required_if_eq*' for '{}' does not exist",
- cmd.get_name(),
- req.0,
- arg.name
- );
- }
-
- for req in &arg.r_ifs_all {
- #[cfg(feature = "unstable-v4")]
- {
- assert!(
- !arg.is_required_set(),
- "Argument {}: `required` conflicts with `required_if_eq_all`",
- arg.name
- );
- }
- assert!(
- cmd.id_exists(&req.0),
- "Command {}: Argument or group '{:?}' specified in 'required_if_eq_all' for '{}' does not exist",
- cmd.get_name(),
- req.0,
- arg.name
- );
- }
-
- for req in &arg.r_unless {
- #[cfg(feature = "unstable-v4")]
- {
- assert!(
- !arg.is_required_set(),
- "Argument {}: `required` conflicts with `required_unless*`",
- arg.name
- );
- }
- assert!(
- cmd.id_exists(req),
- "Command {}: Argument or group '{:?}' specified in 'required_unless*' for '{}' does not exist",
- cmd.get_name(),
- req,
- arg.name,
- );
- }
-
- for req in &arg.r_unless_all {
- #[cfg(feature = "unstable-v4")]
- {
- assert!(
- !arg.is_required_set(),
- "Argument {}: `required` conflicts with `required_unless*`",
- arg.name
- );
- }
- assert!(
- cmd.id_exists(req),
- "Command {}: Argument or group '{:?}' specified in 'required_unless*' for '{}' does not exist",
- cmd.get_name(),
- req,
- arg.name,
- );
- }
-
- // blacklist
- for req in &arg.blacklist {
- assert!(
- cmd.id_exists(req),
- "Command {}: Argument or group '{:?}' specified in 'conflicts_with*' for '{}' does not exist",
- cmd.get_name(),
- req,
- arg.name,
- );
- }
-
- if arg.is_last_set() {
- assert!(
- arg.long.is_none(),
- "Command {}: Flags or Options cannot have last(true) set. '{}' has both a long and last(true) set.",
- cmd.get_name(),
- arg.name
- );
- assert!(
- arg.short.is_none(),
- "Command {}: Flags or Options cannot have last(true) set. '{}' has both a short and last(true) set.",
- cmd.get_name(),
- arg.name
- );
- }
-
- assert!(
- !(arg.is_required_set() && arg.is_global_set()),
- "Command {}: Global arguments cannot be required.\n\n\t'{}' is marked as both global and required",
- cmd.get_name(),
- arg.name
- );
-
- // validators
- assert!(
- arg.validator.is_none() || arg.validator_os.is_none(),
- "Command {}: Argument '{}' has both `validator` and `validator_os` set which is not allowed",
- cmd.get_name(),
- arg.name
- );
-
- if arg.get_value_hint() == ValueHint::CommandWithArguments {
- assert!(
- arg.is_positional(),
- "Command {}: Argument '{}' has hint CommandWithArguments and must be positional.",
- cmd.get_name(),
- arg.name
- );
-
- assert!(
- cmd.is_trailing_var_arg_set(),
- "Command {}: Positional argument '{}' has hint CommandWithArguments, so Command must have TrailingVarArg set.",
- cmd.get_name(),
- arg.name
- );
- }
- }
-
- for group in cmd.get_groups() {
- // Name conflicts
- assert!(
- cmd.get_groups().filter(|x| x.id == group.id).count() < 2,
- "Command {}: Argument group name must be unique\n\n\t'{}' is already in use",
- cmd.get_name(),
- group.name,
- );
-
- // Groups should not have naming conflicts with Args
- assert!(
- !cmd.get_arguments().any(|x| x.id == group.id),
- "Command {}: Argument group name '{}' must not conflict with argument name",
- cmd.get_name(),
- group.name,
- );
-
- for arg in &group.args {
- // Args listed inside groups should exist
- assert!(
- cmd.get_arguments().any(|x| x.id == *arg),
- "Command {}: Argument group '{}' contains non-existent argument '{:?}'",
- cmd.get_name(),
- group.name,
- arg
- );
- }
- }
-
- // Conflicts between flags and subcommands
-
- long_flags.sort_unstable();
- short_flags.sort_unstable();
-
- detect_duplicate_flags(&long_flags, "long");
- detect_duplicate_flags(&short_flags, "short");
-
- _verify_positionals(cmd);
-
- if let Some(help_template) = cmd.get_help_template() {
- assert!(
- !help_template.contains("{flags}"),
- "Command {}: {}",
- cmd.get_name(),
- "`{flags}` template variable was removed in clap3, they are now included in `{options}`",
- );
- assert!(
- !help_template.contains("{unified}"),
- "Command {}: {}",
- cmd.get_name(),
- "`{unified}` template variable was removed in clap3, use `{options}` instead"
- );
- }
-
- cmd._panic_on_missing_help(cmd.is_help_expected_set());
- assert_app_flags(cmd);
-}
-
-#[derive(Eq)]
-enum Flag<'a> {
- Command(String, &'a str),
- Arg(String, &'a str),
-}
-
-impl PartialEq for Flag<'_> {
- fn eq(&self, other: &Flag) -> bool {
- self.cmp(other) == Ordering::Equal
- }
-}
-
-impl PartialOrd for Flag<'_> {
- fn partial_cmp(&self, other: &Flag) -> Option<Ordering> {
- use Flag::*;
-
- match (self, other) {
- (Command(s1, _), Command(s2, _))
- | (Arg(s1, _), Arg(s2, _))
- | (Command(s1, _), Arg(s2, _))
- | (Arg(s1, _), Command(s2, _)) => {
- if s1 == s2 {
- Some(Ordering::Equal)
- } else {
- s1.partial_cmp(s2)
- }
- }
- }
- }
-}
-
-impl Ord for Flag<'_> {
- fn cmp(&self, other: &Self) -> Ordering {
- self.partial_cmp(other).unwrap()
- }
-}
-
-fn detect_duplicate_flags(flags: &[Flag], short_or_long: &str) {
- use Flag::*;
-
- for (one, two) in find_duplicates(flags) {
- match (one, two) {
- (Command(flag, one), Command(_, another)) if one != another => panic!(
- "the '{}' {} flag is specified for both '{}' and '{}' subcommands",
- flag, short_or_long, one, another
- ),
-
- (Arg(flag, one), Arg(_, another)) if one != another => panic!(
- "{} option names must be unique, but '{}' is in use by both '{}' and '{}'",
- short_or_long, flag, one, another
- ),
-
- (Arg(flag, arg), Command(_, sub)) | (Command(flag, sub), Arg(_, arg)) => panic!(
- "the '{}' {} flag for the '{}' argument conflicts with the short flag \
- for '{}' subcommand",
- flag, short_or_long, arg, sub
- ),
-
- _ => {}
- }
- }
-}
-
-/// Find duplicates in a sorted array.
-///
-/// The algorithm is simple: the array is sorted, duplicates
-/// must be placed next to each other, we can check only adjacent elements.
-fn find_duplicates<T: PartialEq>(slice: &[T]) -> impl Iterator<Item = (&T, &T)> {
- slice.windows(2).filter_map(|w| {
- if w[0] == w[1] {
- Some((&w[0], &w[1]))
- } else {
- None
- }
- })
-}
-
-fn assert_app_flags(cmd: &Command) {
- macro_rules! checker {
- ($a:ident requires $($b:ident)|+) => {
- if cmd.$a() {
- let mut s = String::new();
-
- $(
- if !cmd.$b() {
- s.push_str(&format!(" AppSettings::{} is required when AppSettings::{} is set.\n", std::stringify!($b), std::stringify!($a)));
- }
- )+
-
- if !s.is_empty() {
- panic!("{}", s)
- }
- }
- };
- ($a:ident conflicts $($b:ident)|+) => {
- if cmd.$a() {
- let mut s = String::new();
-
- $(
- if cmd.$b() {
- s.push_str(&format!(" AppSettings::{} conflicts with AppSettings::{}.\n", std::stringify!($b), std::stringify!($a)));
- }
- )+
-
- if !s.is_empty() {
- panic!("{}\n{}", cmd.get_name(), s)
- }
- }
- };
- }
-
- checker!(is_allow_invalid_utf8_for_external_subcommands_set requires is_allow_external_subcommands_set);
- checker!(is_multicall_set conflicts is_no_binary_name_set);
-}
-
-#[cfg(debug_assertions)]
-fn _verify_positionals(cmd: &Command) -> bool {
- debug!("Command::_verify_positionals");
- // Because you must wait until all arguments have been supplied, this is the first chance
- // to make assertions on positional argument indexes
- //
- // First we verify that the index highest supplied index, is equal to the number of
- // positional arguments to verify there are no gaps (i.e. supplying an index of 1 and 3
- // but no 2)
-
- let highest_idx = cmd
- .get_keymap()
- .keys()
- .filter_map(|x| {
- if let KeyType::Position(n) = x {
- Some(*n)
- } else {
- None
- }
- })
- .max()
- .unwrap_or(0);
-
- let num_p = cmd.get_keymap().keys().filter(|x| x.is_position()).count();
-
- assert!(
- highest_idx == num_p,
- "Found positional argument whose index is {} but there \
- are only {} positional arguments defined",
- highest_idx,
- num_p
- );
-
- // Next we verify that only the highest index has takes multiple arguments (if any)
- let only_highest = |a: &Arg| a.is_multiple() && (a.index.unwrap_or(0) != highest_idx);
- if cmd.get_positionals().any(only_highest) {
- // First we make sure if there is a positional that allows multiple values
- // the one before it (second to last) has one of these:
- // * a value terminator
- // * ArgSettings::Last
- // * The last arg is Required
-
- // We can't pass the closure (it.next()) to the macro directly because each call to
- // find() (iterator, not macro) gets called repeatedly.
- let last = &cmd.get_keymap()[&KeyType::Position(highest_idx)];
- let second_to_last = &cmd.get_keymap()[&KeyType::Position(highest_idx - 1)];
-
- // Either the final positional is required
- // Or the second to last has a terminator or .last(true) set
- let ok = last.is_required_set()
- || (second_to_last.terminator.is_some() || second_to_last.is_last_set())
- || last.is_last_set();
- assert!(
- ok,
- "When using a positional argument with .multiple_values(true) that is *not the \
- last* positional argument, the last positional argument (i.e. the one \
- with the highest index) *must* have .required(true) or .last(true) set."
- );
-
- // We make sure if the second to last is Multiple the last is ArgSettings::Last
- let ok = second_to_last.is_multiple() || last.is_last_set();
- assert!(
- ok,
- "Only the last positional argument, or second to last positional \
- argument may be set to .multiple_values(true)"
- );
-
- // Next we check how many have both Multiple and not a specific number of values set
- let count = cmd
- .get_positionals()
- .filter(|p| {
- #[allow(deprecated)]
- {
- p.is_multiple_occurrences_set()
- || (p.is_multiple_values_set() && p.num_vals.is_none())
- }
- })
- .count();
- let ok = count <= 1
- || (last.is_last_set()
- && last.is_multiple()
- && second_to_last.is_multiple()
- && count == 2);
- assert!(
- ok,
- "Only one positional argument with .multiple_values(true) set is allowed per \
- command, unless the second one also has .last(true) set"
- );
- }
-
- let mut found = false;
-
- if cmd.is_allow_missing_positional_set() {
- // Check that if a required positional argument is found, all positions with a lower
- // index are also required.
- let mut foundx2 = false;
-
- for p in cmd.get_positionals() {
- if foundx2 && !p.is_required_set() {
- assert!(
- p.is_required_set(),
- "Found non-required positional argument with a lower \
- index than a required positional argument by two or more: {:?} \
- index {:?}",
- p.name,
- p.index
- );
- } else if p.is_required_set() && !p.is_last_set() {
- // Args that .last(true) don't count since they can be required and have
- // positionals with a lower index that aren't required
- // Imagine: prog <req1> [opt1] -- <req2>
- // Both of these are valid invocations:
- // $ prog r1 -- r2
- // $ prog r1 o1 -- r2
- if found {
- foundx2 = true;
- continue;
- }
- found = true;
- continue;
- } else {
- found = false;
- }
- }
- } else {
- // Check that if a required positional argument is found, all positions with a lower
- // index are also required
- for p in (1..=num_p).rev().filter_map(|n| cmd.get_keymap().get(&n)) {
- if found {
- assert!(
- p.is_required_set(),
- "Found non-required positional argument with a lower \
- index than a required positional argument: {:?} index {:?}",
- p.name,
- p.index
- );
- } else if p.is_required_set() && !p.is_last_set() {
- // Args that .last(true) don't count since they can be required and have
- // positionals with a lower index that aren't required
- // Imagine: prog <req1> [opt1] -- <req2>
- // Both of these are valid invocations:
- // $ prog r1 -- r2
- // $ prog r1 o1 -- r2
- found = true;
- continue;
- }
- }
- }
- assert!(
- cmd.get_positionals().filter(|p| p.is_last_set()).count() < 2,
- "Only one positional argument may have last(true) set. Found two."
- );
- if cmd
- .get_positionals()
- .any(|p| p.is_last_set() && p.is_required_set())
- && cmd.has_subcommands()
- && !cmd.is_subcommand_negates_reqs_set()
- {
- panic!(
- "Having a required positional argument with .last(true) set *and* child \
- subcommands without setting SubcommandsNegateReqs isn't compatible."
- );
- }
-
- true
-}
-
-fn assert_arg(arg: &Arg) {
- debug!("Arg::_debug_asserts:{}", arg.name);
-
- // Self conflict
- // TODO: this check should be recursive
- assert!(
- !arg.blacklist.iter().any(|x| *x == arg.id),
- "Argument '{}' cannot conflict with itself",
- arg.name,
- );
-
- assert_eq!(
- arg.get_action().takes_values(),
- arg.is_takes_value_set(),
- "Argument `{}`'s selected action {:?} contradicts `takes_value`",
- arg.name,
- arg.get_action()
- );
- if let Some(action_type_id) = arg.get_action().value_type_id() {
- assert_eq!(
- action_type_id,
- arg.get_value_parser().type_id(),
- "Argument `{}`'s selected action {:?} contradicts `value_parser` ({:?})",
- arg.name,
- arg.get_action(),
- arg.get_value_parser()
- );
- }
-
- if arg.get_value_hint() != ValueHint::Unknown {
- assert!(
- arg.is_takes_value_set(),
- "Argument '{}' has value hint but takes no value",
- arg.name
- );
-
- if arg.get_value_hint() == ValueHint::CommandWithArguments {
- assert!(
- arg.is_multiple_values_set(),
- "Argument '{}' uses hint CommandWithArguments and must accept multiple values",
- arg.name
- )
- }
- }
-
- if arg.index.is_some() {
- assert!(
- arg.is_positional(),
- "Argument '{}' is a positional argument and can't have short or long name versions",
- arg.name
- );
- assert!(
- arg.is_takes_value_set(),
- "Argument '{}` is positional, it must take a value",
- arg.name
- );
- }
-
- #[cfg(feature = "unstable-v4")]
- {
- let num_vals = arg.get_num_vals().unwrap_or(usize::MAX);
- let num_val_names = arg.get_value_names().unwrap_or(&[]).len();
- if num_vals < num_val_names {
- panic!(
- "Argument {}: Too many value names ({}) compared to number_of_values ({})",
- arg.name, num_val_names, num_vals
- );
- }
- }
-
- assert_arg_flags(arg);
-
- assert_defaults(arg, "default_value", arg.default_vals.iter().copied());
- assert_defaults(
- arg,
- "default_missing_value",
- arg.default_missing_vals.iter().copied(),
- );
- assert_defaults(
- arg,
- "default_value_if",
- arg.default_vals_ifs
- .iter()
- .filter_map(|(_, _, default)| *default),
- );
-}
-
-fn assert_arg_flags(arg: &Arg) {
- macro_rules! checker {
- ($a:ident requires $($b:ident)|+) => {
- if arg.$a() {
- let mut s = String::new();
-
- $(
- if !arg.$b() {
- s.push_str(&format!(" Arg::{} is required when Arg::{} is set.\n", std::stringify!($b), std::stringify!($a)));
- }
- )+
-
- if !s.is_empty() {
- panic!("Argument {:?}\n{}", arg.get_id(), s)
- }
- }
- }
- }
-
- checker!(is_require_value_delimiter_set requires is_takes_value_set);
- checker!(is_require_value_delimiter_set requires is_use_value_delimiter_set);
- checker!(is_hide_possible_values_set requires is_takes_value_set);
- checker!(is_allow_hyphen_values_set requires is_takes_value_set);
- checker!(is_require_equals_set requires is_takes_value_set);
- checker!(is_last_set requires is_takes_value_set);
- checker!(is_hide_default_value_set requires is_takes_value_set);
- checker!(is_multiple_values_set requires is_takes_value_set);
- checker!(is_ignore_case_set requires is_takes_value_set);
- {
- #![allow(deprecated)]
- checker!(is_forbid_empty_values_set requires is_takes_value_set);
- checker!(is_allow_invalid_utf8_set requires is_takes_value_set);
- }
-}
-
-fn assert_defaults<'d>(
- arg: &Arg,
- field: &'static str,
- defaults: impl IntoIterator<Item = &'d std::ffi::OsStr>,
-) {
- for default_os in defaults {
- if let Some(default_s) = default_os.to_str() {
- if !arg.possible_vals.is_empty() {
- if let Some(delim) = arg.get_value_delimiter() {
- for part in default_s.split(delim) {
- assert!(
- arg.possible_vals.iter().any(|possible_val| {
- possible_val.matches(part, arg.is_ignore_case_set())
- }),
- "Argument `{}`'s {}={} doesn't match possible values",
- arg.name,
- field,
- part
- )
- }
- } else {
- assert!(
- arg.possible_vals.iter().any(|possible_val| {
- possible_val.matches(default_s, arg.is_ignore_case_set())
- }),
- "Argument `{}`'s {}={} doesn't match possible values",
- arg.name,
- field,
- default_s
- );
- }
- }
-
- if let Some(validator) = arg.validator.as_ref() {
- let mut validator = validator.lock().unwrap();
- if let Some(delim) = arg.get_value_delimiter() {
- for part in default_s.split(delim) {
- if let Err(err) = validator(part) {
- panic!(
- "Argument `{}`'s {}={} failed validation: {}",
- arg.name, field, part, err
- );
- }
- }
- } else if let Err(err) = validator(default_s) {
- panic!(
- "Argument `{}`'s {}={} failed validation: {}",
- arg.name, field, default_s, err
- );
- }
- }
- }
-
- if let Some(validator) = arg.validator_os.as_ref() {
- let mut validator = validator.lock().unwrap();
- if let Some(delim) = arg.get_value_delimiter() {
- let default_os = RawOsStr::new(default_os);
- for part in default_os.split(delim) {
- if let Err(err) = validator(&part.to_os_str()) {
- panic!(
- "Argument `{}`'s {}={:?} failed validation: {}",
- arg.name, field, part, err
- );
- }
- }
- } else if let Err(err) = validator(default_os) {
- panic!(
- "Argument `{}`'s {}={:?} failed validation: {}",
- arg.name, field, default_os, err
- );
- }
- }
-
- let value_parser = arg.get_value_parser();
- let assert_cmd = Command::new("assert");
- if let Some(delim) = arg.get_value_delimiter() {
- let default_os = RawOsStr::new(default_os);
- for part in default_os.split(delim) {
- if let Err(err) = value_parser.parse_ref(&assert_cmd, Some(arg), &part.to_os_str())
- {
- panic!(
- "Argument `{}`'s {}={:?} failed validation: {}",
- arg.name,
- field,
- part.to_str_lossy(),
- err
- );
- }
- }
- } else if let Err(err) = value_parser.parse_ref(&assert_cmd, Some(arg), default_os) {
- panic!(
- "Argument `{}`'s {}={:?} failed validation: {}",
- arg.name, field, default_os, err
- );
- }
- }
-}
diff --git a/vendor/clap/src/builder/macros.rs b/vendor/clap/src/builder/macros.rs
deleted file mode 100644
index 5be4d205e..000000000
--- a/vendor/clap/src/builder/macros.rs
+++ /dev/null
@@ -1,180 +0,0 @@
-#[cfg(feature = "yaml")]
-macro_rules! yaml_tuple2 {
- ($a:ident, $v:ident, $c:ident) => {{
- if let Some(vec) = $v.as_vec() {
- for ys in vec {
- if let Some(tup) = ys.as_vec() {
- debug_assert_eq!(2, tup.len());
- $a = $a.$c(yaml_str!(tup[0]), yaml_str!(tup[1]));
- } else {
- panic!("Failed to convert YAML value to vec");
- }
- }
- } else {
- panic!("Failed to convert YAML value to vec");
- }
- $a
- }};
-}
-
-#[cfg(feature = "yaml")]
-macro_rules! yaml_tuple3 {
- ($a:ident, $v:ident, $c:ident) => {{
- if let Some(vec) = $v.as_vec() {
- for ys in vec {
- if let Some(tup) = ys.as_vec() {
- debug_assert_eq!(3, tup.len());
- $a = $a.$c(
- yaml_str!(tup[0]),
- yaml_opt_str!(tup[1]),
- yaml_opt_str!(tup[2]),
- );
- } else {
- panic!("Failed to convert YAML value to vec");
- }
- }
- } else {
- panic!("Failed to convert YAML value to vec");
- }
- $a
- }};
-}
-
-#[cfg(feature = "yaml")]
-macro_rules! yaml_vec_or_str {
- ($a:ident, $v:ident, $c:ident) => {{
- let maybe_vec = $v.as_vec();
- if let Some(vec) = maybe_vec {
- for ys in vec {
- if let Some(s) = ys.as_str() {
- $a = $a.$c(s);
- } else {
- panic!("Failed to convert YAML value {:?} to a string", ys);
- }
- }
- } else {
- if let Some(s) = $v.as_str() {
- $a = $a.$c(s);
- } else {
- panic!(
- "Failed to convert YAML value {:?} to either a vec or string",
- $v
- );
- }
- }
- $a
- }};
-}
-
-#[cfg(feature = "yaml")]
-macro_rules! yaml_vec {
- ($a:ident, $v:ident, $c:ident) => {{
- let maybe_vec = $v.as_vec();
- if let Some(vec) = maybe_vec {
- let content = vec.into_iter().map(|ys| {
- if let Some(s) = ys.as_str() {
- s
- } else {
- panic!("Failed to convert YAML value {:?} to a string", ys);
- }
- });
- $a = $a.$c(content)
- } else {
- panic!("Failed to convert YAML value {:?} to a vec", $v);
- }
- $a
- }};
-}
-
-#[cfg(feature = "yaml")]
-macro_rules! yaml_opt_str {
- ($v:expr) => {{
- if !$v.is_null() {
- Some(
- $v.as_str()
- .unwrap_or_else(|| panic!("failed to convert YAML {:?} value to a string", $v)),
- )
- } else {
- None
- }
- }};
-}
-
-#[cfg(feature = "yaml")]
-macro_rules! yaml_char {
- ($v:expr) => {{
- $v.as_str()
- .unwrap_or_else(|| panic!("failed to convert YAML {:?} value to a string", $v))
- .chars()
- .next()
- .unwrap_or_else(|| panic!("Expected char"))
- }};
-}
-
-#[cfg(feature = "yaml")]
-macro_rules! yaml_str {
- ($v:expr) => {{
- $v.as_str()
- .unwrap_or_else(|| panic!("failed to convert YAML {:?} value to a string", $v))
- }};
-}
-
-#[cfg(feature = "yaml")]
-macro_rules! yaml_to_char {
- ($a:ident, $v:ident, $c:ident) => {{
- $a.$c(yaml_char!($v))
- }};
-}
-
-#[cfg(feature = "yaml")]
-macro_rules! yaml_to_str {
- ($a:ident, $v:ident, $c:ident) => {{
- $a.$c(yaml_str!($v))
- }};
-}
-
-#[cfg(feature = "yaml")]
-macro_rules! yaml_to_bool {
- ($a:ident, $v:ident, $c:ident) => {{
- $a.$c($v
- .as_bool()
- .unwrap_or_else(|| panic!("failed to convert YAML {:?} value to a string", $v)))
- }};
-}
-
-#[cfg(feature = "yaml")]
-macro_rules! yaml_to_usize {
- ($a:ident, $v:ident, $c:ident) => {{
- $a.$c($v
- .as_i64()
- .unwrap_or_else(|| panic!("failed to convert YAML {:?} value to a string", $v))
- as usize)
- }};
-}
-
-#[cfg(feature = "yaml")]
-macro_rules! yaml_to_setting {
- ($a:ident, $v:ident, $c:ident, $s:ident, $t:literal, $n:expr) => {{
- if let Some(v) = $v.as_vec() {
- for ys in v {
- if let Some(s) = ys.as_str() {
- $a = $a.$c(s.parse::<$s>().unwrap_or_else(|_| {
- panic!("Unknown {} '{}' found in YAML file for {}", $t, s, $n)
- }));
- } else {
- panic!(
- "Failed to convert YAML {:?} value to an array of strings",
- $v
- );
- }
- }
- } else if let Some(v) = $v.as_str() {
- $a = $a.$c(v
- .parse::<$s>()
- .unwrap_or_else(|_| panic!("Unknown {} '{}' found in YAML file for {}", $t, v, $n)))
- } else {
- panic!("Failed to convert YAML {:?} value to a string", $v);
- }
- $a
- }};
-}
diff --git a/vendor/clap/src/builder/mod.rs b/vendor/clap/src/builder/mod.rs
deleted file mode 100644
index 4f24c74d3..000000000
--- a/vendor/clap/src/builder/mod.rs
+++ /dev/null
@@ -1,61 +0,0 @@
-//! Define [`Command`] line [arguments][`Arg`]
-
-#[macro_use]
-mod macros;
-
-mod action;
-mod app_settings;
-mod arg;
-mod arg_group;
-mod arg_predicate;
-mod arg_settings;
-mod command;
-mod possible_value;
-mod usage_parser;
-mod value_hint;
-mod value_parser;
-
-#[cfg(feature = "regex")]
-mod regex;
-
-#[cfg(debug_assertions)]
-mod debug_asserts;
-
-#[cfg(test)]
-mod tests;
-
-pub use action::ArgAction;
-pub use app_settings::{AppFlags, AppSettings};
-pub use arg::Arg;
-pub use arg_group::ArgGroup;
-pub use arg_settings::{ArgFlags, ArgSettings};
-pub use command::Command;
-pub use possible_value::PossibleValue;
-pub use value_hint::ValueHint;
-pub use value_parser::PossibleValuesParser;
-pub use value_parser::RangedI64ValueParser;
-pub use value_parser::RangedU64ValueParser;
-pub use value_parser::StringValueParser;
-pub use value_parser::TypedValueParser;
-pub use value_parser::ValueParser;
-pub use value_parser::ValueParserFactory;
-pub use value_parser::_AnonymousValueParser;
-pub use value_parser::_AutoValueParser;
-pub use value_parser::via_prelude;
-pub use value_parser::BoolValueParser;
-pub use value_parser::BoolishValueParser;
-pub use value_parser::EnumValueParser;
-pub use value_parser::FalseyValueParser;
-pub use value_parser::NonEmptyStringValueParser;
-pub use value_parser::OsStringValueParser;
-pub use value_parser::PathBufValueParser;
-
-#[allow(deprecated)]
-pub use command::App;
-
-#[cfg(feature = "regex")]
-pub use self::regex::RegexRef;
-
-pub(crate) use action::CountType;
-pub(crate) use arg::display_arg_val;
-pub(crate) use arg_predicate::ArgPredicate;
diff --git a/vendor/clap/src/builder/possible_value.rs b/vendor/clap/src/builder/possible_value.rs
deleted file mode 100644
index 1c14217a6..000000000
--- a/vendor/clap/src/builder/possible_value.rs
+++ /dev/null
@@ -1,259 +0,0 @@
-use std::{borrow::Cow, iter};
-
-use crate::util::eq_ignore_case;
-
-/// A possible value of an argument.
-///
-/// This is used for specifying [possible values] of [Args].
-///
-/// **NOTE:** This struct is likely not needed for most usecases as it is only required to
-/// [hide] single values from help messages and shell completions or to attach [help] to possible values.
-///
-/// # Examples
-///
-/// ```rust
-/// # use clap::{Arg, PossibleValue};
-/// let cfg = Arg::new("config")
-/// .takes_value(true)
-/// .value_name("FILE")
-/// .value_parser([
-/// PossibleValue::new("fast"),
-/// PossibleValue::new("slow").help("slower than fast"),
-/// PossibleValue::new("secret speed").hide(true)
-/// ]);
-/// ```
-/// [Args]: crate::Arg
-/// [possible values]: crate::builder::ValueParser::possible_values
-/// [hide]: PossibleValue::hide()
-/// [help]: PossibleValue::help()
-#[derive(Debug, Default, Clone, PartialEq, Eq)]
-pub struct PossibleValue<'help> {
- name: &'help str,
- help: Option<&'help str>,
- aliases: Vec<&'help str>, // (name, visible)
- hide: bool,
-}
-
-impl<'help> PossibleValue<'help> {
- /// Create a [`PossibleValue`] with its name.
- ///
- /// The name will be used to decide whether this value was provided by the user to an argument.
- ///
- /// **NOTE:** In case it is not [hidden] it will also be shown in help messages for arguments
- /// that use it as a [possible value] and have not hidden them through [`Arg::hide_possible_values(true)`].
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::PossibleValue;
- /// PossibleValue::new("fast")
- /// # ;
- /// ```
- /// [hidden]: PossibleValue::hide
- /// [possible value]: crate::Arg::possible_values
- /// [`Arg::hide_possible_values(true)`]: crate::Arg::hide_possible_values()
- pub fn new(name: &'help str) -> Self {
- PossibleValue {
- name,
- ..Default::default()
- }
- }
-
- /// Sets the help description of the value.
- ///
- /// This is typically displayed in completions (where supported) and should be a short, one-line
- /// description.
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::PossibleValue;
- /// PossibleValue::new("slow")
- /// .help("not fast")
- /// # ;
- /// ```
- #[inline]
- #[must_use]
- pub fn help(mut self, help: &'help str) -> Self {
- self.help = Some(help);
- self
- }
-
- /// Hides this value from help and shell completions.
- ///
- /// This is an alternative to hiding through [`Arg::hide_possible_values(true)`], if you only
- /// want to hide some values.
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::PossibleValue;
- /// PossibleValue::new("secret")
- /// .hide(true)
- /// # ;
- /// ```
- /// [`Arg::hide_possible_values(true)`]: crate::Arg::hide_possible_values()
- #[inline]
- #[must_use]
- pub fn hide(mut self, yes: bool) -> Self {
- self.hide = yes;
- self
- }
-
- /// Sets a *hidden* alias for this argument value.
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::PossibleValue;
- /// PossibleValue::new("slow")
- /// .alias("not-fast")
- /// # ;
- /// ```
- #[must_use]
- pub fn alias(mut self, name: &'help str) -> Self {
- self.aliases.push(name);
- self
- }
-
- /// Sets multiple *hidden* aliases for this argument value.
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::PossibleValue;
- /// PossibleValue::new("slow")
- /// .aliases(["not-fast", "snake-like"])
- /// # ;
- /// ```
- #[must_use]
- pub fn aliases<I>(mut self, names: I) -> Self
- where
- I: IntoIterator<Item = &'help str>,
- {
- self.aliases.extend(names.into_iter());
- self
- }
-}
-
-/// Reflection
-impl<'help> PossibleValue<'help> {
- /// Get the name of the argument value
- #[inline]
- pub fn get_name(&self) -> &'help str {
- self.name
- }
-
- /// Get the help specified for this argument, if any
- #[inline]
- pub fn get_help(&self) -> Option<&'help str> {
- self.help
- }
-
- /// Get the help specified for this argument, if any and the argument
- /// value is not hidden
- #[inline]
- #[cfg(feature = "unstable-v4")]
- pub(crate) fn get_visible_help(&self) -> Option<&'help str> {
- if !self.hide {
- self.help
- } else {
- None
- }
- }
-
- /// Deprecated, replaced with [`PossibleValue::is_hide_set`]
- #[inline]
- #[cfg_attr(
- feature = "deprecated",
- deprecated(since = "3.1.0", note = "Replaced with `PossibleValue::is_hide_set`")
- )]
- pub fn is_hidden(&self) -> bool {
- self.is_hide_set()
- }
-
- /// Report if [`PossibleValue::hide`] is set
- #[inline]
- pub fn is_hide_set(&self) -> bool {
- self.hide
- }
-
- /// Report if PossibleValue is not hidden and has a help message
- pub(crate) fn should_show_help(&self) -> bool {
- !self.hide && self.help.is_some()
- }
-
- /// Get the name if argument value is not hidden, `None` otherwise
- #[cfg_attr(
- feature = "deprecated",
- deprecated(
- since = "3.1.4",
- note = "Use `PossibleValue::is_hide_set` and `PossibleValue::get_name`"
- )
- )]
- pub fn get_visible_name(&self) -> Option<&'help str> {
- if self.hide {
- None
- } else {
- Some(self.name)
- }
- }
-
- /// Get the name if argument value is not hidden, `None` otherwise,
- /// but wrapped in quotes if it contains whitespace
- pub(crate) fn get_visible_quoted_name(&self) -> Option<Cow<'help, str>> {
- if !self.hide {
- Some(if self.name.contains(char::is_whitespace) {
- format!("{:?}", self.name).into()
- } else {
- self.name.into()
- })
- } else {
- None
- }
- }
-
- /// Returns all valid values of the argument value.
- ///
- /// Namely the name and all aliases.
- pub fn get_name_and_aliases(&self) -> impl Iterator<Item = &'help str> + '_ {
- iter::once(&self.name).chain(&self.aliases).copied()
- }
-
- /// Tests if the value is valid for this argument value
- ///
- /// The value is valid if it is either the name or one of the aliases.
- ///
- /// # Examples
- ///
- /// ```rust
- /// # use clap::PossibleValue;
- /// let arg_value = PossibleValue::new("fast").alias("not-slow");
- ///
- /// assert!(arg_value.matches("fast", false));
- /// assert!(arg_value.matches("not-slow", false));
- ///
- /// assert!(arg_value.matches("FAST", true));
- /// assert!(!arg_value.matches("FAST", false));
- /// ```
- pub fn matches(&self, value: &str, ignore_case: bool) -> bool {
- if ignore_case {
- self.get_name_and_aliases()
- .any(|name| eq_ignore_case(name, value))
- } else {
- self.get_name_and_aliases().any(|name| name == value)
- }
- }
-}
-
-impl<'help> From<&'help str> for PossibleValue<'help> {
- fn from(s: &'help str) -> Self {
- Self::new(s)
- }
-}
-
-impl<'help> From<&'help &'help str> for PossibleValue<'help> {
- fn from(s: &'help &'help str) -> Self {
- Self::new(s)
- }
-}
diff --git a/vendor/clap/src/builder/regex.rs b/vendor/clap/src/builder/regex.rs
deleted file mode 100644
index bf3a78e0c..000000000
--- a/vendor/clap/src/builder/regex.rs
+++ /dev/null
@@ -1,88 +0,0 @@
-use ::regex::{Error, Regex, RegexSet};
-
-use core::{convert::TryFrom, ops::Deref, str::FromStr};
-use std::borrow::Cow;
-
-/// Contains either a regular expression or a set of them or a reference to one.
-///
-/// See [Arg::validator_regex(][crate::Arg::validator_regex] to set this on an argument.
-#[derive(Debug, Clone)]
-pub enum RegexRef<'a> {
- /// Used if the underlying is a regex set
- RegexSet(Cow<'a, RegexSet>),
- /// Used if the underlying is a regex
- Regex(Cow<'a, Regex>),
-}
-
-impl<'a> RegexRef<'a> {
- pub(crate) fn is_match(&self, text: &str) -> bool {
- match self {
- Self::Regex(r) => r.deref().is_match(text),
- Self::RegexSet(r) => r.deref().is_match(text),
- }
- }
-}
-
-impl<'a> From<&'a Regex> for RegexRef<'a> {
- fn from(r: &'a Regex) -> Self {
- Self::Regex(Cow::Borrowed(r))
- }
-}
-
-impl<'a> From<Regex> for RegexRef<'a> {
- fn from(r: Regex) -> Self {
- Self::Regex(Cow::Owned(r))
- }
-}
-
-impl<'a> From<&'a RegexSet> for RegexRef<'a> {
- fn from(r: &'a RegexSet) -> Self {
- Self::RegexSet(Cow::Borrowed(r))
- }
-}
-
-impl<'a> From<RegexSet> for RegexRef<'a> {
- fn from(r: RegexSet) -> Self {
- Self::RegexSet(Cow::Owned(r))
- }
-}
-
-impl<'a> TryFrom<&'a str> for RegexRef<'a> {
- type Error = <Self as FromStr>::Err;
-
- fn try_from(r: &'a str) -> Result<Self, Self::Error> {
- Self::from_str(r)
- }
-}
-
-impl<'a> FromStr for RegexRef<'a> {
- type Err = Error;
-
- fn from_str(s: &str) -> Result<Self, Self::Err> {
- Regex::from_str(s).map(|v| Self::Regex(Cow::Owned(v)))
- }
-}
-
-#[cfg(test)]
-mod tests {
- use super::*;
- use core::convert::TryInto;
-
- #[test]
- fn test_try_from_with_valid_string() {
- let t: Result<RegexRef, _> = "^Hello, World$".try_into();
- assert!(t.is_ok())
- }
-
- #[test]
- fn test_try_from_with_invalid_string() {
- let t: Result<RegexRef, _> = "^Hello, World)$".try_into();
- assert!(t.is_err());
- }
-
- #[test]
- fn from_str() {
- let t: Result<RegexRef, _> = RegexRef::from_str("^Hello, World");
- assert!(t.is_ok());
- }
-}
diff --git a/vendor/clap/src/builder/tests.rs b/vendor/clap/src/builder/tests.rs
deleted file mode 100644
index 76c8b8785..000000000
--- a/vendor/clap/src/builder/tests.rs
+++ /dev/null
@@ -1,56 +0,0 @@
-use crate::Arg;
-use crate::Command;
-
-#[test]
-fn propagate_version() {
- let mut cmd = Command::new("test")
- .propagate_version(true)
- .version("1.1")
- .subcommand(Command::new("sub1"));
- cmd._propagate();
- assert_eq!(
- cmd.get_subcommands().next().unwrap().get_version(),
- Some("1.1")
- );
-}
-
-#[test]
-fn global_setting() {
- let mut cmd = Command::new("test")
- .disable_version_flag(true)
- .subcommand(Command::new("subcmd"));
- cmd._propagate();
- assert!(cmd
- .get_subcommands()
- .find(|s| s.get_name() == "subcmd")
- .unwrap()
- .is_disable_version_flag_set());
-}
-
-// This test will *fail to compile* if Command is not Send + Sync
-#[test]
-fn app_send_sync() {
- fn foo<T: Send + Sync>(_: T) {}
- foo(Command::new("test"))
-}
-
-#[test]
-fn issue_2090() {
- let mut cmd = Command::new("cmd")
- .disable_version_flag(true)
- .subcommand(Command::new("sub"));
- cmd._build_self();
-
- assert!(cmd
- .get_subcommands()
- .next()
- .unwrap()
- .is_disable_version_flag_set());
-}
-
-// This test will *fail to compile* if Arg is not Send + Sync
-#[test]
-fn arg_send_sync() {
- fn foo<T: Send + Sync>(_: T) {}
- foo(Arg::new("test"))
-}
diff --git a/vendor/clap/src/builder/usage_parser.rs b/vendor/clap/src/builder/usage_parser.rs
deleted file mode 100644
index 85d0d304e..000000000
--- a/vendor/clap/src/builder/usage_parser.rs
+++ /dev/null
@@ -1,1277 +0,0 @@
-#![allow(deprecated)]
-
-// Internal
-use crate::builder::Arg;
-use crate::builder::ArgSettings;
-use crate::INTERNAL_ERROR_MSG;
-
-#[derive(PartialEq, Debug)]
-enum UsageToken {
- Name,
- ValName,
- Short,
- Long,
- Help,
- Multiple,
- Unknown,
- Default,
-}
-
-#[derive(Debug)]
-pub(crate) struct UsageParser<'help> {
- usage: &'help str,
- pos: usize,
- start: usize,
- prev: UsageToken,
- explicit_name_set: bool,
-}
-
-impl<'help> UsageParser<'help> {
- fn new(usage: &'help str) -> Self {
- debug!("new: usage={:?}", usage);
- UsageParser {
- usage,
- pos: 0,
- start: 0,
- prev: UsageToken::Unknown,
- explicit_name_set: false,
- }
- }
-
- pub(crate) fn from_usage(usage: &'help str) -> Self {
- debug!("UsageParser::from_usage");
- UsageParser::new(usage)
- }
-
- pub(crate) fn parse(mut self) -> Arg<'help> {
- debug!("UsageParser::parse");
- let mut arg = Arg::default();
- loop {
- debug!("UsageParser::parse:iter: pos={}", self.pos);
- self.stop_at(token);
- if let Some(&c) = self.usage.as_bytes().get(self.pos) {
- match c {
- b'-' => self.short_or_long(&mut arg),
- b'.' => self.multiple(&mut arg),
- b'@' => self.default(&mut arg),
- b'\'' => self.help(&mut arg),
- _ => self.name(&mut arg),
- }
- } else {
- break;
- }
- }
-
- debug!("UsageParser::parse: vals...{:?}", arg.val_names);
- arg
- }
-
- fn name(&mut self, arg: &mut Arg<'help>) {
- debug!("UsageParser::name");
- if *self
- .usage
- .as_bytes()
- .get(self.pos)
- .expect(INTERNAL_ERROR_MSG)
- == b'<'
- && !self.explicit_name_set
- {
- arg.settings.set(ArgSettings::Required);
- }
- self.pos += 1;
- self.stop_at(name_end);
- let name = &self.usage[self.start..self.pos];
- if self.prev == UsageToken::Unknown {
- debug!("UsageParser::name: setting name...{}", name);
- arg.id = name.into();
- arg.name = name;
- if arg.long.is_none() && arg.short.is_none() {
- debug!("name: explicit name set...");
- self.explicit_name_set = true;
- self.prev = UsageToken::Name;
- }
- } else {
- debug!("UsageParser::name: setting val name...{}", name);
- if arg.val_names.is_empty() {
- arg.settings.set(ArgSettings::TakesValue);
- }
- let len = arg.val_names.len();
- arg.val_names.insert(len, name);
- self.prev = UsageToken::ValName;
- }
- }
-
- fn stop_at<F>(&mut self, f: F)
- where
- F: Fn(u8) -> bool,
- {
- debug!("UsageParser::stop_at");
- self.start = self.pos;
- self.pos += self.usage[self.start..]
- .bytes()
- .take_while(|&b| f(b))
- .count();
- }
-
- fn short_or_long(&mut self, arg: &mut Arg<'help>) {
- debug!("UsageParser::short_or_long");
- self.pos += 1;
- if *self
- .usage
- .as_bytes()
- .get(self.pos)
- .expect(INTERNAL_ERROR_MSG)
- == b'-'
- {
- self.pos += 1;
- self.long(arg);
- return;
- }
- self.short(arg)
- }
-
- fn long(&mut self, arg: &mut Arg<'help>) {
- debug!("UsageParser::long");
- self.stop_at(long_end);
- let name = &self.usage[self.start..self.pos];
- if !self.explicit_name_set {
- debug!("UsageParser::long: setting name...{}", name);
- arg.id = name.into();
- arg.name = name;
- }
- debug!("UsageParser::long: setting long...{}", name);
- arg.long = Some(name);
- self.prev = UsageToken::Long;
- }
-
- fn short(&mut self, arg: &mut Arg<'help>) {
- debug!("UsageParser::short");
- let start = &self.usage[self.pos..];
- let short = start.chars().next().expect(INTERNAL_ERROR_MSG);
- debug!("UsageParser::short: setting short...{}", short);
- arg.short = Some(short);
- if arg.name.is_empty() {
- // --long takes precedence but doesn't set self.explicit_name_set
- let name = &start[..short.len_utf8()];
- debug!("UsageParser::short: setting name...{}", name);
- arg.id = name.into();
- arg.name = name;
- }
- self.prev = UsageToken::Short;
- }
-
- // "something..."
- fn multiple(&mut self, arg: &mut Arg) {
- debug!("UsageParser::multiple");
- let mut dot_counter = 1;
- let start = self.pos;
- let mut bytes = self.usage[start..].bytes();
- while bytes.next() == Some(b'.') {
- dot_counter += 1;
- self.pos += 1;
- if dot_counter == 3 {
- debug!("UsageParser::multiple: setting multiple");
- arg.settings.set(ArgSettings::MultipleOccurrences);
- if arg.is_takes_value_set() {
- arg.settings.set(ArgSettings::MultipleValues);
- arg.settings.set(ArgSettings::UseValueDelimiter);
- arg.val_delim.get_or_insert(',');
- }
- self.prev = UsageToken::Multiple;
- self.pos += 1;
- break;
- }
- }
- }
-
- fn help(&mut self, arg: &mut Arg<'help>) {
- debug!("UsageParser::help");
- self.stop_at(help_start);
- self.start = self.pos + 1;
- self.pos = self.usage.len() - 1;
- debug!(
- "UsageParser::help: setting help...{}",
- &self.usage[self.start..self.pos]
- );
- arg.help = Some(&self.usage[self.start..self.pos]);
- self.pos += 1; // Move to next byte to keep from thinking ending ' is a start
- self.prev = UsageToken::Help;
- }
-
- fn default(&mut self, arg: &mut Arg<'help>) {
- debug!(
- "UsageParser::default: from=\"{}\"",
- &self.usage[self.pos..self.usage.len()]
- );
- self.pos += 1; // Skip @
- self.stop_at(default_value_end); // Find first space after value
- debug!(
- "UsageParser::default: setting default...\"{}\"",
- &self.usage[self.start..self.pos]
- );
- arg.settings.set(ArgSettings::TakesValue);
- arg.default_vals = vec![std::ffi::OsStr::new(&self.usage[self.start..self.pos])];
- self.prev = UsageToken::Default;
- }
-}
-
-#[inline]
-fn name_end(b: u8) -> bool {
- b != b']' && b != b'>'
-}
-
-#[inline]
-fn token(b: u8) -> bool {
- b != b'\'' && b != b'.' && b != b'<' && b != b'[' && b != b'-' && b != b'@'
-}
-
-#[inline]
-fn long_end(b: u8) -> bool {
- b != b'\'' && b != b'.' && b != b'<' && b != b'[' && b != b'=' && b != b' '
-}
-
-#[inline]
-fn help_start(b: u8) -> bool {
- b != b'\''
-}
-
-#[inline]
-fn default_value_end(b: u8) -> bool {
- b != b' '
-}
-
-#[cfg(test)]
-mod test {
- #![allow(deprecated)]
-
- use crate::builder::{Arg, ArgSettings};
-
- #[allow(clippy::cognitive_complexity)]
- #[test]
- fn create_flag_usage() {
- let a = Arg::from_usage("[flag] -f 'some help info'");
- assert_eq!(a.name, "flag");
- assert_eq!(a.short.unwrap(), 'f');
- assert!(a.long.is_none());
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(!a.is_multiple_occurrences_set());
- assert!(a.val_names.is_empty());
-
- let a = Arg::from_usage("[flag] --flag 'some help info'");
- assert_eq!(a.name, "flag");
- assert_eq!(a.long.unwrap(), "flag");
- assert!(a.short.is_none());
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(!a.is_multiple_occurrences_set());
- assert!(a.val_names.is_empty());
-
- let a = Arg::from_usage("--flag 'some help info'");
- assert_eq!(a.name, "flag");
- assert_eq!(a.long.unwrap(), "flag");
- assert!(a.short.is_none());
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(!a.is_multiple_occurrences_set());
- assert!(a.val_names.is_empty());
-
- let a = Arg::from_usage("[flag] -f --flag 'some help info'");
- assert_eq!(a.name, "flag");
- assert_eq!(a.short.unwrap(), 'f');
- assert_eq!(a.long.unwrap(), "flag");
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(!a.is_multiple_occurrences_set());
- assert!(a.val_names.is_empty());
-
- let a = Arg::from_usage("[flag] -f... 'some help info'");
- assert_eq!(a.name, "flag");
- assert_eq!(a.short.unwrap(), 'f');
- assert!(a.long.is_none());
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(a.is_multiple_occurrences_set());
- assert!(a.val_names.is_empty());
-
- let a = Arg::from_usage("[flag] -f --flag... 'some help info'");
- assert_eq!(a.name, "flag");
- assert_eq!(a.long.unwrap(), "flag");
- assert_eq!(a.short.unwrap(), 'f');
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(a.is_multiple_occurrences_set());
- assert!(a.val_names.is_empty());
-
- let a = Arg::from_usage("-f --flag... 'some help info'");
- assert_eq!(a.name, "flag");
- assert_eq!(a.long.unwrap(), "flag");
- assert_eq!(a.short.unwrap(), 'f');
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(a.is_multiple_occurrences_set());
- assert!(a.val_names.is_empty());
-
- let a = Arg::from_usage("--flags");
- assert_eq!(a.name, "flags");
- assert_eq!(a.long.unwrap(), "flags");
- assert!(a.val_names.is_empty());
-
- let a = Arg::from_usage("--flags...");
- assert_eq!(a.name, "flags");
- assert_eq!(a.long.unwrap(), "flags");
- assert!(a.is_multiple_occurrences_set());
- assert!(a.val_names.is_empty());
-
- let a = Arg::from_usage("[flags] -f");
- assert_eq!(a.name, "flags");
- assert_eq!(a.short.unwrap(), 'f');
- assert!(a.val_names.is_empty());
-
- let a = Arg::from_usage("[flags] -f...");
- assert_eq!(a.name, "flags");
- assert_eq!(a.short.unwrap(), 'f');
- assert!(a.is_multiple_occurrences_set());
- assert!(a.val_names.is_empty());
-
- let a = Arg::from_usage("-f 'some help info'");
- assert_eq!(a.name, "f");
- assert_eq!(a.short.unwrap(), 'f');
- assert!(a.long.is_none());
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(!a.is_multiple_occurrences_set());
- assert!(a.val_names.is_empty());
-
- let a = Arg::from_usage("-f");
- assert_eq!(a.name, "f");
- assert_eq!(a.short.unwrap(), 'f');
- assert!(a.val_names.is_empty());
-
- let a = Arg::from_usage("-f...");
- assert_eq!(a.name, "f");
- assert_eq!(a.short.unwrap(), 'f');
- assert!(a.is_multiple_occurrences_set());
- assert!(a.val_names.is_empty());
- }
-
- #[test]
- fn create_option_usage0() {
- // Short only
- let a = Arg::from_usage("[option] -o [opt] 'some help info'");
- assert_eq!(a.name, "option");
- assert_eq!(a.short.unwrap(), 'o');
- assert!(a.long.is_none());
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(!a.is_multiple_occurrences_set());
- assert!(!a.is_multiple_values_set());
- assert!(a.is_takes_value_set());
- assert!(!a.is_required_set());
- assert_eq!(a.val_names.iter().collect::<Vec<_>>(), [&"opt"]);
- }
-
- #[test]
- fn create_option_usage1() {
- let a = Arg::from_usage("-o [opt] 'some help info'");
- assert_eq!(a.name, "o");
- assert_eq!(a.short.unwrap(), 'o');
- assert!(a.long.is_none());
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(!a.is_multiple_occurrences_set());
- assert!(!a.is_multiple_values_set());
- assert!(a.is_takes_value_set());
- assert!(!a.is_required_set());
- assert_eq!(a.val_names.iter().collect::<Vec<_>>(), [&"opt"]);
- }
-
- #[test]
- fn create_option_usage2() {
- let a = Arg::from_usage("<option> -o <opt> 'some help info'");
- assert_eq!(a.name, "option");
- assert_eq!(a.short.unwrap(), 'o');
- assert!(a.long.is_none());
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(!a.is_multiple_occurrences_set());
- assert!(!a.is_multiple_values_set());
- assert!(a.is_takes_value_set());
- assert!(a.is_required_set());
- assert_eq!(a.val_names.iter().collect::<Vec<_>>(), [&"opt"]);
- }
-
- #[test]
- fn create_option_usage3() {
- let a = Arg::from_usage("-o <opt> 'some help info'");
- assert_eq!(a.name, "o");
- assert_eq!(a.short.unwrap(), 'o');
- assert!(a.long.is_none());
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(!a.is_multiple_occurrences_set());
- assert!(!a.is_multiple_values_set());
- assert!(a.is_takes_value_set());
- assert!(a.is_required_set());
- assert_eq!(a.val_names.iter().collect::<Vec<_>>(), [&"opt"]);
- }
-
- #[test]
- fn create_option_usage4() {
- let a = Arg::from_usage("[option] -o [opt]... 'some help info'");
- assert_eq!(a.name, "option");
- assert_eq!(a.short.unwrap(), 'o');
- assert!(a.long.is_none());
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(a.is_multiple_occurrences_set());
- assert!(a.is_multiple_values_set());
- assert!(a.is_takes_value_set());
- assert!(!a.is_required_set());
- assert_eq!(a.val_names.iter().collect::<Vec<_>>(), [&"opt"]);
- }
-
- #[test]
- fn create_option_usage5() {
- let a = Arg::from_usage("[option]... -o [opt] 'some help info'");
- assert_eq!(a.name, "option");
- assert_eq!(a.short.unwrap(), 'o');
- assert!(a.long.is_none());
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(a.is_multiple_occurrences_set());
- assert!(!a.is_multiple_values_set());
- assert!(a.is_takes_value_set());
- assert!(!a.is_required_set());
- assert_eq!(a.val_names.iter().collect::<Vec<_>>(), [&"opt"]);
- }
-
- #[test]
- fn create_option_usage6() {
- let a = Arg::from_usage("-o [opt]... 'some help info'");
- assert_eq!(a.name, "o");
- assert_eq!(a.short.unwrap(), 'o');
- assert!(a.long.is_none());
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(a.is_multiple_occurrences_set());
- assert!(a.is_multiple_values_set());
- assert!(a.is_takes_value_set());
- assert!(!a.is_required_set());
- assert_eq!(a.val_names.iter().collect::<Vec<_>>(), [&"opt"]);
- }
-
- #[test]
- fn create_option_usage7() {
- let a = Arg::from_usage("<option> -o <opt>... 'some help info'");
- assert_eq!(a.name, "option");
- assert_eq!(a.short.unwrap(), 'o');
- assert!(a.long.is_none());
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(a.is_multiple_occurrences_set());
- assert!(a.is_multiple_values_set());
- assert!(a.is_takes_value_set());
- assert!(a.is_required_set());
- assert_eq!(a.val_names.iter().collect::<Vec<_>>(), [&"opt"]);
- }
-
- #[test]
- fn create_option_usage8() {
- let a = Arg::from_usage("<option>... -o <opt> 'some help info'");
- assert_eq!(a.name, "option");
- assert_eq!(a.short.unwrap(), 'o');
- assert!(a.long.is_none());
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(a.is_multiple_occurrences_set());
- assert!(!a.is_multiple_values_set());
- assert!(a.is_takes_value_set());
- assert!(a.is_required_set());
- assert_eq!(a.val_names.iter().collect::<Vec<_>>(), [&"opt"]);
- }
-
- #[test]
- fn create_option_usage9() {
- let a = Arg::from_usage("-o <opt>... 'some help info'");
- assert_eq!(a.name, "o");
- assert_eq!(a.short.unwrap(), 'o');
- assert!(a.long.is_none());
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(a.is_multiple_occurrences_set());
- assert!(a.is_multiple_values_set());
- assert!(a.is_takes_value_set());
- assert!(a.is_required_set());
- assert_eq!(a.val_names.iter().collect::<Vec<_>>(), [&"opt"]);
- }
-
- #[test]
- fn create_option_usage_long1() {
- let a = Arg::from_usage("[option] --opt [opt] 'some help info'");
- assert_eq!(a.name, "option");
- assert_eq!(a.long.unwrap(), "opt");
- assert!(a.short.is_none());
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(!a.is_multiple_occurrences_set());
- assert!(!a.is_multiple_values_set());
- assert!(a.is_takes_value_set());
- assert!(!a.is_required_set());
- assert_eq!(a.val_names.iter().collect::<Vec<_>>(), [&"opt"]);
- }
-
- #[test]
- fn create_option_usage_long2() {
- let a = Arg::from_usage("--opt [option] 'some help info'");
- assert_eq!(a.name, "opt");
- assert_eq!(a.long.unwrap(), "opt");
- assert!(a.short.is_none());
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(!a.is_multiple_occurrences_set());
- assert!(!a.is_multiple_values_set());
- assert!(a.is_takes_value_set());
- assert!(!a.is_required_set());
- assert_eq!(a.val_names.iter().collect::<Vec<_>>(), [&"option"]);
- }
-
- #[test]
- fn create_option_usage_long3() {
- let a = Arg::from_usage("<option> --opt <opt> 'some help info'");
- assert_eq!(a.name, "option");
- assert_eq!(a.long.unwrap(), "opt");
- assert!(a.short.is_none());
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(!a.is_multiple_occurrences_set());
- assert!(!a.is_multiple_values_set());
- assert!(a.is_takes_value_set());
- assert!(a.is_required_set());
- assert_eq!(a.val_names.iter().collect::<Vec<_>>(), [&"opt"]);
- }
-
- #[test]
- fn create_option_usage_long4() {
- let a = Arg::from_usage("--opt <option> 'some help info'");
- assert_eq!(a.name, "opt");
- assert_eq!(a.long.unwrap(), "opt");
- assert!(a.short.is_none());
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(!a.is_multiple_occurrences_set());
- assert!(!a.is_multiple_values_set());
- assert!(a.is_takes_value_set());
- assert!(a.is_required_set());
- assert_eq!(a.val_names.iter().collect::<Vec<_>>(), [&"option"]);
- }
-
- #[test]
- fn create_option_usage_long5() {
- let a = Arg::from_usage("[option] --opt [opt]... 'some help info'");
- assert_eq!(a.name, "option");
- assert_eq!(a.long.unwrap(), "opt");
- assert!(a.short.is_none());
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(a.is_multiple_occurrences_set());
- assert!(a.is_multiple_values_set());
- assert!(a.is_takes_value_set());
- assert!(!a.is_required_set());
- assert_eq!(a.val_names.iter().collect::<Vec<_>>(), [&"opt"]);
- }
-
- #[test]
- fn create_option_usage_long6() {
- let a = Arg::from_usage("[option]... --opt [opt] 'some help info'");
- assert_eq!(a.name, "option");
- assert_eq!(a.long.unwrap(), "opt");
- assert!(a.short.is_none());
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(a.is_multiple_occurrences_set());
- assert!(!a.is_multiple_values_set());
- assert!(a.is_takes_value_set());
- assert!(!a.is_required_set());
- assert_eq!(a.val_names.iter().collect::<Vec<_>>(), [&"opt"]);
- }
-
- #[test]
- fn create_option_usage_long7() {
- let a = Arg::from_usage("--opt [option]... 'some help info'");
- assert_eq!(a.name, "opt");
- assert_eq!(a.long.unwrap(), "opt");
- assert!(a.short.is_none());
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(a.is_multiple_occurrences_set());
- assert!(a.is_multiple_values_set());
- assert!(a.is_takes_value_set());
- assert!(!a.is_required_set());
- assert_eq!(a.val_names.iter().collect::<Vec<_>>(), [&"option"]);
- }
-
- #[test]
- fn create_option_usage_long8() {
- let a = Arg::from_usage("<option> --opt <opt>... 'some help info'");
- assert_eq!(a.name, "option");
- assert_eq!(a.long.unwrap(), "opt");
- assert!(a.short.is_none());
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(a.is_multiple_occurrences_set());
- assert!(a.is_multiple_values_set());
- assert!(a.is_takes_value_set());
- assert!(a.is_required_set());
- assert_eq!(a.val_names.iter().collect::<Vec<_>>(), [&"opt"]);
- }
-
- #[test]
- fn create_option_usage_long9() {
- let a = Arg::from_usage("<option>... --opt <opt> 'some help info'");
- assert_eq!(a.name, "option");
- assert_eq!(a.long.unwrap(), "opt");
- assert!(a.short.is_none());
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(a.is_multiple_occurrences_set());
- assert!(!a.is_multiple_values_set());
- assert!(a.is_takes_value_set());
- assert!(a.is_required_set());
- assert_eq!(a.val_names.iter().collect::<Vec<_>>(), [&"opt"]);
- }
-
- #[test]
- fn create_option_usage_long10() {
- let a = Arg::from_usage("--opt <option>... 'some help info'");
- assert_eq!(a.name, "opt");
- assert_eq!(a.long.unwrap(), "opt");
- assert!(a.short.is_none());
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(a.is_multiple_occurrences_set());
- assert!(a.is_multiple_values_set());
- assert!(a.is_takes_value_set());
- assert!(a.is_required_set());
- assert_eq!(a.val_names.iter().collect::<Vec<_>>(), [&"option"]);
- }
-
- #[test]
- fn create_option_usage_long_equals1() {
- let a = Arg::from_usage("[option] --opt=[opt] 'some help info'");
- assert_eq!(a.name, "option");
- assert_eq!(a.long.unwrap(), "opt");
- assert!(a.short.is_none());
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(!a.is_multiple_occurrences_set());
- assert!(!a.is_multiple_values_set());
- assert!(a.is_takes_value_set());
- assert!(!a.is_required_set());
- assert_eq!(a.val_names.iter().collect::<Vec<_>>(), [&"opt"]);
- }
-
- #[test]
- fn create_option_usage_long_equals2() {
- let a = Arg::from_usage("--opt=[option] 'some help info'");
- assert_eq!(a.name, "opt");
- assert_eq!(a.long.unwrap(), "opt");
- assert!(a.short.is_none());
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(!a.is_multiple_occurrences_set());
- assert!(!a.is_multiple_values_set());
- assert!(a.is_takes_value_set());
- assert!(!a.is_required_set());
- assert_eq!(a.val_names.iter().collect::<Vec<_>>(), [&"option"]);
- }
-
- #[test]
- fn create_option_usage_long_equals3() {
- let a = Arg::from_usage("<option> --opt=<opt> 'some help info'");
- assert_eq!(a.name, "option");
- assert_eq!(a.long.unwrap(), "opt");
- assert!(a.short.is_none());
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(!a.is_multiple_occurrences_set());
- assert!(!a.is_multiple_values_set());
- assert!(a.is_takes_value_set());
- assert!(a.is_required_set());
- assert_eq!(a.val_names.iter().collect::<Vec<_>>(), [&"opt"]);
- }
-
- #[test]
- fn create_option_usage_long_equals4() {
- let a = Arg::from_usage("--opt=<option> 'some help info'");
- assert_eq!(a.name, "opt");
- assert_eq!(a.long.unwrap(), "opt");
- assert!(a.short.is_none());
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(!a.is_multiple_occurrences_set());
- assert!(!a.is_multiple_values_set());
- assert!(a.is_takes_value_set());
- assert!(a.is_required_set());
- assert_eq!(a.val_names.iter().collect::<Vec<_>>(), [&"option"]);
- }
-
- #[test]
- fn create_option_usage_long_equals5() {
- let a = Arg::from_usage("[option] --opt=[opt]... 'some help info'");
- assert_eq!(a.name, "option");
- assert_eq!(a.long.unwrap(), "opt");
- assert!(a.short.is_none());
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(a.is_multiple_occurrences_set());
- assert!(a.is_multiple_values_set());
- assert!(a.is_takes_value_set());
- assert!(!a.is_required_set());
- assert_eq!(a.val_names.iter().collect::<Vec<_>>(), [&"opt"]);
- }
-
- #[test]
- fn create_option_usage_long_equals6() {
- let a = Arg::from_usage("[option]... --opt=[opt] 'some help info'");
- assert_eq!(a.name, "option");
- assert_eq!(a.long.unwrap(), "opt");
- assert!(a.short.is_none());
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(a.is_multiple_occurrences_set());
- assert!(!a.is_multiple_values_set());
- assert!(a.is_takes_value_set());
- assert!(!a.is_required_set());
- assert_eq!(a.val_names.iter().collect::<Vec<_>>(), [&"opt"]);
- }
-
- #[test]
- fn create_option_usage_long_equals7() {
- let a = Arg::from_usage("--opt=[option]... 'some help info'");
- assert_eq!(a.name, "opt");
- assert_eq!(a.long.unwrap(), "opt");
- assert!(a.short.is_none());
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(a.is_multiple_occurrences_set());
- assert!(a.is_multiple_values_set());
- assert!(a.is_takes_value_set());
- assert!(!a.is_required_set());
- assert_eq!(a.val_names.iter().collect::<Vec<_>>(), [&"option"]);
- }
-
- #[test]
- fn create_option_usage_long_equals8() {
- let a = Arg::from_usage("<option> --opt=<opt>... 'some help info'");
- assert_eq!(a.name, "option");
- assert_eq!(a.long.unwrap(), "opt");
- assert!(a.short.is_none());
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(a.is_multiple_occurrences_set());
- assert!(a.is_multiple_values_set());
- assert!(a.is_takes_value_set());
- assert!(a.is_required_set());
- assert_eq!(a.val_names.iter().collect::<Vec<_>>(), [&"opt"]);
- }
-
- #[test]
- fn create_option_usage_long_equals9() {
- let a = Arg::from_usage("<option>... --opt=<opt> 'some help info'");
- assert_eq!(a.name, "option");
- assert_eq!(a.long.unwrap(), "opt");
- assert!(a.short.is_none());
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(a.is_multiple_occurrences_set());
- assert!(!a.is_multiple_values_set());
- assert!(a.is_takes_value_set());
- assert!(a.is_required_set());
- assert_eq!(a.val_names.iter().collect::<Vec<_>>(), [&"opt"]);
- }
-
- #[test]
- fn create_option_usage_long_equals10() {
- let a = Arg::from_usage("--opt=<option>... 'some help info'");
- assert_eq!(a.name, "opt");
- assert_eq!(a.long.unwrap(), "opt");
- assert!(a.short.is_none());
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(a.is_multiple_occurrences_set());
- assert!(a.is_multiple_values_set());
- assert!(a.is_takes_value_set());
- assert!(a.is_required_set());
- assert_eq!(a.val_names.iter().collect::<Vec<_>>(), [&"option"]);
- }
-
- #[test]
- fn create_option_usage_both1() {
- let a = Arg::from_usage("[option] -o --opt [option] 'some help info'");
- assert_eq!(a.name, "option");
- assert_eq!(a.long.unwrap(), "opt");
- assert_eq!(a.short.unwrap(), 'o');
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(!a.is_multiple_occurrences_set());
- assert!(!a.is_multiple_values_set());
- assert!(a.is_takes_value_set());
- assert!(!a.is_required_set());
- assert_eq!(a.val_names.iter().collect::<Vec<_>>(), [&"option"]);
- }
-
- #[test]
- fn create_option_usage_both2() {
- let a = Arg::from_usage("-o --opt [option] 'some help info'");
- assert_eq!(a.name, "opt");
- assert_eq!(a.long.unwrap(), "opt");
- assert_eq!(a.short.unwrap(), 'o');
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(!a.is_multiple_occurrences_set());
- assert!(!a.is_multiple_values_set());
- assert!(a.is_takes_value_set());
- assert!(!a.is_required_set());
- assert_eq!(a.val_names.iter().collect::<Vec<_>>(), [&"option"]);
- }
-
- #[test]
- fn create_option_usage_both3() {
- let a = Arg::from_usage("<option> -o --opt <opt> 'some help info'");
- assert_eq!(a.name, "option");
- assert_eq!(a.long.unwrap(), "opt");
- assert_eq!(a.short.unwrap(), 'o');
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(!a.is_multiple_occurrences_set());
- assert!(!a.is_multiple_values_set());
- assert!(a.is_takes_value_set());
- assert!(a.is_required_set());
- assert_eq!(a.val_names.iter().collect::<Vec<_>>(), [&"opt"]);
- }
-
- #[test]
- fn create_option_usage_both4() {
- let a = Arg::from_usage("-o --opt <option> 'some help info'");
- assert_eq!(a.name, "opt");
- assert_eq!(a.long.unwrap(), "opt");
- assert_eq!(a.short.unwrap(), 'o');
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(!a.is_multiple_occurrences_set());
- assert!(!a.is_multiple_values_set());
- assert!(a.is_takes_value_set());
- assert!(a.is_required_set());
- assert_eq!(a.val_names.iter().collect::<Vec<_>>(), [&"option"]);
- }
-
- #[test]
- fn create_option_usage_both5() {
- let a = Arg::from_usage("[option]... -o --opt [option] 'some help info'");
- assert_eq!(a.name, "option");
- assert_eq!(a.long.unwrap(), "opt");
- assert_eq!(a.short.unwrap(), 'o');
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(a.is_multiple_occurrences_set());
- assert!(!a.is_multiple_values_set());
- assert!(a.is_takes_value_set());
- assert!(!a.is_required_set());
- assert_eq!(a.val_names.iter().collect::<Vec<_>>(), [&"option"]);
- }
-
- #[test]
- fn create_option_usage_both6() {
- let a = Arg::from_usage("-o --opt [option]... 'some help info'");
- assert_eq!(a.name, "opt");
- assert_eq!(a.long.unwrap(), "opt");
- assert_eq!(a.short.unwrap(), 'o');
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(a.is_multiple_occurrences_set());
- assert!(a.is_multiple_values_set());
- assert!(a.is_takes_value_set());
- assert!(!a.is_required_set());
- assert_eq!(a.val_names.iter().collect::<Vec<_>>(), [&"option"]);
- }
-
- #[test]
- fn create_option_usage_both7() {
- let a = Arg::from_usage("<option>... -o --opt <opt> 'some help info'");
- assert_eq!(a.name, "option");
- assert_eq!(a.long.unwrap(), "opt");
- assert_eq!(a.short.unwrap(), 'o');
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(a.is_multiple_occurrences_set());
- assert!(!a.is_multiple_values_set());
- assert!(a.is_takes_value_set());
- assert!(a.is_required_set());
- assert_eq!(a.val_names.iter().collect::<Vec<_>>(), [&"opt"]);
- }
-
- #[test]
- fn create_option_usage_both8() {
- let a = Arg::from_usage("-o --opt <option>... 'some help info'");
- assert_eq!(a.name, "opt");
- assert_eq!(a.long.unwrap(), "opt");
- assert_eq!(a.short.unwrap(), 'o');
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(a.is_multiple_occurrences_set());
- assert!(a.is_multiple_values_set());
- assert!(a.is_takes_value_set());
- assert!(a.is_required_set());
- assert_eq!(a.val_names.iter().collect::<Vec<_>>(), [&"option"]);
- }
-
- #[test]
- fn create_option_usage_both_equals1() {
- let a = Arg::from_usage("[option] -o --opt=[option] 'some help info'");
- assert_eq!(a.name, "option");
- assert_eq!(a.long.unwrap(), "opt");
- assert_eq!(a.short.unwrap(), 'o');
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(!a.is_multiple_occurrences_set());
- assert!(!a.is_multiple_values_set());
- assert!(a.is_takes_value_set());
- assert!(!a.is_required_set());
- assert_eq!(a.val_names.iter().collect::<Vec<_>>(), [&"option"]);
- }
-
- #[test]
- fn create_option_usage_both_equals2() {
- let a = Arg::from_usage("-o --opt=[option] 'some help info'");
- assert_eq!(a.name, "opt");
- assert_eq!(a.long.unwrap(), "opt");
- assert_eq!(a.short.unwrap(), 'o');
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(!a.is_multiple_occurrences_set());
- assert!(!a.is_multiple_values_set());
- assert!(a.is_takes_value_set());
- assert!(!a.is_required_set());
- assert_eq!(a.val_names.iter().collect::<Vec<_>>(), [&"option"]);
- }
-
- #[test]
- fn create_option_usage_both_equals3() {
- let a = Arg::from_usage("<option> -o --opt=<opt> 'some help info'");
- assert_eq!(a.name, "option");
- assert_eq!(a.long.unwrap(), "opt");
- assert_eq!(a.short.unwrap(), 'o');
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(!a.is_multiple_occurrences_set());
- assert!(!a.is_multiple_values_set());
- assert!(a.is_takes_value_set());
- assert!(a.is_required_set());
- assert_eq!(a.val_names.iter().collect::<Vec<_>>(), [&"opt"]);
- }
-
- #[test]
- fn create_option_usage_both_equals4() {
- let a = Arg::from_usage("-o --opt=<option> 'some help info'");
- assert_eq!(a.name, "opt");
- assert_eq!(a.long.unwrap(), "opt");
- assert_eq!(a.short.unwrap(), 'o');
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(!a.is_multiple_occurrences_set());
- assert!(!a.is_multiple_values_set());
- assert!(a.is_takes_value_set());
- assert!(a.is_required_set());
- assert_eq!(a.val_names.iter().collect::<Vec<_>>(), [&"option"]);
- }
-
- #[test]
- fn create_option_usage_both_equals5() {
- let a = Arg::from_usage("[option]... -o --opt=[option] 'some help info'");
- assert_eq!(a.name, "option");
- assert_eq!(a.long.unwrap(), "opt");
- assert_eq!(a.short.unwrap(), 'o');
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(a.is_multiple_occurrences_set());
- assert!(!a.is_multiple_values_set());
- assert!(a.is_takes_value_set());
- assert!(!a.is_required_set());
- assert_eq!(a.val_names.iter().collect::<Vec<_>>(), [&"option"]);
- }
-
- #[test]
- fn create_option_usage_both_equals6() {
- let a = Arg::from_usage("-o --opt=[option]... 'some help info'");
- assert_eq!(a.name, "opt");
- assert_eq!(a.long.unwrap(), "opt");
- assert_eq!(a.short.unwrap(), 'o');
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(a.is_multiple_occurrences_set());
- assert!(a.is_multiple_values_set());
- assert!(a.is_takes_value_set());
- assert!(!a.is_required_set());
- assert_eq!(a.val_names.iter().collect::<Vec<_>>(), [&"option"]);
- }
-
- #[test]
- fn create_option_usage_both_equals7() {
- let a = Arg::from_usage("<option>... -o --opt=<opt> 'some help info'");
- assert_eq!(a.name, "option");
- assert_eq!(a.long.unwrap(), "opt");
- assert_eq!(a.short.unwrap(), 'o');
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(a.is_multiple_occurrences_set());
- assert!(!a.is_multiple_values_set());
- assert!(a.is_takes_value_set());
- assert!(a.is_required_set());
- assert_eq!(a.val_names.iter().collect::<Vec<_>>(), [&"opt"]);
- }
-
- #[test]
- fn create_option_usage_both_equals8() {
- let a = Arg::from_usage("-o --opt=<option>... 'some help info'");
- assert_eq!(a.name, "opt");
- assert_eq!(a.long.unwrap(), "opt");
- assert_eq!(a.short.unwrap(), 'o');
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(a.is_multiple_occurrences_set());
- assert!(a.is_multiple_values_set());
- assert!(a.is_takes_value_set());
- assert!(a.is_required_set());
- assert_eq!(a.val_names.iter().collect::<Vec<_>>(), [&"option"]);
- }
-
- #[test]
- fn create_option_with_vals1() {
- let a = Arg::from_usage("-o <file> <mode> 'some help info'");
- assert_eq!(a.name, "o");
- assert!(a.long.is_none());
- assert_eq!(a.short.unwrap(), 'o');
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(!a.is_multiple_occurrences_set());
- assert!(!a.is_multiple_values_set());
- assert!(a.is_takes_value_set());
- assert!(a.is_required_set());
- assert_eq!(a.val_names.iter().collect::<Vec<_>>(), [&"file", &"mode"]);
- }
-
- #[test]
- fn create_option_with_vals2() {
- let a = Arg::from_usage("-o <file> <mode>... 'some help info'");
- assert_eq!(a.name, "o");
- assert!(a.long.is_none());
- assert_eq!(a.short.unwrap(), 'o');
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(a.is_multiple_occurrences_set());
- assert!(a.is_multiple_values_set());
- assert!(a.is_takes_value_set());
- assert!(a.is_required_set());
- assert_eq!(a.val_names.iter().collect::<Vec<_>>(), [&"file", &"mode"]);
- }
-
- #[test]
- fn create_option_with_vals3() {
- let a = Arg::from_usage("--opt <file> <mode>... 'some help info'");
- assert_eq!(a.name, "opt");
- assert!(a.short.is_none());
- assert_eq!(a.long.unwrap(), "opt");
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(a.is_multiple_occurrences_set());
- assert!(a.is_multiple_values_set());
- assert!(a.is_takes_value_set());
- assert!(a.is_required_set());
- assert_eq!(a.val_names.iter().collect::<Vec<_>>(), [&"file", &"mode"]);
- }
-
- #[test]
- fn create_option_with_vals4() {
- let a = Arg::from_usage("[myopt] --opt <file> <mode> 'some help info'");
- assert_eq!(a.name, "myopt");
- assert!(a.short.is_none());
- assert_eq!(a.long.unwrap(), "opt");
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(!a.is_multiple_occurrences_set());
- assert!(!a.is_multiple_values_set());
- assert!(a.is_takes_value_set());
- assert!(!a.is_required_set());
- assert_eq!(a.val_names.iter().collect::<Vec<_>>(), [&"file", &"mode"]);
- }
-
- #[test]
- fn create_option_with_vals5() {
- let a = Arg::from_usage("--opt <file> <mode> 'some help info'");
- assert_eq!(a.name, "opt");
- assert!(a.short.is_none());
- assert_eq!(a.long.unwrap(), "opt");
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(!a.is_multiple_occurrences_set());
- assert!(!a.is_multiple_values_set());
- assert!(a.is_takes_value_set());
- assert!(a.is_required_set());
- }
-
- #[test]
- fn create_positional_usage() {
- let a = Arg::from_usage("[pos] 'some help info'");
- assert_eq!(a.name, "pos");
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(!a.is_multiple_occurrences_set());
- assert!(!a.is_multiple_values_set());
- assert!(!a.is_required_set());
- assert!(a.val_names.is_empty());
- }
-
- #[test]
- fn create_positional_usage0() {
- let a = Arg::from_usage("<pos> 'some help info'");
- assert_eq!(a.name, "pos");
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(!a.is_multiple_occurrences_set());
- assert!(!a.is_multiple_values_set());
- assert!(a.is_required_set());
- assert!(a.val_names.is_empty());
- }
-
- #[test]
- fn pos_mult_help() {
- let a = Arg::from_usage("[pos]... 'some help info'");
- assert_eq!(a.name, "pos");
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(a.is_multiple_occurrences_set());
- assert!(!a.is_multiple_values_set());
- assert!(!a.is_required_set());
- assert!(a.val_names.is_empty());
- }
-
- #[test]
- fn pos_help_lit_single_quote() {
- let a = Arg::from_usage("[pos]... 'some help\' info'");
- assert_eq!(a.name, "pos");
- assert_eq!(a.help.unwrap(), "some help' info");
- assert!(a.is_multiple_occurrences_set());
- assert!(!a.is_multiple_values_set());
- assert!(!a.is_required_set());
- assert!(a.val_names.is_empty());
- }
-
- #[test]
- fn pos_help_double_lit_single_quote() {
- let a = Arg::from_usage("[pos]... 'some \'help\' info'");
- assert_eq!(a.name, "pos");
- assert_eq!(a.help.unwrap(), "some 'help' info");
- assert!(a.is_multiple_occurrences_set());
- assert!(!a.is_multiple_values_set());
- assert!(!a.is_required_set());
- assert!(a.val_names.is_empty());
- }
-
- #[test]
- fn pos_help_newline() {
- let a = Arg::from_usage(
- "[pos]... 'some help{n}\
- info'",
- );
- assert_eq!(a.name, "pos");
- assert_eq!(a.help.unwrap(), "some help{n}info");
- assert!(a.is_multiple_occurrences_set());
- assert!(!a.is_multiple_values_set());
- assert!(!a.is_required_set());
- assert!(a.val_names.is_empty());
- }
-
- #[test]
- fn pos_help_newline_lit_sq() {
- let a = Arg::from_usage(
- "[pos]... 'some help\' stuff{n}\
- info'",
- );
- assert_eq!(a.name, "pos");
- assert_eq!(a.help.unwrap(), "some help' stuff{n}info");
- assert!(a.is_multiple_occurrences_set());
- assert!(!a.is_multiple_values_set());
- assert!(!a.is_required_set());
- assert!(a.val_names.is_empty());
- }
-
- #[test]
- fn pos_req_mult_help() {
- let a = Arg::from_usage("<pos>... 'some help info'");
- assert_eq!(a.name, "pos");
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(a.is_multiple_occurrences_set());
- assert!(!a.is_multiple_values_set());
- assert!(a.is_required_set());
- assert!(a.val_names.is_empty());
- }
-
- #[test]
- fn pos_req() {
- let a = Arg::from_usage("<pos>");
- assert_eq!(a.name, "pos");
- assert!(!a.is_multiple_occurrences_set());
- assert!(!a.is_multiple_values_set());
- assert!(a.is_required_set());
- assert!(a.val_names.is_empty());
- }
-
- #[test]
- fn pos_mult() {
- let a = Arg::from_usage("[pos]...");
- assert_eq!(a.name, "pos");
- assert!(a.is_multiple_occurrences_set());
- assert!(!a.is_multiple_values_set());
- assert!(!a.is_required_set());
- assert!(a.val_names.is_empty());
- }
-
- #[test]
- fn pos_req_mult_def_help() {
- let a = Arg::from_usage("<pos>... @a 'some help info'");
- assert_eq!(a.name, "pos");
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(a.is_multiple_occurrences_set());
- assert!(!a.is_multiple_values_set());
- assert!(a.is_required_set());
- assert!(a.val_names.is_empty());
- assert_eq!(a.default_vals, vec![std::ffi::OsStr::new("a")]);
- }
-
- #[test]
- fn create_option_with_vals1_def() {
- let a = Arg::from_usage("-o <file> <mode> @a 'some help info'");
- assert_eq!(a.name, "o");
- assert!(a.long.is_none());
- assert_eq!(a.short.unwrap(), 'o');
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(!a.is_multiple_occurrences_set());
- assert!(!a.is_multiple_values_set());
- assert!(a.is_takes_value_set());
- assert!(a.is_required_set());
- assert_eq!(a.val_names.iter().collect::<Vec<_>>(), [&"file", &"mode"]);
- assert_eq!(a.default_vals, vec![std::ffi::OsStr::new("a")]);
- }
-
- #[test]
- fn create_option_with_vals4_def() {
- let a = Arg::from_usage("[myopt] --opt <file> <mode> @a 'some help info'");
- assert_eq!(a.name, "myopt");
- assert!(a.short.is_none());
- assert_eq!(a.long.unwrap(), "opt");
- assert_eq!(a.help.unwrap(), "some help info");
- assert!(!a.is_multiple_occurrences_set());
- assert!(!a.is_multiple_values_set());
- assert!(a.is_takes_value_set());
- assert!(!a.is_required_set());
- assert_eq!(a.val_names.iter().collect::<Vec<_>>(), [&"file", &"mode"]);
- assert_eq!(a.default_vals, vec![std::ffi::OsStr::new("a")]);
- }
-
- #[test]
- fn nonascii() {
- let a = Arg::from_usage("<ASCII> 'üñíčöĐ€'");
- assert_eq!(a.name, "ASCII");
- assert_eq!(a.help, Some("üñíčöĐ€"));
- let a = Arg::from_usage("<üñíčöĐ€> 'ASCII'");
- assert_eq!(a.name, "üñíčöĐ€");
- assert_eq!(a.help, Some("ASCII"));
- let a = Arg::from_usage("<üñíčöĐ€> 'üñíčöĐ€'");
- assert_eq!(a.name, "üñíčöĐ€");
- assert_eq!(a.help, Some("üñíčöĐ€"));
- let a = Arg::from_usage("-ø 'ø'");
- assert_eq!(a.name, "ø");
- assert_eq!(a.short, Some('ø'));
- assert_eq!(a.help, Some("ø"));
- let a = Arg::from_usage("--üñíčöĐ€ 'Nōṫ ASCII'");
- assert_eq!(a.name, "üñíčöĐ€");
- assert_eq!(a.long, Some("üñíčöĐ€"));
- assert_eq!(a.help, Some("Nōṫ ASCII"));
- let a = Arg::from_usage("[ñämê] --ôpt=[üñíčöĐ€] 'hælp'");
- assert_eq!(a.name, "ñämê");
- assert_eq!(a.long, Some("ôpt"));
- assert_eq!(a.val_names.iter().collect::<Vec<_>>(), [&"üñíčöĐ€"]);
- assert_eq!(a.help, Some("hælp"));
- }
-
- #[test]
- fn value_names_building_num_vals_from_usage() {
- use crate::Command;
- let m = Command::new("test")
- .arg(Arg::from_usage("--pos <who> <what> <why>"))
- .try_get_matches_from(vec!["myprog", "--pos", "val1", "val2", "val3"]);
-
- assert!(m.is_ok(), "{:?}", m.unwrap_err().kind());
- let m = m.unwrap();
-
- assert_eq!(
- m.values_of("pos").unwrap().collect::<Vec<_>>(),
- ["val1", "val2", "val3"]
- );
- }
-
- #[test]
- fn issue_665() {
- use crate::{error::ErrorKind, Command};
- // Verify fix for "arg_from_usage(): required values not being enforced when followed by another option"
- let res = Command::new("tester")
- .arg(Arg::from_usage("-v, --reroll-count=[N] 'Mark the patch series as PATCH vN'"))
- .arg(
- Arg::from_usage("--subject-prefix [Subject-Prefix] 'Use [Subject-Prefix] instead of the standard [PATCH] prefix'")
- .setting(ArgSettings::ForbidEmptyValues)
- )
- .try_get_matches_from(vec!["test", "--subject-prefix", "-v", "2"]);
-
- assert!(res.is_err());
- assert_eq!(res.unwrap_err().kind(), ErrorKind::EmptyValue);
- }
-}
diff --git a/vendor/clap/src/builder/value_hint.rs b/vendor/clap/src/builder/value_hint.rs
deleted file mode 100644
index 7c35d1eb3..000000000
--- a/vendor/clap/src/builder/value_hint.rs
+++ /dev/null
@@ -1,95 +0,0 @@
-use std::str::FromStr;
-
-/// Provide shell with hint on how to complete an argument.
-///
-/// See [Arg::value_hint][crate::Arg::value_hint] to set this on an argument.
-///
-/// See the `clap_complete` crate for completion script generation.
-///
-/// Overview of which hints are supported by which shell:
-///
-/// | Hint | zsh | fish[^1]|
-/// | ---------------------- | --- | ------- |
-/// | `AnyPath` | Yes | Yes |
-/// | `FilePath` | Yes | Yes |
-/// | `DirPath` | Yes | Yes |
-/// | `ExecutablePath` | Yes | Partial |
-/// | `CommandName` | Yes | Yes |
-/// | `CommandString` | Yes | Partial |
-/// | `CommandWithArguments` | Yes | |
-/// | `Username` | Yes | Yes |
-/// | `Hostname` | Yes | Yes |
-/// | `Url` | Yes | |
-/// | `EmailAddress` | Yes | |
-///
-/// [^1]: fish completions currently only support named arguments (e.g. -o or --opt), not
-/// positional arguments.
-#[derive(Debug, PartialEq, Eq, Hash, Copy, Clone)]
-#[non_exhaustive]
-pub enum ValueHint {
- /// Default value if hint is not specified. Follows shell default behavior, which is usually
- /// auto-completing filenames.
- Unknown,
- /// None of the hints below apply. Disables shell completion for this argument.
- Other,
- /// Any existing path.
- AnyPath,
- /// Path to a file.
- FilePath,
- /// Path to a directory.
- DirPath,
- /// Path to an executable file.
- ExecutablePath,
- /// Name of a command, without arguments. May be relative to PATH, or full path to executable.
- CommandName,
- /// A single string containing a command and its arguments.
- CommandString,
- /// Capture the remaining arguments as a command name and arguments for that command. This is
- /// common when writing shell wrappers that execute anther command, for example `sudo` or `env`.
- ///
- /// This hint is special, the argument must be a positional argument and have
- /// [`.multiple_values(true)`] and Command must use [`Command::trailing_var_arg(true)`]. The result is that the
- /// command line `my_app ls -la /` will be parsed as `["ls", "-la", "/"]` and clap won't try to
- /// parse the `-la` argument itself.
- ///
- /// [`Command::trailing_var_arg(true)`]: crate::Command::trailing_var_arg
- /// [`.multiple_values(true)`]: crate::Arg::multiple_values()
- CommandWithArguments,
- /// Name of a local operating system user.
- Username,
- /// Host name of a computer.
- /// Shells usually parse `/etc/hosts` and `.ssh/known_hosts` to complete hostnames.
- Hostname,
- /// Complete web address.
- Url,
- /// Email address.
- EmailAddress,
-}
-
-impl Default for ValueHint {
- fn default() -> Self {
- ValueHint::Unknown
- }
-}
-
-impl FromStr for ValueHint {
- type Err = String;
- fn from_str(s: &str) -> Result<Self, <Self as FromStr>::Err> {
- Ok(match &*s.to_ascii_lowercase() {
- "unknown" => ValueHint::Unknown,
- "other" => ValueHint::Other,
- "anypath" => ValueHint::AnyPath,
- "filepath" => ValueHint::FilePath,
- "dirpath" => ValueHint::DirPath,
- "executablepath" => ValueHint::ExecutablePath,
- "commandname" => ValueHint::CommandName,
- "commandstring" => ValueHint::CommandString,
- "commandwitharguments" => ValueHint::CommandWithArguments,
- "username" => ValueHint::Username,
- "hostname" => ValueHint::Hostname,
- "url" => ValueHint::Url,
- "emailaddress" => ValueHint::EmailAddress,
- _ => return Err(format!("unknown ValueHint: `{}`", s)),
- })
- }
-}
diff --git a/vendor/clap/src/builder/value_parser.rs b/vendor/clap/src/builder/value_parser.rs
deleted file mode 100644
index 0492f2782..000000000
--- a/vendor/clap/src/builder/value_parser.rs
+++ /dev/null
@@ -1,2089 +0,0 @@
-use std::convert::TryInto;
-use std::ops::RangeBounds;
-
-use crate::parser::AnyValue;
-use crate::parser::AnyValueId;
-
-/// Parse/validate argument values
-///
-/// Specified with [`Arg::value_parser`][crate::Arg::value_parser].
-///
-/// `ValueParser` defines how to convert a raw argument value into a validated and typed value for
-/// use within an application.
-///
-/// See
-/// - [`value_parser!`][crate::value_parser] for automatically selecting an implementation for a given type
-/// - [`ValueParser::new`] for additional [`TypedValueParser`] that can be used
-///
-/// # Example
-///
-/// ```rust
-/// let mut cmd = clap::Command::new("raw")
-/// .arg(
-/// clap::Arg::new("color")
-/// .long("color")
-/// .value_parser(["always", "auto", "never"])
-/// .default_value("auto")
-/// )
-/// .arg(
-/// clap::Arg::new("hostname")
-/// .long("hostname")
-/// .value_parser(clap::builder::NonEmptyStringValueParser::new())
-/// .takes_value(true)
-/// .required(true)
-/// )
-/// .arg(
-/// clap::Arg::new("port")
-/// .long("port")
-/// .value_parser(clap::value_parser!(u16).range(3000..))
-/// .takes_value(true)
-/// .required(true)
-/// );
-///
-/// let m = cmd.try_get_matches_from_mut(
-/// ["cmd", "--hostname", "rust-lang.org", "--port", "3001"]
-/// ).unwrap();
-///
-/// let color: &String = m.get_one("color")
-/// .expect("default");
-/// assert_eq!(color, "auto");
-///
-/// let hostname: &String = m.get_one("hostname")
-/// .expect("required");
-/// assert_eq!(hostname, "rust-lang.org");
-///
-/// let port: u16 = *m.get_one("port")
-/// .expect("required");
-/// assert_eq!(port, 3001);
-/// ```
-pub struct ValueParser(ValueParserInner);
-
-enum ValueParserInner {
- // Common enough to optimize and for possible values
- Bool,
- // Common enough to optimize
- String,
- // Common enough to optimize
- OsString,
- // Common enough to optimize
- PathBuf,
- Other(Box<dyn AnyValueParser>),
-}
-
-impl ValueParser {
- /// Custom parser for argument values
- ///
- /// To create a custom parser, see [`TypedValueParser`]
- ///
- /// Pre-existing implementations include:
- /// - [`EnumValueParser`] and [`PossibleValuesParser`] for static enumerated values
- /// - [`BoolishValueParser`] and [`FalseyValueParser`] for alternative `bool` implementations
- /// - [`RangedI64ValueParser`] and [`RangedU64ValueParser`]
- /// - [`NonEmptyStringValueParser`]
- ///
- /// # Example
- ///
- /// ```rust
- /// type EnvVar = (String, Option<String>);
- /// fn parse_env_var(env: &str) -> Result<EnvVar, std::io::Error> {
- /// if let Some((var, value)) = env.split_once('=') {
- /// Ok((var.to_owned(), Some(value.to_owned())))
- /// } else {
- /// Ok((env.to_owned(), None))
- /// }
- /// }
- ///
- /// let mut cmd = clap::Command::new("raw")
- /// .arg(
- /// clap::Arg::new("env")
- /// .value_parser(clap::builder::ValueParser::new(parse_env_var))
- /// .required(true)
- /// );
- ///
- /// let m = cmd.try_get_matches_from_mut(["cmd", "key=value"]).unwrap();
- /// let port: &EnvVar = m.get_one("env")
- /// .expect("required");
- /// assert_eq!(*port, ("key".into(), Some("value".into())));
- /// ```
- pub fn new<P>(other: P) -> Self
- where
- P: TypedValueParser,
- P::Value: Send + Sync + Clone,
- {
- Self(ValueParserInner::Other(Box::new(other)))
- }
-
- /// [`bool`] parser for argument values
- ///
- /// See also:
- /// - [`BoolishValueParser`] for different human readable bool representations
- /// - [`FalseyValueParser`] for assuming non-false is true
- ///
- /// # Example
- ///
- /// ```rust
- /// let mut cmd = clap::Command::new("raw")
- /// .arg(
- /// clap::Arg::new("download")
- /// .value_parser(clap::value_parser!(bool))
- /// .required(true)
- /// );
- ///
- /// let m = cmd.try_get_matches_from_mut(["cmd", "true"]).unwrap();
- /// let port: bool = *m.get_one("download")
- /// .expect("required");
- /// assert_eq!(port, true);
- ///
- /// assert!(cmd.try_get_matches_from_mut(["cmd", "forever"]).is_err());
- /// ```
- pub const fn bool() -> Self {
- Self(ValueParserInner::Bool)
- }
-
- /// [`String`] parser for argument values
- ///
- /// See also:
- /// - [`NonEmptyStringValueParser`]
- ///
- /// # Example
- ///
- /// ```rust
- /// let mut cmd = clap::Command::new("raw")
- /// .arg(
- /// clap::Arg::new("port")
- /// .value_parser(clap::value_parser!(String))
- /// .required(true)
- /// );
- ///
- /// let m = cmd.try_get_matches_from_mut(["cmd", "80"]).unwrap();
- /// let port: &String = m.get_one("port")
- /// .expect("required");
- /// assert_eq!(port, "80");
- /// ```
- pub const fn string() -> Self {
- Self(ValueParserInner::String)
- }
-
- /// [`OsString`][std::ffi::OsString] parser for argument values
- ///
- /// # Example
- ///
- #[cfg_attr(not(unix), doc = " ```ignore")]
- #[cfg_attr(unix, doc = " ```rust")]
- /// # use clap::{Command, Arg, builder::ValueParser};
- /// use std::ffi::OsString;
- /// use std::os::unix::ffi::{OsStrExt,OsStringExt};
- /// let r = Command::new("myprog")
- /// .arg(
- /// Arg::new("arg")
- /// .required(true)
- /// .value_parser(ValueParser::os_string())
- /// )
- /// .try_get_matches_from(vec![
- /// OsString::from("myprog"),
- /// OsString::from_vec(vec![0xe9])
- /// ]);
- ///
- /// assert!(r.is_ok());
- /// let m = r.unwrap();
- /// let arg: &OsString = m.get_one("arg")
- /// .expect("required");
- /// assert_eq!(arg.as_bytes(), &[0xe9]);
- /// ```
- pub const fn os_string() -> Self {
- Self(ValueParserInner::OsString)
- }
-
- /// [`PathBuf`][std::path::PathBuf] parser for argument values
- ///
- /// # Example
- ///
- /// ```rust
- /// # use std::path::PathBuf;
- /// # use std::path::Path;
- /// let mut cmd = clap::Command::new("raw")
- /// .arg(
- /// clap::Arg::new("output")
- /// .value_parser(clap::value_parser!(PathBuf))
- /// .required(true)
- /// );
- ///
- /// let m = cmd.try_get_matches_from_mut(["cmd", "hello.txt"]).unwrap();
- /// let port: &PathBuf = m.get_one("output")
- /// .expect("required");
- /// assert_eq!(port, Path::new("hello.txt"));
- ///
- /// assert!(cmd.try_get_matches_from_mut(["cmd", ""]).is_err());
- /// ```
- pub const fn path_buf() -> Self {
- Self(ValueParserInner::PathBuf)
- }
-}
-
-impl ValueParser {
- /// Parse into a `AnyValue`
- ///
- /// When `arg` is `None`, an external subcommand value is being parsed.
- pub(crate) fn parse_ref(
- &self,
- cmd: &crate::Command,
- arg: Option<&crate::Arg>,
- value: &std::ffi::OsStr,
- ) -> Result<AnyValue, crate::Error> {
- self.any_value_parser().parse_ref(cmd, arg, value)
- }
-
- /// Describes the content of `AnyValue`
- pub fn type_id(&self) -> AnyValueId {
- self.any_value_parser().type_id()
- }
-
- /// Reflect on enumerated value properties
- ///
- /// Error checking should not be done with this; it is mostly targeted at user-facing
- /// applications like errors and completion.
- pub fn possible_values(
- &self,
- ) -> Option<Box<dyn Iterator<Item = crate::PossibleValue<'static>> + '_>> {
- self.any_value_parser().possible_values()
- }
-
- fn any_value_parser(&self) -> &dyn AnyValueParser {
- match &self.0 {
- ValueParserInner::Bool => &BoolValueParser {},
- ValueParserInner::String => &StringValueParser {},
- ValueParserInner::OsString => &OsStringValueParser {},
- ValueParserInner::PathBuf => &PathBufValueParser {},
- ValueParserInner::Other(o) => o.as_ref(),
- }
- }
-}
-
-/// Convert a [`TypedValueParser`] to [`ValueParser`]
-///
-/// # Example
-///
-/// ```rust
-/// let mut cmd = clap::Command::new("raw")
-/// .arg(
-/// clap::Arg::new("hostname")
-/// .long("hostname")
-/// .value_parser(clap::builder::NonEmptyStringValueParser::new())
-/// .takes_value(true)
-/// .required(true)
-/// );
-///
-/// let m = cmd.try_get_matches_from_mut(
-/// ["cmd", "--hostname", "rust-lang.org"]
-/// ).unwrap();
-///
-/// let hostname: &String = m.get_one("hostname")
-/// .expect("required");
-/// assert_eq!(hostname, "rust-lang.org");
-/// ```
-impl<P> From<P> for ValueParser
-where
- P: TypedValueParser + Send + Sync + 'static,
- P::Value: Send + Sync + Clone,
-{
- fn from(p: P) -> Self {
- Self::new(p)
- }
-}
-
-impl From<_AnonymousValueParser> for ValueParser {
- fn from(p: _AnonymousValueParser) -> Self {
- p.0
- }
-}
-
-/// Create an `i64` [`ValueParser`] from a `N..M` range
-///
-/// See [`RangedI64ValueParser`] for more control over the output type.
-///
-/// See also [`RangedU64ValueParser`]
-///
-/// # Examples
-///
-/// ```rust
-/// let mut cmd = clap::Command::new("raw")
-/// .arg(
-/// clap::Arg::new("port")
-/// .long("port")
-/// .value_parser(3000..4000)
-/// .takes_value(true)
-/// .required(true)
-/// );
-///
-/// let m = cmd.try_get_matches_from_mut(["cmd", "--port", "3001"]).unwrap();
-/// let port: i64 = *m.get_one("port")
-/// .expect("required");
-/// assert_eq!(port, 3001);
-/// ```
-impl From<std::ops::Range<i64>> for ValueParser {
- fn from(value: std::ops::Range<i64>) -> Self {
- let inner = RangedI64ValueParser::<i64>::new().range(value.start..value.end);
- Self::from(inner)
- }
-}
-
-/// Create an `i64` [`ValueParser`] from a `N..=M` range
-///
-/// See [`RangedI64ValueParser`] for more control over the output type.
-///
-/// See also [`RangedU64ValueParser`]
-///
-/// # Examples
-///
-/// ```rust
-/// let mut cmd = clap::Command::new("raw")
-/// .arg(
-/// clap::Arg::new("port")
-/// .long("port")
-/// .value_parser(3000..=4000)
-/// .takes_value(true)
-/// .required(true)
-/// );
-///
-/// let m = cmd.try_get_matches_from_mut(["cmd", "--port", "3001"]).unwrap();
-/// let port: i64 = *m.get_one("port")
-/// .expect("required");
-/// assert_eq!(port, 3001);
-/// ```
-impl From<std::ops::RangeInclusive<i64>> for ValueParser {
- fn from(value: std::ops::RangeInclusive<i64>) -> Self {
- let inner = RangedI64ValueParser::<i64>::new().range(value.start()..=value.end());
- Self::from(inner)
- }
-}
-
-/// Create an `i64` [`ValueParser`] from a `N..` range
-///
-/// See [`RangedI64ValueParser`] for more control over the output type.
-///
-/// See also [`RangedU64ValueParser`]
-///
-/// # Examples
-///
-/// ```rust
-/// let mut cmd = clap::Command::new("raw")
-/// .arg(
-/// clap::Arg::new("port")
-/// .long("port")
-/// .value_parser(3000..)
-/// .takes_value(true)
-/// .required(true)
-/// );
-///
-/// let m = cmd.try_get_matches_from_mut(["cmd", "--port", "3001"]).unwrap();
-/// let port: i64 = *m.get_one("port")
-/// .expect("required");
-/// assert_eq!(port, 3001);
-/// ```
-impl From<std::ops::RangeFrom<i64>> for ValueParser {
- fn from(value: std::ops::RangeFrom<i64>) -> Self {
- let inner = RangedI64ValueParser::<i64>::new().range(value.start..);
- Self::from(inner)
- }
-}
-
-/// Create an `i64` [`ValueParser`] from a `..M` range
-///
-/// See [`RangedI64ValueParser`] for more control over the output type.
-///
-/// See also [`RangedU64ValueParser`]
-///
-/// # Examples
-///
-/// ```rust
-/// let mut cmd = clap::Command::new("raw")
-/// .arg(
-/// clap::Arg::new("port")
-/// .long("port")
-/// .value_parser(..3000)
-/// .takes_value(true)
-/// .required(true)
-/// );
-///
-/// let m = cmd.try_get_matches_from_mut(["cmd", "--port", "80"]).unwrap();
-/// let port: i64 = *m.get_one("port")
-/// .expect("required");
-/// assert_eq!(port, 80);
-/// ```
-impl From<std::ops::RangeTo<i64>> for ValueParser {
- fn from(value: std::ops::RangeTo<i64>) -> Self {
- let inner = RangedI64ValueParser::<i64>::new().range(..value.end);
- Self::from(inner)
- }
-}
-
-/// Create an `i64` [`ValueParser`] from a `..=M` range
-///
-/// See [`RangedI64ValueParser`] for more control over the output type.
-///
-/// See also [`RangedU64ValueParser`]
-///
-/// # Examples
-///
-/// ```rust
-/// let mut cmd = clap::Command::new("raw")
-/// .arg(
-/// clap::Arg::new("port")
-/// .long("port")
-/// .value_parser(..=3000)
-/// .takes_value(true)
-/// .required(true)
-/// );
-///
-/// let m = cmd.try_get_matches_from_mut(["cmd", "--port", "80"]).unwrap();
-/// let port: i64 = *m.get_one("port")
-/// .expect("required");
-/// assert_eq!(port, 80);
-/// ```
-impl From<std::ops::RangeToInclusive<i64>> for ValueParser {
- fn from(value: std::ops::RangeToInclusive<i64>) -> Self {
- let inner = RangedI64ValueParser::<i64>::new().range(..=value.end);
- Self::from(inner)
- }
-}
-
-/// Create an `i64` [`ValueParser`] from a `..` range
-///
-/// See [`RangedI64ValueParser`] for more control over the output type.
-///
-/// See also [`RangedU64ValueParser`]
-///
-/// # Examples
-///
-/// ```rust
-/// let mut cmd = clap::Command::new("raw")
-/// .arg(
-/// clap::Arg::new("port")
-/// .long("port")
-/// .value_parser(..)
-/// .takes_value(true)
-/// .required(true)
-/// );
-///
-/// let m = cmd.try_get_matches_from_mut(["cmd", "--port", "3001"]).unwrap();
-/// let port: i64 = *m.get_one("port")
-/// .expect("required");
-/// assert_eq!(port, 3001);
-/// ```
-impl From<std::ops::RangeFull> for ValueParser {
- fn from(value: std::ops::RangeFull) -> Self {
- let inner = RangedI64ValueParser::<i64>::new().range(value);
- Self::from(inner)
- }
-}
-
-/// Create a [`ValueParser`] with [`PossibleValuesParser`]
-///
-/// See [`PossibleValuesParser`] for more flexibility in creating the
-/// [`PossibleValue`][crate::PossibleValue]s.
-///
-/// # Examples
-///
-/// ```rust
-/// let mut cmd = clap::Command::new("raw")
-/// .arg(
-/// clap::Arg::new("color")
-/// .long("color")
-/// .value_parser(["always", "auto", "never"])
-/// .default_value("auto")
-/// );
-///
-/// let m = cmd.try_get_matches_from_mut(
-/// ["cmd", "--color", "never"]
-/// ).unwrap();
-///
-/// let color: &String = m.get_one("color")
-/// .expect("default");
-/// assert_eq!(color, "never");
-/// ```
-impl<P, const C: usize> From<[P; C]> for ValueParser
-where
- P: Into<super::PossibleValue<'static>>,
-{
- fn from(values: [P; C]) -> Self {
- let inner = PossibleValuesParser::from(values);
- Self::from(inner)
- }
-}
-
-impl std::fmt::Debug for ValueParser {
- fn fmt(&self, f: &mut std::fmt::Formatter) -> Result<(), std::fmt::Error> {
- match &self.0 {
- ValueParserInner::Bool => f.debug_struct("ValueParser::bool").finish(),
- ValueParserInner::String => f.debug_struct("ValueParser::string").finish(),
- ValueParserInner::OsString => f.debug_struct("ValueParser::os_string").finish(),
- ValueParserInner::PathBuf => f.debug_struct("ValueParser::path_buf").finish(),
- ValueParserInner::Other(o) => write!(f, "ValueParser::other({:?})", o.type_id()),
- }
- }
-}
-
-impl Clone for ValueParser {
- fn clone(&self) -> Self {
- Self(match &self.0 {
- ValueParserInner::Bool => ValueParserInner::Bool,
- ValueParserInner::String => ValueParserInner::String,
- ValueParserInner::OsString => ValueParserInner::OsString,
- ValueParserInner::PathBuf => ValueParserInner::PathBuf,
- ValueParserInner::Other(o) => ValueParserInner::Other(o.clone_any()),
- })
- }
-}
-
-/// A type-erased wrapper for [`TypedValueParser`].
-trait AnyValueParser: Send + Sync + 'static {
- fn parse_ref(
- &self,
- cmd: &crate::Command,
- arg: Option<&crate::Arg>,
- value: &std::ffi::OsStr,
- ) -> Result<AnyValue, crate::Error>;
-
- fn parse(
- &self,
- cmd: &crate::Command,
- arg: Option<&crate::Arg>,
- value: std::ffi::OsString,
- ) -> Result<AnyValue, crate::Error>;
-
- /// Describes the content of `AnyValue`
- fn type_id(&self) -> AnyValueId;
-
- fn possible_values(
- &self,
- ) -> Option<Box<dyn Iterator<Item = crate::PossibleValue<'static>> + '_>>;
-
- fn clone_any(&self) -> Box<dyn AnyValueParser>;
-}
-
-impl<T, P> AnyValueParser for P
-where
- T: std::any::Any + Clone + Send + Sync + 'static,
- P: TypedValueParser<Value = T>,
-{
- fn parse_ref(
- &self,
- cmd: &crate::Command,
- arg: Option<&crate::Arg>,
- value: &std::ffi::OsStr,
- ) -> Result<AnyValue, crate::Error> {
- let value = TypedValueParser::parse_ref(self, cmd, arg, value)?;
- Ok(AnyValue::new(value))
- }
-
- fn parse(
- &self,
- cmd: &crate::Command,
- arg: Option<&crate::Arg>,
- value: std::ffi::OsString,
- ) -> Result<AnyValue, crate::Error> {
- let value = TypedValueParser::parse(self, cmd, arg, value)?;
- Ok(AnyValue::new(value))
- }
-
- fn type_id(&self) -> AnyValueId {
- AnyValueId::of::<T>()
- }
-
- fn possible_values(
- &self,
- ) -> Option<Box<dyn Iterator<Item = crate::PossibleValue<'static>> + '_>> {
- P::possible_values(self)
- }
-
- fn clone_any(&self) -> Box<dyn AnyValueParser> {
- Box::new(self.clone())
- }
-}
-
-/// Parse/validate argument values
-pub trait TypedValueParser: Clone + Send + Sync + 'static {
- /// Argument's value type
- type Value;
-
- /// Parse the argument value
- ///
- /// When `arg` is `None`, an external subcommand value is being parsed.
- fn parse_ref(
- &self,
- cmd: &crate::Command,
- arg: Option<&crate::Arg>,
- value: &std::ffi::OsStr,
- ) -> Result<Self::Value, crate::Error>;
-
- /// Parse the argument value
- ///
- /// When `arg` is `None`, an external subcommand value is being parsed.
- fn parse(
- &self,
- cmd: &crate::Command,
- arg: Option<&crate::Arg>,
- value: std::ffi::OsString,
- ) -> Result<Self::Value, crate::Error> {
- self.parse_ref(cmd, arg, &value)
- }
-
- /// Reflect on enumerated value properties
- ///
- /// Error checking should not be done with this; it is mostly targeted at user-facing
- /// applications like errors and completion.
- fn possible_values(
- &self,
- ) -> Option<Box<dyn Iterator<Item = crate::PossibleValue<'static>> + '_>> {
- None
- }
-}
-
-impl<F, T, E> TypedValueParser for F
-where
- F: Fn(&str) -> Result<T, E> + Clone + Send + Sync + 'static,
- E: Into<Box<dyn std::error::Error + Send + Sync + 'static>>,
-{
- type Value = T;
-
- fn parse_ref(
- &self,
- cmd: &crate::Command,
- arg: Option<&crate::Arg>,
- value: &std::ffi::OsStr,
- ) -> Result<Self::Value, crate::Error> {
- let value = value.to_str().ok_or_else(|| {
- crate::Error::invalid_utf8(
- cmd,
- crate::output::Usage::new(cmd).create_usage_with_title(&[]),
- )
- })?;
- let value = (self)(value).map_err(|e| {
- let arg = arg
- .map(|a| a.to_string())
- .unwrap_or_else(|| "...".to_owned());
- crate::Error::value_validation(arg, value.to_owned(), e.into()).with_cmd(cmd)
- })?;
- Ok(value)
- }
-}
-
-/// Implementation for [`ValueParser::string`]
-///
-/// Useful for composing new [`TypedValueParser`]s
-#[derive(Copy, Clone, Debug)]
-#[non_exhaustive]
-pub struct StringValueParser {}
-
-impl StringValueParser {
- /// Implementation for [`ValueParser::string`]
- pub fn new() -> Self {
- Self {}
- }
-}
-
-impl TypedValueParser for StringValueParser {
- type Value = String;
-
- fn parse_ref(
- &self,
- cmd: &crate::Command,
- arg: Option<&crate::Arg>,
- value: &std::ffi::OsStr,
- ) -> Result<Self::Value, crate::Error> {
- TypedValueParser::parse(self, cmd, arg, value.to_owned())
- }
-
- fn parse(
- &self,
- cmd: &crate::Command,
- _arg: Option<&crate::Arg>,
- value: std::ffi::OsString,
- ) -> Result<Self::Value, crate::Error> {
- let value = value.into_string().map_err(|_| {
- crate::Error::invalid_utf8(
- cmd,
- crate::output::Usage::new(cmd).create_usage_with_title(&[]),
- )
- })?;
- Ok(value)
- }
-}
-
-impl Default for StringValueParser {
- fn default() -> Self {
- Self::new()
- }
-}
-
-/// Implementation for [`ValueParser::os_string`]
-///
-/// Useful for composing new [`TypedValueParser`]s
-#[derive(Copy, Clone, Debug)]
-#[non_exhaustive]
-pub struct OsStringValueParser {}
-
-impl OsStringValueParser {
- /// Implementation for [`ValueParser::os_string`]
- pub fn new() -> Self {
- Self {}
- }
-}
-
-impl TypedValueParser for OsStringValueParser {
- type Value = std::ffi::OsString;
-
- fn parse_ref(
- &self,
- cmd: &crate::Command,
- arg: Option<&crate::Arg>,
- value: &std::ffi::OsStr,
- ) -> Result<Self::Value, crate::Error> {
- TypedValueParser::parse(self, cmd, arg, value.to_owned())
- }
-
- fn parse(
- &self,
- _cmd: &crate::Command,
- _arg: Option<&crate::Arg>,
- value: std::ffi::OsString,
- ) -> Result<Self::Value, crate::Error> {
- Ok(value)
- }
-}
-
-impl Default for OsStringValueParser {
- fn default() -> Self {
- Self::new()
- }
-}
-
-/// Implementation for [`ValueParser::path_buf`]
-///
-/// Useful for composing new [`TypedValueParser`]s
-#[derive(Copy, Clone, Debug)]
-#[non_exhaustive]
-pub struct PathBufValueParser {}
-
-impl PathBufValueParser {
- /// Implementation for [`ValueParser::path_buf`]
- pub fn new() -> Self {
- Self {}
- }
-}
-
-impl TypedValueParser for PathBufValueParser {
- type Value = std::path::PathBuf;
-
- fn parse_ref(
- &self,
- cmd: &crate::Command,
- arg: Option<&crate::Arg>,
- value: &std::ffi::OsStr,
- ) -> Result<Self::Value, crate::Error> {
- TypedValueParser::parse(self, cmd, arg, value.to_owned())
- }
-
- fn parse(
- &self,
- cmd: &crate::Command,
- arg: Option<&crate::Arg>,
- value: std::ffi::OsString,
- ) -> Result<Self::Value, crate::Error> {
- if value.is_empty() {
- return Err(crate::Error::empty_value(
- cmd,
- &[],
- arg.map(ToString::to_string)
- .unwrap_or_else(|| "...".to_owned()),
- ));
- }
- Ok(Self::Value::from(value))
- }
-}
-
-impl Default for PathBufValueParser {
- fn default() -> Self {
- Self::new()
- }
-}
-
-/// Parse an [`ValueEnum`][crate::ValueEnum] value.
-///
-/// See also:
-/// - [`PossibleValuesParser`]
-///
-/// # Example
-///
-/// ```rust
-/// # use std::ffi::OsStr;
-/// # use clap::builder::TypedValueParser;
-/// # let cmd = clap::Command::new("test");
-/// # let arg = None;
-///
-/// #[derive(Copy, Clone, Debug, PartialEq, Eq)]
-/// enum ColorChoice {
-/// Always,
-/// Auto,
-/// Never,
-/// }
-///
-/// impl clap::ValueEnum for ColorChoice {
-/// fn value_variants<'a>() -> &'a [Self] {
-/// &[Self::Always, Self::Auto, Self::Never]
-/// }
-///
-/// fn to_possible_value<'a>(&self) -> Option<clap::PossibleValue<'a>> {
-/// match self {
-/// Self::Always => Some(clap::PossibleValue::new("always")),
-/// Self::Auto => Some(clap::PossibleValue::new("auto")),
-/// Self::Never => Some(clap::PossibleValue::new("never")),
-/// }
-/// }
-/// }
-///
-/// // Usage
-/// let mut cmd = clap::Command::new("raw")
-/// .arg(
-/// clap::Arg::new("color")
-/// .value_parser(clap::builder::EnumValueParser::<ColorChoice>::new())
-/// .required(true)
-/// );
-///
-/// let m = cmd.try_get_matches_from_mut(["cmd", "always"]).unwrap();
-/// let port: ColorChoice = *m.get_one("color")
-/// .expect("required");
-/// assert_eq!(port, ColorChoice::Always);
-///
-/// // Semantics
-/// let value_parser = clap::builder::EnumValueParser::<ColorChoice>::new();
-/// // or
-/// let value_parser = clap::value_parser!(ColorChoice);
-/// assert!(value_parser.parse_ref(&cmd, arg, OsStr::new("random")).is_err());
-/// assert!(value_parser.parse_ref(&cmd, arg, OsStr::new("")).is_err());
-/// assert_eq!(value_parser.parse_ref(&cmd, arg, OsStr::new("always")).unwrap(), ColorChoice::Always);
-/// assert_eq!(value_parser.parse_ref(&cmd, arg, OsStr::new("auto")).unwrap(), ColorChoice::Auto);
-/// assert_eq!(value_parser.parse_ref(&cmd, arg, OsStr::new("never")).unwrap(), ColorChoice::Never);
-/// ```
-#[derive(Clone, Debug)]
-pub struct EnumValueParser<E: crate::ValueEnum + Clone + Send + Sync + 'static>(
- std::marker::PhantomData<E>,
-);
-
-impl<E: crate::ValueEnum + Clone + Send + Sync + 'static> EnumValueParser<E> {
- /// Parse an [`ValueEnum`][crate::ValueEnum]
- pub fn new() -> Self {
- let phantom: std::marker::PhantomData<E> = Default::default();
- Self(phantom)
- }
-}
-
-impl<E: crate::ValueEnum + Clone + Send + Sync + 'static> TypedValueParser for EnumValueParser<E> {
- type Value = E;
-
- fn parse_ref(
- &self,
- cmd: &crate::Command,
- arg: Option<&crate::Arg>,
- value: &std::ffi::OsStr,
- ) -> Result<Self::Value, crate::Error> {
- let ignore_case = arg.map(|a| a.is_ignore_case_set()).unwrap_or(false);
- let possible_vals = || {
- E::value_variants()
- .iter()
- .filter_map(|v| v.to_possible_value())
- .filter(|v| !v.is_hide_set())
- .map(|v| v.get_name())
- .collect::<Vec<_>>()
- };
-
- let value = value.to_str().ok_or_else(|| {
- crate::Error::invalid_value(
- cmd,
- value.to_string_lossy().into_owned(),
- &possible_vals(),
- arg.map(ToString::to_string)
- .unwrap_or_else(|| "...".to_owned()),
- )
- })?;
- let value = E::value_variants()
- .iter()
- .find(|v| {
- v.to_possible_value()
- .expect("ValueEnum::value_variants contains only values with a corresponding ValueEnum::to_possible_value")
- .matches(value, ignore_case)
- })
- .ok_or_else(|| {
- crate::Error::invalid_value(
- cmd,
- value.to_owned(),
- &possible_vals(),
- arg.map(ToString::to_string)
- .unwrap_or_else(|| "...".to_owned()),
- )
- })?
- .clone();
- Ok(value)
- }
-
- fn possible_values(
- &self,
- ) -> Option<Box<dyn Iterator<Item = crate::PossibleValue<'static>> + '_>> {
- Some(Box::new(
- E::value_variants()
- .iter()
- .filter_map(|v| v.to_possible_value()),
- ))
- }
-}
-
-impl<E: crate::ValueEnum + Clone + Send + Sync + 'static> Default for EnumValueParser<E> {
- fn default() -> Self {
- Self::new()
- }
-}
-
-/// Verify the value is from an enumerated set of [`PossibleValue`][crate::PossibleValue].
-///
-/// See also:
-/// - [`EnumValueParser`]
-///
-/// # Example
-///
-/// Usage:
-/// ```rust
-/// let mut cmd = clap::Command::new("raw")
-/// .arg(
-/// clap::Arg::new("color")
-/// .value_parser(clap::builder::PossibleValuesParser::new(["always", "auto", "never"]))
-/// .required(true)
-/// );
-///
-/// let m = cmd.try_get_matches_from_mut(["cmd", "always"]).unwrap();
-/// let port: &String = m.get_one("color")
-/// .expect("required");
-/// assert_eq!(port, "always");
-/// ```
-///
-/// Semantics:
-/// ```rust
-/// # use std::ffi::OsStr;
-/// # use clap::builder::TypedValueParser;
-/// # let cmd = clap::Command::new("test");
-/// # let arg = None;
-/// let value_parser = clap::builder::PossibleValuesParser::new(["always", "auto", "never"]);
-/// assert!(value_parser.parse_ref(&cmd, arg, OsStr::new("random")).is_err());
-/// assert!(value_parser.parse_ref(&cmd, arg, OsStr::new("")).is_err());
-/// assert_eq!(value_parser.parse_ref(&cmd, arg, OsStr::new("always")).unwrap(), "always");
-/// assert_eq!(value_parser.parse_ref(&cmd, arg, OsStr::new("auto")).unwrap(), "auto");
-/// assert_eq!(value_parser.parse_ref(&cmd, arg, OsStr::new("never")).unwrap(), "never");
-/// ```
-#[derive(Clone, Debug)]
-pub struct PossibleValuesParser(Vec<super::PossibleValue<'static>>);
-
-impl PossibleValuesParser {
- /// Verify the value is from an enumerated set pf [`PossibleValue`][crate::PossibleValue].
- pub fn new(values: impl Into<PossibleValuesParser>) -> Self {
- values.into()
- }
-}
-
-impl TypedValueParser for PossibleValuesParser {
- type Value = String;
-
- fn parse_ref(
- &self,
- cmd: &crate::Command,
- arg: Option<&crate::Arg>,
- value: &std::ffi::OsStr,
- ) -> Result<Self::Value, crate::Error> {
- TypedValueParser::parse(self, cmd, arg, value.to_owned())
- }
-
- fn parse(
- &self,
- cmd: &crate::Command,
- arg: Option<&crate::Arg>,
- value: std::ffi::OsString,
- ) -> Result<String, crate::Error> {
- let value = value.into_string().map_err(|_| {
- crate::Error::invalid_utf8(
- cmd,
- crate::output::Usage::new(cmd).create_usage_with_title(&[]),
- )
- })?;
-
- let ignore_case = arg.map(|a| a.is_ignore_case_set()).unwrap_or(false);
- if self.0.iter().any(|v| v.matches(&value, ignore_case)) {
- Ok(value)
- } else {
- let possible_vals = self
- .0
- .iter()
- .filter(|v| !v.is_hide_set())
- .map(crate::builder::PossibleValue::get_name)
- .collect::<Vec<_>>();
-
- Err(crate::Error::invalid_value(
- cmd,
- value,
- &possible_vals,
- arg.map(ToString::to_string)
- .unwrap_or_else(|| "...".to_owned()),
- ))
- }
- }
-
- fn possible_values(
- &self,
- ) -> Option<Box<dyn Iterator<Item = crate::PossibleValue<'static>> + '_>> {
- Some(Box::new(self.0.iter().cloned()))
- }
-}
-
-impl<I, T> From<I> for PossibleValuesParser
-where
- I: IntoIterator<Item = T>,
- T: Into<super::PossibleValue<'static>>,
-{
- fn from(values: I) -> Self {
- Self(values.into_iter().map(|t| t.into()).collect())
- }
-}
-
-/// Parse number that fall within a range of values
-///
-/// # Example
-///
-/// Usage:
-/// ```rust
-/// let mut cmd = clap::Command::new("raw")
-/// .arg(
-/// clap::Arg::new("port")
-/// .long("port")
-/// .value_parser(clap::value_parser!(u16).range(3000..))
-/// .takes_value(true)
-/// .required(true)
-/// );
-///
-/// let m = cmd.try_get_matches_from_mut(["cmd", "--port", "3001"]).unwrap();
-/// let port: u16 = *m.get_one("port")
-/// .expect("required");
-/// assert_eq!(port, 3001);
-/// ```
-///
-/// Semantics:
-/// ```rust
-/// # use std::ffi::OsStr;
-/// # use clap::builder::TypedValueParser;
-/// # let cmd = clap::Command::new("test");
-/// # let arg = None;
-/// let value_parser = clap::builder::RangedI64ValueParser::<i32>::new().range(-1..200);
-/// assert!(value_parser.parse_ref(&cmd, arg, OsStr::new("random")).is_err());
-/// assert!(value_parser.parse_ref(&cmd, arg, OsStr::new("")).is_err());
-/// assert!(value_parser.parse_ref(&cmd, arg, OsStr::new("-200")).is_err());
-/// assert!(value_parser.parse_ref(&cmd, arg, OsStr::new("300")).is_err());
-/// assert_eq!(value_parser.parse_ref(&cmd, arg, OsStr::new("-1")).unwrap(), -1);
-/// assert_eq!(value_parser.parse_ref(&cmd, arg, OsStr::new("0")).unwrap(), 0);
-/// assert_eq!(value_parser.parse_ref(&cmd, arg, OsStr::new("50")).unwrap(), 50);
-/// ```
-#[derive(Copy, Clone, Debug)]
-pub struct RangedI64ValueParser<T: std::convert::TryFrom<i64> + Clone + Send + Sync = i64> {
- bounds: (std::ops::Bound<i64>, std::ops::Bound<i64>),
- target: std::marker::PhantomData<T>,
-}
-
-impl<T: std::convert::TryFrom<i64> + Clone + Send + Sync> RangedI64ValueParser<T> {
- /// Select full range of `i64`
- pub fn new() -> Self {
- Self::from(..)
- }
-
- /// Narrow the supported range
- pub fn range<B: RangeBounds<i64>>(mut self, range: B) -> Self {
- // Consideration: when the user does `value_parser!(u8).range()`
- // - Avoid programming mistakes by accidentally expanding the range
- // - Make it convenient to limit the range like with `..10`
- let start = match range.start_bound() {
- l @ std::ops::Bound::Included(i) => {
- debug_assert!(
- self.bounds.contains(i),
- "{} must be in {:?}",
- i,
- self.bounds
- );
- l.cloned()
- }
- l @ std::ops::Bound::Excluded(i) => {
- debug_assert!(
- self.bounds.contains(&i.saturating_add(1)),
- "{} must be in {:?}",
- i,
- self.bounds
- );
- l.cloned()
- }
- std::ops::Bound::Unbounded => self.bounds.start_bound().cloned(),
- };
- let end = match range.end_bound() {
- l @ std::ops::Bound::Included(i) => {
- debug_assert!(
- self.bounds.contains(i),
- "{} must be in {:?}",
- i,
- self.bounds
- );
- l.cloned()
- }
- l @ std::ops::Bound::Excluded(i) => {
- debug_assert!(
- self.bounds.contains(&i.saturating_sub(1)),
- "{} must be in {:?}",
- i,
- self.bounds
- );
- l.cloned()
- }
- std::ops::Bound::Unbounded => self.bounds.end_bound().cloned(),
- };
- self.bounds = (start, end);
- self
- }
-
- fn format_bounds(&self) -> String {
- let mut result = match self.bounds.0 {
- std::ops::Bound::Included(i) => i.to_string(),
- std::ops::Bound::Excluded(i) => i.saturating_add(1).to_string(),
- std::ops::Bound::Unbounded => i64::MIN.to_string(),
- };
- result.push_str("..");
- match self.bounds.1 {
- std::ops::Bound::Included(i) => {
- result.push('=');
- result.push_str(&i.to_string());
- }
- std::ops::Bound::Excluded(i) => {
- result.push_str(&i.to_string());
- }
- std::ops::Bound::Unbounded => {
- result.push_str(&i64::MAX.to_string());
- }
- }
- result
- }
-}
-
-impl<T: std::convert::TryFrom<i64> + Clone + Send + Sync + 'static> TypedValueParser
- for RangedI64ValueParser<T>
-where
- <T as std::convert::TryFrom<i64>>::Error: Send + Sync + 'static + std::error::Error + ToString,
-{
- type Value = T;
-
- fn parse_ref(
- &self,
- cmd: &crate::Command,
- arg: Option<&crate::Arg>,
- raw_value: &std::ffi::OsStr,
- ) -> Result<Self::Value, crate::Error> {
- let value = raw_value.to_str().ok_or_else(|| {
- crate::Error::invalid_utf8(
- cmd,
- crate::output::Usage::new(cmd).create_usage_with_title(&[]),
- )
- })?;
- let value = value.parse::<i64>().map_err(|err| {
- let arg = arg
- .map(|a| a.to_string())
- .unwrap_or_else(|| "...".to_owned());
- crate::Error::value_validation(
- arg,
- raw_value.to_string_lossy().into_owned(),
- err.into(),
- )
- .with_cmd(cmd)
- })?;
- if !self.bounds.contains(&value) {
- let arg = arg
- .map(|a| a.to_string())
- .unwrap_or_else(|| "...".to_owned());
- return Err(crate::Error::value_validation(
- arg,
- raw_value.to_string_lossy().into_owned(),
- format!("{} is not in {}", value, self.format_bounds()).into(),
- )
- .with_cmd(cmd));
- }
-
- let value: Result<Self::Value, _> = value.try_into();
- let value = value.map_err(|err| {
- let arg = arg
- .map(|a| a.to_string())
- .unwrap_or_else(|| "...".to_owned());
- crate::Error::value_validation(
- arg,
- raw_value.to_string_lossy().into_owned(),
- err.into(),
- )
- .with_cmd(cmd)
- })?;
-
- Ok(value)
- }
-}
-
-impl<T: std::convert::TryFrom<i64> + Clone + Send + Sync, B: RangeBounds<i64>> From<B>
- for RangedI64ValueParser<T>
-{
- fn from(range: B) -> Self {
- Self {
- bounds: (range.start_bound().cloned(), range.end_bound().cloned()),
- target: Default::default(),
- }
- }
-}
-
-impl<T: std::convert::TryFrom<i64> + Clone + Send + Sync> Default for RangedI64ValueParser<T> {
- fn default() -> Self {
- Self::new()
- }
-}
-
-/// Parse number that fall within a range of values
-///
-/// # Example
-///
-/// Usage:
-/// ```rust
-/// let mut cmd = clap::Command::new("raw")
-/// .arg(
-/// clap::Arg::new("port")
-/// .long("port")
-/// .value_parser(clap::value_parser!(u64).range(3000..))
-/// .takes_value(true)
-/// .required(true)
-/// );
-///
-/// let m = cmd.try_get_matches_from_mut(["cmd", "--port", "3001"]).unwrap();
-/// let port: u64 = *m.get_one("port")
-/// .expect("required");
-/// assert_eq!(port, 3001);
-/// ```
-///
-/// Semantics:
-/// ```rust
-/// # use std::ffi::OsStr;
-/// # use clap::builder::TypedValueParser;
-/// # let cmd = clap::Command::new("test");
-/// # let arg = None;
-/// let value_parser = clap::builder::RangedU64ValueParser::<u32>::new().range(0..200);
-/// assert!(value_parser.parse_ref(&cmd, arg, OsStr::new("random")).is_err());
-/// assert!(value_parser.parse_ref(&cmd, arg, OsStr::new("")).is_err());
-/// assert!(value_parser.parse_ref(&cmd, arg, OsStr::new("-200")).is_err());
-/// assert!(value_parser.parse_ref(&cmd, arg, OsStr::new("300")).is_err());
-/// assert!(value_parser.parse_ref(&cmd, arg, OsStr::new("-1")).is_err());
-/// assert_eq!(value_parser.parse_ref(&cmd, arg, OsStr::new("0")).unwrap(), 0);
-/// assert_eq!(value_parser.parse_ref(&cmd, arg, OsStr::new("50")).unwrap(), 50);
-/// ```
-#[derive(Copy, Clone, Debug)]
-pub struct RangedU64ValueParser<T: std::convert::TryFrom<u64> = u64> {
- bounds: (std::ops::Bound<u64>, std::ops::Bound<u64>),
- target: std::marker::PhantomData<T>,
-}
-
-impl<T: std::convert::TryFrom<u64>> RangedU64ValueParser<T> {
- /// Select full range of `u64`
- pub fn new() -> Self {
- Self::from(..)
- }
-
- /// Narrow the supported range
- pub fn range<B: RangeBounds<u64>>(mut self, range: B) -> Self {
- // Consideration: when the user does `value_parser!(u8).range()`
- // - Avoid programming mistakes by accidentally expanding the range
- // - Make it convenient to limit the range like with `..10`
- let start = match range.start_bound() {
- l @ std::ops::Bound::Included(i) => {
- debug_assert!(
- self.bounds.contains(i),
- "{} must be in {:?}",
- i,
- self.bounds
- );
- l.cloned()
- }
- l @ std::ops::Bound::Excluded(i) => {
- debug_assert!(
- self.bounds.contains(&i.saturating_add(1)),
- "{} must be in {:?}",
- i,
- self.bounds
- );
- l.cloned()
- }
- std::ops::Bound::Unbounded => self.bounds.start_bound().cloned(),
- };
- let end = match range.end_bound() {
- l @ std::ops::Bound::Included(i) => {
- debug_assert!(
- self.bounds.contains(i),
- "{} must be in {:?}",
- i,
- self.bounds
- );
- l.cloned()
- }
- l @ std::ops::Bound::Excluded(i) => {
- debug_assert!(
- self.bounds.contains(&i.saturating_sub(1)),
- "{} must be in {:?}",
- i,
- self.bounds
- );
- l.cloned()
- }
- std::ops::Bound::Unbounded => self.bounds.end_bound().cloned(),
- };
- self.bounds = (start, end);
- self
- }
-
- fn format_bounds(&self) -> String {
- let mut result = match self.bounds.0 {
- std::ops::Bound::Included(i) => i.to_string(),
- std::ops::Bound::Excluded(i) => i.saturating_add(1).to_string(),
- std::ops::Bound::Unbounded => u64::MIN.to_string(),
- };
- result.push_str("..");
- match self.bounds.1 {
- std::ops::Bound::Included(i) => {
- result.push('=');
- result.push_str(&i.to_string());
- }
- std::ops::Bound::Excluded(i) => {
- result.push_str(&i.to_string());
- }
- std::ops::Bound::Unbounded => {
- result.push_str(&u64::MAX.to_string());
- }
- }
- result
- }
-}
-
-impl<T: std::convert::TryFrom<u64> + Clone + Send + Sync + 'static> TypedValueParser
- for RangedU64ValueParser<T>
-where
- <T as std::convert::TryFrom<u64>>::Error: Send + Sync + 'static + std::error::Error + ToString,
-{
- type Value = T;
-
- fn parse_ref(
- &self,
- cmd: &crate::Command,
- arg: Option<&crate::Arg>,
- raw_value: &std::ffi::OsStr,
- ) -> Result<Self::Value, crate::Error> {
- let value = raw_value.to_str().ok_or_else(|| {
- crate::Error::invalid_utf8(
- cmd,
- crate::output::Usage::new(cmd).create_usage_with_title(&[]),
- )
- })?;
- let value = value.parse::<u64>().map_err(|err| {
- let arg = arg
- .map(|a| a.to_string())
- .unwrap_or_else(|| "...".to_owned());
- crate::Error::value_validation(
- arg,
- raw_value.to_string_lossy().into_owned(),
- err.into(),
- )
- .with_cmd(cmd)
- })?;
- if !self.bounds.contains(&value) {
- let arg = arg
- .map(|a| a.to_string())
- .unwrap_or_else(|| "...".to_owned());
- return Err(crate::Error::value_validation(
- arg,
- raw_value.to_string_lossy().into_owned(),
- format!("{} is not in {}", value, self.format_bounds()).into(),
- )
- .with_cmd(cmd));
- }
-
- let value: Result<Self::Value, _> = value.try_into();
- let value = value.map_err(|err| {
- let arg = arg
- .map(|a| a.to_string())
- .unwrap_or_else(|| "...".to_owned());
- crate::Error::value_validation(
- arg,
- raw_value.to_string_lossy().into_owned(),
- err.into(),
- )
- .with_cmd(cmd)
- })?;
-
- Ok(value)
- }
-}
-
-impl<T: std::convert::TryFrom<u64>, B: RangeBounds<u64>> From<B> for RangedU64ValueParser<T> {
- fn from(range: B) -> Self {
- Self {
- bounds: (range.start_bound().cloned(), range.end_bound().cloned()),
- target: Default::default(),
- }
- }
-}
-
-impl<T: std::convert::TryFrom<u64>> Default for RangedU64ValueParser<T> {
- fn default() -> Self {
- Self::new()
- }
-}
-
-/// Implementation for [`ValueParser::bool`]
-///
-/// Useful for composing new [`TypedValueParser`]s
-#[derive(Copy, Clone, Debug)]
-#[non_exhaustive]
-pub struct BoolValueParser {}
-
-impl BoolValueParser {
- /// Implementation for [`ValueParser::bool`]
- pub fn new() -> Self {
- Self {}
- }
-
- fn possible_values() -> impl Iterator<Item = crate::PossibleValue<'static>> {
- ["true", "false"]
- .iter()
- .copied()
- .map(crate::PossibleValue::new)
- }
-}
-
-impl TypedValueParser for BoolValueParser {
- type Value = bool;
-
- fn parse_ref(
- &self,
- cmd: &crate::Command,
- arg: Option<&crate::Arg>,
- value: &std::ffi::OsStr,
- ) -> Result<Self::Value, crate::Error> {
- let value = if value == std::ffi::OsStr::new("true") {
- true
- } else if value == std::ffi::OsStr::new("false") {
- false
- } else {
- // Intentionally showing hidden as we hide all of them
- let possible_vals = Self::possible_values()
- .map(|v| v.get_name())
- .collect::<Vec<_>>();
-
- return Err(crate::Error::invalid_value(
- cmd,
- value.to_string_lossy().into_owned(),
- &possible_vals,
- arg.map(ToString::to_string)
- .unwrap_or_else(|| "...".to_owned()),
- ));
- };
- Ok(value)
- }
-
- fn possible_values(
- &self,
- ) -> Option<Box<dyn Iterator<Item = crate::PossibleValue<'static>> + '_>> {
- Some(Box::new(Self::possible_values()))
- }
-}
-
-impl Default for BoolValueParser {
- fn default() -> Self {
- Self::new()
- }
-}
-
-/// Parse false-like string values, everything else is `true`
-///
-/// See also:
-/// - [`ValueParser::bool`] for assuming non-false is true
-/// - [`BoolishValueParser`] for different human readable bool representations
-///
-/// # Example
-///
-/// Usage:
-/// ```rust
-/// let mut cmd = clap::Command::new("raw")
-/// .arg(
-/// clap::Arg::new("append")
-/// .value_parser(clap::builder::FalseyValueParser::new())
-/// .required(true)
-/// );
-///
-/// let m = cmd.try_get_matches_from_mut(["cmd", "true"]).unwrap();
-/// let port: bool = *m.get_one("append")
-/// .expect("required");
-/// assert_eq!(port, true);
-/// ```
-///
-/// Semantics:
-/// ```rust
-/// # use std::ffi::OsStr;
-/// # use clap::builder::TypedValueParser;
-/// # let cmd = clap::Command::new("test");
-/// # let arg = None;
-/// let value_parser = clap::builder::FalseyValueParser::new();
-/// assert_eq!(value_parser.parse_ref(&cmd, arg, OsStr::new("random")).unwrap(), true);
-/// assert_eq!(value_parser.parse_ref(&cmd, arg, OsStr::new("100")).unwrap(), true);
-/// assert_eq!(value_parser.parse_ref(&cmd, arg, OsStr::new("")).unwrap(), false);
-/// assert_eq!(value_parser.parse_ref(&cmd, arg, OsStr::new("false")).unwrap(), false);
-/// assert_eq!(value_parser.parse_ref(&cmd, arg, OsStr::new("No")).unwrap(), false);
-/// assert_eq!(value_parser.parse_ref(&cmd, arg, OsStr::new("oFF")).unwrap(), false);
-/// assert_eq!(value_parser.parse_ref(&cmd, arg, OsStr::new("0")).unwrap(), false);
-/// ```
-#[derive(Copy, Clone, Debug)]
-#[non_exhaustive]
-pub struct FalseyValueParser {}
-
-impl FalseyValueParser {
- /// Parse false-like string values, everything else is `true`
- pub fn new() -> Self {
- Self {}
- }
-
- fn possible_values() -> impl Iterator<Item = crate::PossibleValue<'static>> {
- crate::util::TRUE_LITERALS
- .iter()
- .chain(crate::util::FALSE_LITERALS.iter())
- .copied()
- .map(|l| crate::PossibleValue::new(l).hide(l != "true" && l != "false"))
- }
-}
-
-impl TypedValueParser for FalseyValueParser {
- type Value = bool;
-
- fn parse_ref(
- &self,
- cmd: &crate::Command,
- _arg: Option<&crate::Arg>,
- value: &std::ffi::OsStr,
- ) -> Result<Self::Value, crate::Error> {
- let value = value.to_str().ok_or_else(|| {
- crate::Error::invalid_utf8(
- cmd,
- crate::output::Usage::new(cmd).create_usage_with_title(&[]),
- )
- })?;
- let value = if value.is_empty() {
- false
- } else {
- crate::util::str_to_bool(value).unwrap_or(true)
- };
- Ok(value)
- }
-
- fn possible_values(
- &self,
- ) -> Option<Box<dyn Iterator<Item = crate::PossibleValue<'static>> + '_>> {
- Some(Box::new(Self::possible_values()))
- }
-}
-
-impl Default for FalseyValueParser {
- fn default() -> Self {
- Self::new()
- }
-}
-
-/// Parse bool-like string values, everything else is `true`
-///
-/// See also:
-/// - [`ValueParser::bool`] for different human readable bool representations
-/// - [`FalseyValueParser`] for assuming non-false is true
-///
-/// # Example
-///
-/// Usage:
-/// ```rust
-/// let mut cmd = clap::Command::new("raw")
-/// .arg(
-/// clap::Arg::new("append")
-/// .value_parser(clap::builder::BoolishValueParser::new())
-/// .required(true)
-/// );
-///
-/// let m = cmd.try_get_matches_from_mut(["cmd", "true"]).unwrap();
-/// let port: bool = *m.get_one("append")
-/// .expect("required");
-/// assert_eq!(port, true);
-/// ```
-///
-/// Semantics:
-/// ```rust
-/// # use std::ffi::OsStr;
-/// # use clap::builder::TypedValueParser;
-/// # let cmd = clap::Command::new("test");
-/// # let arg = None;
-/// let value_parser = clap::builder::BoolishValueParser::new();
-/// assert!(value_parser.parse_ref(&cmd, arg, OsStr::new("random")).is_err());
-/// assert!(value_parser.parse_ref(&cmd, arg, OsStr::new("")).is_err());
-/// assert!(value_parser.parse_ref(&cmd, arg, OsStr::new("100")).is_err());
-/// assert_eq!(value_parser.parse_ref(&cmd, arg, OsStr::new("true")).unwrap(), true);
-/// assert_eq!(value_parser.parse_ref(&cmd, arg, OsStr::new("Yes")).unwrap(), true);
-/// assert_eq!(value_parser.parse_ref(&cmd, arg, OsStr::new("oN")).unwrap(), true);
-/// assert_eq!(value_parser.parse_ref(&cmd, arg, OsStr::new("1")).unwrap(), true);
-/// assert_eq!(value_parser.parse_ref(&cmd, arg, OsStr::new("false")).unwrap(), false);
-/// assert_eq!(value_parser.parse_ref(&cmd, arg, OsStr::new("No")).unwrap(), false);
-/// assert_eq!(value_parser.parse_ref(&cmd, arg, OsStr::new("oFF")).unwrap(), false);
-/// assert_eq!(value_parser.parse_ref(&cmd, arg, OsStr::new("0")).unwrap(), false);
-/// ```
-#[derive(Copy, Clone, Debug)]
-#[non_exhaustive]
-pub struct BoolishValueParser {}
-
-impl BoolishValueParser {
- /// Parse bool-like string values, everything else is `true`
- pub fn new() -> Self {
- Self {}
- }
-
- fn possible_values() -> impl Iterator<Item = crate::PossibleValue<'static>> {
- crate::util::TRUE_LITERALS
- .iter()
- .chain(crate::util::FALSE_LITERALS.iter())
- .copied()
- .map(|l| crate::PossibleValue::new(l).hide(l != "true" && l != "false"))
- }
-}
-
-impl TypedValueParser for BoolishValueParser {
- type Value = bool;
-
- fn parse_ref(
- &self,
- cmd: &crate::Command,
- arg: Option<&crate::Arg>,
- value: &std::ffi::OsStr,
- ) -> Result<Self::Value, crate::Error> {
- let value = value.to_str().ok_or_else(|| {
- crate::Error::invalid_utf8(
- cmd,
- crate::output::Usage::new(cmd).create_usage_with_title(&[]),
- )
- })?;
- let value = crate::util::str_to_bool(value).ok_or_else(|| {
- let arg = arg
- .map(|a| a.to_string())
- .unwrap_or_else(|| "...".to_owned());
- crate::Error::value_validation(arg, value.to_owned(), "value was not a boolean".into())
- .with_cmd(cmd)
- })?;
- Ok(value)
- }
-
- fn possible_values(
- &self,
- ) -> Option<Box<dyn Iterator<Item = crate::PossibleValue<'static>> + '_>> {
- Some(Box::new(Self::possible_values()))
- }
-}
-
-impl Default for BoolishValueParser {
- fn default() -> Self {
- Self::new()
- }
-}
-
-/// Parse non-empty string values
-///
-/// See also:
-/// - [`ValueParser::string`]
-///
-/// # Example
-///
-/// Usage:
-/// ```rust
-/// let mut cmd = clap::Command::new("raw")
-/// .arg(
-/// clap::Arg::new("append")
-/// .value_parser(clap::builder::NonEmptyStringValueParser::new())
-/// .required(true)
-/// );
-///
-/// let m = cmd.try_get_matches_from_mut(["cmd", "true"]).unwrap();
-/// let port: &String = m.get_one("append")
-/// .expect("required");
-/// assert_eq!(port, "true");
-/// ```
-///
-/// Semantics:
-/// ```rust
-/// # use std::ffi::OsStr;
-/// # use clap::builder::TypedValueParser;
-/// # let cmd = clap::Command::new("test");
-/// # let arg = None;
-/// let value_parser = clap::builder::NonEmptyStringValueParser::new();
-/// assert_eq!(value_parser.parse_ref(&cmd, arg, OsStr::new("random")).unwrap(), "random");
-/// assert!(value_parser.parse_ref(&cmd, arg, OsStr::new("")).is_err());
-/// ```
-#[derive(Copy, Clone, Debug)]
-#[non_exhaustive]
-pub struct NonEmptyStringValueParser {}
-
-impl NonEmptyStringValueParser {
- /// Parse non-empty string values
- pub fn new() -> Self {
- Self {}
- }
-}
-
-impl TypedValueParser for NonEmptyStringValueParser {
- type Value = String;
-
- fn parse_ref(
- &self,
- cmd: &crate::Command,
- arg: Option<&crate::Arg>,
- value: &std::ffi::OsStr,
- ) -> Result<Self::Value, crate::Error> {
- if value.is_empty() {
- return Err(crate::Error::empty_value(
- cmd,
- &[],
- arg.map(ToString::to_string)
- .unwrap_or_else(|| "...".to_owned()),
- ));
- }
- let value = value.to_str().ok_or_else(|| {
- crate::Error::invalid_utf8(
- cmd,
- crate::output::Usage::new(cmd).create_usage_with_title(&[]),
- )
- })?;
- Ok(value.to_owned())
- }
-}
-
-impl Default for NonEmptyStringValueParser {
- fn default() -> Self {
- Self::new()
- }
-}
-
-/// Register a type with [value_parser!][crate::value_parser!]
-///
-/// # Example
-///
-/// ```rust
-/// #[derive(Copy, Clone, Debug)]
-/// pub struct Custom(u32);
-///
-/// impl clap::builder::ValueParserFactory for Custom {
-/// type Parser = CustomValueParser;
-/// fn value_parser() -> Self::Parser {
-/// CustomValueParser
-/// }
-/// }
-///
-/// #[derive(Clone, Debug)]
-/// pub struct CustomValueParser;
-/// impl clap::builder::TypedValueParser for CustomValueParser {
-/// type Value = Custom;
-///
-/// fn parse_ref(
-/// &self,
-/// cmd: &clap::Command,
-/// arg: Option<&clap::Arg>,
-/// value: &std::ffi::OsStr,
-/// ) -> Result<Self::Value, clap::Error> {
-/// let inner = clap::value_parser!(u32);
-/// let val = inner.parse_ref(cmd, arg, value)?;
-/// Ok(Custom(val))
-/// }
-/// }
-///
-/// let parser: CustomValueParser = clap::value_parser!(Custom);
-/// ```
-pub trait ValueParserFactory {
- /// Generated parser, usually [`ValueParser`].
- ///
- /// It should at least be a type that supports `Into<ValueParser>`. A non-`ValueParser` type
- /// allows the caller to do further initialization on the parser.
- type Parser;
-
- /// Create the specified [`Self::Parser`]
- fn value_parser() -> Self::Parser;
-}
-impl ValueParserFactory for String {
- type Parser = ValueParser;
- fn value_parser() -> Self::Parser {
- ValueParser::string()
- }
-}
-impl ValueParserFactory for std::ffi::OsString {
- type Parser = ValueParser;
- fn value_parser() -> Self::Parser {
- ValueParser::os_string()
- }
-}
-impl ValueParserFactory for std::path::PathBuf {
- type Parser = ValueParser;
- fn value_parser() -> Self::Parser {
- ValueParser::path_buf()
- }
-}
-impl ValueParserFactory for bool {
- type Parser = ValueParser;
- fn value_parser() -> Self::Parser {
- ValueParser::bool()
- }
-}
-impl ValueParserFactory for u8 {
- type Parser = RangedI64ValueParser<u8>;
- fn value_parser() -> Self::Parser {
- let start: i64 = u8::MIN.into();
- let end: i64 = u8::MAX.into();
- RangedI64ValueParser::new().range(start..=end)
- }
-}
-impl ValueParserFactory for i8 {
- type Parser = RangedI64ValueParser<i8>;
- fn value_parser() -> Self::Parser {
- let start: i64 = i8::MIN.into();
- let end: i64 = i8::MAX.into();
- RangedI64ValueParser::new().range(start..=end)
- }
-}
-impl ValueParserFactory for u16 {
- type Parser = RangedI64ValueParser<u16>;
- fn value_parser() -> Self::Parser {
- let start: i64 = u16::MIN.into();
- let end: i64 = u16::MAX.into();
- RangedI64ValueParser::new().range(start..=end)
- }
-}
-impl ValueParserFactory for i16 {
- type Parser = RangedI64ValueParser<i16>;
- fn value_parser() -> Self::Parser {
- let start: i64 = i16::MIN.into();
- let end: i64 = i16::MAX.into();
- RangedI64ValueParser::new().range(start..=end)
- }
-}
-impl ValueParserFactory for u32 {
- type Parser = RangedI64ValueParser<u32>;
- fn value_parser() -> Self::Parser {
- let start: i64 = u32::MIN.into();
- let end: i64 = u32::MAX.into();
- RangedI64ValueParser::new().range(start..=end)
- }
-}
-impl ValueParserFactory for i32 {
- type Parser = RangedI64ValueParser<i32>;
- fn value_parser() -> Self::Parser {
- let start: i64 = i32::MIN.into();
- let end: i64 = i32::MAX.into();
- RangedI64ValueParser::new().range(start..=end)
- }
-}
-impl ValueParserFactory for i64 {
- type Parser = RangedI64ValueParser<i64>;
- fn value_parser() -> Self::Parser {
- RangedI64ValueParser::new()
- }
-}
-impl ValueParserFactory for u64 {
- type Parser = RangedU64ValueParser<u64>;
- fn value_parser() -> Self::Parser {
- RangedU64ValueParser::new()
- }
-}
-
-#[doc(hidden)]
-#[derive(Debug)]
-pub struct _AutoValueParser<T>(std::marker::PhantomData<T>);
-
-impl<T> _AutoValueParser<T> {
- #[doc(hidden)]
- #[allow(clippy::new_without_default)]
- pub fn new() -> Self {
- Self(Default::default())
- }
-}
-
-/// Unstable [`ValueParser`]
-///
-/// Implementation may change to more specific instance in the future
-#[doc(hidden)]
-#[derive(Debug)]
-pub struct _AnonymousValueParser(ValueParser);
-
-#[doc(hidden)]
-pub mod via_prelude {
- use super::*;
-
- #[doc(hidden)]
- pub trait _ValueParserViaFactory: private::_ValueParserViaFactorySealed {
- type Parser;
- fn value_parser(&self) -> Self::Parser;
- }
- impl<P: ValueParserFactory> _ValueParserViaFactory for &&_AutoValueParser<P> {
- type Parser = P::Parser;
- fn value_parser(&self) -> Self::Parser {
- P::value_parser()
- }
- }
-
- #[doc(hidden)]
- pub trait _ValueParserViaValueEnum: private::_ValueParserViaValueEnumSealed {
- type Output;
-
- fn value_parser(&self) -> Self::Output;
- }
- impl<E: crate::ValueEnum + Clone + Send + Sync + 'static> _ValueParserViaValueEnum
- for &_AutoValueParser<E>
- {
- type Output = EnumValueParser<E>;
-
- fn value_parser(&self) -> Self::Output {
- EnumValueParser::<E>::new()
- }
- }
-
- #[doc(hidden)]
- pub trait _ValueParserViaFromStr: private::_ValueParserViaFromStrSealed {
- fn value_parser(&self) -> _AnonymousValueParser;
- }
- impl<FromStr> _ValueParserViaFromStr for _AutoValueParser<FromStr>
- where
- FromStr: std::str::FromStr + std::any::Any + Clone + Send + Sync + 'static,
- <FromStr as std::str::FromStr>::Err:
- Into<Box<dyn std::error::Error + Send + Sync + 'static>>,
- {
- fn value_parser(&self) -> _AnonymousValueParser {
- let func: fn(&str) -> Result<FromStr, <FromStr as std::str::FromStr>::Err> =
- FromStr::from_str;
- _AnonymousValueParser(ValueParser::new(func))
- }
- }
-}
-
-/// Select a [`ValueParser`] implementation from the intended type
-///
-/// To register a custom type with this macro, implement [`ValueParserFactory`].
-///
-/// # Example
-///
-/// Usage:
-/// ```rust
-/// # use std::path::PathBuf;
-/// # use std::path::Path;
-/// let mut cmd = clap::Command::new("raw")
-/// .arg(
-/// clap::Arg::new("output")
-/// .value_parser(clap::value_parser!(PathBuf))
-/// .required(true)
-/// );
-///
-/// let m = cmd.try_get_matches_from_mut(["cmd", "file.txt"]).unwrap();
-/// let port: &PathBuf = m.get_one("output")
-/// .expect("required");
-/// assert_eq!(port, Path::new("file.txt"));
-/// ```
-///
-/// Supported types:
-/// ```rust
-/// // Built-in types
-/// let parser = clap::value_parser!(String);
-/// assert_eq!(format!("{:?}", parser), "ValueParser::string");
-/// let parser = clap::value_parser!(std::ffi::OsString);
-/// assert_eq!(format!("{:?}", parser), "ValueParser::os_string");
-/// let parser = clap::value_parser!(std::path::PathBuf);
-/// assert_eq!(format!("{:?}", parser), "ValueParser::path_buf");
-/// let parser = clap::value_parser!(u16).range(3000..);
-/// assert_eq!(format!("{:?}", parser), "RangedI64ValueParser { bounds: (Included(3000), Included(65535)), target: PhantomData }");
-/// let parser = clap::value_parser!(u64).range(3000..);
-/// assert_eq!(format!("{:?}", parser), "RangedU64ValueParser { bounds: (Included(3000), Unbounded), target: PhantomData }");
-///
-/// // FromStr types
-/// let parser = clap::value_parser!(usize);
-/// assert_eq!(format!("{:?}", parser), "_AnonymousValueParser(ValueParser::other(usize))");
-///
-/// // ValueEnum types
-/// #[derive(Copy, Clone, Debug, PartialEq, Eq)]
-/// enum ColorChoice {
-/// Always,
-/// Auto,
-/// Never,
-/// }
-/// impl clap::ValueEnum for ColorChoice {
-/// // ...
-/// # fn value_variants<'a>() -> &'a [Self] {
-/// # &[Self::Always, Self::Auto, Self::Never]
-/// # }
-/// # fn to_possible_value<'a>(&self) -> Option<clap::PossibleValue<'a>> {
-/// # match self {
-/// # Self::Always => Some(clap::PossibleValue::new("always")),
-/// # Self::Auto => Some(clap::PossibleValue::new("auto")),
-/// # Self::Never => Some(clap::PossibleValue::new("never")),
-/// # }
-/// # }
-/// }
-/// let parser = clap::value_parser!(ColorChoice);
-/// assert_eq!(format!("{:?}", parser), "EnumValueParser(PhantomData)");
-/// ```
-#[macro_export]
-macro_rules! value_parser {
- ($name:ty) => {{
- use $crate::builder::via_prelude::*;
- let auto = $crate::builder::_AutoValueParser::<$name>::new();
- (&&&auto).value_parser()
- }};
-}
-
-mod private {
- use super::*;
-
- pub trait _ValueParserViaSelfSealed {}
- impl<P: Into<ValueParser>> _ValueParserViaSelfSealed for &&&_AutoValueParser<P> {}
-
- pub trait _ValueParserViaFactorySealed {}
- impl<P: ValueParserFactory> _ValueParserViaFactorySealed for &&_AutoValueParser<P> {}
-
- pub trait _ValueParserViaValueEnumSealed {}
- impl<E: crate::ValueEnum> _ValueParserViaValueEnumSealed for &_AutoValueParser<E> {}
-
- pub trait _ValueParserViaFromStrSealed {}
- impl<FromStr> _ValueParserViaFromStrSealed for _AutoValueParser<FromStr>
- where
- FromStr: std::str::FromStr + std::any::Any + Send + Sync + 'static,
- <FromStr as std::str::FromStr>::Err:
- Into<Box<dyn std::error::Error + Send + Sync + 'static>>,
- {
- }
-}
-
-#[cfg(test)]
-mod test {
- use super::*;
-
- #[test]
- fn ensure_typed_applies_to_parse() {
- fn parse(_: &str) -> Result<usize, std::io::Error> {
- Ok(10)
- }
- let cmd = crate::Command::new("cmd");
- let arg = None;
- assert_eq!(
- TypedValueParser::parse_ref(&parse, &cmd, arg, std::ffi::OsStr::new("foo")).unwrap(),
- 10
- );
- }
-}
generated by cgit v1.2.3 (git 2.39.1) at 2024-11-03 19:20:22 +0000