# 111

**Repository Path**: lanshengkai/111

## Basic Information

- **Project Name**: 111
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# wc —— 命令行文本统计工具

> 软件工程个人作业：实现一个类似 Linux `wc` 的命令行文本统计程序，支持字符数、单词数、
> 句子数统计，并扩展支持代码行、空行、注释行统计。

## 1. 项目简介

`wc.exe` 是一个 Windows 命令行小工具，用来统计**纯英文 txt 文本**中的：

- **字符数**（`-c`）
- **单词数**（`-w`）
- **句子数**（`-s`）
- **行数**（`-l`）

以及面向源码文件的**扩展统计**（加分项）：

- **代码行**（`--code`）
- **空行**（`--blank`）
- **注释行**（`--comment`）

支持一次统计多个文件并输出合计，支持 `--json` 结构化输出，支持自动识别
C/C++/C#/Java/JS/Python/Shell/SQL/HTML 等语言的注释语法。

全部 67 个单元测试用例通过。

## 2. 运行环境与构建

- 运行环境：Windows + .NET Framework 4.x（Windows 10/11 自带，无需额外安装）
- 构建工具：`%WINDIR%\Microsoft.NET\Framework64\v4.0.30319\csc.exe`（系统自带 C# 编译器）

```bat
build.bat          :: 编译，生成 bin\wc.exe 与 bin\Wc.Tests.exe
run-tests.bat      :: 运行全部单元测试
```

也可以使用 Visual Studio 2022 打开 `wc.sln` 直接编译（三个项目：
`Wc.Core` 核心库、`wc` 命令行程序、`Wc.Tests` 单元测试）。

## 3. 用法

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

| 选项 | 长选项 | 说明 |
| --- | --- | --- |
| `-c` | `--chars` | 统计字符数 |
| `-w` | `--words` | 统计单词数 |
| `-s` | `--sentences` | 统计句子数 |
| `-l` | `--lines` | 统计行数 |
| `-a` | `--all` | 基础统计全部（默认） |
|  | `--code` | 统计代码行 |
|  | `--blank` | 统计空行 |
|  | `--comment` | 统计注释行 |
| `-x` | `--ext` | 扩展统计全部 |
| `-j` | `--json` | 以 JSON 格式输出 |
|  | `--lang <名称>` | 强制指定语言（c/cpp/cs/java/js/py/sh/sql/html/md/txt 等） |
| `-h` | `--help` | 显示帮助 |
| `-v` | `--version` | 显示版本 |
| `-` |  | 从标准输入读取 |

短选项可以合并写，例如 `-cws` 等价于 `-c -w -s`。

## 4. 运行示例

### 4.1 统计字符数

```bat
> bin\wc.exe -c samples\sample.txt
------------------------------------------------------------------
文件: samples\sample.txt
------------------------------------------------------------------
  字符数: 306
```

### 4.2 统计单词数

```bat
> bin\wc.exe -w samples\sample.txt
------------------------------------------------------------------
文件: samples\sample.txt
------------------------------------------------------------------
  单词数: 54
```

### 4.3 基础统计全部

```bat
> bin\wc.exe -a samples\sample.txt
------------------------------------------------------------------
文件: samples\sample.txt
------------------------------------------------------------------
  字符数: 306
  单词数: 54
  句子数: 7
  行数　: 7
```

### 4.4 扩展统计（代码行 / 空行 / 注释行）

```bat
> bin\wc.exe -x samples\demo.cs
------------------------------------------------------------------
文件: samples\demo.cs
------------------------------------------------------------------
  代码行: 21
  混合行: 2
  空行　: 3
  注释行: 7
  语言　: C/C++/C#/Java/JS
```

### 4.5 多个文件与合计

```bat
> bin\wc.exe -c samples\sample.txt samples\demo.cs
...
合计（2 个文件）
------------------------------------------------------------------
  字符数: 992
```

### 4.6 JSON 输出

