Macro clap::clap_app

source · [−]

macro_rules! clap_app {
    (@app ($builder:expr)) => { ... };
    (@app ($builder:expr) (@arg ($name:expr): $($tail:tt)*) $($tt:tt)*) => { ... };
    (@app ($builder:expr) (@arg $name:literal: $($tail:tt)*) $($tt:tt)*) => { ... };
    (@app ($builder:expr) (@arg $name:ident: $($tail:tt)*) $($tt:tt)*) => { ... };
    (@app ($builder:expr) (@global_setting $setting:ident) $($tt:tt)*) => { ... };
    (@app ($builder:expr) (@setting $setting:ident) $($tt:tt)*) => { ... };
    (@app ($builder:expr) (@attributes $($attr:tt)*) $($tt:tt)*) => { ... };
    (@app ($builder:expr) (@group $name:ident: $($attrs:tt)*) $($tt:tt)*) => { ... };
    (@app ($builder:expr) (@subcommand ($name:expr) => $($tail:tt)*) $($tt:tt)*) => { ... };
    (@app ($builder:expr) (@subcommand $name:literal => $($tail:tt)*) $($tt:tt)*) => { ... };
    (@app ($builder:expr) (@subcommand $name:ident => $($tail:tt)*) $($tt:tt)*) => { ... };
    (@app ($builder:expr) ($ident:ident: $($v:expr),*) $($tt:tt)*) => { ... };
    (@group ($builder:expr, $group:expr)) => { ... };
    (@group ($builder:expr, $group:expr) (@attributes $($attr:tt)*) $($tt:tt)*) => { ... };
    (@group ($builder:expr, $group:expr) (@arg ($name:expr): $($tail:tt)*) $($tt:tt)*) => { ... };
    (@group ($builder:expr, $group:expr) (@arg $name:literal: $($tail:tt)*) $($tt:tt)*) => { ... };
    (@group ($builder:expr, $group:expr) (@arg $name:ident: $($tail:tt)*) $($tt:tt)*) => { ... };
    (@group ($builder:expr, $group:expr) !$ident:ident $($tail:tt)*) => { ... };
    (@group ($builder:expr, $group:expr) +$ident:ident $($tail:tt)*) => { ... };
    (@group ($builder:expr, $group:expr) * $($tail:tt)*) => { ... };
    (@group ($builder:expr, $group:expr) ... $($tail:tt)*) => { ... };
    (@group ($builder:expr, $group:expr) $ident:ident[$($target:literal)*] $($tail:tt)*) => { ... };
    (@group ($builder:expr, $group:expr) $ident:ident[$($target:ident)*] $($tail:tt)*) => { ... };
    (@group ($builder:expr, $group:expr) $ident:ident($($expr:expr),*) $($tail:tt)*) => { ... };
    (@group ($builder:expr, $group:expr) $ident:ident($($expr:expr,)*) $($tail:tt)*) => { ... };
    (@arg ($arg:expr) $modes:tt) => { ... };
    (@arg ($arg:expr) $modes:tt --($long:expr) $($tail:tt)*) => { ... };
    (@arg ($arg:expr) $modes:tt --$long:literal $($tail:tt)*) => { ... };
    (@arg ($arg:expr) $modes:tt --$long:ident $($tail:tt)*) => { ... };
    (@arg ($arg:expr) $modes:tt -($short:expr) $($tail:tt)*) => { ... };
    (@arg ($arg:expr) $modes:tt -$short:literal $($tail:tt)*) => { ... };
    (@arg ($arg:expr) $modes:tt -$short:ident $($tail:tt)*) => { ... };
    (@arg ($arg:expr) (-) <$var:ident> $($tail:tt)*) => { ... };
    (@arg ($arg:expr) (+) <$var:ident> $($tail:tt)*) => { ... };
    (@arg ($arg:expr) (-) [$var:ident] $($tail:tt)*) => { ... };
    (@arg ($arg:expr) (+) [$var:ident] $($tail:tt)*) => { ... };
    (@arg ($arg:expr) $modes:tt ... $($tail:tt)*) => { ... };
    (@arg ($arg:expr) $modes:tt #{$n:expr, $m:expr} $($tail:tt)*) => { ... };
    (@arg ($arg:expr) $modes:tt * $($tail:tt)*) => { ... };
    (@arg ($arg:expr) $modes:tt !$ident:ident $($tail:tt)*) => { ... };
    (@arg ($arg:expr) $modes:tt +$ident:ident $($tail:tt)*) => { ... };
    (@arg ($arg:expr) $modes:tt {$fn_:expr} $($tail:tt)*) => { ... };
    (@as_expr $expr:expr) => { ... };
    (@arg ($arg:expr) $modes:tt $desc:tt) => { ... };
    (@arg ($arg:expr) $modes:tt $ident:ident[$($target:literal)*] $($tail:tt)*) => { ... };
    (@arg ($arg:expr) $modes:tt $ident:ident[$($target:ident)*] $($tail:tt)*) => { ... };
    (@arg ($arg:expr) $modes:tt $ident:ident($($expr:expr),*) $($tail:tt)*) => { ... };
    (@arg ($arg:expr) $modes:tt $ident:ident($($expr:expr,)*) $($tail:tt)*) => { ... };
    (@subcommand ($name:expr) => $($tail:tt)*) => { ... };
    (@subcommand $name:literal => $($tail:tt)*) => { ... };
    (@subcommand $name:ident => $($tail:tt)*) => { ... };
    (($name:expr) => $($tail:tt)*) => { ... };
    ($name:literal => $($tail:tt)*) => { ... };
    ($name:ident => $($tail:tt)*) => { ... };
}

Expand description

Build App, Arg and Group with Usage-string like input but without the associated parsing runtime cost.

clap_app! also supports several shorthand syntaxes.

Examples

let matches = clap_app!(myapp =>
    (version: "1.0")
    (author: "Kevin K. <kbknapp@gmail.com>")
    (about: "Does awesome things")
    (@arg CONFIG: -c --config +takes_value "Sets a custom config file")
    (@arg INPUT: +required "Sets the input file to use")
    (@arg debug: -d ... "Sets the level of debugging information")
    (@group difficulty: +required !multiple
        (@arg hard: -h --hard "Sets hard mode")
        (@arg normal: -n --normal "Sets normal mode")
        (@arg easy: -e --easy "Sets easy mode")
    )
    (@subcommand test =>
        (about: "controls testing features")
        (version: "1.3")
        (author: "Someone E. <someone_else@other.com>")
        (@arg verbose: -v --verbose "Print test information verbosely")
    )
)
.get_matches();

Shorthand Syntax for Args

A single hyphen followed by a character (such as -c) sets the Arg::short
A double hyphen followed by a character or word (such as --config) sets Arg::long
Three dots (...) sets Arg::multiple_values(true)
Three dots (...) sets Arg::multiple_occurrences(true)
Angled brackets after either a short or long will set Arg::value_name and Arg::required(true) such as --config <FILE> = Arg::value_name("FILE") and Arg::required(true)
Square brackets after either a short or long will set Arg::value_name and Arg::required(false) such as --config [FILE] = Arg::value_name("FILE") and Arg::required(false)
There are short hand syntaxes for Arg methods that accept booleans
- A plus sign will set that method to true such as +required = Arg::required(true)
- An exclamation will set that method to false such as !required = Arg::required(false)
A #{min, max} will set Arg::min_values(min) and Arg::max_values(max)
An asterisk (*) will set Arg::required(true)
Curly brackets around a fn will set Arg::validator as in {fn} = Arg::validator(fn)
An Arg method that accepts a string followed by square brackets will set that method such as conflicts_with[FOO] will set Arg::conflicts_with("FOO") (note the lack of quotes around FOO in the macro)
An Arg method that takes a string and can be set multiple times (such as Arg::conflicts_with) followed by square brackets and a list of values separated by spaces will set that method such as conflicts_with[FOO BAR BAZ] will set Arg::conflicts_with("FOO"), Arg::conflicts_with("BAR"), and Arg::conflicts_with("BAZ") (note the lack of quotes around the values in the macro)

Shorthand Syntax for Groups

Some shorthand syntaxes for Arg are also available for ArgGroup:
- For methods accepting a boolean: +required and !multiple, etc.
- For methods accepting strings: conflicts_with[FOO] and conflicts_with[FOO BAR BAZ], etc.
- * for ArgGroup::required
- ... for ArgGroup::multiple

Alternative form for non-ident values

Certain places that normally accept an ident also optionally accept an alternative of ("expr enclosed by parens")

(@arg something: --something) could also be (@arg ("something-else"): --("something-else"))
(@subcommand something => ...) could also be (@subcommand ("something-else") => ...)

Or it can be even simpler by using the literal directly

(@arg "something-else": --"something-else")
(@subcommand "something-else" => ...)