项目

textkit/
├── build.zig              # 构建图定义
├── build.zig.zon          # 包元数据
├── sample.txt             # 演示输入文件
└── src/
    ├── textkit.zig        # 库根文件（公共API）
    ├── string_utils.zig   # 字符串操作工具
    ├── text_stats.zig     # 文本分析函数
    └── main.zig           # CLI可执行文件入口点

// Import the standard library for testing utilities
const std = @import("std");

// / String utilities for text processing
pub const StringUtils = struct {
    // / Count occurrences of a character in a string
    // / Returns the total number of times the specified character appears
    pub fn countChar(text: []const u8, char: u8) usize {
        var count: usize = 0;
        // Iterate through each character in the text
        for (text) |c| {
            // Increment counter when matching character is found
            if (c == char) count += 1;
        }
        return count;
    }

    // / Check if string contains only ASCII characters
    // / ASCII characters have values from 0-127
    pub fn isAscii(text: []const u8) bool {
        for (text) |c| {
            // Any character with value > 127 is non-ASCII
            if (c > 127) return false;
        }
        return true;
    }

    // / Reverse a string in place
    // / Modifies the input buffer directly using two-pointer technique
    pub fn reverse(text: []u8) void {
        // Early return for empty strings
        if (text.len == 0) return;

        var left: usize = 0;
        var right: usize = text.len - 1;

        // Swap characters from both ends moving towards the center
        while (left < right) {
            const temp = text[left];
            text[left] = text[right];
            text[right] = temp;
            left += 1;
            right -= 1;
        }
    }
};

// Test suite verifying countChar functionality with various inputs
test "countChar counts occurrences" {
    const text = "hello world";
    // Verify counting of 'l' character (appears 3 times)
    try std.testing.expectEqual(@as(usize, 3), StringUtils.countChar(text, 'l'));
    // Verify counting of 'o' character (appears 2 times)
    try std.testing.expectEqual(@as(usize, 2), StringUtils.countChar(text, 'o'));
    // Verify counting returns 0 for non-existent character
    try std.testing.expectEqual(@as(usize, 0), StringUtils.countChar(text, 'x'));
}

// Test suite verifying ASCII detection for different character sets
test "isAscii detects ASCII strings" {
    // Standard ASCII letters should return true
    try std.testing.expect(StringUtils.isAscii("hello"));
    // ASCII digits should return true
    try std.testing.expect(StringUtils.isAscii("123"));
    // String with non-ASCII character (é = 233) should return false
    try std.testing.expect(!StringUtils.isAscii("héllo"));
}

// Test suite verifying in-place string reversal
test "reverse reverses string" {
    // Create a mutable buffer to test in-place reversal
    var buffer = [_]u8{ 'h', 'e', 'l', 'l', 'o' };
    StringUtils.reverse(&buffer);
    // Verify the buffer contents are reversed
    try std.testing.expectEqualSlices(u8, "olleh", &buffer);
}

const std = @import("std");

//  Text statistics and analysis structure
//  Provides functionality to analyze text content and compute various metrics
//  such as word count, line count, and character count.
pub const TextStats = struct {
    //  Total number of words found in the analyzed text
    word_count: usize,
    //  Total number of lines in the analyzed text
    line_count: usize,
    //  Total number of characters in the analyzed text
    char_count: usize,

    //  Analyze text and compute statistics
    //  Iterates through the input text to count words, lines, and characters.
    //  Words are defined as sequences of non-whitespace characters separated by whitespace.
    //  Lines are counted based on newline characters, with special handling for text
    //  that doesn't end with a newline.
    pub fn analyze(text: []const u8) TextStats {
        var stats = TextStats{
            .word_count = 0,
            .line_count = 0,
            .char_count = text.len,
        };

        // Track whether we're currently inside a word to avoid counting multiple
        // consecutive whitespace characters as separate word boundaries
        var in_word = false;
        for (text) |c| {
            if (c == '\n') {
                stats.line_count += 1;
                in_word = false;
            } else if (std.ascii.isWhitespace(c)) {
                // Whitespace marks the end of a word
                in_word = false;
            } else if (!in_word) {
                // Transition from whitespace to non-whitespace marks a new word
                stats.word_count += 1;
                in_word = true;
            }
        }

        // Count last line if text doesn't end with newline
        if (text.len > 0 and text[text.len - 1] != '\n') {
            stats.line_count += 1;
        }

        return stats;
    }

    // Format and write statistics to the provided writer
    // Outputs the statistics in a human-readable format: "Lines: X, Words: Y, Chars: Z"
    pub fn format(self: TextStats, writer: *std.Io.Writer) std.Io.Writer.Error!void {
        try writer.print("Lines: {d}, Words: {d}, Chars: {d}", .{
            self.line_count,
            self.word_count,
            self.char_count,
        });
    }
};

