Struct clap::AppCopy item path

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

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

See the examples/ directory for more information

§Examples

App::new("myprog")
     .author("Me, me@mymain.com")

Overrides the system-determined binary name. This should only be used when absolutely neccessary, 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 SubCommands.

§Examples

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

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

§Examples

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

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

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

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

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

Sets a custom usage string to override the auto-generated usage string.

This will be displayed to the user when errors are found in argument parsing, or when you call ArgMatches::usage

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: You do not need to specify the “USAGE: \n\t” portion, as that will still be applied by clap, you only need to specify the portion starting with the binary name.

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

§Examples

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

Sets a custom help message and overrides the auto-generated one. 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::help for them as well.

§Examples

App::new("myapp")
    .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")

Sets the short for the auto-generated help argument.

By default clap automatically assigns h, but this can be overridden if you have a different argument which you’d prefer to use the -h short with. This can be done by defining your own argument with a lowercase h as the short.

clap lazily generates these help arguments after you’ve defined any arguments of your own.

NOTE: Any leading - characters will be stripped, and only the first non - character will be used as the short version

§Examples

App::new("myprog")
    .help_short("H") // Using an uppercase `H` instead of the default lowercase `h`

Sets the short for the auto-generated version argument.

By default clap automatically assigns V, but this can be overridden if you have a different argument which you’d prefer to use the -V short with. This can be done by defining your own argument with an uppercase V as the short.

clap lazily generates these version arguments after you’ve defined any arguments of your own.

NOTE: Any leading - characters will be stripped, and only the first non - character will be used as the short version

§Examples

App::new("myprog")
    .version_short("v") // Using a lowercase `v` instead of the default capital `V`

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. * {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. * {flags} - Help for flags. * {options} - Help for options. * {positionals} - Help for positionals arguments. * {subcommands} - Help for subcommands. * {after-help} - Help for flags.

§Examples

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

**NOTE:**The template system is, on purpose, very simple. Therefore the tags have to writen in the lowercase and without spacing.

Enables a single command, or SubCommand, level settings.

See AppSettings for a full list of possibilities and examples.

§Examples

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

Enables multiple command, or SubCommand, level settings

See AppSettings for a full list of possibilities and examples.

§Examples

App::new("myprog")
    .settings(&[AppSettings::SubcommandRequired,
                 AppSettings::WaitOnError])

Enables a single setting that is propogated down through all child SubCommands.

See AppSettings for a full list of possibilities and examples.

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

§Examples

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

Enables multiple settings which are propogated down through all child SubCommands.

See AppSettings for a full list of possibilities and examples.

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

§Examples

App::new("myprog")
    .global_settings(&[AppSettings::SubcommandRequired,
                 AppSettings::ColoredHelp])

Disables a single command, or SubCommand, level setting.

See AppSettings for a full list of possibilities and examples.

§Examples

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

Disables multiple command, or SubCommand, level settings.

See AppSettings for a full list of possibilities and examples.

§Examples

App::new("myprog")
    .unset_settings(&[AppSettings::ColorAuto,
                      AppSettings::AllowInvalidUtf8])

Sets the terminal width at which to wrap help messages. Defaults to 120.

clap automatically tries to determine the terminal width on Unix, Linux, and OSX 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, and OSX 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)

Adds an argument to the list of valid possibilties.

§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_usage()
    .arg(
        Arg::from_usage("-c --config=[CONFIG] 'Optionally sets a config file to use'")
    )

Adds multiple arguments to the list of valid possibilties

§Examples

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

A convenience method for adding a single [argument] from a usage type string. The string used follows the same rules and syntax as Arg::from_usage

NOTE: The downside to using this method is that you can not set any additional properties of the Arg other than what Arg::from_usage supports.

§Examples

App::new("myprog")
    .arg_from_usage("-c --config=<FILE> 'Sets a configuration file to use'")

Adds multiple arguments at once from a usage string, one per line. See Arg::from_usage for details on the syntax and rules supported.

NOTE: Like App::arg_from_usage the downside is you only set properties for the Args which Arg::from_usage supports.

§Examples

App::new("myprog")
    .args_from_usage(
        "-c --config=[FILE] 'Sets a configuration file to use'
         [debug]... -d 'Sets the debugging level'
         <FILE> 'The input file to use'"
    )

Allows adding a SubCommand 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(SubCommand::with_name("test")
                .alias("do-stuff"))
            .get_matches_from(vec!["myprog", "do-stuff"]);
