# WordCounter

**Repository Path**: yht_666/word-counter

## Basic Information

- **Project Name**: WordCounter
- **Description**: 本项目是一个基于 Python 实现的命令行程序，旨在完成软件工程课程要求的文本与代码统计任务。它严格遵循版本迭代规范，从一个可运行的空项目逐步演进，最终成为了一个功能强大、经过全面测试的综合性分析工具。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-29
- **Last Updated**: 2025-10-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# WordCounter - 多功能命令行文本与代码分析工具

[![Python Version](https://img.shields.io/badge/python-3.6%2B-blue.svg)](https://www.python.org/)
[![Test Status](https://img.shields.io/badge/tests-passing-brightgreen.svg)](v0.3/test.py)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

本项目是一个基于 Python 实现的命令行程序，旨在完成软件工程课程要求的文本与代码统计任务。它严格遵循版本迭代规范，从一个可运行的空项目逐步演进，最终成为了一个功能强大、经过全面测试的综合性分析工具。

## 项目结构总览

本项目严格按照作业需求，将完成作业过程中不同阶段的完整项目分别存放在对应的版本文件夹中，显示出迭代过程，结构清晰，一目了然。

```
WordCounter/
├── examples/        # 存放所有用于功能测试以及性能测试的样例文件
│   ├── performance_test.txt
│   ├── test_code_c.c
│   └── test_code_python.py
│   └── ...
├── v0.1/                    # v0.1 版本：可运行的空项目
│   ├── main.py
│   ├── main.exe
│   └── v0.1运行结果.png
├── v0.2/                    # v0.2 版本：实现所有基础功能
│   ├── main.py
│   ├── test.py
│   ├── main.exe
│   ├── v0.2单元测试结果.png
│   ├── v0.2性能测试结果.png
│   └── v0.2运行结果.png
├── v0.3/                    # v0.3 版本：实现所有扩展功能
│   ├── main.py
│   ├── test.py
│   ├── performance.py
│   ├── main.exe
│   ├── v0.3_code_性能测试结果.png
│   ├── v0.3_txt_性能测试结果.png
│   ├── v0.3单元测试结果.png
│   ├── v0.3运行结果.png
│   └── v0.3智能建议测试结果.png
├── LICENSE                  # 开源协议
└── README.md                # 本项目总说明文档
```

## a. 项目简介及其相关的用法

本工具的核心程序是各版本文件夹下的 `main.exe` (Windows) 以及 `main.py` (跨平台)。它包含两种主要操作模式，分别用于处理不同类型的文件。

### **模式一：自然语言文本分析 (基础功能)**

此模式用于分析纯英文文章、报告等 `.txt` 文件。

**可用参数:**
*   `-c`, `--chars`: 统计字符数。
*   `-w`, `--words`: 统计单词数。
*   `-s`, `--sentences`: 统计句子数。
*   `--all`: 显示所有基础统计信息。

**命令行用法示例 (以 v0.3 版本为例):**
```bash
# 进入 v0.3 文件夹
cd v0.3

# 分析一篇英文文章 (test1.txt)
.\main.exe --all ..\examples\test1.txt
```

### **模式二：源代码文件分析 (扩展功能)**

此模式用于智能分析 `.py` 和 `.c` 等源代码文件，以衡量其代码结构。

**可用参数:**
*   `-x`, `--extended`: 显示所有代码分析信息。
*   `-l`, `--total-lines`: 统计总行数。
*   `-cl`, `--code-lines`: 统计代码行。
*   `-bl`, `--blank-lines`: 统计空行。
*   `-nl`, `--comment-lines`: 统计注释行。

**命令行用法示例 (以 v0.3 版本为例):**
```bash
# 进入 v0.3 文件夹
cd v0.3

# 分析一个 Python 源代码文件
.\main.exe -x ..\examples\test_code_python1.py

# 只看一个 C 语言文件的代码行数
.\main.exe -cl ..\examples\test_code_c1.c
```

## b. 文件列表及其相关说明

*   **`main.py`**: 各版本的核心程序文件，包含所有功能逻辑。
*   **`test.py`**: 各版本的单元测试文件，使用 `unittest` 模块对核心功能进行全面测试。
*   **`performance.py`**: 性能测试脚本，使用 `cProfile` 对程序进行性能分析。
*   **`main.exe`**: 由 `PyInstaller` 打包生成的可执行文件，方便在未安装 Python 的 Windows 环境下运行。
*   **`examples/`**: 存放各类用于功能演示和测试的文本文件及源代码文件。
*   **`*.png`**: 各版本的功能运行、单元测试及性能测试的结果截图。

## c. 例程运行及其相关结果
### v0.1 版本 - 空项目
#### **运行结果**
![v0.1 运行结果](v0.1/v0.1运行结果.png)

### v0.2 版本 - 基础功能

#### **运行结果**
![v0.2 运行结果](v0.2/v0.2运行结果.png)

#### **单元测试结果**
![v0.2 单元测试结果](v0.2/v0.2单元测试结果.png)

#### **性能测试结果**
![v0.2 性能测试结果](v0.2/v0.2性能测试结果.png)

### v0.3 版本 - 扩展功能

#### **运行结果**
![v0.3 运行结果](v0.3/v0.3运行结果.png)

#### **单元测试结果**
![v0.3 单元测试结果](v0.3/v0.3单元测试结果.png)

#### **性能测试结果**
![v0.3 性能测试结果](v0.3/v0.3_txt_性能测试结果.png)

## d. 异常处理说明 (智能建议功能)

为了提升用户体验，本项目在 v0.2 及 v0.3 版本中加入了智能的异常处理机制。当用户输入的命令行参数指向一个不存在的文件时，程序不仅会报告“文件未找到”的错误，还会**智能地猜测用户可能想要输入的文件名**，并给出修正建议。

该功能基于**莱文斯坦距离 (Levenshtein Distance)** 算法实现，通过计算用户输入与目标目录下所有文件名的“编辑距离”，找出最相似的一个作为推荐。

### **功能演示**

**命令行示例(以 v0.3 版本为例) :**
```bash
# 进入 v0.3 文件夹
cd v0.3
#依次输入如下命令，测试智能建议功能
.\main.exe -x ..\examples\test_code1_python.pyy
.\main.exe -all ..\examples\test_1.txtt
.\main.exe -x ..\examples\test_code_c1.cc 
```
#### **运行结果**
![v0.3 智能建议测试结果](v0.3/v0.3智能建议测试结果.png)
## e. 心得体会
本项目从最初的空框架逐步迭代到功能完善的综合分析工具，让我深入体会了软件开发的完整流程。

在v0.1阶段，我掌握了命令行参数和文件读写的基本实现；v0.2阶段重点在文本分析功能的完善与单元测试的运用；v0.3阶段则通过正则表达式与逻辑优化，实现了Python与C代码的自动识别与统计。

整个过程中，我学会了如何规划功能、调试程序、撰写清晰的文档，也体会到测试与性能优化的重要性。通过本次作业，我更加理解了软件工程的系统性与规范性，也提升了自己在代码设计和问题分析方面的能力。