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> |
Chandler Carruth | 3d31560 | 2009-12-17 09:27:29 +0000 | [diff] [blame] | 20 | #include <time.h> |
Steve Naroff | 8814503 | 2009-10-27 14:35:18 +0000 | [diff] [blame] | 21 | |
Ted Kremenek | d2fa566 | 2009-08-26 22:36:44 +0000 | [diff] [blame] | 22 | #ifdef __cplusplus |
| 23 | extern "C" { |
| 24 | #endif |
| 25 | |
Steve Naroff | 8814503 | 2009-10-27 14:35:18 +0000 | [diff] [blame] | 26 | /* MSVC DLL import/export. */ |
John Thompson | 2e06fc8 | 2009-10-27 13:42:56 +0000 | [diff] [blame] | 27 | #ifdef _MSC_VER |
| 28 | #ifdef _CINDEX_LIB_ |
| 29 | #define CINDEX_LINKAGE __declspec(dllexport) |
| 30 | #else |
| 31 | #define CINDEX_LINKAGE __declspec(dllimport) |
| 32 | #endif |
| 33 | #else |
| 34 | #define CINDEX_LINKAGE |
| 35 | #endif |
| 36 | |
Douglas Gregor | 20d416c | 2010-01-20 01:10:47 +0000 | [diff] [blame] | 37 | /** \defgroup CINDEX C Interface to Clang |
| 38 | * |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 39 | * The C Interface to Clang provides a relatively small API that exposes |
Douglas Gregor | f552544 | 2010-01-20 22:45:41 +0000 | [diff] [blame] | 40 | * facilities for parsing source code into an abstract syntax tree (AST), |
| 41 | * loading already-parsed ASTs, traversing the AST, associating |
| 42 | * physical source locations with elements within the AST, and other |
| 43 | * facilities that support Clang-based development tools. |
Douglas Gregor | 20d416c | 2010-01-20 01:10:47 +0000 | [diff] [blame] | 44 | * |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 45 | * This C interface to Clang will never provide all of the information |
Douglas Gregor | f552544 | 2010-01-20 22:45:41 +0000 | [diff] [blame] | 46 | * representation stored in Clang's C++ AST, nor should it: the intent is to |
| 47 | * maintain an API that is relatively stable from one release to the next, |
| 48 | * providing only the basic functionality needed to support development tools. |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 49 | * |
| 50 | * To avoid namespace pollution, data types are prefixed with "CX" and |
Douglas Gregor | f552544 | 2010-01-20 22:45:41 +0000 | [diff] [blame] | 51 | * functions are prefixed with "clang_". |
Douglas Gregor | 20d416c | 2010-01-20 01:10:47 +0000 | [diff] [blame] | 52 | * |
| 53 | * @{ |
| 54 | */ |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 55 | |
Douglas Gregor | 7f17376 | 2010-01-20 22:28:27 +0000 | [diff] [blame] | 56 | /** |
| 57 | * \brief An "index" that consists of a set of translation units that would |
| 58 | * typically be linked together into an executable or library. |
| 59 | */ |
| 60 | typedef void *CXIndex; |
Steve Naroff | 600866c | 2009-08-27 19:51:58 +0000 | [diff] [blame] | 61 | |
Douglas Gregor | 7f17376 | 2010-01-20 22:28:27 +0000 | [diff] [blame] | 62 | /** |
| 63 | * \brief A single translation unit, which resides in an index. |
| 64 | */ |
Steve Naroff | 5039819 | 2009-08-28 15:28:48 +0000 | [diff] [blame] | 65 | typedef void *CXTranslationUnit; /* A translation unit instance. */ |
Steve Naroff | 600866c | 2009-08-27 19:51:58 +0000 | [diff] [blame] | 66 | |
Douglas Gregor | 7f17376 | 2010-01-20 22:28:27 +0000 | [diff] [blame] | 67 | /** |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 68 | * \brief Opaque pointer representing client data that will be passed through |
| 69 | * to various callbacks and visitors. |
Douglas Gregor | 7f17376 | 2010-01-20 22:28:27 +0000 | [diff] [blame] | 70 | */ |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 71 | typedef void *CXClientData; |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 72 | |
Douglas Gregor | 735df88 | 2009-12-02 09:21:34 +0000 | [diff] [blame] | 73 | /** |
| 74 | * \brief Provides the contents of a file that has not yet been saved to disk. |
| 75 | * |
| 76 | * Each CXUnsavedFile instance provides the name of a file on the |
| 77 | * system along with the current contents of that file that have not |
| 78 | * yet been saved to disk. |
| 79 | */ |
| 80 | struct CXUnsavedFile { |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 81 | /** |
| 82 | * \brief The file whose contents have not yet been saved. |
Douglas Gregor | 735df88 | 2009-12-02 09:21:34 +0000 | [diff] [blame] | 83 | * |
| 84 | * This file must already exist in the file system. |
| 85 | */ |
| 86 | const char *Filename; |
| 87 | |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 88 | /** |
Douglas Gregor | 735df88 | 2009-12-02 09:21:34 +0000 | [diff] [blame] | 89 | * \brief A null-terminated buffer containing the unsaved contents |
| 90 | * of this file. |
| 91 | */ |
| 92 | const char *Contents; |
| 93 | |
| 94 | /** |
| 95 | * \brief The length of the unsaved contents of this buffer, not |
| 96 | * counting the NULL at the end of the buffer. |
| 97 | */ |
| 98 | unsigned long Length; |
| 99 | }; |
| 100 | |
Douglas Gregor | 7f17376 | 2010-01-20 22:28:27 +0000 | [diff] [blame] | 101 | /** |
Douglas Gregor | 7f17376 | 2010-01-20 22:28:27 +0000 | [diff] [blame] | 102 | * \defgroup CINDEX_STRING String manipulation routines |
| 103 | * |
| 104 | * @{ |
| 105 | */ |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 106 | |
Douglas Gregor | 7f17376 | 2010-01-20 22:28:27 +0000 | [diff] [blame] | 107 | /** |
| 108 | * \brief A character string. |
| 109 | * |
| 110 | * The \c CXString type is used to return strings from the interface when |
| 111 | * the ownership of that string might different from one call to the next. |
| 112 | * Use \c clang_getCString() to retrieve the string data and, once finished |
| 113 | * with the string data, call \c clang_disposeString() to free the string. |
Steve Naroff | ef0cef6 | 2009-11-09 17:45:52 +0000 | [diff] [blame] | 114 | */ |
| 115 | typedef struct { |
| 116 | const char *Spelling; |
| 117 | /* A 1 value indicates the clang_ indexing API needed to allocate the string |
| 118 | (and it must be freed by clang_disposeString()). */ |
| 119 | int MustFreeString; |
| 120 | } CXString; |
| 121 | |
Douglas Gregor | 7f17376 | 2010-01-20 22:28:27 +0000 | [diff] [blame] | 122 | /** |
| 123 | * \brief Retrieve the character data associated with the given string. |
| 124 | */ |
Steve Naroff | ef0cef6 | 2009-11-09 17:45:52 +0000 | [diff] [blame] | 125 | CINDEX_LINKAGE const char *clang_getCString(CXString string); |
| 126 | |
Douglas Gregor | 7f17376 | 2010-01-20 22:28:27 +0000 | [diff] [blame] | 127 | /** |
| 128 | * \brief Free the given string, |
| 129 | */ |
Steve Naroff | ef0cef6 | 2009-11-09 17:45:52 +0000 | [diff] [blame] | 130 | CINDEX_LINKAGE void clang_disposeString(CXString string); |
| 131 | |
Douglas Gregor | 7f17376 | 2010-01-20 22:28:27 +0000 | [diff] [blame] | 132 | /** |
| 133 | * @} |
| 134 | */ |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 135 | |
| 136 | /** |
Steve Naroff | e56b4ba | 2009-10-20 14:46:24 +0000 | [diff] [blame] | 137 | * \brief clang_createIndex() provides a shared context for creating |
| 138 | * translation units. It provides two options: |
| 139 | * |
| 140 | * - excludeDeclarationsFromPCH: When non-zero, allows enumeration of "local" |
| 141 | * declarations (when loading any new translation units). A "local" declaration |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 142 | * is one that belongs in the translation unit itself and not in a precompiled |
Steve Naroff | e56b4ba | 2009-10-20 14:46:24 +0000 | [diff] [blame] | 143 | * header that was used by the translation unit. If zero, all declarations |
| 144 | * will be enumerated. |
| 145 | * |
| 146 | * - displayDiagnostics: when non-zero, diagnostics will be output. If zero, |
| 147 | * diagnostics will be ignored. |
Steve Naroff | b4ece63 | 2009-10-20 16:36:34 +0000 | [diff] [blame] | 148 | * |
| 149 | * Here is an example: |
| 150 | * |
| 151 | * // excludeDeclsFromPCH = 1, displayDiagnostics = 1 |
| 152 | * Idx = clang_createIndex(1, 1); |
| 153 | * |
| 154 | * // IndexTest.pch was produced with the following command: |
| 155 | * // "clang -x c IndexTest.h -emit-ast -o IndexTest.pch" |
| 156 | * TU = clang_createTranslationUnit(Idx, "IndexTest.pch"); |
| 157 | * |
| 158 | * // This will load all the symbols from 'IndexTest.pch' |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 159 | * clang_visitChildren(clang_getTranslationUnitCursor(TU), |
Douglas Gregor | 002a528 | 2010-01-20 21:37:00 +0000 | [diff] [blame] | 160 | * TranslationUnitVisitor, 0); |
Steve Naroff | b4ece63 | 2009-10-20 16:36:34 +0000 | [diff] [blame] | 161 | * clang_disposeTranslationUnit(TU); |
| 162 | * |
| 163 | * // This will load all the symbols from 'IndexTest.c', excluding symbols |
| 164 | * // from 'IndexTest.pch'. |
Daniel Dunbar | fd9f234 | 2010-01-25 00:43:14 +0000 | [diff] [blame] | 165 | * char *args[] = { "-Xclang", "-include-pch=IndexTest.pch" }; |
| 166 | * TU = clang_createTranslationUnitFromSourceFile(Idx, "IndexTest.c", 2, args, |
| 167 | * 0, 0); |
Douglas Gregor | b2cd487 | 2010-01-20 23:57:43 +0000 | [diff] [blame] | 168 | * clang_visitChildren(clang_getTranslationUnitCursor(TU), |
| 169 | * TranslationUnitVisitor, 0); |
Steve Naroff | b4ece63 | 2009-10-20 16:36:34 +0000 | [diff] [blame] | 170 | * clang_disposeTranslationUnit(TU); |
| 171 | * |
| 172 | * This process of creating the 'pch', loading it separately, and using it (via |
| 173 | * -include-pch) allows 'excludeDeclsFromPCH' to remove redundant callbacks |
| 174 | * (which gives the indexer the same performance benefit as the compiler). |
Steve Naroff | e56b4ba | 2009-10-20 14:46:24 +0000 | [diff] [blame] | 175 | */ |
John Thompson | 2e06fc8 | 2009-10-27 13:42:56 +0000 | [diff] [blame] | 176 | CINDEX_LINKAGE CXIndex clang_createIndex(int excludeDeclarationsFromPCH, |
Steve Naroff | e56b4ba | 2009-10-20 14:46:24 +0000 | [diff] [blame] | 177 | int displayDiagnostics); |
Daniel Dunbar | 8506dde | 2009-12-03 01:54:28 +0000 | [diff] [blame] | 178 | CINDEX_LINKAGE void clang_disposeIndex(CXIndex index); |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 179 | |
| 180 | /** |
| 181 | * \brief Get the original translation unit source file name. |
| 182 | */ |
Daniel Dunbar | 8506dde | 2009-12-03 01:54:28 +0000 | [diff] [blame] | 183 | CINDEX_LINKAGE CXString |
| 184 | clang_getTranslationUnitSpelling(CXTranslationUnit CTUnit); |
| 185 | |
Douglas Gregor | 7f17376 | 2010-01-20 22:28:27 +0000 | [diff] [blame] | 186 | /** |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 187 | * \brief Request that AST's be generated externally for API calls which parse |
Daniel Dunbar | 8506dde | 2009-12-03 01:54:28 +0000 | [diff] [blame] | 188 | * source code on the fly, e.g. \see createTranslationUnitFromSourceFile. |
| 189 | * |
| 190 | * Note: This is for debugging purposes only, and may be removed at a later |
| 191 | * date. |
| 192 | * |
| 193 | * \param index - The index to update. |
| 194 | * \param value - The new flag value. |
| 195 | */ |
| 196 | CINDEX_LINKAGE void clang_setUseExternalASTGeneration(CXIndex index, |
| 197 | int value); |
Steve Naroff | af08ddc | 2009-09-03 15:49:00 +0000 | [diff] [blame] | 198 | |
Douglas Gregor | 7f17376 | 2010-01-20 22:28:27 +0000 | [diff] [blame] | 199 | /** |
Steve Naroff | e56b4ba | 2009-10-20 14:46:24 +0000 | [diff] [blame] | 200 | * \brief Create a translation unit from an AST file (-emit-ast). |
| 201 | */ |
John Thompson | 2e06fc8 | 2009-10-27 13:42:56 +0000 | [diff] [blame] | 202 | CINDEX_LINKAGE CXTranslationUnit clang_createTranslationUnit( |
Steve Naroff | e56b4ba | 2009-10-20 14:46:24 +0000 | [diff] [blame] | 203 | CXIndex, const char *ast_filename |
Steve Naroff | 600866c | 2009-08-27 19:51:58 +0000 | [diff] [blame] | 204 | ); |
Daniel Dunbar | 8506dde | 2009-12-03 01:54:28 +0000 | [diff] [blame] | 205 | |
Ted Kremenek | 1374598 | 2009-10-19 22:15:09 +0000 | [diff] [blame] | 206 | /** |
| 207 | * \brief Destroy the specified CXTranslationUnit object. |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 208 | */ |
John Thompson | 2e06fc8 | 2009-10-27 13:42:56 +0000 | [diff] [blame] | 209 | CINDEX_LINKAGE void clang_disposeTranslationUnit(CXTranslationUnit); |
Ted Kremenek | 1374598 | 2009-10-19 22:15:09 +0000 | [diff] [blame] | 210 | |
| 211 | /** |
Steve Naroff | e56b4ba | 2009-10-20 14:46:24 +0000 | [diff] [blame] | 212 | * \brief Return the CXTranslationUnit for a given source file and the provided |
| 213 | * command line arguments one would pass to the compiler. |
| 214 | * |
Daniel Dunbar | 8506dde | 2009-12-03 01:54:28 +0000 | [diff] [blame] | 215 | * Note: The 'source_filename' argument is optional. If the caller provides a |
| 216 | * NULL pointer, the name of the source file is expected to reside in the |
| 217 | * specified command line arguments. |
Ted Kremenek | 139ba86 | 2009-10-22 00:03:57 +0000 | [diff] [blame] | 218 | * |
Daniel Dunbar | 8506dde | 2009-12-03 01:54:28 +0000 | [diff] [blame] | 219 | * Note: When encountered in 'clang_command_line_args', the following options |
| 220 | * are ignored: |
Ted Kremenek | 139ba86 | 2009-10-22 00:03:57 +0000 | [diff] [blame] | 221 | * |
| 222 | * '-c' |
| 223 | * '-emit-ast' |
| 224 | * '-fsyntax-only' |
| 225 | * '-o <output file>' (both '-o' and '<output file>' are ignored) |
| 226 | * |
Daniel Dunbar | 8506dde | 2009-12-03 01:54:28 +0000 | [diff] [blame] | 227 | * |
| 228 | * \param source_filename - The name of the source file to load, or NULL if the |
| 229 | * source file is included in clang_command_line_args. |
Douglas Gregor | 4db64a4 | 2010-01-23 00:14:00 +0000 | [diff] [blame] | 230 | * |
| 231 | * \param num_unsaved_files the number of unsaved file entries in \p |
| 232 | * unsaved_files. |
| 233 | * |
| 234 | * \param unsaved_files the files that have not yet been saved to disk |
| 235 | * but may be required for code completion, including the contents of |
| 236 | * those files. |
Ted Kremenek | 1374598 | 2009-10-19 22:15:09 +0000 | [diff] [blame] | 237 | */ |
John Thompson | 2e06fc8 | 2009-10-27 13:42:56 +0000 | [diff] [blame] | 238 | CINDEX_LINKAGE CXTranslationUnit clang_createTranslationUnitFromSourceFile( |
Douglas Gregor | 4db64a4 | 2010-01-23 00:14:00 +0000 | [diff] [blame] | 239 | CXIndex CIdx, |
| 240 | const char *source_filename, |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 241 | int num_clang_command_line_args, |
Douglas Gregor | 4db64a4 | 2010-01-23 00:14:00 +0000 | [diff] [blame] | 242 | const char **clang_command_line_args, |
| 243 | unsigned num_unsaved_files, |
| 244 | struct CXUnsavedFile *unsaved_files); |
Steve Naroff | 600866c | 2009-08-27 19:51:58 +0000 | [diff] [blame] | 245 | |
Douglas Gregor | 7eaa8ae | 2010-01-20 00:23:15 +0000 | [diff] [blame] | 246 | /** |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 247 | * \defgroup CINDEX_FILES File manipulation routines |
Douglas Gregor | f552544 | 2010-01-20 22:45:41 +0000 | [diff] [blame] | 248 | * |
| 249 | * @{ |
| 250 | */ |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 251 | |
Douglas Gregor | f552544 | 2010-01-20 22:45:41 +0000 | [diff] [blame] | 252 | /** |
| 253 | * \brief A particular source file that is part of a translation unit. |
| 254 | */ |
| 255 | typedef void *CXFile; |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 256 | |
Douglas Gregor | f552544 | 2010-01-20 22:45:41 +0000 | [diff] [blame] | 257 | |
| 258 | /** |
| 259 | * \brief Retrieve the complete file and path name of the given file. |
Steve Naroff | 8814503 | 2009-10-27 14:35:18 +0000 | [diff] [blame] | 260 | */ |
Douglas Gregor | 08b0e8d | 2009-10-31 15:48:08 +0000 | [diff] [blame] | 261 | CINDEX_LINKAGE const char *clang_getFileName(CXFile SFile); |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 262 | |
Douglas Gregor | f552544 | 2010-01-20 22:45:41 +0000 | [diff] [blame] | 263 | /** |
| 264 | * \brief Retrieve the last modification time of the given file. |
| 265 | */ |
Douglas Gregor | 08b0e8d | 2009-10-31 15:48:08 +0000 | [diff] [blame] | 266 | CINDEX_LINKAGE time_t clang_getFileTime(CXFile SFile); |
Steve Naroff | 8814503 | 2009-10-27 14:35:18 +0000 | [diff] [blame] | 267 | |
Douglas Gregor | 3c7313d | 2010-01-18 22:13:09 +0000 | [diff] [blame] | 268 | /** |
Douglas Gregor | b979034 | 2010-01-22 21:44:22 +0000 | [diff] [blame] | 269 | * \brief Retrieve a file handle within the given translation unit. |
| 270 | * |
| 271 | * \param tu the translation unit |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 272 | * |
Douglas Gregor | b979034 | 2010-01-22 21:44:22 +0000 | [diff] [blame] | 273 | * \param file_name the name of the file. |
| 274 | * |
| 275 | * \returns the file handle for the named file in the translation unit \p tu, |
| 276 | * or a NULL file handle if the file was not a part of this translation unit. |
| 277 | */ |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 278 | CINDEX_LINKAGE CXFile clang_getFile(CXTranslationUnit tu, |
Douglas Gregor | b979034 | 2010-01-22 21:44:22 +0000 | [diff] [blame] | 279 | const char *file_name); |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 280 | |
Douglas Gregor | b979034 | 2010-01-22 21:44:22 +0000 | [diff] [blame] | 281 | /** |
Douglas Gregor | f552544 | 2010-01-20 22:45:41 +0000 | [diff] [blame] | 282 | * @} |
| 283 | */ |
| 284 | |
| 285 | /** |
| 286 | * \defgroup CINDEX_LOCATIONS Physical source locations |
| 287 | * |
| 288 | * Clang represents physical source locations in its abstract syntax tree in |
| 289 | * great detail, with file, line, and column information for the majority of |
| 290 | * the tokens parsed in the source code. These data types and functions are |
| 291 | * used to represent source location information, either for a particular |
| 292 | * point in the program or for a range of points in the program, and extract |
| 293 | * specific location information from those data types. |
| 294 | * |
| 295 | * @{ |
| 296 | */ |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 297 | |
Douglas Gregor | f552544 | 2010-01-20 22:45:41 +0000 | [diff] [blame] | 298 | /** |
Douglas Gregor | 1db19de | 2010-01-19 21:36:55 +0000 | [diff] [blame] | 299 | * \brief Identifies a specific source location within a translation |
| 300 | * unit. |
| 301 | * |
| 302 | * Use clang_getInstantiationLocation() to map a source location to a |
| 303 | * particular file, line, and column. |
Douglas Gregor | 3c7313d | 2010-01-18 22:13:09 +0000 | [diff] [blame] | 304 | */ |
| 305 | typedef struct { |
Douglas Gregor | 1db19de | 2010-01-19 21:36:55 +0000 | [diff] [blame] | 306 | void *ptr_data; |
| 307 | unsigned int_data; |
Douglas Gregor | 3c7313d | 2010-01-18 22:13:09 +0000 | [diff] [blame] | 308 | } CXSourceLocation; |
Ted Kremenek | fe6fd3d | 2010-01-05 23:18:49 +0000 | [diff] [blame] | 309 | |
Douglas Gregor | 3c7313d | 2010-01-18 22:13:09 +0000 | [diff] [blame] | 310 | /** |
Douglas Gregor | 1db19de | 2010-01-19 21:36:55 +0000 | [diff] [blame] | 311 | * \brief Identifies a range of source locations in the source code. |
Douglas Gregor | 3c7313d | 2010-01-18 22:13:09 +0000 | [diff] [blame] | 312 | * |
Douglas Gregor | 1db19de | 2010-01-19 21:36:55 +0000 | [diff] [blame] | 313 | * Use clang_getRangeStart() and clang_getRangeEnd() to retrieve the |
| 314 | * starting and end locations from a source range, respectively. |
Douglas Gregor | 3c7313d | 2010-01-18 22:13:09 +0000 | [diff] [blame] | 315 | */ |
| 316 | typedef struct { |
Douglas Gregor | 1db19de | 2010-01-19 21:36:55 +0000 | [diff] [blame] | 317 | void *ptr_data; |
| 318 | unsigned begin_int_data; |
| 319 | unsigned end_int_data; |
Douglas Gregor | 3c7313d | 2010-01-18 22:13:09 +0000 | [diff] [blame] | 320 | } CXSourceRange; |
Ted Kremenek | fe6fd3d | 2010-01-05 23:18:49 +0000 | [diff] [blame] | 321 | |
Douglas Gregor | 1db19de | 2010-01-19 21:36:55 +0000 | [diff] [blame] | 322 | /** |
Douglas Gregor | b979034 | 2010-01-22 21:44:22 +0000 | [diff] [blame] | 323 | * \brief Retrieve a NULL (invalid) source location. |
| 324 | */ |
| 325 | CINDEX_LINKAGE CXSourceLocation clang_getNullLocation(); |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 326 | |
Douglas Gregor | b979034 | 2010-01-22 21:44:22 +0000 | [diff] [blame] | 327 | /** |
| 328 | * \determine Determine whether two source locations, which must refer into |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 329 | * the same translation unit, refer to exactly the same point in the source |
Douglas Gregor | b979034 | 2010-01-22 21:44:22 +0000 | [diff] [blame] | 330 | * code. |
| 331 | * |
| 332 | * \returns non-zero if the source locations refer to the same location, zero |
| 333 | * if they refer to different locations. |
| 334 | */ |
| 335 | CINDEX_LINKAGE unsigned clang_equalLocations(CXSourceLocation loc1, |
| 336 | CXSourceLocation loc2); |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 337 | |
Douglas Gregor | b979034 | 2010-01-22 21:44:22 +0000 | [diff] [blame] | 338 | /** |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 339 | * \brief Retrieves the source location associated with a given file/line/column |
| 340 | * in a particular translation unit. |
Douglas Gregor | b979034 | 2010-01-22 21:44:22 +0000 | [diff] [blame] | 341 | */ |
| 342 | CINDEX_LINKAGE CXSourceLocation clang_getLocation(CXTranslationUnit tu, |
| 343 | CXFile file, |
| 344 | unsigned line, |
| 345 | unsigned column); |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 346 | |
Douglas Gregor | b979034 | 2010-01-22 21:44:22 +0000 | [diff] [blame] | 347 | /** |
| 348 | * \brief Retrieve a source range given the beginning and ending source |
| 349 | * locations. |
| 350 | */ |
| 351 | CINDEX_LINKAGE CXSourceRange clang_getRange(CXSourceLocation begin, |
| 352 | CXSourceLocation end); |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 353 | |
Douglas Gregor | b979034 | 2010-01-22 21:44:22 +0000 | [diff] [blame] | 354 | /** |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 355 | * \brief Retrieve the file, line, and column represented by the given source |
| 356 | * location. |
Douglas Gregor | 1db19de | 2010-01-19 21:36:55 +0000 | [diff] [blame] | 357 | * |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 358 | * \param location the location within a source file that will be decomposed |
| 359 | * into its parts. |
Douglas Gregor | 1db19de | 2010-01-19 21:36:55 +0000 | [diff] [blame] | 360 | * |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 361 | * \param file [out] if non-NULL, will be set to the file to which the given |
Douglas Gregor | 1db19de | 2010-01-19 21:36:55 +0000 | [diff] [blame] | 362 | * source location points. |
| 363 | * |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 364 | * \param line [out] if non-NULL, will be set to the line to which the given |
Douglas Gregor | 1db19de | 2010-01-19 21:36:55 +0000 | [diff] [blame] | 365 | * source location points. |
| 366 | * |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 367 | * \param column [out] if non-NULL, will be set to the column to which the given |
| 368 | * source location points. |
Douglas Gregor | 1db19de | 2010-01-19 21:36:55 +0000 | [diff] [blame] | 369 | */ |
| 370 | CINDEX_LINKAGE void clang_getInstantiationLocation(CXSourceLocation location, |
| 371 | CXFile *file, |
| 372 | unsigned *line, |
| 373 | unsigned *column); |
| 374 | |
| 375 | /** |
Douglas Gregor | e69517c | 2010-01-26 03:07:15 +0000 | [diff] [blame^] | 376 | * \brief Retrieve the file and offset within that file represented by |
| 377 | * the given source location. |
| 378 | * |
| 379 | * \param location the location within a source file that will be decomposed |
| 380 | * into its parts. |
| 381 | * |
| 382 | * \param file [out] if non-NULL, will be set to the file to which the |
| 383 | * given source location points. |
| 384 | * |
| 385 | * \param offset [out] if non-NULL, will be set to the offset into the |
| 386 | * \p file to which the given source location points. |
| 387 | */ |
| 388 | CINDEX_LINKAGE void clang_getInstantiationLocationOffset( |
| 389 | CXSourceLocation location, |
| 390 | CXFile *File, |
| 391 | unsigned *Offset); |
| 392 | |
| 393 | /** |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 394 | * \brief Retrieve a source location representing the first character within a |
| 395 | * source range. |
Douglas Gregor | 1db19de | 2010-01-19 21:36:55 +0000 | [diff] [blame] | 396 | */ |
| 397 | CINDEX_LINKAGE CXSourceLocation clang_getRangeStart(CXSourceRange range); |
| 398 | |
| 399 | /** |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 400 | * \brief Retrieve a source location representing the last character within a |
| 401 | * source range. |
Douglas Gregor | 1db19de | 2010-01-19 21:36:55 +0000 | [diff] [blame] | 402 | */ |
| 403 | CINDEX_LINKAGE CXSourceLocation clang_getRangeEnd(CXSourceRange range); |
| 404 | |
Douglas Gregor | f552544 | 2010-01-20 22:45:41 +0000 | [diff] [blame] | 405 | /** |
| 406 | * @} |
| 407 | */ |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 408 | |
| 409 | /** |
| 410 | * \brief Describes the kind of entity that a cursor refers to. |
| 411 | */ |
| 412 | enum CXCursorKind { |
| 413 | /* Declarations */ |
| 414 | CXCursor_FirstDecl = 1, |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 415 | /** |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 416 | * \brief A declaration whose specific kind is not exposed via this |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 417 | * interface. |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 418 | * |
| 419 | * Unexposed declarations have the same operations as any other kind |
| 420 | * of declaration; one can extract their location information, |
| 421 | * spelling, find their definitions, etc. However, the specific kind |
| 422 | * of the declaration is not reported. |
| 423 | */ |
| 424 | CXCursor_UnexposedDecl = 1, |
| 425 | /** \brief A C or C++ struct. */ |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 426 | CXCursor_StructDecl = 2, |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 427 | /** \brief A C or C++ union. */ |
| 428 | CXCursor_UnionDecl = 3, |
| 429 | /** \brief A C++ class. */ |
| 430 | CXCursor_ClassDecl = 4, |
| 431 | /** \brief An enumeration. */ |
| 432 | CXCursor_EnumDecl = 5, |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 433 | /** |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 434 | * \brief A field (in C) or non-static data member (in C++) in a |
| 435 | * struct, union, or C++ class. |
| 436 | */ |
| 437 | CXCursor_FieldDecl = 6, |
| 438 | /** \brief An enumerator constant. */ |
| 439 | CXCursor_EnumConstantDecl = 7, |
| 440 | /** \brief A function. */ |
| 441 | CXCursor_FunctionDecl = 8, |
| 442 | /** \brief A variable. */ |
| 443 | CXCursor_VarDecl = 9, |
| 444 | /** \brief A function or method parameter. */ |
| 445 | CXCursor_ParmDecl = 10, |
| 446 | /** \brief An Objective-C @interface. */ |
| 447 | CXCursor_ObjCInterfaceDecl = 11, |
| 448 | /** \brief An Objective-C @interface for a category. */ |
| 449 | CXCursor_ObjCCategoryDecl = 12, |
| 450 | /** \brief An Objective-C @protocol declaration. */ |
| 451 | CXCursor_ObjCProtocolDecl = 13, |
| 452 | /** \brief An Objective-C @property declaration. */ |
| 453 | CXCursor_ObjCPropertyDecl = 14, |
| 454 | /** \brief An Objective-C instance variable. */ |
| 455 | CXCursor_ObjCIvarDecl = 15, |
| 456 | /** \brief An Objective-C instance method. */ |
| 457 | CXCursor_ObjCInstanceMethodDecl = 16, |
| 458 | /** \brief An Objective-C class method. */ |
| 459 | CXCursor_ObjCClassMethodDecl = 17, |
| 460 | /** \brief An Objective-C @implementation. */ |
| 461 | CXCursor_ObjCImplementationDecl = 18, |
| 462 | /** \brief An Objective-C @implementation for a category. */ |
| 463 | CXCursor_ObjCCategoryImplDecl = 19, |
| 464 | /** \brief A typedef */ |
| 465 | CXCursor_TypedefDecl = 20, |
| 466 | CXCursor_LastDecl = 20, |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 467 | |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 468 | /* References */ |
| 469 | CXCursor_FirstRef = 40, /* Decl references */ |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 470 | CXCursor_ObjCSuperClassRef = 40, |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 471 | CXCursor_ObjCProtocolRef = 41, |
| 472 | CXCursor_ObjCClassRef = 42, |
| 473 | /** |
| 474 | * \brief A reference to a type declaration. |
| 475 | * |
| 476 | * A type reference occurs anywhere where a type is named but not |
| 477 | * declared. For example, given: |
| 478 | * |
| 479 | * \code |
| 480 | * typedef unsigned size_type; |
| 481 | * size_type size; |
| 482 | * \endcode |
| 483 | * |
| 484 | * The typedef is a declaration of size_type (CXCursor_TypedefDecl), |
| 485 | * while the type of the variable "size" is referenced. The cursor |
| 486 | * referenced by the type of size is the typedef for size_type. |
| 487 | */ |
| 488 | CXCursor_TypeRef = 43, |
| 489 | CXCursor_LastRef = 43, |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 490 | |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 491 | /* Error conditions */ |
| 492 | CXCursor_FirstInvalid = 70, |
| 493 | CXCursor_InvalidFile = 70, |
| 494 | CXCursor_NoDeclFound = 71, |
| 495 | CXCursor_NotImplemented = 72, |
| 496 | CXCursor_LastInvalid = 72, |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 497 | |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 498 | /* Expressions */ |
| 499 | CXCursor_FirstExpr = 100, |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 500 | |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 501 | /** |
| 502 | * \brief An expression whose specific kind is not exposed via this |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 503 | * interface. |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 504 | * |
| 505 | * Unexposed expressions have the same operations as any other kind |
| 506 | * of expression; one can extract their location information, |
| 507 | * spelling, children, etc. However, the specific kind of the |
| 508 | * expression is not reported. |
| 509 | */ |
| 510 | CXCursor_UnexposedExpr = 100, |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 511 | |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 512 | /** |
| 513 | * \brief An expression that refers to some value declaration, such |
| 514 | * as a function, varible, or enumerator. |
| 515 | */ |
| 516 | CXCursor_DeclRefExpr = 101, |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 517 | |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 518 | /** |
| 519 | * \brief An expression that refers to a member of a struct, union, |
| 520 | * class, Objective-C class, etc. |
| 521 | */ |
| 522 | CXCursor_MemberRefExpr = 102, |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 523 | |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 524 | /** \brief An expression that calls a function. */ |
| 525 | CXCursor_CallExpr = 103, |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 526 | |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 527 | /** \brief An expression that sends a message to an Objective-C |
| 528 | object or class. */ |
| 529 | CXCursor_ObjCMessageExpr = 104, |
| 530 | CXCursor_LastExpr = 104, |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 531 | |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 532 | /* Statements */ |
| 533 | CXCursor_FirstStmt = 200, |
| 534 | /** |
| 535 | * \brief A statement whose specific kind is not exposed via this |
| 536 | * interface. |
| 537 | * |
| 538 | * Unexposed statements have the same operations as any other kind of |
| 539 | * statement; one can extract their location information, spelling, |
| 540 | * children, etc. However, the specific kind of the statement is not |
| 541 | * reported. |
| 542 | */ |
| 543 | CXCursor_UnexposedStmt = 200, |
| 544 | CXCursor_LastStmt = 200, |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 545 | |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 546 | /** |
| 547 | * \brief Cursor that represents the translation unit itself. |
| 548 | * |
| 549 | * The translation unit cursor exists primarily to act as the root |
| 550 | * cursor for traversing the contents of a translation unit. |
| 551 | */ |
| 552 | CXCursor_TranslationUnit = 300 |
| 553 | }; |
| 554 | |
| 555 | /** |
| 556 | * \brief A cursor representing some element in the abstract syntax tree for |
| 557 | * a translation unit. |
| 558 | * |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 559 | * The cursor abstraction unifies the different kinds of entities in a |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 560 | * program--declaration, statements, expressions, references to declarations, |
| 561 | * etc.--under a single "cursor" abstraction with a common set of operations. |
| 562 | * Common operation for a cursor include: getting the physical location in |
| 563 | * a source file where the cursor points, getting the name associated with a |
| 564 | * cursor, and retrieving cursors for any child nodes of a particular cursor. |
| 565 | * |
| 566 | * Cursors can be produced in two specific ways. |
| 567 | * clang_getTranslationUnitCursor() produces a cursor for a translation unit, |
| 568 | * from which one can use clang_visitChildren() to explore the rest of the |
| 569 | * translation unit. clang_getCursor() maps from a physical source location |
| 570 | * to the entity that resides at that location, allowing one to map from the |
| 571 | * source code into the AST. |
| 572 | */ |
| 573 | typedef struct { |
| 574 | enum CXCursorKind kind; |
| 575 | void *data[3]; |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 576 | } CXCursor; |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 577 | |
| 578 | /** |
| 579 | * \defgroup CINDEX_CURSOR_MANIP Cursor manipulations |
| 580 | * |
| 581 | * @{ |
| 582 | */ |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 583 | |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 584 | /** |
| 585 | * \brief Retrieve the NULL cursor, which represents no entity. |
| 586 | */ |
| 587 | CINDEX_LINKAGE CXCursor clang_getNullCursor(void); |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 588 | |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 589 | /** |
| 590 | * \brief Retrieve the cursor that represents the given translation unit. |
| 591 | * |
| 592 | * The translation unit cursor can be used to start traversing the |
| 593 | * various declarations within the given translation unit. |
| 594 | */ |
| 595 | CINDEX_LINKAGE CXCursor clang_getTranslationUnitCursor(CXTranslationUnit); |
| 596 | |
| 597 | /** |
| 598 | * \brief Determine whether two cursors are equivalent. |
| 599 | */ |
| 600 | CINDEX_LINKAGE unsigned clang_equalCursors(CXCursor, CXCursor); |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 601 | |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 602 | /** |
| 603 | * \brief Retrieve the kind of the given cursor. |
| 604 | */ |
| 605 | CINDEX_LINKAGE enum CXCursorKind clang_getCursorKind(CXCursor); |
| 606 | |
| 607 | /** |
| 608 | * \brief Determine whether the given cursor kind represents a declaration. |
| 609 | */ |
| 610 | CINDEX_LINKAGE unsigned clang_isDeclaration(enum CXCursorKind); |
| 611 | |
| 612 | /** |
| 613 | * \brief Determine whether the given cursor kind represents a simple |
| 614 | * reference. |
| 615 | * |
| 616 | * Note that other kinds of cursors (such as expressions) can also refer to |
| 617 | * other cursors. Use clang_getCursorReferenced() to determine whether a |
| 618 | * particular cursor refers to another entity. |
| 619 | */ |
| 620 | CINDEX_LINKAGE unsigned clang_isReference(enum CXCursorKind); |
| 621 | |
| 622 | /** |
| 623 | * \brief Determine whether the given cursor kind represents an expression. |
| 624 | */ |
| 625 | CINDEX_LINKAGE unsigned clang_isExpression(enum CXCursorKind); |
| 626 | |
| 627 | /** |
| 628 | * \brief Determine whether the given cursor kind represents a statement. |
| 629 | */ |
| 630 | CINDEX_LINKAGE unsigned clang_isStatement(enum CXCursorKind); |
| 631 | |
| 632 | /** |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 633 | * \brief Determine whether the given cursor kind represents an invalid |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 634 | * cursor. |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 635 | */ |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 636 | CINDEX_LINKAGE unsigned clang_isInvalid(enum CXCursorKind); |
| 637 | |
| 638 | /** |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 639 | * \brief Determine whether the given cursor kind represents a translation |
| 640 | * unit. |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 641 | */ |
| 642 | CINDEX_LINKAGE unsigned clang_isTranslationUnit(enum CXCursorKind); |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 643 | |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 644 | /** |
| 645 | * @} |
| 646 | */ |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 647 | |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 648 | /** |
| 649 | * \defgroup CINDEX_CURSOR_SOURCE Mapping between cursors and source code |
| 650 | * |
| 651 | * Cursors represent a location within the Abstract Syntax Tree (AST). These |
| 652 | * routines help map between cursors and the physical locations where the |
| 653 | * described entities occur in the source code. The mapping is provided in |
| 654 | * both directions, so one can map from source code to the AST and back. |
| 655 | * |
| 656 | * @{ |
Steve Naroff | 5039819 | 2009-08-28 15:28:48 +0000 | [diff] [blame] | 657 | */ |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 658 | |
Steve Naroff | 6a6de8b | 2009-10-21 13:56:23 +0000 | [diff] [blame] | 659 | /** |
Douglas Gregor | b979034 | 2010-01-22 21:44:22 +0000 | [diff] [blame] | 660 | * \brief Map a source location to the cursor that describes the entity at that |
| 661 | * location in the source code. |
| 662 | * |
| 663 | * clang_getCursor() maps an arbitrary source location within a translation |
| 664 | * unit down to the most specific cursor that describes the entity at that |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 665 | * location. For example, given an expression \c x + y, invoking |
Douglas Gregor | b979034 | 2010-01-22 21:44:22 +0000 | [diff] [blame] | 666 | * clang_getCursor() with a source location pointing to "x" will return the |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 667 | * cursor for "x"; similarly for "y". If the cursor points anywhere between |
Douglas Gregor | b979034 | 2010-01-22 21:44:22 +0000 | [diff] [blame] | 668 | * "x" or "y" (e.g., on the + or the whitespace around it), clang_getCursor() |
| 669 | * will return a cursor referring to the "+" expression. |
| 670 | * |
| 671 | * \returns a cursor representing the entity at the given source location, or |
| 672 | * a NULL cursor if no such entity can be found. |
Steve Naroff | 6a6de8b | 2009-10-21 13:56:23 +0000 | [diff] [blame] | 673 | */ |
Douglas Gregor | b979034 | 2010-01-22 21:44:22 +0000 | [diff] [blame] | 674 | CINDEX_LINKAGE CXCursor clang_getCursor(CXTranslationUnit, CXSourceLocation); |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 675 | |
Douglas Gregor | 98258af | 2010-01-18 22:46:11 +0000 | [diff] [blame] | 676 | /** |
| 677 | * \brief Retrieve the physical location of the source constructor referenced |
| 678 | * by the given cursor. |
| 679 | * |
| 680 | * The location of a declaration is typically the location of the name of that |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 681 | * declaration, where the name of that declaration would occur if it is |
| 682 | * unnamed, or some keyword that introduces that particular declaration. |
| 683 | * The location of a reference is where that reference occurs within the |
Douglas Gregor | 98258af | 2010-01-18 22:46:11 +0000 | [diff] [blame] | 684 | * source code. |
| 685 | */ |
| 686 | CINDEX_LINKAGE CXSourceLocation clang_getCursorLocation(CXCursor); |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 687 | |
Douglas Gregor | b699866 | 2010-01-19 19:34:47 +0000 | [diff] [blame] | 688 | /** |
| 689 | * \brief Retrieve the physical extent of the source construct referenced by |
Douglas Gregor | a7bde20 | 2010-01-19 00:34:46 +0000 | [diff] [blame] | 690 | * the given cursor. |
| 691 | * |
| 692 | * The extent of a cursor starts with the file/line/column pointing at the |
| 693 | * first character within the source construct that the cursor refers to and |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 694 | * ends with the last character withinin that source construct. For a |
Douglas Gregor | a7bde20 | 2010-01-19 00:34:46 +0000 | [diff] [blame] | 695 | * declaration, the extent covers the declaration itself. For a reference, |
| 696 | * the extent covers the location of the reference (e.g., where the referenced |
| 697 | * entity was actually used). |
| 698 | */ |
| 699 | CINDEX_LINKAGE CXSourceRange clang_getCursorExtent(CXCursor); |
Douglas Gregor | c5d1e93 | 2010-01-19 01:20:04 +0000 | [diff] [blame] | 700 | |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 701 | /** |
| 702 | * @} |
| 703 | */ |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 704 | |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 705 | /** |
| 706 | * \defgroup CINDEX_CURSOR_TRAVERSAL Traversing the AST with cursors |
| 707 | * |
| 708 | * These routines provide the ability to traverse the abstract syntax tree |
| 709 | * using cursors. |
| 710 | * |
| 711 | * @{ |
| 712 | */ |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 713 | |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 714 | /** |
| 715 | * \brief Describes how the traversal of the children of a particular |
| 716 | * cursor should proceed after visiting a particular child cursor. |
| 717 | * |
| 718 | * A value of this enumeration type should be returned by each |
| 719 | * \c CXCursorVisitor to indicate how clang_visitChildren() proceed. |
| 720 | */ |
| 721 | enum CXChildVisitResult { |
| 722 | /** |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 723 | * \brief Terminates the cursor traversal. |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 724 | */ |
| 725 | CXChildVisit_Break, |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 726 | /** |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 727 | * \brief Continues the cursor traversal with the next sibling of |
| 728 | * the cursor just visited, without visiting its children. |
| 729 | */ |
| 730 | CXChildVisit_Continue, |
| 731 | /** |
| 732 | * \brief Recursively traverse the children of this cursor, using |
| 733 | * the same visitor and client data. |
| 734 | */ |
| 735 | CXChildVisit_Recurse |
| 736 | }; |
| 737 | |
| 738 | /** |
| 739 | * \brief Visitor invoked for each cursor found by a traversal. |
| 740 | * |
| 741 | * This visitor function will be invoked for each cursor found by |
| 742 | * clang_visitCursorChildren(). Its first argument is the cursor being |
| 743 | * visited, its second argument is the parent visitor for that cursor, |
| 744 | * and its third argument is the client data provided to |
| 745 | * clang_visitCursorChildren(). |
| 746 | * |
| 747 | * The visitor should return one of the \c CXChildVisitResult values |
| 748 | * to direct clang_visitCursorChildren(). |
| 749 | */ |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 750 | typedef enum CXChildVisitResult (*CXCursorVisitor)(CXCursor cursor, |
| 751 | CXCursor parent, |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 752 | CXClientData client_data); |
| 753 | |
| 754 | /** |
| 755 | * \brief Visit the children of a particular cursor. |
| 756 | * |
| 757 | * This function visits all the direct children of the given cursor, |
| 758 | * invoking the given \p visitor function with the cursors of each |
| 759 | * visited child. The traversal may be recursive, if the visitor returns |
| 760 | * \c CXChildVisit_Recurse. The traversal may also be ended prematurely, if |
| 761 | * the visitor returns \c CXChildVisit_Break. |
| 762 | * |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 763 | * \param parent the cursor whose child may be visited. All kinds of |
Daniel Dunbar | a57259e | 2010-01-24 04:10:31 +0000 | [diff] [blame] | 764 | * cursors can be visited, including invalid cursors (which, by |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 765 | * definition, have no children). |
| 766 | * |
| 767 | * \param visitor the visitor function that will be invoked for each |
| 768 | * child of \p parent. |
| 769 | * |
| 770 | * \param client_data pointer data supplied by the client, which will |
| 771 | * be passed to the visitor each time it is invoked. |
| 772 | * |
| 773 | * \returns a non-zero value if the traversal was terminated |
| 774 | * prematurely by the visitor returning \c CXChildVisit_Break. |
| 775 | */ |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 776 | CINDEX_LINKAGE unsigned clang_visitChildren(CXCursor parent, |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 777 | CXCursorVisitor visitor, |
| 778 | CXClientData client_data); |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 779 | |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 780 | /** |
| 781 | * @} |
| 782 | */ |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 783 | |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 784 | /** |
| 785 | * \defgroup CINDEX_CURSOR_XREF Cross-referencing in the AST |
| 786 | * |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 787 | * These routines provide the ability to determine references within and |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 788 | * across translation units, by providing the names of the entities referenced |
| 789 | * by cursors, follow reference cursors to the declarations they reference, |
| 790 | * and associate declarations with their definitions. |
| 791 | * |
| 792 | * @{ |
| 793 | */ |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 794 | |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 795 | /** |
| 796 | * \brief Retrieve a Unified Symbol Resolution (USR) for the entity referenced |
| 797 | * by the given cursor. |
| 798 | * |
| 799 | * A Unified Symbol Resolution (USR) is a string that identifies a particular |
| 800 | * entity (function, class, variable, etc.) within a program. USRs can be |
| 801 | * compared across translation units to determine, e.g., when references in |
| 802 | * one translation refer to an entity defined in another translation unit. |
| 803 | */ |
| 804 | CINDEX_LINKAGE CXString clang_getCursorUSR(CXCursor); |
| 805 | |
| 806 | /** |
| 807 | * \brief Retrieve a name for the entity referenced by this cursor. |
| 808 | */ |
| 809 | CINDEX_LINKAGE CXString clang_getCursorSpelling(CXCursor); |
| 810 | |
Douglas Gregor | c5d1e93 | 2010-01-19 01:20:04 +0000 | [diff] [blame] | 811 | /** \brief For a cursor that is a reference, retrieve a cursor representing the |
| 812 | * entity that it references. |
| 813 | * |
| 814 | * Reference cursors refer to other entities in the AST. For example, an |
| 815 | * Objective-C superclass reference cursor refers to an Objective-C class. |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 816 | * This function produces the cursor for the Objective-C class from the |
Douglas Gregor | c5d1e93 | 2010-01-19 01:20:04 +0000 | [diff] [blame] | 817 | * cursor for the superclass reference. If the input cursor is a declaration or |
| 818 | * definition, it returns that declaration or definition unchanged. |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 819 | * Otherwise, returns the NULL cursor. |
Douglas Gregor | c5d1e93 | 2010-01-19 01:20:04 +0000 | [diff] [blame] | 820 | */ |
| 821 | CINDEX_LINKAGE CXCursor clang_getCursorReferenced(CXCursor); |
Douglas Gregor | b699866 | 2010-01-19 19:34:47 +0000 | [diff] [blame] | 822 | |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 823 | /** |
Douglas Gregor | b699866 | 2010-01-19 19:34:47 +0000 | [diff] [blame] | 824 | * \brief For a cursor that is either a reference to or a declaration |
| 825 | * of some entity, retrieve a cursor that describes the definition of |
| 826 | * that entity. |
| 827 | * |
| 828 | * Some entities can be declared multiple times within a translation |
| 829 | * unit, but only one of those declarations can also be a |
| 830 | * definition. For example, given: |
| 831 | * |
| 832 | * \code |
| 833 | * int f(int, int); |
| 834 | * int g(int x, int y) { return f(x, y); } |
| 835 | * int f(int a, int b) { return a + b; } |
| 836 | * int f(int, int); |
| 837 | * \endcode |
| 838 | * |
| 839 | * there are three declarations of the function "f", but only the |
| 840 | * second one is a definition. The clang_getCursorDefinition() |
| 841 | * function will take any cursor pointing to a declaration of "f" |
| 842 | * (the first or fourth lines of the example) or a cursor referenced |
| 843 | * that uses "f" (the call to "f' inside "g") and will return a |
| 844 | * declaration cursor pointing to the definition (the second "f" |
| 845 | * declaration). |
| 846 | * |
| 847 | * If given a cursor for which there is no corresponding definition, |
| 848 | * e.g., because there is no definition of that entity within this |
| 849 | * translation unit, returns a NULL cursor. |
| 850 | */ |
| 851 | CINDEX_LINKAGE CXCursor clang_getCursorDefinition(CXCursor); |
| 852 | |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 853 | /** |
Douglas Gregor | b699866 | 2010-01-19 19:34:47 +0000 | [diff] [blame] | 854 | * \brief Determine whether the declaration pointed to by this cursor |
| 855 | * is also a definition of that entity. |
| 856 | */ |
| 857 | CINDEX_LINKAGE unsigned clang_isCursorDefinition(CXCursor); |
| 858 | |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 859 | /** |
| 860 | * @} |
| 861 | */ |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 862 | |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 863 | /** |
| 864 | * \defgroup CINDEX_DEBUG Debugging facilities |
| 865 | * |
| 866 | * These routines are used for testing and debugging, only, and should not |
| 867 | * be relied upon. |
| 868 | * |
| 869 | * @{ |
| 870 | */ |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 871 | |
Steve Naroff | 4ade6d6 | 2009-09-23 17:52:52 +0000 | [diff] [blame] | 872 | /* for debug/testing */ |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 873 | CINDEX_LINKAGE const char *clang_getCursorKindSpelling(enum CXCursorKind Kind); |
| 874 | CINDEX_LINKAGE void clang_getDefinitionSpellingAndExtent(CXCursor, |
| 875 | const char **startBuf, |
Steve Naroff | 4ade6d6 | 2009-09-23 17:52:52 +0000 | [diff] [blame] | 876 | const char **endBuf, |
| 877 | unsigned *startLine, |
| 878 | unsigned *startColumn, |
| 879 | unsigned *endLine, |
| 880 | unsigned *endColumn); |
Steve Naroff | 600866c | 2009-08-27 19:51:58 +0000 | [diff] [blame] | 881 | |
Douglas Gregor | 0c8296d | 2009-11-07 00:00:49 +0000 | [diff] [blame] | 882 | /** |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 883 | * @} |
| 884 | */ |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 885 | |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 886 | /** |
| 887 | * \defgroup CINDEX_CODE_COMPLET Code completion |
| 888 | * |
| 889 | * Code completion involves taking an (incomplete) source file, along with |
| 890 | * knowledge of where the user is actively editing that file, and suggesting |
| 891 | * syntactically- and semantically-valid constructs that the user might want to |
| 892 | * use at that particular point in the source code. These data structures and |
| 893 | * routines provide support for code completion. |
| 894 | * |
| 895 | * @{ |
| 896 | */ |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 897 | |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 898 | /** |
Douglas Gregor | 0c8296d | 2009-11-07 00:00:49 +0000 | [diff] [blame] | 899 | * \brief A semantic string that describes a code-completion result. |
| 900 | * |
| 901 | * A semantic string that describes the formatting of a code-completion |
| 902 | * result as a single "template" of text that should be inserted into the |
| 903 | * source buffer when a particular code-completion result is selected. |
| 904 | * Each semantic string is made up of some number of "chunks", each of which |
| 905 | * contains some text along with a description of what that text means, e.g., |
| 906 | * the name of the entity being referenced, whether the text chunk is part of |
| 907 | * the template, or whether it is a "placeholder" that the user should replace |
| 908 | * with actual code,of a specific kind. See \c CXCompletionChunkKind for a |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 909 | * description of the different kinds of chunks. |
Douglas Gregor | 0c8296d | 2009-11-07 00:00:49 +0000 | [diff] [blame] | 910 | */ |
| 911 | typedef void *CXCompletionString; |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 912 | |
Douglas Gregor | 0c8296d | 2009-11-07 00:00:49 +0000 | [diff] [blame] | 913 | /** |
| 914 | * \brief A single result of code completion. |
| 915 | */ |
| 916 | typedef struct { |
| 917 | /** |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 918 | * \brief The kind of entity that this completion refers to. |
Douglas Gregor | 0c8296d | 2009-11-07 00:00:49 +0000 | [diff] [blame] | 919 | * |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 920 | * The cursor kind will be a macro, keyword, or a declaration (one of the |
Douglas Gregor | 0c8296d | 2009-11-07 00:00:49 +0000 | [diff] [blame] | 921 | * *Decl cursor kinds), describing the entity that the completion is |
| 922 | * referring to. |
| 923 | * |
| 924 | * \todo In the future, we would like to provide a full cursor, to allow |
| 925 | * the client to extract additional information from declaration. |
| 926 | */ |
| 927 | enum CXCursorKind CursorKind; |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 928 | |
| 929 | /** |
Douglas Gregor | 0c8296d | 2009-11-07 00:00:49 +0000 | [diff] [blame] | 930 | * \brief The code-completion string that describes how to insert this |
| 931 | * code-completion result into the editing buffer. |
| 932 | */ |
| 933 | CXCompletionString CompletionString; |
| 934 | } CXCompletionResult; |
| 935 | |
| 936 | /** |
| 937 | * \brief Describes a single piece of text within a code-completion string. |
| 938 | * |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 939 | * Each "chunk" within a code-completion string (\c CXCompletionString) is |
| 940 | * either a piece of text with a specific "kind" that describes how that text |
Douglas Gregor | 0c8296d | 2009-11-07 00:00:49 +0000 | [diff] [blame] | 941 | * should be interpreted by the client or is another completion string. |
| 942 | */ |
| 943 | enum CXCompletionChunkKind { |
| 944 | /** |
| 945 | * \brief A code-completion string that describes "optional" text that |
| 946 | * could be a part of the template (but is not required). |
| 947 | * |
| 948 | * The Optional chunk is the only kind of chunk that has a code-completion |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 949 | * string for its representation, which is accessible via |
Douglas Gregor | 0c8296d | 2009-11-07 00:00:49 +0000 | [diff] [blame] | 950 | * \c clang_getCompletionChunkCompletionString(). The code-completion string |
| 951 | * describes an additional part of the template that is completely optional. |
| 952 | * For example, optional chunks can be used to describe the placeholders for |
| 953 | * arguments that match up with defaulted function parameters, e.g. given: |
| 954 | * |
| 955 | * \code |
| 956 | * void f(int x, float y = 3.14, double z = 2.71828); |
| 957 | * \endcode |
| 958 | * |
| 959 | * The code-completion string for this function would contain: |
| 960 | * - a TypedText chunk for "f". |
| 961 | * - a LeftParen chunk for "(". |
| 962 | * - a Placeholder chunk for "int x" |
| 963 | * - an Optional chunk containing the remaining defaulted arguments, e.g., |
| 964 | * - a Comma chunk for "," |
| 965 | * - a Placeholder chunk for "float x" |
| 966 | * - an Optional chunk containing the last defaulted argument: |
| 967 | * - a Comma chunk for "," |
| 968 | * - a Placeholder chunk for "double z" |
| 969 | * - a RightParen chunk for ")" |
| 970 | * |
| 971 | * There are many ways two handle Optional chunks. Two simple approaches are: |
| 972 | * - Completely ignore optional chunks, in which case the template for the |
| 973 | * function "f" would only include the first parameter ("int x"). |
| 974 | * - Fully expand all optional chunks, in which case the template for the |
| 975 | * function "f" would have all of the parameters. |
| 976 | */ |
| 977 | CXCompletionChunk_Optional, |
| 978 | /** |
| 979 | * \brief Text that a user would be expected to type to get this |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 980 | * code-completion result. |
Douglas Gregor | 0c8296d | 2009-11-07 00:00:49 +0000 | [diff] [blame] | 981 | * |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 982 | * There will be exactly one "typed text" chunk in a semantic string, which |
| 983 | * will typically provide the spelling of a keyword or the name of a |
Douglas Gregor | 0c8296d | 2009-11-07 00:00:49 +0000 | [diff] [blame] | 984 | * declaration that could be used at the current code point. Clients are |
| 985 | * expected to filter the code-completion results based on the text in this |
| 986 | * chunk. |
| 987 | */ |
| 988 | CXCompletionChunk_TypedText, |
| 989 | /** |
| 990 | * \brief Text that should be inserted as part of a code-completion result. |
| 991 | * |
| 992 | * A "text" chunk represents text that is part of the template to be |
| 993 | * inserted into user code should this particular code-completion result |
| 994 | * be selected. |
| 995 | */ |
| 996 | CXCompletionChunk_Text, |
| 997 | /** |
| 998 | * \brief Placeholder text that should be replaced by the user. |
| 999 | * |
| 1000 | * A "placeholder" chunk marks a place where the user should insert text |
| 1001 | * into the code-completion template. For example, placeholders might mark |
| 1002 | * the function parameters for a function declaration, to indicate that the |
| 1003 | * user should provide arguments for each of those parameters. The actual |
| 1004 | * text in a placeholder is a suggestion for the text to display before |
| 1005 | * the user replaces the placeholder with real code. |
| 1006 | */ |
| 1007 | CXCompletionChunk_Placeholder, |
| 1008 | /** |
| 1009 | * \brief Informative text that should be displayed but never inserted as |
| 1010 | * part of the template. |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 1011 | * |
Douglas Gregor | 0c8296d | 2009-11-07 00:00:49 +0000 | [diff] [blame] | 1012 | * An "informative" chunk contains annotations that can be displayed to |
| 1013 | * help the user decide whether a particular code-completion result is the |
| 1014 | * right option, but which is not part of the actual template to be inserted |
| 1015 | * by code completion. |
| 1016 | */ |
| 1017 | CXCompletionChunk_Informative, |
| 1018 | /** |
| 1019 | * \brief Text that describes the current parameter when code-completion is |
| 1020 | * referring to function call, message send, or template specialization. |
| 1021 | * |
| 1022 | * A "current parameter" chunk occurs when code-completion is providing |
| 1023 | * information about a parameter corresponding to the argument at the |
| 1024 | * code-completion point. For example, given a function |
| 1025 | * |
| 1026 | * \code |
| 1027 | * int add(int x, int y); |
| 1028 | * \endcode |
| 1029 | * |
| 1030 | * and the source code \c add(, where the code-completion point is after the |
| 1031 | * "(", the code-completion string will contain a "current parameter" chunk |
| 1032 | * for "int x", indicating that the current argument will initialize that |
| 1033 | * parameter. After typing further, to \c add(17, (where the code-completion |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 1034 | * point is after the ","), the code-completion string will contain a |
Douglas Gregor | 0c8296d | 2009-11-07 00:00:49 +0000 | [diff] [blame] | 1035 | * "current paremeter" chunk to "int y". |
| 1036 | */ |
| 1037 | CXCompletionChunk_CurrentParameter, |
| 1038 | /** |
| 1039 | * \brief A left parenthesis ('('), used to initiate a function call or |
| 1040 | * signal the beginning of a function parameter list. |
| 1041 | */ |
| 1042 | CXCompletionChunk_LeftParen, |
| 1043 | /** |
| 1044 | * \brief A right parenthesis (')'), used to finish a function call or |
| 1045 | * signal the end of a function parameter list. |
| 1046 | */ |
| 1047 | CXCompletionChunk_RightParen, |
| 1048 | /** |
| 1049 | * \brief A left bracket ('['). |
| 1050 | */ |
| 1051 | CXCompletionChunk_LeftBracket, |
| 1052 | /** |
| 1053 | * \brief A right bracket (']'). |
| 1054 | */ |
| 1055 | CXCompletionChunk_RightBracket, |
| 1056 | /** |
| 1057 | * \brief A left brace ('{'). |
| 1058 | */ |
| 1059 | CXCompletionChunk_LeftBrace, |
| 1060 | /** |
| 1061 | * \brief A right brace ('}'). |
| 1062 | */ |
| 1063 | CXCompletionChunk_RightBrace, |
| 1064 | /** |
| 1065 | * \brief A left angle bracket ('<'). |
| 1066 | */ |
| 1067 | CXCompletionChunk_LeftAngle, |
| 1068 | /** |
| 1069 | * \brief A right angle bracket ('>'). |
| 1070 | */ |
| 1071 | CXCompletionChunk_RightAngle, |
| 1072 | /** |
| 1073 | * \brief A comma separator (','). |
| 1074 | */ |
Douglas Gregor | ff5ce6e | 2009-12-18 18:53:37 +0000 | [diff] [blame] | 1075 | CXCompletionChunk_Comma, |
| 1076 | /** |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 1077 | * \brief Text that specifies the result type of a given result. |
Douglas Gregor | ff5ce6e | 2009-12-18 18:53:37 +0000 | [diff] [blame] | 1078 | * |
| 1079 | * This special kind of informative chunk is not meant to be inserted into |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 1080 | * the text buffer. Rather, it is meant to illustrate the type that an |
Douglas Gregor | ff5ce6e | 2009-12-18 18:53:37 +0000 | [diff] [blame] | 1081 | * expression using the given completion string would have. |
| 1082 | */ |
Douglas Gregor | 01dfea0 | 2010-01-10 23:08:15 +0000 | [diff] [blame] | 1083 | CXCompletionChunk_ResultType, |
| 1084 | /** |
| 1085 | * \brief A colon (':'). |
| 1086 | */ |
| 1087 | CXCompletionChunk_Colon, |
| 1088 | /** |
| 1089 | * \brief A semicolon (';'). |
| 1090 | */ |
| 1091 | CXCompletionChunk_SemiColon, |
| 1092 | /** |
| 1093 | * \brief An '=' sign. |
| 1094 | */ |
| 1095 | CXCompletionChunk_Equal, |
| 1096 | /** |
| 1097 | * Horizontal space (' '). |
| 1098 | */ |
| 1099 | CXCompletionChunk_HorizontalSpace, |
| 1100 | /** |
| 1101 | * Vertical space ('\n'), after which it is generally a good idea to |
| 1102 | * perform indentation. |
| 1103 | */ |
| 1104 | CXCompletionChunk_VerticalSpace |
Douglas Gregor | 0c8296d | 2009-11-07 00:00:49 +0000 | [diff] [blame] | 1105 | }; |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 1106 | |
Douglas Gregor | 0c8296d | 2009-11-07 00:00:49 +0000 | [diff] [blame] | 1107 | /** |
| 1108 | * \brief Determine the kind of a particular chunk within a completion string. |
| 1109 | * |
| 1110 | * \param completion_string the completion string to query. |
| 1111 | * |
| 1112 | * \param chunk_number the 0-based index of the chunk in the completion string. |
| 1113 | * |
| 1114 | * \returns the kind of the chunk at the index \c chunk_number. |
| 1115 | */ |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 1116 | CINDEX_LINKAGE enum CXCompletionChunkKind |
Douglas Gregor | 0c8296d | 2009-11-07 00:00:49 +0000 | [diff] [blame] | 1117 | clang_getCompletionChunkKind(CXCompletionString completion_string, |
| 1118 | unsigned chunk_number); |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 1119 | |
Douglas Gregor | 0c8296d | 2009-11-07 00:00:49 +0000 | [diff] [blame] | 1120 | /** |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 1121 | * \brief Retrieve the text associated with a particular chunk within a |
Douglas Gregor | 0c8296d | 2009-11-07 00:00:49 +0000 | [diff] [blame] | 1122 | * completion string. |
| 1123 | * |
| 1124 | * \param completion_string the completion string to query. |
| 1125 | * |
| 1126 | * \param chunk_number the 0-based index of the chunk in the completion string. |
| 1127 | * |
| 1128 | * \returns the text associated with the chunk at index \c chunk_number. |
| 1129 | */ |
| 1130 | CINDEX_LINKAGE const char * |
| 1131 | clang_getCompletionChunkText(CXCompletionString completion_string, |
| 1132 | unsigned chunk_number); |
| 1133 | |
| 1134 | /** |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 1135 | * \brief Retrieve the completion string associated with a particular chunk |
Douglas Gregor | 0c8296d | 2009-11-07 00:00:49 +0000 | [diff] [blame] | 1136 | * within a completion string. |
| 1137 | * |
| 1138 | * \param completion_string the completion string to query. |
| 1139 | * |
| 1140 | * \param chunk_number the 0-based index of the chunk in the completion string. |
| 1141 | * |
| 1142 | * \returns the completion string associated with the chunk at index |
| 1143 | * \c chunk_number, or NULL if that chunk is not represented by a completion |
| 1144 | * string. |
| 1145 | */ |
| 1146 | CINDEX_LINKAGE CXCompletionString |
| 1147 | clang_getCompletionChunkCompletionString(CXCompletionString completion_string, |
| 1148 | unsigned chunk_number); |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 1149 | |
Douglas Gregor | 0c8296d | 2009-11-07 00:00:49 +0000 | [diff] [blame] | 1150 | /** |
| 1151 | * \brief Retrieve the number of chunks in the given code-completion string. |
| 1152 | */ |
| 1153 | CINDEX_LINKAGE unsigned |
| 1154 | clang_getNumCompletionChunks(CXCompletionString completion_string); |
| 1155 | |
| 1156 | /** |
Douglas Gregor | ec6762c | 2009-12-18 16:20:58 +0000 | [diff] [blame] | 1157 | * \brief Contains the results of code-completion. |
| 1158 | * |
| 1159 | * This data structure contains the results of code completion, as |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 1160 | * produced by \c clang_codeComplete. Its contents must be freed by |
Douglas Gregor | ec6762c | 2009-12-18 16:20:58 +0000 | [diff] [blame] | 1161 | * \c clang_disposeCodeCompleteResults. |
| 1162 | */ |
| 1163 | typedef struct { |
| 1164 | /** |
| 1165 | * \brief The code-completion results. |
| 1166 | */ |
| 1167 | CXCompletionResult *Results; |
| 1168 | |
| 1169 | /** |
| 1170 | * \brief The number of code-completion results stored in the |
| 1171 | * \c Results array. |
| 1172 | */ |
| 1173 | unsigned NumResults; |
| 1174 | } CXCodeCompleteResults; |
| 1175 | |
| 1176 | /** |
Douglas Gregor | 0c8296d | 2009-11-07 00:00:49 +0000 | [diff] [blame] | 1177 | * \brief Perform code completion at a given location in a source file. |
| 1178 | * |
| 1179 | * This function performs code completion at a particular file, line, and |
| 1180 | * column within source code, providing results that suggest potential |
| 1181 | * code snippets based on the context of the completion. The basic model |
| 1182 | * for code completion is that Clang will parse a complete source file, |
| 1183 | * performing syntax checking up to the location where code-completion has |
| 1184 | * been requested. At that point, a special code-completion token is passed |
| 1185 | * to the parser, which recognizes this token and determines, based on the |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 1186 | * current location in the C/Objective-C/C++ grammar and the state of |
Douglas Gregor | 0c8296d | 2009-11-07 00:00:49 +0000 | [diff] [blame] | 1187 | * semantic analysis, what completions to provide. These completions are |
Douglas Gregor | ec6762c | 2009-12-18 16:20:58 +0000 | [diff] [blame] | 1188 | * returned via a new \c CXCodeCompleteResults structure. |
Douglas Gregor | 0c8296d | 2009-11-07 00:00:49 +0000 | [diff] [blame] | 1189 | * |
| 1190 | * Code completion itself is meant to be triggered by the client when the |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 1191 | * user types punctuation characters or whitespace, at which point the |
Douglas Gregor | 0c8296d | 2009-11-07 00:00:49 +0000 | [diff] [blame] | 1192 | * code-completion location will coincide with the cursor. For example, if \c p |
| 1193 | * is a pointer, code-completion might be triggered after the "-" and then |
| 1194 | * after the ">" in \c p->. When the code-completion location is afer the ">", |
| 1195 | * the completion results will provide, e.g., the members of the struct that |
| 1196 | * "p" points to. The client is responsible for placing the cursor at the |
| 1197 | * beginning of the token currently being typed, then filtering the results |
| 1198 | * based on the contents of the token. For example, when code-completing for |
| 1199 | * the expression \c p->get, the client should provide the location just after |
| 1200 | * the ">" (e.g., pointing at the "g") to this code-completion hook. Then, the |
| 1201 | * client can filter the results based on the current token text ("get"), only |
| 1202 | * showing those results that start with "get". The intent of this interface |
Douglas Gregor | ec6762c | 2009-12-18 16:20:58 +0000 | [diff] [blame] | 1203 | * is to separate the relatively high-latency acquisition of code-completion |
Douglas Gregor | 0c8296d | 2009-11-07 00:00:49 +0000 | [diff] [blame] | 1204 | * results from the filtering of results on a per-character basis, which must |
| 1205 | * have a lower latency. |
| 1206 | * |
| 1207 | * \param CIdx the \c CXIndex instance that will be used to perform code |
| 1208 | * completion. |
| 1209 | * |
Daniel Dunbar | 8506dde | 2009-12-03 01:54:28 +0000 | [diff] [blame] | 1210 | * \param source_filename the name of the source file that should be parsed to |
| 1211 | * perform code-completion. This source file must be the same as or include the |
| 1212 | * filename described by \p complete_filename, or no code-completion results |
| 1213 | * will be produced. NOTE: One can also specify NULL for this argument if the |
| 1214 | * source file is included in command_line_args. |
Douglas Gregor | 0c8296d | 2009-11-07 00:00:49 +0000 | [diff] [blame] | 1215 | * |
| 1216 | * \param num_command_line_args the number of command-line arguments stored in |
| 1217 | * \p command_line_args. |
| 1218 | * |
| 1219 | * \param command_line_args the command-line arguments to pass to the Clang |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 1220 | * compiler to build the given source file. This should include all of the |
Douglas Gregor | 0c8296d | 2009-11-07 00:00:49 +0000 | [diff] [blame] | 1221 | * necessary include paths, language-dialect switches, precompiled header |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 1222 | * includes, etc., but should not include any information specific to |
Douglas Gregor | 0c8296d | 2009-11-07 00:00:49 +0000 | [diff] [blame] | 1223 | * code completion. |
| 1224 | * |
Douglas Gregor | 735df88 | 2009-12-02 09:21:34 +0000 | [diff] [blame] | 1225 | * \param num_unsaved_files the number of unsaved file entries in \p |
| 1226 | * unsaved_files. |
| 1227 | * |
| 1228 | * \param unsaved_files the files that have not yet been saved to disk |
| 1229 | * but may be required for code completion, including the contents of |
| 1230 | * those files. |
| 1231 | * |
Douglas Gregor | 0c8296d | 2009-11-07 00:00:49 +0000 | [diff] [blame] | 1232 | * \param complete_filename the name of the source file where code completion |
| 1233 | * should be performed. In many cases, this name will be the same as the |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 1234 | * source filename. However, the completion filename may also be a file |
| 1235 | * included by the source file, which is required when producing |
Douglas Gregor | 0c8296d | 2009-11-07 00:00:49 +0000 | [diff] [blame] | 1236 | * code-completion results for a header. |
| 1237 | * |
| 1238 | * \param complete_line the line at which code-completion should occur. |
| 1239 | * |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 1240 | * \param complete_column the column at which code-completion should occur. |
Douglas Gregor | 0c8296d | 2009-11-07 00:00:49 +0000 | [diff] [blame] | 1241 | * Note that the column should point just after the syntactic construct that |
| 1242 | * initiated code completion, and not in the middle of a lexical token. |
| 1243 | * |
Douglas Gregor | ec6762c | 2009-12-18 16:20:58 +0000 | [diff] [blame] | 1244 | * \returns if successful, a new CXCodeCompleteResults structure |
| 1245 | * containing code-completion results, which should eventually be |
| 1246 | * freed with \c clang_disposeCodeCompleteResults(). If code |
| 1247 | * completion fails, returns NULL. |
Douglas Gregor | 0c8296d | 2009-11-07 00:00:49 +0000 | [diff] [blame] | 1248 | */ |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 1249 | CINDEX_LINKAGE |
| 1250 | CXCodeCompleteResults *clang_codeComplete(CXIndex CIdx, |
Douglas Gregor | ec6762c | 2009-12-18 16:20:58 +0000 | [diff] [blame] | 1251 | const char *source_filename, |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 1252 | int num_command_line_args, |
Douglas Gregor | ec6762c | 2009-12-18 16:20:58 +0000 | [diff] [blame] | 1253 | const char **command_line_args, |
| 1254 | unsigned num_unsaved_files, |
| 1255 | struct CXUnsavedFile *unsaved_files, |
| 1256 | const char *complete_filename, |
| 1257 | unsigned complete_line, |
| 1258 | unsigned complete_column); |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 1259 | |
Douglas Gregor | ec6762c | 2009-12-18 16:20:58 +0000 | [diff] [blame] | 1260 | /** |
| 1261 | * \brief Free the given set of code-completion results. |
| 1262 | */ |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 1263 | CINDEX_LINKAGE |
Douglas Gregor | ec6762c | 2009-12-18 16:20:58 +0000 | [diff] [blame] | 1264 | void clang_disposeCodeCompleteResults(CXCodeCompleteResults *Results); |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 1265 | |
Douglas Gregor | 20d416c | 2010-01-20 01:10:47 +0000 | [diff] [blame] | 1266 | /** |
| 1267 | * @} |
| 1268 | */ |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 1269 | |
| 1270 | |
Ted Kremenek | 04bb716 | 2010-01-22 22:44:15 +0000 | [diff] [blame] | 1271 | /** |
| 1272 | * \defgroup CINDEX_MISC Miscellaneous utility functions |
| 1273 | * |
| 1274 | * @{ |
| 1275 | */ |
Ted Kremenek | 23e1ad0 | 2010-01-23 17:51:23 +0000 | [diff] [blame] | 1276 | |
| 1277 | /** |
| 1278 | * \brief Return a version string, suitable for showing to a user, but not |
| 1279 | * intended to be parsed (the format is not guaranteed to be stable). |
| 1280 | */ |
Ted Kremenek | 04bb716 | 2010-01-22 22:44:15 +0000 | [diff] [blame] | 1281 | CINDEX_LINKAGE const char *clang_getClangVersion(); |
| 1282 | |
| 1283 | /** |
| 1284 | * @} |
| 1285 | */ |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 1286 | |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 1287 | /** |
| 1288 | * @} |
| 1289 | */ |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 1290 | |
Ted Kremenek | d2fa566 | 2009-08-26 22:36:44 +0000 | [diff] [blame] | 1291 | #ifdef __cplusplus |
| 1292 | } |
| 1293 | #endif |
| 1294 | #endif |
| 1295 | |