Struct clap::App [] [src]

pub struct App<'a, 'v, 'ab, 'u, 'h, '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, 'h, 'ar> App<'a, 'v, 'ab, 'u, 'h, 'ar>
[src]

fn new(n: &'ar str) -> App<'a, 'v, 'ab, 'u, 'h, '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, 'h, '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, 'h, '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 after_help(self, h: &'h str) -> App<'a, 'v, 'ab, 'u, 'h, 'ar>

Adds additional help information to be displayed in addition to and directly after auto-generated help. This information is displayed after the auto-generated help information. This additional help is often used to describe how to use the arguments, or caveats to be noted.

Example

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

fn subcommands_negate_reqs(self, n: bool) -> App<'a, 'v, 'ab, 'u, 'h, 'ar>

Allows subcommands to override all requirements of the parent (this command). For example if you had a subcommand or even top level application which had a required arguments that is only required if no subcommand is used.

NOTE: This defaults to false (using subcommand does not negate requirements)

Example

.subcommands_negate_reqs(true)

fn error_on_no_subcommand(self, n: bool) -> App<'a, 'v, 'ab, 'u, 'h, 'ar>

Allows specifying that if no subcommand is present at runtime, error and exit gracefully

NOTE: This defaults to false (subcommands do not need to be present)

Example

.subcommands_negate_reqs(true)

fn version(self, v: &'v str) -> App<'a, 'v, 'ab, 'u, 'h, '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, 'h, '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(self, a: Arg<'ar, 'ar, 'ar, 'ar, 'ar, 'ar>) -> App<'a, 'v, 'ab, 'u, 'h, '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, 'h, '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, 'h, '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, 'h, '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 arg_group(self, group: ArgGroup<'ar, 'ar>) -> App<'a, 'v, 'ab, 'u, 'h, 'ar>

Adds an ArgGroup to the application. ArgGroups are a family of related arguments. By placing them in a logical group, you make easier requirement and exclusion rules. For instance, you can make an ArgGroup required, this means that one (and only one) argument from that group must be present. Using more than one argument from an ArgGroup causes a failure (graceful exit).

You can also do things such as name an ArgGroup as a confliction, meaning any of the arguments that belong to that group will cause a failure if present.

Perhaps the most common use of ArgGroups is to require one and only one argument to be present out of a given set. For example, lets say that you were building an application where one could set a given version number by supplying a string using an option argument, such as --set-ver v1.2.3, you also wanted to support automatically using a previous version numer and simply incrementing one of the three numbers, so you create three flags --major, --minor, and --patch. All of these arguments shouldn't be used at one time but perhaps you want to specify that at least one of them is used. You can create a group

Example

.args_from_usage("--set-ver [ver] 'set the version manually'
                  --major         'auto increase major'
                  --minor         'auto increase minor'
                  --patch         'auto increase patch")
.arg_group(ArgGroup::with_name("vers")
                    .add_all(vec!["ver", "major", "minor","patch"])
                    .required(true))

fn arg_groups(self, groups: Vec<ArgGroup<'ar, 'ar>>) -> App<'a, 'v, 'ab, 'u, 'h, 'ar>

Adds a ArgGroups to the application. ArgGroups are a family of related arguments. By placing them in a logical group, you make easier requirement and exclusion rules. For instance, you can make an ArgGroup required, this means that one (and only one) argument from that group must be present. Using more than one argument from an ArgGroup causes a failure (graceful exit).

You can also do things such as name an ArgGroup as a confliction, meaning any of the arguments that belong to that group will cause a failure if present.

Perhaps the most common use of ArgGroups is to require one and only one argument to be present out of a given set. For example, lets say that you were building an application where one could set a given version number by supplying a string using an option argument, such as --set-ver v1.2.3, you also wanted to support automatically using a previous version numer and simply incrementing one of the three numbers, so you create three flags --major, --minor, and --patch. All of these arguments shouldn't be used at one time but perhaps you want to specify that at least one of them is used. You can create a group

Example

.args_from_usage("--set-ver [ver] 'set the version manually'
                  --major         'auto increase major'
                  --minor         'auto increase minor'
                  --patch         'auto increase patch")
.arg_group(ArgGroup::with_name("vers")
                    .add_all(vec!["ver", "major", "minor","patch"])
                    .required(true))

fn subcommand(self, subcmd: App<'a, 'v, 'ab, 'u, 'h, 'ar>) -> App<'a, 'v, 'ab, 'u, 'h, '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, 'h, 'ar>>) -> App<'a, 'v, 'ab, 'u, 'h, '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, 'ar>