Index.h revision 204962
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); 174203955Srdivacky 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(); 300202879Srdivacky 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 /** 360203955Srdivacky * \brief A diagnostic that has been suppressed, e.g., by a command-line 361203955Srdivacky * option. 362203955Srdivacky */ 363203955Srdivacky CXDiagnostic_Ignored = 0, 364203955Srdivacky 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 * 454204643Srdivacky * 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 464204643Srdivacky * the diagnostic according to the various options given. The 465204643Srdivacky * \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 * 470204643Srdivacky * \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 */ 494203955SrdivackyCINDEX_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); 515203955Srdivacky 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 521203955Srdivacky * underlining them with '~' characters. 522203955Srdivacky * 523203955Srdivacky * \param Diagnostic the diagnostic whose range is being extracted. 524203955Srdivacky * 525203955Srdivacky * \param Range the zero-based index specifying which range to 526203955Srdivacky * 527203955Srdivacky * \returns the requested source range. 528203955Srdivacky */ 529203955SrdivackyCINDEX_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 */ 563204643SrdivackyCINDEX_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 */ 580203955Srdivacky 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 612203955Srdivacky * those files. 613203955Srdivacky * 614203955Srdivacky * \param diag_callback callback function that will receive any diagnostics 615203955Srdivacky * emitted while processing this source file. If NULL, diagnostics will be 616203955Srdivacky * suppressed. 617203955Srdivacky * 618203955Srdivacky * \param diag_client_data client data that will be passed to the diagnostic 619203955Srdivacky * callback function. 620203955Srdivacky */ 621203955SrdivackyCINDEX_LINKAGE CXTranslationUnit clang_createTranslationUnitFromSourceFile( 622203955Srdivacky CXIndex CIdx, 623203955Srdivacky const char *source_filename, 624203955Srdivacky int num_clang_command_line_args, 625203955Srdivacky const char **clang_command_line_args, 626203955Srdivacky unsigned num_unsaved_files, 627204643Srdivacky struct CXUnsavedFile *unsaved_files); 628203955Srdivacky 629203955Srdivacky/** 630203955Srdivacky * \brief Create a translation unit from an AST file (-emit-ast). 631203955Srdivacky */ 632203955SrdivackyCINDEX_LINKAGE CXTranslationUnit clang_createTranslationUnit(CXIndex, 633204643Srdivacky const char *ast_filename); 634203955Srdivacky 635203955Srdivacky/** 636203955Srdivacky * \brief Destroy the specified CXTranslationUnit object. 637203955Srdivacky */ 638203955SrdivackyCINDEX_LINKAGE void clang_disposeTranslationUnit(CXTranslationUnit); 639203955Srdivacky 640203955Srdivacky/** 641203955Srdivacky * @} 642203955Srdivacky */ 643203955Srdivacky 644203955Srdivacky/** 645202879Srdivacky * \brief Describes the kind of entity that a cursor refers to. 646202379Srdivacky */ 647202879Srdivackyenum CXCursorKind { 648202879Srdivacky /* Declarations */ 649202879Srdivacky CXCursor_FirstDecl = 1, 650203955Srdivacky /** 651202879Srdivacky * \brief A declaration whose specific kind is not exposed via this 652203955Srdivacky * interface. 653202879Srdivacky * 654202879Srdivacky * Unexposed declarations have the same operations as any other kind 655202879Srdivacky * of declaration; one can extract their location information, 656202879Srdivacky * spelling, find their definitions, etc. However, the specific kind 657202879Srdivacky * of the declaration is not reported. 658202879Srdivacky */ 659202879Srdivacky CXCursor_UnexposedDecl = 1, 660202879Srdivacky /** \brief A C or C++ struct. */ 661203955Srdivacky CXCursor_StructDecl = 2, 662202879Srdivacky /** \brief A C or C++ union. */ 663202879Srdivacky CXCursor_UnionDecl = 3, 664202879Srdivacky /** \brief A C++ class. */ 665202879Srdivacky CXCursor_ClassDecl = 4, 666202879Srdivacky /** \brief An enumeration. */ 667202879Srdivacky CXCursor_EnumDecl = 5, 668203955Srdivacky /** 669202879Srdivacky * \brief A field (in C) or non-static data member (in C++) in a 670202879Srdivacky * struct, union, or C++ class. 671202879Srdivacky */ 672202879Srdivacky CXCursor_FieldDecl = 6, 673202879Srdivacky /** \brief An enumerator constant. */ 674202879Srdivacky CXCursor_EnumConstantDecl = 7, 675202879Srdivacky /** \brief A function. */ 676202879Srdivacky CXCursor_FunctionDecl = 8, 677202879Srdivacky /** \brief A variable. */ 678202879Srdivacky CXCursor_VarDecl = 9, 679202879Srdivacky /** \brief A function or method parameter. */ 680202879Srdivacky CXCursor_ParmDecl = 10, 681202879Srdivacky /** \brief An Objective-C @interface. */ 682202879Srdivacky CXCursor_ObjCInterfaceDecl = 11, 683202879Srdivacky /** \brief An Objective-C @interface for a category. */ 684202879Srdivacky CXCursor_ObjCCategoryDecl = 12, 685202879Srdivacky /** \brief An Objective-C @protocol declaration. */ 686202879Srdivacky CXCursor_ObjCProtocolDecl = 13, 687202879Srdivacky /** \brief An Objective-C @property declaration. */ 688202879Srdivacky CXCursor_ObjCPropertyDecl = 14, 689202879Srdivacky /** \brief An Objective-C instance variable. */ 690202879Srdivacky CXCursor_ObjCIvarDecl = 15, 691202879Srdivacky /** \brief An Objective-C instance method. */ 692202879Srdivacky CXCursor_ObjCInstanceMethodDecl = 16, 693202879Srdivacky /** \brief An Objective-C class method. */ 694202879Srdivacky CXCursor_ObjCClassMethodDecl = 17, 695202879Srdivacky /** \brief An Objective-C @implementation. */ 696202879Srdivacky CXCursor_ObjCImplementationDecl = 18, 697202879Srdivacky /** \brief An Objective-C @implementation for a category. */ 698202879Srdivacky CXCursor_ObjCCategoryImplDecl = 19, 699202879Srdivacky /** \brief A typedef */ 700202879Srdivacky CXCursor_TypedefDecl = 20, 701202879Srdivacky CXCursor_LastDecl = 20, 702203955Srdivacky 703202879Srdivacky /* References */ 704202879Srdivacky CXCursor_FirstRef = 40, /* Decl references */ 705203955Srdivacky CXCursor_ObjCSuperClassRef = 40, 706202879Srdivacky CXCursor_ObjCProtocolRef = 41, 707202879Srdivacky CXCursor_ObjCClassRef = 42, 708202879Srdivacky /** 709202879Srdivacky * \brief A reference to a type declaration. 710202879Srdivacky * 711202879Srdivacky * A type reference occurs anywhere where a type is named but not 712202879Srdivacky * declared. For example, given: 713202879Srdivacky * 714202879Srdivacky * \code 715202879Srdivacky * typedef unsigned size_type; 716202879Srdivacky * size_type size; 717202879Srdivacky * \endcode 718202879Srdivacky * 719202879Srdivacky * The typedef is a declaration of size_type (CXCursor_TypedefDecl), 720202879Srdivacky * while the type of the variable "size" is referenced. The cursor 721202879Srdivacky * referenced by the type of size is the typedef for size_type. 722202879Srdivacky */ 723202879Srdivacky CXCursor_TypeRef = 43, 724202879Srdivacky CXCursor_LastRef = 43, 725203955Srdivacky 726202879Srdivacky /* Error conditions */ 727202879Srdivacky CXCursor_FirstInvalid = 70, 728202879Srdivacky CXCursor_InvalidFile = 70, 729202879Srdivacky CXCursor_NoDeclFound = 71, 730202879Srdivacky CXCursor_NotImplemented = 72, 731202879Srdivacky CXCursor_LastInvalid = 72, 732203955Srdivacky 733202879Srdivacky /* Expressions */ 734202879Srdivacky CXCursor_FirstExpr = 100, 735203955Srdivacky 736202879Srdivacky /** 737202879Srdivacky * \brief An expression whose specific kind is not exposed via this 738203955Srdivacky * interface. 739202879Srdivacky * 740202879Srdivacky * Unexposed expressions have the same operations as any other kind 741202879Srdivacky * of expression; one can extract their location information, 742202879Srdivacky * spelling, children, etc. However, the specific kind of the 743202879Srdivacky * expression is not reported. 744202879Srdivacky */ 745202879Srdivacky CXCursor_UnexposedExpr = 100, 746203955Srdivacky 747202879Srdivacky /** 748202879Srdivacky * \brief An expression that refers to some value declaration, such 749202879Srdivacky * as a function, varible, or enumerator. 750202879Srdivacky */ 751202879Srdivacky CXCursor_DeclRefExpr = 101, 752203955Srdivacky 753202879Srdivacky /** 754202879Srdivacky * \brief An expression that refers to a member of a struct, union, 755202879Srdivacky * class, Objective-C class, etc. 756202879Srdivacky */ 757202879Srdivacky CXCursor_MemberRefExpr = 102, 758203955Srdivacky 759202879Srdivacky /** \brief An expression that calls a function. */ 760202879Srdivacky CXCursor_CallExpr = 103, 761203955Srdivacky 762202879Srdivacky /** \brief An expression that sends a message to an Objective-C 763202879Srdivacky object or class. */ 764202879Srdivacky CXCursor_ObjCMessageExpr = 104, 765202879Srdivacky CXCursor_LastExpr = 104, 766203955Srdivacky 767202879Srdivacky /* Statements */ 768202879Srdivacky CXCursor_FirstStmt = 200, 769202879Srdivacky /** 770202879Srdivacky * \brief A statement whose specific kind is not exposed via this 771202879Srdivacky * interface. 772202879Srdivacky * 773202879Srdivacky * Unexposed statements have the same operations as any other kind of 774202879Srdivacky * statement; one can extract their location information, spelling, 775202879Srdivacky * children, etc. However, the specific kind of the statement is not 776202879Srdivacky * reported. 777202879Srdivacky */ 778202879Srdivacky CXCursor_UnexposedStmt = 200, 779202879Srdivacky CXCursor_LastStmt = 200, 780203955Srdivacky 781202879Srdivacky /** 782202879Srdivacky * \brief Cursor that represents the translation unit itself. 783202879Srdivacky * 784202879Srdivacky * The translation unit cursor exists primarily to act as the root 785202879Srdivacky * cursor for traversing the contents of a translation unit. 786202879Srdivacky */ 787204643Srdivacky CXCursor_TranslationUnit = 300, 788204643Srdivacky 789204643Srdivacky /* Attributes */ 790204643Srdivacky CXCursor_FirstAttr = 400, 791204643Srdivacky /** 792204643Srdivacky * \brief An attribute whose specific kind is not exposed via this 793204643Srdivacky * interface. 794204643Srdivacky */ 795204643Srdivacky CXCursor_UnexposedAttr = 400, 796204643Srdivacky 797204643Srdivacky CXCursor_IBActionAttr = 401, 798204643Srdivacky CXCursor_IBOutletAttr = 402, 799204643Srdivacky CXCursor_LastAttr = CXCursor_IBOutletAttr 800202879Srdivacky}; 801202379Srdivacky 802202879Srdivacky/** 803202879Srdivacky * \brief A cursor representing some element in the abstract syntax tree for 804202879Srdivacky * a translation unit. 805202879Srdivacky * 806203955Srdivacky * The cursor abstraction unifies the different kinds of entities in a 807202879Srdivacky * program--declaration, statements, expressions, references to declarations, 808202879Srdivacky * etc.--under a single "cursor" abstraction with a common set of operations. 809202879Srdivacky * Common operation for a cursor include: getting the physical location in 810202879Srdivacky * a source file where the cursor points, getting the name associated with a 811202879Srdivacky * cursor, and retrieving cursors for any child nodes of a particular cursor. 812202879Srdivacky * 813202879Srdivacky * Cursors can be produced in two specific ways. 814202879Srdivacky * clang_getTranslationUnitCursor() produces a cursor for a translation unit, 815202879Srdivacky * from which one can use clang_visitChildren() to explore the rest of the 816202879Srdivacky * translation unit. clang_getCursor() maps from a physical source location 817202879Srdivacky * to the entity that resides at that location, allowing one to map from the 818202879Srdivacky * source code into the AST. 819198092Srdivacky */ 820202879Srdivackytypedef struct { 821202879Srdivacky enum CXCursorKind kind; 822202879Srdivacky void *data[3]; 823203955Srdivacky} CXCursor; 824202879Srdivacky 825198398Srdivacky/** 826202879Srdivacky * \defgroup CINDEX_CURSOR_MANIP Cursor manipulations 827202879Srdivacky * 828202879Srdivacky * @{ 829198398Srdivacky */ 830203955Srdivacky 831202879Srdivacky/** 832202879Srdivacky * \brief Retrieve the NULL cursor, which represents no entity. 833202879Srdivacky */ 834199482SrdivackyCINDEX_LINKAGE CXCursor clang_getNullCursor(void); 835203955Srdivacky 836202879Srdivacky/** 837202879Srdivacky * \brief Retrieve the cursor that represents the given translation unit. 838202879Srdivacky * 839202879Srdivacky * The translation unit cursor can be used to start traversing the 840202879Srdivacky * various declarations within the given translation unit. 841202879Srdivacky */ 842202879SrdivackyCINDEX_LINKAGE CXCursor clang_getTranslationUnitCursor(CXTranslationUnit); 843198092Srdivacky 844202879Srdivacky/** 845202879Srdivacky * \brief Determine whether two cursors are equivalent. 846202879Srdivacky */ 847202879SrdivackyCINDEX_LINKAGE unsigned clang_equalCursors(CXCursor, CXCursor); 848203955Srdivacky 849202879Srdivacky/** 850202879Srdivacky * \brief Retrieve the kind of the given cursor. 851202879Srdivacky */ 852198893SrdivackyCINDEX_LINKAGE enum CXCursorKind clang_getCursorKind(CXCursor); 853202879Srdivacky 854202879Srdivacky/** 855202879Srdivacky * \brief Determine whether the given cursor kind represents a declaration. 856202879Srdivacky */ 857198893SrdivackyCINDEX_LINKAGE unsigned clang_isDeclaration(enum CXCursorKind); 858202879Srdivacky 859202879Srdivacky/** 860202879Srdivacky * \brief Determine whether the given cursor kind represents a simple 861202879Srdivacky * reference. 862202879Srdivacky * 863202879Srdivacky * Note that other kinds of cursors (such as expressions) can also refer to 864202879Srdivacky * other cursors. Use clang_getCursorReferenced() to determine whether a 865202879Srdivacky * particular cursor refers to another entity. 866202879Srdivacky */ 867198893SrdivackyCINDEX_LINKAGE unsigned clang_isReference(enum CXCursorKind); 868202879Srdivacky 869202879Srdivacky/** 870202879Srdivacky * \brief Determine whether the given cursor kind represents an expression. 871202879Srdivacky */ 872202879SrdivackyCINDEX_LINKAGE unsigned clang_isExpression(enum CXCursorKind); 873202879Srdivacky 874202879Srdivacky/** 875202879Srdivacky * \brief Determine whether the given cursor kind represents a statement. 876202879Srdivacky */ 877202879SrdivackyCINDEX_LINKAGE unsigned clang_isStatement(enum CXCursorKind); 878202879Srdivacky 879202879Srdivacky/** 880203955Srdivacky * \brief Determine whether the given cursor kind represents an invalid 881202879Srdivacky * cursor. 882203955Srdivacky */ 883198893SrdivackyCINDEX_LINKAGE unsigned clang_isInvalid(enum CXCursorKind); 884198398Srdivacky 885202879Srdivacky/** 886203955Srdivacky * \brief Determine whether the given cursor kind represents a translation 887203955Srdivacky * unit. 888202879Srdivacky */ 889202879SrdivackyCINDEX_LINKAGE unsigned clang_isTranslationUnit(enum CXCursorKind); 890203955Srdivacky 891204962Srdivacky/*** 892204962Srdivacky * \brief Determine whether the given cursor represents a currently 893204962Srdivacky * unexposed piece of the AST (e.g., CXCursor_UnexposedStmt). 894204962Srdivacky */ 895204962SrdivackyCINDEX_LINKAGE unsigned clang_isUnexposed(enum CXCursorKind); 896204962Srdivacky 897202879Srdivacky/** 898204643Srdivacky * \brief Describe the linkage of the entity referred to by a cursor. 899204643Srdivacky */ 900204643Srdivackyenum CXLinkageKind { 901204643Srdivacky /** \brief This value indicates that no linkage information is available 902204643Srdivacky * for a provided CXCursor. */ 903204643Srdivacky CXLinkage_Invalid, 904204643Srdivacky /** 905204643Srdivacky * \brief This is the linkage for variables, parameters, and so on that 906204643Srdivacky * have automatic storage. This covers normal (non-extern) local variables. 907204643Srdivacky */ 908204643Srdivacky CXLinkage_NoLinkage, 909204643Srdivacky /** \brief This is the linkage for static variables and static functions. */ 910204643Srdivacky CXLinkage_Internal, 911204643Srdivacky /** \brief This is the linkage for entities with external linkage that live 912204643Srdivacky * in C++ anonymous namespaces.*/ 913204643Srdivacky CXLinkage_UniqueExternal, 914204643Srdivacky /** \brief This is the linkage for entities with true, external linkage. */ 915204643Srdivacky CXLinkage_External 916204643Srdivacky}; 917204643Srdivacky 918204643Srdivacky/** 919204643Srdivacky * \brief Determine the linkage of the entity referred to be a given cursor. 920204643Srdivacky */ 921204643SrdivackyCINDEX_LINKAGE enum CXLinkageKind clang_getCursorLinkage(CXCursor cursor); 922204643Srdivacky 923204643Srdivacky/** 924202879Srdivacky * @} 925202879Srdivacky */ 926203955Srdivacky 927202879Srdivacky/** 928202879Srdivacky * \defgroup CINDEX_CURSOR_SOURCE Mapping between cursors and source code 929202879Srdivacky * 930202879Srdivacky * Cursors represent a location within the Abstract Syntax Tree (AST). These 931202879Srdivacky * routines help map between cursors and the physical locations where the 932202879Srdivacky * described entities occur in the source code. The mapping is provided in 933202879Srdivacky * both directions, so one can map from source code to the AST and back. 934202879Srdivacky * 935202879Srdivacky * @{ 936202879Srdivacky */ 937203955Srdivacky 938202879Srdivacky/** 939202879Srdivacky * \brief Map a source location to the cursor that describes the entity at that 940202879Srdivacky * location in the source code. 941202879Srdivacky * 942202879Srdivacky * clang_getCursor() maps an arbitrary source location within a translation 943202879Srdivacky * unit down to the most specific cursor that describes the entity at that 944203955Srdivacky * location. For example, given an expression \c x + y, invoking 945202879Srdivacky * clang_getCursor() with a source location pointing to "x" will return the 946203955Srdivacky * cursor for "x"; similarly for "y". If the cursor points anywhere between 947202879Srdivacky * "x" or "y" (e.g., on the + or the whitespace around it), clang_getCursor() 948202879Srdivacky * will return a cursor referring to the "+" expression. 949202879Srdivacky * 950202879Srdivacky * \returns a cursor representing the entity at the given source location, or 951202879Srdivacky * a NULL cursor if no such entity can be found. 952202879Srdivacky */ 953202879SrdivackyCINDEX_LINKAGE CXCursor clang_getCursor(CXTranslationUnit, CXSourceLocation); 954203955Srdivacky 955202879Srdivacky/** 956202879Srdivacky * \brief Retrieve the physical location of the source constructor referenced 957202879Srdivacky * by the given cursor. 958202879Srdivacky * 959202879Srdivacky * The location of a declaration is typically the location of the name of that 960203955Srdivacky * declaration, where the name of that declaration would occur if it is 961203955Srdivacky * unnamed, or some keyword that introduces that particular declaration. 962203955Srdivacky * The location of a reference is where that reference occurs within the 963202879Srdivacky * source code. 964202879Srdivacky */ 965202879SrdivackyCINDEX_LINKAGE CXSourceLocation clang_getCursorLocation(CXCursor); 966199482Srdivacky 967202879Srdivacky/** 968202879Srdivacky * \brief Retrieve the physical extent of the source construct referenced by 969202879Srdivacky * the given cursor. 970202879Srdivacky * 971202879Srdivacky * The extent of a cursor starts with the file/line/column pointing at the 972202879Srdivacky * first character within the source construct that the cursor refers to and 973203955Srdivacky * ends with the last character withinin that source construct. For a 974202879Srdivacky * declaration, the extent covers the declaration itself. For a reference, 975202879Srdivacky * the extent covers the location of the reference (e.g., where the referenced 976202879Srdivacky * entity was actually used). 977202879Srdivacky */ 978202879SrdivackyCINDEX_LINKAGE CXSourceRange clang_getCursorExtent(CXCursor); 979202879Srdivacky 980202879Srdivacky/** 981202879Srdivacky * @} 982202879Srdivacky */ 983203955Srdivacky 984202879Srdivacky/** 985202879Srdivacky * \defgroup CINDEX_CURSOR_TRAVERSAL Traversing the AST with cursors 986202879Srdivacky * 987202879Srdivacky * These routines provide the ability to traverse the abstract syntax tree 988202879Srdivacky * using cursors. 989202879Srdivacky * 990202879Srdivacky * @{ 991202879Srdivacky */ 992203955Srdivacky 993202879Srdivacky/** 994202879Srdivacky * \brief Describes how the traversal of the children of a particular 995202879Srdivacky * cursor should proceed after visiting a particular child cursor. 996202879Srdivacky * 997202879Srdivacky * A value of this enumeration type should be returned by each 998202879Srdivacky * \c CXCursorVisitor to indicate how clang_visitChildren() proceed. 999202879Srdivacky */ 1000202879Srdivackyenum CXChildVisitResult { 1001202879Srdivacky /** 1002203955Srdivacky * \brief Terminates the cursor traversal. 1003202879Srdivacky */ 1004202879Srdivacky CXChildVisit_Break, 1005203955Srdivacky /** 1006202879Srdivacky * \brief Continues the cursor traversal with the next sibling of 1007202879Srdivacky * the cursor just visited, without visiting its children. 1008202879Srdivacky */ 1009202879Srdivacky CXChildVisit_Continue, 1010202879Srdivacky /** 1011202879Srdivacky * \brief Recursively traverse the children of this cursor, using 1012202879Srdivacky * the same visitor and client data. 1013202879Srdivacky */ 1014202879Srdivacky CXChildVisit_Recurse 1015202879Srdivacky}; 1016202879Srdivacky 1017202879Srdivacky/** 1018202879Srdivacky * \brief Visitor invoked for each cursor found by a traversal. 1019202879Srdivacky * 1020202879Srdivacky * This visitor function will be invoked for each cursor found by 1021202879Srdivacky * clang_visitCursorChildren(). Its first argument is the cursor being 1022202879Srdivacky * visited, its second argument is the parent visitor for that cursor, 1023202879Srdivacky * and its third argument is the client data provided to 1024202879Srdivacky * clang_visitCursorChildren(). 1025202879Srdivacky * 1026202879Srdivacky * The visitor should return one of the \c CXChildVisitResult values 1027202879Srdivacky * to direct clang_visitCursorChildren(). 1028202879Srdivacky */ 1029203955Srdivackytypedef enum CXChildVisitResult (*CXCursorVisitor)(CXCursor cursor, 1030203955Srdivacky CXCursor parent, 1031202879Srdivacky CXClientData client_data); 1032202879Srdivacky 1033202879Srdivacky/** 1034202879Srdivacky * \brief Visit the children of a particular cursor. 1035202879Srdivacky * 1036202879Srdivacky * This function visits all the direct children of the given cursor, 1037202879Srdivacky * invoking the given \p visitor function with the cursors of each 1038202879Srdivacky * visited child. The traversal may be recursive, if the visitor returns 1039202879Srdivacky * \c CXChildVisit_Recurse. The traversal may also be ended prematurely, if 1040202879Srdivacky * the visitor returns \c CXChildVisit_Break. 1041202879Srdivacky * 1042202879Srdivacky * \param parent the cursor whose child may be visited. All kinds of 1043203955Srdivacky * cursors can be visited, including invalid cursors (which, by 1044202879Srdivacky * definition, have no children). 1045202879Srdivacky * 1046202879Srdivacky * \param visitor the visitor function that will be invoked for each 1047202879Srdivacky * child of \p parent. 1048202879Srdivacky * 1049202879Srdivacky * \param client_data pointer data supplied by the client, which will 1050202879Srdivacky * be passed to the visitor each time it is invoked. 1051202879Srdivacky * 1052202879Srdivacky * \returns a non-zero value if the traversal was terminated 1053202879Srdivacky * prematurely by the visitor returning \c CXChildVisit_Break. 1054202879Srdivacky */ 1055203955SrdivackyCINDEX_LINKAGE unsigned clang_visitChildren(CXCursor parent, 1056202879Srdivacky CXCursorVisitor visitor, 1057202879Srdivacky CXClientData client_data); 1058203955Srdivacky 1059202879Srdivacky/** 1060202879Srdivacky * @} 1061202879Srdivacky */ 1062203955Srdivacky 1063202879Srdivacky/** 1064202879Srdivacky * \defgroup CINDEX_CURSOR_XREF Cross-referencing in the AST 1065202879Srdivacky * 1066203955Srdivacky * These routines provide the ability to determine references within and 1067202879Srdivacky * across translation units, by providing the names of the entities referenced 1068202879Srdivacky * by cursors, follow reference cursors to the declarations they reference, 1069202879Srdivacky * and associate declarations with their definitions. 1070202879Srdivacky * 1071202879Srdivacky * @{ 1072202879Srdivacky */ 1073203955Srdivacky 1074202879Srdivacky/** 1075202879Srdivacky * \brief Retrieve a Unified Symbol Resolution (USR) for the entity referenced 1076202879Srdivacky * by the given cursor. 1077202879Srdivacky * 1078202879Srdivacky * A Unified Symbol Resolution (USR) is a string that identifies a particular 1079202879Srdivacky * entity (function, class, variable, etc.) within a program. USRs can be 1080202879Srdivacky * compared across translation units to determine, e.g., when references in 1081202879Srdivacky * one translation refer to an entity defined in another translation unit. 1082202879Srdivacky */ 1083202879SrdivackyCINDEX_LINKAGE CXString clang_getCursorUSR(CXCursor); 1084202879Srdivacky 1085202879Srdivacky/** 1086202879Srdivacky * \brief Retrieve a name for the entity referenced by this cursor. 1087202879Srdivacky */ 1088199482SrdivackyCINDEX_LINKAGE CXString clang_getCursorSpelling(CXCursor); 1089198398Srdivacky 1090202879Srdivacky/** \brief For a cursor that is a reference, retrieve a cursor representing the 1091202879Srdivacky * entity that it references. 1092202879Srdivacky * 1093202879Srdivacky * Reference cursors refer to other entities in the AST. For example, an 1094202879Srdivacky * Objective-C superclass reference cursor refers to an Objective-C class. 1095203955Srdivacky * This function produces the cursor for the Objective-C class from the 1096202879Srdivacky * cursor for the superclass reference. If the input cursor is a declaration or 1097202879Srdivacky * definition, it returns that declaration or definition unchanged. 1098203955Srdivacky * Otherwise, returns the NULL cursor. 1099202879Srdivacky */ 1100202879SrdivackyCINDEX_LINKAGE CXCursor clang_getCursorReferenced(CXCursor); 1101202879Srdivacky 1102203955Srdivacky/** 1103202879Srdivacky * \brief For a cursor that is either a reference to or a declaration 1104202879Srdivacky * of some entity, retrieve a cursor that describes the definition of 1105202879Srdivacky * that entity. 1106202879Srdivacky * 1107202879Srdivacky * Some entities can be declared multiple times within a translation 1108202879Srdivacky * unit, but only one of those declarations can also be a 1109202879Srdivacky * definition. For example, given: 1110202879Srdivacky * 1111202879Srdivacky * \code 1112202879Srdivacky * int f(int, int); 1113202879Srdivacky * int g(int x, int y) { return f(x, y); } 1114202879Srdivacky * int f(int a, int b) { return a + b; } 1115202879Srdivacky * int f(int, int); 1116202879Srdivacky * \endcode 1117202879Srdivacky * 1118202879Srdivacky * there are three declarations of the function "f", but only the 1119202879Srdivacky * second one is a definition. The clang_getCursorDefinition() 1120202879Srdivacky * function will take any cursor pointing to a declaration of "f" 1121202879Srdivacky * (the first or fourth lines of the example) or a cursor referenced 1122202879Srdivacky * that uses "f" (the call to "f' inside "g") and will return a 1123202879Srdivacky * declaration cursor pointing to the definition (the second "f" 1124202879Srdivacky * declaration). 1125202879Srdivacky * 1126202879Srdivacky * If given a cursor for which there is no corresponding definition, 1127202879Srdivacky * e.g., because there is no definition of that entity within this 1128202879Srdivacky * translation unit, returns a NULL cursor. 1129202879Srdivacky */ 1130202879SrdivackyCINDEX_LINKAGE CXCursor clang_getCursorDefinition(CXCursor); 1131202879Srdivacky 1132203955Srdivacky/** 1133202879Srdivacky * \brief Determine whether the declaration pointed to by this cursor 1134202879Srdivacky * is also a definition of that entity. 1135202879Srdivacky */ 1136202879SrdivackyCINDEX_LINKAGE unsigned clang_isCursorDefinition(CXCursor); 1137202879Srdivacky 1138202879Srdivacky/** 1139202879Srdivacky * @} 1140202879Srdivacky */ 1141203955Srdivacky 1142203955Srdivacky/** 1143203955Srdivacky * \defgroup CINDEX_LEX Token extraction and manipulation 1144203955Srdivacky * 1145203955Srdivacky * The routines in this group provide access to the tokens within a 1146203955Srdivacky * translation unit, along with a semantic mapping of those tokens to 1147203955Srdivacky * their corresponding cursors. 1148203955Srdivacky * 1149203955Srdivacky * @{ 1150203955Srdivacky */ 1151203955Srdivacky 1152203955Srdivacky/** 1153203955Srdivacky * \brief Describes a kind of token. 1154203955Srdivacky */ 1155203955Srdivackytypedef enum CXTokenKind { 1156203955Srdivacky /** 1157203955Srdivacky * \brief A token that contains some kind of punctuation. 1158203955Srdivacky */ 1159203955Srdivacky CXToken_Punctuation, 1160202879Srdivacky 1161203955Srdivacky /** 1162203955Srdivacky * \brief A language keyword. 1163203955Srdivacky */ 1164203955Srdivacky CXToken_Keyword, 1165203955Srdivacky 1166203955Srdivacky /** 1167203955Srdivacky * \brief An identifier (that is not a keyword). 1168203955Srdivacky */ 1169203955Srdivacky CXToken_Identifier, 1170203955Srdivacky 1171203955Srdivacky /** 1172203955Srdivacky * \brief A numeric, string, or character literal. 1173203955Srdivacky */ 1174203955Srdivacky CXToken_Literal, 1175203955Srdivacky 1176203955Srdivacky /** 1177203955Srdivacky * \brief A comment. 1178203955Srdivacky */ 1179203955Srdivacky CXToken_Comment 1180203955Srdivacky} CXTokenKind; 1181203955Srdivacky 1182202879Srdivacky/** 1183203955Srdivacky * \brief Describes a single preprocessing token. 1184203955Srdivacky */ 1185203955Srdivackytypedef struct { 1186203955Srdivacky unsigned int_data[4]; 1187203955Srdivacky void *ptr_data; 1188203955Srdivacky} CXToken; 1189203955Srdivacky 1190203955Srdivacky/** 1191203955Srdivacky * \brief Determine the kind of the given token. 1192203955Srdivacky */ 1193203955SrdivackyCINDEX_LINKAGE CXTokenKind clang_getTokenKind(CXToken); 1194203955Srdivacky 1195203955Srdivacky/** 1196203955Srdivacky * \brief Determine the spelling of the given token. 1197203955Srdivacky * 1198203955Srdivacky * The spelling of a token is the textual representation of that token, e.g., 1199203955Srdivacky * the text of an identifier or keyword. 1200203955Srdivacky */ 1201203955SrdivackyCINDEX_LINKAGE CXString clang_getTokenSpelling(CXTranslationUnit, CXToken); 1202203955Srdivacky 1203203955Srdivacky/** 1204203955Srdivacky * \brief Retrieve the source location of the given token. 1205203955Srdivacky */ 1206203955SrdivackyCINDEX_LINKAGE CXSourceLocation clang_getTokenLocation(CXTranslationUnit, 1207203955Srdivacky CXToken); 1208203955Srdivacky 1209203955Srdivacky/** 1210203955Srdivacky * \brief Retrieve a source range that covers the given token. 1211203955Srdivacky */ 1212203955SrdivackyCINDEX_LINKAGE CXSourceRange clang_getTokenExtent(CXTranslationUnit, CXToken); 1213203955Srdivacky 1214203955Srdivacky/** 1215203955Srdivacky * \brief Tokenize the source code described by the given range into raw 1216203955Srdivacky * lexical tokens. 1217203955Srdivacky * 1218203955Srdivacky * \param TU the translation unit whose text is being tokenized. 1219203955Srdivacky * 1220203955Srdivacky * \param Range the source range in which text should be tokenized. All of the 1221203955Srdivacky * tokens produced by tokenization will fall within this source range, 1222203955Srdivacky * 1223203955Srdivacky * \param Tokens this pointer will be set to point to the array of tokens 1224203955Srdivacky * that occur within the given source range. The returned pointer must be 1225203955Srdivacky * freed with clang_disposeTokens() before the translation unit is destroyed. 1226203955Srdivacky * 1227203955Srdivacky * \param NumTokens will be set to the number of tokens in the \c *Tokens 1228203955Srdivacky * array. 1229203955Srdivacky * 1230203955Srdivacky */ 1231203955SrdivackyCINDEX_LINKAGE void clang_tokenize(CXTranslationUnit TU, CXSourceRange Range, 1232203955Srdivacky CXToken **Tokens, unsigned *NumTokens); 1233203955Srdivacky 1234203955Srdivacky/** 1235203955Srdivacky * \brief Annotate the given set of tokens by providing cursors for each token 1236203955Srdivacky * that can be mapped to a specific entity within the abstract syntax tree. 1237203955Srdivacky * 1238203955Srdivacky * This token-annotation routine is equivalent to invoking 1239203955Srdivacky * clang_getCursor() for the source locations of each of the 1240203955Srdivacky * tokens. The cursors provided are filtered, so that only those 1241203955Srdivacky * cursors that have a direct correspondence to the token are 1242203955Srdivacky * accepted. For example, given a function call \c f(x), 1243203955Srdivacky * clang_getCursor() would provide the following cursors: 1244203955Srdivacky * 1245203955Srdivacky * * when the cursor is over the 'f', a DeclRefExpr cursor referring to 'f'. 1246203955Srdivacky * * when the cursor is over the '(' or the ')', a CallExpr referring to 'f'. 1247203955Srdivacky * * when the cursor is over the 'x', a DeclRefExpr cursor referring to 'x'. 1248203955Srdivacky * 1249203955Srdivacky * Only the first and last of these cursors will occur within the 1250203955Srdivacky * annotate, since the tokens "f" and "x' directly refer to a function 1251203955Srdivacky * and a variable, respectively, but the parentheses are just a small 1252203955Srdivacky * part of the full syntax of the function call expression, which is 1253203955Srdivacky * not provided as an annotation. 1254203955Srdivacky * 1255203955Srdivacky * \param TU the translation unit that owns the given tokens. 1256203955Srdivacky * 1257203955Srdivacky * \param Tokens the set of tokens to annotate. 1258203955Srdivacky * 1259203955Srdivacky * \param NumTokens the number of tokens in \p Tokens. 1260203955Srdivacky * 1261203955Srdivacky * \param Cursors an array of \p NumTokens cursors, whose contents will be 1262203955Srdivacky * replaced with the cursors corresponding to each token. 1263203955Srdivacky */ 1264203955SrdivackyCINDEX_LINKAGE void clang_annotateTokens(CXTranslationUnit TU, 1265203955Srdivacky CXToken *Tokens, unsigned NumTokens, 1266203955Srdivacky CXCursor *Cursors); 1267203955Srdivacky 1268203955Srdivacky/** 1269203955Srdivacky * \brief Free the given set of tokens. 1270203955Srdivacky */ 1271203955SrdivackyCINDEX_LINKAGE void clang_disposeTokens(CXTranslationUnit TU, 1272203955Srdivacky CXToken *Tokens, unsigned NumTokens); 1273203955Srdivacky 1274203955Srdivacky/** 1275203955Srdivacky * @} 1276203955Srdivacky */ 1277203955Srdivacky 1278203955Srdivacky/** 1279202879Srdivacky * \defgroup CINDEX_DEBUG Debugging facilities 1280202879Srdivacky * 1281202879Srdivacky * These routines are used for testing and debugging, only, and should not 1282202879Srdivacky * be relied upon. 1283202879Srdivacky * 1284202879Srdivacky * @{ 1285202879Srdivacky */ 1286203955Srdivacky 1287198092Srdivacky/* for debug/testing */ 1288204643SrdivackyCINDEX_LINKAGE CXString clang_getCursorKindSpelling(enum CXCursorKind Kind); 1289203955SrdivackyCINDEX_LINKAGE void clang_getDefinitionSpellingAndExtent(CXCursor, 1290203955Srdivacky const char **startBuf, 1291198092Srdivacky const char **endBuf, 1292198092Srdivacky unsigned *startLine, 1293198092Srdivacky unsigned *startColumn, 1294198092Srdivacky unsigned *endLine, 1295198092Srdivacky unsigned *endColumn); 1296204643SrdivackyCINDEX_LINKAGE void clang_enableStackTraces(void); 1297202879Srdivacky/** 1298202879Srdivacky * @} 1299198092Srdivacky */ 1300203955Srdivacky 1301199482Srdivacky/** 1302202879Srdivacky * \defgroup CINDEX_CODE_COMPLET Code completion 1303202879Srdivacky * 1304202879Srdivacky * Code completion involves taking an (incomplete) source file, along with 1305202879Srdivacky * knowledge of where the user is actively editing that file, and suggesting 1306202879Srdivacky * syntactically- and semantically-valid constructs that the user might want to 1307202879Srdivacky * use at that particular point in the source code. These data structures and 1308202879Srdivacky * routines provide support for code completion. 1309202879Srdivacky * 1310202879Srdivacky * @{ 1311202879Srdivacky */ 1312203955Srdivacky 1313202879Srdivacky/** 1314199482Srdivacky * \brief A semantic string that describes a code-completion result. 1315199482Srdivacky * 1316199482Srdivacky * A semantic string that describes the formatting of a code-completion 1317199482Srdivacky * result as a single "template" of text that should be inserted into the 1318199482Srdivacky * source buffer when a particular code-completion result is selected. 1319199482Srdivacky * Each semantic string is made up of some number of "chunks", each of which 1320199482Srdivacky * contains some text along with a description of what that text means, e.g., 1321199482Srdivacky * the name of the entity being referenced, whether the text chunk is part of 1322199482Srdivacky * the template, or whether it is a "placeholder" that the user should replace 1323199482Srdivacky * with actual code,of a specific kind. See \c CXCompletionChunkKind for a 1324203955Srdivacky * description of the different kinds of chunks. 1325199482Srdivacky */ 1326199482Srdivackytypedef void *CXCompletionString; 1327203955Srdivacky 1328199482Srdivacky/** 1329199482Srdivacky * \brief A single result of code completion. 1330199482Srdivacky */ 1331199482Srdivackytypedef struct { 1332199482Srdivacky /** 1333203955Srdivacky * \brief The kind of entity that this completion refers to. 1334199482Srdivacky * 1335203955Srdivacky * The cursor kind will be a macro, keyword, or a declaration (one of the 1336199482Srdivacky * *Decl cursor kinds), describing the entity that the completion is 1337199482Srdivacky * referring to. 1338199482Srdivacky * 1339199482Srdivacky * \todo In the future, we would like to provide a full cursor, to allow 1340199482Srdivacky * the client to extract additional information from declaration. 1341199482Srdivacky */ 1342199482Srdivacky enum CXCursorKind CursorKind; 1343203955Srdivacky 1344203955Srdivacky /** 1345199482Srdivacky * \brief The code-completion string that describes how to insert this 1346199482Srdivacky * code-completion result into the editing buffer. 1347199482Srdivacky */ 1348199482Srdivacky CXCompletionString CompletionString; 1349199482Srdivacky} CXCompletionResult; 1350199482Srdivacky 1351199482Srdivacky/** 1352199482Srdivacky * \brief Describes a single piece of text within a code-completion string. 1353199482Srdivacky * 1354203955Srdivacky * Each "chunk" within a code-completion string (\c CXCompletionString) is 1355203955Srdivacky * either a piece of text with a specific "kind" that describes how that text 1356199482Srdivacky * should be interpreted by the client or is another completion string. 1357199482Srdivacky */ 1358199482Srdivackyenum CXCompletionChunkKind { 1359199482Srdivacky /** 1360199482Srdivacky * \brief A code-completion string that describes "optional" text that 1361199482Srdivacky * could be a part of the template (but is not required). 1362199482Srdivacky * 1363199482Srdivacky * The Optional chunk is the only kind of chunk that has a code-completion 1364203955Srdivacky * string for its representation, which is accessible via 1365199482Srdivacky * \c clang_getCompletionChunkCompletionString(). The code-completion string 1366199482Srdivacky * describes an additional part of the template that is completely optional. 1367199482Srdivacky * For example, optional chunks can be used to describe the placeholders for 1368199482Srdivacky * arguments that match up with defaulted function parameters, e.g. given: 1369199482Srdivacky * 1370199482Srdivacky * \code 1371199482Srdivacky * void f(int x, float y = 3.14, double z = 2.71828); 1372199482Srdivacky * \endcode 1373199482Srdivacky * 1374199482Srdivacky * The code-completion string for this function would contain: 1375199482Srdivacky * - a TypedText chunk for "f". 1376199482Srdivacky * - a LeftParen chunk for "(". 1377199482Srdivacky * - a Placeholder chunk for "int x" 1378199482Srdivacky * - an Optional chunk containing the remaining defaulted arguments, e.g., 1379199482Srdivacky * - a Comma chunk for "," 1380204643Srdivacky * - a Placeholder chunk for "float y" 1381199482Srdivacky * - an Optional chunk containing the last defaulted argument: 1382199482Srdivacky * - a Comma chunk for "," 1383199482Srdivacky * - a Placeholder chunk for "double z" 1384199482Srdivacky * - a RightParen chunk for ")" 1385199482Srdivacky * 1386204643Srdivacky * There are many ways to handle Optional chunks. Two simple approaches are: 1387199482Srdivacky * - Completely ignore optional chunks, in which case the template for the 1388199482Srdivacky * function "f" would only include the first parameter ("int x"). 1389199482Srdivacky * - Fully expand all optional chunks, in which case the template for the 1390199482Srdivacky * function "f" would have all of the parameters. 1391199482Srdivacky */ 1392199482Srdivacky CXCompletionChunk_Optional, 1393199482Srdivacky /** 1394199482Srdivacky * \brief Text that a user would be expected to type to get this 1395203955Srdivacky * code-completion result. 1396199482Srdivacky * 1397203955Srdivacky * There will be exactly one "typed text" chunk in a semantic string, which 1398203955Srdivacky * will typically provide the spelling of a keyword or the name of a 1399199482Srdivacky * declaration that could be used at the current code point. Clients are 1400199482Srdivacky * expected to filter the code-completion results based on the text in this 1401199482Srdivacky * chunk. 1402199482Srdivacky */ 1403199482Srdivacky CXCompletionChunk_TypedText, 1404199482Srdivacky /** 1405199482Srdivacky * \brief Text that should be inserted as part of a code-completion result. 1406199482Srdivacky * 1407199482Srdivacky * A "text" chunk represents text that is part of the template to be 1408199482Srdivacky * inserted into user code should this particular code-completion result 1409199482Srdivacky * be selected. 1410199482Srdivacky */ 1411199482Srdivacky CXCompletionChunk_Text, 1412199482Srdivacky /** 1413199482Srdivacky * \brief Placeholder text that should be replaced by the user. 1414199482Srdivacky * 1415199482Srdivacky * A "placeholder" chunk marks a place where the user should insert text 1416199482Srdivacky * into the code-completion template. For example, placeholders might mark 1417199482Srdivacky * the function parameters for a function declaration, to indicate that the 1418199482Srdivacky * user should provide arguments for each of those parameters. The actual 1419199482Srdivacky * text in a placeholder is a suggestion for the text to display before 1420199482Srdivacky * the user replaces the placeholder with real code. 1421199482Srdivacky */ 1422199482Srdivacky CXCompletionChunk_Placeholder, 1423199482Srdivacky /** 1424199482Srdivacky * \brief Informative text that should be displayed but never inserted as 1425199482Srdivacky * part of the template. 1426203955Srdivacky * 1427199482Srdivacky * An "informative" chunk contains annotations that can be displayed to 1428199482Srdivacky * help the user decide whether a particular code-completion result is the 1429199482Srdivacky * right option, but which is not part of the actual template to be inserted 1430199482Srdivacky * by code completion. 1431199482Srdivacky */ 1432199482Srdivacky CXCompletionChunk_Informative, 1433199482Srdivacky /** 1434199482Srdivacky * \brief Text that describes the current parameter when code-completion is 1435199482Srdivacky * referring to function call, message send, or template specialization. 1436199482Srdivacky * 1437199482Srdivacky * A "current parameter" chunk occurs when code-completion is providing 1438199482Srdivacky * information about a parameter corresponding to the argument at the 1439199482Srdivacky * code-completion point. For example, given a function 1440199482Srdivacky * 1441199482Srdivacky * \code 1442199482Srdivacky * int add(int x, int y); 1443199482Srdivacky * \endcode 1444199482Srdivacky * 1445199482Srdivacky * and the source code \c add(, where the code-completion point is after the 1446199482Srdivacky * "(", the code-completion string will contain a "current parameter" chunk 1447199482Srdivacky * for "int x", indicating that the current argument will initialize that 1448199482Srdivacky * parameter. After typing further, to \c add(17, (where the code-completion 1449203955Srdivacky * point is after the ","), the code-completion string will contain a 1450199482Srdivacky * "current paremeter" chunk to "int y". 1451199482Srdivacky */ 1452199482Srdivacky CXCompletionChunk_CurrentParameter, 1453199482Srdivacky /** 1454199482Srdivacky * \brief A left parenthesis ('('), used to initiate a function call or 1455199482Srdivacky * signal the beginning of a function parameter list. 1456199482Srdivacky */ 1457199482Srdivacky CXCompletionChunk_LeftParen, 1458199482Srdivacky /** 1459199482Srdivacky * \brief A right parenthesis (')'), used to finish a function call or 1460199482Srdivacky * signal the end of a function parameter list. 1461199482Srdivacky */ 1462199482Srdivacky CXCompletionChunk_RightParen, 1463199482Srdivacky /** 1464199482Srdivacky * \brief A left bracket ('['). 1465199482Srdivacky */ 1466199482Srdivacky CXCompletionChunk_LeftBracket, 1467199482Srdivacky /** 1468199482Srdivacky * \brief A right bracket (']'). 1469199482Srdivacky */ 1470199482Srdivacky CXCompletionChunk_RightBracket, 1471199482Srdivacky /** 1472199482Srdivacky * \brief A left brace ('{'). 1473199482Srdivacky */ 1474199482Srdivacky CXCompletionChunk_LeftBrace, 1475199482Srdivacky /** 1476199482Srdivacky * \brief A right brace ('}'). 1477199482Srdivacky */ 1478199482Srdivacky CXCompletionChunk_RightBrace, 1479199482Srdivacky /** 1480199482Srdivacky * \brief A left angle bracket ('<'). 1481199482Srdivacky */ 1482199482Srdivacky CXCompletionChunk_LeftAngle, 1483199482Srdivacky /** 1484199482Srdivacky * \brief A right angle bracket ('>'). 1485199482Srdivacky */ 1486199482Srdivacky CXCompletionChunk_RightAngle, 1487199482Srdivacky /** 1488199482Srdivacky * \brief A comma separator (','). 1489199482Srdivacky */ 1490201361Srdivacky CXCompletionChunk_Comma, 1491201361Srdivacky /** 1492203955Srdivacky * \brief Text that specifies the result type of a given result. 1493201361Srdivacky * 1494201361Srdivacky * This special kind of informative chunk is not meant to be inserted into 1495203955Srdivacky * the text buffer. Rather, it is meant to illustrate the type that an 1496201361Srdivacky * expression using the given completion string would have. 1497201361Srdivacky */ 1498202379Srdivacky CXCompletionChunk_ResultType, 1499202379Srdivacky /** 1500202379Srdivacky * \brief A colon (':'). 1501202379Srdivacky */ 1502202379Srdivacky CXCompletionChunk_Colon, 1503202379Srdivacky /** 1504202379Srdivacky * \brief A semicolon (';'). 1505202379Srdivacky */ 1506202379Srdivacky CXCompletionChunk_SemiColon, 1507202379Srdivacky /** 1508202379Srdivacky * \brief An '=' sign. 1509202379Srdivacky */ 1510202379Srdivacky CXCompletionChunk_Equal, 1511202379Srdivacky /** 1512202379Srdivacky * Horizontal space (' '). 1513202379Srdivacky */ 1514202379Srdivacky CXCompletionChunk_HorizontalSpace, 1515202379Srdivacky /** 1516202379Srdivacky * Vertical space ('\n'), after which it is generally a good idea to 1517202379Srdivacky * perform indentation. 1518202379Srdivacky */ 1519202379Srdivacky CXCompletionChunk_VerticalSpace 1520199482Srdivacky}; 1521203955Srdivacky 1522199482Srdivacky/** 1523199482Srdivacky * \brief Determine the kind of a particular chunk within a completion string. 1524199482Srdivacky * 1525199482Srdivacky * \param completion_string the completion string to query. 1526199482Srdivacky * 1527199482Srdivacky * \param chunk_number the 0-based index of the chunk in the completion string. 1528199482Srdivacky * 1529199482Srdivacky * \returns the kind of the chunk at the index \c chunk_number. 1530199482Srdivacky */ 1531203955SrdivackyCINDEX_LINKAGE enum CXCompletionChunkKind 1532199482Srdivackyclang_getCompletionChunkKind(CXCompletionString completion_string, 1533199482Srdivacky unsigned chunk_number); 1534203955Srdivacky 1535199482Srdivacky/** 1536203955Srdivacky * \brief Retrieve the text associated with a particular chunk within a 1537199482Srdivacky * completion string. 1538199482Srdivacky * 1539199482Srdivacky * \param completion_string the completion string to query. 1540199482Srdivacky * 1541199482Srdivacky * \param chunk_number the 0-based index of the chunk in the completion string. 1542199482Srdivacky * 1543199482Srdivacky * \returns the text associated with the chunk at index \c chunk_number. 1544199482Srdivacky */ 1545204643SrdivackyCINDEX_LINKAGE CXString 1546199482Srdivackyclang_getCompletionChunkText(CXCompletionString completion_string, 1547199482Srdivacky unsigned chunk_number); 1548199482Srdivacky 1549199482Srdivacky/** 1550203955Srdivacky * \brief Retrieve the completion string associated with a particular chunk 1551199482Srdivacky * within a completion string. 1552199482Srdivacky * 1553199482Srdivacky * \param completion_string the completion string to query. 1554199482Srdivacky * 1555199482Srdivacky * \param chunk_number the 0-based index of the chunk in the completion string. 1556199482Srdivacky * 1557199482Srdivacky * \returns the completion string associated with the chunk at index 1558199482Srdivacky * \c chunk_number, or NULL if that chunk is not represented by a completion 1559199482Srdivacky * string. 1560199482Srdivacky */ 1561199482SrdivackyCINDEX_LINKAGE CXCompletionString 1562199482Srdivackyclang_getCompletionChunkCompletionString(CXCompletionString completion_string, 1563199482Srdivacky unsigned chunk_number); 1564203955Srdivacky 1565199482Srdivacky/** 1566199482Srdivacky * \brief Retrieve the number of chunks in the given code-completion string. 1567199482Srdivacky */ 1568199482SrdivackyCINDEX_LINKAGE unsigned 1569199482Srdivackyclang_getNumCompletionChunks(CXCompletionString completion_string); 1570199482Srdivacky 1571199482Srdivacky/** 1572201361Srdivacky * \brief Contains the results of code-completion. 1573201361Srdivacky * 1574201361Srdivacky * This data structure contains the results of code completion, as 1575203955Srdivacky * produced by \c clang_codeComplete. Its contents must be freed by 1576201361Srdivacky * \c clang_disposeCodeCompleteResults. 1577201361Srdivacky */ 1578201361Srdivackytypedef struct { 1579201361Srdivacky /** 1580201361Srdivacky * \brief The code-completion results. 1581201361Srdivacky */ 1582201361Srdivacky CXCompletionResult *Results; 1583201361Srdivacky 1584201361Srdivacky /** 1585201361Srdivacky * \brief The number of code-completion results stored in the 1586201361Srdivacky * \c Results array. 1587201361Srdivacky */ 1588201361Srdivacky unsigned NumResults; 1589201361Srdivacky} CXCodeCompleteResults; 1590201361Srdivacky 1591201361Srdivacky/** 1592199482Srdivacky * \brief Perform code completion at a given location in a source file. 1593199482Srdivacky * 1594199482Srdivacky * This function performs code completion at a particular file, line, and 1595199482Srdivacky * column within source code, providing results that suggest potential 1596199482Srdivacky * code snippets based on the context of the completion. The basic model 1597199482Srdivacky * for code completion is that Clang will parse a complete source file, 1598199482Srdivacky * performing syntax checking up to the location where code-completion has 1599199482Srdivacky * been requested. At that point, a special code-completion token is passed 1600199482Srdivacky * to the parser, which recognizes this token and determines, based on the 1601203955Srdivacky * current location in the C/Objective-C/C++ grammar and the state of 1602199482Srdivacky * semantic analysis, what completions to provide. These completions are 1603201361Srdivacky * returned via a new \c CXCodeCompleteResults structure. 1604199482Srdivacky * 1605199482Srdivacky * Code completion itself is meant to be triggered by the client when the 1606203955Srdivacky * user types punctuation characters or whitespace, at which point the 1607199482Srdivacky * code-completion location will coincide with the cursor. For example, if \c p 1608199482Srdivacky * is a pointer, code-completion might be triggered after the "-" and then 1609199482Srdivacky * after the ">" in \c p->. When the code-completion location is afer the ">", 1610199482Srdivacky * the completion results will provide, e.g., the members of the struct that 1611199482Srdivacky * "p" points to. The client is responsible for placing the cursor at the 1612199482Srdivacky * beginning of the token currently being typed, then filtering the results 1613199482Srdivacky * based on the contents of the token. For example, when code-completing for 1614199482Srdivacky * the expression \c p->get, the client should provide the location just after 1615199482Srdivacky * the ">" (e.g., pointing at the "g") to this code-completion hook. Then, the 1616199482Srdivacky * client can filter the results based on the current token text ("get"), only 1617199482Srdivacky * showing those results that start with "get". The intent of this interface 1618201361Srdivacky * is to separate the relatively high-latency acquisition of code-completion 1619199482Srdivacky * results from the filtering of results on a per-character basis, which must 1620199482Srdivacky * have a lower latency. 1621199482Srdivacky * 1622199482Srdivacky * \param CIdx the \c CXIndex instance that will be used to perform code 1623199482Srdivacky * completion. 1624199482Srdivacky * 1625200583Srdivacky * \param source_filename the name of the source file that should be parsed to 1626200583Srdivacky * perform code-completion. This source file must be the same as or include the 1627200583Srdivacky * filename described by \p complete_filename, or no code-completion results 1628200583Srdivacky * will be produced. NOTE: One can also specify NULL for this argument if the 1629200583Srdivacky * source file is included in command_line_args. 1630199482Srdivacky * 1631199482Srdivacky * \param num_command_line_args the number of command-line arguments stored in 1632199482Srdivacky * \p command_line_args. 1633199482Srdivacky * 1634199482Srdivacky * \param command_line_args the command-line arguments to pass to the Clang 1635203955Srdivacky * compiler to build the given source file. This should include all of the 1636199482Srdivacky * necessary include paths, language-dialect switches, precompiled header 1637203955Srdivacky * includes, etc., but should not include any information specific to 1638199482Srdivacky * code completion. 1639199482Srdivacky * 1640200583Srdivacky * \param num_unsaved_files the number of unsaved file entries in \p 1641200583Srdivacky * unsaved_files. 1642200583Srdivacky * 1643200583Srdivacky * \param unsaved_files the files that have not yet been saved to disk 1644200583Srdivacky * but may be required for code completion, including the contents of 1645200583Srdivacky * those files. 1646200583Srdivacky * 1647199482Srdivacky * \param complete_filename the name of the source file where code completion 1648199482Srdivacky * should be performed. In many cases, this name will be the same as the 1649203955Srdivacky * source filename. However, the completion filename may also be a file 1650203955Srdivacky * included by the source file, which is required when producing 1651199482Srdivacky * code-completion results for a header. 1652199482Srdivacky * 1653199482Srdivacky * \param complete_line the line at which code-completion should occur. 1654199482Srdivacky * 1655203955Srdivacky * \param complete_column the column at which code-completion should occur. 1656199482Srdivacky * Note that the column should point just after the syntactic construct that 1657199482Srdivacky * initiated code completion, and not in the middle of a lexical token. 1658199482Srdivacky * 1659203955Srdivacky * \param diag_callback callback function that will receive any diagnostics 1660203955Srdivacky * emitted while processing this source file. If NULL, diagnostics will be 1661203955Srdivacky * suppressed. 1662203955Srdivacky * 1663203955Srdivacky * \param diag_client_data client data that will be passed to the diagnostic 1664203955Srdivacky * callback function. 1665203955Srdivacky * 1666201361Srdivacky * \returns if successful, a new CXCodeCompleteResults structure 1667201361Srdivacky * containing code-completion results, which should eventually be 1668201361Srdivacky * freed with \c clang_disposeCodeCompleteResults(). If code 1669201361Srdivacky * completion fails, returns NULL. 1670199482Srdivacky */ 1671203955SrdivackyCINDEX_LINKAGE 1672203955SrdivackyCXCodeCompleteResults *clang_codeComplete(CXIndex CIdx, 1673201361Srdivacky const char *source_filename, 1674203955Srdivacky int num_command_line_args, 1675201361Srdivacky const char **command_line_args, 1676201361Srdivacky unsigned num_unsaved_files, 1677201361Srdivacky struct CXUnsavedFile *unsaved_files, 1678201361Srdivacky const char *complete_filename, 1679201361Srdivacky unsigned complete_line, 1680204643Srdivacky unsigned complete_column); 1681203955Srdivacky 1682201361Srdivacky/** 1683201361Srdivacky * \brief Free the given set of code-completion results. 1684201361Srdivacky */ 1685203955SrdivackyCINDEX_LINKAGE 1686201361Srdivackyvoid clang_disposeCodeCompleteResults(CXCodeCompleteResults *Results); 1687203955Srdivacky 1688202879Srdivacky/** 1689204643Srdivacky * \brief Determine the number of diagnostics produced prior to the 1690204643Srdivacky * location where code completion was performed. 1691204643Srdivacky */ 1692204643SrdivackyCINDEX_LINKAGE 1693204643Srdivackyunsigned clang_codeCompleteGetNumDiagnostics(CXCodeCompleteResults *Results); 1694204643Srdivacky 1695204643Srdivacky/** 1696204643Srdivacky * \brief Retrieve a diagnostic associated with the given code completion. 1697204643Srdivacky * 1698204643Srdivacky * \param Result the code completion results to query. 1699204643Srdivacky * \param Index the zero-based diagnostic number to retrieve. 1700204643Srdivacky * 1701204643Srdivacky * \returns the requested diagnostic. This diagnostic must be freed 1702204643Srdivacky * via a call to \c clang_disposeDiagnostic(). 1703204643Srdivacky */ 1704204643SrdivackyCINDEX_LINKAGE 1705204643SrdivackyCXDiagnostic clang_codeCompleteGetDiagnostic(CXCodeCompleteResults *Results, 1706204643Srdivacky unsigned Index); 1707204643Srdivacky 1708204643Srdivacky/** 1709202879Srdivacky * @} 1710202879Srdivacky */ 1711203955Srdivacky 1712203955Srdivacky 1713202879Srdivacky/** 1714202879Srdivacky * \defgroup CINDEX_MISC Miscellaneous utility functions 1715202879Srdivacky * 1716202879Srdivacky * @{ 1717202879Srdivacky */ 1718202879Srdivacky 1719202879Srdivacky/** 1720203955Srdivacky * \brief Return a version string, suitable for showing to a user, but not 1721203955Srdivacky * intended to be parsed (the format is not guaranteed to be stable). 1722203955Srdivacky */ 1723203955SrdivackyCINDEX_LINKAGE CXString clang_getClangVersion(); 1724203955Srdivacky 1725203955Srdivacky/** 1726203955Srdivacky * \brief Return a version string, suitable for showing to a user, but not 1727203955Srdivacky * intended to be parsed (the format is not guaranteed to be stable). 1728203955Srdivacky */ 1729203955Srdivacky 1730203955Srdivacky 1731203955Srdivacky /** 1732203955Srdivacky * \brief Visitor invoked for each file in a translation unit 1733203955Srdivacky * (used with clang_getInclusions()). 1734203955Srdivacky * 1735203955Srdivacky * This visitor function will be invoked by clang_getInclusions() for each 1736203955Srdivacky * file included (either at the top-level or by #include directives) within 1737203955Srdivacky * a translation unit. The first argument is the file being included, and 1738203955Srdivacky * the second and third arguments provide the inclusion stack. The 1739203955Srdivacky * array is sorted in order of immediate inclusion. For example, 1740203955Srdivacky * the first element refers to the location that included 'included_file'. 1741203955Srdivacky */ 1742203955Srdivackytypedef void (*CXInclusionVisitor)(CXFile included_file, 1743203955Srdivacky CXSourceLocation* inclusion_stack, 1744203955Srdivacky unsigned include_len, 1745203955Srdivacky CXClientData client_data); 1746203955Srdivacky 1747203955Srdivacky/** 1748203955Srdivacky * \brief Visit the set of preprocessor inclusions in a translation unit. 1749203955Srdivacky * The visitor function is called with the provided data for every included 1750203955Srdivacky * file. This does not include headers included by the PCH file (unless one 1751203955Srdivacky * is inspecting the inclusions in the PCH file itself). 1752203955Srdivacky */ 1753203955SrdivackyCINDEX_LINKAGE void clang_getInclusions(CXTranslationUnit tu, 1754203955Srdivacky CXInclusionVisitor visitor, 1755203955Srdivacky CXClientData client_data); 1756203955Srdivacky 1757203955Srdivacky/** 1758202879Srdivacky * @} 1759202879Srdivacky */ 1760203955Srdivacky 1761202879Srdivacky/** 1762202879Srdivacky * @} 1763202879Srdivacky */ 1764203955Srdivacky 1765198092Srdivacky#ifdef __cplusplus 1766198092Srdivacky} 1767198092Srdivacky#endif 1768198092Srdivacky#endif 1769198092Srdivacky 1770