//===--- RewriteRule.h - RewriteRule class ----------------------*- C++ -*-===//

//

// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.

// See https://llvm.org/LICENSE.txt for license information.

// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception

//

//===----------------------------------------------------------------------===//

///

///  \file

///  Defines the RewriteRule class and related functions for creating,

///  modifying and interpreting RewriteRules.

///

//===----------------------------------------------------------------------===//

#ifndef LLVM_CLANG_TOOLING_TRANSFORMER_REWRITE_RULE_H_

#define LLVM_CLANG_TOOLING_TRANSFORMER_REWRITE_RULE_H_

#include "clang/ASTMatchers/ASTMatchFinder.h"

#include "clang/ASTMatchers/ASTMatchers.h"

#include "clang/ASTMatchers/ASTMatchersInternal.h"

#include "clang/Tooling/Refactoring/AtomicChange.h"

#include "clang/Tooling/Transformer/MatchConsumer.h"

#include "clang/Tooling/Transformer/RangeSelector.h"

#include "llvm/ADT/STLExtras.h"

#include "llvm/ADT/SmallVector.h"

#include "llvm/Support/Error.h"

#include <functional>

#include <string>

#include <utility>

namespace clang {

namespace transformer {

using TextGenerator = std::shared_ptr<MatchComputation<std::string>>;

// Description of a source-code edit, expressed in terms of an AST node.

// Includes: an ID for the (bound) node, a selector for source related to the

// node, a replacement and, optionally, an explanation for the edit.

//

// * Target: the source code impacted by the rule. This identifies an AST node,

//   or part thereof (\c Part), whose source range indicates the extent of the

//   replacement applied by the replacement term.  By default, the extent is the

//   node matched by the pattern term (\c NodePart::Node). Target's are typed

//   (\c Kind), which guides the determination of the node extent.

//

// * Replacement: a function that produces a replacement string for the target,

//   based on the match result.

//

// * Note: (optional) a note specifically for this edit, potentially referencing

//   elements of the match.  This will be displayed to the user, where possible;

//   for example, in clang-tidy diagnostics.  Use of notes should be rare --

//   explanations of the entire rewrite should be set in the rule

//   (`RewriteRule::Explanation`) instead.  Notes serve the rare cases wherein

//   edit-specific diagnostics are required.

//

// `ASTEdit` should be built using the `change` convenience functions. For

// example,

// \code

//   changeTo(name(fun), cat("Frodo"))

// \endcode

// Or, if we use Stencil for the TextGenerator:

// \code

//   using stencil::cat;

//   changeTo(statement(thenNode), cat("{", thenNode, "}"))

//   changeTo(callArgs(call), cat(x, ",", y))

// \endcode

// Or, if you are changing the node corresponding to the rule's matcher, you can

// use the single-argument override of \c change:

// \code

//   changeTo(cat("different_expr"))

// \endcode

struct ASTEdit {

  RangeSelector TargetRange;

  TextGenerator Replacement;

  TextGenerator Note;

};

/// Format of the path in an include directive -- angle brackets or quotes.

enum class IncludeFormat {

  Quoted,

  Angled,

};

/// Description of a source-code transformation.

//

// A *rewrite rule* describes a transformation of source code. A simple rule

// contains each of the following components:

//

// * Matcher: the pattern term, expressed as clang matchers (with Transformer

//   extensions).

//

// * Edits: a set of Edits to the source code, described with ASTEdits.

//

// * Explanation: explanation of the rewrite.  This will be displayed to the

//   user, where possible; for example, in clang-tidy diagnostics.

//

// However, rules can also consist of (sub)rules, where the first that matches

// is applied and the rest are ignored.  So, the above components are gathered

// as a `Case` and a rule is a list of cases.

//

// Rule cases have an additional, implicit, component: the parameters. These are

// portions of the pattern which are left unspecified, yet bound in the pattern

// so that we can reference them in the edits.

//

// The \c Transformer class can be used to apply the rewrite rule and obtain the

// corresponding replacements.

struct RewriteRule {

  struct Case {

    ast_matchers::internal::DynTypedMatcher Matcher;

    SmallVector<ASTEdit, 1> Edits;

    TextGenerator Explanation;

    // Include paths to add to the file affected by this case.  These are

    // bundled with the `Case`, rather than the `RewriteRule`, because each case

