{"id":31537681,"url":"https://github.com/aarenwang/haifa-python","last_synced_at":"2026-05-14T20:31:40.045Z","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":"2026-05-14T20:31:40.038Z","avatar_url":"https://github.com/AarenWang.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Haifa Python\n\nEnglish | [简体中文](README_CN.md)\n\nHaifa Python is a teaching-oriented compiler and virtual machine playground built in Python. It uses one core bytecode VM to support two learning tracks:\n\n- a jq-style JSON query/runtime tool (`pyjq`)\n- a Lua subset with runtime, coroutines, and tracing (`pylua`)\n\nThe project is designed for people who want to study how source code moves through the full execution pipeline: lexer, parser, AST, semantic analysis, bytecode generation, VM execution, and debugging/visualization.\n\n## Purpose\n\nHaifa Python exists to make language implementation easier to inspect, modify, and teach. Instead of treating compilers and interpreters as black boxes, it exposes each layer as readable Python modules with examples, tests, and visualizers.\n\nThis makes the repository useful for:\n\n- compiler and interpreter courses\n- programming languages self-study\n- experiments with bytecode design and runtime behavior\n- demonstrations of coroutines, closures, tables, and multi-return semantics\n- jq-style data transformation on top of a reusable VM core\n\n## Computer Science Topics Covered\n\nThe codebase maps directly to core CS and PL concepts:\n\n- lexical analysis and parsing\n- abstract syntax trees and source mapping\n- semantic analysis for scopes, closures, and upvalues\n- bytecode instruction design\n- stack/register-style VM execution tradeoffs\n- call stacks, environments, and runtime error reporting\n- coroutines and event-driven execution tracing\n- CLI tooling, debugging views, and execution visualization\n\nIf you are teaching or learning compiler construction, language runtimes, or virtual machines, this repository is meant to be studied as much as it is meant to be run.\n\n## Project Layout\n\n- `compiler/`: core bytecode VM, jq frontend/runtime, instruction set, and visualizers\n- `haifa_lua/`: Lua lexer, parser, compiler, runtime, stdlib, coroutines, and CLI\n- `docs/`: user guides, sprint notes, and reference material\n- `knowledge/`: architecture and deep-dive notes\n- `examples/`: runnable Lua and coroutine examples\n- `benchmark/`: benchmark scripts, runner, and stored results\n\n## Quick Start\n\n### Requirements\n\n- Python 3.11+\n- Optional: `pygame` for the GUI visualizer\n\n### Install from source\n\n```bash\npython3 -m venv .venv\nsource .venv/bin/activate\npython3 -m pip install --upgrade pip setuptools wheel\npython3 -m pip install .\n```\n\nTo enable the GUI visualizer:\n\n```bash\npython3 -m pip install \".[gui]\"\n```\n\n### Run tests\n\n```bash\npytest\n```\n\n### Try the Lua runtime\n\nRun a script:\n\n```bash\npython3 -m haifa_lua.cli examples/hello.lua --print-output\n```\n\nEvaluate inline code:\n\n```bash\npython3 -m haifa_lua.cli -e 'x = 1; y = 2; return x + y' --print-output\n```\n\nStart the REPL:\n\n```bash\npython3 -m haifa_lua.cli --repl\n```\n\nTrace or visualize execution:\n\n```bash\npython3 -m haifa_lua.cli examples/coroutines.lua --trace coroutine\npython3 -m haifa_lua.cli examples/coroutines.lua --visualize curses\n```\n\n### Try the jq-style runtime\n\nQuery a JSON file:\n\n```bash\npython3 -m haifa_jq.jq_cli '.items[] | .name' --input compiler/sample.json\n```\n\nPipe JSON from stdin:\n\n```bash\ncat compiler/sample.json | python3 -m haifa_jq.jq_cli '.items[] | .price'\n```\n\nUse the terminal visualizer:\n\n```bash\npython3 -m haifa_jq.jq_cli '.items[] | .name' --input compiler/sample.json --visualize curses\n```\n\nAfter installation, the same tools are also available as:\n\n```bash\npylua --help\npyjq --help\n```\n\n## Learning Path\n\nFor a guided tour, a practical sequence is:\n\n1. Run a Lua example from `examples/`.\n2. Read `haifa_lua/lexer.py`, `haifa_lua/parser.py`, and `haifa_lua/compiler.py`.\n3. Follow execution into `compiler/bytecode.py` and `compiler/bytecode_vm.py`.\n4. Compare the Lua flow with the jq flow in `haifa_jq/jq_parser.py`, `haifa_jq/jq_compiler.py`, and `haifa_jq/jq_vm.py`.\n5. Open the visualizer or trace output to inspect runtime state changes.\n\n## Documentation\n\n- [`docs/lua_guide.md`](docs/lua_guide.md): practical guide to the Lua runtime\n- [`docs/guide.md`](docs/guide.md): jq CLI guide and examples\n- [`docs/reference.md`](docs/reference.md): command reference\n- [`docs/lua_sprint.md`](docs/lua_sprint.md): implementation milestones and roadmap\n- [`knowledge/03-bytecode-and-vm.md`](knowledge/03-bytecode-and-vm.md): bytecode/VM background\n- [`knowledge/06-lua-execution-pipeline.md`](knowledge/06-lua-execution-pipeline.md): end-to-end Lua execution pipeline\n\n## Notes\n\n- The GUI visualizer depends on `pygame`. In non-GUI environments, use `--visualize curses`.\n- The Lua implementation is intentionally a subset/runtime experiment, not a full Lua compatibility target.\n- The repository favors readability and inspectability over aggressive optimization.\n","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"}