LC-3 Assembler Project (Python Implementation)

这是一个功能完整的 LC-3 (Little Computer 3) 汇编器项目，使用 Python 编写。它不仅实现了将 LC-3 汇编代码转换为机器码的核心功能，还包含了一套完整的批量编译和自动化测试工具链。

🚀 项目功能特性

• 完整指令集支持：支持所有 LC-3 ISA 指令（ADD, AND, BR, JMP, RET, JSR, LD, LDI, LDR, LEA, NOT, ST, STI, STR, TRAP, RTI）。
• 伪指令支持：支持 .ORIG, .END, .FILL, .BLKW, .STRINGZ。
• 智能错误检测：
  • 能够检测并报告语法错误、标签重定义、未定义标签、立即数越界、操作数数量错误等。
  • 错误信息会同时在终端显示并输出到 .err 文件中。
• .END 处理：自动忽略 .END 伪指令之后的所有内容。
• 双模式运行：支持单文件处理模式和标准输入流模式。
• 自动化工具链：内置批量编译脚本和正确性验证脚本。

📂 项目结构

assembler_python/
├── lc3_assembler.py      # [核心] 汇编器主程序
├── batch_compile.py      # [工具] 批量编译脚本
├── batch_check.py        # [工具] 批量正确性检查脚本
├── compare_files.py      # [工具] 文件差异比对工具（忽略空白符）
├── README.md             # 项目说明文档
├── asm/                  # [输入] 存放 .asm 源代码文件
├── bin/                  # [输出] 存放生成的 .bin 机器码文件和 .err 错误文件
├── symbol/               # [输出] 存放生成的符号表文件 (*_symtable.txt)
├── bin_expected/         # [测试] 存放预期的正确 .bin 文件（用于自动测试）
└── symbol_expected/      # [测试] 存放预期的正确符号表文件（用于自动测试）

🛠️ 使用指南

1. 单个文件汇编 (lc3_assembler.py)

基本用法： 读取 ./asm/ 目录下的文件，并将结果输出到 ./bin/ 和 ./symbol/。

python lc3_assembler.py test_simple.asm

参数说明：

• input_file: 输入文件名（默认在 ./asm/ 下查找，也可以是绝对路径）。

标准输入模式（管道）：

# Windows PowerShell
Get-Content asm\test_simple.asm | python lc3_assembler.py

# Linux/macOS
cat asm/test_simple.asm | python lc3_assembler.py

2. 批量编译 (batch_compile.py)

自动扫描 ./asm/ 文件夹中的所有 .asm 文件并进行编译。

python -B batch_compile.py

• 成功：在 ./bin/ 生成 .bin 文件，在 ./symbol/ 生成 _symtable.txt。
• 失败：在 ./bin/ 生成 .err 文件，包含具体错误信息。

3. 自动化测试与验证 (batch_check.py)

将当前生成的输出与预期正确答案进行对比。你需要预先将正确的 .bin 文件放入 bin_expected/，将正确的符号表放入 symbol_expected/。

python -B batch_check.py

该脚本会：

1. 检查是否存在对应的预期文件。
2. 调用 compare_files.py 逐一比对（忽略空白字符差异）。
3. 输出PASS/FAIL报告。

4. 文件比对工具 (compare_files.py)

单独比较两个文件内容是否一致（忽略换行和空格）。

# 模式 A: 比较任意两个文件
python compare_files.py path/to/file1 path/to/file2

# 模式 B: 比较特定测试用例的生成结果与预期结果
# 比较二进制
python compare_files.py bin test_simple
# 比较符号表
python compare_files.py symbol test_simple

📝 输入输出格式

输入 (.asm)：

• 标准 LC-3 汇编语法。
• 标签不区分大小写。
• .STRINGZ 支持 \n 转义。
• 例子：

  .ORIG x3000
  LOOP ADD R0, R0, #-1
       BRp LOOP
       HALT
  .END

输出 (.bin)：

• ASCII 文本文件，由 '0' 和 '1' 组成。
• 第一行为起始地址（16位二进制）。
• 后续每行为一条指令或数据。

输出 (.err)：

• 仅在编译出错时生成。
• 包含具体的错误原因。

⚠️ 常见错误处理

如果汇编失败，请查看终端输出或 ./bin/ 目录下的同名 .err 文件。常见的错误包括：

• 缺少 .ORIG 或多个 .ORIG。
• 标签重定义或使用了未定义的标签。
• 立即数超出允许的位数范围（如 imm5 超出 -16~15）。
• 指令操作数数量不匹配。