[−][src]Crate tao_log
Extension macros for output to the rust log crate.
“Why write an RFC, when you can just write code?” — 老子 (“Old Master”), 557 BCE
This unenlightened wanderer (游侠) wrote a log crate PR and RFC 317, before published the work as this standalone crate.
Libraries and applications can use the tao-log macros for all log output
needs. This includes re-exported log crate formatted logging and
associated macros, and a set of new -v suffix macros (e.g. debugv!
)
that provide inline expression and value logging, as a superset of
std::dbg!
. Both sets of macros are given a new overview below, with
examples using arbitrary log levels.
If the new macros are eventually accepted to the log crate in compatible form, this crate will be re-released with those re-exports, and possibly deprecated after that.
Using the rust 2018 edition, all exported macros can be imported like a prelude:
use tao_log::*;
Or if desired, import the individual macros:
use tao_log::{debug, debugv, error, warn};
Formatted logging
The original macros for each supported level, from highest to lowest
priority (or lowest to highest verbosity) include: error!
, warn!
,
info!
, debug!
and trace!
. These are passed a literal format string,
supporting the same syntax as println!
, via std::fmt
:
use tao_log::*; info!("Landing gear retracted"); let altitude = 3000; let target = 10500; debug!("Altitude target: {}, current: {}", target, altitude);
If for example, the configured maximum logging level is Info
, then the
above debug!
statement does not log, and the cost of formatting the
message string is avoided.
To these formatted logging macros, tao-log adds a
fatal!
macro, which logs at the error level, and
then uses the same message to panic!
.
Testing for output
The log_enabled!
macro may be used to
explicitly test if logging is enabled, and may be useful to avoid
expensive computations used only for logging.
use tao_log::*; if log_enabled!(log::Level::Debug) { let e = analyze(asteroid); // expensive! debug!("Asteroid volume: {}, mass: {}", e.volume(), e.mass()); }
Inline expression and value logging
The -v macros support inline expression and value logging, as a superset
of the std::dbg!
macro, for use with the logging system. A single
expression argument is evaluated exactly once, regardless of if the
logging level is enabled, and its value is returned from the macro. Given
this code as a starting point:
use std::time::{Duration, Instant}; let remaining = deadline - Instant::now();
A -v macro may be inserted inline around any expression or sub-expression:
use std::time::{Duration, Instant}; use tao_log::*; let remaining = debugv!(deadline - Instant::now()); // ^-- debug log: deadline - Instant::now() → 950µs debugv!("time until deadline", remaining); // or ^-- debug log: time until deadline remaining → 950µs
Note that the value of the expression is moved and then returned. If the
type does not implement Copy
, ownership may be retained by borrowing by
reference, e.g. debugv!(&expr)
.
The default format string for the -v macros is "{} → {:?}"
, where
the stringify!
-ed expression and resulting value are passed, in that
order. If the log record is not filtered out, the Debug
implementation
for the type of the given expression value is used ("{:?}"
).
The log record can be customized via two optional parameters: a message prefix string, and a format specifier for the value. Note that the former is required, if passing the later:
use tao_log::*; let i = 32; infov!(i); infov!("", "{:?}", i); // equivalent to above // ^------------------------ info log: i → 32 infov!("index", i); // prefix for additional context infov!("index", "{}", i); // use `Display` format for value // ^------------------------ info log: index i → 32 infov!("index", "{:#x}", i); // hexadecimal format value // ^------------------------ info log: index i → 0x20 infov!("index", "{:#?}", i); // pretty multi-line format (for structs)
Specifying the logging target
For all logging macros, the target defaults to the module path of the
current location of use, but may be overridden with the target:
marker
and string literal as the first argument:
use tao_log::*; let i = 33; let j = debugv!(target: "maths", "halved", (i-1) / 2); if log_enabled!(target: "special", log::Level::Info) { info!(target: "special", "{}", stats()); }
Re-exports
pub use log; |
Macros
debug | Logs a message at the debug level. |
debugv | Log an expression at the debug level, returning its value. |
error | Logs a message at the error level. |
errorv | Log an expression at the error level, returning its value. |
fatal | Log a message at the error level, flush the logger, and then use the same message to panic. |
info | Logs a message at the info level. |
infov | Log an expression at the info level, returning its value. |
log | The standard logging macro. |
log_enabled | Determines if a message logged at the specified level in that module will be logged. |
logv | Log an expression and its value at any specified level. |
trace | Logs a message at the trace level. |
tracev | Log an expression at the trace level, returning its value. |
warn | Logs a message at the warn level. |
warnv | Log an expression at the warn level, returning its value. |