Roc 语言 `List.ends_with` 空后缀语义与 REPL 快照测试解析

原创2026-09-19 19:38:481,832 阅读

Roc 语言 List.ends_with 空后缀语义与 REPL 快照测试解析

导读

本文以仓库中的 REPL 快照测试 list_ends_with_empty_suffix.md 为切入点,深入剖析 Roc 标准库中 List.ends_with 的边界行为——任何列表都以空列表结尾(恒为 True)——并结合 Builtin.roc 中该函数的真实实现、List.take_last 的底层逻辑以及 snapshot_tool 的 REPL 快照执行机制,说明这一语义是如何被定义、被验证并被自动化测试锁定的。读完本文,你将理解 Roc 列表后缀匹配的完整语义边界,并掌握 REPL 快照测试文件的格式与运行方式。

一、关联快照文件逐段解剖

原始快照文件 test/snapshots/repl/list_ends_with_empty_suffix.md 全文仅四段,但它是一份结构完整的 REPL 快照测试,每段都有明确含义:

# META
~~~ini
description=List.ends_with with an empty suffix is always True (every list ends with the empty list)
type=repl
~~~
# SOURCE
~~~roc
» List.ends_with([1, 2, 3], [])
~~~
# OUTPUT
True
# PROBLEMS
NIL

META 段:测试元信息

description 字段用一句话描述该测试的意图:"List.ends_with with an empty suffix is always True (every list ends with the empty list)"——空后缀时 List.ends_with 恒为 True,因为每个列表都以空列表结尾。type=repl 声明这是一个 REPL 会话类快照,快照工具会根据该字段走独立的 REPL 处理分支。在 src/snapshot_tool/main.zig 中可以看到,当 content.meta.node_type == .repl 时会转入 processReplSnapshot,与普通 .file、.snippet、.expr 等快照走完全不同的流水线。

SOURCE 段:REPL 输入

SOURCE 中的 » 是 Roc REPL 的提示符,其后跟随用户键入的表达式:

» List.ends_with([1, 2, 3], [])

快照工具解析 SOURCE 时会以 » 为分隔符切分多个输入步骤,逐条送入 REPL 会话求值(见 generateReplOutputSection 中对 std.mem.splitSequence(u8, content.source, "»") 的使用)。每条输入由 snapshotReplStep 判定其输入类型(定义、表达式或语句表达式)后交给求值器执行。

OUTPUT 段:期望输出

本用例的期望输出为单个布尔值:

True

如果 REPL 输入包含多个步骤,OUTPUT 段中每个步骤的输出会以独立的一行 --- 分隔,且保持位置一一对应(即使某一步没有产生输出也会保留空位,见快照工具对期望输出的按行解析逻辑)。

PROBLEMS 段:编译诊断

NIL 表示本次 REPL 表达式在解析、类型检查与求值全过程中没有产生任何编译诊断。List.ends_with([1, 2, 3], []) 是类型完全合法的表达式:参数列表为 List(U64)(整数字面量在 REPL 中按未绑定数字类型推断),空列表 [] 与 [1, 2, 3] 推导为同一元素类型,满足 ends_with 的签名约束。

二、List.ends_with 的语义定义与空后缀保证

快照中验证的行为并非巧合,而是由 Roc 标准库中的真实实现明确保证的。在 src/build/roc/Builtin.roc 中,List.ends_with 的定义如下:

## Returns `Bool.True` if the first list ends with the second list.
##
## If the second list is empty, this always returns `Bool.True`; every list
## is considered to "end with" an empty list.
##
## If the first list is empty, this only returns `Bool.True` if the second list is empty.
ends_with : List(a), List(a) -> Bool where [a.is_eq : a, a -> Bool]
ends_with = |list, suffix|
    suffix == List.take_last(list, List.len(suffix))

