Index.h revision 203955
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> 21198893Srdivacky 22198092Srdivacky#ifdef __cplusplus 23198092Srdivackyextern "C" { 24198092Srdivacky#endif 25198092Srdivacky 26198893Srdivacky/* MSVC DLL import/export. */ 27198893Srdivacky#ifdef _MSC_VER 28198893Srdivacky #ifdef _CINDEX_LIB_ 29198893Srdivacky #define CINDEX_LINKAGE __declspec(dllexport) 30198893Srdivacky #else 31198893Srdivacky #define CINDEX_LINKAGE __declspec(dllimport) 32198893Srdivacky #endif 33198893Srdivacky#else 34198893Srdivacky #define CINDEX_LINKAGE 35198893Srdivacky#endif 36198893Srdivacky 37202879Srdivacky/** \defgroup CINDEX C Interface to Clang 38202879Srdivacky * 39203955Srdivacky * The C Interface to Clang provides a relatively small API that exposes 40202879Srdivacky * facilities for parsing source code into an abstract syntax tree (AST), 41202879Srdivacky * loading already-parsed ASTs, traversing the AST, associating 42202879Srdivacky * physical source locations with elements within the AST, and other 43202879Srdivacky * facilities that support Clang-based development tools. 44202879Srdivacky * 45203955Srdivacky * This C interface to Clang will never provide all of the information 46202879Srdivacky * representation stored in Clang's C++ AST, nor should it: the intent is to 47202879Srdivacky * maintain an API that is relatively stable from one release to the next, 48202879Srdivacky * providing only the basic functionality needed to support development tools. 49203955Srdivacky * 50203955Srdivacky * To avoid namespace pollution, data types are prefixed with "CX" and 51202879Srdivacky * functions are prefixed with "clang_". 52202879Srdivacky * 53202879Srdivacky * @{ 54202879Srdivacky */ 55203955Srdivacky 56202879Srdivacky/** 57202879Srdivacky * \brief An "index" that consists of a set of translation units that would 58202879Srdivacky * typically be linked together into an executable or library. 59202879Srdivacky */ 60202879Srdivackytypedef void *CXIndex; 61198092Srdivacky 62202879Srdivacky/** 63202879Srdivacky * \brief A single translation unit, which resides in an index. 64202879Srdivacky */ 65198092Srdivackytypedef void *CXTranslationUnit; /* A translation unit instance. */ 66198092Srdivacky 67200583Srdivacky/** 68202879Srdivacky * \brief Opaque pointer representing client data that will be passed through 69202879Srdivacky * to various callbacks and visitors. 70202879Srdivacky */ 71202879Srdivackytypedef void *CXClientData; 72203955Srdivacky 73202879Srdivacky/** 74200583Srdivacky * \brief Provides the contents of a file that has not yet been saved to disk. 75200583Srdivacky * 76200583Srdivacky * Each CXUnsavedFile instance provides the name of a file on the 77200583Srdivacky * system along with the current contents of that file that have not 78200583Srdivacky * yet been saved to disk. 79200583Srdivacky */ 80200583Srdivackystruct CXUnsavedFile { 81203955Srdivacky /** 82203955Srdivacky * \brief The file whose contents have not yet been saved. 83200583Srdivacky * 84200583Srdivacky * This file must already exist in the file system. 85200583Srdivacky */ 86200583Srdivacky const char *Filename; 87200583Srdivacky 88203955Srdivacky /** 89200583Srdivacky * \brief A null-terminated buffer containing the unsaved contents 90200583Srdivacky * of this file. 91200583Srdivacky */ 92200583Srdivacky const char *Contents; 93200583Srdivacky 94200583Srdivacky /** 95200583Srdivacky * \brief The length of the unsaved contents of this buffer, not 96200583Srdivacky * counting the NULL at the end of the buffer. 97200583Srdivacky */ 98200583Srdivacky unsigned long Length; 99200583Srdivacky}; 100200583Srdivacky 101199482Srdivacky/** 102202879Srdivacky * \defgroup CINDEX_STRING String manipulation routines 103202879Srdivacky * 104202879Srdivacky * @{ 105199482Srdivacky */ 106203955Srdivacky 107202879Srdivacky/** 108202879Srdivacky * \brief A character string. 109202879Srdivacky * 110202879Srdivacky * The \c CXString type is used to return strings from the interface when 111202879Srdivacky * the ownership of that string might different from one call to the next. 112202879Srdivacky * Use \c clang_getCString() to retrieve the string data and, once finished 113202879Srdivacky * with the string data, call \c clang_disposeString() to free the string. 114202879Srdivacky */ 115199482Srdivackytypedef struct { 116199482Srdivacky const char *Spelling; 117199482Srdivacky /* A 1 value indicates the clang_ indexing API needed to allocate the string 118199482Srdivacky (and it must be freed by clang_disposeString()). */ 119199482Srdivacky int MustFreeString; 120199482Srdivacky} CXString; 121199482Srdivacky 122202879Srdivacky/** 123202879Srdivacky * \brief Retrieve the character data associated with the given string. 124202879Srdivacky */ 125199482SrdivackyCINDEX_LINKAGE const char *clang_getCString(CXString string); 126199482Srdivacky 127202879Srdivacky/** 128202879Srdivacky * \brief Free the given string, 129202879Srdivacky */ 130199482SrdivackyCINDEX_LINKAGE void clang_disposeString(CXString string); 131199482Srdivacky 132202879Srdivacky/** 133202879Srdivacky * @} 134202879Srdivacky */ 135203955Srdivacky 136203955Srdivacky/** 137198398Srdivacky * \brief clang_createIndex() provides a shared context for creating 138198398Srdivacky * translation units. It provides two options: 139198398Srdivacky * 140198398Srdivacky * - excludeDeclarationsFromPCH: When non-zero, allows enumeration of "local" 141198398Srdivacky * declarations (when loading any new translation units). A "local" declaration 142203955Srdivacky * is one that belongs in the translation unit itself and not in a precompiled 143198398Srdivacky * header that was used by the translation unit. If zero, all declarations 144198398Srdivacky * will be enumerated. 145198398Srdivacky * 146198398Srdivacky * Here is an example: 147198398Srdivacky * 148203955Srdivacky * // excludeDeclsFromPCH = 1 149203955Srdivacky * Idx = clang_createIndex(1); 150198398Srdivacky * 151198398Srdivacky * // IndexTest.pch was produced with the following command: 152198398Srdivacky * // "clang -x c IndexTest.h -emit-ast -o IndexTest.pch" 153198398Srdivacky * TU = clang_createTranslationUnit(Idx, "IndexTest.pch"); 154198398Srdivacky * 155198398Srdivacky * // This will load all the symbols from 'IndexTest.pch' 156203955Srdivacky * clang_visitChildren(clang_getTranslationUnitCursor(TU), 157202879Srdivacky * TranslationUnitVisitor, 0); 158198398Srdivacky * clang_disposeTranslationUnit(TU); 159198398Srdivacky * 160198398Srdivacky * // This will load all the symbols from 'IndexTest.c', excluding symbols 161198398Srdivacky * // from 'IndexTest.pch'. 162203955Srdivacky * char *args[] = { "-Xclang", "-include-pch=IndexTest.pch" }; 163203955Srdivacky * TU = clang_createTranslationUnitFromSourceFile(Idx, "IndexTest.c", 2, args, 164203955Srdivacky * 0, 0); 165202879Srdivacky * clang_visitChildren(clang_getTranslationUnitCursor(TU), 166202879Srdivacky * TranslationUnitVisitor, 0); 167198398Srdivacky * clang_disposeTranslationUnit(TU); 168198398Srdivacky * 169198398Srdivacky * This process of creating the 'pch', loading it separately, and using it (via 170198398Srdivacky * -include-pch) allows 'excludeDeclsFromPCH' to remove redundant callbacks 171198398Srdivacky * (which gives the indexer the same performance benefit as the compiler). 172198398Srdivacky */ 173203955SrdivackyCINDEX_LINKAGE CXIndex clang_createIndex(int excludeDeclarationsFromPCH); 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 */ 210202879SrdivackyCINDEX_LINKAGE const char *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/** 391203955Srdivacky * \brief Describes the kind of fix-it hint expressed within a 392203955Srdivacky * diagnostic. 393203955Srdivacky */ 394203955Srdivackyenum CXFixItKind { 395203955Srdivacky /** 396203955Srdivacky * \brief A fix-it hint that inserts code at a particular position. 397203955Srdivacky */ 398203955Srdivacky CXFixIt_Insertion = 0, 399203955Srdivacky 400203955Srdivacky /** 401203955Srdivacky * \brief A fix-it hint that removes code within a range. 402203955Srdivacky */ 403203955Srdivacky CXFixIt_Removal = 1, 404203955Srdivacky 405203955Srdivacky /** 406203955Srdivacky * \brief A fix-it hint that replaces the code within a range with another 407203955Srdivacky * string. 408203955Srdivacky */ 409203955Srdivacky CXFixIt_Replacement = 2 410203955Srdivacky}; 411203955Srdivacky 412203955Srdivacky/** 413203955Srdivacky * \brief A single diagnostic, containing the diagnostic's severity, 414203955Srdivacky * location, text, source ranges, and fix-it hints. 415203955Srdivacky */ 416203955Srdivackytypedef void *CXDiagnostic; 417203955Srdivacky 418203955Srdivacky/** 419203955Srdivacky * \brief Callback function invoked for each diagnostic emitted during 420203955Srdivacky * translation. 421203955Srdivacky * 422203955Srdivacky * \param Diagnostic the diagnostic emitted during translation. This 423203955Srdivacky * diagnostic pointer is only valid during the execution of the 424203955Srdivacky * callback. 425203955Srdivacky * 426203955Srdivacky * \param ClientData the callback client data. 427203955Srdivacky */ 428203955Srdivackytypedef void (*CXDiagnosticCallback)(CXDiagnostic Diagnostic, 429203955Srdivacky CXClientData ClientData); 430203955Srdivacky 431203955Srdivacky/** 432203955Srdivacky * \brief Determine the severity of the given diagnostic. 433203955Srdivacky */ 434203955SrdivackyCINDEX_LINKAGE enum CXDiagnosticSeverity 435203955Srdivackyclang_getDiagnosticSeverity(CXDiagnostic); 436203955Srdivacky 437203955Srdivacky/** 438203955Srdivacky * \brief Retrieve the source location of the given diagnostic. 439203955Srdivacky * 440203955Srdivacky * This location is where Clang would print the caret ('^') when 441203955Srdivacky * displaying the diagnostic on the command line. 442203955Srdivacky */ 443203955SrdivackyCINDEX_LINKAGE CXSourceLocation clang_getDiagnosticLocation(CXDiagnostic); 444203955Srdivacky 445203955Srdivacky/** 446203955Srdivacky * \brief Retrieve the text of the given diagnostic. 447203955Srdivacky */ 448203955SrdivackyCINDEX_LINKAGE CXString clang_getDiagnosticSpelling(CXDiagnostic); 449203955Srdivacky 450203955Srdivacky/** 451203955Srdivacky * \brief Determine the number of source ranges associated with the given 452203955Srdivacky * diagnostic. 453203955Srdivacky */ 454203955SrdivackyCINDEX_LINKAGE unsigned clang_getDiagnosticNumRanges(CXDiagnostic); 455203955Srdivacky 456203955Srdivacky/** 457203955Srdivacky * \brief Retrieve a source range associated with the diagnostic. 458203955Srdivacky * 459203955Srdivacky * A diagnostic's source ranges highlight important elements in the source 460203955Srdivacky * code. On the command line, Clang displays source ranges by 461203955Srdivacky * underlining them with '~' characters. 462203955Srdivacky * 463203955Srdivacky * \param Diagnostic the diagnostic whose range is being extracted. 464203955Srdivacky * 465203955Srdivacky * \param Range the zero-based index specifying which range to 466203955Srdivacky * 467203955Srdivacky * \returns the requested source range. 468203955Srdivacky */ 469203955SrdivackyCINDEX_LINKAGE CXSourceRange clang_getDiagnosticRange(CXDiagnostic Diagnostic, 470203955Srdivacky unsigned Range); 471203955Srdivacky 472203955Srdivacky/** 473203955Srdivacky * \brief Determine the number of fix-it hints associated with the 474203955Srdivacky * given diagnostic. 475203955Srdivacky */ 476203955SrdivackyCINDEX_LINKAGE unsigned clang_getDiagnosticNumFixIts(CXDiagnostic Diagnostic); 477203955Srdivacky 478203955Srdivacky/** 479203955Srdivacky * \brief Retrieve the kind of the given fix-it. 480203955Srdivacky * 481203955Srdivacky * \param Diagnostic the diagnostic whose fix-its are being queried. 482203955Srdivacky * 483203955Srdivacky * \param FixIt the zero-based index of the fix-it to query. 484203955Srdivacky */ 485203955SrdivackyCINDEX_LINKAGE enum CXFixItKind 486203955Srdivackyclang_getDiagnosticFixItKind(CXDiagnostic Diagnostic, unsigned FixIt); 487203955Srdivacky 488203955Srdivacky/** 489203955Srdivacky * \brief Retrieve the insertion information for an insertion fix-it. 490203955Srdivacky * 491203955Srdivacky * For a fix-it that describes an insertion into a text buffer, 492203955Srdivacky * retrieve the source location where the text should be inserted and 493203955Srdivacky * the text to be inserted. 494203955Srdivacky * 495203955Srdivacky * \param Diagnostic the diagnostic whose fix-its are being queried. 496203955Srdivacky * 497203955Srdivacky * \param FixIt the zero-based index of the insertion fix-it. 498203955Srdivacky * 499203955Srdivacky * \param Location will be set to the location where text should be 500203955Srdivacky * inserted. 501203955Srdivacky * 502203955Srdivacky * \returns the text string to insert at the given location. 503203955Srdivacky */ 504203955SrdivackyCINDEX_LINKAGE CXString 505203955Srdivackyclang_getDiagnosticFixItInsertion(CXDiagnostic Diagnostic, unsigned FixIt, 506203955Srdivacky CXSourceLocation *Location); 507203955Srdivacky 508203955Srdivacky/** 509203955Srdivacky * \brief Retrieve the removal information for a removal fix-it. 510203955Srdivacky * 511203955Srdivacky * For a fix-it that describes a removal from a text buffer, retrieve 512203955Srdivacky * the source range that should be removed. 513203955Srdivacky * 514203955Srdivacky * \param Diagnostic the diagnostic whose fix-its are being queried. 515203955Srdivacky * 516203955Srdivacky * \param FixIt the zero-based index of the removal fix-it. 517203955Srdivacky * 518203955Srdivacky * \returns a source range describing the text that should be removed 519203955Srdivacky * from the buffer. 520203955Srdivacky */ 521203955SrdivackyCINDEX_LINKAGE CXSourceRange 522203955Srdivackyclang_getDiagnosticFixItRemoval(CXDiagnostic Diagnostic, unsigned FixIt); 523203955Srdivacky 524203955Srdivacky/** 525203955Srdivacky * \brief Retrieve the replacement information for an replacement fix-it. 526203955Srdivacky * 527203955Srdivacky * For a fix-it that describes replacement of text in the text buffer 528203955Srdivacky * with alternative text. 529203955Srdivacky * 530203955Srdivacky * \param Diagnostic the diagnostic whose fix-its are being queried. 531203955Srdivacky * 532203955Srdivacky * \param FixIt the zero-based index of the replacement fix-it. 533203955Srdivacky * 534203955Srdivacky * \param Range will be set to the source range whose text should be 535203955Srdivacky * replaced with the returned text. 536203955Srdivacky * 537203955Srdivacky * \returns the text string to use as replacement text. 538203955Srdivacky */ 539203955SrdivackyCINDEX_LINKAGE CXString 540203955Srdivackyclang_getDiagnosticFixItReplacement(CXDiagnostic Diagnostic, unsigned FixIt, 541203955Srdivacky CXSourceRange *Range); 542203955Srdivacky 543203955Srdivacky/** 544203955Srdivacky * @} 545203955Srdivacky */ 546203955Srdivacky 547203955Srdivacky/** 548203955Srdivacky * \defgroup CINDEX_TRANSLATION_UNIT Translation unit manipulation 549203955Srdivacky * 550203955Srdivacky * The routines in this group provide the ability to create and destroy 551203955Srdivacky * translation units from files, either by parsing the contents of the files or 552203955Srdivacky * by reading in a serialized representation of a translation unit. 553203955Srdivacky * 554203955Srdivacky * @{ 555203955Srdivacky */ 556203955Srdivacky 557203955Srdivacky/** 558203955Srdivacky * \brief Get the original translation unit source file name. 559203955Srdivacky */ 560203955SrdivackyCINDEX_LINKAGE CXString 561203955Srdivackyclang_getTranslationUnitSpelling(CXTranslationUnit CTUnit); 562203955Srdivacky 563203955Srdivacky/** 564203955Srdivacky * \brief Return the CXTranslationUnit for a given source file and the provided 565203955Srdivacky * command line arguments one would pass to the compiler. 566203955Srdivacky * 567203955Srdivacky * Note: The 'source_filename' argument is optional. If the caller provides a 568203955Srdivacky * NULL pointer, the name of the source file is expected to reside in the 569203955Srdivacky * specified command line arguments. 570203955Srdivacky * 571203955Srdivacky * Note: When encountered in 'clang_command_line_args', the following options 572203955Srdivacky * are ignored: 573203955Srdivacky * 574203955Srdivacky * '-c' 575203955Srdivacky * '-emit-ast' 576203955Srdivacky * '-fsyntax-only' 577203955Srdivacky * '-o <output file>' (both '-o' and '<output file>' are ignored) 578203955Srdivacky * 579203955Srdivacky * 580203955Srdivacky * \param source_filename - The name of the source file to load, or NULL if the 581203955Srdivacky * source file is included in clang_command_line_args. 582203955Srdivacky * 583203955Srdivacky * \param num_unsaved_files the number of unsaved file entries in \p 584203955Srdivacky * unsaved_files. 585203955Srdivacky * 586203955Srdivacky * \param unsaved_files the files that have not yet been saved to disk 587203955Srdivacky * but may be required for code completion, including the contents of 588203955Srdivacky * those files. 589203955Srdivacky * 590203955Srdivacky * \param diag_callback callback function that will receive any diagnostics 591203955Srdivacky * emitted while processing this source file. If NULL, diagnostics will be 592203955Srdivacky * suppressed. 593203955Srdivacky * 594203955Srdivacky * \param diag_client_data client data that will be passed to the diagnostic 595203955Srdivacky * callback function. 596203955Srdivacky */ 597203955SrdivackyCINDEX_LINKAGE CXTranslationUnit clang_createTranslationUnitFromSourceFile( 598203955Srdivacky CXIndex CIdx, 599203955Srdivacky const char *source_filename, 600203955Srdivacky int num_clang_command_line_args, 601203955Srdivacky const char **clang_command_line_args, 602203955Srdivacky unsigned num_unsaved_files, 603203955Srdivacky struct CXUnsavedFile *unsaved_files, 604203955Srdivacky CXDiagnosticCallback diag_callback, 605203955Srdivacky CXClientData diag_client_data); 606203955Srdivacky 607203955Srdivacky/** 608203955Srdivacky * \brief Create a translation unit from an AST file (-emit-ast). 609203955Srdivacky */ 610203955SrdivackyCINDEX_LINKAGE CXTranslationUnit clang_createTranslationUnit(CXIndex, 611203955Srdivacky const char *ast_filename, 612203955Srdivacky CXDiagnosticCallback diag_callback, 613203955Srdivacky CXClientData diag_client_data); 614203955Srdivacky 615203955Srdivacky/** 616203955Srdivacky * \brief Destroy the specified CXTranslationUnit object. 617203955Srdivacky */ 618203955SrdivackyCINDEX_LINKAGE void clang_disposeTranslationUnit(CXTranslationUnit); 619203955Srdivacky 620203955Srdivacky/** 621203955Srdivacky * @} 622203955Srdivacky */ 623203955Srdivacky 624203955Srdivacky/** 625202879Srdivacky * \brief Describes the kind of entity that a cursor refers to. 626202379Srdivacky */ 627202879Srdivackyenum CXCursorKind { 628202879Srdivacky /* Declarations */ 629202879Srdivacky CXCursor_FirstDecl = 1, 630203955Srdivacky /** 631202879Srdivacky * \brief A declaration whose specific kind is not exposed via this 632203955Srdivacky * interface. 633202879Srdivacky * 634202879Srdivacky * Unexposed declarations have the same operations as any other kind 635202879Srdivacky * of declaration; one can extract their location information, 636202879Srdivacky * spelling, find their definitions, etc. However, the specific kind 637202879Srdivacky * of the declaration is not reported. 638202879Srdivacky */ 639202879Srdivacky CXCursor_UnexposedDecl = 1, 640202879Srdivacky /** \brief A C or C++ struct. */ 641203955Srdivacky CXCursor_StructDecl = 2, 642202879Srdivacky /** \brief A C or C++ union. */ 643202879Srdivacky CXCursor_UnionDecl = 3, 644202879Srdivacky /** \brief A C++ class. */ 645202879Srdivacky CXCursor_ClassDecl = 4, 646202879Srdivacky /** \brief An enumeration. */ 647202879Srdivacky CXCursor_EnumDecl = 5, 648203955Srdivacky /** 649202879Srdivacky * \brief A field (in C) or non-static data member (in C++) in a 650202879Srdivacky * struct, union, or C++ class. 651202879Srdivacky */ 652202879Srdivacky CXCursor_FieldDecl = 6, 653202879Srdivacky /** \brief An enumerator constant. */ 654202879Srdivacky CXCursor_EnumConstantDecl = 7, 655202879Srdivacky /** \brief A function. */ 656202879Srdivacky CXCursor_FunctionDecl = 8, 657202879Srdivacky /** \brief A variable. */ 658202879Srdivacky CXCursor_VarDecl = 9, 659202879Srdivacky /** \brief A function or method parameter. */ 660202879Srdivacky CXCursor_ParmDecl = 10, 661202879Srdivacky /** \brief An Objective-C @interface. */ 662202879Srdivacky CXCursor_ObjCInterfaceDecl = 11, 663202879Srdivacky /** \brief An Objective-C @interface for a category. */ 664202879Srdivacky CXCursor_ObjCCategoryDecl = 12, 665202879Srdivacky /** \brief An Objective-C @protocol declaration. */ 666202879Srdivacky CXCursor_ObjCProtocolDecl = 13, 667202879Srdivacky /** \brief An Objective-C @property declaration. */ 668202879Srdivacky CXCursor_ObjCPropertyDecl = 14, 669202879Srdivacky /** \brief An Objective-C instance variable. */ 670202879Srdivacky CXCursor_ObjCIvarDecl = 15, 671202879Srdivacky /** \brief An Objective-C instance method. */ 672202879Srdivacky CXCursor_ObjCInstanceMethodDecl = 16, 673202879Srdivacky /** \brief An Objective-C class method. */ 674202879Srdivacky CXCursor_ObjCClassMethodDecl = 17, 675202879Srdivacky /** \brief An Objective-C @implementation. */ 676202879Srdivacky CXCursor_ObjCImplementationDecl = 18, 677202879Srdivacky /** \brief An Objective-C @implementation for a category. */ 678202879Srdivacky CXCursor_ObjCCategoryImplDecl = 19, 679202879Srdivacky /** \brief A typedef */ 680202879Srdivacky CXCursor_TypedefDecl = 20, 681202879Srdivacky CXCursor_LastDecl = 20, 682203955Srdivacky 683202879Srdivacky /* References */ 684202879Srdivacky CXCursor_FirstRef = 40, /* Decl references */ 685203955Srdivacky CXCursor_ObjCSuperClassRef = 40, 686202879Srdivacky CXCursor_ObjCProtocolRef = 41, 687202879Srdivacky CXCursor_ObjCClassRef = 42, 688202879Srdivacky /** 689202879Srdivacky * \brief A reference to a type declaration. 690202879Srdivacky * 691202879Srdivacky * A type reference occurs anywhere where a type is named but not 692202879Srdivacky * declared. For example, given: 693202879Srdivacky * 694202879Srdivacky * \code 695202879Srdivacky * typedef unsigned size_type; 696202879Srdivacky * size_type size; 697202879Srdivacky * \endcode 698202879Srdivacky * 699202879Srdivacky * The typedef is a declaration of size_type (CXCursor_TypedefDecl), 700202879Srdivacky * while the type of the variable "size" is referenced. The cursor 701202879Srdivacky * referenced by the type of size is the typedef for size_type. 702202879Srdivacky */ 703202879Srdivacky CXCursor_TypeRef = 43, 704202879Srdivacky CXCursor_LastRef = 43, 705203955Srdivacky 706202879Srdivacky /* Error conditions */ 707202879Srdivacky CXCursor_FirstInvalid = 70, 708202879Srdivacky CXCursor_InvalidFile = 70, 709202879Srdivacky CXCursor_NoDeclFound = 71, 710202879Srdivacky CXCursor_NotImplemented = 72, 711202879Srdivacky CXCursor_LastInvalid = 72, 712203955Srdivacky 713202879Srdivacky /* Expressions */ 714202879Srdivacky CXCursor_FirstExpr = 100, 715203955Srdivacky 716202879Srdivacky /** 717202879Srdivacky * \brief An expression whose specific kind is not exposed via this 718203955Srdivacky * interface. 719202879Srdivacky * 720202879Srdivacky * Unexposed expressions have the same operations as any other kind 721202879Srdivacky * of expression; one can extract their location information, 722202879Srdivacky * spelling, children, etc. However, the specific kind of the 723202879Srdivacky * expression is not reported. 724202879Srdivacky */ 725202879Srdivacky CXCursor_UnexposedExpr = 100, 726203955Srdivacky 727202879Srdivacky /** 728202879Srdivacky * \brief An expression that refers to some value declaration, such 729202879Srdivacky * as a function, varible, or enumerator. 730202879Srdivacky */ 731202879Srdivacky CXCursor_DeclRefExpr = 101, 732203955Srdivacky 733202879Srdivacky /** 734202879Srdivacky * \brief An expression that refers to a member of a struct, union, 735202879Srdivacky * class, Objective-C class, etc. 736202879Srdivacky */ 737202879Srdivacky CXCursor_MemberRefExpr = 102, 738203955Srdivacky 739202879Srdivacky /** \brief An expression that calls a function. */ 740202879Srdivacky CXCursor_CallExpr = 103, 741203955Srdivacky 742202879Srdivacky /** \brief An expression that sends a message to an Objective-C 743202879Srdivacky object or class. */ 744202879Srdivacky CXCursor_ObjCMessageExpr = 104, 745202879Srdivacky CXCursor_LastExpr = 104, 746203955Srdivacky 747202879Srdivacky /* Statements */ 748202879Srdivacky CXCursor_FirstStmt = 200, 749202879Srdivacky /** 750202879Srdivacky * \brief A statement whose specific kind is not exposed via this 751202879Srdivacky * interface. 752202879Srdivacky * 753202879Srdivacky * Unexposed statements have the same operations as any other kind of 754202879Srdivacky * statement; one can extract their location information, spelling, 755202879Srdivacky * children, etc. However, the specific kind of the statement is not 756202879Srdivacky * reported. 757202879Srdivacky */ 758202879Srdivacky CXCursor_UnexposedStmt = 200, 759202879Srdivacky CXCursor_LastStmt = 200, 760203955Srdivacky 761202879Srdivacky /** 762202879Srdivacky * \brief Cursor that represents the translation unit itself. 763202879Srdivacky * 764202879Srdivacky * The translation unit cursor exists primarily to act as the root 765202879Srdivacky * cursor for traversing the contents of a translation unit. 766202879Srdivacky */ 767202879Srdivacky CXCursor_TranslationUnit = 300 768202879Srdivacky}; 769202379Srdivacky 770202879Srdivacky/** 771202879Srdivacky * \brief A cursor representing some element in the abstract syntax tree for 772202879Srdivacky * a translation unit. 773202879Srdivacky * 774203955Srdivacky * The cursor abstraction unifies the different kinds of entities in a 775202879Srdivacky * program--declaration, statements, expressions, references to declarations, 776202879Srdivacky * etc.--under a single "cursor" abstraction with a common set of operations. 777202879Srdivacky * Common operation for a cursor include: getting the physical location in 778202879Srdivacky * a source file where the cursor points, getting the name associated with a 779202879Srdivacky * cursor, and retrieving cursors for any child nodes of a particular cursor. 780202879Srdivacky * 781202879Srdivacky * Cursors can be produced in two specific ways. 782202879Srdivacky * clang_getTranslationUnitCursor() produces a cursor for a translation unit, 783202879Srdivacky * from which one can use clang_visitChildren() to explore the rest of the 784202879Srdivacky * translation unit. clang_getCursor() maps from a physical source location 785202879Srdivacky * to the entity that resides at that location, allowing one to map from the 786202879Srdivacky * source code into the AST. 787198092Srdivacky */ 788202879Srdivackytypedef struct { 789202879Srdivacky enum CXCursorKind kind; 790202879Srdivacky void *data[3]; 791203955Srdivacky} CXCursor; 792202879Srdivacky 793198398Srdivacky/** 794202879Srdivacky * \defgroup CINDEX_CURSOR_MANIP Cursor manipulations 795202879Srdivacky * 796202879Srdivacky * @{ 797198398Srdivacky */ 798203955Srdivacky 799202879Srdivacky/** 800202879Srdivacky * \brief Retrieve the NULL cursor, which represents no entity. 801202879Srdivacky */ 802199482SrdivackyCINDEX_LINKAGE CXCursor clang_getNullCursor(void); 803203955Srdivacky 804202879Srdivacky/** 805202879Srdivacky * \brief Retrieve the cursor that represents the given translation unit. 806202879Srdivacky * 807202879Srdivacky * The translation unit cursor can be used to start traversing the 808202879Srdivacky * various declarations within the given translation unit. 809202879Srdivacky */ 810202879SrdivackyCINDEX_LINKAGE CXCursor clang_getTranslationUnitCursor(CXTranslationUnit); 811198092Srdivacky 812202879Srdivacky/** 813202879Srdivacky * \brief Determine whether two cursors are equivalent. 814202879Srdivacky */ 815202879SrdivackyCINDEX_LINKAGE unsigned clang_equalCursors(CXCursor, CXCursor); 816203955Srdivacky 817202879Srdivacky/** 818202879Srdivacky * \brief Retrieve the kind of the given cursor. 819202879Srdivacky */ 820198893SrdivackyCINDEX_LINKAGE enum CXCursorKind clang_getCursorKind(CXCursor); 821202879Srdivacky 822202879Srdivacky/** 823202879Srdivacky * \brief Determine whether the given cursor kind represents a declaration. 824202879Srdivacky */ 825198893SrdivackyCINDEX_LINKAGE unsigned clang_isDeclaration(enum CXCursorKind); 826202879Srdivacky 827202879Srdivacky/** 828202879Srdivacky * \brief Determine whether the given cursor kind represents a simple 829202879Srdivacky * reference. 830202879Srdivacky * 831202879Srdivacky * Note that other kinds of cursors (such as expressions) can also refer to 832202879Srdivacky * other cursors. Use clang_getCursorReferenced() to determine whether a 833202879Srdivacky * particular cursor refers to another entity. 834202879Srdivacky */ 835198893SrdivackyCINDEX_LINKAGE unsigned clang_isReference(enum CXCursorKind); 836202879Srdivacky 837202879Srdivacky/** 838202879Srdivacky * \brief Determine whether the given cursor kind represents an expression. 839202879Srdivacky */ 840202879SrdivackyCINDEX_LINKAGE unsigned clang_isExpression(enum CXCursorKind); 841202879Srdivacky 842202879Srdivacky/** 843202879Srdivacky * \brief Determine whether the given cursor kind represents a statement. 844202879Srdivacky */ 845202879SrdivackyCINDEX_LINKAGE unsigned clang_isStatement(enum CXCursorKind); 846202879Srdivacky 847202879Srdivacky/** 848203955Srdivacky * \brief Determine whether the given cursor kind represents an invalid 849202879Srdivacky * cursor. 850203955Srdivacky */ 851198893SrdivackyCINDEX_LINKAGE unsigned clang_isInvalid(enum CXCursorKind); 852198398Srdivacky 853202879Srdivacky/** 854203955Srdivacky * \brief Determine whether the given cursor kind represents a translation 855203955Srdivacky * unit. 856202879Srdivacky */ 857202879SrdivackyCINDEX_LINKAGE unsigned clang_isTranslationUnit(enum CXCursorKind); 858203955Srdivacky 859202879Srdivacky/** 860202879Srdivacky * @} 861202879Srdivacky */ 862203955Srdivacky 863202879Srdivacky/** 864202879Srdivacky * \defgroup CINDEX_CURSOR_SOURCE Mapping between cursors and source code 865202879Srdivacky * 866202879Srdivacky * Cursors represent a location within the Abstract Syntax Tree (AST). These 867202879Srdivacky * routines help map between cursors and the physical locations where the 868202879Srdivacky * described entities occur in the source code. The mapping is provided in 869202879Srdivacky * both directions, so one can map from source code to the AST and back. 870202879Srdivacky * 871202879Srdivacky * @{ 872202879Srdivacky */ 873203955Srdivacky 874202879Srdivacky/** 875202879Srdivacky * \brief Map a source location to the cursor that describes the entity at that 876202879Srdivacky * location in the source code. 877202879Srdivacky * 878202879Srdivacky * clang_getCursor() maps an arbitrary source location within a translation 879202879Srdivacky * unit down to the most specific cursor that describes the entity at that 880203955Srdivacky * location. For example, given an expression \c x + y, invoking 881202879Srdivacky * clang_getCursor() with a source location pointing to "x" will return the 882203955Srdivacky * cursor for "x"; similarly for "y". If the cursor points anywhere between 883202879Srdivacky * "x" or "y" (e.g., on the + or the whitespace around it), clang_getCursor() 884202879Srdivacky * will return a cursor referring to the "+" expression. 885202879Srdivacky * 886202879Srdivacky * \returns a cursor representing the entity at the given source location, or 887202879Srdivacky * a NULL cursor if no such entity can be found. 888202879Srdivacky */ 889202879SrdivackyCINDEX_LINKAGE CXCursor clang_getCursor(CXTranslationUnit, CXSourceLocation); 890203955Srdivacky 891202879Srdivacky/** 892202879Srdivacky * \brief Retrieve the physical location of the source constructor referenced 893202879Srdivacky * by the given cursor. 894202879Srdivacky * 895202879Srdivacky * The location of a declaration is typically the location of the name of that 896203955Srdivacky * declaration, where the name of that declaration would occur if it is 897203955Srdivacky * unnamed, or some keyword that introduces that particular declaration. 898203955Srdivacky * The location of a reference is where that reference occurs within the 899202879Srdivacky * source code. 900202879Srdivacky */ 901202879SrdivackyCINDEX_LINKAGE CXSourceLocation clang_getCursorLocation(CXCursor); 902199482Srdivacky 903202879Srdivacky/** 904202879Srdivacky * \brief Retrieve the physical extent of the source construct referenced by 905202879Srdivacky * the given cursor. 906202879Srdivacky * 907202879Srdivacky * The extent of a cursor starts with the file/line/column pointing at the 908202879Srdivacky * first character within the source construct that the cursor refers to and 909203955Srdivacky * ends with the last character withinin that source construct. For a 910202879Srdivacky * declaration, the extent covers the declaration itself. For a reference, 911202879Srdivacky * the extent covers the location of the reference (e.g., where the referenced 912202879Srdivacky * entity was actually used). 913202879Srdivacky */ 914202879SrdivackyCINDEX_LINKAGE CXSourceRange clang_getCursorExtent(CXCursor); 915202879Srdivacky 916202879Srdivacky/** 917202879Srdivacky * @} 918202879Srdivacky */ 919203955Srdivacky 920202879Srdivacky/** 921202879Srdivacky * \defgroup CINDEX_CURSOR_TRAVERSAL Traversing the AST with cursors 922202879Srdivacky * 923202879Srdivacky * These routines provide the ability to traverse the abstract syntax tree 924202879Srdivacky * using cursors. 925202879Srdivacky * 926202879Srdivacky * @{ 927202879Srdivacky */ 928203955Srdivacky 929202879Srdivacky/** 930202879Srdivacky * \brief Describes how the traversal of the children of a particular 931202879Srdivacky * cursor should proceed after visiting a particular child cursor. 932202879Srdivacky * 933202879Srdivacky * A value of this enumeration type should be returned by each 934202879Srdivacky * \c CXCursorVisitor to indicate how clang_visitChildren() proceed. 935202879Srdivacky */ 936202879Srdivackyenum CXChildVisitResult { 937202879Srdivacky /** 938203955Srdivacky * \brief Terminates the cursor traversal. 939202879Srdivacky */ 940202879Srdivacky CXChildVisit_Break, 941203955Srdivacky /** 942202879Srdivacky * \brief Continues the cursor traversal with the next sibling of 943202879Srdivacky * the cursor just visited, without visiting its children. 944202879Srdivacky */ 945202879Srdivacky CXChildVisit_Continue, 946202879Srdivacky /** 947202879Srdivacky * \brief Recursively traverse the children of this cursor, using 948202879Srdivacky * the same visitor and client data. 949202879Srdivacky */ 950202879Srdivacky CXChildVisit_Recurse 951202879Srdivacky}; 952202879Srdivacky 953202879Srdivacky/** 954202879Srdivacky * \brief Visitor invoked for each cursor found by a traversal. 955202879Srdivacky * 956202879Srdivacky * This visitor function will be invoked for each cursor found by 957202879Srdivacky * clang_visitCursorChildren(). Its first argument is the cursor being 958202879Srdivacky * visited, its second argument is the parent visitor for that cursor, 959202879Srdivacky * and its third argument is the client data provided to 960202879Srdivacky * clang_visitCursorChildren(). 961202879Srdivacky * 962202879Srdivacky * The visitor should return one of the \c CXChildVisitResult values 963202879Srdivacky * to direct clang_visitCursorChildren(). 964202879Srdivacky */ 965203955Srdivackytypedef enum CXChildVisitResult (*CXCursorVisitor)(CXCursor cursor, 966203955Srdivacky CXCursor parent, 967202879Srdivacky CXClientData client_data); 968202879Srdivacky 969202879Srdivacky/** 970202879Srdivacky * \brief Visit the children of a particular cursor. 971202879Srdivacky * 972202879Srdivacky * This function visits all the direct children of the given cursor, 973202879Srdivacky * invoking the given \p visitor function with the cursors of each 974202879Srdivacky * visited child. The traversal may be recursive, if the visitor returns 975202879Srdivacky * \c CXChildVisit_Recurse. The traversal may also be ended prematurely, if 976202879Srdivacky * the visitor returns \c CXChildVisit_Break. 977202879Srdivacky * 978202879Srdivacky * \param parent the cursor whose child may be visited. All kinds of 979203955Srdivacky * cursors can be visited, including invalid cursors (which, by 980202879Srdivacky * definition, have no children). 981202879Srdivacky * 982202879Srdivacky * \param visitor the visitor function that will be invoked for each 983202879Srdivacky * child of \p parent. 984202879Srdivacky * 985202879Srdivacky * \param client_data pointer data supplied by the client, which will 986202879Srdivacky * be passed to the visitor each time it is invoked. 987202879Srdivacky * 988202879Srdivacky * \returns a non-zero value if the traversal was terminated 989202879Srdivacky * prematurely by the visitor returning \c CXChildVisit_Break. 990202879Srdivacky */ 991203955SrdivackyCINDEX_LINKAGE unsigned clang_visitChildren(CXCursor parent, 992202879Srdivacky CXCursorVisitor visitor, 993202879Srdivacky CXClientData client_data); 994203955Srdivacky 995202879Srdivacky/** 996202879Srdivacky * @} 997202879Srdivacky */ 998203955Srdivacky 999202879Srdivacky/** 1000202879Srdivacky * \defgroup CINDEX_CURSOR_XREF Cross-referencing in the AST 1001202879Srdivacky * 1002203955Srdivacky * These routines provide the ability to determine references within and 1003202879Srdivacky * across translation units, by providing the names of the entities referenced 1004202879Srdivacky * by cursors, follow reference cursors to the declarations they reference, 1005202879Srdivacky * and associate declarations with their definitions. 1006202879Srdivacky * 1007202879Srdivacky * @{ 1008202879Srdivacky */ 1009203955Srdivacky 1010202879Srdivacky/** 1011202879Srdivacky * \brief Retrieve a Unified Symbol Resolution (USR) for the entity referenced 1012202879Srdivacky * by the given cursor. 1013202879Srdivacky * 1014202879Srdivacky * A Unified Symbol Resolution (USR) is a string that identifies a particular 1015202879Srdivacky * entity (function, class, variable, etc.) within a program. USRs can be 1016202879Srdivacky * compared across translation units to determine, e.g., when references in 1017202879Srdivacky * one translation refer to an entity defined in another translation unit. 1018202879Srdivacky */ 1019202879SrdivackyCINDEX_LINKAGE CXString clang_getCursorUSR(CXCursor); 1020202879Srdivacky 1021202879Srdivacky/** 1022202879Srdivacky * \brief Retrieve a name for the entity referenced by this cursor. 1023202879Srdivacky */ 1024199482SrdivackyCINDEX_LINKAGE CXString clang_getCursorSpelling(CXCursor); 1025198398Srdivacky 1026202879Srdivacky/** \brief For a cursor that is a reference, retrieve a cursor representing the 1027202879Srdivacky * entity that it references. 1028202879Srdivacky * 1029202879Srdivacky * Reference cursors refer to other entities in the AST. For example, an 1030202879Srdivacky * Objective-C superclass reference cursor refers to an Objective-C class. 1031203955Srdivacky * This function produces the cursor for the Objective-C class from the 1032202879Srdivacky * cursor for the superclass reference. If the input cursor is a declaration or 1033202879Srdivacky * definition, it returns that declaration or definition unchanged. 1034203955Srdivacky * Otherwise, returns the NULL cursor. 1035202879Srdivacky */ 1036202879SrdivackyCINDEX_LINKAGE CXCursor clang_getCursorReferenced(CXCursor); 1037202879Srdivacky 1038203955Srdivacky/** 1039202879Srdivacky * \brief For a cursor that is either a reference to or a declaration 1040202879Srdivacky * of some entity, retrieve a cursor that describes the definition of 1041202879Srdivacky * that entity. 1042202879Srdivacky * 1043202879Srdivacky * Some entities can be declared multiple times within a translation 1044202879Srdivacky * unit, but only one of those declarations can also be a 1045202879Srdivacky * definition. For example, given: 1046202879Srdivacky * 1047202879Srdivacky * \code 1048202879Srdivacky * int f(int, int); 1049202879Srdivacky * int g(int x, int y) { return f(x, y); } 1050202879Srdivacky * int f(int a, int b) { return a + b; } 1051202879Srdivacky * int f(int, int); 1052202879Srdivacky * \endcode 1053202879Srdivacky * 1054202879Srdivacky * there are three declarations of the function "f", but only the 1055202879Srdivacky * second one is a definition. The clang_getCursorDefinition() 1056202879Srdivacky * function will take any cursor pointing to a declaration of "f" 1057202879Srdivacky * (the first or fourth lines of the example) or a cursor referenced 1058202879Srdivacky * that uses "f" (the call to "f' inside "g") and will return a 1059202879Srdivacky * declaration cursor pointing to the definition (the second "f" 1060202879Srdivacky * declaration). 1061202879Srdivacky * 1062202879Srdivacky * If given a cursor for which there is no corresponding definition, 1063202879Srdivacky * e.g., because there is no definition of that entity within this 1064202879Srdivacky * translation unit, returns a NULL cursor. 1065202879Srdivacky */ 1066202879SrdivackyCINDEX_LINKAGE CXCursor clang_getCursorDefinition(CXCursor); 1067202879Srdivacky 1068203955Srdivacky/** 1069202879Srdivacky * \brief Determine whether the declaration pointed to by this cursor 1070202879Srdivacky * is also a definition of that entity. 1071202879Srdivacky */ 1072202879SrdivackyCINDEX_LINKAGE unsigned clang_isCursorDefinition(CXCursor); 1073202879Srdivacky 1074202879Srdivacky/** 1075202879Srdivacky * @} 1076202879Srdivacky */ 1077203955Srdivacky 1078203955Srdivacky/** 1079203955Srdivacky * \defgroup CINDEX_LEX Token extraction and manipulation 1080203955Srdivacky * 1081203955Srdivacky * The routines in this group provide access to the tokens within a 1082203955Srdivacky * translation unit, along with a semantic mapping of those tokens to 1083203955Srdivacky * their corresponding cursors. 1084203955Srdivacky * 1085203955Srdivacky * @{ 1086203955Srdivacky */ 1087203955Srdivacky 1088203955Srdivacky/** 1089203955Srdivacky * \brief Describes a kind of token. 1090203955Srdivacky */ 1091203955Srdivackytypedef enum CXTokenKind { 1092203955Srdivacky /** 1093203955Srdivacky * \brief A token that contains some kind of punctuation. 1094203955Srdivacky */ 1095203955Srdivacky CXToken_Punctuation, 1096202879Srdivacky 1097203955Srdivacky /** 1098203955Srdivacky * \brief A language keyword. 1099203955Srdivacky */ 1100203955Srdivacky CXToken_Keyword, 1101203955Srdivacky 1102203955Srdivacky /** 1103203955Srdivacky * \brief An identifier (that is not a keyword). 1104203955Srdivacky */ 1105203955Srdivacky CXToken_Identifier, 1106203955Srdivacky 1107203955Srdivacky /** 1108203955Srdivacky * \brief A numeric, string, or character literal. 1109203955Srdivacky */ 1110203955Srdivacky CXToken_Literal, 1111203955Srdivacky 1112203955Srdivacky /** 1113203955Srdivacky * \brief A comment. 1114203955Srdivacky */ 1115203955Srdivacky CXToken_Comment 1116203955Srdivacky} CXTokenKind; 1117203955Srdivacky 1118202879Srdivacky/** 1119203955Srdivacky * \brief Describes a single preprocessing token. 1120203955Srdivacky */ 1121203955Srdivackytypedef struct { 1122203955Srdivacky unsigned int_data[4]; 1123203955Srdivacky void *ptr_data; 1124203955Srdivacky} CXToken; 1125203955Srdivacky 1126203955Srdivacky/** 1127203955Srdivacky * \brief Determine the kind of the given token. 1128203955Srdivacky */ 1129203955SrdivackyCINDEX_LINKAGE CXTokenKind clang_getTokenKind(CXToken); 1130203955Srdivacky 1131203955Srdivacky/** 1132203955Srdivacky * \brief Determine the spelling of the given token. 1133203955Srdivacky * 1134203955Srdivacky * The spelling of a token is the textual representation of that token, e.g., 1135203955Srdivacky * the text of an identifier or keyword. 1136203955Srdivacky */ 1137203955SrdivackyCINDEX_LINKAGE CXString clang_getTokenSpelling(CXTranslationUnit, CXToken); 1138203955Srdivacky 1139203955Srdivacky/** 1140203955Srdivacky * \brief Retrieve the source location of the given token. 1141203955Srdivacky */ 1142203955SrdivackyCINDEX_LINKAGE CXSourceLocation clang_getTokenLocation(CXTranslationUnit, 1143203955Srdivacky CXToken); 1144203955Srdivacky 1145203955Srdivacky/** 1146203955Srdivacky * \brief Retrieve a source range that covers the given token. 1147203955Srdivacky */ 1148203955SrdivackyCINDEX_LINKAGE CXSourceRange clang_getTokenExtent(CXTranslationUnit, CXToken); 1149203955Srdivacky 1150203955Srdivacky/** 1151203955Srdivacky * \brief Tokenize the source code described by the given range into raw 1152203955Srdivacky * lexical tokens. 1153203955Srdivacky * 1154203955Srdivacky * \param TU the translation unit whose text is being tokenized. 1155203955Srdivacky * 1156203955Srdivacky * \param Range the source range in which text should be tokenized. All of the 1157203955Srdivacky * tokens produced by tokenization will fall within this source range, 1158203955Srdivacky * 1159203955Srdivacky * \param Tokens this pointer will be set to point to the array of tokens 1160203955Srdivacky * that occur within the given source range. The returned pointer must be 1161203955Srdivacky * freed with clang_disposeTokens() before the translation unit is destroyed. 1162203955Srdivacky * 1163203955Srdivacky * \param NumTokens will be set to the number of tokens in the \c *Tokens 1164203955Srdivacky * array. 1165203955Srdivacky * 1166203955Srdivacky */ 1167203955SrdivackyCINDEX_LINKAGE void clang_tokenize(CXTranslationUnit TU, CXSourceRange Range, 1168203955Srdivacky CXToken **Tokens, unsigned *NumTokens); 1169203955Srdivacky 1170203955Srdivacky/** 1171203955Srdivacky * \brief Annotate the given set of tokens by providing cursors for each token 1172203955Srdivacky * that can be mapped to a specific entity within the abstract syntax tree. 1173203955Srdivacky * 1174203955Srdivacky * This token-annotation routine is equivalent to invoking 1175203955Srdivacky * clang_getCursor() for the source locations of each of the 1176203955Srdivacky * tokens. The cursors provided are filtered, so that only those 1177203955Srdivacky * cursors that have a direct correspondence to the token are 1178203955Srdivacky * accepted. For example, given a function call \c f(x), 1179203955Srdivacky * clang_getCursor() would provide the following cursors: 1180203955Srdivacky * 1181203955Srdivacky * * when the cursor is over the 'f', a DeclRefExpr cursor referring to 'f'. 1182203955Srdivacky * * when the cursor is over the '(' or the ')', a CallExpr referring to 'f'. 1183203955Srdivacky * * when the cursor is over the 'x', a DeclRefExpr cursor referring to 'x'. 1184203955Srdivacky * 1185203955Srdivacky * Only the first and last of these cursors will occur within the 1186203955Srdivacky * annotate, since the tokens "f" and "x' directly refer to a function 1187203955Srdivacky * and a variable, respectively, but the parentheses are just a small 1188203955Srdivacky * part of the full syntax of the function call expression, which is 1189203955Srdivacky * not provided as an annotation. 1190203955Srdivacky * 1191203955Srdivacky * \param TU the translation unit that owns the given tokens. 1192203955Srdivacky * 1193203955Srdivacky * \param Tokens the set of tokens to annotate. 1194203955Srdivacky * 1195203955Srdivacky * \param NumTokens the number of tokens in \p Tokens. 1196203955Srdivacky * 1197203955Srdivacky * \param Cursors an array of \p NumTokens cursors, whose contents will be 1198203955Srdivacky * replaced with the cursors corresponding to each token. 1199203955Srdivacky */ 1200203955SrdivackyCINDEX_LINKAGE void clang_annotateTokens(CXTranslationUnit TU, 1201203955Srdivacky CXToken *Tokens, unsigned NumTokens, 1202203955Srdivacky CXCursor *Cursors); 1203203955Srdivacky 1204203955Srdivacky/** 1205203955Srdivacky * \brief Free the given set of tokens. 1206203955Srdivacky */ 1207203955SrdivackyCINDEX_LINKAGE void clang_disposeTokens(CXTranslationUnit TU, 1208203955Srdivacky CXToken *Tokens, unsigned NumTokens); 1209203955Srdivacky 1210203955Srdivacky/** 1211203955Srdivacky * @} 1212203955Srdivacky */ 1213203955Srdivacky 1214203955Srdivacky/** 1215202879Srdivacky * \defgroup CINDEX_DEBUG Debugging facilities 1216202879Srdivacky * 1217202879Srdivacky * These routines are used for testing and debugging, only, and should not 1218202879Srdivacky * be relied upon. 1219202879Srdivacky * 1220202879Srdivacky * @{ 1221202879Srdivacky */ 1222203955Srdivacky 1223198092Srdivacky/* for debug/testing */ 1224203955SrdivackyCINDEX_LINKAGE const char *clang_getCursorKindSpelling(enum CXCursorKind Kind); 1225203955SrdivackyCINDEX_LINKAGE void clang_getDefinitionSpellingAndExtent(CXCursor, 1226203955Srdivacky const char **startBuf, 1227198092Srdivacky const char **endBuf, 1228198092Srdivacky unsigned *startLine, 1229198092Srdivacky unsigned *startColumn, 1230198092Srdivacky unsigned *endLine, 1231198092Srdivacky unsigned *endColumn); 1232198092Srdivacky 1233202879Srdivacky/** 1234202879Srdivacky * @} 1235198092Srdivacky */ 1236203955Srdivacky 1237199482Srdivacky/** 1238202879Srdivacky * \defgroup CINDEX_CODE_COMPLET Code completion 1239202879Srdivacky * 1240202879Srdivacky * Code completion involves taking an (incomplete) source file, along with 1241202879Srdivacky * knowledge of where the user is actively editing that file, and suggesting 1242202879Srdivacky * syntactically- and semantically-valid constructs that the user might want to 1243202879Srdivacky * use at that particular point in the source code. These data structures and 1244202879Srdivacky * routines provide support for code completion. 1245202879Srdivacky * 1246202879Srdivacky * @{ 1247202879Srdivacky */ 1248203955Srdivacky 1249202879Srdivacky/** 1250199482Srdivacky * \brief A semantic string that describes a code-completion result. 1251199482Srdivacky * 1252199482Srdivacky * A semantic string that describes the formatting of a code-completion 1253199482Srdivacky * result as a single "template" of text that should be inserted into the 1254199482Srdivacky * source buffer when a particular code-completion result is selected. 1255199482Srdivacky * Each semantic string is made up of some number of "chunks", each of which 1256199482Srdivacky * contains some text along with a description of what that text means, e.g., 1257199482Srdivacky * the name of the entity being referenced, whether the text chunk is part of 1258199482Srdivacky * the template, or whether it is a "placeholder" that the user should replace 1259199482Srdivacky * with actual code,of a specific kind. See \c CXCompletionChunkKind for a 1260203955Srdivacky * description of the different kinds of chunks. 1261199482Srdivacky */ 1262199482Srdivackytypedef void *CXCompletionString; 1263203955Srdivacky 1264199482Srdivacky/** 1265199482Srdivacky * \brief A single result of code completion. 1266199482Srdivacky */ 1267199482Srdivackytypedef struct { 1268199482Srdivacky /** 1269203955Srdivacky * \brief The kind of entity that this completion refers to. 1270199482Srdivacky * 1271203955Srdivacky * The cursor kind will be a macro, keyword, or a declaration (one of the 1272199482Srdivacky * *Decl cursor kinds), describing the entity that the completion is 1273199482Srdivacky * referring to. 1274199482Srdivacky * 1275199482Srdivacky * \todo In the future, we would like to provide a full cursor, to allow 1276199482Srdivacky * the client to extract additional information from declaration. 1277199482Srdivacky */ 1278199482Srdivacky enum CXCursorKind CursorKind; 1279203955Srdivacky 1280203955Srdivacky /** 1281199482Srdivacky * \brief The code-completion string that describes how to insert this 1282199482Srdivacky * code-completion result into the editing buffer. 1283199482Srdivacky */ 1284199482Srdivacky CXCompletionString CompletionString; 1285199482Srdivacky} CXCompletionResult; 1286199482Srdivacky 1287199482Srdivacky/** 1288199482Srdivacky * \brief Describes a single piece of text within a code-completion string. 1289199482Srdivacky * 1290203955Srdivacky * Each "chunk" within a code-completion string (\c CXCompletionString) is 1291203955Srdivacky * either a piece of text with a specific "kind" that describes how that text 1292199482Srdivacky * should be interpreted by the client or is another completion string. 1293199482Srdivacky */ 1294199482Srdivackyenum CXCompletionChunkKind { 1295199482Srdivacky /** 1296199482Srdivacky * \brief A code-completion string that describes "optional" text that 1297199482Srdivacky * could be a part of the template (but is not required). 1298199482Srdivacky * 1299199482Srdivacky * The Optional chunk is the only kind of chunk that has a code-completion 1300203955Srdivacky * string for its representation, which is accessible via 1301199482Srdivacky * \c clang_getCompletionChunkCompletionString(). The code-completion string 1302199482Srdivacky * describes an additional part of the template that is completely optional. 1303199482Srdivacky * For example, optional chunks can be used to describe the placeholders for 1304199482Srdivacky * arguments that match up with defaulted function parameters, e.g. given: 1305199482Srdivacky * 1306199482Srdivacky * \code 1307199482Srdivacky * void f(int x, float y = 3.14, double z = 2.71828); 1308199482Srdivacky * \endcode 1309199482Srdivacky * 1310199482Srdivacky * The code-completion string for this function would contain: 1311199482Srdivacky * - a TypedText chunk for "f". 1312199482Srdivacky * - a LeftParen chunk for "(". 1313199482Srdivacky * - a Placeholder chunk for "int x" 1314199482Srdivacky * - an Optional chunk containing the remaining defaulted arguments, e.g., 1315199482Srdivacky * - a Comma chunk for "," 1316199482Srdivacky * - a Placeholder chunk for "float x" 1317199482Srdivacky * - an Optional chunk containing the last defaulted argument: 1318199482Srdivacky * - a Comma chunk for "," 1319199482Srdivacky * - a Placeholder chunk for "double z" 1320199482Srdivacky * - a RightParen chunk for ")" 1321199482Srdivacky * 1322199482Srdivacky * There are many ways two handle Optional chunks. Two simple approaches are: 1323199482Srdivacky * - Completely ignore optional chunks, in which case the template for the 1324199482Srdivacky * function "f" would only include the first parameter ("int x"). 1325199482Srdivacky * - Fully expand all optional chunks, in which case the template for the 1326199482Srdivacky * function "f" would have all of the parameters. 1327199482Srdivacky */ 1328199482Srdivacky CXCompletionChunk_Optional, 1329199482Srdivacky /** 1330199482Srdivacky * \brief Text that a user would be expected to type to get this 1331203955Srdivacky * code-completion result. 1332199482Srdivacky * 1333203955Srdivacky * There will be exactly one "typed text" chunk in a semantic string, which 1334203955Srdivacky * will typically provide the spelling of a keyword or the name of a 1335199482Srdivacky * declaration that could be used at the current code point. Clients are 1336199482Srdivacky * expected to filter the code-completion results based on the text in this 1337199482Srdivacky * chunk. 1338199482Srdivacky */ 1339199482Srdivacky CXCompletionChunk_TypedText, 1340199482Srdivacky /** 1341199482Srdivacky * \brief Text that should be inserted as part of a code-completion result. 1342199482Srdivacky * 1343199482Srdivacky * A "text" chunk represents text that is part of the template to be 1344199482Srdivacky * inserted into user code should this particular code-completion result 1345199482Srdivacky * be selected. 1346199482Srdivacky */ 1347199482Srdivacky CXCompletionChunk_Text, 1348199482Srdivacky /** 1349199482Srdivacky * \brief Placeholder text that should be replaced by the user. 1350199482Srdivacky * 1351199482Srdivacky * A "placeholder" chunk marks a place where the user should insert text 1352199482Srdivacky * into the code-completion template. For example, placeholders might mark 1353199482Srdivacky * the function parameters for a function declaration, to indicate that the 1354199482Srdivacky * user should provide arguments for each of those parameters. The actual 1355199482Srdivacky * text in a placeholder is a suggestion for the text to display before 1356199482Srdivacky * the user replaces the placeholder with real code. 1357199482Srdivacky */ 1358199482Srdivacky CXCompletionChunk_Placeholder, 1359199482Srdivacky /** 1360199482Srdivacky * \brief Informative text that should be displayed but never inserted as 1361199482Srdivacky * part of the template. 1362203955Srdivacky * 1363199482Srdivacky * An "informative" chunk contains annotations that can be displayed to 1364199482Srdivacky * help the user decide whether a particular code-completion result is the 1365199482Srdivacky * right option, but which is not part of the actual template to be inserted 1366199482Srdivacky * by code completion. 1367199482Srdivacky */ 1368199482Srdivacky CXCompletionChunk_Informative, 1369199482Srdivacky /** 1370199482Srdivacky * \brief Text that describes the current parameter when code-completion is 1371199482Srdivacky * referring to function call, message send, or template specialization. 1372199482Srdivacky * 1373199482Srdivacky * A "current parameter" chunk occurs when code-completion is providing 1374199482Srdivacky * information about a parameter corresponding to the argument at the 1375199482Srdivacky * code-completion point. For example, given a function 1376199482Srdivacky * 1377199482Srdivacky * \code 1378199482Srdivacky * int add(int x, int y); 1379199482Srdivacky * \endcode 1380199482Srdivacky * 1381199482Srdivacky * and the source code \c add(, where the code-completion point is after the 1382199482Srdivacky * "(", the code-completion string will contain a "current parameter" chunk 1383199482Srdivacky * for "int x", indicating that the current argument will initialize that 1384199482Srdivacky * parameter. After typing further, to \c add(17, (where the code-completion 1385203955Srdivacky * point is after the ","), the code-completion string will contain a 1386199482Srdivacky * "current paremeter" chunk to "int y". 1387199482Srdivacky */ 1388199482Srdivacky CXCompletionChunk_CurrentParameter, 1389199482Srdivacky /** 1390199482Srdivacky * \brief A left parenthesis ('('), used to initiate a function call or 1391199482Srdivacky * signal the beginning of a function parameter list. 1392199482Srdivacky */ 1393199482Srdivacky CXCompletionChunk_LeftParen, 1394199482Srdivacky /** 1395199482Srdivacky * \brief A right parenthesis (')'), used to finish a function call or 1396199482Srdivacky * signal the end of a function parameter list. 1397199482Srdivacky */ 1398199482Srdivacky CXCompletionChunk_RightParen, 1399199482Srdivacky /** 1400199482Srdivacky * \brief A left bracket ('['). 1401199482Srdivacky */ 1402199482Srdivacky CXCompletionChunk_LeftBracket, 1403199482Srdivacky /** 1404199482Srdivacky * \brief A right bracket (']'). 1405199482Srdivacky */ 1406199482Srdivacky CXCompletionChunk_RightBracket, 1407199482Srdivacky /** 1408199482Srdivacky * \brief A left brace ('{'). 1409199482Srdivacky */ 1410199482Srdivacky CXCompletionChunk_LeftBrace, 1411199482Srdivacky /** 1412199482Srdivacky * \brief A right brace ('}'). 1413199482Srdivacky */ 1414199482Srdivacky CXCompletionChunk_RightBrace, 1415199482Srdivacky /** 1416199482Srdivacky * \brief A left angle bracket ('<'). 1417199482Srdivacky */ 1418199482Srdivacky CXCompletionChunk_LeftAngle, 1419199482Srdivacky /** 1420199482Srdivacky * \brief A right angle bracket ('>'). 1421199482Srdivacky */ 1422199482Srdivacky CXCompletionChunk_RightAngle, 1423199482Srdivacky /** 1424199482Srdivacky * \brief A comma separator (','). 1425199482Srdivacky */ 1426201361Srdivacky CXCompletionChunk_Comma, 1427201361Srdivacky /** 1428203955Srdivacky * \brief Text that specifies the result type of a given result. 1429201361Srdivacky * 1430201361Srdivacky * This special kind of informative chunk is not meant to be inserted into 1431203955Srdivacky * the text buffer. Rather, it is meant to illustrate the type that an 1432201361Srdivacky * expression using the given completion string would have. 1433201361Srdivacky */ 1434202379Srdivacky CXCompletionChunk_ResultType, 1435202379Srdivacky /** 1436202379Srdivacky * \brief A colon (':'). 1437202379Srdivacky */ 1438202379Srdivacky CXCompletionChunk_Colon, 1439202379Srdivacky /** 1440202379Srdivacky * \brief A semicolon (';'). 1441202379Srdivacky */ 1442202379Srdivacky CXCompletionChunk_SemiColon, 1443202379Srdivacky /** 1444202379Srdivacky * \brief An '=' sign. 1445202379Srdivacky */ 1446202379Srdivacky CXCompletionChunk_Equal, 1447202379Srdivacky /** 1448202379Srdivacky * Horizontal space (' '). 1449202379Srdivacky */ 1450202379Srdivacky CXCompletionChunk_HorizontalSpace, 1451202379Srdivacky /** 1452202379Srdivacky * Vertical space ('\n'), after which it is generally a good idea to 1453202379Srdivacky * perform indentation. 1454202379Srdivacky */ 1455202379Srdivacky CXCompletionChunk_VerticalSpace 1456199482Srdivacky}; 1457203955Srdivacky 1458199482Srdivacky/** 1459199482Srdivacky * \brief Determine the kind of a particular chunk within a completion string. 1460199482Srdivacky * 1461199482Srdivacky * \param completion_string the completion string to query. 1462199482Srdivacky * 1463199482Srdivacky * \param chunk_number the 0-based index of the chunk in the completion string. 1464199482Srdivacky * 1465199482Srdivacky * \returns the kind of the chunk at the index \c chunk_number. 1466199482Srdivacky */ 1467203955SrdivackyCINDEX_LINKAGE enum CXCompletionChunkKind 1468199482Srdivackyclang_getCompletionChunkKind(CXCompletionString completion_string, 1469199482Srdivacky unsigned chunk_number); 1470203955Srdivacky 1471199482Srdivacky/** 1472203955Srdivacky * \brief Retrieve the text associated with a particular chunk within a 1473199482Srdivacky * completion string. 1474199482Srdivacky * 1475199482Srdivacky * \param completion_string the completion string to query. 1476199482Srdivacky * 1477199482Srdivacky * \param chunk_number the 0-based index of the chunk in the completion string. 1478199482Srdivacky * 1479199482Srdivacky * \returns the text associated with the chunk at index \c chunk_number. 1480199482Srdivacky */ 1481199482SrdivackyCINDEX_LINKAGE const char * 1482199482Srdivackyclang_getCompletionChunkText(CXCompletionString completion_string, 1483199482Srdivacky unsigned chunk_number); 1484199482Srdivacky 1485199482Srdivacky/** 1486203955Srdivacky * \brief Retrieve the completion string associated with a particular chunk 1487199482Srdivacky * within a completion string. 1488199482Srdivacky * 1489199482Srdivacky * \param completion_string the completion string to query. 1490199482Srdivacky * 1491199482Srdivacky * \param chunk_number the 0-based index of the chunk in the completion string. 1492199482Srdivacky * 1493199482Srdivacky * \returns the completion string associated with the chunk at index 1494199482Srdivacky * \c chunk_number, or NULL if that chunk is not represented by a completion 1495199482Srdivacky * string. 1496199482Srdivacky */ 1497199482SrdivackyCINDEX_LINKAGE CXCompletionString 1498199482Srdivackyclang_getCompletionChunkCompletionString(CXCompletionString completion_string, 1499199482Srdivacky unsigned chunk_number); 1500203955Srdivacky 1501199482Srdivacky/** 1502199482Srdivacky * \brief Retrieve the number of chunks in the given code-completion string. 1503199482Srdivacky */ 1504199482SrdivackyCINDEX_LINKAGE unsigned 1505199482Srdivackyclang_getNumCompletionChunks(CXCompletionString completion_string); 1506199482Srdivacky 1507199482Srdivacky/** 1508201361Srdivacky * \brief Contains the results of code-completion. 1509201361Srdivacky * 1510201361Srdivacky * This data structure contains the results of code completion, as 1511203955Srdivacky * produced by \c clang_codeComplete. Its contents must be freed by 1512201361Srdivacky * \c clang_disposeCodeCompleteResults. 1513201361Srdivacky */ 1514201361Srdivackytypedef struct { 1515201361Srdivacky /** 1516201361Srdivacky * \brief The code-completion results. 1517201361Srdivacky */ 1518201361Srdivacky CXCompletionResult *Results; 1519201361Srdivacky 1520201361Srdivacky /** 1521201361Srdivacky * \brief The number of code-completion results stored in the 1522201361Srdivacky * \c Results array. 1523201361Srdivacky */ 1524201361Srdivacky unsigned NumResults; 1525201361Srdivacky} CXCodeCompleteResults; 1526201361Srdivacky 1527201361Srdivacky/** 1528199482Srdivacky * \brief Perform code completion at a given location in a source file. 1529199482Srdivacky * 1530199482Srdivacky * This function performs code completion at a particular file, line, and 1531199482Srdivacky * column within source code, providing results that suggest potential 1532199482Srdivacky * code snippets based on the context of the completion. The basic model 1533199482Srdivacky * for code completion is that Clang will parse a complete source file, 1534199482Srdivacky * performing syntax checking up to the location where code-completion has 1535199482Srdivacky * been requested. At that point, a special code-completion token is passed 1536199482Srdivacky * to the parser, which recognizes this token and determines, based on the 1537203955Srdivacky * current location in the C/Objective-C/C++ grammar and the state of 1538199482Srdivacky * semantic analysis, what completions to provide. These completions are 1539201361Srdivacky * returned via a new \c CXCodeCompleteResults structure. 1540199482Srdivacky * 1541199482Srdivacky * Code completion itself is meant to be triggered by the client when the 1542203955Srdivacky * user types punctuation characters or whitespace, at which point the 1543199482Srdivacky * code-completion location will coincide with the cursor. For example, if \c p 1544199482Srdivacky * is a pointer, code-completion might be triggered after the "-" and then 1545199482Srdivacky * after the ">" in \c p->. When the code-completion location is afer the ">", 1546199482Srdivacky * the completion results will provide, e.g., the members of the struct that 1547199482Srdivacky * "p" points to. The client is responsible for placing the cursor at the 1548199482Srdivacky * beginning of the token currently being typed, then filtering the results 1549199482Srdivacky * based on the contents of the token. For example, when code-completing for 1550199482Srdivacky * the expression \c p->get, the client should provide the location just after 1551199482Srdivacky * the ">" (e.g., pointing at the "g") to this code-completion hook. Then, the 1552199482Srdivacky * client can filter the results based on the current token text ("get"), only 1553199482Srdivacky * showing those results that start with "get". The intent of this interface 1554201361Srdivacky * is to separate the relatively high-latency acquisition of code-completion 1555199482Srdivacky * results from the filtering of results on a per-character basis, which must 1556199482Srdivacky * have a lower latency. 1557199482Srdivacky * 1558199482Srdivacky * \param CIdx the \c CXIndex instance that will be used to perform code 1559199482Srdivacky * completion. 1560199482Srdivacky * 1561200583Srdivacky * \param source_filename the name of the source file that should be parsed to 1562200583Srdivacky * perform code-completion. This source file must be the same as or include the 1563200583Srdivacky * filename described by \p complete_filename, or no code-completion results 1564200583Srdivacky * will be produced. NOTE: One can also specify NULL for this argument if the 1565200583Srdivacky * source file is included in command_line_args. 1566199482Srdivacky * 1567199482Srdivacky * \param num_command_line_args the number of command-line arguments stored in 1568199482Srdivacky * \p command_line_args. 1569199482Srdivacky * 1570199482Srdivacky * \param command_line_args the command-line arguments to pass to the Clang 1571203955Srdivacky * compiler to build the given source file. This should include all of the 1572199482Srdivacky * necessary include paths, language-dialect switches, precompiled header 1573203955Srdivacky * includes, etc., but should not include any information specific to 1574199482Srdivacky * code completion. 1575199482Srdivacky * 1576200583Srdivacky * \param num_unsaved_files the number of unsaved file entries in \p 1577200583Srdivacky * unsaved_files. 1578200583Srdivacky * 1579200583Srdivacky * \param unsaved_files the files that have not yet been saved to disk 1580200583Srdivacky * but may be required for code completion, including the contents of 1581200583Srdivacky * those files. 1582200583Srdivacky * 1583199482Srdivacky * \param complete_filename the name of the source file where code completion 1584199482Srdivacky * should be performed. In many cases, this name will be the same as the 1585203955Srdivacky * source filename. However, the completion filename may also be a file 1586203955Srdivacky * included by the source file, which is required when producing 1587199482Srdivacky * code-completion results for a header. 1588199482Srdivacky * 1589199482Srdivacky * \param complete_line the line at which code-completion should occur. 1590199482Srdivacky * 1591203955Srdivacky * \param complete_column the column at which code-completion should occur. 1592199482Srdivacky * Note that the column should point just after the syntactic construct that 1593199482Srdivacky * initiated code completion, and not in the middle of a lexical token. 1594199482Srdivacky * 1595203955Srdivacky * \param diag_callback callback function that will receive any diagnostics 1596203955Srdivacky * emitted while processing this source file. If NULL, diagnostics will be 1597203955Srdivacky * suppressed. 1598203955Srdivacky * 1599203955Srdivacky * \param diag_client_data client data that will be passed to the diagnostic 1600203955Srdivacky * callback function. 1601203955Srdivacky * 1602201361Srdivacky * \returns if successful, a new CXCodeCompleteResults structure 1603201361Srdivacky * containing code-completion results, which should eventually be 1604201361Srdivacky * freed with \c clang_disposeCodeCompleteResults(). If code 1605201361Srdivacky * completion fails, returns NULL. 1606199482Srdivacky */ 1607203955SrdivackyCINDEX_LINKAGE 1608203955SrdivackyCXCodeCompleteResults *clang_codeComplete(CXIndex CIdx, 1609201361Srdivacky const char *source_filename, 1610203955Srdivacky int num_command_line_args, 1611201361Srdivacky const char **command_line_args, 1612201361Srdivacky unsigned num_unsaved_files, 1613201361Srdivacky struct CXUnsavedFile *unsaved_files, 1614201361Srdivacky const char *complete_filename, 1615201361Srdivacky unsigned complete_line, 1616203955Srdivacky unsigned complete_column, 1617203955Srdivacky CXDiagnosticCallback diag_callback, 1618203955Srdivacky CXClientData diag_client_data); 1619203955Srdivacky 1620201361Srdivacky/** 1621201361Srdivacky * \brief Free the given set of code-completion results. 1622201361Srdivacky */ 1623203955SrdivackyCINDEX_LINKAGE 1624201361Srdivackyvoid clang_disposeCodeCompleteResults(CXCodeCompleteResults *Results); 1625203955Srdivacky 1626202879Srdivacky/** 1627202879Srdivacky * @} 1628202879Srdivacky */ 1629203955Srdivacky 1630203955Srdivacky 1631202879Srdivacky/** 1632202879Srdivacky * \defgroup CINDEX_MISC Miscellaneous utility functions 1633202879Srdivacky * 1634202879Srdivacky * @{ 1635202879Srdivacky */ 1636202879Srdivacky 1637202879Srdivacky/** 1638203955Srdivacky * \brief Return a version string, suitable for showing to a user, but not 1639203955Srdivacky * intended to be parsed (the format is not guaranteed to be stable). 1640203955Srdivacky */ 1641203955SrdivackyCINDEX_LINKAGE CXString clang_getClangVersion(); 1642203955Srdivacky 1643203955Srdivacky/** 1644203955Srdivacky * \brief Return a version string, suitable for showing to a user, but not 1645203955Srdivacky * intended to be parsed (the format is not guaranteed to be stable). 1646203955Srdivacky */ 1647203955Srdivacky 1648203955Srdivacky 1649203955Srdivacky /** 1650203955Srdivacky * \brief Visitor invoked for each file in a translation unit 1651203955Srdivacky * (used with clang_getInclusions()). 1652203955Srdivacky * 1653203955Srdivacky * This visitor function will be invoked by clang_getInclusions() for each 1654203955Srdivacky * file included (either at the top-level or by #include directives) within 1655203955Srdivacky * a translation unit. The first argument is the file being included, and 1656203955Srdivacky * the second and third arguments provide the inclusion stack. The 1657203955Srdivacky * array is sorted in order of immediate inclusion. For example, 1658203955Srdivacky * the first element refers to the location that included 'included_file'. 1659203955Srdivacky */ 1660203955Srdivackytypedef void (*CXInclusionVisitor)(CXFile included_file, 1661203955Srdivacky CXSourceLocation* inclusion_stack, 1662203955Srdivacky unsigned include_len, 1663203955Srdivacky CXClientData client_data); 1664203955Srdivacky 1665203955Srdivacky/** 1666203955Srdivacky * \brief Visit the set of preprocessor inclusions in a translation unit. 1667203955Srdivacky * The visitor function is called with the provided data for every included 1668203955Srdivacky * file. This does not include headers included by the PCH file (unless one 1669203955Srdivacky * is inspecting the inclusions in the PCH file itself). 1670203955Srdivacky */ 1671203955SrdivackyCINDEX_LINKAGE void clang_getInclusions(CXTranslationUnit tu, 1672203955Srdivacky CXInclusionVisitor visitor, 1673203955Srdivacky CXClientData client_data); 1674203955Srdivacky 1675203955Srdivacky/** 1676202879Srdivacky * @} 1677202879Srdivacky */ 1678203955Srdivacky 1679202879Srdivacky/** 1680202879Srdivacky * @} 1681202879Srdivacky */ 1682203955Srdivacky 1683198092Srdivacky#ifdef __cplusplus 1684198092Srdivacky} 1685198092Srdivacky#endif 1686198092Srdivacky#endif 1687198092Srdivacky 1688