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 | |
Steve Naroff | 8814503 | 2009-10-27 14:35:18 +0000 | [diff] [blame] | 19 | #include <sys/stat.h> |
| 20 | |
Ted Kremenek | d2fa566 | 2009-08-26 22:36:44 +0000 | [diff] [blame] | 21 | #ifdef __cplusplus |
| 22 | extern "C" { |
| 23 | #endif |
| 24 | |
Steve Naroff | 8814503 | 2009-10-27 14:35:18 +0000 | [diff] [blame] | 25 | /* MSVC DLL import/export. */ |
John Thompson | 2e06fc8 | 2009-10-27 13:42:56 +0000 | [diff] [blame] | 26 | #ifdef _MSC_VER |
| 27 | #ifdef _CINDEX_LIB_ |
| 28 | #define CINDEX_LINKAGE __declspec(dllexport) |
| 29 | #else |
| 30 | #define CINDEX_LINKAGE __declspec(dllimport) |
| 31 | #endif |
| 32 | #else |
| 33 | #define CINDEX_LINKAGE |
| 34 | #endif |
| 35 | |
Steve Naroff | 600866c | 2009-08-27 19:51:58 +0000 | [diff] [blame] | 36 | /* |
| 37 | 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] | 38 | 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] | 39 | |
Steve Naroff | b7cd17c | 2009-09-01 17:13:31 +0000 | [diff] [blame] | 40 | "clang -emit-ast <sourcefile.langsuffix> -o <sourcefile.ast>". |
Steve Naroff | 600866c | 2009-08-27 19:51:58 +0000 | [diff] [blame] | 41 | |
Steve Naroff | 600866c | 2009-08-27 19:51:58 +0000 | [diff] [blame] | 42 | Naming Conventions: To avoid namespace pollution, data types are prefixed |
| 43 | with "CX" and functions are prefixed with "clang_". |
| 44 | */ |
Steve Naroff | 5039819 | 2009-08-28 15:28:48 +0000 | [diff] [blame] | 45 | typedef void *CXIndex; /* An indexing instance. */ |
Steve Naroff | 600866c | 2009-08-27 19:51:58 +0000 | [diff] [blame] | 46 | |
Steve Naroff | 5039819 | 2009-08-28 15:28:48 +0000 | [diff] [blame] | 47 | typedef void *CXTranslationUnit; /* A translation unit instance. */ |
Steve Naroff | 600866c | 2009-08-27 19:51:58 +0000 | [diff] [blame] | 48 | |
Steve Naroff | 8814503 | 2009-10-27 14:35:18 +0000 | [diff] [blame] | 49 | typedef void *CXFile; /* A source file */ |
Steve Naroff | 5039819 | 2009-08-28 15:28:48 +0000 | [diff] [blame] | 50 | typedef void *CXDecl; /* A specific declaration within a translation unit. */ |
Steve Naroff | fb57042 | 2009-09-22 19:25:29 +0000 | [diff] [blame] | 51 | typedef void *CXStmt; /* A specific statement within a function/method */ |
Steve Naroff | 600866c | 2009-08-27 19:51:58 +0000 | [diff] [blame] | 52 | |
Steve Naroff | c857ea4 | 2009-09-02 13:28:54 +0000 | [diff] [blame] | 53 | /* Cursors represent declarations, definitions, and references. */ |
Steve Naroff | 89922f8 | 2009-08-31 00:59:03 +0000 | [diff] [blame] | 54 | enum CXCursorKind { |
Steve Naroff | 89922f8 | 2009-08-31 00:59:03 +0000 | [diff] [blame] | 55 | /* Declarations */ |
| 56 | CXCursor_FirstDecl = 1, |
Steve Naroff | c857ea4 | 2009-09-02 13:28:54 +0000 | [diff] [blame] | 57 | CXCursor_TypedefDecl = 2, |
| 58 | CXCursor_StructDecl = 3, |
| 59 | CXCursor_UnionDecl = 4, |
| 60 | CXCursor_ClassDecl = 5, |
| 61 | CXCursor_EnumDecl = 6, |
| 62 | CXCursor_FieldDecl = 7, |
| 63 | CXCursor_EnumConstantDecl = 8, |
| 64 | CXCursor_FunctionDecl = 9, |
| 65 | CXCursor_VarDecl = 10, |
| 66 | CXCursor_ParmDecl = 11, |
| 67 | CXCursor_ObjCInterfaceDecl = 12, |
| 68 | CXCursor_ObjCCategoryDecl = 13, |
| 69 | CXCursor_ObjCProtocolDecl = 14, |
| 70 | CXCursor_ObjCPropertyDecl = 15, |
| 71 | CXCursor_ObjCIvarDecl = 16, |
| 72 | CXCursor_ObjCInstanceMethodDecl = 17, |
| 73 | CXCursor_ObjCClassMethodDecl = 18, |
| 74 | CXCursor_LastDecl = 18, |
Steve Naroff | 89922f8 | 2009-08-31 00:59:03 +0000 | [diff] [blame] | 75 | |
Steve Naroff | c857ea4 | 2009-09-02 13:28:54 +0000 | [diff] [blame] | 76 | /* Definitions */ |
| 77 | CXCursor_FirstDefn = 32, |
| 78 | CXCursor_FunctionDefn = 32, |
| 79 | CXCursor_ObjCClassDefn = 33, |
| 80 | CXCursor_ObjCCategoryDefn = 34, |
| 81 | CXCursor_ObjCInstanceMethodDefn = 35, |
| 82 | CXCursor_ObjCClassMethodDefn = 36, |
| 83 | CXCursor_LastDefn = 36, |
| 84 | |
Steve Naroff | 89922f8 | 2009-08-31 00:59:03 +0000 | [diff] [blame] | 85 | /* References */ |
Steve Naroff | fb57042 | 2009-09-22 19:25:29 +0000 | [diff] [blame] | 86 | CXCursor_FirstRef = 40, /* Decl references */ |
Steve Naroff | f334b4e | 2009-09-02 18:26:48 +0000 | [diff] [blame] | 87 | CXCursor_ObjCSuperClassRef = 40, |
| 88 | CXCursor_ObjCProtocolRef = 41, |
Steve Naroff | fb57042 | 2009-09-22 19:25:29 +0000 | [diff] [blame] | 89 | CXCursor_ObjCClassRef = 42, |
| 90 | |
| 91 | CXCursor_ObjCSelectorRef = 43, /* Expression references */ |
| 92 | CXCursor_ObjCIvarRef = 44, |
| 93 | CXCursor_VarRef = 45, |
| 94 | CXCursor_FunctionRef = 46, |
| 95 | CXCursor_EnumConstantRef = 47, |
| 96 | CXCursor_MemberRef = 48, |
| 97 | CXCursor_LastRef = 48, |
Steve Naroff | 77128dd | 2009-09-15 20:25:34 +0000 | [diff] [blame] | 98 | |
| 99 | /* Error conditions */ |
| 100 | CXCursor_FirstInvalid = 70, |
| 101 | CXCursor_InvalidFile = 70, |
| 102 | CXCursor_NoDeclFound = 71, |
| 103 | CXCursor_NotImplemented = 72, |
| 104 | CXCursor_LastInvalid = 72 |
Steve Naroff | 600866c | 2009-08-27 19:51:58 +0000 | [diff] [blame] | 105 | }; |
| 106 | |
Steve Naroff | 89922f8 | 2009-08-31 00:59:03 +0000 | [diff] [blame] | 107 | /* A cursor into the CXTranslationUnit. */ |
Steve Naroff | fb57042 | 2009-09-22 19:25:29 +0000 | [diff] [blame] | 108 | |
Steve Naroff | 89922f8 | 2009-08-31 00:59:03 +0000 | [diff] [blame] | 109 | typedef struct { |
| 110 | enum CXCursorKind kind; |
| 111 | CXDecl decl; |
Steve Naroff | fb57042 | 2009-09-22 19:25:29 +0000 | [diff] [blame] | 112 | CXStmt stmt; /* expression reference */ |
Steve Naroff | 89922f8 | 2009-08-31 00:59:03 +0000 | [diff] [blame] | 113 | } CXCursor; |
| 114 | |
Steve Naroff | 5039819 | 2009-08-28 15:28:48 +0000 | [diff] [blame] | 115 | /* A unique token for looking up "visible" CXDecls from a CXTranslationUnit. */ |
Steve Naroff | e56b4ba | 2009-10-20 14:46:24 +0000 | [diff] [blame] | 116 | typedef void *CXEntity; |
Steve Naroff | 600866c | 2009-08-27 19:51:58 +0000 | [diff] [blame] | 117 | |
Steve Naroff | ef0cef6 | 2009-11-09 17:45:52 +0000 | [diff] [blame] | 118 | /** |
| 119 | * For functions returning a string that might or might not need |
| 120 | * to be internally allocated and freed. |
| 121 | * Use clang_getCString to access the C string value. |
| 122 | * Use clang_disposeString to free the value. |
| 123 | * Treat it as an opaque type. |
| 124 | */ |
| 125 | typedef struct { |
| 126 | const char *Spelling; |
| 127 | /* A 1 value indicates the clang_ indexing API needed to allocate the string |
| 128 | (and it must be freed by clang_disposeString()). */ |
| 129 | int MustFreeString; |
| 130 | } CXString; |
| 131 | |
| 132 | /* Get C string pointer from a CXString. */ |
| 133 | CINDEX_LINKAGE const char *clang_getCString(CXString string); |
| 134 | |
| 135 | /* Free CXString. */ |
| 136 | CINDEX_LINKAGE void clang_disposeString(CXString string); |
| 137 | |
Steve Naroff | e56b4ba | 2009-10-20 14:46:24 +0000 | [diff] [blame] | 138 | /** |
| 139 | * \brief clang_createIndex() provides a shared context for creating |
| 140 | * translation units. It provides two options: |
| 141 | * |
| 142 | * - excludeDeclarationsFromPCH: When non-zero, allows enumeration of "local" |
| 143 | * declarations (when loading any new translation units). A "local" declaration |
| 144 | * is one that belongs in the translation unit itself and not in a precompiled |
| 145 | * header that was used by the translation unit. If zero, all declarations |
| 146 | * will be enumerated. |
| 147 | * |
| 148 | * - displayDiagnostics: when non-zero, diagnostics will be output. If zero, |
| 149 | * diagnostics will be ignored. |
Steve Naroff | b4ece63 | 2009-10-20 16:36:34 +0000 | [diff] [blame] | 150 | * |
| 151 | * Here is an example: |
| 152 | * |
| 153 | * // excludeDeclsFromPCH = 1, displayDiagnostics = 1 |
| 154 | * Idx = clang_createIndex(1, 1); |
| 155 | * |
| 156 | * // IndexTest.pch was produced with the following command: |
| 157 | * // "clang -x c IndexTest.h -emit-ast -o IndexTest.pch" |
| 158 | * TU = clang_createTranslationUnit(Idx, "IndexTest.pch"); |
| 159 | * |
| 160 | * // This will load all the symbols from 'IndexTest.pch' |
| 161 | * clang_loadTranslationUnit(TU, TranslationUnitVisitor, 0); |
| 162 | * clang_disposeTranslationUnit(TU); |
| 163 | * |
| 164 | * // This will load all the symbols from 'IndexTest.c', excluding symbols |
| 165 | * // from 'IndexTest.pch'. |
| 166 | * char *args[] = { "-Xclang", "-include-pch=IndexTest.pch", 0 }; |
| 167 | * TU = clang_createTranslationUnitFromSourceFile(Idx, "IndexTest.c", 2, args); |
| 168 | * clang_loadTranslationUnit(TU, TranslationUnitVisitor, 0); |
| 169 | * clang_disposeTranslationUnit(TU); |
| 170 | * |
| 171 | * This process of creating the 'pch', loading it separately, and using it (via |
| 172 | * -include-pch) allows 'excludeDeclsFromPCH' to remove redundant callbacks |
| 173 | * (which gives the indexer the same performance benefit as the compiler). |
Steve Naroff | e56b4ba | 2009-10-20 14:46:24 +0000 | [diff] [blame] | 174 | */ |
John Thompson | 2e06fc8 | 2009-10-27 13:42:56 +0000 | [diff] [blame] | 175 | CINDEX_LINKAGE CXIndex clang_createIndex(int excludeDeclarationsFromPCH, |
Steve Naroff | e56b4ba | 2009-10-20 14:46:24 +0000 | [diff] [blame] | 176 | int displayDiagnostics); |
John Thompson | 2e06fc8 | 2009-10-27 13:42:56 +0000 | [diff] [blame] | 177 | CINDEX_LINKAGE void clang_disposeIndex(CXIndex); |
Steve Naroff | ef0cef6 | 2009-11-09 17:45:52 +0000 | [diff] [blame] | 178 | CINDEX_LINKAGE CXString clang_getTranslationUnitSpelling(CXTranslationUnit CTUnit); |
Steve Naroff | af08ddc | 2009-09-03 15:49:00 +0000 | [diff] [blame] | 179 | |
Steve Naroff | e56b4ba | 2009-10-20 14:46:24 +0000 | [diff] [blame] | 180 | /* |
| 181 | * \brief Create a translation unit from an AST file (-emit-ast). |
| 182 | */ |
John Thompson | 2e06fc8 | 2009-10-27 13:42:56 +0000 | [diff] [blame] | 183 | CINDEX_LINKAGE CXTranslationUnit clang_createTranslationUnit( |
Steve Naroff | e56b4ba | 2009-10-20 14:46:24 +0000 | [diff] [blame] | 184 | CXIndex, const char *ast_filename |
Steve Naroff | 600866c | 2009-08-27 19:51:58 +0000 | [diff] [blame] | 185 | ); |
Ted Kremenek | 1374598 | 2009-10-19 22:15:09 +0000 | [diff] [blame] | 186 | /** |
| 187 | * \brief Destroy the specified CXTranslationUnit object. |
| 188 | */ |
John Thompson | 2e06fc8 | 2009-10-27 13:42:56 +0000 | [diff] [blame] | 189 | CINDEX_LINKAGE void clang_disposeTranslationUnit(CXTranslationUnit); |
Ted Kremenek | 1374598 | 2009-10-19 22:15:09 +0000 | [diff] [blame] | 190 | |
| 191 | /** |
Steve Naroff | e56b4ba | 2009-10-20 14:46:24 +0000 | [diff] [blame] | 192 | * \brief Return the CXTranslationUnit for a given source file and the provided |
| 193 | * command line arguments one would pass to the compiler. |
| 194 | * |
Ted Kremenek | 139ba86 | 2009-10-22 00:03:57 +0000 | [diff] [blame] | 195 | * Note: The 'source_filename' argument is optional. If the caller provides a NULL pointer, |
| 196 | * the name of the source file is expected to reside in the specified command line arguments. |
| 197 | * |
| 198 | * Note: When encountered in 'clang_command_line_args', the following options are ignored: |
| 199 | * |
| 200 | * '-c' |
| 201 | * '-emit-ast' |
| 202 | * '-fsyntax-only' |
| 203 | * '-o <output file>' (both '-o' and '<output file>' are ignored) |
| 204 | * |
Ted Kremenek | 1374598 | 2009-10-19 22:15:09 +0000 | [diff] [blame] | 205 | */ |
John Thompson | 2e06fc8 | 2009-10-27 13:42:56 +0000 | [diff] [blame] | 206 | CINDEX_LINKAGE CXTranslationUnit clang_createTranslationUnitFromSourceFile( |
Steve Naroff | 5b7d8e2 | 2009-10-15 20:04:39 +0000 | [diff] [blame] | 207 | CXIndex CIdx, |
Ted Kremenek | 139ba86 | 2009-10-22 00:03:57 +0000 | [diff] [blame] | 208 | const char *source_filename /* specify NULL if the source file is in clang_command_line_args */, |
Steve Naroff | 5b7d8e2 | 2009-10-15 20:04:39 +0000 | [diff] [blame] | 209 | int num_clang_command_line_args, |
Steve Naroff | e56b4ba | 2009-10-20 14:46:24 +0000 | [diff] [blame] | 210 | const char **clang_command_line_args |
Steve Naroff | 5b7d8e2 | 2009-10-15 20:04:39 +0000 | [diff] [blame] | 211 | ); |
Steve Naroff | 600866c | 2009-08-27 19:51:58 +0000 | [diff] [blame] | 212 | |
| 213 | /* |
| 214 | Usage: clang_loadTranslationUnit(). Will load the toplevel declarations |
| 215 | within a translation unit, issuing a 'callback' for each one. |
| 216 | |
| 217 | void printObjCInterfaceNames(CXTranslationUnit X, CXCursor C) { |
| 218 | if (clang_getCursorKind(C) == Cursor_Declaration) { |
| 219 | CXDecl D = clang_getCursorDecl(C); |
| 220 | if (clang_getDeclKind(D) == CXDecl_ObjC_interface) |
| 221 | printf("@interface %s in file %s on line %d column %d\n", |
| 222 | clang_getDeclSpelling(D), clang_getCursorSource(C), |
| 223 | clang_getCursorLine(C), clang_getCursorColumn(C)); |
| 224 | } |
| 225 | } |
| 226 | static void usage { |
| 227 | clang_loadTranslationUnit(CXTranslationUnit, printObjCInterfaceNames); |
| 228 | } |
| 229 | */ |
Steve Naroff | 2b8ee6c | 2009-09-01 15:55:40 +0000 | [diff] [blame] | 230 | typedef void *CXClientData; |
| 231 | typedef void (*CXTranslationUnitIterator)(CXTranslationUnit, CXCursor, |
| 232 | CXClientData); |
John Thompson | 2e06fc8 | 2009-10-27 13:42:56 +0000 | [diff] [blame] | 233 | CINDEX_LINKAGE void clang_loadTranslationUnit(CXTranslationUnit, CXTranslationUnitIterator, |
Steve Naroff | 2b8ee6c | 2009-09-01 15:55:40 +0000 | [diff] [blame] | 234 | CXClientData); |
Steve Naroff | 600866c | 2009-08-27 19:51:58 +0000 | [diff] [blame] | 235 | |
| 236 | /* |
| 237 | Usage: clang_loadDeclaration(). Will load the declaration, issuing a |
| 238 | 'callback' for each declaration/reference within the respective declaration. |
| 239 | |
| 240 | For interface declarations, this will index the super class, protocols, |
| 241 | ivars, methods, etc. For structure declarations, this will index the fields. |
| 242 | For functions, this will index the parameters (and body, for function |
| 243 | definitions), local declarations/references. |
| 244 | |
| 245 | void getInterfaceDetails(CXDecl X, CXCursor C) { |
| 246 | switch (clang_getCursorKind(C)) { |
| 247 | case Cursor_ObjC_ClassRef: |
| 248 | CXDecl SuperClass = clang_getCursorDecl(C); |
| 249 | case Cursor_ObjC_ProtocolRef: |
| 250 | CXDecl AdoptsProtocol = clang_getCursorDecl(C); |
| 251 | case Cursor_Declaration: |
| 252 | CXDecl AnIvarOrMethod = clang_getCursorDecl(C); |
| 253 | } |
| 254 | } |
| 255 | static void usage() { |
| 256 | if (clang_getDeclKind(D) == CXDecl_ObjC_interface) { |
| 257 | clang_loadDeclaration(D, getInterfaceDetails); |
| 258 | } |
| 259 | } |
| 260 | */ |
Steve Naroff | c857ea4 | 2009-09-02 13:28:54 +0000 | [diff] [blame] | 261 | typedef void (*CXDeclIterator)(CXDecl, CXCursor, CXClientData); |
Steve Naroff | 89922f8 | 2009-08-31 00:59:03 +0000 | [diff] [blame] | 262 | |
John Thompson | 2e06fc8 | 2009-10-27 13:42:56 +0000 | [diff] [blame] | 263 | CINDEX_LINKAGE void clang_loadDeclaration(CXDecl, CXDeclIterator, CXClientData); |
Steve Naroff | 600866c | 2009-08-27 19:51:58 +0000 | [diff] [blame] | 264 | |
Steve Naroff | 5039819 | 2009-08-28 15:28:48 +0000 | [diff] [blame] | 265 | /* |
Steve Naroff | 8814503 | 2009-10-27 14:35:18 +0000 | [diff] [blame] | 266 | * CXFile Operations. |
| 267 | */ |
Douglas Gregor | 08b0e8d | 2009-10-31 15:48:08 +0000 | [diff] [blame] | 268 | CINDEX_LINKAGE const char *clang_getFileName(CXFile SFile); |
| 269 | CINDEX_LINKAGE time_t clang_getFileTime(CXFile SFile); |
Steve Naroff | 8814503 | 2009-10-27 14:35:18 +0000 | [diff] [blame] | 270 | |
| 271 | /* |
Steve Naroff | 5039819 | 2009-08-28 15:28:48 +0000 | [diff] [blame] | 272 | * CXEntity Operations. |
| 273 | */ |
John Thompson | 2e06fc8 | 2009-10-27 13:42:56 +0000 | [diff] [blame] | 274 | CINDEX_LINKAGE const char *clang_getDeclarationName(CXEntity); |
| 275 | CINDEX_LINKAGE const char *clang_getURI(CXEntity); |
| 276 | CINDEX_LINKAGE CXEntity clang_getEntity(const char *URI); |
Steve Naroff | 5039819 | 2009-08-28 15:28:48 +0000 | [diff] [blame] | 277 | /* |
| 278 | * CXDecl Operations. |
| 279 | */ |
John Thompson | 2e06fc8 | 2009-10-27 13:42:56 +0000 | [diff] [blame] | 280 | CINDEX_LINKAGE CXCursor clang_getCursorFromDecl(CXDecl); |
| 281 | CINDEX_LINKAGE CXEntity clang_getEntityFromDecl(CXDecl); |
Steve Naroff | ef0cef6 | 2009-11-09 17:45:52 +0000 | [diff] [blame] | 282 | CINDEX_LINKAGE CXString clang_getDeclSpelling(CXDecl); |
John Thompson | 2e06fc8 | 2009-10-27 13:42:56 +0000 | [diff] [blame] | 283 | CINDEX_LINKAGE unsigned clang_getDeclLine(CXDecl); |
| 284 | CINDEX_LINKAGE unsigned clang_getDeclColumn(CXDecl); |
Steve Naroff | 8814503 | 2009-10-27 14:35:18 +0000 | [diff] [blame] | 285 | CINDEX_LINKAGE const char *clang_getDeclSource(CXDecl); /* deprecate */ |
| 286 | CINDEX_LINKAGE CXFile clang_getDeclSourceFile(CXDecl); |
Steve Naroff | 699a07d | 2009-09-25 21:32:34 +0000 | [diff] [blame] | 287 | |
Steve Naroff | 5039819 | 2009-08-28 15:28:48 +0000 | [diff] [blame] | 288 | /* |
| 289 | * CXCursor Operations. |
| 290 | */ |
Steve Naroff | 6a6de8b | 2009-10-21 13:56:23 +0000 | [diff] [blame] | 291 | /** |
| 292 | Usage: clang_getCursor() will translate a source/line/column position |
| 293 | into an AST cursor (to derive semantic information from the source code). |
Steve Naroff | 6a6de8b | 2009-10-21 13:56:23 +0000 | [diff] [blame] | 294 | */ |
John Thompson | 2e06fc8 | 2009-10-27 13:42:56 +0000 | [diff] [blame] | 295 | CINDEX_LINKAGE CXCursor clang_getCursor(CXTranslationUnit, const char *source_name, |
Ted Kremenek | fbcb2b7 | 2009-10-22 17:22:53 +0000 | [diff] [blame] | 296 | unsigned line, unsigned column); |
Ted Kremenek | 7388555 | 2009-11-17 19:28:59 +0000 | [diff] [blame^] | 297 | |
| 298 | CINDEX_LINKAGE CXCursor clang_getNullCursor(void); |
Ted Kremenek | fbcb2b7 | 2009-10-22 17:22:53 +0000 | [diff] [blame] | 299 | |
John Thompson | 2e06fc8 | 2009-10-27 13:42:56 +0000 | [diff] [blame] | 300 | CINDEX_LINKAGE enum CXCursorKind clang_getCursorKind(CXCursor); |
| 301 | CINDEX_LINKAGE unsigned clang_isDeclaration(enum CXCursorKind); |
| 302 | CINDEX_LINKAGE unsigned clang_isReference(enum CXCursorKind); |
| 303 | CINDEX_LINKAGE unsigned clang_isDefinition(enum CXCursorKind); |
| 304 | CINDEX_LINKAGE unsigned clang_isInvalid(enum CXCursorKind); |
Steve Naroff | 600866c | 2009-08-27 19:51:58 +0000 | [diff] [blame] | 305 | |
Ted Kremenek | 7388555 | 2009-11-17 19:28:59 +0000 | [diff] [blame^] | 306 | CINDEX_LINKAGE unsigned clang_equalCursors(CXCursor, CXCursor); |
| 307 | |
John Thompson | 2e06fc8 | 2009-10-27 13:42:56 +0000 | [diff] [blame] | 308 | CINDEX_LINKAGE unsigned clang_getCursorLine(CXCursor); |
| 309 | CINDEX_LINKAGE unsigned clang_getCursorColumn(CXCursor); |
Steve Naroff | ef0cef6 | 2009-11-09 17:45:52 +0000 | [diff] [blame] | 310 | CINDEX_LINKAGE CXString clang_getCursorSpelling(CXCursor); |
Steve Naroff | 8814503 | 2009-10-27 14:35:18 +0000 | [diff] [blame] | 311 | CINDEX_LINKAGE const char *clang_getCursorSource(CXCursor); /* deprecate */ |
| 312 | CINDEX_LINKAGE CXFile clang_getCursorSourceFile(CXCursor); |
Steve Naroff | f334b4e | 2009-09-02 18:26:48 +0000 | [diff] [blame] | 313 | |
Steve Naroff | 4ade6d6 | 2009-09-23 17:52:52 +0000 | [diff] [blame] | 314 | /* for debug/testing */ |
John Thompson | 2e06fc8 | 2009-10-27 13:42:56 +0000 | [diff] [blame] | 315 | CINDEX_LINKAGE const char *clang_getCursorKindSpelling(enum CXCursorKind Kind); |
| 316 | CINDEX_LINKAGE void clang_getDefinitionSpellingAndExtent(CXCursor, |
Steve Naroff | 4ade6d6 | 2009-09-23 17:52:52 +0000 | [diff] [blame] | 317 | const char **startBuf, |
| 318 | const char **endBuf, |
| 319 | unsigned *startLine, |
| 320 | unsigned *startColumn, |
| 321 | unsigned *endLine, |
| 322 | unsigned *endColumn); |
Steve Naroff | 600866c | 2009-08-27 19:51:58 +0000 | [diff] [blame] | 323 | |
Steve Naroff | 5039819 | 2009-08-28 15:28:48 +0000 | [diff] [blame] | 324 | /* |
Chris Lattner | 459789b | 2009-09-16 20:18:54 +0000 | [diff] [blame] | 325 | * If CXCursorKind == Cursor_Reference, then this will return the referenced |
| 326 | * declaration. |
Steve Naroff | 5039819 | 2009-08-28 15:28:48 +0000 | [diff] [blame] | 327 | * If CXCursorKind == Cursor_Declaration, then this will return the declaration. |
| 328 | */ |
John Thompson | 2e06fc8 | 2009-10-27 13:42:56 +0000 | [diff] [blame] | 329 | CINDEX_LINKAGE CXDecl clang_getCursorDecl(CXCursor); |
Ted Kremenek | d2fa566 | 2009-08-26 22:36:44 +0000 | [diff] [blame] | 330 | |
Douglas Gregor | 0c8296d | 2009-11-07 00:00:49 +0000 | [diff] [blame] | 331 | /** |
| 332 | * \brief A semantic string that describes a code-completion result. |
| 333 | * |
| 334 | * A semantic string that describes the formatting of a code-completion |
| 335 | * result as a single "template" of text that should be inserted into the |
| 336 | * source buffer when a particular code-completion result is selected. |
| 337 | * Each semantic string is made up of some number of "chunks", each of which |
| 338 | * contains some text along with a description of what that text means, e.g., |
| 339 | * the name of the entity being referenced, whether the text chunk is part of |
| 340 | * the template, or whether it is a "placeholder" that the user should replace |
| 341 | * with actual code,of a specific kind. See \c CXCompletionChunkKind for a |
| 342 | * description of the different kinds of chunks. |
| 343 | */ |
| 344 | typedef void *CXCompletionString; |
| 345 | |
| 346 | /** |
| 347 | * \brief A single result of code completion. |
| 348 | */ |
| 349 | typedef struct { |
| 350 | /** |
| 351 | * \brief The kind of entity that this completion refers to. |
| 352 | * |
| 353 | * The cursor kind will be a macro, keyword, or a declaration (one of the |
| 354 | * *Decl cursor kinds), describing the entity that the completion is |
| 355 | * referring to. |
| 356 | * |
| 357 | * \todo In the future, we would like to provide a full cursor, to allow |
| 358 | * the client to extract additional information from declaration. |
| 359 | */ |
| 360 | enum CXCursorKind CursorKind; |
| 361 | |
| 362 | /** |
| 363 | * \brief The code-completion string that describes how to insert this |
| 364 | * code-completion result into the editing buffer. |
| 365 | */ |
| 366 | CXCompletionString CompletionString; |
| 367 | } CXCompletionResult; |
| 368 | |
| 369 | /** |
| 370 | * \brief Describes a single piece of text within a code-completion string. |
| 371 | * |
| 372 | * Each "chunk" within a code-completion string (\c CXCompletionString) is |
| 373 | * either a piece of text with a specific "kind" that describes how that text |
| 374 | * should be interpreted by the client or is another completion string. |
| 375 | */ |
| 376 | enum CXCompletionChunkKind { |
| 377 | /** |
| 378 | * \brief A code-completion string that describes "optional" text that |
| 379 | * could be a part of the template (but is not required). |
| 380 | * |
| 381 | * The Optional chunk is the only kind of chunk that has a code-completion |
| 382 | * string for its representation, which is accessible via |
| 383 | * \c clang_getCompletionChunkCompletionString(). The code-completion string |
| 384 | * describes an additional part of the template that is completely optional. |
| 385 | * For example, optional chunks can be used to describe the placeholders for |
| 386 | * arguments that match up with defaulted function parameters, e.g. given: |
| 387 | * |
| 388 | * \code |
| 389 | * void f(int x, float y = 3.14, double z = 2.71828); |
| 390 | * \endcode |
| 391 | * |
| 392 | * The code-completion string for this function would contain: |
| 393 | * - a TypedText chunk for "f". |
| 394 | * - a LeftParen chunk for "(". |
| 395 | * - a Placeholder chunk for "int x" |
| 396 | * - an Optional chunk containing the remaining defaulted arguments, e.g., |
| 397 | * - a Comma chunk for "," |
| 398 | * - a Placeholder chunk for "float x" |
| 399 | * - an Optional chunk containing the last defaulted argument: |
| 400 | * - a Comma chunk for "," |
| 401 | * - a Placeholder chunk for "double z" |
| 402 | * - a RightParen chunk for ")" |
| 403 | * |
| 404 | * There are many ways two handle Optional chunks. Two simple approaches are: |
| 405 | * - Completely ignore optional chunks, in which case the template for the |
| 406 | * function "f" would only include the first parameter ("int x"). |
| 407 | * - Fully expand all optional chunks, in which case the template for the |
| 408 | * function "f" would have all of the parameters. |
| 409 | */ |
| 410 | CXCompletionChunk_Optional, |
| 411 | /** |
| 412 | * \brief Text that a user would be expected to type to get this |
| 413 | * code-completion result. |
| 414 | * |
| 415 | * There will be exactly one "typed text" chunk in a semantic string, which |
| 416 | * will typically provide the spelling of a keyword or the name of a |
| 417 | * declaration that could be used at the current code point. Clients are |
| 418 | * expected to filter the code-completion results based on the text in this |
| 419 | * chunk. |
| 420 | */ |
| 421 | CXCompletionChunk_TypedText, |
| 422 | /** |
| 423 | * \brief Text that should be inserted as part of a code-completion result. |
| 424 | * |
| 425 | * A "text" chunk represents text that is part of the template to be |
| 426 | * inserted into user code should this particular code-completion result |
| 427 | * be selected. |
| 428 | */ |
| 429 | CXCompletionChunk_Text, |
| 430 | /** |
| 431 | * \brief Placeholder text that should be replaced by the user. |
| 432 | * |
| 433 | * A "placeholder" chunk marks a place where the user should insert text |
| 434 | * into the code-completion template. For example, placeholders might mark |
| 435 | * the function parameters for a function declaration, to indicate that the |
| 436 | * user should provide arguments for each of those parameters. The actual |
| 437 | * text in a placeholder is a suggestion for the text to display before |
| 438 | * the user replaces the placeholder with real code. |
| 439 | */ |
| 440 | CXCompletionChunk_Placeholder, |
| 441 | /** |
| 442 | * \brief Informative text that should be displayed but never inserted as |
| 443 | * part of the template. |
| 444 | * |
| 445 | * An "informative" chunk contains annotations that can be displayed to |
| 446 | * help the user decide whether a particular code-completion result is the |
| 447 | * right option, but which is not part of the actual template to be inserted |
| 448 | * by code completion. |
| 449 | */ |
| 450 | CXCompletionChunk_Informative, |
| 451 | /** |
| 452 | * \brief Text that describes the current parameter when code-completion is |
| 453 | * referring to function call, message send, or template specialization. |
| 454 | * |
| 455 | * A "current parameter" chunk occurs when code-completion is providing |
| 456 | * information about a parameter corresponding to the argument at the |
| 457 | * code-completion point. For example, given a function |
| 458 | * |
| 459 | * \code |
| 460 | * int add(int x, int y); |
| 461 | * \endcode |
| 462 | * |
| 463 | * and the source code \c add(, where the code-completion point is after the |
| 464 | * "(", the code-completion string will contain a "current parameter" chunk |
| 465 | * for "int x", indicating that the current argument will initialize that |
| 466 | * parameter. After typing further, to \c add(17, (where the code-completion |
| 467 | * point is after the ","), the code-completion string will contain a |
| 468 | * "current paremeter" chunk to "int y". |
| 469 | */ |
| 470 | CXCompletionChunk_CurrentParameter, |
| 471 | /** |
| 472 | * \brief A left parenthesis ('('), used to initiate a function call or |
| 473 | * signal the beginning of a function parameter list. |
| 474 | */ |
| 475 | CXCompletionChunk_LeftParen, |
| 476 | /** |
| 477 | * \brief A right parenthesis (')'), used to finish a function call or |
| 478 | * signal the end of a function parameter list. |
| 479 | */ |
| 480 | CXCompletionChunk_RightParen, |
| 481 | /** |
| 482 | * \brief A left bracket ('['). |
| 483 | */ |
| 484 | CXCompletionChunk_LeftBracket, |
| 485 | /** |
| 486 | * \brief A right bracket (']'). |
| 487 | */ |
| 488 | CXCompletionChunk_RightBracket, |
| 489 | /** |
| 490 | * \brief A left brace ('{'). |
| 491 | */ |
| 492 | CXCompletionChunk_LeftBrace, |
| 493 | /** |
| 494 | * \brief A right brace ('}'). |
| 495 | */ |
| 496 | CXCompletionChunk_RightBrace, |
| 497 | /** |
| 498 | * \brief A left angle bracket ('<'). |
| 499 | */ |
| 500 | CXCompletionChunk_LeftAngle, |
| 501 | /** |
| 502 | * \brief A right angle bracket ('>'). |
| 503 | */ |
| 504 | CXCompletionChunk_RightAngle, |
| 505 | /** |
| 506 | * \brief A comma separator (','). |
| 507 | */ |
| 508 | CXCompletionChunk_Comma |
| 509 | }; |
| 510 | |
| 511 | /** |
| 512 | * \brief Callback function that receives a single code-completion result. |
| 513 | * |
| 514 | * This callback will be invoked by \c clang_codeComplete() for each |
| 515 | * code-completion result. |
| 516 | * |
| 517 | * \param completion_result a pointer to the current code-completion result, |
| 518 | * providing one possible completion. The pointer itself is only valid |
| 519 | * during the execution of the completion callback. |
| 520 | * |
| 521 | * \param client_data the client data provided to \c clang_codeComplete(). |
| 522 | */ |
| 523 | typedef void (*CXCompletionIterator)(CXCompletionResult *completion_result, |
| 524 | CXClientData client_data); |
| 525 | |
| 526 | /** |
| 527 | * \brief Determine the kind of a particular chunk within a completion string. |
| 528 | * |
| 529 | * \param completion_string the completion string to query. |
| 530 | * |
| 531 | * \param chunk_number the 0-based index of the chunk in the completion string. |
| 532 | * |
| 533 | * \returns the kind of the chunk at the index \c chunk_number. |
| 534 | */ |
| 535 | CINDEX_LINKAGE enum CXCompletionChunkKind |
| 536 | clang_getCompletionChunkKind(CXCompletionString completion_string, |
| 537 | unsigned chunk_number); |
| 538 | |
| 539 | /** |
| 540 | * \brief Retrieve the text associated with a particular chunk within a |
| 541 | * completion string. |
| 542 | * |
| 543 | * \param completion_string the completion string to query. |
| 544 | * |
| 545 | * \param chunk_number the 0-based index of the chunk in the completion string. |
| 546 | * |
| 547 | * \returns the text associated with the chunk at index \c chunk_number. |
| 548 | */ |
| 549 | CINDEX_LINKAGE const char * |
| 550 | clang_getCompletionChunkText(CXCompletionString completion_string, |
| 551 | unsigned chunk_number); |
| 552 | |
| 553 | /** |
| 554 | * \brief Retrieve the completion string associated with a particular chunk |
| 555 | * within a completion string. |
| 556 | * |
| 557 | * \param completion_string the completion string to query. |
| 558 | * |
| 559 | * \param chunk_number the 0-based index of the chunk in the completion string. |
| 560 | * |
| 561 | * \returns the completion string associated with the chunk at index |
| 562 | * \c chunk_number, or NULL if that chunk is not represented by a completion |
| 563 | * string. |
| 564 | */ |
| 565 | CINDEX_LINKAGE CXCompletionString |
| 566 | clang_getCompletionChunkCompletionString(CXCompletionString completion_string, |
| 567 | unsigned chunk_number); |
| 568 | |
| 569 | /** |
| 570 | * \brief Retrieve the number of chunks in the given code-completion string. |
| 571 | */ |
| 572 | CINDEX_LINKAGE unsigned |
| 573 | clang_getNumCompletionChunks(CXCompletionString completion_string); |
| 574 | |
| 575 | /** |
| 576 | * \brief Perform code completion at a given location in a source file. |
| 577 | * |
| 578 | * This function performs code completion at a particular file, line, and |
| 579 | * column within source code, providing results that suggest potential |
| 580 | * code snippets based on the context of the completion. The basic model |
| 581 | * for code completion is that Clang will parse a complete source file, |
| 582 | * performing syntax checking up to the location where code-completion has |
| 583 | * been requested. At that point, a special code-completion token is passed |
| 584 | * to the parser, which recognizes this token and determines, based on the |
| 585 | * current location in the C/Objective-C/C++ grammar and the state of |
| 586 | * semantic analysis, what completions to provide. These completions are |
| 587 | * enumerated through a callback interface to the client. |
| 588 | * |
| 589 | * Code completion itself is meant to be triggered by the client when the |
| 590 | * user types punctuation characters or whitespace, at which point the |
| 591 | * code-completion location will coincide with the cursor. For example, if \c p |
| 592 | * is a pointer, code-completion might be triggered after the "-" and then |
| 593 | * after the ">" in \c p->. When the code-completion location is afer the ">", |
| 594 | * the completion results will provide, e.g., the members of the struct that |
| 595 | * "p" points to. The client is responsible for placing the cursor at the |
| 596 | * beginning of the token currently being typed, then filtering the results |
| 597 | * based on the contents of the token. For example, when code-completing for |
| 598 | * the expression \c p->get, the client should provide the location just after |
| 599 | * the ">" (e.g., pointing at the "g") to this code-completion hook. Then, the |
| 600 | * client can filter the results based on the current token text ("get"), only |
| 601 | * showing those results that start with "get". The intent of this interface |
| 602 | * is to separate the relatively high-latency acquisition of code-competion |
| 603 | * results from the filtering of results on a per-character basis, which must |
| 604 | * have a lower latency. |
| 605 | * |
| 606 | * \param CIdx the \c CXIndex instance that will be used to perform code |
| 607 | * completion. |
| 608 | * |
| 609 | * \param source_filename the name of the source file that should be parsed |
| 610 | * to perform code-completion. This source file must be the same as or |
| 611 | * include the filename described by \p complete_filename, or no code-completion |
Ted Kremenek | 4633d1b | 2009-11-17 18:18:02 +0000 | [diff] [blame] | 612 | * results will be produced. NOTE: One can also specify NULL for this argument if |
| 613 | * the source file is included in command_line_args. |
Douglas Gregor | 0c8296d | 2009-11-07 00:00:49 +0000 | [diff] [blame] | 614 | * |
| 615 | * \param num_command_line_args the number of command-line arguments stored in |
| 616 | * \p command_line_args. |
| 617 | * |
| 618 | * \param command_line_args the command-line arguments to pass to the Clang |
| 619 | * compiler to build the given source file. This should include all of the |
| 620 | * necessary include paths, language-dialect switches, precompiled header |
| 621 | * includes, etc., but should not include any information specific to |
| 622 | * code completion. |
| 623 | * |
| 624 | * \param complete_filename the name of the source file where code completion |
| 625 | * should be performed. In many cases, this name will be the same as the |
| 626 | * source filename. However, the completion filename may also be a file |
| 627 | * included by the source file, which is required when producing |
| 628 | * code-completion results for a header. |
| 629 | * |
| 630 | * \param complete_line the line at which code-completion should occur. |
| 631 | * |
| 632 | * \param complete_column the column at which code-completion should occur. |
| 633 | * Note that the column should point just after the syntactic construct that |
| 634 | * initiated code completion, and not in the middle of a lexical token. |
| 635 | * |
| 636 | * \param completion_iterator a callback function that will receive |
| 637 | * code-completion results. |
| 638 | * |
| 639 | * \param client_data client-specific data that will be passed back via the |
| 640 | * code-completion callback function. |
| 641 | */ |
| 642 | CINDEX_LINKAGE void clang_codeComplete(CXIndex CIdx, |
| 643 | const char *source_filename, |
| 644 | int num_command_line_args, |
| 645 | const char **command_line_args, |
| 646 | const char *complete_filename, |
| 647 | unsigned complete_line, |
| 648 | unsigned complete_column, |
| 649 | CXCompletionIterator completion_iterator, |
| 650 | CXClientData client_data); |
| 651 | |
| 652 | |
Ted Kremenek | d2fa566 | 2009-08-26 22:36:44 +0000 | [diff] [blame] | 653 | #ifdef __cplusplus |
| 654 | } |
| 655 | #endif |
| 656 | #endif |
| 657 | |