[libTooling] Add `getFileRange` as an alternative to `getRangeForEdit`

[li.zhe.hua]

Summary

Add a getFileRange function alongside the existing getRangeForEdit
as a way to get a contiguous range within a single file (similar to
getRangeForEdit) but without the restriction that it cannot be in a
system header.

This can be used where a tool may want to use the range to extract the
source text. In such cases, we don't want to restrict this from
pulling from system headers.

[ymandel]

Can you add a test? probably valuable even if its nearly identical to the test for getRangeForEdit.

clang/include/clang/Tooling/Transformer/SourceCode.h

121–127

This description seems a bit out of place for this function, since it's explicitly *not* focused on the case of edits. Can this be rephrased?

[li.zhe.hua]

Fix description.
Remove default argument.
Fix copy/paste error.

[li.zhe.hua]

Upload correct commit this time...

[li.zhe.hua]

Try this again...

clang/include/clang/Tooling/Transformer/SourceCode.h

 /// locations in macro expansions is supported. For example, if we're looking to
 /// rewrite the int literal 3 to 6, and we have the following definition:
 ///    #define DO_NOTHING(x) x
 /// then
 ///    foo(DO_NOTHING(3))
 /// will be rewritten to
 ///    foo(6)
 std::optional<CharSourceRange>
-getRangeForEdit(const CharSourceRange &EditRange, const SourceManager &SM,
-                const LangOptions &LangOpts, bool IncludeMacroExpansion = true);
+getFileRangeForEdit(const CharSourceRange &EditRange, const SourceManager &SM,
+                    const LangOptions &LangOpts,
+                    bool IncludeMacroExpansion = true);
 inline std::optional<CharSourceRange>
-getRangeForEdit(const CharSourceRange &EditRange, const ASTContext &Context,
+getFileRangeForEdit(const CharSourceRange &EditRange, const ASTContext &Context,
                     bool IncludeMacroExpansion = true) {
-  return getRangeForEdit(EditRange, Context.getSourceManager(),
+  return getFileRangeForEdit(EditRange, Context.getSourceManager(),
                              Context.getLangOpts(), IncludeMacroExpansion);
 }
 
 /// Attempts to resolve the given range to one that starts and ends in a
 /// particular file.
 ///
 /// If \c IncludeMacroExpansion is true, a limited set of cases involving source
 /// locations in macro expansions is supported. For example, if we're looking to
 /// get the range of the int literal 3, and we have the following definition:
 ///    #define DO_NOTHING(x) x
 ///    foo(DO_NOTHING(3))
 /// the returned range will hold the source text `DO_NOTHING(3)`.
 std::optional<CharSourceRange> getFileRange(const CharSourceRange &EditRange,
                                             const SourceManager &SM,
                                             const LangOptions &LangOpts,
                                             bool IncludeMacroExpansion);
 inline std::optional<CharSourceRange>
 getFileRange(const CharSourceRange &EditRange, const ASTContext &Context,
              bool IncludeMacroExpansion) {
   return getFileRange(EditRange, Context.getSourceManager(),
                       Context.getLangOpts(), IncludeMacroExpansion);
 }
 
 } // namespace tooling
 } // namespace clang
 #endif // LLVM_CLANG_TOOLING_TRANSFORMER_SOURCECODE_H

