# 命令行文本计数工具

**Repository Path**: zx20248906/text-counter

## Basic Information

- **Project Name**: 命令行文本计数工具
- **Description**: 基于 C++17 的英文文本计数工具，支持字符、单词、句子及代码行统计。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-29
- **Last Updated**: 2026-10-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 命令行文本计数工具

基于 C++17 的命令行工具，用于统计英文文本的字符数、单词数和句子数。支持 C/C++ 源文件的代码行、空行和注释行分类。当前版本为 v0.3。

## 本次更新：从 v0.2 到 v0.3

v0.2 已能完成英文文本统计。本版本在保留原有命令和计数规则的基础上，增加 C/C++ 源文件的行分类。

- **新增 `-l` 选项**：分别输出代码行、空行和注释行。例如，`wc.exe -l samples/code.cpp` 输出 5 个代码行、2 个空行和 4 个注释行；`-a` 仍只统计字符、单词和句子。
- **扩展统计实现**：增加行分类状态机，区分注释、普通字符串、字符字面量和原始字符串，避免把字符串内的 `//`、`/*` 当作注释起点。
- **扩展回归测试**：保留 v0.2 的 28 个单元测试和 17 个命令行场景，新增 29 个行分类单元测试及 1 个 `-l` 集成场景。
- **加入性能测量**：新增数据生成脚本和耗时测量程序，记录 1、10、50 MiB 输入的实际测量结果；新增 `wc_profile` 固定负载，供 Visual Studio CPU 使用率工具分析热点。
- **补充源代码样例**：新增 `samples/code.cpp`，展示代码与注释混排、块注释及空行的分类结果。

验收结果：Debug、Release 配置各 58 项 CTest 全部通过，其中命令行测试包含 18 个场景。

## 环境要求

- Windows 10/11 x64。
- 支持 C++17 的 MinGW-w64 GCC 9 或更高版本工具链，包含 `g++` 和 `mingw32-make`。
- CMake 3.24 或更高版本。
- PowerShell 5.1 或更高版本（使用构建脚本时需要）。

编译器和 CMake 应加入 PATH。编辑器不作要求；VS Code 可安装 C/C++ 和 CMake Tools 扩展。

进行 IDE CPU 分析时使用 Visual Studio Community（包含“使用 C++ 的桌面开发”工作负载）。运行 `scripts/build-vs.ps1` 可生成用于分析的 Release 解决方案。

测试依赖 GoogleTest v1.14.0，源码包已包含在项目中，构建时无需下载。

## 构建

在项目根目录执行：

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\build.ps1
```

默认生成 Debug 程序并执行测试，输出目录为 `build/debug`。使用 `-Configuration Release` 生成 Release 程序。工具不在 PATH 时，可通过 `-CompilerDirectory` 指定 MinGW 的 bin 目录，通过 `-CMakePath` 指定 cmake.exe。

源码与工具链路径均为英文时，也可直接使用 CMake：

```powershell
cmake --preset debug
cmake --build --preset debug
ctest --preset debug
```

构建脚本兼容中文路径的 MinGW 工具链，执行期间需要 W:、X: 两个空闲盘符。

## 命令用法

```text
wc.exe [选项] 文件名
```

| 选项 | 功能 |
|---|---|
| `-c` | 统计字符数 |
| `-w` | 统计单词数 |
| `-s` | 统计句子数 |
| `-a` | 同时统计字符、单词和句子 |
| `-l` | 统计代码行、空行和注释行 |
| `--help` | 显示帮助 |
| `--version` | 显示版本 |

```powershell
.\build\debug\wc.exe -c .\samples\english.txt
.\build\debug\wc.exe -w .\samples\english.txt
.\build\debug\wc.exe -s .\samples\english.txt
.\build\debug\wc.exe -a .\samples\english.txt
.\build\debug\wc.exe -c -w ".\samples\中文 路径.txt"
```

选项可组合，重复选项只输出一次。每次处理一个文件。文件名含空格时用引号包围；以短横线开头时使用 `--` 分隔，例如 `wc.exe -a -- -notes.txt`。

退出码为 `0` 表示成功，`1` 表示文件或读取错误，`2` 表示参数错误。错误信息写入标准错误流。

## 统计规则

输入为 ASCII 英文文本，可带 UTF-8 BOM。

- **字符**：包括字母、数字、标点和空白；开头的 BOM 不计数，CRLF、LF、CR 均按一个换行字符计数。
- **单词**：连续英文字母构成单词，内部允许单个撇号或连字符；`don't`、`well-known` 各计一个，`a--b` 计两个。数字和下划线分隔单词，纯数字不计入单词数。
- **句子**：包含字母或数字的片段遇到 `. ! ?` 时结束；连续结束标点不产生空句，末尾未加标点的有效片段也计一句。英文缩写、小数和网址按相同标点规则处理。

