Unison 代码库删除命令全解析:delete 与 delete.force 的边界、歧义处理与依赖保护
Unison 代码库删除命令全解析:delete 与 delete.force 的边界、歧义处理与依赖保护
导读
delete 是 Unison 编程语言(README.md 中描述为 "A friendly programming language from the future")交互式代码库(codebase)中用于移除命名空间(namespace)内定义的命令。它既能删除 term,也能删除 type,同时包含一整套 .force、.term、.type 变体,并内置"防止留下未命名依赖"的依赖检查与临时分支(update branch)机制。本文以官方 transcript 测试文档 delete.md 为骨架,逐场景讲解 delete 系列命令的正确用法、歧义(ambiguity)处理规则、构造器删除限制、批量删除语义,并结合 HandleInput/Delete.hs 等源码揭示其底层实现原理。读完你将能安全、精确地完成任何粒度的代码库清理操作。
一、命令概览:delete 系列及其变体
Unison 命令行编辑器(UCM)中,与删除相关的命令由 InputPatterns.hs 中的 deleteGen 工厂函数统一生成。核心命令及变体如下:
| 命令 | 目标 | 是否强制(force) | 说明 |
|---|---|---|---|
delete |
term 或 type | 否 | 基础删除,会做依赖检查 |
delete.force |
term 或 type | 是 | 无视依赖直接删除,可删构造器与 lib.* |
delete.term |
仅 term | 否 | 只匹配 term 名 |
delete.term.force |
仅 term | 是 | 强制删除 term |
delete.type |
仅 type | 否 | 只匹配 type 名 |
delete.type.force |
仅 type | 是 | 强制删除 type |
从源码看,各命令均接受一个或多个参数(OnePlus ("definition to delete", queryCompletionArg)),并支持 rm、rm.term.force 等别名。参数解析后统一封装为 Input.DeleteI force which targetNames(见 Input.hs),其中:
force:True对应.force变体;which:DeleteTarget'TermOrType/DeleteTarget'Term/DeleteTarget'Type(见 Input.hs),决定匹配 term、type 还是两者皆可。
提示:本文所有交互示例都来自幂等 transcript 测试 delete.md,其中
scratch/main>是 UCM 提示符,update将.u文件中新写入的定义应用到当前分支。
二、删除不存在的名字:报错而非静默
delete 对不存在的名字会直接报错。文档中的第一个场景展示了这一点:
scratch/main> delete.verbose foo
⚠️
I don't know how to delete.verbose. Type `help` or `?` to get
help.
注意这里的 delete.verbose 并不是 delete 的变体,UCM 根本不认识它,因此报的是"未知命令"错误。真正删除不存在的名字时,delete 会报告找不到匹配的 term 或 type(下文"lib 删除"一节有完整示例)。这一行为对应源码中的 Output.TermAndOrTypeNameNotFound(见 HandleInput/Delete.hs),说明 delete 对目标名是零容忍的——宁可报错也不允许误删。
三、基础场景:删除无歧义的 term 与 type
先在 scratch 项目中写入一个 term 和一个 type,update 提交到代码库后逐个删除:
foo = 1
structural type Foo = Foo ()
scratch/main> update
Okay, I'm searching the branch for code that needs to be
updated...
Done.
scratch/main> delete foo
I deleted these terms:
1. foo
Tip: You can use `undo` or use a hash from `reflog` to undo
this change.
scratch/main> delete Foo
I deleted these types:
1. Foo
Tip: You can use `undo` or use a hash from `reflog` to undo
this change.
scratch/main> ls
1. lib. (943 terms, 136 types)
要点:
- 同一命令语法可删 term 也可删 type:
delete foo走 term 分支,delete Foo走 type 分支,输出分别归类为 "I deleted these terms" 与 "I deleted these types"。 - 删除后立即生效:
ls确认foo与Foo均已从命名空间消失,只剩内置的lib.。 - 可撤销:每次删除后都会提示可用
undo或reflog中的哈希回滚(源码对应Output.DeletedDefinitions,见 HandleInput/Delete.hs)。
四、按后缀删除:匹配一切、忽略构造器
delete 支持按名字的后缀匹配,即传入一个短名(如 x)时会匹配命名空间内所有以 x 结尾的名字。例如:
foo.x = 17
bar.x = 18
type Baz = x
type foo.x = y
scratch/main> delete x
I deleted these types:
1. foo.x
I deleted these terms:
2. bar.x
3. foo.x
这里 delete x 一口气删掉了 foo.x(type)、bar.x 与 foo.x(term),而 type Baz = x 中的构造器 x 不会被删除——后缀匹配"ignoring constructors"。文档还特别提醒:这一行为可能很快会改变,届时可能改为直接给出歧义错误(ambiguous-error)。因此不建议依赖"按后缀删除会跳过构造器"这一语义来编写脚本或习惯操作。
源码印证:resolveTarget 通过 HQ'.filterUnconflictedBySuffix 进行后缀匹配(见 HandleInput/Delete.hs),匹配结果再按 Referent.Con(构造器)与 Referent.Ref(term)分拣,构造器不会进入普通 delete 的删除集合。
五、构造器删除限制:delete 不行,delete.force 可以
普通 delete 不能删除构造器。文档用如下例子演示:
type Foo = Foo
scratch/main> delete Foo.Foo
⚠️
I can't delete the constructor Foo.Foo.
You may only delete terms and types with `delete`. Use
`delete.force` instead.
改用 delete.force 后即可删除该构造器:
scratch/main> delete.force Foo.Foo
I deleted these terms:
1. Foo.Foo
Tip: You can use `undo` or use a hash from `reflog` to undo
this change.
scratch/main> ls
1. Foo (type)
2. lib. (943 terms, 136 types)
注意 ls 显示 Foo 这个 type 仍然保留,只有构造器 Foo.Foo 被移除。从源码看,resolveTarget 在遇到"只有构造器匹配"时会直接短路并返回 Output.CantDeleteConstructor(见 HandleInput/Delete.hs),这正是上面报错的来源。源码注释进一步解释了什么场景需要 delete.force 删构造器:例如因"多余的构造器别名"导致声明不一致(incoherent decl),或需要清理 transcript 中的 lib.*(见 HandleInput/Delete.hs)。
六、歧义名称:普通 delete 拒绝执行
当一个名字对应多个定义时,delete 会拒绝执行,必须用 delete.force。文档先用 debug.alias.term.force 制造出歧义:
a.foo = 1
a.bar = 2
scratch/main> update
Done.
scratch/main> debug.alias.term.force a.bar a.foo
Done.
此时 a.foo 同时指向两个 term(a.foo 自身与别名的 a.bar):
scratch/main> delete a.foo
Sorry, I can't do that right now, because there's more than
one term with the name `a.foo`. Please `move.term` or
`delete.term.force` all but one of them, then try again.
错误信息同时给出了两条出路:
move.term:先把其中一份移动到别的名字,消除歧义后再delete;delete.term.force:直接用强制变体删除。
用 delete.force 后,a.foo 的两个版本都被移除("A delete should remove both versions of the term"),ls a 只剩 bar:
scratch/main> delete.force a.foo
I deleted these terms:
1. a.foo
scratch/main> ls a
1. bar (Nat)
文档随后在 type 上完整重复了这一流程:
structural type a.Foo = Foo ()
structural type a.Bar = Bar
scratch/main> debug.alias.type.force a.Bar a.Foo
Done.
scratch/main> delete a.Foo
Sorry, I can't do that right now, because there's more than
one type with the name `a.Foo`. Please `move.type` or
`delete.type.force` all but one of them, then try again.
scratch/main> delete.force a.Foo
I deleted these types:
1. a.Foo
scratch/main> delete.force a.Foo.Foo
I deleted these terms:
1. a.Foo.Foo
delete.force a.Foo 删除歧义 type 后,又用 delete.force a.Foo.Foo 清理了残留的构造器,完整演示了 type 歧义场景下的清理顺序。
七、删除 lib.* 中的内容:只能 delete.force
lib.*(内置库命名空间)默认受保护,普通 delete 甚至找不到其中的名字:
foo = 17
scratch/main> move foo lib.foo.foo
scratch/main> delete lib.foo.foo
⚠️
I couldn't find any terms or types that match the name
lib.foo.foo.
普通 delete 的作用域默认排除 lib(源码中 currentNamespaceSansLib0 = Branch.deleteLibdeps ...,见 HandleInput/Delete.hs),因此对 lib.* 内名字直接报"找不到"。而 delete.force 走的是另一条实现路径(resolveTargetInConflicted,直接操作整个命名空间,见 HandleInput/Delete.hs),可以成功删除:
scratch/main> delete.force lib.foo.foo
I deleted these terms:
1. lib.foo.foo
Tip: You can use `undo` or use a hash from `reflog` to undo
this change.
源码注释明确说:从 lib.* 删除是"我们想劝阻甚至普遍禁止"的操作,delete.force 是唯一途径,主要供 transcript 测试等场景使用(见 HandleInput/Delete.hs)。
八、同名 term 与 type:一次 delete 双双删除
如果 term 与 type 同名,普通 delete 会同时删除两者:
foo = 1
structural type foo = Foo ()
scratch/main> update
+ structural type foo
+ foo : Nat
scratch/main> delete foo
I deleted these types:
1. foo
I deleted these terms:
2. foo
Tip: You can use `undo` or use a hash from `reflog` to undo
this change.
scratch/main> ls
1. lib. (943 terms, 136 types)
注意输出顺序:type 在 term 之前被列出。对应源码中 DeleteTarget'TermOrType 分支会同时收集匹配的 term 与 type(见 HandleInput/Delete.hs)。
九、批量删除:一次传入多个名字
delete 天然支持多参数,可一次删除多个 term:
a = "a"
b = "b"
c = "c"
scratch/main> update
+ a : Text
+ b : Text
+ c : Text
scratch/main> delete a b c
I deleted these terms:
1. a
2. b
3. c
也可在同一次调用中混合删除 term 与 type:
structural type Foo = Foo ()
a = "a"
b = "b"
c = "c"
scratch/main> delete a b c Foo
I deleted these types:
1. Foo
I deleted these terms:
2. a
3. b
4. c
源码层面,deleteGen 的参数类型为 OnePlus ("definition to delete", ...)(见 InputPatterns.hs),即至少一个、可多个,最终 traverse parseArg 后整体封装为一个 DeleteI,在 handleDelete 中通过 foldl' (zipDefnsWith unsafeUnion ...) 合并各名字的匹配结果统一处理(见 HandleInput/Delete.hs)。批量删除是原子的——若其中一个名字解析失败,整个命令会短路报错,什么都不会删(见下文"名字错误短回路")。
十、依赖保护:产生未命名依赖时进入 update 分支
delete 最核心的保护机制是依赖检查:如果删除会让某些仍在命名空间中的定义失去可引用名字(即产生 nameless dependency),命令会被拦截,并转入一个临时 update 分支。
文档示例中 d 依赖 a、b、c:
a = 1
b = 2
c = 3
d = a + b + c
scratch/main> delete a b c
I couldn't complete the delete, because some definitions are
still in use.
I've created a temporary branch and added the affected
definitions to scratch.u, where you can fix them up or remove
any that are obsolete.
Once you're happy with the results, use `update` to merge them
back into main, or `cancel` if you change your mind.
随后 UCM 把受影响的 d 写入 scratch.u,等待你修复:
-- The definitions below depend on the deleted definitions.
-- Please fix the errors and run `update`.
d : Nat
d =
use Nat +
a + b + c
这一流程的源码实现在 handleDelete False 分支(见 HandleInput/Delete.hs):
- 解析目标名字,得到
targetIds; - 用
resolveReferencesToDelete找出"最后一个名字会随删除消失"的引用集合nameless; - 计算这些引用的直接依赖(
directDependentsWithinScope),并剔除同样在删除目标里的定义(zipDefnsWith Set.difference); - 若仍存在不在删除目标中的直接依赖者,说明删除会留下未命名依赖 → 走
Left分支,创建 update 分支并把传递依赖(transitiveDependentsWithinScope)物化到 scratch 文件; - 若删除后没有残留依赖者 → 走
Right分支,直接执行删除。
源码注释还说明:失败的删除之所以命名为 update-* 分支,"是因为它在任何方面都表现得像一个 update 分支",不会让你感到陌生(见 HandleInput/Delete.hs)。
例外一:互相引用的定义可以一次全删
如果所有引用者都在删除目标内,即使它们互相引用也能一次删干净:
e = 11
f = 12 + e
g = 13 + f
h = e + f + g
scratch/main> delete e f g h
I deleted these terms:
1. e
2. f
3. g
4. h
原因正是第 3 步的集合差运算:dependents - targetIds 为空,因此不触发 update 分支。
例外二:类型与其引用函数可一起删除
structural type Foo = Foo Nat
incrementFoo : Foo -> Nat
incrementFoo = cases
(Foo.Foo n) -> n + 1
scratch/main> update
+ structural type Foo
+ incrementFoo : Foo -> Nat
scratch/main> delete Foo incrementFoo
I deleted these types:
1. Foo
I deleted these terms:
2. incrementFoo
incrementFoo 引用 Foo,但只要两者都在删除目标内,delete 即可顺利完成。
例外三:只删循环的一部分会触发 update 分支
ping 与 pong 互相引用:
ping _ = 1 Nat.+ !pong
pong _ = 4 Nat.+ !ping
scratch/main> delete ping
I couldn't complete the delete, because some definitions are
still in use.
I've created a temporary branch and added the affected
definitions to scratch.u, where you can fix them up or remove
any that are obsolete.
Once you're happy with the results, use `update` to merge them
back into main, or `cancel` if you change your mind.
此时 pong 仍引用 ping,删除后 pong 将失去可引用名字,因此 UCM 把 ping、pong 都放入 scratch 文件,等你修复(例如将 pong 也删除)后再 update 或 cancel。
十一、名字错误短回路:整批命令不执行
批量删除时,若任何一个名字无法解析,整个命令立即中止,前面解析成功的名字也不会被删除:
e = 11
f = 12 + e
g = 13 + f
h = e + f + g
scratch/main> delete e f gg
⚠️
I couldn't find any terms or types that match the name gg.
源码中 resolveTarget 对每个名字 traverse 解析,遇到 Nothing 即 returnEarly(见 HandleInput/Delete.hs),Cli.returnEarly 会跳出整个命令,因此不会产生"部分删除"的中间状态。这条规则与"删除会创建未命名依赖时进入 update 分支"共同保证了 delete 的全有或全无语义。
十二、源码级实现小结
把文档中的行为映射到实现,可以得到一张清晰的对照表:
| 文档行为 | 源码位置 | 机制要点 |
|---|---|---|
| 支持 term/type/两者 | Input.hs | DeleteTarget'TermOrType / 'Term / 'Type |
| 后缀匹配、忽略构造器 | HandleInput/Delete.hs | HQ'.filterUnconflictedBySuffix + Referent.Con 分拣 |
| 不能删构造器 | HandleInput/Delete.hs | Output.CantDeleteConstructor 短路 |
| 歧义拒绝删除 | HandleInput/Delete.hs | 匹配到多个引用时触发歧义错误 |
| lib 不可普通删除 | HandleInput/Delete.hs | Branch.deleteLibdeps 排除 lib |
| 依赖保护 → update 分支 | HandleInput/Delete.hs | directDependentsWithinScope / transitiveDependentsWithinScope + 临时分支 |
| force 直接删除 | HandleInput/Delete.hs | resolveTargetInConflicted + makeDeleteActionsForConflicted |
非 force 路径只作用于**无冲突(unconflicted)**视图(Branch.asUnconflicted,冲突时返回 Output.ConflictedDefn),而 delete.force 则能直接处理含冲突名的命名空间(见 HandleInput/Delete.hs 对 resolveTargetInConflicted 的注释)。此外,handleDelete 还禁止在 update/upgrade/merge 进行中执行删除(CantDoThatDuring,见 HandleInput/Delete.hs),并要求声明保持一致(incoherent decl 会触发 IncoherentDeclDuringDelete,见 HandleInput/Delete.hs)。
十三、撤销与最佳实践
每次删除后 UCM 都会提示:
Tip: You can use
undoor use a hash fromreflogto undo this change.
undo:回滚最近一次操作;reflog:查看历史操作哈希,可精确回滚到任意一次删除之前的状态;- 若删除触发了 update 分支,可在确认修复结果后
update合并回主分支,或cancel放弃。
实操建议(均可在 delete.md 中找到对应演示):
- 能用
delete就别用delete.force:普通delete的依赖检查能防止你把命名空间"删坏"; - 清理残留引用:删除 type 时,把引用它的函数放进同一次
delete调用,可避免误入 update 分支; - 批量删除注意名字拼写:任何一个名字解析失败都会导致整批命令短路;
lib.*与构造器:只有delete.force能处理,属于刻意保留的逃生通道,日常应避免直接操作内置库。
结语
delete 系列命令的设计折射出 Unison 代码库管理的核心哲学:删除不只是"移除一个名字",更是对依赖图、命名空间一致性与可撤销性的综合操作。普通 delete 提供"全有或全无"的原子语义与依赖保护,delete.force 则作为明确的逃生通道处理构造器、歧义名与 lib.* 等特殊情况。理解 delete 与 delete.force 的分工,是安全驾驭 Unison 交互式代码库的基本功。