# wordcount

**Repository Path**: bao-shuyu/wordcount

## Basic Information

- **Project Name**: wordcount
- **Description**: 命令行文本计数统计程序
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-11-01
- **Last Updated**: 2026-11-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# wc.exe —— 命令行文本计数统计程序

一个用 C# 编写的 Windows 命令行小工具，用来统计纯英文文本的**字符数、单词数、句子数**，并扩展支持**总行数、空行数、注释行数、代码行数**以及**目录递归统计**。

- 语言：C#（.NET Framework 4.x，Windows 自带运行时）
- 构建：调用系统自带的 `csc.exe`，无需安装 Visual Studio 或 .NET SDK
- 测试：19 个单元测试，全部通过
- 性能：5 MB 文本平均约 0.59 s，约 8.5 MB/s

---

## 1. 项目简介与用法

### 1.1 命令格式

```
wc.exe [参数] [文件名或目录]
```

### 1.2 参数说明

| 参数 | 含义 | 类别 |
| --- | --- | --- |
| `-c` | 统计字符数 | 基础功能 |
| `-w` | 统计单词数 | 基础功能 |
| `-s` | 统计句子数 | 基础功能 |
| `-l` | 统计总行数 | 扩展功能 |
| `-a` | 统计空行数 | 扩展功能 |
| `-m` | 统计注释行数 | 扩展功能 |
| `-k` | 统计代码行数（非空且非注释） | 扩展功能 |
| `-r` | 递归统计目录下的文本/代码文件 | 扩展功能 |
| `-h` | 显示帮助 | 其他 |
| `-v` | 显示版本 | 其他 |

- 参数可以合并写，例如 `-cw`、`-lamk`；
- 不给任何参数时，默认统计字符数、单词数、句子数；
- 多个指标会分行输出，目录模式下会先输出每个文件，再输出合计。

### 1.3 使用示例

统计字符数：

```text
> wc.exe -c sample.txt
字符数: 240
```

统计单词数：

```text
> wc.exe -w sample.txt
单词数: 42
```

一次统计三项基础指标：

```text
> wc.exe -c -w -s sample.txt
字符数: 240
单词数: 42
句子数: 6
```

统计代码文件的行构成：

```text
> wc.exe -l -a -m -k code.c
总行数: 19
空行数: 3
注释行数: 4
代码行数: 12
```

递归统计目录（先建一个子目录放几个文件即可）：

```text
> wc.exe -r -l -a -m -k .
== .\code.c
总行数: 19
空行数: 3
注释行数: 4
代码行数: 12
== .\sample.txt
总行数: 3
空行数: 1
注释行数: 0
代码行数: 2
== 合计 (2 个文件)
总行数: 22
空行数: 4
注释行数: 4
代码行数: 14
```

### 1.4 统计口径

| 指标 | 口径 |
| --- | --- |
| 字符数 | 文本解码后的字符总数，**包含空格、制表符和换行符**；纯英文时等于字节数（不含 BOM） |
| 单词数 | 以空白分隔、且至少含一个字母或数字的连续片段；支持 `don't`、`well-known` 这类连字符/撇号 |
| 句子数 | 以 `.`、`!`、`?` 结尾的句子数量；连续标点算一处，末尾没有标点的残句不计 |
| 总行数 | 换行符数量；文件末尾没有换行时最后一行也计入；空文件为 0 |
| 空行数 | 去掉首尾空白后长度为 0 的行 |
| 注释行数 | 以 `//`、`/*`、`*`（块注释续行）开头的行；`.py`、`.sh` 等脚本文件还识别 `#` |
| 代码行数 | 总行数 − 空行数 − 注释行数 |

> 说明：作业基础要求是“纯英文 txt”，因此字符数按字符计即可；程序也能处理 UTF-8 BOM 和 CRLF 换行。

### 1.5 退出码

| 退出码 | 含义 |
| --- | --- |
| 0 | 成功 |
| 1 | 参数错误（未知参数、缺少文件名、目录未加 `-r`） |
| 2 | 文件错误（文件不存在、读取失败、目录下没有可统计文件） |

