Roc 快照测试剖析格式化器如何保留记录字段注解中的 var 关键字【免费下载链接】rocA fast, friendly, functional language.项目地址: https://gitcode.com/GitHub_Trending/ro/roc本篇以 Roc 编译器仓库中的快照测试文件 fmt_var_in_record_field.md 为骨架逐段拆解一个完整快照文件所承载的编译管线信息从 token 化、解析AST、格式化输出到 canonical IR、类型推断与诊断报告。读完本文你将掌握 Roc 快照测试的文件结构与运行/更新方式理解var声明的可变性语义与$命名约定背后的编译期诊断实现并能据此读懂仓库中其他 1200 快照文件。快照测试Roc 编译管线的行为快照Roc 仓库的 test/snapshots/README.md 明确定义了快照测试的定位通过捕获每个编译阶段针对特定 Roc 代码示例的输出来验证编译器行为。快照测试覆盖 token 化、解析、canonicalize、类型检查等完整流程每个快照文件保存各阶段的期望输出当编译器行为发生意外变化时能够及时暴露回归。快照按诊断类型分为两类语义与呈现彻底分离普通快照typefile、snippet、expr等捕获诊断的语义其PROBLEMS段是每个reporting.Report的规范 S-表达式序列化见 src/reporting/report_sexpr.zig包含 severity、标题、源码区域以及完整文档结构文本、注解、源码摘录、下划线不含任何渲染器专属细节无框线字符、ANSI 转义、换行或标记。NIL表示编译未产生任何报告。这类快照回答的问题是编译器是否产生了正确的诊断报告快照typereporting位于reporting/目录固定渲染器输出将同一组语义报告按REPORT、CLI、MARKDOWN、HTML、LSP每种格式各输出一段。渲染器专属改动只应影响reporting/下的文件诊断语义的改动则体现在普通快照中。这正是 fmt_var_in_record_field.md 属于普通快照typesnippet的原因——它固定的是编译器诊断语义与格式化行为而非终端排版。一个快照文件的全景拆解fmt_var_in_record_field.md的文件名意为在记录字段注解中的格式化var其 META 描述为Formatter preserves var keyword in record field annotations格式化器在记录字段注解中保留var关键字。该文件由八个区块组成每一块对应编译管线的某一阶段。我们先看它测试的源代码再逐段解读。META 与 SOURCEdescriptionFormatter preserves var keyword in record field annotations typesnippetMETA 区用 ini 风格的键值对声明快照的测试类型snippet与描述。SOURCE 区是待编译的原始代码f||{var c:[]}这是一行紧凑的 Roc 代码定义标识符f其值为一个无参 lambda||lambda 体内是一个块{ var c : [] }。块中声明了一个带类型注解的var变量c注解类型为[]空 tag union 类型见下方 PARSE 中的ty-tag-union空 tags。该快照的核心关注点即var关键字出现在这类注解位置时格式化器是否会将其原样保留。EXPECTED编译器应产生的诊断VAR NAME MISSING $ - fmt_var_in_record_field.md:1:10:1:11 UNUSED VARIABLE - fmt_var_in_record_field.md:1:10:1:11EXPECTED区是PROBLEMS区的摘要速览指明该源文件在编译时应产生两条警告且两条警告都定位在1:10到1:11的源码区域即第 1 行第 10 列到第 11 列正是标识符c的位置。这两条警告分别是Var Name Missing$——var声明的名字没有以$开头Unused Variable——变量c声明后从未被使用。PROBLEMS规范化的诊断报告PROBLEMS区以 Clojure S-表达式给出两条报告的完整规范序列化。第一条报告的结构如下(report (severity warning) (title Var Name Missing $) (region (start 1 10) (end 1 11)) (headline (reflow The mutable binding ) (annotated symbol-unqualified c) (reflow is declared with ) (annotated keyword var) (reflow but its name does not start with ) (annotated code $) (reflow .)) (document (reflow Rename this binding and all of its uses to ) (annotated symbol-unqualified $c) (reflow . The name is only a convention; mutability comes from the ) (annotated keyword var) (reflow declaration.) ...))这条报告携带了诊断的全部要素severitywarning、title、region源码区域、headline可渲染的标题行对标识符c、关键字var、行内代码$分别做注解标记以及document完整建议文案把该绑定及其所有使用处重命名为$c名字只是约定可变性来自var声明。这正是普通快照与渲染器解耦的体现——报告内容是纯语义结构任何终端、HTML、LSP 渲染器都可以据此独立排版。第二条报告为Unused Variableheadline 为变量c在此定义但从未使用其 document 给出了消除警告的实战建议如不需要该变量请加上下划线前缀如_c以抑制此警告。这一建议与 Roc 的下划线忽略命名惯例一致。TOKENStoken 化结果LowerIdent,OpAssign,OpBar,OpBar,OpenCurly,KwVar,LowerIdent,OpColon,OpenSquare,CloseSquare,CloseCurly, EndOfFile,TOKENS 区展示了词法分析器如何把f||{var c:[]}切分为 token 流fLowerIdent→OpAssign→||两个 OpBar→{OpenCurly→varKwVar关键字 token→cLowerIdent→:OpColon→[OpenSquare→]CloseSquare→}CloseCurly→ EOF。可以注意到var被识别为独立的KwVar关键字 token这是格式化器能够区分并保留它的基础。PARSE语法树(file (type-mod) (statements (s-decl (p-ident (raw f)) (e-lambda (args) (e-block (statements (s-type-anno (name c) (ty-tag-union (tags)))))))))PARSE 区是解析器产出的 AST顶层是s-decl声明左侧模式为标识符f右侧是e-lambda表达式args为空lambda 体是e-block块块内语句为s-type-anno类型注解——注解对象名为c类型表达式为ty-tag-union且tags为空即[]空 tag union 类型。可见var c : []在 AST 层面被建模为带类型注解的变量声明var关键字并未在 PARSE 树中丢失它属于注解的可变性信息。FORMATTED格式化器输出f || { var c : [] }FORMATTED 区是本次快照的标题性结论格式化器将f||{var c:[]}规范化为多行形式并且完整保留了var关键字。具体来说两侧补空格lambda 体{ }展开为三行块var c : []整体保留在块内。格式化器不仅调整了空白与换行还保住了var这一语义关键字——这正是该快照文件名与 META 描述要守护的行为。相关的格式化器实现在 src/fmt/fmt.zig它基于已解析的 AST 重新排版其错误类型FormatAstError、FormatFileError等定义了格式化各输入场景的失败边界。CANONICALIZE 与 TYPES中间表示与类型推断(can-ir (d-let (p-assign (ident f)) (e-lambda (args) (e-block (s-var-uninitialized (p-var-assign (ident c))) (e-empty_record)))))canonicalize 阶段将 AST 转为规范 IRd-let绑定f为 lambdalambda 体内先执行s-var-uninitialized未初始化变量声明模式为p-var-assign (ident c)块末尾表达式是e-empty_record空记录{}。(inferred-types (defs (patt (type ({}) - {}))) (expressions (expr (type ({}) - {}))))类型推断给出f的类型为({}) - {}即该 lambda 接收一个空记录{}参数Roc 中无参函数以空记录为参数的典型形态返回空记录{}。源码级深挖Var Name Missing $诊断的实现快照EXPECTED/PROBLEMS中固定的诊断并非凭空而来其实现位于 src/canonicalize/ModuleEnv.zig 的binding_name_does_not_match_mutability分支。该分支按可变性生成不同标题const title switch (data.mutability) { .mutable Var Name Missing $, .immutable Dollar Prefix Without var, };当绑定为mutable用var声明而名字不以$开头时报告标题为Var Name Missing$headline 文案与快照中的PROBLEMS逐字对应反向情况不可变绑定却以$开头则产生Dollar Prefix Withoutvar警告建议要么去掉$前缀要么改用var声明。值得注意的是报告文档中的措辞The name is only a convention; mutability comes from thevardeclaration.名字只是约定可变性来自var声明——即$前缀本质上只是命名惯例编译期真正的可变性语义由var关键字决定。这也解释了为什么在记录/块注解位置出现var c时编译器仍会检查$前缀。$命名约定的语言层面依据可见于 docs/langref/records.md记录字段名不得包含$与可重新赋值的var标识符相对以及 docs/langref/loops.md 中循环变量的标准写法var $sum 0、var $visited []等示例——可变变量一律以$开头。源码级深挖Unused Variable诊断的实现第二条警告同样有明确的源码依据。src/canonicalize/Diagnostic.zig 定义了unused_variable诊断结构src/canonicalize/ModuleEnv.zig 中将其初始化为标题为Unused Variable、severity 为warning的报告src/canonicalize/Diagnostic.zig 也给出了报告初始化逻辑。诊断的修复建议下划线前缀_c与 Roc 的惯例一致将不需要的变量命名为_或_c即可抑制该警告。在快照的语境中var c : []声明了c但从未在块内使用因此 canonicalize 阶段标记为未使用变量与Var Name Missing $警告叠加出现。实战运行与更新该快照快照文件是机器可校验的规格。仓库提供了统一的快照工具命令源自 test/snapshots/README.md# 生成全部快照 zig build run-snapshot-tool # 仅更新指定快照文件 zig build run-snapshot-tool -- file_path # 依据 PROBLEMS 更新期望值EXPECTED zig build run-snapshot-tool -- file_path --update-expected针对本快照可执行zig build run-snapshot-tool -- test/snapshots/fmt_var_in_record_field.md注意事项快照工具要求编译器以compiler_version null的选项运行从而不重写任何roc: ...版本固定见 src/fmt/fmt.zig 的Options.compiler_version注释保证快照输出不随构建它的编译器版本漂移若源文件需要嵌入回车符字节可在 META 中加source_escapestrue并将\r写入 SOURCEREPL 类快照typerepl可加--trace-eval跟踪解释器执行仅支持单个文件且需 debug 构建。--update-expected尤其适合在确认新诊断行为正确时一键把 PROBLEMS 摘要同步到 EXPECTED 区。小结通过 fmt_var_in_record_field.md 这一个文件可以纵览 Roc 编译器从词法、语法、格式化、canonicalize 到类型推断与诊断的完整管线格式化器保留var关键字的行为被固定为规范输出Var Name Missing $与Unused Variable两条警告分别由 src/canonicalize/ModuleEnv.zig 与 src/canonicalize/Diagnostic.zig 驱动揭示了可变性来自var声明、$仅为命名约定的设计语义。阅读同类快照时按 META → EXPECTED → PROBLEMS → TOKENS → PARSE → FORMATTED → CANONICALIZE → TYPES 的顺序对照源码即可快速定位任何编译行为的期望值与实现位置。【免费下载链接】rocA fast, friendly, functional language.项目地址: https://gitcode.com/GitHub_Trending/ro/roc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
