Ted Kremenek | d2fa566 | 2009-08-26 22:36:44 +0000 | [diff] [blame] | 1 | /*===-- clang-c/Index.h - Indexing Public C Interface -------------*- C -*-===*\ |
| 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 header provides a public inferface to a Clang library for extracting *| |
| 11 | |* high-level symbol information from source files without exposing the full *| |
| 12 | |* Clang C++ API. *| |
| 13 | |* *| |
| 14 | \*===----------------------------------------------------------------------===*/ |
| 15 | |
| 16 | #ifndef CLANG_C_INDEX_H |
| 17 | #define CLANG_C_INDEX_H |
| 18 | |
| 19 | #ifdef __cplusplus |
| 20 | extern "C" { |
| 21 | #endif |
| 22 | |
Steve Naroff | 600866c | 2009-08-27 19:51:58 +0000 | [diff] [blame] | 23 | /* |
| 24 | Clang indeX abstractions. The backing store for the following API's will be |
Steve Naroff | b7cd17c | 2009-09-01 17:13:31 +0000 | [diff] [blame] | 25 | clangs AST file (currently based on PCH). AST files are created as follows: |
Steve Naroff | 600866c | 2009-08-27 19:51:58 +0000 | [diff] [blame] | 26 | |
Steve Naroff | b7cd17c | 2009-09-01 17:13:31 +0000 | [diff] [blame] | 27 | "clang -emit-ast <sourcefile.langsuffix> -o <sourcefile.ast>". |
Steve Naroff | 600866c | 2009-08-27 19:51:58 +0000 | [diff] [blame] | 28 | |
Steve Naroff | 600866c | 2009-08-27 19:51:58 +0000 | [diff] [blame] | 29 | Naming Conventions: To avoid namespace pollution, data types are prefixed |
| 30 | with "CX" and functions are prefixed with "clang_". |
| 31 | */ |
Steve Naroff | 5039819 | 2009-08-28 15:28:48 +0000 | [diff] [blame] | 32 | typedef void *CXIndex; /* An indexing instance. */ |
Steve Naroff | 600866c | 2009-08-27 19:51:58 +0000 | [diff] [blame] | 33 | |
Steve Naroff | 5039819 | 2009-08-28 15:28:48 +0000 | [diff] [blame] | 34 | typedef void *CXTranslationUnit; /* A translation unit instance. */ |
Steve Naroff | 600866c | 2009-08-27 19:51:58 +0000 | [diff] [blame] | 35 | |
Steve Naroff | 5039819 | 2009-08-28 15:28:48 +0000 | [diff] [blame] | 36 | typedef void *CXDecl; /* A specific declaration within a translation unit. */ |
Steve Naroff | 600866c | 2009-08-27 19:51:58 +0000 | [diff] [blame] | 37 | |
Steve Naroff | c857ea4 | 2009-09-02 13:28:54 +0000 | [diff] [blame^] | 38 | /* Cursors represent declarations, definitions, and references. */ |
Steve Naroff | 89922f8 | 2009-08-31 00:59:03 +0000 | [diff] [blame] | 39 | enum CXCursorKind { |
| 40 | CXCursor_Invalid = 0, |
| 41 | |
| 42 | /* Declarations */ |
| 43 | CXCursor_FirstDecl = 1, |
Steve Naroff | c857ea4 | 2009-09-02 13:28:54 +0000 | [diff] [blame^] | 44 | CXCursor_TypedefDecl = 2, |
| 45 | CXCursor_StructDecl = 3, |
| 46 | CXCursor_UnionDecl = 4, |
| 47 | CXCursor_ClassDecl = 5, |
| 48 | CXCursor_EnumDecl = 6, |
| 49 | CXCursor_FieldDecl = 7, |
| 50 | CXCursor_EnumConstantDecl = 8, |
| 51 | CXCursor_FunctionDecl = 9, |
| 52 | CXCursor_VarDecl = 10, |
| 53 | CXCursor_ParmDecl = 11, |
| 54 | CXCursor_ObjCInterfaceDecl = 12, |
| 55 | CXCursor_ObjCCategoryDecl = 13, |
| 56 | CXCursor_ObjCProtocolDecl = 14, |
| 57 | CXCursor_ObjCPropertyDecl = 15, |
| 58 | CXCursor_ObjCIvarDecl = 16, |
| 59 | CXCursor_ObjCInstanceMethodDecl = 17, |
| 60 | CXCursor_ObjCClassMethodDecl = 18, |
| 61 | CXCursor_LastDecl = 18, |
Steve Naroff | 89922f8 | 2009-08-31 00:59:03 +0000 | [diff] [blame] | 62 | |
Steve Naroff | c857ea4 | 2009-09-02 13:28:54 +0000 | [diff] [blame^] | 63 | /* Definitions */ |
| 64 | CXCursor_FirstDefn = 32, |
| 65 | CXCursor_FunctionDefn = 32, |
| 66 | CXCursor_ObjCClassDefn = 33, |
| 67 | CXCursor_ObjCCategoryDefn = 34, |
| 68 | CXCursor_ObjCInstanceMethodDefn = 35, |
| 69 | CXCursor_ObjCClassMethodDefn = 36, |
| 70 | CXCursor_LastDefn = 36, |
| 71 | |
Steve Naroff | 89922f8 | 2009-08-31 00:59:03 +0000 | [diff] [blame] | 72 | /* References */ |
Steve Naroff | c857ea4 | 2009-09-02 13:28:54 +0000 | [diff] [blame^] | 73 | CXCursor_FirstRef = 40, |
| 74 | CXCursor_ObjCClassRef = 41, |
| 75 | CXCursor_ObjCProtocolRef = 42, |
| 76 | CXCursor_ObjCMessageRef = 43, |
| 77 | CXCursor_ObjCSelectorRef = 44, |
| 78 | CXCursor_LastRef = 44 |
Steve Naroff | 600866c | 2009-08-27 19:51:58 +0000 | [diff] [blame] | 79 | }; |
| 80 | |
Steve Naroff | 89922f8 | 2009-08-31 00:59:03 +0000 | [diff] [blame] | 81 | /* A cursor into the CXTranslationUnit. */ |
| 82 | typedef struct { |
| 83 | enum CXCursorKind kind; |
| 84 | CXDecl decl; |
| 85 | |
| 86 | /* FIXME: Handle references. */ |
| 87 | } CXCursor; |
| 88 | |
Steve Naroff | 5039819 | 2009-08-28 15:28:48 +0000 | [diff] [blame] | 89 | /* A unique token for looking up "visible" CXDecls from a CXTranslationUnit. */ |
Steve Naroff | 600866c | 2009-08-27 19:51:58 +0000 | [diff] [blame] | 90 | typedef void *CXEntity; |
| 91 | |
| 92 | CXIndex clang_createIndex(); |
| 93 | |
Steve Naroff | 5039819 | 2009-08-28 15:28:48 +0000 | [diff] [blame] | 94 | CXTranslationUnit clang_createTranslationUnit( |
Steve Naroff | 600866c | 2009-08-27 19:51:58 +0000 | [diff] [blame] | 95 | CXIndex, const char *ast_filename |
| 96 | ); |
| 97 | |
| 98 | /* |
| 99 | Usage: clang_loadTranslationUnit(). Will load the toplevel declarations |
| 100 | within a translation unit, issuing a 'callback' for each one. |
| 101 | |
| 102 | void printObjCInterfaceNames(CXTranslationUnit X, CXCursor C) { |
| 103 | if (clang_getCursorKind(C) == Cursor_Declaration) { |
| 104 | CXDecl D = clang_getCursorDecl(C); |
| 105 | if (clang_getDeclKind(D) == CXDecl_ObjC_interface) |
| 106 | printf("@interface %s in file %s on line %d column %d\n", |
| 107 | clang_getDeclSpelling(D), clang_getCursorSource(C), |
| 108 | clang_getCursorLine(C), clang_getCursorColumn(C)); |
| 109 | } |
| 110 | } |
| 111 | static void usage { |
| 112 | clang_loadTranslationUnit(CXTranslationUnit, printObjCInterfaceNames); |
| 113 | } |
| 114 | */ |
Steve Naroff | 2b8ee6c | 2009-09-01 15:55:40 +0000 | [diff] [blame] | 115 | typedef void *CXClientData; |
| 116 | typedef void (*CXTranslationUnitIterator)(CXTranslationUnit, CXCursor, |
| 117 | CXClientData); |
| 118 | void clang_loadTranslationUnit(CXTranslationUnit, CXTranslationUnitIterator, |
| 119 | CXClientData); |
Steve Naroff | 600866c | 2009-08-27 19:51:58 +0000 | [diff] [blame] | 120 | |
| 121 | /* |
| 122 | Usage: clang_loadDeclaration(). Will load the declaration, issuing a |
| 123 | 'callback' for each declaration/reference within the respective declaration. |
| 124 | |
| 125 | For interface declarations, this will index the super class, protocols, |
| 126 | ivars, methods, etc. For structure declarations, this will index the fields. |
| 127 | For functions, this will index the parameters (and body, for function |
| 128 | definitions), local declarations/references. |
| 129 | |
| 130 | void getInterfaceDetails(CXDecl X, CXCursor C) { |
| 131 | switch (clang_getCursorKind(C)) { |
| 132 | case Cursor_ObjC_ClassRef: |
| 133 | CXDecl SuperClass = clang_getCursorDecl(C); |
| 134 | case Cursor_ObjC_ProtocolRef: |
| 135 | CXDecl AdoptsProtocol = clang_getCursorDecl(C); |
| 136 | case Cursor_Declaration: |
| 137 | CXDecl AnIvarOrMethod = clang_getCursorDecl(C); |
| 138 | } |
| 139 | } |
| 140 | static void usage() { |
| 141 | if (clang_getDeclKind(D) == CXDecl_ObjC_interface) { |
| 142 | clang_loadDeclaration(D, getInterfaceDetails); |
| 143 | } |
| 144 | } |
| 145 | */ |
Steve Naroff | c857ea4 | 2009-09-02 13:28:54 +0000 | [diff] [blame^] | 146 | typedef void (*CXDeclIterator)(CXDecl, CXCursor, CXClientData); |
Steve Naroff | 89922f8 | 2009-08-31 00:59:03 +0000 | [diff] [blame] | 147 | |
Steve Naroff | c857ea4 | 2009-09-02 13:28:54 +0000 | [diff] [blame^] | 148 | void clang_loadDeclaration(CXDecl, CXDeclIterator, CXClientData); |
Steve Naroff | 600866c | 2009-08-27 19:51:58 +0000 | [diff] [blame] | 149 | |
Steve Naroff | 5039819 | 2009-08-28 15:28:48 +0000 | [diff] [blame] | 150 | /* |
| 151 | * CXEntity Operations. |
| 152 | */ |
Steve Naroff | 600866c | 2009-08-27 19:51:58 +0000 | [diff] [blame] | 153 | const char *clang_getDeclarationName(CXEntity); |
| 154 | const char *clang_getURI(CXEntity); |
| 155 | CXEntity clang_getEntity(const char *URI); |
Steve Naroff | 5039819 | 2009-08-28 15:28:48 +0000 | [diff] [blame] | 156 | /* |
| 157 | * CXDecl Operations. |
| 158 | */ |
Steve Naroff | 600866c | 2009-08-27 19:51:58 +0000 | [diff] [blame] | 159 | CXCursor clang_getCursorFromDecl(CXDecl); |
| 160 | CXEntity clang_getEntityFromDecl(CXDecl); |
Steve Naroff | 600866c | 2009-08-27 19:51:58 +0000 | [diff] [blame] | 161 | const char *clang_getDeclSpelling(CXDecl); |
Steve Naroff | 5039819 | 2009-08-28 15:28:48 +0000 | [diff] [blame] | 162 | /* |
| 163 | * CXCursor Operations. |
| 164 | */ |
Steve Naroff | 600866c | 2009-08-27 19:51:58 +0000 | [diff] [blame] | 165 | CXCursor clang_getCursor(CXTranslationUnit, const char *source_name, |
| 166 | unsigned line, unsigned column); |
| 167 | |
Steve Naroff | 5039819 | 2009-08-28 15:28:48 +0000 | [diff] [blame] | 168 | enum CXCursorKind clang_getCursorKind(CXCursor); |
Steve Naroff | 89922f8 | 2009-08-31 00:59:03 +0000 | [diff] [blame] | 169 | unsigned clang_isDeclaration(enum CXCursorKind); |
Steve Naroff | 600866c | 2009-08-27 19:51:58 +0000 | [diff] [blame] | 170 | |
| 171 | unsigned clang_getCursorLine(CXCursor); |
| 172 | unsigned clang_getCursorColumn(CXCursor); |
| 173 | const char *clang_getCursorSource(CXCursor); |
Steve Naroff | 89922f8 | 2009-08-31 00:59:03 +0000 | [diff] [blame] | 174 | const char *clang_getKindSpelling(enum CXCursorKind Kind); |
Steve Naroff | 600866c | 2009-08-27 19:51:58 +0000 | [diff] [blame] | 175 | |
Steve Naroff | 5039819 | 2009-08-28 15:28:48 +0000 | [diff] [blame] | 176 | /* |
| 177 | * If CXCursorKind == Cursor_Reference, then this will return the referenced declaration. |
| 178 | * If CXCursorKind == Cursor_Declaration, then this will return the declaration. |
| 179 | */ |
Steve Naroff | 600866c | 2009-08-27 19:51:58 +0000 | [diff] [blame] | 180 | CXDecl clang_getCursorDecl(CXCursor); |
Ted Kremenek | d2fa566 | 2009-08-26 22:36:44 +0000 | [diff] [blame] | 181 | |
| 182 | #ifdef __cplusplus |
| 183 | } |
| 184 | #endif |
| 185 | #endif |
| 186 | |