## 运行示例

`samples/english.txt` 包含以下两行，最后一行以换行结束：

```text
Hello, world!
How are you? I am fine.
```

执行 `wc.exe -a samples/english.txt`，输出：

```text
字符数：38
单词数：8
句子数：3
```

两行正文分别为 13、23 个字符，加上两个换行，共 38 个字符。

## 代码行统计

执行 `wc.exe -l samples/code.cpp`，输出：

```text
代码行：5
空行：2
注释行：4
```

![v0.3 代码行统计与完整测试结果](docs/screenshots/v03-代码行.png)

三类行互斥，总和为文件的物理行数：

- 空行：空行或仅含空白字符的行，包括块注释、原始字符串中的纯空白行。
- 代码行：含实际代码的行；代码与注释混排时仍归为代码行。
- 注释行：仅含注释及空白的行。

支持 C/C++ 单行注释、块注释、普通字符串、字符字面量、转义字符、原始字符串，以及行末反斜杠延续的单行注释。末尾换行不增加额外行。统计按源文件物理行进行，不执行预处理，也不合并反斜杠拆开的注释分隔符。

## 文件说明

| 文件或目录 | 内容 |
|---|---|
| `src/main.cpp` | 参数解析、文件读取入口和结果输出 |
| `src/counter.cpp` | 文本统计实现 |
| `include/counter.h` | 统计结果和函数接口 |
| `tests/counter_tests.cpp` | 文本统计单元测试 |
| `tests/cli_tests.cmake` | 命令行集成测试 |
| `tests/line_tests.cpp` | 代码行分类单元测试 |
| `benchmarks/` | 性能测试程序和数据生成脚本 |
| `samples/` | 英文文本及代码样例 |
| `scripts/build.ps1` | MinGW 构建与测试脚本 |
| `scripts/build-vs.ps1` | Visual Studio 构建与测试脚本 |
| `CMakeLists.txt`、`CMakePresets.json` | 构建规则及预设 |
| `.vscode/` | 可选的编辑器配置 |
| `third_party/` | GoogleTest 源码包、来源及许可证 |
| `docs/` | 测试报告、运行截图与 AI 提示词记录 |
| `VERSION` | 当前版本号 |

## 实现与测试

字符、单词和句子在单次扫描中统计，时间复杂度 O(n)，额外空间 O(1)。代码行分类采用状态机，缓存当前物理行，额外空间 O(L)，L 为最长行的长度。

测试覆盖及结果见 [测试说明](docs/测试说明.md)。性能测试方法及测量结果见 [性能分析](docs/性能分析.md)。AI 使用记录见 [AI 提示词记录](docs/AI提示词记录.md)。

### v0.3 单元测试

57 个单元测试全部通过，完整 CTest 测试另包含一组命令行集成测试，共 58 项。

![v0.3 单元测试结果](docs/screenshots/v03-测试.png)

### 性能分析

Release 文件统计耗时和 Visual Studio CPU 采样结果如下，测量方法及指标说明见 [性能分析](docs/性能分析.md)。

![v0.3 文件统计耗时](docs/screenshots/v03-运行耗时.png)

![Visual Studio CPU 使用率分析](docs/screenshots/v03-IDE性能分析.png)

## 历史版本运行记录

![v0.1 空项目构建与运行结果](docs/screenshots/v01-空项目.png)

### v0.2 文本统计与基础测试

![v0.2 文本统计结果](docs/screenshots/v02-文本统计.png)

![v0.2 基础单元测试结果](docs/screenshots/v02-测试.png)