这条实现浓缩了三个关键语义点:

  1. 空后缀恒为 True:当 suffix == [] 时,List.len(suffix) 为 0,List.take_last(list, 0) 返回空列表,[] == [] 恒成立,因此任何列表(包括空列表)ends_with [] 都为 True。这正是本次快照 List.ends_with([1, 2, 3], []) 输出 True 的根源。

  2. 空列表只有以空列表结尾时才为 True:当 list == [] 而 suffix 非空时,List.take_last([], n)(n > 0)返回空列表,非空 suffix 与空列表不相等,结果为 False。

  3. 相等性约束:签名中的 where [a.is_eq : a, a -> Bool] 声明了列表元素必须支持 is_eq 相等比较,这意味着 ends_with 可用于任意元素类型可比较的列表——整数、字符串、记录、乃至嵌套列表。

底层:take_last 与 sublist

ends_with 的核心计算委托给了 List.take_last,其实现位于 Builtin.roc:

take_last : List(a), U64 -> List(a)
take_last = |list, n| {
    len = List.len(list)
    start = if (len <= n) 0 else len - n
    List.sublist(list, { start: start, len: len })
}

注意这里的关键设计:start = if (len <= n) 0 else len - n。当请求的 n 不小于列表长度时,start 直接归零,返回整个列表;否则从 len - n 处开始截取。对 ends_with 而言:

  • suffix 比 list 长时,take_last 返回整个 list,此时只有 suffix 恰好等于整个 list 才可能返回 True;
  • suffix 长度正常时,take_last 精确截取 list 尾部与 suffix 等长的子序列,再通过 == 比较内容。

而 take_last 又建立在 List.sublist 之上(sublist : List(a), { start : U64, len : U64 } -> List(a),见 Builtin.roc),即从 start 开始取 len 个元素。整条调用链——ends_with → take_last → sublist——全部是纯函数式实现,不涉及任何可变状态。

三、与 List.starts_with 的对称设计与快照对照

List.ends_with 与 List.starts_with 在标准库中是对称实现的。starts_with 定义于 Builtin.roc:

## Returns `Bool.True` if the first list starts with the second list.
##
## If the second list is empty, this always returns `Bool.True`; every list
## is considered to "start with" an empty list.
##
## If the first list is empty, this only returns `Bool.True` if the second list is empty.
starts_with : List(a), List(a) -> Bool where [a.is_eq : a, a -> Bool]
starts_with = |list, prefix|
    prefix == List.take_first(list, List.len(prefix))

两者结构完全同构:starts_with 使用 List.take_first(实现见 Builtin.roc 中 take_first = |list, n| List.sublist(list, { len: n, start: 0 }))取头部,ends_with 使用 List.take_last 取尾部,然后都用 == 与目标子列表比较。

这一对称性在 REPL 快照中也有成对验证:

快照文件 输入 输出
list_starts_with_empty_prefix.md List.starts_with([1, 2, 3], []) True
list_ends_with_empty_suffix.md List.ends_with([1, 2, 3], []) True
list_ends_with.md List.ends_with([1, 2, 3, 4], [3, 4]) True
list_ends_with_no_match.md List.ends_with([1, 2, 3], [9, 9]) False

从这些快照可以归纳出完整的边界行为矩阵:

  • 后缀匹配:[3, 4] 是 [1, 2, 3, 4] 的后缀 → True;
  • 空后缀:[] 是任何列表的后缀 → True(本文主题);
  • 不匹配后缀:[9, 9] 不是 [1, 2, 3] 的后缀 → False;
  • 对称地,空前缀也是任何列表的前缀 → True。

四、REPL 快照测试的运行机制

为什么用 REPL 快照验证库函数

List.ends_with 这类行为不仅由标准库实现保证,还通过 REPL 快照形成回归防线:一旦实现对空后缀的语义发生偏移,zig build run-snapshot-tool 的校验就会失败。快照体系在 test/snapshots/README.md 中有总览说明——快照测试通过固定各编译阶段(词法、解析、规范化、类型检查乃至求值)的输出来检测编译器行为的不期望变化,NIL 表示编译未产生任何诊断报告。

