[][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.