Haifa Python 编译器与虚拟机

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

• jq 风格 JSON 处理运行时（JQ）
• Lua 子集解释执行（Lua）

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

1. 项目快速入手

• 环境准备
  • Python 3.11+（推荐虚拟环境）
  • 一键创建/激活并安装依赖：

    source scripts/activate_venv.sh
    # 如需 GUI 可视化，请额外安装 pygame
    pip install pygame

  • 运行测试：pytest

从源码编译安装 pylua / pyjq

1. 创建并激活虚拟环境（示例为 Bash）：

   python3 -m venv .venv
   source .venv/bin/activate

   Windows PowerShell 用户可使用 python -m venv .venv 与 .venv\Scripts\Activate.ps1。

2. 安装构建依赖并构建 CLI：

   pip install --upgrade pip setuptools wheel
   pip install .

   • 该步骤会注册 pylua 与 pyjq 两个命令。
   • 若在离线或受限网络环境，可在确认本地已具备 setuptools/wheel 时使用 pip install --no-build-isolation .，或通过 python -m venv .venv --system-site-packages 复用系统站点包。
   • 需要 GUI 可视化时额外执行 pip install haifa-python[gui]（或手动安装 pygame）。

3. 验证安装：

   pylua --help
   pyjq --help
   pylua examples/hello.lua --print-output
   pyjq '.items[] | .name' --input compiler/sample.json

   • pylua 命令会输出帮助文本，并在运行示例脚本时打印 Hello, Lua。
   • pyjq 命令同样会输出帮助文本，并针对 compiler/sample.json 打印示例数据中的 "Alice"、"Bob"、"Cia"。

4. 如需卸载与清理：

   pip uninstall haifa-python -y
   deactivate
   rm -rf .venv

• 体验 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 中改用指定字体文件，例如：

  # 替换 SysFont 为系统字体文件（示例）
  self.font = pygame.font.Font('/System/Library/Fonts/PingFang.ttc', FONT_SIZE)

  也可以将字体文件放入项目并用相对路径加载。
• 在非图形环境下，使用 --visualize curses 进入终端可视化模式。