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 19201361Srdivacky#include <time.h> 20198893Srdivacky 21245431Sdim#include "clang-c/Platform.h" 22245431Sdim#include "clang-c/CXString.h" 23245431Sdim 24245431Sdim/** 25245431Sdim * \brief The version constants for the libclang API. 26245431Sdim * CINDEX_VERSION_MINOR should increase when there are API additions. 27245431Sdim * CINDEX_VERSION_MAJOR is intended for "major" source/ABI breaking changes. 28245431Sdim * 29245431Sdim * The policy about the libclang API was always to keep it source and ABI 30245431Sdim * compatible, thus CINDEX_VERSION_MAJOR is expected to remain stable. 31245431Sdim */ 32245431Sdim#define CINDEX_VERSION_MAJOR 0 33263509Sdim#define CINDEX_VERSION_MINOR 20 34245431Sdim 35245431Sdim#define CINDEX_VERSION_ENCODE(major, minor) ( \ 36245431Sdim ((major) * 10000) \ 37245431Sdim + ((minor) * 1)) 38245431Sdim 39245431Sdim#define CINDEX_VERSION CINDEX_VERSION_ENCODE( \ 40245431Sdim CINDEX_VERSION_MAJOR, \ 41245431Sdim CINDEX_VERSION_MINOR ) 42245431Sdim 43245431Sdim#define CINDEX_VERSION_STRINGIZE_(major, minor) \ 44245431Sdim #major"."#minor 45245431Sdim#define CINDEX_VERSION_STRINGIZE(major, minor) \ 46245431Sdim CINDEX_VERSION_STRINGIZE_(major, minor) 47245431Sdim 48245431Sdim#define CINDEX_VERSION_STRING CINDEX_VERSION_STRINGIZE( \ 49245431Sdim CINDEX_VERSION_MAJOR, \ 50245431Sdim CINDEX_VERSION_MINOR) 51245431Sdim 52198092Srdivacky#ifdef __cplusplus 53198092Srdivackyextern "C" { 54198092Srdivacky#endif 55198092Srdivacky 56219077Sdim/** \defgroup CINDEX libclang: C Interface to Clang 57202879Srdivacky * 58203955Srdivacky * The C Interface to Clang provides a relatively small API that exposes 59202879Srdivacky * facilities for parsing source code into an abstract syntax tree (AST), 60202879Srdivacky * loading already-parsed ASTs, traversing the AST, associating 61202879Srdivacky * physical source locations with elements within the AST, and other 62202879Srdivacky * facilities that support Clang-based development tools. 63202879Srdivacky * 64203955Srdivacky * This C interface to Clang will never provide all of the information 65202879Srdivacky * representation stored in Clang's C++ AST, nor should it: the intent is to 66202879Srdivacky * maintain an API that is relatively stable from one release to the next, 67202879Srdivacky * providing only the basic functionality needed to support development tools. 68203955Srdivacky * 69203955Srdivacky * To avoid namespace pollution, data types are prefixed with "CX" and 70202879Srdivacky * functions are prefixed with "clang_". 71202879Srdivacky * 72202879Srdivacky * @{ 73202879Srdivacky */ 74203955Srdivacky 75202879Srdivacky/** 76202879Srdivacky * \brief An "index" that consists of a set of translation units that would 77202879Srdivacky * typically be linked together into an executable or library. 78202879Srdivacky */ 79202879Srdivackytypedef void *CXIndex; 80198092Srdivacky 81202879Srdivacky/** 82202879Srdivacky * \brief A single translation unit, which resides in an index. 83202879Srdivacky */ 84218893Sdimtypedef struct CXTranslationUnitImpl *CXTranslationUnit; 85198092Srdivacky 86200583Srdivacky/** 87202879Srdivacky * \brief Opaque pointer representing client data that will be passed through 88202879Srdivacky * to various callbacks and visitors. 89202879Srdivacky */ 90202879Srdivackytypedef void *CXClientData; 91203955Srdivacky 92202879Srdivacky/** 93200583Srdivacky * \brief Provides the contents of a file that has not yet been saved to disk. 94200583Srdivacky * 95200583Srdivacky * Each CXUnsavedFile instance provides the name of a file on the 96200583Srdivacky * system along with the current contents of that file that have not 97200583Srdivacky * yet been saved to disk. 98200583Srdivacky */ 99200583Srdivackystruct CXUnsavedFile { 100203955Srdivacky /** 101203955Srdivacky * \brief The file whose contents have not yet been saved. 102200583Srdivacky * 103200583Srdivacky * This file must already exist in the file system. 104200583Srdivacky */ 105200583Srdivacky const char *Filename; 106200583Srdivacky 107203955Srdivacky /** 108204643Srdivacky * \brief A buffer containing the unsaved contents of this file. 109200583Srdivacky */ 110200583Srdivacky const char *Contents; 111200583Srdivacky 112200583Srdivacky /** 113204643Srdivacky * \brief The length of the unsaved contents of this buffer. 114200583Srdivacky */ 115200583Srdivacky unsigned long Length; 116200583Srdivacky}; 117200583Srdivacky 118199482Srdivacky/** 119212904Sdim * \brief Describes the availability of a particular entity, which indicates 120212904Sdim * whether the use of this entity will result in a warning or error due to 121212904Sdim * it being deprecated or unavailable. 122212904Sdim */ 123212904Sdimenum CXAvailabilityKind { 124212904Sdim /** 125212904Sdim * \brief The entity is available. 126212904Sdim */ 127212904Sdim CXAvailability_Available, 128212904Sdim /** 129212904Sdim * \brief The entity is available, but has been deprecated (and its use is 130212904Sdim * not recommended). 131212904Sdim */ 132212904Sdim CXAvailability_Deprecated, 133212904Sdim /** 134212904Sdim * \brief The entity is not available; any use of it will be an error. 135212904Sdim */ 136226890Sdim CXAvailability_NotAvailable, 137226890Sdim /** 138226890Sdim * \brief The entity is available, but not accessible; any use of it will be 139226890Sdim * an error. 140226890Sdim */ 141226890Sdim CXAvailability_NotAccessible 142212904Sdim}; 143203955Srdivacky 144202879Srdivacky/** 145245431Sdim * \brief Describes a version number of the form major.minor.subminor. 146202879Srdivacky */ 147245431Sdimtypedef struct CXVersion { 148245431Sdim /** 149245431Sdim * \brief The major version number, e.g., the '10' in '10.7.3'. A negative 150245431Sdim * value indicates that there is no version number at all. 151245431Sdim */ 152245431Sdim int Major; 153245431Sdim /** 154245431Sdim * \brief The minor version number, e.g., the '7' in '10.7.3'. This value 155245431Sdim * will be negative if no minor version number was provided, e.g., for 156245431Sdim * version '10'. 157245431Sdim */ 158245431Sdim int Minor; 159245431Sdim /** 160245431Sdim * \brief The subminor version number, e.g., the '3' in '10.7.3'. This value 161245431Sdim * will be negative if no minor or subminor version number was provided, 162245431Sdim * e.g., in version '10' or '10.7'. 163245431Sdim */ 164245431Sdim int Subminor; 165245431Sdim} CXVersion; 166245431Sdim 167202879Srdivacky/** 168245431Sdim * \brief Provides a shared context for creating translation units. 169198398Srdivacky * 170245431Sdim * It provides two options: 171245431Sdim * 172198398Srdivacky * - excludeDeclarationsFromPCH: When non-zero, allows enumeration of "local" 173198398Srdivacky * declarations (when loading any new translation units). A "local" declaration 174203955Srdivacky * is one that belongs in the translation unit itself and not in a precompiled 175198398Srdivacky * header that was used by the translation unit. If zero, all declarations 176198398Srdivacky * will be enumerated. 177198398Srdivacky * 178198398Srdivacky * Here is an example: 179198398Srdivacky * 180245431Sdim * \code 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); 201245431Sdim * \endcode 202198398Srdivacky * 203198398Srdivacky * This process of creating the 'pch', loading it separately, and using it (via 204198398Srdivacky * -include-pch) allows 'excludeDeclsFromPCH' to remove redundant callbacks 205198398Srdivacky * (which gives the indexer the same performance benefit as the compiler). 206198398Srdivacky */ 207204643SrdivackyCINDEX_LINKAGE CXIndex clang_createIndex(int excludeDeclarationsFromPCH, 208204643Srdivacky int displayDiagnostics); 209205219Srdivacky 210203955Srdivacky/** 211203955Srdivacky * \brief Destroy the given index. 212203955Srdivacky * 213203955Srdivacky * The index must not be destroyed until all of the translation units created 214203955Srdivacky * within that index have been destroyed. 215203955Srdivacky */ 216200583SrdivackyCINDEX_LINKAGE void clang_disposeIndex(CXIndex index); 217198092Srdivacky 218235633Sdimtypedef enum { 219235633Sdim /** 220235633Sdim * \brief Used to indicate that no special CXIndex options are needed. 221235633Sdim */ 222235633Sdim CXGlobalOpt_None = 0x0, 223235633Sdim 224235633Sdim /** 225235633Sdim * \brief Used to indicate that threads that libclang creates for indexing 226235633Sdim * purposes should use background priority. 227245431Sdim * 228245431Sdim * Affects #clang_indexSourceFile, #clang_indexTranslationUnit, 229245431Sdim * #clang_parseTranslationUnit, #clang_saveTranslationUnit. 230235633Sdim */ 231235633Sdim CXGlobalOpt_ThreadBackgroundPriorityForIndexing = 0x1, 232235633Sdim 233235633Sdim /** 234235633Sdim * \brief Used to indicate that threads that libclang creates for editing 235235633Sdim * purposes should use background priority. 236245431Sdim * 237245431Sdim * Affects #clang_reparseTranslationUnit, #clang_codeCompleteAt, 238245431Sdim * #clang_annotateTokens 239235633Sdim */ 240235633Sdim CXGlobalOpt_ThreadBackgroundPriorityForEditing = 0x2, 241235633Sdim 242235633Sdim /** 243235633Sdim * \brief Used to indicate that all threads that libclang creates should use 244235633Sdim * background priority. 245235633Sdim */ 246235633Sdim CXGlobalOpt_ThreadBackgroundPriorityForAll = 247235633Sdim CXGlobalOpt_ThreadBackgroundPriorityForIndexing | 248235633Sdim CXGlobalOpt_ThreadBackgroundPriorityForEditing 249235633Sdim 250235633Sdim} CXGlobalOptFlags; 251235633Sdim 252202879Srdivacky/** 253245431Sdim * \brief Sets general options associated with a CXIndex. 254235633Sdim * 255235633Sdim * For example: 256235633Sdim * \code 257235633Sdim * CXIndex idx = ...; 258235633Sdim * clang_CXIndex_setGlobalOptions(idx, 259235633Sdim * clang_CXIndex_getGlobalOptions(idx) | 260235633Sdim * CXGlobalOpt_ThreadBackgroundPriorityForIndexing); 261235633Sdim * \endcode 262235633Sdim * 263235633Sdim * \param options A bitmask of options, a bitwise OR of CXGlobalOpt_XXX flags. 264235633Sdim */ 265235633SdimCINDEX_LINKAGE void clang_CXIndex_setGlobalOptions(CXIndex, unsigned options); 266235633Sdim 267235633Sdim/** 268235633Sdim * \brief Gets the general options associated with a CXIndex. 269235633Sdim * 270235633Sdim * \returns A bitmask of options, a bitwise OR of CXGlobalOpt_XXX flags that 271235633Sdim * are associated with the given CXIndex object. 272235633Sdim */ 273235633SdimCINDEX_LINKAGE unsigned clang_CXIndex_getGlobalOptions(CXIndex); 274235633Sdim 275235633Sdim/** 276202879Srdivacky * \defgroup CINDEX_FILES File manipulation routines 277202879Srdivacky * 278202879Srdivacky * @{ 279202879Srdivacky */ 280203955Srdivacky 281202879Srdivacky/** 282202879Srdivacky * \brief A particular source file that is part of a translation unit. 283202879Srdivacky */ 284202879Srdivackytypedef void *CXFile; 285198092Srdivacky 286203955Srdivacky 287202879Srdivacky/** 288202879Srdivacky * \brief Retrieve the complete file and path name of the given file. 289202879Srdivacky */ 290204643SrdivackyCINDEX_LINKAGE CXString clang_getFileName(CXFile SFile); 291203955Srdivacky 292202879Srdivacky/** 293202879Srdivacky * \brief Retrieve the last modification time of the given file. 294202879Srdivacky */ 295202879SrdivackyCINDEX_LINKAGE time_t clang_getFileTime(CXFile SFile); 296198092Srdivacky 297202879Srdivacky/** 298252723Sdim * \brief Uniquely identifies a CXFile, that refers to the same underlying file, 299252723Sdim * across an indexing session. 300252723Sdim */ 301252723Sdimtypedef struct { 302252723Sdim unsigned long long data[3]; 303252723Sdim} CXFileUniqueID; 304252723Sdim 305252723Sdim/** 306252723Sdim * \brief Retrieve the unique ID for the given \c file. 307252723Sdim * 308252723Sdim * \param file the file to get the ID for. 309252723Sdim * \param outID stores the returned CXFileUniqueID. 310252723Sdim * \returns If there was a failure getting the unique ID, returns non-zero, 311252723Sdim * otherwise returns 0. 312252723Sdim*/ 313252723SdimCINDEX_LINKAGE int clang_getFileUniqueID(CXFile file, CXFileUniqueID *outID); 314252723Sdim 315252723Sdim/** 316223017Sdim * \brief Determine whether the given header is guarded against 317223017Sdim * multiple inclusions, either with the conventional 318245431Sdim * \#ifndef/\#define/\#endif macro guards or with \#pragma once. 319223017Sdim */ 320223017SdimCINDEX_LINKAGE unsigned 321223017Sdimclang_isFileMultipleIncludeGuarded(CXTranslationUnit tu, CXFile file); 322223017Sdim 323223017Sdim/** 324202879Srdivacky * \brief Retrieve a file handle within the given translation unit. 325202879Srdivacky * 326202879Srdivacky * \param tu the translation unit 327203955Srdivacky * 328202879Srdivacky * \param file_name the name of the file. 329202879Srdivacky * 330202879Srdivacky * \returns the file handle for the named file in the translation unit \p tu, 331202879Srdivacky * or a NULL file handle if the file was not a part of this translation unit. 332202879Srdivacky */ 333203955SrdivackyCINDEX_LINKAGE CXFile clang_getFile(CXTranslationUnit tu, 334202879Srdivacky const char *file_name); 335203955Srdivacky 336202879Srdivacky/** 337202879Srdivacky * @} 338202879Srdivacky */ 339198092Srdivacky 340202879Srdivacky/** 341202879Srdivacky * \defgroup CINDEX_LOCATIONS Physical source locations 342202879Srdivacky * 343202879Srdivacky * Clang represents physical source locations in its abstract syntax tree in 344202879Srdivacky * great detail, with file, line, and column information for the majority of 345202879Srdivacky * the tokens parsed in the source code. These data types and functions are 346202879Srdivacky * used to represent source location information, either for a particular 347202879Srdivacky * point in the program or for a range of points in the program, and extract 348202879Srdivacky * specific location information from those data types. 349202879Srdivacky * 350202879Srdivacky * @{ 351202879Srdivacky */ 352203955Srdivacky 353202879Srdivacky/** 354202879Srdivacky * \brief Identifies a specific source location within a translation 355202879Srdivacky * unit. 356202879Srdivacky * 357226890Sdim * Use clang_getExpansionLocation() or clang_getSpellingLocation() 358218893Sdim * to map a source location to a particular file, line, and column. 359202879Srdivacky */ 360202879Srdivackytypedef struct { 361252723Sdim const void *ptr_data[2]; 362202879Srdivacky unsigned int_data; 363202879Srdivacky} CXSourceLocation; 364198092Srdivacky 365202879Srdivacky/** 366203955Srdivacky * \brief Identifies a half-open character range in the source code. 367202879Srdivacky * 368202879Srdivacky * Use clang_getRangeStart() and clang_getRangeEnd() to retrieve the 369202879Srdivacky * starting and end locations from a source range, respectively. 370198893Srdivacky */ 371202879Srdivackytypedef struct { 372252723Sdim const void *ptr_data[2]; 373202879Srdivacky unsigned begin_int_data; 374202879Srdivacky unsigned end_int_data; 375202879Srdivacky} CXSourceRange; 376198893Srdivacky 377202879Srdivacky/** 378202879Srdivacky * \brief Retrieve a NULL (invalid) source location. 379198092Srdivacky */ 380252723SdimCINDEX_LINKAGE CXSourceLocation clang_getNullLocation(void); 381203955Srdivacky 382202879Srdivacky/** 383245431Sdim * \brief Determine whether two source locations, which must refer into 384203955Srdivacky * the same translation unit, refer to exactly the same point in the source 385202879Srdivacky * code. 386202879Srdivacky * 387202879Srdivacky * \returns non-zero if the source locations refer to the same location, zero 388202879Srdivacky * if they refer to different locations. 389202879Srdivacky */ 390202879SrdivackyCINDEX_LINKAGE unsigned clang_equalLocations(CXSourceLocation loc1, 391202879Srdivacky CXSourceLocation loc2); 392203955Srdivacky 393202879Srdivacky/** 394203955Srdivacky * \brief Retrieves the source location associated with a given file/line/column 395203955Srdivacky * in a particular translation unit. 396202879Srdivacky */ 397202879SrdivackyCINDEX_LINKAGE CXSourceLocation clang_getLocation(CXTranslationUnit tu, 398202879Srdivacky CXFile file, 399202879Srdivacky unsigned line, 400202879Srdivacky unsigned column); 401218893Sdim/** 402218893Sdim * \brief Retrieves the source location associated with a given character offset 403218893Sdim * in a particular translation unit. 404218893Sdim */ 405218893SdimCINDEX_LINKAGE CXSourceLocation clang_getLocationForOffset(CXTranslationUnit tu, 406218893Sdim CXFile file, 407218893Sdim unsigned offset); 408203955Srdivacky 409203955Srdivacky/** 410252723Sdim * \brief Returns non-zero if the given source location is in a system header. 411252723Sdim */ 412252723SdimCINDEX_LINKAGE int clang_Location_isInSystemHeader(CXSourceLocation location); 413252723Sdim 414252723Sdim/** 415263509Sdim * \brief Returns non-zero if the given source location is in the main file of 416263509Sdim * the corresponding translation unit. 417263509Sdim */ 418263509SdimCINDEX_LINKAGE int clang_Location_isFromMainFile(CXSourceLocation location); 419263509Sdim 420263509Sdim/** 421203955Srdivacky * \brief Retrieve a NULL (invalid) source range. 422203955Srdivacky */ 423252723SdimCINDEX_LINKAGE CXSourceRange clang_getNullRange(void); 424205219Srdivacky 425202879Srdivacky/** 426202879Srdivacky * \brief Retrieve a source range given the beginning and ending source 427202879Srdivacky * locations. 428202879Srdivacky */ 429202879SrdivackyCINDEX_LINKAGE CXSourceRange clang_getRange(CXSourceLocation begin, 430202879Srdivacky CXSourceLocation end); 431203955Srdivacky 432202879Srdivacky/** 433226890Sdim * \brief Determine whether two ranges are equivalent. 434226890Sdim * 435226890Sdim * \returns non-zero if the ranges are the same, zero if they differ. 436226890Sdim */ 437226890SdimCINDEX_LINKAGE unsigned clang_equalRanges(CXSourceRange range1, 438226890Sdim CXSourceRange range2); 439226890Sdim 440226890Sdim/** 441245431Sdim * \brief Returns non-zero if \p range is null. 442226890Sdim */ 443226890SdimCINDEX_LINKAGE int clang_Range_isNull(CXSourceRange range); 444226890Sdim 445226890Sdim/** 446203955Srdivacky * \brief Retrieve the file, line, column, and offset represented by 447203955Srdivacky * the given source location. 448202879Srdivacky * 449226890Sdim * If the location refers into a macro expansion, retrieves the 450226890Sdim * location of the macro expansion. 451218893Sdim * 452203955Srdivacky * \param location the location within a source file that will be decomposed 453203955Srdivacky * into its parts. 454202879Srdivacky * 455203955Srdivacky * \param file [out] if non-NULL, will be set to the file to which the given 456202879Srdivacky * source location points. 457202879Srdivacky * 458203955Srdivacky * \param line [out] if non-NULL, will be set to the line to which the given 459202879Srdivacky * source location points. 460202879Srdivacky * 461203955Srdivacky * \param column [out] if non-NULL, will be set to the column to which the given 462203955Srdivacky * source location points. 463203955Srdivacky * 464203955Srdivacky * \param offset [out] if non-NULL, will be set to the offset into the 465203955Srdivacky * buffer to which the given source location points. 466202879Srdivacky */ 467226890SdimCINDEX_LINKAGE void clang_getExpansionLocation(CXSourceLocation location, 468226890Sdim CXFile *file, 469226890Sdim unsigned *line, 470226890Sdim unsigned *column, 471226890Sdim unsigned *offset); 472226890Sdim 473226890Sdim/** 474226890Sdim * \brief Retrieve the file, line, column, and offset represented by 475226890Sdim * the given source location, as specified in a # line directive. 476226890Sdim * 477226890Sdim * Example: given the following source code in a file somefile.c 478226890Sdim * 479245431Sdim * \code 480226890Sdim * #123 "dummy.c" 1 481226890Sdim * 482226890Sdim * static int func(void) 483226890Sdim * { 484226890Sdim * return 0; 485226890Sdim * } 486245431Sdim * \endcode 487226890Sdim * 488226890Sdim * the location information returned by this function would be 489226890Sdim * 490226890Sdim * File: dummy.c Line: 124 Column: 12 491226890Sdim * 492226890Sdim * whereas clang_getExpansionLocation would have returned 493226890Sdim * 494226890Sdim * File: somefile.c Line: 3 Column: 12 495226890Sdim * 496226890Sdim * \param location the location within a source file that will be decomposed 497226890Sdim * into its parts. 498226890Sdim * 499226890Sdim * \param filename [out] if non-NULL, will be set to the filename of the 500226890Sdim * source location. Note that filenames returned will be for "virtual" files, 501226890Sdim * which don't necessarily exist on the machine running clang - e.g. when 502226890Sdim * parsing preprocessed output obtained from a different environment. If 503226890Sdim * a non-NULL value is passed in, remember to dispose of the returned value 504226890Sdim * using \c clang_disposeString() once you've finished with it. For an invalid 505226890Sdim * source location, an empty string is returned. 506226890Sdim * 507226890Sdim * \param line [out] if non-NULL, will be set to the line number of the 508226890Sdim * source location. For an invalid source location, zero is returned. 509226890Sdim * 510226890Sdim * \param column [out] if non-NULL, will be set to the column number of the 511226890Sdim * source location. For an invalid source location, zero is returned. 512226890Sdim */ 513226890SdimCINDEX_LINKAGE void clang_getPresumedLocation(CXSourceLocation location, 514226890Sdim CXString *filename, 515226890Sdim unsigned *line, 516226890Sdim unsigned *column); 517226890Sdim 518226890Sdim/** 519226890Sdim * \brief Legacy API to retrieve the file, line, column, and offset represented 520226890Sdim * by the given source location. 521226890Sdim * 522226890Sdim * This interface has been replaced by the newer interface 523245431Sdim * #clang_getExpansionLocation(). See that interface's documentation for 524226890Sdim * details. 525226890Sdim */ 526202879SrdivackyCINDEX_LINKAGE void clang_getInstantiationLocation(CXSourceLocation location, 527202879Srdivacky CXFile *file, 528202879Srdivacky unsigned *line, 529203955Srdivacky unsigned *column, 530203955Srdivacky unsigned *offset); 531202379Srdivacky 532202879Srdivacky/** 533218893Sdim * \brief Retrieve the file, line, column, and offset represented by 534218893Sdim * the given source location. 535218893Sdim * 536218893Sdim * If the location refers into a macro instantiation, return where the 537218893Sdim * location was originally spelled in the source file. 538218893Sdim * 539218893Sdim * \param location the location within a source file that will be decomposed 540218893Sdim * into its parts. 541218893Sdim * 542218893Sdim * \param file [out] if non-NULL, will be set to the file to which the given 543218893Sdim * source location points. 544218893Sdim * 545218893Sdim * \param line [out] if non-NULL, will be set to the line to which the given 546218893Sdim * source location points. 547218893Sdim * 548218893Sdim * \param column [out] if non-NULL, will be set to the column to which the given 549218893Sdim * source location points. 550218893Sdim * 551218893Sdim * \param offset [out] if non-NULL, will be set to the offset into the 552218893Sdim * buffer to which the given source location points. 553218893Sdim */ 554218893SdimCINDEX_LINKAGE void clang_getSpellingLocation(CXSourceLocation location, 555218893Sdim CXFile *file, 556218893Sdim unsigned *line, 557218893Sdim unsigned *column, 558218893Sdim unsigned *offset); 559218893Sdim 560218893Sdim/** 561252723Sdim * \brief Retrieve the file, line, column, and offset represented by 562252723Sdim * the given source location. 563252723Sdim * 564252723Sdim * If the location refers into a macro expansion, return where the macro was 565252723Sdim * expanded or where the macro argument was written, if the location points at 566252723Sdim * a macro argument. 567252723Sdim * 568252723Sdim * \param location the location within a source file that will be decomposed 569252723Sdim * into its parts. 570252723Sdim * 571252723Sdim * \param file [out] if non-NULL, will be set to the file to which the given 572252723Sdim * source location points. 573252723Sdim * 574252723Sdim * \param line [out] if non-NULL, will be set to the line to which the given 575252723Sdim * source location points. 576252723Sdim * 577252723Sdim * \param column [out] if non-NULL, will be set to the column to which the given 578252723Sdim * source location points. 579252723Sdim * 580252723Sdim * \param offset [out] if non-NULL, will be set to the offset into the 581252723Sdim * buffer to which the given source location points. 582252723Sdim */ 583252723SdimCINDEX_LINKAGE void clang_getFileLocation(CXSourceLocation location, 584252723Sdim CXFile *file, 585252723Sdim unsigned *line, 586252723Sdim unsigned *column, 587252723Sdim unsigned *offset); 588252723Sdim 589252723Sdim/** 590203955Srdivacky * \brief Retrieve a source location representing the first character within a 591203955Srdivacky * source range. 592198092Srdivacky */ 593202879SrdivackyCINDEX_LINKAGE CXSourceLocation clang_getRangeStart(CXSourceRange range); 594198092Srdivacky 595202879Srdivacky/** 596203955Srdivacky * \brief Retrieve a source location representing the last character within a 597203955Srdivacky * source range. 598202879Srdivacky */ 599202879SrdivackyCINDEX_LINKAGE CXSourceLocation clang_getRangeEnd(CXSourceRange range); 600202379Srdivacky 601202879Srdivacky/** 602202879Srdivacky * @} 603202879Srdivacky */ 604202379Srdivacky 605202879Srdivacky/** 606203955Srdivacky * \defgroup CINDEX_DIAG Diagnostic reporting 607203955Srdivacky * 608203955Srdivacky * @{ 609203955Srdivacky */ 610203955Srdivacky 611203955Srdivacky/** 612203955Srdivacky * \brief Describes the severity of a particular diagnostic. 613203955Srdivacky */ 614203955Srdivackyenum CXDiagnosticSeverity { 615203955Srdivacky /** 616205219Srdivacky * \brief A diagnostic that has been suppressed, e.g., by a command-line 617203955Srdivacky * option. 618203955Srdivacky */ 619203955Srdivacky CXDiagnostic_Ignored = 0, 620205219Srdivacky 621203955Srdivacky /** 622203955Srdivacky * \brief This diagnostic is a note that should be attached to the 623203955Srdivacky * previous (non-note) diagnostic. 624203955Srdivacky */ 625203955Srdivacky CXDiagnostic_Note = 1, 626203955Srdivacky 627203955Srdivacky /** 628203955Srdivacky * \brief This diagnostic indicates suspicious code that may not be 629203955Srdivacky * wrong. 630203955Srdivacky */ 631203955Srdivacky CXDiagnostic_Warning = 2, 632203955Srdivacky 633203955Srdivacky /** 634203955Srdivacky * \brief This diagnostic indicates that the code is ill-formed. 635203955Srdivacky */ 636203955Srdivacky CXDiagnostic_Error = 3, 637203955Srdivacky 638203955Srdivacky /** 639203955Srdivacky * \brief This diagnostic indicates that the code is ill-formed such 640203955Srdivacky * that future parser recovery is unlikely to produce useful 641203955Srdivacky * results. 642203955Srdivacky */ 643203955Srdivacky CXDiagnostic_Fatal = 4 644203955Srdivacky}; 645203955Srdivacky 646203955Srdivacky/** 647204643Srdivacky * \brief A single diagnostic, containing the diagnostic's severity, 648204643Srdivacky * location, text, source ranges, and fix-it hints. 649203955Srdivacky */ 650204643Srdivackytypedef void *CXDiagnostic; 651204643Srdivacky 652204643Srdivacky/** 653235633Sdim * \brief A group of CXDiagnostics. 654235633Sdim */ 655235633Sdimtypedef void *CXDiagnosticSet; 656235633Sdim 657235633Sdim/** 658235633Sdim * \brief Determine the number of diagnostics in a CXDiagnosticSet. 659235633Sdim */ 660235633SdimCINDEX_LINKAGE unsigned clang_getNumDiagnosticsInSet(CXDiagnosticSet Diags); 661235633Sdim 662235633Sdim/** 663235633Sdim * \brief Retrieve a diagnostic associated with the given CXDiagnosticSet. 664235633Sdim * 665245431Sdim * \param Diags the CXDiagnosticSet to query. 666235633Sdim * \param Index the zero-based diagnostic number to retrieve. 667235633Sdim * 668235633Sdim * \returns the requested diagnostic. This diagnostic must be freed 669235633Sdim * via a call to \c clang_disposeDiagnostic(). 670235633Sdim */ 671235633SdimCINDEX_LINKAGE CXDiagnostic clang_getDiagnosticInSet(CXDiagnosticSet Diags, 672235633Sdim unsigned Index); 673235633Sdim 674235633Sdim 675235633Sdim/** 676235633Sdim * \brief Describes the kind of error that occurred (if any) in a call to 677235633Sdim * \c clang_loadDiagnostics. 678235633Sdim */ 679235633Sdimenum CXLoadDiag_Error { 680235633Sdim /** 681235633Sdim * \brief Indicates that no error occurred. 682235633Sdim */ 683235633Sdim CXLoadDiag_None = 0, 684235633Sdim 685235633Sdim /** 686235633Sdim * \brief Indicates that an unknown error occurred while attempting to 687235633Sdim * deserialize diagnostics. 688235633Sdim */ 689235633Sdim CXLoadDiag_Unknown = 1, 690235633Sdim 691235633Sdim /** 692235633Sdim * \brief Indicates that the file containing the serialized diagnostics 693235633Sdim * could not be opened. 694235633Sdim */ 695235633Sdim CXLoadDiag_CannotLoad = 2, 696235633Sdim 697235633Sdim /** 698235633Sdim * \brief Indicates that the serialized diagnostics file is invalid or 699245431Sdim * corrupt. 700235633Sdim */ 701235633Sdim CXLoadDiag_InvalidFile = 3 702235633Sdim}; 703235633Sdim 704235633Sdim/** 705235633Sdim * \brief Deserialize a set of diagnostics from a Clang diagnostics bitcode 706245431Sdim * file. 707235633Sdim * 708245431Sdim * \param file The name of the file to deserialize. 709245431Sdim * \param error A pointer to a enum value recording if there was a problem 710235633Sdim * deserializing the diagnostics. 711245431Sdim * \param errorString A pointer to a CXString for recording the error string 712235633Sdim * if the file was not successfully loaded. 713235633Sdim * 714235633Sdim * \returns A loaded CXDiagnosticSet if successful, and NULL otherwise. These 715245431Sdim * diagnostics should be released using clang_disposeDiagnosticSet(). 716235633Sdim */ 717235633SdimCINDEX_LINKAGE CXDiagnosticSet clang_loadDiagnostics(const char *file, 718235633Sdim enum CXLoadDiag_Error *error, 719235633Sdim CXString *errorString); 720235633Sdim 721235633Sdim/** 722235633Sdim * \brief Release a CXDiagnosticSet and all of its contained diagnostics. 723235633Sdim */ 724235633SdimCINDEX_LINKAGE void clang_disposeDiagnosticSet(CXDiagnosticSet Diags); 725235633Sdim 726235633Sdim/** 727245431Sdim * \brief Retrieve the child diagnostics of a CXDiagnostic. 728245431Sdim * 729245431Sdim * This CXDiagnosticSet does not need to be released by 730263509Sdim * clang_disposeDiagnosticSet. 731235633Sdim */ 732235633SdimCINDEX_LINKAGE CXDiagnosticSet clang_getChildDiagnostics(CXDiagnostic D); 733235633Sdim 734235633Sdim/** 735204643Srdivacky * \brief Determine the number of diagnostics produced for the given 736204643Srdivacky * translation unit. 737204643Srdivacky */ 738204643SrdivackyCINDEX_LINKAGE unsigned clang_getNumDiagnostics(CXTranslationUnit Unit); 739204643Srdivacky 740204643Srdivacky/** 741204643Srdivacky * \brief Retrieve a diagnostic associated with the given translation unit. 742204643Srdivacky * 743204643Srdivacky * \param Unit the translation unit to query. 744204643Srdivacky * \param Index the zero-based diagnostic number to retrieve. 745204643Srdivacky * 746204643Srdivacky * \returns the requested diagnostic. This diagnostic must be freed 747204643Srdivacky * via a call to \c clang_disposeDiagnostic(). 748204643Srdivacky */ 749204643SrdivackyCINDEX_LINKAGE CXDiagnostic clang_getDiagnostic(CXTranslationUnit Unit, 750204643Srdivacky unsigned Index); 751204643Srdivacky 752204643Srdivacky/** 753235633Sdim * \brief Retrieve the complete set of diagnostics associated with a 754235633Sdim * translation unit. 755235633Sdim * 756235633Sdim * \param Unit the translation unit to query. 757235633Sdim */ 758235633SdimCINDEX_LINKAGE CXDiagnosticSet 759235633Sdim clang_getDiagnosticSetFromTU(CXTranslationUnit Unit); 760235633Sdim 761235633Sdim/** 762204643Srdivacky * \brief Destroy a diagnostic. 763204643Srdivacky */ 764204643SrdivackyCINDEX_LINKAGE void clang_disposeDiagnostic(CXDiagnostic Diagnostic); 765204643Srdivacky 766204643Srdivacky/** 767204643Srdivacky * \brief Options to control the display of diagnostics. 768204643Srdivacky * 769204643Srdivacky * The values in this enum are meant to be combined to customize the 770263509Sdim * behavior of \c clang_formatDiagnostic(). 771204643Srdivacky */ 772204643Srdivackyenum CXDiagnosticDisplayOptions { 773203955Srdivacky /** 774204643Srdivacky * \brief Display the source-location information where the 775204643Srdivacky * diagnostic was located. 776204643Srdivacky * 777204643Srdivacky * When set, diagnostics will be prefixed by the file, line, and 778204643Srdivacky * (optionally) column to which the diagnostic refers. For example, 779204643Srdivacky * 780204643Srdivacky * \code 781204643Srdivacky * test.c:28: warning: extra tokens at end of #endif directive 782204643Srdivacky * \endcode 783204643Srdivacky * 784204643Srdivacky * This option corresponds to the clang flag \c -fshow-source-location. 785203955Srdivacky */ 786204643Srdivacky CXDiagnostic_DisplaySourceLocation = 0x01, 787203955Srdivacky 788203955Srdivacky /** 789204643Srdivacky * \brief If displaying the source-location information of the 790204643Srdivacky * diagnostic, also include the column number. 791204643Srdivacky * 792204643Srdivacky * This option corresponds to the clang flag \c -fshow-column. 793203955Srdivacky */ 794204643Srdivacky CXDiagnostic_DisplayColumn = 0x02, 795203955Srdivacky 796203955Srdivacky /** 797204643Srdivacky * \brief If displaying the source-location information of the 798204643Srdivacky * diagnostic, also include information about source ranges in a 799204643Srdivacky * machine-parsable format. 800204643Srdivacky * 801205219Srdivacky * This option corresponds to the clang flag 802204643Srdivacky * \c -fdiagnostics-print-source-range-info. 803203955Srdivacky */ 804218893Sdim CXDiagnostic_DisplaySourceRanges = 0x04, 805218893Sdim 806218893Sdim /** 807218893Sdim * \brief Display the option name associated with this diagnostic, if any. 808218893Sdim * 809218893Sdim * The option name displayed (e.g., -Wconversion) will be placed in brackets 810218893Sdim * after the diagnostic text. This option corresponds to the clang flag 811218893Sdim * \c -fdiagnostics-show-option. 812218893Sdim */ 813218893Sdim CXDiagnostic_DisplayOption = 0x08, 814218893Sdim 815218893Sdim /** 816218893Sdim * \brief Display the category number associated with this diagnostic, if any. 817218893Sdim * 818218893Sdim * The category number is displayed within brackets after the diagnostic text. 819218893Sdim * This option corresponds to the clang flag 820218893Sdim * \c -fdiagnostics-show-category=id. 821218893Sdim */ 822218893Sdim CXDiagnostic_DisplayCategoryId = 0x10, 823218893Sdim 824218893Sdim /** 825218893Sdim * \brief Display the category name associated with this diagnostic, if any. 826218893Sdim * 827218893Sdim * The category name is displayed within brackets after the diagnostic text. 828218893Sdim * This option corresponds to the clang flag 829218893Sdim * \c -fdiagnostics-show-category=name. 830218893Sdim */ 831218893Sdim CXDiagnostic_DisplayCategoryName = 0x20 832203955Srdivacky}; 833203955Srdivacky 834203955Srdivacky/** 835204643Srdivacky * \brief Format the given diagnostic in a manner that is suitable for display. 836204643Srdivacky * 837204643Srdivacky * This routine will format the given diagnostic to a string, rendering 838205219Srdivacky * the diagnostic according to the various options given. The 839205219Srdivacky * \c clang_defaultDiagnosticDisplayOptions() function returns the set of 840204643Srdivacky * options that most closely mimics the behavior of the clang compiler. 841204643Srdivacky * 842204643Srdivacky * \param Diagnostic The diagnostic to print. 843204643Srdivacky * 844205219Srdivacky * \param Options A set of options that control the diagnostic display, 845204643Srdivacky * created by combining \c CXDiagnosticDisplayOptions values. 846204643Srdivacky * 847204643Srdivacky * \returns A new string containing for formatted diagnostic. 848203955Srdivacky */ 849204643SrdivackyCINDEX_LINKAGE CXString clang_formatDiagnostic(CXDiagnostic Diagnostic, 850204643Srdivacky unsigned Options); 851203955Srdivacky 852203955Srdivacky/** 853204643Srdivacky * \brief Retrieve the set of display options most similar to the 854204643Srdivacky * default behavior of the clang compiler. 855203955Srdivacky * 856204643Srdivacky * \returns A set of display options suitable for use with \c 857263509Sdim * clang_formatDiagnostic(). 858203955Srdivacky */ 859204643SrdivackyCINDEX_LINKAGE unsigned clang_defaultDiagnosticDisplayOptions(void); 860203955Srdivacky 861203955Srdivacky/** 862203955Srdivacky * \brief Determine the severity of the given diagnostic. 863203955Srdivacky */ 864205219SrdivackyCINDEX_LINKAGE enum CXDiagnosticSeverity 865203955Srdivackyclang_getDiagnosticSeverity(CXDiagnostic); 866203955Srdivacky 867203955Srdivacky/** 868203955Srdivacky * \brief Retrieve the source location of the given diagnostic. 869203955Srdivacky * 870203955Srdivacky * This location is where Clang would print the caret ('^') when 871203955Srdivacky * displaying the diagnostic on the command line. 872203955Srdivacky */ 873203955SrdivackyCINDEX_LINKAGE CXSourceLocation clang_getDiagnosticLocation(CXDiagnostic); 874203955Srdivacky 875203955Srdivacky/** 876203955Srdivacky * \brief Retrieve the text of the given diagnostic. 877203955Srdivacky */ 878203955SrdivackyCINDEX_LINKAGE CXString clang_getDiagnosticSpelling(CXDiagnostic); 879203955Srdivacky 880203955Srdivacky/** 881218893Sdim * \brief Retrieve the name of the command-line option that enabled this 882218893Sdim * diagnostic. 883218893Sdim * 884218893Sdim * \param Diag The diagnostic to be queried. 885218893Sdim * 886218893Sdim * \param Disable If non-NULL, will be set to the option that disables this 887218893Sdim * diagnostic (if any). 888218893Sdim * 889218893Sdim * \returns A string that contains the command-line option used to enable this 890218893Sdim * warning, such as "-Wconversion" or "-pedantic". 891218893Sdim */ 892218893SdimCINDEX_LINKAGE CXString clang_getDiagnosticOption(CXDiagnostic Diag, 893218893Sdim CXString *Disable); 894218893Sdim 895218893Sdim/** 896218893Sdim * \brief Retrieve the category number for this diagnostic. 897218893Sdim * 898218893Sdim * Diagnostics can be categorized into groups along with other, related 899218893Sdim * diagnostics (e.g., diagnostics under the same warning flag). This routine 900218893Sdim * retrieves the category number for the given diagnostic. 901218893Sdim * 902218893Sdim * \returns The number of the category that contains this diagnostic, or zero 903218893Sdim * if this diagnostic is uncategorized. 904218893Sdim */ 905218893SdimCINDEX_LINKAGE unsigned clang_getDiagnosticCategory(CXDiagnostic); 906218893Sdim 907218893Sdim/** 908235633Sdim * \brief Retrieve the name of a particular diagnostic category. This 909235633Sdim * is now deprecated. Use clang_getDiagnosticCategoryText() 910235633Sdim * instead. 911218893Sdim * 912218893Sdim * \param Category A diagnostic category number, as returned by 913218893Sdim * \c clang_getDiagnosticCategory(). 914218893Sdim * 915218893Sdim * \returns The name of the given diagnostic category. 916218893Sdim */ 917235633SdimCINDEX_DEPRECATED CINDEX_LINKAGE 918235633SdimCXString clang_getDiagnosticCategoryName(unsigned Category); 919235633Sdim 920235633Sdim/** 921235633Sdim * \brief Retrieve the diagnostic category text for a given diagnostic. 922235633Sdim * 923235633Sdim * \returns The text of the given diagnostic category. 924235633Sdim */ 925235633SdimCINDEX_LINKAGE CXString clang_getDiagnosticCategoryText(CXDiagnostic); 926218893Sdim 927218893Sdim/** 928203955Srdivacky * \brief Determine the number of source ranges associated with the given 929203955Srdivacky * diagnostic. 930203955Srdivacky */ 931203955SrdivackyCINDEX_LINKAGE unsigned clang_getDiagnosticNumRanges(CXDiagnostic); 932205219Srdivacky 933203955Srdivacky/** 934203955Srdivacky * \brief Retrieve a source range associated with the diagnostic. 935203955Srdivacky * 936203955Srdivacky * A diagnostic's source ranges highlight important elements in the source 937203955Srdivacky * code. On the command line, Clang displays source ranges by 938205219Srdivacky * underlining them with '~' characters. 939203955Srdivacky * 940203955Srdivacky * \param Diagnostic the diagnostic whose range is being extracted. 941203955Srdivacky * 942205219Srdivacky * \param Range the zero-based index specifying which range to 943203955Srdivacky * 944203955Srdivacky * \returns the requested source range. 945203955Srdivacky */ 946205219SrdivackyCINDEX_LINKAGE CXSourceRange clang_getDiagnosticRange(CXDiagnostic Diagnostic, 947203955Srdivacky unsigned Range); 948203955Srdivacky 949203955Srdivacky/** 950203955Srdivacky * \brief Determine the number of fix-it hints associated with the 951203955Srdivacky * given diagnostic. 952203955Srdivacky */ 953203955SrdivackyCINDEX_LINKAGE unsigned clang_getDiagnosticNumFixIts(CXDiagnostic Diagnostic); 954203955Srdivacky 955203955Srdivacky/** 956204643Srdivacky * \brief Retrieve the replacement information for a given fix-it. 957203955Srdivacky * 958204643Srdivacky * Fix-its are described in terms of a source range whose contents 959204643Srdivacky * should be replaced by a string. This approach generalizes over 960204643Srdivacky * three kinds of operations: removal of source code (the range covers 961204643Srdivacky * the code to be removed and the replacement string is empty), 962204643Srdivacky * replacement of source code (the range covers the code to be 963204643Srdivacky * replaced and the replacement string provides the new code), and 964204643Srdivacky * insertion (both the start and end of the range point at the 965204643Srdivacky * insertion location, and the replacement string provides the text to 966204643Srdivacky * insert). 967203955Srdivacky * 968204643Srdivacky * \param Diagnostic The diagnostic whose fix-its are being queried. 969203955Srdivacky * 970204643Srdivacky * \param FixIt The zero-based index of the fix-it. 971203955Srdivacky * 972204643Srdivacky * \param ReplacementRange The source range whose contents will be 973204643Srdivacky * replaced with the returned replacement string. Note that source 974204643Srdivacky * ranges are half-open ranges [a, b), so the source code should be 975204643Srdivacky * replaced from a and up to (but not including) b. 976203955Srdivacky * 977204643Srdivacky * \returns A string containing text that should be replace the source 978204643Srdivacky * code indicated by the \c ReplacementRange. 979203955Srdivacky */ 980205219SrdivackyCINDEX_LINKAGE CXString clang_getDiagnosticFixIt(CXDiagnostic Diagnostic, 981204643Srdivacky unsigned FixIt, 982204643Srdivacky CXSourceRange *ReplacementRange); 983203955Srdivacky 984203955Srdivacky/** 985203955Srdivacky * @} 986203955Srdivacky */ 987203955Srdivacky 988203955Srdivacky/** 989203955Srdivacky * \defgroup CINDEX_TRANSLATION_UNIT Translation unit manipulation 990203955Srdivacky * 991203955Srdivacky * The routines in this group provide the ability to create and destroy 992203955Srdivacky * translation units from files, either by parsing the contents of the files or 993203955Srdivacky * by reading in a serialized representation of a translation unit. 994203955Srdivacky * 995203955Srdivacky * @{ 996203955Srdivacky */ 997205219Srdivacky 998203955Srdivacky/** 999203955Srdivacky * \brief Get the original translation unit source file name. 1000203955Srdivacky */ 1001203955SrdivackyCINDEX_LINKAGE CXString 1002203955Srdivackyclang_getTranslationUnitSpelling(CXTranslationUnit CTUnit); 1003203955Srdivacky 1004203955Srdivacky/** 1005203955Srdivacky * \brief Return the CXTranslationUnit for a given source file and the provided 1006203955Srdivacky * command line arguments one would pass to the compiler. 1007203955Srdivacky * 1008203955Srdivacky * Note: The 'source_filename' argument is optional. If the caller provides a 1009203955Srdivacky * NULL pointer, the name of the source file is expected to reside in the 1010203955Srdivacky * specified command line arguments. 1011203955Srdivacky * 1012203955Srdivacky * Note: When encountered in 'clang_command_line_args', the following options 1013203955Srdivacky * are ignored: 1014203955Srdivacky * 1015203955Srdivacky * '-c' 1016203955Srdivacky * '-emit-ast' 1017203955Srdivacky * '-fsyntax-only' 1018245431Sdim * '-o \<output file>' (both '-o' and '\<output file>' are ignored) 1019203955Srdivacky * 1020218893Sdim * \param CIdx The index object with which the translation unit will be 1021218893Sdim * associated. 1022203955Srdivacky * 1023245431Sdim * \param source_filename The name of the source file to load, or NULL if the 1024218893Sdim * source file is included in \p clang_command_line_args. 1025203955Srdivacky * 1026218893Sdim * \param num_clang_command_line_args The number of command-line arguments in 1027218893Sdim * \p clang_command_line_args. 1028218893Sdim * 1029218893Sdim * \param clang_command_line_args The command-line arguments that would be 1030218893Sdim * passed to the \c clang executable if it were being invoked out-of-process. 1031218893Sdim * These command-line options will be parsed and will affect how the translation 1032218893Sdim * unit is parsed. Note that the following options are ignored: '-c', 1033245431Sdim * '-emit-ast', '-fsyntax-only' (which is the default), and '-o \<output file>'. 1034218893Sdim * 1035203955Srdivacky * \param num_unsaved_files the number of unsaved file entries in \p 1036203955Srdivacky * unsaved_files. 1037203955Srdivacky * 1038203955Srdivacky * \param unsaved_files the files that have not yet been saved to disk 1039203955Srdivacky * but may be required for code completion, including the contents of 1040207619Srdivacky * those files. The contents and name of these files (as specified by 1041207619Srdivacky * CXUnsavedFile) are copied when necessary, so the client only needs to 1042207619Srdivacky * guarantee their validity until the call to this function returns. 1043203955Srdivacky */ 1044203955SrdivackyCINDEX_LINKAGE CXTranslationUnit clang_createTranslationUnitFromSourceFile( 1045203955Srdivacky CXIndex CIdx, 1046203955Srdivacky const char *source_filename, 1047203955Srdivacky int num_clang_command_line_args, 1048212904Sdim const char * const *clang_command_line_args, 1049203955Srdivacky unsigned num_unsaved_files, 1050204643Srdivacky struct CXUnsavedFile *unsaved_files); 1051205219Srdivacky 1052203955Srdivacky/** 1053203955Srdivacky * \brief Create a translation unit from an AST file (-emit-ast). 1054203955Srdivacky */ 1055205219SrdivackyCINDEX_LINKAGE CXTranslationUnit clang_createTranslationUnit(CXIndex, 1056204643Srdivacky const char *ast_filename); 1057203955Srdivacky 1058203955Srdivacky/** 1059212904Sdim * \brief Flags that control the creation of translation units. 1060212904Sdim * 1061212904Sdim * The enumerators in this enumeration type are meant to be bitwise 1062212904Sdim * ORed together to specify which options should be used when 1063212904Sdim * constructing the translation unit. 1064212904Sdim */ 1065212904Sdimenum CXTranslationUnit_Flags { 1066212904Sdim /** 1067212904Sdim * \brief Used to indicate that no special translation-unit options are 1068212904Sdim * needed. 1069212904Sdim */ 1070212904Sdim CXTranslationUnit_None = 0x0, 1071212904Sdim 1072212904Sdim /** 1073212904Sdim * \brief Used to indicate that the parser should construct a "detailed" 1074212904Sdim * preprocessing record, including all macro definitions and instantiations. 1075212904Sdim * 1076212904Sdim * Constructing a detailed preprocessing record requires more memory 1077212904Sdim * and time to parse, since the information contained in the record 1078212904Sdim * is usually not retained. However, it can be useful for 1079212904Sdim * applications that require more detailed information about the 1080212904Sdim * behavior of the preprocessor. 1081212904Sdim */ 1082212904Sdim CXTranslationUnit_DetailedPreprocessingRecord = 0x01, 1083212904Sdim 1084212904Sdim /** 1085212904Sdim * \brief Used to indicate that the translation unit is incomplete. 1086212904Sdim * 1087212904Sdim * When a translation unit is considered "incomplete", semantic 1088212904Sdim * analysis that is typically performed at the end of the 1089212904Sdim * translation unit will be suppressed. For example, this suppresses 1090212904Sdim * the completion of tentative declarations in C and of 1091212904Sdim * instantiation of implicitly-instantiation function templates in 1092212904Sdim * C++. This option is typically used when parsing a header with the 1093212904Sdim * intent of producing a precompiled header. 1094212904Sdim */ 1095212904Sdim CXTranslationUnit_Incomplete = 0x02, 1096212904Sdim 1097212904Sdim /** 1098212904Sdim * \brief Used to indicate that the translation unit should be built with an 1099212904Sdim * implicit precompiled header for the preamble. 1100212904Sdim * 1101212904Sdim * An implicit precompiled header is used as an optimization when a 1102212904Sdim * particular translation unit is likely to be reparsed many times 1103212904Sdim * when the sources aren't changing that often. In this case, an 1104212904Sdim * implicit precompiled header will be built containing all of the 1105212904Sdim * initial includes at the top of the main file (what we refer to as 1106212904Sdim * the "preamble" of the file). In subsequent parses, if the 1107212904Sdim * preamble or the files in it have not changed, \c 1108212904Sdim * clang_reparseTranslationUnit() will re-use the implicit 1109212904Sdim * precompiled header to improve parsing performance. 1110212904Sdim */ 1111212904Sdim CXTranslationUnit_PrecompiledPreamble = 0x04, 1112212904Sdim 1113212904Sdim /** 1114212904Sdim * \brief Used to indicate that the translation unit should cache some 1115212904Sdim * code-completion results with each reparse of the source file. 1116212904Sdim * 1117212904Sdim * Caching of code-completion results is a performance optimization that 1118212904Sdim * introduces some overhead to reparsing but improves the performance of 1119212904Sdim * code-completion operations. 1120212904Sdim */ 1121218893Sdim CXTranslationUnit_CacheCompletionResults = 0x08, 1122245431Sdim 1123218893Sdim /** 1124245431Sdim * \brief Used to indicate that the translation unit will be serialized with 1125245431Sdim * \c clang_saveTranslationUnit. 1126218893Sdim * 1127245431Sdim * This option is typically used when parsing a header with the intent of 1128245431Sdim * producing a precompiled header. 1129218893Sdim */ 1130245431Sdim CXTranslationUnit_ForSerialization = 0x10, 1131218893Sdim 1132218893Sdim /** 1133226890Sdim * \brief DEPRECATED: Enabled chained precompiled preambles in C++. 1134218893Sdim * 1135218893Sdim * Note: this is a *temporary* option that is available only while 1136226890Sdim * we are testing C++ precompiled preamble support. It is deprecated. 1137218893Sdim */ 1138223017Sdim CXTranslationUnit_CXXChainedPCH = 0x20, 1139224145Sdim 1140224145Sdim /** 1141235633Sdim * \brief Used to indicate that function/method bodies should be skipped while 1142235633Sdim * parsing. 1143224145Sdim * 1144235633Sdim * This option can be used to search for declarations/definitions while 1145235633Sdim * ignoring the usages. 1146224145Sdim */ 1147245431Sdim CXTranslationUnit_SkipFunctionBodies = 0x40, 1148245431Sdim 1149245431Sdim /** 1150245431Sdim * \brief Used to indicate that brief documentation comments should be 1151245431Sdim * included into the set of code completions returned from this translation 1152245431Sdim * unit. 1153245431Sdim */ 1154245431Sdim CXTranslationUnit_IncludeBriefCommentsInCodeCompletion = 0x80 1155212904Sdim}; 1156212904Sdim 1157212904Sdim/** 1158212904Sdim * \brief Returns the set of flags that is suitable for parsing a translation 1159212904Sdim * unit that is being edited. 1160212904Sdim * 1161212904Sdim * The set of flags returned provide options for \c clang_parseTranslationUnit() 1162212904Sdim * to indicate that the translation unit is likely to be reparsed many times, 1163212904Sdim * either explicitly (via \c clang_reparseTranslationUnit()) or implicitly 1164212904Sdim * (e.g., by code completion (\c clang_codeCompletionAt())). The returned flag 1165212904Sdim * set contains an unspecified set of optimizations (e.g., the precompiled 1166212904Sdim * preamble) geared toward improving the performance of these routines. The 1167212904Sdim * set of optimizations enabled may change from one version to the next. 1168212904Sdim */ 1169212904SdimCINDEX_LINKAGE unsigned clang_defaultEditingTranslationUnitOptions(void); 1170212904Sdim 1171212904Sdim/** 1172212904Sdim * \brief Parse the given source file and the translation unit corresponding 1173212904Sdim * to that file. 1174212904Sdim * 1175212904Sdim * This routine is the main entry point for the Clang C API, providing the 1176212904Sdim * ability to parse a source file into a translation unit that can then be 1177212904Sdim * queried by other functions in the API. This routine accepts a set of 1178212904Sdim * command-line arguments so that the compilation can be configured in the same 1179212904Sdim * way that the compiler is configured on the command line. 1180212904Sdim * 1181212904Sdim * \param CIdx The index object with which the translation unit will be 1182212904Sdim * associated. 1183212904Sdim * 1184212904Sdim * \param source_filename The name of the source file to load, or NULL if the 1185218893Sdim * source file is included in \p command_line_args. 1186212904Sdim * 1187212904Sdim * \param command_line_args The command-line arguments that would be 1188212904Sdim * passed to the \c clang executable if it were being invoked out-of-process. 1189212904Sdim * These command-line options will be parsed and will affect how the translation 1190212904Sdim * unit is parsed. Note that the following options are ignored: '-c', 1191245431Sdim * '-emit-ast', '-fsyntax-only' (which is the default), and '-o \<output file>'. 1192212904Sdim * 1193212904Sdim * \param num_command_line_args The number of command-line arguments in 1194212904Sdim * \p command_line_args. 1195212904Sdim * 1196212904Sdim * \param unsaved_files the files that have not yet been saved to disk 1197212904Sdim * but may be required for parsing, including the contents of 1198212904Sdim * those files. The contents and name of these files (as specified by 1199212904Sdim * CXUnsavedFile) are copied when necessary, so the client only needs to 1200212904Sdim * guarantee their validity until the call to this function returns. 1201212904Sdim * 1202212904Sdim * \param num_unsaved_files the number of unsaved file entries in \p 1203212904Sdim * unsaved_files. 1204212904Sdim * 1205212904Sdim * \param options A bitmask of options that affects how the translation unit 1206212904Sdim * is managed but not its compilation. This should be a bitwise OR of the 1207212904Sdim * CXTranslationUnit_XXX flags. 1208212904Sdim * 1209212904Sdim * \returns A new translation unit describing the parsed code and containing 1210212904Sdim * any diagnostics produced by the compiler. If there is a failure from which 1211212904Sdim * the compiler cannot recover, returns NULL. 1212212904Sdim */ 1213212904SdimCINDEX_LINKAGE CXTranslationUnit clang_parseTranslationUnit(CXIndex CIdx, 1214212904Sdim const char *source_filename, 1215212904Sdim const char * const *command_line_args, 1216212904Sdim int num_command_line_args, 1217212904Sdim struct CXUnsavedFile *unsaved_files, 1218212904Sdim unsigned num_unsaved_files, 1219212904Sdim unsigned options); 1220212904Sdim 1221212904Sdim/** 1222212904Sdim * \brief Flags that control how translation units are saved. 1223212904Sdim * 1224212904Sdim * The enumerators in this enumeration type are meant to be bitwise 1225212904Sdim * ORed together to specify which options should be used when 1226212904Sdim * saving the translation unit. 1227212904Sdim */ 1228212904Sdimenum CXSaveTranslationUnit_Flags { 1229212904Sdim /** 1230212904Sdim * \brief Used to indicate that no special saving options are needed. 1231212904Sdim */ 1232212904Sdim CXSaveTranslationUnit_None = 0x0 1233212904Sdim}; 1234212904Sdim 1235212904Sdim/** 1236212904Sdim * \brief Returns the set of flags that is suitable for saving a translation 1237212904Sdim * unit. 1238212904Sdim * 1239212904Sdim * The set of flags returned provide options for 1240212904Sdim * \c clang_saveTranslationUnit() by default. The returned flag 1241212904Sdim * set contains an unspecified set of options that save translation units with 1242212904Sdim * the most commonly-requested data. 1243212904Sdim */ 1244212904SdimCINDEX_LINKAGE unsigned clang_defaultSaveOptions(CXTranslationUnit TU); 1245212904Sdim 1246212904Sdim/** 1247224145Sdim * \brief Describes the kind of error that occurred (if any) in a call to 1248224145Sdim * \c clang_saveTranslationUnit(). 1249224145Sdim */ 1250224145Sdimenum CXSaveError { 1251224145Sdim /** 1252224145Sdim * \brief Indicates that no error occurred while saving a translation unit. 1253224145Sdim */ 1254224145Sdim CXSaveError_None = 0, 1255224145Sdim 1256224145Sdim /** 1257224145Sdim * \brief Indicates that an unknown error occurred while attempting to save 1258224145Sdim * the file. 1259224145Sdim * 1260224145Sdim * This error typically indicates that file I/O failed when attempting to 1261224145Sdim * write the file. 1262224145Sdim */ 1263224145Sdim CXSaveError_Unknown = 1, 1264224145Sdim 1265224145Sdim /** 1266224145Sdim * \brief Indicates that errors during translation prevented this attempt 1267224145Sdim * to save the translation unit. 1268224145Sdim * 1269224145Sdim * Errors that prevent the translation unit from being saved can be 1270224145Sdim * extracted using \c clang_getNumDiagnostics() and \c clang_getDiagnostic(). 1271224145Sdim */ 1272224145Sdim CXSaveError_TranslationErrors = 2, 1273224145Sdim 1274224145Sdim /** 1275224145Sdim * \brief Indicates that the translation unit to be saved was somehow 1276224145Sdim * invalid (e.g., NULL). 1277224145Sdim */ 1278224145Sdim CXSaveError_InvalidTU = 3 1279224145Sdim}; 1280224145Sdim 1281224145Sdim/** 1282212904Sdim * \brief Saves a translation unit into a serialized representation of 1283212904Sdim * that translation unit on disk. 1284212904Sdim * 1285212904Sdim * Any translation unit that was parsed without error can be saved 1286212904Sdim * into a file. The translation unit can then be deserialized into a 1287212904Sdim * new \c CXTranslationUnit with \c clang_createTranslationUnit() or, 1288212904Sdim * if it is an incomplete translation unit that corresponds to a 1289212904Sdim * header, used as a precompiled header when parsing other translation 1290212904Sdim * units. 1291212904Sdim * 1292212904Sdim * \param TU The translation unit to save. 1293212904Sdim * 1294212904Sdim * \param FileName The file to which the translation unit will be saved. 1295212904Sdim * 1296212904Sdim * \param options A bitmask of options that affects how the translation unit 1297212904Sdim * is saved. This should be a bitwise OR of the 1298212904Sdim * CXSaveTranslationUnit_XXX flags. 1299212904Sdim * 1300224145Sdim * \returns A value that will match one of the enumerators of the CXSaveError 1301224145Sdim * enumeration. Zero (CXSaveError_None) indicates that the translation unit was 1302224145Sdim * saved successfully, while a non-zero value indicates that a problem occurred. 1303212904Sdim */ 1304212904SdimCINDEX_LINKAGE int clang_saveTranslationUnit(CXTranslationUnit TU, 1305212904Sdim const char *FileName, 1306212904Sdim unsigned options); 1307212904Sdim 1308212904Sdim/** 1309203955Srdivacky * \brief Destroy the specified CXTranslationUnit object. 1310203955Srdivacky */ 1311203955SrdivackyCINDEX_LINKAGE void clang_disposeTranslationUnit(CXTranslationUnit); 1312205219Srdivacky 1313203955Srdivacky/** 1314212904Sdim * \brief Flags that control the reparsing of translation units. 1315212904Sdim * 1316212904Sdim * The enumerators in this enumeration type are meant to be bitwise 1317212904Sdim * ORed together to specify which options should be used when 1318212904Sdim * reparsing the translation unit. 1319212904Sdim */ 1320212904Sdimenum CXReparse_Flags { 1321212904Sdim /** 1322212904Sdim * \brief Used to indicate that no special reparsing options are needed. 1323212904Sdim */ 1324212904Sdim CXReparse_None = 0x0 1325212904Sdim}; 1326212904Sdim 1327212904Sdim/** 1328212904Sdim * \brief Returns the set of flags that is suitable for reparsing a translation 1329212904Sdim * unit. 1330212904Sdim * 1331212904Sdim * The set of flags returned provide options for 1332212904Sdim * \c clang_reparseTranslationUnit() by default. The returned flag 1333212904Sdim * set contains an unspecified set of optimizations geared toward common uses 1334212904Sdim * of reparsing. The set of optimizations enabled may change from one version 1335212904Sdim * to the next. 1336212904Sdim */ 1337212904SdimCINDEX_LINKAGE unsigned clang_defaultReparseOptions(CXTranslationUnit TU); 1338212904Sdim 1339212904Sdim/** 1340212904Sdim * \brief Reparse the source files that produced this translation unit. 1341212904Sdim * 1342212904Sdim * This routine can be used to re-parse the source files that originally 1343212904Sdim * created the given translation unit, for example because those source files 1344212904Sdim * have changed (either on disk or as passed via \p unsaved_files). The 1345212904Sdim * source code will be reparsed with the same command-line options as it 1346212904Sdim * was originally parsed. 1347212904Sdim * 1348212904Sdim * Reparsing a translation unit invalidates all cursors and source locations 1349212904Sdim * that refer into that translation unit. This makes reparsing a translation 1350212904Sdim * unit semantically equivalent to destroying the translation unit and then 1351212904Sdim * creating a new translation unit with the same command-line arguments. 1352212904Sdim * However, it may be more efficient to reparse a translation 1353212904Sdim * unit using this routine. 1354212904Sdim * 1355212904Sdim * \param TU The translation unit whose contents will be re-parsed. The 1356212904Sdim * translation unit must originally have been built with 1357212904Sdim * \c clang_createTranslationUnitFromSourceFile(). 1358212904Sdim * 1359212904Sdim * \param num_unsaved_files The number of unsaved file entries in \p 1360212904Sdim * unsaved_files. 1361212904Sdim * 1362212904Sdim * \param unsaved_files The files that have not yet been saved to disk 1363212904Sdim * but may be required for parsing, including the contents of 1364212904Sdim * those files. The contents and name of these files (as specified by 1365212904Sdim * CXUnsavedFile) are copied when necessary, so the client only needs to 1366212904Sdim * guarantee their validity until the call to this function returns. 1367212904Sdim * 1368212904Sdim * \param options A bitset of options composed of the flags in CXReparse_Flags. 1369212904Sdim * The function \c clang_defaultReparseOptions() produces a default set of 1370212904Sdim * options recommended for most uses, based on the translation unit. 1371212904Sdim * 1372212904Sdim * \returns 0 if the sources could be reparsed. A non-zero value will be 1373212904Sdim * returned if reparsing was impossible, such that the translation unit is 1374212904Sdim * invalid. In such cases, the only valid call for \p TU is 1375212904Sdim * \c clang_disposeTranslationUnit(TU). 1376212904Sdim */ 1377212904SdimCINDEX_LINKAGE int clang_reparseTranslationUnit(CXTranslationUnit TU, 1378212904Sdim unsigned num_unsaved_files, 1379212904Sdim struct CXUnsavedFile *unsaved_files, 1380212904Sdim unsigned options); 1381221345Sdim 1382212904Sdim/** 1383221345Sdim * \brief Categorizes how memory is being used by a translation unit. 1384221345Sdim */ 1385221345Sdimenum CXTUResourceUsageKind { 1386221345Sdim CXTUResourceUsage_AST = 1, 1387221345Sdim CXTUResourceUsage_Identifiers = 2, 1388221345Sdim CXTUResourceUsage_Selectors = 3, 1389221345Sdim CXTUResourceUsage_GlobalCompletionResults = 4, 1390221345Sdim CXTUResourceUsage_SourceManagerContentCache = 5, 1391221345Sdim CXTUResourceUsage_AST_SideTables = 6, 1392221345Sdim CXTUResourceUsage_SourceManager_Membuffer_Malloc = 7, 1393221345Sdim CXTUResourceUsage_SourceManager_Membuffer_MMap = 8, 1394221345Sdim CXTUResourceUsage_ExternalASTSource_Membuffer_Malloc = 9, 1395221345Sdim CXTUResourceUsage_ExternalASTSource_Membuffer_MMap = 10, 1396223017Sdim CXTUResourceUsage_Preprocessor = 11, 1397223017Sdim CXTUResourceUsage_PreprocessingRecord = 12, 1398226890Sdim CXTUResourceUsage_SourceManager_DataStructures = 13, 1399226890Sdim CXTUResourceUsage_Preprocessor_HeaderSearch = 14, 1400221345Sdim CXTUResourceUsage_MEMORY_IN_BYTES_BEGIN = CXTUResourceUsage_AST, 1401221345Sdim CXTUResourceUsage_MEMORY_IN_BYTES_END = 1402226890Sdim CXTUResourceUsage_Preprocessor_HeaderSearch, 1403221345Sdim 1404221345Sdim CXTUResourceUsage_First = CXTUResourceUsage_AST, 1405226890Sdim CXTUResourceUsage_Last = CXTUResourceUsage_Preprocessor_HeaderSearch 1406221345Sdim}; 1407221345Sdim 1408221345Sdim/** 1409221345Sdim * \brief Returns the human-readable null-terminated C string that represents 1410221345Sdim * the name of the memory category. This string should never be freed. 1411221345Sdim */ 1412221345SdimCINDEX_LINKAGE 1413221345Sdimconst char *clang_getTUResourceUsageName(enum CXTUResourceUsageKind kind); 1414221345Sdim 1415221345Sdimtypedef struct CXTUResourceUsageEntry { 1416221345Sdim /* \brief The memory usage category. */ 1417221345Sdim enum CXTUResourceUsageKind kind; 1418221345Sdim /* \brief Amount of resources used. 1419221345Sdim The units will depend on the resource kind. */ 1420221345Sdim unsigned long amount; 1421221345Sdim} CXTUResourceUsageEntry; 1422221345Sdim 1423221345Sdim/** 1424221345Sdim * \brief The memory usage of a CXTranslationUnit, broken into categories. 1425221345Sdim */ 1426221345Sdimtypedef struct CXTUResourceUsage { 1427221345Sdim /* \brief Private data member, used for queries. */ 1428221345Sdim void *data; 1429221345Sdim 1430221345Sdim /* \brief The number of entries in the 'entries' array. */ 1431221345Sdim unsigned numEntries; 1432221345Sdim 1433221345Sdim /* \brief An array of key-value pairs, representing the breakdown of memory 1434221345Sdim usage. */ 1435221345Sdim CXTUResourceUsageEntry *entries; 1436221345Sdim 1437221345Sdim} CXTUResourceUsage; 1438221345Sdim 1439221345Sdim/** 1440221345Sdim * \brief Return the memory usage of a translation unit. This object 1441221345Sdim * should be released with clang_disposeCXTUResourceUsage(). 1442221345Sdim */ 1443221345SdimCINDEX_LINKAGE CXTUResourceUsage clang_getCXTUResourceUsage(CXTranslationUnit TU); 1444221345Sdim 1445221345SdimCINDEX_LINKAGE void clang_disposeCXTUResourceUsage(CXTUResourceUsage usage); 1446221345Sdim 1447221345Sdim/** 1448203955Srdivacky * @} 1449203955Srdivacky */ 1450205219Srdivacky 1451203955Srdivacky/** 1452202879Srdivacky * \brief Describes the kind of entity that a cursor refers to. 1453202379Srdivacky */ 1454202879Srdivackyenum CXCursorKind { 1455202879Srdivacky /* Declarations */ 1456203955Srdivacky /** 1457202879Srdivacky * \brief A declaration whose specific kind is not exposed via this 1458203955Srdivacky * interface. 1459202879Srdivacky * 1460202879Srdivacky * Unexposed declarations have the same operations as any other kind 1461202879Srdivacky * of declaration; one can extract their location information, 1462202879Srdivacky * spelling, find their definitions, etc. However, the specific kind 1463202879Srdivacky * of the declaration is not reported. 1464202879Srdivacky */ 1465202879Srdivacky CXCursor_UnexposedDecl = 1, 1466202879Srdivacky /** \brief A C or C++ struct. */ 1467203955Srdivacky CXCursor_StructDecl = 2, 1468202879Srdivacky /** \brief A C or C++ union. */ 1469202879Srdivacky CXCursor_UnionDecl = 3, 1470202879Srdivacky /** \brief A C++ class. */ 1471202879Srdivacky CXCursor_ClassDecl = 4, 1472202879Srdivacky /** \brief An enumeration. */ 1473202879Srdivacky CXCursor_EnumDecl = 5, 1474203955Srdivacky /** 1475202879Srdivacky * \brief A field (in C) or non-static data member (in C++) in a 1476202879Srdivacky * struct, union, or C++ class. 1477202879Srdivacky */ 1478202879Srdivacky CXCursor_FieldDecl = 6, 1479202879Srdivacky /** \brief An enumerator constant. */ 1480202879Srdivacky CXCursor_EnumConstantDecl = 7, 1481202879Srdivacky /** \brief A function. */ 1482202879Srdivacky CXCursor_FunctionDecl = 8, 1483202879Srdivacky /** \brief A variable. */ 1484202879Srdivacky CXCursor_VarDecl = 9, 1485202879Srdivacky /** \brief A function or method parameter. */ 1486202879Srdivacky CXCursor_ParmDecl = 10, 1487245431Sdim /** \brief An Objective-C \@interface. */ 1488202879Srdivacky CXCursor_ObjCInterfaceDecl = 11, 1489245431Sdim /** \brief An Objective-C \@interface for a category. */ 1490202879Srdivacky CXCursor_ObjCCategoryDecl = 12, 1491245431Sdim /** \brief An Objective-C \@protocol declaration. */ 1492202879Srdivacky CXCursor_ObjCProtocolDecl = 13, 1493245431Sdim /** \brief An Objective-C \@property declaration. */ 1494202879Srdivacky CXCursor_ObjCPropertyDecl = 14, 1495202879Srdivacky /** \brief An Objective-C instance variable. */ 1496202879Srdivacky CXCursor_ObjCIvarDecl = 15, 1497202879Srdivacky /** \brief An Objective-C instance method. */ 1498202879Srdivacky CXCursor_ObjCInstanceMethodDecl = 16, 1499202879Srdivacky /** \brief An Objective-C class method. */ 1500202879Srdivacky CXCursor_ObjCClassMethodDecl = 17, 1501245431Sdim /** \brief An Objective-C \@implementation. */ 1502202879Srdivacky CXCursor_ObjCImplementationDecl = 18, 1503245431Sdim /** \brief An Objective-C \@implementation for a category. */ 1504202879Srdivacky CXCursor_ObjCCategoryImplDecl = 19, 1505202879Srdivacky /** \brief A typedef */ 1506202879Srdivacky CXCursor_TypedefDecl = 20, 1507207619Srdivacky /** \brief A C++ class method. */ 1508207619Srdivacky CXCursor_CXXMethod = 21, 1509208600Srdivacky /** \brief A C++ namespace. */ 1510208600Srdivacky CXCursor_Namespace = 22, 1511208600Srdivacky /** \brief A linkage specification, e.g. 'extern "C"'. */ 1512208600Srdivacky CXCursor_LinkageSpec = 23, 1513212904Sdim /** \brief A C++ constructor. */ 1514212904Sdim CXCursor_Constructor = 24, 1515212904Sdim /** \brief A C++ destructor. */ 1516212904Sdim CXCursor_Destructor = 25, 1517212904Sdim /** \brief A C++ conversion function. */ 1518212904Sdim CXCursor_ConversionFunction = 26, 1519212904Sdim /** \brief A C++ template type parameter. */ 1520212904Sdim CXCursor_TemplateTypeParameter = 27, 1521212904Sdim /** \brief A C++ non-type template parameter. */ 1522212904Sdim CXCursor_NonTypeTemplateParameter = 28, 1523212904Sdim /** \brief A C++ template template parameter. */ 1524212904Sdim CXCursor_TemplateTemplateParameter = 29, 1525212904Sdim /** \brief A C++ function template. */ 1526212904Sdim CXCursor_FunctionTemplate = 30, 1527212904Sdim /** \brief A C++ class template. */ 1528212904Sdim CXCursor_ClassTemplate = 31, 1529212904Sdim /** \brief A C++ class template partial specialization. */ 1530212904Sdim CXCursor_ClassTemplatePartialSpecialization = 32, 1531212904Sdim /** \brief A C++ namespace alias declaration. */ 1532212904Sdim CXCursor_NamespaceAlias = 33, 1533212904Sdim /** \brief A C++ using directive. */ 1534212904Sdim CXCursor_UsingDirective = 34, 1535221345Sdim /** \brief A C++ using declaration. */ 1536212904Sdim CXCursor_UsingDeclaration = 35, 1537221345Sdim /** \brief A C++ alias declaration */ 1538221345Sdim CXCursor_TypeAliasDecl = 36, 1539245431Sdim /** \brief An Objective-C \@synthesize definition. */ 1540223017Sdim CXCursor_ObjCSynthesizeDecl = 37, 1541245431Sdim /** \brief An Objective-C \@dynamic definition. */ 1542223017Sdim CXCursor_ObjCDynamicDecl = 38, 1543226890Sdim /** \brief An access specifier. */ 1544226890Sdim CXCursor_CXXAccessSpecifier = 39, 1545226890Sdim 1546208600Srdivacky CXCursor_FirstDecl = CXCursor_UnexposedDecl, 1547226890Sdim CXCursor_LastDecl = CXCursor_CXXAccessSpecifier, 1548207619Srdivacky 1549202879Srdivacky /* References */ 1550202879Srdivacky CXCursor_FirstRef = 40, /* Decl references */ 1551203955Srdivacky CXCursor_ObjCSuperClassRef = 40, 1552202879Srdivacky CXCursor_ObjCProtocolRef = 41, 1553202879Srdivacky CXCursor_ObjCClassRef = 42, 1554202879Srdivacky /** 1555202879Srdivacky * \brief A reference to a type declaration. 1556202879Srdivacky * 1557202879Srdivacky * A type reference occurs anywhere where a type is named but not 1558202879Srdivacky * declared. For example, given: 1559202879Srdivacky * 1560202879Srdivacky * \code 1561202879Srdivacky * typedef unsigned size_type; 1562202879Srdivacky * size_type size; 1563202879Srdivacky * \endcode 1564202879Srdivacky * 1565202879Srdivacky * The typedef is a declaration of size_type (CXCursor_TypedefDecl), 1566202879Srdivacky * while the type of the variable "size" is referenced. The cursor 1567202879Srdivacky * referenced by the type of size is the typedef for size_type. 1568202879Srdivacky */ 1569202879Srdivacky CXCursor_TypeRef = 43, 1570212904Sdim CXCursor_CXXBaseSpecifier = 44, 1571212904Sdim /** 1572218893Sdim * \brief A reference to a class template, function template, template 1573218893Sdim * template parameter, or class template partial specialization. 1574212904Sdim */ 1575212904Sdim CXCursor_TemplateRef = 45, 1576212904Sdim /** 1577212904Sdim * \brief A reference to a namespace or namespace alias. 1578212904Sdim */ 1579212904Sdim CXCursor_NamespaceRef = 46, 1580218893Sdim /** 1581218893Sdim * \brief A reference to a member of a struct, union, or class that occurs in 1582218893Sdim * some non-expression context, e.g., a designated initializer. 1583218893Sdim */ 1584218893Sdim CXCursor_MemberRef = 47, 1585218893Sdim /** 1586218893Sdim * \brief A reference to a labeled statement. 1587218893Sdim * 1588218893Sdim * This cursor kind is used to describe the jump to "start_over" in the 1589218893Sdim * goto statement in the following example: 1590218893Sdim * 1591218893Sdim * \code 1592218893Sdim * start_over: 1593218893Sdim * ++counter; 1594218893Sdim * 1595218893Sdim * goto start_over; 1596218893Sdim * \endcode 1597218893Sdim * 1598218893Sdim * A label reference cursor refers to a label statement. 1599218893Sdim */ 1600218893Sdim CXCursor_LabelRef = 48, 1601218893Sdim 1602218893Sdim /** 1603218893Sdim * \brief A reference to a set of overloaded functions or function templates 1604218893Sdim * that has not yet been resolved to a specific function or function template. 1605218893Sdim * 1606218893Sdim * An overloaded declaration reference cursor occurs in C++ templates where 1607218893Sdim * a dependent name refers to a function. For example: 1608218893Sdim * 1609218893Sdim * \code 1610218893Sdim * template<typename T> void swap(T&, T&); 1611218893Sdim * 1612218893Sdim * struct X { ... }; 1613218893Sdim * void swap(X&, X&); 1614218893Sdim * 1615218893Sdim * template<typename T> 1616218893Sdim * void reverse(T* first, T* last) { 1617218893Sdim * while (first < last - 1) { 1618218893Sdim * swap(*first, *--last); 1619218893Sdim * ++first; 1620218893Sdim * } 1621218893Sdim * } 1622218893Sdim * 1623218893Sdim * struct Y { }; 1624218893Sdim * void swap(Y&, Y&); 1625218893Sdim * \endcode 1626218893Sdim * 1627218893Sdim * Here, the identifier "swap" is associated with an overloaded declaration 1628218893Sdim * reference. In the template definition, "swap" refers to either of the two 1629218893Sdim * "swap" functions declared above, so both results will be available. At 1630218893Sdim * instantiation time, "swap" may also refer to other functions found via 1631218893Sdim * argument-dependent lookup (e.g., the "swap" function at the end of the 1632218893Sdim * example). 1633218893Sdim * 1634218893Sdim * The functions \c clang_getNumOverloadedDecls() and 1635218893Sdim * \c clang_getOverloadedDecl() can be used to retrieve the definitions 1636218893Sdim * referenced by this cursor. 1637218893Sdim */ 1638218893Sdim CXCursor_OverloadedDeclRef = 49, 1639218893Sdim 1640235633Sdim /** 1641235633Sdim * \brief A reference to a variable that occurs in some non-expression 1642235633Sdim * context, e.g., a C++ lambda capture list. 1643235633Sdim */ 1644235633Sdim CXCursor_VariableRef = 50, 1645235633Sdim 1646235633Sdim CXCursor_LastRef = CXCursor_VariableRef, 1647203955Srdivacky 1648202879Srdivacky /* Error conditions */ 1649202879Srdivacky CXCursor_FirstInvalid = 70, 1650202879Srdivacky CXCursor_InvalidFile = 70, 1651202879Srdivacky CXCursor_NoDeclFound = 71, 1652202879Srdivacky CXCursor_NotImplemented = 72, 1653205408Srdivacky CXCursor_InvalidCode = 73, 1654205408Srdivacky CXCursor_LastInvalid = CXCursor_InvalidCode, 1655203955Srdivacky 1656202879Srdivacky /* Expressions */ 1657202879Srdivacky CXCursor_FirstExpr = 100, 1658203955Srdivacky 1659202879Srdivacky /** 1660202879Srdivacky * \brief An expression whose specific kind is not exposed via this 1661203955Srdivacky * interface. 1662202879Srdivacky * 1663202879Srdivacky * Unexposed expressions have the same operations as any other kind 1664202879Srdivacky * of expression; one can extract their location information, 1665202879Srdivacky * spelling, children, etc. However, the specific kind of the 1666202879Srdivacky * expression is not reported. 1667202879Srdivacky */ 1668202879Srdivacky CXCursor_UnexposedExpr = 100, 1669203955Srdivacky 1670202879Srdivacky /** 1671202879Srdivacky * \brief An expression that refers to some value declaration, such 1672202879Srdivacky * as a function, varible, or enumerator. 1673202879Srdivacky */ 1674202879Srdivacky CXCursor_DeclRefExpr = 101, 1675203955Srdivacky 1676202879Srdivacky /** 1677202879Srdivacky * \brief An expression that refers to a member of a struct, union, 1678202879Srdivacky * class, Objective-C class, etc. 1679202879Srdivacky */ 1680202879Srdivacky CXCursor_MemberRefExpr = 102, 1681203955Srdivacky 1682202879Srdivacky /** \brief An expression that calls a function. */ 1683202879Srdivacky CXCursor_CallExpr = 103, 1684203955Srdivacky 1685202879Srdivacky /** \brief An expression that sends a message to an Objective-C 1686202879Srdivacky object or class. */ 1687202879Srdivacky CXCursor_ObjCMessageExpr = 104, 1688203955Srdivacky 1689207619Srdivacky /** \brief An expression that represents a block literal. */ 1690207619Srdivacky CXCursor_BlockExpr = 105, 1691207619Srdivacky 1692226890Sdim /** \brief An integer literal. 1693226890Sdim */ 1694226890Sdim CXCursor_IntegerLiteral = 106, 1695207619Srdivacky 1696226890Sdim /** \brief A floating point number literal. 1697226890Sdim */ 1698226890Sdim CXCursor_FloatingLiteral = 107, 1699226890Sdim 1700226890Sdim /** \brief An imaginary number literal. 1701226890Sdim */ 1702226890Sdim CXCursor_ImaginaryLiteral = 108, 1703226890Sdim 1704226890Sdim /** \brief A string literal. 1705226890Sdim */ 1706226890Sdim CXCursor_StringLiteral = 109, 1707226890Sdim 1708226890Sdim /** \brief A character literal. 1709226890Sdim */ 1710226890Sdim CXCursor_CharacterLiteral = 110, 1711226890Sdim 1712226890Sdim /** \brief A parenthesized expression, e.g. "(1)". 1713226890Sdim * 1714226890Sdim * This AST node is only formed if full location information is requested. 1715226890Sdim */ 1716226890Sdim CXCursor_ParenExpr = 111, 1717226890Sdim 1718226890Sdim /** \brief This represents the unary-expression's (except sizeof and 1719226890Sdim * alignof). 1720226890Sdim */ 1721226890Sdim CXCursor_UnaryOperator = 112, 1722226890Sdim 1723226890Sdim /** \brief [C99 6.5.2.1] Array Subscripting. 1724226890Sdim */ 1725226890Sdim CXCursor_ArraySubscriptExpr = 113, 1726226890Sdim 1727226890Sdim /** \brief A builtin binary operation expression such as "x + y" or 1728226890Sdim * "x <= y". 1729226890Sdim */ 1730226890Sdim CXCursor_BinaryOperator = 114, 1731226890Sdim 1732226890Sdim /** \brief Compound assignment such as "+=". 1733226890Sdim */ 1734226890Sdim CXCursor_CompoundAssignOperator = 115, 1735226890Sdim 1736226890Sdim /** \brief The ?: ternary operator. 1737226890Sdim */ 1738226890Sdim CXCursor_ConditionalOperator = 116, 1739226890Sdim 1740226890Sdim /** \brief An explicit cast in C (C99 6.5.4) or a C-style cast in C++ 1741226890Sdim * (C++ [expr.cast]), which uses the syntax (Type)expr. 1742226890Sdim * 1743226890Sdim * For example: (int)f. 1744226890Sdim */ 1745226890Sdim CXCursor_CStyleCastExpr = 117, 1746226890Sdim 1747226890Sdim /** \brief [C99 6.5.2.5] 1748226890Sdim */ 1749226890Sdim CXCursor_CompoundLiteralExpr = 118, 1750226890Sdim 1751226890Sdim /** \brief Describes an C or C++ initializer list. 1752226890Sdim */ 1753226890Sdim CXCursor_InitListExpr = 119, 1754226890Sdim 1755226890Sdim /** \brief The GNU address of label extension, representing &&label. 1756226890Sdim */ 1757226890Sdim CXCursor_AddrLabelExpr = 120, 1758226890Sdim 1759226890Sdim /** \brief This is the GNU Statement Expression extension: ({int X=4; X;}) 1760226890Sdim */ 1761226890Sdim CXCursor_StmtExpr = 121, 1762226890Sdim 1763235633Sdim /** \brief Represents a C11 generic selection. 1764226890Sdim */ 1765226890Sdim CXCursor_GenericSelectionExpr = 122, 1766226890Sdim 1767226890Sdim /** \brief Implements the GNU __null extension, which is a name for a null 1768226890Sdim * pointer constant that has integral type (e.g., int or long) and is the same 1769226890Sdim * size and alignment as a pointer. 1770226890Sdim * 1771226890Sdim * The __null extension is typically only used by system headers, which define 1772226890Sdim * NULL as __null in C++ rather than using 0 (which is an integer that may not 1773226890Sdim * match the size of a pointer). 1774226890Sdim */ 1775226890Sdim CXCursor_GNUNullExpr = 123, 1776226890Sdim 1777226890Sdim /** \brief C++'s static_cast<> expression. 1778226890Sdim */ 1779226890Sdim CXCursor_CXXStaticCastExpr = 124, 1780226890Sdim 1781226890Sdim /** \brief C++'s dynamic_cast<> expression. 1782226890Sdim */ 1783226890Sdim CXCursor_CXXDynamicCastExpr = 125, 1784226890Sdim 1785226890Sdim /** \brief C++'s reinterpret_cast<> expression. 1786226890Sdim */ 1787226890Sdim CXCursor_CXXReinterpretCastExpr = 126, 1788226890Sdim 1789226890Sdim /** \brief C++'s const_cast<> expression. 1790226890Sdim */ 1791226890Sdim CXCursor_CXXConstCastExpr = 127, 1792226890Sdim 1793226890Sdim /** \brief Represents an explicit C++ type conversion that uses "functional" 1794226890Sdim * notion (C++ [expr.type.conv]). 1795226890Sdim * 1796226890Sdim * Example: 1797226890Sdim * \code 1798226890Sdim * x = int(0.5); 1799226890Sdim * \endcode 1800226890Sdim */ 1801226890Sdim CXCursor_CXXFunctionalCastExpr = 128, 1802226890Sdim 1803226890Sdim /** \brief A C++ typeid expression (C++ [expr.typeid]). 1804226890Sdim */ 1805226890Sdim CXCursor_CXXTypeidExpr = 129, 1806226890Sdim 1807226890Sdim /** \brief [C++ 2.13.5] C++ Boolean Literal. 1808226890Sdim */ 1809226890Sdim CXCursor_CXXBoolLiteralExpr = 130, 1810226890Sdim 1811226890Sdim /** \brief [C++0x 2.14.7] C++ Pointer Literal. 1812226890Sdim */ 1813226890Sdim CXCursor_CXXNullPtrLiteralExpr = 131, 1814226890Sdim 1815226890Sdim /** \brief Represents the "this" expression in C++ 1816226890Sdim */ 1817226890Sdim CXCursor_CXXThisExpr = 132, 1818226890Sdim 1819226890Sdim /** \brief [C++ 15] C++ Throw Expression. 1820226890Sdim * 1821226890Sdim * This handles 'throw' and 'throw' assignment-expression. When 1822226890Sdim * assignment-expression isn't present, Op will be null. 1823226890Sdim */ 1824226890Sdim CXCursor_CXXThrowExpr = 133, 1825226890Sdim 1826226890Sdim /** \brief A new expression for memory allocation and constructor calls, e.g: 1827226890Sdim * "new CXXNewExpr(foo)". 1828226890Sdim */ 1829226890Sdim CXCursor_CXXNewExpr = 134, 1830226890Sdim 1831226890Sdim /** \brief A delete expression for memory deallocation and destructor calls, 1832226890Sdim * e.g. "delete[] pArray". 1833226890Sdim */ 1834226890Sdim CXCursor_CXXDeleteExpr = 135, 1835226890Sdim 1836226890Sdim /** \brief A unary expression. 1837226890Sdim */ 1838226890Sdim CXCursor_UnaryExpr = 136, 1839226890Sdim 1840235633Sdim /** \brief An Objective-C string literal i.e. @"foo". 1841226890Sdim */ 1842226890Sdim CXCursor_ObjCStringLiteral = 137, 1843226890Sdim 1844245431Sdim /** \brief An Objective-C \@encode expression. 1845226890Sdim */ 1846226890Sdim CXCursor_ObjCEncodeExpr = 138, 1847226890Sdim 1848245431Sdim /** \brief An Objective-C \@selector expression. 1849226890Sdim */ 1850226890Sdim CXCursor_ObjCSelectorExpr = 139, 1851226890Sdim 1852245431Sdim /** \brief An Objective-C \@protocol expression. 1853226890Sdim */ 1854226890Sdim CXCursor_ObjCProtocolExpr = 140, 1855226890Sdim 1856226890Sdim /** \brief An Objective-C "bridged" cast expression, which casts between 1857226890Sdim * Objective-C pointers and C pointers, transferring ownership in the process. 1858226890Sdim * 1859226890Sdim * \code 1860226890Sdim * NSString *str = (__bridge_transfer NSString *)CFCreateString(); 1861226890Sdim * \endcode 1862226890Sdim */ 1863226890Sdim CXCursor_ObjCBridgedCastExpr = 141, 1864226890Sdim 1865226890Sdim /** \brief Represents a C++0x pack expansion that produces a sequence of 1866226890Sdim * expressions. 1867226890Sdim * 1868226890Sdim * A pack expansion expression contains a pattern (which itself is an 1869226890Sdim * expression) followed by an ellipsis. For example: 1870226890Sdim * 1871226890Sdim * \code 1872226890Sdim * template<typename F, typename ...Types> 1873226890Sdim * void forward(F f, Types &&...args) { 1874226890Sdim * f(static_cast<Types&&>(args)...); 1875226890Sdim * } 1876226890Sdim * \endcode 1877226890Sdim */ 1878226890Sdim CXCursor_PackExpansionExpr = 142, 1879226890Sdim 1880226890Sdim /** \brief Represents an expression that computes the length of a parameter 1881226890Sdim * pack. 1882226890Sdim * 1883226890Sdim * \code 1884226890Sdim * template<typename ...Types> 1885226890Sdim * struct count { 1886226890Sdim * static const unsigned value = sizeof...(Types); 1887226890Sdim * }; 1888226890Sdim * \endcode 1889226890Sdim */ 1890226890Sdim CXCursor_SizeOfPackExpr = 143, 1891226890Sdim 1892235633Sdim /* \brief Represents a C++ lambda expression that produces a local function 1893235633Sdim * object. 1894235633Sdim * 1895235633Sdim * \code 1896235633Sdim * void abssort(float *x, unsigned N) { 1897235633Sdim * std::sort(x, x + N, 1898235633Sdim * [](float a, float b) { 1899235633Sdim * return std::abs(a) < std::abs(b); 1900235633Sdim * }); 1901235633Sdim * } 1902235633Sdim * \endcode 1903235633Sdim */ 1904235633Sdim CXCursor_LambdaExpr = 144, 1905235633Sdim 1906235633Sdim /** \brief Objective-c Boolean Literal. 1907235633Sdim */ 1908235633Sdim CXCursor_ObjCBoolLiteralExpr = 145, 1909226890Sdim 1910252723Sdim /** \brief Represents the "self" expression in a ObjC method. 1911252723Sdim */ 1912252723Sdim CXCursor_ObjCSelfExpr = 146, 1913235633Sdim 1914252723Sdim CXCursor_LastExpr = CXCursor_ObjCSelfExpr, 1915252723Sdim 1916202879Srdivacky /* Statements */ 1917202879Srdivacky CXCursor_FirstStmt = 200, 1918202879Srdivacky /** 1919202879Srdivacky * \brief A statement whose specific kind is not exposed via this 1920202879Srdivacky * interface. 1921202879Srdivacky * 1922202879Srdivacky * Unexposed statements have the same operations as any other kind of 1923202879Srdivacky * statement; one can extract their location information, spelling, 1924202879Srdivacky * children, etc. However, the specific kind of the statement is not 1925202879Srdivacky * reported. 1926202879Srdivacky */ 1927202879Srdivacky CXCursor_UnexposedStmt = 200, 1928218893Sdim 1929218893Sdim /** \brief A labelled statement in a function. 1930218893Sdim * 1931218893Sdim * This cursor kind is used to describe the "start_over:" label statement in 1932218893Sdim * the following example: 1933218893Sdim * 1934218893Sdim * \code 1935218893Sdim * start_over: 1936218893Sdim * ++counter; 1937218893Sdim * \endcode 1938218893Sdim * 1939218893Sdim */ 1940218893Sdim CXCursor_LabelStmt = 201, 1941203955Srdivacky 1942226890Sdim /** \brief A group of statements like { stmt stmt }. 1943226890Sdim * 1944226890Sdim * This cursor kind is used to describe compound statements, e.g. function 1945226890Sdim * bodies. 1946226890Sdim */ 1947226890Sdim CXCursor_CompoundStmt = 202, 1948226890Sdim 1949263509Sdim /** \brief A case statement. 1950226890Sdim */ 1951226890Sdim CXCursor_CaseStmt = 203, 1952226890Sdim 1953226890Sdim /** \brief A default statement. 1954226890Sdim */ 1955226890Sdim CXCursor_DefaultStmt = 204, 1956226890Sdim 1957226890Sdim /** \brief An if statement 1958226890Sdim */ 1959226890Sdim CXCursor_IfStmt = 205, 1960226890Sdim 1961226890Sdim /** \brief A switch statement. 1962226890Sdim */ 1963226890Sdim CXCursor_SwitchStmt = 206, 1964226890Sdim 1965226890Sdim /** \brief A while statement. 1966226890Sdim */ 1967226890Sdim CXCursor_WhileStmt = 207, 1968226890Sdim 1969226890Sdim /** \brief A do statement. 1970226890Sdim */ 1971226890Sdim CXCursor_DoStmt = 208, 1972226890Sdim 1973226890Sdim /** \brief A for statement. 1974226890Sdim */ 1975226890Sdim CXCursor_ForStmt = 209, 1976226890Sdim 1977226890Sdim /** \brief A goto statement. 1978226890Sdim */ 1979226890Sdim CXCursor_GotoStmt = 210, 1980226890Sdim 1981226890Sdim /** \brief An indirect goto statement. 1982226890Sdim */ 1983226890Sdim CXCursor_IndirectGotoStmt = 211, 1984226890Sdim 1985226890Sdim /** \brief A continue statement. 1986226890Sdim */ 1987226890Sdim CXCursor_ContinueStmt = 212, 1988226890Sdim 1989226890Sdim /** \brief A break statement. 1990226890Sdim */ 1991226890Sdim CXCursor_BreakStmt = 213, 1992226890Sdim 1993226890Sdim /** \brief A return statement. 1994226890Sdim */ 1995226890Sdim CXCursor_ReturnStmt = 214, 1996226890Sdim 1997245431Sdim /** \brief A GCC inline assembly statement extension. 1998226890Sdim */ 1999245431Sdim CXCursor_GCCAsmStmt = 215, 2000245431Sdim CXCursor_AsmStmt = CXCursor_GCCAsmStmt, 2001226890Sdim 2002245431Sdim /** \brief Objective-C's overall \@try-\@catch-\@finally statement. 2003226890Sdim */ 2004226890Sdim CXCursor_ObjCAtTryStmt = 216, 2005226890Sdim 2006245431Sdim /** \brief Objective-C's \@catch statement. 2007226890Sdim */ 2008226890Sdim CXCursor_ObjCAtCatchStmt = 217, 2009226890Sdim 2010245431Sdim /** \brief Objective-C's \@finally statement. 2011226890Sdim */ 2012226890Sdim CXCursor_ObjCAtFinallyStmt = 218, 2013226890Sdim 2014245431Sdim /** \brief Objective-C's \@throw statement. 2015226890Sdim */ 2016226890Sdim CXCursor_ObjCAtThrowStmt = 219, 2017226890Sdim 2018245431Sdim /** \brief Objective-C's \@synchronized statement. 2019226890Sdim */ 2020226890Sdim CXCursor_ObjCAtSynchronizedStmt = 220, 2021226890Sdim 2022226890Sdim /** \brief Objective-C's autorelease pool statement. 2023226890Sdim */ 2024226890Sdim CXCursor_ObjCAutoreleasePoolStmt = 221, 2025226890Sdim 2026226890Sdim /** \brief Objective-C's collection statement. 2027226890Sdim */ 2028226890Sdim CXCursor_ObjCForCollectionStmt = 222, 2029226890Sdim 2030226890Sdim /** \brief C++'s catch statement. 2031226890Sdim */ 2032226890Sdim CXCursor_CXXCatchStmt = 223, 2033226890Sdim 2034226890Sdim /** \brief C++'s try statement. 2035226890Sdim */ 2036226890Sdim CXCursor_CXXTryStmt = 224, 2037226890Sdim 2038226890Sdim /** \brief C++'s for (* : *) statement. 2039226890Sdim */ 2040226890Sdim CXCursor_CXXForRangeStmt = 225, 2041226890Sdim 2042226890Sdim /** \brief Windows Structured Exception Handling's try statement. 2043226890Sdim */ 2044226890Sdim CXCursor_SEHTryStmt = 226, 2045226890Sdim 2046226890Sdim /** \brief Windows Structured Exception Handling's except statement. 2047226890Sdim */ 2048226890Sdim CXCursor_SEHExceptStmt = 227, 2049226890Sdim 2050226890Sdim /** \brief Windows Structured Exception Handling's finally statement. 2051226890Sdim */ 2052226890Sdim CXCursor_SEHFinallyStmt = 228, 2053226890Sdim 2054245431Sdim /** \brief A MS inline assembly statement extension. 2055245431Sdim */ 2056245431Sdim CXCursor_MSAsmStmt = 229, 2057245431Sdim 2058226890Sdim /** \brief The null satement ";": C99 6.8.3p3. 2059226890Sdim * 2060226890Sdim * This cursor kind is used to describe the null statement. 2061226890Sdim */ 2062226890Sdim CXCursor_NullStmt = 230, 2063226890Sdim 2064226890Sdim /** \brief Adaptor class for mixing declarations with statements and 2065226890Sdim * expressions. 2066226890Sdim */ 2067226890Sdim CXCursor_DeclStmt = 231, 2068226890Sdim 2069263509Sdim /** \brief OpenMP parallel directive. 2070263509Sdim */ 2071263509Sdim CXCursor_OMPParallelDirective = 232, 2072226890Sdim 2073263509Sdim CXCursor_LastStmt = CXCursor_OMPParallelDirective, 2074263509Sdim 2075202879Srdivacky /** 2076202879Srdivacky * \brief Cursor that represents the translation unit itself. 2077202879Srdivacky * 2078202879Srdivacky * The translation unit cursor exists primarily to act as the root 2079202879Srdivacky * cursor for traversing the contents of a translation unit. 2080202879Srdivacky */ 2081204643Srdivacky CXCursor_TranslationUnit = 300, 2082204643Srdivacky 2083204643Srdivacky /* Attributes */ 2084204643Srdivacky CXCursor_FirstAttr = 400, 2085204643Srdivacky /** 2086204643Srdivacky * \brief An attribute whose specific kind is not exposed via this 2087204643Srdivacky * interface. 2088204643Srdivacky */ 2089204643Srdivacky CXCursor_UnexposedAttr = 400, 2090204643Srdivacky 2091204643Srdivacky CXCursor_IBActionAttr = 401, 2092204643Srdivacky CXCursor_IBOutletAttr = 402, 2093208600Srdivacky CXCursor_IBOutletCollectionAttr = 403, 2094226890Sdim CXCursor_CXXFinalAttr = 404, 2095226890Sdim CXCursor_CXXOverrideAttr = 405, 2096226890Sdim CXCursor_AnnotateAttr = 406, 2097235633Sdim CXCursor_AsmLabelAttr = 407, 2098263509Sdim CXCursor_PackedAttr = 408, 2099263509Sdim CXCursor_LastAttr = CXCursor_PackedAttr, 2100205408Srdivacky 2101205408Srdivacky /* Preprocessing */ 2102205408Srdivacky CXCursor_PreprocessingDirective = 500, 2103205408Srdivacky CXCursor_MacroDefinition = 501, 2104224145Sdim CXCursor_MacroExpansion = 502, 2105224145Sdim CXCursor_MacroInstantiation = CXCursor_MacroExpansion, 2106218893Sdim CXCursor_InclusionDirective = 503, 2107205408Srdivacky CXCursor_FirstPreprocessing = CXCursor_PreprocessingDirective, 2108245431Sdim CXCursor_LastPreprocessing = CXCursor_InclusionDirective, 2109245431Sdim 2110245431Sdim /* Extra Declarations */ 2111245431Sdim /** 2112245431Sdim * \brief A module import declaration. 2113245431Sdim */ 2114245431Sdim CXCursor_ModuleImportDecl = 600, 2115245431Sdim CXCursor_FirstExtraDecl = CXCursor_ModuleImportDecl, 2116245431Sdim CXCursor_LastExtraDecl = CXCursor_ModuleImportDecl 2117202879Srdivacky}; 2118202379Srdivacky 2119202879Srdivacky/** 2120202879Srdivacky * \brief A cursor representing some element in the abstract syntax tree for 2121202879Srdivacky * a translation unit. 2122202879Srdivacky * 2123203955Srdivacky * The cursor abstraction unifies the different kinds of entities in a 2124202879Srdivacky * program--declaration, statements, expressions, references to declarations, 2125202879Srdivacky * etc.--under a single "cursor" abstraction with a common set of operations. 2126202879Srdivacky * Common operation for a cursor include: getting the physical location in 2127202879Srdivacky * a source file where the cursor points, getting the name associated with a 2128202879Srdivacky * cursor, and retrieving cursors for any child nodes of a particular cursor. 2129202879Srdivacky * 2130202879Srdivacky * Cursors can be produced in two specific ways. 2131202879Srdivacky * clang_getTranslationUnitCursor() produces a cursor for a translation unit, 2132202879Srdivacky * from which one can use clang_visitChildren() to explore the rest of the 2133202879Srdivacky * translation unit. clang_getCursor() maps from a physical source location 2134202879Srdivacky * to the entity that resides at that location, allowing one to map from the 2135202879Srdivacky * source code into the AST. 2136198092Srdivacky */ 2137202879Srdivackytypedef struct { 2138202879Srdivacky enum CXCursorKind kind; 2139226890Sdim int xdata; 2140252723Sdim const void *data[3]; 2141203955Srdivacky} CXCursor; 2142202879Srdivacky 2143198398Srdivacky/** 2144245431Sdim * \brief A comment AST node. 2145245431Sdim */ 2146245431Sdimtypedef struct { 2147245431Sdim const void *ASTNode; 2148245431Sdim CXTranslationUnit TranslationUnit; 2149245431Sdim} CXComment; 2150245431Sdim 2151245431Sdim/** 2152202879Srdivacky * \defgroup CINDEX_CURSOR_MANIP Cursor manipulations 2153202879Srdivacky * 2154202879Srdivacky * @{ 2155198398Srdivacky */ 2156203955Srdivacky 2157202879Srdivacky/** 2158202879Srdivacky * \brief Retrieve the NULL cursor, which represents no entity. 2159202879Srdivacky */ 2160199482SrdivackyCINDEX_LINKAGE CXCursor clang_getNullCursor(void); 2161203955Srdivacky 2162202879Srdivacky/** 2163202879Srdivacky * \brief Retrieve the cursor that represents the given translation unit. 2164202879Srdivacky * 2165202879Srdivacky * The translation unit cursor can be used to start traversing the 2166202879Srdivacky * various declarations within the given translation unit. 2167202879Srdivacky */ 2168202879SrdivackyCINDEX_LINKAGE CXCursor clang_getTranslationUnitCursor(CXTranslationUnit); 2169198092Srdivacky 2170202879Srdivacky/** 2171202879Srdivacky * \brief Determine whether two cursors are equivalent. 2172202879Srdivacky */ 2173202879SrdivackyCINDEX_LINKAGE unsigned clang_equalCursors(CXCursor, CXCursor); 2174203955Srdivacky 2175202879Srdivacky/** 2176245431Sdim * \brief Returns non-zero if \p cursor is null. 2177226890Sdim */ 2178245431SdimCINDEX_LINKAGE int clang_Cursor_isNull(CXCursor cursor); 2179226890Sdim 2180226890Sdim/** 2181218893Sdim * \brief Compute a hash value for the given cursor. 2182218893Sdim */ 2183218893SdimCINDEX_LINKAGE unsigned clang_hashCursor(CXCursor); 2184218893Sdim 2185218893Sdim/** 2186202879Srdivacky * \brief Retrieve the kind of the given cursor. 2187202879Srdivacky */ 2188198893SrdivackyCINDEX_LINKAGE enum CXCursorKind clang_getCursorKind(CXCursor); 2189202879Srdivacky 2190202879Srdivacky/** 2191202879Srdivacky * \brief Determine whether the given cursor kind represents a declaration. 2192202879Srdivacky */ 2193198893SrdivackyCINDEX_LINKAGE unsigned clang_isDeclaration(enum CXCursorKind); 2194202879Srdivacky 2195202879Srdivacky/** 2196202879Srdivacky * \brief Determine whether the given cursor kind represents a simple 2197202879Srdivacky * reference. 2198202879Srdivacky * 2199202879Srdivacky * Note that other kinds of cursors (such as expressions) can also refer to 2200202879Srdivacky * other cursors. Use clang_getCursorReferenced() to determine whether a 2201202879Srdivacky * particular cursor refers to another entity. 2202202879Srdivacky */ 2203198893SrdivackyCINDEX_LINKAGE unsigned clang_isReference(enum CXCursorKind); 2204202879Srdivacky 2205202879Srdivacky/** 2206202879Srdivacky * \brief Determine whether the given cursor kind represents an expression. 2207202879Srdivacky */ 2208202879SrdivackyCINDEX_LINKAGE unsigned clang_isExpression(enum CXCursorKind); 2209202879Srdivacky 2210202879Srdivacky/** 2211202879Srdivacky * \brief Determine whether the given cursor kind represents a statement. 2212202879Srdivacky */ 2213202879SrdivackyCINDEX_LINKAGE unsigned clang_isStatement(enum CXCursorKind); 2214202879Srdivacky 2215202879Srdivacky/** 2216224145Sdim * \brief Determine whether the given cursor kind represents an attribute. 2217224145Sdim */ 2218224145SdimCINDEX_LINKAGE unsigned clang_isAttribute(enum CXCursorKind); 2219224145Sdim 2220224145Sdim/** 2221203955Srdivacky * \brief Determine whether the given cursor kind represents an invalid 2222202879Srdivacky * cursor. 2223203955Srdivacky */ 2224198893SrdivackyCINDEX_LINKAGE unsigned clang_isInvalid(enum CXCursorKind); 2225198398Srdivacky 2226202879Srdivacky/** 2227203955Srdivacky * \brief Determine whether the given cursor kind represents a translation 2228203955Srdivacky * unit. 2229202879Srdivacky */ 2230202879SrdivackyCINDEX_LINKAGE unsigned clang_isTranslationUnit(enum CXCursorKind); 2231203955Srdivacky 2232204962Srdivacky/*** 2233205408Srdivacky * \brief Determine whether the given cursor represents a preprocessing 2234205408Srdivacky * element, such as a preprocessor directive or macro instantiation. 2235205408Srdivacky */ 2236205408SrdivackyCINDEX_LINKAGE unsigned clang_isPreprocessing(enum CXCursorKind); 2237205408Srdivacky 2238205408Srdivacky/*** 2239204962Srdivacky * \brief Determine whether the given cursor represents a currently 2240204962Srdivacky * unexposed piece of the AST (e.g., CXCursor_UnexposedStmt). 2241204962Srdivacky */ 2242204962SrdivackyCINDEX_LINKAGE unsigned clang_isUnexposed(enum CXCursorKind); 2243204962Srdivacky 2244202879Srdivacky/** 2245204643Srdivacky * \brief Describe the linkage of the entity referred to by a cursor. 2246204643Srdivacky */ 2247204643Srdivackyenum CXLinkageKind { 2248204643Srdivacky /** \brief This value indicates that no linkage information is available 2249204643Srdivacky * for a provided CXCursor. */ 2250204643Srdivacky CXLinkage_Invalid, 2251204643Srdivacky /** 2252204643Srdivacky * \brief This is the linkage for variables, parameters, and so on that 2253204643Srdivacky * have automatic storage. This covers normal (non-extern) local variables. 2254204643Srdivacky */ 2255204643Srdivacky CXLinkage_NoLinkage, 2256204643Srdivacky /** \brief This is the linkage for static variables and static functions. */ 2257204643Srdivacky CXLinkage_Internal, 2258204643Srdivacky /** \brief This is the linkage for entities with external linkage that live 2259204643Srdivacky * in C++ anonymous namespaces.*/ 2260204643Srdivacky CXLinkage_UniqueExternal, 2261204643Srdivacky /** \brief This is the linkage for entities with true, external linkage. */ 2262204643Srdivacky CXLinkage_External 2263204643Srdivacky}; 2264204643Srdivacky 2265204643Srdivacky/** 2266207619Srdivacky * \brief Determine the linkage of the entity referred to by a given cursor. 2267204643Srdivacky */ 2268204643SrdivackyCINDEX_LINKAGE enum CXLinkageKind clang_getCursorLinkage(CXCursor cursor); 2269204643Srdivacky 2270204643Srdivacky/** 2271245431Sdim * \brief Determine the availability of the entity that this cursor refers to, 2272245431Sdim * taking the current target platform into account. 2273212904Sdim * 2274212904Sdim * \param cursor The cursor to query. 2275212904Sdim * 2276212904Sdim * \returns The availability of the cursor. 2277212904Sdim */ 2278212904SdimCINDEX_LINKAGE enum CXAvailabilityKind 2279212904Sdimclang_getCursorAvailability(CXCursor cursor); 2280212904Sdim 2281212904Sdim/** 2282245431Sdim * Describes the availability of a given entity on a particular platform, e.g., 2283245431Sdim * a particular class might only be available on Mac OS 10.7 or newer. 2284245431Sdim */ 2285245431Sdimtypedef struct CXPlatformAvailability { 2286245431Sdim /** 2287245431Sdim * \brief A string that describes the platform for which this structure 2288245431Sdim * provides availability information. 2289245431Sdim * 2290245431Sdim * Possible values are "ios" or "macosx". 2291245431Sdim */ 2292245431Sdim CXString Platform; 2293245431Sdim /** 2294245431Sdim * \brief The version number in which this entity was introduced. 2295245431Sdim */ 2296245431Sdim CXVersion Introduced; 2297245431Sdim /** 2298245431Sdim * \brief The version number in which this entity was deprecated (but is 2299245431Sdim * still available). 2300245431Sdim */ 2301245431Sdim CXVersion Deprecated; 2302245431Sdim /** 2303245431Sdim * \brief The version number in which this entity was obsoleted, and therefore 2304245431Sdim * is no longer available. 2305245431Sdim */ 2306245431Sdim CXVersion Obsoleted; 2307245431Sdim /** 2308245431Sdim * \brief Whether the entity is unconditionally unavailable on this platform. 2309245431Sdim */ 2310245431Sdim int Unavailable; 2311245431Sdim /** 2312245431Sdim * \brief An optional message to provide to a user of this API, e.g., to 2313245431Sdim * suggest replacement APIs. 2314245431Sdim */ 2315245431Sdim CXString Message; 2316245431Sdim} CXPlatformAvailability; 2317245431Sdim 2318245431Sdim/** 2319245431Sdim * \brief Determine the availability of the entity that this cursor refers to 2320245431Sdim * on any platforms for which availability information is known. 2321245431Sdim * 2322245431Sdim * \param cursor The cursor to query. 2323245431Sdim * 2324245431Sdim * \param always_deprecated If non-NULL, will be set to indicate whether the 2325245431Sdim * entity is deprecated on all platforms. 2326245431Sdim * 2327245431Sdim * \param deprecated_message If non-NULL, will be set to the message text 2328245431Sdim * provided along with the unconditional deprecation of this entity. The client 2329245431Sdim * is responsible for deallocating this string. 2330245431Sdim * 2331245431Sdim * \param always_unavailable If non-NULL, will be set to indicate whether the 2332245431Sdim * entity is unavailable on all platforms. 2333245431Sdim * 2334245431Sdim * \param unavailable_message If non-NULL, will be set to the message text 2335245431Sdim * provided along with the unconditional unavailability of this entity. The 2336245431Sdim * client is responsible for deallocating this string. 2337245431Sdim * 2338245431Sdim * \param availability If non-NULL, an array of CXPlatformAvailability instances 2339245431Sdim * that will be populated with platform availability information, up to either 2340245431Sdim * the number of platforms for which availability information is available (as 2341245431Sdim * returned by this function) or \c availability_size, whichever is smaller. 2342245431Sdim * 2343245431Sdim * \param availability_size The number of elements available in the 2344245431Sdim * \c availability array. 2345245431Sdim * 2346245431Sdim * \returns The number of platforms (N) for which availability information is 2347245431Sdim * available (which is unrelated to \c availability_size). 2348245431Sdim * 2349245431Sdim * Note that the client is responsible for calling 2350245431Sdim * \c clang_disposeCXPlatformAvailability to free each of the 2351245431Sdim * platform-availability structures returned. There are 2352245431Sdim * \c min(N, availability_size) such structures. 2353245431Sdim */ 2354245431SdimCINDEX_LINKAGE int 2355245431Sdimclang_getCursorPlatformAvailability(CXCursor cursor, 2356245431Sdim int *always_deprecated, 2357245431Sdim CXString *deprecated_message, 2358245431Sdim int *always_unavailable, 2359245431Sdim CXString *unavailable_message, 2360245431Sdim CXPlatformAvailability *availability, 2361245431Sdim int availability_size); 2362245431Sdim 2363245431Sdim/** 2364245431Sdim * \brief Free the memory associated with a \c CXPlatformAvailability structure. 2365245431Sdim */ 2366245431SdimCINDEX_LINKAGE void 2367245431Sdimclang_disposeCXPlatformAvailability(CXPlatformAvailability *availability); 2368245431Sdim 2369245431Sdim/** 2370207619Srdivacky * \brief Describe the "language" of the entity referred to by a cursor. 2371207619Srdivacky */ 2372207619SrdivackyCINDEX_LINKAGE enum CXLanguageKind { 2373207619Srdivacky CXLanguage_Invalid = 0, 2374207619Srdivacky CXLanguage_C, 2375207619Srdivacky CXLanguage_ObjC, 2376207619Srdivacky CXLanguage_CPlusPlus 2377207619Srdivacky}; 2378207619Srdivacky 2379207619Srdivacky/** 2380207619Srdivacky * \brief Determine the "language" of the entity referred to by a given cursor. 2381207619Srdivacky */ 2382207619SrdivackyCINDEX_LINKAGE enum CXLanguageKind clang_getCursorLanguage(CXCursor cursor); 2383207619Srdivacky 2384226890Sdim/** 2385226890Sdim * \brief Returns the translation unit that a cursor originated from. 2386226890Sdim */ 2387226890SdimCINDEX_LINKAGE CXTranslationUnit clang_Cursor_getTranslationUnit(CXCursor); 2388218893Sdim 2389226890Sdim 2390207619Srdivacky/** 2391218893Sdim * \brief A fast container representing a set of CXCursors. 2392218893Sdim */ 2393218893Sdimtypedef struct CXCursorSetImpl *CXCursorSet; 2394218893Sdim 2395218893Sdim/** 2396218893Sdim * \brief Creates an empty CXCursorSet. 2397218893Sdim */ 2398252723SdimCINDEX_LINKAGE CXCursorSet clang_createCXCursorSet(void); 2399218893Sdim 2400218893Sdim/** 2401218893Sdim * \brief Disposes a CXCursorSet and releases its associated memory. 2402218893Sdim */ 2403218893SdimCINDEX_LINKAGE void clang_disposeCXCursorSet(CXCursorSet cset); 2404218893Sdim 2405218893Sdim/** 2406218893Sdim * \brief Queries a CXCursorSet to see if it contains a specific CXCursor. 2407218893Sdim * 2408218893Sdim * \returns non-zero if the set contains the specified cursor. 2409218893Sdim*/ 2410218893SdimCINDEX_LINKAGE unsigned clang_CXCursorSet_contains(CXCursorSet cset, 2411218893Sdim CXCursor cursor); 2412218893Sdim 2413218893Sdim/** 2414218893Sdim * \brief Inserts a CXCursor into a CXCursorSet. 2415218893Sdim * 2416218893Sdim * \returns zero if the CXCursor was already in the set, and non-zero otherwise. 2417218893Sdim*/ 2418218893SdimCINDEX_LINKAGE unsigned clang_CXCursorSet_insert(CXCursorSet cset, 2419218893Sdim CXCursor cursor); 2420218893Sdim 2421218893Sdim/** 2422218893Sdim * \brief Determine the semantic parent of the given cursor. 2423218893Sdim * 2424218893Sdim * The semantic parent of a cursor is the cursor that semantically contains 2425218893Sdim * the given \p cursor. For many declarations, the lexical and semantic parents 2426218893Sdim * are equivalent (the lexical parent is returned by 2427218893Sdim * \c clang_getCursorLexicalParent()). They diverge when declarations or 2428218893Sdim * definitions are provided out-of-line. For example: 2429218893Sdim * 2430218893Sdim * \code 2431218893Sdim * class C { 2432218893Sdim * void f(); 2433218893Sdim * }; 2434218893Sdim * 2435218893Sdim * void C::f() { } 2436218893Sdim * \endcode 2437218893Sdim * 2438218893Sdim * In the out-of-line definition of \c C::f, the semantic parent is the 2439218893Sdim * the class \c C, of which this function is a member. The lexical parent is 2440218893Sdim * the place where the declaration actually occurs in the source code; in this 2441218893Sdim * case, the definition occurs in the translation unit. In general, the 2442218893Sdim * lexical parent for a given entity can change without affecting the semantics 2443218893Sdim * of the program, and the lexical parent of different declarations of the 2444218893Sdim * same entity may be different. Changing the semantic parent of a declaration, 2445218893Sdim * on the other hand, can have a major impact on semantics, and redeclarations 2446218893Sdim * of a particular entity should all have the same semantic context. 2447218893Sdim * 2448218893Sdim * In the example above, both declarations of \c C::f have \c C as their 2449218893Sdim * semantic context, while the lexical context of the first \c C::f is \c C 2450218893Sdim * and the lexical context of the second \c C::f is the translation unit. 2451218893Sdim * 2452218893Sdim * For global declarations, the semantic parent is the translation unit. 2453218893Sdim */ 2454218893SdimCINDEX_LINKAGE CXCursor clang_getCursorSemanticParent(CXCursor cursor); 2455218893Sdim 2456218893Sdim/** 2457218893Sdim * \brief Determine the lexical parent of the given cursor. 2458218893Sdim * 2459218893Sdim * The lexical parent of a cursor is the cursor in which the given \p cursor 2460218893Sdim * was actually written. For many declarations, the lexical and semantic parents 2461218893Sdim * are equivalent (the semantic parent is returned by 2462218893Sdim * \c clang_getCursorSemanticParent()). They diverge when declarations or 2463218893Sdim * definitions are provided out-of-line. For example: 2464218893Sdim * 2465218893Sdim * \code 2466218893Sdim * class C { 2467218893Sdim * void f(); 2468218893Sdim * }; 2469218893Sdim * 2470218893Sdim * void C::f() { } 2471218893Sdim * \endcode 2472218893Sdim * 2473218893Sdim * In the out-of-line definition of \c C::f, the semantic parent is the 2474218893Sdim * the class \c C, of which this function is a member. The lexical parent is 2475218893Sdim * the place where the declaration actually occurs in the source code; in this 2476218893Sdim * case, the definition occurs in the translation unit. In general, the 2477218893Sdim * lexical parent for a given entity can change without affecting the semantics 2478218893Sdim * of the program, and the lexical parent of different declarations of the 2479218893Sdim * same entity may be different. Changing the semantic parent of a declaration, 2480218893Sdim * on the other hand, can have a major impact on semantics, and redeclarations 2481218893Sdim * of a particular entity should all have the same semantic context. 2482218893Sdim * 2483218893Sdim * In the example above, both declarations of \c C::f have \c C as their 2484218893Sdim * semantic context, while the lexical context of the first \c C::f is \c C 2485218893Sdim * and the lexical context of the second \c C::f is the translation unit. 2486218893Sdim * 2487218893Sdim * For declarations written in the global scope, the lexical parent is 2488218893Sdim * the translation unit. 2489218893Sdim */ 2490218893SdimCINDEX_LINKAGE CXCursor clang_getCursorLexicalParent(CXCursor cursor); 2491218893Sdim 2492218893Sdim/** 2493218893Sdim * \brief Determine the set of methods that are overridden by the given 2494218893Sdim * method. 2495218893Sdim * 2496218893Sdim * In both Objective-C and C++, a method (aka virtual member function, 2497218893Sdim * in C++) can override a virtual method in a base class. For 2498218893Sdim * Objective-C, a method is said to override any method in the class's 2499235633Sdim * base class, its protocols, or its categories' protocols, that has the same 2500235633Sdim * selector and is of the same kind (class or instance). 2501235633Sdim * If no such method exists, the search continues to the class's superclass, 2502235633Sdim * its protocols, and its categories, and so on. A method from an Objective-C 2503235633Sdim * implementation is considered to override the same methods as its 2504235633Sdim * corresponding method in the interface. 2505218893Sdim * 2506218893Sdim * For C++, a virtual member function overrides any virtual member 2507218893Sdim * function with the same signature that occurs in its base 2508218893Sdim * classes. With multiple inheritance, a virtual member function can 2509218893Sdim * override several virtual member functions coming from different 2510218893Sdim * base classes. 2511218893Sdim * 2512218893Sdim * In all cases, this function determines the immediate overridden 2513218893Sdim * method, rather than all of the overridden methods. For example, if 2514218893Sdim * a method is originally declared in a class A, then overridden in B 2515218893Sdim * (which in inherits from A) and also in C (which inherited from B), 2516218893Sdim * then the only overridden method returned from this function when 2517218893Sdim * invoked on C's method will be B's method. The client may then 2518218893Sdim * invoke this function again, given the previously-found overridden 2519218893Sdim * methods, to map out the complete method-override set. 2520218893Sdim * 2521218893Sdim * \param cursor A cursor representing an Objective-C or C++ 2522218893Sdim * method. This routine will compute the set of methods that this 2523218893Sdim * method overrides. 2524218893Sdim * 2525218893Sdim * \param overridden A pointer whose pointee will be replaced with a 2526218893Sdim * pointer to an array of cursors, representing the set of overridden 2527218893Sdim * methods. If there are no overridden methods, the pointee will be 2528218893Sdim * set to NULL. The pointee must be freed via a call to 2529218893Sdim * \c clang_disposeOverriddenCursors(). 2530218893Sdim * 2531218893Sdim * \param num_overridden A pointer to the number of overridden 2532218893Sdim * functions, will be set to the number of overridden functions in the 2533218893Sdim * array pointed to by \p overridden. 2534218893Sdim */ 2535218893SdimCINDEX_LINKAGE void clang_getOverriddenCursors(CXCursor cursor, 2536218893Sdim CXCursor **overridden, 2537218893Sdim unsigned *num_overridden); 2538218893Sdim 2539218893Sdim/** 2540218893Sdim * \brief Free the set of overridden cursors returned by \c 2541218893Sdim * clang_getOverriddenCursors(). 2542218893Sdim */ 2543218893SdimCINDEX_LINKAGE void clang_disposeOverriddenCursors(CXCursor *overridden); 2544218893Sdim 2545218893Sdim/** 2546218893Sdim * \brief Retrieve the file that is included by the given inclusion directive 2547218893Sdim * cursor. 2548218893Sdim */ 2549218893SdimCINDEX_LINKAGE CXFile clang_getIncludedFile(CXCursor cursor); 2550218893Sdim 2551218893Sdim/** 2552202879Srdivacky * @} 2553202879Srdivacky */ 2554203955Srdivacky 2555202879Srdivacky/** 2556202879Srdivacky * \defgroup CINDEX_CURSOR_SOURCE Mapping between cursors and source code 2557202879Srdivacky * 2558202879Srdivacky * Cursors represent a location within the Abstract Syntax Tree (AST). These 2559202879Srdivacky * routines help map between cursors and the physical locations where the 2560202879Srdivacky * described entities occur in the source code. The mapping is provided in 2561202879Srdivacky * both directions, so one can map from source code to the AST and back. 2562202879Srdivacky * 2563202879Srdivacky * @{ 2564202879Srdivacky */ 2565203955Srdivacky 2566202879Srdivacky/** 2567202879Srdivacky * \brief Map a source location to the cursor that describes the entity at that 2568202879Srdivacky * location in the source code. 2569202879Srdivacky * 2570202879Srdivacky * clang_getCursor() maps an arbitrary source location within a translation 2571202879Srdivacky * unit down to the most specific cursor that describes the entity at that 2572203955Srdivacky * location. For example, given an expression \c x + y, invoking 2573202879Srdivacky * clang_getCursor() with a source location pointing to "x" will return the 2574203955Srdivacky * cursor for "x"; similarly for "y". If the cursor points anywhere between 2575202879Srdivacky * "x" or "y" (e.g., on the + or the whitespace around it), clang_getCursor() 2576202879Srdivacky * will return a cursor referring to the "+" expression. 2577202879Srdivacky * 2578202879Srdivacky * \returns a cursor representing the entity at the given source location, or 2579202879Srdivacky * a NULL cursor if no such entity can be found. 2580202879Srdivacky */ 2581202879SrdivackyCINDEX_LINKAGE CXCursor clang_getCursor(CXTranslationUnit, CXSourceLocation); 2582203955Srdivacky 2583202879Srdivacky/** 2584202879Srdivacky * \brief Retrieve the physical location of the source constructor referenced 2585202879Srdivacky * by the given cursor. 2586202879Srdivacky * 2587202879Srdivacky * The location of a declaration is typically the location of the name of that 2588203955Srdivacky * declaration, where the name of that declaration would occur if it is 2589203955Srdivacky * unnamed, or some keyword that introduces that particular declaration. 2590203955Srdivacky * The location of a reference is where that reference occurs within the 2591202879Srdivacky * source code. 2592202879Srdivacky */ 2593202879SrdivackyCINDEX_LINKAGE CXSourceLocation clang_getCursorLocation(CXCursor); 2594199482Srdivacky 2595202879Srdivacky/** 2596202879Srdivacky * \brief Retrieve the physical extent of the source construct referenced by 2597202879Srdivacky * the given cursor. 2598202879Srdivacky * 2599202879Srdivacky * The extent of a cursor starts with the file/line/column pointing at the 2600202879Srdivacky * first character within the source construct that the cursor refers to and 2601203955Srdivacky * ends with the last character withinin that source construct. For a 2602202879Srdivacky * declaration, the extent covers the declaration itself. For a reference, 2603202879Srdivacky * the extent covers the location of the reference (e.g., where the referenced 2604202879Srdivacky * entity was actually used). 2605202879Srdivacky */ 2606202879SrdivackyCINDEX_LINKAGE CXSourceRange clang_getCursorExtent(CXCursor); 2607202879Srdivacky 2608202879Srdivacky/** 2609202879Srdivacky * @} 2610202879Srdivacky */ 2611212904Sdim 2612202879Srdivacky/** 2613208600Srdivacky * \defgroup CINDEX_TYPES Type information for CXCursors 2614208600Srdivacky * 2615208600Srdivacky * @{ 2616208600Srdivacky */ 2617208600Srdivacky 2618208600Srdivacky/** 2619208600Srdivacky * \brief Describes the kind of type 2620208600Srdivacky */ 2621208600Srdivackyenum CXTypeKind { 2622208600Srdivacky /** 2623208600Srdivacky * \brief Reprents an invalid type (e.g., where no type is available). 2624208600Srdivacky */ 2625208600Srdivacky CXType_Invalid = 0, 2626208600Srdivacky 2627208600Srdivacky /** 2628208600Srdivacky * \brief A type whose specific kind is not exposed via this 2629208600Srdivacky * interface. 2630208600Srdivacky */ 2631208600Srdivacky CXType_Unexposed = 1, 2632208600Srdivacky 2633208600Srdivacky /* Builtin types */ 2634208600Srdivacky CXType_Void = 2, 2635208600Srdivacky CXType_Bool = 3, 2636208600Srdivacky CXType_Char_U = 4, 2637208600Srdivacky CXType_UChar = 5, 2638208600Srdivacky CXType_Char16 = 6, 2639208600Srdivacky CXType_Char32 = 7, 2640208600Srdivacky CXType_UShort = 8, 2641208600Srdivacky CXType_UInt = 9, 2642208600Srdivacky CXType_ULong = 10, 2643208600Srdivacky CXType_ULongLong = 11, 2644208600Srdivacky CXType_UInt128 = 12, 2645208600Srdivacky CXType_Char_S = 13, 2646208600Srdivacky CXType_SChar = 14, 2647208600Srdivacky CXType_WChar = 15, 2648208600Srdivacky CXType_Short = 16, 2649208600Srdivacky CXType_Int = 17, 2650208600Srdivacky CXType_Long = 18, 2651208600Srdivacky CXType_LongLong = 19, 2652208600Srdivacky CXType_Int128 = 20, 2653208600Srdivacky CXType_Float = 21, 2654208600Srdivacky CXType_Double = 22, 2655208600Srdivacky CXType_LongDouble = 23, 2656208600Srdivacky CXType_NullPtr = 24, 2657208600Srdivacky CXType_Overload = 25, 2658208600Srdivacky CXType_Dependent = 26, 2659208600Srdivacky CXType_ObjCId = 27, 2660208600Srdivacky CXType_ObjCClass = 28, 2661208600Srdivacky CXType_ObjCSel = 29, 2662208600Srdivacky CXType_FirstBuiltin = CXType_Void, 2663208600Srdivacky CXType_LastBuiltin = CXType_ObjCSel, 2664208600Srdivacky 2665208600Srdivacky CXType_Complex = 100, 2666208600Srdivacky CXType_Pointer = 101, 2667208600Srdivacky CXType_BlockPointer = 102, 2668208600Srdivacky CXType_LValueReference = 103, 2669208600Srdivacky CXType_RValueReference = 104, 2670208600Srdivacky CXType_Record = 105, 2671208600Srdivacky CXType_Enum = 106, 2672208600Srdivacky CXType_Typedef = 107, 2673208600Srdivacky CXType_ObjCInterface = 108, 2674210299Sed CXType_ObjCObjectPointer = 109, 2675210299Sed CXType_FunctionNoProto = 110, 2676226890Sdim CXType_FunctionProto = 111, 2677235633Sdim CXType_ConstantArray = 112, 2678263509Sdim CXType_Vector = 113, 2679263509Sdim CXType_IncompleteArray = 114, 2680263509Sdim CXType_VariableArray = 115, 2681263509Sdim CXType_DependentSizedArray = 116, 2682263509Sdim CXType_MemberPointer = 117 2683208600Srdivacky}; 2684208600Srdivacky 2685208600Srdivacky/** 2686235633Sdim * \brief Describes the calling convention of a function type 2687235633Sdim */ 2688235633Sdimenum CXCallingConv { 2689235633Sdim CXCallingConv_Default = 0, 2690235633Sdim CXCallingConv_C = 1, 2691235633Sdim CXCallingConv_X86StdCall = 2, 2692235633Sdim CXCallingConv_X86FastCall = 3, 2693235633Sdim CXCallingConv_X86ThisCall = 4, 2694235633Sdim CXCallingConv_X86Pascal = 5, 2695235633Sdim CXCallingConv_AAPCS = 6, 2696235633Sdim CXCallingConv_AAPCS_VFP = 7, 2697245431Sdim CXCallingConv_PnaclCall = 8, 2698252723Sdim CXCallingConv_IntelOclBicc = 9, 2699256382Sdim CXCallingConv_X86_64Win64 = 10, 2700256382Sdim CXCallingConv_X86_64SysV = 11, 2701235633Sdim 2702235633Sdim CXCallingConv_Invalid = 100, 2703235633Sdim CXCallingConv_Unexposed = 200 2704235633Sdim}; 2705235633Sdim 2706235633Sdim 2707235633Sdim/** 2708208600Srdivacky * \brief The type of an element in the abstract syntax tree. 2709208600Srdivacky * 2710208600Srdivacky */ 2711208600Srdivackytypedef struct { 2712208600Srdivacky enum CXTypeKind kind; 2713208600Srdivacky void *data[2]; 2714208600Srdivacky} CXType; 2715208600Srdivacky 2716208600Srdivacky/** 2717208600Srdivacky * \brief Retrieve the type of a CXCursor (if any). 2718208600Srdivacky */ 2719208600SrdivackyCINDEX_LINKAGE CXType clang_getCursorType(CXCursor C); 2720208600Srdivacky 2721208600Srdivacky/** 2722252723Sdim * \brief Pretty-print the underlying type using the rules of the 2723252723Sdim * language of the translation unit from which it came. 2724252723Sdim * 2725252723Sdim * If the type is invalid, an empty string is returned. 2726252723Sdim */ 2727252723SdimCINDEX_LINKAGE CXString clang_getTypeSpelling(CXType CT); 2728252723Sdim 2729252723Sdim/** 2730235633Sdim * \brief Retrieve the underlying type of a typedef declaration. 2731235633Sdim * 2732235633Sdim * If the cursor does not reference a typedef declaration, an invalid type is 2733235633Sdim * returned. 2734235633Sdim */ 2735235633SdimCINDEX_LINKAGE CXType clang_getTypedefDeclUnderlyingType(CXCursor C); 2736235633Sdim 2737235633Sdim/** 2738235633Sdim * \brief Retrieve the integer type of an enum declaration. 2739235633Sdim * 2740235633Sdim * If the cursor does not reference an enum declaration, an invalid type is 2741235633Sdim * returned. 2742235633Sdim */ 2743235633SdimCINDEX_LINKAGE CXType clang_getEnumDeclIntegerType(CXCursor C); 2744235633Sdim 2745235633Sdim/** 2746235633Sdim * \brief Retrieve the integer value of an enum constant declaration as a signed 2747235633Sdim * long long. 2748235633Sdim * 2749235633Sdim * If the cursor does not reference an enum constant declaration, LLONG_MIN is returned. 2750235633Sdim * Since this is also potentially a valid constant value, the kind of the cursor 2751235633Sdim * must be verified before calling this function. 2752235633Sdim */ 2753235633SdimCINDEX_LINKAGE long long clang_getEnumConstantDeclValue(CXCursor C); 2754235633Sdim 2755235633Sdim/** 2756235633Sdim * \brief Retrieve the integer value of an enum constant declaration as an unsigned 2757235633Sdim * long long. 2758235633Sdim * 2759235633Sdim * If the cursor does not reference an enum constant declaration, ULLONG_MAX is returned. 2760235633Sdim * Since this is also potentially a valid constant value, the kind of the cursor 2761235633Sdim * must be verified before calling this function. 2762235633Sdim */ 2763235633SdimCINDEX_LINKAGE unsigned long long clang_getEnumConstantDeclUnsignedValue(CXCursor C); 2764235633Sdim 2765235633Sdim/** 2766252723Sdim * \brief Retrieve the bit width of a bit field declaration as an integer. 2767252723Sdim * 2768252723Sdim * If a cursor that is not a bit field declaration is passed in, -1 is returned. 2769252723Sdim */ 2770252723SdimCINDEX_LINKAGE int clang_getFieldDeclBitWidth(CXCursor C); 2771252723Sdim 2772252723Sdim/** 2773235633Sdim * \brief Retrieve the number of non-variadic arguments associated with a given 2774235633Sdim * cursor. 2775235633Sdim * 2776252723Sdim * The number of arguments can be determined for calls as well as for 2777252723Sdim * declarations of functions or methods. For other cursors -1 is returned. 2778235633Sdim */ 2779235633SdimCINDEX_LINKAGE int clang_Cursor_getNumArguments(CXCursor C); 2780235633Sdim 2781235633Sdim/** 2782235633Sdim * \brief Retrieve the argument cursor of a function or method. 2783235633Sdim * 2784252723Sdim * The argument cursor can be determined for calls as well as for declarations 2785252723Sdim * of functions or methods. For other cursors and for invalid indices, an 2786252723Sdim * invalid cursor is returned. 2787235633Sdim */ 2788235633SdimCINDEX_LINKAGE CXCursor clang_Cursor_getArgument(CXCursor C, unsigned i); 2789235633Sdim 2790235633Sdim/** 2791245431Sdim * \brief Determine whether two CXTypes represent the same type. 2792208600Srdivacky * 2793245431Sdim * \returns non-zero if the CXTypes represent the same type and 2794245431Sdim * zero otherwise. 2795208600Srdivacky */ 2796208600SrdivackyCINDEX_LINKAGE unsigned clang_equalTypes(CXType A, CXType B); 2797208600Srdivacky 2798208600Srdivacky/** 2799208600Srdivacky * \brief Return the canonical type for a CXType. 2800208600Srdivacky * 2801208600Srdivacky * Clang's type system explicitly models typedefs and all the ways 2802208600Srdivacky * a specific type can be represented. The canonical type is the underlying 2803208600Srdivacky * type with all the "sugar" removed. For example, if 'T' is a typedef 2804208600Srdivacky * for 'int', the canonical type for 'T' would be 'int'. 2805208600Srdivacky */ 2806208600SrdivackyCINDEX_LINKAGE CXType clang_getCanonicalType(CXType T); 2807208600Srdivacky 2808208600Srdivacky/** 2809245431Sdim * \brief Determine whether a CXType has the "const" qualifier set, 2810245431Sdim * without looking through typedefs that may have added "const" at a 2811245431Sdim * different level. 2812218893Sdim */ 2813218893SdimCINDEX_LINKAGE unsigned clang_isConstQualifiedType(CXType T); 2814218893Sdim 2815218893Sdim/** 2816245431Sdim * \brief Determine whether a CXType has the "volatile" qualifier set, 2817245431Sdim * without looking through typedefs that may have added "volatile" at 2818245431Sdim * a different level. 2819218893Sdim */ 2820218893SdimCINDEX_LINKAGE unsigned clang_isVolatileQualifiedType(CXType T); 2821218893Sdim 2822218893Sdim/** 2823245431Sdim * \brief Determine whether a CXType has the "restrict" qualifier set, 2824245431Sdim * without looking through typedefs that may have added "restrict" at a 2825245431Sdim * different level. 2826218893Sdim */ 2827218893SdimCINDEX_LINKAGE unsigned clang_isRestrictQualifiedType(CXType T); 2828218893Sdim 2829218893Sdim/** 2830208600Srdivacky * \brief For pointer types, returns the type of the pointee. 2831208600Srdivacky */ 2832208600SrdivackyCINDEX_LINKAGE CXType clang_getPointeeType(CXType T); 2833208600Srdivacky 2834208600Srdivacky/** 2835208600Srdivacky * \brief Return the cursor for the declaration of the given type. 2836208600Srdivacky */ 2837208600SrdivackyCINDEX_LINKAGE CXCursor clang_getTypeDeclaration(CXType T); 2838208600Srdivacky 2839218893Sdim/** 2840218893Sdim * Returns the Objective-C type encoding for the specified declaration. 2841218893Sdim */ 2842218893SdimCINDEX_LINKAGE CXString clang_getDeclObjCTypeEncoding(CXCursor C); 2843208600Srdivacky 2844208600Srdivacky/** 2845208600Srdivacky * \brief Retrieve the spelling of a given CXTypeKind. 2846208600Srdivacky */ 2847208600SrdivackyCINDEX_LINKAGE CXString clang_getTypeKindSpelling(enum CXTypeKind K); 2848208600Srdivacky 2849208600Srdivacky/** 2850235633Sdim * \brief Retrieve the calling convention associated with a function type. 2851235633Sdim * 2852235633Sdim * If a non-function type is passed in, CXCallingConv_Invalid is returned. 2853235633Sdim */ 2854235633SdimCINDEX_LINKAGE enum CXCallingConv clang_getFunctionTypeCallingConv(CXType T); 2855235633Sdim 2856235633Sdim/** 2857210299Sed * \brief Retrieve the result type associated with a function type. 2858235633Sdim * 2859235633Sdim * If a non-function type is passed in, an invalid type is returned. 2860210299Sed */ 2861210299SedCINDEX_LINKAGE CXType clang_getResultType(CXType T); 2862210299Sed 2863210299Sed/** 2864245431Sdim * \brief Retrieve the number of non-variadic arguments associated with a 2865245431Sdim * function type. 2866235633Sdim * 2867235633Sdim * If a non-function type is passed in, -1 is returned. 2868210299Sed */ 2869235633SdimCINDEX_LINKAGE int clang_getNumArgTypes(CXType T); 2870235633Sdim 2871235633Sdim/** 2872235633Sdim * \brief Retrieve the type of an argument of a function type. 2873235633Sdim * 2874245431Sdim * If a non-function type is passed in or the function does not have enough 2875245431Sdim * parameters, an invalid type is returned. 2876235633Sdim */ 2877235633SdimCINDEX_LINKAGE CXType clang_getArgType(CXType T, unsigned i); 2878235633Sdim 2879235633Sdim/** 2880235633Sdim * \brief Return 1 if the CXType is a variadic function type, and 0 otherwise. 2881235633Sdim */ 2882235633SdimCINDEX_LINKAGE unsigned clang_isFunctionTypeVariadic(CXType T); 2883235633Sdim 2884235633Sdim/** 2885235633Sdim * \brief Retrieve the result type associated with a given cursor. 2886235633Sdim * 2887235633Sdim * This only returns a valid type if the cursor refers to a function or method. 2888235633Sdim */ 2889210299SedCINDEX_LINKAGE CXType clang_getCursorResultType(CXCursor C); 2890210299Sed 2891210299Sed/** 2892212904Sdim * \brief Return 1 if the CXType is a POD (plain old data) type, and 0 2893212904Sdim * otherwise. 2894212904Sdim */ 2895212904SdimCINDEX_LINKAGE unsigned clang_isPODType(CXType T); 2896212904Sdim 2897212904Sdim/** 2898235633Sdim * \brief Return the element type of an array, complex, or vector type. 2899235633Sdim * 2900235633Sdim * If a type is passed in that is not an array, complex, or vector type, 2901235633Sdim * an invalid type is returned. 2902235633Sdim */ 2903235633SdimCINDEX_LINKAGE CXType clang_getElementType(CXType T); 2904235633Sdim 2905235633Sdim/** 2906235633Sdim * \brief Return the number of elements of an array or vector type. 2907235633Sdim * 2908235633Sdim * If a type is passed in that is not an array or vector type, 2909235633Sdim * -1 is returned. 2910235633Sdim */ 2911235633SdimCINDEX_LINKAGE long long clang_getNumElements(CXType T); 2912235633Sdim 2913235633Sdim/** 2914226890Sdim * \brief Return the element type of an array type. 2915226890Sdim * 2916226890Sdim * If a non-array type is passed in, an invalid type is returned. 2917226890Sdim */ 2918226890SdimCINDEX_LINKAGE CXType clang_getArrayElementType(CXType T); 2919226890Sdim 2920226890Sdim/** 2921245431Sdim * \brief Return the array size of a constant array. 2922226890Sdim * 2923226890Sdim * If a non-array type is passed in, -1 is returned. 2924226890Sdim */ 2925226890SdimCINDEX_LINKAGE long long clang_getArraySize(CXType T); 2926226890Sdim 2927226890Sdim/** 2928252723Sdim * \brief List the possible error codes for \c clang_Type_getSizeOf, 2929252723Sdim * \c clang_Type_getAlignOf, \c clang_Type_getOffsetOf and 2930252723Sdim * \c clang_Cursor_getOffsetOf. 2931252723Sdim * 2932252723Sdim * A value of this enumeration type can be returned if the target type is not 2933252723Sdim * a valid argument to sizeof, alignof or offsetof. 2934252723Sdim */ 2935252723Sdimenum CXTypeLayoutError { 2936252723Sdim /** 2937252723Sdim * \brief Type is of kind CXType_Invalid. 2938252723Sdim */ 2939252723Sdim CXTypeLayoutError_Invalid = -1, 2940252723Sdim /** 2941252723Sdim * \brief The type is an incomplete Type. 2942252723Sdim */ 2943252723Sdim CXTypeLayoutError_Incomplete = -2, 2944252723Sdim /** 2945252723Sdim * \brief The type is a dependent Type. 2946252723Sdim */ 2947252723Sdim CXTypeLayoutError_Dependent = -3, 2948252723Sdim /** 2949252723Sdim * \brief The type is not a constant size type. 2950252723Sdim */ 2951252723Sdim CXTypeLayoutError_NotConstantSize = -4, 2952252723Sdim /** 2953252723Sdim * \brief The Field name is not valid for this record. 2954252723Sdim */ 2955252723Sdim CXTypeLayoutError_InvalidFieldName = -5 2956252723Sdim}; 2957252723Sdim 2958252723Sdim/** 2959252723Sdim * \brief Return the alignment of a type in bytes as per C++[expr.alignof] 2960252723Sdim * standard. 2961252723Sdim * 2962252723Sdim * If the type declaration is invalid, CXTypeLayoutError_Invalid is returned. 2963252723Sdim * If the type declaration is an incomplete type, CXTypeLayoutError_Incomplete 2964252723Sdim * is returned. 2965252723Sdim * If the type declaration is a dependent type, CXTypeLayoutError_Dependent is 2966252723Sdim * returned. 2967252723Sdim * If the type declaration is not a constant size type, 2968252723Sdim * CXTypeLayoutError_NotConstantSize is returned. 2969252723Sdim */ 2970252723SdimCINDEX_LINKAGE long long clang_Type_getAlignOf(CXType T); 2971252723Sdim 2972252723Sdim/** 2973263509Sdim * \brief Return the class type of an member pointer type. 2974263509Sdim * 2975263509Sdim * If a non-member-pointer type is passed in, an invalid type is returned. 2976263509Sdim */ 2977263509SdimCINDEX_LINKAGE CXType clang_Type_getClassType(CXType T); 2978263509Sdim 2979263509Sdim/** 2980252723Sdim * \brief Return the size of a type in bytes as per C++[expr.sizeof] standard. 2981252723Sdim * 2982252723Sdim * If the type declaration is invalid, CXTypeLayoutError_Invalid is returned. 2983252723Sdim * If the type declaration is an incomplete type, CXTypeLayoutError_Incomplete 2984252723Sdim * is returned. 2985252723Sdim * If the type declaration is a dependent type, CXTypeLayoutError_Dependent is 2986252723Sdim * returned. 2987252723Sdim */ 2988252723SdimCINDEX_LINKAGE long long clang_Type_getSizeOf(CXType T); 2989252723Sdim 2990252723Sdim/** 2991252723Sdim * \brief Return the offset of a field named S in a record of type T in bits 2992252723Sdim * as it would be returned by __offsetof__ as per C++11[18.2p4] 2993252723Sdim * 2994252723Sdim * If the cursor is not a record field declaration, CXTypeLayoutError_Invalid 2995252723Sdim * is returned. 2996252723Sdim * If the field's type declaration is an incomplete type, 2997252723Sdim * CXTypeLayoutError_Incomplete is returned. 2998252723Sdim * If the field's type declaration is a dependent type, 2999252723Sdim * CXTypeLayoutError_Dependent is returned. 3000252723Sdim * If the field's name S is not found, 3001252723Sdim * CXTypeLayoutError_InvalidFieldName is returned. 3002252723Sdim */ 3003252723SdimCINDEX_LINKAGE long long clang_Type_getOffsetOf(CXType T, const char *S); 3004252723Sdim 3005263509Sdimenum CXRefQualifierKind { 3006263509Sdim /** \brief No ref-qualifier was provided. */ 3007263509Sdim CXRefQualifier_None = 0, 3008263509Sdim /** \brief An lvalue ref-qualifier was provided (\c &). */ 3009263509Sdim CXRefQualifier_LValue, 3010263509Sdim /** \brief An rvalue ref-qualifier was provided (\c &&). */ 3011263509Sdim CXRefQualifier_RValue 3012263509Sdim}; 3013263509Sdim 3014252723Sdim/** 3015263509Sdim * \brief Retrieve the ref-qualifier kind of a function or method. 3016263509Sdim * 3017263509Sdim * The ref-qualifier is returned for C++ functions or methods. For other types 3018263509Sdim * or non-C++ declarations, CXRefQualifier_None is returned. 3019263509Sdim */ 3020263509SdimCINDEX_LINKAGE enum CXRefQualifierKind clang_Type_getCXXRefQualifier(CXType T); 3021263509Sdim 3022263509Sdim/** 3023252723Sdim * \brief Returns non-zero if the cursor specifies a Record member that is a 3024252723Sdim * bitfield. 3025252723Sdim */ 3026252723SdimCINDEX_LINKAGE unsigned clang_Cursor_isBitField(CXCursor C); 3027252723Sdim 3028252723Sdim/** 3029212904Sdim * \brief Returns 1 if the base class specified by the cursor with kind 3030212904Sdim * CX_CXXBaseSpecifier is virtual. 3031212904Sdim */ 3032212904SdimCINDEX_LINKAGE unsigned clang_isVirtualBase(CXCursor); 3033212904Sdim 3034212904Sdim/** 3035212904Sdim * \brief Represents the C++ access control level to a base class for a 3036212904Sdim * cursor with kind CX_CXXBaseSpecifier. 3037212904Sdim */ 3038212904Sdimenum CX_CXXAccessSpecifier { 3039212904Sdim CX_CXXInvalidAccessSpecifier, 3040212904Sdim CX_CXXPublic, 3041212904Sdim CX_CXXProtected, 3042212904Sdim CX_CXXPrivate 3043212904Sdim}; 3044212904Sdim 3045212904Sdim/** 3046252723Sdim * \brief Returns the access control level for the referenced object. 3047252723Sdim * 3048252723Sdim * If the cursor refers to a C++ declaration, its access control level within its 3049252723Sdim * parent scope is returned. Otherwise, if the cursor refers to a base specifier or 3050252723Sdim * access specifier, the specifier itself is returned. 3051212904Sdim */ 3052212904SdimCINDEX_LINKAGE enum CX_CXXAccessSpecifier clang_getCXXAccessSpecifier(CXCursor); 3053212904Sdim 3054212904Sdim/** 3055218893Sdim * \brief Determine the number of overloaded declarations referenced by a 3056218893Sdim * \c CXCursor_OverloadedDeclRef cursor. 3057218893Sdim * 3058218893Sdim * \param cursor The cursor whose overloaded declarations are being queried. 3059218893Sdim * 3060218893Sdim * \returns The number of overloaded declarations referenced by \c cursor. If it 3061218893Sdim * is not a \c CXCursor_OverloadedDeclRef cursor, returns 0. 3062218893Sdim */ 3063218893SdimCINDEX_LINKAGE unsigned clang_getNumOverloadedDecls(CXCursor cursor); 3064218893Sdim 3065218893Sdim/** 3066218893Sdim * \brief Retrieve a cursor for one of the overloaded declarations referenced 3067218893Sdim * by a \c CXCursor_OverloadedDeclRef cursor. 3068218893Sdim * 3069218893Sdim * \param cursor The cursor whose overloaded declarations are being queried. 3070218893Sdim * 3071218893Sdim * \param index The zero-based index into the set of overloaded declarations in 3072218893Sdim * the cursor. 3073218893Sdim * 3074218893Sdim * \returns A cursor representing the declaration referenced by the given 3075218893Sdim * \c cursor at the specified \c index. If the cursor does not have an 3076218893Sdim * associated set of overloaded declarations, or if the index is out of bounds, 3077218893Sdim * returns \c clang_getNullCursor(); 3078218893Sdim */ 3079218893SdimCINDEX_LINKAGE CXCursor clang_getOverloadedDecl(CXCursor cursor, 3080218893Sdim unsigned index); 3081218893Sdim 3082218893Sdim/** 3083208600Srdivacky * @} 3084208600Srdivacky */ 3085212904Sdim 3086212904Sdim/** 3087212904Sdim * \defgroup CINDEX_ATTRIBUTES Information for attributes 3088212904Sdim * 3089212904Sdim * @{ 3090212904Sdim */ 3091208600Srdivacky 3092212904Sdim 3093208600Srdivacky/** 3094212904Sdim * \brief For cursors representing an iboutletcollection attribute, 3095212904Sdim * this function returns the collection element type. 3096212904Sdim * 3097212904Sdim */ 3098212904SdimCINDEX_LINKAGE CXType clang_getIBOutletCollectionType(CXCursor); 3099212904Sdim 3100212904Sdim/** 3101212904Sdim * @} 3102212904Sdim */ 3103212904Sdim 3104212904Sdim/** 3105202879Srdivacky * \defgroup CINDEX_CURSOR_TRAVERSAL Traversing the AST with cursors 3106202879Srdivacky * 3107202879Srdivacky * These routines provide the ability to traverse the abstract syntax tree 3108202879Srdivacky * using cursors. 3109202879Srdivacky * 3110202879Srdivacky * @{ 3111202879Srdivacky */ 3112203955Srdivacky 3113202879Srdivacky/** 3114202879Srdivacky * \brief Describes how the traversal of the children of a particular 3115202879Srdivacky * cursor should proceed after visiting a particular child cursor. 3116202879Srdivacky * 3117202879Srdivacky * A value of this enumeration type should be returned by each 3118202879Srdivacky * \c CXCursorVisitor to indicate how clang_visitChildren() proceed. 3119202879Srdivacky */ 3120202879Srdivackyenum CXChildVisitResult { 3121202879Srdivacky /** 3122203955Srdivacky * \brief Terminates the cursor traversal. 3123202879Srdivacky */ 3124202879Srdivacky CXChildVisit_Break, 3125203955Srdivacky /** 3126202879Srdivacky * \brief Continues the cursor traversal with the next sibling of 3127202879Srdivacky * the cursor just visited, without visiting its children. 3128202879Srdivacky */ 3129202879Srdivacky CXChildVisit_Continue, 3130202879Srdivacky /** 3131202879Srdivacky * \brief Recursively traverse the children of this cursor, using 3132202879Srdivacky * the same visitor and client data. 3133202879Srdivacky */ 3134202879Srdivacky CXChildVisit_Recurse 3135202879Srdivacky}; 3136202879Srdivacky 3137202879Srdivacky/** 3138202879Srdivacky * \brief Visitor invoked for each cursor found by a traversal. 3139202879Srdivacky * 3140202879Srdivacky * This visitor function will be invoked for each cursor found by 3141202879Srdivacky * clang_visitCursorChildren(). Its first argument is the cursor being 3142202879Srdivacky * visited, its second argument is the parent visitor for that cursor, 3143202879Srdivacky * and its third argument is the client data provided to 3144202879Srdivacky * clang_visitCursorChildren(). 3145202879Srdivacky * 3146202879Srdivacky * The visitor should return one of the \c CXChildVisitResult values 3147202879Srdivacky * to direct clang_visitCursorChildren(). 3148202879Srdivacky */ 3149203955Srdivackytypedef enum CXChildVisitResult (*CXCursorVisitor)(CXCursor cursor, 3150203955Srdivacky CXCursor parent, 3151202879Srdivacky CXClientData client_data); 3152202879Srdivacky 3153202879Srdivacky/** 3154202879Srdivacky * \brief Visit the children of a particular cursor. 3155202879Srdivacky * 3156202879Srdivacky * This function visits all the direct children of the given cursor, 3157202879Srdivacky * invoking the given \p visitor function with the cursors of each 3158202879Srdivacky * visited child. The traversal may be recursive, if the visitor returns 3159202879Srdivacky * \c CXChildVisit_Recurse. The traversal may also be ended prematurely, if 3160202879Srdivacky * the visitor returns \c CXChildVisit_Break. 3161202879Srdivacky * 3162202879Srdivacky * \param parent the cursor whose child may be visited. All kinds of 3163203955Srdivacky * cursors can be visited, including invalid cursors (which, by 3164202879Srdivacky * definition, have no children). 3165202879Srdivacky * 3166202879Srdivacky * \param visitor the visitor function that will be invoked for each 3167202879Srdivacky * child of \p parent. 3168202879Srdivacky * 3169202879Srdivacky * \param client_data pointer data supplied by the client, which will 3170202879Srdivacky * be passed to the visitor each time it is invoked. 3171202879Srdivacky * 3172202879Srdivacky * \returns a non-zero value if the traversal was terminated 3173202879Srdivacky * prematurely by the visitor returning \c CXChildVisit_Break. 3174202879Srdivacky */ 3175203955SrdivackyCINDEX_LINKAGE unsigned clang_visitChildren(CXCursor parent, 3176202879Srdivacky CXCursorVisitor visitor, 3177202879Srdivacky CXClientData client_data); 3178218893Sdim#ifdef __has_feature 3179218893Sdim# if __has_feature(blocks) 3180218893Sdim/** 3181218893Sdim * \brief Visitor invoked for each cursor found by a traversal. 3182218893Sdim * 3183218893Sdim * This visitor block will be invoked for each cursor found by 3184218893Sdim * clang_visitChildrenWithBlock(). Its first argument is the cursor being 3185218893Sdim * visited, its second argument is the parent visitor for that cursor. 3186218893Sdim * 3187218893Sdim * The visitor should return one of the \c CXChildVisitResult values 3188218893Sdim * to direct clang_visitChildrenWithBlock(). 3189218893Sdim */ 3190218893Sdimtypedef enum CXChildVisitResult 3191218893Sdim (^CXCursorVisitorBlock)(CXCursor cursor, CXCursor parent); 3192203955Srdivacky 3193202879Srdivacky/** 3194218893Sdim * Visits the children of a cursor using the specified block. Behaves 3195218893Sdim * identically to clang_visitChildren() in all other respects. 3196218893Sdim */ 3197218893Sdimunsigned clang_visitChildrenWithBlock(CXCursor parent, 3198218893Sdim CXCursorVisitorBlock block); 3199218893Sdim# endif 3200218893Sdim#endif 3201218893Sdim 3202218893Sdim/** 3203202879Srdivacky * @} 3204202879Srdivacky */ 3205203955Srdivacky 3206202879Srdivacky/** 3207202879Srdivacky * \defgroup CINDEX_CURSOR_XREF Cross-referencing in the AST 3208202879Srdivacky * 3209203955Srdivacky * These routines provide the ability to determine references within and 3210202879Srdivacky * across translation units, by providing the names of the entities referenced 3211202879Srdivacky * by cursors, follow reference cursors to the declarations they reference, 3212202879Srdivacky * and associate declarations with their definitions. 3213202879Srdivacky * 3214202879Srdivacky * @{ 3215202879Srdivacky */ 3216203955Srdivacky 3217202879Srdivacky/** 3218202879Srdivacky * \brief Retrieve a Unified Symbol Resolution (USR) for the entity referenced 3219202879Srdivacky * by the given cursor. 3220202879Srdivacky * 3221202879Srdivacky * A Unified Symbol Resolution (USR) is a string that identifies a particular 3222202879Srdivacky * entity (function, class, variable, etc.) within a program. USRs can be 3223202879Srdivacky * compared across translation units to determine, e.g., when references in 3224202879Srdivacky * one translation refer to an entity defined in another translation unit. 3225202879Srdivacky */ 3226202879SrdivackyCINDEX_LINKAGE CXString clang_getCursorUSR(CXCursor); 3227202879Srdivacky 3228202879Srdivacky/** 3229205219Srdivacky * \brief Construct a USR for a specified Objective-C class. 3230205219Srdivacky */ 3231205219SrdivackyCINDEX_LINKAGE CXString clang_constructUSR_ObjCClass(const char *class_name); 3232205219Srdivacky 3233205219Srdivacky/** 3234205219Srdivacky * \brief Construct a USR for a specified Objective-C category. 3235205219Srdivacky */ 3236205219SrdivackyCINDEX_LINKAGE CXString 3237205219Srdivacky clang_constructUSR_ObjCCategory(const char *class_name, 3238205219Srdivacky const char *category_name); 3239205219Srdivacky 3240205219Srdivacky/** 3241205219Srdivacky * \brief Construct a USR for a specified Objective-C protocol. 3242205219Srdivacky */ 3243205219SrdivackyCINDEX_LINKAGE CXString 3244205219Srdivacky clang_constructUSR_ObjCProtocol(const char *protocol_name); 3245205219Srdivacky 3246205219Srdivacky 3247205219Srdivacky/** 3248205219Srdivacky * \brief Construct a USR for a specified Objective-C instance variable and 3249205219Srdivacky * the USR for its containing class. 3250205219Srdivacky */ 3251205219SrdivackyCINDEX_LINKAGE CXString clang_constructUSR_ObjCIvar(const char *name, 3252205219Srdivacky CXString classUSR); 3253205219Srdivacky 3254205219Srdivacky/** 3255205219Srdivacky * \brief Construct a USR for a specified Objective-C method and 3256205219Srdivacky * the USR for its containing class. 3257205219Srdivacky */ 3258205219SrdivackyCINDEX_LINKAGE CXString clang_constructUSR_ObjCMethod(const char *name, 3259205219Srdivacky unsigned isInstanceMethod, 3260205219Srdivacky CXString classUSR); 3261205219Srdivacky 3262205219Srdivacky/** 3263205219Srdivacky * \brief Construct a USR for a specified Objective-C property and the USR 3264205219Srdivacky * for its containing class. 3265205219Srdivacky */ 3266205219SrdivackyCINDEX_LINKAGE CXString clang_constructUSR_ObjCProperty(const char *property, 3267205219Srdivacky CXString classUSR); 3268205219Srdivacky 3269205219Srdivacky/** 3270202879Srdivacky * \brief Retrieve a name for the entity referenced by this cursor. 3271202879Srdivacky */ 3272199482SrdivackyCINDEX_LINKAGE CXString clang_getCursorSpelling(CXCursor); 3273198398Srdivacky 3274218893Sdim/** 3275235633Sdim * \brief Retrieve a range for a piece that forms the cursors spelling name. 3276235633Sdim * Most of the times there is only one range for the complete spelling but for 3277235633Sdim * objc methods and objc message expressions, there are multiple pieces for each 3278235633Sdim * selector identifier. 3279235633Sdim * 3280235633Sdim * \param pieceIndex the index of the spelling name piece. If this is greater 3281235633Sdim * than the actual number of pieces, it will return a NULL (invalid) range. 3282235633Sdim * 3283235633Sdim * \param options Reserved. 3284235633Sdim */ 3285235633SdimCINDEX_LINKAGE CXSourceRange clang_Cursor_getSpellingNameRange(CXCursor, 3286235633Sdim unsigned pieceIndex, 3287235633Sdim unsigned options); 3288235633Sdim 3289235633Sdim/** 3290218893Sdim * \brief Retrieve the display name for the entity referenced by this cursor. 3291218893Sdim * 3292218893Sdim * The display name contains extra information that helps identify the cursor, 3293218893Sdim * such as the parameters of a function or template or the arguments of a 3294218893Sdim * class template specialization. 3295218893Sdim */ 3296218893SdimCINDEX_LINKAGE CXString clang_getCursorDisplayName(CXCursor); 3297218893Sdim 3298202879Srdivacky/** \brief For a cursor that is a reference, retrieve a cursor representing the 3299202879Srdivacky * entity that it references. 3300202879Srdivacky * 3301202879Srdivacky * Reference cursors refer to other entities in the AST. For example, an 3302202879Srdivacky * Objective-C superclass reference cursor refers to an Objective-C class. 3303203955Srdivacky * This function produces the cursor for the Objective-C class from the 3304202879Srdivacky * cursor for the superclass reference. If the input cursor is a declaration or 3305202879Srdivacky * definition, it returns that declaration or definition unchanged. 3306203955Srdivacky * Otherwise, returns the NULL cursor. 3307202879Srdivacky */ 3308202879SrdivackyCINDEX_LINKAGE CXCursor clang_getCursorReferenced(CXCursor); 3309202879Srdivacky 3310203955Srdivacky/** 3311202879Srdivacky * \brief For a cursor that is either a reference to or a declaration 3312202879Srdivacky * of some entity, retrieve a cursor that describes the definition of 3313202879Srdivacky * that entity. 3314202879Srdivacky * 3315202879Srdivacky * Some entities can be declared multiple times within a translation 3316202879Srdivacky * unit, but only one of those declarations can also be a 3317202879Srdivacky * definition. For example, given: 3318202879Srdivacky * 3319202879Srdivacky * \code 3320202879Srdivacky * int f(int, int); 3321202879Srdivacky * int g(int x, int y) { return f(x, y); } 3322202879Srdivacky * int f(int a, int b) { return a + b; } 3323202879Srdivacky * int f(int, int); 3324202879Srdivacky * \endcode 3325202879Srdivacky * 3326202879Srdivacky * there are three declarations of the function "f", but only the 3327202879Srdivacky * second one is a definition. The clang_getCursorDefinition() 3328202879Srdivacky * function will take any cursor pointing to a declaration of "f" 3329202879Srdivacky * (the first or fourth lines of the example) or a cursor referenced 3330202879Srdivacky * that uses "f" (the call to "f' inside "g") and will return a 3331202879Srdivacky * declaration cursor pointing to the definition (the second "f" 3332202879Srdivacky * declaration). 3333202879Srdivacky * 3334202879Srdivacky * If given a cursor for which there is no corresponding definition, 3335202879Srdivacky * e.g., because there is no definition of that entity within this 3336202879Srdivacky * translation unit, returns a NULL cursor. 3337202879Srdivacky */ 3338202879SrdivackyCINDEX_LINKAGE CXCursor clang_getCursorDefinition(CXCursor); 3339202879Srdivacky 3340203955Srdivacky/** 3341202879Srdivacky * \brief Determine whether the declaration pointed to by this cursor 3342202879Srdivacky * is also a definition of that entity. 3343202879Srdivacky */ 3344202879SrdivackyCINDEX_LINKAGE unsigned clang_isCursorDefinition(CXCursor); 3345202879Srdivacky 3346202879Srdivacky/** 3347218893Sdim * \brief Retrieve the canonical cursor corresponding to the given cursor. 3348218893Sdim * 3349218893Sdim * In the C family of languages, many kinds of entities can be declared several 3350218893Sdim * times within a single translation unit. For example, a structure type can 3351218893Sdim * be forward-declared (possibly multiple times) and later defined: 3352218893Sdim * 3353218893Sdim * \code 3354218893Sdim * struct X; 3355218893Sdim * struct X; 3356218893Sdim * struct X { 3357218893Sdim * int member; 3358218893Sdim * }; 3359218893Sdim * \endcode 3360218893Sdim * 3361218893Sdim * The declarations and the definition of \c X are represented by three 3362218893Sdim * different cursors, all of which are declarations of the same underlying 3363218893Sdim * entity. One of these cursor is considered the "canonical" cursor, which 3364218893Sdim * is effectively the representative for the underlying entity. One can 3365218893Sdim * determine if two cursors are declarations of the same underlying entity by 3366218893Sdim * comparing their canonical cursors. 3367218893Sdim * 3368218893Sdim * \returns The canonical cursor for the entity referred to by the given cursor. 3369218893Sdim */ 3370218893SdimCINDEX_LINKAGE CXCursor clang_getCanonicalCursor(CXCursor); 3371218893Sdim 3372235633Sdim 3373218893Sdim/** 3374235633Sdim * \brief If the cursor points to a selector identifier in a objc method or 3375235633Sdim * message expression, this returns the selector index. 3376235633Sdim * 3377245431Sdim * After getting a cursor with #clang_getCursor, this can be called to 3378235633Sdim * determine if the location points to a selector identifier. 3379235633Sdim * 3380235633Sdim * \returns The selector index if the cursor is an objc method or message 3381235633Sdim * expression and the cursor is pointing to a selector identifier, or -1 3382235633Sdim * otherwise. 3383235633Sdim */ 3384235633SdimCINDEX_LINKAGE int clang_Cursor_getObjCSelectorIndex(CXCursor); 3385235633Sdim 3386235633Sdim/** 3387245431Sdim * \brief Given a cursor pointing to a C++ method call or an ObjC message, 3388245431Sdim * returns non-zero if the method/message is "dynamic", meaning: 3389245431Sdim * 3390245431Sdim * For a C++ method: the call is virtual. 3391245431Sdim * For an ObjC message: the receiver is an object instance, not 'super' or a 3392245431Sdim * specific class. 3393245431Sdim * 3394245431Sdim * If the method/message is "static" or the cursor does not point to a 3395245431Sdim * method/message, it will return zero. 3396245431Sdim */ 3397245431SdimCINDEX_LINKAGE int clang_Cursor_isDynamicCall(CXCursor C); 3398245431Sdim 3399245431Sdim/** 3400245431Sdim * \brief Given a cursor pointing to an ObjC message, returns the CXType of the 3401245431Sdim * receiver. 3402245431Sdim */ 3403245431SdimCINDEX_LINKAGE CXType clang_Cursor_getReceiverType(CXCursor C); 3404245431Sdim 3405245431Sdim/** 3406252723Sdim * \brief Property attributes for a \c CXCursor_ObjCPropertyDecl. 3407252723Sdim */ 3408252723Sdimtypedef enum { 3409252723Sdim CXObjCPropertyAttr_noattr = 0x00, 3410252723Sdim CXObjCPropertyAttr_readonly = 0x01, 3411252723Sdim CXObjCPropertyAttr_getter = 0x02, 3412252723Sdim CXObjCPropertyAttr_assign = 0x04, 3413252723Sdim CXObjCPropertyAttr_readwrite = 0x08, 3414252723Sdim CXObjCPropertyAttr_retain = 0x10, 3415252723Sdim CXObjCPropertyAttr_copy = 0x20, 3416252723Sdim CXObjCPropertyAttr_nonatomic = 0x40, 3417252723Sdim CXObjCPropertyAttr_setter = 0x80, 3418252723Sdim CXObjCPropertyAttr_atomic = 0x100, 3419252723Sdim CXObjCPropertyAttr_weak = 0x200, 3420252723Sdim CXObjCPropertyAttr_strong = 0x400, 3421252723Sdim CXObjCPropertyAttr_unsafe_unretained = 0x800 3422252723Sdim} CXObjCPropertyAttrKind; 3423252723Sdim 3424252723Sdim/** 3425252723Sdim * \brief Given a cursor that represents a property declaration, return the 3426252723Sdim * associated property attributes. The bits are formed from 3427252723Sdim * \c CXObjCPropertyAttrKind. 3428252723Sdim * 3429252723Sdim * \param reserved Reserved for future use, pass 0. 3430252723Sdim */ 3431252723SdimCINDEX_LINKAGE unsigned clang_Cursor_getObjCPropertyAttributes(CXCursor C, 3432252723Sdim unsigned reserved); 3433252723Sdim 3434252723Sdim/** 3435252723Sdim * \brief 'Qualifiers' written next to the return and parameter types in 3436252723Sdim * ObjC method declarations. 3437252723Sdim */ 3438252723Sdimtypedef enum { 3439252723Sdim CXObjCDeclQualifier_None = 0x0, 3440252723Sdim CXObjCDeclQualifier_In = 0x1, 3441252723Sdim CXObjCDeclQualifier_Inout = 0x2, 3442252723Sdim CXObjCDeclQualifier_Out = 0x4, 3443252723Sdim CXObjCDeclQualifier_Bycopy = 0x8, 3444252723Sdim CXObjCDeclQualifier_Byref = 0x10, 3445252723Sdim CXObjCDeclQualifier_Oneway = 0x20 3446252723Sdim} CXObjCDeclQualifierKind; 3447252723Sdim 3448252723Sdim/** 3449252723Sdim * \brief Given a cursor that represents an ObjC method or parameter 3450252723Sdim * declaration, return the associated ObjC qualifiers for the return type or the 3451252723Sdim * parameter respectively. The bits are formed from CXObjCDeclQualifierKind. 3452252723Sdim */ 3453252723SdimCINDEX_LINKAGE unsigned clang_Cursor_getObjCDeclQualifiers(CXCursor C); 3454252723Sdim 3455252723Sdim/** 3456263509Sdim * \brief Given a cursor that represents an ObjC method or property declaration, 3457263509Sdim * return non-zero if the declaration was affected by "@optional". 3458263509Sdim * Returns zero if the cursor is not such a declaration or it is "@required". 3459263509Sdim */ 3460263509SdimCINDEX_LINKAGE unsigned clang_Cursor_isObjCOptional(CXCursor C); 3461263509Sdim 3462263509Sdim/** 3463252723Sdim * \brief Returns non-zero if the given cursor is a variadic function or method. 3464252723Sdim */ 3465252723SdimCINDEX_LINKAGE unsigned clang_Cursor_isVariadic(CXCursor C); 3466252723Sdim 3467252723Sdim/** 3468245431Sdim * \brief Given a cursor that represents a declaration, return the associated 3469245431Sdim * comment's source range. The range may include multiple consecutive comments 3470245431Sdim * with whitespace in between. 3471245431Sdim */ 3472245431SdimCINDEX_LINKAGE CXSourceRange clang_Cursor_getCommentRange(CXCursor C); 3473245431Sdim 3474245431Sdim/** 3475245431Sdim * \brief Given a cursor that represents a declaration, return the associated 3476245431Sdim * comment text, including comment markers. 3477245431Sdim */ 3478245431SdimCINDEX_LINKAGE CXString clang_Cursor_getRawCommentText(CXCursor C); 3479245431Sdim 3480245431Sdim/** 3481245431Sdim * \brief Given a cursor that represents a documentable entity (e.g., 3482245431Sdim * declaration), return the associated \\brief paragraph; otherwise return the 3483245431Sdim * first paragraph. 3484245431Sdim */ 3485245431SdimCINDEX_LINKAGE CXString clang_Cursor_getBriefCommentText(CXCursor C); 3486245431Sdim 3487245431Sdim/** 3488245431Sdim * \brief Given a cursor that represents a documentable entity (e.g., 3489245431Sdim * declaration), return the associated parsed comment as a 3490245431Sdim * \c CXComment_FullComment AST node. 3491245431Sdim */ 3492245431SdimCINDEX_LINKAGE CXComment clang_Cursor_getParsedComment(CXCursor C); 3493245431Sdim 3494245431Sdim/** 3495202879Srdivacky * @} 3496202879Srdivacky */ 3497203955Srdivacky 3498203955Srdivacky/** 3499245431Sdim * \defgroup CINDEX_MODULE Module introspection 3500245431Sdim * 3501245431Sdim * The functions in this group provide access to information about modules. 3502245431Sdim * 3503245431Sdim * @{ 3504245431Sdim */ 3505245431Sdim 3506245431Sdimtypedef void *CXModule; 3507245431Sdim 3508245431Sdim/** 3509245431Sdim * \brief Given a CXCursor_ModuleImportDecl cursor, return the associated module. 3510245431Sdim */ 3511245431SdimCINDEX_LINKAGE CXModule clang_Cursor_getModule(CXCursor C); 3512245431Sdim 3513245431Sdim/** 3514245431Sdim * \param Module a module object. 3515245431Sdim * 3516252723Sdim * \returns the module file where the provided module object came from. 3517252723Sdim */ 3518252723SdimCINDEX_LINKAGE CXFile clang_Module_getASTFile(CXModule Module); 3519252723Sdim 3520252723Sdim/** 3521252723Sdim * \param Module a module object. 3522252723Sdim * 3523245431Sdim * \returns the parent of a sub-module or NULL if the given module is top-level, 3524245431Sdim * e.g. for 'std.vector' it will return the 'std' module. 3525245431Sdim */ 3526245431SdimCINDEX_LINKAGE CXModule clang_Module_getParent(CXModule Module); 3527245431Sdim 3528245431Sdim/** 3529245431Sdim * \param Module a module object. 3530245431Sdim * 3531245431Sdim * \returns the name of the module, e.g. for the 'std.vector' sub-module it 3532245431Sdim * will return "vector". 3533245431Sdim */ 3534245431SdimCINDEX_LINKAGE CXString clang_Module_getName(CXModule Module); 3535245431Sdim 3536245431Sdim/** 3537245431Sdim * \param Module a module object. 3538245431Sdim * 3539245431Sdim * \returns the full name of the module, e.g. "std.vector". 3540245431Sdim */ 3541245431SdimCINDEX_LINKAGE CXString clang_Module_getFullName(CXModule Module); 3542245431Sdim 3543245431Sdim/** 3544245431Sdim * \param Module a module object. 3545245431Sdim * 3546245431Sdim * \returns the number of top level headers associated with this module. 3547245431Sdim */ 3548252723SdimCINDEX_LINKAGE unsigned clang_Module_getNumTopLevelHeaders(CXTranslationUnit, 3549252723Sdim CXModule Module); 3550245431Sdim 3551245431Sdim/** 3552245431Sdim * \param Module a module object. 3553245431Sdim * 3554245431Sdim * \param Index top level header index (zero-based). 3555245431Sdim * 3556245431Sdim * \returns the specified top level header associated with the module. 3557245431Sdim */ 3558245431SdimCINDEX_LINKAGE 3559252723SdimCXFile clang_Module_getTopLevelHeader(CXTranslationUnit, 3560252723Sdim CXModule Module, unsigned Index); 3561245431Sdim 3562245431Sdim/** 3563245431Sdim * @} 3564245431Sdim */ 3565245431Sdim 3566245431Sdim/** 3567245431Sdim * \defgroup CINDEX_COMMENT Comment AST introspection 3568245431Sdim * 3569245431Sdim * The routines in this group provide access to information in the 3570245431Sdim * documentation comment ASTs. 3571245431Sdim * 3572245431Sdim * @{ 3573245431Sdim */ 3574245431Sdim 3575245431Sdim/** 3576245431Sdim * \brief Describes the type of the comment AST node (\c CXComment). A comment 3577245431Sdim * node can be considered block content (e. g., paragraph), inline content 3578245431Sdim * (plain text) or neither (the root AST node). 3579245431Sdim */ 3580245431Sdimenum CXCommentKind { 3581245431Sdim /** 3582245431Sdim * \brief Null comment. No AST node is constructed at the requested location 3583245431Sdim * because there is no text or a syntax error. 3584245431Sdim */ 3585245431Sdim CXComment_Null = 0, 3586245431Sdim 3587245431Sdim /** 3588245431Sdim * \brief Plain text. Inline content. 3589245431Sdim */ 3590245431Sdim CXComment_Text = 1, 3591245431Sdim 3592245431Sdim /** 3593245431Sdim * \brief A command with word-like arguments that is considered inline content. 3594245431Sdim * 3595245431Sdim * For example: \\c command. 3596245431Sdim */ 3597245431Sdim CXComment_InlineCommand = 2, 3598245431Sdim 3599245431Sdim /** 3600245431Sdim * \brief HTML start tag with attributes (name-value pairs). Considered 3601245431Sdim * inline content. 3602245431Sdim * 3603245431Sdim * For example: 3604245431Sdim * \verbatim 3605245431Sdim * <br> <br /> <a href="http://example.org/"> 3606245431Sdim * \endverbatim 3607245431Sdim */ 3608245431Sdim CXComment_HTMLStartTag = 3, 3609245431Sdim 3610245431Sdim /** 3611245431Sdim * \brief HTML end tag. Considered inline content. 3612245431Sdim * 3613245431Sdim * For example: 3614245431Sdim * \verbatim 3615245431Sdim * </a> 3616245431Sdim * \endverbatim 3617245431Sdim */ 3618245431Sdim CXComment_HTMLEndTag = 4, 3619245431Sdim 3620245431Sdim /** 3621245431Sdim * \brief A paragraph, contains inline comment. The paragraph itself is 3622245431Sdim * block content. 3623245431Sdim */ 3624245431Sdim CXComment_Paragraph = 5, 3625245431Sdim 3626245431Sdim /** 3627245431Sdim * \brief A command that has zero or more word-like arguments (number of 3628245431Sdim * word-like arguments depends on command name) and a paragraph as an 3629245431Sdim * argument. Block command is block content. 3630245431Sdim * 3631245431Sdim * Paragraph argument is also a child of the block command. 3632245431Sdim * 3633245431Sdim * For example: \\brief has 0 word-like arguments and a paragraph argument. 3634245431Sdim * 3635245431Sdim * AST nodes of special kinds that parser knows about (e. g., \\param 3636245431Sdim * command) have their own node kinds. 3637245431Sdim */ 3638245431Sdim CXComment_BlockCommand = 6, 3639245431Sdim 3640245431Sdim /** 3641245431Sdim * \brief A \\param or \\arg command that describes the function parameter 3642245431Sdim * (name, passing direction, description). 3643245431Sdim * 3644245431Sdim * For example: \\param [in] ParamName description. 3645245431Sdim */ 3646245431Sdim CXComment_ParamCommand = 7, 3647245431Sdim 3648245431Sdim /** 3649245431Sdim * \brief A \\tparam command that describes a template parameter (name and 3650245431Sdim * description). 3651245431Sdim * 3652245431Sdim * For example: \\tparam T description. 3653245431Sdim */ 3654245431Sdim CXComment_TParamCommand = 8, 3655245431Sdim 3656245431Sdim /** 3657245431Sdim * \brief A verbatim block command (e. g., preformatted code). Verbatim 3658245431Sdim * block has an opening and a closing command and contains multiple lines of 3659245431Sdim * text (\c CXComment_VerbatimBlockLine child nodes). 3660245431Sdim * 3661245431Sdim * For example: 3662245431Sdim * \\verbatim 3663245431Sdim * aaa 3664245431Sdim * \\endverbatim 3665245431Sdim */ 3666245431Sdim CXComment_VerbatimBlockCommand = 9, 3667245431Sdim 3668245431Sdim /** 3669245431Sdim * \brief A line of text that is contained within a 3670245431Sdim * CXComment_VerbatimBlockCommand node. 3671245431Sdim */ 3672245431Sdim CXComment_VerbatimBlockLine = 10, 3673245431Sdim 3674245431Sdim /** 3675245431Sdim * \brief A verbatim line command. Verbatim line has an opening command, 3676245431Sdim * a single line of text (up to the newline after the opening command) and 3677245431Sdim * has no closing command. 3678245431Sdim */ 3679245431Sdim CXComment_VerbatimLine = 11, 3680245431Sdim 3681245431Sdim /** 3682245431Sdim * \brief A full comment attached to a declaration, contains block content. 3683245431Sdim */ 3684245431Sdim CXComment_FullComment = 12 3685245431Sdim}; 3686245431Sdim 3687245431Sdim/** 3688245431Sdim * \brief The most appropriate rendering mode for an inline command, chosen on 3689245431Sdim * command semantics in Doxygen. 3690245431Sdim */ 3691245431Sdimenum CXCommentInlineCommandRenderKind { 3692245431Sdim /** 3693245431Sdim * \brief Command argument should be rendered in a normal font. 3694245431Sdim */ 3695245431Sdim CXCommentInlineCommandRenderKind_Normal, 3696245431Sdim 3697245431Sdim /** 3698245431Sdim * \brief Command argument should be rendered in a bold font. 3699245431Sdim */ 3700245431Sdim CXCommentInlineCommandRenderKind_Bold, 3701245431Sdim 3702245431Sdim /** 3703245431Sdim * \brief Command argument should be rendered in a monospaced font. 3704245431Sdim */ 3705245431Sdim CXCommentInlineCommandRenderKind_Monospaced, 3706245431Sdim 3707245431Sdim /** 3708245431Sdim * \brief Command argument should be rendered emphasized (typically italic 3709245431Sdim * font). 3710245431Sdim */ 3711245431Sdim CXCommentInlineCommandRenderKind_Emphasized 3712245431Sdim}; 3713245431Sdim 3714245431Sdim/** 3715245431Sdim * \brief Describes parameter passing direction for \\param or \\arg command. 3716245431Sdim */ 3717245431Sdimenum CXCommentParamPassDirection { 3718245431Sdim /** 3719245431Sdim * \brief The parameter is an input parameter. 3720245431Sdim */ 3721245431Sdim CXCommentParamPassDirection_In, 3722245431Sdim 3723245431Sdim /** 3724245431Sdim * \brief The parameter is an output parameter. 3725245431Sdim */ 3726245431Sdim CXCommentParamPassDirection_Out, 3727245431Sdim 3728245431Sdim /** 3729245431Sdim * \brief The parameter is an input and output parameter. 3730245431Sdim */ 3731245431Sdim CXCommentParamPassDirection_InOut 3732245431Sdim}; 3733245431Sdim 3734245431Sdim/** 3735245431Sdim * \param Comment AST node of any kind. 3736245431Sdim * 3737245431Sdim * \returns the type of the AST node. 3738245431Sdim */ 3739245431SdimCINDEX_LINKAGE enum CXCommentKind clang_Comment_getKind(CXComment Comment); 3740245431Sdim 3741245431Sdim/** 3742245431Sdim * \param Comment AST node of any kind. 3743245431Sdim * 3744245431Sdim * \returns number of children of the AST node. 3745245431Sdim */ 3746245431SdimCINDEX_LINKAGE unsigned clang_Comment_getNumChildren(CXComment Comment); 3747245431Sdim 3748245431Sdim/** 3749245431Sdim * \param Comment AST node of any kind. 3750245431Sdim * 3751245431Sdim * \param ChildIdx child index (zero-based). 3752245431Sdim * 3753245431Sdim * \returns the specified child of the AST node. 3754245431Sdim */ 3755245431SdimCINDEX_LINKAGE 3756245431SdimCXComment clang_Comment_getChild(CXComment Comment, unsigned ChildIdx); 3757245431Sdim 3758245431Sdim/** 3759245431Sdim * \brief A \c CXComment_Paragraph node is considered whitespace if it contains 3760245431Sdim * only \c CXComment_Text nodes that are empty or whitespace. 3761245431Sdim * 3762245431Sdim * Other AST nodes (except \c CXComment_Paragraph and \c CXComment_Text) are 3763245431Sdim * never considered whitespace. 3764245431Sdim * 3765245431Sdim * \returns non-zero if \c Comment is whitespace. 3766245431Sdim */ 3767245431SdimCINDEX_LINKAGE unsigned clang_Comment_isWhitespace(CXComment Comment); 3768245431Sdim 3769245431Sdim/** 3770245431Sdim * \returns non-zero if \c Comment is inline content and has a newline 3771245431Sdim * immediately following it in the comment text. Newlines between paragraphs 3772245431Sdim * do not count. 3773245431Sdim */ 3774245431SdimCINDEX_LINKAGE 3775245431Sdimunsigned clang_InlineContentComment_hasTrailingNewline(CXComment Comment); 3776245431Sdim 3777245431Sdim/** 3778245431Sdim * \param Comment a \c CXComment_Text AST node. 3779245431Sdim * 3780245431Sdim * \returns text contained in the AST node. 3781245431Sdim */ 3782245431SdimCINDEX_LINKAGE CXString clang_TextComment_getText(CXComment Comment); 3783245431Sdim 3784245431Sdim/** 3785245431Sdim * \param Comment a \c CXComment_InlineCommand AST node. 3786245431Sdim * 3787245431Sdim * \returns name of the inline command. 3788245431Sdim */ 3789245431SdimCINDEX_LINKAGE 3790245431SdimCXString clang_InlineCommandComment_getCommandName(CXComment Comment); 3791245431Sdim 3792245431Sdim/** 3793245431Sdim * \param Comment a \c CXComment_InlineCommand AST node. 3794245431Sdim * 3795245431Sdim * \returns the most appropriate rendering mode, chosen on command 3796245431Sdim * semantics in Doxygen. 3797245431Sdim */ 3798245431SdimCINDEX_LINKAGE enum CXCommentInlineCommandRenderKind 3799245431Sdimclang_InlineCommandComment_getRenderKind(CXComment Comment); 3800245431Sdim 3801245431Sdim/** 3802245431Sdim * \param Comment a \c CXComment_InlineCommand AST node. 3803245431Sdim * 3804245431Sdim * \returns number of command arguments. 3805245431Sdim */ 3806245431SdimCINDEX_LINKAGE 3807245431Sdimunsigned clang_InlineCommandComment_getNumArgs(CXComment Comment); 3808245431Sdim 3809245431Sdim/** 3810245431Sdim * \param Comment a \c CXComment_InlineCommand AST node. 3811245431Sdim * 3812245431Sdim * \param ArgIdx argument index (zero-based). 3813245431Sdim * 3814245431Sdim * \returns text of the specified argument. 3815245431Sdim */ 3816245431SdimCINDEX_LINKAGE 3817245431SdimCXString clang_InlineCommandComment_getArgText(CXComment Comment, 3818245431Sdim unsigned ArgIdx); 3819245431Sdim 3820245431Sdim/** 3821245431Sdim * \param Comment a \c CXComment_HTMLStartTag or \c CXComment_HTMLEndTag AST 3822245431Sdim * node. 3823245431Sdim * 3824245431Sdim * \returns HTML tag name. 3825245431Sdim */ 3826245431SdimCINDEX_LINKAGE CXString clang_HTMLTagComment_getTagName(CXComment Comment); 3827245431Sdim 3828245431Sdim/** 3829245431Sdim * \param Comment a \c CXComment_HTMLStartTag AST node. 3830245431Sdim * 3831245431Sdim * \returns non-zero if tag is self-closing (for example, <br />). 3832245431Sdim */ 3833245431SdimCINDEX_LINKAGE 3834245431Sdimunsigned clang_HTMLStartTagComment_isSelfClosing(CXComment Comment); 3835245431Sdim 3836245431Sdim/** 3837245431Sdim * \param Comment a \c CXComment_HTMLStartTag AST node. 3838245431Sdim * 3839245431Sdim * \returns number of attributes (name-value pairs) attached to the start tag. 3840245431Sdim */ 3841245431SdimCINDEX_LINKAGE unsigned clang_HTMLStartTag_getNumAttrs(CXComment Comment); 3842245431Sdim 3843245431Sdim/** 3844245431Sdim * \param Comment a \c CXComment_HTMLStartTag AST node. 3845245431Sdim * 3846245431Sdim * \param AttrIdx attribute index (zero-based). 3847245431Sdim * 3848245431Sdim * \returns name of the specified attribute. 3849245431Sdim */ 3850245431SdimCINDEX_LINKAGE 3851245431SdimCXString clang_HTMLStartTag_getAttrName(CXComment Comment, unsigned AttrIdx); 3852245431Sdim 3853245431Sdim/** 3854245431Sdim * \param Comment a \c CXComment_HTMLStartTag AST node. 3855245431Sdim * 3856245431Sdim * \param AttrIdx attribute index (zero-based). 3857245431Sdim * 3858245431Sdim * \returns value of the specified attribute. 3859245431Sdim */ 3860245431SdimCINDEX_LINKAGE 3861245431SdimCXString clang_HTMLStartTag_getAttrValue(CXComment Comment, unsigned AttrIdx); 3862245431Sdim 3863245431Sdim/** 3864245431Sdim * \param Comment a \c CXComment_BlockCommand AST node. 3865245431Sdim * 3866245431Sdim * \returns name of the block command. 3867245431Sdim */ 3868245431SdimCINDEX_LINKAGE 3869245431SdimCXString clang_BlockCommandComment_getCommandName(CXComment Comment); 3870245431Sdim 3871245431Sdim/** 3872245431Sdim * \param Comment a \c CXComment_BlockCommand AST node. 3873245431Sdim * 3874245431Sdim * \returns number of word-like arguments. 3875245431Sdim */ 3876245431SdimCINDEX_LINKAGE 3877245431Sdimunsigned clang_BlockCommandComment_getNumArgs(CXComment Comment); 3878245431Sdim 3879245431Sdim/** 3880245431Sdim * \param Comment a \c CXComment_BlockCommand AST node. 3881245431Sdim * 3882245431Sdim * \param ArgIdx argument index (zero-based). 3883245431Sdim * 3884245431Sdim * \returns text of the specified word-like argument. 3885245431Sdim */ 3886245431SdimCINDEX_LINKAGE 3887245431SdimCXString clang_BlockCommandComment_getArgText(CXComment Comment, 3888245431Sdim unsigned ArgIdx); 3889245431Sdim 3890245431Sdim/** 3891245431Sdim * \param Comment a \c CXComment_BlockCommand or 3892245431Sdim * \c CXComment_VerbatimBlockCommand AST node. 3893245431Sdim * 3894245431Sdim * \returns paragraph argument of the block command. 3895245431Sdim */ 3896245431SdimCINDEX_LINKAGE 3897245431SdimCXComment clang_BlockCommandComment_getParagraph(CXComment Comment); 3898245431Sdim 3899245431Sdim/** 3900245431Sdim * \param Comment a \c CXComment_ParamCommand AST node. 3901245431Sdim * 3902245431Sdim * \returns parameter name. 3903245431Sdim */ 3904245431SdimCINDEX_LINKAGE 3905245431SdimCXString clang_ParamCommandComment_getParamName(CXComment Comment); 3906245431Sdim 3907245431Sdim/** 3908245431Sdim * \param Comment a \c CXComment_ParamCommand AST node. 3909245431Sdim * 3910245431Sdim * \returns non-zero if the parameter that this AST node represents was found 3911245431Sdim * in the function prototype and \c clang_ParamCommandComment_getParamIndex 3912245431Sdim * function will return a meaningful value. 3913245431Sdim */ 3914245431SdimCINDEX_LINKAGE 3915245431Sdimunsigned clang_ParamCommandComment_isParamIndexValid(CXComment Comment); 3916245431Sdim 3917245431Sdim/** 3918245431Sdim * \param Comment a \c CXComment_ParamCommand AST node. 3919245431Sdim * 3920245431Sdim * \returns zero-based parameter index in function prototype. 3921245431Sdim */ 3922245431SdimCINDEX_LINKAGE 3923245431Sdimunsigned clang_ParamCommandComment_getParamIndex(CXComment Comment); 3924245431Sdim 3925245431Sdim/** 3926245431Sdim * \param Comment a \c CXComment_ParamCommand AST node. 3927245431Sdim * 3928245431Sdim * \returns non-zero if parameter passing direction was specified explicitly in 3929245431Sdim * the comment. 3930245431Sdim */ 3931245431SdimCINDEX_LINKAGE 3932245431Sdimunsigned clang_ParamCommandComment_isDirectionExplicit(CXComment Comment); 3933245431Sdim 3934245431Sdim/** 3935245431Sdim * \param Comment a \c CXComment_ParamCommand AST node. 3936245431Sdim * 3937245431Sdim * \returns parameter passing direction. 3938245431Sdim */ 3939245431SdimCINDEX_LINKAGE 3940245431Sdimenum CXCommentParamPassDirection clang_ParamCommandComment_getDirection( 3941245431Sdim CXComment Comment); 3942245431Sdim 3943245431Sdim/** 3944245431Sdim * \param Comment a \c CXComment_TParamCommand AST node. 3945245431Sdim * 3946245431Sdim * \returns template parameter name. 3947245431Sdim */ 3948245431SdimCINDEX_LINKAGE 3949245431SdimCXString clang_TParamCommandComment_getParamName(CXComment Comment); 3950245431Sdim 3951245431Sdim/** 3952245431Sdim * \param Comment a \c CXComment_TParamCommand AST node. 3953245431Sdim * 3954245431Sdim * \returns non-zero if the parameter that this AST node represents was found 3955245431Sdim * in the template parameter list and 3956245431Sdim * \c clang_TParamCommandComment_getDepth and 3957245431Sdim * \c clang_TParamCommandComment_getIndex functions will return a meaningful 3958245431Sdim * value. 3959245431Sdim */ 3960245431SdimCINDEX_LINKAGE 3961245431Sdimunsigned clang_TParamCommandComment_isParamPositionValid(CXComment Comment); 3962245431Sdim 3963245431Sdim/** 3964245431Sdim * \param Comment a \c CXComment_TParamCommand AST node. 3965245431Sdim * 3966245431Sdim * \returns zero-based nesting depth of this parameter in the template parameter list. 3967245431Sdim * 3968245431Sdim * For example, 3969245431Sdim * \verbatim 3970245431Sdim * template<typename C, template<typename T> class TT> 3971245431Sdim * void test(TT<int> aaa); 3972245431Sdim * \endverbatim 3973245431Sdim * for C and TT nesting depth is 0, 3974245431Sdim * for T nesting depth is 1. 3975245431Sdim */ 3976245431SdimCINDEX_LINKAGE 3977245431Sdimunsigned clang_TParamCommandComment_getDepth(CXComment Comment); 3978245431Sdim 3979245431Sdim/** 3980245431Sdim * \param Comment a \c CXComment_TParamCommand AST node. 3981245431Sdim * 3982245431Sdim * \returns zero-based parameter index in the template parameter list at a 3983245431Sdim * given nesting depth. 3984245431Sdim * 3985245431Sdim * For example, 3986245431Sdim * \verbatim 3987245431Sdim * template<typename C, template<typename T> class TT> 3988245431Sdim * void test(TT<int> aaa); 3989245431Sdim * \endverbatim 3990245431Sdim * for C and TT nesting depth is 0, so we can ask for index at depth 0: 3991245431Sdim * at depth 0 C's index is 0, TT's index is 1. 3992245431Sdim * 3993245431Sdim * For T nesting depth is 1, so we can ask for index at depth 0 and 1: 3994245431Sdim * at depth 0 T's index is 1 (same as TT's), 3995245431Sdim * at depth 1 T's index is 0. 3996245431Sdim */ 3997245431SdimCINDEX_LINKAGE 3998245431Sdimunsigned clang_TParamCommandComment_getIndex(CXComment Comment, unsigned Depth); 3999245431Sdim 4000245431Sdim/** 4001245431Sdim * \param Comment a \c CXComment_VerbatimBlockLine AST node. 4002245431Sdim * 4003245431Sdim * \returns text contained in the AST node. 4004245431Sdim */ 4005245431SdimCINDEX_LINKAGE 4006245431SdimCXString clang_VerbatimBlockLineComment_getText(CXComment Comment); 4007245431Sdim 4008245431Sdim/** 4009245431Sdim * \param Comment a \c CXComment_VerbatimLine AST node. 4010245431Sdim * 4011245431Sdim * \returns text contained in the AST node. 4012245431Sdim */ 4013245431SdimCINDEX_LINKAGE CXString clang_VerbatimLineComment_getText(CXComment Comment); 4014245431Sdim 4015245431Sdim/** 4016245431Sdim * \brief Convert an HTML tag AST node to string. 4017245431Sdim * 4018245431Sdim * \param Comment a \c CXComment_HTMLStartTag or \c CXComment_HTMLEndTag AST 4019245431Sdim * node. 4020245431Sdim * 4021245431Sdim * \returns string containing an HTML tag. 4022245431Sdim */ 4023245431SdimCINDEX_LINKAGE CXString clang_HTMLTagComment_getAsString(CXComment Comment); 4024245431Sdim 4025245431Sdim/** 4026245431Sdim * \brief Convert a given full parsed comment to an HTML fragment. 4027245431Sdim * 4028245431Sdim * Specific details of HTML layout are subject to change. Don't try to parse 4029245431Sdim * this HTML back into an AST, use other APIs instead. 4030245431Sdim * 4031245431Sdim * Currently the following CSS classes are used: 4032245431Sdim * \li "para-brief" for \\brief paragraph and equivalent commands; 4033245431Sdim * \li "para-returns" for \\returns paragraph and equivalent commands; 4034245431Sdim * \li "word-returns" for the "Returns" word in \\returns paragraph. 4035245431Sdim * 4036245431Sdim * Function argument documentation is rendered as a \<dl\> list with arguments 4037245431Sdim * sorted in function prototype order. CSS classes used: 4038245431Sdim * \li "param-name-index-NUMBER" for parameter name (\<dt\>); 4039245431Sdim * \li "param-descr-index-NUMBER" for parameter description (\<dd\>); 4040245431Sdim * \li "param-name-index-invalid" and "param-descr-index-invalid" are used if 4041245431Sdim * parameter index is invalid. 4042245431Sdim * 4043245431Sdim * Template parameter documentation is rendered as a \<dl\> list with 4044245431Sdim * parameters sorted in template parameter list order. CSS classes used: 4045245431Sdim * \li "tparam-name-index-NUMBER" for parameter name (\<dt\>); 4046245431Sdim * \li "tparam-descr-index-NUMBER" for parameter description (\<dd\>); 4047245431Sdim * \li "tparam-name-index-other" and "tparam-descr-index-other" are used for 4048245431Sdim * names inside template template parameters; 4049245431Sdim * \li "tparam-name-index-invalid" and "tparam-descr-index-invalid" are used if 4050245431Sdim * parameter position is invalid. 4051245431Sdim * 4052245431Sdim * \param Comment a \c CXComment_FullComment AST node. 4053245431Sdim * 4054245431Sdim * \returns string containing an HTML fragment. 4055245431Sdim */ 4056245431SdimCINDEX_LINKAGE CXString clang_FullComment_getAsHTML(CXComment Comment); 4057245431Sdim 4058245431Sdim/** 4059245431Sdim * \brief Convert a given full parsed comment to an XML document. 4060245431Sdim * 4061245431Sdim * A Relax NG schema for the XML can be found in comment-xml-schema.rng file 4062245431Sdim * inside clang source tree. 4063245431Sdim * 4064245431Sdim * \param Comment a \c CXComment_FullComment AST node. 4065245431Sdim * 4066245431Sdim * \returns string containing an XML document. 4067245431Sdim */ 4068245431SdimCINDEX_LINKAGE CXString clang_FullComment_getAsXML(CXComment Comment); 4069245431Sdim 4070245431Sdim/** 4071245431Sdim * @} 4072245431Sdim */ 4073245431Sdim 4074245431Sdim/** 4075208600Srdivacky * \defgroup CINDEX_CPP C++ AST introspection 4076208600Srdivacky * 4077208600Srdivacky * The routines in this group provide access information in the ASTs specific 4078208600Srdivacky * to C++ language features. 4079208600Srdivacky * 4080208600Srdivacky * @{ 4081208600Srdivacky */ 4082208600Srdivacky 4083208600Srdivacky/** 4084263509Sdim * \brief Determine if a C++ member function or member function template is 4085263509Sdim * pure virtual. 4086263509Sdim */ 4087263509SdimCINDEX_LINKAGE unsigned clang_CXXMethod_isPureVirtual(CXCursor C); 4088263509Sdim 4089263509Sdim/** 4090212904Sdim * \brief Determine if a C++ member function or member function template is 4091212904Sdim * declared 'static'. 4092208600Srdivacky */ 4093208600SrdivackyCINDEX_LINKAGE unsigned clang_CXXMethod_isStatic(CXCursor C); 4094208600Srdivacky 4095208600Srdivacky/** 4096223017Sdim * \brief Determine if a C++ member function or member function template is 4097223017Sdim * explicitly declared 'virtual' or if it overrides a virtual method from 4098223017Sdim * one of the base classes. 4099223017Sdim */ 4100223017SdimCINDEX_LINKAGE unsigned clang_CXXMethod_isVirtual(CXCursor C); 4101223017Sdim 4102223017Sdim/** 4103212904Sdim * \brief Given a cursor that represents a template, determine 4104212904Sdim * the cursor kind of the specializations would be generated by instantiating 4105212904Sdim * the template. 4106212904Sdim * 4107212904Sdim * This routine can be used to determine what flavor of function template, 4108212904Sdim * class template, or class template partial specialization is stored in the 4109212904Sdim * cursor. For example, it can describe whether a class template cursor is 4110212904Sdim * declared with "struct", "class" or "union". 4111212904Sdim * 4112212904Sdim * \param C The cursor to query. This cursor should represent a template 4113212904Sdim * declaration. 4114212904Sdim * 4115212904Sdim * \returns The cursor kind of the specializations that would be generated 4116212904Sdim * by instantiating the template \p C. If \p C is not a template, returns 4117212904Sdim * \c CXCursor_NoDeclFound. 4118212904Sdim */ 4119212904SdimCINDEX_LINKAGE enum CXCursorKind clang_getTemplateCursorKind(CXCursor C); 4120212904Sdim 4121212904Sdim/** 4122212904Sdim * \brief Given a cursor that may represent a specialization or instantiation 4123212904Sdim * of a template, retrieve the cursor that represents the template that it 4124212904Sdim * specializes or from which it was instantiated. 4125212904Sdim * 4126212904Sdim * This routine determines the template involved both for explicit 4127212904Sdim * specializations of templates and for implicit instantiations of the template, 4128212904Sdim * both of which are referred to as "specializations". For a class template 4129212904Sdim * specialization (e.g., \c std::vector<bool>), this routine will return 4130212904Sdim * either the primary template (\c std::vector) or, if the specialization was 4131212904Sdim * instantiated from a class template partial specialization, the class template 4132212904Sdim * partial specialization. For a class template partial specialization and a 4133212904Sdim * function template specialization (including instantiations), this 4134212904Sdim * this routine will return the specialized template. 4135212904Sdim * 4136212904Sdim * For members of a class template (e.g., member functions, member classes, or 4137212904Sdim * static data members), returns the specialized or instantiated member. 4138212904Sdim * Although not strictly "templates" in the C++ language, members of class 4139212904Sdim * templates have the same notions of specializations and instantiations that 4140212904Sdim * templates do, so this routine treats them similarly. 4141212904Sdim * 4142212904Sdim * \param C A cursor that may be a specialization of a template or a member 4143212904Sdim * of a template. 4144212904Sdim * 4145212904Sdim * \returns If the given cursor is a specialization or instantiation of a 4146212904Sdim * template or a member thereof, the template or member that it specializes or 4147212904Sdim * from which it was instantiated. Otherwise, returns a NULL cursor. 4148212904Sdim */ 4149212904SdimCINDEX_LINKAGE CXCursor clang_getSpecializedCursorTemplate(CXCursor C); 4150226890Sdim 4151226890Sdim/** 4152226890Sdim * \brief Given a cursor that references something else, return the source range 4153226890Sdim * covering that reference. 4154226890Sdim * 4155226890Sdim * \param C A cursor pointing to a member reference, a declaration reference, or 4156226890Sdim * an operator call. 4157226890Sdim * \param NameFlags A bitset with three independent flags: 4158226890Sdim * CXNameRange_WantQualifier, CXNameRange_WantTemplateArgs, and 4159226890Sdim * CXNameRange_WantSinglePiece. 4160226890Sdim * \param PieceIndex For contiguous names or when passing the flag 4161226890Sdim * CXNameRange_WantSinglePiece, only one piece with index 0 is 4162226890Sdim * available. When the CXNameRange_WantSinglePiece flag is not passed for a 4163245431Sdim * non-contiguous names, this index can be used to retrieve the individual 4164226890Sdim * pieces of the name. See also CXNameRange_WantSinglePiece. 4165226890Sdim * 4166226890Sdim * \returns The piece of the name pointed to by the given cursor. If there is no 4167226890Sdim * name, or if the PieceIndex is out-of-range, a null-cursor will be returned. 4168226890Sdim */ 4169226890SdimCINDEX_LINKAGE CXSourceRange clang_getCursorReferenceNameRange(CXCursor C, 4170226890Sdim unsigned NameFlags, 4171226890Sdim unsigned PieceIndex); 4172226890Sdim 4173226890Sdimenum CXNameRefFlags { 4174226890Sdim /** 4175226890Sdim * \brief Include the nested-name-specifier, e.g. Foo:: in x.Foo::y, in the 4176226890Sdim * range. 4177226890Sdim */ 4178226890Sdim CXNameRange_WantQualifier = 0x1, 4179212904Sdim 4180226890Sdim /** 4181245431Sdim * \brief Include the explicit template arguments, e.g. \<int> in x.f<int>, 4182245431Sdim * in the range. 4183226890Sdim */ 4184226890Sdim CXNameRange_WantTemplateArgs = 0x2, 4185226890Sdim 4186226890Sdim /** 4187226890Sdim * \brief If the name is non-contiguous, return the full spanning range. 4188226890Sdim * 4189226890Sdim * Non-contiguous names occur in Objective-C when a selector with two or more 4190226890Sdim * parameters is used, or in C++ when using an operator: 4191226890Sdim * \code 4192226890Sdim * [object doSomething:here withValue:there]; // ObjC 4193226890Sdim * return some_vector[1]; // C++ 4194226890Sdim * \endcode 4195226890Sdim */ 4196226890Sdim CXNameRange_WantSinglePiece = 0x4 4197226890Sdim}; 4198226890Sdim 4199212904Sdim/** 4200208600Srdivacky * @} 4201208600Srdivacky */ 4202208600Srdivacky 4203208600Srdivacky/** 4204203955Srdivacky * \defgroup CINDEX_LEX Token extraction and manipulation 4205203955Srdivacky * 4206203955Srdivacky * The routines in this group provide access to the tokens within a 4207203955Srdivacky * translation unit, along with a semantic mapping of those tokens to 4208203955Srdivacky * their corresponding cursors. 4209203955Srdivacky * 4210203955Srdivacky * @{ 4211203955Srdivacky */ 4212203955Srdivacky 4213203955Srdivacky/** 4214203955Srdivacky * \brief Describes a kind of token. 4215203955Srdivacky */ 4216203955Srdivackytypedef enum CXTokenKind { 4217203955Srdivacky /** 4218203955Srdivacky * \brief A token that contains some kind of punctuation. 4219203955Srdivacky */ 4220203955Srdivacky CXToken_Punctuation, 4221205219Srdivacky 4222203955Srdivacky /** 4223203955Srdivacky * \brief A language keyword. 4224203955Srdivacky */ 4225203955Srdivacky CXToken_Keyword, 4226205219Srdivacky 4227203955Srdivacky /** 4228203955Srdivacky * \brief An identifier (that is not a keyword). 4229203955Srdivacky */ 4230203955Srdivacky CXToken_Identifier, 4231205219Srdivacky 4232203955Srdivacky /** 4233203955Srdivacky * \brief A numeric, string, or character literal. 4234203955Srdivacky */ 4235203955Srdivacky CXToken_Literal, 4236205219Srdivacky 4237203955Srdivacky /** 4238203955Srdivacky * \brief A comment. 4239203955Srdivacky */ 4240203955Srdivacky CXToken_Comment 4241203955Srdivacky} CXTokenKind; 4242203955Srdivacky 4243202879Srdivacky/** 4244203955Srdivacky * \brief Describes a single preprocessing token. 4245203955Srdivacky */ 4246203955Srdivackytypedef struct { 4247203955Srdivacky unsigned int_data[4]; 4248203955Srdivacky void *ptr_data; 4249203955Srdivacky} CXToken; 4250203955Srdivacky 4251203955Srdivacky/** 4252203955Srdivacky * \brief Determine the kind of the given token. 4253203955Srdivacky */ 4254203955SrdivackyCINDEX_LINKAGE CXTokenKind clang_getTokenKind(CXToken); 4255205219Srdivacky 4256203955Srdivacky/** 4257203955Srdivacky * \brief Determine the spelling of the given token. 4258203955Srdivacky * 4259203955Srdivacky * The spelling of a token is the textual representation of that token, e.g., 4260203955Srdivacky * the text of an identifier or keyword. 4261203955Srdivacky */ 4262203955SrdivackyCINDEX_LINKAGE CXString clang_getTokenSpelling(CXTranslationUnit, CXToken); 4263205219Srdivacky 4264203955Srdivacky/** 4265203955Srdivacky * \brief Retrieve the source location of the given token. 4266203955Srdivacky */ 4267205219SrdivackyCINDEX_LINKAGE CXSourceLocation clang_getTokenLocation(CXTranslationUnit, 4268203955Srdivacky CXToken); 4269205219Srdivacky 4270203955Srdivacky/** 4271203955Srdivacky * \brief Retrieve a source range that covers the given token. 4272203955Srdivacky */ 4273203955SrdivackyCINDEX_LINKAGE CXSourceRange clang_getTokenExtent(CXTranslationUnit, CXToken); 4274203955Srdivacky 4275203955Srdivacky/** 4276203955Srdivacky * \brief Tokenize the source code described by the given range into raw 4277203955Srdivacky * lexical tokens. 4278203955Srdivacky * 4279203955Srdivacky * \param TU the translation unit whose text is being tokenized. 4280203955Srdivacky * 4281203955Srdivacky * \param Range the source range in which text should be tokenized. All of the 4282203955Srdivacky * tokens produced by tokenization will fall within this source range, 4283203955Srdivacky * 4284203955Srdivacky * \param Tokens this pointer will be set to point to the array of tokens 4285203955Srdivacky * that occur within the given source range. The returned pointer must be 4286203955Srdivacky * freed with clang_disposeTokens() before the translation unit is destroyed. 4287203955Srdivacky * 4288203955Srdivacky * \param NumTokens will be set to the number of tokens in the \c *Tokens 4289203955Srdivacky * array. 4290203955Srdivacky * 4291203955Srdivacky */ 4292203955SrdivackyCINDEX_LINKAGE void clang_tokenize(CXTranslationUnit TU, CXSourceRange Range, 4293203955Srdivacky CXToken **Tokens, unsigned *NumTokens); 4294205219Srdivacky 4295203955Srdivacky/** 4296203955Srdivacky * \brief Annotate the given set of tokens by providing cursors for each token 4297203955Srdivacky * that can be mapped to a specific entity within the abstract syntax tree. 4298203955Srdivacky * 4299203955Srdivacky * This token-annotation routine is equivalent to invoking 4300203955Srdivacky * clang_getCursor() for the source locations of each of the 4301203955Srdivacky * tokens. The cursors provided are filtered, so that only those 4302203955Srdivacky * cursors that have a direct correspondence to the token are 4303203955Srdivacky * accepted. For example, given a function call \c f(x), 4304203955Srdivacky * clang_getCursor() would provide the following cursors: 4305203955Srdivacky * 4306203955Srdivacky * * when the cursor is over the 'f', a DeclRefExpr cursor referring to 'f'. 4307203955Srdivacky * * when the cursor is over the '(' or the ')', a CallExpr referring to 'f'. 4308203955Srdivacky * * when the cursor is over the 'x', a DeclRefExpr cursor referring to 'x'. 4309203955Srdivacky * 4310203955Srdivacky * Only the first and last of these cursors will occur within the 4311203955Srdivacky * annotate, since the tokens "f" and "x' directly refer to a function 4312203955Srdivacky * and a variable, respectively, but the parentheses are just a small 4313203955Srdivacky * part of the full syntax of the function call expression, which is 4314203955Srdivacky * not provided as an annotation. 4315203955Srdivacky * 4316203955Srdivacky * \param TU the translation unit that owns the given tokens. 4317203955Srdivacky * 4318203955Srdivacky * \param Tokens the set of tokens to annotate. 4319203955Srdivacky * 4320203955Srdivacky * \param NumTokens the number of tokens in \p Tokens. 4321203955Srdivacky * 4322203955Srdivacky * \param Cursors an array of \p NumTokens cursors, whose contents will be 4323203955Srdivacky * replaced with the cursors corresponding to each token. 4324203955Srdivacky */ 4325203955SrdivackyCINDEX_LINKAGE void clang_annotateTokens(CXTranslationUnit TU, 4326203955Srdivacky CXToken *Tokens, unsigned NumTokens, 4327203955Srdivacky CXCursor *Cursors); 4328205219Srdivacky 4329203955Srdivacky/** 4330203955Srdivacky * \brief Free the given set of tokens. 4331203955Srdivacky */ 4332205219SrdivackyCINDEX_LINKAGE void clang_disposeTokens(CXTranslationUnit TU, 4333203955Srdivacky CXToken *Tokens, unsigned NumTokens); 4334205219Srdivacky 4335203955Srdivacky/** 4336203955Srdivacky * @} 4337203955Srdivacky */ 4338205219Srdivacky 4339203955Srdivacky/** 4340202879Srdivacky * \defgroup CINDEX_DEBUG Debugging facilities 4341202879Srdivacky * 4342202879Srdivacky * These routines are used for testing and debugging, only, and should not 4343202879Srdivacky * be relied upon. 4344202879Srdivacky * 4345202879Srdivacky * @{ 4346202879Srdivacky */ 4347203955Srdivacky 4348198092Srdivacky/* for debug/testing */ 4349204643SrdivackyCINDEX_LINKAGE CXString clang_getCursorKindSpelling(enum CXCursorKind Kind); 4350203955SrdivackyCINDEX_LINKAGE void clang_getDefinitionSpellingAndExtent(CXCursor, 4351203955Srdivacky const char **startBuf, 4352198092Srdivacky const char **endBuf, 4353198092Srdivacky unsigned *startLine, 4354198092Srdivacky unsigned *startColumn, 4355198092Srdivacky unsigned *endLine, 4356198092Srdivacky unsigned *endColumn); 4357204643SrdivackyCINDEX_LINKAGE void clang_enableStackTraces(void); 4358218893SdimCINDEX_LINKAGE void clang_executeOnThread(void (*fn)(void*), void *user_data, 4359218893Sdim unsigned stack_size); 4360218893Sdim 4361202879Srdivacky/** 4362202879Srdivacky * @} 4363198092Srdivacky */ 4364203955Srdivacky 4365199482Srdivacky/** 4366202879Srdivacky * \defgroup CINDEX_CODE_COMPLET Code completion 4367202879Srdivacky * 4368202879Srdivacky * Code completion involves taking an (incomplete) source file, along with 4369202879Srdivacky * knowledge of where the user is actively editing that file, and suggesting 4370202879Srdivacky * syntactically- and semantically-valid constructs that the user might want to 4371202879Srdivacky * use at that particular point in the source code. These data structures and 4372202879Srdivacky * routines provide support for code completion. 4373202879Srdivacky * 4374202879Srdivacky * @{ 4375202879Srdivacky */ 4376203955Srdivacky 4377202879Srdivacky/** 4378199482Srdivacky * \brief A semantic string that describes a code-completion result. 4379199482Srdivacky * 4380199482Srdivacky * A semantic string that describes the formatting of a code-completion 4381199482Srdivacky * result as a single "template" of text that should be inserted into the 4382199482Srdivacky * source buffer when a particular code-completion result is selected. 4383199482Srdivacky * Each semantic string is made up of some number of "chunks", each of which 4384199482Srdivacky * contains some text along with a description of what that text means, e.g., 4385199482Srdivacky * the name of the entity being referenced, whether the text chunk is part of 4386199482Srdivacky * the template, or whether it is a "placeholder" that the user should replace 4387199482Srdivacky * with actual code,of a specific kind. See \c CXCompletionChunkKind for a 4388203955Srdivacky * description of the different kinds of chunks. 4389199482Srdivacky */ 4390199482Srdivackytypedef void *CXCompletionString; 4391203955Srdivacky 4392199482Srdivacky/** 4393199482Srdivacky * \brief A single result of code completion. 4394199482Srdivacky */ 4395199482Srdivackytypedef struct { 4396199482Srdivacky /** 4397203955Srdivacky * \brief The kind of entity that this completion refers to. 4398199482Srdivacky * 4399203955Srdivacky * The cursor kind will be a macro, keyword, or a declaration (one of the 4400199482Srdivacky * *Decl cursor kinds), describing the entity that the completion is 4401199482Srdivacky * referring to. 4402199482Srdivacky * 4403199482Srdivacky * \todo In the future, we would like to provide a full cursor, to allow 4404199482Srdivacky * the client to extract additional information from declaration. 4405199482Srdivacky */ 4406199482Srdivacky enum CXCursorKind CursorKind; 4407203955Srdivacky 4408203955Srdivacky /** 4409199482Srdivacky * \brief The code-completion string that describes how to insert this 4410199482Srdivacky * code-completion result into the editing buffer. 4411199482Srdivacky */ 4412199482Srdivacky CXCompletionString CompletionString; 4413199482Srdivacky} CXCompletionResult; 4414199482Srdivacky 4415199482Srdivacky/** 4416199482Srdivacky * \brief Describes a single piece of text within a code-completion string. 4417199482Srdivacky * 4418203955Srdivacky * Each "chunk" within a code-completion string (\c CXCompletionString) is 4419203955Srdivacky * either a piece of text with a specific "kind" that describes how that text 4420199482Srdivacky * should be interpreted by the client or is another completion string. 4421199482Srdivacky */ 4422199482Srdivackyenum CXCompletionChunkKind { 4423199482Srdivacky /** 4424199482Srdivacky * \brief A code-completion string that describes "optional" text that 4425199482Srdivacky * could be a part of the template (but is not required). 4426199482Srdivacky * 4427199482Srdivacky * The Optional chunk is the only kind of chunk that has a code-completion 4428203955Srdivacky * string for its representation, which is accessible via 4429199482Srdivacky * \c clang_getCompletionChunkCompletionString(). The code-completion string 4430199482Srdivacky * describes an additional part of the template that is completely optional. 4431199482Srdivacky * For example, optional chunks can be used to describe the placeholders for 4432199482Srdivacky * arguments that match up with defaulted function parameters, e.g. given: 4433199482Srdivacky * 4434199482Srdivacky * \code 4435199482Srdivacky * void f(int x, float y = 3.14, double z = 2.71828); 4436199482Srdivacky * \endcode 4437199482Srdivacky * 4438199482Srdivacky * The code-completion string for this function would contain: 4439199482Srdivacky * - a TypedText chunk for "f". 4440199482Srdivacky * - a LeftParen chunk for "(". 4441199482Srdivacky * - a Placeholder chunk for "int x" 4442199482Srdivacky * - an Optional chunk containing the remaining defaulted arguments, e.g., 4443199482Srdivacky * - a Comma chunk for "," 4444204643Srdivacky * - a Placeholder chunk for "float y" 4445199482Srdivacky * - an Optional chunk containing the last defaulted argument: 4446199482Srdivacky * - a Comma chunk for "," 4447199482Srdivacky * - a Placeholder chunk for "double z" 4448199482Srdivacky * - a RightParen chunk for ")" 4449199482Srdivacky * 4450204643Srdivacky * There are many ways to handle Optional chunks. Two simple approaches are: 4451199482Srdivacky * - Completely ignore optional chunks, in which case the template for the 4452199482Srdivacky * function "f" would only include the first parameter ("int x"). 4453199482Srdivacky * - Fully expand all optional chunks, in which case the template for the 4454199482Srdivacky * function "f" would have all of the parameters. 4455199482Srdivacky */ 4456199482Srdivacky CXCompletionChunk_Optional, 4457199482Srdivacky /** 4458199482Srdivacky * \brief Text that a user would be expected to type to get this 4459203955Srdivacky * code-completion result. 4460199482Srdivacky * 4461203955Srdivacky * There will be exactly one "typed text" chunk in a semantic string, which 4462203955Srdivacky * will typically provide the spelling of a keyword or the name of a 4463199482Srdivacky * declaration that could be used at the current code point. Clients are 4464199482Srdivacky * expected to filter the code-completion results based on the text in this 4465199482Srdivacky * chunk. 4466199482Srdivacky */ 4467199482Srdivacky CXCompletionChunk_TypedText, 4468199482Srdivacky /** 4469199482Srdivacky * \brief Text that should be inserted as part of a code-completion result. 4470199482Srdivacky * 4471199482Srdivacky * A "text" chunk represents text that is part of the template to be 4472199482Srdivacky * inserted into user code should this particular code-completion result 4473199482Srdivacky * be selected. 4474199482Srdivacky */ 4475199482Srdivacky CXCompletionChunk_Text, 4476199482Srdivacky /** 4477199482Srdivacky * \brief Placeholder text that should be replaced by the user. 4478199482Srdivacky * 4479199482Srdivacky * A "placeholder" chunk marks a place where the user should insert text 4480199482Srdivacky * into the code-completion template. For example, placeholders might mark 4481199482Srdivacky * the function parameters for a function declaration, to indicate that the 4482199482Srdivacky * user should provide arguments for each of those parameters. The actual 4483199482Srdivacky * text in a placeholder is a suggestion for the text to display before 4484199482Srdivacky * the user replaces the placeholder with real code. 4485199482Srdivacky */ 4486199482Srdivacky CXCompletionChunk_Placeholder, 4487199482Srdivacky /** 4488199482Srdivacky * \brief Informative text that should be displayed but never inserted as 4489199482Srdivacky * part of the template. 4490203955Srdivacky * 4491199482Srdivacky * An "informative" chunk contains annotations that can be displayed to 4492199482Srdivacky * help the user decide whether a particular code-completion result is the 4493199482Srdivacky * right option, but which is not part of the actual template to be inserted 4494199482Srdivacky * by code completion. 4495199482Srdivacky */ 4496199482Srdivacky CXCompletionChunk_Informative, 4497199482Srdivacky /** 4498199482Srdivacky * \brief Text that describes the current parameter when code-completion is 4499199482Srdivacky * referring to function call, message send, or template specialization. 4500199482Srdivacky * 4501199482Srdivacky * A "current parameter" chunk occurs when code-completion is providing 4502199482Srdivacky * information about a parameter corresponding to the argument at the 4503199482Srdivacky * code-completion point. For example, given a function 4504199482Srdivacky * 4505199482Srdivacky * \code 4506199482Srdivacky * int add(int x, int y); 4507199482Srdivacky * \endcode 4508199482Srdivacky * 4509199482Srdivacky * and the source code \c add(, where the code-completion point is after the 4510199482Srdivacky * "(", the code-completion string will contain a "current parameter" chunk 4511199482Srdivacky * for "int x", indicating that the current argument will initialize that 4512199482Srdivacky * parameter. After typing further, to \c add(17, (where the code-completion 4513203955Srdivacky * point is after the ","), the code-completion string will contain a 4514199482Srdivacky * "current paremeter" chunk to "int y". 4515199482Srdivacky */ 4516199482Srdivacky CXCompletionChunk_CurrentParameter, 4517199482Srdivacky /** 4518199482Srdivacky * \brief A left parenthesis ('('), used to initiate a function call or 4519199482Srdivacky * signal the beginning of a function parameter list. 4520199482Srdivacky */ 4521199482Srdivacky CXCompletionChunk_LeftParen, 4522199482Srdivacky /** 4523199482Srdivacky * \brief A right parenthesis (')'), used to finish a function call or 4524199482Srdivacky * signal the end of a function parameter list. 4525199482Srdivacky */ 4526199482Srdivacky CXCompletionChunk_RightParen, 4527199482Srdivacky /** 4528199482Srdivacky * \brief A left bracket ('['). 4529199482Srdivacky */ 4530199482Srdivacky CXCompletionChunk_LeftBracket, 4531199482Srdivacky /** 4532199482Srdivacky * \brief A right bracket (']'). 4533199482Srdivacky */ 4534199482Srdivacky CXCompletionChunk_RightBracket, 4535199482Srdivacky /** 4536199482Srdivacky * \brief A left brace ('{'). 4537199482Srdivacky */ 4538199482Srdivacky CXCompletionChunk_LeftBrace, 4539199482Srdivacky /** 4540199482Srdivacky * \brief A right brace ('}'). 4541199482Srdivacky */ 4542199482Srdivacky CXCompletionChunk_RightBrace, 4543199482Srdivacky /** 4544199482Srdivacky * \brief A left angle bracket ('<'). 4545199482Srdivacky */ 4546199482Srdivacky CXCompletionChunk_LeftAngle, 4547199482Srdivacky /** 4548199482Srdivacky * \brief A right angle bracket ('>'). 4549199482Srdivacky */ 4550199482Srdivacky CXCompletionChunk_RightAngle, 4551199482Srdivacky /** 4552199482Srdivacky * \brief A comma separator (','). 4553199482Srdivacky */ 4554201361Srdivacky CXCompletionChunk_Comma, 4555201361Srdivacky /** 4556203955Srdivacky * \brief Text that specifies the result type of a given result. 4557201361Srdivacky * 4558201361Srdivacky * This special kind of informative chunk is not meant to be inserted into 4559203955Srdivacky * the text buffer. Rather, it is meant to illustrate the type that an 4560201361Srdivacky * expression using the given completion string would have. 4561201361Srdivacky */ 4562202379Srdivacky CXCompletionChunk_ResultType, 4563202379Srdivacky /** 4564202379Srdivacky * \brief A colon (':'). 4565202379Srdivacky */ 4566202379Srdivacky CXCompletionChunk_Colon, 4567202379Srdivacky /** 4568202379Srdivacky * \brief A semicolon (';'). 4569202379Srdivacky */ 4570202379Srdivacky CXCompletionChunk_SemiColon, 4571202379Srdivacky /** 4572202379Srdivacky * \brief An '=' sign. 4573202379Srdivacky */ 4574202379Srdivacky CXCompletionChunk_Equal, 4575202379Srdivacky /** 4576202379Srdivacky * Horizontal space (' '). 4577202379Srdivacky */ 4578202379Srdivacky CXCompletionChunk_HorizontalSpace, 4579202379Srdivacky /** 4580202379Srdivacky * Vertical space ('\n'), after which it is generally a good idea to 4581202379Srdivacky * perform indentation. 4582202379Srdivacky */ 4583202379Srdivacky CXCompletionChunk_VerticalSpace 4584199482Srdivacky}; 4585203955Srdivacky 4586199482Srdivacky/** 4587199482Srdivacky * \brief Determine the kind of a particular chunk within a completion string. 4588199482Srdivacky * 4589199482Srdivacky * \param completion_string the completion string to query. 4590199482Srdivacky * 4591199482Srdivacky * \param chunk_number the 0-based index of the chunk in the completion string. 4592199482Srdivacky * 4593199482Srdivacky * \returns the kind of the chunk at the index \c chunk_number. 4594199482Srdivacky */ 4595203955SrdivackyCINDEX_LINKAGE enum CXCompletionChunkKind 4596199482Srdivackyclang_getCompletionChunkKind(CXCompletionString completion_string, 4597199482Srdivacky unsigned chunk_number); 4598203955Srdivacky 4599199482Srdivacky/** 4600203955Srdivacky * \brief Retrieve the text associated with a particular chunk within a 4601199482Srdivacky * completion string. 4602199482Srdivacky * 4603199482Srdivacky * \param completion_string the completion string to query. 4604199482Srdivacky * 4605199482Srdivacky * \param chunk_number the 0-based index of the chunk in the completion string. 4606199482Srdivacky * 4607199482Srdivacky * \returns the text associated with the chunk at index \c chunk_number. 4608199482Srdivacky */ 4609204643SrdivackyCINDEX_LINKAGE CXString 4610199482Srdivackyclang_getCompletionChunkText(CXCompletionString completion_string, 4611199482Srdivacky unsigned chunk_number); 4612199482Srdivacky 4613199482Srdivacky/** 4614203955Srdivacky * \brief Retrieve the completion string associated with a particular chunk 4615199482Srdivacky * within a completion string. 4616199482Srdivacky * 4617199482Srdivacky * \param completion_string the completion string to query. 4618199482Srdivacky * 4619199482Srdivacky * \param chunk_number the 0-based index of the chunk in the completion string. 4620199482Srdivacky * 4621199482Srdivacky * \returns the completion string associated with the chunk at index 4622226890Sdim * \c chunk_number. 4623199482Srdivacky */ 4624199482SrdivackyCINDEX_LINKAGE CXCompletionString 4625199482Srdivackyclang_getCompletionChunkCompletionString(CXCompletionString completion_string, 4626199482Srdivacky unsigned chunk_number); 4627203955Srdivacky 4628199482Srdivacky/** 4629199482Srdivacky * \brief Retrieve the number of chunks in the given code-completion string. 4630199482Srdivacky */ 4631199482SrdivackyCINDEX_LINKAGE unsigned 4632199482Srdivackyclang_getNumCompletionChunks(CXCompletionString completion_string); 4633199482Srdivacky 4634199482Srdivacky/** 4635208600Srdivacky * \brief Determine the priority of this code completion. 4636208600Srdivacky * 4637208600Srdivacky * The priority of a code completion indicates how likely it is that this 4638208600Srdivacky * particular completion is the completion that the user will select. The 4639208600Srdivacky * priority is selected by various internal heuristics. 4640208600Srdivacky * 4641208600Srdivacky * \param completion_string The completion string to query. 4642208600Srdivacky * 4643208600Srdivacky * \returns The priority of this completion string. Smaller values indicate 4644208600Srdivacky * higher-priority (more likely) completions. 4645208600Srdivacky */ 4646208600SrdivackyCINDEX_LINKAGE unsigned 4647208600Srdivackyclang_getCompletionPriority(CXCompletionString completion_string); 4648208600Srdivacky 4649208600Srdivacky/** 4650212904Sdim * \brief Determine the availability of the entity that this code-completion 4651212904Sdim * string refers to. 4652212904Sdim * 4653212904Sdim * \param completion_string The completion string to query. 4654212904Sdim * 4655212904Sdim * \returns The availability of the completion string. 4656212904Sdim */ 4657212904SdimCINDEX_LINKAGE enum CXAvailabilityKind 4658212904Sdimclang_getCompletionAvailability(CXCompletionString completion_string); 4659212904Sdim 4660212904Sdim/** 4661226890Sdim * \brief Retrieve the number of annotations associated with the given 4662226890Sdim * completion string. 4663226890Sdim * 4664226890Sdim * \param completion_string the completion string to query. 4665226890Sdim * 4666226890Sdim * \returns the number of annotations associated with the given completion 4667226890Sdim * string. 4668226890Sdim */ 4669226890SdimCINDEX_LINKAGE unsigned 4670226890Sdimclang_getCompletionNumAnnotations(CXCompletionString completion_string); 4671226890Sdim 4672226890Sdim/** 4673226890Sdim * \brief Retrieve the annotation associated with the given completion string. 4674226890Sdim * 4675226890Sdim * \param completion_string the completion string to query. 4676226890Sdim * 4677226890Sdim * \param annotation_number the 0-based index of the annotation of the 4678226890Sdim * completion string. 4679226890Sdim * 4680226890Sdim * \returns annotation string associated with the completion at index 4681226890Sdim * \c annotation_number, or a NULL string if that annotation is not available. 4682226890Sdim */ 4683226890SdimCINDEX_LINKAGE CXString 4684226890Sdimclang_getCompletionAnnotation(CXCompletionString completion_string, 4685226890Sdim unsigned annotation_number); 4686226890Sdim 4687226890Sdim/** 4688235633Sdim * \brief Retrieve the parent context of the given completion string. 4689235633Sdim * 4690235633Sdim * The parent context of a completion string is the semantic parent of 4691235633Sdim * the declaration (if any) that the code completion represents. For example, 4692235633Sdim * a code completion for an Objective-C method would have the method's class 4693235633Sdim * or protocol as its context. 4694235633Sdim * 4695235633Sdim * \param completion_string The code completion string whose parent is 4696235633Sdim * being queried. 4697235633Sdim * 4698245431Sdim * \param kind DEPRECATED: always set to CXCursor_NotImplemented if non-NULL. 4699235633Sdim * 4700245431Sdim * \returns The name of the completion parent, e.g., "NSObject" if 4701235633Sdim * the completion string represents a method in the NSObject class. 4702235633Sdim */ 4703235633SdimCINDEX_LINKAGE CXString 4704235633Sdimclang_getCompletionParent(CXCompletionString completion_string, 4705235633Sdim enum CXCursorKind *kind); 4706245431Sdim 4707235633Sdim/** 4708245431Sdim * \brief Retrieve the brief documentation comment attached to the declaration 4709245431Sdim * that corresponds to the given completion string. 4710245431Sdim */ 4711245431SdimCINDEX_LINKAGE CXString 4712245431Sdimclang_getCompletionBriefComment(CXCompletionString completion_string); 4713245431Sdim 4714245431Sdim/** 4715226890Sdim * \brief Retrieve a completion string for an arbitrary declaration or macro 4716226890Sdim * definition cursor. 4717226890Sdim * 4718226890Sdim * \param cursor The cursor to query. 4719226890Sdim * 4720226890Sdim * \returns A non-context-sensitive completion string for declaration and macro 4721226890Sdim * definition cursors, or NULL for other kinds of cursors. 4722226890Sdim */ 4723226890SdimCINDEX_LINKAGE CXCompletionString 4724226890Sdimclang_getCursorCompletionString(CXCursor cursor); 4725226890Sdim 4726226890Sdim/** 4727201361Srdivacky * \brief Contains the results of code-completion. 4728201361Srdivacky * 4729201361Srdivacky * This data structure contains the results of code completion, as 4730218893Sdim * produced by \c clang_codeCompleteAt(). Its contents must be freed by 4731201361Srdivacky * \c clang_disposeCodeCompleteResults. 4732201361Srdivacky */ 4733201361Srdivackytypedef struct { 4734201361Srdivacky /** 4735201361Srdivacky * \brief The code-completion results. 4736201361Srdivacky */ 4737201361Srdivacky CXCompletionResult *Results; 4738201361Srdivacky 4739201361Srdivacky /** 4740201361Srdivacky * \brief The number of code-completion results stored in the 4741201361Srdivacky * \c Results array. 4742201361Srdivacky */ 4743201361Srdivacky unsigned NumResults; 4744201361Srdivacky} CXCodeCompleteResults; 4745201361Srdivacky 4746201361Srdivacky/** 4747212904Sdim * \brief Flags that can be passed to \c clang_codeCompleteAt() to 4748212904Sdim * modify its behavior. 4749212904Sdim * 4750212904Sdim * The enumerators in this enumeration can be bitwise-OR'd together to 4751212904Sdim * provide multiple options to \c clang_codeCompleteAt(). 4752212904Sdim */ 4753212904Sdimenum CXCodeComplete_Flags { 4754212904Sdim /** 4755212904Sdim * \brief Whether to include macros within the set of code 4756212904Sdim * completions returned. 4757212904Sdim */ 4758212904Sdim CXCodeComplete_IncludeMacros = 0x01, 4759212904Sdim 4760212904Sdim /** 4761212904Sdim * \brief Whether to include code patterns for language constructs 4762212904Sdim * within the set of code completions, e.g., for loops. 4763212904Sdim */ 4764245431Sdim CXCodeComplete_IncludeCodePatterns = 0x02, 4765245431Sdim 4766245431Sdim /** 4767245431Sdim * \brief Whether to include brief documentation within the set of code 4768245431Sdim * completions returned. 4769245431Sdim */ 4770245431Sdim CXCodeComplete_IncludeBriefComments = 0x04 4771212904Sdim}; 4772212904Sdim 4773212904Sdim/** 4774224145Sdim * \brief Bits that represent the context under which completion is occurring. 4775224145Sdim * 4776224145Sdim * The enumerators in this enumeration may be bitwise-OR'd together if multiple 4777224145Sdim * contexts are occurring simultaneously. 4778224145Sdim */ 4779224145Sdimenum CXCompletionContext { 4780224145Sdim /** 4781224145Sdim * \brief The context for completions is unexposed, as only Clang results 4782224145Sdim * should be included. (This is equivalent to having no context bits set.) 4783224145Sdim */ 4784224145Sdim CXCompletionContext_Unexposed = 0, 4785224145Sdim 4786224145Sdim /** 4787224145Sdim * \brief Completions for any possible type should be included in the results. 4788224145Sdim */ 4789224145Sdim CXCompletionContext_AnyType = 1 << 0, 4790224145Sdim 4791224145Sdim /** 4792224145Sdim * \brief Completions for any possible value (variables, function calls, etc.) 4793224145Sdim * should be included in the results. 4794224145Sdim */ 4795224145Sdim CXCompletionContext_AnyValue = 1 << 1, 4796224145Sdim /** 4797224145Sdim * \brief Completions for values that resolve to an Objective-C object should 4798224145Sdim * be included in the results. 4799224145Sdim */ 4800224145Sdim CXCompletionContext_ObjCObjectValue = 1 << 2, 4801224145Sdim /** 4802224145Sdim * \brief Completions for values that resolve to an Objective-C selector 4803224145Sdim * should be included in the results. 4804224145Sdim */ 4805224145Sdim CXCompletionContext_ObjCSelectorValue = 1 << 3, 4806224145Sdim /** 4807224145Sdim * \brief Completions for values that resolve to a C++ class type should be 4808224145Sdim * included in the results. 4809224145Sdim */ 4810224145Sdim CXCompletionContext_CXXClassTypeValue = 1 << 4, 4811224145Sdim 4812224145Sdim /** 4813224145Sdim * \brief Completions for fields of the member being accessed using the dot 4814224145Sdim * operator should be included in the results. 4815224145Sdim */ 4816224145Sdim CXCompletionContext_DotMemberAccess = 1 << 5, 4817224145Sdim /** 4818224145Sdim * \brief Completions for fields of the member being accessed using the arrow 4819224145Sdim * operator should be included in the results. 4820224145Sdim */ 4821224145Sdim CXCompletionContext_ArrowMemberAccess = 1 << 6, 4822224145Sdim /** 4823224145Sdim * \brief Completions for properties of the Objective-C object being accessed 4824224145Sdim * using the dot operator should be included in the results. 4825224145Sdim */ 4826224145Sdim CXCompletionContext_ObjCPropertyAccess = 1 << 7, 4827224145Sdim 4828224145Sdim /** 4829224145Sdim * \brief Completions for enum tags should be included in the results. 4830224145Sdim */ 4831224145Sdim CXCompletionContext_EnumTag = 1 << 8, 4832224145Sdim /** 4833224145Sdim * \brief Completions for union tags should be included in the results. 4834224145Sdim */ 4835224145Sdim CXCompletionContext_UnionTag = 1 << 9, 4836224145Sdim /** 4837224145Sdim * \brief Completions for struct tags should be included in the results. 4838224145Sdim */ 4839224145Sdim CXCompletionContext_StructTag = 1 << 10, 4840224145Sdim 4841224145Sdim /** 4842224145Sdim * \brief Completions for C++ class names should be included in the results. 4843224145Sdim */ 4844224145Sdim CXCompletionContext_ClassTag = 1 << 11, 4845224145Sdim /** 4846224145Sdim * \brief Completions for C++ namespaces and namespace aliases should be 4847224145Sdim * included in the results. 4848224145Sdim */ 4849224145Sdim CXCompletionContext_Namespace = 1 << 12, 4850224145Sdim /** 4851224145Sdim * \brief Completions for C++ nested name specifiers should be included in 4852224145Sdim * the results. 4853224145Sdim */ 4854224145Sdim CXCompletionContext_NestedNameSpecifier = 1 << 13, 4855224145Sdim 4856224145Sdim /** 4857224145Sdim * \brief Completions for Objective-C interfaces (classes) should be included 4858224145Sdim * in the results. 4859224145Sdim */ 4860224145Sdim CXCompletionContext_ObjCInterface = 1 << 14, 4861224145Sdim /** 4862224145Sdim * \brief Completions for Objective-C protocols should be included in 4863224145Sdim * the results. 4864224145Sdim */ 4865224145Sdim CXCompletionContext_ObjCProtocol = 1 << 15, 4866224145Sdim /** 4867224145Sdim * \brief Completions for Objective-C categories should be included in 4868224145Sdim * the results. 4869224145Sdim */ 4870224145Sdim CXCompletionContext_ObjCCategory = 1 << 16, 4871224145Sdim /** 4872224145Sdim * \brief Completions for Objective-C instance messages should be included 4873224145Sdim * in the results. 4874224145Sdim */ 4875224145Sdim CXCompletionContext_ObjCInstanceMessage = 1 << 17, 4876224145Sdim /** 4877224145Sdim * \brief Completions for Objective-C class messages should be included in 4878224145Sdim * the results. 4879224145Sdim */ 4880224145Sdim CXCompletionContext_ObjCClassMessage = 1 << 18, 4881224145Sdim /** 4882224145Sdim * \brief Completions for Objective-C selector names should be included in 4883224145Sdim * the results. 4884224145Sdim */ 4885224145Sdim CXCompletionContext_ObjCSelectorName = 1 << 19, 4886224145Sdim 4887224145Sdim /** 4888224145Sdim * \brief Completions for preprocessor macro names should be included in 4889224145Sdim * the results. 4890224145Sdim */ 4891224145Sdim CXCompletionContext_MacroName = 1 << 20, 4892224145Sdim 4893224145Sdim /** 4894224145Sdim * \brief Natural language completions should be included in the results. 4895224145Sdim */ 4896224145Sdim CXCompletionContext_NaturalLanguage = 1 << 21, 4897224145Sdim 4898224145Sdim /** 4899224145Sdim * \brief The current context is unknown, so set all contexts. 4900224145Sdim */ 4901224145Sdim CXCompletionContext_Unknown = ((1 << 22) - 1) 4902224145Sdim}; 4903224145Sdim 4904224145Sdim/** 4905212904Sdim * \brief Returns a default set of code-completion options that can be 4906212904Sdim * passed to\c clang_codeCompleteAt(). 4907212904Sdim */ 4908212904SdimCINDEX_LINKAGE unsigned clang_defaultCodeCompleteOptions(void); 4909212904Sdim 4910212904Sdim/** 4911212904Sdim * \brief Perform code completion at a given location in a translation unit. 4912212904Sdim * 4913212904Sdim * This function performs code completion at a particular file, line, and 4914212904Sdim * column within source code, providing results that suggest potential 4915212904Sdim * code snippets based on the context of the completion. The basic model 4916212904Sdim * for code completion is that Clang will parse a complete source file, 4917212904Sdim * performing syntax checking up to the location where code-completion has 4918212904Sdim * been requested. At that point, a special code-completion token is passed 4919212904Sdim * to the parser, which recognizes this token and determines, based on the 4920212904Sdim * current location in the C/Objective-C/C++ grammar and the state of 4921212904Sdim * semantic analysis, what completions to provide. These completions are 4922212904Sdim * returned via a new \c CXCodeCompleteResults structure. 4923212904Sdim * 4924212904Sdim * Code completion itself is meant to be triggered by the client when the 4925212904Sdim * user types punctuation characters or whitespace, at which point the 4926212904Sdim * code-completion location will coincide with the cursor. For example, if \c p 4927212904Sdim * is a pointer, code-completion might be triggered after the "-" and then 4928212904Sdim * after the ">" in \c p->. When the code-completion location is afer the ">", 4929212904Sdim * the completion results will provide, e.g., the members of the struct that 4930212904Sdim * "p" points to. The client is responsible for placing the cursor at the 4931212904Sdim * beginning of the token currently being typed, then filtering the results 4932212904Sdim * based on the contents of the token. For example, when code-completing for 4933212904Sdim * the expression \c p->get, the client should provide the location just after 4934212904Sdim * the ">" (e.g., pointing at the "g") to this code-completion hook. Then, the 4935212904Sdim * client can filter the results based on the current token text ("get"), only 4936212904Sdim * showing those results that start with "get". The intent of this interface 4937212904Sdim * is to separate the relatively high-latency acquisition of code-completion 4938212904Sdim * results from the filtering of results on a per-character basis, which must 4939212904Sdim * have a lower latency. 4940212904Sdim * 4941212904Sdim * \param TU The translation unit in which code-completion should 4942212904Sdim * occur. The source files for this translation unit need not be 4943212904Sdim * completely up-to-date (and the contents of those source files may 4944212904Sdim * be overridden via \p unsaved_files). Cursors referring into the 4945212904Sdim * translation unit may be invalidated by this invocation. 4946212904Sdim * 4947212904Sdim * \param complete_filename The name of the source file where code 4948212904Sdim * completion should be performed. This filename may be any file 4949212904Sdim * included in the translation unit. 4950212904Sdim * 4951212904Sdim * \param complete_line The line at which code-completion should occur. 4952212904Sdim * 4953212904Sdim * \param complete_column The column at which code-completion should occur. 4954212904Sdim * Note that the column should point just after the syntactic construct that 4955212904Sdim * initiated code completion, and not in the middle of a lexical token. 4956212904Sdim * 4957212904Sdim * \param unsaved_files the Tiles that have not yet been saved to disk 4958212904Sdim * but may be required for parsing or code completion, including the 4959212904Sdim * contents of those files. The contents and name of these files (as 4960212904Sdim * specified by CXUnsavedFile) are copied when necessary, so the 4961212904Sdim * client only needs to guarantee their validity until the call to 4962212904Sdim * this function returns. 4963212904Sdim * 4964212904Sdim * \param num_unsaved_files The number of unsaved file entries in \p 4965212904Sdim * unsaved_files. 4966212904Sdim * 4967212904Sdim * \param options Extra options that control the behavior of code 4968212904Sdim * completion, expressed as a bitwise OR of the enumerators of the 4969212904Sdim * CXCodeComplete_Flags enumeration. The 4970212904Sdim * \c clang_defaultCodeCompleteOptions() function returns a default set 4971212904Sdim * of code-completion options. 4972212904Sdim * 4973212904Sdim * \returns If successful, a new \c CXCodeCompleteResults structure 4974212904Sdim * containing code-completion results, which should eventually be 4975212904Sdim * freed with \c clang_disposeCodeCompleteResults(). If code 4976212904Sdim * completion fails, returns NULL. 4977212904Sdim */ 4978212904SdimCINDEX_LINKAGE 4979212904SdimCXCodeCompleteResults *clang_codeCompleteAt(CXTranslationUnit TU, 4980212904Sdim const char *complete_filename, 4981212904Sdim unsigned complete_line, 4982212904Sdim unsigned complete_column, 4983212904Sdim struct CXUnsavedFile *unsaved_files, 4984212904Sdim unsigned num_unsaved_files, 4985212904Sdim unsigned options); 4986212904Sdim 4987212904Sdim/** 4988212904Sdim * \brief Sort the code-completion results in case-insensitive alphabetical 4989212904Sdim * order. 4990212904Sdim * 4991212904Sdim * \param Results The set of results to sort. 4992212904Sdim * \param NumResults The number of results in \p Results. 4993212904Sdim */ 4994212904SdimCINDEX_LINKAGE 4995212904Sdimvoid clang_sortCodeCompletionResults(CXCompletionResult *Results, 4996212904Sdim unsigned NumResults); 4997212904Sdim 4998212904Sdim/** 4999201361Srdivacky * \brief Free the given set of code-completion results. 5000201361Srdivacky */ 5001203955SrdivackyCINDEX_LINKAGE 5002201361Srdivackyvoid clang_disposeCodeCompleteResults(CXCodeCompleteResults *Results); 5003212904Sdim 5004202879Srdivacky/** 5005204643Srdivacky * \brief Determine the number of diagnostics produced prior to the 5006204643Srdivacky * location where code completion was performed. 5007204643Srdivacky */ 5008205219SrdivackyCINDEX_LINKAGE 5009204643Srdivackyunsigned clang_codeCompleteGetNumDiagnostics(CXCodeCompleteResults *Results); 5010204643Srdivacky 5011204643Srdivacky/** 5012204643Srdivacky * \brief Retrieve a diagnostic associated with the given code completion. 5013204643Srdivacky * 5014245431Sdim * \param Results the code completion results to query. 5015204643Srdivacky * \param Index the zero-based diagnostic number to retrieve. 5016204643Srdivacky * 5017204643Srdivacky * \returns the requested diagnostic. This diagnostic must be freed 5018204643Srdivacky * via a call to \c clang_disposeDiagnostic(). 5019204643Srdivacky */ 5020205219SrdivackyCINDEX_LINKAGE 5021204643SrdivackyCXDiagnostic clang_codeCompleteGetDiagnostic(CXCodeCompleteResults *Results, 5022204643Srdivacky unsigned Index); 5023204643Srdivacky 5024204643Srdivacky/** 5025224145Sdim * \brief Determines what compeltions are appropriate for the context 5026224145Sdim * the given code completion. 5027224145Sdim * 5028224145Sdim * \param Results the code completion results to query 5029224145Sdim * 5030224145Sdim * \returns the kinds of completions that are appropriate for use 5031224145Sdim * along with the given code completion results. 5032224145Sdim */ 5033224145SdimCINDEX_LINKAGE 5034224145Sdimunsigned long long clang_codeCompleteGetContexts( 5035224145Sdim CXCodeCompleteResults *Results); 5036226890Sdim 5037226890Sdim/** 5038226890Sdim * \brief Returns the cursor kind for the container for the current code 5039226890Sdim * completion context. The container is only guaranteed to be set for 5040226890Sdim * contexts where a container exists (i.e. member accesses or Objective-C 5041226890Sdim * message sends); if there is not a container, this function will return 5042226890Sdim * CXCursor_InvalidCode. 5043226890Sdim * 5044226890Sdim * \param Results the code completion results to query 5045226890Sdim * 5046226890Sdim * \param IsIncomplete on return, this value will be false if Clang has complete 5047226890Sdim * information about the container. If Clang does not have complete 5048226890Sdim * information, this value will be true. 5049226890Sdim * 5050226890Sdim * \returns the container kind, or CXCursor_InvalidCode if there is not a 5051226890Sdim * container 5052226890Sdim */ 5053226890SdimCINDEX_LINKAGE 5054226890Sdimenum CXCursorKind clang_codeCompleteGetContainerKind( 5055226890Sdim CXCodeCompleteResults *Results, 5056226890Sdim unsigned *IsIncomplete); 5057226890Sdim 5058226890Sdim/** 5059226890Sdim * \brief Returns the USR for the container for the current code completion 5060226890Sdim * context. If there is not a container for the current context, this 5061226890Sdim * function will return the empty string. 5062226890Sdim * 5063226890Sdim * \param Results the code completion results to query 5064226890Sdim * 5065226890Sdim * \returns the USR for the container 5066226890Sdim */ 5067226890SdimCINDEX_LINKAGE 5068226890SdimCXString clang_codeCompleteGetContainerUSR(CXCodeCompleteResults *Results); 5069224145Sdim 5070226890Sdim 5071224145Sdim/** 5072226890Sdim * \brief Returns the currently-entered selector for an Objective-C message 5073226890Sdim * send, formatted like "initWithFoo:bar:". Only guaranteed to return a 5074226890Sdim * non-empty string for CXCompletionContext_ObjCInstanceMessage and 5075226890Sdim * CXCompletionContext_ObjCClassMessage. 5076226890Sdim * 5077226890Sdim * \param Results the code completion results to query 5078226890Sdim * 5079226890Sdim * \returns the selector (or partial selector) that has been entered thus far 5080226890Sdim * for an Objective-C message send. 5081226890Sdim */ 5082226890SdimCINDEX_LINKAGE 5083226890SdimCXString clang_codeCompleteGetObjCSelector(CXCodeCompleteResults *Results); 5084226890Sdim 5085226890Sdim/** 5086202879Srdivacky * @} 5087202879Srdivacky */ 5088203955Srdivacky 5089203955Srdivacky 5090202879Srdivacky/** 5091202879Srdivacky * \defgroup CINDEX_MISC Miscellaneous utility functions 5092202879Srdivacky * 5093202879Srdivacky * @{ 5094202879Srdivacky */ 5095202879Srdivacky 5096202879Srdivacky/** 5097203955Srdivacky * \brief Return a version string, suitable for showing to a user, but not 5098203955Srdivacky * intended to be parsed (the format is not guaranteed to be stable). 5099203955Srdivacky */ 5100252723SdimCINDEX_LINKAGE CXString clang_getClangVersion(void); 5101203955Srdivacky 5102221345Sdim 5103221345Sdim/** 5104221345Sdim * \brief Enable/disable crash recovery. 5105221345Sdim * 5106245431Sdim * \param isEnabled Flag to indicate if crash recovery is enabled. A non-zero 5107245431Sdim * value enables crash recovery, while 0 disables it. 5108221345Sdim */ 5109221345SdimCINDEX_LINKAGE void clang_toggleCrashRecovery(unsigned isEnabled); 5110221345Sdim 5111203955Srdivacky /** 5112205219Srdivacky * \brief Visitor invoked for each file in a translation unit 5113203955Srdivacky * (used with clang_getInclusions()). 5114203955Srdivacky * 5115203955Srdivacky * This visitor function will be invoked by clang_getInclusions() for each 5116245431Sdim * file included (either at the top-level or by \#include directives) within 5117203955Srdivacky * a translation unit. The first argument is the file being included, and 5118203955Srdivacky * the second and third arguments provide the inclusion stack. The 5119203955Srdivacky * array is sorted in order of immediate inclusion. For example, 5120203955Srdivacky * the first element refers to the location that included 'included_file'. 5121203955Srdivacky */ 5122203955Srdivackytypedef void (*CXInclusionVisitor)(CXFile included_file, 5123203955Srdivacky CXSourceLocation* inclusion_stack, 5124203955Srdivacky unsigned include_len, 5125203955Srdivacky CXClientData client_data); 5126203955Srdivacky 5127203955Srdivacky/** 5128203955Srdivacky * \brief Visit the set of preprocessor inclusions in a translation unit. 5129203955Srdivacky * The visitor function is called with the provided data for every included 5130203955Srdivacky * file. This does not include headers included by the PCH file (unless one 5131203955Srdivacky * is inspecting the inclusions in the PCH file itself). 5132203955Srdivacky */ 5133203955SrdivackyCINDEX_LINKAGE void clang_getInclusions(CXTranslationUnit tu, 5134203955Srdivacky CXInclusionVisitor visitor, 5135203955Srdivacky CXClientData client_data); 5136203955Srdivacky 5137203955Srdivacky/** 5138202879Srdivacky * @} 5139202879Srdivacky */ 5140203955Srdivacky 5141224145Sdim/** \defgroup CINDEX_REMAPPING Remapping functions 5142224145Sdim * 5143224145Sdim * @{ 5144224145Sdim */ 5145224145Sdim 5146202879Srdivacky/** 5147224145Sdim * \brief A remapping of original source files and their translated files. 5148224145Sdim */ 5149224145Sdimtypedef void *CXRemapping; 5150224145Sdim 5151224145Sdim/** 5152224145Sdim * \brief Retrieve a remapping. 5153224145Sdim * 5154224145Sdim * \param path the path that contains metadata about remappings. 5155224145Sdim * 5156224145Sdim * \returns the requested remapping. This remapping must be freed 5157224145Sdim * via a call to \c clang_remap_dispose(). Can return NULL if an error occurred. 5158224145Sdim */ 5159224145SdimCINDEX_LINKAGE CXRemapping clang_getRemappings(const char *path); 5160224145Sdim 5161224145Sdim/** 5162235633Sdim * \brief Retrieve a remapping. 5163235633Sdim * 5164235633Sdim * \param filePaths pointer to an array of file paths containing remapping info. 5165235633Sdim * 5166235633Sdim * \param numFiles number of file paths. 5167235633Sdim * 5168235633Sdim * \returns the requested remapping. This remapping must be freed 5169235633Sdim * via a call to \c clang_remap_dispose(). Can return NULL if an error occurred. 5170235633Sdim */ 5171235633SdimCINDEX_LINKAGE 5172235633SdimCXRemapping clang_getRemappingsFromFileList(const char **filePaths, 5173235633Sdim unsigned numFiles); 5174235633Sdim 5175235633Sdim/** 5176224145Sdim * \brief Determine the number of remappings. 5177224145Sdim */ 5178224145SdimCINDEX_LINKAGE unsigned clang_remap_getNumFiles(CXRemapping); 5179224145Sdim 5180224145Sdim/** 5181224145Sdim * \brief Get the original and the associated filename from the remapping. 5182224145Sdim * 5183224145Sdim * \param original If non-NULL, will be set to the original filename. 5184224145Sdim * 5185224145Sdim * \param transformed If non-NULL, will be set to the filename that the original 5186224145Sdim * is associated with. 5187224145Sdim */ 5188224145SdimCINDEX_LINKAGE void clang_remap_getFilenames(CXRemapping, unsigned index, 5189224145Sdim CXString *original, CXString *transformed); 5190224145Sdim 5191224145Sdim/** 5192224145Sdim * \brief Dispose the remapping. 5193224145Sdim */ 5194224145SdimCINDEX_LINKAGE void clang_remap_dispose(CXRemapping); 5195224145Sdim 5196224145Sdim/** 5197202879Srdivacky * @} 5198202879Srdivacky */ 5199203955Srdivacky 5200226890Sdim/** \defgroup CINDEX_HIGH Higher level API functions 5201226890Sdim * 5202226890Sdim * @{ 5203226890Sdim */ 5204226890Sdim 5205226890Sdimenum CXVisitorResult { 5206226890Sdim CXVisit_Break, 5207226890Sdim CXVisit_Continue 5208226890Sdim}; 5209226890Sdim 5210226890Sdimtypedef struct { 5211226890Sdim void *context; 5212226890Sdim enum CXVisitorResult (*visit)(void *context, CXCursor, CXSourceRange); 5213226890Sdim} CXCursorAndRangeVisitor; 5214226890Sdim 5215252723Sdimtypedef enum { 5216252723Sdim /** 5217252723Sdim * \brief Function returned successfully. 5218252723Sdim */ 5219252723Sdim CXResult_Success = 0, 5220252723Sdim /** 5221252723Sdim * \brief One of the parameters was invalid for the function. 5222252723Sdim */ 5223252723Sdim CXResult_Invalid = 1, 5224252723Sdim /** 5225252723Sdim * \brief The function was terminated by a callback (e.g. it returned 5226252723Sdim * CXVisit_Break) 5227252723Sdim */ 5228252723Sdim CXResult_VisitBreak = 2 5229252723Sdim 5230252723Sdim} CXResult; 5231252723Sdim 5232224145Sdim/** 5233226890Sdim * \brief Find references of a declaration in a specific file. 5234226890Sdim * 5235226890Sdim * \param cursor pointing to a declaration or a reference of one. 5236226890Sdim * 5237226890Sdim * \param file to search for references. 5238226890Sdim * 5239226890Sdim * \param visitor callback that will receive pairs of CXCursor/CXSourceRange for 5240226890Sdim * each reference found. 5241226890Sdim * The CXSourceRange will point inside the file; if the reference is inside 5242226890Sdim * a macro (and not a macro argument) the CXSourceRange will be invalid. 5243252723Sdim * 5244252723Sdim * \returns one of the CXResult enumerators. 5245226890Sdim */ 5246252723SdimCINDEX_LINKAGE CXResult clang_findReferencesInFile(CXCursor cursor, CXFile file, 5247226890Sdim CXCursorAndRangeVisitor visitor); 5248226890Sdim 5249252723Sdim/** 5250252723Sdim * \brief Find #import/#include directives in a specific file. 5251252723Sdim * 5252252723Sdim * \param TU translation unit containing the file to query. 5253252723Sdim * 5254252723Sdim * \param file to search for #import/#include directives. 5255252723Sdim * 5256252723Sdim * \param visitor callback that will receive pairs of CXCursor/CXSourceRange for 5257252723Sdim * each directive found. 5258252723Sdim * 5259252723Sdim * \returns one of the CXResult enumerators. 5260252723Sdim */ 5261252723SdimCINDEX_LINKAGE CXResult clang_findIncludesInFile(CXTranslationUnit TU, 5262252723Sdim CXFile file, 5263252723Sdim CXCursorAndRangeVisitor visitor); 5264252723Sdim 5265226890Sdim#ifdef __has_feature 5266226890Sdim# if __has_feature(blocks) 5267226890Sdim 5268226890Sdimtypedef enum CXVisitorResult 5269226890Sdim (^CXCursorAndRangeVisitorBlock)(CXCursor, CXSourceRange); 5270226890Sdim 5271226890SdimCINDEX_LINKAGE 5272252723SdimCXResult clang_findReferencesInFileWithBlock(CXCursor, CXFile, 5273252723Sdim CXCursorAndRangeVisitorBlock); 5274226890Sdim 5275252723SdimCINDEX_LINKAGE 5276252723SdimCXResult clang_findIncludesInFileWithBlock(CXTranslationUnit, CXFile, 5277252723Sdim CXCursorAndRangeVisitorBlock); 5278252723Sdim 5279226890Sdim# endif 5280226890Sdim#endif 5281226890Sdim 5282226890Sdim/** 5283235633Sdim * \brief The client's data object that is associated with a CXFile. 5284235633Sdim */ 5285235633Sdimtypedef void *CXIdxClientFile; 5286235633Sdim 5287235633Sdim/** 5288235633Sdim * \brief The client's data object that is associated with a semantic entity. 5289235633Sdim */ 5290235633Sdimtypedef void *CXIdxClientEntity; 5291235633Sdim 5292235633Sdim/** 5293235633Sdim * \brief The client's data object that is associated with a semantic container 5294235633Sdim * of entities. 5295235633Sdim */ 5296235633Sdimtypedef void *CXIdxClientContainer; 5297235633Sdim 5298235633Sdim/** 5299235633Sdim * \brief The client's data object that is associated with an AST file (PCH 5300235633Sdim * or module). 5301235633Sdim */ 5302235633Sdimtypedef void *CXIdxClientASTFile; 5303235633Sdim 5304235633Sdim/** 5305235633Sdim * \brief Source location passed to index callbacks. 5306235633Sdim */ 5307235633Sdimtypedef struct { 5308235633Sdim void *ptr_data[2]; 5309235633Sdim unsigned int_data; 5310235633Sdim} CXIdxLoc; 5311235633Sdim 5312235633Sdim/** 5313245431Sdim * \brief Data for ppIncludedFile callback. 5314235633Sdim */ 5315235633Sdimtypedef struct { 5316235633Sdim /** 5317245431Sdim * \brief Location of '#' in the \#include/\#import directive. 5318235633Sdim */ 5319235633Sdim CXIdxLoc hashLoc; 5320235633Sdim /** 5321245431Sdim * \brief Filename as written in the \#include/\#import directive. 5322235633Sdim */ 5323235633Sdim const char *filename; 5324235633Sdim /** 5325245431Sdim * \brief The actual file that the \#include/\#import directive resolved to. 5326235633Sdim */ 5327235633Sdim CXFile file; 5328235633Sdim int isImport; 5329235633Sdim int isAngled; 5330245431Sdim /** 5331245431Sdim * \brief Non-zero if the directive was automatically turned into a module 5332245431Sdim * import. 5333245431Sdim */ 5334245431Sdim int isModuleImport; 5335235633Sdim} CXIdxIncludedFileInfo; 5336235633Sdim 5337235633Sdim/** 5338245431Sdim * \brief Data for IndexerCallbacks#importedASTFile. 5339235633Sdim */ 5340235633Sdimtypedef struct { 5341245431Sdim /** 5342245431Sdim * \brief Top level AST file containing the imported PCH, module or submodule. 5343245431Sdim */ 5344235633Sdim CXFile file; 5345235633Sdim /** 5346245431Sdim * \brief The imported module or NULL if the AST file is a PCH. 5347235633Sdim */ 5348245431Sdim CXModule module; 5349245431Sdim /** 5350245431Sdim * \brief Location where the file is imported. Applicable only for modules. 5351245431Sdim */ 5352235633Sdim CXIdxLoc loc; 5353235633Sdim /** 5354245431Sdim * \brief Non-zero if an inclusion directive was automatically turned into 5355245431Sdim * a module import. Applicable only for modules. 5356235633Sdim */ 5357245431Sdim int isImplicit; 5358245431Sdim 5359235633Sdim} CXIdxImportedASTFileInfo; 5360235633Sdim 5361235633Sdimtypedef enum { 5362235633Sdim CXIdxEntity_Unexposed = 0, 5363235633Sdim CXIdxEntity_Typedef = 1, 5364235633Sdim CXIdxEntity_Function = 2, 5365235633Sdim CXIdxEntity_Variable = 3, 5366235633Sdim CXIdxEntity_Field = 4, 5367235633Sdim CXIdxEntity_EnumConstant = 5, 5368235633Sdim 5369235633Sdim CXIdxEntity_ObjCClass = 6, 5370235633Sdim CXIdxEntity_ObjCProtocol = 7, 5371235633Sdim CXIdxEntity_ObjCCategory = 8, 5372235633Sdim 5373235633Sdim CXIdxEntity_ObjCInstanceMethod = 9, 5374235633Sdim CXIdxEntity_ObjCClassMethod = 10, 5375235633Sdim CXIdxEntity_ObjCProperty = 11, 5376235633Sdim CXIdxEntity_ObjCIvar = 12, 5377235633Sdim 5378235633Sdim CXIdxEntity_Enum = 13, 5379235633Sdim CXIdxEntity_Struct = 14, 5380235633Sdim CXIdxEntity_Union = 15, 5381235633Sdim 5382235633Sdim CXIdxEntity_CXXClass = 16, 5383235633Sdim CXIdxEntity_CXXNamespace = 17, 5384235633Sdim CXIdxEntity_CXXNamespaceAlias = 18, 5385235633Sdim CXIdxEntity_CXXStaticVariable = 19, 5386235633Sdim CXIdxEntity_CXXStaticMethod = 20, 5387235633Sdim CXIdxEntity_CXXInstanceMethod = 21, 5388235633Sdim CXIdxEntity_CXXConstructor = 22, 5389235633Sdim CXIdxEntity_CXXDestructor = 23, 5390235633Sdim CXIdxEntity_CXXConversionFunction = 24, 5391245431Sdim CXIdxEntity_CXXTypeAlias = 25, 5392245431Sdim CXIdxEntity_CXXInterface = 26 5393235633Sdim 5394235633Sdim} CXIdxEntityKind; 5395235633Sdim 5396235633Sdimtypedef enum { 5397235633Sdim CXIdxEntityLang_None = 0, 5398235633Sdim CXIdxEntityLang_C = 1, 5399235633Sdim CXIdxEntityLang_ObjC = 2, 5400235633Sdim CXIdxEntityLang_CXX = 3 5401235633Sdim} CXIdxEntityLanguage; 5402235633Sdim 5403235633Sdim/** 5404235633Sdim * \brief Extra C++ template information for an entity. This can apply to: 5405235633Sdim * CXIdxEntity_Function 5406235633Sdim * CXIdxEntity_CXXClass 5407235633Sdim * CXIdxEntity_CXXStaticMethod 5408235633Sdim * CXIdxEntity_CXXInstanceMethod 5409235633Sdim * CXIdxEntity_CXXConstructor 5410235633Sdim * CXIdxEntity_CXXConversionFunction 5411235633Sdim * CXIdxEntity_CXXTypeAlias 5412235633Sdim */ 5413235633Sdimtypedef enum { 5414235633Sdim CXIdxEntity_NonTemplate = 0, 5415235633Sdim CXIdxEntity_Template = 1, 5416235633Sdim CXIdxEntity_TemplatePartialSpecialization = 2, 5417235633Sdim CXIdxEntity_TemplateSpecialization = 3 5418235633Sdim} CXIdxEntityCXXTemplateKind; 5419235633Sdim 5420235633Sdimtypedef enum { 5421235633Sdim CXIdxAttr_Unexposed = 0, 5422235633Sdim CXIdxAttr_IBAction = 1, 5423235633Sdim CXIdxAttr_IBOutlet = 2, 5424235633Sdim CXIdxAttr_IBOutletCollection = 3 5425235633Sdim} CXIdxAttrKind; 5426235633Sdim 5427235633Sdimtypedef struct { 5428235633Sdim CXIdxAttrKind kind; 5429235633Sdim CXCursor cursor; 5430235633Sdim CXIdxLoc loc; 5431235633Sdim} CXIdxAttrInfo; 5432235633Sdim 5433235633Sdimtypedef struct { 5434235633Sdim CXIdxEntityKind kind; 5435235633Sdim CXIdxEntityCXXTemplateKind templateKind; 5436235633Sdim CXIdxEntityLanguage lang; 5437235633Sdim const char *name; 5438235633Sdim const char *USR; 5439235633Sdim CXCursor cursor; 5440235633Sdim const CXIdxAttrInfo *const *attributes; 5441235633Sdim unsigned numAttributes; 5442235633Sdim} CXIdxEntityInfo; 5443235633Sdim 5444235633Sdimtypedef struct { 5445235633Sdim CXCursor cursor; 5446235633Sdim} CXIdxContainerInfo; 5447235633Sdim 5448235633Sdimtypedef struct { 5449235633Sdim const CXIdxAttrInfo *attrInfo; 5450235633Sdim const CXIdxEntityInfo *objcClass; 5451235633Sdim CXCursor classCursor; 5452235633Sdim CXIdxLoc classLoc; 5453235633Sdim} CXIdxIBOutletCollectionAttrInfo; 5454235633Sdim 5455252723Sdimtypedef enum { 5456252723Sdim CXIdxDeclFlag_Skipped = 0x1 5457252723Sdim} CXIdxDeclInfoFlags; 5458252723Sdim 5459235633Sdimtypedef struct { 5460235633Sdim const CXIdxEntityInfo *entityInfo; 5461235633Sdim CXCursor cursor; 5462235633Sdim CXIdxLoc loc; 5463235633Sdim const CXIdxContainerInfo *semanticContainer; 5464235633Sdim /** 5465245431Sdim * \brief Generally same as #semanticContainer but can be different in 5466235633Sdim * cases like out-of-line C++ member functions. 5467235633Sdim */ 5468235633Sdim const CXIdxContainerInfo *lexicalContainer; 5469235633Sdim int isRedeclaration; 5470235633Sdim int isDefinition; 5471235633Sdim int isContainer; 5472235633Sdim const CXIdxContainerInfo *declAsContainer; 5473235633Sdim /** 5474235633Sdim * \brief Whether the declaration exists in code or was created implicitly 5475235633Sdim * by the compiler, e.g. implicit objc methods for properties. 5476235633Sdim */ 5477235633Sdim int isImplicit; 5478235633Sdim const CXIdxAttrInfo *const *attributes; 5479235633Sdim unsigned numAttributes; 5480252723Sdim 5481252723Sdim unsigned flags; 5482252723Sdim 5483235633Sdim} CXIdxDeclInfo; 5484235633Sdim 5485235633Sdimtypedef enum { 5486235633Sdim CXIdxObjCContainer_ForwardRef = 0, 5487235633Sdim CXIdxObjCContainer_Interface = 1, 5488235633Sdim CXIdxObjCContainer_Implementation = 2 5489235633Sdim} CXIdxObjCContainerKind; 5490235633Sdim 5491235633Sdimtypedef struct { 5492235633Sdim const CXIdxDeclInfo *declInfo; 5493235633Sdim CXIdxObjCContainerKind kind; 5494235633Sdim} CXIdxObjCContainerDeclInfo; 5495235633Sdim 5496235633Sdimtypedef struct { 5497235633Sdim const CXIdxEntityInfo *base; 5498235633Sdim CXCursor cursor; 5499235633Sdim CXIdxLoc loc; 5500235633Sdim} CXIdxBaseClassInfo; 5501235633Sdim 5502235633Sdimtypedef struct { 5503235633Sdim const CXIdxEntityInfo *protocol; 5504235633Sdim CXCursor cursor; 5505235633Sdim CXIdxLoc loc; 5506235633Sdim} CXIdxObjCProtocolRefInfo; 5507235633Sdim 5508235633Sdimtypedef struct { 5509235633Sdim const CXIdxObjCProtocolRefInfo *const *protocols; 5510235633Sdim unsigned numProtocols; 5511235633Sdim} CXIdxObjCProtocolRefListInfo; 5512235633Sdim 5513235633Sdimtypedef struct { 5514235633Sdim const CXIdxObjCContainerDeclInfo *containerInfo; 5515235633Sdim const CXIdxBaseClassInfo *superInfo; 5516235633Sdim const CXIdxObjCProtocolRefListInfo *protocols; 5517235633Sdim} CXIdxObjCInterfaceDeclInfo; 5518235633Sdim 5519235633Sdimtypedef struct { 5520235633Sdim const CXIdxObjCContainerDeclInfo *containerInfo; 5521235633Sdim const CXIdxEntityInfo *objcClass; 5522235633Sdim CXCursor classCursor; 5523235633Sdim CXIdxLoc classLoc; 5524235633Sdim const CXIdxObjCProtocolRefListInfo *protocols; 5525235633Sdim} CXIdxObjCCategoryDeclInfo; 5526235633Sdim 5527235633Sdimtypedef struct { 5528235633Sdim const CXIdxDeclInfo *declInfo; 5529235633Sdim const CXIdxEntityInfo *getter; 5530235633Sdim const CXIdxEntityInfo *setter; 5531235633Sdim} CXIdxObjCPropertyDeclInfo; 5532235633Sdim 5533235633Sdimtypedef struct { 5534235633Sdim const CXIdxDeclInfo *declInfo; 5535235633Sdim const CXIdxBaseClassInfo *const *bases; 5536235633Sdim unsigned numBases; 5537235633Sdim} CXIdxCXXClassDeclInfo; 5538235633Sdim 5539235633Sdim/** 5540245431Sdim * \brief Data for IndexerCallbacks#indexEntityReference. 5541235633Sdim */ 5542235633Sdimtypedef enum { 5543235633Sdim /** 5544235633Sdim * \brief The entity is referenced directly in user's code. 5545235633Sdim */ 5546235633Sdim CXIdxEntityRef_Direct = 1, 5547235633Sdim /** 5548235633Sdim * \brief An implicit reference, e.g. a reference of an ObjC method via the 5549235633Sdim * dot syntax. 5550235633Sdim */ 5551235633Sdim CXIdxEntityRef_Implicit = 2 5552235633Sdim} CXIdxEntityRefKind; 5553235633Sdim 5554235633Sdim/** 5555245431Sdim * \brief Data for IndexerCallbacks#indexEntityReference. 5556235633Sdim */ 5557235633Sdimtypedef struct { 5558235633Sdim CXIdxEntityRefKind kind; 5559235633Sdim /** 5560235633Sdim * \brief Reference cursor. 5561235633Sdim */ 5562235633Sdim CXCursor cursor; 5563235633Sdim CXIdxLoc loc; 5564235633Sdim /** 5565235633Sdim * \brief The entity that gets referenced. 5566235633Sdim */ 5567235633Sdim const CXIdxEntityInfo *referencedEntity; 5568235633Sdim /** 5569235633Sdim * \brief Immediate "parent" of the reference. For example: 5570235633Sdim * 5571235633Sdim * \code 5572235633Sdim * Foo *var; 5573235633Sdim * \endcode 5574235633Sdim * 5575235633Sdim * The parent of reference of type 'Foo' is the variable 'var'. 5576235633Sdim * For references inside statement bodies of functions/methods, 5577235633Sdim * the parentEntity will be the function/method. 5578235633Sdim */ 5579235633Sdim const CXIdxEntityInfo *parentEntity; 5580235633Sdim /** 5581235633Sdim * \brief Lexical container context of the reference. 5582235633Sdim */ 5583235633Sdim const CXIdxContainerInfo *container; 5584235633Sdim} CXIdxEntityRefInfo; 5585235633Sdim 5586245431Sdim/** 5587245431Sdim * \brief A group of callbacks used by #clang_indexSourceFile and 5588245431Sdim * #clang_indexTranslationUnit. 5589245431Sdim */ 5590235633Sdimtypedef struct { 5591235633Sdim /** 5592235633Sdim * \brief Called periodically to check whether indexing should be aborted. 5593235633Sdim * Should return 0 to continue, and non-zero to abort. 5594235633Sdim */ 5595235633Sdim int (*abortQuery)(CXClientData client_data, void *reserved); 5596235633Sdim 5597235633Sdim /** 5598235633Sdim * \brief Called at the end of indexing; passes the complete diagnostic set. 5599235633Sdim */ 5600235633Sdim void (*diagnostic)(CXClientData client_data, 5601235633Sdim CXDiagnosticSet, void *reserved); 5602235633Sdim 5603235633Sdim CXIdxClientFile (*enteredMainFile)(CXClientData client_data, 5604245431Sdim CXFile mainFile, void *reserved); 5605235633Sdim 5606235633Sdim /** 5607245431Sdim * \brief Called when a file gets \#included/\#imported. 5608235633Sdim */ 5609235633Sdim CXIdxClientFile (*ppIncludedFile)(CXClientData client_data, 5610235633Sdim const CXIdxIncludedFileInfo *); 5611235633Sdim 5612235633Sdim /** 5613235633Sdim * \brief Called when a AST file (PCH or module) gets imported. 5614235633Sdim * 5615235633Sdim * AST files will not get indexed (there will not be callbacks to index all 5616235633Sdim * the entities in an AST file). The recommended action is that, if the AST 5617245431Sdim * file is not already indexed, to initiate a new indexing job specific to 5618245431Sdim * the AST file. 5619235633Sdim */ 5620235633Sdim CXIdxClientASTFile (*importedASTFile)(CXClientData client_data, 5621235633Sdim const CXIdxImportedASTFileInfo *); 5622235633Sdim 5623235633Sdim /** 5624235633Sdim * \brief Called at the beginning of indexing a translation unit. 5625235633Sdim */ 5626235633Sdim CXIdxClientContainer (*startedTranslationUnit)(CXClientData client_data, 5627235633Sdim void *reserved); 5628235633Sdim 5629235633Sdim void (*indexDeclaration)(CXClientData client_data, 5630235633Sdim const CXIdxDeclInfo *); 5631235633Sdim 5632235633Sdim /** 5633235633Sdim * \brief Called to index a reference of an entity. 5634235633Sdim */ 5635235633Sdim void (*indexEntityReference)(CXClientData client_data, 5636235633Sdim const CXIdxEntityRefInfo *); 5637235633Sdim 5638235633Sdim} IndexerCallbacks; 5639235633Sdim 5640235633SdimCINDEX_LINKAGE int clang_index_isEntityObjCContainerKind(CXIdxEntityKind); 5641235633SdimCINDEX_LINKAGE const CXIdxObjCContainerDeclInfo * 5642235633Sdimclang_index_getObjCContainerDeclInfo(const CXIdxDeclInfo *); 5643235633Sdim 5644235633SdimCINDEX_LINKAGE const CXIdxObjCInterfaceDeclInfo * 5645235633Sdimclang_index_getObjCInterfaceDeclInfo(const CXIdxDeclInfo *); 5646235633Sdim 5647235633SdimCINDEX_LINKAGE 5648235633Sdimconst CXIdxObjCCategoryDeclInfo * 5649235633Sdimclang_index_getObjCCategoryDeclInfo(const CXIdxDeclInfo *); 5650235633Sdim 5651235633SdimCINDEX_LINKAGE const CXIdxObjCProtocolRefListInfo * 5652235633Sdimclang_index_getObjCProtocolRefListInfo(const CXIdxDeclInfo *); 5653235633Sdim 5654235633SdimCINDEX_LINKAGE const CXIdxObjCPropertyDeclInfo * 5655235633Sdimclang_index_getObjCPropertyDeclInfo(const CXIdxDeclInfo *); 5656235633Sdim 5657235633SdimCINDEX_LINKAGE const CXIdxIBOutletCollectionAttrInfo * 5658235633Sdimclang_index_getIBOutletCollectionAttrInfo(const CXIdxAttrInfo *); 5659235633Sdim 5660235633SdimCINDEX_LINKAGE const CXIdxCXXClassDeclInfo * 5661235633Sdimclang_index_getCXXClassDeclInfo(const CXIdxDeclInfo *); 5662235633Sdim 5663235633Sdim/** 5664235633Sdim * \brief For retrieving a custom CXIdxClientContainer attached to a 5665235633Sdim * container. 5666235633Sdim */ 5667235633SdimCINDEX_LINKAGE CXIdxClientContainer 5668235633Sdimclang_index_getClientContainer(const CXIdxContainerInfo *); 5669235633Sdim 5670235633Sdim/** 5671235633Sdim * \brief For setting a custom CXIdxClientContainer attached to a 5672235633Sdim * container. 5673235633Sdim */ 5674235633SdimCINDEX_LINKAGE void 5675235633Sdimclang_index_setClientContainer(const CXIdxContainerInfo *,CXIdxClientContainer); 5676235633Sdim 5677235633Sdim/** 5678235633Sdim * \brief For retrieving a custom CXIdxClientEntity attached to an entity. 5679235633Sdim */ 5680235633SdimCINDEX_LINKAGE CXIdxClientEntity 5681235633Sdimclang_index_getClientEntity(const CXIdxEntityInfo *); 5682235633Sdim 5683235633Sdim/** 5684235633Sdim * \brief For setting a custom CXIdxClientEntity attached to an entity. 5685235633Sdim */ 5686235633SdimCINDEX_LINKAGE void 5687235633Sdimclang_index_setClientEntity(const CXIdxEntityInfo *, CXIdxClientEntity); 5688235633Sdim 5689235633Sdim/** 5690252723Sdim * \brief An indexing action/session, to be applied to one or multiple 5691252723Sdim * translation units. 5692235633Sdim */ 5693235633Sdimtypedef void *CXIndexAction; 5694235633Sdim 5695235633Sdim/** 5696252723Sdim * \brief An indexing action/session, to be applied to one or multiple 5697252723Sdim * translation units. 5698235633Sdim * 5699235633Sdim * \param CIdx The index object with which the index action will be associated. 5700235633Sdim */ 5701235633SdimCINDEX_LINKAGE CXIndexAction clang_IndexAction_create(CXIndex CIdx); 5702235633Sdim 5703235633Sdim/** 5704235633Sdim * \brief Destroy the given index action. 5705235633Sdim * 5706235633Sdim * The index action must not be destroyed until all of the translation units 5707235633Sdim * created within that index action have been destroyed. 5708235633Sdim */ 5709235633SdimCINDEX_LINKAGE void clang_IndexAction_dispose(CXIndexAction); 5710235633Sdim 5711235633Sdimtypedef enum { 5712235633Sdim /** 5713235633Sdim * \brief Used to indicate that no special indexing options are needed. 5714235633Sdim */ 5715235633Sdim CXIndexOpt_None = 0x0, 5716235633Sdim 5717235633Sdim /** 5718245431Sdim * \brief Used to indicate that IndexerCallbacks#indexEntityReference should 5719245431Sdim * be invoked for only one reference of an entity per source file that does 5720245431Sdim * not also include a declaration/definition of the entity. 5721235633Sdim */ 5722235633Sdim CXIndexOpt_SuppressRedundantRefs = 0x1, 5723235633Sdim 5724235633Sdim /** 5725235633Sdim * \brief Function-local symbols should be indexed. If this is not set 5726235633Sdim * function-local symbols will be ignored. 5727235633Sdim */ 5728235633Sdim CXIndexOpt_IndexFunctionLocalSymbols = 0x2, 5729235633Sdim 5730235633Sdim /** 5731235633Sdim * \brief Implicit function/class template instantiations should be indexed. 5732235633Sdim * If this is not set, implicit instantiations will be ignored. 5733235633Sdim */ 5734235633Sdim CXIndexOpt_IndexImplicitTemplateInstantiations = 0x4, 5735235633Sdim 5736235633Sdim /** 5737235633Sdim * \brief Suppress all compiler warnings when parsing for indexing. 5738235633Sdim */ 5739252723Sdim CXIndexOpt_SuppressWarnings = 0x8, 5740252723Sdim 5741252723Sdim /** 5742252723Sdim * \brief Skip a function/method body that was already parsed during an 5743252723Sdim * indexing session assosiated with a \c CXIndexAction object. 5744252723Sdim * Bodies in system headers are always skipped. 5745252723Sdim */ 5746252723Sdim CXIndexOpt_SkipParsedBodiesInSession = 0x10 5747252723Sdim 5748235633Sdim} CXIndexOptFlags; 5749235633Sdim 5750235633Sdim/** 5751235633Sdim * \brief Index the given source file and the translation unit corresponding 5752245431Sdim * to that file via callbacks implemented through #IndexerCallbacks. 5753235633Sdim * 5754235633Sdim * \param client_data pointer data supplied by the client, which will 5755235633Sdim * be passed to the invoked callbacks. 5756235633Sdim * 5757235633Sdim * \param index_callbacks Pointer to indexing callbacks that the client 5758235633Sdim * implements. 5759235633Sdim * 5760245431Sdim * \param index_callbacks_size Size of #IndexerCallbacks structure that gets 5761235633Sdim * passed in index_callbacks. 5762235633Sdim * 5763235633Sdim * \param index_options A bitmask of options that affects how indexing is 5764235633Sdim * performed. This should be a bitwise OR of the CXIndexOpt_XXX flags. 5765235633Sdim * 5766235633Sdim * \param out_TU [out] pointer to store a CXTranslationUnit that can be reused 5767235633Sdim * after indexing is finished. Set to NULL if you do not require it. 5768235633Sdim * 5769235633Sdim * \returns If there is a failure from which the there is no recovery, returns 5770235633Sdim * non-zero, otherwise returns 0. 5771235633Sdim * 5772245431Sdim * The rest of the parameters are the same as #clang_parseTranslationUnit. 5773235633Sdim */ 5774235633SdimCINDEX_LINKAGE int clang_indexSourceFile(CXIndexAction, 5775235633Sdim CXClientData client_data, 5776235633Sdim IndexerCallbacks *index_callbacks, 5777235633Sdim unsigned index_callbacks_size, 5778235633Sdim unsigned index_options, 5779235633Sdim const char *source_filename, 5780235633Sdim const char * const *command_line_args, 5781235633Sdim int num_command_line_args, 5782235633Sdim struct CXUnsavedFile *unsaved_files, 5783235633Sdim unsigned num_unsaved_files, 5784235633Sdim CXTranslationUnit *out_TU, 5785235633Sdim unsigned TU_options); 5786235633Sdim 5787235633Sdim/** 5788235633Sdim * \brief Index the given translation unit via callbacks implemented through 5789245431Sdim * #IndexerCallbacks. 5790235633Sdim * 5791235633Sdim * The order of callback invocations is not guaranteed to be the same as 5792235633Sdim * when indexing a source file. The high level order will be: 5793235633Sdim * 5794235633Sdim * -Preprocessor callbacks invocations 5795235633Sdim * -Declaration/reference callbacks invocations 5796235633Sdim * -Diagnostic callback invocations 5797235633Sdim * 5798245431Sdim * The parameters are the same as #clang_indexSourceFile. 5799235633Sdim * 5800235633Sdim * \returns If there is a failure from which the there is no recovery, returns 5801235633Sdim * non-zero, otherwise returns 0. 5802235633Sdim */ 5803235633SdimCINDEX_LINKAGE int clang_indexTranslationUnit(CXIndexAction, 5804235633Sdim CXClientData client_data, 5805235633Sdim IndexerCallbacks *index_callbacks, 5806235633Sdim unsigned index_callbacks_size, 5807235633Sdim unsigned index_options, 5808235633Sdim CXTranslationUnit); 5809235633Sdim 5810235633Sdim/** 5811235633Sdim * \brief Retrieve the CXIdxFile, file, line, column, and offset represented by 5812235633Sdim * the given CXIdxLoc. 5813235633Sdim * 5814235633Sdim * If the location refers into a macro expansion, retrieves the 5815235633Sdim * location of the macro expansion and if it refers into a macro argument 5816235633Sdim * retrieves the location of the argument. 5817235633Sdim */ 5818235633SdimCINDEX_LINKAGE void clang_indexLoc_getFileLocation(CXIdxLoc loc, 5819235633Sdim CXIdxClientFile *indexFile, 5820235633Sdim CXFile *file, 5821235633Sdim unsigned *line, 5822235633Sdim unsigned *column, 5823235633Sdim unsigned *offset); 5824235633Sdim 5825235633Sdim/** 5826235633Sdim * \brief Retrieve the CXSourceLocation represented by the given CXIdxLoc. 5827235633Sdim */ 5828235633SdimCINDEX_LINKAGE 5829235633SdimCXSourceLocation clang_indexLoc_getCXSourceLocation(CXIdxLoc loc); 5830235633Sdim 5831235633Sdim/** 5832224145Sdim * @} 5833224145Sdim */ 5834224145Sdim 5835226890Sdim/** 5836226890Sdim * @} 5837226890Sdim */ 5838226890Sdim 5839198092Srdivacky#ifdef __cplusplus 5840198092Srdivacky} 5841198092Srdivacky#endif 5842198092Srdivacky#endif 5843198092Srdivacky 5844