1 /// A convenience macro for loading the YAML file at compile time (relative to the current file, 2 /// like modules work). That YAML object can then be passed to this function. 3 /// 4 /// # Panics 5 /// 6 /// The YAML file must be properly formatted or this function will panic!(). A good way to 7 /// ensure this doesn't happen is to run your program with the `--help` switch. If this passes 8 /// without error, you needn't worry because the YAML is properly formatted. 9 /// 10 /// # Examples 11 /// 12 /// The following example shows how to load a properly formatted YAML file to build an instance 13 /// of an `App` struct. 14 /// 15 /// ```ignore 16 /// # #[macro_use] 17 /// # extern crate clap; 18 /// # use clap::App; 19 /// # fn main() { 20 /// let yml = load_yaml!("app.yml"); 21 /// let app = App::from_yaml(yml); 22 /// 23 /// // continued logic goes here, such as `app.get_matches()` etc. 24 /// # } 25 /// ``` 26 #[cfg(feature = "yaml")] 27 #[macro_export] 28 macro_rules! load_yaml { 29 ($yml:expr) => ( 30 &::clap::YamlLoader::load_from_str(include_str!($yml)).expect("failed to load YAML file")[0] 31 ); 32 } 33 34 /// Convenience macro getting a typed value `T` where `T` implements [`std::str::FromStr`] from an 35 /// argument value. This macro returns a `Result<T,String>` which allows you as the developer to 36 /// decide what you'd like to do on a failed parse. There are two types of errors, parse failures 37 /// and those where the argument wasn't present (such as a non-required argument). You can use 38 /// it to get a single value, or a iterator as with the [`ArgMatches::values_of`] 39 /// 40 /// # Examples 41 /// 42 /// ```no_run 43 /// # #[macro_use] 44 /// # extern crate clap; 45 /// # use clap::App; 46 /// # fn main() { 47 /// let matches = App::new("myapp") 48 /// .arg_from_usage("[length] 'Set the length to use as a pos whole num, i.e. 20'") 49 /// .get_matches(); 50 /// 51 /// let len = value_t!(matches.value_of("length"), u32).unwrap_or_else(|e| e.exit()); 52 /// let also_len = value_t!(matches, "length", u32).unwrap_or_else(|e| e.exit()); 53 /// 54 /// println!("{} + 2: {}", len, len + 2); 55 /// # } 56 /// ``` 57 /// [`std::str::FromStr`]: https://doc.rust-lang.org/std/str/trait.FromStr.html 58 /// [`ArgMatches::values_of`]: ./struct.ArgMatches.html#method.values_of 59 /// [`Result<T,String>`]: https://doc.rust-lang.org/std/result/enum.Result.html 60 #[macro_export] 61 macro_rules! value_t { 62 ($m:ident, $v:expr, $t:ty) => { 63 value_t!($m.value_of($v), $t) 64 }; 65 ($m:ident.value_of($v:expr), $t:ty) => { 66 if let Some(v) = $m.value_of($v) { 67 match v.parse::<$t>() { 68 Ok(val) => Ok(val), 69 Err(_) => 70 Err(::clap::Error::value_validation_auto( 71 format!("The argument '{}' isn't a valid value", v))), 72 } 73 } else { 74 Err(::clap::Error::argument_not_found_auto($v)) 75 } 76 }; 77 } 78 79 /// Convenience macro getting a typed value `T` where `T` implements [`std::str::FromStr`] or 80 /// exiting upon error, instead of returning a [`Result`] type. 81 /// 82 /// **NOTE:** This macro is for backwards compatibility sake. Prefer 83 /// [`value_t!(/* ... */).unwrap_or_else(|e| e.exit())`] 84 /// 85 /// # Examples 86 /// 87 /// ```no_run 88 /// # #[macro_use] 89 /// # extern crate clap; 90 /// # use clap::App; 91 /// # fn main() { 92 /// let matches = App::new("myapp") 93 /// .arg_from_usage("[length] 'Set the length to use as a pos whole num, i.e. 20'") 94 /// .get_matches(); 95 /// 96 /// let len = value_t_or_exit!(matches.value_of("length"), u32); 97 /// let also_len = value_t_or_exit!(matches, "length", u32); 98 /// 99 /// println!("{} + 2: {}", len, len + 2); 100 /// # } 101 /// ``` 102 /// [`std::str::FromStr`]: https://doc.rust-lang.org/std/str/trait.FromStr.html 103 /// [`Result`]: https://doc.rust-lang.org/std/result/enum.Result.html 104 /// [`value_t!(/* ... */).unwrap_or_else(|e| e.exit())`]: ./macro.value_t!.html 105 #[macro_export] 106 macro_rules! value_t_or_exit { 107 ($m:ident, $v:expr, $t:ty) => { 108 value_t_or_exit!($m.value_of($v), $t) 109 }; 110 ($m:ident.value_of($v:expr), $t:ty) => { 111 if let Some(v) = $m.value_of($v) { 112 match v.parse::<$t>() { 113 Ok(val) => val, 114 Err(_) => 115 ::clap::Error::value_validation_auto( 116 format!("The argument '{}' isn't a valid value", v)).exit(), 117 } 118 } else { 119 ::clap::Error::argument_not_found_auto($v).exit() 120 } 121 }; 122 } 123 124 /// Convenience macro getting a typed value [`Vec<T>`] where `T` implements [`std::str::FromStr`] 125 /// This macro returns a [`clap::Result<Vec<T>>`] which allows you as the developer to decide 126 /// what you'd like to do on a failed parse. 127 /// 128 /// # Examples 129 /// 130 /// ```no_run 131 /// # #[macro_use] 132 /// # extern crate clap; 133 /// # use clap::App; 134 /// # fn main() { 135 /// let matches = App::new("myapp") 136 /// .arg_from_usage("[seq]... 'A sequence of pos whole nums, i.e. 20 45'") 137 /// .get_matches(); 138 /// 139 /// let vals = values_t!(matches.values_of("seq"), u32).unwrap_or_else(|e| e.exit()); 140 /// for v in &vals { 141 /// println!("{} + 2: {}", v, v + 2); 142 /// } 143 /// 144 /// let vals = values_t!(matches, "seq", u32).unwrap_or_else(|e| e.exit()); 145 /// for v in &vals { 146 /// println!("{} + 2: {}", v, v + 2); 147 /// } 148 /// # } 149 /// ``` 150 /// [`std::str::FromStr`]: https://doc.rust-lang.org/std/str/trait.FromStr.html 151 /// [`Vec<T>`]: https://doc.rust-lang.org/std/vec/struct.Vec.html 152 /// [`clap::Result<Vec<T>>`]: ./type.Result.html 153 #[macro_export] 154 macro_rules! values_t { 155 ($m:ident, $v:expr, $t:ty) => { 156 values_t!($m.values_of($v), $t) 157 }; 158 ($m:ident.values_of($v:expr), $t:ty) => { 159 if let Some(vals) = $m.values_of($v) { 160 let mut tmp = vec![]; 161 let mut err = None; 162 for pv in vals { 163 match pv.parse::<$t>() { 164 Ok(rv) => tmp.push(rv), 165 Err(..) => { 166 err = Some(::clap::Error::value_validation_auto( 167 format!("The argument '{}' isn't a valid value", pv))); 168 break 169 } 170 } 171 } 172 match err { 173 Some(e) => Err(e), 174 None => Ok(tmp), 175 } 176 } else { 177 Err(::clap::Error::argument_not_found_auto($v)) 178 } 179 }; 180 } 181 182 /// Convenience macro getting a typed value [`Vec<T>`] where `T` implements [`std::str::FromStr`] 183 /// or exiting upon error. 184 /// 185 /// **NOTE:** This macro is for backwards compatibility sake. Prefer 186 /// [`values_t!(/* ... */).unwrap_or_else(|e| e.exit())`] 187 /// 188 /// # Examples 189 /// 190 /// ```no_run 191 /// # #[macro_use] 192 /// # extern crate clap; 193 /// # use clap::App; 194 /// # fn main() { 195 /// let matches = App::new("myapp") 196 /// .arg_from_usage("[seq]... 'A sequence of pos whole nums, i.e. 20 45'") 197 /// .get_matches(); 198 /// 199 /// let vals = values_t_or_exit!(matches.values_of("seq"), u32); 200 /// for v in &vals { 201 /// println!("{} + 2: {}", v, v + 2); 202 /// } 203 /// 204 /// // type for example only 205 /// let vals: Vec<u32> = values_t_or_exit!(matches, "seq", u32); 206 /// for v in &vals { 207 /// println!("{} + 2: {}", v, v + 2); 208 /// } 209 /// # } 210 /// ``` 211 /// [`values_t!(/* ... */).unwrap_or_else(|e| e.exit())`]: ./macro.values_t!.html 212 /// [`std::str::FromStr`]: https://doc.rust-lang.org/std/str/trait.FromStr.html 213 /// [`Vec<T>`]: https://doc.rust-lang.org/std/vec/struct.Vec.html 214 #[macro_export] 215 macro_rules! values_t_or_exit { 216 ($m:ident, $v:expr, $t:ty) => { 217 values_t_or_exit!($m.values_of($v), $t) 218 }; 219 ($m:ident.values_of($v:expr), $t:ty) => { 220 if let Some(vals) = $m.values_of($v) { 221 vals.map(|v| v.parse::<$t>().unwrap_or_else(|_|{ 222 ::clap::Error::value_validation_auto( 223 format!("One or more arguments aren't valid values")).exit() 224 })).collect::<Vec<$t>>() 225 } else { 226 ::clap::Error::argument_not_found_auto($v).exit() 227 } 228 }; 229 } 230 231 // _clap_count_exprs! is derived from https://github.com/DanielKeep/rust-grabbag 232 // commit: 82a35ca5d9a04c3b920622d542104e3310ee5b07 233 // License: MIT 234 // Copyright ⓒ 2015 grabbag contributors. 235 // Licensed under the MIT license (see LICENSE or <http://opensource.org 236 // /licenses/MIT>) or the Apache License, Version 2.0 (see LICENSE of 237 // <http://www.apache.org/licenses/LICENSE-2.0>), at your option. All 238 // files in the project carrying such notice may not be copied, modified, 239 // or distributed except according to those terms. 240 // 241 /// Counts the number of comma-delimited expressions passed to it. The result is a compile-time 242 /// evaluable expression, suitable for use as a static array size, or the value of a `const`. 243 /// 244 /// # Examples 245 /// 246 /// ``` 247 /// # #[macro_use] extern crate clap; 248 /// # fn main() { 249 /// const COUNT: usize = _clap_count_exprs!(a, 5+1, "hi there!".into_string()); 250 /// assert_eq!(COUNT, 3); 251 /// # } 252 /// ``` 253 #[macro_export] 254 macro_rules! _clap_count_exprs { 255 () => { 0 }; 256 ($e:expr) => { 1 }; 257 ($e:expr, $($es:expr),+) => { 1 + $crate::_clap_count_exprs!($($es),*) }; 258 } 259 260 /// Convenience macro to generate more complete enums with variants to be used as a type when 261 /// parsing arguments. This enum also provides a `variants()` function which can be used to 262 /// retrieve a `Vec<&'static str>` of the variant names, as well as implementing [`FromStr`] and 263 /// [`Display`] automatically. 264 /// 265 /// **NOTE:** Case insensitivity is supported for ASCII characters only. It's highly recommended to 266 /// use [`Arg::case_insensitive(true)`] for args that will be used with these enums 267 /// 268 /// **NOTE:** This macro automatically implements [`std::str::FromStr`] and [`std::fmt::Display`] 269 /// 270 /// **NOTE:** These enums support pub (or not) and uses of the `#[derive()]` traits 271 /// 272 /// # Examples 273 /// 274 /// ```rust 275 /// # #[macro_use] 276 /// # extern crate clap; 277 /// # use clap::{App, Arg}; 278 /// arg_enum!{ 279 /// #[derive(PartialEq, Debug)] 280 /// pub enum Foo { 281 /// Bar, 282 /// Baz, 283 /// Qux 284 /// } 285 /// } 286 /// // Foo enum can now be used via Foo::Bar, or Foo::Baz, etc 287 /// // and implements std::str::FromStr to use with the value_t! macros 288 /// fn main() { 289 /// let m = App::new("app") 290 /// .arg(Arg::from_usage("<foo> 'the foo'") 291 /// .possible_values(&Foo::variants()) 292 /// .case_insensitive(true)) 293 /// .get_matches_from(vec![ 294 /// "app", "baz" 295 /// ]); 296 /// let f = value_t!(m, "foo", Foo).unwrap_or_else(|e| e.exit()); 297 /// 298 /// assert_eq!(f, Foo::Baz); 299 /// } 300 /// ``` 301 /// [`FromStr`]: https://doc.rust-lang.org/std/str/trait.FromStr.html 302 /// [`std::str::FromStr`]: https://doc.rust-lang.org/std/str/trait.FromStr.html 303 /// [`Display`]: https://doc.rust-lang.org/std/fmt/trait.Display.html 304 /// [`std::fmt::Display`]: https://doc.rust-lang.org/std/fmt/trait.Display.html 305 /// [`Arg::case_insensitive(true)`]: ./struct.Arg.html#method.case_insensitive 306 #[macro_export] 307 macro_rules! arg_enum { 308 (@as_item $($i:item)*) => ($($i)*); 309 (@impls ( $($tts:tt)* ) -> ($e:ident, $($v:ident),+)) => { 310 arg_enum!(@as_item 311 $($tts)* 312 313 impl ::std::str::FromStr for $e { 314 type Err = String; 315 316 fn from_str(s: &str) -> ::std::result::Result<Self,Self::Err> { 317 #[allow(deprecated, unused_imports)] 318 use ::std::ascii::AsciiExt; 319 match s { 320 $(stringify!($v) | 321 _ if s.eq_ignore_ascii_case(stringify!($v)) => Ok($e::$v)),+, 322 _ => Err({ 323 let v = vec![ 324 $(stringify!($v),)+ 325 ]; 326 format!("valid values: {}", 327 v.join(", ")) 328 }), 329 } 330 } 331 } 332 impl ::std::fmt::Display for $e { 333 fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result { 334 match *self { 335 $($e::$v => write!(f, stringify!($v)),)+ 336 } 337 } 338 } 339 impl $e { 340 #[allow(dead_code)] 341 pub fn variants() -> [&'static str; $crate::_clap_count_exprs!($(stringify!($v)),+)] { 342 [ 343 $(stringify!($v),)+ 344 ] 345 } 346 }); 347 }; 348 ($(#[$($m:meta),+])+ pub enum $e:ident { $($v:ident $(=$val:expr)*,)+ } ) => { 349 arg_enum!(@impls 350 ($(#[$($m),+])+ 351 pub enum $e { 352 $($v$(=$val)*),+ 353 }) -> ($e, $($v),+) 354 ); 355 }; 356 ($(#[$($m:meta),+])+ pub enum $e:ident { $($v:ident $(=$val:expr)*),+ } ) => { 357 arg_enum!(@impls 358 ($(#[$($m),+])+ 359 pub enum $e { 360 $($v$(=$val)*),+ 361 }) -> ($e, $($v),+) 362 ); 363 }; 364 ($(#[$($m:meta),+])+ enum $e:ident { $($v:ident $(=$val:expr)*,)+ } ) => { 365 arg_enum!(@impls 366 ($(#[$($m),+])+ 367 enum $e { 368 $($v$(=$val)*),+ 369 }) -> ($e, $($v),+) 370 ); 371 }; 372 ($(#[$($m:meta),+])+ enum $e:ident { $($v:ident $(=$val:expr)*),+ } ) => { 373 arg_enum!(@impls 374 ($(#[$($m),+])+ 375 enum $e { 376 $($v$(=$val)*),+ 377 }) -> ($e, $($v),+) 378 ); 379 }; 380 (pub enum $e:ident { $($v:ident $(=$val:expr)*,)+ } ) => { 381 arg_enum!(@impls 382 (pub enum $e { 383 $($v$(=$val)*),+ 384 }) -> ($e, $($v),+) 385 ); 386 }; 387 (pub enum $e:ident { $($v:ident $(=$val:expr)*),+ } ) => { 388 arg_enum!(@impls 389 (pub enum $e { 390 $($v$(=$val)*),+ 391 }) -> ($e, $($v),+) 392 ); 393 }; 394 (enum $e:ident { $($v:ident $(=$val:expr)*,)+ } ) => { 395 arg_enum!(@impls 396 (enum $e { 397 $($v$(=$val)*),+ 398 }) -> ($e, $($v),+) 399 ); 400 }; 401 (enum $e:ident { $($v:ident $(=$val:expr)*),+ } ) => { 402 arg_enum!(@impls 403 (enum $e { 404 $($v$(=$val)*),+ 405 }) -> ($e, $($v),+) 406 ); 407 }; 408 } 409 410 /// Allows you to pull the version from your Cargo.toml at compile time as 411 /// `MAJOR.MINOR.PATCH_PKGVERSION_PRE` 412 /// 413 /// # Examples 414 /// 415 /// ```no_run 416 /// # #[macro_use] 417 /// # extern crate clap; 418 /// # use clap::App; 419 /// # fn main() { 420 /// let m = App::new("app") 421 /// .version(crate_version!()) 422 /// .get_matches(); 423 /// # } 424 /// ``` 425 #[cfg(not(feature = "no_cargo"))] 426 #[macro_export] 427 macro_rules! crate_version { 428 () => { 429 env!("CARGO_PKG_VERSION") 430 }; 431 } 432 433 /// Allows you to pull the authors for the app from your Cargo.toml at 434 /// compile time in the form: 435 /// `"author1 lastname <author1@example.com>:author2 lastname <author2@example.com>"` 436 /// 437 /// You can replace the colons with a custom separator by supplying a 438 /// replacement string, so, for example, 439 /// `crate_authors!(",\n")` would become 440 /// `"author1 lastname <author1@example.com>,\nauthor2 lastname <author2@example.com>,\nauthor3 lastname <author3@example.com>"` 441 /// 442 /// # Examples 443 /// 444 /// ```no_run 445 /// # #[macro_use] 446 /// # extern crate clap; 447 /// # use clap::App; 448 /// # fn main() { 449 /// let m = App::new("app") 450 /// .author(crate_authors!("\n")) 451 /// .get_matches(); 452 /// # } 453 /// ``` 454 #[cfg(not(feature = "no_cargo"))] 455 #[macro_export] 456 macro_rules! crate_authors { 457 ($sep:expr) => {{ 458 use std::ops::Deref; 459 use std::sync::{ONCE_INIT, Once}; 460 461 #[allow(missing_copy_implementations)] 462 #[allow(dead_code)] 463 struct CargoAuthors { __private_field: () }; 464 465 impl Deref for CargoAuthors { 466 type Target = str; 467 468 #[allow(unsafe_code)] 469 fn deref(&self) -> &'static str { 470 static ONCE: Once = ONCE_INIT; 471 static mut VALUE: *const String = 0 as *const String; 472 473 unsafe { 474 ONCE.call_once(|| { 475 let s = env!("CARGO_PKG_AUTHORS").replace(':', $sep); 476 VALUE = Box::into_raw(Box::new(s)); 477 }); 478 479 &(*VALUE)[..] 480 } 481 } 482 } 483 484 &*CargoAuthors { __private_field: () } 485 }}; 486 () => { 487 env!("CARGO_PKG_AUTHORS") 488 }; 489 } 490 491 /// Allows you to pull the description from your Cargo.toml at compile time. 492 /// 493 /// # Examples 494 /// 495 /// ```no_run 496 /// # #[macro_use] 497 /// # extern crate clap; 498 /// # use clap::App; 499 /// # fn main() { 500 /// let m = App::new("app") 501 /// .about(crate_description!()) 502 /// .get_matches(); 503 /// # } 504 /// ``` 505 #[cfg(not(feature = "no_cargo"))] 506 #[macro_export] 507 macro_rules! crate_description { 508 () => { 509 env!("CARGO_PKG_DESCRIPTION") 510 }; 511 } 512 513 /// Allows you to pull the name from your Cargo.toml at compile time. 514 /// 515 /// # Examples 516 /// 517 /// ```no_run 518 /// # #[macro_use] 519 /// # extern crate clap; 520 /// # use clap::App; 521 /// # fn main() { 522 /// let m = App::new(crate_name!()) 523 /// .get_matches(); 524 /// # } 525 /// ``` 526 #[cfg(not(feature = "no_cargo"))] 527 #[macro_export] 528 macro_rules! crate_name { 529 () => { 530 env!("CARGO_PKG_NAME") 531 }; 532 } 533 534 /// Allows you to build the `App` instance from your Cargo.toml at compile time. 535 /// 536 /// Equivalent to using the `crate_*!` macros with their respective fields. 537 /// 538 /// Provided separator is for the [`crate_authors!`](macro.crate_authors.html) macro, 539 /// refer to the documentation therefor. 540 /// 541 /// **NOTE:** Changing the values in your `Cargo.toml` does not trigger a re-build automatically, 542 /// and therefore won't change the generated output until you recompile. 543 /// 544 /// **Pro Tip:** In some cases you can "trick" the compiler into triggering a rebuild when your 545 /// `Cargo.toml` is changed by including this in your `src/main.rs` file 546 /// `include_str!("../Cargo.toml");` 547 /// 548 /// # Examples 549 /// 550 /// ```no_run 551 /// # #[macro_use] 552 /// # extern crate clap; 553 /// # fn main() { 554 /// let m = app_from_crate!().get_matches(); 555 /// # } 556 /// ``` 557 #[cfg(not(feature = "no_cargo"))] 558 #[macro_export] 559 macro_rules! app_from_crate { 560 () => { 561 $crate::App::new(crate_name!()) 562 .version(crate_version!()) 563 .author(crate_authors!()) 564 .about(crate_description!()) 565 }; 566 ($sep:expr) => { 567 $crate::App::new(crate_name!()) 568 .version(crate_version!()) 569 .author(crate_authors!($sep)) 570 .about(crate_description!()) 571 }; 572 } 573 574 /// Build `App`, `Arg`s, `SubCommand`s and `Group`s with Usage-string like input 575 /// but without the associated parsing runtime cost. 576 /// 577 /// `clap_app!` also supports several shorthand syntaxes. 578 /// 579 /// # Examples 580 /// 581 /// ```no_run 582 /// # #[macro_use] 583 /// # extern crate clap; 584 /// # fn main() { 585 /// let matches = clap_app!(myapp => 586 /// (version: "1.0") 587 /// (author: "Kevin K. <kbknapp@gmail.com>") 588 /// (about: "Does awesome things") 589 /// (@arg CONFIG: -c --config +takes_value "Sets a custom config file") 590 /// (@arg INPUT: +required "Sets the input file to use") 591 /// (@arg debug: -d ... "Sets the level of debugging information") 592 /// (@group difficulty => 593 /// (@arg hard: -h --hard "Sets hard mode") 594 /// (@arg normal: -n --normal "Sets normal mode") 595 /// (@arg easy: -e --easy "Sets easy mode") 596 /// ) 597 /// (@subcommand test => 598 /// (about: "controls testing features") 599 /// (version: "1.3") 600 /// (author: "Someone E. <someone_else@other.com>") 601 /// (@arg verbose: -v --verbose "Print test information verbosely") 602 /// ) 603 /// ) 604 /// .get_matches(); 605 /// # } 606 /// ``` 607 /// # Shorthand Syntax for Args 608 /// 609 /// * A single hyphen followed by a character (such as `-c`) sets the [`Arg::short`] 610 /// * A double hyphen followed by a character or word (such as `--config`) sets [`Arg::long`] 611 /// * If one wishes to use a [`Arg::long`] with a hyphen inside (i.e. `--config-file`), you 612 /// must use `--("config-file")` due to limitations of the Rust macro system. 613 /// * Three dots (`...`) sets [`Arg::multiple(true)`] 614 /// * Angled brackets after either a short or long will set [`Arg::value_name`] and 615 /// `Arg::required(true)` such as `--config <FILE>` = `Arg::value_name("FILE")` and 616 /// `Arg::required(true)` 617 /// * Square brackets after either a short or long will set [`Arg::value_name`] and 618 /// `Arg::required(false)` such as `--config [FILE]` = `Arg::value_name("FILE")` and 619 /// `Arg::required(false)` 620 /// * There are short hand syntaxes for Arg methods that accept booleans 621 /// * A plus sign will set that method to `true` such as `+required` = `Arg::required(true)` 622 /// * An exclamation will set that method to `false` such as `!required` = `Arg::required(false)` 623 /// * A `#{min, max}` will set [`Arg::min_values(min)`] and [`Arg::max_values(max)`] 624 /// * An asterisk (`*`) will set `Arg::required(true)` 625 /// * Curly brackets around a `fn` will set [`Arg::validator`] as in `{fn}` = `Arg::validator(fn)` 626 /// * An Arg method that accepts a string followed by square brackets will set that method such as 627 /// `conflicts_with[FOO]` will set `Arg::conflicts_with("FOO")` (note the lack of quotes around 628 /// `FOO` in the macro) 629 /// * An Arg method that takes a string and can be set multiple times (such as 630 /// [`Arg::conflicts_with`]) followed by square brackets and a list of values separated by spaces 631 /// will set that method such as `conflicts_with[FOO BAR BAZ]` will set 632 /// `Arg::conflicts_with("FOO")`, `Arg::conflicts_with("BAR")`, and `Arg::conflicts_with("BAZ")` 633 /// (note the lack of quotes around the values in the macro) 634 /// 635 /// # Shorthand Syntax for Groups 636 /// 637 /// * There are short hand syntaxes for `ArgGroup` methods that accept booleans 638 /// * A plus sign will set that method to `true` such as `+required` = `ArgGroup::required(true)` 639 /// * An exclamation will set that method to `false` such as `!required` = `ArgGroup::required(false)` 640 /// 641 /// [`Arg::short`]: ./struct.Arg.html#method.short 642 /// [`Arg::long`]: ./struct.Arg.html#method.long 643 /// [`Arg::multiple(true)`]: ./struct.Arg.html#method.multiple 644 /// [`Arg::value_name`]: ./struct.Arg.html#method.value_name 645 /// [`Arg::min_values(min)`]: ./struct.Arg.html#method.min_values 646 /// [`Arg::max_values(max)`]: ./struct.Arg.html#method.max_values 647 /// [`Arg::validator`]: ./struct.Arg.html#method.validator 648 /// [`Arg::conflicts_with`]: ./struct.Arg.html#method.conflicts_with 649 #[macro_export] 650 macro_rules! clap_app { 651 (@app ($builder:expr)) => { $builder }; 652 (@app ($builder:expr) (@arg ($name:expr): $($tail:tt)*) $($tt:tt)*) => { 653 clap_app!{ @app 654 ($builder.arg( 655 clap_app!{ @arg ($crate::Arg::with_name($name)) (-) $($tail)* })) 656 $($tt)* 657 } 658 }; 659 (@app ($builder:expr) (@arg $name:ident: $($tail:tt)*) $($tt:tt)*) => { 660 clap_app!{ @app 661 ($builder.arg( 662 clap_app!{ @arg ($crate::Arg::with_name(stringify!($name))) (-) $($tail)* })) 663 $($tt)* 664 } 665 }; 666 (@app ($builder:expr) (@setting $setting:ident) $($tt:tt)*) => { 667 clap_app!{ @app 668 ($builder.setting($crate::AppSettings::$setting)) 669 $($tt)* 670 } 671 }; 672 // Treat the application builder as an argument to set its attributes 673 (@app ($builder:expr) (@attributes $($attr:tt)*) $($tt:tt)*) => { 674 clap_app!{ @app (clap_app!{ @arg ($builder) $($attr)* }) $($tt)* } 675 }; 676 (@app ($builder:expr) (@group $name:ident => $($tail:tt)*) $($tt:tt)*) => { 677 clap_app!{ @app 678 (clap_app!{ @group ($builder, $crate::ArgGroup::with_name(stringify!($name))) $($tail)* }) 679 $($tt)* 680 } 681 }; 682 (@app ($builder:expr) (@group $name:ident !$ident:ident => $($tail:tt)*) $($tt:tt)*) => { 683 clap_app!{ @app 684 (clap_app!{ @group ($builder, $crate::ArgGroup::with_name(stringify!($name)).$ident(false)) $($tail)* }) 685 $($tt)* 686 } 687 }; 688 (@app ($builder:expr) (@group $name:ident +$ident:ident => $($tail:tt)*) $($tt:tt)*) => { 689 clap_app!{ @app 690 (clap_app!{ @group ($builder, $crate::ArgGroup::with_name(stringify!($name)).$ident(true)) $($tail)* }) 691 $($tt)* 692 } 693 }; 694 // Handle subcommand creation 695 (@app ($builder:expr) (@subcommand $name:ident => $($tail:tt)*) $($tt:tt)*) => { 696 clap_app!{ @app 697 ($builder.subcommand( 698 clap_app!{ @app ($crate::SubCommand::with_name(stringify!($name))) $($tail)* } 699 )) 700 $($tt)* 701 } 702 }; 703 // Yaml like function calls - used for setting various meta directly against the app 704 (@app ($builder:expr) ($ident:ident: $($v:expr),*) $($tt:tt)*) => { 705 // clap_app!{ @app ($builder.$ident($($v),*)) $($tt)* } 706 clap_app!{ @app 707 ($builder.$ident($($v),*)) 708 $($tt)* 709 } 710 }; 711 712 // Add members to group and continue argument handling with the parent builder 713 (@group ($builder:expr, $group:expr)) => { $builder.group($group) }; 714 // Treat the group builder as an argument to set its attributes 715 (@group ($builder:expr, $group:expr) (@attributes $($attr:tt)*) $($tt:tt)*) => { 716 clap_app!{ @group ($builder, clap_app!{ @arg ($group) (-) $($attr)* }) $($tt)* } 717 }; 718 (@group ($builder:expr, $group:expr) (@arg $name:ident: $($tail:tt)*) $($tt:tt)*) => { 719 clap_app!{ @group 720 (clap_app!{ @app ($builder) (@arg $name: $($tail)*) }, 721 $group.arg(stringify!($name))) 722 $($tt)* 723 } 724 }; 725 726 // No more tokens to munch 727 (@arg ($arg:expr) $modes:tt) => { $arg }; 728 // Shorthand tokens influenced by the usage_string 729 (@arg ($arg:expr) $modes:tt --($long:expr) $($tail:tt)*) => { 730 clap_app!{ @arg ($arg.long($long)) $modes $($tail)* } 731 }; 732 (@arg ($arg:expr) $modes:tt --$long:ident $($tail:tt)*) => { 733 clap_app!{ @arg ($arg.long(stringify!($long))) $modes $($tail)* } 734 }; 735 (@arg ($arg:expr) $modes:tt -$short:ident $($tail:tt)*) => { 736 clap_app!{ @arg ($arg.short(stringify!($short))) $modes $($tail)* } 737 }; 738 (@arg ($arg:expr) (-) <$var:ident> $($tail:tt)*) => { 739 clap_app!{ @arg ($arg.value_name(stringify!($var))) (+) +takes_value +required $($tail)* } 740 }; 741 (@arg ($arg:expr) (+) <$var:ident> $($tail:tt)*) => { 742 clap_app!{ @arg ($arg.value_name(stringify!($var))) (+) $($tail)* } 743 }; 744 (@arg ($arg:expr) (-) [$var:ident] $($tail:tt)*) => { 745 clap_app!{ @arg ($arg.value_name(stringify!($var))) (+) +takes_value $($tail)* } 746 }; 747 (@arg ($arg:expr) (+) [$var:ident] $($tail:tt)*) => { 748 clap_app!{ @arg ($arg.value_name(stringify!($var))) (+) $($tail)* } 749 }; 750 (@arg ($arg:expr) $modes:tt ... $($tail:tt)*) => { 751 clap_app!{ @arg ($arg) $modes +multiple $($tail)* } 752 }; 753 // Shorthand magic 754 (@arg ($arg:expr) $modes:tt #{$n:expr, $m:expr} $($tail:tt)*) => { 755 clap_app!{ @arg ($arg) $modes min_values($n) max_values($m) $($tail)* } 756 }; 757 (@arg ($arg:expr) $modes:tt * $($tail:tt)*) => { 758 clap_app!{ @arg ($arg) $modes +required $($tail)* } 759 }; 760 // !foo -> .foo(false) 761 (@arg ($arg:expr) $modes:tt !$ident:ident $($tail:tt)*) => { 762 clap_app!{ @arg ($arg.$ident(false)) $modes $($tail)* } 763 }; 764 // +foo -> .foo(true) 765 (@arg ($arg:expr) $modes:tt +$ident:ident $($tail:tt)*) => { 766 clap_app!{ @arg ($arg.$ident(true)) $modes $($tail)* } 767 }; 768 // Validator 769 (@arg ($arg:expr) $modes:tt {$fn_:expr} $($tail:tt)*) => { 770 clap_app!{ @arg ($arg.validator($fn_)) $modes $($tail)* } 771 }; 772 (@as_expr $expr:expr) => { $expr }; 773 // Help 774 (@arg ($arg:expr) $modes:tt $desc:tt) => { $arg.help(clap_app!{ @as_expr $desc }) }; 775 // Handle functions that need to be called multiple times for each argument 776 (@arg ($arg:expr) $modes:tt $ident:ident[$($target:ident)*] $($tail:tt)*) => { 777 clap_app!{ @arg ($arg $( .$ident(stringify!($target)) )*) $modes $($tail)* } 778 }; 779 // Inherit builder's functions, e.g. `index(2)`, `requires_if("val", "arg")` 780 (@arg ($arg:expr) $modes:tt $ident:ident($($expr:expr),*) $($tail:tt)*) => { 781 clap_app!{ @arg ($arg.$ident($($expr),*)) $modes $($tail)* } 782 }; 783 // Inherit builder's functions with trailing comma, e.g. `index(2,)`, `requires_if("val", "arg",)` 784 (@arg ($arg:expr) $modes:tt $ident:ident($($expr:expr,)*) $($tail:tt)*) => { 785 clap_app!{ @arg ($arg.$ident($($expr),*)) $modes $($tail)* } 786 }; 787 788 // Build a subcommand outside of an app. 789 (@subcommand $name:ident => $($tail:tt)*) => { 790 clap_app!{ @app ($crate::SubCommand::with_name(stringify!($name))) $($tail)* } 791 }; 792 // Start the magic 793 (($name:expr) => $($tail:tt)*) => {{ 794 clap_app!{ @app ($crate::App::new($name)) $($tail)*} 795 }}; 796 797 ($name:ident => $($tail:tt)*) => {{ 798 clap_app!{ @app ($crate::App::new(stringify!($name))) $($tail)*} 799 }}; 800 } 801 802 macro_rules! impl_settings { 803 ($n:ident, $($v:ident => $c:path),+) => { 804 pub fn set(&mut self, s: $n) { 805 match s { 806 $($n::$v => self.0.insert($c)),+ 807 } 808 } 809 810 pub fn unset(&mut self, s: $n) { 811 match s { 812 $($n::$v => self.0.remove($c)),+ 813 } 814 } 815 816 pub fn is_set(&self, s: $n) -> bool { 817 match s { 818 $($n::$v => self.0.contains($c)),+ 819 } 820 } 821 }; 822 } 823 824 // Convenience for writing to stderr thanks to https://github.com/BurntSushi 825 macro_rules! wlnerr( 826 ($($arg:tt)*) => ({ 827 use std::io::{Write, stderr}; 828 writeln!(&mut stderr(), $($arg)*).ok(); 829 }) 830 ); 831 832 #[cfg(feature = "debug")] 833 #[cfg_attr(feature = "debug", macro_use)] 834 #[cfg_attr(feature = "debug", allow(unused_macros))] 835 mod debug_macros { 836 macro_rules! debugln { 837 ($fmt:expr) => (println!(concat!("DEBUG:clap:", $fmt))); 838 ($fmt:expr, $($arg:tt)*) => (println!(concat!("DEBUG:clap:",$fmt), $($arg)*)); 839 } 840 macro_rules! sdebugln { 841 ($fmt:expr) => (println!($fmt)); 842 ($fmt:expr, $($arg:tt)*) => (println!($fmt, $($arg)*)); 843 } 844 macro_rules! debug { 845 ($fmt:expr) => (print!(concat!("DEBUG:clap:", $fmt))); 846 ($fmt:expr, $($arg:tt)*) => (print!(concat!("DEBUG:clap:",$fmt), $($arg)*)); 847 } 848 macro_rules! sdebug { 849 ($fmt:expr) => (print!($fmt)); 850 ($fmt:expr, $($arg:tt)*) => (print!($fmt, $($arg)*)); 851 } 852 } 853 854 #[cfg(not(feature = "debug"))] 855 #[cfg_attr(not(feature = "debug"), macro_use)] 856 mod debug_macros { 857 macro_rules! debugln { 858 ($fmt:expr) => (); 859 ($fmt:expr, $($arg:tt)*) => (); 860 } 861 macro_rules! sdebugln { 862 ($fmt:expr) => (); 863 ($fmt:expr, $($arg:tt)*) => (); 864 } 865 macro_rules! debug { 866 ($fmt:expr) => (); 867 ($fmt:expr, $($arg:tt)*) => (); 868 } 869 } 870 871 // Helper/deduplication macro for printing the correct number of spaces in help messages 872 // used in: 873 // src/args/arg_builder/*.rs 874 // src/app/mod.rs 875 macro_rules! write_nspaces { 876 ($dst:expr, $num:expr) => ({ 877 debugln!("write_spaces!: num={}", $num); 878 for _ in 0..$num { 879 $dst.write_all(b" ")?; 880 } 881 }) 882 } 883 884 // convenience macro for remove an item from a vec 885 //macro_rules! vec_remove_all { 886 // ($vec:expr, $to_rem:expr) => { 887 // debugln!("vec_remove_all! to_rem={:?}", $to_rem); 888 // for i in (0 .. $vec.len()).rev() { 889 // let should_remove = $to_rem.any(|name| name == &$vec[i]); 890 // if should_remove { $vec.swap_remove(i); } 891 // } 892 // }; 893 //} 894 macro_rules! find_from { 895 ($_self:expr, $arg_name:expr, $from:ident, $matcher:expr) => {{ 896 let mut ret = None; 897 for k in $matcher.arg_names() { 898 if let Some(f) = find_by_name!($_self, k, flags, iter) { 899 if let Some(ref v) = f.$from() { 900 if v.contains($arg_name) { 901 ret = Some(f.to_string()); 902 } 903 } 904 } 905 if let Some(o) = find_by_name!($_self, k, opts, iter) { 906 if let Some(ref v) = o.$from() { 907 if v.contains(&$arg_name) { 908 ret = Some(o.to_string()); 909 } 910 } 911 } 912 if let Some(pos) = find_by_name!($_self, k, positionals, values) { 913 if let Some(ref v) = pos.$from() { 914 if v.contains($arg_name) { 915 ret = Some(pos.b.name.to_owned()); 916 } 917 } 918 } 919 } 920 ret 921 }}; 922 } 923 924 //macro_rules! find_name_from { 925 // ($_self:expr, $arg_name:expr, $from:ident, $matcher:expr) => {{ 926 // let mut ret = None; 927 // for k in $matcher.arg_names() { 928 // if let Some(f) = find_by_name!($_self, k, flags, iter) { 929 // if let Some(ref v) = f.$from() { 930 // if v.contains($arg_name) { 931 // ret = Some(f.b.name); 932 // } 933 // } 934 // } 935 // if let Some(o) = find_by_name!($_self, k, opts, iter) { 936 // if let Some(ref v) = o.$from() { 937 // if v.contains(&$arg_name) { 938 // ret = Some(o.b.name); 939 // } 940 // } 941 // } 942 // if let Some(pos) = find_by_name!($_self, k, positionals, values) { 943 // if let Some(ref v) = pos.$from() { 944 // if v.contains($arg_name) { 945 // ret = Some(pos.b.name); 946 // } 947 // } 948 // } 949 // } 950 // ret 951 // }}; 952 //} 953 954 955 macro_rules! find_any_by_name { 956 ($p:expr, $name:expr) => { 957 { 958 fn as_trait_obj<'a, 'b, T: AnyArg<'a, 'b>>(x: &T) -> &AnyArg<'a, 'b> { x } 959 find_by_name!($p, $name, flags, iter).map(as_trait_obj).or( 960 find_by_name!($p, $name, opts, iter).map(as_trait_obj).or( 961 find_by_name!($p, $name, positionals, values).map(as_trait_obj) 962 ) 963 ) 964 } 965 } 966 } 967 // Finds an arg by name 968 macro_rules! find_by_name { 969 ($p:expr, $name:expr, $what:ident, $how:ident) => { 970 $p.$what.$how().find(|o| o.b.name == $name) 971 } 972 } 973 974 // Finds an option including if it's aliased 975 macro_rules! find_opt_by_long { 976 (@os $_self:ident, $long:expr) => {{ 977 _find_by_long!($_self, $long, opts) 978 }}; 979 ($_self:ident, $long:expr) => {{ 980 _find_by_long!($_self, $long, opts) 981 }}; 982 } 983 984 macro_rules! find_flag_by_long { 985 (@os $_self:ident, $long:expr) => {{ 986 _find_by_long!($_self, $long, flags) 987 }}; 988 ($_self:ident, $long:expr) => {{ 989 _find_by_long!($_self, $long, flags) 990 }}; 991 } 992 993 macro_rules! _find_by_long { 994 ($_self:ident, $long:expr, $what:ident) => {{ 995 $_self.$what 996 .iter() 997 .filter(|a| a.s.long.is_some()) 998 .find(|a| { 999 a.s.long.unwrap() == $long || 1000 (a.s.aliases.is_some() && 1001 a.s 1002 .aliases 1003 .as_ref() 1004 .unwrap() 1005 .iter() 1006 .any(|&(alias, _)| alias == $long)) 1007 }) 1008 }} 1009 } 1010 1011 // Finds an option 1012 macro_rules! find_opt_by_short { 1013 ($_self:ident, $short:expr) => {{ 1014 _find_by_short!($_self, $short, opts) 1015 }} 1016 } 1017 1018 macro_rules! find_flag_by_short { 1019 ($_self:ident, $short:expr) => {{ 1020 _find_by_short!($_self, $short, flags) 1021 }} 1022 } 1023 1024 macro_rules! _find_by_short { 1025 ($_self:ident, $short:expr, $what:ident) => {{ 1026 $_self.$what 1027 .iter() 1028 .filter(|a| a.s.short.is_some()) 1029 .find(|a| a.s.short.unwrap() == $short) 1030 }} 1031 } 1032 1033 macro_rules! find_subcmd { 1034 ($_self:expr, $sc:expr) => {{ 1035 $_self.subcommands 1036 .iter() 1037 .find(|s| { 1038 &*s.p.meta.name == $sc || 1039 (s.p.meta.aliases.is_some() && 1040 s.p 1041 .meta 1042 .aliases 1043 .as_ref() 1044 .unwrap() 1045 .iter() 1046 .any(|&(n, _)| n == $sc)) 1047 }) 1048 }}; 1049 } 1050 1051 macro_rules! shorts { 1052 ($_self:ident) => {{ 1053 _shorts_longs!($_self, short) 1054 }}; 1055 } 1056 1057 1058 macro_rules! longs { 1059 ($_self:ident) => {{ 1060 _shorts_longs!($_self, long) 1061 }}; 1062 } 1063 1064 macro_rules! _shorts_longs { 1065 ($_self:ident, $what:ident) => {{ 1066 $_self.flags 1067 .iter() 1068 .filter(|f| f.s.$what.is_some()) 1069 .map(|f| f.s.$what.as_ref().unwrap()) 1070 .chain($_self.opts.iter() 1071 .filter(|o| o.s.$what.is_some()) 1072 .map(|o| o.s.$what.as_ref().unwrap())) 1073 }}; 1074 } 1075 1076 macro_rules! arg_names { 1077 ($_self:ident) => {{ 1078 _names!(@args $_self) 1079 }}; 1080 } 1081 1082 macro_rules! sc_names { 1083 ($_self:ident) => {{ 1084 _names!(@sc $_self) 1085 }}; 1086 } 1087 1088 macro_rules! _names { 1089 (@args $_self:ident) => {{ 1090 $_self.flags 1091 .iter() 1092 .map(|f| &*f.b.name) 1093 .chain($_self.opts.iter() 1094 .map(|o| &*o.b.name) 1095 .chain($_self.positionals.values() 1096 .map(|p| &*p.b.name))) 1097 }}; 1098 (@sc $_self:ident) => {{ 1099 $_self.subcommands 1100 .iter() 1101 .map(|s| &*s.p.meta.name) 1102 .chain($_self.subcommands 1103 .iter() 1104 .filter(|s| s.p.meta.aliases.is_some()) 1105 .flat_map(|s| s.p.meta.aliases.as_ref().unwrap().iter().map(|&(n, _)| n))) 1106 1107 }} 1108 } 1109