--- /dev/null
+==========================
+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
projects / platform / upstream / llvm.git / commitdiff