// Verify that TextStats correctly analyzes multi-line text with multiple words
test "TextStats analyzes simple text" {
    const text = "hello world\nfoo bar";
    const stats = TextStats.analyze(text);
    try std.testing.expectEqual(@as(usize, 2), stats.line_count);
    try std.testing.expectEqual(@as(usize, 4), stats.word_count);
    try std.testing.expectEqual(@as(usize, 19), stats.char_count);
}

// Verify that TextStats correctly handles edge case of empty input
test "TextStats handles empty text" {
    const text = "";
    const stats = TextStats.analyze(text);
    try std.testing.expectEqual(@as(usize, 0), stats.line_count);
    try std.testing.expectEqual(@as(usize, 0), stats.word_count);
    try std.testing.expectEqual(@as(usize, 0), stats.char_count);
}

// ! TextKit - A text processing library
//!
// ! This library provides utilities for text manipulation and analysis,
// ! including string utilities and text statistics.

pub const StringUtils = @import("string_utils.zig").StringUtils;
pub const TextStats = @import("text_stats.zig").TextStats;

const std = @import("std");

//  Library version information
pub const version = std.SemanticVersion{
    .major = 1,
    .minor = 0,
    .patch = 0,
};

test {
    // Ensure all module tests are run
    std.testing.refAllDecls(@This());
}

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

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

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

    // 确保至少提供一个命令参数（args[0]是程序名）
    if (args.len < 2) {
        try printUsage();
        return;
    }

    // 从第一个参数中提取命令动词
    const command = args[1];

    // 根据命令分派到适当的处理程序
    if (std.mem.eql(u8, command, "analyze")) {
        // 'analyze'需要一个文件名参数
        if (args.len < 3) {
            std.debug.print("Error: analyze requires a filename\n", .{});
            return;
        }
        try analyzeFile(allocator, args[2]);
    } else if (std.mem.eql(u8, command, "reverse")) {
        // 'reverse'需要反转的文本
        if (args.len < 3) {
            std.debug.print("Error: reverse requires text\n", .{});
            return;
        }
        try reverseText(args[2]);
    } else if (std.mem.eql(u8, command, "count")) {
        // 'count'需要文本和要计数的单个字符
        if (args.len < 4) {
            std.debug.print("Error: count requires text and character\n", .{});
            return;
        }
        // 验证字符参数恰好是一个字节
        if (args[3].len != 1) {
            std.debug.print("Error: character must be single byte\n", .{});
            return;
        }
        try countCharacter(args[2], args[3][0]);
    } else {
        // 处理无法识别的命令
        std.debug.print("Unknown command: {s}\n", .{command});
        try printUsage();
    }
}

/// 打印使用说明以指导用户了解可用命令
fn printUsage() !void {
    const usage =
        \\TextKit CLI - Text processing utility
        \\
        \\Usage:
        \\  textkit-cli analyze <file>      Analyze text file statistics
        \\  textkit-cli reverse <text>      Reverse the given text
        \\  textkit-cli count <text> <char> Count character occurrences
        \\
    ;
    std.debug.print("{s}", .{usage});
}

/// 读取文件并显示其文本内容的统计分析
fn analyzeFile(allocator: std.mem.Allocator, filename: []const u8) !void {
    // 从当前工作目录以只读模式打开文件
    const file = try std.fs.cwd().openFile(filename, .{});
    defer file.close();

    // 将整个文件内容读取到内存（限制为1MB）
    const content = try file.readToEndAlloc(allocator, 1024 * 1024);
    defer allocator.free(content);

    // 使用textkit库计算文本统计信息
    const stats = textkit.TextStats.analyze(content);

    // 向用户显示计算出的统计信息
    std.debug.print("File: {s}\n", .{filename});
    std.debug.print("  Lines: {d}\n", .{stats.line_count});
    std.debug.print("  Words: {d}\n", .{stats.word_count});
    std.debug.print("  Characters: {d}\n", .{stats.char_count});
    std.debug.print("  ASCII only: {}\n", .{textkit.StringUtils.isAscii(content)});
}

