Unison 项目 `transcripts-using-base` 前奏(Prelude)文档剖析:`_base.output.md` 的构建、作用与测试工作流
Unison 项目 transcripts-using-base 前奏(Prelude)文档剖析:_base.output.md 的构建、作用与测试工作流
导读
_base.output.md 是 Unison 语言仓库中 unison-src/transcripts-using-base/ 目录下前奏(prelude)脚本的可执行转录(transcript)输出,它展示了如何通过一条 ucm 命令加载一个精简版 base 库、注册测试辅助函数,并用内置测试框架验证这些辅助函数的行为。本文以该文件为骨架,结合仓库中的 base.u、Transcripts.hs 等源码,深入讲解该前奏的作用、加载方式、辅助函数设计意图以及转录测试的运作机制,帮助你理解 Unison 项目中“转录驱动开发”的测试工作流。
1. 文档定位:这是一个可执行的“前奏”
_base.output.md 对应的是 _base.md 的运行输出,两者共同构成 Unison 生态中一种特殊的测试工具——转录(transcript)。转录文档既是人类可读的说明文档,也是机器可执行的测试用例;ucm 会逐块执行其中的代码块,并将执行结果以 +/- 增删标记的形式写回 .output.md 文件。
从源码看,Transcripts.hs 在测试套件中通过 buildTests config (testBuilder False False recordFailure) ("unison-src" </> "transcripts-using-base") Nothing 来运行该目录下所有转录;而 README 明确说明这些转录仅在“新运行时(new runtime)”下运行,这是该目录测试的前提条件。
_base 的定位在文档开头写得很清楚:它被设计为其他转录的前奏(prelude)——预先注入辅助函数和一个精简版 base 子集,让后续转录文件减少样板代码(boilerplate),专注于各自要测试的主题。
2. Usage 一节:前奏的加载与自检
_base.output.md 的 Usage 部分演示了前奏本身的加载方式,分为两步:先通过 ucm :hide 块静默执行三条命令完成环境准备,再通过 unison :hide 块注册一个自检测试。
2.1 前奏加载三步曲
> builtins.mergeio
> load unison-src/transcripts-using-base/base.u
> add
builtins.mergeio:将io2.IO相关的内置定义合并进当前代码库。新运行时要求先注入 IO 能力(capability)相关的 builtin,后续的getArgs、printText、readFile等辅助函数才可用。load unison-src/transcripts-using-base/base.u:加载该目录下的 base.u 文件,解析其中的定义。注意这里的load只是“解析 + 暂存”,尚未写入代码库。add:将暂存的定义正式加入代码库(branch)。
由于 _base 被设计为其他转录的前奏,这三个步骤在 ucm :hide 块中执行,输出会被隐藏,不会污染后续转录的输出格式。
2.2 自检:验证 hex/fromHex 的往返一致性
test> hex.tests.ex1 = checks let
s = "3984af9b"
[hex (fromHex s) == s]
这条定义使用 checks 辅助函数,断言 hex (fromHex s) == s。这正是 base.u 中 checks 与 hex/fromHex 组合的意义:
hex : Bytes -> Text将字节转为 Base16 文本;fromHex : Text -> Bytes将 Base16 文本还原为字节;checks : [Boolean] -> [Result]将所有布尔断言汇总为[Result]——全部为真则返回[Ok "Passed"],否则返回[Fail "Failed"]。
这个测试验证的是“编码→解码”的往返(round-trip)性质:对任意合法的十六进制字符串 s,hex (fromHex s) == s 必须恒成立。测试通过 test 命令执行,由于它位于 :hide 块内,正常输出的测试结果不会出现在转录中——这解释了为什么 .output.md 中看不到这次自检的打印结果。
3. 前奏提供的能力全景:base.u 源码解析
_base.output.md 的正文只展示了 testAutoClean 一个示例,但它背后依赖的前奏能力全部来自 base.u。理解 _base 的完整价值,需要看这份源码。可以按功能划分为以下几组:
3.1 管道与组合子
a |> f = f a
f <| a = f a
compose f g = a -> f (g a)
compose2 f g = a -> b -> f (g a b)
compose3 f g = a -> b -> c -> f (g a b c)
id a = a
void x = ()
这些是编写无样板转录的基础工具:|> / <| 提供管道式调用,compose/compose2/compose3 用于把 .impl 风格的 IO 包装函数组合成带 Exception.reraise 的“干净”接口(见 3.5 节)。
3.2 异常(Exception)能力
structural ability Exception where
raise: io2.Failure -> anything
base.u 以**能力(ability)**的方式定义了 Exception,并提供了 Exception.catch、Exception.toEither、Exception.unsafeRun!、Exception.reraise 等便捷接口。这套设计与仓库中 Exception.raise (Failure _ t _) 的用法(见 _base.output.md 的 testAutoClean)呼应:转录作者可以像对待普通异常一样编写测试,而 runTest/evalTest 会在外层统一捕获失败并转成 [Fail t] 结果。
3.3 结果与测试辅助:check / checks / expect / Stream
check: Text -> Boolean -> {Stream Result} ()
checks : [Boolean] -> [Result]
expect : Text -> (a -> a -> Boolean) -> a -> a -> {Stream Result} ()
expectU : Text -> a -> a -> {Stream Result} ()
check 和 checks 是最常用的断言原语,expect/expectU 提供期望值比较。它们都通过 Stream 能力输出结果:Stream.emit 一个 Result(Ok 或 Fail),由 Stream.toList 或 Stream.collect 处理器收集。这正是 _base.output.md 中 io.test testAutoClean 输出“◉”符号列表的原因——每个 ◉ 对应一次 emit。
3.4 临时目录与自动清理:TempDirs + autoCleaned
structural ability TempDirs where
newTempDir: Text -> Text
removeDir: Text -> ()
这是 testAutoClean 的核心能力。autoCleaned.handler 在计算结束时遍历已创建目录并逐个 removeDirectory.impl 清理,即使中途抛异常也不会残留。这种设计对“需要与文件系统交互的 IO 测试”尤其有价值——转录作者无需手动删除临时目录。
3.5 IO 包装层:reraise + compose
base.u 中大量形如 readFile = compose reraise readFile.impl 的定义,把内置的 *.impl 函数(它们返回 Either Failure)统一包装成“可直接调用、失败即抛异常”的版本。这一模式贯穿文件、目录、网络、TLS、MVar 等全部 IO 能力,让转录代码保持简洁。
3.6 序列化与自包含测试基础设施
saveSelfContained / loadSelfContained / saveTestCase / cache 以及 Code.transitiveDeps / Value.transitiveDeps 构成序列化测试的底层工具。saveTestCase 会把测试用例连同依赖写入 serialized-cases 目录(.ser 与 .hash 文件),供 random-deserial、serial-test-* 等转录回放验证。这解释了为什么该目录中既有大量 serial-test-*.md/.output.md,又有 case-*.v4/v5.ser 与 .hash 文件。
3.7 二分查找与依赖爬取
bSearch / bSplit / bInsert / bSort 系列函数把“按 a 值排序的关联列表”当作简易 map 使用,是 crawl(传递依赖搜索)和 Map 类型(Bin Nat k v 结构)的基础。Code.transitiveDeps 从 Link.Term 出发沿 Code.dependencies 递归收集传递依赖,并主动跳过以 ## 开头的 builtin 链接——因为 builtin 无需也不能被可靠地序列化传输。
4. 转录测试的运作机制(源码佐证)
_base.output.md 之所以能以“文档 + 执行结果”的双重身份存在,根源于 Transcripts.hs 中的转录构建器:
- 测试入口
test config会依次对多个目录调用buildTests,其中就包含("unison-src" </> "transcripts-using-base")(Transcripts.hs); - 每个
.md文件被视为一个转录,逐代码块交给ucm执行,再将输出与既有.output.md比对;不一致即视为测试失败,从而把文档本身变成回归测试; cleanup会把执行后残留的transcript-*目录(失败转录的输出目录)移动到test-output/下,便于人工排查。
这也意味着:转录的 .output.md 不是手工编写的,而是由测试框架自动生成/校验的。_base.output.md 中 :added-by-ucm 标记的代码块(+ testAutoClean : '{IO} [Result] 与“Run update to apply these changes”提示)正是 ucm 检测到暂存区改动后自动注入的输出片段——它是转录机制真实运行的直接证据。
5. testAutoClean 的逐段解读
_base.output.md 的核心示例 testAutoClean 旨在验证自动清理能力是否真的生效,可拆解为三层:
- 测试体(
go):调用newTempDir "autoclean"创建带前缀autoclean的临时目录,用check "our temporary directory should exist" (isDirectory dir)断言目录存在,并把dir作为返回值传出。 - 执行层(
evalTest go):evalTest先用Stream.collect.handler收集所有emit的Result,再用autoCleaned.handler处理TempDirs请求;autoCleaned在计算完成后统一删除已创建目录。 - 断言层(
match ... with cases):- 若抛
Exception.raise (Failure _ t _),则返回[Fail t]; - 若正常返回
(results, dir),则再次检查io2.IO.isDirectory.impl dir——此时目录应当已被自动清理,即Right b为false。若仍存在则追加Fail "our temporary directory should no longer exist",否则追加Ok同名断言。
- 若抛
从 .output.md 的执行结果看,io.test testAutoClean 输出了两个 ◉(一个对应“创建后存在”,一个对应“清理后不存在”),最终 ✅ 2 test(s) passing。这个测试以最小成本验证了前奏基础设施的两个关键承诺:TempDirs 能创建目录、autoCleaned 能确保清理。
6. 与其他转录的协作关系
_base.output.md 不是孤立文件,它与 transcripts-using-base 目录构成一个整体:
- 以
_开头的_base.md是“前置转录”,其余*.md转录(如run-watch.md、failure-tests.md、hashing.md、mvar.md、utf8.md等)在运行时已具备_base注入的全部能力; run-watch.md演示的run>watch 可以强制'{IO, Exception} a惰性块并真正执行 IO(写入临时文件再读回),其临时文件机制正是借助autoCleaned;failure-tests.md验证 builtin 产生的Failure会正确地通过Exception能力上报(io.test对抛错测试输出:error标记);all-base-hashes.md通过find.verbose把所有 builtin/定义连同哈希完整列出,用于暴露哈希算法的意外变动;serialized-cases/下的case-*.v4/v5.ser与.hash是序列化回放测试的持久化用例,对应saveTestCase的产物。
换言之,_base 是这些转录共享的“测试工具箱”,而 _base.output.md 就是这套工具箱的验收报告。
7. 实战:如何亲自运行这段转录
- 前置条件:使用新运行时(目录
README明确要求Transcripts in this directory are only run using the new runtime),且已构建ucm可执行文件; - 运行方式:
ucm支持直接加载转录目录执行测试,或在ucm会话中依次执行builtins.mergeio→load unison-src/transcripts-using-base/base.u→add,然后运行io.test testAutoClean复现文档中的✅ 2 test(s) passing; - 校验方式:重新执行后若输出与
_base.output.md不一致,会被 Transcripts.hs 的转录比对机制判定为失败——这正是该文件既是文档、又是回归测试的意义所在。
结语
_base.output.md 通过一个可复现的执行记录,完整展示了 Unison “转录即测试”的开发范式:以 base.u 提供精简能力库与测试辅助,以 ucm 转录机制自动执行并校验输出,以 testAutoClean 这类自检测试验证基础设施自身的正确性。理解这份文件,就等于拿到了阅读 unison-src/transcripts-using-base/ 下全部转录的钥匙——后续每一份转录的简洁代码,背后都是 _base 前奏默默注入的整套测试工具。