    // might have different associated changes to the includes.

    std::vector<std::pair<std::string, IncludeFormat>> AddedIncludes;

  };

  // We expect RewriteRules will most commonly include only one case.

  SmallVector<Case, 1> Cases;

  // ID used as the default target of each match. The node described by the

  // matcher is should always be bound to this id.

  static constexpr llvm::StringLiteral RootID = "___root___";

};

/// Convenience function for constructing a simple \c RewriteRule.

RewriteRule makeRule(ast_matchers::internal::DynTypedMatcher M,

                     SmallVector<ASTEdit, 1> Edits,

                     TextGenerator Explanation = nullptr);

/// Convenience overload of \c makeRule for common case of only one edit.

inline RewriteRule makeRule(ast_matchers::internal::DynTypedMatcher M,

                            ASTEdit Edit,

                            TextGenerator Explanation = nullptr) {

  SmallVector<ASTEdit, 1> Edits;

  Edits.emplace_back(std::move(Edit));

  return makeRule(std::move(M), std::move(Edits), std::move(Explanation));

}

/// For every case in Rule, adds an include directive for the given header. The

/// common use is assumed to be a rule with only one case. For example, to

/// replace a function call and add headers corresponding to the new code, one

/// could write:

/// \code

///   auto R = makeRule(callExpr(callee(functionDecl(hasName("foo")))),

///            changeTo(cat("bar()")));

///   AddInclude(R, "path/to/bar_header.h");

///   AddInclude(R, "vector", IncludeFormat::Angled);

/// \endcode

void addInclude(RewriteRule &Rule, llvm::StringRef Header,

                IncludeFormat Format = IncludeFormat::Quoted);

/// Applies the first rule whose pattern matches; other rules are ignored.  If

/// the matchers are independent then order doesn't matter. In that case,

/// `applyFirst` is simply joining the set of rules into one.

//

// `applyFirst` is like an `anyOf` matcher with an edit action attached to each

// of its cases. Anywhere you'd use `anyOf(m1.bind("id1"), m2.bind("id2"))` and

// then dispatch on those ids in your code for control flow, `applyFirst` lifts

// that behavior to the rule level.  So, you can write `applyFirst({makeRule(m1,

// action1), makeRule(m2, action2), ...});`

//

// For example, consider a type `T` with a deterministic serialization function,

// `serialize()`.  For performance reasons, we would like to make it

// non-deterministic.  Therefore, we want to drop the expectation that

// `a.serialize() = b.serialize() iff a = b` (although we'll maintain

// `deserialize(a.serialize()) = a`).

//

// We have three cases to consider (for some equality function, `eq`):

// ```

// eq(a.serialize(), b.serialize()) --> eq(a,b)

// eq(a, b.serialize())             --> eq(deserialize(a), b)

// eq(a.serialize(), b)             --> eq(a, deserialize(b))

// ```

//

// `applyFirst` allows us to specify each independently:

// ```

// auto eq_fun = functionDecl(...);

// auto method_call = cxxMemberCallExpr(...);

//

// auto two_calls = callExpr(callee(eq_fun), hasArgument(0, method_call),

//                           hasArgument(1, method_call));

// auto left_call =

//     callExpr(callee(eq_fun), callExpr(hasArgument(0, method_call)));

// auto right_call =

//     callExpr(callee(eq_fun), callExpr(hasArgument(1, method_call)));

//

// RewriteRule R = applyFirst({makeRule(two_calls, two_calls_action),

//                             makeRule(left_call, left_call_action),

//                             makeRule(right_call, right_call_action)});

// ```

RewriteRule applyFirst(ArrayRef<RewriteRule> Rules);

/// Replaces a portion of the source text with \p Replacement.

ASTEdit changeTo(RangeSelector Target, TextGenerator Replacement);

/// DEPRECATED: use \c changeTo.

inline ASTEdit change(RangeSelector Target, TextGenerator Replacement) {

  return changeTo(std::move(Target), std::move(Replacement));

}

/// Replaces the entirety of a RewriteRule's match with \p Replacement.  For

/// example, to replace a function call, one could write:

/// \code

///   makeRule(callExpr(callee(functionDecl(hasName("foo")))),

///            changeTo(cat("bar()")))

/// \endcode

inline ASTEdit changeTo(TextGenerator Replacement) {

  return changeTo(node(std::string(RewriteRule::RootID)),

                  std::move(Replacement));

}

/// DEPRECATED: use \c changeTo.

inline ASTEdit change(TextGenerator Replacement) {

  return changeTo(std::move(Replacement));

}

/// Inserts \p Replacement before \p S, leaving the source selected by \S

/// unchanged.

inline ASTEdit insertBefore(RangeSelector S, TextGenerator Replacement) {

  return changeTo(before(std::move(S)), std::move(Replacement));

}

/// Inserts \p Replacement after \p S, leaving the source selected by \S

/// unchanged.

inline ASTEdit insertAfter(RangeSelector S, TextGenerator Replacement) {

  return changeTo(after(std::move(S)), std::move(Replacement));

}

/// Removes the source selected by \p S.

ASTEdit remove(RangeSelector S);

/// The following three functions are a low-level part of the RewriteRule

/// API. We expose them for use in implementing the fixtures that interpret

/// RewriteRule, like Transformer and TransfomerTidy, or for more advanced

/// users.

//

// FIXME: These functions are really public, if advanced, elements of the

// RewriteRule API.  Recast them as such.  Or, just declare these functions

// public and well-supported and move them out of `detail`.

namespace detail {

/// Builds a single matcher for the rule, covering all of the rule's cases.

/// Only supports Rules whose cases' matchers share the same base "kind"

/// (`Stmt`, `Decl`, etc.)  Deprecated: use `buildMatchers` instead, which

/// supports mixing matchers of different kinds.

ast_matchers::internal::DynTypedMatcher buildMatcher(const RewriteRule &Rule);

/// Builds a set of matchers that cover the rule (one for each distinct node

/// matcher base kind: Stmt, Decl, etc.). Node-matchers for `QualType` and

/// `Type` are not permitted, since such nodes carry no source location

/// information and are therefore not relevant for rewriting. If any such

/// matchers are included, will return an empty vector.

std::vector<ast_matchers::internal::DynTypedMatcher>

buildMatchers(const RewriteRule &Rule);

/// Gets the beginning location of the source matched by a rewrite rule. If the

/// match occurs within a macro expansion, returns the beginning of the

/// expansion point. `Result` must come from the matching of a rewrite rule.

SourceLocation

getRuleMatchLoc(const ast_matchers::MatchFinder::MatchResult &Result);

/// Returns the \c Case of \c Rule that was selected in the match result.

/// Assumes a matcher built with \c buildMatcher.

const RewriteRule::Case &

findSelectedCase(const ast_matchers::MatchFinder::MatchResult &Result,

                 const RewriteRule &Rule);

/// A source "transformation," represented by a character range in the source to

/// be replaced and a corresponding replacement string.

struct Transformation {

