Index.h revision 202379
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 37198092Srdivacky/* 38198092Srdivacky Clang indeX abstractions. The backing store for the following API's will be 39198092Srdivacky clangs AST file (currently based on PCH). AST files are created as follows: 40198092Srdivacky 41198092Srdivacky "clang -emit-ast <sourcefile.langsuffix> -o <sourcefile.ast>". 42198092Srdivacky 43198092Srdivacky Naming Conventions: To avoid namespace pollution, data types are prefixed 44198092Srdivacky with "CX" and functions are prefixed with "clang_". 45198092Srdivacky*/ 46198092Srdivackytypedef void *CXIndex; /* An indexing instance. */ 47198092Srdivacky 48198092Srdivackytypedef void *CXTranslationUnit; /* A translation unit instance. */ 49198092Srdivacky 50198893Srdivackytypedef void *CXFile; /* A source file */ 51198092Srdivackytypedef void *CXDecl; /* A specific declaration within a translation unit. */ 52198092Srdivackytypedef void *CXStmt; /* A specific statement within a function/method */ 53198092Srdivacky 54198092Srdivacky/* Cursors represent declarations, definitions, and references. */ 55198092Srdivackyenum CXCursorKind { 56198092Srdivacky /* Declarations */ 57198092Srdivacky CXCursor_FirstDecl = 1, 58198092Srdivacky CXCursor_TypedefDecl = 2, 59198092Srdivacky CXCursor_StructDecl = 3, 60198092Srdivacky CXCursor_UnionDecl = 4, 61198092Srdivacky CXCursor_ClassDecl = 5, 62198092Srdivacky CXCursor_EnumDecl = 6, 63198092Srdivacky CXCursor_FieldDecl = 7, 64198092Srdivacky CXCursor_EnumConstantDecl = 8, 65198092Srdivacky CXCursor_FunctionDecl = 9, 66198092Srdivacky CXCursor_VarDecl = 10, 67198092Srdivacky CXCursor_ParmDecl = 11, 68198092Srdivacky CXCursor_ObjCInterfaceDecl = 12, 69198092Srdivacky CXCursor_ObjCCategoryDecl = 13, 70198092Srdivacky CXCursor_ObjCProtocolDecl = 14, 71198092Srdivacky CXCursor_ObjCPropertyDecl = 15, 72198092Srdivacky CXCursor_ObjCIvarDecl = 16, 73198092Srdivacky CXCursor_ObjCInstanceMethodDecl = 17, 74198092Srdivacky CXCursor_ObjCClassMethodDecl = 18, 75198092Srdivacky CXCursor_LastDecl = 18, 76198092Srdivacky 77198092Srdivacky /* Definitions */ 78198092Srdivacky CXCursor_FirstDefn = 32, 79198092Srdivacky CXCursor_FunctionDefn = 32, 80198092Srdivacky CXCursor_ObjCClassDefn = 33, 81198092Srdivacky CXCursor_ObjCCategoryDefn = 34, 82198092Srdivacky CXCursor_ObjCInstanceMethodDefn = 35, 83198092Srdivacky CXCursor_ObjCClassMethodDefn = 36, 84198092Srdivacky CXCursor_LastDefn = 36, 85198092Srdivacky 86198092Srdivacky /* References */ 87198092Srdivacky CXCursor_FirstRef = 40, /* Decl references */ 88198092Srdivacky CXCursor_ObjCSuperClassRef = 40, 89198092Srdivacky CXCursor_ObjCProtocolRef = 41, 90198092Srdivacky CXCursor_ObjCClassRef = 42, 91198092Srdivacky 92198092Srdivacky CXCursor_ObjCSelectorRef = 43, /* Expression references */ 93198092Srdivacky CXCursor_ObjCIvarRef = 44, 94198092Srdivacky CXCursor_VarRef = 45, 95198092Srdivacky CXCursor_FunctionRef = 46, 96198092Srdivacky CXCursor_EnumConstantRef = 47, 97198092Srdivacky CXCursor_MemberRef = 48, 98198092Srdivacky CXCursor_LastRef = 48, 99198092Srdivacky 100198092Srdivacky /* Error conditions */ 101198092Srdivacky CXCursor_FirstInvalid = 70, 102198092Srdivacky CXCursor_InvalidFile = 70, 103198092Srdivacky CXCursor_NoDeclFound = 71, 104198092Srdivacky CXCursor_NotImplemented = 72, 105198092Srdivacky CXCursor_LastInvalid = 72 106198092Srdivacky}; 107198092Srdivacky 108200583Srdivacky/** 109200583Srdivacky * \brief Provides the contents of a file that has not yet been saved to disk. 110200583Srdivacky * 111200583Srdivacky * Each CXUnsavedFile instance provides the name of a file on the 112200583Srdivacky * system along with the current contents of that file that have not 113200583Srdivacky * yet been saved to disk. 114200583Srdivacky */ 115200583Srdivackystruct CXUnsavedFile { 116200583Srdivacky /** 117200583Srdivacky * \brief The file whose contents have not yet been saved. 118200583Srdivacky * 119200583Srdivacky * This file must already exist in the file system. 120200583Srdivacky */ 121200583Srdivacky const char *Filename; 122200583Srdivacky 123200583Srdivacky /** 124200583Srdivacky * \brief A null-terminated buffer containing the unsaved contents 125200583Srdivacky * of this file. 126200583Srdivacky */ 127200583Srdivacky const char *Contents; 128200583Srdivacky 129200583Srdivacky /** 130200583Srdivacky * \brief The length of the unsaved contents of this buffer, not 131200583Srdivacky * counting the NULL at the end of the buffer. 132200583Srdivacky */ 133200583Srdivacky unsigned long Length; 134200583Srdivacky}; 135200583Srdivacky 136198092Srdivacky/* A cursor into the CXTranslationUnit. */ 137198092Srdivacky 138198092Srdivackytypedef struct { 139198092Srdivacky enum CXCursorKind kind; 140198092Srdivacky CXDecl decl; 141198092Srdivacky CXStmt stmt; /* expression reference */ 142202379Srdivacky CXDecl referringDecl; 143198092Srdivacky} CXCursor; 144198092Srdivacky 145198092Srdivacky/* A unique token for looking up "visible" CXDecls from a CXTranslationUnit. */ 146202379Srdivackytypedef struct { 147202379Srdivacky CXIndex index; 148202379Srdivacky void *data; 149202379Srdivacky} CXEntity; 150198092Srdivacky 151199482Srdivacky/** 152199482Srdivacky * For functions returning a string that might or might not need 153199482Srdivacky * to be internally allocated and freed. 154199482Srdivacky * Use clang_getCString to access the C string value. 155199482Srdivacky * Use clang_disposeString to free the value. 156199482Srdivacky * Treat it as an opaque type. 157199482Srdivacky */ 158199482Srdivackytypedef struct { 159199482Srdivacky const char *Spelling; 160199482Srdivacky /* A 1 value indicates the clang_ indexing API needed to allocate the string 161199482Srdivacky (and it must be freed by clang_disposeString()). */ 162199482Srdivacky int MustFreeString; 163199482Srdivacky} CXString; 164199482Srdivacky 165199482Srdivacky/* Get C string pointer from a CXString. */ 166199482SrdivackyCINDEX_LINKAGE const char *clang_getCString(CXString string); 167199482Srdivacky 168199482Srdivacky/* Free CXString. */ 169199482SrdivackyCINDEX_LINKAGE void clang_disposeString(CXString string); 170199482Srdivacky 171198398Srdivacky/** 172198398Srdivacky * \brief clang_createIndex() provides a shared context for creating 173198398Srdivacky * translation units. It provides two options: 174198398Srdivacky * 175198398Srdivacky * - excludeDeclarationsFromPCH: When non-zero, allows enumeration of "local" 176198398Srdivacky * declarations (when loading any new translation units). A "local" declaration 177198398Srdivacky * is one that belongs in the translation unit itself and not in a precompiled 178198398Srdivacky * header that was used by the translation unit. If zero, all declarations 179198398Srdivacky * will be enumerated. 180198398Srdivacky * 181198398Srdivacky * - displayDiagnostics: when non-zero, diagnostics will be output. If zero, 182198398Srdivacky * diagnostics will be ignored. 183198398Srdivacky * 184198398Srdivacky * Here is an example: 185198398Srdivacky * 186198398Srdivacky * // excludeDeclsFromPCH = 1, displayDiagnostics = 1 187198398Srdivacky * Idx = clang_createIndex(1, 1); 188198398Srdivacky * 189198398Srdivacky * // IndexTest.pch was produced with the following command: 190198398Srdivacky * // "clang -x c IndexTest.h -emit-ast -o IndexTest.pch" 191198398Srdivacky * TU = clang_createTranslationUnit(Idx, "IndexTest.pch"); 192198398Srdivacky * 193198398Srdivacky * // This will load all the symbols from 'IndexTest.pch' 194198398Srdivacky * clang_loadTranslationUnit(TU, TranslationUnitVisitor, 0); 195198398Srdivacky * clang_disposeTranslationUnit(TU); 196198398Srdivacky * 197198398Srdivacky * // This will load all the symbols from 'IndexTest.c', excluding symbols 198198398Srdivacky * // from 'IndexTest.pch'. 199198398Srdivacky * char *args[] = { "-Xclang", "-include-pch=IndexTest.pch", 0 }; 200198398Srdivacky * TU = clang_createTranslationUnitFromSourceFile(Idx, "IndexTest.c", 2, args); 201198398Srdivacky * clang_loadTranslationUnit(TU, TranslationUnitVisitor, 0); 202198398Srdivacky * clang_disposeTranslationUnit(TU); 203198398Srdivacky * 204198398Srdivacky * This process of creating the 'pch', loading it separately, and using it (via 205198398Srdivacky * -include-pch) allows 'excludeDeclsFromPCH' to remove redundant callbacks 206198398Srdivacky * (which gives the indexer the same performance benefit as the compiler). 207198398Srdivacky */ 208198893SrdivackyCINDEX_LINKAGE CXIndex clang_createIndex(int excludeDeclarationsFromPCH, 209198398Srdivacky int displayDiagnostics); 210200583SrdivackyCINDEX_LINKAGE void clang_disposeIndex(CXIndex index); 211200583SrdivackyCINDEX_LINKAGE CXString 212200583Srdivackyclang_getTranslationUnitSpelling(CXTranslationUnit CTUnit); 213198092Srdivacky 214198398Srdivacky/* 215200583Srdivacky * \brief Request that AST's be generated external for API calls which parse 216200583Srdivacky * source code on the fly, e.g. \see createTranslationUnitFromSourceFile. 217200583Srdivacky * 218200583Srdivacky * Note: This is for debugging purposes only, and may be removed at a later 219200583Srdivacky * date. 220200583Srdivacky * 221200583Srdivacky * \param index - The index to update. 222200583Srdivacky * \param value - The new flag value. 223200583Srdivacky */ 224200583SrdivackyCINDEX_LINKAGE void clang_setUseExternalASTGeneration(CXIndex index, 225200583Srdivacky int value); 226200583Srdivacky 227200583Srdivacky/* 228198398Srdivacky * \brief Create a translation unit from an AST file (-emit-ast). 229198398Srdivacky */ 230198893SrdivackyCINDEX_LINKAGE CXTranslationUnit clang_createTranslationUnit( 231198092Srdivacky CXIndex, const char *ast_filename 232198092Srdivacky); 233200583Srdivacky 234198398Srdivacky/** 235198398Srdivacky * \brief Destroy the specified CXTranslationUnit object. 236198398Srdivacky */ 237198893SrdivackyCINDEX_LINKAGE void clang_disposeTranslationUnit(CXTranslationUnit); 238198092Srdivacky 239198398Srdivacky/** 240198398Srdivacky * \brief Return the CXTranslationUnit for a given source file and the provided 241198398Srdivacky * command line arguments one would pass to the compiler. 242198398Srdivacky * 243200583Srdivacky * Note: The 'source_filename' argument is optional. If the caller provides a 244200583Srdivacky * NULL pointer, the name of the source file is expected to reside in the 245200583Srdivacky * specified command line arguments. 246198398Srdivacky * 247200583Srdivacky * Note: When encountered in 'clang_command_line_args', the following options 248200583Srdivacky * are ignored: 249198398Srdivacky * 250198398Srdivacky * '-c' 251198398Srdivacky * '-emit-ast' 252198398Srdivacky * '-fsyntax-only' 253198398Srdivacky * '-o <output file>' (both '-o' and '<output file>' are ignored) 254198398Srdivacky * 255200583Srdivacky * 256200583Srdivacky * \param source_filename - The name of the source file to load, or NULL if the 257200583Srdivacky * source file is included in clang_command_line_args. 258198398Srdivacky */ 259198893SrdivackyCINDEX_LINKAGE CXTranslationUnit clang_createTranslationUnitFromSourceFile( 260200583Srdivacky CXIndex CIdx, 261200583Srdivacky const char *source_filename, 262198398Srdivacky int num_clang_command_line_args, 263198398Srdivacky const char **clang_command_line_args 264198398Srdivacky); 265198398Srdivacky 266198092Srdivacky/* 267198092Srdivacky Usage: clang_loadTranslationUnit(). Will load the toplevel declarations 268198092Srdivacky within a translation unit, issuing a 'callback' for each one. 269198092Srdivacky 270198092Srdivacky void printObjCInterfaceNames(CXTranslationUnit X, CXCursor C) { 271198092Srdivacky if (clang_getCursorKind(C) == Cursor_Declaration) { 272198092Srdivacky CXDecl D = clang_getCursorDecl(C); 273198092Srdivacky if (clang_getDeclKind(D) == CXDecl_ObjC_interface) 274198092Srdivacky printf("@interface %s in file %s on line %d column %d\n", 275198092Srdivacky clang_getDeclSpelling(D), clang_getCursorSource(C), 276198092Srdivacky clang_getCursorLine(C), clang_getCursorColumn(C)); 277198092Srdivacky } 278198092Srdivacky } 279198092Srdivacky static void usage { 280198092Srdivacky clang_loadTranslationUnit(CXTranslationUnit, printObjCInterfaceNames); 281200583Srdivacky } 282198092Srdivacky*/ 283198092Srdivackytypedef void *CXClientData; 284198092Srdivackytypedef void (*CXTranslationUnitIterator)(CXTranslationUnit, CXCursor, 285198092Srdivacky CXClientData); 286200583SrdivackyCINDEX_LINKAGE void clang_loadTranslationUnit(CXTranslationUnit, 287200583Srdivacky CXTranslationUnitIterator, 288200583Srdivacky CXClientData); 289198092Srdivacky 290198092Srdivacky/* 291198092Srdivacky Usage: clang_loadDeclaration(). Will load the declaration, issuing a 292198092Srdivacky 'callback' for each declaration/reference within the respective declaration. 293198092Srdivacky 294198092Srdivacky For interface declarations, this will index the super class, protocols, 295198092Srdivacky ivars, methods, etc. For structure declarations, this will index the fields. 296198092Srdivacky For functions, this will index the parameters (and body, for function 297198092Srdivacky definitions), local declarations/references. 298198092Srdivacky 299198092Srdivacky void getInterfaceDetails(CXDecl X, CXCursor C) { 300198092Srdivacky switch (clang_getCursorKind(C)) { 301198092Srdivacky case Cursor_ObjC_ClassRef: 302198092Srdivacky CXDecl SuperClass = clang_getCursorDecl(C); 303198092Srdivacky case Cursor_ObjC_ProtocolRef: 304198092Srdivacky CXDecl AdoptsProtocol = clang_getCursorDecl(C); 305198092Srdivacky case Cursor_Declaration: 306198092Srdivacky CXDecl AnIvarOrMethod = clang_getCursorDecl(C); 307198092Srdivacky } 308198092Srdivacky } 309198092Srdivacky static void usage() { 310198092Srdivacky if (clang_getDeclKind(D) == CXDecl_ObjC_interface) { 311198092Srdivacky clang_loadDeclaration(D, getInterfaceDetails); 312198092Srdivacky } 313198092Srdivacky } 314198092Srdivacky*/ 315198092Srdivackytypedef void (*CXDeclIterator)(CXDecl, CXCursor, CXClientData); 316198092Srdivacky 317198893SrdivackyCINDEX_LINKAGE void clang_loadDeclaration(CXDecl, CXDeclIterator, CXClientData); 318198092Srdivacky 319198092Srdivacky/* 320198893Srdivacky * CXFile Operations. 321198893Srdivacky */ 322198893SrdivackyCINDEX_LINKAGE const char *clang_getFileName(CXFile SFile); 323198893SrdivackyCINDEX_LINKAGE time_t clang_getFileTime(CXFile SFile); 324198893Srdivacky 325198893Srdivacky/* 326198092Srdivacky * CXEntity Operations. 327198092Srdivacky */ 328202379Srdivacky 329202379Srdivacky/* clang_getDeclaration() maps from a CXEntity to the matching CXDecl (if any) 330202379Srdivacky * in a specified translation unit. */ 331202379SrdivackyCINDEX_LINKAGE CXDecl clang_getDeclaration(CXEntity, CXTranslationUnit); 332202379Srdivacky 333198092Srdivacky/* 334198092Srdivacky * CXDecl Operations. 335198092Srdivacky */ 336198893SrdivackyCINDEX_LINKAGE CXCursor clang_getCursorFromDecl(CXDecl); 337202379SrdivackyCINDEX_LINKAGE CXEntity clang_getEntityFromDecl(CXIndex, CXDecl); 338199482SrdivackyCINDEX_LINKAGE CXString clang_getDeclSpelling(CXDecl); 339198893SrdivackyCINDEX_LINKAGE unsigned clang_getDeclLine(CXDecl); 340198893SrdivackyCINDEX_LINKAGE unsigned clang_getDeclColumn(CXDecl); 341202379SrdivackyCINDEX_LINKAGE CXString clang_getDeclUSR(CXDecl); 342198893SrdivackyCINDEX_LINKAGE const char *clang_getDeclSource(CXDecl); /* deprecate */ 343198893SrdivackyCINDEX_LINKAGE CXFile clang_getDeclSourceFile(CXDecl); 344198092Srdivacky 345202379Srdivackytypedef struct CXSourceLineColumn { 346202379Srdivacky unsigned line; 347202379Srdivacky unsigned column; 348202379Srdivacky} CXSourceLineColumn; 349202379Srdivacky 350202379Srdivackytypedef struct CXDeclExtent { 351202379Srdivacky CXSourceLineColumn begin; 352202379Srdivacky CXSourceLineColumn end; 353202379Srdivacky} CXSourceExtent; 354202379Srdivacky 355202379Srdivacky/* clang_getDeclExtent() returns the physical extent of a declaration. The 356202379Srdivacky * beginning line/column pair points to the start of the first token in the 357202379Srdivacky * declaration, and the ending line/column pair points to the last character in 358202379Srdivacky * the last token of the declaration. 359202379Srdivacky */ 360202379SrdivackyCINDEX_LINKAGE CXSourceExtent clang_getDeclExtent(CXDecl); 361202379Srdivacky 362198092Srdivacky/* 363198092Srdivacky * CXCursor Operations. 364198092Srdivacky */ 365198398Srdivacky/** 366198398Srdivacky Usage: clang_getCursor() will translate a source/line/column position 367198398Srdivacky into an AST cursor (to derive semantic information from the source code). 368198398Srdivacky */ 369200583SrdivackyCINDEX_LINKAGE CXCursor clang_getCursor(CXTranslationUnit, 370200583Srdivacky const char *source_name, 371200583Srdivacky unsigned line, unsigned column); 372199482Srdivacky 373199482SrdivackyCINDEX_LINKAGE CXCursor clang_getNullCursor(void); 374198092Srdivacky 375198893SrdivackyCINDEX_LINKAGE enum CXCursorKind clang_getCursorKind(CXCursor); 376198893SrdivackyCINDEX_LINKAGE unsigned clang_isDeclaration(enum CXCursorKind); 377198893SrdivackyCINDEX_LINKAGE unsigned clang_isReference(enum CXCursorKind); 378198893SrdivackyCINDEX_LINKAGE unsigned clang_isDefinition(enum CXCursorKind); 379198893SrdivackyCINDEX_LINKAGE unsigned clang_isInvalid(enum CXCursorKind); 380198398Srdivacky 381199482SrdivackyCINDEX_LINKAGE unsigned clang_equalCursors(CXCursor, CXCursor); 382199482Srdivacky 383198893SrdivackyCINDEX_LINKAGE unsigned clang_getCursorLine(CXCursor); 384198893SrdivackyCINDEX_LINKAGE unsigned clang_getCursorColumn(CXCursor); 385199482SrdivackyCINDEX_LINKAGE CXString clang_getCursorSpelling(CXCursor); 386198893SrdivackyCINDEX_LINKAGE const char *clang_getCursorSource(CXCursor); /* deprecate */ 387198893SrdivackyCINDEX_LINKAGE CXFile clang_getCursorSourceFile(CXCursor); 388198398Srdivacky 389198092Srdivacky/* for debug/testing */ 390198893SrdivackyCINDEX_LINKAGE const char *clang_getCursorKindSpelling(enum CXCursorKind Kind); 391198893SrdivackyCINDEX_LINKAGE void clang_getDefinitionSpellingAndExtent(CXCursor, 392198092Srdivacky const char **startBuf, 393198092Srdivacky const char **endBuf, 394198092Srdivacky unsigned *startLine, 395198092Srdivacky unsigned *startColumn, 396198092Srdivacky unsigned *endLine, 397198092Srdivacky unsigned *endColumn); 398198092Srdivacky 399198092Srdivacky/* 400198092Srdivacky * If CXCursorKind == Cursor_Reference, then this will return the referenced 401198092Srdivacky * declaration. 402198092Srdivacky * If CXCursorKind == Cursor_Declaration, then this will return the declaration. 403198092Srdivacky */ 404198893SrdivackyCINDEX_LINKAGE CXDecl clang_getCursorDecl(CXCursor); 405198092Srdivacky 406199482Srdivacky/** 407199482Srdivacky * \brief A semantic string that describes a code-completion result. 408199482Srdivacky * 409199482Srdivacky * A semantic string that describes the formatting of a code-completion 410199482Srdivacky * result as a single "template" of text that should be inserted into the 411199482Srdivacky * source buffer when a particular code-completion result is selected. 412199482Srdivacky * Each semantic string is made up of some number of "chunks", each of which 413199482Srdivacky * contains some text along with a description of what that text means, e.g., 414199482Srdivacky * the name of the entity being referenced, whether the text chunk is part of 415199482Srdivacky * the template, or whether it is a "placeholder" that the user should replace 416199482Srdivacky * with actual code,of a specific kind. See \c CXCompletionChunkKind for a 417199482Srdivacky * description of the different kinds of chunks. 418199482Srdivacky */ 419199482Srdivackytypedef void *CXCompletionString; 420199482Srdivacky 421199482Srdivacky/** 422199482Srdivacky * \brief A single result of code completion. 423199482Srdivacky */ 424199482Srdivackytypedef struct { 425199482Srdivacky /** 426199482Srdivacky * \brief The kind of entity that this completion refers to. 427199482Srdivacky * 428199482Srdivacky * The cursor kind will be a macro, keyword, or a declaration (one of the 429199482Srdivacky * *Decl cursor kinds), describing the entity that the completion is 430199482Srdivacky * referring to. 431199482Srdivacky * 432199482Srdivacky * \todo In the future, we would like to provide a full cursor, to allow 433199482Srdivacky * the client to extract additional information from declaration. 434199482Srdivacky */ 435199482Srdivacky enum CXCursorKind CursorKind; 436199482Srdivacky 437199482Srdivacky /** 438199482Srdivacky * \brief The code-completion string that describes how to insert this 439199482Srdivacky * code-completion result into the editing buffer. 440199482Srdivacky */ 441199482Srdivacky CXCompletionString CompletionString; 442199482Srdivacky} CXCompletionResult; 443199482Srdivacky 444199482Srdivacky/** 445199482Srdivacky * \brief Describes a single piece of text within a code-completion string. 446199482Srdivacky * 447199482Srdivacky * Each "chunk" within a code-completion string (\c CXCompletionString) is 448199482Srdivacky * either a piece of text with a specific "kind" that describes how that text 449199482Srdivacky * should be interpreted by the client or is another completion string. 450199482Srdivacky */ 451199482Srdivackyenum CXCompletionChunkKind { 452199482Srdivacky /** 453199482Srdivacky * \brief A code-completion string that describes "optional" text that 454199482Srdivacky * could be a part of the template (but is not required). 455199482Srdivacky * 456199482Srdivacky * The Optional chunk is the only kind of chunk that has a code-completion 457199482Srdivacky * string for its representation, which is accessible via 458199482Srdivacky * \c clang_getCompletionChunkCompletionString(). The code-completion string 459199482Srdivacky * describes an additional part of the template that is completely optional. 460199482Srdivacky * For example, optional chunks can be used to describe the placeholders for 461199482Srdivacky * arguments that match up with defaulted function parameters, e.g. given: 462199482Srdivacky * 463199482Srdivacky * \code 464199482Srdivacky * void f(int x, float y = 3.14, double z = 2.71828); 465199482Srdivacky * \endcode 466199482Srdivacky * 467199482Srdivacky * The code-completion string for this function would contain: 468199482Srdivacky * - a TypedText chunk for "f". 469199482Srdivacky * - a LeftParen chunk for "(". 470199482Srdivacky * - a Placeholder chunk for "int x" 471199482Srdivacky * - an Optional chunk containing the remaining defaulted arguments, e.g., 472199482Srdivacky * - a Comma chunk for "," 473199482Srdivacky * - a Placeholder chunk for "float x" 474199482Srdivacky * - an Optional chunk containing the last defaulted argument: 475199482Srdivacky * - a Comma chunk for "," 476199482Srdivacky * - a Placeholder chunk for "double z" 477199482Srdivacky * - a RightParen chunk for ")" 478199482Srdivacky * 479199482Srdivacky * There are many ways two handle Optional chunks. Two simple approaches are: 480199482Srdivacky * - Completely ignore optional chunks, in which case the template for the 481199482Srdivacky * function "f" would only include the first parameter ("int x"). 482199482Srdivacky * - Fully expand all optional chunks, in which case the template for the 483199482Srdivacky * function "f" would have all of the parameters. 484199482Srdivacky */ 485199482Srdivacky CXCompletionChunk_Optional, 486199482Srdivacky /** 487199482Srdivacky * \brief Text that a user would be expected to type to get this 488199482Srdivacky * code-completion result. 489199482Srdivacky * 490199482Srdivacky * There will be exactly one "typed text" chunk in a semantic string, which 491199482Srdivacky * will typically provide the spelling of a keyword or the name of a 492199482Srdivacky * declaration that could be used at the current code point. Clients are 493199482Srdivacky * expected to filter the code-completion results based on the text in this 494199482Srdivacky * chunk. 495199482Srdivacky */ 496199482Srdivacky CXCompletionChunk_TypedText, 497199482Srdivacky /** 498199482Srdivacky * \brief Text that should be inserted as part of a code-completion result. 499199482Srdivacky * 500199482Srdivacky * A "text" chunk represents text that is part of the template to be 501199482Srdivacky * inserted into user code should this particular code-completion result 502199482Srdivacky * be selected. 503199482Srdivacky */ 504199482Srdivacky CXCompletionChunk_Text, 505199482Srdivacky /** 506199482Srdivacky * \brief Placeholder text that should be replaced by the user. 507199482Srdivacky * 508199482Srdivacky * A "placeholder" chunk marks a place where the user should insert text 509199482Srdivacky * into the code-completion template. For example, placeholders might mark 510199482Srdivacky * the function parameters for a function declaration, to indicate that the 511199482Srdivacky * user should provide arguments for each of those parameters. The actual 512199482Srdivacky * text in a placeholder is a suggestion for the text to display before 513199482Srdivacky * the user replaces the placeholder with real code. 514199482Srdivacky */ 515199482Srdivacky CXCompletionChunk_Placeholder, 516199482Srdivacky /** 517199482Srdivacky * \brief Informative text that should be displayed but never inserted as 518199482Srdivacky * part of the template. 519199482Srdivacky * 520199482Srdivacky * An "informative" chunk contains annotations that can be displayed to 521199482Srdivacky * help the user decide whether a particular code-completion result is the 522199482Srdivacky * right option, but which is not part of the actual template to be inserted 523199482Srdivacky * by code completion. 524199482Srdivacky */ 525199482Srdivacky CXCompletionChunk_Informative, 526199482Srdivacky /** 527199482Srdivacky * \brief Text that describes the current parameter when code-completion is 528199482Srdivacky * referring to function call, message send, or template specialization. 529199482Srdivacky * 530199482Srdivacky * A "current parameter" chunk occurs when code-completion is providing 531199482Srdivacky * information about a parameter corresponding to the argument at the 532199482Srdivacky * code-completion point. For example, given a function 533199482Srdivacky * 534199482Srdivacky * \code 535199482Srdivacky * int add(int x, int y); 536199482Srdivacky * \endcode 537199482Srdivacky * 538199482Srdivacky * and the source code \c add(, where the code-completion point is after the 539199482Srdivacky * "(", the code-completion string will contain a "current parameter" chunk 540199482Srdivacky * for "int x", indicating that the current argument will initialize that 541199482Srdivacky * parameter. After typing further, to \c add(17, (where the code-completion 542199482Srdivacky * point is after the ","), the code-completion string will contain a 543199482Srdivacky * "current paremeter" chunk to "int y". 544199482Srdivacky */ 545199482Srdivacky CXCompletionChunk_CurrentParameter, 546199482Srdivacky /** 547199482Srdivacky * \brief A left parenthesis ('('), used to initiate a function call or 548199482Srdivacky * signal the beginning of a function parameter list. 549199482Srdivacky */ 550199482Srdivacky CXCompletionChunk_LeftParen, 551199482Srdivacky /** 552199482Srdivacky * \brief A right parenthesis (')'), used to finish a function call or 553199482Srdivacky * signal the end of a function parameter list. 554199482Srdivacky */ 555199482Srdivacky CXCompletionChunk_RightParen, 556199482Srdivacky /** 557199482Srdivacky * \brief A left bracket ('['). 558199482Srdivacky */ 559199482Srdivacky CXCompletionChunk_LeftBracket, 560199482Srdivacky /** 561199482Srdivacky * \brief A right bracket (']'). 562199482Srdivacky */ 563199482Srdivacky CXCompletionChunk_RightBracket, 564199482Srdivacky /** 565199482Srdivacky * \brief A left brace ('{'). 566199482Srdivacky */ 567199482Srdivacky CXCompletionChunk_LeftBrace, 568199482Srdivacky /** 569199482Srdivacky * \brief A right brace ('}'). 570199482Srdivacky */ 571199482Srdivacky CXCompletionChunk_RightBrace, 572199482Srdivacky /** 573199482Srdivacky * \brief A left angle bracket ('<'). 574199482Srdivacky */ 575199482Srdivacky CXCompletionChunk_LeftAngle, 576199482Srdivacky /** 577199482Srdivacky * \brief A right angle bracket ('>'). 578199482Srdivacky */ 579199482Srdivacky CXCompletionChunk_RightAngle, 580199482Srdivacky /** 581199482Srdivacky * \brief A comma separator (','). 582199482Srdivacky */ 583201361Srdivacky CXCompletionChunk_Comma, 584201361Srdivacky /** 585201361Srdivacky * \brief Text that specifies the result type of a given result. 586201361Srdivacky * 587201361Srdivacky * This special kind of informative chunk is not meant to be inserted into 588201361Srdivacky * the text buffer. Rather, it is meant to illustrate the type that an 589201361Srdivacky * expression using the given completion string would have. 590201361Srdivacky */ 591202379Srdivacky CXCompletionChunk_ResultType, 592202379Srdivacky /** 593202379Srdivacky * \brief A colon (':'). 594202379Srdivacky */ 595202379Srdivacky CXCompletionChunk_Colon, 596202379Srdivacky /** 597202379Srdivacky * \brief A semicolon (';'). 598202379Srdivacky */ 599202379Srdivacky CXCompletionChunk_SemiColon, 600202379Srdivacky /** 601202379Srdivacky * \brief An '=' sign. 602202379Srdivacky */ 603202379Srdivacky CXCompletionChunk_Equal, 604202379Srdivacky /** 605202379Srdivacky * Horizontal space (' '). 606202379Srdivacky */ 607202379Srdivacky CXCompletionChunk_HorizontalSpace, 608202379Srdivacky /** 609202379Srdivacky * Vertical space ('\n'), after which it is generally a good idea to 610202379Srdivacky * perform indentation. 611202379Srdivacky */ 612202379Srdivacky CXCompletionChunk_VerticalSpace 613199482Srdivacky}; 614199482Srdivacky 615199482Srdivacky/** 616199482Srdivacky * \brief Determine the kind of a particular chunk within a completion string. 617199482Srdivacky * 618199482Srdivacky * \param completion_string the completion string to query. 619199482Srdivacky * 620199482Srdivacky * \param chunk_number the 0-based index of the chunk in the completion string. 621199482Srdivacky * 622199482Srdivacky * \returns the kind of the chunk at the index \c chunk_number. 623199482Srdivacky */ 624199482SrdivackyCINDEX_LINKAGE enum CXCompletionChunkKind 625199482Srdivackyclang_getCompletionChunkKind(CXCompletionString completion_string, 626199482Srdivacky unsigned chunk_number); 627199482Srdivacky 628199482Srdivacky/** 629199482Srdivacky * \brief Retrieve the text associated with a particular chunk within a 630199482Srdivacky * completion string. 631199482Srdivacky * 632199482Srdivacky * \param completion_string the completion string to query. 633199482Srdivacky * 634199482Srdivacky * \param chunk_number the 0-based index of the chunk in the completion string. 635199482Srdivacky * 636199482Srdivacky * \returns the text associated with the chunk at index \c chunk_number. 637199482Srdivacky */ 638199482SrdivackyCINDEX_LINKAGE const char * 639199482Srdivackyclang_getCompletionChunkText(CXCompletionString completion_string, 640199482Srdivacky unsigned chunk_number); 641199482Srdivacky 642199482Srdivacky/** 643199482Srdivacky * \brief Retrieve the completion string associated with a particular chunk 644199482Srdivacky * within a completion string. 645199482Srdivacky * 646199482Srdivacky * \param completion_string the completion string to query. 647199482Srdivacky * 648199482Srdivacky * \param chunk_number the 0-based index of the chunk in the completion string. 649199482Srdivacky * 650199482Srdivacky * \returns the completion string associated with the chunk at index 651199482Srdivacky * \c chunk_number, or NULL if that chunk is not represented by a completion 652199482Srdivacky * string. 653199482Srdivacky */ 654199482SrdivackyCINDEX_LINKAGE CXCompletionString 655199482Srdivackyclang_getCompletionChunkCompletionString(CXCompletionString completion_string, 656199482Srdivacky unsigned chunk_number); 657199482Srdivacky 658199482Srdivacky/** 659199482Srdivacky * \brief Retrieve the number of chunks in the given code-completion string. 660199482Srdivacky */ 661199482SrdivackyCINDEX_LINKAGE unsigned 662199482Srdivackyclang_getNumCompletionChunks(CXCompletionString completion_string); 663199482Srdivacky 664199482Srdivacky/** 665201361Srdivacky * \brief Contains the results of code-completion. 666201361Srdivacky * 667201361Srdivacky * This data structure contains the results of code completion, as 668201361Srdivacky * produced by \c clang_codeComplete. Its contents must be freed by 669201361Srdivacky * \c clang_disposeCodeCompleteResults. 670201361Srdivacky */ 671201361Srdivackytypedef struct { 672201361Srdivacky /** 673201361Srdivacky * \brief The code-completion results. 674201361Srdivacky */ 675201361Srdivacky CXCompletionResult *Results; 676201361Srdivacky 677201361Srdivacky /** 678201361Srdivacky * \brief The number of code-completion results stored in the 679201361Srdivacky * \c Results array. 680201361Srdivacky */ 681201361Srdivacky unsigned NumResults; 682201361Srdivacky} CXCodeCompleteResults; 683201361Srdivacky 684201361Srdivacky/** 685199482Srdivacky * \brief Perform code completion at a given location in a source file. 686199482Srdivacky * 687199482Srdivacky * This function performs code completion at a particular file, line, and 688199482Srdivacky * column within source code, providing results that suggest potential 689199482Srdivacky * code snippets based on the context of the completion. The basic model 690199482Srdivacky * for code completion is that Clang will parse a complete source file, 691199482Srdivacky * performing syntax checking up to the location where code-completion has 692199482Srdivacky * been requested. At that point, a special code-completion token is passed 693199482Srdivacky * to the parser, which recognizes this token and determines, based on the 694199482Srdivacky * current location in the C/Objective-C/C++ grammar and the state of 695199482Srdivacky * semantic analysis, what completions to provide. These completions are 696201361Srdivacky * returned via a new \c CXCodeCompleteResults structure. 697199482Srdivacky * 698199482Srdivacky * Code completion itself is meant to be triggered by the client when the 699199482Srdivacky * user types punctuation characters or whitespace, at which point the 700199482Srdivacky * code-completion location will coincide with the cursor. For example, if \c p 701199482Srdivacky * is a pointer, code-completion might be triggered after the "-" and then 702199482Srdivacky * after the ">" in \c p->. When the code-completion location is afer the ">", 703199482Srdivacky * the completion results will provide, e.g., the members of the struct that 704199482Srdivacky * "p" points to. The client is responsible for placing the cursor at the 705199482Srdivacky * beginning of the token currently being typed, then filtering the results 706199482Srdivacky * based on the contents of the token. For example, when code-completing for 707199482Srdivacky * the expression \c p->get, the client should provide the location just after 708199482Srdivacky * the ">" (e.g., pointing at the "g") to this code-completion hook. Then, the 709199482Srdivacky * client can filter the results based on the current token text ("get"), only 710199482Srdivacky * showing those results that start with "get". The intent of this interface 711201361Srdivacky * is to separate the relatively high-latency acquisition of code-completion 712199482Srdivacky * results from the filtering of results on a per-character basis, which must 713199482Srdivacky * have a lower latency. 714199482Srdivacky * 715199482Srdivacky * \param CIdx the \c CXIndex instance that will be used to perform code 716199482Srdivacky * completion. 717199482Srdivacky * 718200583Srdivacky * \param source_filename the name of the source file that should be parsed to 719200583Srdivacky * perform code-completion. This source file must be the same as or include the 720200583Srdivacky * filename described by \p complete_filename, or no code-completion results 721200583Srdivacky * will be produced. NOTE: One can also specify NULL for this argument if the 722200583Srdivacky * source file is included in command_line_args. 723199482Srdivacky * 724199482Srdivacky * \param num_command_line_args the number of command-line arguments stored in 725199482Srdivacky * \p command_line_args. 726199482Srdivacky * 727199482Srdivacky * \param command_line_args the command-line arguments to pass to the Clang 728199482Srdivacky * compiler to build the given source file. This should include all of the 729199482Srdivacky * necessary include paths, language-dialect switches, precompiled header 730199482Srdivacky * includes, etc., but should not include any information specific to 731199482Srdivacky * code completion. 732199482Srdivacky * 733200583Srdivacky * \param num_unsaved_files the number of unsaved file entries in \p 734200583Srdivacky * unsaved_files. 735200583Srdivacky * 736200583Srdivacky * \param unsaved_files the files that have not yet been saved to disk 737200583Srdivacky * but may be required for code completion, including the contents of 738200583Srdivacky * those files. 739200583Srdivacky * 740199482Srdivacky * \param complete_filename the name of the source file where code completion 741199482Srdivacky * should be performed. In many cases, this name will be the same as the 742199482Srdivacky * source filename. However, the completion filename may also be a file 743199482Srdivacky * included by the source file, which is required when producing 744199482Srdivacky * code-completion results for a header. 745199482Srdivacky * 746199482Srdivacky * \param complete_line the line at which code-completion should occur. 747199482Srdivacky * 748199482Srdivacky * \param complete_column the column at which code-completion should occur. 749199482Srdivacky * Note that the column should point just after the syntactic construct that 750199482Srdivacky * initiated code completion, and not in the middle of a lexical token. 751199482Srdivacky * 752201361Srdivacky * \returns if successful, a new CXCodeCompleteResults structure 753201361Srdivacky * containing code-completion results, which should eventually be 754201361Srdivacky * freed with \c clang_disposeCodeCompleteResults(). If code 755201361Srdivacky * completion fails, returns NULL. 756199482Srdivacky */ 757201361SrdivackyCINDEX_LINKAGE 758201361SrdivackyCXCodeCompleteResults *clang_codeComplete(CXIndex CIdx, 759201361Srdivacky const char *source_filename, 760201361Srdivacky int num_command_line_args, 761201361Srdivacky const char **command_line_args, 762201361Srdivacky unsigned num_unsaved_files, 763201361Srdivacky struct CXUnsavedFile *unsaved_files, 764201361Srdivacky const char *complete_filename, 765201361Srdivacky unsigned complete_line, 766201361Srdivacky unsigned complete_column); 767199482Srdivacky 768201361Srdivacky/** 769201361Srdivacky * \brief Free the given set of code-completion results. 770201361Srdivacky */ 771201361SrdivackyCINDEX_LINKAGE 772201361Srdivackyvoid clang_disposeCodeCompleteResults(CXCodeCompleteResults *Results); 773201361Srdivacky 774198092Srdivacky#ifdef __cplusplus 775198092Srdivacky} 776198092Srdivacky#endif 777198092Srdivacky#endif 778198092Srdivacky 779