[libTooling] Add `describe` stencil for formatting AST nodes for diagnostics.

[ymandel]

Summary

This new stencil combinator is intended for use in diagnostics and the like.

[ymandel]

renamed the combinator

[ymandel]

updated name, comments and tests.

[tdl-g]

Looks great, just one comment.

clang/unittests/Tooling/StencilTest.cpp

519

Can you add a comment (or a more detailed test name) explaining what this test case is validating?

[ymandel]

thanks!

clang/unittests/Tooling/StencilTest.cpp

519

It's the same pattern for (nearly) all of the StencilToStringTest cases. Might a comment on the fixture be a better place?

[tdl-g]

clang/unittests/Tooling/StencilTest.cpp

519

Oh, sorry, I thought the "repr" was a stencil combinator, I didn't realize it was part of the raw string quotation. My bad.

LGTM as is.

clang/include/clang/Tooling/Transformer/Stencil.h

inline Stencil ifBound(llvm::StringRef Id, llvm::StringRef TrueText,
   return ifBound(Id, detail::makeStencil(TrueText),
                  detail::makeStencil(FalseText));
 }
 
 /// Wraps a \c MatchConsumer in a \c Stencil, so that it can be used in a \c
 /// Stencil.  This supports user-defined extensions to the \c Stencil language.
 Stencil run(MatchConsumer<std::string> C);
 
+/// Produces a human-readable rendering of the node bound to `Id`, suitable for
+/// diagnostics and debugging. This operator can be applied to any node, but is
+/// targeted at those whose source cannot be printed directly, including:
+///
+/// * Types. represented based on their structure. Note that namespace
+///   qualifiers are always printed, with the anonymous namespace represented
+///   explicitly. No desugaring or canonicalization is applied.
+Stencil describe(llvm::StringRef Id);
+
 /// For debug use only; semantics are not guaranteed.
 ///
 /// \returns the string resulting from calling the node's print() method.
 Stencil dPrint(llvm::StringRef Id);
 } // namespace transformer
 } // namespace clang
 #endif // LLVM_CLANG_TOOLING_TRANSFORMER_STENCIL_H_

