Struct App

Source

pub struct App<'b> { /* private fields */ }

Expand description

Used to create a representation of a command line program and all possible command line arguments. Application settings are set using the “builder pattern” with the App::get_matches family of methods being the terminal methods that starts the runtime-parsing process. These methods then return information about the user supplied arguments (or lack there of).

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, me@mail.com")
    .version("1.0.2")
    .about("Explains in brief what the program does")
    .arg(
        Arg::with_name("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§

Source §

impl<'b> App<'b>

Source

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

Creates a new instance of an application requiring a name. The name may be, but doesn’t have to be, same as the binary. The name will be displayed to the user when they request to print version or help and usage information.

§Examples

let prog = App::new("My Program")

Source

pub fn get_name(&self) -> &str

Get the name of the app

Source

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

Get the name of the binary

Source

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

Sets a string of author(s) that will be displayed to the user when they request the help information with --help or -h.

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, me@mymain.com")

Source

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

Overrides the system-determined binary name. 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 command should not be used for ``s.

§Examples

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

Source

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

Sets a string describing what the program does. This will be displayed when displaying help information with -h.

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

NOTE: Only App::about is used in completion script generation in order to be concise

§Examples

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

Source

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

Sets a string describing what the program does. This will be displayed when displaying help information.

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

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

Source

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

Sets the program’s name. This will be displayed when displaying help information.

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 yml = load_yaml!("app.yml");
let app = App::from_yaml(yml)
    .name(crate_name!());

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

Source

pub fn after_help<S: Into<&'b 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. This is often used to describe how to use the arguments, or caveats to be noted.

§Examples

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

Source

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

Adds additional help information to be displayed in addition to auto-generated help. This information is displayed before the auto-generated help information. This is often used for header information.

§Examples

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

Source

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

Sets a string of the version number to be displayed when displaying version or help information with -V.

NOTE: If only version is provided, and not App::long_version but the user requests --version clap will still display the contents of version appropriately

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

§Examples

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

Source

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

Sets a string of the version number to be displayed when displaying version or help information with --version.

NOTE: If only long_version is provided, and not App::version but the user requests -V clap will still display the contents of long_version appropriately

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

§Examples

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

Source

pub fn override_usage<S: Into<&'b 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>")

Source

pub fn override_help<S: Into<&'b 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) me@mail.com\n\n\

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

           Options:\n\
           -h, --helpe      Dispay 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")

Source

pub fn help_template<S: Into<&'b str>>(self, s: S) -> Self

Sets the help template to be used, overriding the default format.

Tags arg given inside curly brackets.

Valid tags are:

{bin} - Binary name.
{version} - Version number.
{author} - Author information.
{about} - General description (from App::about)
{usage} - Automatically generated or given usage string.
{all-args} - Help for all arguments (options, flags, positionals 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 positionals arguments.
{subcommands} - Help for subcommands.
{after-help} - Help from App::after_help
{before-help} - Help from App::before_help

§Examples

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

**NOTE:**The template system is, on purpose, very simple. Therefore the tags have to be written in the lowercase and without spacing. App::about: ./struct.App.html#method.about App::after_help: ./struct.App.html#method.after_help App::before_help: ./struct.App.html#method.before_help AppSettings::UnifiedHelpMessage: ./enum.AppSettings.html#variant.UnifiedHelpMessage

Source

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

Enables a single command, or ``, level settings.

See AppSettings for a full list of possibilities and examples.

§Examples

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

Source

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

Disables a single command, or ``, level setting.

See AppSettings for a full list of possibilities and examples.

§Examples

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

Source

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)

Source

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)

Source

pub fn set_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 used while compiling. If the terminal width cannot be determined, clap defaults to 120.

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")
    .set_term_width(80)

Source

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

Sets the max 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 used while compiling, but one might want to limit the size (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)

Source

pub fn arg<A: Into<Arg<'b>>>(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::with_name()
    .arg(
        Arg::with_name("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::from("-c --config=[CONFIG] 'Optionally sets a config file to use'")
    )

Source

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

Set a custom section heading for future args. Every call to arg will have this header (instead of its default header) until a subsequent call to help_heading

Source

pub fn stop_custom_headings(self) -> Self

Stop using custom section headings.

Source

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

Adds multiple arguments to the list of valid possibilities.

§Examples

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

Source

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

Allows adding a `` alias, which function as “hidden” 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")
                .alias("do-stuff"))
            .get_matches_from(vec!["myprog", "do-stuff"]);
assert_eq!(m.subcommand_name(), Some("test"));

Source

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

Allows adding `` aliases, which function as “hidden” 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")
                .aliases(&["do-stuff", "do-tests", "tests"]))
                .arg(Arg::with_name("input")
                            .help("the file to add")
                            .index(1)
                            .required(false))
            .get_matches_from(vec!["myprog", "do-tests"]);
assert_eq!(m.subcommand_name(), Some("test"));

Source

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

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

§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"));

Source

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

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

§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"));

Source

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

Replaces an argument to this application with other arguments.

Below, when the given args are app install, they will be changed to app module install.

§Examples

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

Source

pub fn group(self, group: ArgGroup<'b>) -> 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::with_name("vers")
         .args(&["set-ver", "major", "minor","patch"])
         .required(true))

Source

pub fn groups(self, groups: &[ArgGroup<'b>]) -> 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::with_name("vers")
            .args(&["set-ver", "major", "minor","patch"])
            .required(true),
        ArgGroup::with_name("input")
            .args(&["c", "i"])
    ])

Source

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

Adds a `` 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'"))

Source

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

Adds multiple subcommands to the list of valid possibilities by iterating over an IntoIterator of ``s

§Examples

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

Source

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

Allows custom ordering of ``s 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 emphasise 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

Source

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

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

§Examples


let mut app = App::new("foo")
    .arg(Arg::with_name("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());

Source

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

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();

Source

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

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();

Source

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

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");

Source

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

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");

Source

pub fn write_version<W: Write>(&self, w: &mut W) -> ClapResult<()>

Writes the version message to the user to a io::Write object 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)

§Examples

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

Source

pub fn write_long_version<W: Write>(&self, w: &mut W) -> ClapResult<()>

Writes the version message to the user to a io::Write object

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

§Examples

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

Source

pub fn generate_usage(&mut self) -> String

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

Source

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();

Source

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();

Source

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::HelpDisplayed or ErrorKind::VersionDisplayed 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() );

Source

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

Source

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::HelpDisplayed or ErrorKind::VersionDisplayed 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| { panic!("An error occurs: {}", e) });

Source

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| { panic!("An error occurs: {}", e) });