clang/lib/Tooling/Transformer/RewriteRule.cpp

 static Expected<SmallVector<transformer::Edit, 1>>
 translateEdits(const MatchResult &Result, ArrayRef<ASTEdit> ASTEdits) {
   SmallVector<transformer::Edit, 1> Edits;
   for (const auto &E : ASTEdits) {
     Expected<CharSourceRange> Range = E.TargetRange(Result);
     if (!Range)
       return Range.takeError();
     std::optional<CharSourceRange> EditRange =
-        tooling::getRangeForEdit(*Range, *Result.Context);
+        tooling::getFileRangeForEdit(*Range, *Result.Context);
     // FIXME: let user specify whether to treat this case as an error or ignore
     // it as is currently done. This behavior is problematic in that it hides
     // failures from bad ranges. Also, the behavior here differs from
     // `flatten`. Here, we abort (without error), whereas flatten, if it hits an
     // empty list, does not abort. As a result, `editList({A,B})` is not
     // equivalent to `flatten(edit(A), edit(B))`. The former will abort if `A`
     // produces a bad range, whereas the latter will simply ignore A.
     if (!EditRange)
DynTypedMatcher transformer::detail::buildMatcher(const RewriteRuleBase &Rule) {
   assert(Ms.size() == 1 && "Cases must have compatible matchers.");
   return Ms[0];
 }
 
 SourceLocation transformer::detail::getRuleMatchLoc(const MatchResult &Result) {
   auto &NodesMap = Result.Nodes.getMap();
   auto Root = NodesMap.find(RootID);
   assert(Root != NodesMap.end() && "Transformation failed: missing root node.");
-  std::optional<CharSourceRange> RootRange = tooling::getRangeForEdit(
+  std::optional<CharSourceRange> RootRange = tooling::getFileRangeForEdit(
       CharSourceRange::getTokenRange(Root->second.getSourceRange()),
       *Result.Context);
   if (RootRange)
     return RootRange->getBegin();
   // The match doesn't have a coherent range, so fall back to the expansion
   // location as the "beginning" of the match.
   return Result.SourceManager->getExpansionLoc(
       Root->second.getSourceRange().getBegin());

clang/lib/Tooling/Transformer/SourceCode.cpp

if (IncludeMacroExpansion) {
     auto E = SM.getSpellingLoc(EditRange.getEnd());
     if (EditRange.isTokenRange())
       E = Lexer::getLocForEndOfToken(E, 0, SM, LangOpts);
     Range = CharSourceRange::getCharRange(B, E);
   }
   return Range;
 }
 
-std::optional<CharSourceRange> clang::tooling::getRangeForEdit(
+std::optional<CharSourceRange> clang::tooling::getFileRangeForEdit(
     const CharSourceRange &EditRange, const SourceManager &SM,
     const LangOptions &LangOpts, bool IncludeMacroExpansion) {
   CharSourceRange Range =
       getRange(EditRange, SM, LangOpts, IncludeMacroExpansion);
   bool IsInvalid = llvm::errorToBool(validateEditRange(Range, SM));
   if (IsInvalid)
     return std::nullopt;
   return Range;

clang/unittests/Tooling/SourceCodeTest.cpp

 using namespace clang;
 
 using llvm::Failed;
 using llvm::Succeeded;
 using llvm::ValueIs;
 using tooling::getAssociatedRange;
 using tooling::getExtendedRange;
 using tooling::getExtendedText;
-using tooling::getRangeForEdit;
+using tooling::getFileRangeForEdit;
 using tooling::getText;
 using tooling::maybeExtendRange;
 using tooling::validateEditRange;
 
 namespace {
 
 struct IntLitVisitor : TestVisitor<IntLitVisitor> {
   bool VisitIntegerLiteral(IntegerLiteral *Expr) {

 #define M(a) a * 13
 int foo(int x, int y);
 int a = $r[[foo(M(1), M(2))]];
 )cpp");
 
   CallsVisitor Visitor;
   Visitor.OnCall = [&Code](CallExpr *CE, ASTContext *Context) {
     auto Range = CharSourceRange::getTokenRange(CE->getSourceRange());
-    EXPECT_THAT(getRangeForEdit(Range, *Context, GetParam()),
+    EXPECT_THAT(getFileRangeForEdit(Range, *Context, GetParam()),
                 ValueIs(AsRange(Context->getSourceManager(), Code.range("r"))));
   };
   Visitor.runOver(Code.code());
 }
 
 TEST(SourceCodeTest, EditWholeMacroExpansionShouldSucceed) {
   llvm::Annotations Code(R"cpp(
 #define FOO 10
 int a = $r[[FOO]];
 )cpp");
 
   IntLitVisitor Visitor;
   Visitor.OnIntLit = [&Code](IntegerLiteral *Expr, ASTContext *Context) {
     auto Range = CharSourceRange::getTokenRange(Expr->getSourceRange());
-    EXPECT_THAT(getRangeForEdit(Range, *Context),
+    EXPECT_THAT(getFileRangeForEdit(Range, *Context),
                 ValueIs(AsRange(Context->getSourceManager(), Code.range("r"))));
   };
   Visitor.runOver(Code.code());
 }
 
 TEST(SourceCodeTest, EditInvolvingExpansionIgnoringExpansionShouldFail) {
   // If we specify to ignore macro expansions, none of these call expressions
   // should have an editable range.
   llvm::Annotations Code(R"cpp(
 #define M1(x) x(1)
 #define M2(x, y) x ## y
 #define M3(x) foobar(x)
 int foobar(int);
 int a = M1(foobar);
 int b = M2(foo, bar(2));
 int c = M3(3);
 )cpp");
 
   CallsVisitor Visitor;
   Visitor.OnCall = [](CallExpr *CE, ASTContext *Context) {
     auto Range = CharSourceRange::getTokenRange(CE->getSourceRange());
     EXPECT_FALSE(
-        getRangeForEdit(Range, *Context, /*IncludeMacroExpansion=*/false));
+        getFileRangeForEdit(Range, *Context, /*IncludeMacroExpansion=*/false));
   };
   Visitor.runOver(Code.code());
 }
 
 TEST_P(GetRangeForEditTest, EditPartialMacroExpansionShouldFail) {
   std::string Code = R"cpp(
 #define BAR 10+
 int c = BAR 3.0;
 )cpp";
 
   IntLitVisitor Visitor;
   Visitor.OnIntLit = [](IntegerLiteral *Expr, ASTContext *Context) {
     auto Range = CharSourceRange::getTokenRange(Expr->getSourceRange());
-    EXPECT_FALSE(getRangeForEdit(Range, *Context, GetParam()));
+    EXPECT_FALSE(getFileRangeForEdit(Range, *Context, GetParam()));
   };
   Visitor.runOver(Code);
 }
 
 TEST_P(GetRangeForEditTest, EditWholeMacroArgShouldSucceed) {
   llvm::Annotations Code(R"cpp(
 #define FOO(a) a + 7.0;
 int a = FOO($r[[10]]);
 )cpp");
 
   IntLitVisitor Visitor;
   Visitor.OnIntLit = [&Code](IntegerLiteral *Expr, ASTContext *Context) {
     auto Range = CharSourceRange::getTokenRange(Expr->getSourceRange());
-    EXPECT_THAT(getRangeForEdit(Range, *Context, GetParam()),
+    EXPECT_THAT(getFileRangeForEdit(Range, *Context, GetParam()),
                 ValueIs(AsRange(Context->getSourceManager(), Code.range("r"))));
   };
   Visitor.runOver(Code.code());
 }
 
 TEST_P(GetRangeForEditTest, EditPartialMacroArgShouldSucceed) {
   llvm::Annotations Code(R"cpp(
 #define FOO(a) a + 7.0;
 int a = FOO($r[[10]] + 10.0);
 )cpp");
 
   IntLitVisitor Visitor;
   Visitor.OnIntLit = [&Code](IntegerLiteral *Expr, ASTContext *Context) {
     auto Range = CharSourceRange::getTokenRange(Expr->getSourceRange());
-    EXPECT_THAT(getRangeForEdit(Range, *Context, GetParam()),
+    EXPECT_THAT(getFileRangeForEdit(Range, *Context, GetParam()),
                 ValueIs(AsRange(Context->getSourceManager(), Code.range("r"))));
   };
   Visitor.runOver(Code.code());
 }
 
 TEST(SourceCodeTest, EditRangeWithMacroExpansionsIsValid) {
   // The call expression, whose range we are extracting, includes two macro
   // expansions.