Clang的重构引擎

展示如何使用重构API中的各种原语来实现不同的重构.
LibTooling库提供了几个在开发重构操作时,使用的其他API.

可用重构引擎来实现,用编辑器或IDE中的选择启动的本地重构.可结合AST匹配器和重构引擎,以实现不适合源选择和/或必须查询某些指定节点的AST的重构.

假定基本了解了ClangAST.更多见ClangAST简介.

介绍

Clang的重构引擎定义了一组重构操作,来实现许多不同的源转换.clang-refactor命令行工具可用来重构.

其他如文本编辑器和IDE也用这些重构.

重构操作是一个定义了相关重构操作(规则)列表的类.在共同的单个clang-refactor命令下,分组这些规则.
除了规则外,重构操作还向clang-refactor提供操作的命令名和描述.每个操作都必须实现RefactoringAction接口.
下面是本地重命名操作的大概:

class LocalRename final : public RefactoringAction {
public:StringRef getCommand() const override { return "local-rename"; }StringRef getDescription() const override {return "Finds and renames symbols in code with no indexer support";}RefactoringActionRules createActionRules() const override {...}
};

重构操作规则

单个重构操作负责创建一组表示重构操作的分组重构操作规则.尽管一个操作中的规则可能有多个不同实现,但它们应努力产生类似结果.

无论使用哪种重构操作规则,用户都应很容易识别是哪个重构操作产生了结果.

通过区分操作和规则,可创建定义一组产生类似结果的不同规则的操作.如,"添加缺失的开关(switch)"重构操作,一般一次添加一个缺失到switch.

但是,在指定枚举上运行所有开关上都适用的重构可能很有用,因为在添加新的枚举常量后,可自动更新所有开关.为此,可创建两个使用clang-refactor子命令的不同规则.

第一条规则描述在用户选择单个开关时启动的本地操作.第二条规则描述跨翻译单元工作的全局操作,并在用户向clang-refactor提供枚举名时启动(或用户可改为选择枚举声明).

然后,clang-refactor工具分析传递给重构操作的选择和其他选项,并为给定选择和其他选项选择最合适的规则.

规则类型

Clang的重构引擎支持几个不同的重构规则:
1,SourceChangeRefactoringRule生成应用至源文件的源替换.选择实现此规则的子类必须实现createSourceReplacements成员函数.
该类型规则一般用来实现仅在翻译单元内转换源的本地重构.
2,FindSymbolOccurrencesRefactoringRule生成"部分"重构结果:引用指定符号的一组实例.该类型的规则一般用来实现,重构时,允许用户指定应重命名哪些匹配项的交互式重命名操作.

选择实现此规则的子类必须实现findSymbolOccurrences成员函数.

如果不确定应使用的规则类型,以下快速检查也许有用:

如果想在一个翻译单元中转换源,且不需要跨TU信息,则SourceChangeRefactoringRule应该适合你.
如果要使用潜在的交互式组件实现类似重命名的操作,则FindSymbolOccurrencesRefactoringRule可能适合你.

如何创建规则

确定适合规则后,可通过继承规则并实现其接口来重构.子类应该有个取期望重构的输入的构造器.
如,如果要实现仅删除所选内容规则,则应使用接受选择区间的构造器,来创建SourceChangeRefactoringRule的子类:

class DeleteSelectedRange final : public SourceChangeRefactoringRule {
public:DeleteSelection(SourceRange Selection) : Selection(Selection) {}Expected<AtomicChanges>createSourceReplacements(RefactoringRuleContext &Context) override {AtomicChange Replacement(Context.getSources(), Selection.getBegin());Replacement.replace(Context.getSource,CharSourceRange::getCharRange(Selection), "");return { Replacement };}
private:SourceRange Selection;
};

然后,可用createRefactoringActionRule函数添加规则子类到特定操作的重构操作规则列表中.如,可用以下代码,把上面显示的类添加到操作规则列表中:

RefactoringActionRules Rules;
Rules.push_back(createRefactoringActionRule<DeleteSelectedRange>( SourceRangeSelectionRequirement()));

createRefactoringActionRule函数取重构操作规则要求值的列表.这些值描述重构引擎必须满足的启动要求,然后才能构造和调用提供的操作规则.

后面介绍如何求值这些要求,并列举可用来构造重构操作规则的所有可能要求.

重构操作规则要求

重构操作规则要求是一个从RefactoringActionRuleRequirement继承的类型的值.该类型必须定义一个返回Expected<...>的evaluate成员函数.

按createRefactoringActionRule的参数用要求值时,在启动操作规则时求值该值.然后,除非求值产生错误,把求值结果传递给规则的构造器.

如,以下步骤求值上一部分中定义的DeleteSelectedRange示例规则:
首先调用SourceRangeSelectionRequirement的返回Expected<SourceRange>的evaluate成员函数.

如果返回值为错误,则启动失败,并给客户报告错误.注意,客户可能不会向用户报告错误.

否则,用源区间返回值来构造DeleteSelectedRange规则.然后,启动成功(已成功求值所有要求)时,调用该规则.

相同的一系列步骤适合所有重构规则.首先,引擎求值所有要求.然后,检查是否满足这些要求(它们不应产生错误).然后,构造规则并调用它.

需求,求值和调用重构操作规则的分离允许重构客户:
1,禁止不支持的要求的重构操作规则.
2,收集选项集并定义一个允许用户不调用操作时,输入这些选项的命令行/可视化接口.

选区要求

下面列举了需要选择源的重构规则要求:
1,在使用某种选择调用操作时,按源区间计算SourceRangeSelectionRequirement.在编辑器中启动重构时,即使用户未选择内容(此时,区间包含光标的位置),也应满足此要求.

其他要求

创建重构规则时,可用其他几种要求类型:
1,RefactoringOptionsRequirement要求是一个应由使用选项的需求继承的抽象类.更具体的OptionRequirement要求是上述类在计算特定选项时,返回该选项值的简单实现.

重构选项

重构选项是影响重构操作的值,它用命令行选项或其他客户相关机制指定.应使用从OptionalRequiredOption或RequiredRefactoringOption继承的类创建选项.

以下示例显示了如何创建与clang-refactor中的-new-name命令行选项对应的必需串选项:

class NewNameOption : public RequiredRefactoringOption<std::string> {
public:StringRef getName() const override { return "new-name"; }StringRef getDescription() const override {return "目标的新名";}
};

然后,可用上面示例中显示的选项,通过类似OptionRequirement的要求为重构规则创建要求:

createRefactoringActionRule<RenameOccurrences>(...,OptionRequirement<NewNameOption>())
);