```bat
> bin\wc.exe -a -x --json samples\demo.cs
{
  "tool": "wc",
  "version": "1.0.0",
  "files": [
    {"file": "samples\\demo.cs", "characters": 686, "words": 57, "sentences": 7, "lines": 31, "codeLines": 21, "mixedLines": 2, "blankLines": 3, "commentLines": 7}
  ],
  "total": {"characters": 686, "words": 57, "sentences": 7, "lines": 31, "codeLines": 21, "mixedLines": 2, "blankLines": 3, "commentLines": 7}
}
```

### 4.7 从标准输入读取

```bat
> type samples\sample.txt | bin\wc.exe -c -
```

### 4.8 运行结果截图

以下截图由 `bin\wc.exe` 的**真实输出**渲染生成，保存在 `docs/images/`：

**编译与单元测试**

![编译与单元测试](docs/images/01-build-and-tests.png)

**基础统计（字符数 / 单词数 / 句子数 / 全部）**

![基础统计](docs/images/02-basic-stats.png)

**扩展统计（代码行 / 空行 / 注释行）**

![扩展统计](docs/images/03-extended-stats.png)

**多文件合计与 JSON 输出**

![多文件与 JSON](docs/images/04-multi-and-json.png)

## 5. 统计规则

规则写在 `TextCounter` 与 `CodeCounter` 的注释里，并有对应单元测试。

### 5.1 字符数

- 统计文本中的**全部字符**，包括空格、制表符、换行符。
- `\r\n` 视为**一个**换行字符（避免 CRLF 文件字符数虚高）。
- 文件开头的 UTF-8 BOM 不计入。

### 5.2 单词数

- 单词 = 由**字母、数字、下划线**组成的连续串。
- 撇号 `'` 只有在两个单词字符之间时才属于单词：`don't` 算 1 个单词，`'hello'` 算 1 个单词。
- 其余字符（空格、逗号、连字符、换行等）都作为分隔符：
  `hello,world` 算 2 个单词，`well-known` 算 2 个单词。

### 5.3 句子数

- 以 `.` `!` `?` 结尾的片段算一句。
- 连续的句末标点算一处：`Wait... what?` 是 2 句，`Wow!!!` 是 1 句。
- 文件结尾没有句末标点、但含有非空白字符时，也算一句。

### 5.4 行数

- 等于换行符个数；最后一行若没有换行符结尾，则再加 1。
- 空文件为 0 行；`"abc\n"` 为 1 行；`"\n\n"` 为 2 行。

### 5.5 代码行 / 空行 / 注释行

逐行扫描，扫描时会**跳过字符串字面量**，所以 `"http://example.com"` 不会被误判成注释。

每行按内容分为三类，且满足恒等式：

```
总行数 = 代码行 + 注释行 + 空行
```

| 类别 | 判定 |
| --- | --- |
| 空行 | 去掉空白后为空的行 |
| 注释行 | 整行只有注释（含块注释内部的行） |
| 代码行 | 含任何代码的行，**包含混合行** |

其中「混合行」指同一行既有代码又有注释（例如 `int a = 1; // 说明`），
它是代码行的子集，单独列出便于观察，不重复计入总行数。

## 6. 文件列表

