Index.h revision 234353
1198092Srdivacky/*===-- clang-c/Index.h - Indexing Public C Interface -------------*- C -*-===*\ 2198092Srdivacky|* *| 3198092Srdivacky|* The LLVM Compiler Infrastructure *| 4198092Srdivacky|* *| 5198092Srdivacky|* This file is distributed under the University of Illinois Open Source *| 6198092Srdivacky|* License. See LICENSE.TXT for details. *| 7198092Srdivacky|* *| 8198092Srdivacky|*===----------------------------------------------------------------------===*| 9198092Srdivacky|* *| 10198092Srdivacky|* This header provides a public inferface to a Clang library for extracting *| 11198092Srdivacky|* high-level symbol information from source files without exposing the full *| 12198092Srdivacky|* Clang C++ API. *| 13198092Srdivacky|* *| 14198092Srdivacky\*===----------------------------------------------------------------------===*/ 15198092Srdivacky 16198092Srdivacky#ifndef CLANG_C_INDEX_H 17198092Srdivacky#define CLANG_C_INDEX_H 18198092Srdivacky 19198893Srdivacky#include <sys/stat.h> 20201361Srdivacky#include <time.h> 21204643Srdivacky#include <stdio.h> 22198893Srdivacky 23198092Srdivacky#ifdef __cplusplus 24198092Srdivackyextern "C" { 25198092Srdivacky#endif 26198092Srdivacky 27198893Srdivacky/* MSVC DLL import/export. */ 28198893Srdivacky#ifdef _MSC_VER 29198893Srdivacky #ifdef _CINDEX_LIB_ 30198893Srdivacky #define CINDEX_LINKAGE __declspec(dllexport) 31198893Srdivacky #else 32198893Srdivacky #define CINDEX_LINKAGE __declspec(dllimport) 33198893Srdivacky #endif 34198893Srdivacky#else 35198893Srdivacky #define CINDEX_LINKAGE 36198893Srdivacky#endif 37198893Srdivacky 38234353Sdim#ifdef __GNUC__ 39234353Sdim #define CINDEX_DEPRECATED __attribute__((deprecated)) 40234353Sdim#else 41234353Sdim #ifdef _MSC_VER 42234353Sdim #define CINDEX_DEPRECATED __declspec(deprecated) 43234353Sdim #else 44234353Sdim #define CINDEX_DEPRECATED 45234353Sdim #endif 46234353Sdim#endif 47234353Sdim 48219077Sdim/** \defgroup CINDEX libclang: C Interface to Clang 49202879Srdivacky * 50203955Srdivacky * The C Interface to Clang provides a relatively small API that exposes 51202879Srdivacky * facilities for parsing source code into an abstract syntax tree (AST), 52202879Srdivacky * loading already-parsed ASTs, traversing the AST, associating 53202879Srdivacky * physical source locations with elements within the AST, and other 54202879Srdivacky * facilities that support Clang-based development tools. 55202879Srdivacky * 56203955Srdivacky * This C interface to Clang will never provide all of the information 57202879Srdivacky * representation stored in Clang's C++ AST, nor should it: the intent is to 58202879Srdivacky * maintain an API that is relatively stable from one release to the next, 59202879Srdivacky * providing only the basic functionality needed to support development tools. 60203955Srdivacky * 61203955Srdivacky * To avoid namespace pollution, data types are prefixed with "CX" and 62202879Srdivacky * functions are prefixed with "clang_". 63202879Srdivacky * 64202879Srdivacky * @{ 65202879Srdivacky */ 66203955Srdivacky 67202879Srdivacky/** 68202879Srdivacky * \brief An "index" that consists of a set of translation units that would 69202879Srdivacky * typically be linked together into an executable or library. 70202879Srdivacky */ 71202879Srdivackytypedef void *CXIndex; 72198092Srdivacky 73202879Srdivacky/** 74202879Srdivacky * \brief A single translation unit, which resides in an index. 75202879Srdivacky */ 76218893Sdimtypedef struct CXTranslationUnitImpl *CXTranslationUnit; 77198092Srdivacky 78200583Srdivacky/** 79202879Srdivacky * \brief Opaque pointer representing client data that will be passed through 80202879Srdivacky * to various callbacks and visitors. 81202879Srdivacky */ 82202879Srdivackytypedef void *CXClientData; 83203955Srdivacky 84202879Srdivacky/** 85200583Srdivacky * \brief Provides the contents of a file that has not yet been saved to disk. 86200583Srdivacky * 87200583Srdivacky * Each CXUnsavedFile instance provides the name of a file on the 88200583Srdivacky * system along with the current contents of that file that have not 89200583Srdivacky * yet been saved to disk. 90200583Srdivacky */ 91200583Srdivackystruct CXUnsavedFile { 92203955Srdivacky /** 93203955Srdivacky * \brief The file whose contents have not yet been saved. 94200583Srdivacky * 95200583Srdivacky * This file must already exist in the file system. 96200583Srdivacky */ 97200583Srdivacky const char *Filename; 98200583Srdivacky 99203955Srdivacky /** 100204643Srdivacky * \brief A buffer containing the unsaved contents of this file. 101200583Srdivacky */ 102200583Srdivacky const char *Contents; 103200583Srdivacky 104200583Srdivacky /** 105204643Srdivacky * \brief The length of the unsaved contents of this buffer. 106200583Srdivacky */ 107200583Srdivacky unsigned long Length; 108200583Srdivacky}; 109200583Srdivacky 110199482Srdivacky/** 111212904Sdim * \brief Describes the availability of a particular entity, which indicates 112212904Sdim * whether the use of this entity will result in a warning or error due to 113212904Sdim * it being deprecated or unavailable. 114212904Sdim */ 115212904Sdimenum CXAvailabilityKind { 116212904Sdim /** 117212904Sdim * \brief The entity is available. 118212904Sdim */ 119212904Sdim CXAvailability_Available, 120212904Sdim /** 121212904Sdim * \brief The entity is available, but has been deprecated (and its use is 122212904Sdim * not recommended). 123212904Sdim */ 124212904Sdim CXAvailability_Deprecated, 125212904Sdim /** 126212904Sdim * \brief The entity is not available; any use of it will be an error. 127212904Sdim */ 128226633Sdim CXAvailability_NotAvailable, 129226633Sdim /** 130226633Sdim * \brief The entity is available, but not accessible; any use of it will be 131226633Sdim * an error. 132226633Sdim */ 133226633Sdim CXAvailability_NotAccessible 134212904Sdim}; 135212904Sdim 136212904Sdim/** 137202879Srdivacky * \defgroup CINDEX_STRING String manipulation routines 138202879Srdivacky * 139202879Srdivacky * @{ 140199482Srdivacky */ 141203955Srdivacky 142202879Srdivacky/** 143202879Srdivacky * \brief A character string. 144202879Srdivacky * 145202879Srdivacky * The \c CXString type is used to return strings from the interface when 146202879Srdivacky * the ownership of that string might different from one call to the next. 147202879Srdivacky * Use \c clang_getCString() to retrieve the string data and, once finished 148202879Srdivacky * with the string data, call \c clang_disposeString() to free the string. 149202879Srdivacky */ 150199482Srdivackytypedef struct { 151218893Sdim void *data; 152218893Sdim unsigned private_flags; 153199482Srdivacky} CXString; 154199482Srdivacky 155202879Srdivacky/** 156202879Srdivacky * \brief Retrieve the character data associated with the given string. 157202879Srdivacky */ 158199482SrdivackyCINDEX_LINKAGE const char *clang_getCString(CXString string); 159199482Srdivacky 160202879Srdivacky/** 161202879Srdivacky * \brief Free the given string, 162202879Srdivacky */ 163199482SrdivackyCINDEX_LINKAGE void clang_disposeString(CXString string); 164199482Srdivacky 165202879Srdivacky/** 166202879Srdivacky * @} 167202879Srdivacky */ 168203955Srdivacky 169203955Srdivacky/** 170198398Srdivacky * \brief clang_createIndex() provides a shared context for creating 171198398Srdivacky * translation units. It provides two options: 172198398Srdivacky * 173198398Srdivacky * - excludeDeclarationsFromPCH: When non-zero, allows enumeration of "local" 174198398Srdivacky * declarations (when loading any new translation units). A "local" declaration 175203955Srdivacky * is one that belongs in the translation unit itself and not in a precompiled 176198398Srdivacky * header that was used by the translation unit. If zero, all declarations 177198398Srdivacky * will be enumerated. 178198398Srdivacky * 179198398Srdivacky * Here is an example: 180198398Srdivacky * 181204643Srdivacky * // excludeDeclsFromPCH = 1, displayDiagnostics=1 182204643Srdivacky * Idx = clang_createIndex(1, 1); 183198398Srdivacky * 184198398Srdivacky * // IndexTest.pch was produced with the following command: 185198398Srdivacky * // "clang -x c IndexTest.h -emit-ast -o IndexTest.pch" 186198398Srdivacky * TU = clang_createTranslationUnit(Idx, "IndexTest.pch"); 187198398Srdivacky * 188198398Srdivacky * // This will load all the symbols from 'IndexTest.pch' 189203955Srdivacky * clang_visitChildren(clang_getTranslationUnitCursor(TU), 190202879Srdivacky * TranslationUnitVisitor, 0); 191198398Srdivacky * clang_disposeTranslationUnit(TU); 192198398Srdivacky * 193198398Srdivacky * // This will load all the symbols from 'IndexTest.c', excluding symbols 194198398Srdivacky * // from 'IndexTest.pch'. 195203955Srdivacky * char *args[] = { "-Xclang", "-include-pch=IndexTest.pch" }; 196203955Srdivacky * TU = clang_createTranslationUnitFromSourceFile(Idx, "IndexTest.c", 2, args, 197203955Srdivacky * 0, 0); 198202879Srdivacky * clang_visitChildren(clang_getTranslationUnitCursor(TU), 199202879Srdivacky * TranslationUnitVisitor, 0); 200198398Srdivacky * clang_disposeTranslationUnit(TU); 201198398Srdivacky * 202198398Srdivacky * This process of creating the 'pch', loading it separately, and using it (via 203198398Srdivacky * -include-pch) allows 'excludeDeclsFromPCH' to remove redundant callbacks 204198398Srdivacky * (which gives the indexer the same performance benefit as the compiler). 205198398Srdivacky */ 206204643SrdivackyCINDEX_LINKAGE CXIndex clang_createIndex(int excludeDeclarationsFromPCH, 207204643Srdivacky int displayDiagnostics); 208205219Srdivacky 209203955Srdivacky/** 210203955Srdivacky * \brief Destroy the given index. 211203955Srdivacky * 212203955Srdivacky * The index must not be destroyed until all of the translation units created 213203955Srdivacky * within that index have been destroyed. 214203955Srdivacky */ 215200583SrdivackyCINDEX_LINKAGE void clang_disposeIndex(CXIndex index); 216198092Srdivacky 217234353Sdimtypedef enum { 218234353Sdim /** 219234353Sdim * \brief Used to indicate that no special CXIndex options are needed. 220234353Sdim */ 221234353Sdim CXGlobalOpt_None = 0x0, 222234353Sdim 223234353Sdim /** 224234353Sdim * \brief Used to indicate that threads that libclang creates for indexing 225234353Sdim * purposes should use background priority. 226234353Sdim * Affects \see clang_indexSourceFile, \see clang_indexTranslationUnit, 227234353Sdim * \see clang_parseTranslationUnit, \see clang_saveTranslationUnit. 228234353Sdim */ 229234353Sdim CXGlobalOpt_ThreadBackgroundPriorityForIndexing = 0x1, 230234353Sdim 231234353Sdim /** 232234353Sdim * \brief Used to indicate that threads that libclang creates for editing 233234353Sdim * purposes should use background priority. 234234353Sdim * Affects \see clang_reparseTranslationUnit, \see clang_codeCompleteAt, 235234353Sdim * \see clang_annotateTokens 236234353Sdim */ 237234353Sdim CXGlobalOpt_ThreadBackgroundPriorityForEditing = 0x2, 238234353Sdim 239234353Sdim /** 240234353Sdim * \brief Used to indicate that all threads that libclang creates should use 241234353Sdim * background priority. 242234353Sdim */ 243234353Sdim CXGlobalOpt_ThreadBackgroundPriorityForAll = 244234353Sdim CXGlobalOpt_ThreadBackgroundPriorityForIndexing | 245234353Sdim CXGlobalOpt_ThreadBackgroundPriorityForEditing 246234353Sdim 247234353Sdim} CXGlobalOptFlags; 248234353Sdim 249202879Srdivacky/** 250234353Sdim * \brief Sets general options associated with a CXIndex. 251234353Sdim * 252234353Sdim * For example: 253234353Sdim * \code 254234353Sdim * CXIndex idx = ...; 255234353Sdim * clang_CXIndex_setGlobalOptions(idx, 256234353Sdim * clang_CXIndex_getGlobalOptions(idx) | 257234353Sdim * CXGlobalOpt_ThreadBackgroundPriorityForIndexing); 258234353Sdim * \endcode 259234353Sdim * 260234353Sdim * \param options A bitmask of options, a bitwise OR of CXGlobalOpt_XXX flags. 261234353Sdim */ 262234353SdimCINDEX_LINKAGE void clang_CXIndex_setGlobalOptions(CXIndex, unsigned options); 263234353Sdim 264234353Sdim/** 265234353Sdim * \brief Gets the general options associated with a CXIndex. 266234353Sdim * 267234353Sdim * \returns A bitmask of options, a bitwise OR of CXGlobalOpt_XXX flags that 268234353Sdim * are associated with the given CXIndex object. 269234353Sdim */ 270234353SdimCINDEX_LINKAGE unsigned clang_CXIndex_getGlobalOptions(CXIndex); 271234353Sdim 272234353Sdim/** 273202879Srdivacky * \defgroup CINDEX_FILES File manipulation routines 274202879Srdivacky * 275202879Srdivacky * @{ 276202879Srdivacky */ 277203955Srdivacky 278202879Srdivacky/** 279202879Srdivacky * \brief A particular source file that is part of a translation unit. 280202879Srdivacky */ 281202879Srdivackytypedef void *CXFile; 282198092Srdivacky 283203955Srdivacky 284202879Srdivacky/** 285202879Srdivacky * \brief Retrieve the complete file and path name of the given file. 286202879Srdivacky */ 287204643SrdivackyCINDEX_LINKAGE CXString clang_getFileName(CXFile SFile); 288203955Srdivacky 289202879Srdivacky/** 290202879Srdivacky * \brief Retrieve the last modification time of the given file. 291202879Srdivacky */ 292202879SrdivackyCINDEX_LINKAGE time_t clang_getFileTime(CXFile SFile); 293198092Srdivacky 294202879Srdivacky/** 295223017Sdim * \brief Determine whether the given header is guarded against 296223017Sdim * multiple inclusions, either with the conventional 297223017Sdim * #ifndef/#define/#endif macro guards or with #pragma once. 298223017Sdim */ 299223017SdimCINDEX_LINKAGE unsigned 300223017Sdimclang_isFileMultipleIncludeGuarded(CXTranslationUnit tu, CXFile file); 301223017Sdim 302223017Sdim/** 303202879Srdivacky * \brief Retrieve a file handle within the given translation unit. 304202879Srdivacky * 305202879Srdivacky * \param tu the translation unit 306203955Srdivacky * 307202879Srdivacky * \param file_name the name of the file. 308202879Srdivacky * 309202879Srdivacky * \returns the file handle for the named file in the translation unit \p tu, 310202879Srdivacky * or a NULL file handle if the file was not a part of this translation unit. 311202879Srdivacky */ 312203955SrdivackyCINDEX_LINKAGE CXFile clang_getFile(CXTranslationUnit tu, 313202879Srdivacky const char *file_name); 314203955Srdivacky 315202879Srdivacky/** 316202879Srdivacky * @} 317202879Srdivacky */ 318198092Srdivacky 319202879Srdivacky/** 320202879Srdivacky * \defgroup CINDEX_LOCATIONS Physical source locations 321202879Srdivacky * 322202879Srdivacky * Clang represents physical source locations in its abstract syntax tree in 323202879Srdivacky * great detail, with file, line, and column information for the majority of 324202879Srdivacky * the tokens parsed in the source code. These data types and functions are 325202879Srdivacky * used to represent source location information, either for a particular 326202879Srdivacky * point in the program or for a range of points in the program, and extract 327202879Srdivacky * specific location information from those data types. 328202879Srdivacky * 329202879Srdivacky * @{ 330202879Srdivacky */ 331203955Srdivacky 332202879Srdivacky/** 333202879Srdivacky * \brief Identifies a specific source location within a translation 334202879Srdivacky * unit. 335202879Srdivacky * 336226633Sdim * Use clang_getExpansionLocation() or clang_getSpellingLocation() 337218893Sdim * to map a source location to a particular file, line, and column. 338202879Srdivacky */ 339202879Srdivackytypedef struct { 340203955Srdivacky void *ptr_data[2]; 341202879Srdivacky unsigned int_data; 342202879Srdivacky} CXSourceLocation; 343198092Srdivacky 344202879Srdivacky/** 345203955Srdivacky * \brief Identifies a half-open character range in the source code. 346202879Srdivacky * 347202879Srdivacky * Use clang_getRangeStart() and clang_getRangeEnd() to retrieve the 348202879Srdivacky * starting and end locations from a source range, respectively. 349198893Srdivacky */ 350202879Srdivackytypedef struct { 351203955Srdivacky void *ptr_data[2]; 352202879Srdivacky unsigned begin_int_data; 353202879Srdivacky unsigned end_int_data; 354202879Srdivacky} CXSourceRange; 355198893Srdivacky 356202879Srdivacky/** 357202879Srdivacky * \brief Retrieve a NULL (invalid) source location. 358198092Srdivacky */ 359202879SrdivackyCINDEX_LINKAGE CXSourceLocation clang_getNullLocation(); 360203955Srdivacky 361202879Srdivacky/** 362202879Srdivacky * \determine Determine whether two source locations, which must refer into 363203955Srdivacky * the same translation unit, refer to exactly the same point in the source 364202879Srdivacky * code. 365202879Srdivacky * 366202879Srdivacky * \returns non-zero if the source locations refer to the same location, zero 367202879Srdivacky * if they refer to different locations. 368202879Srdivacky */ 369202879SrdivackyCINDEX_LINKAGE unsigned clang_equalLocations(CXSourceLocation loc1, 370202879Srdivacky CXSourceLocation loc2); 371203955Srdivacky 372202879Srdivacky/** 373203955Srdivacky * \brief Retrieves the source location associated with a given file/line/column 374203955Srdivacky * in a particular translation unit. 375202879Srdivacky */ 376202879SrdivackyCINDEX_LINKAGE CXSourceLocation clang_getLocation(CXTranslationUnit tu, 377202879Srdivacky CXFile file, 378202879Srdivacky unsigned line, 379202879Srdivacky unsigned column); 380218893Sdim/** 381218893Sdim * \brief Retrieves the source location associated with a given character offset 382218893Sdim * in a particular translation unit. 383218893Sdim */ 384218893SdimCINDEX_LINKAGE CXSourceLocation clang_getLocationForOffset(CXTranslationUnit tu, 385218893Sdim CXFile file, 386218893Sdim unsigned offset); 387203955Srdivacky 388203955Srdivacky/** 389203955Srdivacky * \brief Retrieve a NULL (invalid) source range. 390203955Srdivacky */ 391203955SrdivackyCINDEX_LINKAGE CXSourceRange clang_getNullRange(); 392205219Srdivacky 393202879Srdivacky/** 394202879Srdivacky * \brief Retrieve a source range given the beginning and ending source 395202879Srdivacky * locations. 396202879Srdivacky */ 397202879SrdivackyCINDEX_LINKAGE CXSourceRange clang_getRange(CXSourceLocation begin, 398202879Srdivacky CXSourceLocation end); 399203955Srdivacky 400202879Srdivacky/** 401226633Sdim * \brief Determine whether two ranges are equivalent. 402226633Sdim * 403226633Sdim * \returns non-zero if the ranges are the same, zero if they differ. 404226633Sdim */ 405226633SdimCINDEX_LINKAGE unsigned clang_equalRanges(CXSourceRange range1, 406226633Sdim CXSourceRange range2); 407226633Sdim 408226633Sdim/** 409226633Sdim * \brief Returns non-zero if \arg range is null. 410226633Sdim */ 411226633SdimCINDEX_LINKAGE int clang_Range_isNull(CXSourceRange range); 412226633Sdim 413226633Sdim/** 414203955Srdivacky * \brief Retrieve the file, line, column, and offset represented by 415203955Srdivacky * the given source location. 416202879Srdivacky * 417226633Sdim * If the location refers into a macro expansion, retrieves the 418226633Sdim * location of the macro expansion. 419218893Sdim * 420203955Srdivacky * \param location the location within a source file that will be decomposed 421203955Srdivacky * into its parts. 422202879Srdivacky * 423203955Srdivacky * \param file [out] if non-NULL, will be set to the file to which the given 424202879Srdivacky * source location points. 425202879Srdivacky * 426203955Srdivacky * \param line [out] if non-NULL, will be set to the line to which the given 427202879Srdivacky * source location points. 428202879Srdivacky * 429203955Srdivacky * \param column [out] if non-NULL, will be set to the column to which the given 430203955Srdivacky * source location points. 431203955Srdivacky * 432203955Srdivacky * \param offset [out] if non-NULL, will be set to the offset into the 433203955Srdivacky * buffer to which the given source location points. 434202879Srdivacky */ 435226633SdimCINDEX_LINKAGE void clang_getExpansionLocation(CXSourceLocation location, 436226633Sdim CXFile *file, 437226633Sdim unsigned *line, 438226633Sdim unsigned *column, 439226633Sdim unsigned *offset); 440226633Sdim 441226633Sdim/** 442226633Sdim * \brief Retrieve the file, line, column, and offset represented by 443226633Sdim * the given source location, as specified in a # line directive. 444226633Sdim * 445226633Sdim * Example: given the following source code in a file somefile.c 446226633Sdim * 447226633Sdim * #123 "dummy.c" 1 448226633Sdim * 449226633Sdim * static int func(void) 450226633Sdim * { 451226633Sdim * return 0; 452226633Sdim * } 453226633Sdim * 454226633Sdim * the location information returned by this function would be 455226633Sdim * 456226633Sdim * File: dummy.c Line: 124 Column: 12 457226633Sdim * 458226633Sdim * whereas clang_getExpansionLocation would have returned 459226633Sdim * 460226633Sdim * File: somefile.c Line: 3 Column: 12 461226633Sdim * 462226633Sdim * \param location the location within a source file that will be decomposed 463226633Sdim * into its parts. 464226633Sdim * 465226633Sdim * \param filename [out] if non-NULL, will be set to the filename of the 466226633Sdim * source location. Note that filenames returned will be for "virtual" files, 467226633Sdim * which don't necessarily exist on the machine running clang - e.g. when 468226633Sdim * parsing preprocessed output obtained from a different environment. If 469226633Sdim * a non-NULL value is passed in, remember to dispose of the returned value 470226633Sdim * using \c clang_disposeString() once you've finished with it. For an invalid 471226633Sdim * source location, an empty string is returned. 472226633Sdim * 473226633Sdim * \param line [out] if non-NULL, will be set to the line number of the 474226633Sdim * source location. For an invalid source location, zero is returned. 475226633Sdim * 476226633Sdim * \param column [out] if non-NULL, will be set to the column number of the 477226633Sdim * source location. For an invalid source location, zero is returned. 478226633Sdim */ 479226633SdimCINDEX_LINKAGE void clang_getPresumedLocation(CXSourceLocation location, 480226633Sdim CXString *filename, 481226633Sdim unsigned *line, 482226633Sdim unsigned *column); 483226633Sdim 484226633Sdim/** 485226633Sdim * \brief Legacy API to retrieve the file, line, column, and offset represented 486226633Sdim * by the given source location. 487226633Sdim * 488226633Sdim * This interface has been replaced by the newer interface 489226633Sdim * \see clang_getExpansionLocation(). See that interface's documentation for 490226633Sdim * details. 491226633Sdim */ 492202879SrdivackyCINDEX_LINKAGE void clang_getInstantiationLocation(CXSourceLocation location, 493202879Srdivacky CXFile *file, 494202879Srdivacky unsigned *line, 495203955Srdivacky unsigned *column, 496203955Srdivacky unsigned *offset); 497202379Srdivacky 498202879Srdivacky/** 499218893Sdim * \brief Retrieve the file, line, column, and offset represented by 500218893Sdim * the given source location. 501218893Sdim * 502218893Sdim * If the location refers into a macro instantiation, return where the 503218893Sdim * location was originally spelled in the source file. 504218893Sdim * 505218893Sdim * \param location the location within a source file that will be decomposed 506218893Sdim * into its parts. 507218893Sdim * 508218893Sdim * \param file [out] if non-NULL, will be set to the file to which the given 509218893Sdim * source location points. 510218893Sdim * 511218893Sdim * \param line [out] if non-NULL, will be set to the line to which the given 512218893Sdim * source location points. 513218893Sdim * 514218893Sdim * \param column [out] if non-NULL, will be set to the column to which the given 515218893Sdim * source location points. 516218893Sdim * 517218893Sdim * \param offset [out] if non-NULL, will be set to the offset into the 518218893Sdim * buffer to which the given source location points. 519218893Sdim */ 520218893SdimCINDEX_LINKAGE void clang_getSpellingLocation(CXSourceLocation location, 521218893Sdim CXFile *file, 522218893Sdim unsigned *line, 523218893Sdim unsigned *column, 524218893Sdim unsigned *offset); 525218893Sdim 526218893Sdim/** 527203955Srdivacky * \brief Retrieve a source location representing the first character within a 528203955Srdivacky * source range. 529198092Srdivacky */ 530202879SrdivackyCINDEX_LINKAGE CXSourceLocation clang_getRangeStart(CXSourceRange range); 531198092Srdivacky 532202879Srdivacky/** 533203955Srdivacky * \brief Retrieve a source location representing the last character within a 534203955Srdivacky * source range. 535202879Srdivacky */ 536202879SrdivackyCINDEX_LINKAGE CXSourceLocation clang_getRangeEnd(CXSourceRange range); 537202379Srdivacky 538202879Srdivacky/** 539202879Srdivacky * @} 540202879Srdivacky */ 541202379Srdivacky 542202879Srdivacky/** 543203955Srdivacky * \defgroup CINDEX_DIAG Diagnostic reporting 544203955Srdivacky * 545203955Srdivacky * @{ 546203955Srdivacky */ 547203955Srdivacky 548203955Srdivacky/** 549203955Srdivacky * \brief Describes the severity of a particular diagnostic. 550203955Srdivacky */ 551203955Srdivackyenum CXDiagnosticSeverity { 552203955Srdivacky /** 553205219Srdivacky * \brief A diagnostic that has been suppressed, e.g., by a command-line 554203955Srdivacky * option. 555203955Srdivacky */ 556203955Srdivacky CXDiagnostic_Ignored = 0, 557205219Srdivacky 558203955Srdivacky /** 559203955Srdivacky * \brief This diagnostic is a note that should be attached to the 560203955Srdivacky * previous (non-note) diagnostic. 561203955Srdivacky */ 562203955Srdivacky CXDiagnostic_Note = 1, 563203955Srdivacky 564203955Srdivacky /** 565203955Srdivacky * \brief This diagnostic indicates suspicious code that may not be 566203955Srdivacky * wrong. 567203955Srdivacky */ 568203955Srdivacky CXDiagnostic_Warning = 2, 569203955Srdivacky 570203955Srdivacky /** 571203955Srdivacky * \brief This diagnostic indicates that the code is ill-formed. 572203955Srdivacky */ 573203955Srdivacky CXDiagnostic_Error = 3, 574203955Srdivacky 575203955Srdivacky /** 576203955Srdivacky * \brief This diagnostic indicates that the code is ill-formed such 577203955Srdivacky * that future parser recovery is unlikely to produce useful 578203955Srdivacky * results. 579203955Srdivacky */ 580203955Srdivacky CXDiagnostic_Fatal = 4 581203955Srdivacky}; 582203955Srdivacky 583203955Srdivacky/** 584204643Srdivacky * \brief A single diagnostic, containing the diagnostic's severity, 585204643Srdivacky * location, text, source ranges, and fix-it hints. 586203955Srdivacky */ 587204643Srdivackytypedef void *CXDiagnostic; 588204643Srdivacky 589204643Srdivacky/** 590234353Sdim * \brief A group of CXDiagnostics. 591234353Sdim */ 592234353Sdimtypedef void *CXDiagnosticSet; 593234353Sdim 594234353Sdim/** 595234353Sdim * \brief Determine the number of diagnostics in a CXDiagnosticSet. 596234353Sdim */ 597234353SdimCINDEX_LINKAGE unsigned clang_getNumDiagnosticsInSet(CXDiagnosticSet Diags); 598234353Sdim 599234353Sdim/** 600234353Sdim * \brief Retrieve a diagnostic associated with the given CXDiagnosticSet. 601234353Sdim * 602234353Sdim * \param Unit the CXDiagnosticSet to query. 603234353Sdim * \param Index the zero-based diagnostic number to retrieve. 604234353Sdim * 605234353Sdim * \returns the requested diagnostic. This diagnostic must be freed 606234353Sdim * via a call to \c clang_disposeDiagnostic(). 607234353Sdim */ 608234353SdimCINDEX_LINKAGE CXDiagnostic clang_getDiagnosticInSet(CXDiagnosticSet Diags, 609234353Sdim unsigned Index); 610234353Sdim 611234353Sdim 612234353Sdim/** 613234353Sdim * \brief Describes the kind of error that occurred (if any) in a call to 614234353Sdim * \c clang_loadDiagnostics. 615234353Sdim */ 616234353Sdimenum CXLoadDiag_Error { 617234353Sdim /** 618234353Sdim * \brief Indicates that no error occurred. 619234353Sdim */ 620234353Sdim CXLoadDiag_None = 0, 621234353Sdim 622234353Sdim /** 623234353Sdim * \brief Indicates that an unknown error occurred while attempting to 624234353Sdim * deserialize diagnostics. 625234353Sdim */ 626234353Sdim CXLoadDiag_Unknown = 1, 627234353Sdim 628234353Sdim /** 629234353Sdim * \brief Indicates that the file containing the serialized diagnostics 630234353Sdim * could not be opened. 631234353Sdim */ 632234353Sdim CXLoadDiag_CannotLoad = 2, 633234353Sdim 634234353Sdim /** 635234353Sdim * \brief Indicates that the serialized diagnostics file is invalid or 636234353Sdim * corrupt. 637234353Sdim */ 638234353Sdim CXLoadDiag_InvalidFile = 3 639234353Sdim}; 640234353Sdim 641234353Sdim/** 642234353Sdim * \brief Deserialize a set of diagnostics from a Clang diagnostics bitcode 643234353Sdim * file. 644234353Sdim * 645234353Sdim * \param The name of the file to deserialize. 646234353Sdim * \param A pointer to a enum value recording if there was a problem 647234353Sdim * deserializing the diagnostics. 648234353Sdim * \param A pointer to a CXString for recording the error string 649234353Sdim * if the file was not successfully loaded. 650234353Sdim * 651234353Sdim * \returns A loaded CXDiagnosticSet if successful, and NULL otherwise. These 652234353Sdim * diagnostics should be released using clang_disposeDiagnosticSet(). 653234353Sdim */ 654234353SdimCINDEX_LINKAGE CXDiagnosticSet clang_loadDiagnostics(const char *file, 655234353Sdim enum CXLoadDiag_Error *error, 656234353Sdim CXString *errorString); 657234353Sdim 658234353Sdim/** 659234353Sdim * \brief Release a CXDiagnosticSet and all of its contained diagnostics. 660234353Sdim */ 661234353SdimCINDEX_LINKAGE void clang_disposeDiagnosticSet(CXDiagnosticSet Diags); 662234353Sdim 663234353Sdim/** 664234353Sdim * \brief Retrieve the child diagnostics of a CXDiagnostic. This 665234353Sdim * CXDiagnosticSet does not need to be released by clang_diposeDiagnosticSet. 666234353Sdim */ 667234353SdimCINDEX_LINKAGE CXDiagnosticSet clang_getChildDiagnostics(CXDiagnostic D); 668234353Sdim 669234353Sdim/** 670204643Srdivacky * \brief Determine the number of diagnostics produced for the given 671204643Srdivacky * translation unit. 672204643Srdivacky */ 673204643SrdivackyCINDEX_LINKAGE unsigned clang_getNumDiagnostics(CXTranslationUnit Unit); 674204643Srdivacky 675204643Srdivacky/** 676204643Srdivacky * \brief Retrieve a diagnostic associated with the given translation unit. 677204643Srdivacky * 678204643Srdivacky * \param Unit the translation unit to query. 679204643Srdivacky * \param Index the zero-based diagnostic number to retrieve. 680204643Srdivacky * 681204643Srdivacky * \returns the requested diagnostic. This diagnostic must be freed 682204643Srdivacky * via a call to \c clang_disposeDiagnostic(). 683204643Srdivacky */ 684204643SrdivackyCINDEX_LINKAGE CXDiagnostic clang_getDiagnostic(CXTranslationUnit Unit, 685204643Srdivacky unsigned Index); 686204643Srdivacky 687204643Srdivacky/** 688234353Sdim * \brief Retrieve the complete set of diagnostics associated with a 689234353Sdim * translation unit. 690234353Sdim * 691234353Sdim * \param Unit the translation unit to query. 692234353Sdim */ 693234353SdimCINDEX_LINKAGE CXDiagnosticSet 694234353Sdim clang_getDiagnosticSetFromTU(CXTranslationUnit Unit); 695234353Sdim 696234353Sdim/** 697204643Srdivacky * \brief Destroy a diagnostic. 698204643Srdivacky */ 699204643SrdivackyCINDEX_LINKAGE void clang_disposeDiagnostic(CXDiagnostic Diagnostic); 700204643Srdivacky 701204643Srdivacky/** 702204643Srdivacky * \brief Options to control the display of diagnostics. 703204643Srdivacky * 704204643Srdivacky * The values in this enum are meant to be combined to customize the 705204643Srdivacky * behavior of \c clang_displayDiagnostic(). 706204643Srdivacky */ 707204643Srdivackyenum CXDiagnosticDisplayOptions { 708203955Srdivacky /** 709204643Srdivacky * \brief Display the source-location information where the 710204643Srdivacky * diagnostic was located. 711204643Srdivacky * 712204643Srdivacky * When set, diagnostics will be prefixed by the file, line, and 713204643Srdivacky * (optionally) column to which the diagnostic refers. For example, 714204643Srdivacky * 715204643Srdivacky * \code 716204643Srdivacky * test.c:28: warning: extra tokens at end of #endif directive 717204643Srdivacky * \endcode 718204643Srdivacky * 719204643Srdivacky * This option corresponds to the clang flag \c -fshow-source-location. 720203955Srdivacky */ 721204643Srdivacky CXDiagnostic_DisplaySourceLocation = 0x01, 722203955Srdivacky 723203955Srdivacky /** 724204643Srdivacky * \brief If displaying the source-location information of the 725204643Srdivacky * diagnostic, also include the column number. 726204643Srdivacky * 727204643Srdivacky * This option corresponds to the clang flag \c -fshow-column. 728203955Srdivacky */ 729204643Srdivacky CXDiagnostic_DisplayColumn = 0x02, 730203955Srdivacky 731203955Srdivacky /** 732204643Srdivacky * \brief If displaying the source-location information of the 733204643Srdivacky * diagnostic, also include information about source ranges in a 734204643Srdivacky * machine-parsable format. 735204643Srdivacky * 736205219Srdivacky * This option corresponds to the clang flag 737204643Srdivacky * \c -fdiagnostics-print-source-range-info. 738203955Srdivacky */ 739218893Sdim CXDiagnostic_DisplaySourceRanges = 0x04, 740218893Sdim 741218893Sdim /** 742218893Sdim * \brief Display the option name associated with this diagnostic, if any. 743218893Sdim * 744218893Sdim * The option name displayed (e.g., -Wconversion) will be placed in brackets 745218893Sdim * after the diagnostic text. This option corresponds to the clang flag 746218893Sdim * \c -fdiagnostics-show-option. 747218893Sdim */ 748218893Sdim CXDiagnostic_DisplayOption = 0x08, 749218893Sdim 750218893Sdim /** 751218893Sdim * \brief Display the category number associated with this diagnostic, if any. 752218893Sdim * 753218893Sdim * The category number is displayed within brackets after the diagnostic text. 754218893Sdim * This option corresponds to the clang flag 755218893Sdim * \c -fdiagnostics-show-category=id. 756218893Sdim */ 757218893Sdim CXDiagnostic_DisplayCategoryId = 0x10, 758218893Sdim 759218893Sdim /** 760218893Sdim * \brief Display the category name associated with this diagnostic, if any. 761218893Sdim * 762218893Sdim * The category name is displayed within brackets after the diagnostic text. 763218893Sdim * This option corresponds to the clang flag 764218893Sdim * \c -fdiagnostics-show-category=name. 765218893Sdim */ 766218893Sdim CXDiagnostic_DisplayCategoryName = 0x20 767203955Srdivacky}; 768203955Srdivacky 769203955Srdivacky/** 770204643Srdivacky * \brief Format the given diagnostic in a manner that is suitable for display. 771204643Srdivacky * 772204643Srdivacky * This routine will format the given diagnostic to a string, rendering 773205219Srdivacky * the diagnostic according to the various options given. The 774205219Srdivacky * \c clang_defaultDiagnosticDisplayOptions() function returns the set of 775204643Srdivacky * options that most closely mimics the behavior of the clang compiler. 776204643Srdivacky * 777204643Srdivacky * \param Diagnostic The diagnostic to print. 778204643Srdivacky * 779205219Srdivacky * \param Options A set of options that control the diagnostic display, 780204643Srdivacky * created by combining \c CXDiagnosticDisplayOptions values. 781204643Srdivacky * 782204643Srdivacky * \returns A new string containing for formatted diagnostic. 783203955Srdivacky */ 784204643SrdivackyCINDEX_LINKAGE CXString clang_formatDiagnostic(CXDiagnostic Diagnostic, 785204643Srdivacky unsigned Options); 786203955Srdivacky 787203955Srdivacky/** 788204643Srdivacky * \brief Retrieve the set of display options most similar to the 789204643Srdivacky * default behavior of the clang compiler. 790203955Srdivacky * 791204643Srdivacky * \returns A set of display options suitable for use with \c 792204643Srdivacky * clang_displayDiagnostic(). 793203955Srdivacky */ 794204643SrdivackyCINDEX_LINKAGE unsigned clang_defaultDiagnosticDisplayOptions(void); 795203955Srdivacky 796203955Srdivacky/** 797203955Srdivacky * \brief Determine the severity of the given diagnostic. 798203955Srdivacky */ 799205219SrdivackyCINDEX_LINKAGE enum CXDiagnosticSeverity 800203955Srdivackyclang_getDiagnosticSeverity(CXDiagnostic); 801203955Srdivacky 802203955Srdivacky/** 803203955Srdivacky * \brief Retrieve the source location of the given diagnostic. 804203955Srdivacky * 805203955Srdivacky * This location is where Clang would print the caret ('^') when 806203955Srdivacky * displaying the diagnostic on the command line. 807203955Srdivacky */ 808203955SrdivackyCINDEX_LINKAGE CXSourceLocation clang_getDiagnosticLocation(CXDiagnostic); 809203955Srdivacky 810203955Srdivacky/** 811203955Srdivacky * \brief Retrieve the text of the given diagnostic. 812203955Srdivacky */ 813203955SrdivackyCINDEX_LINKAGE CXString clang_getDiagnosticSpelling(CXDiagnostic); 814203955Srdivacky 815203955Srdivacky/** 816218893Sdim * \brief Retrieve the name of the command-line option that enabled this 817218893Sdim * diagnostic. 818218893Sdim * 819218893Sdim * \param Diag The diagnostic to be queried. 820218893Sdim * 821218893Sdim * \param Disable If non-NULL, will be set to the option that disables this 822218893Sdim * diagnostic (if any). 823218893Sdim * 824218893Sdim * \returns A string that contains the command-line option used to enable this 825218893Sdim * warning, such as "-Wconversion" or "-pedantic". 826218893Sdim */ 827218893SdimCINDEX_LINKAGE CXString clang_getDiagnosticOption(CXDiagnostic Diag, 828218893Sdim CXString *Disable); 829218893Sdim 830218893Sdim/** 831218893Sdim * \brief Retrieve the category number for this diagnostic. 832218893Sdim * 833218893Sdim * Diagnostics can be categorized into groups along with other, related 834218893Sdim * diagnostics (e.g., diagnostics under the same warning flag). This routine 835218893Sdim * retrieves the category number for the given diagnostic. 836218893Sdim * 837218893Sdim * \returns The number of the category that contains this diagnostic, or zero 838218893Sdim * if this diagnostic is uncategorized. 839218893Sdim */ 840218893SdimCINDEX_LINKAGE unsigned clang_getDiagnosticCategory(CXDiagnostic); 841218893Sdim 842218893Sdim/** 843234353Sdim * \brief Retrieve the name of a particular diagnostic category. This 844234353Sdim * is now deprecated. Use clang_getDiagnosticCategoryText() 845234353Sdim * instead. 846218893Sdim * 847218893Sdim * \param Category A diagnostic category number, as returned by 848218893Sdim * \c clang_getDiagnosticCategory(). 849218893Sdim * 850218893Sdim * \returns The name of the given diagnostic category. 851218893Sdim */ 852234353SdimCINDEX_DEPRECATED CINDEX_LINKAGE 853234353SdimCXString clang_getDiagnosticCategoryName(unsigned Category); 854234353Sdim 855234353Sdim/** 856234353Sdim * \brief Retrieve the diagnostic category text for a given diagnostic. 857234353Sdim * 858234353Sdim * 859234353Sdim * \returns The text of the given diagnostic category. 860234353Sdim */ 861234353SdimCINDEX_LINKAGE CXString clang_getDiagnosticCategoryText(CXDiagnostic); 862218893Sdim 863218893Sdim/** 864203955Srdivacky * \brief Determine the number of source ranges associated with the given 865203955Srdivacky * diagnostic. 866203955Srdivacky */ 867203955SrdivackyCINDEX_LINKAGE unsigned clang_getDiagnosticNumRanges(CXDiagnostic); 868205219Srdivacky 869203955Srdivacky/** 870203955Srdivacky * \brief Retrieve a source range associated with the diagnostic. 871203955Srdivacky * 872203955Srdivacky * A diagnostic's source ranges highlight important elements in the source 873203955Srdivacky * code. On the command line, Clang displays source ranges by 874205219Srdivacky * underlining them with '~' characters. 875203955Srdivacky * 876203955Srdivacky * \param Diagnostic the diagnostic whose range is being extracted. 877203955Srdivacky * 878205219Srdivacky * \param Range the zero-based index specifying which range to 879203955Srdivacky * 880203955Srdivacky * \returns the requested source range. 881203955Srdivacky */ 882205219SrdivackyCINDEX_LINKAGE CXSourceRange clang_getDiagnosticRange(CXDiagnostic Diagnostic, 883203955Srdivacky unsigned Range); 884203955Srdivacky 885203955Srdivacky/** 886203955Srdivacky * \brief Determine the number of fix-it hints associated with the 887203955Srdivacky * given diagnostic. 888203955Srdivacky */ 889203955SrdivackyCINDEX_LINKAGE unsigned clang_getDiagnosticNumFixIts(CXDiagnostic Diagnostic); 890203955Srdivacky 891203955Srdivacky/** 892204643Srdivacky * \brief Retrieve the replacement information for a given fix-it. 893203955Srdivacky * 894204643Srdivacky * Fix-its are described in terms of a source range whose contents 895204643Srdivacky * should be replaced by a string. This approach generalizes over 896204643Srdivacky * three kinds of operations: removal of source code (the range covers 897204643Srdivacky * the code to be removed and the replacement string is empty), 898204643Srdivacky * replacement of source code (the range covers the code to be 899204643Srdivacky * replaced and the replacement string provides the new code), and 900204643Srdivacky * insertion (both the start and end of the range point at the 901204643Srdivacky * insertion location, and the replacement string provides the text to 902204643Srdivacky * insert). 903203955Srdivacky * 904204643Srdivacky * \param Diagnostic The diagnostic whose fix-its are being queried. 905203955Srdivacky * 906204643Srdivacky * \param FixIt The zero-based index of the fix-it. 907203955Srdivacky * 908204643Srdivacky * \param ReplacementRange The source range whose contents will be 909204643Srdivacky * replaced with the returned replacement string. Note that source 910204643Srdivacky * ranges are half-open ranges [a, b), so the source code should be 911204643Srdivacky * replaced from a and up to (but not including) b. 912203955Srdivacky * 913204643Srdivacky * \returns A string containing text that should be replace the source 914204643Srdivacky * code indicated by the \c ReplacementRange. 915203955Srdivacky */ 916205219SrdivackyCINDEX_LINKAGE CXString clang_getDiagnosticFixIt(CXDiagnostic Diagnostic, 917204643Srdivacky unsigned FixIt, 918204643Srdivacky CXSourceRange *ReplacementRange); 919203955Srdivacky 920203955Srdivacky/** 921203955Srdivacky * @} 922203955Srdivacky */ 923203955Srdivacky 924203955Srdivacky/** 925203955Srdivacky * \defgroup CINDEX_TRANSLATION_UNIT Translation unit manipulation 926203955Srdivacky * 927203955Srdivacky * The routines in this group provide the ability to create and destroy 928203955Srdivacky * translation units from files, either by parsing the contents of the files or 929203955Srdivacky * by reading in a serialized representation of a translation unit. 930203955Srdivacky * 931203955Srdivacky * @{ 932203955Srdivacky */ 933205219Srdivacky 934203955Srdivacky/** 935203955Srdivacky * \brief Get the original translation unit source file name. 936203955Srdivacky */ 937203955SrdivackyCINDEX_LINKAGE CXString 938203955Srdivackyclang_getTranslationUnitSpelling(CXTranslationUnit CTUnit); 939203955Srdivacky 940203955Srdivacky/** 941203955Srdivacky * \brief Return the CXTranslationUnit for a given source file and the provided 942203955Srdivacky * command line arguments one would pass to the compiler. 943203955Srdivacky * 944203955Srdivacky * Note: The 'source_filename' argument is optional. If the caller provides a 945203955Srdivacky * NULL pointer, the name of the source file is expected to reside in the 946203955Srdivacky * specified command line arguments. 947203955Srdivacky * 948203955Srdivacky * Note: When encountered in 'clang_command_line_args', the following options 949203955Srdivacky * are ignored: 950203955Srdivacky * 951203955Srdivacky * '-c' 952203955Srdivacky * '-emit-ast' 953203955Srdivacky * '-fsyntax-only' 954203955Srdivacky * '-o <output file>' (both '-o' and '<output file>' are ignored) 955203955Srdivacky * 956218893Sdim * \param CIdx The index object with which the translation unit will be 957218893Sdim * associated. 958203955Srdivacky * 959203955Srdivacky * \param source_filename - The name of the source file to load, or NULL if the 960218893Sdim * source file is included in \p clang_command_line_args. 961203955Srdivacky * 962218893Sdim * \param num_clang_command_line_args The number of command-line arguments in 963218893Sdim * \p clang_command_line_args. 964218893Sdim * 965218893Sdim * \param clang_command_line_args The command-line arguments that would be 966218893Sdim * passed to the \c clang executable if it were being invoked out-of-process. 967218893Sdim * These command-line options will be parsed and will affect how the translation 968218893Sdim * unit is parsed. Note that the following options are ignored: '-c', 969218893Sdim * '-emit-ast', '-fsyntex-only' (which is the default), and '-o <output file>'. 970218893Sdim * 971203955Srdivacky * \param num_unsaved_files the number of unsaved file entries in \p 972203955Srdivacky * unsaved_files. 973203955Srdivacky * 974203955Srdivacky * \param unsaved_files the files that have not yet been saved to disk 975203955Srdivacky * but may be required for code completion, including the contents of 976207619Srdivacky * those files. The contents and name of these files (as specified by 977207619Srdivacky * CXUnsavedFile) are copied when necessary, so the client only needs to 978207619Srdivacky * guarantee their validity until the call to this function returns. 979203955Srdivacky */ 980203955SrdivackyCINDEX_LINKAGE CXTranslationUnit clang_createTranslationUnitFromSourceFile( 981203955Srdivacky CXIndex CIdx, 982203955Srdivacky const char *source_filename, 983203955Srdivacky int num_clang_command_line_args, 984212904Sdim const char * const *clang_command_line_args, 985203955Srdivacky unsigned num_unsaved_files, 986204643Srdivacky struct CXUnsavedFile *unsaved_files); 987205219Srdivacky 988203955Srdivacky/** 989203955Srdivacky * \brief Create a translation unit from an AST file (-emit-ast). 990203955Srdivacky */ 991205219SrdivackyCINDEX_LINKAGE CXTranslationUnit clang_createTranslationUnit(CXIndex, 992204643Srdivacky const char *ast_filename); 993203955Srdivacky 994203955Srdivacky/** 995212904Sdim * \brief Flags that control the creation of translation units. 996212904Sdim * 997212904Sdim * The enumerators in this enumeration type are meant to be bitwise 998212904Sdim * ORed together to specify which options should be used when 999212904Sdim * constructing the translation unit. 1000212904Sdim */ 1001212904Sdimenum CXTranslationUnit_Flags { 1002212904Sdim /** 1003212904Sdim * \brief Used to indicate that no special translation-unit options are 1004212904Sdim * needed. 1005212904Sdim */ 1006212904Sdim CXTranslationUnit_None = 0x0, 1007212904Sdim 1008212904Sdim /** 1009212904Sdim * \brief Used to indicate that the parser should construct a "detailed" 1010212904Sdim * preprocessing record, including all macro definitions and instantiations. 1011212904Sdim * 1012212904Sdim * Constructing a detailed preprocessing record requires more memory 1013212904Sdim * and time to parse, since the information contained in the record 1014212904Sdim * is usually not retained. However, it can be useful for 1015212904Sdim * applications that require more detailed information about the 1016212904Sdim * behavior of the preprocessor. 1017212904Sdim */ 1018212904Sdim CXTranslationUnit_DetailedPreprocessingRecord = 0x01, 1019212904Sdim 1020212904Sdim /** 1021212904Sdim * \brief Used to indicate that the translation unit is incomplete. 1022212904Sdim * 1023212904Sdim * When a translation unit is considered "incomplete", semantic 1024212904Sdim * analysis that is typically performed at the end of the 1025212904Sdim * translation unit will be suppressed. For example, this suppresses 1026212904Sdim * the completion of tentative declarations in C and of 1027212904Sdim * instantiation of implicitly-instantiation function templates in 1028212904Sdim * C++. This option is typically used when parsing a header with the 1029212904Sdim * intent of producing a precompiled header. 1030212904Sdim */ 1031212904Sdim CXTranslationUnit_Incomplete = 0x02, 1032212904Sdim 1033212904Sdim /** 1034212904Sdim * \brief Used to indicate that the translation unit should be built with an 1035212904Sdim * implicit precompiled header for the preamble. 1036212904Sdim * 1037212904Sdim * An implicit precompiled header is used as an optimization when a 1038212904Sdim * particular translation unit is likely to be reparsed many times 1039212904Sdim * when the sources aren't changing that often. In this case, an 1040212904Sdim * implicit precompiled header will be built containing all of the 1041212904Sdim * initial includes at the top of the main file (what we refer to as 1042212904Sdim * the "preamble" of the file). In subsequent parses, if the 1043212904Sdim * preamble or the files in it have not changed, \c 1044212904Sdim * clang_reparseTranslationUnit() will re-use the implicit 1045212904Sdim * precompiled header to improve parsing performance. 1046212904Sdim */ 1047212904Sdim CXTranslationUnit_PrecompiledPreamble = 0x04, 1048212904Sdim 1049212904Sdim /** 1050212904Sdim * \brief Used to indicate that the translation unit should cache some 1051212904Sdim * code-completion results with each reparse of the source file. 1052212904Sdim * 1053212904Sdim * Caching of code-completion results is a performance optimization that 1054212904Sdim * introduces some overhead to reparsing but improves the performance of 1055212904Sdim * code-completion operations. 1056212904Sdim */ 1057218893Sdim CXTranslationUnit_CacheCompletionResults = 0x08, 1058218893Sdim /** 1059226633Sdim * \brief DEPRECATED: Enable precompiled preambles in C++. 1060218893Sdim * 1061218893Sdim * Note: this is a *temporary* option that is available only while 1062226633Sdim * we are testing C++ precompiled preamble support. It is deprecated. 1063218893Sdim */ 1064218893Sdim CXTranslationUnit_CXXPrecompiledPreamble = 0x10, 1065218893Sdim 1066218893Sdim /** 1067226633Sdim * \brief DEPRECATED: Enabled chained precompiled preambles in C++. 1068218893Sdim * 1069218893Sdim * Note: this is a *temporary* option that is available only while 1070226633Sdim * we are testing C++ precompiled preamble support. It is deprecated. 1071218893Sdim */ 1072223017Sdim CXTranslationUnit_CXXChainedPCH = 0x20, 1073224145Sdim 1074224145Sdim /** 1075234353Sdim * \brief Used to indicate that function/method bodies should be skipped while 1076234353Sdim * parsing. 1077224145Sdim * 1078234353Sdim * This option can be used to search for declarations/definitions while 1079234353Sdim * ignoring the usages. 1080224145Sdim */ 1081234353Sdim CXTranslationUnit_SkipFunctionBodies = 0x40 1082212904Sdim}; 1083212904Sdim 1084212904Sdim/** 1085212904Sdim * \brief Returns the set of flags that is suitable for parsing a translation 1086212904Sdim * unit that is being edited. 1087212904Sdim * 1088212904Sdim * The set of flags returned provide options for \c clang_parseTranslationUnit() 1089212904Sdim * to indicate that the translation unit is likely to be reparsed many times, 1090212904Sdim * either explicitly (via \c clang_reparseTranslationUnit()) or implicitly 1091212904Sdim * (e.g., by code completion (\c clang_codeCompletionAt())). The returned flag 1092212904Sdim * set contains an unspecified set of optimizations (e.g., the precompiled 1093212904Sdim * preamble) geared toward improving the performance of these routines. The 1094212904Sdim * set of optimizations enabled may change from one version to the next. 1095212904Sdim */ 1096212904SdimCINDEX_LINKAGE unsigned clang_defaultEditingTranslationUnitOptions(void); 1097212904Sdim 1098212904Sdim/** 1099212904Sdim * \brief Parse the given source file and the translation unit corresponding 1100212904Sdim * to that file. 1101212904Sdim * 1102212904Sdim * This routine is the main entry point for the Clang C API, providing the 1103212904Sdim * ability to parse a source file into a translation unit that can then be 1104212904Sdim * queried by other functions in the API. This routine accepts a set of 1105212904Sdim * command-line arguments so that the compilation can be configured in the same 1106212904Sdim * way that the compiler is configured on the command line. 1107212904Sdim * 1108212904Sdim * \param CIdx The index object with which the translation unit will be 1109212904Sdim * associated. 1110212904Sdim * 1111212904Sdim * \param source_filename The name of the source file to load, or NULL if the 1112218893Sdim * source file is included in \p command_line_args. 1113212904Sdim * 1114212904Sdim * \param command_line_args The command-line arguments that would be 1115212904Sdim * passed to the \c clang executable if it were being invoked out-of-process. 1116212904Sdim * These command-line options will be parsed and will affect how the translation 1117212904Sdim * unit is parsed. Note that the following options are ignored: '-c', 1118212904Sdim * '-emit-ast', '-fsyntex-only' (which is the default), and '-o <output file>'. 1119212904Sdim * 1120212904Sdim * \param num_command_line_args The number of command-line arguments in 1121212904Sdim * \p command_line_args. 1122212904Sdim * 1123212904Sdim * \param unsaved_files the files that have not yet been saved to disk 1124212904Sdim * but may be required for parsing, including the contents of 1125212904Sdim * those files. The contents and name of these files (as specified by 1126212904Sdim * CXUnsavedFile) are copied when necessary, so the client only needs to 1127212904Sdim * guarantee their validity until the call to this function returns. 1128212904Sdim * 1129212904Sdim * \param num_unsaved_files the number of unsaved file entries in \p 1130212904Sdim * unsaved_files. 1131212904Sdim * 1132212904Sdim * \param options A bitmask of options that affects how the translation unit 1133212904Sdim * is managed but not its compilation. This should be a bitwise OR of the 1134212904Sdim * CXTranslationUnit_XXX flags. 1135212904Sdim * 1136212904Sdim * \returns A new translation unit describing the parsed code and containing 1137212904Sdim * any diagnostics produced by the compiler. If there is a failure from which 1138212904Sdim * the compiler cannot recover, returns NULL. 1139212904Sdim */ 1140212904SdimCINDEX_LINKAGE CXTranslationUnit clang_parseTranslationUnit(CXIndex CIdx, 1141212904Sdim const char *source_filename, 1142212904Sdim const char * const *command_line_args, 1143212904Sdim int num_command_line_args, 1144212904Sdim struct CXUnsavedFile *unsaved_files, 1145212904Sdim unsigned num_unsaved_files, 1146212904Sdim unsigned options); 1147212904Sdim 1148212904Sdim/** 1149212904Sdim * \brief Flags that control how translation units are saved. 1150212904Sdim * 1151212904Sdim * The enumerators in this enumeration type are meant to be bitwise 1152212904Sdim * ORed together to specify which options should be used when 1153212904Sdim * saving the translation unit. 1154212904Sdim */ 1155212904Sdimenum CXSaveTranslationUnit_Flags { 1156212904Sdim /** 1157212904Sdim * \brief Used to indicate that no special saving options are needed. 1158212904Sdim */ 1159212904Sdim CXSaveTranslationUnit_None = 0x0 1160212904Sdim}; 1161212904Sdim 1162212904Sdim/** 1163212904Sdim * \brief Returns the set of flags that is suitable for saving a translation 1164212904Sdim * unit. 1165212904Sdim * 1166212904Sdim * The set of flags returned provide options for 1167212904Sdim * \c clang_saveTranslationUnit() by default. The returned flag 1168212904Sdim * set contains an unspecified set of options that save translation units with 1169212904Sdim * the most commonly-requested data. 1170212904Sdim */ 1171212904SdimCINDEX_LINKAGE unsigned clang_defaultSaveOptions(CXTranslationUnit TU); 1172212904Sdim 1173212904Sdim/** 1174224145Sdim * \brief Describes the kind of error that occurred (if any) in a call to 1175224145Sdim * \c clang_saveTranslationUnit(). 1176224145Sdim */ 1177224145Sdimenum CXSaveError { 1178224145Sdim /** 1179224145Sdim * \brief Indicates that no error occurred while saving a translation unit. 1180224145Sdim */ 1181224145Sdim CXSaveError_None = 0, 1182224145Sdim 1183224145Sdim /** 1184224145Sdim * \brief Indicates that an unknown error occurred while attempting to save 1185224145Sdim * the file. 1186224145Sdim * 1187224145Sdim * This error typically indicates that file I/O failed when attempting to 1188224145Sdim * write the file. 1189224145Sdim */ 1190224145Sdim CXSaveError_Unknown = 1, 1191224145Sdim 1192224145Sdim /** 1193224145Sdim * \brief Indicates that errors during translation prevented this attempt 1194224145Sdim * to save the translation unit. 1195224145Sdim * 1196224145Sdim * Errors that prevent the translation unit from being saved can be 1197224145Sdim * extracted using \c clang_getNumDiagnostics() and \c clang_getDiagnostic(). 1198224145Sdim */ 1199224145Sdim CXSaveError_TranslationErrors = 2, 1200224145Sdim 1201224145Sdim /** 1202224145Sdim * \brief Indicates that the translation unit to be saved was somehow 1203224145Sdim * invalid (e.g., NULL). 1204224145Sdim */ 1205224145Sdim CXSaveError_InvalidTU = 3 1206224145Sdim}; 1207224145Sdim 1208224145Sdim/** 1209212904Sdim * \brief Saves a translation unit into a serialized representation of 1210212904Sdim * that translation unit on disk. 1211212904Sdim * 1212212904Sdim * Any translation unit that was parsed without error can be saved 1213212904Sdim * into a file. The translation unit can then be deserialized into a 1214212904Sdim * new \c CXTranslationUnit with \c clang_createTranslationUnit() or, 1215212904Sdim * if it is an incomplete translation unit that corresponds to a 1216212904Sdim * header, used as a precompiled header when parsing other translation 1217212904Sdim * units. 1218212904Sdim * 1219212904Sdim * \param TU The translation unit to save. 1220212904Sdim * 1221212904Sdim * \param FileName The file to which the translation unit will be saved. 1222212904Sdim * 1223212904Sdim * \param options A bitmask of options that affects how the translation unit 1224212904Sdim * is saved. This should be a bitwise OR of the 1225212904Sdim * CXSaveTranslationUnit_XXX flags. 1226212904Sdim * 1227224145Sdim * \returns A value that will match one of the enumerators of the CXSaveError 1228224145Sdim * enumeration. Zero (CXSaveError_None) indicates that the translation unit was 1229224145Sdim * saved successfully, while a non-zero value indicates that a problem occurred. 1230212904Sdim */ 1231212904SdimCINDEX_LINKAGE int clang_saveTranslationUnit(CXTranslationUnit TU, 1232212904Sdim const char *FileName, 1233212904Sdim unsigned options); 1234212904Sdim 1235212904Sdim/** 1236203955Srdivacky * \brief Destroy the specified CXTranslationUnit object. 1237203955Srdivacky */ 1238203955SrdivackyCINDEX_LINKAGE void clang_disposeTranslationUnit(CXTranslationUnit); 1239205219Srdivacky 1240203955Srdivacky/** 1241212904Sdim * \brief Flags that control the reparsing of translation units. 1242212904Sdim * 1243212904Sdim * The enumerators in this enumeration type are meant to be bitwise 1244212904Sdim * ORed together to specify which options should be used when 1245212904Sdim * reparsing the translation unit. 1246212904Sdim */ 1247212904Sdimenum CXReparse_Flags { 1248212904Sdim /** 1249212904Sdim * \brief Used to indicate that no special reparsing options are needed. 1250212904Sdim */ 1251212904Sdim CXReparse_None = 0x0 1252212904Sdim}; 1253212904Sdim 1254212904Sdim/** 1255212904Sdim * \brief Returns the set of flags that is suitable for reparsing a translation 1256212904Sdim * unit. 1257212904Sdim * 1258212904Sdim * The set of flags returned provide options for 1259212904Sdim * \c clang_reparseTranslationUnit() by default. The returned flag 1260212904Sdim * set contains an unspecified set of optimizations geared toward common uses 1261212904Sdim * of reparsing. The set of optimizations enabled may change from one version 1262212904Sdim * to the next. 1263212904Sdim */ 1264212904SdimCINDEX_LINKAGE unsigned clang_defaultReparseOptions(CXTranslationUnit TU); 1265212904Sdim 1266212904Sdim/** 1267212904Sdim * \brief Reparse the source files that produced this translation unit. 1268212904Sdim * 1269212904Sdim * This routine can be used to re-parse the source files that originally 1270212904Sdim * created the given translation unit, for example because those source files 1271212904Sdim * have changed (either on disk or as passed via \p unsaved_files). The 1272212904Sdim * source code will be reparsed with the same command-line options as it 1273212904Sdim * was originally parsed. 1274212904Sdim * 1275212904Sdim * Reparsing a translation unit invalidates all cursors and source locations 1276212904Sdim * that refer into that translation unit. This makes reparsing a translation 1277212904Sdim * unit semantically equivalent to destroying the translation unit and then 1278212904Sdim * creating a new translation unit with the same command-line arguments. 1279212904Sdim * However, it may be more efficient to reparse a translation 1280212904Sdim * unit using this routine. 1281212904Sdim * 1282212904Sdim * \param TU The translation unit whose contents will be re-parsed. The 1283212904Sdim * translation unit must originally have been built with 1284212904Sdim * \c clang_createTranslationUnitFromSourceFile(). 1285212904Sdim * 1286212904Sdim * \param num_unsaved_files The number of unsaved file entries in \p 1287212904Sdim * unsaved_files. 1288212904Sdim * 1289212904Sdim * \param unsaved_files The files that have not yet been saved to disk 1290212904Sdim * but may be required for parsing, including the contents of 1291212904Sdim * those files. The contents and name of these files (as specified by 1292212904Sdim * CXUnsavedFile) are copied when necessary, so the client only needs to 1293212904Sdim * guarantee their validity until the call to this function returns. 1294212904Sdim * 1295212904Sdim * \param options A bitset of options composed of the flags in CXReparse_Flags. 1296212904Sdim * The function \c clang_defaultReparseOptions() produces a default set of 1297212904Sdim * options recommended for most uses, based on the translation unit. 1298212904Sdim * 1299212904Sdim * \returns 0 if the sources could be reparsed. A non-zero value will be 1300212904Sdim * returned if reparsing was impossible, such that the translation unit is 1301212904Sdim * invalid. In such cases, the only valid call for \p TU is 1302212904Sdim * \c clang_disposeTranslationUnit(TU). 1303212904Sdim */ 1304212904SdimCINDEX_LINKAGE int clang_reparseTranslationUnit(CXTranslationUnit TU, 1305212904Sdim unsigned num_unsaved_files, 1306212904Sdim struct CXUnsavedFile *unsaved_files, 1307212904Sdim unsigned options); 1308221345Sdim 1309212904Sdim/** 1310221345Sdim * \brief Categorizes how memory is being used by a translation unit. 1311221345Sdim */ 1312221345Sdimenum CXTUResourceUsageKind { 1313221345Sdim CXTUResourceUsage_AST = 1, 1314221345Sdim CXTUResourceUsage_Identifiers = 2, 1315221345Sdim CXTUResourceUsage_Selectors = 3, 1316221345Sdim CXTUResourceUsage_GlobalCompletionResults = 4, 1317221345Sdim CXTUResourceUsage_SourceManagerContentCache = 5, 1318221345Sdim CXTUResourceUsage_AST_SideTables = 6, 1319221345Sdim CXTUResourceUsage_SourceManager_Membuffer_Malloc = 7, 1320221345Sdim CXTUResourceUsage_SourceManager_Membuffer_MMap = 8, 1321221345Sdim CXTUResourceUsage_ExternalASTSource_Membuffer_Malloc = 9, 1322221345Sdim CXTUResourceUsage_ExternalASTSource_Membuffer_MMap = 10, 1323223017Sdim CXTUResourceUsage_Preprocessor = 11, 1324223017Sdim CXTUResourceUsage_PreprocessingRecord = 12, 1325226633Sdim CXTUResourceUsage_SourceManager_DataStructures = 13, 1326226633Sdim CXTUResourceUsage_Preprocessor_HeaderSearch = 14, 1327221345Sdim CXTUResourceUsage_MEMORY_IN_BYTES_BEGIN = CXTUResourceUsage_AST, 1328221345Sdim CXTUResourceUsage_MEMORY_IN_BYTES_END = 1329226633Sdim CXTUResourceUsage_Preprocessor_HeaderSearch, 1330221345Sdim 1331221345Sdim CXTUResourceUsage_First = CXTUResourceUsage_AST, 1332226633Sdim CXTUResourceUsage_Last = CXTUResourceUsage_Preprocessor_HeaderSearch 1333221345Sdim}; 1334221345Sdim 1335221345Sdim/** 1336221345Sdim * \brief Returns the human-readable null-terminated C string that represents 1337221345Sdim * the name of the memory category. This string should never be freed. 1338221345Sdim */ 1339221345SdimCINDEX_LINKAGE 1340221345Sdimconst char *clang_getTUResourceUsageName(enum CXTUResourceUsageKind kind); 1341221345Sdim 1342221345Sdimtypedef struct CXTUResourceUsageEntry { 1343221345Sdim /* \brief The memory usage category. */ 1344221345Sdim enum CXTUResourceUsageKind kind; 1345221345Sdim /* \brief Amount of resources used. 1346221345Sdim The units will depend on the resource kind. */ 1347221345Sdim unsigned long amount; 1348221345Sdim} CXTUResourceUsageEntry; 1349221345Sdim 1350221345Sdim/** 1351221345Sdim * \brief The memory usage of a CXTranslationUnit, broken into categories. 1352221345Sdim */ 1353221345Sdimtypedef struct CXTUResourceUsage { 1354221345Sdim /* \brief Private data member, used for queries. */ 1355221345Sdim void *data; 1356221345Sdim 1357221345Sdim /* \brief The number of entries in the 'entries' array. */ 1358221345Sdim unsigned numEntries; 1359221345Sdim 1360221345Sdim /* \brief An array of key-value pairs, representing the breakdown of memory 1361221345Sdim usage. */ 1362221345Sdim CXTUResourceUsageEntry *entries; 1363221345Sdim 1364221345Sdim} CXTUResourceUsage; 1365221345Sdim 1366221345Sdim/** 1367221345Sdim * \brief Return the memory usage of a translation unit. This object 1368221345Sdim * should be released with clang_disposeCXTUResourceUsage(). 1369221345Sdim */ 1370221345SdimCINDEX_LINKAGE CXTUResourceUsage clang_getCXTUResourceUsage(CXTranslationUnit TU); 1371221345Sdim 1372221345SdimCINDEX_LINKAGE void clang_disposeCXTUResourceUsage(CXTUResourceUsage usage); 1373221345Sdim 1374221345Sdim/** 1375203955Srdivacky * @} 1376203955Srdivacky */ 1377205219Srdivacky 1378203955Srdivacky/** 1379202879Srdivacky * \brief Describes the kind of entity that a cursor refers to. 1380202379Srdivacky */ 1381202879Srdivackyenum CXCursorKind { 1382202879Srdivacky /* Declarations */ 1383203955Srdivacky /** 1384202879Srdivacky * \brief A declaration whose specific kind is not exposed via this 1385203955Srdivacky * interface. 1386202879Srdivacky * 1387202879Srdivacky * Unexposed declarations have the same operations as any other kind 1388202879Srdivacky * of declaration; one can extract their location information, 1389202879Srdivacky * spelling, find their definitions, etc. However, the specific kind 1390202879Srdivacky * of the declaration is not reported. 1391202879Srdivacky */ 1392202879Srdivacky CXCursor_UnexposedDecl = 1, 1393202879Srdivacky /** \brief A C or C++ struct. */ 1394203955Srdivacky CXCursor_StructDecl = 2, 1395202879Srdivacky /** \brief A C or C++ union. */ 1396202879Srdivacky CXCursor_UnionDecl = 3, 1397202879Srdivacky /** \brief A C++ class. */ 1398202879Srdivacky CXCursor_ClassDecl = 4, 1399202879Srdivacky /** \brief An enumeration. */ 1400202879Srdivacky CXCursor_EnumDecl = 5, 1401203955Srdivacky /** 1402202879Srdivacky * \brief A field (in C) or non-static data member (in C++) in a 1403202879Srdivacky * struct, union, or C++ class. 1404202879Srdivacky */ 1405202879Srdivacky CXCursor_FieldDecl = 6, 1406202879Srdivacky /** \brief An enumerator constant. */ 1407202879Srdivacky CXCursor_EnumConstantDecl = 7, 1408202879Srdivacky /** \brief A function. */ 1409202879Srdivacky CXCursor_FunctionDecl = 8, 1410202879Srdivacky /** \brief A variable. */ 1411202879Srdivacky CXCursor_VarDecl = 9, 1412202879Srdivacky /** \brief A function or method parameter. */ 1413202879Srdivacky CXCursor_ParmDecl = 10, 1414202879Srdivacky /** \brief An Objective-C @interface. */ 1415202879Srdivacky CXCursor_ObjCInterfaceDecl = 11, 1416202879Srdivacky /** \brief An Objective-C @interface for a category. */ 1417202879Srdivacky CXCursor_ObjCCategoryDecl = 12, 1418202879Srdivacky /** \brief An Objective-C @protocol declaration. */ 1419202879Srdivacky CXCursor_ObjCProtocolDecl = 13, 1420202879Srdivacky /** \brief An Objective-C @property declaration. */ 1421202879Srdivacky CXCursor_ObjCPropertyDecl = 14, 1422202879Srdivacky /** \brief An Objective-C instance variable. */ 1423202879Srdivacky CXCursor_ObjCIvarDecl = 15, 1424202879Srdivacky /** \brief An Objective-C instance method. */ 1425202879Srdivacky CXCursor_ObjCInstanceMethodDecl = 16, 1426202879Srdivacky /** \brief An Objective-C class method. */ 1427202879Srdivacky CXCursor_ObjCClassMethodDecl = 17, 1428202879Srdivacky /** \brief An Objective-C @implementation. */ 1429202879Srdivacky CXCursor_ObjCImplementationDecl = 18, 1430202879Srdivacky /** \brief An Objective-C @implementation for a category. */ 1431202879Srdivacky CXCursor_ObjCCategoryImplDecl = 19, 1432202879Srdivacky /** \brief A typedef */ 1433202879Srdivacky CXCursor_TypedefDecl = 20, 1434207619Srdivacky /** \brief A C++ class method. */ 1435207619Srdivacky CXCursor_CXXMethod = 21, 1436208600Srdivacky /** \brief A C++ namespace. */ 1437208600Srdivacky CXCursor_Namespace = 22, 1438208600Srdivacky /** \brief A linkage specification, e.g. 'extern "C"'. */ 1439208600Srdivacky CXCursor_LinkageSpec = 23, 1440212904Sdim /** \brief A C++ constructor. */ 1441212904Sdim CXCursor_Constructor = 24, 1442212904Sdim /** \brief A C++ destructor. */ 1443212904Sdim CXCursor_Destructor = 25, 1444212904Sdim /** \brief A C++ conversion function. */ 1445212904Sdim CXCursor_ConversionFunction = 26, 1446212904Sdim /** \brief A C++ template type parameter. */ 1447212904Sdim CXCursor_TemplateTypeParameter = 27, 1448212904Sdim /** \brief A C++ non-type template parameter. */ 1449212904Sdim CXCursor_NonTypeTemplateParameter = 28, 1450212904Sdim /** \brief A C++ template template parameter. */ 1451212904Sdim CXCursor_TemplateTemplateParameter = 29, 1452212904Sdim /** \brief A C++ function template. */ 1453212904Sdim CXCursor_FunctionTemplate = 30, 1454212904Sdim /** \brief A C++ class template. */ 1455212904Sdim CXCursor_ClassTemplate = 31, 1456212904Sdim /** \brief A C++ class template partial specialization. */ 1457212904Sdim CXCursor_ClassTemplatePartialSpecialization = 32, 1458212904Sdim /** \brief A C++ namespace alias declaration. */ 1459212904Sdim CXCursor_NamespaceAlias = 33, 1460212904Sdim /** \brief A C++ using directive. */ 1461212904Sdim CXCursor_UsingDirective = 34, 1462221345Sdim /** \brief A C++ using declaration. */ 1463212904Sdim CXCursor_UsingDeclaration = 35, 1464221345Sdim /** \brief A C++ alias declaration */ 1465221345Sdim CXCursor_TypeAliasDecl = 36, 1466223017Sdim /** \brief An Objective-C @synthesize definition. */ 1467223017Sdim CXCursor_ObjCSynthesizeDecl = 37, 1468223017Sdim /** \brief An Objective-C @dynamic definition. */ 1469223017Sdim CXCursor_ObjCDynamicDecl = 38, 1470226633Sdim /** \brief An access specifier. */ 1471226633Sdim CXCursor_CXXAccessSpecifier = 39, 1472226633Sdim 1473208600Srdivacky CXCursor_FirstDecl = CXCursor_UnexposedDecl, 1474226633Sdim CXCursor_LastDecl = CXCursor_CXXAccessSpecifier, 1475207619Srdivacky 1476202879Srdivacky /* References */ 1477202879Srdivacky CXCursor_FirstRef = 40, /* Decl references */ 1478203955Srdivacky CXCursor_ObjCSuperClassRef = 40, 1479202879Srdivacky CXCursor_ObjCProtocolRef = 41, 1480202879Srdivacky CXCursor_ObjCClassRef = 42, 1481202879Srdivacky /** 1482202879Srdivacky * \brief A reference to a type declaration. 1483202879Srdivacky * 1484202879Srdivacky * A type reference occurs anywhere where a type is named but not 1485202879Srdivacky * declared. For example, given: 1486202879Srdivacky * 1487202879Srdivacky * \code 1488202879Srdivacky * typedef unsigned size_type; 1489202879Srdivacky * size_type size; 1490202879Srdivacky * \endcode 1491202879Srdivacky * 1492202879Srdivacky * The typedef is a declaration of size_type (CXCursor_TypedefDecl), 1493202879Srdivacky * while the type of the variable "size" is referenced. The cursor 1494202879Srdivacky * referenced by the type of size is the typedef for size_type. 1495202879Srdivacky */ 1496202879Srdivacky CXCursor_TypeRef = 43, 1497212904Sdim CXCursor_CXXBaseSpecifier = 44, 1498212904Sdim /** 1499218893Sdim * \brief A reference to a class template, function template, template 1500218893Sdim * template parameter, or class template partial specialization. 1501212904Sdim */ 1502212904Sdim CXCursor_TemplateRef = 45, 1503212904Sdim /** 1504212904Sdim * \brief A reference to a namespace or namespace alias. 1505212904Sdim */ 1506212904Sdim CXCursor_NamespaceRef = 46, 1507218893Sdim /** 1508218893Sdim * \brief A reference to a member of a struct, union, or class that occurs in 1509218893Sdim * some non-expression context, e.g., a designated initializer. 1510218893Sdim */ 1511218893Sdim CXCursor_MemberRef = 47, 1512218893Sdim /** 1513218893Sdim * \brief A reference to a labeled statement. 1514218893Sdim * 1515218893Sdim * This cursor kind is used to describe the jump to "start_over" in the 1516218893Sdim * goto statement in the following example: 1517218893Sdim * 1518218893Sdim * \code 1519218893Sdim * start_over: 1520218893Sdim * ++counter; 1521218893Sdim * 1522218893Sdim * goto start_over; 1523218893Sdim * \endcode 1524218893Sdim * 1525218893Sdim * A label reference cursor refers to a label statement. 1526218893Sdim */ 1527218893Sdim CXCursor_LabelRef = 48, 1528218893Sdim 1529218893Sdim /** 1530218893Sdim * \brief A reference to a set of overloaded functions or function templates 1531218893Sdim * that has not yet been resolved to a specific function or function template. 1532218893Sdim * 1533218893Sdim * An overloaded declaration reference cursor occurs in C++ templates where 1534218893Sdim * a dependent name refers to a function. For example: 1535218893Sdim * 1536218893Sdim * \code 1537218893Sdim * template<typename T> void swap(T&, T&); 1538218893Sdim * 1539218893Sdim * struct X { ... }; 1540218893Sdim * void swap(X&, X&); 1541218893Sdim * 1542218893Sdim * template<typename T> 1543218893Sdim * void reverse(T* first, T* last) { 1544218893Sdim * while (first < last - 1) { 1545218893Sdim * swap(*first, *--last); 1546218893Sdim * ++first; 1547218893Sdim * } 1548218893Sdim * } 1549218893Sdim * 1550218893Sdim * struct Y { }; 1551218893Sdim * void swap(Y&, Y&); 1552218893Sdim * \endcode 1553218893Sdim * 1554218893Sdim * Here, the identifier "swap" is associated with an overloaded declaration 1555218893Sdim * reference. In the template definition, "swap" refers to either of the two 1556218893Sdim * "swap" functions declared above, so both results will be available. At 1557218893Sdim * instantiation time, "swap" may also refer to other functions found via 1558218893Sdim * argument-dependent lookup (e.g., the "swap" function at the end of the 1559218893Sdim * example). 1560218893Sdim * 1561218893Sdim * The functions \c clang_getNumOverloadedDecls() and 1562218893Sdim * \c clang_getOverloadedDecl() can be used to retrieve the definitions 1563218893Sdim * referenced by this cursor. 1564218893Sdim */ 1565218893Sdim CXCursor_OverloadedDeclRef = 49, 1566218893Sdim 1567234353Sdim /** 1568234353Sdim * \brief A reference to a variable that occurs in some non-expression 1569234353Sdim * context, e.g., a C++ lambda capture list. 1570234353Sdim */ 1571234353Sdim CXCursor_VariableRef = 50, 1572234353Sdim 1573234353Sdim CXCursor_LastRef = CXCursor_VariableRef, 1574203955Srdivacky 1575202879Srdivacky /* Error conditions */ 1576202879Srdivacky CXCursor_FirstInvalid = 70, 1577202879Srdivacky CXCursor_InvalidFile = 70, 1578202879Srdivacky CXCursor_NoDeclFound = 71, 1579202879Srdivacky CXCursor_NotImplemented = 72, 1580205408Srdivacky CXCursor_InvalidCode = 73, 1581205408Srdivacky CXCursor_LastInvalid = CXCursor_InvalidCode, 1582203955Srdivacky 1583202879Srdivacky /* Expressions */ 1584202879Srdivacky CXCursor_FirstExpr = 100, 1585203955Srdivacky 1586202879Srdivacky /** 1587202879Srdivacky * \brief An expression whose specific kind is not exposed via this 1588203955Srdivacky * interface. 1589202879Srdivacky * 1590202879Srdivacky * Unexposed expressions have the same operations as any other kind 1591202879Srdivacky * of expression; one can extract their location information, 1592202879Srdivacky * spelling, children, etc. However, the specific kind of the 1593202879Srdivacky * expression is not reported. 1594202879Srdivacky */ 1595202879Srdivacky CXCursor_UnexposedExpr = 100, 1596203955Srdivacky 1597202879Srdivacky /** 1598202879Srdivacky * \brief An expression that refers to some value declaration, such 1599202879Srdivacky * as a function, varible, or enumerator. 1600202879Srdivacky */ 1601202879Srdivacky CXCursor_DeclRefExpr = 101, 1602203955Srdivacky 1603202879Srdivacky /** 1604202879Srdivacky * \brief An expression that refers to a member of a struct, union, 1605202879Srdivacky * class, Objective-C class, etc. 1606202879Srdivacky */ 1607202879Srdivacky CXCursor_MemberRefExpr = 102, 1608203955Srdivacky 1609202879Srdivacky /** \brief An expression that calls a function. */ 1610202879Srdivacky CXCursor_CallExpr = 103, 1611203955Srdivacky 1612202879Srdivacky /** \brief An expression that sends a message to an Objective-C 1613202879Srdivacky object or class. */ 1614202879Srdivacky CXCursor_ObjCMessageExpr = 104, 1615203955Srdivacky 1616207619Srdivacky /** \brief An expression that represents a block literal. */ 1617207619Srdivacky CXCursor_BlockExpr = 105, 1618207619Srdivacky 1619226633Sdim /** \brief An integer literal. 1620226633Sdim */ 1621226633Sdim CXCursor_IntegerLiteral = 106, 1622207619Srdivacky 1623226633Sdim /** \brief A floating point number literal. 1624226633Sdim */ 1625226633Sdim CXCursor_FloatingLiteral = 107, 1626226633Sdim 1627226633Sdim /** \brief An imaginary number literal. 1628226633Sdim */ 1629226633Sdim CXCursor_ImaginaryLiteral = 108, 1630226633Sdim 1631226633Sdim /** \brief A string literal. 1632226633Sdim */ 1633226633Sdim CXCursor_StringLiteral = 109, 1634226633Sdim 1635226633Sdim /** \brief A character literal. 1636226633Sdim */ 1637226633Sdim CXCursor_CharacterLiteral = 110, 1638226633Sdim 1639226633Sdim /** \brief A parenthesized expression, e.g. "(1)". 1640226633Sdim * 1641226633Sdim * This AST node is only formed if full location information is requested. 1642226633Sdim */ 1643226633Sdim CXCursor_ParenExpr = 111, 1644226633Sdim 1645226633Sdim /** \brief This represents the unary-expression's (except sizeof and 1646226633Sdim * alignof). 1647226633Sdim */ 1648226633Sdim CXCursor_UnaryOperator = 112, 1649226633Sdim 1650226633Sdim /** \brief [C99 6.5.2.1] Array Subscripting. 1651226633Sdim */ 1652226633Sdim CXCursor_ArraySubscriptExpr = 113, 1653226633Sdim 1654226633Sdim /** \brief A builtin binary operation expression such as "x + y" or 1655226633Sdim * "x <= y". 1656226633Sdim */ 1657226633Sdim CXCursor_BinaryOperator = 114, 1658226633Sdim 1659226633Sdim /** \brief Compound assignment such as "+=". 1660226633Sdim */ 1661226633Sdim CXCursor_CompoundAssignOperator = 115, 1662226633Sdim 1663226633Sdim /** \brief The ?: ternary operator. 1664226633Sdim */ 1665226633Sdim CXCursor_ConditionalOperator = 116, 1666226633Sdim 1667226633Sdim /** \brief An explicit cast in C (C99 6.5.4) or a C-style cast in C++ 1668226633Sdim * (C++ [expr.cast]), which uses the syntax (Type)expr. 1669226633Sdim * 1670226633Sdim * For example: (int)f. 1671226633Sdim */ 1672226633Sdim CXCursor_CStyleCastExpr = 117, 1673226633Sdim 1674226633Sdim /** \brief [C99 6.5.2.5] 1675226633Sdim */ 1676226633Sdim CXCursor_CompoundLiteralExpr = 118, 1677226633Sdim 1678226633Sdim /** \brief Describes an C or C++ initializer list. 1679226633Sdim */ 1680226633Sdim CXCursor_InitListExpr = 119, 1681226633Sdim 1682226633Sdim /** \brief The GNU address of label extension, representing &&label. 1683226633Sdim */ 1684226633Sdim CXCursor_AddrLabelExpr = 120, 1685226633Sdim 1686226633Sdim /** \brief This is the GNU Statement Expression extension: ({int X=4; X;}) 1687226633Sdim */ 1688226633Sdim CXCursor_StmtExpr = 121, 1689226633Sdim 1690234353Sdim /** \brief Represents a C11 generic selection. 1691226633Sdim */ 1692226633Sdim CXCursor_GenericSelectionExpr = 122, 1693226633Sdim 1694226633Sdim /** \brief Implements the GNU __null extension, which is a name for a null 1695226633Sdim * pointer constant that has integral type (e.g., int or long) and is the same 1696226633Sdim * size and alignment as a pointer. 1697226633Sdim * 1698226633Sdim * The __null extension is typically only used by system headers, which define 1699226633Sdim * NULL as __null in C++ rather than using 0 (which is an integer that may not 1700226633Sdim * match the size of a pointer). 1701226633Sdim */ 1702226633Sdim CXCursor_GNUNullExpr = 123, 1703226633Sdim 1704226633Sdim /** \brief C++'s static_cast<> expression. 1705226633Sdim */ 1706226633Sdim CXCursor_CXXStaticCastExpr = 124, 1707226633Sdim 1708226633Sdim /** \brief C++'s dynamic_cast<> expression. 1709226633Sdim */ 1710226633Sdim CXCursor_CXXDynamicCastExpr = 125, 1711226633Sdim 1712226633Sdim /** \brief C++'s reinterpret_cast<> expression. 1713226633Sdim */ 1714226633Sdim CXCursor_CXXReinterpretCastExpr = 126, 1715226633Sdim 1716226633Sdim /** \brief C++'s const_cast<> expression. 1717226633Sdim */ 1718226633Sdim CXCursor_CXXConstCastExpr = 127, 1719226633Sdim 1720226633Sdim /** \brief Represents an explicit C++ type conversion that uses "functional" 1721226633Sdim * notion (C++ [expr.type.conv]). 1722226633Sdim * 1723226633Sdim * Example: 1724226633Sdim * \code 1725226633Sdim * x = int(0.5); 1726226633Sdim * \endcode 1727226633Sdim */ 1728226633Sdim CXCursor_CXXFunctionalCastExpr = 128, 1729226633Sdim 1730226633Sdim /** \brief A C++ typeid expression (C++ [expr.typeid]). 1731226633Sdim */ 1732226633Sdim CXCursor_CXXTypeidExpr = 129, 1733226633Sdim 1734226633Sdim /** \brief [C++ 2.13.5] C++ Boolean Literal. 1735226633Sdim */ 1736226633Sdim CXCursor_CXXBoolLiteralExpr = 130, 1737226633Sdim 1738226633Sdim /** \brief [C++0x 2.14.7] C++ Pointer Literal. 1739226633Sdim */ 1740226633Sdim CXCursor_CXXNullPtrLiteralExpr = 131, 1741226633Sdim 1742226633Sdim /** \brief Represents the "this" expression in C++ 1743226633Sdim */ 1744226633Sdim CXCursor_CXXThisExpr = 132, 1745226633Sdim 1746226633Sdim /** \brief [C++ 15] C++ Throw Expression. 1747226633Sdim * 1748226633Sdim * This handles 'throw' and 'throw' assignment-expression. When 1749226633Sdim * assignment-expression isn't present, Op will be null. 1750226633Sdim */ 1751226633Sdim CXCursor_CXXThrowExpr = 133, 1752226633Sdim 1753226633Sdim /** \brief A new expression for memory allocation and constructor calls, e.g: 1754226633Sdim * "new CXXNewExpr(foo)". 1755226633Sdim */ 1756226633Sdim CXCursor_CXXNewExpr = 134, 1757226633Sdim 1758226633Sdim /** \brief A delete expression for memory deallocation and destructor calls, 1759226633Sdim * e.g. "delete[] pArray". 1760226633Sdim */ 1761226633Sdim CXCursor_CXXDeleteExpr = 135, 1762226633Sdim 1763226633Sdim /** \brief A unary expression. 1764226633Sdim */ 1765226633Sdim CXCursor_UnaryExpr = 136, 1766226633Sdim 1767234353Sdim /** \brief An Objective-C string literal i.e. @"foo". 1768226633Sdim */ 1769226633Sdim CXCursor_ObjCStringLiteral = 137, 1770226633Sdim 1771234353Sdim /** \brief An Objective-C @encode expression. 1772226633Sdim */ 1773226633Sdim CXCursor_ObjCEncodeExpr = 138, 1774226633Sdim 1775234353Sdim /** \brief An Objective-C @selector expression. 1776226633Sdim */ 1777226633Sdim CXCursor_ObjCSelectorExpr = 139, 1778226633Sdim 1779234353Sdim /** \brief An Objective-C @protocol expression. 1780226633Sdim */ 1781226633Sdim CXCursor_ObjCProtocolExpr = 140, 1782226633Sdim 1783226633Sdim /** \brief An Objective-C "bridged" cast expression, which casts between 1784226633Sdim * Objective-C pointers and C pointers, transferring ownership in the process. 1785226633Sdim * 1786226633Sdim * \code 1787226633Sdim * NSString *str = (__bridge_transfer NSString *)CFCreateString(); 1788226633Sdim * \endcode 1789226633Sdim */ 1790226633Sdim CXCursor_ObjCBridgedCastExpr = 141, 1791226633Sdim 1792226633Sdim /** \brief Represents a C++0x pack expansion that produces a sequence of 1793226633Sdim * expressions. 1794226633Sdim * 1795226633Sdim * A pack expansion expression contains a pattern (which itself is an 1796226633Sdim * expression) followed by an ellipsis. For example: 1797226633Sdim * 1798226633Sdim * \code 1799226633Sdim * template<typename F, typename ...Types> 1800226633Sdim * void forward(F f, Types &&...args) { 1801226633Sdim * f(static_cast<Types&&>(args)...); 1802226633Sdim * } 1803226633Sdim * \endcode 1804226633Sdim */ 1805226633Sdim CXCursor_PackExpansionExpr = 142, 1806226633Sdim 1807226633Sdim /** \brief Represents an expression that computes the length of a parameter 1808226633Sdim * pack. 1809226633Sdim * 1810226633Sdim * \code 1811226633Sdim * template<typename ...Types> 1812226633Sdim * struct count { 1813226633Sdim * static const unsigned value = sizeof...(Types); 1814226633Sdim * }; 1815226633Sdim * \endcode 1816226633Sdim */ 1817226633Sdim CXCursor_SizeOfPackExpr = 143, 1818226633Sdim 1819234353Sdim /* \brief Represents a C++ lambda expression that produces a local function 1820234353Sdim * object. 1821234353Sdim * 1822234353Sdim * \code 1823234353Sdim * void abssort(float *x, unsigned N) { 1824234353Sdim * std::sort(x, x + N, 1825234353Sdim * [](float a, float b) { 1826234353Sdim * return std::abs(a) < std::abs(b); 1827234353Sdim * }); 1828234353Sdim * } 1829234353Sdim * \endcode 1830234353Sdim */ 1831234353Sdim CXCursor_LambdaExpr = 144, 1832234353Sdim 1833234353Sdim /** \brief Objective-c Boolean Literal. 1834234353Sdim */ 1835234353Sdim CXCursor_ObjCBoolLiteralExpr = 145, 1836226633Sdim 1837234353Sdim CXCursor_LastExpr = CXCursor_ObjCBoolLiteralExpr, 1838234353Sdim 1839202879Srdivacky /* Statements */ 1840202879Srdivacky CXCursor_FirstStmt = 200, 1841202879Srdivacky /** 1842202879Srdivacky * \brief A statement whose specific kind is not exposed via this 1843202879Srdivacky * interface. 1844202879Srdivacky * 1845202879Srdivacky * Unexposed statements have the same operations as any other kind of 1846202879Srdivacky * statement; one can extract their location information, spelling, 1847202879Srdivacky * children, etc. However, the specific kind of the statement is not 1848202879Srdivacky * reported. 1849202879Srdivacky */ 1850202879Srdivacky CXCursor_UnexposedStmt = 200, 1851218893Sdim 1852218893Sdim /** \brief A labelled statement in a function. 1853218893Sdim * 1854218893Sdim * This cursor kind is used to describe the "start_over:" label statement in 1855218893Sdim * the following example: 1856218893Sdim * 1857218893Sdim * \code 1858218893Sdim * start_over: 1859218893Sdim * ++counter; 1860218893Sdim * \endcode 1861218893Sdim * 1862218893Sdim */ 1863218893Sdim CXCursor_LabelStmt = 201, 1864203955Srdivacky 1865226633Sdim /** \brief A group of statements like { stmt stmt }. 1866226633Sdim * 1867226633Sdim * This cursor kind is used to describe compound statements, e.g. function 1868226633Sdim * bodies. 1869226633Sdim */ 1870226633Sdim CXCursor_CompoundStmt = 202, 1871226633Sdim 1872226633Sdim /** \brief A case statment. 1873226633Sdim */ 1874226633Sdim CXCursor_CaseStmt = 203, 1875226633Sdim 1876226633Sdim /** \brief A default statement. 1877226633Sdim */ 1878226633Sdim CXCursor_DefaultStmt = 204, 1879226633Sdim 1880226633Sdim /** \brief An if statement 1881226633Sdim */ 1882226633Sdim CXCursor_IfStmt = 205, 1883226633Sdim 1884226633Sdim /** \brief A switch statement. 1885226633Sdim */ 1886226633Sdim CXCursor_SwitchStmt = 206, 1887226633Sdim 1888226633Sdim /** \brief A while statement. 1889226633Sdim */ 1890226633Sdim CXCursor_WhileStmt = 207, 1891226633Sdim 1892226633Sdim /** \brief A do statement. 1893226633Sdim */ 1894226633Sdim CXCursor_DoStmt = 208, 1895226633Sdim 1896226633Sdim /** \brief A for statement. 1897226633Sdim */ 1898226633Sdim CXCursor_ForStmt = 209, 1899226633Sdim 1900226633Sdim /** \brief A goto statement. 1901226633Sdim */ 1902226633Sdim CXCursor_GotoStmt = 210, 1903226633Sdim 1904226633Sdim /** \brief An indirect goto statement. 1905226633Sdim */ 1906226633Sdim CXCursor_IndirectGotoStmt = 211, 1907226633Sdim 1908226633Sdim /** \brief A continue statement. 1909226633Sdim */ 1910226633Sdim CXCursor_ContinueStmt = 212, 1911226633Sdim 1912226633Sdim /** \brief A break statement. 1913226633Sdim */ 1914226633Sdim CXCursor_BreakStmt = 213, 1915226633Sdim 1916226633Sdim /** \brief A return statement. 1917226633Sdim */ 1918226633Sdim CXCursor_ReturnStmt = 214, 1919226633Sdim 1920226633Sdim /** \brief A GNU inline assembly statement extension. 1921226633Sdim */ 1922226633Sdim CXCursor_AsmStmt = 215, 1923226633Sdim 1924234353Sdim /** \brief Objective-C's overall @try-@catch-@finally statement. 1925226633Sdim */ 1926226633Sdim CXCursor_ObjCAtTryStmt = 216, 1927226633Sdim 1928226633Sdim /** \brief Objective-C's @catch statement. 1929226633Sdim */ 1930226633Sdim CXCursor_ObjCAtCatchStmt = 217, 1931226633Sdim 1932226633Sdim /** \brief Objective-C's @finally statement. 1933226633Sdim */ 1934226633Sdim CXCursor_ObjCAtFinallyStmt = 218, 1935226633Sdim 1936226633Sdim /** \brief Objective-C's @throw statement. 1937226633Sdim */ 1938226633Sdim CXCursor_ObjCAtThrowStmt = 219, 1939226633Sdim 1940226633Sdim /** \brief Objective-C's @synchronized statement. 1941226633Sdim */ 1942226633Sdim CXCursor_ObjCAtSynchronizedStmt = 220, 1943226633Sdim 1944226633Sdim /** \brief Objective-C's autorelease pool statement. 1945226633Sdim */ 1946226633Sdim CXCursor_ObjCAutoreleasePoolStmt = 221, 1947226633Sdim 1948226633Sdim /** \brief Objective-C's collection statement. 1949226633Sdim */ 1950226633Sdim CXCursor_ObjCForCollectionStmt = 222, 1951226633Sdim 1952226633Sdim /** \brief C++'s catch statement. 1953226633Sdim */ 1954226633Sdim CXCursor_CXXCatchStmt = 223, 1955226633Sdim 1956226633Sdim /** \brief C++'s try statement. 1957226633Sdim */ 1958226633Sdim CXCursor_CXXTryStmt = 224, 1959226633Sdim 1960226633Sdim /** \brief C++'s for (* : *) statement. 1961226633Sdim */ 1962226633Sdim CXCursor_CXXForRangeStmt = 225, 1963226633Sdim 1964226633Sdim /** \brief Windows Structured Exception Handling's try statement. 1965226633Sdim */ 1966226633Sdim CXCursor_SEHTryStmt = 226, 1967226633Sdim 1968226633Sdim /** \brief Windows Structured Exception Handling's except statement. 1969226633Sdim */ 1970226633Sdim CXCursor_SEHExceptStmt = 227, 1971226633Sdim 1972226633Sdim /** \brief Windows Structured Exception Handling's finally statement. 1973226633Sdim */ 1974226633Sdim CXCursor_SEHFinallyStmt = 228, 1975226633Sdim 1976226633Sdim /** \brief The null satement ";": C99 6.8.3p3. 1977226633Sdim * 1978226633Sdim * This cursor kind is used to describe the null statement. 1979226633Sdim */ 1980226633Sdim CXCursor_NullStmt = 230, 1981226633Sdim 1982226633Sdim /** \brief Adaptor class for mixing declarations with statements and 1983226633Sdim * expressions. 1984226633Sdim */ 1985226633Sdim CXCursor_DeclStmt = 231, 1986226633Sdim 1987226633Sdim CXCursor_LastStmt = CXCursor_DeclStmt, 1988226633Sdim 1989202879Srdivacky /** 1990202879Srdivacky * \brief Cursor that represents the translation unit itself. 1991202879Srdivacky * 1992202879Srdivacky * The translation unit cursor exists primarily to act as the root 1993202879Srdivacky * cursor for traversing the contents of a translation unit. 1994202879Srdivacky */ 1995204643Srdivacky CXCursor_TranslationUnit = 300, 1996204643Srdivacky 1997204643Srdivacky /* Attributes */ 1998204643Srdivacky CXCursor_FirstAttr = 400, 1999204643Srdivacky /** 2000204643Srdivacky * \brief An attribute whose specific kind is not exposed via this 2001204643Srdivacky * interface. 2002204643Srdivacky */ 2003204643Srdivacky CXCursor_UnexposedAttr = 400, 2004204643Srdivacky 2005204643Srdivacky CXCursor_IBActionAttr = 401, 2006204643Srdivacky CXCursor_IBOutletAttr = 402, 2007208600Srdivacky CXCursor_IBOutletCollectionAttr = 403, 2008226633Sdim CXCursor_CXXFinalAttr = 404, 2009226633Sdim CXCursor_CXXOverrideAttr = 405, 2010226633Sdim CXCursor_AnnotateAttr = 406, 2011234353Sdim CXCursor_AsmLabelAttr = 407, 2012234353Sdim CXCursor_LastAttr = CXCursor_AsmLabelAttr, 2013205408Srdivacky 2014205408Srdivacky /* Preprocessing */ 2015205408Srdivacky CXCursor_PreprocessingDirective = 500, 2016205408Srdivacky CXCursor_MacroDefinition = 501, 2017224145Sdim CXCursor_MacroExpansion = 502, 2018224145Sdim CXCursor_MacroInstantiation = CXCursor_MacroExpansion, 2019218893Sdim CXCursor_InclusionDirective = 503, 2020205408Srdivacky CXCursor_FirstPreprocessing = CXCursor_PreprocessingDirective, 2021218893Sdim CXCursor_LastPreprocessing = CXCursor_InclusionDirective 2022202879Srdivacky}; 2023202379Srdivacky 2024202879Srdivacky/** 2025202879Srdivacky * \brief A cursor representing some element in the abstract syntax tree for 2026202879Srdivacky * a translation unit. 2027202879Srdivacky * 2028203955Srdivacky * The cursor abstraction unifies the different kinds of entities in a 2029202879Srdivacky * program--declaration, statements, expressions, references to declarations, 2030202879Srdivacky * etc.--under a single "cursor" abstraction with a common set of operations. 2031202879Srdivacky * Common operation for a cursor include: getting the physical location in 2032202879Srdivacky * a source file where the cursor points, getting the name associated with a 2033202879Srdivacky * cursor, and retrieving cursors for any child nodes of a particular cursor. 2034202879Srdivacky * 2035202879Srdivacky * Cursors can be produced in two specific ways. 2036202879Srdivacky * clang_getTranslationUnitCursor() produces a cursor for a translation unit, 2037202879Srdivacky * from which one can use clang_visitChildren() to explore the rest of the 2038202879Srdivacky * translation unit. clang_getCursor() maps from a physical source location 2039202879Srdivacky * to the entity that resides at that location, allowing one to map from the 2040202879Srdivacky * source code into the AST. 2041198092Srdivacky */ 2042202879Srdivackytypedef struct { 2043202879Srdivacky enum CXCursorKind kind; 2044226633Sdim int xdata; 2045202879Srdivacky void *data[3]; 2046203955Srdivacky} CXCursor; 2047202879Srdivacky 2048198398Srdivacky/** 2049202879Srdivacky * \defgroup CINDEX_CURSOR_MANIP Cursor manipulations 2050202879Srdivacky * 2051202879Srdivacky * @{ 2052198398Srdivacky */ 2053203955Srdivacky 2054202879Srdivacky/** 2055202879Srdivacky * \brief Retrieve the NULL cursor, which represents no entity. 2056202879Srdivacky */ 2057199482SrdivackyCINDEX_LINKAGE CXCursor clang_getNullCursor(void); 2058203955Srdivacky 2059202879Srdivacky/** 2060202879Srdivacky * \brief Retrieve the cursor that represents the given translation unit. 2061202879Srdivacky * 2062202879Srdivacky * The translation unit cursor can be used to start traversing the 2063202879Srdivacky * various declarations within the given translation unit. 2064202879Srdivacky */ 2065202879SrdivackyCINDEX_LINKAGE CXCursor clang_getTranslationUnitCursor(CXTranslationUnit); 2066198092Srdivacky 2067202879Srdivacky/** 2068202879Srdivacky * \brief Determine whether two cursors are equivalent. 2069202879Srdivacky */ 2070202879SrdivackyCINDEX_LINKAGE unsigned clang_equalCursors(CXCursor, CXCursor); 2071203955Srdivacky 2072202879Srdivacky/** 2073226633Sdim * \brief Returns non-zero if \arg cursor is null. 2074226633Sdim */ 2075234353SdimCINDEX_LINKAGE int clang_Cursor_isNull(CXCursor); 2076226633Sdim 2077226633Sdim/** 2078218893Sdim * \brief Compute a hash value for the given cursor. 2079218893Sdim */ 2080218893SdimCINDEX_LINKAGE unsigned clang_hashCursor(CXCursor); 2081218893Sdim 2082218893Sdim/** 2083202879Srdivacky * \brief Retrieve the kind of the given cursor. 2084202879Srdivacky */ 2085198893SrdivackyCINDEX_LINKAGE enum CXCursorKind clang_getCursorKind(CXCursor); 2086202879Srdivacky 2087202879Srdivacky/** 2088202879Srdivacky * \brief Determine whether the given cursor kind represents a declaration. 2089202879Srdivacky */ 2090198893SrdivackyCINDEX_LINKAGE unsigned clang_isDeclaration(enum CXCursorKind); 2091202879Srdivacky 2092202879Srdivacky/** 2093202879Srdivacky * \brief Determine whether the given cursor kind represents a simple 2094202879Srdivacky * reference. 2095202879Srdivacky * 2096202879Srdivacky * Note that other kinds of cursors (such as expressions) can also refer to 2097202879Srdivacky * other cursors. Use clang_getCursorReferenced() to determine whether a 2098202879Srdivacky * particular cursor refers to another entity. 2099202879Srdivacky */ 2100198893SrdivackyCINDEX_LINKAGE unsigned clang_isReference(enum CXCursorKind); 2101202879Srdivacky 2102202879Srdivacky/** 2103202879Srdivacky * \brief Determine whether the given cursor kind represents an expression. 2104202879Srdivacky */ 2105202879SrdivackyCINDEX_LINKAGE unsigned clang_isExpression(enum CXCursorKind); 2106202879Srdivacky 2107202879Srdivacky/** 2108202879Srdivacky * \brief Determine whether the given cursor kind represents a statement. 2109202879Srdivacky */ 2110202879SrdivackyCINDEX_LINKAGE unsigned clang_isStatement(enum CXCursorKind); 2111202879Srdivacky 2112202879Srdivacky/** 2113224145Sdim * \brief Determine whether the given cursor kind represents an attribute. 2114224145Sdim */ 2115224145SdimCINDEX_LINKAGE unsigned clang_isAttribute(enum CXCursorKind); 2116224145Sdim 2117224145Sdim/** 2118203955Srdivacky * \brief Determine whether the given cursor kind represents an invalid 2119202879Srdivacky * cursor. 2120203955Srdivacky */ 2121198893SrdivackyCINDEX_LINKAGE unsigned clang_isInvalid(enum CXCursorKind); 2122198398Srdivacky 2123202879Srdivacky/** 2124203955Srdivacky * \brief Determine whether the given cursor kind represents a translation 2125203955Srdivacky * unit. 2126202879Srdivacky */ 2127202879SrdivackyCINDEX_LINKAGE unsigned clang_isTranslationUnit(enum CXCursorKind); 2128203955Srdivacky 2129204962Srdivacky/*** 2130205408Srdivacky * \brief Determine whether the given cursor represents a preprocessing 2131205408Srdivacky * element, such as a preprocessor directive or macro instantiation. 2132205408Srdivacky */ 2133205408SrdivackyCINDEX_LINKAGE unsigned clang_isPreprocessing(enum CXCursorKind); 2134205408Srdivacky 2135205408Srdivacky/*** 2136204962Srdivacky * \brief Determine whether the given cursor represents a currently 2137204962Srdivacky * unexposed piece of the AST (e.g., CXCursor_UnexposedStmt). 2138204962Srdivacky */ 2139204962SrdivackyCINDEX_LINKAGE unsigned clang_isUnexposed(enum CXCursorKind); 2140204962Srdivacky 2141202879Srdivacky/** 2142204643Srdivacky * \brief Describe the linkage of the entity referred to by a cursor. 2143204643Srdivacky */ 2144204643Srdivackyenum CXLinkageKind { 2145204643Srdivacky /** \brief This value indicates that no linkage information is available 2146204643Srdivacky * for a provided CXCursor. */ 2147204643Srdivacky CXLinkage_Invalid, 2148204643Srdivacky /** 2149204643Srdivacky * \brief This is the linkage for variables, parameters, and so on that 2150204643Srdivacky * have automatic storage. This covers normal (non-extern) local variables. 2151204643Srdivacky */ 2152204643Srdivacky CXLinkage_NoLinkage, 2153204643Srdivacky /** \brief This is the linkage for static variables and static functions. */ 2154204643Srdivacky CXLinkage_Internal, 2155204643Srdivacky /** \brief This is the linkage for entities with external linkage that live 2156204643Srdivacky * in C++ anonymous namespaces.*/ 2157204643Srdivacky CXLinkage_UniqueExternal, 2158204643Srdivacky /** \brief This is the linkage for entities with true, external linkage. */ 2159204643Srdivacky CXLinkage_External 2160204643Srdivacky}; 2161204643Srdivacky 2162204643Srdivacky/** 2163207619Srdivacky * \brief Determine the linkage of the entity referred to by a given cursor. 2164204643Srdivacky */ 2165204643SrdivackyCINDEX_LINKAGE enum CXLinkageKind clang_getCursorLinkage(CXCursor cursor); 2166204643Srdivacky 2167204643Srdivacky/** 2168212904Sdim * \brief Determine the availability of the entity that this cursor refers to. 2169212904Sdim * 2170212904Sdim * \param cursor The cursor to query. 2171212904Sdim * 2172212904Sdim * \returns The availability of the cursor. 2173212904Sdim */ 2174212904SdimCINDEX_LINKAGE enum CXAvailabilityKind 2175212904Sdimclang_getCursorAvailability(CXCursor cursor); 2176212904Sdim 2177212904Sdim/** 2178207619Srdivacky * \brief Describe the "language" of the entity referred to by a cursor. 2179207619Srdivacky */ 2180207619SrdivackyCINDEX_LINKAGE enum CXLanguageKind { 2181207619Srdivacky CXLanguage_Invalid = 0, 2182207619Srdivacky CXLanguage_C, 2183207619Srdivacky CXLanguage_ObjC, 2184207619Srdivacky CXLanguage_CPlusPlus 2185207619Srdivacky}; 2186207619Srdivacky 2187207619Srdivacky/** 2188207619Srdivacky * \brief Determine the "language" of the entity referred to by a given cursor. 2189207619Srdivacky */ 2190207619SrdivackyCINDEX_LINKAGE enum CXLanguageKind clang_getCursorLanguage(CXCursor cursor); 2191207619Srdivacky 2192226633Sdim/** 2193226633Sdim * \brief Returns the translation unit that a cursor originated from. 2194226633Sdim */ 2195226633SdimCINDEX_LINKAGE CXTranslationUnit clang_Cursor_getTranslationUnit(CXCursor); 2196218893Sdim 2197226633Sdim 2198207619Srdivacky/** 2199218893Sdim * \brief A fast container representing a set of CXCursors. 2200218893Sdim */ 2201218893Sdimtypedef struct CXCursorSetImpl *CXCursorSet; 2202218893Sdim 2203218893Sdim/** 2204218893Sdim * \brief Creates an empty CXCursorSet. 2205218893Sdim */ 2206218893SdimCINDEX_LINKAGE CXCursorSet clang_createCXCursorSet(); 2207218893Sdim 2208218893Sdim/** 2209218893Sdim * \brief Disposes a CXCursorSet and releases its associated memory. 2210218893Sdim */ 2211218893SdimCINDEX_LINKAGE void clang_disposeCXCursorSet(CXCursorSet cset); 2212218893Sdim 2213218893Sdim/** 2214218893Sdim * \brief Queries a CXCursorSet to see if it contains a specific CXCursor. 2215218893Sdim * 2216218893Sdim * \returns non-zero if the set contains the specified cursor. 2217218893Sdim*/ 2218218893SdimCINDEX_LINKAGE unsigned clang_CXCursorSet_contains(CXCursorSet cset, 2219218893Sdim CXCursor cursor); 2220218893Sdim 2221218893Sdim/** 2222218893Sdim * \brief Inserts a CXCursor into a CXCursorSet. 2223218893Sdim * 2224218893Sdim * \returns zero if the CXCursor was already in the set, and non-zero otherwise. 2225218893Sdim*/ 2226218893SdimCINDEX_LINKAGE unsigned clang_CXCursorSet_insert(CXCursorSet cset, 2227218893Sdim CXCursor cursor); 2228218893Sdim 2229218893Sdim/** 2230218893Sdim * \brief Determine the semantic parent of the given cursor. 2231218893Sdim * 2232218893Sdim * The semantic parent of a cursor is the cursor that semantically contains 2233218893Sdim * the given \p cursor. For many declarations, the lexical and semantic parents 2234218893Sdim * are equivalent (the lexical parent is returned by 2235218893Sdim * \c clang_getCursorLexicalParent()). They diverge when declarations or 2236218893Sdim * definitions are provided out-of-line. For example: 2237218893Sdim * 2238218893Sdim * \code 2239218893Sdim * class C { 2240218893Sdim * void f(); 2241218893Sdim * }; 2242218893Sdim * 2243218893Sdim * void C::f() { } 2244218893Sdim * \endcode 2245218893Sdim * 2246218893Sdim * In the out-of-line definition of \c C::f, the semantic parent is the 2247218893Sdim * the class \c C, of which this function is a member. The lexical parent is 2248218893Sdim * the place where the declaration actually occurs in the source code; in this 2249218893Sdim * case, the definition occurs in the translation unit. In general, the 2250218893Sdim * lexical parent for a given entity can change without affecting the semantics 2251218893Sdim * of the program, and the lexical parent of different declarations of the 2252218893Sdim * same entity may be different. Changing the semantic parent of a declaration, 2253218893Sdim * on the other hand, can have a major impact on semantics, and redeclarations 2254218893Sdim * of a particular entity should all have the same semantic context. 2255218893Sdim * 2256218893Sdim * In the example above, both declarations of \c C::f have \c C as their 2257218893Sdim * semantic context, while the lexical context of the first \c C::f is \c C 2258218893Sdim * and the lexical context of the second \c C::f is the translation unit. 2259218893Sdim * 2260218893Sdim * For global declarations, the semantic parent is the translation unit. 2261218893Sdim */ 2262218893SdimCINDEX_LINKAGE CXCursor clang_getCursorSemanticParent(CXCursor cursor); 2263218893Sdim 2264218893Sdim/** 2265218893Sdim * \brief Determine the lexical parent of the given cursor. 2266218893Sdim * 2267218893Sdim * The lexical parent of a cursor is the cursor in which the given \p cursor 2268218893Sdim * was actually written. For many declarations, the lexical and semantic parents 2269218893Sdim * are equivalent (the semantic parent is returned by 2270218893Sdim * \c clang_getCursorSemanticParent()). They diverge when declarations or 2271218893Sdim * definitions are provided out-of-line. For example: 2272218893Sdim * 2273218893Sdim * \code 2274218893Sdim * class C { 2275218893Sdim * void f(); 2276218893Sdim * }; 2277218893Sdim * 2278218893Sdim * void C::f() { } 2279218893Sdim * \endcode 2280218893Sdim * 2281218893Sdim * In the out-of-line definition of \c C::f, the semantic parent is the 2282218893Sdim * the class \c C, of which this function is a member. The lexical parent is 2283218893Sdim * the place where the declaration actually occurs in the source code; in this 2284218893Sdim * case, the definition occurs in the translation unit. In general, the 2285218893Sdim * lexical parent for a given entity can change without affecting the semantics 2286218893Sdim * of the program, and the lexical parent of different declarations of the 2287218893Sdim * same entity may be different. Changing the semantic parent of a declaration, 2288218893Sdim * on the other hand, can have a major impact on semantics, and redeclarations 2289218893Sdim * of a particular entity should all have the same semantic context. 2290218893Sdim * 2291218893Sdim * In the example above, both declarations of \c C::f have \c C as their 2292218893Sdim * semantic context, while the lexical context of the first \c C::f is \c C 2293218893Sdim * and the lexical context of the second \c C::f is the translation unit. 2294218893Sdim * 2295218893Sdim * For declarations written in the global scope, the lexical parent is 2296218893Sdim * the translation unit. 2297218893Sdim */ 2298218893SdimCINDEX_LINKAGE CXCursor clang_getCursorLexicalParent(CXCursor cursor); 2299218893Sdim 2300218893Sdim/** 2301218893Sdim * \brief Determine the set of methods that are overridden by the given 2302218893Sdim * method. 2303218893Sdim * 2304218893Sdim * In both Objective-C and C++, a method (aka virtual member function, 2305218893Sdim * in C++) can override a virtual method in a base class. For 2306218893Sdim * Objective-C, a method is said to override any method in the class's 2307234353Sdim * base class, its protocols, or its categories' protocols, that has the same 2308234353Sdim * selector and is of the same kind (class or instance). 2309234353Sdim * If no such method exists, the search continues to the class's superclass, 2310234353Sdim * its protocols, and its categories, and so on. A method from an Objective-C 2311234353Sdim * implementation is considered to override the same methods as its 2312234353Sdim * corresponding method in the interface. 2313218893Sdim * 2314218893Sdim * For C++, a virtual member function overrides any virtual member 2315218893Sdim * function with the same signature that occurs in its base 2316218893Sdim * classes. With multiple inheritance, a virtual member function can 2317218893Sdim * override several virtual member functions coming from different 2318218893Sdim * base classes. 2319218893Sdim * 2320218893Sdim * In all cases, this function determines the immediate overridden 2321218893Sdim * method, rather than all of the overridden methods. For example, if 2322218893Sdim * a method is originally declared in a class A, then overridden in B 2323218893Sdim * (which in inherits from A) and also in C (which inherited from B), 2324218893Sdim * then the only overridden method returned from this function when 2325218893Sdim * invoked on C's method will be B's method. The client may then 2326218893Sdim * invoke this function again, given the previously-found overridden 2327218893Sdim * methods, to map out the complete method-override set. 2328218893Sdim * 2329218893Sdim * \param cursor A cursor representing an Objective-C or C++ 2330218893Sdim * method. This routine will compute the set of methods that this 2331218893Sdim * method overrides. 2332218893Sdim * 2333218893Sdim * \param overridden A pointer whose pointee will be replaced with a 2334218893Sdim * pointer to an array of cursors, representing the set of overridden 2335218893Sdim * methods. If there are no overridden methods, the pointee will be 2336218893Sdim * set to NULL. The pointee must be freed via a call to 2337218893Sdim * \c clang_disposeOverriddenCursors(). 2338218893Sdim * 2339218893Sdim * \param num_overridden A pointer to the number of overridden 2340218893Sdim * functions, will be set to the number of overridden functions in the 2341218893Sdim * array pointed to by \p overridden. 2342218893Sdim */ 2343218893SdimCINDEX_LINKAGE void clang_getOverriddenCursors(CXCursor cursor, 2344218893Sdim CXCursor **overridden, 2345218893Sdim unsigned *num_overridden); 2346218893Sdim 2347218893Sdim/** 2348218893Sdim * \brief Free the set of overridden cursors returned by \c 2349218893Sdim * clang_getOverriddenCursors(). 2350218893Sdim */ 2351218893SdimCINDEX_LINKAGE void clang_disposeOverriddenCursors(CXCursor *overridden); 2352218893Sdim 2353218893Sdim/** 2354218893Sdim * \brief Retrieve the file that is included by the given inclusion directive 2355218893Sdim * cursor. 2356218893Sdim */ 2357218893SdimCINDEX_LINKAGE CXFile clang_getIncludedFile(CXCursor cursor); 2358218893Sdim 2359218893Sdim/** 2360202879Srdivacky * @} 2361202879Srdivacky */ 2362203955Srdivacky 2363202879Srdivacky/** 2364202879Srdivacky * \defgroup CINDEX_CURSOR_SOURCE Mapping between cursors and source code 2365202879Srdivacky * 2366202879Srdivacky * Cursors represent a location within the Abstract Syntax Tree (AST). These 2367202879Srdivacky * routines help map between cursors and the physical locations where the 2368202879Srdivacky * described entities occur in the source code. The mapping is provided in 2369202879Srdivacky * both directions, so one can map from source code to the AST and back. 2370202879Srdivacky * 2371202879Srdivacky * @{ 2372202879Srdivacky */ 2373203955Srdivacky 2374202879Srdivacky/** 2375202879Srdivacky * \brief Map a source location to the cursor that describes the entity at that 2376202879Srdivacky * location in the source code. 2377202879Srdivacky * 2378202879Srdivacky * clang_getCursor() maps an arbitrary source location within a translation 2379202879Srdivacky * unit down to the most specific cursor that describes the entity at that 2380203955Srdivacky * location. For example, given an expression \c x + y, invoking 2381202879Srdivacky * clang_getCursor() with a source location pointing to "x" will return the 2382203955Srdivacky * cursor for "x"; similarly for "y". If the cursor points anywhere between 2383202879Srdivacky * "x" or "y" (e.g., on the + or the whitespace around it), clang_getCursor() 2384202879Srdivacky * will return a cursor referring to the "+" expression. 2385202879Srdivacky * 2386202879Srdivacky * \returns a cursor representing the entity at the given source location, or 2387202879Srdivacky * a NULL cursor if no such entity can be found. 2388202879Srdivacky */ 2389202879SrdivackyCINDEX_LINKAGE CXCursor clang_getCursor(CXTranslationUnit, CXSourceLocation); 2390203955Srdivacky 2391202879Srdivacky/** 2392202879Srdivacky * \brief Retrieve the physical location of the source constructor referenced 2393202879Srdivacky * by the given cursor. 2394202879Srdivacky * 2395202879Srdivacky * The location of a declaration is typically the location of the name of that 2396203955Srdivacky * declaration, where the name of that declaration would occur if it is 2397203955Srdivacky * unnamed, or some keyword that introduces that particular declaration. 2398203955Srdivacky * The location of a reference is where that reference occurs within the 2399202879Srdivacky * source code. 2400202879Srdivacky */ 2401202879SrdivackyCINDEX_LINKAGE CXSourceLocation clang_getCursorLocation(CXCursor); 2402199482Srdivacky 2403202879Srdivacky/** 2404202879Srdivacky * \brief Retrieve the physical extent of the source construct referenced by 2405202879Srdivacky * the given cursor. 2406202879Srdivacky * 2407202879Srdivacky * The extent of a cursor starts with the file/line/column pointing at the 2408202879Srdivacky * first character within the source construct that the cursor refers to and 2409203955Srdivacky * ends with the last character withinin that source construct. For a 2410202879Srdivacky * declaration, the extent covers the declaration itself. For a reference, 2411202879Srdivacky * the extent covers the location of the reference (e.g., where the referenced 2412202879Srdivacky * entity was actually used). 2413202879Srdivacky */ 2414202879SrdivackyCINDEX_LINKAGE CXSourceRange clang_getCursorExtent(CXCursor); 2415202879Srdivacky 2416202879Srdivacky/** 2417202879Srdivacky * @} 2418202879Srdivacky */ 2419212904Sdim 2420202879Srdivacky/** 2421208600Srdivacky * \defgroup CINDEX_TYPES Type information for CXCursors 2422208600Srdivacky * 2423208600Srdivacky * @{ 2424208600Srdivacky */ 2425208600Srdivacky 2426208600Srdivacky/** 2427208600Srdivacky * \brief Describes the kind of type 2428208600Srdivacky */ 2429208600Srdivackyenum CXTypeKind { 2430208600Srdivacky /** 2431208600Srdivacky * \brief Reprents an invalid type (e.g., where no type is available). 2432208600Srdivacky */ 2433208600Srdivacky CXType_Invalid = 0, 2434208600Srdivacky 2435208600Srdivacky /** 2436208600Srdivacky * \brief A type whose specific kind is not exposed via this 2437208600Srdivacky * interface. 2438208600Srdivacky */ 2439208600Srdivacky CXType_Unexposed = 1, 2440208600Srdivacky 2441208600Srdivacky /* Builtin types */ 2442208600Srdivacky CXType_Void = 2, 2443208600Srdivacky CXType_Bool = 3, 2444208600Srdivacky CXType_Char_U = 4, 2445208600Srdivacky CXType_UChar = 5, 2446208600Srdivacky CXType_Char16 = 6, 2447208600Srdivacky CXType_Char32 = 7, 2448208600Srdivacky CXType_UShort = 8, 2449208600Srdivacky CXType_UInt = 9, 2450208600Srdivacky CXType_ULong = 10, 2451208600Srdivacky CXType_ULongLong = 11, 2452208600Srdivacky CXType_UInt128 = 12, 2453208600Srdivacky CXType_Char_S = 13, 2454208600Srdivacky CXType_SChar = 14, 2455208600Srdivacky CXType_WChar = 15, 2456208600Srdivacky CXType_Short = 16, 2457208600Srdivacky CXType_Int = 17, 2458208600Srdivacky CXType_Long = 18, 2459208600Srdivacky CXType_LongLong = 19, 2460208600Srdivacky CXType_Int128 = 20, 2461208600Srdivacky CXType_Float = 21, 2462208600Srdivacky CXType_Double = 22, 2463208600Srdivacky CXType_LongDouble = 23, 2464208600Srdivacky CXType_NullPtr = 24, 2465208600Srdivacky CXType_Overload = 25, 2466208600Srdivacky CXType_Dependent = 26, 2467208600Srdivacky CXType_ObjCId = 27, 2468208600Srdivacky CXType_ObjCClass = 28, 2469208600Srdivacky CXType_ObjCSel = 29, 2470208600Srdivacky CXType_FirstBuiltin = CXType_Void, 2471208600Srdivacky CXType_LastBuiltin = CXType_ObjCSel, 2472208600Srdivacky 2473208600Srdivacky CXType_Complex = 100, 2474208600Srdivacky CXType_Pointer = 101, 2475208600Srdivacky CXType_BlockPointer = 102, 2476208600Srdivacky CXType_LValueReference = 103, 2477208600Srdivacky CXType_RValueReference = 104, 2478208600Srdivacky CXType_Record = 105, 2479208600Srdivacky CXType_Enum = 106, 2480208600Srdivacky CXType_Typedef = 107, 2481208600Srdivacky CXType_ObjCInterface = 108, 2482210299Sed CXType_ObjCObjectPointer = 109, 2483210299Sed CXType_FunctionNoProto = 110, 2484226633Sdim CXType_FunctionProto = 111, 2485234353Sdim CXType_ConstantArray = 112, 2486234353Sdim CXType_Vector = 113 2487208600Srdivacky}; 2488208600Srdivacky 2489208600Srdivacky/** 2490234353Sdim * \brief Describes the calling convention of a function type 2491234353Sdim */ 2492234353Sdimenum CXCallingConv { 2493234353Sdim CXCallingConv_Default = 0, 2494234353Sdim CXCallingConv_C = 1, 2495234353Sdim CXCallingConv_X86StdCall = 2, 2496234353Sdim CXCallingConv_X86FastCall = 3, 2497234353Sdim CXCallingConv_X86ThisCall = 4, 2498234353Sdim CXCallingConv_X86Pascal = 5, 2499234353Sdim CXCallingConv_AAPCS = 6, 2500234353Sdim CXCallingConv_AAPCS_VFP = 7, 2501234353Sdim 2502234353Sdim CXCallingConv_Invalid = 100, 2503234353Sdim CXCallingConv_Unexposed = 200 2504234353Sdim}; 2505234353Sdim 2506234353Sdim 2507234353Sdim/** 2508208600Srdivacky * \brief The type of an element in the abstract syntax tree. 2509208600Srdivacky * 2510208600Srdivacky */ 2511208600Srdivackytypedef struct { 2512208600Srdivacky enum CXTypeKind kind; 2513208600Srdivacky void *data[2]; 2514208600Srdivacky} CXType; 2515208600Srdivacky 2516208600Srdivacky/** 2517208600Srdivacky * \brief Retrieve the type of a CXCursor (if any). 2518208600Srdivacky */ 2519208600SrdivackyCINDEX_LINKAGE CXType clang_getCursorType(CXCursor C); 2520208600Srdivacky 2521208600Srdivacky/** 2522234353Sdim * \brief Retrieve the underlying type of a typedef declaration. 2523234353Sdim * 2524234353Sdim * If the cursor does not reference a typedef declaration, an invalid type is 2525234353Sdim * returned. 2526234353Sdim */ 2527234353SdimCINDEX_LINKAGE CXType clang_getTypedefDeclUnderlyingType(CXCursor C); 2528234353Sdim 2529234353Sdim/** 2530234353Sdim * \brief Retrieve the integer type of an enum declaration. 2531234353Sdim * 2532234353Sdim * If the cursor does not reference an enum declaration, an invalid type is 2533234353Sdim * returned. 2534234353Sdim */ 2535234353SdimCINDEX_LINKAGE CXType clang_getEnumDeclIntegerType(CXCursor C); 2536234353Sdim 2537234353Sdim/** 2538234353Sdim * \brief Retrieve the integer value of an enum constant declaration as a signed 2539234353Sdim * long long. 2540234353Sdim * 2541234353Sdim * If the cursor does not reference an enum constant declaration, LLONG_MIN is returned. 2542234353Sdim * Since this is also potentially a valid constant value, the kind of the cursor 2543234353Sdim * must be verified before calling this function. 2544234353Sdim */ 2545234353SdimCINDEX_LINKAGE long long clang_getEnumConstantDeclValue(CXCursor C); 2546234353Sdim 2547234353Sdim/** 2548234353Sdim * \brief Retrieve the integer value of an enum constant declaration as an unsigned 2549234353Sdim * long long. 2550234353Sdim * 2551234353Sdim * If the cursor does not reference an enum constant declaration, ULLONG_MAX is returned. 2552234353Sdim * Since this is also potentially a valid constant value, the kind of the cursor 2553234353Sdim * must be verified before calling this function. 2554234353Sdim */ 2555234353SdimCINDEX_LINKAGE unsigned long long clang_getEnumConstantDeclUnsignedValue(CXCursor C); 2556234353Sdim 2557234353Sdim/** 2558234353Sdim * \brief Retrieve the number of non-variadic arguments associated with a given 2559234353Sdim * cursor. 2560234353Sdim * 2561234353Sdim * If a cursor that is not a function or method is passed in, -1 is returned. 2562234353Sdim */ 2563234353SdimCINDEX_LINKAGE int clang_Cursor_getNumArguments(CXCursor C); 2564234353Sdim 2565234353Sdim/** 2566234353Sdim * \brief Retrieve the argument cursor of a function or method. 2567234353Sdim * 2568234353Sdim * If a cursor that is not a function or method is passed in or the index 2569234353Sdim * exceeds the number of arguments, an invalid cursor is returned. 2570234353Sdim */ 2571234353SdimCINDEX_LINKAGE CXCursor clang_Cursor_getArgument(CXCursor C, unsigned i); 2572234353Sdim 2573234353Sdim/** 2574208600Srdivacky * \determine Determine whether two CXTypes represent the same type. 2575208600Srdivacky * 2576208600Srdivacky * \returns non-zero if the CXTypes represent the same type and 2577208600Srdivacky zero otherwise. 2578208600Srdivacky */ 2579208600SrdivackyCINDEX_LINKAGE unsigned clang_equalTypes(CXType A, CXType B); 2580208600Srdivacky 2581208600Srdivacky/** 2582208600Srdivacky * \brief Return the canonical type for a CXType. 2583208600Srdivacky * 2584208600Srdivacky * Clang's type system explicitly models typedefs and all the ways 2585208600Srdivacky * a specific type can be represented. The canonical type is the underlying 2586208600Srdivacky * type with all the "sugar" removed. For example, if 'T' is a typedef 2587208600Srdivacky * for 'int', the canonical type for 'T' would be 'int'. 2588208600Srdivacky */ 2589208600SrdivackyCINDEX_LINKAGE CXType clang_getCanonicalType(CXType T); 2590208600Srdivacky 2591208600Srdivacky/** 2592218893Sdim * \determine Determine whether a CXType has the "const" qualifier set, 2593218893Sdim * without looking through typedefs that may have added "const" at a different level. 2594218893Sdim */ 2595218893SdimCINDEX_LINKAGE unsigned clang_isConstQualifiedType(CXType T); 2596218893Sdim 2597218893Sdim/** 2598218893Sdim * \determine Determine whether a CXType has the "volatile" qualifier set, 2599218893Sdim * without looking through typedefs that may have added "volatile" at a different level. 2600218893Sdim */ 2601218893SdimCINDEX_LINKAGE unsigned clang_isVolatileQualifiedType(CXType T); 2602218893Sdim 2603218893Sdim/** 2604218893Sdim * \determine Determine whether a CXType has the "restrict" qualifier set, 2605218893Sdim * without looking through typedefs that may have added "restrict" at a different level. 2606218893Sdim */ 2607218893SdimCINDEX_LINKAGE unsigned clang_isRestrictQualifiedType(CXType T); 2608218893Sdim 2609218893Sdim/** 2610208600Srdivacky * \brief For pointer types, returns the type of the pointee. 2611208600Srdivacky * 2612208600Srdivacky */ 2613208600SrdivackyCINDEX_LINKAGE CXType clang_getPointeeType(CXType T); 2614208600Srdivacky 2615208600Srdivacky/** 2616208600Srdivacky * \brief Return the cursor for the declaration of the given type. 2617208600Srdivacky */ 2618208600SrdivackyCINDEX_LINKAGE CXCursor clang_getTypeDeclaration(CXType T); 2619208600Srdivacky 2620218893Sdim/** 2621218893Sdim * Returns the Objective-C type encoding for the specified declaration. 2622218893Sdim */ 2623218893SdimCINDEX_LINKAGE CXString clang_getDeclObjCTypeEncoding(CXCursor C); 2624208600Srdivacky 2625208600Srdivacky/** 2626208600Srdivacky * \brief Retrieve the spelling of a given CXTypeKind. 2627208600Srdivacky */ 2628208600SrdivackyCINDEX_LINKAGE CXString clang_getTypeKindSpelling(enum CXTypeKind K); 2629208600Srdivacky 2630208600Srdivacky/** 2631234353Sdim * \brief Retrieve the calling convention associated with a function type. 2632234353Sdim * 2633234353Sdim * If a non-function type is passed in, CXCallingConv_Invalid is returned. 2634234353Sdim */ 2635234353SdimCINDEX_LINKAGE enum CXCallingConv clang_getFunctionTypeCallingConv(CXType T); 2636234353Sdim 2637234353Sdim/** 2638210299Sed * \brief Retrieve the result type associated with a function type. 2639234353Sdim * 2640234353Sdim * If a non-function type is passed in, an invalid type is returned. 2641210299Sed */ 2642210299SedCINDEX_LINKAGE CXType clang_getResultType(CXType T); 2643210299Sed 2644210299Sed/** 2645234353Sdim * \brief Retrieve the number of non-variadic arguments associated with a function type. 2646234353Sdim * 2647234353Sdim * If a non-function type is passed in, -1 is returned. 2648210299Sed */ 2649234353SdimCINDEX_LINKAGE int clang_getNumArgTypes(CXType T); 2650234353Sdim 2651234353Sdim/** 2652234353Sdim * \brief Retrieve the type of an argument of a function type. 2653234353Sdim * 2654234353Sdim * If a non-function type is passed in or the function does not have enough parameters, 2655234353Sdim * an invalid type is returned. 2656234353Sdim */ 2657234353SdimCINDEX_LINKAGE CXType clang_getArgType(CXType T, unsigned i); 2658234353Sdim 2659234353Sdim/** 2660234353Sdim * \brief Return 1 if the CXType is a variadic function type, and 0 otherwise. 2661234353Sdim * 2662234353Sdim */ 2663234353SdimCINDEX_LINKAGE unsigned clang_isFunctionTypeVariadic(CXType T); 2664234353Sdim 2665234353Sdim/** 2666234353Sdim * \brief Retrieve the result type associated with a given cursor. 2667234353Sdim * 2668234353Sdim * This only returns a valid type if the cursor refers to a function or method. 2669234353Sdim */ 2670210299SedCINDEX_LINKAGE CXType clang_getCursorResultType(CXCursor C); 2671210299Sed 2672210299Sed/** 2673212904Sdim * \brief Return 1 if the CXType is a POD (plain old data) type, and 0 2674212904Sdim * otherwise. 2675212904Sdim */ 2676212904SdimCINDEX_LINKAGE unsigned clang_isPODType(CXType T); 2677212904Sdim 2678212904Sdim/** 2679234353Sdim * \brief Return the element type of an array, complex, or vector type. 2680234353Sdim * 2681234353Sdim * If a type is passed in that is not an array, complex, or vector type, 2682234353Sdim * an invalid type is returned. 2683234353Sdim */ 2684234353SdimCINDEX_LINKAGE CXType clang_getElementType(CXType T); 2685234353Sdim 2686234353Sdim/** 2687234353Sdim * \brief Return the number of elements of an array or vector type. 2688234353Sdim * 2689234353Sdim * If a type is passed in that is not an array or vector type, 2690234353Sdim * -1 is returned. 2691234353Sdim */ 2692234353SdimCINDEX_LINKAGE long long clang_getNumElements(CXType T); 2693234353Sdim 2694234353Sdim/** 2695226633Sdim * \brief Return the element type of an array type. 2696226633Sdim * 2697226633Sdim * If a non-array type is passed in, an invalid type is returned. 2698226633Sdim */ 2699226633SdimCINDEX_LINKAGE CXType clang_getArrayElementType(CXType T); 2700226633Sdim 2701226633Sdim/** 2702226633Sdim * \brief Return the the array size of a constant array. 2703226633Sdim * 2704226633Sdim * If a non-array type is passed in, -1 is returned. 2705226633Sdim */ 2706226633SdimCINDEX_LINKAGE long long clang_getArraySize(CXType T); 2707226633Sdim 2708226633Sdim/** 2709212904Sdim * \brief Returns 1 if the base class specified by the cursor with kind 2710212904Sdim * CX_CXXBaseSpecifier is virtual. 2711212904Sdim */ 2712212904SdimCINDEX_LINKAGE unsigned clang_isVirtualBase(CXCursor); 2713212904Sdim 2714212904Sdim/** 2715212904Sdim * \brief Represents the C++ access control level to a base class for a 2716212904Sdim * cursor with kind CX_CXXBaseSpecifier. 2717212904Sdim */ 2718212904Sdimenum CX_CXXAccessSpecifier { 2719212904Sdim CX_CXXInvalidAccessSpecifier, 2720212904Sdim CX_CXXPublic, 2721212904Sdim CX_CXXProtected, 2722212904Sdim CX_CXXPrivate 2723212904Sdim}; 2724212904Sdim 2725212904Sdim/** 2726212904Sdim * \brief Returns the access control level for the C++ base specifier 2727226633Sdim * represented by a cursor with kind CXCursor_CXXBaseSpecifier or 2728226633Sdim * CXCursor_AccessSpecifier. 2729212904Sdim */ 2730212904SdimCINDEX_LINKAGE enum CX_CXXAccessSpecifier clang_getCXXAccessSpecifier(CXCursor); 2731212904Sdim 2732212904Sdim/** 2733218893Sdim * \brief Determine the number of overloaded declarations referenced by a 2734218893Sdim * \c CXCursor_OverloadedDeclRef cursor. 2735218893Sdim * 2736218893Sdim * \param cursor The cursor whose overloaded declarations are being queried. 2737218893Sdim * 2738218893Sdim * \returns The number of overloaded declarations referenced by \c cursor. If it 2739218893Sdim * is not a \c CXCursor_OverloadedDeclRef cursor, returns 0. 2740218893Sdim */ 2741218893SdimCINDEX_LINKAGE unsigned clang_getNumOverloadedDecls(CXCursor cursor); 2742218893Sdim 2743218893Sdim/** 2744218893Sdim * \brief Retrieve a cursor for one of the overloaded declarations referenced 2745218893Sdim * by a \c CXCursor_OverloadedDeclRef cursor. 2746218893Sdim * 2747218893Sdim * \param cursor The cursor whose overloaded declarations are being queried. 2748218893Sdim * 2749218893Sdim * \param index The zero-based index into the set of overloaded declarations in 2750218893Sdim * the cursor. 2751218893Sdim * 2752218893Sdim * \returns A cursor representing the declaration referenced by the given 2753218893Sdim * \c cursor at the specified \c index. If the cursor does not have an 2754218893Sdim * associated set of overloaded declarations, or if the index is out of bounds, 2755218893Sdim * returns \c clang_getNullCursor(); 2756218893Sdim */ 2757218893SdimCINDEX_LINKAGE CXCursor clang_getOverloadedDecl(CXCursor cursor, 2758218893Sdim unsigned index); 2759218893Sdim 2760218893Sdim/** 2761208600Srdivacky * @} 2762208600Srdivacky */ 2763212904Sdim 2764212904Sdim/** 2765212904Sdim * \defgroup CINDEX_ATTRIBUTES Information for attributes 2766212904Sdim * 2767212904Sdim * @{ 2768212904Sdim */ 2769208600Srdivacky 2770212904Sdim 2771208600Srdivacky/** 2772212904Sdim * \brief For cursors representing an iboutletcollection attribute, 2773212904Sdim * this function returns the collection element type. 2774212904Sdim * 2775212904Sdim */ 2776212904SdimCINDEX_LINKAGE CXType clang_getIBOutletCollectionType(CXCursor); 2777212904Sdim 2778212904Sdim/** 2779212904Sdim * @} 2780212904Sdim */ 2781212904Sdim 2782212904Sdim/** 2783202879Srdivacky * \defgroup CINDEX_CURSOR_TRAVERSAL Traversing the AST with cursors 2784202879Srdivacky * 2785202879Srdivacky * These routines provide the ability to traverse the abstract syntax tree 2786202879Srdivacky * using cursors. 2787202879Srdivacky * 2788202879Srdivacky * @{ 2789202879Srdivacky */ 2790203955Srdivacky 2791202879Srdivacky/** 2792202879Srdivacky * \brief Describes how the traversal of the children of a particular 2793202879Srdivacky * cursor should proceed after visiting a particular child cursor. 2794202879Srdivacky * 2795202879Srdivacky * A value of this enumeration type should be returned by each 2796202879Srdivacky * \c CXCursorVisitor to indicate how clang_visitChildren() proceed. 2797202879Srdivacky */ 2798202879Srdivackyenum CXChildVisitResult { 2799202879Srdivacky /** 2800203955Srdivacky * \brief Terminates the cursor traversal. 2801202879Srdivacky */ 2802202879Srdivacky CXChildVisit_Break, 2803203955Srdivacky /** 2804202879Srdivacky * \brief Continues the cursor traversal with the next sibling of 2805202879Srdivacky * the cursor just visited, without visiting its children. 2806202879Srdivacky */ 2807202879Srdivacky CXChildVisit_Continue, 2808202879Srdivacky /** 2809202879Srdivacky * \brief Recursively traverse the children of this cursor, using 2810202879Srdivacky * the same visitor and client data. 2811202879Srdivacky */ 2812202879Srdivacky CXChildVisit_Recurse 2813202879Srdivacky}; 2814202879Srdivacky 2815202879Srdivacky/** 2816202879Srdivacky * \brief Visitor invoked for each cursor found by a traversal. 2817202879Srdivacky * 2818202879Srdivacky * This visitor function will be invoked for each cursor found by 2819202879Srdivacky * clang_visitCursorChildren(). Its first argument is the cursor being 2820202879Srdivacky * visited, its second argument is the parent visitor for that cursor, 2821202879Srdivacky * and its third argument is the client data provided to 2822202879Srdivacky * clang_visitCursorChildren(). 2823202879Srdivacky * 2824202879Srdivacky * The visitor should return one of the \c CXChildVisitResult values 2825202879Srdivacky * to direct clang_visitCursorChildren(). 2826202879Srdivacky */ 2827203955Srdivackytypedef enum CXChildVisitResult (*CXCursorVisitor)(CXCursor cursor, 2828203955Srdivacky CXCursor parent, 2829202879Srdivacky CXClientData client_data); 2830202879Srdivacky 2831202879Srdivacky/** 2832202879Srdivacky * \brief Visit the children of a particular cursor. 2833202879Srdivacky * 2834202879Srdivacky * This function visits all the direct children of the given cursor, 2835202879Srdivacky * invoking the given \p visitor function with the cursors of each 2836202879Srdivacky * visited child. The traversal may be recursive, if the visitor returns 2837202879Srdivacky * \c CXChildVisit_Recurse. The traversal may also be ended prematurely, if 2838202879Srdivacky * the visitor returns \c CXChildVisit_Break. 2839202879Srdivacky * 2840202879Srdivacky * \param parent the cursor whose child may be visited. All kinds of 2841203955Srdivacky * cursors can be visited, including invalid cursors (which, by 2842202879Srdivacky * definition, have no children). 2843202879Srdivacky * 2844202879Srdivacky * \param visitor the visitor function that will be invoked for each 2845202879Srdivacky * child of \p parent. 2846202879Srdivacky * 2847202879Srdivacky * \param client_data pointer data supplied by the client, which will 2848202879Srdivacky * be passed to the visitor each time it is invoked. 2849202879Srdivacky * 2850202879Srdivacky * \returns a non-zero value if the traversal was terminated 2851202879Srdivacky * prematurely by the visitor returning \c CXChildVisit_Break. 2852202879Srdivacky */ 2853203955SrdivackyCINDEX_LINKAGE unsigned clang_visitChildren(CXCursor parent, 2854202879Srdivacky CXCursorVisitor visitor, 2855202879Srdivacky CXClientData client_data); 2856218893Sdim#ifdef __has_feature 2857218893Sdim# if __has_feature(blocks) 2858218893Sdim/** 2859218893Sdim * \brief Visitor invoked for each cursor found by a traversal. 2860218893Sdim * 2861218893Sdim * This visitor block will be invoked for each cursor found by 2862218893Sdim * clang_visitChildrenWithBlock(). Its first argument is the cursor being 2863218893Sdim * visited, its second argument is the parent visitor for that cursor. 2864218893Sdim * 2865218893Sdim * The visitor should return one of the \c CXChildVisitResult values 2866218893Sdim * to direct clang_visitChildrenWithBlock(). 2867218893Sdim */ 2868218893Sdimtypedef enum CXChildVisitResult 2869218893Sdim (^CXCursorVisitorBlock)(CXCursor cursor, CXCursor parent); 2870203955Srdivacky 2871202879Srdivacky/** 2872218893Sdim * Visits the children of a cursor using the specified block. Behaves 2873218893Sdim * identically to clang_visitChildren() in all other respects. 2874218893Sdim */ 2875218893Sdimunsigned clang_visitChildrenWithBlock(CXCursor parent, 2876218893Sdim CXCursorVisitorBlock block); 2877218893Sdim# endif 2878218893Sdim#endif 2879218893Sdim 2880218893Sdim/** 2881202879Srdivacky * @} 2882202879Srdivacky */ 2883203955Srdivacky 2884202879Srdivacky/** 2885202879Srdivacky * \defgroup CINDEX_CURSOR_XREF Cross-referencing in the AST 2886202879Srdivacky * 2887203955Srdivacky * These routines provide the ability to determine references within and 2888202879Srdivacky * across translation units, by providing the names of the entities referenced 2889202879Srdivacky * by cursors, follow reference cursors to the declarations they reference, 2890202879Srdivacky * and associate declarations with their definitions. 2891202879Srdivacky * 2892202879Srdivacky * @{ 2893202879Srdivacky */ 2894203955Srdivacky 2895202879Srdivacky/** 2896202879Srdivacky * \brief Retrieve a Unified Symbol Resolution (USR) for the entity referenced 2897202879Srdivacky * by the given cursor. 2898202879Srdivacky * 2899202879Srdivacky * A Unified Symbol Resolution (USR) is a string that identifies a particular 2900202879Srdivacky * entity (function, class, variable, etc.) within a program. USRs can be 2901202879Srdivacky * compared across translation units to determine, e.g., when references in 2902202879Srdivacky * one translation refer to an entity defined in another translation unit. 2903202879Srdivacky */ 2904202879SrdivackyCINDEX_LINKAGE CXString clang_getCursorUSR(CXCursor); 2905202879Srdivacky 2906202879Srdivacky/** 2907205219Srdivacky * \brief Construct a USR for a specified Objective-C class. 2908205219Srdivacky */ 2909205219SrdivackyCINDEX_LINKAGE CXString clang_constructUSR_ObjCClass(const char *class_name); 2910205219Srdivacky 2911205219Srdivacky/** 2912205219Srdivacky * \brief Construct a USR for a specified Objective-C category. 2913205219Srdivacky */ 2914205219SrdivackyCINDEX_LINKAGE CXString 2915205219Srdivacky clang_constructUSR_ObjCCategory(const char *class_name, 2916205219Srdivacky const char *category_name); 2917205219Srdivacky 2918205219Srdivacky/** 2919205219Srdivacky * \brief Construct a USR for a specified Objective-C protocol. 2920205219Srdivacky */ 2921205219SrdivackyCINDEX_LINKAGE CXString 2922205219Srdivacky clang_constructUSR_ObjCProtocol(const char *protocol_name); 2923205219Srdivacky 2924205219Srdivacky 2925205219Srdivacky/** 2926205219Srdivacky * \brief Construct a USR for a specified Objective-C instance variable and 2927205219Srdivacky * the USR for its containing class. 2928205219Srdivacky */ 2929205219SrdivackyCINDEX_LINKAGE CXString clang_constructUSR_ObjCIvar(const char *name, 2930205219Srdivacky CXString classUSR); 2931205219Srdivacky 2932205219Srdivacky/** 2933205219Srdivacky * \brief Construct a USR for a specified Objective-C method and 2934205219Srdivacky * the USR for its containing class. 2935205219Srdivacky */ 2936205219SrdivackyCINDEX_LINKAGE CXString clang_constructUSR_ObjCMethod(const char *name, 2937205219Srdivacky unsigned isInstanceMethod, 2938205219Srdivacky CXString classUSR); 2939205219Srdivacky 2940205219Srdivacky/** 2941205219Srdivacky * \brief Construct a USR for a specified Objective-C property and the USR 2942205219Srdivacky * for its containing class. 2943205219Srdivacky */ 2944205219SrdivackyCINDEX_LINKAGE CXString clang_constructUSR_ObjCProperty(const char *property, 2945205219Srdivacky CXString classUSR); 2946205219Srdivacky 2947205219Srdivacky/** 2948202879Srdivacky * \brief Retrieve a name for the entity referenced by this cursor. 2949202879Srdivacky */ 2950199482SrdivackyCINDEX_LINKAGE CXString clang_getCursorSpelling(CXCursor); 2951198398Srdivacky 2952218893Sdim/** 2953234353Sdim * \brief Retrieve a range for a piece that forms the cursors spelling name. 2954234353Sdim * Most of the times there is only one range for the complete spelling but for 2955234353Sdim * objc methods and objc message expressions, there are multiple pieces for each 2956234353Sdim * selector identifier. 2957234353Sdim * 2958234353Sdim * \param pieceIndex the index of the spelling name piece. If this is greater 2959234353Sdim * than the actual number of pieces, it will return a NULL (invalid) range. 2960234353Sdim * 2961234353Sdim * \param options Reserved. 2962234353Sdim */ 2963234353SdimCINDEX_LINKAGE CXSourceRange clang_Cursor_getSpellingNameRange(CXCursor, 2964234353Sdim unsigned pieceIndex, 2965234353Sdim unsigned options); 2966234353Sdim 2967234353Sdim/** 2968218893Sdim * \brief Retrieve the display name for the entity referenced by this cursor. 2969218893Sdim * 2970218893Sdim * The display name contains extra information that helps identify the cursor, 2971218893Sdim * such as the parameters of a function or template or the arguments of a 2972218893Sdim * class template specialization. 2973218893Sdim */ 2974218893SdimCINDEX_LINKAGE CXString clang_getCursorDisplayName(CXCursor); 2975218893Sdim 2976202879Srdivacky/** \brief For a cursor that is a reference, retrieve a cursor representing the 2977202879Srdivacky * entity that it references. 2978202879Srdivacky * 2979202879Srdivacky * Reference cursors refer to other entities in the AST. For example, an 2980202879Srdivacky * Objective-C superclass reference cursor refers to an Objective-C class. 2981203955Srdivacky * This function produces the cursor for the Objective-C class from the 2982202879Srdivacky * cursor for the superclass reference. If the input cursor is a declaration or 2983202879Srdivacky * definition, it returns that declaration or definition unchanged. 2984203955Srdivacky * Otherwise, returns the NULL cursor. 2985202879Srdivacky */ 2986202879SrdivackyCINDEX_LINKAGE CXCursor clang_getCursorReferenced(CXCursor); 2987202879Srdivacky 2988203955Srdivacky/** 2989202879Srdivacky * \brief For a cursor that is either a reference to or a declaration 2990202879Srdivacky * of some entity, retrieve a cursor that describes the definition of 2991202879Srdivacky * that entity. 2992202879Srdivacky * 2993202879Srdivacky * Some entities can be declared multiple times within a translation 2994202879Srdivacky * unit, but only one of those declarations can also be a 2995202879Srdivacky * definition. For example, given: 2996202879Srdivacky * 2997202879Srdivacky * \code 2998202879Srdivacky * int f(int, int); 2999202879Srdivacky * int g(int x, int y) { return f(x, y); } 3000202879Srdivacky * int f(int a, int b) { return a + b; } 3001202879Srdivacky * int f(int, int); 3002202879Srdivacky * \endcode 3003202879Srdivacky * 3004202879Srdivacky * there are three declarations of the function "f", but only the 3005202879Srdivacky * second one is a definition. The clang_getCursorDefinition() 3006202879Srdivacky * function will take any cursor pointing to a declaration of "f" 3007202879Srdivacky * (the first or fourth lines of the example) or a cursor referenced 3008202879Srdivacky * that uses "f" (the call to "f' inside "g") and will return a 3009202879Srdivacky * declaration cursor pointing to the definition (the second "f" 3010202879Srdivacky * declaration). 3011202879Srdivacky * 3012202879Srdivacky * If given a cursor for which there is no corresponding definition, 3013202879Srdivacky * e.g., because there is no definition of that entity within this 3014202879Srdivacky * translation unit, returns a NULL cursor. 3015202879Srdivacky */ 3016202879SrdivackyCINDEX_LINKAGE CXCursor clang_getCursorDefinition(CXCursor); 3017202879Srdivacky 3018203955Srdivacky/** 3019202879Srdivacky * \brief Determine whether the declaration pointed to by this cursor 3020202879Srdivacky * is also a definition of that entity. 3021202879Srdivacky */ 3022202879SrdivackyCINDEX_LINKAGE unsigned clang_isCursorDefinition(CXCursor); 3023202879Srdivacky 3024202879Srdivacky/** 3025218893Sdim * \brief Retrieve the canonical cursor corresponding to the given cursor. 3026218893Sdim * 3027218893Sdim * In the C family of languages, many kinds of entities can be declared several 3028218893Sdim * times within a single translation unit. For example, a structure type can 3029218893Sdim * be forward-declared (possibly multiple times) and later defined: 3030218893Sdim * 3031218893Sdim * \code 3032218893Sdim * struct X; 3033218893Sdim * struct X; 3034218893Sdim * struct X { 3035218893Sdim * int member; 3036218893Sdim * }; 3037218893Sdim * \endcode 3038218893Sdim * 3039218893Sdim * The declarations and the definition of \c X are represented by three 3040218893Sdim * different cursors, all of which are declarations of the same underlying 3041218893Sdim * entity. One of these cursor is considered the "canonical" cursor, which 3042218893Sdim * is effectively the representative for the underlying entity. One can 3043218893Sdim * determine if two cursors are declarations of the same underlying entity by 3044218893Sdim * comparing their canonical cursors. 3045218893Sdim * 3046218893Sdim * \returns The canonical cursor for the entity referred to by the given cursor. 3047218893Sdim */ 3048218893SdimCINDEX_LINKAGE CXCursor clang_getCanonicalCursor(CXCursor); 3049218893Sdim 3050234353Sdim 3051218893Sdim/** 3052234353Sdim * \brief If the cursor points to a selector identifier in a objc method or 3053234353Sdim * message expression, this returns the selector index. 3054234353Sdim * 3055234353Sdim * After getting a cursor with \see clang_getCursor, this can be called to 3056234353Sdim * determine if the location points to a selector identifier. 3057234353Sdim * 3058234353Sdim * \returns The selector index if the cursor is an objc method or message 3059234353Sdim * expression and the cursor is pointing to a selector identifier, or -1 3060234353Sdim * otherwise. 3061234353Sdim */ 3062234353SdimCINDEX_LINKAGE int clang_Cursor_getObjCSelectorIndex(CXCursor); 3063234353Sdim 3064234353Sdim/** 3065202879Srdivacky * @} 3066202879Srdivacky */ 3067203955Srdivacky 3068203955Srdivacky/** 3069208600Srdivacky * \defgroup CINDEX_CPP C++ AST introspection 3070208600Srdivacky * 3071208600Srdivacky * The routines in this group provide access information in the ASTs specific 3072208600Srdivacky * to C++ language features. 3073208600Srdivacky * 3074208600Srdivacky * @{ 3075208600Srdivacky */ 3076208600Srdivacky 3077208600Srdivacky/** 3078212904Sdim * \brief Determine if a C++ member function or member function template is 3079212904Sdim * declared 'static'. 3080208600Srdivacky */ 3081208600SrdivackyCINDEX_LINKAGE unsigned clang_CXXMethod_isStatic(CXCursor C); 3082208600Srdivacky 3083208600Srdivacky/** 3084223017Sdim * \brief Determine if a C++ member function or member function template is 3085223017Sdim * explicitly declared 'virtual' or if it overrides a virtual method from 3086223017Sdim * one of the base classes. 3087223017Sdim */ 3088223017SdimCINDEX_LINKAGE unsigned clang_CXXMethod_isVirtual(CXCursor C); 3089223017Sdim 3090223017Sdim/** 3091212904Sdim * \brief Given a cursor that represents a template, determine 3092212904Sdim * the cursor kind of the specializations would be generated by instantiating 3093212904Sdim * the template. 3094212904Sdim * 3095212904Sdim * This routine can be used to determine what flavor of function template, 3096212904Sdim * class template, or class template partial specialization is stored in the 3097212904Sdim * cursor. For example, it can describe whether a class template cursor is 3098212904Sdim * declared with "struct", "class" or "union". 3099212904Sdim * 3100212904Sdim * \param C The cursor to query. This cursor should represent a template 3101212904Sdim * declaration. 3102212904Sdim * 3103212904Sdim * \returns The cursor kind of the specializations that would be generated 3104212904Sdim * by instantiating the template \p C. If \p C is not a template, returns 3105212904Sdim * \c CXCursor_NoDeclFound. 3106212904Sdim */ 3107212904SdimCINDEX_LINKAGE enum CXCursorKind clang_getTemplateCursorKind(CXCursor C); 3108212904Sdim 3109212904Sdim/** 3110212904Sdim * \brief Given a cursor that may represent a specialization or instantiation 3111212904Sdim * of a template, retrieve the cursor that represents the template that it 3112212904Sdim * specializes or from which it was instantiated. 3113212904Sdim * 3114212904Sdim * This routine determines the template involved both for explicit 3115212904Sdim * specializations of templates and for implicit instantiations of the template, 3116212904Sdim * both of which are referred to as "specializations". For a class template 3117212904Sdim * specialization (e.g., \c std::vector<bool>), this routine will return 3118212904Sdim * either the primary template (\c std::vector) or, if the specialization was 3119212904Sdim * instantiated from a class template partial specialization, the class template 3120212904Sdim * partial specialization. For a class template partial specialization and a 3121212904Sdim * function template specialization (including instantiations), this 3122212904Sdim * this routine will return the specialized template. 3123212904Sdim * 3124212904Sdim * For members of a class template (e.g., member functions, member classes, or 3125212904Sdim * static data members), returns the specialized or instantiated member. 3126212904Sdim * Although not strictly "templates" in the C++ language, members of class 3127212904Sdim * templates have the same notions of specializations and instantiations that 3128212904Sdim * templates do, so this routine treats them similarly. 3129212904Sdim * 3130212904Sdim * \param C A cursor that may be a specialization of a template or a member 3131212904Sdim * of a template. 3132212904Sdim * 3133212904Sdim * \returns If the given cursor is a specialization or instantiation of a 3134212904Sdim * template or a member thereof, the template or member that it specializes or 3135212904Sdim * from which it was instantiated. Otherwise, returns a NULL cursor. 3136212904Sdim */ 3137212904SdimCINDEX_LINKAGE CXCursor clang_getSpecializedCursorTemplate(CXCursor C); 3138226633Sdim 3139226633Sdim/** 3140226633Sdim * \brief Given a cursor that references something else, return the source range 3141226633Sdim * covering that reference. 3142226633Sdim * 3143226633Sdim * \param C A cursor pointing to a member reference, a declaration reference, or 3144226633Sdim * an operator call. 3145226633Sdim * \param NameFlags A bitset with three independent flags: 3146226633Sdim * CXNameRange_WantQualifier, CXNameRange_WantTemplateArgs, and 3147226633Sdim * CXNameRange_WantSinglePiece. 3148226633Sdim * \param PieceIndex For contiguous names or when passing the flag 3149226633Sdim * CXNameRange_WantSinglePiece, only one piece with index 0 is 3150226633Sdim * available. When the CXNameRange_WantSinglePiece flag is not passed for a 3151226633Sdim * non-contiguous names, this index can be used to retreive the individual 3152226633Sdim * pieces of the name. See also CXNameRange_WantSinglePiece. 3153226633Sdim * 3154226633Sdim * \returns The piece of the name pointed to by the given cursor. If there is no 3155226633Sdim * name, or if the PieceIndex is out-of-range, a null-cursor will be returned. 3156226633Sdim */ 3157226633SdimCINDEX_LINKAGE CXSourceRange clang_getCursorReferenceNameRange(CXCursor C, 3158226633Sdim unsigned NameFlags, 3159226633Sdim unsigned PieceIndex); 3160226633Sdim 3161226633Sdimenum CXNameRefFlags { 3162226633Sdim /** 3163226633Sdim * \brief Include the nested-name-specifier, e.g. Foo:: in x.Foo::y, in the 3164226633Sdim * range. 3165226633Sdim */ 3166226633Sdim CXNameRange_WantQualifier = 0x1, 3167212904Sdim 3168226633Sdim /** 3169226633Sdim * \brief Include the explicit template arguments, e.g. <int> in x.f<int>, in 3170226633Sdim * the range. 3171226633Sdim */ 3172226633Sdim CXNameRange_WantTemplateArgs = 0x2, 3173226633Sdim 3174226633Sdim /** 3175226633Sdim * \brief If the name is non-contiguous, return the full spanning range. 3176226633Sdim * 3177226633Sdim * Non-contiguous names occur in Objective-C when a selector with two or more 3178226633Sdim * parameters is used, or in C++ when using an operator: 3179226633Sdim * \code 3180226633Sdim * [object doSomething:here withValue:there]; // ObjC 3181226633Sdim * return some_vector[1]; // C++ 3182226633Sdim * \endcode 3183226633Sdim */ 3184226633Sdim CXNameRange_WantSinglePiece = 0x4 3185226633Sdim}; 3186226633Sdim 3187212904Sdim/** 3188208600Srdivacky * @} 3189208600Srdivacky */ 3190208600Srdivacky 3191208600Srdivacky/** 3192203955Srdivacky * \defgroup CINDEX_LEX Token extraction and manipulation 3193203955Srdivacky * 3194203955Srdivacky * The routines in this group provide access to the tokens within a 3195203955Srdivacky * translation unit, along with a semantic mapping of those tokens to 3196203955Srdivacky * their corresponding cursors. 3197203955Srdivacky * 3198203955Srdivacky * @{ 3199203955Srdivacky */ 3200203955Srdivacky 3201203955Srdivacky/** 3202203955Srdivacky * \brief Describes a kind of token. 3203203955Srdivacky */ 3204203955Srdivackytypedef enum CXTokenKind { 3205203955Srdivacky /** 3206203955Srdivacky * \brief A token that contains some kind of punctuation. 3207203955Srdivacky */ 3208203955Srdivacky CXToken_Punctuation, 3209205219Srdivacky 3210203955Srdivacky /** 3211203955Srdivacky * \brief A language keyword. 3212203955Srdivacky */ 3213203955Srdivacky CXToken_Keyword, 3214205219Srdivacky 3215203955Srdivacky /** 3216203955Srdivacky * \brief An identifier (that is not a keyword). 3217203955Srdivacky */ 3218203955Srdivacky CXToken_Identifier, 3219205219Srdivacky 3220203955Srdivacky /** 3221203955Srdivacky * \brief A numeric, string, or character literal. 3222203955Srdivacky */ 3223203955Srdivacky CXToken_Literal, 3224205219Srdivacky 3225203955Srdivacky /** 3226203955Srdivacky * \brief A comment. 3227203955Srdivacky */ 3228203955Srdivacky CXToken_Comment 3229203955Srdivacky} CXTokenKind; 3230203955Srdivacky 3231202879Srdivacky/** 3232203955Srdivacky * \brief Describes a single preprocessing token. 3233203955Srdivacky */ 3234203955Srdivackytypedef struct { 3235203955Srdivacky unsigned int_data[4]; 3236203955Srdivacky void *ptr_data; 3237203955Srdivacky} CXToken; 3238203955Srdivacky 3239203955Srdivacky/** 3240203955Srdivacky * \brief Determine the kind of the given token. 3241203955Srdivacky */ 3242203955SrdivackyCINDEX_LINKAGE CXTokenKind clang_getTokenKind(CXToken); 3243205219Srdivacky 3244203955Srdivacky/** 3245203955Srdivacky * \brief Determine the spelling of the given token. 3246203955Srdivacky * 3247203955Srdivacky * The spelling of a token is the textual representation of that token, e.g., 3248203955Srdivacky * the text of an identifier or keyword. 3249203955Srdivacky */ 3250203955SrdivackyCINDEX_LINKAGE CXString clang_getTokenSpelling(CXTranslationUnit, CXToken); 3251205219Srdivacky 3252203955Srdivacky/** 3253203955Srdivacky * \brief Retrieve the source location of the given token. 3254203955Srdivacky */ 3255205219SrdivackyCINDEX_LINKAGE CXSourceLocation clang_getTokenLocation(CXTranslationUnit, 3256203955Srdivacky CXToken); 3257205219Srdivacky 3258203955Srdivacky/** 3259203955Srdivacky * \brief Retrieve a source range that covers the given token. 3260203955Srdivacky */ 3261203955SrdivackyCINDEX_LINKAGE CXSourceRange clang_getTokenExtent(CXTranslationUnit, CXToken); 3262203955Srdivacky 3263203955Srdivacky/** 3264203955Srdivacky * \brief Tokenize the source code described by the given range into raw 3265203955Srdivacky * lexical tokens. 3266203955Srdivacky * 3267203955Srdivacky * \param TU the translation unit whose text is being tokenized. 3268203955Srdivacky * 3269203955Srdivacky * \param Range the source range in which text should be tokenized. All of the 3270203955Srdivacky * tokens produced by tokenization will fall within this source range, 3271203955Srdivacky * 3272203955Srdivacky * \param Tokens this pointer will be set to point to the array of tokens 3273203955Srdivacky * that occur within the given source range. The returned pointer must be 3274203955Srdivacky * freed with clang_disposeTokens() before the translation unit is destroyed. 3275203955Srdivacky * 3276203955Srdivacky * \param NumTokens will be set to the number of tokens in the \c *Tokens 3277203955Srdivacky * array. 3278203955Srdivacky * 3279203955Srdivacky */ 3280203955SrdivackyCINDEX_LINKAGE void clang_tokenize(CXTranslationUnit TU, CXSourceRange Range, 3281203955Srdivacky CXToken **Tokens, unsigned *NumTokens); 3282205219Srdivacky 3283203955Srdivacky/** 3284203955Srdivacky * \brief Annotate the given set of tokens by providing cursors for each token 3285203955Srdivacky * that can be mapped to a specific entity within the abstract syntax tree. 3286203955Srdivacky * 3287203955Srdivacky * This token-annotation routine is equivalent to invoking 3288203955Srdivacky * clang_getCursor() for the source locations of each of the 3289203955Srdivacky * tokens. The cursors provided are filtered, so that only those 3290203955Srdivacky * cursors that have a direct correspondence to the token are 3291203955Srdivacky * accepted. For example, given a function call \c f(x), 3292203955Srdivacky * clang_getCursor() would provide the following cursors: 3293203955Srdivacky * 3294203955Srdivacky * * when the cursor is over the 'f', a DeclRefExpr cursor referring to 'f'. 3295203955Srdivacky * * when the cursor is over the '(' or the ')', a CallExpr referring to 'f'. 3296203955Srdivacky * * when the cursor is over the 'x', a DeclRefExpr cursor referring to 'x'. 3297203955Srdivacky * 3298203955Srdivacky * Only the first and last of these cursors will occur within the 3299203955Srdivacky * annotate, since the tokens "f" and "x' directly refer to a function 3300203955Srdivacky * and a variable, respectively, but the parentheses are just a small 3301203955Srdivacky * part of the full syntax of the function call expression, which is 3302203955Srdivacky * not provided as an annotation. 3303203955Srdivacky * 3304203955Srdivacky * \param TU the translation unit that owns the given tokens. 3305203955Srdivacky * 3306203955Srdivacky * \param Tokens the set of tokens to annotate. 3307203955Srdivacky * 3308203955Srdivacky * \param NumTokens the number of tokens in \p Tokens. 3309203955Srdivacky * 3310203955Srdivacky * \param Cursors an array of \p NumTokens cursors, whose contents will be 3311203955Srdivacky * replaced with the cursors corresponding to each token. 3312203955Srdivacky */ 3313203955SrdivackyCINDEX_LINKAGE void clang_annotateTokens(CXTranslationUnit TU, 3314203955Srdivacky CXToken *Tokens, unsigned NumTokens, 3315203955Srdivacky CXCursor *Cursors); 3316205219Srdivacky 3317203955Srdivacky/** 3318203955Srdivacky * \brief Free the given set of tokens. 3319203955Srdivacky */ 3320205219SrdivackyCINDEX_LINKAGE void clang_disposeTokens(CXTranslationUnit TU, 3321203955Srdivacky CXToken *Tokens, unsigned NumTokens); 3322205219Srdivacky 3323203955Srdivacky/** 3324203955Srdivacky * @} 3325203955Srdivacky */ 3326205219Srdivacky 3327203955Srdivacky/** 3328202879Srdivacky * \defgroup CINDEX_DEBUG Debugging facilities 3329202879Srdivacky * 3330202879Srdivacky * These routines are used for testing and debugging, only, and should not 3331202879Srdivacky * be relied upon. 3332202879Srdivacky * 3333202879Srdivacky * @{ 3334202879Srdivacky */ 3335203955Srdivacky 3336198092Srdivacky/* for debug/testing */ 3337204643SrdivackyCINDEX_LINKAGE CXString clang_getCursorKindSpelling(enum CXCursorKind Kind); 3338203955SrdivackyCINDEX_LINKAGE void clang_getDefinitionSpellingAndExtent(CXCursor, 3339203955Srdivacky const char **startBuf, 3340198092Srdivacky const char **endBuf, 3341198092Srdivacky unsigned *startLine, 3342198092Srdivacky unsigned *startColumn, 3343198092Srdivacky unsigned *endLine, 3344198092Srdivacky unsigned *endColumn); 3345204643SrdivackyCINDEX_LINKAGE void clang_enableStackTraces(void); 3346218893SdimCINDEX_LINKAGE void clang_executeOnThread(void (*fn)(void*), void *user_data, 3347218893Sdim unsigned stack_size); 3348218893Sdim 3349202879Srdivacky/** 3350202879Srdivacky * @} 3351198092Srdivacky */ 3352203955Srdivacky 3353199482Srdivacky/** 3354202879Srdivacky * \defgroup CINDEX_CODE_COMPLET Code completion 3355202879Srdivacky * 3356202879Srdivacky * Code completion involves taking an (incomplete) source file, along with 3357202879Srdivacky * knowledge of where the user is actively editing that file, and suggesting 3358202879Srdivacky * syntactically- and semantically-valid constructs that the user might want to 3359202879Srdivacky * use at that particular point in the source code. These data structures and 3360202879Srdivacky * routines provide support for code completion. 3361202879Srdivacky * 3362202879Srdivacky * @{ 3363202879Srdivacky */ 3364203955Srdivacky 3365202879Srdivacky/** 3366199482Srdivacky * \brief A semantic string that describes a code-completion result. 3367199482Srdivacky * 3368199482Srdivacky * A semantic string that describes the formatting of a code-completion 3369199482Srdivacky * result as a single "template" of text that should be inserted into the 3370199482Srdivacky * source buffer when a particular code-completion result is selected. 3371199482Srdivacky * Each semantic string is made up of some number of "chunks", each of which 3372199482Srdivacky * contains some text along with a description of what that text means, e.g., 3373199482Srdivacky * the name of the entity being referenced, whether the text chunk is part of 3374199482Srdivacky * the template, or whether it is a "placeholder" that the user should replace 3375199482Srdivacky * with actual code,of a specific kind. See \c CXCompletionChunkKind for a 3376203955Srdivacky * description of the different kinds of chunks. 3377199482Srdivacky */ 3378199482Srdivackytypedef void *CXCompletionString; 3379203955Srdivacky 3380199482Srdivacky/** 3381199482Srdivacky * \brief A single result of code completion. 3382199482Srdivacky */ 3383199482Srdivackytypedef struct { 3384199482Srdivacky /** 3385203955Srdivacky * \brief The kind of entity that this completion refers to. 3386199482Srdivacky * 3387203955Srdivacky * The cursor kind will be a macro, keyword, or a declaration (one of the 3388199482Srdivacky * *Decl cursor kinds), describing the entity that the completion is 3389199482Srdivacky * referring to. 3390199482Srdivacky * 3391199482Srdivacky * \todo In the future, we would like to provide a full cursor, to allow 3392199482Srdivacky * the client to extract additional information from declaration. 3393199482Srdivacky */ 3394199482Srdivacky enum CXCursorKind CursorKind; 3395203955Srdivacky 3396203955Srdivacky /** 3397199482Srdivacky * \brief The code-completion string that describes how to insert this 3398199482Srdivacky * code-completion result into the editing buffer. 3399199482Srdivacky */ 3400199482Srdivacky CXCompletionString CompletionString; 3401199482Srdivacky} CXCompletionResult; 3402199482Srdivacky 3403199482Srdivacky/** 3404199482Srdivacky * \brief Describes a single piece of text within a code-completion string. 3405199482Srdivacky * 3406203955Srdivacky * Each "chunk" within a code-completion string (\c CXCompletionString) is 3407203955Srdivacky * either a piece of text with a specific "kind" that describes how that text 3408199482Srdivacky * should be interpreted by the client or is another completion string. 3409199482Srdivacky */ 3410199482Srdivackyenum CXCompletionChunkKind { 3411199482Srdivacky /** 3412199482Srdivacky * \brief A code-completion string that describes "optional" text that 3413199482Srdivacky * could be a part of the template (but is not required). 3414199482Srdivacky * 3415199482Srdivacky * The Optional chunk is the only kind of chunk that has a code-completion 3416203955Srdivacky * string for its representation, which is accessible via 3417199482Srdivacky * \c clang_getCompletionChunkCompletionString(). The code-completion string 3418199482Srdivacky * describes an additional part of the template that is completely optional. 3419199482Srdivacky * For example, optional chunks can be used to describe the placeholders for 3420199482Srdivacky * arguments that match up with defaulted function parameters, e.g. given: 3421199482Srdivacky * 3422199482Srdivacky * \code 3423199482Srdivacky * void f(int x, float y = 3.14, double z = 2.71828); 3424199482Srdivacky * \endcode 3425199482Srdivacky * 3426199482Srdivacky * The code-completion string for this function would contain: 3427199482Srdivacky * - a TypedText chunk for "f". 3428199482Srdivacky * - a LeftParen chunk for "(". 3429199482Srdivacky * - a Placeholder chunk for "int x" 3430199482Srdivacky * - an Optional chunk containing the remaining defaulted arguments, e.g., 3431199482Srdivacky * - a Comma chunk for "," 3432204643Srdivacky * - a Placeholder chunk for "float y" 3433199482Srdivacky * - an Optional chunk containing the last defaulted argument: 3434199482Srdivacky * - a Comma chunk for "," 3435199482Srdivacky * - a Placeholder chunk for "double z" 3436199482Srdivacky * - a RightParen chunk for ")" 3437199482Srdivacky * 3438204643Srdivacky * There are many ways to handle Optional chunks. Two simple approaches are: 3439199482Srdivacky * - Completely ignore optional chunks, in which case the template for the 3440199482Srdivacky * function "f" would only include the first parameter ("int x"). 3441199482Srdivacky * - Fully expand all optional chunks, in which case the template for the 3442199482Srdivacky * function "f" would have all of the parameters. 3443199482Srdivacky */ 3444199482Srdivacky CXCompletionChunk_Optional, 3445199482Srdivacky /** 3446199482Srdivacky * \brief Text that a user would be expected to type to get this 3447203955Srdivacky * code-completion result. 3448199482Srdivacky * 3449203955Srdivacky * There will be exactly one "typed text" chunk in a semantic string, which 3450203955Srdivacky * will typically provide the spelling of a keyword or the name of a 3451199482Srdivacky * declaration that could be used at the current code point. Clients are 3452199482Srdivacky * expected to filter the code-completion results based on the text in this 3453199482Srdivacky * chunk. 3454199482Srdivacky */ 3455199482Srdivacky CXCompletionChunk_TypedText, 3456199482Srdivacky /** 3457199482Srdivacky * \brief Text that should be inserted as part of a code-completion result. 3458199482Srdivacky * 3459199482Srdivacky * A "text" chunk represents text that is part of the template to be 3460199482Srdivacky * inserted into user code should this particular code-completion result 3461199482Srdivacky * be selected. 3462199482Srdivacky */ 3463199482Srdivacky CXCompletionChunk_Text, 3464199482Srdivacky /** 3465199482Srdivacky * \brief Placeholder text that should be replaced by the user. 3466199482Srdivacky * 3467199482Srdivacky * A "placeholder" chunk marks a place where the user should insert text 3468199482Srdivacky * into the code-completion template. For example, placeholders might mark 3469199482Srdivacky * the function parameters for a function declaration, to indicate that the 3470199482Srdivacky * user should provide arguments for each of those parameters. The actual 3471199482Srdivacky * text in a placeholder is a suggestion for the text to display before 3472199482Srdivacky * the user replaces the placeholder with real code. 3473199482Srdivacky */ 3474199482Srdivacky CXCompletionChunk_Placeholder, 3475199482Srdivacky /** 3476199482Srdivacky * \brief Informative text that should be displayed but never inserted as 3477199482Srdivacky * part of the template. 3478203955Srdivacky * 3479199482Srdivacky * An "informative" chunk contains annotations that can be displayed to 3480199482Srdivacky * help the user decide whether a particular code-completion result is the 3481199482Srdivacky * right option, but which is not part of the actual template to be inserted 3482199482Srdivacky * by code completion. 3483199482Srdivacky */ 3484199482Srdivacky CXCompletionChunk_Informative, 3485199482Srdivacky /** 3486199482Srdivacky * \brief Text that describes the current parameter when code-completion is 3487199482Srdivacky * referring to function call, message send, or template specialization. 3488199482Srdivacky * 3489199482Srdivacky * A "current parameter" chunk occurs when code-completion is providing 3490199482Srdivacky * information about a parameter corresponding to the argument at the 3491199482Srdivacky * code-completion point. For example, given a function 3492199482Srdivacky * 3493199482Srdivacky * \code 3494199482Srdivacky * int add(int x, int y); 3495199482Srdivacky * \endcode 3496199482Srdivacky * 3497199482Srdivacky * and the source code \c add(, where the code-completion point is after the 3498199482Srdivacky * "(", the code-completion string will contain a "current parameter" chunk 3499199482Srdivacky * for "int x", indicating that the current argument will initialize that 3500199482Srdivacky * parameter. After typing further, to \c add(17, (where the code-completion 3501203955Srdivacky * point is after the ","), the code-completion string will contain a 3502199482Srdivacky * "current paremeter" chunk to "int y". 3503199482Srdivacky */ 3504199482Srdivacky CXCompletionChunk_CurrentParameter, 3505199482Srdivacky /** 3506199482Srdivacky * \brief A left parenthesis ('('), used to initiate a function call or 3507199482Srdivacky * signal the beginning of a function parameter list. 3508199482Srdivacky */ 3509199482Srdivacky CXCompletionChunk_LeftParen, 3510199482Srdivacky /** 3511199482Srdivacky * \brief A right parenthesis (')'), used to finish a function call or 3512199482Srdivacky * signal the end of a function parameter list. 3513199482Srdivacky */ 3514199482Srdivacky CXCompletionChunk_RightParen, 3515199482Srdivacky /** 3516199482Srdivacky * \brief A left bracket ('['). 3517199482Srdivacky */ 3518199482Srdivacky CXCompletionChunk_LeftBracket, 3519199482Srdivacky /** 3520199482Srdivacky * \brief A right bracket (']'). 3521199482Srdivacky */ 3522199482Srdivacky CXCompletionChunk_RightBracket, 3523199482Srdivacky /** 3524199482Srdivacky * \brief A left brace ('{'). 3525199482Srdivacky */ 3526199482Srdivacky CXCompletionChunk_LeftBrace, 3527199482Srdivacky /** 3528199482Srdivacky * \brief A right brace ('}'). 3529199482Srdivacky */ 3530199482Srdivacky CXCompletionChunk_RightBrace, 3531199482Srdivacky /** 3532199482Srdivacky * \brief A left angle bracket ('<'). 3533199482Srdivacky */ 3534199482Srdivacky CXCompletionChunk_LeftAngle, 3535199482Srdivacky /** 3536199482Srdivacky * \brief A right angle bracket ('>'). 3537199482Srdivacky */ 3538199482Srdivacky CXCompletionChunk_RightAngle, 3539199482Srdivacky /** 3540199482Srdivacky * \brief A comma separator (','). 3541199482Srdivacky */ 3542201361Srdivacky CXCompletionChunk_Comma, 3543201361Srdivacky /** 3544203955Srdivacky * \brief Text that specifies the result type of a given result. 3545201361Srdivacky * 3546201361Srdivacky * This special kind of informative chunk is not meant to be inserted into 3547203955Srdivacky * the text buffer. Rather, it is meant to illustrate the type that an 3548201361Srdivacky * expression using the given completion string would have. 3549201361Srdivacky */ 3550202379Srdivacky CXCompletionChunk_ResultType, 3551202379Srdivacky /** 3552202379Srdivacky * \brief A colon (':'). 3553202379Srdivacky */ 3554202379Srdivacky CXCompletionChunk_Colon, 3555202379Srdivacky /** 3556202379Srdivacky * \brief A semicolon (';'). 3557202379Srdivacky */ 3558202379Srdivacky CXCompletionChunk_SemiColon, 3559202379Srdivacky /** 3560202379Srdivacky * \brief An '=' sign. 3561202379Srdivacky */ 3562202379Srdivacky CXCompletionChunk_Equal, 3563202379Srdivacky /** 3564202379Srdivacky * Horizontal space (' '). 3565202379Srdivacky */ 3566202379Srdivacky CXCompletionChunk_HorizontalSpace, 3567202379Srdivacky /** 3568202379Srdivacky * Vertical space ('\n'), after which it is generally a good idea to 3569202379Srdivacky * perform indentation. 3570202379Srdivacky */ 3571202379Srdivacky CXCompletionChunk_VerticalSpace 3572199482Srdivacky}; 3573203955Srdivacky 3574199482Srdivacky/** 3575199482Srdivacky * \brief Determine the kind of a particular chunk within a completion string. 3576199482Srdivacky * 3577199482Srdivacky * \param completion_string the completion string to query. 3578199482Srdivacky * 3579199482Srdivacky * \param chunk_number the 0-based index of the chunk in the completion string. 3580199482Srdivacky * 3581199482Srdivacky * \returns the kind of the chunk at the index \c chunk_number. 3582199482Srdivacky */ 3583203955SrdivackyCINDEX_LINKAGE enum CXCompletionChunkKind 3584199482Srdivackyclang_getCompletionChunkKind(CXCompletionString completion_string, 3585199482Srdivacky unsigned chunk_number); 3586203955Srdivacky 3587199482Srdivacky/** 3588203955Srdivacky * \brief Retrieve the text associated with a particular chunk within a 3589199482Srdivacky * completion string. 3590199482Srdivacky * 3591199482Srdivacky * \param completion_string the completion string to query. 3592199482Srdivacky * 3593199482Srdivacky * \param chunk_number the 0-based index of the chunk in the completion string. 3594199482Srdivacky * 3595199482Srdivacky * \returns the text associated with the chunk at index \c chunk_number. 3596199482Srdivacky */ 3597204643SrdivackyCINDEX_LINKAGE CXString 3598199482Srdivackyclang_getCompletionChunkText(CXCompletionString completion_string, 3599199482Srdivacky unsigned chunk_number); 3600199482Srdivacky 3601199482Srdivacky/** 3602203955Srdivacky * \brief Retrieve the completion string associated with a particular chunk 3603199482Srdivacky * within a completion string. 3604199482Srdivacky * 3605199482Srdivacky * \param completion_string the completion string to query. 3606199482Srdivacky * 3607199482Srdivacky * \param chunk_number the 0-based index of the chunk in the completion string. 3608199482Srdivacky * 3609199482Srdivacky * \returns the completion string associated with the chunk at index 3610226633Sdim * \c chunk_number. 3611199482Srdivacky */ 3612199482SrdivackyCINDEX_LINKAGE CXCompletionString 3613199482Srdivackyclang_getCompletionChunkCompletionString(CXCompletionString completion_string, 3614199482Srdivacky unsigned chunk_number); 3615203955Srdivacky 3616199482Srdivacky/** 3617199482Srdivacky * \brief Retrieve the number of chunks in the given code-completion string. 3618199482Srdivacky */ 3619199482SrdivackyCINDEX_LINKAGE unsigned 3620199482Srdivackyclang_getNumCompletionChunks(CXCompletionString completion_string); 3621199482Srdivacky 3622199482Srdivacky/** 3623208600Srdivacky * \brief Determine the priority of this code completion. 3624208600Srdivacky * 3625208600Srdivacky * The priority of a code completion indicates how likely it is that this 3626208600Srdivacky * particular completion is the completion that the user will select. The 3627208600Srdivacky * priority is selected by various internal heuristics. 3628208600Srdivacky * 3629208600Srdivacky * \param completion_string The completion string to query. 3630208600Srdivacky * 3631208600Srdivacky * \returns The priority of this completion string. Smaller values indicate 3632208600Srdivacky * higher-priority (more likely) completions. 3633208600Srdivacky */ 3634208600SrdivackyCINDEX_LINKAGE unsigned 3635208600Srdivackyclang_getCompletionPriority(CXCompletionString completion_string); 3636208600Srdivacky 3637208600Srdivacky/** 3638212904Sdim * \brief Determine the availability of the entity that this code-completion 3639212904Sdim * string refers to. 3640212904Sdim * 3641212904Sdim * \param completion_string The completion string to query. 3642212904Sdim * 3643212904Sdim * \returns The availability of the completion string. 3644212904Sdim */ 3645212904SdimCINDEX_LINKAGE enum CXAvailabilityKind 3646212904Sdimclang_getCompletionAvailability(CXCompletionString completion_string); 3647212904Sdim 3648212904Sdim/** 3649226633Sdim * \brief Retrieve the number of annotations associated with the given 3650226633Sdim * completion string. 3651226633Sdim * 3652226633Sdim * \param completion_string the completion string to query. 3653226633Sdim * 3654226633Sdim * \returns the number of annotations associated with the given completion 3655226633Sdim * string. 3656226633Sdim */ 3657226633SdimCINDEX_LINKAGE unsigned 3658226633Sdimclang_getCompletionNumAnnotations(CXCompletionString completion_string); 3659226633Sdim 3660226633Sdim/** 3661226633Sdim * \brief Retrieve the annotation associated with the given completion string. 3662226633Sdim * 3663226633Sdim * \param completion_string the completion string to query. 3664226633Sdim * 3665226633Sdim * \param annotation_number the 0-based index of the annotation of the 3666226633Sdim * completion string. 3667226633Sdim * 3668226633Sdim * \returns annotation string associated with the completion at index 3669226633Sdim * \c annotation_number, or a NULL string if that annotation is not available. 3670226633Sdim */ 3671226633SdimCINDEX_LINKAGE CXString 3672226633Sdimclang_getCompletionAnnotation(CXCompletionString completion_string, 3673226633Sdim unsigned annotation_number); 3674226633Sdim 3675226633Sdim/** 3676234353Sdim * \brief Retrieve the parent context of the given completion string. 3677234353Sdim * 3678234353Sdim * The parent context of a completion string is the semantic parent of 3679234353Sdim * the declaration (if any) that the code completion represents. For example, 3680234353Sdim * a code completion for an Objective-C method would have the method's class 3681234353Sdim * or protocol as its context. 3682234353Sdim * 3683234353Sdim * \param completion_string The code completion string whose parent is 3684234353Sdim * being queried. 3685234353Sdim * 3686234353Sdim * \param kind If non-NULL, will be set to the kind of the parent context, 3687234353Sdim * or CXCursor_NotImplemented if there is no context. 3688234353Sdim * 3689234353Sdim * \param Returns the name of the completion parent, e.g., "NSObject" if 3690234353Sdim * the completion string represents a method in the NSObject class. 3691234353Sdim */ 3692234353SdimCINDEX_LINKAGE CXString 3693234353Sdimclang_getCompletionParent(CXCompletionString completion_string, 3694234353Sdim enum CXCursorKind *kind); 3695234353Sdim/** 3696226633Sdim * \brief Retrieve a completion string for an arbitrary declaration or macro 3697226633Sdim * definition cursor. 3698226633Sdim * 3699226633Sdim * \param cursor The cursor to query. 3700226633Sdim * 3701226633Sdim * \returns A non-context-sensitive completion string for declaration and macro 3702226633Sdim * definition cursors, or NULL for other kinds of cursors. 3703226633Sdim */ 3704226633SdimCINDEX_LINKAGE CXCompletionString 3705226633Sdimclang_getCursorCompletionString(CXCursor cursor); 3706226633Sdim 3707226633Sdim/** 3708201361Srdivacky * \brief Contains the results of code-completion. 3709201361Srdivacky * 3710201361Srdivacky * This data structure contains the results of code completion, as 3711218893Sdim * produced by \c clang_codeCompleteAt(). Its contents must be freed by 3712201361Srdivacky * \c clang_disposeCodeCompleteResults. 3713201361Srdivacky */ 3714201361Srdivackytypedef struct { 3715201361Srdivacky /** 3716201361Srdivacky * \brief The code-completion results. 3717201361Srdivacky */ 3718201361Srdivacky CXCompletionResult *Results; 3719201361Srdivacky 3720201361Srdivacky /** 3721201361Srdivacky * \brief The number of code-completion results stored in the 3722201361Srdivacky * \c Results array. 3723201361Srdivacky */ 3724201361Srdivacky unsigned NumResults; 3725201361Srdivacky} CXCodeCompleteResults; 3726201361Srdivacky 3727201361Srdivacky/** 3728212904Sdim * \brief Flags that can be passed to \c clang_codeCompleteAt() to 3729212904Sdim * modify its behavior. 3730212904Sdim * 3731212904Sdim * The enumerators in this enumeration can be bitwise-OR'd together to 3732212904Sdim * provide multiple options to \c clang_codeCompleteAt(). 3733212904Sdim */ 3734212904Sdimenum CXCodeComplete_Flags { 3735212904Sdim /** 3736212904Sdim * \brief Whether to include macros within the set of code 3737212904Sdim * completions returned. 3738212904Sdim */ 3739212904Sdim CXCodeComplete_IncludeMacros = 0x01, 3740212904Sdim 3741212904Sdim /** 3742212904Sdim * \brief Whether to include code patterns for language constructs 3743212904Sdim * within the set of code completions, e.g., for loops. 3744212904Sdim */ 3745212904Sdim CXCodeComplete_IncludeCodePatterns = 0x02 3746212904Sdim}; 3747212904Sdim 3748212904Sdim/** 3749224145Sdim * \brief Bits that represent the context under which completion is occurring. 3750224145Sdim * 3751224145Sdim * The enumerators in this enumeration may be bitwise-OR'd together if multiple 3752224145Sdim * contexts are occurring simultaneously. 3753224145Sdim */ 3754224145Sdimenum CXCompletionContext { 3755224145Sdim /** 3756224145Sdim * \brief The context for completions is unexposed, as only Clang results 3757224145Sdim * should be included. (This is equivalent to having no context bits set.) 3758224145Sdim */ 3759224145Sdim CXCompletionContext_Unexposed = 0, 3760224145Sdim 3761224145Sdim /** 3762224145Sdim * \brief Completions for any possible type should be included in the results. 3763224145Sdim */ 3764224145Sdim CXCompletionContext_AnyType = 1 << 0, 3765224145Sdim 3766224145Sdim /** 3767224145Sdim * \brief Completions for any possible value (variables, function calls, etc.) 3768224145Sdim * should be included in the results. 3769224145Sdim */ 3770224145Sdim CXCompletionContext_AnyValue = 1 << 1, 3771224145Sdim /** 3772224145Sdim * \brief Completions for values that resolve to an Objective-C object should 3773224145Sdim * be included in the results. 3774224145Sdim */ 3775224145Sdim CXCompletionContext_ObjCObjectValue = 1 << 2, 3776224145Sdim /** 3777224145Sdim * \brief Completions for values that resolve to an Objective-C selector 3778224145Sdim * should be included in the results. 3779224145Sdim */ 3780224145Sdim CXCompletionContext_ObjCSelectorValue = 1 << 3, 3781224145Sdim /** 3782224145Sdim * \brief Completions for values that resolve to a C++ class type should be 3783224145Sdim * included in the results. 3784224145Sdim */ 3785224145Sdim CXCompletionContext_CXXClassTypeValue = 1 << 4, 3786224145Sdim 3787224145Sdim /** 3788224145Sdim * \brief Completions for fields of the member being accessed using the dot 3789224145Sdim * operator should be included in the results. 3790224145Sdim */ 3791224145Sdim CXCompletionContext_DotMemberAccess = 1 << 5, 3792224145Sdim /** 3793224145Sdim * \brief Completions for fields of the member being accessed using the arrow 3794224145Sdim * operator should be included in the results. 3795224145Sdim */ 3796224145Sdim CXCompletionContext_ArrowMemberAccess = 1 << 6, 3797224145Sdim /** 3798224145Sdim * \brief Completions for properties of the Objective-C object being accessed 3799224145Sdim * using the dot operator should be included in the results. 3800224145Sdim */ 3801224145Sdim CXCompletionContext_ObjCPropertyAccess = 1 << 7, 3802224145Sdim 3803224145Sdim /** 3804224145Sdim * \brief Completions for enum tags should be included in the results. 3805224145Sdim */ 3806224145Sdim CXCompletionContext_EnumTag = 1 << 8, 3807224145Sdim /** 3808224145Sdim * \brief Completions for union tags should be included in the results. 3809224145Sdim */ 3810224145Sdim CXCompletionContext_UnionTag = 1 << 9, 3811224145Sdim /** 3812224145Sdim * \brief Completions for struct tags should be included in the results. 3813224145Sdim */ 3814224145Sdim CXCompletionContext_StructTag = 1 << 10, 3815224145Sdim 3816224145Sdim /** 3817224145Sdim * \brief Completions for C++ class names should be included in the results. 3818224145Sdim */ 3819224145Sdim CXCompletionContext_ClassTag = 1 << 11, 3820224145Sdim /** 3821224145Sdim * \brief Completions for C++ namespaces and namespace aliases should be 3822224145Sdim * included in the results. 3823224145Sdim */ 3824224145Sdim CXCompletionContext_Namespace = 1 << 12, 3825224145Sdim /** 3826224145Sdim * \brief Completions for C++ nested name specifiers should be included in 3827224145Sdim * the results. 3828224145Sdim */ 3829224145Sdim CXCompletionContext_NestedNameSpecifier = 1 << 13, 3830224145Sdim 3831224145Sdim /** 3832224145Sdim * \brief Completions for Objective-C interfaces (classes) should be included 3833224145Sdim * in the results. 3834224145Sdim */ 3835224145Sdim CXCompletionContext_ObjCInterface = 1 << 14, 3836224145Sdim /** 3837224145Sdim * \brief Completions for Objective-C protocols should be included in 3838224145Sdim * the results. 3839224145Sdim */ 3840224145Sdim CXCompletionContext_ObjCProtocol = 1 << 15, 3841224145Sdim /** 3842224145Sdim * \brief Completions for Objective-C categories should be included in 3843224145Sdim * the results. 3844224145Sdim */ 3845224145Sdim CXCompletionContext_ObjCCategory = 1 << 16, 3846224145Sdim /** 3847224145Sdim * \brief Completions for Objective-C instance messages should be included 3848224145Sdim * in the results. 3849224145Sdim */ 3850224145Sdim CXCompletionContext_ObjCInstanceMessage = 1 << 17, 3851224145Sdim /** 3852224145Sdim * \brief Completions for Objective-C class messages should be included in 3853224145Sdim * the results. 3854224145Sdim */ 3855224145Sdim CXCompletionContext_ObjCClassMessage = 1 << 18, 3856224145Sdim /** 3857224145Sdim * \brief Completions for Objective-C selector names should be included in 3858224145Sdim * the results. 3859224145Sdim */ 3860224145Sdim CXCompletionContext_ObjCSelectorName = 1 << 19, 3861224145Sdim 3862224145Sdim /** 3863224145Sdim * \brief Completions for preprocessor macro names should be included in 3864224145Sdim * the results. 3865224145Sdim */ 3866224145Sdim CXCompletionContext_MacroName = 1 << 20, 3867224145Sdim 3868224145Sdim /** 3869224145Sdim * \brief Natural language completions should be included in the results. 3870224145Sdim */ 3871224145Sdim CXCompletionContext_NaturalLanguage = 1 << 21, 3872224145Sdim 3873224145Sdim /** 3874224145Sdim * \brief The current context is unknown, so set all contexts. 3875224145Sdim */ 3876224145Sdim CXCompletionContext_Unknown = ((1 << 22) - 1) 3877224145Sdim}; 3878224145Sdim 3879224145Sdim/** 3880212904Sdim * \brief Returns a default set of code-completion options that can be 3881212904Sdim * passed to\c clang_codeCompleteAt(). 3882212904Sdim */ 3883212904SdimCINDEX_LINKAGE unsigned clang_defaultCodeCompleteOptions(void); 3884212904Sdim 3885212904Sdim/** 3886212904Sdim * \brief Perform code completion at a given location in a translation unit. 3887212904Sdim * 3888212904Sdim * This function performs code completion at a particular file, line, and 3889212904Sdim * column within source code, providing results that suggest potential 3890212904Sdim * code snippets based on the context of the completion. The basic model 3891212904Sdim * for code completion is that Clang will parse a complete source file, 3892212904Sdim * performing syntax checking up to the location where code-completion has 3893212904Sdim * been requested. At that point, a special code-completion token is passed 3894212904Sdim * to the parser, which recognizes this token and determines, based on the 3895212904Sdim * current location in the C/Objective-C/C++ grammar and the state of 3896212904Sdim * semantic analysis, what completions to provide. These completions are 3897212904Sdim * returned via a new \c CXCodeCompleteResults structure. 3898212904Sdim * 3899212904Sdim * Code completion itself is meant to be triggered by the client when the 3900212904Sdim * user types punctuation characters or whitespace, at which point the 3901212904Sdim * code-completion location will coincide with the cursor. For example, if \c p 3902212904Sdim * is a pointer, code-completion might be triggered after the "-" and then 3903212904Sdim * after the ">" in \c p->. When the code-completion location is afer the ">", 3904212904Sdim * the completion results will provide, e.g., the members of the struct that 3905212904Sdim * "p" points to. The client is responsible for placing the cursor at the 3906212904Sdim * beginning of the token currently being typed, then filtering the results 3907212904Sdim * based on the contents of the token. For example, when code-completing for 3908212904Sdim * the expression \c p->get, the client should provide the location just after 3909212904Sdim * the ">" (e.g., pointing at the "g") to this code-completion hook. Then, the 3910212904Sdim * client can filter the results based on the current token text ("get"), only 3911212904Sdim * showing those results that start with "get". The intent of this interface 3912212904Sdim * is to separate the relatively high-latency acquisition of code-completion 3913212904Sdim * results from the filtering of results on a per-character basis, which must 3914212904Sdim * have a lower latency. 3915212904Sdim * 3916212904Sdim * \param TU The translation unit in which code-completion should 3917212904Sdim * occur. The source files for this translation unit need not be 3918212904Sdim * completely up-to-date (and the contents of those source files may 3919212904Sdim * be overridden via \p unsaved_files). Cursors referring into the 3920212904Sdim * translation unit may be invalidated by this invocation. 3921212904Sdim * 3922212904Sdim * \param complete_filename The name of the source file where code 3923212904Sdim * completion should be performed. This filename may be any file 3924212904Sdim * included in the translation unit. 3925212904Sdim * 3926212904Sdim * \param complete_line The line at which code-completion should occur. 3927212904Sdim * 3928212904Sdim * \param complete_column The column at which code-completion should occur. 3929212904Sdim * Note that the column should point just after the syntactic construct that 3930212904Sdim * initiated code completion, and not in the middle of a lexical token. 3931212904Sdim * 3932212904Sdim * \param unsaved_files the Tiles that have not yet been saved to disk 3933212904Sdim * but may be required for parsing or code completion, including the 3934212904Sdim * contents of those files. The contents and name of these files (as 3935212904Sdim * specified by CXUnsavedFile) are copied when necessary, so the 3936212904Sdim * client only needs to guarantee their validity until the call to 3937212904Sdim * this function returns. 3938212904Sdim * 3939212904Sdim * \param num_unsaved_files The number of unsaved file entries in \p 3940212904Sdim * unsaved_files. 3941212904Sdim * 3942212904Sdim * \param options Extra options that control the behavior of code 3943212904Sdim * completion, expressed as a bitwise OR of the enumerators of the 3944212904Sdim * CXCodeComplete_Flags enumeration. The 3945212904Sdim * \c clang_defaultCodeCompleteOptions() function returns a default set 3946212904Sdim * of code-completion options. 3947212904Sdim * 3948212904Sdim * \returns If successful, a new \c CXCodeCompleteResults structure 3949212904Sdim * containing code-completion results, which should eventually be 3950212904Sdim * freed with \c clang_disposeCodeCompleteResults(). If code 3951212904Sdim * completion fails, returns NULL. 3952212904Sdim */ 3953212904SdimCINDEX_LINKAGE 3954212904SdimCXCodeCompleteResults *clang_codeCompleteAt(CXTranslationUnit TU, 3955212904Sdim const char *complete_filename, 3956212904Sdim unsigned complete_line, 3957212904Sdim unsigned complete_column, 3958212904Sdim struct CXUnsavedFile *unsaved_files, 3959212904Sdim unsigned num_unsaved_files, 3960212904Sdim unsigned options); 3961212904Sdim 3962212904Sdim/** 3963212904Sdim * \brief Sort the code-completion results in case-insensitive alphabetical 3964212904Sdim * order. 3965212904Sdim * 3966212904Sdim * \param Results The set of results to sort. 3967212904Sdim * \param NumResults The number of results in \p Results. 3968212904Sdim */ 3969212904SdimCINDEX_LINKAGE 3970212904Sdimvoid clang_sortCodeCompletionResults(CXCompletionResult *Results, 3971212904Sdim unsigned NumResults); 3972212904Sdim 3973212904Sdim/** 3974201361Srdivacky * \brief Free the given set of code-completion results. 3975201361Srdivacky */ 3976203955SrdivackyCINDEX_LINKAGE 3977201361Srdivackyvoid clang_disposeCodeCompleteResults(CXCodeCompleteResults *Results); 3978212904Sdim 3979202879Srdivacky/** 3980204643Srdivacky * \brief Determine the number of diagnostics produced prior to the 3981204643Srdivacky * location where code completion was performed. 3982204643Srdivacky */ 3983205219SrdivackyCINDEX_LINKAGE 3984204643Srdivackyunsigned clang_codeCompleteGetNumDiagnostics(CXCodeCompleteResults *Results); 3985204643Srdivacky 3986204643Srdivacky/** 3987204643Srdivacky * \brief Retrieve a diagnostic associated with the given code completion. 3988204643Srdivacky * 3989204643Srdivacky * \param Result the code completion results to query. 3990204643Srdivacky * \param Index the zero-based diagnostic number to retrieve. 3991204643Srdivacky * 3992204643Srdivacky * \returns the requested diagnostic. This diagnostic must be freed 3993204643Srdivacky * via a call to \c clang_disposeDiagnostic(). 3994204643Srdivacky */ 3995205219SrdivackyCINDEX_LINKAGE 3996204643SrdivackyCXDiagnostic clang_codeCompleteGetDiagnostic(CXCodeCompleteResults *Results, 3997204643Srdivacky unsigned Index); 3998204643Srdivacky 3999204643Srdivacky/** 4000224145Sdim * \brief Determines what compeltions are appropriate for the context 4001224145Sdim * the given code completion. 4002224145Sdim * 4003224145Sdim * \param Results the code completion results to query 4004224145Sdim * 4005224145Sdim * \returns the kinds of completions that are appropriate for use 4006224145Sdim * along with the given code completion results. 4007224145Sdim */ 4008224145SdimCINDEX_LINKAGE 4009224145Sdimunsigned long long clang_codeCompleteGetContexts( 4010224145Sdim CXCodeCompleteResults *Results); 4011226633Sdim 4012226633Sdim/** 4013226633Sdim * \brief Returns the cursor kind for the container for the current code 4014226633Sdim * completion context. The container is only guaranteed to be set for 4015226633Sdim * contexts where a container exists (i.e. member accesses or Objective-C 4016226633Sdim * message sends); if there is not a container, this function will return 4017226633Sdim * CXCursor_InvalidCode. 4018226633Sdim * 4019226633Sdim * \param Results the code completion results to query 4020226633Sdim * 4021226633Sdim * \param IsIncomplete on return, this value will be false if Clang has complete 4022226633Sdim * information about the container. If Clang does not have complete 4023226633Sdim * information, this value will be true. 4024226633Sdim * 4025226633Sdim * \returns the container kind, or CXCursor_InvalidCode if there is not a 4026226633Sdim * container 4027226633Sdim */ 4028226633SdimCINDEX_LINKAGE 4029226633Sdimenum CXCursorKind clang_codeCompleteGetContainerKind( 4030226633Sdim CXCodeCompleteResults *Results, 4031226633Sdim unsigned *IsIncomplete); 4032226633Sdim 4033226633Sdim/** 4034226633Sdim * \brief Returns the USR for the container for the current code completion 4035226633Sdim * context. If there is not a container for the current context, this 4036226633Sdim * function will return the empty string. 4037226633Sdim * 4038226633Sdim * \param Results the code completion results to query 4039226633Sdim * 4040226633Sdim * \returns the USR for the container 4041226633Sdim */ 4042226633SdimCINDEX_LINKAGE 4043226633SdimCXString clang_codeCompleteGetContainerUSR(CXCodeCompleteResults *Results); 4044224145Sdim 4045226633Sdim 4046224145Sdim/** 4047226633Sdim * \brief Returns the currently-entered selector for an Objective-C message 4048226633Sdim * send, formatted like "initWithFoo:bar:". Only guaranteed to return a 4049226633Sdim * non-empty string for CXCompletionContext_ObjCInstanceMessage and 4050226633Sdim * CXCompletionContext_ObjCClassMessage. 4051226633Sdim * 4052226633Sdim * \param Results the code completion results to query 4053226633Sdim * 4054226633Sdim * \returns the selector (or partial selector) that has been entered thus far 4055226633Sdim * for an Objective-C message send. 4056226633Sdim */ 4057226633SdimCINDEX_LINKAGE 4058226633SdimCXString clang_codeCompleteGetObjCSelector(CXCodeCompleteResults *Results); 4059226633Sdim 4060226633Sdim/** 4061202879Srdivacky * @} 4062202879Srdivacky */ 4063203955Srdivacky 4064203955Srdivacky 4065202879Srdivacky/** 4066202879Srdivacky * \defgroup CINDEX_MISC Miscellaneous utility functions 4067202879Srdivacky * 4068202879Srdivacky * @{ 4069202879Srdivacky */ 4070202879Srdivacky 4071202879Srdivacky/** 4072203955Srdivacky * \brief Return a version string, suitable for showing to a user, but not 4073203955Srdivacky * intended to be parsed (the format is not guaranteed to be stable). 4074203955Srdivacky */ 4075203955SrdivackyCINDEX_LINKAGE CXString clang_getClangVersion(); 4076203955Srdivacky 4077221345Sdim 4078221345Sdim/** 4079221345Sdim * \brief Enable/disable crash recovery. 4080221345Sdim * 4081221345Sdim * \param Flag to indicate if crash recovery is enabled. A non-zero value 4082221345Sdim * enables crash recovery, while 0 disables it. 4083221345Sdim */ 4084221345SdimCINDEX_LINKAGE void clang_toggleCrashRecovery(unsigned isEnabled); 4085221345Sdim 4086203955Srdivacky /** 4087205219Srdivacky * \brief Visitor invoked for each file in a translation unit 4088203955Srdivacky * (used with clang_getInclusions()). 4089203955Srdivacky * 4090203955Srdivacky * This visitor function will be invoked by clang_getInclusions() for each 4091203955Srdivacky * file included (either at the top-level or by #include directives) within 4092203955Srdivacky * a translation unit. The first argument is the file being included, and 4093203955Srdivacky * the second and third arguments provide the inclusion stack. The 4094203955Srdivacky * array is sorted in order of immediate inclusion. For example, 4095203955Srdivacky * the first element refers to the location that included 'included_file'. 4096203955Srdivacky */ 4097203955Srdivackytypedef void (*CXInclusionVisitor)(CXFile included_file, 4098203955Srdivacky CXSourceLocation* inclusion_stack, 4099203955Srdivacky unsigned include_len, 4100203955Srdivacky CXClientData client_data); 4101203955Srdivacky 4102203955Srdivacky/** 4103203955Srdivacky * \brief Visit the set of preprocessor inclusions in a translation unit. 4104203955Srdivacky * The visitor function is called with the provided data for every included 4105203955Srdivacky * file. This does not include headers included by the PCH file (unless one 4106203955Srdivacky * is inspecting the inclusions in the PCH file itself). 4107203955Srdivacky */ 4108203955SrdivackyCINDEX_LINKAGE void clang_getInclusions(CXTranslationUnit tu, 4109203955Srdivacky CXInclusionVisitor visitor, 4110203955Srdivacky CXClientData client_data); 4111203955Srdivacky 4112203955Srdivacky/** 4113202879Srdivacky * @} 4114202879Srdivacky */ 4115203955Srdivacky 4116224145Sdim/** \defgroup CINDEX_REMAPPING Remapping functions 4117224145Sdim * 4118224145Sdim * @{ 4119224145Sdim */ 4120224145Sdim 4121202879Srdivacky/** 4122224145Sdim * \brief A remapping of original source files and their translated files. 4123224145Sdim */ 4124224145Sdimtypedef void *CXRemapping; 4125224145Sdim 4126224145Sdim/** 4127224145Sdim * \brief Retrieve a remapping. 4128224145Sdim * 4129224145Sdim * \param path the path that contains metadata about remappings. 4130224145Sdim * 4131224145Sdim * \returns the requested remapping. This remapping must be freed 4132224145Sdim * via a call to \c clang_remap_dispose(). Can return NULL if an error occurred. 4133224145Sdim */ 4134224145SdimCINDEX_LINKAGE CXRemapping clang_getRemappings(const char *path); 4135224145Sdim 4136224145Sdim/** 4137234353Sdim * \brief Retrieve a remapping. 4138234353Sdim * 4139234353Sdim * \param filePaths pointer to an array of file paths containing remapping info. 4140234353Sdim * 4141234353Sdim * \param numFiles number of file paths. 4142234353Sdim * 4143234353Sdim * \returns the requested remapping. This remapping must be freed 4144234353Sdim * via a call to \c clang_remap_dispose(). Can return NULL if an error occurred. 4145234353Sdim */ 4146234353SdimCINDEX_LINKAGE 4147234353SdimCXRemapping clang_getRemappingsFromFileList(const char **filePaths, 4148234353Sdim unsigned numFiles); 4149234353Sdim 4150234353Sdim/** 4151224145Sdim * \brief Determine the number of remappings. 4152224145Sdim */ 4153224145SdimCINDEX_LINKAGE unsigned clang_remap_getNumFiles(CXRemapping); 4154224145Sdim 4155224145Sdim/** 4156224145Sdim * \brief Get the original and the associated filename from the remapping. 4157224145Sdim * 4158224145Sdim * \param original If non-NULL, will be set to the original filename. 4159224145Sdim * 4160224145Sdim * \param transformed If non-NULL, will be set to the filename that the original 4161224145Sdim * is associated with. 4162224145Sdim */ 4163224145SdimCINDEX_LINKAGE void clang_remap_getFilenames(CXRemapping, unsigned index, 4164224145Sdim CXString *original, CXString *transformed); 4165224145Sdim 4166224145Sdim/** 4167224145Sdim * \brief Dispose the remapping. 4168224145Sdim */ 4169224145SdimCINDEX_LINKAGE void clang_remap_dispose(CXRemapping); 4170224145Sdim 4171224145Sdim/** 4172202879Srdivacky * @} 4173202879Srdivacky */ 4174203955Srdivacky 4175226633Sdim/** \defgroup CINDEX_HIGH Higher level API functions 4176226633Sdim * 4177226633Sdim * @{ 4178226633Sdim */ 4179226633Sdim 4180226633Sdimenum CXVisitorResult { 4181226633Sdim CXVisit_Break, 4182226633Sdim CXVisit_Continue 4183226633Sdim}; 4184226633Sdim 4185226633Sdimtypedef struct { 4186226633Sdim void *context; 4187226633Sdim enum CXVisitorResult (*visit)(void *context, CXCursor, CXSourceRange); 4188226633Sdim} CXCursorAndRangeVisitor; 4189226633Sdim 4190224145Sdim/** 4191226633Sdim * \brief Find references of a declaration in a specific file. 4192226633Sdim * 4193226633Sdim * \param cursor pointing to a declaration or a reference of one. 4194226633Sdim * 4195226633Sdim * \param file to search for references. 4196226633Sdim * 4197226633Sdim * \param visitor callback that will receive pairs of CXCursor/CXSourceRange for 4198226633Sdim * each reference found. 4199226633Sdim * The CXSourceRange will point inside the file; if the reference is inside 4200226633Sdim * a macro (and not a macro argument) the CXSourceRange will be invalid. 4201226633Sdim */ 4202226633SdimCINDEX_LINKAGE void clang_findReferencesInFile(CXCursor cursor, CXFile file, 4203226633Sdim CXCursorAndRangeVisitor visitor); 4204226633Sdim 4205226633Sdim#ifdef __has_feature 4206226633Sdim# if __has_feature(blocks) 4207226633Sdim 4208226633Sdimtypedef enum CXVisitorResult 4209226633Sdim (^CXCursorAndRangeVisitorBlock)(CXCursor, CXSourceRange); 4210226633Sdim 4211226633SdimCINDEX_LINKAGE 4212226633Sdimvoid clang_findReferencesInFileWithBlock(CXCursor, CXFile, 4213226633Sdim CXCursorAndRangeVisitorBlock); 4214226633Sdim 4215226633Sdim# endif 4216226633Sdim#endif 4217226633Sdim 4218226633Sdim/** 4219234353Sdim * \brief The client's data object that is associated with a CXFile. 4220234353Sdim */ 4221234353Sdimtypedef void *CXIdxClientFile; 4222234353Sdim 4223234353Sdim/** 4224234353Sdim * \brief The client's data object that is associated with a semantic entity. 4225234353Sdim */ 4226234353Sdimtypedef void *CXIdxClientEntity; 4227234353Sdim 4228234353Sdim/** 4229234353Sdim * \brief The client's data object that is associated with a semantic container 4230234353Sdim * of entities. 4231234353Sdim */ 4232234353Sdimtypedef void *CXIdxClientContainer; 4233234353Sdim 4234234353Sdim/** 4235234353Sdim * \brief The client's data object that is associated with an AST file (PCH 4236234353Sdim * or module). 4237234353Sdim */ 4238234353Sdimtypedef void *CXIdxClientASTFile; 4239234353Sdim 4240234353Sdim/** 4241234353Sdim * \brief Source location passed to index callbacks. 4242234353Sdim */ 4243234353Sdimtypedef struct { 4244234353Sdim void *ptr_data[2]; 4245234353Sdim unsigned int_data; 4246234353Sdim} CXIdxLoc; 4247234353Sdim 4248234353Sdim/** 4249234353Sdim * \brief Data for \see ppIncludedFile callback. 4250234353Sdim */ 4251234353Sdimtypedef struct { 4252234353Sdim /** 4253234353Sdim * \brief Location of '#' in the #include/#import directive. 4254234353Sdim */ 4255234353Sdim CXIdxLoc hashLoc; 4256234353Sdim /** 4257234353Sdim * \brief Filename as written in the #include/#import directive. 4258234353Sdim */ 4259234353Sdim const char *filename; 4260234353Sdim /** 4261234353Sdim * \brief The actual file that the #include/#import directive resolved to. 4262234353Sdim */ 4263234353Sdim CXFile file; 4264234353Sdim int isImport; 4265234353Sdim int isAngled; 4266234353Sdim} CXIdxIncludedFileInfo; 4267234353Sdim 4268234353Sdim/** 4269234353Sdim * \brief Data for \see importedASTFile callback. 4270234353Sdim */ 4271234353Sdimtypedef struct { 4272234353Sdim CXFile file; 4273234353Sdim /** 4274234353Sdim * \brief Location where the file is imported. It is useful mostly for 4275234353Sdim * modules. 4276234353Sdim */ 4277234353Sdim CXIdxLoc loc; 4278234353Sdim /** 4279234353Sdim * \brief Non-zero if the AST file is a module otherwise it's a PCH. 4280234353Sdim */ 4281234353Sdim int isModule; 4282234353Sdim} CXIdxImportedASTFileInfo; 4283234353Sdim 4284234353Sdimtypedef enum { 4285234353Sdim CXIdxEntity_Unexposed = 0, 4286234353Sdim CXIdxEntity_Typedef = 1, 4287234353Sdim CXIdxEntity_Function = 2, 4288234353Sdim CXIdxEntity_Variable = 3, 4289234353Sdim CXIdxEntity_Field = 4, 4290234353Sdim CXIdxEntity_EnumConstant = 5, 4291234353Sdim 4292234353Sdim CXIdxEntity_ObjCClass = 6, 4293234353Sdim CXIdxEntity_ObjCProtocol = 7, 4294234353Sdim CXIdxEntity_ObjCCategory = 8, 4295234353Sdim 4296234353Sdim CXIdxEntity_ObjCInstanceMethod = 9, 4297234353Sdim CXIdxEntity_ObjCClassMethod = 10, 4298234353Sdim CXIdxEntity_ObjCProperty = 11, 4299234353Sdim CXIdxEntity_ObjCIvar = 12, 4300234353Sdim 4301234353Sdim CXIdxEntity_Enum = 13, 4302234353Sdim CXIdxEntity_Struct = 14, 4303234353Sdim CXIdxEntity_Union = 15, 4304234353Sdim 4305234353Sdim CXIdxEntity_CXXClass = 16, 4306234353Sdim CXIdxEntity_CXXNamespace = 17, 4307234353Sdim CXIdxEntity_CXXNamespaceAlias = 18, 4308234353Sdim CXIdxEntity_CXXStaticVariable = 19, 4309234353Sdim CXIdxEntity_CXXStaticMethod = 20, 4310234353Sdim CXIdxEntity_CXXInstanceMethod = 21, 4311234353Sdim CXIdxEntity_CXXConstructor = 22, 4312234353Sdim CXIdxEntity_CXXDestructor = 23, 4313234353Sdim CXIdxEntity_CXXConversionFunction = 24, 4314234353Sdim CXIdxEntity_CXXTypeAlias = 25 4315234353Sdim 4316234353Sdim} CXIdxEntityKind; 4317234353Sdim 4318234353Sdimtypedef enum { 4319234353Sdim CXIdxEntityLang_None = 0, 4320234353Sdim CXIdxEntityLang_C = 1, 4321234353Sdim CXIdxEntityLang_ObjC = 2, 4322234353Sdim CXIdxEntityLang_CXX = 3 4323234353Sdim} CXIdxEntityLanguage; 4324234353Sdim 4325234353Sdim/** 4326234353Sdim * \brief Extra C++ template information for an entity. This can apply to: 4327234353Sdim * CXIdxEntity_Function 4328234353Sdim * CXIdxEntity_CXXClass 4329234353Sdim * CXIdxEntity_CXXStaticMethod 4330234353Sdim * CXIdxEntity_CXXInstanceMethod 4331234353Sdim * CXIdxEntity_CXXConstructor 4332234353Sdim * CXIdxEntity_CXXConversionFunction 4333234353Sdim * CXIdxEntity_CXXTypeAlias 4334234353Sdim */ 4335234353Sdimtypedef enum { 4336234353Sdim CXIdxEntity_NonTemplate = 0, 4337234353Sdim CXIdxEntity_Template = 1, 4338234353Sdim CXIdxEntity_TemplatePartialSpecialization = 2, 4339234353Sdim CXIdxEntity_TemplateSpecialization = 3 4340234353Sdim} CXIdxEntityCXXTemplateKind; 4341234353Sdim 4342234353Sdimtypedef enum { 4343234353Sdim CXIdxAttr_Unexposed = 0, 4344234353Sdim CXIdxAttr_IBAction = 1, 4345234353Sdim CXIdxAttr_IBOutlet = 2, 4346234353Sdim CXIdxAttr_IBOutletCollection = 3 4347234353Sdim} CXIdxAttrKind; 4348234353Sdim 4349234353Sdimtypedef struct { 4350234353Sdim CXIdxAttrKind kind; 4351234353Sdim CXCursor cursor; 4352234353Sdim CXIdxLoc loc; 4353234353Sdim} CXIdxAttrInfo; 4354234353Sdim 4355234353Sdimtypedef struct { 4356234353Sdim CXIdxEntityKind kind; 4357234353Sdim CXIdxEntityCXXTemplateKind templateKind; 4358234353Sdim CXIdxEntityLanguage lang; 4359234353Sdim const char *name; 4360234353Sdim const char *USR; 4361234353Sdim CXCursor cursor; 4362234353Sdim const CXIdxAttrInfo *const *attributes; 4363234353Sdim unsigned numAttributes; 4364234353Sdim} CXIdxEntityInfo; 4365234353Sdim 4366234353Sdimtypedef struct { 4367234353Sdim CXCursor cursor; 4368234353Sdim} CXIdxContainerInfo; 4369234353Sdim 4370234353Sdimtypedef struct { 4371234353Sdim const CXIdxAttrInfo *attrInfo; 4372234353Sdim const CXIdxEntityInfo *objcClass; 4373234353Sdim CXCursor classCursor; 4374234353Sdim CXIdxLoc classLoc; 4375234353Sdim} CXIdxIBOutletCollectionAttrInfo; 4376234353Sdim 4377234353Sdimtypedef struct { 4378234353Sdim const CXIdxEntityInfo *entityInfo; 4379234353Sdim CXCursor cursor; 4380234353Sdim CXIdxLoc loc; 4381234353Sdim const CXIdxContainerInfo *semanticContainer; 4382234353Sdim /** 4383234353Sdim * \brief Generally same as \see semanticContainer but can be different in 4384234353Sdim * cases like out-of-line C++ member functions. 4385234353Sdim */ 4386234353Sdim const CXIdxContainerInfo *lexicalContainer; 4387234353Sdim int isRedeclaration; 4388234353Sdim int isDefinition; 4389234353Sdim int isContainer; 4390234353Sdim const CXIdxContainerInfo *declAsContainer; 4391234353Sdim /** 4392234353Sdim * \brief Whether the declaration exists in code or was created implicitly 4393234353Sdim * by the compiler, e.g. implicit objc methods for properties. 4394234353Sdim */ 4395234353Sdim int isImplicit; 4396234353Sdim const CXIdxAttrInfo *const *attributes; 4397234353Sdim unsigned numAttributes; 4398234353Sdim} CXIdxDeclInfo; 4399234353Sdim 4400234353Sdimtypedef enum { 4401234353Sdim CXIdxObjCContainer_ForwardRef = 0, 4402234353Sdim CXIdxObjCContainer_Interface = 1, 4403234353Sdim CXIdxObjCContainer_Implementation = 2 4404234353Sdim} CXIdxObjCContainerKind; 4405234353Sdim 4406234353Sdimtypedef struct { 4407234353Sdim const CXIdxDeclInfo *declInfo; 4408234353Sdim CXIdxObjCContainerKind kind; 4409234353Sdim} CXIdxObjCContainerDeclInfo; 4410234353Sdim 4411234353Sdimtypedef struct { 4412234353Sdim const CXIdxEntityInfo *base; 4413234353Sdim CXCursor cursor; 4414234353Sdim CXIdxLoc loc; 4415234353Sdim} CXIdxBaseClassInfo; 4416234353Sdim 4417234353Sdimtypedef struct { 4418234353Sdim const CXIdxEntityInfo *protocol; 4419234353Sdim CXCursor cursor; 4420234353Sdim CXIdxLoc loc; 4421234353Sdim} CXIdxObjCProtocolRefInfo; 4422234353Sdim 4423234353Sdimtypedef struct { 4424234353Sdim const CXIdxObjCProtocolRefInfo *const *protocols; 4425234353Sdim unsigned numProtocols; 4426234353Sdim} CXIdxObjCProtocolRefListInfo; 4427234353Sdim 4428234353Sdimtypedef struct { 4429234353Sdim const CXIdxObjCContainerDeclInfo *containerInfo; 4430234353Sdim const CXIdxBaseClassInfo *superInfo; 4431234353Sdim const CXIdxObjCProtocolRefListInfo *protocols; 4432234353Sdim} CXIdxObjCInterfaceDeclInfo; 4433234353Sdim 4434234353Sdimtypedef struct { 4435234353Sdim const CXIdxObjCContainerDeclInfo *containerInfo; 4436234353Sdim const CXIdxEntityInfo *objcClass; 4437234353Sdim CXCursor classCursor; 4438234353Sdim CXIdxLoc classLoc; 4439234353Sdim const CXIdxObjCProtocolRefListInfo *protocols; 4440234353Sdim} CXIdxObjCCategoryDeclInfo; 4441234353Sdim 4442234353Sdimtypedef struct { 4443234353Sdim const CXIdxDeclInfo *declInfo; 4444234353Sdim const CXIdxEntityInfo *getter; 4445234353Sdim const CXIdxEntityInfo *setter; 4446234353Sdim} CXIdxObjCPropertyDeclInfo; 4447234353Sdim 4448234353Sdimtypedef struct { 4449234353Sdim const CXIdxDeclInfo *declInfo; 4450234353Sdim const CXIdxBaseClassInfo *const *bases; 4451234353Sdim unsigned numBases; 4452234353Sdim} CXIdxCXXClassDeclInfo; 4453234353Sdim 4454234353Sdim/** 4455234353Sdim * \brief Data for \see indexEntityReference callback. 4456234353Sdim */ 4457234353Sdimtypedef enum { 4458234353Sdim /** 4459234353Sdim * \brief The entity is referenced directly in user's code. 4460234353Sdim */ 4461234353Sdim CXIdxEntityRef_Direct = 1, 4462234353Sdim /** 4463234353Sdim * \brief An implicit reference, e.g. a reference of an ObjC method via the 4464234353Sdim * dot syntax. 4465234353Sdim */ 4466234353Sdim CXIdxEntityRef_Implicit = 2 4467234353Sdim} CXIdxEntityRefKind; 4468234353Sdim 4469234353Sdim/** 4470234353Sdim * \brief Data for \see indexEntityReference callback. 4471234353Sdim */ 4472234353Sdimtypedef struct { 4473234353Sdim CXIdxEntityRefKind kind; 4474234353Sdim /** 4475234353Sdim * \brief Reference cursor. 4476234353Sdim */ 4477234353Sdim CXCursor cursor; 4478234353Sdim CXIdxLoc loc; 4479234353Sdim /** 4480234353Sdim * \brief The entity that gets referenced. 4481234353Sdim */ 4482234353Sdim const CXIdxEntityInfo *referencedEntity; 4483234353Sdim /** 4484234353Sdim * \brief Immediate "parent" of the reference. For example: 4485234353Sdim * 4486234353Sdim * \code 4487234353Sdim * Foo *var; 4488234353Sdim * \endcode 4489234353Sdim * 4490234353Sdim * The parent of reference of type 'Foo' is the variable 'var'. 4491234353Sdim * For references inside statement bodies of functions/methods, 4492234353Sdim * the parentEntity will be the function/method. 4493234353Sdim */ 4494234353Sdim const CXIdxEntityInfo *parentEntity; 4495234353Sdim /** 4496234353Sdim * \brief Lexical container context of the reference. 4497234353Sdim */ 4498234353Sdim const CXIdxContainerInfo *container; 4499234353Sdim} CXIdxEntityRefInfo; 4500234353Sdim 4501234353Sdimtypedef struct { 4502234353Sdim /** 4503234353Sdim * \brief Called periodically to check whether indexing should be aborted. 4504234353Sdim * Should return 0 to continue, and non-zero to abort. 4505234353Sdim */ 4506234353Sdim int (*abortQuery)(CXClientData client_data, void *reserved); 4507234353Sdim 4508234353Sdim /** 4509234353Sdim * \brief Called at the end of indexing; passes the complete diagnostic set. 4510234353Sdim */ 4511234353Sdim void (*diagnostic)(CXClientData client_data, 4512234353Sdim CXDiagnosticSet, void *reserved); 4513234353Sdim 4514234353Sdim CXIdxClientFile (*enteredMainFile)(CXClientData client_data, 4515234353Sdim CXFile mainFile, void *reserved); 4516234353Sdim 4517234353Sdim /** 4518234353Sdim * \brief Called when a file gets #included/#imported. 4519234353Sdim */ 4520234353Sdim CXIdxClientFile (*ppIncludedFile)(CXClientData client_data, 4521234353Sdim const CXIdxIncludedFileInfo *); 4522234353Sdim 4523234353Sdim /** 4524234353Sdim * \brief Called when a AST file (PCH or module) gets imported. 4525234353Sdim * 4526234353Sdim * AST files will not get indexed (there will not be callbacks to index all 4527234353Sdim * the entities in an AST file). The recommended action is that, if the AST 4528234353Sdim * file is not already indexed, to block further indexing and initiate a new 4529234353Sdim * indexing job specific to the AST file. 4530234353Sdim */ 4531234353Sdim CXIdxClientASTFile (*importedASTFile)(CXClientData client_data, 4532234353Sdim const CXIdxImportedASTFileInfo *); 4533234353Sdim 4534234353Sdim /** 4535234353Sdim * \brief Called at the beginning of indexing a translation unit. 4536234353Sdim */ 4537234353Sdim CXIdxClientContainer (*startedTranslationUnit)(CXClientData client_data, 4538234353Sdim void *reserved); 4539234353Sdim 4540234353Sdim void (*indexDeclaration)(CXClientData client_data, 4541234353Sdim const CXIdxDeclInfo *); 4542234353Sdim 4543234353Sdim /** 4544234353Sdim * \brief Called to index a reference of an entity. 4545234353Sdim */ 4546234353Sdim void (*indexEntityReference)(CXClientData client_data, 4547234353Sdim const CXIdxEntityRefInfo *); 4548234353Sdim 4549234353Sdim} IndexerCallbacks; 4550234353Sdim 4551234353SdimCINDEX_LINKAGE int clang_index_isEntityObjCContainerKind(CXIdxEntityKind); 4552234353SdimCINDEX_LINKAGE const CXIdxObjCContainerDeclInfo * 4553234353Sdimclang_index_getObjCContainerDeclInfo(const CXIdxDeclInfo *); 4554234353Sdim 4555234353SdimCINDEX_LINKAGE const CXIdxObjCInterfaceDeclInfo * 4556234353Sdimclang_index_getObjCInterfaceDeclInfo(const CXIdxDeclInfo *); 4557234353Sdim 4558234353SdimCINDEX_LINKAGE 4559234353Sdimconst CXIdxObjCCategoryDeclInfo * 4560234353Sdimclang_index_getObjCCategoryDeclInfo(const CXIdxDeclInfo *); 4561234353Sdim 4562234353SdimCINDEX_LINKAGE const CXIdxObjCProtocolRefListInfo * 4563234353Sdimclang_index_getObjCProtocolRefListInfo(const CXIdxDeclInfo *); 4564234353Sdim 4565234353SdimCINDEX_LINKAGE const CXIdxObjCPropertyDeclInfo * 4566234353Sdimclang_index_getObjCPropertyDeclInfo(const CXIdxDeclInfo *); 4567234353Sdim 4568234353SdimCINDEX_LINKAGE const CXIdxIBOutletCollectionAttrInfo * 4569234353Sdimclang_index_getIBOutletCollectionAttrInfo(const CXIdxAttrInfo *); 4570234353Sdim 4571234353SdimCINDEX_LINKAGE const CXIdxCXXClassDeclInfo * 4572234353Sdimclang_index_getCXXClassDeclInfo(const CXIdxDeclInfo *); 4573234353Sdim 4574234353Sdim/** 4575234353Sdim * \brief For retrieving a custom CXIdxClientContainer attached to a 4576234353Sdim * container. 4577234353Sdim */ 4578234353SdimCINDEX_LINKAGE CXIdxClientContainer 4579234353Sdimclang_index_getClientContainer(const CXIdxContainerInfo *); 4580234353Sdim 4581234353Sdim/** 4582234353Sdim * \brief For setting a custom CXIdxClientContainer attached to a 4583234353Sdim * container. 4584234353Sdim */ 4585234353SdimCINDEX_LINKAGE void 4586234353Sdimclang_index_setClientContainer(const CXIdxContainerInfo *,CXIdxClientContainer); 4587234353Sdim 4588234353Sdim/** 4589234353Sdim * \brief For retrieving a custom CXIdxClientEntity attached to an entity. 4590234353Sdim */ 4591234353SdimCINDEX_LINKAGE CXIdxClientEntity 4592234353Sdimclang_index_getClientEntity(const CXIdxEntityInfo *); 4593234353Sdim 4594234353Sdim/** 4595234353Sdim * \brief For setting a custom CXIdxClientEntity attached to an entity. 4596234353Sdim */ 4597234353SdimCINDEX_LINKAGE void 4598234353Sdimclang_index_setClientEntity(const CXIdxEntityInfo *, CXIdxClientEntity); 4599234353Sdim 4600234353Sdim/** 4601234353Sdim * \brief An indexing action, to be applied to one or multiple translation units 4602234353Sdim * but not on concurrent threads. If there are threads doing indexing 4603234353Sdim * concurrently, they should use different CXIndexAction objects. 4604234353Sdim */ 4605234353Sdimtypedef void *CXIndexAction; 4606234353Sdim 4607234353Sdim/** 4608234353Sdim * \brief An indexing action, to be applied to one or multiple translation units 4609234353Sdim * but not on concurrent threads. If there are threads doing indexing 4610234353Sdim * concurrently, they should use different CXIndexAction objects. 4611234353Sdim * 4612234353Sdim * \param CIdx The index object with which the index action will be associated. 4613234353Sdim */ 4614234353SdimCINDEX_LINKAGE CXIndexAction clang_IndexAction_create(CXIndex CIdx); 4615234353Sdim 4616234353Sdim/** 4617234353Sdim * \brief Destroy the given index action. 4618234353Sdim * 4619234353Sdim * The index action must not be destroyed until all of the translation units 4620234353Sdim * created within that index action have been destroyed. 4621234353Sdim */ 4622234353SdimCINDEX_LINKAGE void clang_IndexAction_dispose(CXIndexAction); 4623234353Sdim 4624234353Sdimtypedef enum { 4625234353Sdim /** 4626234353Sdim * \brief Used to indicate that no special indexing options are needed. 4627234353Sdim */ 4628234353Sdim CXIndexOpt_None = 0x0, 4629234353Sdim 4630234353Sdim /** 4631234353Sdim * \brief Used to indicate that \see indexEntityReference should be invoked 4632234353Sdim * for only one reference of an entity per source file that does not also 4633234353Sdim * include a declaration/definition of the entity. 4634234353Sdim */ 4635234353Sdim CXIndexOpt_SuppressRedundantRefs = 0x1, 4636234353Sdim 4637234353Sdim /** 4638234353Sdim * \brief Function-local symbols should be indexed. If this is not set 4639234353Sdim * function-local symbols will be ignored. 4640234353Sdim */ 4641234353Sdim CXIndexOpt_IndexFunctionLocalSymbols = 0x2, 4642234353Sdim 4643234353Sdim /** 4644234353Sdim * \brief Implicit function/class template instantiations should be indexed. 4645234353Sdim * If this is not set, implicit instantiations will be ignored. 4646234353Sdim */ 4647234353Sdim CXIndexOpt_IndexImplicitTemplateInstantiations = 0x4, 4648234353Sdim 4649234353Sdim /** 4650234353Sdim * \brief Suppress all compiler warnings when parsing for indexing. 4651234353Sdim */ 4652234353Sdim CXIndexOpt_SuppressWarnings = 0x8 4653234353Sdim} CXIndexOptFlags; 4654234353Sdim 4655234353Sdim/** 4656234353Sdim * \brief Index the given source file and the translation unit corresponding 4657234353Sdim * to that file via callbacks implemented through \see IndexerCallbacks. 4658234353Sdim * 4659234353Sdim * \param client_data pointer data supplied by the client, which will 4660234353Sdim * be passed to the invoked callbacks. 4661234353Sdim * 4662234353Sdim * \param index_callbacks Pointer to indexing callbacks that the client 4663234353Sdim * implements. 4664234353Sdim * 4665234353Sdim * \param index_callbacks_size Size of \see IndexerCallbacks structure that gets 4666234353Sdim * passed in index_callbacks. 4667234353Sdim * 4668234353Sdim * \param index_options A bitmask of options that affects how indexing is 4669234353Sdim * performed. This should be a bitwise OR of the CXIndexOpt_XXX flags. 4670234353Sdim * 4671234353Sdim * \param out_TU [out] pointer to store a CXTranslationUnit that can be reused 4672234353Sdim * after indexing is finished. Set to NULL if you do not require it. 4673234353Sdim * 4674234353Sdim * \returns If there is a failure from which the there is no recovery, returns 4675234353Sdim * non-zero, otherwise returns 0. 4676234353Sdim * 4677234353Sdim * The rest of the parameters are the same as \see clang_parseTranslationUnit. 4678234353Sdim */ 4679234353SdimCINDEX_LINKAGE int clang_indexSourceFile(CXIndexAction, 4680234353Sdim CXClientData client_data, 4681234353Sdim IndexerCallbacks *index_callbacks, 4682234353Sdim unsigned index_callbacks_size, 4683234353Sdim unsigned index_options, 4684234353Sdim const char *source_filename, 4685234353Sdim const char * const *command_line_args, 4686234353Sdim int num_command_line_args, 4687234353Sdim struct CXUnsavedFile *unsaved_files, 4688234353Sdim unsigned num_unsaved_files, 4689234353Sdim CXTranslationUnit *out_TU, 4690234353Sdim unsigned TU_options); 4691234353Sdim 4692234353Sdim/** 4693234353Sdim * \brief Index the given translation unit via callbacks implemented through 4694234353Sdim * \see IndexerCallbacks. 4695234353Sdim * 4696234353Sdim * The order of callback invocations is not guaranteed to be the same as 4697234353Sdim * when indexing a source file. The high level order will be: 4698234353Sdim * 4699234353Sdim * -Preprocessor callbacks invocations 4700234353Sdim * -Declaration/reference callbacks invocations 4701234353Sdim * -Diagnostic callback invocations 4702234353Sdim * 4703234353Sdim * The parameters are the same as \see clang_indexSourceFile. 4704234353Sdim * 4705234353Sdim * \returns If there is a failure from which the there is no recovery, returns 4706234353Sdim * non-zero, otherwise returns 0. 4707234353Sdim */ 4708234353SdimCINDEX_LINKAGE int clang_indexTranslationUnit(CXIndexAction, 4709234353Sdim CXClientData client_data, 4710234353Sdim IndexerCallbacks *index_callbacks, 4711234353Sdim unsigned index_callbacks_size, 4712234353Sdim unsigned index_options, 4713234353Sdim CXTranslationUnit); 4714234353Sdim 4715234353Sdim/** 4716234353Sdim * \brief Retrieve the CXIdxFile, file, line, column, and offset represented by 4717234353Sdim * the given CXIdxLoc. 4718234353Sdim * 4719234353Sdim * If the location refers into a macro expansion, retrieves the 4720234353Sdim * location of the macro expansion and if it refers into a macro argument 4721234353Sdim * retrieves the location of the argument. 4722234353Sdim */ 4723234353SdimCINDEX_LINKAGE void clang_indexLoc_getFileLocation(CXIdxLoc loc, 4724234353Sdim CXIdxClientFile *indexFile, 4725234353Sdim CXFile *file, 4726234353Sdim unsigned *line, 4727234353Sdim unsigned *column, 4728234353Sdim unsigned *offset); 4729234353Sdim 4730234353Sdim/** 4731234353Sdim * \brief Retrieve the CXSourceLocation represented by the given CXIdxLoc. 4732234353Sdim */ 4733234353SdimCINDEX_LINKAGE 4734234353SdimCXSourceLocation clang_indexLoc_getCXSourceLocation(CXIdxLoc loc); 4735234353Sdim 4736234353Sdim/** 4737224145Sdim * @} 4738224145Sdim */ 4739224145Sdim 4740226633Sdim/** 4741226633Sdim * @} 4742226633Sdim */ 4743226633Sdim 4744198092Srdivacky#ifdef __cplusplus 4745198092Srdivacky} 4746198092Srdivacky#endif 4747198092Srdivacky#endif 4748198092Srdivacky 4749