src/liblog/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 //! Logging macros
  12
  13 #![macro_escape]
  14
  15 /// The standard logging macro
  16 ///
  17 /// This macro will generically log over a provided level (of type u32) with a
  18 /// format!-based argument list. See documentation in `std::fmt` for details on
  19 /// how to use the syntax.
  20 ///
  21 /// # Example
  22 ///
  23 /// ```
  24 /// #[feature(phase)];
  25 /// #[phase(syntax, link)] extern crate log;
  26 ///
  27 /// # fn main() {
  28 /// log!(log::DEBUG, "this is a debug message");
  29 /// log!(log::WARN, "this is a warning {}", "message");
  30 /// log!(6, "this is a custom logging level: {level}", level=6);
  31 /// # }
  32 /// ```
  33 #[macro_export]
  34 macro_rules! log(
  35     ($lvl:expr, $($arg:tt)+) => ({
  36         let lvl = $lvl;
  37         if log_enabled!(lvl) {
  38             format_args!(|args| { ::log::log(lvl, args) }, $($arg)+)
  39         }
  40     })
  41 )
  42
  43 /// A convenience macro for logging at the error log level.
  44 ///
  45 /// # Example
  46 ///
  47 /// ```
  48 /// #[feature(phase)];
  49 /// #[phase(syntax, link)] extern crate log;
  50 ///
  51 /// # fn main() {
  52 /// # let error = 3;
  53 /// error!("the build has failed with error code: {}", error);
  54 /// # }
  55 /// ```
  56 #[macro_export]
  57 macro_rules! error(
  58     ($($arg:tt)*) => (log!(::log::ERROR, $($arg)*))
  59 )
  60
  61 /// A convenience macro for logging at the warning log level.
  62 ///
  63 /// # Example
  64 ///
  65 /// ```
  66 /// #[feature(phase)];
  67 /// #[phase(syntax, link)] extern crate log;
  68 ///
  69 /// # fn main() {
  70 /// # let code = 3;
  71 /// warn!("you may like to know that a process exited with: {}", code);
  72 /// # }
  73 /// ```
  74 #[macro_export]
  75 macro_rules! warn(
  76     ($($arg:tt)*) => (log!(::log::WARN, $($arg)*))
  77 )
  78
  79 /// A convenience macro for logging at the info log level.
  80 ///
  81 /// # Example
  82 ///
  83 /// ```
  84 /// #[feature(phase)];
  85 /// #[phase(syntax, link)] extern crate log;
  86 ///
  87 /// # fn main() {
  88 /// # let ret = 3;
  89 /// info!("this function is about to return: {}", ret);
  90 /// # }
  91 /// ```
  92 #[macro_export]
  93 macro_rules! info(
  94     ($($arg:tt)*) => (log!(::log::INFO, $($arg)*))
  95 )
  96
  97 /// A convenience macro for logging at the debug log level. This macro can also
  98 /// be omitted at compile time by passing `--cfg ndebug` to the compiler. If
  99 /// this option is not passed, then debug statements will be compiled.
 100 ///
 101 /// # Example
 102 ///
 103 /// ```
 104 /// #[feature(phase)];
 105 /// #[phase(syntax, link)] extern crate log;
 106 ///
 107 /// # fn main() {
 108 /// debug!("x = {x}, y = {y}", x=10, y=20);
 109 /// # }
 110 /// ```
 111 #[macro_export]
 112 macro_rules! debug(
 113     ($($arg:tt)*) => (if cfg!(not(ndebug)) { log!(::log::DEBUG, $($arg)*) })
 114 )
 115
 116 /// A macro to test whether a log level is enabled for the current module.
 117 ///
 118 /// # Example
 119 ///
 120 /// ```
 121 /// #[feature(phase)];
 122 /// #[phase(syntax, link)] extern crate log;
 123 ///
 124 /// # fn main() {
 125 /// # struct Point { x: int, y: int }
 126 /// # fn some_expensive_computation() -> Point { Point { x: 1, y: 2 } }
 127 /// if log_enabled!(log::DEBUG) {
 128 ///     let x = some_expensive_computation();
 129 ///     debug!("x.x = {}, x.y = {}", x.x, x.y);
 130 /// }
 131 /// # }
 132 /// ```
 133 #[macro_export]
 134 macro_rules! log_enabled(
 135     ($lvl:expr) => ({
 136         let lvl = $lvl;
 137         (lvl != ::log::DEBUG || cfg!(not(ndebug))) &&
 138         lvl <= ::log::log_level() &&
 139         ::log::mod_enabled(lvl, module_path!())
 140     })
 141 )