/// 反转提供的文本并显示原始和反转版本
fn reverseText(text: []const u8) !void {
    // 为就地反转分配栈缓冲区
    var buffer: [1024]u8 = undefined;

    // 确保输入文本适合缓冲区
    if (text.len > buffer.len) {
        std.debug.print("Error: text too long (max {d} chars)\n", .{buffer.len});
        return;
    }

    // 将输入文本复制到可变缓冲区中进行反转
    @memcpy(buffer[0..text.len], text);

    // 使用textkit实用工具执行就地反转
    textkit.StringUtils.reverse(buffer[0..text.len]);

    // 显示原始和反转文本
    std.debug.print("Original: {s}\n", .{text});
    std.debug.print("Reversed: {s}\n", .{buffer[0..text.len]});
}

/// 计算提供文本中特定字符的出现次数
fn countCharacter(text: []const u8, char: u8) !void {
    // 使用textkit计算字符出现次数
    const count = textkit.StringUtils.countChar(text, char);

    // 显示计数结果
    std.debug.print("Character '{c}' appears {d} time(s) in: {s}\n", .{
        char,
        count,
        text,
    });
}

// 测试此模块中的所有声明是否可访问并正确编译
test "main program compiles" {
    std.testing.refAllDecls(@This());
}

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

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

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

    // 确保至少提供一个命令参数（args[0]是程序名）
    if (args.len < 2) {
        try printUsage();
        return;
    }

    // 从第一个参数中提取命令动词
    const command = args[1];

    // 根据命令分派到适当的处理程序
    if (std.mem.eql(u8, command, "analyze")) {
        // 'analyze'需要一个文件名参数
        if (args.len < 3) {
            std.debug.print("Error: analyze requires a filename\n", .{});
            return;
        }
        try analyzeFile(allocator, args[2]);
    } else if (std.mem.eql(u8, command, "reverse")) {
        // 'reverse'需要反转的文本
        if (args.len < 3) {
            std.debug.print("Error: reverse requires text\n", .{});
            return;
        }
        try reverseText(args[2]);
    } else if (std.mem.eql(u8, command, "count")) {
        // 'count'需要文本和要计数的单个字符
        if (args.len < 4) {
            std.debug.print("Error: count requires text and character\n", .{});
            return;
        }
        // 验证字符参数恰好是一个字节
        if (args[3].len != 1) {
            std.debug.print("Error: character must be single byte\n", .{});
            return;
        }
        try countCharacter(args[2], args[3][0]);
    } else {
        // 处理无法识别的命令
        std.debug.print("Unknown command: {s}\n", .{command});
        try printUsage();
    }
}

/// 打印使用说明以指导用户了解可用命令
fn printUsage() !void {
    const usage =
        \\TextKit CLI - Text processing utility
        \\
        \\Usage:
        \\  textkit-cli analyze <file>      Analyze text file statistics
        \\  textkit-cli reverse <text>      Reverse the given text
        \\  textkit-cli count <text> <char> Count character occurrences
        \\
    ;
    std.debug.print("{s}", .{usage});
}

/// 读取文件并显示其文本内容的统计分析
fn analyzeFile(allocator: std.mem.Allocator, filename: []const u8) !void {
    // 从当前工作目录以只读模式打开文件
    const file = try std.fs.cwd().openFile(filename, .{});
    defer file.close();

    // 将整个文件内容读取到内存（限制为1MB）
    const content = try file.readToEndAlloc(allocator, 1024 * 1024);
    defer allocator.free(content);

    // 使用textkit库计算文本统计信息
    const stats = textkit.TextStats.analyze(content);

    // 向用户显示计算出的统计信息
    std.debug.print("File: {s}\n", .{filename});
    std.debug.print("  Lines: {d}\n", .{stats.line_count});
    std.debug.print("  Words: {d}\n", .{stats.word_count});
    std.debug.print("  Characters: {d}\n", .{stats.char_count});
    std.debug.print("  ASCII only: {}\n", .{textkit.StringUtils.isAscii(content)});
}