  CharSourceRange Range;

  std::string Replacement;

};

/// Attempts to translate `Edits`, which are in terms of AST nodes bound in the

/// match `Result`, into Transformations, which are in terms of the source code

/// text.

///

/// Returns an empty vector if any of the edits apply to portions of the source

/// that are ineligible for rewriting (certain interactions with macros, for

/// example).  Fails if any invariants are violated relating to bound nodes in

/// the match.  However, it does not fail in the case of conflicting edits --

/// conflict handling is left to clients.  We recommend use of the \c

/// AtomicChange or \c Replacements classes for assistance in detecting such

/// conflicts.

Expected<SmallVector<Transformation, 1>>

translateEdits(const ast_matchers::MatchFinder::MatchResult &Result,

               llvm::ArrayRef<ASTEdit> Edits);

} // namespace detail

} // namespace transformer

namespace tooling {

// DEPRECATED: These are temporary aliases supporting client migration to the

// `transformer` namespace.

/// Wraps a string as a TextGenerator.

using TextGenerator = transformer::TextGenerator;

TextGenerator text(std::string M);

using transformer::addInclude;

using transformer::applyFirst;

using transformer::change;

using transformer::insertAfter;

using transformer::insertBefore;

using transformer::makeRule;

using transformer::remove;

using transformer::RewriteRule;

using transformer::IncludeFormat;

namespace detail {

using namespace transformer::detail;

} // namespace detail

} // namespace tooling

} // namespace clang

#endif // LLVM_CLANG_TOOLING_TRANSFORMER_REWRITE_RULE_H_