文件系统与 I/O

const std = @import("std");

pub fn main() !void {
    // 初始化通用分配器用于动态内存分配
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();
    const allocator = gpa.allocator();

    // 创建用于流复制演示的工作目录
    const dir_name = "fs_stream_copy";
    try std.fs.cwd().makePath(dir_name);
    // 退出时清理目录，如果不存在则忽略错误
    defer std.fs.cwd().deleteTree(dir_name) catch {};

    // 为源文件构造平台无关的路径
    const source_path = try std.fs.path.join(allocator, &.{ dir_name, "source.txt" });
    defer allocator.free(source_path);

    // 创建具有截断和读取权限的源文件
    // 截断确保我们从空文件开始
    var source_file = try std.fs.cwd().createFile(source_path, .{ .truncate = true, .read = true });
    defer source_file.close();

    // 为源文件设置缓冲写入器
    // 缓冲区通过批量写入减少系统调用开销
    var source_writer_buffer: [128]u8 = undefined;
    var source_writer_state = source_file.writer(&source_writer_buffer);
    const source_writer = &source_writer_state.interface;

    // 向源文件写入示例数据
    try source_writer.print("alpha\n", .{});
    try source_writer.print("beta\n", .{});
    try source_writer.print("gamma\n", .{});
    // 刷新确保所有缓冲数据写入磁盘
    try source_writer.flush();

    // 将源文件光标倒回到开头以进行读取
    try source_file.seekTo(0);

    // 为目标文件构造平台无关的路径
    const dest_path = try std.fs.path.join(allocator, &.{ dir_name, "copy.txt" });
    defer allocator.free(dest_path);

    // 创建具有截断和读取权限的目标文件
    var dest_file = try std.fs.cwd().createFile(dest_path, .{ .truncate = true, .read = true });
    defer dest_file.close();

    // 为目标文件设置缓冲写入器
    var dest_writer_buffer: [64]u8 = undefined;
    var dest_writer_state = dest_file.writer(&dest_writer_buffer);
    const dest_writer = &dest_writer_state.interface;

    // 分配块缓冲区用于流复制操作
    var chunk: [128]u8 = undefined;
    var total_bytes: usize = 0;

    // 以块为单位从源流式传输数据到目标
    // 此方法对大文件内存高效
    while (true) {
        const read_len = try source_file.read(&chunk);
        // 读取长度为0表示EOF
        if (read_len == 0) break;
        // 将读取的确切字节数写入目标
        try dest_writer.writeAll(chunk[0..read_len]);
        total_bytes += read_len;
    }

    // 刷新目标写入器以确保所有数据持久化
    try dest_writer.flush();

    // 检索文件元数据以验证复制操作
    const info = try dest_file.stat();

    // 设置缓冲标准输出写入器用于显示结果
    var stdout_buffer: [256]u8 = undefined;
    var stdout_state = std.fs.File.stdout().writer(&stdout_buffer);
    const out = &stdout_state.interface;

    // 显示复制操作统计信息
    try out.print("copied {d} bytes\n", .{total_bytes});
    try out.print("destination size: {d}\n", .{info.size});

    // 将目标文件倒回以读取复制的内容
    try dest_file.seekTo(0);
    const copied = try dest_file.readToEndAlloc(allocator, 16 * 1024);
    defer allocator.free(copied);

    // 显示复制的文件内容以进行验证
    try out.print("--- copy.txt ---\n{s}", .{copied});
    // 刷新标准输出以确保所有输出显示
    try out.flush();
}

const std = @import("std");

// / Helper function to create a directory path from multiple path components
// / 从多个路径组件创建目录路径的辅助函数
// / Joins path segments using platform-appropriate separators and creates the full path
// / 使用平台适当的分隔符连接路径段并创建完整路径
fn ensurePath(allocator: std.mem.Allocator, parts: []const []const u8) !void {
    // Join path components into a single platform-neutral path string
    // 将路径组件连接成单个平台无关的路径字符串
    const joined = try std.fs.path.join(allocator, parts);
    defer allocator.free(joined);
    // Create the directory path, including any missing parent directories
    // 创建目录路径，包括任何缺失的父目录
    try std.fs.cwd().makePath(joined);
}

