Index.h revision 202879
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 * 39202879Srdivacky * 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 * 45202879Srdivacky * 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. 49202879Srdivacky * 50202879Srdivacky * To avoid namespace pollution, data types are prefixed with "CX" and 51202879Srdivacky * functions are prefixed with "clang_". 52202879Srdivacky * 53202879Srdivacky * @{ 54202879Srdivacky */ 55202879Srdivacky 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; 72202879Srdivacky 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 { 81200583Srdivacky /** 82200583Srdivacky * \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 88200583Srdivacky /** 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 */ 106202879Srdivacky 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 */ 135202879Srdivacky 136198398Srdivacky/** 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 142198398Srdivacky * 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 * - displayDiagnostics: when non-zero, diagnostics will be output. If zero, 147198398Srdivacky * diagnostics will be ignored. 148198398Srdivacky * 149198398Srdivacky * Here is an example: 150198398Srdivacky * 151198398Srdivacky * // excludeDeclsFromPCH = 1, displayDiagnostics = 1 152198398Srdivacky * Idx = clang_createIndex(1, 1); 153198398Srdivacky * 154198398Srdivacky * // IndexTest.pch was produced with the following command: 155198398Srdivacky * // "clang -x c IndexTest.h -emit-ast -o IndexTest.pch" 156198398Srdivacky * TU = clang_createTranslationUnit(Idx, "IndexTest.pch"); 157198398Srdivacky * 158198398Srdivacky * // This will load all the symbols from 'IndexTest.pch' 159202879Srdivacky * clang_visitChildren(clang_getTranslationUnitCursor(TU), 160202879Srdivacky * TranslationUnitVisitor, 0); 161198398Srdivacky * clang_disposeTranslationUnit(TU); 162198398Srdivacky * 163198398Srdivacky * // This will load all the symbols from 'IndexTest.c', excluding symbols 164198398Srdivacky * // from 'IndexTest.pch'. 165198398Srdivacky * char *args[] = { "-Xclang", "-include-pch=IndexTest.pch", 0 }; 166198398Srdivacky * TU = clang_createTranslationUnitFromSourceFile(Idx, "IndexTest.c", 2, args); 167202879Srdivacky * clang_visitChildren(clang_getTranslationUnitCursor(TU), 168202879Srdivacky * TranslationUnitVisitor, 0); 169198398Srdivacky * clang_disposeTranslationUnit(TU); 170198398Srdivacky * 171198398Srdivacky * This process of creating the 'pch', loading it separately, and using it (via 172198398Srdivacky * -include-pch) allows 'excludeDeclsFromPCH' to remove redundant callbacks 173198398Srdivacky * (which gives the indexer the same performance benefit as the compiler). 174198398Srdivacky */ 175198893SrdivackyCINDEX_LINKAGE CXIndex clang_createIndex(int excludeDeclarationsFromPCH, 176198398Srdivacky int displayDiagnostics); 177200583SrdivackyCINDEX_LINKAGE void clang_disposeIndex(CXIndex index); 178200583SrdivackyCINDEX_LINKAGE CXString 179200583Srdivackyclang_getTranslationUnitSpelling(CXTranslationUnit CTUnit); 180198092Srdivacky 181202879Srdivacky/** 182200583Srdivacky * \brief Request that AST's be generated external for API calls which parse 183200583Srdivacky * source code on the fly, e.g. \see createTranslationUnitFromSourceFile. 184200583Srdivacky * 185200583Srdivacky * Note: This is for debugging purposes only, and may be removed at a later 186200583Srdivacky * date. 187200583Srdivacky * 188200583Srdivacky * \param index - The index to update. 189200583Srdivacky * \param value - The new flag value. 190200583Srdivacky */ 191200583SrdivackyCINDEX_LINKAGE void clang_setUseExternalASTGeneration(CXIndex index, 192200583Srdivacky int value); 193200583Srdivacky 194202879Srdivacky/** 195198398Srdivacky * \brief Create a translation unit from an AST file (-emit-ast). 196198398Srdivacky */ 197198893SrdivackyCINDEX_LINKAGE CXTranslationUnit clang_createTranslationUnit( 198198092Srdivacky CXIndex, const char *ast_filename 199198092Srdivacky); 200200583Srdivacky 201198398Srdivacky/** 202198398Srdivacky * \brief Destroy the specified CXTranslationUnit object. 203198398Srdivacky */ 204198893SrdivackyCINDEX_LINKAGE void clang_disposeTranslationUnit(CXTranslationUnit); 205198092Srdivacky 206198398Srdivacky/** 207198398Srdivacky * \brief Return the CXTranslationUnit for a given source file and the provided 208198398Srdivacky * command line arguments one would pass to the compiler. 209198398Srdivacky * 210200583Srdivacky * Note: The 'source_filename' argument is optional. If the caller provides a 211200583Srdivacky * NULL pointer, the name of the source file is expected to reside in the 212200583Srdivacky * specified command line arguments. 213198398Srdivacky * 214200583Srdivacky * Note: When encountered in 'clang_command_line_args', the following options 215200583Srdivacky * are ignored: 216198398Srdivacky * 217198398Srdivacky * '-c' 218198398Srdivacky * '-emit-ast' 219198398Srdivacky * '-fsyntax-only' 220198398Srdivacky * '-o <output file>' (both '-o' and '<output file>' are ignored) 221198398Srdivacky * 222200583Srdivacky * 223200583Srdivacky * \param source_filename - The name of the source file to load, or NULL if the 224200583Srdivacky * source file is included in clang_command_line_args. 225202879Srdivacky * 226202879Srdivacky * \param num_unsaved_files the number of unsaved file entries in \p 227202879Srdivacky * unsaved_files. 228202879Srdivacky * 229202879Srdivacky * \param unsaved_files the files that have not yet been saved to disk 230202879Srdivacky * but may be required for code completion, including the contents of 231202879Srdivacky * those files. 232198398Srdivacky */ 233198893SrdivackyCINDEX_LINKAGE CXTranslationUnit clang_createTranslationUnitFromSourceFile( 234202879Srdivacky CXIndex CIdx, 235202879Srdivacky const char *source_filename, 236202879Srdivacky int num_clang_command_line_args, 237202879Srdivacky const char **clang_command_line_args, 238202879Srdivacky unsigned num_unsaved_files, 239202879Srdivacky struct CXUnsavedFile *unsaved_files); 240198398Srdivacky 241202879Srdivacky/** 242202879Srdivacky * \defgroup CINDEX_FILES File manipulation routines 243202879Srdivacky * 244202879Srdivacky * @{ 245202879Srdivacky */ 246202879Srdivacky 247202879Srdivacky/** 248202879Srdivacky * \brief A particular source file that is part of a translation unit. 249202879Srdivacky */ 250202879Srdivackytypedef void *CXFile; 251202879Srdivacky 252198092Srdivacky 253202879Srdivacky/** 254202879Srdivacky * \brief Retrieve the complete file and path name of the given file. 255202879Srdivacky */ 256202879SrdivackyCINDEX_LINKAGE const char *clang_getFileName(CXFile SFile); 257202879Srdivacky 258202879Srdivacky/** 259202879Srdivacky * \brief Retrieve the last modification time of the given file. 260202879Srdivacky */ 261202879SrdivackyCINDEX_LINKAGE time_t clang_getFileTime(CXFile SFile); 262198092Srdivacky 263202879Srdivacky/** 264202879Srdivacky * \brief Retrieve a file handle within the given translation unit. 265202879Srdivacky * 266202879Srdivacky * \param tu the translation unit 267202879Srdivacky * 268202879Srdivacky * \param file_name the name of the file. 269202879Srdivacky * 270202879Srdivacky * \returns the file handle for the named file in the translation unit \p tu, 271202879Srdivacky * or a NULL file handle if the file was not a part of this translation unit. 272202879Srdivacky */ 273202879SrdivackyCINDEX_LINKAGE CXFile clang_getFile(CXTranslationUnit tu, 274202879Srdivacky const char *file_name); 275202879Srdivacky 276202879Srdivacky/** 277202879Srdivacky * @} 278202879Srdivacky */ 279198092Srdivacky 280202879Srdivacky/** 281202879Srdivacky * \defgroup CINDEX_LOCATIONS Physical source locations 282202879Srdivacky * 283202879Srdivacky * Clang represents physical source locations in its abstract syntax tree in 284202879Srdivacky * great detail, with file, line, and column information for the majority of 285202879Srdivacky * the tokens parsed in the source code. These data types and functions are 286202879Srdivacky * used to represent source location information, either for a particular 287202879Srdivacky * point in the program or for a range of points in the program, and extract 288202879Srdivacky * specific location information from those data types. 289202879Srdivacky * 290202879Srdivacky * @{ 291202879Srdivacky */ 292202879Srdivacky 293202879Srdivacky/** 294202879Srdivacky * \brief Identifies a specific source location within a translation 295202879Srdivacky * unit. 296202879Srdivacky * 297202879Srdivacky * Use clang_getInstantiationLocation() to map a source location to a 298202879Srdivacky * particular file, line, and column. 299202879Srdivacky */ 300202879Srdivackytypedef struct { 301202879Srdivacky void *ptr_data; 302202879Srdivacky unsigned int_data; 303202879Srdivacky} CXSourceLocation; 304198092Srdivacky 305202879Srdivacky/** 306202879Srdivacky * \brief Identifies a range of source locations in the source code. 307202879Srdivacky * 308202879Srdivacky * Use clang_getRangeStart() and clang_getRangeEnd() to retrieve the 309202879Srdivacky * starting and end locations from a source range, respectively. 310198893Srdivacky */ 311202879Srdivackytypedef struct { 312202879Srdivacky void *ptr_data; 313202879Srdivacky unsigned begin_int_data; 314202879Srdivacky unsigned end_int_data; 315202879Srdivacky} CXSourceRange; 316198893Srdivacky 317202879Srdivacky/** 318202879Srdivacky * \brief Retrieve a NULL (invalid) source location. 319198092Srdivacky */ 320202879SrdivackyCINDEX_LINKAGE CXSourceLocation clang_getNullLocation(); 321202379Srdivacky 322202879Srdivacky/** 323202879Srdivacky * \determine Determine whether two source locations, which must refer into 324202879Srdivacky * the same translation unit, refer to exactly the same point in the source 325202879Srdivacky * code. 326202879Srdivacky * 327202879Srdivacky * \returns non-zero if the source locations refer to the same location, zero 328202879Srdivacky * if they refer to different locations. 329202879Srdivacky */ 330202879SrdivackyCINDEX_LINKAGE unsigned clang_equalLocations(CXSourceLocation loc1, 331202879Srdivacky CXSourceLocation loc2); 332202879Srdivacky 333202879Srdivacky/** 334202879Srdivacky * \brief Retrieves the source location associated with a given 335202879Srdivacky * file/line/column in a particular translation unit. 336202879Srdivacky */ 337202879SrdivackyCINDEX_LINKAGE CXSourceLocation clang_getLocation(CXTranslationUnit tu, 338202879Srdivacky CXFile file, 339202879Srdivacky unsigned line, 340202879Srdivacky unsigned column); 341202879Srdivacky 342202879Srdivacky/** 343202879Srdivacky * \brief Retrieve a source range given the beginning and ending source 344202879Srdivacky * locations. 345202879Srdivacky */ 346202879SrdivackyCINDEX_LINKAGE CXSourceRange clang_getRange(CXSourceLocation begin, 347202879Srdivacky CXSourceLocation end); 348202879Srdivacky 349202879Srdivacky/** 350202879Srdivacky * \brief Retrieve the file, line, and column represented by the 351202879Srdivacky * given source location. 352202879Srdivacky * 353202879Srdivacky * \param location the location within a source file that will be 354202879Srdivacky * decomposed into its parts. 355202879Srdivacky * 356202879Srdivacky * \param file if non-NULL, will be set to the file to which the given 357202879Srdivacky * source location points. 358202879Srdivacky * 359202879Srdivacky * \param line if non-NULL, will be set to the line to which the given 360202879Srdivacky * source location points. 361202879Srdivacky * 362202879Srdivacky * \param column if non-NULL, will be set to the column to which the 363202879Srdivacky * given source location points. 364202879Srdivacky */ 365202879SrdivackyCINDEX_LINKAGE void clang_getInstantiationLocation(CXSourceLocation location, 366202879Srdivacky CXFile *file, 367202879Srdivacky unsigned *line, 368202879Srdivacky unsigned *column); 369202379Srdivacky 370202879Srdivacky/** 371202879Srdivacky * \brief Retrieve a source location representing the first 372202879Srdivacky * character within a source range. 373198092Srdivacky */ 374202879SrdivackyCINDEX_LINKAGE CXSourceLocation clang_getRangeStart(CXSourceRange range); 375198092Srdivacky 376202879Srdivacky/** 377202879Srdivacky * \brief Retrieve a source location representing the last 378202879Srdivacky * character within a source range. 379202879Srdivacky */ 380202879SrdivackyCINDEX_LINKAGE CXSourceLocation clang_getRangeEnd(CXSourceRange range); 381202379Srdivacky 382202879Srdivacky/** 383202879Srdivacky * @} 384202879Srdivacky */ 385202379Srdivacky 386202879Srdivacky/** 387202879Srdivacky * \brief Describes the kind of entity that a cursor refers to. 388202379Srdivacky */ 389202879Srdivackyenum CXCursorKind { 390202879Srdivacky /* Declarations */ 391202879Srdivacky CXCursor_FirstDecl = 1, 392202879Srdivacky /** 393202879Srdivacky * \brief A declaration whose specific kind is not exposed via this 394202879Srdivacky * interface. 395202879Srdivacky * 396202879Srdivacky * Unexposed declarations have the same operations as any other kind 397202879Srdivacky * of declaration; one can extract their location information, 398202879Srdivacky * spelling, find their definitions, etc. However, the specific kind 399202879Srdivacky * of the declaration is not reported. 400202879Srdivacky */ 401202879Srdivacky CXCursor_UnexposedDecl = 1, 402202879Srdivacky /** \brief A C or C++ struct. */ 403202879Srdivacky CXCursor_StructDecl = 2, 404202879Srdivacky /** \brief A C or C++ union. */ 405202879Srdivacky CXCursor_UnionDecl = 3, 406202879Srdivacky /** \brief A C++ class. */ 407202879Srdivacky CXCursor_ClassDecl = 4, 408202879Srdivacky /** \brief An enumeration. */ 409202879Srdivacky CXCursor_EnumDecl = 5, 410202879Srdivacky /** 411202879Srdivacky * \brief A field (in C) or non-static data member (in C++) in a 412202879Srdivacky * struct, union, or C++ class. 413202879Srdivacky */ 414202879Srdivacky CXCursor_FieldDecl = 6, 415202879Srdivacky /** \brief An enumerator constant. */ 416202879Srdivacky CXCursor_EnumConstantDecl = 7, 417202879Srdivacky /** \brief A function. */ 418202879Srdivacky CXCursor_FunctionDecl = 8, 419202879Srdivacky /** \brief A variable. */ 420202879Srdivacky CXCursor_VarDecl = 9, 421202879Srdivacky /** \brief A function or method parameter. */ 422202879Srdivacky CXCursor_ParmDecl = 10, 423202879Srdivacky /** \brief An Objective-C @interface. */ 424202879Srdivacky CXCursor_ObjCInterfaceDecl = 11, 425202879Srdivacky /** \brief An Objective-C @interface for a category. */ 426202879Srdivacky CXCursor_ObjCCategoryDecl = 12, 427202879Srdivacky /** \brief An Objective-C @protocol declaration. */ 428202879Srdivacky CXCursor_ObjCProtocolDecl = 13, 429202879Srdivacky /** \brief An Objective-C @property declaration. */ 430202879Srdivacky CXCursor_ObjCPropertyDecl = 14, 431202879Srdivacky /** \brief An Objective-C instance variable. */ 432202879Srdivacky CXCursor_ObjCIvarDecl = 15, 433202879Srdivacky /** \brief An Objective-C instance method. */ 434202879Srdivacky CXCursor_ObjCInstanceMethodDecl = 16, 435202879Srdivacky /** \brief An Objective-C class method. */ 436202879Srdivacky CXCursor_ObjCClassMethodDecl = 17, 437202879Srdivacky /** \brief An Objective-C @implementation. */ 438202879Srdivacky CXCursor_ObjCImplementationDecl = 18, 439202879Srdivacky /** \brief An Objective-C @implementation for a category. */ 440202879Srdivacky CXCursor_ObjCCategoryImplDecl = 19, 441202879Srdivacky /** \brief A typedef */ 442202879Srdivacky CXCursor_TypedefDecl = 20, 443202879Srdivacky CXCursor_LastDecl = 20, 444202879Srdivacky 445202879Srdivacky /* References */ 446202879Srdivacky CXCursor_FirstRef = 40, /* Decl references */ 447202879Srdivacky CXCursor_ObjCSuperClassRef = 40, 448202879Srdivacky CXCursor_ObjCProtocolRef = 41, 449202879Srdivacky CXCursor_ObjCClassRef = 42, 450202879Srdivacky /** 451202879Srdivacky * \brief A reference to a type declaration. 452202879Srdivacky * 453202879Srdivacky * A type reference occurs anywhere where a type is named but not 454202879Srdivacky * declared. For example, given: 455202879Srdivacky * 456202879Srdivacky * \code 457202879Srdivacky * typedef unsigned size_type; 458202879Srdivacky * size_type size; 459202879Srdivacky * \endcode 460202879Srdivacky * 461202879Srdivacky * The typedef is a declaration of size_type (CXCursor_TypedefDecl), 462202879Srdivacky * while the type of the variable "size" is referenced. The cursor 463202879Srdivacky * referenced by the type of size is the typedef for size_type. 464202879Srdivacky */ 465202879Srdivacky CXCursor_TypeRef = 43, 466202879Srdivacky CXCursor_LastRef = 43, 467202879Srdivacky 468202879Srdivacky /* Error conditions */ 469202879Srdivacky CXCursor_FirstInvalid = 70, 470202879Srdivacky CXCursor_InvalidFile = 70, 471202879Srdivacky CXCursor_NoDeclFound = 71, 472202879Srdivacky CXCursor_NotImplemented = 72, 473202879Srdivacky CXCursor_LastInvalid = 72, 474202879Srdivacky 475202879Srdivacky /* Expressions */ 476202879Srdivacky CXCursor_FirstExpr = 100, 477202879Srdivacky 478202879Srdivacky /** 479202879Srdivacky * \brief An expression whose specific kind is not exposed via this 480202879Srdivacky * interface. 481202879Srdivacky * 482202879Srdivacky * Unexposed expressions have the same operations as any other kind 483202879Srdivacky * of expression; one can extract their location information, 484202879Srdivacky * spelling, children, etc. However, the specific kind of the 485202879Srdivacky * expression is not reported. 486202879Srdivacky */ 487202879Srdivacky CXCursor_UnexposedExpr = 100, 488202879Srdivacky 489202879Srdivacky /** 490202879Srdivacky * \brief An expression that refers to some value declaration, such 491202879Srdivacky * as a function, varible, or enumerator. 492202879Srdivacky */ 493202879Srdivacky CXCursor_DeclRefExpr = 101, 494202879Srdivacky 495202879Srdivacky /** 496202879Srdivacky * \brief An expression that refers to a member of a struct, union, 497202879Srdivacky * class, Objective-C class, etc. 498202879Srdivacky */ 499202879Srdivacky CXCursor_MemberRefExpr = 102, 500202879Srdivacky 501202879Srdivacky /** \brief An expression that calls a function. */ 502202879Srdivacky CXCursor_CallExpr = 103, 503202879Srdivacky 504202879Srdivacky /** \brief An expression that sends a message to an Objective-C 505202879Srdivacky object or class. */ 506202879Srdivacky CXCursor_ObjCMessageExpr = 104, 507202879Srdivacky CXCursor_LastExpr = 104, 508202879Srdivacky 509202879Srdivacky /* Statements */ 510202879Srdivacky CXCursor_FirstStmt = 200, 511202879Srdivacky /** 512202879Srdivacky * \brief A statement whose specific kind is not exposed via this 513202879Srdivacky * interface. 514202879Srdivacky * 515202879Srdivacky * Unexposed statements have the same operations as any other kind of 516202879Srdivacky * statement; one can extract their location information, spelling, 517202879Srdivacky * children, etc. However, the specific kind of the statement is not 518202879Srdivacky * reported. 519202879Srdivacky */ 520202879Srdivacky CXCursor_UnexposedStmt = 200, 521202879Srdivacky CXCursor_LastStmt = 200, 522202879Srdivacky 523202879Srdivacky /** 524202879Srdivacky * \brief Cursor that represents the translation unit itself. 525202879Srdivacky * 526202879Srdivacky * The translation unit cursor exists primarily to act as the root 527202879Srdivacky * cursor for traversing the contents of a translation unit. 528202879Srdivacky */ 529202879Srdivacky CXCursor_TranslationUnit = 300 530202879Srdivacky}; 531202379Srdivacky 532202879Srdivacky/** 533202879Srdivacky * \brief A cursor representing some element in the abstract syntax tree for 534202879Srdivacky * a translation unit. 535202879Srdivacky * 536202879Srdivacky * The cursor abstraction unifies the different kinds of entities in a 537202879Srdivacky * program--declaration, statements, expressions, references to declarations, 538202879Srdivacky * etc.--under a single "cursor" abstraction with a common set of operations. 539202879Srdivacky * Common operation for a cursor include: getting the physical location in 540202879Srdivacky * a source file where the cursor points, getting the name associated with a 541202879Srdivacky * cursor, and retrieving cursors for any child nodes of a particular cursor. 542202879Srdivacky * 543202879Srdivacky * Cursors can be produced in two specific ways. 544202879Srdivacky * clang_getTranslationUnitCursor() produces a cursor for a translation unit, 545202879Srdivacky * from which one can use clang_visitChildren() to explore the rest of the 546202879Srdivacky * translation unit. clang_getCursor() maps from a physical source location 547202879Srdivacky * to the entity that resides at that location, allowing one to map from the 548202879Srdivacky * source code into the AST. 549198092Srdivacky */ 550202879Srdivackytypedef struct { 551202879Srdivacky enum CXCursorKind kind; 552202879Srdivacky void *data[3]; 553202879Srdivacky} CXCursor; 554202879Srdivacky 555198398Srdivacky/** 556202879Srdivacky * \defgroup CINDEX_CURSOR_MANIP Cursor manipulations 557202879Srdivacky * 558202879Srdivacky * @{ 559198398Srdivacky */ 560202879Srdivacky 561202879Srdivacky/** 562202879Srdivacky * \brief Retrieve the NULL cursor, which represents no entity. 563202879Srdivacky */ 564199482SrdivackyCINDEX_LINKAGE CXCursor clang_getNullCursor(void); 565202879Srdivacky 566202879Srdivacky/** 567202879Srdivacky * \brief Retrieve the cursor that represents the given translation unit. 568202879Srdivacky * 569202879Srdivacky * The translation unit cursor can be used to start traversing the 570202879Srdivacky * various declarations within the given translation unit. 571202879Srdivacky */ 572202879SrdivackyCINDEX_LINKAGE CXCursor clang_getTranslationUnitCursor(CXTranslationUnit); 573198092Srdivacky 574202879Srdivacky/** 575202879Srdivacky * \brief Determine whether two cursors are equivalent. 576202879Srdivacky */ 577202879SrdivackyCINDEX_LINKAGE unsigned clang_equalCursors(CXCursor, CXCursor); 578202879Srdivacky 579202879Srdivacky/** 580202879Srdivacky * \brief Retrieve the kind of the given cursor. 581202879Srdivacky */ 582198893SrdivackyCINDEX_LINKAGE enum CXCursorKind clang_getCursorKind(CXCursor); 583202879Srdivacky 584202879Srdivacky/** 585202879Srdivacky * \brief Determine whether the given cursor kind represents a declaration. 586202879Srdivacky */ 587198893SrdivackyCINDEX_LINKAGE unsigned clang_isDeclaration(enum CXCursorKind); 588202879Srdivacky 589202879Srdivacky/** 590202879Srdivacky * \brief Determine whether the given cursor kind represents a simple 591202879Srdivacky * reference. 592202879Srdivacky * 593202879Srdivacky * Note that other kinds of cursors (such as expressions) can also refer to 594202879Srdivacky * other cursors. Use clang_getCursorReferenced() to determine whether a 595202879Srdivacky * particular cursor refers to another entity. 596202879Srdivacky */ 597198893SrdivackyCINDEX_LINKAGE unsigned clang_isReference(enum CXCursorKind); 598202879Srdivacky 599202879Srdivacky/** 600202879Srdivacky * \brief Determine whether the given cursor kind represents an expression. 601202879Srdivacky */ 602202879SrdivackyCINDEX_LINKAGE unsigned clang_isExpression(enum CXCursorKind); 603202879Srdivacky 604202879Srdivacky/** 605202879Srdivacky * \brief Determine whether the given cursor kind represents a statement. 606202879Srdivacky */ 607202879SrdivackyCINDEX_LINKAGE unsigned clang_isStatement(enum CXCursorKind); 608202879Srdivacky 609202879Srdivacky/** 610202879Srdivacky * \brief Determine whether the given cursor kind represents an invalid 611202879Srdivacky * cursor. 612202879Srdivacky */ 613198893SrdivackyCINDEX_LINKAGE unsigned clang_isInvalid(enum CXCursorKind); 614198398Srdivacky 615202879Srdivacky/** 616202879Srdivacky * \brief Determine whether the given cursor kind represents a translation 617202879Srdivacky * unit. 618202879Srdivacky */ 619202879SrdivackyCINDEX_LINKAGE unsigned clang_isTranslationUnit(enum CXCursorKind); 620202879Srdivacky 621202879Srdivacky/** 622202879Srdivacky * @} 623202879Srdivacky */ 624202879Srdivacky 625202879Srdivacky/** 626202879Srdivacky * \defgroup CINDEX_CURSOR_SOURCE Mapping between cursors and source code 627202879Srdivacky * 628202879Srdivacky * Cursors represent a location within the Abstract Syntax Tree (AST). These 629202879Srdivacky * routines help map between cursors and the physical locations where the 630202879Srdivacky * described entities occur in the source code. The mapping is provided in 631202879Srdivacky * both directions, so one can map from source code to the AST and back. 632202879Srdivacky * 633202879Srdivacky * @{ 634202879Srdivacky */ 635202879Srdivacky 636202879Srdivacky/** 637202879Srdivacky * \brief Map a source location to the cursor that describes the entity at that 638202879Srdivacky * location in the source code. 639202879Srdivacky * 640202879Srdivacky * clang_getCursor() maps an arbitrary source location within a translation 641202879Srdivacky * unit down to the most specific cursor that describes the entity at that 642202879Srdivacky * location. For example, given an expression \c x + y, invoking 643202879Srdivacky * clang_getCursor() with a source location pointing to "x" will return the 644202879Srdivacky * cursor for "x"; similarly for "y". If the cursor points anywhere between 645202879Srdivacky * "x" or "y" (e.g., on the + or the whitespace around it), clang_getCursor() 646202879Srdivacky * will return a cursor referring to the "+" expression. 647202879Srdivacky * 648202879Srdivacky * \returns a cursor representing the entity at the given source location, or 649202879Srdivacky * a NULL cursor if no such entity can be found. 650202879Srdivacky */ 651202879SrdivackyCINDEX_LINKAGE CXCursor clang_getCursor(CXTranslationUnit, CXSourceLocation); 652202879Srdivacky 653202879Srdivacky/** 654202879Srdivacky * \brief Retrieve the physical location of the source constructor referenced 655202879Srdivacky * by the given cursor. 656202879Srdivacky * 657202879Srdivacky * The location of a declaration is typically the location of the name of that 658202879Srdivacky * declaration, where the name of that declaration would occur if it is 659202879Srdivacky * unnamed, or some keyword that introduces that particular declaration. 660202879Srdivacky * The location of a reference is where that reference occurs within the 661202879Srdivacky * source code. 662202879Srdivacky */ 663202879SrdivackyCINDEX_LINKAGE CXSourceLocation clang_getCursorLocation(CXCursor); 664199482Srdivacky 665202879Srdivacky/** 666202879Srdivacky * \brief Retrieve the physical extent of the source construct referenced by 667202879Srdivacky * the given cursor. 668202879Srdivacky * 669202879Srdivacky * The extent of a cursor starts with the file/line/column pointing at the 670202879Srdivacky * first character within the source construct that the cursor refers to and 671202879Srdivacky * ends with the last character withinin that source construct. For a 672202879Srdivacky * declaration, the extent covers the declaration itself. For a reference, 673202879Srdivacky * the extent covers the location of the reference (e.g., where the referenced 674202879Srdivacky * entity was actually used). 675202879Srdivacky */ 676202879SrdivackyCINDEX_LINKAGE CXSourceRange clang_getCursorExtent(CXCursor); 677202879Srdivacky 678202879Srdivacky/** 679202879Srdivacky * @} 680202879Srdivacky */ 681202879Srdivacky 682202879Srdivacky/** 683202879Srdivacky * \defgroup CINDEX_CURSOR_TRAVERSAL Traversing the AST with cursors 684202879Srdivacky * 685202879Srdivacky * These routines provide the ability to traverse the abstract syntax tree 686202879Srdivacky * using cursors. 687202879Srdivacky * 688202879Srdivacky * @{ 689202879Srdivacky */ 690202879Srdivacky 691202879Srdivacky/** 692202879Srdivacky * \brief Describes how the traversal of the children of a particular 693202879Srdivacky * cursor should proceed after visiting a particular child cursor. 694202879Srdivacky * 695202879Srdivacky * A value of this enumeration type should be returned by each 696202879Srdivacky * \c CXCursorVisitor to indicate how clang_visitChildren() proceed. 697202879Srdivacky */ 698202879Srdivackyenum CXChildVisitResult { 699202879Srdivacky /** 700202879Srdivacky * \brief Terminates the cursor traversal. 701202879Srdivacky */ 702202879Srdivacky CXChildVisit_Break, 703202879Srdivacky /** 704202879Srdivacky * \brief Continues the cursor traversal with the next sibling of 705202879Srdivacky * the cursor just visited, without visiting its children. 706202879Srdivacky */ 707202879Srdivacky CXChildVisit_Continue, 708202879Srdivacky /** 709202879Srdivacky * \brief Recursively traverse the children of this cursor, using 710202879Srdivacky * the same visitor and client data. 711202879Srdivacky */ 712202879Srdivacky CXChildVisit_Recurse 713202879Srdivacky}; 714202879Srdivacky 715202879Srdivacky/** 716202879Srdivacky * \brief Visitor invoked for each cursor found by a traversal. 717202879Srdivacky * 718202879Srdivacky * This visitor function will be invoked for each cursor found by 719202879Srdivacky * clang_visitCursorChildren(). Its first argument is the cursor being 720202879Srdivacky * visited, its second argument is the parent visitor for that cursor, 721202879Srdivacky * and its third argument is the client data provided to 722202879Srdivacky * clang_visitCursorChildren(). 723202879Srdivacky * 724202879Srdivacky * The visitor should return one of the \c CXChildVisitResult values 725202879Srdivacky * to direct clang_visitCursorChildren(). 726202879Srdivacky */ 727202879Srdivackytypedef enum CXChildVisitResult (*CXCursorVisitor)(CXCursor cursor, 728202879Srdivacky CXCursor parent, 729202879Srdivacky CXClientData client_data); 730202879Srdivacky 731202879Srdivacky/** 732202879Srdivacky * \brief Visit the children of a particular cursor. 733202879Srdivacky * 734202879Srdivacky * This function visits all the direct children of the given cursor, 735202879Srdivacky * invoking the given \p visitor function with the cursors of each 736202879Srdivacky * visited child. The traversal may be recursive, if the visitor returns 737202879Srdivacky * \c CXChildVisit_Recurse. The traversal may also be ended prematurely, if 738202879Srdivacky * the visitor returns \c CXChildVisit_Break. 739202879Srdivacky * 740202879Srdivacky * \param tu the translation unit into which the cursor refers. 741202879Srdivacky * 742202879Srdivacky * \param parent the cursor whose child may be visited. All kinds of 743202879Srdivacky * cursors can be visited, including invalid visitors (which, by 744202879Srdivacky * definition, have no children). 745202879Srdivacky * 746202879Srdivacky * \param visitor the visitor function that will be invoked for each 747202879Srdivacky * child of \p parent. 748202879Srdivacky * 749202879Srdivacky * \param client_data pointer data supplied by the client, which will 750202879Srdivacky * be passed to the visitor each time it is invoked. 751202879Srdivacky * 752202879Srdivacky * \returns a non-zero value if the traversal was terminated 753202879Srdivacky * prematurely by the visitor returning \c CXChildVisit_Break. 754202879Srdivacky */ 755202879SrdivackyCINDEX_LINKAGE unsigned clang_visitChildren(CXCursor parent, 756202879Srdivacky CXCursorVisitor visitor, 757202879Srdivacky CXClientData client_data); 758202879Srdivacky 759202879Srdivacky/** 760202879Srdivacky * @} 761202879Srdivacky */ 762202879Srdivacky 763202879Srdivacky/** 764202879Srdivacky * \defgroup CINDEX_CURSOR_XREF Cross-referencing in the AST 765202879Srdivacky * 766202879Srdivacky * These routines provide the ability to determine references within and 767202879Srdivacky * across translation units, by providing the names of the entities referenced 768202879Srdivacky * by cursors, follow reference cursors to the declarations they reference, 769202879Srdivacky * and associate declarations with their definitions. 770202879Srdivacky * 771202879Srdivacky * @{ 772202879Srdivacky */ 773202879Srdivacky 774202879Srdivacky/** 775202879Srdivacky * \brief Retrieve a Unified Symbol Resolution (USR) for the entity referenced 776202879Srdivacky * by the given cursor. 777202879Srdivacky * 778202879Srdivacky * A Unified Symbol Resolution (USR) is a string that identifies a particular 779202879Srdivacky * entity (function, class, variable, etc.) within a program. USRs can be 780202879Srdivacky * compared across translation units to determine, e.g., when references in 781202879Srdivacky * one translation refer to an entity defined in another translation unit. 782202879Srdivacky */ 783202879SrdivackyCINDEX_LINKAGE CXString clang_getCursorUSR(CXCursor); 784202879Srdivacky 785202879Srdivacky/** 786202879Srdivacky * \brief Retrieve a name for the entity referenced by this cursor. 787202879Srdivacky */ 788199482SrdivackyCINDEX_LINKAGE CXString clang_getCursorSpelling(CXCursor); 789198398Srdivacky 790202879Srdivacky/** \brief For a cursor that is a reference, retrieve a cursor representing the 791202879Srdivacky * entity that it references. 792202879Srdivacky * 793202879Srdivacky * Reference cursors refer to other entities in the AST. For example, an 794202879Srdivacky * Objective-C superclass reference cursor refers to an Objective-C class. 795202879Srdivacky * This function produces the cursor for the Objective-C class from the 796202879Srdivacky * cursor for the superclass reference. If the input cursor is a declaration or 797202879Srdivacky * definition, it returns that declaration or definition unchanged. 798202879Srdivacky * Othewise, returns the NULL cursor. 799202879Srdivacky */ 800202879SrdivackyCINDEX_LINKAGE CXCursor clang_getCursorReferenced(CXCursor); 801202879Srdivacky 802202879Srdivacky/** 803202879Srdivacky * \brief For a cursor that is either a reference to or a declaration 804202879Srdivacky * of some entity, retrieve a cursor that describes the definition of 805202879Srdivacky * that entity. 806202879Srdivacky * 807202879Srdivacky * Some entities can be declared multiple times within a translation 808202879Srdivacky * unit, but only one of those declarations can also be a 809202879Srdivacky * definition. For example, given: 810202879Srdivacky * 811202879Srdivacky * \code 812202879Srdivacky * int f(int, int); 813202879Srdivacky * int g(int x, int y) { return f(x, y); } 814202879Srdivacky * int f(int a, int b) { return a + b; } 815202879Srdivacky * int f(int, int); 816202879Srdivacky * \endcode 817202879Srdivacky * 818202879Srdivacky * there are three declarations of the function "f", but only the 819202879Srdivacky * second one is a definition. The clang_getCursorDefinition() 820202879Srdivacky * function will take any cursor pointing to a declaration of "f" 821202879Srdivacky * (the first or fourth lines of the example) or a cursor referenced 822202879Srdivacky * that uses "f" (the call to "f' inside "g") and will return a 823202879Srdivacky * declaration cursor pointing to the definition (the second "f" 824202879Srdivacky * declaration). 825202879Srdivacky * 826202879Srdivacky * If given a cursor for which there is no corresponding definition, 827202879Srdivacky * e.g., because there is no definition of that entity within this 828202879Srdivacky * translation unit, returns a NULL cursor. 829202879Srdivacky */ 830202879SrdivackyCINDEX_LINKAGE CXCursor clang_getCursorDefinition(CXCursor); 831202879Srdivacky 832202879Srdivacky/** 833202879Srdivacky * \brief Determine whether the declaration pointed to by this cursor 834202879Srdivacky * is also a definition of that entity. 835202879Srdivacky */ 836202879SrdivackyCINDEX_LINKAGE unsigned clang_isCursorDefinition(CXCursor); 837202879Srdivacky 838202879Srdivacky/** 839202879Srdivacky * @} 840202879Srdivacky */ 841202879Srdivacky 842202879Srdivacky/** 843202879Srdivacky * \defgroup CINDEX_DEBUG Debugging facilities 844202879Srdivacky * 845202879Srdivacky * These routines are used for testing and debugging, only, and should not 846202879Srdivacky * be relied upon. 847202879Srdivacky * 848202879Srdivacky * @{ 849202879Srdivacky */ 850202879Srdivacky 851198092Srdivacky/* for debug/testing */ 852198893SrdivackyCINDEX_LINKAGE const char *clang_getCursorKindSpelling(enum CXCursorKind Kind); 853198893SrdivackyCINDEX_LINKAGE void clang_getDefinitionSpellingAndExtent(CXCursor, 854198092Srdivacky const char **startBuf, 855198092Srdivacky const char **endBuf, 856198092Srdivacky unsigned *startLine, 857198092Srdivacky unsigned *startColumn, 858198092Srdivacky unsigned *endLine, 859198092Srdivacky unsigned *endColumn); 860198092Srdivacky 861202879Srdivacky/** 862202879Srdivacky * @} 863198092Srdivacky */ 864202879Srdivacky 865199482Srdivacky/** 866202879Srdivacky * \defgroup CINDEX_CODE_COMPLET Code completion 867202879Srdivacky * 868202879Srdivacky * Code completion involves taking an (incomplete) source file, along with 869202879Srdivacky * knowledge of where the user is actively editing that file, and suggesting 870202879Srdivacky * syntactically- and semantically-valid constructs that the user might want to 871202879Srdivacky * use at that particular point in the source code. These data structures and 872202879Srdivacky * routines provide support for code completion. 873202879Srdivacky * 874202879Srdivacky * @{ 875202879Srdivacky */ 876202879Srdivacky 877202879Srdivacky/** 878199482Srdivacky * \brief A semantic string that describes a code-completion result. 879199482Srdivacky * 880199482Srdivacky * A semantic string that describes the formatting of a code-completion 881199482Srdivacky * result as a single "template" of text that should be inserted into the 882199482Srdivacky * source buffer when a particular code-completion result is selected. 883199482Srdivacky * Each semantic string is made up of some number of "chunks", each of which 884199482Srdivacky * contains some text along with a description of what that text means, e.g., 885199482Srdivacky * the name of the entity being referenced, whether the text chunk is part of 886199482Srdivacky * the template, or whether it is a "placeholder" that the user should replace 887199482Srdivacky * with actual code,of a specific kind. See \c CXCompletionChunkKind for a 888199482Srdivacky * description of the different kinds of chunks. 889199482Srdivacky */ 890199482Srdivackytypedef void *CXCompletionString; 891199482Srdivacky 892199482Srdivacky/** 893199482Srdivacky * \brief A single result of code completion. 894199482Srdivacky */ 895199482Srdivackytypedef struct { 896199482Srdivacky /** 897199482Srdivacky * \brief The kind of entity that this completion refers to. 898199482Srdivacky * 899199482Srdivacky * The cursor kind will be a macro, keyword, or a declaration (one of the 900199482Srdivacky * *Decl cursor kinds), describing the entity that the completion is 901199482Srdivacky * referring to. 902199482Srdivacky * 903199482Srdivacky * \todo In the future, we would like to provide a full cursor, to allow 904199482Srdivacky * the client to extract additional information from declaration. 905199482Srdivacky */ 906199482Srdivacky enum CXCursorKind CursorKind; 907199482Srdivacky 908199482Srdivacky /** 909199482Srdivacky * \brief The code-completion string that describes how to insert this 910199482Srdivacky * code-completion result into the editing buffer. 911199482Srdivacky */ 912199482Srdivacky CXCompletionString CompletionString; 913199482Srdivacky} CXCompletionResult; 914199482Srdivacky 915199482Srdivacky/** 916199482Srdivacky * \brief Describes a single piece of text within a code-completion string. 917199482Srdivacky * 918199482Srdivacky * Each "chunk" within a code-completion string (\c CXCompletionString) is 919199482Srdivacky * either a piece of text with a specific "kind" that describes how that text 920199482Srdivacky * should be interpreted by the client or is another completion string. 921199482Srdivacky */ 922199482Srdivackyenum CXCompletionChunkKind { 923199482Srdivacky /** 924199482Srdivacky * \brief A code-completion string that describes "optional" text that 925199482Srdivacky * could be a part of the template (but is not required). 926199482Srdivacky * 927199482Srdivacky * The Optional chunk is the only kind of chunk that has a code-completion 928199482Srdivacky * string for its representation, which is accessible via 929199482Srdivacky * \c clang_getCompletionChunkCompletionString(). The code-completion string 930199482Srdivacky * describes an additional part of the template that is completely optional. 931199482Srdivacky * For example, optional chunks can be used to describe the placeholders for 932199482Srdivacky * arguments that match up with defaulted function parameters, e.g. given: 933199482Srdivacky * 934199482Srdivacky * \code 935199482Srdivacky * void f(int x, float y = 3.14, double z = 2.71828); 936199482Srdivacky * \endcode 937199482Srdivacky * 938199482Srdivacky * The code-completion string for this function would contain: 939199482Srdivacky * - a TypedText chunk for "f". 940199482Srdivacky * - a LeftParen chunk for "(". 941199482Srdivacky * - a Placeholder chunk for "int x" 942199482Srdivacky * - an Optional chunk containing the remaining defaulted arguments, e.g., 943199482Srdivacky * - a Comma chunk for "," 944199482Srdivacky * - a Placeholder chunk for "float x" 945199482Srdivacky * - an Optional chunk containing the last defaulted argument: 946199482Srdivacky * - a Comma chunk for "," 947199482Srdivacky * - a Placeholder chunk for "double z" 948199482Srdivacky * - a RightParen chunk for ")" 949199482Srdivacky * 950199482Srdivacky * There are many ways two handle Optional chunks. Two simple approaches are: 951199482Srdivacky * - Completely ignore optional chunks, in which case the template for the 952199482Srdivacky * function "f" would only include the first parameter ("int x"). 953199482Srdivacky * - Fully expand all optional chunks, in which case the template for the 954199482Srdivacky * function "f" would have all of the parameters. 955199482Srdivacky */ 956199482Srdivacky CXCompletionChunk_Optional, 957199482Srdivacky /** 958199482Srdivacky * \brief Text that a user would be expected to type to get this 959199482Srdivacky * code-completion result. 960199482Srdivacky * 961199482Srdivacky * There will be exactly one "typed text" chunk in a semantic string, which 962199482Srdivacky * will typically provide the spelling of a keyword or the name of a 963199482Srdivacky * declaration that could be used at the current code point. Clients are 964199482Srdivacky * expected to filter the code-completion results based on the text in this 965199482Srdivacky * chunk. 966199482Srdivacky */ 967199482Srdivacky CXCompletionChunk_TypedText, 968199482Srdivacky /** 969199482Srdivacky * \brief Text that should be inserted as part of a code-completion result. 970199482Srdivacky * 971199482Srdivacky * A "text" chunk represents text that is part of the template to be 972199482Srdivacky * inserted into user code should this particular code-completion result 973199482Srdivacky * be selected. 974199482Srdivacky */ 975199482Srdivacky CXCompletionChunk_Text, 976199482Srdivacky /** 977199482Srdivacky * \brief Placeholder text that should be replaced by the user. 978199482Srdivacky * 979199482Srdivacky * A "placeholder" chunk marks a place where the user should insert text 980199482Srdivacky * into the code-completion template. For example, placeholders might mark 981199482Srdivacky * the function parameters for a function declaration, to indicate that the 982199482Srdivacky * user should provide arguments for each of those parameters. The actual 983199482Srdivacky * text in a placeholder is a suggestion for the text to display before 984199482Srdivacky * the user replaces the placeholder with real code. 985199482Srdivacky */ 986199482Srdivacky CXCompletionChunk_Placeholder, 987199482Srdivacky /** 988199482Srdivacky * \brief Informative text that should be displayed but never inserted as 989199482Srdivacky * part of the template. 990199482Srdivacky * 991199482Srdivacky * An "informative" chunk contains annotations that can be displayed to 992199482Srdivacky * help the user decide whether a particular code-completion result is the 993199482Srdivacky * right option, but which is not part of the actual template to be inserted 994199482Srdivacky * by code completion. 995199482Srdivacky */ 996199482Srdivacky CXCompletionChunk_Informative, 997199482Srdivacky /** 998199482Srdivacky * \brief Text that describes the current parameter when code-completion is 999199482Srdivacky * referring to function call, message send, or template specialization. 1000199482Srdivacky * 1001199482Srdivacky * A "current parameter" chunk occurs when code-completion is providing 1002199482Srdivacky * information about a parameter corresponding to the argument at the 1003199482Srdivacky * code-completion point. For example, given a function 1004199482Srdivacky * 1005199482Srdivacky * \code 1006199482Srdivacky * int add(int x, int y); 1007199482Srdivacky * \endcode 1008199482Srdivacky * 1009199482Srdivacky * and the source code \c add(, where the code-completion point is after the 1010199482Srdivacky * "(", the code-completion string will contain a "current parameter" chunk 1011199482Srdivacky * for "int x", indicating that the current argument will initialize that 1012199482Srdivacky * parameter. After typing further, to \c add(17, (where the code-completion 1013199482Srdivacky * point is after the ","), the code-completion string will contain a 1014199482Srdivacky * "current paremeter" chunk to "int y". 1015199482Srdivacky */ 1016199482Srdivacky CXCompletionChunk_CurrentParameter, 1017199482Srdivacky /** 1018199482Srdivacky * \brief A left parenthesis ('('), used to initiate a function call or 1019199482Srdivacky * signal the beginning of a function parameter list. 1020199482Srdivacky */ 1021199482Srdivacky CXCompletionChunk_LeftParen, 1022199482Srdivacky /** 1023199482Srdivacky * \brief A right parenthesis (')'), used to finish a function call or 1024199482Srdivacky * signal the end of a function parameter list. 1025199482Srdivacky */ 1026199482Srdivacky CXCompletionChunk_RightParen, 1027199482Srdivacky /** 1028199482Srdivacky * \brief A left bracket ('['). 1029199482Srdivacky */ 1030199482Srdivacky CXCompletionChunk_LeftBracket, 1031199482Srdivacky /** 1032199482Srdivacky * \brief A right bracket (']'). 1033199482Srdivacky */ 1034199482Srdivacky CXCompletionChunk_RightBracket, 1035199482Srdivacky /** 1036199482Srdivacky * \brief A left brace ('{'). 1037199482Srdivacky */ 1038199482Srdivacky CXCompletionChunk_LeftBrace, 1039199482Srdivacky /** 1040199482Srdivacky * \brief A right brace ('}'). 1041199482Srdivacky */ 1042199482Srdivacky CXCompletionChunk_RightBrace, 1043199482Srdivacky /** 1044199482Srdivacky * \brief A left angle bracket ('<'). 1045199482Srdivacky */ 1046199482Srdivacky CXCompletionChunk_LeftAngle, 1047199482Srdivacky /** 1048199482Srdivacky * \brief A right angle bracket ('>'). 1049199482Srdivacky */ 1050199482Srdivacky CXCompletionChunk_RightAngle, 1051199482Srdivacky /** 1052199482Srdivacky * \brief A comma separator (','). 1053199482Srdivacky */ 1054201361Srdivacky CXCompletionChunk_Comma, 1055201361Srdivacky /** 1056201361Srdivacky * \brief Text that specifies the result type of a given result. 1057201361Srdivacky * 1058201361Srdivacky * This special kind of informative chunk is not meant to be inserted into 1059201361Srdivacky * the text buffer. Rather, it is meant to illustrate the type that an 1060201361Srdivacky * expression using the given completion string would have. 1061201361Srdivacky */ 1062202379Srdivacky CXCompletionChunk_ResultType, 1063202379Srdivacky /** 1064202379Srdivacky * \brief A colon (':'). 1065202379Srdivacky */ 1066202379Srdivacky CXCompletionChunk_Colon, 1067202379Srdivacky /** 1068202379Srdivacky * \brief A semicolon (';'). 1069202379Srdivacky */ 1070202379Srdivacky CXCompletionChunk_SemiColon, 1071202379Srdivacky /** 1072202379Srdivacky * \brief An '=' sign. 1073202379Srdivacky */ 1074202379Srdivacky CXCompletionChunk_Equal, 1075202379Srdivacky /** 1076202379Srdivacky * Horizontal space (' '). 1077202379Srdivacky */ 1078202379Srdivacky CXCompletionChunk_HorizontalSpace, 1079202379Srdivacky /** 1080202379Srdivacky * Vertical space ('\n'), after which it is generally a good idea to 1081202379Srdivacky * perform indentation. 1082202379Srdivacky */ 1083202379Srdivacky CXCompletionChunk_VerticalSpace 1084199482Srdivacky}; 1085199482Srdivacky 1086199482Srdivacky/** 1087199482Srdivacky * \brief Determine the kind of a particular chunk within a completion string. 1088199482Srdivacky * 1089199482Srdivacky * \param completion_string the completion string to query. 1090199482Srdivacky * 1091199482Srdivacky * \param chunk_number the 0-based index of the chunk in the completion string. 1092199482Srdivacky * 1093199482Srdivacky * \returns the kind of the chunk at the index \c chunk_number. 1094199482Srdivacky */ 1095199482SrdivackyCINDEX_LINKAGE enum CXCompletionChunkKind 1096199482Srdivackyclang_getCompletionChunkKind(CXCompletionString completion_string, 1097199482Srdivacky unsigned chunk_number); 1098199482Srdivacky 1099199482Srdivacky/** 1100199482Srdivacky * \brief Retrieve the text associated with a particular chunk within a 1101199482Srdivacky * completion string. 1102199482Srdivacky * 1103199482Srdivacky * \param completion_string the completion string to query. 1104199482Srdivacky * 1105199482Srdivacky * \param chunk_number the 0-based index of the chunk in the completion string. 1106199482Srdivacky * 1107199482Srdivacky * \returns the text associated with the chunk at index \c chunk_number. 1108199482Srdivacky */ 1109199482SrdivackyCINDEX_LINKAGE const char * 1110199482Srdivackyclang_getCompletionChunkText(CXCompletionString completion_string, 1111199482Srdivacky unsigned chunk_number); 1112199482Srdivacky 1113199482Srdivacky/** 1114199482Srdivacky * \brief Retrieve the completion string associated with a particular chunk 1115199482Srdivacky * within a completion string. 1116199482Srdivacky * 1117199482Srdivacky * \param completion_string the completion string to query. 1118199482Srdivacky * 1119199482Srdivacky * \param chunk_number the 0-based index of the chunk in the completion string. 1120199482Srdivacky * 1121199482Srdivacky * \returns the completion string associated with the chunk at index 1122199482Srdivacky * \c chunk_number, or NULL if that chunk is not represented by a completion 1123199482Srdivacky * string. 1124199482Srdivacky */ 1125199482SrdivackyCINDEX_LINKAGE CXCompletionString 1126199482Srdivackyclang_getCompletionChunkCompletionString(CXCompletionString completion_string, 1127199482Srdivacky unsigned chunk_number); 1128199482Srdivacky 1129199482Srdivacky/** 1130199482Srdivacky * \brief Retrieve the number of chunks in the given code-completion string. 1131199482Srdivacky */ 1132199482SrdivackyCINDEX_LINKAGE unsigned 1133199482Srdivackyclang_getNumCompletionChunks(CXCompletionString completion_string); 1134199482Srdivacky 1135199482Srdivacky/** 1136201361Srdivacky * \brief Contains the results of code-completion. 1137201361Srdivacky * 1138201361Srdivacky * This data structure contains the results of code completion, as 1139201361Srdivacky * produced by \c clang_codeComplete. Its contents must be freed by 1140201361Srdivacky * \c clang_disposeCodeCompleteResults. 1141201361Srdivacky */ 1142201361Srdivackytypedef struct { 1143201361Srdivacky /** 1144201361Srdivacky * \brief The code-completion results. 1145201361Srdivacky */ 1146201361Srdivacky CXCompletionResult *Results; 1147201361Srdivacky 1148201361Srdivacky /** 1149201361Srdivacky * \brief The number of code-completion results stored in the 1150201361Srdivacky * \c Results array. 1151201361Srdivacky */ 1152201361Srdivacky unsigned NumResults; 1153201361Srdivacky} CXCodeCompleteResults; 1154201361Srdivacky 1155201361Srdivacky/** 1156199482Srdivacky * \brief Perform code completion at a given location in a source file. 1157199482Srdivacky * 1158199482Srdivacky * This function performs code completion at a particular file, line, and 1159199482Srdivacky * column within source code, providing results that suggest potential 1160199482Srdivacky * code snippets based on the context of the completion. The basic model 1161199482Srdivacky * for code completion is that Clang will parse a complete source file, 1162199482Srdivacky * performing syntax checking up to the location where code-completion has 1163199482Srdivacky * been requested. At that point, a special code-completion token is passed 1164199482Srdivacky * to the parser, which recognizes this token and determines, based on the 1165199482Srdivacky * current location in the C/Objective-C/C++ grammar and the state of 1166199482Srdivacky * semantic analysis, what completions to provide. These completions are 1167201361Srdivacky * returned via a new \c CXCodeCompleteResults structure. 1168199482Srdivacky * 1169199482Srdivacky * Code completion itself is meant to be triggered by the client when the 1170199482Srdivacky * user types punctuation characters or whitespace, at which point the 1171199482Srdivacky * code-completion location will coincide with the cursor. For example, if \c p 1172199482Srdivacky * is a pointer, code-completion might be triggered after the "-" and then 1173199482Srdivacky * after the ">" in \c p->. When the code-completion location is afer the ">", 1174199482Srdivacky * the completion results will provide, e.g., the members of the struct that 1175199482Srdivacky * "p" points to. The client is responsible for placing the cursor at the 1176199482Srdivacky * beginning of the token currently being typed, then filtering the results 1177199482Srdivacky * based on the contents of the token. For example, when code-completing for 1178199482Srdivacky * the expression \c p->get, the client should provide the location just after 1179199482Srdivacky * the ">" (e.g., pointing at the "g") to this code-completion hook. Then, the 1180199482Srdivacky * client can filter the results based on the current token text ("get"), only 1181199482Srdivacky * showing those results that start with "get". The intent of this interface 1182201361Srdivacky * is to separate the relatively high-latency acquisition of code-completion 1183199482Srdivacky * results from the filtering of results on a per-character basis, which must 1184199482Srdivacky * have a lower latency. 1185199482Srdivacky * 1186199482Srdivacky * \param CIdx the \c CXIndex instance that will be used to perform code 1187199482Srdivacky * completion. 1188199482Srdivacky * 1189200583Srdivacky * \param source_filename the name of the source file that should be parsed to 1190200583Srdivacky * perform code-completion. This source file must be the same as or include the 1191200583Srdivacky * filename described by \p complete_filename, or no code-completion results 1192200583Srdivacky * will be produced. NOTE: One can also specify NULL for this argument if the 1193200583Srdivacky * source file is included in command_line_args. 1194199482Srdivacky * 1195199482Srdivacky * \param num_command_line_args the number of command-line arguments stored in 1196199482Srdivacky * \p command_line_args. 1197199482Srdivacky * 1198199482Srdivacky * \param command_line_args the command-line arguments to pass to the Clang 1199199482Srdivacky * compiler to build the given source file. This should include all of the 1200199482Srdivacky * necessary include paths, language-dialect switches, precompiled header 1201199482Srdivacky * includes, etc., but should not include any information specific to 1202199482Srdivacky * code completion. 1203199482Srdivacky * 1204200583Srdivacky * \param num_unsaved_files the number of unsaved file entries in \p 1205200583Srdivacky * unsaved_files. 1206200583Srdivacky * 1207200583Srdivacky * \param unsaved_files the files that have not yet been saved to disk 1208200583Srdivacky * but may be required for code completion, including the contents of 1209200583Srdivacky * those files. 1210200583Srdivacky * 1211199482Srdivacky * \param complete_filename the name of the source file where code completion 1212199482Srdivacky * should be performed. In many cases, this name will be the same as the 1213199482Srdivacky * source filename. However, the completion filename may also be a file 1214199482Srdivacky * included by the source file, which is required when producing 1215199482Srdivacky * code-completion results for a header. 1216199482Srdivacky * 1217199482Srdivacky * \param complete_line the line at which code-completion should occur. 1218199482Srdivacky * 1219199482Srdivacky * \param complete_column the column at which code-completion should occur. 1220199482Srdivacky * Note that the column should point just after the syntactic construct that 1221199482Srdivacky * initiated code completion, and not in the middle of a lexical token. 1222199482Srdivacky * 1223201361Srdivacky * \returns if successful, a new CXCodeCompleteResults structure 1224201361Srdivacky * containing code-completion results, which should eventually be 1225201361Srdivacky * freed with \c clang_disposeCodeCompleteResults(). If code 1226201361Srdivacky * completion fails, returns NULL. 1227199482Srdivacky */ 1228201361SrdivackyCINDEX_LINKAGE 1229201361SrdivackyCXCodeCompleteResults *clang_codeComplete(CXIndex CIdx, 1230201361Srdivacky const char *source_filename, 1231201361Srdivacky int num_command_line_args, 1232201361Srdivacky const char **command_line_args, 1233201361Srdivacky unsigned num_unsaved_files, 1234201361Srdivacky struct CXUnsavedFile *unsaved_files, 1235201361Srdivacky const char *complete_filename, 1236201361Srdivacky unsigned complete_line, 1237201361Srdivacky unsigned complete_column); 1238199482Srdivacky 1239201361Srdivacky/** 1240201361Srdivacky * \brief Free the given set of code-completion results. 1241201361Srdivacky */ 1242201361SrdivackyCINDEX_LINKAGE 1243201361Srdivackyvoid clang_disposeCodeCompleteResults(CXCodeCompleteResults *Results); 1244201361Srdivacky 1245202879Srdivacky/** 1246202879Srdivacky * @} 1247202879Srdivacky */ 1248202879Srdivacky 1249202879Srdivacky 1250202879Srdivacky/** 1251202879Srdivacky * \defgroup CINDEX_MISC Miscellaneous utility functions 1252202879Srdivacky * 1253202879Srdivacky * @{ 1254202879Srdivacky */ 1255202879Srdivacky 1256202879SrdivackyCINDEX_LINKAGE const char *clang_getClangVersion(); 1257202879Srdivacky 1258202879Srdivacky/** 1259202879Srdivacky * @} 1260202879Srdivacky */ 1261202879Srdivacky 1262202879Srdivacky/** 1263202879Srdivacky * @} 1264202879Srdivacky */ 1265202879Srdivacky 1266198092Srdivacky#ifdef __cplusplus 1267198092Srdivacky} 1268198092Srdivacky#endif 1269198092Srdivacky#endif 1270198092Srdivacky 1271