Index.h revision 210299
1198092Srdivacky/*===-- clang-c/Index.h - Indexing Public C Interface -------------*- C -*-===*\ 2198092Srdivacky|* *| 3198092Srdivacky|* The LLVM Compiler Infrastructure *| 4198092Srdivacky|* *| 5198092Srdivacky|* This file is distributed under the University of Illinois Open Source *| 6198092Srdivacky|* License. See LICENSE.TXT for details. *| 7198092Srdivacky|* *| 8198092Srdivacky|*===----------------------------------------------------------------------===*| 9198092Srdivacky|* *| 10198092Srdivacky|* This header provides a public inferface to a Clang library for extracting *| 11198092Srdivacky|* high-level symbol information from source files without exposing the full *| 12198092Srdivacky|* Clang C++ API. *| 13198092Srdivacky|* *| 14198092Srdivacky\*===----------------------------------------------------------------------===*/ 15198092Srdivacky 16198092Srdivacky#ifndef CLANG_C_INDEX_H 17198092Srdivacky#define CLANG_C_INDEX_H 18198092Srdivacky 19198893Srdivacky#include <sys/stat.h> 20201361Srdivacky#include <time.h> 21204643Srdivacky#include <stdio.h> 22198893Srdivacky 23198092Srdivacky#ifdef __cplusplus 24198092Srdivackyextern "C" { 25198092Srdivacky#endif 26198092Srdivacky 27198893Srdivacky/* MSVC DLL import/export. */ 28198893Srdivacky#ifdef _MSC_VER 29198893Srdivacky #ifdef _CINDEX_LIB_ 30198893Srdivacky #define CINDEX_LINKAGE __declspec(dllexport) 31198893Srdivacky #else 32198893Srdivacky #define CINDEX_LINKAGE __declspec(dllimport) 33198893Srdivacky #endif 34198893Srdivacky#else 35198893Srdivacky #define CINDEX_LINKAGE 36198893Srdivacky#endif 37198893Srdivacky 38202879Srdivacky/** \defgroup CINDEX C Interface to Clang 39202879Srdivacky * 40203955Srdivacky * The C Interface to Clang provides a relatively small API that exposes 41202879Srdivacky * facilities for parsing source code into an abstract syntax tree (AST), 42202879Srdivacky * loading already-parsed ASTs, traversing the AST, associating 43202879Srdivacky * physical source locations with elements within the AST, and other 44202879Srdivacky * facilities that support Clang-based development tools. 45202879Srdivacky * 46203955Srdivacky * This C interface to Clang will never provide all of the information 47202879Srdivacky * representation stored in Clang's C++ AST, nor should it: the intent is to 48202879Srdivacky * maintain an API that is relatively stable from one release to the next, 49202879Srdivacky * providing only the basic functionality needed to support development tools. 50203955Srdivacky * 51203955Srdivacky * To avoid namespace pollution, data types are prefixed with "CX" and 52202879Srdivacky * functions are prefixed with "clang_". 53202879Srdivacky * 54202879Srdivacky * @{ 55202879Srdivacky */ 56203955Srdivacky 57202879Srdivacky/** 58202879Srdivacky * \brief An "index" that consists of a set of translation units that would 59202879Srdivacky * typically be linked together into an executable or library. 60202879Srdivacky */ 61202879Srdivackytypedef void *CXIndex; 62198092Srdivacky 63202879Srdivacky/** 64202879Srdivacky * \brief A single translation unit, which resides in an index. 65202879Srdivacky */ 66198092Srdivackytypedef void *CXTranslationUnit; /* A translation unit instance. */ 67198092Srdivacky 68200583Srdivacky/** 69202879Srdivacky * \brief Opaque pointer representing client data that will be passed through 70202879Srdivacky * to various callbacks and visitors. 71202879Srdivacky */ 72202879Srdivackytypedef void *CXClientData; 73203955Srdivacky 74202879Srdivacky/** 75200583Srdivacky * \brief Provides the contents of a file that has not yet been saved to disk. 76200583Srdivacky * 77200583Srdivacky * Each CXUnsavedFile instance provides the name of a file on the 78200583Srdivacky * system along with the current contents of that file that have not 79200583Srdivacky * yet been saved to disk. 80200583Srdivacky */ 81200583Srdivackystruct CXUnsavedFile { 82203955Srdivacky /** 83203955Srdivacky * \brief The file whose contents have not yet been saved. 84200583Srdivacky * 85200583Srdivacky * This file must already exist in the file system. 86200583Srdivacky */ 87200583Srdivacky const char *Filename; 88200583Srdivacky 89203955Srdivacky /** 90204643Srdivacky * \brief A buffer containing the unsaved contents of this file. 91200583Srdivacky */ 92200583Srdivacky const char *Contents; 93200583Srdivacky 94200583Srdivacky /** 95204643Srdivacky * \brief The length of the unsaved contents of this buffer. 96200583Srdivacky */ 97200583Srdivacky unsigned long Length; 98200583Srdivacky}; 99200583Srdivacky 100199482Srdivacky/** 101202879Srdivacky * \defgroup CINDEX_STRING String manipulation routines 102202879Srdivacky * 103202879Srdivacky * @{ 104199482Srdivacky */ 105203955Srdivacky 106202879Srdivacky/** 107202879Srdivacky * \brief A character string. 108202879Srdivacky * 109202879Srdivacky * The \c CXString type is used to return strings from the interface when 110202879Srdivacky * the ownership of that string might different from one call to the next. 111202879Srdivacky * Use \c clang_getCString() to retrieve the string data and, once finished 112202879Srdivacky * with the string data, call \c clang_disposeString() to free the string. 113202879Srdivacky */ 114199482Srdivackytypedef struct { 115199482Srdivacky const char *Spelling; 116199482Srdivacky /* A 1 value indicates the clang_ indexing API needed to allocate the string 117199482Srdivacky (and it must be freed by clang_disposeString()). */ 118199482Srdivacky int MustFreeString; 119199482Srdivacky} CXString; 120199482Srdivacky 121202879Srdivacky/** 122202879Srdivacky * \brief Retrieve the character data associated with the given string. 123202879Srdivacky */ 124199482SrdivackyCINDEX_LINKAGE const char *clang_getCString(CXString string); 125199482Srdivacky 126202879Srdivacky/** 127202879Srdivacky * \brief Free the given string, 128202879Srdivacky */ 129199482SrdivackyCINDEX_LINKAGE void clang_disposeString(CXString string); 130199482Srdivacky 131202879Srdivacky/** 132202879Srdivacky * @} 133202879Srdivacky */ 134203955Srdivacky 135203955Srdivacky/** 136198398Srdivacky * \brief clang_createIndex() provides a shared context for creating 137198398Srdivacky * translation units. It provides two options: 138198398Srdivacky * 139198398Srdivacky * - excludeDeclarationsFromPCH: When non-zero, allows enumeration of "local" 140198398Srdivacky * declarations (when loading any new translation units). A "local" declaration 141203955Srdivacky * is one that belongs in the translation unit itself and not in a precompiled 142198398Srdivacky * header that was used by the translation unit. If zero, all declarations 143198398Srdivacky * will be enumerated. 144198398Srdivacky * 145198398Srdivacky * Here is an example: 146198398Srdivacky * 147204643Srdivacky * // excludeDeclsFromPCH = 1, displayDiagnostics=1 148204643Srdivacky * Idx = clang_createIndex(1, 1); 149198398Srdivacky * 150198398Srdivacky * // IndexTest.pch was produced with the following command: 151198398Srdivacky * // "clang -x c IndexTest.h -emit-ast -o IndexTest.pch" 152198398Srdivacky * TU = clang_createTranslationUnit(Idx, "IndexTest.pch"); 153198398Srdivacky * 154198398Srdivacky * // This will load all the symbols from 'IndexTest.pch' 155203955Srdivacky * clang_visitChildren(clang_getTranslationUnitCursor(TU), 156202879Srdivacky * TranslationUnitVisitor, 0); 157198398Srdivacky * clang_disposeTranslationUnit(TU); 158198398Srdivacky * 159198398Srdivacky * // This will load all the symbols from 'IndexTest.c', excluding symbols 160198398Srdivacky * // from 'IndexTest.pch'. 161203955Srdivacky * char *args[] = { "-Xclang", "-include-pch=IndexTest.pch" }; 162203955Srdivacky * TU = clang_createTranslationUnitFromSourceFile(Idx, "IndexTest.c", 2, args, 163203955Srdivacky * 0, 0); 164202879Srdivacky * clang_visitChildren(clang_getTranslationUnitCursor(TU), 165202879Srdivacky * TranslationUnitVisitor, 0); 166198398Srdivacky * clang_disposeTranslationUnit(TU); 167198398Srdivacky * 168198398Srdivacky * This process of creating the 'pch', loading it separately, and using it (via 169198398Srdivacky * -include-pch) allows 'excludeDeclsFromPCH' to remove redundant callbacks 170198398Srdivacky * (which gives the indexer the same performance benefit as the compiler). 171198398Srdivacky */ 172204643SrdivackyCINDEX_LINKAGE CXIndex clang_createIndex(int excludeDeclarationsFromPCH, 173204643Srdivacky int displayDiagnostics); 174205219Srdivacky 175203955Srdivacky/** 176203955Srdivacky * \brief Destroy the given index. 177203955Srdivacky * 178203955Srdivacky * The index must not be destroyed until all of the translation units created 179203955Srdivacky * within that index have been destroyed. 180203955Srdivacky */ 181200583SrdivackyCINDEX_LINKAGE void clang_disposeIndex(CXIndex index); 182198092Srdivacky 183202879Srdivacky/** 184203955Srdivacky * \brief Request that AST's be generated externally for API calls which parse 185200583Srdivacky * source code on the fly, e.g. \see createTranslationUnitFromSourceFile. 186200583Srdivacky * 187200583Srdivacky * Note: This is for debugging purposes only, and may be removed at a later 188200583Srdivacky * date. 189200583Srdivacky * 190200583Srdivacky * \param index - The index to update. 191200583Srdivacky * \param value - The new flag value. 192200583Srdivacky */ 193200583SrdivackyCINDEX_LINKAGE void clang_setUseExternalASTGeneration(CXIndex index, 194200583Srdivacky int value); 195202879Srdivacky/** 196202879Srdivacky * \defgroup CINDEX_FILES File manipulation routines 197202879Srdivacky * 198202879Srdivacky * @{ 199202879Srdivacky */ 200203955Srdivacky 201202879Srdivacky/** 202202879Srdivacky * \brief A particular source file that is part of a translation unit. 203202879Srdivacky */ 204202879Srdivackytypedef void *CXFile; 205198092Srdivacky 206203955Srdivacky 207202879Srdivacky/** 208202879Srdivacky * \brief Retrieve the complete file and path name of the given file. 209202879Srdivacky */ 210204643SrdivackyCINDEX_LINKAGE CXString clang_getFileName(CXFile SFile); 211203955Srdivacky 212202879Srdivacky/** 213202879Srdivacky * \brief Retrieve the last modification time of the given file. 214202879Srdivacky */ 215202879SrdivackyCINDEX_LINKAGE time_t clang_getFileTime(CXFile SFile); 216198092Srdivacky 217202879Srdivacky/** 218202879Srdivacky * \brief Retrieve a file handle within the given translation unit. 219202879Srdivacky * 220202879Srdivacky * \param tu the translation unit 221203955Srdivacky * 222202879Srdivacky * \param file_name the name of the file. 223202879Srdivacky * 224202879Srdivacky * \returns the file handle for the named file in the translation unit \p tu, 225202879Srdivacky * or a NULL file handle if the file was not a part of this translation unit. 226202879Srdivacky */ 227203955SrdivackyCINDEX_LINKAGE CXFile clang_getFile(CXTranslationUnit tu, 228202879Srdivacky const char *file_name); 229203955Srdivacky 230202879Srdivacky/** 231202879Srdivacky * @} 232202879Srdivacky */ 233198092Srdivacky 234202879Srdivacky/** 235202879Srdivacky * \defgroup CINDEX_LOCATIONS Physical source locations 236202879Srdivacky * 237202879Srdivacky * Clang represents physical source locations in its abstract syntax tree in 238202879Srdivacky * great detail, with file, line, and column information for the majority of 239202879Srdivacky * the tokens parsed in the source code. These data types and functions are 240202879Srdivacky * used to represent source location information, either for a particular 241202879Srdivacky * point in the program or for a range of points in the program, and extract 242202879Srdivacky * specific location information from those data types. 243202879Srdivacky * 244202879Srdivacky * @{ 245202879Srdivacky */ 246203955Srdivacky 247202879Srdivacky/** 248202879Srdivacky * \brief Identifies a specific source location within a translation 249202879Srdivacky * unit. 250202879Srdivacky * 251202879Srdivacky * Use clang_getInstantiationLocation() to map a source location to a 252202879Srdivacky * particular file, line, and column. 253202879Srdivacky */ 254202879Srdivackytypedef struct { 255203955Srdivacky void *ptr_data[2]; 256202879Srdivacky unsigned int_data; 257202879Srdivacky} CXSourceLocation; 258198092Srdivacky 259202879Srdivacky/** 260203955Srdivacky * \brief Identifies a half-open character range in the source code. 261202879Srdivacky * 262202879Srdivacky * Use clang_getRangeStart() and clang_getRangeEnd() to retrieve the 263202879Srdivacky * starting and end locations from a source range, respectively. 264198893Srdivacky */ 265202879Srdivackytypedef struct { 266203955Srdivacky void *ptr_data[2]; 267202879Srdivacky unsigned begin_int_data; 268202879Srdivacky unsigned end_int_data; 269202879Srdivacky} CXSourceRange; 270198893Srdivacky 271202879Srdivacky/** 272202879Srdivacky * \brief Retrieve a NULL (invalid) source location. 273198092Srdivacky */ 274202879SrdivackyCINDEX_LINKAGE CXSourceLocation clang_getNullLocation(); 275203955Srdivacky 276202879Srdivacky/** 277202879Srdivacky * \determine Determine whether two source locations, which must refer into 278203955Srdivacky * the same translation unit, refer to exactly the same point in the source 279202879Srdivacky * code. 280202879Srdivacky * 281202879Srdivacky * \returns non-zero if the source locations refer to the same location, zero 282202879Srdivacky * if they refer to different locations. 283202879Srdivacky */ 284202879SrdivackyCINDEX_LINKAGE unsigned clang_equalLocations(CXSourceLocation loc1, 285202879Srdivacky CXSourceLocation loc2); 286203955Srdivacky 287202879Srdivacky/** 288203955Srdivacky * \brief Retrieves the source location associated with a given file/line/column 289203955Srdivacky * in a particular translation unit. 290202879Srdivacky */ 291202879SrdivackyCINDEX_LINKAGE CXSourceLocation clang_getLocation(CXTranslationUnit tu, 292202879Srdivacky CXFile file, 293202879Srdivacky unsigned line, 294202879Srdivacky unsigned column); 295203955Srdivacky 296203955Srdivacky/** 297203955Srdivacky * \brief Retrieve a NULL (invalid) source range. 298203955Srdivacky */ 299203955SrdivackyCINDEX_LINKAGE CXSourceRange clang_getNullRange(); 300205219Srdivacky 301202879Srdivacky/** 302202879Srdivacky * \brief Retrieve a source range given the beginning and ending source 303202879Srdivacky * locations. 304202879Srdivacky */ 305202879SrdivackyCINDEX_LINKAGE CXSourceRange clang_getRange(CXSourceLocation begin, 306202879Srdivacky CXSourceLocation end); 307203955Srdivacky 308202879Srdivacky/** 309203955Srdivacky * \brief Retrieve the file, line, column, and offset represented by 310203955Srdivacky * the given source location. 311202879Srdivacky * 312203955Srdivacky * \param location the location within a source file that will be decomposed 313203955Srdivacky * into its parts. 314202879Srdivacky * 315203955Srdivacky * \param file [out] if non-NULL, will be set to the file to which the given 316202879Srdivacky * source location points. 317202879Srdivacky * 318203955Srdivacky * \param line [out] if non-NULL, will be set to the line to which the given 319202879Srdivacky * source location points. 320202879Srdivacky * 321203955Srdivacky * \param column [out] if non-NULL, will be set to the column to which the given 322203955Srdivacky * source location points. 323203955Srdivacky * 324203955Srdivacky * \param offset [out] if non-NULL, will be set to the offset into the 325203955Srdivacky * buffer to which the given source location points. 326202879Srdivacky */ 327202879SrdivackyCINDEX_LINKAGE void clang_getInstantiationLocation(CXSourceLocation location, 328202879Srdivacky CXFile *file, 329202879Srdivacky unsigned *line, 330203955Srdivacky unsigned *column, 331203955Srdivacky unsigned *offset); 332202379Srdivacky 333202879Srdivacky/** 334203955Srdivacky * \brief Retrieve a source location representing the first character within a 335203955Srdivacky * source range. 336198092Srdivacky */ 337202879SrdivackyCINDEX_LINKAGE CXSourceLocation clang_getRangeStart(CXSourceRange range); 338198092Srdivacky 339202879Srdivacky/** 340203955Srdivacky * \brief Retrieve a source location representing the last character within a 341203955Srdivacky * source range. 342202879Srdivacky */ 343202879SrdivackyCINDEX_LINKAGE CXSourceLocation clang_getRangeEnd(CXSourceRange range); 344202379Srdivacky 345202879Srdivacky/** 346202879Srdivacky * @} 347202879Srdivacky */ 348202379Srdivacky 349202879Srdivacky/** 350203955Srdivacky * \defgroup CINDEX_DIAG Diagnostic reporting 351203955Srdivacky * 352203955Srdivacky * @{ 353203955Srdivacky */ 354203955Srdivacky 355203955Srdivacky/** 356203955Srdivacky * \brief Describes the severity of a particular diagnostic. 357203955Srdivacky */ 358203955Srdivackyenum CXDiagnosticSeverity { 359203955Srdivacky /** 360205219Srdivacky * \brief A diagnostic that has been suppressed, e.g., by a command-line 361203955Srdivacky * option. 362203955Srdivacky */ 363203955Srdivacky CXDiagnostic_Ignored = 0, 364205219Srdivacky 365203955Srdivacky /** 366203955Srdivacky * \brief This diagnostic is a note that should be attached to the 367203955Srdivacky * previous (non-note) diagnostic. 368203955Srdivacky */ 369203955Srdivacky CXDiagnostic_Note = 1, 370203955Srdivacky 371203955Srdivacky /** 372203955Srdivacky * \brief This diagnostic indicates suspicious code that may not be 373203955Srdivacky * wrong. 374203955Srdivacky */ 375203955Srdivacky CXDiagnostic_Warning = 2, 376203955Srdivacky 377203955Srdivacky /** 378203955Srdivacky * \brief This diagnostic indicates that the code is ill-formed. 379203955Srdivacky */ 380203955Srdivacky CXDiagnostic_Error = 3, 381203955Srdivacky 382203955Srdivacky /** 383203955Srdivacky * \brief This diagnostic indicates that the code is ill-formed such 384203955Srdivacky * that future parser recovery is unlikely to produce useful 385203955Srdivacky * results. 386203955Srdivacky */ 387203955Srdivacky CXDiagnostic_Fatal = 4 388203955Srdivacky}; 389203955Srdivacky 390203955Srdivacky/** 391204643Srdivacky * \brief A single diagnostic, containing the diagnostic's severity, 392204643Srdivacky * location, text, source ranges, and fix-it hints. 393203955Srdivacky */ 394204643Srdivackytypedef void *CXDiagnostic; 395204643Srdivacky 396204643Srdivacky/** 397204643Srdivacky * \brief Determine the number of diagnostics produced for the given 398204643Srdivacky * translation unit. 399204643Srdivacky */ 400204643SrdivackyCINDEX_LINKAGE unsigned clang_getNumDiagnostics(CXTranslationUnit Unit); 401204643Srdivacky 402204643Srdivacky/** 403204643Srdivacky * \brief Retrieve a diagnostic associated with the given translation unit. 404204643Srdivacky * 405204643Srdivacky * \param Unit the translation unit to query. 406204643Srdivacky * \param Index the zero-based diagnostic number to retrieve. 407204643Srdivacky * 408204643Srdivacky * \returns the requested diagnostic. This diagnostic must be freed 409204643Srdivacky * via a call to \c clang_disposeDiagnostic(). 410204643Srdivacky */ 411204643SrdivackyCINDEX_LINKAGE CXDiagnostic clang_getDiagnostic(CXTranslationUnit Unit, 412204643Srdivacky unsigned Index); 413204643Srdivacky 414204643Srdivacky/** 415204643Srdivacky * \brief Destroy a diagnostic. 416204643Srdivacky */ 417204643SrdivackyCINDEX_LINKAGE void clang_disposeDiagnostic(CXDiagnostic Diagnostic); 418204643Srdivacky 419204643Srdivacky/** 420204643Srdivacky * \brief Options to control the display of diagnostics. 421204643Srdivacky * 422204643Srdivacky * The values in this enum are meant to be combined to customize the 423204643Srdivacky * behavior of \c clang_displayDiagnostic(). 424204643Srdivacky */ 425204643Srdivackyenum CXDiagnosticDisplayOptions { 426203955Srdivacky /** 427204643Srdivacky * \brief Display the source-location information where the 428204643Srdivacky * diagnostic was located. 429204643Srdivacky * 430204643Srdivacky * When set, diagnostics will be prefixed by the file, line, and 431204643Srdivacky * (optionally) column to which the diagnostic refers. For example, 432204643Srdivacky * 433204643Srdivacky * \code 434204643Srdivacky * test.c:28: warning: extra tokens at end of #endif directive 435204643Srdivacky * \endcode 436204643Srdivacky * 437204643Srdivacky * This option corresponds to the clang flag \c -fshow-source-location. 438203955Srdivacky */ 439204643Srdivacky CXDiagnostic_DisplaySourceLocation = 0x01, 440203955Srdivacky 441203955Srdivacky /** 442204643Srdivacky * \brief If displaying the source-location information of the 443204643Srdivacky * diagnostic, also include the column number. 444204643Srdivacky * 445204643Srdivacky * This option corresponds to the clang flag \c -fshow-column. 446203955Srdivacky */ 447204643Srdivacky CXDiagnostic_DisplayColumn = 0x02, 448203955Srdivacky 449203955Srdivacky /** 450204643Srdivacky * \brief If displaying the source-location information of the 451204643Srdivacky * diagnostic, also include information about source ranges in a 452204643Srdivacky * machine-parsable format. 453204643Srdivacky * 454205219Srdivacky * This option corresponds to the clang flag 455204643Srdivacky * \c -fdiagnostics-print-source-range-info. 456203955Srdivacky */ 457204643Srdivacky CXDiagnostic_DisplaySourceRanges = 0x04 458203955Srdivacky}; 459203955Srdivacky 460203955Srdivacky/** 461204643Srdivacky * \brief Format the given diagnostic in a manner that is suitable for display. 462204643Srdivacky * 463204643Srdivacky * This routine will format the given diagnostic to a string, rendering 464205219Srdivacky * the diagnostic according to the various options given. The 465205219Srdivacky * \c clang_defaultDiagnosticDisplayOptions() function returns the set of 466204643Srdivacky * options that most closely mimics the behavior of the clang compiler. 467204643Srdivacky * 468204643Srdivacky * \param Diagnostic The diagnostic to print. 469204643Srdivacky * 470205219Srdivacky * \param Options A set of options that control the diagnostic display, 471204643Srdivacky * created by combining \c CXDiagnosticDisplayOptions values. 472204643Srdivacky * 473204643Srdivacky * \returns A new string containing for formatted diagnostic. 474203955Srdivacky */ 475204643SrdivackyCINDEX_LINKAGE CXString clang_formatDiagnostic(CXDiagnostic Diagnostic, 476204643Srdivacky unsigned Options); 477203955Srdivacky 478203955Srdivacky/** 479204643Srdivacky * \brief Retrieve the set of display options most similar to the 480204643Srdivacky * default behavior of the clang compiler. 481203955Srdivacky * 482204643Srdivacky * \returns A set of display options suitable for use with \c 483204643Srdivacky * clang_displayDiagnostic(). 484203955Srdivacky */ 485204643SrdivackyCINDEX_LINKAGE unsigned clang_defaultDiagnosticDisplayOptions(void); 486203955Srdivacky 487203955Srdivacky/** 488204643Srdivacky * \brief Print a diagnostic to the given file. 489204643Srdivacky */ 490204643Srdivacky 491204643Srdivacky/** 492203955Srdivacky * \brief Determine the severity of the given diagnostic. 493203955Srdivacky */ 494205219SrdivackyCINDEX_LINKAGE enum CXDiagnosticSeverity 495203955Srdivackyclang_getDiagnosticSeverity(CXDiagnostic); 496203955Srdivacky 497203955Srdivacky/** 498203955Srdivacky * \brief Retrieve the source location of the given diagnostic. 499203955Srdivacky * 500203955Srdivacky * This location is where Clang would print the caret ('^') when 501203955Srdivacky * displaying the diagnostic on the command line. 502203955Srdivacky */ 503203955SrdivackyCINDEX_LINKAGE CXSourceLocation clang_getDiagnosticLocation(CXDiagnostic); 504203955Srdivacky 505203955Srdivacky/** 506203955Srdivacky * \brief Retrieve the text of the given diagnostic. 507203955Srdivacky */ 508203955SrdivackyCINDEX_LINKAGE CXString clang_getDiagnosticSpelling(CXDiagnostic); 509203955Srdivacky 510203955Srdivacky/** 511203955Srdivacky * \brief Determine the number of source ranges associated with the given 512203955Srdivacky * diagnostic. 513203955Srdivacky */ 514203955SrdivackyCINDEX_LINKAGE unsigned clang_getDiagnosticNumRanges(CXDiagnostic); 515205219Srdivacky 516203955Srdivacky/** 517203955Srdivacky * \brief Retrieve a source range associated with the diagnostic. 518203955Srdivacky * 519203955Srdivacky * A diagnostic's source ranges highlight important elements in the source 520203955Srdivacky * code. On the command line, Clang displays source ranges by 521205219Srdivacky * underlining them with '~' characters. 522203955Srdivacky * 523203955Srdivacky * \param Diagnostic the diagnostic whose range is being extracted. 524203955Srdivacky * 525205219Srdivacky * \param Range the zero-based index specifying which range to 526203955Srdivacky * 527203955Srdivacky * \returns the requested source range. 528203955Srdivacky */ 529205219SrdivackyCINDEX_LINKAGE CXSourceRange clang_getDiagnosticRange(CXDiagnostic Diagnostic, 530203955Srdivacky unsigned Range); 531203955Srdivacky 532203955Srdivacky/** 533203955Srdivacky * \brief Determine the number of fix-it hints associated with the 534203955Srdivacky * given diagnostic. 535203955Srdivacky */ 536203955SrdivackyCINDEX_LINKAGE unsigned clang_getDiagnosticNumFixIts(CXDiagnostic Diagnostic); 537203955Srdivacky 538203955Srdivacky/** 539204643Srdivacky * \brief Retrieve the replacement information for a given fix-it. 540203955Srdivacky * 541204643Srdivacky * Fix-its are described in terms of a source range whose contents 542204643Srdivacky * should be replaced by a string. This approach generalizes over 543204643Srdivacky * three kinds of operations: removal of source code (the range covers 544204643Srdivacky * the code to be removed and the replacement string is empty), 545204643Srdivacky * replacement of source code (the range covers the code to be 546204643Srdivacky * replaced and the replacement string provides the new code), and 547204643Srdivacky * insertion (both the start and end of the range point at the 548204643Srdivacky * insertion location, and the replacement string provides the text to 549204643Srdivacky * insert). 550203955Srdivacky * 551204643Srdivacky * \param Diagnostic The diagnostic whose fix-its are being queried. 552203955Srdivacky * 553204643Srdivacky * \param FixIt The zero-based index of the fix-it. 554203955Srdivacky * 555204643Srdivacky * \param ReplacementRange The source range whose contents will be 556204643Srdivacky * replaced with the returned replacement string. Note that source 557204643Srdivacky * ranges are half-open ranges [a, b), so the source code should be 558204643Srdivacky * replaced from a and up to (but not including) b. 559203955Srdivacky * 560204643Srdivacky * \returns A string containing text that should be replace the source 561204643Srdivacky * code indicated by the \c ReplacementRange. 562203955Srdivacky */ 563205219SrdivackyCINDEX_LINKAGE CXString clang_getDiagnosticFixIt(CXDiagnostic Diagnostic, 564204643Srdivacky unsigned FixIt, 565204643Srdivacky CXSourceRange *ReplacementRange); 566203955Srdivacky 567203955Srdivacky/** 568203955Srdivacky * @} 569203955Srdivacky */ 570203955Srdivacky 571203955Srdivacky/** 572203955Srdivacky * \defgroup CINDEX_TRANSLATION_UNIT Translation unit manipulation 573203955Srdivacky * 574203955Srdivacky * The routines in this group provide the ability to create and destroy 575203955Srdivacky * translation units from files, either by parsing the contents of the files or 576203955Srdivacky * by reading in a serialized representation of a translation unit. 577203955Srdivacky * 578203955Srdivacky * @{ 579203955Srdivacky */ 580205219Srdivacky 581203955Srdivacky/** 582203955Srdivacky * \brief Get the original translation unit source file name. 583203955Srdivacky */ 584203955SrdivackyCINDEX_LINKAGE CXString 585203955Srdivackyclang_getTranslationUnitSpelling(CXTranslationUnit CTUnit); 586203955Srdivacky 587203955Srdivacky/** 588203955Srdivacky * \brief Return the CXTranslationUnit for a given source file and the provided 589203955Srdivacky * command line arguments one would pass to the compiler. 590203955Srdivacky * 591203955Srdivacky * Note: The 'source_filename' argument is optional. If the caller provides a 592203955Srdivacky * NULL pointer, the name of the source file is expected to reside in the 593203955Srdivacky * specified command line arguments. 594203955Srdivacky * 595203955Srdivacky * Note: When encountered in 'clang_command_line_args', the following options 596203955Srdivacky * are ignored: 597203955Srdivacky * 598203955Srdivacky * '-c' 599203955Srdivacky * '-emit-ast' 600203955Srdivacky * '-fsyntax-only' 601203955Srdivacky * '-o <output file>' (both '-o' and '<output file>' are ignored) 602203955Srdivacky * 603203955Srdivacky * 604203955Srdivacky * \param source_filename - The name of the source file to load, or NULL if the 605203955Srdivacky * source file is included in clang_command_line_args. 606203955Srdivacky * 607203955Srdivacky * \param num_unsaved_files the number of unsaved file entries in \p 608203955Srdivacky * unsaved_files. 609203955Srdivacky * 610203955Srdivacky * \param unsaved_files the files that have not yet been saved to disk 611203955Srdivacky * but may be required for code completion, including the contents of 612207619Srdivacky * those files. The contents and name of these files (as specified by 613207619Srdivacky * CXUnsavedFile) are copied when necessary, so the client only needs to 614207619Srdivacky * guarantee their validity until the call to this function returns. 615203955Srdivacky * 616203955Srdivacky * \param diag_callback callback function that will receive any diagnostics 617203955Srdivacky * emitted while processing this source file. If NULL, diagnostics will be 618203955Srdivacky * suppressed. 619203955Srdivacky * 620203955Srdivacky * \param diag_client_data client data that will be passed to the diagnostic 621203955Srdivacky * callback function. 622203955Srdivacky */ 623203955SrdivackyCINDEX_LINKAGE CXTranslationUnit clang_createTranslationUnitFromSourceFile( 624203955Srdivacky CXIndex CIdx, 625203955Srdivacky const char *source_filename, 626203955Srdivacky int num_clang_command_line_args, 627203955Srdivacky const char **clang_command_line_args, 628203955Srdivacky unsigned num_unsaved_files, 629204643Srdivacky struct CXUnsavedFile *unsaved_files); 630205219Srdivacky 631203955Srdivacky/** 632203955Srdivacky * \brief Create a translation unit from an AST file (-emit-ast). 633203955Srdivacky */ 634205219SrdivackyCINDEX_LINKAGE CXTranslationUnit clang_createTranslationUnit(CXIndex, 635204643Srdivacky const char *ast_filename); 636203955Srdivacky 637203955Srdivacky/** 638203955Srdivacky * \brief Destroy the specified CXTranslationUnit object. 639203955Srdivacky */ 640203955SrdivackyCINDEX_LINKAGE void clang_disposeTranslationUnit(CXTranslationUnit); 641205219Srdivacky 642203955Srdivacky/** 643203955Srdivacky * @} 644203955Srdivacky */ 645205219Srdivacky 646203955Srdivacky/** 647202879Srdivacky * \brief Describes the kind of entity that a cursor refers to. 648202379Srdivacky */ 649202879Srdivackyenum CXCursorKind { 650202879Srdivacky /* Declarations */ 651203955Srdivacky /** 652202879Srdivacky * \brief A declaration whose specific kind is not exposed via this 653203955Srdivacky * interface. 654202879Srdivacky * 655202879Srdivacky * Unexposed declarations have the same operations as any other kind 656202879Srdivacky * of declaration; one can extract their location information, 657202879Srdivacky * spelling, find their definitions, etc. However, the specific kind 658202879Srdivacky * of the declaration is not reported. 659202879Srdivacky */ 660202879Srdivacky CXCursor_UnexposedDecl = 1, 661202879Srdivacky /** \brief A C or C++ struct. */ 662203955Srdivacky CXCursor_StructDecl = 2, 663202879Srdivacky /** \brief A C or C++ union. */ 664202879Srdivacky CXCursor_UnionDecl = 3, 665202879Srdivacky /** \brief A C++ class. */ 666202879Srdivacky CXCursor_ClassDecl = 4, 667202879Srdivacky /** \brief An enumeration. */ 668202879Srdivacky CXCursor_EnumDecl = 5, 669203955Srdivacky /** 670202879Srdivacky * \brief A field (in C) or non-static data member (in C++) in a 671202879Srdivacky * struct, union, or C++ class. 672202879Srdivacky */ 673202879Srdivacky CXCursor_FieldDecl = 6, 674202879Srdivacky /** \brief An enumerator constant. */ 675202879Srdivacky CXCursor_EnumConstantDecl = 7, 676202879Srdivacky /** \brief A function. */ 677202879Srdivacky CXCursor_FunctionDecl = 8, 678202879Srdivacky /** \brief A variable. */ 679202879Srdivacky CXCursor_VarDecl = 9, 680202879Srdivacky /** \brief A function or method parameter. */ 681202879Srdivacky CXCursor_ParmDecl = 10, 682202879Srdivacky /** \brief An Objective-C @interface. */ 683202879Srdivacky CXCursor_ObjCInterfaceDecl = 11, 684202879Srdivacky /** \brief An Objective-C @interface for a category. */ 685202879Srdivacky CXCursor_ObjCCategoryDecl = 12, 686202879Srdivacky /** \brief An Objective-C @protocol declaration. */ 687202879Srdivacky CXCursor_ObjCProtocolDecl = 13, 688202879Srdivacky /** \brief An Objective-C @property declaration. */ 689202879Srdivacky CXCursor_ObjCPropertyDecl = 14, 690202879Srdivacky /** \brief An Objective-C instance variable. */ 691202879Srdivacky CXCursor_ObjCIvarDecl = 15, 692202879Srdivacky /** \brief An Objective-C instance method. */ 693202879Srdivacky CXCursor_ObjCInstanceMethodDecl = 16, 694202879Srdivacky /** \brief An Objective-C class method. */ 695202879Srdivacky CXCursor_ObjCClassMethodDecl = 17, 696202879Srdivacky /** \brief An Objective-C @implementation. */ 697202879Srdivacky CXCursor_ObjCImplementationDecl = 18, 698202879Srdivacky /** \brief An Objective-C @implementation for a category. */ 699202879Srdivacky CXCursor_ObjCCategoryImplDecl = 19, 700202879Srdivacky /** \brief A typedef */ 701202879Srdivacky CXCursor_TypedefDecl = 20, 702207619Srdivacky /** \brief A C++ class method. */ 703207619Srdivacky CXCursor_CXXMethod = 21, 704208600Srdivacky /** \brief A C++ namespace. */ 705208600Srdivacky CXCursor_Namespace = 22, 706208600Srdivacky /** \brief A linkage specification, e.g. 'extern "C"'. */ 707208600Srdivacky CXCursor_LinkageSpec = 23, 708207619Srdivacky 709208600Srdivacky CXCursor_FirstDecl = CXCursor_UnexposedDecl, 710208600Srdivacky CXCursor_LastDecl = CXCursor_LinkageSpec, 711207619Srdivacky 712202879Srdivacky /* References */ 713202879Srdivacky CXCursor_FirstRef = 40, /* Decl references */ 714203955Srdivacky CXCursor_ObjCSuperClassRef = 40, 715202879Srdivacky CXCursor_ObjCProtocolRef = 41, 716202879Srdivacky CXCursor_ObjCClassRef = 42, 717202879Srdivacky /** 718202879Srdivacky * \brief A reference to a type declaration. 719202879Srdivacky * 720202879Srdivacky * A type reference occurs anywhere where a type is named but not 721202879Srdivacky * declared. For example, given: 722202879Srdivacky * 723202879Srdivacky * \code 724202879Srdivacky * typedef unsigned size_type; 725202879Srdivacky * size_type size; 726202879Srdivacky * \endcode 727202879Srdivacky * 728202879Srdivacky * The typedef is a declaration of size_type (CXCursor_TypedefDecl), 729202879Srdivacky * while the type of the variable "size" is referenced. The cursor 730202879Srdivacky * referenced by the type of size is the typedef for size_type. 731202879Srdivacky */ 732202879Srdivacky CXCursor_TypeRef = 43, 733202879Srdivacky CXCursor_LastRef = 43, 734203955Srdivacky 735202879Srdivacky /* Error conditions */ 736202879Srdivacky CXCursor_FirstInvalid = 70, 737202879Srdivacky CXCursor_InvalidFile = 70, 738202879Srdivacky CXCursor_NoDeclFound = 71, 739202879Srdivacky CXCursor_NotImplemented = 72, 740205408Srdivacky CXCursor_InvalidCode = 73, 741205408Srdivacky CXCursor_LastInvalid = CXCursor_InvalidCode, 742203955Srdivacky 743202879Srdivacky /* Expressions */ 744202879Srdivacky CXCursor_FirstExpr = 100, 745203955Srdivacky 746202879Srdivacky /** 747202879Srdivacky * \brief An expression whose specific kind is not exposed via this 748203955Srdivacky * interface. 749202879Srdivacky * 750202879Srdivacky * Unexposed expressions have the same operations as any other kind 751202879Srdivacky * of expression; one can extract their location information, 752202879Srdivacky * spelling, children, etc. However, the specific kind of the 753202879Srdivacky * expression is not reported. 754202879Srdivacky */ 755202879Srdivacky CXCursor_UnexposedExpr = 100, 756203955Srdivacky 757202879Srdivacky /** 758202879Srdivacky * \brief An expression that refers to some value declaration, such 759202879Srdivacky * as a function, varible, or enumerator. 760202879Srdivacky */ 761202879Srdivacky CXCursor_DeclRefExpr = 101, 762203955Srdivacky 763202879Srdivacky /** 764202879Srdivacky * \brief An expression that refers to a member of a struct, union, 765202879Srdivacky * class, Objective-C class, etc. 766202879Srdivacky */ 767202879Srdivacky CXCursor_MemberRefExpr = 102, 768203955Srdivacky 769202879Srdivacky /** \brief An expression that calls a function. */ 770202879Srdivacky CXCursor_CallExpr = 103, 771203955Srdivacky 772202879Srdivacky /** \brief An expression that sends a message to an Objective-C 773202879Srdivacky object or class. */ 774202879Srdivacky CXCursor_ObjCMessageExpr = 104, 775203955Srdivacky 776207619Srdivacky /** \brief An expression that represents a block literal. */ 777207619Srdivacky CXCursor_BlockExpr = 105, 778207619Srdivacky 779207619Srdivacky CXCursor_LastExpr = 105, 780207619Srdivacky 781202879Srdivacky /* Statements */ 782202879Srdivacky CXCursor_FirstStmt = 200, 783202879Srdivacky /** 784202879Srdivacky * \brief A statement whose specific kind is not exposed via this 785202879Srdivacky * interface. 786202879Srdivacky * 787202879Srdivacky * Unexposed statements have the same operations as any other kind of 788202879Srdivacky * statement; one can extract their location information, spelling, 789202879Srdivacky * children, etc. However, the specific kind of the statement is not 790202879Srdivacky * reported. 791202879Srdivacky */ 792202879Srdivacky CXCursor_UnexposedStmt = 200, 793202879Srdivacky CXCursor_LastStmt = 200, 794203955Srdivacky 795202879Srdivacky /** 796202879Srdivacky * \brief Cursor that represents the translation unit itself. 797202879Srdivacky * 798202879Srdivacky * The translation unit cursor exists primarily to act as the root 799202879Srdivacky * cursor for traversing the contents of a translation unit. 800202879Srdivacky */ 801204643Srdivacky CXCursor_TranslationUnit = 300, 802204643Srdivacky 803204643Srdivacky /* Attributes */ 804204643Srdivacky CXCursor_FirstAttr = 400, 805204643Srdivacky /** 806204643Srdivacky * \brief An attribute whose specific kind is not exposed via this 807204643Srdivacky * interface. 808204643Srdivacky */ 809204643Srdivacky CXCursor_UnexposedAttr = 400, 810204643Srdivacky 811204643Srdivacky CXCursor_IBActionAttr = 401, 812204643Srdivacky CXCursor_IBOutletAttr = 402, 813208600Srdivacky CXCursor_IBOutletCollectionAttr = 403, 814208600Srdivacky CXCursor_LastAttr = CXCursor_IBOutletCollectionAttr, 815205408Srdivacky 816205408Srdivacky /* Preprocessing */ 817205408Srdivacky CXCursor_PreprocessingDirective = 500, 818205408Srdivacky CXCursor_MacroDefinition = 501, 819205408Srdivacky CXCursor_MacroInstantiation = 502, 820205408Srdivacky CXCursor_FirstPreprocessing = CXCursor_PreprocessingDirective, 821205408Srdivacky CXCursor_LastPreprocessing = CXCursor_MacroInstantiation 822202879Srdivacky}; 823202379Srdivacky 824202879Srdivacky/** 825202879Srdivacky * \brief A cursor representing some element in the abstract syntax tree for 826202879Srdivacky * a translation unit. 827202879Srdivacky * 828203955Srdivacky * The cursor abstraction unifies the different kinds of entities in a 829202879Srdivacky * program--declaration, statements, expressions, references to declarations, 830202879Srdivacky * etc.--under a single "cursor" abstraction with a common set of operations. 831202879Srdivacky * Common operation for a cursor include: getting the physical location in 832202879Srdivacky * a source file where the cursor points, getting the name associated with a 833202879Srdivacky * cursor, and retrieving cursors for any child nodes of a particular cursor. 834202879Srdivacky * 835202879Srdivacky * Cursors can be produced in two specific ways. 836202879Srdivacky * clang_getTranslationUnitCursor() produces a cursor for a translation unit, 837202879Srdivacky * from which one can use clang_visitChildren() to explore the rest of the 838202879Srdivacky * translation unit. clang_getCursor() maps from a physical source location 839202879Srdivacky * to the entity that resides at that location, allowing one to map from the 840202879Srdivacky * source code into the AST. 841198092Srdivacky */ 842202879Srdivackytypedef struct { 843202879Srdivacky enum CXCursorKind kind; 844202879Srdivacky void *data[3]; 845203955Srdivacky} CXCursor; 846202879Srdivacky 847198398Srdivacky/** 848202879Srdivacky * \defgroup CINDEX_CURSOR_MANIP Cursor manipulations 849202879Srdivacky * 850202879Srdivacky * @{ 851198398Srdivacky */ 852203955Srdivacky 853202879Srdivacky/** 854202879Srdivacky * \brief Retrieve the NULL cursor, which represents no entity. 855202879Srdivacky */ 856199482SrdivackyCINDEX_LINKAGE CXCursor clang_getNullCursor(void); 857203955Srdivacky 858202879Srdivacky/** 859202879Srdivacky * \brief Retrieve the cursor that represents the given translation unit. 860202879Srdivacky * 861202879Srdivacky * The translation unit cursor can be used to start traversing the 862202879Srdivacky * various declarations within the given translation unit. 863202879Srdivacky */ 864202879SrdivackyCINDEX_LINKAGE CXCursor clang_getTranslationUnitCursor(CXTranslationUnit); 865198092Srdivacky 866202879Srdivacky/** 867202879Srdivacky * \brief Determine whether two cursors are equivalent. 868202879Srdivacky */ 869202879SrdivackyCINDEX_LINKAGE unsigned clang_equalCursors(CXCursor, CXCursor); 870203955Srdivacky 871202879Srdivacky/** 872202879Srdivacky * \brief Retrieve the kind of the given cursor. 873202879Srdivacky */ 874198893SrdivackyCINDEX_LINKAGE enum CXCursorKind clang_getCursorKind(CXCursor); 875202879Srdivacky 876202879Srdivacky/** 877202879Srdivacky * \brief Determine whether the given cursor kind represents a declaration. 878202879Srdivacky */ 879198893SrdivackyCINDEX_LINKAGE unsigned clang_isDeclaration(enum CXCursorKind); 880202879Srdivacky 881202879Srdivacky/** 882202879Srdivacky * \brief Determine whether the given cursor kind represents a simple 883202879Srdivacky * reference. 884202879Srdivacky * 885202879Srdivacky * Note that other kinds of cursors (such as expressions) can also refer to 886202879Srdivacky * other cursors. Use clang_getCursorReferenced() to determine whether a 887202879Srdivacky * particular cursor refers to another entity. 888202879Srdivacky */ 889198893SrdivackyCINDEX_LINKAGE unsigned clang_isReference(enum CXCursorKind); 890202879Srdivacky 891202879Srdivacky/** 892202879Srdivacky * \brief Determine whether the given cursor kind represents an expression. 893202879Srdivacky */ 894202879SrdivackyCINDEX_LINKAGE unsigned clang_isExpression(enum CXCursorKind); 895202879Srdivacky 896202879Srdivacky/** 897202879Srdivacky * \brief Determine whether the given cursor kind represents a statement. 898202879Srdivacky */ 899202879SrdivackyCINDEX_LINKAGE unsigned clang_isStatement(enum CXCursorKind); 900202879Srdivacky 901202879Srdivacky/** 902203955Srdivacky * \brief Determine whether the given cursor kind represents an invalid 903202879Srdivacky * cursor. 904203955Srdivacky */ 905198893SrdivackyCINDEX_LINKAGE unsigned clang_isInvalid(enum CXCursorKind); 906198398Srdivacky 907202879Srdivacky/** 908203955Srdivacky * \brief Determine whether the given cursor kind represents a translation 909203955Srdivacky * unit. 910202879Srdivacky */ 911202879SrdivackyCINDEX_LINKAGE unsigned clang_isTranslationUnit(enum CXCursorKind); 912203955Srdivacky 913204962Srdivacky/*** 914205408Srdivacky * \brief Determine whether the given cursor represents a preprocessing 915205408Srdivacky * element, such as a preprocessor directive or macro instantiation. 916205408Srdivacky */ 917205408SrdivackyCINDEX_LINKAGE unsigned clang_isPreprocessing(enum CXCursorKind); 918205408Srdivacky 919205408Srdivacky/*** 920204962Srdivacky * \brief Determine whether the given cursor represents a currently 921204962Srdivacky * unexposed piece of the AST (e.g., CXCursor_UnexposedStmt). 922204962Srdivacky */ 923204962SrdivackyCINDEX_LINKAGE unsigned clang_isUnexposed(enum CXCursorKind); 924204962Srdivacky 925202879Srdivacky/** 926204643Srdivacky * \brief Describe the linkage of the entity referred to by a cursor. 927204643Srdivacky */ 928204643Srdivackyenum CXLinkageKind { 929204643Srdivacky /** \brief This value indicates that no linkage information is available 930204643Srdivacky * for a provided CXCursor. */ 931204643Srdivacky CXLinkage_Invalid, 932204643Srdivacky /** 933204643Srdivacky * \brief This is the linkage for variables, parameters, and so on that 934204643Srdivacky * have automatic storage. This covers normal (non-extern) local variables. 935204643Srdivacky */ 936204643Srdivacky CXLinkage_NoLinkage, 937204643Srdivacky /** \brief This is the linkage for static variables and static functions. */ 938204643Srdivacky CXLinkage_Internal, 939204643Srdivacky /** \brief This is the linkage for entities with external linkage that live 940204643Srdivacky * in C++ anonymous namespaces.*/ 941204643Srdivacky CXLinkage_UniqueExternal, 942204643Srdivacky /** \brief This is the linkage for entities with true, external linkage. */ 943204643Srdivacky CXLinkage_External 944204643Srdivacky}; 945204643Srdivacky 946204643Srdivacky/** 947207619Srdivacky * \brief Determine the linkage of the entity referred to by a given cursor. 948204643Srdivacky */ 949204643SrdivackyCINDEX_LINKAGE enum CXLinkageKind clang_getCursorLinkage(CXCursor cursor); 950204643Srdivacky 951204643Srdivacky/** 952207619Srdivacky * \brief Describe the "language" of the entity referred to by a cursor. 953207619Srdivacky */ 954207619SrdivackyCINDEX_LINKAGE enum CXLanguageKind { 955207619Srdivacky CXLanguage_Invalid = 0, 956207619Srdivacky CXLanguage_C, 957207619Srdivacky CXLanguage_ObjC, 958207619Srdivacky CXLanguage_CPlusPlus 959207619Srdivacky}; 960207619Srdivacky 961207619Srdivacky/** 962207619Srdivacky * \brief Determine the "language" of the entity referred to by a given cursor. 963207619Srdivacky */ 964207619SrdivackyCINDEX_LINKAGE enum CXLanguageKind clang_getCursorLanguage(CXCursor cursor); 965207619Srdivacky 966207619Srdivacky/** 967202879Srdivacky * @} 968202879Srdivacky */ 969203955Srdivacky 970202879Srdivacky/** 971202879Srdivacky * \defgroup CINDEX_CURSOR_SOURCE Mapping between cursors and source code 972202879Srdivacky * 973202879Srdivacky * Cursors represent a location within the Abstract Syntax Tree (AST). These 974202879Srdivacky * routines help map between cursors and the physical locations where the 975202879Srdivacky * described entities occur in the source code. The mapping is provided in 976202879Srdivacky * both directions, so one can map from source code to the AST and back. 977202879Srdivacky * 978202879Srdivacky * @{ 979202879Srdivacky */ 980203955Srdivacky 981202879Srdivacky/** 982202879Srdivacky * \brief Map a source location to the cursor that describes the entity at that 983202879Srdivacky * location in the source code. 984202879Srdivacky * 985202879Srdivacky * clang_getCursor() maps an arbitrary source location within a translation 986202879Srdivacky * unit down to the most specific cursor that describes the entity at that 987203955Srdivacky * location. For example, given an expression \c x + y, invoking 988202879Srdivacky * clang_getCursor() with a source location pointing to "x" will return the 989203955Srdivacky * cursor for "x"; similarly for "y". If the cursor points anywhere between 990202879Srdivacky * "x" or "y" (e.g., on the + or the whitespace around it), clang_getCursor() 991202879Srdivacky * will return a cursor referring to the "+" expression. 992202879Srdivacky * 993202879Srdivacky * \returns a cursor representing the entity at the given source location, or 994202879Srdivacky * a NULL cursor if no such entity can be found. 995202879Srdivacky */ 996202879SrdivackyCINDEX_LINKAGE CXCursor clang_getCursor(CXTranslationUnit, CXSourceLocation); 997203955Srdivacky 998202879Srdivacky/** 999202879Srdivacky * \brief Retrieve the physical location of the source constructor referenced 1000202879Srdivacky * by the given cursor. 1001202879Srdivacky * 1002202879Srdivacky * The location of a declaration is typically the location of the name of that 1003203955Srdivacky * declaration, where the name of that declaration would occur if it is 1004203955Srdivacky * unnamed, or some keyword that introduces that particular declaration. 1005203955Srdivacky * The location of a reference is where that reference occurs within the 1006202879Srdivacky * source code. 1007202879Srdivacky */ 1008202879SrdivackyCINDEX_LINKAGE CXSourceLocation clang_getCursorLocation(CXCursor); 1009199482Srdivacky 1010202879Srdivacky/** 1011202879Srdivacky * \brief Retrieve the physical extent of the source construct referenced by 1012202879Srdivacky * the given cursor. 1013202879Srdivacky * 1014202879Srdivacky * The extent of a cursor starts with the file/line/column pointing at the 1015202879Srdivacky * first character within the source construct that the cursor refers to and 1016203955Srdivacky * ends with the last character withinin that source construct. For a 1017202879Srdivacky * declaration, the extent covers the declaration itself. For a reference, 1018202879Srdivacky * the extent covers the location of the reference (e.g., where the referenced 1019202879Srdivacky * entity was actually used). 1020202879Srdivacky */ 1021202879SrdivackyCINDEX_LINKAGE CXSourceRange clang_getCursorExtent(CXCursor); 1022202879Srdivacky 1023202879Srdivacky/** 1024202879Srdivacky * @} 1025202879Srdivacky */ 1026203955Srdivacky 1027202879Srdivacky/** 1028208600Srdivacky * \defgroup CINDEX_TYPES Type information for CXCursors 1029208600Srdivacky * 1030208600Srdivacky * @{ 1031208600Srdivacky */ 1032208600Srdivacky 1033208600Srdivacky/** 1034208600Srdivacky * \brief Describes the kind of type 1035208600Srdivacky */ 1036208600Srdivackyenum CXTypeKind { 1037208600Srdivacky /** 1038208600Srdivacky * \brief Reprents an invalid type (e.g., where no type is available). 1039208600Srdivacky */ 1040208600Srdivacky CXType_Invalid = 0, 1041208600Srdivacky 1042208600Srdivacky /** 1043208600Srdivacky * \brief A type whose specific kind is not exposed via this 1044208600Srdivacky * interface. 1045208600Srdivacky */ 1046208600Srdivacky CXType_Unexposed = 1, 1047208600Srdivacky 1048208600Srdivacky /* Builtin types */ 1049208600Srdivacky CXType_Void = 2, 1050208600Srdivacky CXType_Bool = 3, 1051208600Srdivacky CXType_Char_U = 4, 1052208600Srdivacky CXType_UChar = 5, 1053208600Srdivacky CXType_Char16 = 6, 1054208600Srdivacky CXType_Char32 = 7, 1055208600Srdivacky CXType_UShort = 8, 1056208600Srdivacky CXType_UInt = 9, 1057208600Srdivacky CXType_ULong = 10, 1058208600Srdivacky CXType_ULongLong = 11, 1059208600Srdivacky CXType_UInt128 = 12, 1060208600Srdivacky CXType_Char_S = 13, 1061208600Srdivacky CXType_SChar = 14, 1062208600Srdivacky CXType_WChar = 15, 1063208600Srdivacky CXType_Short = 16, 1064208600Srdivacky CXType_Int = 17, 1065208600Srdivacky CXType_Long = 18, 1066208600Srdivacky CXType_LongLong = 19, 1067208600Srdivacky CXType_Int128 = 20, 1068208600Srdivacky CXType_Float = 21, 1069208600Srdivacky CXType_Double = 22, 1070208600Srdivacky CXType_LongDouble = 23, 1071208600Srdivacky CXType_NullPtr = 24, 1072208600Srdivacky CXType_Overload = 25, 1073208600Srdivacky CXType_Dependent = 26, 1074208600Srdivacky CXType_ObjCId = 27, 1075208600Srdivacky CXType_ObjCClass = 28, 1076208600Srdivacky CXType_ObjCSel = 29, 1077208600Srdivacky CXType_FirstBuiltin = CXType_Void, 1078208600Srdivacky CXType_LastBuiltin = CXType_ObjCSel, 1079208600Srdivacky 1080208600Srdivacky CXType_Complex = 100, 1081208600Srdivacky CXType_Pointer = 101, 1082208600Srdivacky CXType_BlockPointer = 102, 1083208600Srdivacky CXType_LValueReference = 103, 1084208600Srdivacky CXType_RValueReference = 104, 1085208600Srdivacky CXType_Record = 105, 1086208600Srdivacky CXType_Enum = 106, 1087208600Srdivacky CXType_Typedef = 107, 1088208600Srdivacky CXType_ObjCInterface = 108, 1089210299Sed CXType_ObjCObjectPointer = 109, 1090210299Sed CXType_FunctionNoProto = 110, 1091210299Sed CXType_FunctionProto = 111 1092208600Srdivacky}; 1093208600Srdivacky 1094208600Srdivacky/** 1095208600Srdivacky * \brief The type of an element in the abstract syntax tree. 1096208600Srdivacky * 1097208600Srdivacky */ 1098208600Srdivackytypedef struct { 1099208600Srdivacky enum CXTypeKind kind; 1100208600Srdivacky void *data[2]; 1101208600Srdivacky} CXType; 1102208600Srdivacky 1103208600Srdivacky/** 1104208600Srdivacky * \brief Retrieve the type of a CXCursor (if any). 1105208600Srdivacky */ 1106208600SrdivackyCINDEX_LINKAGE CXType clang_getCursorType(CXCursor C); 1107208600Srdivacky 1108208600Srdivacky/** 1109208600Srdivacky * \determine Determine whether two CXTypes represent the same type. 1110208600Srdivacky * 1111208600Srdivacky * \returns non-zero if the CXTypes represent the same type and 1112208600Srdivacky zero otherwise. 1113208600Srdivacky */ 1114208600SrdivackyCINDEX_LINKAGE unsigned clang_equalTypes(CXType A, CXType B); 1115208600Srdivacky 1116208600Srdivacky/** 1117208600Srdivacky * \brief Return the canonical type for a CXType. 1118208600Srdivacky * 1119208600Srdivacky * Clang's type system explicitly models typedefs and all the ways 1120208600Srdivacky * a specific type can be represented. The canonical type is the underlying 1121208600Srdivacky * type with all the "sugar" removed. For example, if 'T' is a typedef 1122208600Srdivacky * for 'int', the canonical type for 'T' would be 'int'. 1123208600Srdivacky */ 1124208600SrdivackyCINDEX_LINKAGE CXType clang_getCanonicalType(CXType T); 1125208600Srdivacky 1126208600Srdivacky/** 1127208600Srdivacky * \brief For pointer types, returns the type of the pointee. 1128208600Srdivacky * 1129208600Srdivacky */ 1130208600SrdivackyCINDEX_LINKAGE CXType clang_getPointeeType(CXType T); 1131208600Srdivacky 1132208600Srdivacky/** 1133208600Srdivacky * \brief Return the cursor for the declaration of the given type. 1134208600Srdivacky */ 1135208600SrdivackyCINDEX_LINKAGE CXCursor clang_getTypeDeclaration(CXType T); 1136208600Srdivacky 1137208600Srdivacky 1138208600Srdivacky/** 1139208600Srdivacky * \brief Retrieve the spelling of a given CXTypeKind. 1140208600Srdivacky */ 1141208600SrdivackyCINDEX_LINKAGE CXString clang_getTypeKindSpelling(enum CXTypeKind K); 1142208600Srdivacky 1143208600Srdivacky/** 1144210299Sed * \brief Retrieve the result type associated with a function type. 1145210299Sed */ 1146210299SedCINDEX_LINKAGE CXType clang_getResultType(CXType T); 1147210299Sed 1148210299Sed/** 1149210299Sed * \brief Retrieve the result type associated with a given cursor. This only 1150210299Sed * returns a valid type of the cursor refers to a function or method. 1151210299Sed */ 1152210299SedCINDEX_LINKAGE CXType clang_getCursorResultType(CXCursor C); 1153210299Sed 1154210299Sed/** 1155208600Srdivacky * @} 1156208600Srdivacky */ 1157208600Srdivacky 1158208600Srdivacky/** 1159202879Srdivacky * \defgroup CINDEX_CURSOR_TRAVERSAL Traversing the AST with cursors 1160202879Srdivacky * 1161202879Srdivacky * These routines provide the ability to traverse the abstract syntax tree 1162202879Srdivacky * using cursors. 1163202879Srdivacky * 1164202879Srdivacky * @{ 1165202879Srdivacky */ 1166203955Srdivacky 1167202879Srdivacky/** 1168202879Srdivacky * \brief Describes how the traversal of the children of a particular 1169202879Srdivacky * cursor should proceed after visiting a particular child cursor. 1170202879Srdivacky * 1171202879Srdivacky * A value of this enumeration type should be returned by each 1172202879Srdivacky * \c CXCursorVisitor to indicate how clang_visitChildren() proceed. 1173202879Srdivacky */ 1174202879Srdivackyenum CXChildVisitResult { 1175202879Srdivacky /** 1176203955Srdivacky * \brief Terminates the cursor traversal. 1177202879Srdivacky */ 1178202879Srdivacky CXChildVisit_Break, 1179203955Srdivacky /** 1180202879Srdivacky * \brief Continues the cursor traversal with the next sibling of 1181202879Srdivacky * the cursor just visited, without visiting its children. 1182202879Srdivacky */ 1183202879Srdivacky CXChildVisit_Continue, 1184202879Srdivacky /** 1185202879Srdivacky * \brief Recursively traverse the children of this cursor, using 1186202879Srdivacky * the same visitor and client data. 1187202879Srdivacky */ 1188202879Srdivacky CXChildVisit_Recurse 1189202879Srdivacky}; 1190202879Srdivacky 1191202879Srdivacky/** 1192202879Srdivacky * \brief Visitor invoked for each cursor found by a traversal. 1193202879Srdivacky * 1194202879Srdivacky * This visitor function will be invoked for each cursor found by 1195202879Srdivacky * clang_visitCursorChildren(). Its first argument is the cursor being 1196202879Srdivacky * visited, its second argument is the parent visitor for that cursor, 1197202879Srdivacky * and its third argument is the client data provided to 1198202879Srdivacky * clang_visitCursorChildren(). 1199202879Srdivacky * 1200202879Srdivacky * The visitor should return one of the \c CXChildVisitResult values 1201202879Srdivacky * to direct clang_visitCursorChildren(). 1202202879Srdivacky */ 1203203955Srdivackytypedef enum CXChildVisitResult (*CXCursorVisitor)(CXCursor cursor, 1204203955Srdivacky CXCursor parent, 1205202879Srdivacky CXClientData client_data); 1206202879Srdivacky 1207202879Srdivacky/** 1208202879Srdivacky * \brief Visit the children of a particular cursor. 1209202879Srdivacky * 1210202879Srdivacky * This function visits all the direct children of the given cursor, 1211202879Srdivacky * invoking the given \p visitor function with the cursors of each 1212202879Srdivacky * visited child. The traversal may be recursive, if the visitor returns 1213202879Srdivacky * \c CXChildVisit_Recurse. The traversal may also be ended prematurely, if 1214202879Srdivacky * the visitor returns \c CXChildVisit_Break. 1215202879Srdivacky * 1216202879Srdivacky * \param parent the cursor whose child may be visited. All kinds of 1217203955Srdivacky * cursors can be visited, including invalid cursors (which, by 1218202879Srdivacky * definition, have no children). 1219202879Srdivacky * 1220202879Srdivacky * \param visitor the visitor function that will be invoked for each 1221202879Srdivacky * child of \p parent. 1222202879Srdivacky * 1223202879Srdivacky * \param client_data pointer data supplied by the client, which will 1224202879Srdivacky * be passed to the visitor each time it is invoked. 1225202879Srdivacky * 1226202879Srdivacky * \returns a non-zero value if the traversal was terminated 1227202879Srdivacky * prematurely by the visitor returning \c CXChildVisit_Break. 1228202879Srdivacky */ 1229203955SrdivackyCINDEX_LINKAGE unsigned clang_visitChildren(CXCursor parent, 1230202879Srdivacky CXCursorVisitor visitor, 1231202879Srdivacky CXClientData client_data); 1232203955Srdivacky 1233202879Srdivacky/** 1234202879Srdivacky * @} 1235202879Srdivacky */ 1236203955Srdivacky 1237202879Srdivacky/** 1238202879Srdivacky * \defgroup CINDEX_CURSOR_XREF Cross-referencing in the AST 1239202879Srdivacky * 1240203955Srdivacky * These routines provide the ability to determine references within and 1241202879Srdivacky * across translation units, by providing the names of the entities referenced 1242202879Srdivacky * by cursors, follow reference cursors to the declarations they reference, 1243202879Srdivacky * and associate declarations with their definitions. 1244202879Srdivacky * 1245202879Srdivacky * @{ 1246202879Srdivacky */ 1247203955Srdivacky 1248202879Srdivacky/** 1249202879Srdivacky * \brief Retrieve a Unified Symbol Resolution (USR) for the entity referenced 1250202879Srdivacky * by the given cursor. 1251202879Srdivacky * 1252202879Srdivacky * A Unified Symbol Resolution (USR) is a string that identifies a particular 1253202879Srdivacky * entity (function, class, variable, etc.) within a program. USRs can be 1254202879Srdivacky * compared across translation units to determine, e.g., when references in 1255202879Srdivacky * one translation refer to an entity defined in another translation unit. 1256202879Srdivacky */ 1257202879SrdivackyCINDEX_LINKAGE CXString clang_getCursorUSR(CXCursor); 1258202879Srdivacky 1259202879Srdivacky/** 1260205219Srdivacky * \brief Construct a USR for a specified Objective-C class. 1261205219Srdivacky */ 1262205219SrdivackyCINDEX_LINKAGE CXString clang_constructUSR_ObjCClass(const char *class_name); 1263205219Srdivacky 1264205219Srdivacky/** 1265205219Srdivacky * \brief Construct a USR for a specified Objective-C category. 1266205219Srdivacky */ 1267205219SrdivackyCINDEX_LINKAGE CXString 1268205219Srdivacky clang_constructUSR_ObjCCategory(const char *class_name, 1269205219Srdivacky const char *category_name); 1270205219Srdivacky 1271205219Srdivacky/** 1272205219Srdivacky * \brief Construct a USR for a specified Objective-C protocol. 1273205219Srdivacky */ 1274205219SrdivackyCINDEX_LINKAGE CXString 1275205219Srdivacky clang_constructUSR_ObjCProtocol(const char *protocol_name); 1276205219Srdivacky 1277205219Srdivacky 1278205219Srdivacky/** 1279205219Srdivacky * \brief Construct a USR for a specified Objective-C instance variable and 1280205219Srdivacky * the USR for its containing class. 1281205219Srdivacky */ 1282205219SrdivackyCINDEX_LINKAGE CXString clang_constructUSR_ObjCIvar(const char *name, 1283205219Srdivacky CXString classUSR); 1284205219Srdivacky 1285205219Srdivacky/** 1286205219Srdivacky * \brief Construct a USR for a specified Objective-C method and 1287205219Srdivacky * the USR for its containing class. 1288205219Srdivacky */ 1289205219SrdivackyCINDEX_LINKAGE CXString clang_constructUSR_ObjCMethod(const char *name, 1290205219Srdivacky unsigned isInstanceMethod, 1291205219Srdivacky CXString classUSR); 1292205219Srdivacky 1293205219Srdivacky/** 1294205219Srdivacky * \brief Construct a USR for a specified Objective-C property and the USR 1295205219Srdivacky * for its containing class. 1296205219Srdivacky */ 1297205219SrdivackyCINDEX_LINKAGE CXString clang_constructUSR_ObjCProperty(const char *property, 1298205219Srdivacky CXString classUSR); 1299205219Srdivacky 1300205219Srdivacky/** 1301202879Srdivacky * \brief Retrieve a name for the entity referenced by this cursor. 1302202879Srdivacky */ 1303199482SrdivackyCINDEX_LINKAGE CXString clang_getCursorSpelling(CXCursor); 1304198398Srdivacky 1305202879Srdivacky/** \brief For a cursor that is a reference, retrieve a cursor representing the 1306202879Srdivacky * entity that it references. 1307202879Srdivacky * 1308202879Srdivacky * Reference cursors refer to other entities in the AST. For example, an 1309202879Srdivacky * Objective-C superclass reference cursor refers to an Objective-C class. 1310203955Srdivacky * This function produces the cursor for the Objective-C class from the 1311202879Srdivacky * cursor for the superclass reference. If the input cursor is a declaration or 1312202879Srdivacky * definition, it returns that declaration or definition unchanged. 1313203955Srdivacky * Otherwise, returns the NULL cursor. 1314202879Srdivacky */ 1315202879SrdivackyCINDEX_LINKAGE CXCursor clang_getCursorReferenced(CXCursor); 1316202879Srdivacky 1317203955Srdivacky/** 1318202879Srdivacky * \brief For a cursor that is either a reference to or a declaration 1319202879Srdivacky * of some entity, retrieve a cursor that describes the definition of 1320202879Srdivacky * that entity. 1321202879Srdivacky * 1322202879Srdivacky * Some entities can be declared multiple times within a translation 1323202879Srdivacky * unit, but only one of those declarations can also be a 1324202879Srdivacky * definition. For example, given: 1325202879Srdivacky * 1326202879Srdivacky * \code 1327202879Srdivacky * int f(int, int); 1328202879Srdivacky * int g(int x, int y) { return f(x, y); } 1329202879Srdivacky * int f(int a, int b) { return a + b; } 1330202879Srdivacky * int f(int, int); 1331202879Srdivacky * \endcode 1332202879Srdivacky * 1333202879Srdivacky * there are three declarations of the function "f", but only the 1334202879Srdivacky * second one is a definition. The clang_getCursorDefinition() 1335202879Srdivacky * function will take any cursor pointing to a declaration of "f" 1336202879Srdivacky * (the first or fourth lines of the example) or a cursor referenced 1337202879Srdivacky * that uses "f" (the call to "f' inside "g") and will return a 1338202879Srdivacky * declaration cursor pointing to the definition (the second "f" 1339202879Srdivacky * declaration). 1340202879Srdivacky * 1341202879Srdivacky * If given a cursor for which there is no corresponding definition, 1342202879Srdivacky * e.g., because there is no definition of that entity within this 1343202879Srdivacky * translation unit, returns a NULL cursor. 1344202879Srdivacky */ 1345202879SrdivackyCINDEX_LINKAGE CXCursor clang_getCursorDefinition(CXCursor); 1346202879Srdivacky 1347203955Srdivacky/** 1348202879Srdivacky * \brief Determine whether the declaration pointed to by this cursor 1349202879Srdivacky * is also a definition of that entity. 1350202879Srdivacky */ 1351202879SrdivackyCINDEX_LINKAGE unsigned clang_isCursorDefinition(CXCursor); 1352202879Srdivacky 1353202879Srdivacky/** 1354202879Srdivacky * @} 1355202879Srdivacky */ 1356203955Srdivacky 1357203955Srdivacky/** 1358208600Srdivacky * \defgroup CINDEX_CPP C++ AST introspection 1359208600Srdivacky * 1360208600Srdivacky * The routines in this group provide access information in the ASTs specific 1361208600Srdivacky * to C++ language features. 1362208600Srdivacky * 1363208600Srdivacky * @{ 1364208600Srdivacky */ 1365208600Srdivacky 1366208600Srdivacky/** 1367208600Srdivacky * \brief Determine if a C++ member function is declared 'static'. 1368208600Srdivacky */ 1369208600SrdivackyCINDEX_LINKAGE unsigned clang_CXXMethod_isStatic(CXCursor C); 1370208600Srdivacky 1371208600Srdivacky/** 1372208600Srdivacky * @} 1373208600Srdivacky */ 1374208600Srdivacky 1375208600Srdivacky/** 1376203955Srdivacky * \defgroup CINDEX_LEX Token extraction and manipulation 1377203955Srdivacky * 1378203955Srdivacky * The routines in this group provide access to the tokens within a 1379203955Srdivacky * translation unit, along with a semantic mapping of those tokens to 1380203955Srdivacky * their corresponding cursors. 1381203955Srdivacky * 1382203955Srdivacky * @{ 1383203955Srdivacky */ 1384203955Srdivacky 1385203955Srdivacky/** 1386203955Srdivacky * \brief Describes a kind of token. 1387203955Srdivacky */ 1388203955Srdivackytypedef enum CXTokenKind { 1389203955Srdivacky /** 1390203955Srdivacky * \brief A token that contains some kind of punctuation. 1391203955Srdivacky */ 1392203955Srdivacky CXToken_Punctuation, 1393205219Srdivacky 1394203955Srdivacky /** 1395203955Srdivacky * \brief A language keyword. 1396203955Srdivacky */ 1397203955Srdivacky CXToken_Keyword, 1398205219Srdivacky 1399203955Srdivacky /** 1400203955Srdivacky * \brief An identifier (that is not a keyword). 1401203955Srdivacky */ 1402203955Srdivacky CXToken_Identifier, 1403205219Srdivacky 1404203955Srdivacky /** 1405203955Srdivacky * \brief A numeric, string, or character literal. 1406203955Srdivacky */ 1407203955Srdivacky CXToken_Literal, 1408205219Srdivacky 1409203955Srdivacky /** 1410203955Srdivacky * \brief A comment. 1411203955Srdivacky */ 1412203955Srdivacky CXToken_Comment 1413203955Srdivacky} CXTokenKind; 1414203955Srdivacky 1415202879Srdivacky/** 1416203955Srdivacky * \brief Describes a single preprocessing token. 1417203955Srdivacky */ 1418203955Srdivackytypedef struct { 1419203955Srdivacky unsigned int_data[4]; 1420203955Srdivacky void *ptr_data; 1421203955Srdivacky} CXToken; 1422203955Srdivacky 1423203955Srdivacky/** 1424203955Srdivacky * \brief Determine the kind of the given token. 1425203955Srdivacky */ 1426203955SrdivackyCINDEX_LINKAGE CXTokenKind clang_getTokenKind(CXToken); 1427205219Srdivacky 1428203955Srdivacky/** 1429203955Srdivacky * \brief Determine the spelling of the given token. 1430203955Srdivacky * 1431203955Srdivacky * The spelling of a token is the textual representation of that token, e.g., 1432203955Srdivacky * the text of an identifier or keyword. 1433203955Srdivacky */ 1434203955SrdivackyCINDEX_LINKAGE CXString clang_getTokenSpelling(CXTranslationUnit, CXToken); 1435205219Srdivacky 1436203955Srdivacky/** 1437203955Srdivacky * \brief Retrieve the source location of the given token. 1438203955Srdivacky */ 1439205219SrdivackyCINDEX_LINKAGE CXSourceLocation clang_getTokenLocation(CXTranslationUnit, 1440203955Srdivacky CXToken); 1441205219Srdivacky 1442203955Srdivacky/** 1443203955Srdivacky * \brief Retrieve a source range that covers the given token. 1444203955Srdivacky */ 1445203955SrdivackyCINDEX_LINKAGE CXSourceRange clang_getTokenExtent(CXTranslationUnit, CXToken); 1446203955Srdivacky 1447203955Srdivacky/** 1448203955Srdivacky * \brief Tokenize the source code described by the given range into raw 1449203955Srdivacky * lexical tokens. 1450203955Srdivacky * 1451203955Srdivacky * \param TU the translation unit whose text is being tokenized. 1452203955Srdivacky * 1453203955Srdivacky * \param Range the source range in which text should be tokenized. All of the 1454203955Srdivacky * tokens produced by tokenization will fall within this source range, 1455203955Srdivacky * 1456203955Srdivacky * \param Tokens this pointer will be set to point to the array of tokens 1457203955Srdivacky * that occur within the given source range. The returned pointer must be 1458203955Srdivacky * freed with clang_disposeTokens() before the translation unit is destroyed. 1459203955Srdivacky * 1460203955Srdivacky * \param NumTokens will be set to the number of tokens in the \c *Tokens 1461203955Srdivacky * array. 1462203955Srdivacky * 1463203955Srdivacky */ 1464203955SrdivackyCINDEX_LINKAGE void clang_tokenize(CXTranslationUnit TU, CXSourceRange Range, 1465203955Srdivacky CXToken **Tokens, unsigned *NumTokens); 1466205219Srdivacky 1467203955Srdivacky/** 1468203955Srdivacky * \brief Annotate the given set of tokens by providing cursors for each token 1469203955Srdivacky * that can be mapped to a specific entity within the abstract syntax tree. 1470203955Srdivacky * 1471203955Srdivacky * This token-annotation routine is equivalent to invoking 1472203955Srdivacky * clang_getCursor() for the source locations of each of the 1473203955Srdivacky * tokens. The cursors provided are filtered, so that only those 1474203955Srdivacky * cursors that have a direct correspondence to the token are 1475203955Srdivacky * accepted. For example, given a function call \c f(x), 1476203955Srdivacky * clang_getCursor() would provide the following cursors: 1477203955Srdivacky * 1478203955Srdivacky * * when the cursor is over the 'f', a DeclRefExpr cursor referring to 'f'. 1479203955Srdivacky * * when the cursor is over the '(' or the ')', a CallExpr referring to 'f'. 1480203955Srdivacky * * when the cursor is over the 'x', a DeclRefExpr cursor referring to 'x'. 1481203955Srdivacky * 1482203955Srdivacky * Only the first and last of these cursors will occur within the 1483203955Srdivacky * annotate, since the tokens "f" and "x' directly refer to a function 1484203955Srdivacky * and a variable, respectively, but the parentheses are just a small 1485203955Srdivacky * part of the full syntax of the function call expression, which is 1486203955Srdivacky * not provided as an annotation. 1487203955Srdivacky * 1488203955Srdivacky * \param TU the translation unit that owns the given tokens. 1489203955Srdivacky * 1490203955Srdivacky * \param Tokens the set of tokens to annotate. 1491203955Srdivacky * 1492203955Srdivacky * \param NumTokens the number of tokens in \p Tokens. 1493203955Srdivacky * 1494203955Srdivacky * \param Cursors an array of \p NumTokens cursors, whose contents will be 1495203955Srdivacky * replaced with the cursors corresponding to each token. 1496203955Srdivacky */ 1497203955SrdivackyCINDEX_LINKAGE void clang_annotateTokens(CXTranslationUnit TU, 1498203955Srdivacky CXToken *Tokens, unsigned NumTokens, 1499203955Srdivacky CXCursor *Cursors); 1500205219Srdivacky 1501203955Srdivacky/** 1502203955Srdivacky * \brief Free the given set of tokens. 1503203955Srdivacky */ 1504205219SrdivackyCINDEX_LINKAGE void clang_disposeTokens(CXTranslationUnit TU, 1505203955Srdivacky CXToken *Tokens, unsigned NumTokens); 1506205219Srdivacky 1507203955Srdivacky/** 1508203955Srdivacky * @} 1509203955Srdivacky */ 1510205219Srdivacky 1511203955Srdivacky/** 1512202879Srdivacky * \defgroup CINDEX_DEBUG Debugging facilities 1513202879Srdivacky * 1514202879Srdivacky * These routines are used for testing and debugging, only, and should not 1515202879Srdivacky * be relied upon. 1516202879Srdivacky * 1517202879Srdivacky * @{ 1518202879Srdivacky */ 1519203955Srdivacky 1520198092Srdivacky/* for debug/testing */ 1521204643SrdivackyCINDEX_LINKAGE CXString clang_getCursorKindSpelling(enum CXCursorKind Kind); 1522203955SrdivackyCINDEX_LINKAGE void clang_getDefinitionSpellingAndExtent(CXCursor, 1523203955Srdivacky const char **startBuf, 1524198092Srdivacky const char **endBuf, 1525198092Srdivacky unsigned *startLine, 1526198092Srdivacky unsigned *startColumn, 1527198092Srdivacky unsigned *endLine, 1528198092Srdivacky unsigned *endColumn); 1529204643SrdivackyCINDEX_LINKAGE void clang_enableStackTraces(void); 1530202879Srdivacky/** 1531202879Srdivacky * @} 1532198092Srdivacky */ 1533203955Srdivacky 1534199482Srdivacky/** 1535202879Srdivacky * \defgroup CINDEX_CODE_COMPLET Code completion 1536202879Srdivacky * 1537202879Srdivacky * Code completion involves taking an (incomplete) source file, along with 1538202879Srdivacky * knowledge of where the user is actively editing that file, and suggesting 1539202879Srdivacky * syntactically- and semantically-valid constructs that the user might want to 1540202879Srdivacky * use at that particular point in the source code. These data structures and 1541202879Srdivacky * routines provide support for code completion. 1542202879Srdivacky * 1543202879Srdivacky * @{ 1544202879Srdivacky */ 1545203955Srdivacky 1546202879Srdivacky/** 1547199482Srdivacky * \brief A semantic string that describes a code-completion result. 1548199482Srdivacky * 1549199482Srdivacky * A semantic string that describes the formatting of a code-completion 1550199482Srdivacky * result as a single "template" of text that should be inserted into the 1551199482Srdivacky * source buffer when a particular code-completion result is selected. 1552199482Srdivacky * Each semantic string is made up of some number of "chunks", each of which 1553199482Srdivacky * contains some text along with a description of what that text means, e.g., 1554199482Srdivacky * the name of the entity being referenced, whether the text chunk is part of 1555199482Srdivacky * the template, or whether it is a "placeholder" that the user should replace 1556199482Srdivacky * with actual code,of a specific kind. See \c CXCompletionChunkKind for a 1557203955Srdivacky * description of the different kinds of chunks. 1558199482Srdivacky */ 1559199482Srdivackytypedef void *CXCompletionString; 1560203955Srdivacky 1561199482Srdivacky/** 1562199482Srdivacky * \brief A single result of code completion. 1563199482Srdivacky */ 1564199482Srdivackytypedef struct { 1565199482Srdivacky /** 1566203955Srdivacky * \brief The kind of entity that this completion refers to. 1567199482Srdivacky * 1568203955Srdivacky * The cursor kind will be a macro, keyword, or a declaration (one of the 1569199482Srdivacky * *Decl cursor kinds), describing the entity that the completion is 1570199482Srdivacky * referring to. 1571199482Srdivacky * 1572199482Srdivacky * \todo In the future, we would like to provide a full cursor, to allow 1573199482Srdivacky * the client to extract additional information from declaration. 1574199482Srdivacky */ 1575199482Srdivacky enum CXCursorKind CursorKind; 1576203955Srdivacky 1577203955Srdivacky /** 1578199482Srdivacky * \brief The code-completion string that describes how to insert this 1579199482Srdivacky * code-completion result into the editing buffer. 1580199482Srdivacky */ 1581199482Srdivacky CXCompletionString CompletionString; 1582199482Srdivacky} CXCompletionResult; 1583199482Srdivacky 1584199482Srdivacky/** 1585199482Srdivacky * \brief Describes a single piece of text within a code-completion string. 1586199482Srdivacky * 1587203955Srdivacky * Each "chunk" within a code-completion string (\c CXCompletionString) is 1588203955Srdivacky * either a piece of text with a specific "kind" that describes how that text 1589199482Srdivacky * should be interpreted by the client or is another completion string. 1590199482Srdivacky */ 1591199482Srdivackyenum CXCompletionChunkKind { 1592199482Srdivacky /** 1593199482Srdivacky * \brief A code-completion string that describes "optional" text that 1594199482Srdivacky * could be a part of the template (but is not required). 1595199482Srdivacky * 1596199482Srdivacky * The Optional chunk is the only kind of chunk that has a code-completion 1597203955Srdivacky * string for its representation, which is accessible via 1598199482Srdivacky * \c clang_getCompletionChunkCompletionString(). The code-completion string 1599199482Srdivacky * describes an additional part of the template that is completely optional. 1600199482Srdivacky * For example, optional chunks can be used to describe the placeholders for 1601199482Srdivacky * arguments that match up with defaulted function parameters, e.g. given: 1602199482Srdivacky * 1603199482Srdivacky * \code 1604199482Srdivacky * void f(int x, float y = 3.14, double z = 2.71828); 1605199482Srdivacky * \endcode 1606199482Srdivacky * 1607199482Srdivacky * The code-completion string for this function would contain: 1608199482Srdivacky * - a TypedText chunk for "f". 1609199482Srdivacky * - a LeftParen chunk for "(". 1610199482Srdivacky * - a Placeholder chunk for "int x" 1611199482Srdivacky * - an Optional chunk containing the remaining defaulted arguments, e.g., 1612199482Srdivacky * - a Comma chunk for "," 1613204643Srdivacky * - a Placeholder chunk for "float y" 1614199482Srdivacky * - an Optional chunk containing the last defaulted argument: 1615199482Srdivacky * - a Comma chunk for "," 1616199482Srdivacky * - a Placeholder chunk for "double z" 1617199482Srdivacky * - a RightParen chunk for ")" 1618199482Srdivacky * 1619204643Srdivacky * There are many ways to handle Optional chunks. Two simple approaches are: 1620199482Srdivacky * - Completely ignore optional chunks, in which case the template for the 1621199482Srdivacky * function "f" would only include the first parameter ("int x"). 1622199482Srdivacky * - Fully expand all optional chunks, in which case the template for the 1623199482Srdivacky * function "f" would have all of the parameters. 1624199482Srdivacky */ 1625199482Srdivacky CXCompletionChunk_Optional, 1626199482Srdivacky /** 1627199482Srdivacky * \brief Text that a user would be expected to type to get this 1628203955Srdivacky * code-completion result. 1629199482Srdivacky * 1630203955Srdivacky * There will be exactly one "typed text" chunk in a semantic string, which 1631203955Srdivacky * will typically provide the spelling of a keyword or the name of a 1632199482Srdivacky * declaration that could be used at the current code point. Clients are 1633199482Srdivacky * expected to filter the code-completion results based on the text in this 1634199482Srdivacky * chunk. 1635199482Srdivacky */ 1636199482Srdivacky CXCompletionChunk_TypedText, 1637199482Srdivacky /** 1638199482Srdivacky * \brief Text that should be inserted as part of a code-completion result. 1639199482Srdivacky * 1640199482Srdivacky * A "text" chunk represents text that is part of the template to be 1641199482Srdivacky * inserted into user code should this particular code-completion result 1642199482Srdivacky * be selected. 1643199482Srdivacky */ 1644199482Srdivacky CXCompletionChunk_Text, 1645199482Srdivacky /** 1646199482Srdivacky * \brief Placeholder text that should be replaced by the user. 1647199482Srdivacky * 1648199482Srdivacky * A "placeholder" chunk marks a place where the user should insert text 1649199482Srdivacky * into the code-completion template. For example, placeholders might mark 1650199482Srdivacky * the function parameters for a function declaration, to indicate that the 1651199482Srdivacky * user should provide arguments for each of those parameters. The actual 1652199482Srdivacky * text in a placeholder is a suggestion for the text to display before 1653199482Srdivacky * the user replaces the placeholder with real code. 1654199482Srdivacky */ 1655199482Srdivacky CXCompletionChunk_Placeholder, 1656199482Srdivacky /** 1657199482Srdivacky * \brief Informative text that should be displayed but never inserted as 1658199482Srdivacky * part of the template. 1659203955Srdivacky * 1660199482Srdivacky * An "informative" chunk contains annotations that can be displayed to 1661199482Srdivacky * help the user decide whether a particular code-completion result is the 1662199482Srdivacky * right option, but which is not part of the actual template to be inserted 1663199482Srdivacky * by code completion. 1664199482Srdivacky */ 1665199482Srdivacky CXCompletionChunk_Informative, 1666199482Srdivacky /** 1667199482Srdivacky * \brief Text that describes the current parameter when code-completion is 1668199482Srdivacky * referring to function call, message send, or template specialization. 1669199482Srdivacky * 1670199482Srdivacky * A "current parameter" chunk occurs when code-completion is providing 1671199482Srdivacky * information about a parameter corresponding to the argument at the 1672199482Srdivacky * code-completion point. For example, given a function 1673199482Srdivacky * 1674199482Srdivacky * \code 1675199482Srdivacky * int add(int x, int y); 1676199482Srdivacky * \endcode 1677199482Srdivacky * 1678199482Srdivacky * and the source code \c add(, where the code-completion point is after the 1679199482Srdivacky * "(", the code-completion string will contain a "current parameter" chunk 1680199482Srdivacky * for "int x", indicating that the current argument will initialize that 1681199482Srdivacky * parameter. After typing further, to \c add(17, (where the code-completion 1682203955Srdivacky * point is after the ","), the code-completion string will contain a 1683199482Srdivacky * "current paremeter" chunk to "int y". 1684199482Srdivacky */ 1685199482Srdivacky CXCompletionChunk_CurrentParameter, 1686199482Srdivacky /** 1687199482Srdivacky * \brief A left parenthesis ('('), used to initiate a function call or 1688199482Srdivacky * signal the beginning of a function parameter list. 1689199482Srdivacky */ 1690199482Srdivacky CXCompletionChunk_LeftParen, 1691199482Srdivacky /** 1692199482Srdivacky * \brief A right parenthesis (')'), used to finish a function call or 1693199482Srdivacky * signal the end of a function parameter list. 1694199482Srdivacky */ 1695199482Srdivacky CXCompletionChunk_RightParen, 1696199482Srdivacky /** 1697199482Srdivacky * \brief A left bracket ('['). 1698199482Srdivacky */ 1699199482Srdivacky CXCompletionChunk_LeftBracket, 1700199482Srdivacky /** 1701199482Srdivacky * \brief A right bracket (']'). 1702199482Srdivacky */ 1703199482Srdivacky CXCompletionChunk_RightBracket, 1704199482Srdivacky /** 1705199482Srdivacky * \brief A left brace ('{'). 1706199482Srdivacky */ 1707199482Srdivacky CXCompletionChunk_LeftBrace, 1708199482Srdivacky /** 1709199482Srdivacky * \brief A right brace ('}'). 1710199482Srdivacky */ 1711199482Srdivacky CXCompletionChunk_RightBrace, 1712199482Srdivacky /** 1713199482Srdivacky * \brief A left angle bracket ('<'). 1714199482Srdivacky */ 1715199482Srdivacky CXCompletionChunk_LeftAngle, 1716199482Srdivacky /** 1717199482Srdivacky * \brief A right angle bracket ('>'). 1718199482Srdivacky */ 1719199482Srdivacky CXCompletionChunk_RightAngle, 1720199482Srdivacky /** 1721199482Srdivacky * \brief A comma separator (','). 1722199482Srdivacky */ 1723201361Srdivacky CXCompletionChunk_Comma, 1724201361Srdivacky /** 1725203955Srdivacky * \brief Text that specifies the result type of a given result. 1726201361Srdivacky * 1727201361Srdivacky * This special kind of informative chunk is not meant to be inserted into 1728203955Srdivacky * the text buffer. Rather, it is meant to illustrate the type that an 1729201361Srdivacky * expression using the given completion string would have. 1730201361Srdivacky */ 1731202379Srdivacky CXCompletionChunk_ResultType, 1732202379Srdivacky /** 1733202379Srdivacky * \brief A colon (':'). 1734202379Srdivacky */ 1735202379Srdivacky CXCompletionChunk_Colon, 1736202379Srdivacky /** 1737202379Srdivacky * \brief A semicolon (';'). 1738202379Srdivacky */ 1739202379Srdivacky CXCompletionChunk_SemiColon, 1740202379Srdivacky /** 1741202379Srdivacky * \brief An '=' sign. 1742202379Srdivacky */ 1743202379Srdivacky CXCompletionChunk_Equal, 1744202379Srdivacky /** 1745202379Srdivacky * Horizontal space (' '). 1746202379Srdivacky */ 1747202379Srdivacky CXCompletionChunk_HorizontalSpace, 1748202379Srdivacky /** 1749202379Srdivacky * Vertical space ('\n'), after which it is generally a good idea to 1750202379Srdivacky * perform indentation. 1751202379Srdivacky */ 1752202379Srdivacky CXCompletionChunk_VerticalSpace 1753199482Srdivacky}; 1754203955Srdivacky 1755199482Srdivacky/** 1756199482Srdivacky * \brief Determine the kind of a particular chunk within a completion string. 1757199482Srdivacky * 1758199482Srdivacky * \param completion_string the completion string to query. 1759199482Srdivacky * 1760199482Srdivacky * \param chunk_number the 0-based index of the chunk in the completion string. 1761199482Srdivacky * 1762199482Srdivacky * \returns the kind of the chunk at the index \c chunk_number. 1763199482Srdivacky */ 1764203955SrdivackyCINDEX_LINKAGE enum CXCompletionChunkKind 1765199482Srdivackyclang_getCompletionChunkKind(CXCompletionString completion_string, 1766199482Srdivacky unsigned chunk_number); 1767203955Srdivacky 1768199482Srdivacky/** 1769203955Srdivacky * \brief Retrieve the text associated with a particular chunk within a 1770199482Srdivacky * completion string. 1771199482Srdivacky * 1772199482Srdivacky * \param completion_string the completion string to query. 1773199482Srdivacky * 1774199482Srdivacky * \param chunk_number the 0-based index of the chunk in the completion string. 1775199482Srdivacky * 1776199482Srdivacky * \returns the text associated with the chunk at index \c chunk_number. 1777199482Srdivacky */ 1778204643SrdivackyCINDEX_LINKAGE CXString 1779199482Srdivackyclang_getCompletionChunkText(CXCompletionString completion_string, 1780199482Srdivacky unsigned chunk_number); 1781199482Srdivacky 1782199482Srdivacky/** 1783203955Srdivacky * \brief Retrieve the completion string associated with a particular chunk 1784199482Srdivacky * within a completion string. 1785199482Srdivacky * 1786199482Srdivacky * \param completion_string the completion string to query. 1787199482Srdivacky * 1788199482Srdivacky * \param chunk_number the 0-based index of the chunk in the completion string. 1789199482Srdivacky * 1790199482Srdivacky * \returns the completion string associated with the chunk at index 1791199482Srdivacky * \c chunk_number, or NULL if that chunk is not represented by a completion 1792199482Srdivacky * string. 1793199482Srdivacky */ 1794199482SrdivackyCINDEX_LINKAGE CXCompletionString 1795199482Srdivackyclang_getCompletionChunkCompletionString(CXCompletionString completion_string, 1796199482Srdivacky unsigned chunk_number); 1797203955Srdivacky 1798199482Srdivacky/** 1799199482Srdivacky * \brief Retrieve the number of chunks in the given code-completion string. 1800199482Srdivacky */ 1801199482SrdivackyCINDEX_LINKAGE unsigned 1802199482Srdivackyclang_getNumCompletionChunks(CXCompletionString completion_string); 1803199482Srdivacky 1804199482Srdivacky/** 1805208600Srdivacky * \brief Determine the priority of this code completion. 1806208600Srdivacky * 1807208600Srdivacky * The priority of a code completion indicates how likely it is that this 1808208600Srdivacky * particular completion is the completion that the user will select. The 1809208600Srdivacky * priority is selected by various internal heuristics. 1810208600Srdivacky * 1811208600Srdivacky * \param completion_string The completion string to query. 1812208600Srdivacky * 1813208600Srdivacky * \returns The priority of this completion string. Smaller values indicate 1814208600Srdivacky * higher-priority (more likely) completions. 1815208600Srdivacky */ 1816208600SrdivackyCINDEX_LINKAGE unsigned 1817208600Srdivackyclang_getCompletionPriority(CXCompletionString completion_string); 1818208600Srdivacky 1819208600Srdivacky/** 1820201361Srdivacky * \brief Contains the results of code-completion. 1821201361Srdivacky * 1822201361Srdivacky * This data structure contains the results of code completion, as 1823203955Srdivacky * produced by \c clang_codeComplete. Its contents must be freed by 1824201361Srdivacky * \c clang_disposeCodeCompleteResults. 1825201361Srdivacky */ 1826201361Srdivackytypedef struct { 1827201361Srdivacky /** 1828201361Srdivacky * \brief The code-completion results. 1829201361Srdivacky */ 1830201361Srdivacky CXCompletionResult *Results; 1831201361Srdivacky 1832201361Srdivacky /** 1833201361Srdivacky * \brief The number of code-completion results stored in the 1834201361Srdivacky * \c Results array. 1835201361Srdivacky */ 1836201361Srdivacky unsigned NumResults; 1837201361Srdivacky} CXCodeCompleteResults; 1838201361Srdivacky 1839201361Srdivacky/** 1840199482Srdivacky * \brief Perform code completion at a given location in a source file. 1841199482Srdivacky * 1842199482Srdivacky * This function performs code completion at a particular file, line, and 1843199482Srdivacky * column within source code, providing results that suggest potential 1844199482Srdivacky * code snippets based on the context of the completion. The basic model 1845199482Srdivacky * for code completion is that Clang will parse a complete source file, 1846199482Srdivacky * performing syntax checking up to the location where code-completion has 1847199482Srdivacky * been requested. At that point, a special code-completion token is passed 1848199482Srdivacky * to the parser, which recognizes this token and determines, based on the 1849203955Srdivacky * current location in the C/Objective-C/C++ grammar and the state of 1850199482Srdivacky * semantic analysis, what completions to provide. These completions are 1851201361Srdivacky * returned via a new \c CXCodeCompleteResults structure. 1852199482Srdivacky * 1853199482Srdivacky * Code completion itself is meant to be triggered by the client when the 1854203955Srdivacky * user types punctuation characters or whitespace, at which point the 1855199482Srdivacky * code-completion location will coincide with the cursor. For example, if \c p 1856199482Srdivacky * is a pointer, code-completion might be triggered after the "-" and then 1857199482Srdivacky * after the ">" in \c p->. When the code-completion location is afer the ">", 1858199482Srdivacky * the completion results will provide, e.g., the members of the struct that 1859199482Srdivacky * "p" points to. The client is responsible for placing the cursor at the 1860199482Srdivacky * beginning of the token currently being typed, then filtering the results 1861199482Srdivacky * based on the contents of the token. For example, when code-completing for 1862199482Srdivacky * the expression \c p->get, the client should provide the location just after 1863199482Srdivacky * the ">" (e.g., pointing at the "g") to this code-completion hook. Then, the 1864199482Srdivacky * client can filter the results based on the current token text ("get"), only 1865199482Srdivacky * showing those results that start with "get". The intent of this interface 1866201361Srdivacky * is to separate the relatively high-latency acquisition of code-completion 1867199482Srdivacky * results from the filtering of results on a per-character basis, which must 1868199482Srdivacky * have a lower latency. 1869199482Srdivacky * 1870199482Srdivacky * \param CIdx the \c CXIndex instance that will be used to perform code 1871199482Srdivacky * completion. 1872199482Srdivacky * 1873200583Srdivacky * \param source_filename the name of the source file that should be parsed to 1874200583Srdivacky * perform code-completion. This source file must be the same as or include the 1875200583Srdivacky * filename described by \p complete_filename, or no code-completion results 1876200583Srdivacky * will be produced. NOTE: One can also specify NULL for this argument if the 1877200583Srdivacky * source file is included in command_line_args. 1878199482Srdivacky * 1879199482Srdivacky * \param num_command_line_args the number of command-line arguments stored in 1880199482Srdivacky * \p command_line_args. 1881199482Srdivacky * 1882199482Srdivacky * \param command_line_args the command-line arguments to pass to the Clang 1883203955Srdivacky * compiler to build the given source file. This should include all of the 1884199482Srdivacky * necessary include paths, language-dialect switches, precompiled header 1885203955Srdivacky * includes, etc., but should not include any information specific to 1886199482Srdivacky * code completion. 1887199482Srdivacky * 1888200583Srdivacky * \param num_unsaved_files the number of unsaved file entries in \p 1889200583Srdivacky * unsaved_files. 1890200583Srdivacky * 1891200583Srdivacky * \param unsaved_files the files that have not yet been saved to disk 1892200583Srdivacky * but may be required for code completion, including the contents of 1893207619Srdivacky * those files. The contents and name of these files (as specified by 1894207619Srdivacky * CXUnsavedFile) are copied when necessary, so the client only needs to 1895207619Srdivacky * guarantee their validity until the call to this function returns. 1896200583Srdivacky * 1897199482Srdivacky * \param complete_filename the name of the source file where code completion 1898199482Srdivacky * should be performed. In many cases, this name will be the same as the 1899203955Srdivacky * source filename. However, the completion filename may also be a file 1900203955Srdivacky * included by the source file, which is required when producing 1901199482Srdivacky * code-completion results for a header. 1902199482Srdivacky * 1903199482Srdivacky * \param complete_line the line at which code-completion should occur. 1904199482Srdivacky * 1905203955Srdivacky * \param complete_column the column at which code-completion should occur. 1906199482Srdivacky * Note that the column should point just after the syntactic construct that 1907199482Srdivacky * initiated code completion, and not in the middle of a lexical token. 1908199482Srdivacky * 1909203955Srdivacky * \param diag_callback callback function that will receive any diagnostics 1910203955Srdivacky * emitted while processing this source file. If NULL, diagnostics will be 1911203955Srdivacky * suppressed. 1912203955Srdivacky * 1913203955Srdivacky * \param diag_client_data client data that will be passed to the diagnostic 1914203955Srdivacky * callback function. 1915203955Srdivacky * 1916201361Srdivacky * \returns if successful, a new CXCodeCompleteResults structure 1917201361Srdivacky * containing code-completion results, which should eventually be 1918201361Srdivacky * freed with \c clang_disposeCodeCompleteResults(). If code 1919201361Srdivacky * completion fails, returns NULL. 1920199482Srdivacky */ 1921203955SrdivackyCINDEX_LINKAGE 1922203955SrdivackyCXCodeCompleteResults *clang_codeComplete(CXIndex CIdx, 1923201361Srdivacky const char *source_filename, 1924203955Srdivacky int num_command_line_args, 1925201361Srdivacky const char **command_line_args, 1926201361Srdivacky unsigned num_unsaved_files, 1927201361Srdivacky struct CXUnsavedFile *unsaved_files, 1928201361Srdivacky const char *complete_filename, 1929201361Srdivacky unsigned complete_line, 1930204643Srdivacky unsigned complete_column); 1931203955Srdivacky 1932201361Srdivacky/** 1933201361Srdivacky * \brief Free the given set of code-completion results. 1934201361Srdivacky */ 1935203955SrdivackyCINDEX_LINKAGE 1936201361Srdivackyvoid clang_disposeCodeCompleteResults(CXCodeCompleteResults *Results); 1937203955Srdivacky 1938202879Srdivacky/** 1939204643Srdivacky * \brief Determine the number of diagnostics produced prior to the 1940204643Srdivacky * location where code completion was performed. 1941204643Srdivacky */ 1942205219SrdivackyCINDEX_LINKAGE 1943204643Srdivackyunsigned clang_codeCompleteGetNumDiagnostics(CXCodeCompleteResults *Results); 1944204643Srdivacky 1945204643Srdivacky/** 1946204643Srdivacky * \brief Retrieve a diagnostic associated with the given code completion. 1947204643Srdivacky * 1948204643Srdivacky * \param Result the code completion results to query. 1949204643Srdivacky * \param Index the zero-based diagnostic number to retrieve. 1950204643Srdivacky * 1951204643Srdivacky * \returns the requested diagnostic. This diagnostic must be freed 1952204643Srdivacky * via a call to \c clang_disposeDiagnostic(). 1953204643Srdivacky */ 1954205219SrdivackyCINDEX_LINKAGE 1955204643SrdivackyCXDiagnostic clang_codeCompleteGetDiagnostic(CXCodeCompleteResults *Results, 1956204643Srdivacky unsigned Index); 1957204643Srdivacky 1958204643Srdivacky/** 1959202879Srdivacky * @} 1960202879Srdivacky */ 1961203955Srdivacky 1962203955Srdivacky 1963202879Srdivacky/** 1964202879Srdivacky * \defgroup CINDEX_MISC Miscellaneous utility functions 1965202879Srdivacky * 1966202879Srdivacky * @{ 1967202879Srdivacky */ 1968202879Srdivacky 1969202879Srdivacky/** 1970203955Srdivacky * \brief Return a version string, suitable for showing to a user, but not 1971203955Srdivacky * intended to be parsed (the format is not guaranteed to be stable). 1972203955Srdivacky */ 1973203955SrdivackyCINDEX_LINKAGE CXString clang_getClangVersion(); 1974203955Srdivacky 1975203955Srdivacky/** 1976203955Srdivacky * \brief Return a version string, suitable for showing to a user, but not 1977203955Srdivacky * intended to be parsed (the format is not guaranteed to be stable). 1978203955Srdivacky */ 1979205219Srdivacky 1980205219Srdivacky 1981203955Srdivacky /** 1982205219Srdivacky * \brief Visitor invoked for each file in a translation unit 1983203955Srdivacky * (used with clang_getInclusions()). 1984203955Srdivacky * 1985203955Srdivacky * This visitor function will be invoked by clang_getInclusions() for each 1986203955Srdivacky * file included (either at the top-level or by #include directives) within 1987203955Srdivacky * a translation unit. The first argument is the file being included, and 1988203955Srdivacky * the second and third arguments provide the inclusion stack. The 1989203955Srdivacky * array is sorted in order of immediate inclusion. For example, 1990203955Srdivacky * the first element refers to the location that included 'included_file'. 1991203955Srdivacky */ 1992203955Srdivackytypedef void (*CXInclusionVisitor)(CXFile included_file, 1993203955Srdivacky CXSourceLocation* inclusion_stack, 1994203955Srdivacky unsigned include_len, 1995203955Srdivacky CXClientData client_data); 1996203955Srdivacky 1997203955Srdivacky/** 1998203955Srdivacky * \brief Visit the set of preprocessor inclusions in a translation unit. 1999203955Srdivacky * The visitor function is called with the provided data for every included 2000203955Srdivacky * file. This does not include headers included by the PCH file (unless one 2001203955Srdivacky * is inspecting the inclusions in the PCH file itself). 2002203955Srdivacky */ 2003203955SrdivackyCINDEX_LINKAGE void clang_getInclusions(CXTranslationUnit tu, 2004203955Srdivacky CXInclusionVisitor visitor, 2005203955Srdivacky CXClientData client_data); 2006203955Srdivacky 2007203955Srdivacky/** 2008202879Srdivacky * @} 2009202879Srdivacky */ 2010203955Srdivacky 2011202879Srdivacky/** 2012202879Srdivacky * @} 2013202879Srdivacky */ 2014203955Srdivacky 2015198092Srdivacky#ifdef __cplusplus 2016198092Srdivacky} 2017198092Srdivacky#endif 2018198092Srdivacky#endif 2019198092Srdivacky 2020