# ParseEngine 解析器生成器

**Repository Path**: rabbitc999/ParseEngine

## Basic Information

- **Project Name**: ParseEngine 解析器生成器
- **Description**: ParseEngine 是一个 Yacc 风格的解析器生成器：输入一份 .gram 文法，输出可直接编译的 C99 / C++17 / C# / Rust 解析器工程，或一份免编译的 Python 产物。它覆盖 LL / LR / GLR 三大类共 12 种生成模式，支持 5 种目标语言，并额外提供「只要文法与分析报告、不要代码」的导出档。
- **Primary Language**: C++
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-09-10
- **Last Updated**: 2026-10-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ParseEngine · 解析器生成器

<img src="image/gram-editor-256.png" alt="ParseEngine 解析器生成器图标" width="120" align="right" />

ParseEngine 从一份 `.gram` 文法生成词法器、解析器和可构建的工程，并附上分析报告。它适合编写语言前端、配置格式与教学示例；仓库中的 Magic-C 编译器也使用它生成语法前端。

![ParseEngine 解析器生成器总览](image/ParseEngine-overview.png)

[查看可缩放的总览图](image/ParseEngine-overview.svg) · [生成器完整手册](source/README.md) · [文档导航](source/doc/README.md)

## 快速开始

```sh
make -C source
./build/bin/ParseEngine --grammar-file example/calc.gram --mode ielr --lang cpp17 --out-dir tmp/calc-parser
make -C tmp/calc-parser
```

Windows 上可执行文件为 `build/bin/ParseEngine.exe`。默认目标语言是 C++17，默认分析模式是 IELR(1)；命令行的 `--lang`、`--mode` 可覆盖文法中的 `%lang`、`%mode`。生成目录中有源码、构建文件和 `RESULT.md` 分析报告。命令行选项与 `.gram` 写法见[使用手册](source/doc/09-grammar-usage.md)。

| 输出 | 支持范围 |
| --- | --- |
| C99 | 13 种模式 |
| C++17、Python、C#、Rust、Go | 各 16 种模式 |
| Java、JavaScript/TypeScript | DD、Earley、CYK |
| `--lang gram` | 导出原文法与分析报告，覆盖全部 16 种模式 |

十六种模式包括 LL、LR、GLR、Earley、CYK、递归下降 DD 和仅生成词法器的 `lex`。各模式的准确支持范围、限制和 C++17 / Rust 增量 API 以[支持矩阵](source/doc/12-language-mode-support.md)为准。

生成器的入口在 [`source/`](source/)，产物模板在 [`source/templates/`](source/templates/)，示例文法在 [`example/`](example/)。语法编辑可使用 [VS Code 插件](vscode/README.md)或[桌面编辑器](editor/README.md)；实现结构见[架构文档](source/doc/01-architecture.md)。

## 仓库中的三个项目

| 项目 | 作用 | 独立入口 |
| --- | --- | --- |
| **ParseEngine** | 从 `.gram` 生成八种目标语言的解析器，另可导出文法与分析报告 | [`source/`](source/README.md) |
| **Magic-C（MC 语言）** | 由 ParseEngine 生成前端，编译到 StackVM；提供标准库、宿主胶水与 C ABI | [`magic-c/`](magic-c/README.md) |
| **Hydra86** | 独立的 8086 风格汇编器与多核虚拟机 | [`Hydra86/`](Hydra86/README.md) |

### Magic-C

Magic-C 是仓库根目录的独立语言工程。其编译器由 [`magic_c.gram`](magic-c/magic_c.gram) 生成；[标准库](magic-c/lang.mc)、[`mc-emit`](magic-c/mc-emit/README.md) 和 [`mc-generator`](magic-c/mc-generator/README.md) 随语言一起维护。胶水通过 C++ 注册宿主能力，C ABI 则让 MC 调用外部动态库；[文法冻结说明](LANGUAGE_SPEC.md)记录源码语法基线，语法、示例和边界说明见[语言手册](magic-c/README.md)与[专题文档](magic-c/doc/README.md)。

![Magic-C 编译、运行与导出总览](image/Magic-C-overview.png)

### Hydra86

Hydra86 可独立汇编、执行、反汇编和调试；[`library/transfer`](library/transfer/README.md) 可将四元式降为 Hydra86 汇编。具体指令与运行方式见[项目手册](Hydra86/README.md)。

![Hydra86 总览](image/Hydra86-overview.png)

## 构建与文档

```sh
sh build.sh                  # 三个项目、库与示例；不运行测试
sh build.sh --list           # 只检查环境并列出构建步骤
make -C source               # 只构建 ParseEngine
make -C magic-c              # 只构建 Magic-C（首次或改文法后先运行 sh magic-c/gen.sh）
make -C Hydra86              # 只构建 Hydra86
```

Windows PowerShell 使用 `./build.ps1` 和 `./build.ps1 -List`；原有的 `build-all.sh` / `build-all.ps1` 入口继续可用。构建脚本记录每一步的输出到 `tmp/build-all/logs/`。

[仓库文档总览](doc/01-overview.md)汇总所有文档。两篇项目故事是[满级文法与一次大扫除](doc/02-gram-legend.md)和[方块世界里的 MC 语言](doc/03-magic-c-story.md)。协作和生成物维护规则见 [`AGENTS.md`](AGENTS.md)；许可证见 [`LICENSE`](LICENSE)。