std.log 是标准化的日志接口,使 std.options.logFn 的实现者能够统一设置程序及库所产生的日志格式,并对其过滤。
每条日志消息都关联一个作用域枚举,可为日志提供上下文。std.log 中的日志函数隐式使用 .default 作用域。
可以调用 std.log.scoped 并传入作用域,创建使用自定义作用域的日志命名空间;返回结构体中的日志函数使用所提供的作用域参数。
例如,名为“libfoo”的库可以使用 const log = std.log.scoped(.libfoo);,使其日志消息采用 .libfoo 作用域。
logFn 的实现示例见默认实现 defaultLog。它输出到标准错误流,并在支持时使用颜色。输出形式如下:
error: this is an error
error(scope): this is an error with a non-default scope
warning: this is a warning
info: this is an informative message
debug: this is a debugging message
std.log.builtin
常量
std.log.debug
常量
使用默认作用域记录调试消息。此日志级别用于 仅对调试有帮助的消息。
std.log.default
类型
默认的带作用域日志命名空间。
std.log.default_level
常量
默认日志级别基于构建模式。
Level
std.log.default_log_scope
常量
std.log.defaultLog
函数
日志函数的默认实现。自定义日志函数可将日志消息 转发给此函数。
使用 64 字节缓冲区进行格式化打印, 并在函数返回之前刷新缓冲区。
pub fn defaultLog( comptime level: Level, comptime scope: @EnumLiteral(), comptime format: []const u8, args: anytype, ) void
参数
std.log.defaultLogFileTerminal
函数
pub fn defaultLogFileTerminal( comptime level: Level, comptime scope: @EnumLiteral(), comptime format: []const u8, args: anytype, t: std.Io.Terminal, ) std.Io.Writer.Error!void
参数
错误
- WriteFailed
详细诊断信息见
Writer实现。
std.log.defaultTerminalMode
函数
pub fn defaultTerminalMode() std.Io.Terminal.Mode
std.log.err
常量
使用默认作用域记录错误消息。此日志级别用于 某些情况已经出错时。该错误可能可恢复,也可能 随后导致程序退出。
std.log.info
常量
使用默认作用域记录信息消息。此日志级别用于关于程序状态的一般消息。
std.log.Level
容器
字段
std.log.Level.asText
函数
以完整文本形式返回给定级别的字符串字面量。
pub fn asText(comptime self: Level) []const u8
参数
self: Level
std.log.log
函数
fn log( comptime level: Level, comptime scope: @EnumLiteral(), comptime format: []const u8, args: anytype, ) void
参数
std.log.logEnabled
函数
确定是否启用指定日志消息级别与作用域组合的日志记录。
pub fn logEnabled(comptime level: Level, comptime scope: @EnumLiteral()) bool
参数
level: Level
scope: @EnumLiteral()
std.log.scoped
类型函数
返回限定作用域的日志命名空间, 所有消息均使用此处提供的作用域记录。
pub fn scoped(comptime scope: @EnumLiteral()) type
参数
scope: @EnumLiteral()
std.log.scoped.debug
函数
记录调试消息。此日志级别用于 仅对调试有帮助的消息。
pub fn debug( comptime format: []const u8, args: anytype, ) void
参数
format: []const u8
std.log.scoped.err
函数
记录错误消息。此日志级别用于 某些情况已经出错时。该错误可能可恢复, 也可能随后导致程序退出。
pub fn err( comptime format: []const u8, args: anytype, ) void
参数
format: []const u8
std.log.scoped.info
函数
记录信息级别消息。此日志级别用于记录 关于程序状态的一般消息。
pub fn info( comptime format: []const u8, args: anytype, ) void
参数
format: []const u8
std.log.scoped.warn
函数
记录警告消息。此日志级别用于 尚不确定是否发生错误, 但情况值得调查的场景。
pub fn warn( comptime format: []const u8, args: anytype, ) void
参数
format: []const u8
std.log.ScopeLevel
容器
字段
scope: @EnumLiteral()
level: Level
std.log.std
别名
别名目标 std
std.log.terminalMode
别名
std.log.warn
常量
使用默认作用域记录警告消息。此日志级别用于 尚不确定是否发生问题,但相关情况 值得调查的场景。
源码
std/log.zig
//! std.log 是标准化的日志接口,使 `std.options.logFn` 的实现者能够统一设置程序及库所产生的日志格式,并对其过滤。
//!
//! 每条日志消息都关联一个作用域枚举,可为日志提供上下文。std.log 中的日志函数隐式使用 .default 作用域。
//!
//! 可以调用 std.log.scoped 并传入作用域,创建使用自定义作用域的日志命名空间;返回结构体中的日志函数使用所提供的作用域参数。
//! 例如,名为“libfoo”的库可以使用 `const log = std.log.scoped(.libfoo);`,使其日志消息采用 .libfoo 作用域。
//!
//! `logFn` 的实现示例见默认实现 `defaultLog`。它输出到标准错误流,并在支持时使用颜色。输出形式如下:
//! ```
//! error: this is an error
//! error(scope): this is an error with a non-default scope
//! warning: this is a warning
//! info: this is an informative message
//! debug: this is a debugging message
//! ```
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
const std = @import("std.zig");
const builtin = @import("builtin");
pub const Level = enum {
/// 错误:发生了问题。
/// 可能可以恢复,也可能随后导致程序退出。
err,
/// 警告:尚不确定是否发生了问题,但
/// 当前情况值得调查。
warn,
/// 信息:关于程序状态的一般消息。
info,
/// 调试:仅对调试有用的消息。
debug,
/// 以完整文本形式返回给定级别的字符串字面量。
pub fn asText(comptime self: Level) []const u8 {
return switch (self) {
.err => "error",
.warn => "warning",
.info => "info",
.debug => "debug",
};
}
};
/// 默认日志级别基于构建模式。
pub const default_level: Level = switch (builtin.mode) {
.debug => .debug,
.safe, .fast, .small => .info,
};
pub const ScopeLevel = struct {
scope: @EnumLiteral(),
level: Level,
};
fn log(
comptime level: Level,
comptime scope: @EnumLiteral(),
comptime format: []const u8,
args: anytype,
) void {
if (comptime !logEnabled(level, scope)) return;
std.options.logFn(level, scope, format, args);
}
/// 确定是否启用指定日志消息级别与作用域组合的日志记录。
pub fn logEnabled(comptime level: Level, comptime scope: @EnumLiteral()) bool {
inline for (std.options.log_scope_levels) |scope_level| {
if (scope_level.scope == scope) return @backingInt(level) <= @backingInt(scope_level.level);
}
return @backingInt(level) <= @backingInt(std.options.log_level);
}
pub const terminalMode = std.Options.logTerminalMode;
pub fn defaultTerminalMode() std.Io.Terminal.Mode {
const stderr = std.debug.lockStderr(&.{}).terminal();
std.debug.unlockStderr();
return stderr.mode;
}
/// 日志函数的默认实现。自定义日志函数可将日志消息
/// 转发给此函数。
///
/// 使用 64 字节缓冲区进行格式化打印,
/// 并在函数返回之前刷新缓冲区。
pub fn defaultLog(
comptime level: Level,
comptime scope: @EnumLiteral(),
comptime format: []const u8,
args: anytype,
) void {
const io = std.Options.debug_io;
const prev = io.swapCancelProtection(.blocked);
defer _ = io.swapCancelProtection(prev);
var buffer: [64]u8 = undefined;
const stderr = std.debug.lockStderr(&buffer).terminal();
defer std.debug.unlockStderr();
return defaultLogFileTerminal(level, scope, format, args, stderr) catch {};
}
pub fn defaultLogFileTerminal(
comptime level: Level,
comptime scope: @EnumLiteral(),
comptime format: []const u8,
args: anytype,
t: std.Io.Terminal,
) std.Io.Writer.Error!void {
t.setColor(switch (level) {
.err => .red,
.warn => .yellow,
.info => .green,
.debug => .magenta,
}) catch {};
t.setColor(.bold) catch {};
try t.writer.writeAll(level.asText());
t.setColor(.reset) catch {};
t.setColor(.dim) catch {};
t.setColor(.bold) catch {};
if (scope != .default) try t.writer.print("({t})", .{scope});
try t.writer.writeAll(": ");
t.setColor(.reset) catch {};
try t.writer.print(format ++ "\n", args);
}
/// 返回限定作用域的日志命名空间,
/// 所有消息均使用此处提供的作用域记录。
pub fn scoped(comptime scope: @EnumLiteral()) type {
return struct {
/// 记录错误消息。此日志级别用于
/// 某些情况已经出错时。该错误可能可恢复,
/// 也可能随后导致程序退出。
pub fn err(
comptime format: []const u8,
args: anytype,
) void {
@branchHint(.cold);
log(.err, scope, format, args);
}
/// 记录警告消息。此日志级别用于
/// 尚不确定是否发生错误,
/// 但情况值得调查的场景。
pub fn warn(
comptime format: []const u8,
args: anytype,
) void {
log(.warn, scope, format, args);
}
/// 记录信息级别消息。此日志级别用于记录
/// 关于程序状态的一般消息。
pub fn info(
comptime format: []const u8,
args: anytype,
) void {
log(.info, scope, format, args);
}
/// 记录调试消息。此日志级别用于
/// 仅对调试有帮助的消息。
pub fn debug(
comptime format: []const u8,
args: anytype,
) void {
log(.debug, scope, format, args);
}
};
}
pub const default_log_scope = .default;
/// 默认的带作用域日志命名空间。
pub const default = scoped(default_log_scope);
/// 使用默认作用域记录错误消息。此日志级别用于
/// 某些情况已经出错时。该错误可能可恢复,也可能
/// 随后导致程序退出。
pub const err = default.err;
/// 使用默认作用域记录警告消息。此日志级别用于
/// 尚不确定是否发生问题,但相关情况
/// 值得调查的场景。
pub const warn = default.warn;
/// 使用默认作用域记录信息消息。此日志级别用于关于程序状态的一般消息。
///
pub const info = default.info;
/// 使用默认作用域记录调试消息。此日志级别用于
/// 仅对调试有帮助的消息。
pub const debug = default.debug;