Struct clap::App

pub struct App<'help> { /* fields omitted */ }

Represents a command line interface which is made up of all possible command line arguments and subcommands. Interface arguments and settings are configured using the "builder pattern." Once all configuration is complete, the App::get_matches family of methods starts the runtime-parsing process. These methods then return information about the user supplied arguments (or lack thereof).

NOTE: There aren't any mandatory "options" that one must set. The "options" may also appear in any order (so long as one of the App::get_matches methods is the last method called).

Examples

let m = App::new("My Program")
    .author("Me, [email protected]")
    .version("1.0.2")
    .about("Explains in brief what the program does")
    .arg(
        Arg::new("in_file").index(1)
    )
    .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...

Implementations

impl<'help> App<'help>

pub fn get_name(&self) -> &str

Get the name of the app.

pub fn get_short_flag(&self) -> Option<char>

Get the short flag of the subcommand.

pub fn get_long_flag(&self) -> Option<&str>

Get the long flag of the subcommand.

pub fn get_bin_name(&self) -> Option<&str>

Get the name of the binary.

pub fn set_bin_name<S: Into<String>>(&mut self, name: S)

Set binary name. Uses &mut self instead of self.

pub fn get_about(&self) -> Option<&str>

Get the help message specified via App::about.

pub fn get_visible_aliases(&self) -> impl Iterator<Item = &str>

Iterate through the visible aliases for this subcommand.

pub fn get_visible_short_flag_aliases(&self) -> impl Iterator<Item = char> + '_

Iterate through the visible short aliases for this subcommand.

pub fn get_visible_long_flag_aliases(
    &self
) -> impl Iterator<Item = &'help str> + '_

Iterate through the visible short aliases for this subcommand.

pub fn get_all_aliases(&self) -> impl Iterator<Item = &str>

Iterate through the set of all the aliases for this subcommand, both visible and hidden.

pub fn get_all_short_flag_aliases(&self) -> impl Iterator<Item = char> + '_

Iterate through the set of all the short aliases for this subcommand, both visible and hidden.

pub fn get_all_long_flag_aliases(&self) -> impl Iterator<Item = &'help str> + '_

Iterate through the set of all the long aliases for this subcommand, both visible and hidden.

pub fn get_subcommands(&self) -> impl Iterator<Item = &App<'help>>

Iterate through the set of subcommands, getting a reference to each.

pub fn get_subcommands_mut(&mut self) -> impl Iterator<Item = &mut App<'help>>

Iterate through the set of subcommands, getting a mutable reference to each.

pub fn get_arguments(&self) -> impl Iterator<Item = &Arg<'help>>

Iterate through the set of arguments.

pub fn get_positionals(&self) -> impl Iterator<Item = &Arg<'help>>

Get the list of positional arguments.

pub fn get_flags_with_no_heading(&self) -> impl Iterator<Item = &Arg<'help>>

Iterate through the flags that don't have custom heading.

pub fn get_opts_with_no_heading(&self) -> impl Iterator<Item = &Arg<'help>>

Iterate through the options that don't have custom heading.

