{"id":31537681,"url":"https://github.com/aarenwang/haifa-python","last_synced_at":"2025-10-04T08:09:10.251Z","repository":{"id":290809776,"uuid":"975578400","full_name":"AarenWang/haifa-python","owner":"AarenWang","description":"类汇编语言解释执行引擎","archived":false,"fork":false,"pushed_at":"2025-09-22T14:37:49.000Z","size":47,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-09-22T16:34:08.456Z","etag":null,"topics":["abstract-syntax-tree","assembly-language","bytecode-interpreter","interpreter","x86-assembly"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AarenWang.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-30T14:43:30.000Z","updated_at":"2025-09-22T14:37:53.000Z","dependencies_parsed_at":"2025-04-30T17:46:51.521Z","dependency_job_id":"4eb9d7e8-e6f5-4536-a040-b718ef289480","html_url":"https://github.com/AarenWang/haifa-python","commit_stats":null,"previous_names":["aarenwang/haifa-python"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/AarenWang/haifa-python","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AarenWang%2Fhaifa-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AarenWang%2Fhaifa-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AarenWang%2Fhaifa-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AarenWang%2Fhaifa-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AarenWang","download_url":"https://codeload.github.com/AarenWang/haifa-python/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AarenWang%2Fhaifa-python/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278283509,"owners_count":25961311,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-04T02:00:05.491Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["abstract-syntax-tree","assembly-language","bytecode-interpreter","interpreter","x86-assembly"],"created_at":"2025-10-04T08:09:07.998Z","updated_at":"2025-10-04T08:09:10.246Z","avatar_url":"https://github.com/AarenWang.png","language":"Python","readme":"# Haifa Python 编译器与虚拟机\n\n\nHaifa Python 是一个教学友好、可视化友好的“字节码编译器 + 虚拟机”实验平台。在统一的 Core VM 上，项目同时承载：\n- jq 风格 JSON 处理运行时（JQ）\n- Lua 子集解释执行（Lua）\n\n你可以从“源代码/脚本 → AST → 字节码 → 虚拟机执行”的完整链路中学习、实验和扩展，并用 GUI/终端可视化器实时观察执行过程。\n\n## 1. 项目快速入手\n\n- 环境准备\n  - Python 3.11+（推荐虚拟环境）\n  - 一键创建/激活并安装依赖：\n    ```bash\n    source scripts/activate_venv.sh\n    # 如需 GUI 可视化，请额外安装 pygame\n    pip install pygame\n    ```\n  - 运行测试：`pytest`\n\n- 体验 Lua（pylua）\n  - 运行脚本：`pylua examples/hello.lua`\n  - 单行执行：`pylua -e 'x=1; y=2; return x+y' --print-output`\n  - REPL：`pylua --repl`\n  - 可视化执行：\n    - GUI：`pylua examples/coroutines.lua --visualize`\n    - 终端：`pylua examples/coroutines.lua --visualize curses`\n\n- 体验 jq（pyjq）\n  - 从文件：`pyjq '.items | map(.name)' --input data.json`\n  - 从标准输入：`cat data.json | pyjq '.items[] | .price'`\n  - 可视化（终端）：`python -m compiler.jq_cli '.[]' --input data.json --visualize curses`\n\n提示：GUI 可视化器依赖 pygame；若没有图形环境或导入失败，会自动回退到 curses 终端模式。\n\n## 2. 本项目快速介绍\n\n- 完整流水线：源/脚本 → 词法/语法 → AST → 字节码 → Core VM → 可视化\n- 分层设计：核心指令集精简通用；JQ/Lua 分别在其上提供语义与标准库\n- 可视化调试：pygame GUI 与 curses 终端两种形态；支持协程事件时间线、寄存器变更高亮、指令搜索、执行轨迹导出\n- 测试与样例：200+ 测试与多份示例脚本，覆盖从指令到 CLI 的端到端路径\n\n## 3. 项目架构概览\n\n- Core 层（`compiler/`）\n  - `bytecode.py`：指令与调试元信息\n  - `bytecode_vm.py`：字节码虚拟机（寄存器模型、调用栈、事件/快照）\n  - 可视化：`vm_visualizer.py`（GUI）、`vm_visualizer_headless.py`（curses）\n\n- JQ 层（`compiler/`）\n  - `jq_parser.py` / `jq_ast.py` / `jq_compiler.py`：jq 解析与编译\n  - `jq_vm.py`：JQVM（在 Core VM 上扩展）\n  - `jq_cli.py`：命令行入口（`pyjq`）\n\n- Lua 层（`haifa_lua/`）\n  - 前端：`lexer.py`、`parser.py`、`compiler.py`\n  - 运行时：`runtime.py`、`environment.py`、`stdlib.py`、`coroutines.py`\n  - 命令行：`cli.py`（`pylua`）\n\n## 4. 代码层次与常用入口\n\n- 指令分层\n  - Core Opcode：算术/逻辑/跳转/表/闭包/多返回等通用操作（`compiler/bytecode.py`）\n  - JQ Opcode：对象访问、迭代、聚合、字符串等（`compiler/jq_*`）\n  - 执行单元：`BytecodeVM` 仅实现 Core；`JQVM` 在其上扩展 JQ 指令\n\n- CLI 与示例\n  - CLI：`pylua` 与 `pyjq`\n  - 示例：`examples/*.lua`；基准：`benchmark/scripts/*.lua`\n  - 可视化：`--visualize [gui|curses]`（Lua 与 jq 均支持）\n\n## 5. 相关文档索引\n\n- 语言/运行时与计划\n  - `docs/lua_sprint.md`：Lua 解释器里程碑与计划（含协程 API 完备）\n  - `docs/lua_guide.md`：Lua 实践指南与示例\n  - `docs/jq_design.md`：jq 设计与指令分层\n\n- 可视化与调试\n  - `knowledge/07-debugger-architecture.md`：调试器架构与原则\n  - `knowledge/09-coroutine-visualizer-and-error-plan.md`：协程事件与错误展示计划\n\n- 性能与基准\n  - `docs/performance_benchmark.md`：Lua 解释器性能基准方案\n  - `benchmark/`：脚本、运行器与报告示例\n\n---\n\n附注\n- GUI 中文显示：若 pygame GUI 无法显示中文，可在 `compiler/vm_visualizer.py` 中改用指定字体文件，例如：\n  ```python\n  # 替换 SysFont 为系统字体文件（示例）\n  self.font = pygame.font.Font('/System/Library/Fonts/PingFang.ttc', FONT_SIZE)\n  ```\n  也可以将字体文件放入项目并用相对路径加载。\n- 在非图形环境下，使用 `--visualize curses` 进入终端可视化模式。\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faarenwang%2Fhaifa-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faarenwang%2Fhaifa-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faarenwang%2Fhaifa-python/lists"}