src/libstd/macros.rs

   1 // Copyright 2014 The Rust Project Developers. See the COPYRIGHT
   2 // file at the top-level directory of this distribution and at
   3 // http://rust-lang.org/COPYRIGHT.
   4 //
   5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
   6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
   7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
   8 // option. This file may not be copied, modified, or distributed
   9 // except according to those terms.
  10
  11 //! Standard library macros
  12 //!
  13 //! This modules contains a set of macros which are exported from the standard
  14 //! library. Each macro is available for use when linking against the standard
  15 //! library.
  16
  17 #![experimental]
  18 #![macro_escape]
  19
  20 // NOTE(stage0): Remove cfg after a snapshot
  21 #[cfg(not(stage0))]
  22 /// The entry point for panic of Rust tasks.
  23 ///
  24 /// This macro is used to inject panic into a Rust task, causing the task to
  25 /// unwind and panic entirely. Each task's panic can be reaped as the
  26 /// `Box<Any>` type, and the single-argument form of the `panic!` macro will be
  27 /// the value which is transmitted.
  28 ///
  29 /// The multi-argument form of this macro panics with a string and has the
  30 /// `format!` syntax for building a string.
  31 ///
  32 /// # Example
  33 ///
  34 /// ```should_fail
  35 /// # #![allow(unreachable_code)]
  36 /// panic!();
  37 /// panic!("this is a terrible mistake!");
  38 /// panic!(4i); // panic with the value of 4 to be collected elsewhere
  39 /// panic!("this is a {} {message}", "fancy", message = "message");
  40 /// ```
  41 #[macro_export]
  42 macro_rules! panic {
  43     () => ({
  44         panic!("explicit panic")
  45     });
  46     ($msg:expr) => ({
  47         // static requires less code at runtime, more constant data
  48         static _FILE_LINE: (&'static str, uint) = (file!(), line!());
  49         ::std::rt::begin_unwind($msg, &_FILE_LINE)
  50     });
  51     ($fmt:expr, $($arg:tt)*) => ({
  52         // The leading _'s are to avoid dead code warnings if this is
  53         // used inside a dead function. Just `#[allow(dead_code)]` is
  54         // insufficient, since the user may have
  55         // `#[forbid(dead_code)]` and which cannot be overridden.
  56         static _FILE_LINE: (&'static str, uint) = (file!(), line!());
  57         ::std::rt::begin_unwind_fmt(format_args!($fmt, $($arg)*), &_FILE_LINE)
  58
  59     });
  60 }
  61
  62 // NOTE(stage0): Remove macro after a snapshot
  63 #[cfg(stage0)]
  64 /// The entry point for panic of Rust tasks.
  65 ///
  66 /// This macro is used to inject panic into a Rust task, causing the task to
  67 /// unwind and panic entirely. Each task's panic can be reaped as the
  68 /// `Box<Any>` type, and the single-argument form of the `panic!` macro will be
  69 /// the value which is transmitted.
  70 ///
  71 /// The multi-argument form of this macro panics with a string and has the
  72 /// `format!` syntax for building a string.
  73 ///
  74 /// # Example
  75 ///
  76 /// ```should_fail
  77 /// # #![allow(unreachable_code)]
  78 /// panic!();
  79 /// panic!("this is a terrible mistake!");
  80 /// panic!(4i); // panic with the value of 4 to be collected elsewhere
  81 /// panic!("this is a {} {message}", "fancy", message = "message");
  82 /// ```
  83 #[macro_export]
  84 macro_rules! panic {
  85     () => ({
  86         panic!("explicit panic")
  87     });
  88     ($msg:expr) => ({
  89         // static requires less code at runtime, more constant data
  90         static _FILE_LINE: (&'static str, uint) = (file!(), line!());
  91         ::std::rt::begin_unwind($msg, &_FILE_LINE)
  92     });
  93     ($fmt:expr, $($arg:tt)*) => ({
  94         // a closure can't have return type !, so we need a full
  95         // function to pass to format_args!, *and* we need the
  96         // file and line numbers right here; so an inner bare fn
  97         // is our only choice.
  98         //
  99         // LLVM doesn't tend to inline this, presumably because begin_unwind_fmt
 100         // is #[cold] and #[inline(never)] and because this is flagged as cold
 101         // as returning !. We really do want this to be inlined, however,
 102         // because it's just a tiny wrapper. Small wins (156K to 149K in size)
 103         // were seen when forcing this to be inlined, and that number just goes
 104         // up with the number of calls to panic!()
 105         //
 106         // The leading _'s are to avoid dead code warnings if this is
 107         // used inside a dead function. Just `#[allow(dead_code)]` is
 108         // insufficient, since the user may have
 109         // `#[forbid(dead_code)]` and which cannot be overridden.
 110         #[inline(always)]
 111         fn _run_fmt(fmt: &::std::fmt::Arguments) -> ! {
 112             static _FILE_LINE: (&'static str, uint) = (file!(), line!());
 113             ::std::rt::begin_unwind_fmt(fmt, &_FILE_LINE)
 114         }
 115         format_args!(_run_fmt, $fmt, $($arg)*)
 116     });
 117 }
 118
 119 /// Ensure that a boolean expression is `true` at runtime.
 120 ///
 121 /// This will invoke the `panic!` macro if the provided expression cannot be
 122 /// evaluated to `true` at runtime.
 123 ///
 124 /// # Example
 125 ///
 126 /// ```
 127 /// // the panic message for these assertions is the stringified value of the
 128 /// // expression given.
 129 /// assert!(true);
 130 /// # fn some_computation() -> bool { true }
 131 /// assert!(some_computation());
 132 ///
 133 /// // assert with a custom message
 134 /// # let x = true;
 135 /// assert!(x, "x wasn't true!");
 136 /// # let a = 3i; let b = 27i;
 137 /// assert!(a + b == 30, "a = {}, b = {}", a, b);
 138 /// ```
 139 #[macro_export]
 140 macro_rules! assert {
 141     ($cond:expr) => (
 142         if !$cond {
 143             panic!(concat!("assertion failed: ", stringify!($cond)))
 144         }
 145     );
 146     ($cond:expr, $($arg:expr),+) => (
 147         if !$cond {
 148             panic!($($arg),+)
 149         }
 150     );
 151 }
 152
 153 /// Asserts that two expressions are equal to each other, testing equality in
 154 /// both directions.
 155 ///
 156 /// On panic, this macro will print the values of the expressions.
 157 ///
 158 /// # Example
 159 ///
 160 /// ```
 161 /// let a = 3i;
 162 /// let b = 1i + 2i;
 163 /// assert_eq!(a, b);
 164 /// ```
 165 #[macro_export]
 166 macro_rules! assert_eq {
 167     ($left:expr , $right:expr) => ({
 168         match (&($left), &($right)) {
 169             (left_val, right_val) => {
 170                 // check both directions of equality....
 171                 if !((*left_val == *right_val) &&
 172                      (*right_val == *left_val)) {
 173                     panic!("assertion failed: `(left == right) && (right == left)` \
 174                            (left: `{}`, right: `{}`)", *left_val, *right_val)
 175                 }
 176             }
 177         }
 178     })
 179 }
 180
 181 /// Ensure that a boolean expression is `true` at runtime.
 182 ///
 183 /// This will invoke the `panic!` macro if the provided expression cannot be
 184 /// evaluated to `true` at runtime.
 185 ///
 186 /// Unlike `assert!`, `debug_assert!` statements can be disabled by passing
 187 /// `--cfg ndebug` to the compiler. This makes `debug_assert!` useful for
 188 /// checks that are too expensive to be present in a release build but may be
 189 /// helpful during development.
 190 ///
 191 /// # Example
 192 ///
 193 /// ```
 194 /// // the panic message for these assertions is the stringified value of the
 195 /// // expression given.
 196 /// debug_assert!(true);
 197 /// # fn some_expensive_computation() -> bool { true }
 198 /// debug_assert!(some_expensive_computation());
 199 ///
 200 /// // assert with a custom message
 201 /// # let x = true;
 202 /// debug_assert!(x, "x wasn't true!");
 203 /// # let a = 3i; let b = 27i;
 204 /// debug_assert!(a + b == 30, "a = {}, b = {}", a, b);
 205 /// ```
 206 #[macro_export]
 207 macro_rules! debug_assert {
 208     ($($arg:tt)*) => (if cfg!(not(ndebug)) { assert!($($arg)*); })
 209 }
 210
 211 /// Asserts that two expressions are equal to each other, testing equality in
 212 /// both directions.
 213 ///
 214 /// On panic, this macro will print the values of the expressions.
 215 ///
 216 /// Unlike `assert_eq!`, `debug_assert_eq!` statements can be disabled by
 217 /// passing `--cfg ndebug` to the compiler. This makes `debug_assert_eq!`
 218 /// useful for checks that are too expensive to be present in a release build
 219 /// but may be helpful during development.
 220 ///
 221 /// # Example
 222 ///
 223 /// ```
 224 /// let a = 3i;
 225 /// let b = 1i + 2i;
 226 /// debug_assert_eq!(a, b);
 227 /// ```
 228 #[macro_export]
 229 macro_rules! debug_assert_eq {
 230     ($($arg:tt)*) => (if cfg!(not(ndebug)) { assert_eq!($($arg)*); })
 231 }
 232
 233 /// A utility macro for indicating unreachable code.
 234 ///
 235 /// This is useful any time that the compiler can't determine that some code is unreachable. For
 236 /// example:
 237 ///
 238 /// * Match arms with guard conditions.
 239 /// * Loops that dynamically terminate.
 240 /// * Iterators that dynamically terminate.
 241 ///
 242 /// # Panics
 243 ///
 244 /// This will always panic.
 245 ///
 246 /// # Examples
 247 ///
 248 /// Match arms:
 249 ///
 250 /// ```rust
 251 /// fn foo(x: Option<int>) {
 252 ///     match x {
 253 ///         Some(n) if n >= 0 => println!("Some(Non-negative)"),
 254 ///         Some(n) if n <  0 => println!("Some(Negative)"),
 255 ///         Some(_)           => unreachable!(), // compile error if commented out
 256 ///         None              => println!("None")
 257 ///     }
 258 /// }
 259 /// ```
 260 ///
 261 /// Iterators:
 262 ///
 263 /// ```rust
 264 /// fn divide_by_three(x: u32) -> u32 { // one of the poorest implementations of x/3
 265 ///     for i in std::iter::count(0_u32, 1) {
 266 ///         if 3*i < i { panic!("u32 overflow"); }
 267 ///         if x < 3*i { return i-1; }
 268 ///     }
 269 ///     unreachable!();
 270 /// }
 271 /// ```
 272 #[macro_export]
 273 macro_rules! unreachable {
 274     () => ({
 275         panic!("internal error: entered unreachable code")
 276     });
 277     ($msg:expr) => ({
 278         unreachable!("{}", $msg)
 279     });
 280     ($fmt:expr, $($arg:tt)*) => ({
 281         panic!(concat!("internal error: entered unreachable code: ", $fmt), $($arg)*)
 282     });
 283 }
 284
 285 /// A standardised placeholder for marking unfinished code. It panics with the
 286 /// message `"not yet implemented"` when executed.
 287 #[macro_export]
 288 macro_rules! unimplemented {
 289     () => (panic!("not yet implemented"))
 290 }
 291
 292 // NOTE(stage0): Remove cfg after a snapshot
 293 #[cfg(not(stage0))]
 294 /// Use the syntax described in `std::fmt` to create a value of type `String`.
 295 /// See `std::fmt` for more information.
 296 ///
 297 /// # Example
 298 ///
 299 /// ```
 300 /// format!("test");
 301 /// format!("hello {}", "world!");
 302 /// format!("x = {}, y = {y}", 10i, y = 30i);
 303 /// ```
 304 #[macro_export]
 305 #[stable]
 306 macro_rules! format {
 307     ($($arg:tt)*) => (::std::fmt::format(format_args!($($arg)*)))
 308 }
 309
 310 // NOTE(stage0): Remove macro after a snapshot
 311 #[cfg(stage0)]
 312 /// Use the syntax described in `std::fmt` to create a value of type `String`.
 313 /// See `std::fmt` for more information.
 314 ///
 315 /// # Example
 316 ///
 317 /// ```
 318 /// format!("test");
 319 /// format!("hello {}", "world!");
 320 /// format!("x = {}, y = {y}", 10i, y = 30i);
 321 /// ```
 322 #[macro_export]
 323 #[stable]
 324 macro_rules! format {
 325     ($($arg:tt)*) => (
 326         format_args!(::std::fmt::format, $($arg)*)
 327     )
 328 }
 329
 330 // NOTE(stage0): Remove cfg after a snapshot
 331 #[cfg(not(stage0))]
 332 /// Use the `format!` syntax to write data into a buffer of type `&mut Writer`.
 333 /// See `std::fmt` for more information.
 334 ///
 335 /// # Example
 336 ///
 337 /// ```
 338 /// # #![allow(unused_must_use)]
 339 ///
 340 /// let mut w = Vec::new();
 341 /// write!(&mut w, "test");
 342 /// write!(&mut w, "formatted {}", "arguments");
 343 /// ```
 344 #[macro_export]
 345 #[stable]
 346 macro_rules! write {
 347     ($dst:expr, $($arg:tt)*) => ((&mut *$dst).write_fmt(format_args!($($arg)*)))
 348 }
 349
 350 // NOTE(stage0): Remove macro after a snapshot
 351 #[cfg(stage0)]
 352 /// Use the `format!` syntax to write data into a buffer of type `&mut Writer`.
 353 /// See `std::fmt` for more information.
 354 ///
 355 /// # Example
 356 ///
 357 /// ```
 358 /// # #![allow(unused_must_use)]
 359 ///
 360 /// let mut w = Vec::new();
 361 /// write!(&mut w, "test");
 362 /// write!(&mut w, "formatted {}", "arguments");
 363 /// ```
 364 #[macro_export]
 365 #[stable]
 366 macro_rules! write {
 367     ($dst:expr, $($arg:tt)*) => ({
 368         let dst = &mut *$dst;
 369         format_args!(|args| { dst.write_fmt(args) }, $($arg)*)
 370     })
 371 }
 372
 373 /// Equivalent to the `write!` macro, except that a newline is appended after
 374 /// the message is written.
 375 #[macro_export]
 376 #[stable]
 377 macro_rules! writeln {
 378     ($dst:expr, $fmt:expr $($arg:tt)*) => (
 379         write!($dst, concat!($fmt, "\n") $($arg)*)
 380     )
 381 }
 382
 383 // NOTE(stage0): Remove cfg after a snapshot
 384 #[cfg(not(stage0))]
 385 /// Equivalent to the `println!` macro except that a newline is not printed at
 386 /// the end of the message.
 387 #[macro_export]
 388 #[stable]
 389 macro_rules! print {
 390     ($($arg:tt)*) => (::std::io::stdio::print_args(format_args!($($arg)*)))
 391 }
 392
 393 // NOTE(stage0): Remove macro after a snapshot
 394 #[cfg(stage0)]
 395 /// Equivalent to the `println!` macro except that a newline is not printed at
 396 /// the end of the message.
 397 #[macro_export]
 398 #[stable]
 399 macro_rules! print {
 400     ($($arg:tt)*) => (format_args!(::std::io::stdio::print_args, $($arg)*))
 401 }
 402
 403 // NOTE(stage0): Remove cfg after a snapshot
 404 #[cfg(not(stage0))]
 405 /// Macro for printing to a task's stdout handle.
 406 ///
 407 /// Each task can override its stdout handle via `std::io::stdio::set_stdout`.
 408 /// The syntax of this macro is the same as that used for `format!`. For more
 409 /// information, see `std::fmt` and `std::io::stdio`.
 410 ///
 411 /// # Example
 412 ///
 413 /// ```
 414 /// println!("hello there!");
 415 /// println!("format {} arguments", "some");
 416 /// ```
 417 #[macro_export]
 418 #[stable]
 419 macro_rules! println {
 420     ($($arg:tt)*) => (::std::io::stdio::println_args(format_args!($($arg)*)))
 421 }
 422
 423 // NOTE(stage0): Remove macro after a snapshot
 424 #[cfg(stage0)]
 425 /// Macro for printing to a task's stdout handle.
 426 ///
 427 /// Each task can override its stdout handle via `std::io::stdio::set_stdout`.
 428 /// The syntax of this macro is the same as that used for `format!`. For more
 429 /// information, see `std::fmt` and `std::io::stdio`.
 430 ///
 431 /// # Example
 432 ///
 433 /// ```
 434 /// println!("hello there!");
 435 /// println!("format {} arguments", "some");
 436 /// ```
 437 #[macro_export]
 438 #[stable]
 439 macro_rules! println {
 440     ($($arg:tt)*) => (format_args!(::std::io::stdio::println_args, $($arg)*))
 441 }
 442
 443 /// Helper macro for unwrapping `Result` values while returning early with an
 444 /// error if the value of the expression is `Err`. For more information, see
 445 /// `std::io`.
 446 #[macro_export]
 447 macro_rules! try {
 448     ($expr:expr) => ({
 449         match $expr {
 450             Ok(val) => val,
 451             Err(err) => return Err(::std::error::FromError::from_error(err))
 452         }
 453     })
 454 }
 455
 456 /// Create a `std::vec::Vec` containing the arguments.
 457 #[macro_export]
 458 macro_rules! vec {
 459     ($($x:expr),*) => ({
 460         use std::slice::BoxedSliceExt;
 461         let xs: ::std::boxed::Box<[_]> = box [$($x),*];
 462         xs.into_vec()
 463     });
 464     ($($x:expr,)*) => (vec![$($x),*])
 465 }
 466
 467 /// A macro to select an event from a number of receivers.
 468 ///
 469 /// This macro is used to wait for the first event to occur on a number of
 470 /// receivers. It places no restrictions on the types of receivers given to
 471 /// this macro, this can be viewed as a heterogeneous select.
 472 ///
 473 /// # Example
 474 ///
 475 /// ```
 476 /// use std::thread::Thread;
 477 ///
 478 /// let (tx1, rx1) = channel();
 479 /// let (tx2, rx2) = channel();
 480 /// # fn long_running_task() {}
 481 /// # fn calculate_the_answer() -> int { 42i }
 482 ///
 483 /// Thread::spawn(move|| { long_running_task(); tx1.send(()) }).detach();
 484 /// Thread::spawn(move|| { tx2.send(calculate_the_answer()) }).detach();
 485 ///
 486 /// select! (
 487 ///     () = rx1.recv() => println!("the long running task finished first"),
 488 ///     answer = rx2.recv() => {
 489 ///         println!("the answer was: {}", answer);
 490 ///     }
 491 /// )
 492 /// ```
 493 ///
 494 /// For more information about select, see the `std::comm::Select` structure.
 495 #[macro_export]
 496 #[experimental]
 497 macro_rules! select {
 498     (
 499         $($name:pat = $rx:ident.$meth:ident() => $code:expr),+
 500     ) => ({
 501         use std::comm::Select;
 502         let sel = Select::new();
 503         $( let mut $rx = sel.handle(&$rx); )+
 504         unsafe {
 505             $( $rx.add(); )+
 506         }
 507         let ret = sel.wait();
 508         $( if ret == $rx.id() { let $name = $rx.$meth(); $code } else )+
 509         { unreachable!() }
 510     })
 511 }
 512
 513 // When testing the standard library, we link to the liblog crate to get the
 514 // logging macros. In doing so, the liblog crate was linked against the real
 515 // version of libstd, and uses a different std::fmt module than the test crate
 516 // uses. To get around this difference, we redefine the log!() macro here to be
 517 // just a dumb version of what it should be.
 518 #[cfg(test)]
 519 macro_rules! log {
 520     ($lvl:expr, $($args:tt)*) => (
 521         if log_enabled!($lvl) { println!($($args)*) }
 522     )
 523 }
 524
 525 /// Built-in macros to the compiler itself.
 526 ///
 527 /// These macros do not have any corresponding definition with a `macro_rules!`
 528 /// macro, but are documented here. Their implementations can be found hardcoded
 529 /// into libsyntax itself.
 530 #[cfg(dox)]
 531 pub mod builtin {
 532     /// The core macro for formatted string creation & output.
 533     ///
 534     /// This macro produces a value of type `fmt::Arguments`. This value can be
 535     /// passed to the functions in `std::fmt` for performing useful functions.
 536     /// All other formatting macros (`format!`, `write!`, `println!`, etc) are
 537     /// proxied through this one.
 538     ///
 539     /// For more information, see the documentation in `std::fmt`.
 540     ///
 541     /// # Example
 542     ///
 543     /// ```rust
 544     /// use std::fmt;
 545     ///
 546     /// let s = fmt::format(format_args!("hello {}", "world"));
 547     /// assert_eq!(s, format!("hello {}", "world"));
 548     ///
 549     /// ```
 550     #[macro_export]
 551     macro_rules! format_args { ($fmt:expr $($args:tt)*) => ({
 552         /* compiler built-in */
 553     }) }
 554
 555     /// Inspect an environment variable at compile time.
 556     ///
 557     /// This macro will expand to the value of the named environment variable at
 558     /// compile time, yielding an expression of type `&'static str`.
 559     ///
 560     /// If the environment variable is not defined, then a compilation error
 561     /// will be emitted.  To not emit a compile error, use the `option_env!`
 562     /// macro instead.
 563     ///
 564     /// # Example
 565     ///
 566     /// ```rust
 567     /// let path: &'static str = env!("PATH");
 568     /// println!("the $PATH variable at the time of compiling was: {}", path);
 569     /// ```
 570     #[macro_export]
 571     macro_rules! env { ($name:expr) => ({ /* compiler built-in */ }) }
 572
 573     /// Optionally inspect an environment variable at compile time.
 574     ///
 575     /// If the named environment variable is present at compile time, this will
 576     /// expand into an expression of type `Option<&'static str>` whose value is
 577     /// `Some` of the value of the environment variable. If the environment
 578     /// variable is not present, then this will expand to `None`.
 579     ///
 580     /// A compile time error is never emitted when using this macro regardless
 581     /// of whether the environment variable is present or not.
 582     ///
 583     /// # Example
 584     ///
 585     /// ```rust
 586     /// let key: Option<&'static str> = option_env!("SECRET_KEY");
 587     /// println!("the secret key might be: {}", key);
 588     /// ```
 589     #[macro_export]
 590     macro_rules! option_env { ($name:expr) => ({ /* compiler built-in */ }) }
 591
 592     /// Concatenate literals into a static byte slice.
 593     ///
 594     /// This macro takes any number of comma-separated literal expressions,
 595     /// yielding an expression of type `&'static [u8]` which is the
 596     /// concatenation (left to right) of all the literals in their byte format.
 597     ///
 598     /// This extension currently only supports string literals, character
 599     /// literals, and integers less than 256. The byte slice returned is the
 600     /// utf8-encoding of strings and characters.
 601     ///
 602     /// # Example
 603     ///
 604     /// ```
 605     /// let rust = bytes!("r", 'u', "st", 255);
 606     /// assert_eq!(rust[1], b'u');
 607     /// assert_eq!(rust[4], 255);
 608     /// ```
 609     #[macro_export]
 610     macro_rules! bytes { ($($e:expr),*) => ({ /* compiler built-in */ }) }
 611
 612     /// Concatenate identifiers into one identifier.
 613     ///
 614     /// This macro takes any number of comma-separated identifiers, and
 615     /// concatenates them all into one, yielding an expression which is a new
 616     /// identifier. Note that hygiene makes it such that this macro cannot
 617     /// capture local variables, and macros are only allowed in item,
 618     /// statement or expression position, meaning this macro may be difficult to
 619     /// use in some situations.
 620     ///
 621     /// # Example
 622     ///
 623     /// ```
 624     /// #![feature(concat_idents)]
 625     ///
 626     /// # fn main() {
 627     /// fn foobar() -> int { 23 }
 628     ///
 629     /// let f = concat_idents!(foo, bar);
 630     /// println!("{}", f());
 631     /// # }
 632     /// ```
 633     #[macro_export]
 634     macro_rules! concat_idents {
 635         ($($e:ident),*) => ({ /* compiler built-in */ })
 636     }
 637
 638     /// Concatenates literals into a static string slice.
 639     ///
 640     /// This macro takes any number of comma-separated literals, yielding an
 641     /// expression of type `&'static str` which represents all of the literals
 642     /// concatenated left-to-right.
 643     ///
 644     /// Integer and floating point literals are stringified in order to be
 645     /// concatenated.
 646     ///
 647     /// # Example
 648     ///
 649     /// ```
 650     /// let s = concat!("test", 10i, 'b', true);
 651     /// assert_eq!(s, "test10btrue");
 652     /// ```
 653     #[macro_export]
 654     macro_rules! concat { ($($e:expr),*) => ({ /* compiler built-in */ }) }
 655
 656     /// A macro which expands to the line number on which it was invoked.
 657     ///
 658     /// The expanded expression has type `uint`, and the returned line is not
 659     /// the invocation of the `line!()` macro itself, but rather the first macro
 660     /// invocation leading up to the invocation of the `line!()` macro.
 661     ///
 662     /// # Example
 663     ///
 664     /// ```
 665     /// let current_line = line!();
 666     /// println!("defined on line: {}", current_line);
 667     /// ```
 668     #[macro_export]
 669     macro_rules! line { () => ({ /* compiler built-in */ }) }
 670
 671     /// A macro which expands to the column number on which it was invoked.
 672     ///
 673     /// The expanded expression has type `uint`, and the returned column is not
 674     /// the invocation of the `column!()` macro itself, but rather the first macro
 675     /// invocation leading up to the invocation of the `column!()` macro.
 676     ///
 677     /// # Example
 678     ///
 679     /// ```
 680     /// let current_col = column!();
 681     /// println!("defined on column: {}", current_col);
 682     /// ```
 683     #[macro_export]
 684     macro_rules! column { () => ({ /* compiler built-in */ }) }
 685
 686     /// A macro which expands to the file name from which it was invoked.
 687     ///
 688     /// The expanded expression has type `&'static str`, and the returned file
 689     /// is not the invocation of the `file!()` macro itself, but rather the
 690     /// first macro invocation leading up to the invocation of the `file!()`
 691     /// macro.
 692     ///
 693     /// # Example
 694     ///
 695     /// ```
 696     /// let this_file = file!();
 697     /// println!("defined in file: {}", this_file);
 698     /// ```
 699     #[macro_export]
 700     macro_rules! file { () => ({ /* compiler built-in */ }) }
 701
 702     /// A macro which stringifies its argument.
 703     ///
 704     /// This macro will yield an expression of type `&'static str` which is the
 705     /// stringification of all the tokens passed to the macro. No restrictions
 706     /// are placed on the syntax of the macro invocation itself.
 707     ///
 708     /// # Example
 709     ///
 710     /// ```
 711     /// let one_plus_one = stringify!(1 + 1);
 712     /// assert_eq!(one_plus_one, "1 + 1");
 713     /// ```
 714     #[macro_export]
 715     macro_rules! stringify { ($t:tt) => ({ /* compiler built-in */ }) }
 716
 717     /// Includes a utf8-encoded file as a string.
 718     ///
 719     /// This macro will yield an expression of type `&'static str` which is the
 720     /// contents of the filename specified. The file is located relative to the
 721     /// current file (similarly to how modules are found),
 722     ///
 723     /// # Example
 724     ///
 725     /// ```rust,ignore
 726     /// let secret_key = include_str!("secret-key.ascii");
 727     /// ```
 728     #[macro_export]
 729     macro_rules! include_str { ($file:expr) => ({ /* compiler built-in */ }) }
 730
 731     /// Includes a file as a byte slice.
 732     ///
 733     /// This macro will yield an expression of type `&'static [u8]` which is
 734     /// the contents of the filename specified. The file is located relative to
 735     /// the current file (similarly to how modules are found),
 736     ///
 737     /// # Example
 738     ///
 739     /// ```rust,ignore
 740     /// let secret_key = include_bytes!("secret-key.bin");
 741     /// ```
 742     #[macro_export]
 743     macro_rules! include_bytes { ($file:expr) => ({ /* compiler built-in */ }) }
 744
 745     /// Deprecated alias for `include_bytes!()`.
 746     #[macro_export]
 747     macro_rules! include_bin { ($file:expr) => ({ /* compiler built-in */}) }
 748
 749     /// Expands to a string that represents the current module path.
 750     ///
 751     /// The current module path can be thought of as the hierarchy of modules
 752     /// leading back up to the crate root. The first component of the path
 753     /// returned is the name of the crate currently being compiled.
 754     ///
 755     /// # Example
 756     ///
 757     /// ```rust
 758     /// mod test {
 759     ///     pub fn foo() {
 760     ///         assert!(module_path!().ends_with("test"));
 761     ///     }
 762     /// }
 763     ///
 764     /// test::foo();
 765     /// ```
 766     #[macro_export]
 767     macro_rules! module_path { () => ({ /* compiler built-in */ }) }
 768
 769     /// Boolean evaluation of configuration flags.
 770     ///
 771     /// In addition to the `#[cfg]` attribute, this macro is provided to allow
 772     /// boolean expression evaluation of configuration flags. This frequently
 773     /// leads to less duplicated code.
 774     ///
 775     /// The syntax given to this macro is the same syntax as the `cfg`
 776     /// attribute.
 777     ///
 778     /// # Example
 779     ///
 780     /// ```rust
 781     /// let my_directory = if cfg!(windows) {
 782     ///     "windows-specific-directory"
 783     /// } else {
 784     ///     "unix-directory"
 785     /// };
 786     /// ```
 787     #[macro_export]
 788     macro_rules! cfg { ($cfg:tt) => ({ /* compiler built-in */ }) }
 789 }