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