---

## 2. 文件列表及说明

```text
wordcount/
├── README.md          项目说明（本文件）
├── build.bat          一键构建脚本，调用系统 csc.exe 生成 wc.exe
├── wc.cs              全部源代码（单文件，约 330 行）
├── sample.txt         英文文本示例，用于基础功能演示
├── code.c             C 代码示例，用于注释行/空行/代码行演示
├── test_wc.py         19 个单元测试（Python unittest）
├── perf_test.py       性能测试脚本（生成 5 MB 文本并计时）
├── make_repo.ps1      辅助脚本：按 v0.1 → v0.2 → v0.3 生成三次提交
├── wc_v0.2.cs         v0.2 基础功能版本源码（供提交历史使用）
├── wc_v0.3.cs         v0.3 完整版本源码（与 wc.cs 相同）
├── run-results.txt    示例运行结果汇总（可截图用）
├── .gitignore         忽略构建产物和测试临时文件
└── wc.exe             构建产物（不提交到仓库）
```

> 为方便在码云网页端直接上传文件，项目采用扁平目录结构，所有源码和文档都在根目录。

| 文件 | 作用 |
| --- | --- |
| `wc.cs` | 参数解析、文件读取、字符/单词/句子统计、行分类、目录递归、帮助信息 |
| `build.bat` | 定位 `%WINDIR%\Microsoft.NET\Framework64\v4.0.30319\csc.exe` 并编译 |
| `test_wc.py` | 调用 `wc.exe`，对输出和退出码做断言，覆盖正常与异常场景 |
| `perf_test.py` | 生成 5 MB 测试文本，重复运行 10 次并统计吞吐量 |
| `sample.txt` / `code.c` | 演示与手工验证用的小文件 |

---

## 3. 构建与运行环境

- 操作系统：Windows 10 / 11
- 运行时：.NET Framework 4.x（Windows 自带）
- 编译器：`C:\Windows\Microsoft.NET\Framework64\v4.0.30319\csc.exe`（随系统提供）
- 测试脚本：Python 3.8+（仅测试需要）

构建：

```bat
build.bat
```

成功输出：

```text
Build OK: wc.exe
```

---

## 4. 例程运行及结果

### 4.1 示例文件

`sample.txt`：

```text
The quick brown fox jumps over the lazy dog. This is a simple sample file for the word count program. It contains three sentences and some punctuation, like commas and hyphens.

A second paragraph starts here! Does it work? Yes, it should.
```

### 4.2 基础功能结果

| 命令 | 输出 |
| --- | --- |
| `wc.exe -c sample.txt` | `字符数: 240` |
| `wc.exe -w sample.txt` | `单词数: 42` |
| `wc.exe -s sample.txt` | `句子数: 6` |
| `wc.exe -c -w -s sample.txt` | 240 / 42 / 6 |

### 4.3 扩展功能结果

`code.c` 共 19 行，其中空行 3 行、注释行 4 行、代码行 12 行：

```text
> wc.exe -l -a -m -k code.c
总行数: 19
空行数: 3
注释行数: 4
代码行数: 12
```

### 4.4 异常输入

```text
> wc.exe -c not-exist.txt
错误: 找不到文件或目录 "not-exist.txt"。

> wc.exe -z sample.txt
错误: 未知参数 -z
使用 wc.exe -h 查看帮助。

> wc.exe -c .
错误: "." 是目录，请加 -r 递归统计。
```

---

## 5. 单元测试

测试文件：`test_wc.py`，共 **19 个用例**，覆盖：

- 基础功能：空文件、单个单词、单句、多句、连续空格/制表符、纯标点、连字符与撇号、默认参数；
- 编码与换行：CRLF 行数、UTF-8 BOM；
- 扩展功能：代码行/空行/注释行、`#` 注释、目录递归与合计；
- 异常处理：无参数、未知参数、文件不存在、目录未加 `-r`、合并参数。