| 文件 | 说明 |
| --- | --- |
| `build.bat` | 使用系统自带 `csc.exe` 一键编译 |
| `run-tests.bat` | 运行单元测试 |
| `wc.sln` | Visual Studio 解决方案 |
| `src/Wc.Core/TextStats.cs` | 基础统计结果模型（支持 `+` 累加） |
| `src/Wc.Core/TextCounter.cs` | 字符 / 单词 / 句子 / 行的统计实现 |
| `src/Wc.Core/CodeStats.cs` | 扩展统计结果模型 |
| `src/Wc.Core/CodeCounter.cs` | 代码行 / 空行 / 注释行的逐行扫描实现 |
| `src/Wc.Core/CommentSyntax.cs` | 各语言注释语法表与按扩展名识别 |
| `src/Wc.Core/ReportFormatter.cs` | 文本报告 / JSON 报告格式化 |
| `src/Wc.Core/Cli/Options.cs` | 命令行参数解析与帮助文本 |
| `src/wc/Program.cs` | 命令行入口，负责文件读取与调度 |
| `tests/TestFramework.cs` | 自研轻量单元测试框架（Test / Assert / Runner） |
| `tests/TextCounterTests.cs` | 基础统计的 20 个测试用例 |
| `tests/CodeCounterTests.cs` | 扩展统计的 25 个测试用例 |
| `tests/OptionsTests.cs` | 参数解析的 17 个测试用例 |
| `tests/ReportFormatterTests.cs` | 输出格式化的 5 个测试用例 |
| `samples/sample.txt` | 英文文本样例 |
| `samples/demo.cs` | 含注释的源码样例 |
| `tools/gen-corpus.ps1` | 生成性能测试用的大文本 |
| `tools/bench.ps1` | 性能测试脚本（计时统计） |
| `docs/设计与实现.md` | 设计说明、模块划分与关键决策 |
| `docs/版本记录.md` | v0.1 / v0.2 / v0.3 三个版本的变更说明 |
| `docs/性能测试.md` | 性能测试环境、结果与分析 |
| `docs/images/*.png` | 运行结果截图（由真实输出渲染） |

## 7. 单元测试

测试不依赖任何第三方框架（不需要 NuGet，联网受限也能跑）：

```bat
> run-tests.bat
==================================================================
  wc 单元测试
==================================================================
[PASS] CodeCounterTests.AllCodeLines
...
------------------------------------------------------------------
通过 67 / 67，失败 0，用时 29 ms
```

退出码 0 表示全部通过，非 0 表示存在失败用例，可直接接入 CI。

支持按关键字过滤：

```bat
> bin\Wc.Tests.exe words
```

### 测试覆盖点

- 空文本、null、纯空白文本
- CRLF / LF / 末尾换行 / 连续空行
- 省略号、连续标点、无标点的结尾句
- 撇号、连字符、逗号分隔、数字与下划线
- UTF-8 BOM
- 单行注释、多行块注释、行尾混合注释、未闭合块注释
- 字符串中的 `//` 与转义引号
- Python/Shell、SQL、HTML 三种注释语法
- 参数合并写法、长选项、`--`、`-`、未知选项、非法语言
- 文本报告与 JSON 报告格式

## 8. 性能测试

```bat
> powershell -ExecutionPolicy Bypass -File tools\gen-corpus.ps1 -Megabytes 50
> powershell -ExecutionPolicy Bypass -File tools\bench.ps1
```

在本机（Windows 11 / .NET Framework 4.8）对约 50 MB 纯文本的实测结果：

| 操作 | 耗时 | 吞吐 |
| --- | --- | --- |
| 全量基础统计（字符+单词+句子+行）| 约 0.70 s | 约 71 MB/s |
| 扩展统计（代码行 / 空行 / 注释行）| 约 1.05 s | 约 48 MB/s |
| 基础 + 扩展 | 约 1.06 s | 约 47 MB/s |

详见 `docs/性能测试.md`。

## 9. 已知限制

- 只支持 UTF-8 / UTF-16（带 BOM）编码的文本，GBK 文件会乱码；
- 句子统计基于标点，`Mr. Smith`、`e.g.` 这类缩写会被多算一句；
- 代码统计不处理 C# 的逐字字符串 `@"..."`、Python 三引号文档字符串；
- 不识别嵌套块注释（Rust、Swift 支持嵌套）；
- 单词统计按「字母/数字连续串」口径，与 GNU `wc -w`（按空白切分）在
  `hello,world` 这类输入上结果不同，属有意设计并已在第 5.2 节说明。

## 10. 版本历史

| 版本 | 日期 | 内容 |
| --- | --- | --- |
| v0.1 | 2026-11-02 | 空项目：目录结构、README 骨架、`.gitignore` |
| v0.2 | 2026-11-02 | 完成基础功能：`-c/-w/-s/-l`、单元测试、样例文件 |
| v0.3 | 2026-11-02 | 完成扩展功能：代码行/空行/注释行、JSON 输出、性能测试（加分项） |