项目

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 {
    // Set up a general-purpose allocator for dynamic memory allocation
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();
    const allocator = gpa.allocator();

    // Retrieve command line arguments passed to the program
    const args = try std.process.argsAlloc(allocator);
    defer std.process.argsFree(allocator, args);

    // Ensure at least one command argument is provided (args[0] is the program name)
    if (args.len < 2) {
        try printUsage();
        return;
    }

    // Extract the command verb from the first argument
    const command = args[1];

    // Dispatch to the appropriate handler based on the command
    if (std.mem.eql(u8, command, "analyze")) {
        // 'analyze' requires a filename argument
        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' requires text to 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' requires both text and a single character to count
        if (args.len < 4) {
            std.debug.print("Error: count requires text and character\n", .{});
            return;
        }
        // Validate that the character argument is exactly one byte
        if (args[3].len != 1) {
            std.debug.print("Error: character must be single byte\n", .{});
            return;
        }
        try countCharacter(args[2], args[3][0]);
    } else {
        // Handle unrecognized commands
        std.debug.print("Unknown command: {s}\n", .{command});
        try printUsage();
    }
}

/// Print usage information to guide users on available commands
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});
}

/// Read a file and display statistical analysis of its text content
fn analyzeFile(allocator: std.mem.Allocator, filename: []const u8) !void {
    // Open the file in read-only mode from the current working directory
    const file = try std.fs.cwd().openFile(filename, .{});
    defer file.close();

    // Read the entire file content into memory (limited to 1MB)
    const content = try file.readToEndAlloc(allocator, 1024 * 1024);
    defer allocator.free(content);

    // Use textkit library to compute text statistics
    const stats = textkit.TextStats.analyze(content);

    // Display the computed statistics to the user
    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)});
}

/// Reverse the provided text and display both original and reversed versions
fn reverseText(text: []const u8) !void {
    // Allocate a stack buffer for in-place reversal
    var buffer: [1024]u8 = undefined;
    
    // Ensure the input text fits within the buffer
    if (text.len > buffer.len) {
        std.debug.print("Error: text too long (max {d} chars)\n", .{buffer.len});
        return;
    }

    // Copy input text into the mutable buffer for reversal
    @memcpy(buffer[0..text.len], text);
    
    // Perform in-place reversal using textkit utility
    textkit.StringUtils.reverse(buffer[0..text.len]);

    // Display both the original and reversed text
    std.debug.print("Original: {s}\n", .{text});
    std.debug.print("Reversed: {s}\n", .{buffer[0..text.len]});
}

/// Count occurrences of a specific character in the provided text
fn countCharacter(text: []const u8, char: u8) !void {
    // Use textkit to count character occurrences
    const count = textkit.StringUtils.countChar(text, char);
    
    // Display the count result
    std.debug.print("Character '{c}' appears {d} time(s) in: {s}\n", .{
        char,
        count,
        text,
    });
}

// Test that all declarations in this module are reachable and compile correctly
test "main program compiles" {
    std.testing.refAllDecls(@This());
}

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

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

    // Retrieve command line arguments passed to the program
    const args = try std.process.argsAlloc(allocator);
    defer std.process.argsFree(allocator, args);

    // Ensure at least one command argument is provided (args[0] is the program name)
    if (args.len < 2) {
        try printUsage();
        return;
    }

    // Extract the command verb from the first argument
    const command = args[1];

    // Dispatch to the appropriate handler based on the command
    if (std.mem.eql(u8, command, "analyze")) {
        // 'analyze' requires a filename argument
        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' requires text to 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' requires both text and a single character to count
        if (args.len < 4) {
            std.debug.print("Error: count requires text and character\n", .{});
            return;
        }
        // Validate that the character argument is exactly one byte
        if (args[3].len != 1) {
            std.debug.print("Error: character must be single byte\n", .{});
            return;
        }
        try countCharacter(args[2], args[3][0]);
    } else {
        // Handle unrecognized commands
        std.debug.print("Unknown command: {s}\n", .{command});
        try printUsage();
    }
}

/// Print usage information to guide users on available commands
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});
}

/// Read a file and display statistical analysis of its text content
fn analyzeFile(allocator: std.mem.Allocator, filename: []const u8) !void {
    // Open the file in read-only mode from the current working directory
    const file = try std.fs.cwd().openFile(filename, .{});
    defer file.close();

    // Read the entire file content into memory (limited to 1MB)
    const content = try file.readToEndAlloc(allocator, 1024 * 1024);
    defer allocator.free(content);

    // Use textkit library to compute text statistics
    const stats = textkit.TextStats.analyze(content);

    // Display the computed statistics to the user
    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)});
}

/// Reverse the provided text and display both original and reversed versions
fn reverseText(text: []const u8) !void {
    // Allocate a stack buffer for in-place reversal
    var buffer: [1024]u8 = undefined;
    
    // Ensure the input text fits within the buffer
    if (text.len > buffer.len) {
        std.debug.print("Error: text too long (max {d} chars)\n", .{buffer.len});
        return;
    }

    // Copy input text into the mutable buffer for reversal
    @memcpy(buffer[0..text.len], text);
    
    // Perform in-place reversal using textkit utility
    textkit.StringUtils.reverse(buffer[0..text.len]);

    // Display both the original and reversed text
    std.debug.print("Original: {s}\n", .{text});
    std.debug.print("Reversed: {s}\n", .{buffer[0..text.len]});
}

/// Count occurrences of a specific character in the provided text
fn countCharacter(text: []const u8, char: u8) !void {
    // Use textkit to count character occurrences
    const count = textkit.StringUtils.countChar(text, char);
    
    // Display the count result
    std.debug.print("Character '{c}' appears {d} time(s) in: {s}\n", .{
        char,
        count,
        text,
    });
}

// Test that all declarations in this module are reachable and compile correctly
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,
    });
    
    // Install the library (to zig-out/lib/)
    b.installArtifact(lib);
    
    // ===== EXECUTABLE =====
    // Create executable that uses the library
    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 },
            },
        }),
    });
    
    // Install the executable (to zig-out/bin/)
    b.installArtifact(exe);
    
    // ===== RUN STEP =====
    // Create a run step for the executable
    const run_cmd = b.addRunArtifact(exe);
    run_cmd.step.dependOn(b.getInstallStep());
    
    // Forward command-line arguments to the application
    if (b.args) |args| {
        run_cmd.addArgs(args);
    }
    
    const run_step = b.step("run", "Run the TextKit CLI");
    run_step.dependOn(&run_cmd.step);
    
    // ===== TESTS =====
    // Library tests
    const lib_tests = b.addTest(.{
        .root_module = textkit_mod,
    });
    
    const run_lib_tests = b.addRunArtifact(lib_tests);
    
    // Executable tests (minimal for main.zig)
    const exe_tests = b.addTest(.{
        .root_module = exe.root_module,
    });
    
    const run_exe_tests = b.addRunArtifact(exe_tests);
    
    // Test step that runs all tests
    const test_step = b.step("test", "Run all tests");
    test_step.dependOn(&run_lib_tests.step);
    test_step.dependOn(&run_exe_tests.step);
    
    // ===== CUSTOM STEPS =====
    // Demo step that shows usage
    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