Introduction¶

Clang’s refactoring engine defines a set refactoring actions that implement a number of different source transformations. The clang-refactor command-line tool can be used to perform these refactorings. Certain refactorings are also available in other clients like text editors and IDEs.

A refactoring action is a class that defines a list of related refactoring operations (rules). These rules are grouped under a common umbrella - a single clang-refactor command. In addition to rules, the refactoring action provides the action’s command name and description to clang-refactor. Each action must implement the RefactoringAction interface. Here’s an outline of a local-rename action:

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 {
    ...
  }
};

Refactoring Action Rules¶

An individual refactoring action is responsible for creating the set of grouped refactoring action rules that represent one refactoring operation. Although the rules in one action may have a number of different implementations, they should strive to produce a similar result. It should be easy for users to identify which refactoring action produced the result regardless of which refactoring action rule was used.

The distinction between actions and rules enables the creation of actions that define a set of different rules that produce similar results. For example, the “add missing switch cases” refactoring operation typically adds missing cases to one switch at a time. However, it could be useful to have a refactoring that works on all switches that operate on a particular enum, as one could then automatically update all of them after adding a new enum constant. To achieve that, we can create two different rules that will use one clang-refactor subcommand. The first rule will describe a local operation that’s initiated when the user selects a single switch. The second rule will describe a global operation that works across translation units and is initiated when the user provides the name of the enum to clang-refactor (or the user could select the enum declaration instead). The clang-refactor tool will then analyze the selection and other options passed to the refactoring action, and will pick the most appropriate rule for the given selection and other options.

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;
};

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

Refactoring Action Rule Requirements¶

A refactoring action rule requirement is a value whose type derives from the RefactoringActionRuleRequirement class. The type must define an evaluate member function that returns a value of type Expected<...>. When a requirement value is used as an argument to createRefactoringActionRule, that value is evaluated during the initiation of the action rule. The evaluated result is then passed to the rule’s constructor unless the evaluation produced an error. For example, the DeleteSelectedRange sample rule that’s defined in the previous section will be evaluated using the following steps:

1. SourceRangeSelectionRequirement‘s evaluate member function will be called first. It will return an Expected<SourceRange>.
2. If the return value is an error the initiation will fail and the error will be reported to the client. Note that the client may not report the error to the user.
3. Otherwise the source range return value will be used to construct the DeleteSelectedRange rule. The rule will then be invoked as the initiation succeeded (all requirements were evaluated successfully).

The same series of steps applies to any refactoring rule. Firstly, the engine will evaluate all of the requirements. Then it will check if these requirements are satisfied (they should not produce an error). Then it will construct the rule and invoke it.

The separation of requirements, their evaluation and the invocation of the refactoring action rule allows the refactoring clients to:

• Disable refactoring action rules whose requirements are not supported.
• Gather the set of options and define a command-line / visual interface that allows users to input these options without ever invoking the action.

Refactoring Options¶

Refactoring options are values that affect a refactoring operation and are specified either using command-line options or another client-specific mechanism. Options should be created using a class that derives either from the OptionalRequiredOption or RequiredRefactoringOption. The following example shows how one can created a required string option that corresponds to the -new-name command-line option in clang-refactor:

class NewNameOption : public RequiredRefactoringOption<std::string> {
public:
  StringRef getName() const override { return "new-name"; }
  StringRef getDescription() const override {
    return "The new name to change the symbol to";
  }
};

The option that’s shown in the example above can then be used to create a requirement for a refactoring rule using a requirement like OptionRequirement:

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