1 //===--- JSONNodeDumper.h - Printing of AST nodes to JSON -----------------===//
2 //
3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4 // See https://llvm.org/LICENSE.txt for license information.
5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6 //
7 //===----------------------------------------------------------------------===//
8 //
9 // This file implements AST dumping of components of individual AST nodes to
10 // a JSON.
11 //
12 //===----------------------------------------------------------------------===//
13 
14 #ifndef LLVM_CLANG_AST_JSONNODEDUMPER_H
15 #define LLVM_CLANG_AST_JSONNODEDUMPER_H
16 
17 #include "clang/AST/ASTContext.h"
18 #include "clang/AST/ASTDumperUtils.h"
19 #include "clang/AST/ASTNodeTraverser.h"
20 #include "clang/AST/AttrVisitor.h"
21 #include "clang/AST/CommentCommandTraits.h"
22 #include "clang/AST/CommentVisitor.h"
23 #include "clang/AST/ExprConcepts.h"
24 #include "clang/AST/ExprCXX.h"
25 #include "clang/AST/Mangle.h"
26 #include "clang/AST/Type.h"
27 #include "llvm/Support/JSON.h"
28 
29 namespace clang {
30 
31 class APValue;
32 
33 class NodeStreamer {
34   bool FirstChild = true;
35   bool TopLevel = true;
36   llvm::SmallVector<std::function<void(bool IsLastChild)>, 32> Pending;
37 
38 protected:
39   llvm::json::OStream JOS;
40 
41 public:
42   /// Add a child of the current node.  Calls DoAddChild without arguments
AddChild(Fn DoAddChild)43   template <typename Fn> void AddChild(Fn DoAddChild) {
44     return AddChild("", DoAddChild);
45   }
46 
47   /// Add a child of the current node with an optional label.
48   /// Calls DoAddChild without arguments.
AddChild(StringRef Label,Fn DoAddChild)49   template <typename Fn> void AddChild(StringRef Label, Fn DoAddChild) {
50     // If we're at the top level, there's nothing interesting to do; just
51     // run the dumper.
52     if (TopLevel) {
53       TopLevel = false;
54       JOS.objectBegin();
55 
56       DoAddChild();
57 
58       while (!Pending.empty()) {
59         Pending.back()(true);
60         Pending.pop_back();
61       }
62 
63       JOS.objectEnd();
64       TopLevel = true;
65       return;
66     }
67 
68     // We need to capture an owning-string in the lambda because the lambda
69     // is invoked in a deferred manner.
70     std::string LabelStr(!Label.empty() ? Label : "inner");
71     bool WasFirstChild = FirstChild;
72     auto DumpWithIndent = [=](bool IsLastChild) {
73       if (WasFirstChild) {
74         JOS.attributeBegin(LabelStr);
75         JOS.arrayBegin();
76       }
77 
78       FirstChild = true;
79       unsigned Depth = Pending.size();
80       JOS.objectBegin();
81 
82       DoAddChild();
83 
84       // If any children are left, they're the last at their nesting level.
85       // Dump those ones out now.
86       while (Depth < Pending.size()) {
87         Pending.back()(true);
88         this->Pending.pop_back();
89       }
90 
91       JOS.objectEnd();
92 
93       if (IsLastChild) {
94         JOS.arrayEnd();
95         JOS.attributeEnd();
96       }
97     };
98 
99     if (FirstChild) {
100       Pending.push_back(std::move(DumpWithIndent));
101     } else {
102       Pending.back()(false);
103       Pending.back() = std::move(DumpWithIndent);
104     }
105     FirstChild = false;
106   }
107 
NodeStreamer(raw_ostream & OS)108   NodeStreamer(raw_ostream &OS) : JOS(OS, 2) {}
109 };
110 
111 // Dumps AST nodes in JSON format. There is no implied stability for the
112 // content or format of the dump between major releases of Clang, other than it
113 // being valid JSON output. Further, there is no requirement that the
114 // information dumped is a complete representation of the AST, only that the
115 // information presented is correct.
116 class JSONNodeDumper
117     : public ConstAttrVisitor<JSONNodeDumper>,
118       public comments::ConstCommentVisitor<JSONNodeDumper, void,
119                                            const comments::FullComment *>,
120       public ConstTemplateArgumentVisitor<JSONNodeDumper>,
121       public ConstStmtVisitor<JSONNodeDumper>,
122       public TypeVisitor<JSONNodeDumper>,
123       public ConstDeclVisitor<JSONNodeDumper>,
124       public NodeStreamer {
125   friend class JSONDumper;
126 
127   const SourceManager &SM;
128   ASTContext& Ctx;
129   ASTNameGenerator ASTNameGen;
130   PrintingPolicy PrintPolicy;
131   const comments::CommandTraits *Traits;
132   StringRef LastLocFilename, LastLocPresumedFilename;
133   unsigned LastLocLine, LastLocPresumedLine;
134 
135   using InnerAttrVisitor = ConstAttrVisitor<JSONNodeDumper>;
136   using InnerCommentVisitor =
137       comments::ConstCommentVisitor<JSONNodeDumper, void,
138                                     const comments::FullComment *>;
139   using InnerTemplateArgVisitor = ConstTemplateArgumentVisitor<JSONNodeDumper>;
140   using InnerStmtVisitor = ConstStmtVisitor<JSONNodeDumper>;
141   using InnerTypeVisitor = TypeVisitor<JSONNodeDumper>;
142   using InnerDeclVisitor = ConstDeclVisitor<JSONNodeDumper>;
143 
attributeOnlyIfTrue(StringRef Key,bool Value)144   void attributeOnlyIfTrue(StringRef Key, bool Value) {
145     if (Value)
146       JOS.attribute(Key, Value);
147   }
148 
149   void writeIncludeStack(PresumedLoc Loc, bool JustFirst = false);
150 
151   // Writes the attributes of a SourceLocation object without.
152   void writeBareSourceLocation(SourceLocation Loc, bool IsSpelling);
153 
154   // Writes the attributes of a SourceLocation to JSON based on its presumed
155   // spelling location. If the given location represents a macro invocation,
156   // this outputs two sub-objects: one for the spelling and one for the
157   // expansion location.
158   void writeSourceLocation(SourceLocation Loc);
159   void writeSourceRange(SourceRange R);
160   std::string createPointerRepresentation(const void *Ptr);
161   llvm::json::Object createQualType(QualType QT, bool Desugar = true);
162   llvm::json::Object createBareDeclRef(const Decl *D);
163   void writeBareDeclRef(const Decl *D);
164   llvm::json::Object createCXXRecordDefinitionData(const CXXRecordDecl *RD);
165   llvm::json::Object createCXXBaseSpecifier(const CXXBaseSpecifier &BS);
166   std::string createAccessSpecifier(AccessSpecifier AS);
167   llvm::json::Array createCastPath(const CastExpr *C);
168 
writePreviousDeclImpl(...)169   void writePreviousDeclImpl(...) {}
170 
writePreviousDeclImpl(const Mergeable<T> * D)171   template <typename T> void writePreviousDeclImpl(const Mergeable<T> *D) {
172     const T *First = D->getFirstDecl();
173     if (First != D)
174       JOS.attribute("firstRedecl", createPointerRepresentation(First));
175   }
176 
writePreviousDeclImpl(const Redeclarable<T> * D)177   template <typename T> void writePreviousDeclImpl(const Redeclarable<T> *D) {
178     const T *Prev = D->getPreviousDecl();
179     if (Prev)
180       JOS.attribute("previousDecl", createPointerRepresentation(Prev));
181   }
182   void addPreviousDeclaration(const Decl *D);
183 
184   StringRef getCommentCommandName(unsigned CommandID) const;
185 
186 public:
JSONNodeDumper(raw_ostream & OS,const SourceManager & SrcMgr,ASTContext & Ctx,const PrintingPolicy & PrintPolicy,const comments::CommandTraits * Traits)187   JSONNodeDumper(raw_ostream &OS, const SourceManager &SrcMgr, ASTContext &Ctx,
188                  const PrintingPolicy &PrintPolicy,
189                  const comments::CommandTraits *Traits)
190       : NodeStreamer(OS), SM(SrcMgr), Ctx(Ctx), ASTNameGen(Ctx),
191         PrintPolicy(PrintPolicy), Traits(Traits), LastLocLine(0),
192         LastLocPresumedLine(0) {}
193 
194   void Visit(const Attr *A);
195   void Visit(const Stmt *Node);
196   void Visit(const Type *T);
197   void Visit(QualType T);
198   void Visit(const Decl *D);
199 
200   void Visit(const comments::Comment *C, const comments::FullComment *FC);
201   void Visit(const TemplateArgument &TA, SourceRange R = {},
202              const Decl *From = nullptr, StringRef Label = {});
203   void Visit(const CXXCtorInitializer *Init);
204   void Visit(const OMPClause *C);
205   void Visit(const BlockDecl::Capture &C);
206   void Visit(const GenericSelectionExpr::ConstAssociation &A);
207   void Visit(const concepts::Requirement *R);
208   void Visit(const APValue &Value, QualType Ty);
209 
210   void VisitTypedefType(const TypedefType *TT);
211   void VisitFunctionType(const FunctionType *T);
212   void VisitFunctionProtoType(const FunctionProtoType *T);
213   void VisitRValueReferenceType(const ReferenceType *RT);
214   void VisitArrayType(const ArrayType *AT);
215   void VisitConstantArrayType(const ConstantArrayType *CAT);
216   void VisitDependentSizedExtVectorType(const DependentSizedExtVectorType *VT);
217   void VisitVectorType(const VectorType *VT);
218   void VisitUnresolvedUsingType(const UnresolvedUsingType *UUT);
219   void VisitUnaryTransformType(const UnaryTransformType *UTT);
220   void VisitTagType(const TagType *TT);
221   void VisitTemplateTypeParmType(const TemplateTypeParmType *TTPT);
222   void VisitAutoType(const AutoType *AT);
223   void VisitTemplateSpecializationType(const TemplateSpecializationType *TST);
224   void VisitInjectedClassNameType(const InjectedClassNameType *ICNT);
225   void VisitObjCInterfaceType(const ObjCInterfaceType *OIT);
226   void VisitPackExpansionType(const PackExpansionType *PET);
227   void VisitElaboratedType(const ElaboratedType *ET);
228   void VisitMacroQualifiedType(const MacroQualifiedType *MQT);
229   void VisitMemberPointerType(const MemberPointerType *MPT);
230 
231   void VisitNamedDecl(const NamedDecl *ND);
232   void VisitTypedefDecl(const TypedefDecl *TD);
233   void VisitTypeAliasDecl(const TypeAliasDecl *TAD);
234   void VisitNamespaceDecl(const NamespaceDecl *ND);
235   void VisitUsingDirectiveDecl(const UsingDirectiveDecl *UDD);
236   void VisitNamespaceAliasDecl(const NamespaceAliasDecl *NAD);
237   void VisitUsingDecl(const UsingDecl *UD);
238   void VisitUsingEnumDecl(const UsingEnumDecl *UED);
239   void VisitUsingShadowDecl(const UsingShadowDecl *USD);
240   void VisitVarDecl(const VarDecl *VD);
241   void VisitFieldDecl(const FieldDecl *FD);
242   void VisitFunctionDecl(const FunctionDecl *FD);
243   void VisitEnumDecl(const EnumDecl *ED);
244   void VisitEnumConstantDecl(const EnumConstantDecl *ECD);
245   void VisitRecordDecl(const RecordDecl *RD);
246   void VisitCXXRecordDecl(const CXXRecordDecl *RD);
247   void VisitTemplateTypeParmDecl(const TemplateTypeParmDecl *D);
248   void VisitNonTypeTemplateParmDecl(const NonTypeTemplateParmDecl *D);
249   void VisitTemplateTemplateParmDecl(const TemplateTemplateParmDecl *D);
250   void VisitLinkageSpecDecl(const LinkageSpecDecl *LSD);
251   void VisitAccessSpecDecl(const AccessSpecDecl *ASD);
252   void VisitFriendDecl(const FriendDecl *FD);
253 
254   void VisitObjCIvarDecl(const ObjCIvarDecl *D);
255   void VisitObjCMethodDecl(const ObjCMethodDecl *D);
256   void VisitObjCTypeParamDecl(const ObjCTypeParamDecl *D);
257   void VisitObjCCategoryDecl(const ObjCCategoryDecl *D);
258   void VisitObjCCategoryImplDecl(const ObjCCategoryImplDecl *D);
259   void VisitObjCProtocolDecl(const ObjCProtocolDecl *D);
260   void VisitObjCInterfaceDecl(const ObjCInterfaceDecl *D);
261   void VisitObjCImplementationDecl(const ObjCImplementationDecl *D);
262   void VisitObjCCompatibleAliasDecl(const ObjCCompatibleAliasDecl *D);
263   void VisitObjCPropertyDecl(const ObjCPropertyDecl *D);
264   void VisitObjCPropertyImplDecl(const ObjCPropertyImplDecl *D);
265   void VisitBlockDecl(const BlockDecl *D);
266 
267   void VisitDeclRefExpr(const DeclRefExpr *DRE);
268   void VisitSYCLUniqueStableNameExpr(const SYCLUniqueStableNameExpr *E);
269   void VisitPredefinedExpr(const PredefinedExpr *PE);
270   void VisitUnaryOperator(const UnaryOperator *UO);
271   void VisitBinaryOperator(const BinaryOperator *BO);
272   void VisitCompoundAssignOperator(const CompoundAssignOperator *CAO);
273   void VisitMemberExpr(const MemberExpr *ME);
274   void VisitCXXNewExpr(const CXXNewExpr *NE);
275   void VisitCXXDeleteExpr(const CXXDeleteExpr *DE);
276   void VisitCXXThisExpr(const CXXThisExpr *TE);
277   void VisitCastExpr(const CastExpr *CE);
278   void VisitImplicitCastExpr(const ImplicitCastExpr *ICE);
279   void VisitCallExpr(const CallExpr *CE);
280   void VisitUnaryExprOrTypeTraitExpr(const UnaryExprOrTypeTraitExpr *TTE);
281   void VisitSizeOfPackExpr(const SizeOfPackExpr *SOPE);
282   void VisitUnresolvedLookupExpr(const UnresolvedLookupExpr *ULE);
283   void VisitAddrLabelExpr(const AddrLabelExpr *ALE);
284   void VisitCXXTypeidExpr(const CXXTypeidExpr *CTE);
285   void VisitConstantExpr(const ConstantExpr *CE);
286   void VisitInitListExpr(const InitListExpr *ILE);
287   void VisitGenericSelectionExpr(const GenericSelectionExpr *GSE);
288   void VisitCXXUnresolvedConstructExpr(const CXXUnresolvedConstructExpr *UCE);
289   void VisitCXXConstructExpr(const CXXConstructExpr *CE);
290   void VisitExprWithCleanups(const ExprWithCleanups *EWC);
291   void VisitCXXBindTemporaryExpr(const CXXBindTemporaryExpr *BTE);
292   void VisitMaterializeTemporaryExpr(const MaterializeTemporaryExpr *MTE);
293   void VisitCXXDependentScopeMemberExpr(const CXXDependentScopeMemberExpr *ME);
294   void VisitRequiresExpr(const RequiresExpr *RE);
295 
296   void VisitObjCEncodeExpr(const ObjCEncodeExpr *OEE);
297   void VisitObjCMessageExpr(const ObjCMessageExpr *OME);
298   void VisitObjCBoxedExpr(const ObjCBoxedExpr *OBE);
299   void VisitObjCSelectorExpr(const ObjCSelectorExpr *OSE);
300   void VisitObjCProtocolExpr(const ObjCProtocolExpr *OPE);
301   void VisitObjCPropertyRefExpr(const ObjCPropertyRefExpr *OPRE);
302   void VisitObjCSubscriptRefExpr(const ObjCSubscriptRefExpr *OSRE);
303   void VisitObjCIvarRefExpr(const ObjCIvarRefExpr *OIRE);
304   void VisitObjCBoolLiteralExpr(const ObjCBoolLiteralExpr *OBLE);
305 
306   void VisitIntegerLiteral(const IntegerLiteral *IL);
307   void VisitCharacterLiteral(const CharacterLiteral *CL);
308   void VisitFixedPointLiteral(const FixedPointLiteral *FPL);
309   void VisitFloatingLiteral(const FloatingLiteral *FL);
310   void VisitStringLiteral(const StringLiteral *SL);
311   void VisitCXXBoolLiteralExpr(const CXXBoolLiteralExpr *BLE);
312 
313   void VisitIfStmt(const IfStmt *IS);
314   void VisitSwitchStmt(const SwitchStmt *SS);
315   void VisitCaseStmt(const CaseStmt *CS);
316   void VisitLabelStmt(const LabelStmt *LS);
317   void VisitGotoStmt(const GotoStmt *GS);
318   void VisitWhileStmt(const WhileStmt *WS);
319   void VisitObjCAtCatchStmt(const ObjCAtCatchStmt *OACS);
320 
321   void VisitNullTemplateArgument(const TemplateArgument &TA);
322   void VisitTypeTemplateArgument(const TemplateArgument &TA);
323   void VisitDeclarationTemplateArgument(const TemplateArgument &TA);
324   void VisitNullPtrTemplateArgument(const TemplateArgument &TA);
325   void VisitIntegralTemplateArgument(const TemplateArgument &TA);
326   void VisitTemplateTemplateArgument(const TemplateArgument &TA);
327   void VisitTemplateExpansionTemplateArgument(const TemplateArgument &TA);
328   void VisitExpressionTemplateArgument(const TemplateArgument &TA);
329   void VisitPackTemplateArgument(const TemplateArgument &TA);
330 
331   void visitTextComment(const comments::TextComment *C,
332                         const comments::FullComment *);
333   void visitInlineCommandComment(const comments::InlineCommandComment *C,
334                                  const comments::FullComment *);
335   void visitHTMLStartTagComment(const comments::HTMLStartTagComment *C,
336                                 const comments::FullComment *);
337   void visitHTMLEndTagComment(const comments::HTMLEndTagComment *C,
338                               const comments::FullComment *);
339   void visitBlockCommandComment(const comments::BlockCommandComment *C,
340                                 const comments::FullComment *);
341   void visitParamCommandComment(const comments::ParamCommandComment *C,
342                                 const comments::FullComment *FC);
343   void visitTParamCommandComment(const comments::TParamCommandComment *C,
344                                  const comments::FullComment *FC);
345   void visitVerbatimBlockComment(const comments::VerbatimBlockComment *C,
346                                  const comments::FullComment *);
347   void
348   visitVerbatimBlockLineComment(const comments::VerbatimBlockLineComment *C,
349                                 const comments::FullComment *);
350   void visitVerbatimLineComment(const comments::VerbatimLineComment *C,
351                                 const comments::FullComment *);
352 };
353 
354 class JSONDumper : public ASTNodeTraverser<JSONDumper, JSONNodeDumper> {
355   JSONNodeDumper NodeDumper;
356 
357   template <typename SpecializationDecl>
writeTemplateDeclSpecialization(const SpecializationDecl * SD,bool DumpExplicitInst,bool DumpRefOnly)358   void writeTemplateDeclSpecialization(const SpecializationDecl *SD,
359                                        bool DumpExplicitInst,
360                                        bool DumpRefOnly) {
361     bool DumpedAny = false;
362     for (const auto *RedeclWithBadType : SD->redecls()) {
363       // FIXME: The redecls() range sometimes has elements of a less-specific
364       // type. (In particular, ClassTemplateSpecializationDecl::redecls() gives
365       // us TagDecls, and should give CXXRecordDecls).
366       const auto *Redecl = dyn_cast<SpecializationDecl>(RedeclWithBadType);
367       if (!Redecl) {
368         // Found the injected-class-name for a class template. This will be
369         // dumped as part of its surrounding class so we don't need to dump it
370         // here.
371         assert(isa<CXXRecordDecl>(RedeclWithBadType) &&
372                "expected an injected-class-name");
373         continue;
374       }
375 
376       switch (Redecl->getTemplateSpecializationKind()) {
377       case TSK_ExplicitInstantiationDeclaration:
378       case TSK_ExplicitInstantiationDefinition:
379         if (!DumpExplicitInst)
380           break;
381         LLVM_FALLTHROUGH;
382       case TSK_Undeclared:
383       case TSK_ImplicitInstantiation:
384         if (DumpRefOnly)
385           NodeDumper.AddChild([=] { NodeDumper.writeBareDeclRef(Redecl); });
386         else
387           Visit(Redecl);
388         DumpedAny = true;
389         break;
390       case TSK_ExplicitSpecialization:
391         break;
392       }
393     }
394 
395     // Ensure we dump at least one decl for each specialization.
396     if (!DumpedAny)
397       NodeDumper.AddChild([=] { NodeDumper.writeBareDeclRef(SD); });
398   }
399 
400   template <typename TemplateDecl>
writeTemplateDecl(const TemplateDecl * TD,bool DumpExplicitInst)401   void writeTemplateDecl(const TemplateDecl *TD, bool DumpExplicitInst) {
402     // FIXME: it would be nice to dump template parameters and specializations
403     // to their own named arrays rather than shoving them into the "inner"
404     // array. However, template declarations are currently being handled at the
405     // wrong "level" of the traversal hierarchy and so it is difficult to
406     // achieve without losing information elsewhere.
407 
408     dumpTemplateParameters(TD->getTemplateParameters());
409 
410     Visit(TD->getTemplatedDecl());
411 
412     for (const auto *Child : TD->specializations())
413       writeTemplateDeclSpecialization(Child, DumpExplicitInst,
414                                       !TD->isCanonicalDecl());
415   }
416 
417 public:
JSONDumper(raw_ostream & OS,const SourceManager & SrcMgr,ASTContext & Ctx,const PrintingPolicy & PrintPolicy,const comments::CommandTraits * Traits)418   JSONDumper(raw_ostream &OS, const SourceManager &SrcMgr, ASTContext &Ctx,
419              const PrintingPolicy &PrintPolicy,
420              const comments::CommandTraits *Traits)
421       : NodeDumper(OS, SrcMgr, Ctx, PrintPolicy, Traits) {}
422 
doGetNodeDelegate()423   JSONNodeDumper &doGetNodeDelegate() { return NodeDumper; }
424 
VisitFunctionTemplateDecl(const FunctionTemplateDecl * FTD)425   void VisitFunctionTemplateDecl(const FunctionTemplateDecl *FTD) {
426     writeTemplateDecl(FTD, true);
427   }
VisitClassTemplateDecl(const ClassTemplateDecl * CTD)428   void VisitClassTemplateDecl(const ClassTemplateDecl *CTD) {
429     writeTemplateDecl(CTD, false);
430   }
VisitVarTemplateDecl(const VarTemplateDecl * VTD)431   void VisitVarTemplateDecl(const VarTemplateDecl *VTD) {
432     writeTemplateDecl(VTD, false);
433   }
434 };
435 
436 } // namespace clang
437 
438 #endif // LLVM_CLANG_AST_JSONNODEDUMPER_H
439