Clang Project

clang_source_code/tools/libclang/CXCursor.h
1//===- CXCursor.h - Routines for manipulating CXCursors -------------------===//
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 defines routines for manipulating CXCursors.
10//
11//===----------------------------------------------------------------------===//
12
13#ifndef LLVM_CLANG_TOOLS_LIBCLANG_CXCURSOR_H
14#define LLVM_CLANG_TOOLS_LIBCLANG_CXCURSOR_H
15
16#include "clang-c/Index.h"
17#include "clang/Basic/SourceLocation.h"
18#include "llvm/ADT/PointerUnion.h"
19#include <utility>
20
21namespace clang {
22
23class ASTContext;
24class ASTUnit;
25class Attr;
26class CXXBaseSpecifier;
27class Decl;
28class Expr;
29class FieldDecl;
30class InclusionDirective;
31class LabelStmt;
32class MacroDefinitionRecord;
33class MacroExpansion;
34class NamedDecl;
35class ObjCInterfaceDecl;
36class ObjCProtocolDecl;
37class OverloadedTemplateStorage;
38class OverloadExpr;
39class Stmt;
40class TemplateDecl;
41class TemplateName;
42class TypeDecl;
43class VarDecl;
44class IdentifierInfo;
45
46namespace cxcursor {
47
48CXCursor getCursor(CXTranslationUnit, SourceLocation);
49
50CXCursor MakeCXCursor(const clang::Attr *A, const clang::Decl *Parent,
51                      CXTranslationUnit TU);
52CXCursor MakeCXCursor(const clang::Decl *D, CXTranslationUnit TU,
53                      SourceRange RegionOfInterest = SourceRange(),
54                      bool FirstInDeclGroup = true);
55CXCursor MakeCXCursor(const clang::Stmt *S, const clang::Decl *Parent,
56                      CXTranslationUnit TU,
57                      SourceRange RegionOfInterest = SourceRange());
58CXCursor MakeCXCursorInvalid(CXCursorKind K, CXTranslationUnit TU = nullptr);
59
60/// Create an Objective-C superclass reference at the given location.
61CXCursor MakeCursorObjCSuperClassRef(ObjCInterfaceDecl *Super, 
62                                     SourceLocation Loc, 
63                                     CXTranslationUnit TU);
64
65/// Unpack an ObjCSuperClassRef cursor into the interface it references
66/// and optionally the location where the reference occurred.
67std::pair<const ObjCInterfaceDecl *, SourceLocation>
68  getCursorObjCSuperClassRef(CXCursor C);
69
70/// Create an Objective-C protocol reference at the given location.
71CXCursor MakeCursorObjCProtocolRef(const ObjCProtocolDecl *Proto,
72                                   SourceLocation Loc, 
73                                   CXTranslationUnit TU);
74
75/// Unpack an ObjCProtocolRef cursor into the protocol it references
76/// and optionally the location where the reference occurred.
77std::pair<const ObjCProtocolDecl *, SourceLocation>
78  getCursorObjCProtocolRef(CXCursor C);
79
80/// Create an Objective-C class reference at the given location.
81CXCursor MakeCursorObjCClassRef(const ObjCInterfaceDecl *Class,
82                                SourceLocation Loc, 
83                                CXTranslationUnit TU);
84
85/// Unpack an ObjCClassRef cursor into the class it references
86/// and optionally the location where the reference occurred.
87std::pair<const ObjCInterfaceDecl *, SourceLocation>
88  getCursorObjCClassRef(CXCursor C);
89
90/// Create a type reference at the given location.
91CXCursor MakeCursorTypeRef(const TypeDecl *Type, SourceLocation Loc,
92                           CXTranslationUnit TU);
93                               
94/// Unpack a TypeRef cursor into the class it references
95/// and optionally the location where the reference occurred.
96std::pair<const TypeDecl *, SourceLocation> getCursorTypeRef(CXCursor C);
97
98/// Create a reference to a template at the given location.
99CXCursor MakeCursorTemplateRef(const TemplateDecl *Template, SourceLocation Loc,
100                               CXTranslationUnit TU);
101
102/// Unpack a TemplateRef cursor into the template it references and
103/// the location where the reference occurred.
104std::pair<const TemplateDecl *, SourceLocation>
105  getCursorTemplateRef(CXCursor C);
106
107/// Create a reference to a namespace or namespace alias at the given 
108/// location.
109CXCursor MakeCursorNamespaceRef(const NamedDecl *NS, SourceLocation Loc,
110                                CXTranslationUnit TU);
111
112/// Unpack a NamespaceRef cursor into the namespace or namespace alias
113/// it references and the location where the reference occurred.
114std::pair<const NamedDecl *, SourceLocation> getCursorNamespaceRef(CXCursor C);
115
116/// Create a reference to a variable at the given location.
117CXCursor MakeCursorVariableRef(const VarDecl *Var, SourceLocation Loc, 
118                               CXTranslationUnit TU);
119
120/// Unpack a VariableRef cursor into the variable it references and the
121/// location where the where the reference occurred.
122std::pair<const VarDecl *, SourceLocation> getCursorVariableRef(CXCursor C);
123
124/// Create a reference to a field at the given location.
125CXCursor MakeCursorMemberRef(const FieldDecl *Field, SourceLocation Loc, 
126                             CXTranslationUnit TU);
127
128/// Unpack a MemberRef cursor into the field it references and the 
129/// location where the reference occurred.
130std::pair<const FieldDecl *, SourceLocation> getCursorMemberRef(CXCursor C);
131
132/// Create a CXX base specifier cursor.
133CXCursor MakeCursorCXXBaseSpecifier(const CXXBaseSpecifier *B,
134                                    CXTranslationUnit TU);
135
136/// Unpack a CXXBaseSpecifier cursor into a CXXBaseSpecifier.
137const CXXBaseSpecifier *getCursorCXXBaseSpecifier(CXCursor C);
138
139/// Create a preprocessing directive cursor.
140CXCursor MakePreprocessingDirectiveCursor(SourceRange Range,
141                                          CXTranslationUnit TU);
142
143/// Unpack a given preprocessing directive to retrieve its source range.
144SourceRange getCursorPreprocessingDirective(CXCursor C);
145
146/// Create a macro definition cursor.
147CXCursor MakeMacroDefinitionCursor(const MacroDefinitionRecord *,
148                                   CXTranslationUnit TU);
149
150/// Unpack a given macro definition cursor to retrieve its
151/// source range.
152const MacroDefinitionRecord *getCursorMacroDefinition(CXCursor C);
153
154/// Create a macro expansion cursor.
155CXCursor MakeMacroExpansionCursor(MacroExpansion *, CXTranslationUnit TU);
156
157/// Create a "pseudo" macro expansion cursor, using a macro definition
158/// and a source location.
159CXCursor MakeMacroExpansionCursor(MacroDefinitionRecord *, SourceLocation Loc,
160                                  CXTranslationUnit TU);
161
162/// Wraps a macro expansion cursor and provides a common interface
163/// for a normal macro expansion cursor or a "pseudo" one.
164///
165/// "Pseudo" macro expansion cursors (essentially a macro definition along with
166/// a source location) are created in special cases, for example they can be
167/// created for identifiers inside macro definitions, if these identifiers are
168/// macro names.
169class MacroExpansionCursor {
170  CXCursor C;
171
172  bool isPseudo() const { return C.data[1] != nullptr; }
173  const MacroDefinitionRecord *getAsMacroDefinition() const {
174    assert(isPseudo());
175    return static_cast<const MacroDefinitionRecord *>(C.data[0]);
176  }
177  const MacroExpansion *getAsMacroExpansion() const {
178    assert(!isPseudo());
179    return static_cast<const MacroExpansion *>(C.data[0]);
180  }
181  SourceLocation getPseudoLoc() const {
182    assert(isPseudo());
183    return SourceLocation::getFromPtrEncoding(C.data[1]);
184  }
185
186public:
187  MacroExpansionCursor(CXCursor C) : C(C) {
188    assert(C.kind == CXCursor_MacroExpansion);
189  }
190
191  const IdentifierInfo *getName() const;
192  const MacroDefinitionRecord *getDefinition() const;
193  SourceRange getSourceRange() const;
194};
195
196/// Unpack a given macro expansion cursor to retrieve its info.
197static inline MacroExpansionCursor getCursorMacroExpansion(CXCursor C) {
198  return C;
199}
200
201/// Create an inclusion directive cursor.
202CXCursor MakeInclusionDirectiveCursor(InclusionDirective *,
203                                      CXTranslationUnit TU);
204
205/// Unpack a given inclusion directive cursor to retrieve its
206/// source range.
207const InclusionDirective *getCursorInclusionDirective(CXCursor C);
208
209/// Create a label reference at the given location.
210CXCursor MakeCursorLabelRef(LabelStmt *Label, SourceLocation Loc,
211                            CXTranslationUnit TU);
212
213/// Unpack a label reference into the label statement it refers to and
214/// the location of the reference.
215std::pair<const LabelStmt *, SourceLocation> getCursorLabelRef(CXCursor C);
216
217/// Create a overloaded declaration reference cursor for an expression.
218CXCursor MakeCursorOverloadedDeclRef(const OverloadExpr *E,
219                                     CXTranslationUnit TU);
220
221/// Create a overloaded declaration reference cursor for a declaration.
222CXCursor MakeCursorOverloadedDeclRef(const Decl *D, SourceLocation Location,
223                                     CXTranslationUnit TU);
224
225/// Create a overloaded declaration reference cursor for a template name.
226CXCursor MakeCursorOverloadedDeclRef(TemplateName Template, 
227                                     SourceLocation Location,
228                                     CXTranslationUnit TU);
229
230/// Internal storage for an overloaded declaration reference cursor;
231typedef llvm::PointerUnion3<const OverloadExpr *, const Decl *,
232                            OverloadedTemplateStorage *>
233  OverloadedDeclRefStorage;
234
235/// Unpack an overloaded declaration reference into an expression,
236/// declaration, or template name along with the source location.
237std::pair<OverloadedDeclRefStorage, SourceLocation>
238  getCursorOverloadedDeclRef(CXCursor C);
239
240const Decl *getCursorDecl(CXCursor Cursor);
241const Expr *getCursorExpr(CXCursor Cursor);
242const Stmt *getCursorStmt(CXCursor Cursor);
243const Attr *getCursorAttr(CXCursor Cursor);
244
245ASTContext &getCursorContext(CXCursor Cursor);
246ASTUnit *getCursorASTUnit(CXCursor Cursor);
247CXTranslationUnit getCursorTU(CXCursor Cursor);
248
249void getOverriddenCursors(CXCursor cursor,
250                          SmallVectorImpl<CXCursor> &overridden);
251
252/// Create an opaque pool used for fast generation of overridden
253/// CXCursor arrays.
254void *createOverridenCXCursorsPool();
255
256/// Dispose of the overridden CXCursors pool.
257void disposeOverridenCXCursorsPool(void *pool);
258
259/// Returns a index/location pair for a selector identifier if the cursor
260/// points to one.
261std::pair<int, SourceLocation> getSelectorIdentifierIndexAndLoc(CXCursor);
262static inline int getSelectorIdentifierIndex(CXCursor cursor) {
263  return getSelectorIdentifierIndexAndLoc(cursor).first;
264}
265static inline SourceLocation getSelectorIdentifierLoc(CXCursor cursor) {
266  return getSelectorIdentifierIndexAndLoc(cursor).second;
267}
268
269CXCursor getSelectorIdentifierCursor(int SelIdx, CXCursor cursor);
270
271static inline CXCursor getTypeRefedCallExprCursor(CXCursor cursor) {
272  CXCursor newCursor = cursor;
273  if (cursor.kind == CXCursor_CallExpr)
274    newCursor.xdata = 1;
275  return newCursor;
276}
277
278CXCursor getTypeRefCursor(CXCursor cursor);
279
280/// Generate a USR for \arg D and put it in \arg Buf.
281/// \returns true if no USR was computed or the result should be ignored,
282/// false otherwise.
283bool getDeclCursorUSR(const Decl *D, SmallVectorImpl<char> &Buf);
284
285bool operator==(CXCursor X, CXCursor Y);
286
287inline bool operator!=(CXCursor X, CXCursor Y) {
288  return !(X == Y);
289}
290
291/// Return true if the cursor represents a declaration that is the
292/// first in a declaration group.
293bool isFirstInDeclGroup(CXCursor C);
294
295}} // end namespace: clang::cxcursor
296
297#endif
298
clang::cxcursor::MacroExpansionCursor::C
clang::cxcursor::MacroExpansionCursor::isPseudo
clang::cxcursor::MacroExpansionCursor::getAsMacroDefinition
clang::cxcursor::MacroExpansionCursor::getAsMacroExpansion
clang::cxcursor::MacroExpansionCursor::getPseudoLoc
clang::cxcursor::MacroExpansionCursor::getName
clang::cxcursor::MacroExpansionCursor::getDefinition
clang::cxcursor::MacroExpansionCursor::getSourceRange
CodeThinker, Enjoy your reading code