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> |
Douglas Gregor | 0a812cf | 2010-02-18 23:07:20 +0000 | [diff] [blame] | 21 | #include <stdio.h> |
Steve Naroff | 8814503 | 2009-10-27 14:35:18 +0000 | [diff] [blame] | 22 | |
Ted Kremenek | d2fa566 | 2009-08-26 22:36:44 +0000 | [diff] [blame] | 23 | #ifdef __cplusplus |
| 24 | extern "C" { |
| 25 | #endif |
| 26 | |
Steve Naroff | 8814503 | 2009-10-27 14:35:18 +0000 | [diff] [blame] | 27 | /* MSVC DLL import/export. */ |
John Thompson | 2e06fc8 | 2009-10-27 13:42:56 +0000 | [diff] [blame] | 28 | #ifdef _MSC_VER |
| 29 | #ifdef _CINDEX_LIB_ |
| 30 | #define CINDEX_LINKAGE __declspec(dllexport) |
| 31 | #else |
| 32 | #define CINDEX_LINKAGE __declspec(dllimport) |
| 33 | #endif |
| 34 | #else |
| 35 | #define CINDEX_LINKAGE |
| 36 | #endif |
| 37 | |
Douglas Gregor | 87fb940 | 2011-02-23 17:45:25 +0000 | [diff] [blame] | 38 | /** \defgroup CINDEX libclang: C Interface to Clang |
Douglas Gregor | 20d416c | 2010-01-20 01:10:47 +0000 | [diff] [blame] | 39 | * |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 40 | * The C Interface to Clang provides a relatively small API that exposes |
Douglas Gregor | f552544 | 2010-01-20 22:45:41 +0000 | [diff] [blame] | 41 | * facilities for parsing source code into an abstract syntax tree (AST), |
| 42 | * loading already-parsed ASTs, traversing the AST, associating |
| 43 | * physical source locations with elements within the AST, and other |
| 44 | * facilities that support Clang-based development tools. |
Douglas Gregor | 20d416c | 2010-01-20 01:10:47 +0000 | [diff] [blame] | 45 | * |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 46 | * This C interface to Clang will never provide all of the information |
Douglas Gregor | f552544 | 2010-01-20 22:45:41 +0000 | [diff] [blame] | 47 | * representation stored in Clang's C++ AST, nor should it: the intent is to |
| 48 | * maintain an API that is relatively stable from one release to the next, |
| 49 | * providing only the basic functionality needed to support development tools. |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 50 | * |
| 51 | * To avoid namespace pollution, data types are prefixed with "CX" and |
Douglas Gregor | f552544 | 2010-01-20 22:45:41 +0000 | [diff] [blame] | 52 | * functions are prefixed with "clang_". |
Douglas Gregor | 20d416c | 2010-01-20 01:10:47 +0000 | [diff] [blame] | 53 | * |
| 54 | * @{ |
| 55 | */ |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 56 | |
Douglas Gregor | 7f17376 | 2010-01-20 22:28:27 +0000 | [diff] [blame] | 57 | /** |
| 58 | * \brief An "index" that consists of a set of translation units that would |
| 59 | * typically be linked together into an executable or library. |
| 60 | */ |
| 61 | typedef void *CXIndex; |
Steve Naroff | 600866c | 2009-08-27 19:51:58 +0000 | [diff] [blame] | 62 | |
Douglas Gregor | 7f17376 | 2010-01-20 22:28:27 +0000 | [diff] [blame] | 63 | /** |
| 64 | * \brief A single translation unit, which resides in an index. |
| 65 | */ |
Ted Kremenek | 0a90d32 | 2010-11-17 23:24:11 +0000 | [diff] [blame] | 66 | typedef struct CXTranslationUnitImpl *CXTranslationUnit; |
Steve Naroff | 600866c | 2009-08-27 19:51:58 +0000 | [diff] [blame] | 67 | |
Douglas Gregor | 7f17376 | 2010-01-20 22:28:27 +0000 | [diff] [blame] | 68 | /** |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 69 | * \brief Opaque pointer representing client data that will be passed through |
| 70 | * to various callbacks and visitors. |
Douglas Gregor | 7f17376 | 2010-01-20 22:28:27 +0000 | [diff] [blame] | 71 | */ |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 72 | typedef void *CXClientData; |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 73 | |
Douglas Gregor | 735df88 | 2009-12-02 09:21:34 +0000 | [diff] [blame] | 74 | /** |
| 75 | * \brief Provides the contents of a file that has not yet been saved to disk. |
| 76 | * |
| 77 | * Each CXUnsavedFile instance provides the name of a file on the |
| 78 | * system along with the current contents of that file that have not |
| 79 | * yet been saved to disk. |
| 80 | */ |
| 81 | struct CXUnsavedFile { |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 82 | /** |
| 83 | * \brief The file whose contents have not yet been saved. |
Douglas Gregor | 735df88 | 2009-12-02 09:21:34 +0000 | [diff] [blame] | 84 | * |
| 85 | * This file must already exist in the file system. |
| 86 | */ |
| 87 | const char *Filename; |
| 88 | |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 89 | /** |
Douglas Gregor | c8dfe5e | 2010-02-27 01:32:48 +0000 | [diff] [blame] | 90 | * \brief A buffer containing the unsaved contents of this file. |
Douglas Gregor | 735df88 | 2009-12-02 09:21:34 +0000 | [diff] [blame] | 91 | */ |
| 92 | const char *Contents; |
| 93 | |
| 94 | /** |
Douglas Gregor | c8dfe5e | 2010-02-27 01:32:48 +0000 | [diff] [blame] | 95 | * \brief The length of the unsaved contents of this buffer. |
Douglas Gregor | 735df88 | 2009-12-02 09:21:34 +0000 | [diff] [blame] | 96 | */ |
| 97 | unsigned long Length; |
| 98 | }; |
| 99 | |
Peter Collingbourne | 076c22a | 2010-08-24 00:31:37 +0000 | [diff] [blame] | 100 | /** |
| 101 | * \brief Describes the availability of a particular entity, which indicates |
| 102 | * whether the use of this entity will result in a warning or error due to |
| 103 | * it being deprecated or unavailable. |
| 104 | */ |
Douglas Gregor | 58ddb60 | 2010-08-23 23:00:57 +0000 | [diff] [blame] | 105 | enum CXAvailabilityKind { |
Peter Collingbourne | 076c22a | 2010-08-24 00:31:37 +0000 | [diff] [blame] | 106 | /** |
| 107 | * \brief The entity is available. |
| 108 | */ |
Douglas Gregor | 58ddb60 | 2010-08-23 23:00:57 +0000 | [diff] [blame] | 109 | CXAvailability_Available, |
Peter Collingbourne | 076c22a | 2010-08-24 00:31:37 +0000 | [diff] [blame] | 110 | /** |
| 111 | * \brief The entity is available, but has been deprecated (and its use is |
| 112 | * not recommended). |
| 113 | */ |
Douglas Gregor | 58ddb60 | 2010-08-23 23:00:57 +0000 | [diff] [blame] | 114 | CXAvailability_Deprecated, |
Peter Collingbourne | 076c22a | 2010-08-24 00:31:37 +0000 | [diff] [blame] | 115 | /** |
| 116 | * \brief The entity is not available; any use of it will be an error. |
| 117 | */ |
Erik Verbruggen | d120596 | 2011-10-06 07:27:49 +0000 | [diff] [blame] | 118 | CXAvailability_NotAvailable, |
| 119 | /** |
| 120 | * \brief The entity is available, but not accessible; any use of it will be |
| 121 | * an error. |
| 122 | */ |
| 123 | CXAvailability_NotAccessible |
Douglas Gregor | 58ddb60 | 2010-08-23 23:00:57 +0000 | [diff] [blame] | 124 | }; |
| 125 | |
Douglas Gregor | 7f17376 | 2010-01-20 22:28:27 +0000 | [diff] [blame] | 126 | /** |
Douglas Gregor | 7f17376 | 2010-01-20 22:28:27 +0000 | [diff] [blame] | 127 | * \defgroup CINDEX_STRING String manipulation routines |
| 128 | * |
| 129 | * @{ |
| 130 | */ |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 131 | |
Douglas Gregor | 7f17376 | 2010-01-20 22:28:27 +0000 | [diff] [blame] | 132 | /** |
| 133 | * \brief A character string. |
| 134 | * |
| 135 | * The \c CXString type is used to return strings from the interface when |
| 136 | * the ownership of that string might different from one call to the next. |
| 137 | * Use \c clang_getCString() to retrieve the string data and, once finished |
| 138 | * with the string data, call \c clang_disposeString() to free the string. |
Steve Naroff | ef0cef6 | 2009-11-09 17:45:52 +0000 | [diff] [blame] | 139 | */ |
| 140 | typedef struct { |
Ted Kremenek | a60ed47 | 2010-11-16 08:15:36 +0000 | [diff] [blame] | 141 | void *data; |
Ted Kremenek | ed12273 | 2010-11-16 01:56:27 +0000 | [diff] [blame] | 142 | unsigned private_flags; |
Steve Naroff | ef0cef6 | 2009-11-09 17:45:52 +0000 | [diff] [blame] | 143 | } CXString; |
| 144 | |
Douglas Gregor | 7f17376 | 2010-01-20 22:28:27 +0000 | [diff] [blame] | 145 | /** |
| 146 | * \brief Retrieve the character data associated with the given string. |
| 147 | */ |
Steve Naroff | ef0cef6 | 2009-11-09 17:45:52 +0000 | [diff] [blame] | 148 | CINDEX_LINKAGE const char *clang_getCString(CXString string); |
| 149 | |
Douglas Gregor | 7f17376 | 2010-01-20 22:28:27 +0000 | [diff] [blame] | 150 | /** |
| 151 | * \brief Free the given string, |
| 152 | */ |
Steve Naroff | ef0cef6 | 2009-11-09 17:45:52 +0000 | [diff] [blame] | 153 | CINDEX_LINKAGE void clang_disposeString(CXString string); |
| 154 | |
Douglas Gregor | 7f17376 | 2010-01-20 22:28:27 +0000 | [diff] [blame] | 155 | /** |
| 156 | * @} |
| 157 | */ |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 158 | |
| 159 | /** |
Steve Naroff | e56b4ba | 2009-10-20 14:46:24 +0000 | [diff] [blame] | 160 | * \brief clang_createIndex() provides a shared context for creating |
| 161 | * translation units. It provides two options: |
| 162 | * |
| 163 | * - excludeDeclarationsFromPCH: When non-zero, allows enumeration of "local" |
| 164 | * declarations (when loading any new translation units). A "local" declaration |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 165 | * 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] | 166 | * header that was used by the translation unit. If zero, all declarations |
| 167 | * will be enumerated. |
| 168 | * |
Steve Naroff | b4ece63 | 2009-10-20 16:36:34 +0000 | [diff] [blame] | 169 | * Here is an example: |
| 170 | * |
Douglas Gregor | 0a812cf | 2010-02-18 23:07:20 +0000 | [diff] [blame] | 171 | * // excludeDeclsFromPCH = 1, displayDiagnostics=1 |
| 172 | * Idx = clang_createIndex(1, 1); |
Steve Naroff | b4ece63 | 2009-10-20 16:36:34 +0000 | [diff] [blame] | 173 | * |
| 174 | * // IndexTest.pch was produced with the following command: |
| 175 | * // "clang -x c IndexTest.h -emit-ast -o IndexTest.pch" |
| 176 | * TU = clang_createTranslationUnit(Idx, "IndexTest.pch"); |
| 177 | * |
| 178 | * // This will load all the symbols from 'IndexTest.pch' |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 179 | * clang_visitChildren(clang_getTranslationUnitCursor(TU), |
Douglas Gregor | 002a528 | 2010-01-20 21:37:00 +0000 | [diff] [blame] | 180 | * TranslationUnitVisitor, 0); |
Steve Naroff | b4ece63 | 2009-10-20 16:36:34 +0000 | [diff] [blame] | 181 | * clang_disposeTranslationUnit(TU); |
| 182 | * |
| 183 | * // This will load all the symbols from 'IndexTest.c', excluding symbols |
| 184 | * // from 'IndexTest.pch'. |
Daniel Dunbar | fd9f234 | 2010-01-25 00:43:14 +0000 | [diff] [blame] | 185 | * char *args[] = { "-Xclang", "-include-pch=IndexTest.pch" }; |
| 186 | * TU = clang_createTranslationUnitFromSourceFile(Idx, "IndexTest.c", 2, args, |
| 187 | * 0, 0); |
Douglas Gregor | b2cd487 | 2010-01-20 23:57:43 +0000 | [diff] [blame] | 188 | * clang_visitChildren(clang_getTranslationUnitCursor(TU), |
| 189 | * TranslationUnitVisitor, 0); |
Steve Naroff | b4ece63 | 2009-10-20 16:36:34 +0000 | [diff] [blame] | 190 | * clang_disposeTranslationUnit(TU); |
| 191 | * |
| 192 | * This process of creating the 'pch', loading it separately, and using it (via |
| 193 | * -include-pch) allows 'excludeDeclsFromPCH' to remove redundant callbacks |
| 194 | * (which gives the indexer the same performance benefit as the compiler). |
Steve Naroff | e56b4ba | 2009-10-20 14:46:24 +0000 | [diff] [blame] | 195 | */ |
Douglas Gregor | 0a812cf | 2010-02-18 23:07:20 +0000 | [diff] [blame] | 196 | CINDEX_LINKAGE CXIndex clang_createIndex(int excludeDeclarationsFromPCH, |
| 197 | int displayDiagnostics); |
Ted Kremenek | 896b70f | 2010-03-13 02:50:34 +0000 | [diff] [blame] | 198 | |
Douglas Gregor | 0087e1a | 2010-02-08 23:03:06 +0000 | [diff] [blame] | 199 | /** |
| 200 | * \brief Destroy the given index. |
| 201 | * |
| 202 | * The index must not be destroyed until all of the translation units created |
| 203 | * within that index have been destroyed. |
| 204 | */ |
Daniel Dunbar | 8506dde | 2009-12-03 01:54:28 +0000 | [diff] [blame] | 205 | CINDEX_LINKAGE void clang_disposeIndex(CXIndex index); |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 206 | |
Argyrios Kyrtzidis | fdc1795 | 2012-03-28 02:18:05 +0000 | [diff] [blame^] | 207 | typedef enum { |
| 208 | /** |
| 209 | * \brief Used to indicate that no special CXIndex options are needed. |
| 210 | */ |
| 211 | CXGlobalOpt_None = 0x0, |
| 212 | |
| 213 | /** |
| 214 | * \brief Used to indicate that threads that libclang creates for indexing |
| 215 | * purposes should use background priority. |
| 216 | * Affects \see clang_indexSourceFile, \see clang_indexTranslationUnit, |
| 217 | * \see clang_parseTranslationUnit, \see clang_saveTranslationUnit. |
| 218 | */ |
| 219 | CXGlobalOpt_ThreadBackgroundPriorityForIndexing = 0x1, |
| 220 | |
| 221 | /** |
| 222 | * \brief Used to indicate that threads that libclang creates for editing |
| 223 | * purposes should use background priority. |
| 224 | * Affects \see clang_reparseTranslationUnit, \see clang_codeCompleteAt, |
| 225 | * \see clang_annotateTokens |
| 226 | */ |
| 227 | CXGlobalOpt_ThreadBackgroundPriorityForEditing = 0x2, |
| 228 | |
| 229 | /** |
| 230 | * \brief Used to indicate that all threads that libclang creates should use |
| 231 | * background priority. |
| 232 | */ |
| 233 | CXGlobalOpt_ThreadBackgroundPriorityForAll = |
| 234 | CXGlobalOpt_ThreadBackgroundPriorityForIndexing | |
| 235 | CXGlobalOpt_ThreadBackgroundPriorityForEditing |
| 236 | |
| 237 | } CXGlobalOptFlags; |
| 238 | |
| 239 | /** |
| 240 | * \brief Sets general options associated with a CXIndex. |
| 241 | * |
| 242 | * For example: |
| 243 | * \code |
| 244 | * CXIndex idx = ...; |
| 245 | * clang_CXIndex_setGlobalOptions(idx, |
| 246 | * clang_CXIndex_getGlobalOptions(idx) | |
| 247 | * CXGlobalOpt_ThreadBackgroundPriorityForIndexing); |
| 248 | * \endcode |
| 249 | * |
| 250 | * \param options A bitmask of options, a bitwise OR of CXGlobalOpt_XXX flags. |
| 251 | */ |
| 252 | CINDEX_LINKAGE void clang_CXIndex_setGlobalOptions(CXIndex, unsigned options); |
| 253 | |
| 254 | /** |
| 255 | * \brief Gets the general options associated with a CXIndex. |
| 256 | * |
| 257 | * \returns A bitmask of options, a bitwise OR of CXGlobalOpt_XXX flags that |
| 258 | * are associated with the given CXIndex object. |
| 259 | */ |
| 260 | CINDEX_LINKAGE unsigned clang_CXIndex_getGlobalOptions(CXIndex); |
| 261 | |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 262 | /** |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 263 | * \defgroup CINDEX_FILES File manipulation routines |
Douglas Gregor | f552544 | 2010-01-20 22:45:41 +0000 | [diff] [blame] | 264 | * |
| 265 | * @{ |
| 266 | */ |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 267 | |
Douglas Gregor | f552544 | 2010-01-20 22:45:41 +0000 | [diff] [blame] | 268 | /** |
| 269 | * \brief A particular source file that is part of a translation unit. |
| 270 | */ |
| 271 | typedef void *CXFile; |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 272 | |
Douglas Gregor | f552544 | 2010-01-20 22:45:41 +0000 | [diff] [blame] | 273 | |
| 274 | /** |
| 275 | * \brief Retrieve the complete file and path name of the given file. |
Steve Naroff | 8814503 | 2009-10-27 14:35:18 +0000 | [diff] [blame] | 276 | */ |
Ted Kremenek | 7484407 | 2010-02-17 00:41:20 +0000 | [diff] [blame] | 277 | CINDEX_LINKAGE CXString clang_getFileName(CXFile SFile); |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 278 | |
Douglas Gregor | f552544 | 2010-01-20 22:45:41 +0000 | [diff] [blame] | 279 | /** |
| 280 | * \brief Retrieve the last modification time of the given file. |
| 281 | */ |
Douglas Gregor | 08b0e8d | 2009-10-31 15:48:08 +0000 | [diff] [blame] | 282 | CINDEX_LINKAGE time_t clang_getFileTime(CXFile SFile); |
Steve Naroff | 8814503 | 2009-10-27 14:35:18 +0000 | [diff] [blame] | 283 | |
Douglas Gregor | 3c7313d | 2010-01-18 22:13:09 +0000 | [diff] [blame] | 284 | /** |
Douglas Gregor | dd3e554 | 2011-05-04 00:14:37 +0000 | [diff] [blame] | 285 | * \brief Determine whether the given header is guarded against |
| 286 | * multiple inclusions, either with the conventional |
| 287 | * #ifndef/#define/#endif macro guards or with #pragma once. |
| 288 | */ |
| 289 | CINDEX_LINKAGE unsigned |
| 290 | clang_isFileMultipleIncludeGuarded(CXTranslationUnit tu, CXFile file); |
| 291 | |
| 292 | /** |
Douglas Gregor | b979034 | 2010-01-22 21:44:22 +0000 | [diff] [blame] | 293 | * \brief Retrieve a file handle within the given translation unit. |
| 294 | * |
| 295 | * \param tu the translation unit |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 296 | * |
Douglas Gregor | b979034 | 2010-01-22 21:44:22 +0000 | [diff] [blame] | 297 | * \param file_name the name of the file. |
| 298 | * |
| 299 | * \returns the file handle for the named file in the translation unit \p tu, |
| 300 | * or a NULL file handle if the file was not a part of this translation unit. |
| 301 | */ |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 302 | CINDEX_LINKAGE CXFile clang_getFile(CXTranslationUnit tu, |
Douglas Gregor | b979034 | 2010-01-22 21:44:22 +0000 | [diff] [blame] | 303 | const char *file_name); |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 304 | |
Douglas Gregor | b979034 | 2010-01-22 21:44:22 +0000 | [diff] [blame] | 305 | /** |
Douglas Gregor | f552544 | 2010-01-20 22:45:41 +0000 | [diff] [blame] | 306 | * @} |
| 307 | */ |
| 308 | |
| 309 | /** |
| 310 | * \defgroup CINDEX_LOCATIONS Physical source locations |
| 311 | * |
| 312 | * Clang represents physical source locations in its abstract syntax tree in |
| 313 | * great detail, with file, line, and column information for the majority of |
| 314 | * the tokens parsed in the source code. These data types and functions are |
| 315 | * used to represent source location information, either for a particular |
| 316 | * point in the program or for a range of points in the program, and extract |
| 317 | * specific location information from those data types. |
| 318 | * |
| 319 | * @{ |
| 320 | */ |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 321 | |
Douglas Gregor | f552544 | 2010-01-20 22:45:41 +0000 | [diff] [blame] | 322 | /** |
Douglas Gregor | 1db19de | 2010-01-19 21:36:55 +0000 | [diff] [blame] | 323 | * \brief Identifies a specific source location within a translation |
| 324 | * unit. |
| 325 | * |
Chandler Carruth | 2017422 | 2011-08-31 16:53:37 +0000 | [diff] [blame] | 326 | * Use clang_getExpansionLocation() or clang_getSpellingLocation() |
Douglas Gregor | a9b06d4 | 2010-11-09 06:24:54 +0000 | [diff] [blame] | 327 | * to map a source location to a particular file, line, and column. |
Douglas Gregor | 3c7313d | 2010-01-18 22:13:09 +0000 | [diff] [blame] | 328 | */ |
| 329 | typedef struct { |
Douglas Gregor | 5352ac0 | 2010-01-28 00:27:43 +0000 | [diff] [blame] | 330 | void *ptr_data[2]; |
Douglas Gregor | 1db19de | 2010-01-19 21:36:55 +0000 | [diff] [blame] | 331 | unsigned int_data; |
Douglas Gregor | 3c7313d | 2010-01-18 22:13:09 +0000 | [diff] [blame] | 332 | } CXSourceLocation; |
Ted Kremenek | fe6fd3d | 2010-01-05 23:18:49 +0000 | [diff] [blame] | 333 | |
Douglas Gregor | 3c7313d | 2010-01-18 22:13:09 +0000 | [diff] [blame] | 334 | /** |
Daniel Dunbar | d52864b | 2010-02-14 10:02:57 +0000 | [diff] [blame] | 335 | * \brief Identifies a half-open character range in the source code. |
Douglas Gregor | 3c7313d | 2010-01-18 22:13:09 +0000 | [diff] [blame] | 336 | * |
Douglas Gregor | 1db19de | 2010-01-19 21:36:55 +0000 | [diff] [blame] | 337 | * Use clang_getRangeStart() and clang_getRangeEnd() to retrieve the |
| 338 | * starting and end locations from a source range, respectively. |
Douglas Gregor | 3c7313d | 2010-01-18 22:13:09 +0000 | [diff] [blame] | 339 | */ |
| 340 | typedef struct { |
Douglas Gregor | 5352ac0 | 2010-01-28 00:27:43 +0000 | [diff] [blame] | 341 | void *ptr_data[2]; |
Douglas Gregor | 1db19de | 2010-01-19 21:36:55 +0000 | [diff] [blame] | 342 | unsigned begin_int_data; |
| 343 | unsigned end_int_data; |
Douglas Gregor | 3c7313d | 2010-01-18 22:13:09 +0000 | [diff] [blame] | 344 | } CXSourceRange; |
Ted Kremenek | fe6fd3d | 2010-01-05 23:18:49 +0000 | [diff] [blame] | 345 | |
Douglas Gregor | 1db19de | 2010-01-19 21:36:55 +0000 | [diff] [blame] | 346 | /** |
Douglas Gregor | b979034 | 2010-01-22 21:44:22 +0000 | [diff] [blame] | 347 | * \brief Retrieve a NULL (invalid) source location. |
| 348 | */ |
| 349 | CINDEX_LINKAGE CXSourceLocation clang_getNullLocation(); |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 350 | |
Douglas Gregor | b979034 | 2010-01-22 21:44:22 +0000 | [diff] [blame] | 351 | /** |
| 352 | * \determine Determine whether two source locations, which must refer into |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 353 | * 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] | 354 | * code. |
| 355 | * |
| 356 | * \returns non-zero if the source locations refer to the same location, zero |
| 357 | * if they refer to different locations. |
| 358 | */ |
| 359 | CINDEX_LINKAGE unsigned clang_equalLocations(CXSourceLocation loc1, |
| 360 | CXSourceLocation loc2); |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 361 | |
Douglas Gregor | b979034 | 2010-01-22 21:44:22 +0000 | [diff] [blame] | 362 | /** |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 363 | * \brief Retrieves the source location associated with a given file/line/column |
| 364 | * in a particular translation unit. |
Douglas Gregor | b979034 | 2010-01-22 21:44:22 +0000 | [diff] [blame] | 365 | */ |
| 366 | CINDEX_LINKAGE CXSourceLocation clang_getLocation(CXTranslationUnit tu, |
| 367 | CXFile file, |
| 368 | unsigned line, |
| 369 | unsigned column); |
David Chisnall | 83889a7 | 2010-10-15 17:07:39 +0000 | [diff] [blame] | 370 | /** |
| 371 | * \brief Retrieves the source location associated with a given character offset |
| 372 | * in a particular translation unit. |
| 373 | */ |
| 374 | CINDEX_LINKAGE CXSourceLocation clang_getLocationForOffset(CXTranslationUnit tu, |
| 375 | CXFile file, |
| 376 | unsigned offset); |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 377 | |
Douglas Gregor | b979034 | 2010-01-22 21:44:22 +0000 | [diff] [blame] | 378 | /** |
Douglas Gregor | 5352ac0 | 2010-01-28 00:27:43 +0000 | [diff] [blame] | 379 | * \brief Retrieve a NULL (invalid) source range. |
| 380 | */ |
| 381 | CINDEX_LINKAGE CXSourceRange clang_getNullRange(); |
Ted Kremenek | 896b70f | 2010-03-13 02:50:34 +0000 | [diff] [blame] | 382 | |
Douglas Gregor | 5352ac0 | 2010-01-28 00:27:43 +0000 | [diff] [blame] | 383 | /** |
Douglas Gregor | b979034 | 2010-01-22 21:44:22 +0000 | [diff] [blame] | 384 | * \brief Retrieve a source range given the beginning and ending source |
| 385 | * locations. |
| 386 | */ |
| 387 | CINDEX_LINKAGE CXSourceRange clang_getRange(CXSourceLocation begin, |
| 388 | CXSourceLocation end); |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 389 | |
Douglas Gregor | b979034 | 2010-01-22 21:44:22 +0000 | [diff] [blame] | 390 | /** |
Douglas Gregor | ab4e83b | 2011-07-23 19:35:14 +0000 | [diff] [blame] | 391 | * \brief Determine whether two ranges are equivalent. |
| 392 | * |
| 393 | * \returns non-zero if the ranges are the same, zero if they differ. |
| 394 | */ |
| 395 | CINDEX_LINKAGE unsigned clang_equalRanges(CXSourceRange range1, |
| 396 | CXSourceRange range2); |
| 397 | |
| 398 | /** |
Argyrios Kyrtzidis | de5db64 | 2011-09-28 18:14:21 +0000 | [diff] [blame] | 399 | * \brief Returns non-zero if \arg range is null. |
| 400 | */ |
Erik Verbruggen | 733dbc8 | 2011-10-06 12:11:57 +0000 | [diff] [blame] | 401 | CINDEX_LINKAGE int clang_Range_isNull(CXSourceRange range); |
Argyrios Kyrtzidis | de5db64 | 2011-09-28 18:14:21 +0000 | [diff] [blame] | 402 | |
| 403 | /** |
Douglas Gregor | 46766dc | 2010-01-26 19:19:08 +0000 | [diff] [blame] | 404 | * \brief Retrieve the file, line, column, and offset represented by |
| 405 | * the given source location. |
Douglas Gregor | 1db19de | 2010-01-19 21:36:55 +0000 | [diff] [blame] | 406 | * |
Chandler Carruth | 2017422 | 2011-08-31 16:53:37 +0000 | [diff] [blame] | 407 | * If the location refers into a macro expansion, retrieves the |
| 408 | * location of the macro expansion. |
Douglas Gregor | a9b06d4 | 2010-11-09 06:24:54 +0000 | [diff] [blame] | 409 | * |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 410 | * \param location the location within a source file that will be decomposed |
| 411 | * into its parts. |
Douglas Gregor | 1db19de | 2010-01-19 21:36:55 +0000 | [diff] [blame] | 412 | * |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 413 | * \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] | 414 | * source location points. |
| 415 | * |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 416 | * \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] | 417 | * source location points. |
| 418 | * |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 419 | * \param column [out] if non-NULL, will be set to the column to which the given |
| 420 | * source location points. |
Douglas Gregor | 46766dc | 2010-01-26 19:19:08 +0000 | [diff] [blame] | 421 | * |
| 422 | * \param offset [out] if non-NULL, will be set to the offset into the |
| 423 | * buffer to which the given source location points. |
Douglas Gregor | 1db19de | 2010-01-19 21:36:55 +0000 | [diff] [blame] | 424 | */ |
Chandler Carruth | 2017422 | 2011-08-31 16:53:37 +0000 | [diff] [blame] | 425 | CINDEX_LINKAGE void clang_getExpansionLocation(CXSourceLocation location, |
| 426 | CXFile *file, |
| 427 | unsigned *line, |
| 428 | unsigned *column, |
| 429 | unsigned *offset); |
| 430 | |
| 431 | /** |
Argyrios Kyrtzidis | e6be34d | 2011-09-13 21:49:08 +0000 | [diff] [blame] | 432 | * \brief Retrieve the file, line, column, and offset represented by |
| 433 | * the given source location, as specified in a # line directive. |
| 434 | * |
| 435 | * Example: given the following source code in a file somefile.c |
| 436 | * |
| 437 | * #123 "dummy.c" 1 |
| 438 | * |
| 439 | * static int func(void) |
| 440 | * { |
| 441 | * return 0; |
| 442 | * } |
| 443 | * |
| 444 | * the location information returned by this function would be |
| 445 | * |
| 446 | * File: dummy.c Line: 124 Column: 12 |
| 447 | * |
| 448 | * whereas clang_getExpansionLocation would have returned |
| 449 | * |
| 450 | * File: somefile.c Line: 3 Column: 12 |
| 451 | * |
| 452 | * \param location the location within a source file that will be decomposed |
| 453 | * into its parts. |
| 454 | * |
| 455 | * \param filename [out] if non-NULL, will be set to the filename of the |
| 456 | * source location. Note that filenames returned will be for "virtual" files, |
| 457 | * which don't necessarily exist on the machine running clang - e.g. when |
| 458 | * parsing preprocessed output obtained from a different environment. If |
| 459 | * a non-NULL value is passed in, remember to dispose of the returned value |
| 460 | * using \c clang_disposeString() once you've finished with it. For an invalid |
| 461 | * source location, an empty string is returned. |
| 462 | * |
| 463 | * \param line [out] if non-NULL, will be set to the line number of the |
| 464 | * source location. For an invalid source location, zero is returned. |
| 465 | * |
| 466 | * \param column [out] if non-NULL, will be set to the column number of the |
| 467 | * source location. For an invalid source location, zero is returned. |
| 468 | */ |
| 469 | CINDEX_LINKAGE void clang_getPresumedLocation(CXSourceLocation location, |
| 470 | CXString *filename, |
| 471 | unsigned *line, |
| 472 | unsigned *column); |
| 473 | |
| 474 | /** |
Chandler Carruth | 2017422 | 2011-08-31 16:53:37 +0000 | [diff] [blame] | 475 | * \brief Legacy API to retrieve the file, line, column, and offset represented |
| 476 | * by the given source location. |
| 477 | * |
| 478 | * This interface has been replaced by the newer interface |
| 479 | * \see clang_getExpansionLocation(). See that interface's documentation for |
| 480 | * details. |
| 481 | */ |
Douglas Gregor | 1db19de | 2010-01-19 21:36:55 +0000 | [diff] [blame] | 482 | CINDEX_LINKAGE void clang_getInstantiationLocation(CXSourceLocation location, |
| 483 | CXFile *file, |
| 484 | unsigned *line, |
Douglas Gregor | 46766dc | 2010-01-26 19:19:08 +0000 | [diff] [blame] | 485 | unsigned *column, |
| 486 | unsigned *offset); |
Douglas Gregor | e69517c | 2010-01-26 03:07:15 +0000 | [diff] [blame] | 487 | |
| 488 | /** |
Douglas Gregor | a9b06d4 | 2010-11-09 06:24:54 +0000 | [diff] [blame] | 489 | * \brief Retrieve the file, line, column, and offset represented by |
| 490 | * the given source location. |
| 491 | * |
| 492 | * If the location refers into a macro instantiation, return where the |
| 493 | * location was originally spelled in the source file. |
| 494 | * |
| 495 | * \param location the location within a source file that will be decomposed |
| 496 | * into its parts. |
| 497 | * |
| 498 | * \param file [out] if non-NULL, will be set to the file to which the given |
| 499 | * source location points. |
| 500 | * |
| 501 | * \param line [out] if non-NULL, will be set to the line to which the given |
| 502 | * source location points. |
| 503 | * |
| 504 | * \param column [out] if non-NULL, will be set to the column to which the given |
| 505 | * source location points. |
| 506 | * |
| 507 | * \param offset [out] if non-NULL, will be set to the offset into the |
| 508 | * buffer to which the given source location points. |
| 509 | */ |
| 510 | CINDEX_LINKAGE void clang_getSpellingLocation(CXSourceLocation location, |
| 511 | CXFile *file, |
| 512 | unsigned *line, |
| 513 | unsigned *column, |
| 514 | unsigned *offset); |
| 515 | |
| 516 | /** |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 517 | * \brief Retrieve a source location representing the first character within a |
| 518 | * source range. |
Douglas Gregor | 1db19de | 2010-01-19 21:36:55 +0000 | [diff] [blame] | 519 | */ |
| 520 | CINDEX_LINKAGE CXSourceLocation clang_getRangeStart(CXSourceRange range); |
| 521 | |
| 522 | /** |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 523 | * \brief Retrieve a source location representing the last character within a |
| 524 | * source range. |
Douglas Gregor | 1db19de | 2010-01-19 21:36:55 +0000 | [diff] [blame] | 525 | */ |
| 526 | CINDEX_LINKAGE CXSourceLocation clang_getRangeEnd(CXSourceRange range); |
| 527 | |
Douglas Gregor | f552544 | 2010-01-20 22:45:41 +0000 | [diff] [blame] | 528 | /** |
| 529 | * @} |
| 530 | */ |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 531 | |
| 532 | /** |
Douglas Gregor | 5352ac0 | 2010-01-28 00:27:43 +0000 | [diff] [blame] | 533 | * \defgroup CINDEX_DIAG Diagnostic reporting |
| 534 | * |
| 535 | * @{ |
| 536 | */ |
| 537 | |
| 538 | /** |
| 539 | * \brief Describes the severity of a particular diagnostic. |
| 540 | */ |
| 541 | enum CXDiagnosticSeverity { |
| 542 | /** |
Ted Kremenek | 896b70f | 2010-03-13 02:50:34 +0000 | [diff] [blame] | 543 | * \brief A diagnostic that has been suppressed, e.g., by a command-line |
Douglas Gregor | 5352ac0 | 2010-01-28 00:27:43 +0000 | [diff] [blame] | 544 | * option. |
| 545 | */ |
| 546 | CXDiagnostic_Ignored = 0, |
Ted Kremenek | 896b70f | 2010-03-13 02:50:34 +0000 | [diff] [blame] | 547 | |
Douglas Gregor | 5352ac0 | 2010-01-28 00:27:43 +0000 | [diff] [blame] | 548 | /** |
| 549 | * \brief This diagnostic is a note that should be attached to the |
| 550 | * previous (non-note) diagnostic. |
| 551 | */ |
| 552 | CXDiagnostic_Note = 1, |
| 553 | |
| 554 | /** |
| 555 | * \brief This diagnostic indicates suspicious code that may not be |
| 556 | * wrong. |
| 557 | */ |
| 558 | CXDiagnostic_Warning = 2, |
| 559 | |
| 560 | /** |
| 561 | * \brief This diagnostic indicates that the code is ill-formed. |
| 562 | */ |
| 563 | CXDiagnostic_Error = 3, |
| 564 | |
| 565 | /** |
| 566 | * \brief This diagnostic indicates that the code is ill-formed such |
| 567 | * that future parser recovery is unlikely to produce useful |
| 568 | * results. |
| 569 | */ |
| 570 | CXDiagnostic_Fatal = 4 |
| 571 | }; |
| 572 | |
| 573 | /** |
Douglas Gregor | 5352ac0 | 2010-01-28 00:27:43 +0000 | [diff] [blame] | 574 | * \brief A single diagnostic, containing the diagnostic's severity, |
| 575 | * location, text, source ranges, and fix-it hints. |
| 576 | */ |
| 577 | typedef void *CXDiagnostic; |
| 578 | |
| 579 | /** |
Ted Kremenek | 1532217 | 2011-11-10 08:43:12 +0000 | [diff] [blame] | 580 | * \brief A group of CXDiagnostics. |
| 581 | */ |
| 582 | typedef void *CXDiagnosticSet; |
| 583 | |
| 584 | /** |
| 585 | * \brief Determine the number of diagnostics in a CXDiagnosticSet. |
| 586 | */ |
| 587 | CINDEX_LINKAGE unsigned clang_getNumDiagnosticsInSet(CXDiagnosticSet Diags); |
| 588 | |
| 589 | /** |
| 590 | * \brief Retrieve a diagnostic associated with the given CXDiagnosticSet. |
| 591 | * |
| 592 | * \param Unit the CXDiagnosticSet to query. |
| 593 | * \param Index the zero-based diagnostic number to retrieve. |
| 594 | * |
| 595 | * \returns the requested diagnostic. This diagnostic must be freed |
| 596 | * via a call to \c clang_disposeDiagnostic(). |
| 597 | */ |
| 598 | CINDEX_LINKAGE CXDiagnostic clang_getDiagnosticInSet(CXDiagnosticSet Diags, |
| 599 | unsigned Index); |
| 600 | |
| 601 | |
| 602 | /** |
| 603 | * \brief Describes the kind of error that occurred (if any) in a call to |
| 604 | * \c clang_loadDiagnostics. |
| 605 | */ |
| 606 | enum CXLoadDiag_Error { |
| 607 | /** |
| 608 | * \brief Indicates that no error occurred. |
| 609 | */ |
| 610 | CXLoadDiag_None = 0, |
| 611 | |
| 612 | /** |
| 613 | * \brief Indicates that an unknown error occurred while attempting to |
| 614 | * deserialize diagnostics. |
| 615 | */ |
| 616 | CXLoadDiag_Unknown = 1, |
| 617 | |
| 618 | /** |
| 619 | * \brief Indicates that the file containing the serialized diagnostics |
| 620 | * could not be opened. |
| 621 | */ |
| 622 | CXLoadDiag_CannotLoad = 2, |
| 623 | |
| 624 | /** |
| 625 | * \brief Indicates that the serialized diagnostics file is invalid or |
| 626 | * corrupt. |
| 627 | */ |
| 628 | CXLoadDiag_InvalidFile = 3 |
| 629 | }; |
| 630 | |
| 631 | /** |
| 632 | * \brief Deserialize a set of diagnostics from a Clang diagnostics bitcode |
| 633 | * file. |
| 634 | * |
| 635 | * \param The name of the file to deserialize. |
| 636 | * \param A pointer to a enum value recording if there was a problem |
| 637 | * deserializing the diagnostics. |
| 638 | * \param A pointer to a CXString for recording the error string |
| 639 | * if the file was not successfully loaded. |
| 640 | * |
| 641 | * \returns A loaded CXDiagnosticSet if successful, and NULL otherwise. These |
| 642 | * diagnostics should be released using clang_disposeDiagnosticSet(). |
| 643 | */ |
| 644 | CINDEX_LINKAGE CXDiagnosticSet clang_loadDiagnostics(const char *file, |
| 645 | enum CXLoadDiag_Error *error, |
| 646 | CXString *errorString); |
| 647 | |
| 648 | /** |
| 649 | * \brief Release a CXDiagnosticSet and all of its contained diagnostics. |
| 650 | */ |
| 651 | CINDEX_LINKAGE void clang_disposeDiagnosticSet(CXDiagnosticSet Diags); |
| 652 | |
| 653 | /** |
| 654 | * \brief Retrieve the child diagnostics of a CXDiagnostic. This |
| 655 | * CXDiagnosticSet does not need to be released by clang_diposeDiagnosticSet. |
| 656 | */ |
| 657 | CINDEX_LINKAGE CXDiagnosticSet clang_getChildDiagnostics(CXDiagnostic D); |
| 658 | |
| 659 | /** |
Douglas Gregor | a88084b | 2010-02-18 18:08:43 +0000 | [diff] [blame] | 660 | * \brief Determine the number of diagnostics produced for the given |
| 661 | * translation unit. |
Douglas Gregor | 5352ac0 | 2010-01-28 00:27:43 +0000 | [diff] [blame] | 662 | */ |
Douglas Gregor | a88084b | 2010-02-18 18:08:43 +0000 | [diff] [blame] | 663 | CINDEX_LINKAGE unsigned clang_getNumDiagnostics(CXTranslationUnit Unit); |
| 664 | |
| 665 | /** |
| 666 | * \brief Retrieve a diagnostic associated with the given translation unit. |
| 667 | * |
| 668 | * \param Unit the translation unit to query. |
| 669 | * \param Index the zero-based diagnostic number to retrieve. |
| 670 | * |
| 671 | * \returns the requested diagnostic. This diagnostic must be freed |
| 672 | * via a call to \c clang_disposeDiagnostic(). |
| 673 | */ |
| 674 | CINDEX_LINKAGE CXDiagnostic clang_getDiagnostic(CXTranslationUnit Unit, |
| 675 | unsigned Index); |
| 676 | |
| 677 | /** |
Ted Kremenek | 0373fcc | 2011-12-09 22:28:32 +0000 | [diff] [blame] | 678 | * \brief Retrieve the complete set of diagnostics associated with a |
| 679 | * translation unit. |
| 680 | * |
| 681 | * \param Unit the translation unit to query. |
| 682 | */ |
| 683 | CINDEX_LINKAGE CXDiagnosticSet |
| 684 | clang_getDiagnosticSetFromTU(CXTranslationUnit Unit); |
| 685 | |
| 686 | /** |
Douglas Gregor | a88084b | 2010-02-18 18:08:43 +0000 | [diff] [blame] | 687 | * \brief Destroy a diagnostic. |
| 688 | */ |
| 689 | CINDEX_LINKAGE void clang_disposeDiagnostic(CXDiagnostic Diagnostic); |
Douglas Gregor | 5352ac0 | 2010-01-28 00:27:43 +0000 | [diff] [blame] | 690 | |
| 691 | /** |
Douglas Gregor | 0a812cf | 2010-02-18 23:07:20 +0000 | [diff] [blame] | 692 | * \brief Options to control the display of diagnostics. |
| 693 | * |
| 694 | * The values in this enum are meant to be combined to customize the |
| 695 | * behavior of \c clang_displayDiagnostic(). |
| 696 | */ |
| 697 | enum CXDiagnosticDisplayOptions { |
| 698 | /** |
| 699 | * \brief Display the source-location information where the |
| 700 | * diagnostic was located. |
| 701 | * |
| 702 | * When set, diagnostics will be prefixed by the file, line, and |
| 703 | * (optionally) column to which the diagnostic refers. For example, |
| 704 | * |
| 705 | * \code |
| 706 | * test.c:28: warning: extra tokens at end of #endif directive |
| 707 | * \endcode |
| 708 | * |
| 709 | * This option corresponds to the clang flag \c -fshow-source-location. |
| 710 | */ |
| 711 | CXDiagnostic_DisplaySourceLocation = 0x01, |
| 712 | |
| 713 | /** |
| 714 | * \brief If displaying the source-location information of the |
| 715 | * diagnostic, also include the column number. |
| 716 | * |
| 717 | * This option corresponds to the clang flag \c -fshow-column. |
| 718 | */ |
| 719 | CXDiagnostic_DisplayColumn = 0x02, |
| 720 | |
| 721 | /** |
| 722 | * \brief If displaying the source-location information of the |
| 723 | * diagnostic, also include information about source ranges in a |
| 724 | * machine-parsable format. |
| 725 | * |
Ted Kremenek | 896b70f | 2010-03-13 02:50:34 +0000 | [diff] [blame] | 726 | * This option corresponds to the clang flag |
Douglas Gregor | 0a812cf | 2010-02-18 23:07:20 +0000 | [diff] [blame] | 727 | * \c -fdiagnostics-print-source-range-info. |
| 728 | */ |
Douglas Gregor | aa5f135 | 2010-11-19 16:18:16 +0000 | [diff] [blame] | 729 | CXDiagnostic_DisplaySourceRanges = 0x04, |
| 730 | |
| 731 | /** |
| 732 | * \brief Display the option name associated with this diagnostic, if any. |
| 733 | * |
| 734 | * The option name displayed (e.g., -Wconversion) will be placed in brackets |
| 735 | * after the diagnostic text. This option corresponds to the clang flag |
| 736 | * \c -fdiagnostics-show-option. |
| 737 | */ |
| 738 | CXDiagnostic_DisplayOption = 0x08, |
| 739 | |
| 740 | /** |
| 741 | * \brief Display the category number associated with this diagnostic, if any. |
| 742 | * |
| 743 | * The category number is displayed within brackets after the diagnostic text. |
| 744 | * This option corresponds to the clang flag |
| 745 | * \c -fdiagnostics-show-category=id. |
| 746 | */ |
| 747 | CXDiagnostic_DisplayCategoryId = 0x10, |
| 748 | |
| 749 | /** |
| 750 | * \brief Display the category name associated with this diagnostic, if any. |
| 751 | * |
| 752 | * The category name is displayed within brackets after the diagnostic text. |
| 753 | * This option corresponds to the clang flag |
| 754 | * \c -fdiagnostics-show-category=name. |
| 755 | */ |
| 756 | CXDiagnostic_DisplayCategoryName = 0x20 |
Douglas Gregor | 0a812cf | 2010-02-18 23:07:20 +0000 | [diff] [blame] | 757 | }; |
| 758 | |
| 759 | /** |
Douglas Gregor | 274f190 | 2010-02-22 23:17:23 +0000 | [diff] [blame] | 760 | * \brief Format the given diagnostic in a manner that is suitable for display. |
Douglas Gregor | 0a812cf | 2010-02-18 23:07:20 +0000 | [diff] [blame] | 761 | * |
Douglas Gregor | 274f190 | 2010-02-22 23:17:23 +0000 | [diff] [blame] | 762 | * This routine will format the given diagnostic to a string, rendering |
Ted Kremenek | 896b70f | 2010-03-13 02:50:34 +0000 | [diff] [blame] | 763 | * the diagnostic according to the various options given. The |
| 764 | * \c clang_defaultDiagnosticDisplayOptions() function returns the set of |
Douglas Gregor | 0a812cf | 2010-02-18 23:07:20 +0000 | [diff] [blame] | 765 | * options that most closely mimics the behavior of the clang compiler. |
| 766 | * |
| 767 | * \param Diagnostic The diagnostic to print. |
| 768 | * |
Ted Kremenek | 896b70f | 2010-03-13 02:50:34 +0000 | [diff] [blame] | 769 | * \param Options A set of options that control the diagnostic display, |
Douglas Gregor | 0a812cf | 2010-02-18 23:07:20 +0000 | [diff] [blame] | 770 | * created by combining \c CXDiagnosticDisplayOptions values. |
Douglas Gregor | 274f190 | 2010-02-22 23:17:23 +0000 | [diff] [blame] | 771 | * |
| 772 | * \returns A new string containing for formatted diagnostic. |
Douglas Gregor | 0a812cf | 2010-02-18 23:07:20 +0000 | [diff] [blame] | 773 | */ |
Douglas Gregor | 274f190 | 2010-02-22 23:17:23 +0000 | [diff] [blame] | 774 | CINDEX_LINKAGE CXString clang_formatDiagnostic(CXDiagnostic Diagnostic, |
| 775 | unsigned Options); |
Douglas Gregor | 0a812cf | 2010-02-18 23:07:20 +0000 | [diff] [blame] | 776 | |
| 777 | /** |
| 778 | * \brief Retrieve the set of display options most similar to the |
| 779 | * default behavior of the clang compiler. |
| 780 | * |
| 781 | * \returns A set of display options suitable for use with \c |
| 782 | * clang_displayDiagnostic(). |
| 783 | */ |
| 784 | CINDEX_LINKAGE unsigned clang_defaultDiagnosticDisplayOptions(void); |
| 785 | |
| 786 | /** |
Douglas Gregor | 5352ac0 | 2010-01-28 00:27:43 +0000 | [diff] [blame] | 787 | * \brief Determine the severity of the given diagnostic. |
| 788 | */ |
Ted Kremenek | 896b70f | 2010-03-13 02:50:34 +0000 | [diff] [blame] | 789 | CINDEX_LINKAGE enum CXDiagnosticSeverity |
Douglas Gregor | 5352ac0 | 2010-01-28 00:27:43 +0000 | [diff] [blame] | 790 | clang_getDiagnosticSeverity(CXDiagnostic); |
| 791 | |
| 792 | /** |
| 793 | * \brief Retrieve the source location of the given diagnostic. |
| 794 | * |
| 795 | * This location is where Clang would print the caret ('^') when |
| 796 | * displaying the diagnostic on the command line. |
| 797 | */ |
| 798 | CINDEX_LINKAGE CXSourceLocation clang_getDiagnosticLocation(CXDiagnostic); |
| 799 | |
| 800 | /** |
| 801 | * \brief Retrieve the text of the given diagnostic. |
| 802 | */ |
| 803 | CINDEX_LINKAGE CXString clang_getDiagnosticSpelling(CXDiagnostic); |
Douglas Gregor | a3890ba | 2010-02-08 23:11:56 +0000 | [diff] [blame] | 804 | |
| 805 | /** |
Douglas Gregor | aa5f135 | 2010-11-19 16:18:16 +0000 | [diff] [blame] | 806 | * \brief Retrieve the name of the command-line option that enabled this |
| 807 | * diagnostic. |
| 808 | * |
| 809 | * \param Diag The diagnostic to be queried. |
| 810 | * |
| 811 | * \param Disable If non-NULL, will be set to the option that disables this |
| 812 | * diagnostic (if any). |
| 813 | * |
| 814 | * \returns A string that contains the command-line option used to enable this |
| 815 | * warning, such as "-Wconversion" or "-pedantic". |
| 816 | */ |
| 817 | CINDEX_LINKAGE CXString clang_getDiagnosticOption(CXDiagnostic Diag, |
| 818 | CXString *Disable); |
| 819 | |
| 820 | /** |
| 821 | * \brief Retrieve the category number for this diagnostic. |
| 822 | * |
| 823 | * Diagnostics can be categorized into groups along with other, related |
| 824 | * diagnostics (e.g., diagnostics under the same warning flag). This routine |
| 825 | * retrieves the category number for the given diagnostic. |
| 826 | * |
| 827 | * \returns The number of the category that contains this diagnostic, or zero |
| 828 | * if this diagnostic is uncategorized. |
| 829 | */ |
| 830 | CINDEX_LINKAGE unsigned clang_getDiagnosticCategory(CXDiagnostic); |
| 831 | |
| 832 | /** |
| 833 | * \brief Retrieve the name of a particular diagnostic category. |
| 834 | * |
| 835 | * \param Category A diagnostic category number, as returned by |
| 836 | * \c clang_getDiagnosticCategory(). |
| 837 | * |
| 838 | * \returns The name of the given diagnostic category. |
| 839 | */ |
| 840 | CINDEX_LINKAGE CXString clang_getDiagnosticCategoryName(unsigned Category); |
| 841 | |
| 842 | /** |
Douglas Gregor | a3890ba | 2010-02-08 23:11:56 +0000 | [diff] [blame] | 843 | * \brief Determine the number of source ranges associated with the given |
| 844 | * diagnostic. |
| 845 | */ |
| 846 | CINDEX_LINKAGE unsigned clang_getDiagnosticNumRanges(CXDiagnostic); |
Ted Kremenek | 896b70f | 2010-03-13 02:50:34 +0000 | [diff] [blame] | 847 | |
Douglas Gregor | 5352ac0 | 2010-01-28 00:27:43 +0000 | [diff] [blame] | 848 | /** |
Douglas Gregor | a3890ba | 2010-02-08 23:11:56 +0000 | [diff] [blame] | 849 | * \brief Retrieve a source range associated with the diagnostic. |
Douglas Gregor | 5352ac0 | 2010-01-28 00:27:43 +0000 | [diff] [blame] | 850 | * |
Douglas Gregor | a3890ba | 2010-02-08 23:11:56 +0000 | [diff] [blame] | 851 | * A diagnostic's source ranges highlight important elements in the source |
Douglas Gregor | 5352ac0 | 2010-01-28 00:27:43 +0000 | [diff] [blame] | 852 | * code. On the command line, Clang displays source ranges by |
Ted Kremenek | 896b70f | 2010-03-13 02:50:34 +0000 | [diff] [blame] | 853 | * underlining them with '~' characters. |
Douglas Gregor | 5352ac0 | 2010-01-28 00:27:43 +0000 | [diff] [blame] | 854 | * |
Douglas Gregor | a3890ba | 2010-02-08 23:11:56 +0000 | [diff] [blame] | 855 | * \param Diagnostic the diagnostic whose range is being extracted. |
Douglas Gregor | 5352ac0 | 2010-01-28 00:27:43 +0000 | [diff] [blame] | 856 | * |
Ted Kremenek | 896b70f | 2010-03-13 02:50:34 +0000 | [diff] [blame] | 857 | * \param Range the zero-based index specifying which range to |
Douglas Gregor | 5352ac0 | 2010-01-28 00:27:43 +0000 | [diff] [blame] | 858 | * |
Douglas Gregor | a3890ba | 2010-02-08 23:11:56 +0000 | [diff] [blame] | 859 | * \returns the requested source range. |
Douglas Gregor | 5352ac0 | 2010-01-28 00:27:43 +0000 | [diff] [blame] | 860 | */ |
Ted Kremenek | 896b70f | 2010-03-13 02:50:34 +0000 | [diff] [blame] | 861 | CINDEX_LINKAGE CXSourceRange clang_getDiagnosticRange(CXDiagnostic Diagnostic, |
Douglas Gregor | a3890ba | 2010-02-08 23:11:56 +0000 | [diff] [blame] | 862 | unsigned Range); |
Douglas Gregor | 5352ac0 | 2010-01-28 00:27:43 +0000 | [diff] [blame] | 863 | |
| 864 | /** |
| 865 | * \brief Determine the number of fix-it hints associated with the |
| 866 | * given diagnostic. |
| 867 | */ |
| 868 | CINDEX_LINKAGE unsigned clang_getDiagnosticNumFixIts(CXDiagnostic Diagnostic); |
| 869 | |
| 870 | /** |
Douglas Gregor | 473d701 | 2010-02-19 18:16:06 +0000 | [diff] [blame] | 871 | * \brief Retrieve the replacement information for a given fix-it. |
Douglas Gregor | 5352ac0 | 2010-01-28 00:27:43 +0000 | [diff] [blame] | 872 | * |
Douglas Gregor | 473d701 | 2010-02-19 18:16:06 +0000 | [diff] [blame] | 873 | * Fix-its are described in terms of a source range whose contents |
| 874 | * should be replaced by a string. This approach generalizes over |
| 875 | * three kinds of operations: removal of source code (the range covers |
| 876 | * the code to be removed and the replacement string is empty), |
| 877 | * replacement of source code (the range covers the code to be |
| 878 | * replaced and the replacement string provides the new code), and |
| 879 | * insertion (both the start and end of the range point at the |
| 880 | * insertion location, and the replacement string provides the text to |
| 881 | * insert). |
Douglas Gregor | 5352ac0 | 2010-01-28 00:27:43 +0000 | [diff] [blame] | 882 | * |
Douglas Gregor | 473d701 | 2010-02-19 18:16:06 +0000 | [diff] [blame] | 883 | * \param Diagnostic The diagnostic whose fix-its are being queried. |
| 884 | * |
| 885 | * \param FixIt The zero-based index of the fix-it. |
| 886 | * |
| 887 | * \param ReplacementRange The source range whose contents will be |
| 888 | * replaced with the returned replacement string. Note that source |
| 889 | * ranges are half-open ranges [a, b), so the source code should be |
| 890 | * replaced from a and up to (but not including) b. |
| 891 | * |
| 892 | * \returns A string containing text that should be replace the source |
| 893 | * code indicated by the \c ReplacementRange. |
Douglas Gregor | 5352ac0 | 2010-01-28 00:27:43 +0000 | [diff] [blame] | 894 | */ |
Ted Kremenek | 896b70f | 2010-03-13 02:50:34 +0000 | [diff] [blame] | 895 | CINDEX_LINKAGE CXString clang_getDiagnosticFixIt(CXDiagnostic Diagnostic, |
Douglas Gregor | 473d701 | 2010-02-19 18:16:06 +0000 | [diff] [blame] | 896 | unsigned FixIt, |
| 897 | CXSourceRange *ReplacementRange); |
Douglas Gregor | 5352ac0 | 2010-01-28 00:27:43 +0000 | [diff] [blame] | 898 | |
| 899 | /** |
| 900 | * @} |
| 901 | */ |
| 902 | |
| 903 | /** |
| 904 | * \defgroup CINDEX_TRANSLATION_UNIT Translation unit manipulation |
| 905 | * |
| 906 | * The routines in this group provide the ability to create and destroy |
| 907 | * translation units from files, either by parsing the contents of the files or |
| 908 | * by reading in a serialized representation of a translation unit. |
| 909 | * |
| 910 | * @{ |
| 911 | */ |
Ted Kremenek | 896b70f | 2010-03-13 02:50:34 +0000 | [diff] [blame] | 912 | |
Douglas Gregor | 5352ac0 | 2010-01-28 00:27:43 +0000 | [diff] [blame] | 913 | /** |
| 914 | * \brief Get the original translation unit source file name. |
| 915 | */ |
| 916 | CINDEX_LINKAGE CXString |
| 917 | clang_getTranslationUnitSpelling(CXTranslationUnit CTUnit); |
| 918 | |
| 919 | /** |
| 920 | * \brief Return the CXTranslationUnit for a given source file and the provided |
| 921 | * command line arguments one would pass to the compiler. |
| 922 | * |
| 923 | * Note: The 'source_filename' argument is optional. If the caller provides a |
| 924 | * NULL pointer, the name of the source file is expected to reside in the |
| 925 | * specified command line arguments. |
| 926 | * |
| 927 | * Note: When encountered in 'clang_command_line_args', the following options |
| 928 | * are ignored: |
| 929 | * |
| 930 | * '-c' |
| 931 | * '-emit-ast' |
| 932 | * '-fsyntax-only' |
| 933 | * '-o <output file>' (both '-o' and '<output file>' are ignored) |
| 934 | * |
Ted Kremenek | 1ddb02c | 2010-11-08 04:28:51 +0000 | [diff] [blame] | 935 | * \param CIdx The index object with which the translation unit will be |
| 936 | * associated. |
Douglas Gregor | 5352ac0 | 2010-01-28 00:27:43 +0000 | [diff] [blame] | 937 | * |
| 938 | * \param source_filename - The name of the source file to load, or NULL if the |
Ted Kremenek | 1ddb02c | 2010-11-08 04:28:51 +0000 | [diff] [blame] | 939 | * source file is included in \p clang_command_line_args. |
| 940 | * |
| 941 | * \param num_clang_command_line_args The number of command-line arguments in |
| 942 | * \p clang_command_line_args. |
| 943 | * |
| 944 | * \param clang_command_line_args The command-line arguments that would be |
| 945 | * passed to the \c clang executable if it were being invoked out-of-process. |
| 946 | * These command-line options will be parsed and will affect how the translation |
| 947 | * unit is parsed. Note that the following options are ignored: '-c', |
| 948 | * '-emit-ast', '-fsyntex-only' (which is the default), and '-o <output file>'. |
Douglas Gregor | 5352ac0 | 2010-01-28 00:27:43 +0000 | [diff] [blame] | 949 | * |
| 950 | * \param num_unsaved_files the number of unsaved file entries in \p |
| 951 | * unsaved_files. |
| 952 | * |
| 953 | * \param unsaved_files the files that have not yet been saved to disk |
| 954 | * but may be required for code completion, including the contents of |
Ted Kremenek | c6f530d | 2010-04-12 18:47:26 +0000 | [diff] [blame] | 955 | * those files. The contents and name of these files (as specified by |
| 956 | * CXUnsavedFile) are copied when necessary, so the client only needs to |
| 957 | * guarantee their validity until the call to this function returns. |
Douglas Gregor | 5352ac0 | 2010-01-28 00:27:43 +0000 | [diff] [blame] | 958 | */ |
| 959 | CINDEX_LINKAGE CXTranslationUnit clang_createTranslationUnitFromSourceFile( |
| 960 | CXIndex CIdx, |
| 961 | const char *source_filename, |
| 962 | int num_clang_command_line_args, |
Douglas Gregor | 2ef6944 | 2010-09-01 16:43:19 +0000 | [diff] [blame] | 963 | const char * const *clang_command_line_args, |
Douglas Gregor | 5352ac0 | 2010-01-28 00:27:43 +0000 | [diff] [blame] | 964 | unsigned num_unsaved_files, |
Douglas Gregor | a88084b | 2010-02-18 18:08:43 +0000 | [diff] [blame] | 965 | struct CXUnsavedFile *unsaved_files); |
Ted Kremenek | 896b70f | 2010-03-13 02:50:34 +0000 | [diff] [blame] | 966 | |
Douglas Gregor | 5352ac0 | 2010-01-28 00:27:43 +0000 | [diff] [blame] | 967 | /** |
| 968 | * \brief Create a translation unit from an AST file (-emit-ast). |
| 969 | */ |
Ted Kremenek | 896b70f | 2010-03-13 02:50:34 +0000 | [diff] [blame] | 970 | CINDEX_LINKAGE CXTranslationUnit clang_createTranslationUnit(CXIndex, |
Douglas Gregor | a88084b | 2010-02-18 18:08:43 +0000 | [diff] [blame] | 971 | const char *ast_filename); |
Douglas Gregor | 5352ac0 | 2010-01-28 00:27:43 +0000 | [diff] [blame] | 972 | |
Douglas Gregor | 44c181a | 2010-07-23 00:33:23 +0000 | [diff] [blame] | 973 | /** |
| 974 | * \brief Flags that control the creation of translation units. |
| 975 | * |
| 976 | * The enumerators in this enumeration type are meant to be bitwise |
| 977 | * ORed together to specify which options should be used when |
| 978 | * constructing the translation unit. |
| 979 | */ |
Douglas Gregor | 5a43021 | 2010-07-21 18:52:53 +0000 | [diff] [blame] | 980 | enum CXTranslationUnit_Flags { |
| 981 | /** |
| 982 | * \brief Used to indicate that no special translation-unit options are |
| 983 | * needed. |
| 984 | */ |
| 985 | CXTranslationUnit_None = 0x0, |
| 986 | |
| 987 | /** |
| 988 | * \brief Used to indicate that the parser should construct a "detailed" |
| 989 | * preprocessing record, including all macro definitions and instantiations. |
| 990 | * |
| 991 | * Constructing a detailed preprocessing record requires more memory |
| 992 | * and time to parse, since the information contained in the record |
| 993 | * is usually not retained. However, it can be useful for |
| 994 | * applications that require more detailed information about the |
| 995 | * behavior of the preprocessor. |
| 996 | */ |
Douglas Gregor | 44c181a | 2010-07-23 00:33:23 +0000 | [diff] [blame] | 997 | CXTranslationUnit_DetailedPreprocessingRecord = 0x01, |
| 998 | |
| 999 | /** |
Douglas Gregor | b1c031b | 2010-08-09 22:28:58 +0000 | [diff] [blame] | 1000 | * \brief Used to indicate that the translation unit is incomplete. |
Douglas Gregor | 44c181a | 2010-07-23 00:33:23 +0000 | [diff] [blame] | 1001 | * |
Douglas Gregor | b1c031b | 2010-08-09 22:28:58 +0000 | [diff] [blame] | 1002 | * When a translation unit is considered "incomplete", semantic |
| 1003 | * analysis that is typically performed at the end of the |
| 1004 | * translation unit will be suppressed. For example, this suppresses |
| 1005 | * the completion of tentative declarations in C and of |
| 1006 | * instantiation of implicitly-instantiation function templates in |
| 1007 | * C++. This option is typically used when parsing a header with the |
| 1008 | * intent of producing a precompiled header. |
Douglas Gregor | 44c181a | 2010-07-23 00:33:23 +0000 | [diff] [blame] | 1009 | */ |
Douglas Gregor | b1c031b | 2010-08-09 22:28:58 +0000 | [diff] [blame] | 1010 | CXTranslationUnit_Incomplete = 0x02, |
Douglas Gregor | 44c181a | 2010-07-23 00:33:23 +0000 | [diff] [blame] | 1011 | |
| 1012 | /** |
| 1013 | * \brief Used to indicate that the translation unit should be built with an |
| 1014 | * implicit precompiled header for the preamble. |
| 1015 | * |
| 1016 | * An implicit precompiled header is used as an optimization when a |
| 1017 | * particular translation unit is likely to be reparsed many times |
| 1018 | * when the sources aren't changing that often. In this case, an |
| 1019 | * implicit precompiled header will be built containing all of the |
| 1020 | * initial includes at the top of the main file (what we refer to as |
| 1021 | * the "preamble" of the file). In subsequent parses, if the |
| 1022 | * preamble or the files in it have not changed, \c |
| 1023 | * clang_reparseTranslationUnit() will re-use the implicit |
| 1024 | * precompiled header to improve parsing performance. |
| 1025 | */ |
Douglas Gregor | e1e13bf | 2010-08-11 15:58:42 +0000 | [diff] [blame] | 1026 | CXTranslationUnit_PrecompiledPreamble = 0x04, |
| 1027 | |
| 1028 | /** |
| 1029 | * \brief Used to indicate that the translation unit should cache some |
| 1030 | * code-completion results with each reparse of the source file. |
| 1031 | * |
| 1032 | * Caching of code-completion results is a performance optimization that |
| 1033 | * introduces some overhead to reparsing but improves the performance of |
| 1034 | * code-completion operations. |
| 1035 | */ |
Douglas Gregor | 99ba202 | 2010-10-27 17:24:53 +0000 | [diff] [blame] | 1036 | CXTranslationUnit_CacheCompletionResults = 0x08, |
| 1037 | /** |
Douglas Gregor | b5af843 | 2011-08-25 22:54:01 +0000 | [diff] [blame] | 1038 | * \brief DEPRECATED: Enable precompiled preambles in C++. |
Douglas Gregor | 99ba202 | 2010-10-27 17:24:53 +0000 | [diff] [blame] | 1039 | * |
| 1040 | * Note: this is a *temporary* option that is available only while |
Douglas Gregor | b5af843 | 2011-08-25 22:54:01 +0000 | [diff] [blame] | 1041 | * we are testing C++ precompiled preamble support. It is deprecated. |
Douglas Gregor | 99ba202 | 2010-10-27 17:24:53 +0000 | [diff] [blame] | 1042 | */ |
| 1043 | CXTranslationUnit_CXXPrecompiledPreamble = 0x10, |
| 1044 | |
| 1045 | /** |
Douglas Gregor | b5af843 | 2011-08-25 22:54:01 +0000 | [diff] [blame] | 1046 | * \brief DEPRECATED: Enabled chained precompiled preambles in C++. |
Douglas Gregor | 99ba202 | 2010-10-27 17:24:53 +0000 | [diff] [blame] | 1047 | * |
| 1048 | * Note: this is a *temporary* option that is available only while |
Douglas Gregor | b5af843 | 2011-08-25 22:54:01 +0000 | [diff] [blame] | 1049 | * we are testing C++ precompiled preamble support. It is deprecated. |
Douglas Gregor | 99ba202 | 2010-10-27 17:24:53 +0000 | [diff] [blame] | 1050 | */ |
Argyrios Kyrtzidis | e1d4330 | 2012-02-25 02:41:16 +0000 | [diff] [blame] | 1051 | CXTranslationUnit_CXXChainedPCH = 0x20 |
Douglas Gregor | 5a43021 | 2010-07-21 18:52:53 +0000 | [diff] [blame] | 1052 | }; |
| 1053 | |
| 1054 | /** |
Douglas Gregor | b1c031b | 2010-08-09 22:28:58 +0000 | [diff] [blame] | 1055 | * \brief Returns the set of flags that is suitable for parsing a translation |
| 1056 | * unit that is being edited. |
| 1057 | * |
| 1058 | * The set of flags returned provide options for \c clang_parseTranslationUnit() |
| 1059 | * to indicate that the translation unit is likely to be reparsed many times, |
| 1060 | * either explicitly (via \c clang_reparseTranslationUnit()) or implicitly |
| 1061 | * (e.g., by code completion (\c clang_codeCompletionAt())). The returned flag |
| 1062 | * set contains an unspecified set of optimizations (e.g., the precompiled |
| 1063 | * preamble) geared toward improving the performance of these routines. The |
| 1064 | * set of optimizations enabled may change from one version to the next. |
| 1065 | */ |
Douglas Gregor | e1e13bf | 2010-08-11 15:58:42 +0000 | [diff] [blame] | 1066 | CINDEX_LINKAGE unsigned clang_defaultEditingTranslationUnitOptions(void); |
Douglas Gregor | b1c031b | 2010-08-09 22:28:58 +0000 | [diff] [blame] | 1067 | |
| 1068 | /** |
Douglas Gregor | 5a43021 | 2010-07-21 18:52:53 +0000 | [diff] [blame] | 1069 | * \brief Parse the given source file and the translation unit corresponding |
| 1070 | * to that file. |
| 1071 | * |
| 1072 | * This routine is the main entry point for the Clang C API, providing the |
| 1073 | * ability to parse a source file into a translation unit that can then be |
| 1074 | * queried by other functions in the API. This routine accepts a set of |
| 1075 | * command-line arguments so that the compilation can be configured in the same |
| 1076 | * way that the compiler is configured on the command line. |
| 1077 | * |
| 1078 | * \param CIdx The index object with which the translation unit will be |
| 1079 | * associated. |
| 1080 | * |
| 1081 | * \param source_filename The name of the source file to load, or NULL if the |
Ted Kremenek | 1ddb02c | 2010-11-08 04:28:51 +0000 | [diff] [blame] | 1082 | * source file is included in \p command_line_args. |
Douglas Gregor | 5a43021 | 2010-07-21 18:52:53 +0000 | [diff] [blame] | 1083 | * |
| 1084 | * \param command_line_args The command-line arguments that would be |
| 1085 | * passed to the \c clang executable if it were being invoked out-of-process. |
| 1086 | * These command-line options will be parsed and will affect how the translation |
| 1087 | * unit is parsed. Note that the following options are ignored: '-c', |
| 1088 | * '-emit-ast', '-fsyntex-only' (which is the default), and '-o <output file>'. |
| 1089 | * |
| 1090 | * \param num_command_line_args The number of command-line arguments in |
| 1091 | * \p command_line_args. |
| 1092 | * |
| 1093 | * \param unsaved_files the files that have not yet been saved to disk |
Douglas Gregor | 1abc6bc | 2010-08-04 16:47:14 +0000 | [diff] [blame] | 1094 | * but may be required for parsing, including the contents of |
Douglas Gregor | 5a43021 | 2010-07-21 18:52:53 +0000 | [diff] [blame] | 1095 | * those files. The contents and name of these files (as specified by |
| 1096 | * CXUnsavedFile) are copied when necessary, so the client only needs to |
| 1097 | * guarantee their validity until the call to this function returns. |
| 1098 | * |
| 1099 | * \param num_unsaved_files the number of unsaved file entries in \p |
| 1100 | * unsaved_files. |
| 1101 | * |
| 1102 | * \param options A bitmask of options that affects how the translation unit |
| 1103 | * is managed but not its compilation. This should be a bitwise OR of the |
| 1104 | * CXTranslationUnit_XXX flags. |
| 1105 | * |
| 1106 | * \returns A new translation unit describing the parsed code and containing |
| 1107 | * any diagnostics produced by the compiler. If there is a failure from which |
| 1108 | * the compiler cannot recover, returns NULL. |
| 1109 | */ |
| 1110 | CINDEX_LINKAGE CXTranslationUnit clang_parseTranslationUnit(CXIndex CIdx, |
| 1111 | const char *source_filename, |
Douglas Gregor | 2ef6944 | 2010-09-01 16:43:19 +0000 | [diff] [blame] | 1112 | const char * const *command_line_args, |
Douglas Gregor | 5a43021 | 2010-07-21 18:52:53 +0000 | [diff] [blame] | 1113 | int num_command_line_args, |
| 1114 | struct CXUnsavedFile *unsaved_files, |
| 1115 | unsigned num_unsaved_files, |
| 1116 | unsigned options); |
| 1117 | |
Douglas Gregor | 5352ac0 | 2010-01-28 00:27:43 +0000 | [diff] [blame] | 1118 | /** |
Douglas Gregor | 1999844 | 2010-08-13 15:35:05 +0000 | [diff] [blame] | 1119 | * \brief Flags that control how translation units are saved. |
| 1120 | * |
| 1121 | * The enumerators in this enumeration type are meant to be bitwise |
| 1122 | * ORed together to specify which options should be used when |
| 1123 | * saving the translation unit. |
| 1124 | */ |
| 1125 | enum CXSaveTranslationUnit_Flags { |
| 1126 | /** |
| 1127 | * \brief Used to indicate that no special saving options are needed. |
| 1128 | */ |
| 1129 | CXSaveTranslationUnit_None = 0x0 |
| 1130 | }; |
| 1131 | |
| 1132 | /** |
| 1133 | * \brief Returns the set of flags that is suitable for saving a translation |
| 1134 | * unit. |
| 1135 | * |
| 1136 | * The set of flags returned provide options for |
| 1137 | * \c clang_saveTranslationUnit() by default. The returned flag |
| 1138 | * set contains an unspecified set of options that save translation units with |
| 1139 | * the most commonly-requested data. |
| 1140 | */ |
| 1141 | CINDEX_LINKAGE unsigned clang_defaultSaveOptions(CXTranslationUnit TU); |
| 1142 | |
| 1143 | /** |
Douglas Gregor | 39c411f | 2011-07-06 16:43:36 +0000 | [diff] [blame] | 1144 | * \brief Describes the kind of error that occurred (if any) in a call to |
| 1145 | * \c clang_saveTranslationUnit(). |
| 1146 | */ |
| 1147 | enum CXSaveError { |
| 1148 | /** |
| 1149 | * \brief Indicates that no error occurred while saving a translation unit. |
| 1150 | */ |
| 1151 | CXSaveError_None = 0, |
| 1152 | |
| 1153 | /** |
| 1154 | * \brief Indicates that an unknown error occurred while attempting to save |
| 1155 | * the file. |
| 1156 | * |
| 1157 | * This error typically indicates that file I/O failed when attempting to |
| 1158 | * write the file. |
| 1159 | */ |
| 1160 | CXSaveError_Unknown = 1, |
| 1161 | |
| 1162 | /** |
| 1163 | * \brief Indicates that errors during translation prevented this attempt |
| 1164 | * to save the translation unit. |
| 1165 | * |
| 1166 | * Errors that prevent the translation unit from being saved can be |
| 1167 | * extracted using \c clang_getNumDiagnostics() and \c clang_getDiagnostic(). |
| 1168 | */ |
| 1169 | CXSaveError_TranslationErrors = 2, |
| 1170 | |
| 1171 | /** |
| 1172 | * \brief Indicates that the translation unit to be saved was somehow |
| 1173 | * invalid (e.g., NULL). |
| 1174 | */ |
| 1175 | CXSaveError_InvalidTU = 3 |
| 1176 | }; |
| 1177 | |
| 1178 | /** |
Douglas Gregor | 7ae2faa | 2010-08-13 05:36:37 +0000 | [diff] [blame] | 1179 | * \brief Saves a translation unit into a serialized representation of |
| 1180 | * that translation unit on disk. |
| 1181 | * |
| 1182 | * Any translation unit that was parsed without error can be saved |
| 1183 | * into a file. The translation unit can then be deserialized into a |
| 1184 | * new \c CXTranslationUnit with \c clang_createTranslationUnit() or, |
| 1185 | * if it is an incomplete translation unit that corresponds to a |
| 1186 | * header, used as a precompiled header when parsing other translation |
| 1187 | * units. |
| 1188 | * |
| 1189 | * \param TU The translation unit to save. |
Douglas Gregor | 1999844 | 2010-08-13 15:35:05 +0000 | [diff] [blame] | 1190 | * |
Douglas Gregor | 7ae2faa | 2010-08-13 05:36:37 +0000 | [diff] [blame] | 1191 | * \param FileName The file to which the translation unit will be saved. |
| 1192 | * |
Douglas Gregor | 1999844 | 2010-08-13 15:35:05 +0000 | [diff] [blame] | 1193 | * \param options A bitmask of options that affects how the translation unit |
| 1194 | * is saved. This should be a bitwise OR of the |
| 1195 | * CXSaveTranslationUnit_XXX flags. |
| 1196 | * |
Douglas Gregor | 39c411f | 2011-07-06 16:43:36 +0000 | [diff] [blame] | 1197 | * \returns A value that will match one of the enumerators of the CXSaveError |
| 1198 | * enumeration. Zero (CXSaveError_None) indicates that the translation unit was |
| 1199 | * saved successfully, while a non-zero value indicates that a problem occurred. |
Douglas Gregor | 7ae2faa | 2010-08-13 05:36:37 +0000 | [diff] [blame] | 1200 | */ |
| 1201 | CINDEX_LINKAGE int clang_saveTranslationUnit(CXTranslationUnit TU, |
Douglas Gregor | 1999844 | 2010-08-13 15:35:05 +0000 | [diff] [blame] | 1202 | const char *FileName, |
| 1203 | unsigned options); |
Douglas Gregor | 7ae2faa | 2010-08-13 05:36:37 +0000 | [diff] [blame] | 1204 | |
| 1205 | /** |
Douglas Gregor | 5352ac0 | 2010-01-28 00:27:43 +0000 | [diff] [blame] | 1206 | * \brief Destroy the specified CXTranslationUnit object. |
| 1207 | */ |
| 1208 | CINDEX_LINKAGE void clang_disposeTranslationUnit(CXTranslationUnit); |
Ted Kremenek | 896b70f | 2010-03-13 02:50:34 +0000 | [diff] [blame] | 1209 | |
Douglas Gregor | 5352ac0 | 2010-01-28 00:27:43 +0000 | [diff] [blame] | 1210 | /** |
Douglas Gregor | e1e13bf | 2010-08-11 15:58:42 +0000 | [diff] [blame] | 1211 | * \brief Flags that control the reparsing of translation units. |
| 1212 | * |
| 1213 | * The enumerators in this enumeration type are meant to be bitwise |
| 1214 | * ORed together to specify which options should be used when |
| 1215 | * reparsing the translation unit. |
| 1216 | */ |
| 1217 | enum CXReparse_Flags { |
| 1218 | /** |
| 1219 | * \brief Used to indicate that no special reparsing options are needed. |
| 1220 | */ |
| 1221 | CXReparse_None = 0x0 |
| 1222 | }; |
| 1223 | |
| 1224 | /** |
| 1225 | * \brief Returns the set of flags that is suitable for reparsing a translation |
| 1226 | * unit. |
| 1227 | * |
| 1228 | * The set of flags returned provide options for |
| 1229 | * \c clang_reparseTranslationUnit() by default. The returned flag |
| 1230 | * set contains an unspecified set of optimizations geared toward common uses |
| 1231 | * of reparsing. The set of optimizations enabled may change from one version |
| 1232 | * to the next. |
| 1233 | */ |
| 1234 | CINDEX_LINKAGE unsigned clang_defaultReparseOptions(CXTranslationUnit TU); |
| 1235 | |
| 1236 | /** |
Douglas Gregor | abc563f | 2010-07-19 21:46:24 +0000 | [diff] [blame] | 1237 | * \brief Reparse the source files that produced this translation unit. |
| 1238 | * |
| 1239 | * This routine can be used to re-parse the source files that originally |
| 1240 | * created the given translation unit, for example because those source files |
| 1241 | * have changed (either on disk or as passed via \p unsaved_files). The |
| 1242 | * source code will be reparsed with the same command-line options as it |
| 1243 | * was originally parsed. |
| 1244 | * |
| 1245 | * Reparsing a translation unit invalidates all cursors and source locations |
| 1246 | * that refer into that translation unit. This makes reparsing a translation |
| 1247 | * unit semantically equivalent to destroying the translation unit and then |
| 1248 | * creating a new translation unit with the same command-line arguments. |
| 1249 | * However, it may be more efficient to reparse a translation |
| 1250 | * unit using this routine. |
| 1251 | * |
| 1252 | * \param TU The translation unit whose contents will be re-parsed. The |
| 1253 | * translation unit must originally have been built with |
| 1254 | * \c clang_createTranslationUnitFromSourceFile(). |
| 1255 | * |
| 1256 | * \param num_unsaved_files The number of unsaved file entries in \p |
| 1257 | * unsaved_files. |
| 1258 | * |
| 1259 | * \param unsaved_files The files that have not yet been saved to disk |
| 1260 | * but may be required for parsing, including the contents of |
| 1261 | * those files. The contents and name of these files (as specified by |
| 1262 | * CXUnsavedFile) are copied when necessary, so the client only needs to |
| 1263 | * guarantee their validity until the call to this function returns. |
| 1264 | * |
Douglas Gregor | e1e13bf | 2010-08-11 15:58:42 +0000 | [diff] [blame] | 1265 | * \param options A bitset of options composed of the flags in CXReparse_Flags. |
| 1266 | * The function \c clang_defaultReparseOptions() produces a default set of |
| 1267 | * options recommended for most uses, based on the translation unit. |
| 1268 | * |
Douglas Gregor | abc563f | 2010-07-19 21:46:24 +0000 | [diff] [blame] | 1269 | * \returns 0 if the sources could be reparsed. A non-zero value will be |
| 1270 | * returned if reparsing was impossible, such that the translation unit is |
| 1271 | * invalid. In such cases, the only valid call for \p TU is |
| 1272 | * \c clang_disposeTranslationUnit(TU). |
| 1273 | */ |
| 1274 | CINDEX_LINKAGE int clang_reparseTranslationUnit(CXTranslationUnit TU, |
| 1275 | unsigned num_unsaved_files, |
Douglas Gregor | e1e13bf | 2010-08-11 15:58:42 +0000 | [diff] [blame] | 1276 | struct CXUnsavedFile *unsaved_files, |
| 1277 | unsigned options); |
Ted Kremenek | 59fc1e5 | 2011-04-18 22:47:10 +0000 | [diff] [blame] | 1278 | |
| 1279 | /** |
| 1280 | * \brief Categorizes how memory is being used by a translation unit. |
| 1281 | */ |
Ted Kremenek | f787002 | 2011-04-20 16:41:07 +0000 | [diff] [blame] | 1282 | enum CXTUResourceUsageKind { |
| 1283 | CXTUResourceUsage_AST = 1, |
| 1284 | CXTUResourceUsage_Identifiers = 2, |
| 1285 | CXTUResourceUsage_Selectors = 3, |
| 1286 | CXTUResourceUsage_GlobalCompletionResults = 4, |
Ted Kremenek | 457aaf0 | 2011-04-28 04:10:31 +0000 | [diff] [blame] | 1287 | CXTUResourceUsage_SourceManagerContentCache = 5, |
Ted Kremenek | ba29bd2 | 2011-04-28 04:53:38 +0000 | [diff] [blame] | 1288 | CXTUResourceUsage_AST_SideTables = 6, |
Ted Kremenek | f61b831 | 2011-04-28 20:36:42 +0000 | [diff] [blame] | 1289 | CXTUResourceUsage_SourceManager_Membuffer_Malloc = 7, |
Ted Kremenek | e9b5f3d | 2011-04-28 23:46:20 +0000 | [diff] [blame] | 1290 | CXTUResourceUsage_SourceManager_Membuffer_MMap = 8, |
| 1291 | CXTUResourceUsage_ExternalASTSource_Membuffer_Malloc = 9, |
| 1292 | CXTUResourceUsage_ExternalASTSource_Membuffer_MMap = 10, |
Ted Kremenek | 5e1db6a | 2011-05-04 01:38:46 +0000 | [diff] [blame] | 1293 | CXTUResourceUsage_Preprocessor = 11, |
| 1294 | CXTUResourceUsage_PreprocessingRecord = 12, |
Ted Kremenek | ca7dc2b | 2011-07-26 23:46:06 +0000 | [diff] [blame] | 1295 | CXTUResourceUsage_SourceManager_DataStructures = 13, |
Ted Kremenek | d1194fb | 2011-07-26 23:46:11 +0000 | [diff] [blame] | 1296 | CXTUResourceUsage_Preprocessor_HeaderSearch = 14, |
Ted Kremenek | f787002 | 2011-04-20 16:41:07 +0000 | [diff] [blame] | 1297 | CXTUResourceUsage_MEMORY_IN_BYTES_BEGIN = CXTUResourceUsage_AST, |
| 1298 | CXTUResourceUsage_MEMORY_IN_BYTES_END = |
Ted Kremenek | d1194fb | 2011-07-26 23:46:11 +0000 | [diff] [blame] | 1299 | CXTUResourceUsage_Preprocessor_HeaderSearch, |
Ted Kremenek | f787002 | 2011-04-20 16:41:07 +0000 | [diff] [blame] | 1300 | |
| 1301 | CXTUResourceUsage_First = CXTUResourceUsage_AST, |
Ted Kremenek | d1194fb | 2011-07-26 23:46:11 +0000 | [diff] [blame] | 1302 | CXTUResourceUsage_Last = CXTUResourceUsage_Preprocessor_HeaderSearch |
Ted Kremenek | 59fc1e5 | 2011-04-18 22:47:10 +0000 | [diff] [blame] | 1303 | }; |
| 1304 | |
| 1305 | /** |
| 1306 | * \brief Returns the human-readable null-terminated C string that represents |
Ted Kremenek | f787002 | 2011-04-20 16:41:07 +0000 | [diff] [blame] | 1307 | * the name of the memory category. This string should never be freed. |
Ted Kremenek | 59fc1e5 | 2011-04-18 22:47:10 +0000 | [diff] [blame] | 1308 | */ |
| 1309 | CINDEX_LINKAGE |
Ted Kremenek | f787002 | 2011-04-20 16:41:07 +0000 | [diff] [blame] | 1310 | const char *clang_getTUResourceUsageName(enum CXTUResourceUsageKind kind); |
Ted Kremenek | 59fc1e5 | 2011-04-18 22:47:10 +0000 | [diff] [blame] | 1311 | |
Ted Kremenek | f787002 | 2011-04-20 16:41:07 +0000 | [diff] [blame] | 1312 | typedef struct CXTUResourceUsageEntry { |
Ted Kremenek | 59fc1e5 | 2011-04-18 22:47:10 +0000 | [diff] [blame] | 1313 | /* \brief The memory usage category. */ |
Ted Kremenek | f787002 | 2011-04-20 16:41:07 +0000 | [diff] [blame] | 1314 | enum CXTUResourceUsageKind kind; |
| 1315 | /* \brief Amount of resources used. |
| 1316 | The units will depend on the resource kind. */ |
Ted Kremenek | 59fc1e5 | 2011-04-18 22:47:10 +0000 | [diff] [blame] | 1317 | unsigned long amount; |
Ted Kremenek | f787002 | 2011-04-20 16:41:07 +0000 | [diff] [blame] | 1318 | } CXTUResourceUsageEntry; |
Ted Kremenek | 59fc1e5 | 2011-04-18 22:47:10 +0000 | [diff] [blame] | 1319 | |
| 1320 | /** |
| 1321 | * \brief The memory usage of a CXTranslationUnit, broken into categories. |
| 1322 | */ |
Ted Kremenek | f787002 | 2011-04-20 16:41:07 +0000 | [diff] [blame] | 1323 | typedef struct CXTUResourceUsage { |
Ted Kremenek | 59fc1e5 | 2011-04-18 22:47:10 +0000 | [diff] [blame] | 1324 | /* \brief Private data member, used for queries. */ |
| 1325 | void *data; |
| 1326 | |
| 1327 | /* \brief The number of entries in the 'entries' array. */ |
| 1328 | unsigned numEntries; |
| 1329 | |
| 1330 | /* \brief An array of key-value pairs, representing the breakdown of memory |
| 1331 | usage. */ |
Ted Kremenek | f787002 | 2011-04-20 16:41:07 +0000 | [diff] [blame] | 1332 | CXTUResourceUsageEntry *entries; |
Ted Kremenek | 59fc1e5 | 2011-04-18 22:47:10 +0000 | [diff] [blame] | 1333 | |
Ted Kremenek | f787002 | 2011-04-20 16:41:07 +0000 | [diff] [blame] | 1334 | } CXTUResourceUsage; |
Ted Kremenek | 59fc1e5 | 2011-04-18 22:47:10 +0000 | [diff] [blame] | 1335 | |
| 1336 | /** |
| 1337 | * \brief Return the memory usage of a translation unit. This object |
Ted Kremenek | f787002 | 2011-04-20 16:41:07 +0000 | [diff] [blame] | 1338 | * should be released with clang_disposeCXTUResourceUsage(). |
Ted Kremenek | 59fc1e5 | 2011-04-18 22:47:10 +0000 | [diff] [blame] | 1339 | */ |
Ted Kremenek | f787002 | 2011-04-20 16:41:07 +0000 | [diff] [blame] | 1340 | CINDEX_LINKAGE CXTUResourceUsage clang_getCXTUResourceUsage(CXTranslationUnit TU); |
Ted Kremenek | 59fc1e5 | 2011-04-18 22:47:10 +0000 | [diff] [blame] | 1341 | |
Ted Kremenek | f787002 | 2011-04-20 16:41:07 +0000 | [diff] [blame] | 1342 | CINDEX_LINKAGE void clang_disposeCXTUResourceUsage(CXTUResourceUsage usage); |
Ted Kremenek | 59fc1e5 | 2011-04-18 22:47:10 +0000 | [diff] [blame] | 1343 | |
Douglas Gregor | abc563f | 2010-07-19 21:46:24 +0000 | [diff] [blame] | 1344 | /** |
Douglas Gregor | 5352ac0 | 2010-01-28 00:27:43 +0000 | [diff] [blame] | 1345 | * @} |
| 1346 | */ |
Ted Kremenek | 896b70f | 2010-03-13 02:50:34 +0000 | [diff] [blame] | 1347 | |
Douglas Gregor | 5352ac0 | 2010-01-28 00:27:43 +0000 | [diff] [blame] | 1348 | /** |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 1349 | * \brief Describes the kind of entity that a cursor refers to. |
| 1350 | */ |
| 1351 | enum CXCursorKind { |
| 1352 | /* Declarations */ |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 1353 | /** |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 1354 | * \brief A declaration whose specific kind is not exposed via this |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 1355 | * interface. |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 1356 | * |
| 1357 | * Unexposed declarations have the same operations as any other kind |
| 1358 | * of declaration; one can extract their location information, |
| 1359 | * spelling, find their definitions, etc. However, the specific kind |
| 1360 | * of the declaration is not reported. |
| 1361 | */ |
| 1362 | CXCursor_UnexposedDecl = 1, |
| 1363 | /** \brief A C or C++ struct. */ |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 1364 | CXCursor_StructDecl = 2, |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 1365 | /** \brief A C or C++ union. */ |
| 1366 | CXCursor_UnionDecl = 3, |
| 1367 | /** \brief A C++ class. */ |
| 1368 | CXCursor_ClassDecl = 4, |
| 1369 | /** \brief An enumeration. */ |
| 1370 | CXCursor_EnumDecl = 5, |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 1371 | /** |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 1372 | * \brief A field (in C) or non-static data member (in C++) in a |
| 1373 | * struct, union, or C++ class. |
| 1374 | */ |
| 1375 | CXCursor_FieldDecl = 6, |
| 1376 | /** \brief An enumerator constant. */ |
| 1377 | CXCursor_EnumConstantDecl = 7, |
| 1378 | /** \brief A function. */ |
| 1379 | CXCursor_FunctionDecl = 8, |
| 1380 | /** \brief A variable. */ |
| 1381 | CXCursor_VarDecl = 9, |
| 1382 | /** \brief A function or method parameter. */ |
| 1383 | CXCursor_ParmDecl = 10, |
| 1384 | /** \brief An Objective-C @interface. */ |
| 1385 | CXCursor_ObjCInterfaceDecl = 11, |
| 1386 | /** \brief An Objective-C @interface for a category. */ |
| 1387 | CXCursor_ObjCCategoryDecl = 12, |
| 1388 | /** \brief An Objective-C @protocol declaration. */ |
| 1389 | CXCursor_ObjCProtocolDecl = 13, |
| 1390 | /** \brief An Objective-C @property declaration. */ |
| 1391 | CXCursor_ObjCPropertyDecl = 14, |
| 1392 | /** \brief An Objective-C instance variable. */ |
| 1393 | CXCursor_ObjCIvarDecl = 15, |
| 1394 | /** \brief An Objective-C instance method. */ |
| 1395 | CXCursor_ObjCInstanceMethodDecl = 16, |
| 1396 | /** \brief An Objective-C class method. */ |
| 1397 | CXCursor_ObjCClassMethodDecl = 17, |
| 1398 | /** \brief An Objective-C @implementation. */ |
| 1399 | CXCursor_ObjCImplementationDecl = 18, |
| 1400 | /** \brief An Objective-C @implementation for a category. */ |
| 1401 | CXCursor_ObjCCategoryImplDecl = 19, |
| 1402 | /** \brief A typedef */ |
| 1403 | CXCursor_TypedefDecl = 20, |
Ted Kremenek | 8bd5a69 | 2010-04-13 23:39:06 +0000 | [diff] [blame] | 1404 | /** \brief A C++ class method. */ |
| 1405 | CXCursor_CXXMethod = 21, |
Ted Kremenek | 8f06e0e | 2010-05-06 23:38:21 +0000 | [diff] [blame] | 1406 | /** \brief A C++ namespace. */ |
| 1407 | CXCursor_Namespace = 22, |
Ted Kremenek | a0536d8 | 2010-05-07 01:04:29 +0000 | [diff] [blame] | 1408 | /** \brief A linkage specification, e.g. 'extern "C"'. */ |
| 1409 | CXCursor_LinkageSpec = 23, |
Douglas Gregor | 01829d3 | 2010-08-31 14:41:23 +0000 | [diff] [blame] | 1410 | /** \brief A C++ constructor. */ |
| 1411 | CXCursor_Constructor = 24, |
| 1412 | /** \brief A C++ destructor. */ |
| 1413 | CXCursor_Destructor = 25, |
| 1414 | /** \brief A C++ conversion function. */ |
| 1415 | CXCursor_ConversionFunction = 26, |
Douglas Gregor | fe72e9c | 2010-08-31 17:01:39 +0000 | [diff] [blame] | 1416 | /** \brief A C++ template type parameter. */ |
| 1417 | CXCursor_TemplateTypeParameter = 27, |
| 1418 | /** \brief A C++ non-type template parameter. */ |
| 1419 | CXCursor_NonTypeTemplateParameter = 28, |
| 1420 | /** \brief A C++ template template parameter. */ |
| 1421 | CXCursor_TemplateTemplateParameter = 29, |
| 1422 | /** \brief A C++ function template. */ |
| 1423 | CXCursor_FunctionTemplate = 30, |
Douglas Gregor | 39d6f07 | 2010-08-31 19:02:00 +0000 | [diff] [blame] | 1424 | /** \brief A C++ class template. */ |
| 1425 | CXCursor_ClassTemplate = 31, |
Douglas Gregor | 74dbe64 | 2010-08-31 19:31:58 +0000 | [diff] [blame] | 1426 | /** \brief A C++ class template partial specialization. */ |
| 1427 | CXCursor_ClassTemplatePartialSpecialization = 32, |
Douglas Gregor | 6931900 | 2010-08-31 23:48:11 +0000 | [diff] [blame] | 1428 | /** \brief A C++ namespace alias declaration. */ |
| 1429 | CXCursor_NamespaceAlias = 33, |
Douglas Gregor | 0a35bce | 2010-09-01 03:07:18 +0000 | [diff] [blame] | 1430 | /** \brief A C++ using directive. */ |
| 1431 | CXCursor_UsingDirective = 34, |
Richard Smith | 162e1c1 | 2011-04-15 14:24:37 +0000 | [diff] [blame] | 1432 | /** \brief A C++ using declaration. */ |
Douglas Gregor | 7e24256 | 2010-09-01 19:52:22 +0000 | [diff] [blame] | 1433 | CXCursor_UsingDeclaration = 35, |
Richard Smith | 162e1c1 | 2011-04-15 14:24:37 +0000 | [diff] [blame] | 1434 | /** \brief A C++ alias declaration */ |
| 1435 | CXCursor_TypeAliasDecl = 36, |
Douglas Gregor | 352697a | 2011-06-03 23:08:58 +0000 | [diff] [blame] | 1436 | /** \brief An Objective-C @synthesize definition. */ |
| 1437 | CXCursor_ObjCSynthesizeDecl = 37, |
| 1438 | /** \brief An Objective-C @dynamic definition. */ |
| 1439 | CXCursor_ObjCDynamicDecl = 38, |
Argyrios Kyrtzidis | 2dfdb94 | 2011-09-30 17:58:23 +0000 | [diff] [blame] | 1440 | /** \brief An access specifier. */ |
| 1441 | CXCursor_CXXAccessSpecifier = 39, |
Douglas Gregor | 42b2984 | 2011-10-05 19:00:14 +0000 | [diff] [blame] | 1442 | |
Ted Kremenek | 50aa6ac | 2010-05-19 21:51:10 +0000 | [diff] [blame] | 1443 | CXCursor_FirstDecl = CXCursor_UnexposedDecl, |
Argyrios Kyrtzidis | 2dfdb94 | 2011-09-30 17:58:23 +0000 | [diff] [blame] | 1444 | CXCursor_LastDecl = CXCursor_CXXAccessSpecifier, |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 1445 | |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 1446 | /* References */ |
| 1447 | CXCursor_FirstRef = 40, /* Decl references */ |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 1448 | CXCursor_ObjCSuperClassRef = 40, |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 1449 | CXCursor_ObjCProtocolRef = 41, |
| 1450 | CXCursor_ObjCClassRef = 42, |
| 1451 | /** |
| 1452 | * \brief A reference to a type declaration. |
| 1453 | * |
| 1454 | * A type reference occurs anywhere where a type is named but not |
| 1455 | * declared. For example, given: |
| 1456 | * |
| 1457 | * \code |
| 1458 | * typedef unsigned size_type; |
| 1459 | * size_type size; |
| 1460 | * \endcode |
| 1461 | * |
| 1462 | * The typedef is a declaration of size_type (CXCursor_TypedefDecl), |
| 1463 | * while the type of the variable "size" is referenced. The cursor |
| 1464 | * referenced by the type of size is the typedef for size_type. |
| 1465 | */ |
| 1466 | CXCursor_TypeRef = 43, |
Ted Kremenek | 3064ef9 | 2010-08-27 21:34:58 +0000 | [diff] [blame] | 1467 | CXCursor_CXXBaseSpecifier = 44, |
Douglas Gregor | 0b36e61 | 2010-08-31 20:37:03 +0000 | [diff] [blame] | 1468 | /** |
Douglas Gregor | a67e03f | 2010-09-09 21:42:20 +0000 | [diff] [blame] | 1469 | * \brief A reference to a class template, function template, template |
| 1470 | * template parameter, or class template partial specialization. |
Douglas Gregor | 0b36e61 | 2010-08-31 20:37:03 +0000 | [diff] [blame] | 1471 | */ |
| 1472 | CXCursor_TemplateRef = 45, |
Douglas Gregor | 6931900 | 2010-08-31 23:48:11 +0000 | [diff] [blame] | 1473 | /** |
| 1474 | * \brief A reference to a namespace or namespace alias. |
| 1475 | */ |
| 1476 | CXCursor_NamespaceRef = 46, |
Douglas Gregor | a67e03f | 2010-09-09 21:42:20 +0000 | [diff] [blame] | 1477 | /** |
Douglas Gregor | 36897b0 | 2010-09-10 00:22:18 +0000 | [diff] [blame] | 1478 | * \brief A reference to a member of a struct, union, or class that occurs in |
| 1479 | * some non-expression context, e.g., a designated initializer. |
Douglas Gregor | a67e03f | 2010-09-09 21:42:20 +0000 | [diff] [blame] | 1480 | */ |
| 1481 | CXCursor_MemberRef = 47, |
Douglas Gregor | 36897b0 | 2010-09-10 00:22:18 +0000 | [diff] [blame] | 1482 | /** |
| 1483 | * \brief A reference to a labeled statement. |
| 1484 | * |
| 1485 | * This cursor kind is used to describe the jump to "start_over" in the |
| 1486 | * goto statement in the following example: |
| 1487 | * |
| 1488 | * \code |
| 1489 | * start_over: |
| 1490 | * ++counter; |
| 1491 | * |
| 1492 | * goto start_over; |
| 1493 | * \endcode |
| 1494 | * |
| 1495 | * A label reference cursor refers to a label statement. |
| 1496 | */ |
| 1497 | CXCursor_LabelRef = 48, |
| 1498 | |
Douglas Gregor | 1f60d9e | 2010-09-13 22:52:57 +0000 | [diff] [blame] | 1499 | /** |
| 1500 | * \brief A reference to a set of overloaded functions or function templates |
| 1501 | * that has not yet been resolved to a specific function or function template. |
| 1502 | * |
| 1503 | * An overloaded declaration reference cursor occurs in C++ templates where |
| 1504 | * a dependent name refers to a function. For example: |
| 1505 | * |
| 1506 | * \code |
| 1507 | * template<typename T> void swap(T&, T&); |
| 1508 | * |
| 1509 | * struct X { ... }; |
| 1510 | * void swap(X&, X&); |
| 1511 | * |
| 1512 | * template<typename T> |
| 1513 | * void reverse(T* first, T* last) { |
| 1514 | * while (first < last - 1) { |
| 1515 | * swap(*first, *--last); |
| 1516 | * ++first; |
| 1517 | * } |
| 1518 | * } |
| 1519 | * |
| 1520 | * struct Y { }; |
| 1521 | * void swap(Y&, Y&); |
| 1522 | * \endcode |
| 1523 | * |
| 1524 | * Here, the identifier "swap" is associated with an overloaded declaration |
| 1525 | * reference. In the template definition, "swap" refers to either of the two |
| 1526 | * "swap" functions declared above, so both results will be available. At |
| 1527 | * instantiation time, "swap" may also refer to other functions found via |
| 1528 | * argument-dependent lookup (e.g., the "swap" function at the end of the |
| 1529 | * example). |
| 1530 | * |
| 1531 | * The functions \c clang_getNumOverloadedDecls() and |
| 1532 | * \c clang_getOverloadedDecl() can be used to retrieve the definitions |
| 1533 | * referenced by this cursor. |
| 1534 | */ |
| 1535 | CXCursor_OverloadedDeclRef = 49, |
| 1536 | |
Douglas Gregor | 011d8b9 | 2012-02-15 00:54:55 +0000 | [diff] [blame] | 1537 | /** |
| 1538 | * \brief A reference to a variable that occurs in some non-expression |
| 1539 | * context, e.g., a C++ lambda capture list. |
| 1540 | */ |
| 1541 | CXCursor_VariableRef = 50, |
| 1542 | |
| 1543 | CXCursor_LastRef = CXCursor_VariableRef, |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 1544 | |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 1545 | /* Error conditions */ |
| 1546 | CXCursor_FirstInvalid = 70, |
| 1547 | CXCursor_InvalidFile = 70, |
| 1548 | CXCursor_NoDeclFound = 71, |
| 1549 | CXCursor_NotImplemented = 72, |
Ted Kremenek | ebfa339 | 2010-03-19 20:39:03 +0000 | [diff] [blame] | 1550 | CXCursor_InvalidCode = 73, |
| 1551 | CXCursor_LastInvalid = CXCursor_InvalidCode, |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 1552 | |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 1553 | /* Expressions */ |
| 1554 | CXCursor_FirstExpr = 100, |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 1555 | |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 1556 | /** |
| 1557 | * \brief An expression whose specific kind is not exposed via this |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 1558 | * interface. |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 1559 | * |
| 1560 | * Unexposed expressions have the same operations as any other kind |
| 1561 | * of expression; one can extract their location information, |
| 1562 | * spelling, children, etc. However, the specific kind of the |
| 1563 | * expression is not reported. |
| 1564 | */ |
| 1565 | CXCursor_UnexposedExpr = 100, |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 1566 | |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 1567 | /** |
| 1568 | * \brief An expression that refers to some value declaration, such |
| 1569 | * as a function, varible, or enumerator. |
| 1570 | */ |
| 1571 | CXCursor_DeclRefExpr = 101, |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 1572 | |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 1573 | /** |
| 1574 | * \brief An expression that refers to a member of a struct, union, |
| 1575 | * class, Objective-C class, etc. |
| 1576 | */ |
| 1577 | CXCursor_MemberRefExpr = 102, |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 1578 | |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 1579 | /** \brief An expression that calls a function. */ |
| 1580 | CXCursor_CallExpr = 103, |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 1581 | |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 1582 | /** \brief An expression that sends a message to an Objective-C |
| 1583 | object or class. */ |
| 1584 | CXCursor_ObjCMessageExpr = 104, |
Ted Kremenek | 1ee6cad | 2010-04-11 21:47:37 +0000 | [diff] [blame] | 1585 | |
| 1586 | /** \brief An expression that represents a block literal. */ |
| 1587 | CXCursor_BlockExpr = 105, |
| 1588 | |
Douglas Gregor | 42b2984 | 2011-10-05 19:00:14 +0000 | [diff] [blame] | 1589 | /** \brief An integer literal. |
| 1590 | */ |
| 1591 | CXCursor_IntegerLiteral = 106, |
| 1592 | |
| 1593 | /** \brief A floating point number literal. |
| 1594 | */ |
| 1595 | CXCursor_FloatingLiteral = 107, |
| 1596 | |
| 1597 | /** \brief An imaginary number literal. |
| 1598 | */ |
| 1599 | CXCursor_ImaginaryLiteral = 108, |
| 1600 | |
| 1601 | /** \brief A string literal. |
| 1602 | */ |
| 1603 | CXCursor_StringLiteral = 109, |
| 1604 | |
| 1605 | /** \brief A character literal. |
| 1606 | */ |
| 1607 | CXCursor_CharacterLiteral = 110, |
| 1608 | |
| 1609 | /** \brief A parenthesized expression, e.g. "(1)". |
| 1610 | * |
| 1611 | * This AST node is only formed if full location information is requested. |
| 1612 | */ |
| 1613 | CXCursor_ParenExpr = 111, |
| 1614 | |
| 1615 | /** \brief This represents the unary-expression's (except sizeof and |
| 1616 | * alignof). |
| 1617 | */ |
| 1618 | CXCursor_UnaryOperator = 112, |
| 1619 | |
| 1620 | /** \brief [C99 6.5.2.1] Array Subscripting. |
| 1621 | */ |
| 1622 | CXCursor_ArraySubscriptExpr = 113, |
| 1623 | |
| 1624 | /** \brief A builtin binary operation expression such as "x + y" or |
| 1625 | * "x <= y". |
| 1626 | */ |
| 1627 | CXCursor_BinaryOperator = 114, |
| 1628 | |
| 1629 | /** \brief Compound assignment such as "+=". |
| 1630 | */ |
| 1631 | CXCursor_CompoundAssignOperator = 115, |
| 1632 | |
| 1633 | /** \brief The ?: ternary operator. |
| 1634 | */ |
| 1635 | CXCursor_ConditionalOperator = 116, |
| 1636 | |
| 1637 | /** \brief An explicit cast in C (C99 6.5.4) or a C-style cast in C++ |
| 1638 | * (C++ [expr.cast]), which uses the syntax (Type)expr. |
| 1639 | * |
| 1640 | * For example: (int)f. |
| 1641 | */ |
| 1642 | CXCursor_CStyleCastExpr = 117, |
| 1643 | |
| 1644 | /** \brief [C99 6.5.2.5] |
| 1645 | */ |
| 1646 | CXCursor_CompoundLiteralExpr = 118, |
| 1647 | |
| 1648 | /** \brief Describes an C or C++ initializer list. |
| 1649 | */ |
| 1650 | CXCursor_InitListExpr = 119, |
| 1651 | |
| 1652 | /** \brief The GNU address of label extension, representing &&label. |
| 1653 | */ |
| 1654 | CXCursor_AddrLabelExpr = 120, |
| 1655 | |
| 1656 | /** \brief This is the GNU Statement Expression extension: ({int X=4; X;}) |
| 1657 | */ |
| 1658 | CXCursor_StmtExpr = 121, |
| 1659 | |
Benjamin Kramer | ffbe9b9 | 2011-12-23 17:00:35 +0000 | [diff] [blame] | 1660 | /** \brief Represents a C11 generic selection. |
Douglas Gregor | 42b2984 | 2011-10-05 19:00:14 +0000 | [diff] [blame] | 1661 | */ |
| 1662 | CXCursor_GenericSelectionExpr = 122, |
| 1663 | |
| 1664 | /** \brief Implements the GNU __null extension, which is a name for a null |
| 1665 | * pointer constant that has integral type (e.g., int or long) and is the same |
| 1666 | * size and alignment as a pointer. |
| 1667 | * |
| 1668 | * The __null extension is typically only used by system headers, which define |
| 1669 | * NULL as __null in C++ rather than using 0 (which is an integer that may not |
| 1670 | * match the size of a pointer). |
| 1671 | */ |
| 1672 | CXCursor_GNUNullExpr = 123, |
| 1673 | |
| 1674 | /** \brief C++'s static_cast<> expression. |
| 1675 | */ |
| 1676 | CXCursor_CXXStaticCastExpr = 124, |
| 1677 | |
| 1678 | /** \brief C++'s dynamic_cast<> expression. |
| 1679 | */ |
| 1680 | CXCursor_CXXDynamicCastExpr = 125, |
| 1681 | |
| 1682 | /** \brief C++'s reinterpret_cast<> expression. |
| 1683 | */ |
| 1684 | CXCursor_CXXReinterpretCastExpr = 126, |
| 1685 | |
| 1686 | /** \brief C++'s const_cast<> expression. |
| 1687 | */ |
| 1688 | CXCursor_CXXConstCastExpr = 127, |
| 1689 | |
| 1690 | /** \brief Represents an explicit C++ type conversion that uses "functional" |
| 1691 | * notion (C++ [expr.type.conv]). |
| 1692 | * |
| 1693 | * Example: |
| 1694 | * \code |
| 1695 | * x = int(0.5); |
| 1696 | * \endcode |
| 1697 | */ |
| 1698 | CXCursor_CXXFunctionalCastExpr = 128, |
| 1699 | |
| 1700 | /** \brief A C++ typeid expression (C++ [expr.typeid]). |
| 1701 | */ |
| 1702 | CXCursor_CXXTypeidExpr = 129, |
| 1703 | |
| 1704 | /** \brief [C++ 2.13.5] C++ Boolean Literal. |
| 1705 | */ |
| 1706 | CXCursor_CXXBoolLiteralExpr = 130, |
| 1707 | |
| 1708 | /** \brief [C++0x 2.14.7] C++ Pointer Literal. |
| 1709 | */ |
| 1710 | CXCursor_CXXNullPtrLiteralExpr = 131, |
| 1711 | |
| 1712 | /** \brief Represents the "this" expression in C++ |
| 1713 | */ |
| 1714 | CXCursor_CXXThisExpr = 132, |
| 1715 | |
| 1716 | /** \brief [C++ 15] C++ Throw Expression. |
| 1717 | * |
| 1718 | * This handles 'throw' and 'throw' assignment-expression. When |
| 1719 | * assignment-expression isn't present, Op will be null. |
| 1720 | */ |
| 1721 | CXCursor_CXXThrowExpr = 133, |
| 1722 | |
| 1723 | /** \brief A new expression for memory allocation and constructor calls, e.g: |
| 1724 | * "new CXXNewExpr(foo)". |
| 1725 | */ |
| 1726 | CXCursor_CXXNewExpr = 134, |
| 1727 | |
| 1728 | /** \brief A delete expression for memory deallocation and destructor calls, |
| 1729 | * e.g. "delete[] pArray". |
| 1730 | */ |
| 1731 | CXCursor_CXXDeleteExpr = 135, |
| 1732 | |
| 1733 | /** \brief A unary expression. |
| 1734 | */ |
| 1735 | CXCursor_UnaryExpr = 136, |
| 1736 | |
Douglas Gregor | 9793e8f | 2011-11-11 22:35:18 +0000 | [diff] [blame] | 1737 | /** \brief An Objective-C string literal i.e. @"foo". |
Douglas Gregor | 42b2984 | 2011-10-05 19:00:14 +0000 | [diff] [blame] | 1738 | */ |
| 1739 | CXCursor_ObjCStringLiteral = 137, |
| 1740 | |
Douglas Gregor | 9793e8f | 2011-11-11 22:35:18 +0000 | [diff] [blame] | 1741 | /** \brief An Objective-C @encode expression. |
Douglas Gregor | 42b2984 | 2011-10-05 19:00:14 +0000 | [diff] [blame] | 1742 | */ |
| 1743 | CXCursor_ObjCEncodeExpr = 138, |
| 1744 | |
Douglas Gregor | 9793e8f | 2011-11-11 22:35:18 +0000 | [diff] [blame] | 1745 | /** \brief An Objective-C @selector expression. |
Douglas Gregor | 42b2984 | 2011-10-05 19:00:14 +0000 | [diff] [blame] | 1746 | */ |
| 1747 | CXCursor_ObjCSelectorExpr = 139, |
| 1748 | |
Douglas Gregor | 9793e8f | 2011-11-11 22:35:18 +0000 | [diff] [blame] | 1749 | /** \brief An Objective-C @protocol expression. |
Douglas Gregor | 42b2984 | 2011-10-05 19:00:14 +0000 | [diff] [blame] | 1750 | */ |
| 1751 | CXCursor_ObjCProtocolExpr = 140, |
| 1752 | |
| 1753 | /** \brief An Objective-C "bridged" cast expression, which casts between |
| 1754 | * Objective-C pointers and C pointers, transferring ownership in the process. |
| 1755 | * |
| 1756 | * \code |
| 1757 | * NSString *str = (__bridge_transfer NSString *)CFCreateString(); |
| 1758 | * \endcode |
| 1759 | */ |
| 1760 | CXCursor_ObjCBridgedCastExpr = 141, |
| 1761 | |
| 1762 | /** \brief Represents a C++0x pack expansion that produces a sequence of |
| 1763 | * expressions. |
| 1764 | * |
| 1765 | * A pack expansion expression contains a pattern (which itself is an |
| 1766 | * expression) followed by an ellipsis. For example: |
| 1767 | * |
| 1768 | * \code |
| 1769 | * template<typename F, typename ...Types> |
| 1770 | * void forward(F f, Types &&...args) { |
| 1771 | * f(static_cast<Types&&>(args)...); |
| 1772 | * } |
| 1773 | * \endcode |
| 1774 | */ |
| 1775 | CXCursor_PackExpansionExpr = 142, |
| 1776 | |
| 1777 | /** \brief Represents an expression that computes the length of a parameter |
| 1778 | * pack. |
| 1779 | * |
| 1780 | * \code |
| 1781 | * template<typename ...Types> |
| 1782 | * struct count { |
| 1783 | * static const unsigned value = sizeof...(Types); |
| 1784 | * }; |
| 1785 | * \endcode |
| 1786 | */ |
| 1787 | CXCursor_SizeOfPackExpr = 143, |
| 1788 | |
Douglas Gregor | 011d8b9 | 2012-02-15 00:54:55 +0000 | [diff] [blame] | 1789 | /* \brief Represents a C++ lambda expression that produces a local function |
| 1790 | * object. |
| 1791 | * |
| 1792 | * \code |
| 1793 | * void abssort(float *x, unsigned N) { |
| 1794 | * std::sort(x, x + N, |
| 1795 | * [](float a, float b) { |
| 1796 | * return std::abs(a) < std::abs(b); |
| 1797 | * }); |
| 1798 | * } |
| 1799 | * \endcode |
| 1800 | */ |
| 1801 | CXCursor_LambdaExpr = 144, |
| 1802 | |
Ted Kremenek | b3f7542 | 2012-03-06 20:06:06 +0000 | [diff] [blame] | 1803 | /** \brief Objective-c Boolean Literal. |
| 1804 | */ |
| 1805 | CXCursor_ObjCBoolLiteralExpr = 145, |
| 1806 | |
| 1807 | CXCursor_LastExpr = CXCursor_ObjCBoolLiteralExpr, |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 1808 | |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 1809 | /* Statements */ |
| 1810 | CXCursor_FirstStmt = 200, |
| 1811 | /** |
| 1812 | * \brief A statement whose specific kind is not exposed via this |
| 1813 | * interface. |
| 1814 | * |
| 1815 | * Unexposed statements have the same operations as any other kind of |
| 1816 | * statement; one can extract their location information, spelling, |
| 1817 | * children, etc. However, the specific kind of the statement is not |
| 1818 | * reported. |
| 1819 | */ |
| 1820 | CXCursor_UnexposedStmt = 200, |
Douglas Gregor | 36897b0 | 2010-09-10 00:22:18 +0000 | [diff] [blame] | 1821 | |
| 1822 | /** \brief A labelled statement in a function. |
| 1823 | * |
| 1824 | * This cursor kind is used to describe the "start_over:" label statement in |
| 1825 | * the following example: |
| 1826 | * |
| 1827 | * \code |
| 1828 | * start_over: |
| 1829 | * ++counter; |
| 1830 | * \endcode |
| 1831 | * |
| 1832 | */ |
| 1833 | CXCursor_LabelStmt = 201, |
Douglas Gregor | 42b2984 | 2011-10-05 19:00:14 +0000 | [diff] [blame] | 1834 | |
| 1835 | /** \brief A group of statements like { stmt stmt }. |
| 1836 | * |
| 1837 | * This cursor kind is used to describe compound statements, e.g. function |
| 1838 | * bodies. |
| 1839 | */ |
| 1840 | CXCursor_CompoundStmt = 202, |
| 1841 | |
| 1842 | /** \brief A case statment. |
| 1843 | */ |
| 1844 | CXCursor_CaseStmt = 203, |
| 1845 | |
| 1846 | /** \brief A default statement. |
| 1847 | */ |
| 1848 | CXCursor_DefaultStmt = 204, |
| 1849 | |
| 1850 | /** \brief An if statement |
| 1851 | */ |
| 1852 | CXCursor_IfStmt = 205, |
| 1853 | |
| 1854 | /** \brief A switch statement. |
| 1855 | */ |
| 1856 | CXCursor_SwitchStmt = 206, |
| 1857 | |
| 1858 | /** \brief A while statement. |
| 1859 | */ |
| 1860 | CXCursor_WhileStmt = 207, |
| 1861 | |
| 1862 | /** \brief A do statement. |
| 1863 | */ |
| 1864 | CXCursor_DoStmt = 208, |
| 1865 | |
| 1866 | /** \brief A for statement. |
| 1867 | */ |
| 1868 | CXCursor_ForStmt = 209, |
| 1869 | |
| 1870 | /** \brief A goto statement. |
| 1871 | */ |
| 1872 | CXCursor_GotoStmt = 210, |
| 1873 | |
| 1874 | /** \brief An indirect goto statement. |
| 1875 | */ |
| 1876 | CXCursor_IndirectGotoStmt = 211, |
| 1877 | |
| 1878 | /** \brief A continue statement. |
| 1879 | */ |
| 1880 | CXCursor_ContinueStmt = 212, |
| 1881 | |
| 1882 | /** \brief A break statement. |
| 1883 | */ |
| 1884 | CXCursor_BreakStmt = 213, |
| 1885 | |
| 1886 | /** \brief A return statement. |
| 1887 | */ |
| 1888 | CXCursor_ReturnStmt = 214, |
| 1889 | |
| 1890 | /** \brief A GNU inline assembly statement extension. |
| 1891 | */ |
| 1892 | CXCursor_AsmStmt = 215, |
| 1893 | |
Douglas Gregor | 3f54d48 | 2011-11-08 21:07:04 +0000 | [diff] [blame] | 1894 | /** \brief Objective-C's overall @try-@catch-@finally statement. |
Douglas Gregor | 42b2984 | 2011-10-05 19:00:14 +0000 | [diff] [blame] | 1895 | */ |
| 1896 | CXCursor_ObjCAtTryStmt = 216, |
| 1897 | |
| 1898 | /** \brief Objective-C's @catch statement. |
| 1899 | */ |
| 1900 | CXCursor_ObjCAtCatchStmt = 217, |
| 1901 | |
| 1902 | /** \brief Objective-C's @finally statement. |
| 1903 | */ |
| 1904 | CXCursor_ObjCAtFinallyStmt = 218, |
| 1905 | |
| 1906 | /** \brief Objective-C's @throw statement. |
| 1907 | */ |
| 1908 | CXCursor_ObjCAtThrowStmt = 219, |
| 1909 | |
| 1910 | /** \brief Objective-C's @synchronized statement. |
| 1911 | */ |
| 1912 | CXCursor_ObjCAtSynchronizedStmt = 220, |
| 1913 | |
| 1914 | /** \brief Objective-C's autorelease pool statement. |
| 1915 | */ |
| 1916 | CXCursor_ObjCAutoreleasePoolStmt = 221, |
| 1917 | |
| 1918 | /** \brief Objective-C's collection statement. |
| 1919 | */ |
| 1920 | CXCursor_ObjCForCollectionStmt = 222, |
| 1921 | |
| 1922 | /** \brief C++'s catch statement. |
| 1923 | */ |
| 1924 | CXCursor_CXXCatchStmt = 223, |
| 1925 | |
| 1926 | /** \brief C++'s try statement. |
| 1927 | */ |
| 1928 | CXCursor_CXXTryStmt = 224, |
| 1929 | |
| 1930 | /** \brief C++'s for (* : *) statement. |
| 1931 | */ |
| 1932 | CXCursor_CXXForRangeStmt = 225, |
| 1933 | |
| 1934 | /** \brief Windows Structured Exception Handling's try statement. |
| 1935 | */ |
| 1936 | CXCursor_SEHTryStmt = 226, |
| 1937 | |
| 1938 | /** \brief Windows Structured Exception Handling's except statement. |
| 1939 | */ |
| 1940 | CXCursor_SEHExceptStmt = 227, |
| 1941 | |
| 1942 | /** \brief Windows Structured Exception Handling's finally statement. |
| 1943 | */ |
| 1944 | CXCursor_SEHFinallyStmt = 228, |
| 1945 | |
| 1946 | /** \brief The null satement ";": C99 6.8.3p3. |
| 1947 | * |
| 1948 | * This cursor kind is used to describe the null statement. |
| 1949 | */ |
| 1950 | CXCursor_NullStmt = 230, |
| 1951 | |
| 1952 | /** \brief Adaptor class for mixing declarations with statements and |
| 1953 | * expressions. |
| 1954 | */ |
| 1955 | CXCursor_DeclStmt = 231, |
| 1956 | |
| 1957 | CXCursor_LastStmt = CXCursor_DeclStmt, |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 1958 | |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 1959 | /** |
| 1960 | * \brief Cursor that represents the translation unit itself. |
| 1961 | * |
| 1962 | * The translation unit cursor exists primarily to act as the root |
| 1963 | * cursor for traversing the contents of a translation unit. |
| 1964 | */ |
Ted Kremenek | e77f443 | 2010-02-18 03:09:07 +0000 | [diff] [blame] | 1965 | CXCursor_TranslationUnit = 300, |
| 1966 | |
| 1967 | /* Attributes */ |
| 1968 | CXCursor_FirstAttr = 400, |
| 1969 | /** |
| 1970 | * \brief An attribute whose specific kind is not exposed via this |
| 1971 | * interface. |
| 1972 | */ |
| 1973 | CXCursor_UnexposedAttr = 400, |
| 1974 | |
| 1975 | CXCursor_IBActionAttr = 401, |
| 1976 | CXCursor_IBOutletAttr = 402, |
Ted Kremenek | 857e918 | 2010-05-19 17:38:06 +0000 | [diff] [blame] | 1977 | CXCursor_IBOutletCollectionAttr = 403, |
Argyrios Kyrtzidis | 6639e92 | 2011-09-13 17:39:31 +0000 | [diff] [blame] | 1978 | CXCursor_CXXFinalAttr = 404, |
| 1979 | CXCursor_CXXOverrideAttr = 405, |
Erik Verbruggen | 5f1c822 | 2011-10-13 09:41:32 +0000 | [diff] [blame] | 1980 | CXCursor_AnnotateAttr = 406, |
Argyrios Kyrtzidis | 84b7964 | 2011-12-06 22:05:01 +0000 | [diff] [blame] | 1981 | CXCursor_AsmLabelAttr = 407, |
| 1982 | CXCursor_LastAttr = CXCursor_AsmLabelAttr, |
Douglas Gregor | 9f1e3ff | 2010-03-18 00:42:48 +0000 | [diff] [blame] | 1983 | |
| 1984 | /* Preprocessing */ |
| 1985 | CXCursor_PreprocessingDirective = 500, |
Douglas Gregor | 572feb2 | 2010-03-18 18:04:21 +0000 | [diff] [blame] | 1986 | CXCursor_MacroDefinition = 501, |
Chandler Carruth | 9b2a0ac | 2011-07-14 08:41:15 +0000 | [diff] [blame] | 1987 | CXCursor_MacroExpansion = 502, |
| 1988 | CXCursor_MacroInstantiation = CXCursor_MacroExpansion, |
Douglas Gregor | ecdcb88 | 2010-10-20 22:00:55 +0000 | [diff] [blame] | 1989 | CXCursor_InclusionDirective = 503, |
Douglas Gregor | 9f1e3ff | 2010-03-18 00:42:48 +0000 | [diff] [blame] | 1990 | CXCursor_FirstPreprocessing = CXCursor_PreprocessingDirective, |
Douglas Gregor | ecdcb88 | 2010-10-20 22:00:55 +0000 | [diff] [blame] | 1991 | CXCursor_LastPreprocessing = CXCursor_InclusionDirective |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 1992 | }; |
| 1993 | |
| 1994 | /** |
| 1995 | * \brief A cursor representing some element in the abstract syntax tree for |
| 1996 | * a translation unit. |
| 1997 | * |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 1998 | * The cursor abstraction unifies the different kinds of entities in a |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 1999 | * program--declaration, statements, expressions, references to declarations, |
| 2000 | * etc.--under a single "cursor" abstraction with a common set of operations. |
| 2001 | * Common operation for a cursor include: getting the physical location in |
| 2002 | * a source file where the cursor points, getting the name associated with a |
| 2003 | * cursor, and retrieving cursors for any child nodes of a particular cursor. |
| 2004 | * |
| 2005 | * Cursors can be produced in two specific ways. |
| 2006 | * clang_getTranslationUnitCursor() produces a cursor for a translation unit, |
| 2007 | * from which one can use clang_visitChildren() to explore the rest of the |
| 2008 | * translation unit. clang_getCursor() maps from a physical source location |
| 2009 | * to the entity that resides at that location, allowing one to map from the |
| 2010 | * source code into the AST. |
| 2011 | */ |
| 2012 | typedef struct { |
| 2013 | enum CXCursorKind kind; |
Argyrios Kyrtzidis | aed123e | 2011-10-06 07:00:54 +0000 | [diff] [blame] | 2014 | int xdata; |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 2015 | void *data[3]; |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 2016 | } CXCursor; |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 2017 | |
| 2018 | /** |
| 2019 | * \defgroup CINDEX_CURSOR_MANIP Cursor manipulations |
| 2020 | * |
| 2021 | * @{ |
| 2022 | */ |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 2023 | |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 2024 | /** |
| 2025 | * \brief Retrieve the NULL cursor, which represents no entity. |
| 2026 | */ |
| 2027 | CINDEX_LINKAGE CXCursor clang_getNullCursor(void); |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 2028 | |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 2029 | /** |
| 2030 | * \brief Retrieve the cursor that represents the given translation unit. |
| 2031 | * |
| 2032 | * The translation unit cursor can be used to start traversing the |
| 2033 | * various declarations within the given translation unit. |
| 2034 | */ |
| 2035 | CINDEX_LINKAGE CXCursor clang_getTranslationUnitCursor(CXTranslationUnit); |
| 2036 | |
| 2037 | /** |
| 2038 | * \brief Determine whether two cursors are equivalent. |
| 2039 | */ |
| 2040 | CINDEX_LINKAGE unsigned clang_equalCursors(CXCursor, CXCursor); |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 2041 | |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 2042 | /** |
Argyrios Kyrtzidis | b0d6eaa | 2011-09-27 00:30:30 +0000 | [diff] [blame] | 2043 | * \brief Returns non-zero if \arg cursor is null. |
| 2044 | */ |
Benjamin Kramer | 5b41936 | 2012-02-01 20:37:28 +0000 | [diff] [blame] | 2045 | CINDEX_LINKAGE int clang_Cursor_isNull(CXCursor); |
Argyrios Kyrtzidis | b0d6eaa | 2011-09-27 00:30:30 +0000 | [diff] [blame] | 2046 | |
| 2047 | /** |
Douglas Gregor | 9ce5584 | 2010-11-20 00:09:34 +0000 | [diff] [blame] | 2048 | * \brief Compute a hash value for the given cursor. |
| 2049 | */ |
| 2050 | CINDEX_LINKAGE unsigned clang_hashCursor(CXCursor); |
| 2051 | |
| 2052 | /** |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 2053 | * \brief Retrieve the kind of the given cursor. |
| 2054 | */ |
| 2055 | CINDEX_LINKAGE enum CXCursorKind clang_getCursorKind(CXCursor); |
| 2056 | |
| 2057 | /** |
| 2058 | * \brief Determine whether the given cursor kind represents a declaration. |
| 2059 | */ |
| 2060 | CINDEX_LINKAGE unsigned clang_isDeclaration(enum CXCursorKind); |
| 2061 | |
| 2062 | /** |
| 2063 | * \brief Determine whether the given cursor kind represents a simple |
| 2064 | * reference. |
| 2065 | * |
| 2066 | * Note that other kinds of cursors (such as expressions) can also refer to |
| 2067 | * other cursors. Use clang_getCursorReferenced() to determine whether a |
| 2068 | * particular cursor refers to another entity. |
| 2069 | */ |
| 2070 | CINDEX_LINKAGE unsigned clang_isReference(enum CXCursorKind); |
| 2071 | |
| 2072 | /** |
| 2073 | * \brief Determine whether the given cursor kind represents an expression. |
| 2074 | */ |
| 2075 | CINDEX_LINKAGE unsigned clang_isExpression(enum CXCursorKind); |
| 2076 | |
| 2077 | /** |
| 2078 | * \brief Determine whether the given cursor kind represents a statement. |
| 2079 | */ |
| 2080 | CINDEX_LINKAGE unsigned clang_isStatement(enum CXCursorKind); |
| 2081 | |
| 2082 | /** |
Douglas Gregor | 8be80e1 | 2011-07-06 03:00:34 +0000 | [diff] [blame] | 2083 | * \brief Determine whether the given cursor kind represents an attribute. |
| 2084 | */ |
| 2085 | CINDEX_LINKAGE unsigned clang_isAttribute(enum CXCursorKind); |
| 2086 | |
| 2087 | /** |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 2088 | * \brief Determine whether the given cursor kind represents an invalid |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 2089 | * cursor. |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 2090 | */ |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 2091 | CINDEX_LINKAGE unsigned clang_isInvalid(enum CXCursorKind); |
| 2092 | |
| 2093 | /** |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 2094 | * \brief Determine whether the given cursor kind represents a translation |
| 2095 | * unit. |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 2096 | */ |
| 2097 | CINDEX_LINKAGE unsigned clang_isTranslationUnit(enum CXCursorKind); |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 2098 | |
Ted Kremenek | ad6eff6 | 2010-03-08 21:17:29 +0000 | [diff] [blame] | 2099 | /*** |
Douglas Gregor | 9f1e3ff | 2010-03-18 00:42:48 +0000 | [diff] [blame] | 2100 | * \brief Determine whether the given cursor represents a preprocessing |
| 2101 | * element, such as a preprocessor directive or macro instantiation. |
| 2102 | */ |
| 2103 | CINDEX_LINKAGE unsigned clang_isPreprocessing(enum CXCursorKind); |
| 2104 | |
| 2105 | /*** |
Ted Kremenek | ad6eff6 | 2010-03-08 21:17:29 +0000 | [diff] [blame] | 2106 | * \brief Determine whether the given cursor represents a currently |
| 2107 | * unexposed piece of the AST (e.g., CXCursor_UnexposedStmt). |
| 2108 | */ |
| 2109 | CINDEX_LINKAGE unsigned clang_isUnexposed(enum CXCursorKind); |
| 2110 | |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 2111 | /** |
Ted Kremenek | 16b4259 | 2010-03-03 06:36:57 +0000 | [diff] [blame] | 2112 | * \brief Describe the linkage of the entity referred to by a cursor. |
| 2113 | */ |
| 2114 | enum CXLinkageKind { |
| 2115 | /** \brief This value indicates that no linkage information is available |
| 2116 | * for a provided CXCursor. */ |
| 2117 | CXLinkage_Invalid, |
| 2118 | /** |
| 2119 | * \brief This is the linkage for variables, parameters, and so on that |
| 2120 | * have automatic storage. This covers normal (non-extern) local variables. |
| 2121 | */ |
| 2122 | CXLinkage_NoLinkage, |
| 2123 | /** \brief This is the linkage for static variables and static functions. */ |
| 2124 | CXLinkage_Internal, |
| 2125 | /** \brief This is the linkage for entities with external linkage that live |
| 2126 | * in C++ anonymous namespaces.*/ |
| 2127 | CXLinkage_UniqueExternal, |
| 2128 | /** \brief This is the linkage for entities with true, external linkage. */ |
| 2129 | CXLinkage_External |
| 2130 | }; |
| 2131 | |
| 2132 | /** |
Ted Kremenek | 45e1dae | 2010-04-12 21:22:16 +0000 | [diff] [blame] | 2133 | * \brief Determine the linkage of the entity referred to by a given cursor. |
Ted Kremenek | 16b4259 | 2010-03-03 06:36:57 +0000 | [diff] [blame] | 2134 | */ |
| 2135 | CINDEX_LINKAGE enum CXLinkageKind clang_getCursorLinkage(CXCursor cursor); |
| 2136 | |
| 2137 | /** |
Douglas Gregor | 58ddb60 | 2010-08-23 23:00:57 +0000 | [diff] [blame] | 2138 | * \brief Determine the availability of the entity that this cursor refers to. |
| 2139 | * |
| 2140 | * \param cursor The cursor to query. |
| 2141 | * |
| 2142 | * \returns The availability of the cursor. |
| 2143 | */ |
| 2144 | CINDEX_LINKAGE enum CXAvailabilityKind |
| 2145 | clang_getCursorAvailability(CXCursor cursor); |
| 2146 | |
| 2147 | /** |
Ted Kremenek | 45e1dae | 2010-04-12 21:22:16 +0000 | [diff] [blame] | 2148 | * \brief Describe the "language" of the entity referred to by a cursor. |
| 2149 | */ |
| 2150 | CINDEX_LINKAGE enum CXLanguageKind { |
Ted Kremenek | 6cd1e7c | 2010-04-14 20:58:32 +0000 | [diff] [blame] | 2151 | CXLanguage_Invalid = 0, |
Ted Kremenek | 45e1dae | 2010-04-12 21:22:16 +0000 | [diff] [blame] | 2152 | CXLanguage_C, |
| 2153 | CXLanguage_ObjC, |
Ted Kremenek | 6cd1e7c | 2010-04-14 20:58:32 +0000 | [diff] [blame] | 2154 | CXLanguage_CPlusPlus |
Ted Kremenek | 45e1dae | 2010-04-12 21:22:16 +0000 | [diff] [blame] | 2155 | }; |
| 2156 | |
| 2157 | /** |
| 2158 | * \brief Determine the "language" of the entity referred to by a given cursor. |
| 2159 | */ |
| 2160 | CINDEX_LINKAGE enum CXLanguageKind clang_getCursorLanguage(CXCursor cursor); |
| 2161 | |
Argyrios Kyrtzidis | b0d6eaa | 2011-09-27 00:30:30 +0000 | [diff] [blame] | 2162 | /** |
| 2163 | * \brief Returns the translation unit that a cursor originated from. |
| 2164 | */ |
| 2165 | CINDEX_LINKAGE CXTranslationUnit clang_Cursor_getTranslationUnit(CXCursor); |
| 2166 | |
Ted Kremenek | eca099b | 2010-12-08 23:43:14 +0000 | [diff] [blame] | 2167 | |
| 2168 | /** |
| 2169 | * \brief A fast container representing a set of CXCursors. |
| 2170 | */ |
| 2171 | typedef struct CXCursorSetImpl *CXCursorSet; |
| 2172 | |
| 2173 | /** |
| 2174 | * \brief Creates an empty CXCursorSet. |
| 2175 | */ |
| 2176 | CINDEX_LINKAGE CXCursorSet clang_createCXCursorSet(); |
| 2177 | |
| 2178 | /** |
| 2179 | * \brief Disposes a CXCursorSet and releases its associated memory. |
| 2180 | */ |
| 2181 | CINDEX_LINKAGE void clang_disposeCXCursorSet(CXCursorSet cset); |
| 2182 | |
| 2183 | /** |
| 2184 | * \brief Queries a CXCursorSet to see if it contains a specific CXCursor. |
| 2185 | * |
| 2186 | * \returns non-zero if the set contains the specified cursor. |
| 2187 | */ |
| 2188 | CINDEX_LINKAGE unsigned clang_CXCursorSet_contains(CXCursorSet cset, |
| 2189 | CXCursor cursor); |
| 2190 | |
| 2191 | /** |
| 2192 | * \brief Inserts a CXCursor into a CXCursorSet. |
| 2193 | * |
| 2194 | * \returns zero if the CXCursor was already in the set, and non-zero otherwise. |
| 2195 | */ |
| 2196 | CINDEX_LINKAGE unsigned clang_CXCursorSet_insert(CXCursorSet cset, |
| 2197 | CXCursor cursor); |
| 2198 | |
Douglas Gregor | 2be5bc9 | 2010-09-22 21:22:29 +0000 | [diff] [blame] | 2199 | /** |
| 2200 | * \brief Determine the semantic parent of the given cursor. |
| 2201 | * |
| 2202 | * The semantic parent of a cursor is the cursor that semantically contains |
| 2203 | * the given \p cursor. For many declarations, the lexical and semantic parents |
| 2204 | * are equivalent (the lexical parent is returned by |
| 2205 | * \c clang_getCursorLexicalParent()). They diverge when declarations or |
| 2206 | * definitions are provided out-of-line. For example: |
| 2207 | * |
| 2208 | * \code |
| 2209 | * class C { |
| 2210 | * void f(); |
| 2211 | * }; |
| 2212 | * |
| 2213 | * void C::f() { } |
| 2214 | * \endcode |
| 2215 | * |
| 2216 | * In the out-of-line definition of \c C::f, the semantic parent is the |
| 2217 | * the class \c C, of which this function is a member. The lexical parent is |
| 2218 | * the place where the declaration actually occurs in the source code; in this |
| 2219 | * case, the definition occurs in the translation unit. In general, the |
| 2220 | * lexical parent for a given entity can change without affecting the semantics |
| 2221 | * of the program, and the lexical parent of different declarations of the |
| 2222 | * same entity may be different. Changing the semantic parent of a declaration, |
| 2223 | * on the other hand, can have a major impact on semantics, and redeclarations |
| 2224 | * of a particular entity should all have the same semantic context. |
| 2225 | * |
| 2226 | * In the example above, both declarations of \c C::f have \c C as their |
| 2227 | * semantic context, while the lexical context of the first \c C::f is \c C |
| 2228 | * and the lexical context of the second \c C::f is the translation unit. |
Douglas Gregor | 3910cfd | 2010-12-21 07:55:45 +0000 | [diff] [blame] | 2229 | * |
| 2230 | * For global declarations, the semantic parent is the translation unit. |
Douglas Gregor | 2be5bc9 | 2010-09-22 21:22:29 +0000 | [diff] [blame] | 2231 | */ |
| 2232 | CINDEX_LINKAGE CXCursor clang_getCursorSemanticParent(CXCursor cursor); |
| 2233 | |
| 2234 | /** |
| 2235 | * \brief Determine the lexical parent of the given cursor. |
| 2236 | * |
| 2237 | * The lexical parent of a cursor is the cursor in which the given \p cursor |
| 2238 | * was actually written. For many declarations, the lexical and semantic parents |
| 2239 | * are equivalent (the semantic parent is returned by |
| 2240 | * \c clang_getCursorSemanticParent()). They diverge when declarations or |
| 2241 | * definitions are provided out-of-line. For example: |
| 2242 | * |
| 2243 | * \code |
| 2244 | * class C { |
| 2245 | * void f(); |
| 2246 | * }; |
| 2247 | * |
| 2248 | * void C::f() { } |
| 2249 | * \endcode |
| 2250 | * |
| 2251 | * In the out-of-line definition of \c C::f, the semantic parent is the |
| 2252 | * the class \c C, of which this function is a member. The lexical parent is |
| 2253 | * the place where the declaration actually occurs in the source code; in this |
| 2254 | * case, the definition occurs in the translation unit. In general, the |
| 2255 | * lexical parent for a given entity can change without affecting the semantics |
| 2256 | * of the program, and the lexical parent of different declarations of the |
| 2257 | * same entity may be different. Changing the semantic parent of a declaration, |
| 2258 | * on the other hand, can have a major impact on semantics, and redeclarations |
| 2259 | * of a particular entity should all have the same semantic context. |
| 2260 | * |
| 2261 | * In the example above, both declarations of \c C::f have \c C as their |
| 2262 | * semantic context, while the lexical context of the first \c C::f is \c C |
| 2263 | * and the lexical context of the second \c C::f is the translation unit. |
Douglas Gregor | 3910cfd | 2010-12-21 07:55:45 +0000 | [diff] [blame] | 2264 | * |
| 2265 | * For declarations written in the global scope, the lexical parent is |
| 2266 | * the translation unit. |
Douglas Gregor | 2be5bc9 | 2010-09-22 21:22:29 +0000 | [diff] [blame] | 2267 | */ |
| 2268 | CINDEX_LINKAGE CXCursor clang_getCursorLexicalParent(CXCursor cursor); |
Douglas Gregor | 9f59234 | 2010-10-01 20:25:15 +0000 | [diff] [blame] | 2269 | |
| 2270 | /** |
| 2271 | * \brief Determine the set of methods that are overridden by the given |
| 2272 | * method. |
| 2273 | * |
| 2274 | * In both Objective-C and C++, a method (aka virtual member function, |
| 2275 | * in C++) can override a virtual method in a base class. For |
| 2276 | * Objective-C, a method is said to override any method in the class's |
Argyrios Kyrtzidis | 044e645 | 2012-03-08 00:20:03 +0000 | [diff] [blame] | 2277 | * base class, its protocols, or its categories' protocols, that has the same |
| 2278 | * selector and is of the same kind (class or instance). |
| 2279 | * If no such method exists, the search continues to the class's superclass, |
| 2280 | * its protocols, and its categories, and so on. A method from an Objective-C |
| 2281 | * implementation is considered to override the same methods as its |
| 2282 | * corresponding method in the interface. |
Douglas Gregor | 9f59234 | 2010-10-01 20:25:15 +0000 | [diff] [blame] | 2283 | * |
| 2284 | * For C++, a virtual member function overrides any virtual member |
| 2285 | * function with the same signature that occurs in its base |
| 2286 | * classes. With multiple inheritance, a virtual member function can |
| 2287 | * override several virtual member functions coming from different |
| 2288 | * base classes. |
| 2289 | * |
| 2290 | * In all cases, this function determines the immediate overridden |
| 2291 | * method, rather than all of the overridden methods. For example, if |
| 2292 | * a method is originally declared in a class A, then overridden in B |
| 2293 | * (which in inherits from A) and also in C (which inherited from B), |
| 2294 | * then the only overridden method returned from this function when |
| 2295 | * invoked on C's method will be B's method. The client may then |
| 2296 | * invoke this function again, given the previously-found overridden |
| 2297 | * methods, to map out the complete method-override set. |
| 2298 | * |
| 2299 | * \param cursor A cursor representing an Objective-C or C++ |
| 2300 | * method. This routine will compute the set of methods that this |
| 2301 | * method overrides. |
| 2302 | * |
| 2303 | * \param overridden A pointer whose pointee will be replaced with a |
| 2304 | * pointer to an array of cursors, representing the set of overridden |
| 2305 | * methods. If there are no overridden methods, the pointee will be |
| 2306 | * set to NULL. The pointee must be freed via a call to |
| 2307 | * \c clang_disposeOverriddenCursors(). |
| 2308 | * |
| 2309 | * \param num_overridden A pointer to the number of overridden |
| 2310 | * functions, will be set to the number of overridden functions in the |
| 2311 | * array pointed to by \p overridden. |
| 2312 | */ |
| 2313 | CINDEX_LINKAGE void clang_getOverriddenCursors(CXCursor cursor, |
| 2314 | CXCursor **overridden, |
| 2315 | unsigned *num_overridden); |
| 2316 | |
| 2317 | /** |
| 2318 | * \brief Free the set of overridden cursors returned by \c |
| 2319 | * clang_getOverriddenCursors(). |
| 2320 | */ |
| 2321 | CINDEX_LINKAGE void clang_disposeOverriddenCursors(CXCursor *overridden); |
| 2322 | |
Ted Kremenek | 45e1dae | 2010-04-12 21:22:16 +0000 | [diff] [blame] | 2323 | /** |
Douglas Gregor | ecdcb88 | 2010-10-20 22:00:55 +0000 | [diff] [blame] | 2324 | * \brief Retrieve the file that is included by the given inclusion directive |
| 2325 | * cursor. |
| 2326 | */ |
| 2327 | CINDEX_LINKAGE CXFile clang_getIncludedFile(CXCursor cursor); |
| 2328 | |
| 2329 | /** |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 2330 | * @} |
| 2331 | */ |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 2332 | |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 2333 | /** |
| 2334 | * \defgroup CINDEX_CURSOR_SOURCE Mapping between cursors and source code |
| 2335 | * |
| 2336 | * Cursors represent a location within the Abstract Syntax Tree (AST). These |
| 2337 | * routines help map between cursors and the physical locations where the |
| 2338 | * described entities occur in the source code. The mapping is provided in |
| 2339 | * both directions, so one can map from source code to the AST and back. |
| 2340 | * |
| 2341 | * @{ |
Steve Naroff | 5039819 | 2009-08-28 15:28:48 +0000 | [diff] [blame] | 2342 | */ |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 2343 | |
Steve Naroff | 6a6de8b | 2009-10-21 13:56:23 +0000 | [diff] [blame] | 2344 | /** |
Douglas Gregor | b979034 | 2010-01-22 21:44:22 +0000 | [diff] [blame] | 2345 | * \brief Map a source location to the cursor that describes the entity at that |
| 2346 | * location in the source code. |
| 2347 | * |
| 2348 | * clang_getCursor() maps an arbitrary source location within a translation |
| 2349 | * 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] | 2350 | * location. For example, given an expression \c x + y, invoking |
Douglas Gregor | b979034 | 2010-01-22 21:44:22 +0000 | [diff] [blame] | 2351 | * clang_getCursor() with a source location pointing to "x" will return the |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 2352 | * cursor for "x"; similarly for "y". If the cursor points anywhere between |
Douglas Gregor | b979034 | 2010-01-22 21:44:22 +0000 | [diff] [blame] | 2353 | * "x" or "y" (e.g., on the + or the whitespace around it), clang_getCursor() |
| 2354 | * will return a cursor referring to the "+" expression. |
| 2355 | * |
| 2356 | * \returns a cursor representing the entity at the given source location, or |
| 2357 | * a NULL cursor if no such entity can be found. |
Steve Naroff | 6a6de8b | 2009-10-21 13:56:23 +0000 | [diff] [blame] | 2358 | */ |
Douglas Gregor | b979034 | 2010-01-22 21:44:22 +0000 | [diff] [blame] | 2359 | CINDEX_LINKAGE CXCursor clang_getCursor(CXTranslationUnit, CXSourceLocation); |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 2360 | |
Douglas Gregor | 98258af | 2010-01-18 22:46:11 +0000 | [diff] [blame] | 2361 | /** |
| 2362 | * \brief Retrieve the physical location of the source constructor referenced |
| 2363 | * by the given cursor. |
| 2364 | * |
| 2365 | * 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] | 2366 | * declaration, where the name of that declaration would occur if it is |
| 2367 | * unnamed, or some keyword that introduces that particular declaration. |
| 2368 | * The location of a reference is where that reference occurs within the |
Douglas Gregor | 98258af | 2010-01-18 22:46:11 +0000 | [diff] [blame] | 2369 | * source code. |
| 2370 | */ |
| 2371 | CINDEX_LINKAGE CXSourceLocation clang_getCursorLocation(CXCursor); |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 2372 | |
Douglas Gregor | b699866 | 2010-01-19 19:34:47 +0000 | [diff] [blame] | 2373 | /** |
| 2374 | * \brief Retrieve the physical extent of the source construct referenced by |
Douglas Gregor | a7bde20 | 2010-01-19 00:34:46 +0000 | [diff] [blame] | 2375 | * the given cursor. |
| 2376 | * |
| 2377 | * The extent of a cursor starts with the file/line/column pointing at the |
| 2378 | * first character within the source construct that the cursor refers to and |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 2379 | * ends with the last character withinin that source construct. For a |
Douglas Gregor | a7bde20 | 2010-01-19 00:34:46 +0000 | [diff] [blame] | 2380 | * declaration, the extent covers the declaration itself. For a reference, |
| 2381 | * the extent covers the location of the reference (e.g., where the referenced |
| 2382 | * entity was actually used). |
| 2383 | */ |
| 2384 | CINDEX_LINKAGE CXSourceRange clang_getCursorExtent(CXCursor); |
Douglas Gregor | c5d1e93 | 2010-01-19 01:20:04 +0000 | [diff] [blame] | 2385 | |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 2386 | /** |
| 2387 | * @} |
| 2388 | */ |
Ted Kremenek | 95f3355 | 2010-08-26 01:42:22 +0000 | [diff] [blame] | 2389 | |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 2390 | /** |
Ted Kremenek | 8e0ac17 | 2010-05-14 21:29:26 +0000 | [diff] [blame] | 2391 | * \defgroup CINDEX_TYPES Type information for CXCursors |
| 2392 | * |
| 2393 | * @{ |
| 2394 | */ |
| 2395 | |
| 2396 | /** |
| 2397 | * \brief Describes the kind of type |
| 2398 | */ |
| 2399 | enum CXTypeKind { |
| 2400 | /** |
| 2401 | * \brief Reprents an invalid type (e.g., where no type is available). |
| 2402 | */ |
| 2403 | CXType_Invalid = 0, |
| 2404 | |
| 2405 | /** |
| 2406 | * \brief A type whose specific kind is not exposed via this |
| 2407 | * interface. |
| 2408 | */ |
| 2409 | CXType_Unexposed = 1, |
| 2410 | |
| 2411 | /* Builtin types */ |
| 2412 | CXType_Void = 2, |
| 2413 | CXType_Bool = 3, |
| 2414 | CXType_Char_U = 4, |
| 2415 | CXType_UChar = 5, |
| 2416 | CXType_Char16 = 6, |
| 2417 | CXType_Char32 = 7, |
| 2418 | CXType_UShort = 8, |
| 2419 | CXType_UInt = 9, |
| 2420 | CXType_ULong = 10, |
| 2421 | CXType_ULongLong = 11, |
| 2422 | CXType_UInt128 = 12, |
| 2423 | CXType_Char_S = 13, |
| 2424 | CXType_SChar = 14, |
| 2425 | CXType_WChar = 15, |
| 2426 | CXType_Short = 16, |
| 2427 | CXType_Int = 17, |
| 2428 | CXType_Long = 18, |
| 2429 | CXType_LongLong = 19, |
| 2430 | CXType_Int128 = 20, |
| 2431 | CXType_Float = 21, |
| 2432 | CXType_Double = 22, |
| 2433 | CXType_LongDouble = 23, |
| 2434 | CXType_NullPtr = 24, |
| 2435 | CXType_Overload = 25, |
| 2436 | CXType_Dependent = 26, |
| 2437 | CXType_ObjCId = 27, |
| 2438 | CXType_ObjCClass = 28, |
| 2439 | CXType_ObjCSel = 29, |
| 2440 | CXType_FirstBuiltin = CXType_Void, |
| 2441 | CXType_LastBuiltin = CXType_ObjCSel, |
| 2442 | |
| 2443 | CXType_Complex = 100, |
| 2444 | CXType_Pointer = 101, |
| 2445 | CXType_BlockPointer = 102, |
| 2446 | CXType_LValueReference = 103, |
| 2447 | CXType_RValueReference = 104, |
| 2448 | CXType_Record = 105, |
| 2449 | CXType_Enum = 106, |
| 2450 | CXType_Typedef = 107, |
| 2451 | CXType_ObjCInterface = 108, |
Ted Kremenek | 04c3cf3 | 2010-06-21 20:15:39 +0000 | [diff] [blame] | 2452 | CXType_ObjCObjectPointer = 109, |
| 2453 | CXType_FunctionNoProto = 110, |
Argyrios Kyrtzidis | 5f0bfc5 | 2011-09-27 17:44:34 +0000 | [diff] [blame] | 2454 | CXType_FunctionProto = 111, |
Argyrios Kyrtzidis | 84b7964 | 2011-12-06 22:05:01 +0000 | [diff] [blame] | 2455 | CXType_ConstantArray = 112, |
| 2456 | CXType_Vector = 113 |
Ted Kremenek | 8e0ac17 | 2010-05-14 21:29:26 +0000 | [diff] [blame] | 2457 | }; |
| 2458 | |
| 2459 | /** |
Argyrios Kyrtzidis | 84b7964 | 2011-12-06 22:05:01 +0000 | [diff] [blame] | 2460 | * \brief Describes the calling convention of a function type |
| 2461 | */ |
| 2462 | enum CXCallingConv { |
| 2463 | CXCallingConv_Default = 0, |
| 2464 | CXCallingConv_C = 1, |
| 2465 | CXCallingConv_X86StdCall = 2, |
| 2466 | CXCallingConv_X86FastCall = 3, |
| 2467 | CXCallingConv_X86ThisCall = 4, |
| 2468 | CXCallingConv_X86Pascal = 5, |
| 2469 | CXCallingConv_AAPCS = 6, |
| 2470 | CXCallingConv_AAPCS_VFP = 7, |
| 2471 | |
| 2472 | CXCallingConv_Invalid = 100, |
| 2473 | CXCallingConv_Unexposed = 200 |
| 2474 | }; |
| 2475 | |
| 2476 | |
| 2477 | /** |
Ted Kremenek | 8e0ac17 | 2010-05-14 21:29:26 +0000 | [diff] [blame] | 2478 | * \brief The type of an element in the abstract syntax tree. |
| 2479 | * |
| 2480 | */ |
| 2481 | typedef struct { |
| 2482 | enum CXTypeKind kind; |
| 2483 | void *data[2]; |
| 2484 | } CXType; |
| 2485 | |
| 2486 | /** |
| 2487 | * \brief Retrieve the type of a CXCursor (if any). |
| 2488 | */ |
| 2489 | CINDEX_LINKAGE CXType clang_getCursorType(CXCursor C); |
| 2490 | |
| 2491 | /** |
Argyrios Kyrtzidis | 84b7964 | 2011-12-06 22:05:01 +0000 | [diff] [blame] | 2492 | * \brief Retrieve the underlying type of a typedef declaration. |
| 2493 | * |
| 2494 | * If the cursor does not reference a typedef declaration, an invalid type is |
| 2495 | * returned. |
| 2496 | */ |
| 2497 | CINDEX_LINKAGE CXType clang_getTypedefDeclUnderlyingType(CXCursor C); |
| 2498 | |
| 2499 | /** |
| 2500 | * \brief Retrieve the integer type of an enum declaration. |
| 2501 | * |
| 2502 | * If the cursor does not reference an enum declaration, an invalid type is |
| 2503 | * returned. |
| 2504 | */ |
| 2505 | CINDEX_LINKAGE CXType clang_getEnumDeclIntegerType(CXCursor C); |
| 2506 | |
| 2507 | /** |
| 2508 | * \brief Retrieve the integer value of an enum constant declaration as a signed |
| 2509 | * long long. |
| 2510 | * |
| 2511 | * If the cursor does not reference an enum constant declaration, LLONG_MIN is returned. |
| 2512 | * Since this is also potentially a valid constant value, the kind of the cursor |
| 2513 | * must be verified before calling this function. |
| 2514 | */ |
| 2515 | CINDEX_LINKAGE long long clang_getEnumConstantDeclValue(CXCursor C); |
| 2516 | |
| 2517 | /** |
| 2518 | * \brief Retrieve the integer value of an enum constant declaration as an unsigned |
| 2519 | * long long. |
| 2520 | * |
| 2521 | * If the cursor does not reference an enum constant declaration, ULLONG_MAX is returned. |
| 2522 | * Since this is also potentially a valid constant value, the kind of the cursor |
| 2523 | * must be verified before calling this function. |
| 2524 | */ |
| 2525 | CINDEX_LINKAGE unsigned long long clang_getEnumConstantDeclUnsignedValue(CXCursor C); |
| 2526 | |
| 2527 | /** |
Ted Kremenek | 8e0ac17 | 2010-05-14 21:29:26 +0000 | [diff] [blame] | 2528 | * \determine Determine whether two CXTypes represent the same type. |
| 2529 | * |
| 2530 | * \returns non-zero if the CXTypes represent the same type and |
| 2531 | zero otherwise. |
| 2532 | */ |
| 2533 | CINDEX_LINKAGE unsigned clang_equalTypes(CXType A, CXType B); |
| 2534 | |
| 2535 | /** |
| 2536 | * \brief Return the canonical type for a CXType. |
| 2537 | * |
| 2538 | * Clang's type system explicitly models typedefs and all the ways |
| 2539 | * a specific type can be represented. The canonical type is the underlying |
| 2540 | * type with all the "sugar" removed. For example, if 'T' is a typedef |
| 2541 | * for 'int', the canonical type for 'T' would be 'int'. |
| 2542 | */ |
| 2543 | CINDEX_LINKAGE CXType clang_getCanonicalType(CXType T); |
| 2544 | |
| 2545 | /** |
Douglas Gregor | e72fb6f | 2011-01-27 16:27:11 +0000 | [diff] [blame] | 2546 | * \determine Determine whether a CXType has the "const" qualifier set, |
| 2547 | * without looking through typedefs that may have added "const" at a different level. |
| 2548 | */ |
| 2549 | CINDEX_LINKAGE unsigned clang_isConstQualifiedType(CXType T); |
| 2550 | |
| 2551 | /** |
| 2552 | * \determine Determine whether a CXType has the "volatile" qualifier set, |
| 2553 | * without looking through typedefs that may have added "volatile" at a different level. |
| 2554 | */ |
| 2555 | CINDEX_LINKAGE unsigned clang_isVolatileQualifiedType(CXType T); |
| 2556 | |
| 2557 | /** |
| 2558 | * \determine Determine whether a CXType has the "restrict" qualifier set, |
| 2559 | * without looking through typedefs that may have added "restrict" at a different level. |
| 2560 | */ |
| 2561 | CINDEX_LINKAGE unsigned clang_isRestrictQualifiedType(CXType T); |
| 2562 | |
| 2563 | /** |
Ted Kremenek | 8e0ac17 | 2010-05-14 21:29:26 +0000 | [diff] [blame] | 2564 | * \brief For pointer types, returns the type of the pointee. |
| 2565 | * |
| 2566 | */ |
| 2567 | CINDEX_LINKAGE CXType clang_getPointeeType(CXType T); |
| 2568 | |
| 2569 | /** |
| 2570 | * \brief Return the cursor for the declaration of the given type. |
| 2571 | */ |
| 2572 | CINDEX_LINKAGE CXCursor clang_getTypeDeclaration(CXType T); |
| 2573 | |
David Chisnall | 5389f48 | 2010-12-30 14:05:53 +0000 | [diff] [blame] | 2574 | /** |
| 2575 | * Returns the Objective-C type encoding for the specified declaration. |
| 2576 | */ |
| 2577 | CINDEX_LINKAGE CXString clang_getDeclObjCTypeEncoding(CXCursor C); |
Ted Kremenek | 8e0ac17 | 2010-05-14 21:29:26 +0000 | [diff] [blame] | 2578 | |
| 2579 | /** |
| 2580 | * \brief Retrieve the spelling of a given CXTypeKind. |
| 2581 | */ |
| 2582 | CINDEX_LINKAGE CXString clang_getTypeKindSpelling(enum CXTypeKind K); |
| 2583 | |
| 2584 | /** |
Argyrios Kyrtzidis | 84b7964 | 2011-12-06 22:05:01 +0000 | [diff] [blame] | 2585 | * \brief Retrieve the calling convention associated with a function type. |
| 2586 | * |
| 2587 | * If a non-function type is passed in, CXCallingConv_Invalid is returned. |
| 2588 | */ |
| 2589 | CINDEX_LINKAGE enum CXCallingConv clang_getFunctionTypeCallingConv(CXType T); |
| 2590 | |
| 2591 | /** |
Ted Kremenek | 9a14084 | 2010-06-21 20:48:56 +0000 | [diff] [blame] | 2592 | * \brief Retrieve the result type associated with a function type. |
Argyrios Kyrtzidis | 84b7964 | 2011-12-06 22:05:01 +0000 | [diff] [blame] | 2593 | * |
| 2594 | * If a non-function type is passed in, an invalid type is returned. |
Ted Kremenek | 04c3cf3 | 2010-06-21 20:15:39 +0000 | [diff] [blame] | 2595 | */ |
| 2596 | CINDEX_LINKAGE CXType clang_getResultType(CXType T); |
| 2597 | |
| 2598 | /** |
Argyrios Kyrtzidis | 84b7964 | 2011-12-06 22:05:01 +0000 | [diff] [blame] | 2599 | * \brief Retrieve the number of non-variadic arguments associated with a function type. |
| 2600 | * |
| 2601 | * If a non-function type is passed in, UINT_MAX is returned. |
| 2602 | */ |
| 2603 | CINDEX_LINKAGE unsigned clang_getNumArgTypes(CXType T); |
| 2604 | |
| 2605 | /** |
| 2606 | * \brief Retrieve the type of an argument of a function type. |
| 2607 | * |
| 2608 | * If a non-function type is passed in or the function does not have enough parameters, |
| 2609 | * an invalid type is returned. |
| 2610 | */ |
| 2611 | CINDEX_LINKAGE CXType clang_getArgType(CXType T, unsigned i); |
| 2612 | |
| 2613 | /** |
| 2614 | * \brief Return 1 if the CXType is a variadic function type, and 0 otherwise. |
| 2615 | * |
| 2616 | */ |
| 2617 | CINDEX_LINKAGE unsigned clang_isFunctionTypeVariadic(CXType T); |
| 2618 | |
| 2619 | /** |
| 2620 | * \brief Retrieve the result type associated with a given cursor. |
| 2621 | * |
| 2622 | * This only returns a valid type if the cursor refers to a function or method. |
Ted Kremenek | 9a14084 | 2010-06-21 20:48:56 +0000 | [diff] [blame] | 2623 | */ |
| 2624 | CINDEX_LINKAGE CXType clang_getCursorResultType(CXCursor C); |
| 2625 | |
| 2626 | /** |
Ted Kremenek | 3ce9e7d | 2010-07-30 00:14:11 +0000 | [diff] [blame] | 2627 | * \brief Return 1 if the CXType is a POD (plain old data) type, and 0 |
| 2628 | * otherwise. |
| 2629 | */ |
| 2630 | CINDEX_LINKAGE unsigned clang_isPODType(CXType T); |
| 2631 | |
| 2632 | /** |
Argyrios Kyrtzidis | 84b7964 | 2011-12-06 22:05:01 +0000 | [diff] [blame] | 2633 | * \brief Return the element type of an array, complex, or vector type. |
| 2634 | * |
| 2635 | * If a type is passed in that is not an array, complex, or vector type, |
| 2636 | * an invalid type is returned. |
| 2637 | */ |
| 2638 | CINDEX_LINKAGE CXType clang_getElementType(CXType T); |
| 2639 | |
| 2640 | /** |
| 2641 | * \brief Return the number of elements of an array or vector type. |
| 2642 | * |
| 2643 | * If a type is passed in that is not an array or vector type, |
| 2644 | * -1 is returned. |
| 2645 | */ |
| 2646 | CINDEX_LINKAGE long long clang_getNumElements(CXType T); |
| 2647 | |
| 2648 | /** |
Argyrios Kyrtzidis | 5f0bfc5 | 2011-09-27 17:44:34 +0000 | [diff] [blame] | 2649 | * \brief Return the element type of an array type. |
| 2650 | * |
| 2651 | * If a non-array type is passed in, an invalid type is returned. |
| 2652 | */ |
| 2653 | CINDEX_LINKAGE CXType clang_getArrayElementType(CXType T); |
| 2654 | |
| 2655 | /** |
| 2656 | * \brief Return the the array size of a constant array. |
| 2657 | * |
| 2658 | * If a non-array type is passed in, -1 is returned. |
| 2659 | */ |
| 2660 | CINDEX_LINKAGE long long clang_getArraySize(CXType T); |
| 2661 | |
| 2662 | /** |
Ted Kremenek | 3064ef9 | 2010-08-27 21:34:58 +0000 | [diff] [blame] | 2663 | * \brief Returns 1 if the base class specified by the cursor with kind |
| 2664 | * CX_CXXBaseSpecifier is virtual. |
| 2665 | */ |
| 2666 | CINDEX_LINKAGE unsigned clang_isVirtualBase(CXCursor); |
| 2667 | |
| 2668 | /** |
| 2669 | * \brief Represents the C++ access control level to a base class for a |
| 2670 | * cursor with kind CX_CXXBaseSpecifier. |
| 2671 | */ |
| 2672 | enum CX_CXXAccessSpecifier { |
| 2673 | CX_CXXInvalidAccessSpecifier, |
| 2674 | CX_CXXPublic, |
| 2675 | CX_CXXProtected, |
| 2676 | CX_CXXPrivate |
| 2677 | }; |
| 2678 | |
| 2679 | /** |
| 2680 | * \brief Returns the access control level for the C++ base specifier |
Argyrios Kyrtzidis | 2dfdb94 | 2011-09-30 17:58:23 +0000 | [diff] [blame] | 2681 | * represented by a cursor with kind CXCursor_CXXBaseSpecifier or |
| 2682 | * CXCursor_AccessSpecifier. |
Ted Kremenek | 3064ef9 | 2010-08-27 21:34:58 +0000 | [diff] [blame] | 2683 | */ |
| 2684 | CINDEX_LINKAGE enum CX_CXXAccessSpecifier clang_getCXXAccessSpecifier(CXCursor); |
| 2685 | |
| 2686 | /** |
Douglas Gregor | 1f60d9e | 2010-09-13 22:52:57 +0000 | [diff] [blame] | 2687 | * \brief Determine the number of overloaded declarations referenced by a |
| 2688 | * \c CXCursor_OverloadedDeclRef cursor. |
| 2689 | * |
| 2690 | * \param cursor The cursor whose overloaded declarations are being queried. |
| 2691 | * |
| 2692 | * \returns The number of overloaded declarations referenced by \c cursor. If it |
| 2693 | * is not a \c CXCursor_OverloadedDeclRef cursor, returns 0. |
| 2694 | */ |
| 2695 | CINDEX_LINKAGE unsigned clang_getNumOverloadedDecls(CXCursor cursor); |
| 2696 | |
| 2697 | /** |
| 2698 | * \brief Retrieve a cursor for one of the overloaded declarations referenced |
| 2699 | * by a \c CXCursor_OverloadedDeclRef cursor. |
| 2700 | * |
| 2701 | * \param cursor The cursor whose overloaded declarations are being queried. |
| 2702 | * |
| 2703 | * \param index The zero-based index into the set of overloaded declarations in |
| 2704 | * the cursor. |
| 2705 | * |
| 2706 | * \returns A cursor representing the declaration referenced by the given |
| 2707 | * \c cursor at the specified \c index. If the cursor does not have an |
| 2708 | * associated set of overloaded declarations, or if the index is out of bounds, |
| 2709 | * returns \c clang_getNullCursor(); |
| 2710 | */ |
| 2711 | CINDEX_LINKAGE CXCursor clang_getOverloadedDecl(CXCursor cursor, |
| 2712 | unsigned index); |
| 2713 | |
| 2714 | /** |
Ted Kremenek | 8e0ac17 | 2010-05-14 21:29:26 +0000 | [diff] [blame] | 2715 | * @} |
| 2716 | */ |
Ted Kremenek | 95f3355 | 2010-08-26 01:42:22 +0000 | [diff] [blame] | 2717 | |
| 2718 | /** |
Ted Kremenek | ad72f4d | 2010-08-27 21:34:51 +0000 | [diff] [blame] | 2719 | * \defgroup CINDEX_ATTRIBUTES Information for attributes |
Ted Kremenek | 95f3355 | 2010-08-26 01:42:22 +0000 | [diff] [blame] | 2720 | * |
| 2721 | * @{ |
| 2722 | */ |
| 2723 | |
| 2724 | |
| 2725 | /** |
| 2726 | * \brief For cursors representing an iboutletcollection attribute, |
| 2727 | * this function returns the collection element type. |
| 2728 | * |
| 2729 | */ |
| 2730 | CINDEX_LINKAGE CXType clang_getIBOutletCollectionType(CXCursor); |
| 2731 | |
| 2732 | /** |
| 2733 | * @} |
| 2734 | */ |
Ted Kremenek | 8e0ac17 | 2010-05-14 21:29:26 +0000 | [diff] [blame] | 2735 | |
| 2736 | /** |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 2737 | * \defgroup CINDEX_CURSOR_TRAVERSAL Traversing the AST with cursors |
| 2738 | * |
| 2739 | * These routines provide the ability to traverse the abstract syntax tree |
| 2740 | * using cursors. |
| 2741 | * |
| 2742 | * @{ |
| 2743 | */ |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 2744 | |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 2745 | /** |
| 2746 | * \brief Describes how the traversal of the children of a particular |
| 2747 | * cursor should proceed after visiting a particular child cursor. |
| 2748 | * |
| 2749 | * A value of this enumeration type should be returned by each |
| 2750 | * \c CXCursorVisitor to indicate how clang_visitChildren() proceed. |
| 2751 | */ |
| 2752 | enum CXChildVisitResult { |
| 2753 | /** |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 2754 | * \brief Terminates the cursor traversal. |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 2755 | */ |
| 2756 | CXChildVisit_Break, |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 2757 | /** |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 2758 | * \brief Continues the cursor traversal with the next sibling of |
| 2759 | * the cursor just visited, without visiting its children. |
| 2760 | */ |
| 2761 | CXChildVisit_Continue, |
| 2762 | /** |
| 2763 | * \brief Recursively traverse the children of this cursor, using |
| 2764 | * the same visitor and client data. |
| 2765 | */ |
| 2766 | CXChildVisit_Recurse |
| 2767 | }; |
| 2768 | |
| 2769 | /** |
| 2770 | * \brief Visitor invoked for each cursor found by a traversal. |
| 2771 | * |
| 2772 | * This visitor function will be invoked for each cursor found by |
| 2773 | * clang_visitCursorChildren(). Its first argument is the cursor being |
| 2774 | * visited, its second argument is the parent visitor for that cursor, |
| 2775 | * and its third argument is the client data provided to |
| 2776 | * clang_visitCursorChildren(). |
| 2777 | * |
| 2778 | * The visitor should return one of the \c CXChildVisitResult values |
| 2779 | * to direct clang_visitCursorChildren(). |
| 2780 | */ |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 2781 | typedef enum CXChildVisitResult (*CXCursorVisitor)(CXCursor cursor, |
| 2782 | CXCursor parent, |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 2783 | CXClientData client_data); |
| 2784 | |
| 2785 | /** |
| 2786 | * \brief Visit the children of a particular cursor. |
| 2787 | * |
| 2788 | * This function visits all the direct children of the given cursor, |
| 2789 | * invoking the given \p visitor function with the cursors of each |
| 2790 | * visited child. The traversal may be recursive, if the visitor returns |
| 2791 | * \c CXChildVisit_Recurse. The traversal may also be ended prematurely, if |
| 2792 | * the visitor returns \c CXChildVisit_Break. |
| 2793 | * |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 2794 | * \param parent the cursor whose child may be visited. All kinds of |
Daniel Dunbar | a57259e | 2010-01-24 04:10:31 +0000 | [diff] [blame] | 2795 | * cursors can be visited, including invalid cursors (which, by |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 2796 | * definition, have no children). |
| 2797 | * |
| 2798 | * \param visitor the visitor function that will be invoked for each |
| 2799 | * child of \p parent. |
| 2800 | * |
| 2801 | * \param client_data pointer data supplied by the client, which will |
| 2802 | * be passed to the visitor each time it is invoked. |
| 2803 | * |
| 2804 | * \returns a non-zero value if the traversal was terminated |
| 2805 | * prematurely by the visitor returning \c CXChildVisit_Break. |
| 2806 | */ |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 2807 | CINDEX_LINKAGE unsigned clang_visitChildren(CXCursor parent, |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 2808 | CXCursorVisitor visitor, |
| 2809 | CXClientData client_data); |
David Chisnall | 3387c65 | 2010-11-03 14:12:26 +0000 | [diff] [blame] | 2810 | #ifdef __has_feature |
| 2811 | # if __has_feature(blocks) |
| 2812 | /** |
| 2813 | * \brief Visitor invoked for each cursor found by a traversal. |
| 2814 | * |
| 2815 | * This visitor block will be invoked for each cursor found by |
| 2816 | * clang_visitChildrenWithBlock(). Its first argument is the cursor being |
| 2817 | * visited, its second argument is the parent visitor for that cursor. |
| 2818 | * |
| 2819 | * The visitor should return one of the \c CXChildVisitResult values |
| 2820 | * to direct clang_visitChildrenWithBlock(). |
| 2821 | */ |
| 2822 | typedef enum CXChildVisitResult |
| 2823 | (^CXCursorVisitorBlock)(CXCursor cursor, CXCursor parent); |
| 2824 | |
| 2825 | /** |
| 2826 | * Visits the children of a cursor using the specified block. Behaves |
| 2827 | * identically to clang_visitChildren() in all other respects. |
| 2828 | */ |
| 2829 | unsigned clang_visitChildrenWithBlock(CXCursor parent, |
| 2830 | CXCursorVisitorBlock block); |
| 2831 | # endif |
| 2832 | #endif |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 2833 | |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 2834 | /** |
| 2835 | * @} |
| 2836 | */ |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 2837 | |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 2838 | /** |
| 2839 | * \defgroup CINDEX_CURSOR_XREF Cross-referencing in the AST |
| 2840 | * |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 2841 | * These routines provide the ability to determine references within and |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 2842 | * across translation units, by providing the names of the entities referenced |
| 2843 | * by cursors, follow reference cursors to the declarations they reference, |
| 2844 | * and associate declarations with their definitions. |
| 2845 | * |
| 2846 | * @{ |
| 2847 | */ |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 2848 | |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 2849 | /** |
| 2850 | * \brief Retrieve a Unified Symbol Resolution (USR) for the entity referenced |
| 2851 | * by the given cursor. |
| 2852 | * |
| 2853 | * A Unified Symbol Resolution (USR) is a string that identifies a particular |
| 2854 | * entity (function, class, variable, etc.) within a program. USRs can be |
| 2855 | * compared across translation units to determine, e.g., when references in |
| 2856 | * one translation refer to an entity defined in another translation unit. |
| 2857 | */ |
| 2858 | CINDEX_LINKAGE CXString clang_getCursorUSR(CXCursor); |
| 2859 | |
| 2860 | /** |
Ted Kremenek | 896b70f | 2010-03-13 02:50:34 +0000 | [diff] [blame] | 2861 | * \brief Construct a USR for a specified Objective-C class. |
| 2862 | */ |
| 2863 | CINDEX_LINKAGE CXString clang_constructUSR_ObjCClass(const char *class_name); |
| 2864 | |
| 2865 | /** |
| 2866 | * \brief Construct a USR for a specified Objective-C category. |
| 2867 | */ |
| 2868 | CINDEX_LINKAGE CXString |
Ted Kremenek | 66ccaec | 2010-03-15 17:38:58 +0000 | [diff] [blame] | 2869 | clang_constructUSR_ObjCCategory(const char *class_name, |
Ted Kremenek | 896b70f | 2010-03-13 02:50:34 +0000 | [diff] [blame] | 2870 | const char *category_name); |
| 2871 | |
| 2872 | /** |
| 2873 | * \brief Construct a USR for a specified Objective-C protocol. |
| 2874 | */ |
| 2875 | CINDEX_LINKAGE CXString |
| 2876 | clang_constructUSR_ObjCProtocol(const char *protocol_name); |
| 2877 | |
| 2878 | |
| 2879 | /** |
| 2880 | * \brief Construct a USR for a specified Objective-C instance variable and |
| 2881 | * the USR for its containing class. |
| 2882 | */ |
| 2883 | CINDEX_LINKAGE CXString clang_constructUSR_ObjCIvar(const char *name, |
| 2884 | CXString classUSR); |
| 2885 | |
| 2886 | /** |
| 2887 | * \brief Construct a USR for a specified Objective-C method and |
| 2888 | * the USR for its containing class. |
| 2889 | */ |
| 2890 | CINDEX_LINKAGE CXString clang_constructUSR_ObjCMethod(const char *name, |
| 2891 | unsigned isInstanceMethod, |
| 2892 | CXString classUSR); |
| 2893 | |
| 2894 | /** |
| 2895 | * \brief Construct a USR for a specified Objective-C property and the USR |
| 2896 | * for its containing class. |
| 2897 | */ |
| 2898 | CINDEX_LINKAGE CXString clang_constructUSR_ObjCProperty(const char *property, |
| 2899 | CXString classUSR); |
| 2900 | |
| 2901 | /** |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 2902 | * \brief Retrieve a name for the entity referenced by this cursor. |
| 2903 | */ |
| 2904 | CINDEX_LINKAGE CXString clang_getCursorSpelling(CXCursor); |
| 2905 | |
Douglas Gregor | 358559d | 2010-10-02 22:49:11 +0000 | [diff] [blame] | 2906 | /** |
| 2907 | * \brief Retrieve the display name for the entity referenced by this cursor. |
| 2908 | * |
| 2909 | * The display name contains extra information that helps identify the cursor, |
| 2910 | * such as the parameters of a function or template or the arguments of a |
| 2911 | * class template specialization. |
| 2912 | */ |
| 2913 | CINDEX_LINKAGE CXString clang_getCursorDisplayName(CXCursor); |
| 2914 | |
Douglas Gregor | c5d1e93 | 2010-01-19 01:20:04 +0000 | [diff] [blame] | 2915 | /** \brief For a cursor that is a reference, retrieve a cursor representing the |
| 2916 | * entity that it references. |
| 2917 | * |
| 2918 | * Reference cursors refer to other entities in the AST. For example, an |
| 2919 | * Objective-C superclass reference cursor refers to an Objective-C class. |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 2920 | * This function produces the cursor for the Objective-C class from the |
Douglas Gregor | c5d1e93 | 2010-01-19 01:20:04 +0000 | [diff] [blame] | 2921 | * cursor for the superclass reference. If the input cursor is a declaration or |
| 2922 | * definition, it returns that declaration or definition unchanged. |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 2923 | * Otherwise, returns the NULL cursor. |
Douglas Gregor | c5d1e93 | 2010-01-19 01:20:04 +0000 | [diff] [blame] | 2924 | */ |
| 2925 | CINDEX_LINKAGE CXCursor clang_getCursorReferenced(CXCursor); |
Douglas Gregor | b699866 | 2010-01-19 19:34:47 +0000 | [diff] [blame] | 2926 | |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 2927 | /** |
Douglas Gregor | b699866 | 2010-01-19 19:34:47 +0000 | [diff] [blame] | 2928 | * \brief For a cursor that is either a reference to or a declaration |
| 2929 | * of some entity, retrieve a cursor that describes the definition of |
| 2930 | * that entity. |
| 2931 | * |
| 2932 | * Some entities can be declared multiple times within a translation |
| 2933 | * unit, but only one of those declarations can also be a |
| 2934 | * definition. For example, given: |
| 2935 | * |
| 2936 | * \code |
| 2937 | * int f(int, int); |
| 2938 | * int g(int x, int y) { return f(x, y); } |
| 2939 | * int f(int a, int b) { return a + b; } |
| 2940 | * int f(int, int); |
| 2941 | * \endcode |
| 2942 | * |
| 2943 | * there are three declarations of the function "f", but only the |
| 2944 | * second one is a definition. The clang_getCursorDefinition() |
| 2945 | * function will take any cursor pointing to a declaration of "f" |
| 2946 | * (the first or fourth lines of the example) or a cursor referenced |
| 2947 | * that uses "f" (the call to "f' inside "g") and will return a |
| 2948 | * declaration cursor pointing to the definition (the second "f" |
| 2949 | * declaration). |
| 2950 | * |
| 2951 | * If given a cursor for which there is no corresponding definition, |
| 2952 | * e.g., because there is no definition of that entity within this |
| 2953 | * translation unit, returns a NULL cursor. |
| 2954 | */ |
| 2955 | CINDEX_LINKAGE CXCursor clang_getCursorDefinition(CXCursor); |
| 2956 | |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 2957 | /** |
Douglas Gregor | b699866 | 2010-01-19 19:34:47 +0000 | [diff] [blame] | 2958 | * \brief Determine whether the declaration pointed to by this cursor |
| 2959 | * is also a definition of that entity. |
| 2960 | */ |
| 2961 | CINDEX_LINKAGE unsigned clang_isCursorDefinition(CXCursor); |
| 2962 | |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 2963 | /** |
Douglas Gregor | 1a9d050 | 2010-11-19 23:44:15 +0000 | [diff] [blame] | 2964 | * \brief Retrieve the canonical cursor corresponding to the given cursor. |
| 2965 | * |
| 2966 | * In the C family of languages, many kinds of entities can be declared several |
| 2967 | * times within a single translation unit. For example, a structure type can |
| 2968 | * be forward-declared (possibly multiple times) and later defined: |
| 2969 | * |
| 2970 | * \code |
| 2971 | * struct X; |
| 2972 | * struct X; |
| 2973 | * struct X { |
| 2974 | * int member; |
| 2975 | * }; |
| 2976 | * \endcode |
| 2977 | * |
| 2978 | * The declarations and the definition of \c X are represented by three |
| 2979 | * different cursors, all of which are declarations of the same underlying |
| 2980 | * entity. One of these cursor is considered the "canonical" cursor, which |
| 2981 | * is effectively the representative for the underlying entity. One can |
| 2982 | * determine if two cursors are declarations of the same underlying entity by |
| 2983 | * comparing their canonical cursors. |
| 2984 | * |
| 2985 | * \returns The canonical cursor for the entity referred to by the given cursor. |
| 2986 | */ |
| 2987 | CINDEX_LINKAGE CXCursor clang_getCanonicalCursor(CXCursor); |
| 2988 | |
| 2989 | /** |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 2990 | * @} |
| 2991 | */ |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 2992 | |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 2993 | /** |
Ted Kremenek | 9ada39a | 2010-05-17 20:06:56 +0000 | [diff] [blame] | 2994 | * \defgroup CINDEX_CPP C++ AST introspection |
| 2995 | * |
| 2996 | * The routines in this group provide access information in the ASTs specific |
| 2997 | * to C++ language features. |
| 2998 | * |
| 2999 | * @{ |
| 3000 | */ |
| 3001 | |
| 3002 | /** |
Douglas Gregor | 49f6f54 | 2010-08-31 22:12:17 +0000 | [diff] [blame] | 3003 | * \brief Determine if a C++ member function or member function template is |
| 3004 | * declared 'static'. |
Ted Kremenek | 9ada39a | 2010-05-17 20:06:56 +0000 | [diff] [blame] | 3005 | */ |
| 3006 | CINDEX_LINKAGE unsigned clang_CXXMethod_isStatic(CXCursor C); |
| 3007 | |
| 3008 | /** |
Douglas Gregor | 211924b | 2011-05-12 15:17:24 +0000 | [diff] [blame] | 3009 | * \brief Determine if a C++ member function or member function template is |
| 3010 | * explicitly declared 'virtual' or if it overrides a virtual method from |
| 3011 | * one of the base classes. |
| 3012 | */ |
| 3013 | CINDEX_LINKAGE unsigned clang_CXXMethod_isVirtual(CXCursor C); |
| 3014 | |
| 3015 | /** |
Douglas Gregor | 49f6f54 | 2010-08-31 22:12:17 +0000 | [diff] [blame] | 3016 | * \brief Given a cursor that represents a template, determine |
| 3017 | * the cursor kind of the specializations would be generated by instantiating |
| 3018 | * the template. |
| 3019 | * |
| 3020 | * This routine can be used to determine what flavor of function template, |
| 3021 | * class template, or class template partial specialization is stored in the |
| 3022 | * cursor. For example, it can describe whether a class template cursor is |
| 3023 | * declared with "struct", "class" or "union". |
| 3024 | * |
| 3025 | * \param C The cursor to query. This cursor should represent a template |
| 3026 | * declaration. |
| 3027 | * |
| 3028 | * \returns The cursor kind of the specializations that would be generated |
| 3029 | * by instantiating the template \p C. If \p C is not a template, returns |
| 3030 | * \c CXCursor_NoDeclFound. |
| 3031 | */ |
| 3032 | CINDEX_LINKAGE enum CXCursorKind clang_getTemplateCursorKind(CXCursor C); |
| 3033 | |
| 3034 | /** |
Douglas Gregor | e0329ac | 2010-09-02 00:07:54 +0000 | [diff] [blame] | 3035 | * \brief Given a cursor that may represent a specialization or instantiation |
| 3036 | * of a template, retrieve the cursor that represents the template that it |
| 3037 | * specializes or from which it was instantiated. |
| 3038 | * |
| 3039 | * This routine determines the template involved both for explicit |
| 3040 | * specializations of templates and for implicit instantiations of the template, |
| 3041 | * both of which are referred to as "specializations". For a class template |
| 3042 | * specialization (e.g., \c std::vector<bool>), this routine will return |
| 3043 | * either the primary template (\c std::vector) or, if the specialization was |
| 3044 | * instantiated from a class template partial specialization, the class template |
| 3045 | * partial specialization. For a class template partial specialization and a |
| 3046 | * function template specialization (including instantiations), this |
| 3047 | * this routine will return the specialized template. |
| 3048 | * |
| 3049 | * For members of a class template (e.g., member functions, member classes, or |
| 3050 | * static data members), returns the specialized or instantiated member. |
| 3051 | * Although not strictly "templates" in the C++ language, members of class |
| 3052 | * templates have the same notions of specializations and instantiations that |
| 3053 | * templates do, so this routine treats them similarly. |
| 3054 | * |
| 3055 | * \param C A cursor that may be a specialization of a template or a member |
| 3056 | * of a template. |
| 3057 | * |
| 3058 | * \returns If the given cursor is a specialization or instantiation of a |
| 3059 | * template or a member thereof, the template or member that it specializes or |
| 3060 | * from which it was instantiated. Otherwise, returns a NULL cursor. |
| 3061 | */ |
| 3062 | CINDEX_LINKAGE CXCursor clang_getSpecializedCursorTemplate(CXCursor C); |
Douglas Gregor | 430d7a1 | 2011-07-25 17:48:11 +0000 | [diff] [blame] | 3063 | |
| 3064 | /** |
| 3065 | * \brief Given a cursor that references something else, return the source range |
| 3066 | * covering that reference. |
| 3067 | * |
| 3068 | * \param C A cursor pointing to a member reference, a declaration reference, or |
| 3069 | * an operator call. |
| 3070 | * \param NameFlags A bitset with three independent flags: |
| 3071 | * CXNameRange_WantQualifier, CXNameRange_WantTemplateArgs, and |
| 3072 | * CXNameRange_WantSinglePiece. |
| 3073 | * \param PieceIndex For contiguous names or when passing the flag |
| 3074 | * CXNameRange_WantSinglePiece, only one piece with index 0 is |
| 3075 | * available. When the CXNameRange_WantSinglePiece flag is not passed for a |
| 3076 | * non-contiguous names, this index can be used to retreive the individual |
| 3077 | * pieces of the name. See also CXNameRange_WantSinglePiece. |
| 3078 | * |
| 3079 | * \returns The piece of the name pointed to by the given cursor. If there is no |
| 3080 | * name, or if the PieceIndex is out-of-range, a null-cursor will be returned. |
| 3081 | */ |
Francois Pichet | 48a8d14 | 2011-07-25 22:00:44 +0000 | [diff] [blame] | 3082 | CINDEX_LINKAGE CXSourceRange clang_getCursorReferenceNameRange(CXCursor C, |
| 3083 | unsigned NameFlags, |
Douglas Gregor | 430d7a1 | 2011-07-25 17:48:11 +0000 | [diff] [blame] | 3084 | unsigned PieceIndex); |
| 3085 | |
| 3086 | enum CXNameRefFlags { |
| 3087 | /** |
| 3088 | * \brief Include the nested-name-specifier, e.g. Foo:: in x.Foo::y, in the |
| 3089 | * range. |
| 3090 | */ |
| 3091 | CXNameRange_WantQualifier = 0x1, |
| 3092 | |
| 3093 | /** |
| 3094 | * \brief Include the explicit template arguments, e.g. <int> in x.f<int>, in |
| 3095 | * the range. |
| 3096 | */ |
| 3097 | CXNameRange_WantTemplateArgs = 0x2, |
| 3098 | |
| 3099 | /** |
| 3100 | * \brief If the name is non-contiguous, return the full spanning range. |
| 3101 | * |
| 3102 | * Non-contiguous names occur in Objective-C when a selector with two or more |
| 3103 | * parameters is used, or in C++ when using an operator: |
| 3104 | * \code |
| 3105 | * [object doSomething:here withValue:there]; // ObjC |
| 3106 | * return some_vector[1]; // C++ |
| 3107 | * \endcode |
| 3108 | */ |
| 3109 | CXNameRange_WantSinglePiece = 0x4 |
| 3110 | }; |
Douglas Gregor | e0329ac | 2010-09-02 00:07:54 +0000 | [diff] [blame] | 3111 | |
| 3112 | /** |
Ted Kremenek | 9ada39a | 2010-05-17 20:06:56 +0000 | [diff] [blame] | 3113 | * @} |
| 3114 | */ |
| 3115 | |
| 3116 | /** |
Douglas Gregor | 0045e9f | 2010-01-26 18:31:56 +0000 | [diff] [blame] | 3117 | * \defgroup CINDEX_LEX Token extraction and manipulation |
| 3118 | * |
| 3119 | * The routines in this group provide access to the tokens within a |
| 3120 | * translation unit, along with a semantic mapping of those tokens to |
| 3121 | * their corresponding cursors. |
Douglas Gregor | fc8ea23 | 2010-01-26 17:06:03 +0000 | [diff] [blame] | 3122 | * |
| 3123 | * @{ |
| 3124 | */ |
| 3125 | |
| 3126 | /** |
| 3127 | * \brief Describes a kind of token. |
| 3128 | */ |
| 3129 | typedef enum CXTokenKind { |
| 3130 | /** |
| 3131 | * \brief A token that contains some kind of punctuation. |
| 3132 | */ |
| 3133 | CXToken_Punctuation, |
Ted Kremenek | 896b70f | 2010-03-13 02:50:34 +0000 | [diff] [blame] | 3134 | |
Douglas Gregor | fc8ea23 | 2010-01-26 17:06:03 +0000 | [diff] [blame] | 3135 | /** |
Douglas Gregor | 0045e9f | 2010-01-26 18:31:56 +0000 | [diff] [blame] | 3136 | * \brief A language keyword. |
Douglas Gregor | fc8ea23 | 2010-01-26 17:06:03 +0000 | [diff] [blame] | 3137 | */ |
| 3138 | CXToken_Keyword, |
Ted Kremenek | 896b70f | 2010-03-13 02:50:34 +0000 | [diff] [blame] | 3139 | |
Douglas Gregor | fc8ea23 | 2010-01-26 17:06:03 +0000 | [diff] [blame] | 3140 | /** |
| 3141 | * \brief An identifier (that is not a keyword). |
| 3142 | */ |
| 3143 | CXToken_Identifier, |
Ted Kremenek | 896b70f | 2010-03-13 02:50:34 +0000 | [diff] [blame] | 3144 | |
Douglas Gregor | fc8ea23 | 2010-01-26 17:06:03 +0000 | [diff] [blame] | 3145 | /** |
| 3146 | * \brief A numeric, string, or character literal. |
| 3147 | */ |
| 3148 | CXToken_Literal, |
Ted Kremenek | 896b70f | 2010-03-13 02:50:34 +0000 | [diff] [blame] | 3149 | |
Douglas Gregor | fc8ea23 | 2010-01-26 17:06:03 +0000 | [diff] [blame] | 3150 | /** |
| 3151 | * \brief A comment. |
| 3152 | */ |
| 3153 | CXToken_Comment |
| 3154 | } CXTokenKind; |
| 3155 | |
| 3156 | /** |
| 3157 | * \brief Describes a single preprocessing token. |
| 3158 | */ |
| 3159 | typedef struct { |
| 3160 | unsigned int_data[4]; |
| 3161 | void *ptr_data; |
| 3162 | } CXToken; |
| 3163 | |
| 3164 | /** |
| 3165 | * \brief Determine the kind of the given token. |
| 3166 | */ |
| 3167 | CINDEX_LINKAGE CXTokenKind clang_getTokenKind(CXToken); |
Ted Kremenek | 896b70f | 2010-03-13 02:50:34 +0000 | [diff] [blame] | 3168 | |
Douglas Gregor | fc8ea23 | 2010-01-26 17:06:03 +0000 | [diff] [blame] | 3169 | /** |
| 3170 | * \brief Determine the spelling of the given token. |
| 3171 | * |
| 3172 | * The spelling of a token is the textual representation of that token, e.g., |
| 3173 | * the text of an identifier or keyword. |
| 3174 | */ |
| 3175 | CINDEX_LINKAGE CXString clang_getTokenSpelling(CXTranslationUnit, CXToken); |
Ted Kremenek | 896b70f | 2010-03-13 02:50:34 +0000 | [diff] [blame] | 3176 | |
Douglas Gregor | fc8ea23 | 2010-01-26 17:06:03 +0000 | [diff] [blame] | 3177 | /** |
| 3178 | * \brief Retrieve the source location of the given token. |
| 3179 | */ |
Ted Kremenek | 896b70f | 2010-03-13 02:50:34 +0000 | [diff] [blame] | 3180 | CINDEX_LINKAGE CXSourceLocation clang_getTokenLocation(CXTranslationUnit, |
Douglas Gregor | fc8ea23 | 2010-01-26 17:06:03 +0000 | [diff] [blame] | 3181 | CXToken); |
Ted Kremenek | 896b70f | 2010-03-13 02:50:34 +0000 | [diff] [blame] | 3182 | |
Douglas Gregor | fc8ea23 | 2010-01-26 17:06:03 +0000 | [diff] [blame] | 3183 | /** |
| 3184 | * \brief Retrieve a source range that covers the given token. |
| 3185 | */ |
| 3186 | CINDEX_LINKAGE CXSourceRange clang_getTokenExtent(CXTranslationUnit, CXToken); |
| 3187 | |
| 3188 | /** |
| 3189 | * \brief Tokenize the source code described by the given range into raw |
| 3190 | * lexical tokens. |
| 3191 | * |
| 3192 | * \param TU the translation unit whose text is being tokenized. |
| 3193 | * |
| 3194 | * \param Range the source range in which text should be tokenized. All of the |
| 3195 | * tokens produced by tokenization will fall within this source range, |
| 3196 | * |
| 3197 | * \param Tokens this pointer will be set to point to the array of tokens |
| 3198 | * that occur within the given source range. The returned pointer must be |
| 3199 | * freed with clang_disposeTokens() before the translation unit is destroyed. |
| 3200 | * |
| 3201 | * \param NumTokens will be set to the number of tokens in the \c *Tokens |
| 3202 | * array. |
| 3203 | * |
| 3204 | */ |
| 3205 | CINDEX_LINKAGE void clang_tokenize(CXTranslationUnit TU, CXSourceRange Range, |
| 3206 | CXToken **Tokens, unsigned *NumTokens); |
Ted Kremenek | 896b70f | 2010-03-13 02:50:34 +0000 | [diff] [blame] | 3207 | |
Douglas Gregor | fc8ea23 | 2010-01-26 17:06:03 +0000 | [diff] [blame] | 3208 | /** |
| 3209 | * \brief Annotate the given set of tokens by providing cursors for each token |
| 3210 | * that can be mapped to a specific entity within the abstract syntax tree. |
| 3211 | * |
Douglas Gregor | 0045e9f | 2010-01-26 18:31:56 +0000 | [diff] [blame] | 3212 | * This token-annotation routine is equivalent to invoking |
| 3213 | * clang_getCursor() for the source locations of each of the |
| 3214 | * tokens. The cursors provided are filtered, so that only those |
| 3215 | * cursors that have a direct correspondence to the token are |
| 3216 | * accepted. For example, given a function call \c f(x), |
| 3217 | * clang_getCursor() would provide the following cursors: |
| 3218 | * |
| 3219 | * * when the cursor is over the 'f', a DeclRefExpr cursor referring to 'f'. |
| 3220 | * * when the cursor is over the '(' or the ')', a CallExpr referring to 'f'. |
| 3221 | * * when the cursor is over the 'x', a DeclRefExpr cursor referring to 'x'. |
| 3222 | * |
| 3223 | * Only the first and last of these cursors will occur within the |
| 3224 | * annotate, since the tokens "f" and "x' directly refer to a function |
| 3225 | * and a variable, respectively, but the parentheses are just a small |
| 3226 | * part of the full syntax of the function call expression, which is |
| 3227 | * not provided as an annotation. |
Douglas Gregor | fc8ea23 | 2010-01-26 17:06:03 +0000 | [diff] [blame] | 3228 | * |
| 3229 | * \param TU the translation unit that owns the given tokens. |
| 3230 | * |
| 3231 | * \param Tokens the set of tokens to annotate. |
| 3232 | * |
| 3233 | * \param NumTokens the number of tokens in \p Tokens. |
| 3234 | * |
| 3235 | * \param Cursors an array of \p NumTokens cursors, whose contents will be |
| 3236 | * replaced with the cursors corresponding to each token. |
| 3237 | */ |
| 3238 | CINDEX_LINKAGE void clang_annotateTokens(CXTranslationUnit TU, |
| 3239 | CXToken *Tokens, unsigned NumTokens, |
| 3240 | CXCursor *Cursors); |
Ted Kremenek | 896b70f | 2010-03-13 02:50:34 +0000 | [diff] [blame] | 3241 | |
Douglas Gregor | fc8ea23 | 2010-01-26 17:06:03 +0000 | [diff] [blame] | 3242 | /** |
| 3243 | * \brief Free the given set of tokens. |
| 3244 | */ |
Ted Kremenek | 896b70f | 2010-03-13 02:50:34 +0000 | [diff] [blame] | 3245 | CINDEX_LINKAGE void clang_disposeTokens(CXTranslationUnit TU, |
Douglas Gregor | fc8ea23 | 2010-01-26 17:06:03 +0000 | [diff] [blame] | 3246 | CXToken *Tokens, unsigned NumTokens); |
Ted Kremenek | 896b70f | 2010-03-13 02:50:34 +0000 | [diff] [blame] | 3247 | |
Douglas Gregor | fc8ea23 | 2010-01-26 17:06:03 +0000 | [diff] [blame] | 3248 | /** |
| 3249 | * @} |
| 3250 | */ |
Ted Kremenek | 896b70f | 2010-03-13 02:50:34 +0000 | [diff] [blame] | 3251 | |
Douglas Gregor | fc8ea23 | 2010-01-26 17:06:03 +0000 | [diff] [blame] | 3252 | /** |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 3253 | * \defgroup CINDEX_DEBUG Debugging facilities |
| 3254 | * |
| 3255 | * These routines are used for testing and debugging, only, and should not |
| 3256 | * be relied upon. |
| 3257 | * |
| 3258 | * @{ |
| 3259 | */ |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 3260 | |
Steve Naroff | 4ade6d6 | 2009-09-23 17:52:52 +0000 | [diff] [blame] | 3261 | /* for debug/testing */ |
Ted Kremenek | e68fff6 | 2010-02-17 00:41:32 +0000 | [diff] [blame] | 3262 | CINDEX_LINKAGE CXString clang_getCursorKindSpelling(enum CXCursorKind Kind); |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 3263 | CINDEX_LINKAGE void clang_getDefinitionSpellingAndExtent(CXCursor, |
| 3264 | const char **startBuf, |
Steve Naroff | 4ade6d6 | 2009-09-23 17:52:52 +0000 | [diff] [blame] | 3265 | const char **endBuf, |
| 3266 | unsigned *startLine, |
| 3267 | unsigned *startColumn, |
| 3268 | unsigned *endLine, |
| 3269 | unsigned *endColumn); |
Douglas Gregor | 0a812cf | 2010-02-18 23:07:20 +0000 | [diff] [blame] | 3270 | CINDEX_LINKAGE void clang_enableStackTraces(void); |
Daniel Dunbar | 995aaf9 | 2010-11-04 01:26:29 +0000 | [diff] [blame] | 3271 | CINDEX_LINKAGE void clang_executeOnThread(void (*fn)(void*), void *user_data, |
| 3272 | unsigned stack_size); |
| 3273 | |
Douglas Gregor | 0c8296d | 2009-11-07 00:00:49 +0000 | [diff] [blame] | 3274 | /** |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 3275 | * @} |
| 3276 | */ |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 3277 | |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 3278 | /** |
| 3279 | * \defgroup CINDEX_CODE_COMPLET Code completion |
| 3280 | * |
| 3281 | * Code completion involves taking an (incomplete) source file, along with |
| 3282 | * knowledge of where the user is actively editing that file, and suggesting |
| 3283 | * syntactically- and semantically-valid constructs that the user might want to |
| 3284 | * use at that particular point in the source code. These data structures and |
| 3285 | * routines provide support for code completion. |
| 3286 | * |
| 3287 | * @{ |
| 3288 | */ |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 3289 | |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 3290 | /** |
Douglas Gregor | 0c8296d | 2009-11-07 00:00:49 +0000 | [diff] [blame] | 3291 | * \brief A semantic string that describes a code-completion result. |
| 3292 | * |
| 3293 | * A semantic string that describes the formatting of a code-completion |
| 3294 | * result as a single "template" of text that should be inserted into the |
| 3295 | * source buffer when a particular code-completion result is selected. |
| 3296 | * Each semantic string is made up of some number of "chunks", each of which |
| 3297 | * contains some text along with a description of what that text means, e.g., |
| 3298 | * the name of the entity being referenced, whether the text chunk is part of |
| 3299 | * the template, or whether it is a "placeholder" that the user should replace |
| 3300 | * with actual code,of a specific kind. See \c CXCompletionChunkKind for a |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 3301 | * description of the different kinds of chunks. |
Douglas Gregor | 0c8296d | 2009-11-07 00:00:49 +0000 | [diff] [blame] | 3302 | */ |
| 3303 | typedef void *CXCompletionString; |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 3304 | |
Douglas Gregor | 0c8296d | 2009-11-07 00:00:49 +0000 | [diff] [blame] | 3305 | /** |
| 3306 | * \brief A single result of code completion. |
| 3307 | */ |
| 3308 | typedef struct { |
| 3309 | /** |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 3310 | * \brief The kind of entity that this completion refers to. |
Douglas Gregor | 0c8296d | 2009-11-07 00:00:49 +0000 | [diff] [blame] | 3311 | * |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 3312 | * 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] | 3313 | * *Decl cursor kinds), describing the entity that the completion is |
| 3314 | * referring to. |
| 3315 | * |
| 3316 | * \todo In the future, we would like to provide a full cursor, to allow |
| 3317 | * the client to extract additional information from declaration. |
| 3318 | */ |
| 3319 | enum CXCursorKind CursorKind; |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 3320 | |
| 3321 | /** |
Douglas Gregor | 0c8296d | 2009-11-07 00:00:49 +0000 | [diff] [blame] | 3322 | * \brief The code-completion string that describes how to insert this |
| 3323 | * code-completion result into the editing buffer. |
| 3324 | */ |
| 3325 | CXCompletionString CompletionString; |
| 3326 | } CXCompletionResult; |
| 3327 | |
| 3328 | /** |
| 3329 | * \brief Describes a single piece of text within a code-completion string. |
| 3330 | * |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 3331 | * Each "chunk" within a code-completion string (\c CXCompletionString) is |
| 3332 | * 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] | 3333 | * should be interpreted by the client or is another completion string. |
| 3334 | */ |
| 3335 | enum CXCompletionChunkKind { |
| 3336 | /** |
| 3337 | * \brief A code-completion string that describes "optional" text that |
| 3338 | * could be a part of the template (but is not required). |
| 3339 | * |
| 3340 | * 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] | 3341 | * string for its representation, which is accessible via |
Douglas Gregor | 0c8296d | 2009-11-07 00:00:49 +0000 | [diff] [blame] | 3342 | * \c clang_getCompletionChunkCompletionString(). The code-completion string |
| 3343 | * describes an additional part of the template that is completely optional. |
| 3344 | * For example, optional chunks can be used to describe the placeholders for |
| 3345 | * arguments that match up with defaulted function parameters, e.g. given: |
| 3346 | * |
| 3347 | * \code |
| 3348 | * void f(int x, float y = 3.14, double z = 2.71828); |
| 3349 | * \endcode |
| 3350 | * |
| 3351 | * The code-completion string for this function would contain: |
| 3352 | * - a TypedText chunk for "f". |
| 3353 | * - a LeftParen chunk for "(". |
| 3354 | * - a Placeholder chunk for "int x" |
| 3355 | * - an Optional chunk containing the remaining defaulted arguments, e.g., |
| 3356 | * - a Comma chunk for "," |
Daniel Dunbar | 7157018 | 2010-02-17 08:07:44 +0000 | [diff] [blame] | 3357 | * - a Placeholder chunk for "float y" |
Douglas Gregor | 0c8296d | 2009-11-07 00:00:49 +0000 | [diff] [blame] | 3358 | * - an Optional chunk containing the last defaulted argument: |
| 3359 | * - a Comma chunk for "," |
| 3360 | * - a Placeholder chunk for "double z" |
| 3361 | * - a RightParen chunk for ")" |
| 3362 | * |
Daniel Dunbar | 7157018 | 2010-02-17 08:07:44 +0000 | [diff] [blame] | 3363 | * There are many ways to handle Optional chunks. Two simple approaches are: |
Douglas Gregor | 0c8296d | 2009-11-07 00:00:49 +0000 | [diff] [blame] | 3364 | * - Completely ignore optional chunks, in which case the template for the |
| 3365 | * function "f" would only include the first parameter ("int x"). |
| 3366 | * - Fully expand all optional chunks, in which case the template for the |
| 3367 | * function "f" would have all of the parameters. |
| 3368 | */ |
| 3369 | CXCompletionChunk_Optional, |
| 3370 | /** |
| 3371 | * \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] | 3372 | * code-completion result. |
Douglas Gregor | 0c8296d | 2009-11-07 00:00:49 +0000 | [diff] [blame] | 3373 | * |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 3374 | * There will be exactly one "typed text" chunk in a semantic string, which |
| 3375 | * 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] | 3376 | * declaration that could be used at the current code point. Clients are |
| 3377 | * expected to filter the code-completion results based on the text in this |
| 3378 | * chunk. |
| 3379 | */ |
| 3380 | CXCompletionChunk_TypedText, |
| 3381 | /** |
| 3382 | * \brief Text that should be inserted as part of a code-completion result. |
| 3383 | * |
| 3384 | * A "text" chunk represents text that is part of the template to be |
| 3385 | * inserted into user code should this particular code-completion result |
| 3386 | * be selected. |
| 3387 | */ |
| 3388 | CXCompletionChunk_Text, |
| 3389 | /** |
| 3390 | * \brief Placeholder text that should be replaced by the user. |
| 3391 | * |
| 3392 | * A "placeholder" chunk marks a place where the user should insert text |
| 3393 | * into the code-completion template. For example, placeholders might mark |
| 3394 | * the function parameters for a function declaration, to indicate that the |
| 3395 | * user should provide arguments for each of those parameters. The actual |
| 3396 | * text in a placeholder is a suggestion for the text to display before |
| 3397 | * the user replaces the placeholder with real code. |
| 3398 | */ |
| 3399 | CXCompletionChunk_Placeholder, |
| 3400 | /** |
| 3401 | * \brief Informative text that should be displayed but never inserted as |
| 3402 | * part of the template. |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 3403 | * |
Douglas Gregor | 0c8296d | 2009-11-07 00:00:49 +0000 | [diff] [blame] | 3404 | * An "informative" chunk contains annotations that can be displayed to |
| 3405 | * help the user decide whether a particular code-completion result is the |
| 3406 | * right option, but which is not part of the actual template to be inserted |
| 3407 | * by code completion. |
| 3408 | */ |
| 3409 | CXCompletionChunk_Informative, |
| 3410 | /** |
| 3411 | * \brief Text that describes the current parameter when code-completion is |
| 3412 | * referring to function call, message send, or template specialization. |
| 3413 | * |
| 3414 | * A "current parameter" chunk occurs when code-completion is providing |
| 3415 | * information about a parameter corresponding to the argument at the |
| 3416 | * code-completion point. For example, given a function |
| 3417 | * |
| 3418 | * \code |
| 3419 | * int add(int x, int y); |
| 3420 | * \endcode |
| 3421 | * |
| 3422 | * and the source code \c add(, where the code-completion point is after the |
| 3423 | * "(", the code-completion string will contain a "current parameter" chunk |
| 3424 | * for "int x", indicating that the current argument will initialize that |
| 3425 | * parameter. After typing further, to \c add(17, (where the code-completion |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 3426 | * point is after the ","), the code-completion string will contain a |
Douglas Gregor | 0c8296d | 2009-11-07 00:00:49 +0000 | [diff] [blame] | 3427 | * "current paremeter" chunk to "int y". |
| 3428 | */ |
| 3429 | CXCompletionChunk_CurrentParameter, |
| 3430 | /** |
| 3431 | * \brief A left parenthesis ('('), used to initiate a function call or |
| 3432 | * signal the beginning of a function parameter list. |
| 3433 | */ |
| 3434 | CXCompletionChunk_LeftParen, |
| 3435 | /** |
| 3436 | * \brief A right parenthesis (')'), used to finish a function call or |
| 3437 | * signal the end of a function parameter list. |
| 3438 | */ |
| 3439 | CXCompletionChunk_RightParen, |
| 3440 | /** |
| 3441 | * \brief A left bracket ('['). |
| 3442 | */ |
| 3443 | CXCompletionChunk_LeftBracket, |
| 3444 | /** |
| 3445 | * \brief A right bracket (']'). |
| 3446 | */ |
| 3447 | CXCompletionChunk_RightBracket, |
| 3448 | /** |
| 3449 | * \brief A left brace ('{'). |
| 3450 | */ |
| 3451 | CXCompletionChunk_LeftBrace, |
| 3452 | /** |
| 3453 | * \brief A right brace ('}'). |
| 3454 | */ |
| 3455 | CXCompletionChunk_RightBrace, |
| 3456 | /** |
| 3457 | * \brief A left angle bracket ('<'). |
| 3458 | */ |
| 3459 | CXCompletionChunk_LeftAngle, |
| 3460 | /** |
| 3461 | * \brief A right angle bracket ('>'). |
| 3462 | */ |
| 3463 | CXCompletionChunk_RightAngle, |
| 3464 | /** |
| 3465 | * \brief A comma separator (','). |
| 3466 | */ |
Douglas Gregor | ff5ce6e | 2009-12-18 18:53:37 +0000 | [diff] [blame] | 3467 | CXCompletionChunk_Comma, |
| 3468 | /** |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 3469 | * \brief Text that specifies the result type of a given result. |
Douglas Gregor | ff5ce6e | 2009-12-18 18:53:37 +0000 | [diff] [blame] | 3470 | * |
| 3471 | * 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] | 3472 | * 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] | 3473 | * expression using the given completion string would have. |
| 3474 | */ |
Douglas Gregor | 01dfea0 | 2010-01-10 23:08:15 +0000 | [diff] [blame] | 3475 | CXCompletionChunk_ResultType, |
| 3476 | /** |
| 3477 | * \brief A colon (':'). |
| 3478 | */ |
| 3479 | CXCompletionChunk_Colon, |
| 3480 | /** |
| 3481 | * \brief A semicolon (';'). |
| 3482 | */ |
| 3483 | CXCompletionChunk_SemiColon, |
| 3484 | /** |
| 3485 | * \brief An '=' sign. |
| 3486 | */ |
| 3487 | CXCompletionChunk_Equal, |
| 3488 | /** |
| 3489 | * Horizontal space (' '). |
| 3490 | */ |
| 3491 | CXCompletionChunk_HorizontalSpace, |
| 3492 | /** |
| 3493 | * Vertical space ('\n'), after which it is generally a good idea to |
| 3494 | * perform indentation. |
| 3495 | */ |
| 3496 | CXCompletionChunk_VerticalSpace |
Douglas Gregor | 0c8296d | 2009-11-07 00:00:49 +0000 | [diff] [blame] | 3497 | }; |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 3498 | |
Douglas Gregor | 0c8296d | 2009-11-07 00:00:49 +0000 | [diff] [blame] | 3499 | /** |
| 3500 | * \brief Determine the kind of a particular chunk within a completion string. |
| 3501 | * |
| 3502 | * \param completion_string the completion string to query. |
| 3503 | * |
| 3504 | * \param chunk_number the 0-based index of the chunk in the completion string. |
| 3505 | * |
| 3506 | * \returns the kind of the chunk at the index \c chunk_number. |
| 3507 | */ |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 3508 | CINDEX_LINKAGE enum CXCompletionChunkKind |
Douglas Gregor | 0c8296d | 2009-11-07 00:00:49 +0000 | [diff] [blame] | 3509 | clang_getCompletionChunkKind(CXCompletionString completion_string, |
| 3510 | unsigned chunk_number); |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 3511 | |
Douglas Gregor | 0c8296d | 2009-11-07 00:00:49 +0000 | [diff] [blame] | 3512 | /** |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 3513 | * \brief Retrieve the text associated with a particular chunk within a |
Douglas Gregor | 0c8296d | 2009-11-07 00:00:49 +0000 | [diff] [blame] | 3514 | * completion string. |
| 3515 | * |
| 3516 | * \param completion_string the completion string to query. |
| 3517 | * |
| 3518 | * \param chunk_number the 0-based index of the chunk in the completion string. |
| 3519 | * |
| 3520 | * \returns the text associated with the chunk at index \c chunk_number. |
| 3521 | */ |
Ted Kremenek | 2ef6f8f | 2010-02-17 01:42:24 +0000 | [diff] [blame] | 3522 | CINDEX_LINKAGE CXString |
Douglas Gregor | 0c8296d | 2009-11-07 00:00:49 +0000 | [diff] [blame] | 3523 | clang_getCompletionChunkText(CXCompletionString completion_string, |
| 3524 | unsigned chunk_number); |
| 3525 | |
| 3526 | /** |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 3527 | * \brief Retrieve the completion string associated with a particular chunk |
Douglas Gregor | 0c8296d | 2009-11-07 00:00:49 +0000 | [diff] [blame] | 3528 | * within a completion string. |
| 3529 | * |
| 3530 | * \param completion_string the completion string to query. |
| 3531 | * |
| 3532 | * \param chunk_number the 0-based index of the chunk in the completion string. |
| 3533 | * |
| 3534 | * \returns the completion string associated with the chunk at index |
Erik Verbruggen | 6164ea1 | 2011-10-14 15:31:08 +0000 | [diff] [blame] | 3535 | * \c chunk_number. |
Douglas Gregor | 0c8296d | 2009-11-07 00:00:49 +0000 | [diff] [blame] | 3536 | */ |
| 3537 | CINDEX_LINKAGE CXCompletionString |
| 3538 | clang_getCompletionChunkCompletionString(CXCompletionString completion_string, |
| 3539 | unsigned chunk_number); |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 3540 | |
Douglas Gregor | 0c8296d | 2009-11-07 00:00:49 +0000 | [diff] [blame] | 3541 | /** |
| 3542 | * \brief Retrieve the number of chunks in the given code-completion string. |
| 3543 | */ |
| 3544 | CINDEX_LINKAGE unsigned |
| 3545 | clang_getNumCompletionChunks(CXCompletionString completion_string); |
| 3546 | |
| 3547 | /** |
Douglas Gregor | 12e1313 | 2010-05-26 22:00:08 +0000 | [diff] [blame] | 3548 | * \brief Determine the priority of this code completion. |
| 3549 | * |
| 3550 | * The priority of a code completion indicates how likely it is that this |
| 3551 | * particular completion is the completion that the user will select. The |
| 3552 | * priority is selected by various internal heuristics. |
| 3553 | * |
| 3554 | * \param completion_string The completion string to query. |
| 3555 | * |
| 3556 | * \returns The priority of this completion string. Smaller values indicate |
| 3557 | * higher-priority (more likely) completions. |
| 3558 | */ |
| 3559 | CINDEX_LINKAGE unsigned |
| 3560 | clang_getCompletionPriority(CXCompletionString completion_string); |
| 3561 | |
| 3562 | /** |
Douglas Gregor | 58ddb60 | 2010-08-23 23:00:57 +0000 | [diff] [blame] | 3563 | * \brief Determine the availability of the entity that this code-completion |
| 3564 | * string refers to. |
| 3565 | * |
| 3566 | * \param completion_string The completion string to query. |
| 3567 | * |
| 3568 | * \returns The availability of the completion string. |
| 3569 | */ |
| 3570 | CINDEX_LINKAGE enum CXAvailabilityKind |
| 3571 | clang_getCompletionAvailability(CXCompletionString completion_string); |
| 3572 | |
| 3573 | /** |
Erik Verbruggen | 6164ea1 | 2011-10-14 15:31:08 +0000 | [diff] [blame] | 3574 | * \brief Retrieve the number of annotations associated with the given |
| 3575 | * completion string. |
| 3576 | * |
| 3577 | * \param completion_string the completion string to query. |
| 3578 | * |
| 3579 | * \returns the number of annotations associated with the given completion |
| 3580 | * string. |
| 3581 | */ |
| 3582 | CINDEX_LINKAGE unsigned |
| 3583 | clang_getCompletionNumAnnotations(CXCompletionString completion_string); |
| 3584 | |
| 3585 | /** |
| 3586 | * \brief Retrieve the annotation associated with the given completion string. |
| 3587 | * |
| 3588 | * \param completion_string the completion string to query. |
| 3589 | * |
| 3590 | * \param annotation_number the 0-based index of the annotation of the |
| 3591 | * completion string. |
| 3592 | * |
| 3593 | * \returns annotation string associated with the completion at index |
| 3594 | * \c annotation_number, or a NULL string if that annotation is not available. |
| 3595 | */ |
| 3596 | CINDEX_LINKAGE CXString |
| 3597 | clang_getCompletionAnnotation(CXCompletionString completion_string, |
| 3598 | unsigned annotation_number); |
| 3599 | |
| 3600 | /** |
Douglas Gregor | ba10306 | 2012-03-27 23:34:16 +0000 | [diff] [blame] | 3601 | * \brief Retrieve the parent context of the given completion string. |
| 3602 | * |
| 3603 | * The parent context of a completion string is the semantic parent of |
| 3604 | * the declaration (if any) that the code completion represents. For example, |
| 3605 | * a code completion for an Objective-C method would have the method's class |
| 3606 | * or protocol as its context. |
| 3607 | * |
| 3608 | * \param completion_string The code completion string whose parent is |
| 3609 | * being queried. |
| 3610 | * |
| 3611 | * \param kind If non-NULL, will be set to the kind of the parent context, |
| 3612 | * or CXCursor_NotImplemented if there is no context. |
| 3613 | * |
| 3614 | * \param Returns the name of the completion parent, e.g., "NSObject" if |
| 3615 | * the completion string represents a method in the NSObject class. |
| 3616 | */ |
| 3617 | CINDEX_LINKAGE CXString |
| 3618 | clang_getCompletionParent(CXCompletionString completion_string, |
| 3619 | enum CXCursorKind *kind); |
| 3620 | /** |
Douglas Gregor | 8fa0a80 | 2011-08-04 20:04:59 +0000 | [diff] [blame] | 3621 | * \brief Retrieve a completion string for an arbitrary declaration or macro |
| 3622 | * definition cursor. |
| 3623 | * |
| 3624 | * \param cursor The cursor to query. |
| 3625 | * |
| 3626 | * \returns A non-context-sensitive completion string for declaration and macro |
| 3627 | * definition cursors, or NULL for other kinds of cursors. |
| 3628 | */ |
| 3629 | CINDEX_LINKAGE CXCompletionString |
| 3630 | clang_getCursorCompletionString(CXCursor cursor); |
| 3631 | |
| 3632 | /** |
Douglas Gregor | ec6762c | 2009-12-18 16:20:58 +0000 | [diff] [blame] | 3633 | * \brief Contains the results of code-completion. |
| 3634 | * |
| 3635 | * This data structure contains the results of code completion, as |
Douglas Gregor | e0cc52e | 2010-10-11 21:51:20 +0000 | [diff] [blame] | 3636 | * produced by \c clang_codeCompleteAt(). Its contents must be freed by |
Douglas Gregor | ec6762c | 2009-12-18 16:20:58 +0000 | [diff] [blame] | 3637 | * \c clang_disposeCodeCompleteResults. |
| 3638 | */ |
| 3639 | typedef struct { |
| 3640 | /** |
| 3641 | * \brief The code-completion results. |
| 3642 | */ |
| 3643 | CXCompletionResult *Results; |
| 3644 | |
| 3645 | /** |
| 3646 | * \brief The number of code-completion results stored in the |
| 3647 | * \c Results array. |
| 3648 | */ |
| 3649 | unsigned NumResults; |
| 3650 | } CXCodeCompleteResults; |
| 3651 | |
| 3652 | /** |
Douglas Gregor | cee235c | 2010-08-05 09:09:23 +0000 | [diff] [blame] | 3653 | * \brief Flags that can be passed to \c clang_codeCompleteAt() to |
| 3654 | * modify its behavior. |
| 3655 | * |
| 3656 | * The enumerators in this enumeration can be bitwise-OR'd together to |
| 3657 | * provide multiple options to \c clang_codeCompleteAt(). |
| 3658 | */ |
| 3659 | enum CXCodeComplete_Flags { |
| 3660 | /** |
| 3661 | * \brief Whether to include macros within the set of code |
| 3662 | * completions returned. |
| 3663 | */ |
| 3664 | CXCodeComplete_IncludeMacros = 0x01, |
| 3665 | |
| 3666 | /** |
| 3667 | * \brief Whether to include code patterns for language constructs |
| 3668 | * within the set of code completions, e.g., for loops. |
| 3669 | */ |
| 3670 | CXCodeComplete_IncludeCodePatterns = 0x02 |
| 3671 | }; |
| 3672 | |
| 3673 | /** |
Douglas Gregor | 3da626b | 2011-07-07 16:03:39 +0000 | [diff] [blame] | 3674 | * \brief Bits that represent the context under which completion is occurring. |
| 3675 | * |
| 3676 | * The enumerators in this enumeration may be bitwise-OR'd together if multiple |
| 3677 | * contexts are occurring simultaneously. |
| 3678 | */ |
| 3679 | enum CXCompletionContext { |
| 3680 | /** |
| 3681 | * \brief The context for completions is unexposed, as only Clang results |
| 3682 | * should be included. (This is equivalent to having no context bits set.) |
| 3683 | */ |
| 3684 | CXCompletionContext_Unexposed = 0, |
| 3685 | |
| 3686 | /** |
| 3687 | * \brief Completions for any possible type should be included in the results. |
| 3688 | */ |
| 3689 | CXCompletionContext_AnyType = 1 << 0, |
| 3690 | |
| 3691 | /** |
| 3692 | * \brief Completions for any possible value (variables, function calls, etc.) |
| 3693 | * should be included in the results. |
| 3694 | */ |
| 3695 | CXCompletionContext_AnyValue = 1 << 1, |
| 3696 | /** |
| 3697 | * \brief Completions for values that resolve to an Objective-C object should |
| 3698 | * be included in the results. |
| 3699 | */ |
| 3700 | CXCompletionContext_ObjCObjectValue = 1 << 2, |
| 3701 | /** |
| 3702 | * \brief Completions for values that resolve to an Objective-C selector |
| 3703 | * should be included in the results. |
| 3704 | */ |
| 3705 | CXCompletionContext_ObjCSelectorValue = 1 << 3, |
| 3706 | /** |
| 3707 | * \brief Completions for values that resolve to a C++ class type should be |
| 3708 | * included in the results. |
| 3709 | */ |
| 3710 | CXCompletionContext_CXXClassTypeValue = 1 << 4, |
| 3711 | |
| 3712 | /** |
| 3713 | * \brief Completions for fields of the member being accessed using the dot |
| 3714 | * operator should be included in the results. |
| 3715 | */ |
| 3716 | CXCompletionContext_DotMemberAccess = 1 << 5, |
| 3717 | /** |
| 3718 | * \brief Completions for fields of the member being accessed using the arrow |
| 3719 | * operator should be included in the results. |
| 3720 | */ |
| 3721 | CXCompletionContext_ArrowMemberAccess = 1 << 6, |
| 3722 | /** |
| 3723 | * \brief Completions for properties of the Objective-C object being accessed |
| 3724 | * using the dot operator should be included in the results. |
| 3725 | */ |
| 3726 | CXCompletionContext_ObjCPropertyAccess = 1 << 7, |
| 3727 | |
| 3728 | /** |
| 3729 | * \brief Completions for enum tags should be included in the results. |
| 3730 | */ |
| 3731 | CXCompletionContext_EnumTag = 1 << 8, |
| 3732 | /** |
| 3733 | * \brief Completions for union tags should be included in the results. |
| 3734 | */ |
| 3735 | CXCompletionContext_UnionTag = 1 << 9, |
| 3736 | /** |
| 3737 | * \brief Completions for struct tags should be included in the results. |
| 3738 | */ |
| 3739 | CXCompletionContext_StructTag = 1 << 10, |
| 3740 | |
| 3741 | /** |
| 3742 | * \brief Completions for C++ class names should be included in the results. |
| 3743 | */ |
| 3744 | CXCompletionContext_ClassTag = 1 << 11, |
| 3745 | /** |
| 3746 | * \brief Completions for C++ namespaces and namespace aliases should be |
| 3747 | * included in the results. |
| 3748 | */ |
| 3749 | CXCompletionContext_Namespace = 1 << 12, |
| 3750 | /** |
| 3751 | * \brief Completions for C++ nested name specifiers should be included in |
| 3752 | * the results. |
| 3753 | */ |
| 3754 | CXCompletionContext_NestedNameSpecifier = 1 << 13, |
| 3755 | |
| 3756 | /** |
| 3757 | * \brief Completions for Objective-C interfaces (classes) should be included |
| 3758 | * in the results. |
| 3759 | */ |
| 3760 | CXCompletionContext_ObjCInterface = 1 << 14, |
| 3761 | /** |
| 3762 | * \brief Completions for Objective-C protocols should be included in |
| 3763 | * the results. |
| 3764 | */ |
| 3765 | CXCompletionContext_ObjCProtocol = 1 << 15, |
| 3766 | /** |
| 3767 | * \brief Completions for Objective-C categories should be included in |
| 3768 | * the results. |
| 3769 | */ |
| 3770 | CXCompletionContext_ObjCCategory = 1 << 16, |
| 3771 | /** |
| 3772 | * \brief Completions for Objective-C instance messages should be included |
| 3773 | * in the results. |
| 3774 | */ |
| 3775 | CXCompletionContext_ObjCInstanceMessage = 1 << 17, |
| 3776 | /** |
| 3777 | * \brief Completions for Objective-C class messages should be included in |
| 3778 | * the results. |
| 3779 | */ |
| 3780 | CXCompletionContext_ObjCClassMessage = 1 << 18, |
| 3781 | /** |
| 3782 | * \brief Completions for Objective-C selector names should be included in |
| 3783 | * the results. |
| 3784 | */ |
| 3785 | CXCompletionContext_ObjCSelectorName = 1 << 19, |
| 3786 | |
| 3787 | /** |
| 3788 | * \brief Completions for preprocessor macro names should be included in |
| 3789 | * the results. |
| 3790 | */ |
| 3791 | CXCompletionContext_MacroName = 1 << 20, |
| 3792 | |
| 3793 | /** |
| 3794 | * \brief Natural language completions should be included in the results. |
| 3795 | */ |
| 3796 | CXCompletionContext_NaturalLanguage = 1 << 21, |
| 3797 | |
| 3798 | /** |
| 3799 | * \brief The current context is unknown, so set all contexts. |
| 3800 | */ |
| 3801 | CXCompletionContext_Unknown = ((1 << 22) - 1) |
| 3802 | }; |
| 3803 | |
| 3804 | /** |
Douglas Gregor | cee235c | 2010-08-05 09:09:23 +0000 | [diff] [blame] | 3805 | * \brief Returns a default set of code-completion options that can be |
| 3806 | * passed to\c clang_codeCompleteAt(). |
| 3807 | */ |
| 3808 | CINDEX_LINKAGE unsigned clang_defaultCodeCompleteOptions(void); |
| 3809 | |
| 3810 | /** |
Douglas Gregor | 1abc6bc | 2010-08-04 16:47:14 +0000 | [diff] [blame] | 3811 | * \brief Perform code completion at a given location in a translation unit. |
| 3812 | * |
| 3813 | * This function performs code completion at a particular file, line, and |
| 3814 | * column within source code, providing results that suggest potential |
| 3815 | * code snippets based on the context of the completion. The basic model |
| 3816 | * for code completion is that Clang will parse a complete source file, |
| 3817 | * performing syntax checking up to the location where code-completion has |
| 3818 | * been requested. At that point, a special code-completion token is passed |
| 3819 | * to the parser, which recognizes this token and determines, based on the |
| 3820 | * current location in the C/Objective-C/C++ grammar and the state of |
| 3821 | * semantic analysis, what completions to provide. These completions are |
| 3822 | * returned via a new \c CXCodeCompleteResults structure. |
| 3823 | * |
| 3824 | * Code completion itself is meant to be triggered by the client when the |
| 3825 | * user types punctuation characters or whitespace, at which point the |
| 3826 | * code-completion location will coincide with the cursor. For example, if \c p |
| 3827 | * is a pointer, code-completion might be triggered after the "-" and then |
| 3828 | * after the ">" in \c p->. When the code-completion location is afer the ">", |
| 3829 | * the completion results will provide, e.g., the members of the struct that |
| 3830 | * "p" points to. The client is responsible for placing the cursor at the |
| 3831 | * beginning of the token currently being typed, then filtering the results |
| 3832 | * based on the contents of the token. For example, when code-completing for |
| 3833 | * the expression \c p->get, the client should provide the location just after |
| 3834 | * the ">" (e.g., pointing at the "g") to this code-completion hook. Then, the |
| 3835 | * client can filter the results based on the current token text ("get"), only |
| 3836 | * showing those results that start with "get". The intent of this interface |
| 3837 | * is to separate the relatively high-latency acquisition of code-completion |
| 3838 | * results from the filtering of results on a per-character basis, which must |
| 3839 | * have a lower latency. |
| 3840 | * |
| 3841 | * \param TU The translation unit in which code-completion should |
| 3842 | * occur. The source files for this translation unit need not be |
| 3843 | * completely up-to-date (and the contents of those source files may |
| 3844 | * be overridden via \p unsaved_files). Cursors referring into the |
| 3845 | * translation unit may be invalidated by this invocation. |
| 3846 | * |
| 3847 | * \param complete_filename The name of the source file where code |
| 3848 | * completion should be performed. This filename may be any file |
| 3849 | * included in the translation unit. |
| 3850 | * |
| 3851 | * \param complete_line The line at which code-completion should occur. |
| 3852 | * |
| 3853 | * \param complete_column The column at which code-completion should occur. |
| 3854 | * Note that the column should point just after the syntactic construct that |
| 3855 | * initiated code completion, and not in the middle of a lexical token. |
| 3856 | * |
| 3857 | * \param unsaved_files the Tiles that have not yet been saved to disk |
| 3858 | * but may be required for parsing or code completion, including the |
| 3859 | * contents of those files. The contents and name of these files (as |
| 3860 | * specified by CXUnsavedFile) are copied when necessary, so the |
| 3861 | * client only needs to guarantee their validity until the call to |
| 3862 | * this function returns. |
| 3863 | * |
| 3864 | * \param num_unsaved_files The number of unsaved file entries in \p |
| 3865 | * unsaved_files. |
| 3866 | * |
Douglas Gregor | cee235c | 2010-08-05 09:09:23 +0000 | [diff] [blame] | 3867 | * \param options Extra options that control the behavior of code |
| 3868 | * completion, expressed as a bitwise OR of the enumerators of the |
| 3869 | * CXCodeComplete_Flags enumeration. The |
| 3870 | * \c clang_defaultCodeCompleteOptions() function returns a default set |
| 3871 | * of code-completion options. |
| 3872 | * |
Douglas Gregor | 1abc6bc | 2010-08-04 16:47:14 +0000 | [diff] [blame] | 3873 | * \returns If successful, a new \c CXCodeCompleteResults structure |
| 3874 | * containing code-completion results, which should eventually be |
| 3875 | * freed with \c clang_disposeCodeCompleteResults(). If code |
| 3876 | * completion fails, returns NULL. |
| 3877 | */ |
| 3878 | CINDEX_LINKAGE |
| 3879 | CXCodeCompleteResults *clang_codeCompleteAt(CXTranslationUnit TU, |
| 3880 | const char *complete_filename, |
| 3881 | unsigned complete_line, |
| 3882 | unsigned complete_column, |
| 3883 | struct CXUnsavedFile *unsaved_files, |
Douglas Gregor | cee235c | 2010-08-05 09:09:23 +0000 | [diff] [blame] | 3884 | unsigned num_unsaved_files, |
| 3885 | unsigned options); |
Douglas Gregor | 1abc6bc | 2010-08-04 16:47:14 +0000 | [diff] [blame] | 3886 | |
| 3887 | /** |
Douglas Gregor | 1e5e668 | 2010-08-26 13:48:20 +0000 | [diff] [blame] | 3888 | * \brief Sort the code-completion results in case-insensitive alphabetical |
| 3889 | * order. |
| 3890 | * |
| 3891 | * \param Results The set of results to sort. |
| 3892 | * \param NumResults The number of results in \p Results. |
| 3893 | */ |
| 3894 | CINDEX_LINKAGE |
| 3895 | void clang_sortCodeCompletionResults(CXCompletionResult *Results, |
| 3896 | unsigned NumResults); |
| 3897 | |
| 3898 | /** |
Douglas Gregor | ec6762c | 2009-12-18 16:20:58 +0000 | [diff] [blame] | 3899 | * \brief Free the given set of code-completion results. |
| 3900 | */ |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 3901 | CINDEX_LINKAGE |
Douglas Gregor | ec6762c | 2009-12-18 16:20:58 +0000 | [diff] [blame] | 3902 | void clang_disposeCodeCompleteResults(CXCodeCompleteResults *Results); |
Douglas Gregor | 58ddb60 | 2010-08-23 23:00:57 +0000 | [diff] [blame] | 3903 | |
Douglas Gregor | 20d416c | 2010-01-20 01:10:47 +0000 | [diff] [blame] | 3904 | /** |
Douglas Gregor | a88084b | 2010-02-18 18:08:43 +0000 | [diff] [blame] | 3905 | * \brief Determine the number of diagnostics produced prior to the |
| 3906 | * location where code completion was performed. |
| 3907 | */ |
Ted Kremenek | 896b70f | 2010-03-13 02:50:34 +0000 | [diff] [blame] | 3908 | CINDEX_LINKAGE |
Douglas Gregor | a88084b | 2010-02-18 18:08:43 +0000 | [diff] [blame] | 3909 | unsigned clang_codeCompleteGetNumDiagnostics(CXCodeCompleteResults *Results); |
| 3910 | |
| 3911 | /** |
| 3912 | * \brief Retrieve a diagnostic associated with the given code completion. |
| 3913 | * |
| 3914 | * \param Result the code completion results to query. |
| 3915 | * \param Index the zero-based diagnostic number to retrieve. |
| 3916 | * |
| 3917 | * \returns the requested diagnostic. This diagnostic must be freed |
| 3918 | * via a call to \c clang_disposeDiagnostic(). |
| 3919 | */ |
Ted Kremenek | 896b70f | 2010-03-13 02:50:34 +0000 | [diff] [blame] | 3920 | CINDEX_LINKAGE |
Douglas Gregor | a88084b | 2010-02-18 18:08:43 +0000 | [diff] [blame] | 3921 | CXDiagnostic clang_codeCompleteGetDiagnostic(CXCodeCompleteResults *Results, |
| 3922 | unsigned Index); |
| 3923 | |
| 3924 | /** |
Douglas Gregor | 3da626b | 2011-07-07 16:03:39 +0000 | [diff] [blame] | 3925 | * \brief Determines what compeltions are appropriate for the context |
| 3926 | * the given code completion. |
| 3927 | * |
| 3928 | * \param Results the code completion results to query |
| 3929 | * |
| 3930 | * \returns the kinds of completions that are appropriate for use |
| 3931 | * along with the given code completion results. |
| 3932 | */ |
| 3933 | CINDEX_LINKAGE |
| 3934 | unsigned long long clang_codeCompleteGetContexts( |
| 3935 | CXCodeCompleteResults *Results); |
Douglas Gregor | e081a61 | 2011-07-21 01:05:26 +0000 | [diff] [blame] | 3936 | |
| 3937 | /** |
| 3938 | * \brief Returns the cursor kind for the container for the current code |
| 3939 | * completion context. The container is only guaranteed to be set for |
| 3940 | * contexts where a container exists (i.e. member accesses or Objective-C |
| 3941 | * message sends); if there is not a container, this function will return |
| 3942 | * CXCursor_InvalidCode. |
| 3943 | * |
| 3944 | * \param Results the code completion results to query |
| 3945 | * |
| 3946 | * \param IsIncomplete on return, this value will be false if Clang has complete |
| 3947 | * information about the container. If Clang does not have complete |
| 3948 | * information, this value will be true. |
| 3949 | * |
| 3950 | * \returns the container kind, or CXCursor_InvalidCode if there is not a |
| 3951 | * container |
| 3952 | */ |
| 3953 | CINDEX_LINKAGE |
| 3954 | enum CXCursorKind clang_codeCompleteGetContainerKind( |
| 3955 | CXCodeCompleteResults *Results, |
| 3956 | unsigned *IsIncomplete); |
| 3957 | |
| 3958 | /** |
| 3959 | * \brief Returns the USR for the container for the current code completion |
| 3960 | * context. If there is not a container for the current context, this |
| 3961 | * function will return the empty string. |
| 3962 | * |
| 3963 | * \param Results the code completion results to query |
| 3964 | * |
| 3965 | * \returns the USR for the container |
| 3966 | */ |
| 3967 | CINDEX_LINKAGE |
| 3968 | CXString clang_codeCompleteGetContainerUSR(CXCodeCompleteResults *Results); |
Douglas Gregor | 3da626b | 2011-07-07 16:03:39 +0000 | [diff] [blame] | 3969 | |
Douglas Gregor | 0a47d69 | 2011-07-26 15:24:30 +0000 | [diff] [blame] | 3970 | |
| 3971 | /** |
| 3972 | * \brief Returns the currently-entered selector for an Objective-C message |
| 3973 | * send, formatted like "initWithFoo:bar:". Only guaranteed to return a |
| 3974 | * non-empty string for CXCompletionContext_ObjCInstanceMessage and |
| 3975 | * CXCompletionContext_ObjCClassMessage. |
| 3976 | * |
| 3977 | * \param Results the code completion results to query |
| 3978 | * |
| 3979 | * \returns the selector (or partial selector) that has been entered thus far |
| 3980 | * for an Objective-C message send. |
| 3981 | */ |
| 3982 | CINDEX_LINKAGE |
| 3983 | CXString clang_codeCompleteGetObjCSelector(CXCodeCompleteResults *Results); |
| 3984 | |
Douglas Gregor | 3da626b | 2011-07-07 16:03:39 +0000 | [diff] [blame] | 3985 | /** |
Douglas Gregor | 20d416c | 2010-01-20 01:10:47 +0000 | [diff] [blame] | 3986 | * @} |
| 3987 | */ |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 3988 | |
| 3989 | |
Ted Kremenek | 04bb716 | 2010-01-22 22:44:15 +0000 | [diff] [blame] | 3990 | /** |
| 3991 | * \defgroup CINDEX_MISC Miscellaneous utility functions |
| 3992 | * |
| 3993 | * @{ |
| 3994 | */ |
Ted Kremenek | 23e1ad0 | 2010-01-23 17:51:23 +0000 | [diff] [blame] | 3995 | |
| 3996 | /** |
| 3997 | * \brief Return a version string, suitable for showing to a user, but not |
| 3998 | * intended to be parsed (the format is not guaranteed to be stable). |
| 3999 | */ |
Ted Kremenek | a2a9d6e | 2010-02-12 22:54:40 +0000 | [diff] [blame] | 4000 | CINDEX_LINKAGE CXString clang_getClangVersion(); |
Ted Kremenek | 04bb716 | 2010-01-22 22:44:15 +0000 | [diff] [blame] | 4001 | |
Ted Kremenek | d2427dd | 2011-03-18 23:05:39 +0000 | [diff] [blame] | 4002 | |
| 4003 | /** |
| 4004 | * \brief Enable/disable crash recovery. |
| 4005 | * |
| 4006 | * \param Flag to indicate if crash recovery is enabled. A non-zero value |
| 4007 | * enables crash recovery, while 0 disables it. |
| 4008 | */ |
| 4009 | CINDEX_LINKAGE void clang_toggleCrashRecovery(unsigned isEnabled); |
| 4010 | |
Ted Kremenek | 16b55a7 | 2010-01-26 19:31:51 +0000 | [diff] [blame] | 4011 | /** |
Ted Kremenek | 896b70f | 2010-03-13 02:50:34 +0000 | [diff] [blame] | 4012 | * \brief Visitor invoked for each file in a translation unit |
Ted Kremenek | 16b55a7 | 2010-01-26 19:31:51 +0000 | [diff] [blame] | 4013 | * (used with clang_getInclusions()). |
| 4014 | * |
| 4015 | * This visitor function will be invoked by clang_getInclusions() for each |
| 4016 | * file included (either at the top-level or by #include directives) within |
| 4017 | * a translation unit. The first argument is the file being included, and |
| 4018 | * the second and third arguments provide the inclusion stack. The |
| 4019 | * array is sorted in order of immediate inclusion. For example, |
| 4020 | * the first element refers to the location that included 'included_file'. |
| 4021 | */ |
| 4022 | typedef void (*CXInclusionVisitor)(CXFile included_file, |
| 4023 | CXSourceLocation* inclusion_stack, |
| 4024 | unsigned include_len, |
| 4025 | CXClientData client_data); |
| 4026 | |
| 4027 | /** |
| 4028 | * \brief Visit the set of preprocessor inclusions in a translation unit. |
| 4029 | * The visitor function is called with the provided data for every included |
| 4030 | * file. This does not include headers included by the PCH file (unless one |
| 4031 | * is inspecting the inclusions in the PCH file itself). |
| 4032 | */ |
| 4033 | CINDEX_LINKAGE void clang_getInclusions(CXTranslationUnit tu, |
| 4034 | CXInclusionVisitor visitor, |
| 4035 | CXClientData client_data); |
| 4036 | |
| 4037 | /** |
Ted Kremenek | 04bb716 | 2010-01-22 22:44:15 +0000 | [diff] [blame] | 4038 | * @} |
| 4039 | */ |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 4040 | |
Argyrios Kyrtzidis | 97c337c | 2011-07-11 20:15:00 +0000 | [diff] [blame] | 4041 | /** \defgroup CINDEX_REMAPPING Remapping functions |
| 4042 | * |
| 4043 | * @{ |
| 4044 | */ |
| 4045 | |
| 4046 | /** |
| 4047 | * \brief A remapping of original source files and their translated files. |
| 4048 | */ |
| 4049 | typedef void *CXRemapping; |
| 4050 | |
| 4051 | /** |
| 4052 | * \brief Retrieve a remapping. |
| 4053 | * |
| 4054 | * \param path the path that contains metadata about remappings. |
| 4055 | * |
| 4056 | * \returns the requested remapping. This remapping must be freed |
| 4057 | * via a call to \c clang_remap_dispose(). Can return NULL if an error occurred. |
| 4058 | */ |
| 4059 | CINDEX_LINKAGE CXRemapping clang_getRemappings(const char *path); |
| 4060 | |
| 4061 | /** |
Ted Kremenek | 30660a8 | 2012-03-06 20:06:33 +0000 | [diff] [blame] | 4062 | * \brief Retrieve a remapping. |
| 4063 | * |
| 4064 | * \param filePaths pointer to an array of file paths containing remapping info. |
| 4065 | * |
| 4066 | * \param numFiles number of file paths. |
| 4067 | * |
| 4068 | * \returns the requested remapping. This remapping must be freed |
| 4069 | * via a call to \c clang_remap_dispose(). Can return NULL if an error occurred. |
| 4070 | */ |
| 4071 | CINDEX_LINKAGE |
| 4072 | CXRemapping clang_getRemappingsFromFileList(const char **filePaths, |
| 4073 | unsigned numFiles); |
| 4074 | |
| 4075 | /** |
Argyrios Kyrtzidis | 97c337c | 2011-07-11 20:15:00 +0000 | [diff] [blame] | 4076 | * \brief Determine the number of remappings. |
| 4077 | */ |
| 4078 | CINDEX_LINKAGE unsigned clang_remap_getNumFiles(CXRemapping); |
| 4079 | |
| 4080 | /** |
| 4081 | * \brief Get the original and the associated filename from the remapping. |
| 4082 | * |
| 4083 | * \param original If non-NULL, will be set to the original filename. |
| 4084 | * |
| 4085 | * \param transformed If non-NULL, will be set to the filename that the original |
| 4086 | * is associated with. |
| 4087 | */ |
| 4088 | CINDEX_LINKAGE void clang_remap_getFilenames(CXRemapping, unsigned index, |
| 4089 | CXString *original, CXString *transformed); |
| 4090 | |
| 4091 | /** |
| 4092 | * \brief Dispose the remapping. |
| 4093 | */ |
| 4094 | CINDEX_LINKAGE void clang_remap_dispose(CXRemapping); |
| 4095 | |
| 4096 | /** |
| 4097 | * @} |
| 4098 | */ |
| 4099 | |
Argyrios Kyrtzidis | aed123e | 2011-10-06 07:00:54 +0000 | [diff] [blame] | 4100 | /** \defgroup CINDEX_HIGH Higher level API functions |
| 4101 | * |
| 4102 | * @{ |
| 4103 | */ |
| 4104 | |
| 4105 | enum CXVisitorResult { |
| 4106 | CXVisit_Break, |
| 4107 | CXVisit_Continue |
| 4108 | }; |
| 4109 | |
| 4110 | typedef struct { |
| 4111 | void *context; |
| 4112 | enum CXVisitorResult (*visit)(void *context, CXCursor, CXSourceRange); |
| 4113 | } CXCursorAndRangeVisitor; |
| 4114 | |
| 4115 | /** |
| 4116 | * \brief Find references of a declaration in a specific file. |
| 4117 | * |
| 4118 | * \param cursor pointing to a declaration or a reference of one. |
| 4119 | * |
| 4120 | * \param file to search for references. |
| 4121 | * |
| 4122 | * \param visitor callback that will receive pairs of CXCursor/CXSourceRange for |
| 4123 | * each reference found. |
| 4124 | * The CXSourceRange will point inside the file; if the reference is inside |
| 4125 | * a macro (and not a macro argument) the CXSourceRange will be invalid. |
| 4126 | */ |
| 4127 | CINDEX_LINKAGE void clang_findReferencesInFile(CXCursor cursor, CXFile file, |
| 4128 | CXCursorAndRangeVisitor visitor); |
| 4129 | |
| 4130 | #ifdef __has_feature |
| 4131 | # if __has_feature(blocks) |
| 4132 | |
| 4133 | typedef enum CXVisitorResult |
| 4134 | (^CXCursorAndRangeVisitorBlock)(CXCursor, CXSourceRange); |
| 4135 | |
| 4136 | CINDEX_LINKAGE |
| 4137 | void clang_findReferencesInFileWithBlock(CXCursor, CXFile, |
| 4138 | CXCursorAndRangeVisitorBlock); |
| 4139 | |
| 4140 | # endif |
| 4141 | #endif |
| 4142 | |
Argyrios Kyrtzidis | bd0ddf8 | 2011-10-27 17:36:12 +0000 | [diff] [blame] | 4143 | /** |
| 4144 | * \brief The client's data object that is associated with a CXFile. |
| 4145 | */ |
Argyrios Kyrtzidis | dd93c59 | 2011-11-11 00:23:36 +0000 | [diff] [blame] | 4146 | typedef void *CXIdxClientFile; |
Argyrios Kyrtzidis | bd0ddf8 | 2011-10-27 17:36:12 +0000 | [diff] [blame] | 4147 | |
| 4148 | /** |
Argyrios Kyrtzidis | 2957e6f | 2011-11-22 07:24:51 +0000 | [diff] [blame] | 4149 | * \brief The client's data object that is associated with a semantic entity. |
| 4150 | */ |
| 4151 | typedef void *CXIdxClientEntity; |
| 4152 | |
| 4153 | /** |
Argyrios Kyrtzidis | bd0ddf8 | 2011-10-27 17:36:12 +0000 | [diff] [blame] | 4154 | * \brief The client's data object that is associated with a semantic container |
| 4155 | * of entities. |
Argyrios Kyrtzidis | bd0ddf8 | 2011-10-27 17:36:12 +0000 | [diff] [blame] | 4156 | */ |
Argyrios Kyrtzidis | dd93c59 | 2011-11-11 00:23:36 +0000 | [diff] [blame] | 4157 | typedef void *CXIdxClientContainer; |
Argyrios Kyrtzidis | bd0ddf8 | 2011-10-27 17:36:12 +0000 | [diff] [blame] | 4158 | |
| 4159 | /** |
Argyrios Kyrtzidis | bd0ddf8 | 2011-10-27 17:36:12 +0000 | [diff] [blame] | 4160 | * \brief The client's data object that is associated with an AST file (PCH |
| 4161 | * or module). |
| 4162 | */ |
Argyrios Kyrtzidis | dd93c59 | 2011-11-11 00:23:36 +0000 | [diff] [blame] | 4163 | typedef void *CXIdxClientASTFile; |
Argyrios Kyrtzidis | 4e7064f | 2011-10-17 19:48:19 +0000 | [diff] [blame] | 4164 | |
Argyrios Kyrtzidis | bd0ddf8 | 2011-10-27 17:36:12 +0000 | [diff] [blame] | 4165 | /** |
Argyrios Kyrtzidis | dd93c59 | 2011-11-11 00:23:36 +0000 | [diff] [blame] | 4166 | * \brief Source location passed to index callbacks. |
Argyrios Kyrtzidis | bd0ddf8 | 2011-10-27 17:36:12 +0000 | [diff] [blame] | 4167 | */ |
Argyrios Kyrtzidis | 4e7064f | 2011-10-17 19:48:19 +0000 | [diff] [blame] | 4168 | typedef struct { |
| 4169 | void *ptr_data[2]; |
| 4170 | unsigned int_data; |
| 4171 | } CXIdxLoc; |
| 4172 | |
Argyrios Kyrtzidis | bd0ddf8 | 2011-10-27 17:36:12 +0000 | [diff] [blame] | 4173 | /** |
| 4174 | * \brief Data for \see ppIncludedFile callback. |
| 4175 | */ |
Argyrios Kyrtzidis | 4e7064f | 2011-10-17 19:48:19 +0000 | [diff] [blame] | 4176 | typedef struct { |
Argyrios Kyrtzidis | bd0ddf8 | 2011-10-27 17:36:12 +0000 | [diff] [blame] | 4177 | /** |
| 4178 | * \brief Location of '#' in the #include/#import directive. |
| 4179 | */ |
Argyrios Kyrtzidis | 4e7064f | 2011-10-17 19:48:19 +0000 | [diff] [blame] | 4180 | CXIdxLoc hashLoc; |
Argyrios Kyrtzidis | bd0ddf8 | 2011-10-27 17:36:12 +0000 | [diff] [blame] | 4181 | /** |
| 4182 | * \brief Filename as written in the #include/#import directive. |
| 4183 | */ |
Argyrios Kyrtzidis | 4e7064f | 2011-10-17 19:48:19 +0000 | [diff] [blame] | 4184 | const char *filename; |
Argyrios Kyrtzidis | bd0ddf8 | 2011-10-27 17:36:12 +0000 | [diff] [blame] | 4185 | /** |
| 4186 | * \brief The actual file that the #include/#import directive resolved to. |
| 4187 | */ |
Argyrios Kyrtzidis | dd93c59 | 2011-11-11 00:23:36 +0000 | [diff] [blame] | 4188 | CXFile file; |
Argyrios Kyrtzidis | 4e7064f | 2011-10-17 19:48:19 +0000 | [diff] [blame] | 4189 | int isImport; |
| 4190 | int isAngled; |
| 4191 | } CXIdxIncludedFileInfo; |
| 4192 | |
Argyrios Kyrtzidis | bd0ddf8 | 2011-10-27 17:36:12 +0000 | [diff] [blame] | 4193 | /** |
| 4194 | * \brief Data for \see importedASTFile callback. |
| 4195 | */ |
Argyrios Kyrtzidis | 4e7064f | 2011-10-17 19:48:19 +0000 | [diff] [blame] | 4196 | typedef struct { |
| 4197 | CXFile file; |
Argyrios Kyrtzidis | bd0ddf8 | 2011-10-27 17:36:12 +0000 | [diff] [blame] | 4198 | /** |
| 4199 | * \brief Location where the file is imported. It is useful mostly for |
| 4200 | * modules. |
| 4201 | */ |
Argyrios Kyrtzidis | 4e7064f | 2011-10-17 19:48:19 +0000 | [diff] [blame] | 4202 | CXIdxLoc loc; |
Argyrios Kyrtzidis | bd0ddf8 | 2011-10-27 17:36:12 +0000 | [diff] [blame] | 4203 | /** |
| 4204 | * \brief Non-zero if the AST file is a module otherwise it's a PCH. |
| 4205 | */ |
Argyrios Kyrtzidis | 4e7064f | 2011-10-17 19:48:19 +0000 | [diff] [blame] | 4206 | int isModule; |
| 4207 | } CXIdxImportedASTFileInfo; |
| 4208 | |
Argyrios Kyrtzidis | dd93c59 | 2011-11-11 00:23:36 +0000 | [diff] [blame] | 4209 | typedef enum { |
| 4210 | CXIdxEntity_Unexposed = 0, |
| 4211 | CXIdxEntity_Typedef = 1, |
| 4212 | CXIdxEntity_Function = 2, |
| 4213 | CXIdxEntity_Variable = 3, |
| 4214 | CXIdxEntity_Field = 4, |
| 4215 | CXIdxEntity_EnumConstant = 5, |
| 4216 | |
| 4217 | CXIdxEntity_ObjCClass = 6, |
| 4218 | CXIdxEntity_ObjCProtocol = 7, |
| 4219 | CXIdxEntity_ObjCCategory = 8, |
| 4220 | |
Argyrios Kyrtzidis | c71d554 | 2011-11-14 22:39:19 +0000 | [diff] [blame] | 4221 | CXIdxEntity_ObjCInstanceMethod = 9, |
| 4222 | CXIdxEntity_ObjCClassMethod = 10, |
| 4223 | CXIdxEntity_ObjCProperty = 11, |
| 4224 | CXIdxEntity_ObjCIvar = 12, |
Argyrios Kyrtzidis | dd93c59 | 2011-11-11 00:23:36 +0000 | [diff] [blame] | 4225 | |
Argyrios Kyrtzidis | c71d554 | 2011-11-14 22:39:19 +0000 | [diff] [blame] | 4226 | CXIdxEntity_Enum = 13, |
| 4227 | CXIdxEntity_Struct = 14, |
| 4228 | CXIdxEntity_Union = 15, |
Argyrios Kyrtzidis | 2957e6f | 2011-11-22 07:24:51 +0000 | [diff] [blame] | 4229 | |
| 4230 | CXIdxEntity_CXXClass = 16, |
| 4231 | CXIdxEntity_CXXNamespace = 17, |
| 4232 | CXIdxEntity_CXXNamespaceAlias = 18, |
| 4233 | CXIdxEntity_CXXStaticVariable = 19, |
| 4234 | CXIdxEntity_CXXStaticMethod = 20, |
| 4235 | CXIdxEntity_CXXInstanceMethod = 21, |
| 4236 | CXIdxEntity_CXXConstructor = 22, |
| 4237 | CXIdxEntity_CXXDestructor = 23, |
| 4238 | CXIdxEntity_CXXConversionFunction = 24, |
Argyrios Kyrtzidis | 838d3c2 | 2011-12-07 20:44:12 +0000 | [diff] [blame] | 4239 | CXIdxEntity_CXXTypeAlias = 25 |
Argyrios Kyrtzidis | dd93c59 | 2011-11-11 00:23:36 +0000 | [diff] [blame] | 4240 | |
| 4241 | } CXIdxEntityKind; |
Argyrios Kyrtzidis | 4e7064f | 2011-10-17 19:48:19 +0000 | [diff] [blame] | 4242 | |
Argyrios Kyrtzidis | 838d3c2 | 2011-12-07 20:44:12 +0000 | [diff] [blame] | 4243 | typedef enum { |
| 4244 | CXIdxEntityLang_None = 0, |
| 4245 | CXIdxEntityLang_C = 1, |
| 4246 | CXIdxEntityLang_ObjC = 2, |
| 4247 | CXIdxEntityLang_CXX = 3 |
| 4248 | } CXIdxEntityLanguage; |
| 4249 | |
Argyrios Kyrtzidis | 2957e6f | 2011-11-22 07:24:51 +0000 | [diff] [blame] | 4250 | /** |
| 4251 | * \brief Extra C++ template information for an entity. This can apply to: |
| 4252 | * CXIdxEntity_Function |
| 4253 | * CXIdxEntity_CXXClass |
| 4254 | * CXIdxEntity_CXXStaticMethod |
| 4255 | * CXIdxEntity_CXXInstanceMethod |
| 4256 | * CXIdxEntity_CXXConstructor |
| 4257 | * CXIdxEntity_CXXConversionFunction |
| 4258 | * CXIdxEntity_CXXTypeAlias |
| 4259 | */ |
| 4260 | typedef enum { |
| 4261 | CXIdxEntity_NonTemplate = 0, |
| 4262 | CXIdxEntity_Template = 1, |
| 4263 | CXIdxEntity_TemplatePartialSpecialization = 2, |
| 4264 | CXIdxEntity_TemplateSpecialization = 3 |
| 4265 | } CXIdxEntityCXXTemplateKind; |
| 4266 | |
Argyrios Kyrtzidis | b395c63 | 2011-11-18 00:26:51 +0000 | [diff] [blame] | 4267 | typedef enum { |
| 4268 | CXIdxAttr_Unexposed = 0, |
| 4269 | CXIdxAttr_IBAction = 1, |
| 4270 | CXIdxAttr_IBOutlet = 2, |
| 4271 | CXIdxAttr_IBOutletCollection = 3 |
| 4272 | } CXIdxAttrKind; |
| 4273 | |
| 4274 | typedef struct { |
| 4275 | CXIdxAttrKind kind; |
| 4276 | CXCursor cursor; |
| 4277 | CXIdxLoc loc; |
| 4278 | } CXIdxAttrInfo; |
| 4279 | |
| 4280 | typedef struct { |
Argyrios Kyrtzidis | 643d3ce | 2011-12-15 00:05:00 +0000 | [diff] [blame] | 4281 | CXIdxEntityKind kind; |
| 4282 | CXIdxEntityCXXTemplateKind templateKind; |
| 4283 | CXIdxEntityLanguage lang; |
| 4284 | const char *name; |
| 4285 | const char *USR; |
| 4286 | CXCursor cursor; |
| 4287 | const CXIdxAttrInfo *const *attributes; |
| 4288 | unsigned numAttributes; |
| 4289 | } CXIdxEntityInfo; |
| 4290 | |
| 4291 | typedef struct { |
| 4292 | CXCursor cursor; |
| 4293 | } CXIdxContainerInfo; |
| 4294 | |
| 4295 | typedef struct { |
Argyrios Kyrtzidis | b395c63 | 2011-11-18 00:26:51 +0000 | [diff] [blame] | 4296 | const CXIdxAttrInfo *attrInfo; |
| 4297 | const CXIdxEntityInfo *objcClass; |
| 4298 | CXCursor classCursor; |
| 4299 | CXIdxLoc classLoc; |
| 4300 | } CXIdxIBOutletCollectionAttrInfo; |
| 4301 | |
Argyrios Kyrtzidis | 4e7064f | 2011-10-17 19:48:19 +0000 | [diff] [blame] | 4302 | typedef struct { |
Argyrios Kyrtzidis | 6ec43ad | 2011-11-12 02:16:30 +0000 | [diff] [blame] | 4303 | const CXIdxEntityInfo *entityInfo; |
Argyrios Kyrtzidis | 4e7064f | 2011-10-17 19:48:19 +0000 | [diff] [blame] | 4304 | CXCursor cursor; |
| 4305 | CXIdxLoc loc; |
Argyrios Kyrtzidis | b1febb6 | 2011-12-07 20:44:19 +0000 | [diff] [blame] | 4306 | const CXIdxContainerInfo *semanticContainer; |
| 4307 | /** |
| 4308 | * \brief Generally same as \see semanticContainer but can be different in |
| 4309 | * cases like out-of-line C++ member functions. |
| 4310 | */ |
| 4311 | const CXIdxContainerInfo *lexicalContainer; |
Argyrios Kyrtzidis | dd93c59 | 2011-11-11 00:23:36 +0000 | [diff] [blame] | 4312 | int isRedeclaration; |
Argyrios Kyrtzidis | 4e7064f | 2011-10-17 19:48:19 +0000 | [diff] [blame] | 4313 | int isDefinition; |
Argyrios Kyrtzidis | c71d554 | 2011-11-14 22:39:19 +0000 | [diff] [blame] | 4314 | int isContainer; |
Argyrios Kyrtzidis | 2957e6f | 2011-11-22 07:24:51 +0000 | [diff] [blame] | 4315 | const CXIdxContainerInfo *declAsContainer; |
Argyrios Kyrtzidis | c71d554 | 2011-11-14 22:39:19 +0000 | [diff] [blame] | 4316 | /** |
| 4317 | * \brief Whether the declaration exists in code or was created implicitly |
| 4318 | * by the compiler, e.g. implicit objc methods for properties. |
| 4319 | */ |
| 4320 | int isImplicit; |
Argyrios Kyrtzidis | b395c63 | 2011-11-18 00:26:51 +0000 | [diff] [blame] | 4321 | const CXIdxAttrInfo *const *attributes; |
| 4322 | unsigned numAttributes; |
Argyrios Kyrtzidis | dd93c59 | 2011-11-11 00:23:36 +0000 | [diff] [blame] | 4323 | } CXIdxDeclInfo; |
Argyrios Kyrtzidis | 4e7064f | 2011-10-17 19:48:19 +0000 | [diff] [blame] | 4324 | |
Argyrios Kyrtzidis | dd93c59 | 2011-11-11 00:23:36 +0000 | [diff] [blame] | 4325 | typedef enum { |
| 4326 | CXIdxObjCContainer_ForwardRef = 0, |
| 4327 | CXIdxObjCContainer_Interface = 1, |
| 4328 | CXIdxObjCContainer_Implementation = 2 |
| 4329 | } CXIdxObjCContainerKind; |
Argyrios Kyrtzidis | 4e7064f | 2011-10-17 19:48:19 +0000 | [diff] [blame] | 4330 | |
| 4331 | typedef struct { |
Argyrios Kyrtzidis | 6ec43ad | 2011-11-12 02:16:30 +0000 | [diff] [blame] | 4332 | const CXIdxDeclInfo *declInfo; |
Argyrios Kyrtzidis | dd93c59 | 2011-11-11 00:23:36 +0000 | [diff] [blame] | 4333 | CXIdxObjCContainerKind kind; |
| 4334 | } CXIdxObjCContainerDeclInfo; |
Argyrios Kyrtzidis | 4e7064f | 2011-10-17 19:48:19 +0000 | [diff] [blame] | 4335 | |
| 4336 | typedef struct { |
Argyrios Kyrtzidis | 6ec43ad | 2011-11-12 02:16:30 +0000 | [diff] [blame] | 4337 | const CXIdxEntityInfo *base; |
| 4338 | CXCursor cursor; |
Argyrios Kyrtzidis | 4e7064f | 2011-10-17 19:48:19 +0000 | [diff] [blame] | 4339 | CXIdxLoc loc; |
Argyrios Kyrtzidis | 6ec43ad | 2011-11-12 02:16:30 +0000 | [diff] [blame] | 4340 | } CXIdxBaseClassInfo; |
Argyrios Kyrtzidis | 4e7064f | 2011-10-17 19:48:19 +0000 | [diff] [blame] | 4341 | |
| 4342 | typedef struct { |
Argyrios Kyrtzidis | 6ec43ad | 2011-11-12 02:16:30 +0000 | [diff] [blame] | 4343 | const CXIdxEntityInfo *protocol; |
| 4344 | CXCursor cursor; |
Argyrios Kyrtzidis | 4e7064f | 2011-10-17 19:48:19 +0000 | [diff] [blame] | 4345 | CXIdxLoc loc; |
| 4346 | } CXIdxObjCProtocolRefInfo; |
| 4347 | |
| 4348 | typedef struct { |
Argyrios Kyrtzidis | 6ec43ad | 2011-11-12 02:16:30 +0000 | [diff] [blame] | 4349 | const CXIdxObjCProtocolRefInfo *const *protocols; |
Argyrios Kyrtzidis | 4e7064f | 2011-10-17 19:48:19 +0000 | [diff] [blame] | 4350 | unsigned numProtocols; |
Argyrios Kyrtzidis | c71d554 | 2011-11-14 22:39:19 +0000 | [diff] [blame] | 4351 | } CXIdxObjCProtocolRefListInfo; |
Argyrios Kyrtzidis | 4e7064f | 2011-10-17 19:48:19 +0000 | [diff] [blame] | 4352 | |
| 4353 | typedef struct { |
Argyrios Kyrtzidis | c71d554 | 2011-11-14 22:39:19 +0000 | [diff] [blame] | 4354 | const CXIdxObjCContainerDeclInfo *containerInfo; |
| 4355 | const CXIdxBaseClassInfo *superInfo; |
| 4356 | const CXIdxObjCProtocolRefListInfo *protocols; |
| 4357 | } CXIdxObjCInterfaceDeclInfo; |
Argyrios Kyrtzidis | 4e7064f | 2011-10-17 19:48:19 +0000 | [diff] [blame] | 4358 | |
Argyrios Kyrtzidis | 2957e6f | 2011-11-22 07:24:51 +0000 | [diff] [blame] | 4359 | typedef struct { |
Argyrios Kyrtzidis | c10a4c8 | 2011-12-13 18:47:45 +0000 | [diff] [blame] | 4360 | const CXIdxObjCContainerDeclInfo *containerInfo; |
| 4361 | const CXIdxEntityInfo *objcClass; |
| 4362 | CXCursor classCursor; |
| 4363 | CXIdxLoc classLoc; |
| 4364 | const CXIdxObjCProtocolRefListInfo *protocols; |
| 4365 | } CXIdxObjCCategoryDeclInfo; |
| 4366 | |
| 4367 | typedef struct { |
Argyrios Kyrtzidis | 2957e6f | 2011-11-22 07:24:51 +0000 | [diff] [blame] | 4368 | const CXIdxDeclInfo *declInfo; |
Argyrios Kyrtzidis | 792db26 | 2012-02-28 17:50:33 +0000 | [diff] [blame] | 4369 | const CXIdxEntityInfo *getter; |
| 4370 | const CXIdxEntityInfo *setter; |
| 4371 | } CXIdxObjCPropertyDeclInfo; |
| 4372 | |
| 4373 | typedef struct { |
| 4374 | const CXIdxDeclInfo *declInfo; |
Argyrios Kyrtzidis | 2957e6f | 2011-11-22 07:24:51 +0000 | [diff] [blame] | 4375 | const CXIdxBaseClassInfo *const *bases; |
| 4376 | unsigned numBases; |
| 4377 | } CXIdxCXXClassDeclInfo; |
| 4378 | |
Argyrios Kyrtzidis | bd0ddf8 | 2011-10-27 17:36:12 +0000 | [diff] [blame] | 4379 | /** |
| 4380 | * \brief Data for \see indexEntityReference callback. |
| 4381 | */ |
Argyrios Kyrtzidis | aca19be | 2011-10-18 15:50:50 +0000 | [diff] [blame] | 4382 | typedef enum { |
Argyrios Kyrtzidis | bd0ddf8 | 2011-10-27 17:36:12 +0000 | [diff] [blame] | 4383 | /** |
| 4384 | * \brief The entity is referenced directly in user's code. |
| 4385 | */ |
Argyrios Kyrtzidis | aca19be | 2011-10-18 15:50:50 +0000 | [diff] [blame] | 4386 | CXIdxEntityRef_Direct = 1, |
Argyrios Kyrtzidis | bd0ddf8 | 2011-10-27 17:36:12 +0000 | [diff] [blame] | 4387 | /** |
Argyrios Kyrtzidis | b395c63 | 2011-11-18 00:26:51 +0000 | [diff] [blame] | 4388 | * \brief An implicit reference, e.g. a reference of an ObjC method via the |
| 4389 | * dot syntax. |
Argyrios Kyrtzidis | bd0ddf8 | 2011-10-27 17:36:12 +0000 | [diff] [blame] | 4390 | */ |
Argyrios Kyrtzidis | b395c63 | 2011-11-18 00:26:51 +0000 | [diff] [blame] | 4391 | CXIdxEntityRef_Implicit = 2 |
Argyrios Kyrtzidis | aca19be | 2011-10-18 15:50:50 +0000 | [diff] [blame] | 4392 | } CXIdxEntityRefKind; |
| 4393 | |
Argyrios Kyrtzidis | bd0ddf8 | 2011-10-27 17:36:12 +0000 | [diff] [blame] | 4394 | /** |
| 4395 | * \brief Data for \see indexEntityReference callback. |
| 4396 | */ |
Argyrios Kyrtzidis | 4e7064f | 2011-10-17 19:48:19 +0000 | [diff] [blame] | 4397 | typedef struct { |
Argyrios Kyrtzidis | b1febb6 | 2011-12-07 20:44:19 +0000 | [diff] [blame] | 4398 | CXIdxEntityRefKind kind; |
Argyrios Kyrtzidis | bd0ddf8 | 2011-10-27 17:36:12 +0000 | [diff] [blame] | 4399 | /** |
| 4400 | * \brief Reference cursor. |
| 4401 | */ |
Argyrios Kyrtzidis | 4e7064f | 2011-10-17 19:48:19 +0000 | [diff] [blame] | 4402 | CXCursor cursor; |
| 4403 | CXIdxLoc loc; |
Argyrios Kyrtzidis | bd0ddf8 | 2011-10-27 17:36:12 +0000 | [diff] [blame] | 4404 | /** |
| 4405 | * \brief The entity that gets referenced. |
| 4406 | */ |
Argyrios Kyrtzidis | 6ec43ad | 2011-11-12 02:16:30 +0000 | [diff] [blame] | 4407 | const CXIdxEntityInfo *referencedEntity; |
Argyrios Kyrtzidis | bd0ddf8 | 2011-10-27 17:36:12 +0000 | [diff] [blame] | 4408 | /** |
| 4409 | * \brief Immediate "parent" of the reference. For example: |
| 4410 | * |
| 4411 | * \code |
| 4412 | * Foo *var; |
| 4413 | * \endcode |
| 4414 | * |
| 4415 | * The parent of reference of type 'Foo' is the variable 'var'. |
Argyrios Kyrtzidis | e422e45 | 2011-12-13 18:47:41 +0000 | [diff] [blame] | 4416 | * For references inside statement bodies of functions/methods, |
| 4417 | * the parentEntity will be the function/method. |
Argyrios Kyrtzidis | bd0ddf8 | 2011-10-27 17:36:12 +0000 | [diff] [blame] | 4418 | */ |
Argyrios Kyrtzidis | 6ec43ad | 2011-11-12 02:16:30 +0000 | [diff] [blame] | 4419 | const CXIdxEntityInfo *parentEntity; |
Argyrios Kyrtzidis | bd0ddf8 | 2011-10-27 17:36:12 +0000 | [diff] [blame] | 4420 | /** |
Argyrios Kyrtzidis | e422e45 | 2011-12-13 18:47:41 +0000 | [diff] [blame] | 4421 | * \brief Lexical container context of the reference. |
Argyrios Kyrtzidis | bd0ddf8 | 2011-10-27 17:36:12 +0000 | [diff] [blame] | 4422 | */ |
Argyrios Kyrtzidis | 2957e6f | 2011-11-22 07:24:51 +0000 | [diff] [blame] | 4423 | const CXIdxContainerInfo *container; |
Argyrios Kyrtzidis | 4e7064f | 2011-10-17 19:48:19 +0000 | [diff] [blame] | 4424 | } CXIdxEntityRefInfo; |
| 4425 | |
| 4426 | typedef struct { |
Argyrios Kyrtzidis | bd0ddf8 | 2011-10-27 17:36:12 +0000 | [diff] [blame] | 4427 | /** |
Argyrios Kyrtzidis | 6ec43ad | 2011-11-12 02:16:30 +0000 | [diff] [blame] | 4428 | * \brief Called periodically to check whether indexing should be aborted. |
| 4429 | * Should return 0 to continue, and non-zero to abort. |
| 4430 | */ |
| 4431 | int (*abortQuery)(CXClientData client_data, void *reserved); |
| 4432 | |
| 4433 | /** |
Argyrios Kyrtzidis | b395c63 | 2011-11-18 00:26:51 +0000 | [diff] [blame] | 4434 | * \brief Called at the end of indexing; passes the complete diagnostic set. |
Argyrios Kyrtzidis | bd0ddf8 | 2011-10-27 17:36:12 +0000 | [diff] [blame] | 4435 | */ |
Argyrios Kyrtzidis | 4e7064f | 2011-10-17 19:48:19 +0000 | [diff] [blame] | 4436 | void (*diagnostic)(CXClientData client_data, |
Argyrios Kyrtzidis | b395c63 | 2011-11-18 00:26:51 +0000 | [diff] [blame] | 4437 | CXDiagnosticSet, void *reserved); |
Argyrios Kyrtzidis | 4e7064f | 2011-10-17 19:48:19 +0000 | [diff] [blame] | 4438 | |
Argyrios Kyrtzidis | dd93c59 | 2011-11-11 00:23:36 +0000 | [diff] [blame] | 4439 | CXIdxClientFile (*enteredMainFile)(CXClientData client_data, |
| 4440 | CXFile mainFile, void *reserved); |
| 4441 | |
Argyrios Kyrtzidis | bd0ddf8 | 2011-10-27 17:36:12 +0000 | [diff] [blame] | 4442 | /** |
| 4443 | * \brief Called when a file gets #included/#imported. |
| 4444 | */ |
Argyrios Kyrtzidis | dd93c59 | 2011-11-11 00:23:36 +0000 | [diff] [blame] | 4445 | CXIdxClientFile (*ppIncludedFile)(CXClientData client_data, |
Argyrios Kyrtzidis | 6ec43ad | 2011-11-12 02:16:30 +0000 | [diff] [blame] | 4446 | const CXIdxIncludedFileInfo *); |
Argyrios Kyrtzidis | 4e7064f | 2011-10-17 19:48:19 +0000 | [diff] [blame] | 4447 | |
Argyrios Kyrtzidis | bd0ddf8 | 2011-10-27 17:36:12 +0000 | [diff] [blame] | 4448 | /** |
| 4449 | * \brief Called when a AST file (PCH or module) gets imported. |
| 4450 | * |
| 4451 | * AST files will not get indexed (there will not be callbacks to index all |
| 4452 | * the entities in an AST file). The recommended action is that, if the AST |
| 4453 | * file is not already indexed, to block further indexing and initiate a new |
Argyrios Kyrtzidis | 6ec43ad | 2011-11-12 02:16:30 +0000 | [diff] [blame] | 4454 | * indexing job specific to the AST file. |
Argyrios Kyrtzidis | bd0ddf8 | 2011-10-27 17:36:12 +0000 | [diff] [blame] | 4455 | */ |
Argyrios Kyrtzidis | dd93c59 | 2011-11-11 00:23:36 +0000 | [diff] [blame] | 4456 | CXIdxClientASTFile (*importedASTFile)(CXClientData client_data, |
Argyrios Kyrtzidis | 6ec43ad | 2011-11-12 02:16:30 +0000 | [diff] [blame] | 4457 | const CXIdxImportedASTFileInfo *); |
Argyrios Kyrtzidis | 4e7064f | 2011-10-17 19:48:19 +0000 | [diff] [blame] | 4458 | |
Argyrios Kyrtzidis | bd0ddf8 | 2011-10-27 17:36:12 +0000 | [diff] [blame] | 4459 | /** |
| 4460 | * \brief Called at the beginning of indexing a translation unit. |
| 4461 | */ |
Argyrios Kyrtzidis | dd93c59 | 2011-11-11 00:23:36 +0000 | [diff] [blame] | 4462 | CXIdxClientContainer (*startedTranslationUnit)(CXClientData client_data, |
Argyrios Kyrtzidis | 6ec43ad | 2011-11-12 02:16:30 +0000 | [diff] [blame] | 4463 | void *reserved); |
Argyrios Kyrtzidis | 4e7064f | 2011-10-17 19:48:19 +0000 | [diff] [blame] | 4464 | |
Argyrios Kyrtzidis | 6ec43ad | 2011-11-12 02:16:30 +0000 | [diff] [blame] | 4465 | void (*indexDeclaration)(CXClientData client_data, |
Argyrios Kyrtzidis | 2957e6f | 2011-11-22 07:24:51 +0000 | [diff] [blame] | 4466 | const CXIdxDeclInfo *); |
Argyrios Kyrtzidis | 4e7064f | 2011-10-17 19:48:19 +0000 | [diff] [blame] | 4467 | |
Argyrios Kyrtzidis | bd0ddf8 | 2011-10-27 17:36:12 +0000 | [diff] [blame] | 4468 | /** |
| 4469 | * \brief Called to index a reference of an entity. |
| 4470 | */ |
Argyrios Kyrtzidis | 4e7064f | 2011-10-17 19:48:19 +0000 | [diff] [blame] | 4471 | void (*indexEntityReference)(CXClientData client_data, |
Argyrios Kyrtzidis | 6ec43ad | 2011-11-12 02:16:30 +0000 | [diff] [blame] | 4472 | const CXIdxEntityRefInfo *); |
Argyrios Kyrtzidis | 4e7064f | 2011-10-17 19:48:19 +0000 | [diff] [blame] | 4473 | |
| 4474 | } IndexerCallbacks; |
| 4475 | |
NAKAMURA Takumi | ab336c1 | 2011-11-11 02:51:09 +0000 | [diff] [blame] | 4476 | CINDEX_LINKAGE int clang_index_isEntityObjCContainerKind(CXIdxEntityKind); |
Argyrios Kyrtzidis | 6ec43ad | 2011-11-12 02:16:30 +0000 | [diff] [blame] | 4477 | CINDEX_LINKAGE const CXIdxObjCContainerDeclInfo * |
| 4478 | clang_index_getObjCContainerDeclInfo(const CXIdxDeclInfo *); |
Argyrios Kyrtzidis | dd93c59 | 2011-11-11 00:23:36 +0000 | [diff] [blame] | 4479 | |
Argyrios Kyrtzidis | 6ec43ad | 2011-11-12 02:16:30 +0000 | [diff] [blame] | 4480 | CINDEX_LINKAGE const CXIdxObjCInterfaceDeclInfo * |
| 4481 | clang_index_getObjCInterfaceDeclInfo(const CXIdxDeclInfo *); |
| 4482 | |
NAKAMURA Takumi | ab336c1 | 2011-11-11 02:51:09 +0000 | [diff] [blame] | 4483 | CINDEX_LINKAGE |
Argyrios Kyrtzidis | 6ec43ad | 2011-11-12 02:16:30 +0000 | [diff] [blame] | 4484 | const CXIdxObjCCategoryDeclInfo * |
| 4485 | clang_index_getObjCCategoryDeclInfo(const CXIdxDeclInfo *); |
| 4486 | |
Argyrios Kyrtzidis | c71d554 | 2011-11-14 22:39:19 +0000 | [diff] [blame] | 4487 | CINDEX_LINKAGE const CXIdxObjCProtocolRefListInfo * |
| 4488 | clang_index_getObjCProtocolRefListInfo(const CXIdxDeclInfo *); |
Argyrios Kyrtzidis | dd93c59 | 2011-11-11 00:23:36 +0000 | [diff] [blame] | 4489 | |
Argyrios Kyrtzidis | 792db26 | 2012-02-28 17:50:33 +0000 | [diff] [blame] | 4490 | CINDEX_LINKAGE const CXIdxObjCPropertyDeclInfo * |
| 4491 | clang_index_getObjCPropertyDeclInfo(const CXIdxDeclInfo *); |
| 4492 | |
Argyrios Kyrtzidis | b395c63 | 2011-11-18 00:26:51 +0000 | [diff] [blame] | 4493 | CINDEX_LINKAGE const CXIdxIBOutletCollectionAttrInfo * |
| 4494 | clang_index_getIBOutletCollectionAttrInfo(const CXIdxAttrInfo *); |
| 4495 | |
Argyrios Kyrtzidis | 2957e6f | 2011-11-22 07:24:51 +0000 | [diff] [blame] | 4496 | CINDEX_LINKAGE const CXIdxCXXClassDeclInfo * |
| 4497 | clang_index_getCXXClassDeclInfo(const CXIdxDeclInfo *); |
| 4498 | |
| 4499 | /** |
| 4500 | * \brief For retrieving a custom CXIdxClientContainer attached to a |
| 4501 | * container. |
| 4502 | */ |
| 4503 | CINDEX_LINKAGE CXIdxClientContainer |
| 4504 | clang_index_getClientContainer(const CXIdxContainerInfo *); |
| 4505 | |
| 4506 | /** |
| 4507 | * \brief For setting a custom CXIdxClientContainer attached to a |
| 4508 | * container. |
| 4509 | */ |
| 4510 | CINDEX_LINKAGE void |
| 4511 | clang_index_setClientContainer(const CXIdxContainerInfo *,CXIdxClientContainer); |
| 4512 | |
| 4513 | /** |
| 4514 | * \brief For retrieving a custom CXIdxClientEntity attached to an entity. |
| 4515 | */ |
| 4516 | CINDEX_LINKAGE CXIdxClientEntity |
| 4517 | clang_index_getClientEntity(const CXIdxEntityInfo *); |
| 4518 | |
| 4519 | /** |
| 4520 | * \brief For setting a custom CXIdxClientEntity attached to an entity. |
| 4521 | */ |
| 4522 | CINDEX_LINKAGE void |
| 4523 | clang_index_setClientEntity(const CXIdxEntityInfo *, CXIdxClientEntity); |
| 4524 | |
| 4525 | /** |
| 4526 | * \brief An indexing action, to be applied to one or multiple translation units |
| 4527 | * but not on concurrent threads. If there are threads doing indexing |
| 4528 | * concurrently, they should use different CXIndexAction objects. |
| 4529 | */ |
| 4530 | typedef void *CXIndexAction; |
| 4531 | |
| 4532 | /** |
| 4533 | * \brief An indexing action, to be applied to one or multiple translation units |
| 4534 | * but not on concurrent threads. If there are threads doing indexing |
| 4535 | * concurrently, they should use different CXIndexAction objects. |
| 4536 | * |
| 4537 | * \param CIdx The index object with which the index action will be associated. |
| 4538 | */ |
| 4539 | CINDEX_LINKAGE CXIndexAction clang_IndexAction_create(CXIndex CIdx); |
| 4540 | |
| 4541 | /** |
| 4542 | * \brief Destroy the given index action. |
| 4543 | * |
| 4544 | * The index action must not be destroyed until all of the translation units |
| 4545 | * created within that index action have been destroyed. |
| 4546 | */ |
| 4547 | CINDEX_LINKAGE void clang_IndexAction_dispose(CXIndexAction); |
| 4548 | |
Argyrios Kyrtzidis | 21ee570 | 2011-11-15 06:20:16 +0000 | [diff] [blame] | 4549 | typedef enum { |
| 4550 | /** |
| 4551 | * \brief Used to indicate that no special indexing options are needed. |
| 4552 | */ |
| 4553 | CXIndexOpt_None = 0x0, |
| 4554 | |
| 4555 | /** |
| 4556 | * \brief Used to indicate that \see indexEntityReference should be invoked |
Argyrios Kyrtzidis | b395c63 | 2011-11-18 00:26:51 +0000 | [diff] [blame] | 4557 | * for only one reference of an entity per source file that does not also |
| 4558 | * include a declaration/definition of the entity. |
Argyrios Kyrtzidis | 21ee570 | 2011-11-15 06:20:16 +0000 | [diff] [blame] | 4559 | */ |
Argyrios Kyrtzidis | 2249074 | 2012-01-14 00:11:49 +0000 | [diff] [blame] | 4560 | CXIndexOpt_SuppressRedundantRefs = 0x1, |
| 4561 | |
| 4562 | /** |
| 4563 | * \brief Function-local symbols should be indexed. If this is not set |
| 4564 | * function-local symbols will be ignored. |
| 4565 | */ |
Argyrios Kyrtzidis | 58d2dbe | 2012-02-14 22:23:11 +0000 | [diff] [blame] | 4566 | CXIndexOpt_IndexFunctionLocalSymbols = 0x2, |
| 4567 | |
| 4568 | /** |
| 4569 | * \brief Implicit function/class template instantiations should be indexed. |
| 4570 | * If this is not set, implicit instantiations will be ignored. |
| 4571 | */ |
Argyrios Kyrtzidis | b49a29f | 2012-03-27 21:38:03 +0000 | [diff] [blame] | 4572 | CXIndexOpt_IndexImplicitTemplateInstantiations = 0x4, |
| 4573 | |
| 4574 | /** |
| 4575 | * \brief Suppress all compiler warnings when parsing for indexing. |
| 4576 | */ |
| 4577 | CXIndexOpt_SuppressWarnings = 0x8 |
Argyrios Kyrtzidis | 21ee570 | 2011-11-15 06:20:16 +0000 | [diff] [blame] | 4578 | } CXIndexOptFlags; |
| 4579 | |
Argyrios Kyrtzidis | bd0ddf8 | 2011-10-27 17:36:12 +0000 | [diff] [blame] | 4580 | /** |
| 4581 | * \brief Index the given source file and the translation unit corresponding |
| 4582 | * to that file via callbacks implemented through \see IndexerCallbacks. |
| 4583 | * |
| 4584 | * \param client_data pointer data supplied by the client, which will |
| 4585 | * be passed to the invoked callbacks. |
| 4586 | * |
| 4587 | * \param index_callbacks Pointer to indexing callbacks that the client |
| 4588 | * implements. |
| 4589 | * |
| 4590 | * \param index_callbacks_size Size of \see IndexerCallbacks structure that gets |
| 4591 | * passed in index_callbacks. |
| 4592 | * |
Argyrios Kyrtzidis | 21ee570 | 2011-11-15 06:20:16 +0000 | [diff] [blame] | 4593 | * \param index_options A bitmask of options that affects how indexing is |
| 4594 | * performed. This should be a bitwise OR of the CXIndexOpt_XXX flags. |
Argyrios Kyrtzidis | bd0ddf8 | 2011-10-27 17:36:12 +0000 | [diff] [blame] | 4595 | * |
| 4596 | * \param out_TU [out] pointer to store a CXTranslationUnit that can be reused |
| 4597 | * after indexing is finished. Set to NULL if you do not require it. |
| 4598 | * |
Argyrios Kyrtzidis | 21ee570 | 2011-11-15 06:20:16 +0000 | [diff] [blame] | 4599 | * \returns If there is a failure from which the there is no recovery, returns |
Argyrios Kyrtzidis | bd0ddf8 | 2011-10-27 17:36:12 +0000 | [diff] [blame] | 4600 | * non-zero, otherwise returns 0. |
Argyrios Kyrtzidis | 21ee570 | 2011-11-15 06:20:16 +0000 | [diff] [blame] | 4601 | * |
Argyrios Kyrtzidis | bd0ddf8 | 2011-10-27 17:36:12 +0000 | [diff] [blame] | 4602 | * The rest of the parameters are the same as \see clang_parseTranslationUnit. |
| 4603 | */ |
Argyrios Kyrtzidis | 2957e6f | 2011-11-22 07:24:51 +0000 | [diff] [blame] | 4604 | CINDEX_LINKAGE int clang_indexSourceFile(CXIndexAction, |
Argyrios Kyrtzidis | 4e7064f | 2011-10-17 19:48:19 +0000 | [diff] [blame] | 4605 | CXClientData client_data, |
| 4606 | IndexerCallbacks *index_callbacks, |
| 4607 | unsigned index_callbacks_size, |
| 4608 | unsigned index_options, |
| 4609 | const char *source_filename, |
| 4610 | const char * const *command_line_args, |
| 4611 | int num_command_line_args, |
| 4612 | struct CXUnsavedFile *unsaved_files, |
| 4613 | unsigned num_unsaved_files, |
| 4614 | CXTranslationUnit *out_TU, |
| 4615 | unsigned TU_options); |
| 4616 | |
Argyrios Kyrtzidis | bd0ddf8 | 2011-10-27 17:36:12 +0000 | [diff] [blame] | 4617 | /** |
Argyrios Kyrtzidis | 21ee570 | 2011-11-15 06:20:16 +0000 | [diff] [blame] | 4618 | * \brief Index the given translation unit via callbacks implemented through |
| 4619 | * \see IndexerCallbacks. |
| 4620 | * |
| 4621 | * The order of callback invocations is not guaranteed to be the same as |
| 4622 | * when indexing a source file. The high level order will be: |
| 4623 | * |
| 4624 | * -Preprocessor callbacks invocations |
| 4625 | * -Declaration/reference callbacks invocations |
| 4626 | * -Diagnostic callback invocations |
| 4627 | * |
| 4628 | * The parameters are the same as \see clang_indexSourceFile. |
| 4629 | * |
| 4630 | * \returns If there is a failure from which the there is no recovery, returns |
| 4631 | * non-zero, otherwise returns 0. |
| 4632 | */ |
Argyrios Kyrtzidis | 2957e6f | 2011-11-22 07:24:51 +0000 | [diff] [blame] | 4633 | CINDEX_LINKAGE int clang_indexTranslationUnit(CXIndexAction, |
Argyrios Kyrtzidis | 21ee570 | 2011-11-15 06:20:16 +0000 | [diff] [blame] | 4634 | CXClientData client_data, |
| 4635 | IndexerCallbacks *index_callbacks, |
| 4636 | unsigned index_callbacks_size, |
Argyrios Kyrtzidis | 2957e6f | 2011-11-22 07:24:51 +0000 | [diff] [blame] | 4637 | unsigned index_options, |
| 4638 | CXTranslationUnit); |
Argyrios Kyrtzidis | 21ee570 | 2011-11-15 06:20:16 +0000 | [diff] [blame] | 4639 | |
| 4640 | /** |
Argyrios Kyrtzidis | bd0ddf8 | 2011-10-27 17:36:12 +0000 | [diff] [blame] | 4641 | * \brief Retrieve the CXIdxFile, file, line, column, and offset represented by |
| 4642 | * the given CXIdxLoc. |
| 4643 | * |
| 4644 | * If the location refers into a macro expansion, retrieves the |
| 4645 | * location of the macro expansion and if it refers into a macro argument |
| 4646 | * retrieves the location of the argument. |
| 4647 | */ |
Argyrios Kyrtzidis | 4e7064f | 2011-10-17 19:48:19 +0000 | [diff] [blame] | 4648 | CINDEX_LINKAGE void clang_indexLoc_getFileLocation(CXIdxLoc loc, |
Argyrios Kyrtzidis | dd93c59 | 2011-11-11 00:23:36 +0000 | [diff] [blame] | 4649 | CXIdxClientFile *indexFile, |
Argyrios Kyrtzidis | 4e7064f | 2011-10-17 19:48:19 +0000 | [diff] [blame] | 4650 | CXFile *file, |
| 4651 | unsigned *line, |
| 4652 | unsigned *column, |
| 4653 | unsigned *offset); |
| 4654 | |
Argyrios Kyrtzidis | bd0ddf8 | 2011-10-27 17:36:12 +0000 | [diff] [blame] | 4655 | /** |
| 4656 | * \brief Retrieve the CXSourceLocation represented by the given CXIdxLoc. |
| 4657 | */ |
Argyrios Kyrtzidis | 4e7064f | 2011-10-17 19:48:19 +0000 | [diff] [blame] | 4658 | CINDEX_LINKAGE |
| 4659 | CXSourceLocation clang_indexLoc_getCXSourceLocation(CXIdxLoc loc); |
| 4660 | |
Argyrios Kyrtzidis | aed123e | 2011-10-06 07:00:54 +0000 | [diff] [blame] | 4661 | /** |
| 4662 | * @} |
| 4663 | */ |
| 4664 | |
Douglas Gregor | c42fefa | 2010-01-22 22:29:16 +0000 | [diff] [blame] | 4665 | /** |
| 4666 | * @} |
| 4667 | */ |
Daniel Dunbar | 1efcf3d | 2010-01-24 02:54:26 +0000 | [diff] [blame] | 4668 | |
Ted Kremenek | d2fa566 | 2009-08-26 22:36:44 +0000 | [diff] [blame] | 4669 | #ifdef __cplusplus |
| 4670 | } |
| 4671 | #endif |
| 4672 | #endif |
| 4673 | |