https://github.com/aarenwang/haifa-python

类汇编语言解释执行引擎
https://github.com/aarenwang/haifa-python

abstract-syntax-tree assembly-language bytecode-interpreter interpreter x86-assembly

Last synced: 4 months ago
JSON representation

类汇编语言解释执行引擎

• Host: GitHub
• URL: https://github.com/aarenwang/haifa-python
• Owner: AarenWang
• Created: 2025-04-30T14:43:30.000Z (9 months ago)
• Default Branch: master
• Last Pushed: 2025-09-22T14:37:49.000Z (4 months ago)
• Last Synced: 2025-09-22T16:34:08.456Z (4 months ago)
• Topics: abstract-syntax-tree, assembly-language, bytecode-interpreter, interpreter, x86-assembly
• Language: Python
• Homepage:
• Size: 45.9 KB
• Stars: 0
• Watchers: 1
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

          
# Haifa Python 编译器与虚拟机

Haifa Python 是一个教学友好、可视化友好的“字节码编译器 + 虚拟机”实验平台。在统一的 Core VM 上，项目同时承载：

- jq 风格 JSON 处理运行时（JQ）

- Lua 子集解释执行（Lua）

你可以从“源代码/脚本 → AST → 字节码 → 虚拟机执行”的完整链路中学习、实验和扩展，并用 GUI/终端可视化器实时观察执行过程。

## 1. 项目快速入手

- 环境准备

  - Python 3.11+（推荐虚拟环境）

  - 一键创建/激活并安装依赖：

    ```bash

    source scripts/activate_venv.sh

    # 如需 GUI 可视化，请额外安装 pygame

    pip install pygame

    ```

  - 运行测试：`pytest`

- 体验 Lua（pylua）

  - 运行脚本：`pylua examples/hello.lua`

  - 单行执行：`pylua -e 'x=1; y=2; return x+y' --print-output`

  - REPL：`pylua --repl`

  - 可视化执行：

    - GUI：`pylua examples/coroutines.lua --visualize`

    - 终端：`pylua examples/coroutines.lua --visualize curses`

- 体验 jq（pyjq）

  - 从文件：`pyjq '.items | map(.name)' --input data.json`

  - 从标准输入：`cat data.json | pyjq '.items[] | .price'`

  - 可视化（终端）：`python -m compiler.jq_cli '.[]' --input data.json --visualize curses`

提示：GUI 可视化器依赖 pygame；若没有图形环境或导入失败，会自动回退到 curses 终端模式。

## 2. 本项目快速介绍

- 完整流水线：源/脚本 → 词法/语法 → AST → 字节码 → Core VM → 可视化

- 分层设计：核心指令集精简通用；JQ/Lua 分别在其上提供语义与标准库

- 可视化调试：pygame GUI 与 curses 终端两种形态；支持协程事件时间线、寄存器变更高亮、指令搜索、执行轨迹导出

- 测试与样例：200+ 测试与多份示例脚本，覆盖从指令到 CLI 的端到端路径

## 3. 项目架构概览

- Core 层（`compiler/`）

  - `bytecode.py`：指令与调试元信息

  - `bytecode_vm.py`：字节码虚拟机（寄存器模型、调用栈、事件/快照）

  - 可视化：`vm_visualizer.py`（GUI）、`vm_visualizer_headless.py`（curses）

- JQ 层（`compiler/`）

  - `jq_parser.py` / `jq_ast.py` / `jq_compiler.py`：jq 解析与编译

  - `jq_vm.py`：JQVM（在 Core VM 上扩展）

  - `jq_cli.py`：命令行入口（`pyjq`）

- Lua 层（`haifa_lua/`）

  - 前端：`lexer.py`、`parser.py`、`compiler.py`

  - 运行时：`runtime.py`、`environment.py`、`stdlib.py`、`coroutines.py`

  - 命令行：`cli.py`（`pylua`）

## 4. 代码层次与常用入口

- 指令分层

  - Core Opcode：算术/逻辑/跳转/表/闭包/多返回等通用操作（`compiler/bytecode.py`）

  - JQ Opcode：对象访问、迭代、聚合、字符串等（`compiler/jq_*`）

  - 执行单元：`BytecodeVM` 仅实现 Core；`JQVM` 在其上扩展 JQ 指令

- CLI 与示例

  - CLI：`pylua` 与 `pyjq`

  - 示例：`examples/*.lua`；基准：`benchmark/scripts/*.lua`

  - 可视化：`--visualize [gui|curses]`（Lua 与 jq 均支持）

## 5. 相关文档索引

- 语言/运行时与计划

  - `docs/lua_sprint.md`：Lua 解释器里程碑与计划（含协程 API 完备）

  - `docs/lua_guide.md`：Lua 实践指南与示例

  - `docs/jq_design.md`：jq 设计与指令分层

- 可视化与调试

  - `knowledge/07-debugger-architecture.md`：调试器架构与原则

  - `knowledge/09-coroutine-visualizer-and-error-plan.md`：协程事件与错误展示计划

- 性能与基准

  - `docs/performance_benchmark.md`：Lua 解释器性能基准方案

  - `benchmark/`：脚本、运行器与报告示例

---

附注

- GUI 中文显示：若 pygame GUI 无法显示中文，可在 `compiler/vm_visualizer.py` 中改用指定字体文件，例如：

  ```python

  # 替换 SysFont 为系统字体文件（示例）

  self.font = pygame.font.Font('/System/Library/Fonts/PingFang.ttc', FONT_SIZE)

  ```

  也可以将字体文件放入项目并用相对路径加载。

- 在非图形环境下，使用 `--visualize curses` 进入终端可视化模式。