// / Helper function to create a file and write contents to it
// / 创建文件并写入内容的辅助函数
// / Constructs the file path from components, creates the file, and writes data using buffered I/O
// / 从组件构造文件路径，创建文件，并使用缓冲 I/O 写入数据
fn writeFile(allocator: std.mem.Allocator, parts: []const []const u8, contents: []const u8) !void {
    // Join path components into a single platform-neutral path string
    // 将路径组件连接成单个平台无关的路径字符串
    const joined = try std.fs.path.join(allocator, parts);
    defer allocator.free(joined);
    // Create a new file with truncate option to start with an empty file
    // 使用截断选项创建新文件，从空文件开始
    var file = try std.fs.cwd().createFile(joined, .{ .truncate = true });
    defer file.close();
    // Set up a buffered writer to reduce syscall overhead
    // 设置缓冲写入器以减少系统调用开销
    var buffer: [128]u8 = undefined;
    var state = file.writer(&buffer);
    const writer = &state.interface;
    // Write the contents to the file and ensure all data is persisted
    try writer.writeAll(contents);
    try writer.flush();
}

pub fn main() !void {
    // Initialize a general-purpose allocator for dynamic memory allocation
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();
    const allocator = gpa.allocator();

    // Create a temporary directory structure for the directory walk demonstration
    const root = "fs_walk_listing";
    try std.fs.cwd().makePath(root);
    // Clean up the directory tree on exit, ignoring errors if it doesn't exist
    defer std.fs.cwd().deleteTree(root) catch {};

    // Create a multi-level directory structure with nested subdirectories
    try ensurePath(allocator, &.{ root, "logs", "app" });
    try ensurePath(allocator, &.{ root, "logs", "jobs" });
    try ensurePath(allocator, &.{ root, "notes" });

    // Populate the directory structure with sample files
    try writeFile(allocator, &.{ root, "logs", "app", "today.log" }, "ok 200\n");
    try writeFile(allocator, &.{ root, "logs", "app", "errors.log" }, "warn 429\n");
    try writeFile(allocator, &.{ root, "logs", "jobs", "batch.log" }, "started\n");
    try writeFile(allocator, &.{ root, "notes", "todo.txt" }, "rotate logs\n");

    // Open the root directory with iteration capabilities for traversal
    var root_dir = try std.fs.cwd().openDir(root, .{ .iterate = true });
    defer root_dir.close();

    // Create a directory walker to recursively traverse the directory tree
    var walker = try root_dir.walk(allocator);
    defer walker.deinit();

    // Set up a buffered stdout writer for efficient console output
    var stdout_buffer: [512]u8 = undefined;
    var stdout_state = std.fs.File.stdout().writer(&stdout_buffer);
    const out = &stdout_state.interface;

    // Initialize counters to track directory contents
    var total_dirs: usize = 0;
    var total_files: usize = 0;
    var log_files: usize = 0;

    // Walk the directory tree recursively, processing each entry
    while (try walker.next()) |entry| {
        // Extract the null-terminated path from the entry
        const path = std.mem.sliceTo(entry.path, 0);
        // Process entry based on its type (directory, file, etc.)
        switch (entry.kind) {
            .directory => {
                total_dirs += 1;
                try out.print("DIR  {s}\n", .{path});
            },
            .file => {
                total_files += 1;
                // Retrieve file metadata to display size information
                const info = try entry.dir.statFile(entry.basename);
                // Check if the file has a .log extension
                const is_log = std.mem.endsWith(u8, path, ".log");
                if (is_log) log_files += 1;
                // Display file path, size, and mark log files with a tag
                try out.print("FILE {s} ({d} bytes){s}\n", .{
                    path,
                    info.size,
                    if (is_log) " [log]" else "",
                });
            },
            // Ignore other entry types (symlinks, etc.)
            else => {},
        }
    }

    // Display summary statistics of the directory walk
    try out.print("--- summary ---\n", .{});
    try out.print("directories: {d}\n", .{total_dirs});
    try out.print("files: {d}\n", .{total_files});
    try out.print("log files: {d}\n", .{log_files});
    // Flush stdout to ensure all output is displayed
    try out.flush();
}