常用命令

根据 test/snapshots/README.md 的 Usage 一节:

# 生成/校验全部快照
zig build run-snapshot-tool

# 更新单个快照文件
zig build run-snapshot-tool -- test/snapshots/repl/list_ends_with_empty_suffix.md

# 用实际输出刷新期望值(OUTPUT 段)
zig build run-snapshot-tool -- test/snapshots/repl/list_ends_with_empty_suffix.md --update-expected

# 调试 REPL 求值过程(仅适用于 type=repl 的单个快照)
zig build run-snapshot-tool -- test/snapshots/repl/list_ends_with_empty_suffix.md --trace-eval

其中 --trace-eval 会开启解释器逐步骤追踪,方便观察 List.ends_with 调用 take_last、sublist 时求值器内部的执行路径;调试构建默认开启追踪,release 构建需通过 -Dtrace-eval=true 显式启用。

快照工具内部流程

从源码看,一个 REPL 快照的生成流程大致为(对应 processReplSnapshot):

  1. 输出 HTML 包装(可选)与 META、SOURCE 段落;
  2. 调用 generateReplOutputSection:以 » 拆分 SOURCE 得到若干输入步骤;
  3. 每步输入经 snapshotReplStep 判定类型(定义 / 表达式 / 语句表达式)后送入 REPL 会话求值;
  4. 将实际输出与 OUTPUT 段逐条比对(--check-expected 模式下不一致即判失败),或写入新输出(--update-expected);
  5. 生成 PROBLEMS 段,记录编译诊断的规范化序列化结果。

同一目录下共 308 个 REPL 快照文件,覆盖列表、字典、字符串、数值、Result(rc_*)、Range、闭包、for 循环等主题,构成了一套针对解释器求值行为的系统性回归测试网。

五、实战应用:在 Roc 代码中使用 ends_with

理解空后缀语义后,可以放心地在业务代码中依赖这一行为。典型场景如扩展名判断、路径后缀匹配、协议头检测:

# 判断路径是否以指定目录结尾(suffix 可为空列表,此时恒为 True)
is_in_dir : List(Str), List(Str) -> Bool
is_in_dir = |path, dir_parts|
    List.ends_with(path, dir_parts)

# 结合 starts_with 做双端匹配
matches_both_ends : List(U64), List(U64), List(U64) -> Bool
matches_both_ends = |xs, prefix, suffix|
    List.starts_with(xs, prefix) && List.ends_with(xs, suffix)

调用 List.ends_with 时需要注意元素类型的相等性:ends_with 签名要求 a.is_eq 约束,因此列表中元素必须支持相等比较;此外 ends_with 是纯函数(无副作用、无 ! 效果标记),可在 expect 断言与纯函数上下文中自由使用。空后缀恒为 True 这一约定也意味着:如果业务上需要"后缀必须非空",应在调用前自行用 List.is_empty 判断,而不是依赖 ends_with 的结果。

六、总结

一份 13 行的 REPL 快照 list_ends_with_empty_suffix.md,背后连接着三件事:

  • 标准库语义:List.ends_with 在 Builtin.roc 中被明确定义为空后缀恒为 True,实现委托给 List.take_last 与 List.sublist,并与 List.starts_with 保持完全对称;
  • 求值验证:type=repl 快照由 snapshot_tool/main.zig 的 REPL 流水线逐条求值并比对输出,NIL 表明该表达式全程无编译诊断;
  • 回归保障:zig build run-snapshot-tool 持续校验该行为,任何破坏空后缀语义的改动都会被测试网拦截。

这也是 Roc 项目"以快照驱动编译器正确性"工程哲学的缩影:把语言语义写进标准库源码,再把语义的每个边界条件固化为一组可机械校验的 REPL 快照,让 True 这个看似简单的答案拥有完整的证据链。

登录后查看全文
roc