Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #3774 from epage/action
feat(builder): Expose ArgAction
- Loading branch information
Showing
6 changed files
with
199 additions
and
23 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,8 +1,135 @@ | ||
| /// Behavior of arguments when they are encountered while parsing | ||
| #[derive(Clone, Debug, PartialEq, Eq)] | ||
| pub(crate) enum ArgAction { | ||
| /// | ||
| /// # Examples | ||
| /// | ||
| /// ```rust | ||
| /// # use clap::Command; | ||
| /// # use clap::Arg; | ||
| /// let cmd = Command::new("mycmd") | ||
| /// .arg( | ||
| /// Arg::new("special-help") | ||
| /// .short('?') | ||
| /// .action(clap::builder::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::builder::ArgAction::StoreValue) | ||
| /// ); | ||
| /// | ||
| /// let matches = cmd.try_get_matches_from(["mycmd", "--flag", "value"]).unwrap(); | ||
| /// assert!(matches.is_present("flag")); | ||
| /// assert_eq!(matches.occurrences_of("flag"), 1); | ||
| /// assert_eq!( | ||
| /// matches.get_many::<String>("flag").unwrap_or_default().map(|v| v.as_str()).collect::<Vec<_>>(), | ||
| /// vec!["value"] | ||
| /// ); | ||
| /// ``` | ||
| StoreValue, | ||
| Flag, | ||
| /// When encountered, increment [`ArgMatches::occurrences_of`][crate::ArgMatches::occurrences_of] | ||
| /// | ||
| /// No value is allowed | ||
| /// | ||
| /// # Examples | ||
| /// | ||
| /// ```rust | ||
| /// # use clap::Command; | ||
| /// # use clap::Arg; | ||
| /// let cmd = Command::new("mycmd") | ||
| /// .arg( | ||
| /// Arg::new("flag") | ||
| /// .long("flag") | ||
| /// .multiple_occurrences(true) | ||
| /// .action(clap::builder::ArgAction::IncOccurrence) | ||
| /// ); | ||
| /// | ||
| /// let matches = cmd.try_get_matches_from(["mycmd", "--flag", "--flag"]).unwrap(); | ||
| /// assert!(matches.is_present("flag")); | ||
| /// assert_eq!(matches.occurrences_of("flag"), 2); | ||
| /// assert_eq!(matches.get_many::<String>("flag").unwrap_or_default().count(), 0); | ||
| /// ``` | ||
| IncOccurrence, | ||
| /// 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::builder::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::builder::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 { | ||
| pub(crate) fn takes_value(&self) -> bool { | ||
| match self { | ||
| Self::StoreValue => true, | ||
| Self::IncOccurrence => false, | ||
| Self::Help => false, | ||
| Self::Version => false, | ||
| } | ||
| } | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters