编程语言编译器开发工具【免费下载链接】grammars-v4Grammars written for ANTLR v4; expectation that the grammars are free of actions.项目地址https://gitcode.com/gh_mirrors/gr/grammars-v4点击查看免费下载本篇技术指南系统讲解 ANTLR v4 语法仓库 grammars-v4 的 CI 测试体系从 _scripts/readme.md 定义的test.sh/test.ps1两个入口脚本到其底层依赖的 trgen 生成器与 _scripts/templates/ 模板目录再到驱动代码的生成、构建、解析测试全流程。读完本文你将掌握如何在 grammars-v4 中针对任意目标语言CSharp、Java、Cpp、Dart、Go、Python3 等快速生成测试驱动、跑通make make test流水线并能读懂、自定义模板与~/.trgen.rc/~/.trwdog.rc配置文件甚至为自己的语法贡献接入这套 CI 体系。一、为什么 grammars-v4 需要一套统一的测试脚本grammars-v4 是一个存放无 action 的 ANTLR v4 语法的仓库每个语法如 abb、abnf都自成目录目录内通常包含.g4文法文件、描述文法的pom.xml与desc.xml以及用于验证的examples/样例目录。仓库根目录还有聚合所有语法的 pom.xml并以 _scripts/desc.xsd 约束desc.xml的格式。由于同一个文法要能编译出面向多种语言运行时CSharp、Java、Cpp、Dart、Go、Python、JavaScript……的解析器逐一记忆每种语言的构建运行解析器命令显然不可行。因此仓库在 _scripts/ 目录下集中了两套测试脚本和一套模板体系把生成驱动 → 构建 → 用 examples 做解析测试的流程标准化。_scripts/readme.md正是这套体系的说明文档。二、两个入口脚本test.sh 与 test.ps1_scripts/readme.md定义了仓库 CI 测试的两个入口regtest.shBash 版文档描述它是一个可测试任意 target的 Bash 脚本。在实际仓库中对应的实现是 _scripts/test.sh。运行方式为先cd到仓库根目录或某个语法目录然后执行bash _scripts/test.sh target其中target可以是 Cpp、CSharp、Dart、Go、Java、PHP 或 Python3。test.ps1PowerShell 版功能与 Bash 版类似面向 Windows/跨平台 CI 场景实现在 _scripts/test.ps1。运行测试前需要准备的环境包括NET SDKtrgen 驱动生成器依赖它、可访问互联网用于还原 NuGet 包/工具链依赖、目标语言的工具链以及ANTLR4 工具的 jar 路径通过参数或配置文件指定详见第四节。两个脚本都借助trgen从语法目录的pom.xml中读取文法信息为某个目标语言生成解析器驱动程序。生成的代码里同时包含 makefile 和 PowerShell 脚本向用户提供统一的构建与解析运行接口——正如文档所说你无需记住如何为给定 target 构建和运行解析器。三、手工跑通一次测试trgen make 三步曲_scripts/readme.md给出了最直接的手工操作流程以 CSharp 目标、abnf 语法为例cd abnf trgen -t CSharp --template-sources-directory _scripts/templates/ --antlr-tool-path /tmp/antlr-4.9.3-complete.jar make make test三个命令各司其职trgen读取当前目录的pom.xml提取文法名、入口规则等信息把abbParser.g4/abbLexer.g4等源文件与模板合并在Generated-*目录中生成驱动代码make调用模板里的build.sh完成驱动程序的编译构建make test调用模板里的test.sh用语法目录examples/下的样例文件逐个执行解析测试并校验错误输出.errors与语法树.tree约定。这里特别值得注意--template-sources-directory参数文档明确指出它用于指定本仓库为驱动程序准备的模板所在位置。trgen 自带一套通用模板但通用模板与本仓库 CI 使用的模板可能存在差异所以测试本仓库语法时应显式传入_scripts/templates/。3.1 环境前提make 与 Bash用 makefile 构建和运行解析器要求运行环境提供make和BashUbuntu开箱即用Windows上需要使用MinGW64然后通过pacman install makemingw-w64-x86_64-make 包安装并手动创建一个指向make的符号链接文件——文档特别提示这个包不知为何没有定义普通的 make.exe。3.2 makefile 里到底发生了什么模板中的 makefile 是非常薄的壳真正的工作由同名 shell 脚本完成。以 Java/st.makefile 为例default: FORCE bash build.sh clean: FORCE bash clean.sh FORCE: ; test: FORCE bash test.sh即make等价于bash build.shmake test等价于bash test.shmake clean等价于bash clean.sh。每个目标语言的模板目录中都配套提供了st.build.sh、st.test.sh、st.clean.sh、st.run.sh、st.perf.sh等脚本见 _scripts/templates/ 下的 CSharp、Java、Python3 等子目录保证理想化接口在不同语言间一致。四、个性化配置~/.trgen.rc 与 ~/.trwdog.rc为了避免每次都在命令行重复传参文档建议在用户主目录创建两个 JSON 配置文件覆盖 trgen 与 trwdog 的默认值。~/.trgen.rc覆盖 trgen 的默认选项例如指定 ANTLR 工具 jar 的路径{ antlr_tool_path : c:/users/kenne/downloads/antlr-4.9.3-complete.jar }~/.trwdog.rc覆盖 trwdog 工具的默认超时。trwdog 默认给解析测试设置了 5 分钟超时在慢速机器上可能不够用可以通过该文件调大{ Timeout : 2 }文档特别说明配置文件中主目录的计算方式由 C# 运行时决定即Environment.GetFolderPath(Environment.SpecialFolder.UserProfile)。这意味着在 Linux 上对应$HOME在 Windows 上对应C:\Users\用户名两套平台的配置互不干扰。五、深入 test.sh命令行选项与执行流程仓库中实际的 Bash 测试脚本 _scripts/test.sh 比文档描述的功能更完整其-h帮助信息给出的用法如下test [-g ...] | [-s ...] | [-t ...]核心选项见脚本第 126-194 行选项含义取值/默认-g指定搜索文法的目录列表每个文法需同时具备pom.xml与desc.xml才会被测试不指定时默认从当前目录递归搜索-f测试过滤类型all全部默认/diff仅 git 有变更的文法/agnostic仅含 action 的文法-t要测试的目标语言CSharp、Cpp、Dart、Go、Java、JavaScript、Python3等不指定时默认测试全部目标-o测试排序方式grammars默认或按 target 排序-a指定 ANTLR4 jar 路径默认/tmp/antlr4-complete.jar--antlr-version指定 ANTLR4 工具与运行时版本如4.13.1或传dev从 ANTLR4 dev 分支克隆构建直接透传给 trgen省略时使用 trgen 默认版本脚本的完整流水线如下_scripts/test.sh根据-f计算待测文法集合all模式用find . -name desc.xml枚举全部语法目录diff模式用git diff --name-only找出变更文件所属的语法目录agnostic模式额外用dotnet trash parse -t ANTLRv4 *.g4解析文法再经 xpath 检查是否存在actionBlock/argActionBlock有 action 的文法才会被测试对文法 × 目标做笛卡尔积逐个执行用dotnet trash xml2 desc.xml读取每个文法的targets声明all表示全部目标、-Target表示排除某目标决定该文法是否跳过当前 target组装 trgen 参数-t target --template-sources-directory templates --antlr-tool-path jar必要时追加--antlr-version调用dotnet trash gen生成驱动进入生成的Generated-target-*目录先bash build.sh构建再bash test.sh解析测试逐条记录成功/失败结果并统计耗时任何一步失败都会把该文法/目标记入 failed 列表最终脚本以非零状态码退出。六、深入 test.ps1PowerShell 变体与 Git 差异测试_scripts/test.ps1 是 Bash 版的 Windows 对应实现参数略有不同param ( [string]$targetCSharp, # 目标语言默认 CSharp [string]$pc, # 上一个提交previous commit [string]$cc, # 当前提交current commit默认 HEAD [bool]$buildonly$false # 只构建不测试 )脚本内部按阶段组织定义了FailStage枚举Success/CodeGeneration/Compile/Test来精确定位失败环节并提供了多个可复用函数Get-GrammarSkip检查语法目录是否有desc.xml、是否在targets中排除了当前目标与 Bash 版逻辑一致Get-Grammars递归解析各层pom.xml的modules收集所有含 antlr 插件配置的语法目录Get-GitChangedDirectories/Get-ChangedGrammars基于git diff pc cc --name-only找出发生变更的语法目录自动排除_scripts、.github等目录Test-AllGrammars遍历待测文法逐个执行dotnet trash gen→./build.ps1→./test.ps1最后汇总失败列表并设置退出码。因此test.ps1既可以全量测试不传pc也可以做增量测试例如# 全量测试全部文法CSharp 目标 powershell -File _scripts/test.ps1 # 仅测试某两个提交之间发生变更的文法 powershell -File _scripts/test.ps1 -pc commit1 -cc commit2七、模板体系templates/ 的目录结构与维护规则7.1 按目标语言组织的目录标准_scripts/readme.md明确指出所有模板采用per-target directory按目标分目录标准模板目录中的文件会被实例化到生成的输出目录模板目录下的子目录以目标语言命名如 CSharp、Java、JavaScript 等trgen 只把指定目标对应子目录中的文件复制到生成目录。文档给出的默认模板结构为templates/ CSharp/ ErrorListener.cs Program.cs Test.csproj makefile Cpp/ Dart/ analysis_options.yaml cli.dart makefile pubspec.yaml Go/ Program.go makefile Java/ ErrorListener.java Program.java makefile JavaScript/ index.js makefile package.json Python3/ Program.py makefile files Arithmetic.g4对照当前仓库_scripts/templates/ 已扩展到更多目标除上述语言外还包含Antlr4cs、Antlr4ng、Cpp含 cmake 辅助文件、OphiRust、PHP、Rust、TypeScript等子目录每个目录都成套提供st.build.sh、st.test.sh、st.clean.sh、st.run.sh、st.perf.sh、st.test.ps1等文件注意模板文件统一带st.前缀。7.2 关键维护规则files 清单文件文档特别强调一条维护约定如果增删了 templates/ 下的任何文件必须重新生成files清单否则 trgen 不会把新增模板文件加入生成的代码cd templates/ find . -type f filesfiles文件就是 trgen 判断哪些模板文件参与生成的依据这是最容易踩的坑。7.3 模板本质StringTemplatetemplates/下所有文件本质上是 StringTemplate 里的from lexer_name import lexer_name;以及 CSharp/Test.csproj.st 中对if(name_space)、tool_grammar_files:{...}等模板指令的运用。八、trgen 模板属性参考表trgen 会构造并传给模板求值器一系列属性_scripts/readme.md给出了完整清单AttributeTypeDefaultadditional_sourcesliststring目标语言后缀的输入文件列表例如 Cpp 目标的所有 .cpp 文件antlr_tool_pathstringUbuntu:~/Downloads/antlr-4.9.1-complete.jarWin:Environment.GetFolderPath(Environment.SpecialFolder.UserProfile) /Downloads/antlr-4.9.1-complete.jarcap_start_symbolstring同start_symbol但首字母大写cli_bashboolUbuntu: trueWin: falsecli_cmdboolUbuntu: falseWin: truecmake_targetstringWin:-G MSYS MakefileUbuntu:exec_namestringUbuntu: TestWin: Test.exehas_name_spacebool仅当 pom.xml 指定了非空packageName时为 trueis_combined_grammarbool文法是否为合并combined文法lexer_grammar_namestring文法文件名或合并文法文件名本身lexer_namestringpom.xml 的grammarName Lexername_spacestringpom.xmlpackageName的值parser_namestringpom.xml 的grammarName Parserpath_sep_colonboolUbuntu: trueWin: falsepath_sep_semiboolUbuntu: falseWin: truestart_symbolstringpom.xmlentryPoint的值temp_dirstringWin:c:/tempUbuntu:/tmp用于 Cpp 目标tool_grammar_filesListstring计算所得文法文件相对于输出目录的路径列表tool_grammar_tuples{ GrammarFileName, GeneratedFileName, GrammarAutomName }由tool_grammar_files、parser_name、lexer_name计算例如[{ abbLexer.g4, abbLexer.cs, abbLexer }, ...]versionstringtrgen 的版本号对照仓库中 abb/desc.xml 与 abb/pom.xml 可以直观理解这些属性的来源desc.xml声明了antlr-version^4.10、targetsAntlr4ng;Cpp;CSharp;Dart;Go;Java;JavaScript;Python3;Rust;TypeScript和inputsexamples/**/*.syspom.xml则通过entryPointmodule_/entryPoint对应start_symbol、grammarNameabb/grammarName决定lexer_name/parser_name、packageName/packageName空值使has_name_space为 false以及exampleFilesexamples//exampleFiles驱动模板求值。九、驱动代码的生成合并过程_scripts/readme.md以 grammars-v4/abb/ 目录为例完整演示了trgen -t CSharp的合并过程工具先从pom.xml提取文法细节把语法源文件复制到Generated/再把对应模板子目录的文件复制进去最终得到Generated/ abbParser.g4 (来自源 abb/abbParser.g4) abbLexer.g4 (来自源 abb/abbLexer.g4) ErrorListener.cs (来自模板 templates/CSharp/ErrorListener.cs) makefile (来自模板 templates/CSharp/makefile) Program.cs (来自模板 templates/CSharp/Program.cs) Test.csproj (来自模板 templates/CSharp/Test.csproj)即仓库文法源码 目标语言模板在Generated/目录中合成为一个完整可构建的驱动工程。这也解释了Generated-*目录为何在每次测试前会被清理重建——_scripts/test.sh 开头的rm -rf $(find . -name Generated* -type d)正是为了保证测试从干净的生成状态开始。十、驱动程序的统一 CLI以 Java 与 Python3 模板为例生成后的驱动TestWindows 上为Test.exe提供了一套跨语言一致的命令行接口。以 Java/st.Test.java 为例支持的主要选项包括选项作用-d启用诊断错误监听器diagnostic error listener-profile打开性能剖析-tokens打印词法 token 流-tree打印解析树tee模式下写入file.tree-prefix输出行前缀-input str把命令行字符串当作输入解析-tee/-o dir把错误输出写入file.errors/ 输出到指定目录-encoding enc指定输入文件编码-x从标准输入逐行读取文件路径-q静默模式-trace开启解析器 trace解析结束后驱动会在 stderr 输出性能统计PT解析总时间、OT解析之外的总开销、TT总时间、TPS每秒 token 数以及多文件场景下的Post-warmup TPS和Post-warmup speed up预热后相对首个文件的加速比——这正是仓库根目录 performance.md 与 performance.html 中性能数据的来源管道。Python3/st.Test.py 的 CLI 与统计逻辑与之对应只是实现语言不同。错误处理约定也值得注意驱动通过自定义ErrorListener如 Java/st.Test.java 中的ErrorListener类收集词法/语法错误任一监听器报告错误即令进程以非零状态码退出同时模板的测试脚本会区分期望解析失败的样例——若examples/中存在file.errors文件则解析该文件失败才是预期结果参见 CSharp/Test.csproj.st 中内嵌的 bash/CMD 测试逻辑。仓库中有大量语法目录正是利用这一约定存放带.errors后缀的负向样例。十一、trgen 的安装与版本选择_scripts/readme.md对 trgen 版本给出明确建议这个工具我经常改动可能有回归务必在安装时指定版本目前0.13.2版本工作良好。模板实例化一节则给出了安装命令示例dotnet tool install -g trgen --version 0.20.19生成驱动程序的完整步骤为切换到目标文法目录例如cd abb执行trgen -t Java --template-sources-directory ../_scripts/templates/再次强调必须传--template-sources-directory ../_scripts/templates/指向本仓库模板若不传trgen 将使用工具自带的通用模板。-t可选目标包括 Cpp、CSharp、Dart、Go、Java、JavaScript、Python3仓库模板另支持 Antlr4ng、OphiRust、PHP、Rust、TypeScript 等见 _scripts/templates/。templates/目录中的files文件标明了参与生成的文件清单它是通过find . -type f files生成的。十二、从测试到性能与覆盖率模板中的配套脚本除构建/测试外各目标模板目录还配套了多个进阶脚本均为st.前缀st.perf.sh性能基准测试脚本与驱动内置的 TPS 统计配合使用st.test-cover.shCSharp 模板解析覆盖率测试st.test-ambiguity.shCSharp 模板歧义检测st.run.sh/st.run.ps1单文件快速运行驱动。仓库根目录的 _scripts/ 下还有perf-changed.sh、test-cover.sh、test-static-checks.sh、test-tps.sh、what-to-test.sh等脚本它们与模板脚本共同构成了 grammars-v4 从正确性到性能/覆盖率的完整质量保障矩阵。结语从脚本到模板的完整心智模型掌握 grammars-v4 的测试体系核心是理解三层结构入口层_scripts/test.sh 与 _scripts/test.ps1负责按需筛选文法与目标并调度生成层trgen _scripts/templates/负责从pom.xml提取元数据、实例化 StringTemplate 模板、产出跨语言统一的驱动工程执行层build.sh/test.sh/Test驱动负责构建、解析 examples 并校验.errors/.tree约定。无论你想为本仓库新增一个目标语言、调试某个语法的 CI 失败还是给自己的 ANTLR 项目搭建类似的测试流水线都可以从这套现成的脚本与模板出发辅以~/.trgen.rc、~/.trwdog.rc做环境定制快速落地一套可复用的跨语言语法测试方案。赞分享编程语言编译器开发工具【免费下载链接】grammars-v4Grammars written for ANTLR v4; expectation that the grammars are free of actions.项目地址https://gitcode.com/gh_mirrors/gr/grammars-v4点击查看免费下载相关推荐Elasticsearch Rust Client API全解析从基础操作到高级查询的实战指南Elasticsearch Rust Client API全解析从基础操作到高级查询的实战指南 Elasticsearch Rust Client 是 Ela后端开发工具2025全新ANTLR/grammars-v4解析指南300语言语法一键集成2025全新ANTLR/grammars v4解析指南300语言语法一键集成 GitHub加速计划下的gr/grammars v4项目是一个为ANTLR v编程语言编译器开发工具grammars-v4 中 ANTLR4 C 测试程序模板MSYS2 环境下的 CMake 构建与运行指南grammars v4 中 ANTLR4 C 测试程序模板MSYS2 环境下的 CMake 构建与运行指南 本篇技术指南以 grammars v4 仓库中编程语言编译器开发工具上一篇NumPy 1.16.3 发布说明全解析pickle 安全加固、随机数精度修复与数组接口偏移量修正下一篇FSCalendar 使用教程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考