1// Copyright 2014-2015 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/// The standard logging macro.
12///
13/// This macro will generically log with the specified `Level` and `format!`
14/// based argument list.
15///
16/// ```
17/// use log::{log, Level};
18///
19/// let data = (42, "Forty-two");
20/// let private_data = "private";
21///
22/// log!(Level::Error, "Received errors: {}, {}", data.0, data.1);
23/// ```
24///
25/// Optionally, you can specify a `target` argument to attach a specific target
26/// to the log record. By default, the target is the module path of the caller.
27///
28/// ```
29/// use log::{log, Level};
30///
31/// let data = (42, "Forty-two");
32/// let private_data = "private";
33///
34/// log!(
35/// target: "app_events",
36/// Level::Error,
37/// "Received errors: {}, {}",
38/// data.0, data.1
39/// );
40/// ```
41///
42/// And optionally, you can specify a `logger` argument to use a specific logger
43/// instead of the default global logger.
44///
45/// ```
46/// # struct MyLogger {}
47/// # impl Log for MyLogger {
48/// # fn enabled(&self, _metadata: &log::Metadata) -> bool {
49/// # false
50/// # }
51/// # fn log(&self, _record: &log::Record) {}
52/// # fn flush(&self) {}
53/// # }
54/// use log::{log, Level, Log};
55///
56/// let data = (42, "Forty-two");
57/// let private_data = "private";
58///
59/// let my_logger = MyLogger {};
60/// log!(
61/// logger: my_logger,
62/// Level::Error,
63/// "Received errors: {}, {}",
64/// data.0, data.1
65/// );
66/// ```
67///
68/// The `logger` argument accepts a value that implements the `Log` trait. The value
69/// will be borrowed within the macro.
70///
71/// Note that the global level set via Cargo features, or through `set_max_level` will
72/// still apply, even when a custom logger is supplied with the `logger` argument.
73#[macro_export]
74#[clippy::format_args]
75macro_rules! log {
76 // log!(logger: my_logger, target: "my_target", Level::Info, "a {} event", "log");
77 (logger: $logger:expr, target: $target:expr, $lvl:expr, $($arg:tt)+) => ({
78 $crate::__log!(
79 logger: $crate::__log_logger!($logger),
80 target: $target,
81 $lvl,
82 $($arg)+
83 )
84 });
85
86 // log!(logger: my_logger, Level::Info, "a log event")
87 (logger: $logger:expr, $lvl:expr, $($arg:tt)+) => ({
88 $crate::__log!(
89 logger: $crate::__log_logger!($logger),
90 target: $crate::__private_api::module_path!(),
91 $lvl,
92 $($arg)+
93 )
94 });
95
96 // log!(target: "my_target", Level::Info, "a log event")
97 (target: $target:expr, $lvl:expr, $($arg:tt)+) => ({
98 $crate::__log!(
99 logger: $crate::__log_logger!(__log_global_logger),
100 target: $target,
101 $lvl,
102 $($arg)+
103 )
104 });
105
106 // log!(Level::Info, "a log event")
107 ($lvl:expr, $($arg:tt)+) => ({
108 $crate::__log!(
109 logger: $crate::__log_logger!(__log_global_logger),
110 target: $crate::__private_api::module_path!(),
111 $lvl,
112 $($arg)+
113 )
114 });
115}
116
117#[doc(hidden)]
118#[macro_export]
119macro_rules! __log {
120 // log!(logger: my_logger, target: "my_target", Level::Info, key1:? = 42, key2 = true; "a {} event", "log");
121 (logger: $logger:expr, target: $target:expr, $lvl:expr, $($key:tt $(:$capture:tt)? $(= $value:expr)?),+; $($arg:tt)+) => ({
122 let lvl = $lvl;
123 if lvl <= $crate::STATIC_MAX_LEVEL && lvl <= $crate::max_level() {
124 $crate::__private_api::log(
125 $logger,
126 $crate::__private_api::format_args!($($arg)+),
127 lvl,
128 &($target, $crate::__private_api::module_path!(), $crate::__private_api::loc()),
129 &[$(($crate::__log_key!($key), $crate::__log_value!($key $(:$capture)* = $($value)*))),+] as &[_],
130 );
131 }
132 });
133
134 // log!(logger: my_logger, target: "my_target", Level::Info, "a {} event", "log");
135 (logger: $logger:expr, target: $target:expr, $lvl:expr, $($arg:tt)+) => ({
136 let lvl = $lvl;
137 if lvl <= $crate::STATIC_MAX_LEVEL && lvl <= $crate::max_level() {
138 $crate::__private_api::log(
139 $logger,
140 $crate::__private_api::format_args!($($arg)+),
141 lvl,
142 &($target, $crate::__private_api::module_path!(), $crate::__private_api::loc()),
143 (),
144 );
145 }
146 });
147}
148
149/// Logs a message at the error level.
150///
151/// # Examples
152///
153/// ```
154/// use log::error;
155///
156/// # let my_logger = log::__private_api::GlobalLogger;
157/// let (err_info, port) = ("No connection", 22);
158///
159/// error!("Error: {err_info} on port {port}");
160/// error!(target: "app_events", "App Error: {err_info}, Port: {port}");
161/// error!(logger: my_logger, "App Error: {err_info}, Port: {port}");
162/// ```
163#[macro_export]
164#[clippy::format_args]
165macro_rules! error {
166 // error!(logger: my_logger, target: "my_target", key1 = 42, key2 = true; "a {} event", "log")
167 // error!(logger: my_logger, target: "my_target", "a {} event", "log")
168 (logger: $logger:expr, target: $target:expr, $($arg:tt)+) => ({
169 $crate::log!(logger: $crate::__log_logger!($logger), target: $target, $crate::Level::Error, $($arg)+)
170 });
171
172 // error!(logger: my_logger, key1 = 42, key2 = true; "a {} event", "log")
173 // error!(logger: my_logger, "a {} event", "log")
174 (logger: $logger:expr, $($arg:tt)+) => ({
175 $crate::log!(logger: $crate::__log_logger!($logger), $crate::Level::Error, $($arg)+)
176 });
177
178 // error!(target: "my_target", key1 = 42, key2 = true; "a {} event", "log")
179 // error!(target: "my_target", "a {} event", "log")
180 (target: $target:expr, $($arg:tt)+) => ({
181 $crate::log!(target: $target, $crate::Level::Error, $($arg)+)
182 });
183
184 // error!("a {} event", "log")
185 ($($arg:tt)+) => ($crate::log!($crate::Level::Error, $($arg)+))
186}
187
188/// Logs a message at the warn level.
189///
190/// # Examples
191///
192/// ```
193/// use log::warn;
194///
195/// # let my_logger = log::__private_api::GlobalLogger;
196/// let warn_description = "Invalid Input";
197///
198/// warn!("Warning! {warn_description}!");
199/// warn!(target: "input_events", "App received warning: {warn_description}");
200/// warn!(logger: my_logger, "App received warning: {warn_description}");
201/// ```
202#[macro_export]
203#[clippy::format_args]
204macro_rules! warn {
205 // warn!(logger: my_logger, target: "my_target", key1 = 42, key2 = true; "a {} event", "log")
206 // warn!(logger: my_logger, target: "my_target", "a {} event", "log")
207 (logger: $logger:expr, target: $target:expr, $($arg:tt)+) => ({
208 $crate::log!(logger: $crate::__log_logger!($logger), target: $target, $crate::Level::Warn, $($arg)+)
209 });
210
211 // warn!(logger: my_logger, key1 = 42, key2 = true; "a {} event", "log")
212 // warn!(logger: my_logger, "a {} event", "log")
213 (logger: $logger:expr, $($arg:tt)+) => ({
214 $crate::log!(logger: $crate::__log_logger!($logger), $crate::Level::Warn, $($arg)+)
215 });
216
217 // warn!(target: "my_target", key1 = 42, key2 = true; "a {} event", "log")
218 // warn!(target: "my_target", "a {} event", "log")
219 (target: $target:expr, $($arg:tt)+) => ({
220 $crate::log!(target: $target, $crate::Level::Warn, $($arg)+)
221 });
222
223 // warn!("a {} event", "log")
224 ($($arg:tt)+) => ($crate::log!($crate::Level::Warn, $($arg)+))
225}
226
227/// Logs a message at the info level.
228///
229/// # Examples
230///
231/// ```
232/// use log::info;
233///
234/// # let my_logger = log::__private_api::GlobalLogger;
235/// # struct Connection { port: u32, speed: f32 }
236/// let conn_info = Connection { port: 40, speed: 3.20 };
237///
238/// info!("Connected to port {} at {} Mb/s", conn_info.port, conn_info.speed);
239/// info!(
240/// target: "connection_events",
241/// "Successful connection, port: {}, speed: {}",
242/// conn_info.port, conn_info.speed
243/// );
244/// info!(
245/// logger: my_logger,
246/// "Successful connection, port: {}, speed: {}",
247/// conn_info.port, conn_info.speed
248/// );
249/// ```
250#[macro_export]
251#[clippy::format_args]
252macro_rules! info {
253 // info!(logger: my_logger, target: "my_target", key1 = 42, key2 = true; "a {} event", "log")
254 // info!(logger: my_logger, target: "my_target", "a {} event", "log")
255 (logger: $logger:expr, target: $target:expr, $($arg:tt)+) => ({
256 $crate::log!(logger: $crate::__log_logger!($logger), target: $target, $crate::Level::Info, $($arg)+)
257 });
258
259 // info!(logger: my_logger, key1 = 42, key2 = true; "a {} event", "log")
260 // info!(logger: my_logger, "a {} event", "log")
261 (logger: $logger:expr, $($arg:tt)+) => ({
262 $crate::log!(logger: $crate::__log_logger!($logger), $crate::Level::Info, $($arg)+)
263 });
264
265 // info!(target: "my_target", key1 = 42, key2 = true; "a {} event", "log")
266 // info!(target: "my_target", "a {} event", "log")
267 (target: $target:expr, $($arg:tt)+) => ({
268 $crate::log!(target: $target, $crate::Level::Info, $($arg)+)
269 });
270
271 // info!("a {} event", "log")
272 ($($arg:tt)+) => ($crate::log!($crate::Level::Info, $($arg)+))
273}
274
275/// Logs a message at the debug level.
276///
277/// # Examples
278///
279/// ```
280/// use log::debug;
281///
282/// # let my_logger = log::__private_api::GlobalLogger;
283/// # struct Position { x: f32, y: f32 }
284/// let pos = Position { x: 3.234, y: -1.223 };
285///
286/// debug!("New position: x: {}, y: {}", pos.x, pos.y);
287/// debug!(target: "app_events", "New position: x: {}, y: {}", pos.x, pos.y);
288/// debug!(logger: my_logger, "New position: x: {}, y: {}", pos.x, pos.y);
289/// ```
290#[macro_export]
291#[clippy::format_args]
292macro_rules! debug {
293 // debug!(logger: my_logger, target: "my_target", key1 = 42, key2 = true; "a {} event", "log")
294 // debug!(logger: my_logger, target: "my_target", "a {} event", "log")
295 (logger: $logger:expr, target: $target:expr, $($arg:tt)+) => ({
296 $crate::log!(logger: $crate::__log_logger!($logger), target: $target, $crate::Level::Debug, $($arg)+)
297 });
298
299 // debug!(logger: my_logger, key1 = 42, key2 = true; "a {} event", "log")
300 // debug!(logger: my_logger, "a {} event", "log")
301 (logger: $logger:expr, $($arg:tt)+) => ({
302 $crate::log!(logger: $crate::__log_logger!($logger), $crate::Level::Debug, $($arg)+)
303 });
304
305 // debug!(target: "my_target", key1 = 42, key2 = true; "a {} event", "log")
306 // debug!(target: "my_target", "a {} event", "log")
307 (target: $target:expr, $($arg:tt)+) => ({
308 $crate::log!(target: $target, $crate::Level::Debug, $($arg)+)
309 });
310
311 // debug!("a {} event", "log")
312 ($($arg:tt)+) => ($crate::log!($crate::Level::Debug, $($arg)+))
313}
314
315/// Logs a message at the trace level.
316///
317/// # Examples
318///
319/// ```
320/// use log::trace;
321///
322/// # let my_logger = log::__private_api::GlobalLogger;
323/// # struct Position { x: f32, y: f32 }
324/// let pos = Position { x: 3.234, y: -1.223 };
325///
326/// trace!("Position is: x: {}, y: {}", pos.x, pos.y);
327/// trace!(target: "app_events", "x is {} and y is {}",
328/// if pos.x >= 0.0 { "positive" } else { "negative" },
329/// if pos.y >= 0.0 { "positive" } else { "negative" });
330/// trace!(logger: my_logger, "x is {} and y is {}",
331/// if pos.x >= 0.0 { "positive" } else { "negative" },
332/// if pos.y >= 0.0 { "positive" } else { "negative" });
333/// ```
334#[macro_export]
335#[clippy::format_args]
336macro_rules! trace {
337 // trace!(logger: my_logger, target: "my_target", key1 = 42, key2 = true; "a {} event", "log")
338 // trace!(logger: my_logger, target: "my_target", "a {} event", "log")
339 (logger: $logger:expr, target: $target:expr, $($arg:tt)+) => ({
340 $crate::log!(logger: $crate::__log_logger!($logger), target: $target, $crate::Level::Trace, $($arg)+)
341 });
342
343 // trace!(logger: my_logger, key1 = 42, key2 = true; "a {} event", "log")
344 // trace!(logger: my_logger, "a {} event", "log")
345 (logger: $logger:expr, $($arg:tt)+) => ({
346 $crate::log!(logger: $crate::__log_logger!($logger), $crate::Level::Trace, $($arg)+)
347 });
348
349 // trace!(target: "my_target", key1 = 42, key2 = true; "a {} event", "log")
350 // trace!(target: "my_target", "a {} event", "log")
351 (target: $target:expr, $($arg:tt)+) => ({
352 $crate::log!(target: $target, $crate::Level::Trace, $($arg)+)
353 });
354
355 // trace!("a {} event", "log")
356 ($($arg:tt)+) => ($crate::log!($crate::Level::Trace, $($arg)+))
357}
358
359/// Determines if a message logged at the specified level in that module will
360/// be logged.
361///
362/// This can be used to avoid expensive computation of log message arguments if
363/// the message would be ignored anyway.
364///
365/// # Examples
366///
367/// ```
368/// use log::{debug, log_enabled, Level};
369///
370/// # struct Data { x: u32, y: u32 }
371/// # fn expensive_call() -> Data { Data { x: 0, y: 0 } }
372/// # let my_logger = log::__private_api::GlobalLogger;
373/// if log_enabled!(Level::Debug) {
374/// let data = expensive_call();
375/// debug!("expensive debug data: {} {}", data.x, data.y);
376/// }
377///
378/// if log_enabled!(target: "Global", Level::Debug) {
379/// let data = expensive_call();
380/// debug!(target: "Global", "expensive debug data: {} {}", data.x, data.y);
381/// }
382///
383/// if log_enabled!(logger: my_logger, Level::Debug) {
384/// let data = expensive_call();
385/// debug!(target: "Global", "expensive debug data: {} {}", data.x, data.y);
386/// }
387/// ```
388///
389/// This macro accepts the same `target` and `logger` arguments as [`macro@log`].
390#[macro_export]
391macro_rules! log_enabled {
392 // log_enabled!(logger: my_logger, target: "my_target", Level::Info)
393 (logger: $logger:expr, target: $target:expr, $lvl:expr) => ({
394 $crate::__log_enabled!(logger: $crate::__log_logger!($logger), target: $target, $lvl)
395 });
396
397 // log_enabled!(logger: my_logger, Level::Info)
398 (logger: $logger:expr, $lvl:expr) => ({
399 $crate::__log_enabled!(logger: $crate::__log_logger!($logger), target: $crate::__private_api::module_path!(), $lvl)
400 });
401
402 // log_enabled!(target: "my_target", Level::Info)
403 (target: $target:expr, $lvl:expr) => ({
404 $crate::__log_enabled!(logger: $crate::__log_logger!(__log_global_logger), target: $target, $lvl)
405 });
406
407 // log_enabled!(Level::Info)
408 ($lvl:expr) => ({
409 $crate::__log_enabled!(logger: $crate::__log_logger!(__log_global_logger), target: $crate::__private_api::module_path!(), $lvl)
410 });
411}
412
413#[doc(hidden)]
414#[macro_export]
415macro_rules! __log_enabled {
416 // log_enabled!(logger: my_logger, target: "my_target", Level::Info)
417 (logger: $logger:expr, target: $target:expr, $lvl:expr) => {{
418 let lvl = $lvl;
419 lvl <= $crate::STATIC_MAX_LEVEL
420 && lvl <= $crate::max_level()
421 && $crate::__private_api::enabled($logger, lvl, $target)
422 }};
423}
424
425// Determine the logger to use, and whether to take it by-value or by reference
426
427#[doc(hidden)]
428#[macro_export]
429macro_rules! __log_logger {
430 (__log_global_logger) => {{
431 $crate::__private_api::GlobalLogger
432 }};
433
434 ($logger:expr) => {{
435 &($logger)
436 }};
437}
438
439// These macros use a pattern of #[cfg]s to produce nicer error
440// messages when log features aren't available
441
442#[doc(hidden)]
443#[macro_export]
444#[cfg(feature = "kv")]
445macro_rules! __log_key {
446 // key1 = 42
447 ($($args:ident)*) => {
448 $crate::__private_api::stringify!($($args)*)
449 };
450 // "key1" = 42
451 ($($args:expr)*) => {
452 $($args)*
453 };
454}
455
456#[doc(hidden)]
457#[macro_export]
458#[cfg(not(feature = "kv"))]
459macro_rules! __log_key {
460 ($($args:tt)*) => {
461 compile_error!("key value support requires the `kv` feature of `log`")
462 };
463}
464
465#[doc(hidden)]
466#[macro_export]
467#[cfg(feature = "kv")]
468macro_rules! __log_value {
469 // Entrypoint
470 ($key:tt = $args:expr) => {
471 $crate::__log_value!(($args):value)
472 };
473 ($key:tt :$capture:tt = $args:expr) => {
474 $crate::__log_value!(($args):$capture)
475 };
476 ($key:ident =) => {
477 $crate::__log_value!(($key):value)
478 };
479 ($key:ident :$capture:tt =) => {
480 $crate::__log_value!(($key):$capture)
481 };
482 // ToValue
483 (($args:expr):value) => {
484 $crate::__private_api::capture_to_value(&&$args)
485 };
486 // Debug
487 (($args:expr):?) => {
488 $crate::__private_api::capture_debug(&&$args)
489 };
490 (($args:expr):debug) => {
491 $crate::__private_api::capture_debug(&&$args)
492 };
493 // Display
494 (($args:expr):%) => {
495 $crate::__private_api::capture_display(&&$args)
496 };
497 (($args:expr):display) => {
498 $crate::__private_api::capture_display(&&$args)
499 };
500 //Error
501 (($args:expr):err) => {
502 $crate::__log_value_error!($args)
503 };
504 // sval::Value
505 (($args:expr):sval) => {
506 $crate::__log_value_sval!($args)
507 };
508 // serde::Serialize
509 (($args:expr):serde) => {
510 $crate::__log_value_serde!($args)
511 };
512}
513
514#[doc(hidden)]
515#[macro_export]
516#[cfg(not(feature = "kv"))]
517macro_rules! __log_value {
518 ($($args:tt)*) => {
519 compile_error!("key value support requires the `kv` feature of `log`")
520 };
521}
522
523#[doc(hidden)]
524#[macro_export]
525#[cfg(feature = "kv_sval")]
526macro_rules! __log_value_sval {
527 ($args:expr) => {
528 $crate::__private_api::capture_sval(&&$args)
529 };
530}
531
532#[doc(hidden)]
533#[macro_export]
534#[cfg(not(feature = "kv_sval"))]
535macro_rules! __log_value_sval {
536 ($args:expr) => {
537 compile_error!("capturing values as `sval::Value` requites the `kv_sval` feature of `log`")
538 };
539}
540
541#[doc(hidden)]
542#[macro_export]
543#[cfg(feature = "kv_serde")]
544macro_rules! __log_value_serde {
545 ($args:expr) => {
546 $crate::__private_api::capture_serde(&&$args)
547 };
548}
549
550#[doc(hidden)]
551#[macro_export]
552#[cfg(not(feature = "kv_serde"))]
553macro_rules! __log_value_serde {
554 ($args:expr) => {
555 compile_error!(
556 "capturing values as `serde::Serialize` requites the `kv_serde` feature of `log`"
557 )
558 };
559}
560
561#[doc(hidden)]
562#[macro_export]
563#[cfg(feature = "kv_std")]
564macro_rules! __log_value_error {
565 ($args:expr) => {
566 $crate::__private_api::capture_error(&$args)
567 };
568}
569
570#[doc(hidden)]
571#[macro_export]
572#[cfg(not(feature = "kv_std"))]
573macro_rules! __log_value_error {
574 ($args:expr) => {
575 compile_error!(
576 "capturing values as `std::error::Error` requites the `kv_std` feature of `log`"
577 )
578 };
579}
580