Roc 语言快照测试解析：带载荷 Tag 的 match 表达式完整编译流水线
发布时间：2026/9/18 8:01:19 作者：尧图编辑部 阅读量：1,286
Roc 语言快照测试解析带载荷 Tag 的 match 表达式完整编译流水线【免费下载链接】rocA fast, friendly, functional language.项目地址: https://gitcode.com/GitHub_Trending/ro/roc本篇技术指南以 Roc 编译器仓库中的快照文档test/snapshots/match_expr/tag_with_payload.md为骨架逐层剖析一个带载荷payload的 Tag 模式 match 表达式如何依次经过词法分析、语法解析、代码格式化、规范化canonicalization与类型检查五个编译阶段并结合 canonicalize 源码 与 快照工具 的实现说明快照测试如何锁定编译器行为。读完本文你将理解 Roc 中 Tag Union 构造器模式匹配的语法与语义、小数在 IR 中的有理数表示以及如何阅读、运行和更新这类快照测试。一、背景Roc 的快照测试体系RocREADME.md 中自我描述为 A fast, friendly, functional language是一个函数式语言其编译器使用 Zig 实现。为了保证编译器在大量用例下不产生行为回退regression仓库维护了一套**快照测试snapshot testing**机制相关说明见 src/snapshot_tool/README.mdSnapshot testing is a method used to verify the behavior of the compilers different stages. The tool generates golden snapshot files, which are baseline outputs that are known to be correct.快照文件即黄金基线测试运行时工具会重新运行编译器各阶段将实际输出与这些已提交到仓库的基线比对任何差异都会导致测试失败。每个快照文件展示同一段 Roc 源码在词法、解析、规范化、类型检查等各阶段的预期输出总览见 test/snapshots/README.md。本文聚焦的 tag_with_payload.md 属于test/snapshots/match_expr/目录该目录收录了 40 余个关于match表达式的快照如 basic_tag_union.md、guards_1.md、literal_patterns.md 等本文这份专门验证Tag 模式携带载荷的场景。二、被测试的源码基于 Tag Union 的面积计算快照文档的SOURCE段落给出了被测代码这是全文的起点match shape { Circle(radius) 3.14 * radius * radius Rectangle(width, height) width * height Triangle(base, height) 0.5 * base * height }这是一段典型的Tag Union标签联合模式匹配代码match关键字后是被匹配的被检值scrutineeshape花括号内是若干分支branch每个分支由**模式pattern与之后的表达式expression**组成。Circle(radius)匹配标签Circle且携带一个载荷radiusRectangle(width, height)匹配标签Rectangle且携带两个载荷width、heightTriangle(base, height)匹配标签Triangle且携带两个载荷base、height。每个分支的右侧都根据几何公式计算面积圆面积πr²用3.14近似 π、矩形面积宽 × 高、三角形面积底 × 高 ÷ 2。由于三个分支都会产出小数整个表达式的类型被推断为Dec十进制小数见下文TYPES段。match是 Roc 的核心控制流结构而带载荷的标签模式正是其最常用形态。在编译器内部这类模式有专门的数据结构支撑见 src/canonicalize/Pattern.zig/// Pattern that matches a tag with arguments (constructor pattern). /// Used for pattern matching tag unions with payloads. /// /// roc /// match shape { /// Circle(radius) 3.14 * radius * radius /// Rectangle(width, height) width * height /// } /// applied_tag: struct { name: Ident.Idx, args: Pattern.Span, },从源码注释可以看到applied_tag已应用标签/构造器模式正是为匹配携带载荷的 Tag Union而设计源码注释中的示例与快照中的Circle、Rectangle分支如出一辙。其中name记录标签名如Circleargs记录载荷模式序列如radius、width, height每个载荷本身又是一个子模式这里是标识符模式p-ident。文档元信息EXPECTED 与 PROBLEMS 均为 NIL快照头部的META段声明了descriptionMatch expression with tag patterns containing payloads用一句话描述本用例与typeexpr快照类型为表达式级。EXPECTED与PROBLEMS两段均为NIL含义是这段代码是合法的、可以成功编译的编译器不应产出任何诊断报告。按 test/snapshots/README.md 的说明普通快照typeexpr等的PROBLEMS段保存的是每个reporting.Report的规范化 S-表达式由 src/reporting/report_sexpr.zig 序列化NIL即表示本次编译零报告。三、第一站词法分析TOKENS快照的TOKENS段展示了词法分析器lexer的输出即把源码切分为带类型的 token 流KwMatch,LowerIdent,OpenCurly, UpperIdent,NoSpaceOpenRound,LowerIdent,CloseRound,OpFatArrow,Float,OpStar,LowerIdent,OpStar,LowerIdent, UpperIdent,NoSpaceOpenRound,LowerIdent,Comma,LowerIdent,CloseRound,OpFatArrow,LowerIdent,OpStar,LowerIdent, UpperIdent,NoSpaceOpenRound,LowerIdent,Comma,LowerIdent,CloseRound,OpFatArrow,Float,OpStar,LowerIdent,OpStar,LowerIdent, CloseCurly, EndOfFile,逐 token 对照源码可还原出词法规则KwMatchmatch关键字LowerIdent小写开头的标识符shape、radius、width、height、baseUpperIdent大写开头的标识符Circle、Rectangle、TriangleRoc 借此区分 Tag 与普通变量OpenCurly/CloseCurly花括号{}NoSpaceOpenRound紧贴前一个 token 的(——注意这个 token 专门编码了左括号与前缀之间无空格这一信息是保留格式布局所需CloseRound)Comma,OpFatArrowFloat浮点字面量3.14、0.5OpStar*乘法运算符EndOfFile文件结束标记。值得强调的是NoSpaceOpenRoundRoc 的词法层会保留 token 间的空白信息为后续格式化FORMATTED段提供依据这也解释了为何解析树中的p-tag节点能够记录无空格左括号这类布局细节。四、第二站语法解析PARSEPARSE段是语法分析器产出的 S-表达式形式的 AST抽象语法树展示了match表达式的整体结构(e-match (e-ident (raw shape)) (branches (branch (p-tag (raw Circle) (p-ident (raw radius))) (e-binop (op *) (e-binop (op *) (e-frac (raw 3.14)) (e-ident (raw radius))) (e-ident (raw radius)))) (branch (p-tag (raw Rectangle) (p-ident (raw width)) (p-ident (raw height))) (e-binop (op *) (e-ident (raw width)) (e-ident (raw height)))) (branch (p-tag (raw Triangle) (p-ident (raw base)) (p-ident (raw height))) (e-binop (op *) (e-binop (op *) (e-frac (raw 0.5)) (e-ident (raw base))) (e-ident (raw height))))))从解析树中可以读出明确的语法结构根节点e-match带两个子节点被检值表达式(e-ident (raw shape))与branches分支列表每个branch由模式部分与表达式部分构成模式部分p-tag标签名Circle等后跟若干p-ident载荷标识符即带载荷的 Tag 模式表达式部分e-binop二元运算节点3.14 * radius * radius被解析为左结合的嵌套结构(3.14 * radius) * radius0.5 * base * height同理而width * height是一层e-binope-frac小数/分数字面量节点3.14、0.5。这里可以观察到语法设计的两个要点其一Tag 的载荷数量没有限制一个到多个皆可语法上表现为p-tag的任意多个子节点其二*是左结合运算符e-binop因此呈左深嵌套这一形态会原样传递到规范化阶段。五、第三站格式化输出FORMATTEDFORMATTED段给出了格式化器的输出。由于源码本身书写规范格式化结果与输入一致match shape { Circle(radius) 3.14 * radius * radius Rectangle(width, height) width * height Triangle(base, height) 0.5 * base * height }注意两点缩进使用的是制表符TabCircle(radius)中括号紧贴标签名没有空格——这与词法层记录的NoSpaceOpenRound信息相呼应说明 Roc 的格式化器依赖词法阶段保留的空白信息来还原规范布局。快照测试将格式化输出也纳入基线因此任何格式化规则的变化都会在快照差异中暴露。六、第四站规范化CANONICALIZECANONICALIZE段是整份文档信息量最大、最能体现编译器内部表示IR的部分。规范化阶段将 AST 转换为更接近底层语义的规范化 IR快照的PROBLEMS为NIL意味着这个阶段同样无诊断。下面是完整输出(e-match (match (cond (e-runtime-error (tag ident_not_in_scope))) (branches (branch (patterns (pattern (degenerate false) (p-applied-tag))) (value (e-dispatch-call (method times) (constraint-fn-var 241) (receiver (e-dispatch-call (method times) (constraint-fn-var 239) (receiver (e-dec-small (numerator 314) (denominator-power-of-ten 2) (value 3.14))) (args (e-lookup-local (p-assign (ident radius)))))) (args (e-lookup-local (p-assign (ident radius))))))) (branch (patterns (pattern (degenerate false) (p-applied-tag))) (value (e-dispatch-call (method times) (constraint-fn-var 247) (receiver (e-lookup-local (p-assign (ident width)))) (args (e-lookup-local (p-assign (ident height))))))) (branch (patterns (pattern (degenerate false) (p-applied-tag))) (value (e-dispatch-call (method times) (constraint-fn-var 262) (receiver (e-dispatch-call (method times) (constraint-fn-var 260) (receiver (e-dec-small (numerator 5) (denominator-power-of-ten 1) (value 0.5))) (args (e-lookup-local (p-assign (ident base)))))) (args (e-lookup-local (p-assign (ident height))))))))))对照源码实现可逐点解读1.e-match节点的序列化。规范化 IR 中每个match表达式对应e-match节点见 src/canonicalize/Expression.zig 中e_match分支的pushStaticAtom(e-match)其子节点match、cond、branches承载具体结构。这里有一个值得注意的细节cond下出现(e-runtime-error (tag ident_not_in_scope))。从源码结构可以推断这是规范化器为被检值表达式shape生成的占位/降级表示——由于快照是脱离完整模块独立编译的片段shape在作用域中不可见规范化器便以运行时错误标识符不在作用域的节点兜底同时保证流水线继续推进。也就是说这段快照验证的是match语法与模式语义而非被检值本身的求值。2.p-applied-tag模式。每个分支的模式统一变为(pattern (degenerate false) (p-applied-tag))p-applied-tag与 Pattern.zig 中的applied_tag变体对应其 S-表达式序列化实现在 Pattern.zigpushStaticAtom(p-applied-tag)。(degenerate false)表示该模式不是退化模式即匹配不会必然失败/必然成功是真实的构造器匹配。而Circle、Rectangle、Triangle的标签名与载荷在这里被折叠进了p-applied-tag标记中——规范化阶段已完成了对模式的解析与归类radius、width等载荷标识符则下沉到各分支的value表达式中以e-lookup-localp-assign形式出现。3. 小数改为有理数表示e-dec-small。这是最体现 Roc 设计哲学的细节3.14不再以浮点字面量出现而是被表示为(e-dec-small (numerator 314) (denominator-power-of-ten 2) (value 3.14))即314 / 10² 3.140.5则表示为(numerator 5) (denominator-power-of-ten 1)即5 / 10¹ 0.5。对应的序列化实现位于 src/canonicalize/Expression.zig节点输出numerator分子、denominator-power-of-ten分母的 10 的幂次与回算出的value。Roc 的Decdecimal类型采用分子 10 的幂次分母的有理数表示从根本上规避二进制浮点的精度问题——这正与 Pattern.zig 中对小数模式匹配的注释一致Rocs preferred approach for exact decimal matching, avoiding floating-point precision issues by using numerator/denominator representation。对3.14这样的字面量规范化的第一步就是把浮点写法转成精确的有理数。4. 运算被编译为方法分派e-dispatch-call。每个*乘法都变成e-dispatch-call节点方法名为times并携带一个constraint-fn-var约束函数变量编号如 239、241、247、260、262。例如圆面积分支(e-dispatch-call (method times) (constraint-fn-var 241) (receiver (e-dispatch-call (method times) (constraint-fn-var 239) (receiver (e-dec-small ... (value 3.14))) (args (e-lookup-local (p-assign (ident radius)))))) (args (e-lookup-local (p-assign (ident radius)))))其序列化同样在 Expression.zig 附近pushStaticAtom(e-dispatch-call)。含义是times是一个约束函数变量constraint function variable其具体实现例如Dec上的乘法还是F64上的乘法要等类型检查阶段解析约束后确定——这是 Roc 支持重载/能力capabilities的 IR 级体现。radius在模式中被绑定进入分支体后以e-lookup-local局部查找p-assign赋值模式读取印证了模式绑定变量在分支体内可见的作用域规则。5. 分支结构保持一一对应。三个分支在规范化后顺序不变每个分支仍由patterns含degenerate标记与value分支体表达式构成与解析树的branch一一对应便于类型检查与后续代码生成逐分支处理。七、第五站类型检查TYPES最后一个快照段TYPES极简但信息完整(expr (type Dec))整个match表达式的类型被推断为Dec十进制小数。这个结论由三个分支的返回类型共同收敛得出3.14 * radius * radius、width * height、0.5 * base * height均为小数运算e-dec-small的字面量类型为Dec因此match的所有分支体类型一致表达式整体为Dec。这也反向印证了快照META中typeexpr的定位本快照只针对表达式级类型信息做基线锁定match分支类型一致性exhaustiveness / 类型统一是类型检查器在此处的核心职责。八、实操运行与更新快照tag_with_payload.md这类快照不是手工编写的文档而是由快照工具生成并维护的。在仓库根目录执行详见 test/snapshots/README.md 的 Usage 一节# 重新生成全部快照基线比对 zig build run-snapshot-tool # 只更新指定快照文件 zig build run-snapshot-tool -- test/snapshots/match_expr/tag_with_payload.md # 更新期望值当代码行为有意的变化导致 PROBLEMS 变化时使用 zig build run-snapshot-tool -- test/snapshots/match_expr/tag_with_payload.md --update-expected对应的构建步骤定义在 build.zigrun-snapshot-tool步骤约 build.zig 附近负责运行快照工具更新文件另有run-check-snapshots步骤约 build.zig 附近会重新生成全部快照再通过git diff --exit-code test/snapshots校验跟踪文件是否有变化见 build.zig从而在 CI 中自动拦截编译器行为被意外改变但快照未同步的回退。快照工具本体位于 src/snapshot_tool/main.zig工作流程是读取快照文件的SOURCE运行编译流水线各阶段将实际输出与文件中的TOKENS/PARSE/FORMATTED/CANONICALIZE/TYPES等段比对。因此当你修改了词法、解析、格式化、规范化或类型检查的任何行为后若相关快照报错就说明该行为变化影响了既有基线——这正是快照测试的守护价值。此外src/snapshot_tool/README.md 还说明了诊断快照的分工普通快照的PROBLEMS锁定诊断语义由 src/reporting/report_sexpr.zig 序列化而test/snapshots/reporting/下的typereporting快照才锁定 CLI、MARKDOWN、HTML、LSP 等渲染器的具体排版。九、小结通过 tag_with_payload.md 这一份快照可以一次看全 Roc 编译器对带载荷 Tag 模式 match 表达式的完整处理链路编译阶段快照段关键证据词法分析TOKENSUpperIdent区分 TagNoSpaceOpenRound保留布局信息语法解析PARSEp-tag携带任意多个p-ident载荷*左结合嵌套格式化FORMATTED规范布局与词法空白信息一致Tab 缩进规范化CANONICALIZEp-applied-tag模式、e-dec-small有理数小数、e-dispatch-call方法分派、模式变量经e-lookup-local读取类型检查TYPES三分支类型收敛为Dec其背后分别是 Pattern.zig 的applied_tag模式设计、Expression.zig 的e-match/e-dec-small/e-dispatch-call序列化实现以及 snapshot_tool 的整体快照机制。理解这份快照就等于理解了 Roc 中 Tag Union 模式匹配从源码到 IR 的核心语义也掌握了阅读与维护编译器快照测试的方法。若想继续深入可以对照阅读同目录下的 basic_tag_union.md无载荷 Tag 匹配、nested_patterns.md嵌套模式与 pattern_alternatives_basic.md模式备选分支它们共同勾勒出 Roc 模式匹配的完整能力边界。【免费下载链接】rocA fast, friendly, functional language.项目地址: https://gitcode.com/GitHub_Trending/ro/roc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
尧图网站开发 