[clang]: Add DeclContext::dumpAsDecl().

[tahonermann]

Summary

This change enables a declaration to be conveniently displayed within a debugger when only a pointer to its DeclContext is available. For example, in gdb:

(gdb) p Ctx
$1 = (const clang::DeclContext *) 0x14c1a580
(gdb) p Ctx->dumpAsDecl()
ClassTemplateSpecializationDecl 0x14c1a540 <t.cpp:1:1, line:7:1> line:2:8 struct ct
`-TemplateArgument type 'int'
  `-BuiltinType 0x14bac420 'int'
$2 = void

In the event that the pointed to DeclContext is invalid (that it has an invalid DeclKind as a result of a dangling pointer, memory corruption, etc...) it is not possible to dump its associated declaration. In this case, the DeclContext will be reported as invalid. For example, in gdb:

(gdb) p Ctx->dumpAsDecl()
DeclContext 0x14c1a580 <unrecognized Decl kind 127>
$3 = void

[erichkeane]

clang/lib/AST/ASTDumper.cpp

233

One thing to note is that the 'else' case here is a little uninformative. See https://clang.llvm.org/doxygen/DeclBase_8cpp_source.html#l00915 for some similar logic here (though not sure we should be emulating that).

More, I wonder if there is SOME message here that should be dumped for 'else'.

[aaron.ballman]

clang/lib/AST/ASTDumper.cpp

232

233

Looking at what inherits from DeclContext, is there use of it which is *not* a Decl? I couldn't find a use where it's not also a Decl.

[erichkeane]

clang/lib/AST/ASTDumper.cpp

233

I've DEFINITELY run into it in the debugger before, but I have no idea WHAT case that is. It is sometimes just "DeclContext is an invalid pointer" kinda thing, so it might be worth-while to have SOME output besides "print nothing", particularly when debugging.

[aaron.ballman]

clang/lib/AST/ASTDumper.cpp

233

IIRC, the case this comes up in is when the object is only partially constructed, and so I agree that having an else clause here would be useful -- because this interface is predominately used from a debugger, it has to deal with special "impossible" situations a bit more carefully.

[shafik]

Nice, thank you for doing this.

[shafik]

clang/lib/AST/ASTDumper.cpp

231

Interesting DeclContext::dumpDeclContext() is in DeclPrinter.cpp I wonder why these were split like this.

233

So looking at the other dump member functions, all of them seem to assume we have a valid DeclContext and so they do not have any else either.

So maybe we want to think about making the rest a bit smarter as well?

[aaron.ballman]

clang/lib/AST/ASTDumper.cpp

233

So maybe we want to think about making the rest a bit smarter as well?

What do you have in mind?

I think it's plausible to be in a partially constructed state in terms of when ctors are called, but I'm far less worried about people calling a dump method in the middle of the member inits happening.

[shafik]

clang/lib/AST/ASTDumper.cpp

233

So maybe we want to think about making the rest a bit smarter as well?

What do you have in mind?

I think it's plausible to be in a partially constructed state in terms of when ctors are called, but I'm far less worried about people calling a dump method in the middle of the member inits happening.

Apologies, what I meant was if we are going to add an else here then we should be consistent and add it in the other dump functions as well.

[aaron.ballman]

clang/lib/AST/ASTDumper.cpp

233

None of the other DeclContext dump functions cast to Decl, so I'm not certain there's an else to add to any of them, or am I misunderstanding?

[tahonermann]

Addressed review feedback; when presented with an invalid DeclContext, output will now be produced that explains why it is invalid.

[tahonermann]

Addressed a suggested edit I originally failed to notice.

[tahonermann]

clang/lib/AST/ASTDumper.cpp

231

It looks like the implementation of DeclContext::dumpDeclContext() requires class DeclPrinter to be defined. DeclPrinter is defined in clang/lib/AST/DeclPrinter.cpp in an unnamed namespace.

[erichkeane]

Please see the two comments, otherwise this LGTM. Feel free to fix the below as a part of the commit process.

clang/lib/AST/ASTDumper.cpp

240

This gets a little overly coy for our comments...

250

This can now just be 'cast'

