#![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, display_name: Option, bin_name: Option, 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, help_str: Option<&'help str>, disp_ord: Option, term_w: Option, max_w: Option, template: Option<&'help str>, settings: AppFlags, g_settings: AppFlags, args: MKeyMap<'help>, subcommands: Vec>, replacers: HashMap<&'help str, &'help [&'help str]>, groups: Vec>, current_help_heading: Option<&'help str>, current_disp_ord: Option, 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>(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 "Optionally sets a config file to use") /// ) /// # ; /// ``` /// [argument]: Arg #[must_use] pub fn arg>>(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(mut self, args: I) -> Self where I: IntoIterator, T: Into>, { 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(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>>(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(mut self, groups: I) -> Self where I: IntoIterator, T: Into>, { 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!(" 'Required configuration file to use'"))) /// # ; /// ``` #[inline] #[must_use] pub fn subcommand>>(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(mut self, subcmds: I) -> Self where I: IntoIterator, T: Into>, { 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::("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 { // 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(mut self, itr: I) -> ArgMatches where I: IntoIterator, T: Into + 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(mut self, itr: I) -> ClapResult where I: IntoIterator, T: Into + 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(&mut self, itr: I) -> ClapResult where I: IntoIterator, T: Into + 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(&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(&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!( ... "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 "Sets a custom config file").required(false)) /// .arg(arg!(-x --stuff "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>(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>(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>(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>(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>>(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>>(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>(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>(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>(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>(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>(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>(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] ") /// # ; /// ``` /// /// Or for multiple usage lines: /// /// ```no_run /// # use clap::{Command, Arg}; /// Command::new("myprog") /// .override_usage( /// "myapp -X [-a] [-b] \n \ /// myapp -Y [-c] \n \ /// myapp -Z [-d|-e]" /// ) /// # ; /// ``` /// /// [`ArgMatches::usage`]: ArgMatches::usage() #[must_use] pub fn override_usage>(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 \n\n\ /// /// Options:\n\ /// -h, --help Display this message\n\ /// -V, --version Display version info\n\ /// -s 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>(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>(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(mut self, setting: F) -> Self where F: Into, { 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(mut self, setting: F) -> Self where F: Into, { 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(self, heading: O) -> Self where O: Into>, { 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(mut self, heading: O) -> Self where O: Into>, { 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>) -> 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::("save-context").expect("defaulted by clap")); /// assert!(*m.get_one::("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::("save-context").expect("defaulted by clap")); /// assert!(*m.get_one::("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!( ... "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] ` where one /// of the two following usages is allowed: /// /// * `$ prog [optional] ` /// * `$ prog ` /// /// 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::>(), &["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::>(), &["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::("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::("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>(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>(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_args] [subcmd_args] [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: /// /// * ` [subsubcmd_args]` /// * ` [subcmd_args]` /// * ` [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::>(), /// &["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::>(), /// &["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(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(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>(&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 { 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 + '_ { 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 + '_ { 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 + '_ { 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 + '_ { 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 + '_ { 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 + '_ { 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> { 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> { 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(&self, name: &T) -> Option<&App<'help>> where T: PartialEq + ?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(&mut self, name: &T) -> Option<&mut App<'help>> where T: PartialEq + ?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> { self.groups.iter() } /// Iterate through the set of arguments. #[inline] pub fn get_arguments(&self) -> impl Iterator> { self.args.args() } /// Iterate through the *positionals* arguments. #[inline] pub fn get_positionals(&self) -> impl Iterator> { self.get_arguments().filter(|a| a.is_positional()) } /// Iterate through the *options*. pub fn get_opts(&self) -> impl Iterator> { 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>(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>(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>(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(&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(&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 { 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(self, itr: I) -> ClapResult where I: IntoIterator, T: Into + 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(&mut self, itr: I) -> ClapResult where I: IntoIterator, T: Into + 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 { self.term_w } pub(crate) fn get_max_term_width(&self) -> Option { 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) { 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 { 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 + [] + 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 = 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(&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(&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. x.name_no_brackets().to_string() } else { // Print usage string for flags arguments, e.g. <--help> x.to_string() } }) .collect::>() .join("|"); format!("<{}>", &*g_string) } } /// A workaround: /// 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> { 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> { 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> { 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(&self, name: &T) -> bool where T: PartialEq + ?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(&self, flag: &T) -> bool where T: PartialEq + ?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 + '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 + 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 { 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 { 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(&self, func: F, arg: &Id) -> Vec where F: Fn(&(ArgPredicate<'_>, Id)) -> Option, { 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 { 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(mut iter: I) -> Option<(T, T)> where I: Iterator, { 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); }