/// 反转提供的文本并显示原始和反转版本
fn reverseText(text: []const u8) !void {
    // 为就地反转分配栈缓冲区
    var buffer: [1024]u8 = undefined;

    // 确保输入文本适合缓冲区
    if (text.len > buffer.len) {
        std.debug.print("Error: text too long (max {d} chars)\n", .{buffer.len});
        return;
    }

    // 将输入文本复制到可变缓冲区中进行反转
    @memcpy(buffer[0..text.len], text);

    // 使用textkit实用工具执行就地反转
    textkit.StringUtils.reverse(buffer[0..text.len]);

    // 显示原始和反转文本
    std.debug.print("Original: {s}\n", .{text});
    std.debug.print("Reversed: {s}\n", .{buffer[0..text.len]});
}

/// 计算提供文本中特定字符的出现次数
fn countCharacter(text: []const u8, char: u8) !void {
    // 使用textkit计算字符出现次数
    const count = textkit.StringUtils.countChar(text, char);

    // 显示计数结果
    std.debug.print("Character '{c}' appears {d} time(s) in: {s}\n", .{
        char,
        count,
        text,
    });
}

// 测试此模块中的所有声明是否可访问并正确编译
test "main program compiles" {
    std.testing.refAllDecls(@This());
}

const std = @import("std");

pub fn build(b: *std.Build) void {
    // 标准目标和优化选项
    const target = b.standardTargetOptions(.{});
    const optimize = b.standardOptimizeOption(.{});
    
    // ===== 库 =====
    // 创建 TextKit 库模块
    const textkit_mod = b.addModule("textkit", .{
        .root_source_file = b.path("src/textkit.zig"),
        .target = target,
    });
    
    // 构建静态库产物
    const lib = b.addLibrary(.{
        .name = "textkit",
        .root_module = b.createModule(.{
            .root_source_file = b.path("src/textkit.zig"),
            .target = target,
            .optimize = optimize,
        }),
        .version = .{ .major = 1, .minor = 0, .patch = 0 },
        .linkage = .static,
    });
    
    // 安装库 (到 zig-out/lib/)
    b.installArtifact(lib);
    
    // ===== 可执行文件 =====
    // 创建使用库的可执行文件
    const exe = b.addExecutable(.{
        .name = "textkit-cli",
        .root_module = b.createModule(.{
            .root_source_file = b.path("src/main.zig"),
            .target = target,
            .optimize = optimize,
            .imports = &.{
                .{ .name = "textkit", .module = textkit_mod },
            },
        }),
    });
    
    // 安装可执行文件 (到 zig-out/bin/)
    b.installArtifact(exe);
    
    // ===== 运行步骤 =====
    // 创建可执行文件的运行步骤
    const run_cmd = b.addRunArtifact(exe);
    run_cmd.step.dependOn(b.getInstallStep());
    
    // 转发命令行参数到应用程序
    if (b.args) |args| {
        run_cmd.addArgs(args);
    }
    
    const run_step = b.step("run", "Run the TextKit CLI");
    run_step.dependOn(&run_cmd.step);
    
    // ===== 测试 =====
    // 库测试
    const lib_tests = b.addTest(.{
        .root_module = textkit_mod,
    });
    
    const run_lib_tests = b.addRunArtifact(lib_tests);
    
    // 可执行文件测试 (main.zig 的最小测试)
    const exe_tests = b.addTest(.{
        .root_module = exe.root_module,
    });
    
    const run_exe_tests = b.addRunArtifact(exe_tests);
    
    // 运行所有测试的测试步骤
    const test_step = b.step("test", "Run all tests");
    test_step.dependOn(&run_lib_tests.step);
    test_step.dependOn(&run_exe_tests.step);
    
    // ===== 自定义步骤 =====
    // 展示用法的演示步骤
    const demo_step = b.step("demo", "Run demo commands");
    
    const demo_reverse = b.addRunArtifact(exe);
    demo_reverse.addArgs(&.{ "reverse", "Hello Zig!" });
    demo_step.dependOn(&demo_reverse.step);
    
    const demo_count = b.addRunArtifact(exe);
    demo_count.addArgs(&.{ "count", "mississippi", "s" });
    demo_step.dependOn(&demo_count.step);
}

$ zig build

$ zig build test

$ zig build demo

$ zig build-exe src/main.zig --name textkit-cli --pkg-begin textkit src/textkit.zig --pkg-end

$ zig build