运行：

```bat
python test_wc.py -v
```

运行结果：

```text
Ran 19 tests in 1.712s

OK
```

---

## 6. 性能测试

`perf_test.py` 会生成约 5 MB 的英文文本，连续运行 10 次 `wc.exe -c -w -s -l`：

```text
测试文件: _tmp\perf_big.txt (5.00 MB)
运行次数: 10
最快: 0.555 s
最慢: 0.606 s
平均: 0.588 s
吞吐量: 8.50 MB/s
```

> 说明：程序采用一次读入 + 正则统计，5 MB 文本（约 90 万单词、6 万句）在普通笔记本上不到 0.6 秒，满足日常使用。

---

## 7. 版本历史

| 版本 | 内容 |
| --- | --- |
| v0.1 | 空项目：初始化仓库，建立 README 和目录结构 |
| v0.2 | 完成基础功能 `-c / -w / -s`，可读取 txt 并输出统计结果 |
| v0.3 | 完成扩展功能 `-l / -a / -m / -k / -r`，补充单元测试、性能测试和完整文档 |

对应提交：

```bat
git log --oneline --decorate
# v0.3 ... 完成扩展功能：行统计、目录递归、单元测试与性能测试
# v0.2 ... 完成基础功能：-c 字符数、-w 单词数、-s 句子数
# v0.1 ... 空项目：初始化仓库与项目说明
```

---

## 8. 上传到码云（Gitee）

仓库地址：`https://gitee.com/bao-shuyu/wordcount`

网页端上传方式（无需安装 Git）：

1. 进入仓库，点「上传文件」；
2. 第一次（v0.1）：上传 `README.md`、`.gitignore`，提交信息填 `v0.1 空项目：初始化仓库与项目说明`；
3. 第二次（v0.2）：上传 `README.md`、`build.bat`、`wc_v0.2.cs` 并重命名为 `wc.cs`、`sample.txt`，提交信息填 `v0.2 完成基础功能：字符数、单词数、句子数`；
4. 第三次（v0.3）：上传 `wc.cs`（完整版）、`code.c`、`test_wc.py`、`perf_test.py`、`make_repo.ps1`、`run-results.txt`，提交信息填 `v0.3 完成扩展功能：行统计、递归、单元测试与性能测试`；
5. 仓库首页「标签」中依次新建 `v0.1`、`v0.2`、`v0.3`。

命令行方式（已安装 Git）：

```bat
git init
git add README.md .gitignore
git commit -m "v0.1 空项目：初始化仓库与项目说明"
git tag v0.1

copy /Y wc_v0.2.cs wc.cs
git add wc.cs build.bat sample.txt
git commit -m "v0.2 完成基础功能：字符数、单词数、句子数"
git tag v0.2

copy /Y wc_v0.3.cs wc.cs
git add .
git commit -m "v0.3 完成扩展功能：行统计、递归、单元测试与性能测试"
git tag v0.3

git remote add origin https://gitee.com/bao-shuyu/wordcount.git
git push -u origin master --tags
```

> 也可以直接运行 `make_repo.ps1`，自动生成带三次提交的仓库目录。

---

## 9. 设计说明与已知限制

- **为什么用 C#**：Windows 自带 .NET Framework 编译器和运行时，双击 `build.bat` 即可生成 `wc.exe`，不需要额外安装环境。
- **单文件实现**：所有逻辑集中在一个 `wc.cs` 中，便于阅读和提交；类 `Stats` 负责数据，`Program` 负责流程。
- **注释识别**：只识别行首的 `//`、`/*`、`*` 以及脚本语言的 `#`；`x = 1; // 行尾注释` 仍算代码行，这是常见简化。
- **字符数**：按 .NET 字符串长度统计（UTF-16 码元），纯英文场景与字节数一致；含中文时一个汉字计 1 个字符。
- **未实现**：`-e` 停用词表、多文件并行统计、彩色输出等，属于可选扩展，当前版本未包含。