Zig CLI 深入解析

const std = @import("std");
const builtin = @import("builtin");

pub fn main() !void {
    // 设置一个通用分配器用于动态内存分配
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();

    const allocator = gpa.allocator();

    // 检索传递给程序的所有命令行参数
    const argv = try std.process.argsAlloc(allocator);
    defer std.process.argsFree(allocator, argv);

    // 显示编译期间使用的优化模式（Debug, ReleaseSafe, ReleaseFast, ReleaseSmall）
    std.debug.print("optimize-mode: {s}\n", .{@tagName(builtin.mode)});

    // 显示目标平台三元组（架构-操作系统-ABI）
    std.debug.print(
        "target-triple: {s}-{s}-{s}\n",
        .{
            @tagName(builtin.target.cpu.arch),
            @tagName(builtin.target.os.tag),
            @tagName(builtin.target.abi),
        },
    );

    // 显示程序是否以单线程模式编译
    std.debug.print("single-threaded: {}\n", .{builtin.single_threaded});

    // 检查是否提供了任何用户参数（argv[0] 是程序名本身）
    if (argv.len <= 1) {
        std.debug.print("user-args: <none>\n", .{});
        return;
    }

    // 打印所有用户提供的参数（跳过 argv[0] 处的程序名）
    std.debug.print("user-args:\n", .{});
    for (argv[1..], 0..) |arg, idx| {
        std.debug.print("  arg[{d}] = {s}\n", .{ idx, arg });
    }
}

const std = @import("std");

// / Calculates the sum of all integers in the provided slice.
// / 计算提供切片中所有整数的和。
// / Returns 0 for an empty slice.
// / 对空切片返回 0。
fn sum(values: []const i32) i32 {
    var total: i32 = 0;
    // Accumulate all values in the slice
    // 累加切片中的所有值
    for (values) |value| total += value;
    return total;
}

// / Calculates the product of all integers in the provided slice.
// / 计算提供切片中所有整数的乘积。
// / Returns 1 for an empty slice (multiplicative identity).
// / 对空切片返回 1（乘法单位元）。
fn product(values: []const i32) i32 {
    var total: i32 = 1;
    // Multiply each value with the running total
    // 将每个值与运行总数相乘
    for (values) |value|
        total *= value;
    return total;
}

// Verifies that sum correctly adds positive integers
// 验证sum函数正确计算正整数的和
test "sum-of-three" {
    try std.testing.expectEqual(@as(i32, 42), sum(&.{ 20, 10, 12 }));
}

// Verifies that sum handles mixed positive and negative integers correctly
// 验证sum函数正确处理正负整数混合
test "sum-mixed-signs" {
    try std.testing.expectEqual(@as(i32, -1), sum(&.{ 4, -3, -2 }));
}

// Verifies that product correctly multiplies positive integers
// 验证product函数正确计算正整数的乘积
test "product-positive" {
    try std.testing.expectEqual(@as(i32, 120), product(&.{ 2, 3, 4, 5 }));
}

// Verifies that product correctly handles negative integers,
// 验证product函数正确处理负整数，
// resulting in a negative product when an odd number of negatives are present
// 当存在奇数个负数时结果为负乘积
test "product-negative" {
    try std.testing.expectEqual(@as(i32, -18), product(&.{ 3, -3, 2 }));
}

// ! 用于 CLI 环境配置和跨平台默认设置的实用函数。
// ! 该模块提供用于确定缓存目录、颜色支持、
// ! 以及基于目标操作系统的默认工具配置的帮助程序。
const std = @import("std");
const builtin = @import("builtin");

// / 返回缓存目录的适当环境变量键
// / 基于目标操作系统。
///
// / - Windows 使用 LOCALAPPDATA 作为应用程序缓存
// / - macOS 和 iOS 使用 HOME（缓存通常位于 ~/Library/Caches 中）
// / - 类 Unix 系统倾向于使用 XDG_CACHE_HOME 来符合 XDG 基本目录规范
// / - 其他系统回退到 HOME 目录
pub fn defaultCacheEnvKey() []const u8 {
    return switch (builtin.os.tag) {
        .windows => "LOCALAPPDATA",
        .macos => "HOME",
        .ios => "HOME",
        .linux, .freebsd, .netbsd, .openbsd, .dragonfly, .haiku => "XDG_CACHE_HOME",
        else => "HOME",
    };
}

// / 确定终端输出中是否应使用 ANSI 颜色代码
// / 基于标准环境变量。
///
// / 遵循非正式标准：
// / - NO_COLOR（任何值）禁用颜色
// / - CLICOLOR_FORCE（任何值）强制使用颜色，即使不是 TTY
// / - 默认行为是启用颜色
///
// / 如果应使用 ANSI 颜色则返回 true，否则返回 false。
pub fn preferAnsiColor(env: std.process.EnvMap) bool {
    // Check if colors are explicitly disabled
    if (env.get("NO_COLOR")) |_| return false;
    // Check if colors are explicitly forced
    if (env.get("CLICOLOR_FORCE")) |_| return true;
    // Default to enabling colors
    return true;
}

// / 返回用于调用 Zig 格式化程序的默认命令行参数
// / 在检查模式下（报告格式问题而不修改文件）。
pub fn defaultFormatterArgs() []const []const u8 {
    return &.{ "zig", "fmt", "--check" };
}