clang/docs/RefactoringEngine.rst

==========================
Clang's refactoring engine
==========================

This document describes the design of Clang's refactoring engine and provides
a couple of examples that show how various primitives in the refactoring API
can be used to implement different refactoring actions. The :doc:`LibTooling`
library provides several other APIs that are used when developing a
refactoring action.

Refactoring engine can be used to implement local refactorings that are
initiated using a selection in an editor or an IDE. You can combine
:doc:`AST matchers<LibASTMatchers>` and the refactoring engine to implement
refactorings that don't lend themselves well to source selection and/or have to
query ASTs for some particular nodes.

We assume basic knowledge about the Clang AST. See the :doc:`Introduction
to the Clang AST <IntroductionToTheClangAST>` if you want to learn more
about how the AST is structured.

..  FIXME: create new refactoring action tutorial and link to the tutorial

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:

.. code-block:: c++

  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.

Rule Types
^^^^^^^^^^

Clang's refactoring engine supports several different refactoring rules:

- ``SourceChangeRefactoringRule`` produces source replacements that are applied
  to the source files. Subclasses that choose to implement this rule have to
  implement the ``createSourceReplacements`` member function. This type of
  rule is typically used to implement local refactorings that transform the
  source in one translation unit only.

- ``FindSymbolOccurrencesRefactoringRule`` produces a "partial" refactoring
  result: a set of occurrences that refer to a particular symbol. This type
  of rule is typically used to implement an interactive renaming action that
  allows users to specify which occurrences should be renamed during the
  refactoring. Subclasses that choose to implement this rule have to implement
  the ``findSymbolOccurrences`` member function.

The following set of quick checks might help if you are unsure about the type
of rule you should use:

#. If you would like to transform the source in one translation unit and if
   you don't need any cross-TU information, then the
   ``SourceChangeRefactoringRule`` should work for you.

#. If you would like to implement a rename-like operation with potential
   interactive components, then ``FindSymbolOccurrencesRefactoringRule`` might
   work for you.

How to Create a Rule
^^^^^^^^^^^^^^^^^^^^

Once you determine which type of rule is suitable for your needs you can
implement the refactoring by subclassing the rule and implementing its
interface. The subclass should have a constructor that takes the inputs that
are needed to perform the refactoring. For example, if you want to implement a
rule that simply deletes a selection, you should create a subclass of
``SourceChangeRefactoringRule`` with a constructor that accepts the selection
range:

.. code-block:: c++

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

The rule's subclass can then be added to the list of refactoring action's
rules for a particular action using the ``createRefactoringActionRule``
function. For example, the class that's shown above can be added to the
list of action rules using the following code:

.. code-block:: c++

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

The ``createRefactoringActionRule`` function takes in a list of refactoring
action rule requirement values. These values describe the initiation
requirements that have to be satisfied by the refactoring engine before the
provided action rule can be constructed and invoked. The next section
describes how these requirements are evaluated and lists all the possible
requirements that can be used to construct a refactoring action rule.

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:

#. ``SourceRangeSelectionRequirement``'s ``evaluate`` member function will be
   called first. It will return an ``Expected<SourceRange>``.

#. 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.

#. 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.

Selection Requirements
^^^^^^^^^^^^^^^^^^^^^^

The refactoring rule requirements that require some form of source selection
are listed below:

- ``SourceRangeSelectionRequirement`` evaluates to a source range when the
  action is invoked with some sort of selection. This requirement should be
  satisfied when a refactoring is initiated in an editor, even when the user
  has not selected anything (the range will contain the cursor's location in
  that case).

..  FIXME: Future selection requirements

..  FIXME: Maybe mention custom selection requirements?

Other Requirements
^^^^^^^^^^^^^^^^^^

There are several other requirements types that can be used when creating
a refactoring rule:

- The ``RefactoringOptionsRequirement`` requirement is an abstract class that
  should be subclassed by requirements working with options. The more
  concrete ``OptionRequirement`` requirement is a simple implementation of the
  aforementioned class that returns the value of the specified option when
  it's evaluated. The next section talks more about refactoring options and
  how they can be used when creating a rule.

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:

.. code-block:: c++

  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``:

.. code-block:: c++

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

..  FIXME: Editor Bindings section