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