跳转到内容
标准库Zig 0.17.0官方原文
源码std/log.zig

第 1 行

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

常量

第 28 行

std.log.debug

常量

第 201 行

使用默认作用域记录调试消息。此日志级别用于 仅对调试有帮助的消息。

std.log.default

类型

第 183 行

默认的带作用域日志命名空间。

std.log.default_level

常量

第 54 行

默认日志级别基于构建模式。

Level

std.log.default_log_scope

常量

第 180 行

std.log.defaultLog

函数

第 96 行

日志函数的默认实现。自定义日志函数可将日志消息 转发给此函数。

使用 64 字节缓冲区进行格式化打印, 并在函数返回之前刷新缓冲区。

pub fn defaultLog( comptime level: Level, comptime scope: @EnumLiteral(), comptime format: []const u8, args: anytype, ) void

参数

level: Level
scope: @EnumLiteral()
format: []const u8

std.log.defaultLogFileTerminal

函数

第 111 行

pub fn defaultLogFileTerminal( comptime level: Level, comptime scope: @EnumLiteral(), comptime format: []const u8, args: anytype, t: std.Io.Terminal, ) std.Io.Writer.Error!void

参数

level: Level
scope: @EnumLiteral()
format: []const u8
t: std.Io.Terminal

错误

WriteFailed

详细诊断信息见 Writer 实现。

std.log.defaultTerminalMode

函数

第 85 行

pub fn defaultTerminalMode() std.Io.Terminal.Mode

std.log.err

常量

第 188 行

使用默认作用域记录错误消息。此日志级别用于 某些情况已经出错时。该错误可能可恢复,也可能 随后导致程序退出。

std.log.info

常量

第 197 行

使用默认作用域记录信息消息。此日志级别用于关于程序状态的一般消息。

std.log.Level

容器

第 30 行

字段

err

错误:发生了问题。 可能可以恢复,也可能随后导致程序退出。

warn

警告:尚不确定是否发生了问题,但 当前情况值得调查。

info

信息:关于程序状态的一般消息。

debug

调试:仅对调试有用的消息。

std.log.Level.asText

函数

第 43 行

以完整文本形式返回给定级别的字符串字面量。

pub fn asText(comptime self: Level) []const u8

参数

self: Level

std.log.log

函数

第 64 行

fn log( comptime level: Level, comptime scope: @EnumLiteral(), comptime format: []const u8, args: anytype, ) void

参数

level: Level
scope: @EnumLiteral()
format: []const u8

std.log.logEnabled

函数

第 76 行

确定是否启用指定日志消息级别与作用域组合的日志记录。

pub fn logEnabled(comptime level: Level, comptime scope: @EnumLiteral()) bool

参数

level: Level
scope: @EnumLiteral()

std.log.scoped

类型函数

第 137 行

返回限定作用域的日志命名空间, 所有消息均使用此处提供的作用域记录。

pub fn scoped(comptime scope: @EnumLiteral()) type

参数

scope: @EnumLiteral()

std.log.scoped.debug

函数

第 171 行

记录调试消息。此日志级别用于 仅对调试有帮助的消息。

pub fn debug( comptime format: []const u8, args: anytype, ) void

参数

format: []const u8

std.log.scoped.err

函数

第 142 行

记录错误消息。此日志级别用于 某些情况已经出错时。该错误可能可恢复, 也可能随后导致程序退出。

pub fn err( comptime format: []const u8, args: anytype, ) void

参数

format: []const u8

std.log.scoped.info

函数

第 162 行

记录信息级别消息。此日志级别用于记录 关于程序状态的一般消息。

pub fn info( comptime format: []const u8, args: anytype, ) void

参数

format: []const u8

std.log.scoped.warn

函数

第 153 行

记录警告消息。此日志级别用于 尚不确定是否发生错误, 但情况值得调查的场景。

pub fn warn( comptime format: []const u8, args: anytype, ) void

参数

format: []const u8

std.log.ScopeLevel

容器

第 59 行

字段

scope: @EnumLiteral()
level: Level

std.log.std

别名

第 27 行

别名目标 std

std.log.terminalMode

别名

第 83 行

别名目标 std.Options.logTerminalMode

std.log.warn

常量

第 193 行

使用默认作用域记录警告消息。此日志级别用于 尚不确定是否发生问题,但相关情况 值得调查的场景。

源码

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;