pub fn get_arg_conflicts_with(&self, arg: &Arg<'_>) -> Vec<&Arg<'help>>

Get a list of all arguments the given argument conflicts with.

Panics

If the given arg contains a conflict with an argument that is unknown to this App.

pub fn is_set(&self, s: AppSettings) -> bool

Returns true if the given AppSettings variant is currently set in this App (checks both local and global settings).

pub fn has_subcommands(&self) -> bool

Returns true if this App has subcommands.

pub fn find_subcommand<T: ?Sized>(&self, name: &T) -> Option<&App<'help>> where
    T: PartialEq<str>, 

Find subcommand such that its name or one of aliases equals name.

This does not recurse through subcommands of subcommands.

impl<'help> App<'help>

pub fn new<S: Into<String>>(name: S) -> Self

Creates a new instance of an App requiring a name.

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.

An App represents a command line interface (CLI) which is made up of all possible command line arguments and subcommands. "Subcommands" are sub-CLIs with their own arguments, settings, and even subcommands forming a sort of hierarchy.

Examples

App::new("My Program")

pub fn author<S: Into<&'help str>>(self, author: S) -> Self

Sets a string of author(s) that will be displayed to the user when they request the help message.

Pro-tip: Use claps convenience macro crate_authors! to automatically set your application's author(s) to the same thing as your crate at compile time.

See the examples/ directory for more information.

Examples

App::new("myprog")
     .author("Me, [email protected]")

pub fn bin_name<S: Into<String>>(self, name: S) -> Self

Overrides the runtime-determined name of the binary. 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.

Normally, the binary name is used in help and error messages. clap automatically determines the binary name at runtime, however by manually setting the binary name, one can effectively override what will be displayed in the help or error messages.

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

App::new("My Program")
     .bin_name("my_binary")

pub fn about<S: Into<&'help str>>(self, about: S) -> Self

Sets a string describing what the program does. This will be displayed when the user requests the short format help message (-h).

clap can display two different help messages, a long format and a short format depending on whether the user used -h (short) or --help (long). This method sets the message during the short format (-h) message. However, if no long format message is configured, this message will be displayed for both the long format, or short format help message.

NOTE: Only App::about (short format) is used in completion script generation in order to be concise.

Examples

App::new("myprog")
    .about("Does really amazing things for great people")

pub fn long_about<S: Into<&'help str>>(self, about: S) -> Self

Sets a long format string describing what the program does. This will be displayed when the user requests the long format help message (--help).

Advanced

clap can display two different help messages, a long format and a short format depending on whether the user used -h (short) or --help (long). This method sets the message during the long format (--help) message. However, if no short format message is configured, this message will be displayed for both the long format, or short format help message.

NOTE: Only App::about (short format) is used in completion script generation in order to be concise.

Examples

App::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!")

pub fn name<S: Into<String>>(self, name: S) -> Self

(Re)Sets the program's name. This will be displayed when displaying help or version messages.

Pro-tip: This function is particularly useful when configuring a program via App::from(yaml) in conjunction with the crate_name! macro to derive the program's name from its Cargo.toml.

Examples

let yaml = load_yaml!("app.yaml");
let app = App::from(yaml)
    .name(crate_name!());

// continued logic goes here, such as `app.get_matches()` etc.

pub fn after_help<S: Into<&'help str>>(self, help: S) -> Self

Adds additional help information to be displayed at the end of the auto-generated help. This is often used to describe how to use the arguments, caveats to be noted, or license and contact information.

NOTE: If only after_long_help is provided, and not App::after_help but the user requests -h clap will still display the contents of after_help appropriately.

Examples

App::new("myprog")
    .after_help("Does really amazing things for great people... but be careful with -R!")

pub fn after_long_help<S: Into<&'help str>>(self, help: S) -> Self

Adds additional help information to be displayed in addition to auto-generated help. This information is displayed after the auto-generated help information and is meant to be more verbose than after_help. This is often used to describe how to use the arguments, or caveats to be noted in man pages.

NOTE: If only after_help is provided, and not App::after_long_help but the user requests --help, clap will still display the contents of after_help appropriately.

Examples

App::new("myprog")
    .after_long_help("Does really amazing things to great people... but be careful with -R, \
                     like, for real, be careful with this!")

pub fn before_help<S: Into<&'help str>>(self, help: S) -> Self

Adds additional help information to be displayed prior to the auto-generated help. This is often used for header, copyright, or license information.

NOTE: If only before_long_help is provided, and not App::before_help but the user requests -h clap will still display the contents of before_long_help appropriately.

Examples

App::new("myprog")
    .before_help("Some info I'd like to appear before the help info")

pub fn before_long_help<S: Into<&'help str>>(self, help: S) -> Self

Adds additional help information to be displayed prior to the auto-generated help. This is often used for header, copyright, or license information.

NOTE: If only before_help is provided, and not App::before_long_help but the user requests --help, clap will still display the contents of before_help appropriately.

Examples

App::new("myprog")
    .before_long_help("Some verbose and long info I'd like to appear before the help info")

pub fn short_flag(self, short: char) -> Self

Allows the subcommand to be used as if it were an Arg::short.

Sets the short version of the subcommand flag without the preceding -.

Examples

let matches = App::new("pacman")
    .subcommand(
        App::new("sync").short_flag('S').arg(
            Arg::new("search")
                .short('s')
                .long("search")
                .about("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.is_present("search"));

pub fn long_flag(self, long: &'help str) -> Self

Allows the subcommand to be used as if it were an Arg::long.

Sets the long version of the subcommand flag without the preceding --.

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).

let matches = App::new("pacman")
    .subcommand(
        App::new("sync").long_flag("sync").arg(
            Arg::new("search")
                .short('s')
                .long("search")
                .about("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.is_present("search"));

pub fn version<S: Into<&'help str>>(self, ver: S) -> Self

Sets a string of the version number to be displayed when displaying the short format version message (-V) or the help message.

Pro-tip: Use claps convenience macro crate_version! to automatically set your application's version to the same thing as your crate at compile time. See the examples/ directory for more information.

clap can display two different version messages, a [long format] and a [short format] depending on whether the user used -V (short) or --version (long). This method sets the message during the short format (-V). However, if no long format message is configured, this message will be displayed for both the long format, or short format version message.

Examples

App::new("myprog")
    .version("v0.1.24")

pub fn long_version<S: Into<&'help str>>(self, ver: S) -> Self

Sets a string of the version number to be displayed when the user requests the long format version message (--version) or the help message.

This is often used to display things such as commit ID, or compile time configured options.

Pro-tip: Use claps convenience macro crate_version! to automatically set your application's version to the same thing as your crate at compile time. See the examples/ directory for more information.

clap can display two different version messages, a [long format] and a [short format] depending on whether the user used -V (short) or --version (long). This method sets the message during the long format (--version). However, if no short format message is configured, this message will be displayed for both the long format, or short format version message.

Examples

App::new("myprog")
    .long_version(
"v0.1.24
 commit: abcdef89726d
 revision: 123
 release: 2
 binary: myprog")

pub fn override_usage<S: Into<&'help str>>(self, usage: S) -> Self

Overrides the clap generated usage string.

This will be displayed to the user when errors are found in argument parsing.

CAUTION: Using this setting disables claps "context-aware" usage strings. After this setting is set, this will be the only usage string displayed to the user!

NOTE: This will not replace the entire help message, only the portion showing the usage.

Examples

App::new("myprog")
    .override_usage("myapp [-clDas] <some_file>")

pub fn override_help<S: Into<&'help str>>(self, help: S) -> Self

Overrides the clap generated help message. This should only be used when the auto-generated message does not suffice.

This will be displayed to the user when they use --help or -h.

NOTE: This replaces the entire help message, so nothing will be auto-generated.

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 Arg::override_help for them as well.

Examples

App::new("myapp")
    .override_help("myapp v1.0\n\
           Does awesome things\n\
           (C) [email protected]\n\n\

           USAGE: myapp <opts> <comamnd>\n\n\

           Options:\n\
           -h, --help       Display this message\n\
           -V, --version    Display version info\n\
           -s <stuff>       Do something with stuff\n\
           -v               Be verbose\n\n\

           Commmands:\n\
           help             Prints this message\n\
           work             Do some work")

pub fn help_template<S: Into<&'help str>>(self, s: S) -> 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:

• {bin} - Binary name.
• {version} - Version number.
• {author} - Author information.
• {author-with-newline} - Author followed by \n.
• {about} - General description (from App::about or App::long_about).
• {about-with-newline} - About 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.
• {unified} - Unified help for options and flags. Note, you must also set AppSettings::UnifiedHelpMessage to fully merge both options and flags, otherwise the ordering is "best effort".
• {flags} - Help for flags.
• {options} - Help for options.
• {positionals} - Help for positional arguments.
• {subcommands} - Help for subcommands.
• {after-help} - Help from App::after_help or App::after_long_help.
• {before-help} - Help from App::before_help or App::before_long_help.

Examples

App::new("myprog")
    .version("1.0")
    .help_template("{bin} ({version}) - {usage}")

pub fn setting(self, setting: AppSettings) -> Self

Enables a single settings for the current (this App instance) command or subcommand.

See AppSettings for a full list of possibilities and examples.

Examples

App::new("myprog")
    .setting(AppSettings::SubcommandRequired)
    .setting(AppSettings::WaitOnError)

pub fn unset_setting(self, setting: AppSettings) -> Self

Disables a single setting for the current (this App instance) command or subcommand.

See AppSettings for a full list of possibilities and examples.

Examples

App::new("myprog")
    .unset_setting(AppSettings::ColorAuto)

pub fn global_setting(self, setting: AppSettings) -> Self

Enables a single setting that is propagated down through all child subcommands.

See AppSettings for a full list of possibilities and examples.

NOTE: The setting is only propagated down and not up through parent commands.

Examples

App::new("myprog")
    .global_setting(AppSettings::SubcommandRequired)

pub fn unset_global_setting(self, setting: AppSettings) -> Self

Disables a global setting, and stops propagating down to child subcommands.

See AppSettings for a full list of possibilities and examples.

NOTE: The setting being unset will be unset from both local and global settings.

Examples

App::new("myprog")
    .unset_global_setting(AppSettings::ColorAuto)

pub fn term_width(self, width: usize) -> Self

Sets the terminal width at which to wrap help messages. Defaults to 120. Using 0 will ignore terminal widths and use source formatting.

clap automatically tries to determine the terminal width on Unix, Linux, OSX and Windows if the wrap_help cargo "feature" has been enabled at compile time. If the terminal width cannot be determined, clap fall back to 100.

NOTE: This setting applies globally and not on a per-command basis.

NOTE: This setting must be set before any subcommands are added!

Platform Specific

Only Unix, Linux, OSX and Windows support automatic determination of terminal width. Even on those platforms, this setting is useful if for any reason the terminal width cannot be determined.

Examples

App::new("myprog")
    .term_width(80)

pub fn max_term_width(self, w: usize) -> Self

Sets the maximum terminal width at which to wrap help messages. Using 0 will ignore terminal widths and use source formatting.

clap automatically tries to determine the terminal width on Unix, Linux, OSX and Windows if the wrap_help cargo "feature" has been enabled at compile time, but one might want to limit the size to some maximum (e.g. when the terminal is running fullscreen).

NOTE: This setting applies globally and not on a per-command basis.

NOTE: This setting must be set before any subcommands are added!

Platform Specific

Only Unix, Linux, OSX and Windows support automatic determination of terminal width.

Examples

App::new("myprog")
    .max_term_width(100)

pub fn arg<A: Into<Arg<'help>>>(self, a: A) -> Self

Adds an argument to the list of valid possibilities.

Examples

App::new("myprog")
    // Adding a single "flag" argument with a short and help text, using Arg::new()
    .arg(
        Arg::new("debug")
           .short('d')
           .about("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::from("-c --config=[CONFIG] 'Optionally sets a config file to use'")
    )

pub fn help_heading(self, heading: &'help str) -> Self

Set a custom section heading for future args. Every call to App::arg (and its related methods) will use this header (instead of the default header for the specified argument type) until a subsequent call to App::help_heading or App::stop_custom_headings.

This is useful if the default FLAGS, OPTIONS, or ARGS headings are not specific enough for one's use case.

pub fn stop_custom_headings(self) -> Self

Stop using custom argument headings and return to default headings.

pub fn args<I, T>(self, args: I) -> Self where
    I: IntoIterator<Item = T>,
    T: Into<Arg<'help>>, 

Adds multiple arguments to the list of valid possibilities.

Examples

App::new("myprog")
    .args(&[
        Arg::from("[debug] -d 'turns on debugging info'"),
        Arg::new("input").index(1).about("the input file to use")
    ])

pub fn alias<S: Into<&'help str>>(self, name: S) -> Self

If this App instance is a subcommand, this method adds an alias, which allows this 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 App::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

let m = App::new("myprog")
    .subcommand(App::new("test")
        .alias("do-stuff"))
    .get_matches_from(vec!["myprog", "do-stuff"]);
assert_eq!(m.subcommand_name(), Some("test"));

pub fn short_flag_alias(self, name: char) -> Self

Allows adding an alias, which function as "hidden" short flag subcommands that 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

let m = App::new("myprog")
            .subcommand(App::new("test").short_flag('t')
                .short_flag_alias('d'))
            .get_matches_from(vec!["myprog", "-d"]);
assert_eq!(m.subcommand_name(), Some("test"));

pub fn long_flag_alias(self, name: &'help str) -> Self

Allows adding an alias, which function as "hidden" long flag subcommands that 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

let m = App::new("myprog")
            .subcommand(App::new("test").long_flag("test")
                .long_flag_alias("testing"))
            .get_matches_from(vec!["myprog", "--testing"]);
assert_eq!(m.subcommand_name(), Some("test"));

pub fn aliases(self, names: &[&'help str]) -> Self

If this App instance is a subcommand, this method adds a multiple aliases, which allows this 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 App::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

let m = App::new("myprog")
    .subcommand(App::new("test")
        .aliases(&["do-stuff", "do-tests", "tests"]))
        .arg(Arg::new("input")
            .about("the file to add")
            .index(1)
            .required(false))
    .get_matches_from(vec!["myprog", "do-tests"]);
assert_eq!(m.subcommand_name(), Some("test"));

pub fn short_flag_aliases(self, names: &[char]) -> Self

Allows adding aliases, which function as "hidden" short flag subcommands that 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

let m = App::new("myprog")
    .subcommand(App::new("test").short_flag('t')
        .short_flag_aliases(&['a', 'b', 'c']))
        .arg(Arg::new("input")
            .about("the file to add")
            .index(1)
            .required(false))
    .get_matches_from(vec!["myprog", "-a"]);
assert_eq!(m.subcommand_name(), Some("test"));

pub fn long_flag_aliases(self, names: &[&'help str]) -> Self

Allows adding aliases, which function as "hidden" long flag subcommands that 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

let m = App::new("myprog")
            .subcommand(App::new("test").long_flag("test")
                .long_flag_aliases(&["testing", "testall", "test_all"]))
                .arg(Arg::new("input")
                            .about("the file to add")
                            .index(1)
                            .required(false))
            .get_matches_from(vec!["myprog", "--testing"]);
assert_eq!(m.subcommand_name(), Some("test"));

pub fn visible_alias<S: Into<&'help str>>(self, name: S) -> Self

If this App instance is a subcommand, this method adds a visible alias, which allows this 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 App::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

let m = App::new("myprog")
    .subcommand(App::new("test")
        .visible_alias("do-stuff"))
    .get_matches_from(vec!["myprog", "do-stuff"]);
assert_eq!(m.subcommand_name(), Some("test"));

pub fn visible_short_flag_alias(self, name: char) -> Self

Allows adding an alias that functions exactly like those defined with App::short_flag_alias, except that they are visible inside the help message.

Examples

let m = App::new("myprog")
            .subcommand(App::new("test").short_flag('t')
                .visible_short_flag_alias('d'))
            .get_matches_from(vec!["myprog", "-d"]);
assert_eq!(m.subcommand_name(), Some("test"));

pub fn visible_long_flag_alias(self, name: &'help str) -> Self

Allows adding an alias that functions exactly like those defined with App::long_flag_alias, except that they are visible inside the help message.

Examples

let m = App::new("myprog")
            .subcommand(App::new("test").long_flag("test")
                .visible_long_flag_alias("testing"))
            .get_matches_from(vec!["myprog", "--testing"]);
assert_eq!(m.subcommand_name(), Some("test"));

pub fn visible_aliases(self, names: &[&'help str]) -> Self

If this App instance is a subcommand, this method adds multiple visible aliases, which allows this 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 App::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

let m = App::new("myprog")
    .subcommand(App::new("test")
        .visible_aliases(&["do-stuff", "tests"]))
    .get_matches_from(vec!["myprog", "do-stuff"]);
assert_eq!(m.subcommand_name(), Some("test"));

pub fn visible_short_flag_aliases(self, names: &[char]) -> Self

Allows adding multiple short flag aliases that functions exactly like those defined with App::short_flag_aliases, except that they are visible inside the help message.

Examples

let m = App::new("myprog")
            .subcommand(App::new("test").short_flag('b')
                .visible_short_flag_aliases(&['t']))
            .get_matches_from(vec!["myprog", "-t"]);
assert_eq!(m.subcommand_name(), Some("test"));

pub fn visible_long_flag_aliases(self, names: &[&'help str]) -> Self

Allows adding multiple long flag aliases that functions exactly like those defined with App::long_flag_aliases, except that they are visible inside the help message.

Examples

let m = App::new("myprog")
            .subcommand(App::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"));

pub fn replace(self, name: &'help str, target: &'help [&'help str]) -> Self

Replaces an argument or subcommand used on the CLI at runtime with other arguments or subcommands.

When this method is used, name is removed from the CLI, and target is inserted in it's 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.

Some examples may help to clear this up.

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 app module. Now let's also assume module also has a subcommand called install which can be invoked app module install. If for some reason users needed to be able to reach app module install via the short-hand app 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 app module install handling code. This is error prone and tedious.

We could instead use App::replace so that, when the user types app install, clap will replace install with module install which will end up getting parsed as if the user typed the entire incantation.

let m = App::new("app")
    .subcommand(App::new("module")
        .subcommand(App::new("install")))
    .replace("install", &["module", "install"])
    .get_matches_from(vec!["app", "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 app --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 App::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!

let m = App::new("app")
    .arg(Arg::new("save-context")
        .long("save-context"))
    .arg(Arg::new("save-runtime")
        .long("save-runtime"))
    .replace("--save-all", &["--save-context", "--save-runtime"])
    .get_matches_from(vec!["app", "--save-all"]);

assert!(m.is_present("save-context"));
assert!(m.is_present("save-runtime"));

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:

let m = App::new("app")
    .arg(Arg::new("save-context")
        .long("save-context"))
    .arg(Arg::new("save-runtime")
        .long("save-runtime"))
    .arg(Arg::new("format")
        .long("format")
        .takes_value(true)
        .possible_values(&["txt", "json"]))
    .replace("--save-all", &["--save-context", "--save-runtime", "--format=json"])
    .get_matches_from(vec!["app", "--save-all"]);

assert!(m.is_present("save-context"));
assert!(m.is_present("save-runtime"));
assert_eq!(m.value_of("format"), Some("json"));

pub fn group(self, group: ArgGroup<'help>) -> Self

Adds an ArgGroup to the application. ArgGroups are a family of related arguments. By placing them in a logical group, you can build easier requirement and exclusion rules. For instance, you can make an entire ArgGroup required, meaning that one (and only one) argument from that group must be present at runtime.

You can also do things such as 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.

Another added benefit of ArgGroups is that you can extract a value from a group instead of determining exactly which argument was used.

Finally, using ArgGroups to ensure exclusion between arguments is another very common use.

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.

App::new("app")
    .arg("--set-ver [ver] 'set the version manually'")
    .arg("--major 'auto increase major'")
    .arg("--minor 'auto increase minor'")
    .arg("--patch 'auto increase patch'")
    .group(ArgGroup::new("vers")
         .args(&["set-ver", "major", "minor","patch"])
         .required(true))

pub fn groups(self, groups: &[ArgGroup<'help>]) -> Self

Adds multiple ArgGroups to the App at once.

Examples

App::new("app")
    .arg("--set-ver [ver] 'set the version manually'")
    .arg("--major         'auto increase major'")
    .arg("--minor         'auto increase minor'")
    .arg("--patch         'auto increase patch'")
    .arg("-c [FILE]       'a config file'")
    .arg("-i [IFACE]      'an interface'")
    .groups(&[
        ArgGroup::new("vers")
            .args(&["set-ver", "major", "minor","patch"])
            .required(true),
        ArgGroup::new("input")
            .args(&["c", "i"])
    ])

pub fn subcommand(self, subcmd: App<'help>) -> Self

Adds a subcommand to the list of valid possibilities. Subcommands are effectively sub-Apps, because they can contain their own arguments, subcommands, version, usage, etc. They also function just like Apps, in that they get their own auto generated help, version, and usage.

Examples

App::new("myprog")
    .subcommand(App::new("config")
        .about("Controls configuration features")
        .arg("<config> 'Required configuration file to use'"))

pub fn subcommands<I>(self, subcmds: I) -> Self where
    I: IntoIterator<Item = App<'help>>, 

Adds multiple subcommands to the list of valid possibilities by iterating over an IntoIterator of Apps.

Examples

.subcommands( vec![
       App::new("config").about("Controls configuration functionality")
                                .arg(Arg::new("config_file").index(1)),
       App::new("debug").about("Controls debug functionality")])

pub fn display_order(self, ord: usize) -> Self

Allows custom ordering of subcommands within the help message. Subcommands with a lower value will be displayed first in the help message. This is helpful when one would like to emphasize frequently used subcommands, or prioritize those towards the top of the list. Duplicate values are allowed. Subcommands with duplicate display orders will be displayed in alphabetical order.

NOTE: The default is 999 for all subcommands.

Examples

let m = App::new("cust-ord")
    .subcommand(App::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(App::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

cust-ord

USAGE:
    cust-ord [FLAGS] [OPTIONS]

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

SUBCOMMANDS:
    beta    I should be first!
    alpha   Some help and text

pub fn mut_arg<T, F>(self, arg_id: T, f: F) -> Self where
    F: FnOnce(Arg<'help>) -> Arg<'help>,
    T: Key + Into<&'help str>, 

Allows one to mutate an Arg after it's been added to an App.

Examples

let mut app = App::new("foo")
    .arg(Arg::new("bar")
        .short('b'))
    .mut_arg("bar", |a| a.short('B'));

let res = app.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 = app.try_get_matches_from_mut(vec!["foo", "-B"]);
assert!(res.is_ok());

pub fn print_help(&mut self) -> Result<()>

Prints the full help message to io::stdout() using a [BufWriter] using the same method as if someone ran -h to request the help message.

NOTE: clap has the ability to distinguish between "short" and "long" help messages depending on if the user ran -h (short) or --help (long).

Examples

let mut app = App::new("myprog");
app.print_help();

pub fn print_long_help(&mut self) -> Result<()>

Prints the full help message to io::stdout() using a BufWriter using the same method as if someone ran --help to request the help message.

NOTE: clap has the ability to distinguish between "short" and "long" help messages depending on if the user ran -h (short) or --help (long).

Examples

let mut app = App::new("myprog");
app.print_long_help();

pub fn write_help<W: Write>(&mut self, w: &mut W) -> Result<()>

Writes the full help message to the user to a io::Write object in the same method as if the user ran -h.

NOTE: clap has the ability to distinguish between "short" and "long" help messages depending on if the user ran -h (short) or --help (long).

Examples

use std::io;
let mut app = App::new("myprog");
let mut out = io::stdout();
app.write_help(&mut out).expect("failed to write to stdout");

pub fn write_long_help<W: Write>(&mut self, w: &mut W) -> Result<()>

Writes the full help message to the user to a io::Write object in the same method as if the user ran --help.

NOTE: clap has the ability to distinguish between "short" and "long" help messages depending on if the user ran -h (short) or --help (long).

Examples

use std::io;
let mut app = App::new("myprog");
let mut out = io::stdout();
app.write_long_help(&mut out).expect("failed to write to stdout");

pub fn render_version(&self) -> String

Returns the version message rendered as if the user ran -V.

NOTE: clap has the ability to distinguish between "short" and "long" version messages depending on if the user ran -V (short) or --version (long).

Coloring

This function does not try to color the message nor it inserts any ANSI escape codes.

Examples

use std::io;
let app = App::new("myprog");
println!("{}", app.render_version());

pub fn render_long_version(&self) -> String

Returns the version message rendered as if the user ran --version.

NOTE: clap has the ability to distinguish between "short" and "long" version messages depending on if the user ran -V (short) or --version (long).

Coloring

This function does not try to color the message nor it inserts any ANSI escape codes.

Examples

use std::io;
let app = App::new("myprog");
println!("{}", app.render_long_version());

pub fn generate_usage(&mut self) -> String

@TODO-v3-alpha @docs @p2: write docs

pub fn get_matches(self) -> ArgMatches

Starts the parsing process, upon a failed parse an error will be displayed to the user and the process will exit with the appropriate error code. By default this method gets all user provided arguments from env::args_os in order to allow for invalid UTF-8 code points, which are legal on many platforms.

Examples

let matches = App::new("myprog")
    // Args and options go here...
    .get_matches();

pub fn get_matches_mut(&mut self) -> ArgMatches

Starts the parsing process, just like App::get_matches but doesn't consume the App.

Examples

let mut app = App::new("myprog")
    // Args and options go here...
    ;
let matches = app.get_matches_mut();

pub fn try_get_matches(self) -> ClapResult<ArgMatches>

Starts the parsing process. This method will return a clap::Result type instead of exiting the process on failed parse. By default this method gets matches from env::args_os.

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.

Examples

let matches = App::new("myprog")
    // Args and options go here...
    .try_get_matches()
    .unwrap_or_else(|e| e.exit());

pub fn get_matches_from<I, T>(self, itr: I) -> ArgMatches where
    I: IntoIterator<Item = T>,
    T: Into<OsString> + Clone, 

Starts the parsing process. Like App::get_matches this method does not return a clap::Result and will automatically exit with an error message. This method, however, lets you specify what iterator to use when performing matches, such as a Vec of your making.

NOTE: The first argument will be parsed as the binary name unless AppSettings::NoBinaryName is used.

Examples

let arg_vec = vec!["my_prog", "some", "args", "to", "parse"];

let matches = App::new("myprog")
    // Args and options go here...
    .get_matches_from(arg_vec);

pub fn try_get_matches_from<I, T>(self, itr: I) -> ClapResult<ArgMatches> where
    I: IntoIterator<Item = T>,
    T: Into<OsString> + Clone, 

Starts the parsing process. A combination of App::get_matches_from, and App::try_get_matches.

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 AppSettings::NoBinaryName is used.

Examples

let arg_vec = vec!["my_prog", "some", "args", "to", "parse"];

let matches = App::new("myprog")
    // Args and options go here...
    .try_get_matches_from(arg_vec)
    .unwrap_or_else(|e| e.exit());

pub fn try_get_matches_from_mut<I, T>(
    &mut self,
    itr: I
) -> ClapResult<ArgMatches> where
    I: IntoIterator<Item = T>,
    T: Into<OsString> + Clone, 

Starts the parsing process without consuming the App struct self. This is normally not the desired functionality, instead prefer App::try_get_matches_from which does consume self.

NOTE: The first argument will be parsed as the binary name unless AppSettings::NoBinaryName is used.

Examples

let arg_vec = vec!["my_prog", "some", "args", "to", "parse"];

let mut app = App::new("myprog");
    // Args and options go here...
let matches = app.try_get_matches_from_mut(arg_vec)
    .unwrap_or_else(|e| e.exit());

pub fn subcommand_placeholder<S, T>(self, placeholder: S, header: T) -> Self where
    S: Into<&'help str>,
    T: Into<&'help str>, 

Sets the placeholder text used for subcommands when printing usage and help. By default, this is "SUBCOMMAND" with a header of "SUBCOMMANDS".

Examples

App::new("myprog")
    .subcommand(App::new("sub1"))
    .print_help()

will produce

myprog

USAGE:
    myprog [SUBCOMMAND]

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

SUBCOMMANDS:
    help    Prints this message or the help of the given subcommand(s)
    sub1

but usage of subcommand_placeholder

App::new("myprog")
    .subcommand(App::new("sub1"))
    .subcommand_placeholder("THING", "THINGS")
    .print_help()

will produce

myprog

USAGE:
    myprog [THING]

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

THINGS:
    help    Prints this message or the help of the given subcommand(s)
    sub1

Trait Implementations

impl<'help> Clone for App<'help>

fn clone(&self) -> App<'help>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'help> Debug for App<'help>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'help> Default for App<'help>

fn default() -> App<'help>

Returns the "default value" for a type.

impl<'_> Display for App<'_>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.