Roc 语言十六进制整数字面量解析全流程以 test/snapshots/expr/int_hex.md 快照测试为线索【免费下载链接】rocA fast, friendly, functional language.项目地址: https://gitcode.com/GitHub_Trending/ro/roc本篇以 roc 编译器仓库中的快照测试 test/snapshots/expr/int_hex.md 为骨架逐段拆解十六进制整数字面量0xFF从词法分析、语法解析、规范化到类型推断的完整编译管线并对照 docs/langref/numbers.md 中的数字字面量规范与相邻快照测试说明 roc 如何识别十六进制前缀、字母数字、下划线等词法要素如何在规范化阶段完成进制换算以及未约束类型的整数字面量为何默认推断为Dec。读完本文你将能够依据快照格式复现编译器各阶段的输出并掌握 roc 数字字面量的完整语法规则与边界行为。一、快照测试Roc 编译器最细粒度的“活文档”在 roc 仓库的 test/snapshots 目录下存放着成百上千个快照测试文件。它们把一段最小的 roc 源码分别输入编译器前端的不同阶段并将每个阶段的精确输出记录下来作为回归测试的期望值只要某次修改让任一阶段的输出与快照不符测试即失败。快照文件采用固定的分段结构每个分段都有明确职责test/snapshots/expr/int_hex.md 就是最典型的一例分段职责int_hex.md 中的内容META测试元信息描述、类型descriptionHexadecimal integer literal、typeexprSOURCE被测的 roc 源码输入0xFFEXPECTED期望的编译结果NIL表示无错误NILPROBLEMS期望的诊断/错误报告NIL表示无报告NILTOKENS词法分析Lexer产出的 Token 流Int, EndOfFilePARSE语法分析Parser产出的 AST(e-int (raw 0xFF))FORMATTED格式化器的输出NO CHANGE表示源码本身已符合格式规范NO CHANGECANONICALIZE规范化Canonicalization后的中间表示(e-num (value 255))TYPES类型推断后的类型信息(expr (type Dec))这份文件同时具备三重价值它是回归测试断言每个分段都是必须满足的期望值、是编译器各阶段的精确文档记录了内部表示的真实形态、也是理解语言语义的最小教学案例。本文即以它的九个分段为主线展开。二、逐段拆解 int_hex.md从源码到类型的九步2.1 META测试的身份证descriptionHexadecimal integer literal typeexprdescription用一句话概括本测试的语义关注点——十六进制整数字面量typeexpr表明该测试位于表达式expression类别对应它在 test/snapshots/expr 目录下的位置。同目录下的int_with_underscores.md、number_literal_suffixes.md、minus_not_h.md、unicode_not_hex.md等文件共同构成了整数字面量的测试矩阵。2.2 SOURCE被测输入0xFF这是全文唯一一行源码十六进制前缀0x加上两位十六进制字母数字FF。它同时命中了 roc 数字字面量的两个关键语法要素——Base Prefix与Letter Digits是验证十六进制解析的最小完备用例。2.3 EXPECTED 与 PROBLEMS合法输入的“零告警”EXPECTED NIL PROBLEMS NIL两个NIL说明0xFF是完全合法的输入编译不会产出任何错误EXPECTED也不会产生任何诊断报告PROBLEMS。对比同目录下的 number_literal_suffixes.md其中-123.U8等负数字面量超出无符号类型范围时PROBLEMS段会给出(severity runtime_error)、标题为Invalid Number、正文为This number literal does not fit in the inferred type.的完整诊断——合法与非法输入的快照差异正是理解编译器报错机制的对照样本。2.4 TOKENS词法层只认得一个“整数”TokenInt, EndOfFile,词法分析阶段只产出两个 Token一个Int整数字面量和流结束符EndOfFile。注意十六进制前缀0x并不会单独成为一个 Token词法器把0xFF整体识别为一个Int前缀与字母数字的区分被推迟到后续阶段处理。这印证了 roc 词法设计的取舍——Token 层面只关心“这是不是一个整数”不关心“它是几进制的”。2.5 PARSE语法树保留原始拼写(e-int (raw 0xFF))Parser 产出的 AST 节点是e-int其参数raw原样保存了源码文本0xFF。raw字段的存在说明解析阶段不做任何进制换算也不剥离前缀0x与FF的完整拼写被原封不动地携带进 AST等待规范化阶段统一处理。2.6 FORMATTED格式稳定性断言NO CHANGENO CHANGE意味着这段源码已经符合 roc 格式化器的规范格式化后输出与输入完全一致。格式化稳定性是快照测试的常规断言——它保证语言风格的一致性不会因编译器版本迭代而漂移。2.7 CANONICALIZE进制换算在这里完成(e-num (value 255))规范化canonicalize阶段是本文的核心看点AST 节点从e-int变为e-numraw 0xFF变为value 255。十六进制到十进制的换算0xFF 255正是在这个阶段完成的前缀0x被剥离字母数字被换算为等值的十进制字符串。这一机制在兄弟快照中得到交叉印证int_with_underscores.md1_000_000解析为(e-int (raw 1_000_000))规范化后为(e-num (value 1000000))——下划线在规范化阶段被移除只留下纯数值number_literal_suffixes.md0b101解析为(e-typed-int (raw 0b101) (type U8))规范化后为(e-typed-int (value 5) (type U8))——二进制 101 被换算为十进制 5。三个案例共同揭示了一条清晰的设计原则词法层与解析层保留源码的原始形态进制换算统一收敛在规范化阶段。这样下游的类型检查与代码生成只需处理统一的十进制表示无需关心字面量当初用哪种进制书写。从源码结构看这也是 roc 编译器将“数字语义处理”从“语法结构处理”中分离出来的体现相关代码目录见仓库 src/canonicalize 与 src/parse。2.8 TYPES未约束字面量默认推断为 Dec(expr (type Dec))0xFF没有出现在任何会约束其类型的上下文中没有参与运算、没有作为函数实参、没有类型注解因此类型推断阶段为其选定了默认类型Dec。这正是 docs/langref/numbers.md 中 “Defaulting toDec” 一节的落地实现当数字字面量始终无法被推断为具体类型时编译器回退到内置的Dec。三、词法规则全景0x 前缀、字母数字与书写要素docs/langref/numbers.md 对数字字面量的词法构成给出了权威定义。一个 roc 数字字面量可以由以下要素任意组合要素规则数字位0-9位于最开头的0永远不会改变数值字母位a-f大小写均可0xFF即大写用例在十六进制字面量中表示十进制 10–15进制前缀0x十六进制base-16、0o八进制base-8、0b二进制base-2无前缀时默认为十进制base-10前缀字母必须小写科学计数法后缀仅限十进制字面量形如e___将e前的部分乘以 10 的___次幂指定进制前缀时不可使用小数点可与科学计数法组合但进制前缀存在时不可使用避免小数点后的大写十六进制字母与类型后缀如.F64产生歧义下划线编译器直接跳过仅用于提高长数字可读性可出现在任意数字位之间含字母位及小数点后的数字之间但两侧必须有数字负号位于最前方表示负数这是字面量的一部分区别于对表达式生效的取负运算符如-x是运算符-1是普通字面量二者对自定义数字类型有语义差异来自官方文档的合法示例1 -1 1.23 -123.456e789 0x1abcde42 -1_000_000.123_456_789注意0x1abcde42同时使用了字母位与数字位而-1_000_000.123_456_789演示了负号与下划线的组合——这些要素叠加时编译器会按上表规则逐一校验。同目录下minus_not_h.md与unicode_not_hex.md从命名即可看出roc 的快照矩阵还覆盖了“h相关歧义”“Unicode 字符不应被当作十六进制字母”等边界情形说明十六进制词法并非简单的前缀匹配而是有严格的字符集约束。四、类型系统从默认 Dec 到显式类型后缀4.1 为什么默认是 Dec按 docs/langref/numbers.md 的说明当字面量始终无法被推断出具体类型时roc 使用内置Dec。其典型场景是 REPL 中的即兴计算——Dec既能表示小数又能在快速计算时给出精确答案。文档中的示例if 2 1 { # ... }这里2 1必须求值以决定if分支但没有任何使用场景能把2和1关联到具体数字类型因此等价于2.Dec 1.Dec。int_hex.md 中的0xFF正是这一规则的最小验证案例。4.2 显式类型后缀让字面量类型一目了然如果希望字面量被解释为特定类型无论是为了文档化还是为了在误用时获得错误报告可以在字面量末尾以点号接类型名-12.34.Dec 123.U8 0b101.U8类型后缀不仅适用于内置类型也适用于自定义数字类型——唯一要求是类型名必须在作用域内。自定义类型通过实现from_numeralroc 的 well-known 静态分派方法之一在编译期将字面量解析为对应值。4.3 内置整数类型速查docs/langref/numbers.md 给出的内置整数类型固定大小、不随编译目标变化、仅在与Str等堆分配类型互转时分配堆内存范围类型内存大小-128到127I81 字节0到255U81 字节-32_768到32_767I162 字节0到65_535U162 字节-2_147_483_648到2_147_483_647I324 字节0到4_294_967_295U324 字节-9_223_372_036_854_775_808到9_223_372_036_854_775_807I648 字节0到18_446_744_073_709_551_615U648 字节-170_141_183_460_469_231_731_687_303_715_884_105_728到170_141_183_460_469_231_731_687_303_715_884_105_727I12816 字节0到340_282_366_920_938_463_463_374_607_431_768_211_455U12816 字节有符号与无符号的选择直接影响可表示范围而 number_literal_suffixes.md 的快照证明超出推断类型的字面量会在编译期被拒绝——-123.U8产生Invalid Number运行时错误级报告0b101.U8则因 5 落在U8范围内而正常通过。这意味着0xFF即 255若被标注为0xFF.U8可以合法编译但若写成0x100.U8即 256就会触发同样的越界错误——十六进制字面量与十进制字面量共享同一套范围校验。五、把快照当测试用校验机制与阅读建议快照文件是编译器测试基建的输入测试运行器读取SOURCE段的源码将其送入编译器的词法、解析、格式化、规范化、类型推断各阶段再把每个阶段的实际输出与快照中对应分段逐一比对任何不一致都会导致测试失败。因此修改编译器前端行为时开发者必须同步更新受影响的快照——这正是快照测试作为“活文档”能长期保持与实现同步的原因。仓库的 CI 脚本中即可看到针对快照的专门校验例如 ci/valgrind_snapshots.sh。对读者而言阅读 test/snapshots/expr 目录时建议采用“对照法”先看SOURCE判断被测语法点再看TOKENS/PARSE理解词法与语法形态随后重点对比PARSE与CANONICALIZE观察语义归一化进制换算、去下划线、字符转码都发生在这里最后用TYPES验证类型推断结论。int_hex.md 正是练习这一读法的理想起点——它足够短小却又覆盖了从源码到类型的全部九个阶段。六、总结从0xFF这一个十六进制字面量出发test/snapshots/expr/int_hex.md 完整呈现了 roc 编译器的前端工作流词法层把0xFF整体识别为IntToken解析层以e-int节点保留原始拼写规范化层完成进制换算得到(e-num (value 255))类型推断层在无约束时默认给出Dec。配合 docs/langref/numbers.md 的规范说明与int_with_underscores、number_literal_suffixes等兄弟快照可以得出三条可验证的结论进制换算发生在规范化阶段而非词法或解析阶段——原始拼写会一直保留到canonicalize十六进制只是书写语法0xFF、0b101、1_000_000在规范化后都统一为十进制字符串后续阶段完全一致未约束的数字字面量默认推断为Dec而显式类型后缀如.U8会触发编译期的范围校验越界即报Invalid Number。快照测试既是断言也是文档以它为线索可以低成本地窥见 roc 编译器各阶段的真实内部表示并进一步扩展阅读 test/snapshots/expr 目录下的其他表达式快照构建起对 roc 表达式语义的系统理解。【免费下载链接】rocA fast, friendly, functional language.项目地址: https://gitcode.com/GitHub_Trending/ro/roc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考