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::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=6u);
  31 /// # }
  32 /// ```
  33 #[macro_export]
  34 macro_rules! log(
  35     ($lvl:expr, $($arg:tt)+) => ({
  36         static LOC: ::log::LogLocation = ::log::LogLocation {
  37             line: line!(),
  38             file: file!(),
  39             module_path: module_path!(),
  40         };
  41         let lvl = $lvl;
  42         if log_enabled!(lvl) {
  43             format_args!(|args| { ::log::log(lvl, &LOC, args) }, $($arg)+)
  44         }
  45     })
  46 )
  47
  48 /// A convenience macro for logging at the error log level.
  49 ///
  50 /// # Example
  51 ///
  52 /// ```
  53 /// #![feature(phase)]
  54 /// #[phase(plugin, link)] extern crate log;
  55 ///
  56 /// # fn main() {
  57 /// # let error = 3u;
  58 /// error!("the build has failed with error code: {}", error);
  59 /// # }
  60 /// ```
  61 #[macro_export]
  62 macro_rules! error(
  63     ($($arg:tt)*) => (log!(::log::ERROR, $($arg)*))
  64 )
  65
  66 /// A convenience macro for logging at the warning log level.
  67 ///
  68 /// # Example
  69 ///
  70 /// ```
  71 /// #![feature(phase)]
  72 /// #[phase(plugin, link)] extern crate log;
  73 ///
  74 /// # fn main() {
  75 /// # let code = 3u;
  76 /// warn!("you may like to know that a process exited with: {}", code);
  77 /// # }
  78 /// ```
  79 #[macro_export]
  80 macro_rules! warn(
  81     ($($arg:tt)*) => (log!(::log::WARN, $($arg)*))
  82 )
  83
  84 /// A convenience macro for logging at the info log level.
  85 ///
  86 /// # Example
  87 ///
  88 /// ```
  89 /// #![feature(phase)]
  90 /// #[phase(plugin, link)] extern crate log;
  91 ///
  92 /// # fn main() {
  93 /// # let ret = 3i;
  94 /// info!("this function is about to return: {}", ret);
  95 /// # }
  96 /// ```
  97 #[macro_export]
  98 macro_rules! info(
  99     ($($arg:tt)*) => (log!(::log::INFO, $($arg)*))
 100 )
 101
 102 /// A convenience macro for logging at the debug log level. This macro can also
 103 /// be omitted at compile time by passing `--cfg ndebug` to the compiler. If
 104 /// this option is not passed, then debug statements will be compiled.
 105 ///
 106 /// # Example
 107 ///
 108 /// ```
 109 /// #![feature(phase)]
 110 /// #[phase(plugin, link)] extern crate log;
 111 ///
 112 /// # fn main() {
 113 /// debug!("x = {x}, y = {y}", x=10i, y=20i);
 114 /// # }
 115 /// ```
 116 #[macro_export]
 117 macro_rules! debug(
 118     ($($arg:tt)*) => (if cfg!(not(ndebug)) { log!(::log::DEBUG, $($arg)*) })
 119 )
 120
 121 /// A macro to test whether a log level is enabled for the current module.
 122 ///
 123 /// # Example
 124 ///
 125 /// ```
 126 /// #![feature(phase)]
 127 /// #[phase(plugin, link)] extern crate log;
 128 ///
 129 /// # fn main() {
 130 /// # struct Point { x: int, y: int }
 131 /// # fn some_expensive_computation() -> Point { Point { x: 1, y: 2 } }
 132 /// if log_enabled!(log::DEBUG) {
 133 ///     let x = some_expensive_computation();
 134 ///     debug!("x.x = {}, x.y = {}", x.x, x.y);
 135 /// }
 136 /// # }
 137 /// ```
 138 #[macro_export]
 139 macro_rules! log_enabled(
 140     ($lvl:expr) => ({
 141         let lvl = $lvl;
 142         (lvl != ::log::DEBUG || cfg!(not(ndebug))) &&
 143         lvl <= ::log::log_level() &&
 144         ::log::mod_enabled(lvl, module_path!())
 145     })
 146 )