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(plugin, link)] extern crate log;
  26 ///
  27 /// fn main() {
  28 ///     log!(log::WARN, "this is a warning {}", "message");
  29 ///     log!(log::DEBUG, "this is a debug message");
  30 ///     log!(6, "this is a custom logging level: {level}", level=6u);
  31 /// }
  32 /// ```
  33 ///
  34 /// Assumes the binary is `main`:
  35 ///
  36 /// ```{.bash}
  37 /// $ RUST_LOG=warn ./main
  38 /// WARN:main: this is a warning message
  39 /// ```
  40 ///
  41 /// ```{.bash}
  42 /// $ RUST_LOG=debug ./main
  43 /// DEBUG:main: this is a debug message
  44 /// WARN:main: this is a warning message
  45 /// ```
  46 ///
  47 /// ```{.bash}
  48 /// $ RUST_LOG=6 ./main
  49 /// DEBUG:main: this is a debug message
  50 /// WARN:main: this is a warning message
  51 /// 6:main: this is a custom logging level: 6
  52 /// ```
  53 #[macro_export]
  54 macro_rules! log {
  55     ($lvl:expr, $($arg:tt)+) => ({
  56         static LOC: ::log::LogLocation = ::log::LogLocation {
  57             line: line!(),
  58             file: file!(),
  59             module_path: module_path!(),
  60         };
  61         let lvl = $lvl;
  62         if log_enabled!(lvl) {
  63             ::log::log(lvl, &LOC, format_args!($($arg)+))
  64         }
  65     })
  66 }
  67
  68 /// A convenience macro for logging at the error log level.
  69 ///
  70 /// # Example
  71 ///
  72 /// ```
  73 /// #![feature(phase)]
  74 /// #[phase(plugin, link)] extern crate log;
  75 ///
  76 /// fn main() {
  77 ///     let error = 3u;
  78 ///     error!("the build has failed with error code: {}", error);
  79 /// }
  80 /// ```
  81 ///
  82 /// Assumes the binary is `main`:
  83 ///
  84 /// ```{.bash}
  85 /// $ RUST_LOG=error ./main
  86 /// ERROR:main: the build has failed with error code: 3
  87 /// ```
  88 ///
  89 #[macro_export]
  90 macro_rules! error {
  91     ($($arg:tt)*) => (log!(::log::ERROR, $($arg)*))
  92 }
  93
  94 /// A convenience macro for logging at the warning log level.
  95 ///
  96 /// # Example
  97 ///
  98 /// ```
  99 /// #![feature(phase)]
 100 /// #[phase(plugin, link)] extern crate log;
 101 ///
 102 /// fn main() {
 103 ///     let code = 3u;
 104 ///     warn!("you may like to know that a process exited with: {}", code);
 105 /// }
 106 /// ```
 107 ///
 108 /// Assumes the binary is `main`:
 109 ///
 110 /// ```{.bash}
 111 /// $ RUST_LOG=warn ./main
 112 /// WARN:main: you may like to know that a process exited with: 3
 113 /// ```
 114 #[macro_export]
 115 macro_rules! warn {
 116     ($($arg:tt)*) => (log!(::log::WARN, $($arg)*))
 117 }
 118
 119 /// A convenience macro for logging at the info log level.
 120 ///
 121 /// # Example
 122 ///
 123 /// ```
 124 /// #![feature(phase)]
 125 /// #[phase(plugin, link)] extern crate log;
 126 ///
 127 /// fn main() {
 128 ///     let ret = 3;
 129 ///     info!("this function is about to return: {}", ret);
 130 /// }
 131 /// ```
 132 ///
 133 /// Assumes the binary is `main`:
 134 ///
 135 /// ```{.bash}
 136 /// $ RUST_LOG=info ./main
 137 /// INFO:main: this function is about to return: 3
 138 /// ```
 139 #[macro_export]
 140 macro_rules! info {
 141     ($($arg:tt)*) => (log!(::log::INFO, $($arg)*))
 142 }
 143
 144 /// A convenience macro for logging at the debug log level. This macro can also
 145 /// be omitted at compile time by passing `--cfg ndebug` to the compiler. If
 146 /// this option is not passed, then debug statements will be compiled.
 147 ///
 148 /// # Example
 149 ///
 150 /// ```
 151 /// #![feature(phase)]
 152 /// #[phase(plugin, link)] extern crate log;
 153 ///
 154 /// fn main() {
 155 ///     debug!("x = {x}, y = {y}", x=10, y=20);
 156 /// }
 157 /// ```
 158 ///
 159 /// Assumes the binary is `main`:
 160 ///
 161 /// ```{.bash}
 162 /// $ RUST_LOG=debug ./main
 163 /// DEBUG:main: x = 10, y = 20
 164 /// ```
 165 #[macro_export]
 166 macro_rules! debug {
 167     ($($arg:tt)*) => (if cfg!(not(ndebug)) { log!(::log::DEBUG, $($arg)*) })
 168 }
 169
 170 /// A macro to test whether a log level is enabled for the current module.
 171 ///
 172 /// # Example
 173 ///
 174 /// ```
 175 /// #![feature(phase)]
 176 /// #[phase(plugin, link)] extern crate log;
 177 ///
 178 /// struct Point { x: int, y: int }
 179 /// fn some_expensive_computation() -> Point { Point { x: 1, y: 2 } }
 180 ///
 181 /// fn main() {
 182 ///     if log_enabled!(log::DEBUG) {
 183 ///         let x = some_expensive_computation();
 184 ///         debug!("x.x = {}, x.y = {}", x.x, x.y);
 185 ///     }
 186 /// }
 187 /// ```
 188 ///
 189 /// Assumes the binary is `main`:
 190 ///
 191 /// ```{.bash}
 192 /// $ RUST_LOG=error ./main
 193 /// ```
 194 ///
 195 /// ```{.bash}
 196 /// $ RUST_LOG=debug ./main
 197 /// DEBUG:main: x.x = 1, x.y = 2
 198 /// ```
 199 #[macro_export]
 200 macro_rules! log_enabled {
 201     ($lvl:expr) => ({
 202         let lvl = $lvl;
 203         (lvl != ::log::DEBUG || cfg!(not(ndebug))) &&
 204         lvl <= ::log::log_level() &&
 205         ::log::mod_enabled(lvl, module_path!())
 206     })
 207 }
 208