Grammars-v4：ANTLR v4 开源文法集合的项目结构与测试指南

编程语言编译器开发工具【免费下载链接】grammars-v4Grammars written for ANTLR v4; expectation that the grammars are free of actions.项目地址https://gitcode.com/gh_mirrors/gr/grammars-v4点击查看免费下载本文是 grammars-v4 开源仓库的完整技术指南。grammars-v4 是专为 ANTLR v4 编写的正式文法formal grammar集合覆盖 Java、C/C、C#、Python、SQL 系列、JSON、XML 等数百种语言与文件格式其核心设计期望是所有文法不含 actionsfree of actions从而保持文法与目标语言无关。读完本文你将掌握该仓库的目录组织与命名约定、单个文法的标准文件结构desc.xml / pom.xml / .g4 / examples、基于 Trash Toolkit 与 Maven 两套测试流程的完整用法以及如何阅读官方性能表来评估文法吞吐量与歧义状况。项目定位为 ANTLR v4 服务的多语言文法生态仓库根目录的 README.md 用一句话定义了项目本质这是一个为 ANTLR v4 编写的正式文法集合。它不是一个单一语言的解析器项目而是一个文法仓库目标是让使用者能基于其中任意一条文法用 ANTLR v4 工具链为任意支持的目标语言target生成可用的词法/语法分析器。根据 House_Rules.md 的历史章节该仓库创建于 2012 年 9 月早期生态中缺少一个可验证可用性的文法库为此仓库引入了antlr4test-maven-plugin与 CI 来保证两条底线每条文法都能被当前版本的 ANTLR 工具解析语法本身合法生成的 lexer-parser 能用当前版本 ANTLR 成功解析至少一个示例输入。截至 House Rules 文档写作时仓库已收录略少于 300 个左右的源语言文法原文表述为 a little less than 300-ish source language grammars见 House_Rules.md并支持包括 C、Java、C#、Python、JS、Swift 等在内的多个 ANTLR 目标。README 顶部还展示了三条持续集成流水线状态每次 PR 合入构建Last PR merge build、每周 .jar 构建Weekly JAR与每周 dev 构建Weekly Dev用以持续验证全库文法在当前 ANTLR 版本下的可生成性与可测试性。目录组织根目录名即语言名README 明确规定了仓库的目录约定根目录名是被文法解析的语言或文件格式的全小写名称例如 java、cpp、csharp、c 等。这意味着你可以通过目录名直接判断该目录对应哪种语言。实际浏览仓库可以看到两种典型形态单一文法目录如 json、xml、csv目录内直接存放.g4文法文件多版本/子目录形态当一个语言有多个文法实现或版本时采用子目录隔离例如 csharp/v6、csharp/v7、csharp/v8-specjava/java、java/java8、java/java9、java/java20以及 sql 下的 mysql、postgresql、tsql、sqlite 等数十个方言目录。这种目录名 语言/格式名的约定配合性能表见下文中的 Grammar 列让使用者可以快速建立目录 ↔ 文法 ↔ 性能数据的对应关系。单个文法的标准结构以 json 为例每个可测试文法目录都遵循统一的四件套结构以 json 目录为例json/ ├── examples/ # 示例输入文件测试基线 │ ├── example1.json │ └── numbers.json ├── JSON.g4 # ANTLR v4 文法文件 ├── desc.xml # Trash Toolkit 生成驱动时读取的配置 ├── pom.xml # Maven 测试antlr4test-maven-plugin配置 └── readme.md # 文法说明desc.xml声明支持的目标语言json/desc.xml 是 Trash Toolkit 的trgen工具读取的配置其 XML 结构由 _scripts/desc.xsd 约束核心元素为targets?xml version1.0 encodingUTF-8 ? desc xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:noNamespaceSchemaLocation../_scripts/desc.xsd targetsCSharp;Cpp;Dart;Go;Java;JavaScript;PHP;Python3;TypeScript;Antlr4ng/targets /desctargets以分号分隔声明该文法支持哪些 ANTLR 代码生成目标。据此json 文法可面向 C#、C、Dart、Go、Java、JavaScript、PHP、Python3、TypeScript 与 Antlr4ng 生成解析器。测试脚本 _scripts/test.sh 会读取该字段决定对哪些grammar, target组合执行测试并支持all全部与-target排除修饰符。pom.xmlMaven 侧的生成与测试配置json/pom.xml 展示了标准配置它依赖根 pom.xml 定义的统一版本属性——根 pom 中声明了antlr.version4.13.2与antlr4test-maven-plugin.version1.22整个仓库的文法统一使用同一套 ANTLR 工具与测试插件版本避免版本漂移。json 的 pom 中两个关键插件antlr4-maven-plugin配置sourceDirectory指向文法目录、includeJSON.g4/include指定文法文件并开启visitor与listener代码生成antlr4test-maven-plugincom.khubla.antlr配置grammarNameJSON、entryPointjson入口规则、exampleFilesexamples/测试时用示例文件驱动生成的解析器并比对结果。文法精读JSON.g4json/JSON.g4 取自 Terence Parr 的《The Definitive ANTLR 4 Reference》并声明派生自 json.org 规范是无 actions文法的典型样本。其解析器规则完整覆盖 JSON 语法json : value EOF ; obj : { pair (, pair)* } | { } ; pair : STRING : value ; arr : [ value (, value)* ] | [ ] ; value : STRING | NUMBER | obj | arr | true | false | null ;值得注意的工程细节可作为编写同类文法时的参考入口规则json : value EOF显式锚定输入末尾保证整段输入被完整消费这也是entryPoint配置与之对应的原因空对象/空数组通过{ }、[ ]单独一条备选分支处理词法层面STRING由ESC与SAFECODEPOINT两个 fragment 组成SAFECODEPOINT使用~ [\\\u0000-\u001F]排除引号、反斜杠与控制字符NUMBER的整数部分通过 fragmentINT禁止前导零0 | [1-9] [0-9]*而指数部分EXP则允许前导零如1e01与 JSON 规范一致空白处理WS : [ \t\n\r] - skip;直接跳过不进入语法规则保持解析器规则简洁。整条文法不含任何嵌入动作action完全符合仓库grammars are free of actions的设计期望。获取仓库并生成解析器Trash Toolkit 流程仓库为文法测试维护了一套基于 .NET 的Trash Toolkit工具链trgen、trwdog、trperf、trparse、trtree、trquery等。根据 CLAUDE.md 的记录完整流程如下。1. 克隆与工具还原git clone https://gitcode.com/gh_mirrors/gr/grammars-v4 cd grammars-v4 dotnet tool restore # 一次性还原 Trash Toolkit 全部 tr* 工具 clonerootpwd2. 生成驱动代码进入目标文法目录例如 csharp/v8-spec使用trgen生成驱动工程cd csharp/v8-spec dotnet trash gen -t CSharptrgen会读取当前目录的desc.xml、发现所有.g4文件、解析其依赖关系并把完整的驱动应用写入Generated-CSharp/。使用上有三条硬性规则源自 CLAUDE.md只使用-t target选项不要附加其他选项必须在包含desc.xml的文法目录内运行dotnet trash gen不能在仓库根目录运行生成 Java 驱动时使用dotnet trash gen -t Java产物为Generated-Java/。3. 构建与测试cd Generated-CSharp bash build.sh # 先运行 antlr4 从 .g4 重新生成 lexer/parser 源码再编译驱动 bash test.sh # 解析 desc.xml 中列出的所有示例文件与基线比对 bash run.sh *.txt # 解析单个文件test.sh会把解析结果写成.tree与.errors文件并与提交的基线做 diff成功输出Test succeeded.失败则输出Test failed.及差异详情。4. 歧义检测生成驱动的二进制支持 ANTLR 剖析模式用于定位文法歧义./bin/Debug/net10.0/Test.exe --ambig file # 报告所有 ATN 决策处的真实歧义 ./bin/Debug/net10.0/Test.exe --ambig195,42 file # 只关注指定决策 ./bin/Debug/net10.0/Test.exe --ambig --limit4 file dotnet trash parse --ambig file | dotnet trash tree每次歧义会打印所有不同的解析树每行以ddecision.aalt前缀标识例如d195.a1。关于如何消除歧义GLOSSARY.md 给出了关键原则一个**分歧点divergence point**是指定歧义输入下、多个解析树从根到该节点祖先完全相同、仅该节点子树不同的节点要消除该歧义该决策在全部报告解析树中出现过的每个备选分支都必须加上语义谓词且这些谓词必须两两互斥——只要遗漏任何一个无条件可行的备选歧义就无法真正消除。Maven 测试路径与常见问题仓库同时保留 Java/Maven 测试体系antlr4test-maven-plugin同样在 CLAUDE.md 中有完整记录cd grammar-dir # 进入包含 pom.xml 的文法目录 mvn clean test # 测试单个文法 cd repo-root mvn clean test # 测试全部文法 _scripts/maven.sh before-git-sha after-git-sha # 只测试 PR 中变更的文法仓库级测试驱动脚本是 _scripts/test.sh它支持丰富的过滤选项脚本内-h帮助文档可查-g dirs指定搜索文法的目录列表默认从当前目录递归查找含desc.xml的目录-f filter过滤测试类型all全部、diff仅测试 git diff 涉及的文法、agnostic仅测试含 actions 的文法——其中agnostic模式正是通过dotnet trash parse -t ANTLRv4 *.g4 | dotnet trash xpath //(actionBlock | argActionBlock)统计文法中的 action 块数量-t targets指定测试目标默认覆盖 Antlr4ng、CSharp、Cpp、Dart、Go、Java、JavaScript、OphiRust、Python3、Rust、TypeScript--antlr-version ver指定 ANTLR 工具与运行时版本如4.13.1或传dev从 ANTLR4 dev 分支构建省略时使用trgen默认版本。针对 Maven 测试的两个高频失败CLAUDE.md 记录了原因与对策no errors found, but errors file existsTrash Toolkit 测试运行器遗留的零字节.errors文件会被 Maven 插件当作期望解析失败的基线导致解析成功反而报错。解决方法是只删除测试目录下的零字节.errors文件可通过 pom.xml 的exampleFiles确认目录默认是examples/find examples/ -name *.errors -size 0 -deleteexamples/ 中出现意外扩展名pom.xml 若未配置testFileExtension插件会尝试解析 examples 目录中的每一个文件混入的文档或其他格式输入会导致失败应显式声明测试文件扩展名。性能表如何量化文法质量README 的 Performance 章节指向仓库的 performance.html可按表头列排序对应的原始数据与列定义在 performance.md 中。该表记录了每条文法在 N3 次运行均值 ± 标准误下的关键指标列名含义PT纯解析时间所有输入文件解析耗时之和OT开销时间TT − PT含文件 I/O、lexer/parser 构造与解析后处理TT总耗时整次运行的墙钟时间TPS每秒 token 数总 token 数 / PT纯解析吞吐量Post-warmup TPS仅取第 2…N 个文件的 TPS排除首个热身运行只有一个文件时为n.a.Post-warmup Speed UpPost-warmup TPS 与首个文件 TPS 之比反映 JIT/运行时预热收益Ambiguities测试期间检测到的歧义数量Actions文法中嵌入的 action 数量表中的Actions列直接服务于仓库文法不含 actions的定位——例如多数文法的 Actions 为 0而部分历史移植文法如 ada2012 的 68、mysql/Oracle 的 287仍有遗留动作可作为进一步去 action 化的候选。Ambiguities列则与上文 GLOSSARY 的分歧点修复方法配套使用表中非零的歧义计数正是值得深入排查并施加语义谓词的决策点清单。通过 TPS 与 Post-warmup Speed Up 两列还能快速对比不同文法在相同测试负载下的吞吐量与 JIT 预热收益。贡献规范与社区约定README 的 Code of Conduct 章节指向 House_Rules.md其中规定了仓库的协作基调对想要提交新文法或修复 bug 的开发者尤为重要欢迎一切贡献从拼写修正到全新文法均受欢迎社区对新手与专家一视同仁仓库所有者对全部提交拥有最终审批权CI 是硬门槛所有变更必须通过 CI 才能合入新文法强烈建议附带 examples新增特性或修复 bug 时也鼓励附带覆盖该特性/修复的示例命名传统符号冲突一般通过在标识符后追加下划线解决例如id冲突时改为id_代码风格文法格式化风格默认遵循 Antlr4Formatter 工具的输出格式json 的 JSON.g4 头部即可看到$antlr-format指令声明的对齐、列宽、空行等格式化参数致谢传统仓库保留对每个贡献者在 PR 合入时致谢的传统许可说明仓库没有单一统一许可证部分文法由 grammars-v3 前向移植而来保留原作者信息多数文法的许可信息写在.g4文件头部使用时请逐条核对。总结与进一步探索路径grammars-v4 是一个以目录即语言、以 CI 兜底质量的 ANTLR v4 文法生态仓库目录命名约定让你能快速定位目标语言文法desc.xmlpom.xmlexamples/的标准结构让每条文法都能被 Trash Toolkit 与 Maven 两套流水线自动生成、构建与验证性能表则把吞吐量、歧义数与 action 数透明化为选型与改进提供量化依据。建议的深入学习路径从 json/JSON.g4 这类简洁文法入手理解无 actions文法的写法阅读 _scripts/test.sh 与 CLAUDE.md 掌握全量/增量/agnostic 三类测试模式对照 performance.md 的列定义解读 performance.html 中的排序表在动手贡献前通读 House_Rules.md 的贡献与命名约定。赞分享编程语言编译器开发工具【免费下载链接】grammars-v4Grammars written for ANTLR v4; expectation that the grammars are free of actions.项目地址https://gitcode.com/gh_mirrors/gr/grammars-v4点击查看免费下载相关推荐ANTLR v4 语法文件集合教程ANTLR v4 语法文件集合教程 项目介绍 ANTLR v4 Grammars 是一个庞大的开源项目它汇集了用于 ANTLR v4 的一系列形式化语法规则文编程语言编译器开发工具KOReader终极指南多设备电子书阅读器的完整安装与配置教程KOReader终极指南多设备电子书阅读器的完整安装与配置教程 你是否经常在不同设备上阅读电子书却苦于阅读进度无法同步或者厌倦了原生阅读器的功能限制渴望桌面应用跨平台嵌入式告别语法解析烦恼antlr/grammars-v4与IDE集成完全指南告别语法解析烦恼antlr/grammars v4与IDE集成完全指南 你是否还在为手动编写语法解析器而头疼是否在IDE中面对复杂语法文件时感到无所适从本编程语言编译器开发工具上一篇最全面的MangoHud配置教程从入门到自定义监控面板下一篇Sketch识别神器ml-projects中100类手绘图形识别模型的使用技巧创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考