重构
概述
clice refactor 根据持久化索引改写项目的源代码,读取的正是 clice query 所用的同一份索引。整个过程无需编译,因此在大型源码树上执行一次重构的耗时与一次查询相当。它提供的重构只有 rename;编辑器中的重命名运行的也是同一个引擎。
用法:clice refactor rename (<locator> <new-name> | --spec <file>) [--workspace <dir>] [--configuration <tag>] [--dry-run] [--fresh]
重命名
符号由定位符(locator)指明,写法与 clice query 接受的相同:可以是区分大小写、一字不差的名称,也可以是传回的 symbol(取自 clice query 的答案),或源码位置 file:line[:column]。与编辑器的光标一样,位置落在模板中依赖模板参数的名称上时,重命名的是各个实例化将该名称解析到的符号;若不同实例化将其解析到分属不同重命名目标的符号,或没有任何实例化被索引,则会拒绝重命名。近似匹配或通配模式不能用来指定改写整个项目的目标。同一作用域内的多个重载共用该名称时,写出名称会将它们全部重命名;传入其中某一个重载的 symbol 则只重命名那一个。其他多个不同符号共用该名称时,会将它们列在 candidates 中。
重命名会修改索引关联到该符号的每一处声明、定义和引用,以及必须与它保持同名的符号:
- 类的构造函数与析构函数——重命名构造函数也会重命名其所属的类;
- 模板的显式特化与偏特化,以及类模板的推导指引(deduction guides);
- 基类与派生类中与该虚函数关联的各个重写函数。
在模板中,依赖模板参数的名称(value.print()、T::type)在索引保存的实例化将其解析为该符号时会被重命名,没有任何实例化被索引时则会列出供检查。若一个实例化将其解析为该符号,另一个实例化却将其解析为另一个同名符号,该名称既不能改也不能保留:重命名会就此停止,除非批量重命名清单把两者改成同一个新名称。若某次调用的候选重载由模板自身的名称查找即可找到(compute(value)),只要这些重载全在本次重命名之列,无论是否实例化过,该调用都会被重命名。
运算符、转换函数、用户定义字面量、在系统头文件中声明的符号,以及每一处声明都由宏拼出的符号,均无法重命名。新名称必须是合法标识符,且不能是 C 或 C++ 的关键字;使用保留给实现的名称(__x、_X,以及全局作用域中的 _x)会产生警告。
宏
宏名在每个能看到它的翻译单元中都是同一个名字,因此重命名宏会把彼此关联的各处定义一起重命名:定义或使用该宏的文件中它的每一个 #define——包括 #if 的各个分支、#undef 之后的重定义——以及该宏的使用在别处解析到的定义,例如在另一组宏定义下编译的头文件,或是宏体引用了由各文件自行定义的配套宏(如 DEBUG_TYPE 与 LLVM_DEBUG)。其他库中的同名宏保持不变。重命名会修改它的各处使用(无论直接写出还是作为其他宏的实参)、检测它的 #ifdef、#ifndef 和 defined、它的 #undef、展开后会拼出它的其他宏的宏体,以及在定义或使用它的文件中,没有任何定义能够到达却写有该宏名的指令:保护默认定义或头文件的 #ifndef,以及位于构建未启用分支中的 #define。
由编译命令或编译器定义的宏(-DNAME、__GNUC__),或由系统头文件定义的宏,均无法重命名;若在本次重命名要修改的某处使用上,该宏被某个翻译单元的编译命令覆盖,同样无法重命名。宏的新名称不能与项目中任何作用域内的符号、宏或 #ifdef 重名,否则宏展开会将其替换。defined 不能用作宏名。
一次执行多项重命名
--spec <file> 会在一次运行中完成清单文件列出的全部重命名:索引只读取一次,因此跨越数百个名称的术语清理耗时与单次重命名相当,而且索引只需在结束后更新一次,不必在两次重命名之间反复更新。传入 - 会从 stdin 读取清单。每行格式为 <locator> => <new name>;空行和以 // 开头的行会跳过。单行匹配到多个符号本身即视为错误,因此清单最好用 symbol(取自 clice query 每条答案所附的字段)来编写:
// row → variant, flavor → kind
#645572aaecc8aada => VariantHash
::clice::index::RowSource => IndexSource
JoinFlavor => JoinKind所有重命名同时生效,每个定位符指明的都是任何重命名发生之前索引中的符号:A => B 与 B => C 并列时,会把原有的 B 改为 C,两个名称也可以直接互换。每个新名称都会与整份清单执行后留下的名称做冲突检查——已被另一行改走名称的符号不再与之冲突,而两行将同一作用域内的符号改成相同名称则会冲突。同时指向两个被重命名符号的 Token(例如模板中在两个重载之间悬而未决的调用),在两者改成同一新名称时会一起修改,改成不同名称时则会终止整份清单。若某一行重命名的符号已被前面的行重命名过,新名称相同时只规划一次,不同时则判为冲突。
清单要么全部执行,要么全不执行:只要有一行未能指明符号、任一行存在冲突,或遇到过期文件,整份清单都会停止,不会写入任何内容。遇到未指明符号的行或冲突时,修正清单后重新运行即可:由于未写入任何改动,索引依然与磁盘一致。遇到过期文件则需先重新建立索引,传入 --fresh 即可完成。
答案
答案与查询命令一样是一个 JSON 对象 {"result": ..., "stale": [...]},单次重命名与清单重命名的返回格式相同:
renames为请求的每项重命名各给出一项,包含其在清单中的line、原样保留的locator、找到的符号(name、kind、symbol)、目标newName以及修改的 Token 数量edits。若定位符未能指明可重命名的符号,error会说明原因,匹配到多个符号时还会附上candidates。warnings不会阻止重命名:新名称与同一作用域内的函数构成重载,或是保留给实现的名称;构建中尚有翻译单元未建立索引,其中引用的名称未被重命名。conflicts则会阻止该项重命名:新名称已在同一作用域中声明、本身是一个宏、在重命名宏时与项目中的任一符号或#ifdef重名、与同一函数的参数或标签重名、与基类或派生类的成员重名、与被重命名成员所属的类重名,或与被重命名类的成员重名;要修改的某个 Token 在另一处实例化或另一种构建配置下还指向另一个同名符号;重命名会修改项目以外的文件;两个命名空间会合并为一个;前面的某一行已将该符号重命名为另一个名称;要修改的某个 Token 同时指向被另一行重命名为其他名称的符号。files列出每个文件中被替换的 Token,附带从 1 开始的行号与字节列号,以及各处从name替换为newName的名称。unconfirmed列出索引关联到旧名称name、但由于单凭字面代码无法确定所指对象而保持原样的位置:#define的宏体(在另一次展开中可能指向别的符号)、展开后拼出该名称的宏或由##拼接而成的宏名、模板中没有任何已索引实例化将其解析到该符号的名称、模板中可能选中另一个同名重载的调用,以及在重命名宏时,既不定义也不使用该宏的文件里没有任何定义能够到达却写有该宏名的指令。构建前请先逐一检查。conflicts会阻止整批重命名:两个重命名项试图把同一个 Token 改成不同的名称,或某个文件无法改写。stale列出本次重命名要修改、或写有旧名称与新名称,但文本在建立索引后已发生更改的文件。这些文件同样会阻止重命名;--fresh会先为它们重新建立索引。
重命名成功写入文件,或在 --dry-run 下成功生成计划时,退出码为 0;因错误、冲突或过期文件而停止时,退出码为 1。选项或清单内容无法解析时返回 {"error": "..."}(清单错误会指明出错行号),退出码为 1;命令行参数本身无法解析,或无法读取项目及其索引时,退出码为 2。
写入
不带 --dry-run 时,命令会在计算出所有新文本后再写入文件:只要有任何文件的文本在生成计划后发生了变化,整个重命名就会在写入任何内容前停止。每个文件均原地改写,保留原有的字节顺序标记(BOM)、换行符和文件权限;遇到无法写入的文件(如只读文件或磁盘已满)时,重命名会立即停在该处,并在错误信息中列出已经改写的文件。
只有项目内的文件会被修改:隐藏目录、缓存目录和构建目录(含有 CMakeCache.txt 或 build.ninja 的目录)均排除在外;只要索引记录了位置,修改可以落在任意后缀名的文件中。重命名只读取索引、要修改的文件以及建立索引后发生更改的文件,从不扫描项目的其余部分:索引未关联到任何符号的文本既不会重命名,也不会列出——包括被 #if 排除的代码、从未展开过的 #define 宏体,以及构建中没有任何翻译单元编译或包含的文件。重命名后请在项目中搜索一遍旧名称。
命令直接读取磁盘,看不到编辑器中未保存的缓冲区。请先保存文件,或直接在编辑器中执行重命名。
在编辑器中
编辑器中的重命名会选中光标下的名称,或说明该处的符号为何无法重命名。它读取已打开的缓冲区而非磁盘,返回的编辑操作带有对应缓冲区的版本号。遇到冲突或过期文件时会返回指明具体项的错误;警告和保持原样的位置则通过消息提示显示。
示例
重命名符号
试运行会展示修改计划,正式运行则会写入文件。
先规划,再写入
试运行只列出修改项而不写入磁盘,正式运行则会改写文件
--dry-run 会按文件列出重命名将修改的每一处名称,以及保持原样、留待人工核对的位置:CALL 的宏体写有 compute,但宏体中的名称实际指向什么取决于每次展开的上下文。不带 --dry-run 时则会直接改写文件。重命名类时,其构造函数也会重命名。
有歧义的名称
多个符号共用的名称不会触发任何重命名,直到用定位符选定其中一个。
指明有歧义的符号
对应两个符号的名称会将两者都列出,使用带作用域的名称或候选的 symbol 即可选定其一
名称存在歧义时不会执行任何重命名。每个候选都带有可直接原样传回的 symbol。
批量重命名
一份重命名清单可在单次运行中完成规划与写入。
一次重命名整份清单
在文件中按每行一条 <symbol> => <new name> 列出重命名项,即可在一次运行中全部完成
每一行都基于同一份索引统一规划,文件只写入一次,所有重命名要么全部完成,要么全不执行。空行和以 // 开头的行会跳过。
已知限制
- 检查均为静态检查:索引无法察觉的语义变化——实参依赖查找(argument-dependent lookup)匹配到了另一个函数、同名新成员截获了类内的某处使用、函数内同名局部变量或模板参数与重命名后的符号冲突或将其遮蔽、某个重载无法与重命名后的函数共存——都不会报错。重命名后请执行一次构建。
- 读取项目宏的系统头文件(例如读取
NOMINMAX的windows.h)只有在某个已索引翻译单元包含该头文件时,才会阻止该宏的重命名;经#字符串化的宏名会保留原有拼写。宏的新名称只会与名称搜索能找到的符号以及被修改文件中出现的名称比对:其他文件中同名的局部变量或参数不会被察觉。 - 编辑器中的重命名只根据当前文件所属项目的索引执行修改;同一编辑器中打开的其他项目里对该符号的使用保持不变。
