Struct clap::App [] [src]

pub struct App<'a, 'v, 'ab, 'u, 'ar> {
    // some fields omitted
}

Used to create a representation of a command line program and all possible command line arguments for parsing at runtime.

Application settings are set using the "builder pattern" with .get_matches() being the terminal method that starts the runtime-parsing process and returns information about the user supplied arguments (or lack there of).

The options set for the application are not mandatory, and may appear in any order (so long as .get_matches() is last).

Example

let myprog = App::new("myprog")
                  .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)
                       // Add other possible command line argument options here...
                   )
                  .get_matches();

// Your pogram logic starts here...

Methods

impl<'a, 'v, 'ab, 'u, 'ar> App<'a, 'v, 'ab, 'u, 'ar>
[src]

fn new<'n>(n: &'n str) -> App<'a, 'v, 'ab, 'u, 'ar>

Creates a new instance of an application requiring a name (such as the binary). The name will be displayed to the user when they request to print version or help and usage information. The name should not contain spaces (hyphens '-' are ok).

Example

let prog = App::new("myprog")

fn author(self, a: &'a str) -> App<'a, 'v, 'ab, 'u, 'ar>

Sets a string of author(s) and will be displayed to the user when they request the version or help information.

Example

.author("Kevin <kbknapp@gmail.com>")

fn about(self, a: &'ab str) -> App<'a, 'v, 'ab, 'u, 'ar>

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

Example

.about("Does really amazing things to great people")

fn version(self, v: &'v str) -> App<'a, 'v, 'ab, 'u, 'ar>

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

Example

.version("v0.1.24")

fn usage(self, u: &'u str) -> App<'a, 'v, 'ab, 'u, 'ar>

Sets a custom usage string to over-ride the auto-generated usage string. Will be displayed to the user when errors are found in argument parsing, or when you call ArgMatches::usage()

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.

Example

.usage("myapp [-clDas] <some_file>")

fn arg<'l, 'h, 'b, 'r>(self, a: Arg<'ar, 'ar, 'ar, 'ar, 'ar, 'ar>) -> App<'a, 'v, 'ab, 'u, 'ar>

Adds an argument to the list of valid possibilties manually. This method allows you full control over the arguments settings and options (as well as dynamic generation). It also allows you specify several more advanced configuration options such as relational rules (exclusions and requirements).

The only disadvantage to this method is that it's more verbose, and arguments must be added one at a time. Using Arg::from_usage helps with the verbosity, and still allows full control over the advanced configuration options.

Example

// 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 configuration file to use'"))

fn args(self, args: Vec<Arg<'ar, 'ar, 'ar, 'ar, 'ar, 'ar>>) -> App<'a, 'v, 'ab, 'u, 'ar>

Adds multiple arguments to the list of valid possibilties by iterating over a Vec of Args

Example

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

fn arg_from_usage(self, usage: &'ar str) -> App<'a, 'v, 'ab, 'u, 'ar>

A convienience method for adding a single basic argument (one without advanced relational rules) from a usage type string. The string used follows the same rules and syntax as Arg::from_usage()

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.

Example

.arg_from_usage("-c --conf=<config> 'Sets a configuration file to use'")

fn args_from_usage(self, usage: &'ar str) -> App<'a, 'v, 'ab, 'u, 'ar>

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

Like App::arg_from_usage() the downside is you only set properties for the Args which Arg::from_usage() supports. But here the benefit is pretty strong, as the readability is greatly enhanced, especially if you don't need any of the more advanced configuration options.

Example

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

fn subcommand(self, subcmd: App<'a, 'v, 'ab, 'u, 'ar>) -> App<'a, 'v, 'ab, 'u, 'ar>

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.

Example

.subcommand(SubCommand::new("config")
               .about("Controls configuration features")
               .arg_from_usage("<config> 'Required configuration file to use'"))
            // Additional subcommand configuration goes here, such as other arguments...

fn subcommands(self, subcmds: Vec<App<'a, 'v, 'ab, 'u, 'ar>>) -> App<'a, 'v, 'ab, 'u, 'ar>

Adds multiple subcommands to the list of valid possibilties by iterating over a Vec of SubCommands

Example

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

fn get_matches(self) -> ArgMatches<'ar>