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