assert_eq!(m.subcommand_name(), Some("test"));

Allows adding SubCommand 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(SubCommand::with_name("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"));

Allows adding a SubCommand 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(SubCommand::with_name("test")
                .visible_alias("do-stuff"))
            .get_matches_from(vec!["myprog", "do-stuff"]);
assert_eq!(m.subcommand_name(), Some("test"));

Allows adding multiple SubCommand 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(SubCommand::with_name("test")
                .visible_aliases(&["do-stuff", "tests"]))
            .get_matches_from(vec!["myprog", "do-stuff"]);
assert_eq!(m.subcommand_name(), Some("test"));

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 benfit 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")
    .args_from_usage(
        "--set-ver [ver] 'set the version manually'
         --major         'auto increase major'
         --minor         'auto increase minor'
         --patch         'auto increase patch'")
    .group(ArgGroup::with_name("vers")
         .args(&["set-ver", "major", "minor","patch"])
         .required(true))

Adds multiple ArgGroups to the App at once.

§Examples

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

Adds a SubCommand to the list of valid possibilties. 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(SubCommand::with_name("config")
        .about("Controls configuration features")
        .arg_from_usage("<config> 'Required configuration file to use'"))

Adds multiple subcommands to the list of valid possibilties by iterating over an IntoIterator of SubCommands

§Examples

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

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 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(SubCommand::with_name("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(SubCommand::with_name("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

Prints the full help message to io::stdout() using a BufWriter

§Examples

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

Writes the full help message to the user to a io::Write object

§Examples

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

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

§Examples

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

Generate a completions file for a specified shell at compile time.

NOTE: to generate the this file at compile time you must use a build.rs “Build Script”

§Examples

The following example generates a bash completion script via a build.rs script. In this simple example, we’ll demo a very small application with only a single subcommand and two args. Real applications could be many multiple levels deep in subcommands, and have tens or potentiall hundreds of arguments.

First, it helps if we separate out our App definition into a seperate file. Whether you do this as a function, or bare App definition is a matter of personal preference.

// src/cli.rs

use clap::{App, Arg, SubCommand};

pub fn build_cli() -> App<'static, 'static> {
    App::new("compl")
        .about("Tests completions")
        .arg(Arg::with_name("file")
            .help("some input file"))
        .subcommand(SubCommand::with_name("test")
            .about("tests things")
            .arg(Arg::with_name("case")
                .long("case")
                .takes_value(true)
                .help("the case to test")))
}

In our regular code, we can simply call this build_cli() function, then call get_matches(), or any of the other normal methods directly after. For example:

// src/main.rs

mod cli;

fn main() {
    let m = cli::build_cli().get_matches();

    // normal logic continues...
}

Next, we set up our Cargo.toml to use a build.rs build script.

build = "build.rs"

[build-dependencies]
clap = "2.9"

Next, we place a build.rs in our project root.

extern crate clap;

use clap::Shell;

include!("src/cli.rs");

fn main() {
    let mut app = build_cli();
    app.gen_completions("myapp",          // We need to specify the bin name manually
                        Shell::Bash,      // Then say which shell to build completions for
                        env!("OUT_DIR")); // Then say where write the completions to
}

Now, once we combile there will be a bash.sh file in the directory. Assuming we compiled with debug mode, it would be somewhere similar to <project>/target/debug/build/myapp-<hash>/out/myapp_bash.sh

Generate a completions file for a specified shell at runtime. Until cargo install can install extra files like a completion script, this may be used e.g. in a command that outputs the contents of the completion script, to be redirected into a file by the user.

§Examples

Assuming a separate cli.rs like the example above, we can let users generate a completion script using a command:

// src/main.rs

mod cli;
use std::io;

fn main() {
    let matches = cli::build_cli().get_matches();

    if matches.is_present("generate-bash-completions") {
        cli::build_cli().gen_completions_to("myapp", Shell::Bash, &mut io::stdout());
    }

    // normal logic continues...
}

Usage:

$ myapp generate-bash-completions > /etc/bash_completion.d/myapp

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

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...
    .get_matches_safe()
    .unwrap_or_else( |e| e.exit() );

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

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

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

Starts the parsing process without consuming the App struct self. This is normally not the desired functionality, instead prefer App::get_matches_from_safe 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.get_matches_from_safe_borrow(arg_vec)
    .unwrap_or_else( |e| { panic!("An error occurs: {}", e) });

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.