编程语言编译器语言运行时标准库开发工具【免费下载链接】sdkThe Dart SDK, including the VM, JS and Wasm compilers, analysis, core libraries, and more.项目地址https://gitcode.com/gh_mirrors/sdk1/sdk点击查看免费下载本篇技术指南以 Dart SDK 中的规范解析器Dart Specification Parser为核心讲解其设计动机、基于 ANTLR 的Dart.g语法文件构建原理以及它为多测试multi-test工作流引入的syntax error新期望结果。读完本文你将掌握规范解析器在 SDK 中的构建方式、如何用tools/spec_parse.py解析任意 Dart 源文件以及测试框架tools/test.py中-c spec_parser配置的底层实现链路。什么是 Dart 规范解析器Dart 规范解析器是一个建立在 ANTLR 语法文件 Dart.g 之上的可用解析器。这份Dart.g文件是 Dart 语言语法的机械化mechanized描述它由 ANTLR 工具转换为可工作的解析器代码并辅以若干辅助文件协同运行核心入口包括 spec_parse.py 与 tools/spec_parser 目录。从源码目录看tools/spec_parser下包含的关键构件有Dart.gANTLR 语法文件本体当前约 2400 行是解析器的“规范源头”Dart.g4位于dart_spec_parser子目录的 ANTLR4 格式语法Makefile生成词法/语法分析器并编译SpecParser.class的构建脚本SpecParserRunner.java一个从标准输入逐行读取待解析文件名的 Java 辅助入口spec_parse.dartDart 版调用前端通过Process.run启动 JVM 中的SpecParser。Dart.g头部维护着一份详细的版本变更日志截至当前仓库已迭代到 v0.60记录着语法随语言演进的过程例如 v0.57 引入 augmentation 相关更新、v0.44 支持 null-aware elements、v0.35 将命名可选参数语法收紧为必须使用、v0.30 增加sealed/final/base/interface类修饰符与mixin class、v0.20 允许空记录()等。这份日志本身就是追踪 Dart 语法演化历史的重要线索。动机为什么要有规范解析器文档阐述了两个核心动机第一用真实代码验证语法规范。规范解析器可以直接解析现存的 Dart 源码从而验证Dart.g对语法的描述是否一致、可解析并且与语言实际实现和使用方式精确对应。换句话说它是连接“纸面语法”与“真实语言”的校验器——任何写进Dart.g的规则都必须能解析得动真实世界中的 Dart 代码。第二为语言规范维护提供可信依据。由于Dart.g是机械化的、精确的语法描述它可以作为维护语言规范中语法规则时的重要信息来源。需要强调的是语言规范中的语法规则永远不会是Dart.g的逐字拷贝——Dart.g是 ANTLR 规范天然包含大量 ANTLR 特有的、或属于偶然性的细节。但Dart.g仍然是一个足够详细、可信赖的参考源对语言规范语法规则的维护非常有帮助。语言规范规则应比 Dart.g 更抽象Dart.g与语言规范中的语法规则之间存在刻意保留的“抽象度差”语言规范的语法规则应当比Dart.g更抽象甚至允许存在一定歧义只要这种歧义能换来显著更简单、更可读的规则。其合理性在于语言规范中的语法规则主要供人脑使用读者在思考“如何用语言表达某个想法”时会在脑海中构造表达式、声明等构件——即使规则有歧义人脑推导代码片段也完全没问题。相反语法歧义必须被消除才能支撑非异常情况下的实际解析工作。因此凡是寻求 Dart 解析实用方案的人都可以把Dart.g当作“如何消除歧义”的权威答案来源。这种“规范抽象、实现精确”的双轨设计是 Dart 语言规范维护中一个值得借鉴的思路。测试工作流multi-test 与新增的 syntax error 期望回顾 multi-test 机制Dart 的测试体系支持multi-tests即一个测试库文件中某些行会按照给定标签label被删除或保留。例如文档中的示例main() { print(none); print(01); //# 01: ok print(02); //# 02: ok print(03 new Map()); //# 03: compile-time error }在 subtest 01 中打印 none 和 01在 subtest 02 中打印 none 和 02在 subtest 03Dart 2 及强模式中报告编译期错误从而每次只启用一个 subtest而在所有 subtest 都未启用的一次单独运行中即所有 subtest 专属行都被删除只打印 none。multi-test 的源码实现在 multitest.dart其中_multitestOutcomes定义了一组合法期望结果集合syntax error正是其中之一final _multitestOutcomes { ok, syntax error, compile-time error, runtime error, static type warning, // Used by some analyzer tests. };处理 multi-test 时测试框架会按标签把每一段拆分生成独立的_key.dart测试文件并通过hasSyntaxError/hasCompileError等标志记录各 subtest 的期望var hasSyntaxError outcome.contains(syntax error); var hasCompileError hasSyntaxError || outcome.contains(compile-time error);为什么需要 syntax error 这一新结果规范解析器加入工具集之后测试需要一种新的期望结果——syntax errormain() { print(nothing because this fails to parse!; //# 01: syntax error }关键区别在于除规范解析器之外的任何工具都会把syntax error视为“该 subtest 的期望结果是编译期错误”——也就是说对它们而言写成//# 01: compile-time error效果相同。但规范解析器不做任何静态分析只做语法检查因此它能够把语法错误与其他编译期错误区分开。由此带来的判定规则是凡是期望为compile-time error或任何不是syntax error的变体的 subtest规范解析器一律视为“期望无错误”于是它既能发现意外的语法错误规范解析器报错但期望不是syntax error也能发现意外缺失的语法错误规范解析器成功解析但 subtest 期望是syntax error。因此在编写和维护 multi-test 时应当遵循语法错误就标记为syntax error其他编译期错误标记为compile-time error或checked mode compile-time error等其他合适的变体。为什么区分语法错误很有价值文档特别强调了一个隐蔽的测试陷阱如果开发者无意中写入了语法错误却把期望标成了compile-time error测试“看似”通过但它实际上从未测试到原本想测试的类型错误等现象——因为静态分析早在解析阶段就失败了。这种错误可能伪装成成功测试持续数月所有人都以为测试工作正常。文档作者提到在做这项工作时就修复了若干此类问题。截至文档写作时间2017 年 11 月作者建议采用“尽力而为”best effort的做法把那些本意就是语法错误的 subtest 标记为syntax error并指出在规范解析器进入主瀑布 buildbot 之前这些标记会按需调整当时甚至可能根本不会上线。各工具对错误检测阶段的自由分配还有一个值得注意的设计原则每个 Dart 工具规范解析器除外都可以自由地在解析器与静态分析的其他部分之间重新分配错误检测。也就是说某些在Dart.g看来是语法错误的问题某工具可能在后续静态分析阶段才检出某些在Dart.g看来不是语法错误的问题某工具的解析器却会拒绝。这不会造成冲突因为除规范解析器外所有工具都应继续把所有编译期错误统一报告为 compile-time error无论它是在解析器还是静态分析其他部分被检出的测试框架test.py只要每个工具在期望为syntax error、compile-time error或其变体的 subtest 上报告了 compile-time error就判定测试运行成功。特别地这些工具不应该尝试单独检出并报告语法错误应像过去一样视作编译期错误因此它们把期望的syntax error报告为非语法的编译期错误或反之都不算 bug。测试框架中的源码级实现规范解析器作为编译器配置接入测试框架的实现位于 compiler_configuration.dart 中的SpecParserCompilerConfiguration类约第 1666 行起/// Configuration for spec_parser. class SpecParserCompilerConfiguration extends CompilerConfiguration { SpecParserCompilerConfiguration(super.configuration) : super._subclass(); override String computeCompilerPath() tools/spec_parse.py; override CommandArtifact computeCompilationArtifact(...) { // Since this is not a real compilation, no artifacts are produced. return CommandArtifact( [ SpecParseCommand( computeCompilerPath(), arguments, environmentOverrides, ), ], arguments.singleWhere((argument) argument.endsWith(.dart)), application/vnd.dart, ); } override ListString computeRuntimeArguments(...) []; }注意其中的关键设计这不是一次真正的编译不会产生任何产物——它只是把待解析的.dart文件路径交给SpecParseCommand。执行类 SpecParseCommand约第 837 行起在测试框架中注册名为spec_parser的命令。结果判定逻辑在 SpecParseCommandOutput约第 813 行起bool get hasSyntaxError exitCode parseFailExitCode; override Expectation result(TestCase testCase) { if (hasCrashed) return Expectation.crash; if (hasTimedOut) return Expectation.timeout; if (hasNonUtf8) return Expectation.nonUtf8Error; if (truncatedOutput) return Expectation.truncatedOutput; if (testCase.testFile.isStaticErrorTest) { return _validateExpectedErrors(testCase); } if (hasSyntaxError || exitCode ! 0) return Expectation.syntaxError; return Expectation.pass; }这里的parseFailExitCode定义在 process_queue.dart 中值为245——规范解析器解析失败时以该退出码结束进程测试框架据此判定syntaxError期望。源码注释还给出了 ANTLR 诊断输出的真实样例Syntax error in foo.dart: line 1:14 no viable alternative at input (} Parsing failed与此同时TestFile 中保存了hasSyntaxError、hasCompileError等布尔字段用于把 subtest 的期望属性传递给后续的测试执行与结果比对。使用指南构建与运行规范解析器的使用说明是本文档最具实操价值的部分这里结合仓库源码给出完整步骤。环境前提根据 spec_parse.py 顶部注释运行需要满足三个前提已在tools/spec_parser目录成功执行过make parserPATH 中存在可执行的java合适的 JVMANTLR4 运行时 jar 位于/usr/share/java/antlr4-runtime.jar。脚本会在启动时检查后两项缺失时打印提示并以退出码 1 结束if not os.path.exists(antlr_jar): Help(antlr_jar) if not os.path.exists(spec_parser_file): Help(make parser in spec_parser)生成解析器make parser在 Linux 主机上、且 ANTLR 库位于/usr/share/java/antlr4-runtime.jar的前提下进入tools/spec_parser执行make parser即可生成解析器。查看 Makefile 可知构建链路antlr4从Dart.g生成DartLexer.java、DartParser.java、DartLexer.tokensjavac -cp .:$(ANTLR_JAR)编译SpecParser.java为SpecParser.class依赖ANTLR_JAR/usr/share/java/antlr4-runtime.jar与 JDK 中的javac/java。需要注意当前尚不能通过tools/build.py构建规范解析器且它可能无法在所有平台上工作文档明确说明支持tools/build.py/tools/ninja.py以及全平台构建的计划后续才会实现。运行解析器tools/spec_parse.py生成完成后即可用如下方式解析文件tools/spec_parse.py files-to-parse...也可以从其他目录以some/other/path/tools/spec_parse.py调用或将其加入PATH后直接使用。脚本实际的执行逻辑是spec_parser_dir os.path.join(tools_dir, spec_parser) spec_parser_file os.path.join(spec_parser_dir, SpecParser.class) antlr_jar /usr/share/java/antlr4-runtime.jar class_path :.join([spec_parser_dir, antlr_jar]) command [java, -cp, class_path, SpecParser] args即最终以java -cp tools/spec_parser:/usr/share/java/antlr4-runtime.jar SpecParser files的形式在 JVM 中启动解析器并把退出码原样传递回 shell。仓库中还提供了 Dart 语言版本的前端 spec_parse.dart其逻辑相同classpath 中指向antlr3-runtime.jar以异步Process.run方式逐个解析参数中的文件并打印结果或错误。若需批量处理SpecParserRunner.java 支持从标准输入逐行读取文件名并为每个文件打印---------- filename ----------分隔头后调用SpecParser.main。通过 test.py 运行 multi-test 套件涉及 multi-test 的测试运行必须使用tools/test.py因为 multi-test 在被其处理之前通常充满了语法错误。文档给出的示例调用为 tools/test.py -c spec_parser language_2/variable [00:05 | 100% | 137 | - 0] 输出行中的 137表示 137 个测试通过、- 0表示 0 个失败。-c spec_parser正是让测试框架选用上文所述的SpecParserCompilerConfiguration将所有.dart文件交给tools/spec_parse.py做纯语法校验。局限与演进现状从文档与仓库现状可以归纳出以下几点构建方式受限文档明确提到“尚不支持tools/build.py构建可能无法在所有平台工作”构建依赖系统路径下的 ANTLR jar 与 JDK跨平台支持属于后续计划。尚未接入主构建线截至文档写作时规范解析器尚未在任何 buildbot 上运行因此继续在所有 subtest 中一律使用compile-time error不会导致构建失败但这会损失对“语法错误”的精准检验能力。语法文件持续演进从 Dart.g 的变更日志v0.19 → v0.60可以看出这份语法规范一直跟随 Dart 语言新特性同步更新覆盖了记录records、模式patterns、扩展类型extension type、增强augmentation、类修饰符sealed/base/interface/final等现代语法。它既是一台可用的解析器也是一份随语言演进而保持鲜活的语法事实记录。综上Dart 规范解析器在 SDK 中扮演着“语法事实检验器”的角色用真实代码验证语法规则、为语言规范维护提供精确参照并通过syntax error期望结果让测试体系能够区分“解析失败”与“静态分析失败”从而避免语法错误伪装成通过已久的测试。相关实现与文档可分别在 docs/The-Dart-specification-parser.md、tools/spec_parser 与 pkg/test_runner/lib/src 中继续深入探索。赞分享编程语言编译器语言运行时标准库开发工具【免费下载链接】sdkThe Dart SDK, including the VM, JS and Wasm compilers, analysis, core libraries, and more.项目地址https://gitcode.com/gh_mirrors/sdk1/sdk点击查看免费下载相关推荐Baserow 公式语言语法工程解析基于 ANTLR 的文法设计、词法规则与双端解析器生成流程Baserow 公式语言语法工程解析基于 ANTLR 的文法设计、词法规则与双端解析器生成流程 导读 Baserow 的公式字段Formula Field后端前端数据库低代码工作流自动化黑苹果EFI一键生成只用3个按钮OpCore Simplify 自动化工具完整实战指南黑苹果EFI一键生成只用3个按钮OpCore Simplify 自动化工具完整实战指南 EFI 已经生成了U盘插上去却进不了安装界面——多半是配置里缺了几个开发工具CLIelectron-builder 开发工作流指南编译、测试与验证规范全解析electron builder 开发工作流指南编译、测试与验证规范全解析 导读 本文基于 electron builder 仓库根目录的 CLAUDE.md构建工具桌面应用开发工具上一篇Mac 菜单栏图标被刘海吞掉Ice 菜单管理 3 步救回来下一篇告别代码异味5款重构神器助你写出工业级VS Code插件创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
