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 Arg
s 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 SubCommand
s
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")])