[tahonermann]

Pushed, but I forgot to add the Differential Revision tag to the commit, so closing manually. The changes landed as commit 4247cdb568eca4c31b14d91105fe5ee140225036.

clang/lib/AST/ASTDumper.cpp

240

Aw, I was having fun writing that comment! No problem, I'll sprinkle some professional polishing salts on it.

clang/include/clang/AST/ASTDumper.h

public:
   ASTDumper(raw_ostream &OS, const ASTContext &Context, bool ShowColors)
       : NodeDumper(OS, Context, ShowColors), OS(OS), ShowColors(ShowColors) {}
 
   ASTDumper(raw_ostream &OS, bool ShowColors)
       : NodeDumper(OS, ShowColors), OS(OS), ShowColors(ShowColors) {}
 
   TextNodeDumper &doGetNodeDelegate() { return NodeDumper; }
 
+  void dumpInvalidDeclContext(const DeclContext *DC);
   void dumpLookups(const DeclContext *DC, bool DumpDecls);
 
   template <typename SpecializationDecl>
   void dumpTemplateDeclSpecialization(const SpecializationDecl *D,
                                       bool DumpExplicitInst, bool DumpRefOnly);
   template <typename TemplateDecl>
   void dumpTemplateDecl(const TemplateDecl *D, bool DumpExplicitInst);
 
   void VisitFunctionTemplateDecl(const FunctionTemplateDecl *D);
   void VisitClassTemplateDecl(const ClassTemplateDecl *D);
   void VisitVarTemplateDecl(const VarTemplateDecl *D);
 };
 
 } // namespace clang
 
 #endif

clang/include/clang/AST/DeclBase.h

protected:
   static std::pair<Decl *, Decl *>
   BuildDeclChain(ArrayRef<Decl*> Decls, bool FieldsAlreadyLoaded);
 
   DeclContext(Decl::Kind K);
 
 public:
   ~DeclContext();
 
