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