clang/lib/Tooling/Transformer/Stencil.cpp

 
 // Operators that take a single node Id as an argument.
 enum class UnaryNodeOperator {
   Parens,
   Deref,
   MaybeDeref,
   AddressOf,
   MaybeAddressOf,
+  Describe,
 };
 
 // Generic container for stencil operations with a (single) node-id argument.
 struct UnaryOperationData {
   UnaryOperationData(UnaryNodeOperator Op, std::string Id)
       : Op(Op), Id(std::move(Id)) {}
   UnaryNodeOperator Op;
   std::string Id;
case UnaryNodeOperator::MaybeDeref:
     OpName = "maybeDeref";
     break;
   case UnaryNodeOperator::AddressOf:
     OpName = "addressOf";
     break;
   case UnaryNodeOperator::MaybeAddressOf:
     OpName = "maybeAddressOf";
     break;
+  case UnaryNodeOperator::Describe:
+    OpName = "describe";
+    break;
   }
   return (OpName + "(\"" + Data.Id + "\")").str();
 }
 
 std::string toStringData(const SelectorData &) { return "selection(...)"; }
 
 std::string toStringData(const AccessData &Data) {
   return (llvm::Twine("access(\"") + Data.BaseId + "\", " +

 // type of stencil data.
 
 Error evalData(const RawTextData &Data, const MatchFinder::MatchResult &,
                std::string *Result) {
   Result->append(Data.Text);
   return Error::success();
 }
 
-Error evalData(const DebugPrintNodeData &Data,
-               const MatchFinder::MatchResult &Match, std::string *Result) {
+static Error printNode(StringRef Id, const MatchFinder::MatchResult &Match,
+                       std::string *Result) {
   std::string Output;
   llvm::raw_string_ostream Os(Output);
-  auto NodeOrErr = getNode(Match.Nodes, Data.Id);
+  auto NodeOrErr = getNode(Match.Nodes, Id);
   if (auto Err = NodeOrErr.takeError())
     return Err;
   NodeOrErr->print(Os, PrintingPolicy(Match.Context->getLangOpts()));
   *Result += Os.str();
   return Error::success();
 }
 
+Error evalData(const DebugPrintNodeData &Data,
+               const MatchFinder::MatchResult &Match, std::string *Result) {
+  return printNode(Data.Id, Match, Result);
+}
+
 Error evalData(const UnaryOperationData &Data,
                const MatchFinder::MatchResult &Match, std::string *Result) {
+  // The `Describe` operation can be applied to any node, not just expressions,
+  // so it is handled here, separately.
+  if (Data.Op == UnaryNodeOperator::Describe)
+    return printNode(Data.Id, Match, Result);
+
   const auto *E = Match.Nodes.getNodeAs<Expr>(Data.Id);
   if (E == nullptr)
     return llvm::make_error<StringError>(
         errc::invalid_argument, "Id not bound or not Expr: " + Data.Id);
   llvm::Optional<std::string> Source;
   switch (Data.Op) {
   case UnaryNodeOperator::Parens:
     Source = tooling::buildParens(*E, *Match.Context);
case UnaryNodeOperator::AddressOf:
     break;
   case UnaryNodeOperator::MaybeAddressOf:
     if (E->getType()->isAnyPointerType()) {
       *Result += tooling::getText(*E, *Match.Context);
       return Error::success();
     }
     Source = tooling::buildAddressOf(*E, *Match.Context);
     break;
+  case UnaryNodeOperator::Describe:
+    llvm_unreachable("This case is handled at the start of the function");
   }
   if (!Source)
     return llvm::make_error<StringError>(
         errc::invalid_argument,
         "Could not construct expression source from ID: " + Data.Id);
   *Result += *Source;
   return Error::success();
 }
return std::make_shared<StencilImpl<UnaryOperationData>>(
       UnaryNodeOperator::AddressOf, std::string(ExprId));
 }
 
 Stencil transformer::maybeAddressOf(llvm::StringRef ExprId) {
   return std::make_shared<StencilImpl<UnaryOperationData>>(
       UnaryNodeOperator::MaybeAddressOf, std::string(ExprId));
 }
 
+Stencil transformer::describe(StringRef Id) {
+  return std::make_shared<StencilImpl<UnaryOperationData>>(
+      UnaryNodeOperator::Describe, std::string(Id));
+}
+
 Stencil transformer::access(StringRef BaseId, Stencil Member) {
   return std::make_shared<StencilImpl<AccessData>>(BaseId, std::move(Member));
 }
 
 Stencil transformer::ifBound(StringRef Id, Stencil TrueStencil,
                              Stencil FalseStencil) {
   return std::make_shared<StencilImpl<IfBoundData>>(Id, std::move(TrueStencil),
                                                     std::move(FalseStencil));

clang/unittests/Tooling/StencilTest.cpp

 using ::llvm::HasValue;
 using ::llvm::StringError;
 using ::testing::AllOf;
 using ::testing::HasSubstr;
 using MatchResult = MatchFinder::MatchResult;
 
 // Create a valid translation-unit from a statement.
 static std::string wrapSnippet(StringRef StatementCode) {
-  return ("struct S { int field; }; auto stencil_test_snippet = []{" +
+  return ("namespace N { class C {}; } "
+          "namespace { class AnonC {}; } "
+          "struct S { int field; }; auto stencil_test_snippet = []{" +
           StatementCode + "};")
       .str();
 }
 
 static DeclarationMatcher wrapMatcher(const StatementMatcher &Matcher) {
   return varDecl(hasName("stencil_test_snippet"),
                  hasDescendant(compoundStmt(hasAnySubstatement(Matcher))));
 }
 
 struct TestMatch {
   // The AST unit from which `result` is built. We bundle it because it backs
   // the result. Users are not expected to access it.
   std::unique_ptr<ASTUnit> AstUnit;
   // The result to use in the test. References `ast_unit`.
   MatchResult Result;
 };
 
 // Matches `Matcher` against the statement `StatementCode` and returns the
 // result. Handles putting the statement inside a function and modifying the
 // matcher correspondingly. `Matcher` should match one of the statements in
 // `StatementCode` exactly -- that is, produce exactly one match. However,
 // `StatementCode` may contain other statements not described by `Matcher`.
 static llvm::Optional<TestMatch> matchStmt(StringRef StatementCode,
                                            StatementMatcher Matcher) {
-  auto AstUnit = tooling::buildASTFromCode(wrapSnippet(StatementCode));
+  auto AstUnit = tooling::buildASTFromCodeWithArgs(wrapSnippet(StatementCode),
+                                                   {"-Wno-unused-value"});
   if (AstUnit == nullptr) {
     ADD_FAILURE() << "AST construction failed";
     return llvm::None;
   }
   ASTContext &Context = AstUnit->getASTContext();
-  auto Matches = ast_matchers::match(
-      traverse(ast_type_traits::TK_AsIs, wrapMatcher(Matcher)), Context);
+  auto Matches = ast_matchers::match(wrapMatcher(Matcher), Context);
   // We expect a single, exact match for the statement.
   if (Matches.size() != 1) {
     ADD_FAILURE() << "Wrong number of matches: " << Matches.size();
     return llvm::None;
   }
   return TestMatch{std::move(AstUnit), MatchResult(Matches[0], &Context)};
 }
 
TEST_F(StencilTest, AccessOpImplicitThis) {
   auto StmtMatch =
       matchStmt(Snippet, returnStmt(hasReturnValue(ignoringImplicit(memberExpr(
                              hasObjectExpression(expr().bind("obj")))))));
   ASSERT_TRUE(StmtMatch);
   const Stencil Stencil = access("obj", "field");
   EXPECT_THAT_EXPECTED(Stencil->eval(StmtMatch->Result), HasValue("field"));
 }
 
+TEST_F(StencilTest, DescribeType) {
+  std::string Snippet = "int *x; x;";
+  std::string Expected = "int *";
+  auto StmtMatch =
+      matchStmt(Snippet, declRefExpr(hasType(qualType().bind("type"))));
+  ASSERT_TRUE(StmtMatch);
+  EXPECT_THAT_EXPECTED(describe("type")->eval(StmtMatch->Result),
+                       HasValue(std::string(Expected)));
+}
+
+TEST_F(StencilTest, DescribeSugaredType) {
+  std::string Snippet = "using Ty = int; Ty *x; x;";
+  std::string Expected = "Ty *";
+  auto StmtMatch =
+      matchStmt(Snippet, declRefExpr(hasType(qualType().bind("type"))));
+  ASSERT_TRUE(StmtMatch);
+  EXPECT_THAT_EXPECTED(describe("type")->eval(StmtMatch->Result),
+                       HasValue(std::string(Expected)));
+}
+
+TEST_F(StencilTest, DescribeDeclType) {
+  std::string Snippet = "S s; s;";
+  std::string Expected = "S";
+  auto StmtMatch =
+      matchStmt(Snippet, declRefExpr(hasType(qualType().bind("type"))));
+  ASSERT_TRUE(StmtMatch);
+  EXPECT_THAT_EXPECTED(describe("type")->eval(StmtMatch->Result),
+                       HasValue(std::string(Expected)));
+}
+
+TEST_F(StencilTest, DescribeQualifiedType) {
+  std::string Snippet = "N::C c; c;";
+  std::string Expected = "N::C";
+  auto StmtMatch =
+      matchStmt(Snippet, declRefExpr(hasType(qualType().bind("type"))));
+  ASSERT_TRUE(StmtMatch);
+  EXPECT_THAT_EXPECTED(describe("type")->eval(StmtMatch->Result),
+                       HasValue(std::string(Expected)));
+}
+
+TEST_F(StencilTest, DescribeUnqualifiedType) {
+  std::string Snippet = "using N::C; C c; c;";
+  std::string Expected = "N::C";
+  auto StmtMatch =
+      matchStmt(Snippet, declRefExpr(hasType(qualType().bind("type"))));
+  ASSERT_TRUE(StmtMatch);
+  EXPECT_THAT_EXPECTED(describe("type")->eval(StmtMatch->Result),
+                       HasValue(std::string(Expected)));
+}
+
+TEST_F(StencilTest, DescribeAnonNamespaceType) {
+  std::string Snippet = "AnonC c; c;";
+  std::string Expected = "(anonymous namespace)::AnonC";
+  auto StmtMatch =
+      matchStmt(Snippet, declRefExpr(hasType(qualType().bind("type"))));
+  ASSERT_TRUE(StmtMatch);
+  EXPECT_THAT_EXPECTED(describe("type")->eval(StmtMatch->Result),
+                       HasValue(std::string(Expected)));
+}
+
 TEST_F(StencilTest, RunOp) {
   StringRef Id = "id";
   auto SimpleFn = [Id](const MatchResult &R) {
     return std::string(R.Nodes.getNodeAs<Stmt>(Id) != nullptr ? "Bound"
                                                               : "Unbound");
   };
   testExpr(Id, "3;", run(SimpleFn), "Bound");
 }
#define MACRO (3.77)
   Expected<std::string> Result = S->eval(StmtMatch->Result);
   ASSERT_THAT_EXPECTED(Result, Failed<StringError>());
   llvm::handleAllErrors(Result.takeError(), [](const llvm::StringError &E) {
     EXPECT_THAT(E.getMessage(), AllOf(HasSubstr("selected range"),
                                       HasSubstr("macro expansion")));
   });
 }
 
+// The `StencilToStringTest` tests verify that the string representation of the
+// stencil combinator matches (as best possible) the spelling of the
+// combinator's construction.  Exceptions include those combinators that have no
+// explicit spelling (like raw text) and those supporting non-printable
+// arguments (like `run`, `selection`).
+
 TEST(StencilToStringTest, RawTextOp) {
   auto S = cat("foo bar baz");
   StringRef Expected = R"("foo bar baz")";
   EXPECT_EQ(S->toString(), Expected);
 }
 
 TEST(StencilToStringTest, RawTextOpEscaping) {
   auto S = cat("foo \"bar\" baz\\n");
   StringRef Expected = R"("foo \"bar\" baz\\n")";
   EXPECT_EQ(S->toString(), Expected);
 }
 
+TEST(StencilToStringTest, DescribeOp) {
+  auto S = describe("Id");
+  StringRef Expected = R"repr(describe("Id"))repr";
+  EXPECT_EQ(S->toString(), Expected);
+}
+
 TEST(StencilToStringTest, DebugPrintNodeOp) {
   auto S = dPrint("Id");
   StringRef Expected = R"repr(dPrint("Id"))repr";
   EXPECT_EQ(S->toString(), Expected);
 }
 
 TEST(StencilToStringTest, ExpressionOp) {
   auto S = expression("Id");