+  // For use when debugging; hasValidDeclKind() will always return true for
+  // a correctly constructed object within its lifetime.
+  bool hasValidDeclKind() const;
+
   Decl::Kind getDeclKind() const {
     return static_cast<Decl::Kind>(DeclContextBits.DeclKind);
   }
 
   const char *getDeclKindName() const;
 
   /// getParent - Returns the containing DeclContext.
   DeclContext *getParent() {
public:
 
   bool shouldUseQualifiedLookup() const {
     return DeclContextBits.UseQualifiedLookup;
   }
 
   static bool classof(const Decl *D);
   static bool classof(const DeclContext *D) { return true; }
 
+  void dumpAsDecl() const;
+  void dumpAsDecl(const ASTContext *Ctx) const;
   void dumpDeclContext() const;
   void dumpLookups() const;
   void dumpLookups(llvm::raw_ostream &OS, bool DumpDecls = false,
                    bool Deserialize = false) const;
 
 private:
   /// Whether this declaration context has had externally visible
   /// storage added since the last lookup. In this case, \c LookupPtr's

clang/lib/AST/ASTDumper.cpp

 #include "clang/AST/ASTDumper.h"
 #include "clang/AST/ASTContext.h"
 #include "clang/AST/DeclLookups.h"
 #include "clang/AST/JSONNodeDumper.h"
 #include "clang/Basic/Builtins.h"
 #include "clang/Basic/Module.h"
 #include "clang/Basic/SourceManager.h"
 #include "llvm/Support/raw_ostream.h"
+
 using namespace clang;
 using namespace clang::comments;
 
+void ASTDumper::dumpInvalidDeclContext(const DeclContext *DC) {
+  NodeDumper.AddChild([=] {
+    if (!DC) {
+      ColorScope Color(OS, ShowColors, NullColor);
+      OS << "<<<NULL>>>";
+      return;
+    }
+    // An invalid DeclContext is one for which a dyn_cast() from a DeclContext
+    // pointer to a Decl pointer would fail an assertion or otherwise fall prey
+    // to undefined behavior as a result of an invalid associated DeclKind.
+    // Such invalidity is not supposed to happen of course, but, when it does,
+    // the information provided below is intended to provide some hints about
+    // what might have gone awry.
+    {
+      ColorScope Color(OS, ShowColors, DeclKindNameColor);
+      OS << "DeclContext";
+    }
+    NodeDumper.dumpPointer(DC);
+    OS << " <";
+    {
+      ColorScope Color(OS, ShowColors, DeclNameColor);
+      OS << "unrecognized Decl kind " << (unsigned)DC->getDeclKind();
+    }
+    OS << ">";
+  });
+}
+
 void ASTDumper::dumpLookups(const DeclContext *DC, bool DumpDecls) {
   NodeDumper.AddChild([=] {
     OS << "StoredDeclsMap ";
     NodeDumper.dumpBareDeclRef(cast<Decl>(DC));
 
     const DeclContext *Primary = DC->getPrimaryContext();
     if (Primary != DC) {
       OS << " primary";

 }
 
 LLVM_DUMP_METHOD void Decl::dumpColor() const {
   const ASTContext &Ctx = getASTContext();
   ASTDumper P(llvm::errs(), Ctx, /*ShowColors=*/true);
   P.Visit(this);
 }
 
+LLVM_DUMP_METHOD void DeclContext::dumpAsDecl() const {
+  dumpAsDecl(nullptr);
+}
+
+LLVM_DUMP_METHOD void DeclContext::dumpAsDecl(const ASTContext *Ctx) const {
+  // By design, every DeclContext instance is required to be a base class of
+  // some class that derives from Decl. Thus, it should always be possible to
+  // dyn_cast() from a DeclContext pointer to a Decl pointer and, indeed,
+  // the innerworkings of dyn_cast() do assert that to be the case! Alas,
+  // strange and unfortunate things do occasionally occur that lead to folk
+  // like yourself, dear reader, running a debugger and feeling extraordinarily
+  // curious about the origin of a DeclContext instance for which you have
+  // little knowledge. This function has been carefully designed to provide you,
+  // yes you, the answers you desperately seek and deserve with minimal risk
+  // that simply asking the question will upend your debugging experience. The
+  // call to dyn_cast() below is guarded by a validity check that ensures its
+  // success, thus preventing an otherwise potentially volatile (no, not that
+  // kind of volatile) situation.
+  if (hasValidDeclKind()) {
+    const auto *D = dyn_cast<Decl>(this);
+    D->dump();
+  } else {
+    // If an ASTContext is not available, a less capable ASTDumper is
+    // constructed for which color diagnostics are, regrettably, disabled.
+    ASTDumper P = Ctx ? ASTDumper(llvm::errs(), *Ctx,
+                                  Ctx->getDiagnostics().getShowColors())
+                      : ASTDumper(llvm::errs(), /*ShowColors*/ false);
+    P.dumpInvalidDeclContext(this);
+  }
+}
+
 LLVM_DUMP_METHOD void DeclContext::dumpLookups() const {
   dumpLookups(llvm::errs());
 }
 
 LLVM_DUMP_METHOD void DeclContext::dumpLookups(raw_ostream &OS,
                                                bool DumpDecls,
                                                bool Deserialize) const {
   const DeclContext *DC = this;

clang/lib/AST/DeclBase.cpp

void Decl::setInvalidDecl(bool Invalid) {
   // are invalid too.
   if (auto *DD = dyn_cast<DecompositionDecl>(this)) {
     for (auto *Binding : DD->bindings()) {
       Binding->setInvalidDecl();
     }
   }
 }
 
+bool DeclContext::hasValidDeclKind() const {
+  switch (getDeclKind()) {
+#define DECL(DERIVED, BASE) case Decl::DERIVED: return true;
+#define ABSTRACT_DECL(DECL)
+#include "clang/AST/DeclNodes.inc"
+  }
+  return false;
+}
+
 const char *DeclContext::getDeclKindName() const {
   switch (getDeclKind()) {
 #define DECL(DERIVED, BASE) case Decl::DERIVED: return #DERIVED;
 #define ABSTRACT_DECL(DECL)
 #include "clang/AST/DeclNodes.inc"
   }
   llvm_unreachable("Declaration context not in DeclNodes.inc!");
 }